@holmes-lab/holmes-kit 0.1.6 → 0.1.8

package/dist/holmes/cpg/language-parser.d.ts

@@ -0,0 +1,116 @@
+export interface CodeSymbol {
+    name: string;
+    kind: 'function' | 'class' | 'method';
+    qualifiedName: string;
+    startLine: number;
+    endLine: number;
+}
+/**
+ * A call/import relation recovered from a parse tree.
+ *
+ * @implements A-SPEC-136
+ * WIRED END-TO-END. `CpgScanner.scan` populates `ScannedFile.edges` via `extractEdges`;
+ * `addCallEdges` resolves each bare callee name to a graph edge under a precision-over-recall rule
+ * (same-file first, else the single unique definition across the scan, else nothing); and
+ * `impactedBy` traverses `callersOf`, so a change to an unanchored callee reaches its caller's spec.
+ * Measured: the self-repo carries ~2260 `calls` edges. Only `calls` edges are traversed for impact;
+ * `imports` are recorded but advisory.
+ *
+ * Traceability remains a file-level `@implements` claim as the FLOOR — a call the walk cannot resolve
+ * leaves a gap L6 surfaces, never a wrong edge (a wrong edge poisons every impact answer through it).
+ * Call-edge extraction covers TS/JS and Python (bespoke walks, for their import handling) and
+ * Go/Rust/Java/C#/C++ (table-driven `EDGE_CONFIG` + `walkEdges` in language-parser-walk.js). The
+ * corrected wiring pin lives in rtm-builder.test.ts ('call edges ARE scanned, resolved, and
+ * traversed'); a prior version of this note wrongly said edges were unwired and misled an audit.
+ */
+export interface CodeEdge {
+    from: string;
+    to: string;
+    rel: 'calls' | 'imports';
+}
+export type TsLang = 'typescript' | 'tsx' | 'python' | 'csharp' | 'java' | 'go' | 'rust' | 'cpp';
+/**
+ * Def-use FACTS for one file — what a taint fixpoint needs, with no analysis applied yet.
+ *
+ * @implements A-SPEC-140.1
+ * `fn` is always the enclosing definition's QUALIFIED name, built by the same rule as
+ * `CodeEdge.from`, so a fact can be joined to the call graph. `calls[].args` is ORDERED: position is
+ * what binds an argument to a parameter, and `params[].index` is the parameter's DECLARATION index —
+ * a parameter whose identifier cannot be read is omitted but still consumes its index, so the
+ * remaining ones keep their true positions.
+ *
+ * Every field reports what the tree literally says. A construct the walk cannot read produces NO
+ * fact rather than a guessed one (precision over recall): the cost is a propagation hop that does
+ * not happen, which is a disclosed false negative, versus a fabricated flow, which is a false
+ * positive nobody can distinguish from a real finding.
+ */
+export interface DataFlowFacts {
+    defs: {
+        fn: string;
+        name: string;
+        expr: Expr;
+        line: number;
+    }[];
+    calls: {
+        fn: string;
+        callee: string;
+        args: Expr[];
+        line: number;
+    }[];
+    params: {
+        fn: string;
+        index: number;
+        name: string;
+    }[];
+    returns: {
+        fn: string;
+        expr: Expr;
+        line: number;
+    }[];
+}
+/**
+ * An expression as STRUCTURE rather than text.
+ *
+ * @implements A-SPEC-140.1
+ * Text alone would force the propagation pass to ask "does this mention a tainted variable?"
+ * lexically, and two ordinary lines break that: `const note = "raw user input";` falsely taints
+ * `note` because the literal contains the word, and `exec(sanitize(raw))` looks tainted because the
+ * argument text contains `raw` even though it was sanitized inline. Both are exactly the false
+ * positives REQ-140 exists to remove, so the structure is recovered once, from the tree.
+ */
+export interface Expr {
+    /** Source text, trimmed and bounded (200 chars) — for display, and for the inherently textual source/sink patterns. */
+    text: string;
+    /** Identifiers READ, deduped, first-appearance order. A property name after a dot is not a read (`req.body.cmd` → `['req']`). */
+    refs: string[];
+    /** Bare names INVOKED, deduped, first-appearance order (`sanitize(raw)` → `['sanitize']`), by the edge walk's last-segment rule. */
+    callees: string[];
+}
+export interface LanguageParser {
+    extractSymbols(code: string, lang?: TsLang): CodeSymbol[];
+    extractEdges(code: string, lang?: TsLang): CodeEdge[];
+    /** `undefined` — never an empty fact set — for a language with no data-flow walk: not analysed ≠ nothing found. */
+    extractDataFlow(code: string, lang?: TsLang): DataFlowFacts | undefined;
+}
+/**
+ * Thrown for RPC/infrastructure failures on the jest worker_thread path
+ * (timeout, dead worker, desynchronized response) — as opposed to a genuine
+ * per-file parse exception. Callers such as CpgScanner use this to avoid
+ * silently treating a systemic worker failure as "just this file is
+ * unparseable".
+ */
+export declare class TreeSitterInfraError extends Error {
+}
+/**
+ * Whether a language has a data-flow walk at all.
+ *
+ * @implements A-SPEC-140.1
+ * Read straight from the walk's own table so the two can never drift: a caller that guessed the
+ * list would eventually claim "analysed, nothing found" for a language nothing ever looked at.
+ */
+export declare function hasDataFlowWalk(lang: TsLang): boolean;
+export declare class TreeSitterTsParser implements LanguageParser {
+    extractSymbols(code: string, lang?: TsLang): CodeSymbol[];
+    extractEdges(code: string, lang?: TsLang): CodeEdge[];
+    extractDataFlow(code: string, lang?: TsLang): DataFlowFacts | undefined;
+}

