open-multi-agent-kit 0.90.7 → 0.90.9

package/dist/guardrails/replay-ledger-lock.js

@@ -0,0 +1,135 @@
+import { linkSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+import { createLockCandidate, fsyncDirectory, removeLockCandidate } from "./replay-ledger-io.js";
+import { createLockOwner, errorCode, inspectProcessIdentity, lockOwnerIsDead, lockOwnersEqual, ReplayLedgerLockError, readLockOwner, } from "./replay-ledger-lock-owner.js";
+import { ReplayLedgerMutationGate } from "./replay-ledger-mutation-gate.js";
+export { fsyncDirectory, writeAll } from "./replay-ledger-io.js";
+export { ReplayLedgerLockError } from "./replay-ledger-lock-owner.js";
+const LOCK_ATTEMPTS = 200;
+const LOCK_WAIT_MS = 5;
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+export class ReplayLedgerLock {
+    path;
+    gate;
+    processIdentity;
+    beforeReclaimRemove;
+    constructor(path, options = {}) {
+        this.path = path;
+        this.processIdentity = options.processIdentity ?? inspectProcessIdentity;
+        this.beforeReclaimRemove = options.beforeReclaimRemove;
+        this.gate = new ReplayLedgerMutationGate(`${path}.reclaim`, {
+            processIdentity: this.processIdentity,
+            beforeReclaimRemove: options.beforeMutationGateReclaimRemove,
+            beforeRelease: options.beforeMutationGateRelease,
+        });
+    }
+    withMutationGate(operation) {
+        return this.gate.run(operation);
+    }
+    tryAcquire(candidate, expected) {
+        return this.withMutationGate(() => {
+            try {
+                linkSync(candidate, this.path);
+                fsyncDirectory(dirname(this.path));
+                const acquired = readLockOwner(this.path);
+                if (!lockOwnersEqual(acquired, expected)) {
+                    throw new ReplayLedgerLockError("replay lock ownership changed during acquisition");
+                }
+                return acquired;
+            }
+            catch (error) {
+                if (errorCode(error) === "EEXIST")
+                    return undefined;
+                throw error;
+            }
+        });
+    }
+    reclaim(observed) {
+        this.withMutationGate(() => {
+            let current;
+            try {
+                current = readLockOwner(this.path);
+            }
+            catch (error) {
+                if (errorCode(error) === "ENOENT")
+                    return;
+                throw error;
+            }
+            if (!lockOwnersEqual(current, observed))
+                return;
+            this.beforeReclaimRemove?.();
+            let finalOwner;
+            try {
+                finalOwner = readLockOwner(this.path);
+            }
+            catch (error) {
+                if (errorCode(error) === "ENOENT")
+                    return;
+                throw error;
+            }
+            if (!lockOwnersEqual(finalOwner, observed))
+                return;
+            unlinkSync(this.path);
+            fsyncDirectory(dirname(this.path));
+        });
+    }
+    acquire(owner) {
+        const candidate = createLockCandidate(this.path, owner);
+        try {
+            const expected = readLockOwner(candidate);
+            for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+                let current;
+                try {
+                    current = readLockOwner(this.path);
+                }
+                catch (error) {
+                    if (errorCode(error) !== "ENOENT")
+                        throw error;
+                    const acquired = this.tryAcquire(candidate, expected);
+                    if (acquired !== undefined)
+                        return acquired;
+                    continue;
+                }
+                if (lockOwnerIsDead(current.owner, this.processIdentity)) {
+                    this.reclaim(current);
+                    continue;
+                }
+                Atomics.wait(sleeper, 0, 0, LOCK_WAIT_MS);
+            }
+            throw new ReplayLedgerLockError("replay ledger interprocess lock is unavailable");
+        }
+        finally {
+            removeLockCandidate(candidate);
+        }
+    }
+    release(acquired) {
+        this.withMutationGate(() => {
+            const current = readLockOwner(this.path);
+            if (!lockOwnersEqual(current, acquired)) {
+                throw new ReplayLedgerLockError("replay lock ownership changed before release");
+            }
+            unlinkSync(this.path);
+            fsyncDirectory(dirname(this.path));
+        });
+    }
+    run(operation) {
+        const acquired = this.acquire(createLockOwner(this.processIdentity));
+        let result;
+        try {
+            result = operation();
+        }
+        catch (error) {
+            this.release(acquired);
+            throw error;
+        }
+        if (result !== null &&
+            (typeof result === "object" || typeof result === "function") &&
+            "then" in result &&
+            typeof result.then === "function") {
+            return Promise.resolve(result).finally(() => this.release(acquired));
+        }
+        this.release(acquired);
+        return result;
+    }
+}
+//# sourceMappingURL=replay-ledger-lock.js.map

