@tangle-network/agent-eval 0.187.2 → 0.189.0

package/dist/{journal-BuRLm6ho.js → journal-CDP0Vhx_.js}

@@ -1,4 +1,5 @@
 import { a as hashCanonical, r as canonicalString, t as LEDGER_HASH_PATTERN } from "./canonical-BsZVgBhW.js";
+import { t as deepFreezeCanonicalJson } from "./deep-freeze-CurcOQg3.js";
 import { randomUUID } from "node:crypto";
 import { closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -623,11 +624,13 @@ function clearTrustedHeadFile(path, 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. */
+* index and sequence interchangeable here. An array serves as `entries`; a
+* journal that keeps no entries in memory passes a reader with the same
+* `length` and `at`. */
 function verifyEntriesAgainstTrustedHead(entries, head, context, naming) {
 	if (typeof naming !== "object" || naming === null) throw new TypeError("verifyEntriesAgainstTrustedHead expects { subject, trustedHeadPath } as its fourth argument");
 	const { subject, trustedHeadPath } = naming;
-	const pinned = entries[head.sequence];
+	const pinned = entries.at(head.sequence);
 	if (pinned === void 0) throw context.integrityError(`${subject} trusted head ${trustedHeadPath} pins sequence ${head.sequence} (${head.entryHash}) but the journal has ${entries.length} entries — pinned history is missing (truncation, rollback, or rewrite). Restore the journal, or abandon the pinned history on purpose with clearTrustedHead().`);
 	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 ${trustedHeadPath}`);
 	if (pinned.entryHash !== head.entryHash) throw context.integrityError(`${subject} entry at pinned sequence ${head.sequence} carries ${pinned.entryHash} but the trusted head ${trustedHeadPath} recorded ${head.entryHash} — the journal was rewritten. Restore the journal, or abandon the pinned history on purpose with clearTrustedHead().`);
@@ -652,6 +655,16 @@ function verifyEntriesAgainstTrustedHead(entries, head, context, naming) {
 * so truncation and wholesale rewrite are refused. `trusted-head.ts` carries
 * the full threat model, including what a pin does not defend against.
 *
+* Verification is incremental. A journal instance verifies its whole file once,
+* on its first call, and keeps the verified head, the live projector, and an
+* eventId index. Every later call checks that the head line it verified is
+* still in place, then reads, verifies, and projects only the bytes past it, so
+* an append reads one entry however long the journal is. Rows another writer
+* appended are verified as that tail. A file that was replaced, shrank, or no
+* longer carries the verified head is verified whole again. What an open
+* instance cannot see is a same-length rewrite of rows before its head; a new
+* instance verifies every row and refuses one.
+*
 * 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.
@@ -664,8 +677,9 @@ function mutexFor(path) {
 	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. */
+/** Durable filesystem journal. Construction performs no I/O. The first call
+* verifies the complete file under the locks; later calls verify the retained
+* head and only the bytes past it (see the module comment). */
 var FileLedgerJournal = class {
 	path;
 	/** Sibling file holding this journal's trusted head. */
@@ -673,6 +687,7 @@ var FileLedgerJournal = class {
 	codec;
 	mutex;
 	requireTrustedHead;
+	verified = null;
 	constructor(path, codec, options = {}) {
 		this.path = resolve(path);
 		this.trustedHeadPath = trustedHeadPathFor(this.path);
@@ -681,43 +696,53 @@ var FileLedgerJournal = class {
 		this.requireTrustedHead = options.requireTrustedHead === true;
 	}
 	async replay() {
-		return this.mutex.runExclusive(() => withLedgerFileLock(this.path, this.codec, () => this.replayLocked()));
+		return this.locked(() => this.sync(this.requireTrustedHead).projector.snapshot());
 	}
 	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) {
+		return this.locked(() => {
+			const state = this.sync(this.requireTrustedHead);
+			const existingSequence = state.sequenceByEventId.get(event.eventId);
+			if (existingSequence !== void 0) {
+				const existing = this.entryAt(state, existingSequence);
 				if (canonicalString(existing.event) !== canonicalString(event)) throw this.codec.conflictError(`eventId ${event.eventId} already exists with different content`);
-				if (options.pinHead === true) this.pinAcknowledged(existing, before.entries);
+				if (options.pinHead === true) this.pinAcknowledged(state, existing);
 				return {
 					entry: existing,
 					appended: false,
-					projection: before.projection
+					projection: state.projector.snapshot()
 				};
 			}
+			const sequence = state.offsets.length;
 			const material = {
 				...this.codec.header,
-				sequence: before.entries.length,
-				previousHash: before.entries.at(-1)?.entryHash ?? null,
+				sequence,
+				previousHash: state.head?.entry.entryHash ?? null,
 				event
 			};
-			const entry = {
+			const text = canonicalString({
 				...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
+			});
+			const entry = parseRow(text, {
+				path: this.path,
+				line: sequence + 1
 			}, this.codec);
+			admitEntry(state, entry, Buffer.from(`${text}\n`, "utf8"), this.codec);
+			appendLedgerLine(this.path, `${text}\n`, this.codec);
+			if (options.pinHead === true) {
+				const head = {
+					sequence: entry.sequence,
+					entryHash: entry.entryHash
+				};
+				writeTrustedHeadFile(this.trustedHeadPath, head, this.codec);
+				state.pin = head;
+			}
 			return {
 				entry,
 				appended: true,
-				projection
+				projection: state.projector.snapshot()
 			};
-		}));
+		});
 	}
 	/** The pinned head, or null when this journal has never been pinned. */
 	async trustedHead() {
@@ -727,19 +752,17 @@ var FileLedgerJournal = class {
 	* 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`);
+		return this.locked(() => {
+			const state = this.sync(false);
+			if (state.head === null) 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
+				sequence: state.head.entry.sequence,
+				entryHash: state.head.entry.entryHash
 			};
 			writeTrustedHeadFile(this.trustedHeadPath, head, this.codec);
+			state.pin = head;
 			return head;
-		}));
+		});
 	}
 	/** Discard this journal's pin, reporting what was discarded. The journal file
 	* is untouched and reads as unpinned afterwards, so the next pinning append
@@ -749,115 +772,239 @@ var FileLedgerJournal = class {
 	* is indistinguishable from a deletion. Clearing removes the deletion
 	* guarantee for every entry the pin covered. */
 	async clearTrustedHead() {
-		return this.mutex.runExclusive(() => withLedgerFileLock(this.path, this.codec, () => clearTrustedHeadFile(this.trustedHeadPath, this.codec)));
+		return this.locked(() => {
+			const removal = clearTrustedHeadFile(this.trustedHeadPath, this.codec);
+			if (this.verified !== null) this.verified.pin = null;
+			return removal;
+		});
+	}
+	/** Run under both locks. Any failure discards the verified state, because a
+	* throw can leave it describing bytes the file does not hold: a projector
+	* half way through a rejected transition, or a row whose write failed. */
+	locked(run) {
+		return this.mutex.runExclusive(() => withLedgerFileLock(this.path, this.codec, () => {
+			try {
+				return run();
+			} catch (error) {
+				this.verified = null;
+				throw error;
+			}
+		}));
+	}
+	/** Bring the verified state up to the file: keep it when its head row is
+	* still where it was verified, else start over from byte 0; then verify and
+	* apply every row past it, and check the pin. */
+	sync(requirePin) {
+		let state = this.verified;
+		const fd = openForReading(this.path, this.codec);
+		if (fd === null) {
+			if (state === null || state.size > 0) state = emptyJournal(this.codec);
+			this.verified = state;
+			this.verifyPin(state, requirePin);
+			return state;
+		}
+		try {
+			const stats = fstatSync(fd, { bigint: true });
+			const size = Number(stats.size);
+			const identity = {
+				dev: stats.dev,
+				ino: stats.ino
+			};
+			if (state === null || state.identity !== null && (state.identity.dev !== identity.dev || state.identity.ino !== identity.ino) || size < state.size || !headInPlace(fd, state.size, state.head?.row ?? null)) state = emptyJournal(this.codec);
+			state.identity = identity;
+			this.verified = state;
+			if (size > state.size) extendJournal(state, readRange(fd, state.size, size), this.path, this.codec);
+		} finally {
+			closeSync(fd);
+		}
+		this.verifyPin(state, requirePin);
+		return state;
+	}
+	verifyPin(state, requirePin) {
+		const pinned = readTrustedHeadFile(this.trustedHeadPath, this.codec);
+		const count = state.offsets.length;
+		if (pinned === null) {
+			state.pin = null;
+			if (requirePin && count > 0) throw this.codec.integrityError(`${this.codec.subject} ${this.path} has ${count} entries but no trusted head at ${this.trustedHeadPath} — without its pin the journal cannot prove nothing was deleted. Restore the pin file, or adopt the current head with pinTrustedHead().`);
+			return;
+		}
+		if (state.pin?.sequence === pinned.sequence && state.pin.entryHash === pinned.entryHash) return;
+		verifyEntriesAgainstTrustedHead({
+			length: count,
+			at: (sequence) => this.entryAt(state, sequence)
+		}, pinned, this.codec, {
+			subject: `${this.codec.subject} ${this.path}`,
+			trustedHeadPath: this.trustedHeadPath
+		});
+		state.pin = pinned;
 	}
 	/** Move the pin up to an entry this caller just acknowledged on the
 	* idempotent path, when a pin write that failed after its row was already
 	* fsynced left the pin behind. The move is safe because it is forward-only
-	* along a chain `replayLocked` has just verified: every entry up to this one
-	* is bound to it by hash, so the pin can only ever come to name more history
-	* than it did, never different history.
+	* along a chain `sync` has just verified: every entry up to this one is bound
+	* to it by hash, so the pin can only ever come to name more history than it
+	* did, never different history.
 	*
 	* With no pin at all this only pins the journal's current head. An entry in
 	* the middle would publish a pin that reads as protection while leaving every
 	* later entry silently truncatable, which is a worse state to hand an auditor
 	* than the honest absence of a pin; `pinTrustedHead()` is the way to pin an
 	* unpinned journal on purpose. */
