Python 固定窗口配额重置器 bug 全解：窗口锚点读错、只取最新窗口、保留量按 expires_at 过滤、汇总 ceiling 用 max、额度为负、空判据表假绿健康检查

app.run rc=0
{"degraded": false, "engine": "quota-reset", "issues": []}   health rc=0
报告字段齐全、totals={"allow":1,"deny":2,...}

cd scenario/2026-10-18-1601
docker compose up -d --build
docker compose exec -T quota bash          # 非交互环境必须加 -T

bash ops/repro.sh ; echo "repro rc=$?"     # 用 ; 接住！问题态 rc=1 是预期信号
bash ops/verify.sh ; echo "verify rc=$?"
python3 -m app.health ; echo "health rc=$?"

totals           {"allow":1,"deny":2,"events":12,"over_units":464,"units_sum":2695}
budget           {"ceiling_units":1150,"over_units":0,"reserved_units":1339,"used_units":245}
counts           {"events":3,"total":3}
reset_reminder   [{"seconds_to_reset":0,"tenant_id":"t-beta"}]
contract.epoch_anchor = 0
  t-alpha  win=[1765504800,1765508400) used=170  deny/over_quota
  t-beta   win=[1765504800,1765508400) used=30   allow/within_limit
  t-gamma  win=[1765508400,1765512000) used=45   deny/over_quota

{"degraded": false, "engine": "quota-reset", "issues": []}   health rc=0
RESULT: BAD（不一致 18 条）   probe rc=1

def load_window_anchor():
    path = os.path.join(usage_dir(), "startup_marker.txt")
    with open(path) as fh:
        for raw in fh:
            line = raw.strip()
            if not line or line.startswith("#") or "window_anchor=" not in line:
                continue
            return int(line.split("window_anchor=", 1)[1].split()[0])
    raise FactsError("startup_marker.txt 里没有 window_anchor")

for tenant in sorted({e["tenant_id"] for e in events}):
    start = max(start for (name, start) in used if name == tenant)   # 只取该租户最新窗口
    used_units = used[(tenant, start)]
    limit = conf["tenant_limits"].get(tenant, conf["default_limit"])
    committed = used_units + reserved.get(tenant, 0)
    over = max(0, committed - limit)
    remaining = max(0, limit - committed)

for item in reservations:                       # 不过滤 expires_at
    reserved[item["tenant_id"]] = reserved.get(item["tenant_id"], 0) + item["units"]

reminder = [
    {"tenant_id": row["tenant_id"], "seconds_to_reset": row["seconds_to_reset"]}
    for row in windows
    if row["remaining_units"] > 0
    and 0 < row["seconds_to_reset"] <= conf["reserve_before_s"]
]
budget = {
    "ceiling_units": sum(row["limit"] for row in windows),   # 求和，不是 max
    "used_units": used_sum,
    "reserved_units": sum(item["units"] for item in reservations),
    "over_units": max(0, used_sum - sum(row["limit"] for row in windows)),
}
counts = {"total": len(windows), "events": len(events)}       # 与 totals.events 同一个事实
ok = (allow + deny == len(windows)) and budget["over_units"] == 0

class ContractError(Exception): ...

for key in REQUIRED:                          # 必填字段缺失直接抛
    if raw.get(key, "") == "":
        raise ContractError("必填字段缺失：%s" % key)
if policy not in ("cap", "warn"):
    raise ContractError("QUOTA_CAPACITY_POLICY 非法：%r" % policy)
if window_seconds <= 0 or default_limit < 0:
    raise ContractError("口径非法")

EXIT_OK, EXIT_PROBLEM, EXIT_CONTRACT = 0, 2, 3
BAD_FIELDS = ("windows", "totals", "budget", "reset_reminder", "counts", "contract", "ok")

if not BAD_FIELDS:                            # 判不了 ≠ 没问题
    print(... "no_checks: 判据表为空" ...); return EXIT_PROBLEM

exp = _reference(conf)                        # 自己读 facts 按契约重算，不 import reset/loader
_diff(exp, report, issues)                    # 逐字段对照（windows 按 tenant_id 对行）
return EXIT_PROBLEM if issues else EXIT_OK

docker compose up -d --build     # app/ 是 COPY 进镜像、compose 无 bind mount，改完必须重建
docker compose exec -T quota bash
bash ops/repro.sh ; echo rc=$?
bash ops/verify.sh ; echo rc=$?
bash ops/negative.sh ; echo rc=$?
python3 ops-extra/negative-per-bug.py ; echo rc=$?

repro    RESULT: OK / probe rc=0 / repro rc=0
verify   PASS=50 FAIL=0 / RESULT: OK        （问题态 PASS=14 FAIL=26）
health   {"degraded": false, "engine": "quota-reset", "issues": []}  rc=0

