@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/governance/provenance-chain.js

@@ -0,0 +1,365 @@
+"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.PROVENANCE_FILE = exports.ProvenanceChain = exports.GENESIS = void 0;
+exports.canonicalize = canonicalize;
+exports.computeHash = computeHash;
+exports.chainNext = chainNext;
+exports.verifyChain = verifyChain;
+exports.authorizationRef = authorizationRef;
+exports.redactTarget = redactTarget;
+exports.blankNonce = blankNonce;
+exports.nonceDeclared = nonceDeclared;
+exports.nonceFingerprint = nonceFingerprint;
+exports.approvalMarkers = approvalMarkers;
+exports.consumeNonceExclusively = consumeNonceExclusively;
+// @implements A-SPEC-125.2
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const ledger_lock_1 = require("./ledger-lock");
+exports.GENESIS = 'GENESIS';
+/** Ordered-key serialization so identical bodies always produce identical bytes (hash stability). */
+function canonicalize(b) {
+    return JSON.stringify({
+        seq: b.seq, ts: b.ts, actor: b.actor, kind: b.kind, summary: b.summary,
+        inputs: b.inputs ?? [], rationale: b.rationale ?? '', authorization: b.authorization ?? '',
+    });
+}
+/**
+ * Event hash. WITHOUT a key: plain sha256 chain (tamper-EVIDENT — a full rewrite from point k still
+ * passes, the documented no-key limit). WITH an out-of-band key (HOLMES_LEDGER_KEY env, same channel
+ * discipline as HOLMES_APPROVAL): HMAC-SHA256 — a forger without the key cannot recompute ANY link,
+ * so even the full-rewrite attack fails verification. Key presence upgrades the guarantee from
+ * tamper-evident to tamper-PROOF-against-keyless-forgers; absence degrades gracefully to the chain.
+ */
+function computeHash(prevHash, body, key) {
+    const input = `${prevHash}|${canonicalize(body)}`;
+    return key
+        ? crypto.createHmac('sha256', key).update(input).digest('hex')
+        : crypto.createHash('sha256').update(input).digest('hex');
+}
+/** Build the next chained event from the current chain tail (pure). */
+function chainNext(chain, body, key) {
+    const prev = chain.length > 0 ? chain[chain.length - 1] : undefined;
+    const prevHash = prev ? prev.hash : exports.GENESIS;
+    const full = { seq: chain.length, ...body };
+    return { ...full, prevHash, hash: computeHash(prevHash, full, key) };
+}
+const KNOWN_FIELDS = new Set(['seq', 'ts', 'actor', 'kind', 'summary', 'inputs', 'rationale', 'authorization', 'prevHash', 'hash']);
+/**
+ * Verify the whole chain: recomputed hashes, prevHash linkage, contiguous seq, AND no unknown fields.
+ * The unknown-field check closes the canonicalization-gap attack (adversarial review #2): canonicalize
+ * hashes only the known fields, so a tamperer could smuggle forged data in an EXTRA field that the
+ * hash ignores but a consumer might read — any field outside the schema now fails verification.
+ * Returns the FIRST broken seam so remediation is addressable. An empty chain is trivially valid.
+ */
+function verifyChain(chain, key) {
+    // MIXED-MODE key adoption (review: enabling the key used to brick a pre-existing keyless ledger,
+    // and pure per-event fallback would let a keyless forger keep appending). Rules with a key:
+    //   - a KEYLESS PREFIX (history from before the key existed) verifies with the plain hash;
+    //   - from the FIRST keyed event onward, every event must be keyed (monotonic upgrade — a keyless
+    //     event after a keyed one is a forgery attempt);
+    //   - the chain must contain at least one keyed event (a fully-keyless chain under a configured
+    //     key is a keyless-rollback rewrite — the exact attack HMAC exists to stop).
+    let keyedSeen = false;
+    for (let i = 0; i < chain.length; i++) {
+        const e = chain[i];
+        const unknown = Object.keys(e).filter((k) => !KNOWN_FIELDS.has(k));
+        if (unknown.length > 0)
+            return { ok: false, brokenAt: i, detail: `unknown field(s) outside the hashed schema: ${unknown.join(', ')} (smuggled data)` };
+        if (e.seq !== i)
+            return { ok: false, brokenAt: i, detail: `seq gap: expected ${i}, found ${e.seq}` };
+        const expectedPrev = i === 0 ? exports.GENESIS : chain[i - 1].hash;
+        if (e.prevHash !== expectedPrev)
+            return { ok: false, brokenAt: i, detail: 'prevHash does not link to the prior event' };
+        const { prevHash: _p, hash: _h, ...body } = e;
+        if (key) {
+            if (computeHash(e.prevHash, body, key) === e.hash) {
+                keyedSeen = true;
+            }
+            else if (!keyedSeen && computeHash(e.prevHash, body) === e.hash) {
+                // legacy keyless prefix — acceptable history from before key adoption
+            }
+            else {
+                return { ok: false, brokenAt: i, detail: keyedSeen ? 'keyless/tampered event AFTER key adoption' : 'event content does not match its hash (tampered)' };
+            }
+        }
+        else if (computeHash(e.prevHash, body) !== e.hash) {
+            return { ok: false, brokenAt: i, detail: 'event content does not match its hash (tampered)' };
+        }
+    }
+    if (key && chain.length > 0 && !keyedSeen) {
+        return { ok: false, brokenAt: chain.length - 1, detail: 'signing key is configured but the chain has NO keyed events — keyless-rollback rewrite suspected' };
+    }
+    return { ok: true };
+}
+/**
+ * Reference an approval credential WITHOUT persisting it: a short sha256 fingerprint identifies which
+ * token authorized an action while the ledger never stores the replayable secret (adversarial review
+ * #1 — the raw token in an audit file meant any local reader could harvest live gate-unlock
+ * credentials).
+ */
+function authorizationRef(actor, token) {
+    return `${actor}:${crypto.createHash('sha256').update(token).digest('hex').slice(0, 12)}`;
+}
+/**
+ * Redact a tool's target before it enters the audit trail.
+ *
+ * The chain used to store the raw command text. Audited on this repository's own ledger: 29 records,
+ * 15 carrying absolute home paths and 6 matching secret-ish patterns. The hazard is structural, not
+ * incidental — the gate DENIES commands like `echo $HOLMES_APPROVAL` and `HOLMES_LEDGER_KEY=…`, and
+ * a denial is exactly what gets recorded, so the ledger is the one place guaranteed to collect the
+ * secrets the gate exists to protect. Committing it would publish them irreversibly.
+ *
+ * Same principle `authorizationRef` already applies to tokens: fingerprint, never store.
+ *
+ * - A FILE PATH is kept, because "which file was touched" is the audit question, but normalised to
+ *   repo-relative; anything outside the repository becomes a placeholder rather than a host path.
+ * - A COMMAND is never kept. Its digest is recorded instead, so identical attempts remain
+ *   correlatable across records without the text being recoverable. Nothing is lost for audit: the
+ *   event's `summary` already carries the human-readable classification ("hard-hitl risk: git push
+ *   --force rewrites remote history"), which is what a reader actually needs.
+ */
+function redactTarget(kind, value, repoRoot) {
+    if (!value)
+        return '';
+    if (kind === 'command') {
+        return `cmd:${crypto.createHash('sha256').update(value).digest('hex').slice(0, 12)}`;
+    }
+    const root = repoRoot ?? process.cwd();
+    const abs = path.resolve(root, value);
+    const rel = path.relative(root, abs);
+    // `..` or an absolute result means the path escaped the repository; naming it would leak host
+    // layout (usernames, mount points) into an artefact intended to be shareable.
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+        return '<outside-repo>';
+    return rel.split(path.sep).join('/');
+}
+// @implements A-SPEC-191 §11 — `nonce: ''` is not the absence of a nonce. Truthiness sent a blank
+// token down the no-nonce path, so a grant that ASKED to be single-use became unlimited (the same
+// degenerate fail-open as the blank `expires` and the empty scope pattern before it). A declared but
+// unusable nonce is refused, never ignored.
+function blankNonce(nonce) {
+    if (nonce === undefined || nonce === null)
+        return false; // 부재는 부재다
+    // Round-9: `nonce: 0` and `nonce: false` are DECLARED and unusable, yet truthiness sent them down
+    // the no-nonce path — the same degenerate fail-open the blank string closed, two values further.
+    // A nonce is a string that names a grant; anything else cannot be spent, and what cannot be spent
+    // must not silently become 'unlimited'.
+    return typeof nonce !== 'string' || nonce.trim() === '';
+}
+/** Declared at all — the operand for "does this grant claim single use?" (falsy values included). */
+function nonceDeclared(nonce) {
+    return nonce !== undefined && nonce !== null;
+}
+// @implements A-SPEC-191 §11 — a spent nonce is recorded by FINGERPRINT, never by value. The old
+// record filed the raw single-use token (and, in the hook, the raw command it authorized) into the
+// append-only chain, so the artefact that proves a token was spent also republished the token and
+// the command forever. `isNonceConsumed` still recognizes both forms, so ledgers written before this
+// change keep denying replays.
+function nonceFingerprint(nonce) {
+    return `nonce:${crypto.createHash('sha256').update(nonce).digest('hex').slice(0, 12)}`;
+}
+// @implements A-SPEC-191 §11 — an audit line about an approval must not become the leak the audit
+// line was redacted to prevent. r8 measured it: A-SPEC-133 recommends least-privilege approvals whose
+// scope pattern EQUALS the command being authorized, so writing patterns verbatim put
+// `git push --force origin main` — and a planted `sk-SECRET-…` — into the same record whose target
+// was hashed precisely so the ledger would not accumulate the secrets the gate protects.
+//
+// What an auditor needs is preserved: which KINDS were authorized, whether a wildcard (the master
+// key) was among them, how many entries there were, and whether the grant carried an expiry or was
+// single-use. The patterns themselves travel as fingerprints, comparable across records but not
+// readable. Entries are dropped WHOLE with a count, never cut mid-entry — a truncated summary that
+// silently loses the `shell=*` entry tells the auditor the opposite of what happened.
+function approvalMarkers(approval) {
+    const SCOPE_BUDGET = 120;
+    let scope;
+    if (!approval?.scope)
+        scope = 'unscoped';
+    else if (approval.scope.length === 0)
+        scope = 'empty';
+    else {
+        // Round-9: a single malformed entry (a null element, a non-string pattern) threw here, and the
+        // caller's catch turned that into NO audit line at all for a gate that DID open. The summary is
+        // total: anything unprintable is named as such, because 'malformed' is itself audit-worthy.
+        const entries = Array.isArray(approval.scope) ? approval.scope : [];
+        const parts = entries.map((s) => {
+            const kind = s && typeof s.kind === 'string' ? s.kind : '<malformed>';
+            const pattern = s ? s.pattern : undefined;
+            if (pattern === '*')
+                return `${kind}=*`;
+            if (typeof pattern !== 'string')
+                return `${kind}=<malformed>`;
+            return `${kind}=${redactTarget('command', pattern)}`;
+        });
+        // A wildcard is the MASTER KEY: it is the entry an auditor most needs to see, so it never loses
+        // its place to a budget (round-9: `shell=*` disappeared behind '(+N건 생략)' because a longer
+        // entry happened to come first).
+        const ordered = [...parts.filter((p) => p.endsWith('=*')), ...parts.filter((p) => !p.endsWith('=*'))];
+        const kept = [];
+        let len = 0;
+        for (const p of ordered) {
+            if (len + p.length + 1 > SCOPE_BUDGET)
+                continue; // 통째로 건너뛴다 — 자르지 않는다
+            kept.push(p);
+            len += p.length + 1;
+        }
+        const omitted = ordered.length - kept.length;
+        scope = kept.join(',') + (omitted > 0 ? `${kept.length ? ',' : ''}(+${omitted}건 생략)` : '');
+    }
+    const expiry = approval?.expires ? `until ${String(approval.expires).slice(0, 40)}` : 'no-expiry';
+    // nonce 는 값이 아니라 선언 여부만 — 값은 재사용 재료다.
+    const nonce = nonceDeclared(approval?.nonce) ? 'single-use' : 'no-nonce';
+    return `approval[scope=${scope}; expiry=${expiry}; nonce=${nonce}]`;
+}
+class ProvenanceChain {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    /** Load all events. ENOENT -> []; any other error throws (audit trail must not silently vanish). */
+    load() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.file, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* torn tail line tolerated; verify() exposes real tampering */ }
+        }
+        return out;
+    }
+    /** Append a new event chained onto the CURRENT on-disk tail. Returns the appended event.
+     *  The signing key comes from HOLMES_LEDGER_KEY (out-of-band env, never tool-settable in-session).
+     *
+     *  @implements A-SPEC-141
+     *  The read-and-write span runs under exclusion. Measured without it: two processes read the same
+     *  tail, both wrote events claiming the same `seq`, and `verify()` then reported `ok:false` —
+     *  tampering that never happened, 17 times out of 20. */
+    append(body) {
+        return (0, ledger_lock_1.withLedgerLock)(this.file, () => this.appendUnlocked(body), { onStaleBreak: this.recordStaleBreak });
+    }
+    /**
+     * Append assuming exclusion is ALREADY held. Only for callers running inside `withLedgerLock` on
+     * this same file — `consumeNonceExclusively` needs the read and the write in one hold, and calling
+     * `append()` from there would deadlock against its own budget.
+     */
+    appendInsideLock(body) {
+        return this.appendUnlocked(body);
+    }
+    /** The append itself, assuming exclusion is already held. Only callers INSIDE a hold may use it. */
+    appendUnlocked(body) {
+        const chain = this.load();
+        const evt = chainNext(chain, body, process.env.HOLMES_LEDGER_KEY || undefined);
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+        fs.appendFileSync(this.file, JSON.stringify(evt) + '\n', 'utf8');
+        return evt;
+    }
+    /**
+     * Records a broken stale hold into the chain itself. Bound so it can be handed to the lock layer,
+     * which must not import this module (the lock is the lower layer).
+     *
+     * Written WITHOUT re-entering the lock: this fires from inside the acquire loop, where the hold has
+     * just been released and not yet re-taken, so calling `append()` here would deadlock against the
+     * budget. The event may therefore race a concurrent writer, which is acceptable for a diagnostic —
+     * a missing note is better than a wedged harness, and `verify()` still reports any resulting seam.
+     */
+    staleBreakRecorder() { return this.recordStaleBreak; }
+    recordStaleBreak = (info) => {
+        try {
+            this.appendUnlocked({
+                ts: new Date().toISOString(), actor: 'holmes-kit', kind: 'lock-broken',
+                summary: `broke stale ledger lock held by pid ${info.pid ?? 'unknown'} (age ${info.ageMs}ms)`,
+                inputs: [], rationale: 'holder exceeded the staleness threshold; recovery must not require an operator',
+            });
+        }
+        catch { /* a diagnostic must never block the recovery it is describing */ }
+    };
+    verify() {
+        return verifyChain(this.load(), process.env.HOLMES_LEDGER_KEY || undefined);
+    }
+}
+exports.ProvenanceChain = ProvenanceChain;
+/** Default chain location, beside the other L4 ledgers (protected surface). */
+exports.PROVENANCE_FILE = path.join('.ax', 'ledger', 'provenance.jsonl');
+/**
+ * Spend a single-use approval, atomically. Returns `true` iff THIS caller spent it.
+ *
+ * @implements A-SPEC-141
+ * THIS is the operation REQ-141 exists for. The gate used to ask `isNonceConsumed(...)` and only
+ * afterwards append the consumption record, so two agents both observed "not consumed" and both
+ * proceeded: measured, a single-use approval for a destructive command was honoured TWICE in 20 of
+ * 20 barrier-synchronized trials. Locking the append alone would not have helped — the unguarded
+ * span is the READ followed by the WRITE, so both must live inside one hold.
+ *
+ * A loser writes NOTHING. Recording a consumption the caller was refused would put a second
+ * `nonce-consumed` event in the audit trail for an action that never happened.
+ *
+ * Throws `LedgerLockError` when exclusion cannot be obtained. The direction to fail is the CALLER's
+ * decision, not this function's: an authorization gate must deny, while a record-keeping append must
+ * not flip a decision that was already made.
+ */
+function consumeNonceExclusively(nonce, ledgerFile, body, opts) {
+    const chain = new ProvenanceChain(ledgerFile);
+    return (0, ledger_lock_1.withLedgerLock)(ledgerFile, () => {
+        // @implements A-SPEC-148
+        // The spent-check spans EVERY replica chain, not just the file being written. Judging from one
+        // chain alone would let a single-use approval be spent once per replica, resurrecting REQ-141's
+        // double-spend along a new axis. NAMED LIMIT: within one machine the lock makes this exact;
+        // across machines there is no shared filesystem to lock, so two machines racing the same nonce
+        // can both pass and the duplicate is DETECTED afterwards in the merged ledger rather than
+        // prevented. Preventing it needs a shared authority, which is out of this slice's scope.
+        const { FileLedgerStore } = require('./ledger-store');
+        const spent = new FileLedgerStore(path.dirname(ledgerFile)).isNonceConsumed(nonce);
+        if (spent)
+            return false;
+        chain.appendInsideLock(body);
+        return true;
+        // Default the stale-break recorder to the chain's own: breaking a lock silently is forbidden
+        // here for exactly the same reason it is in `append()`, and leaving it undefined made this
+        // path — the SECURITY path — the one place a lock could be stolen without a trace.
+    }, { ...opts, onStaleBreak: opts?.onStaleBreak ?? chain.staleBreakRecorder() });
+}