-	pinAcknowledged(entry, entries) {
-		const pinned = readTrustedHeadFile(this.trustedHeadPath, this.codec);
+	pinAcknowledged(state, entry) {
+		const pinned = state.pin;
 		if (pinned === null) {
-			if (entry.sequence !== entries.length - 1) return;
+			if (entry.sequence !== state.offsets.length - 1) return;
 		} else if (pinned.sequence >= entry.sequence) return;
-		writeTrustedHeadFile(this.trustedHeadPath, {
+		const head = {
 			sequence: entry.sequence,
 			entryHash: entry.entryHash
-		}, this.codec);
-	}
-	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. Restore the pin file, or adopt the current head with pinTrustedHead().`);
-			return;
+		writeTrustedHeadFile(this.trustedHeadPath, head, this.codec);
+		state.pin = head;
+	}
+	/** The verified entry at `sequence`, read back from the file. The rows from
+	* it to the head are re-read and must chain to the verified head hash, which
+	* binds the returned entry to the history this instance verified. Callers ask
+	* for recent entries — an idempotent retry, a pin one entry behind — so this
+	* usually reads nothing or one row. */
+	entryAt(state, sequence) {
+		const count = state.offsets.length;
+		if (!Number.isSafeInteger(sequence) || sequence < 0 || sequence >= count) return void 0;
+		if (sequence === count - 1) return state.head.entry;
+		const changed = () => this.codec.integrityError(`${this.codec.subject} ${this.path} changed at or after sequence ${sequence} since this reader verified it`);
+		const fd = openForReading(this.path, this.codec);
+		if (fd === null) throw changed();
+		let bytes;
+		try {
+			bytes = readRange(fd, state.offsets[sequence], state.size);
+		} finally {
+			closeSync(fd);
 		}
-		verifyEntriesAgainstTrustedHead(entries, pinned, this.codec, {
-			subject: `${this.codec.subject} ${this.path}`,
-			trustedHeadPath: this.trustedHeadPath
-		});
-	}
-	readEntries() {
-		if (!existsSync(this.path)) return [];
-		return parseLedgerText(readFileSync(this.path, "utf8"), this.path, this.codec);
-	}
-	project(entries) {
-		return projectLedgerEntries(entries, this.codec);
+		const rows = splitRows(bytes, this.path, this.codec);
+		if (rows.length !== count - sequence) throw changed();
+		let first;
+		let previous;
+		for (let index = 0; index < rows.length; index += 1) {
+			const entry = parseRow(rows[index].text, {
+				path: this.path,
+				line: sequence + index + 1
+			}, this.codec);
+			const { entryHash, ...material } = entry;
+			if (entry.sequence !== sequence + index || hashCanonical(material) !== entryHash || previous !== void 0 && entry.previousHash !== previous.entryHash) throw changed();
+			first ??= entry;
+			previous = entry;
+		}
+		if (previous?.entryHash !== state.head.entry.entryHash) throw changed();
+		return first;
 	}
 };
 /** Verify and replay resolved immutable journal bytes without filesystem I/O. */
 function replayLedgerText(text, path, codec) {
-	const entries = parseLedgerText(text, path, codec);
+	const state = emptyJournal(codec);
+	extendJournal(state, Buffer.from(text, "utf8"), path, codec);
+	return state.projector.snapshot();
+}
+function emptyJournal(codec) {
 	return {
-		entries,
-		projection: projectLedgerEntries(entries, codec)
+		identity: null,
+		size: 0,
+		offsets: [],
+		head: null,
+		sequenceByEventId: /* @__PURE__ */ new Map(),
+		projector: codec.createProjector(),
+		pin: null
 	};
 }
-function parseLedgerText(text, path, codec) {
-	if (text.length === 0) return [];
-	if (!text.endsWith("\n")) throw codec.integrityError(`${codec.subject} ${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 codec.integrityError(`${codec.subject} ${path} has a blank row at line ${index + 1}`);
-		let raw;
-		try {
-			raw = JSON.parse(line);
-		} catch (error) {
-			throw codec.integrityError(`${codec.subject} ${path} has invalid JSON at line ${index + 1}`, { cause: error });
-		}
-		const entry = codec.parseEntry(raw, {
-			path,
-			line: index + 1
+/** Verify and apply the rows in `bytes`, which start at the state's verified
+* length. */
+function extendJournal(state, bytes, path, codec) {
+	const rows = splitRows(bytes, path, codec);
+	for (const { text, start, end } of rows) admitEntry(state, parseRow(text, {
+		path,
+		line: state.offsets.length + 1
+	}, codec), Buffer.from(bytes.subarray(start, end)), codec);
+}
+/** Check one parsed entry against the chain and apply it. Every row, read or
+* about to be written, enters the verified state here. */
+function admitEntry(state, entry, row, codec) {
+	const index = state.offsets.length;
+	codec.checkEntryHeader(entry, index);
+	if (entry.sequence !== index) throw codec.integrityError(`entry ${entry.event.eventId} has sequence ${entry.sequence}, expected ${index}`);
+	if (entry.previousHash !== (state.head?.entry.entryHash ?? null)) throw 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 codec.integrityError(`entry ${entry.event.eventId} hash mismatch: expected ${expectedHash}, got ${entry.entryHash}`);
+	if (state.sequenceByEventId.has(entry.event.eventId)) throw codec.integrityError(`duplicate eventId ${entry.event.eventId} in durable ledger`);
+	state.projector.apply(entry, index);
+	state.sequenceByEventId.set(entry.event.eventId, index);
+	state.offsets.push(state.size);
+	state.size += row.byteLength;
+	state.head = {
+		entry,
+		row
+	};
+}
+/** Parse one canonical row into a frozen entry. The projector and every caller
+* share entries, so none of them can change what the journal verified. */
+function parseRow(text, context, codec) {
+	const { path, line } = context;
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch (error) {
+		throw codec.integrityError(`${codec.subject} ${path} has invalid JSON at line ${line}`, { cause: error });
+	}
+	const entry = codec.parseEntry(raw, context);
+	let canonical;
+	try {
+		canonical = canonicalString(entry);
+	} catch (error) {
+		throw codec.integrityError(`${codec.subject} ${path} has a row with no canonical JSON form at line ${line}`, { cause: error });
+	}
+	if (text !== canonical) throw codec.integrityError(`${codec.subject} ${path} has non-canonical bytes at line ${line}`);
+	return deepFreezeCanonicalJson(entry);
+}
+function splitRows(bytes, path, context) {
+	if (bytes.byteLength === 0) return [];
+	if (bytes[bytes.byteLength - 1] !== 10) throw context.integrityError(`${context.subject} ${path} has a truncated final record (missing newline)`);
+	const rows = [];
+	let start = 0;
+	while (start < bytes.byteLength) {
+		const newline = bytes.indexOf(10, start);
+		if (newline === start) throw context.integrityError(`${context.subject} ${path} has a blank row at line ${rows.length + 1}`);
+		rows.push({
+			text: bytes.toString("utf8", start, newline),
+			start,
+			end: newline + 1
 		});
-		let canonical;
-		try {
-			canonical = canonicalString(entry);
-		} catch (error) {
-			throw codec.integrityError(`${codec.subject} ${path} has a row with no canonical JSON form at line ${index + 1}`, { cause: error });
-		}
-		if (line !== canonical) throw codec.integrityError(`${codec.subject} ${path} has non-canonical bytes at line ${index + 1}`);
-		entries.push(entry);
-	}
-	return entries;
-}
-function projectLedgerEntries(entries, codec) {
-	const projector = codec.createProjector();
-	const eventIds = /* @__PURE__ */ new Set();
-	let expectedPrevious = null;
-	for (let index = 0; index < entries.length; index += 1) {
-		const entry = entries[index];
-		codec.checkEntryHeader(entry, index);
-		if (entry.sequence !== index) throw codec.integrityError(`entry ${entry.event.eventId} has sequence ${entry.sequence}, expected ${index}`);
-		if (entry.previousHash !== expectedPrevious) throw 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 codec.integrityError(`entry ${entry.event.eventId} hash mismatch: expected ${expectedHash}, got ${entry.entryHash}`);
-		expectedPrevious = entry.entryHash;
-		if (eventIds.has(entry.event.eventId)) throw codec.integrityError(`duplicate eventId ${entry.event.eventId} in durable ledger`);
-		eventIds.add(entry.event.eventId);
-		projector.apply(entry, index);
-	}
-	return projector.finish(entries);
+		start = newline + 1;
+	}
+	return rows;
+}
+/** True when the verified head row still ends the verified length of the file. */
+function headInPlace(fd, size, row) {
+	return row === null || readRange(fd, size - row.byteLength, size).equals(row);
+}
+/** A read-only descriptor, or null when the file does not exist. */
+function openForReading(path, context) {
+	try {
+		return openSync(path, constants.O_RDONLY);
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw context.integrityError(`${context.subject} ${path} could not be opened for reading`, { cause: error });
+	}
+}
+function readRange(fd, start, end) {
+	const bytes = Buffer.allocUnsafe(end - start);
+	let offset = 0;
+	while (offset < bytes.byteLength) {
+		const read = readSync(fd, bytes, offset, bytes.byteLength - offset, start + offset);
+		if (read === 0) return bytes.subarray(0, offset);
+		offset += read;
+	}
+	return bytes;
 }
 //#endregion
 export { verifyEntriesAgainstTrustedHead as a, withLedgerFileLock as c, mapConcurrent as d, mapConcurrentRange as f, tryAcquireAtomicFileLock as h, trustedHeadPathFor as i, writeLedgerFileAtomically as l, probeAtomicFileLock as m, replayLedgerText as n, appendLedgerLine as o, AtomicFileLockError as p, readTrustedHeadFile as r, tryWithLedgerFileLock as s, FileLedgerJournal as t, Mutex as u };
 
-//# sourceMappingURL=journal-BuRLm6ho.js.map
+//# sourceMappingURL=journal-CDP0Vhx_.js.map