wowdump 0.0.0 → 0.2.0

package/dist/broker-runtime.js

@@ -0,0 +1,1283 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { buildAdapterRegistry } from "./adapters.js";
+import { BrokerWireCodec } from "./broker-codec.js";
+import { BrokerProtocolError } from "./broker-protocol.js";
+import { FocusRequestError, isAttachmentFatalError } from "./focus-errors.js";
+const MUTATION_POLICIES = {
+    write_memory: { rollbackModes: ["reversible", "compensating"], rollbackOperations: ["write_memory"] },
+    protect_memory: { rollbackModes: ["reversible", "compensating"], rollbackOperations: ["protect_memory"] },
+    resume: { rollbackModes: ["compensating", "irreversible"], rollbackOperations: ["kill"] },
+    kill: { rollbackModes: ["irreversible"], rollbackOperations: [] },
+    script_load: { rollbackModes: ["compensating", "irreversible"], rollbackOperations: ["script_unload"] },
+    script_unload: { rollbackModes: ["compensating", "irreversible"], rollbackOperations: ["script_load"] },
+    script_call: { rollbackModes: ["reversible", "compensating", "irreversible"], rollbackOperations: ["script_call", "write_memory", "protect_memory"] },
+    host_call: { rollbackModes: ["reversible", "compensating", "irreversible"], rollbackOperations: ["host_call"] }
+};
+const MUTATING_OPERATIONS = new Set(Object.keys(MUTATION_POLICIES));
+const RELEASE_OPERATIONS = {
+    detach: "attachment",
+    script_unload: "script",
+    trace_stop: "trace",
+    session_stop: "session",
+    handle_release: "handle"
+};
+const BROKER_ATTACHMENT_OWNER = "__broker_attachment_owner__";
+const READ_ONLY_EVIDENCE_OPERATIONS = new Set(["devices", "processes", "applications", "modules", "exports", "ranges", "read_memory", "scan_memory"]);
+const FOCUS_OPERATIONS = new Set([
+    "wow_focus_start", "wow_focus_read", "wow_focus_status", "wow_focus_pause", "wow_focus_resume", "wow_focus_stop",
+    "wow_watch_start", "wow_watch_read", "wow_watch_status", "wow_watch_stop", "wow_session_checkpoint"
+]);
+const FOCUS_START_OPERATIONS = new Set(["wow_focus_start", "wow_watch_start"]);
+const FOCUS_STOP_OPERATIONS = new Set(["wow_focus_stop", "wow_watch_stop"]);
+/** Broker-owned Frida runtime; no Frida object crosses IPC. */
+export class BrokerFridaRuntime {
+    executor;
+    readyIdentity;
+    hostAllowlist;
+    processResolver;
+    focusService;
+    fatalHandlers;
+    sessionResources = new Map();
+    scriptResources = new Map();
+    confirmationNonces = new Set();
+    attachmentIdentities = new Map();
+    captures = new Map();
+    releasedCaptures = new Map();
+    captureResourceRoles = new Map();
+    brokerAttachments = new Map();
+    strictIdentity;
+    evidenceDirectory;
+    codec = new BrokerWireCodec();
+    constructor(executor, readyIdentity, hostAllowlist = [
+        {
+            buildKey: "*",
+            methods: ["enumerateDevices", "enumerateProcesses", "enumerateApplications"],
+            sideEffect: "read",
+            argumentTypes: [],
+            maxDurationMs: 5_000,
+            rollbackModes: ["reversible", "compensating"]
+        }
+    ], evidenceDirectory = join(tmpdir(), "wowdump-frida-broker-evidence"), processResolver, focusService) {
+        this.executor = executor;
+        this.readyIdentity = readyIdentity;
+        this.hostAllowlist = hostAllowlist;
+        this.processResolver = processResolver;
+        this.focusService = focusService;
+        this.evidenceDirectory = resolve(evidenceDirectory);
+        this.strictIdentity = processResolver !== undefined || process.env.WOW_BROKER_STRICT_IDENTITY === "1";
+        if (typeof this.focusService?.setFatalHandler === "function")
+            this.focusService.setFatalHandler(event => this.handleFocusFatal(event));
+        if (typeof this.focusService?.setDurationExpiredHandler === "function")
+            this.focusService.setDurationExpiredHandler(event => this.handleDurationExpired(event));
+    }
+    bindFatalHandlers(handlers) { this.fatalHandlers = handlers; }
+    focusedSessionIds(pid, buildKey) {
+        return [...this.captures.values()]
+            .filter(capture => (pid === undefined || capture.pid === pid) && (buildKey === undefined || capture.buildKey === buildKey))
+            .map(capture => capture.controlSessionId)
+            .sort();
+    }
+    async handleFocusFatal(event) {
+        if (event.failureClass === "capture_fatal") {
+            const capture = this.captureForServiceSession(event.sessionId);
+            if (capture && capture.pid === event.pid && capture.buildKey === event.buildKey)
+                return this.fatalHandlers?.captureFatal(event.sessionId, event.pid, event.buildKey, event.error);
+            await this.focusService?.cleanupSession(event.sessionId, "capture_fatal");
+            return;
+        }
+        if (event.failureClass === "attachment_fatal")
+            return this.fatalHandlers?.attachmentFatal(event.pid, event.buildKey);
+        await this.fatalHandlers?.brokerFatal(`focused session ${event.sessionId} reported broker_fatal`);
+    }
+    async handleDurationExpired(event) {
+        const capture = this.captureForServiceSession(event.sessionId);
+        if (capture && capture.pid === event.pid && capture.buildKey === event.buildKey && this.fatalHandlers)
+            return this.fatalHandlers.durationExpired(event.sessionId, event.pid, event.buildKey);
+        await this.focusService?.cleanupSession(event.sessionId, "duration_expired");
+    }
+    async execute(request, context) {
+        if (request.operation === "broker_status") {
+            let processes = [];
+            try {
+                processes = toJson((await this.executor.execute({ operation: "processes" })).processes ?? []);
+            }
+            catch { /* status remains attach-free if discovery fails */ }
+            return { status: "ready", protocolVersion: "2026-07-28", ...(this.readyIdentity ?? {}), processes, focused: toJson(typeof this.focusService?.statusSnapshot === "function" ? this.focusService.statusSnapshot() : []) };
+        }
+        if (request.operation === "broker_processes")
+            return toJson(await this.executor.execute({ operation: "processes" }));
+        if (request.operation === "client_release" || request.operation === "broker_stop")
+            return { accepted: true, operation: request.operation };
+        if (FOCUS_OPERATIONS.has(request.operation))
+            return this.executeFocus(request, context);
+        if (request.operation !== "frida_command")
+            throw new Error(`unsupported Broker operation ${request.operation}`);
+        const payload = request.payload;
+        const rawRequest = isRecord(payload.request) ? payload.request : payload;
+        const operationHint = typeof rawRequest.operation === "string" ? rawRequest.operation : "";
+        const decodedRequest = this.codec.decode(rawRequest, { clientId: request.clientId, pid: request.pid, buildKey: request.buildKey }, operationHint);
+        if (!isRecord(decodedRequest))
+            throw new BrokerProtocolError("FRAME_INVALID", "decoded Frida command must be an object");
+        const command = deserializeCommand(decodedRequest);
+        const target = isRecord(payload.context) ? deserializeContext(payload.context) : undefined;
+        const mutation = isRecord(decodedRequest.mutation) ? decodedRequest.mutation : undefined;
+        const launch = isRecord(decodedRequest.launch) ? decodedRequest.launch : undefined;
+        const operation = command.operation ?? "";
+        const mutating = MUTATING_OPERATIONS.has(operation);
+        const spawning = operation === "spawn";
+        const controlled = mutating || spawning;
+        const contract = spawning ? launch : mutation;
+        const resourceId = this.resolveResourceId(operation, decodedRequest, command);
+        this.validateTargetBinding(request, command, target);
+        this.requireCommandOwnership(command, request, context);
+        if (spawning)
+            this.validateLaunch(request, launch);
+        else if (this.strictIdentity && request.pid !== null && operation === "attach")
+            await this.validateProcessTarget(request, target);
+        else if (this.strictIdentity && request.pid !== null && this.requiresTargetIdentity(operation))
+            await this.revalidateTarget(request, command, target, context);
+        if (operation === "script_load")
+            this.requireScriptParent(command, request, context);
+        if (RELEASE_OPERATIONS[operation])
+            this.requireReleaseResource(resourceId, request.clientId, RELEASE_OPERATIONS[operation], context);
+        if (operation === "host_call" && !request.buildKey)
+            throw new BrokerProtocolError("HOST_CALL_BUILD_KEY_REQUIRED", "host_call requires buildKey");
+        if (mutating)
+            this.validateMutation(request, operation, mutation);
+        if (operation === "host_call")
+            this.validateHostCall(request, command, mutation);
+        const evidence = [];
+        if (controlled && contract) {
+            try {
+                const before = await this.captureEvidence("before", request, command, target, context, contract.evidencePlan.before);
+                evidence.push(before);
+                context.transition("before_captured", { evidenceRefs: [before.path], result: { evidence: toJson(evidence) } });
+            }
+            catch (error) {
+                throw new BrokerProtocolError("MUTATION_BEFORE_EVIDENCE_FAILED", errorText(error), "Fix the evidence plan before retrying; the mutation was not executed.");
+            }
+            context.transition("executing");
+        }
+        let result;
+        try {
+            result = spawning
+                ? await this.executeLaunch(command, launch)
+                : RELEASE_OPERATIONS[operation]
+                    ? await this.releaseOwnedResource(resourceId, request, RELEASE_OPERATIONS[operation], context)
+                    : await this.executor.execute(command, target);
+            const identity = this.strictIdentity && operation === "attach"
+                ? await this.validateAttachedTarget(request, command, target, result)
+                : undefined;
+            if (identity) {
+                result.identity = toJson(identity);
+                result.processStartTime = identity.processStartTime ?? null;
+                result.moduleBase = identity.moduleBase;
+                result.moduleIdentity = identity.moduleIdentity;
+                result.executable = identity.executable ?? null;
+            }
+            if (controlled)
+                context.transition("executed", { result: toJson(result) });
+            if (controlled && contract) {
+                const after = await this.captureEvidence("after", request, command, target, context, contract.evidencePlan.after, result);
+                evidence.push(after);
+                assertMatches(contract.expectedEffect, toJson(result), "expectedEffect");
+                context.transition("after_validated", { evidenceRefs: [after.path], result: { evidence: toJson(evidence) } });
+            }
+        }
+        catch (error) {
+            if (!controlled || !contract)
+                throw error;
+            if (spawning && error instanceof BrokerProtocolError && error.code === "SPAWN_BUILD_MISMATCH") {
+                context.transition("rollback_started", { error: toJson({ rootError: error.message }) });
+                context.transition("rollback_executed", { result: { operation: "kill", spawnedProcessOnly: true } });
+                context.transition("rollback_validated", { result: { code: "SPAWN_BUILD_MISMATCH", killed: true } });
+                context.transition("rolled_back");
+            }
+            else {
+                await this.rollbackMutation(request, command, contract, target, context, error, evidence, result);
+            }
+            throw error;
+        }
+        await this.registerResult(command, result, request, context);
+        const encoded = this.codec.encode(result, { clientId: request.clientId, pid: request.pid, buildKey: request.buildKey });
+        for (const handle of encoded.handles)
+            context.registerResource({ resourceId: handle.resourceId, ownerClientId: request.clientId, pid: request.pid, buildKey: request.buildKey, type: "handle" });
+        return evidence.length === 0 ? encoded.value : mergeEvidence(encoded.value, evidence);
+    }
+    async cleanup(resource, step, reason, cleanupContext) {
+        const captureRole = this.captureResourceRoles.get(resource.resourceId);
+        if (captureRole) {
+            const { capture, role } = captureRole;
+            (capture.cleanupSteps ??= []).push(step);
+            // The capture scope is prepared exactly once by cleanupCaptureScope.
+            // Resource cleanup only commits ownership refs and the final attachment.
+            if (!capture.cleanupResult && step !== "ref_release" && step !== "attachment_detach")
+                await this.ensureCaptureCleanup(capture, reason, cleanupContext?.effectiveDeadline);
+            if (step === "ref_release" && role !== "attachment")
+                this.captureResourceRoles.delete(resource.resourceId);
+            if (role === "attachment" && step === "attachment_detach") {
+                const rawSessionId = this.sessionResources.get(resource.resourceId);
+                if (!rawSessionId)
+                    throw new Error(`session handle missing for ${resource.resourceId}`);
+                await this.executor.execute({ operation: "detach", sessionId: rawSessionId, pid: resource.pid ?? undefined, buildKey: resource.buildKey ?? undefined });
+                this.sessionResources.delete(resource.resourceId);
+                this.attachmentIdentities.delete(rawSessionId);
+                this.captureResourceRoles.delete(resource.resourceId);
+                for (const member of this.captures.values())
+                    if (member.attachmentResourceId === resource.resourceId)
+                        member.released = true;
+            }
+            return;
+        }
+        if (step === "script_unload" && resource.type === "script") {
+            const scriptId = this.scriptResources.get(resource.resourceId) ?? idFromResource(resource.resourceId, "script:");
+            if (!scriptId)
+                throw new Error(`script handle missing for ${resource.resourceId}`);
+            await this.executor.execute({ operation: "script_unload", scriptId });
+            this.scriptResources.delete(resource.resourceId);
+        }
+        if (step === "attachment_detach" && resource.type === "attachment") {
+            const sessionId = this.sessionResources.get(resource.resourceId) ?? idFromResource(resource.resourceId, "attachment:");
+            if (!sessionId)
+                throw new Error(`session handle missing for ${resource.resourceId}`);
+            await this.executor.execute({ operation: "detach", sessionId });
+            this.sessionResources.delete(resource.resourceId);
+            this.attachmentIdentities.delete(sessionId);
+            this.brokerAttachments.delete(resource.resourceId);
+        }
+        if (step === "ref_release" && resource.type === "handle")
+            this.codec.releaseResource(resource.resourceId);
+        void reason;
+    }
+    async cleanupCaptureScope(scopeId, reason, context) {
+        const capture = this.captureForServiceSession(scopeId);
+        if (!capture)
+            return;
+        let literalResult;
+        try {
+            literalResult = await this.ensureCaptureCleanup(capture, reason, context.effectiveDeadline);
+        }
+        catch (error) {
+            return {
+                sessionId: scopeId,
+                status: "failed",
+                steps: cleanupStepsFromResult(capture.cleanupResult, error),
+                residualResources: capture.managedResources.map(resource => resource.resourceId),
+                literalResult: toJson(capture.cleanupResult ?? { error: errorText(error) })
+            };
+        }
+        const steps = cleanupStepsFromResult(literalResult);
+        const cleanupStatus = isRecord(literalResult.cleanupStatus) ? literalResult.cleanupStatus : {};
+        const residual = Number(cleanupStatus.hooks ?? 0) !== 0 || Number(cleanupStatus.scripts ?? 0) !== 0 || Number(cleanupStatus.interceptors ?? 0) !== 0;
+        return {
+            sessionId: scopeId,
+            status: residual || steps.some(step => !step.ok) ? "partial" : "passed",
+            steps,
+            evidenceRefs: evidenceRefsFromFocusResult(literalResult),
+            residualResources: residual ? capture.managedResources.map(resource => resource.resourceId) : [],
+            literalResult: toJson(literalResult)
+        };
+    }
+    finalizeCaptureScope(scopeId, _reason, result) {
+        const capture = this.captureForServiceSession(scopeId);
+        if (!capture)
+            return;
+        capture.cleanupAttempted = true;
+        if (result.literalResult && isRecord(result.literalResult))
+            capture.cleanupResult = result.literalResult;
+        if (result.status !== "passed")
+            return;
+        capture.cleanupFailureReason = undefined;
+    }
+    completeCaptureScope(scopeId, _reason) {
+        const capture = this.captureForServiceSession(scopeId);
+        if (!capture || !capture.cleanupResult)
+            return;
+        const scopedResourcesReleased = capture.managedResources
+            .filter(item => item.type !== "attachment")
+            .every(item => item.resource?.cleanupState === "released");
+        const attachmentHealthy = capture.managedResources
+            .filter(item => item.type === "attachment")
+            .every(item => item.resource?.cleanupState !== "failed");
+        if (scopedResourcesReleased && attachmentHealthy) {
+            for (const item of capture.managedResources) {
+                if (item.type === "attachment" && item.resource?.cleanupState === "released"
+                    && this.captureResourceRoles.get(item.resourceId)?.role === "attachment") {
+                    this.captureResourceRoles.delete(item.resourceId);
+                }
+            }
+            this.markCaptureReleased(capture);
+        }
+    }
+    markCaptureReleased(capture) {
+        if (capture.fullyReleased)
+            return;
+        capture.fullyReleased = true;
+        capture.released = true;
+        this.releasedCaptures.set(capture.controlSessionId, {
+            ownerClientId: capture.ownerClientId,
+            pid: capture.pid,
+            buildKey: capture.buildKey,
+            cleanupResult: capture.cleanupResult
+        });
+        this.captures.delete(capture.controlSessionId);
+        for (const item of capture.managedResources) {
+            if (item.type !== "attachment" && this.captureResourceRoles.get(item.resourceId)?.capture === capture)
+                this.captureResourceRoles.delete(item.resourceId);
+        }
+    }
+    async close() {
+        await this.focusService?.close();
+        await this.executor.close();
+    }
+    async releaseClient(clientId) { this.codec.releaseClient(clientId); }
+    async executeFocus(request, context) {
+        if (!this.focusService)
+            throw new BrokerProtocolError("BROKER_FATAL", "Broker focus service is not configured");
+        if (request.pid === null)
+            throw new BrokerProtocolError("PID_REQUIRED", `${request.operation} requires pid`);
+        if (!request.buildKey)
+            throw new BrokerProtocolError("PID_BUILD_MISMATCH", `${request.operation} requires buildKey`);
+        assertFocusEnvelope(request, request.payload);
+        const input = { ...request.payload, pid: request.pid, buildKey: request.buildKey };
+        if (FOCUS_START_OPERATIONS.has(request.operation)) {
+            const result = await this.invokeFocus(request.operation, input);
+            return toJson(await this.registerCapture(request, result, context));
+        }
+        const sessionId = typeof input.sessionId === "string" && input.sessionId ? input.sessionId : undefined;
+        if (!sessionId)
+            throw new BrokerProtocolError("RESOURCE_NOT_FOUND", `${request.operation} requires sessionId`);
+        const capture = this.captures.get(sessionId);
+        if (!capture) {
+            const released = this.releasedCaptures.get(sessionId);
+            if (!released)
+                throw new BrokerProtocolError("RESOURCE_NOT_FOUND", `capture session ${sessionId} was not found`);
+            if (released.ownerClientId !== request.clientId)
+                throw new BrokerProtocolError("RESOURCE_NOT_OWNER", `${request.clientId} does not own capture ${sessionId}`);
+            if (released.pid !== request.pid || released.buildKey !== request.buildKey)
+                throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", `capture ${sessionId} target does not match Broker envelope`);
+            if (!FOCUS_STOP_OPERATIONS.has(request.operation))
+                throw new BrokerProtocolError("RESOURCE_ALREADY_RELEASED", `capture ${sessionId} is already released`);
+            return toJson({ ...(released.cleanupResult ?? {}), sessionId, stopped: true, cleanupAttempted: true, fullyReleased: true, alreadyReleased: true });
+        }
+        if (capture.ownerClientId !== request.clientId)
+            throw new BrokerProtocolError("RESOURCE_NOT_OWNER", `${request.clientId} does not own capture ${sessionId}`);
+        if (capture.pid !== request.pid || capture.buildKey !== request.buildKey)
+            throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", `capture ${sessionId} target does not match Broker envelope`);
+        if (FOCUS_STOP_OPERATIONS.has(request.operation)) {
+            if (capture.fullyReleased)
+                return toJson({ ...(capture.cleanupResult ?? {}), sessionId, stopped: true, cleanupAttempted: true, fullyReleased: true, alreadyReleased: true });
+            await this.releaseCapture(capture, request, context);
+            return toJson({ ...(capture.cleanupResult ?? {}), sessionId, stopped: true, cleanupAttempted: true, fullyReleased: true, resourceId: capture.sessionResourceId });
+        }
+        if (!capture.released)
+            context.requireOwnedResource(capture.sessionResourceId, request.clientId, "session");
+        return toJson(await this.invokeFocus(request.operation, input));
+    }
+    async invokeFocus(operation, input) {
+        try {
+            return await this.focusService.invoke(operation, input);
+        }
+        catch (error) {
+            if (error instanceof FocusRequestError) {
+                throw new BrokerProtocolError(error.code, error.message, "Correct the focused-session selector and retry the same Broker request.");
+            }
+            if (isAttachmentFatalError(error)) {
+                throw new BrokerProtocolError("ATTACHMENT_FATAL", error instanceof Error ? error.message : String(error), "Confirm the target process is running, then start a new focused session for its current PID.");
+            }
+            throw error;
+        }
+    }
+    captureForServiceSession(sessionId) {
+        return this.captures.get(sessionId)
+            ?? [...this.captures.values()].find(capture => capture.sessionId === sessionId);
+    }
+    async registerCapture(request, result, context) {
+        const sessionId = typeof result.sessionId === "string" && result.sessionId ? result.sessionId : undefined;
+        const fallbackSessionId = typeof request.payload.sessionId === "string" && request.payload.sessionId ? request.payload.sessionId : undefined;
+        if (!sessionId || request.pid === null || !request.buildKey) {
+            const error = new BrokerProtocolError("CAPTURE_FATAL", "focused start did not return a sessionId");
+            await this.rollbackUnregisteredCapture(request, result, fallbackSessionId, error, context);
+            throw error;
+        }
+        if (this.captures.has(sessionId)) {
+            const error = new BrokerProtocolError("RESOURCE_ALREADY_RELEASED", `capture ${sessionId} already exists`);
+            await this.rollbackUnregisteredCapture(request, result, sessionId, error, context);
+            throw error;
+        }
+        const returnedPid = result.pid;
+        const returnedBuildKey = result.buildKey;
+        if ((returnedPid !== undefined && returnedPid !== request.pid)
+            || (returnedBuildKey !== undefined && returnedBuildKey !== request.buildKey)
+            || (result.ready !== undefined && result.ready !== true)) {
+            const error = new BrokerProtocolError("SESSION_TARGET_MISMATCH", "focused start returned a record that failed post-start validation");
+            await this.rollbackUnregisteredCapture(request, result, sessionId, error, context);
+            throw error;
+        }
+        const rawAttachmentId = typeof result.fridaSessionId === "string" && result.fridaSessionId ? result.fridaSessionId : sessionId;
+        let attachmentResourceId = `focus-attachment:${rawAttachmentId}`;
+        const sessionResourceId = `focus-session:${sessionId}`;
+        const rawScriptId = typeof result.scriptId === "string" && result.scriptId ? result.scriptId : undefined;
+        const scriptResourceId = rawScriptId ? `focus-script:${sessionId}` : undefined;
+        const rawHooks = Array.isArray(result.hookIds) ? result.hookIds.filter((value) => typeof value === "string") : [];
+        const identity = {
+            ...(typeof result.processStartTime === "number" ? { processStartTime: new Date(result.processStartTime).toISOString() } : {}),
+            ...(typeof result.moduleBase === "string" ? { moduleBase: result.moduleBase } : {}),
+            ...(typeof result.moduleIdentity === "string" ? { moduleIdentity: result.moduleIdentity } : {})
+        };
+        const capture = {
+            controlSessionId: sessionId,
+            sessionId,
+            ownerClientId: request.clientId,
+            pid: request.pid,
+            buildKey: request.buildKey,
+            attachmentResourceId,
+            sessionResourceId,
+            scriptResourceId,
+            hookResourceIds: rawHooks.map((_, index) => `focus-hook:${sessionId}:${index}`),
+            managedResources: [],
+            identity
+        };
+        const registered = [];
+        let acquiredAttachment = false;
+        let acquiredAttachmentResource;
+        const rollbackErrors = [];
+        try {
+            const existingAttachment = this.brokerAttachments.get(attachmentResourceId);
+            if (existingAttachment) {
+                if (existingAttachment.pid !== request.pid || existingAttachment.buildKey !== request.buildKey || !sameCaptureIdentity(existingAttachment.identity, identity)) {
+                    throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", `${attachmentResourceId} does not match the requested capture target identity`);
+                }
+                try {
+                    acquiredAttachmentResource = context.acquireResource(attachmentResourceId, request.clientId);
+                    acquiredAttachment = true;
+                }
+                catch (error) {
+                    if (!(error instanceof BrokerProtocolError) || error.code !== "RESOURCE_ALREADY_RELEASED")
+                        throw error;
+                    attachmentResourceId = `${attachmentResourceId}:${sessionId}`;
+                    capture.attachmentResourceId = attachmentResourceId;
+                    const resource = context.registerResource({ resourceId: attachmentResourceId, ownerClientId: request.clientId, pid: request.pid, buildKey: request.buildKey, type: "attachment", identity });
+                    registered.push({ resourceId: attachmentResourceId, type: "attachment", resource });
+                    this.sessionResources.set(attachmentResourceId, rawAttachmentId);
+                    this.brokerAttachments.set(attachmentResourceId, { pid: request.pid, buildKey: request.buildKey, identity });
+                }
+            }
+            else {
+                const resource = context.registerResource({ resourceId: attachmentResourceId, ownerClientId: BROKER_ATTACHMENT_OWNER, pid: request.pid, buildKey: request.buildKey, type: "attachment", identity });
+                acquiredAttachmentResource = context.acquireResource(attachmentResourceId, request.clientId);
+                acquiredAttachment = true;
+                this.sessionResources.set(attachmentResourceId, rawAttachmentId);
+                this.brokerAttachments.set(attachmentResourceId, { pid: request.pid, buildKey: request.buildKey, identity });
+            }
+            const sessionResource = context.registerResource({ resourceId: sessionResourceId, ownerClientId: request.clientId, pid: request.pid, buildKey: request.buildKey, type: "session", parentResourceId: attachmentResourceId, cleanupScopeId: sessionId, identity });
+            registered.push({ resourceId: sessionResourceId, type: "session", resource: sessionResource });
+            this.captureResourceRoles.set(sessionResourceId, { capture, role: "session" });
+            if (scriptResourceId) {
+                const resource = context.registerResource({ resourceId: scriptResourceId, ownerClientId: request.clientId, pid: request.pid, buildKey: request.buildKey, type: "script", parentResourceId: sessionResourceId, cleanupScopeId: sessionId, identity });
+                registered.push({ resourceId: scriptResourceId, type: "script", resource });
+                this.captureResourceRoles.set(scriptResourceId, { capture, role: "script" });
+            }
+            for (const resourceId of capture.hookResourceIds) {
+                const resource = context.registerResource({ resourceId, ownerClientId: request.clientId, pid: request.pid, buildKey: request.buildKey, type: "hook", parentResourceId: scriptResourceId ?? sessionResourceId, cleanupScopeId: sessionId, identity });
+                registered.push({ resourceId, type: "hook", resource });
+                this.captureResourceRoles.set(resourceId, { capture, role: "hook" });
+            }
+            this.captures.set(sessionId, capture);
+            capture.managedResources = [
+                ...[...registered].reverse().map(item => ({ ...item, reasonRole: item.type })),
+                ...(acquiredAttachment ? [{ resourceId: attachmentResourceId, type: "attachment", reasonRole: "acquired_ref", resource: acquiredAttachmentResource }] : [])
+            ];
+            return { ...result, resourceId: sessionResourceId, attachmentResourceId, scriptResourceId: scriptResourceId ?? null, hookResourceIds: capture.hookResourceIds };
+        }
+        catch (error) {
+            let cleanupSucceeded = false;
+            try {
+                capture.cleanupAttempted = true;
+                capture.cleanupPromise = this.focusService.cleanupSession(sessionId, "broker_registration_failed");
+                capture.cleanupResult = await capture.cleanupPromise;
+                cleanupSucceeded = true;
+            }
+            catch (cleanupError) {
+                capture.cleanupPromise = undefined;
+                const message = errorText(cleanupError);
+                (capture.cleanupFailures ??= []).push(message);
+                rollbackErrors.push(`capture cleanup: ${message}`);
+            }
+            if (cleanupSucceeded) {
+                for (const item of [...registered].reverse()) {
+                    try {
+                        await context.releaseResource(item.resourceId, request.clientId, item.type, "focus_registration_rollback");
+                    }
+                    catch (releaseError) {
+                        rollbackErrors.push(`${item.resourceId}: ${errorText(releaseError)}`);
+                    }
+                }
+                if (acquiredAttachment) {
+                    try {
+                        await context.releaseResource(attachmentResourceId, request.clientId, "attachment", "focus_registration_rollback:acquired_ref");
+                    }
+                    catch (releaseError) {
+                        rollbackErrors.push(`${attachmentResourceId}: ${errorText(releaseError)}`);
+                    }
+                }
+            }
+            capture.managedResources = [
+                ...[...registered].reverse().map(item => ({ ...item, reasonRole: item.type })),
+                ...(acquiredAttachment ? [{ resourceId: attachmentResourceId, type: "attachment", reasonRole: "acquired_ref", resource: acquiredAttachmentResource }] : [])
+            ];
+            capture.fullyReleased = cleanupSucceeded && rollbackErrors.length === 0;
+            capture.released = capture.fullyReleased;
+            if (capture.fullyReleased) {
+                for (const item of registered)
+                    if (item.type !== "attachment" || this.captureResourceRoles.get(item.resourceId)?.capture === capture)
+                        this.captureResourceRoles.delete(item.resourceId);
+            }
+            else {
+                const controlSessionId = this.reserveResidualSessionId(sessionId);
+                capture.controlSessionId = controlSessionId;
+                this.captures.set(controlSessionId, capture);
+                this.annotateResidualError(error, controlSessionId, rollbackErrors);
+            }
+            if (rollbackErrors.length && error && typeof error === "object")
+                Object.assign(error, { registrationRollback: rollbackErrors });
+            throw error;
+        }
+    }
+    async rollbackUnregisteredCapture(request, result, sessionId, error, context) {
+        if (!sessionId) {
+            Object.assign(error, { registrationRollback: ["capture cleanup unavailable: start returned no sessionId and request supplied no fallback sessionId"] });
+            return;
+        }
+        try {
+            await this.focusService.cleanupSession(sessionId, "broker_registration_failed");
+        }
+        catch (cleanupError) {
+            const controlSessionId = this.reserveResidualSessionId(sessionId);
+            const resourceId = `focus-session:${controlSessionId}`;
+            const capture = {
+                controlSessionId, sessionId, ownerClientId: request.clientId, pid: request.pid, buildKey: request.buildKey,
+                attachmentResourceId: "", sessionResourceId: resourceId, hookResourceIds: [], managedResources: [{ resourceId, type: "session", reasonRole: "residual_session" }],
+                identity: {}, cleanupAttempted: true, cleanupFailures: [errorText(cleanupError)], released: false, fullyReleased: false
+            };
+            context.registerResource({ resourceId, ownerClientId: request.clientId, pid: request.pid, buildKey: request.buildKey, type: "session", cleanupScopeId: sessionId });
+            this.captureResourceRoles.set(resourceId, { capture, role: "session" });
+            this.captures.set(controlSessionId, capture);
+            const failures = [`capture cleanup: ${errorText(cleanupError)}`];
+            Object.assign(error, { registrationRollback: failures });
+            this.annotateResidualError(error, controlSessionId, failures);
+        }
+        void result;
+    }
+    async releaseCapture(capture, request, context) {
+        try {
+            await this.ensureCaptureCleanup(capture, capture.cleanupAttempted ? `${request.operation}:retry_cleanup` : `${request.operation}:session_release`);
+        }
+        catch (error) {
+            const retained = capture.managedResources.map(item => item.resourceId);
+            throw new BrokerProtocolError("CLEANUP_TIMEOUT", `cleanupAttempted=true; fullyReleased=false; residualSessionId=${capture.controlSessionId}; residualResources=${JSON.stringify(retained)}; focus cleanup failed: ${errorText(error)}`, `Retry ${request.operation} with sessionId=${capture.controlSessionId}.`);
+        }
+        const normalPlan = [
+            ...capture.hookResourceIds.map(resourceId => ({ resourceId, type: "hook", reasonRole: "hook" })),
+            ...(capture.scriptResourceId ? [{ resourceId: capture.scriptResourceId, type: "script", reasonRole: "script" }] : []),
+            { resourceId: capture.sessionResourceId, type: "session", reasonRole: "session" },
+            { resourceId: capture.attachmentResourceId, type: "attachment", reasonRole: "attachment" }
+        ];
+        const managed = capture.managedResources.length ? capture.managedResources : normalPlan;
+        const plan = managed
+            .filter(item => !item.resource || ((item.resource.cleanupState === "active" || item.resource.cleanupState === "failed") && item.resource.refs.has(request.clientId)))
+            .map(item => ({ ...item, reason: `${request.operation}:${item.reasonRole}_release` }));
+        const failures = [];
+        for (const item of plan) {
+            try {
+                await context.releaseResource(item.resourceId, request.clientId, item.type, item.reason);
+            }
+            catch (error) {
+                failures.push(`${item.resourceId}: ${errorText(error)}`);
+            }
+        }
+        capture.cleanupAttempted = true;
+        const residualResources = managed
+            .filter(item => item.resource && item.resource.refs.has(request.clientId) && item.resource.cleanupState !== "released")
+            .map(item => item.resourceId);
+        capture.fullyReleased = failures.length === 0 && residualResources.length === 0;
+        capture.released = capture.fullyReleased;
+        if (capture.fullyReleased) {
+            this.releasedCaptures.set(capture.controlSessionId, {
+                ownerClientId: capture.ownerClientId,
+                pid: capture.pid,
+                buildKey: capture.buildKey,
+                cleanupResult: capture.cleanupResult
+            });
+            this.captures.delete(capture.controlSessionId);
+            for (const item of managed) {
+                if (this.captureResourceRoles.get(item.resourceId)?.capture === capture)
+                    this.captureResourceRoles.delete(item.resourceId);
+            }
+        }
+        if (!capture.fullyReleased) {
+            capture.cleanupFailures = [...(capture.cleanupFailures ?? []), ...failures];
+            throw new BrokerProtocolError("CLEANUP_TIMEOUT", `cleanupAttempted=true; fullyReleased=false; residualResources=${JSON.stringify(residualResources)}; failures=${failures.join("; ")}`, "Retry stop and inspect focused-session residual cleanup evidence.");
+        }
+    }
+    async ensureCaptureCleanup(capture, reason, cleanupDeadline) {
+        if (capture.cleanupResult !== undefined)
+            return capture.cleanupResult;
+        if (capture.cleanupFailureReason !== undefined && capture.cleanupFailureReason !== reason) {
+            capture.cleanupPromise = undefined;
+            capture.cleanupFailureReason = undefined;
+        }
+        capture.cleanupAttempted = true;
+        capture.cleanupPromise ??= this.focusService.cleanupSession(capture.sessionId, reason, cleanupDeadline);
+        try {
+            capture.cleanupResult = await capture.cleanupPromise;
+            capture.cleanupFailureReason = undefined;
+            return capture.cleanupResult;
+        }
+        catch (error) {
+            capture.cleanupFailureReason = reason;
+            (capture.cleanupFailures ??= []).push(errorText(error));
+            throw error;
+        }
+    }
+    reserveResidualSessionId(sessionId) {
+        let candidate;
+        do
+            candidate = `${sessionId}#rollback-${randomUUID()}`;
+        while (this.captures.has(candidate));
+        return candidate;
+    }
+    annotateResidualError(error, controlSessionId, failures) {
+        if (!error || typeof error !== "object")
+            return;
+        const message = `cleanup residual retained; residualSessionId=${controlSessionId}; failures=${failures.join("; ")}`;
+        Object.assign(error, { residualSessionId: controlSessionId, nextAction: `Retry wow_focus_stop with sessionId=${controlSessionId}.` });
+        if (error instanceof Error)
+            error.message = `${error.message}; ${message}`;
+    }
+    requireScriptParent(command, request, context) {
+        if (!command.sessionId)
+            throw new BrokerProtocolError("RESOURCE_NOT_FOUND", "script_load requires its Broker attachment sessionId");
+        const parent = context.requireOwnedResource(`attachment:${command.sessionId}`, request.clientId, "attachment");
+        if (parent.pid !== request.pid || parent.buildKey !== request.buildKey)
+            throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", "script attachment scope does not match request target");
+    }
+    requireCommandOwnership(command, request, context) {
+        if (command.operation === "attach")
+            return;
+        let attachment;
+        let explicitResource;
+        if (command.sessionId)
+            attachment = context.requireOwnedResource(`attachment:${command.sessionId}`, request.clientId, "attachment");
+        if (command.scriptId) {
+            const script = context.requireOwnedResource(`script:${command.scriptId}`, request.clientId, "script");
+            if (command.sessionId && script.parentResourceId !== `attachment:${command.sessionId}`)
+                throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", "script does not belong to the requested attachment");
+            attachment ??= script.parentResourceId ? context.requireOwnedResource(script.parentResourceId, request.clientId, "attachment") : undefined;
+        }
+        if (command.resourceId) {
+            explicitResource = context.requireOwnedResource(command.resourceId, request.clientId);
+            const attachmentId = explicitResource.type === "attachment" ? explicitResource.resourceId : explicitResource.parentResourceId;
+            if (attachmentId)
+                attachment ??= context.requireOwnedResource(attachmentId, request.clientId, "attachment");
+        }
+        if (command.resourceId && command.sessionId) {
+            let explicitAttachmentId;
+            let cursor = explicitResource;
+            while (cursor) {
+                if (cursor.type === "attachment") {
+                    explicitAttachmentId = cursor.resourceId;
+                    break;
+                }
+                explicitAttachmentId = cursor.parentResourceId;
+                cursor = cursor.parentResourceId ? context.requireOwnedResource(cursor.parentResourceId, request.clientId) : undefined;
+            }
+            if (explicitAttachmentId !== `attachment:${command.sessionId}`)
+                throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", "resourceId does not belong to sessionId attachment");
+        }
+        if (command.resourceId && command.scriptId && command.operation === "script_unload" && command.resourceId !== `script:${command.scriptId}`)
+            throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", "resourceId does not match scriptId");
+        if (attachment && (attachment.pid !== request.pid || attachment.buildKey !== request.buildKey))
+            throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", "Broker resource scope does not match request target");
+        if (explicitResource && (explicitResource.pid !== request.pid || explicitResource.buildKey !== request.buildKey))
+            throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", "Broker resource scope does not match request target");
+    }
+    async validateNestedCommand(command, request, target, context) {
+        this.validateTargetBinding(request, command, target);
+        this.requireCommandOwnership(command, request, context);
+        const operation = command.operation ?? "";
+        if (operation === "script_load")
+            this.requireScriptParent(command, request, context);
+        if (RELEASE_OPERATIONS[operation])
+            this.requireReleaseResource(this.resolveResourceId(operation, command, command), request.clientId, RELEASE_OPERATIONS[operation], context);
+        if (this.strictIdentity && request.pid !== null && operation === "attach")
+            await this.validateProcessTarget(request, target);
+        else if (this.strictIdentity && request.pid !== null && this.requiresTargetIdentity(operation))
+            await this.revalidateTarget(request, command, target, context);
+    }
+    requireReleaseResource(resourceId, clientId, expectedType, context) {
+        if (!resourceId)
+            throw new BrokerProtocolError("RESOURCE_NOT_FOUND", `${expectedType} release requires resourceId`, "Use the Broker-issued resourceId; raw Frida IDs cannot release resources.");
+        return context.requireOwnedResource(resourceId, clientId, expectedType);
+    }
+    resolveResourceId(_operation, rawRequest, _command) {
+        return typeof rawRequest.resourceId === "string" ? rawRequest.resourceId : undefined;
+    }
+    async releaseOwnedResource(resourceId, request, expectedType, context) {
+        const resource = await context.releaseResource(resourceId, request.clientId, expectedType, `${request.operation}:explicit_release`);
+        return { resourceId, released: resource.cleanupState === "released", cleanupState: resource.cleanupState };
+    }
+    async registerResult(command, result, request, context) {
+        const clientId = request.clientId;
+        const pid = request.pid ?? command.pid ?? null;
+        const buildKey = request.buildKey ?? command.buildKey ?? null;
+        if (command.operation === "attach" && typeof result.sessionId === "string") {
+            const resourceId = `attachment:${result.sessionId}`;
+            if (this.sessionResources.has(resourceId))
+                context.acquireResource(resourceId, clientId);
+            else {
+                this.sessionResources.set(resourceId, result.sessionId);
+                const identity = this.attachmentIdentities.get(result.sessionId);
+                context.registerResource({
+                    resourceId,
+                    ownerClientId: clientId,
+                    pid,
+                    buildKey,
+                    type: "attachment",
+                    ...(identity ? { identity: identityResourceFields(identity) } : {})
+                });
+            }
+            result.resourceId = resourceId;
+        }
+        if (command.operation === "script_load" && typeof result.scriptId === "string") {
+            const resourceId = `script:${result.scriptId}`;
+            if (this.scriptResources.has(resourceId)) {
+                try {
+                    context.requireOwnedResource(resourceId, clientId, "script");
+                    context.acquireResource(resourceId, clientId);
+                }
+                catch (error) {
+                    await this.executor.execute({ operation: "script_unload", sessionId: command.sessionId, scriptId: result.scriptId, pid: pid ?? undefined, buildKey: buildKey ?? undefined }).catch(() => undefined);
+                    throw error;
+                }
+            }
+            else {
+                this.scriptResources.set(resourceId, result.scriptId);
+                context.registerResource({ resourceId, ownerClientId: clientId, pid, buildKey, type: "script", parentResourceId: `attachment:${command.sessionId}` });
+            }
+            result.resourceId = resourceId;
+        }
+    }
+    validateTargetBinding(request, command, target) {
+        for (const candidate of [command.pid, target?.pid])
+            if (candidate !== undefined && candidate !== request.pid)
+                throw new BrokerProtocolError("MUTATION_TARGET_MISMATCH", "command/context pid differs from Broker envelope");
+        for (const candidate of [command.buildKey, target?.buildKey])
+            if (candidate !== undefined && candidate !== request.buildKey)
+                throw new BrokerProtocolError("MUTATION_TARGET_MISMATCH", "command/context buildKey differs from Broker envelope");
+    }
+    requiresTargetIdentity(operation) {
+        return !["", "devices", "processes", "applications", "session_status", "broker_status", "broker_processes"].includes(operation);
+    }
+    async validateProcessTarget(request, target) {
+        if (request.pid === null)
+            throw new BrokerProtocolError("PID_REQUIRED", "target operation requires pid");
+        const actual = await this.resolveProcess(request.pid);
+        if (!actual)
+            throw new BrokerProtocolError("MODULE_NOT_FOUND", `PID ${request.pid} is no longer running`, "List current Wow.exe PIDs and start a fresh request.");
+        if (actual.name.toLowerCase() !== "wow.exe")
+            throw new BrokerProtocolError("PID_NOT_WOW", `PID ${request.pid} is ${actual.name || "an unknown process"}, not Wow.exe`);
+        if (!actual.buildKey)
+            throw new BrokerProtocolError("PID_BUILD_MISMATCH", `PID ${request.pid} has no verified build identity`);
+        if (!actual.executable || !actual.processStartTime)
+            throw new BrokerProtocolError("PID_REUSED", `PID ${request.pid} has incomplete executable/start-time identity`);
+        if (request.buildKey && actual.buildKey !== request.buildKey)
+            throw new BrokerProtocolError("PID_BUILD_MISMATCH", `PID ${request.pid} is ${actual.buildKey}, expected ${request.buildKey}`);
+        if (target?.executable && (!actual.executable || canonicalPath(actual.executable) !== canonicalPath(target.executable)))
+            throw new BrokerProtocolError("PID_REUSED", `PID ${request.pid} executable identity changed`);
+        if (target?.processStartTime && (!actual.processStartTime || normalizeTime(actual.processStartTime) !== normalizeTime(target.processStartTime)))
+            throw new BrokerProtocolError("PID_REUSED", `PID ${request.pid} start time changed`);
+        return actual;
+    }
+    async revalidateTarget(request, command, target, context) {
+        const process = await this.validateProcessTarget(request, target);
+        const sessionId = this.targetSessionId(command, request, context);
+        if (!sessionId)
+            throw new BrokerProtocolError("MODULE_NOT_FOUND", "A Broker-owned attachment is required to validate Wow.exe module identity", "Attach to the explicit PID first and reuse the returned sessionId/resourceId.");
+        const expected = this.attachmentIdentities.get(sessionId);
+        if (!expected)
+            throw new BrokerProtocolError("RESOURCE_NOT_FOUND", `attachment identity for ${sessionId} was not found`, "Use the Broker-issued attachment resource.");
+        const actual = await this.resolveModuleIdentity(request, sessionId, process);
+        assertStableIdentity(expected, actual);
+        if (target?.moduleBase && normalizeHex(target.moduleBase) !== normalizeHex(actual.moduleBase))
+            throw new BrokerProtocolError("MODULE_NOT_FOUND", `Wow.exe module base changed for PID ${request.pid}`);
+        if (target?.moduleIdentity && target.moduleIdentity !== actual.moduleIdentity)
+            throw new BrokerProtocolError("MODULE_NOT_FOUND", `Wow.exe module identity changed for PID ${request.pid}`);
+        return actual;
+    }
+    async validateAttachedTarget(request, command, target, result) {
+        const sessionId = typeof result.sessionId === "string" ? result.sessionId : undefined;
+        if (!sessionId)
+            throw new BrokerProtocolError("MODULE_NOT_FOUND", "attach did not return a sessionId");
+        try {
+            const process = await this.validateProcessTarget(request, target);
+            const actual = await this.resolveModuleIdentity(request, sessionId, process);
+            const prior = this.attachmentIdentities.get(sessionId);
+            if (prior)
+                assertStableIdentity(prior, actual);
+            if (target?.moduleBase && normalizeHex(target.moduleBase) !== normalizeHex(actual.moduleBase))
+                throw new BrokerProtocolError("MODULE_NOT_FOUND", `Wow.exe module base changed for PID ${request.pid}`);
+            if (target?.moduleIdentity && target.moduleIdentity !== actual.moduleIdentity)
+                throw new BrokerProtocolError("MODULE_NOT_FOUND", `Wow.exe module identity changed for PID ${request.pid}`);
+            this.attachmentIdentities.set(sessionId, actual);
+            return actual;
+        }
+        catch (error) {
+            if (result.reused !== true)
+                await this.executor.execute({ operation: "detach", sessionId, pid: request.pid ?? undefined, buildKey: request.buildKey ?? undefined }, target).catch(() => undefined);
+            throw error;
+        }
+    }
+    targetSessionId(command, request, context) {
+        if (command.sessionId) {
+            const resource = context.requireOwnedResource(`attachment:${command.sessionId}`, request.clientId, "attachment");
+            if (resource.pid !== request.pid || resource.buildKey !== request.buildKey)
+                throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", "attachment scope does not match request target");
+            return command.sessionId;
+        }
+        const expectedType = RELEASE_OPERATIONS[command.operation ?? ""];
+        if (!expectedType || typeof command.resourceId !== "string")
+            return undefined;
+        const resource = context.requireOwnedResource(command.resourceId, request.clientId, expectedType);
+        const attachmentId = resource.type === "attachment" ? resource.resourceId : resource.parentResourceId;
+        return attachmentId ? idFromResource(attachmentId, "attachment:") : undefined;
+    }
+    async resolveProcess(pid) {
+        if (this.processResolver)
+            return this.processResolver(pid);
+        const response = await this.executor.execute({ operation: "processes" });
+        const record = arrayOfRecords(response.processes ?? response.value).find(item => Number(item.pid) === pid);
+        return record ? processIdentityFromRecord(record) : undefined;
+    }
+    async resolveModuleIdentity(request, sessionId, process) {
+        let response;
+        try {
+            response = await this.executor.execute({ operation: "modules", sessionId, pid: request.pid ?? undefined, buildKey: request.buildKey ?? undefined }, { pid: request.pid ?? undefined, buildKey: request.buildKey ?? undefined, executable: process.executable, processStartTime: process.processStartTime });
+        }
+        catch (error) {
+            throw new BrokerProtocolError("MODULE_NOT_FOUND", `failed to enumerate Wow.exe modules: ${errorText(error)}`);
+        }
+        const module = arrayOfRecords(response.modules ?? response.value).find(item => String(item.name ?? "").toLowerCase() === "wow.exe");
+        if (!module || typeof module.base !== "string" || typeof module.path !== "string")
+            throw new BrokerProtocolError("MODULE_NOT_FOUND", `Wow.exe module identity is incomplete for PID ${request.pid}`);
+        const modulePath = module.path;
+        if (process.executable && modulePath && canonicalPath(process.executable) !== canonicalPath(modulePath))
+            throw new BrokerProtocolError("PID_REUSED", `Wow.exe module path changed for PID ${request.pid}`);
+        const moduleSize = typeof module.size === "number" && Number.isFinite(module.size) ? module.size : undefined;
+        const moduleBase = normalizeHex(module.base);
+        const moduleIdentity = createHash("sha256").update(JSON.stringify({ name: "Wow.exe", path: modulePath ? canonicalPath(modulePath) : null, size: moduleSize ?? null, base: moduleBase })).digest("hex");
+        return {
+            ...process,
+            name: "Wow.exe",
+            buildKey: process.buildKey,
+            moduleBase,
+            moduleIdentity,
+            ...(modulePath ? { modulePath } : {}),
+            ...(moduleSize !== undefined ? { moduleSize } : {})
+        };
+    }
+    validateMutation(request, operation, mutation) {
+        if (!mutation)
+            throw new BrokerProtocolError("MUTATION_PLAN_REQUIRED", `${operation} requires a mutation contract`, "Provide mutationPlanId, confirmation, rollback, evidencePlan and audit.");
+        if (!mutation.mutationPlanId)
+            throw new BrokerProtocolError("MUTATION_PLAN_REQUIRED", "mutationPlanId is required");
+        if (!mutation.confirmation)
+            throw new BrokerProtocolError("MUTATION_CONFIRMATION_REQUIRED", "mutation confirmation is required");
+        if (mutation.confirmation.clientId !== request.clientId)
+            throw new BrokerProtocolError("MUTATION_TARGET_MISMATCH", "confirmation clientId does not match request clientId");
+        const confirmedAt = Date.parse(mutation.confirmation.confirmedAt);
+        if (!Number.isFinite(confirmedAt) || Math.abs(Date.now() - confirmedAt) > 300_000)
+            throw new BrokerProtocolError("MUTATION_CONFIRMATION_EXPIRED", "mutation confirmation is expired");
+        if (!mutation.confirmation.nonce)
+            throw new BrokerProtocolError("MUTATION_CONFIRMATION_REQUIRED", "confirmation nonce is required");
+        if (this.confirmationNonces.has(mutation.confirmation.nonce))
+            throw new BrokerProtocolError("MUTATION_CONFIRMATION_REPLAYED", "confirmation nonce was already used");
+        if (mutation.expectedEffect === undefined || mutation.expectedEffect === null)
+            throw new BrokerProtocolError("MUTATION_EXPECTED_EFFECT_REQUIRED", "expectedEffect is required");
+        if (!mutation.rollback)
+            throw new BrokerProtocolError("MUTATION_ROLLBACK_REQUIRED", "rollback is required");
+        if (!mutation.evidencePlan)
+            throw new BrokerProtocolError("MUTATION_EVIDENCE_PLAN_REQUIRED", "evidencePlan is required");
+        if (!mutation.audit)
+            throw new BrokerProtocolError("MUTATION_AUDIT_REQUIRED", "audit is required");
+        if (mutation.audit.requestId !== request.requestId)
+            throw new BrokerProtocolError("MUTATION_TARGET_MISMATCH", "audit requestId does not match requestId");
+        const policy = MUTATION_POLICIES[operation];
+        if (!policy || !policy.rollbackModes.includes(mutation.rollback.mode))
+            throw new BrokerProtocolError("MUTATION_ROLLBACK_INVALID", `${operation} does not allow ${mutation.rollback.mode} rollback`);
+        if (mutation.rollback.mode !== "irreversible" && (!mutation.rollback.plan || !mutation.rollback.deadline || !mutation.rollback.successOracle))
+            throw new BrokerProtocolError("MUTATION_ROLLBACK_INVALID", "reversible and compensating rollback require plan, deadline and successOracle");
+        if (mutation.rollback.mode === "irreversible" && (!mutation.rollback.irreversibleReason || mutation.confirmation.irreversibleAcknowledged !== true))
+            throw new BrokerProtocolError("MUTATION_IRREVERSIBLE_CONFIRMATION_REQUIRED", "irreversible mutations require explicit acknowledgement and reason");
+        if (mutation.rollback.mode !== "irreversible") {
+            const rollbackOperation = isRecord(mutation.rollback.plan) ? mutation.rollback.plan.operation : undefined;
+            if (typeof rollbackOperation !== "string" || !policy.rollbackOperations.includes(rollbackOperation))
+                throw new BrokerProtocolError("MUTATION_ROLLBACK_INVALID", `${operation} rollback operation is not allowlisted`);
+        }
+        if (request.pid === null)
+            throw new BrokerProtocolError("PID_REQUIRED", "mutating operation requires pid");
+        const mutationTarget = mutation.target;
+        if (mutationTarget && (mutationTarget.pid !== request.pid || (mutationTarget.buildKey ?? null) !== request.buildKey))
+            throw new BrokerProtocolError("MUTATION_TARGET_MISMATCH", "mutation target differs from Broker envelope");
+        this.confirmationNonces.add(mutation.confirmation.nonce);
+    }
+    validateLaunch(request, launch) {
+        if (request.pid !== null)
+            throw new BrokerProtocolError("SPAWN_PID_MUST_BE_NULL", "spawn must not be bound to an existing pid");
+        if (!launch)
+            throw new BrokerProtocolError("SPAWN_CONTRACT_REQUIRED", "spawn requires a launch contract");
+        if (!launch.mutationPlanId)
+            throw new BrokerProtocolError("MUTATION_PLAN_REQUIRED", "launch mutationPlanId is required");
+        if (!launch.confirmation)
+            throw new BrokerProtocolError("MUTATION_CONFIRMATION_REQUIRED", "launch confirmation is required");
+        if (launch.confirmation.clientId !== request.clientId)
+            throw new BrokerProtocolError("MUTATION_TARGET_MISMATCH", "launch confirmation clientId does not match request clientId");
+        const confirmedAt = Date.parse(launch.confirmation.confirmedAt);
+        if (!Number.isFinite(confirmedAt) || Math.abs(Date.now() - confirmedAt) > 300_000)
+            throw new BrokerProtocolError("MUTATION_CONFIRMATION_EXPIRED", "launch confirmation is expired");
+        if (!launch.confirmation.nonce)
+            throw new BrokerProtocolError("MUTATION_CONFIRMATION_REQUIRED", "launch confirmation nonce is required");
+        if (this.confirmationNonces.has(launch.confirmation.nonce))
+            throw new BrokerProtocolError("MUTATION_CONFIRMATION_REPLAYED", "launch confirmation nonce was already used");
+        if (!launch.launchSpec || typeof launch.launchSpec.executable !== "string" || !launch.launchSpec.executable || !Array.isArray(launch.launchSpec.argv) || launch.launchSpec.argv.some(value => typeof value !== "string") || typeof launch.launchSpec.cwd !== "string" || !launch.launchSpec.cwd || !/^[a-f0-9]{64}$/i.test(launch.launchSpec.environmentDigest) || typeof launch.launchSpec.suspended !== "boolean")
+            throw new BrokerProtocolError("SPAWN_CONTRACT_REQUIRED", "launchSpec is incomplete or invalid");
+        if (!isAbsolute(launch.launchSpec.executable) || !isAbsolute(launch.launchSpec.cwd))
+            throw new BrokerProtocolError("SPAWN_CONTRACT_REQUIRED", "launch executable and cwd must be absolute paths");
+        if (launch.expectedEffect === undefined || launch.expectedEffect === null)
+            throw new BrokerProtocolError("MUTATION_EXPECTED_EFFECT_REQUIRED", "launch expectedEffect is required");
+        if (!launch.rollback)
+            throw new BrokerProtocolError("MUTATION_ROLLBACK_REQUIRED", "launch rollback is required");
+        if (!launch.evidencePlan)
+            throw new BrokerProtocolError("MUTATION_EVIDENCE_PLAN_REQUIRED", "launch evidencePlan is required");
+        if (!launch.audit)
+            throw new BrokerProtocolError("MUTATION_AUDIT_REQUIRED", "launch audit is required");
+        if (launch.audit.requestId !== request.requestId)
+            throw new BrokerProtocolError("MUTATION_TARGET_MISMATCH", "launch audit requestId does not match requestId");
+        if (launch.rollback.mode !== "compensating" || !isRecord(launch.rollback.plan) || launch.rollback.plan.operation !== "kill" || !launch.rollback.deadline || !launch.rollback.successOracle)
+            throw new BrokerProtocolError("MUTATION_ROLLBACK_INVALID", "spawn requires a compensating kill rollback with deadline and oracle");
+        this.confirmationNonces.add(launch.confirmation.nonce);
+    }
+    async executeLaunch(command, launch) {
+        const result = await this.executor.execute({
+            ...command,
+            pid: undefined,
+            program: launch.launchSpec.executable,
+            argv: [launch.launchSpec.executable, ...launch.launchSpec.argv],
+            options: { ...(command.options ?? {}), cwd: launch.launchSpec.cwd, suspended: launch.launchSpec.suspended }
+        });
+        const pid = typeof result.pid === "number" ? result.pid : undefined;
+        if (!pid)
+            throw new BrokerProtocolError("MUTATION_EXECUTION_FAILED", "spawn did not return a pid");
+        const identity = await this.spawnIdentity(pid, result);
+        if (!identity.buildKey) {
+            await this.executor.execute({ operation: "kill", pid }).catch(() => undefined);
+            throw new BrokerProtocolError("PID_BUILD_MISMATCH", `spawned PID ${pid} has no verified build identity`);
+        }
+        if (!identity.executable || !identity.startTime || !identity.moduleIdentity) {
+            await this.executor.execute({ operation: "kill", pid }).catch(() => undefined);
+            throw new BrokerProtocolError("MODULE_NOT_FOUND", `spawned PID ${pid} has incomplete executable/start-time/module identity`);
+        }
+        if (canonicalPath(identity.executable) !== canonicalPath(launch.launchSpec.executable)) {
+            await this.executor.execute({ operation: "kill", pid }).catch(() => undefined);
+            throw new BrokerProtocolError("PID_REUSED", `spawned PID ${pid} executable identity differs from launch contract`);
+        }
+        if (launch.expectedBuildKey && launch.expectedBuildKey !== identity.buildKey) {
+            await this.executor.execute({ operation: "kill", pid }).catch(() => undefined);
+            throw new BrokerProtocolError("SPAWN_BUILD_MISMATCH", `spawned process is ${identity.buildKey}, expected ${launch.expectedBuildKey}`);
+        }
+        return { ...result, pid, buildKey: identity.buildKey ?? launch.expectedBuildKey ?? null, startTime: identity.startTime ?? null, executable: identity.executable ?? launch.launchSpec.executable, suspended: launch.launchSpec.suspended };
+    }
+    async spawnIdentity(pid, result) {
+        const direct = isRecord(result.identity) ? result.identity : result;
+        let candidate = direct;
+        try {
+            const processes = await this.executor.execute({ operation: "processes" });
+            candidate = arrayOfRecords(processes.processes ?? processes.value).find(item => item.pid === pid) ?? direct;
+        }
+        catch { /* direct spawn evidence remains available */ }
+        return {
+            buildKey: typeof candidate.buildKey === "string" ? candidate.buildKey : undefined,
+            startTime: typeof candidate.startTime === "string" ? candidate.startTime : undefined,
+            executable: typeof candidate.executable === "string" ? candidate.executable : typeof candidate.path === "string" ? candidate.path : undefined,
+            moduleIdentity: typeof candidate.moduleIdentity === "string" ? candidate.moduleIdentity : undefined
+        };
+    }
+    validateHostCall(request, command, mutation) {
+        if (!request.buildKey)
+            throw new BrokerProtocolError("HOST_CALL_BUILD_KEY_REQUIRED", "host_call requires buildKey");
+        const method = typeof command.method === "string" ? command.method : "";
+        const entry = this.hostAllowlist.find(item => (item.buildKey === "*" || item.buildKey === request.buildKey) && item.methods.includes(method));
+        if (!entry)
+            throw new BrokerProtocolError("HOST_CALL_NOT_ALLOWLISTED", `host call ${method || "<empty>"} is not allowlisted`, "Use a registered Broker host-call entry.");
+        const args = command.args ?? [];
+        if (entry.argumentTypes && (args.length !== entry.argumentTypes.length || args.some((value, index) => jsonType(value) !== entry.argumentTypes[index])))
+            throw new BrokerProtocolError("HOST_CALL_SCHEMA_MISMATCH", `host call ${method} arguments do not match the registered schema`);
+        if (entry.maxDurationMs !== undefined && (command.timeoutMs ?? entry.maxDurationMs) > entry.maxDurationMs)
+            throw new BrokerProtocolError("HOST_CALL_SCHEMA_MISMATCH", `host call ${method} exceeds its ${entry.maxDurationMs}ms deadline`);
+        if (!(entry.rollbackModes ?? []).includes(mutation.rollback.mode))
+            throw new BrokerProtocolError("MUTATION_ROLLBACK_INVALID", `host call ${method} does not allow ${mutation.rollback.mode} rollback`);
+        if (entry.sideEffect === "read" && mutation.rollback.mode === "irreversible")
+            throw new BrokerProtocolError("MUTATION_ROLLBACK_INVALID", `read-only host call ${method} cannot be declared irreversible`);
+    }
+    async captureEvidence(phase, request, command, target, context, plan, result) {
+        const measurement = await this.measure(request, command, target, context, plan, result);
+        validateEvidencePlan(plan, measurement);
+        const record = {
+            schema: "wowdump.broker.mutation-evidence.v1",
+            phase,
+            capturedAt: new Date().toISOString(),
+            requestId: request.requestId,
+            clientId: request.clientId,
+            pid: request.pid,
+            buildKey: request.buildKey,
+            operation: command.operation ?? null,
+            measurement
+        };
+        const body = Buffer.from(JSON.stringify(record), "utf8");
+        const sha256 = createHash("sha256").update(body).digest("hex");
+        await mkdir(this.evidenceDirectory, { recursive: true });
+        const path = join(this.evidenceDirectory, `${sanitize(request.requestId)}-${phase}-${randomUUID()}-${sha256.slice(0, 16)}.json`);
+        const handle = await open(path, "wx");
+        try {
+            await handle.writeFile(body);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return { path, size: body.length, sha256, schema: record.schema, phase };
+    }
+    async measure(request, command, target, context, plan, result) {
+        if (isRecord(plan) && isRecord(plan.command)) {
+            const evidenceCommand = deserializeCommand(plan.command);
+            if (!READ_ONLY_EVIDENCE_OPERATIONS.has(evidenceCommand.operation ?? ""))
+                throw new BrokerProtocolError("MUTATION_EVIDENCE_MISMATCH", "evidence command must be read-only");
+            await this.validateNestedCommand(evidenceCommand, request, target, context);
+            return toJson(await this.executor.execute(evidenceCommand, target));
+        }
+        if (command.operation === "write_memory" && command.address !== undefined && command.bytesHex) {
+            const evidenceCommand = { operation: "read_memory", sessionId: command.sessionId, address: command.address, size: Math.ceil(command.bytesHex.length / 2) };
+            await this.validateNestedCommand(evidenceCommand, request, target, context);
+            return toJson(await this.executor.execute(evidenceCommand, target));
+        }
+        return toJson({ resource: this.resourceMeasurement(command), result: result ?? null });
+    }
+    resourceMeasurement(command) {
+        const sourceHash = typeof command.source === "string" ? createHash("sha256").update(command.source).digest("hex") : null;
+        return { sessionId: command.sessionId ?? null, scriptId: command.scriptId ?? null, sourceSha256: sourceHash, exportName: command.exportName ?? null };
+    }
+    async rollbackMutation(request, command, mutation, target, context, rootError, evidence, executionResult) {
+        const rootMessage = errorText(rootError);
+        const residualStateEvidence = evidence.length > 0 ? evidence.map(reference => reference.path) : ["no-residual-evidence-captured"];
+        const manualVerification = "Reopen the recorded evidenceRefs and verify the target state against the expected effect.";
+        const manualRecoveryAction = "Do not replay the request; inspect residual-state evidence and restore the intended state manually.";
+        if (mutation.rollback.mode === "irreversible") {
+            context.transition("irreversible_failed", { error: toJson({ code: "MUTATION_EXECUTION_FAILED", rootError: rootMessage, residualStateEvidence, manualVerification, manualRecoveryAction }) });
+            return;
+        }
+        const deadline = Date.parse(mutation.rollback.deadline ?? "");
+        const plan = isRecord(mutation.rollback.plan) ? mutation.rollback.plan : undefined;
+        if (!Number.isFinite(deadline) || deadline < Date.now() || !plan || typeof plan.operation !== "string") {
+            context.transition("rollback_unavailable", { error: toJson({ code: "MUTATION_ROLLBACK_UNAVAILABLE", rootError: rootMessage, failedPrecondition: !plan ? "rollback plan is missing" : "rollback deadline is missing or expired", deadline: mutation.rollback.deadline ?? null, residualStateEvidence, manualVerification, manualRecoveryAction }) });
+            throw new BrokerProtocolError("MUTATION_ROLLBACK_UNAVAILABLE", "rollback deadline or executable plan is unavailable");
+        }
+        context.transition("rollback_started", { error: toJson({ rootError: errorText(rootError) }) });
+        try {
+            const rollbackCommand = deserializeCommand({ ...plan, ...(command.operation === "spawn" && typeof executionResult?.pid === "number" ? { pid: executionResult.pid } : {}) });
+            await this.validateNestedCommand(rollbackCommand, request, target, context);
+            const result = await this.executor.execute(rollbackCommand, target);
+            context.transition("rollback_executed", { result: toJson(result) });
+            assertMatches(mutation.rollback.successOracle, toJson(result), "rollback success oracle");
+            const reference = await this.captureEvidence("rollback", request, command, target, context, mutation.evidencePlan.rollback ?? {}, result);
+            evidence.push(reference);
+            context.transition("rollback_validated", { evidenceRefs: [reference.path], result: { evidence: toJson(evidence) } });
+            context.transition("rolled_back");
+        }
+        catch (rollbackError) {
+            context.transition("rollback_failed", { error: toJson({ code: "MUTATION_ROLLBACK_FAILED", rootError: rootMessage, rollbackError: errorText(rollbackError), residualStateEvidence, manualVerification, manualRecoveryAction }) });
+            throw new BrokerProtocolError("MUTATION_ROLLBACK_FAILED", "mutation and rollback both failed");
+        }
+    }
+}
+function validateEvidencePlan(plan, measurement) {
+    if (!isRecord(plan))
+        return;
+    if (plan.expected !== undefined)
+        assertMatches(plan.expected, measurement, "evidence expected value");
+    if (!isRecord(plan.schema) || !isRecord(measurement))
+        return;
+    const required = Array.isArray(plan.schema.required) ? plan.schema.required : [];
+    for (const key of required)
+        if (typeof key === "string" && !(key in measurement))
+            throw new BrokerProtocolError("MUTATION_EVIDENCE_MISMATCH", `evidence is missing required field ${key}`);
+    const properties = isRecord(plan.schema.properties) ? plan.schema.properties : {};
+    for (const [key, descriptor] of Object.entries(properties))
+        if (isRecord(descriptor) && typeof descriptor.type === "string" && key in measurement && jsonType(measurement[key]) !== descriptor.type)
+            throw new BrokerProtocolError("MUTATION_EVIDENCE_MISMATCH", `evidence field ${key} has the wrong type`);
+}
+function assertMatches(expected, actual, label) {
+    if (isRecord(expected)) {
+        if (!isRecord(actual))
+            throw new BrokerProtocolError("MUTATION_EVIDENCE_MISMATCH", `${label} expected an object`);
+        for (const [key, value] of Object.entries(expected)) {
+            if (!(key in actual))
+                throw new BrokerProtocolError("MUTATION_EVIDENCE_MISMATCH", `${label} is missing ${key}`);
+            assertMatches(value, actual[key], `${label}.${key}`);
+        }
+        return;
+    }
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual) || expected.length !== actual.length)
+            throw new BrokerProtocolError("MUTATION_EVIDENCE_MISMATCH", `${label} array mismatch`);
+        expected.forEach((value, index) => assertMatches(value, actual[index], `${label}[${index}]`));
+        return;
+    }
+    if (expected !== actual)
+        throw new BrokerProtocolError("MUTATION_EVIDENCE_MISMATCH", `${label} mismatch`);
+}
+function mergeEvidence(result, evidence) {
+    return isRecord(result) ? toJson({ ...result, brokerEvidence: evidence }) : toJson({ value: result, brokerEvidence: evidence });
+}
+function cleanupStepsFromResult(value, failure) {
+    const record = isRecord(value) ? value : {};
+    const raw = arrayOfRecords(record.cleanupSteps);
+    const cleanupStatus = isRecord(record.cleanupStatus) ? record.cleanupStatus : {};
+    const byName = new Map(raw.map(step => [String(step.step ?? ""), step]));
+    const failed = (names) => names.some(name => {
+        const step = byName.get(name);
+        return step && step.status !== "passed" && step.status !== "deferred";
+    });
+    const errorFor = (names) => names.map(name => byName.get(name)).find(step => step && step.status !== "passed" && step.status !== "deferred")?.error;
+    const cleanupResidual = Number(cleanupStatus.hooks ?? 0) !== 0 || Number(cleanupStatus.scripts ?? 0) !== 0 || Number(cleanupStatus.interceptors ?? 0) !== 0;
+    const groups = [
+        { step: "stop_gate", names: ["stop_accepting_events"] },
+        { step: "after_snapshot", names: ["after_snapshot", "append_after_snapshot"] },
+        { step: "trace_dispose", names: ["trace_dispose", "trace_hook_script_cleanup"] },
+        { step: "hook_cleanup", names: ["hook_cleanup", "trace_hook_script_cleanup"], residual: cleanupResidual },
+        { step: "script_unload", names: ["script_unload", "trace_hook_script_cleanup"], residual: cleanupResidual },
+        { step: "artifact_freeze", names: ["drain_append_queue", "stream_prefixes", "write_manifest", "final_stream_prefixes", "freeze_artifacts", "publish_terminal_failure", "quiesce_manifest_publications"] }
+    ];
+    return groups.map(group => {
+        const stepFailed = failure !== undefined || group.residual === true || failed(group.names);
+        const message = errorFor(group.names);
+        return {
+            step: group.step,
+            ok: !stepFailed,
+            ...(stepFailed ? { error: message ? String(message) : failure ? errorText(failure) : "cleanup residual remained" } : {})
+        };
+    });
+}
+function evidenceRefsFromFocusResult(value) {
+    const refs = new Set();
+    if (typeof value.artifactDirectory === "string")
+        refs.add(value.artifactDirectory);
+    if (isRecord(value.streamFiles))
+        for (const path of Object.values(value.streamFiles))
+            if (typeof path === "string")
+                refs.add(path);
+    return [...refs].sort();
+}
+function idFromResource(resourceId, prefix) { return resourceId.startsWith(prefix) ? resourceId.slice(prefix.length) : undefined; }
+function sanitize(value) { return value.replace(/[^A-Za-z0-9_.-]/g, "_"); }
+function jsonType(value) { return value === null ? "null" : Array.isArray(value) ? "array" : typeof value; }
+function isRecord(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function arrayOfRecords(value) { return Array.isArray(value) ? value.filter(isRecord) : []; }
+function processIdentityFromRecord(record) {
+    const parameters = isRecord(record.parameters) ? record.parameters : {};
+    const name = stringValue(record.name) ?? stringValue(record.processName) ?? stringValue(parameters.name) ?? "";
+    const executable = stringValue(record.executable) ?? stringValue(record.path) ?? stringValue(record.executablePath) ?? stringValue(parameters.executable) ?? stringValue(parameters.path) ?? stringValue(parameters.ExecutablePath);
+    const processStartTime = stringValue(record.processStartTime) ?? stringValue(record.startTime) ?? stringValue(record.creationTime) ?? stringValue(parameters.startTime) ?? stringValue(parameters.creationTime);
+    const buildKey = stringValue(record.buildKey) ?? stringValue(parameters.buildKey);
+    return {
+        pid: Number(record.pid),
+        name,
+        ...(executable ? { executable } : {}),
+        ...(processStartTime ? { processStartTime } : {}),
+        ...(buildKey ? { buildKey } : {})
+    };
+}
+function stringValue(value) { return typeof value === "string" && value.length > 0 ? value : undefined; }
+function canonicalPath(value) { return value.replace(/[\\/]+/g, "\\").replace(/^\\\?\\/, "").toLowerCase(); }
+function normalizeTime(value) { return value.trim().replace(/\.\d+(?=Z$)/i, "").toLowerCase(); }
+function normalizeHex(value) {
+    const text = value.trim();
+    if (!/^0x[0-9a-f]+$/i.test(text))
+        throw new BrokerProtocolError("MODULE_NOT_FOUND", `invalid module base ${value}`);
+    return `0x${text.slice(2).toLowerCase()}`;
+}
+function identityResourceFields(identity) {
+    return {
+        ...(identity.executable ? { executable: identity.executable } : {}),
+        ...(identity.processStartTime ? { processStartTime: identity.processStartTime } : {}),
+        moduleBase: identity.moduleBase,
+        moduleIdentity: identity.moduleIdentity
+    };
+}
+function sameCaptureIdentity(left, right) {
+    try {
+        const sameOptional = (a, b, normalize) => a === undefined && b === undefined || a !== undefined && b !== undefined && normalize(a) === normalize(b);
+        return sameOptional(left.executable, right.executable, canonicalPath)
+            && sameOptional(left.processStartTime, right.processStartTime, normalizeTime)
+            && sameOptional(left.moduleBase, right.moduleBase, normalizeHex)
+            && sameOptional(left.moduleIdentity, right.moduleIdentity, value => value);
+    }
+    catch {
+        return false;
+    }
+}
+function assertStableIdentity(expected, actual) {
+    if (expected.pid !== actual.pid)
+        throw new BrokerProtocolError("PID_REUSED", `PID changed from ${expected.pid} to ${actual.pid}`);
+    if (expected.buildKey !== actual.buildKey)
+        throw new BrokerProtocolError("PID_BUILD_MISMATCH", `build changed from ${expected.buildKey} to ${actual.buildKey}`);
+    if (expected.executable && (!actual.executable || canonicalPath(expected.executable) !== canonicalPath(actual.executable)))
+        throw new BrokerProtocolError("PID_REUSED", "executable identity changed");
+    if (expected.processStartTime && (!actual.processStartTime || normalizeTime(expected.processStartTime) !== normalizeTime(actual.processStartTime)))
+        throw new BrokerProtocolError("PID_REUSED", "process start time changed");
+    if (normalizeHex(expected.moduleBase) !== normalizeHex(actual.moduleBase) || expected.moduleIdentity !== actual.moduleIdentity)
+        throw new BrokerProtocolError("MODULE_NOT_FOUND", "Wow.exe module identity changed");
+}
+function deserializeCommand(value) { return { ...value }; }
+function deserializeContext(value) {
+    const context = {};
+    if (typeof value.pid === "number")
+        context.pid = value.pid;
+    if (typeof value.buildKey === "string")
+        context.buildKey = value.buildKey;
+    if (typeof value.flavor === "string")
+        context.flavor = value.flavor;
+    if (typeof value.executable === "string")
+        context.executable = value.executable;
+    if (typeof value.processStartTime === "string")
+        context.processStartTime = value.processStartTime;
+    if (typeof value.moduleBase === "string")
+        context.moduleBase = value.moduleBase;
+    if (typeof value.moduleIdentity === "string")
+        context.moduleIdentity = value.moduleIdentity;
+    if (context.buildKey)
+        context.adapter = buildAdapterRegistry.lookup(context.buildKey);
+    return context;
+}
+function toJson(value) {
+    return JSON.parse(JSON.stringify(value, (_key, child) => typeof child === "bigint" ? child.toString() : child === undefined ? null : child));
+}
+function errorText(error) { return error instanceof Error ? error.message : String(error); }
+function assertFocusEnvelope(request, input) {
+    if (input.pid !== undefined && input.pid !== request.pid)
+        throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", "focus payload pid differs from Broker envelope");
+    if (input.buildKey !== undefined && input.buildKey !== request.buildKey)
+        throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", "focus payload buildKey differs from Broker envelope");
+}