package/dist/guardrails/replay-ledger-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-ledger-lock.js","sourceRoot":"","sources":["../../src/guardrails/replay-ledger-lock.ts"],"names":[],"mappings":"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","sourcesContent":["import { linkSync, unlinkSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { createLockCandidate, fsyncDirectory, removeLockCandidate } from \"./replay-ledger-io.ts\";\nimport {\n\tcreateLockOwner,\n\terrorCode,\n\tinspectProcessIdentity,\n\ttype LockOwner,\n\ttype LockOwnerSnapshot,\n\tlockOwnerIsDead,\n\tlockOwnersEqual,\n\tReplayLedgerLockError,\n\ttype ReplayLedgerProcessIdentityReader,\n\treadLockOwner,\n} from \"./replay-ledger-lock-owner.ts\";\nimport { ReplayLedgerMutationGate } from \"./replay-ledger-mutation-gate.ts\";\n\nexport { fsyncDirectory, writeAll } from \"./replay-ledger-io.ts\";\nexport type { ReplayLedgerProcessIdentity } from \"./replay-ledger-lock-owner.ts\";\nexport { ReplayLedgerLockError } from \"./replay-ledger-lock-owner.ts\";\n\nconst LOCK_ATTEMPTS = 200;\nconst LOCK_WAIT_MS = 5;\nconst sleeper = new Int32Array(new SharedArrayBuffer(4));\n\nexport interface ReplayLedgerLockOptions {\n\treadonly processIdentity?: ReplayLedgerProcessIdentityReader;\n\treadonly beforeReclaimRemove?: () => void;\n\treadonly beforeMutationGateReclaimRemove?: () => void;\n\treadonly beforeMutationGateRelease?: () => void;\n}\n\nexport class ReplayLedgerLock {\n\tprivate readonly path: string;\n\tprivate readonly gate: ReplayLedgerMutationGate;\n\tprivate readonly processIdentity: ReplayLedgerProcessIdentityReader;\n\tprivate readonly beforeReclaimRemove: (() => void) | undefined;\n\n\tconstructor(path: string, options: ReplayLedgerLockOptions = {}) {\n\t\tthis.path = path;\n\t\tthis.processIdentity = options.processIdentity ?? inspectProcessIdentity;\n\t\tthis.beforeReclaimRemove = options.beforeReclaimRemove;\n\t\tthis.gate = new ReplayLedgerMutationGate(`${path}.reclaim`, {\n\t\t\tprocessIdentity: this.processIdentity,\n\t\t\tbeforeReclaimRemove: options.beforeMutationGateReclaimRemove,\n\t\t\tbeforeRelease: options.beforeMutationGateRelease,\n\t\t});\n\t}\n\n\tprivate withMutationGate<T>(operation: () => T): T {\n\t\treturn this.gate.run(operation);\n\t}\n\n\tprivate tryAcquire(candidate: string, expected: LockOwnerSnapshot): LockOwnerSnapshot | undefined {\n\t\treturn this.withMutationGate(() => {\n\t\t\ttry {\n\t\t\t\tlinkSync(candidate, this.path);\n\t\t\t\tfsyncDirectory(dirname(this.path));\n\t\t\t\tconst acquired = readLockOwner(this.path);\n\t\t\t\tif (!lockOwnersEqual(acquired, expected)) {\n\t\t\t\t\tthrow new ReplayLedgerLockError(\"replay lock ownership changed during acquisition\");\n\t\t\t\t}\n\t\t\t\treturn acquired;\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"EEXIST\") return undefined;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t});\n\t}\n\n\tprivate reclaim(observed: LockOwnerSnapshot): void {\n\t\tthis.withMutationGate(() => {\n\t\t\tlet current: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tcurrent = readLockOwner(this.path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") return;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (!lockOwnersEqual(current, observed)) return;\n\t\t\tthis.beforeReclaimRemove?.();\n\t\t\tlet finalOwner: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tfinalOwner = readLockOwner(this.path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") return;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (!lockOwnersEqual(finalOwner, observed)) return;\n\t\t\tunlinkSync(this.path);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t});\n\t}\n\n\tprivate acquire(owner: LockOwner): LockOwnerSnapshot {\n\t\tconst candidate = createLockCandidate(this.path, owner);\n\t\ttry {\n\t\t\tconst expected = readLockOwner(candidate);\n\t\t\tfor (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {\n\t\t\t\tlet current: LockOwnerSnapshot;\n\t\t\t\ttry {\n\t\t\t\t\tcurrent = readLockOwner(this.path);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (errorCode(error) !== \"ENOENT\") throw error;\n\t\t\t\t\tconst acquired = this.tryAcquire(candidate, expected);\n\t\t\t\t\tif (acquired !== undefined) return acquired;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (lockOwnerIsDead(current.owner, this.processIdentity)) {\n\t\t\t\t\tthis.reclaim(current);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tAtomics.wait(sleeper, 0, 0, LOCK_WAIT_MS);\n\t\t\t}\n\t\t\tthrow new ReplayLedgerLockError(\"replay ledger interprocess lock is unavailable\");\n\t\t} finally {\n\t\t\tremoveLockCandidate(candidate);\n\t\t}\n\t}\n\n\tprivate release(acquired: LockOwnerSnapshot): void {\n\t\tthis.withMutationGate(() => {\n\t\t\tconst current = readLockOwner(this.path);\n\t\t\tif (!lockOwnersEqual(current, acquired)) {\n\t\t\t\tthrow new ReplayLedgerLockError(\"replay lock ownership changed before release\");\n\t\t\t}\n\t\t\tunlinkSync(this.path);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t});\n\t}\n\n\trun<T>(operation: () => T): T {\n\t\tconst acquired = this.acquire(createLockOwner(this.processIdentity));\n\t\tlet result: T;\n\t\ttry {\n\t\t\tresult = operation();\n\t\t} catch (error) {\n\t\t\tthis.release(acquired);\n\t\t\tthrow error;\n\t\t}\n\t\tif (\n\t\t\tresult !== null &&\n\t\t\t(typeof result === \"object\" || typeof result === \"function\") &&\n\t\t\t\"then\" in result &&\n\t\t\ttypeof result.then === \"function\"\n\t\t) {\n\t\t\treturn Promise.resolve(result).finally(() => this.release(acquired)) as T;\n\t\t}\n\t\tthis.release(acquired);\n\t\treturn result;\n\t}\n}\n"]}

package/dist/guardrails/replay-ledger-mutation-gate.d.ts

@@ -0,0 +1,24 @@
+import { type ReplayLedgerProcessIdentityReader } from "./replay-ledger-lock-owner.ts";
+export interface ReplayLedgerMutationGateOptions {
+    readonly processIdentity?: ReplayLedgerProcessIdentityReader;
+    readonly beforeReclaimRemove?: () => void;
+    readonly beforeRelease?: () => void;
+}
+export declare class ReplayLedgerMutationGate {
+    private readonly path;
+    private readonly processIdentity;
+    private readonly beforeReclaimRemove;
+    private readonly beforeRelease;
+    constructor(path: string, options?: ReplayLedgerMutationGateOptions);
+    private intentPaths;
+    private hasLiveIntent;
+    private withIntent;
+    private abandon;
+    private tryAcquire;
+    private reclaim;
+    private acquire;
+    private releaseOwned;
+    private release;
+    run<T>(operation: () => T): T;
+}
+//# sourceMappingURL=replay-ledger-mutation-gate.d.ts.map