package/dist/holmes/governance/provenance-schema.js

@@ -0,0 +1,47 @@
+"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.provenanceSchemaOf = provenanceSchemaOf;
+// @implements A-SPEC-147
+const path = __importStar(require("node:path"));
+const V2 = /^provenance\.[^.]+\.jsonl$/;
+function provenanceSchemaOf(fileName) {
+    // A path may arrive instead of a bare name; the schema is a property of the file, not its location.
+    const base = path.basename(fileName || '');
+    // An unrecognised name is read as the OLDER schema on purpose. Guessing the newer format for an
+    // unknown file would apply replica-local seq rules to a global chain and report false gaps —
+    // conservative here means "assume the format that has been around longest".
+    return V2.test(base) ? 2 : 1;
+}

package/dist/holmes/governance/replica-id.js

@@ -0,0 +1,106 @@
+"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.sanitizeReplicaId = sanitizeReplicaId;
+exports.resolveReplicaId = resolveReplicaId;
+// @implements A-SPEC-148
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+/**
+ * The identity of the machine writing this ledger, used as the chain's filename segment.
+ *
+ * It is a LOCAL fact: stored under `.ax/state/` (already gitignored) so it stays stable across runs
+ * on one machine and never travels with the repository. It must be recognisable to a human reading
+ * `provenance.<id>.jsonl`, and must never carry a secret or an absolute path — ADR-012 established
+ * that discipline for the ledger's contents and it applies to its name too.
+ */
+const MAX = 32;
+const STORE = path.join('.ax', 'state', 'replica-id');
+/**
+ * Reduce a raw name to something safe to embed in `provenance.<id>.jsonl`.
+ *
+ * DOTS ARE THE POINT. macOS hostnames end in `.local`, and the schema rule reads
+ * `provenance.<segment>.jsonl` with `<segment>` containing no dot — an unsanitised
+ * `SungNamui-MacStudio.local` would produce `provenance.SungNamui-MacStudio.local.jsonl`, which the
+ * schema check would not recognise as a replica chain at all. Two rules disagreeing about the same
+ * file is worse than either rule being wrong.
+ */
+function sanitizeReplicaId(raw) {
+    const cleaned = (raw || '').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, MAX);
+    // Everything stripped (an all-punctuation name, or an empty one) still needs a usable filename.
+    return cleaned === '' ? 'local' : cleaned;
+}
+/**
+ * Resolve this machine's replica id: explicit env, then the stored value, then the hostname.
+ *
+ * The env override exists for CI and for tests, where the hostname is neither stable nor meaningful.
+ * Writing the generated value down is what makes the identity stable — an id derived fresh each run
+ * would scatter one machine's history across several chains.
+ */
+function resolveReplicaId(root, env = process.env, opts = {}) {
+    const persist = opts.persist !== false;
+    const fromEnv = env.HOLMES_REPLICA_ID;
+    if (typeof fromEnv === 'string' && fromEnv.trim() !== '')
+        return sanitizeReplicaId(fromEnv);
+    const file = path.join(root, STORE);
+    try {
+        const stored = fs.readFileSync(file, 'utf8').trim();
+        if (stored !== '')
+            return sanitizeReplicaId(stored);
+    }
+    catch { /* not yet written */ }
+    let host = 'local';
+    try {
+        host = os.hostname();
+    }
+    catch { /* keep the fallback */ }
+    const id = sanitizeReplicaId(host);
+    // Best-effort persistence: failing to record the id must not stop the caller from writing to the
+    // ledger, it only means the next run re-derives the same value from the same hostname.
+    // @implements A-SPEC-150
+    // Persisting is a WRITE. Asking "who am I" is a read, and a read must leave no trace — the ledger
+    // port's conformance requires it, and doing it here is why merely constructing a store used to
+    // create `.ax/state/`. Callers that are about to append pass `persist: true` (the default);
+    // read-only callers pass false and get the same value without the side effect.
+    if (persist) {
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, `${id}\n`, 'utf8');
+        }
+        catch { /* ignore */ }
+    }
+    return id;
+}

