@holmes-lab/holmes-kit 0.35.9 → 0.35.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +1 -0
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cpg/cpg-scanner.d.ts +10 -0
  5. package/dist/holmes/cpg/cpg-scanner.js +37 -3
  6. package/dist/holmes/cpg/scan-cache.d.ts +1 -1
  7. package/dist/holmes/cpg/scan-cache.js +6 -1
  8. package/dist/holmes/cpg/scanned-file.d.ts +42 -0
  9. package/dist/holmes/cpg/ts-call-resolution.d.ts +46 -0
  10. package/dist/holmes/cpg/ts-call-resolution.js +252 -0
  11. package/dist/holmes/governance/constitution.d.ts +5 -0
  12. package/dist/holmes/governance/constitution.js +1 -1
  13. package/dist/holmes/hooks/stop.d.ts +28 -0
  14. package/dist/holmes/hooks/stop.js +69 -6
  15. package/dist/holmes/mcp/handlers/graph-operations.js +9 -3
  16. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +29 -4
  17. package/dist/holmes/mcp/handlers/requirement-triage.js +51 -4
  18. package/dist/holmes/mcp/handlers.d.ts +14 -4
  19. package/dist/holmes/mcp/handlers.js +9 -2
  20. package/dist/holmes/mcp/maintenance-analyze.d.ts +8 -0
  21. package/dist/holmes/mcp/maintenance-analyze.js +69 -4
  22. package/dist/holmes/review/graph-resolution.d.ts +61 -0
  23. package/dist/holmes/review/graph-resolution.js +158 -0
  24. package/dist/holmes/review/requirement-triage.js +3 -2
  25. package/dist/holmes/review/run-replay.d.ts +49 -0
  26. package/dist/holmes/review/run-replay.js +132 -13
  27. package/dist/holmes/review/semantic-retrieval.d.ts +2 -0
  28. package/dist/holmes/review/semantic-retrieval.js +4 -1
  29. package/dist/holmes/rtm/anchor-binding.d.ts +34 -0
  30. package/dist/holmes/rtm/anchor-binding.js +43 -0
  31. package/dist/holmes/rtm/anchor-history.d.ts +39 -0
  32. package/dist/holmes/rtm/anchor-history.js +97 -0
  33. package/dist/holmes/rtm/anchor-ids.d.ts +21 -0
  34. package/dist/holmes/rtm/anchor-ids.js +51 -5
  35. package/dist/holmes/rtm/localize.d.ts +7 -0
  36. package/dist/holmes/rtm/localize.js +11 -2
  37. package/dist/holmes/rtm/rtm-builder.d.ts +12 -0
  38. package/dist/holmes/rtm/rtm-builder.js +64 -2
  39. package/dist/holmes/rtm/rtm-graph.d.ts +11 -0
  40. package/dist/holmes/rtm/rtm-graph.js +20 -0
  41. package/package.json +1 -1
