M1: Implement Z.ai quota response parser #6

New issue

Closed

opened 2026-09-03 12:48:22 +00:00 by creatidy · 0 comments

creatidy commented

2026-09-03 12:48:22 +00:00

(Migrated from github.com)

Implement the first provider-edge parser: Z.ai Coding Plan quota response → normalized capacity contract v1.

Scope (strictly pure parsing + normalization):

Input: an already decoded JSON/Python-compatible payload plus an explicit caller-supplied retrieval timestamp.
Output: a validated v1 CapacitySnapshot (provider=zai, source=zai_usage_endpoint).
Zero I/O: no clock, filesystem, environment or network access; deterministic.

Behavior:

Validate the evidenced envelope (code/msg/success/data.level/data.limits[]) deliberately; structurally incompatible successful responses map to schema_changed with no partial decoding.
Validated token-window mappings: TOKENS_LIMIT (unit=3, number=5) → five_hour tokens (18000s); TOKENS_LIMIT (unit=6, number=1) → weekly tokens (604800s). Never by array position.
TIME_LIMIT → resource=time, kind=unknown (no inferred period).
Unknown (unit, number) / missing unit/number → kind=unknown, window preserved with a deterministic safe window_id, no invented duration.
percentage is used-oriented (evidenced): valid int 0..100 → used_percent + remaining_percent=100-used; otherwise omit the pair and emit percentage_unknown. Missing ≠ zero.
nextResetTime is epoch milliseconds → canonical UTC YYYY-MM-DDTHH:MM:SS.sssZ; unusable values omit resets_at and emit reset_unknown.
Plan from data.level only when it already satisfies the v1 safe-ID grammar; otherwise omitted.
401 → auth_required with no synthesized windows; provider error text never enters normalized output.

Constraints:

No fixtures rewritten; all six Z.ai fixtures exercised by parser tests.
Standard library only; no new dependencies; U-008 untouched.
basedpyright recommended gate must stay 0 errors / 0 warnings / 0 notes via make check.
No live acquisition, credentials, Kilo auth access, retries, redirects or any network code — that is explicitly out of scope.

One issue → one branch → one PR → human review.

Implement the first provider-edge parser: Z.ai Coding Plan quota response → normalized capacity contract v1. Scope (strictly pure parsing + normalization): - Input: an already decoded JSON/Python-compatible payload plus an explicit caller-supplied retrieval timestamp. - Output: a validated v1 `CapacitySnapshot` (`provider=zai`, `source=zai_usage_endpoint`). - Zero I/O: no clock, filesystem, environment or network access; deterministic. Behavior: - Validate the evidenced envelope (`code`/`msg`/`success`/`data.level`/`data.limits[]`) deliberately; structurally incompatible successful responses map to `schema_changed` with no partial decoding. - Validated token-window mappings: `TOKENS_LIMIT (unit=3, number=5)` → five_hour tokens (18000s); `TOKENS_LIMIT (unit=6, number=1)` → weekly tokens (604800s). Never by array position. - `TIME_LIMIT` → `resource=time`, `kind=unknown` (no inferred period). - Unknown `(unit, number)` / missing `unit`/`number` → `kind=unknown`, window preserved with a deterministic safe `window_id`, no invented duration. - `percentage` is used-oriented (evidenced): valid int 0..100 → `used_percent` + `remaining_percent=100-used`; otherwise omit the pair and emit `percentage_unknown`. Missing ≠ zero. - `nextResetTime` is epoch milliseconds → canonical UTC `YYYY-MM-DDTHH:MM:SS.sssZ`; unusable values omit `resets_at` and emit `reset_unknown`. - Plan from `data.level` only when it already satisfies the v1 safe-ID grammar; otherwise omitted. - 401 → `auth_required` with no synthesized windows; provider error text never enters normalized output. Constraints: - No fixtures rewritten; all six Z.ai fixtures exercised by parser tests. - Standard library only; no new dependencies; U-008 untouched. - basedpyright `recommended` gate must stay 0 errors / 0 warnings / 0 notes via `make check`. - No live acquisition, credentials, Kilo auth access, retries, redirects or any network code — that is explicitly out of scope. One issue → one branch → one PR → human review.