@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/mcp/validate-args.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEAR_CACHE_SIZE = void 0;
+exports.nearKeys = nearKeys;
+exports.nearestKey = nearestKey;
+exports.validateArgs = validateArgs;
+const typeOf = (v) => Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v;
+/**
+ * Nearest declared key by edit distance, or null.
+ *
+ * Threshold 2: `aspecId`→`aspec` (distance 2) and `mappings`→`mapping` (distance 1) are the
+ * measured mistakes this exists for. Anything farther is guessing, and a wrong suggestion is worse
+ * than none. Ties resolve to the first declared key, which keeps the output deterministic.
+ */
+/** Suggestion work is BOUNDED: keys longer than this are never candidates (adversarial 50k-char
+ * keys measured seconds of Levenshtein on the single-threaded server), and a length gap beyond the
+ * threshold cannot be within distance 2, so it is pruned before any table is built. */
+const KEY_MAX = 64;
+// Damerau (round-10): an adjacent transposition is ONE slip of the fingers, and counting it as two
+// edits is why `actro` needed a distance-2 budget to reach `actor` — the same budget that made
+// `rule`/`line`/`port` "typos" of `file`/`root`.
+const dist = (a, b) => {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 0; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return dp[a.length][b.length];
+};
+/**
+ * ALL declared keys within edit distance 1..2 of `unknown`, nearest first (ties keep declared
+ * order). The single-best shape let a SUPPLIED sibling shadow an absent key's typo into a silent
+ * pass — round-5 measured: risk_check's `actro` tied to the supplied `action` (declared first), so
+ * the absent `actor` never entered the judgment and the ledger lost its attribution.
+ */
+function nearKeysWithDist(unknown, declared) {
+    if (unknown.length > KEY_MAX)
+        return [];
+    const hits = [];
+    for (const d of declared) {
+        if (d.length > KEY_MAX || Math.abs(d.length - unknown.length) >= 3)
+            continue;
+        const dd = dist(unknown, d);
+        // @implements A-SPEC-189 §7 (round 10) — the tolerance scales with the SHORTER name. A flat
+        // distance of 2 is most of a four-letter word: measured, advertising `file`/`specRef` on a
+        // finding turned `line`, `rule`, `fix`, `title` into "typos" and refused perfectly ordinary
+        // findings, and `port`/`host`/`cost`/`sort`/`tool` became typos of spec_create's `root`,
+        // breaking its caller-wins frontmatter contract. Two edits away from a short word is usually a
+        // DIFFERENT word — except when one name merely extends the other (`te`→`test`,
+        // `aspecId`→`aspec`), which is a slip of scope, not a different word.
+        const extendsOther = unknown.startsWith(d) || d.startsWith(unknown);
+        const budget = extendsOther || Math.min(unknown.length, d.length) > 5 ? 2 : 1;
+        if (dd > 0 && dd <= budget)
+            hits.push({ d, dd });
+    }
+    return hits.sort((a, b) => a.dd - b.dd);
+}
+function nearKeys(unknown, declared) {
+    return nearKeysWithDist(unknown, declared).map((h) => h.d);
+}
+function nearestKey(unknown, declared) {
+    return nearKeys(unknown, declared)[0] ?? null;
+}
+/** Cap on rendered violation items — the reason enters context on every refusal (REQ-183 rule). */
+const ITEM_CAP = 8;
+// @implements A-SPEC-189 §6 — `nearKeysWithDist` is a pure function of (unknown key, declared
+// keys), and a large payload repeats the SAME unknown key across thousands of array elements
+// (round-9 measured 262k keys, one request holding the single-threaded server for seconds). A
+// memo keyed by both operands removes that repetition WITHOUT bounding anything: no verdict
+// depends on how many keys came before, which is the property round-4 and round-5 were withdrawn
+// to protect.
+const NEAR_CACHE = new Map();
+/** 시험용 관측점: 요청이 끝난 뒤 메모가 비어 있음을 고정한다(§7f). */
+const NEAR_CACHE_SIZE = () => NEAR_CACHE.size;
+exports.NEAR_CACHE_SIZE = NEAR_CACHE_SIZE;
+function nearCache(u, declared) {
+    // Round-10: a key over KEY_MAX computes nothing (nearKeysWithDist returns [] immediately), so
+    // caching it bought zero and held the attacker's bytes — measured 38.6 MB still resident after
+    // the request ended. Nothing to compute, nothing to remember.
+    if (u.length > KEY_MAX)
+        return [];
+    const key = `${u}\u0000${declared.join('\u0001')}`;
+    const hit = NEAR_CACHE.get(key);
+    if (hit)
+        return hit;
+    const computed = nearKeysWithDist(u, declared);
+    if (NEAR_CACHE.size > 4096)
+        NEAR_CACHE.clear(); // 메모는 캐시지 원장이 아니다
+    NEAR_CACHE.set(key, computed);
+    return computed;
+}
+function judgeObject(path, schema, value, out) {
+    const props = schema.properties ?? {};
+    const declared = Object.keys(props);
+    const present = Object.keys(value);
+    // NO scan cap (round-5 HIGH): slicing unknown keys made the typo REFUSAL insertion-order
+    // dependent — 32 pad keys before `dryrun` flipped the same call from refusal to silent pass.
+    // Judgment must not depend on where a key sits. Cost stays bounded without it: KEY_MAX excludes
+    // long keys, the length-gap prune skips dissimilar pairs, and declared-key lists are short.
+    const unknownKeys = present.filter((k) => !declared.includes(k));
+    // additionalProperties: true is an EXPLICIT contract that extra keys are data (spec_create's
+    // caller-wins frontmatter) — no typo judgement may fire there.
+    const extrasAreData = schema.additionalProperties === true;
+    const required = schema.required ?? [];
+    // ASSIGNMENT, not a target-first map (round-8): every earlier shape let one unknown key render
+    // on several lines (bark → mark AND base), let insertion order drop a second typo's line
+    // outright (ro preempted root, roo vanished), and let a d2 first-comer swallow a d1 typo's
+    // target. The contract is per UNKNOWN key: at most ONE line, aimed at its NEAREST ABSENT
+    // declared key; if its nearest candidates are all SUPPLIED, the extra is data (§5c). Ties
+    // prefer the absent candidate, then declared order — deterministic and order-independent.
+    //
+    // NO global budget (round-4) and NO per-object scan cap (round-5): both made a REFUSAL depend
+    // on where the key sat. The surviving DoS bounds are KEY_MAX and the length-gap prune;
+    // declared-key lists are short, so cost is linear in input size with a small constant.
+    const isAbsent = (k) => value[k] === undefined || value[k] === null;
+    const assign = new Map(); // unknown key -> its one absent target
+    const assignDist = new Map();
+    for (const u of unknownKeys) {
+        const cands = nearCache(u, declared);
+        if (cands.length === 0)
+            continue;
+        const minD = cands[0].dd;
+        const absentAtMin = cands.filter((c) => c.dd === minD).find((c) => isAbsent(c.d));
+        if (absentAtMin) {
+            assign.set(u, absentAtMin.d);
+            assignDist.set(u, minD);
+            continue;
+        }
+        // @implements A-SPEC-189 §7 (round 10) — §5c says an extra beside a SUPPLIED near-name is data,
+        // and that stays true where extras are data by contract. But a key ONE edit from a declared
+        // CONTROL key, in a schema whose extras become a stored document, is the measured harm itself:
+        // `rot: /Users/<name>/…` reached a git-shared frontmatter while `root` was supplied too.
+        if (extrasAreData && minD === 1) {
+            assign.set(u, cands[0].d);
+            assignDist.set(u, minD);
+        }
+    }
+    // @implements A-SPEC-189 §6 — every unknown key is NAMED exactly once, and which name comes
+    // first is decided by distance then alphabet, never by where the key sat in the object. Round-9
+    // measured the old shape: `find()` over insertion order cited a distance-2 typo while the
+    // distance-1 typo aimed at the same missing key evaporated from the message entirely, so the same
+    // key set refused with different text depending on the caller's key order.
+    const spokes = new Map(); // absent target -> its typos, deterministic order
+    for (const [u, target] of assign) {
+        const list = spokes.get(target);
+        if (list)
+            list.push(u);
+        else
+            spokes.set(target, [u]);
+    }
+    for (const list of spokes.values()) {
+        list.sort((x, y) => (assignDist.get(x) - assignDist.get(y)) || (x < y ? -1 : x > y ? 1 : 0));
+    }
+    // Names are quoted whole with a counted omission label — a cut list reads as a complete one.
+    const NAME_BUDGET = 3;
+    const quoteAll = (prefix, us) => {
+        const kept = us.slice(0, NAME_BUDGET).map((u) => `${prefix}${u}`);
+        const omitted = us.length - kept.length;
+        return kept.join(', ') + (omitted > 0 ? ` 외 ${omitted}건` : '');
+    };
+    // NOTE: no `rendered` bookkeeping — each unknown key holds exactly ONE assigned target, so it
+    // can appear in the required loop XOR the optional loop, never both (round-8 review would flag
+    // a defensive duplicate guard as an equivalent mutant, and it would be right).
+    for (const req of required) {
+        const v = value[req];
+        // null/undefined are ABSENCE, not a type violation: what the caller must do is supply the
+        // value, and the sentence should say that rather than argue about null's type.
+        if (v === undefined || v === null) {
+            const desc = props[req]?.description;
+            const us = spokes.get(req) ?? [];
+            out.push({
+                path: path ? `${path}.${req}` : req,
+                message: `이(가) 없습니다${desc ? ` — "${desc}"` : ''}`,
+                suggestion: us.length
+                    ? `${quoteAll(path ? `${path}.` : '', us)}는 알 수 없는 키 — ${req}을(를) 잘못 쓴 것 아닙니까`
+                    : undefined,
+            });
+        }
+    }
+    // @implements A-SPEC-189 (round 2) — the success-shaped no-op survives through OPTIONAL keys
+    // too: `dryrun: false` silently leaves dryRun's default true and the caller believes a write
+    // happened. Each unknown key renders through its ASSIGNED target exactly once; a typo whose
+    // target is a missing required key folds into that violation's suggestion above (one mistake,
+    // one line) — a second typo of the same missing key stays silent rather than duplicating the
+    // same fix instruction.
+    // @implements A-SPEC-189 §6 — `additionalProperties: true` says extra keys are DATA, and that
+    // stays true for names unlike anything declared. It cannot also mean 'a misspelling of a declared
+    // CONTROL key is data': round-9 measured `rot: /Users/<name>/…` on spec_create being written into
+    // a git-shared document as frontmatter — a machine-local absolute path, no refusal, no trace. A
+    // near-miss of a DECLARED key is refused everywhere; only unrelated names travel as data.
+    // Round-10: the round-9 determinism reached only the missing-REQUIRED branch. This loop still
+    // walked `unknownKeys` in the caller's insertion order and pushed one line per typo, so the same
+    // key set rendered differently per permutation (measured across 13 tools), four typos of one
+    // target repeated the identical fix instruction four times, and — worse — which typo survived the
+    // ITEM_CAP truncation was decided by key order. One line per TARGET, targets in declared order,
+    // names ordered by distance then alphabet: the same contract the required branch already keeps.
+    for (const target of declared) {
+        const us = spokes.get(target);
+        if (!us || us.length === 0)
+            continue;
+        // The missing-required line already carries this fix — but ONLY when the required key is
+        // actually missing. Round-11 measured the orphan: on spec_create (extras become a stored
+        // document) a one-edit typo of a SUPPLIED required key — `titl`, `typ`, `idd` — was assigned
+        // here, rendered nowhere, and written verbatim into a git-shared frontmatter. Same harm as
+        // round-9's `rot`, one key over.
+        if (required.includes(target) && (value[target] === undefined || value[target] === null))
+            continue;
+        out.push({
+            path: path ? `${path}.${us[0]}` : us[0],
+            message: us.length === 1
+                ? `은(는) 알 수 없는 키입니다 — ${target}을(를) 잘못 쓴 것 아닙니까`
+                : `외 ${quoteAll('', us.slice(1))}은(는) 알 수 없는 키입니다 — ${target}을(를) 잘못 쓴 것 아닙니까`,
+        });
+    }
+    for (const [key, prop] of Object.entries(props)) {
+        const v = value[key];
+        if (v === undefined || v === null)
+            continue; // absence is required's business
+        const p = path ? `${path}.${key}` : key;
+        if (prop.type && typeOf(v) !== prop.type) {
+            out.push({ path: p, message: `의 타입이 선언(${prop.type})과 다릅니다 — 받은 것: ${typeOf(v)}` });
+            continue;
+        }
+        if (prop.enum && !prop.enum.includes(v)) {
+            out.push({ path: p, message: `이(가) 허용 목록 밖입니다 — 허용: ${prop.enum.join(' | ')}` });
+            continue;
+        }
+        if (prop.type === 'array' && Array.isArray(v) && prop.items) {
+            const itemSchema = prop.items;
+            const structured = Boolean(itemSchema.properties || itemSchema.required);
+            v.forEach((item, i) => {
+                if (structured && typeOf(item) === 'object') {
+                    judgeObject(`${p}[${i}]`, itemSchema, item, out);
+                }
+                else if (itemSchema.type && typeOf(item) !== itemSchema.type) {
+                    // Scalar item schemas (strArray) were the round-2 hole: declared items:{type:'string'}
+                    // let numeric elements through to handlers that then failed as success-shaped garbage.
+                    out.push({ path: `${p}[${i}]`, message: `의 타입이 선언(${itemSchema.type})과 다릅니다 — 받은 것: ${typeOf(item)}` });
+                }
+            });
+        }
+        if (prop.type === 'object' && typeOf(v) === 'object' && (prop.properties || prop.required)) {
+            judgeObject(p, prop, v, out);
+        }
+    }
+}
+function validateArgs(toolName, schema, args) {
+    // Defense-in-depth for direct/in-process misuse. Over the wire the MCP SDK's request schema
+    // already rejects non-object `arguments` at the JSON-RPC layer, so this line is unreachable from
+    // a stdio client (round-3 [13]) — it guards the exported function's own contract, not the wire.
+    if (typeOf(args) !== 'object') {
+        return { ok: false, reason: `${toolName}의 인자는 객체여야 합니다 — 받은 것: ${typeOf(args)}` };
+    }
+    const out = [];
+    try {
+        judgeObject('', schema, args, out);
+    }
+    finally {
+        // The memo is a within-request optimisation: a large payload repeats the same unknown key
+        // thousands of times. It is NOT a session cache, and holding a caller's key bytes after the
+        // answer is sent is storage nobody asked for (round-10).
+        NEAR_CACHE.clear();
+    }
+    if (out.length === 0)
+        return { ok: true };
+    // All violations in ONE refusal (no round trips), bounded like every other rendered list here:
+    // whole items or none, and past the cap a count instead of a tail.
+    const shown = out.slice(0, ITEM_CAP);
+    const lines = shown.map((v) => `${v.path}${v.message}${v.suggestion ? ` (${v.suggestion})` : ''}`);
+    const more = out.length > shown.length ? ` 외 ${out.length - shown.length}건.` : '';
+    return {
+        ok: false,
+        reason: `${toolName} 호출이 선언된 스키마와 다릅니다: ${lines.join('; ')}${more}`,
+    };
+}

