@aligndottech/cli 0.49.0 → 0.50.0

package/dist/lib/share/visible.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible.d.ts","sourceRoot":"","sources":["../../../src/lib/share/visible.ts"],"names":[],"mappings":"AAoBA,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAOlF"}

package/dist/lib/share/visible.js

@@ -0,0 +1,30 @@
+/**
+ * L9: make every untrusted string safe to print on a terminal a person is about to answer.
+ *
+ * A decision's title, text, URL and notes come from sources other people write (a PR title, a Slack
+ * thread). Raw, they can carry ESC sequences that rewrite or clear the screen, a bare CR that overwrites
+ * the line above, or bidi overrides that reorder what is read, so the preview would show something other
+ * than what is sent. Each such character is replaced by a visible escape (`\x1b`, `‮`), never
+ * dropped: dropping would also hide that it was there.
+ *
+ * Covered, by Unicode category: controls (ESC, CR, tab, NUL, DEL, C1), every format character (bidi
+ * overrides and isolates, zero-width, soft hyphen, U+061C, the tag characters U+E0000-E007F), line and
+ * paragraph separators, default-ignorable code points (U+034F, U+180E, U+3164, U+FFF9-FFFB) and lone surrogates.
+ * `\n` is kept only when the caller asks (the indented body), because it cannot overwrite earlier text.
+ */
+// Unicode categories rather than hand-listed ranges (a hand-written list is guessing at published data):
+// Cc controls (ESC, CR, NUL, C1), Cf format (bidi marks and overrides, zero-width, soft hyphen, ALM, tag
+// characters U+E0000-E007F), Zl/Zp line and paragraph separators, Default_Ignorable_Code_Point (Hangul
+// fillers, U+034F, U+180E, interlinear annotation marks) and Cs, a lone surrogate (needs the u flag).
+const UNSAFE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}]|\p{Cs}/gu;
+export function visible(text, opts = {}) {
+    return text.replace(UNSAFE, (c) => {
+        if (c === '\n' && opts.keepNewline)
+            return c;
+        const code = c.codePointAt(0);
+        if (code <= 0xff)
+            return `\\x${code.toString(16).padStart(2, '0')}`;
+        return code <= 0xffff ? `\\u${code.toString(16).padStart(4, '0')}` : `\\u{${code.toString(16)}}`;
+    });
+}
+//# sourceMappingURL=visible.js.map

package/dist/lib/share/visible.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible.js","sourceRoot":"","sources":["../../../src/lib/share/visible.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,yGAAyG;AACzG,yGAAyG;AACzG,uGAAuG;AACvG,sGAAsG;AACtG,MAAM,MAAM,GAAG,qEAAqE,CAAC;AAErF,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,OAAkC,EAAE;IACxE,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;QAChC,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC;QAC/B,IAAI,IAAI,IAAI,IAAI;YAAE,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QACpE,OAAO,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC;IACnG,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/share/wire.d.ts