@@ -0,0 +1,61 @@
1
+ export interface GraphRows {
2
+ nodes: Array<{
3
+ id: string;
4
+ kind: string;
5
+ sourcePath: string | null;
6
+ }>;
7
+ edges: Array<{
8
+ src: string;
9
+ dst: string;
10
+ rel: string;
11
+ derivation: string | null;
12
+ observedAt: string | null;
13
+ validUntil: string | null;
14
+ evidenceDigest: string | null;
15
+ }>;
16
+ }
17
+ export interface GraphResolution {
18
+ nodesByKind: Record<string, number>;
19
+ edgesByRel: Record<string, number>;
20
+ specLink: {
21
+ linkedSymbols: number;
22
+ filesWithTwoOrMore: number;
23
+ uniformFiles: number;
24
+ uniformShare: number | null;
25
+ specsPerSymbolMedian: number | null;
26
+ specsPerSymbolMax: number | null;
27
+ siteBoundEdges: number;
28
+ };
29
+ verification: {
30
+ caseNodes: number;
31
+ criterionNodes: number;
32
+ executesEdges: number;
33
+ verifiesEdges: number;
34
+ };
35
+ calls: {
36
+ resolved: number;
37
+ ambiguous: number;
38
+ ambiguousShare: number | null;
39
+ };
40
+ flowEdges: number;
41
+ provenance: {
42
+ edges: number;
43
+ withObservedAt: number;
44
+ withValidUntil: number;
45
+ withEvidenceDigest: number;
46
+ };
47
+ }
48
+ export type GraphRowsRead = {
49
+ ok: true;
50
+ rows: GraphRows;
51
+ } | {
52
+ ok: false;
53
+ reason: 'missing' | 'not-a-graph-store';
54
+ };
55
+ export declare function graphResolution(rows: GraphRows): GraphResolution;
56
+ /**
57
+ * The rows of a graph store, read without ever writing to it. `fileMustExist` matters: the driver
58
+ * creates an empty database for an absent path, and an empty store would then read as "a graph with
59
+ * nothing in it" — the zero result this instrument must never report for a missing one.
60
+ */
61
+ export declare function readGraphRows(dbPath: string): GraphRowsRead;
@@ -0,0 +1,158 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ var __importDefault = (this && this.__importDefault) || function (mod) {
36
+ return (mod && mod.__esModule) ? mod : { "default": mod };
37
+ };
38
+ Object.defineProperty(exports, "__esModule", { value: true });
39
+ exports.graphResolution = graphResolution;
40
+ exports.readGraphRows = readGraphRows;
41
+ // @implements A-SPEC-755
42
+ /**
43
+ * How far a built traceability graph is from the resolution the design claims.
44
+ *
45
+ * Measured by hand on 2026-10-07: in 330 of 330 files with two or more symbols every symbol carried
46
+ * the identical spec set (the file's anchors copied onto each function), there was no node for a test
47
+ * case or a success criterion, 41% of call edges were ambiguous and no edge carried an observation
48
+ * time, a validity bound or an evidence digest. Those numbers came from throw-away scripts; this is
49
+ * the same measurement with its definitions fixed in A-SPEC-755, so a later change to the graph is
50
+ * judged by it and not by a node count.
51
+ *
52
+ * Read-only by construction: the census is pure, and the reader opens the store read-only.
53
+ */
54
+ const fs = __importStar(require("node:fs"));
55
+ const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
56
+ const filled = (v) => v !== null && v !== '';
57
+ function graphResolution(rows) {
58
+ const nodesByKind = {};
59
+ const fileOfCode = new Map();
60
+ for (const n of rows.nodes) {
61
+ nodesByKind[n.kind] = (nodesByKind[n.kind] ?? 0) + 1;
62
+ if (n.kind === 'CODE')
63
+ fileOfCode.set(n.id, n.sourcePath);
64
+ }
65
+ const edgesByRel = {};
66
+ // Targets per linked symbol. A Set, so an edge stated twice does not make two symbols look different.
67
+ const specsOfSymbol = new Map();
68
+ let siteBoundEdges = 0, withObservedAt = 0, withValidUntil = 0, withEvidenceDigest = 0;
69
+ for (const e of rows.edges) {
70
+ edgesByRel[e.rel] = (edgesByRel[e.rel] ?? 0) + 1;
71
+ if (filled(e.observedAt))
72
+ withObservedAt++;
73
+ if (filled(e.validUntil))
74
+ withValidUntil++;
75
+ if (filled(e.evidenceDigest))
76
+ withEvidenceDigest++;
77
+ // An edge whose source is not a CODE node in these rows has no file to be attributed to.
78
+ if (e.rel !== 'implements' || !fileOfCode.has(e.src))
79
+ continue;
80
+ if (e.derivation === 'anchor-site')
81
+ siteBoundEdges++;
82
+ const set = specsOfSymbol.get(e.src);
83
+ if (set)
84
+ set.add(e.dst);
85
+ else
86
+ specsOfSymbol.set(e.src, new Set([e.dst]));
87
+ }
88
+ // Per file: the distinct spec sets its linked symbols carry. One distinct set = the file is uniform.
89
+ const setsOfFile = new Map();
90
+ const sizes = [];
91
+ for (const [id, set] of specsOfSymbol) {
92
+ sizes.push(set.size);
93
+ const file = fileOfCode.get(id) ?? null;
94
+ const entry = setsOfFile.get(file) ?? { symbols: 0, distinct: new Set() };
95
+ entry.symbols++;
96
+ entry.distinct.add([...set].sort().join('\n'));
97
+ setsOfFile.set(file, entry);
98
+ }
99
+ let filesWithTwoOrMore = 0, uniformFiles = 0;
100
+ for (const entry of setsOfFile.values()) {
101
+ if (entry.symbols < 2)
102
+ continue;
103
+ filesWithTwoOrMore++;
104
+ if (entry.distinct.size === 1)
105
+ uniformFiles++;
106
+ }
107
+ sizes.sort((a, b) => a - b);
108
+ const count = (m, k) => m[k] ?? 0;
109
+ const resolved = count(edgesByRel, 'calls');
110
+ const ambiguous = count(edgesByRel, 'calls_ambiguous');
111
+ return {
112
+ nodesByKind, edgesByRel,
113
+ specLink: {
114
+ linkedSymbols: sizes.length,
115
+ filesWithTwoOrMore, uniformFiles,
116
+ uniformShare: filesWithTwoOrMore === 0 ? null : uniformFiles / filesWithTwoOrMore,
117
+ // Lower middle for an even count: a median that is always a value some symbol really has.
118
+ specsPerSymbolMedian: sizes.length === 0 ? null : sizes[Math.floor((sizes.length - 1) / 2)],
119
+ specsPerSymbolMax: sizes.length === 0 ? null : sizes[sizes.length - 1],
120
+ siteBoundEdges,
121
+ },
122
+ verification: {
123
+ caseNodes: count(nodesByKind, 'CASE'),
124
+ criterionNodes: count(nodesByKind, 'CRITERION') + count(nodesByKind, 'RULE'),
125
+ executesEdges: count(edgesByRel, 'executes'),
126
+ verifiesEdges: count(edgesByRel, 'verifies'),
127
+ },
128
+ calls: { resolved, ambiguous, ambiguousShare: resolved + ambiguous === 0 ? null : ambiguous / (resolved + ambiguous) },
129
+ flowEdges: count(edgesByRel, 'data_dep') + count(edgesByRel, 'control_dep'),
130
+ provenance: { edges: rows.edges.length, withObservedAt, withValidUntil, withEvidenceDigest },
131
+ };
132
+ }
133
+ /**
134
+ * The rows of a graph store, read without ever writing to it. `fileMustExist` matters: the driver
135
+ * creates an empty database for an absent path, and an empty store would then read as "a graph with
136
+ * nothing in it" — the zero result this instrument must never report for a missing one.
137
+ */
138
+ function readGraphRows(dbPath) {
139
+ if (!fs.existsSync(dbPath))
140
+ return { ok: false, reason: 'missing' };
141
+ let db = null;
142
+ try {
143
+ db = new better_sqlite3_1.default(dbPath, { readonly: true, fileMustExist: true });
144
+ const nodes = db.prepare('SELECT id, kind, source_path AS sourcePath FROM nodes').all();
145
+ const edges = db.prepare(`SELECT src, dst, rel, derivation, observed_at AS observedAt, valid_until AS validUntil,
146
+ evidence_digest AS evidenceDigest FROM edges`).all();
147
+ return { ok: true, rows: { nodes, edges } };
148
+ }
149
+ catch {
150
+ return { ok: false, reason: 'not-a-graph-store' };
151
+ }
152
+ finally {
153
+ try {
154
+ db?.close();
155
+ }
156
+ catch { /* a handle that never opened has nothing to close */ }
157
+ }
158
+ }
@@ -4,7 +4,7 @@ exports.canonicalRequirementDocument = void 0;
4
4
  exports.requestIdentifiers = requestIdentifiers;