package/dist/holmes/messages/registry.js

@@ -0,0 +1,50 @@
+"use strict";
+// @implements A-SPEC-195
+/**
+ * Holmes-Kit Centralized Message Registry
+ *
+ * Single Source of Truth for all user/agent-facing refusal, validation, and diagnostic messages.
+ * Unified 3-Part English Format: [Subsystem] Title — Technical Cause — Next Action
+ * Internal Holmes-Kit Spec IDs are strictly masked unless HOLMES_DEBUG=1 is set.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MESSAGES = void 0;
+function formatDebugTrace(internalSpecTrace) {
+    if (process.env.HOLMES_DEBUG === '1' && internalSpecTrace) {
+        return `\n  [trace: ${internalSpecTrace}]`;
+    }
+    return '';
+}
+function truncateTitle(title, maxLen = 30) {
+    if (!title)
+        return '';
+    return title.length > maxLen ? `${title.slice(0, maxLen)}...` : title;
+}
+function toTspecId(aspecId) {
+    const numMatch = aspecId.match(/\d+/);
+    return numMatch ? `T-SPEC-${numMatch[0]}` : `T-SPEC-${aspecId}`;
+}
+exports.MESSAGES = {
+    SECURITY_ENV_ACCESS: (internalTrace) => `[Holmes-Kit Security] Direct Access to Process Environment Restricted — Subshell command execution contains environment variable access patterns — Next Action: Security secrets (HOLMES_APPROVAL) are scrubbed from subshell environments. Inject mock environment objects within test runner scope if needed.${formatDebugTrace(internalTrace)}`,
+    INTEGRITY_CONFIG_EDIT: (file = '.mcp.json', internalTrace) => `[Holmes-Kit Integrity] Direct Modification of '${file}' Restricted — Harness hook and server configuration is protected against unauthenticated edits — Next Action: Request out-of-band operator configuration or approval.${formatDebugTrace(internalTrace)}`,
+    GOVERNANCE_LEDGER_DESTRUCTION: (path = '.ax/', internalTrace) => `[Holmes-Kit Audit] Governance Path Destruction Restricted — Removal command targets protected governance ledger directory '${path}' — Next Action: Governance state cannot be deleted directly. Use 'spec_approve' or governance tools.${formatDebugTrace(internalTrace)}`,
+    SEAL_SELF_APPROVAL_RESTRICTED: (specId, internalTrace) => `[Holmes-Kit Seal] Specification Self-Approval Restricted — Creating or promoting '${specId}' to status 'approved' requires out-of-band operator approval (cannot self-approve) — Next Action: Author specification as 'draft', then approve out-of-band via 'spec_approve ${specId}'.${formatDebugTrace(internalTrace)}`,
+    SEAL_APPROVED_SPEC_MUTATION: (specId, specTitle, internalTrace) => {
+        const boundSpec = specTitle ? `'${specId}' (${truncateTitle(specTitle)})` : `'${specId}'`;
+        return `[Holmes-Kit Seal] Approved Specification Modification Restricted — Specification ${boundSpec} is cryptographically sealed (status: approved) — Next Action: Update specification status to 'draft' before editing, or re-approve via 'spec_approve ${specId}' after changes.${formatDebugTrace(internalTrace)}`;
+    },
+    GOVERNANCE_UNAPPROVED_TSPEC: (tspecId, aspecId, aspecTitle, internalTrace) => {
+        const boundSpec = aspecTitle ? `'${aspecId}' (${truncateTitle(aspecTitle)})` : `'${aspecId}'`;
+        return `[Holmes-Kit Governance] Linked Test Specification Not Approved — Test specification '${tspecId}' linked to ${boundSpec} is not approved — Next Action: Approve the test specification via 'spec_approve ${tspecId}'.${formatDebugTrace(internalTrace)}`;
+    },
+    GOVERNANCE_MISSING_TSPEC: (aspecId, aspecTitle, internalTrace) => {
+        const boundSpec = aspecTitle ? `'${aspecId}' (${truncateTitle(aspecTitle)})` : `'${aspecId}'`;
+        const targetTspec = toTspecId(aspecId);
+        return `[Holmes-Kit Governance] Missing Test Specification — Specification ${boundSpec} lacks an approved linked test specification — Next Action: Create a mirroring T-SPEC and approve it via 'spec_approve ${targetTspec}'.${formatDebugTrace(internalTrace)}`;
+    },
+    VALIDATION_MISSING_REQUIRED: (paramPath, description) => `validate-args: parameter '${paramPath}' is required${description ? ` — "${description}"` : ''}`,
+    VALIDATION_TYPO_SUGGESTION: (unknownKey, suggestedKey) => `validate-args: '${unknownKey}' is an unknown property — did you mean '${suggestedKey}'?`,
+    VALIDATION_ENUM_INVALID: (paramName, value, allowedValues) => `validate-args: value '${value}' for '${paramName}' is invalid — allowed values: [${allowedValues.map((v) => `'${v}'`).join(', ')}]`,
+    VALIDATION_FOREIGN_ROOT: (root, boundRoot) => `foreign-root: specified root '${root}' is outside the bound project root '${boundRoot}'`,
+    LEGACY_REVERSE_DRAFT_PARENT: () => `parentReqId is required. A REQ states business intent... write the REQ first, then re-run with its id`,
+};

package/dist/holmes/project/baseline.js

@@ -0,0 +1,210 @@
+"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.BASELINE_DIR = void 0;
+exports.baselineDigest = baselineDigest;
+exports.writeBaseline = writeBaseline;
+exports.isBaselineTrusted = isBaselineTrusted;
+exports.readBaseline = readBaseline;
+exports.shouldRecordBaseline = shouldRecordBaseline;
+exports.listBaselines = listBaselines;
+// @implements A-SPEC-128
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const ledger_store_1 = require("../governance/ledger-store");
+/**
+ * A NAMED reference point: "the tree as it was when this label was taken".
+ *
+ * This is the piece that makes change analysis possible without version control, and it adds no new
+ * machinery — `HashCache` already persists sha256-per-file and `ScanFileCache` stores the same hash
+ * beside each file's symbols. What was missing is a NAME, so a caller can ask "what changed since the
+ * last verified state" instead of "what changed since HEAD~1".
+ *
+ * That naming is also why this is an improvement INSIDE a git project. `HEAD~1` is a proxy for "what I
+ * have been working on" that depends entirely on commit habits — ten commits or none change the
+ * answer. `last-green`, written only when a run actually passed, does not.
+ *
+ * Storage is derived state under `.ax/state/`: reconstructable, machine-local, gitignored. It is not
+ * project content and must never be committed.
+ */
+exports.BASELINE_DIR = path.join('.ax', 'state', 'baselines');
+/**
+ * Labels arrive from tool input and become a filename, so a traversing label would write a file
+ * anywhere on the host. Restricted to one safe path segment; anything else is refused loudly.
+ */
+const LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function assertLabel(label) {
+    if (typeof label !== 'string' || !LABEL_RE.test(label) || label === '.' || label === '..') {
+        throw new Error(`baseline: invalid label ${JSON.stringify(label)} — use letters, digits, dot, dash or underscore`);
+    }
+}
+const fileFor = (root, label) => path.join(root, exports.BASELINE_DIR, `${label}.json`);
+/**
+ * @implements A-SPEC-134
+ * The tamper-evidence digest a baseline is anchored by: sha256 of the key-sorted files map. NOT the
+ * whole record (takenAt is a timestamp, not content) — only the file→hash mapping the scope narrows
+ * against. Editing any file entry changes this digest, and the anchor on the append-only chain will
+ * no longer match. Pure, key-order-insensitive.
+ */
+function baselineDigest(files) {
+    const sorted = {};
+    for (const k of Object.keys(files).sort())
+        sorted[k] = files[k];
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(JSON.stringify(sorted), 'utf8').digest('hex')}`;
+}
+const ledgerFor = (root) => path.join(root, '.ax', 'ledger', 'provenance.jsonl');
+/** Write (or replace) a labelled baseline. One label holds exactly one reference point. */
+function writeBaseline(root, label, files) {
+    assertLabel(label);
+    // Keys sorted so the stored file is byte-stable for the same input; a diffable baseline is easier
+    // to inspect, and instability here would show up as noise in any tooling that reads it.
+    const sorted = {};
+    for (const k of Object.keys(files).sort())
+        sorted[k] = files[k];
+    const baseline = { label, takenAt: new Date().toISOString(), files: sorted };
+    fs.mkdirSync(path.dirname(fileFor(root, label)), { recursive: true });
+    fs.writeFileSync(fileFor(root, label), `${JSON.stringify(baseline, null, 2)}\n`);
+    // @implements A-SPEC-134
+    // Anchor the digest on the append-only provenance chain. A ledger failure must NOT fail the
+    // baseline write — the baseline stays usable, just UNANCHORED, which read-verification treats as
+    // untrusted → full scope (the safe direction). Never trade a working baseline for a crash here.
+    try {
+        // @implements A-SPEC-148 — writes go to THIS replica's chain; the legacy file is read-only now.
+        new ledger_store_1.FileLedgerStore(path.dirname(ledgerFor(root))).append({
+            ts: baseline.takenAt, actor: 'holmes-kit', kind: 'baseline-recorded',
+            summary: `baseline ${label} recorded (${Object.keys(sorted).length} files)`,
+            inputs: [label, baselineDigest(sorted)], rationale: '', authorization: '',
+        });
+    }
+    catch { /* unanchored baseline degrades to untrusted on read, never throws the write */ }
+    return baseline;
+}
+/**
+ * @implements A-SPEC-134
+ * Is this baseline still the one that was recorded? Recompute its digest from the on-disk files and
+ * confirm a `baseline-recorded` chain entry carries that (label, digest). A hand-edit changes the
+ * digest and no entry matches → false. A missing baseline or missing/unreadable chain → false:
+ * cannot-verify is not permission to narrow (the caller degrades to full scope).
+ */
+function isBaselineTrusted(root, label, ledgerFile) {
+    const baseline = readBaseline(root, label);
+    if (!baseline)
+        return false;
+    const digest = baselineDigest(baseline.files);
+    // @implements A-SPEC-148
+    // The anchor is searched across EVERY replica chain. Writes now land in this machine's own chain,
+    // so scanning only the legacy file would fail to find an anchor this very process just wrote.
+    let events;
+    try {
+        const { FileLedgerStore } = require('../governance/ledger-store');
+        events = new FileLedgerStore(path.dirname(ledgerFile)).loadAll();
+    }
+    catch {
+        return false;
+    }
+    // @implements A-SPEC-134
+    // The anchor is only trustworthy if the chain it sits on is INTACT. Adversarial review: an attacker
+    // who hand-appends a `baseline-recorded` entry with a forged digest would otherwise be "found" here
+    // — but forging a valid hash link needs HOLMES_LEDGER_KEY, so a hand-append breaks verify(). Tie
+    // baseline trust to chain integrity: a broken chain trusts NO baseline (degrade to full scope),
+    // which is the safe direction and closes the within-turn window the Stop-hook ART-2 check only
+    // caught at turn end.
+    try {
+        // @implements A-SPEC-148 — the anchor is only trustworthy if EVERY chain is intact, not just one.
+        const { FileLedgerStore } = require('../governance/ledger-store');
+        if (!new FileLedgerStore(path.dirname(ledgerFile)).verifyAll().ok)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    for (const evt of events) {
+        if (evt.kind === 'baseline-recorded' && Array.isArray(evt.inputs)
+            && evt.inputs.includes(label) && evt.inputs.includes(digest))
+            return true;
+    }
+    return false;
+}
+/**
+ * Read a baseline, or null when there is none.
+ *
+ * ABSENT AND EMPTY ARE DIFFERENT. Empty means "nothing existed when this was taken"; absent means
+ * "there is no reference point at all". Returning an empty baseline for a missing one would let a
+ * caller narrow its scope against a reference it never took — the silently-wrong direction. A corrupt
+ * or unreadable file is treated as absent for the same reason a cold cache is: it must degrade the
+ * run, never abort it.
+ */
+function readBaseline(root, label) {
+    try {
+        assertLabel(label);
+    }
+    catch {
+        return null; // an invalid label cannot name an existing baseline
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(fileFor(root, label), 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.files !== 'object' || parsed.files === null)
+            return null;
+        return { label, takenAt: String(parsed.takenAt ?? ''), files: parsed.files };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * May this run become the reference point for "since the last verified state"?
+ *
+ * ONLY a run that actually executed and passed. A red suite must not become the baseline — every
+ * later scope would then be narrowed against a state nobody verified — and a skipped run is not
+ * evidence of anything at all. This is exactly the condition that already gates writing test
+ * evidence, extracted so both branches are pinned by a test rather than only the negative one: a
+ * fixture project has no runnable suite, so the passing branch is otherwise never exercised.
+ */
+function shouldRecordBaseline(result) {
+    return result.passed && !result.skipped;
+}
+/** Every label that exists, sorted. */
+function listBaselines(root) {
+    try {
+        return fs.readdirSync(path.join(root, exports.BASELINE_DIR))
+            .filter((f) => f.endsWith('.json'))
+            .map((f) => f.slice(0, -'.json'.length))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}