@@ -0,0 +1,98 @@
+/**
+ * L9: the shape POST /ingest/batch answers a SHARE with, read without trusting it.
+ *
+ * The response is not one snapshot per request item. It carries `snapshots` for what was WRITTEN
+ * (each with `request_index`, its position in the request), and the rest by index: `matched`
+ * (attached to a decision the team already held, nothing created), `skipped` (a re-share left alone),
+ * `refused` (the identity belongs to a decision the caller cannot see), `match_ambiguous` (several
+ * team decisions share the source key, so the item was created as new) and `judgements` (one report
+ * per target, one result per judgement). Reading `snapshots[0]` as "the decision I shared" is wrong
+ * whenever any of those is present. This module turns the response into exactly one outcome per
+ * request item, and an item the response never mentions is `unknown`, never "created".
+ */
+export interface JudgementResult {
+    ok: boolean;
+    stored?: boolean;
+    error?: string;
+}
+export interface BatchResponse {
+    snapshots?: Array<{
+        id: string;
+        title?: string;
+        summary?: string;
+        request_index?: number;
+        is_new?: boolean;
+    }>;
+    skipped?: Array<{
+        index: number;
+        reason: string;
+        existing_id: string;
+    }>;
+    matched?: Array<{
+        request_index: number;
+        existing_id: string;
+        status?: string;
+        team_text_hash?: string;
+        needs_confirmation?: Array<{
+            kind: string;
+            judgement_index: number;
+        }>;
+    }>;
+    match_ambiguous?: number[];
+    refused?: Array<{
+        request_index: number;
+        reason: string;
+    }>;
+    judgements?: Array<{
+        request_index: number;
+        decision_id: string;
+        results: JudgementResult[];
+    }>;
+}
+export interface JudgementFailure {
+    index: number;
+    error: string;
+}
+interface Common {
+    index: number;
+    /** One result per judgement sent, or null when the gateway reported none (an older gateway ignores the field). */
+    judgements: JudgementResult[] | null;
+}
+export type ItemOutcome = (Common & {
+    kind: 'created';
+    remoteId: string;
+    ambiguous: boolean;
+    uncertain: boolean;
+}) | (Common & {
+    kind: 'updated';
+    remoteId: string;
+}) | (Common & {
+    kind: 'matched';
+    remoteId: string;
+    status: string;
+    teamTextHash: string | null;
+    needsConfirmation: Array<{
+        kind: string;
+        judgement_index: number;
+    }>;
+}) | (Common & {
+    kind: 'skipped';
+    remoteId: string;
+    reason: string;
+}) | {
+    kind: 'refused';
+    index: number;
+    reason: string;
+} | {
+    kind: 'unknown';
+    index: number;
+};
+export declare function failedJudgements(results: JudgementResult[] | null): JudgementFailure[];
+/**
+ * One outcome per request item. `sent` is how many items the request carried. A response whose
+ * snapshots carry no `request_index` (a gateway before the field) is index-aligned ONLY when nothing
+ * was matched, skipped or refused and the counts agree; otherwise those items are `unknown`.
+ */
+export declare function readOutcomes(sent: number, res: BatchResponse): ItemOutcome[];
+export {};
+//# sourceMappingURL=wire.d.ts.map

package/dist/lib/share/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/lib/share/wire.ts"],"names":[],"mappings":"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"}

package/dist/lib/share/wire.js

@@ -0,0 +1,43 @@
+export function failedJudgements(results) {
+    return (results ?? []).flatMap((r, index) => (r.ok ? [] : [{ index, error: r.error ?? 'failed' }]));
+}
+/**
+ * One outcome per request item. `sent` is how many items the request carried. A response whose
+ * snapshots carry no `request_index` (a gateway before the field) is index-aligned ONLY when nothing
+ * was matched, skipped or refused and the counts agree; otherwise those items are `unknown`.
+ */
+export function readOutcomes(sent, res) {
+    const snapshots = res.snapshots ?? [];
+    const judged = new Map((res.judgements ?? []).map((j) => [j.request_index, j.results]));
+    const reportFor = (index) => judged.get(index) ?? null;
+    const ambiguous = new Set(res.match_ambiguous ?? []);
+    const out = new Map();
+    for (const r of res.refused ?? [])
+        out.set(r.request_index, { kind: 'refused', index: r.request_index, reason: r.reason });
+    for (const m of res.matched ?? []) {
+        out.set(m.request_index, {
+            kind: 'matched', index: m.request_index, remoteId: m.existing_id, status: m.status ?? 'unknown',
+            teamTextHash: m.team_text_hash ?? null, needsConfirmation: m.needs_confirmation ?? [], judgements: reportFor(m.request_index),
+        });
+    }
+    for (const s of res.skipped ?? []) {
+        out.set(s.index, { kind: 'skipped', index: s.index, remoteId: s.existing_id, reason: s.reason, judgements: reportFor(s.index) });
+    }
+    const untagged = snapshots.some((s) => s.request_index === undefined);
+    const aligned = untagged && snapshots.length === sent && out.size === 0;
+    snapshots.forEach((s, k) => {
+        const index = s.request_index ?? (aligned ? k : undefined);
+        if (index === undefined || out.has(index))
+            return;
+        // `created` is only believed when the gateway said so in so many words: a request_index AND is_new === true.
+        // A gateway before share matching (self-host older than 0.46.0) sends neither, so a row it REUSED at that
+        // source looks identical to a new one. Retracting it would archive somebody else's decision, so it is
+        // `uncertain` and recorded as not ours.
+        const sure = s.request_index !== undefined && s.is_new === true;
+        out.set(index, s.is_new === false
+            ? { kind: 'updated', index, remoteId: s.id, judgements: reportFor(index) }
+            : { kind: 'created', index, remoteId: s.id, ambiguous: ambiguous.has(index), uncertain: !sure, judgements: reportFor(index) });
+    });
+    return Array.from({ length: sent }, (_, index) => out.get(index) ?? { kind: 'unknown', index });
+}
+//# sourceMappingURL=wire.js.map

