wowdump 0.0.0 → 0.2.0

package/dist/broker-gateway.js

@@ -0,0 +1,447 @@
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BrokerBootstrapCoordinator, WindowsBrokerBootstrapPlatform } from "./broker-client.js";
+import { BROKER_MANAGED_COMMAND } from "./frida-runtime.js";
+import { BrokerClient, NamedPipeClientTransport } from "./broker-client.js";
+import { BrokerProtocolError, canonicalArtifactRoot, FrameDecoder, pipeNameForSid } from "./broker-protocol.js";
+const FOCUS_READ_OPERATIONS = new Set([
+    "wow_focus_read",
+    "wow_watch_read",
+    "wow_focus_status",
+    "wow_watch_status"
+]);
+/** MCP-side Frida executor. It never imports the Frida runtime implementation. */
+export class BrokerFridaGateway {
+    clientId = randomUUID();
+    client;
+    transport;
+    started = false;
+    scriptTargets = new Map();
+    sessionTargets = new Map();
+    pipeName;
+    requestTimeoutMs;
+    connectTimeoutMs;
+    options;
+    activeLauncher;
+    sid;
+    artifactRoot;
+    connectPromise;
+    closePromise;
+    releaseReceipt;
+    constructor(options = {}) {
+        this.options = options;
+        this.sid = options.sid ?? process.env.WOW_BROKER_SID ?? defaultBrokerSid();
+        this.pipeName = options.pipeName ?? pipeNameForSid(this.sid);
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.connectTimeoutMs = options.connectTimeoutMs ?? 10_000;
+        this.artifactRoot = canonicalArtifactRoot(options.artifactDir ?? process.env.WOWDUMP_RUNTIME_DIR ?? defaultRuntimeRoot());
+    }
+    async execute(request, context) {
+        const remembered = typeof request.scriptId === "string"
+            ? this.scriptTargets.get(request.scriptId)
+            : typeof request.sessionId === "string" ? this.sessionTargets.get(request.sessionId) : undefined;
+        const pid = context?.pid ?? request.pid ?? remembered?.pid ?? null;
+        const buildKey = context?.buildKey ?? request.buildKey ?? remembered?.buildKey ?? null;
+        const requestId = suppliedRequestId(request) ?? randomUUID();
+        const managed = request[BROKER_MANAGED_COMMAND];
+        const wireRequest = { ...request };
+        const rememberedResourceId = remembered?.resourceId;
+        if (rememberedResourceId && !wireRequest.resourceId && (request.operation === "detach" || request.operation === "script_unload"))
+            wireRequest.resourceId = rememberedResourceId;
+        if (managed)
+            wireRequest.mutation = managedMutationContract(this.clientId, requestId, pid, buildKey, managed.purpose, managed.irreversibleReason);
+        else if (isRecord(request.mutation))
+            wireRequest.mutation = bindMutation(request.mutation, this.clientId, requestId, pid, buildKey);
+        if (isRecord(request.launch))
+            wireRequest.launch = bindLaunch(request.launch, this.clientId, requestId);
+        const effectiveContext = context ?? (remembered ? {
+            pid: remembered.pid ?? undefined,
+            buildKey: remembered.buildKey ?? undefined,
+            executable: remembered.executable,
+            processStartTime: remembered.processStartTime,
+            moduleBase: remembered.moduleBase,
+            moduleIdentity: remembered.moduleIdentity
+        } : undefined);
+        const payload = {
+            request: jsonSafe(wireRequest),
+            context: effectiveContext ? jsonSafe({
+                pid: effectiveContext.pid,
+                buildKey: effectiveContext.buildKey,
+                flavor: effectiveContext.flavor,
+                executable: effectiveContext.executable,
+                processStartTime: effectiveContext.processStartTime,
+                moduleBase: effectiveContext.moduleBase,
+                moduleIdentity: effectiveContext.moduleIdentity
+            }) : null
+        };
+        const result = await this.requestWithRecovery("frida_command", {
+            requestId,
+            pid,
+            buildKey,
+            payload,
+            timeoutMs: request.timeoutMs ?? this.requestTimeoutMs
+        }, isMutatingFridaRequest(request));
+        const normalized = (isRecord(result) ? result : { value: result });
+        const identity = isRecord(normalized.identity) ? normalized.identity : {};
+        const identityFields = {
+            executable: typeof identity.executable === "string" ? identity.executable : typeof normalized.executable === "string" ? normalized.executable : undefined,
+            processStartTime: typeof identity.processStartTime === "string" ? identity.processStartTime : typeof normalized.processStartTime === "string" ? normalized.processStartTime : undefined,
+            moduleBase: typeof identity.moduleBase === "string" ? identity.moduleBase : typeof normalized.moduleBase === "string" ? normalized.moduleBase : undefined,
+            moduleIdentity: typeof identity.moduleIdentity === "string" ? identity.moduleIdentity : typeof normalized.moduleIdentity === "string" ? normalized.moduleIdentity : undefined
+        };
+        if (request.operation === "attach" && typeof normalized.sessionId === "string")
+            this.sessionTargets.set(normalized.sessionId, { pid, buildKey, resourceId: typeof normalized.resourceId === "string" ? normalized.resourceId : undefined, ...identityFields });
+        if (request.operation === "script_load" && typeof normalized.scriptId === "string")
+            this.scriptTargets.set(normalized.scriptId, { pid, buildKey, resourceId: typeof normalized.resourceId === "string" ? normalized.resourceId : undefined, ...identityFields });
+        if (request.operation === "script_unload" && typeof request.scriptId === "string")
+            this.scriptTargets.delete(request.scriptId);
+        if (request.operation === "detach" && typeof request.sessionId === "string")
+            this.sessionTargets.delete(request.sessionId);
+        return normalized;
+    }
+    async invoke(operation, input = {}) {
+        const pid = Number(input.pid);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new BrokerProtocolError("PID_REQUIRED", `${operation} requires a positive pid`);
+        const buildKey = typeof input.buildKey === "string" && input.buildKey.trim() ? input.buildKey : undefined;
+        if (!buildKey)
+            throw new BrokerProtocolError("PID_BUILD_MISMATCH", `${operation} requires buildKey`);
+        const requestId = randomUUID();
+        const result = await this.requestWithRecovery(operation, {
+            requestId,
+            pid,
+            buildKey,
+            payload: jsonSafe(input),
+            timeoutMs: typeof input.durationMs === "number"
+                ? Math.max(this.requestTimeoutMs, Math.min(input.durationMs + 10_000, 86_410_000))
+                : this.requestTimeoutMs
+        }, !FOCUS_READ_OPERATIONS.has(operation));
+        if (!isRecord(result))
+            return { value: result };
+        return result;
+    }
+    async status() {
+        try {
+            await this.ensureConnected(false);
+            const result = await this.client.request("broker_status", { payload: {}, timeoutMs: this.requestTimeoutMs });
+            this.validateReadyResult(result);
+            return isRecord(result) ? result : { status: result };
+        }
+        catch (error) {
+            return { status: "stopped", error: errorText(error), pipeName: this.pipeName };
+        }
+    }
+    async start() {
+        await this.ensureConnected(true);
+        return { status: "ready", pipeName: this.pipeName, clientId: this.clientId, artifactRoot: this.artifactRoot };
+    }
+    async reconnect() {
+        await this.closeTransport();
+        await this.ensureConnected(true);
+        return { status: "ready", pipeName: this.pipeName, clientId: this.clientId, artifactRoot: this.artifactRoot };
+    }
+    async close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closePromise = this.closeInternal().finally(() => { this.closePromise = undefined; });
+        return this.closePromise;
+    }
+    get brokerPipeName() { return this.pipeName; }
+    get brokerClientId() { return this.clientId; }
+    get lastReleaseReceipt() { return this.releaseReceipt; }
+    async requestWithRecovery(operation, options, mutationLike) {
+        await this.ensureConnected(true);
+        try {
+            return await this.client.request(operation, options);
+        }
+        catch (error) {
+            if (!isRecoverableTransportError(error))
+                throw error;
+            await this.closeTransport();
+            await this.ensureConnected(true);
+            if (!mutationLike)
+                return this.client.request(operation, options);
+            const status = await this.client.request("request_status", {
+                requestId: randomUUID(),
+                pid: options.pid,
+                buildKey: options.buildKey,
+                payload: { requestId: options.requestId },
+                timeoutMs: options.timeoutMs
+            });
+            if (!isRecord(status))
+                throw new BrokerProtocolError("MUTATION_OUTCOME_UNKNOWN", `request ${options.requestId} has no durable outcome`);
+            const state = typeof status.state === "string" ? status.state : "outcome_unknown";
+            if ((state === "completed" || state === "rolled_back") && Object.hasOwn(status, "result"))
+                return status.result;
+            if (state === "outcome_unknown")
+                throw new BrokerProtocolError("MUTATION_OUTCOME_UNKNOWN", `request ${options.requestId} outcome is unknown`, "Inspect request_status evidence before issuing a new mutation.");
+            throw new BrokerProtocolError("REQUEST_TIMEOUT", `request ${options.requestId} remains ${state}`, "Query request_status again; do not replay the mutation.");
+        }
+    }
+    async ensureConnected(autoStart) {
+        if (this.client)
+            return;
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.connectPromise = this.connectInternal(autoStart).finally(() => { this.connectPromise = undefined; });
+        return this.connectPromise;
+    }
+    async connectInternal(autoStart) {
+        if (this.client)
+            return;
+        const transportFactory = this.options.transportFactory ?? (pipe => new NamedPipeClientTransport(pipe));
+        let transport = transportFactory(this.pipeName);
+        try {
+            const statusFrame = await withTimeout(transport.request(encodeStatusFrame(this.clientId), this.connectTimeoutMs), this.connectTimeoutMs);
+            this.validateReadyFrame(statusFrame);
+            this.transport = transport;
+            this.client = new BrokerClient(transport, this.clientId);
+            this.started = true;
+            return;
+        }
+        catch (firstError) {
+            await transport.close().catch(() => undefined);
+            if (firstError instanceof BrokerProtocolError && firstError.code === "BROKER_ARTIFACT_ROOT_MISMATCH")
+                throw firstError;
+            if (!autoStart)
+                throw firstError;
+            const launcher = this.options.launcher
+                ?? (process.env.WOW_BROKER_TEST_FIXTURE === "1"
+                    ? new ProcessBrokerLauncher(this.options)
+                    : new CoordinatorBrokerLauncher(this.options, this.sid));
+            this.activeLauncher = launcher;
+            try {
+                await launcher.start(this.pipeName);
+            }
+            catch (error) {
+                await launcher.stop().catch(() => undefined);
+                this.activeLauncher = undefined;
+                throw error;
+            }
+            const deadline = Date.now() + this.connectTimeoutMs;
+            while (Date.now() < deadline) {
+                transport = transportFactory(this.pipeName);
+                try {
+                    const statusFrame = await withTimeout(transport.request(encodeStatusFrame(this.clientId), this.connectTimeoutMs), 1_000);
+                    this.validateReadyFrame(statusFrame);
+                    this.transport = transport;
+                    this.client = new BrokerClient(transport, this.clientId);
+                    this.started = true;
+                    return;
+                }
+                catch (error) {
+                    await transport.close().catch(() => undefined);
+                    if (error instanceof BrokerProtocolError && error.code === "BROKER_ARTIFACT_ROOT_MISMATCH")
+                        throw error;
+                    await delay(50);
+                }
+            }
+            throw new Error(`Broker did not become ready on ${this.pipeName}: ${errorText(firstError)}`);
+        }
+    }
+    async closeInternal() {
+        await this.connectPromise?.catch(() => undefined);
+        try {
+            if (this.client) {
+                const value = await this.client.request("client_release", { payload: {}, timeoutMs: Math.min(this.requestTimeoutMs, 5_000) });
+                if (!isRecord(value) || value.released !== true || value.clientId !== this.clientId || value.remainingResourceRefs !== 0 || !Array.isArray(value.residualResourceIds) || value.residualResourceIds.length !== 0) {
+                    throw new BrokerProtocolError("CLEANUP_TIMEOUT", `Broker client release did not prove zero references: ${JSON.stringify(value)}`, "Inspect Broker resources and retry client release.");
+                }
+                this.releaseReceipt = { ...value };
+            }
+        }
+        finally {
+            await this.closeTransport();
+            this.scriptTargets.clear();
+            this.sessionTargets.clear();
+            await this.activeLauncher?.stop().catch(() => undefined);
+            this.activeLauncher = undefined;
+        }
+    }
+    async closeTransport() {
+        await this.transport?.close().catch(() => undefined);
+        this.transport = undefined;
+        this.client = undefined;
+        this.started = false;
+    }
+    validateReadyFrame(frame) {
+        const response = new FrameDecoder().push(frame)[0];
+        if (!response?.ok)
+            throw new BrokerProtocolError("BROKER_ARTIFACT_ROOT_MISMATCH", response?.error?.message ?? "Broker ready identity is unavailable", "Restart Broker with the configured artifact root.");
+        this.validateReadyResult(response.result);
+    }
+    validateReadyResult(value) {
+        if (!isRecord(value) || value.status !== "ready" || typeof value.artifactRoot !== "string") {
+            throw new BrokerProtocolError("BROKER_ARTIFACT_ROOT_MISMATCH", "Broker status omitted canonical artifactRoot", "Restart Broker with the configured artifact root.");
+        }
+        let actual;
+        try {
+            actual = canonicalArtifactRoot(value.artifactRoot);
+        }
+        catch {
+            actual = "";
+        }
+        if (actual !== this.artifactRoot)
+            throw new BrokerProtocolError("BROKER_ARTIFACT_ROOT_MISMATCH", `Broker artifact root mismatch: expected ${this.artifactRoot}, got ${value.artifactRoot}`, "Connect to the Broker serving the configured artifact root.");
+    }
+}
+/** Bootstrap-coordinator launcher used by production MCP/collector entries. */
+export class CoordinatorBrokerLauncher {
+    options;
+    sid;
+    coordinator;
+    artifactRoot;
+    ready;
+    constructor(options, sid) {
+        this.options = options;
+        this.sid = sid;
+        this.coordinator = new BrokerBootstrapCoordinator(options.bootstrapPlatform ?? new WindowsBrokerBootstrapPlatform());
+        this.artifactRoot = canonicalArtifactRoot(options.artifactDir ?? process.env.WOWDUMP_RUNTIME_DIR ?? defaultRuntimeRoot());
+    }
+    async start(pipeName) {
+        const { entry, workdir } = resolveBrokerLaunchPaths(this.options);
+        const ready = await this.coordinator.start({
+            sid: this.sid,
+            pipeName,
+            executable: process.execPath,
+            workdir,
+            artifactRoot: this.artifactRoot,
+            argv: [entry],
+            timeoutMs: this.options.connectTimeoutMs
+        });
+        this.ready = ready;
+    }
+    async stop() {
+        // Broker shutdown is requested by client_release; elevated children are
+        // intentionally not force-killed from the MCP process.
+        this.ready = undefined;
+    }
+    get readyIdentity() { return this.ready; }
+}
+/** Explicit legacy launcher kept for injected test fixtures only. */
+export class ProcessBrokerLauncher {
+    options;
+    child;
+    artifactRoot;
+    constructor(options) {
+        this.options = options;
+        this.artifactRoot = canonicalArtifactRoot(options.artifactDir ?? process.env.WOWDUMP_RUNTIME_DIR ?? defaultRuntimeRoot());
+    }
+    async start(pipeName) {
+        if (this.child && !this.child.killed)
+            return;
+        const { entry, workdir } = resolveBrokerLaunchPaths(this.options);
+        if (!existsSync(entry))
+            throw new Error(`Broker executable is missing: ${entry}`);
+        this.child = spawn(process.execPath, [entry, "--pipe", pipeName], {
+            cwd: workdir,
+            env: { ...process.env, WOWDUMP_RUNTIME_DIR: this.artifactRoot, WOW_BROKER_ARTIFACT_ROOT: this.artifactRoot },
+            stdio: ["ignore", "ignore", "pipe"],
+            windowsHide: true,
+            detached: false
+        });
+        this.child.stderr?.on("data", chunk => process.stderr.write(`broker: ${String(chunk)}`));
+        await new Promise((resolvePromise, reject) => {
+            const child = this.child;
+            const onError = (error) => { child.off("exit", onExit); reject(error); };
+            const onExit = (code) => { child.off("error", onError); if (code !== null && code !== 0)
+                reject(new Error(`Broker exited during startup (${code})`)); };
+            child.once("error", onError);
+            child.once("exit", onExit);
+            setTimeout(() => { child.off("error", onError); child.off("exit", onExit); resolvePromise(); }, 100);
+        });
+    }
+    async stop() {
+        const child = this.child;
+        this.child = undefined;
+        if (!child || child.killed)
+            return;
+        child.kill();
+        await new Promise(resolvePromise => child.once("exit", () => resolvePromise()));
+    }
+}
+export function resolveBrokerLaunchPaths(options = {}) {
+    const moduleDistRoot = dirname(fileURLToPath(import.meta.url));
+    const workdir = options.brokerWorkdir
+        ? resolve(options.brokerWorkdir)
+        : moduleDistRoot;
+    const configuredEntry = options.brokerEntry ?? "broker-main.js";
+    const entry = isAbsolute(configuredEntry)
+        ? configuredEntry
+        : resolve(workdir, configuredEntry);
+    return { entry, workdir };
+}
+function encodeStatusFrame(clientId) {
+    // Imported lazily to keep the gateway's public surface small.
+    const body = Buffer.from(JSON.stringify({ schemaVersion: 1, protocolVersion: "2026-07-28", requestId: randomUUID(), clientId, operation: "broker_status", pid: null, buildKey: null, payload: {} }), "utf8");
+    const frame = Buffer.allocUnsafe(body.length + 4);
+    frame.writeUInt32LE(body.length, 0);
+    body.copy(frame, 4);
+    return frame;
+}
+function jsonSafe(value) {
+    return JSON.parse(JSON.stringify(value, (_key, child) => typeof child === "bigint" ? child.toString() : child === undefined ? null : child));
+}
+function isRecord(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function errorText(error) { return error instanceof Error ? error.message : String(error); }
+function isRecoverableTransportError(error) {
+    return !(error instanceof BrokerProtocolError) || error.code === "REQUEST_TIMEOUT" || error.code === "BROKER_STOPPED";
+}
+function isMutatingFridaRequest(request) {
+    return request.operation === "spawn" || isRecord(request.mutation) || isRecord(request.launch) || [
+        "write_memory", "protect_memory", "resume", "kill", "script_load", "script_unload", "script_call", "host_call"
+    ].includes(request.operation ?? "");
+}
+function managedMutationContract(clientId, requestId, pid, buildKey, purpose, irreversibleReason) {
+    return {
+        mutationPlanId: `broker-managed:${requestId}`,
+        confirmation: { clientId, confirmedAt: new Date().toISOString(), nonce: randomUUID(), irreversibleAcknowledged: true },
+        target: { pid, buildKey },
+        expectedEffect: {},
+        rollback: { mode: "irreversible", irreversibleReason: irreversibleReason ?? "Broker-managed observation instrumentation has resource-ledger cleanup evidence." },
+        evidencePlan: { before: {}, after: {}, rollback: {} },
+        audit: { actor: "broker-managed-mcp", reason: purpose, requestId }
+    };
+}
+function suppliedRequestId(request) {
+    return typeof request.requestId === "string" && request.requestId.trim() ? request.requestId : undefined;
+}
+function bindMutation(value, clientId, requestId, pid, buildKey) {
+    const confirmation = isRecord(value.confirmation) ? value.confirmation : {};
+    const audit = isRecord(value.audit) ? value.audit : {};
+    return { ...value, confirmation: { ...confirmation, clientId }, audit: { ...audit, requestId }, target: { pid, buildKey } };
+}
+function bindLaunch(value, clientId, requestId) {
+    const confirmation = isRecord(value.confirmation) ? value.confirmation : {};
+    const audit = isRecord(value.audit) ? value.audit : {};
+    return { ...value, confirmation: { ...confirmation, clientId }, audit: { ...audit, requestId } };
+}
+function delay(ms) { return new Promise(resolvePromise => setTimeout(resolvePromise, ms)); }
+function defaultRuntimeRoot() { return join(process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "wowdump"); }
+function defaultBrokerSid() {
+    if (process.platform !== "win32")
+        return process.env.USERNAME ?? process.env.USER ?? "default";
+    try {
+        const output = execFileSync("whoami.exe", ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", windowsHide: true });
+        const sid = output.match(/S-\d-(?:\d+-)+\d+/i)?.[0];
+        if (sid)
+            return sid.toUpperCase();
+    }
+    catch { /* reported as a configuration error below */ }
+    throw new Error("Unable to resolve the current Windows SID for Broker pipe isolation; set WOW_BROKER_SID explicitly.");
+}
+async function withTimeout(promise, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Broker connection timeout")), timeoutMs); })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/broker-ledger.js

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, truncateSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+const LEDGER_STATES = new Set([
+    "validated", "before_captured", "executing", "executed", "after_validated", "completed",
+    "before_failed", "rollback_started", "rollback_executed", "rollback_validated", "rolled_back",
+    "rollback_unavailable", "rollback_failed", "irreversible_failed", "outcome_unknown"
+]);
+const TERMINAL_STATES = new Set([
+    "completed", "before_failed", "rolled_back", "rollback_unavailable", "rollback_failed",
+    "irreversible_failed", "outcome_unknown"
+]);
+export class FileBrokerLedgerStore {
+    path;
+    fd;
+    closed = false;
+    constructor(path) {
+        this.path = path;
+        mkdirSync(dirname(path), { recursive: true });
+        this.fd = openSync(path, "a+", 0o600);
+    }
+    load() {
+        try {
+            const entries = new Map();
+            if (!existsSync(this.path))
+                return entries;
+            const content = readFileSync(this.path);
+            const hasTerminalNewline = content.length === 0 || content.at(-1) === 0x0a;
+            const lines = content.toString("utf8").split("\n");
+            for (let index = 0; index < lines.length; index += 1) {
+                const line = lines[index];
+                if (!line)
+                    continue;
+                let record;
+                try {
+                    record = JSON.parse(line);
+                }
+                catch (error) {
+                    const isFinalTail = index === lines.length - 1 && !hasTerminalNewline;
+                    if (isFinalTail) {
+                        const tailOffset = content.lastIndexOf(0x0a) + 1;
+                        const tail = content.subarray(tailOffset);
+                        if (isIncompleteJsonTail(tail)) {
+                            quarantineTail(this.path, tailOffset, tail);
+                            truncateSync(this.path, tailOffset);
+                            fsyncSync(this.fd);
+                            return entries;
+                        }
+                    }
+                    throw new Error(`invalid Broker ledger JSON at line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                if (record.schemaVersion !== 1 || (record.kind !== "upsert" && record.kind !== "delete")) {
+                    throw new Error(`invalid Broker ledger record at line ${index + 1}`);
+                }
+                if (record.kind === "delete") {
+                    if (typeof record.requestId !== "string")
+                        throw new Error(`invalid Broker ledger delete at line ${index + 1}`);
+                    entries.delete(record.requestId);
+                    continue;
+                }
+                const candidateRequestId = record.entry && typeof record.entry === "object" && typeof record.entry.requestId === "string"
+                    ? record.entry.requestId
+                    : undefined;
+                const prior = candidateRequestId === undefined ? undefined : entries.get(candidateRequestId);
+                if (prior && !extendsHistory(prior, record.entry)) {
+                    throw new Error(`non-monotonic Broker ledger history at line ${index + 1}`);
+                }
+                validateEntry(record.entry, index + 1);
+                entries.set(record.entry.requestId, structuredClone(record.entry));
+            }
+            return entries;
+        }
+        catch (error) {
+            this.close();
+            throw error;
+        }
+    }
+    persist(entry) {
+        this.append({ schemaVersion: 1, kind: "upsert", entry });
+    }
+    remove(requestId) {
+        this.append({ schemaVersion: 1, kind: "delete", requestId });
+    }
+    close() {
+        if (this.closed)
+            return;
+        closeSync(this.fd);
+        this.closed = true;
+    }
+    append(record) {
+        const bytes = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+        // One append syscall keeps records indivisible when callers converge on the same ledger.
+        const written = writeSync(this.fd, bytes, 0, bytes.length);
+        if (written !== bytes.length)
+            throw new Error(`short Broker ledger append: wrote ${written} of ${bytes.length} bytes`);
+        fsyncSync(this.fd);
+    }
+}
+function quarantineTail(path, byteOffset, tail) {
+    const sha256 = createHash("sha256").update(tail).digest("hex");
+    const quarantinePath = `${path}.tail-${sha256}.quarantine.json`;
+    const evidence = Buffer.from(`${JSON.stringify({
+        schemaVersion: 1,
+        kind: "broker-ledger-incomplete-tail",
+        sourcePath: path,
+        byteOffset,
+        bytes: tail.length,
+        sha256,
+        encoding: "base64",
+        data: tail.toString("base64")
+    })}\n`, "utf8");
+    if (existsSync(quarantinePath)) {
+        if (!readFileSync(quarantinePath).equals(evidence))
+            throw new Error(`Broker ledger quarantine conflict: ${quarantinePath}`);
+        return;
+    }
+    const fd = openSync(quarantinePath, "wx", 0o600);
+    try {
+        let offset = 0;
+        while (offset < evidence.length)
+            offset += writeSync(fd, evidence, offset, evidence.length - offset);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function isIncompleteJsonTail(tail) {
+    const text = tail.toString("utf8").trimStart();
+    if (!text.startsWith("{"))
+        return false;
+    const stack = [];
+    let inString = false;
+    let escaped = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const character = text[index];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (character === '"')
+            inString = true;
+        else if (character === "{" || character === "[")
+            stack.push(character);
+        else if (character === "}" || character === "]") {
+            const expected = character === "}" ? "{" : "[";
+            if (stack.pop() !== expected)
+                return false;
+            if (stack.length === 0 && text.slice(index + 1).trim())
+                return false;
+        }
+    }
+    return inString || escaped || stack.length > 0;
+}
+function extendsHistory(prior, next) {
+    if (prior.payloadHash !== next.payloadHash || next.transitions.length < prior.transitions.length)
+        return false;
+    return prior.transitions.every((transition, index) => {
+        const candidate = next.transitions[index];
+        return candidate?.state === transition.state && candidate.timestamp === transition.timestamp;
+    });
+}
+function validateEntry(entry, line) {
+    if (!entry || typeof entry !== "object" || typeof entry.requestId !== "string" || typeof entry.clientId !== "string" ||
+        typeof entry.operation !== "string" || typeof entry.payloadHash !== "string" || typeof entry.state !== "string" ||
+        typeof entry.terminal !== "boolean" || !Array.isArray(entry.transitions) || !Array.isArray(entry.evidenceRefs)) {
+        throw new Error(`invalid Broker ledger entry at line ${line}`);
+    }
+    if (!entry.requestId || !entry.clientId || !entry.operation || !entry.payloadHash || !LEDGER_STATES.has(entry.state)) {
+        throw new Error(`invalid Broker ledger entry identity or state at line ${line}`);
+    }
+    if (!Number.isFinite(entry.acceptedAt) || !entry.evidenceRefs.every(reference => typeof reference === "string")) {
+        throw new Error(`invalid Broker ledger entry evidence at line ${line}`);
+    }
+    if (entry.transitions.length === 0 || entry.transitions.at(-1)?.state !== entry.state) {
+        throw new Error(`inconsistent Broker ledger transition history at line ${line}`);
+    }
+    let previousTimestamp = Number.NEGATIVE_INFINITY;
+    for (const transition of entry.transitions) {
+        if (!transition || typeof transition !== "object" || !LEDGER_STATES.has(transition.state) ||
+            !Number.isFinite(transition.timestamp) || transition.timestamp < previousTimestamp ||
+            !Array.isArray(transition.evidenceRefs) || !transition.evidenceRefs.every(reference => typeof reference === "string")) {
+            throw new Error(`invalid Broker ledger transition history at line ${line}`);
+        }
+        previousTimestamp = transition.timestamp;
+    }
+    if (entry.terminal !== TERMINAL_STATES.has(entry.state) ||
+        (entry.terminal ? !Number.isFinite(entry.terminalAt) : entry.terminalAt !== undefined)) {
+        throw new Error(`inconsistent Broker ledger terminal state at line ${line}`);
+    }
+}