3 Commits

Author	SHA1	Message	Date
Garry Tan	d28be5d091	v0.40.4.0 feat(search): selective graph signals + per-stage attribution + audit-writer unification (#1300) ... * v0.40.4.0 T1: shared audit-writer primitive Extract createAuditWriter() helper. Five hand-rolled JSONL audit modules (rerank-audit, shell-audit, supervisor-audit, audit-slug- fallback, phantom-audit) duplicated the same ISO-week filename math, best-effort write loop, and read-current-plus-previous-week loop. T2 refactors all 5 onto this primitive. Behavior preservation: filename format, JSONL line shape, mkdir recursive, appendFileSync utf8, stderr-on-failure all byte-identical to the existing modules so their tests pass unchanged. resolveAuditDir() moves here from shell-audit.ts; shell-audit.ts will re-export for back-compat (T2). Honors GBRAIN_AUDIT_DIR with whitespace-trim, falls back to ~/.gbrain/audit/. Test coverage: 22 cases covering ISO-week math + year-boundary edges (2027-01-01 → 2026-W53), env override, mkdir-recursive, fail-open stderr-warn shape, cross-week readback, corrupt-row skip, non-finite- ts skip, round-trip with nested fields, computeFilename + resolveDir accessors. Plan ref: D5=B audit unification cathedral expansion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T2: refactor 5 audit modules onto shared writer Replace the duplicated ISO-week filename math + best-effort write loop + read-current-plus-previous-week loop in: - src/core/rerank-audit.ts (rerank-failures-*.jsonl) - src/core/audit-slug-fallback.ts (slug-fallback-*.jsonl) - src/core/minions/handlers/shell-audit.ts (shell-jobs-*.jsonl) - src/core/minions/handlers/supervisor-audit.ts (supervisor-*.jsonl) - src/core/facts/phantom-audit.ts (phantoms-*.jsonl) All five now delegate file I/O to createAuditWriter from T1. Public API preserved bit-for-bit: - logRerankFailure, readRecentRerankFailures, computeRerankAuditFilename - logSlugFallback, readRecentSlugFallbacks, computeSlugFallbackAuditFilename - logShellSubmission, computeAuditFilename, resolveAuditDir - writeSupervisorEvent, readSupervisorEvents, computeSupervisorAuditFilename plus isCrashExit, summarizeCrashes, CrashSummary (domain-specific helpers stay in supervisor-audit.ts; only file I/O moves) - logPhantomEvent, readRecentPhantomEvents, computePhantomAuditFilename Domain-specific behavior preserved: - audit-slug-fallback emits per-call stderr (D7 dual logging) in the caller; the shared writer is failure-only stderr - rerank-audit truncates error_summary to 200 chars before write - phantom-audit spreads optional fields conditionally (skip undefined) - supervisor-audit keeps single-file readback (no cross-week walk) to preserve pre-v0.40.4 doctor assertions resolveAuditDir lives in src/core/audit/audit-writer.ts; shell-audit.ts re-exports it so existing imports keep working (every other audit module + gbrain-home-isolation.test.ts + minions.test.ts + minions-shell.test.ts pull resolveAuditDir from shell-audit.ts). Operator-visible drift: rerank-audit stderr line drops the 'rerank-failure audit' qualifier — was '[gbrain] rerank-failure audit write failed (...)' now '[gbrain] write failed (...); search continues'. Stderr is human-debugging, not machine-parsed; the file written gives the qualifier away in `tail -f audit/*`. Test coverage: 128/128 audit-touching tests pass unchanged. Plan ref: D5=B audit unification cathedral expansion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T3: getAdjacencyBoosts engine method (PG+PGLite parity) Add BrainEngine.getAdjacencyBoosts(pageIds) returning Map<page_id, AdjacencyRow{hits, cross_source_hits}>. Returns ALL pages with hits >= 1 (callers apply their own threshold). Cross-source semantic (D15=A): cross_source_hits EXCLUDES the target page's own source. A page in source A linked from 2 pages in source A reports cross_source_hits = 0. Linked from 1 in source B + 1 in source C reports 2. Source-scope contract: pageIds MUST already be source-scoped by the caller. Method does NOT filter by source_id. The in-set restriction makes cross-source leakage impossible by construction. JSDoc spells this out; same trust posture as cosineReScore's chunk_id handling. COALESCE(p.source_id, 'default') on both target and from-page sides for defense-in-depth even though pages.source_id is NOT NULL today. JSDoc/SQL contract alignment (codex #2): HAVING >= 1 matches the "returns ALL pages with hits >= 1" contract; threshold of 2 is the caller's call in applyGraphSignals. Known limitation (codex #15): cross_source_hits cannot distinguish "genuinely linked from another team" from "mirrored imports from another source." T-todo-4 captures the v0.41+ refinement. SearchResult type extension (D4=A flat fields, D12=A attribution): - graph_adjacency_hits, graph_cross_source_hits, graph_session_demoted, graph_session_prefix - base_score, backlink_boost, salience_boost, recency_boost, exact_match_boost, graph_adjacency_boost, graph_cross_source_boost, session_demote_factor, reranker_delta All optional; T4-T6 populate them. Test coverage: 7/7 hermetic PGLite cases. Empty input, singleton, same-source hub, cross-source attribution including the "linked-only-from-other-source" case (widget in source b, linked from alice+bob in source a → cross_source_hits=1), JSDoc HAVING>=1 contract. Postgres parity asserted by SQL-shape identity (will get a mirror Postgres E2E in T10's eval gate work via DATABASE_URL when set; PGLite hermetic case shipped now). NULL source_id COALESCE branch noted as untestable in current PGLite schema (pages.source_id is NOT NULL); kept as defense-in-depth. Plan ref: T3 in v0.40.4.0 wave plan; D1=A, D3=A, D15=A. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T4+T11: applyGraphSignals 4th stage in runPostFusionStages New file src/core/search/graph-signals.ts. Three signals: 1. Adjacency-within-top-K (×1.05): hits >= 2 inbound from in-set. 2. Cross-source adjacency (×1.10, stacks): cross_source_hits >= 2. Dormant on single-source brains. 3. Session diversification (×0.95): if multiple top-K share a slug prefix, keep highest scoring, DEMOTE the rest. NOT amplify — codex caught the original framing was backwards (amplification of redundancy makes the cited "weak chunks compete for budget" problem worse, not better). Conservative magnitudes (D14=B): 1.05/1.10/0.95. Score-distribution probe (onScoreDistribution) collects min/p25/p50/p75/p95/max + reorder_band_width to feed T-todo-2 magnitude calibration wave. Slot: 4th stage inside runPostFusionStages (hybrid.ts:248), AFTER backlink/salience/recency, pre-dedup. Inherits the v0.35.6.0 floor-ratio gate from computeFloorThreshold — this is the structural protection that prevents a low-cosine hub from outranking a strong non-hub (codex T2 / D1=A). PostFusionOpts extends with graphSignalsEnabled, onGraphMeta, onScoreDistribution. Caller (hybridSearch in subsequent T5 work) resolves graph_signals from the mode bundle. Source-scope contract preserved: getAdjacencyBoosts takes raw page_ids, no source filter. Adjacency is in-set restricted so cross-source leakage is impossible by construction (D3=A). Fail-open: engine throw → JSONL audit row via shared createAuditWriter (T1/T2 primitive, featureName='graph-signals-failures') + meta.errored + caller's results unchanged. Session diversification ALSO skips on failure (predictable all-or-nothing posture). Mutation note (codex #9): score mutated in place. base_score must be stamped at runPostFusionStages entry BEFORE this stage so eval-capture sees pre-boost score (T6 attribution wave). Test coverage (24 cases, including T11 IRON RULE regression): - sessionPrefix multi/single/empty cases - computeScoreDistribution percentile math - Disabled + empty short-circuits - Adjacency hit, no-hit, cross-source stacking, cross-source alone - Session diversification 3-share + single-segment + singleton - Test seam injection (no engine call) - Fail-open: throw → audit row + meta.errored + unchanged - Empty Map → session still runs - Score-distribution always emits when enabled - Meta carries fire counts + duration_ms - Missing page_id silently skipped from dedup set - **T11 IRON RULE regression (3 cases):** * weak hub BELOW floor_threshold does NOT get boosted past above-floor non-hub (the bug class the floor gate exists for) * hub AT floor still gets boosted (gate is < not <=) * NaN score → NaN >= threshold is false → no boost Plan ref: T4 + T11 in v0.40.4.0 wave plan; D1=A, D2=A, D11=B, D14=B, D9=A, D5=B. Codex outside-voice #1 + #2 + #6 + #8 + #9 addressed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T5: graph_signals mode-bundle knob + KNOBS_HASH bump 3→4 ModeBundle gains graph_signals: boolean. Per-mode defaults: - conservative: false (cost-sensitive tier) - balanced: true (the wave's primary surface for default-on) - tokenmax: true (power-user tier, capstone fit) SearchKeyOverrides + SearchPerCallOpts gain optional graph_signals field. resolveSearchMode picks via the standard per-call → config override → mode bundle chain. loadOverridesFromConfig parses 'search.graph_signals' from the config table ('1' or 'true' → true). SEARCH_MODE_CONFIG_KEYS adds the key so `gbrain search modes --reset` clears it alongside other knobs. KNOBS_HASH_VERSION bump 3→4 (append-only per CDX2-F13). New `gs=` parts entry appended AFTER cross-modal + column + prov entries. A graph-on cache write cannot be served to a graph-off lookup — mid-deploy hit-rate dip clears within cache.ttl_seconds (3600s). src/commands/search.ts KNOB_DESCRIPTIONS gains graph_signals entry so `gbrain search modes` dashboard renders the new knob. Test coverage: - test/search-mode.test.ts (+ 8 new cases): per-mode defaults canonical, config override both directions, per-call override wins, knobsHash distinct for on/off, config key registered, attributeKnob reports per-call + mode sources correctly. - test/search/knobs-hash-reranker.test.ts: version assertion bumped 3→4 with v0.40.4 rationale comment. - test/cross-modal-phase1.test.ts: version assertion bumped 3→4 with v0.40.4 rationale comment. - Canonical-bundle assertions updated to include graph_signals in expected shape (3 cases). 50/50 search-mode tests pass. 45/45 cross-modal pass. 17/17 knobs-hash-reranker pass. 10/10 balanced-reranker pass. Plan ref: T5 in v0.40.4.0 wave plan. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T6: per-stage attribution stamping in every boost Every boost stage that mutates SearchResult.score now stamps a field recording WHAT it multiplied: - applyBacklinkBoost → backlink_boost (skipped when count == 0) - applySalienceBoost → salience_boost (skipped when score == 0) - applyRecencyBoost → recency_boost (skipped on evergreen prefix) - applyExactMatchBoost → exact_match_boost (skipped on no-match OR when intent's exactMatchBoost == 1.0 no-op) - runPostFusionStages → base_score stamped ONCE at entry, BEFORE any boost mutates r.score. Idempotent: caller-pre-stamped value preserved. Empty-results short-circuit unchanged. - applyReranker → reranker_delta = original_index - new_index (positive = rank improved; raw rerank score stays in rerank_score) - applyGraphSignals → graph_adjacency_boost, graph_cross_source_boost, session_demote_factor (T4 already stamped these) Why: feeds the T7 `gbrain search --explain` formatter so it can attribute the final score to its components. Without these stamps, "why did this rank where it did?" is grep-and-guess. SearchResult.reranker_delta doc updated to clarify it's a RANK delta (positive = improved), not a score delta. The raw relevance score stays in `rerank_score` (untyped, for back-compat with telemetry that already reads it). Test coverage: 16 new cases in test/search/attribution-stamping.test.ts. Pins: every boost stamps when it fires AND skips stamping when it doesn't (no false attribution on no-op stages). base_score idempotency preserved. reranker_delta computed correctly across rank-improved + rank-degraded cases. All 178/178 search tests pass (no regressions). Plan ref: T6 cathedral expansion in v0.40.4.0 wave plan; D12=A. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T7: gbrain search --explain per-stage attribution New file src/core/search/explain-formatter.ts renders SearchResult[] as a multi-line breakdown of how the final score was formed: 1. people/alice (score=12.4) base=10.2 (rrf+cosine) + backlink ×1.08 + salience ×1.05 + adjacency ×1.05 (hits=3) + cross_source ×1.10 (other_sources=2) ↑ reranker rank +2 = final 12.4 Reads the boost_* / base_score / *_hits fields populated by T4 + T6. Empty path: "no boosts applied" when no stage stamped anything. Session demote rendered with `-` prefix (not `+`) so the demotion direction is visually distinct from boosts. CliOptions gains `explain: boolean`; parseGlobalFlags recognizes `--explain` anywhere in argv. cli.ts formatResult for `search` + `query` cases reads CliOptions.explain via the module-level singleton and routes to formatResultsExplain when set. Lazy import keeps the hot path narrow for the common non-explain case. Number formatting: 4-decimal precision, trailing zeros stripped ('1.0000' → '1', '0.1234' → '0.1234'). NaN preserved as 'NaN'. Test coverage: - test/search/explain-formatter.test.ts: 19 cases pin output format. Each boost type renders correctly, every-stage stacking composes, reranker_delta=0 doesn't render, empty list short- circuits, rank numbering 1-based, number formatting edge cases. - test/cli-options.test.ts: 3 new cases for --explain parsing (basic, absent default, any-argv-position). Existing CliOptions literals in test/cli-options.test.ts + test/thin-client-upgrade-prompt.test.ts updated for new required explain field. JSON envelope unchanged — the same attribution fields surface in existing --json output via JSON.stringify; no separate JSON formatter needed. Plan ref: T7 cathedral expansion in v0.40.4.0 wave plan; D12=A + D6=A. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T8: doctor check graph_signals_coverage New checkGraphSignalsCoverage in src/commands/doctor.ts. Wired into both runDoctor (local engine) and doctorReportRemote (HTTP MCP / JSON path) so local AND remote-server brains both surface the metric. Logic: 1. Resolve active graph_signals setting: config override 'search.graph_signals' wins, else mode bundle default ('search.mode' → conservative=false, balanced/tokenmax=true). 2. When disabled → silent ok ("disabled — coverage not checked"). Avoids polluting doctor output on installs that don't use the feature. 3. When enabled, compute global inbound-link density: COUNT(DISTINCT to_page_id) / COUNT(*) across non-deleted pages. 4. <10% → warn ("signal will rarely fire") with paste-ready `gbrain extract all` fix hint. 5. >=30% → ok ("fire on most queries") with metric. 6. 10-29% → ok ("fire occasionally") with metric. Known limitation (codex outside-voice #14): global density is an imperfect proxy for "top-K subgraphs have enough edges to fire." T-todo-5 captures the v0.41+ refinement that measures actual fire rate from search-stats after 30 days of data. Best-effort: SQL errors → warn with the underlying message. Never breaks doctor. Test coverage (7 new cases in test/doctor.test.ts): - conservative mode → silent ok regardless of coverage - balanced default + 0 links → warn at 0% with fix hint - balanced default + 40% inbound → ok "fire on most queries" - balanced default + 20% inbound → ok "fire occasionally" - explicit search.graph_signals=false overrides mode default - empty brain → ok with explanation - check is wired into runDoctor (source-grep regression guard) All 55/55 doctor.test.ts cases pass. Plan ref: T8 in v0.40.4.0 wave plan; D6=A. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T9: gbrain search stats graph_signals section runStatsSubcommand in src/commands/search.ts gains a graph_signals section in both --json and human output: Graph signals: enabled: true (mode default) failures: 3 fail-open event(s) ECONNREFUSED 2 timeout 1 Data sources: - config: 'search.graph_signals' override → enabled + source=config, otherwise mode-bundle default → enabled + source=mode_default. - JSONL audit: readRecentGraphSignalsFailures(days) returns events; failures_count is len, failures_by_reason buckets by first word of error_summary (e.g. 'ECONNREFUSED', 'timeout'). JSON envelope (schema_version 2 unchanged; graph_signals is a new sibling property of stats, so consumers reading the existing fields keep working): { "schema_version": 2, ...stats..., "graph_signals": { "enabled": bool, "source": "config" | "mode_default", "failures_count": int, "failures_by_reason": { reason: count } }, "_meta": { metric_glossary: { ..., graph_signals_enabled: ..., graph_signals_failures_count: ... } } } Fire-rate metrics (adjacency_fires, cross_source_fires, session_demotions) and score-distribution stats are NOT in this section yet — they require telemetry-table writes from the applyGraphSignals onMeta callback. Wired in v0.41+ via T-todo-2 calibration wave (the wave that needs them). For v0.40.4: status + error count is the actionable surface for "is graph_signals on, and is it failing?" Human output: prints the section after the existing stats block. Edge case: when total_calls is 0 BUT graph_signals is enabled OR has historical failures, still prints the section so operators don't lose the signal on a brain with no telemetry yet. Test coverage (6 cases in test/search/search-stats-graph-signals.test.ts): - search.graph_signals=true → enabled true, source=config - mode=conservative → enabled false, source=mode_default - no config → enabled true (balanced default), source=mode_default - JSONL failures bucketed by first word of error_summary - empty audit → failures_count 0, empty failures_by_reason - human output includes "Graph signals:" header Plan ref: T9 in v0.40.4.0 wave plan; D6=A. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T10: eval gates (longmemeval-mini A/B + paired bootstrap) New test/e2e/graph-signals-eval.test.ts runs each longmemeval-mini question twice (graph_signals off, graph_signals on) and asserts: Gate 1 (QUALITY) — paired bootstrap, 10,000 resamples: - If signals-on is significantly WORSE than off (delta < 0 AND p < 0.05) → fail. - Otherwise pass. p>=0.05 either direction OR delta >= 0 → ok. Gate 2a (CHANGE-MAGNITUDE): mean Jaccard@5 over result-set overlap must be >= 0.5. If results overlap less than half, the change is too large and needs human review before default-on. Gate 2b (CHANGE-MAGNITUDE): top-1 stability rate >= 0.7. If 30%+ of top picks change, hard look required. Gate 3 (HARD ABSOLUTE FLOOR): recall@5 drop <= 5pt. Catastrophic regression catch (codex outside-voice #18 — addresses the "top-5 must not drop at all" brittleness on tiny fixtures). Bootstrap implementation: - Per-question observation is binary (recall@5 hit/miss). - Paired pairing on question_id between on/off branches. - Centered distribution under null (subtract observed mean) per standard paired-bootstrap-shift approach for binary outcomes. - Two-tailed p-value: |resampled delta| >= |observed delta|. - Deterministic seeded RNG so test runs are stable across CI. pairedBootstrapPValue exported as a pure function with separate tests for edge cases (empty input, all-equal, strong positive, strong negative, determinism). Reusable from future calibration waves. Hermetic: in-memory PGLite via createBenchmarkBrain + resetTables between questions. No API keys needed (--no-embed import path exercises keyword-only retrieval). Skips gracefully via describe.skip when the fixture is missing. Plan ref: T10 in v0.40.4.0 wave plan; D7=C absolute floor + D13=A paired bootstrap; codex #4 + #18 stability-vs-quality distinction. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 T12: VERSION + package.json + CHANGELOG + TODOS VERSION: 0.37.11.0 → 0.40.4.0 package.json: 0.37.11.0 → 0.40.4.0 CHANGELOG.md: top entry for v0.40.4.0 in ELI10-lead voice per CLAUDE.md release rules. Lead is plain-English ("Your search now notices when a page is a hub for your query"); precise file paths / SQL semantics / numbers live in the "Itemized changes" section below. Includes the cathedral-expansion notes (D5=B audit unification, D12=A per-stage attribution, D13=A eval gates) and the "To take advantage of v0.40.4.0" verify-and-fix block. TODOS.md: 5 new items captured under "v0.40.4 graph signals — deferred follow-ups (v0.41+)": - T-todo-1: profile graph-signal SQL latency, merge if hot (D8=C) - T-todo-2: magnitude calibration wave from probe data (D14=B / D17) - T-todo-3: DB-backed audit table for cross-deploy observability (codex #15) - T-todo-4: sync-topology-aware cross-source signal (codex #11) - T-todo-5: replace doctor's global density with fire-rate (codex #14) Verified the 3-line audit: VERSION + package.json + CHANGELOG topmost all match 0.40.4.0. `bun install` ran (lockfile unchanged — root package version isn't stored in bun.lock). `bun run build:llms` refreshed llms.txt + llms-full.txt for the next commit. Plan ref: T12 in v0.40.4.0 wave plan. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 TODO: document pre-existing shard-2 flake noticed during ship 3 isCacheSafe test failures in shard 2 reproduce on stashed clean master. Confirmed pre-existing — not introduced by v0.40.4. Filed under "Pre-existing flake on master (noticed during v0.40.4 ship)" with reproduction commands + remediation options. Shipping v0.40.4 through it; future wave can fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 privacy scrub: replace wintermute → media in example slugs CLAUDE.md line 550 bans the private OpenClaw fork name in public artifacts. Example session prefix in sessionPrefix() docs + 3 test fixtures swept to 'media/chat/...' instead. Pre-existing scripts/check-privacy.sh in `bun run verify` caught it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 fix: wire graph_signals from mode bundle to runPostFusionStages CRITICAL: pre-landing review (codex outside-voice via /ship Step 9) caught that hybrid.ts's `postFusionOpts` literal at line 566 was building PostFusionOpts WITHOUT threading `resolvedMode.graph_signals` to `graphSignalsEnabled`. The gate at hybrid.ts:358 read the field from a literal that never set it. Result before this fix: the entire v0.40.4 graph-signals wave was dead code in production. Mode bundles set `balanced.graph_signals = true` and `tokenmax.graph_signals = true`, but no production call site ever reached applyGraphSignals. The KNOBS_HASH bump 3→4 correctly varied the cache key by the flag, so contamination was prevented — but the feature itself never fired. All shipped infrastructure (engine SQL, fail-open audit, attribution stamps, --explain formatter, doctor coverage check, search-stats section) was reachable only through the unit-test seam (`opts.adjacencyFn`). The CHANGELOG-advertised behavior never landed in user-visible search. Fix: thread `graphSignalsEnabled: resolvedMode.graph_signals` into the postFusionOpts literal (1 line). Inline comment names codex's catch so future refactors see the regression class. Tests: new test/search/graph-signals-wire-integration.test.ts pins the wire end-to-end. Three cases: 1. balanced mode → hybridSearch on a seeded brain with adjacency hub produces a result with base_score stamped (proves runPostFusionStages actually ran). 2. search.graph_signals=false config override → no graph_* fields stamped (proves the gate honors the override path). 3. Source-grep regression guard pinning the `graphSignalsEnabled: resolvedMode.graph_signals` literal in hybrid.ts so a future refactor can't silently disconnect. All 57 existing v0.40.4 wave tests still pass. Typecheck clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 fix: pre-landing review AUTO-FIX findings (audit msg drift + deleted_at) Two informational findings from /ship pre-landing review (Step 9): 1. Stderr message qualifier drift (rerank/slug-fallback/phantom audits) Pre-v0.40.4 messages included a per-feature qualifier: [gbrain] rerank-failure audit write failed (...) [gbrain] slug-fallback audit write failed (...) [gbrain] phantom audit write failed (...) The T2 refactor dropped the qualifier (plan promised "byte-identical" operator-visible behavior, but stderr lines did drift). Restored via new `errorMessagePrefix` option on `createAuditWriter` (optional, '' default). Three modules pass the per-feature qualifier; shell-audit and supervisor-audit unaffected (their pre-v0.40.4 messages didn't have a separate qualifier — label already carried the feature name). 2. Defense-in-depth `deleted_at IS NULL` on getAdjacencyBoosts SQL was previously protected by-construction (hybridSearch's visibility filter ensures input pageIds are live), but matches the v0.35.5.0 findOrphanPages pattern and closes the bug class if a future caller bypasses hybridSearch. Added to both Postgres and PGLite engines for parity. Three JOIN sites guarded (targets CTE, FROM-pages join). One inline comment per engine cites the codex review and the v0.35.5.0 precedent. Plan ref: /ship pre-landing review v0.40.4.0 (codex finding C and F). All 84 audit+graph-signals tests pass. Typecheck clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 fix: adversarial review HIGH findings (codex H1+H2 + Claude F1) Three HIGH-severity issues from /ship adversarial pass: H1 (Codex): Eval gate was a no-op. Test passed `graph_signals: graphSignalsOn` via `as any` cast, but SearchOpts had no field and hybridSearch's perCall didn't thread it. Both off/on branches resolved to the mode-bundle default — gate measured identical behavior, could pass while detecting nothing. Fix: add `graph_signals?: boolean` to SearchOpts (types.ts:794). Thread `opts.graph_signals` into perCall in both hybridSearch (hybrid.ts:425) AND hybridSearchCached (hybrid.ts:1027) so the cache-key resolver also sees the override. Drop the `as any` from the eval test — types are real now. H2 (Codex): Session diversification fired on entity directories. sessionPrefix() used "any shared parent directory" as the session signal. Result: a search for "people in SF" returned `people/alice` + `people/bob` + `people/charlie` and the latter two got demoted to 0.95×. Every common entity-search query silently penalized legitimate same-type results. Default-on for balanced/tokenmax means production behavior was wrong. Fix: narrow sessionPrefix() to fire ONLY when the slug contains a session-like marker (`chat`/`session`/`sessions` segment OR a `YYYY-MM-DD` date segment). Entity directories (`people/`, `companies/`, `docs/`) return null → diversification skips. Returns NULL (not the slug itself) so the loop skips clean. Examples in JSDoc: your-agent/chat/2026-05-20-foo → 'your-agent/chat/2026-05-20-foo' daily/2026-05-20/journal-entry-1 → 'daily/2026-05-20' transcripts/chat/funding-discussion → 'transcripts/chat/funding-discussion' people/alice → null ← codex H2 regression docs/quickstart → null F1 (Claude adversarial subagent): case-sensitivity drift across 3 sites. loadOverridesFromConfig in mode.ts is case-insensitive + whitespace-trimmed for 'search.graph_signals' values. But doctor's checkGraphSignalsCoverage (doctor.ts:899) AND search-stats's readGraphSignalsStats (search.ts:288) used case-sensitive compare. User sets `search.graph_signals TRUE`: production enables the feature, but doctor + search-stats both silently report disabled. Operators lose the only observability surface for the new feature on values like 'True'/'TRUE'. Fix: trim + lowercase parity at both sites. Mirror the parser's semantic. Also case-normalized `search.mode` reads at both sites for the same divergence class. Tests: - sessionPrefix block rewritten with 7 cases covering chat marker + date anchor + entity dirs (now-NULL) + degenerate (no /). - Added regression test pinning codex H2: people/alice + people/bob + people/charlie do NOT get diversified. - graph-signals-eval.test.ts drops `as any` — typed field works. - Existing tests using `chat/a`/`chat/b` updated to session-shaped `media/2026-05-20/chunk-a` so the date anchor actually fires. 111/111 graph-signals + doctor + search-stats tests pass. Typecheck clean. Plan ref: /ship adversarial review v0.40.4.0 (codex H1, H2; Claude F1). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.4.0 TODOs: capture 11 LOW adversarial findings for v0.41+ Codex L1 (audit window underreport) + Claude F2/F3/F5-F8/F11/F12/F14/F16 from /ship adversarial review. None are load-bearing; all captured under 'v0.40.4 adversarial review LOW findings — captured for v0.41+'. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: update project documentation for v0.40.4.0 - README: surface v0.40.4.0 graph signals + --explain in Hybrid search capability - CLAUDE.md: annotate engine.ts getAdjacencyBoosts, new graph-signals.ts / explain-formatter.ts / audit/audit-writer.ts, plus hybrid.ts post-fusion 4th stage, mode.ts graph_signals knob + KNOBS_HASH 3→4, cli-options.ts --explain flag, search stats + doctor coverage check - llms-full.txt: regenerated from CLAUDE.md per the build:llms chaser rule Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(ci): pin bun-version to 1.3.13 across all workflows setup-bun action with `bun-version: latest` calls the GitHub API (https://api.github.com/repos/oven-sh/bun/git/refs/tags) to resolve the tag. CI started failing today with HTTP 401 "Bad credentials" even though the action receives a token (visible as `token: ***` in the run log). Pinning the version eliminates the API call entirely. Affected workflows: test.yml, e2e.yml, release.yml, heavy-tests.yml (5 invocations total). Pinned to 1.3.13 — matches package.json engines (`bun >= 1.3.10`) and the version v0.40.4.0 was developed against. Bump cadence: when a new bun version is required, update this pin in one PR. Trading "always-latest" for "always-deterministic" is the right trade for a 5-shard CI matrix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-23 10:01:08 -07:00
Garry Tan	43608c1856	v0.40.3.0 feat: contextual retrieval + cache invalidation gate + 4 deferred-item closures (#1323) ... * v0.40.3.0 T1: migration v81 + CRMode type substrate Five additive columns + Page/SourceRow type extensions + CRMode discriminated union land the schema foundation for v0.40.3.0 contextual retrieval. All columns are NULL-tolerant; existing rows continue working unchanged until the post-upgrade reembed sweep catches up. Schema (migration v81 + schema.sql + pglite-schema.ts mirror): - pages.contextual_retrieval_mode TEXT NULL — tier the page was last embedded under. NULL on pre-v81 rows; drift detection treats NULL as 'none' for reindex predicates. - pages.corpus_generation TEXT NULL — composite hash of (synopsis_prompt_version, haiku_model, title_wrapper_version, embedding_model) per D27 P1-5. Document-side provenance for the v0.40.3.0 query_cache.page_generations invalidation contract. - sources.contextual_retrieval_mode TEXT NULL — per-source override. CLI-write-only per D15 security gate. - sources.trust_frontmatter_overrides BOOLEAN DEFAULT FALSE — per-source mount-frontmatter trust gate per D15. Host source (id='default') is always trusted in the resolver regardless of column value. - query_cache.page_generations JSONB DEFAULT '{}' — D27 P1-5 invalidation contract foundation. Per-row tag of {page_id: corpus_generation} so lookup can LEFT JOIN against current pages and exclude stale rows. Types (src/core/types.ts + src/core/sources-ops.ts): - New CR_MODES = ['none', 'title', 'per_chunk_synopsis'] as const + CRMode type union + isCRMode() type guard for parsing untrusted frontmatter / config values. - Page interface extended with contextual_retrieval_mode + corpus_generation (optional, NULL-tolerant for pre-v81 rows). - SourceRow interface extended with contextual_retrieval_mode + trust_frontmatter_overrides (optional for pre-v81 brains). Bootstrap coverage: - All four pages/sources columns are in PGLITE_SCHEMA_SQL CREATE TABLE bodies (fresh installs get them at initSchema time). - query_cache.page_generations is exempt because query_cache itself is migration-created (added in v55, not in PGLITE_SCHEMA_SQL). Same rationale as the existing query_cache.knobs_hash exemption. Pinned by the migrate.test.ts v81 round-trip + the schema-bootstrap-coverage parser (which also gained the query_cache.page_generations exemption). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T2: MARKDOWN_CHUNKER_VERSION 2→3 (contextual wrapper signal) Bumps the markdown chunker version so the post-upgrade reembed sweep finds every page on the old chunker version and re-embeds it through the new contextual-retrieval wrapper path. Chunk boundaries themselves are unchanged from v2 — the bump forces re-embed (not re-chunk) so existing pages pick up the wrapper without recomputing chunk splits. JSDoc on MARKDOWN_CHUNKER_VERSION updated to document the v3 semantic ("chunks embed with optional contextual retrieval wrapper per Anthropic's published methodology"). Pins the dependency between the chunker version bump and the upcoming src/core/contextual-retrieval-service.ts (T5). Test fixture in test/chunkers/recursive.test.ts updated to assert v3 with a brief comment on the bump rationale so future contributors see the v0.40.3.0 reason inline. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T3: pure modules — resolver, wrapper, synopsis, audit Four new pure modules under src/core/ that the upcoming service layer (T5) and Minion handler (T6) compose. All four are testable in isolation; no engine I/O, no filesystem reads outside the synopsis source-text fallback chain (which is invoked by the service, not the modules themselves). src/core/contextual-retrieval-resolver.ts (D5+D6+D15+D26 P0-4): - resolveContextualRetrievalMode() walks the three-source override chain: page frontmatter > source row > global mode bundle. Returns a tagged result with source attribution + invalid_frontmatter_value (D13) + frontmatter_rejected_untrusted_mount (D15) for doctor surfacing. - crModeDistinct() helper for D26 P0-4 IS DISTINCT FROM semantics on app-side CRMode comparisons (NULL-aware, defeats the != misses NULL drift bug Codex pass 2 caught). - HOST_SOURCE_ID = 'default' always trusted regardless of trust_frontmatter_overrides; mount sources require the explicit flag per D15 security gate. src/core/embedding-context.ts (D20-T1 + D20-T4 + Codex T5 title-weakness): - buildContextualPrefix(title, synopsis) → null | wrapped block. Handles title-only, summary-only, both, or neither. - wrapChunkForEmbedding(text, prefix, chunkSource) short-circuits on chunk_source='fenced_code' per D20-T4 (code chunks inside markdown pages skip the wrapper — prepending page title to a code block doesn't help cross-modal retrieval). - sanitizeTitle/sanitizeSynopsis strip </context> (injection vector) and collapse whitespace + cap at 300 chars. - extractFirstTwoSentences() pure regex with CJK_SENTENCE_DELIMITERS from src/core/cjk.ts for the title-tier free fallback path. src/core/page-summary.ts (D27 P1-2 + D27 P1-4 + D21 reversal): - generatePerChunkSynopsis() routes through gateway.chat(tier='utility'). - Richer failure envelope per D27 P1-2: refusal/empty/malformed (→ D14 page-level fall-back) vs auth_failure/rate_limit/timeout/network/ provider_5xx (→ retry per gateway, or throw to Minion retry). - buildSynopsisCacheKey() composes the LRU key per D27 P1-4: (content_hash, chunk_index, corpus_generation, source_text_hash). - DELIBERATELY no calibration injection — D21 reversed D7's calibration- aware acceptance. Mutable answer-time bias tags don't belong in static document vectors. Query-side personalization is the v0.41+ home. src/core/audit-synopsis.ts (D17, mirrors v0.35.0.0 rerank-audit precedent): - Failure-only JSONL writer at ~/.gbrain/audit/synopsis-failures-YYYY-Www.jsonl with ISO-week rotation. Deliberately no success logging (10K+ pages per backfill would generate 10K+ JSONL rows of noise; failure signal is the actionable one). - summarizeSynopsisFailures() aggregator returns SynopsisFailureSummary for doctor's synopsis_refusal_rate check. Clean typecheck across the four modules. Tests land in T14 alongside the service + Minion handler so the test layer can integrate the full path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T4: ModeBundle.contextual_retrieval + KNOBS_HASH_VERSION 3→4 Three-tier wrapper ladder gated by search.mode lands in the bundle. The per-mode defaults match the cost-tier philosophy (D2): conservative → 'none' (minimum surface) balanced → 'title' (free at runtime; pure string concat) tokenmax → 'per_chunk_synopsis' (Anthropic's published method) Plus the D18 soft kill switch (contextual_retrieval_disabled) so a single config-key flip neutralizes wrapping for queries AND new embeds without touching the migration path. src/core/search/mode.ts: - ModeBundle: contextual_retrieval: CRMode + contextual_retrieval_disabled. - All three frozen MODE_BUNDLES updated with the per-tier defaults. - SearchKeyOverrides + SearchPerCallOpts: both fields optional in the per-key config + per-call surfaces. - resolveSearchMode's pick chain threads both new fields through the standard per-call > per-key > mode bundle precedence ladder. - KNOBS_HASH_VERSION 3→4. Two new entries appended to knobsHash() parts list (append-only per CDX2-F13 convention): cr=${cr_mode} + crd=${0|1}. A query against a tokenmax-mode brain can no longer be served from a cache row written when the brain was on balanced — they sit in different embedding spaces. - SEARCH_MODE_CONFIG_KEYS: 'search.contextual_retrieval' + 'search.contextual_retrieval_disabled' added. - loadOverridesFromConfig reads both keys; CR_MODES guard rejects typos (drift typos still fall through to mode default per D13 sync-failure semantics; this is the no-typo path). - Imports CR_MODES + CRMode from src/core/types.ts. src/commands/search.ts: - KNOB_DESCRIPTIONS picks up the two new entries so `gbrain search modes` dashboard renders them with description copy. test/search-mode.test.ts: - Three canonical bundle tests updated with the per-tier CR defaults. - KNOBS_HASH_VERSION expectation bumped 3→4 with inline rationale. Clean typecheck + 42 search-mode tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T8: NULL→non-NULL upsert race fix (D24, closes v0.35.x TODO) Two writers racing on the same chunk (autopilot sync + manual `embed --stale` + contextual reindex) previously raced last-writer-wins via the text- unchanged branch's `COALESCE(EXCLUDED.embedding, content_chunks.embedding)`. Pre-v0.40.3 the cost of an overwrite was one wasted ~$0.000001 text- embedding-3-large call. With v0.40.3's per-chunk Haiku synopsis on tokenmax, the cost rises ~300x to ~$0.0003 per overwritten chunk plus the discarded synopsis work. On a 10K-page tokenmax brain, a few percent overwrite rate during concurrent backfill+sync wastes $1-5 of Haiku spend silently. Fix (mirrored exactly in postgres-engine.ts + pglite-engine.ts so both engines stay parity-pinned): embedding = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.embedding WHEN content_chunks.embedding IS NULL THEN EXCLUDED.embedding WHEN EXCLUDED.embedded_at IS NOT NULL AND (content_chunks.embedded_at IS NULL OR EXCLUDED.embedded_at > content_chunks.embedded_at) THEN EXCLUDED.embedding ELSE content_chunks.embedding END, embedded_at = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text AND EXCLUDED.embedding IS NULL THEN NULL WHEN content_chunks.embedding IS NULL AND EXCLUDED.embedding IS NOT NULL THEN EXCLUDED.embedded_at WHEN EXCLUDED.embedded_at IS NOT NULL AND (content_chunks.embedded_at IS NULL OR EXCLUDED.embedded_at > content_chunks.embedded_at) THEN EXCLUDED.embedded_at ELSE content_chunks.embedded_at END, The two columns move together via aligned CASE WHEN logic — embedding + embedded_at stay consistent so `embed --stale` (predicate `embedding IS NULL`) keeps working correctly. Behavior summary for the text-unchanged branch: - existing embedding NULL → take new (cold path, no race) - new is fresher (embedded_at > existing) → take new - otherwise → keep existing (slower writer with stale embedding loses) Closes the v0.35.x TODOS.md item that flagged this race pre-existing. v0.40.3 fold-in lands the fix when the wave amplifies the cost vector, per D24 in the eng-review pass. 100 pglite-engine tests pass + clean typecheck. E2E concurrent-writer test lands in T14 alongside the broader test suite. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T5: contextual-retrieval-service + two-phase build (D27 P1-1) Centerpiece service module. Single source of truth for "re-embed one page with the active CR mode" — composed by import-file.ts (sync time), reindex.ts (batch sweep), and the contextual-reindex-per-chunk Minion handler (T6). Closes the drift class Codex pass 2 P1-1 flagged: each consumer no longer hand-rolls the embed-then-stamp flow, so there's literally no way for them to diverge. src/core/contextual-retrieval-service.ts: - reembedPageWithContextualRetrieval() implements the D26 P0-2 two-phase build pattern. PHASE 1 (in-memory, no DB writes): - Load page + source + chunks - Resolve effective CR mode (resolver) with optional kill-switch short-circuit per D18 - 'none' tier: skip wrap, stamp column, return early (records page is up-to-date relative to current state so reindex sweep doesn't re-walk it) - 'title' tier: pure string concat with sanitized title prefix - 'per_chunk_synopsis' tier: read source text via fallback chain (D11), generate synopsis per chunk SEQUENTIALLY within page (D10), batch embedBatch ONCE per page (D27 P2-2). Rate-leasing hooks (acquireSynopsisLease/releaseSynopsisLease) supplied by the Minion handler; inline callers rely on gateway-level retry. - On refusal/empty/malformed (per D27 P1-2): RESTART PHASE 1 at 'title' tier — D14 page-level consistency (whole page demoted, no mid-state on disk). PHASE 2 (single DB transaction): - tx.upsertChunks() — chunk_text stays canonical per D20-T1; only the wrapped string went to the embedder, not into the column. - tx.updatePageContextualRetrievalState() — stamps both columns atomically with PHASE 1 chunk writes. - computeCorpusGeneration() composes the document-side provenance hash per D27 P1-5: sha256(cr_mode + synopsis_prompt_version + haiku_model + title_wrapper_version + embedding_model_tag).slice(0,16). Future prompt edits or model bumps invalidate prior cache rows via the query_cache.page_generations LEFT JOIN (lands in T11). - computeSourceTextHash() for D27 P1-4 synopsis cache key composition. - expectedModeForPageSourceOnly() helper for the T9 reindex sweep predicate. - ReembedPageResult discriminated union: success | skipped (4 reasons) | page_fallback (refusal triggered D14) | transient_error | permanent_error. Each consumer dispatches on `kind` to decide retry / surface / commit. New engine method (added to BrainEngine interface + both engines): - updatePageContextualRetrievalState(slug, sourceId, mode, corpusGeneration): narrow UPDATE of just the two CR-state columns + updated_at. Skips soft-deleted rows. Mirrors refreshPageBody's narrow-update pattern so we don't fire createVersion on every tier upgrade (which would bloat page_versions). Clean typecheck + 272 existing tests pass (no regressions). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T6: contextual_reindex_per_chunk Minion handler + protection Thin handler (D23) that wires the global Haiku rate-leaser (D26 P0-3) + delegates re-embed work to contextual-retrieval-service.ts (T5). One job per page (D10). Submitted by the mode-switch hook (T10), the reindex sweep (T9), and doctor --remediate (T13). src/core/minions/handlers/contextual-reindex-per-chunk.ts: - makeContextualReindexHandler(opts) factory closure. - Per-chunk Haiku call wrapped in acquireLease/releaseLease against the shared key 'anthropic:utility:contextual-synopsis'. Default RPM cap is 50 (Anthropic Haiku 4.5 published limit); operators on a tier with higher quota override via GBRAIN_CONTEXTUAL_HAIKU_RPM env var. - D27 P2-1 source-id derivation: payload carries only page_slug; handler loads the page row and uses its source_id as authoritative. Optional expected_source_id field on the payload triggers UnrecoverableError on mismatch (stale/malicious payload defense). - Result classification: success / page_fallback (D14) → ok transient_error → throw (Minion retries) permanent_error → UnrecoverableError → dead-letter - 60s poll-wait per Haiku call when the rate-lease is saturated; gives up with explicit error rather than blocking forever. src/core/minions/protected-names.ts: - contextual_reindex_per_chunk added to PROTECTED_JOB_NAMES with comment documenting the cost vector (1-50 Haiku calls per page, bulk MCP submission could drain user's Anthropic budget). src/commands/jobs.ts: - registerBuiltinHandlers wires the new handler via dynamic import. - Registered ABOVE autopilot-cycle so the handler is available when doctor --remediate proposes contextual_retrieval_coverage steps. Clean typecheck. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T7: import-file.ts wraps at embed time, stamps CR state columns import-file.ts now resolves the effective CR mode for each page at embed time and applies the wrapper inline. Per D20-T1 critical invariant, the stored chunk_text stays canonical (powers FTS, snippets, reranker, debug); only the wrapped string goes to the embedder. Inline path scope (cost-discipline choice): - title-tier: inline wrap is free (pure string concat). Applied directly. - per_chunk_synopsis tier: TOO EXPENSIVE for the inline import path (one Haiku call per chunk on every sync would compound into hours of blocking per `gbrain sync`). The inline path lands the page at the title tier; the Minion-driven contextual reindex (T6 handler) upgrades it to per_chunk_synopsis later when the user accepts the cost prompt in the mode-switch hook (T10). Per D3 explicit-consent contract. - 'none' tier (conservative mode, kill-switch disabled): no wrapping, raw chunk_text → embedder unchanged from pre-v40.3 behavior. Code chunks (chunk_source='fenced_code') always bypass wrapping per D20-T4 — wrapChunkForEmbedding short-circuits. Stamping (alongside putPage in the same transaction): - pages.contextual_retrieval_mode → tier the page was just embedded at - pages.corpus_generation → composite hash via computeCorpusGeneration from the service module. NULL when 'none' tier or noEmbed=true. Override chain: page frontmatter > source row > global mode bundle (D5+D6). Mount-frontmatter trust gate (D15) — currently lookup uses defaults for source row; future T9 reindex sweep + T10 mode-switch hook can pass a richer source row when the per-source override lands. Kill switch (D18): when search.contextual_retrieval_disabled=true, the resolver short-circuits to 'none' and the wrapper is skipped. Clean typecheck + 251 unit tests pass (migrate + pglite-engine + import-file all green). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T9: reindex --markdown extends to catch CR state drift `gbrain reindex --markdown` predicate widens from chunker_version drift alone to also catch contextual_retrieval_mode IS NULL — the v0.40.3.0 upgrade-path signal that a page has never been evaluated against the CR ladder (pre-v81 brains where the column is freshly NULL after the migration ran). Pages enter the sweep when EITHER: (a) chunker_version < MARKDOWN_CHUNKER_VERSION (existing behavior) (b) contextual_retrieval_mode IS NULL (new — D26 P0-1 + D26 P0-4 prep) Since chunker_version 2→3 (T2) already forces every pre-v40 page into (a), the IS NULL clause is effectively a belt-and-suspenders for the case where a brain upgrades migrate but somehow the chunker_version bump didn't propagate (concurrent upgrade race, manual SQL edit, etc.). The re-import path uses importFromContent with forceRechunk:true (existing v0.32.7 behavior) which bypasses the content_hash short- circuit so the v0.40.3.0 import-file.ts wrapper application path (T7) actually applies. Each re-imported page picks up the active CR tier and stamps contextual_retrieval_mode + corpus_generation atomically. Page-frontmatter overrides are honored at re-import time (importFromFile re-parses YAML and the resolver picks the per-page tier). The frontmatter- mismatch drift case Codex P0-1 called for (user removes override after initial import) is partially handled here via the IS NULL+forceRechunk path; a v0.41+ wave can add the explicit "frontmatter may contain override" candidate path if real users hit drift the current predicate misses. Clean typecheck + 230 unit tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T10: post-upgrade cost prompt explains contextual retrieval The existing post-upgrade-reembed.ts prompt fires automatically on `gbrain upgrade` because T2 bumped MARKDOWN_CHUNKER_VERSION 2→3. Prompt copy extended to explain WHY the re-embed is happening — without this, users see a "chunker-bump" prompt and wonder if it's a routine internal refresh vs the actual headline feature ship. formatReembedPrompt now appends a [contextual retrieval] line below the chunker-bump cost summary, mentioning that v0.40.3.0 wraps each chunk with its page title before embedding (Anthropic's published method). What the user sees on upgrade: [chunker-bump] Will re-embed ~N markdown pages via {model}, est. ~$X.XX, ~Ymin. Press Ctrl-C within Zs to abort. [contextual retrieval] v0.40.3.0 wraps each chunk with its page title before embedding (Anthropic's published method). Title-tier wrap is free at runtime (pure string concat, no Haiku) so the cost number stays unchanged from the chunker-bump-only case. The per-chunk Haiku synopsis tier is OPT-IN via `gbrain config set search.mode tokenmax` post-upgrade, which fires the contextual_reindex_per_chunk Minion handler (T6) for the backfill. T10 mode-switch hook in src/commands/config.ts (the explicit per-mode cost prompt UX on `gbrain config set search.mode tokenmax`) is deferred to v0.40.3.1 — the explicit-consent contract (D3) is satisfied by the existing post-upgrade prompt for the title-tier path that the wave ships by default. The Minion handler from T6 + the protected-name guard ensure that any direct Minion submission for the per-chunk path is gated on the CLI/doctor-remediate trust boundary. Kill switch (D18): the contextual_retrieval_disabled config key is honored at import time (T7) and in the service (T5) — when true, the resolver short-circuits to 'none' regardless of mode bundle. No hybridSearch changes needed: queries embed raw text already; the kill switch only affects NEW embeds. Existing wrapped vectors keep serving queries via cosine similarity (asymmetric retrieval is preserved). 11 upgrade-reembed-prompt tests pass + clean typecheck. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T11-T13: query cache notes + remediation note + doctor check T11 (query_cache.page_generations contract): the DB column shipped in T1 migration v81 + KNOBS_HASH_VERSION 4 bump in T4 invalidates the common-case cache contamination (full-brain mode upgrade). The LEFT JOIN read-side gate per Codex P1-5 — for the edge case where a brain is mid- reindex and some pages are stamped at corpus_generation N+1 while others are still at N — is deferred to v0.40.3.1. In practice, the post-upgrade reembed prompt fires automatically + completes before search resumes on healthy brains, so the edge case is narrow. CHANGELOG documents the limitation. T12 (generic RemediationStep contract): the existing recommendation registry shape (sync/embed/backlinks/extract hardcoded) is extended via the doctor check below rather than refactored to a generic registry. Codex P1-6 called for the refactor; v0.40.3.1+ can absorb it once a real second consumer requires the same registration shape. T13 (contextual_retrieval_coverage doctor check): - New checkContextualRetrievalCoverage() in src/commands/doctor.ts. - Two SQL signals: pages.chunker_version < current + pages.contextual_ retrieval_mode IS NULL. Single COUNT...FILTER query is cheap on every brain size. - Audit summary line: reads ~/.gbrain/audit/synopsis-failures-*.jsonl via the v0.40.3.0 audit-synopsis module (T3). >5% page-level fallback rate surfaces explicitly so operators see the Haiku refusal signal. - Paste-ready fix: `gbrain reindex --markdown` — the v0.32.7 + v0.40.3.0 sweep covers both chunker_version drift AND CR mode drift per T9. - Status: ok when fully aligned + no recent failures; warn when drift exists (with the paste-ready fix in the message). - Wired into the standard doctor run alongside the other v0.36+ checks (abandoned_threads, calibration_freshness, etc.). Sources/mounts CLI surfaces (set-cr-mode + trust-frontmatter) deferred — the post-upgrade-reembed prompt + the per-page frontmatter override path cover the v0.40.3.0 operational workflow. Per-source override CLI is a power-user feature that can ship in v0.40.4+ once real federated- brain users surface specific friction. 48 doctor tests pass + clean typecheck. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T14: 5 test files, 77 new tests, IRON-RULE regression coverage Test suite for the v0.40.3.0 contextual retrieval wave. 77 new test cases across 5 files, all green. Pins every IRON-RULE invariant end-to-end so future contributors can't silently regress the wave. test/contextual-retrieval-resolver.test.ts (29 tests): - 9-combo override matrix (page-fm > source-row > global, all permutations). - D15 mount-trust gate: host always trusted, mounts honor only when trust_frontmatter_overrides=true, rejected frontmatter surfaces via result.frontmatter_rejected_untrusted_mount for doctor. - D13 invalid frontmatter (typo + non-string + empty): falls through to source/global with raw value in invalid_frontmatter_value. - D18 kill switch: short-circuits to 'none' regardless of overrides. - D26 P0-4 crModeDistinct: NULL-aware comparison, matches SQL IS DISTINCT FROM semantics on every combination of NULL/defined args. test/embedding-context.test.ts (21 tests): - buildContextualPrefix: title-only, synopsis-only, both, neither. - wrapChunkForEmbedding: non-code wraps; D20-T4 fenced_code ALWAYS bypasses; null prefix passes through; image_asset wraps as text. - sanitizeTitle: </context> injection stripped (case-insensitive), whitespace collapsed, 300-char cap, trim semantics. - extractFirstTwoSentences: English boundaries, question marks, CJK delimiters, run-on cap, empty input, no-delimiter passthrough. - modeRequiresHaiku / modeRequiresWrapper guards. - D20-T1 IRON-RULE regression test: wrapping does not mutate input string reference (so caller's chunk_text safely flows to upsert). test/contextual-retrieval-service-pure.test.ts (16 tests): - computeCorpusGeneration: 16-char hex, deterministic, mode-sensitive, model-sensitive, TITLE_WRAPPER_VERSION stable. - computeSourceTextHash: D27 P1-4 cache invalidation key composition. - expectedModeForPageSourceOnly (T9 reindex predicate helper): kill switch returns none, source override beats global, invalid override falls through, all CR modes round-trip. test/audit-synopsis.test.ts (11 tests): - ISO-week filename rotation (stable for same week, different days). - logSynopsisFailure round-trip: kind, page_level_fallback flag, multi-event accumulation, detail 200-char cap. - summarizeSynopsisFailures aggregation: null on empty, by_kind counts, page_level_fallback_rate math. - Missing audit file returns empty (silent no-op). test/e2e/contextual-retrieval-pglite.test.ts (5 tests, hermetic PGLite + gateway stub): - IRON RULE #1 (D20-T1): wrapper text in embedder input but NEVER in content_chunks.chunk_text after import — pins the canonical chunk_text separation invariant end-to-end. - IRON RULE #2 (D14 stamping): pages.contextual_retrieval_mode AND pages.corpus_generation are set after every import. - IRON RULE: chunker_version stamps to current MARKDOWN_CHUNKER_VERSION (3 for v0.40.3.0). - D5 per-page frontmatter override: `contextual_retrieval: none` makes the embedder receive UNWRAPPED text; mode column stamped 'none'. - T9 reindex predicate: pages with contextual_retrieval_mode IS NULL enter the sweep regardless of chunker_version. 462 tests pass across all v0.40.3.0 + adjacent suites (migrate, pglite-engine, search-mode, doctor, import-file, upgrade-reembed-prompt, schema-bootstrap-coverage, recursive chunker, all five new files). Zero regressions, clean typecheck. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 T15: VERSION + CHANGELOG + migration self-repair + llms regen VERSION 0.37.11.0 → 0.40.3.0 with package.json sync. CHANGELOG entry follows the CLAUDE.md ELI10-lead voice rule: opens with "Your search now understands what each chunk is about, not just what words are in it," lays out the tier ladder with a real cost table, calls out the chunk_text storage separation (D20-T1) with a concrete example, and includes the "Things to watch" + "What we caught and fixed before merging" sections per the format spec. CHANGELOG also includes the canonical "To take advantage of v0.40.3.0" self-repair block with the manual `gbrain apply-migrations --yes` + `gbrain reindex --markdown` recovery path for users whose `gbrain upgrade` post-upgrade-reembed didn't fully fire. skills/migrations/v0.40.3.0.md walks the agent through the mechanical upgrade flow, the opt-up to tokenmax path with the realistic backfill cost table, the opt-out soft kill switch flip, and the per-page frontmatter override with the D15 mount-trust note. Matches the v0.13.0 + v0.32.7 migration doc structure so agent muscle memory works. llms-full.txt + llms.txt regenerated via `bun run build:llms` to pick up the CHANGELOG + migration doc additions. test/build-llms.test.ts passes. Also moved test/audit-synopsis.test.ts → test/audit-synopsis.serial.test.ts to satisfy the check-test-isolation lint (the test mutates GBRAIN_AUDIT_DIR via beforeAll/afterAll for a fixture dir, which the parallel runner forbids in *.test.ts files; serial quarantine is the canonical fix per CLAUDE.md test-isolation rules). `bun run verify` passes (typecheck + 4 CI gate checks). 469 tests across all v0.40.3.0 + adjacent suites pass with 0 failures. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.3.0 test gaps: doctor check coverage + concurrent race regression Post-T15 test gap-fill: covers the two highest-leverage spots that the T14 suite didn't exercise. test/contextual-retrieval-doctor.serial.test.ts (8 tests, .serial because the doctor check reads the audit JSONL via GBRAIN_AUDIT_DIR env mutation): - empty-brain → ok - fully-aligned brain (chunker_version current + mode stamped) → ok - chunker_version drift → warn with paste-ready `gbrain reindex --markdown` - NULL mode column → warn surfaces "never evaluated against CR ladder" - both drift conditions together → warn with both messages - soft-deleted pages NOT counted (deleted_at filter works) - non-markdown (code) pages NOT counted (page_kind filter works) - audit JSONL refusal event surfaces in the failure-summary line test/e2e/concurrent-embed-race.test.ts (3 tests, D24 regression guard): - cold path: existing embedding NULL → take new (no-race case) - IRON RULE: fresher write wins over stale write when text unchanged. Pre-fix this would have last-writer-wins via COALESCE; post-fix the fresher embedded_at survives. Pinned by raw SQL upsert with an explicit -5min embedded_at to simulate the slower writer. - text change with no new embedding → both embedding + embedded_at reset to NULL (consistent state so embed --stale picks up). Cross-shard contamination fix: race test calls configureGateway with embedding_dimensions=1536 BEFORE initSchema so the PGLite vector column sizes consistently regardless of what other tests in the same shard process configured first. Without this, running the race test alongside the pglite-e2e test triggered "expected 1280 dimensions, not 1536" when the gateway was left in its default ZE-1280 state by a prior file. `bun run verify` passes (typecheck + 5 CI gate checks). 88 tests pass across all v0.40.3.0 + new gap-fill files in one combined run; zero shared-state contamination. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.40.5.0 T2: schema — v90 contextual_retrieval_columns + v91 trigger + index Migration v90 (renamed from v0.40.3.0 v81 on master merge per D2/D7): - 5 additive columns (pages.contextual_retrieval_mode, pages.corpus_generation, sources.contextual_retrieval_mode, sources.trust_frontmatter_overrides, query_cache.page_generations) for the contextual retrieval wave. Migration v91 (NEW per D6 + codex #4 + codex #8): - pages.generation BIGINT NOT NULL DEFAULT 1 (per-page generation counter) - query_cache.max_generation_at_store BIGINT NOT NULL DEFAULT 0 (Layer 1 bookmark) - bump_page_generation_fn() trigger function: - BEFORE INSERT: NEW.generation := COALESCE(MAX(generation), 0) + 1 — codex #4 INSERT coverage so cache rows stored before a new page existed invalidate correctly. - BEFORE UPDATE: bumps generation only when allow-list columns IS DISTINCT FROM (compiled_truth, timeline, frontmatter, deleted_at, contextual_retrieval_mode, title, type, page_kind, corpus_generation, content_hash) per D6 widened to catch user-visible mutations. - CREATE INDEX CONCURRENTLY pages_generation_idx ON pages (generation) so MAX(generation) for the bookmark check is O(log N) — codex #8 confirmed plain btree, no DESC necessary. Mirrored in src/schema.sql, src/core/pglite-schema.ts CREATE TABLE body (trigger included so fresh PGLite installs get it from the schema blob, not just migration replay). Extended REQUIRED_BOOTSTRAP_COVERAGE with pages.contextual_retrieval_mode, pages.corpus_generation, sources.contextual_retrieval_mode, sources.trust_frontmatter_overrides, pages.generation. Probes added to applyForwardReferenceBootstrap on both engines + matching ALTER blocks for pre-v90/pre-v91 brains. COLUMN_EXEMPTIONS extended: query_cache.max_generation_at_store (same rationale as page_generations — query_cache is migration-only, not in PGLITE_SCHEMA_SQL). Test results: - bun test test/migrate.test.ts: 140 pass / 0 fail - bun test test/schema-bootstrap-coverage.test.ts: 9 pass / 0 fail - bun run typecheck: clean * v0.40.5.0 T3: cache gate — query-cache-gate.ts + lookup/store rewrites New pure module src/core/search/query-cache-gate.ts: - buildPageGenerationsSnapshot(engine, pageIds) builds the {pageId: gen} snapshot + MAX(generation) bookmark in one round trip via UNION ALL. Pre-v91 brains (no generation column) fall back to empty snapshot + zero bookmark — backward compat with legacy rows preserved. - validateCacheRowAgainstPages() — pure validator for unit testing. - CACHE_GATE_WHERE_CLAUSE exported as a SQL fragment that lookup() embeds in its WHERE clause. Two-layer gate per D11: Layer 1 (cheap): (SELECT MAX(generation) FROM pages) <= qc.max_generation_at_store Layer 2 (per-page): jsonb_each + LEFT JOIN pages to detect deletes + bumped pages on the cached result set. Legacy compat: rows with empty {} snapshot are vacuously valid (Layer 2 short-circuits) — IRON-RULE pinned. query-cache.ts wiring: - lookup() table-aliased to `qc` so the gate fragment can reference qc.max_generation_at_store + qc.page_generations. WHERE clause adds `AND ${CACHE_GATE_WHERE_CLAUSE}` after the existing similarity + TTL + knobs_hash filters. - store() captures the snapshot via the pure helper, then INSERTs both page_generations JSONB and max_generation_at_store BIGINT alongside the existing columns. ON CONFLICT (id) DO UPDATE refreshes both. Test coverage (15 unit + 6 e2e): - test/query-cache-gate.test.ts: 15 cases covering pure validator branches (vacuous valid, bookmark short-circuit, single/multi/partial bumps, deleted page, codex D11 critical case), PGLite-backed snapshot builder (empty pageIds, populated pageIds, integer JSONB shape, non-existent IDs skipped, bump-after-update), SQL shape regression on CACHE_GATE_WHERE_CLAUSE. - test/e2e/cache-gate-pglite.test.ts: 6 cases covering store → HIT, content UPDATE → MISS, INSERT new page → HIT (codex #4 case where bookmark fires but snapshot intact serves correctly), legacy row → HIT (IRON-RULE backward compat), soft-delete → MISS (trigger path), multi-page partial bump → MISS. Test results: - bun test test/query-cache-gate.test.ts test/query-cache.test.ts test/query-cache-isolation.test.ts test/e2e/cache-gate-pglite.test.ts: 33 pass / 0 fail - bun run typecheck: clean Note: hard-delete (raw DELETE FROM pages) is not covered by the trigger (BEFORE INSERT OR UPDATE doesn't fire on DELETE). Production uses soft-delete via deleted_at (trigger allow-list catches NULL → timestamp distinction). Hard-delete via admin-only `gbrain pages purge-deleted` is best-effort cache-wise — acceptable for the rare admin path. * v0.40.5.0 T5: mode-switch UX at gbrain config set search.mode New module src/core/search/mode-switch-ux.ts: - summarizeTransition(old, new): pure 5-cell matrix (no_change / narrowing / broadening / tokenmax_opt_in / invalid_new_mode) + reindex command + cost estimate + paste-ready callout lines. - probeWorkerAvailable(engine): worker liveness proxy. gbrain has no minion_workers heartbeat table yet (B7 follow-up from v0.19.1), so we use a proxy: minion_jobs activity within 10-min query window. Within 2 min = active; >2min but <10min = stale; nothing = never_seen. - buildReindexIdempotencyKey(): content-stable per codex D12 Bug 1. Pattern: cr-backfill:<source_id>:<chunker_version>:<mode>. NOT timestamp-based — two retries against same brain state dedupe. - runModeSwitchUx(): orchestrator. Honors GBRAIN_NO_MODE_SWITCH_UX=1 (full skip), non-TTY (print paste-ready hints to stderr), yesFlag (auto-submit reindex). For tokenmax_opt_in + TTY + worker probe active: submits via MinionQueue.add with allowProtectedSubmit=true. For probe = stale or never_seen: loud-fail per D3 with a "start a worker OR run inline" recovery hint — closes the silent-stall footgun. src/commands/config.ts hook (~30 LOC): - Captures the OLD search.mode BEFORE setConfig so summarizeTransition classifies correctly. - Fires runModeSwitchUx() AFTER setConfig persisted, wrapped in try/catch so UX failures never break the config-set that already landed. - Best-effort: failures emit `[mode-switch] UX hook failed (non-fatal)` to stderr. Test coverage (18 cases): - summarizeTransition: 8 cases covering all 5 transition kinds + null inputs + tokenmax-as-first-set + invalid mode. - probeWorkerAvailable: 4 cases via real PGLite — never_seen / active / stale (seeded via minion_jobs) + threshold constant assertion. - buildReindexIdempotencyKey: 6 cases pinning content-stable contract (codex D12 Bug 1) — identical inputs match, different inputs differ, consecutive calls match despite time delta (NOT timestamp-based). Test results: - bun test test/mode-switch-ux.test.ts: 18 pass / 0 fail - bun run typecheck: clean * v0.40.5.0 T6: gbrain mounts {enable,disable,trust-frontmatter,untrust-frontmatter} Four new mounts CLI verbs per D4: - gbrain mounts enable <id> — re-enable a disabled mount - gbrain mounts disable <id> — toggle off without removing - gbrain mounts trust-frontmatter <id> — let this mount's per-page contextual_retrieval_mode frontmatter override the source default. Off by default for mounted brains; host is always trusted. - gbrain mounts untrust-frontmatter <id> — clear the trust flag. Implementation: - src/core/brain-registry.ts MountEntry interface extended with trust_frontmatter_overrides?: boolean. loadMounts() projection threads the field through with default false (mounts opt in explicitly per D4 + D15 security posture). - src/commands/mounts.ts: new runSetMountFlag() helper handles all 4 verbs via a shared file-write path. Missing-mount loud rejection (GBrainError with list-hint). Host brain rejection. Idempotent: no-op when current value already matches. Cache refresh after each write so host agents see the new flag immediately. Test infrastructure: - GBRAIN_MOUNTS_PATH env override on getMountsPath() in BOTH brain-registry.ts AND mounts.ts (the latter has its own copy — two source-of-truth paths). Reason: libuv caches homedir() on some platforms, so withFakeHome's HOME mutation isn't picked up by tests calling runMounts(). Production callers don't set the env. Test coverage (5 new cases): - enable → disable → enable cycle persists - trust-frontmatter → untrust → trust cycle preserves other fields - missing mount id → loud rejection with list-hint (closes the critical gap from idempotent-pebble Failure Modes table) - host brain rejection: cannot trust-frontmatter "host" - enable on already-enabled mount: no-op (idempotent) Test results: - bun test test/mounts-cli.test.ts test/brain-registry.serial.test.ts: 54 pass / 0 fail - bun run typecheck: clean * v0.40.5.0 T7: gbrain sources set-cr-mode + missing-source loud rejection New verb `gbrain sources set-cr-mode <id> <mode>` per D5: - Mode argument validated against CR_MODES via isCRMode (closed enum: none | title | per_chunk_synopsis). - "unset" / "default" / "" clears the column to NULL (falls through to the global search.mode bundle). - Loud rejection on: - Missing id/mode → exit 2, prints usage - Invalid mode → exit 2, lists valid options - Missing source id → exit 4, paste-ready `gbrain sources list` hint (closes the idempotent-pebble Failure Modes critical gap) src/commands/sources.ts wired into the switch dispatch + help text updated. isCRMode + CR_MODES lazy-imported per existing import pattern in this file. Test coverage (10 cases): - happy path for all 3 valid CRMode values - unset path via "unset" + "default" both clear to NULL - invalid mode → exit 2 + no mutation - missing source id → exit 4 - missing arguments → exit 2 with usage - missing mode (only id) → exit 2 + no mutation - round-trip preserves other fields (name) Test results: - bun test test/sources-set-cr-mode.test.ts: 10 pass / 0 fail - bun run typecheck: clean * v0.40.5.0 T8: RemediationStep refactor + makeRemediationStep factory New canonical module src/core/remediation-step.ts: - RemediationStep interface (lifted from brain-score-recommendations.ts). Same shape; rename to "Step" suffix per D6 for clarity ("a step in a remediation plan"). - RemediationSeverity + RemediationStatus type re-exports. - canonicalJson(value): zero-dep canonical serialization — sorts object keys recursively before stringify. Per codex D12 Bug 2: identical logical params hash identically regardless of insertion order. - idempotencyKey(source, job, params): shape <source>:<job>:sha8(canonicalJson(params)). Lifted from the legacy inline idemKey helper so future check authors don't drift. - makeRemediationStep(opts): canonical factory. Defaults id to the idempotency key (override for human-readable like 'sync.repo'). Status defaults to 'remediable'. All check authors should use this; hand-rolling is the drift hazard the refactor closes. src/core/brain-score-recommendations.ts: - Removed the local Remediation + RemediationSeverity + RemediationStatus definitions. - Re-exports them from remediation-step.ts so existing callers (e.g. doctor.ts) still resolve. Also re-exports Remediation as an alias for RemediationStep so import paths can migrate gradually. - Imports type Remediation alias internally so the (substantial) existing computeRecommendations body keeps compiling without sed pass. Test coverage (17 cases): - canonicalJson: key-ordering determinism (3 cases), nested objects, array order preservation, primitive types, codex D12 Bug 2 regression - idempotencyKey: shape regex, content invariance, key-ordering invariance, source/job/params differentiation - makeRemediationStep: default id, explicit id override, default status, canonical-JSON invariance, all-opts threadthrough - back-compat: `import { Remediation } from brain-score-recommendations` still resolves to RemediationStep (compile + runtime check) Test results: - bun test test/remediation-step.test.ts: 17 pass / 0 fail - bun test test/brain-score-recommendations.test.ts test/doctor.test.ts: 70 pass / 0 fail (back-compat preserved) - bun run typecheck: clean Per D6 + D8: T8b in next commit wires lint, integrity, sync_failures doctor checks to emit RemediationStep via the new factory. * v0.40.5.0 T8b: RemediationStep consumers — integrity + sync_failures + 3 Minion handlers Doctor checks now emit RemediationStep via makeRemediationStep(): - `integrity` check (when bareHits > 0) emits integrity-auto step. Severity escalates to 'high' when bareHits > 50. Deterministic; $0 cost. - `sync_failures` check (when unacked > 0) emits sync-retry-failed step. Severity escalates to 'high' when count >= 10. Content-stable params (failure_count + oldest_failure timestamp) per codex D12 Bug 2. - sync-skip-failed DELIBERATELY NOT emitted per D12 Bug 3 (auto-skipping failed syncs hides data loss). Operators retain `gbrain sync --skip-failed` as a direct CLI option. Lint doctor check NOT wired — there is no `lint` check in doctor.ts today; the lint workflow is the standalone `gbrain lint` command. Adding a doctor lint check is a v0.41+ TODO when it justifies its own complete section. Three new Minion handlers in registerBuiltinHandlers (NOT in PROTECTED_JOB_NAMES — they're thin wrappers around already-shipping CLI commands, idempotent, no shell exec, MCP-safe): - lint-fix → runLintCore({ fix: true }) - integrity-auto → runIntegrity(['auto']) - sync-retry-failed → runSync(['--retry-failed']) Check.remediation field shape upgrade: - Was: inline Array<{...}> shape. - Now: RemediationStep[] from the canonical src/core/remediation-step.ts. Check authors `import { makeRemediationStep }` and emit through the factory. Test results: - bun test test/doctor.test.ts: 48 pass / 0 fail (zero regression on the doctor surface; new remediation fields are additive) - bun run typecheck: clean * v0.40.5.0 T11: capture-generation regression test (D3 + codex #5) The v0.38 ingestion cathedral added a new write path to pages via the `ingest_capture` Minion handler. The v0.40.5.0 cache-invalidation gate relies on pages.generation being bumped by EVERY write path via the BEFORE INSERT OR UPDATE trigger. This file pins that the new v0.38 capture write path correctly bumps generation through three scenarios: 1. INSERT path (codex #4 INSERT coverage): ingest_capture with a fresh slug creates a page with generation = MAX(generation) + 1 so any cache row stored before the new page existed has its bookmark fire. 2. UPDATE path: ingest_capture with an existing slug + new content → trigger fires on content-column IS DISTINCT FROM and bumps generation. 3. Idempotent UPDATE: capture with the SAME content → trigger short-circuits, no bump. Cache freshness preserved on re-runs. Per codex #5 strengthening: noEmbed: true is set explicitly so the test doesn't require API keys (test runs against pure PGLite). Test results: - bun test test/e2e/capture-generation-regression.test.ts: 3 pass / 0 fail - bun run typecheck: clean * v0.40.5.0 T9: docs — CHANGELOG fold-in + CLAUDE.md + migration skill + llms regen Single combined v0.40.5.0 CHANGELOG entry folds in v0.40.3.0 contextual retrieval content + v0.40.5.0 wave additions (cache gate + mode-switch UX + mounts/sources CLI + RemediationStep refactor). Voice per CLAUDE.md: ELI10 lead, plain language, paste-ready commands, tier table, "Things to watch", "What we caught and fixed before merging" (summarizes the 8 codex findings + 3 design decisions in user-facing terms), "Itemized changes", "## To take advantage of v0.40.5.0" mandatory self-repair block. CLAUDE.md: new section "Key commands added in v0.40.5.0 (contextual retrieval + cache gate + 4 CLI verbs)" listing the 4 new mount verbs, sources set-cr-mode, mode-switch UX, KNOBS_HASH_VERSION bump, 3 new Minion handlers, and the 3 new modules (remediation-step, query-cache-gate, mode-switch-ux). skills/migrations/v0.40.5.0.md: new migration skill with feature_pitch frontmatter for the auto-update agent. Documents the 6 master commits merged in, migration v90 (renumber from v81) + v91 (trigger), the optional opt-up to tokenmax, per-source CR mode overrides, mount frontmatter trust, the soft kill switch, and the backward-compat guarantees. bun run build:llms refreshed llms.txt + llms-full.txt: - llms.txt: 4314 bytes - llms-full.txt: 578257 bytes Test results: - bun test test/build-llms.test.ts: 7 pass / 0 fail (committed bundles byte-match generator output) * v0.40.5.0 T10: fix 5 unit-suite drift failures from the wave KNOBS_HASH_VERSION bumped 4→5 per D8 (sequenced behind salem's pending v=4 graph-signals work). Three test files held stale ==3 / ==4 assertions: - test/search-mode.test.ts: assertion + comment updated to v=5. - test/search/knobs-hash-reranker.test.ts: assertion + describe name updated to v=5 ladder. - test/cross-modal-phase1.test.ts: assertion + name updated to v=5. reindex.test.ts "skips pages already at current chunker_version" — the v0.40.3.0 reindex predicate (`chunker_version < CURRENT OR contextual_retrieval_mode IS NULL`) caught the should-skip page because its CR mode was NULL. Fixed by seeding `contextual_retrieval_mode = 'title'` on the should-skip row. reindex.test.ts "idempotent: re-run on a fully-updated brain reports nothing to do" — by design, `--no-embed` reindex bumps chunker_version but skips CR-state stamping (import-file.ts:457-466 documents this). Fixed by manually stamping `contextual_retrieval_mode = 'title'` between the first and second reindex calls so the brain matches the "fully updated" state the idempotency test name implies. Production embed flow stamps both in one pass; the test uses --no-embed only to avoid requiring API keys. Test results: - bun run verify (typecheck + 4 pre-checks): clean - bun run test: 9482 pass / 0 fail / 0 skip across 410s * v0.40.3.0: rename version from 0.40.5.0 → 0.40.3.0 (clean slot above master) Master is at v0.40.2.0; v0.40.3.0 is genuinely the next free slot. The wave was originally planned as v0.40.5.0 sequenced behind salem (PR #1300 = v0.40.4.0) but the user is shipping THIS branch as v0.40.3.0 because: 1. v0.40.3.0 IS the canonical version slot for the contextual retrieval cathedral (matches branch name garrytan/v0.40.3.0-contextual-retrieval). 2. Master is at v0.40.2.0 — v0.40.3.0 is the immediate next slot, not a collision. 3. salem's v0.40.4.0 + any v0.40.5.0 work sit ON TOP of this in the landing train, not under it. Mechanical rename only — no content changes from the v0.40.5.0 commit sequence (T1-T11 wave is preserved verbatim, just relabeled): - VERSION + package.json: 0.40.5.0 → 0.40.3.0 - bun.lock: refreshed (no dep changes) - CHANGELOG.md: ## [0.40.5.0] header → ## [0.40.3.0] + body references - skills/migrations/v0.40.5.0.md → skills/migrations/v0.40.3.0.md (previous v0.40.3.0.md file overwritten with the richer T9 content) - CLAUDE.md: "Key commands added in v0.40.5.0" → "v0.40.3.0" - 30 source + test files: comment references swept via sed s/0.40.5.0/0.40.3.0/g - llms.txt + llms-full.txt: regenerated Migration numbering UNCHANGED: v90 (renamed from original v81 because master took v82-v88) and v91 (new trigger migration) stay at v90/v91 — the version slot is orthogonal to the migration ledger collision. KNOBS_HASH_VERSION = 5 stays — sequenced behind master's v=4 schema-pack work; salem's v=4 graph-signals will rebump to v=5 if it lands first. Test results after rename: - bun run verify: clean (typecheck + 7 pre-checks) - bun run test: 9482 pass / 0 fail / 0 skip Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(migrate): v91 CREATE INDEX CONCURRENTLY can't run inside a transaction (CI Tier 1) CI Tier 1 (Mechanical) failed on real Postgres with: ERROR: CREATE INDEX CONCURRENTLY cannot run inside a transaction block STATEMENT: <v91 multi-statement SQL block including CREATE INDEX CONCURRENTLY ...> Root cause: postgres.js's multi-statement `.unsafe()` wraps the entire block in an implicit transaction. `transaction: false` on the migration entry doesn't help — the implicit wrap happens at the driver layer, below the migration runner. CONCURRENTLY refuses to run inside any transaction. Fix: rewrite v91 using the v14 pages_updated_at_index handler pattern — `sql: ''` + `handler:` function that splits the work into separate `engine.runMigration()` calls: 1. Columns + trigger function + trigger (single multi-statement runMigration — ALTER/CREATE FUNCTION/CREATE TRIGGER are transaction-safe). 2. On Postgres only: pre-drop invalid index remnant via `pg_index.indisvalid` (matches v14 pattern for retry safety after a failed CONCURRENTLY left a half-built index with the target name). 3. CREATE INDEX CONCURRENTLY as a standalone runMigration call (separate statement = no implicit transaction wrap). 4. PGLite: plain CREATE INDEX (no CONCURRENTLY needed — single writer). Verified against real Postgres (pgvector:pg16): - schema_version=91 after init - pages_generation_idx exists with btree shape - bump_page_generation_trg installed - test/e2e/postgres-bootstrap.test.ts + test/e2e/schema-drift.test.ts: 8 pass / 0 fail - bun test test/migrate.test.ts test/schema-bootstrap-coverage.test.ts: 161 pass / 0 fail - bun run typecheck: clean --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-23 08:49:28 -07:00
Garry Tan	e60b60244f	v0.36.6.0 feat: cross-modal search wave (text↔image + unified column + LLM intent) (#1165) ... * feat(cross-modal/0): batched multimodal + query helpers + SSRF helper Commit 0 of the cross-modal search wave. Foundation for Phase 1-3: - embedMultimodal accepts MultimodalInput text variant + EmbedMultimodalOpts with inputType: 'document' | 'query' (D22-2). Default unchanged so importImageFile keeps document-side embedding. - embedQueryMultimodal(text) + embedQueryMultimodalImage(input) wrappers for hybridSearch + searchByImage query paths. - embedMultimodalSafe binary-search retry on transient batch failure + failed_indices surfacing. Phase 3 reindex uses this so a single bad chunk doesn't discard the 31 in-flight embeddings around it. - Voyage path: text + image inputs in one batch via content arrays. - openai-compat path: text + image inputs in one request per input. - src/core/ssrf-validate.ts (D19): DNS-resolve-and-fetch-by-IP defense for redirect chains. Closes the DNS-rebinding gap that url-safety.ts' static check leaves open. Uses node:dns/promises with {all: true, family: 0} to inspect every A and AAAA record before connecting. fetchWithSSRFGuard helper validates per-redirect-hop and limits chain depth (default 3). - Re-exports from src/core/embedding.ts public seam. Tests: - test/embed-multimodal-batching.test.ts (13 cases): text variant, query inputType discipline, mixed text+image batches, embedQueryMultimodal, embedQueryMultimodalImage, embedMultimodalSafe happy/empty/all-fail/ mid-batch-recovery/permanent-misconfig. - test/ssrf-validate.test.ts (20 cases): static rejections via isInternalUrl, scheme + credentials rejection, DNS rebinding defense (single-record + multi-record), public happy path, IPv6 literals, malformed URLs. No regression in existing voyage-multimodal.test.ts or openai-compat-multimodal.test.ts (33 cases all pass). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cross-modal/1): Phase 1 text→image routing + knobsHash + RRF + backfill Phase 1 of the cross-modal search wave. Wires the existing 1024d Voyage multimodal embedding space (already populated for image chunks via importImageFile) into the user-facing query path. Text queries that match cross-modal intent regex route through Voyage multimodal-3 instead of the text embedding model, then search content_chunks.embedding_image. - query-intent.ts: new `suggestedModality: 'text' | 'image' | 'both'` axis on `QuerySuggestions`. Module-scope CROSS_MODAL_PATTERNS regex array (D15 — compiled once at module load). Conservative on purpose; LLM intent escalation (Commit 4) catches genuinely ambiguous phrasings. - query-intent.ts: new `isAmbiguousModalityQuery(query)` pure heuristic for Commit 4's escalation gate. Returns true ONLY when regex misses AND a visual noun + reference marker both fire. - types.ts: `SearchOpts.crossModal: 'text' | 'image' | 'both' | 'auto'` + `SearchResult.modality: 'text' | 'image'` for downstream renderers. - mode.ts: 7 new knobs in ModeBundle (D2): cross_modal_both_text_weight, cross_modal_both_image_weight, image_query_text_refinement_weight, image_query_image_refinement_weight, unified_multimodal, unified_multimodal_only, cross_modal_llm_intent. All three mode bundles default to the same values (cross-modal is opt-in). - mode.ts: D2 cache-key fix — KNOBS_HASH_VERSION bumped 2→3, all 7 new knobs participate in knobsHash so a text-mode cache hit can't be served to an image-mode caller. - mode.ts: D3 registry — all 7 keys land in SEARCH_MODE_CONFIG_KEYS so `gbrain search modes` / `stats` / `tune` see them. - hybrid.ts: routing branch at the embed step. Resolves effective modality from (per-call opts → suggestions → 'text'). Image route: embedQueryMultimodal + searchVector(embedding_image), skip expansion + keyword (D9 mode-bundle override). Both route: parallel text + image vector searches merged via weighted RRF (D6) with cross_modal_both_* weights. Fail-open: multimodal misconfigured → structured warn + text fallback. 'auto' literal normalized to undefined (D22-1). - operations.ts: thread `cross_modal` param through `query` op. - backfill-registry.ts: new `modality` backfill kind. SQL filter requires `chunk_source='image_asset'` (D22-7 defensive guard). Idempotent. - doctor.ts: `cross_modal_modality_backfill` check surfaces unflagged image-asset chunks with paste-ready `gbrain backfill modality` hint. Tests: - cross-modal-phase1.test.ts (45 cases): regex classification (positive + negative + plural-safe), isAmbiguousModalityQuery, D3 registry, D2 knobsHash diffs across all 7 new knobs, MODE_BUNDLES defaults, resolveSearchMode precedence chain. - cross-modal-hybrid-integration.test.ts (7 cases): PGLite + stubbed gateway. Verifies image-modality calls Voyage and not OpenAI, text calls OpenAI and not Voyage, 'auto' literal normalizes, 'both' mode hits both endpoints, fail-open routes to text on multimodal misconfig. - search-mode.test.ts: updated MODE_BUNDLES + KNOBS_HASH_VERSION assertions (148 cross-suite tests still pass; no regression). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cross-modal/2): Phase 2 image-as-query + D18 path ban + D23-#6 spend cap Phase 2 of the cross-modal search wave. Adds the `search_by_image` MCP op, the SSRF-defended image loader, and the daily per-OAuth-client spend cap on paid Voyage multimodal calls. D17 honest framing applied: Phase 2 ships image→similar-images + image-OCR-text retrieval. True image→full-text- knowledge requires Phase 3's unified column. - src/core/search/image-loader.ts: loadImageInput accepts local path, data: URI, or http(s):// URL. Magic-byte sniff for PNG/JPEG/WebP (no other formats). Hard size cap (10MB local default, 2MB remote default). http(s) path uses fetchWithSSRFGuard from Commit 0: every redirect hop re-resolved via DNS lookup + every record checked against the internal IP deny list. Max 3 redirect hops. 5s total fetch timeout. Pre-flight Content-Length check + post-fetch size guard for lying servers. - src/core/search/by-image.ts: searchByImage runs the image branch always; D13 hybrid intersect runs a parallel text branch when `query` is provided, merged via weighted RRF. Phase 3 will widen the column routing to embedding_multimodal once that lands. - src/core/operations.ts: new search_by_image op (scope: read, NOT localOnly). D18 P0 — when ctx.remote === true AND image_path is set, rejects with permission_denied at handler entry (validateParams would catch it again at dispatch). D5 source-id thread via sourceScopeOpts. D12 per-param length cap enforced via remote-vs-local maxBytes config read at handler entry. D23-#6 pre-flight checkBudget + post-call recordSpend (best-effort; failures don't block response). - src/core/spend-log.ts: BudgetExceededError + checkBudget + recordSpend + getTodaySpendCents. UTC day-aligned aggregation so the cap rolls over deterministically. Local CLI callers (no clientId) bypass the gate entirely. Pre-v0.36 brains without the mcp_spend_log table fail open to spend=0; the migration brings the table in on first start. - src/core/migrate.ts: new migration v67 mcp_spend_log table + indexes for the (client_id, day) and (token_name, day) hot reads. PGLite parity via sqlFor.pglite. - src/core/search/hybrid.ts: RRF_K constant exported so by-image.ts can share the same effective-K math as the main hybrid path. Tests: - cross-modal-phase2.test.ts (15 cases): magic-byte sniffing (PNG + JPEG + WebP positive, GIF rejection), oversized rejection (default + custom cap), data: URI happy path + malformed + decoded-non-image + oversized, invalid input shapes (empty + ftp), SSRF defense via DNS rebinding stub. - search-by-image-op.test.ts (7 cases): D18 remote image_path rejection + local CLI accepts; input validation (missing all three / multiple together); D23-#6 budget block-at-cap + allow-under-cap + local-CLI-bypass; migration v67 mcp_spend_log table applied cleanly. All 166 tests across the cross-modal suite pass; no regression in existing voyage-multimodal / openai-compat-multimodal / search-mode suites. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cross-modal/3): Phase 3 unified column + reindex + D8 fail-open + D23-#2 Phase 3 of the cross-modal search wave. Adds the unified multimodal column on content_chunks + the `gbrain reindex --multimodal` sweep + the `search.unified_multimodal` routing flag with D8 source-aware coverage guard + fail-open behavior. D17 honest framing: this is the phase that unlocks true image→full-text-knowledge — Phase 2's searchByImage transparently upgrades to the richer retrieval once the unified column has coverage. D10 reindex-core extraction filed as a follow-up TODO. The existing markdown reindex walks pages and re-imports via importFromFile; this walks content_chunks and re-embeds via the gateway. Patterns rhyme but cores diverge enough that extraction balloons the diff. Both commands stand alone with their own checkpoint + cost-prompt logic. - migrate.ts v68 (embedding_multimodal_column): column-only ALTER on content_chunks. HNSW partial index deferred to post-reindex build (D20: pgvector docs recommend post-load build for HNSW). Both engines. - types.ts SearchOpts.embeddingColumn type widened to include 'embedding_multimodal'. - postgres-engine.ts + pglite-engine.ts searchVector: route to embedding_multimodal column when opts.embeddingColumn set. NO modality filter (unified column carries both text + image content). - hybrid.ts unified routing branch: when search.unified_multimodal=true, bypasses dual-column branching and runs embedQueryMultimodal + searchVector(embedding_multimodal). D8 fail-open: zero rows + not strict-mode → falls through to dual-column text path with structured warning. search.unified_multimodal_only=true bypasses the fallback. - src/commands/reindex-multimodal.ts: `gbrain reindex --multimodal`. D7 lock via tryAcquireDbLock('gbrain-reindex-multimodal'); 6h TTL. Cost prompt + 10s Ctrl-C grace window in TTY; auto-proceeds non-TTY. GBRAIN_NO_REEMBED=1 bypass. Checkpoint at ~/.gbrain/reindex-multimodal-checkpoint.json for resume. D23-#2 auto-flip prompt at coverage=100% completion. - cli.ts: `gbrain reindex --multimodal` dispatch with --limit, --dry-run, --cost-estimate, --no-embed, --yes, --json flags. - doctor.ts: unified_multimodal_coverage check (D21 source-aware) + reports per-source % when search.unified_multimodal is on. Warns at <95% lowest source; fails when unified_multimodal_only=true AND lowest source <99%. Falls open to OK when column not yet present. Tests: - unified-multimodal.test.ts (8 cases): schema migration v68 applies, reindex --dry-run + --cost-estimate + GBRAIN_NO_REEMBED bypass + zero-pending fast-path, hybridSearch unified routing forces voyage endpoint, D8 fail-open routes to text on empty unified, D8 strict blocks text fallback. All 211 tests across the cross-modal + related suite pass; no regression in voyage-multimodal / openai-compat-multimodal / search-mode / intent / search base suites. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cross-modal/4): LLM intent escalation for ambiguous modality Commit 4 of the cross-modal search wave (opt-in default off). When `search.cross_modal.llm_intent` is true AND the regex classifier returned 'text' AND `isAmbiguousModalityQuery(query)` fires, hybridSearch awaits a Haiku tie-break via gateway.chat() before routing. The ambiguous-modality gate (introduced in Commit 1) ensures the LLM call only fires on the narrow band where regex misses but a visual noun + reference marker both fire — roughly <1% of queries with the flag on. - src/core/search/llm-intent.ts: new module. `classifyModalityWithLLM` routes through gateway.chat() with a fixed system prompt ("Output exactly one word: text, image, or both"). 1s timeout via AbortController. `parseModality` is a pure exported helper that tolerates trailing punctuation + casing. Fail-open on every error path (gateway unavailable, timeout, parse failure, unrecognized output). - src/core/search/hybrid.ts: escalation branch slots BEFORE the unified routing branch. Gated by: no explicit per-call crossModal opt, regex result == 'text', config flag on, ambiguity heuristic fires. Fail-open to regex result on any error from the LLM tie-break. Tests: - llm-intent-escalation.test.ts (14 cases): parseModality tolerance matrix (text / image / both / trailing punct / whitespace / unrecognized / empty), classifyModalityWithLLM happy paths for all 3 outputs, fail-open on throw / unrecognized output / gateway-not- configured, explicit-fallback-honored. - llm-intent-hybrid-integration.test.ts (6 cases): hybridSearch escalation gate fires ONLY when flag-on + ambiguous; off when flag-off, unambiguous, regex-confident, or explicit per-call opt set; fail-open on LLM throw. All 231 tests across the cross-modal + related suite pass; no regression in voyage-multimodal / openai-compat-multimodal / search-mode / intent / search base suites. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(cross-modal/3): verify-gate fixes for full test suite Three small fixes to pass the full unit + E2E sweep after the cross-modal wave commits land. - migrate.ts v67: drop date_trunc('day', created_at) from mcp_spend_log indexes. TIMESTAMPTZ truncation depends on session timezone and isn't IMMUTABLE, so Postgres rejects the function in the index expression with SQLSTATE 42P17. BTREE on (client_id, created_at) covers the per-day rollup query via range scan on created_at — same performance, no IMMUTABLE constraint. - pglite-schema.ts + src/schema.sql: shorten the embedding_multimodal column comment. The longer version contained a comma inside a SQL line comment ("...search.unified_multimodal=true, all queries..."), which broke parseBaseTableColumns in test/schema-bootstrap-coverage (the parser splits on commas at depth-0 before stripping comments, so the comma inside the comment shortened the column-definition part and an "all" token from "all queries" got picked up as the next column name — silently hiding embedding_multimodal from coverage). - schema-embedded.ts: regenerated via `bun run build:schema`. - test/e2e/v030_1-integration-pglite.test.ts: listBackfills assertion extended to include the new `modality` entry registered in src/core/backfill-registry.ts as part of Commit 1. - test/search/knobs-hash-reranker.test.ts: KNOBS_HASH_VERSION assertion updated from 2→3 to match the cross-modal-wave hash-key extension (D2 cache contamination fix). Same shape as the prior v0.32→v0.35 bump. - test/unified-multimodal.test.ts: migrated process.env mutation to withEnv() helper to satisfy the scripts/check-test-isolation R1 rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(cross-modal): VERSION + CHANGELOG + CLAUDE.md + spec doc + llms regen Final docs commit for the cross-modal wave (v0.36.0.0). - VERSION + package.json: bump 0.35.5.1 → 0.36.0.0 - CHANGELOG.md: full Garry-voice release entry with five-commit breakdown, the-numbers-that-matter table, what-this-means-for-you, and the required to-take-advantage-of-v0.36.0.0 block - docs/issues/cross-modal-search.md: cherry-picked from PR #1127 head (164 lines, the original spec doc preserved as historical reference for Phase 2 + 3 background) - CLAUDE.md: Key Files entries for src/core/ssrf-validate.ts, src/core/search/image-loader.ts, src/core/search/by-image.ts, src/core/search/llm-intent.ts, src/core/spend-log.ts, src/commands/reindex-multimodal.ts, plus extension annotations on src/core/search/query-intent.ts, src/core/search/mode.ts, src/core/search/hybrid.ts, src/core/backfill-registry.ts, src/core/migrate.ts (v67 + v68) - llms-full.txt + llms.txt: regenerated via `bun run build:llms` `bun run verify` clean (privacy + proposal-pii + test-names + jsonb + source-id-projection + progress + test-isolation + wasm + admin-build + admin-scope-drift + cli-exec + system-of-record + eval-glossary + typecheck). `bun test test/build-llms.test.ts` clean (7/7). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(cross-modal): renumber migrations 67→69 + 68→70 post-master-merge Master shipped its own v67 (`facts_typed_claim_columns`) during the cross-modal wave's review cycle. The merge picked up both side's v67 entries, breaking the migration-distinct-versions test. Renumbering moves cross-modal's table + column ALTER off the collision: - v67 mcp_spend_log → v69 mcp_spend_log - v68 embedding_multimodal_column → v70 embedding_multimodal_column References updated in CHANGELOG, CLAUDE.md, pglite-schema.ts, schema.sql. schema-embedded.ts regenerated. llms-full.txt regenerated. 7006 unit tests pass, 0 fail. No test code touched — just version renumbering plus comment refs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version 0.36.0.0 → 0.36.4.0 Bumping to v0.36.4.0 to land in the queue slot the user requested. No behavior change; pure version bump across VERSION, package.json, CHANGELOG.md header, llms-full.txt regen. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-19 17:14:53 -07:00