Slice A (reuse program #150): reset-aware quota state + Z.ai reset plausibility #151

New issue

Closed

opened 2026-09-28 00:12:59 +00:00 by kilo · 0 comments

kilo commented

2026-09-28 00:12:59 +00:00

Member

Child of #150 (reuse-first reconstruction program). Slice A: quota correctness and reset mechanics.

Problem

State layer (resource_state.py): freshness is TTL-only. classify_freshness compares observation age against freshness_ttl_seconds; refresh_due/_entry_refresh_due compare age against poll_interval_seconds. A window's normalized resets_at is carried as explanation data but never consumed: an observation taken one minute before a five-hour window reset stays fresh for its whole TTL even after the reset moment passes, and a 0%-exhausted window pins its scarcity as unavailable until the next poll even when its reset time is already in the past. Stale quota facts can therefore outlive the window they describe.
Parser (providers/zai.py): nextResetTime is validated only as a 13-digit epoch-ms band. A five-hour window whose reset claims to be days away (timezone-shifted or drifted provider value) is accepted verbatim; the evidenced five-hour duration is never cross-checked against the claimed reset.

Change (state mechanics only — no ranking-policy change)

Reset-crossed observations are stale: classify_freshness gains an optional earliest-window-reset input; when the evaluation instant has reached any observed window's resets_at, the observation is stale regardless of TTL age. refresh_due (registry + entry) additionally report a reset-crossed observation as due even when younger than the poll interval. Exhausted (0%) windows are covered by the same rule: after reset crossing they stop pinning scarcity via obsolete facts. The FRESHNESS_STATES vocabulary is unchanged (stale is an existing value); observation classes, health statuses and serialized contracts are unchanged.
Z.ai reset plausibility: for windows with an evidenced duration (five-hour, weekly), a nextResetTime more than duration + 60s ahead of the retrieval instant is implausible: resets_at is omitted and the existing reset_unknown window diagnostic is emitted (no new diagnostic vocabulary). Resets at or before the retrieval instant are preserved as-is; obsolescence is the state layer's reset-crossing rule.

Frozen semantics untouched

D-026 penalty (no reset-proximity term), D-037 role blend, capacity v3 vocabularies, _DIAGNOSTIC_CODES, health statuses, reason codes. The change only makes staleness truthful; scoring inputs are unchanged.

Required regressions (new tests)

classify_freshness: reset crossed → stale despite age < TTL; reset in future → fresh; reset exactly at now → stale; no resets → TTL-only behavior unchanged; malformed reset rejected.
registry_snapshot: entry freshness reflects a crossed reset; multi-window observation (weekly future + five-hour crossed) → stale.
refresh_due (both forms): reset-crossed observation is due despite young poll interval; no polling cadence → never due even when reset crossed (freshness still evaluates stale).
Exhaustion case: 0% window whose reset passed → observation stale (no longer treated as trustworthy capacity).
Worker-report path: apply_worker_report then evaluated read shows the reset-crossing rule.
Z.ai parser: five-hour reset > 5h+60s ahead → omitted + reset_unknown; boundary at exactly 5h+60s → kept; weekly window bounded by 7d+60s; unknown-kind window (no evidenced duration) → no plausibility check; normal near-future reset kept; past reset kept (state layer owns obsolescence).

Scope

scarcity_router/resource_state.py, scarcity_router/providers/zai.py, focused doc updates (docs/capacity-model.md freshness prose; providers/zai.py module docstring; Codex evidence re-pin note per #150), tests in tests/test_resource_state.py + tests/test_zai_parser.py. No selector/policy/contract changes.

Evidence / complexity boundary

Upstream evidence: weave-os/router usage package @ e5133a6 (Apache-2.0) — ExhaustedAsOf reset semantics and TestObserver_ResetAtExpiresBeforeWindowLength invariant, PORTed as state mechanics with its test invariants reused as specifications; CodexBar zai.js @ 491ae68 (MIT) — five-hour reset plausibility pattern ("a five-hour Coding Plan reset cannot be ten hours away; never guess a timezone correction"). Attribution via this issue; no source vendored, no NOTICE change required (no code copied).

Budget: 120 min wall clock. Full gate before PR; PR targets develop, left open for human review.

Security classification

Not security-critical (no credentials, transport, or execution-surface changes). Independent exact-head review mandatory; UX impact assessment mandatory.

Child of #150 (reuse-first reconstruction program). Slice A: quota correctness and reset mechanics. ## Problem 1. **State layer (`resource_state.py`):** freshness is TTL-only. `classify_freshness` compares observation age against `freshness_ttl_seconds`; `refresh_due`/`_entry_refresh_due` compare age against `poll_interval_seconds`. A window's normalized `resets_at` is carried as explanation data but never consumed: an observation taken one minute before a five-hour window reset stays `fresh` for its whole TTL even after the reset moment passes, and a 0%-exhausted window pins its scarcity as `unavailable` until the next poll even when its reset time is already in the past. Stale quota facts can therefore outlive the window they describe. 2. **Parser (`providers/zai.py`):** `nextResetTime` is validated only as a 13-digit epoch-ms band. A five-hour window whose reset claims to be days away (timezone-shifted or drifted provider value) is accepted verbatim; the evidenced five-hour duration is never cross-checked against the claimed reset. ## Change (state mechanics only — no ranking-policy change) 1. **Reset-crossed observations are stale:** `classify_freshness` gains an optional earliest-window-reset input; when the evaluation instant has reached any observed window's `resets_at`, the observation is `stale` regardless of TTL age. `refresh_due` (registry + entry) additionally report a reset-crossed observation as due even when younger than the poll interval. Exhausted (0%) windows are covered by the same rule: after reset crossing they stop pinning scarcity via obsolete facts. The `FRESHNESS_STATES` vocabulary is unchanged (`stale` is an existing value); observation classes, health statuses and serialized contracts are unchanged. 2. **Z.ai reset plausibility:** for windows with an evidenced duration (five-hour, weekly), a `nextResetTime` more than duration + 60s ahead of the retrieval instant is implausible: `resets_at` is omitted and the existing `reset_unknown` window diagnostic is emitted (no new diagnostic vocabulary). Resets at or before the retrieval instant are preserved as-is; obsolescence is the state layer's reset-crossing rule. ## Frozen semantics untouched D-026 penalty (no reset-proximity term), D-037 role blend, capacity v3 vocabularies, `_DIAGNOSTIC_CODES`, health statuses, reason codes. The change only makes staleness truthful; scoring inputs are unchanged. ## Required regressions (new tests) 1. `classify_freshness`: reset crossed → `stale` despite age < TTL; reset in future → `fresh`; reset exactly at `now` → `stale`; no resets → TTL-only behavior unchanged; malformed reset rejected. 2. `registry_snapshot`: entry freshness reflects a crossed reset; multi-window observation (weekly future + five-hour crossed) → `stale`. 3. `refresh_due` (both forms): reset-crossed observation is due despite young poll interval; no polling cadence → never due even when reset crossed (freshness still evaluates `stale`). 4. Exhaustion case: 0% window whose reset passed → observation `stale` (no longer treated as trustworthy capacity). 5. Worker-report path: `apply_worker_report` then evaluated read shows the reset-crossing rule. 6. Z.ai parser: five-hour reset > 5h+60s ahead → omitted + `reset_unknown`; boundary at exactly 5h+60s → kept; weekly window bounded by 7d+60s; unknown-kind window (no evidenced duration) → no plausibility check; normal near-future reset kept; past reset kept (state layer owns obsolescence). ## Scope `scarcity_router/resource_state.py`, `scarcity_router/providers/zai.py`, focused doc updates (`docs/capacity-model.md` freshness prose; `providers/zai.py` module docstring; Codex evidence re-pin note per #150), tests in `tests/test_resource_state.py` + `tests/test_zai_parser.py`. No selector/policy/contract changes. ## Evidence / complexity boundary Upstream evidence: weave-os/router `usage` package @ `e5133a6` (Apache-2.0) — `ExhaustedAsOf` reset semantics and `TestObserver_ResetAtExpiresBeforeWindowLength` invariant, PORTed as state mechanics with its test invariants reused as specifications; CodexBar `zai.js` @ `491ae68` (MIT) — five-hour reset plausibility pattern ("a five-hour Coding Plan reset cannot be ten hours away; never guess a timezone correction"). Attribution via this issue; no source vendored, no NOTICE change required (no code copied). Budget: 120 min wall clock. Full gate before PR; PR targets `develop`, left open for human review. ## Security classification Not security-critical (no credentials, transport, or execution-surface changes). Independent exact-head review mandatory; UX impact assessment mandatory.