@isaacriehm/cairn-state 0.22.5

package/dist/archive.js.map

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

package/dist/cache.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Per-process LRU cache (max 1 entry) for the invariants ledger and
+ * task-status lookups consumed by the read-enricher hook. All disk
+ * reads here are best-effort: any failure returns null/not_found so
+ * the hook stays a no-op.
+ */
+import { type ScopeIndexEntry } from "./scope-index.js";
+export type { ScopeIndexEntry } from "./scope-index.js";
+export interface LedgerSnapshot {
+    invariantsByid: Map<string, {
+        title: string;
+        status: string;
+        superseded_by?: string;
+    }>;
+}
+export interface DecisionsLedgerSnapshot {
+    decisionsByid: Map<string, {
+        title: string;
+        status: string;
+        superseded_by?: string;
+    }>;
+}
+export declare function getInvariantsLedger(repoRoot: string): LedgerSnapshot | null;
+export declare function getDecisionsLedger(repoRoot: string): DecisionsLedgerSnapshot | null;
+/**
+ * Cached scope-index reader. Content-keyed (sha256 of first 512 bytes) so
+ * back-to-back hook invocations in the same process don't re-parse the file
+ * AND so concurrent ledger writes that happen within the same mtime tick
+ * are not silently masked by a stale cache hit (Gap 6 in BUILD_REPORT).
+ *
+ * Returns null when the file is missing, when no entry matches the path,
+ * when the entry is explicitly `unscoped: true`, or when the entry has no
+ * decisions/invariants — i.e., when there is nothing useful to surface.
+ */
+export declare function getScopeIndexEntry(repoRoot: string, repoRelativePath: string): ScopeIndexEntry | null;
+/**
+ * Cached `file-candidates-map.yaml` reader. mtime-keyed; the read-enrich
+ * hook hits this once per Read so the cache pays off after the second
+ * read of any file in the same session. Returns 0 when the file is
+ * missing (no walks have happened yet — typical for a fresh clone) so
+ * the candidate-count hint stays silent on un-adopted projects.
+ *
+ *  The map is regenerated every time
+ * phase 5b walks the repo and every time phase 6 / `cairn_propose_decision`
+ * stamps a new `dec_id` on a topic-index entry. The mtime invalidation
+ * picks up both refresh paths.
+ */
+export declare function getFileCandidateCount(repoRoot: string, repoRelativePath: string): number;

package/dist/cache.js