package/dist/holmes/cpg/program-slicing.d.ts

@@ -0,0 +1,21 @@
+import { ScannedFile } from './cpg-scanner';
+export interface SliceCriterion {
+    file: string;
+    symbolName?: string;
+    line?: number;
+    direction?: 'backward' | 'forward' | 'both';
+}
+export interface SliceResult {
+    criterion: SliceCriterion;
+    slicedNodeIds: Set<string>;
+    totalOriginalNodes: number;
+    prunedNodesCount: number;
+    pruningRatioPct: number;
+    slicedFiles: ScannedFile[];
+}
+/**
+ * Perform precise program slicing over CPG AST nodes and call edges to prune noise and isolate affected nodes.
+ *
+ * @implements A-SPEC-217
+ */
+export declare function sliceProgram(scannedFiles: ScannedFile[] | null | undefined, criterion: SliceCriterion | null | undefined): SliceResult;

package/dist/holmes/cpg/program-slicing.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sliceProgram = sliceProgram;
+function isFileMatch(sfSource, sfFull, normTargetFile) {
+    if (!normTargetFile)
+        return true;
+    if (sfSource !== '' && (sfSource === normTargetFile || sfSource.endsWith('/' + normTargetFile)))
+        return true;
+    if (sfFull !== '' && (sfFull === normTargetFile || sfFull.endsWith('/' + normTargetFile)))
+        return true;
+    return false;
+}
+function getSymbolId(sf, sym) {
+    if (sym.qualifiedName)
+        return sym.qualifiedName;
+    const sfSource = (sf.sourcePath || '').split(/[\\/]/).filter(Boolean).join('/');
+    const sfFull = (sf.path || '').split(/[\\/]/).filter(Boolean).join('/');
+    return `${sfSource || sfFull}#${sym.name}`;
+}
+/**
+ * Perform precise program slicing over CPG AST nodes and call edges to prune noise and isolate affected nodes.
+ *
+ * @implements A-SPEC-217
+ */
+function sliceProgram(scannedFiles, criterion) {
+    const safeFiles = Array.isArray(scannedFiles) ? scannedFiles : [];
+    const safeCriterion = criterion || { file: '' };
+    const direction = safeCriterion.direction || 'both';
+    let totalOriginalNodes = 0;
+    // Build symbol lookup maps and adjacency graph
+    const nodeMap = new Map();
+    const forwardEdges = new Map();
+    const backwardEdges = new Map();
+    const normTargetFile = (safeCriterion.file || '').split(/[\\/]/).filter(Boolean).join('/');
+    const seedNodeIds = new Set();
+    for (const sf of safeFiles) {
+        if (!sf)
+            continue;
+        const sfSource = (sf.sourcePath || '').split(/[\\/]/).filter(Boolean).join('/');
+        const sfFull = (sf.path || '').split(/[\\/]/).filter(Boolean).join('/');
+        const fileMatches = isFileMatch(sfSource, sfFull, normTargetFile);
+        const symbols = Array.isArray(sf.symbols) ? sf.symbols : [];
+        for (const sym of symbols) {
+            totalOriginalNodes++;
+            const id = getSymbolId(sf, sym);
+            nodeMap.set(id, { file: sf, name: sym.name, qualifiedName: id, line: sym.startLine });
+            if (!forwardEdges.has(id))
+                forwardEdges.set(id, new Set());
+            if (!backwardEdges.has(id))
+                backwardEdges.set(id, new Set());
+            if (fileMatches) {
+                let nameMatch = !safeCriterion.symbolName || sym.name === safeCriterion.symbolName || sym.qualifiedName === safeCriterion.symbolName;
+                let lineMatch = safeCriterion.line === undefined || (safeCriterion.line >= sym.startLine && safeCriterion.line <= sym.endLine);
+                if (nameMatch && lineMatch) {
+                    seedNodeIds.add(id);
+                }
+            }
+        }
+        const edges = Array.isArray(sf.edges) ? sf.edges : [];
+        for (const e of edges) {
+            if (e && e.from && e.to) {
+                if (!forwardEdges.has(e.from))
+                    forwardEdges.set(e.from, new Set());
+                forwardEdges.get(e.from).add(e.to);
+                if (!backwardEdges.has(e.to))
+                    backwardEdges.set(e.to, new Set());
+                backwardEdges.get(e.to).add(e.from);
+            }
+        }
+    }
+    // Traversal for transitive closure
+    const slicedNodeIds = new Set();
+    const queue = Array.from(seedNodeIds);
+    for (const id of seedNodeIds) {
+        slicedNodeIds.add(id);
+    }
+    while (queue.length > 0) {
+        const curr = queue.shift();
+        if (direction === 'forward' || direction === 'both') {
+            const nextForward = forwardEdges.get(curr);
+            if (nextForward) {
+                for (const nextId of nextForward) {
+                    if (!slicedNodeIds.has(nextId) && nodeMap.has(nextId)) {
+                        slicedNodeIds.add(nextId);
+                        queue.push(nextId);
+                    }
+                }
+            }
+        }
+        if (direction === 'backward' || direction === 'both') {
+            const nextBackward = backwardEdges.get(curr);
+            if (nextBackward) {
+                for (const prevId of nextBackward) {
+                    if (!slicedNodeIds.has(prevId) && nodeMap.has(prevId)) {
+                        slicedNodeIds.add(prevId);
+                        queue.push(prevId);
+                    }
+                }
+            }
+        }
+    }
+    const prunedNodesCount = totalOriginalNodes - slicedNodeIds.size;
+    const pruningRatioPct = totalOriginalNodes > 0 ? Math.round((prunedNodesCount / totalOriginalNodes) * 100) : 0;
+    // Filter scanned files to include only sliced symbols
+    const slicedFiles = safeFiles.map((sf) => {
+        if (!sf)
+            return sf;
+        const symbols = Array.isArray(sf.symbols) ? sf.symbols : [];
+        const filteredSymbols = symbols.filter((sym) => {
+            const id = getSymbolId(sf, sym);
+            return slicedNodeIds.has(id);
+        });
+        return { ...sf, symbols: filteredSymbols };
+    });
+    return {
+        criterion: safeCriterion,
+        slicedNodeIds,
+        totalOriginalNodes,
+        prunedNodesCount,
+        pruningRatioPct,
+        slicedFiles,
+    };
+}

