@holmes-lab/holmes-kit 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.19.0] - 2026-09-08
+
+### Added
+- **Cycle governance for the code graph** (REQ-574). The spec graph has been required to be acyclic
+  by constitution (ART-2) for a long time; the code graph never was, in the same repository. Now it
+  is governed at three moments, because each can do a different thing:
+  - **Guidance, before design** — the authoring playbooks carry "share types through a third module,
+    do not create cycles" (pinned by test, inherited by the installed skills). At approval time the
+    graph cannot see the cycle a design *would* create — import edges come from scanning real source
+    — so words are the only thing that works there.
+  - **Advisory, at design time** — `approval_status`'s `graphPreview` gains `cycles`: the cycles the
+    files you declared are **already** in, with each edge classified as `type-erasable` (TypeScript
+    deletes it — not a runtime cycle), `lazy-require` (a workaround someone already paid for) or
+    `eager-value`. The note says in words that this is not a prediction.
+  - **Ratchet, after the code exists** — the Stop hook's constitution gains ART-2's sibling on the
+    code graph. Ships in `track` (records, never blocks); `strict` promotion waits on the observation
+    ledger. Not absolute zero but a ratchet, and the escape is a **named exception**, never a
+    threshold — a project with legacy cycles must still be able to adopt the harness.
+- **Architecture observation beside the design-time advisory** (REQ-574 S4): `graphPreview` gains
+  `architecture` — lines, symbols, longest function, fan-in and fan-out for each declared file.
+  Numbers only: no grade, no threshold, no participation in any verdict (a test pins the absence of
+  such a field, because one would grow into the gate the measurement does not support).
+- **A symbol axis in the replay benchmark** (REQ-573 S3-instrument): commit-touched symbols are
+  derived from the parent-side changed lines, so a mechanism aimed at function-level selection can
+  finally be judged.
+- **Paired-power instrument** (REQ-573 S5): `editSetF1` and `pairedPower` report σ and the
+  minimum detectable effect at 80% power, so a verdict can state whether the difference it rests on
+  was large enough to detect.
+- **The publish procedure reaches the external doc surfaces** (REQ-575): after a successful release,
+  the repo README is synchronised to GitHub and the org profile README is **inspected** for
+  claim-vs-reality drift (never auto-corrected — positioning wording is a person's call). The target
+  is derived from `package.json`'s `repository`, never hardcoded, because this playbook installs
+  into consuming projects.
+
+### Changed
+- **Candidate admission narrowed to files that could be the answer** (REQ-573 S1). The commit-prose
+  channel admitted whatever git history named, so ledger JSONL, build baselines and CHANGELOG took
+  emission slots: measured over 12 real requests, **76 of 120 candidate slots (63.3%)** went to files
+  that cannot be the answer, one of them at the head of the list. History-derived candidates are now
+  restricted to files that could be source, and vendored trees are demoted the way the lexical path
+  already demotes them. Measured after: **0%**.
+- **`maintenance_analyze` candidates carry def-use-ranked symbols** (REQ-573 S3): inside a file the
+  search already found, the functions the request's terms reach through data flow come first.
+  Measured on this repository: symbol Top-10 recall **0.087 → 0.287**, precision **0.038 → 0.098**,
+  file-level axes unchanged, request latency +10.3%. On two other corpora it moved nothing — the
+  gain is conditional on the file layer already being right, and it is reported as conditional.
+- **Ambiguous call targets are preserved instead of dropped** (REQ-573 S4): a call whose name is
+  defined in several places now emits candidate edges on a new `calls_ambiguous` relation
+  (22.6% of resolved edges were being discarded). Every certainty-requiring reader filters on
+  `rel='calls'`, so gates and advisories are unaffected. **The PPR weight for it stays 0**: the
+  weighted arm was measured on two corpora and rejected (one unchanged, one monotonically worse).
+
+### Fixed
+- **Three import cycles in this repository, and the workarounds they forced** (REQ-574 S2). All
+  three had the same cure — move the shared thing to a module neither side owns — and two lazy
+  `require()` calls existed only to dodge them. Their absence is now the evidence the cycles are gone.
+- **The benchmark measured a pipeline that does not ship** (REQ-573 S3-instrument): the replay
+  narrowed the commit-prose boost on its own, a filter the product never had, which is why a defect
+  worth 63.3% of the product's emitted slots read as six-decimal no movement. Removing it moved four
+  pins (recorded before/after in the commit); the product did not change.
+
+### Notes
+- `RRF_K` was swept over {5, 10, 20, 60} on two corpora and **kept at 60**: no value improved both
+  corpora on every metric. Worth recording is that the sweep on the *unrepaired* benchmark said
+  k=10 dominated — fixing the instrument reversed the adoption decision.
+- Judgement axis, measured: harness+judgement 0.2946 vs grep+judgement 0.2867 in edit-set F1, with
+  σ 0.1113 and a minimum detectable effect of 0.0551. The observed 0.0080 is a seventh of what this
+  design could detect, so the advantage is **not distinguishable from zero** at n=32.
+
 ## [0.18.0] - 2026-09-08
 
 Decisions become governed. A consuming project's operational decisions had been leaking into agent

package/README.md

@@ -16,6 +16,9 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 🔁 **Import cycles are governed, at the three moments that can each do something** *(new in 0.19.0)*: the spec graph has been required to be acyclic since early on; the code graph now is too. **Guidance** reaches the agent before it designs (the authoring playbooks say "share types through a third module", pinned by test). **A design-time advisory** — `approval_status`'s `graphPreview` gains `cycles` — names the cycles your declared files are *already* in, with each edge classified as `type-erasable` (TypeScript deletes it, so it is not a runtime cycle), `lazy-require` (a workaround someone already paid for) or `eager-value`; the note says in words that this is **not** a prediction, because at approval time the code that would create a cycle does not exist yet. **A ratchet** in the Stop hook's constitution catches new cycles after the code is written — shipped in `track` (records, never blocks), and the escape is a **named exception**, never a threshold, so a project carrying legacy cycles can still adopt the harness. This repository went from three cycles to zero, and the two lazy `require()` workarounds they forced are gone.
+- 📐 **Size and fan-in, shown but never judged** *(new in 0.19.0)*: the same design-time advisory carries `architecture` — lines, symbols, longest function, fan-in and fan-out for each declared file. Numbers only: no grade, no threshold, no participation in any verdict. A test pins the *absence* of a severity field, because one would grow into the gate the evidence does not support (the size/defect correlation in the literature is largely "there is more code"). Practitioners still reject inspecting more than five things, so the number is worth seeing — the person decides.
+- 🎯 **Candidates you could actually act on** *(new in 0.19.0)*: the commit-history channel used to admit whatever git named, so ledger files and build baselines took emission slots — measured, **63.3% of candidate slots** went to files that cannot be the answer, one at the head of the list. Now history-derived candidates must be able to be source, vendored trees are demoted, and inside a file the search already found, def-use ranking puts the functions the request reaches through data flow first (symbol Top-10 recall 0.087 → 0.287 on this repository; unchanged on two others, and reported as conditional rather than general).
 - 🧭 **The graph speaks BEFORE you commit to a scope** *(new in 0.18.0)*: the read-only `approval_status` now also answers `graphPreview` — `impact` (files that call INTO your declared Files-to-Touch from outside it, each anchor carrying its spec's intent sentence) and `density` (anchor-dense files inside the scope) — computed by the **same functions the sealing advisory uses**, so the preview can never disagree with the seal. Read the impact, then widen the declaration, narrow the design, or leave it knowingly; the authoring playbooks carry the step (pinned by test) and it stays a discipline, not a gate. Root-cause work gets the other half: `maintenance_analyze` candidates ride with `decisionContext` — the ADRs constraining that file and each decision's own sentence — which is the order a person diagnoses in (what broke, then why it was left this way). Both are information only: value tests pin that no ranking, score or gate reads them.
 - 📜 **ADR as a first-class governed document** *(new in 0.18.0)*: decisions stop leaking into agent memory outside the gate (a measured incident on a consuming project drove this). `spec_create(type: "ADR")` scaffolds a root decision document (Context / Decision / Consequences / Alternatives, `decided`/`decider`) under the store's full authoring governance — validate, `spec_approve` seal, ledger, tamper-block — with its **own number space** (your existing `ADR-0001` just works) and a **hitl-only seal** (autonomy never self-approves a decision). Store ADRs join the existing decision surface with zero new edge kinds: `ADR-XXXX` citations in specs/code become `constrained_by` edges, `supersedes` chains link, the graph's SPEC:ADR node carries the Decision line as its intent summary, and legacy `.ax/decisions/` entries coexist (store wins on id collision). A migration guide ships at `docs/adr-migration.md`.
 

package/dist/.build-id

@@ -1 +1 @@
-cc24589-mtrjegw0
+0043954-mtspy09e

package/dist/holmes/cli/release-docs.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The GitHub target this project publishes to, read from `package.json`.
+ *
+ * Derived, never hardcoded: this playbook is installed INTO consuming projects, so a literal
+ * `owner/repo` here would make someone else's release overwrite ours. When the field is missing,
+ * malformed, or points somewhere other than GitHub the answer is `null` — the caller then SKIPS and
+ * says so, which is the honest outcome. A fallback would be a guess wearing a default's clothes.
+ */
+export declare function repoTargetFrom(pkg: unknown): {
+    owner: string;
+    repo: string;
+} | null;
+export interface ProfileDriftInput {
+    profileText: string;
+    /** The version live on the registry, or null when the lookup failed. */
+    npmVersion: string | null;
+    profilePushedAt: string | null;
+    lastReleaseAt: string | null;
+}
+/**
+ * Sentences a person should read before the next release — never a rewrite, and never a grade.
+ *
+ * No severity, no score: attaching one is how an advisory becomes a gate, and the wording of a
+ * positioning document is not something a gate should decide. An empty list is a real answer, which
+ * is why the "current document" case is tested — a check that always speaks is not a check.
+ */
+export declare function profileDriftFindings(input: ProfileDriftInput): string[];

package/dist/holmes/cli/release-docs.js

@@ -0,0 +1,68 @@
+"use strict";
+// @implements A-SPEC-575.1
+// Publishing reaches surfaces the release procedure never knew about. This repository has NO GitHub
+// remote — origin is a local gitea — so three releases went out while the README that npm's
+// `homepage` points at stayed frozen at 2026-08-31, and the org profile still said the project was
+// a walking skeleton under construction.
+//
+// Two surfaces, two treatments. The repo README is a COPY of the local one (section-for-section
+// identical, measured), so it is synchronised. The profile README is an independent positioning
+// document, so it is only INSPECTED — rewriting someone's positioning is not a release step.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.repoTargetFrom = repoTargetFrom;
+exports.profileDriftFindings = profileDriftFindings;
+/**
+ * The GitHub target this project publishes to, read from `package.json`.
+ *
+ * Derived, never hardcoded: this playbook is installed INTO consuming projects, so a literal
+ * `owner/repo` here would make someone else's release overwrite ours. When the field is missing,
+ * malformed, or points somewhere other than GitHub the answer is `null` — the caller then SKIPS and
+ * says so, which is the honest outcome. A fallback would be a guess wearing a default's clothes.
+ */
+function repoTargetFrom(pkg) {
+    const repository = pkg?.repository;
+    const url = typeof repository === 'string' ? repository
+        : typeof repository?.url === 'string'
+            ? repository.url
+            : null;
+    if (url === null)
+        return null;
+    // The three shapes npm accepts, plus the `git+` prefix and the optional `.git` suffix.
+    const m = /^(?:git\+)?(?:https?:\/\/github\.com\/|git@github\.com:)([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(url.trim());
+    return m === null ? null : { owner: m[1], repo: m[2] };
+}
+/** Phrases that claim the project has not shipped yet. */
+const PRE_RELEASE_CLAIMS = ['early stage', 'under construction', 'walking-skeleton', 'walking skeleton', 'bootstrap'];
+/**
+ * Sentences a person should read before the next release — never a rewrite, and never a grade.
+ *
+ * No severity, no score: attaching one is how an advisory becomes a gate, and the wording of a
+ * positioning document is not something a gate should decide. An empty list is a real answer, which
+ * is why the "current document" case is tested — a check that always speaks is not a check.
+ */
+function profileDriftFindings(input) {
+    const out = [];
+    const text = input.profileText.toLowerCase();
+    // Only run the maturity check when the registry actually answered. Not knowing must not turn into
+    // a claim about what the document gets wrong.
+    if (input.npmVersion !== null && isShipped(input.npmVersion)) {
+        const claimed = PRE_RELEASE_CLAIMS.filter((p) => text.includes(p));
+        if (claimed.length > 0) {
+            out.push(`profile README still claims pre-release status (${claimed.join(', ')}) `
+                + `while npm has ${input.npmVersion} — the claim is no longer true.`);
+        }
+    }
+    if (input.profilePushedAt !== null && input.lastReleaseAt !== null
+        && Date.parse(input.profilePushedAt) < Date.parse(input.lastReleaseAt)) {
+        out.push(`profile README (${input.profilePushedAt}) is older than the last release `
+            + `(${input.lastReleaseAt}) — it has not been looked at across at least one shipment.`);
+    }
+    return out;
+}
+/** A version that means "this shipped" — anything at or past 0.1.0. */
+function isShipped(version) {
+    const m = /^(\d+)\.(\d+)\./.exec(version);
+    if (m === null)
+        return false;
+    return Number(m[1]) > 0 || Number(m[2]) > 0;
+}

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;