@sentropic/h2a-cli 0.1.1 → 0.1.7

package/dist/runtime/local-files/locks.js

@@ -0,0 +1,197 @@
+/**
+ * Advisory file locking for the local-files store (DEC-036).
+ *
+ * The store layout (DEC-031) was originally written under the assumption that
+ * a single CLI/MCP process owned the `<root>/.h2a/` tree at any given time.
+ * In practice, multiple `h2a` invocations and an `h2a mcp-serve` process can
+ * race on the same root. Append-only JSONL files (`registry/instances.jsonl`,
+ * `negotiations/<id>/journal.jsonl`) survive this via the `PIPE_BUF`
+ * atomicity of `appendFileSync` for sub-4KB lines, but every read-then-write
+ * critical section (dup detection on `registerInstance`, hash-chain link on
+ * `appendNegotiationEvent`, the whole `stabilizeNegotiation` transaction)
+ * remains a race.
+ *
+ * This module implements **advisory** file locking via exclusive-create
+ * sentinel files (`O_CREAT | O_EXCL` semantics through `openSync(path, "wx")`).
+ * It is intentionally limited to **same-machine** coordination: a lock file
+ * holding a foreign-host PID would be treated as live (we cannot
+ * `process.kill(pid, 0)` across hosts). Cross-machine sharing of a store
+ * remains out of scope (V2).
+ *
+ * Stale-lock recovery: if the lock file already exists, we parse its JSON
+ * payload `{pid, hostname, startedAt}`. If `hostname` matches and the PID is
+ * gone (`process.kill(pid, 0)` throws `ESRCH`), we reclaim the lock by
+ * unlinking and retrying. Otherwise we poll up to `timeoutMs` and throw
+ * `LockTimeoutError`.
+ */
+import { closeSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+export class LockTimeoutError extends Error {
+    lockPath;
+    lastSeenOwner;
+    constructor(lockPath, lastSeenOwner, timeoutMs) {
+        const ownerSuffix = lastSeenOwner
+            ? ` held by ${JSON.stringify(lastSeenOwner)}`
+            : "";
+        super(`LockTimeoutError: could not acquire ${lockPath} within ${timeoutMs}ms${ownerSuffix}`);
+        this.name = "LockTimeoutError";
+        this.lockPath = lockPath;
+        this.lastSeenOwner = lastSeenOwner;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_POLL_MS = 50;
+function tryParseOwner(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed.pid === "number" &&
+            typeof parsed.hostname === "string" &&
+            typeof parsed.startedAt === "string") {
+            return { pid: parsed.pid, hostname: parsed.hostname, startedAt: parsed.startedAt };
+        }
+    }
+    catch {
+        /* malformed — fall through */
+    }
+    return undefined;
+}
+function pidIsAliveOnSameHost(owner, selfHostname) {
+    if (owner.hostname !== selfHostname) {
+        // Cross-host owner: we cannot probe its liveness. Treat as live to err on
+        // the side of safety (the caller will then time out, which is the
+        // expected behaviour — cross-machine store sharing is out of scope V1).
+        return true;
+    }
+    try {
+        process.kill(owner.pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false;
+        // EPERM means the process exists but is owned by another user — still
+        // live for our purposes.
+        return true;
+    }
+}
+function acquire(lockPath, selfHostname) {
+    const ownerPayload = {
+        pid: process.pid,
+        hostname: selfHostname,
+        startedAt: new Date().toISOString()
+    };
+    try {
+        const fd = openSync(lockPath, "wx");
+        try {
+            writeFileSync(fd, JSON.stringify(ownerPayload));
+        }
+        finally {
+            closeSync(fd);
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "EEXIST")
+            throw err;
+    }
+    // Lock exists — inspect the owner record for staleness.
+    let raw;
+    try {
+        raw = readFileSync(lockPath, "utf8");
+    }
+    catch {
+        // The lock was released between EEXIST and our read. Caller should retry.
+        return { ok: false };
+    }
+    const owner = tryParseOwner(raw);
+    if (owner && !pidIsAliveOnSameHost(owner, selfHostname)) {
+        // Stale: reclaim by unlinking. The next loop iteration retries the create.
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* concurrent reclaim — fine */
+        }
+        return { ok: false };
+    }
+    return { ok: false, lastSeen: owner };
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function busyWaitSync(ms) {
+    // Synchronous wait without blocking event-loop indefinitely. Used by
+    // `withLockSync` only — most store methods are sync today and we don't
+    // want to ripple `async` through them just for locking (DEC-036).
+    const end = Date.now() + ms;
+    // `Atomics.wait` on a private SharedArrayBuffer is the standard
+    // "sleep without spinning" primitive in modern Node.
+    const sab = new SharedArrayBuffer(4);
+    const view = new Int32Array(sab);
+    while (Date.now() < end) {
+        const remaining = end - Date.now();
+        if (remaining <= 0)
+            break;
+        Atomics.wait(view, 0, 0, Math.min(remaining, 25));
+    }
+}
+export async function withLock(lockPath, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    const selfHostname = hostname();
+    const deadline = Date.now() + timeoutMs;
+    let lastSeen;
+    while (true) {
+        const attempt = acquire(lockPath, selfHostname);
+        if (attempt.ok)
+            break;
+        lastSeen = attempt.lastSeen ?? lastSeen;
+        if (Date.now() >= deadline) {
+            throw new LockTimeoutError(lockPath, lastSeen, timeoutMs);
+        }
+        await delay(pollMs);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* lock file already gone — fine */
+        }
+    }
+}
+export function withLockSync(lockPath, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    const selfHostname = hostname();
+    const deadline = Date.now() + timeoutMs;
+    let lastSeen;
+    while (true) {
+        const attempt = acquire(lockPath, selfHostname);
+        if (attempt.ok)
+            break;
+        lastSeen = attempt.lastSeen ?? lastSeen;
+        if (Date.now() >= deadline) {
+            throw new LockTimeoutError(lockPath, lastSeen, timeoutMs);
+        }
+        busyWaitSync(pollMs);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* lock file already gone — fine */
+        }
+    }
+}
+//# sourceMappingURL=locks.js.map