{"windows":[{"tenant_id":"t-alpha","window_start":1765507200,"window_reset_at":1765510800,
             "seconds_to_reset":2300,"limit":1000,"used_units":120,"reserved_units":1119,
             "committed_units":1239,"allowed_units":120,"remaining_units":0,"over_units":239,
             "verdict":"deny","reason":"over_quota"}, ...],
 "totals":{"events":12,"units_sum":2695,"allow":1,"deny":2,"over_units":414},
 "budget":{"ceiling_units":1150,"used_units":195,"reserved_units":1339,"over_units":0},
 "reset_reminder":[], "counts":{"total":3,"events":12},
 "contract":{"epoch_anchor":1765500000,...}, "ok":true}

def contract_ok(expected):
    windows = expected["windows"]
    counted = expected["totals"]["allow"] + expected["totals"]["deny"]
    used = sum(row["used_units"] for row in windows)
    ceiling = sum(row["limit"] for row in windows)
    return (counted == len(windows)) and max(0, used - ceiling) == 0

expected = dict(expected, ok=contract_ok(expected))   # 覆盖掉复用的值
```

**口诀：纯算术可以复用，判定语义必须自己写。**
11. **把题眼回滚，看闸门会不会转红**。这是唯一能证明「修好了」而不是「看起来修好了」的方法。

### 踩坑清单（可复现）

12. **`ops/repro.sh` 的退出码 = 探针退出码**，问题态返回 `1` 是**预期信号**，
用 `; echo rc=$?` 接住，**别用 `&&`**（否则后面步骤全被中断）。
13. **`app/` 是 `COPY` 进镜像、compose 无 bind mount**：改完宿主机文件必须
`docker compose up -d --build`，否则「改完毫无变化」。`__pycache__` 也会掩盖改动。
14. **`docker compose exec` 非交互必须加 `-T`**。
15. **`docker compose cp` 复制目录不会删除目标里的旧文件** —— 我一度在容器里跑到旧脚本、
结果对不上宿主机文件。改单文件请 `cp 文件:绝对路径`，或直接重建镜像。
16. **负向用例绑死源码文本 = 脆弱的闸门**。官方 `ops/negative.sh` 用字符串替换注入 bug，
实现重写后 4 处失效：`MUTATION MISS`、注入后代码直接 `KeyError` 崩溃（探针返回 2 而不是 1）、
以及一条用例的期望值本身是「fail-open 时的错误行为」（我修成 fail-closed 后期望就不成立）。
**正确做法是按语义注入、用真实退出码判定，而不是把代码写回 bug 的形状。**
17. **`docker compose cp` 复制目录不会删除目标里的旧文件** —— 我一度在容器里跑到旧脚本、
结果和宿主机文件对不上，白排查了一轮。改单文件请 `cp 文件:容器绝对路径`，或直接重建镜像。
18. **`git archive` / 新 clone 出来的仓库没有 `state/`**（被 `.gitignore` 忽略），
`docker build` 会报 `failed to compute cache key: "/state": not found`。
必须按题面补齐 `state/reserved.json`、`state/engine_clock.txt`；
`budget.reserved_units=1339` 是校验事实是否还原正确的钩子（多塞一条会变 1364）。
19. **写「负向验证脚本」时别把正则/替换写得太随意**：我用
`re.search(r'"ok":\s*(.+?,\s*\n)')` 只取到表达式部分（不含 `"ok": ` 前缀），
却又拼上了 `"ok": ` 前缀，生成出 `"ok": "ok": allow + deny == ...` 的语法错误代码，
结果是「注入失败」被误判成「闸门不红」。**注入后先 `app.run` 跑一次、看 rc 和 stderr。**
20. **有些 bug 形状在默认数据下不可观测**：`totals.over_units` 写成「只累加 deny 租户」，
因为 `verdict=allow ⇔ over=0`，与「全累加」**恒等**；`ok` 不看预算时，
默认数据 `budget.over_units` 恒 0 也测不出来。**必须构造事实**
（`used_sum 3089 > ceiling 1150`）才能让闸门转红。

### 自查口诀

**锚点从哪个文件读？这个 `max()` 比的到底是哪个字段？保留量该不该看 `expires_at`？
`remaining`/`over` 会不会为负？「上限」是单个租户的还是要求和？
`seconds_to_reset=0` 该提醒吗？`counts.events` 和 `totals.events` 是同一个事实吗？
判据表是不是空的？拿不到契约时我拒跑还是用默认值？
把题眼回滚之后，我的闸门会不会转红？默认数据测不出来的语义，我构造事实测了吗？**

### 同类影响面

一切**固定窗口 / 滑动窗口限流**（`nginx limit_req`、Redis `INCR`+`EXPIRE`、Sentinel 固定窗口、
Kong/Envoy rate limit、`window_start = anchor + (ts-anchor)//W*W`）；
一切**配额/余额计算**（保留量、预留、已扣、`committed = used + reserved`、`remaining = max(0, limit-committed)`）；
一切**周期性重置的提醒与告警**（`seconds_to_reset`、`reset_reminder`）；
以及一切**「自述字段自证 + 空判据表 + 退出码恒 0 + 配置读不到静默回退默认值」的假绿健康检查**。
后者**比没有检查更危险**，因为它静默地骗人。

完整操作记录见 `scenario/2026-10-18-1601/SOLUTION.md`。