package/dist/lib/share/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../../../src/lib/share/wire.ts"],"names":[],"mappings":"AA0CA,MAAM,UAAU,gBAAgB,CAAC,OAAiC;IAChE,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;AACtG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,GAAkB;IAC3D,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,OAAO,CAAU,CAAC,CAAC,CAAC;IACjG,MAAM,SAAS,GAAG,CAAC,KAAa,EAA4B,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IACzF,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE3C,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE;QAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3H,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QAClC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,aAAa,EAAE;YACvB,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,aAAa,EAAE,QAAQ,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,SAAS;YAC/F,YAAY,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC,kBAAkB,IAAI,EAAE,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC;SAC9H,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QAClC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnI,CAAC;IACD,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,QAAQ,IAAI,SAAS,CAAC,MAAM,KAAK,IAAI,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC;IACxE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACzB,MAAM,KAAK,GAAG,CAAC,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC3D,IAAI,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO;QAClD,6GAA6G;QAC7G,0GAA0G;QAC1G,sGAAsG;QACtG,wCAAwC;QACxC,MAAM,IAAI,GAAG,CAAC,CAAC,aAAa,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC;QAChE,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,KAAK,KAAK;YAC/B,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,UAAU,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE;YAC1E,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnI,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,SAAkB,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3G,CAAC"}

package/dist/lib/similarity/embedding-matrix.d.ts

@@ -0,0 +1,64 @@
+/**
+ * An in-memory copy of every stored embedding, held as ONE contiguous Float32Array, with an
+ * exhaustive top-K scan over it (plan LB, decision 26).
+ *
+ * Why it exists: ingest ranked each new item against the whole graph by re-reading every
+ * stored vector out of SQLite, decoding it, and cosine-scoring it, once per item. Measured
+ * (profile at 5,000 rows): read and decode 5.7 ms, cosine 1.9 ms, sort 0.4 ms per item, and
+ * the read grows with the graph, so a batch was quadratic. Loading once per run and appending
+ * as items land removes the read; scoring against precomputed norms removes two thirds of the
+ * arithmetic. The scan stays EXHAUSTIVE - narrowing candidates would drop the cross-tool links
+ * the product exists for - so results must equal the old scan exactly. They do: the dot
+ * product accumulates in the same order as cosineSimilarity and divides by the same
+ * sqrt(normQuery) * sqrt(normRow), so every score is bit-identical, not merely close.
+ *
+ * Pure: no database, no model. The caller decides which rows go in.
+ */
+export interface Scored {
+    decisionId: string;
+    score: number;
+}
+/** Anything that can rank the graph against a query: the matrix, or the streaming scan that
+ *  stands in for it on a graph too large to hold in memory. */
+export interface Ranker {
+    topK(query: Float32Array, k: number, opts?: {
+        excludeId?: string;
+        threshold?: number;
+    }): Scored[] | Promise<Scored[]>;
+}
+/**
+ * Above this many stored embeddings ingest does not build a matrix and ranks by streaming the
+ * table per item, as it did before the matrix existed. Memory: a 384-dim row is 1,536 bytes of
+ * Float32 plus its id and norm, so about 1.5 KB per row, i.e. roughly 230 MB at 150,000 rows.
+ * Building reads every row out of SQLite first, so the transient peak is about 2.5x the
+ * matrix (the decoded rows, the contiguous copy, and growth headroom) until the rows are
+ * released. The cap keeps that peak near 600 MB. Measured graphs are in the thousands of rows;
+ * this is a guard for the pathological case, not a tuning knob.
+ */
+export declare const MATRIX_MAX_ROWS = 150000;
+/** The one writer of the "different model" error, shared with cosineSimilarity. */
+export declare function embeddingLengthMismatch(a: number, b: number): Error;
+export declare class EmbeddingMatrix implements Ranker {
+    private dim;
+    private data;
+    private sqrtNorms;
+    private ids;
+    private index;
+    static fromRows(rows: Array<{
+        decisionId: string;
+        embedding: Float32Array;
+    }>): EmbeddingMatrix;
+    get size(): number;
+    /** Adds a row, or replaces the vector of an id already held (setEmbedding is INSERT OR
+     *  REPLACE, so the matrix must never hold two vectors for one decision). */
+    add(decisionId: string, embedding: Float32Array): void;
+    /** The `k` best rows by cosine, best first; equal scores order by id in code-unit order.
+     *  Rows scoring below `threshold` are dropped (default: none are; findSimilar passed 0). */
+    topK(query: Float32Array, k: number, opts?: {
+        excludeId?: string;
+        threshold?: number;
+    }): Scored[];
+    private outranks;
+    private grow;
+}
+//# sourceMappingURL=embedding-matrix.d.ts.map

