secondbrain-py 0.2.1__py3-none-any.whl

brain/migrations/014_graphrag_community_summary_hash.sql

@@ -0,0 +1,33 @@
+-- Migration 014 — GraphRAG community summary staleness tracker (wave G3-c).
+--
+-- Additive + idempotent. Adds ONE nullable column to ``graph_communities``:
+--
+--   summary_members_hash TEXT NULL
+--       The ``members_hash`` value that the community's CURRENT ``summary`` was
+--       generated from. The eager summary pass (§17c Q10,
+--       ``brain.graph_rag.communities_summary.summarize_communities``) treats a
+--       community as NEEDING a (re)summary when
+--           ``summary IS NULL OR summary_members_hash IS DISTINCT FROM members_hash``
+--       i.e. a never-summarized community OR one whose membership changed since
+--       its last summary. The G3-b delta-gate
+--       (``brain.graph_rag.communities._update_reused_community``) MOVES
+--       ``members_hash`` on a membership change while PRESERVING the old summary;
+--       this column lets that staleness be detected WITHOUT ever blanking the
+--       live summary — the existing summary stays queryable until a fresh one
+--       replaces it.
+--
+-- ``IS DISTINCT FROM`` (not ``<>``) is what makes the predicate NULL-safe: a row
+-- whose ``summary_members_hash`` is NULL (every row right after this migration,
+-- and every freshly-minted community) is correctly seen as stale relative to its
+-- non-NULL ``members_hash`` and gets summarized on the next pass.
+--
+-- No new index: the staleness scan is tenant-scoped over the (small) community
+-- set, already covered by the ``(tenant_id, level)`` index from migration 013;
+-- a dedicated index would not pay for itself at personal-corpus community counts.
+
+BEGIN;
+
+ALTER TABLE graph_communities
+    ADD COLUMN IF NOT EXISTS summary_members_hash TEXT NULL;
+
+COMMIT;

brain/migrations/015_interactions_graph_targets.sql