package/dist/runtime/local-files/locks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locks.js","sourceRoot":"","sources":["../../../src/runtime/local-files/locks.ts"],"names":[],"mappings":"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"}

package/dist/runtime/local-files/paths.d.ts

@@ -0,0 +1,18 @@
+export interface LocalStorePaths {
+    root: string;
+    registry: string;
+    instances: string;
+    contracts: string;
+    policies: string;
+    engagements: string;
+    artifacts: string;
+    negotiations: string;
+    inbox: string;
+    outbox: string;
+}
+export declare function localStorePaths(root: string): LocalStorePaths;
+export declare function negotiationDir(paths: LocalStorePaths, negotiationId: string): string;
+export declare function negotiationJournalFile(paths: LocalStorePaths, negotiationId: string): string;
+export declare function inboxDir(paths: LocalStorePaths, actor: string): string;
+export declare function outboxDir(paths: LocalStorePaths, actor: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/runtime/local-files/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/runtime/local-files/paths.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAa7D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,eAAe,EACtB,aAAa,EAAE,MAAM,GACpB,MAAM,CAER;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvE"}

package/dist/runtime/local-files/paths.js

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+export function localStorePaths(root) {
+    return {
+        root,
+        registry: join(root, "registry"),
+        instances: join(root, "registry", "instances.jsonl"),
+        contracts: join(root, "contracts"),
+        policies: join(root, "policies"),
+        engagements: join(root, "engagements"),
+        artifacts: join(root, "artifacts"),
+        negotiations: join(root, "negotiations"),
+        inbox: join(root, "inbox"),
+        outbox: join(root, "outbox")
+    };
+}
+export function negotiationDir(paths, negotiationId) {
+    return join(paths.negotiations, negotiationId);
+}
+export function negotiationJournalFile(paths, negotiationId) {
+    return join(negotiationDir(paths, negotiationId), "journal.jsonl");
+}
+export function inboxDir(paths, actor) {
+    return join(paths.inbox, actor);
+}
+export function outboxDir(paths, actor) {
+    return join(paths.outbox, actor);
+}
+//# sourceMappingURL=paths.js.map

package/dist/runtime/local-files/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/runtime/local-files/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAejC,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;QAChC,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,iBAAiB,CAAC;QACpD,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC;QAClC,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;QAChC,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC;QACtC,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC;QAClC,YAAY,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC;QACxC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC;QAC1B,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC;KAC7B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAsB,EAAE,aAAqB;IAC1E,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,KAAsB,EACtB,aAAqB;IAErB,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAsB,EAAE,KAAa;IAC5D,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAsB,EAAE,KAAa;IAC7D,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACnC,CAAC"}

package/dist/runtime/local-files/schema.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Local-files store schema versioning (DEC-036).
+ *
+ * Every initialized store carries a `<root>/.h2a-schema.json` sentinel:
+ *
+ * ```json
+ * {
+ *   "version": "1",
+ *   "createdAt": "2026-05-20T08:12:34.567Z",
+ *   "createdBy": "@sentropic/h2a-cli@0.1.1"
+ * }
+ * ```
+ *
+ * The version string is opaque and strictly compared against
+ * `H2A_STORE_SCHEMA_VERSION`. A future schema bump requires:
+ *
+ *  - a new DEC documenting the layout change,
+ *  - a migration ramp (`h2a store migrate --from <old> --to <new>`),
+ *  - a `H2A_STORE_SCHEMA_VERSION` bump in this file.
+ *
+ * The escape hatch `createLocalStore({ allowVersionMismatch: true })` is
+ * intentionally narrow: it logs a stderr warning, skips the version check,
+ * and **never** rewrites the sentinel. It exists so a read-only inspection
+ * tool (e.g., a debugger) can open a store written by a newer CLI.
+ */
+export declare const H2A_STORE_SCHEMA_VERSION: "1";
+export declare const H2A_STORE_SCHEMA_FILE: ".h2a-schema.json";
+export interface H2AStoreSchemaSentinel {
+    readonly version: string;
+    readonly createdAt: string;
+    readonly createdBy: string;
+}
+export declare class StoreSchemaMismatchError extends Error {
+    readonly foundVersion: string;
+    readonly expectedVersion: string;
+    constructor(foundVersion: string, expectedVersion: string, root: string);
+}
+/**
+ * Best-effort lookup of `@sentropic/h2a-cli`'s own package version. We walk
+ * up from the current module file (`dist/runtime/local-files/schema.js` at
+ * runtime, or the TS source under tests) until we find a `package.json`
+ * whose `name` matches. Falls back to `0.0.0-unknown` if the search fails,
+ * which only affects the `createdBy` metadata field — it never aborts a
+ * store init.
+ */
+export declare function readCliPackageVersion(): string;
+//# sourceMappingURL=schema.d.ts.map

package/dist/runtime/local-files/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/runtime/local-files/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,eAAO,MAAM,wBAAwB,EAAG,GAAY,CAAC;AAErD,eAAO,MAAM,qBAAqB,EAAG,kBAA2B,CAAC;AAEjE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;gBAErB,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAQxE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAwB9C"}

package/dist/runtime/local-files/schema.js

@@ -0,0 +1,77 @@
+/**
+ * Local-files store schema versioning (DEC-036).
+ *
+ * Every initialized store carries a `<root>/.h2a-schema.json` sentinel:
+ *
+ * ```json
+ * {
+ *   "version": "1",
+ *   "createdAt": "2026-05-20T08:12:34.567Z",
+ *   "createdBy": "@sentropic/h2a-cli@0.1.1"
+ * }
+ * ```
+ *
+ * The version string is opaque and strictly compared against
+ * `H2A_STORE_SCHEMA_VERSION`. A future schema bump requires:
+ *
+ *  - a new DEC documenting the layout change,
+ *  - a migration ramp (`h2a store migrate --from <old> --to <new>`),
+ *  - a `H2A_STORE_SCHEMA_VERSION` bump in this file.
+ *
+ * The escape hatch `createLocalStore({ allowVersionMismatch: true })` is
+ * intentionally narrow: it logs a stderr warning, skips the version check,
+ * and **never** rewrites the sentinel. It exists so a read-only inspection
+ * tool (e.g., a debugger) can open a store written by a newer CLI.
+ */
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+export const H2A_STORE_SCHEMA_VERSION = "1";
+export const H2A_STORE_SCHEMA_FILE = ".h2a-schema.json";
+export class StoreSchemaMismatchError extends Error {
+    foundVersion;
+    expectedVersion;
+    constructor(foundVersion, expectedVersion, root) {
+        super(`StoreSchemaMismatchError: store at ${root} declares schema version "${foundVersion}" but this CLI expects "${expectedVersion}". Run \`h2a store migrate --from ${foundVersion} --to ${expectedVersion}\` or pass \`allowVersionMismatch: true\` for read-only inspection (DEC-036).`);
+        this.name = "StoreSchemaMismatchError";
+        this.foundVersion = foundVersion;
+        this.expectedVersion = expectedVersion;
+    }
+}
+/**
+ * Best-effort lookup of `@sentropic/h2a-cli`'s own package version. We walk
+ * up from the current module file (`dist/runtime/local-files/schema.js` at
+ * runtime, or the TS source under tests) until we find a `package.json`
+ * whose `name` matches. Falls back to `0.0.0-unknown` if the search fails,
+ * which only affects the `createdBy` metadata field — it never aborts a
+ * store init.
+ */
+export function readCliPackageVersion() {
+    try {
+        const here = fileURLToPath(import.meta.url);
+        let dir = dirname(here);
+        // Walk up at most 8 levels (dist/runtime/local-files → package root is
+        // typically 3, but allow some slack for the source-mode test runner).
+        for (let i = 0; i < 8; i++) {
+            try {
+                const raw = readFileSync(`${dir}/package.json`, "utf8");
+                const parsed = JSON.parse(raw);
+                if (parsed.name === "@sentropic/h2a-cli" && typeof parsed.version === "string") {
+                    return `@sentropic/h2a-cli@${parsed.version}`;
+                }
+            }
+            catch {
+                /* keep walking */
+            }
+            const next = dirname(dir);
+            if (next === dir)
+                break;
+            dir = next;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return "@sentropic/h2a-cli@0.0.0-unknown";
+}
+//# sourceMappingURL=schema.js.map

package/dist/runtime/local-files/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/runtime/local-files/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAY,CAAC;AAErD,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAA2B,CAAC;AAQjE,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACxC,YAAY,CAAS;IACrB,eAAe,CAAS;IAEjC,YAAY,YAAoB,EAAE,eAAuB,EAAE,IAAY;QACrE,KAAK,CACH,sCAAsC,IAAI,6BAA6B,YAAY,2BAA2B,eAAe,qCAAqC,YAAY,SAAS,eAAe,+EAA+E,CACtR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,uEAAuE;QACvE,sEAAsE;QACtE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,GAAG,eAAe,EAAE,MAAM,CAAC,CAAC;gBACxD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwC,CAAC;gBACtE,IAAI,MAAM,CAAC,IAAI,KAAK,oBAAoB,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;oBAC/E,OAAO,sBAAsB,MAAM,CAAC,OAAO,EAAE,CAAC;gBAChD,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,kBAAkB;YACpB,CAAC;YACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YAC1B,IAAI,IAAI,KAAK,GAAG;gBAAE,MAAM;YACxB,GAAG,GAAG,IAAI,CAAC;QACb,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IACD,OAAO,kCAAkC,CAAC;AAC5C,CAAC"}

package/dist/runtime/local-files/store.d.ts

@@ -0,0 +1,44 @@
+import { type H2AActorRegistration, type H2AEnvelope, type H2AJournalEntry, type H2AJournalPayload, type H2ANegotiationRecord } from "@sentropic/h2a";
+import { type LocalStorePaths } from "./paths.js";
+export interface CreateLocalStoreOptions {
+    root: string;
+    /**
+     * Timeout (ms) for acquiring any per-store advisory file lock. Defaults to
+     * 5000. Tests use a much smaller value to exercise the timeout path
+     * without slowing the suite. DEC-036.
+     */
+    lockTimeoutMs?: number;
+    /**
+     * Read-only escape hatch: if the on-disk `.h2a-schema.json` declares a
+     * version we don't recognize, proceed anyway with a stderr warning. Never
+     * rewrites the sentinel. Intended for inspection tooling. DEC-036.
+     */
+    allowVersionMismatch?: boolean;
+}
+export interface LocalStore {
+    paths: LocalStorePaths;
+    registerInstance(reg: H2AActorRegistration): void;
+    listInstances(): H2AActorRegistration[];
+    findInstance(id: string): H2AActorRegistration | undefined;
+    openNegotiation(record: H2ANegotiationRecord): H2ANegotiationRecord;
+    readNegotiation(id: string): H2ANegotiationRecord | undefined;
+    updateNegotiationStatus(id: string, status: H2ANegotiationRecord["status"]): H2ANegotiationRecord;
+    appendNegotiationEvent<TBody = unknown>(negotiationId: string, payload: H2AJournalPayload<TBody>): H2AJournalEntry<TBody>;
+    readNegotiationJournal(negotiationId: string): H2AJournalEntry<unknown>[];
+    stabilizeNegotiation(negotiationId: string, options?: {
+        eventId?: string;
+    }): {
+        record: H2ANegotiationRecord;
+        artifactHash: string;
+        signers: string[];
+        finalEvent: H2AJournalEntry<unknown>;
+        artifactPath: string;
+    };
+    putInboxMessage(actor: string, envelope: H2AEnvelope): void;
+    readInbox(actor: string): H2AEnvelope[];
+    popInboxMessage(actor: string, envelopeId: string): H2AEnvelope | undefined;
+    putOutboxMessage(actor: string, envelope: H2AEnvelope): void;
+    readOutbox(actor: string): H2AEnvelope[];
+}
+export declare function createLocalStore(options: CreateLocalStoreOptions): LocalStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/runtime/local-files/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/runtime/local-files/store.ts"],"names":[],"mappings":"AAWA,OAAO,EAWL,KAAK,oBAAoB,EAEzB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAG1B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AASpB,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB,gBAAgB,CAAC,GAAG,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAClD,aAAa,IAAI,oBAAoB,EAAE,CAAC;IACxC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAAC;IAC3D,eAAe,CAAC,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IACpE,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAAC;IAC9D,uBAAuB,CACrB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACrC,oBAAoB,CAAC;IACxB,sBAAsB,CAAC,KAAK,GAAG,OAAO,EACpC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAChC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC1B,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1E,oBAAoB,CAClB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7B;QACD,MAAM,EAAE,oBAAoB,CAAC;QAC7B,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,UAAU,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;QACrC,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IACxC,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAC5E,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7D,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;CAC1C;AA8GD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CAga7E"}