@holmes-lab/holmes-kit 0.25.0 → 0.26.0

package/dist/holmes/hooks/stop.js

@@ -56,6 +56,8 @@ exports.decideStopGuard = decideStopGuard;
 exports.__setWiredSpecsForTest = __setWiredSpecsForTest;
 exports.guardCountOrZero = guardCountOrZero;
 exports.readGuardCount = readGuardCount;
+exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
+exports.scanCodeCycles = scanCodeCycles;
 exports.writeGuardCount = writeGuardCount;
 const fs = __importStar(require("node:fs"));
 // @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
@@ -88,6 +90,8 @@ const test_files_1 = require("../cpg/test-files");
 const ci_runs_1 = require("../project/ci-runs");
 const dist_freshness_1 = require("../project/dist-freshness");
 const analysis_currency_1 = require("../project/analysis-currency");
+const forbidden_edges_1 = require("../cpg/forbidden-edges");
+const forbidden_edge_report_1 = require("../cpg/forbidden-edge-report");
 // @implements A-SPEC-660 — the I/O half of the known-defect marker: walk the workspace's test files
 // (the same directory rule and test predicate ART-4's anchor scan uses), parse each for markers,
 // judge them against the injected clock. A walk that cannot START is NO SIGNAL (undefined) — never
@@ -699,6 +703,15 @@ function evaluateStop(specs, evidence) {
         if (detail)
             tracked = [...(tracked ?? []), { article: 'ANALYSIS', detail }];
     }
+    // @implements A-SPEC-693 — the declared architecture's verdict rides the same non-blocking channel.
+    // Blocking is the pre-edit gate's job and an expired baseline is never a block (owner decision,
+    // 2026-09-19); what was missing is that nobody could SEE a violation, an expiry or an unjudged
+    // language. Never enters `problems`.
+    if (evidence?.forbiddenEdges) {
+        const t = (0, forbidden_edge_report_1.forbiddenEdgeStatusLines)(evidence.forbiddenEdges).map((detail) => ({ article: 'ARCH', detail }));
+        if (t.length)
+            tracked = [...(tracked ?? []), ...t];
+    }
     // @implements A-SPEC-683 — the vector-coverage line rides the same non-blocking channel. It is a
     // STRING here, not a verdict object: the hook read what the refresh child wrote and has nothing
     // to judge. An absent verdict already reads as "not run" inside coverageStopLine.