package/dist/holmes/cpg/scan-cache.d.ts

@@ -0,0 +1,21 @@
+import { ScannedFile } from './cpg-scanner';
+export declare const SCAN_CACHE_VERSION = 3;
+export declare class ScanFileCache {
+    private readonly dir;
+    private readonly file;
+    private entries;
+    private seen;
+    private dirty;
+    hits: number;
+    misses: number;
+    constructor(dir: string);
+    static hashOf(content: string): string;
+    /** Cached scan result iff the stored hash matches this content. Marks the path as seen. */
+    get(sourcePath: string, contentHash: string): Omit<ScannedFile, 'path'> | undefined;
+    put(sourcePath: string, contentHash: string, file: Omit<ScannedFile, 'path'>): void;
+    /**
+     * Persist once per scan. Mark-and-sweep: entries whose path was NOT seen this scan belong to
+     * deleted/renamed files — pruned so the cache cannot grow unboundedly. No-op when nothing changed.
+     */
+    save(scannedScopeDir?: string): void;
+}

package/dist/holmes/cpg/source-path.d.ts

@@ -0,0 +1,2 @@
+/** Repo-root-relative, POSIX-normalized path used as the provenance key for graph rows. */
+export declare function toSourcePath(repoRoot: string, absOrRelPath: string): string;

