@tangle-network/agent-eval 0.133.0 → 0.133.2

package/dist/ledger-core/index.d.ts

@@ -1,2 +1,2 @@
-import { C as AtomicFileLockUnavailable, S as AtomicFileLockOwner, T as tryAcquireAtomicFileLock, _ as withLedgerFileLock, a as LedgerEventBase, b as AtomicFileLockError, c as LedgerLineContext, d as canonicalString, f as hashCanonical, g as tryWithLedgerFileLock, h as appendLedgerLine, i as LedgerEntryOf, l as LedgerProjector, m as LedgerFileContext, n as LedgerAppendResult, o as LedgerHash, p as FileLockResult, r as LedgerChainFields, s as LedgerJournalCodec, t as FileLedgerJournal, u as LedgerReplayResult, v as AtomicFileLock, w as probeAtomicFileLock, x as AtomicFileLockOptions, y as AtomicFileLockAcquisition } from "../index-BAvgST_9.js";
-export { type AtomicFileLock, type AtomicFileLockAcquisition, AtomicFileLockError, type AtomicFileLockOptions, type AtomicFileLockOwner, type AtomicFileLockUnavailable, FileLedgerJournal, type FileLockResult, type LedgerAppendResult, type LedgerChainFields, type LedgerEntryOf, type LedgerEventBase, type LedgerFileContext, type LedgerHash, type LedgerJournalCodec, type LedgerLineContext, type LedgerProjector, type LedgerReplayResult, appendLedgerLine, canonicalString, hashCanonical, probeAtomicFileLock, tryAcquireAtomicFileLock, tryWithLedgerFileLock, withLedgerFileLock };
+import { A as AtomicFileLockOptions, C as LedgerCanonicalizationError, D as AtomicFileLock, E as hashCanonical, M as AtomicFileLockUnavailable, N as probeAtomicFileLock, O as AtomicFileLockAcquisition, P as tryAcquireAtomicFileLock, S as LEDGER_HASH_PATTERN, T as canonicalString, _ as LedgerFileContext, a as LedgerChainFields, b as withLedgerFileLock, c as LedgerJournalCodec, d as LedgerReplayResult, f as LedgerAnchoredEntry, g as FileLockResult, h as verifyEntriesAgainstTrustedHead, i as LedgerAppendResult, j as AtomicFileLockOwner, k as AtomicFileLockError, l as LedgerLineContext, m as trustedHeadPathFor, n as FileLedgerJournalOptions, o as LedgerEntryOf, p as LedgerTrustedHead, r as LedgerAppendOptions, s as LedgerEventBase, t as FileLedgerJournal, u as LedgerProjector, v as appendLedgerLine, w as LedgerHash, x as writeLedgerFileAtomically, y as tryWithLedgerFileLock } from "../index-nhIYz9hn.js";
+export { type AtomicFileLock, type AtomicFileLockAcquisition, AtomicFileLockError, type AtomicFileLockOptions, type AtomicFileLockOwner, type AtomicFileLockUnavailable, FileLedgerJournal, type FileLedgerJournalOptions, type FileLockResult, LEDGER_HASH_PATTERN, type LedgerAnchoredEntry, type LedgerAppendOptions, type LedgerAppendResult, LedgerCanonicalizationError, type LedgerChainFields, type LedgerEntryOf, type LedgerEventBase, type LedgerFileContext, type LedgerHash, type LedgerJournalCodec, type LedgerLineContext, type LedgerProjector, type LedgerReplayResult, type LedgerTrustedHead, appendLedgerLine, canonicalString, hashCanonical, probeAtomicFileLock, trustedHeadPathFor, tryAcquireAtomicFileLock, tryWithLedgerFileLock, verifyEntriesAgainstTrustedHead, withLedgerFileLock, writeLedgerFileAtomically };

package/dist/ledger-core/index.js