package/dist/lib/similarity/embedding-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-matrix.d.ts","sourceRoot":"","sources":["../../../src/lib/similarity/embedding-matrix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,MAAM;IAAG,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAE7D;+DAC+D;AAC/D,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACvH;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,SAAU,CAAC;AAEvC,mFAAmF;AACnF,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,CAKnE;AAID,qBAAa,eAAgB,YAAW,MAAM;IAC5C,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,GAAG,CAAgB;IAC3B,OAAO,CAAC,KAAK,CAA6B;IAE1C,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,YAAY,CAAA;KAAE,CAAC,GAAG,eAAe;IAM9F,IAAI,IAAI,IAAI,MAAM,CAA4B;IAE9C;gFAC4E;IAC5E,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,GAAG,IAAI;IAgBtD;gGAC4F;IAC5F,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM,EAAE;IAgCrG,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,IAAI;CAQb"}

package/dist/lib/similarity/embedding-matrix.js

@@ -0,0 +1,119 @@
+/**
+ * An in-memory copy of every stored embedding, held as ONE contiguous Float32Array, with an
+ * exhaustive top-K scan over it (plan LB, decision 26).
+ *
+ * Why it exists: ingest ranked each new item against the whole graph by re-reading every
+ * stored vector out of SQLite, decoding it, and cosine-scoring it, once per item. Measured
+ * (profile at 5,000 rows): read and decode 5.7 ms, cosine 1.9 ms, sort 0.4 ms per item, and
+ * the read grows with the graph, so a batch was quadratic. Loading once per run and appending
+ * as items land removes the read; scoring against precomputed norms removes two thirds of the
+ * arithmetic. The scan stays EXHAUSTIVE - narrowing candidates would drop the cross-tool links
+ * the product exists for - so results must equal the old scan exactly. They do: the dot
+ * product accumulates in the same order as cosineSimilarity and divides by the same
+ * sqrt(normQuery) * sqrt(normRow), so every score is bit-identical, not merely close.
+ *
+ * Pure: no database, no model. The caller decides which rows go in.
+ */
+/**
+ * Above this many stored embeddings ingest does not build a matrix and ranks by streaming the
+ * table per item, as it did before the matrix existed. Memory: a 384-dim row is 1,536 bytes of
+ * Float32 plus its id and norm, so about 1.5 KB per row, i.e. roughly 230 MB at 150,000 rows.
+ * Building reads every row out of SQLite first, so the transient peak is about 2.5x the
+ * matrix (the decoded rows, the contiguous copy, and growth headroom) until the rows are
+ * released. The cap keeps that peak near 600 MB. Measured graphs are in the thousands of rows;
+ * this is a guard for the pathological case, not a tuning knob.
+ */
+export const MATRIX_MAX_ROWS = 150_000;
+/** The one writer of the "different model" error, shared with cosineSimilarity. */
+export function embeddingLengthMismatch(a, b) {
+    return new Error(`Embedding length mismatch: ${a} vs ${b}. The local graph holds a vector ` +
+        'from a different model - run `align local reset` and re-import to rebuild it.');
+}
+const INITIAL_ROWS = 256;
+export class EmbeddingMatrix {
+    dim = -1;
+    data = new Float32Array(0);
+    sqrtNorms = new Float64Array(0);
+    ids = [];
+    index = new Map();
+    static fromRows(rows) {
+        const m = new EmbeddingMatrix();
+        for (const r of rows)
+            m.add(r.decisionId, r.embedding);
+        return m;
+    }
+    get size() { return this.ids.length; }
+    /** Adds a row, or replaces the vector of an id already held (setEmbedding is INSERT OR
+     *  REPLACE, so the matrix must never hold two vectors for one decision). */
+    add(decisionId, embedding) {
+        if (this.dim === -1)
+            this.dim = embedding.length;
+        else if (embedding.length !== this.dim)
+            throw embeddingLengthMismatch(embedding.length, this.dim);
+        let row = this.index.get(decisionId);
+        if (row === undefined) {
+            row = this.ids.length;
+            if ((row + 1) * this.dim > this.data.length)
+                this.grow(Math.max(INITIAL_ROWS, row * 2));
+            this.ids.push(decisionId);
+            this.index.set(decisionId, row);
+        }
+        this.data.set(embedding, row * this.dim);
+        let norm = 0;
+        for (let i = 0; i < this.dim; i++)
+            norm += embedding[i] * embedding[i];
+        this.sqrtNorms[row] = Math.sqrt(norm);
+    }
+    /** The `k` best rows by cosine, best first; equal scores order by id in code-unit order.
+     *  Rows scoring below `threshold` are dropped (default: none are; findSimilar passed 0). */
+    topK(query, k, opts = {}) {
+        const n = this.ids.length;
+        if (n === 0 || k <= 0)
+            return [];
+        if (query.length !== this.dim)
+            throw embeddingLengthMismatch(query.length, this.dim);
+        const threshold = opts.threshold ?? -Infinity;
+        const skip = opts.excludeId === undefined ? -1 : (this.index.get(opts.excludeId) ?? -1);
+        let normQ = 0;
+        for (let i = 0; i < this.dim; i++)
+            normQ += query[i] * query[i];
+        const sqrtQ = Math.sqrt(normQ);
+        const best = [];
+        const dim = this.dim, data = this.data;
+        for (let r = 0; r < n; r++) {
+            if (r === skip)
+                continue;
+            const base = r * dim;
+            let dot = 0;
+            for (let i = 0; i < dim; i++)
+                dot += query[i] * data[base + i];
+            const denom = sqrtQ * this.sqrtNorms[r];
+            const score = denom === 0 ? 0 : dot / denom;
+            if (!(score >= threshold))
+                continue;
+            if (best.length === k && !this.outranks(score, this.ids[r], best[k - 1]))
+                continue;
+            // Insertion into a list of at most k: k is 10 in ingest, so this beats any heap.
+            let pos = best.length === k ? k - 1 : best.length;
+            while (pos > 0 && this.outranks(score, this.ids[r], best[pos - 1])) {
+                if (pos < k)
+                    best[pos] = best[pos - 1];
+                pos--;
+            }
+            best[pos] = { decisionId: this.ids[r], score };
+        }
+        return best;
+    }
+    outranks(score, id, other) {
+        return score > other.score || (score === other.score && id < other.decisionId);
+    }
+    grow(rows) {
+        const data = new Float32Array(rows * this.dim);
+        data.set(this.data);
+        this.data = data;
+        const norms = new Float64Array(rows);
+        norms.set(this.sqrtNorms);
+        this.sqrtNorms = norms;
+    }
+}
+//# sourceMappingURL=embedding-matrix.js.map