5
5
  exports.triageRequirements = triageRequirements;
6
6
  exports.requirementSemanticCoverage = requirementSemanticCoverage;
7
- // @implements A-SPEC-713.1, A-SPEC-713.2, A-SPEC-713.3, A-SPEC-713.4, A-SPEC-742, A-SPEC-713
7
+ // @implements A-SPEC-713.1, A-SPEC-713.2, A-SPEC-713.3, A-SPEC-713.4, A-SPEC-742, A-SPEC-713, A-SPEC-757
8
8
  /** Pure, conservative lifecycle triage over governed requirement documents. */
9
9
  const semantic_retrieval_1 = require("./semantic-retrieval");
10
10
  const localize_1 = require("../rtm/localize");
@@ -92,7 +92,8 @@ function rankCompare(a, b, cited) {
92
92
  return b.lexicalScore - a.lexicalScore || a.reqId.localeCompare(b.reqId);
93
93
  }
94
94
  function bm25(query, docs) {
95
- const terms = docs.map((text) => (0, semantic_retrieval_1.normalisedTerms)(text));
95
+ // @implements A-SPEC-757 — the document form: `normalisedTerms` is the request's (distinct, first 64).
96
+ const terms = docs.map((text) => (0, semantic_retrieval_1.normalisedDocumentTerms)(text));
96
97
  const avg = terms.reduce((n, row) => n + row.length, 0) / (terms.length || 1);
97
98
  const df = new Map();
98
99
  for (const row of terms)
@@ -1,6 +1,38 @@
1
1
  import { evaluationMetrics, impactMetrics, ceilingMetrics } from './evaluation-metrics';
2
2
  import { type ReplayCorpus } from './replay-corpus';
3
3
  import { type PprArmConfig } from '../assoc/assoc-arm';
4
+ /** @implements A-SPEC-756.1 — one case under one anchor-binding arm, with the case's truth. */
5
+ /**
6
+ * @implements A-SPEC-758
7
+ * One impact case under one call-graph arm: `compiler` is the scored run (the scan as the scanner
8
+ * returns it), `name` the same scan with the compiler's record removed — the graph every earlier build
9
+ * produced. Same seed, same expected set, same request.
10
+ */
11
+ export interface CallArmRow {
12
+ commit: string;
13
+ arm: 'compiler' | 'name';
14
+ /**
15
+ * `union`: the request alone — ranked candidates plus graded impact, scored against every truth file
16
+ * (`seed` is empty). `impact`: one truth file given as changed, scored against the others.
17
+ */
18
+ surface: 'union' | 'impact';
19
+ seed: string;
20
+ expected: string[];
21
+ ranked: string[];
22
+ rankedImpact: string[];
23
+ impactedFiles: string[];
24
+ }
25
+ export interface AnchorArmRow {
26
+ commit: string;
27
+ arm: 'file' | 'site' | 'site+commit';
28
+ ranked: string[];
29
+ rankedSymbols: string[];
30
+ selectedTests: string[];
31
+ rankedImpact: string[];
32
+ truthFiles: string[];
33
+ truthSymbols: string[];
34
+ truthTests: string[];
35
+ }
4
36
  /** One case, scored by both arms. Measurement only — never read by a pin. */
5
37
  export interface PairedRow {
6
38
  commit: string;
@@ -228,6 +260,19 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
228
260
  * the 1-pass result; the dump carries the 2-pass (semantic-injected) output when
229
261
  * productSemantic is present. The RUNNER owns blinding: truth goes to a separate file.
230
262
  */
263
+ /**
264
+ * @implements A-SPEC-756.1 — the anchor-binding arms, three rows per case: `file` (the scan
265
+ * with every site record removed — the graph as it was before anchors were bound to functions),
266
+ * `site` (the scan as the scanner returns it — the scored path itself) and `site+commit` (history
267
+ * binding over it, blame taken AT THE PARENT of the case, never at the answer). A callback, like
268
+ * the other measurement options: asking for it changes no scored metric and no existing row.
269
+ */
270
+ anchorArms?: (row: AnchorArmRow) => void;
271
+ /**
272
+ * @implements A-SPEC-758 — the impact case of each commit under both call graphs. A callback like
273
+ * the others: asking for it changes no scored metric.
274
+ */
275
+ callArms?: (row: CallArmRow) => void;
231
276
  caseDump?: (row: {
232
277
  commit: string;
233
278
  subject: string;
@@ -243,6 +288,10 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
243
288
  semCos?: number;
244
289
  }>;
245
290
  truthFiles: string[];
291
+ /** @implements A-SPEC-755.1 — the function axis as scored: truth from the parent-side changed
292
+ * lines, prediction from the scored (1-pass) candidates. Empty truth = outside that denominator. */
293
+ truthSymbols: string[];
294
+ rankedSymbols: string[];
246
295
  /** @implements A-SPEC-489 — present only when dumpBodies was asked. */
247
296
  bodies?: Record<string, string>;
248
297
  /** @implements A-SPEC-567.2 — present only when judgementBundle was asked. */
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.uncitedDiffs = uncitedDiffs;
37
37
  exports.runReplay = runReplay;
38
38
  exports.semanticCaseRanking = semanticCaseRanking;
39
- // @implements A-SPEC-346, A-SPEC-734
39
+ // @implements A-SPEC-346, A-SPEC-734, A-SPEC-758
40
40
  // @implements A-SPEC-347
41
41
  // @implements A-SPEC-348
42
42
  // @implements A-SPEC-349
@@ -83,6 +83,36 @@ const explore_1 = require("../assoc/explore");
83
83
  const temporal_prior_1 = require("./temporal-prior");
84
84
  const commit_text_1 = require("./commit-text");
85
85
  const bounded_io_1 = require("../project/bounded-io");
86
+ // @implements A-SPEC-756.1 — the anchor-binding arms: file-level, place, place plus history.
87
+ const anchor_history_1 = require("../rtm/anchor-history");
88
+ /**
89
+ * @implements A-SPEC-756.1
90
+ * The newest commit at or before `rev` that touched each path of the corpus' source — one `git log`.
91
+ * It keys the blame memo: two cases whose parents agree on a path's last commit get the same blame.
92
+ * A path absent from the answer has no history git could list, and the caller keys it by `rev`.
93
+ */
94
+ function lastTouchAt(corpus, rev) {
95
+ const out = new Map();
96
+ let raw;
97
+ try {
98
+ raw = (0, node_child_process_1.execFileSync)('git', ['-C', corpus.root, 'log', rev, '--format=%x1e%H', '--name-only', '--', ...corpus.sourcePathspec], { timeout: bounded_io_1.GIT_LONG_TIMEOUT_MS, encoding: 'utf8', maxBuffer: bounded_io_1.GIT_MAX_BUFFER, stdio: 'pipe' });
99
+ }
100
+ catch {
101
+ return out;
102
+ }
103
+ for (const block of raw.split('\x1e')) {
104
+ const lines = block.split('\n');
105
+ const commit = lines[0].trim();
106
+ if (commit === '')
107
+ continue;
108
+ for (const line of lines.slice(1)) {
109
+ const file = line.trim();
110
+ if (file !== '' && !out.has(file))
111
+ out.set(file, commit);
112
+ }
113
+ }
114
+ return out;
115
+ }
86
116
  /**
87
117
  * @implements A-SPEC-578.7
88
118
  * The paired differences on the UNCITED axis, ready for `pairedPower`.
@@ -187,6 +217,9 @@ async function runReplay(corpus, limit, opts = {}) {
187
217
  const unionCeilingCases = [];
188
218
  let unmeasured = 0;
189
219
  let casesWithoutSpecs = 0;
220
+ // @implements A-SPEC-756.1 — a blame is the same for every case whose parent sees the same last
221
+ // commit on that path, so it is kept across cases under exactly that key (path + last commit).
222
+ const blameMemo = new Map();
190
223
  for (const c of cases) {
191
224
  const dest = fs.mkdtempSync(path.join(os.tmpdir(), `replay-${c.commit.slice(0, 8)}-`));
192
225
  const parent = `${c.commit}^`;
@@ -243,17 +276,19 @@ async function runReplay(corpus, limit, opts = {}) {
243
276
  if (top > 0)
244
277
  for (const h of ct)
245
278
  commitTextBoost[h.file] = h.score / top;
246
- const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
247
- request: c.subject, scanned, specs, graph, testAnchors: anchors, history: [], changePrior, commitTextBoost,
248
- groundTruth: { files: c.files, tests: c.tests },
249
- basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
250
- coverage: { scannedFiles: scanned.length, skippedFiles: [], unsupportedLanguages: [] },
251
- defUse,
252
- });
253
- // @implements A-SPEC-573.4 — the same two-pass the handler runs, for the same reason the
254
- // bench stopped filtering the boost on its own: what is measured has to be what ships.
255
- const firstPass = analyzeWith();
256
- const result = (() => {
279
+ // @implements A-SPEC-756.1 — parameterised by the scan and its graph, so an anchor-binding
280
+ // arm runs the SAME two-pass analysis as the scored path instead of a second copy of it.
281
+ const twoPassOn = (scannedOn, graphOn) => {
282
+ const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
283
+ request: c.subject, scanned: scannedOn, specs, graph: graphOn, testAnchors: anchors, history: [], changePrior, commitTextBoost,
284
+ groundTruth: { files: c.files, tests: c.tests },
285
+ basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
286
+ coverage: { scannedFiles: scannedOn.length, skippedFiles: [], unsupportedLanguages: [] },
287
+ defUse,
288
+ });
289
+ // @implements A-SPEC-573.4 — the same two-pass the handler runs, for the same reason the
290
+ // bench stopped filtering the boost on its own: what is measured has to be what ships.
291
+ const firstPass = analyzeWith();
257
292
  const targets = firstPass.candidates.slice(0, defuse_bound_1.DEFUSE_TOP_FILES).map((x) => x.file);
258
293
  if (targets.length === 0)
259
294
  return firstPass;
@@ -271,7 +306,21 @@ async function runReplay(corpus, limit, opts = {}) {
271
306
  catch { /* fail-open, per file */ }
272
307
  }
273
308
  return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
274
- })();
309
+ };
310
+ // @implements A-SPEC-758 — the `name` arm: this case's scan with the compiler's record removed,
311
+ // and the graph built from it. Built only when the arm is asked for.
312
+ const onNameGraph = (fn) => {
313
+ const byName = scanned.map((f) => { const { resolvedCalls: _calls, ...rest } = f; return rest; });
314
+ const g = new rtm_graph_1.RtmGraph();
315
+ try {
316
+ (0, rtm_builder_1.buildRtm)(specs, byName, g);
317
+ return fn(byName, g);
318
+ }
319
+ finally {
320
+ g.close();
321
+ }
322
+ };
323
+ const result = twoPassOn(scanned, graph);
275
324
  const ranked = result.candidates.map((x) => x.file);