package/dist/holmes/governance/role-policy.js

@@ -0,0 +1,137 @@
+"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.loadRolePolicy = loadRolePolicy;
+exports.rolePolicyStatus = rolePolicyStatus;
+exports.roleCheck = roleCheck;
+// @implements A-SPEC-152
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const yaml = __importStar(require("js-yaml"));
+const ROLES_DIR = path.join('.ax', 'roles');
+/** `null` when the project has not opted in. A PRESENT-but-broken policy is never null — see below. */
+function loadRolePolicy(root) {
+    const dir = path.join(root, ROLES_DIR);
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml')).sort();
+    }
+    catch {
+        return null; // no directory: not opted in
+    }
+    if (files.length === 0)
+        return null; // empty directory: not opted in either
+    const roles = {};
+    let dflt;
+    for (const f of files) {
+        try {
+            const doc = yaml.load(fs.readFileSync(path.join(dir, f), 'utf8'));
+            // FIRST declaration wins, by filename order. If the last one won, dropping in a new file would
+            // silently reverse a decision another file already made — and nothing would report the change.
+            if (dflt === undefined && typeof doc?.default === 'string' && doc.default.trim() !== '') {
+                dflt = doc.default.trim();
+            }
+            const declared = doc && typeof doc === 'object' ? doc.roles : undefined;
+            if (!declared || typeof declared !== 'object')
+                continue;
+            for (const [name, def] of Object.entries(declared)) {
+                const allow = def?.allow;
+                roles[name] = { allow: Array.isArray(allow) ? allow.filter((a) => typeof a === 'string') : [] };
+            }
+        }
+        catch {
+            // A corrupt file contributes NO roles — deliberately not `null`. Returning "no policy" would
+            // turn a broken governance file into "roles are off", silently downgrading enforcement, which
+            // is the failure direction REQ-144 forbids. A policy that grants nothing denies everything.
+            continue;
+        }
+    }
+    return dflt === undefined ? { roles } : { roles, default: dflt };
+}
+/**
+ * Describes the project's role configuration WITHOUT judging it. Not having roles on is not a
+ * defect; reporting it as one would teach operators to ignore doctor, which costs more than it saves.
+ */
+function rolePolicyStatus(root) {
+    const dir = path.join(root, ROLES_DIR);
+    if (!fs.existsSync(dir))
+        return { state: 'absent', roles: [] };
+    const policy = loadRolePolicy(root);
+    if (policy === null)
+        return { state: 'inactive', roles: [] };
+    return { state: 'active', roles: Object.keys(policy.roles).sort(), default: policy.default };
+}
+/**
+ * Whether this identity may perform this action. Returns the refusal reason, or `null` to allow.
+ *
+ * Fail-closed once a policy exists: an absent role, an unregistered role, and a role without the
+ * action are all refusals. Before a policy exists there is no opinion at all.
+ */
+function roleCheck(action, identity, policy) {
+    if (policy === null)
+        return null;
+    const known = Object.keys(policy.roles);
+    // The default is resolved HERE, not in the identity provider. Identity is observed fact — what the
+    // operator actually claimed — while a default is the policy's interpretation of silence. Folding
+    // one into the other would leave a server-backed provider unable to tell a role it verified from
+    // a role that was merely assumed, which is exactly what `proven` exists to distinguish.
+    let effective = identity.role;
+    if (!effective && policy.default !== undefined) {
+        if (!policy.roles[policy.default]) {
+            // A typo'd default must be louder than plain absence: it reads as "roles are configured" while
+            // granting nothing to no one, so the operator believes an enforcement exists that does not.
+            return `[Holmes-Kit] 역할 정책의 기본 역할 "${policy.default}"이(가) 정의되어 있지 않습니다 — ${action}을(를) 허용할 수 없습니다.`
+                + ` .ax/roles/의 default를 고치거나 그 역할을 정의하세요. 등록된 역할: ${known.join(', ') || '(없음)'}`;
+        }
+        effective = policy.default;
+    }
+    if (!effective) {
+        return `[Holmes-Kit] 이 프로젝트는 역할 정책을 사용합니다 — 역할이 지정되지 않아 ${action}을(를) 허용할 수 없습니다.`
+            + ` 에이전트를 기동할 때 HOLMES_ROLE을 설정하세요(대역외 채널), 또는 .ax/roles/에 default를 선언하세요.`
+            + ` 등록된 역할: ${known.join(', ') || '(없음)'}`;
+    }
+    // Exact match on purpose: a silent case-fold would make `Developer` and `developer` the same
+    // principal by accident, which is not a decision a policy file ever expressed.
+    const def = policy.roles[effective];
+    if (!def) {
+        return `[Holmes-Kit] 역할 "${effective}"이(가) 역할 정책에 없습니다 — ${action}을(를) 허용할 수 없습니다.`
+            + ` 등록된 역할: ${known.join(', ') || '(없음)'}`;
+    }
+    if (!def.allow.includes(action)) {
+        return `[Holmes-Kit] 역할 "${effective}"은(는) ${action}을(를) 수행할 수 없습니다.`
+            + ` 허용된 동작: ${def.allow.join(', ') || '(없음)'}`;
+    }
+    return null;
+}