@holmes-lab/holmes-kit 0.18.0 → 0.19.2

package/dist/holmes/cpg/arch-observe.d.ts

@@ -0,0 +1,15 @@
+export interface ArchObservation {
+    path: string;
+    lines: number | null;
+    symbols: number;
+    longestFunction: number | null;
+    fanIn: number;
+    fanOut: number;
+}
+export declare function architectureObservation(files: readonly string[], symbolsByFile: ReadonlyMap<string, Array<{
+    startLine: number;
+    endLine: number;
+}>>, importEdges: readonly {
+    from: string;
+    to: string;
+}[], readLines: (file: string) => number | null): ArchObservation[];

package/dist/holmes/cpg/arch-observe.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.architectureObservation = architectureObservation;
+function architectureObservation(files, symbolsByFile, importEdges, readLines) {
+    return [...files].sort().map((path) => {
+        const syms = symbolsByFile.get(path) ?? [];
+        const spans = syms.map((s) => s.endLine - s.startLine + 1);
+        return {
+            path,
+            // null, not 0: a file we could not read is a different fact from an empty file, and
+            // collapsing the two is how a report starts lying quietly.
+            lines: readLines(path),
+            symbols: syms.length,
+            longestFunction: spans.length === 0 ? null : Math.max(...spans),
+            fanIn: importEdges.filter((e) => e.to === path).length,
+            fanOut: importEdges.filter((e) => e.from === path).length,
+        };
+    });
+}

package/dist/holmes/cpg/cpg-scanner.d.ts

@@ -1,39 +1,6 @@
-import { LanguageParser, CodeSymbol, CodeEdge, DataFlowFacts } from './language-parser';
-export interface ScannedFile {
-    path: string;
-    /** Repo-root-relative POSIX path — provenance key used by RtmGraph.removeBySource. */
-    sourcePath: string;
-    symbols: CodeSymbol[];
-    /**
-     * Call/import relations recovered from this file, with `from` a qualified name defined HERE and
-     * `to` a bare callee name or module path. Resolution to graph node ids happens in rtm-builder,
-     * where the whole scan is visible; a single file cannot know where a callee lives.
-     *
-     * Optional so a cache entry written by an older scanner still loads — such an entry simply carries
-     * no edges, which degrades to the previous anchor-only behaviour rather than crashing.
-     */
-    edges?: CodeEdge[];
-    /**
-     * Def-use facts, present ONLY when the scanner was constructed with `{ dataflow: true }` AND the
-     * file's language has a data-flow walk.
-     *
-     * @implements A-SPEC-140.1
-     * Opt-in by measurement, not taste: the scan already parses each file twice (symbols, edges), and
-     * an unconditional third parse would regress the REQ-139 cold-scan baseline by ~50% to produce a
-     * signal only the taint pass reads. `undefined` therefore means "not extracted" — for the option
-     * being off, for a language with no walk, or for a cache entry from an older writer. It never
-     * means "extracted, found nothing"; that is `{defs:[],calls:[],params:[],returns:[]}`.
-     */
-    dataflow?: DataFlowFacts;
-    implementsSpecs: string[];
-    /**
-     * `@implements` tags shaped like a well-formed governed spec id (REQ/H-SPEC/
-     * C-SPEC/T-SPEC-NNN) instead of an A-SPEC anchor — a wrong-kind anchor that
-     * would otherwise be silently dropped (audit finding D). Populated
-     * alongside `implementsSpecs`, never overlapping with it.
-     */
-    unanchoredImplements: string[];
-}
+import { LanguageParser } from './language-parser';
+import type { ScannedFile } from './scanned-file';
+export type { ScannedFile } from './scanned-file';
 /**
  * Directories that never contain hand-written source for the project under analysis.
  *
@@ -71,6 +38,13 @@ export declare const SKIP: Set<string>;
  */
 export declare function isUnderSkippedDir(p: unknown): boolean;
 /** Single source of truth for which file extensions CpgScanner ingests (REQ-124 gate 2). */
