diff --git a/AGENTS.md b/AGENTS.md index 8455fa0..f6ff206 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,7 +37,7 @@ Runtime: Node.js (ESM, `.mjs` throughout). No build step. No bundler. `server.mj - `lib/ir/` β€” Intermediate Representation definition + serializers. Governed by ADR 0003. - `lib/cache/` β€” content-addressed cache layer (per-key isolation, `cache_control` bypass, chunked stream replay, singleflight). Governed by ADR 0005. - `lib/fallback/` β€” fallback engine (trigger detection, chain advancement, idempotent-failure safety, header annotation). Governed by ADR 0004. -- `lib/keys.mjs` β€” multi-key auth, per-key namespacing, audit log. Carries OCP's per-key isolation model into OLP. **πŸ“‹ Planned (Phase 2) β€” not yet authored.** +- `lib/keys.mjs` β€” multi-key auth, per-key namespacing, audit log. Carries OCP's per-key isolation model into OLP. **πŸ“‹ Phase 2 active per ADR 0007 (drafting at D43-B) β€” not yet authored.** - `dashboard.html` β€” owner-only multi-provider dashboard (quota panels, fallback rate, cache hit rate). **πŸ“‹ Planned (Phase 6) β€” not yet authored.** - `models-registry.json` β€” single source of truth for `(provider, model) β†’ metadata`. SPOT. - `ALIGNMENT.md` β€” the constitution. Binding for any plugin / entry-surface / IR change. @@ -45,7 +45,7 @@ Runtime: Node.js (ESM, `.mjs` throughout). No build step. No bundler. `server.mj - `.github/workflows/alignment.yml` β€” CI blacklist grep + per-provider citation soft check; fails the build on known-hallucinated tokens. - `CLAUDE.md` β€” Claude-Code-specific session instructions + `release_kit` overlay (Iron Rule 5.5). -**Implementation status note (as of 2026-05-24):** Files marked πŸ“‹ above are designed and documented but not yet on disk. For the full status table see `README.md Β§ "Implementation status"`. Do not attempt to read or import these files β€” they will not be found. The shipped set as of Phase 1 is: `server.mjs`, `lib/ir/`, `lib/providers/{anthropic,codex,mistral}.mjs`, `lib/cache/{keys,store}.mjs`, `lib/fallback/engine.mjs`, `models-registry.json`, `test-features.mjs`. +**Implementation status note (as of 2026-05-25):** Files marked πŸ“‹ above are designed and documented but not yet on disk. For the full status table see `README.md Β§ "Implementation status"`. Do not attempt to read or import these files β€” they will not be found. The shipped set as of Phase 1 close (v0.1.1, 2026-05-25) is: `server.mjs`, `lib/ir/`, `lib/providers/{anthropic,codex,mistral}.mjs`, `lib/cache/{keys,store}.mjs`, `lib/fallback/engine.mjs`, `models-registry.json`, `test-features.mjs`. Phase 2 active scope: `lib/keys.mjs` per ADR 0007 (drafting at D43-B). --- diff --git a/ALIGNMENT.md b/ALIGNMENT.md index bc99585..43f7ecb 100644 --- a/ALIGNMENT.md +++ b/ALIGNMENT.md @@ -124,6 +124,8 @@ OLP distinguishes **Candidate Providers** (declared in this constitution as inte The v0.1 founding commit ships **zero Enabled Providers**. This is intentional: a constitution that names a provider as "default-enabled" while its CLI version, output shape, auth artifact, and exit-code semantics are still TBD violates Rules 1 (Cite First) and 3 (Match the Implementation). Enablement is a Phase audit deliverable, not a bootstrap claim. +**Note on phase terminology.** "Phase" in the tables and audit triggers below (and in Β§ One-shot Triggered Audits β†’ "OpenAI Codex ToS formal pin") refers to the **original per-plugin enablement plan** captured at project founding (one Tier-D plugin enabled per phase). The milestone phase numbering in [`README.md` Β§ Phase plan](./README.md#phase-plan) was re-aligned at v0.1.1 close (D43-A, 2026-05-25) to reflect actually-shipped bundling β€” Phase 1 shipped all three Tier-D plugins + cache + fallback together as a single milestone, and Phase 2 became multi-key auth per ADR 0007. The two numberings are orthogonal: ALIGNMENT.md tracks **per-plugin enablement maturity**; README tracks **milestone release scope**. + ### Enabled Providers | Provider key | Tier | Default state | Authority pin | Inclusion source | diff --git a/CHANGELOG.md b/CHANGELOG.md index f596423..d05b13e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,16 @@ All notable changes to OLP land here. Per `CLAUDE.md` release_kit overlay, this ## Unreleased -(empty β€” Phase 2 entries land here once Phase 2 opens) +### 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 diff --git a/CLAUDE.md b/CLAUDE.md index 6fa8503..0d4e597 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -135,7 +135,7 @@ release_kit: # This overlay is the authoritative source. If Iron Rule 5 appears to be silently # violated (no version bump after many D-day pushes), check this section first # before filing a compliance finding. - current_phase: Phase 1 - current_pre_release_identifier: "0.1.0-bootstrap" + current_phase: Phase 2 + current_pre_release_identifier: "0.2.0-phase2" phase_close_trigger: explicit maintainer action (not automated) ``` diff --git a/README.md b/README.md index 70907c9..0a65de4 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A personal- and family-scale multi-provider LLM proxy. One HTTP endpoint, many subscriptions behind it, automatic routing, automatic fallback, content-addressed caching β€” so your IDEs and family clients keep working as long as *any* of your subscriptions has quota left. -> **Status:** v0.1 β€” bootstrap. Most of this README is a skeleton; sections marked _placeholder_ land alongside the relevant phase of work (see [phase plan](#phase-plan)). +> **Status:** v0.1.1 shipped (2026-05-25) β€” Phase 1 multi-provider proxy core + cleanup. Phase 2 (multi-key auth, `lib/keys.mjs`) is currently in progress per ADR 0007. Sections marked _placeholder_ land alongside the relevant phase of work (see [phase plan](#phase-plan)). --- @@ -165,9 +165,9 @@ If a fallback chain is exhausted, `X-OLP-Fallback-Exhausted` lists the tried pro --- -## Implementation status (as of 2026-05-24) +## Implementation status (as of 2026-05-25) -Phase 1 is in progress. This table reflects what is currently shipped vs. what is designed for later phases. +Phase 1 is closed at v0.1.1 (multi-provider proxy core + pre-Phase-2 cleanup). Phase 2 (multi-key auth, `lib/keys.mjs`) is in progress per ADR 0007. This table reflects what is currently shipped vs. what is designed for later phases. | File / artifact | Status | Notes | |---|---|---| @@ -182,7 +182,7 @@ Phase 1 is in progress. This table reflects what is currently shipped vs. what i | Soft trigger data path (`quotaStatus()` polling) | πŸ“‹ Planned (v1.x) | Evaluation logic shipped + tested; data ingestion deferred per ADR 0004 Amendment 2 | | `models-registry.json` | βœ… Shipped | SPOT for `(provider, model)` metadata | | `test-features.mjs` | βœ… Shipped | Comprehensive test suite covering IR, cache, fallback, and integration paths (CI: `test.yml`) | -| `lib/keys.mjs` | πŸ“‹ Planned (Phase 2) | Multi-key auth, per-key namespacing, audit log | +| `lib/keys.mjs` | πŸ“‹ Phase 2 active | Multi-key auth, per-key namespacing, audit log. ADR 0007 drafting at D43-B; implementation D-days to follow. | | `dashboard.html` | πŸ“‹ Planned (Phase 6) | Owner-only multi-provider dashboard | | `docs/provider-caveats.md` | πŸ“‹ Planned (Phase 3+) | Lossy-translation reference; for now documented inline in each plugin header | | `docs/openai-spec-pin.md` | βœ… Shipped (D30) | OpenAI spec snapshot for annual audit; v0.1 baseline pinned 2026-05-24 | @@ -196,7 +196,7 @@ Behaviors that work correctly at personal/family scale but have ratified follow- - **Streaming-path singleflight not implemented.** The cache layer's D4 singleflight (one spawn per identical concurrent request) is fully wired on the buffered path but NOT on the streaming path. N concurrent identical streaming requests at v0.1 will each spawn their own CLI process. Design ratified in [ADR 0005 Amendment 8](./docs/adr/0005-cache-cross-provider.md); implementation tracked via [issue #16](https://github.com/dtzp555-max/olp/issues/16) and [v1.x roadmap #1](./docs/v1x-roadmap.md). At family scale this is observably fine β€” every caller still receives the correct response; the cost is N CLI processes instead of one. - **Soft triggers configured but inert.** `routing.soft_triggers` in `~/.olp/config.json` is honored by the engine's evaluation logic but `quotaStatus()` polling is not wired (ADR 0004 Amendment 2). A startup warning fires if the field is non-empty so the inert state is visible. -- **Multi-key auth not yet implemented.** All requests today share the cache namespace `__anonymous__`. The cache data model is keyed by `keyId` and ready to accept real identities when `lib/keys.mjs` lands. Tracked in [v1.x roadmap #2](./docs/v1x-roadmap.md). +- **Multi-key auth not yet implemented.** All requests today share the cache namespace `__anonymous__`. The cache data model is keyed by `keyId` and ready to accept real identities when `lib/keys.mjs` lands. Phase 2 active: ADR 0007 drafting at D43-B, implementation D-days to follow. Tracked in [v1.x roadmap #2](./docs/v1x-roadmap.md). - **Provider-level `cacheKeyFields` mask not implemented.** Cache keys include every IR field including ones individual plugins drop at spawn (e.g., Anthropic plugin drops `temperature`). Spurious cache misses possible (extra spawn cost; never spurious hits). Conservative posture documented in [ADR 0005 Amendment 7](./docs/adr/0005-cache-cross-provider.md). Tracked in [v1.x roadmap #5](./docs/v1x-roadmap.md). --- @@ -220,17 +220,16 @@ Read the ADRs in `docs/adr/` in order before proposing structural changes. OLP lands in phases. Each phase has its own PR series and Iron-Rule-10 reviewer; this README's placeholders are filled per-phase via the [`release_kit`](./CLAUDE.md) overlay. -- Phase 0 β€” Repo bootstrap, `ALIGNMENT.md`, founding ADRs, CI workflows, PR template. **(current)** -- Phase 1 β€” `server.mjs` skeleton, IR, Anthropic plugin, cache D1+D4. Port from OCP. -- Phase 2 β€” OpenAI Codex plugin. -- Phase 3 β€” Mistral Vibe plugin. -- Phase 4 β€” Fallback engine + routing chains config + quota poll worker. -- Phase 5 β€” Cache cross-provider hardening (D2+D3). -- Phase 6 β€” Dashboard + observability (`/v0/management/quota`). -- Phase 7 β€” Release v0.1, OCP enters maintenance. -- Phase 8+ β€” Optional Grok / Kimi / tier-2 plugins; provider-native protocol endpoints; deterministic triggers. +The original v0.1 spec (in `~/.cc-rules/memory/projects/olp_v0_1_spec.md` on the maintainer's workstations) planned one provider plugin per phase. The actual Phase 1 execution bundled the three Tier-D provider plugins + cache layer + fallback engine into a single shipped milestone (v0.1.0) followed by a cleanup batch (v0.1.1). The phase numbering below reflects what was actually shipped, not the original per-plugin partition. -Full spec (decision rationale, open questions, risks): `~/.cc-rules/memory/projects/olp_v0_1_spec.md` on the maintainer's workstations. +- **Phase 0** β€” Repo bootstrap, `ALIGNMENT.md`, founding ADRs, CI workflows, PR template. βœ… Shipped (2026-05-23). +- **Phase 1** β€” Multi-provider proxy core: `server.mjs`, IR, three Tier-D provider plugins (Anthropic / OpenAI Codex / Mistral Vibe), cache (D1+D4) + cleanup (D2 bypass / D3 chunked replay / D23 size cap), fallback engine with first-chunk safety + hard triggers + per-hop log observability, IR↔OpenAI translation under Rule 2(b). βœ… Shipped β€” v0.1.0 (2026-05-24) + v0.1.1 cleanup (2026-05-25, D35–D42). +- **Phase 2** β€” Multi-key auth (`lib/keys.mjs`) per ADR 0007: opaque OLP API keys, per-key cache namespacing (the data model already supports this β€” only the `keyId` source is missing), owner-vs-guest tier for header gating, audit ndjson, owner-only gating for `/health` + `X-OLP-Fallback-Detail` (D40 follow-up). **(current β€” ADR drafting at D43-B)**. +- **Phase 3** β€” Dashboard (`dashboard.html`) + audit query layer (deferred from Phase 2). Owner-only multi-provider quota panels, fallback rate, cache hit rate; localhost-bound by default. +- **Phase 4+** β€” v1.x roadmap items as triggered. Full deferred-work tracker: [`docs/v1x-roadmap.md`](./docs/v1x-roadmap.md). Includes streaming-path singleflight ([issue #16](https://github.com/dtzp555-max/olp/issues/16) + ADR 0005 Amendment 8 design ratified), soft-trigger reactivation (ADR 0004 Amendment 2), `/health` activeSpawns integration, provider-level `cacheKeyFields` mask, streaming-path SPAWN_FAILED salvage. +- **Phase N (opt-in)** β€” Tier-2 / Tier-C provider plugins (Grok / Kimi / MiniMax / GLM / Qwen) per [ADR 0006](./docs/adr/0006-provider-inclusion.md); provider-native protocol endpoints; deterministic triggers. Triggered by tier-2 demand, not on the bootstrap path. + +Full spec (decision rationale, open questions, risks): `~/.cc-rules/memory/projects/olp_v0_1_spec.md` on the maintainer's workstations. Phase 2 kickoff handoff: `~/.cc-rules/memory/handoffs/2026-05-25-phase-2-kickoff.md`. ---