package/dist/lib/similarity/embedding-matrix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-matrix.js","sourceRoot":"","sources":["../../../src/lib/similarity/embedding-matrix.ts"],"names":[],"mappings":"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"}

package/dist/lib/since-flag.d.ts

@@ -0,0 +1,11 @@
+import { type SyncWindow } from './since.js';
+/** The help line for `--since`, one writer for every command that takes it. */
+export declare const SINCE_HELP = "How far back to read: 30d, 2w, 6m, 1y or all (default 180 days). A ceiling still applies";
+/**
+ * L3: the CLI end of the one duration parser. A bad value exits 2 (usage error) naming the
+ * accepted forms, before any request is made: a window the user did not mean would be read
+ * and reported as complete. `align_backfill` calls parseSince directly and returns the same
+ * message as a tool error.
+ */
+export declare function sinceFromFlag(raw: string | undefined, now?: Date): SyncWindow;
+//# sourceMappingURL=since-flag.d.ts.map

package/dist/lib/since-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"since-flag.d.ts","sourceRoot":"","sources":["../../src/lib/since-flag.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAErE,+EAA+E;AAC/E,eAAO,MAAM,UAAU,6FAA6F,CAAC;AAErH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,IAAiB,GAAG,UAAU,CASzF"}

package/dist/lib/since-flag.js