+/**
+ * Extension -> grammar. Exported because a SECOND consumer now reads data flow (the def-use symbol
+ * lane), and a second copy of this rule is a second thing to drift — the first wiring omitted the
+ * language entirely and parsed Python as TypeScript, which cost the other corpus 0.2376 -> 0.1741
+ * on the symbol axis before the instrument caught it.
+ */
+export declare function langForPath(name: string): 'python' | 'csharp' | 'java' | 'go' | 'rust' | 'cpp' | 'tsx' | 'typescript';
 export declare const SCANNABLE_EXTENSIONS: readonly [".ts", ".mts", ".cts", ".tsx", ".jsx", ".js", ".mjs", ".cjs", ".py", ".cs", ".java", ".go", ".rs", ".cpp", ".cc", ".cxx", ".hpp", ".hh", ".h"];
 export { TEST_FILE_PATTERNS, isTestFile } from './test-files';
 export declare class CpgScanner {

package/dist/holmes/cpg/cpg-scanner.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CpgScanner = exports.isTestFile = exports.TEST_FILE_PATTERNS = exports.SCANNABLE_EXTENSIONS = exports.SKIP = void 0;
 exports.isUnderSkippedDir = isUnderSkippedDir;
+exports.langForPath = langForPath;
 // @implements A-SPEC-208
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -109,6 +110,28 @@ function isVendorDir(dir) {
 // Anchor parsing (incl. wrong-kind detection) moved to the shared comma-list parser in
 // rtm/anchor-ids (A-SPEC-503.1) — the local single-capture regexes dropped every id after a comma.
 /** Single source of truth for which file extensions CpgScanner ingests (REQ-124 gate 2). */
+// @implements A-SPEC-573.4
+/**
+ * Extension -> grammar. Exported because a SECOND consumer now reads data flow (the def-use symbol
+ * lane), and a second copy of this rule is a second thing to drift — the first wiring omitted the
+ * language entirely and parsed Python as TypeScript, which cost the other corpus 0.2376 -> 0.1741
+ * on the symbol axis before the instrument caught it.
+ */
+function langForPath(name) {
+    if (/\.py$/.test(name))
+        return 'python';
+    if (/\.cs$/.test(name))
+        return 'csharp';
+    if (/\.java$/.test(name))
+        return 'java';
+    if (/\.go$/.test(name))
+        return 'go';
+    if (/\.rs$/.test(name))
+        return 'rust';
+    if (/\.(cpp|cc|cxx|hpp|hh|h)$/.test(name))
+        return 'cpp';
+    return TSX_GRAMMAR_RE.test(name) ? 'tsx' : 'typescript';
+}
 exports.SCANNABLE_EXTENSIONS = ['.ts', '.mts', '.cts', '.tsx', '.jsx', '.js', '.mjs', '.cjs', '.py', '.cs', '.java', '.go', '.rs', '.cpp', '.cc', '.cxx', '.hpp', '.hh', '.h'];
 const SCANNABLE_RE = /\.(ts|mts|cts|tsx|jsx|js|mjs|cjs|py|cs|java|go|rs|cpp|cc|cxx|hpp|hh|h)$/;
 // The test-file table moved to ./test-files, so the PreToolUse phase gate can read the SAME rules
@@ -118,6 +141,8 @@ var test_files_1 = require("./test-files");
 Object.defineProperty(exports, "TEST_FILE_PATTERNS", { enumerable: true, get: function () { return test_files_1.TEST_FILE_PATTERNS; } });
 Object.defineProperty(exports, "isTestFile", { enumerable: true, get: function () { return test_files_1.isTestFile; } });
 const test_files_2 = require("./test-files");
+// @implements A-SPEC-574.3 — a plain import now: the cycle that forced a lazy require is gone.
+const scan_cache_1 = require("./scan-cache");
 const anchor_ids_1 = require("../rtm/anchor-ids");
 // .ts/.mts/.cts can contain TS type-assertion syntax (`<T>x`, arrow-generics)
 // that the 'tsx' grammar misreads as JSX, so they must stay on 'typescript'.
@@ -208,7 +233,7 @@ class CpgScanner {
                         // C++ grammar parses plain C headers acceptably for our lexical
                         // symbol walk, and disambiguating a bare `.h` between C and C++
                         // is out of scope for this slice.
-                        const lang = /\.py$/.test(e.name) ? 'python' : (/\.cs$/.test(e.name) ? 'csharp' : (/\.java$/.test(e.name) ? 'java' : (/\.go$/.test(e.name) ? 'go' : (/\.rs$/.test(e.name) ? 'rust' : (/\.(cpp|cc|cxx|hpp|hh|h)$/.test(e.name) ? 'cpp' : (TSX_GRAMMAR_RE.test(e.name) ? 'tsx' : 'typescript'))))));
+                        const lang = langForPath(e.name);
                         // @implements A-SPEC-503.1 — comma-listed anchors: the old single-capture regexes
                         // dropped every id after the first (C12), and a wrong-kind id in second position was
                         // invisible to the warning. Both consumers now ride the shared list parser.
@@ -221,8 +246,7 @@ class CpgScanner {
                         const dataflow = () => (this.opts.dataflow ? this.parser.extractDataFlow(code, lang) : undefined);
                         // N7 incremental: on a content-hash hit, reuse cached symbols and skip the parse.
                         if (this.cache) {
-                            const { ScanFileCache } = require('./scan-cache');
-                            const h = ScanFileCache.hashOf(code);
+                            const h = scan_cache_1.ScanFileCache.hashOf(code);
                             const hit = this.cache.get(sourcePath, h);
                             // @implements A-SPEC-140.1
                             // A hit written by a scan that did NOT extract data-flow cannot satisfy one that does:

package/dist/holmes/cpg/cycle-detect.d.ts

@@ -0,0 +1,87 @@
+export type EdgeKind = 'type-erasable' | 'lazy-require' | 'eager-value';
+export interface CycleEdge {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+}
+export interface Cycle {
+    /** The files in the cycle, sorted, so two runs report it the same way. */
+    files: string[];
+    edges: CycleEdge[];
+    /** True unless EVERY edge holding the cycle together is erased at compile time. */
+    runtime: boolean;
+}
+/**
+ * What survives compilation for one import edge.
+ *
+ * Deliberately conservative: a shape this cannot read is `eager-value`, never `type-erasable`.
+ * Reporting "this disappears at compile time" about something we did not understand is the one
+ * error that silently deletes a real cycle from the count.
+ */
+export declare function classifyImportEdge(source: string, specifier: string): EdgeKind;
+/**
+ * Strongly connected components of size > 1 — Tarjan, iterative order-independent output.
+ *
+ * A self-edge is not a cycle: a file importing itself is a parse artefact, not a design defect.
+ */
+export declare function detectCycles(edges: readonly CycleEdge[]): {
+    cycles: Cycle[];
+    runtimeCycles: number;
+};
+/**
+ * @implements A-SPEC-574.2
+ * The wording that ships with the advisory. Fixed here, not composed at the call site, so the one
+ * thing this surface must never claim cannot drift: it reports cycles that ALREADY exist among the
+ * declared files. What a design is about to create is not visible until the code is written.
+ */
+export declare const CYCLE_ADVISORY_NOTE: string;
+/**
+ * @implements A-SPEC-574.2
+ * Classify the edge `fromFile -> toFile` by finding the import statement that actually resolves to
+ * that target.
+ *
+ * Picking the statement by the target's BASENAME would classify the wrong import whenever two files
+ * share a name in different directories — which is ordinary in any tree with `util.ts` or
+ * `index.ts`. The specifier is resolved instead, the way the module system does it.
+ *
+ * A target no specifier in this source resolves to is `eager-value`: not finding it is not evidence
+ * that it disappears at compile time.
+ */
+export declare function classifyEdgeByTarget(source: string, fromFile: string, toFile: string): EdgeKind;
+export interface CycleFinding extends Cycle {
+    /** The declared files that put this cycle in front of the author. */
+    declared: string[];
+}
+/**
+ * @implements A-SPEC-574.2
+ * The cycles the DECLARED files are already in — read before the Files-to-Touch are frozen.
+ *
+ * This is not a prediction and must never be presented as one. Import edges come from scanning real
+ * source, so the cycle a design would CREATE does not exist to be seen at approval time; what can
+ * be seen is that a file the author is about to edit already sits in one. Selling the first as the
+ * second would be worse than silence.
+ *
+ * Calls `detectCycles` rather than computing its own: the advisory and the later verdict have to be
+ * the same function, or "what we warned" and "what we judge" drift apart (A-SPEC-572.1).
+ */
+export declare function cycleAdvisory(fttFiles: readonly string[], edges: readonly CycleEdge[]): CycleFinding[];
+export interface CycleViolation {
+    key: string;
+    files: string[];
+    detail: string;
+}
+/**
+ * @implements A-SPEC-574.4
+ * The runtime cycles nobody allowed — a RATCHET, not an absolute zero.
+ *
+ * Absolute zero would keep every project with a legacy cycle from adopting the harness at all, and
+ * a rule that blocks adoption is a barrier rather than a rule. The escape is a NAME in the allow
+ * list, never a threshold: naming a cycle is a decision someone signed, while a threshold is a
+ * number anyone can move.
+ *
+ * Type-erasable-only cycles are not counted: TypeScript deletes those imports, so refusing them
+ * would refuse something that does not exist at runtime.
+ */
+export declare function cycleRatchetViolations(current: readonly Cycle[], allowed: readonly string[]): CycleViolation[];
+/** Order-independent identity for a cycle, so the allow list cannot be defeated by a reordering. */
+export declare function cycleKey(files: readonly string[]): string;

package/dist/holmes/cpg/cycle-detect.js

@@ -0,0 +1,251 @@
+"use strict";
+// @implements A-SPEC-574.1
+// The spec graph has been cycle-free by constitution (ART-2) since early on; the CODE graph never
+// was — the same repository enforcing acyclicity on one graph and not the other. Census 2026-09-08
+// on src/holmes: three cycles, whose edges are three different things. A rule that cannot tell them
+// apart is wrong on its first day: TypeScript ERASES a type-only import, so a "cycle" held up only
+// by those does not exist at runtime.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CYCLE_ADVISORY_NOTE = void 0;
+exports.classifyImportEdge = classifyImportEdge;
+exports.detectCycles = detectCycles;
+exports.classifyEdgeByTarget = classifyEdgeByTarget;
+exports.cycleAdvisory = cycleAdvisory;
+exports.cycleRatchetViolations = cycleRatchetViolations;
+exports.cycleKey = cycleKey;
+/**
+ * What survives compilation for one import edge.
+ *
+ * Deliberately conservative: a shape this cannot read is `eager-value`, never `type-erasable`.
+ * Reporting "this disappears at compile time" about something we did not understand is the one
+ * error that silently deletes a real cycle from the count.
+ */
+function classifyImportEdge(source, specifier) {
+    const quoted = specifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // A require() anywhere but the top level is the deliberate cycle-breaking idiom. Its PRESENCE is
+    // evidence the cycle was real enough that someone paid to work around it.
+    if (new RegExp(`require\\(\\s*['"]${quoted}['"]\\s*\\)`).test(source))
+        return 'lazy-require';
+    const decl = new RegExp(`^\\s*import\\s+(type\\s+)?([^;]*?)\\s+from\\s+['"]${quoted}['"]`, 'm').exec(source);
+    if (decl === null)
+        return 'eager-value';
+    if (decl[1] !== undefined)
+        return 'type-erasable'; // explicit `import type`
+    const clause = decl[2].trim();
+    // Namespace and default imports carry no per-binding information here — not readable, so eager.
+    const named = /^\{([^}]*)\}$/.exec(clause);
+    if (named === null)
+        return 'eager-value';
+    const bindings = named[1].split(',')
+        .map((b) => b.split(/\s+as\s+/).pop().trim())
+        .filter((b) => b !== '');
+    if (bindings.length === 0)
+        return 'eager-value';
+    // A binding used ONLY in type position is elided by TypeScript. "Type position" is approximated
+    // by the shapes a tree-sitter-free reader can see: after `:`, after `<`, in `extends`/`implements`,
+    // or as a type alias right-hand side. Anything else — a call, a `new`, a value reference — makes
+    // the whole edge eager, because one surviving binding keeps the import statement alive.
+    // Comments are stripped first. Measured on the real corpus: `scan-cache.ts` uses `ScannedFile`
+    // only in type positions, but a prose comment saying "the ScannedFile schema" made the whole edge
+    // read as a value use — the classifier was scoring English.
+    const body = stripComments(source.slice(decl.index + decl[0].length));
+    return bindings.every((b) => usedOnlyAsType(body, b)) ? 'type-erasable' : 'eager-value';
+}
+/** Line and block comments removed, so prose cannot look like code. String bodies are left alone. */
+function stripComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/^[^\n]*?\/\/[^\n]*$/gm, (line) => {
+        const at = line.indexOf('//');
+        return at < 0 ? line : line.slice(0, at);
+    });
+}
+function usedOnlyAsType(body, binding) {
+    const name = binding.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const uses = [...body.matchAll(new RegExp(`\\b${name}\\b`, 'g'))];
+    if (uses.length === 0)
+        return true; // imported and never used: nothing survives
+    return uses.every((m) => {
+        const before = body.slice(Math.max(0, m.index - 40), m.index);
+        const after = body.slice(m.index + binding.length, m.index + binding.length + 2);
+        if (/[:<|&,(]\s*$/.test(before) && !/\(\s*$/.test(before))
+            return true; // annotation, generic arg, union
+        if (/\b(extends|implements|satisfies)\s+$/.test(before))
+            return true;
+        if (/\btype\s+\w+\s*=\s*$/.test(before))
+            return true;
+        if (/^\s*[<[]/.test(after) && /[:<|&]\s*$/.test(before))
+            return true;
+        return false;
+    });
+}
+/**
+ * Strongly connected components of size > 1 — Tarjan, iterative order-independent output.
+ *
+ * A self-edge is not a cycle: a file importing itself is a parse artefact, not a design defect.
+ */
+function detectCycles(edges) {
+    const out = new Map();
+    const nodes = new Set();
+    for (const e of edges) {
+        if (e.from === e.to)
+            continue;
+        nodes.add(e.from);
+        nodes.add(e.to);
+        (out.get(e.from) ?? out.set(e.from, []).get(e.from)).push(e.to);
+    }
+    // Sorted adjacency and sorted roots: the same edge set in any input order yields the same result.
+    for (const [, list] of out)
+        list.sort();
+    let counter = 0;
+    const index = new Map();
+    const low = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const components = [];
+    const strongconnect = (v) => {
+        index.set(v, counter);
+        low.set(v, counter);
+        counter++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of out.get(v) ?? []) {
+            if (!index.has(w)) {
+                strongconnect(w);
+                low.set(v, Math.min(low.get(v), low.get(w)));
+            }
+            else if (onStack.has(w))
+                low.set(v, Math.min(low.get(v), index.get(w)));
+        }
+        if (low.get(v) === index.get(v)) {
+            const comp = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                comp.push(w);
+            } while (w !== v);
+            if (comp.length > 1)
+                components.push(comp.sort());
+        }
+    };
+    for (const v of [...nodes].sort())
+        if (!index.has(v))
+            strongconnect(v);
+    const cycles = components
+        .map((files) => {
+        const members = new Set(files);
+        // Sorted, not input order: `files` alone being sorted still let two runs of the same edge set
+        // differ, which the determinism case caught.
+        // Deduped: the scanner emits one edge per occurrence, so three `require('./y')` calls in one
+        // file said the same thing three times. Sorted, because `files` alone being sorted still let
+        // two runs of the same edge set differ.
+        const seen = new Set();
+        const held = edges
+            .filter((e) => e.from !== e.to && members.has(e.from) && members.has(e.to))
+            .filter((e) => {
+            const key = `${e.from}\u0000${e.to}\u0000${e.kind}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        })
+            .sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+        return {
+            files,
+            edges: held,
+            // One surviving edge is enough to keep the cycle at runtime; all-erasable means it is gone.
+            runtime: held.some((e) => e.kind !== 'type-erasable'),
+        };
+    })
+        .sort((a, b) => a.files[0].localeCompare(b.files[0]));
+    return { cycles, runtimeCycles: cycles.filter((c) => c.runtime).length };
+}
+/**
+ * @implements A-SPEC-574.2
+ * The wording that ships with the advisory. Fixed here, not composed at the call site, so the one
+ * thing this surface must never claim cannot drift: it reports cycles that ALREADY exist among the
+ * declared files. What a design is about to create is not visible until the code is written.
+ */
+exports.CYCLE_ADVISORY_NOTE = '선언한 파일이 이미 순환 안에 있습니다. 이것은 예측이 아닙니다 — '
+    + 'import 간선은 실제 소스에서 나오므로, 아직 쓰이지 않은 코드가 만들 순환은 여기서 보이지 않습니다.';
+/**
+ * @implements A-SPEC-574.2
+ * Classify the edge `fromFile -> toFile` by finding the import statement that actually resolves to
+ * that target.
+ *
+ * Picking the statement by the target's BASENAME would classify the wrong import whenever two files
+ * share a name in different directories — which is ordinary in any tree with `util.ts` or
+ * `index.ts`. The specifier is resolved instead, the way the module system does it.
+ *
+ * A target no specifier in this source resolves to is `eager-value`: not finding it is not evidence
+ * that it disappears at compile time.
+ */
+function classifyEdgeByTarget(source, fromFile, toFile) {
+    const dir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : '';
+    const target = toFile.replace(/(\/index)?\.[cm]?[jt]sx?$/, '');
+    for (const m of source.matchAll(/from\s+['"](\.[^'"]*)['"]|require\(\s*['"](\.[^'"]*)['"]\s*\)/g)) {
+        const spec = m[1] ?? m[2];
+        if (spec === undefined)
+            continue;
+        if (normalizeRelative(dir, spec) === target)
+            return classifyImportEdge(source, spec);
+    }
+    return 'eager-value';
+}
+/** POSIX-style join+normalize, without pulling in `path` — this module stays pure and portable. */
+function normalizeRelative(dir, spec) {
+    const parts = (dir === '' ? [] : dir.split('/')).concat(spec.split('/'));
+    const out = [];
+    for (const p of parts) {
+        if (p === '' || p === '.')
+            continue;
+        if (p === '..') {
+            out.pop();
+            continue;
+        }
+        out.push(p);
+    }
+    return out.join('/').replace(/(\/index)?\.[cm]?[jt]sx?$/, '');
+}
+/**
+ * @implements A-SPEC-574.2
+ * The cycles the DECLARED files are already in — read before the Files-to-Touch are frozen.
+ *
+ * This is not a prediction and must never be presented as one. Import edges come from scanning real
+ * source, so the cycle a design would CREATE does not exist to be seen at approval time; what can
+ * be seen is that a file the author is about to edit already sits in one. Selling the first as the
+ * second would be worse than silence.
+ *
+ * Calls `detectCycles` rather than computing its own: the advisory and the later verdict have to be
+ * the same function, or "what we warned" and "what we judge" drift apart (A-SPEC-572.1).
+ */
+function cycleAdvisory(fttFiles, edges) {
+    const declaredSet = new Set(fttFiles);
+    if (declaredSet.size === 0)
+        return [];
+    return detectCycles(edges).cycles
+        .map((c) => ({ ...c, declared: c.files.filter((f) => declaredSet.has(f)) }))
+        .filter((c) => c.declared.length > 0);
+}
+/**
+ * @implements A-SPEC-574.4
+ * The runtime cycles nobody allowed — a RATCHET, not an absolute zero.
+ *
+ * Absolute zero would keep every project with a legacy cycle from adopting the harness at all, and
+ * a rule that blocks adoption is a barrier rather than a rule. The escape is a NAME in the allow
+ * list, never a threshold: naming a cycle is a decision someone signed, while a threshold is a
+ * number anyone can move.
+ *
+ * Type-erasable-only cycles are not counted: TypeScript deletes those imports, so refusing them
+ * would refuse something that does not exist at runtime.
+ */
+function cycleRatchetViolations(current, allowed) {
+    const permitted = new Set(allowed);
+    return current
+        .filter((c) => c.runtime)
+        .map((c) => ({ key: cycleKey(c.files), files: c.files, detail: `import cycle: ${c.files.join(' -> ')} -> ${c.files[0]}` }))
+        .filter((v) => !permitted.has(v.key));
+}
+/** Order-independent identity for a cycle, so the allow list cannot be defeated by a reordering. */
+function cycleKey(files) {
+    return [...files].sort().join('|');
+}

package/dist/holmes/cpg/cycle-observation.d.ts

@@ -0,0 +1,65 @@
+import { type Cycle } from './cycle-detect';
+/**
+ * How many cycles one record lists before it starts counting instead.
+ *
+ * A record must not grow with the tree: a repository with a thousand cycles would otherwise write a
+ * thousand-entry line every turn, and the ledger this exists to make readable would be the thing
+ * that makes it unreadable. What is dropped is COUNTED, never silently cut.
+ */
+export declare const CYCLE_LIST_CAP = 50;
+/**
+ * One turn's observation — paths, integers and enums only.
+ *
+ * ADR-012's redaction rule is what lets this file be git-tracked at all: no prose, no command
+ * strings, no file content. `files` are the scanner's project-relative paths, which the impact and
+ * density ledgers already carry.
+ */
+export interface CycleObservationRecord {
+    ts: string;
+    mode: 'strict' | 'track' | 'off';
+    cycles: Array<{
+        key: string;
+        files: string[];
+        runtime: boolean;
+        edges: number;
+    }>;
+    /** Cycles beyond CYCLE_LIST_CAP: counted, so a truncation is never mistaken for a clean tree. */
+    cyclesOmitted: number;
+    /** Keys of the runtime cycles nobody allowed — the ratchet's verdict at this moment. */
+    violations: string[];
+    allowed: number;
+    scope: {
+        judged: string[];
+        unavailable: string[];
+    };
+    replica?: string;
+}
+/** The cycle evidence the Stop hook computes, in the shape it already holds it. */
+export interface CycleEvidence {
+    current: Cycle[];
+    allowed: string[];
+    mode: 'strict' | 'track' | 'off';
+    scope: {
+        judged: string[];
+        unavailable: string[];
+    };
+}
+/**
+ * Build the record. PURE — the clock is an argument, so a test can pin it and two callers cannot
+ * disagree about what "now" was.
+ *
+ * A CLEAN run produces a record too. That is the whole design: a false-positive RATE is violations
+ * over chances, and a ledger that only speaks when something is wrong records the numerator and
+ * throws the denominator away.
+ */
+export declare function buildCycleObservation(ev: CycleEvidence, ts: string): CycleObservationRecord;
+/**
+ * Append one record. Never throws, and never creates `.ax` where governance was not opted into
+ * (A-SPEC-191 §25 — the same refusal the approval queue makes).
+ *
+ * A failure returns `false` and changes nothing else: this is an OBSERVATION, and an observation
+ * that could alter a verdict would be a gate wearing a different name.
+ */
+export declare function appendCycleObservation(root: string, rec: CycleObservationRecord): boolean;
+/** Every replica's records, merged. A corrupt line is skipped, never fatal. */
+export declare function readCycleObservations(root: string): CycleObservationRecord[];