@@ -1,2 +1,2 @@
-import { a as tryWithLedgerFileLock, c as probeAtomicFileLock, i as appendLedgerLine, l as tryAcquireAtomicFileLock, n as canonicalString, o as withLedgerFileLock, r as hashCanonical, s as AtomicFileLockError, t as FileLedgerJournal } from "../ledger-core-eqaI3PCD.js";
-export { AtomicFileLockError, FileLedgerJournal, appendLedgerLine, canonicalString, hashCanonical, probeAtomicFileLock, tryAcquireAtomicFileLock, tryWithLedgerFileLock, withLedgerFileLock };
+import { a as tryWithLedgerFileLock, c as LEDGER_HASH_PATTERN, d as hashCanonical, f as AtomicFileLockError, i as appendLedgerLine, l as LedgerCanonicalizationError, m as tryAcquireAtomicFileLock, n as trustedHeadPathFor, o as withLedgerFileLock, p as probeAtomicFileLock, r as verifyEntriesAgainstTrustedHead, s as writeLedgerFileAtomically, t as FileLedgerJournal, u as canonicalString } from "../ledger-core-CPZfcrC2.js";
+export { AtomicFileLockError, FileLedgerJournal, LEDGER_HASH_PATTERN, LedgerCanonicalizationError, appendLedgerLine, canonicalString, hashCanonical, probeAtomicFileLock, trustedHeadPathFor, tryAcquireAtomicFileLock, tryWithLedgerFileLock, verifyEntriesAgainstTrustedHead, withLedgerFileLock, writeLedgerFileAtomically };

package/dist/ledger-core-CPZfcrC2.js