@@ -0,0 +1,89 @@
+-- Migration 015 — generalize ``interactions`` for graph-target feedback
+-- (wave G4-a; spec docs/specs/2026-05-20-graphrag-design.md §17d Q2/Q5).
+--
+-- Additive + idempotent. Migration 010 created ``interactions`` as a
+-- DOCUMENT-only feedback log (``document_id`` NOT NULL). G4 makes the graph
+-- surfaces — entity / community / theme — FIRST-CLASS rateable targets while
+-- keeping every existing document-only caller (``brain rate``, MCP
+-- ``brain_show``) working unchanged. This migration:
+--
+--   1. ``document_id`` → NULLABLE (a graph-target row has no document).
+--   2. ADD ``target_type TEXT NULL`` — one of 'entity' | 'community' | 'theme'.
+--   3. ADD ``target_id   TEXT NULL`` — the durable id of the graph target
+--      (entity UUID / community_key / theme key). TEXT (not UUID) because the
+--      three target kinds do not share a single id type; the target_type names
+--      which space the id lives in.
+--   4. ADD ``graph_retrieved BOOLEAN NOT NULL DEFAULT FALSE`` — PROVENANCE only
+--      (a graph surface produced this row). It is NOT part of the target model;
+--      a document row surfaced via a graph path is still a document row with
+--      ``graph_retrieved = TRUE``. Existing rows backfill to FALSE.
+--
+-- Two CHECK constraints (the authoritative gate; the Python writer mirrors them
+-- in ``brain.interactions``):
+--
+--   * target_type domain — NULL, or one of the three known kinds.
+--   * EXACTLY ONE target shape (XOR) — a row is EITHER a document row
+--     (``document_id`` set, both target_* NULL) OR a graph-target row
+--     (``document_id`` NULL, both target_* set). The two disjuncts are mutually
+--     exclusive (one demands ``document_id`` NOT NULL, the other NULL), so their
+--     OR is a true XOR. Every pre-015 row satisfies the first disjunct, so the
+--     constraint validates cleanly against existing data.
+--
+-- An additive partial index on (target_type, target_id) supports graph-target
+-- lookups; it excludes the document-only rows (target_type NULL) to stay small.
+--
+-- NEVER edit a shipped migration — this is a NEW numbered file. Migration 010
+-- and all prior migrations are untouched.
+
+BEGIN;
+
+-- 1. document_id becomes nullable. Idempotent: DROP NOT NULL on an already
+--    nullable column is a successful no-op.
+ALTER TABLE interactions
+    ALTER COLUMN document_id DROP NOT NULL;
+
+-- 2-4. Additive columns. graph_retrieved backfills FALSE on existing rows.
+ALTER TABLE interactions
+    ADD COLUMN IF NOT EXISTS target_type     TEXT,
+    ADD COLUMN IF NOT EXISTS target_id       TEXT,
+    ADD COLUMN IF NOT EXISTS graph_retrieved BOOLEAN NOT NULL DEFAULT FALSE;
+
+-- 5. target_type domain CHECK. Postgres has no ADD CONSTRAINT IF NOT EXISTS,
+--    so guard on pg_constraint by name to keep re-runs safe.
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'interactions_target_type_chk'
+    ) THEN
+        ALTER TABLE interactions
+            ADD CONSTRAINT interactions_target_type_chk
+            CHECK (target_type IS NULL
+                   OR target_type IN ('entity', 'community', 'theme'));
+    END IF;
+END$$;
+
+-- 6. XOR target-shape CHECK: document-only OR graph-target-only, never both,
+--    never neither.
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'interactions_target_xor_chk'
+    ) THEN
+        ALTER TABLE interactions
+            ADD CONSTRAINT interactions_target_xor_chk
+            CHECK (
+                (document_id IS NOT NULL
+                    AND target_type IS NULL AND target_id IS NULL)
+                OR
+                (document_id IS NULL
+                    AND target_type IS NOT NULL AND target_id IS NOT NULL)
+            );
+    END IF;
+END$$;
+
+-- 7. Partial index for graph-target lookups (entity/community/theme rows only).
+CREATE INDEX IF NOT EXISTS interactions_target_idx
+    ON interactions (target_type, target_id)
+    WHERE target_type IS NOT NULL;
+
+COMMIT;

brain/migrations/016_index_hygiene.sql

@@ -0,0 +1,61 @@
+-- Migration 016: index hygiene — drop one provably dead index, add two missing.
+--
+-- All operations are idempotent:
+-- ``DROP INDEX IF EXISTS`` is a no-op when already gone;
+-- ``CREATE INDEX IF NOT EXISTS`` is a no-op when already present.
+--
+-- 1. DROP documents_tsv_idx — the only PROVABLY dead index.
+--    Code-level evidence: migration 009 moved FTS to the weighted
+--    chunks.tsv (multi-field tsvector). The documents.tsv column is still
+--    present (generated, no migration cost to keep), but no search query
+--    plan uses this index. It is a ~12 MB GIN that carries unnecessary
+--    write-amplification on every document INSERT / UPDATE.
+--
+-- 2. DEFERRED — the following six filter indexes also showed idx_scan=0 at
+--    the 2026-05-25 audit, but the prod stats were reset by the 2026-05-22
+--    AGE cutover (pg_restore). Three days of observations is too short a
+--    window to call filter indexes "dead":
+--
+--      derived_links_rule_idx        (on derived_links.rule)
+--      documents_tags_idx            (GIN on documents.tags)
+--      directory_entries_email_idx   (on directory_entries.email)
+--      idx_documents_draft           (on documents.draft)
+--      idx_documents_sent_at         (on documents.sent_at)
+--      idx_documents_thread_id       (on documents.thread_id)
+--
+--    Revisit after ~30 days of post-cutover prod traffic. Drop in a
+--    migration 017 if idx_scan remains 0 at that point.
+--
+-- 3. NEVER DROP uq_documents_gmail_thread — it is a UNIQUE constraint
+--    (indisunique=True, migration 008) that enforces the invariant
+--    "one email_thread row per thread_id". UNIQUE indexes legitimately
+--    show idx_scan=0 because uniqueness enforcement does not increment
+--    idx_scan. Dropping it would silently remove a data-integrity guard.
+--
+-- 4. NEW: GIN index on documents.participants — the ``&&`` array-overlap
+--    operator used by the --person filter (Q1-C) forces a seq-scan without
+--    this index.
+--
+-- 5. NEW: partial btree index on documents.source_path — the file-ingest
+--    dedup path (``WHERE source_path = %s``) forces a seq-scan without it.
+--    Scoped to IS NOT NULL rows (stdin ingests use content_hash dedup and
+--    have source_path NULL), keeping the index small.
+
+BEGIN;
+
+-- Drop the single provably-dead index (FTS moved to chunks.tsv in 009).
+DROP INDEX IF EXISTS documents_tsv_idx;
+
+-- GIN for ``documents.participants && ARRAY[...]`` array-overlap queries
+-- (the --person filter in Q1-C; currently a full seq-scan).
+CREATE INDEX IF NOT EXISTS documents_participants_idx
+    ON documents USING GIN (participants);
+
+-- Partial btree for file-ingest dedup: ``WHERE source_path = %s``.
+-- Restricts to IS NOT NULL so the index never covers stdin rows (which use
+-- content_hash dedup instead), keeping the index small.
+CREATE INDEX IF NOT EXISTS documents_source_path_idx
+    ON documents (source_path)
+    WHERE source_path IS NOT NULL;
+
+COMMIT;