276
325
  // @implements A-SPEC-578.7 — the power arm. Both recalls come from what already exists:
277
326
  // the product's from `ranked` (never recomputed — recomputing is how a benchmark ends up
@@ -319,6 +368,45 @@ async function runReplay(corpus, limit, opts = {}) {
319
368
  }
320
369
  outcomes.push({ ranked, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests,
321
370
  truthSymbols, rankedSymbols });
371
+ // @implements A-SPEC-756.1 — the three anchor-binding arms on this case. The `site` arm IS
372
+ // the scored result above (same scan, same graph), so it is emitted from it, not re-run.
373
+ if (opts.anchorArms !== undefined) {
374
+ const symbolsOfResult = (r) => {
375
+ const out = [];
376
+ for (const cand of r.candidates)
377
+ for (const sy of cand.symbols)
378
+ if (!out.includes(sy))
379
+ out.push(sy);
380
+ return out;
381
+ };
382
+ const emit = (arm, r) => opts.anchorArms({
383
+ commit: c.commit, arm,
384
+ ranked: r.candidates.map((x) => x.file),
385
+ rankedSymbols: symbolsOfResult(r),
386
+ selectedTests: [...r.relevantTests],
387
+ rankedImpact: (r.impacts?.rankedImpact ?? []).map((x) => x.file),
388
+ truthFiles: [...c.files], truthSymbols: [...truthSymbols], truthTests: [...c.tests],
389
+ });
390
+ const onArm = (arm, scannedArm) => {
391
+ const g = new rtm_graph_1.RtmGraph();
392
+ try {
393
+ (0, rtm_builder_1.buildRtm)(specs, scannedArm, g);
394
+ emit(arm, twoPassOn(scannedArm, g));
395
+ }
396
+ finally {
397
+ g.close();
398
+ }
399
+ };
400
+ onArm('file', scanned.map((f) => { const { anchorSites: _sites, ...rest } = f; return rest; }));
401
+ emit('site', result);
402
+ const lastTouch = lastTouchAt(corpus, parent);
403
+ onArm('site+commit', (0, anchor_history_1.bindAnchorsByHistory)(scanned, (f) => {
404
+ const key = `${f.sourcePath}\u0000${lastTouch.get(f.sourcePath) ?? parent}`;
405
+ if (!blameMemo.has(key))
406
+ blameMemo.set(key, (0, anchor_history_1.gitBlameLines)(corpus.root, f.sourcePath, parent));
407
+ return blameMemo.get(key) ?? null;
408
+ }));
409
+ }
322
410
  // @implements A-SPEC-487 — the dump: 2-pass with semantic injected when asked (vectors
