@holmes-lab/holmes-kit 0.40.0 → 0.40.1

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 (56) hide show
  1. package/CHANGELOG.md +234 -0
  2. package/README.md +70 -4
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/index.js +25 -19
  5. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  6. package/dist/holmes/cli/interactive-prompt.js +98 -16
  7. package/dist/holmes/config/config.d.ts +17 -0
  8. package/dist/holmes/config/config.js +13 -1
  9. package/dist/holmes/governance/autonomy.d.ts +7 -0
  10. package/dist/holmes/governance/autonomy.js +36 -5
  11. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  12. package/dist/holmes/governance/push-gate-runner.js +40 -3
  13. package/dist/holmes/governance/push-gate.d.ts +13 -2
  14. package/dist/holmes/governance/push-gate.js +106 -14
  15. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  16. package/dist/holmes/guardrail/advisory-line.js +718 -0
  17. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  18. package/dist/holmes/guardrail/impact-gate.js +32 -5
  19. package/dist/holmes/hooks/pre-tool-use.d.ts +11 -0
  20. package/dist/holmes/hooks/pre-tool-use.js +44 -5
  21. package/dist/holmes/hooks/session-start.js +17 -1
  22. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  23. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  24. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  25. package/dist/holmes/mcp/handlers/test-execution.js +199 -21
  26. package/dist/holmes/mcp/handlers.d.ts +468 -3
  27. package/dist/holmes/mcp/handlers.js +5 -1
  28. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  29. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  30. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  31. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  32. package/dist/holmes/mcp/tool-schemas.js +13 -7
  33. package/dist/holmes/project/baseline.d.ts +15 -2
  34. package/dist/holmes/project/baseline.js +11 -6
  35. package/dist/holmes/project/bounded-io.d.ts +1 -0
  36. package/dist/holmes/project/bounded-io.js +4 -2
  37. package/dist/holmes/project/change-source.d.ts +4 -0
  38. package/dist/holmes/project/change-source.js +13 -5
  39. package/dist/holmes/project/root.js +3 -1
  40. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  41. package/dist/holmes/review/evidence-mode.js +33 -0
  42. package/dist/holmes/review/head-worktree.d.ts +55 -0
  43. package/dist/holmes/review/head-worktree.js +329 -0
  44. package/dist/holmes/review/mrp.js +13 -3
  45. package/dist/holmes/review/run-provenance.d.ts +45 -0
  46. package/dist/holmes/review/run-provenance.js +314 -0
  47. package/dist/holmes/review/test-evidence.d.ts +174 -0
  48. package/dist/holmes/review/test-evidence.js +330 -2
  49. package/dist/holmes/review/test-reports.d.ts +94 -0
  50. package/dist/holmes/review/test-reports.js +382 -0
  51. package/dist/holmes/review/test-runner.d.ts +176 -65
  52. package/dist/holmes/review/test-runner.js +531 -316
  53. package/dist/holmes/review/test-units.d.ts +159 -0
  54. package/dist/holmes/review/test-units.js +814 -0
  55. package/package.json +1 -1
  56. package/playbooks/publish/PLAYBOOK.md +2 -1