package/dist/holmes/cpg/test-files.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What counts as a TEST file, per ecosystem — the single table both the scanner and the phase gate
+ * read.
+ *
+ * It lives in its own module, apart from the scanner, because two very different consumers need it
+ * and only one of them can afford the scanner's dependencies. `CpgScanner` uses it to keep test
+ * symbols out of the production graph; `classifyAction` (the PreToolUse phase gate, which runs on
+ * every Write/Edit and is measured in tens of milliseconds) uses it to tell WRITE_TEST from
+ * WRITE_CODE. When the two disagree about what a test is, the harness contradicts itself: measured on
+ * a real Python target, `tests/test_briefing.py` was excluded from the graph as a test AND gated as
+ * production code, so editing it demanded a stricter chain than the code it tests.
+ *
+ * Nothing here imports anything, and that is deliberate — it is the property that lets the hook use
+ * it without pulling tree-sitter into a latency-critical path.
+ */
+/**
+ * Test-file conventions, one entry per ecosystem, matched against the path RELATIVE to the project
+ * root (POSIX-separated).
+ *
+ * Test code must never enter the production graph: its symbols would be counted as production, which
+ * corrupts change-impact, clustering, and any reverse-engineered spec drafted from a scan. The
+ * previous rules covered TS/JS, Python and Go only, so — measured — `AppTest.java`, `AppTests.cs`,
+ * `app_test.rs`, `tests/mod.rs` and `app_test.cpp` all leaked through.
+ *
+ * Kept as one exported table rather than scattered constants so the per-language coverage is
+ * auditable at a glance and testable as a unit; `isTestFile` is the only entry point.
+ */
+export declare const TEST_FILE_PATTERNS: ReadonlyArray<readonly [string, RegExp]>;
+/**
+ * True when a PROJECT-ROOT-RELATIVE POSIX path is a test file by any ecosystem's convention.
+ *
+ * The path must be relative to the project, not absolute: several rules key on a directory segment,
+ * so a repository that merely lives under some `/…/test/` directory on disk would otherwise read as
+ * one big test tree.
+ */
+export declare function isTestFile(relPosixPath: string): boolean;

package/dist/holmes/governance/constitution-debt.d.ts

@@ -0,0 +1,3 @@
+export declare function writeDebt(root: string, articles: string[]): void;
+export declare function readDebt(root: string): string[] | null;
+export declare function clearDebt(root: string): void;