323
411
  // only for the files the 1-pass surfaced — the hot-path lookup contract holds), 1-pass
324
412
  // otherwise. Nothing here feeds outcomes or any pin.
@@ -401,6 +489,9 @@ async function runReplay(corpus, limit, opts = {}) {
401
489
  candidates: dumpResult.candidates,
402
490
  rankedImpact: dumpResult.impacts?.rankedImpact ?? [],
403
491
  truthFiles: c.files,
492
+ // @implements A-SPEC-755.1 — the SAME arrays the scored outcome above holds, never a
493
+ // second derivation: a paired before/after on the function axis must compare what was scored.
494
+ truthSymbols, rankedSymbols,
404
495
  ...(bodies !== undefined ? { bodies } : {}),
405
496
  ...(judgementBundle !== undefined ? { judgementBundle } : {}),
406
497
  });
@@ -474,6 +565,18 @@ async function runReplay(corpus, limit, opts = {}) {
474
565
  }
475
566
  const unionList = [...new Set([...ranked, ...impacted])];
476
567
  unionCases.push({ seed: '', expected: c.files, predicted: unionList });
568
+ // @implements A-SPEC-758 — the union surface (what a caller receives: ranked plus graded impact)
569
+ // under both call graphs.
570
+ if (opts.callArms !== undefined) {
571
+ const emitUnion = (arm, r) => opts.callArms({
572
+ commit: c.commit, arm, surface: 'union', seed: '', expected: [...c.files],
573
+ ranked: r.candidates.map((x) => x.file),
574
+ rankedImpact: (r.impacts?.rankedImpact ?? []).map((x) => x.file),
575
+ impactedFiles: [...(r.impacts?.impactedFiles ?? [])],
576
+ });
577
+ emitUnion('compiler', result);
578
+ onNameGraph((byName, g) => emitUnion('name', twoPassOn(byName, g)));
579
+ }
477
580
  // @implements A-SPEC-493 — the ceiling rows: a strict superset of the union prediction.