@@ -0,0 +1,314 @@
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
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.PYTHON_NAMES = exports.PLUGIN = void 0;
37
+ exports.pythonNames = pythonNames;
38
+ exports.pythonEnvironmentResolves = pythonEnvironmentResolves;
39
+ exports.loadedFromWorkTree = loadedFromWorkTree;
40
+ exports.pytestRunProvenance = pytestRunProvenance;
41
+ exports.nodeNamesResolveToWorkTree = nodeNamesResolveToWorkTree;
42
+ // @implements A-SPEC-128.14, A-SPEC-128.15, A-SPEC-128.16, A-SPEC-128.17
43
+ /**
44
+ * HEAD's run must import HEAD's code. A full pytest unit in HEAD's worktree runs the work tree's interpreter (a `.venv`
45
+ * is not in HEAD), and an editable install, a `.pth` finder or a path entry there can load the work tree's source — so
46
+ * a red commit went green on code that was never committed (reviewer B, 128.13 to 128.15).
47
+ *
48
+ * Two witnesses, both judged against the same exemption — the interpreter's own library directories:
49
+ * - A-SPEC-128.16 E3 asks the ENVIRONMENT, before and apart from the tests: the interpreter, started in HEAD's
50
+ * worktree with the unit's environment, says where each of HEAD's top-level names resolves. A subprocess, an xdist
51
+ * worker or a test that restores sys.modules uses the same environment, so one question covers them all.
52
+ * - A-SPEC-128.15 O1 records the OUTCOME: a plugin writes the file of every module the run loaded.
53
+ * Node is asked the same question (E4): where HEAD's package names resolve from each package directory.
54
+ */
55
+ const fs = __importStar(require("node:fs"));
56
+ const os = __importStar(require("node:os"));
57
+ const path = __importStar(require("node:path"));
58
+ const node_child_process_1 = require("node:child_process");
59
+ const test_units_1 = require("./test-units");
60
+ const config_1 = require("../config/config");
61
+ const root_1 = require("../project/root");
62
+ const bounded_io_1 = require("../project/bounded-io");
63
+ exports.PLUGIN = 'holmes_provenance';
64
+ const LIBS = 'import sysconfig\ndef _libs():\n p = sysconfig.get_paths()\n return [p[k] for k in ("stdlib", "platstdlib", "purelib", "platlib") if p.get(k)]\n';
65
+ const SOURCE = [
66
+ 'import json, os, sys', LIBS,
67
+ 'def pytest_sessionfinish(session, exitstatus):',
68
+ ' out = os.environ.get("HOLMES_PROVENANCE_OUT")',
69
+ ' if not out:',
70
+ ' return',
71
+ ' files = [f for f in (getattr(m, "__file__", None) for m in list(sys.modules.values())) if isinstance(f, str)]',
72
+ ' with open(out, "w") as fh:',
73
+ ' json.dump({"prefixes": _libs(), "files": files}, fh)',
74
+ '',
75
+ ].join('\n');
76
+ const PROBE = [
77
+ 'import importlib.util, json, os, sys', LIBS,
78
+ 'here = {os.getcwd(), os.path.realpath(os.getcwd())}',
79
+ 'sys.path = [p for p in sys.path if p not in ("", ".") and os.path.realpath(p) not in here]',
80
+ 'channels = list(sys.path)',
81
+ '# HEAD itself is only the last resort, so a parent package resolves and the environment\'s own paths still come first',
82
+ 'sys.path.append(os.getcwd())',
83
+ 'found = {}',
84
+ 'with open(os.environ["HOLMES_PROBE_NAMES_FILE"]) as fh:',
85
+ ' names = json.load(fh)',
86
+ 'for n in names:',
87
+ ' try:',
88
+ ' s = importlib.util.find_spec(n)',
89
+ ' except Exception:',
90
+ ' continue',
91
+ ' if s is None:',
92
+ ' continue',
93
+ ' locs = [s.origin] if s.origin and s.origin not in ("built-in", "frozen") else []',
94
+ ' locs += [str(x) for x in (s.submodule_search_locations or [])]',
95
+ ' if locs:',
96
+ ' found[n] = locs',
97
+ 'with open(os.environ["HOLMES_PROBE_OUT"], "w") as fh:',
98
+ ' json.dump({"libs": _libs(), "found": found, "paths": channels}, fh)',
99
+ ].join('\n');
100
+ const real = (p) => { try {
101
+ return fs.realpathSync(p);
102
+ }
103
+ catch {
104
+ return path.resolve(p);
105
+ } };
106
+ const inside = (child, parent) => { const rel = path.relative(parent, child); return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel)); };
107
+ const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
108
+ /** A location of the work tree's code: inside it, outside HEAD's worktree, outside every library directory. */
109
+ const workTreeCode = (loc, tree, head, libs) => { const r = real(loc); return inside(r, tree) && !inside(r, head) && !libs.some((l) => inside(r, l)); };
110
+ const rel = (tree, loc) => path.relative(tree, real(loc)).split(path.sep).join('/');
111
+ exports.PYTHON_NAMES = 20_000;
112
+ /** HEAD's tracked python files, as git lists them in the worktree; a bounded walk when git cannot answer. */
113
+ function pythonFiles(runRoot) {
114
+ try {
115
+ return (0, node_child_process_1.execFileSync)('git', ['-C', runRoot, 'ls-files', '-z', '--', '*.py'], { encoding: 'utf8', timeout: bounded_io_1.GIT_TIMEOUT_MS * 4, maxBuffer: 256 * 1024 * 1024, env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'ignore'] })
116
+ .split('\0').filter((f) => f !== '');
117
+ }
118
+ catch {
119
+ const out = [];
120
+ const walk = (d, relDir) => {
121
+ let kids = [];
122
+ try {
123
+ kids = fs.readdirSync(d, { withFileTypes: true });
124
+ }
125
+ catch {
126
+ return;
127
+ }
128
+ if (kids.some((k) => k.name === 'pyvenv.cfg'))
129
+ return;
130
+ for (const k of kids) {
131
+ if (k.name.startsWith('.') || k.name === 'node_modules')
132
+ continue;
133
+ const r = relDir === '' ? k.name : `${relDir}/${k.name}`;
134
+ if (k.isDirectory())
135
+ walk(path.join(d, k.name), r);
136
+ else if (k.name.endsWith('.py'))
137
+ out.push(r);
138
+ }
139
+ };
140
+ walk(runRoot, '');
141
+ return out;
142
+ }
143
+ }
144
+ /**
145
+ * A-SPEC-128.17 N2: every dotted module name of HEAD's python files — each identifier suffix of each path, and each
146
+ * package on the way (namespace packages included), so no layout (src/, python/, packages/x/src/) is missed. `over` when
147
+ * the names pass the cap (testRun.pythonNames).
148
+ */
149
+ function pythonNames(runRoot, cap = exports.PYTHON_NAMES) {
150
+ const names = new Set();
151
+ for (const file of pythonFiles(runRoot)) {
152
+ const segs = file.split('/');
153
+ const stem = segs[segs.length - 1].slice(0, -3);
154
+ const mod = stem === '__init__' ? segs.slice(0, -1) : [...segs.slice(0, -1), stem];
155
+ for (let end = 1; end <= mod.length; end++) {
156
+ for (let start = end - 1; start >= 0; start--) {
157
+ if (!IDENT.test(mod[start]))
158
+ break;
159
+ names.add(mod.slice(start, end).join('.'));
160
+ if (names.size > cap)
161
+ return { names: [...names], over: true };
162
+ }
163
+ }
164
+ }
165
+ return { names: [...names], over: false };
166
+ }
167
+ /**
168
+ * E3: where the interpreter resolves HEAD's names, asked in HEAD's worktree with the unit's environment; a reason or null.
169
+ * `-P` (python 3.11+) keeps the current directory off sys.path from the first import, so HEAD's own json.py or
170
+ * sysconfig.py never runs in the question; an older python fails it, and that is environment. The answer is written to
171
+ * a file, so nothing a .pth or an exit handler prints can be read as it (review A of 128.16, L1 and L2).
172
+ */
173
+ function pythonEnvironmentResolves(python, cwd, names, workTree, headTree, env, exec = (c, a, o) => (0, node_child_process_1.execFileSync)(c, a, { ...o, encoding: 'utf8', timeout: 60_000, stdio: ['ignore', 'pipe', 'pipe'] })) {
174
+ let answer;
175
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-probe-'));
176
+ const out = path.join(dir, 'answer.json');
177
+ const namesFile = path.join(dir, 'names.json');
178
+ try {
179
+ fs.writeFileSync(namesFile, JSON.stringify(names));
180
+ exec(python, ['-P', '-c', PROBE], { cwd, env: { ...env, HOLMES_PROBE_NAMES_FILE: namesFile, HOLMES_PROBE_OUT: out } });
181
+ answer = JSON.parse(fs.readFileSync(out, 'utf8'));
182
+ }
183
+ catch (e) {
184
+ return `the interpreter (${python}) could not say where HEAD's names resolve (python 3.11 or later is needed): ${String(e.message ?? e).split('\n')[0].slice(0, 160)}`;
185
+ }
186
+ finally {
187
+ try {
188
+ fs.rmSync(dir, { recursive: true, force: true });
189
+ }
190
+ catch { /* best effort */ }
191
+ }
192
+ const tree = real(workTree), head = real(headTree);
193
+ const libs = (Array.isArray(answer.libs) ? answer.libs : []).filter((l) => typeof l === 'string' && l !== '').map(real);
194
+ // A-SPEC-128.17 C1: an import-path entry into the work tree is a channel, whatever names resolve through it
195
+ const channel = (Array.isArray(answer.paths) ? answer.paths : []).find((p) => typeof p === 'string' && p !== '' && workTreeCode(p, tree, head, libs));
196
+ if (channel !== undefined) {
197
+ return `the interpreter's import path holds the work tree (${rel(tree, channel)}) — PYTHONPATH, a .pth line or site configuration would let any process of the run load uncommitted code; remove it from the environment`;
198
+ }
199
+ const found = (answer.found && typeof answer.found === 'object' ? answer.found : {});
200
+ for (const [name, locs] of Object.entries(found)) {
201
+ const hit = (Array.isArray(locs) ? locs : []).find((l) => typeof l === 'string' && workTreeCode(l, tree, head, libs));
202
+ if (hit !== undefined) {
203
+ return `the environment resolves HEAD's ${name} to the work tree (${rel(tree, hit)}) — an editable install, a .pth finder or a path entry; every process of the run (subprocesses, workers) would load uncommitted code; use a non-editable environment`;
204
+ }
205
+ }
206
+ return null;
207
+ }
208
+ /** O1: the first loaded file inside the work tree, outside HEAD's worktree and every library directory, as a reason; or null. */
209
+ function loadedFromWorkTree(recordFile, workTree, headTree) {
210
+ let rec;
211
+ try {
212
+ rec = JSON.parse(fs.readFileSync(recordFile, 'utf8'));
213
+ }
214
+ catch {
215
+ return 'the run left no record of the modules it loaded (holmes_provenance) — HEAD\'s provenance cannot be judged';
216
+ }
217
+ const tree = real(workTree), head = real(headTree);
218
+ const libs = (Array.isArray(rec.prefixes) ? rec.prefixes : []).filter((p) => typeof p === 'string' && p !== '').map(real);
219
+ const files = (Array.isArray(rec.files) ? rec.files : []).filter((f) => typeof f === 'string' && f !== '');
220
+ const hit = files.find((f) => workTreeCode(f, tree, head, libs));
221
+ return hit === undefined ? null
222
+ : `the run loaded a module from the work tree (${rel(tree, hit)}) — an editable install, a .pth finder or a path entry put uncommitted code into HEAD's run; use a non-editable environment`;
223
+ }
224
+ /**
225
+ * The provenance of one full pytest unit in HEAD's worktree: P1's pinned configuration and confcutdir, E3's environment
226
+ * answer (`refused` when the environment resolves HEAD's names to the work tree), and O1's plugin with its judgement.
227
+ */
228
+ function pytestRunProvenance(tmpDir, run, unitCwd, python, env, exec) {
229
+ const unitDir = path.relative(run.root, unitCwd).split(path.sep).filter(Boolean).join('/');
230
+ let cap = exports.PYTHON_NAMES;
231
+ try {
232
+ cap = (0, config_1.loadConfig)(run.root).testRun.pythonNames ?? exports.PYTHON_NAMES;
233
+ }
234
+ catch {
235
+ cap = exports.PYTHON_NAMES;
236
+ }
237
+ const named = pythonNames(run.root, cap);
238
+ const inifile = (0, test_units_1.pytestInifile)(run.root, unitDir);
239
+ const ini = inifile ?? path.join(tmpDir, 'pytest.ini');
240
+ if (inifile === null)
241
+ fs.writeFileSync(ini, '[pytest]\n');
242
+ const out = path.join(tmpDir, 'provenance.json');
243
+ fs.writeFileSync(path.join(tmpDir, `${exports.PLUGIN}.py`), SOURCE);
244
+ return {
245
+ refused: named.over
246
+ ? `HEAD has more python module names than ${cap} — raise ax.config.json testRun.pythonNames to let the run prove where each resolves`
247
+ : pythonEnvironmentResolves(python, unitCwd, named.names, run.sourceRoot, run.root, env, exec),
248
+ args: ['-c', ini, '-p', exports.PLUGIN],
249
+ confcutdir: inifile ? real(path.dirname(inifile)) : real(unitCwd),
250
+ env: (base) => ({ ...base, PYTHONPATH: [tmpDir, base.PYTHONPATH].filter((p) => typeof p === 'string' && p !== '').join(path.delimiter), HOLMES_PROVENANCE_OUT: out }),
251
+ // A missing record matters only for a green run: a red that stopped before the session (a conftest that cannot import)
252
+ // is already red, and is the tests', not the environment's
253
+ judge: (passed) => (passed || fs.existsSync(out) ? loadedFromWorkTree(out, run.sourceRoot, run.root) : null),
254
+ };
255
+ }
256
+ /**
257
+ * E4: HEAD's package names (every package.json of the worktree outside node_modules), each resolved as node resolves a
258
+ * bare name — `node_modules/<name>` up the ancestors of every package directory, then each NODE_PATH entry. One that
259
+ * lands inside the work tree, outside HEAD's worktree and every node_modules, is a reason; otherwise null.
260
+ */
261
+ function nodeNamesResolveToWorkTree(headTree, workTree, env) {
262
+ const dirs = [];
263
+ const names = new Set();
264
+ const walk = (d, depth) => {
265
+ if (depth > 6 || dirs.length >= 200)
266
+ return;
267
+ let kids = [];
268
+ try {
269
+ kids = fs.readdirSync(d, { withFileTypes: true });
270
+ }
271
+ catch {
272
+ return;
273
+ }
274
+ if (kids.some((k) => k.isFile() && k.name === 'package.json')) {
275
+ dirs.push(d);
276
+ try {
277
+ const n = JSON.parse(fs.readFileSync(path.join(d, 'package.json'), 'utf8')).name;
278
+ if (typeof n === 'string' && n !== '')
279
+ names.add(n);
280
+ }
281
+ catch { /* unnamed */ }
282
+ }
283
+ for (const k of kids)
284
+ if (k.isDirectory() && k.name !== 'node_modules' && !k.name.startsWith('.'))
285
+ walk(path.join(d, k.name), depth + 1);
286
+ };
287
+ walk(headTree, 0);
288
+ const tree = real(workTree), head = real(headTree);
289
+ const extra = (env.NODE_PATH ?? '').split(path.delimiter).filter((p) => p !== '');
290
+ // A-SPEC-128.17 C1: a NODE_PATH entry into the work tree is a channel, whatever HEAD's package names are
291
+ const channel = extra.find((p) => { const to = real(p); return inside(to, tree) && !inside(to, head) && !path.relative(tree, to).split(path.sep).includes('node_modules'); });
292
+ if (channel !== undefined)
293
+ return `NODE_PATH holds the work tree (${rel(tree, channel)}) — any require of the run could load uncommitted code through it; remove it from the environment`;
294
+ for (const name of names) {
295
+ for (const d of dirs) {
296
+ const candidates = [];
297
+ for (let a = d;; a = path.dirname(a)) {
298
+ candidates.push(path.join(a, 'node_modules', name));
299
+ if (path.dirname(a) === a)
300
+ break;
301
+ }
302
+ for (const p of extra)
303
+ candidates.push(path.join(p, name));
304
+ const at = candidates.find((c) => fs.existsSync(path.join(c, 'package.json')));
305
+ if (at === undefined)
306
+ continue;
307
+ const to = real(at);
308
+ if (inside(to, tree) && !inside(to, head) && !path.relative(tree, to).split(path.sep).includes('node_modules')) {
309
+ return `HEAD's package ${name} resolves to the work tree (${rel(tree, to)}) — a workspace link or NODE_PATH would load uncommitted code; 0.40.x does not evidence it`;
310
+ }
311
+ }
312
+ }
313
+ return null;
314
+ }
@@ -21,6 +21,146 @@ export interface TestEvidence {
21
21
  tier: string;
22
22
  passed: boolean;
23
23
  executedByAspec: Record<string, number>;
24
+ /** @implements A-SPEC-466.2 — the jest worker count the run applied; null when none was set; absent before 466.2. */
25
+ workers?: number | null;
26
+ /** @implements A-SPEC-466.3 — the runners that ran and took no worker count; absent when none. */
27
+ workersIgnoredBy?: string[];
28
+ /** @implements A-SPEC-466.6 — the run's time budget in minutes (30 by default); recorded, never judged on. */
29
+ timeoutMinutes?: number;
30
+ /** @implements A-SPEC-128.2 — the runner's mode; only `full` is written here. Absent before 128.2 (a legacy record). */
31
+ mode?: string;
32
+ /** @implements A-SPEC-128.2 — how many test files the run executed (A-SPEC-128.4: the executed files, not the plan's list). */
33
+ ranFileCount?: number;
34
+ /** @implements A-SPEC-128.4 — the ecosystems that ran. */
35
+ ranWith?: string[];
36
+ /** @implements A-SPEC-128.5 — the tests the runners executed; the push gate's count. */
37
+ testsRun?: number;
38
+ /** @implements A-SPEC-128.5 — the ecosystems the project has; `ranWith` covered every one. */
39
+ detected?: string[];
40
+ /** @implements A-SPEC-128.6 — the tests executed per ecosystem; every detected one must be at least 1. */
41
+ testsRunBy?: Record<string, number>;
42
+ /** @implements A-SPEC-128.7 — per detected ecosystem, the root-relative path that named it. */
43
+ detectedBy?: Record<string, string>;
44
+ /** @implements A-SPEC-128.7 — impacted ecosystems a full run did not run (I1). */
45
+ notRun?: NotRun[];
46
+ /** @implements A-SPEC-128.7 — build files outside the detection range. */
47
+ notDetected?: NotDetected[];
48
+ }
49
+ /** @implements A-SPEC-128.7 — an impacted ecosystem a full run did not run, because it is not detected. */
50
+ export interface NotRun {
51
+ ecosystem: string;
52
+ reason: string;
53
+ }
54
+ /** @implements A-SPEC-128.7 — a build file outside the detection range, named and not run. */
55
+ export interface NotDetected {
56
+ path: string;
57
+ ecosystem: string;
58
+ reason: string;
59
+ }
60
+ /**
61
+ * @implements A-SPEC-128.7 — I2: what a refusal tells the pusher to do, so that doing it once from the same repository
62
+ * state reaches allow. `rerun`: the full call. `fix-tests`: nothing but changed tests can pass (a real red, no tests, the
63
+ * project's own suite all skipped). `exclude`: a tree below the root that is not the project's — the exact entry.
64
+ */
65
+ export type EvidenceAct = 'collect' | 'environment' | 'fix-tests' | 'rerun';
66
+ export interface EvidenceVerdict {
67
+ problem: string;
68
+ act: EvidenceAct;
69
+ }
70
+ /**
71
+ * @implements A-SPEC-128.10 — I3 and R2 read from a record, in that order: detected tests the runners did not report
72
+ * (`collect`), then build roots whose code saw no executed test (`fix-tests`, naming a missing build file).
73
+ */
74
+ export declare function coverageVerdict(r: {
75
+ notExecuted?: unknown;
76
+ untestedCode?: unknown;
77
+ }): EvidenceVerdict | null;
78
+ /** @implements A-SPEC-128.9 — the units of a record that ran no test (each unit must run at least one). */
79
+ export declare function idleUnits(r: {
80
+ units?: unknown;
81
+ }): string[];
82
+ /**
83
+ * @implements A-SPEC-128.9 — E2: a full attempt at `head` that ran nothing, has no unit and counts no implementation code
84
+ * — nothing is testable (owner decision 1, corrected 2026-11-06: README, settings, docs only). Allowed with a record.
85
+ */
86
+ export declare function noTestableCode(s: Record<string, unknown> | null | undefined, head: string): boolean;
87
+ /**
88
+ * @implements A-SPEC-128.7 — fail-closed shape: a field that is present with the wrong shape is named. A string `detected`
89
+ * passed the predicate as "nothing detected", and a string `missing` threw inside the gate, which exited 0 (A L1, B M1).
90
+ */
91
+ export declare function recordShapeProblem(r: Record<string, unknown>, opts: {
92
+ requireDetected: boolean;
93
+ }): string | null;
94
+ /** @implements A-SPEC-128.7 — the detected ecosystems that ran no test: one reading for the predicate, the writer and the gate. */
95
+ export declare function idleEcosystems(r: {
96
+ detected?: unknown;
97
+ testsRunBy?: unknown;
98
+ }): string[];
99
+ /**
100
+ * @implements A-SPEC-128.7 — a failed full attempt, read wherever it lies (scoped-evidence, or test-evidence it voided in
101
+ * place). Its words follow I2: a stopped run → a larger budget; a red or idle ecosystem → its owner's act; another head
102
+ * → that head named.
103
+ */
104
+ export declare function attemptVerdict(s: Record<string, unknown>, head: string): EvidenceVerdict;
105
+ /**
106
+ * @implements A-SPEC-128.6 — THE push-evidence predicate: the writer (whether to write test-evidence), the push gate and
107
+ * the merge-ready package all read it. Null when `r` is push evidence for `head`; otherwise the first failing condition,
108
+ * in words a refusal can carry. A summed count hid an ecosystem that ran nothing (review 2026-11-05 20:34, A H1).
109
+ * @implements A-SPEC-128.7 — with the act that clears it (I2), and fail-closed on shape.
110
+ */
111
+ export declare function pushEvidenceVerdict(r: Partial<TestEvidence> | null | undefined, head: string): EvidenceVerdict | null;
112
+ /** @implements A-SPEC-128.6 — the predicate's words; @implements A-SPEC-128.7 — the verdict's problem. */
113
+ export declare function pushEvidenceProblem(r: Partial<TestEvidence> | null | undefined, head: string): string | null;
114
+ /** @implements A-SPEC-128.6 — `pushEvidenceProblem(...) === null`. */
115
+ export declare function isPushEvidence(r: Partial<TestEvidence> | null | undefined, head: string): boolean;
116
+ /**
117
+ * @implements A-SPEC-128.2 — what counts as full evidence, in one place: a run whose mode AND tier were full. A record
118
+ * without a mode (written before 128.2, when a scoped green could land here) is not full evidence.
119
+ * @implements A-SPEC-128.4 — the write side decides with this same predicate, over the shared token.
120
+ */
121
+ export declare function isFullEvidence(ev: {
122
+ mode?: unknown;
123
+ tier?: unknown;
124
+ } | null | undefined): boolean;
125
+ /** The words a refusal uses for a record that is not full evidence: its tier and mode, `absent` when it has none. */
126
+ export declare function evidenceKind(ev: {
127
+ mode?: unknown;
128
+ tier?: unknown;
129
+ }): string;
130
+ /**
131
+ * @implements A-SPEC-128.2 — what a run that was not full verified: its own record, never test-evidence or a baseline,
132
+ * so a scoped green can never stand as the full suite's.
133
+ */
134
+ export interface ScopedEvidence {
135
+ takenAt: string;
136
+ head: string;
137
+ tier: string;
138
+ /**
139
+ * @implements A-SPEC-128.4 — a noop run is always skipped and writes nothing.
140
+ * @implements A-SPEC-128.5 — `full-attempt`: a full run that was red, stopped, or missed a detected ecosystem.
141
+ */
142
+ mode: 'scoped' | 'full-attempt';
143
+ ranFiles: string[];
144
+ passed: boolean;
145
+ executedByAspec: Record<string, number>;
146
+ ranWith?: string[];
147
+ /** @implements A-SPEC-128.5 — false when a runner was stopped at the budget. */
148
+ judged?: boolean;
149
+ testsRun?: number;
150
+ detected?: string[];
151
+ /** @implements A-SPEC-128.6 */
152
+ testsRunBy?: Record<string, number>;
153
+ /** @implements A-SPEC-128.6 — the detected ecosystems that ran no test. */
154
+ missing?: string[];
155
+ /** @implements A-SPEC-128.7 — the words a refusal needs: whose each ecosystem is, which ran red, what was left out. */
156
+ detectedBy?: Record<string, string>;
157
+ failedBy?: string[];
158
+ notRun?: NotRun[];
159
+ notDetected?: NotDetected[];
160
+ /** @implements A-SPEC-128.7 — the budget the attempt ran under, so a stopped one names a larger one. */
161
+ timeoutMinutes?: number;
162
+ /** @implements A-SPEC-128.8 — the worker count applied, so the next call keeps it. */
163
+ workers?: number | null;
24
164
  }