@@ -0,0 +1,24 @@
+import chalk from 'chalk';
+import { trackChildFromEnv } from './backfill-state.js';
+import { parseSince, SinceError } from './since.js';
+/** The help line for `--since`, one writer for every command that takes it. */
+export const SINCE_HELP = 'How far back to read: 30d, 2w, 6m, 1y or all (default 180 days). A ceiling still applies';
+/**
+ * L3: the CLI end of the one duration parser. A bad value exits 2 (usage error) naming the
+ * accepted forms, before any request is made: a window the user did not mean would be read
+ * and reported as complete. `align_backfill` calls parseSince directly and returns the same
+ * message as a tool error.
+ */
+export function sinceFromFlag(raw, now = new Date()) {
+    try {
+        return parseSince(raw, now);
+    }
+    catch (e) {
+        if (!(e instanceof SinceError))
+            throw e;
+        trackChildFromEnv()?.note(e.message); // a backfill child records why it ended
+        console.error(chalk.red(`align connect: ${e.message}`));
+        return process.exit(2);
+    }
+}
+//# sourceMappingURL=since-flag.js.map

package/dist/lib/since-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"since-flag.js","sourceRoot":"","sources":["../../src/lib/since-flag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AAErE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAG,0FAA0F,CAAC;AAErH;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAuB,EAAE,MAAY,IAAI,IAAI,EAAE;IAC3E,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,CAAC,CAAC,YAAY,UAAU,CAAC;YAAE,MAAM,CAAC,CAAC;QACxC,iBAAiB,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,wCAAwC;QAC9E,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACxD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;AACH,CAAC"}

package/dist/lib/since.d.ts