package/dist/guardrails/replay-ledger-mutation-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-ledger-mutation-gate.d.ts","sourceRoot":"","sources":["../../src/guardrails/replay-ledger-mutation-gate.ts"],"names":[],"mappings":"AAGA,OAAO,EASN,KAAK,iCAAiC,EAEtC,MAAM,+BAA+B,CAAC;AAMvC,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,CAAC,eAAe,CAAC,EAAE,iCAAiC,CAAC;IAC7D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAED,qBAAa,wBAAwB;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IACpE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA2B;IAC/D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IAEzD,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,+BAAoC,EAKtE;IAED,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,aAAa;IA4BrB,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,UAAU;IAqBlB,OAAO,CAAC,OAAO;IAwBf,OAAO,CAAC,OAAO;IA0Bf,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,OAAO;IAKf,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAmB5B;CACD","sourcesContent":["import { linkSync, readdirSync, unlinkSync } from \"node:fs\";\nimport { basename, dirname, join } from \"node:path\";\nimport { createLockCandidate, fsyncDirectory, removeLockCandidate } from \"./replay-ledger-io.ts\";\nimport {\n\tcreateLockOwner,\n\terrorCode,\n\tinspectProcessIdentity,\n\ttype LockOwner,\n\ttype LockOwnerSnapshot,\n\tlockOwnerIsDead,\n\tlockOwnersEqual,\n\tReplayLedgerLockError,\n\ttype ReplayLedgerProcessIdentityReader,\n\treadLockOwner,\n} from \"./replay-ledger-lock-owner.ts\";\n\nconst GATE_ATTEMPTS = 200;\nconst GATE_WAIT_MS = 5;\nconst sleeper = new Int32Array(new SharedArrayBuffer(4));\n\nexport interface ReplayLedgerMutationGateOptions {\n\treadonly processIdentity?: ReplayLedgerProcessIdentityReader;\n\treadonly beforeReclaimRemove?: () => void;\n\treadonly beforeRelease?: () => void;\n}\n\nexport class ReplayLedgerMutationGate {\n\tprivate readonly path: string;\n\tprivate readonly processIdentity: ReplayLedgerProcessIdentityReader;\n\tprivate readonly beforeReclaimRemove: (() => void) | undefined;\n\tprivate readonly beforeRelease: (() => void) | undefined;\n\n\tconstructor(path: string, options: ReplayLedgerMutationGateOptions = {}) {\n\t\tthis.path = path;\n\t\tthis.processIdentity = options.processIdentity ?? inspectProcessIdentity;\n\t\tthis.beforeReclaimRemove = options.beforeReclaimRemove;\n\t\tthis.beforeRelease = options.beforeRelease;\n\t}\n\n\tprivate intentPaths(): string[] {\n\t\tconst directory = dirname(this.path);\n\t\tconst prefix = `${basename(this.path)}.intent.`;\n\t\treturn readdirSync(directory)\n\t\t\t.filter((name) => name.startsWith(prefix))\n\t\t\t.map((name) => join(directory, name));\n\t}\n\n\tprivate hasLiveIntent(): boolean {\n\t\tconst prefix = `${this.path}.intent.`;\n\t\tfor (const path of this.intentPaths()) {\n\t\t\tlet observed: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tobserved = readLockOwner(path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") continue;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (path.slice(prefix.length) !== observed.owner.ownerId) {\n\t\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim intent owner is invalid\");\n\t\t\t}\n\t\t\tif (!lockOwnerIsDead(observed.owner, this.processIdentity)) return true;\n\t\t\tlet current: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tcurrent = readLockOwner(path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") continue;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (!lockOwnersEqual(current, observed) || !lockOwnerIsDead(current.owner, this.processIdentity)) return true;\n\t\t\tremoveLockCandidate(path);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t}\n\t\treturn false;\n\t}\n\n\tprivate withIntent<T>(candidate: string, owner: LockOwner, operation: () => T): T {\n\t\tconst intent = `${this.path}.intent.${owner.ownerId}`;\n\t\tlinkSync(candidate, intent);\n\t\tfsyncDirectory(dirname(this.path));\n\t\ttry {\n\t\t\treturn operation();\n\t\t} finally {\n\t\t\tremoveLockCandidate(intent);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t}\n\t}\n\n\tprivate abandon(acquired: LockOwnerSnapshot): void {\n\t\ttry {\n\t\t\tconst current = readLockOwner(this.path);\n\t\t\tif (lockOwnersEqual(current, acquired)) unlinkSync(this.path);\n\t\t} catch {\n\t\t\t// Preserve the original acquisition error; a mismatched owner must remain.\n\t\t}\n\t}\n\n\tprivate tryAcquire(candidate: string, expected: LockOwnerSnapshot): LockOwnerSnapshot | undefined {\n\t\tif (this.hasLiveIntent()) return undefined;\n\t\tlet linked = false;\n\t\ttry {\n\t\t\tlinkSync(candidate, this.path);\n\t\t\tlinked = true;\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t\tconst acquired = readLockOwner(this.path);\n\t\t\tif (!lockOwnersEqual(acquired, expected)) {\n\t\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim ownership changed during acquisition\");\n\t\t\t}\n\t\t\tif (!this.hasLiveIntent()) return acquired;\n\t\t\tthis.releaseOwned(acquired);\n\t\t\treturn undefined;\n\t\t} catch (error) {\n\t\t\tif (errorCode(error) === \"EEXIST\") return undefined;\n\t\t\tif (linked) this.abandon(expected);\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tprivate reclaim(candidate: string, owner: LockOwner, observed: LockOwnerSnapshot): void {\n\t\tthis.withIntent(candidate, owner, () => {\n\t\t\tlet current: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tcurrent = readLockOwner(this.path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") return;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (!lockOwnersEqual(current, observed) || !lockOwnerIsDead(current.owner, this.processIdentity)) return;\n\t\t\tthis.beforeReclaimRemove?.();\n\t\t\tlet finalOwner: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tfinalOwner = readLockOwner(this.path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") return;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (!lockOwnersEqual(finalOwner, observed) || !lockOwnerIsDead(finalOwner.owner, this.processIdentity)) return;\n\t\t\tremoveLockCandidate(this.path);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t});\n\t}\n\n\tprivate acquire(owner: LockOwner): LockOwnerSnapshot {\n\t\tconst candidate = createLockCandidate(this.path, owner);\n\t\ttry {\n\t\t\tconst expected = readLockOwner(candidate);\n\t\t\tfor (let attempt = 0; attempt < GATE_ATTEMPTS; attempt++) {\n\t\t\t\tconst acquired = this.tryAcquire(candidate, expected);\n\t\t\t\tif (acquired !== undefined) return acquired;\n\t\t\t\tlet current: LockOwnerSnapshot;\n\t\t\t\ttry {\n\t\t\t\t\tcurrent = readLockOwner(this.path);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (errorCode(error) === \"ENOENT\") continue;\n\t\t\t\t\tthrow error;\n\t\t\t\t}\n\t\t\t\tif (lockOwnerIsDead(current.owner, this.processIdentity)) {\n\t\t\t\t\tthis.reclaim(candidate, owner, current);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tAtomics.wait(sleeper, 0, 0, GATE_WAIT_MS);\n\t\t\t}\n\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim serialization is unavailable\");\n\t\t} finally {\n\t\t\tremoveLockCandidate(candidate);\n\t\t}\n\t}\n\n\tprivate releaseOwned(acquired: LockOwnerSnapshot): void {\n\t\tlet current: LockOwnerSnapshot;\n\t\ttry {\n\t\t\tcurrent = readLockOwner(this.path);\n\t\t} catch (error) {\n\t\t\tif (errorCode(error) === \"ENOENT\") {\n\t\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim ownership changed before release\");\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t\tif (!lockOwnersEqual(current, acquired)) {\n\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim ownership changed before release\");\n\t\t}\n\t\tunlinkSync(this.path);\n\t\tfsyncDirectory(dirname(this.path));\n\t}\n\n\tprivate release(acquired: LockOwnerSnapshot): void {\n\t\tthis.beforeRelease?.();\n\t\tthis.releaseOwned(acquired);\n\t}\n\n\trun<T>(operation: () => T): T {\n\t\tconst acquired = this.acquire(createLockOwner(this.processIdentity));\n\t\tlet result: T;\n\t\ttry {\n\t\t\tresult = operation();\n\t\t} catch (error) {\n\t\t\tthis.release(acquired);\n\t\t\tthrow error;\n\t\t}\n\t\tif (\n\t\t\tresult !== null &&\n\t\t\t(typeof result === \"object\" || typeof result === \"function\") &&\n\t\t\t\"then\" in result &&\n\t\t\ttypeof result.then === \"function\"\n\t\t) {\n\t\t\treturn Promise.resolve(result).finally(() => this.release(acquired)) as T;\n\t\t}\n\t\tthis.release(acquired);\n\t\treturn result;\n\t}\n}\n"]}

package/dist/guardrails/replay-ledger-mutation-gate.js

@@ -0,0 +1,205 @@
+import { linkSync, readdirSync, unlinkSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { createLockCandidate, fsyncDirectory, removeLockCandidate } from "./replay-ledger-io.js";
+import { createLockOwner, errorCode, inspectProcessIdentity, lockOwnerIsDead, lockOwnersEqual, ReplayLedgerLockError, readLockOwner, } from "./replay-ledger-lock-owner.js";
+const GATE_ATTEMPTS = 200;
+const GATE_WAIT_MS = 5;
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+export class ReplayLedgerMutationGate {
+    path;
+    processIdentity;
+    beforeReclaimRemove;
+    beforeRelease;
+    constructor(path, options = {}) {
+        this.path = path;
+        this.processIdentity = options.processIdentity ?? inspectProcessIdentity;
+        this.beforeReclaimRemove = options.beforeReclaimRemove;
+        this.beforeRelease = options.beforeRelease;
+    }
+    intentPaths() {
+        const directory = dirname(this.path);
+        const prefix = `${basename(this.path)}.intent.`;
+        return readdirSync(directory)
+            .filter((name) => name.startsWith(prefix))
+            .map((name) => join(directory, name));
+    }
+    hasLiveIntent() {
+        const prefix = `${this.path}.intent.`;
+        for (const path of this.intentPaths()) {
+            let observed;
+            try {
+                observed = readLockOwner(path);
+            }
+            catch (error) {
+                if (errorCode(error) === "ENOENT")
+                    continue;
+                throw error;
+            }
+            if (path.slice(prefix.length) !== observed.owner.ownerId) {
+                throw new ReplayLedgerLockError("replay lock reclaim intent owner is invalid");
+            }
+            if (!lockOwnerIsDead(observed.owner, this.processIdentity))
+                return true;
+            let current;
+            try {
+                current = readLockOwner(path);
+            }
+            catch (error) {
+                if (errorCode(error) === "ENOENT")
+                    continue;
+                throw error;
+            }
+            if (!lockOwnersEqual(current, observed) || !lockOwnerIsDead(current.owner, this.processIdentity))
+                return true;
+            removeLockCandidate(path);
+            fsyncDirectory(dirname(this.path));
+        }
+        return false;
+    }
+    withIntent(candidate, owner, operation) {
+        const intent = `${this.path}.intent.${owner.ownerId}`;
+        linkSync(candidate, intent);
+        fsyncDirectory(dirname(this.path));
+        try {
+            return operation();
+        }
+        finally {
+            removeLockCandidate(intent);
+            fsyncDirectory(dirname(this.path));
+        }
+    }
+    abandon(acquired) {
+        try {
+            const current = readLockOwner(this.path);
+            if (lockOwnersEqual(current, acquired))
+                unlinkSync(this.path);
+        }
+        catch {
+            // Preserve the original acquisition error; a mismatched owner must remain.
+        }
+    }
+    tryAcquire(candidate, expected) {
+        if (this.hasLiveIntent())
+            return undefined;
+        let linked = false;
+        try {
+            linkSync(candidate, this.path);
+            linked = true;
+            fsyncDirectory(dirname(this.path));
+            const acquired = readLockOwner(this.path);
+            if (!lockOwnersEqual(acquired, expected)) {
+                throw new ReplayLedgerLockError("replay lock reclaim ownership changed during acquisition");
+            }
+            if (!this.hasLiveIntent())
+                return acquired;
+            this.releaseOwned(acquired);
+            return undefined;
+        }
+        catch (error) {
+            if (errorCode(error) === "EEXIST")
+                return undefined;
+            if (linked)
+                this.abandon(expected);
+            throw error;
+        }
+    }
+    reclaim(candidate, owner, observed) {
+        this.withIntent(candidate, owner, () => {
+            let current;
+            try {
+                current = readLockOwner(this.path);
+            }
+            catch (error) {
+                if (errorCode(error) === "ENOENT")
+                    return;
+                throw error;
+            }
+            if (!lockOwnersEqual(current, observed) || !lockOwnerIsDead(current.owner, this.processIdentity))
+                return;
+            this.beforeReclaimRemove?.();
+            let finalOwner;
+            try {
+                finalOwner = readLockOwner(this.path);
+            }
+            catch (error) {
+                if (errorCode(error) === "ENOENT")
+                    return;
+                throw error;
+            }
+            if (!lockOwnersEqual(finalOwner, observed) || !lockOwnerIsDead(finalOwner.owner, this.processIdentity))
+                return;
+            removeLockCandidate(this.path);
+            fsyncDirectory(dirname(this.path));
+        });
+    }
+    acquire(owner) {
+        const candidate = createLockCandidate(this.path, owner);
+        try {
+            const expected = readLockOwner(candidate);
+            for (let attempt = 0; attempt < GATE_ATTEMPTS; attempt++) {
+                const acquired = this.tryAcquire(candidate, expected);
+                if (acquired !== undefined)
+                    return acquired;
+                let current;
+                try {
+                    current = readLockOwner(this.path);
+                }
+                catch (error) {
+                    if (errorCode(error) === "ENOENT")
+                        continue;
+                    throw error;
+                }
+                if (lockOwnerIsDead(current.owner, this.processIdentity)) {
+                    this.reclaim(candidate, owner, current);
+                    continue;
+                }
+                Atomics.wait(sleeper, 0, 0, GATE_WAIT_MS);
+            }
+            throw new ReplayLedgerLockError("replay lock reclaim serialization is unavailable");
+        }
+        finally {
+            removeLockCandidate(candidate);
+        }
+    }
+    releaseOwned(acquired) {
+        let current;
+        try {
+            current = readLockOwner(this.path);
+        }
+        catch (error) {
+            if (errorCode(error) === "ENOENT") {
+                throw new ReplayLedgerLockError("replay lock reclaim ownership changed before release");
+            }
+            throw error;
+        }
+        if (!lockOwnersEqual(current, acquired)) {
+            throw new ReplayLedgerLockError("replay lock reclaim ownership changed before release");
+        }
+        unlinkSync(this.path);
+        fsyncDirectory(dirname(this.path));
+    }
+    release(acquired) {
+        this.beforeRelease?.();
+        this.releaseOwned(acquired);
+    }
+    run(operation) {
+        const acquired = this.acquire(createLockOwner(this.processIdentity));
+        let result;
+        try {
+            result = operation();
+        }
+        catch (error) {
+            this.release(acquired);
+            throw error;
+        }
+        if (result !== null &&
+            (typeof result === "object" || typeof result === "function") &&
+            "then" in result &&
+            typeof result.then === "function") {
+            return Promise.resolve(result).finally(() => this.release(acquired));
+        }
+        this.release(acquired);
+        return result;
+    }
+}
+//# sourceMappingURL=replay-ledger-mutation-gate.js.map

package/dist/guardrails/replay-ledger-mutation-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-ledger-mutation-gate.js","sourceRoot":"","sources":["../../src/guardrails/replay-ledger-mutation-gate.ts"],"names":[],"mappings":"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","sourcesContent":["import { linkSync, readdirSync, unlinkSync } from \"node:fs\";\nimport { basename, dirname, join } from \"node:path\";\nimport { createLockCandidate, fsyncDirectory, removeLockCandidate } from \"./replay-ledger-io.ts\";\nimport {\n\tcreateLockOwner,\n\terrorCode,\n\tinspectProcessIdentity,\n\ttype LockOwner,\n\ttype LockOwnerSnapshot,\n\tlockOwnerIsDead,\n\tlockOwnersEqual,\n\tReplayLedgerLockError,\n\ttype ReplayLedgerProcessIdentityReader,\n\treadLockOwner,\n} from \"./replay-ledger-lock-owner.ts\";\n\nconst GATE_ATTEMPTS = 200;\nconst GATE_WAIT_MS = 5;\nconst sleeper = new Int32Array(new SharedArrayBuffer(4));\n\nexport interface ReplayLedgerMutationGateOptions {\n\treadonly processIdentity?: ReplayLedgerProcessIdentityReader;\n\treadonly beforeReclaimRemove?: () => void;\n\treadonly beforeRelease?: () => void;\n}\n\nexport class ReplayLedgerMutationGate {\n\tprivate readonly path: string;\n\tprivate readonly processIdentity: ReplayLedgerProcessIdentityReader;\n\tprivate readonly beforeReclaimRemove: (() => void) | undefined;\n\tprivate readonly beforeRelease: (() => void) | undefined;\n\n\tconstructor(path: string, options: ReplayLedgerMutationGateOptions = {}) {\n\t\tthis.path = path;\n\t\tthis.processIdentity = options.processIdentity ?? inspectProcessIdentity;\n\t\tthis.beforeReclaimRemove = options.beforeReclaimRemove;\n\t\tthis.beforeRelease = options.beforeRelease;\n\t}\n\n\tprivate intentPaths(): string[] {\n\t\tconst directory = dirname(this.path);\n\t\tconst prefix = `${basename(this.path)}.intent.`;\n\t\treturn readdirSync(directory)\n\t\t\t.filter((name) => name.startsWith(prefix))\n\t\t\t.map((name) => join(directory, name));\n\t}\n\n\tprivate hasLiveIntent(): boolean {\n\t\tconst prefix = `${this.path}.intent.`;\n\t\tfor (const path of this.intentPaths()) {\n\t\t\tlet observed: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tobserved = readLockOwner(path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") continue;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (path.slice(prefix.length) !== observed.owner.ownerId) {\n\t\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim intent owner is invalid\");\n\t\t\t}\n\t\t\tif (!lockOwnerIsDead(observed.owner, this.processIdentity)) return true;\n\t\t\tlet current: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tcurrent = readLockOwner(path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") continue;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (!lockOwnersEqual(current, observed) || !lockOwnerIsDead(current.owner, this.processIdentity)) return true;\n\t\t\tremoveLockCandidate(path);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t}\n\t\treturn false;\n\t}\n\n\tprivate withIntent<T>(candidate: string, owner: LockOwner, operation: () => T): T {\n\t\tconst intent = `${this.path}.intent.${owner.ownerId}`;\n\t\tlinkSync(candidate, intent);\n\t\tfsyncDirectory(dirname(this.path));\n\t\ttry {\n\t\t\treturn operation();\n\t\t} finally {\n\t\t\tremoveLockCandidate(intent);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t}\n\t}\n\n\tprivate abandon(acquired: LockOwnerSnapshot): void {\n\t\ttry {\n\t\t\tconst current = readLockOwner(this.path);\n\t\t\tif (lockOwnersEqual(current, acquired)) unlinkSync(this.path);\n\t\t} catch {\n\t\t\t// Preserve the original acquisition error; a mismatched owner must remain.\n\t\t}\n\t}\n\n\tprivate tryAcquire(candidate: string, expected: LockOwnerSnapshot): LockOwnerSnapshot | undefined {\n\t\tif (this.hasLiveIntent()) return undefined;\n\t\tlet linked = false;\n\t\ttry {\n\t\t\tlinkSync(candidate, this.path);\n\t\t\tlinked = true;\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t\tconst acquired = readLockOwner(this.path);\n\t\t\tif (!lockOwnersEqual(acquired, expected)) {\n\t\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim ownership changed during acquisition\");\n\t\t\t}\n\t\t\tif (!this.hasLiveIntent()) return acquired;\n\t\t\tthis.releaseOwned(acquired);\n\t\t\treturn undefined;\n\t\t} catch (error) {\n\t\t\tif (errorCode(error) === \"EEXIST\") return undefined;\n\t\t\tif (linked) this.abandon(expected);\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tprivate reclaim(candidate: string, owner: LockOwner, observed: LockOwnerSnapshot): void {\n\t\tthis.withIntent(candidate, owner, () => {\n\t\t\tlet current: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tcurrent = readLockOwner(this.path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") return;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (!lockOwnersEqual(current, observed) || !lockOwnerIsDead(current.owner, this.processIdentity)) return;\n\t\t\tthis.beforeReclaimRemove?.();\n\t\t\tlet finalOwner: LockOwnerSnapshot;\n\t\t\ttry {\n\t\t\t\tfinalOwner = readLockOwner(this.path);\n\t\t\t} catch (error) {\n\t\t\t\tif (errorCode(error) === \"ENOENT\") return;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (!lockOwnersEqual(finalOwner, observed) || !lockOwnerIsDead(finalOwner.owner, this.processIdentity)) return;\n\t\t\tremoveLockCandidate(this.path);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t});\n\t}\n\n\tprivate acquire(owner: LockOwner): LockOwnerSnapshot {\n\t\tconst candidate = createLockCandidate(this.path, owner);\n\t\ttry {\n\t\t\tconst expected = readLockOwner(candidate);\n\t\t\tfor (let attempt = 0; attempt < GATE_ATTEMPTS; attempt++) {\n\t\t\t\tconst acquired = this.tryAcquire(candidate, expected);\n\t\t\t\tif (acquired !== undefined) return acquired;\n\t\t\t\tlet current: LockOwnerSnapshot;\n\t\t\t\ttry {\n\t\t\t\t\tcurrent = readLockOwner(this.path);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (errorCode(error) === \"ENOENT\") continue;\n\t\t\t\t\tthrow error;\n\t\t\t\t}\n\t\t\t\tif (lockOwnerIsDead(current.owner, this.processIdentity)) {\n\t\t\t\t\tthis.reclaim(candidate, owner, current);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tAtomics.wait(sleeper, 0, 0, GATE_WAIT_MS);\n\t\t\t}\n\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim serialization is unavailable\");\n\t\t} finally {\n\t\t\tremoveLockCandidate(candidate);\n\t\t}\n\t}\n\n\tprivate releaseOwned(acquired: LockOwnerSnapshot): void {\n\t\tlet current: LockOwnerSnapshot;\n\t\ttry {\n\t\t\tcurrent = readLockOwner(this.path);\n\t\t} catch (error) {\n\t\t\tif (errorCode(error) === \"ENOENT\") {\n\t\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim ownership changed before release\");\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t\tif (!lockOwnersEqual(current, acquired)) {\n\t\t\tthrow new ReplayLedgerLockError(\"replay lock reclaim ownership changed before release\");\n\t\t}\n\t\tunlinkSync(this.path);\n\t\tfsyncDirectory(dirname(this.path));\n\t}\n\n\tprivate release(acquired: LockOwnerSnapshot): void {\n\t\tthis.beforeRelease?.();\n\t\tthis.releaseOwned(acquired);\n\t}\n\n\trun<T>(operation: () => T): T {\n\t\tconst acquired = this.acquire(createLockOwner(this.processIdentity));\n\t\tlet result: T;\n\t\ttry {\n\t\t\tresult = operation();\n\t\t} catch (error) {\n\t\t\tthis.release(acquired);\n\t\t\tthrow error;\n\t\t}\n\t\tif (\n\t\t\tresult !== null &&\n\t\t\t(typeof result === \"object\" || typeof result === \"function\") &&\n\t\t\t\"then\" in result &&\n\t\t\ttypeof result.then === \"function\"\n\t\t) {\n\t\t\treturn Promise.resolve(result).finally(() => this.release(acquired)) as T;\n\t\t}\n\t\tthis.release(acquired);\n\t\treturn result;\n\t}\n}\n"]}

package/dist/guardrails/replay-ledger-quarantine.d.ts

@@ -0,0 +1,2 @@
+export declare function quarantineReplayLedgerSuffix(ledgerPath: string, suffix: Buffer, beforeFsync?: () => void): string;
+//# sourceMappingURL=replay-ledger-quarantine.d.ts.map

package/dist/guardrails/replay-ledger-quarantine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-ledger-quarantine.d.ts","sourceRoot":"","sources":["../../src/guardrails/replay-ledger-quarantine.ts"],"names":[],"mappings":"AAKA,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,IAAI,GAAG,MAAM,CAYjH","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { closeSync, constants as fsConstants, fsyncSync, openSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { fsyncDirectory, writeAll } from \"./replay-ledger-lock.ts\";\n\nexport function quarantineReplayLedgerSuffix(ledgerPath: string, suffix: Buffer, beforeFsync?: () => void): string {\n\tconst artifactPath = `${ledgerPath}.quarantine.${randomUUID()}`;\n\tconst fd = openSync(artifactPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);\n\ttry {\n\t\twriteAll(fd, suffix);\n\t\tbeforeFsync?.();\n\t\tfsyncSync(fd);\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\tfsyncDirectory(dirname(ledgerPath));\n\treturn artifactPath;\n}\n"]}

package/dist/guardrails/replay-ledger-quarantine.js

@@ -0,0 +1,19 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants as fsConstants, fsyncSync, openSync } from "node:fs";
+import { dirname } from "node:path";
+import { fsyncDirectory, writeAll } from "./replay-ledger-lock.js";
+export function quarantineReplayLedgerSuffix(ledgerPath, suffix, beforeFsync) {
+    const artifactPath = `${ledgerPath}.quarantine.${randomUUID()}`;
+    const fd = openSync(artifactPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
+    try {
+        writeAll(fd, suffix);
+        beforeFsync?.();
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    fsyncDirectory(dirname(ledgerPath));
+    return artifactPath;
+}
+//# sourceMappingURL=replay-ledger-quarantine.js.map

package/dist/guardrails/replay-ledger-quarantine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-ledger-quarantine.js","sourceRoot":"","sources":["../../src/guardrails/replay-ledger-quarantine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,SAAS,IAAI,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnE,MAAM,UAAU,4BAA4B,CAAC,UAAkB,EAAE,MAAc,EAAE,WAAwB,EAAU;IAClH,MAAM,YAAY,GAAG,GAAG,UAAU,eAAe,UAAU,EAAE,EAAE,CAAC;IAChE,MAAM,EAAE,GAAG,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,MAAM,GAAG,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC1G,IAAI,CAAC;QACJ,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACrB,WAAW,EAAE,EAAE,CAAC;QAChB,SAAS,CAAC,EAAE,CAAC,CAAC;IACf,CAAC;YAAS,CAAC;QACV,SAAS,CAAC,EAAE,CAAC,CAAC;IACf,CAAC;IACD,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IACpC,OAAO,YAAY,CAAC;AAAA,CACpB","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { closeSync, constants as fsConstants, fsyncSync, openSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { fsyncDirectory, writeAll } from \"./replay-ledger-lock.ts\";\n\nexport function quarantineReplayLedgerSuffix(ledgerPath: string, suffix: Buffer, beforeFsync?: () => void): string {\n\tconst artifactPath = `${ledgerPath}.quarantine.${randomUUID()}`;\n\tconst fd = openSync(artifactPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);\n\ttry {\n\t\twriteAll(fd, suffix);\n\t\tbeforeFsync?.();\n\t\tfsyncSync(fd);\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\tfsyncDirectory(dirname(ledgerPath));\n\treturn artifactPath;\n}\n"]}

package/dist/guardrails/replay-ledger-store.d.ts

@@ -0,0 +1,32 @@
+import type { ReplayLedgerHead } from "../types/evidence.ts";
+export declare const EMPTY_REPLAY_LEDGER_HEAD: ReplayLedgerHead;
+interface InspectedLedger {
+    readonly lastSeq: number;
+    readonly lastHash: string;
+}
+interface StoreSnapshot {
+    readonly bytes: Buffer;
+    readonly head: ReplayLedgerHead;
+}
+export declare function replayLedgerHeadsEqual(left: ReplayLedgerHead, right: ReplayLedgerHead): boolean;
+export interface ReplayLedgerStoreOptions {
+    readonly afterLedgerFsync?: () => void;
+    readonly beforeQuarantineFsync?: () => void;
+}
+export declare class ReplayLedgerStore {
+    private readonly path;
+    private readonly inspect;
+    private readonly headPath;
+    private readonly lock;
+    private readonly afterLedgerFsync;
+    private readonly beforeQuarantineFsync;
+    constructor(path: string, inspect: (bytes: Buffer) => InspectedLedger, options?: ReplayLedgerStoreOptions);
+    private withLock;
+    private readVerified;
+    private initializeGenesis;
+    private publishHead;
+    load(expectedHead?: ReplayLedgerHead): StoreSnapshot;
+    append(line: Buffer, nextSeq: number, nextHash: string, expectedHead: ReplayLedgerHead): ReplayLedgerHead;
+}
+export {};
+//# sourceMappingURL=replay-ledger-store.d.ts.map

package/dist/guardrails/replay-ledger-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-ledger-store.d.ts","sourceRoot":"","sources":["../../src/guardrails/replay-ledger-store.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAK7D,eAAO,MAAM,wBAAwB,EAAE,gBAKrC,CAAC;AACH,UAAU,eAAe;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AACD,UAAU,aAAa;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CAChC;AASD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAO/F;AA4CD,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC5C;AAED,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA2B;IAC5D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA2B;IAEjE,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,eAAe,EAAE,OAAO,GAAE,wBAA6B,EAQ5G;IAED,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,YAAY;IAmDpB,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,WAAW;IAkBnB,IAAI,CAAC,YAAY,CAAC,EAAE,gBAAgB,GAAG,aAAa,CAQnD;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,gBAAgB,GAAG,gBAAgB,CAoCxG;CACD","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport {\n\tcloseSync,\n\texistsSync,\n\tconstants as fsConstants,\n\tfstatSync,\n\tfsyncSync,\n\tftruncateSync,\n\tmkdirSync,\n\topenSync,\n\treadFileSync,\n\trenameSync,\n\tunlinkSync,\n} from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport type { ReplayLedgerHead } from \"../types/evidence.ts\";\nimport { fsyncDirectory, ReplayLedgerLock, writeAll } from \"./replay-ledger-lock.ts\";\nimport { quarantineReplayLedgerSuffix } from \"./replay-ledger-quarantine.ts\";\n\nconst GENESIS_HASH = \"genesis\";\nexport const EMPTY_REPLAY_LEDGER_HEAD: ReplayLedgerHead = Object.freeze({\n\tfileIdentity: null,\n\tsize: 0,\n\tlastSeq: 0,\n\tlastHash: GENESIS_HASH,\n});\ninterface InspectedLedger {\n\treadonly lastSeq: number;\n\treadonly lastHash: string;\n}\ninterface StoreSnapshot {\n\treadonly bytes: Buffer;\n\treadonly head: ReplayLedgerHead;\n}\nfunction identity(stat: ReturnType<typeof fstatSync>): ReplayLedgerHead[\"fileIdentity\"] {\n\treturn Object.freeze({ dev: String(stat.dev), ino: String(stat.ino) });\n}\n\nfunction sameIdentity(left: ReplayLedgerHead[\"fileIdentity\"], right: ReplayLedgerHead[\"fileIdentity\"]): boolean {\n\treturn left === null ? right === null : right !== null && left.dev === right.dev && left.ino === right.ino;\n}\n\nexport function replayLedgerHeadsEqual(left: ReplayLedgerHead, right: ReplayLedgerHead): boolean {\n\treturn (\n\t\tsameIdentity(left.fileIdentity, right.fileIdentity) &&\n\t\tleft.size === right.size &&\n\t\tleft.lastSeq === right.lastSeq &&\n\t\tleft.lastHash === right.lastHash\n\t);\n}\n\nfunction parseHead(value: unknown): ReplayLedgerHead {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value))\n\t\tthrow new Error(\"replay committed head is invalid\");\n\tconst record = value as Record<string, unknown>;\n\tif (Object.keys(record).sort().join(\",\") !== \"fileIdentity,lastHash,lastSeq,size\") {\n\t\tthrow new Error(\"replay committed head has an invalid key set\");\n\t}\n\tconst rawIdentity = record.fileIdentity;\n\tlet fileIdentity: ReplayLedgerHead[\"fileIdentity\"] = null;\n\tif (rawIdentity !== null) {\n\t\tif (typeof rawIdentity !== \"object\" || Array.isArray(rawIdentity))\n\t\t\tthrow new Error(\"replay file identity is invalid\");\n\t\tconst fields = rawIdentity as Record<string, unknown>;\n\t\tif (\n\t\t\tObject.keys(fields).sort().join(\",\") !== \"dev,ino\" ||\n\t\t\ttypeof fields.dev !== \"string\" ||\n\t\t\ttypeof fields.ino !== \"string\" ||\n\t\t\t!/^\\d+$/.test(fields.dev) ||\n\t\t\t!/^\\d+$/.test(fields.ino)\n\t\t) {\n\t\t\tthrow new Error(\"replay file identity is invalid\");\n\t\t}\n\t\tfileIdentity = Object.freeze({ dev: fields.dev, ino: fields.ino });\n\t}\n\tif (\n\t\t!Number.isSafeInteger(record.size) ||\n\t\t(record.size as number) < 0 ||\n\t\t!Number.isSafeInteger(record.lastSeq) ||\n\t\t(record.lastSeq as number) < 0 ||\n\t\ttypeof record.lastHash !== \"string\" ||\n\t\t(record.lastSeq === 0 ? record.lastHash !== GENESIS_HASH : !/^[0-9a-f]{64}$/.test(record.lastHash))\n\t) {\n\t\tthrow new Error(\"replay committed head fields are invalid\");\n\t}\n\treturn Object.freeze({\n\t\tfileIdentity,\n\t\tsize: record.size as number,\n\t\tlastSeq: record.lastSeq as number,\n\t\tlastHash: record.lastHash,\n\t});\n}\n\nexport interface ReplayLedgerStoreOptions {\n\treadonly afterLedgerFsync?: () => void;\n\treadonly beforeQuarantineFsync?: () => void;\n}\n\nexport class ReplayLedgerStore {\n\tprivate readonly path: string;\n\tprivate readonly inspect: (bytes: Buffer) => InspectedLedger;\n\tprivate readonly headPath: string;\n\tprivate readonly lock: ReplayLedgerLock;\n\tprivate readonly afterLedgerFsync: (() => void) | undefined;\n\tprivate readonly beforeQuarantineFsync: (() => void) | undefined;\n\n\tconstructor(path: string, inspect: (bytes: Buffer) => InspectedLedger, options: ReplayLedgerStoreOptions = {}) {\n\t\tthis.path = path;\n\t\tthis.inspect = inspect;\n\t\tmkdirSync(dirname(path), { recursive: true });\n\t\tthis.headPath = `${path}.head`;\n\t\tthis.lock = new ReplayLedgerLock(`${path}.lock`);\n\t\tthis.afterLedgerFsync = options.afterLedgerFsync;\n\t\tthis.beforeQuarantineFsync = options.beforeQuarantineFsync;\n\t}\n\n\tprivate withLock<T>(operation: () => T): T {\n\t\treturn this.lock.run(operation);\n\t}\n\n\tprivate readVerified(): StoreSnapshot {\n\t\tconst ledgerExists = existsSync(this.path);\n\t\tconst headExists = existsSync(this.headPath);\n\t\tif (!ledgerExists && !headExists) return { bytes: Buffer.alloc(0), head: EMPTY_REPLAY_LEDGER_HEAD };\n\t\tif (ledgerExists && !headExists) {\n\t\t\tconst fd = openSync(this.path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));\n\t\t\ttry {\n\t\t\t\tconst stat = fstatSync(fd);\n\t\t\t\tif (!stat.isFile() || stat.size !== 0) throw new Error(\"replay ledger or committed head suffix is missing\");\n\t\t\t} finally {\n\t\t\t\tcloseSync(fd);\n\t\t\t}\n\t\t\tunlinkSync(this.path);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t\treturn { bytes: Buffer.alloc(0), head: EMPTY_REPLAY_LEDGER_HEAD };\n\t\t}\n\t\tif (!ledgerExists) throw new Error(\"replay ledger or committed head suffix is missing\");\n\t\tconst head = parseHead(JSON.parse(readFileSync(this.headPath, \"utf8\")));\n\t\tconst fd = openSync(this.path, fsConstants.O_RDWR | (fsConstants.O_NOFOLLOW ?? 0));\n\t\ttry {\n\t\t\tconst before = fstatSync(fd);\n\t\t\tconst bytes = readFileSync(fd);\n\t\t\tconst after = fstatSync(fd);\n\t\t\tif (\n\t\t\t\t!before.isFile() ||\n\t\t\t\t!after.isFile() ||\n\t\t\t\t!sameIdentity(identity(before), identity(after)) ||\n\t\t\t\tbefore.size !== after.size ||\n\t\t\t\tafter.size !== bytes.byteLength ||\n\t\t\t\t!sameIdentity(head.fileIdentity, identity(after)) ||\n\t\t\t\thead.size > after.size\n\t\t\t) {\n\t\t\t\tthrow new Error(\"replay ledger tampered: file identity or size does not match its committed head\");\n\t\t\t}\n\t\t\tconst committedBytes = head.size === after.size ? bytes : bytes.subarray(0, head.size);\n\t\t\tconst inspected = this.inspect(committedBytes);\n\t\t\tif (inspected.lastSeq !== head.lastSeq || inspected.lastHash !== head.lastHash) {\n\t\t\t\tthrow new Error(\"replay ledger suffix does not match its committed head\");\n\t\t\t}\n\t\t\tif (head.size < after.size) {\n\t\t\t\tquarantineReplayLedgerSuffix(this.path, bytes.subarray(head.size), this.beforeQuarantineFsync);\n\t\t\t\tftruncateSync(fd, head.size);\n\t\t\t\tfsyncSync(fd);\n\t\t\t\tfsyncDirectory(dirname(this.path));\n\t\t\t}\n\t\t\treturn { bytes: committedBytes, head };\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t}\n\n\tprivate initializeGenesis(): ReplayLedgerHead {\n\t\tconst fd = openSync(this.path, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);\n\t\ttry {\n\t\t\tfsyncSync(fd);\n\t\t\tconst stat = fstatSync(fd);\n\t\t\tconst head = Object.freeze({ ...EMPTY_REPLAY_LEDGER_HEAD, fileIdentity: identity(stat) });\n\t\t\tthis.publishHead(head);\n\t\t\treturn head;\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t}\n\n\tprivate publishHead(head: ReplayLedgerHead): void {\n\t\tconst temp = `${this.headPath}.${randomUUID()}.tmp`;\n\t\tconst fd = openSync(temp, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);\n\t\ttry {\n\t\t\twriteAll(fd, Buffer.from(`${JSON.stringify(head)}\\n`, \"utf8\"));\n\t\t\tfsyncSync(fd);\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t\ttry {\n\t\t\trenameSync(temp, this.headPath);\n\t\t\tfsyncDirectory(dirname(this.path));\n\t\t} catch (error) {\n\t\t\tif (existsSync(temp)) unlinkSync(temp);\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tload(expectedHead?: ReplayLedgerHead): StoreSnapshot {\n\t\treturn this.withLock(() => {\n\t\t\tconst snapshot = this.readVerified();\n\t\t\tif (expectedHead !== undefined && !replayLedgerHeadsEqual(snapshot.head, expectedHead)) {\n\t\t\t\tthrow new Error(\"replay ledger expected-head CAS verification failed\");\n\t\t\t}\n\t\t\treturn snapshot;\n\t\t});\n\t}\n\n\tappend(line: Buffer, nextSeq: number, nextHash: string, expectedHead: ReplayLedgerHead): ReplayLedgerHead {\n\t\treturn this.withLock(() => {\n\t\t\tconst snapshot = this.readVerified();\n\t\t\tif (!replayLedgerHeadsEqual(snapshot.head, expectedHead)) {\n\t\t\t\tthrow new Error(\"replay ledger concurrent append failed expected-head CAS\");\n\t\t\t}\n\t\t\tconst appendHead = snapshot.head.fileIdentity === null ? this.initializeGenesis() : snapshot.head;\n\t\t\tconst fd = openSync(\n\t\t\t\tthis.path,\n\t\t\t\tfsConstants.O_CREAT | fsConstants.O_APPEND | fsConstants.O_WRONLY | (fsConstants.O_NOFOLLOW ?? 0),\n\t\t\t\t0o600,\n\t\t\t);\n\t\t\ttry {\n\t\t\t\tconst before = fstatSync(fd);\n\t\t\t\tif (before.size !== appendHead.size || !sameIdentity(appendHead.fileIdentity, identity(before))) {\n\t\t\t\t\tthrow new Error(\"replay ledger file identity or size changed before CAS append\");\n\t\t\t\t}\n\t\t\t\twriteAll(fd, line);\n\t\t\t\tfsyncSync(fd);\n\t\t\t\tconst after = fstatSync(fd);\n\t\t\t\tif (!sameIdentity(identity(before), identity(after)) || after.size !== appendHead.size + line.byteLength) {\n\t\t\t\t\tthrow new Error(\"replay ledger file changed during CAS append\");\n\t\t\t\t}\n\t\t\t\tconst head = Object.freeze({\n\t\t\t\t\tfileIdentity: identity(after),\n\t\t\t\t\tsize: after.size,\n\t\t\t\t\tlastSeq: nextSeq,\n\t\t\t\t\tlastHash: nextHash,\n\t\t\t\t});\n\t\t\t\tthis.afterLedgerFsync?.();\n\t\t\t\tthis.publishHead(head);\n\t\t\t\treturn head;\n\t\t\t} finally {\n\t\t\t\tcloseSync(fd);\n\t\t\t}\n\t\t});\n\t}\n}\n"]}