@isaacriehm/cairn-state 0.22.5

package/dist/scope-index.js

@@ -0,0 +1,299 @@
+/**
+ * Scope index — forward map from every file path in the repo to the decisions
+ * and invariants that apply to that file.
+ *
+ * Built at init by the Tier-2 mapper LLM, maintained by the GC sweep + the
+ * MCP record-decision tool when scope edits land. Read by the read-enricher
+ * / write-guardian hooks (via cached accessor in
+ * `hooks/post-tool-use/ledger-cache.ts`) and by the GC scope-coverage pass.
+ *
+ * Spec: docs/FILESYSTEM_LAYOUT.md §2.1.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { cairnDir, isGhost } from "./home.js";
+import { writeFileSafe } from "./fs.js";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { getLogger } from "./logger.js";
+const DEC_ID_RE = /\bDEC-[0-9a-f]{7,}\b/;
+const INV_ID_RE = /\bINV-[0-9a-f]{7,}\b/;
+/**
+ * Mapper LLMs occasionally emit ledger-entry PROSE ("HTTP layer is the only
+ * public surface…") into `decisions[]` / `invariants[]` instead of bare IDs,
+ * because the user prompt lists them as `${id} — ${title}` and the JSON-mode
+ * schema only constrains the type to `string`. This coercer extracts the
+ * first ID-shaped token from each string and silently drops anything that
+ * doesn't match — IDs only, deduplicated, order preserved.
+ */
+export function coerceDecisionIds(raw) {
+    return coerceIds(raw, DEC_ID_RE);
+}
+export function coerceInvariantIds(raw) {
+    return coerceIds(raw, INV_ID_RE);
+}
+function coerceIds(raw, re) {
+    const out = [];
+    const seen = new Set();
+    for (const s of raw) {
+        if (typeof s !== "string")
+            continue;
+        const m = s.match(re);
+        if (m === null)
+            continue;
+        if (seen.has(m[0]))
+            continue;
+        seen.add(m[0]);
+        out.push(m[0]);
+    }
+    return out;
+}
+export function scopeIndexPath(repoRoot) {
+    return cairnDir(repoRoot, "ground", "scope-index.yaml");
+}
+export function readScopeIndex(repoRoot) {
+    const path = scopeIndexPath(repoRoot);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = parseYaml(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const generated = typeof parsed["generated"] === "string"
+        ? parsed["generated"]
+        : new Date().toISOString();
+    const filesRaw = parsed["files"];
+    const files = {};
+    if (typeof filesRaw === "object" && filesRaw !== null) {
+        for (const [k, v] of Object.entries(filesRaw)) {
+            if (typeof v !== "object" || v === null)
+                continue;
+            const e = v;
+            const decisions = Array.isArray(e["decisions"])
+                ? e["decisions"].filter((x) => typeof x === "string")
+                : [];
+            const invariants = Array.isArray(e["invariants"])
+                ? e["invariants"].filter((x) => typeof x === "string")
+                : [];
+            const entry = { decisions, invariants };
+            if (e["unscoped"] === true)
+                entry.unscoped = true;
+            files[k] = entry;
+        }
+    }
+    return { generated, files };
+}
+export function lookupScope(index, repoRelativePath) {
+    const entry = index.files[repoRelativePath];
+    if (entry === undefined)
+        return null;
+    return entry;
+}
+export function writeScopeIndex(repoRoot, index) {
+    const path = scopeIndexPath(repoRoot);
+    writeFileSafe(path, stringifyYaml(index));
+}
+const log = getLogger();
+/* -------------------------------------------------------------------------- */
+/* Deterministic citation rescan                                              */
+/* -------------------------------------------------------------------------- */
+const CITATION_RE = /§(?:INV|DEC)-\d{4,}/g;
+const RESCAN_SOURCE_EXT_RE = /\.(?:ts|tsx|cts|mts|js|jsx|cjs|mjs|py|rb|go|rs|java|kt|swift|c|cc|cpp|h|hpp|cs|php|sql|sh|bash)$/i;
+const RESCAN_SKIP_DIR_RE = /(?:^|\/)(?:node_modules|dist|build|out|\.next|\.turbo|\.cache|coverage|\.cairn|\.archive|\.git)(?:\/|$)/;
+/**
+ * Deterministic regex sweep — walk every git-tracked source file, parse
+ * `§INV-<hash>` / `§DEC-<hash>` cite tokens, and sync the scope-index so the
+ * in-scope tools never lag behind source-cite reality. No LLM, no
+ * incremental tracking complexity. Cheap enough to run on every
+ * SessionStart (~100ms on 50k files).
+ *
+ * Honors `unscoped: true` entries — never touches them. Skips files with
+ * no citations and no prior entry to avoid polluting the index. When a
+ * file's cite set differs from its scope-index entry (added, removed, or
+ * stale ids), the entry is rewritten with the deterministically-sorted
+ * current set.
+ */
+export function rescanScopeIndex(repoRoot) {
+    // Ghost: scope-index is the SoT (written at Layer A emit), NOT a cache
+    // derived from in-source cites. There are no cites to rescan — and a rescan
+    // would rewrite every bound file's entry to the empty cite-set, wiping the
+    // SoT. No-op so the bindings the GC + recall depend on survive SessionStart
+    // and `cairn join`. (Maintenance happens via anchor-map re-anchoring, §3.6.)
+    if (isGhost(repoRoot)) {
+        return { filesScanned: 0, entriesAdded: 0, entriesUpdated: 0, entriesUnchanged: 0, dirty: false };
+    }
+    const sourceFiles = listGitTrackedSourceFiles(repoRoot);
+    const existing = readScopeIndex(repoRoot) ?? {
+        generated: new Date().toISOString(),
+        files: {},
+    };
+    let entriesAdded = 0;
+    let entriesUpdated = 0;
+    let entriesUnchanged = 0;
+    let dirty = false;
+    for (const rel of sourceFiles) {
+        const prior = existing.files[rel];
+        if (prior?.unscoped === true)
+            continue;
+        const found = scanFileCitations(join(repoRoot, rel));
+        if (found === null)
+            continue;
+        if (found.decisions.length === 0 &&
+            found.invariants.length === 0 &&
+            prior === undefined) {
+            continue;
+        }
+        if (prior === undefined) {
+            existing.files[rel] = {
+                decisions: found.decisions,
+                invariants: found.invariants,
+            };
+            entriesAdded += 1;
+            dirty = true;
+            continue;
+        }
+        const sameDecs = prior.decisions.length === found.decisions.length &&
+            prior.decisions.every((d, i) => d === found.decisions[i]);
+        const sameInvs = prior.invariants.length === found.invariants.length &&
+            prior.invariants.every((v, i) => v === found.invariants[i]);
+        if (sameDecs && sameInvs) {
+            entriesUnchanged += 1;
+            continue;
+        }
+        existing.files[rel] = {
+            decisions: found.decisions,
+            invariants: found.invariants,
+        };
+        entriesUpdated += 1;
+        dirty = true;
+    }
+    if (dirty) {
+        writeScopeIndex(repoRoot, {
+            generated: new Date().toISOString(),
+            files: existing.files,
+        });
+    }
+    return {
+        filesScanned: sourceFiles.length,
+        entriesAdded,
+        entriesUpdated,
+        entriesUnchanged,
+        dirty,
+    };
+}
+function scanFileCitations(absPath) {
+    let body;
+    try {
+        body = readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    return parseCitations(body);
+}
+function parseCitations(body) {
+    const decs = new Set();
+    const invs = new Set();
+    for (const m of body.matchAll(CITATION_RE)) {
+        const tok = m[0].slice(1);
+        if (tok.startsWith("DEC-"))
+            decs.add(tok);
+        else if (tok.startsWith("INV-"))
+            invs.add(tok);
+    }
+    return {
+        decisions: [...decs].sort(),
+        invariants: [...invs].sort(),
+    };
+}
+/**
+ * Single-file scope-index sync from in-memory content. Called by the
+ * PostToolUse(Write/Edit) hook so an agent's writes don't leave the
+ * scope-index stale until the next SessionStart rescan. Same regex
+ * parser as `rescanScopeIndex`, but bounded to one file — O(1) cost,
+ * no walker.
+ *
+ * Honors `unscoped: true` entries (skips them). Honors the same skip
+ * rule the rescan does: file with no citations and no prior entry is
+ * a no-op so we don't pollute the index with empty rows.
+ */
+export function syncFileScopeFromContent(repoRoot, repoRelPath, content) {
+    const found = parseCitations(content);
+    const existing = readScopeIndex(repoRoot) ?? {
+        generated: new Date().toISOString(),
+        files: {},
+    };
+    const prior = existing.files[repoRelPath];
+    if (prior?.unscoped === true)
+        return { dirty: false };
+    if (found.decisions.length === 0 &&
+        found.invariants.length === 0 &&
+        prior === undefined) {
+        return { dirty: false };
+    }
+    if (prior !== undefined) {
+        const sameDecs = prior.decisions.length === found.decisions.length &&
+            prior.decisions.every((d, i) => d === found.decisions[i]);
+        const sameInvs = prior.invariants.length === found.invariants.length &&
+            prior.invariants.every((v, i) => v === found.invariants[i]);
+        if (sameDecs && sameInvs)
+            return { dirty: false };
+    }
+    existing.files[repoRelPath] = {
+        decisions: found.decisions,
+        invariants: found.invariants,
+    };
+    writeScopeIndex(repoRoot, {
+        generated: new Date().toISOString(),
+        files: existing.files,
+    });
+    return { dirty: true };
+}
+function listGitTrackedSourceFiles(repoRoot) {
+    let out;
+    try {
+        out = execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], { cwd: repoRoot, maxBuffer: 100 * 1024 * 1024 }).toString("utf8");
+    }
+    catch {
+        return [];
+    }
+    const acc = [];
+    for (const path of out.split("\0")) {
+        if (path.length === 0)
+            continue;
+        if (RESCAN_SKIP_DIR_RE.test(path))
+            continue;
+        if (!RESCAN_SOURCE_EXT_RE.test(path))
+            continue;
+        acc.push(path);
+    }
+    return acc;
+}
+/**
+ * `cairn scope rebuild` — full deterministic resync of `.cairn/ground/
+ * scope-index.yaml` from current source-cite reality. Used to be a
+ * Sonnet call (`runMapper`-style) that re-classified files via the
+ * Tier-2 mapper, but classification was always the wrong abstraction
+ * — bare-symbol citations in source are the canonical source of truth,
+ * `rescanScopeIndex` parses them deterministically, and the result
+ * matches what the read-enricher legend actually shows.
+ *
+ * No LLM. No tokens. No mapper. Just a regex sweep over git-tracked
+ * source files and an atomic write.
+ */
+export async function rebuildScopeIndex(opts) {
+    log.info({ repo_root: opts.repoRoot }, "scope rebuild — deterministic rescan");
+    const startedAt = Date.now();
+    const result = rescanScopeIndex(opts.repoRoot);
+    return {
+        path: scopeIndexPath(opts.repoRoot),
+        filesClassified: result.entriesAdded + result.entriesUpdated + result.entriesUnchanged,
+        durationMs: Date.now() - startedAt,
+    };
+}
+//# sourceMappingURL=scope-index.js.map