package/dist/holmes/governance/constitution-report.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Renders constitution violations as text a reader can act on.
+ *
+ * This exists because of a measured failure of diagnosis, not a failure of logic. The suite's
+ * corpus assertions compare arrays of violation objects, so a failure printed an opaque diff —
+ * `expect([]).toEqual([6 items])`. Twice that failure was recorded as an unidentified intermittent
+ * and the cause was never found; the 2026-08-08 run reproduced it eleven times on demand and showed
+ * it was never random at all, but a true report about the working tree at the moment it was read.
+ *
+ * Pure and exported rather than assembled inside the test, because an unverified diagnostic is wrong
+ * exactly when it is needed. Extracting it lets a mutation prove the message really names the spec.
+ */
+export interface ConstitutionViolation {
+    article?: string;
+    detail?: string;
+}
+/**
+ * Cap on listed violations. A corpus-wide regression across 300+ specs would otherwise bury the
+ * terminal in hundreds of lines, which reads as noise and gets skipped — the same outcome as
+ * printing nothing.
+ */
+export declare const MAX_LISTED = 20;
+export declare function describeViolations(violations: ConstitutionViolation[]): string;

package/dist/holmes/governance/constitution.d.ts

@@ -0,0 +1,61 @@
+import { Spec } from '../spec/spec-parser';
+/**
+ * L1 — Governance CONSTITUTION (target-architecture §7 L1).
+ *
+ * The inviolable principles are defined ONCE, here, as named ARTICLES — deterministic, pure checks —
+ * and RE-VERIFIED at every phase boundary by the hooks (the Stop gate calls verifyConstitution each
+ * turn; the PreToolUse gates enforce ART-1/ART-5 per-action). This is the spec-kit "constitution" +
+ * bkit "BeforePhase re-verification" pattern, realized as CODE, not prompt text: an article cannot be
+ * rationalized away by a model because it is executed, not read.
+ *
+ * Articles (violations carry the article id so remediation is addressable):
+ *   ART-1 No-Spec-No-Code    — enforced per-action by the PreToolUse phase gate (not re-checked here;
+ *                              listed for completeness of the constitution document).
+ *   ART-2 RTM integrity      — the governed spec graph has no orphans/cycles/dangling/duplicates.
+ *   ART-3 Spec validity      — every governed spec passes its type rules (incl. 4-quadrant GWT).
+ *   ART-4 Coverage honesty   — an approved T-SPEC is backed by REAL anchored test cases (evidence).
+ *   ART-5 Approval out-of-band — spec approval/config writes require HOLMES_APPROVAL (enforced
+ *                              per-action by the PreToolUse gate; listed for completeness).
+ *
+ * Pure: no I/O, no clocks. The hooks supply loaded specs + evidence.
+ */
+export interface ConstitutionViolation {
+    article: string;
+    detail: string;
+}
+export interface ConstitutionContext {
+    specs: Spec[];
+    /**
+     * @implements A-SPEC-160
+     * Recorded review findings, for ART-6. Supplied by the hook, like ART-4's evidence — the
+     * constitution stays pure and does no I/O.
+     *
+     * @implements A-SPEC-191
+     * `severity` rides along for ART-7. The ledger always carried it; this type narrowed it away, so
+     * the constitution could not legally read the one field that says "this must not ship". Optional:
+     * pre-REQ-157 records never had it, and absence stays silent (the A-SPEC-146 trap). `summary`
+     * rides along too (§4d) — a violation that names only an opaque id sends the operator to grep.
+     */
+    findings?: {
+        id: string;
+        status: 'open' | 'resolved';
+        basis?: string;
+        severity?: string;
+        summary?: string;
+    }[];
+    /** A-SPEC id -> count of real test cases in anchored test files (H1 syntactic lower bound). */
+    testCasesByAspec?: Record<string, number>;
+    /**
+     * A-SPEC id -> cases that ACTUALLY EXECUTED in a recorded PASSING test run.
+     *
+     * STRICTLY ADDITIVE (adversarial review C1/C3): this can only ADD violations, never satisfy ART-4
+     * on its own. The record lives in an unsigned, gitignored file an agent can rewrite, and its
+     * freshness stamp (git HEAD) does not move for uncommitted work — so letting it OVERRIDE the
+     * syntactic bound made forgery and staleness able to SUPPRESS real violations (measured: 16 -> 0).
+     * As an additive signal both failure modes are defused: forging it unlocks nothing, and a stale
+     * record cannot hide a missing test suite because the syntactic bound is still enforced.
+     */
+    executedByAspec?: Record<string, number>;
+}
+export declare const ARTICLES: Record<string, string>;
+export declare function verifyConstitution(ctx: ConstitutionContext): ConstitutionViolation[];

