2 Commits

Include renames

Author	SHA1	Message	Date
3 people	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
5 people	c9652443cf	v0.32.7 feat: CJK fix wave — 6 layers from one root cause (closes vinsew + 313094319-sudo PRs) (#898) ... * feat: shared CJK detection module (cjk.ts) Foundation for the CJK fix wave. Single source of truth for CJK ranges (Han, Hiragana, Katakana, Hangul Syllables), the slug-char string used by adjacent validators, sentence + clause delimiter sets, the 30% density threshold for word counting, and a LIKE-pattern escape helper. Replaces the inline hasCJK regex at expansion.ts:58 so four-place drift becomes impossible. countCJKAwareWords uses density threshold (per codex outside-voice C13) so a long English doc with one Japanese term stays whitespace-tokenized, not char-split. Co-Authored-By: vinsew <vinsew@users.noreply.github.com> * feat: migration v51 + pages.chunker_version/source_path columns Schema-level support for the v0.32.7 CJK wave. Two new columns on pages: - chunker_version SMALLINT NOT NULL DEFAULT 1 — bumped to MARKDOWN_CHUNKER_VERSION (2) on every new import. The post-upgrade gbrain reindex --markdown sweep walks chunker_version < 2 to find pre-bump rows and rebuilds them. - source_path TEXT — captures the repo-relative path at import time so sync's delete/rename code can resolve frontmatter-fallback slugs (CJK / emoji / exotic-script files where the path itself doesn't derive a slug). Both columns plumbed through PageInput, partial indexes scoped to markdown-only / non-null. PGLite + Postgres parity via the standard ALTER TABLE ... IF NOT EXISTS shape. Replaces the original PR #599 plan of folding MARKDOWN_CHUNKER_VERSION into content_hash. Codex outside-voice C2 caught that as a no-op: performSync gates on actual file change, not hash-would-differ, so the fold never reached existing pages. Column + sweep is the real fix. Co-Authored-By: vinsew <vinsew@users.noreply.github.com> * feat: CJK-aware slugify + SLUG_SEGMENT_PATTERN + adjacent validators slugifySegment now preserves Han / Hiragana / Katakana / Hangul Syllables with NFC re-normalization after the NFD-strip-accents pass so Hangul Jamo recomposes back into precomposed syllables that fall inside the whitelist. café still slugifies to cafe (regression preserved — iron rule). SLUG_SEGMENT_PATTERN (consumed by takes-holder validation) extended with CJK_SLUG_CHARS in the same commit so CJK slugs aren't rejected by adjacent validators downstream. Codex outside-voice C4 caught this exact half-fix in the original plan — leaving the pattern ASCII-only would have shipped a feature where the slugify produced 品牌圣经 but adjacent validators flagged it. src/core/operations.ts: validatePageSlug + validateFilename also extended with CJK ranges. matchesSlugAllowList is unchanged (works on string prefixes, no character class). Co-Authored-By: vinsew <vinsew@users.noreply.github.com> * feat: recursive chunker — MARKDOWN_CHUNKER_VERSION + CJK splitting + maxChars cap Four coordinated chunker changes for the v0.32.7 wave: - MARKDOWN_CHUNKER_VERSION = 2 exported. Folded into pages.chunker_version so the post-upgrade reindex sweep can find pre-bump pages. - countWords delegated to countCJKAwareWords from cjk.ts (30% density threshold). Below threshold: whitespace-token count (English-dominant docs stay tokenized). At/above: char count (Chinese paragraphs actually split instead of being treated as one 8192-token-overflowing word). - DELIMITERS extends L2 (sentences) with 。！？ and L3 (clauses) with ；：，、. CJK punctuation now produces real chunk boundaries. - maxChars hard cap (default 6000) with sliding-window splitByChars and 500-char overlap. Catches pathological whitespace-less inputs that the word-level pipeline can't bound (pure-Han paragraphs, base64 blobs, long URLs). Applied to both single-short-chunk and merged-chunks paths. - splitOnWhitespace falls through to char-slice when ANY single "word" exceeds target chars (the greedy /\S+/g regex returns a whole CJK paragraph as one "word"; without this, the L4 fallback produces one huge piece). Pre-fix this was the silent-failure path. Tests in test/chunkers/recursive.test.ts: 9 new cases — pure Chinese, Japanese + 。, Korean Hangul, mixed CJK+English, 20KB CJK with overlap, single-short-chunk maxChars edge, pure-English regression. Co-Authored-By: vinsew <vinsew@users.noreply.github.com> * feat: PGLite CJK keyword fallback + engine chunker_version/source_path passthrough PGLite uses websearch_to_tsquery('english') over to_tsvector('english'), which can't tokenize CJK. Pre-fix, CJK queries returned empty results on PGLite brains even with proper embeddings. searchKeyword + searchKeywordChunks now branch on hasCJK(query): - ASCII path: unchanged. websearch_to_tsquery('english') continues to drive FTS. No regression risk. - CJK path: switches to ILIKE '%' || $qLike || '%' ESCAPE '\\' over chunk_text with two distinct param bindings ($qLike escaped for the ILIKE clause, $qRaw raw for the ranking arithmetic). Empty $qRaw guard bails before binding. Bigram-frequency-count ranking via (LENGTH(chunk_text) - LENGTH(REPLACE(chunk_text, $qRaw, ''))) / LENGTH($qRaw) approximates ts_rank semantics; position-in-chunk tiebreaker so earlier matches outrank later ones at the same occurrence count. Codex outside-voice C8 caught the original plan's one-param shortcut (escaped chars can't be reused as ranking substrings) + missing ESCAPE clause + asymmetric whitespace strip. C9 corrected the FTS dialect (websearch_to_tsquery, not to_tsvector('simple')). Source-boost CASE, hard-exclude clause, visibility clause, and the DISTINCT ON (slug) page-dedup all survive on both branches. Postgres engine path stays untouched (multi-tenant Postgres deployments can install pgroonga / zhparser for CJK; out of scope for this wave). Postgres + PGLite putPage both extended to write chunker_version and source_path columns (with COALESCE(EXCLUDED.x, pages.x) so auto-link / code-reindex callers that don't supply them don't blank existing values). Tests: 8 new cases covering Chinese / Japanese / Korean substring search, bigram ranking (3-hit > 1-hit), LIKE-meta-char escape (literal % does not wildcard), English query stays on FTS path. Co-Authored-By: vinsew <vinsew@users.noreply.github.com> Co-Authored-By: 313094319-sudo <313094319-sudo@users.noreply.github.com> * feat: import-file frontmatter-slug fallback + audit JSONL importFromFile gains a fallback branch: when slugifyPath returns empty (emoji / Thai / Arabic / exotic-script filename — including post-CJK-wave files that still don't slugify) AND the frontmatter declares a slug, the frontmatter slug becomes authoritative. Anti-spoof rule preserved unchanged: when slugifyPath produces a non-empty path slug AND the frontmatter slug claims a different one, the file is still rejected. notes/random.md cannot impersonate people/elon via frontmatter. D6=B error string when both path slug AND frontmatter slug are empty: "Filename produces no usable slug. Add a 'slug:' to the frontmatter, or rename the file to use ASCII / Chinese / Japanese / Korean characters." Honest about the actually-supported scripts. Every import now populates pages.chunker_version (set to MARKDOWN_CHUNKER_VERSION) and pages.source_path (repo-relative). These drive the post-upgrade reindex sweep + sync's delete/rename slug resolution. NEW src/core/audit-slug-fallback.ts — weekly ISO-week-rotated JSONL at ~/.gbrain/audit/slug-fallback-YYYY-Www.jsonl. Per codex C7, info events don't belong in sync-failures.jsonl (which gates bookmark advancement); separate audit surface keeps the failure-handling code unchanged. logSlugFallback emits a stderr line AND appends to the audit file (D7=D dual logging). Tests: 5 new import-file cases (小米 with no frontmatter slug, 🚀.md with frontmatter fallback, 🌟🚀.md friendly D6=B error, anti-spoof regression, chunker_version + source_path populated). 6 new audit cases covering write, weekly rotation, 7-day window, corrupt-row tolerance. Co-Authored-By: vinsew <vinsew@users.noreply.github.com> * feat: git() helper hardening + core.quotepath=false for CJK paths git CLI emits CJK paths as quoted octal escapes (\345\223\201 ...) by default in diff --name-status output. Pre-fix, buildSyncManifest silently dropped these paths because downstream filesystem lookups saw the literal escape string. gbrain sync reported added=0 while git had the file committed. git() helper refactored: - New signature: git(repoPath, args: string[], configs?: string[]) - Config flags emit BEFORE -C and BEFORE the subcommand (git CLI requires this order) - core.quotepath=false always prepended - Future callers needing extra -c config pass configs:[]; no more inlining -c into args (the silent-future-drift footgun codex C12 flagged as a related concern) New invariant test in test/sync.test.ts pins the emit order. NEW test/e2e/sync-cjk-git.test.ts — real-git E2E in a tmpdir. Spawns real git via execFileSync, commits a Chinese-named markdown file, drives the helper through buildSyncManifest, asserts the manifest contains the UTF-8 path (not the octal-escape form). Closes the real-CLI-behavior gap that unit tests can't cover (the helper builds the right args; only an E2E proves git actually emits UTF-8 under the flag). Co-Authored-By: vinsew <vinsew@users.noreply.github.com> * feat: gbrain reindex --markdown sweep command NEW src/commands/reindex.ts — operator-facing markdown re-chunk sweep. Walks SELECT slug, source_path FROM pages WHERE page_kind = 'markdown' AND chunker_version < MARKDOWN_CHUNKER_VERSION in 100-row batches, ordered by id ASC so partial-completion re-runs pick up where they left off. For rows with non-null source_path: re-imports via importFromFile when the file exists on disk. For rows without (legacy pre-migration backfill): fallback to importFromContent using the stored markdown body. Flags: --markdown (target selector), --limit N, --dry-run, --json, --no-embed (offline / CI / test path that lets the chunker run without a configured AI gateway), --repo PATH. Wired into src/cli.ts dispatch table. Will also be invoked automatically by gbrain upgrade's post-upgrade hook (next commit) so chunker-version bumps reach existing markdown pages without an explicit operator action. Tests in test/reindex.test.ts: 5 cases covering dry-run, actual sweep, idempotent re-run, --limit cap, skipped-already-at-current. Co-Authored-By: vinsew <vinsew@users.noreply.github.com> Co-Authored-By: 313094319-sudo <313094319-sudo@users.noreply.github.com> * feat: post-upgrade chunker-bump cost prompt + auto-reindex sweep Wires the chunker-version bump into gbrain upgrade so existing brains heal automatically. Three new pieces: NEW src/core/embedding-pricing.ts — EMBEDDING_PRICING map keyed provider:model (OpenAI text-embedding-3-large + 3-small + ada-002, Voyage 3-large + 3). lookupEmbeddingPrice returns 'known' or 'unknown' shape so the cost-estimate prompt can degrade gracefully for unknown providers rather than fabricate numbers (codex C3). estimateCostFromChars uses 3.5 chars/token approximation. NEW src/core/post-upgrade-reembed.ts — pure-ish functions for the cost-estimate prompt: - computeReembedEstimate: real SQL against COUNT(*) + COALESCE(SUM(LENGTH(compiled_truth)) + SUM(LENGTH(timeline)) on the chunker_version-filtered query. No phantom markdown_body column (codex C3 caught the original plan referencing nonexistent schema fields). - formatReembedPrompt: pure string formatter for the stderr line. - runPostUpgradeReembedPrompt: orchestrates the prompt + 10-second Ctrl-C window. TTY-only wait so non-TTY upgrades (CI, cron-driven, headless) don't hang. GBRAIN_NO_REEMBED=1 bails out entirely with a doctor-warning marker; GBRAIN_REEMBED_GRACE_SECONDS=0 skips the wait. src/commands/upgrade.ts: after apply-migrations runs, the new prompt fires through the gateway's configured embedding model, then invokes gbrain reindex --markdown automatically if the user proceeds. Wrapped in try-catch so a reindex failure is non-fatal — the user can re-run manually. Tests in test/upgrade-reembed-prompt.test.ts: 11 cases covering real SQL counts, unknown-provider fallback, TTY / non-TTY paths, GBRAIN_NO_REEMBED bail-out, GBRAIN_REEMBED_GRACE_SECONDS=0 skip-wait. Codex outside-voice C2 caught the original plan as a no-op (performSync doesn't re-import unchanged files just because content_hash would differ). The migration v51 column + this sweep + this prompt is the real fix that actually reaches existing pages. Co-Authored-By: vinsew <vinsew@users.noreply.github.com> * feat: doctor slug_fallback_audit check + CJK roundtrip E2E gbrain doctor learns a new slug_fallback_audit check (v0.32.7). Reads the latest week of ~/.gbrain/audit/slug-fallback-*.jsonl, counts info-severity entries from the last 7 days, surfaces the total as an ok-status line. No health-score docking; no warning. sync-failures.jsonl (which gates bookmark advancement) stays untouched — info events live in their own surface per codex C7. NEW test/e2e/cjk-roundtrip.test.ts — proves the wave delivers end- to-end. PGLite-in-memory fixture with Chinese / Japanese / Korean content. Each page: importFromContent → chunkText (CJK-aware) → searchKeyword (LIKE-branch with bigram count). Asserts every CJK query lands on its source page. ASCII regression: an English query still uses the FTS path on the same brain. Vector path skips gracefully without OPENAI_API_KEY. Co-Authored-By: vinsew <vinsew@users.noreply.github.com> * chore: bump version and changelog (v0.32.7) CJK fix wave — six layers from one root cause. Three originating PRs from @vinsew and one extracted from @313094319-sudo's #765 land together as a coherent collector. Codex outside-voice review on the plan caught four critical bugs the eng review missed (no-op re-embed, SLUG_SEGMENT_PATTERN half-fix, LIKE SQL needing two distinct param bindings, countCJKAwareWords over-splitting on English+1-CJK-term docs). All four addressed in the implementation. TODOS.md: resolved the v0.32.x PGLite CJK keyword fallback entry; filed five v0.33+ follow-ups (Postgres CJK FTS via pgroonga / wider Unicode property escapes / -z NUL git framing / CJK overlap context / other non-Latin scripts / embedding pricing refresh mechanism). Co-Authored-By: vinsew <vinsew@users.noreply.github.com> Co-Authored-By: 313094319-sudo <313094319-sudo@users.noreply.github.com> Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix: review findings — forceRechunk + source_path lookup (codex post-merge) Two critical issues caught by codex adversarial on the post-merge tree: F1 — Reindex sweep was a no-op on unchanged-source pages. importFromContent short-circuits on existing.content_hash === hash BEFORE the chunker runs, so the v0.32.7 MARKDOWN_CHUNKER_VERSION bump (and master's v0.32.2 stripFactsFence privacy strip) never reached pages whose markdown body hadn't been edited. Fix: new `forceRechunk?: boolean` option on importFromContent + importFromFile. When set, the hash short-circuit is bypassed and the page re-runs the full chunk + write pipeline. `gbrain reindex --markdown` now passes forceRechunk: true on every row. This means: - The CJK chunker bump actually reaches existing markdown pages. - Master's v0.32.2 stripFactsFence applies retroactively too — any pre-strip private fact bytes lingering in content_chunks get cleared when the v0.32.7 post-upgrade sweep runs. New test in test/reindex.test.ts seeds a page, runs the sweep, mocks a stale chunker_version=1 without changing compiled_truth, runs the sweep again, asserts chunker_version is bumped despite hash match. F4 — Sync delete/rename still used resolveSlugForPath(path) only, ignoring the new pages.source_path column added in v52. Frontmatter-fallback pages (emoji-only / Thai / Arabic filenames where slugifyPath returns empty and the slug came from the markdown frontmatter) would orphan on delete or rename because the path-derived slug doesn't match the stored slug. Fix: new exported helper resolveSlugByPathOrSourcePath(engine, path, sourceId?) queries pages.source_path first, falls back to resolveSlugForPath when no row matches. Threaded into 3 call sites in sync.ts (un-syncable modified cleanup at :531, deletes at :603, rename oldSlug at :622). Best-effort: query errors fall through to the legacy path so pre-migration brains still work. 3 new test cases in test/sync.test.ts cover: stored-slug lookup hits, fallback when no source_path row exists, and source_id scoping when two sources have the same source_path value. Codex finding #3 (reindex not in CLI_ONLY) was verified as a false positive — CLI_ONLY is the set that doesn't need an engine; reindex correctly belongs to the engine-backed dispatch. 302 wave tests pass / 0 fail. bun run verify green. * docs: update CLAUDE.md + llms-full.txt for v0.32.7 CJK fix wave CLAUDE.md Key Files: added entries for the five new modules introduced by the wave — src/core/cjk.ts (shared detection + delimiters + density threshold), src/core/audit-slug-fallback.ts (weekly JSONL), src/core/embedding-pricing.ts (post-upgrade cost lookup table), src/core/post-upgrade-reembed.ts (prompt + grace window), and src/commands/reindex.ts (chunker_version sweep with forceRechunk). Also noted src/commands/sync.ts:resolveSlugByPathOrSourcePath — the F4 codex post-merge fix that wires the new pages.source_path column into sync delete/rename so frontmatter-fallback pages don't orphan. CLAUDE.md Commands: added a v0.32.7 section covering `gbrain reindex --markdown`, the new doctor slug_fallback_audit check, PGLite CJK keyword fallback in `gbrain search`, and the post-upgrade chunker-bump cost prompt with its env-var overrides. llms-full.txt: regenerated via bun run build:llms (CI gate runs the generator on every release; commit must include the bundle). README.md: no changes needed — v0.32.7 is internal correctness across the existing pipeline, not a new skill or setup story. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: vinsew <vinsew@users.noreply.github.com> Co-authored-by: 313094319-sudo <313094319-sudo@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-11 22:54:35 -07:00