2 Commits

Include renames

Author	SHA1	Message	Date
taodengandClaude Opus 4.7	f784fdb947	fix+docs: D33 — round-5 cleanup batch (F1/F3/F5/F8/F9/F10/F11/F12) ... cold-audit catch from 2026-05-24 (round 5) Round-5 cold-audit cleanup batch. 8 items + 1 release-discipline reconciliation. Largest batch by line count (582+/39-) but every item is small-and-focused. 3 P2 items (F1/F3/F5 of which F3 + F1 are real correctness/observability fixes; F5 backfills /health to spec). Changes (10 files, +583/-39): **P2 fixes** 1. **F1 — ALIGNMENT.md mistral authority pin self-contradicted plugin** (ALIGNMENT.md): row cited `vibe --prompt --output json` but mistral.mjs uses `--output streaming` (the plugin header at lines 360-369 even justifies WHY: `--output json` emits single blob, breaks NDJSON line-buffered parser). Constitution self-contradicting itself — missed across 4 prior rounds. Pin updated to `--output streaming` with DOCS-1 reference. 2. **F3 — Deterministic function_call synth ID** (lib/ir/openai-to-ir.mjs): deprecated `function_call` translation produced `id: \`fc-${Date.now()}\`` → ID flows into normalized tool_calls → cache key SHA-256. Two identical requests separated by ≥1ms → different cache keys → cache always misses for `function_call` request shape. Violates ADR 0005 invariant "same inputs → same key, no random, no timestamp." Fixed: id is now `fc-<16-hex>` from SHA-256 of `${name}\0${arguments}`. NUL separator prevents the (name='ab',args='c') vs (name='a',args='bc') collision. 2^64 collision resistance is more than sufficient for tool_call ID disambiguation (per-request semantic key, not crypto primitive). **P3 fixes** 3. **F5 — /health invokes per-plugin healthCheck()** (server.mjs + docs/openai-spec-pin.md): ADR 0002 says "healthCheck — startup AND /health endpoint use this." Pre-D33 /health returned only {enabled, available} counts. Now async, iterates loadedProviders, awaits each plugin's healthCheck() in try/catch. Returns `providers: {enabled, available, status: {<name>: {ok, latencyMs?, error?}}}`. 4. **F8 — X-OLP-Cache reports fallback-hop cache hits** (server.mjs): pre-D33 cacheStatus computed from `preCheckHit && fallbackHops === 0` — only counted primary-hop cache hits. When fallback fires + the fallback hop's getOrCompute returns from cache, header reported `miss` despite no spawn happening. Fixed: peek BEFORE getOrCompute inside executeHopFn, set `lastHopWasCached` closure variable on every hop (last-write-wins = serving hop's state). cacheStatus combines `lastHopWasCached || (preCheckHit && fallbackHops === 0)`. F8 chose option (b) peek-then-getOrCompute over option (a) getOrCompute API change because option (a) would break ~15 test callsites for marginal benefit. Accepted race window same as existing preCheckHit pattern. 5. **F9 — validateProvider hints error message updated** (lib/providers/ base.mjs): pre-D33 message listed cacheable as missing and maxSpawnTimeMs as required. Now: `'hints must be an object with { requiresTTY, concurrentSpawnSafe, maxConcurrent } + optional { maxSpawnTimeMs, cacheable }'`. 6. **F10 — Dead cache-write branch removed** (server.mjs): the `if (hasStopChunk)` check in the streaming stop-less exhaustion branch was unreachable (the stop-chunk completion path returns earlier inside the for-await loop). Removed the dead code + added a comment documenting the invariant. **Governance/policy** 7. **F11 — Phase rolling mode policy formalized** (CLAUDE.md + CHANGELOG.md): 22+ D-day commits accumulated under "Unreleased" without per-D version bumps — Iron Rule 5 (release-kit bump-before- push) appeared to be silently violated. Reality: per-D bumps would produce 30+ noise tags during Phase 1. F11 formalizes the policy: intra-Phase D-day commits accumulate under Unreleased; bump+tag fires explicitly at Phase close (maintainer-triggered, not automated). CLAUDE.md release_kit overlay gains `phase_rolling_mode` block documenting the exception with self-pointer ("if Rule 5 appears silently violated, check this section first"). CHANGELOG "Unreleased" gets a notice at top. **No version bump, no git tag in D33** — policy formalization only. 8. **F12 — /v1/models created is stable per-model timestamp** (models-registry.json + lib/providers/index.mjs + server.mjs + docs/openai-spec-pin.md): pre-D33 used Math.floor(Date.now()/1000) per request — violates OpenAI spec which treats `created` as per-model attribute. Clients caching models by created would see spurious updates on every poll. Fixed: models-registry.json gains `bootstrapCreated: 1778630400` top-level constant + per-model `created` fields where known (anthropic claude-{opus,sonnet,haiku} with estimated release dates; devstral models from "25-12" suffix; codex models pinned to bootstrap pending verified release dates). handleModels uses `getModelCreated(modelId)` helper from lib/providers/index.mjs. Aliases share canonical's timestamp. **Tests** (test-features.mjs): 401 → 414 (+13): - F3 ×3 (same input → same id → same cache key; different name → different) - F5 ×4 (empty/single/multi/throwing-plugin /health shapes) - F8 ×1 (2-hop primary-fail + secondary-cache-hit → X-OLP-Cache: hit) - F12 ×5 (stability/fallback/alias-equals-canonical) Pre-commit fold-in (per evidence-first checkpoint #4): - **D33 reviewer flagged F3 empty-args asymmetry** (Concern #1): hash input used `?? ''` (empty stays) but emitted IR field used `|| '{}'` (empty becomes '{}'). Consequence: `arguments: ''` and `arguments: '{}'` emit identical IR but compute different ids → different cache keys for semantically-identical requests. The exact cache-stability bug F3 was supposed to fix. Folded in: canonicalize empty-args to '{}' BEFORE hashing. Hash input now matches IR emission exactly. Same line change resolves the asymmetry. Authority: - ALIGNMENT.md self-amendment (F1 pin correction) - ADR 0005 invariant "same inputs → same key, no random, no timestamp" (F3 restoration) - ADR 0002 § Provider contract "/health uses healthCheck" (F5) - ADR 0004 § Observability headers (F8 X-OLP-Cache correctness) - ADR 0005 § Cache write conditions item 1 (F10 truncation-not-cached invariant explicit) - Iron Rule 5 (F11 release-kit reconciliation) - OpenAI /v1/models spec — `created` per-model stable (F12) - CC 开发铁律 v1.6 § 10.x — Round-5 Cold Audit caught all 8 Reviewer (Iron Rule v1.6 § 10.x Mode A, fresh-context opus, independent of drafter): APPROVE_WITH_MINOR. Verified: - F1 plugin cross-reference (mistral.mjs:360-369) accurately documents the rationale - F3 collision resistance + NUL separator + restored cache invariant - F5 all 4 cases (empty/single/multi/throwing) work - F8 closure semantics across multi-hop chains (verified hop-fail + fallback-hit case) - F10 dead code removal preserves the stop-chunk completion path - F11 phase_rolling_mode policy honest about what happened and what the going-forward rule is - F12 stability across consecutive /v1/models calls; alias-canonical parity - 414/414 tests pass 3 remaining non-blocking suggestions (F3-vs-modern-tool_calls path canonicalization symmetry; F12 codex models explicit-vs-fallback writeup mismatch; F8 servingHopWasCached naming) tracked as future polish; not folded. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-24 19:12:03 +10:00
taodengandClaude Opus 4.7	5119b427fd	docs: D30 — README env vars correctness (F7) + openai-spec-pin.md v0.1 baseline (F20) ... cold-audit catch from 2026-05-24 (round 3) Round-3 P3 docs batch. Two unrelated docs items grouped per IDR cleanup convention (D19/D20/D25 precedent). **F7** — README Environment Variables table drift. Pre-D30 table documented `OLP_HOME` and `OLP_LOG_LEVEL` — neither is read by any code in the repo. The table missed `OLP_CLAUDE_BIN`, `OLP_CODEX_BIN`, `OLP_VIBE_BIN` which the 3 provider plugins DO read to override the path to each provider's CLI binary. `grep -rn "process\.env\.OLP_" server.mjs lib/` returns exactly 4 reads: - `OLP_PORT` (server.mjs:49) - `OLP_CLAUDE_BIN` (anthropic.mjs:69) - `OLP_CODEX_BIN` (codex.mjs:143) - `OLP_VIBE_BIN` (mistral.mjs:240) Fix: README env-vars table now lists exactly these 4 active vars with their actual defaults. `OLP_HOME` + `OLP_LOG_LEVEL` moved to a "📋 Planned (Phase 2)" callout block beneath the table, with honest explanations linking to the actual code state (`loadFallbackConfigSync` hardcodes the config path; `logEvent` writes unconditionally). **F20** — Author docs/openai-spec-pin.md v0.1 baseline. ALIGNMENT.md Authority 2 + Annual Alignment Audit § Scope both referenced `docs/openai-spec-pin.md` as the artifact the annual audit diffs against. Pre-D30 the file didn't exist (D20 marked it 📋 Planned). This left the entry-surface audit without a diff baseline — v0.1 ships with no provable "the OpenAI spec was THIS on the day OLP implemented its entry surface" anchor. Fix: author a 175-line minimal v0.1 baseline. Every field claim is verified against source (openai-to-ir.mjs + ir-to-openai.mjs + server.mjs). Structure: - POST /v1/chat/completions: 14 supported request fields (model, messages + 6 message-level subfields, stream, temperature, max_tokens, top_p, stop, tools, tool_choice, response_format) + 11 NOT-yet-supported fields (n, seed, frequency_penalty, presence_penalty, logit_bias, logprobs, top_logprobs, user, service_tier, parallel_tool_calls, stream_options) - Response shapes: chat.completion (non-stream), chat.completion.chunk (streaming) — verified against irResponseToOpenAINonStream and irChunkToOpenAISSE - `finish_reason` enum: verified against OPENAI_FINISH_REASON_ENUM constant in ir-to-openai.mjs (post-D19 + D26) - Error response shape: HTTP 4xx/5xx + `{error: {message, type}}` — verified against `sendError` in server.mjs - GET /v1/models: verified against handleModels (post-D18 + D27 F15) - Streaming SSE semantics: framing, terminator, post-D26 F19 truncation marker The pin also documents the v0.1 → v1.0 forward-looking expansion plan: the "NOT yet supported" fields are explicit candidates for v1.0+ implementation via openai-to-ir.mjs amendments + ADR 0003 updates. ALIGNMENT.md + README Implementation status table both flip the marker from 📋 Planned to ✅ Shipped (D30) with the 2026-05-24 timestamp. Changes (3 files, +180 / -8): - ALIGNMENT.md +2/-2 (2 markers updated: Authority 2 + Annual Audit) - README.md +11/-6 (env-vars table delta + status table marker flip + Planned callout for OLP_HOME/OLP_LOG_LEVEL) - docs/openai-spec-pin.md (new, 175 lines) Tests: 400/400 unchanged — pure docs change. Authority: - F7 → process.env reads verified by direct grep - F20 → OpenAI Chat Completions spec https://platform.openai.com/docs/api-reference/chat/create https://platform.openai.com/docs/api-reference/chat/streaming https://platform.openai.com/docs/api-reference/chat/object https://platform.openai.com/docs/api-reference/models/list - F20 internal source-of-truth: openai-to-ir.mjs + ir-to-openai.mjs + server.mjs (all field claims traced) - ALIGNMENT.md § Authority 2 + § Annual Alignment Audit - CC 开发铁律 v1.6 § 10.x — Round-3 Cold Audit caught both items Reviewer (Iron Rule v1.6 § 10.x Mode A, fresh-context opus, independent of drafter): APPROVE. Independent verification: - Grep confirmed exactly 4 process.env.OLP_* reads — matches new env vars table - Each new var's default value verified against the plugin code (anthropic.mjs:69 → 'claude'; codex.mjs:143 → 'codex'; mistral.mjs:240 → 'vibe') - All 14 spec-pin supported request fields traced to openAIToIR line references (model L129, messages L45-89, stream L141, temperature L160, max_tokens L152, top_p L168, stop L176, tools L183, tool_choice L187, response_format L191) - All 11 NOT-supported fields confirmed absent via grep - Response shape claims (chat.completion + chat.completion.chunk + /v1/models) all match source code line-by-line - ALIGNMENT.md markers — pure markup flip, no rule changes - 400/400 tests pass 3 non-blocking suggestions noted (function_call finish_reason caveat; README slug rendering; ADR 0003 cross-link in spec-pin) — all cosmetic, not folded. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-24 16:56:01 +10:00