Distillation

Date: Sep 16, 2026

• 🔴 (15:11) User directive: “Never trust the fix without seeing it fail.” Bug fixes must follow failing-first TDD: write a deterministic regression test, confirm it fails on the base branch, then confirm it passes with the fix.
• 🔴 (15:12) User directive: “Always accumulate into the internal state for postResponse.”
• 🟡 (15:11) Recent commit chain shown: ce88c614c0ae55d229cb605aa7c7369d918d3650 (fix(responses): complete lifecycle reconciliation, parent 683dff02101f15198b18e3088a0b57dade290056); 683dff02101f15198b18e3088a0b57dade290056 (fix(responses): bound sparse lifecycle coordinates, parent df49b0cec904a3f432a0f7f29ea398840d62fe9e); df49b0cec904a3f432a0f7f29ea398840d62fe9e (fix(responses): preserve limit-crossing state, parent 2cbf40060c67df229731cf1b9e34d5bf22ec2145); 2cbf40060c67df229731cf1b9e34d5bf22ec2145 (feat(cch): add seeds for Claude Code up to 2.1.272 (#1780), parent e977b4b1da8f8197c3238466d41de0bccd8eb054). Changes span packages/gateway/src/pipeline.ts, packages/gateway/src/stream/openai-responses.ts, and packages/gateway/test/openai-responses-recall-aware-stream.test.ts: 3 files changed, 2,068 insertions, 136 deletions.
• 🔴 (15:11) User’s regression-test discipline in quality/REVIEW.md: every adversarial-review defect must receive a deterministic same-PR regression test that (1) fails on the base branch, (2) passes on the fix, and (3) drives the real precondition rather than constructing an artificial state. A guard test must fail when the guard is removed.
• 🔴 (15:11) User’s adversarial-order test convention: establish state before the operation that should handle it; test delete-then-recreate across lifecycle boundaries; and test modify-while-off so disabled capture triggers cannot observe the content change.
• 🔴 (15:11) User’s fan-out registry coverage rules: SYNCED_TABLES additions require packages/core/test/sync-registry-contract.test.ts coverage for registered shape, pull-only/no-capture invariant, composite-primary-key correctness, and versioned status; MIGRATIONS additions require the db.test.ts schema-version assertion using toBe(MIGRATIONS.length) plus migration-specific behavior tests; AGENTS additions require agents.test.ts checks for name, displayName, binary, and detect(), with binary remaining a constant placeholder string.
• 🔴 (15:11) User’s standing test batteries: 1. Registry contract—SYNCED_TABLES shape, pull-only guard, ID-column correctness, and versioned flag in packages/core/test/sync-registry-contract.test.ts; 2. Sync invariants per operation—no pull-only outbox, profiles ≤ 1, and every state row references a registered table via assertSyncInvariants in packages/core/src/sync-data.ts; 3. Sequence properties—standing invariants after every operation, prune-floor never wedges, eventual convergence, no ping-pong, and correct currentTier in packages/gateway/test/sync.property.test.ts.
• 🔴 (15:11) User stated skip/early-return branches are the highest-risk surface; guards involving NOT EXISTS, latest <> 'upsert', and content matching previously masked data-loss bugs. Every skip branch needs a test that makes it fire incorrectly and proves the operation is not skipped.
• 🔴 (15:11) User stated property-based tests over faithful mocks caught four real sequence-dependent sync-engine bugs missed by example tests, spanning enable/disable/push/pull boundaries.
• 🔴 (15:11) User prefers freezing memoized arrays shared across callers, such as the syncedColumns PRAGMA cache, so mutation fails loudly with TypeError in strict mode instead of silently corrupting the cache.
• 🔴 (15:11) User stated db().query monkeypatches are shadowed by the tracing Proxy. Tests that count SQL statements must use log.registerSink({ withDbSpan }); directly assigning db().query = ... is silently ignored by the Proxy, as empirically verified in #874.
• 🔴 [requested-review] (15:11) User’s review workflow requires two separate review passes for non-trivial changes: 1. adversarial/correctness review asking “What state makes this break?”, including enumerated cases, apply-then-revert mutants, property-test stability ×10, hash-equivalence proofs, frozen-array mutation safety, and stale-cache analysis; 2. security/pentest review covering injection vectors, credential leaks, protocol-level attacks, and privilege escalation. These must be distinct subagent invocations with separate prompts; adversarial review is mandatory before merge, while security review depends on risk profile.
• 🔴 [requested-review] (15:11) User requires reviewers to run pnpm test, pnpm run typecheck, pnpm run lint, and pnpm run format:check; inspect exit codes because a blank output tail can hide lint/format failure; run property tests ×10; confirm an unmodified working tree using hash verification; and report per-point PASS / FAIL / CONCERN / MUST-FIX verdicts with file:line evidence plus an overall MERGE / DO-NOT-MERGE verdict. Unstructured “LGTM” is insufficient.
• 🔴 [requested-review] (15:11) User requires adversarial review for any change touching correctness-critical paths, including the sync engine, hashing, lifecycle handling, and migrations, regardless of change size. Mechanical or test-only PRs may skip adversarial review at reviewer discretion.
• 🟡 (15:12) packages/gateway/src/pipeline.ts lifecycle reconciliation now models OutputLifecycle with reasoning: Map<number, TextPartLifecycle> and content: Map<number, TextPartLifecycle>. finalizedMessageContent() preserves sparse content_index coordinates by assigning finalized output_text or refusal records directly to content[contentIndex], rather than sorting and compacting entries with .filter().map().
• 🟡 (15:12) Codex normalization in packages/gateway/src/pipeline.ts:7932-7949 uses a WeakMap<ResponsesAccState, ResponsesAccState> named codexNormalizationStates; normalizeCodexEvent() invokes normalizeCodexResponsesEvent() only when opts.validation === "codex" and bounds normalization with Math.min(maxSSEFrames, DEFAULT_MAX_SSE_FRAMES).
• 🟡 (15:12) Follow-up cancellation logic in packages/gateway/src/pipeline.ts:9806-9848 uses settleFollowUp(), races opts.runFollowUp() against an abort promise, immediately throws signal.reason when aborted, and calls cancelAndReleaseReader(late.reader, signal.reason) if an abort-ignoring operation returns a reader late.
• 🟡 (15:12) Sparse-index arithmetic in packages/gateway/src/pipeline.ts:9849-9855 uses shiftedOutputIndex(index, offset). It throws Error("Responses output_index overflow") when the sum is not a safe integer or is negative.
• 🟡 (15:12) Sparse lifecycle enforcement locations shown in packages/gateway/src/pipeline.ts: maxSSEFrames defaults at line 8116; maxSparseIndex = Math.min(maxSSEFrames, DEFAULT_MAX_SSE_FRAMES) at line 8117; assertSparseCoordinates() at line 8386 and invocation at line 10371; continuation coordinate tracking uses maximumOutputIndex at lines 10940-10944, shiftedOutputIndex() for contIndex at lines 10948-10949, continuation validation at line 11001, shifted output events at lines 11124 and 11272, and shifted recall indices at lines 11522 and 11572.