package/dist/holmes/governance/identity.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Who is acting — the port a server-backed identity will eventually fill.
+ *
+ * `proven` is the load-bearing field. A LOCAL role is a claim the operator made when launching the
+ * agent; nothing verified it. Recording that plainly is what keeps a later reader from assuming a
+ * local role was checked by something, and it reserves the exact slot where a server answers
+ * `proven: true` for "this really is the Reviewer".
+ */
+export interface Identity {
+    actor?: string;
+    role?: string;
+    /** Always false locally. A server-backed provider is where this becomes true. */
+    proven: boolean;
+}
+export interface IdentityProvider {
+    current(): Identity;
+}
+/**
+ * Reads the claim from the process environment — the same out-of-band discipline `HOLMES_APPROVAL`
+ * established, and for the same reason: a session cannot set its own environment, so it cannot claim
+ * its own role. A role carried in the tool payload would be self-assertion, which is precisely what
+ * ART-5 forbids on the spec axis.
+ */
+export declare class EnvIdentityProvider implements IdentityProvider {
+    private readonly env;
+    constructor(env?: NodeJS.ProcessEnv);
+    current(): Identity;
+}

package/dist/holmes/governance/ledger-lock.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cross-process mutual exclusion for one ledger file.
+ *
+ * WHY this exists, measured rather than assumed. `ProvenanceChain.append()` was read-then-append and
+ * the single-use approval gate was check-then-act, so two agents running at once could both observe
+ * "nonce not consumed" and both proceed. Two real processes synchronized on a file barrier, 20
+ * trials: the single-use approval was spent TWICE 20/20 times, and the tamper-evident chain reported
+ * `ok:false` 17/20 times — reporting tampering that never happened. Sequential behaviour was, and
+ * remains, correct; the failure only appears when the critical sections overlap, which is precisely
+ * the case a harness with "agentic" in its name promises to support.
+ *
+ * `fs.mkdirSync` is the primitive: atomic on every platform this ships to, `EEXIST` when held, and
+ * with none of the file-vs-`O_EXCL` subtleties. A DIRECTORY rather than a lock FILE because a
+ * zero-byte file is what a cleanup script or `git clean` deletes mid-hold, while a directory holds
+ * its own metadata and cannot be removed non-empty by accident.
+ *
+ * LIMIT, stated rather than implied: single host, single filesystem with atomic `mkdir`. Networked
+ * filesystems (NFS, shared volumes) are out of scope and this does not pretend to cover them.
+ */
+/** Thrown when exclusion cannot be obtained within the acquire budget. Distinguishable on purpose. */
+export declare class LedgerLockError extends Error {
+    readonly holmesRefusal = true;
+}
+/**
+ * A hold older than this is treated as abandoned and broken.
+ *
+ * 30 seconds against a critical section that reads a few hundred bytes and appends one line —
+ * microseconds of real work, so this is roughly five orders of magnitude of headroom and cannot fire
+ * on a live holder that is merely slow. The number exists because a `kill -9`'d agent must not wedge
+ * every other agent forever.
+ */
+export declare const STALE_MS = 30000;
+/** Default budget for waiting on someone else's hold before failing. */
+export declare const ACQUIRE_MS = 5000;
+export declare function lockDirFor(ledgerFile: string): string;
+export interface LockOptions {
+    acquireMs?: number;
+    staleMs?: number;
+    /**
+     * Records the breaking of a stale hold. Injected so the lock module does not depend on the
+     * provenance chain that depends on IT — `withLedgerLock` is the lower layer.
+     */
+    onStaleBreak?: (info: {
+        pid?: number;
+        ageMs: number;
+        ledgerFile: string;
+    }) => void;
+}
+/**
+ * Run `fn` while holding exclusion for `ledgerFile`.
+ *
+ * The hold is released in `finally`, including when `fn` throws, and a release problem never masks
+ * `fn`'s own error — the body's failure is the one the caller needs to see.
+ */
+export declare function withLedgerLock<T>(ledgerFile: string, fn: () => T, opts?: LockOptions): T;