@@ -0,0 +1,59 @@
+/**
+ * L3: the ONE parser for how far back an import reads. `align connect --since` and the MCP
+ * tool `align_backfill` both call it, so the two surfaces cannot accept different spellings
+ * of the same window (code-style.md: two readers of one format must agree).
+ *
+ * Accepted: `Nd`, `Nw`, `Nm` (a month is 30.4 days, rounded), `Ny`, and `all`. Anything else
+ * is a SinceError: a window the user did not mean is worse than a refusal, because the
+ * report would still say the read was complete.
+ */
+import { type SourceId } from './import-defaults.js';
+import type { ScopeFetchOpts } from './scope-values.js';
+export declare const ACCEPTED_SINCE_FORMS = "30d, 2w, 6m, 1y or all";
+export declare class SinceError extends Error {
+    constructor(raw: string, why: string);
+}
+export interface SyncWindow {
+    /** Days back from now. Absent for `all`. */
+    days?: number;
+    /** ISO-8601 UTC lower bound for the SDK's `since`. Absent for `all`: only the ceiling applies. */
+    since?: string;
+}
+/** `undefined` means the flag was not passed: the plan default applies. */
+export declare function parseSince(raw: string | undefined, now?: Date): SyncWindow;
+/**
+ * The phrase the capture report prints. Exact: "the last 6 months" only for a window that IS
+ * what `6m` parses to (182 days). The default is 180 days and reads "the last 180 days", so two
+ * different reads never share a label. A month or year label needs the day count to be exactly
+ * what that many months or years parse to; anything else is said in days.
+ */
+export declare function windowLabel(days: number | undefined): string;
+/**
+ * The options every windowed fetch gets: this source's ceiling, the shared time budget and the
+ * window's lower bound. `since` is OMITTED for `all`, never set to undefined, so the SDK sees no
+ * bound at all. The one reader of SYNC_CEILINGS for a fetch (import-defaults.test.ts pins it).
+ */
+export declare function fetchWindow(id: SourceId, window: SyncWindow): {
+    limit: number;
+    timeBudgetMs: number;
+    since?: string;
+};
+/**
+ * What a source's fetch is handed beyond the window: L5's `until` and Slack `hotThreads`, and L4's team-scope option (Jira `projects`,
+ * Linear `teams`, GitLab `projectId`, Confluence `spaces`). `team` and `repo` are GitHub's, read by its closure in setup.ts.
+ */
+export interface FetchExtras extends ScopeFetchOpts {
+    until?: string;
+    hotThreads?: Array<{
+        channel: string;
+        ts: string;
+    }>;
+    team?: boolean;
+    /** GitHub team scope: the repo. */
+    repo?: string;
+    /** True when the caller has already decided the scope (repo or none): the fetch must not look at the folder itself. */
+    resolved?: boolean;
+}
+/** The optional extras a fetch adds to the window itself. Omitted keys stay omitted. */
+export declare function windowExtras(o?: FetchExtras): FetchExtras;
+//# sourceMappingURL=since.d.ts.map

package/dist/lib/since.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"since.d.ts","sourceRoot":"","sources":["../../src/lib/since.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,QAAQ,EAAgE,MAAM,sBAAsB,CAAC;AACnH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAS7D,qBAAa,UAAW,SAAQ,KAAK;gBACvB,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAKrC;AAED,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kGAAkG;IAClG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,IAAiB,GAAG,UAAU,CAUtF;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQ5D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAMrH;AAED;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uHAAuH;IACvH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,CAAC,CAAC,EAAE,WAAW,GAAG,WAAW,CASzD"}

package/dist/lib/since.js

