2 Commits

Include renames

Author	SHA1	Message	Date
4 people	bddf2cba1e	release(v0.5.1): hotfix — quota probe cache/backoff/schema-drift correctness (codex review) (#58) ... * release(v0.5.1): hotfix — quota probe cache/backoff/schema-drift correctness (codex review) Addresses three production-quality findings from codex's post-v0.5.0 review (codex review on PR #57, reproduced with local mocks): F1 [P1] — Doctor bypass of cache + backoff (ADR 0013 Rule 3) `anthropic.quota_probe_reachable` called `_probeOnce(auth)` directly, bypassing `quotaProbeState.backoffUntil`. Successive `olp doctor` invocations within a backoff window each hit upstream — violating ADR 0013 Rule 3 (backoff is mandatory for ALL consumers). Fix: doctor now routes through `quotaStatus()`. ADR 0013 Rule 3 clarified: "All consumers of `quotaStatus()`, including `olp doctor` checks, MUST route through `quotaStatus()` and MUST NOT call `_probeOnce()` directly." F2 [P2] — 200 with empty ratelimit headers cached as live data (ADR 0013 Rule 5) A 200 OK with zero `anthropic-ratelimit-*` headers was cached as `stale: false` (live). Minimum-viable-schema gate added to `_probeOnce`: requires 5h-utilization + 5h-reset + 7d-utilization + 7d-reset present; absence → `failureKind: 'schema_drift'`, backoff scheduled, result NOT cached. ADR 0013 Rule 5 updated with the gate specification. F3 [P2] — Dashboard-data loses failure detail (ADR 0013 Rule 6) `aggregateProviderQuota()` collapsed all failure modes into `status: 'unavailable'` ("no public quota api or probe disabled") — same as providers with no API at all. Fix: `quotaStatus()` v0.5.1 contract — `null` ONLY for opt-in-off; failures return `{ probe_status: 'unreachable', failure: { kind, message, backoff_until? } }`. New `failure_kind` enum: no_credentials | auth_failed | rate_limited | schema_drift | network | other. Dashboard renders `unreachable` with red border + failure detail. Authority: ADR 0013 Rules 3, 5, 6 (cache + backoff + schema-drift + failure transparency) ADR 0008 Amendment 2 (richer quota_v2 shape; new unreachable status) ADR 0002 Amendment 8 unchanged (constitutional permission for the probe) Codex review findings F1–F3 (codex on PR #57) Changes: - lib/providers/anthropic.mjs: quotaProbeState gains lastError + failureKind; _probeOnce: min-field gate + failureKind population; quotaStatus(): v0.5.1 contract (null=disabled only; probe_status:live/stale/unreachable); doctorChecks routes through quotaStatus(); reset functions updated - lib/audit-query.mjs: _normalizeAnthropicQuota handles probe_status field; aggregateProviderQuota emits failure/failure_kind/backoff_until; unreachable status - dashboard.html: unreachable CSS classes + render path + footer v0.5.1 - test-features.mjs: 38f/j/l updated for v0.5.1 shape; 38r refactored for F1; 38g/k gain probe_status assertions; 38u/v/w new regression tests; 756→759 tests - docs/adr/0008: Amendment 2 (richer ProviderQuotaEntry + quotaStatus contract) - docs/adr/0013: Rule 3 clarification (doctor must use quotaStatus); Rule 5 min-viable-schema gate specification - package.json: 0.5.0 → 0.5.1 - CHANGELOG.md: v0.5.1 hotfix entry promoted from Unreleased - README.md / AGENTS.md: Phase 5 closed at v0.5.1; Phase 6 next Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs+code: PR #58 fold-in — reviewer Nits #1 + #2 (ADR doc-drift + opt_in_off enum) Fresh-context reviewer (PR #58) verdict: APPROVE_WITH_MINOR, 0 blocking, 4 nits. Folding in #1 + #2 (both 1-line cosmetic-but-correct fixes). Deferring #3 (test-only edge case in module-level seam restore) and #4 (pre-existing codex F4 — bin/olp.mjs + olp-plugin still read legacy quota shape; separate PR planned). Nit #1 — ADR 0002 Amendment 8 documentation drift. Amendment 8 at v0.5.0 line 20 said "the function returns `null` rather than throwing", and line 33 said "stale-cache-on-failure (`null` is returned only when no cache entry exists; if a stale entry exists it's returned with a `stale: true` marker)". v0.5.1 refined this contract: `null` is now reserved STRICTLY for opt-in-off, and all failure modes return `{ probe_status: 'unreachable' | 'stale', failure: {...} }`. The substantive idempotent-failure constraint (no throw to caller) is unchanged. The operational description in Amendment 8 was stale — fixed to cross-reference ADR 0008 Amendment 2 + ADR 0013 Rule 6 for the v0.5.1 contract refinement. Also references Suite 38 (38u/38v/38w) as the regression coverage producing the new shape. Nit #2 — `failureKind: 'opt_in_off'` declared but never produced. The enum value was listed in both the code comment (anthropic.mjs:250) and ADR 0008 Amendment 2 (line 30) but never actually assigned — because when opt-in is off, `quotaStatus()` returns the literal `null` BEFORE any state mutation happens. The enum value was dead. Fix: removed `opt_in_off` from both enum declarations + added an inline note explaining that consumers (audit-query, doctor) distinguish opt-in-off by checking `quotaStatus() === null`, not via failureKind. Deferred: - Nit #3 (test-seam restore edge case): if a caller pre-sets `_quotaAuthReadFnForTest` AND passes a non-default `_authReadFn`, the finally block restores to null clobbering pre-set value. Test-only impact, no production risk. Pure hygiene; defer. - Nit #4 (codex F4): bin/olp.mjs cmdUsage and olp-plugin/index.js still read legacy `body.quota` field, never consume `quota_v2`. Reviewer confirmed neither crashes — both gracefully fall through to "no quota api" branch. Out of scope for this hotfix per the hotfix dispatch contract; separate PR will migrate them. Tests: 759/759 still pass post-fold-in. No test changes needed. Authority: PR #58 review thread + ADR 0013 Rule 6 (failure transparency) + ADR 0008 Amendment 2 (ProviderQuotaEntry v0.5.1 shape). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-27 09:33:47 +10:00
4 people	1605400052	docs: D79 — Phase 5 constitutional layer (ADR 0012 + ADR 0002 Amendment 8 + ADR 0013) (#50) ... * docs: D79 — Phase 5 constitutional layer (ADR 0012 + ADR 0002 Amendment 8 + ADR 0013) Three coupled governance documents land together as the Phase 5 constitutional layer (Iron Rule 11 IDR — reviewing them separately cannot verify consumer-producer alignment). Phase 5 opens 2026-05-26; D79 is governance-only, no code changes. - ADR 0012 (Phase 5 charter) — port OCP's plan-usage probe to `lib/providers/anthropic.mjs:quotaStatus()` (D80) + extend `/v0/management/dashboard-data` for new shape (D81) + Claude.ai-style dashboard restructure with 1-min auto-refresh + manual refresh (D82) + Suite 38/39 tests (D83) + optional mistral probe at D84 (codex skipped — no public API) + v0.5.0 close (maintainer-triggered). ~6 D-days. - ADR 0002 Amendment 8 (direct-API READ-ONLY exemption) — plugin contract amendment permitting quotaStatus() to call provider HTTP APIs directly, subject to three constraints: READ-ONLY (no mutating calls), subscription-scope (reuses spawn-path credentials), idempotent failure (returns null on any error, never throws). No other contract method gains this permission. - ADR 0013 (OAuth READ-ONLY consumption + schema-drift mitigation) — implementation discipline for ADR 0002 Amendment 8. Seven rules: (1) credential reuse via plugin's readAuthArtifact(), (2) READ-ONLY at wire (max_tokens:1, headers-only parse, body discarded), (3) cache TTL 5min + 60s-3600s exponential refresh backoff + stale-cache-on-failure, (4) opt-in via `~/.olp/config.json providers.<name>.quota_probe_enabled` (default false), (5) schema-drift mitigation via dual-path verification (compiled-binary `strings` + live API probe diff), (6) failure transparency through `olp doctor` + dashboard staleness markers, (7) explicit out-of-scope clarifications. Pre-flight institutional-knowledge audit (Iron Rule 12 prior-art search) captured at `~/.cc-rules/memory/learnings/anthropic_plan_usage_probe_schema_2026_05_26.md` (cross-machine git-sync). Findings: - OCP probe (server.mjs:842-1109) still works against current api.anthropic.com — tested live from PI231 OAuth credentials 2026-05-26. - 13 `anthropic-ratelimit-unified-*` response headers confirmed (3 new since OCP 2026-04 capture: 5h-status, 7d-status, overage-reset; no removals or renames). - Claude Code v2.1.x is now distributed as compiled native binary (Mach-O on macOS, ELF on Linux) — OCP's "grep cli.js" verification is no longer applicable. ADR 0013 Rule 5 replaces with dual-path verification (`strings` over the binary + live API probe diff). - OAuth refresh path (platform.claude.com/v1/oauth/token + client_id 9d1c250a-...) all unchanged. Authority: - ALIGNMENT.md Rule 1 (citation): audit memory + OCP server.mjs:842-1109 + live `/v1/messages` probe transcript 2026-05-26. - ALIGNMENT.md Rule 2 (provider-CLI-as-authority): Amendment 8 documents the exemption; the probe mirrors observed CLI behaviour. - ALIGNMENT.md Rule 5 (CI alignment.yml): not triggered (docs/ excluded by workflow `paths:` filter); blacklisted `/api/oauth/usage` token referenced only as meta-references ("must continue to blacklist"). - CLAUDE.md release_kit overlay: Phase 5 open; D-day commits stay under "Unreleased" until maintainer-triggered v0.5.0 close. Iron Rule 10: fresh-context reviewer required before merge per CLAUDE.md hard requirement #3. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs: D79 fold-in — 6 in-PR nits from fresh-context reviewer (PR #50) Reviewer verdict: APPROVE_WITH_MINOR (0 blocking, 9 nits — 6 in-PR, 3 outside-PR). Folding in the 6 in-PR nits here; the 3 outside-PR ones (audit-memory chronology, audit-memory D80/D81 mapping, ALIGNMENT.md cross-ref to Amendment 8) are deferred. Folded-in nits: 1. ADR 0002 Amendment 8: added a 5th "does NOT permit" bullet making per-endpoint containment explicit. Amendment 8 permits the kind of call; ADR 0013 Rule 2 enumerates which specific endpoint. Re-opening per-endpoint scope requires an ADR 0013 amendment, not a Amendment-8-only interpretation. 2. ADR 0013 Rule 5: added "Path A prerequisites" paragraph documenting that strings (GNU/BSD binutils/coreutils) + Claude Code v2.1.x install are required for compiled-binary verification. Windows reviewers need WSL or binutils-mingw. 3. ADR 0013 Rule 5: added "Trigger for re-running the diff" paragraph naming three explicit hooks for major-version-bump detection: Annual Alignment Audit (14 May), olp doctor anthropic.quota_probe_reachable failure, manual maintainer attention. Documented graceful-degradation failure mode. 4. ADR 0012 D80 estimate: 1.5d → 2d. Reviewer flagged 1.5d as optimistic compared to D61-D63 (2.5d for narrower SSE heartbeat scope). Aligning. 5. ADR 0012 D84: moved Mistral GO/NO-GO spike to D79 close (before D80 starts), not mid-phase. Reduces mid-phase scope drift risk. Outcome will be amended into this charter as a D79-close amendment. 6. ADR 0012 Authority + cross-references: replaced "Claude Code <version> § OAuth bearer + ratelimit headers" with "compiled-binary strings evidence per audit memory § Path A". Claude Code v2.1.x has no traditional section structure because it is a Mach-O / ELF compiled binary. Deferred (outside-PR) nits documented in PR review thread: - Audit memory historical-table chronology error (cb6c2a8 placed last; was second chronologically — narrative arc still holds, dates need correction). - Audit memory D80/D81 mapping mismatch (memory says D81 adds new fields; ADR 0012 says D80 parses all 13). - ALIGNMENT.md cross-reference to Amendment 8 (Class-specific Exceptions subsection should name Amendment 8 explicitly). All three outside-PR items are docs-only and not load-bearing for D80 implementation. Will fold in either at D80 commit (audit-memory updates) or as a tiny constitutional cleanup PR (ALIGNMENT.md cross-ref). Iron Rule 10: reviewer was a fresh-context opus subagent; their full review is recorded in PR #50 thread. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-26 16:30:09 +10:00