@aligndottech/cli 0.18.0 → 0.19.1

package/dist/lib/local-db.d.ts

@@ -17,7 +17,51 @@ export interface DbStats {
     decisions: number;
     embeddings: number;
 }
+/**
+ * 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 declare const SCHEMA_VERSION = 2;
+/**
+ * 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:
+ *
+ *     dist/fetchers/teams.js:60   source_url: msg.webUrl ?? 'https://teams.microsoft.com'
+ *
+ * Treating that as an identity is destructive once the column is unique - every such message
+ * collapses onto one row. So a bare origin, an empty string and whitespace are normalised to
+ * null, which means "no identity" and never collides.
+ *
+ * Normalised away rather than stored beside a separate identity column: a URL that addresses a
+ * host and nothing on it is not a link to the decision, so keeping it would render a
+ * "source" link in `align search` that takes the reader to a homepage. One column, one meaning.
+ *
+ * Deliberately narrow: a URL with any path is treated as identifying, because Confluence's
+ * `linkBase`
+ * fallback (`https://site.atlassian.net/wiki`) cannot be told apart from a genuinely short page
+ * URL, and a hardcoded list of known fallbacks would be wrong the day a fetcher invents one
+ * more. That case is caught by the other half of the key instead - uniqueness is on
+ * (source_url, title).
+ */
+export declare function identifyingSourceUrl(raw: string | null): string | null;
 export declare function createLocalDb(dbPath: string): {
+    /**
+     * Insert, or refresh the decision that already carries this `source_url`, returning the id
+     * that now holds it.
+     *
+     * Refresh rather than ignore: a rewritten commit message or an edited Jira issue should be
+     * current in the graph. Returning the EXISTING id on a conflict is what keeps the caller's
+     * `setEmbedding` on the surviving row instead of orphaning a vector.
+     *
+     * A null `source_url` never conflicts - SQLite treats each NULL in a unique index as
+     * distinct - so `align capture` with no URL keeps inserting, by construction rather than by
+     * a special case here.
+     */
     insertDecision(row: {
         title: string;
         summary: string;
@@ -32,6 +76,16 @@ export declare function createLocalDb(dbPath: string): {
         decisionId: string;
         embedding: Float32Array;
     }>;
+    /**
+     * `INSERT OR IGNORE` here was decorative: the id is a fresh UUID, so the only key that
+     * could conflict was guaranteed not to, and there was no unique index on the triple. With
+     * decisions now deduping, a re-import returns the SAME decision id and this added another
+     * identical edge every time - measured 1, 2, 3 over three imports, inflating the
+     * "similar decisions found" count `align local status` prints.
+     *
+     * The unique index (created in migrate) is what makes the OR IGNORE real. Confidence is
+     * refreshed rather than ignored so a better score replaces a worse one.
+     */
     insertLink(link: {
         sourceId: string;
         targetId: string;

package/dist/lib/local-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-db.d.ts","sourceRoot":"","sources":["../../src/lib/local-db.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAoDD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM;wBAapB;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;qBAQ1F,WAAW,EAAE;wBAMV,MAAM,GAAG,WAAW,GAAG,IAAI;6BAMtB,MAAM,aAAa,YAAY,GAAG,IAAI;6BAMtC,MAAM,GAAG,YAAY,GAAG,IAAI;wBAQjC,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,YAAY,CAAA;KAAE,CAAC;qBAUzD;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;uBAMjF;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,EAAE;gBAQ7D,OAAO;eAQR,IAAI;aAIN,IAAI;EAIhB;AAED,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC"}
+{"version":3,"file":"local-db.d.ts","sourceRoot":"","sources":["../../src/lib/local-db.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AA2BD;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAetE;AA2HD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM;IAaxC;;;;;;;;;;;OAWG;wBACiB;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;qBAe1F,WAAW,EAAE;wBAMV,MAAM,GAAG,WAAW,GAAG,IAAI;6BAMtB,MAAM,aAAa,YAAY,GAAG,IAAI;6BAMtC,MAAM,GAAG,YAAY,GAAG,IAAI;wBAQjC,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,YAAY,CAAA;KAAE,CAAC;IAU1E;;;;;;;;;OASG;qBACc;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;uBAQjF;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,EAAE;gBAQ7D,OAAO;eAQR,IAAI;aAIN,IAAI;EAIhB;AAED,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/lib/local-db.js

@@ -26,8 +26,56 @@ CREATE TABLE IF NOT EXISTS decision_links (
   created_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 `;
-/** Schema version this build expects. Bump when adding a step to `migrate`. */
-const SCHEMA_VERSION = 1;
+/**
+ * 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 = 2;
+/**
+ * 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:
+ *
+ *     dist/fetchers/teams.js:60   source_url: msg.webUrl ?? 'https://teams.microsoft.com'
+ *
+ * Treating that as an identity is destructive once the column is unique - every such message
+ * collapses onto one row. So a bare origin, an empty string and whitespace are normalised to
+ * null, which means "no identity" and never collides.
+ *
+ * Normalised away rather than stored beside a separate identity column: a URL that addresses a
+ * host and nothing on it is not a link to the decision, so keeping it would render a
+ * "source" link in `align search` that takes the reader to a homepage. One column, one meaning.
+ *
+ * Deliberately narrow: a URL with any path is treated as identifying, because Confluence's
+ * `linkBase`
+ * fallback (`https://site.atlassian.net/wiki`) cannot be told apart from a genuinely short page
+ * URL, and a hardcoded list of known fallbacks would be wrong the day a fetcher invents one
+ * more. That case is caught by the other half of the key instead - uniqueness is on
+ * (source_url, title).
+ */
+export function identifyingSourceUrl(raw) {
+    if (raw === null)
+        return null;
+    const value = raw.trim();
+    if (!value)
+        return null;
+    try {
+        const parsed = new URL(value);
+        // No path, no query, no fragment: this addresses a host, not a thing on it.
+        if ((parsed.pathname === '' || parsed.pathname === '/') && !parsed.search && !parsed.hash) {
+            return null;
+        }
+    }
+    catch {
+        // Not a parseable URL. `git://commit/<sha>` parses, but an opaque key may not, and an
+        // opaque key is still an identity - discarding it would be the destructive direction.
+    }
+    return value;
+}
 /**
  * One-time data migrations, tracked in SQLite's built-in `user_version`.
  *
@@ -36,6 +84,12 @@ const SCHEMA_VERSION = 1;
  *    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 import 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.
+ *
  * 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.
@@ -45,6 +99,101 @@ function migrate(db) {
     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.
+            db.pragma(`user_version = ${SCHEMA_VERSION}`);
+            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.inTransaction)
+                db.exec('ROLLBACK');
+            throw err;
+        }
+    }
     if (version < SCHEMA_VERSION) {
         db.pragma(`user_version = ${SCHEMA_VERSION}`);
     }
@@ -61,10 +210,23 @@ export function createLocalDb(dbPath) {
     db.exec(SCHEMA);
     migrate(db);
     return {
+        /**
+         * Insert, or refresh the decision that already carries this `source_url`, returning the id
+         * that now holds it.
+         *
+         * Refresh rather than ignore: a rewritten commit message or an edited Jira issue should be
+         * current in the graph. Returning the EXISTING id on a conflict is what keeps the caller's
+         * `setEmbedding` on the surviving row instead of orphaning a vector.
+         *
+         * A null `source_url` never conflicts - SQLite treats each NULL in a unique index as
+         * distinct - so `align capture` with no URL keeps inserting, by construction rather than by
+         * a special case here.
+         */
         insertDecision(row) {
-            const id = randomUUID();
-            db.prepare(`INSERT INTO decisions (id, title, summary, source_url, platform) VALUES (?, ?, ?, ?, ?)`).run(id, row.title, row.summary, row.sourceUrl, row.platform);
-            return id;
+            const inserted = db.prepare(`INSERT INTO decisions (id, title, summary, source_url, platform) VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(source_url, title) DO UPDATE SET summary = excluded.summary, platform = excluded.platform
+         RETURNING id`).get(randomUUID(), row.title, row.summary, identifyingSourceUrl(row.sourceUrl), row.platform);
+            return inserted.id;
         },
         listDecisions() {
             return db.prepare(`SELECT id, title, summary, source_url as sourceUrl, platform, created_at as createdAt FROM decisions ORDER BY created_at DESC`).all();
@@ -88,8 +250,20 @@ export function createLocalDb(dbPath) {
                 embedding: new Float32Array(r.embedding.buffer, r.embedding.byteOffset, r.embedding.byteLength / 4),
             }));
         },
+        /**
+         * `INSERT OR IGNORE` here was decorative: the id is a fresh UUID, so the only key that
+         * could conflict was guaranteed not to, and there was no unique index on the triple. With
+         * decisions now deduping, a re-import returns the SAME decision id and this added another
+         * identical edge every time - measured 1, 2, 3 over three imports, inflating the
+         * "similar decisions found" count `align local status` prints.
+         *
+         * The unique index (created in migrate) is what makes the OR IGNORE real. Confidence is
+         * refreshed rather than ignored so a better score replaces a worse one.
+         */
         insertLink(link) {
-            db.prepare(`INSERT OR IGNORE INTO decision_links (id, source_id, target_id, relation, confidence) VALUES (?, ?, ?, ?, ?)`).run(randomUUID(), link.sourceId, link.targetId, link.relation, link.confidence);
+            db.prepare(`INSERT INTO decision_links (id, source_id, target_id, relation, confidence) 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);
         },
         listLinks(filter) {
             let sql = `SELECT id, source_id as sourceId, target_id as targetId, relation, confidence FROM decision_links WHERE 1=1`;

package/dist/lib/local-db.js.map

@@ -1 +1 @@
-{"version":3,"file":"local-db.js","sourceRoot":"","sources":["../../src/lib/local-db.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"local-db.js","sourceRoot":"","sources":["../../src/lib/local-db.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuBd,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAkB;IACrD,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9B,4EAA4E;QAC5E,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,EAAE,IAAI,MAAM,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC1F,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sFAAsF;QACtF,sFAAsF;IACxF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,OAAO,CAAC,EAAqB;IACpC,MAAM,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAW,CAAC;IACtE,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,EAAE,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,4FAA4F;QAC5F,2FAA2F;QAC3F,4FAA4F;QAC5F,4FAA4F;QAC5F,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC3B,IAAI,CAAC;YACH,uFAAuF;YACvF,0FAA0F;YAC1F,0FAA0F;YAC1F,wFAAwF;YACxF,EAAE;YACF,oFAAoF;YACpF,oFAAoF;YACpF,0FAA0F;YAC1F,0FAA0F;YAC1F,oCAAoC;YACpC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;OAaP,CAAC,CAAC;YACH,0FAA0F;YAC1F,oFAAoF;YACpF,EAAE,CAAC,IAAI,CAAC;;;;;;;OAOP,CAAC,CAAC;YACH,wFAAwF;YACxF,2FAA2F;YAC3F,wFAAwF;YACxF,EAAE,CAAC,IAAI,CAAC;;;;;OAKP,CAAC,CAAC;YACH,kFAAkF;YAClF,6EAA6E;YAC7E,EAAE,CAAC,IAAI,CAAC,qFAAqF,CAAC,CAAC;YAC/F,EAAE,CAAC,IAAI,CAAC,kEAAkE,CAAC,CAAC;YAC5E,EAAE,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;YAChE,yFAAyF;YACzF,uFAAuF;YACvF,+EAA+E;YAC/E,EAAE;YACF,uFAAuF;YACvF,qFAAqF;YACrF,+EAA+E;YAC/E,EAAE,CAAC,IAAI,CAAC,iGAAiG,CAAC,CAAC;YAC3G,2FAA2F;YAC3F,qFAAqF;YACrF,EAAE;YACF,uFAAuF;YACvF,wFAAwF;YACxF,sFAAsF;YACtF,+EAA+E;YAC/E,EAAE,CAAC,IAAI,CAAC;;;;;;;;OAQP,CAAC,CAAC;YACH,EAAE,CAAC,IAAI,CAAC,kHAAkH,CAAC,CAAC;YAC5H,sFAAsF;YACtF,oFAAoF;YACpF,yFAAyF;YACzF,EAAE,CAAC,MAAM,CAAC,kBAAkB,cAAc,EAAE,CAAC,CAAC;YAC9C,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,gFAAgF;YAChF,oFAAoF;YACpF,mFAAmF;YACnF,IAAI,EAAE,CAAC,aAAa;gBAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC1C,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IACD,IAAI,OAAO,GAAG,cAAc,EAAE,CAAC;QAC7B,EAAE,CAAC,MAAM,CAAC,kBAAkB,cAAc,EAAE,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,iFAAiF;IACjF,kFAAkF;IAClF,gFAAgF;IAChF,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAC1B,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAChC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,CAAC;IAEZ,OAAO;QACL;;;;;;;;;;;WAWG;QACH,cAAc,CAAC,GAAmF;YAChG,MAAM,QAAQ,GAAG,EAAE,CAAC,OAAO,CACzB;;sBAEc,CACf,CAAC,GAAG,CACH,UAAU,EAAE,EACZ,GAAG,CAAC,KAAK,EACT,GAAG,CAAC,OAAO,EACX,oBAAoB,CAAC,GAAG,CAAC,SAAS,CAAC,EACnC,GAAG,CAAC,QAAQ,CACK,CAAC;YACpB,OAAO,QAAQ,CAAC,EAAE,CAAC;QACrB,CAAC;QAED,aAAa;YACX,OAAO,EAAE,CAAC,OAAO,CACf,+HAA+H,CAChI,CAAC,GAAG,EAAmB,CAAC;QAC3B,CAAC;QAED,eAAe,CAAC,EAAU;YACxB,OAAQ,EAAE,CAAC,OAAO,CAChB,mHAAmH,CACpH,CAAC,GAAG,CAAC,EAAE,CAAwB,IAAI,IAAI,CAAC;QAC3C,CAAC;QAED,YAAY,CAAC,UAAkB,EAAE,SAAuB;YACtD,EAAE,CAAC,OAAO,CACR,mFAAmF,CACpF,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QAC/F,CAAC;QAED,YAAY,CAAC,UAAkB;YAC7B,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CACpB,iEAAiE,CAClE,CAAC,GAAG,CAAC,UAAU,CAAiC,CAAC;YAClD,IAAI,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAC;YACtB,OAAO,IAAI,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;QACxG,CAAC;QAED,gBAAgB;YACd,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CACrB,wDAAwD,CACzD,CAAC,GAAG,EAAuD,CAAC;YAC7D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACpB,UAAU,EAAE,CAAC,CAAC,WAAW;gBACzB,SAAS,EAAE,IAAI,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC,UAAU,GAAG,CAAC,CAAC;aACpG,CAAC,CAAC,CAAC;QACN,CAAC;QAED;;;;;;;;;WASG;QACH,UAAU,CAAC,IAAkF;YAC3F,EAAE,CAAC,OAAO,CACR;;2EAEmE,CACpE,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACpF,CAAC;QAED,SAAS,CAAC,MAAmD;YAC3D,IAAI,GAAG,GAAG,6GAA6G,CAAC;YACxH,MAAM,MAAM,GAAc,EAAE,CAAC;YAC7B,IAAI,MAAM,EAAE,QAAQ,EAAE,CAAC;gBAAC,GAAG,IAAI,mBAAmB,CAAC;gBAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAAC,CAAC;YACnF,IAAI,MAAM,EAAE,UAAU,EAAE,CAAC;gBAAC,GAAG,IAAI,uCAAuC,CAAC;gBAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;YAAC,CAAC;YAC9H,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAc,CAAC;QACrD,CAAC;QAED,QAAQ;YACN,MAAM,SAAS,GAAI,EAAE,CAAC,OAAO,CAAC,qCAAqC,CAAC,CAAC,GAAG,EAAoB,CAAC,CAAC,CAAC;YAC/F,MAAM,UAAU,GAAI,EAAE,CAAC,OAAO,CAAC,+CAA+C,CAAC,CAAC,GAAG,EAAoB,CAAC,CAAC,CAAC;YAC1G,sFAAsF;YACtF,2EAA2E;YAC3E,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;QACnC,CAAC;QAED,OAAO;YACL,EAAE,CAAC,IAAI,CAAC,qFAAqF,CAAC,CAAC;QACjG,CAAC;QAED,KAAK;YACH,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/lib/local-embeddings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-embeddings.d.ts","sourceRoot":"","sources":["../../src/lib/local-embeddings.ts"],"names":[],"mappings":"AAGA,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA0CtE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CASzE"}
+{"version":3,"file":"local-embeddings.d.ts","sourceRoot":"","sources":["../../src/lib/local-embeddings.ts"],"names":[],"mappings":"AAGA,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA6CtE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAmBzE"}

package/dist/lib/local-embeddings.js

@@ -22,17 +22,20 @@ export async function getEmbedding(text) {
                 `(${err.message})`);
         }
         try {
-            // First call downloads the ~90MB model from the Hugging Face Hub.
+            // First call downloads ~23MB from the Hugging Face Hub (huggingface.co), then caches.
             // dtype 'q8' is load-bearing, not a perf tweak: @xenova/transformers@2 loaded
             // quantized weights by default and v3+ default to fp32, which shifts pairwise
             // cosine by up to 2.3e-02 against vectors already persisted in a user's local
             // graph. Pinning q8 holds that to 6.6e-04. See local-embeddings-dtype.test.ts.
+            // The size follows from that pin: q8 fetches onnx/model_quantized.onnx (22.0MiB) plus
+            // the tokenizer, where fp32 would be 86.2MiB. This comment and the copy in setup.ts
+            // and README.md said "~90MB" for both, quoting the file the pin exists to avoid.
             _pipe = (await mod.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
                 dtype: 'q8',
             }));
         }
         catch (err) {
-            throw new Error('Could not load the local embedding model (~90MB, Xenova/all-MiniLM-L6-v2). ' +
+            throw new Error('Could not load the local embedding model (~23MB, Xenova/all-MiniLM-L6-v2, from huggingface.co). ' +
                 'Check your internet connection or proxy and try again. ' +
                 `(${err.message})`);
         }
@@ -41,6 +44,14 @@ export async function getEmbedding(text) {
     return output[0].data;
 }
 export function cosineSimilarity(a, b) {
+    // Loudly, because the silent version is worse than a crash: this loop indexes `b[i]` over
+    // `a.length`, so a shorter `b` yields undefined -> NaN -> `NaN >= threshold` is false, and
+    // findSimilar drops the row as IRRELEVANT. A vector written by a different model would make
+    // decisions quietly unfindable with no error anywhere.
+    if (a.length !== b.length) {
+        throw new Error(`Embedding length mismatch: ${a.length} vs ${b.length}. The local graph holds a vector ` +
+            'from a different model - run `align local reset` and re-import to rebuild it.');
+    }
     let dot = 0, normA = 0, normB = 0;
     for (let i = 0; i < a.length; i++) {
         dot += a[i] * b[i];

package/dist/lib/local-embeddings.js.map

@@ -1 +1 @@
-{"version":3,"file":"local-embeddings.js","sourceRoot":"","sources":["../../src/lib/local-embeddings.ts"],"names":[],"mappings":"AACA,IAAI,KAAK,GAA6B,IAAI,CAAC;AAE3C,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,GAAoG,CAAC;QACzG,IAAI,CAAC;YACH,+EAA+E;YAC/E,yEAAyE;YACzE,gFAAgF;YAChF,EAAE;YACF,0EAA0E;YAC1E,4EAA4E;YAC5E,2EAA2E;YAC3E,4EAA4E;YAC5E,yEAAyE;YACzE,uBAAuB;YACvB,MAAM,eAAe,GAAG,2BAA2B,CAAC;YACpD,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,eAAe,CAAC,CAA0B,CAAC;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,uHAAuH;gBACvH,mHAAmH;gBACnH,IAAK,GAAa,CAAC,OAAO,GAAG,CAC9B,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,kEAAkE;YAClE,8EAA8E;YAC9E,8EAA8E;YAC9E,8EAA8E;YAC9E,+EAA+E;YAC/E,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,oBAAoB,EAAE,yBAAyB,EAAE;gBAC3E,KAAK,EAAE,IAAI;aACZ,CAAC,CAAiC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,6EAA6E;gBAC7E,yDAAyD;gBACzD,IAAK,GAAa,CAAC,OAAO,GAAG,CAC9B,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,OAAO,MAAM,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAe,EAAE,CAAe;IAC/D,IAAI,GAAG,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACrB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACvB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACzB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC;AACvC,CAAC"}
+{"version":3,"file":"local-embeddings.js","sourceRoot":"","sources":["../../src/lib/local-embeddings.ts"],"names":[],"mappings":"AACA,IAAI,KAAK,GAA6B,IAAI,CAAC;AAE3C,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,GAAoG,CAAC;QACzG,IAAI,CAAC;YACH,+EAA+E;YAC/E,yEAAyE;YACzE,gFAAgF;YAChF,EAAE;YACF,0EAA0E;YAC1E,4EAA4E;YAC5E,2EAA2E;YAC3E,4EAA4E;YAC5E,yEAAyE;YACzE,uBAAuB;YACvB,MAAM,eAAe,GAAG,2BAA2B,CAAC;YACpD,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,eAAe,CAAC,CAA0B,CAAC;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,uHAAuH;gBACvH,mHAAmH;gBACnH,IAAK,GAAa,CAAC,OAAO,GAAG,CAC9B,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,sFAAsF;YACtF,8EAA8E;YAC9E,8EAA8E;YAC9E,8EAA8E;YAC9E,+EAA+E;YAC/E,sFAAsF;YACtF,oFAAoF;YACpF,iFAAiF;YACjF,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,oBAAoB,EAAE,yBAAyB,EAAE;gBAC3E,KAAK,EAAE,IAAI;aACZ,CAAC,CAAiC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,kGAAkG;gBAClG,yDAAyD;gBACzD,IAAK,GAAa,CAAC,OAAO,GAAG,CAC9B,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,OAAO,MAAM,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAe,EAAE,CAAe;IAC/D,0FAA0F;IAC1F,2FAA2F;IAC3F,4FAA4F;IAC5F,uDAAuD;IACvD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,8BAA8B,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,mCAAmC;YACxF,+EAA+E,CAChF,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACrB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACvB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACzB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC;AACvC,CAAC"}

package/dist/lib/local-gateway-client.d.ts

@@ -27,7 +27,39 @@ export declare const SIMILARITY_THRESHOLD = 0.65;
  * than two wrong decisions, because the caller can act on it.
  */
 export declare const SEARCH_THRESHOLD = 0.25;
+/**
+ * Candidate floor for ADJUDICATION - the path that then pays an LLM per candidate.
+ *
+ * Deliberately higher than the retrieval floor below, because this surface is expensive in
+ * three ways the hook is not: up to 5 sequential calls to the user's own provider, ~11s of
+ * latency, and an exit code. A keyless CI runner that gets `no-context` today exits 0; the
+ * moment retrieval finds anything it gets `unknown` and exits 2. And the classifier cannot
+ * reject a candidate - its vocabulary is ten positive relations with no "unrelated" - so a
+ * loose candidate that reaches it is reported rather than filtered.
+ *
+ * Deliberately NOT recalibrated with the retrieval floor. Measured on the corpus, 0.30 would
+ * recover four more related pairs here too, and that trade is a separate decision with a
+ * separate blast radius (see relatedness-calibration.test.ts).
+ */
 export declare const RELATES_THRESHOLD = 0.45;
+/**
+ * Candidate floor for RETRIEVAL ONLY (`depth: 'related'`, the agent editor hook).
+ *
+ * Measured, not chosen. Against fixtures/relatedness-corpus.json: 0.45 recovered 3 of 8 related
+ * pairs, 0.30 recovers 7 of 8, and neither admits a single unrelated pair. 0.25 scores the same
+ * 7 of 8, so the tie-break is margin over the worst false positive (0.2051): 0.30 clears it by
+ * 0.095 against 0.25's 0.045.
+ *
+ * 0.30 is also where this constant sat until commit 0cbef08 raised it to 0.45 inside a rename,
+ * unmentioned and unmeasured. So this is a revert with evidence attached rather than a new
+ * guess, and the evidence is a test that fails if the corpus stops supporting it.
+ *
+ * Safe to be looser here precisely because this path is cheap and honest: it returns above
+ * Stage 2, so it makes no provider call, and what the hook prints declines to assert anything
+ * ("related by content search and have NOT been adjudicated"). That is the same posture as
+ * `align search`, which has run at 0.25 all along - as has MCP `align_get_related_decisions`.
+ */
+export declare const RETRIEVAL_RELATES_THRESHOLD = 0.3;
 export declare const DRIFT_THRESHOLD = 0.5;
 export declare function createLocalGatewayClient(dbPath: string): {
     /** Release the underlying SQLite handle (required on Windows before deleting the file). */
@@ -77,7 +109,10 @@ export declare function createLocalGatewayClient(dbPath: string): {
         status: string;
     }[]>;
     searchDecisions(query: string, limit?: number): Promise<SearchResults>;
-    checkAlignment(diff: string, _context?: string): Promise<AlignmentResult>;
+    checkAlignment(diff: string, _context?: string, opts?: {
+        depth?: "related" | "full";
+        title?: string;
+    }): Promise<AlignmentResult>;
     checkDrift(decisionId: string, content: string, _sourceType?: string): Promise<{
         decisionId: string;
         score: null;

package/dist/lib/local-gateway-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-gateway-client.d.ts","sourceRoot":"","sources":["../../src/lib/local-gateway-client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE1E;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAGrC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAGtC,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM;IA2DnD,2FAA2F;;;;;;;2BAS9D,MAAM;;;;;;;;uBAKV,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;;;;;;;;;;;;;;;2BA6BhF;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;2BAgBjB,MAAM,mBAAe,OAAO,CAAC,aAAa,CAAC;yBAgC7C,MAAM,aAAa,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;2BA8FlD,MAAM,WAAW,MAAM,gBAAgB,MAAM;;;;;;;;;;;0BAQ9C,MAAM;;;;;;;;EAmBrC;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"local-gateway-client.d.ts","sourceRoot":"","sources":["../../src/lib/local-gateway-client.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE1E;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAG/C,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM;IA2DnD,2FAA2F;;;;;;;2BAS9D,MAAM;;;;;;;;uBAKV,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;;;;;;;;;;;;;;;2BA6BhF;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;2BAgBjB,MAAM,mBAAe,OAAO,CAAC,aAAa,CAAC;yBAiChE,MAAM,aACD,MAAM,SACX;QAAE,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACnD,OAAO,CAAC,eAAe,CAAC;2BAuJE,MAAM,WAAW,MAAM,gBAAgB,MAAM;;;;;;;;;;;0BAQ9C,MAAM;;;;;;;;EAmBrC;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/lib/local-gateway-client.js

@@ -1,6 +1,7 @@
 import { createLocalDb } from './local-db.js';
 import { cosineSimilarity, getEmbedding } from './local-embeddings.js';
 import { classifyRelationship } from './local-relationship-classifier.js';
+import { RECOMMENDED_OLLAMA_PULL } from './local-llm.js';
 import { citationFor, repositoryOf } from './decision-links.js';
 /**
  * Cosine floor for linking two decisions as related on ingest.
@@ -30,9 +31,39 @@ export const SIMILARITY_THRESHOLD = 0.65;
  * than two wrong decisions, because the caller can act on it.
  */
 export const SEARCH_THRESHOLD = 0.25;
-// Embeddings flag a decision as a related CANDIDATE at/above this score; the
-// relationship type is then assigned lazily by the LLM classifier.
+/**
+ * Candidate floor for ADJUDICATION - the path that then pays an LLM per candidate.
+ *
+ * Deliberately higher than the retrieval floor below, because this surface is expensive in
+ * three ways the hook is not: up to 5 sequential calls to the user's own provider, ~11s of
+ * latency, and an exit code. A keyless CI runner that gets `no-context` today exits 0; the
+ * moment retrieval finds anything it gets `unknown` and exits 2. And the classifier cannot
+ * reject a candidate - its vocabulary is ten positive relations with no "unrelated" - so a
+ * loose candidate that reaches it is reported rather than filtered.
+ *
+ * Deliberately NOT recalibrated with the retrieval floor. Measured on the corpus, 0.30 would
+ * recover four more related pairs here too, and that trade is a separate decision with a
+ * separate blast radius (see relatedness-calibration.test.ts).
+ */
 export const RELATES_THRESHOLD = 0.45;
+/**
+ * Candidate floor for RETRIEVAL ONLY (`depth: 'related'`, the agent editor hook).
+ *
+ * Measured, not chosen. Against fixtures/relatedness-corpus.json: 0.45 recovered 3 of 8 related
+ * pairs, 0.30 recovers 7 of 8, and neither admits a single unrelated pair. 0.25 scores the same
+ * 7 of 8, so the tie-break is margin over the worst false positive (0.2051): 0.30 clears it by
+ * 0.095 against 0.25's 0.045.
+ *
+ * 0.30 is also where this constant sat until commit 0cbef08 raised it to 0.45 inside a rename,
+ * unmentioned and unmeasured. So this is a revert with evidence attached rather than a new
+ * guess, and the evidence is a test that fails if the corpus stops supporting it.
+ *
+ * Safe to be looser here precisely because this path is cheap and honest: it returns above
+ * Stage 2, so it makes no provider call, and what the hook prints declines to assert anything
+ * ("related by content search and have NOT been adjudicated"). That is the same posture as
+ * `align search`, which has run at 0.25 all along - as has MCP `align_get_related_decisions`.
+ */
+export const RETRIEVAL_RELATES_THRESHOLD = 0.3;
 // Below this similarity between a decision and new content, the content is
 // considered to have drifted from the decision.
 export const DRIFT_THRESHOLD = 0.5;
@@ -169,10 +200,16 @@ export function createLocalGatewayClient(dbPath) {
                 .filter((d) => d !== null);
             return { results, count: results.length, strategy: 'semantic' };
         },
-        async checkAlignment(diff, _context) {
+        async checkAlignment(diff, _context, opts = {}) {
             // Stage 1: embeddings find candidate related decisions (free, local).
+            //
+            // The floor depends on what the caller will DO with the candidates. Retrieval-only stops
+            // above Stage 2, so a looser match costs one extra title in prose that asserts nothing;
+            // adjudication pays a provider call per candidate and can move an exit code, so it keeps
+            // the stricter bar. One constant could not serve both.
+            const threshold = opts.depth === 'related' ? RETRIEVAL_RELATES_THRESHOLD : RELATES_THRESHOLD;
             const embedding = await getEmbedding(diff);
-            const similar = await findSimilar(embedding, 5, RELATES_THRESHOLD);
+            const similar = await findSimilar(embedding, 5, threshold);
             const candidates = similar
                 .map(s => {
                 const row = db.getDecisionById(s.decisionId);
@@ -182,12 +219,53 @@ export function createLocalGatewayClient(dbPath) {
             if (!candidates.length) {
                 return { status: 'no-context', confidence: 0, relevant_decisions: [], conflicts: [], message: 'No related decisions found in your local graph.' };
             }
+            // `depth:'related'` means retrieval only, and honouring it matters more here than in the
+            // cloud client. The editor hook asks for it to fit a <=10s budget (check.ts), but in
+            // local mode Stage 2 is also the only EGRESS in the pipeline: it posts the proposed
+            // content plus a stored decision to the user's own LLM provider, once per candidate, on
+            // every agent Write/Edit. This signature took two arguments, so the option was silently
+            // dropped and adjudication ran anyway - up to 5 provider calls per keystroke-level event,
+            // whose results the hook then abandoned at its 2.5s race.
+            //
+            // Matched as an allowlist-of-one rather than `!== 'full'`, which would be the safer
+            // polarity for an egress guard, because the two callers that MUST adjudicate
+            // (`align check` and `--ci`, check.ts) pass no depth at all. Inverting it would silence
+            // them. The cost of this direction: a future caller misspelling the value adjudicates,
+            // so keep `depth` typed as the union at every call site rather than widening it.
+            if (opts.depth === 'related') {
+                return {
+                    status: 'retrieved',
+                    confidence: Math.max(...candidates.map(c => c.score)),
+                    relevant_decisions: candidates.map(c => ({
+                        id: c.id,
+                        title: c.title,
+                        summary: c.summary,
+                        similarity: c.score,
+                        url: c.sourceUrl ?? undefined,
+                    })),
+                    conflicts: [],
+                    message: `Found ${candidates.length} related decision(s) - retrieval only, not adjudicated.`,
+                };
+            }
             // Stage 2: type each candidate against the proposed change (LLM, user's key,
             // lazy - only the few candidates we surface here). Degrades to untyped.
-            const subject = { title: 'Proposed change', summary: diff.slice(0, 2000) };
+            // The caller's title when it gave one: `align check --title` exists because adjudicating
+            // on a bare diff means judging a file header and a few `+` lines. Accepting the option in
+            // the signature and then classifying against a placeholder is the dropped-`depth` defect
+            // one field over.
+            const subject = { title: opts.title ?? 'Proposed change', summary: diff.slice(0, 2000) };
             const typed = [];
+            let chainStopped = false;
             for (const c of candidates) {
-                const outcome = await classifyRelationship(subject, { title: c.title, summary: c.summary });
+                // ALI-692: a recorded chain stop is a property of the PROVIDER, not of this
+                // candidate, so asking again per candidate repeats one doomed call N times -
+                // on a 429 that burns the retry budget while `--advisory` races its deadline.
+                // The remaining candidates still report, untyped, which is what `unknown` means.
+                const outcome = chainStopped
+                    ? { ok: false, reason: 'classifier_error' }
+                    : await classifyRelationship(subject, { title: c.title, summary: c.summary });
+                if (!outcome.ok && outcome.failure?.kind === 'provider_stopped')
+                    chainStopped = true;
                 const rel = outcome.ok ? outcome.relationship : null;
                 typed.push({
                     id: c.id,
@@ -198,6 +276,10 @@ export function createLocalGatewayClient(dbPath) {
                     confidence: rel?.confidence ?? c.score,
                     typed: rel !== null,
                     failureReason: outcome.ok ? undefined : outcome.reason,
+                    // The diagnosis travels WITH the candidate it describes, so the hint below
+                    // names the model that failed on this one rather than whatever a module
+                    // getter happened to hold by the time the loop finished.
+                    failure: outcome.ok ? undefined : outcome.failure,
                     reason: rel?.reason,
                     similarity: c.score,
                 });
@@ -231,11 +313,17 @@ export function createLocalGatewayClient(dbPath) {
             if (unclassified) {
                 // ALI-420: an unvetted local model gets its own remedy. The no_llm_key hint below
                 // says "or run a local Ollama", which is nonsense to someone already running one.
+                // ALI-692: the third rung. A recorded chain stop names the model that failed,
+                // and this is the surface agents gate on - it used to fall through to an empty
+                // hint, discarding the diagnosis one frame above where it was recorded.
+                const failure = unclassified.failure;
                 const hint = unclassified.failureReason === 'unvetted_local_model'
-                    ? ' Ollama is running, but no vetted model is installed: `ollama pull llama3.2`, or set ALIGN_OLLAMA_MODEL to name your own.'
+                    ? ` Ollama is running, but no recognised model is installed: \`ollama pull ${RECOMMENDED_OLLAMA_PULL}\`, or set ALIGN_OLLAMA_MODEL to name your own.`
                     : unclassified.failureReason === 'no_llm_key'
                         ? ' Set ANTHROPIC_API_KEY or OPENAI_API_KEY (or run a local Ollama) so these can be classified.'
-                        : '';
+                        : failure?.kind === 'provider_stopped'
+                            ? ` ${failure.model} (${failure.provider}) returned an unusable response (${failure.detail}), and no weaker model was asked in its place.`
+                            : '';
                 return {
                     status: 'unknown',
                     reason: unclassified.failureReason,