25
165
  /** Map per-test-file executed counts onto the A-SPECs those files @implement (pure). */
26
166
  export declare function computeExecutedByAspec(executedByFile: Record<string, number>, testAnchors: Record<string, string[]>): Record<string, number>;
@@ -28,4 +168,38 @@ export declare function computeExecutedByAspec(executedByFile: Record<string, nu
28
168
  export declare function isFresh(ev: TestEvidence | undefined, currentHead: string): boolean;
29
169
  export declare const EVIDENCE_FILE: string;
30
170
  export declare function writeTestEvidence(root: string, ev: TestEvidence): boolean;
171
+ /**
172
+ * @implements A-SPEC-128.6 — a newer failed full attempt supersedes older evidence: the writer removes it, so the gate's
173
+ * newest observation is the attempt (a green-then-red at one head passed the gate before, review 2026-11-05 20:34).
174
+ */
175
+ export declare function removeTestEvidence(root: string): void;
176
+ /**
177
+ * @implements A-SPEC-128.7 — void the older test-evidence after an attempt, so it can never stand beside it. With the
178
+ * attempt written, the evidence is removed; when it cannot be removed, or the attempt could not be written (nothing else
179
+ * would record the red run), the attempt is written over test-evidence in place — a record that is not full evidence.
180
+ * A read-only ledger directory left a green record standing after a red run (review 2026-11-06 00:16, A M2).
181
+ * True when no full evidence stands afterwards.
182
+ */
183
+ export declare function voidTestEvidence(root: string, attemptRecord: ScopedEvidence, attemptWritten: boolean): boolean;
31
184
  export declare function readTestEvidence(root: string): TestEvidence | undefined;
185
+ export declare const SCOPED_EVIDENCE_FILE: string;
186
+ /** @implements A-SPEC-128.2 — fail-open like writeTestEvidence: recording never breaks a run. */
187
+ export declare function writeScopedEvidence(root: string, ev: ScopedEvidence): boolean;
188
+ /** @implements A-SPEC-128.2 — the scoped record's own reader; a missing or unreadable record is absent. */
189
+ export declare function readScopedEvidence(root: string): ScopedEvidence | undefined;
190
+ /**
191
+ * @implements A-SPEC-128.5 — the same three states for test-evidence: a file that exists but is not a record is a run
192
+ * history the push gate cannot read, so it refuses rather than taking the unrun pass (decided 2026-11-05 19:58).
193
+ */
194
+ export declare function testEvidenceState(root: string): {
195
+ state: 'absent' | 'valid' | 'unreadable';
196
+ evidence?: TestEvidence;
197
+ };
198
+ /**
199
+ * @implements A-SPEC-128.4 — absent, valid, or present but not a record. A file that exists is a run history even when it
200
+ * cannot be read, so the push gate refuses on `unreadable` rather than taking the unrun pass.
201
+ */
202
+ export declare function scopedEvidenceState(root: string): {
203
+ state: 'absent' | 'valid' | 'unreadable';
204
+ evidence?: ScopedEvidence;
205
+ };