@@ -0,0 +1,241 @@
+/**
+ * Per-process LRU cache (max 1 entry) for the invariants ledger and
+ * task-status lookups consumed by the read-enricher hook. All disk
+ * reads here are best-effort: any failure returns null/not_found so
+ * the hook stays a no-op.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, openSync, readFileSync, readSync, closeSync, statSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { cairnDir } from "./home.js";
+import { fileCandidatesMapPath } from "./paths.js";
+import { FileCandidatesMap } from "./schemas.js";
+import { lookupScope, readScopeIndex, scopeIndexPath, } from "./scope-index.js";
+const DecisionLedgerEntrySchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    status: z.string().optional(),
+    superseded_by: z.string().optional(),
+}).passthrough();
+const InvariantLedgerEntrySchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    status: z.string().optional(),
+    superseded_by: z.string().optional(),
+}).passthrough();
+const SCOPE_INDEX_HASH_BYTES = 512;
+/**
+ * Hash the first N bytes of a file. Returns null when the file can't be read.
+ * Used as the cache key for scope-index — mtime is unreliable under clock
+ * skew (concurrent ledger writes can land with the same mtime as the
+ * previous read).
+ */
+function hashFilePrefix(path, bytes) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const buf = Buffer.alloc(bytes);
+        const read = readSync(fd, buf, 0, bytes, 0);
+        return createHash("sha256")
+            .update(buf.subarray(0, read))
+            .digest("hex");
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // ignore — best-effort
+        }
+    }
+}
+let invariantsCache = null;
+let decisionsCache = null;
+let scopeIndexCache = null;
+let fileCandidatesCache = null;
+function invariantsLedgerFile(repoRoot) {
+    return cairnDir(repoRoot, "ground", "invariants", "invariants.ledger.yaml");
+}
+export function getInvariantsLedger(repoRoot) {
+    const path = invariantsLedgerFile(repoRoot);
+    if (!existsSync(path))
+        return null;
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+    if (invariantsCache !== null &&
+        invariantsCache.repoRoot === repoRoot &&
+        invariantsCache.mtimeMs === mtimeMs) {
+        return invariantsCache.snapshot;
+    }
+    let parsed;
+    try {
+        const raw = readFileSync(path, "utf8");
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return null;
+    }
+    const result = z.array(InvariantLedgerEntrySchema).safeParse(parsed);
+    if (!result.success)
+        return null;
+    const map = new Map();
+    for (const entry of result.data) {
+        const id = entry.id;
+        const title = entry.title;
+        const status = entry.status ?? "active";
+        const supersededBy = entry.superseded_by;
+        map.set(id, {
+            title,
+            status,
+            ...(typeof supersededBy === "string" && supersededBy.length > 0 ? { superseded_by: supersededBy } : {}),
+        });
+    }
+    const snapshot = { invariantsByid: map };
+    invariantsCache = { repoRoot, mtimeMs, snapshot };
+    return snapshot;
+}
+function decisionsLedgerFile(repoRoot) {
+    return cairnDir(repoRoot, "ground", "decisions", "decisions.ledger.yaml");
+}
+export function getDecisionsLedger(repoRoot) {
+    const path = decisionsLedgerFile(repoRoot);
+    if (!existsSync(path))
+        return null;
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+    if (decisionsCache !== null &&
+        decisionsCache.repoRoot === repoRoot &&
+        decisionsCache.mtimeMs === mtimeMs) {
+        return decisionsCache.snapshot;
+    }
+    let parsed;
+    try {
+        const raw = readFileSync(path, "utf8");
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return null;
+    }
+    const result = z.array(DecisionLedgerEntrySchema).safeParse(parsed);
+    if (!result.success)
+        return null;
+    const map = new Map();
+    for (const entry of result.data) {
+        const id = entry.id;
+        const title = entry.title;
+        const status = entry.status ?? "accepted";
+        const supersededBy = entry.superseded_by;
+        map.set(id, {
+            title,
+            status,
+            ...(typeof supersededBy === "string" && supersededBy.length > 0 ? { superseded_by: supersededBy } : {}),
+        });
+    }
+    const snapshot = { decisionsByid: map };
+    decisionsCache = { repoRoot, mtimeMs, snapshot };
+    return snapshot;
+}
+/**
+ * Cached scope-index reader. Content-keyed (sha256 of first 512 bytes) so
+ * back-to-back hook invocations in the same process don't re-parse the file
+ * AND so concurrent ledger writes that happen within the same mtime tick
+ * are not silently masked by a stale cache hit (Gap 6 in BUILD_REPORT).
+ *
+ * Returns null when the file is missing, when no entry matches the path,
+ * when the entry is explicitly `unscoped: true`, or when the entry has no
+ * decisions/invariants — i.e., when there is nothing useful to surface.
+ */
+export function getScopeIndexEntry(repoRoot, repoRelativePath) {
+    const path = scopeIndexPath(repoRoot);
+    if (!existsSync(path))
+        return null;
+    const contentHash = hashFilePrefix(path, SCOPE_INDEX_HASH_BYTES);
+    if (contentHash === null)
+        return null;
+    let index;
+    if (scopeIndexCache !== null &&
+        scopeIndexCache.repoRoot === repoRoot &&
+        scopeIndexCache.contentHash === contentHash) {
+        index = scopeIndexCache.index;
+    }
+    else {
+        const fresh = readScopeIndex(repoRoot);
+        if (fresh === null)
+            return null;
+        scopeIndexCache = { repoRoot, contentHash, index: fresh };
+        index = fresh;
+    }
+    const entry = lookupScope(index, repoRelativePath);
+    if (entry === null)
+        return null;
+    if (entry.unscoped === true)
+        return null;
+    if (entry.decisions.length === 0 && entry.invariants.length === 0)
+        return null;
+    return entry;
+}
+/**
+ * Cached `file-candidates-map.yaml` reader. mtime-keyed; the read-enrich
+ * hook hits this once per Read so the cache pays off after the second
+ * read of any file in the same session. Returns 0 when the file is
+ * missing (no walks have happened yet — typical for a fresh clone) so
+ * the candidate-count hint stays silent on un-adopted projects.
+ *
+ *  The map is regenerated every time
+ * phase 5b walks the repo and every time phase 6 / `cairn_propose_decision`
+ * stamps a new `dec_id` on a topic-index entry. The mtime invalidation
+ * picks up both refresh paths.
+ */
+export function getFileCandidateCount(repoRoot, repoRelativePath) {
+    const path = fileCandidatesMapPath(repoRoot);
+    if (!existsSync(path))
+        return 0;
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+    if (fileCandidatesCache === null ||
+        fileCandidatesCache.repoRoot !== repoRoot ||
+        fileCandidatesCache.mtimeMs !== mtimeMs) {
+        let parsed;
+        try {
+            parsed = parseYaml(readFileSync(path, "utf8"));
+        }
+        catch {
+            return 0;
+        }
+        const result = FileCandidatesMap.safeParse(parsed);
+        if (!result.success)
+            return 0;
+        const counts = new Map();
+        for (const [file, count] of Object.entries(result.data.file_candidates)) {
+            if (typeof count === "number" && count > 0)
+                counts.set(file, count);
+        }
+        fileCandidatesCache = { repoRoot, mtimeMs, counts };
+    }
+    return fileCandidatesCache.counts.get(repoRelativePath) ?? 0;
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE5F,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,GAGf,MAAM,kBAAkB,CAAC;AAI1B,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC,WAAW,EAAE,CAAC;AAEjB,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC,WAAW,EAAE,CAAC;AA0CjB,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAEnC;;;;;GAKG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,KAAa;IACjD,IAAI,EAAU,CAAC;IACf,IAAI,CAAC;QACH,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5C,OAAO,UAAU,CAAC,QAAQ,CAAC;aACxB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;aAC7B,MAAM,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,SAAS,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;AACH,CAAC;AAED,IAAI,eAAe,GAAgC,IAAI,CAAC;AACxD,IAAI,cAAc,GAA+B,IAAI,CAAC;AACtD,IAAI,eAAe,GAAgC,IAAI,CAAC;AACxD,IAAI,mBAAmB,GAAoC,IAAI,CAAC;AAEhE,SAAS,oBAAoB,CAAC,QAAgB;IAC5C,OAAO,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,wBAAwB,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,QAAgB;IAEhB,MAAM,IAAI,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IACE,eAAe,KAAK,IAAI;QACxB,eAAe,CAAC,QAAQ,KAAK,QAAQ;QACrC,eAAe,CAAC,OAAO,KAAK,OAAO,EACnC,CAAC;QACD,OAAO,eAAe,CAAC,QAAQ,CAAC;IAClC,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACvC,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACrE,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAGhB,CAAC;IACJ,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,QAAQ,CAAC;QACxC,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC;QACzC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE;YACV,KAAK;YACL,MAAM;YACN,GAAG,CAAC,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxG,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAmB,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC;IACzD,eAAe,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAClD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAgB;IAC3C,OAAO,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,uBAAuB,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,QAAgB;IAEhB,MAAM,IAAI,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IACE,cAAc,KAAK,IAAI;QACvB,cAAc,CAAC,QAAQ,KAAK,QAAQ;QACpC,cAAc,CAAC,OAAO,KAAK,OAAO,EAClC,CAAC;QACD,OAAO,cAAc,CAAC,QAAQ,CAAC;IACjC,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACvC,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpE,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAGhB,CAAC;IACJ,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,UAAU,CAAC;QAC1C,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC;QACzC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE;YACV,KAAK;YACL,MAAM;YACN,GAAG,CAAC,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxG,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAA4B,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC;IACjE,cAAc,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IACjD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,gBAAwB;IAExB,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;IACjE,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,KAAiB,CAAC;IACtB,IACE,eAAe,KAAK,IAAI;QACxB,eAAe,CAAC,QAAQ,KAAK,QAAQ;QACrC,eAAe,CAAC,WAAW,KAAK,WAAW,EAC3C,CAAC;QACD,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC;IAChC,CAAC;SAAM,CAAC;QACN,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAChC,eAAe,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC1D,KAAK,GAAG,KAAK,CAAC;IAChB,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;IACnD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,gBAAwB;IAExB,MAAM,IAAI,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IACE,mBAAmB,KAAK,IAAI;QAC5B,mBAAmB,CAAC,QAAQ,KAAK,QAAQ;QACzC,mBAAmB,CAAC,OAAO,KAAK,OAAO,EACvC,CAAC;QACD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;YACxE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC;gBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtE,CAAC;QACD,mBAAmB,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IACtD,CAAC;IACD,OAAO,mBAAmB,CAAC,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}