brain/migrations/017_elicit.sql

@@ -0,0 +1,30 @@
+-- 017_elicit.sql — tacit-knowledge elicitation gap-state table.
+-- Mutable lifecycle (surfaced → snoozed → dismissed → resolved); NOT in interactions
+-- (that table is append-only). See docs/specs/2026-06-01-tacit-knowledge-elicitation-design.md.
+
+CREATE TABLE IF NOT EXISTS elicitation_gaps (
+    id                UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id         TEXT NOT NULL DEFAULT 'default',
+    signal_kind       TEXT NOT NULL
+                      CHECK (signal_kind IN ('delta','orphan','contradiction','user_flagged')),
+    target_type       TEXT NOT NULL
+                      CHECK (target_type IN ('person','org','project','topic','tool','doc')),
+    target_id         TEXT NOT NULL,
+    score             DOUBLE PRECISION NOT NULL CHECK (score >= 0),
+    evidence_ids      TEXT[] NOT NULL DEFAULT '{}',
+    rationale         TEXT NOT NULL DEFAULT '',
+    status            TEXT NOT NULL DEFAULT 'surfaced'
+                      CHECK (status IN ('surfaced','snoozed','dismissed','resolved')),
+    snoozed_until     TIMESTAMPTZ,
+    resolved_note_id  UUID REFERENCES documents(id) ON DELETE SET NULL,
+    first_surfaced_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at        TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS elicitation_gaps_tenant_signal_target_idx
+    ON elicitation_gaps (tenant_id, signal_kind, target_id)
+    WHERE status <> 'resolved';
+
+CREATE INDEX IF NOT EXISTS elicitation_gaps_queue_idx
+    ON elicitation_gaps (tenant_id, status, score DESC)
+    WHERE status IN ('surfaced','snoozed');

brain/migrations/018_review_gap_signal_kinds.sql

@@ -0,0 +1,40 @@
+-- 018_review_gap_signal_kinds.sql
+-- Additive + idempotent. Extends elicitation_gaps.signal_kind CHECK to the full
+-- superset of all known signal kinds so no later migration needs to rewrite it.
+-- Plan 03 adds 'stale'; Plan 08 (migration 019) depends on 'search_failure'
+-- already being valid here, so this migration ships the complete six-value set.
+-- Uses the same DO-block guard pattern as migration 015.
+-- NEVER edit shipped migrations 001-017.
+
+BEGIN;
+
+DO $$
+BEGIN
+    -- Drop the four-value constraint from 017 if it still exists.
+    -- (The inline CHECK from CREATE TABLE gets the auto-generated name below.)
+    IF EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conname = 'elicitation_gaps_signal_kind_check'
+          AND conrelid = 'elicitation_gaps'::regclass
+    ) THEN
+        ALTER TABLE elicitation_gaps
+            DROP CONSTRAINT elicitation_gaps_signal_kind_check;
+    END IF;
+
+    -- Add the six-value superset constraint under a versioned name.
+    -- Idempotent: no-op if already present from a prior run of this migration.
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conname = 'elicitation_gaps_signal_kind_v2_check'
+          AND conrelid = 'elicitation_gaps'::regclass
+    ) THEN
+        ALTER TABLE elicitation_gaps
+            ADD CONSTRAINT elicitation_gaps_signal_kind_v2_check
+            CHECK (signal_kind IN (
+                'delta', 'orphan', 'contradiction', 'user_flagged',
+                'stale', 'search_failure'
+            ));
+    END IF;
+END$$;
+
+COMMIT;