package/dist/scope-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-index.js","sourceRoot":"","sources":["../src/scope-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAQxC,MAAM,SAAS,GAAG,sBAAsB,CAAC;AACzC,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAuB;IACvD,OAAO,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAuB;IACxD,OAAO,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,SAAS,CAAC,GAAuB,EAAE,EAAU;IACpD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,SAAS;QACpC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,IAAI;YAAE,SAAS;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,SAAS;QAC7B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACf,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAOD,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/D,MAAM,SAAS,GACb,OAAQ,MAAkC,CAAC,WAAW,CAAC,KAAK,QAAQ;QAClE,CAAC,CAAG,MAAkC,CAAC,WAAW,CAAY;QAC9D,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAI,MAAkC,CAAC,OAAO,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAoC,EAAE,CAAC;IAClD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;gBAAE,SAAS;YAClD,MAAM,CAAC,GAAG,CAA4B,CAAC;YACvC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;gBAC7C,CAAC,CAAE,CAAC,CAAC,WAAW,CAAe,CAAC,MAAM,CAClC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAC1C;gBACH,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;gBAC/C,CAAC,CAAE,CAAC,CAAC,YAAY,CAAe,CAAC,MAAM,CACnC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAC1C;gBACH,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,KAAK,GAAoB,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;YACzD,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK,IAAI;gBAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;YAClD,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,KAAiB,EACjB,gBAAwB;IAExB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC5C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,KAAiB;IACjE,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACtC,aAAa,CAAC,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;AAExB,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,MAAM,WAAW,GAAG,sBAAsB,CAAC;AAE3C,MAAM,oBAAoB,GACxB,mGAAmG,CAAC;AAEtG,MAAM,kBAAkB,GACtB,yGAAyG,CAAC;AAW5G;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,uEAAuE;IACvE,4EAA4E;IAC5E,2EAA2E;IAC3E,4EAA4E;IAC5E,6EAA6E;IAC7E,IAAI,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACpG,CAAC;IACD,MAAM,WAAW,GAAG,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,CAAC,IAAI;QAC3C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK,EAAE,EAAE;KACV,CAAC;IACF,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,gBAAgB,GAAG,CAAC,CAAC;IACzB,IAAI,KAAK,GAAG,KAAK,CAAC;IAElB,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,KAAK,EAAE,QAAQ,KAAK,IAAI;YAAE,SAAS;QACvC,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;QACrD,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAE7B,IACE,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YAC5B,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;YAC7B,KAAK,KAAK,SAAS,EACnB,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG;gBACpB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;aAC7B,CAAC;YACF,YAAY,IAAI,CAAC,CAAC;YAClB,KAAK,GAAG,IAAI,CAAC;YACb,SAAS;QACX,CAAC;QAED,MAAM,QAAQ,GACZ,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,KAAK,CAAC,SAAS,CAAC,MAAM;YACjD,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,QAAQ,GACZ,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,KAAK,CAAC,UAAU,CAAC,MAAM;YACnD,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,IAAI,QAAQ,IAAI,QAAQ,EAAE,CAAC;YACzB,gBAAgB,IAAI,CAAC,CAAC;YACtB,SAAS;QACX,CAAC;QAED,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG;YACpB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B,CAAC;QACF,cAAc,IAAI,CAAC,CAAC;QACpB,KAAK,GAAG,IAAI,CAAC;IACf,CAAC;IAED,IAAI,KAAK,EAAE,CAAC;QACV,eAAe,CAAC,QAAQ,EAAE;YACxB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,YAAY,EAAE,WAAW,CAAC,MAAM;QAChC,YAAY;QACZ,cAAc;QACd,gBAAgB;QAChB,KAAK;KACN,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CACxB,OAAe;IAEf,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAIlC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;aACrC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjD,CAAC;IACD,OAAO;QACL,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE;QAC3B,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE;KAC7B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAgB,EAChB,WAAmB,EACnB,OAAe;IAEf,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,CAAC,IAAI;QAC3C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK,EAAE,EAAE;KACV,CAAC;IACF,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAC1C,IAAI,KAAK,EAAE,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACtD,IACE,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAC5B,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;QAC7B,KAAK,KAAK,SAAS,EACnB,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,QAAQ,GACZ,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,KAAK,CAAC,SAAS,CAAC,MAAM;YACjD,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,QAAQ,GACZ,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,KAAK,CAAC,UAAU,CAAC,MAAM;YACnD,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,IAAI,QAAQ,IAAI,QAAQ;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACpD,CAAC;IACD,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG;QAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;KAC7B,CAAC;IACF,eAAe,CAAC,QAAQ,EAAE;QACxB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK,EAAE,QAAQ,CAAC,KAAK;KACtB,CAAC,CAAC;IACH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,SAAS,yBAAyB,CAAC,QAAgB;IACjD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAChB,KAAK,EACL,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,oBAAoB,EAAE,IAAI,CAAC,EAChE,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,CAChD,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAChC,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAC5C,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/C,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAiBD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAA8B;IAE9B,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,sCAAsC,CAAC,CAAC;IAC/E,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/C,OAAO;QACL,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;QACnC,eAAe,EACb,MAAM,CAAC,YAAY,GAAG,MAAM,CAAC,cAAc,GAAG,MAAM,CAAC,gBAAgB;QACvE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;KACnC,CAAC;AACJ,CAAC"}

