# Changelog All notable changes to OLP land here. Per `CLAUDE.md` release_kit overlay, this file is the source of truth for GitHub release notes. ## Unreleased ### D54 β€” README Phase 3 polish (docs-only, no code change) Seventh Phase 3 D-day. Documentation polish ahead of Phase 3 close (D55, maintainer-triggered). Brings README status header / Implementation Status / API Endpoints / Known limitations / Phase plan up to date with Phase 3 work shipped to main through D48-D53. - **Status header**: `v0.2.0 shipped` β†’ `v0.2.0 shipped; v0.3.0 in progress` + lists D48-D54 highlights. - **Implementation status note**: Phase 3 description updated from "next milestone" to "shipped to main through D54; v0.3.0 release pending maintainer-triggered close (D55)". - **Implementation Status table** β€” 4 row updates: - `lib/audit.mjs`: 🟑 D45-only β†’ βœ… D45 append + D52 rotation; describes both responsibilities. - `lib/audit-query.mjs`: NEW row (D49 shipped, 5-function aggregate query API). - `dashboard.html`: πŸ“‹ Planned (Phase 6) β†’ βœ… Phase 3 shipped (D50 stub + D51 full UI); describes the 4 panels. - `bin/olp-audit-rotate.mjs`: NEW row (D52 shipped, external cron tool). - **API Endpoints table** β€” `/cache/stats`, `/v0/management/quota`, `/dashboard` (Phase 6 πŸ“‹ Planned β†’ Phase 3 βœ… Shipped); new `/v0/management/dashboard-data` row; `/health` row clarified to spell out owner-only-trim semantic. Removed the "placeholder β€” full table lands" stub since the table is now substantively complete. - **Known limitations** β€” Phase 2 paragraph kept (now reads as historical Phase 2 completion note); new Phase 3 paragraph summarizing D48-D54 shipped + D55 close pending. - **Phase plan** β€” Phase 3 description (was "next") β†’ "🟑 In progress β€” D48 (ADR) + D49–D54 shipped to main 2026-05-25; v0.3.0 close awaits maintainer trigger." Added Phase 4+ entry covering the deferred items (per-key per-provider auth, SQLite hybrid, audit rotation/retention policies, provider-cost weights). - **Test count:** 601 β†’ 601 (docs-only). - **Authority:** CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; ADR 0008 Β§ 13 sprint shape (D54 = "E2E + AGENTS / README polish"); standing autopilot grant. ### D53 β€” `tried_providers` schema semantic fix (D45 P2 deferral closed) Sixth Phase 3 D-day. Small focused fix for the D45 fresh-context opus reviewer P2 finding that was deferred: `auditCtx.tried_providers` on the `key_no_provider_access` 403 path was being stamped with the ORIGINAL chain (which was filtered out, never dispatched), distorting downstream audit queries like "which providers did key X actually call". - **`server.mjs` 403 path fix** (around L815): `auditCtx.tried_providers = []` (was `_originalChainProviders`). The configured-but-blocked chain still appears in the human-readable error message body β€” the audit just doesn't claim those providers were "tried" when the server's filter dispatched zero. - **ADR 0007 Β§ 8 amendment**: new paragraph spelling out the `tried_providers` semantic β€” "the list of providers the server actually dispatched a spawn against. A provider that was configured in the chain but filtered out by `providers_enabled` gating is NOT included β€” the key didn't try the provider, the gate did. On the 403 path `tried_providers` is the empty array." Plus a forward note that audit log rotation moved to Phase 3 / ADR 0008 Β§ 5. - **Suite 20h-extra-audit (+1 test β€” 600 β†’ 601):** creates a guest key with `providers_enabled: ['mistral']`; fires a request for an Anthropic-routed model; asserts 403 `key_no_provider_access`; reads the audit row from `audit.ndjson`; asserts `tried_providers === []`. This pins the D53 semantic against regression β€” if a future change reverts to stamping the original chain, the test fails. - **Documentation:** CHANGELOG D53 entry; ADR 0007 Β§ 8 amendment. - **Test count:** 600 β†’ 601 (+1 D53 regression test). - **Authority:** ADR 0007 Β§ 8 amendment (D53, 2026-05-25); D45 fresh-context opus reviewer P2 deferral note; CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; standing autopilot grant. ### D52 β€” Daily audit rotation (`lib/audit.mjs` extension + `bin/olp-audit-rotate.mjs`) Fifth Phase 3 D-day. Adds daily UTC-aware rotation to `lib/audit.mjs` per ADR 0008 Β§ 5 + ships an external cron tool. Rotation is **synchronous** at v0.3.0 (Lane 3 = B daily rotation; synchronous design eliminates the race that an async wrapper would create between date-change-detection and the append). - **`lib/audit.mjs` extended**: - New `_maybeRotateAudit({ olpHome, logEvent })` (synchronous): probes the live `audit.ndjson`; if it holds events from a past UTC date, renames it to `audit-YYYY-MM-DD.ndjson`. Idempotent. If the target file already exists (cron beat the in-server check), logs warn + skips per ADR 0008 Β§ 5.3 race safety. - `appendAuditEvent` extended: cheap fast-path date check via module-cached `_lastSeenUtcDate`. On date change, calls `_maybeRotateAudit` synchronously BEFORE `appendFileSync` β€” so old-date events land in the rotated file and new-date events land in the fresh live file. No event straddles the boundary. - Why synchronous instead of async: an async wrapper would let the sync `appendFileSync` race the not-yet-completed `renameSync`, landing today's event in the about-to-be-renamed file. Sync rotation is the only correct ordering at the append-fired-from-many-routes scale OLP runs. - New exports: `_maybeRotateAudit` (sync), `getAuditRotateCount`, `getAuditRotateFailCount`, `__resetAuditRotateState`, `__setLastSeenUtcDateForTesting`. - First-event-date discovery: when probing the live file's date, reads only the first ndjson line + parses its `ts`. Falls back to file mtime if events absent (corrupt/empty edge). - **`bin/olp-audit-rotate.mjs`** (~95 lines): external cron tool per ADR 0008 Β§ 5.2. Calls `_maybeRotateAudit` once + reports outcome. Exit codes 0 (success or no-op), 1 (bad usage), 2 (rotation failed). Installed via `package.json bin` so `npx olp-audit-rotate [--olp-home=]` works. Example cron line documented in the file header. - **Concurrent-safety semantics** (ADR 0008 Β§ 5.3): in-process sequential appends after the first date-change detection short-circuit via the updated `_lastSeenUtcDate` cache β†’ exactly 1 rename even under N sequential appends. Cross-process (cron + server) coexistence handled by the "target already exists β†’ skip + warn" branch. - **Test surface (Suite 26, +12 tests β€” 588 β†’ 600):** - 26a-1..5: `_maybeRotateAudit` (no live file / today already / yesterdayβ†’rotate / idempotent re-call / cron-race target-exists warn) - 26b-1: `appendAuditEvent` past UTC date change triggers sync rotation + append lands in fresh live file - 26c-1: 10 sequential `appendAuditEvent` across date change β†’ exactly 1 rotation + all 10 events in new live file - 26d-1..4: `bin/olp-audit-rotate.mjs` CLI (--help / no-live-file / yesterday-file-rotates / unknown-flag exit 1) - 26e-1: rotated files queryable via `lib/audit-query.mjs` `discoverAuditFiles` + `readAuditWindow` cross-file read - **`package.json`**: `bin.olp-audit-rotate` + `scripts.olp-audit-rotate` entries added. - **Documentation:** AGENTS.md `lib/audit.mjs` marker promoted to βœ… (D45 append + D52 rotation both shipped); new `bin/olp-audit-rotate.mjs` entry. - **Test count:** 588 β†’ 600 (+12 D52 tests in Suite 26). - **Authority:** ADR 0008 Β§ 5.1 (first-append-after-UTC-midnight trigger), Β§ 5.2 (external cron alternative), Β§ 5.3 (concurrent-rotation safety + cron-coexistence semantics), Β§ 5.4 (renamed-file query path consumed by D49 lib/audit-query.mjs); CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; standing autopilot grant. ### D51 β€” `dashboard.html` full multi-panel UI (Phase 3) Fourth Phase 3 D-day. Replaces the D50 `dashboard.html` placeholder with the full 4-panel UI per ADR 0008 Β§ 6. Vanilla HTML + JS + fetch β€” no build step, no framework, no CDN (Lane 1 = A). 30s page poll with `document.visibilityState` pause/resume (Lane 4 = A). - **4 panels rendered from `/v0/management/dashboard-data`** (the single backing endpoint, per Lane 2 in-memory query model): - **Panel 1 β€” Per-provider quota**: table of `{ Provider | Available | Status }`; surfaces `null` available as "n/a" + capturing per-provider `provider.quotaStatus()` errors as a red status pill (graceful degradation per ADR Β§ 9). - **Panel 2 β€” Last 24h: request count + cache hit + fallback rate**: per-provider row of `{ Requests | Cache hit % | Fallback rate % }`. Cache hit sourced from `cache_hit_24h.by_provider[p].hit_rate`; fallback rate computed from `window_24h.by_provider[p].fallback_count / count`. - **Panel 3 β€” Request count last 30 days (SVG sparkline)**: vanilla SVG bar chart with `` tooltips showing per-day per-provider breakdown. Y-axis: requests per day (scaled to max); X-axis: 30 daily buckets (UTC). Each bar `<title>` includes the date + total count + provider breakdown. - **Panel 4 β€” Top fallback chains (last 24h)**: numbered table of `{ # | Chain | Count | First seen | Last seen }` with chain arrows rendered in monospace (`anthropic β†’ openai`). - **30s poll + visibilitychange pause** (ADR 0008 Β§ 6.5): - `setInterval(refresh, 30000)` after the initial fetch. - `document.addEventListener('visibilitychange', ...)` β†’ `stopPolling()` on hidden / `refresh() + startPolling()` on visible. - Per ADR Β§ 6.5 this prevents 2880 background polls/day per owner when the dashboard tab is in the background. - **Error handling**: - 401 from `/v0/management/dashboard-data` β†’ in-page error banner explains owner-tier requirement + suggests SSH-tunnel + header-injection workaround (browsers can't natively send `Authorization: Bearer` without a proxy/extension). - Other HTTP errors β†’ generic "HTTP <code>" banner; console.warn for operator debugging. - Per-panel "Loading…" / "No requests in window." / "No fallback chains triggered" empty states. - **DOM helpers**: small `el(tag, attrs, ...children)` + `svgEl(tag, attrs)` factories β€” no framework, ~10 lines each. Sparkline uses native `<title>` for tooltips (no JS hover handlers). - **Critical correctness invariants** (per ADR 0008 Β§ 6 + Lane 1 = A): - No `<script src>` β€” entire JS inline in `<script>` tag (Suite 25d asserts). - No `<link rel="stylesheet" href=>` β€” all CSS in `<style>` tag (Suite 25d asserts). - Only one backing endpoint hit: `/v0/management/dashboard-data` (Suite 25e asserts). All 4 panels consume slices of its response. - 401 path keeps panels in last-good state rather than clearing them; operator sees the error banner + can debug. - **Test surface (Suite 25, +6 tests β€” 582 β†’ 588):** - 25a: owner /dashboard response contains all 4 panel container IDs (`panel-quota`, `panel-24h`, `panel-trend`, `panel-chains`). - 25b: dashboard JS declares `POLL_INTERVAL_MS = 30000` + uses `setInterval` + `clearInterval`. - 25c: visibilitychange listener wired + checks `document.visibilityState === 'hidden'`. - 25d: NO external `<script src>` and NO external stylesheet `<link href>` β€” pinning Lane 1 = A. - 25e: dashboard JS fetches `/v0/management/dashboard-data` (the single consolidated D50 endpoint). - 25f: 401 in-page error banner mentions owner-tier so a maintainer who lands on a 401 knows the route forward. - **Manual smoke (ADR 0008 Β§ 10 #12 manual acceptance)**: the dashboard renders without console errors in a real browser when served by a running OLP instance + owner-tier Bearer token injected via SSH-tunnel + header-injection extension. Not automated at Phase 3 (Lane 4 = A poll model doesn't need playwright; Phase 4+ may add a playwright smoke if dashboard complexity grows). - **Documentation:** AGENTS.md `dashboard.html` marker promoted from 🟑 D50 placeholder to βœ… D51 full UI. - **Test count:** 582 β†’ 588 (+6 D51 tests in Suite 25). - **Authority:** ADR 0008 Β§ 6 (panels + refresh + localhost) + Β§ 6.5 (poll + visibilityState pause) + Lane 1 = A (no build step) + Lane 4 = A (30s poll) + Lane 5 = B (full 4-panel scope); ADR Β§ 9 (graceful degradation surfaced in Panel 1); ADR Β§ 10 criterion #12 (HTML smoke); CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; standing autopilot grant. ### D50 β€” `server.mjs` management endpoints (Phase 3 dashboard wire-up) Third Phase 3 D-day. Wires the D49 `lib/audit-query.mjs` aggregate query layer into 4 owner_only_block HTTP endpoints per ADR 0008 §§ 7-8. Ships a placeholder `dashboard.html` at repo root (D51 lands the full multi-panel UI). All endpoints follow the Phase 2 / D45 auth + audit + touchLastUsed pattern. - **4 new endpoints** (all owner_only_block per ADR 0008 Β§ 8 β€” anonymous + guest + missing-key all β†’ 401): - `GET /dashboard` β€” serves `dashboard.html` (Content-Type text/html; charset=utf-8). D50 stub explains the state + lists backing endpoints; D51 replaces with full UI. - `GET /v0/management/dashboard-data` β€” full aggregate per ADR 0008 Β§ 7.2: `{ generated_at, window_24h (auditAggregateRequests), cache_hit_24h (auditCacheHitRateWindow), quota (per-provider provider.quotaStatus + error capture), spend_trend_30d (auditSpendTrendDaily β€” exactly 30 entries), top_fallback_chains_24h (auditTopFallbackChains limit 10), cache_stats (live cacheStore.stats()) }`. - `GET /v0/management/quota` β€” quota subset only (subset of dashboard-data; useful for scripted monitoring). - `GET /cache/stats` β€” live in-memory `cacheStore.stats()` shape (`{ hits, misses, size, inflightCount }` + `generated_at` wrapper). - **`_runOwnerOnlyManagementEndpoint(req, res, method, path, inner)` helper** factors the common auth + audit ctx + owner-block + res.on('finish') wire. inner is async (req, res, olpIdentity, auditCtx) β†’ returns void. Eliminates 4Γ— boilerplate. - **`owner_only_block` mode** (ADR 0008 Β§ 8): authenticate β†’ if not owner β†’ 401 `owner_required`. Distinct from `owner_only_trim` (Phase 2 /health pattern). Anonymous identity (when `allow_anonymous: true`) reaches the handler and is 401'd by the owner check β€” verified by Suite 24c. - **Provider quotaStatus error capture**: dashboard-data + quota endpoints catch per-provider throws and surface `{ provider, error, available: null }` so one bad provider doesn't fail the whole panel (ADR 0008 Β§ 9 graceful degradation). - **`dashboard.html` placeholder** (~50 lines at repo root): explains the D50 state, lists backing endpoints with curl example. Cached in memory at first /dashboard request (`_loadDashboardHtml` with module-scope `_dashboardHtmlCache`); falls back to an in-memory stub if the file is missing (e.g., test imports from non-repo cwd). - **Audit on management endpoints** (ADR 0008 Β§ 7.5): every management request appends an audit row including 401 paths (verified by Suite 24j). Touch wire skips anonymous + env-owner identities (matches Phase 2 pattern). - **Router**: 4 new GET branches added between /v1/chat/completions and the 404 fallback. - **Test surface (Suite 24, +11 tests β€” 571 β†’ 582):** - 24a-d: /dashboard owner_only_block (owner 200 / guest 401 / anonymous-with-allow_anonymous=true 401 / no-auth-with-allow_anonymous=false 401) - 24e: dashboard-data owner β†’ 200 JSON with all required ADR Β§ 7.2 fields (asserts `spend_trend_30d.length === 30`) - 24f: dashboard-data guest β†’ 401 owner_required - 24g: quota owner β†’ 200 JSON with quota array - 24h: cache/stats owner β†’ 200 JSON with `{ hits, misses, size, inflightCount, generated_at }` - 24h-401: cache/stats guest β†’ 401 - 24i: successful dashboard-data appends audit row with `status_code: 200` + `key_id` + `path: '/v0/management/dashboard-data'` - 24j: 401 (guest blocked) dashboard-data appends audit row with `error_code: 'owner_required'` + `owner_tier: 'guest'` - **Documentation:** AGENTS.md `lib/audit-query.mjs` D49 marker note added + new `dashboard.html` entry (D50 placeholder). - **Test count:** 571 β†’ 582 (+11 D50 tests in Suite 24). - **Authority:** ADR 0008 Β§ 7 (endpoints) + Β§ 8 (owner_only_block mode) + Β§ 9 (graceful degradation) + Β§ 7.5 (audit on management endpoints); ADR 0007 Β§ 7 (auth model reused); ADR 0002 Β§ Provider contract (quotaStatus); ADR 0005 (cacheStore.stats); CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; standing autopilot grant. ### D49 β€” `lib/audit-query.mjs` audit aggregate query layer (Phase 3) Second Phase 3 D-day. Implements ADR 0008 Β§ 4 query API. Pure in-memory ndjson scan; cross-file walk over `audit.ndjson` (live) + `audit-YYYY-MM-DD.ndjson` (rotated). No server.mjs integration in this D-day (D50 wires the consuming endpoints). - **New file `lib/audit-query.mjs`** (~370 lines): 5 public API functions per ADR 0008 Β§ 4.1: - `discoverAuditFiles({ olpHome })` β€” filesystem scan; returns `Map<date|'live', path>`. - `readAuditWindow({ startMs, endMs, olpHome, logEvent })` β€” generator over events in half-open window [startMs, endMs). Walks rotated date files + live file. Skips malformed lines + logs warn. - `aggregateRequests({ windowMs, olpHome })` β€” counts + status buckets + by_provider + by_owner_tier + by_path + median/p95 latency over rolling window. - `topFallbackChains({ windowMs, limit, olpHome })` β€” top-N chains by trigger count from events with `fallback_hops > 0`. Tied-count tiebreak: ascending first_seen. - `spendTrendDaily({ days, olpHome })` β€” daily series ending today with sparse-fill for zero-request days. Per-day request_count + median latency + by_provider breakdown. - `cacheHitRateWindow({ windowMs, olpHome })` β€” audit-derived cache hit rate (bypass excluded from denominator); per-provider + overall. - **PII discipline** (ADR 0008 Β§ 4.3): every aggregate function relays only schema fields; never message content. Suite 23g actively asserts the absence of `content`/`message`/`messages`/`prompt`/`response`/`body` keys in every aggregate output. - **Cross-file walk semantics** (ADR 0008 Β§ 4.2): half-open window [startMs, endMs); date-range computed once from window bounds; each rotated date file checked; live `audit.ndjson` always checked (it covers today regardless of whether the window endpoint is past midnight). - **`spendTrendDaily` calendar-date semantics**: `days: N` returns "last N calendar UTC dates ending today" β€” NOT "events within a rolling NΓ—86400-ms window" (which would span N+1 distinct UTC dates and produce off-by-one buckets at non-midnight call times). Computed via `for (let i = days-1; i >= 0; i--) dates.push(_utcDateFromMs(now - i*86400*1000));`. - **`cacheHitRateWindow` denominator**: hit_rate = hit / (hit + miss). Bypass is intentional non-cacheable (Anthropic cache_control marker), NOT a cache miss; excluding it from the denominator gives a clean cache-effectiveness signal. - **Test surface (Suite 23, +27 tests β€” 544 β†’ 571):** - 23a-1..4: `discoverAuditFiles` (empty dir / live only / live+rotated / non-audit files ignored) - 23b-1..6: `readAuditWindow` (all-coverage / single-day / half-open exclusivity / empty window / missing files / malformed-skip with warn) - 23c-1..4: `aggregateRequests` (counts + status buckets + by_provider; by_owner_tier; median+p95 latency over realistic distribution; invalid windowMs rejection) - 23d-1..4: `topFallbackChains` (sort desc by count; limit truncation; fallback_hops=0 excluded; first_seen/last_seen carried) - 23e-1..3: `spendTrendDaily` (N-day range correctness; populated day breakdown; empty day sparse-fill) - 23f-1..3: `cacheHitRateWindow` (overall + per-provider hit_rate; bypass not in denominator; cache_status=null events excluded) - 23g-1..3: PII guard for `aggregateRequests` / `spendTrendDaily` / `topFallbackChains` + `cacheHitRateWindow` β€” every output JSON-stringified + scanned for forbidden PII keys - **Documentation:** AGENTS.md `lib/audit-query.mjs` new entry; `lib/audit.mjs` note added that D52 extends with daily rotation. - **Test count:** 544 β†’ 571 (+27 D49 tests). - **Authority:** ADR 0008 Β§ 4 (query API surface) + Β§ 5 (rotation file naming pattern) + Β§ 3 (storage layout); ADR 0007 Β§ 8 (audit ndjson event schema β€” input data); CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; standing autopilot grant. ### D48 β€” ADR 0008 Phase 3 design draft (Dashboard + audit query layer) First Phase 3 D-day. Design-only. Ratifies the storage / query model / rotation / dashboard / refresh / scope decisions ahead of D49+ implementation D-days. Opens ADR 0007 Β§ 12 deferral for Dashboard + audit query layer + rotation. - **New file `docs/adr/0008-dashboard-and-audit-query.md`** (~390 lines): 13 sections + Consequences + Authority citations. Decisions per maintainer-pinned lanes: - Lane 1 (tech stack): static HTML + vanilla JS + fetch (no build step; matches OLP "no bundler" ethos) - Lane 2 (query model): in-memory scan of audit ndjson per request (defers SQLite hybrid per ADR 0007 Β§ 13) - Lane 3 (rotation): daily rotation, `audit-YYYY-MM-DD.ndjson` on first append after UTC midnight + optional `bin/olp-audit-rotate.mjs` external cron - Lane 4 (refresh): 30s page poll (no SSE infra at v0.3.0) - Lane 5 (dashboard scope): full per spec Β§ 4.6 β€” 4 panels (quota / per-provider 24h counts / 30d spend trend / top fallback chains) - **`docs/adr/README.md` index**: added ADR 0008 row with one-paragraph summary. - **CHANGELOG.md** Unreleased: this entry. - **Phase 3 sprint shape:** D49 `lib/audit-query.mjs` + Suite 23 β†’ D50 `/v0/management/*` endpoints + Suite 24 β†’ D51 `dashboard.html` β†’ D52 daily audit rotation + Suite 25 β†’ D53 `tried_providers` schema fix (D45 P2 deferral) β†’ D54 E2E + docs β†’ D55 Phase 3 close β†’ v0.3.0 (maintainer-triggered). - **Fold-in (fresh-context opus reviewer findings β€” 1 P2 + 2 P3, all ADR-text polish):** - **P2 Β§ 8 + Β§ 10 #9 gating-mode wording** β€” original Β§ 8 implied a new "block non-owner identities" behaviour without naming it; Β§ 10 #9 tested only the universal `allow_anonymous: false` 401 case. Fix: Β§ 8 now formalizes two gating modes β€” `owner_only_trim` (Phase 2 /health pattern) vs `owner_only_block` (new Phase 3 management-endpoints pattern) β€” and explains the management endpoints are `owner_only_block` because the entire payload is sensitive. Β§ 10 #9 now covers both 401 paths (with `allow_anonymous: true` + no header β†’ anonymous identity β†’ still 401 because management endpoints are `owner_only_block`; AND with `allow_anonymous: false` + no header β†’ 401 at the authenticate middleware itself). - **P3 `/cache/stats` citation accuracy** β€” original Β§ 7.4 + Authority block cited "ADR 0005 Β§ Cache stats" which is not a real section. Corrected: planning authority is OLP v0.1 spec Β§ 4.6; ADR 0005 references the endpoint in `Consequences/Mitigations` (~line 279) for the per-`(provider, model)` cache-hit-rate breakdown surface. - **P3 `cacheStore.stats()` shape gap** β€” Β§ 7.4 now explicitly acknowledges the current shape (`{ hits, misses, size, inflightCount }` global aggregate) lacks the per-`(provider, model)` breakdown spec Β§ 4.6 implies; Phase 3 Panel 2 sources per-provider counts from `aggregateRequests` (audit-side) instead. If a future panel needs the breakdown, D50 amends the store shape + an ADR 0005 amendment fires at that time. Phase 3 acceptance criteria do not require the breakdown. - **Test count:** 544 β†’ 544 (design-only, no test change). - **Authority:** ADR 0007 Β§ 12 (opens deferral) + Β§ 13 (rejects SQLite at Phase 3 per Node baseline); v0.1 spec Β§ 4.6 / Β§ 4.7 (Dashboard + observability endpoints planning authority); OCP `dashboard.html` (prior art); CC 开发铁律 v1.6 Β§ 10 β€” fresh-context opus reviewer required for design ADR; Phase 3 kickoff via maintainer "go" 2026-05-25 + standing-autopilot grant; PR #25 fresh-context opus reviewer findings (3 polish items). ## v0.2.0 β€” 2026-05-25 ### Phase 2 β€” Multi-key auth + audit + owner gating + keygen CLI (D43-A β†’ D47) **Overview.** v0.2.0 closes Phase 2 β€” the multi-key authentication track that grew OLP from single-tenant anonymous-only proxy (v0.1.1) to a multi-identity deployment with per-key cache isolation, audit attribution, owner-vs-guest header gating, and a reproducible bootstrap CLI. 6 D-day commits (D43-A through D47) shipped between 2026-05-25 (single intensive session under the standing-autopilot grant). All 11 ADR 0007 Β§ 10 acceptance criteria are implemented + tested. **Test count: 468 (v0.1.1) β†’ 544 (v0.2.0).** +76 tests across the Phase 2 arc. **Phase 2 release_kit checklist** - [x] All 6 D-day deliverables landed on main (D43-A, D43-B ADR draft, D44, D45, D46, D47) - [x] CI green on every D-day merge commit + on this release commit's head - [x] Fresh-context opus reviewer on every implementation D-day (D44/D45/D46/D47), maintainer text-review on D43-B ADR - [x] All 11 ADR 0007 Β§ 10 acceptance criteria (#1–#11) covered by Suite 19/20/21/22 tests - [x] CHANGELOG "Unreleased" promoted to "## v0.2.0 β€” 2026-05-25" with D43-A through D47 entries - [x] `package.json` bumped 0.1.1 β†’ 0.2.0 - [x] `CLAUDE.md release_kit.phase_rolling_mode`: `current_phase` Phase 2 β†’ Phase 3; `current_pre_release_identifier` `0.2.0-phase2` β†’ `0.3.0-phase3` - [x] README status header + Implementation Status + Phase plan reflect Phase 2 shipped - [ ] Tag pushed (next step in this PR's lifecycle) - [ ] `release.yml` triggered + GitHub Release created (auto on tag push; D37 phase_rolling_mode gate will pass because Unreleased is now sentinel-only) **ADR 0007 Β§ 10 acceptance criteria β€” final ship status** | # | Criterion | Covering tests | |---|---|---| | 1 | Per-key cache namespace isolation | Suite 20i | | 2 | Anonymous prod-default off β†’ 401 | Suite 20a | | 3 | Anonymous dev-mode on β†’ 200 | Suite 20g | | 4 | Owner-vs-guest `/health` gating | Suite 21a-d | | 5 | Owner-vs-guest `X-OLP-Fallback-Detail` gating | Suite 21e-h | | 6 | Post-revoke 401 within next request | Suite 19o + Suite 20e | | 7 | Manifest atomicity + revoke-dominates-touch | Suite 19y-1..4 | | 8 | Audit ndjson round-trip + PII guard | Suite 20j + 20j-stream + 20j-401 | | 9 | Bootstrap keygen surface reproducible | Suite 22 | | 10 | `OLP_OWNER_TOKEN` env override | Suite 19p + Suite 20f | | 11 | `providers_enabled` 403 scope enforcement | Suite 20h | **Known limitations carried beyond v0.2.0** Phase 2 functional scope is complete. The following remain as Phase 3+ deferrals (tracked in `docs/v1x-roadmap.md` + new entries below): - **Dashboard (`dashboard.html`)** β€” owner-only multi-provider quota / fallback / cache-hit-rate panels. Per ADR 0007 Β§ 12 + v0.1 spec Β§ 4.6. Phase 3 mainline. - **Audit query layer + rotation** β€” `audit.ndjson` is append-only at v0.2.0; aggregate queries + log rotation deferred to Phase 3 alongside Dashboard. - **`tried_providers` semantics on `key_no_provider_access` 403** β€” schema currently reports filter-rejected hops as "tried"; either ADR Β§ 8 amendment (rename / add field) or D46+ semantic fix. Noted by D45 opus reviewer. - **Per-provider per-key auth artifact mapping** β€” ADR Β§ 12 explicit out-of-scope. Per-key cache + audit isolation works; per-key per-provider OAuth tokens (e.g., two OLP keys each authenticated to different OpenAI Codex accounts) is Phase 3+ work. - **SQLite migration (Option 3 hybrid)** β€” ADR Β§ 13 documents the forward path; trigger is Dashboard / SQL-aggregate-quota / multi-second audit-query workload. Requires engines bump (`>=22.13.0` or `>=23.4.0`) per ADR Β§ 11 as a separate prior PR. ### D47 β€” `bin/olp-keys.mjs` keygen CLI (Phase 2 functional scope closes) Fourth Phase 2 implementation D-day. Closes ADR 0007 Β§ 10 acceptance criterion #9 (bootstrap workflow must be reproducible without manual file editing) by shipping a minimal keygen CLI per Β§ 9.1. **Phase 2 functional scope is complete with this D-day** β€” remaining work is Phase 2 close β†’ v0.2.0 (maintainer-triggered, explicit per CLAUDE.md `release_kit.phase_close_trigger`). - **New file `bin/olp-keys.mjs`** (~250 lines): subcommand CLI with three subcommands: - `keygen [--owner] [--name=<label>] [--tier=guest|owner] [--providers=<csv>] [--force]` β€” creates a key + prints plaintext token to stdout ONCE; manifest stores only SHA-256 hash. `--force` revokes existing owner keys before creating the new owner (recovery flow per ADR Β§ 9.3). `--providers=*` (default) or comma-separated allowlist. - `list [--owner-only] [--include-revoked]` β€” lists keys with `token_hash` redacted (lib/keys.mjs `listKeys` already redacts). - `revoke --id=<key-id>` β€” marks the key's `revoked_at`; idempotent (already-revoked β†’ no-op + status message); missing id β†’ exit 2. - Common flag `--olp-home=<path>` overrides `~/.olp/`; defaults to `OLP_HOME` env or `~/.olp/`. - **`package.json` `bin` field**: `olp-keys` β†’ `./bin/olp-keys.mjs` so `npx olp-keys ...` resolves; also `npm run olp-keys ...` via scripts. - **Module shape**: CLI exposes `runCli(argv, { out, err })` so tests can invoke it with synthetic argv + IO writers (no process spawn). Main guard auto-runs when invoked as entrypoint. - **Plaintext token discipline**: per ADR Β§ 5 + Β§ 9.1, plaintext is printed exactly once on stdout. Never logged, never written to manifest, never written to audit. Operators must capture immediately; lost β†’ `--force` revoke + regenerate. - **`--force` async correctness**: `cmdKeygen` is async and `await`s each `revokeKey` (which is async β€” acquires per-key write lock per Β§ 6.4). Sequence: revoke each existing owner manifest atomically β†’ then `createKey` for new owner. Avoids the race where create-new runs before revoke-old completes. - **Test surface (Suite 22, +20 tests β€” 524 β†’ 544):** - 22a-1..5: parseArgv unit tests (`--flag=value`, `--flag value`, boolean, mixed positional) - 22b-1..5: keygen subcommand (owner default, name+providers, missing-name error, invalid-tier error, --force revoke-then-create flow with isolation tmpdir) - 22c-1..3: list subcommand (empty, populated with token_hash-redaction check, --owner-only filter) - 22d-1..4: revoke subcommand (valid id, idempotent re-revoke, missing-id error, nonexistent-id error) - 22e-1..3: top-level CLI behaviour (--help / no args / unknown subcommand exit codes) - **Documentation:** AGENTS.md `lib/keys.mjs` marker promoted to βœ…; new `bin/olp-keys.mjs` entry. Implementation-status-note + shipped-set updated. README.md Implementation Status table gains `bin/olp-keys.mjs` row; Known limitations note updated to "Phase 2 functional scope complete; close pending"; new "Bootstrap workflow" section with copy-pasteable npx commands + recovery flow. - **Test count:** 524 β†’ 544 (+20 D47 tests in Suite 22). - **Authority:** ADR 0007 (multi-key auth β€” Β§ 5 token format, Β§ 9.1 minimal keygen command surface, Β§ 9.3 recovery, Β§ 10 acceptance criterion #9 covered); CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; standing autopilot grant. ### D46 β€” owner-vs-guest gating for `/health` + `X-OLP-Fallback-Detail` (Phase 2 closes header observability gap) Third Phase 2 implementation D-day. Closes ADR 0007 Β§ 10 acceptance criteria #4 (`/health` payload trimming for non-owner) + #5 (`X-OLP-Fallback-Detail` emission gating per `fallback_detail_header_policy`). Phase 2 server surface is now fully gated end-to-end; remaining D-days are keygen CLI surface (D47+) and Phase 2 close (v0.2.0, maintainer-triggered). - **`server.mjs` `handleHealth` identity-aware payload** per ADR Β§ 7.1: - Auth gate at top β€” `authenticate(req)` returns 401 for unauth + `allow_anonymous: false` (consistent with /v1/* routes); 200 with trimmed payload for anonymous / guest; 200 with full payload for owner. - Trim controlled by `_authConfig.owner_only_endpoints` β€” if `/health` is in the list, non-owner gets `{ ok: true, version }`; else (operator removes it) full payload to everyone (v0.1.1 opt-out knob). - `touchLastUsed` fired on `res.on('finish')` for filesystem identities (matches /v1/* pattern). No audit row on /health β€” high-volume monitoring endpoint, audit volume noise not justified at Phase 2 (would land with Phase 3 Dashboard if aggregate /health stats become needed). - **`server.mjs` `withFallbackDetailHeader` identity-aware emission** per ADR Β§ 7.2: - New helper `shouldEmitFallbackDetailHeader(olpIdentity)` reads `_authConfig.fallback_detail_header_policy`: - `'owner_only'` (default) β†’ emit only when `olpIdentity.owner_tier === 'owner'` - `'all'` β†’ emit unconditionally (v0.1.1 opt-back-in for operators who want the diagnostic header for all identities) - `'none'` β†’ suppress unconditionally - When `olpIdentity` is null (pre-auth error paths), defaults to emit β€” preserves the v0.1.1 ungated behaviour for pre-auth errors where identity is unknown. - `withFallbackDetailHeader` signature gains a third `olpIdentity` argument; both call sites in `handleChatCompletions` updated to pass `olpIdentity`. - **Test surface (Suite 21, +9 tests + 1 added in Suite 20 β€” 515 β†’ 524):** - **20m** /health with no auth + `allow_anonymous=false` β†’ 401 (consistency with /v1/* routes) - **21a-d** /health payload trimming (criterion #4): anonymous trimmed; guest trimmed; owner full; `owner_only_endpoints: []` opts out (guest gets full) - **21e-h** X-OLP-Fallback-Detail emission gating (criterion #5): `owner_only` + guest β†’ header absent; `owner_only` + owner β†’ header present + valid JSON; `'all'` + guest β†’ header present (v0.1.1 opt-back); `'none'` + owner β†’ header absent (full suppression). Tests use a 2-hop chain (anthropic primary fail + openai secondary) to produce non-empty `fallbackDetail` for the header content. - **Test-mode setup updated:** the global `__setAuthConfig({ allow_anonymous: true })` was extended to also pass `owner_only_endpoints: []` + `fallback_detail_header_policy: 'all'` so pre-D46 tests (Suite 18, F5 /health tests, D40 fallback-detail tests, etc.) continue to pass without modification β€” Suite 21 explicitly overrides per-case to exercise the production-default-gated paths. - **Documentation:** AGENTS.md `lib/keys.mjs` marker updated to reflect D46 ship; Implementation-status-note updated. README.md Implementation Status row + Known limitations "Multi-key auth" note rewritten to reflect D46 ship + remaining keygen CLI. - **Test count:** 515 β†’ 524 (+9 D46 tests). - **Authority:** ADR 0007 (multi-key auth β€” §§ 7.1 + 7.2 implementation contracts + Β§ 10 acceptance criteria #4 + #5 covered); ADR 0004 Amendment 5 (D40 ratification of "Phase 2 will re-introduce owner-vs-non-owner gating when `lib/keys.mjs` lands" β€” this D-day fulfils the deferral); CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; standing autopilot grant (`~/.cc-rules/memory/auto/standing_autopilot_phase_2.md` in cc-rules `bf0ed9a`). ### D45 β€” `server.mjs` auth integration + `lib/audit.mjs` (Phase 2 wire-up) Second Phase 2 implementation D-day. Wires the D44 `lib/keys.mjs` identity layer into the request flow + lands `lib/audit.mjs` per ADR 0007 Β§ 6.2 + Β§ 8. Closes acceptance criteria #1 (per-key cache isolation, validation-side end-to-end), #2 (anonymous prod-default off), #3 (anonymous dev-mode on), #6 (post-revoke 401 within next request β€” full), #8 (audit ndjson round-trip), #10 (`OLP_OWNER_TOKEN` env override β€” full server-side), #11 (`providers_enabled` 403 scope). Owner-vs-guest gating for `/health` + `X-OLP-Fallback-Detail` (criteria #4, #5) remains in D46 scope. - **New file `lib/audit.mjs`** (~75 lines): `appendAuditEvent(event, opts)` writes one JSON event per line to `~/.olp/logs/audit.ndjson` (file 0600, dir 0700). Β§ 6.2 retry semantics: warn + 1 retry on first failure; per-process drop counter + warn on second failure; NEVER throws. Per-call `OLP_HOME` env resolution (matches `lib/keys.mjs`). Exports `getAuditDropCount` for future /health surface. - **`lib/keys.mjs`** extended with `loadAuthConfigSync({ olpHome })` reading the `auth` block from `~/.olp/config.json` with defaults per ADR Β§ 7.2 (`allow_anonymous: false`, `owner_only_endpoints: ['/health']`, `fallback_detail_header_policy: 'owner_only'`). Both `lib/keys.mjs` + `lib/audit.mjs` now resolve `OLP_HOME` env per call (precedence: opts.olpHome β†’ process.env.OLP_HOME β†’ ~/.olp) so tests and operator deployments can redirect without code edits. - **`server.mjs` auth middleware integration:** - `extractToken(req)` parses `Authorization: Bearer <token>` first, then `x-api-key: <token>`. - `authenticate(req)` calls `validateKey(token, { allowAnonymous: _authConfig.allow_anonymous })`; returns identity on success, 401 `{ auth_required | invalid_or_revoked_key }` on failure. - `isProviderEnabled(olpIdentity, providerKey)` enforces `providers_enabled` allowlist (`'*'` = all). - `_authConfig` loaded at startup; warn `auth_allow_anonymous_enabled` fires if `allow_anonymous: true` so the relaxed posture is visible. Test seams `__setAuthConfig` / `__resetAuthConfig`. - `handleChatCompletions` and `handleModels` both gated by `authenticate(req)` at top. Audit ctx object built throughout the handler lifecycle; `res.on('finish')` appends the row + fires `touchLastUsed` async (best-effort). - **Identity-vs-credentials separation:** `olpIdentity` (the new validated identity) is consumed for cache namespacing + providers_enabled + audit; `authContext` passed to `provider.spawn()` REMAINS `null` so providers continue their own credential discovery (env / keychain / file). Per-provider per-key credential mapping is Phase 3+ scope per ADR Β§ 12. - `handleChatCompletions` chain filtered by `chain.filter(hop => isProviderEnabled(olpIdentity, hop.provider))`; empty result returns 403 `key_no_provider_access` with helpful diagnostic message. - `keyId = olpIdentity.keyId` (replacing hardcoded `'__anonymous__'` at the cache call sites). - Audit captures fields throughout: post-auth (key_id, owner_tier); post-IR (model); post-chain-success (provider, fallback_hops, tried_providers, cache_status); post-chain-exhausted (error_code, providerUsed=chain[0], cache_status='miss'). Status code + latency populated on `res.on('finish')`. - **Test surface (Suite 20, +15 tests, 499 β†’ 514):** - 20a-d: header parsing + valid key happy paths (Bearer / x-api-key / invalid β†’ 401) - 20e: revoked key 401 (closes criterion #6 end-to-end) - 20f: `OLP_OWNER_TOKEN` env override returns 200 (criterion #10 full coverage) - 20g: `allow_anonymous: true` + no header returns 200 (criterion #3) - 20h + 20h-extra: `providers_enabled: ['mistral']` for anthropic model β†’ 403; `'*'` baseline returns 200 (criterion #11) - 20i: per-key cache namespace isolation β€” keys A/B with identical payload do not share cache (criterion #1 end-to-end) - 20j + 20j-401: audit.ndjson written with Β§ 8 schema fields including PII guard; 401 path also appends (criterion #8) - 20k: filesystem key `last_used_at` populated after first successful request (D45 touchLastUsed wire) - 20l + 20l-200: `/v1/models` also enforces auth (consistent gating across `/v1/*`) - **Test-mode setup:** test-features.mjs sets `process.env.OLP_HOME` to a tmpdir at module load so audit + key writes don't pollute `~/.olp/`. After the server.mjs import resolves, calls `__setAuthConfig({ allow_anonymous: true })` so pre-D45 HTTP integration tests (Suite 18 etc.) that don't pass an Authorization header continue to pass as anonymous; Suite 20 explicitly overrides per-case for production-default-off coverage. - **Documentation:** AGENTS.md `lib/keys.mjs` 🟑 marker updated + new `lib/audit.mjs` entry; AGENTS.md Implementation-status-note + shipped-set updated. README.md Implementation Status table gains `lib/audit.mjs` row + `lib/keys.mjs` row updated; Known limitations "Multi-key auth" note rewritten to reflect D45 ship + D46 follow-up; new env-vars and config block surfaced for users. - **Test count:** 499 β†’ 515 (+15 initial Suite 20 tests + 1 fold-in regression test `20j-stream` covering opus-P1 streaming audit-fidelity). - **Fold-in (CI-fail recovery + fresh-context opus reviewer findings, 1 CI + 1 P1 + 2 P2 + 1 P3):** - **CI Node 24 failure** β€” Suite 20 setup did not stub `CLAUDE_CODE_OAUTH_TOKEN` before the mock spawn ran; lib/providers/anthropic.mjs `_spawnAndStream` checks for an OAuth token BEFORE invoking the (mock) spawn, so the AUTH_MISSING pre-check fired and every Suite 20 200-expecting test 502'd on CI Node 24 (local Node 22 had the env from the maintainer's claude install). Fixed by `ensureSuite20FakeOAuth` / `restoreSuite20OAuth` helpers in `makeSuite20Server` / `teardownSuite20`; matches the existing pattern used at Suite 9 line ~2154 (`test-fake-oauth-token-for-cache-tests`). - **P1 real-streaming audit fidelity** β€” single-hop streaming success path (server.mjs ~L1050+ `if (ir.stream && chain.length === 1 && !bypassCacheForFirstHop ...)`) did not populate `auditCtx.provider` / `tried_providers` / `cache_status`, so audit rows for the most common deployed shape carried `provider: null`. Fixed by stamping these fields at the top of the streaming branch (between the streamPlugin null-check and the `streamHeaders` build) and amending `error_code` on the two streaming failure exit paths (`streaming_error_after_first_chunk` + `streaming_error_before_first_chunk`). New regression test `20j-stream` makes a streaming request and asserts the audit row's `provider`, `cache_status`, and `tried_providers` fields are populated. - **P2 global test tmpdir cleanup** β€” `process.env.OLP_HOME = mkdtempSync(...)` at module load left a `/var/folders/.../olp-test-home-*` directory leak per `npm test` run. Fixed by `process.on('exit', () => rmSync(...))` registered immediately after the mkdtempSync. Best-effort; never throws at exit. - **P3 handleModels 401 lacks OLP diagnostic headers** β€” `handleChatCompletions` 401 path passes `olpErrorHeaders({ startMs })` but `handleModels` did not. Aligned by adding the same headers to the `handleModels` `authResult.ok=false` return. - **Deferred (acknowledged by reviewer as non-blocking):** P2 `tried_providers` semantics on `key_no_provider_access` 403 β€” schema currently reports filter-rejected hops as "tried" which a downstream Dashboard would misread; either ADR Β§ 8 amendment (rename / add field) or D46+ semantic fix. - **Authority:** ADR 0007 (multi-key auth β€” §§ 5/6.2/7/9.4 implementation contracts + Β§ 10 acceptance criteria #1/#2/#3/#6/#8/#10/#11); CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; Phase 2 kickoff handoff (`~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md` in cc-rules `d9da966`); standing autopilot grant (`~/.cc-rules/memory/auto/standing_autopilot_phase_2.md` in cc-rules `bf0ed9a`). ### D44 β€” `lib/keys.mjs` core landed (multi-key auth, no server wire-up yet) First Phase 2 implementation D-day. Lands the `lib/keys.mjs` module per ADR 0007 §§ 5/6.1/6.3/6.3.5/6.4/9.4. Identity / lifecycle layer for OLP API keys is now in-tree; `server.mjs` integration scheduled D45 (until then, requests still use the hardcoded `'__anonymous__'` cache namespace β€” no behavioural change at v0.1.1 / D44). - **New file `lib/keys.mjs`** (~462 lines after fold-in) β€” public API surface: - `createKey({ name, owner_tier, providers_enabled, notes, olpHome })` β€” generates opaque `olp_<32-byte base64url>` token (47-char total), SHA-256 hashes it for manifest storage, atomically writes `keys/<id>/manifest.json` (mode 0600, dir 0700). Returns `{ id, plaintext_token, manifest }` β€” plaintext token is printed once and never persisted. - `validateKey(plaintext, { allowAnonymous, olpHome })` β€” three-tier resolution per Β§ 5 / Β§ 7 / Β§ 9.4: env override (`OLP_OWNER_TOKEN` β†’ `__env_owner__` synthetic identity) β†’ anonymous (only when `allowAnonymous: true`, returns `__anonymous__` identity) β†’ filesystem manifest lookup (constant-time hash compare via `crypto.timingSafeEqual`). Revoked manifests return null (caller produces 401). Per Β§ 6.3.5 β€” MUST hit manifest every request; no in-process validation cache. - `revokeKey({ id, olpHome })` β€” idempotent; sets `revoked_at` via atomic write inside per-key write-lock. - `listKeys({ olpHome })` β€” returns manifest objects with `token_hash` redacted. - `touchLastUsed(id, { olpHome })` β€” async best-effort lazy update per Β§ 6.3 revoke-dominates-touch: re-reads latest manifest inside the per-key lock, NO-OPs if `revoked_at` is non-null, otherwise merges `last_used_at` preserving all other fields. Failure logs warn and never throws. - **Β§ 6.4 in-process per-key write-lock** β€” `Map<key-id, Promise>` chain; serializes intra-process writes. External (CLI) writes not lock-protected at Phase 2; atomic-rename + Β§ 6.3 read-before-write give the `revoke dominates touch` safety property. - **Test-only hooks** β€” `__setTouchInterleaveHook` (inject deterministic pause between touch's lock acquisition and read for race tests) + `__resetWriteLocks` (test cleanup). - **What is NOT in D44 (split per ADR §§ 6.2 / 9.1 separation):** audit ndjson append (request-layer concern; D45 server glue); keygen CLI bootstrap surface (D45+); `server.mjs` integration replacing the hardcoded `'__anonymous__'` keyId at `server.mjs:502, :531` (D45); owner-vs-guest gating for `/health` and `X-OLP-Fallback-Detail` (D46). - **Test count:** 468 β†’ 496 (+28 tests in new Suite 19): - 19a-d token generation (Β§ 5) - 19e-j manifest write+read + chmod 0600/0700 + schema validation (Β§ 4, Β§ 6.1) - 19k-p validateKey: filesystem / wrong / missing / anonymous / revoked / env override (Β§ 5, Β§ 6.3.5, Β§ 9.4) - 19q-r revokeKey idempotency + non-existent id - 19s-t listKeys empty + redaction - 19u-x touchLastUsed updates + NO-OP on revoked + NO-OP on anonymous/env identities + best-effort failure - **19y-1 to 19y-4 acceptance criterion #7 (concurrent revoke + touch race tests)**: revokeβ†’touch, touchβ†’revoke, interleaved external-revoke-via-hook (deterministically reproduces the Β§ 6.3 race the maintainer's text review caught), 30-iteration concurrent-promise stress - **Documentation:** AGENTS.md `lib/keys.mjs` πŸ“‹ marker β†’ 🟑 "core landed at D44"; AGENTS.md Implementation-status-note + shipped-set updated to include `lib/keys.mjs`; README.md Implementation Status row + Known limitations "Multi-key auth" note updated to "core landed, server integration pending D45". - **Fold-in (fresh-context opus reviewer findings, 2 P2 correctness + 2 P3 polish):** - **P2 #1 lock-map cleanup** (`lib/keys.mjs` `_withKeyLock`): prior version stored `prev.then(() => next)` as the Map tail, but the cleanup-identity check `_writeLocks.get(id) === next` could never match the derived promise β€” Map entries leaked one-per-unique-key-id. Bounded impact at family scale (~5–10 entries) but a real correctness bug. Fixed by storing `next` directly. New regression tests `19x-extra` (sequential) + `19x-extra-2` (concurrent 3-key Γ— 3-touch contention) assert `__writeLockSize() === 0` post-drain. - **P2 #2 `validateKey` non-string defensive coding**: prior version threw `TypeError` when called with a non-string truthy plaintext (`validateKey(42)` / `validateKey({})`), reaching `hashToken(<non-string>)` β†’ `createHash().update(<non-string>)`. Q2 promised "bad inputs return null." Fixed via top-of-function `if (plaintextToken != null && typeof plaintextToken !== 'string') return null;`. New test `19m-extra` covers number / object / array / `allowAnonymous: true` paths. - **P3 #3 19y-3 test scope comment**: test simulates external revoke landing BEFORE touch's read, not BETWEEN touch's read and write (which is currently unreachable because `touchLastUsed` has synchronous readβ†’write β€” no await between `readManifest` and `writeManifestAtomic`). Added explanatory comment documenting the synchronous-read-write property as the satisfaction mechanism for ADR Β§ 10 criterion #7 scenario 3, with a note that a post-read hook + matching test would be required if a future refactor introduces an await between read and write. - **P3 #4 CHANGELOG line count**: corrected `~330 lines` to `~462 lines after fold-in` (matches `wc -l lib/keys.mjs`). - **Test count after fold-in:** 468 β†’ 499 (+31 tests: 28 initial + 3 fold-in regression tests). - **Authority:** ADR 0007 (multi-key auth β€” Decision: Option 2 filesystem manifest + opaque token; §§ 5/6.1/6.3/6.3.5/6.4/9.4 implementation contracts; Β§ 10 acceptance criteria #6/#7 partially-covered by D44 tests, full coverage requires D45+ server integration); CLAUDE.md `release_kit overlay phase_rolling_mode` β€” under Unreleased; Phase 2 kickoff handoff (`~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md` in cc-rules `d9da966`); PR #20 fresh-context opus reviewer findings. ### D43-B β€” ADR 0007 multi-key auth design draft (design-only, no code change) Phase 2 mainline design ADR. Ratifies the storage / token / manifest / atomic-write / owner-gating / bootstrap / Node-baseline decisions ahead of D44+ implementation D-days. Pure design doc β€” no `.mjs` / no tests / 4 files touched. - `docs/adr/0007-multi-key-auth.md` (new, ~420 lines after fold-ins): 13 sections covering Context / Decision (Option 2 + opaque key) / Storage layout (`~/.olp/keys/<key-id>/manifest.json` + `~/.olp/logs/audit.ndjson`) / Manifest schema (schema_version, token_hash, owner_tier, providers_enabled) / Token format (`olp_<32-byte base64url>`, SHA-256 hash) / Atomic write & audit append (manifest lifecycle-only atomic via tmpfile+fsync+rename; audit per-request append, warn + 1 retry, no memory buffer at Phase 2) / Owner-vs-guest-vs-anonymous gating (config.json `auth.allow_anonymous` default false, no env auto-detection) / Audit ndjson schema (no PII) / Bootstrap & recovery (minimal keygen command surface + `OLP_OWNER_TOKEN` env override with stable `__env_owner__` keyId) / Acceptance criteria (11 test surfaces for D44+) / Node baseline (Option 1 SQLite port rejection rationale citing `engines >=18` + CI 20/24 vs `node:sqlite` v22.5.0 with flag) / Out of scope (Dashboard, quota enforcement, audit query, file locking deferred to Phase 3+) / Future forward (Option 3 hybrid migration trigger + preconditions). - `docs/adr/README.md` index: added ADR 0007 row with one-paragraph summary. - `docs/v1x-roadmap.md` #2: marked **PHASE 2 ACTIVE (no longer deferred)**; "Design ADR (NOT YET RATIFIED)" β†’ "Design ADR (ratified) β†’ ADR 0007"; trigger updated to "already fired 2026-05-25"; code anchors pinned to exact line numbers (cache/store.mjs:77-79/:287, server.mjs:502/:531/:392/:1072/:1101). - `CHANGELOG.md` Unreleased: this entry. - **Fold-in #1 (fresh-context opus reviewer findings, 2 P2 + 3 P3, all polish):** Β§ 6.2 step 1 β€” pin audit serialization timing to after status_code + latency_ms are known (resolves Β§10 #2 testability gap); new Β§ 6.3.5 β€” explicit "no in-process validation cache at Phase 2" rule (resolves Β§10 #6 implicit-contract gap); Β§ 6.1 β€” document deliberate omission of directory fsync after rename (single-process trade-off); Β§ 9.4 β€” token-collision policy between `OLP_OWNER_TOKEN` and filesystem keys declared undefined behaviour; Β§10 #4 β€” test rephrased to assert against config-driven `owner_only_endpoints` rather than hardcoded payload shape. - **Fold-in #2 (maintainer text-review findings, 1 P1 + 1 P2 + 1 P3):** Β§ 6.3 rewritten to `last_used_at` revoke-dominates-touch semantics (P1 β€” fixes safety bug where lazy touch could overwrite revoke and silently clear `revoked_at`, breaking acceptance criterion #6 under concurrent CLI revoke + in-flight server request); Β§ 6.4 reframed from "both states are valid" / "observability-grade" to "revoke dominates touch" with Β§6.3 as the load-bearing discipline; Β§ 10 criterion #7 expanded to test all three orderings (revokeβ†’touch, touchβ†’revoke, interleaved) with explicit MUST: `revoked_at` non-null after revoke regardless of ordering; Β§ 11 forward path step (1) corrected Node version history β€” minimum non-flag-gated baseline is v22.13.0 (LTS) / v23.4.0 (current), RC since v25.7.0, stable TBD (previous wording "Node v22.5.0+ for unflagged but RC" was factually wrong per https://nodejs.org/download/release/v22.12.0/docs/api/sqlite.html and https://nodejs.org/api/sqlite.html); this CHANGELOG entry line-count corrected from "~270 lines" to "~420 lines after fold-ins". - **Test count:** 468 β†’ 468 (design-only, no test change). - **Authority:** Phase 2 kickoff handoff (`~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md` in cc-rules `d9da966`); OLP v0.1 spec Β§ 4.5 (planning authority for `~/.olp/` layout); OCP `keys.mjs` (prior-art for opaque-key + per-key isolation model); Node `node:sqlite` docs (https://nodejs.org/api/sqlite.html β€” Option 1 rejection rationale per ADR 0007 Β§ 11); CC 开发铁律 v1.6 Β§ 10 β€” fresh-context opus reviewer required for design ADR per Iron Rule 10. ### D43-A β€” Phase 2 doc alignment (no code change) Phase 1 was closed at v0.1.1; this commit aligns documentation surfaces to the Phase 2 reality before D43-B (ADR 0007 draft) lands. Pure doc cleanup; no `.mjs` or test changes. - `CLAUDE.md release_kit.current_phase` Phase 1 β†’ Phase 2; `current_pre_release_identifier` `0.1.0-bootstrap` β†’ `0.2.0-phase2`. - `README.md` status header + Implementation Status + Phase plan rewritten to reflect actually-shipped reality (v0.1.0 + v0.1.1 bundled the three Tier-D plugins + cache + fallback into a single Phase 1 milestone, not one phase per plugin as the original v0.1 spec planned). `lib/keys.mjs` row + "Multi-key auth not yet implemented" note updated to "Phase 2 active per ADR 0007 (drafting at D43-B)". - `AGENTS.md` Β§ Key files to know β€” `lib/keys.mjs` πŸ“‹ marker updated to "Phase 2 active per ADR 0007 (drafting at D43-B)"; Implementation-status-note paragraph dated 2026-05-25 + reflects Phase 1 close + Phase 2 active scope. - `ALIGNMENT.md` Β§ Provider Inventory β€” added one-paragraph "Note on phase terminology" clarifying that "Phase" in the Provider Inventory tables + Β§ One-shot Triggered Audits "OpenAI Codex ToS formal pin" refers to the original per-plugin enablement plan, orthogonal to the milestone phase numbering in README. Fold-in for D43-A reviewer P2 finding; no governance-text change, no Speculative-Candidate plugin reclassification. - **Test count:** 468 β†’ 468 (no test change). - **Authority:** `CLAUDE.md release_kit overlay phase_rolling_mode` β€” under Unreleased; Phase 2 kickoff handoff at `~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md`; ADR 0007 forthcoming at D43-B. ## v0.1.1 β€” 2026-05-25 ### Phase 1 cleanup β€” pre-Phase-2 batch (D35–D42, closes 16 of 17 issues) **Overview.** v0.1.1 closes the post-v0.1.0 cleanup batch covering all 17 pre-Phase-2 issues raised during the 6-round cold-audit cycle on the Phase 1 deliverable. 8 D-day commits (D35–D42) shipped between 2026-05-24 and 2026-05-25. 16 issues closed; issue #16 (streaming singleflight) stays OPEN as the v1.x tracker with its design ratified in ADR 0005 Amendment 8. **Test count: 416 (v0.1.0) β†’ 468 (v0.1.1).** +52 tests across the cleanup batch. ### D35 β€” pre-Phase-2 batch #1 (issues #4 #9 #10 #11 #12) - **#4 β€” X-OLP-Latency-Ms uniform.** Audit confirmed already-correct via D32; D35 adds the `#4-audit` regression test pinning the 5-header invariant on the 503 no-provider sendError so future drift is caught immediately. - **#9 β€” Streaming empty-then-clean-exit headers.** Zero-chunk streaming path now guards `!res.headersSent` and emits Content-Type=text/event-stream, Cache-Control=no-cache, Connection=keep-alive, X-Accel-Buffering=no, plus all 5 X-OLP-* headers via olpHeaders before writing `SSE_DONE`. Zero-chunk path correctly does NOT cache. - **#10 β€” Streaming post-first-chunk error truncation marker.** Two sibling fixes: catch-block-firstChunkEmitted=true and error-chunk-after-first-chunk both now emit synthetic `{type:'stop', finish_reason:'length'}` via `irChunkToOpenAISSE` + `SSE_DONE` + `res.end()`. Per ADR 0004 Β§ Fallback safety: post-first-chunk truncation surfaces as `length` finish, never a hang. - **#11 β€” `validateIRRequest` irVersion strict check.** ADR 0003 IR contract pins irVersion to `'1.0'`. Validator now: `obj.irVersion !== undefined && obj.irVersion !== '1.0'` β†’ rejection. Strict string match β€” `undefined` accepted (back-compat), `'1.0'` accepted, `'2.0'` rejected, numeric `1.0` rejected (`1.0 !== '1.0'`). - **#12 β€” `alignment.yml` scripts/** trigger removal.** Removed from both `push.paths` and `pull_request.paths` since the `scripts/` directory does not currently exist (planned for Phase 7). - **Test count:** 416 β†’ 424 (+8). ### D36 β€” pre-Phase-2 batch #2 (issues #2 #5 #6 #13 #14 #15) - **#2 β€” cache_control partial-noop debug log.** `server.mjs handleChatCompletions` fires `logEvent('debug', 'cache_control_partial_noop', { chain, marker_count })` at most once per request when markers present AND chain has at least one non-Anthropic hop. Per ADR 0005 Β§ D2. - **#5 β€” ADR 0002 vibe.mjs β†’ mistral.mjs.** Β§ Decision filesystem layout corrected to match the shipped file naming convention (file named after provider key, not CLI binary). Amendment 5 documents the correction + makes the convention statement explicit for future contributors. - **#6 β€” mistral.mjs A5 flip + ALIGNMENT.md table update.** Header A5 (model flag) flipped from `UNPINNED-D-later-verifies` to `CONFIRMED-NOT-APPLICABLE` with DeepWiki citation; ALIGNMENT.md Speculative-Candidate table mistral row updated to remove A5. - **#13 β€” /v1/models alias governance.** ALIGNMENT.md gains "Controlled deviations (entry-surface scope)" subsection documenting the alias surface as a controlled Rule 2(b) deviation; `docs/openai-spec-pin.md` gains the alias-surfacing subsection with full 4-field contract table. - **#14 β€” cache_control slot determinism regression test.** 4 tests in test-features.mjs construct hand-built IRs with synthetic markers (bypassing openAIToIR which strips them at v0.1) and verify the cache key SHA-256 is deterministic. Per ALIGNMENT.md Rule 2 (No Invention), no `sortMarkers` helper shipped β€” the slot is dead-code at v0.1. - **#15 β€” Anthropic v2.1.89 transcript artifact.** New file `docs/provider-audits/anthropic.md` as a single living version-capture artifact. Records observed `claude --version` (2.1.132 at capture date 2026-05-24), pinned version (v2.1.89 from D4), drift note, sample invocation, flag-surface table for 5 OLP-consumed flags. Closes the circular ALIGNMENT.md ↔ plugin header citation by anchoring on an external artifact. - **Test count:** 424 β†’ 431 (+7). ### D37 β€” release.yml phase_rolling_mode gate (issue #17) - **CI gate enforcing phase_rolling_mode promotion discipline.** New "Enforce phase_rolling_mode (Unreleased must be promoted)" step in `release.yml` between the version-match check and the CHANGELOG extraction step. Awk extracts content between `## Unreleased` and the next `## ` heading; sed strips blank lines and parenthetical-sentinel-only lines. Non-trivial remaining content fails the workflow with `::error::` instructing the maintainer to promote Unreleased β†’ `## v<version>` per CLAUDE.md release_kit.phase_rolling_mode. - **Dry-run validated against 4 cases:** current sentinel-only Unreleased β†’ PASS; synthetic non-trivial Unreleased β†’ FIRES with offending lines reported; no Unreleased section β†’ PASS; multi-sentinel + blank lines β†’ PASS. - **Gate is purely additive** β€” fires only on tag push to `v*.*.*`, does not affect normal push/PR CI. - **Test count:** 431 β†’ 431 (no test change β€” CI workflow only). ### D38 β€” maxConcurrent runtime enforcement (issue #1) - **Spawn lifecycle gate** β€” `hints.maxConcurrent` is now enforced at runtime per ADR 0002 Amendment 6: `lib/providers/index.mjs` exports a per-provider `tryAcquireSpawn` / `releaseSpawn` / `getActiveSpawnCount` semaphore; `server.mjs` gates both the buffered and streaming spawn call sites in `handleChatCompletions` with a try/finally release. Saturation surfaces as `ProviderError(CONCURRENCY_LIMIT)` which the fallback engine treats as a hard trigger (ADR 0004 Amendment 4) β€” the chain advances to the next hop instead of queueing. If the entire chain is saturated, the user receives a chain-exhausted error via the existing exhaustion path. Closes #1. Queue+timeout deferred (see ADR 0002 Amendment 6 Β§ Design choice). Test count 431 β†’ 447. - **Spawn lifecycle gate** β€” `hints.maxConcurrent` is now enforced at runtime per ADR 0002 Amendment 6: `lib/providers/index.mjs` exports a per-provider `tryAcquireSpawn` / `releaseSpawn` / `getActiveSpawnCount` semaphore; `server.mjs` gates both the buffered and streaming spawn call sites in `handleChatCompletions` with a try/finally release. Saturation surfaces as `ProviderError(CONCURRENCY_LIMIT)` which the fallback engine treats as a hard trigger (ADR 0004 Amendment 4) β€” the chain advances to the next hop instead of queueing. If the entire chain is saturated, the user receives a chain-exhausted error via the existing exhaustion path. Closes #1. Queue+timeout deferred (see ADR 0002 Amendment 6 Β§ Design choice). Test count 431 β†’ 447. ### D39 β€” D16 follow-ups (issue #3): explicit cache delete + eviction log + SPAWN_TIMEOUT asymmetry doc - **Part 1 β€” `CacheStore.delete(keyId, cacheKey)`** β€” adds an explicit eviction primitive to `lib/cache/store.mjs`. Returns `boolean` (true if entry present and removed; false otherwise) and removes empty per-keyId namespace `Map` entries from the outer store for memory hygiene (matches the D38 `_activeSpawns` pattern). `server.mjs` D16 salvage path replaces `cacheStore.set(..., ttlMs=0)` (lazy tombstone that lived in the namespace `Map` until the next `get`/`peek` purged it) with `cacheStore.delete(...)` (immediate removal). Cache semantics unchanged β€” truncated responses still don't persist. ADR 0005 Β§ "Cache write conditions" item 1 authority. - **Part 2 β€” `cache_evicted_truncated` observability log** β€” adds an `info`-level structured log event fired immediately after the D16 eviction in `executeHopFn`. Carries `{ provider, model }` so dashboards can surface salvage frequency per (provider, model) pair. P3 polish; no semantic change. - **Part 3 β€” sticky-cache regression test** β€” defense-in-depth test asserting two consecutive identical buffered requests that both trigger SPAWN_FAILED-with-chunks salvage each invoke a fresh spawn (spawnCount=2 across the two requests; second request reports `X-OLP-Cache: miss`). Catches any future regression where the eviction is dropped or the gate condition flips. - **Part 4 β€” SPAWN_TIMEOUT salvage asymmetry documented (no code change)** β€” ADR 0004 Amendment 1 gains a new sub-section "Why SPAWN_TIMEOUT is excluded from salvage" with a 4-point rationale: (1) SPAWN_FAILED is a terminal signal, SPAWN_TIMEOUT is a deadline signal; (2) the next hop is a different provider with different speed characteristics, plausibly full-response-soon-after-T; (3) the "user paid for partial" framing applies to SPAWN_FAILED only β€” for SPAWN_TIMEOUT the user paid for "result within T"; (4) code inspection confirms the catch block matches only `code === 'SPAWN_FAILED'`. Includes hard-trigger-taxonomy completeness note and v1.x re-evaluation trigger (opt-in salvage-on-timeout for long deadlines). - **Authority:** ADR 0005 Β§ Cache layer / CacheStore API extension (Part 1); ADR 0004 Amendment 1 (Part 4); GitHub issue #3 β€” closed by this commit; D16 commit `bafa6d1` non-blocking suggestions β€” batched here. - **Test count:** 447 β†’ 452 (3 unit tests for `CacheStore.delete` + 1 log-event integration test + 1 sticky-cache regression test). ### D40 β€” `X-OLP-Fallback-Detail` header (issue #7) - **New debug header on responses with a non-empty failure trail** β€” `lib/fallback/engine.mjs#executeWithFallback` now returns a `fallbackDetail` array of per-hop tuples on every code path. `server.mjs` emits `X-OLP-Fallback-Detail: <JSON-stringified array>` on any response where at least one hop failed before the chain resolved or exhausted (chain-exhausted, non-trigger-error, client-error, AUTH_MISSING, and success-with-prior-failure paths). Header is absent on clean primary success (no failure trail to report). - **Tuple schema** β€” `{ hop, provider, model, code, error_message, trigger_type }` per failed hop. `code` is the `ProviderError` code or `'UNKNOWN'` for non-`ProviderError` exceptions; `error_message` is truncated to 200 chars with a U+2026 ellipsis on truncation; `trigger_type` matches D28's `classifyTrigger` output (`'hard'` / `'soft'` / `'auth_missing'` / `'client_error'` / `'non_trigger'`). Field shapes reuse D28's per-hop structured log event keys so logs and the header pivot on the same surface. - **4KB UTF-8 byte cap** β€” if the JSON-stringified array exceeds 4096 bytes, tail tuples are dropped and a `{ truncated: true, omitted_hops: N }` sentinel is appended such that the total fits under the cap. Cap calculation uses `Buffer.byteLength('utf8')`, not string length. - **RFC 7230 hygiene** β€” non-ASCII code points (e.g. the em dash in the D38 `CONCURRENCY_LIMIT` synthesised error message) are escaped as `\uXXXX` so the header value is pure ASCII. Node's HTTP header validator rejects multi-byte UTF-8 in field values; without this step, em-dash-bearing error messages would crash `res.writeHead`. `JSON.parse` round-trips the escaped form correctly. - **Gating posture β€” ungated at v0.1** β€” the original ADR 0004 Β§ Chain advancement step 4 specified owner-only gating. Per the maintainer decision in issue #7, v0.1 ships the header **ungated** (single-tenant family-scale per ALIGNMENT.md; no PII risk in error details). **Phase 2 will re-introduce owner-vs-non-owner gating when `lib/keys.mjs` lands** β€” explicit follow-up tracked in AGENTS.md Β§ Key files to know and ADR 0004 Amendment 5. - **Authority:** ADR 0004 Β§ Decision Β§ Chain advancement step 4 (original promise β€” D40 fulfils it); ADR 0004 Amendment 5 (D40 ratification); D18 (5 standard X-OLP-* headers; D40 builds on the convention); D28 (per-hop structured log fields; D40 reuses the field shapes); GitHub issue #7 β€” closed by this commit. - **Test count:** 452 β†’ 468 (7 engine-level tuple-shape tests + 6 serialiser unit tests including the 4KB cap + non-ASCII regression + 3 HTTP integration tests). ### D41 β€” `X-OLP-Provider-Used` semantics documented (issue #8) - **Doc-only clarification.** On a chain-exhausted response, `X-OLP-Provider-Used` identifies the chain's configured primary entry (`chain[0].provider`), not necessarily the first hop where `spawn()` was actually invoked. At v0.1 this is unobservable because soft triggers are deferred (ADR 0004 Amendment 2) β€” every hop is attempted in order, so chain-origin and first-attempted are equivalent. When soft triggers reactivate in v1.x, a soft-skipped hop 0 followed by hard-failed hops 1+N would still report `providerUsed=chain[0]` despite chain[0] never being spawned. - **Option B (document chain-origin) chosen over Option A (track `firstAttemptedProvider`).** Rationale: Option A would add state to `executeWithFallback` for an unreachable v0.1 code path (ALIGNMENT.md Rule 2 β€” No Invention). The D40 `X-OLP-Fallback-Detail` header already carries precise per-hop spawn history (including soft-skip records with `trigger_type: 'soft'`), so the disambiguation channel exists on the wire without needing `providerUsed` to handle it. - **Updates:** ADR 0004 Amendment 6 documents the semantics; `README.md` Β§ Observability headers replaces "which provider's plugin served the request" with the chain-origin wording; `lib/fallback/engine.mjs` chain-exhausted return site gains an inline comment citing the amendment and the v1.x re-evaluation note. - **No code-behavior change. No new tests** β€” the relevant scenario is dead-by-config at v0.1; the v1.x soft-trigger reactivation work should add a test that exercises the soft-skip + chain-exhausted edge case and pins whichever option the v1.x maintainer chooses (the amendment names Option A as the likely v1.x preference). - **Authority:** ADR 0004 Amendment 6 (this commit); ADR 0004 Β§ Decision Β§ Chain advancement step 4; ADR 0004 Amendment 2 (soft triggers deferred β€” precondition); ADR 0004 Amendment 5 (per-hop attribution channel via `X-OLP-Fallback-Detail`); ALIGNMENT.md Rule 2 (No Invention rationale); GitHub issue #8 β€” closed by this commit. - **Test count:** 468 β†’ 468 (no test change). ### D42 β€” Streaming singleflight design ADR + v1.x roadmap (issue #16) - **Design-only ratification of the v1.x streaming singleflight implementation.** ADR 0005 Amendment 6 (D34) had deferred this work with a "design alone warrants a dedicated ADR" note. D42 fulfils the note as ADR 0005 Amendment 8, ratifying the `cacheStore.getOrComputeStreaming(...)` API shape, per-(keyId, cacheKey) inflight Map, tee fan-out with bounded per-client backpressure queues, late-joiner replay buffer, AbortController propagation on all-disconnect, D38 `tryAcquireSpawn` coordination (only the first caller's spawn counts against the semaphore), cache TTL race handling, the new `STREAM_BACKPRESSURE` error code (NOT a hard trigger), and the new `X-OLP-Streaming-Inflight: source | attached | solo` header. Implementation acceptance criteria are enumerated in Amendment 8 Β§13. - **Multi-layer safeguards to ensure the v1.x work is not forgotten.** New file `docs/v1x-roadmap.md` is a single living landing page for every Phase-1 deferral (streaming SF, multi-key auth, soft-trigger reactivation, `/health` activeSpawns, provider-level `cacheKeyFields`, streaming-path SPAWN_FAILED salvage, D40 AUTH_MISSING tuple test). Each entry names the ratifying ADR, the load-bearing code anchor, and a concrete trigger to start. Cross-references added at: `lib/cache/store.mjs#getOrCompute` JSDoc (sibling API TODO), `server.mjs` streaming-branch entry (~line 810, the peek+spawn pattern Amendment 8 replaces), `README.md Β§ Known limitations` (user-facing surface), and `docs/adr/0005-cache-cross-provider.md` Amendment 8 Β§ "Cross-references and safeguards". - **Issue #16 status.** STAYS OPEN as the v1.x implementation tracker. The body of the issue is updated post-D42 to reference Amendment 8 and clarify scope ("design ratified; implementation pending"). DO NOT close the issue until Amendment 8 Β§13's test surface is green against an actual implementation. - **No code-behavior change. No new tests.** Amendment 8 is design-only. The implementation will go through full Iron Rule 10 (fresh-context opus reviewer + acceptance-criteria-gated test pass) when the v1.x sprint kicks off. - **Authority:** ADR 0005 Amendment 8 (this commit); ADR 0005 Amendment 6 (D34 β€” original deferral note); GitHub issue #16 (round-6 F13 β€” sibling TOCTOU); ADR 0002 Amendment 6 (D38 β€” `tryAcquireSpawn` semantics that Β§7 coordination builds on); ADR 0004 Amendment 5 (D40 β€” observability pattern Β§11 extends); `CLAUDE.md` release_kit_overlay phase_rolling_mode β€” under Unreleased; CC 开发铁律 v1.6 Β§ 10.x (design-only amendment; fresh-context reviewer not required per the Iron Rule 10 implementation-phase scope, documented in the amendment's procedural mechanism). - **Test count:** 468 β†’ 468 (no test change β€” design-only). ### Phase 1 cleanup release_kit checklist - [x] All 8 D-day deliverables landed on main (D35-D42) - [x] CI green on every D-day commit + on this release commit's head - [x] Cold-audit round 7 (fresh-context opus full-pass) β€” PASS_WITH_MINOR, 0 P1/P2 findings - [x] 16 of 17 pre-Phase-2 GitHub issues closed (#1-#15 and #17); #16 stays OPEN as v1.x tracker - [x] Issue #16 status comment posted referencing ADR 0005 Amendment 8 design ratification - [x] CHANGELOG "Unreleased" promoted to "## v0.1.1 β€” 2026-05-25" with D35-D42 entries - [x] `package.json` bumped from 0.1.0 β†’ 0.1.1 - [x] `docs/v1x-roadmap.md` created β€” 7 deferred items with anchors + start triggers - [ ] Tag pushed (next step in this PR's lifecycle) - [ ] `release.yml` triggered + GitHub Release created (auto on tag push; D37 phase_rolling_mode gate will pass because Unreleased is now sentinel-only) ### Known limitations carried to v1.x Full list with code anchors + start triggers in [`docs/v1x-roadmap.md`](./docs/v1x-roadmap.md): - Streaming-path singleflight (issue #16, ADR 0005 Amendment 8 design ratified) - Multi-key auth (`lib/keys.mjs`) - Soft-trigger reactivation (ADR 0004 Amendment 2) - `/health` activeSpawns integration (ADR 0002 Amendment 6 forward note) - Provider-level `cacheKeyFields` mask (ADR 0005 Amendment 7 forward note) - Streaming-path SPAWN_FAILED salvage (bundled with #1 in v1.x) - D40 AUTH_MISSING tuple test coverage (test polish) ## v0.1.0 β€” 2026-05-24 ### Phase 1 Close β€” Multi-provider proxy core **Overview.** Phase 1 delivers the OLP minimum-viable multi-provider proxy: OpenAI-compatible HTTP entry surface, plugin architecture for 3 Tier-D providers (Anthropic Claude / OpenAI Codex / Mistral Vibe), cache layer (D1 per-key isolation + D4 buffered-path singleflight + size cap + cacheable opt-out), fallback engine with first-chunk safety + spawn-timeout hard trigger + structured per-hop log observability, IR↔OpenAI translation honoring the Rule 2(b) no-invention constraint, and a 416-test suite covering all of it. Released under `phase_rolling_mode` (CLAUDE.md release_kit overlay): 25 D-day commits accumulated on `main` between 2026-05-23 and 2026-05-24 before this version bump + tag. **Provider posture.** Three Tier D plugins ship as **Candidate** (per ALIGNMENT.md Β§ Provider Inventory) β€” runnable via `providers.enabled` config but not Enabled by default. Five additional Tier B/C plugin slots exist in `models-registry.json` as Speculative-Candidate / candidate stubs awaiting CLI authority pins. Zero Enabled providers at v0.1; transition to Enabled requires Phase audit + primary-source pin per ADR 0002. ### What landed (D10–D34 commit index) The per-commit detail is in the git log; this index summarizes the deliverables. **Phase 1 core hardening:** - **D10** (`2cfd0b1`) β€” P1 round-3: providers.enabled config wiring + real SSE streaming on single-hop cache-miss + spawn-timeout hard trigger across all 3 plugins. **Round-1 fold-in batch (cold audit caught 17 findings):** - **D11** (`f659e29`) β€” ADR 0002 Amendment 1: `maxSpawnTimeMs` ratified into Provider contract hints. - **D12** (`4b1a9c8`) β€” IR translator Rule 2(b) compliance: removed invented top-level `error` field on `chat.completion` shapes. - **D13** (`f34b690`) β€” Per-hop `cache_control` bypass evaluation (was request-global). - **D14** (`a7085d9`) β€” Defer `res.writeHead(200)` until first chunk; early-error returns 502 JSON instead of 200 empty SSE. - **D15** (`8ae77c3`) β€” ADR 0005 Amendment 2: cache key includes `max_tokens` / `top_p` / `stop` / `tool_choice`. - **D16** (`bafa6d1`) β€” ADR 0004 Amendment 1: SPAWN_FAILED-with-chunks salvage (don't discard partial responses). - **D17** (`cb86807`) β€” Alias routing SPOT via `models-registry.json`; `getProviderForModel` canonicalizes. - **D18** (`82ff007`) β€” `/v1/models` populated from registry; 5 standard X-OLP-* headers on error responses. - **D19** (`ed82e65`) β€” Cleanup batch: finish_reason validator, dead alignment.yml KNOWN_PROVIDERS removal, unused imports. - **D20** (`d85a2dc`) β€” Docs drift: README/AGENTS/ADR forward-references annotated `πŸ“‹ Planned`. **Round-2 fold-in batch (13 findings):** - **D21** (`1466d3a`) β€” `validateProvider` enforces `maxSpawnTimeMs` contract field. - **D22** (`e10b7d7`) β€” ADR 0004 Amendment 2: soft triggers deferred to v1.x. - **D23** (`7ef5510`) β€” `hints.cacheable` opt-out + 10MB cache entry size cap (ADR 0002 Amendment 3, ADR 0005 Amendment 3). - **D24** (`f8348ad`) β€” Spawn-timeout race fix: post-loop `if (spawnTimedOut) throw SPAWN_TIMEOUT` closes the rejectNext-null window across all 3 plugins. - **D25** (`cd391b1`) β€” Round-2 P3 docs batch. **Round-3 fold-in batch (13 findings):** - **D26** (`a281d3e`) β€” Soft-trigger startup warning, stderr propagation on error-chunk SPAWN_FAILED (codex+mistral), anthropic D4-observation header, streaming truncation marker. - **D27** (`c3ba751`) β€” IR validator response_format + tool_choice checks, ADR 0005 Amendment 4 (cache_control IR vs body), `/v1/models` alias surfacing. - **D28** (`4a238c9`) β€” Per-hop log observability: `chain_id`, `trigger_type`, `ir_request_hash`, `next_provider` on all 8 fallback log events. - **D29** (`de9f3ca`) β€” Suite 17 port-collision flake fix: 16 test sites switched to OS-assigned `listen(0)`. - **D30** (`5119b42`) β€” README env vars correctness, `docs/openai-spec-pin.md` v0.1 baseline. - **D31** (`d6347e3`) β€” ADR amendment trio: F5 (ADR 0003 Amendment 1 substitute test strategy), F11 (ADR 0005 Amendment 5 Anthropic wire limitation), F13+F14 (ALIGNMENT.md Speculative-Candidate exception class). **Round-4 fold-in batch (10 findings):** - **D32** (`30de965`) β€” Provider auth env vars in README, X-OLP-* on early-return paths, ADR 0002 Amendment 4 ratifying `contractVersion`, dead OUTPUT_PARSE_ERROR removal, codex parser inline assumption labels. **Round-5 fold-in batch (12 findings):** - **D33** (`f784fdb`) β€” ALIGNMENT mistral `--output streaming` pin correction, deterministic `function_call` ID (cache key stability), `/health` per-provider snapshot, fallback-hop cache-hit X-OLP-Cache correctness, `CLAUDE.md` `phase_rolling_mode` policy formalization, `/v1/models` stable `created` timestamps. **Round-6 final batch (14 findings; 4 closed, 9 filed as issues):** - **D34** (`60570ef`) β€” ADR 0005 Amendment 6 (streaming singleflight v1.x deferral), array-field cache key normalization (`tools:[]` / `stop:[]` now collide with omitted), QUOTA_EXHAUSTED + RATE_LIMITED dead code removal (ADR 0004 Amendment 3), ADR 0005 Amendment 7 (conservative cache-key v0.1 trade-off). ### ADRs in scope - **ADR 0001** β€” Project founding (Phase 1 founding doc; no amendments) - **ADR 0002** β€” Plugin architecture (4 amendments β€” `maxSpawnTimeMs`, `cacheable`, `contractVersion` ratifications) - **ADR 0003** β€” IR design (1 amendment β€” `__irRoundTripTest` removal + substitute test strategy) - **ADR 0004** β€” Fallback engine (3 amendments β€” SPAWN_FAILED salvage, soft trigger deferral, hard-trigger taxonomy narrowing) - **ADR 0005** β€” Cache layer (7 amendments β€” cache key expansions, cache_control IR-vs-body, cacheable + size cap, Anthropic wire limitation, streaming singleflight deferral, conservative cache-key v0.1 trade-off) - **ADR 0006** β€” Provider inclusion (Tier framework; no amendments) - **ALIGNMENT.md** β€” Speculative-Candidate plugin Rule 4 exception class added (D31) - **CLAUDE.md** β€” `phase_rolling_mode` overlay added (D33) - **`docs/openai-spec-pin.md`** β€” v0.1 baseline pinned (D30) ### Test growth 277 (pre-D10) β†’ 416 (post-D34). 6 cold audit rounds reviewed code against ADR claims. Iron Rule v1.6 Β§ 10.x dual-mode review discipline (Diff Review + Cold Audit) caught 78+ findings of which ~50 closed via implementation and ~28 deferred to GitHub issues. ### Known limitations carried to v1.x 17 GitHub issues filed for follow-up. Notably: - **Streaming singleflight** (#16) β€” multi-concurrent identical streaming requests each spawn fresh CLI; buffered path participates in D4, streaming path doesn't (deferred via ADR 0005 Amendment 6). - **maxConcurrent runtime enforcement** (#1) β€” declarative-only at v0.1. - **X-OLP-Fallback-Detail debug header** (#7) β€” documented in ADR 0004, never emitted. - **Soft triggers** (per ADR 0004 Amendment 2) β€” evaluation code exists but `quotaStatus()` polling not wired; configured thresholds inert at v0.1. ### Migration from OCP OLP supersedes OCP per ADR 0001. The `scripts/migrate-from-ocp.mjs` migration tool is πŸ“‹ Planned (Phase 7). ## v0.1.0-bootstrap β€” 2026-05-23 ### Phase 0 β€” Repo bootstrap (founding + post-codex-review hardening) This is the founding commit set of OLP (Open LLM Proxy), a personal- and family-scale multi-provider LLM proxy that supersedes OCP. The trigger was Anthropic's 2026-05-14 announcement (effective 2026-06-15) splitting `claude -p` / Agent SDK / third-party agent traffic out of the Pro/Max subscription pool into a separate fixed monthly Agent SDK Credit pool. **What lands at v0.1.0-bootstrap (final state on `main` as of 2026-05-23):** - `ALIGNMENT.md` β€” OLP constitution. Three concurrent authorities (per-provider CLI / OpenAI spec / IR contract), 5 Rules, 4-tier Risk Tier Framework, Candidate-vs-Enabled provider inventory, one-shot triggered audits (2026-06-16 Anthropic post-split; 90-day Antigravity primary-source pin). - `AGENTS.md` β€” multi-tool agent guidelines (inherits `~/.cc-rules/AGENTS.md`). - `CLAUDE.md` β€” Claude-Code-specific session instructions + machine-readable `release_kit` overlay (Iron Rule 5.5). - `README.md` β€” phase-aware skeleton with Candidate-vs-Enabled provider tables, API endpoint table, environment-variables table, response-headers spec, architecture overview, phase plan, migration-from-OCP outline. Placeholder content marked as such per phase. - `docs/adr/` β€” 6 founding ADRs: - `0001-project-founding.md` β€” Mission, non-mission, narrow-scope supersession of OCP ADR 0005 (single-provider-sufficiency premise only; BYOK / no-spawn parts of ADR 0005 not inherited). - `0002-plugin-architecture.md` β€” `lib/providers/<name>.mjs` plug-in model with the Provider contract (name / models / auth / spawn / estimateCost / quotaStatus / healthCheck / hints). 8 candidate providers declared, 0 Enabled at v0.1. - `0003-intermediate-representation.md` β€” OLP-internal canonical IR between OpenAI-compat entry and provider plugins. - `0004-fallback-engine.md` β€” Trigger taxonomy (Hard / Soft / Deterministic-deferred / Cost-aware-deferred), idempotent-failure safety (first-chunk rule), chain advancement one-at-a-time, observability headers. - `0005-cache-cross-provider.md` β€” Cache key composition over `(provider, model, messages, ...)`, D1+D2+D3+D4 port from OCP v3.13.0. - `0006-provider-inclusion.md` β€” 4-tier Risk Framework, Candidate-vs-Enabled distinction, 8-provider candidate classification, Antigravity Tier A (evidence-backed, pending primary-source pin) β€” exclusion rests on (named prohibition + no cost advantage + reinstatement friction) combination; primary-source URL not yet pinned, follow-up tracked. - `.github/PULL_REQUEST_TEMPLATE.md` β€” 8-radio Change Type taxonomy + per-type Authority Evidence sections + Iron Rule 10 reviewer checklist. - `.github/workflows/alignment.yml` β€” CI blacklist (transitive `api.anthropic.com/api/oauth/usage` from OCP 2026-04-11 drift; Antigravity provider exclusion enforcement) + `models-registry.json` validator + commit-citation soft check (process-substitution form, no Bash subshell trap). - `.github/workflows/release.yml` β€” Auto-release on tag push with `package.json`-vs-tag version match check (Iron Rule 5). - `.github/workflows/test.yml` β€” Node 20/24 matrix; tolerates bootstrap-phase absence of `test-features.mjs` AND `scripts.test`. - `models-registry.json` β€” minimal v0.1 stub with empty `providers: {}`, matching the 0-Enabled posture; populated by Phase audits as providers transition Candidate β†’ Enabled. - `package.json` β€” minimal: no `main`, no `scripts.test`, no `scripts.start` (those entries land alongside the real files in Phase 1). - `.gitignore`, `LICENSE` (MIT), `CHANGELOG.md` β€” standard project boilerplate. **Provider posture at v0.1.0-bootstrap (per ALIGNMENT.md Β§ Provider Inventory):** | Tier | Anticipated providers | v0.1 default state | |---|---|---| | D (eligible-for-default-enabled) | Anthropic, OpenAI Codex, Mistral Vibe | Candidate (transition gate: authority pin + plugin + Phase audit) | | C (opt-in) | xAI Grok, Moonshot Kimi | Candidate | | B (opt-in + consent) | MiniMax, Zhipu GLM, Alibaba Qwen | Candidate | | A (excluded by default; constitutional-amendment-only re-inclusion) | Google Antigravity | Excluded; pending primary-source pin | **Total Enabled at v0.1.0-bootstrap: 0.** Enablement is a Phase audit deliverable, not a bootstrap claim. This explicit zero is intentional and codified β€” a constitution that names providers as "default-enabled" while their CLI versions, output shapes, auth artifacts, and exit-code semantics are still TBD would violate Rules 1 (Cite First) and 3 (Match the Implementation). **Review history for this version:** 1. **Initial internal review (Claude Opus, fresh-context, Iron Rule 10).** Verdict: APPROVE_WITH_MINOR β€” 2 minor items (alignment.yml heredoc indent breaking bash parse on failure path; AGENTS.md cross-reference to ADR 0003 imprecise). Both folded in before the founding commit. 2. **External review #1 (OpenAI Codex CLI, no spec framing).** Verdict: 6 substantive findings beyond internal review. - Provider Inventory split into Candidate vs Enabled (the v0.1 constitution had declared `anthropic` / `openai` / `mistral` as Tier D default-enabled while their Authority pins were still `TBD at Phase N spawn` β€” direct violation of Rule 1 / Rule 3 against the constitution's own text). - Antigravity Tier A downgraded to "evidence-backed, pending primary-source pin" (secondary reports disagree on blast radius; Google FAQ URL not yet primary-source-pinned). - ADR 0001 supersession scope narrowed (OLP rejects ADR 0005's "BYOK + no spawn" qualifiers, which originally applied to a commercial pivot; OLP is non-commercial and spawn-binary by design). - Anthropic post-2026-06-15 one-shot audit scheduled (annual May 14 audit would leave Anthropic re-eval ~year late after the split takes effect). - Tier A "permanent" language unified across docs (constitution and ADR 0006 had disagreed). - OpenAI Tier D wording softened ("maintainer signal indicates low risk; formal ToS pin pending" β€” Discussion #8338 is a posture statement, not a formal ToS blessing). 3. **External review #2 (OpenAI Codex CLI, second pass after review #1 fold-in).** Verdict: 6 additional substantive findings β€” the self-consistency trap recurred when fold-in of review #1 was scoped only to files codex explicitly named. Round #2 caught: - ADR 0002 still claimed "three default-enabled" while ALIGNMENT.md said zero Enabled β€” accepted ADR contradicting constitution. - `release.yml` would publish stale `## v0.1.0-bootstrap` notes that ignored the "Unreleased" amendments β€” fixed by consolidating amendments into the v0.1.0-bootstrap section (this entry). - `package.json` advertised `main` / `scripts.test` / `scripts.start` for files that don't exist β€” `npm test` / `npm start` failed locally. Removed all three; will return in Phase 1 alongside the real files. - `models-registry.json` documented as SPOT but missing β€” minimal stub added. - `alignment.yml` commit-citation soft check had a Bash subshell trap (`while` in pipe loses `WARN=1` mutation) β€” fixed via process substitution `< <(...)`. - Tier A "permanent" wording still inconsistent across `alignment.yml` workflow text, ADR 0006 Consequences section, and the rest of the docs β€” unified throughout. All 6 round-#2 findings folded in this consolidated v0.1.0-bootstrap state. **Reviewer framing learning (recorded permanently in `~/.cc-rules/memory/learnings/ai_reviewer_self_consistency_trap.md`):** Internal AI reviewers framed on a shared source-of-truth miss bugs in the source-of-truth itself. The self-consistency trap recurred during the fold-in of round #1 β€” when an external reviewer surfaces findings, the fold-in must grep the entire repo for the same concept, not only edit the files the reviewer named. Round #2 caught what round #1's fold-in missed for exactly this reason. Both lessons updated in the cross-machine memory. **Iron Rule 10 status:** Satisfied. Initial reviewer = internal opus (independent from drafters). Round #1 reviewer = external codex (independent from drafters and from internal opus). Round #2 reviewer = external codex (independent from the round #1 fold-in implementer). The maintainer's role across all three reviews was approver, not author. The drafting agents and fold-in agents were never the same as the reviewers for any of the three passes. **Next:** Phase 1 lands `server.mjs` skeleton + IR + Anthropic provider plugin + cache D1+D4 port from OCP. At that point, `package.json` regains `main` + `scripts.test` + `scripts.start`, `test-features.mjs` lands, `models-registry.json` populates its first `providers.anthropic` entry, and Anthropic transitions Candidate β†’ Enabled. Per spec Β§6 phase plan.