478
581
  if (opts.semanticArm?.gates === true) {
479
582
  for (const k of UPA_KS) {
@@ -622,6 +725,22 @@ async function runReplay(corpus, limit, opts = {}) {
622
725
  // @implements A-SPEC-469 — score the SHIPPED prediction surface (ablation must score
623
726
  // what ships): the graded top-K, not the ungraded closure the gates keep.
624
727
  impactCases.push({ seed, expected, predicted: (run.impacts?.rankedImpact ?? []).map((r) => r.file) });
728
+ // @implements A-SPEC-758 — the same impact case on the name-resolved call graph.
729
+ if (opts.callArms !== undefined) {
730
+ const emitCall = (arm, r) => opts.callArms({
731
+ commit: c.commit, arm, surface: 'impact', seed, expected: [...expected],
732
+ ranked: r.candidates.map((x) => x.file),
733
+ rankedImpact: (r.impacts?.rankedImpact ?? []).map((x) => x.file),
734
+ impactedFiles: [...(r.impacts?.impactedFiles ?? [])],
735
+ });
736
+ emitCall('compiler', run);
737
+ onNameGraph((byName, g) => emitCall('name', (0, maintenance_analyze_1.analyzeMaintenance)({
738
+ request: c.subject, scanned: byName, specs, graph: g, testAnchors: anchors, history: [],
739
+ changedFiles: [seed], changePrior, commitTextBoost,
740
+ basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
741
+ coverage: { scannedFiles: byName.length, skippedFiles: [], unsupportedLanguages: [] },
742
+ })));
743
+ }
625
744
  // @implements A-SPEC-470 — the frozen string-property heuristic on the same case.
626
745
  impactBaselineCases.push({ seed, expected,
627
746
  predicted: (0, impact_baseline_1.impactBaselinePredict)(seed, scanned.map((f) => f.sourcePath)) });
@@ -8,6 +8,8 @@ import type { Spec } from '../spec/spec-parser';
8
8
  */
9
9
  export declare function normaliseTerm(term: string): string;
10
10
  export declare const normalisedTerms: (text: string) => string[];
11
+ /** @implements A-SPEC-757 — a document's terms: every occurrence, unbounded, through the same normaliser. */
12
+ export declare const normalisedDocumentTerms: (text: string) => string[];
11
13
  export interface RankedSpec {
12
14
  id: string;
13
15
  score: number;
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.normalisedTerms = void 0;
3
+ exports.normalisedDocumentTerms = exports.normalisedTerms = void 0;
4
4
  exports.normaliseTerm = normaliseTerm;
5
5
  exports.retrieveSpecs = retrieveSpecs;
6
6
  exports.expandThroughGraph = expandThroughGraph;
@@ -74,6 +74,9 @@ function normaliseTerm(term) {
74
74
  }
75
75
  const normalisedTerms = (text) => (0, localize_1.significantTerms)(text).map(normaliseTerm);
76
76
  exports.normalisedTerms = normalisedTerms;
77
+ /** @implements A-SPEC-757 — a document's terms: every occurrence, unbounded, through the same normaliser. */
78
+ const normalisedDocumentTerms = (text) => (0, localize_1.documentTerms)(text).map(normaliseTerm);
79
+ exports.normalisedDocumentTerms = normalisedDocumentTerms;
77
80
  /**
78
81
  * BM25 over A-SPEC documents.
79
82
  *
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Which function an anchor speaks about, judged by where it is written.
3
+ *
4
+ * Measured 2026-10-07: 2,816 of this repository's 3,793 anchor mentions sit inside or directly above
5
+ * the code they describe, and the graph builder threw that away — it added one edge per pair of
6
+ * symbol and spec in the FILE's list, so in 330 of 330 files every function carried the identical
7
+ * set. This is the place-based rule; the history-based one (A-SPEC-756.1) covers anchors written in
8
+ * a header, which is where the shipped guidance tells consumers to put them.
9
+ */
10
+ export interface AnchorSite {
11
+ spec: string;
12
+ line: number;
13
+ }
14
+ export interface BoundAnchorSite extends AnchorSite {
15
+ symbol: string | null;
16
+ }
17
+ export interface SymbolRange {
18
+ qualifiedName: string;
19
+ startLine: number;
20
+ endLine: number;
21
+ }
22
+ /**
23
+ * Bind each site to a function, or to none.
24
+ *
25
+ * 1. Inside one or more symbols' ranges: the INNERMOST one — a note inside a method is about the
26
+ * method, not about the class around it.
27
+ * 2. Otherwise, in the comment block directly above a symbol: every line strictly between the
28
+ * site and the symbol's first line is blank or comment. One line of code in between and the
29
+ * comment was about that code, not about the function further down.
30
+ * 3. Otherwise none. A header anchor above the imports is a statement about the file.
31
+ *
32
+ * `lines[i]` is line `i + 1`. Pure: same text, same ranges, same answer.
33
+ */
34
+ export declare function bindAnchorSites(lines: readonly string[], symbols: readonly SymbolRange[], sites: readonly AnchorSite[]): BoundAnchorSite[];
@@ -0,0 +1,43 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.bindAnchorSites = bindAnchorSites;
4
+ /** Blank, or a line that only continues or opens a comment — the lines a doc block is made of. */
5
+ const COMMENT_OR_BLANK = /^\s*(?:$|\/\/|\/\*|\*|#|"""|''')/;
6
+ /**
7
+ * Bind each site to a function, or to none.
8
+ *
9
+ * 1. Inside one or more symbols' ranges: the INNERMOST one — a note inside a method is about the
10
+ * method, not about the class around it.
11
+ * 2. Otherwise, in the comment block directly above a symbol: every line strictly between the
12
+ * site and the symbol's first line is blank or comment. One line of code in between and the
13
+ * comment was about that code, not about the function further down.
14
+ * 3. Otherwise none. A header anchor above the imports is a statement about the file.
15
+ *
16
+ * `lines[i]` is line `i + 1`. Pure: same text, same ranges, same answer.
17
+ */
18
+ function bindAnchorSites(lines, symbols, sites) {
19
+ const byStart = [...symbols].sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine);
20
+ return sites.map((site) => {
21
+ let inner = null;
22
+ for (const s of byStart) {
23
+ if (s.startLine > site.line)
24
+ break;
25
+ if (s.endLine < site.line)
26
+ continue;
27
+ const span = s.endLine - s.startLine;
28
+ // Smaller range wins; on a tie the later start (visited later) is the more deeply nested one.
29
+ if (inner === null || span <= inner.endLine - inner.startLine)
30
+ inner = s;
31
+ }
32
+ if (inner !== null)
33
+ return { ...site, symbol: inner.qualifiedName };
34
+ const next = byStart.find((s) => s.startLine > site.line);
35
+ if (next === undefined)
36
+ return { ...site, symbol: null };
37
+ for (let ln = site.line + 1; ln < next.startLine; ln++) {
38
+ if (!COMMENT_OR_BLANK.test(lines[ln - 1] ?? ''))
39
+ return { ...site, symbol: null };
40
+ }
41
+ return { ...site, symbol: next.qualifiedName };
42
+ });
43
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Which functions an anchor speaks about, judged by the commit that introduced it.
3
+ *
4
+ * Place binds an anchor written in or above a function (A-SPEC-756). It cannot bind an anchor
5
+ * written in a file's header — and the header is where the shipped guidance tells people to put
6
+ * them: measured 2026-10-07, 7 of 1,702 anchor sites on the second corpus sit at a function. History
7
+ * can: 88% to 94% of recent source commits on both corpora add an anchor line, and the functions
8
+ * whose lines such a commit last touched are the ones it wrote for that spec. One `git blame` per
9
+ * file answers both halves — which commit introduced the anchor line, and which functions still
10
+ * hold lines of that commit.
11
+ *
12
+ * OBSERVED, not declared: the edge says "the commit that brought this anchor wrote these functions".
13
+ * It decays honestly — a function rewritten by a later commit stops matching.
14
+ */
15
+ import type { ScannedFile } from '../cpg/scanned-file';
16
+ export interface BlameLine {
17
+ commit: string;
18
+ text: string;
19
+ }
20
+ /**
21
+ * Bind every site that place left unbound to the functions its introducing commit last touched.
22
+ *
23
+ * A site stays unbound when its line is not committed yet, when the commit touched no function, or
24
+ * when it touched EVERY function of a file with two or more — "this commit wrote the whole file" is
25
+ * a statement about the file, and recording it on each function would only relabel the copy.
26
+ *
27
+ * `blameOf` is asked only for a file that has an unbound site. A `null` answer, or a blame shorter
28
+ * than the site's line, leaves that file exactly as it came.
29
+ */
30
+ export declare function bindAnchorsByHistory(scanned: readonly ScannedFile[], blameOf: (f: ScannedFile) => readonly BlameLine[] | null): ScannedFile[];
31
+ /**
32
+ * One `git blame` of a file: the commit that last touched each line, and the line's text.
33
+ *
34
+ * `-w` so a re-indent does not claim a function; `--line-porcelain` because its shape does not change
35
+ * with renames or boundary commits the way the human format's columns do. `rev` reads the file as it
36
+ * was at that revision — the replay uses the PARENT of the commit it scores, never the answer.
37
+ * `null` for anything that is not a tracked file in a repository git can read.
38
+ */
39
+ export declare function gitBlameLines(root: string, sourcePath: string, rev?: string): BlameLine[] | null;