@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/hooks/stop.js

@@ -0,0 +1,416 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CONSECUTIVE_BLOCKS = void 0;
+exports.governanceLostPreflight = governanceLostPreflight;
+exports.evaluateStop = evaluateStop;
+exports.stopDebtAction = stopDebtAction;
+exports.decideStopGuard = decideStopGuard;
+exports.__setWiredSpecsForTest = __setWiredSpecsForTest;
+exports.readGuardCount = readGuardCount;
+exports.writeGuardCount = writeGuardCount;
+const fs = __importStar(require("node:fs"));
+const node_child_process_1 = require("node:child_process");
+const path = __importStar(require("node:path"));
+const test_scope_1 = require("../rtm/test-scope");
+const constitution_1 = require("../governance/constitution");
+const provenance_chain_1 = require("../governance/provenance-chain");
+const test_evidence_1 = require("../review/test-evidence");
+const pre_tool_use_1 = require("./pre-tool-use");
+const governance_history_1 = require("../guardrail/governance-history");
+const constitution_debt_1 = require("../governance/constitution-debt");
+/**
+ * @implements A-SPEC-175
+ * The turn-boundary answer to "this project is governed but its specs are gone".
+ *
+ * Extracted so it is reachable by a test: the runtime block below only runs under
+ * `require.main === module`, and a check that lives only there is a check nothing can mutate against.
+ * Returns the reason to block with, or null when there is nothing to report.
+ */
+function governanceLostPreflight(specsDir, projectRoot) {
+    if (fs.existsSync(specsDir))
+        return null;
+    // @implements A-SPEC-191 §18 (round 11) — the project is not "two directories up from the spec
+    // store". That arithmetic assumed a two-segment layout (`.ax/specs`), and `init --specs-dir specs`
+    // is an explicitly supported one-segment value: there `../..` names the project's PARENT, so the
+    // A-SPEC-175 protection looked for governance history in the wrong tree — silent where it should
+    // block, and blocking where it should be silent. The caller knows the root; it passes it.
+    const root = projectRoot ?? path.resolve(specsDir, '..', '..');
+    return (0, governance_history_1.hasGovernanceHistory)(root) ? governance_history_1.GOVERNANCE_LOST_HINT : null;
+}
+function evaluateStop(specs, evidence) {
+    // L1: the Stop gate IS the constitution's re-verification point — every turn boundary re-runs the
+    // inviolable articles (ART-2 RTM, ART-3 validity incl. 4-quadrant GWT, ART-4 coverage evidence).
+    // The articles live in ONE place (governance/constitution.ts); this gate merely executes them.
+    const violations = (0, constitution_1.verifyConstitution)({ specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings });
+    const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
+    // Tampered audit trail blocks finishing — wires the provenance chain's verify into the live gate
+    // (review finding: verify() previously had no product caller, so the chain's guarantee was inert).
+    if (evidence?.provenance && !evidence.provenance.ok) {
+        problems.push(`[ART-2] provenance chain broken at seq ${evidence.provenance.brokenAt}: ${evidence.provenance.detail}`);
+    }
+    // @implements A-SPEC-191 (§4a) — an existing-but-unreadable findings ledger is not a clean turn:
+    // it may hold an open critical, and a "clean" verdict here would also CLEAR standing ART-7 debt.
+    if (evidence?.findingsUnreadable) {
+        problems.push('[ART-7] findings 원장을 읽을 수 없습니다 — 열린 치명 발견의 존재를 확인할 수 없는 턴은 깨끗한 턴이 아닙니다 (원장 파일의 권한·형식을 복구하십시오)');
+    }
+    if (problems.length === 0)
+        return { block: false };
+    const shown = problems.slice(0, 20);
+    const more = problems.length > shown.length ? `\n…and ${problems.length - shown.length} more` : '';
+    // @implements A-SPEC-134 — the distinct articles feed the constitution-debt state on a cap-yield.
+    const articles = [...new Set(violations.map((x) => x.article)
+            .concat(evidence?.provenance && !evidence.provenance.ok ? ['ART-2'] : [])
+            .concat(evidence?.findingsUnreadable ? ['ART-7'] : []))];
+    return {
+        block: true,
+        articles,
+        reason: `[Holmes-Kit] constitution gate: ${problems.length} article violation(s) must be ` +
+            `fixed before finishing:\n${shown.join('\n')}${more}`,
+    };
+}
+/**
+ * @implements A-SPEC-134
+ * Pure decision for the constitution-debt state at a turn boundary. Replaces the Stop gate's silent
+ * cap-yield: a clean turn clears any standing debt; a cap-yield (the gate giving up its block after
+ * MAX_CONSECUTIVE_BLOCKS) RECORDS the unresolved articles as debt so new code is blocked until the
+ * constitution is clean again; a normal block (still within the cap) touches nothing.
+ */
+function stopDebtAction(evaluation, guard) {
+    if (!evaluation.block)
+        return { action: 'clear', articles: [] }; // clean turn → debt paid
+    if (guard.capped)
+        return { action: 'write', articles: evaluation.articles ?? [] }; // gave up → debt owed
+    return { action: 'none', articles: [] }; // still blocking within cap
+}
+// ---- H2: stop loop-guard with a bounded consecutive-block cap ----------------------------------
+// The old guard exited unconditionally when stop_hook_active was set, making the gate a ONE-SHOT
+// speed bump (block once, then the very next stop sails through with the problems unfixed —
+// adversarial review F7). Now consecutive blocked stops are COUNTED in a state file: the gate keeps
+// blocking while problems persist, up to MAX_CONSECUTIVE_BLOCKS, then yields with a loud warning
+// (bounded, so an unfixable state cannot infinite-loop the session). Any clean stop resets the count.
+exports.MAX_CONSECUTIVE_BLOCKS = 3;
+function decideStopGuard(wantsBlock, priorConsecutiveBlocks, cap = exports.MAX_CONSECUTIVE_BLOCKS) {
+    if (!wantsBlock)
+        return { block: false, nextCount: 0, capped: false };
+    if (priorConsecutiveBlocks >= cap)
+        return { block: false, nextCount: 0, capped: true }; // yield, reset
+    return { block: true, nextCount: priorConsecutiveBlocks + 1, capped: false };
+}
+/**
+ * @implements A-SPEC-191 §14 (round 10)
+ * WHERE this hook keeps its state, and it is the project — not the shell.
+ *
+ * Measured: with a raw relative path, running a session from a subdirectory made this hook create
+ * `<cwd>/.ax/ledger/stop-guard.json` on every CLEAN turn. That directory is a project marker, so the
+ * NEXT tool call's walk-up stopped there, and the PreToolUse gate then classified nearly the whole
+ * real project as "outside the project" — roles policy, .mcp.json, the ledger, spec promotion and
+ * ordinary source writes all flipped from deny to allow, one turn after the session started. The
+ * round-9 anchor fix went into PreToolUse only; this hook quietly undid it.
+ */
+/**
+ * @implements A-SPEC-191 §19 (round 11, 3rd)
+ * The project this turn belongs to, or NULL when there is none to be found.
+ *
+ * Round-10 walked up for a `.ax` marker, and `resolveProjectRoot` returns its INPUT when the walk
+ * finds nothing. So on the first-class `--specs-dir docs/specs` deployment — where `.ax` may not
+ * exist at all (its contents are derived state the generated .gitignore ignores, and `.ax/roles` is
+ * optional) — a clean turn in a subdirectory wrote `<sub>/.ax/ledger/stop-guard.json` and thereby
+ * MINTED a project marker. From then on the nearest-marker walk stopped there: the real root could
+ * later gain its own `.ax` and still lose, and measured, that subdirectory session had No-Spec-No-Code
+ * and config-write open forever. §15(b) excused this on the premise that "nothing above is a
+ * project"; the premise was false — a real project above simply had no marker to find.
+ *
+ * So: look for the marker, then for the wired spec directory (the deployment's own evidence of where
+ * the project is), and if neither answers, say so. A hook that cannot find the project does not
+ * invent one; it keeps no state and falls back to the stateless one-shot guard.
+ */
+function findProjectRoot(specsDir) {
+    try {
+        const { resolveProjectRoot } = require('../project/root');
+        const r = resolveProjectRoot(process.cwd());
+        if (r.marker !== 'given')
+            return r.root;
+    }
+    catch { /* fall through to the specs-dir walk */ }
+    if (specsDir && !path.isAbsolute(specsDir)) {
+        let dir = process.cwd();
+        for (let hop = 0; hop < 64; hop++) {
+            if (fs.existsSync(path.join(dir, specsDir)))
+                return dir;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    // @implements A-SPEC-191 §21 (round 11) — `dirname(dirname(specsDir))` is the same two-segment
+    // arithmetic §18 deleted from `governanceLostPreflight`, and it came back on the absolute branch.
+    // On the first-class one-segment deployment (`--specs-dir specs`) it names the project's PARENT,
+    // and §19's own minting then plants `.ax/ledger/stop-guard.json` there — measured: a project at
+    // `<outer>/proj` (marker and all) had the anchor moved to `<outer>` by one clean turn. Cut a tail
+    // only after confirming it is there; otherwise ask the marker, and if nothing answers, say so.
+    if (specsDir && path.isAbsolute(specsDir) && fs.existsSync(specsDir)) {
+        const norm = specsDir.replace(/\\/g, '/').replace(/\/+$/, '');
+        if (/\/\.ax\/specs$/i.test(norm))
+            return path.dirname(path.dirname(norm));
+        try {
+            const { resolveProjectRoot } = require('../project/root');
+            const r = resolveProjectRoot(norm);
+            if (r.marker !== 'given')
+                return r.root;
+        }
+        catch { /* 표지가 없으면 짓지 않는다 */ }
+        return null;
+    }
+    return null;
+}
+/** The wired spec directory for this run, set once by the CLI so the lookups above can use it. */
+let WIRED_SPECS;
+/** Test seam for the same reason as the two exports below — the CLI sets this on a real run. */
+function __setWiredSpecsForTest(v) { WIRED_SPECS = v; }
+function stopProjectRoot() {
+    return findProjectRoot(WIRED_SPECS) ?? process.cwd();
+}
+/** null when no project could be found — nothing is written, nothing is minted. */
+function guardStatePath() {
+    const root = findProjectRoot(WIRED_SPECS);
+    return root === null ? null : path.join(root, '.ax', 'ledger', 'stop-guard.json');
+}
+const GUARD_STATE = () => guardStatePath() ?? path.join(process.cwd(), '.ax', 'ledger', 'stop-guard.json');
+// State is keyed by SESSION so two concurrent sessions in one repo don't share/reset each other's
+// count (adversarial finding MED-5). A different session id starts from 0.
+//
+// @implements A-SPEC-191 §18 (round 11) — keyed for READING is not keyed for STORING. The file held
+// ONE {sessionId, consecutiveBlocks} cell, so two sessions taking turns each read 0 (the id does not
+// match) and wrote 1 (overwriting the other) — the count could never reach the cap and the Stop gate
+// blocked FOREVER. That is precisely the unbounded loop H2 exists to prevent, on the ordinary
+// two-sessions-in-one-repo case, and round-10 widened it from same-cwd to project-wide by moving
+// every session into a single project-level file. One cell per session, oldest evicted.
+const GUARD_SESSIONS_MAX = 32;
+function readGuardState() {
+    try {
+        return JSON.parse(fs.readFileSync(GUARD_STATE(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function readGuardCount(sessionId) {
+    const s = readGuardState();
+    const entry = s.sessions?.[sessionId];
+    if (entry && Number.isInteger(entry.n) && entry.n >= 0)
+        return entry.n;
+    // Pre-§18 files carried a single cell; honour it for the session that owns it so an upgrade in
+    // mid-session does not silently reset a count the operator is already living with.
+    if (s.sessionId === sessionId && Number.isInteger(s.consecutiveBlocks) && (s.consecutiveBlocks ?? -1) >= 0) {
+        return s.consecutiveBlocks;
+    }
+    return 0;
+}
+// Returns whether the state actually persisted. If it did NOT, the caller must fall back to the
+// stateless one-shot guard (stop_hook_active) — otherwise an unwritable state file would make the
+// count always read 0 and the gate block FOREVER (adversarial finding MED-4: the exact infinite
+// loop H2 exists to prevent).
+/**
+ * Exported for the §19 race discriminator: the persistence layer was the untested half (round-11),
+ * and a test that can only reach it through a spawned hook cannot pin what the lock does.
+ */
+function writeGuardCount(sessionId, n) {
+    // @implements A-SPEC-191 §19 — no project, no state. Minting `<cwd>/.ax` to hold a counter is how
+    // the gate lost the project in the first place; returning false puts the caller on the stateless
+    // one-shot guard, which is the documented fallback for "the state did not persist".
+    const target = guardStatePath();
+    if (target === null)
+        return false;
+    try {
+        // @implements A-SPEC-191 §19 — read-modify-write under the SAME lock the findings ledger uses.
+        // Round-10 moved every session into one project-level file and round-11 gave each its own cell,
+        // but the merge was unguarded: two hooks overlapping meant the later writer dropped the other's
+        // cell, so a session's count kept resetting and the cap never fired — measured 12/12 consecutive
+        // blocks with three concurrent sessions, which is exactly the unbounded loop H2 exists to stop.
+        const { withLedgerLock } = require('../governance/ledger-lock');
+        return withLedgerLock(target, () => {
+            const prev = readGuardState();
+            const sessions = { ...(prev.sessions ?? {}) };
+            sessions[sessionId] = { n, at: Date.now() };
+            // Bounded: a long-lived repository must not accumulate a cell per session forever. The oldest
+            // are dropped, never the caller's own.
+            const ordered = Object.entries(sessions).sort((a, b) => b[1].at - a[1].at).slice(0, GUARD_SESSIONS_MAX);
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, JSON.stringify({ sessions: Object.fromEntries(ordered) }));
+            return true;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+// CLI entry: Claude Code passes Stop-hook JSON on stdin. Fail-open (never crash a turn).
+if (require.main === module) {
+    let buf = '';
+    process.stdin.on('data', (c) => (buf += c));
+    process.stdin.on('end', () => {
+        try {
+            const input = JSON.parse(buf || '{}');
+            const sessionId = typeof input.session_id === 'string' ? input.session_id : 'unknown-session';
+            // @implements A-SPEC-190 (round 8) — same wiring channel as the PreToolUse hook.
+            const { wiredSpecsDir } = require('./pre-tool-use');
+            // @implements A-SPEC-191 §16 (round 11) — the INPUTS move with the outputs, or the hook judges
+            // one tree and writes the verdict onto another. Round-10 moved the state paths to the project
+            // and left the spec path relative to the shell: a subdirectory turn then saw an EMPTY project,
+            // called the turn clean, and applied that clean verdict to the REAL root — deleting its
+            // constitution-debt record and reopening WRITE_CODE. Before round 10 the same miss was inert
+            // (it wrote to cwd too); the repair is what turned an inert miss into active laundering.
+            const wired = wiredSpecsDir(process.argv, process.env);
+            // The wiring is also EVIDENCE of where the project is (§19): a deployment that keeps its specs
+            // in `docs/specs` says so on this hook's own command line, and that is a marker no `.ax`
+            // gitignore can erase. Set before any path is resolved.
+            WIRED_SPECS = wired;
+            const specsDir = path.isAbsolute(wired) ? wired : path.join(stopProjectRoot(), wired);
+            // @implements A-SPEC-175
+            // BEFORE the constitution runs, because with the spec tree gone there are no articles to check
+            // and this hook simply exited 0 in silence — measured 2026-08-12, while the PreToolUse escape
+            // hatch justified itself by claiming this hook re-verifies. It does, but only when there is
+            // something to verify; a project whose ledger records approvals and whose specs have vanished
+            // is exactly the case that fell between the two.
+            const lost = governanceLostPreflight(specsDir, stopProjectRoot());
+            if (lost) {
+                process.stdout.write(JSON.stringify({ decision: 'block', reason: lost }));
+                process.stderr.write(`${lost}\n`);
+                return;
+            }
+            const specs = (0, pre_tool_use_1.readSpecsSync)(specsDir);
+            // H1 evidence: count EXECUTABLE test cases per anchored A-SPEC (countTestCases strips comments/
+            // strings — sham-resistant). A scan FAILURE yields `undefined` (ART-4 skipped this turn, true
+            // fail-open); a SUCCESSFUL scan that finds nothing yields `{}` and DOES enforce — all evidence
+            // vanishing while approved T-SPECs exist is a genuine violation state, not a hiccup.
+            let testCasesByAspec;
+            try {
+                testCasesByAspec = {};
+                for (const [file, ids] of Object.entries((0, test_scope_1.scanTestAnchors)(stopProjectRoot()))) {
+                    let n = 0;
+                    // Pass the path: the counter picks the test framework from the extension, and without it
+                    // every non-JS suite counts zero and ART-4 reports "no tests" for a project that has them.
+                    try {
+                        n = (0, test_scope_1.countTestCases)(fs.readFileSync(file, 'utf8'), file);
+                    }
+                    catch { /* unreadable file: skip */ }
+                    for (const id of ids)
+                        testCasesByAspec[id] = (testCasesByAspec[id] ?? 0) + n;
+                }
+            }
+            catch {
+                testCasesByAspec = undefined;
+            }
+            // EXECUTION evidence (ART-4 upgrade): usable only when produced at the CURRENT git HEAD, so a
+            // stale record can never vouch for changed code. Absent/stale -> syntactic fallback.
+            let executedByAspec;
+            try {
+                const head = (0, node_child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], { cwd: stopProjectRoot(), stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+                const ev = (0, test_evidence_1.readTestEvidence)(stopProjectRoot());
+                if ((0, test_evidence_1.isFresh)(ev, head))
+                    executedByAspec = ev.executedByAspec;
+            }
+            catch {
+                executedByAspec = undefined;
+            }
+            // Provenance-chain verification (fail-open: a verify error skips the check, never crashes).
+            let provenance;
+            // @implements A-SPEC-148
+            // Verify EVERY replica chain: after the split a single file is only part of the ledger, and a
+            // broken chain elsewhere must still block finishing. `ok` collapses the per-chain results in
+            // the safe direction — one bad chain means the audit trail is not intact.
+            try {
+                const { FileLedgerStore } = require('../governance/ledger-store');
+                // Same rule for the tamper check (round-11): verifying the shell's `.ax/ledger` let a forged
+                // chain in the real project pass unseen from a subdirectory.
+                const r = new FileLedgerStore(path.join(stopProjectRoot(), path.dirname(provenance_chain_1.PROVENANCE_FILE))).verifyAll();
+                provenance = r.ok ? { ok: true } : { ok: false, detail: r.broken.map((b) => `${b.replicaId ?? 'legacy'}: ${b.detail ?? 'broken'}`).join('; ') };
+            }
+            catch {
+                provenance = undefined;
+            }
+            // @implements A-SPEC-160 — supply the findings ledger so ART-6 can see judgements sealed on a
+            // diverged server. An article nobody feeds is a dead article; ADR-014's discipline applies to
+            // the constitution too.
+            let findings;
+            let findingsUnreadable = false;
+            try {
+                const { FindingsLedger } = require('../review/findings');
+                findings = new FindingsLedger(path.join(stopProjectRoot(), '.ax', 'ledger', 'findings.jsonl')).list();
+            }
+            catch {
+                findingsUnreadable = true;
+            } // @implements A-SPEC-191 (§4a) — list() absorbs ENOENT; a throw means the ledger EXISTS and cannot be read, which must block, not launder
+            const out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable });
+            const guard = decideStopGuard(out.block, readGuardCount(sessionId));
+            const persisted = writeGuardCount(sessionId, guard.nextCount);
+            // @implements A-SPEC-134 — the cap-yield is no longer silent: a clean turn clears any debt, a
+            // give-up records the unresolved articles so WRITE_CODE is blocked until the constitution is
+            // clean again. Fail-open: a debt-state write error never changes the stop verdict.
+            try {
+                const debt = stopDebtAction(out, guard);
+                if (debt.action === 'clear')
+                    (0, constitution_debt_1.clearDebt)(stopProjectRoot());
+                else if (debt.action === 'write')
+                    (0, constitution_debt_1.writeDebt)(stopProjectRoot(), debt.articles);
+            }
+            catch { /* debt bookkeeping must never break the gate */ }
+            if (guard.block && !persisted && input.stop_hook_active) {
+                // State cannot persist -> the counter can never advance. Degrade to the stateless one-shot
+                // guard instead of blocking forever: stop_hook_active means we already blocked once.
+                process.stderr.write(`[Holmes-Kit] governance gate yielding (guard state unwritable, one-shot fallback) — issues remain UNRESOLVED:\n${out.reason ?? ''}\n`);
+                process.exitCode = 0;
+                return;
+            }
+            if (guard.block) {
+                process.stdout.write(JSON.stringify({ decision: 'block', reason: out.reason }));
+                process.stderr.write(`${out.reason}\n`);
+            }
+            else if (guard.capped) {
+                process.stderr.write(`[Holmes-Kit] governance gate YIELDING after ${exports.MAX_CONSECUTIVE_BLOCKS} consecutive blocks — issues remain UNRESOLVED:\n${out.reason ?? ''}\n`);
+            }
+            // exitCode, NOT process.exit(): exit() tears the process down before large async stdout
+            // writes flush — a >64KB block decision reached the hook runner as TRUNCATED (invalid) JSON
+            // and the block silently became a pass (round-3). Natural exit drains the pipe first.
+            process.exitCode = 0;
+        }
+        catch (err) {
+            process.stderr.write(`[Holmes-Kit Stop Hook] Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 0; // fail-open — exitCode 로 파이프를 비운 뒤 자연 종료(잘림 방지)
+        }
+    });
+}

package/dist/holmes/mcp/basis.js

@@ -0,0 +1,162 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASIS_DIVERGED = exports.MAX_BUILD_LEN = exports.MAX_DIGEST_LEN = void 0;
+exports.basisDiverged = basisDiverged;
+exports.loadedBuildId = loadedBuildId;
+exports.collectBasis = collectBasis;
+exports.basisDigest = basisDigest;
+exports.withBasis = withBasis;
+// @implements A-SPEC-156
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * There is deliberately NO graph axis. `RtmGraph` is in-memory only (ADR-011 — a derived index,
+ * rebuilt every time), so the graph is a FUNCTION of specs and scan and cannot diverge from them
+ * independently. Including it would mean either an always-`?` field or a rebuild per call: token
+ * cost with no information in the first case, a constant-I/O violation in the second.
+ */
+/**
+ * Cap on the digest. A basis rides on every one of the tools, so its size multiplies across a
+ * session — this bound is what keeps "carry the basis" compatible with REQ-122's requirement that
+ * the harness be net-token-positive, rather than opposed to it.
+ */
+exports.MAX_DIGEST_LEN = 64;
+/**
+ * Cap on the build id alone. Truncating the whole digest at the end would eat the trailing axes, so
+ * a long build id could make `x:` disappear entirely and the digest would read as if that axis had
+ * never existed — the exact silent-omission failure `?` exists to prevent. Bounding the variable
+ * part instead keeps the structure intact whatever the stamp looks like.
+ */
+exports.MAX_BUILD_LEN = 32;
+/**
+ * @implements A-SPEC-160
+ * Appended when the loaded and on-disk builds are BOTH known and differ.
+ *
+ * This is an observation, not a verdict, and the distinction matters: REQ-156 deliberately refused to
+ * let the server decide whether it was stale, because that logic would be running inside the stale
+ * build. Reporting that two measured values disagree is a fact; what to do about it is ART-6's call.
+ *
+ * An unknown disk build never carries the marker. Reading absence as divergence would fire on every
+ * tool but `review_record` — none of the others read disk — and an article that fires constantly is
+ * one people route around within a day.
+ */
+exports.BASIS_DIVERGED = '/!';
+/** Reads the marker back out of a sealed digest. */
+function basisDiverged(digest) {
+    return typeof digest === 'string' && digest.endsWith(exports.BASIS_DIVERGED);
+}
+const BUILD_ID_FILE = path.join('dist', '.build-id');
+/**
+ * The build identity of the code that is RUNNING. Read once at start-up by the server, never per
+ * call: hashing `dist` on every request buys I/O for no new information, and mtime changes on a
+ * checkout or a copy, which would manufacture divergence that is not there.
+ *
+ * An unstamped build is reported as `unknown` rather than guessed. Absence is a fact too, and a
+ * fabricated id would be worse than none — it would look like agreement.
+ */
+function loadedBuildId(root) {
+    try {
+        const raw = fs.readFileSync(path.join(root, BUILD_ID_FILE), 'utf8').trim();
+        if (raw === '')
+            return 'unknown';
+        return raw.length <= exports.MAX_BUILD_LEN ? raw : `${raw.slice(0, exports.MAX_BUILD_LEN - 1)}~`;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Runs one axis, converting any failure into absence. */
+const attempt = (f) => {
+    if (!f)
+        return undefined;
+    try {
+        return f();
+    }
+    catch {
+        // Basis is diagnostic. If collecting it could fail a request, adding it would make the harness
+        // LESS available than before — the exact opposite of the point.
+        return undefined;
+    }
+};
+function collectBasis(ctx) {
+    const basis = { loadedBuild: ctx.loadedBuild ?? (ctx.root ? loadedBuildId(ctx.root) : 'unknown') };
+    const scanFp = attempt(ctx.scanFp);
+    if (scanFp !== undefined)
+        basis.scanFp = scanFp;
+    const specs = attempt(ctx.specs);
+    if (specs !== undefined)
+        basis.specs = specs;
+    // The on-disk value is deliberately NOT compared here. If the server rendered the "am I stale?"
+    // verdict, that logic would itself be running inside the stale build — the exact circle that let
+    // today's defect answer confidently. Both values are exposed; the caller draws the conclusion.
+    if (ctx.root)
+        basis.diskBuild = loadedBuildId(ctx.root);
+    return basis;
+}
+/**
+ * `b:<build>/s:<scanFp>/x:<specs>`
+ *
+ * Short by design: a caller compares the value against another and learns that something diverged
+ * without needing to interpret any field. An unmeasured axis renders as `?` rather than being
+ * dropped — omitting it would let a reader take "these two matched" for agreement when the third
+ * was never measured at all.
+ */
+function basisDigest(b) {
+    const diverged = b.diskBuild !== undefined && b.diskBuild !== b.loadedBuild ? exports.BASIS_DIVERGED : '';
+    const digest = `b:${b.loadedBuild}/s:${b.scanFp ?? '?'}/x:${b.specs ?? '?'}`;
+    const capped = digest.length <= exports.MAX_DIGEST_LEN ? digest : `${digest.slice(0, exports.MAX_DIGEST_LEN - 1)}~`;
+    // The marker is appended AFTER capping so a long build id can never truncate it away — losing it
+    // would silently downgrade a divergent record to an agreeing one, which is the one direction this
+    // must never fail in.
+    return capped + diverged;
+}
+/**
+ * Attaches a basis to a handler's result.
+ *
+ * Exported and pure so the contract is testable without a handler that exercises each branch. The
+ * array guard in particular has no live caller today — every tool returns an object — and an
+ * untested guard is one a later change deletes for free. Spreading an array into an object yields
+ * `{0:…, 1:…, basis}`, silently reshaping a response into something no caller can read, so the
+ * branch has to survive on its own merits rather than on nobody having tried it yet.
+ */
+function withBasis(fn, basisOf) {
+    return async (a) => {
+        const out = await fn(a);
+        if (out === null || typeof out !== 'object' || Array.isArray(out))
+            return out;
+        return { ...out, basis: basisDigest(basisOf(a)) };
+    };
+}