package/dist/component-registry.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Headerless component registry — the ghost-mode source of truth for the
+ * component store (GHOST_MODE_PLAN.md §3.8.1).
+ *
+ * In committed mode the `@cairn <Name>` header in source IS the source of
+ * truth (`collectComponents` reads it with `parseComponentHeader`). Ghost never
+ * writes that header into client source, so the same classification
+ * (name / category / purpose / aliases) lives out-of-repo here instead, keyed
+ * by the natural identity the in-file header never had to encode because it sat
+ * physically on the code: **(workspace, file, export)**. A content-hash anchor
+ * rides along for the (later) re-anchor-on-read + freshness passes; nothing
+ * reads it yet, so v1 stores a whole-file fingerprint.
+ *
+ * This module is pure state — schema + I/O + upsert + lookup. The MCP write
+ * tool, the mode-aware `collectComponents` flip, and the adoption phases live
+ * in cairn-core. `ComponentRecord`/`ComponentTags` projection (`entryToTags`)
+ * stays in `components.ts` to avoid an import cycle.
+ */
+import { z } from "zod";
+export declare const ComponentAnchor: z.ZodObject<{
+    content_hash: z.ZodString;
+    line_range: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, z.core.$strip>;
+export type ComponentAnchor = z.infer<typeof ComponentAnchor>;
+export declare const ComponentRegistryEntry: z.ZodObject<{
+    workspace: z.ZodDefault<z.ZodString>;
+    file: z.ZodString;
+    export: z.ZodString;
+    name: z.ZodString;
+    category: z.ZodString;
+    purpose: z.ZodString;
+    aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    singleton: z.ZodOptional<z.ZodBoolean>;
+    status: z.ZodOptional<z.ZodString>;
+    uses: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    anchor: z.ZodObject<{
+        content_hash: z.ZodString;
+        line_range: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strip>;
+    exports: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    unit_shaped: z.ZodOptional<z.ZodBoolean>;
+    needs_reconfirm: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ComponentRegistryEntry = z.infer<typeof ComponentRegistryEntry>;
+export declare const ComponentRegistry: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    entries: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        workspace: z.ZodDefault<z.ZodString>;
+        file: z.ZodString;
+        export: z.ZodString;
+        name: z.ZodString;
+        category: z.ZodString;
+        purpose: z.ZodString;
+        aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        singleton: z.ZodOptional<z.ZodBoolean>;
+        status: z.ZodOptional<z.ZodString>;
+        uses: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        anchor: z.ZodObject<{
+            content_hash: z.ZodString;
+            line_range: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, z.core.$strip>;
+        exports: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        unit_shaped: z.ZodOptional<z.ZodBoolean>;
+        needs_reconfirm: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ComponentRegistry = z.infer<typeof ComponentRegistry>;
+export declare function componentRegistryPath(repoRoot: string): string;
+export declare function emptyComponentRegistry(): ComponentRegistry;
+/** Read the registry; empty when absent / unreadable / invalid. */
+export declare function readComponentRegistry(repoRoot: string): ComponentRegistry;
+export declare function writeComponentRegistry(repoRoot: string, reg: ComponentRegistry): string;
+/**
+ * Upsert one entry by its natural key (workspace, file, export). Pass
+ * `preloaded` when the caller already parsed the registry this tick (e.g. the
+ * freshness hot path on PostToolUse Write) to skip a second YAML read+parse.
+ */
+export declare function registerComponentEntry(repoRoot: string, entry: ComponentRegistryEntry, preloaded?: ComponentRegistry): ComponentRegistry;
+/**
+ * Find the registry entry for a file: same (workspace, file) and an export
+ * the file actually still declares. `exports` is the file's current export
+ * list — passing it lets a renamed-but-not-moved file miss cleanly (→ the
+ * unit reads as unregistered) rather than resolve to a stale symbol.
+ */
+export declare function lookupComponentEntry(reg: ComponentRegistry, workspace: string, file: string, exports: readonly string[]): ComponentRegistryEntry | null;
+/**
+ * Find the entry that governs a repo-relative file path, ignoring workspace
+ * and export — the freshness gate (§3.8.1) only has an edited path in hand, not
+ * the workspace/export. A file maps to at most one registered unit, so the
+ * first `file` match wins. Null when the path isn't registered.
+ */
+export declare function lookupComponentEntryByFile(reg: ComponentRegistry, file: string): ComponentRegistryEntry | null;

package/dist/component-registry.js.map

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

package/dist/components.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Component registry — Cairn's fourth ground store.
+ *
+ * Headers in source (`@cairn <ExportName>` comments) are the committed
+ * source of truth; `.cairn/ground/components/` holds the *derived* index the
+ * agent reads in full before UI work. This module is the pure state layer:
+ * config loading, header parsing, repo walking, deterministic index
+ * rendering, and validation. Disk writes, the advisory audit, MCP tools, and
+ * adoption phases live in cairn-core.
+ *
+ * The registry header is recognized in EVERY comment form (language-agnostic):
+ * block `/* *​/` / JSDoc, `//` line runs, `#` hash runs, `<!-- -->` (Vue /
+ * Svelte / Razor / HTML), `--` (Lua / SQL), and Python `"""` docstrings. The
+ * earliest comment carrying the `@cairn <Name>` signal wins. Export extraction
+ * and unit-shape detection are routed through the shared `languages.ts`
+ * profile table, so a Python `def`, a Go capitalized ident, a SwiftUI `View`,
+ * or a Vue SFC are all first-class — there is no JS/React default.
+ *
+ * The `@cairn <Name>` registry header is disjoint from the pre-existing
+ * `@cairn:decision` / `@cairn:rule` SoT markers: the header detector requires
+ * whitespace then an identifier start, so a colon-form marker can never be
+ * misread as a header.
+ */
+import { z } from "zod";
+export declare const DEFAULT_CATEGORIES: readonly ["layout", "navigation", "data-display", "forms", "feedback", "overlay", "media", "marketing", "utility"];
+export declare const DEFAULT_EXTENSIONS: readonly string[];
+export declare const DEFAULT_EXCLUDE: readonly ["node_modules", "dist", ".next", "build", "coverage", "__tests__", "__mocks__", "stories"];
+/** Tags a header MUST carry. */
+export declare const COMPONENT_REQUIRED_TAGS: readonly ["cairn", "category", "purpose", "aliases"];
+export declare const ComponentsWorkspaceConfig: z.ZodObject<{
+    componentDirs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    shared: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export type ComponentsWorkspaceConfig = z.infer<typeof ComponentsWorkspaceConfig>;
+export declare const ComponentsConfig: z.ZodObject<{
+    componentDirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    workspaces: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        componentDirs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        shared: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type ComponentsConfig = z.infer<typeof ComponentsConfig>;
+/** A workspace after defaults are folded in. `name: ""` = single-app. */
+export interface ComponentWorkspace {
+    name: string;
+    componentDirs: string[];
+    exclude: string[];
+    extensions: string[];
+    categories: string[];
+    shared: boolean;
+}
+export interface NormalizedComponentsConfig {
+    workspaces: ComponentWorkspace[];
+}
+/**
+ * Fold the raw `components:` config into a normalized workspace list.
+ * Flat (single-app) config becomes one unnamed workspace; a `workspaces`
+ * map becomes one entry per key, each inheriting the top-level
+ * exclude/extensions/categories unless it overrides them.
+ */
+export declare function normalizeComponentsConfig(raw: ComponentsConfig): NormalizedComponentsConfig;
+/** Read + normalize the `components:` config from `.cairn/config.yaml`. */
+export declare function loadComponentsConfig(repoRoot: string): NormalizedComponentsConfig;
+/** True when any workspace declares at least one component dir. */
+export declare function hasComponentConfig(config: NormalizedComponentsConfig): boolean;
+/** True for monorepo configs (more than one workspace). */
+export declare function isMonorepoComponents(config: NormalizedComponentsConfig): boolean;
+export interface ComponentTags {
+    cairn?: string;
+    category?: string;
+    purpose?: string;
+    aliases?: string;
+    props?: string;
+    uses?: string;
+    singleton?: string;
+    status?: string;
+    example?: string;
+    [k: string]: string | undefined;
+}
+export interface ComponentRecord {
+    /** Repo-relative POSIX path. */
+    file: string;
+    /** Owning workspace name; "" for single-app. */
+    workspace: string;
+    tags: ComponentTags;
+    /** Best-effort single detected export name, or null when undetectable. */
+    exportName: string | null;
+    /** Every top-level export name in the file (header must match one). */
+    exportNames: string[];
+}
+/**
+ * True when a raw comment block is a `@cairn` registry header. Exported so
+ * the source-comment + curator walkers can exclude headers from candidate
+ * registration (headers must not pollute the topic index or be stripped).
+ */
+export declare function isComponentHeaderBlock(rawBlockText: string): boolean;
+/**
+ * Parse a file's component header into a tag map, or null if absent. The
+ * header is the EARLIEST comment — in any supported form — that carries the
+ * `@cairn <Name>` signal. The per-line tag finder is tolerant of leading
+ * markers (`*`, `//`, `#`, `--`), so raw comment text parses directly.
+ */
+export declare function parseComponentHeader(source: string): ComponentTags | null;
+export interface CollectResult {
+    components: ComponentRecord[];
+    /**
+     * Repo-relative paths of unit-shaped files that are not yet in the store —
+     * committed: no `@cairn` header; ghost: not in the external registry. The
+     * `ghost` flag below tells `validateComponents` how to phrase the finding.
+     */
+    missing: string[];
+    /** True when the tag source was the out-of-repo registry (ghost). */
+    ghost: boolean;
+}
+/**
+ * Walk every workspace's component dirs and parse headers. Returns the
+ * parsed components plus the files that are missing a header. Output is
+ * deterministically sorted (workspace, then component name).
+ */
+export declare function collectComponents(repoRoot: string, config: NormalizedComponentsConfig): CollectResult;
+/** Filesystem-safe slice slug for a workspace name. */
+export declare function sliceSlug(name: string): string;
+/** Relative path (under the components ground dir) of a workspace slice. */
+export declare function sliceRelPath(name: string): string;
+/**
+ * Render every index artifact as a Map of relative path (under
+ * `.cairn/ground/components/`) → content. Single workspace: one flat
+ * INDEX.md. Monorepo: INDEX.md manifest + index/<ws>.md slices — never an
+ * all-workspace inventory file (the honeypot invariant).
+ */
+export declare function renderComponentsIndex(components: ComponentRecord[], config: NormalizedComponentsConfig): Map<string, string>;
+export type ComponentFindingKind = "missing-header" | "unregistered-unit" | "missing-tag" | "invalid-category" | "duplicate-name" | "export-mismatch";
+export interface ComponentFinding {
+    kind: ComponentFindingKind;
+    severity: "hard" | "soft";
+    /** Repo-relative path the finding is about, when applicable. */
+    file?: string;
+    message: string;
+}
+/**
+ * Validate headers across all workspaces. Name uniqueness is scoped per
+ * workspace — platform/Button and site/Button may coexist. Hard findings are
+ * gate failures; soft findings are warnings.
+ *
+ * `@aliases` overlap is NOT a finding: aliases are intentionally-overlapping
+ * fuzzy search hints (two components both findable by "activity log" is
+ * correct), so collision is a non-constraint — flagging it drove edits that
+ * deleted valid aliases and degraded search recall.
+ */
+export declare function validateComponents(result: CollectResult, config: NormalizedComponentsConfig): ComponentFinding[];
+export interface ComponentLedgerEntry {
+    name: string;
+    workspace: string;
+    file: string;
+    category: string;
+    purpose: string;
+    aliases: string[];
+    singleton: boolean;
+    status?: string;
+    uses: string[];
+}
+/** Collect + project the component registry into ledger entries. */
+export declare function buildComponentsLedger(repoRoot: string): ComponentLedgerEntry[];
+export interface ComponentScope {
+    /** Workspaces the requested paths resolved to (own + shared). */
+    workspaces: string[];
+    /** Isolated workspaces the caller may NOT use (awareness list). */
+    offLimits: string[];
+    /** The entitled inventory. */
+    components: ComponentLedgerEntry[];
+}
+/**
+ * Resolve which workspace(s) the given repo-relative path globs touch
+ * (longest-prefix match against component dirs), and return the entitled
+ * inventory: own workspace(s) + any `[shared]` workspace, with isolated
+ * workspaces named in `offLimits`. Single-app → the whole inventory.
+ */
+export declare function componentsInScope(repoRoot: string, pathGlobs: string[]): ComponentScope;
+/** Look up a single component by name (optionally scoped to a workspace). */
+export declare function getComponent(repoRoot: string, name: string, workspace?: string): {
+    entry: ComponentLedgerEntry;
+    record: ComponentRecord;
+} | null;