@@ -0,0 +1,86 @@
+/**
+ * L3: the ONE parser for how far back an import reads. `align connect --since` and the MCP
+ * tool `align_backfill` both call it, so the two surfaces cannot accept different spellings
+ * of the same window (code-style.md: two readers of one format must agree).
+ *
+ * Accepted: `Nd`, `Nw`, `Nm` (a month is 30.4 days, rounded), `Ny`, and `all`. Anything else
+ * is a SinceError: a window the user did not mean is worse than a refusal, because the
+ * report would still say the read was complete.
+ */
+import { SYNC_CEILINGS, SYNC_TIME_BUDGET_MS, SYNC_WINDOW_DEFAULT_DAYS } from './import-defaults.js';
+export const ACCEPTED_SINCE_FORMS = '30d, 2w, 6m, 1y or all';
+const DAY_MS = 86_400_000;
+const MONTH_DAYS = 30.4;
+const DAYS_PER_UNIT = { d: 1, w: 7, m: MONTH_DAYS, y: 365 };
+// The SDK refuses a window that starts before 1970 (a `shape` skip, nothing read). Refusing
+// it here turns that into a message naming the accepted forms instead of a skip line.
+const EPOCH_MS = Date.UTC(1970, 0, 1);
+export class SinceError extends Error {
+    constructor(raw, why) {
+        // Cut: a pasted secret in the wrong field must not ride along into an error transcript.
+        super(`Cannot read "${raw.slice(0, 16)}" as how far back to look: ${why}. Use ${ACCEPTED_SINCE_FORMS}.`);
+        this.name = 'SinceError';
+    }
+}
+/** `undefined` means the flag was not passed: the plan default applies. */
+export function parseSince(raw, now = new Date()) {
+    if (raw === undefined)
+        return windowOfDays(SYNC_WINDOW_DEFAULT_DAYS, now);
+    const text = raw.trim().toLowerCase();
+    if (text === 'all')
+        return {};
+    const m = /^(\d+)([dwmy])$/.exec(text);
+    if (!m)
+        throw new SinceError(raw, 'it is not a whole number followed by d, w, m or y');
+    const days = Math.round(Number(m[1]) * DAYS_PER_UNIT[m[2]]);
+    if (days < 1)
+        throw new SinceError(raw, 'it is not a positive length of time');
+    if (now.getTime() - days * DAY_MS < EPOCH_MS)
+        throw new SinceError(raw, 'it reaches back before 1970');
+    return windowOfDays(days, now);
+}
+function windowOfDays(days, now) {
+    return { days, since: new Date(now.getTime() - days * DAY_MS).toISOString() };
+}
+/**
+ * The phrase the capture report prints. Exact: "the last 6 months" only for a window that IS
+ * what `6m` parses to (182 days). The default is 180 days and reads "the last 180 days", so two
+ * different reads never share a label. A month or year label needs the day count to be exactly
+ * what that many months or years parse to; anything else is said in days.
+ */
+export function windowLabel(days) {
+    if (days === undefined)
+        return 'all the history the ceiling allowed';
+    const plural = (n, unit) => `${n} ${unit}${n === 1 ? '' : 's'}`;
+    // Years first: 3y is 1095 days, which 36 months (1094) does not round-trip to.
+    if (days % 365 === 0)
+        return `the last ${plural(days / 365, 'year')}`;
+    const months = Math.round(days / MONTH_DAYS);
+    if (months >= 2 && Math.round(months * MONTH_DAYS) === days)
+        return `the last ${plural(months, 'month')}`;
+    return `the last ${plural(days, 'day')}`;
+}
+/**
+ * The options every windowed fetch gets: this source's ceiling, the shared time budget and the
+ * window's lower bound. `since` is OMITTED for `all`, never set to undefined, so the SDK sees no
+ * bound at all. The one reader of SYNC_CEILINGS for a fetch (import-defaults.test.ts pins it).
+ */
+export function fetchWindow(id, window) {
+    return {
+        limit: SYNC_CEILINGS[id],
+        timeBudgetMs: SYNC_TIME_BUDGET_MS,
+        ...(window.since !== undefined ? { since: window.since } : {}),
+    };
+}
+/** The optional extras a fetch adds to the window itself. Omitted keys stay omitted. */
+export function windowExtras(o) {
+    return {
+        ...(o?.until !== undefined ? { until: o.until } : {}),
+        ...(o?.hotThreads !== undefined && o.hotThreads.length > 0 ? { hotThreads: o.hotThreads } : {}),
+        ...(o?.projects !== undefined ? { projects: o.projects } : {}),
+        ...(o?.teams !== undefined ? { teams: o.teams } : {}),
+        ...(o?.projectId !== undefined ? { projectId: o.projectId } : {}),
+        ...(o?.spaces !== undefined ? { spaces: o.spaces } : {}),
+    };
+}
+//# sourceMappingURL=since.js.map

package/dist/lib/since.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"since.js","sourceRoot":"","sources":["../../src/lib/since.ts"],"names":[],"mappings":"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"}

package/dist/lib/source-key.d.ts

@@ -0,0 +1,13 @@
+export { normaliseSourceKey } from '@aligndottech/connector-core';
+/** Every platform a connector import can key. */
+export declare const KEYED_PLATFORMS: readonly string[];
+/**
+ * The key stored in `decisions.source_key`, or undefined (the row keeps its
+ * (source_url, title) identity). The platform is part of the stored string, so a `git` import
+ * and a `github` row for the same commit URL are different items and never merge.
+ *
+ * Only a connector import is ever given one (callers decide that; see insertDecision's
+ * `keyed`). The platform alone cannot say: `align capture <PR url>` also stamps `github`.
+ */
+export declare function connectorItemKey(platform: string, url: string | null | undefined): string | undefined;
+//# sourceMappingURL=source-key.d.ts.map

package/dist/lib/source-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-key.d.ts","sourceRoot":"","sources":["../../src/lib/source-key.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAkBlE,iDAAiD;AACjD,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAA6B,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAUrG"}