@aligndottech/cli 0.49.0 → 0.51.0

package/dist/lib/local-db.js

@@ -1,66 +1,14 @@
 import { DatabaseSync } from 'node:sqlite';
 import { randomUUID } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { repoFromSourceUrl } from './repo-identity.js';
-const SCHEMA = `
-CREATE TABLE IF NOT EXISTS decisions (
-  id TEXT PRIMARY KEY,
-  title TEXT NOT NULL,
-  summary TEXT NOT NULL,
-  source_url TEXT,
-  platform TEXT NOT NULL DEFAULT 'cli',
-  created_at TEXT NOT NULL DEFAULT (datetime('now')),
-  repo TEXT,
-  decided_at TEXT,
-  decider_kind TEXT,
-  confirmed_by TEXT,
-  confirmed_at TEXT,
-  ratified_by TEXT,
-  ratified_at TEXT
-);
-
-CREATE TABLE IF NOT EXISTS decision_audit (
-  id TEXT PRIMARY KEY,
-  decision_id TEXT NOT NULL,
-  action TEXT NOT NULL,
-  actor TEXT,
-  detail TEXT,
-  created_at TEXT NOT NULL DEFAULT (datetime('now'))
-);
-
-CREATE TABLE IF NOT EXISTS decision_embeddings (
-  decision_id TEXT PRIMARY KEY REFERENCES decisions(id) ON DELETE CASCADE,
-  embedding BLOB NOT NULL,
-  model TEXT
-);
-
-CREATE TABLE IF NOT EXISTS decision_links (
-  id TEXT PRIMARY KEY,
-  source_id TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
-  target_id TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
-  relation TEXT NOT NULL,
-  confidence REAL NOT NULL DEFAULT 1.0,
-  created_at TEXT NOT NULL DEFAULT (datetime('now'))
-);
-
-CREATE TABLE IF NOT EXISTS decision_refs (
-  decision_id TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
-  ref TEXT NOT NULL,
-  platform TEXT NOT NULL,
-  PRIMARY KEY (decision_id, ref)
-);
-`;
-/**
- * Schema version this build expects. Bump when adding a step to `migrate`.
- *
- * Exported so a test can assert the migration WROTE the version it claims, without hardcoding
- * the number - a test pinning a literal 1 had to be edited by this change rather than passing
- * or failing on its own merits. A parity test also derives the highest `version <` branch in
- * `migrate` from the source and compares it here, because forgetting the bump leaves the new
- * branch running destructively on every open with nothing to stop it.
- */
-export const SCHEMA_VERSION = 6;
+import { dirname, resolve } from 'node:path';
+import { deleteDecisionWithDependents, migrate, SCHEMA, SLACK_TOMBSTONE_TITLE } from './local-db-migrate.js';
+import { bumpRowSetEpoch, rowSetEpoch } from './local-db-epoch.js';
+import { foldKeylessTwin } from './local-db-v7.js';
+import { discussionStart } from './github-text.js';
+import { connectorItemKey, KEYED_PLATFORMS } from './source-key.js';
+import { alignConfigDir, ensurePrivateDir, precreatePrivateFile, tightenGraphFiles } from './private-files.js';
+export { SCHEMA_VERSION } from './local-db-migrate.js';
 /**
  * ALI-829: a source timestamp as this database stores it - ISO-8601 Z - or null.
  *
@@ -92,10 +40,6 @@ export function normaliseDecidedAt(value) {
         return null;
     return new Date(ms).toISOString();
 }
-/** The title connector-core 0.5.0 gave every Slack thread whose root was deleted. The 0.6.0
- *  fetcher titles such a thread from its first human message, or drops it; either way this
- *  row is a duplicate-to-be under the (source_url, title) key, or noise. */
-const SLACK_TOMBSTONE_TITLE = 'This message was deleted.';
 /**
  * A `source_url` is only an identity if it points at ONE thing. Some fetchers substitute a
  * constant when the per-item link is missing, and connector-core ships one:
@@ -136,329 +80,60 @@ export function identifyingSourceUrl(raw) {
     }
     return value;
 }
-/** The five ALI-831 columns, named exactly as the shared contract spells them. One list,
- *  read by the migration; SCHEMA above spells them a second time because a fresh CREATE
- *  TABLE cannot read a constant, and the provenance test pins both against each other. */
-const PROVENANCE_COLUMNS = ['decider_kind', 'confirmed_by', 'confirmed_at', 'ratified_by', 'ratified_at'];
-/**
- * ALI-787: the only embedding model this graph has ever written before the `model` column
- * existed. Verified, not assumed - `git log --all -p` on local-embeddings.ts and
- * local-embeddings-wasm.ts shows exactly one HF model id was ever hardcoded there, across
- * every commit. So backfilling every pre-column row with this is a true historical fact,
- * unlike `decided_at` (step 4 below), which genuinely cannot be derived from an existing row.
- *
- * A deliberate LITERAL, not an import of local-embeddings.ts's EMBEDDING_MODEL_ID: this
- * constant names what was true when the column was added, and must stay that value even
- * after a future model swap changes EMBEDDING_MODEL_ID. Migrations are a historical record.
- */
-const LEGACY_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
-/**
- * One-time data migrations, tracked in SQLite's built-in `user_version`.
- *
- * 1. ALI-503: relabel the cosine-similarity links that were written as `conflicts_with`.
- *    Every such row at version 0 is provably an artefact, because `insertLink` had exactly
- *    one caller and it hardcoded that relation for any pair over 0.65 cosine. No classifier
- *    verdict was ever persisted, so there is no earned row to damage.
- *
- * 2. A decision's `source_url` identifies it, and nothing enforced that: `insertDecision` minted
- *    a fresh UUID per call, so re-importing the same commit added a second copy. The documented
- *    first run does exactly that - `setup --local` seeds from git, then its own outro tells you
- *    to run `align connect git` - so a graph goes from 2 decisions to 4 by following the tips.
- *    Collapse the existing duplicates, then make them unrepresentable with a unique index.
- *
- * 3. ALI-798: add the `repo` column (missing on any graph that predates it) and backfill it
- *    for every existing row from `source_url`, via the same `repoFromSourceUrl` the importer
- *    now stamps new rows with - one reader of the URL shape, used for both. A row whose
- *    source is not code (Jira, Slack, a bare capture) stays NULL, which is "unattributed",
- *    not "wrong": `--repo` scoping always includes unattributed rows alongside the named
- *    repo (see local-gateway-client.ts), so nothing existing becomes invisible.
- *
- * 4. ALI-829: add `decided_at` - when the decision was MADE, from the source's own
- *    timestamp, as distinct from `created_at`, the minute this CLI imported it. Every one
- *    of the 684 rows in the 2026-09-02 measurement carried the ingest minute and nothing
- *    else, so "what changed since March" was unanswerable offline. No backfill, unlike
- *    `repo`: a repo is derivable from a stored source_url, and a decision date is not
- *    derivable from anything already in the row. A re-import fills it in; inventing one
- *    from created_at would write the exact wrong fact this column exists to correct.
- *
- *    Same bump, second step: drop the Slack rows titled by a deleted root. The 0.6.0
- *    fetcher titles a thread from its first human message, and the dedup key is
- *    (source_url, title), so each of those rows would otherwise be re-inserted BESIDE its
- *    tombstone twin on the next import (35 of 39 on the 2026-09-02 graph). The next import
- *    recreates the real ones with real titles; the ones that were only bot output on a
- *    deleted root do not come back, which is the point. Foreign keys are off in this
- *    database (see step 2), so the dependent rows are deleted explicitly - including any
- *    link a human adjudicated on such a row. That is a real loss, accepted: the row's
- *    identity is changing under it, and the re-import classifies the retitled thread
- *    afresh. Scoped to platform = 'slack': a git commit or a captured note that happens to
- *    carry the same words is not a tombstone and is left alone.
- *
- * 5. ALI-831: add the decider/ratified columns (`decider_kind`, `confirmed_by`,
- *    `confirmed_at`, `ratified_by`, `ratified_at`) so an agent-made decision can enter as a
- *    CLAIM a human later stands behind, and the `decision_audit` table the human act is
- *    recorded in. No backfill, on purpose: a row captured before the column reads as
- *    'unknown', and stamping 'human' on it from its platform would be the retroactive
- *    guess align-stack's migration 113 refuses. The columns are added here rather than only
- *    in SCHEMA because CREATE TABLE IF NOT EXISTS never alters an existing table.
- *
- * The version guard is load-bearing rather than tidiness. The same UPDATE run on every open
- * is indistinguishable from this one today, and starts silently eating genuine conflicts the
- * moment anything writes one.
- */
-/**
- * Remove a decision and everything hanging off it. Foreign keys are off in this database
- * (see migrate, step 2), so the dependents are named explicitly rather than cascaded. One
- * writer for the v4 tombstone sweep and the ingest-time twin removal (ALI-829).
- */
-function deleteDecisionWithDependents(db, id) {
-    db.prepare('DELETE FROM decision_links WHERE source_id = ? OR target_id = ?').run(id, id);
-    db.prepare('DELETE FROM decision_refs WHERE decision_id = ?').run(id);
-    db.prepare('DELETE FROM decision_embeddings WHERE decision_id = ?').run(id);
-    db.prepare('DELETE FROM decision_audit WHERE decision_id = ?').run(id);
-    db.prepare('DELETE FROM decisions WHERE id = ?').run(id);
-}
-function migrate(db) {
-    const version = db.prepare('PRAGMA user_version').get().user_version;
-    if (version < 1) {
-        db.exec(`UPDATE decision_links SET relation = 'relates' WHERE relation = 'conflicts_with'`);
-    }
-    if (version < 2) {
-        // IMMEDIATE, not the default DEFERRED: this transaction reads (the survivor scan) before it
-        // writes, and under WAL another writer arriving in between makes the first write fail with
-        // SQLITE_BUSY_SNAPSHOT, which busy_timeout does not retry. Every local command opens the DB
-        // and the advisory hook fires on every agent edit, so a concurrent open is the normal case.
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            // The survivor is the row inserted FIRST. `rowid` rather than `id` breaks a created_at
-            // tie: created_at has one-second granularity so rows written in one import tie routinely,
-            // and ordering by a random UUID would keep an arbitrary one while this comment claimed to
-            // keep the long-standing id. rowid is insertion order (the table is not WITHOUT ROWID).
-            //
-            // Keyed on (source_url, title), not source_url alone. Some fetchers emit a CONSTANT
-            // source_url when the per-item link is missing - connector-core's Teams fallback is
-            // literally 'https://teams.microsoft.com' - and collapsing on the URL alone deleted every
-            // such message but one. Two rows sharing a URL AND a title are duplicates by any reading;
-            // two sharing only the URL are not.
-            db.exec(`
-        CREATE TEMP TABLE dedup_survivor AS
-        SELECT source_url, title, id FROM (
-          SELECT source_url, title, id,
-                 ROW_NUMBER() OVER (PARTITION BY source_url, title ORDER BY created_at, rowid) AS rn
-          FROM decisions WHERE source_url IS NOT NULL
-        ) WHERE rn = 1;
-
-        CREATE TEMP TABLE dedup_dropped AS
-        SELECT d.id AS id, s.id AS survivor_id
-        FROM decisions d JOIN dedup_survivor s
-          ON d.source_url = s.source_url AND d.title = s.title
-        WHERE d.id <> s.id;
-      `);
-            // Repoint edges rather than dropping them: an edge naming a duplicate is a real edge that
-            // happened to name the copy. Dropping it would lose a relationship the user earned.
-            db.exec(`
-        UPDATE decision_links SET source_id = (
-          SELECT survivor_id FROM dedup_dropped WHERE id = decision_links.source_id
-        ) WHERE source_id IN (SELECT id FROM dedup_dropped);
-        UPDATE decision_links SET target_id = (
-          SELECT survivor_id FROM dedup_dropped WHERE id = decision_links.target_id
-        ) WHERE target_id IN (SELECT id FROM dedup_dropped);
-      `);
-            // Both cleanups are scoped to the pairs repointing actually touched. An earlier version
-            // deduplicated decision_links table-wide, which deleted user-earned edges that had nothing
-            // to do with duplication - and kept the lowest UUID rather than the highest confidence.
-            db.exec(`
-        DELETE FROM decision_links
-        WHERE source_id = target_id
-          AND (source_id IN (SELECT survivor_id FROM dedup_dropped)
-            OR target_id IN (SELECT survivor_id FROM dedup_dropped));
-      `);
-            // Explicitly, not by CASCADE: SQLite leaves foreign_keys OFF unless asked, so the
-            // ON DELETE CASCADE in the schema does not fire and these would be orphaned.
-            db.exec(`DELETE FROM decision_embeddings WHERE decision_id IN (SELECT id FROM dedup_dropped)`);
-            db.exec(`DELETE FROM decisions WHERE id IN (SELECT id FROM dedup_dropped)`);
-            db.exec(`DROP TABLE dedup_dropped; DROP TABLE dedup_survivor;`);
-            // Created here rather than in SCHEMA on purpose: SCHEMA runs before this function, so on
-            // any already-duplicated graph the index would fail to build before the collapse could
-            // run. A fresh database passes through the same path with nothing to collapse.
-            //
-            // A distinct name from any previous attempt, because IF NOT EXISTS matches on the NAME
-            // only: an index of the same name with different columns would be silently kept, and
-            // every later insert would then fail with "ON CONFLICT clause does not match".
-            db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS decisions_source_title_unique ON decisions(source_url, title)`);
-            // Same story for edges: insertLink's `OR IGNORE` was decorative without a unique index, so
-            // a re-import stacked an identical relates row every time. Collapse, then constrain.
-            //
-            // This one IS table-wide, unavoidably: the index cannot be created while any duplicate
-            // triple remains anywhere. Every row it removes duplicates another by definition - same
-            // source, same target, same relation. It keeps the HIGHEST confidence rather than the
-            // lowest uuid, so the survivor is the best score rather than an arbitrary one.
-            db.exec(`
-        DELETE FROM decision_links WHERE id NOT IN (
-          SELECT id FROM (
-            SELECT id, ROW_NUMBER() OVER (
-              PARTITION BY source_id, target_id, relation ORDER BY confidence DESC, rowid
-            ) AS rn FROM decision_links
-          ) WHERE rn = 1
-        );
-      `);
-            db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS decision_links_triple_unique ON decision_links(source_id, target_id, relation)`);
-            // Stamped INSIDE the transaction. Outside it, a process killed between COMMIT and the
-            // pragma replays the version-1 relabel on the next open, which turns an adjudicated
-            // conflicts_with edge into relates - the exact silent loss the docstring above warns of.
-            //
-            // Stamps this step's OWN number (2), not SCHEMA_VERSION: a later step (3, below) runs
-            // after this one commits, and if a crash lands between the two, `user_version` must
-            // still read 2 so the version-3 step is not skipped on the next open.
-            db.exec('PRAGMA user_version = 2');
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            // Guarded: SQLITE_FULL, IOERR, BUSY, NOMEM and INTERRUPT auto-roll-back, and an
-            // unconditional ROLLBACK then throws "no transaction is active" and buries the real
-            // cause - so a user whose disk filled mid-migration would be told the wrong thing.
-            if (db.isTransaction)
-                db.exec('ROLLBACK');
-            throw err;
-        }
-    }
-    if (version < 3) {
-        // The column may already exist: a brand-new database's CREATE TABLE (SCHEMA, above)
-        // declares `repo` directly, so on a fresh install this ALTER would fail with "duplicate
-        // column name" if run unconditionally. A legacy database predates the column entirely.
-        const hasRepoColumn = db.prepare('PRAGMA table_info(decisions)').all()
-            .some((c) => c.name === 'repo');
-        if (!hasRepoColumn) {
-            db.exec('ALTER TABLE decisions ADD COLUMN repo TEXT');
-        }
-        // Backfill every row with no repo yet. JS-side because SQLite has no regex function to
-        // apply `repoFromSourceUrl`'s pattern in SQL - and it must be the SAME function the
-        // importer stamps new rows with, or a backfilled row and a freshly-imported one for the
-        // same URL could disagree about which repo they belong to.
-        const rows = db.prepare('SELECT id, source_url FROM decisions WHERE repo IS NULL')
-            .all();
-        if (rows.length) {
-            db.exec('BEGIN IMMEDIATE');
-            try {
-                const update = db.prepare('UPDATE decisions SET repo = ? WHERE id = ?');
-                for (const row of rows) {
-                    const repo = repoFromSourceUrl(row.source_url);
-                    // Only WRITE when a repo was found: leaving a non-code row NULL is the correct
-                    // outcome (unattributed, not "wrong"), and writing NULL over NULL is a no-op
-                    // this loop can just skip.
-                    if (repo)
-                        update.run(repo, row.id);
-                }
-                db.exec('PRAGMA user_version = 3');
-                db.exec('COMMIT');
-            }
-            catch (err) {
-                if (db.isTransaction)
-                    db.exec('ROLLBACK');
-                throw err;
-            }
-        }
-        else {
-            db.exec('PRAGMA user_version = 3');
-        }
-    }
-    if (version < 4) {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            // Same shape as the `repo` step: a fresh database's CREATE TABLE already declares the
-            // column, and a legacy one predates it, so the ALTER is conditional. Checked INSIDE
-            // the write lock, unlike step 3: two processes opening a v3 file at once (the
-            // advisory hook is the normal concurrent case) could otherwise both read "no column"
-            // and the second would die on "duplicate column name". SQLite DDL is transactional.
-            const hasDecidedAt = db.prepare('PRAGMA table_info(decisions)').all()
-                .some((c) => c.name === 'decided_at');
-            if (!hasDecidedAt) {
-                db.exec('ALTER TABLE decisions ADD COLUMN decided_at TEXT');
-            }
-            const tombstones = db.prepare(`SELECT id FROM decisions WHERE platform = 'slack' AND title = ?`).all(SLACK_TOMBSTONE_TITLE);
-            for (const { id } of tombstones)
-                deleteDecisionWithDependents(db, id);
-            // Stamped inside the transaction, for the reason step 2 gives.
-            db.exec('PRAGMA user_version = 4');
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            if (db.isTransaction)
-                db.exec('ROLLBACK');
-            throw err;
-        }
-    }
-    if (version < 5) {
-        // Inside the write lock, for the reason step 4 gives: two concurrent opens of a v4
-        // file must not both read "no column" and race the ALTER.
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const existing = new Set(db.prepare('PRAGMA table_info(decisions)').all().map((c) => c.name));
-            for (const column of PROVENANCE_COLUMNS) {
-                if (!existing.has(column))
-                    db.exec(`ALTER TABLE decisions ADD COLUMN ${column} TEXT`);
-            }
-            db.exec('PRAGMA user_version = 5');
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            if (db.isTransaction)
-                db.exec('ROLLBACK');
-            throw err;
-        }
-    }
-    if (version < 6) {
-        // Inside the write lock, for the reason step 4/5 give: two concurrent opens of a v5
-        // file must not both read "no column" and race the ALTER.
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const hasModel = db.prepare('PRAGMA table_info(decision_embeddings)').all()
-                .some((c) => c.name === 'model');
-            if (!hasModel) {
-                db.exec('ALTER TABLE decision_embeddings ADD COLUMN model TEXT');
-            }
-            // Every row that predates the column was written by LEGACY_EMBEDDING_MODEL - see its
-            // doc comment for how that is verified rather than assumed. Only rows with no tag yet
-            // are touched, so re-running this on an already-migrated database is a no-op.
-            db.prepare('UPDATE decision_embeddings SET model = ? WHERE model IS NULL').run(LEGACY_EMBEDDING_MODEL);
-            db.exec('PRAGMA user_version = 6');
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            if (db.isTransaction)
-                db.exec('ROLLBACK');
-            throw err;
-        }
-    }
-    if (version < SCHEMA_VERSION) {
-        db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
-    }
-}
 /** Every column a DecisionRow carries, aliased to its camelCase name. One writer, read by
  *  both row readers, so a new column cannot be added to one SELECT and missed by the other. */
 const DECISION_COLUMNS = 'id, title, summary, source_url as sourceUrl, platform, created_at as createdAt, repo, decided_at as decidedAt, ' +
     'decider_kind as deciderKind, confirmed_by as confirmedBy, confirmed_at as confirmedAt, ' +
     'ratified_by as ratifiedBy, ratified_at as ratifiedAt';
