@deepseek-ai/dsh-session-persistence-jsonl 0.1.2-alpha.5 → 0.1.3-alpha.2

package/lib/worker.cjs

@@ -0,0 +1,1235 @@
+let node_worker_threads = require("node:worker_threads");
+let node_crypto = require("node:crypto");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let node_perf_hooks = require("node:perf_hooks");
+let node_stream = require("node:stream");
+let node_timers_promises = require("node:timers/promises");
+let node_util = require("node:util");
+let node_zlib = require("node:zlib");
+let _deepseek_ai_dsh_session = require("@deepseek-ai/dsh-session");
+let _deepseek_ai_dsh_llm = require("@deepseek-ai/dsh-llm");
+let _deepseek_ai_dsh_session_persistence = require("@deepseek-ai/dsh-session-persistence");
+let _deepseek_ai_dsh_session_format = require("@deepseek-ai/dsh-session-format");
+let _deepseek_ai_dsh_session_format_catalog = require("@deepseek-ai/dsh-session-format-catalog");
+let node_buffer = require("node:buffer");
+//#region lib/types/format.js
+/**
+* On-disk format helpers for the JSONL session-persistence backend: path
+* sanitization (a {@link SessionId} is an unvalidated branded string, so it
+* MUST be encoded before use in a path — no traversal, no collision), the
+* per-project/session directory layout, header-line (de)serialization, and the
+* truncation-repair offset computation.
+*
+* @module dsh-session-persistence-jsonl/format
+*/
+/**
+* Return the artifact suffix for one physical encoding.
+* @param compression - configured JSONL artifact encoding.
+* @returns `.jsonl.zstd` for Zstandard or `.jsonl` for plaintext.
+*/
+function logSuffix(compression) {
+	return `.jsonl${compressionSuffix(compression)}`;
+}
+function compressionSuffix(compression) {
+	return compression === "zstd" ? ".zstd" : "";
+}
+/**
+* Return the canonical filename for one immutable Session format generation.
+* Version zero retains the original suffix-only name; every later generation
+* carries a lowercase numeric `vN` component.
+* @param version - non-negative safe Session format version.
+* @param compression - configured JSONL artifact encoding.
+* @returns the generation filename inside one Session directory.
+*/
+function generationLogFilename(version, compression) {
+	return `${(0, _deepseek_ai_dsh_session_format.sessionFormatLogFilename)(version)}${compressionSuffix(compression)}`;
+}
+const HEADER_REQUIRED_KEYS = [
+	"type",
+	"version",
+	"id",
+	"createdAt",
+	"isSeeded",
+	"delegationDepth"
+];
+const HEADER_OPTIONAL_KEYS = [
+	"cwd",
+	"parentSession",
+	"origin",
+	"agentPreset"
+];
+const HEADER_KEYS = new Set([...HEADER_REQUIRED_KEYS, ...HEADER_OPTIONAL_KEYS]);
+/**
+* Refuse policy fields that never belong to a released Session header.
+* @param value - parsed physical header candidate.
+* @returns nothing after successful validation.
+*/
+function assertNoRetiredHeaderFields(value) {
+	if (typeof value !== "object" || value === null) return;
+	if (Object.hasOwn(value, "sandboxMode") || Object.hasOwn(value, "approvalPolicy")) throw new Error("session header uses retired policy baseline fields");
+}
+/**
+* Translate one current physical header into logical metadata and its cut.
+* @param line - the shape-checked first line of a log (see the `isHeaderLine` guard).
+* @returns logical Session metadata paired with the exact inherited prefix length.
+*/
+function fromHeaderLine(line) {
+	return {
+		meta: {
+			version: _deepseek_ai_dsh_session.SESSION_FORMAT_VERSION,
+			id: line.id,
+			createdAt: line.createdAt,
+			...line.cwd !== void 0 ? { cwd: line.cwd } : {},
+			...line.parentSession !== void 0 ? { parentSession: line.parentSession } : {},
+			isSeeded: line.isSeeded,
+			...line.origin !== void 0 ? { origin: line.origin } : {},
+			delegationDepth: line.delegationDepth,
+			...line.agentPreset !== void 0 ? { agentPreset: line.agentPreset } : {}
+		},
+		inheritedEventCount: (0, _deepseek_ai_dsh_session.SessionLogOffset)(0)
+	};
+}
+/** Type guard: a parsed first line is a well-formed session header. */
+function isHeaderLine(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && HEADER_REQUIRED_KEYS.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => HEADER_KEYS.has(key)) && value.type === "session" && typeof value.version === "number" && typeof value.id === "string" && typeof value.createdAt === "number" && Number.isSafeInteger(value.createdAt) && value.createdAt >= 0 && !Object.is(value.createdAt, -0) && typeof value.delegationDepth === "number" && Number.isSafeInteger(value.delegationDepth) && value.delegationDepth >= 0 && !Object.is(value.delegationDepth, -0) && (value.cwd === void 0 || typeof value.cwd === "string" && (0, node_path.isAbsolute)(value.cwd)) && (value.parentSession === void 0 || typeof value.parentSession === "string") && typeof value.isSeeded === "boolean" && (value.origin === void 0 || value.origin === "subagent") && (value.agentPreset === void 0 || typeof value.agentPreset === "string");
+}
+/**
+* Refuse a header carrying a format version this build does not read BEFORE
+* validating the current header shape or decoding any event row: a future
+* format need not satisfy this build's structural checks at all, and its user
+* must see "upgrade the harness", never "corrupt session log".
+* @param parsed - the JSON-parsed first line of a session artifact.
+*/
+function refuseForeignFormatVersion(parsed) {
+	const { version, id } = parsed;
+	if (typeof version !== "number" || version === _deepseek_ai_dsh_session.SESSION_FORMAT_VERSION) return;
+	throw new _deepseek_ai_dsh_session_persistence.SessionFormatUnsupportedError((0, _deepseek_ai_dsh_session_persistence.sessionFormatVersionRefusal)(typeof id === "string" ? id : String(id), version));
+}
+/** Parse one complete header record supplied independently from event rows. */
+function parseHeaderRecord(record) {
+	if (record.length === 0 || record.at(-1) !== 10 || record.indexOf(10) !== record.length - 1) throw new Error("empty or header-less session log");
+	let parsed;
+	try {
+		parsed = JSON.parse(record.subarray(0, -1).toString("utf8"));
+	} catch {
+		throw new Error("corrupt session log: header line is not valid JSON");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("corrupt session log: first line is not a JSON object");
+	refuseForeignFormatVersion(parsed);
+	assertNoRetiredHeaderFields(parsed);
+	if (!isHeaderLine(parsed)) throw new Error("corrupt session log: first line is not a session header");
+	let restore;
+	try {
+		restore = _deepseek_ai_dsh_session_format_catalog.sessionFormatCatalog.createRestore(parsed, {
+			recovery: "strict",
+			validation: "transformed"
+		});
+	} catch {
+		/* v8 ignore next -- isHeaderLine matches the current codec; this preserves classification if it tightens. */
+		throw new Error("corrupt session log: first line is not a session header");
+	}
+	return {
+		meta: fromHeaderLine(parsed).meta,
+		restore
+	};
+}
+/**
+* Incrementally scan complete JSONL event records after an independently
+* supplied header record. Newline search and byte offsets stay on raw buffers;
+* only complete records are decoded to UTF-8. A fragment crossing writes is
+* copied because a decoder may reuse its output buffer after `write()` returns.
+*/
+var SessionLogScanner = class {
+	recovery;
+	meta;
+	restore;
+	eventCount = 0;
+	fragments = [];
+	fragmentBytes = 0;
+	inputBytes;
+	committedBytes;
+	eventLine = 0;
+	issue;
+	finished = false;
+	/**
+	* Create an event scanner from exactly one newline-terminated header record.
+	* @param headerRecord - the complete first JSONL record, including its newline.
+	*/
+	constructor(headerRecord, recovery = "recoverable") {
+		this.recovery = recovery;
+		const parsed = parseHeaderRecord(headerRecord);
+		this.meta = parsed.meta;
+		this.restore = parsed.restore;
+		this.inputBytes = headerRecord.length;
+		this.committedBytes = headerRecord.length;
+	}
+	/**
+	* Consume the next raw plaintext chunk, retaining only an incomplete final record.
+	* @param chunk - bytes immediately following all previously supplied bytes.
+	*/
+	write(chunk) {
+		if (this.finished) throw new Error("cannot write to a finished session log scanner");
+		const chunkStart = this.inputBytes;
+		this.inputBytes += chunk.length;
+		let lineStart = 0;
+		for (let newline = chunk.indexOf(10); newline !== -1; newline = chunk.indexOf(10, lineStart)) {
+			const fragment = chunk.subarray(lineStart, newline);
+			let line = fragment;
+			if (this.fragments.length > 0) {
+				if (fragment.length > 0) this.fragments.push(fragment);
+				line = Buffer.concat(this.fragments, this.fragmentBytes + fragment.length);
+				this.fragments = [];
+				this.fragmentBytes = 0;
+			}
+			this.consumeEventLine(line, chunkStart + newline + 1);
+			lineStart = newline + 1;
+		}
+		if (lineStart < chunk.length) {
+			const fragment = Buffer.from(chunk.subarray(lineStart));
+			this.fragments.push(fragment);
+			this.fragmentBytes += fragment.length;
+		}
+	}
+	/**
+	* Snapshot progress before appending a recoverable torn-frame prefix.
+	* @returns byte, committed-prefix, and expanded-event cursors.
+	*/
+	checkpoint() {
+		return {
+			inputBytes: this.inputBytes,
+			committedBytes: this.committedBytes,
+			eventCount: (0, _deepseek_ai_dsh_session.SessionLogOffset)(this.eventCount)
+		};
+	}
+	/**
+	* Finish scanning, ignoring a final record without a newline as a torn tail.
+	* @returns the header, contiguous event prefix, and safe truncation offset.
+	*/
+	finish() {
+		this.finished = true;
+		const artifact = this.restore.finish();
+		return {
+			meta: this.meta,
+			inheritedEventCount: (0, _deepseek_ai_dsh_session.SessionLogOffset)(artifact.inheritedEventCount),
+			events: artifact.events,
+			committedBytes: this.committedBytes
+		};
+	}
+	/** Decode one complete event row and update the contiguous prefix. */
+	consumeEventLine(line, endByte) {
+		this.eventLine += 1;
+		let decoded;
+		try {
+			decoded = JSON.parse(line.toString("utf8"));
+		} catch {
+			const issue = /* @__PURE__ */ new Error(`corrupt session log: unparsable committed event at line ${this.eventLine}`);
+			if (this.recovery === "strict") throw issue;
+			this.issue ??= issue;
+			return;
+		}
+		if (this.issue !== void 0) {
+			if (typeof decoded === "object" && decoded !== null && decoded.type === "turn/end") throw this.issue;
+			return;
+		}
+		try {
+			this.restore.decodeRow(decoded);
+		} catch (error) {
+			/* v8 ignore next -- every production Session format decoder rejects with Error. */
+			const detail = error instanceof Error ? error.message : String(error);
+			const issue = new Error(`corrupt session log: invalid committed event at line ${this.eventLine}: ${detail}`, { cause: error });
+			if (this.recovery === "strict") throw issue;
+			this.issue = issue;
+			if (typeof decoded === "object" && decoded !== null && decoded.type === "turn/end") throw issue;
+			return;
+		}
+		this.eventCount += 1;
+		this.committedBytes = endByte;
+	}
+};
+//#endregion
+//#region lib/types/win32.js
+/**
+* Windows durable namespace helpers for the JSONL backend.
+*
+* POSIX publishes a newly-created log by creating a directory entry and then
+* fsyncing the parent directory. Windows does not expose that parent-directory
+* fsync contract through Node, so the Windows path uses the native durable
+* namespace primitive instead: create a staging object in the target directory
+* and publish it with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without
+* replacement or cross-volume copy fallback.
+*
+* @module dsh-session-persistence-jsonl/win32
+*/
+const MOVEFILE_WRITE_THROUGH = 8;
+const ERROR_FILE_NOT_FOUND = 2;
+const ERROR_PATH_NOT_FOUND = 3;
+const ERROR_ACCESS_DENIED = 5;
+const ERROR_NOT_SAME_DEVICE = 17;
+const ERROR_SHARING_VIOLATION = 32;
+const ERROR_FILE_EXISTS = 80;
+const ERROR_INVALID_NAME = 123;
+const ERROR_ALREADY_EXISTS = 183;
+let bindings;
+/** Load the small Win32 API lazily so non-Windows processes never load Koffi. */
+async function win32() {
+	if (bindings !== void 0) return bindings;
+	const kernel32 = (await import("koffi")).default.load("kernel32.dll");
+	bindings = {
+		moveFileExW: kernel32.func("__stdcall", "MoveFileExW", "int", [
+			"str16",
+			"str16",
+			"uint"
+		]),
+		createSemaphoreW: kernel32.func("__stdcall", "CreateSemaphoreW", "intptr", [
+			"void*",
+			"int",
+			"int",
+			"str16"
+		]),
+		waitForSingleObject: kernel32.func("__stdcall", "WaitForSingleObject", "uint", ["intptr", "uint"]),
+		releaseSemaphore: kernel32.func("__stdcall", "ReleaseSemaphore", "int", [
+			"intptr",
+			"int",
+			"void*"
+		]),
+		closeHandle: kernel32.func("__stdcall", "CloseHandle", "int", ["intptr"]),
+		getLastError: kernel32.func("__stdcall", "GetLastError", "uint", [])
+	};
+	return bindings;
+}
+function errnoCode(win32Code) {
+	switch (win32Code) {
+		case ERROR_FILE_NOT_FOUND:
+		case ERROR_PATH_NOT_FOUND: return "ENOENT";
+		case ERROR_ACCESS_DENIED: return "EACCES";
+		case ERROR_NOT_SAME_DEVICE: return "EXDEV";
+		case ERROR_SHARING_VIOLATION: return "EBUSY";
+		case ERROR_FILE_EXISTS:
+		case ERROR_ALREADY_EXISTS: return "EEXIST";
+		case ERROR_INVALID_NAME: return "EINVAL";
+		default: return "EIO";
+	}
+}
+function win32Error(syscall, win32Code, path, dest) {
+	const code = errnoCode(win32Code);
+	const error = /* @__PURE__ */ new Error(`${syscall} ${code} (Win32 ${win32Code}): ${path} -> ${dest}`);
+	error.code = code;
+	error.errno = win32Code;
+	error.syscall = syscall;
+	error.path = path;
+	error.dest = dest;
+	error.win32Code = win32Code;
+	return error;
+}
+/**
+* Publish `existing` at `replacement` with Windows write-through rename
+* semantics. The destination must not already exist; the move must stay within
+* the volume (no copy fallback flag is set).
+* @param existing - the synced staging path to move.
+* @param replacement - the final path, which must not already exist.
+*/
+async function publishNewFileWin32(existing, replacement) {
+	const api = await win32();
+	if (api.moveFileExW((0, node_path.toNamespacedPath)(existing), (0, node_path.toNamespacedPath)(replacement), MOVEFILE_WRITE_THROUGH) === 0) throw win32Error("MoveFileExW", api.getLastError(), existing, replacement);
+}
+//#endregion
+//#region lib/types/zstd-private-decoder.js
+/**
+* Node-private synchronous Zstandard frame decoder optimization.
+* @module dsh-session-persistence-jsonl/zstd-private-decoder
+*/
+const DECODE_CHUNK_SIZE = 1024 * 1024;
+/** Return the stream with its observed private Node contract, or reject that optimization. */
+function privateZstdStream(stream) {
+	const candidate = stream;
+	const handle = candidate._handle;
+	const errorKey = Reflect.ownKeys(stream).find((key) => typeof key === "symbol" && key.description === "kError");
+	/* v8 ignore next -- one test runtime exposes one Node-private shape; the Node 22/24/26 matrix checks compatibility. */
+	if (typeof handle !== "object" || handle === null || typeof handle.writeSync !== "function" || !(candidate._writeState instanceof Uint32Array) || candidate._writeState.length < 2 || typeof candidate._defaultFlushFlag !== "number" || errorKey === void 0 || candidate[errorKey] !== null) return void 0;
+	return {
+		stream,
+		errorKey
+	};
+}
+/**
+* Synchronous multi-frame decoder backed by one Node Zstd stream handle. Node
+* exposes synchronous decoding only as a one-shot API, so this adapter uses
+* the stream's private handle contract to reuse its native context and output
+* chunks across frames.
+*/
+var NodePrivateZstdFrameDecoder = class NodePrivateZstdFrameDecoder {
+	stream;
+	errorKey;
+	output = Buffer.allocUnsafe(DECODE_CHUNK_SIZE);
+	decoderError;
+	started = false;
+	closed = false;
+	constructor(stream, errorKey) {
+		this.stream = stream;
+		this.errorKey = errorKey;
+		this.stream.on("error", (error) => {
+			this.decoderError ??= error;
+		});
+	}
+	/**
+	* Create the optimized decoder when this Node release exposes the expected
+	* private stream shape.
+	* @returns a shared decoder, or `undefined` when callers must use the public fallback.
+	*/
+	static create() {
+		const stream = (0, node_zlib.createZstdDecompress)({ chunkSize: DECODE_CHUNK_SIZE });
+		const privateAccess = privateZstdStream(stream);
+		/* v8 ignore next -- reached only when a supported Node release changes its private stream shape. */
+		if (privateAccess !== void 0) return new NodePrivateZstdFrameDecoder(privateAccess.stream, privateAccess.errorKey);
+		/* v8 ignore next -- the active Node runtime passed the private-shape probe above. */
+		stream.close();
+	}
+	/** @inheritdoc */
+	*decode(source, frames) {
+		if (this.started) throw new Error("Zstandard frame decoder was already started");
+		if (this.closed) throw new Error("cannot start a closed Zstandard frame decoder");
+		this.started = true;
+		try {
+			for (const frame of frames) try {
+				yield this.decodeFrame(source.subarray(frame.start, frame.end));
+			} catch (error) {
+				throw new Error(`corrupt Zstandard session log: frame at byte ${frame.start} failed validation`, { cause: error });
+			}
+		} finally {
+			this.close();
+		}
+	}
+	/** Decode one frame; its returned scratch view remains valid until the next call. */
+	decodeFrame(input) {
+		const handle = this.stream._handle;
+		/* v8 ignore next -- decode() rejects closed instances before entering this private frame operation. */
+		if (this.closed || handle === null) throw new Error("cannot decode with a closed Zstandard frame decoder");
+		let inputOffset = 0;
+		let inputRemaining = input.length;
+		let outputBytes = 0;
+		const fullChunks = [];
+		for (;;) {
+			handle.writeSync(this.stream._defaultFlushFlag, input, inputOffset, inputRemaining, this.output, 0, this.output.length);
+			if (this.decoderError !== void 0) throw this.decoderError;
+			const internalError = this.stream[this.errorKey];
+			if (internalError !== null) {
+				if (internalError instanceof Error) throw internalError;
+				throw new Error("Zstandard decoder exposed a non-Error internal failure");
+			}
+			const outputAfter = this.stream._writeState[0];
+			const inputAfter = this.stream._writeState[1];
+			const consumed = inputRemaining - inputAfter;
+			const produced = this.output.length - outputAfter;
+			if (produced > 0) {
+				outputBytes += produced;
+				/* v8 ignore next -- Buffer cannot materialize a frame beyond its own process-wide maximum length. */
+				if (outputBytes > node_buffer.constants.MAX_LENGTH) throw new Error(`Zstandard frame output exceeds ${node_buffer.constants.MAX_LENGTH} bytes`);
+			}
+			if (outputAfter !== 0) {
+				/* v8 ignore next -- structurally scanned ranges contain exactly one complete frame and no trailing bytes. */
+				if (inputAfter !== 0) throw new Error("Zstandard frame decoder left trailing input");
+				const finalChunk = this.output.subarray(0, produced);
+				if (fullChunks.length === 0) return finalChunk;
+				if (produced > 0) fullChunks.push(Buffer.from(finalChunk));
+				const onlyChunk = fullChunks[0];
+				return fullChunks.length === 1 ? onlyChunk : Buffer.concat(fullChunks, outputBytes);
+			}
+			fullChunks.push(Buffer.from(this.output));
+			inputOffset += consumed;
+			inputRemaining = inputAfter;
+		}
+	}
+	/** @inheritdoc */
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.stream.close();
+	}
+};
+//#endregion
+//#region lib/types/zstd-public-decoder.js
+/**
+* Public-API synchronous Zstandard frame decoder fallback.
+* @module dsh-session-persistence-jsonl/zstd-public-decoder
+*/
+/** Multi-frame adapter built exclusively from Node's supported one-shot API. */
+var PublicZstdFrameDecoder = class {
+	started = false;
+	closed = false;
+	/** @inheritdoc */
+	*decode(source, frames) {
+		if (this.started) throw new Error("Zstandard frame decoder was already started");
+		if (this.closed) throw new Error("cannot start a closed Zstandard frame decoder");
+		this.started = true;
+		try {
+			for (const { start, end } of frames) {
+				let decoded;
+				try {
+					decoded = (0, node_zlib.zstdDecompressSync)(source.subarray(start, end));
+				} catch (error) {
+					throw new Error(`corrupt Zstandard session log: frame at byte ${start} failed validation`, { cause: error });
+				}
+				yield decoded;
+			}
+		} finally {
+			this.close();
+		}
+	}
+	/** @inheritdoc */
+	close() {
+		this.closed = true;
+	}
+};
+//#endregion
+//#region lib/types/zstd.js
+/**
+* Zstandard frame primitives for the JSONL persistence backend. The backend
+* owns a concatenated-frame container so it can append and recover batches
+* without exposing compression mechanics through the persistence seam.
+* @module dsh-session-persistence-jsonl/zstd
+*/
+const ZSTD_MAGIC = 4247762216;
+const zstdCompressAsync = (0, node_util.promisify)(node_zlib.zstdCompress);
+const zstdDecompressAsync = (0, node_util.promisify)(node_zlib.zstdDecompress);
+const CHECKSUM_OPTIONS = { params: { [node_zlib.constants.ZSTD_c_checksumFlag]: 1 } };
+const INCOMPLETE_FRAME_OPTIONS = { finishFlush: node_zlib.constants.ZSTD_e_flush };
+/**
+* Locate complete frames without decompressing their blocks. Invalid complete
+* structure rejects; EOF inside the final frame returns its start for repair.
+* @param buffer - complete bytes currently present in the session artifact.
+* @param maxFrames - optional complete-frame limit for metadata-only readers.
+* @returns complete frame ranges and an optional incomplete-final-frame start.
+*/
+function scanZstdFrames(buffer, maxFrames = Number.POSITIVE_INFINITY) {
+	const frames = [];
+	let offset = 0;
+	while (offset < buffer.length) {
+		const start = offset;
+		if (buffer.length - offset < 4) return {
+			frames,
+			tornStart: start
+		};
+		if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) throw new Error(`corrupt Zstandard session log: invalid frame magic at byte ${offset}`);
+		offset += 4;
+		if (offset === buffer.length) return {
+			frames,
+			tornStart: start
+		};
+		const descriptor = buffer.readUInt8(offset);
+		offset += 1;
+		if ((descriptor & 24) !== 0) throw new Error(`corrupt Zstandard session log: reserved frame-header bit at byte ${offset - 1}`);
+		const contentSizeFlag = descriptor >>> 6;
+		const singleSegment = (descriptor & 32) !== 0;
+		const checksum = (descriptor & 4) !== 0;
+		const dictionaryFlag = descriptor & 3;
+		const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+		const contentSizeBytes = contentSizeFlag === 0 ? singleSegment ? 1 : 0 : 1 << contentSizeFlag;
+		const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+		if (buffer.length - offset < remainingHeaderBytes) return {
+			frames,
+			tornStart: start
+		};
+		offset += remainingHeaderBytes;
+		for (;;) {
+			if (buffer.length - offset < 3) return {
+				frames,
+				tornStart: start
+			};
+			const blockHeader = buffer.readUIntLE(offset, 3);
+			offset += 3;
+			const lastBlock = (blockHeader & 1) !== 0;
+			const blockType = blockHeader >>> 1 & 3;
+			const blockSize = blockHeader >>> 3;
+			if (blockType === 3) throw new Error(`corrupt Zstandard session log: reserved block type at byte ${offset - 3}`);
+			const payloadBytes = blockType === 1 ? 1 : blockSize;
+			if (buffer.length - offset < payloadBytes) return {
+				frames,
+				tornStart: start
+			};
+			offset += payloadBytes;
+			if (lastBlock) break;
+		}
+		if (checksum) {
+			if (buffer.length - offset < 4) return {
+				frames,
+				tornStart: start
+			};
+			offset += 4;
+		}
+		frames.push({
+			start,
+			end: offset
+		});
+		if (frames.length === maxFrames) return { frames };
+	}
+	return { frames };
+}
+/**
+* Compress one independently decodable, checksummed Zstandard frame.
+* @param input - JSONL bytes for a header or durable event batch.
+* @returns the complete encoded frame.
+*/
+async function compressZstdFrame(input) {
+	return zstdCompressAsync(input, CHECKSUM_OPTIONS);
+}
+/**
+* Select the shared private decoder when the running Node 22/24/26 shape is
+* compatible, otherwise preserve correctness with the public one-shot API.
+* @returns a synchronous decoder with an implementation-independent lifecycle.
+*/
+function createZstdFrameDecoder() {
+	return NodePrivateZstdFrameDecoder.create() ?? new PublicZstdFrameDecoder();
+}
+/**
+* Recover available plaintext from a structurally incomplete final frame.
+* `ZSTD_e_flush` deliberately suppresses final-frame and checksum completion;
+* callers must establish the torn frame boundary before using this helper.
+* @param input - available bytes from a known incomplete Zstandard frame.
+* @returns plaintext produced from the available input.
+*/
+async function decompressZstdPrefix(input) {
+	return zstdDecompressAsync(input, INCOMPLETE_FRAME_OPTIONS);
+}
+//#endregion
+//#region lib/types/generation.js
+/**
+* Durable whole-generation publication for JSONL Session artifacts.
+*
+* Format packages transform parsed JSON values. This module owns the physical
+* encoding, exact source identity, immutable generation files, and exclusive
+* current-generation publication for both configured JSONL suffixes.
+* @module @deepseek-ai/dsh-session-persistence-jsonl/generation
+*/
+/** Internal scheduling bounds: preserve old decode cadence and cap each synchronous encode slice. */
+const MIGRATION_DECODE_YIELD_INTERVAL_MS = 500;
+const MIGRATION_WORK_CHUNK_BYTES = 1024 * 1024;
+const MIGRATION_WRITE_CHUNK_BYTES = 4 * 1024 * 1024;
+const ZSTD_CHECKSUM_OPTIONS = {
+	chunkSize: MIGRATION_WORK_CHUNK_BYTES,
+	params: { [node_zlib.constants.ZSTD_c_checksumFlag]: 1 }
+};
+/** A historical source changed after its single decode and migration pass. */
+var JsonlGenerationSourceChangedError = class extends Error {
+	path;
+	name = "JsonlGenerationSourceChangedError";
+	/** @param path - historical generation whose revision changed. */
+	constructor(path) {
+		super(`historical session generation changed during migration: "${path}"`);
+		this.path = path;
+	}
+};
+/** A historical artifact is intact, but the format edge refuses its contents. */
+var JsonlGenerationUnsupportedMigrationError = class extends Error {
+	fromVersion;
+	reason;
+	name = "JsonlGenerationUnsupportedMigrationError";
+	/**
+	* @param fromVersion - unchanged source generation version.
+	* @param reason - format-edge refusal.
+	*/
+	constructor(fromVersion, reason) {
+		super(reason.message, { cause: reason });
+		this.fromVersion = fromVersion;
+		this.reason = reason;
+	}
+};
+/** A current-generation filename already names different or invalid bytes. */
+var JsonlGenerationTargetConflictError = class extends Error {
+	path;
+	reason;
+	name = "JsonlGenerationTargetConflictError";
+	/**
+	* @param path - immutable target that prevented exclusive publication.
+	* @param reason - why the existing target cannot be accepted.
+	*/
+	constructor(path, reason) {
+		super(`current session generation already exists at "${path}": ${reason.message}`, { cause: reason });
+		this.path = path;
+		this.reason = reason;
+	}
+};
+const defaultFileSystem = {
+	open: (path, flags, mode) => (0, node_fs_promises.open)(path, flags, mode),
+	readFile: (path, signal) => (0, node_fs_promises.readFile)(path, signal === void 0 ? void 0 : { signal }),
+	readdir: (path) => (0, node_fs_promises.readdir)(path),
+	stat: (path) => (0, node_fs_promises.stat)(path, { bigint: true }),
+	lstat: (path) => (0, node_fs_promises.lstat)(path),
+	link: node_fs_promises.link,
+	rm: (path) => (0, node_fs_promises.rm)(path, { force: true })
+};
+const defaultInternals = {
+	fs: defaultFileSystem,
+	randomToken: () => (0, node_crypto.randomBytes)(8).toString("hex"),
+	platform: process.platform,
+	publishNewWin32: publishNewFileWin32,
+	barrier: () => {}
+};
+function isEEXIST(error) {
+	return error?.code === "EEXIST";
+}
+/** Whether a filesystem-owned failure should retain its original errno and path. */
+function isErrnoException(error) {
+	return typeof error?.code === "string";
+}
+function identity(value) {
+	return [
+		value.dev,
+		value.ino,
+		value.size,
+		value.mtimeNs,
+		value.ctimeNs
+	].join(":");
+}
+async function readStableSnapshot(path, signal, fs) {
+	signal?.throwIfAborted();
+	let before = await fs.stat(path);
+	for (let attempt = 0;; attempt += 1) {
+		const bytes = await fs.readFile(path, signal);
+		signal?.throwIfAborted();
+		const after = await fs.stat(path);
+		if (identity(before) === identity(after)) {
+			signal?.throwIfAborted();
+			return {
+				bytes,
+				identity: after
+			};
+		}
+		if (attempt === 1) return {
+			bytes: bytes.subarray(0, Number(before.size)),
+			identity: before
+		};
+		before = after;
+	}
+}
+/** Parse the version discriminator without validating any version-specific field. */
+function storedVersion(header) {
+	if (typeof header !== "object" || header === null || Array.isArray(header)) throw new Error("corrupt session log: first line is not a JSON object");
+	const version = header.version;
+	if (!Number.isSafeInteger(version) || version < 0 || Object.is(version, -0)) throw new Error("corrupt session log: header version is not a non-negative safe integer");
+	return version;
+}
+function parseJson(text, subject) {
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		throw new Error(`corrupt session log: ${subject} is not valid JSON`, { cause: error });
+	}
+}
+/** Incremental JSONL parser that retains only one cross-frame record fragment. */
+var MigratingJsonlRows = class {
+	restore;
+	fragments = [];
+	fragmentBytes = 0;
+	rowIndex = 0;
+	issue;
+	constructor(restore) {
+		this.restore = restore;
+	}
+	/** Consume plaintext bytes following the independently decoded header. */
+	write(chunk) {
+		let lineStart = 0;
+		for (let newline = chunk.indexOf(10); newline !== -1; newline = chunk.indexOf(10, lineStart)) {
+			const fragment = chunk.subarray(lineStart, newline);
+			let line = fragment;
+			if (this.fragments.length > 0) {
+				if (fragment.length > 0) this.fragments.push(fragment);
+				line = Buffer.concat(this.fragments, this.fragmentBytes + fragment.length);
+				this.fragments = [];
+				this.fragmentBytes = 0;
+			}
+			this.consume(line);
+			lineStart = newline + 1;
+		}
+		if (lineStart < chunk.length) {
+			const fragment = Buffer.from(chunk.subarray(lineStart));
+			this.fragments.push(fragment);
+			this.fragmentBytes += fragment.length;
+		}
+	}
+	/** Refuse a record fragment left by structurally complete Zstandard frames. */
+	assertCompleteFramesEndOnRecord() {
+		if (this.fragments.length > 0) throw new Error("corrupt Zstandard session log: complete frame contains a torn JSONL record");
+	}
+	finish() {
+		return this.restore.finish();
+	}
+	consume(line) {
+		const index = this.rowIndex;
+		this.rowIndex += 1;
+		let row;
+		try {
+			row = parseJson(line.toString("utf8"), `row ${index + 1}`);
+		} catch (error) {
+			this.issue ??= asError(error);
+			return;
+		}
+		if (this.issue !== void 0) {
+			if (typeof row === "object" && row !== null && row.type === "turn/end") throw this.issue;
+			return;
+		}
+		this.restore.decodeRow(row);
+	}
+};
+async function startMigrationStream(headerRecord, sourceVersion, format, validateHistoricalHeader) {
+	const value = parseJson(headerRecord.subarray(0, -1).toString("utf8"), "header line");
+	const version = storedVersion(value);
+	if (version !== sourceVersion) throw new Error(`resolved JSONL source filename identifies v${sourceVersion}, but its header identifies v${version}`);
+	const header = value;
+	const validation = validateHistoricalHeader?.(header);
+	if (validation !== void 0) await validation;
+	return { parser: new MigratingJsonlRows(format.createRestore(header)) };
+}
+async function consumeMigrationBytes(rows, chunks, signal) {
+	signal?.throwIfAborted();
+	let yieldDeadline = node_perf_hooks.performance.now() + MIGRATION_DECODE_YIELD_INTERVAL_MS;
+	for (const bytes of chunks) for (let offset = 0; offset < bytes.length; offset += MIGRATION_WORK_CHUNK_BYTES) {
+		rows.write(bytes.subarray(offset, offset + MIGRATION_WORK_CHUNK_BYTES));
+		if (node_perf_hooks.performance.now() < yieldDeadline) continue;
+		await node_timers_promises.scheduler.yield();
+		signal?.throwIfAborted();
+		yieldDeadline = node_perf_hooks.performance.now() + MIGRATION_DECODE_YIELD_INTERVAL_MS;
+	}
+}
+async function decodeStreamingMigration(bytes, compression, sourceVersion, format, validateHistoricalHeader, signal) {
+	signal?.throwIfAborted();
+	if (compression === "none") {
+		const headerEnd = bytes.indexOf(10);
+		if (headerEnd === -1) throw new Error("empty or header-less session log");
+		const stream = await startMigrationStream(bytes.subarray(0, headerEnd + 1), sourceVersion, format, validateHistoricalHeader);
+		signal?.throwIfAborted();
+		const bodyEnd = bytes.lastIndexOf(10);
+		if (bodyEnd > headerEnd) await consumeMigrationBytes(stream.parser, [bytes.subarray(headerEnd + 1, bodyEnd + 1)], signal);
+		return stream.parser.finish();
+	}
+	const { frames, tornStart } = scanZstdFrames(bytes);
+	if (frames.length === 0) throw new Error("empty or header-less Zstandard session log");
+	const decoder = createZstdFrameDecoder();
+	try {
+		const decoded = decoder.decode(bytes, frames);
+		const first = decoded.next();
+		/* v8 ignore next -- a non-empty structural frame list yields once or throws. */
+		if (first.done) throw new Error("empty or header-less Zstandard session log");
+		assertIndependentHeaderFrame(first.value);
+		const stream = await startMigrationStream(first.value, sourceVersion, format, validateHistoricalHeader);
+		signal?.throwIfAborted();
+		await consumeMigrationBytes(stream.parser, decoded, signal);
+		stream.parser.assertCompleteFramesEndOnRecord();
+		if (tornStart !== void 0) {
+			let recovered = Buffer.alloc(0);
+			try {
+				recovered = await decompressZstdPrefix(bytes.subarray(tornStart));
+			} catch {
+				/* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent. */
+				if (signal?.aborted) signal.throwIfAborted();
+			}
+			signal?.throwIfAborted();
+			const newline = recovered.lastIndexOf(10);
+			if (newline !== -1) await consumeMigrationBytes(stream.parser, [recovered.subarray(0, newline + 1)], signal);
+		}
+		return stream.parser.finish();
+	} finally {
+		decoder.close();
+	}
+}
+/**
+* Read and validate one complete current generation for an isolated verifier.
+* @param path - staged or competing current-generation path.
+* @param compression - configured physical encoding.
+* @param expectedId - Session identity expected in the header.
+* @param expectedEventCount - exact logical event count expected after decoding.
+* @param expectedPrefix - verified migration prefix; an append tail may be present and is not validated.
+* @returns stable physical identity and digest for publication comparison.
+*/
+async function verifyJsonlCurrentGeneration(path, compression, expectedId, expectedEventCount, expectedPrefix) {
+	return defaultGenerationRuntime.verify(path, compression, expectedId, expectedEventCount, expectedPrefix);
+}
+async function verifyCurrentGeneration(path, compression, expectedId, expectedEventCount, fs, expectedPrefix) {
+	const before = await fs.stat(path);
+	const bytes = await fs.readFile(path);
+	const after = await fs.stat(path);
+	if (expectedPrefix !== void 0) {
+		if (bytes.length < expectedPrefix.bytes) throw new Error("target bytes are shorter than the migrated generation");
+		const digest = (0, node_crypto.createHash)("sha256").update(bytes.subarray(0, expectedPrefix.bytes)).digest("hex");
+		if (digest !== expectedPrefix.digest) throw new Error("target bytes do not begin with the migrated generation");
+		return {
+			identity: after,
+			bytes: expectedPrefix.bytes,
+			digest
+		};
+	}
+	if (identity(before) !== identity(after)) throw new Error("current session generation changed during verification");
+	const snapshot = {
+		bytes,
+		identity: after
+	};
+	const generation = decodeCurrentGeneration(snapshot.bytes, compression);
+	(0, _deepseek_ai_dsh_session_persistence.validateStoredEvents)(generation.meta, generation.events, {
+		kind: "jsonl",
+		path
+	});
+	if (generation.meta.id !== expectedId) throw new Error(`current session generation contains id "${generation.meta.id}", expected "${expectedId}"`);
+	if (generation.events.length !== expectedEventCount) throw new Error(`current session generation contains ${generation.events.length} events, expected ${expectedEventCount}`);
+	_deepseek_ai_dsh_session.Session.fromRestore(generation.meta.id, generation.events, generation.meta, generation.inheritedEventCount, "detached");
+	assertCurrentAssistantStreams(generation.events);
+	return {
+		identity: snapshot.identity,
+		bytes: snapshot.bytes.length,
+		digest: (0, node_crypto.createHash)("sha256").update(snapshot.bytes).digest("hex")
+	};
+}
+/** Fully replay embedded streams only inside isolated current-generation verification. */
+function assertCurrentAssistantStreams(events) {
+	for (const [index, event] of events.entries()) {
+		if (event.type !== "assistant/message" && event.type !== "assistant/attempt") continue;
+		const assembler = new _deepseek_ai_dsh_llm.BlockAssembler();
+		let timed;
+		try {
+			timed = (0, _deepseek_ai_dsh_llm.expandAssistantStream)(event.data.stream);
+			for (const member of timed) assembler.push(member.chunk);
+		} catch (error) {
+			throw new Error(`seed ${event.type} at index ${index} has an invalid embedded stream`, { cause: error });
+		}
+		if (event.type === "assistant/attempt" || timed.length === 0) continue;
+		const content = event.data.interrupted === true ? assembler.interruptedBlocks() : assembler.blocks();
+		if (!(0, node_util.isDeepStrictEqual)(event.data.message.content, content)) throw new Error(`seed assistant/message at index ${index} content disagrees with its embedded stream`);
+		if (!(0, node_util.isDeepStrictEqual)(event.data.usage, assembler.usage)) throw new Error(`seed assistant/message at index ${index} usage disagrees with its embedded stream`);
+		if (!(0, node_util.isDeepStrictEqual)(event.data.message.source.replayState, assembler.replayState)) throw new Error(`seed assistant/message at index ${index} replay state disagrees with its embedded stream`);
+	}
+}
+function decodeCurrentGeneration(bytes, compression) {
+	if (compression === "none") {
+		const headerEnd = bytes.indexOf(10);
+		if (headerEnd === -1) throw new Error("empty or header-less session log");
+		const scanner = new SessionLogScanner(bytes.subarray(0, headerEnd + 1), "strict");
+		scanner.write(bytes.subarray(headerEnd + 1));
+		return finishCurrentGenerationScan(scanner);
+	}
+	const { frames, tornStart } = scanZstdFrames(bytes);
+	if (frames.length === 0) throw new Error("empty or header-less Zstandard session log");
+	if (tornStart !== void 0) throw new Error("current session generation has a torn physical tail");
+	const decoder = createZstdFrameDecoder();
+	try {
+		const plaintext = decoder.decode(bytes, frames);
+		const header = plaintext.next();
+		/* v8 ignore next -- a non-empty structural frame list yields once or throws. */
+		if (header.done) throw new Error("empty or header-less Zstandard session log");
+		assertIndependentHeaderFrame(header.value);
+		const scanner = new SessionLogScanner(header.value, "strict");
+		for (const chunk of plaintext) scanner.write(chunk);
+		return finishCurrentGenerationScan(scanner);
+	} finally {
+		decoder.close();
+	}
+}
+function finishCurrentGenerationScan(scanner) {
+	const inputBytes = scanner.checkpoint().inputBytes;
+	const decoded = scanner.finish();
+	if (decoded.committedBytes !== inputBytes) throw new Error("current session generation has a torn physical tail");
+	return decoded;
+}
+function stringifyJson(value, subject) {
+	let text;
+	try {
+		text = JSON.stringify(value);
+	} catch (error) {
+		throw new Error(`${subject} is not lossless JSON`, { cause: error });
+	}
+	if (typeof text !== "string") throw new Error(`${subject} is not lossless JSON`);
+	return text;
+}
+function assertIndependentHeaderFrame(plaintext) {
+	if (plaintext.length === 0 || plaintext.indexOf(10) !== plaintext.length - 1) throw new Error("corrupt Zstandard session log: first frame is not exactly one header line");
+}
+function assertGenerationPaths(sourcePath, sourceVersion, currentPath, currentVersion, compression) {
+	const expectedSource = generationLogFilename(sourceVersion, compression);
+	const expectedCurrent = generationLogFilename(currentVersion, compression);
+	if ((0, node_path.basename)(sourcePath) !== expectedSource) throw new Error(`resolved JSONL source path must end with "${expectedSource}": ${sourcePath}`);
+	if ((0, node_path.basename)(currentPath) !== expectedCurrent) throw new Error(`current JSONL generation path must end with "${expectedCurrent}": ${currentPath}`);
+	if ((0, node_path.dirname)(sourcePath) !== (0, node_path.dirname)(currentPath)) throw new Error("source and current JSONL generations must share one Session directory");
+	return logSuffix(compression);
+}
+async function syncDirectory(path, internals) {
+	/* v8 ignore next -- Windows namespace operations request write-through directly. */
+	if (internals.platform === "win32") return;
+	const handle = await internals.fs.open(path, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+/** Produce bounded JSONL chunks while yielding between main-thread encoding slices. */
+async function* encodeMigrationRows(artifact, format, signal) {
+	signal?.throwIfAborted();
+	let lines = [];
+	let bytes = 0;
+	for (const value of artifact.events) {
+		const line = `${stringifyJson(format.encodeEvent(value), `migrated Session event ${value.seq}`)}\n`;
+		const lineBytes = Buffer.byteLength(line);
+		if (bytes > 0 && bytes + lineBytes > MIGRATION_WORK_CHUNK_BYTES) {
+			yield Buffer.from(lines.join(""));
+			await node_timers_promises.scheduler.yield();
+			signal?.throwIfAborted();
+			lines = [];
+			bytes = 0;
+		}
+		lines.push(line);
+		bytes += lineBytes;
+	}
+	yield Buffer.from(lines.join(""));
+}
+async function writeMigrationChunks(chunks, write) {
+	let pending = [];
+	let bytes = 0;
+	for await (const chunk of chunks) {
+		pending.push(chunk);
+		bytes += chunk.length;
+		if (bytes < MIGRATION_WRITE_CHUNK_BYTES) continue;
+		await write(pending.length === 1 ? pending[0] : Buffer.concat(pending, bytes));
+		pending = [];
+		bytes = 0;
+	}
+	if (bytes > 0) await write(pending.length === 1 ? pending[0] : Buffer.concat(pending, bytes));
+}
+/** Encode directly into one synced stage without a whole-artifact row or byte buffer. */
+async function writeSyncedTemp(currentPath, suffix, compression, artifact, format, signal, internals) {
+	signal?.throwIfAborted();
+	let path;
+	let handle;
+	for (;;) {
+		path = (0, node_path.join)((0, node_path.dirname)(currentPath), `session.migration.${internals.randomToken()}${suffix}.tmp`);
+		try {
+			handle = await internals.fs.open(path, "wx", 384);
+			break;
+		} catch (error) {
+			if (isEEXIST(error)) continue;
+			throw error;
+		}
+	}
+	const hash = (0, node_crypto.createHash)("sha256");
+	let bytes = 0;
+	const write = async (chunk) => {
+		await handle.writeFile(chunk);
+		hash.update(chunk);
+		bytes += chunk.length;
+	};
+	let failure;
+	try {
+		const headerValue = format.encodeHeader(artifact.header, artifact.inheritedEventCount);
+		const header = Buffer.from(`${stringifyJson(headerValue, "migrated session header")}\n`);
+		await write(compression === "zstd" ? await compressZstdFrame(header) : header);
+		if (artifact.events.length > 0) {
+			const rows = encodeMigrationRows(artifact, format, signal);
+			if (compression === "none") await writeMigrationChunks(rows, write);
+			else await new Promise((resolve, reject) => {
+				(0, node_stream.pipeline)(node_stream.Readable.from(rows, {
+					objectMode: false,
+					highWaterMark: MIGRATION_WORK_CHUNK_BYTES
+				}), (0, node_zlib.createZstdCompress)(ZSTD_CHECKSUM_OPTIONS), async (source) => {
+					await writeMigrationChunks(source, write);
+				}, (error) => {
+					if (error instanceof Error) reject(error);
+					else resolve();
+				});
+			});
+		}
+		signal?.throwIfAborted();
+		await handle.sync();
+	} catch (error) {
+		failure = error;
+	}
+	try {
+		await handle.close();
+	} catch (error) {
+		failure = failure === void 0 ? error : new AggregateError([failure, error], `failed to write and close migration stage "${path}"`);
+	}
+	if (failure !== void 0) {
+		const writeError = failure instanceof Error ? failure : new Error("migration stage write failed with a non-Error rejection", { cause: failure });
+		await removeTemporary(path, writeError, internals);
+		throw writeError;
+	}
+	return {
+		path,
+		bytes,
+		digest: hash.digest("hex")
+	};
+}
+/** Remove one temporary file without hiding the operation failure that made it disposable. */
+async function removeTemporary(path, primaryFailure, internals) {
+	try {
+		await internals.fs.rm(path);
+	} catch (cleanupFailure) {
+		throw new AggregateError([primaryFailure, cleanupFailure], `failed to clean migration temporary "${path}" after an earlier failure`);
+	}
+}
+/** Remove a redundant stage after the target has been validated as committed. */
+async function removeCommittedTemporary(path, internals) {
+	try {
+		await internals.fs.rm(path);
+	} catch {}
+}
+async function publishCurrentExclusive(staged, currentPath, internals) {
+	if (internals.platform === "win32") try {
+		await internals.publishNewWin32(staged, currentPath);
+		return true;
+	} catch (error) {
+		/* v8 ignore else -- native helper tests own non-collision Win32 failures. */
+		if (isEEXIST(error)) return false;
+		/* v8 ignore next -- the filesystem error is already complete. */
+		throw error;
+	}
+	try {
+		await internals.fs.link(staged, currentPath);
+	} catch (error) {
+		/* v8 ignore else -- a non-collision filesystem error propagates unchanged. */
+		if (isEEXIST(error)) return false;
+		/* v8 ignore next -- the filesystem error is already complete. */
+		throw error;
+	}
+	await syncDirectory((0, node_path.dirname)(currentPath), internals);
+	return true;
+}
+function asError(error) {
+	return error instanceof Error ? error : new Error("current-generation validation failed with a non-Error rejection", { cause: error });
+}
+async function inspectExpectedCurrent(currentPath, internals, inspect) {
+	try {
+		const expectedName = (0, node_path.basename)(currentPath);
+		const names = await internals.fs.readdir((0, node_path.dirname)(currentPath));
+		if (!names.includes(expectedName)) {
+			const noncanonical = names.find((name) => name.toLowerCase() === expectedName.toLowerCase());
+			if (noncanonical !== void 0) throw new Error(`target resolves to noncanonical directory entry "${noncanonical}"`);
+		}
+		const info = await internals.fs.lstat(currentPath);
+		if (info.isSymbolicLink() || !info.isFile()) throw new Error(`target is a ${info.isSymbolicLink() ? "symbolic link" : "non-regular file"}`);
+		return await inspect();
+	} catch (error) {
+		if (isErrnoException(error)) throw error;
+		throw new JsonlGenerationTargetConflictError(currentPath, asError(error));
+	}
+}
+function withOverrides(overrides) {
+	return {
+		...defaultInternals,
+		...overrides,
+		fs: {
+			...defaultFileSystem,
+			...overrides.fs
+		}
+	};
+}
+async function publishPreparedMigration(options, suffix, artifact, sourceIdentity, internals) {
+	await node_timers_promises.scheduler.yield();
+	const { sourcePath, currentPath, compression, verifyCurrentFile } = options;
+	const eventCount = artifact.events.length;
+	let staged = await writeSyncedTemp(currentPath, suffix, compression, artifact, options.format, void 0, internals);
+	try {
+		const verifiedStage = await verifyCurrentFile(staged.path, compression, artifact.header.id, eventCount);
+		if (verifiedStage.bytes !== staged.bytes || verifiedStage.digest !== staged.digest) throw new Error("staged session generation changed during verification");
+		await internals.barrier("before-source-check", 1);
+		if (identity(await internals.fs.stat(sourcePath)) !== identity(sourceIdentity)) throw new JsonlGenerationSourceChangedError(sourcePath);
+		const published = await publishCurrentExclusive(staged.path, currentPath, internals);
+		if (published && internals.platform === "win32") staged = {
+			...staged,
+			path: ""
+		};
+		await internals.barrier("after-publication", 1);
+		let currentIdentity;
+		if (published) {
+			if (staged.path !== "") {
+				await removeCommittedTemporary(staged.path, internals);
+				staged = {
+					...staged,
+					path: ""
+				};
+			}
+			currentIdentity = await internals.fs.stat(currentPath);
+		} else {
+			currentIdentity = (await inspectExpectedCurrent(currentPath, internals, async () => {
+				const candidate = await verifyCurrentFile(currentPath, compression, artifact.header.id, eventCount, staged);
+				if (candidate.bytes !== staged.bytes || candidate.digest !== staged.digest) throw new Error("target bytes differ from the migrated generation");
+				return candidate;
+			})).identity;
+			await removeCommittedTemporary(staged.path, internals);
+			staged = {
+				...staged,
+				path: ""
+			};
+		}
+		return currentIdentity;
+	} catch (error) {
+		if (staged.path !== "") await removeTemporary(staged.path, error, internals);
+		throw error;
+	}
+}
+async function prepareMigration(options, internals) {
+	const { sourcePath, sourceVersion, currentPath, compression, format, signal } = options;
+	const suffix = assertGenerationPaths(sourcePath, sourceVersion, currentPath, format.currentVersion, compression);
+	if (sourceVersion >= format.currentVersion) throw new Error(`migration preparation requires a historical source, got v${sourceVersion}`);
+	const source = await readStableSnapshot(sourcePath, signal, internals.fs);
+	let artifact;
+	try {
+		artifact = await decodeStreamingMigration(source.bytes, compression, sourceVersion, format, options.validateHistoricalHeader, signal);
+	} catch (error) {
+		if (format.isUnsupportedMigrationError?.(error) === true) throw new JsonlGenerationUnsupportedMigrationError(sourceVersion, error);
+		throw error;
+	}
+	if (artifact.header.version !== format.currentVersion) throw new Error(`format migration returned v${artifact.header.version}, expected v${format.currentVersion}`);
+	const sourceIdentity = source.identity;
+	let publication;
+	return {
+		sourceIdentity,
+		artifact,
+		publish() {
+			if (publication === void 0) publication = publishPreparedMigration(options, suffix, artifact, sourceIdentity, internals);
+			return publication;
+		}
+	};
+}
+/**
+* Create one generation runtime with fixed filesystem and publication dependencies.
+* @param overrides - deterministic filesystem, platform, and race dependencies.
+* @returns bound generation operations.
+*/
+function createJsonlGenerationRuntime(overrides = {}) {
+	const internals = withOverrides(overrides);
+	return {
+		readStable: (path, signal) => readStableSnapshot(path, signal, internals.fs),
+		prepare: (options) => prepareMigration(options, internals),
+		verify: (path, compression, expectedId, expectedEventCount, expectedPrefix) => verifyCurrentGeneration(path, compression, expectedId, expectedEventCount, internals.fs, expectedPrefix)
+	};
+}
+const defaultGenerationRuntime = createJsonlGenerationRuntime();
+//#endregion
+//#region lib/types/worker.js
+/** Worker entry for current-generation physical and logical verification. */
+function parseRequest(value) {
+	if (typeof value !== "object" || value === null) throw new Error("migration verifier request must be an object");
+	const request = value;
+	if (typeof request.path !== "string" || request.compression !== "none" && request.compression !== "zstd" || typeof request.expectedId !== "string" || !Number.isSafeInteger(request.expectedEventCount) || request.expectedEventCount < 0 || request.expectedPrefix !== void 0 && (!Number.isSafeInteger(request.expectedPrefix.bytes) || request.expectedPrefix.bytes < 0 || !/^[0-9a-f]{64}$/.test(request.expectedPrefix.digest))) throw new Error("migration verifier request is malformed");
+	return request;
+}
+if (node_worker_threads.parentPort === null) throw new Error("migration verifier requires a parent port");
+const port = node_worker_threads.parentPort;
+const request = parseRequest(node_worker_threads.workerData);
+async function verify() {
+	try {
+		const result = await verifyJsonlCurrentGeneration(request.path, request.compression, request.expectedId, request.expectedEventCount, request.expectedPrefix);
+		port.postMessage({
+			ok: true,
+			result
+		});
+	} catch (error) {
+		const failure = error instanceof Error ? error : new Error(String(error));
+		port.postMessage({
+			ok: false,
+			message: failure.message,
+			stack: failure.stack
+		});
+	} finally {
+		port.close();
+	}
+}
+verify();
+//#endregion