package/dist/holmes/governance/ledger-store.conformance.d.ts

@@ -0,0 +1,11 @@
+import { LedgerStore } from './ledger-store';
+/**
+ * The ONE conformance suite every `LedgerStore` adapter must pass.
+ *
+ * Deliberately a single exported function rather than a copy per adapter: two copies drift, and
+ * "both adapters pass" quietly stops meaning anything. Everything here is expressed against the
+ * CONTRACT — no paths, no files, no knowledge of how an adapter stores anything. If a property
+ * cannot be written that way, that is itself the finding: the contract has leaked its
+ * implementation, and finding that now is the whole reason a second adapter exists.
+ */
+export declare function ledgerStoreConformance(name: string, make: () => LedgerStore): void;

package/dist/holmes/governance/ledger-store.d.ts

@@ -0,0 +1,114 @@
+import { ProvenanceEvent } from './provenance-chain';
+import { LedgerEvent } from './provenance-ledger';
+/**
+ * The ledger as a PORT — ADR-001's deferred half, applied to the one store whose shape was derived
+ * from real use rather than guessed at.
+ *
+ * ADR-001 decided the ports now because "an interface changed later causes core-wide rework, while
+ * an adapter can wait". Measured on 2026-08-07: seven of the eight declared ports do not exist, and
+ * the one that does carries the very `read/write/list` shape that ADR called insufficient. This is
+ * the first to land, and it starts from `ProvenanceLedger` — five operations that five production
+ * call sites already use — so it avoids the cost that ADR itself listed as the downside: designing a
+ * contract for something nobody calls.
+ *
+ * DECLARED, with reasons:
+ *  - `replicaId()` — the filename carries it locally, but a server adapter has no filenames. On the
+ *    contract it becomes independent of storage.
+ *  - append-only — free from a file append, an explicit promise for anything else.
+ *  - `isNonceConsumed` spanning ALL chains — REQ-148's rule. An adapter storing chains separately
+ *    can get this wrong, so the contract has to require it rather than one implementation happening
+ *    to do it.
+ *
+ * NOT DECLARED, and why: transactions, batching, pagination, RBAC. No caller needs them, they cannot
+ * be verified by the two adapters, and an unverifiable contract clause is worth less than a comment.
+ * ADR-001 named speculative port design as the cost of deciding early; this is where that cost is
+ * refused.
+ */
+export interface LedgerStore {
+    /** This writer's identity — the one used for events this store appends. */
+    replicaId(): string;
+    /** Known chains by IDENTITY, never by location: a path here is a filesystem assumption a server adapter could not satisfy. */
+    chains(): {
+        replicaId: string | null;
+        id: string;
+    }[];
+    /** Every event across every chain, deterministically ordered. */
+    loadAll(): LedgerEvent[];
+    /** Per-chain verification; one broken chain fails the whole store and is named. */
+    verifyAll(): {
+        ok: boolean;
+        broken: {
+            replicaId: string | null;
+            detail?: string;
+        }[];
+    };
+    /** Append to this writer's chain. Never modifies or removes an existing event. */
+    append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
+    /** Spent on ANY chain — see the interface note. */
+    isNonceConsumed(nonce: string): boolean;
+}
+/**
+ * Local adapter — DELEGATES to `ProvenanceLedger` rather than re-implementing it.
+ *
+ * That is load-bearing, not stylistic. REQ-141's per-file lock, REQ-147's read compatibility with the
+ * pre-split ledger, and REQ-148's replica split all live inside `ProvenanceLedger`. An adapter that
+ * wrote files itself would satisfy every conformance test while silently dropping all three, and
+ * nothing in this suite would notice — which is why a structural test pins the delegation too.
+ */
+export declare class FileLedgerStore implements LedgerStore {
+    private readonly dir;
+    private readonly givenId?;
+    private readonly inner;
+    private cachedId;
+    /**
+     * The replica id is resolved LAZILY and the root derivation is delegated.
+     *
+     * Both were regressions I reintroduced here: resolving in the constructor made a mere read create
+     * `.ax/state/` (REQ-148 had fixed precisely that in ProvenanceLedger), and deriving the project
+     * root with a local regex duplicated a rule that already exists — two copies of one rule drift.
+     * The contract now demands the no-footprint property so the NEXT adapter cannot lose it either.
+     */
+    constructor(dir: string, givenId?: string | undefined);
+    replicaId(): string;
+    chains(): {
+        replicaId: string | null;
+        id: string;
+    }[];
+    loadAll(): LedgerEvent[];
+    verifyAll(): {
+        ok: boolean;
+        broken: {
+            replicaId: string | null;
+            detail?: string;
+        }[];
+    };
+    append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
+    isNonceConsumed(nonce: string): boolean;
+}
+/**
+ * In-memory adapter — the instrument that makes the contract testable.
+ *
+ * Uses NO filesystem, deliberately. An in-memory store backed by a temp directory would be the file
+ * adapter in disguise and would prove nothing about coupling. It reuses the pure chain functions
+ * (`chainNext`, `verifyChain`) because those are the format, not the storage.
+ */
+export declare class MemoryLedgerStore implements LedgerStore {
+    private readonly id;
+    private readonly byReplica;
+    constructor(id?: string);
+    replicaId(): string;
+    chains(): {
+        replicaId: string | null;
+        id: string;
+    }[];
+    loadAll(): LedgerEvent[];
+    verifyAll(): {
+        ok: boolean;
+        broken: {
+            replicaId: string | null;
+            detail?: string;
+        }[];
+    };
+    append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
+    isNonceConsumed(nonce: string): boolean;
+}