package/dist/slug.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Normalize a prose block: strip markdown ornaments + collapse whitespace.
+ * Output is the canonical form fed into both content-fingerprint slug
+ * generation and content-hash calculation. Identical normalized output
+ * → identical slug, even if the source markdown formatting differs.
+ */
+export declare function normalizeBlock(input: string): string;
+/**
+ * Compute the 12-char content-fingerprint slug for a prose block. Uses
+ * sha256 over the normalized body, hex-encoded, sliced to 12 chars.
+ *
+ * 12 chars → 48 bits, ~280 trillion buckets. Birthday collision becomes
+ * meaningful around 16 million distinct topics; real repos are nowhere
+ * close to that.
+ */
+export declare function topicSlug(input: string): string;
+/**
+ * Compute the full sha256 hex of a prose body (no normalization). Used
+ * for sot_content_hash drift detection — the hash must change when the
+ * operator edits the source paragraph by even one character so the
+ * doc-drift sensor can fire.
+ */
+export declare function bodyContentHash(body: string): string;
+/**
+ * Derive a stable DEC id from canonical inputs. Plan §3.2.1: id =
+ * "DEC-" + sha256(JSON.stringify({sot_path, title, capture_source})).slice(0, 7).
+ *
+ * Body is intentionally NOT in the hash input — doc-drift refresh
+ * updates body but keeps the id stable so every §DEC-<hash> token in
+ * source files survives the refresh.
+ */
+export declare function deriveDecId(input: {
+    sot_path: string;
+    title: string;
+    capture_source: string;
+}): string;
+export declare function deriveInvId(input: {
+    sot_path: string;
+    title: string;
+    capture_source: string;
+}): string;
+/**
+ * Ledger-DEC id derivation for source-comment captures (plan §5.3). The
+ * generic `deriveDecId` keys on `(sot_path, title, capture_source)`, which
+ * collapses for ledger entries because every source-comment DEC shares the
+ * literal `sot_path: "ledger"`. Title alone is not unique — two essay
+ * comments starting with the same line would collide. Source location is
+ * stable post-strip-replace, so `(source_file, source_offset, capture_source)`
+ * is the per-fact unique input.
+ */
+export declare function deriveLedgerDecId(input: {
+    source_file: string;
+    source_offset: number;
+    capture_source: string;
+}): string;
+export declare function deriveLedgerInvId(input: {
+    source_file: string;
+    source_offset: number;
+    capture_source: string;
+}): string;
+/**
+ * Convert an arbitrary title into a kebab-case slug suitable for a
+ * mission id (`MIS-<slug>-<hash7>`). Lowercased ASCII; non-alnum
+ * collapses to single hyphen; trims leading/trailing hyphens; capped
+ * at 32 chars to keep mission ids inside the 40-char statusline budget
+ * after the `MIS-` prefix + `-<hash7>` suffix.
+ */
+export declare function titleToSlug(title: string, maxLen?: number): string;
+/**
+ * Derive a stable mission id from canonical inputs. Format:
+ * `MIS-<slug>-<hash7>` mirroring TSK-/DEC-/INV- conventions.
+ *
+ * Hash inputs include `started_at` so re-running `mission start` on the
+ * same spec doc minutes later produces a fresh id (no collision with
+ * the prior mission's archived dirs).
+ */
+export declare function deriveMissionId(input: {
+    title: string;
+    spec_path: string;
+    started_at: string;
+}): string;