+/** A person's ratification or confirmation covers the text they read (review finding 4). */
+const ATTESTED = 'decisions.ratified_at IS NOT NULL OR decisions.confirmed_at IS NOT NULL';
 export function createLocalDb(dbPath) {
     // SQLite creates the DB file but not its parent directory, so on a clean machine
     // (~/.config/align-cli absent) `align setup --local` crashed with "unable to open
     // database file". Create the directory first. ':memory:' has no parent.
     //
     // Still true after the move off better-sqlite3: node:sqlite does not mkdir either.
+    //
+    // The directory is created 0700 and the file 0600 before SQLite opens it (whose own default for a
+    // new file is 0644). The file is tightened on every open, and so is the folder when it is align's own
+    // config folder (private-files.ts). SQLite gives the
+    // -wal and -shm it creates the main file's mode, so they follow it.
     if (dbPath !== ':memory:') {
-        mkdirSync(dirname(dbPath), { recursive: true });
+        const dir = dirname(dbPath);
+        // Throws the real reason (ENOTDIR, EACCES) rather than SQLite's "unable to open database file".
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (resolve(dir) === resolve(alignConfigDir()))
+            ensurePrivateDir(dir);
+        precreatePrivateFile(dbPath);
+        tightenGraphFiles(dbPath);
     }
     const db = new DatabaseSync(dbPath);
-    db.exec('PRAGMA journal_mode = WAL');
-    db.exec(SCHEMA);
-    migrate(db);
+    // 30s: the longest measured v7 migration (100k rows, 33k merges) takes about 5s, so a waiting
+    // opener outlasts it with margin. First, before anything that needs a lock: every local command and the advisory hook open
+    // this file, so a concurrent opener is normal, and without a timeout it fails at once with
+    // "database is locked" instead of waiting for the migration in progress.
+    db.exec('PRAGMA busy_timeout = 30000');
+    try {
+        db.exec('PRAGMA journal_mode = WAL');
+        db.exec(SCHEMA);
+        migrate(db);
+    }
+    catch (err) {
+        db.close();
+        throw err;
+    }
     // Shared by insertLink and resolveRefs (ALI-796), so there is one writer of the
     // decision_links insert rather than two copies of the same ON CONFLICT clause.
+    // `detectorVersion` (schema v12): which detector wrote the edge. Omitted means 'v0'; only the
+    // v1 detector passes 'v1'. A conflict on the triple keeps the stored version: same relation,
+    // nothing re-typed.
     function insertLinkRow(link) {
-        db.prepare(`INSERT INTO decision_links (id, source_id, target_id, relation, confidence) VALUES (?, ?, ?, ?, ?)
+        db.prepare(`INSERT INTO decision_links (id, source_id, target_id, relation, confidence, detector_version) VALUES (?, ?, ?, ?, ?, ?)
        ON CONFLICT(source_id, target_id, relation)
-         DO UPDATE SET confidence = MAX(confidence, excluded.confidence)`).run(randomUUID(), link.sourceId, link.targetId, link.relation, link.confidence);
+         DO UPDATE SET confidence = MAX(confidence, excluded.confidence)`).run(link.id ?? randomUUID(), link.sourceId, link.targetId, link.relation, link.confidence, link.detectorVersion ?? 'v0');
     }
-    return {
+    let dataVersionStmt;
+    const api = {
         /**
          * Insert, or refresh the decision that already carries this `source_url`, returning the id
          * that now holds it.
@@ -484,15 +159,39 @@ export function createLocalDb(dbPath) {
          * change which repo it points at between imports.
          */
         insertDecision(row) {
-            const inserted = db.prepare(`INSERT INTO decisions (id, title, summary, source_url, platform, repo, decided_at, decider_kind) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            // L2: a one-item-per-URL connector item upserts on its source_key, and that branch takes
+            // the new title, so an edited PR title updates the row instead of adding a twin. Every
+            // other row (sessions, captures, docs) keeps the (source_url, title) identity.
+            //
+            // Both branches clear enriched_at: the row's text may have changed, so its links are not
+            // known to be current until ingestOne's link pass marks it again (Decision 30).
+            const sourceUrl = identifyingSourceUrl(row.sourceUrl);
+            const key = (row.keyed ? connectorItemKey(row.platform, sourceUrl) : undefined) ?? null;
+            api.foldPendingTwin(sourceUrl, row.title, row.platform, row.keyed);
+            const inserted = db.prepare(`INSERT INTO decisions (id, title, summary, source_url, platform, repo, decided_at, decider_kind, source_key, detail_pending) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(source_key) WHERE source_key IS NOT NULL DO UPDATE SET
+           title = CASE WHEN ${ATTESTED} THEN decisions.title ELSE excluded.title END,
+           summary = CASE WHEN ${ATTESTED} THEN decisions.summary ELSE excluded.summary END,
+           platform = excluded.platform,
+           repo = COALESCE(excluded.repo, decisions.repo),
+           decided_at = COALESCE(excluded.decided_at, decisions.decided_at),
+           -- An attested row keeps its text, so it keeps the flag that describes that text (review 8).
+           -- A thin arrival whose body IS the stored body (ingestOne passed the stored text on
+           -- because the stored one is richer) must not turn a complete row pending again.
+           detail_pending = CASE
+             WHEN ${ATTESTED} THEN decisions.detail_pending
+             WHEN excluded.detail_pending = 1 AND decisions.detail_pending = 0 AND excluded.summary = decisions.summary THEN 0
+             ELSE excluded.detail_pending END,
+           enriched_at = CASE WHEN ${ATTESTED} THEN decisions.enriched_at ELSE NULL END
          ON CONFLICT(source_url, title) DO UPDATE SET
            summary = excluded.summary, platform = excluded.platform,
            repo = COALESCE(excluded.repo, decisions.repo),
-           decided_at = COALESCE(excluded.decided_at, decisions.decided_at)
-         RETURNING id`).get(randomUUID(), row.title, row.summary, identifyingSourceUrl(row.sourceUrl), row.platform, row.repo ?? null, 
+           decided_at = COALESCE(excluded.decided_at, decisions.decided_at),
+           enriched_at = NULL
+         RETURNING id`).get(randomUUID(), row.title, row.summary, sourceUrl, row.platform, row.repo ?? null, 
             // `||`, not `??`: COALESCE('', old) is '', so an empty string would blank a stored
             // date. Callers normalise, but this is the one place the column is written.
-            row.decidedAt || null, row.deciderKind ?? null);
+            row.decidedAt || null, row.deciderKind ?? null, key, row.detailPending ? 1 : 0);
             return inserted.id;
         },
         /**
@@ -519,13 +218,95 @@ export function createLocalDb(dbPath) {
          * A null `sourceUrl` is always null here: SQLite treats each NULL in a unique index as
          * distinct, so those rows never conflict and every one of them really is new.
          */
-        findIdBySource(sourceUrl, title) {
+        findIdBySource(sourceUrl, title, platform, keyed) {
             const identity = identifyingSourceUrl(sourceUrl);
             if (identity === null)
                 return null;
+            // L2: with the platform, a one-item-per-URL item is found by its source_key, so a retitled
+            // PR is recognised as the row insertDecision is about to update, not as a new one.
+            const key = platform === undefined || !keyed ? undefined : connectorItemKey(platform, identity);
+            if (key !== undefined) {
+                const byKey = db.prepare(`SELECT id FROM decisions WHERE source_key = ?`).get(key);
+                if (byKey)
+                    return byKey.id;
+            }
             const row = db.prepare(`SELECT id FROM decisions WHERE source_url = ? AND title = ?`).get(identity, title);
             return row?.id ?? null;
         },
+        /**
+         * Review finding 4: what a keyed re-import may write over row `id`. A ratified or confirmed
+         * row keeps the text a person attested; the incoming text is recorded once as a
+         * `text_revision_pending` audit note and the stored text is returned. Any other row (or an
+         * unknown id) gets the incoming text back unchanged.
+         */
+        keepProtectedText(id, title, summary, thin = false) {
+            const row = db.prepare(`SELECT title, summary, detail_pending, ratified_at, confirmed_at FROM decisions WHERE id = ?`).get(id);
+            if (row && row.ratified_at === null && row.confirmed_at === null && thin && row.detail_pending === 0) {
+                // L3: `thin` is an items-first arrival (discussion not fetched). The stored row is complete
+                // and has a discussion block: keep the BLOCK and take everything else from the arrival
+                // (title, body, Status, Repo), so a merge, a rename or an edit still lands. The result
+                // equals the stored text when nothing changed, which makes the caller's unchanged-skip fire.
+                const keep = discussionStart(row.summary);
+                if (keep !== -1 && discussionStart(summary) === -1) {
+                    return { title, summary: summary + row.summary.slice(keep), keptDiscussion: true };
+                }
+            }
+            if (!row || (row.ratified_at === null && row.confirmed_at === null))
+                return { title, summary };
+            if (row.title !== title || row.summary !== summary) {
+                const detail = JSON.stringify({ title, summary });
+                const seen = db.prepare(`SELECT 1 AS hit FROM decision_audit WHERE decision_id = ? AND action = 'text_revision_pending' AND detail = ?`).get(id, detail);
+                if (!seen) {
+                    api.insertAudit({ decisionId: id, action: 'text_revision_pending', actor: null, detail });
+                    // Bounded: an upstream that changes every sync would otherwise add a row per sync.
+                    db.prepare(`DELETE FROM decision_audit WHERE decision_id = ? AND action = 'text_revision_pending' AND rowid NOT IN
+            (SELECT rowid FROM decision_audit WHERE decision_id = ? AND action = 'text_revision_pending' ORDER BY rowid DESC LIMIT 5)`).run(id, id);
+                }
+            }
+            return { title: row.title, summary: row.summary };
+        },
+        /** The id of the connector-imported item `url` names, under any platform, or null. A capture
+         *  of that URL must not rewrite the imported text (L2 review finding 1). */
+        findKeyedIdByUrl(url) {
+            const identity = identifyingSourceUrl(url);
+            if (identity === null)
+                return null;
+            for (const platform of KEYED_PLATFORMS) {
+                const key = connectorItemKey(platform, identity);
+                const hit = key === undefined ? undefined : db.prepare(`SELECT id FROM decisions WHERE source_key = ?`).get(key);
+                if (hit)
+                    return hit.id;
+            }
+            return null;
+        },
+        /**
+         * A keyless row at this (source_url, title) is a twin an older binary wrote beside the keyed
+         * one. Adopt it as the keyed row, or fold it with the row that already holds the key (the
+         * attested one survives). ingestOne calls this BEFORE it looks the item up, so the text it
+         * protects and embeds is the survivor's. No-op for an unkeyed call.
+         */
+        foldPendingTwin(sourceUrl, title, platform, keyed) {
+            const key = keyed ? connectorItemKey(platform, sourceUrl) : undefined;
+            if (key === undefined)
+                return;
+            const twin = db.prepare(`SELECT id FROM decisions WHERE source_url = ? AND title = ? AND source_key IS NULL`).get(sourceUrl, title);
+            if (!twin)
+                return;
+            const holder = db.prepare(`SELECT id FROM decisions WHERE source_key = ?`).get(key);
+            if (holder)
+                foldKeylessTwin(db, twin.id, holder.id, key);
+            else
+                db.prepare(`UPDATE decisions SET source_key = ? WHERE id = ?`).run(key, twin.id);
+        },
+        /** A capture of a URL a connector already imported: audit it, change nothing, return the row. */
+        noteCaptureOfHeldItem(url) {
+            const id = api.findKeyedIdByUrl(url);
+            const row = id === null ? null : api.getDecisionById(id);
+            const today = id === null ? undefined : db.prepare(`SELECT 1 AS hit FROM decision_audit WHERE decision_id = ? AND action = 'capture_seen' AND date(created_at) = date('now')`).get(id);
+            if (row && !today)
+                api.insertAudit({ decisionId: row.id, action: 'capture_seen', actor: null, detail: url });
+            return row;
+        },
         /**
          * `filter.repo` scopes to one repo's rows. `includeUnattributed` (ALI-798's own rule:
          * "repo = ? OR repo IS NULL") also returns rows with no repo at all - a Jira ticket, a
@@ -585,6 +366,19 @@ export function createLocalDb(dbPath) {
          RETURNING confirmed_at AS confirmedAt`).get(confirmedBy, confirmedAt, id);
             return row ?? null;
         },
+        /**
+         * L2, Decision 30: the decision's ingest finished, link pass included. ingestOne is the one
+         * caller, and calls it as its last write; insertDecision clears it whenever it rewrites the
+         * row. NULL therefore means "links not known to be current", and the unchanged-skip will
+         * not skip such a row.
+         */
+        markEnriched(id) {
+            db.prepare(`UPDATE decisions SET enriched_at = ? WHERE id = ?`).run(new Date().toISOString(), id);
+        },
+        getEnrichedAt(id) {
+            const row = db.prepare(`SELECT enriched_at AS e FROM decisions WHERE id = ?`).get(id);
+            return row?.e ?? null;
+        },
         /** ALI-831: one row per human act on a decision (ratified, pushed), so "who stood behind
          *  this, and when" is answerable after the fact. Append-only by construction. */
         insertAudit(entry) {
@@ -656,6 +450,10 @@ export function createLocalDb(dbPath) {
          * (local-gateway-client.ts's ingestOne) always passes EMBEDDING_MODEL_ID.
          */
         setEmbedding(decisionId, embedding, model) {
+            // Replacing a vector changes what a copy of the embeddings should hold; a first write
+            // only adds a row, which the writer appends itself. (rowSetEpoch's contract.)
+            if (db.prepare('SELECT 1 FROM decision_embeddings WHERE decision_id = ?').get(decisionId))
+                bumpRowSetEpoch(db);
             db.prepare(`INSERT OR REPLACE INTO decision_embeddings (decision_id, embedding, model) VALUES (?, ?, ?)`).run(decisionId, Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength), model ?? null);
         },
         getEmbedding(decisionId) {
@@ -746,6 +544,16 @@ export function createLocalDb(dbPath) {
         insertLink(link) {
             insertLinkRow(link);
         },
+        /**
+         * LM: the ONE way a link is deleted on behalf of a person's mark. `align mark <a> replaces <b>`
+         * writes its supersedes link under the id `mark:<judgement id>` (when the classifier had not
+         * already written that edge, in which case the edge keeps its own id and is not ours), and
+         * `--undo` removes exactly that row here. The id is built inside this method, so no caller can
+         * name another link: a classifier edge, or a link another mark owns, cannot be reached from here.
+         */
+        deleteMarkLink(judgementId) {
+            return Number(db.prepare(`DELETE FROM decision_links WHERE id = ? AND relation = 'supersedes'`).run(`mark:${judgementId}`).changes);
+        },
         /**
          * ALI-1065: a pair gets ONE edge, never two. `insertLinkRow`'s unique index is on
          * (source_id, target_id, relation), so writing `supersedes` for a pair that already
@@ -755,8 +563,26 @@ export function createLocalDb(dbPath) {
          * classification can upgrade a cosine `relates` edge into a typed one atomically.
          */
         replaceLink(link) {
-            db.prepare('DELETE FROM decision_links WHERE (source_id = ? AND target_id = ?) OR (source_id = ? AND target_id = ?)').run(link.sourceId, link.targetId, link.targetId, link.sourceId);
-            insertLinkRow(link);
+            // LM: an edge a person's `align mark ... replaces` wrote (id `mark:<judgement id>`) is theirs, not
+            // the classifier's to upgrade away: deleting it would orphan the judgement, and `--undo` could
+            // no longer find its link. The pair may then carry that edge beside the new one.
+            // One unit (review F8): a failure after the delete must not leave the pair unlinked. A
+            // SAVEPOINT, not BEGIN, so a caller already inside a transaction can still call this.
+            db.exec('SAVEPOINT replace_link');
+            try {
+                // Review F1: a `replaces` mark written over an existing classifier row keeps that row's id,
+                // so the judgement itself is what protects it, not only the `mark:` id.
+                db.prepare(`DELETE FROM decision_links WHERE ((source_id = ? AND target_id = ?) OR (source_id = ? AND target_id = ?)) AND id NOT LIKE 'mark:%'
+             AND NOT (relation = 'supersedes' AND EXISTS (SELECT 1 FROM local_judgements j
+               WHERE j.kind = 'supersede' AND j.decision_id = decision_links.source_id AND j.counterpart_id = decision_links.target_id))`).run(link.sourceId, link.targetId, link.targetId, link.sourceId);
+                insertLinkRow(link);
+                db.exec('RELEASE replace_link');
+            }
+            catch (err) {
+                db.exec('ROLLBACK TO replace_link');
+                db.exec('RELEASE replace_link');
+                throw err;
+            }
         },
         /**
          * ALI-792: what this decision's text points at (ticket keys, #N, tool URLs).
@@ -851,6 +677,11 @@ export function createLocalDb(dbPath) {
             }
             return db.prepare(sql).all(...params);
         },
+        /** True when another stored decision supersedes this one: the v1 detector shows it RETIRED and refuses a verdict edge (review F5). */
+        isSuperseded(decisionId) {
+            return db.prepare(`SELECT 1 FROM decision_links l JOIN decisions s ON s.id = l.source_id
+         WHERE l.target_id = ? AND l.relation IN ('supersedes', 'partially_supersedes') LIMIT 1`).get(decisionId) !== undefined;
+        },
         getStats() {
             const decisions = db.prepare(`SELECT COUNT(*) as n FROM decisions`).get().n;
             const embeddings = db.prepare(`SELECT COUNT(*) as n FROM decision_embeddings`).get().n;
@@ -862,11 +693,30 @@ export function createLocalDb(dbPath) {
             // decision_refs listed explicitly: SQLite leaves foreign_keys OFF unless asked,
             // so the schema's ON DELETE CASCADE never fires (same fact the v2 migration
             // documents above).
+            bumpRowSetEpoch(db);
             db.exec(`DELETE FROM decision_refs; DELETE FROM decision_links; DELETE FROM decision_embeddings; DELETE FROM decisions;`);
         },
+        /** Goes up whenever a decision is deleted or re-id'd or an embedding is deleted or replaced
+         *  on this connection (see local-db-epoch.ts). A holder of a copy of the embeddings
+         *  compares it to the value it built at. */
+        rowSetEpoch() {
+            return rowSetEpoch(db);
+        },
+        /** SQLite's data_version: changes when ANOTHER connection commits (another process, an
+         *  MCP server, a second CLI), never for this connection's own writes. The cross-process
+         *  half of "has the graph moved under my copy of it". */
+        dataVersion() {
+            return (dataVersionStmt ??= db.prepare('PRAGMA data_version')).get()['data_version'];
+        },
+        /** Stored embeddings of every model: an upper bound on what a matrix would hold, read
+         *  before building one so a huge graph is never loaded just to be refused. */
+        countEmbeddings() {
+            return db.prepare('SELECT COUNT(*) AS n FROM decision_embeddings').get().n;
+        },
         close() {
             db.close();
         },
     };
+    return api;
 }
 //# sourceMappingURL=local-db.js.map