package/dist/holmes/governance/progress-ledger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * L4 — append-only PROGRESS ledger + checkpoints (target-architecture §7 L4).
+ *
+ * Complements the decision ledger (guardrail/decision-ledger.ts, same L4 family): decisions record
+ * WHY, this ledger records WHAT HAPPENED — slices completed, findings, checkpoints — as append-only
+ * JSONL under .ax/ledger/progress.jsonl (gitignored, like all .ax derived state). Append-only means
+ * an agent cannot rewrite history it doesn't like; a checkpoint entry pins the git HEAD + suite count
+ * so "where were we / what was green" survives compaction and session loss.
+ *
+ * Pure half: formatProgressEntry / parseProgressLog (deterministic — the caller supplies the
+ * timestamp, this module never reads a clock). I/O half: appendProgress / readProgress (fail-open).
+ */
+export type ProgressKind = 'slice' | 'finding' | 'checkpoint' | 'note';
+export interface ProgressEntry {
+    ts: string;
+    kind: ProgressKind;
+    summary: string;
+    refs?: string[];
+    suite?: number;
+    head?: string;
+}
+export declare function formatProgressEntry(e: ProgressEntry): string;
+export declare function parseProgressLog(text: string): ProgressEntry[];
+export declare function appendProgress(root: string, entry: ProgressEntry): boolean;
+export declare function readProgress(root: string, lastN?: number): ProgressEntry[];