package/dist/slug.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+/**
+ * Content-fingerprint helpers shared by topic-index, anchor-map, sot-cache,
+ * and the Layer A alignment hook.
+ *
+ * The content slug is sha256-derived from the normalized prose body so two
+ * identical blocks (in any source) produce the same slug. Different content
+ * → different slug, regardless of leading words. This avoids the "we use
+ * postgres for X" vs "we use postgres for Y" collision that a leading-word
+ * slugger would suffer.
+ */
+const NORMALIZE_PATTERNS = [
+    { pattern: /```[\s\S]*?```/g, replacement: " " },
+    { pattern: /`[^`]+`/g, replacement: " " },
+    { pattern: /\[([^\]]+)\]\([^)]*\)/g, replacement: "$1" },
+    { pattern: /^#{1,6}\s+/gm, replacement: "" },
+    { pattern: /^[\s>*\-+]+/gm, replacement: "" },
+    { pattern: /\s+/g, replacement: " " },
+];
+/**
+ * Normalize a prose block: strip markdown ornaments + collapse whitespace.
+ * Output is the canonical form fed into both content-fingerprint slug
+ * generation and content-hash calculation. Identical normalized output
+ * → identical slug, even if the source markdown formatting differs.
+ */
+export function normalizeBlock(input) {
+    let s = input;
+    for (const { pattern, replacement } of NORMALIZE_PATTERNS) {
+        s = s.replace(pattern, replacement);
+    }
+    return s.trim().toLowerCase();
+}
+/**
+ * Compute the 12-char content-fingerprint slug for a prose block. Uses
+ * sha256 over the normalized body, hex-encoded, sliced to 12 chars.
+ *
+ * 12 chars → 48 bits, ~280 trillion buckets. Birthday collision becomes
+ * meaningful around 16 million distinct topics; real repos are nowhere
+ * close to that.
+ */
+export function topicSlug(input) {
+    const normalized = normalizeBlock(input);
+    return createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 12);
+}
+/**
+ * Compute the full sha256 hex of a prose body (no normalization). Used
+ * for sot_content_hash drift detection — the hash must change when the
+ * operator edits the source paragraph by even one character so the
+ * doc-drift sensor can fire.
+ */
+export function bodyContentHash(body) {
+    return createHash("sha256").update(body, "utf8").digest("hex");
+}
+/**
+ * Derive a stable DEC id from canonical inputs. Plan §3.2.1: id =
+ * "DEC-" + sha256(JSON.stringify({sot_path, title, capture_source})).slice(0, 7).
+ *
+ * Body is intentionally NOT in the hash input — doc-drift refresh
+ * updates body but keeps the id stable so every §DEC-<hash> token in
+ * source files survives the refresh.
+ */
+export function deriveDecId(input) {
+    const json = JSON.stringify({
+        sot_path: input.sot_path,
+        title: input.title,
+        capture_source: input.capture_source,
+    });
+    return `DEC-${createHash("sha256").update(json, "utf8").digest("hex").slice(0, 7)}`;
+}
+export function deriveInvId(input) {
+    const json = JSON.stringify({
+        sot_path: input.sot_path,
+        title: input.title,
+        capture_source: input.capture_source,
+    });
+    return `INV-${createHash("sha256").update(json, "utf8").digest("hex").slice(0, 7)}`;
+}
+/**
+ * Ledger-DEC id derivation for source-comment captures (plan §5.3). The
+ * generic `deriveDecId` keys on `(sot_path, title, capture_source)`, which
+ * collapses for ledger entries because every source-comment DEC shares the
+ * literal `sot_path: "ledger"`. Title alone is not unique — two essay
+ * comments starting with the same line would collide. Source location is
+ * stable post-strip-replace, so `(source_file, source_offset, capture_source)`
+ * is the per-fact unique input.
+ */
+export function deriveLedgerDecId(input) {
+    const json = JSON.stringify({
+        source_file: input.source_file,
+        source_offset: input.source_offset,
+        capture_source: input.capture_source,
+    });
+    return `DEC-${createHash("sha256").update(json, "utf8").digest("hex").slice(0, 7)}`;
+}
+export function deriveLedgerInvId(input) {
+    const json = JSON.stringify({
+        source_file: input.source_file,
+        source_offset: input.source_offset,
+        capture_source: input.capture_source,
+    });
+    return `INV-${createHash("sha256").update(json, "utf8").digest("hex").slice(0, 7)}`;
+}
+/**
+ * Convert an arbitrary title into a kebab-case slug suitable for a
+ * mission id (`MIS-<slug>-<hash7>`). Lowercased ASCII; non-alnum
+ * collapses to single hyphen; trims leading/trailing hyphens; capped
+ * at 32 chars to keep mission ids inside the 40-char statusline budget
+ * after the `MIS-` prefix + `-<hash7>` suffix.
+ */
+export function titleToSlug(title, maxLen = 32) {
+    const slug = title
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, maxLen)
+        .replace(/-+$/g, "");
+    return slug.length > 0 ? slug : "mission";
+}
+/**
+ * Derive a stable mission id from canonical inputs. Format:
+ * `MIS-<slug>-<hash7>` mirroring TSK-/DEC-/INV- conventions.
+ *
+ * Hash inputs include `started_at` so re-running `mission start` on the
+ * same spec doc minutes later produces a fresh id (no collision with
+ * the prior mission's archived dirs).
+ */
+export function deriveMissionId(input) {
+    const slug = titleToSlug(input.title);
+    const json = JSON.stringify({
+        title: input.title,
+        spec_path: input.spec_path,
+        started_at: input.started_at,
+    });
+    const hash = createHash("sha256").update(json, "utf8").digest("hex").slice(0, 7);
+    return `MIS-${slug}-${hash}`;
+}
+//# sourceMappingURL=slug.js.map

package/dist/slug.js.map

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

package/dist/sot-bindings.d.ts

@@ -0,0 +1,14 @@
+import { SotBindings } from "./schemas.js";
+/**
+ * Sot-bindings is the lookup table that lens + sensors + the alignment
+ * hook all consult to resolve a §DEC-<hash> token to its canonical
+ * source. The forward index is one DEC → one path. The reverse index is
+ * one path → many DECs (supersedes chains share their sot_path).
+ */
+export declare function emptySotBindings(): SotBindings;
+export declare function readSotBindings(repoRoot: string): SotBindings;
+export declare function writeSotBindings(repoRoot: string, bindings: SotBindings): string;
+export declare function bindDec(bindings: SotBindings, decId: string, sotPath: string): SotBindings;
+export declare function unbindDec(bindings: SotBindings, decId: string): SotBindings;
+export declare function decsForPath(bindings: SotBindings, sotPath: string): string[];
+export declare function pathForDec(bindings: SotBindings, decId: string): string | null;

package/dist/sot-bindings.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileSafe } from "./fs.js";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { getLogger } from "./logger.js";
+import { sotBindingsPath } from "./paths.js";
+import { SotBindings } from "./schemas.js";
+const log = getLogger();
+/**
+ * Sot-bindings is the lookup table that lens + sensors + the alignment
+ * hook all consult to resolve a §DEC-<hash> token to its canonical
+ * source. The forward index is one DEC → one path. The reverse index is
+ * one path → many DECs (supersedes chains share their sot_path).
+ */
+export function emptySotBindings() {
+    return {
+        version: 1,
+        generated: new Date().toISOString(),
+        forward: {},
+        reverse: {},
+    };
+}
+export function readSotBindings(repoRoot) {
+    const path = sotBindingsPath(repoRoot);
+    if (!existsSync(path))
+        return emptySotBindings();
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = SotBindings.safeParse(parseYaml(raw));
+        if (!parsed.success) {
+            log.warn({ path, error: parsed.error.message }, "sot-bindings invalid; treating as empty");
+            return emptySotBindings();
+        }
+        return parsed.data;
+    }
+    catch (err) {
+        log.warn({ path, err }, "sot-bindings read failed; treating as empty");
+        return emptySotBindings();
+    }
+}
+export function writeSotBindings(repoRoot, bindings) {
+    const path = sotBindingsPath(repoRoot);
+    const next = { ...bindings, generated: new Date().toISOString() };
+    writeFileSafe(path, stringifyYaml(next));
+    log.debug({ path, decs: Object.keys(next.forward).length }, "wrote sot-bindings");
+    return path;
+}
+export function bindDec(bindings, decId, sotPath) {
+    const forward = { ...bindings.forward, [decId]: sotPath };
+    const reverse = { ...bindings.reverse };
+    const existing = reverse[sotPath] ?? [];
+    if (!existing.includes(decId)) {
+        reverse[sotPath] = [...existing, decId];
+    }
+    return { ...bindings, forward, reverse };
+}
+export function unbindDec(bindings, decId) {
+    const sotPath = bindings.forward[decId];
+    if (sotPath === undefined)
+        return bindings;
+    const forward = { ...bindings.forward };
+    delete forward[decId];
+    const reverse = { ...bindings.reverse };
+    const list = reverse[sotPath] ?? [];
+    const filtered = list.filter((id) => id !== decId);
+    if (filtered.length === 0) {
+        delete reverse[sotPath];
+    }
+    else {
+        reverse[sotPath] = filtered;
+    }
+    return { ...bindings, forward, reverse };
+}
+export function decsForPath(bindings, sotPath) {
+    return bindings.reverse[sotPath] ?? [];
+}
+export function pathForDec(bindings, decId) {
+    return bindings.forward[decId] ?? null;
+}
+//# sourceMappingURL=sot-bindings.js.map

package/dist/sot-bindings.js.map

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

package/dist/sot-cache.d.ts

@@ -0,0 +1,18 @@
+import { SotCache, type SotCacheEntry } from "./schemas.js";
+/**
+ * Sot-cache holds pre-tokenized DEC body content for the Layer A Jaccard
+ * pre-filter. Rebuilt at SessionStart, incremental on PostToolUse Write
+ * events that touch a DEC body or sot-path file. Mtime-keyed so a stale
+ * entry is detected without re-tokenizing every body on every Write.
+ */
+export declare function emptySotCache(): SotCache;
+export declare function readSotCache(repoRoot: string): SotCache;
+export declare function writeSotCache(repoRoot: string, cache: SotCache): string;
+export declare function setSotCacheEntry(cache: SotCache, decId: string, entry: SotCacheEntry): SotCache;
+export declare function getSotCacheEntry(cache: SotCache, decId: string): SotCacheEntry | null;
+export declare function deleteSotCacheEntry(cache: SotCache, decId: string): SotCache;
+/**
+ * Iterate all entries. Layer A's pre-filter pass calls this on each
+ * Write to compute Jaccard against every cached DEC body.
+ */
+export declare function sotCacheEntries(cache: SotCache): SotCacheEntry[];