@@ -1018,6 +1031,120 @@ function readGuardCount(sessionId) {
  * Exported for the §19 race discriminator: the persistence layer was the untested half (round-11),
  * and a test that can only reach it through a spawned hook cannot pin what the lock does.
  */
+/**
+ * @implements A-SPEC-688
+ * Type erasure is a TypeScript fact, not a universal one.
+ *
+ * `classifyEdgeByTarget` reads TS syntax to decide whether an import survives into the emit. Python,
+ * Go, Java, C#, Rust and C++ have no erasure — every import there is an eager runtime dependency —
+ * so running a TS-syntax detector over their source can only mislabel. REQ-574 sorted cycles into
+ * (a) type-erasable, (b) lazy require and (c) eager value; category (a) does not exist in these
+ * languages, so the classification is not consulted and the edge is eager by construction.
+ */
+// @implements A-SPEC-693 — the gate is "can the classifier READ this syntax", not "does this language
+// erase types". The classifier reads `require()` and `from`, which is the whole JS family; gating on
+// erasure alone switched it off for `.js/.cjs/.mjs/.jsx` and REQ-574's category (b), lazy require,
+// stopped being recorded there. The other languages stay eager by construction, as above.
+const CLASSIFIER_READS = /\.[cm]?[jt]sx?$/;
+function kindOfEdge(text, from, to) {
+    return CLASSIFIER_READS.test(from) ? (0, cycle_detect_1.classifyEdgeByTarget)(text, from, to) : 'eager-value';
+}
+/**
+ * @implements A-SPEC-693
+ * The scan-wide forbidden-edge judgement, over the SAME rules the pre-edit gate reads: approved
+ * C-SPECs only, rules and baselines out of one parse of one section.
+ *
+ * Returns `undefined` when no rule is declared — the project never adopted this, so it pays nothing
+ * and hears nothing. The scan is handed in rather than made here: the Stop hook already scans once a
+ * turn for the cycle ratchet, and scanning is that hook's dominant cost.
+ */
+function collectForbiddenEdgeJudgement(specs, scanned, now) {
+    const rules = [];
+    const baselines = [];
+    for (const sp of specs) {
+        if (sp.type !== 'C-SPEC' || sp.status !== 'approved')
+            continue;
+        const parsed = (0, forbidden_edges_1.parseForbiddenEdges)(sp.sections?.['Forbidden Edges'] ?? '');
+        rules.push(...parsed.rules);
+        baselines.push(...parsed.baselines);
+    }
+    if (rules.length === 0)
+        return undefined;
+    return (0, forbidden_edges_1.judgeForbiddenEdges)(scanned, rules, { baselines, now });
+}
+/**
+ * @implements A-SPEC-688
+ * The code graph's cycles, judged where the code exists — extracted from the hook body so the
+ * judgement is observable without driving a whole Stop turn.
+ *
+ * Returns `undefined` when the scan could not run at all. That is NOT "no cycles": the caller must
+ * keep the article silent rather than report a clean tree, because "we could not look" and "there
+ * is nothing there" are different facts (REQ-574).
+ *
+ * @implements A-SPEC-693 — `shared` is a scan the caller already made. When given it is BELIEVED
+ * and no second scan runs, so one turn pays for one scan however many judgements read it.
+ */
+function scanCodeCycles(root, shared) {
+    try {
+        const { CpgScanner } = require('../cpg/cpg-scanner');
+        const { createImportResolver } = require('../cpg/import-resolver');
+        const scanned = shared ?? new CpgScanner().scan(root, root);
+        // The resolver the graph builder uses. Re-deriving it here is what made seven language
+        // families read as `unavailable` while the tree could already resolve them.
+        const resolver = createImportResolver(scanned);
+        const edges = [];
+        const judged = new Set();
+        const sawImports = new Set();
+        for (const f of scanned) {
+            const ext = f.sourcePath.slice(f.sourcePath.lastIndexOf('.'));
+            let text = '';
+            try {
+                text = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            let sawImport = false;
+            for (const e of f.edges ?? []) {
+                if (e.rel !== 'imports' || !e.to)
+                    continue;
+                sawImport = true;
+                // Go: a package specifier names every file of the package, so one specifier is many edges.
+                // The ratchet must see the same graph the builder does, or the two disagree about cycles.
+                const targets = [...resolver.fanOut(f.sourcePath, e.to)];
+                const single = targets.length === 0 ? resolver.resolve(f.sourcePath, e.to) : null;
+                if (single !== null)
+                    targets.push(single);
+                for (const to of targets) {
+                    if (to === f.sourcePath)
+                        continue;
+                    edges.push({ from: f.sourcePath, to, kind: kindOfEdge(text, f.sourcePath, to) });
+                    judged.add(ext);
+                }
+            }
+            // A file whose imports are all bare specifiers is not evidence that its LANGUAGE is
+            // unresolvable — subtract the judged set at the end instead of marking per file, or one
+            // such file makes the whole language read as unjudged (measured: `.ts` and `.js` landed in
+            // both lists).
+            if (sawImport)
+                sawImports.add(ext);
+        }
+        return {
+            current: (0, cycle_detect_1.detectCycles)(edges).cycles,
+            allowed: [],
+            mode: 'track',
+            // Unjudged = saw imports, resolved none, anywhere. Naming these is the difference between
+            // "no cycles" and "no cycles in the languages we could follow".
+            scope: {
+                judged: [...judged].sort(),
+                unavailable: [...sawImports].filter((e) => !judged.has(e)).sort(),
+            },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 function writeGuardCount(sessionId, n) {
     // @implements A-SPEC-191 §19 — no project, no state. Minting `<cwd>/.ax` to hold a counter is how
     // the gate lost the project in the first place; returning false puts the caller on the stateless
@@ -1145,56 +1272,33 @@ if (require.main === module) {
             // import edge starts from. Fail-open in every direction: any error leaves the article silent,
             // because "we could not look" must never be reported as "there is nothing there".
             let cycles;
+            // @implements A-SPEC-693 — ONE scan a turn, read by both judgements below. A scan that cannot
+            // run leaves both silent; neither judgement scans again on its own.
+            let sharedScan;
             try {
-                const root = stopProjectRoot();
                 const { CpgScanner } = require('../cpg/cpg-scanner');
-                const scanned = new CpgScanner().scan(root, root);
-                const known = new Set(scanned.map((f) => f.sourcePath));
-                const edges = [];
-                const judged = new Set();
-                const sawImports = new Set();
-                for (const f of scanned) {
-                    const ext = f.sourcePath.slice(f.sourcePath.lastIndexOf('.'));
-                    let text = '';
-                    try {
-                        text = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
-                    }
-                    catch {
-                        continue;
-                    }
-                    let sawImport = false;
-                    for (const e of f.edges ?? []) {
-                        if (e.rel !== 'imports' || !e.to)
-                            continue;
-                        sawImport = true;
-                        if (!e.to.startsWith('.'))
-                            continue;
-                        const base = path.posix.normalize(path.posix.join(path.posix.dirname(f.sourcePath), e.to));
-                        const to = ['.ts', '.tsx', '.js', '/index.ts'].map((x) => base + x).find((c) => known.has(c))
-                            ?? (known.has(base) ? base : null);
-                        if (to === null || to === f.sourcePath)
-                            continue;
-                        edges.push({ from: f.sourcePath, to, kind: (0, cycle_detect_1.classifyEdgeByTarget)(text, f.sourcePath, to) });
-                        judged.add(ext);
-                    }
-                    // A file whose imports are all bare specifiers is not evidence that its LANGUAGE is
-                    // unresolvable — subtract the judged set at the end instead of marking per file, or one
-                    // such file makes the whole language read as unjudged (measured: `.ts` and `.js` landed in
-                    // both lists).
-                    if (sawImport)
-                        sawImports.add(ext);
-                }
-                cycles = {
-                    current: (0, cycle_detect_1.detectCycles)(edges).cycles,
-                    allowed: [],
-                    mode: 'track',
-                    // Unjudged = saw imports, resolved none, anywhere. Naming these is the difference between
-                    // "no cycles" and "no cycles in the languages we could follow".
-                    scope: {
-                        judged: [...judged].sort(),
-                        unavailable: [...sawImports].filter((e) => !judged.has(e)).sort(),
-                    },
-                };
+                sharedScan = new CpgScanner().scan(stopProjectRoot(), stopProjectRoot());
+            }
+            catch {
+                sharedScan = undefined;
+            }
+            // Its OWN try, like the observation below: a fault in the architecture judgement must not
+            // discard the cycle evidence, nor the other way round.
+            let forbiddenEdges;
+            try {
+                if (sharedScan !== undefined)
+                    forbiddenEdges = collectForbiddenEdgeJudgement(specs, sharedScan, new Date());
+            }
+            catch {
+                forbiddenEdges = undefined;
+            }
+            try {
+                const root = stopProjectRoot();
+                if (sharedScan === undefined)
+                    throw new Error('cycle scan unavailable');
+                cycles = scanCodeCycles(root, sharedScan);
+                if (cycles === undefined)
+                    throw new Error('cycle scan unavailable');
                 // @implements A-SPEC-578.1 — record the observation the promotion criterion waits on.
                 // EVERY run, including a clean one: a false-positive rate is violations over chances, and a
                 // ledger that only speaks when something is wrong keeps the numerator and drops the
@@ -1322,7 +1426,7 @@ if (require.main === module) {
             catch {
                 semantic = undefined;
             }
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}) });
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}) });
             // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
             // the operator observes RED-first gaps before an owner promotes the posture to strict.
             // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty

package/dist/holmes/mcp/handlers/entity-integration.js

@@ -36,13 +36,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.renumberedMappingInputs = renumberedMappingInputs;
 exports.integrationSealTransitions = integrationSealTransitions;
 exports.createEntityIntegrationHandlers = createEntityIntegrationHandlers;
-// @implements A-SPEC-629
-// @implements A-SPEC-645
-// @implements A-SPEC-642
-// @implements A-SPEC-639
-// @implements A-SPEC-632
-// @implements A-SPEC-635
-const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const entity_store_1 = require("../../spec/entity-store");
 const root_1 = require("../../project/root");
@@ -129,7 +122,11 @@ function createEntityIntegrationHandlers(context) {
                 if (!context.storeRoot)
                     throw new entity_store_1.EntityStoreError('unsupported-store', 'Git integration requires a configured filesystem spec store.');
                 const bound = (0, entity_store_1.entityStoreBinding)(context.storeRoot);
-                if (a.root !== undefined && fs.realpathSync((0, root_1.resolveProjectRoot)(a.root, { includeGit: false }).root) !== bound.root)
+                // @implements A-SPEC-692 — `bound.root` is already canonical (A-SPEC-651.1 says so in as
+                // many words); the JS `fs.realpathSync` that stood on this side is not, and it leaves a
+                // Windows 8.3 alias spelled as it arrived. The same workspace then read as foreign.
+                // `sameCanonicalDirectory` exists for exactly this comparison — one canonicaliser, both sides.
+                if (a.root !== undefined && !(0, root_1.sameCanonicalDirectory)((0, root_1.resolveProjectRoot)(a.root, { includeGit: false }).root, bound.root))
                     throw new entity_store_1.EntityStoreError('foreign-workspace', 'The requested workspace differs from the configured store.');
                 const recoveryTarget = (plan) => 'entity-store:integrate-recover:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify(plan));
                 const requireStore = (plan) => {

package/dist/holmes/mcp/handlers/entity-renumber.js

@@ -34,10 +34,6 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEntityRenumberHandlers = createEntityRenumberHandlers;
-// @implements A-SPEC-628
-// @implements A-SPEC-642
-// @implements A-SPEC-639
-const fs = __importStar(require("node:fs"));
 const entity_store_1 = require("../../spec/entity-store");
 const entity_renumber_1 = require("../../spec/entity-renumber");
 const root_1 = require("../../project/root");
@@ -56,7 +52,10 @@ function createEntityRenumberHandlers(context) {
                 if (!context.storeRoot)
                     throw new entity_store_1.EntityStoreError('unsupported-store', 'Entity renumbering requires a configured filesystem spec store.');
                 const bound = (0, entity_store_1.entityStoreBinding)(context.storeRoot);
-                if (a.root !== undefined && fs.realpathSync((0, root_1.resolveProjectRoot)(a.root, { includeGit: false }).root) !== bound.root)
+                // @implements A-SPEC-692 — one canonicaliser on both sides; see the twin in
+                // `entity-integration.ts`. `bound.root` is canonical, so this side must be too, or an 8.3
+                // spelling of the SAME workspace is refused as foreign.
+                if (a.root !== undefined && !(0, root_1.sameCanonicalDirectory)((0, root_1.resolveProjectRoot)(a.root, { includeGit: false }).root, bound.root))
                     throw new entity_store_1.EntityStoreError('foreign-workspace', 'The requested workspace differs from the configured store.');
                 if (a.operation === 'recovery-plan')
                     return { ok: true, plan: (0, entity_renumber_transaction_1.planEntityRenumberRecovery)(context.storeRoot) };

package/dist/holmes/mcp/handlers/spec-authoring.js

@@ -42,6 +42,7 @@ const validator_1 = require("../../spec/validator");
 const spec_types_1 = require("../../spec/spec-types");
 const legacy_format_1 = require("../../spec/legacy-format");
 const write_target_1 = require("../../guardrail/write-target");
+const root_1 = require("../../project/root");
 const spec_id_guard_1 = require("../spec-id-guard");
 function createSpecAuthoringHandlers(context) {
     const { store, projectRootOf, resolver } = context;
@@ -105,8 +106,15 @@ function createSpecAuthoringHandlers(context) {
             // deployments refuse their own root. It is "you named a project that already exists, and my
             // store is not inside it", which is true whatever the specs directory is called.
             if (typeof reqRoot === 'string' && reqRoot !== '' && derivedForCreate === null && boundSpecsRoot !== null) {
+                // @implements A-SPEC-692 — BOTH sides of this comparison go through ONE canonicaliser.
+                // `projectRootOf` below already expands Windows 8.3 aliases (it ends in `canonicalPath`,
+                // i.e. `realpathSync.native`); the JS `fs.realpathSync` that used to stand here does not.
+                // So the same directory arrived under two spellings and the containment test said "another
+                // project": measured 2026-09-19, `C:\Users\SUNGNA~1\…\probe83` was refused while
+                // `C:\Users\SungNam Park\…\probe83` — the same directory — created. `change-source.ts`
+                // named this rule on 2026-08-23 after the identical failure; this is the same rule, here.
                 const real = (p2) => { try {
-                    return fs.realpathSync(p2);
+                    return (0, root_1.canonicalPath)(p2);
                 }
                 catch {
                     return path.resolve(p2);

package/dist/holmes/project/report-briefing.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The other end of the loop `holmes-kit report` opened.
+ *
+ * `report` writes every fingerprint this machine reported into `.ax/reports/reported.jsonl`, and
+ * until now nothing read it — the file's own header said it existed "for a briefing that does not
+ * exist yet". So the set accumulated on consumers' disks while the person who took the trouble to
+ * report a defect learned nothing when it was fixed.
+ *
+ * The match is a **local set intersection**: a file this machine wrote against a list that shipped
+ * in the package. Nothing is sent, nothing is requested, and there is no device id and no MAC
+ * address — a fingerprint identifies a DEFECT, not a person, which is why it can do this job at all.
+ *
+ * PURE. Every input is passed in; the caller owns the filesystem and the clock.
+ */
+import type { ResolvedReport } from './resolved-reports';
+export interface BriefingInput {
+    reported: ReadonlyArray<{
+        fingerprint: string;
+    }>;
+    resolved: ReadonlyArray<ResolvedReport>;
+    /** The version running now. */
+    installed: string;
+    /** Versions this installation's code contains — the installed one and everything before it. */
+    shipped: ReadonlyArray<string>;
+    announced: ReadonlySet<string>;
+}
+/**
+ * Lines to say, or none.
+ *
+ * A fingerprint is briefed when this machine reported it, the list resolves it, the resolving
+ * version is one this installation actually CONTAINS, and it has not been said before.
+ *
+ * "Contains" is membership in the shipped list, not semver arithmetic: the question is whether the
+ * consumer is running the fix, and a list of released versions answers that without this module
+ * having to know how versions compare.
+ */
+export declare function briefingLines(input: BriefingInput): string[];
+/** Tolerant: one unparseable line must not take the rest of the set down. */
+export declare function reportedFrom(raw: string | null): Array<{
+    fingerprint: string;
+}>;
+/**
+ * An unreadable marker yields an EMPTY set on purpose: the briefing then speaks. Hearing it twice
+ * is a smaller harm than a consumer who never hears it, and that is the rule the tier invitation
+ * follows for the same reason.
+ */
+export declare function announcedFrom(raw: string | null): Set<string>;
+export declare function announcedTo(set: ReadonlySet<string>): string;

package/dist/holmes/project/report-briefing.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.briefingLines = briefingLines;
+exports.reportedFrom = reportedFrom;
+exports.announcedFrom = announcedFrom;
+exports.announcedTo = announcedTo;
+/**
+ * Lines to say, or none.
+ *
+ * A fingerprint is briefed when this machine reported it, the list resolves it, the resolving
+ * version is one this installation actually CONTAINS, and it has not been said before.
+ *
+ * "Contains" is membership in the shipped list, not semver arithmetic: the question is whether the
+ * consumer is running the fix, and a list of released versions answers that without this module
+ * having to know how versions compare.
+ */
+function briefingLines(input) {
+    const mine = new Set(input.reported.map((r) => r.fingerprint).filter((f) => typeof f === 'string' && f !== ''));
+    const has = new Set([...input.shipped, input.installed]);
+    const out = [];
+    for (const r of input.resolved) {
+        if (!mine.has(r.fingerprint))
+            continue; // not ours — this is not a release-notes feed
+        if (!has.has(r.version))
+            continue; // not running the fix yet; the update notice owns that
+        if (input.announced.has(r.fingerprint))
+            continue; // once is once
+        out.push(`a defect you reported (${r.fingerprint}) was fixed in ${r.version} — ${r.note}`);
+    }
+    return out;
+}
+/** Tolerant: one unparseable line must not take the rest of the set down. */
+function reportedFrom(raw) {
+    if (raw === null)
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (t === '')
+            continue;
+        try {
+            const o = JSON.parse(t);
+            if (typeof o.fingerprint === 'string' && o.fingerprint !== '')
+                out.push({ fingerprint: o.fingerprint });
+        }
+        catch { /* a malformed line is skipped, never fatal */ }
+    }
+    return out;
+}
+/**
+ * An unreadable marker yields an EMPTY set on purpose: the briefing then speaks. Hearing it twice
+ * is a smaller harm than a consumer who never hears it, and that is the rule the tier invitation
+ * follows for the same reason.
+ */
+function announcedFrom(raw) {
+    if (raw === null)
+        return new Set();
+    try {
+        const o = JSON.parse(raw);
+        if (!Array.isArray(o.announced))
+            return new Set();
+        return new Set(o.announced.filter((x) => typeof x === 'string' && x !== ''));
+    }
+    catch {
+        return new Set();
+    }
+}
+function announcedTo(set) {
+    return JSON.stringify({ announced: [...set].sort() }, null, 2) + '\n';
+}

package/dist/holmes/project/resolved-reports.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Field reports this project has resolved, and the version that resolved them.
+ *
+ * A DATA MODULE rather than a JSON file: TypeScript compiles it into `dist/` automatically, so it
+ * ships with no change to `package.json`'s `files` and no build step anyone can forget.
+ *
+ * The fingerprint is the one that appeared in the report — `advisoryId`-shaped, the first 16 hex of
+ * a sha256 over the canonical report. It identifies a DEFECT, never a person or a machine.
+ *
+ * This list is kept alive by the publish ritual, not by a command: before cutting a release the
+ * playbook asks for the fingerprints that release resolved. A command nobody runs would leave this
+ * empty and the briefing permanently silent, and this repository already records six instruments
+ * that were built and never consumed.
+ */
+export interface ResolvedReport {
+    fingerprint: string;
+    version: string;
+    note: string;
+}
+export declare const RESOLVED_REPORTS: ReadonlyArray<ResolvedReport>;

package/dist/holmes/project/resolved-reports.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOLVED_REPORTS = void 0;
+exports.RESOLVED_REPORTS = [
+// Empty until a field report is resolved. The briefing is silent while it is, which is correct:
+// no consumer has reported anything this project has since fixed.
+];

package/dist/holmes/rtm/rtm-builder.js

@@ -46,6 +46,7 @@ exports.addDecisionEdges = addDecisionEdges;
 const path = __importStar(require("node:path"));
 const fs = __importStar(require("node:fs"));
 const language_capability_1 = require("../cpg/language-capability");
+const import_resolver_1 = require("../cpg/import-resolver");
 /**
  * @implements A-SPEC-281
  * Build one fact's provenance from the shared observation context plus what this call site knows.
@@ -429,146 +430,10 @@ function fsReadGoMod(p) {
     }
 }
 function addImportEdges(scanned, graph, opts) {
-    const known = new Set(scanned.map((f) => f.sourcePath));
-    const EXTENSIONS = ['', '.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs', '.jsx', '.py',
-        '/index.ts', '/index.js', '/__init__.py'];
-    const firstKnown = (base) => EXTENSIONS.map((ext) => `${base}${ext}`).find((candidate) => known.has(candidate)) ?? null;
-    // @implements A-SPEC-525.1 — the five languages' resolution rules, selected by the IMPORTING
-    // file's extension because resolution IS per-language semantics. The founding rule is unchanged
-    // everywhere: resolve only to files the scan actually contains; the ambiguous resolve to none.
-    const knownList = [...known];
-    const uniqueSuffix = (suffix) => {
-        const hits = knownList.filter((k) => k === suffix || k.endsWith(`/${suffix}`));
-        return hits.length === 1 ? hits[0] : null; // two files may not become a guess
-    };
-    // go.mod discovery: injected via opts when the caller knows it; otherwise walked up from the
-    // first Go file's ABSOLUTE path (bounded), so production builds resolve without extra wiring.
-    let goModCache;
-    const goModuleOf = () => {
-        if (opts?.goModule)
-            return opts.goModule;
-        if (goModCache !== undefined)
-            return goModCache ?? undefined;
-        goModCache = null;
-        const anyGo = scanned.find((f) => /\.go$/.test(f.sourcePath) && f.path);
-        if (anyGo) {
-            let dir = path.dirname(anyGo.path);
-            for (let hops = 0; hops < 12; hops++) {
-                try {
-                    const txt = fsReadGoMod(path.join(dir, 'go.mod'));
-                    if (txt !== null) {
-                        goModCache = txt;
-                        break;
-                    }
-                }
-                catch { /* keep walking */ }
-                const up = path.dirname(dir);
-                if (up === dir)
-                    break;
-                dir = up;
-            }
-        }
-        return goModCache ?? undefined;
-    };
-    const goPackage = (spec) => {
-        const mod = goModuleOf();
-        if (!mod || !(spec === mod || spec.startsWith(`${mod}/`)))
-            return []; // external, honestly
-        const dir = spec === mod ? '' : spec.slice(mod.length + 1);
-        const prefix = dir === '' ? '' : `${dir}/`;
-        return knownList.filter((k) => k.startsWith(prefix) && k.endsWith('.go')
-            && !k.endsWith('_test.go') && !k.slice(prefix.length).includes('/'));
-    };
-    const rustResolve = (fromFile, spec) => {
-        const segs = spec.split('::');
-        const head = segs.shift();
-        let baseDir;
-        if (head === 'crate') {
-            // the crate root is the src/ directory nearest above the importing file
-            const m = fromFile.match(/^(.*?src)\//);
-            baseDir = m ? m[1] : 'src';
-        }
-        else if (head === 'super') {
-            baseDir = path.posix.dirname(path.posix.dirname(fromFile));
-            while (segs[0] === 'super') {
-                // @implements A-SPEC-527.1 — super:: above the crate root is an rustc error; resolving
-                // it pinned '.' and produced edges to repo-root files (adversarial sweep). Refuse.
-                if (baseDir === '.' || baseDir === '/')
-                    return null;
-                segs.shift();
-                baseDir = path.posix.dirname(baseDir);
-            }
-        }
-        else if (head === 'self') {
-            baseDir = path.posix.dirname(fromFile);
-        }
-        else {
-            return null; // external crate
-        }
-        const tryPath = (parts) => {
-            if (parts.length === 0)
-                return null;
-            const base = path.posix.normalize(path.posix.join(baseDir, ...parts));
-            if (known.has(`${base}.rs`))
-                return `${base}.rs`;
-            if (known.has(`${base}/mod.rs`))
-                return `${base}/mod.rs`;
-            return null;
-        };
-        // the last segment may be an ITEM, not a module — drop it once and retry
-        return tryPath(segs) ?? tryPath(segs.slice(0, -1));
-    };
-    const resolve = (fromFile, spec) => {
-        // @implements A-SPEC-525.1 — language branches BEFORE the JS/Python-shaped fallthrough.
-        if (/\.go$/.test(fromFile))
-            return null; // Go fans out separately (a package is its files)
-        if (/\.rs$/.test(fromFile))
-            return rustResolve(fromFile, spec);
-        if (/\.java$/.test(fromFile))
-            return uniqueSuffix(`${spec.split('.').join('/')}.java`);
-        if (/\.cs$/.test(fromFile))
-            return uniqueSuffix(`${spec.split('.').join('/')}.cs`);
-        if (/\.(cpp|cc|cxx|hpp|h)$/.test(fromFile)) {
-            // @implements A-SPEC-527.1 — an ABSOLUTE include is not a repository coordinate: joining
-            // it into the repo frame let `#include "/etc/passwd"` match a coincidentally-shaped
-            // scanned file (adversarial sweep). Absolute means absolute; it resolves to nothing here.
-            if (spec.startsWith('/'))
-                return null;
-            // extension preserved: the dotted split below would butcher `util/env.h`
-            const relative = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), spec));
-            if (known.has(relative))
-                return relative;
-            return known.has(spec) ? spec : null; // repo-root-relative include
-        }
-        // @implements A-SPEC-406
-        // A specifier without a leading dot used to be refused outright, on the ground that it names an
-        // external package. That holds for `node:fs` and `js-yaml`; it does NOT hold for Python, which
-        // writes intra-repository modules absolutely — `from src.core.memory_audit import X`. Measured
-        // on the jarvis corpus: 1060 specifiers, 0 relative, 542 naming a file the scan already had, and
-        // 0 import edges in the graph. The whole import layer was missing for that language because the
-        // resolver's shape was JS's.
-        //
-        // The rule the original was written under is unchanged and is what makes this safe: resolve
-        // ONLY to a file the scan actually contains. `os.path` becomes `os/path.py`, which is in no
-        // scan, so it still emits nothing. Nothing is invented; the dotted form is simply also read.
-        if (!spec.startsWith('.')) {
-            if (spec.includes(':'))
-                return null; // `node:fs` and friends are never a repository path
-            return firstKnown(path.posix.normalize(spec.split('.').filter(Boolean).join('/')));
-        }
-        // @implements A-SPEC-289
-        // Python writes a relative import as `.b` / `..pkg.mod`, where the leading dots are LEVELS and
-        // the remaining dots are path separators — not the `./b` form JS uses. Treating `.b` as a path
-        // yields the literal name `.b`, which matches nothing. Detected by the absence of a slash: a
-        // specifier that already contains one is a JS-style path and is left alone.
-        let relative = spec;
-        if (!spec.includes('/')) {
-            const dots = spec.match(/^\.+/)[0].length;
-            const rest = spec.slice(dots).split('.').filter(Boolean).join('/');
-            relative = `${'../'.repeat(Math.max(0, dots - 1)) || './'}${rest}`;
-        }
-        return firstKnown(path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), relative)));
-    };
+    // @implements A-SPEC-688 — the resolution rules moved to `cpg/import-resolver` so the cycle
+    // ratchet consumes the SAME code instead of re-deriving a weaker copy. The rules themselves are
+    // unchanged; this call is where they used to be spelled out.
+    const { resolve, fanOut } = (0, import_resolver_1.createImportResolver)(scanned, { goModule: opts?.goModule });
     graph.transaction(() => {
         for (const f of scanned) {
             for (const e of f.edges ?? []) {
@@ -578,7 +443,7 @@ function addImportEdges(scanned, graph, opts) {
                 // language's semantics, not an invention), so one specifier fans out to each scanned
                 // file of the package directory.
                 if (/\.go$/.test(f.sourcePath)) {
-                    for (const target of goPackage(e.to)) {
+                    for (const target of fanOut(f.sourcePath, e.to)) {
                         graph.addNode(`FILE:${f.sourcePath}`, 'FILE', f.sourcePath, fact(opts, f.sourcePath, 'ast-scan', 1));
                         graph.addNode(`FILE:${target}`, 'FILE', target, fact(opts, target, 'ast-scan', 1));
                         graph.addEdge(`FILE:${f.sourcePath}`, `FILE:${target}`, 'imports', f.sourcePath, fact(opts, `${f.sourcePath} -> ${e.to}`, 'import-resolution', 1));