@@ -0,0 +1,620 @@
+import { s as ValidationError } from "./errors-8YnH8WlF.js";
+import { t as Mutex } from "./concurrency-MUjT7VjM.js";
+import { closeSync, constants, existsSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { canonicalCandidateBytes, canonicalCandidateJson, sha256Bytes } from "@tangle-network/agent-interface";
+//#region src/ledger-core/atomic-file-lock.ts
+/** Crash-safe filesystem lock shared by campaign persistence and run exclusion. */
+var AtomicFileLockError = class extends Error {
+	name = "AtomicFileLockError";
+};
+/** Report whether another lock path prevents acquisition without modifying it. */
+function probeAtomicFileLock(options) {
+	if (existsSync(recoveryPath(options.lockPath))) return {
+		acquired: false,
+		reason: "recovery"
+	};
+	const state = ownerState(options.lockPath);
+	if (state.state === "held") return {
+		acquired: false,
+		reason: "held",
+		holder: state.owner
+	};
+	return null;
+}
+/**
+* Try to acquire a complete, uniquely-owned lock inode.
+*
+* A hard link publishes fully-written owner metadata atomically. Stale-owner
+* removal is serialized so one reclaimer cannot delete a new owner's lock.
+*/
+function tryAcquireAtomicFileLock(options) {
+	const pid = options.pid ?? process.pid;
+	if (!Number.isSafeInteger(pid) || pid <= 0) throw new AtomicFileLockError("atomic file lock pid must be a positive integer");
+	const owner = {
+		pid,
+		host: hostname(),
+		nonce: randomUUID()
+	};
+	for (let attempt = 0; attempt < 8; attempt += 1) {
+		if (existsSync(recoveryPath(options.lockPath))) return {
+			acquired: false,
+			reason: "recovery"
+		};
+		if (tryLinkOwner(options.lockPath, owner, `acquire.${attempt}`)) return acquired(options.lockPath, owner);
+		const holder = ownerState(options.lockPath);
+		if (holder.state === "missing") continue;
+		if (holder.state === "held") return {
+			acquired: false,
+			reason: "held",
+			holder: holder.owner
+		};
+		const reclaimPath = recoveryPath(options.lockPath);
+		if (!tryLinkOwner(reclaimPath, owner, `reclaim.${attempt}`)) return {
+			acquired: false,
+			reason: "recovery"
+		};
+		try {
+			const current = ownerState(options.lockPath);
+			if (current.state === "held") return {
+				acquired: false,
+				reason: "held",
+				holder: current.owner
+			};
+			if (current.state === "stale") {
+				const tombstone = `${options.lockPath}.stale.${owner.nonce}.${attempt}`;
+				try {
+					renameSync(options.lockPath, tombstone);
+					unlinkSync(tombstone);
+				} catch (error) {
+					if (!isMissing(error)) throw error;
+				}
+			}
+			if (tryLinkOwner(options.lockPath, owner, `recovered.${attempt}`)) return acquired(options.lockPath, owner);
+		} finally {
+			releaseOwnedPath(reclaimPath, owner);
+		}
+	}
+	throw new AtomicFileLockError(`could not acquire atomic file lock ${options.lockPath}`);
+}
+function acquired(lockPath, owner) {
+	return {
+		acquired: true,
+		lock: {
+			owner,
+			release: () => releaseOwnedPath(lockPath, owner)
+		}
+	};
+}
+function tryLinkOwner(lockPath, owner, suffix) {
+	const ownerPath = `${lockPath}.${owner.pid}.${owner.nonce}.${suffix}.owner`;
+	const descriptor = openSync(ownerPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 384);
+	try {
+		writeFileSync(descriptor, `${canonicalOwner(owner)}\n`, "utf8");
+		fsyncSync(descriptor);
+	} catch (error) {
+		closeSync(descriptor);
+		unlinkIfExists(ownerPath);
+		throw error;
+	}
+	closeSync(descriptor);
+	try {
+		linkSync(ownerPath, lockPath);
+		return true;
+	} catch (error) {
+		if (!isAlreadyExists(error)) throw error;
+		return false;
+	} finally {
+		unlinkIfExists(ownerPath);
+	}
+}
+function ownerState(lockPath) {
+	const owner = readOwner(lockPath);
+	if (!owner) return { state: "missing" };
+	if (owner.host !== hostname()) return {
+		state: "held",
+		owner
+	};
+	try {
+		process.kill(owner.pid, 0);
+		return {
+			state: "held",
+			owner
+		};
+	} catch (error) {
+		if (isNoSuchProcess(error)) return {
+			state: "stale",
+			owner
+		};
+		return {
+			state: "held",
+			owner
+		};
+	}
+}
+function readOwner(lockPath) {
+	let contents;
+	try {
+		contents = readFileSync(lockPath, "utf8").trim();
+	} catch (error) {
+		if (isMissing(error)) return void 0;
+		throw error;
+	}
+	let value;
+	try {
+		value = JSON.parse(contents);
+	} catch (error) {
+		throw invalidOwner(lockPath, error);
+	}
+	if (!isOwner(value)) throw invalidOwner(lockPath);
+	return value;
+}
+function isOwner(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value;
+	return Object.keys(record).length === 3 && Number.isSafeInteger(record.pid) && Number(record.pid) > 0 && typeof record.host === "string" && record.host.trim().length > 0 && typeof record.nonce === "string" && record.nonce.trim().length > 0;
+}
+function invalidOwner(lockPath, cause) {
+	const error = new AtomicFileLockError(`atomic file lock has an invalid owner (${lockPath}); refusing unsafe recovery`);
+	if (cause !== void 0) Object.defineProperty(error, "cause", { value: cause });
+	return error;
+}
+function releaseOwnedPath(lockPath, owner) {
+	const current = readOwner(lockPath);
+	if (!current) return;
+	if (canonicalOwner(current) !== canonicalOwner(owner)) throw new AtomicFileLockError(`atomic file lock owner changed before release (${lockPath})`);
+	try {
+		unlinkSync(lockPath);
+	} catch (error) {
+		if (!isMissing(error)) throw error;
+	}
+}
+function canonicalOwner(owner) {
+	return JSON.stringify({
+		host: owner.host,
+		nonce: owner.nonce,
+		pid: owner.pid
+	});
+}
+function recoveryPath(lockPath) {
+	return `${lockPath}.reclaim`;
+}
+function isAlreadyExists(error) {
+	return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+function isMissing(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isNoSuchProcess(error) {
+	return error instanceof Error && "code" in error && error.code === "ESRCH";
+}
+function unlinkIfExists(path) {
+	try {
+		unlinkSync(path);
+	} catch (error) {
+		if (!isMissing(error)) throw error;
+	}
+}
+//#endregion
+//#region src/ledger-core/canonical.ts
+/**
+* Canonical bytes and digests for durable journal rows.
+*
+* Serialization is RFC 8785 through `@tangle-network/agent-interface` — the
+* stack's single identity scheme — so a value carries the same digest in every
+* package that produces or verifies one.
+*
+* Values canonical JSON cannot represent faithfully are refused, never coerced.
+* `NaN`, `Infinity`, `undefined`, class instances, cycles, and unpaired
+* surrogates each have a lossy encoding that maps distinct records onto one
+* digest, and in a hash chain the digest IS the record's identity: a coercion
+* there is a collision, not a convenience.
+*/
+/** Shape of every ledger digest: `sha256:` followed by 64 lowercase hex chars. */
+const LEDGER_HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+/** A value has no faithful canonical-JSON form, so it cannot be stored or hashed. */
+var LedgerCanonicalizationError = class extends ValidationError {};
+/** Canonical JSON encoding (RFC 8785): object keys sorted by UTF-16 code unit,
+* recursively. This is the byte form that is hashed and stored, so equal values
+* always encode identically. */
+function canonicalString(value) {
+	try {
+		return canonicalCandidateJson(value);
+	} catch (error) {
+		throw canonicalizationError(value, error);
+	}
+}
+function hashCanonical(value) {
+	try {
+		return sha256Bytes(canonicalCandidateBytes(value));
+	} catch (error) {
+		throw canonicalizationError(value, error);
+	}
+}
+/** Name the offending value and path so a refusal is actionable. The RFC 8785
+* encoder above is the sole authority on acceptance; this walk only explains a
+* rejection it already made. */
+function canonicalizationError(value, cause) {
+	const defect = firstNonCanonicalDefect(value, "$", /* @__PURE__ */ new Set());
+	return new LedgerCanonicalizationError(`value has no canonical JSON form: ${defect !== "" ? defect : cause instanceof Error ? cause.message : String(cause)}`, { cause });
+}
+function firstNonCanonicalDefect(value, path, ancestors) {
+	if (value === null) return "";
+	if (value === void 0) return `${path} is undefined`;
+	const type = typeof value;
+	if (type === "number") return Number.isFinite(value) ? "" : `${path} is ${String(value)}`;
+	if (type === "string") return isWellFormedUtf16(value) ? "" : `${path} contains an unpaired surrogate`;
+	if (type === "boolean") return "";
+	if (type !== "object") return `${path} is a ${type}`;
+	const object = value;
+	if (ancestors.has(object)) return `${path} closes a reference cycle`;
+	const prototype = Object.getPrototypeOf(object);
+	if (!Array.isArray(object) && prototype !== Object.prototype && prototype !== null) return `${path} is a ${object.constructor?.name ?? "non-plain"} instance, not plain JSON data`;
+	const nested = new Set(ancestors).add(object);
+	if (Array.isArray(object)) {
+		for (let index = 0; index < object.length; index += 1) {
+			const defect = firstNonCanonicalDefect(object[index], `${path}[${index}]`, nested);
+			if (defect !== "") return defect;
+		}
+		return "";
+	}
+	for (const [key, entry] of Object.entries(object)) {
+		if (!isWellFormedUtf16(key)) return `${path}.${key} has a key with an unpaired surrogate`;
+		const defect = firstNonCanonicalDefect(entry, `${path}.${key}`, nested);
+		if (defect !== "") return defect;
+	}
+	return "";
+}
+function isWellFormedUtf16(value) {
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code >= 55296 && code <= 56319) {
+			const next = value.charCodeAt(index + 1);
+			if (!(next >= 56320 && next <= 57343)) return false;
+			index += 1;
+		} else if (code >= 56320 && code <= 57343) return false;
+	}
+	return true;
+}
+//#endregion
+//#region src/ledger-core/journal-file.ts
+/** Filesystem durability and cross-process exclusion for append-only journal files. */
+/** Append one already-serialized line; the write is fsynced (file and directory)
+* before returning so an acknowledged append survives a crash. */
+function appendLedgerLine(path, line, context) {
+	mkdirSync(dirname(path), { recursive: true });
+	const fd = openSync(path, constants.O_CREAT | constants.O_WRONLY | constants.O_APPEND, 384);
+	try {
+		writeAll(fd, Buffer.from(line, "utf8"), context);
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	fsyncDirectory(dirname(path));
+}
+/** Replace a small sidecar file whole: write a temporary sibling, fsync it,
+* then rename over the target. A reader therefore sees the previous contents
+* or the new ones, never a partial file. */
+function writeLedgerFileAtomically(path, contents, context) {
+	const directory = dirname(path);
+	mkdirSync(directory, { recursive: true });
+	const temporaryPath = `${path}.tmp`;
+	const fd = openSync(temporaryPath, constants.O_CREAT | constants.O_WRONLY | constants.O_TRUNC, 384);
+	try {
+		writeAll(fd, Buffer.from(contents, "utf8"), context);
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	renameSync(temporaryPath, path);
+	fsyncDirectory(directory);
+}
+function withLedgerFileLock(path, context, run) {
+	const result = tryWithLedgerFileLock(path, context, run);
+	if (!result.acquired) throw context.integrityError(`${context.subject} lock is held (${path})`);
+	return result.value;
+}
+function tryWithLedgerFileLock(path, context, run) {
+	mkdirSync(dirname(path), { recursive: true });
+	const lockPath = `${path}.lock`;
+	try {
+		const acquisition = tryAcquireAtomicFileLock({ lockPath });
+		if (!acquisition.acquired) return { acquired: false };
+		try {
+			return {
+				acquired: true,
+				value: run()
+			};
+		} finally {
+			acquisition.lock.release();
+		}
+	} catch (error) {
+		if (error instanceof AtomicFileLockError) throw context.integrityError(error.message, { cause: error });
+		throw error;
+	}
+}
+function writeAll(fd, bytes, context) {
+	let offset = 0;
+	while (offset < bytes.byteLength) {
+		const written = writeSync(fd, bytes, offset, bytes.byteLength - offset);
+		if (written <= 0) throw context.integrityError("filesystem wrote zero bytes");
+		offset += written;
+	}
+}
+function fsyncDirectory(path) {
+	const fd = openSync(path, constants.O_RDONLY);
+	try {
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+}
+//#endregion
+//#region src/ledger-core/trusted-head.ts
+/**
+* Trusted head — the pin that makes deletion detectable.
+*
+* ## What the chain binds
+*
+* Every entry hashes the journal header, its sequence, the previous entry's
+* hash, and its event, so editing, reordering, or removing an entry in the
+* middle of a journal invalidates every hash after it. What a hash chain
+* cannot bind is its own length. Dropping entries off the END leaves a shorter
+* journal that is internally perfect, and rebuilding a journal from sequence 0
+* with recomputed hashes produces a different, equally perfect chain. For an
+* audit log of candidate registrations and promotion decisions that is the
+* difference between a record of a search that happened and a record of one
+* that did not.
+*
+* ## What the pin binds
+*
+* `<journal>.head` holds `{sequence, entryHash}` for one entry a writer
+* actually appended, in a file separate from the journal it attests. Each
+* entry hash commits to the entire prefix before it, so checking that the
+* entry at exactly `sequence` still carries `entryHash` proves two things at
+* once: the journal is at least `sequence + 1` entries long, and those entries
+* are byte-for-byte the ones the writer saw. A journal that merely grew past
+* the pin still verifies; a truncated, rolled-back, or wholesale-rewritten one
+* cannot.
+*
+* ## What the pin does NOT defend against
+*
+* The pin is a second file, not a signature. A writer with access to BOTH the
+* journal and its pin can rewrite both consistently, and the result verifies.
+* Pinning raises the cost of undetected tampering from one file to two and
+* nothing more; defending against a writer who holds both requires an anchor
+* outside this store entirely — a signed head, or a digest published to an
+* append-only service the tamperer does not control.
+*
+* Deleting the pin file downgrades a pinned journal to an unpinned one, which
+* cannot be distinguished from a journal written before pinning existed. That
+* is what `requireTrustedHead` is for: a journal opened under it refuses to
+* read at all once a non-empty journal has no pin.
+*/
+/** Sibling pin file for a journal — deliberately NOT the journal, so rewriting
+* the log is not enough to rewrite the trust recorded about it. */
+function trustedHeadPathFor(journalPath) {
+	return `${journalPath}.head`;
+}
+/** The pin, or null when this journal has never been pinned. A pin that exists
+* but does not parse is corruption or tamper of the trust record itself and
+* fails loudly: reporting it as "no pin" would silently downgrade what the
+* journal can prove. */
+function readTrustedHeadFile(path, context) {
+	if (!existsSync(path)) return null;
+	const text = readFileSync(path, "utf8");
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch (error) {
+		throw context.integrityError(`${context.subject} trusted head ${path} is not valid JSON`, { cause: error });
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw context.integrityError(`${context.subject} trusted head ${path} is not an object`);
+	const record = raw;
+	const keys = Object.keys(record).sort();
+	if (keys.length !== 2 || keys[0] !== "entryHash" || keys[1] !== "sequence") throw context.integrityError(`${context.subject} trusted head ${path} has keys [${keys.join(", ")}], expected [entryHash, sequence]`);
+	const { sequence, entryHash } = record;
+	if (typeof sequence !== "number" || !Number.isSafeInteger(sequence) || sequence < 0) throw context.integrityError(`${context.subject} trusted head ${path} sequence is not a non-negative integer`);
+	if (typeof entryHash !== "string" || !LEDGER_HASH_PATTERN.test(entryHash)) throw context.integrityError(`${context.subject} trusted head ${path} entryHash is not a sha256 digest`);
+	return {
+		sequence,
+		entryHash
+	};
+}
+/** Publish a pin by write-then-rename, so a crash leaves either the previous
+* pin or the new one and never a torn file that would lock a journal out of
+* its own trust record. */
+function writeTrustedHeadFile(path, head, context) {
+	writeLedgerFileAtomically(path, `${canonicalString(head)}\n`, context);
+}
+/** The entry at exactly `head.sequence` must still carry `head.entryHash`.
+* Entries must already have passed chain verification, which is what makes
+* index and sequence interchangeable here. */
+function verifyEntriesAgainstTrustedHead(entries, head, context, subject) {
+	const pinned = entries[head.sequence];
+	if (pinned === void 0) throw context.integrityError(`${subject} trusted head pins sequence ${head.sequence} (${head.entryHash}) but the journal has ${entries.length} entries — pinned history is missing (truncation, rollback, or rewrite)`);
+	if (pinned.sequence !== head.sequence) throw context.integrityError(`${subject} entry at index ${head.sequence} carries sequence ${pinned.sequence}; the chain was not verified before the trusted head`);
+	if (pinned.entryHash !== head.entryHash) throw context.integrityError(`${subject} entry at pinned sequence ${head.sequence} carries ${pinned.entryHash} but the trusted head recorded ${head.entryHash} — the journal was rewritten`);
+}
+//#endregion
+//#region src/ledger-core/journal.ts
+/**
+* Generic durable append-only journal with a SHA-256 hash chain.
+*
+* The file format is canonical JSONL: every row is the canonical JSON encoding
+* (RFC 8785, object keys sorted recursively) of one entry, and every entry
+* hashes the previous entry's hash so the log is tamper-evident. Appends are
+* serialized in-process per path and across processes via a lock file, fsynced
+* before acknowledgement, and idempotent by `eventId`. A malformed,
+* non-canonical, truncated, reordered, or conflicting log fails loudly; a bad
+* row is never skipped.
+*
+* A hash chain binds each entry to its predecessor, which cannot prove that no
+* entry was removed from the end: a valid shorter prefix is still a valid
+* chain. `pinHead` records the appended entry in a sibling `<journal>.head`
+* file and every read re-verifies the journal against a pin that is present,
+* so truncation and wholesale rewrite are refused. `trusted-head.ts` carries
+* the full threat model, including what a pin does not defend against.
+*
+* Domain vocabulary lives entirely in the consumer's codec: entry schema
+* validation, the constant header fields stamped into every entry, the error
+* taxonomy, and the state machine replayed over verified entries.
+*/
+const journalMutexes = /* @__PURE__ */ new Map();
+function mutexFor(path) {
+	const existing = journalMutexes.get(path);
+	if (existing) return existing;
+	const mutex = new Mutex();
+	journalMutexes.set(path, mutex);
+	return mutex;
+}
+/** Durable filesystem journal. Construction performs no I/O; `append` and
+* `replay` validate the complete existing file under the locks. */
+var FileLedgerJournal = class {
+	path;
+	/** Sibling file holding this journal's trusted head. */
+	trustedHeadPath;
+	codec;
+	mutex;
+	requireTrustedHead;
+	constructor(path, codec, options = {}) {
+		this.path = resolve(path);
+		this.trustedHeadPath = trustedHeadPathFor(this.path);
+		this.codec = codec;
+		this.mutex = mutexFor(this.path);
+		this.requireTrustedHead = options.requireTrustedHead === true;
+	}
+	async replay() {
+		return this.mutex.runExclusive(() => withLedgerFileLock(this.path, this.codec, () => this.replayLocked()));
+	}
+	async append(event, options = {}) {
+		return this.mutex.runExclusive(() => withLedgerFileLock(this.path, this.codec, () => {
+			const before = this.replayLocked();
+			const existing = before.entries.find((entry) => entry.event.eventId === event.eventId);
+			if (existing) {
+				if (canonicalString(existing.event) !== canonicalString(event)) throw this.codec.conflictError(`eventId ${event.eventId} already exists with different content`);
+				return {
+					entry: existing,
+					appended: false,
+					projection: before.projection
+				};
+			}
+			const material = {
+				...this.codec.header,
+				sequence: before.entries.length,
+				previousHash: before.entries.at(-1)?.entryHash ?? null,
+				event
+			};
+			const entry = {
+				...material,
+				entryHash: hashCanonical(material)
+			};
+			const projection = this.project([...before.entries, entry]);
+			appendLedgerLine(this.path, `${canonicalString(entry)}\n`, this.codec);
+			if (options.pinHead === true) writeTrustedHeadFile(this.trustedHeadPath, {
+				sequence: entry.sequence,
+				entryHash: entry.entryHash
+			}, this.codec);
+			return {
+				entry,
+				appended: true,
+				projection
+			};
+		}));
+	}
+	/** The pinned head, or null when this journal has never been pinned. */
+	async trustedHead() {
+		return this.mutex.runExclusive(() => withLedgerFileLock(this.path, this.codec, () => readTrustedHeadFile(this.trustedHeadPath, this.codec)));
+	}
+	/** Pin the current verified head. The chain and any existing pin are checked
+	* first, so the pin only ever moves forward along a journal that still
+	* carries the history it already recorded. */
+	async pinTrustedHead() {
+		return this.mutex.runExclusive(() => withLedgerFileLock(this.path, this.codec, () => {
+			const entries = this.readEntries();
+			this.project(entries);
+			this.verifyTrustedHead(entries, false);
+			const last = entries.at(-1);
+			if (last === void 0) throw this.codec.integrityError(`${this.codec.subject} ${this.path} is empty; there is no head to pin`);
+			const head = {
+				sequence: last.sequence,
+				entryHash: last.entryHash
+			};
+			writeTrustedHeadFile(this.trustedHeadPath, head, this.codec);
+			return head;
+		}));
+	}
+	replayLocked() {
+		const entries = this.readEntries();
+		const projection = this.project(entries);
+		this.verifyTrustedHead(entries, this.requireTrustedHead);
+		return {
+			entries,
+			projection
+		};
+	}
+	verifyTrustedHead(entries, requirePin) {
+		const pinned = readTrustedHeadFile(this.trustedHeadPath, this.codec);
+		if (pinned === null) {
+			if (requirePin && entries.length > 0) throw this.codec.integrityError(`${this.codec.subject} ${this.path} has ${entries.length} entries but no trusted head at ${this.trustedHeadPath} — without its pin the journal cannot prove nothing was deleted`);
+			return;
+		}
+		verifyEntriesAgainstTrustedHead(entries, pinned, this.codec, `${this.codec.subject} ${this.path}`);
+	}
+	readEntries() {
+		if (!existsSync(this.path)) return [];
+		const text = readFileSync(this.path, "utf8");
+		if (text.length === 0) return [];
+		if (!text.endsWith("\n")) throw this.codec.integrityError(`${this.codec.subject} ${this.path} has a truncated final record (missing newline)`);
+		const lines = text.slice(0, -1).split("\n");
+		const entries = [];
+		for (let index = 0; index < lines.length; index += 1) {
+			const line = lines[index];
+			if (line.length === 0) throw this.codec.integrityError(`${this.codec.subject} ${this.path} has a blank row at line ${index + 1}`);
+			let raw;
+			try {
+				raw = JSON.parse(line);
+			} catch (error) {
+				throw this.codec.integrityError(`${this.codec.subject} ${this.path} has invalid JSON at line ${index + 1}`, { cause: error });
+			}
+			const entry = this.codec.parseEntry(raw, {
+				path: this.path,
+				line: index + 1
+			});
+			let canonical;
+			try {
+				canonical = canonicalString(entry);
+			} catch (error) {
+				throw this.codec.integrityError(`${this.codec.subject} ${this.path} has a row with no canonical JSON form at line ${index + 1}`, { cause: error });
+			}
+			if (line !== canonical) throw this.codec.integrityError(`${this.codec.subject} ${this.path} has non-canonical bytes at line ${index + 1}`);
+			entries.push(entry);
+		}
+		return entries;
+	}
+	project(entries) {
+		const projector = this.codec.createProjector();
+		const eventIds = /* @__PURE__ */ new Set();
+		let expectedPrevious = null;
+		for (let index = 0; index < entries.length; index += 1) {
+			const entry = entries[index];
+			this.codec.checkEntryHeader(entry, index);
+			if (entry.sequence !== index) throw this.codec.integrityError(`entry ${entry.event.eventId} has sequence ${entry.sequence}, expected ${index}`);
+			if (entry.previousHash !== expectedPrevious) throw this.codec.integrityError(`entry ${entry.event.eventId} does not extend the previous hash`);
+			const { entryHash: _entryHash, ...material } = entry;
+			const expectedHash = hashCanonical(material);
+			if (entry.entryHash !== expectedHash) throw this.codec.integrityError(`entry ${entry.event.eventId} hash mismatch: expected ${expectedHash}, got ${entry.entryHash}`);
+			expectedPrevious = entry.entryHash;
+			if (eventIds.has(entry.event.eventId)) throw this.codec.integrityError(`duplicate eventId ${entry.event.eventId} in durable ledger`);
+			eventIds.add(entry.event.eventId);
+			projector.apply(entry, index);
+		}
+		return projector.finish(entries);
+	}
+};
+//#endregion
+export { tryWithLedgerFileLock as a, LEDGER_HASH_PATTERN as c, hashCanonical as d, AtomicFileLockError as f, appendLedgerLine as i, LedgerCanonicalizationError as l, tryAcquireAtomicFileLock as m, trustedHeadPathFor as n, withLedgerFileLock as o, probeAtomicFileLock as p, verifyEntriesAgainstTrustedHead as r, writeLedgerFileAtomically as s, FileLedgerJournal as t, canonicalString as u };
+
+//# sourceMappingURL=ledger-core-CPZfcrC2.js.map