brain/migrations/019_search_queries.sql

@@ -0,0 +1,35 @@
+-- 019_search_queries.sql — lightweight log of every hybrid-search call.
+-- Plan 08 (`brain gaps`): a repeated zero-result / no-click query is direct
+-- evidence the brain is missing knowledge the user needs. ``interactions``
+-- structurally cannot hold a zero-result search (migration 015's
+-- document-XOR-graph-target CHECK requires a target, and a failed search has
+-- none), so search-failure mining needs its own append-only table.
+--
+-- Additive + idempotent. Creates ONLY the ``search_queries`` table + indexes.
+-- The ``elicitation_gaps.signal_kind`` CHECK already includes 'search_failure'
+-- (shipped by migration 018) — this migration does NOT touch that constraint.
+-- NEVER edit shipped migrations 001-018.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS search_queries (
+    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id    TEXT NOT NULL DEFAULT 'default',
+    query        TEXT NOT NULL,
+    result_count INT  NOT NULL DEFAULT 0,
+    session_id   UUID,              -- nullable; MCP path mints one, CLI path NULL
+    source       TEXT NOT NULL
+                   CHECK (source IN ('cli', 'mcp', 'wiki')),
+    at           TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Recency-ordered tenant scan backs both the read view and the detector window.
+CREATE INDEX IF NOT EXISTS search_queries_tenant_at_idx
+    ON search_queries (tenant_id, at DESC);
+
+-- Partial index for the zero-result hot path (the headline gap signal).
+CREATE INDEX IF NOT EXISTS search_queries_zero_result_idx
+    ON search_queries (tenant_id, at DESC)
+    WHERE result_count = 0;
+
+COMMIT;

brain/migrations/020_link_suggestions.sql

@@ -0,0 +1,40 @@
+-- Plan 07 — `brain connect` proactive auto-link suggestions.
+--
+-- Additive only: nothing in prior migrations is altered or dropped. One new
+-- table backs the proactive suggestion queue. Each row is a candidate
+-- (source_doc → target_doc) wikilink the user has NOT yet drawn, scored by a
+-- RRF blend of an entity-graph affinity leg and an embedding affinity leg
+-- (see ``src/brain/connect.py``). The accept/reject state machine is a
+-- DEDICATED concern, separate from the ``interactions`` log (migration 010):
+-- a suggestion is ``pending`` until the user accepts (optionally writing the
+-- wikilink into the source vault file) or rejects it.
+--
+-- The ``UNIQUE (source_doc_id, target_doc_id)`` constraint makes
+-- ``brain connect refresh`` safely idempotent: re-running upserts the score on
+-- ``pending`` rows only (``ON CONFLICT ... DO UPDATE ... WHERE status =
+-- 'pending'``), so accepted/rejected rows are frozen and never resurface.
+-- Directed pairs are distinct rows: A→B and B→A may both be suggested.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS link_suggestions (
+    id              UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+    source_doc_id   UUID        NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    target_doc_id   UUID        NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    score           FLOAT       NOT NULL,
+    graph_score     FLOAT,
+    embed_score     FLOAT,
+    suggested_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+    status          TEXT        NOT NULL DEFAULT 'pending'
+                    CHECK (status IN ('pending', 'accepted', 'rejected')),
+    actioned_at     TIMESTAMPTZ,
+    CHECK (source_doc_id <> target_doc_id),
+    UNIQUE (source_doc_id, target_doc_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_link_suggestions_status
+    ON link_suggestions (status);
+CREATE INDEX IF NOT EXISTS idx_link_suggestions_source
+    ON link_suggestions (source_doc_id);
+
+COMMIT;

brain/migrations/021_timeline_doc_date.sql

@@ -0,0 +1,34 @@
+-- Migration 021 — optional `doc_date` generated column for `brain timeline`
+-- (Plan 05, Phase 3). Slot 021 per the cross-plan assignment in
+-- docs/plans/2026-06-03-brain-next-features/README.md (migrations 018/019/020
+-- belong to Plans 03/08/07 respectively; 016/017 already shipped).
+--
+-- ADDITIVE ONLY. The timeline's temporal anchor is
+-- COALESCE(documents.sent_at, documents.ingested_at) — event time when known
+-- (emails, Krisp), else ingest time. Phases 1 and 2 compute that inline in
+-- every query. This migration materializes it as a generated STORED column +
+-- a B-tree index so the repeated COALESCE expression is replaced by a single
+-- indexed read. `brain.timeline._doc_date_expr` auto-detects the column via
+-- information_schema and falls back to the inline COALESCE when it is absent,
+-- so applying this migration is purely an optimization — zero behavior change.
+--
+-- References only `documents` columns frozen by earlier shipped migrations
+-- (sent_at + participants from 007; ingested_at from 001). It does NOT
+-- reference any object from migrations 018–020 (which may not yet exist when
+-- this file is applied — the runner tolerates name-order gaps).
+--
+-- ⚠ Generated-column caveat: `ADD COLUMN … GENERATED … STORED` rewrites the
+-- `documents` table in Postgres. At personal-corpus scale (≤ 5 000 rows) this
+-- completes in well under a second, but it is not zero-cost. Existing rows are
+-- backfilled automatically by Postgres. Idempotent (`IF NOT EXISTS`).
+
+BEGIN;
+
+ALTER TABLE documents
+    ADD COLUMN IF NOT EXISTS doc_date TIMESTAMPTZ
+        GENERATED ALWAYS AS (COALESCE(sent_at, ingested_at)) STORED;
+
+CREATE INDEX IF NOT EXISTS idx_documents_doc_date
+    ON documents (doc_date DESC);
+
+COMMIT;

brain/migrations/022_link_suggestions_undirected.sql

@@ -0,0 +1,84 @@
+-- Plan 07 follow-up — make `link_suggestions` pairs UNDIRECTED.
+--
+-- Additive/idempotent: alters the migration-020 table in place. No data is
+-- destroyed beyond redundant mirror rows (see the dedup step below).
+--
+-- THE BUG THIS FIXES (verified in live QA): migration 020 keyed uniqueness on
+-- the DIRECTED pair ``UNIQUE (source_doc_id, target_doc_id)``, so A→B and B→A
+-- were stored as two separate rows. ``brain connect refresh`` scores every
+-- source doc independently, so it wrote BOTH orientations of the same unordered
+-- pair — ~52% of the live pending queue was mirror duplicates. Worse, accepting
+-- (or rejecting) one orientation left its mirror ``pending``, forcing the
+-- reviewer to action the same pair twice.
+--
+-- THE FIX: a suggested link pair is undirected for review purposes. We keep
+-- ``source_doc_id`` / ``target_doc_id`` as the BEST-SCORING orientation (so the
+-- ``accept --write`` vault writeback still appends the ``## See Also`` wikilink
+-- into a sensible "source" doc), but enforce ONE row per UNORDERED pair via a
+-- functional unique index on ``(LEAST(source, target), GREATEST(source,
+-- target))``. The application upsert (``connect._upsert_suggestion``) targets
+-- this index and only flips orientation when a strictly-better score arrives;
+-- the mirror of an already accepted/rejected pair can no longer be inserted.
+--
+-- This supersedes migration 020's comment ("Directed pairs are distinct rows").
+-- Migration 020 is frozen and left untouched, per the repo migration rules.
+
+BEGIN;
+
+-- Step 1 — collapse existing mirror rows to one canonical row per UNORDERED
+-- pair BEFORE the unique index is added (otherwise index creation would fail on
+-- the live corpus's 501 mirror pairs). For each unordered pair keep the single
+-- highest-priority row and delete the rest:
+--   1. status priority: accepted (3) > rejected (2) > pending (1)
+--   2. then higher blended ``score``  (keeps the better-scoring orientation)
+--   3. then lower ``id`` (stable, deterministic tie-break)
+--
+-- Consequences of this ordering, by case:
+--   * pending + pending  → keep the better-scoring orientation, drop the mirror
+--                          (the common ~52% case). Accepted/rejected untouched.
+--   * pending + decided  → keep the decided (accepted/rejected) row, drop the
+--                          stale pending mirror. NO accepted/rejected row is
+--                          deleted here.
+--   * decided + decided  → only reachable if the SAME pair was both accepted in
+--                          one orientation and rejected/accepted in the other
+--                          (contradictory historical decisions). The unique
+--                          index cannot hold both, so exactly one must go; we
+--                          keep accepted-over-rejected, then higher score. This
+--                          is the ONLY path that can drop a decided row, and it
+--                          only triggers on self-contradictory legacy data.
+WITH ranked AS (
+    SELECT id,
+           row_number() OVER (
+               PARTITION BY LEAST(source_doc_id, target_doc_id),
+                            GREATEST(source_doc_id, target_doc_id)
+               ORDER BY CASE status
+                            WHEN 'accepted' THEN 3
+                            WHEN 'rejected' THEN 2
+                            ELSE 1
+                        END DESC,
+                        score DESC,
+                        id ASC
+           ) AS rn
+    FROM link_suggestions
+)
+DELETE FROM link_suggestions
+WHERE id IN (SELECT id FROM ranked WHERE rn > 1);
+
+-- Step 2 — drop the directed unique constraint from migration 020. The new
+-- functional index (Step 3) is strictly stronger, so this would otherwise be a
+-- redundant, confusing second uniqueness rule and an ambiguous ON CONFLICT
+-- inference target.
+ALTER TABLE link_suggestions
+    DROP CONSTRAINT IF EXISTS link_suggestions_source_doc_id_target_doc_id_key;
+
+-- Step 3 — enforce ONE row per UNORDERED pair regardless of which doc is stored
+-- as source vs target. ``LEAST`` / ``GREATEST`` over the two UUIDs canonicalize
+-- the pair; the index value is identical for A→B and B→A. This is the inference
+-- target for ``connect._upsert_suggestion``'s ON CONFLICT.
+CREATE UNIQUE INDEX IF NOT EXISTS uq_link_suggestions_unordered_pair
+    ON link_suggestions (
+        LEAST(source_doc_id, target_doc_id),
+        GREATEST(source_doc_id, target_doc_id)
+    );
+
+COMMIT;

brain/migrations/023_search_queries_fts_count.sql

@@ -0,0 +1,28 @@
+-- 023_search_queries_fts_count.sql — record the FTS (lexical) leg hit count.
+-- Plan 08 (`brain gaps`) design gap, found in live QA: hybrid search's VECTOR
+-- leg always returns nearest neighbours, so an off-corpus query logs
+-- result_count > 0 (filler) and the result_count = 0 detector never fires. The
+-- FTS (lexical) leg matching ZERO chunks is the real "knowledge gap" signal:
+-- the corpus has no lexical trace of the query. This column records that leg's
+-- hit count so `brain gaps` can key off `fts_count = 0`.
+--
+-- Additive + idempotent. Adds ONLY the nullable ``fts_count`` column + one
+-- partial index. Old rows keep ``fts_count IS NULL`` and the detector falls
+-- back to the historical ``result_count = 0`` semantics for them. NULL (not 0)
+-- is the right default: a 0 default would mislabel every legacy row as a
+-- lexical miss. NEVER edit shipped migrations 001-021.
+--
+-- Numbered 023 to avoid colliding with the concurrently-shipping 022
+-- (link_suggestions); this migration references NO 022 objects.
+
+BEGIN;
+
+ALTER TABLE search_queries ADD COLUMN IF NOT EXISTS fts_count INT;
+
+-- Partial index for the lexical-miss hot path (the new headline gap signal),
+-- mirroring the existing result_count = 0 partial index from migration 019.
+CREATE INDEX IF NOT EXISTS search_queries_fts_zero_idx
+    ON search_queries (tenant_id, at DESC)
+    WHERE fts_count = 0;
+
+COMMIT;

brain/quartz_overrides/__init__.py

@@ -0,0 +1,8 @@
+"""Quartz overlay sources — TypeScript/SCSS files that customise Quartz rendering.
+
+This package exists solely so that ``importlib.resources.files("brain.quartz_overrides")``
+resolves to this directory regardless of whether the brain package is installed in
+editable mode (``pip install -e``) or as a regular wheel.  The Python files inside are
+not imported directly; the overlay step in ``brain.vault.quartz_overlay`` walks the
+directory tree and copies everything here into a live Quartz workspace.
+"""

brain/quartz_overrides/quartz/bootstrap-cli.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env -S node --no-deprecation
+// Brain wiki overlay — quartz/bootstrap-cli.mjs
+//
+// This file shadows the upstream ``~/brain-vault/.quartz/quartz/bootstrap-cli.mjs``.
+// All upstream commands are preserved verbatim.  The only addition is the
+// ``build-partial`` command, which wires to ``partialBuildContent`` (exported from
+// the handlers overlay at quartz/cli/handlers.js via build_partial_handler.js).
+//
+// T4 addition (Plan B v3 — per-file emit fast path):
+//   ``build-partial``  — partial rebuild for a single changed slug.
+//   Usage: node bootstrap-cli.mjs build-partial --slug <slug> [--directory <vault>] [--output <dir>]
+//   Handler: partialBuildContent (from ./cli/handlers.js → ./cli/build_partial_handler.js)
+//   Args:    BuildPartialArgv (from ./cli/args.js)
+
+import yargs from "yargs"
+import { hideBin } from "yargs/helpers"
+import {
+  handleBuild,
+  handleCreate,
+  handleUpdate,
+  handleRestore,
+  handleSync,
+  partialBuildContent,
+} from "./cli/handlers.js"
+import { CommonArgv, BuildArgv, CreateArgv, SyncArgv, BuildPartialArgv } from "./cli/args.js"
+import { version } from "./cli/constants.js"
+
+yargs(hideBin(process.argv))
+  .scriptName("quartz")
+  .version(version)
+  .usage("$0 <cmd> [args]")
+  .command("create", "Initialize Quartz", CreateArgv, async (argv) => {
+    await handleCreate(argv)
+  })
+  .command("update", "Get the latest Quartz updates", CommonArgv, async (argv) => {
+    await handleUpdate(argv)
+  })
+  .command(
+    "restore",
+    "Try to restore your content folder from the cache",
+    CommonArgv,
+    async (argv) => {
+      await handleRestore(argv)
+    },
+  )
+  .command("sync", "Sync your Quartz to and from GitHub.", SyncArgv, async (argv) => {
+    await handleSync(argv)
+  })
+  .command("build", "Build Quartz into a bundle of static HTML files", BuildArgv, async (argv) => {
+    await handleBuild(argv)
+  })
+  // brain overlay (T4): fast partial rebuild for a single changed slug.
+  // Re-parses one file, emits its HTML (skipping ContentIndex), and bumps .build-id.
+  .command(
+    "build-partial",
+    "Partial rebuild for a single changed slug (brain fast path)",
+    BuildPartialArgv,
+    async (argv) => {
+      await partialBuildContent(argv)
+    },
+  )
+  .showHelpOnFail(false)
+  .help()
+  .strict()
+  .demandCommand().argv