wowdump 0.2.1 → 0.3.2

package/dist/broker-core.js

@@ -1,1045 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { BROKER_PROTOCOL_VERSION, BROKER_SCHEMA_VERSION, BrokerProtocolError, canonicalPayloadHash, validateRequest } from "./broker-protocol.js";
-import { FileBrokerLedgerStore } from "./broker-ledger.js";
-export const systemBrokerClock = {
-    now: () => performance.now(),
-    setTimeout: (callback, delayMs) => {
-        const timer = setTimeout(callback, delayMs);
-        timer.unref();
-        return timer;
-    },
-    clearTimeout: handle => clearTimeout(handle)
-};
-const TERMINAL = new Set(["completed", "before_failed", "rolled_back", "rollback_unavailable", "rollback_failed", "irreversible_failed", "outcome_unknown"]);
-const CLEANUP_STEPS = ["stop_gate", "after_snapshot", "trace_dispose", "hook_cleanup", "script_unload", "artifact_freeze", "ref_release", "attachment_detach"];
-const RELEVANT_STEPS = {
-    session: CLEANUP_STEPS.slice(0, 7), trace: ["stop_gate", "after_snapshot", "trace_dispose", "artifact_freeze", "ref_release"],
-    interceptor: ["stop_gate", "hook_cleanup", "ref_release"], hook: ["stop_gate", "hook_cleanup", "ref_release"],
-    script: ["stop_gate", "script_unload", "ref_release"], handle: ["ref_release"], attachment: ["ref_release", "attachment_detach"]
-};
-const ALLOWED_TRANSITIONS = {
-    validated: new Set(["before_captured", "executing", "completed", "before_failed", "outcome_unknown"]),
-    before_captured: new Set(["executing", "before_failed", "outcome_unknown"]),
-    executing: new Set(["executed", "after_validated", "completed", "outcome_unknown", "rollback_started", "rollback_unavailable", "rollback_failed", "irreversible_failed"]),
-    executed: new Set(["after_validated", "completed", "outcome_unknown", "rollback_started", "rollback_unavailable", "rollback_failed", "irreversible_failed"]),
-    after_validated: new Set(["completed", "rollback_started", "outcome_unknown"]),
-    completed: new Set(),
-    before_failed: new Set(),
-    rollback_started: new Set(["rollback_executed", "rollback_unavailable", "rollback_failed", "outcome_unknown"]),
-    rollback_executed: new Set(["rollback_validated", "rollback_failed", "outcome_unknown"]),
-    rollback_validated: new Set(["rolled_back", "rollback_failed", "outcome_unknown"]),
-    rolled_back: new Set(),
-    rollback_unavailable: new Set(),
-    rollback_failed: new Set(),
-    irreversible_failed: new Set(),
-    outcome_unknown: new Set()
-};
-export class BrokerCore {
-    options;
-    instanceId = randomUUID();
-    startedAt;
-    ledger = new Map();
-    resources = new Map();
-    clients = new Map();
-    lastAcceptedRequestAt;
-    lastAcceptedRequestId = null;
-    timer;
-    accepting = true;
-    shutdownPromise;
-    clock;
-    idleTimeoutMs;
-    runningByClient = new Map();
-    queuesByClient = new Map();
-    activeRequests = new Set();
-    drainWaiters = new Set();
-    requestCancellers = new Map();
-    lifecycleTail = Promise.resolve();
-    lifecycleFailure;
-    ledgerStore;
-    cleanupDeadlines = new Map();
-    constructor(options) {
-        this.options = options;
-        this.clock = options.clock ?? systemBrokerClock;
-        this.idleTimeoutMs = options.idleTimeoutMs ?? 1_200_000;
-        this.startedAt = this.lastAcceptedRequestAt = this.clock.now();
-        options.runtime.bindFatalHandlers?.({
-            captureFatal: (sessionId, pid, buildKey, error) => this.handleCaptureFatal(sessionId, pid, buildKey, error),
-            durationExpired: (sessionId, pid, buildKey) => this.handleCaptureExpiry(sessionId, pid, buildKey),
-            attachmentFatal: (pid, buildKey) => this.handleTargetExit(pid, buildKey),
-            brokerFatal: reason => this.shutdown(reason),
-        });
-        if (options.ledgerPath) {
-            this.ledgerStore = new FileBrokerLedgerStore(options.ledgerPath);
-            for (const [requestId, entry] of this.ledgerStore.load())
-                this.ledger.set(requestId, entry);
-            for (const entry of this.ledger.values()) {
-                if (!entry.terminal)
-                    this.transition(entry, "outcome_unknown", { error: { code: "MUTATION_OUTCOME_UNKNOWN", message: "Broker restarted before the durable request outcome was recorded", nextAction: "Inspect evidence and reconcile before retrying." } });
-            }
-        }
-        this.armIdleTimer();
-    }
-    connectClient(clientId) {
-        const now = this.clock.now();
-        if (!this.clients.has(clientId)) {
-            if (this.clients.size >= (this.options.maxClients ?? 32))
-                throw new BrokerProtocolError("REQUEST_CANCELLED", "Broker client limit reached", "Release an inactive Broker client and retry.");
-            this.clients.set(clientId, { connectedAt: now, lastActivityAt: now, inFlight: 0 });
-            this.emit({ action: "client_connected", clientId, status: "passed" });
-        }
-    }
-    async accept(raw) {
-        if (!this.accepting)
-            return this.failure(requestIdOf(raw), "BROKER_STOPPED", "Broker is shutting down", "Reconnect to a new Broker instance.");
-        let request;
-        try {
-            request = validateRequest(raw);
-        }
-        catch (error) {
-            return this.failure(requestIdOf(raw), error);
-        }
-        const hash = canonicalPayloadHash(request);
-        const prior = this.ledger.get(request.requestId);
-        if (prior) {
-            if (prior.payloadHash !== hash)
-                return this.failure(request.requestId, "REQUEST_ID_REPLAYED", "requestId is already bound to different content", "Use request_status or a fresh requestId.");
-            const response = this.responseFor(prior);
-            await this.flushLifecycle();
-            return response;
-        }
-        try {
-            this.connectClient(request.clientId);
-        }
-        catch (error) {
-            return this.failure(request.requestId, error);
-        }
-        const client = this.clients.get(request.clientId);
-        const now = this.clock.now();
-        client.lastActivityAt = now;
-        client.inFlight += 1;
-        this.lastAcceptedRequestAt = now;
-        this.lastAcceptedRequestId = request.requestId;
-        this.armIdleTimer();
-        const entry = {
-            requestId: request.requestId, clientId: request.clientId, operation: request.operation,
-            pid: request.pid, buildKey: request.buildKey, payloadHash: hash, acceptedAt: now,
-            state: "validated", terminal: false, evidenceRefs: [], transitions: [{ state: "validated", timestamp: now, evidenceRefs: [] }],
-            ...requestCorrelation(request),
-            ...mutationMetadata(request)
-        };
-        try {
-            this.persistLedger(entry);
-        }
-        catch (error) {
-            client.inFlight = Math.max(0, client.inFlight - 1);
-            return this.failure(request.requestId, error, undefined, undefined, request);
-        }
-        this.ledger.set(request.requestId, entry);
-        this.activeRequests.add(request.requestId);
-        const pruning = this.pruneLedger();
-        if (pruning)
-            await pruning;
-        this.emit({ action: "request_accepted", clientId: request.clientId, requestId: request.requestId, operation: request.operation, pid: request.pid, buildKey: request.buildKey, sessionId: entry.sessionId ?? null, resourceId: entry.resourceId ?? null, status: "started" });
-        let executionSlot = false;
-        try {
-            await this.acquireExecutionSlot(request.clientId);
-            executionSlot = true;
-            if (request.operation === "request_status") {
-                const response = this.complete(entry, this.requestStatus(String(request.payload.requestId ?? "")));
-                await this.flushLifecycle();
-                return response;
-            }
-            if (request.operation === "client_release") {
-                await this.releaseClient(request.clientId, request.requestId);
-                const residualResourceIds = [...this.resources.values()]
-                    .filter(resource => (resource.refs.get(request.clientId) ?? 0) > 0)
-                    .map(resource => resource.resourceId);
-                const remainingResourceRefs = [...this.resources.values()]
-                    .reduce((sum, resource) => sum + (resource.refs.get(request.clientId) ?? 0), 0);
-                const lastClientReleased = this.clients.size === 0;
-                const response = this.complete(entry, {
-                    released: residualResourceIds.length === 0 && remainingResourceRefs === 0,
-                    clientId: request.clientId,
-                    remainingResourceRefs,
-                    residualResourceIds,
-                    brokerRetained: true,
-                    shutdownReason: null,
-                    idleDeadline: this.lastAcceptedRequestAt + this.idleTimeoutMs
-                });
-                await this.flushLifecycle();
-                if (lastClientReleased)
-                    this.armIdleTimer();
-                return response;
-            }
-            if (request.operation === "broker_stop") {
-                const response = this.complete(entry, { stopping: true, reason: String(request.payload.reason ?? "requested") });
-                await this.shutdown(String(request.payload.reason ?? "requested"), request.requestId);
-                await this.flushLifecycle();
-                return response;
-            }
-            const result = await this.executeRuntime(request, {
-                registerResource: input => this.registerResource(input),
-                acquireResource: (resourceId, clientId) => this.acquireResource(resourceId, clientId),
-                releaseResource: (resourceId, clientId, expectedType, reason) => this.releaseResource(resourceId, clientId, reason, expectedType),
-                requireOwnedResource: (resourceId, clientId, expectedType) => this.requireOwnedResource(resourceId, clientId, expectedType),
-                transition: (state, data) => this.transition(entry, state, data)
-            });
-            const response = this.complete(entry, result);
-            await this.flushLifecycle();
-            return response;
-        }
-        catch (error) {
-            const failure = errorJson(error);
-            if (!entry.terminal) {
-                const failureState = entry.state === "executing" || entry.state === "executed" ? "outcome_unknown" : "before_failed";
-                this.transition(entry, failureState, { error: failure });
-            }
-            else if (entry.state !== "outcome_unknown" && entry.error === undefined) {
-                entry.error = failure;
-                this.persistLedger(entry);
-            }
-            const mutation = Boolean(entry.mutationPlanId);
-            this.emit({
-                action: mutation ? "mutation_failed" : "request_failed",
-                clientId: entry.clientId,
-                requestId: entry.requestId,
-                operation: entry.operation,
-                pid: entry.pid,
-                buildKey: entry.buildKey,
-                sessionId: entry.sessionId ?? null,
-                resourceId: entry.resourceId ?? null,
-                status: "failed",
-                error: entry.error,
-                mutationPlanId: entry.mutationPlanId ?? null,
-                confirmationNonce: entry.confirmationNonce ?? null,
-                rollbackMode: entry.rollbackMode ?? null,
-                evidenceRefs: [...entry.evidenceRefs],
-                literalResult: entry.result ?? null,
-                exitStatus: null,
-                nextAction: "Query request_status before retrying.",
-                result: mutation ? mutationLifecycleResult(entry, entry.result ?? null, "Query request_status before retrying.") : focusedLifecycleProjection(entry, entry.result, entry.error)
-            });
-            await this.flushLifecycle();
-            return this.failure(request.requestId, error, undefined, undefined, request);
-        }
-        finally {
-            if (executionSlot)
-                this.releaseExecutionSlot(request.clientId);
-            client.inFlight = Math.max(0, client.inFlight - 1);
-            this.activeRequests.delete(request.requestId);
-            for (const wake of this.drainWaiters)
-                wake();
-            if (this.clock.now() - this.lastAcceptedRequestAt >= this.idleTimeoutMs)
-                this.onIdleTimer();
-        }
-    }
-    requestStatus(requestId) {
-        const entry = this.ledger.get(requestId);
-        if (!entry)
-            throw new BrokerProtocolError("REQUEST_NOT_FOUND", `request ${requestId} was not found`, "Check the requestId and Broker instance.");
-        const failed = new Set(["before_failed", "rollback_unavailable", "rollback_failed", "irreversible_failed"]);
-        return {
-            requestId, state: entry.state,
-            status: entry.state === "outcome_unknown" ? "outcome_unknown" : entry.state === "completed" || entry.state === "rolled_back" ? "completed" : failed.has(entry.state) ? "failed" : "pending",
-            phase: entry.state, terminal: entry.terminal, result: entry.result ?? null, error: entry.error ?? null,
-            evidenceRefs: entry.evidenceRefs, sessionId: entry.sessionId ?? null, resourceId: entry.resourceId ?? null
-        };
-    }
-    registerResource(input) {
-        const resourceId = input.resourceId ?? `${input.type}-${randomUUID()}`;
-        if (this.resources.has(resourceId))
-            throw new Error(`resource ${resourceId} already exists`);
-        const ancestors = [];
-        if (input.parentResourceId) {
-            let parentId = input.parentResourceId;
-            while (parentId) {
-                const parent = this.requireOwnedResource(parentId, input.ownerClientId);
-                if (parent.pid !== input.pid || parent.buildKey !== input.buildKey) {
-                    throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", `parent ${parentId} does not share target scope`);
-                }
-                ancestors.push(parent);
-                parentId = parent.parentResourceId;
-            }
-        }
-        const resource = { ...input, resourceId, refs: new Map([[input.ownerClientId, 1]]), cleanupState: "active" };
-        try {
-            for (const ancestor of ancestors)
-                ancestor.refs.set(input.ownerClientId, (ancestor.refs.get(input.ownerClientId) ?? 0) + 1);
-            this.resources.set(resourceId, resource);
-        }
-        catch (error) {
-            for (const ancestor of ancestors.reverse())
-                decrementRef(ancestor, input.ownerClientId);
-            throw error;
-        }
-        return resource;
-    }
-    acquireResource(resourceId, clientId) {
-        const resource = this.requireResource(resourceId);
-        if (resource.cleanupState !== "active")
-            throw new BrokerProtocolError("RESOURCE_ALREADY_RELEASED", `${resourceId} is not active`);
-        const acquiredParents = [];
-        let parentId = resource.parentResourceId;
-        try {
-            while (parentId) {
-                const parent = this.requireResource(parentId);
-                if (parent.cleanupState !== "active" || parent.pid !== resource.pid || parent.buildKey !== resource.buildKey) {
-                    throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", `${resourceId} parent graph is not active in the same scope`);
-                }
-                parent.refs.set(clientId, (parent.refs.get(clientId) ?? 0) + 1);
-                acquiredParents.push(parent);
-                parentId = parent.parentResourceId;
-            }
-        }
-        catch (error) {
-            for (const parent of acquiredParents.reverse())
-                decrementRef(parent, clientId);
-            throw error;
-        }
-        resource.refs.set(clientId, (resource.refs.get(clientId) ?? 0) + 1);
-        return resource;
-    }
-    requireOwnedResource(resourceId, clientId, expectedType) {
-        const resource = this.requireResource(resourceId);
-        if (resource.cleanupState !== "active")
-            throw new BrokerProtocolError("RESOURCE_ALREADY_RELEASED", `${resourceId} is not active`);
-        if (!resource.refs.has(clientId))
-            throw new BrokerProtocolError("RESOURCE_NOT_OWNER", `${clientId} does not own ${resourceId}`);
-        if (expectedType && resource.type !== expectedType)
-            throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", `${resourceId} is not a ${expectedType} resource`);
-        return resource;
-    }
-    async releaseResource(resourceId, clientId, reason = "client_release", expectedType, outerDeadline = Number.POSITIVE_INFINITY) {
-        const resource = this.requireResource(resourceId);
-        if (resource.cleanupState === "released" || resource.cleanupState === "cleaning")
-            throw new BrokerProtocolError("RESOURCE_ALREADY_RELEASED", `${resourceId} is not available for release`);
-        if (expectedType && resource.type !== expectedType)
-            throw new BrokerProtocolError("SESSION_TARGET_MISMATCH", `${resourceId} is not a ${expectedType} resource`);
-        if (!resource.refs.has(clientId))
-            throw new BrokerProtocolError("RESOURCE_NOT_OWNER", `${clientId} does not own ${resourceId}`);
-        const count = resource.refs.get(clientId);
-        if (count <= 0)
-            throw new BrokerProtocolError("RESOURCE_REF_UNDERFLOW", `${resourceId} refcount would underflow`);
-        const failures = [];
-        const isLastLease = resource.refs.size === 1 && count === 1;
-        let releasedLease = false;
-        if (isLastLease) {
-            const records = [];
-            await this.cleanupResource(resource, reason, records, outerDeadline);
-            if (resource.cleanupState === "failed") {
-                failures.push(new BrokerProtocolError("CLEANUP_TIMEOUT", `${resourceId} cleanup failed: ${resource.cleanupErrors?.map(item => `${item.step}: ${item.error}`).join("; ") ?? "unknown error"}`, "Inspect residual resource state before retrying cleanup."));
-            }
-            else
-                releasedLease = true;
-        }
-        else {
-            decrementRef(resource, clientId);
-            releasedLease = true;
-        }
-        if (resource.parentResourceId && releasedLease) {
-            try {
-                await this.releaseResource(resource.parentResourceId, clientId, `${reason}:child_ref`, undefined, outerDeadline);
-            }
-            catch (error) {
-                failures.push(error);
-            }
-        }
-        if (failures.length === 1)
-            throw failures[0];
-        if (failures.length > 1)
-            throw new BrokerProtocolError("CLEANUP_TIMEOUT", failures.map(error => error instanceof Error ? error.message : String(error)).join("; "), "Inspect residual resource state before retrying cleanup.");
-        return resource;
-    }
-    async releaseClient(clientId, excludeRequestId) {
-        const owned = [...this.resources.values()].filter(resource => resource.refs.has(clientId));
-        owned.sort((a, b) => resourceDepth(b, this.resources) - resourceDepth(a, this.resources));
-        const deadline = this.clock.now() + (this.options.sessionCleanupTimeoutMs ?? 2_000);
-        const cleanupRecords = [];
-        const failedScopes = await this.prepareCaptureScopes(owned, "lease_release", cleanupRecords, deadline);
-        if (failedScopes.size > 0) {
-            throw new BrokerProtocolError("CLEANUP_TIMEOUT", `capture cleanup failed for ${[...failedScopes].join(",")}`, "Retry client release after inspecting the frozen residual evidence.");
-        }
-        let cleanupFailure = false;
-        for (const resource of owned) {
-            const count = resource.refs.get(clientId) ?? 0;
-            for (let index = 0; index < count; index += 1) {
-                try {
-                    await this.releaseResource(resource.resourceId, clientId, "lease_release", undefined, deadline);
-                }
-                catch (error) {
-                    cleanupFailure = true;
-                    cleanupRecords.push({ resourceId: resource.resourceId, step: "ref_release", ok: false, error: errorText(error) });
-                }
-            }
-        }
-        for (const scopeId of new Set(owned.map(resource => resource.cleanupScopeId).filter((value) => Boolean(value)))) {
-            if (!await this.completeCaptureScope(scopeId, "lease_release", deadline, cleanupRecords))
-                cleanupFailure = true;
-        }
-        if (!await this.releaseRuntimeClient(clientId, deadline, cleanupRecords))
-            cleanupFailure = true;
-        if (cleanupFailure) {
-            throw new BrokerProtocolError("CLEANUP_TIMEOUT", `client release cleanup failed: ${cleanupRecords.filter(item => !item.ok).map(item => `${item.resourceId}:${item.error}`).join("; ")}`, "Inspect residual resource state and retry client release.");
-        }
-        this.clients.delete(clientId);
-        this.emit({ action: "client_released", clientId, status: "passed" });
-    }
-    async shutdown(reason, excludeRequestId) {
-        if (this.shutdownPromise)
-            return this.shutdownPromise;
-        this.accepting = false;
-        if (this.timer !== undefined)
-            this.clock.clearTimeout(this.timer);
-        this.shutdownPromise = (async () => {
-            const result = { reason, cleanupOrder: [] };
-            const brokerDeadline = this.clock.now() + (this.options.brokerCleanupTimeoutMs ?? 10_000);
-            this.emit({ action: "shutdown_started", status: "started", result: { reason } });
-            const preparedScopes = new Set();
-            const failedScopes = await this.prepareCaptureScopes([...this.resources.values()], reason, result.cleanupOrder, brokerDeadline, preparedScopes);
-            await this.drainInFlight(brokerDeadline, excludeRequestId, result.cleanupOrder);
-            for (const scope of await this.prepareCaptureScopes([...this.resources.values()], reason, result.cleanupOrder, brokerDeadline, preparedScopes))
-                failedScopes.add(scope);
-            const resources = [...this.resources.values()].sort((a, b) => resourceDepth(b, this.resources) - resourceDepth(a, this.resources));
-            for (const resource of resources) {
-                if (resource.cleanupState !== "active" && resource.cleanupState !== "failed")
-                    continue;
-                if (resource.cleanupScopeId && failedScopes.has(resource.cleanupScopeId))
-                    continue;
-                const blockers = this.unreleasedChildren(resource.resourceId);
-                if (blockers.length > 0) {
-                    this.markResidualParent(resource, blockers);
-                    result.cleanupOrder.push({ resourceId: resource.resourceId, step: "ref_release", ok: false, error: `CHILD_RESOURCE_RESIDUAL:${blockers.join(",")}` });
-                    continue;
-                }
-                await this.cleanupResource(resource, reason, result.cleanupOrder, brokerDeadline);
-            }
-            for (const scopeId of preparedScopes) {
-                if (!failedScopes.has(scopeId))
-                    await this.completeCaptureScope(scopeId, reason, brokerDeadline, result.cleanupOrder);
-            }
-            await this.shutdownStep(result, "server_close", brokerDeadline, () => this.options.closeServer?.());
-            await this.shutdownStep(result, "runtime_close", brokerDeadline, () => this.options.runtime.close?.());
-            await this.shutdownStep(result, "lock_release", brokerDeadline, () => this.options.releaseSingleton?.());
-            await this.shutdownStep(result, "on_shutdown", brokerDeadline, () => this.options.onShutdown?.(result, this.cleanupContext(brokerDeadline, brokerDeadline)));
-            await this.shutdownStep(result, "ledger_close", brokerDeadline, () => this.ledgerStore?.close());
-            this.emit({ action: "shutdown_completed", status: result.cleanupOrder.some(item => !item.ok) ? "partial" : "passed", result: { reason, cleanupSteps: result.cleanupOrder.length } });
-            await this.shutdownStep(result, "lifecycle_flush", brokerDeadline, () => this.flushLifecycle());
-            return result;
-        })();
-        return this.shutdownPromise;
-    }
-    status() {
-        return { instanceId: this.instanceId, protocolVersion: BROKER_PROTOCOL_VERSION, startedAt: this.startedAt, uptimeMs: this.clock.now() - this.startedAt, idleTimeoutMs: this.idleTimeoutMs, idleDeadline: this.lastAcceptedRequestAt + this.idleTimeoutMs, lastAcceptedRequestId: this.lastAcceptedRequestId, clients: [...this.clients.entries()].map(([clientId, value]) => ({ clientId, ...value })), inFlight: [...this.clients.values()].reduce((sum, client) => sum + client.inFlight, 0), resources: [...this.resources.values()].map(resource => ({ resourceId: resource.resourceId, type: resource.type, pid: resource.pid, buildKey: resource.buildKey, refcount: [...resource.refs.values()].reduce((sum, count) => sum + count, 0), cleanupState: resource.cleanupState })), ledgerEntries: this.ledger.size, accepting: this.accepting };
-    }
-    async handleTargetExit(pid, buildKey) {
-        const affected = [...this.resources.values()].filter(resource => resource.pid === pid && (buildKey === null || resource.buildKey === buildKey));
-        affected.sort((a, b) => resourceDepth(b, this.resources) - resourceDepth(a, this.resources));
-        const deadline = this.clock.now() + (this.options.sessionCleanupTimeoutMs ?? 2_000);
-        const records = [];
-        const failedScopes = await this.prepareCaptureScopes(affected, "target_exit", records, deadline);
-        for (const resource of affected) {
-            if (resource.cleanupScopeId && failedScopes.has(resource.cleanupScopeId))
-                continue;
-            const blockers = this.unreleasedChildren(resource.resourceId);
-            if (blockers.length > 0) {
-                this.markResidualParent(resource, blockers);
-                records.push({ resourceId: resource.resourceId, step: "ref_release", ok: false, error: `CHILD_RESOURCE_RESIDUAL:${blockers.join(",")}` });
-                continue;
-            }
-            await this.cleanupResource(resource, "target_exit", records, deadline);
-        }
-        for (const scopeId of new Set(affected.map(resource => resource.cleanupScopeId).filter((value) => Boolean(value))))
-            if (!failedScopes.has(scopeId))
-                await this.completeCaptureScope(scopeId, "target_exit", deadline, records);
-        this.emit({ action: "attachment_fatal", pid, buildKey, status: records.some(record => !record.ok) ? "partial" : "failed", error: { failureClass: "attachment_fatal", errorCode: "ATTACHMENT_FATAL", scope: "attachment" }, result: { cleanup: records } });
-    }
-    async handleCaptureFatal(sessionId, pid, buildKey, error) {
-        await this.terminateCaptureScope(sessionId, pid, buildKey, "capture_fatal", error);
-    }
-    async handleCaptureExpiry(sessionId, pid, buildKey) {
-        await this.terminateCaptureScope(sessionId, pid, buildKey, "duration_expired");
-    }
-    async terminateCaptureScope(sessionId, pid, buildKey, reason, error) {
-        const affected = [...this.resources.values()].filter(resource => resource.cleanupScopeId === sessionId && resource.pid === pid && resource.buildKey === buildKey);
-        const records = [];
-        const deadline = this.clock.now() + (this.options.sessionCleanupTimeoutMs ?? 2_000);
-        const failedScopes = await this.prepareCaptureScopes(affected, reason, records, deadline);
-        if (failedScopes.has(sessionId)) {
-            this.emit(reason === "capture_fatal"
-                ? { action: "capture_fatal", sessionId, pid, buildKey, status: "partial", error: { failureClass: "capture_fatal", errorCode: "CAPTURE_FATAL", scope: "session", message: error instanceof Error ? error.message : error === undefined ? null : String(error) }, result: { cleanup: records } }
-                : { action: "duration_expired", sessionId, pid, buildKey, status: "partial", result: { cleanup: records } });
-            return;
-        }
-        affected.sort((a, b) => resourceDepth(b, this.resources) - resourceDepth(a, this.resources));
-        const session = affected.find(resource => resource.type === "session");
-        const ownerClientId = session?.ownerClientId;
-        const attachmentResourceId = session?.parentResourceId;
-        if (ownerClientId) {
-            for (const resource of affected) {
-                if (!resource.refs.has(ownerClientId))
-                    continue;
-                try {
-                    await this.releaseResource(resource.resourceId, ownerClientId, reason, resource.type, deadline);
-                }
-                catch (releaseError) {
-                    records.push({ resourceId: resource.resourceId, step: "ref_release", ok: false, error: releaseError instanceof Error ? releaseError.message : String(releaseError) });
-                }
-            }
-            if (attachmentResourceId) {
-                try {
-                    await this.releaseResource(attachmentResourceId, ownerClientId, `${reason}:attachment_ref`, "attachment", deadline);
-                }
-                catch (releaseError) {
-                    records.push({ resourceId: attachmentResourceId, step: "ref_release", ok: false, error: releaseError instanceof Error ? releaseError.message : String(releaseError) });
-                }
-            }
-        }
-        await this.completeCaptureScope(sessionId, reason, deadline, records);
-        if (reason === "capture_fatal") {
-            this.emit({
-                action: "capture_fatal",
-                sessionId,
-                pid,
-                buildKey,
-                status: records.some(record => !record.ok) ? "partial" : "failed",
-                error: { failureClass: "capture_fatal", errorCode: "CAPTURE_FATAL", scope: "session", message: error instanceof Error ? error.message : error === undefined ? null : String(error) },
-                result: { cleanup: records }
-            });
-        }
-        else {
-            this.emit({ action: "duration_expired", sessionId, pid, buildKey, status: records.some(record => !record.ok) ? "partial" : "passed", result: { cleanup: records } });
-        }
-    }
-    unreleasedChildren(resourceId) {
-        return [...this.resources.values()]
-            .filter(candidate => candidate.parentResourceId === resourceId && candidate.cleanupState !== "released")
-            .map(candidate => candidate.resourceId)
-            .sort();
-    }
-    markResidualParent(resource, blockers) {
-        resource.cleanupState = "failed";
-        const marker = `CHILD_RESOURCE_RESIDUAL:${blockers.join(",")}`;
-        if (!(resource.cleanupErrors ?? []).some(error => error.step === "ref_release" && error.error === marker))
-            (resource.cleanupErrors ??= []).push({ step: "ref_release", error: marker });
-    }
-    transition(entry, state, data = {}) {
-        if (entry.state !== state && !ALLOWED_TRANSITIONS[entry.state].has(state))
-            throw new BrokerProtocolError("BROKER_FATAL", `invalid ledger transition ${entry.state} -> ${state}`, "Inspect request_status and Broker lifecycle evidence.");
-        const previousTimestamp = entry.transitions.at(-1)?.timestamp ?? this.clock.now();
-        const timestamp = Math.max(previousTimestamp, this.clock.now());
-        entry.state = state;
-        if (Object.hasOwn(data, "result"))
-            entry.result = data.result;
-        if (Object.hasOwn(data, "error"))
-            entry.error = data.error;
-        if (data.evidenceRefs)
-            entry.evidenceRefs.push(...data.evidenceRefs);
-        entry.transitions.push({ state, timestamp, result: data.result, error: data.error, evidenceRefs: data.evidenceRefs ? [...data.evidenceRefs] : [] });
-        if (TERMINAL.has(state))
-            this.makeTerminal(entry);
-        this.persistLedger(entry);
-        if (state === "executing" && entry.mutationPlanId) {
-            const nextAction = "Complete operation and validate after evidence.";
-            this.emit({
-                action: "mutation_started",
-                clientId: entry.clientId,
-                requestId: entry.requestId,
-                operation: entry.operation,
-                pid: entry.pid,
-                buildKey: entry.buildKey,
-                status: "started",
-                mutationPlanId: entry.mutationPlanId,
-                confirmationNonce: entry.confirmationNonce ?? null,
-                rollbackMode: entry.rollbackMode ?? null,
-                evidenceRefs: [...entry.evidenceRefs],
-                literalResult: null,
-                exitStatus: null,
-                nextAction,
-                result: mutationLifecycleResult(entry, null, nextAction)
-            });
-        }
-    }
-    complete(entry, result) {
-        updateEntryCorrelation(entry, result);
-        this.transition(entry, "completed", { result });
-        const nextAction = entry.mutationPlanId ? "Reopen evidenceRefs and verify hashes." : undefined;
-        this.emit({
-            action: entry.mutationPlanId ? "mutation_completed" : "request_completed",
-            clientId: entry.clientId,
-            requestId: entry.requestId,
-            operation: entry.operation,
-            pid: entry.pid,
-            buildKey: entry.buildKey,
-            sessionId: entry.sessionId ?? null,
-            resourceId: entry.resourceId ?? null,
-            status: "passed",
-            mutationPlanId: entry.mutationPlanId ?? null,
-            confirmationNonce: entry.confirmationNonce ?? null,
-            rollbackMode: entry.rollbackMode ?? null,
-            evidenceRefs: [...entry.evidenceRefs],
-            literalResult: entry.mutationPlanId ? result : null,
-            exitStatus: entry.mutationPlanId ? 0 : undefined,
-            nextAction,
-            result: entry.mutationPlanId ? mutationLifecycleResult(entry, result, nextAction) : focusedLifecycleProjection(entry, result)
-        });
-        return { schemaVersion: BROKER_SCHEMA_VERSION, protocolVersion: BROKER_PROTOCOL_VERSION, requestId: entry.requestId, ok: true, result };
-    }
-    makeTerminal(entry) { entry.terminal = true; entry.terminalAt = this.clock.now(); }
-    responseFor(entry) {
-        if (entry.error && typeof entry.error === "object" && !Array.isArray(entry.error)) {
-            const error = entry.error;
-            return this.failure(entry.requestId, typeof error.code === "string" ? error.code : "BROKER_FATAL", typeof error.message === "string" ? error.message : "Broker request failed", typeof error.nextAction === "string" ? error.nextAction : undefined, { operation: entry.operation, pid: entry.pid, buildKey: entry.buildKey });
-        }
-        return { schemaVersion: 1, protocolVersion: BROKER_PROTOCOL_VERSION, requestId: entry.requestId, ok: true, result: Object.hasOwn(entry, "result") ? entry.result : this.requestStatus(entry.requestId) };
-    }
-    failure(requestId, codeOrError, message, nextAction, request) {
-        const error = codeOrError instanceof BrokerProtocolError ? codeOrError : typeof codeOrError === "string" ? new BrokerProtocolError(codeOrError, message ?? codeOrError, nextAction) : new BrokerProtocolError("BROKER_FATAL", codeOrError instanceof Error ? codeOrError.message : String(codeOrError));
-        const metadata = failureMetadata(error.code);
-        return { schemaVersion: 1, protocolVersion: BROKER_PROTOCOL_VERSION, requestId, ok: false, error: { code: error.code, message: error.message, nextAction: error.nextAction, ...metadata, ...(request ? { operation: request.operation, pid: request.pid, buildKey: request.buildKey } : {}) } };
-    }
-    requireResource(resourceId) { const resource = this.resources.get(resourceId); if (!resource)
-        throw new BrokerProtocolError("RESOURCE_NOT_FOUND", `${resourceId} was not found`); return resource; }
-    async cleanupResource(resource, reason, records, outerDeadline = Number.POSITIVE_INFINITY) {
-        if (resource.cleanupState === "released")
-            return;
-        if (resource.cleanupState === "cleaning")
-            return;
-        resource.cleanupState = "cleaning";
-        const scopeId = resource.cleanupScopeId ?? resource.resourceId;
-        const sessionDeadline = this.cleanupDeadlines.get(scopeId) ?? this.clock.now() + (this.options.sessionCleanupTimeoutMs ?? 2_000);
-        this.cleanupDeadlines.set(scopeId, sessionDeadline);
-        const resourceDeadline = Math.min(outerDeadline, sessionDeadline);
-        const steps = resource.cleanupScopeId && this.options.runtime.cleanupCaptureScope
-            ? ["ref_release"]
-            : RELEVANT_STEPS[resource.type];
-        for (const step of steps) {
-            const cleanupContext = this.cleanupContext(sessionDeadline, outerDeadline);
-            try {
-                await this.runBeforeDeadline(() => this.options.runtime.cleanup?.(resource, step, reason, cleanupContext) ?? Promise.resolve(), resourceDeadline);
-                records.push({ resourceId: resource.resourceId, step, ok: true });
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                resource.cleanupState = "failed";
-                (resource.cleanupErrors ??= []).push({ step, error: message });
-                records.push({ resourceId: resource.resourceId, step, ok: false, error: message });
-            }
-        }
-        if (resource.cleanupState !== "failed")
-            resource.cleanupState = "released";
-        if (resource.cleanupState === "released")
-            resource.refs.clear();
-        if (![...this.resources.values()].some(candidate => (candidate.cleanupScopeId ?? candidate.resourceId) === scopeId && (candidate.cleanupState === "active" || candidate.cleanupState === "cleaning")))
-            this.cleanupDeadlines.delete(scopeId);
-    }
-    cleanupContext(sessionDeadline, brokerDeadline) {
-        const effectiveDeadline = Math.min(sessionDeadline, brokerDeadline);
-        return {
-            sessionDeadline,
-            brokerDeadline,
-            effectiveDeadline,
-            remainingMs: Math.max(0, effectiveDeadline - this.clock.now())
-        };
-    }
-    async prepareCaptureScopes(resources, reason, records, brokerDeadline, preparedScopes = new Set()) {
-        const failedScopes = new Set();
-        if (!this.options.runtime.cleanupCaptureScope)
-            return failedScopes;
-        const scopes = [...new Set(resources.map(resource => resource.cleanupScopeId).filter((value) => Boolean(value)))].filter(scope => !preparedScopes.has(scope)).sort();
-        for (const scopeId of scopes) {
-            preparedScopes.add(scopeId);
-            const sessionDeadline = this.cleanupDeadlines.get(scopeId) ?? this.clock.now() + (this.options.sessionCleanupTimeoutMs ?? 2_000);
-            this.cleanupDeadlines.set(scopeId, sessionDeadline);
-            const context = this.cleanupContext(sessionDeadline, brokerDeadline);
-            let result;
-            try {
-                const prepared = await this.runBeforeDeadline(() => this.options.runtime.cleanupCaptureScope(scopeId, reason, context), context.effectiveDeadline);
-                result = prepared ?? { sessionId: scopeId, status: "passed", steps: [] };
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                result = { sessionId: scopeId, status: "failed", steps: [{ step: "artifact_freeze", ok: false, error: message }], residualResources: resources.filter(resource => resource.cleanupScopeId === scopeId).map(resource => resource.resourceId) };
-            }
-            for (const step of result.steps)
-                records.push({ resourceId: `capture:${scopeId}`, ...step });
-            const finalized = await this.finalizeCaptureScope(scopeId, reason, result, context.effectiveDeadline, records);
-            if (result.status !== "passed" || !finalized) {
-                failedScopes.add(scopeId);
-                for (const resource of resources.filter(candidate => candidate.cleanupScopeId === scopeId)) {
-                    resource.cleanupState = "failed";
-                    for (const step of result.steps.filter(candidate => !candidate.ok))
-                        (resource.cleanupErrors ??= []).push({ step: step.step, error: step.error ?? result.status });
-                    if (!finalized && !(resource.cleanupErrors ?? []).some(item => item.step === "artifact_freeze" && item.error.includes("finalizeCaptureScope")))
-                        (resource.cleanupErrors ??= []).push({ step: "artifact_freeze", error: "finalizeCaptureScope failed" });
-                }
-            }
-        }
-        return failedScopes;
-    }
-    async finalizeCaptureScope(scopeId, reason, result, deadline, records) {
-        if (!this.options.runtime.finalizeCaptureScope)
-            return true;
-        try {
-            await this.runBeforeDeadline(() => Promise.resolve(this.options.runtime.finalizeCaptureScope(scopeId, reason, result)), deadline);
-            return true;
-        }
-        catch (error) {
-            records.push({ resourceId: `capture:${scopeId}`, step: "artifact_freeze", ok: false, error: `finalizeCaptureScope: ${errorText(error)}` });
-            return false;
-        }
-    }
-    async completeCaptureScope(scopeId, reason, deadline, records) {
-        if (!this.options.runtime.completeCaptureScope)
-            return true;
-        try {
-            await this.runBeforeDeadline(() => Promise.resolve(this.options.runtime.completeCaptureScope(scopeId, reason)), deadline);
-            return true;
-        }
-        catch (error) {
-            records.push({ resourceId: `capture:${scopeId}`, step: "ref_release", ok: false, error: `completeCaptureScope: ${errorText(error)}` });
-            return false;
-        }
-    }
-    async releaseRuntimeClient(clientId, deadline, records) {
-        if (!this.options.runtime.releaseClient)
-            return true;
-        try {
-            await this.runBeforeDeadline(() => Promise.resolve(this.options.runtime.releaseClient(clientId)), deadline);
-            return true;
-        }
-        catch (error) {
-            records.push({ resourceId: `client:${clientId}`, step: "ref_release", ok: false, error: `releaseClient: ${errorText(error)}` });
-            return false;
-        }
-    }
-    armIdleTimer() { if (this.timer !== undefined)
-        this.clock.clearTimeout(this.timer); this.timer = this.clock.setTimeout(() => this.onIdleTimer(), this.idleTimeoutMs); }
-    onIdleTimer() {
-        if (!this.accepting)
-            return;
-        const elapsed = this.clock.now() - this.lastAcceptedRequestAt;
-        const inFlight = [...this.clients.values()].some(client => client.inFlight > 0);
-        if (elapsed >= this.idleTimeoutMs && !inFlight)
-            void this.shutdown("idle_timeout");
-        else
-            this.timer = this.clock.setTimeout(() => this.onIdleTimer(), Math.max(1, this.idleTimeoutMs - elapsed));
-    }
-    async acquireExecutionSlot(clientId) {
-        const running = this.runningByClient.get(clientId) ?? 0;
-        if (running < (this.options.maxInFlightPerClient ?? 32)) {
-            this.runningByClient.set(clientId, running + 1);
-            return;
-        }
-        const queue = this.queuesByClient.get(clientId) ?? [];
-        if (queue.length >= (this.options.maxQueuedPerClient ?? 128))
-            throw new BrokerProtocolError("REQUEST_CANCELLED", "Broker client queue limit reached", "Wait for current requests to finish.");
-        await new Promise(resolve => { queue.push(resolve); this.queuesByClient.set(clientId, queue); });
-        this.runningByClient.set(clientId, (this.runningByClient.get(clientId) ?? 0) + 1);
-    }
-    releaseExecutionSlot(clientId) {
-        this.runningByClient.set(clientId, Math.max(0, (this.runningByClient.get(clientId) ?? 1) - 1));
-        const next = this.queuesByClient.get(clientId)?.shift();
-        if (next)
-            next();
-    }
-    pruneLedger() {
-        const max = this.options.maxLedgerEntries ?? 10_000;
-        const retention = this.options.ledgerRetentionMs ?? 86_400_000;
-        if (this.ledger.size <= max)
-            return;
-        return (async () => {
-            for (const [id, entry] of this.ledger) {
-                if (this.ledger.size <= max || !entry.terminalAt || this.clock.now() - entry.terminalAt < retention)
-                    continue;
-                this.emit({ action: "ledger_evicted", requestId: id, status: "passed", result: { terminalAt: entry.terminalAt, retentionMs: retention } });
-                await this.flushLifecycle();
-                this.ledgerStore?.remove(id);
-                this.ledger.delete(id);
-            }
-        })();
-    }
-    emit(event) {
-        const record = { timestamp: this.clock.now(), instanceId: this.instanceId, ...event };
-        this.lifecycleTail = this.lifecycleTail.then(async () => {
-            try {
-                await this.options.lifecycle?.(record);
-            }
-            catch (error) {
-                this.lifecycleFailure ??= error;
-            }
-        });
-    }
-    async flushLifecycle() {
-        await this.lifecycleTail;
-        if (this.lifecycleFailure) {
-            const error = this.lifecycleFailure;
-            this.lifecycleFailure = undefined;
-            throw new BrokerProtocolError("BROKER_FATAL", `lifecycle persistence failed: ${error instanceof Error ? error.message : String(error)}`, "Inspect Broker lifecycle storage and retry after repair.");
-        }
-    }
-    persistLedger(entry) {
-        try {
-            this.ledgerStore?.persist(entry);
-        }
-        catch (error) {
-            throw new BrokerProtocolError("BROKER_FATAL", `ledger persistence failed: ${error instanceof Error ? error.message : String(error)}`, "Inspect Broker ledger storage and restart after repair.");
-        }
-    }
-    async runBeforeDeadline(action, deadline) {
-        const remaining = deadline - this.clock.now();
-        if (remaining <= 0) {
-            throw new BrokerProtocolError("CLEANUP_TIMEOUT", "cleanup deadline exhausted");
-        }
-        let timer;
-        try {
-            return await Promise.race([action(), new Promise((_, reject) => { timer = this.clock.setTimeout(() => reject(new BrokerProtocolError("CLEANUP_TIMEOUT", "cleanup step timed out")), remaining); })]);
-        }
-        finally {
-            if (timer !== undefined)
-                this.clock.clearTimeout(timer);
-        }
-    }
-    async shutdownStep(result, step, deadline, action) {
-        try {
-            await this.runBeforeDeadline(() => Promise.resolve(action()), deadline);
-            result.cleanupOrder.push({ resourceId: "broker", step, ok: true });
-        }
-        catch (error) {
-            result.cleanupOrder.push({ resourceId: "broker", step, ok: false, error: error instanceof Error ? error.message : String(error) });
-        }
-    }
-    async drainInFlight(deadline, excludeRequestId, records) {
-        const pending = () => [...this.activeRequests].some(requestId => requestId !== excludeRequestId);
-        const wallDeadline = Date.now() + Math.max(0, deadline - this.clock.now());
-        while (pending()) {
-            const remaining = deadline - this.clock.now();
-            if (remaining <= 0 || Date.now() >= wallDeadline) {
-                for (const requestId of this.activeRequests) {
-                    if (requestId === excludeRequestId)
-                        continue;
-                    const entry = this.ledger.get(requestId);
-                    if (entry && !entry.terminal) {
-                        try {
-                            this.transition(entry, "outcome_unknown", { error: { code: "REQUEST_TIMEOUT", message: "Broker shutdown deadline expired while request was in flight", nextAction: "Query request_status before retrying." } });
-                        }
-                        catch { /* preserve the original ledger error */ }
-                    }
-                    this.requestCancellers.get(requestId)?.();
-                }
-                records.push({ resourceId: "broker", step: "in_flight_drain", ok: false, error: "CLEANUP_TIMEOUT" });
-                return;
-            }
-            await new Promise(resolve => {
-                let timer;
-                const wake = () => {
-                    this.drainWaiters.delete(wake);
-                    if (timer !== undefined)
-                        clearTimeout(timer);
-                    resolve();
-                };
-                this.drainWaiters.add(wake);
-                timer = setTimeout(wake, Math.max(1, Math.min(remaining, wallDeadline - Date.now())));
-            });
-        }
-        records.push({ resourceId: "broker", step: "in_flight_drain", ok: true });
-    }
-    async executeRuntime(request, context) {
-        let cancel;
-        const cancelled = new Promise((_, reject) => {
-            cancel = () => reject(new BrokerProtocolError("BROKER_STOPPED", "Broker shutdown cancelled the in-flight request", "Query request_status before retrying."));
-        });
-        this.requestCancellers.set(request.requestId, cancel);
-        let runtimePromise;
-        try {
-            runtimePromise = Promise.resolve(this.options.runtime.execute(request, context));
-        }
-        catch (error) {
-            runtimePromise = Promise.reject(error);
-        }
-        try {
-            return await Promise.race([runtimePromise, cancelled]);
-        }
-        finally {
-            this.requestCancellers.delete(request.requestId);
-        }
-    }
-}
-function errorText(error) { return error instanceof Error ? error.message : String(error); }
-function resourceDepth(resource, resources) { let depth = 0; let parent = resource.parentResourceId; while (parent) {
-    depth += 1;
-    parent = resources.get(parent)?.parentResourceId;
-} return depth; }
-function decrementRef(resource, clientId) {
-    const count = resource.refs.get(clientId);
-    if (count === undefined)
-        throw new BrokerProtocolError("RESOURCE_NOT_OWNER", `${clientId} does not own ${resource.resourceId}`);
-    if (count <= 0)
-        throw new BrokerProtocolError("RESOURCE_REF_UNDERFLOW", `${resource.resourceId} refcount would underflow`);
-    if (count === 1)
-        resource.refs.delete(clientId);
-    else
-        resource.refs.set(clientId, count - 1);
-}
-function requestIdOf(raw) { return raw && typeof raw === "object" && typeof raw.requestId === "string" ? String(raw.requestId) : "unknown"; }
-function errorJson(error) {
-    const code = error instanceof BrokerProtocolError ? error.code : "BROKER_FATAL";
-    const base = error instanceof BrokerProtocolError ? { code, message: error.message, nextAction: error.nextAction } : { code, message: error instanceof Error ? error.message : String(error), nextAction: null };
-    return { ...base, ...failureMetadata(code) };
-}
-function failureMetadata(code) {
-    if (code === "CAPTURE_FATAL")
-        return { errorCode: code, failureClass: "capture_fatal", scope: "session" };
-    if (code === "ATTACHMENT_FATAL")
-        return { errorCode: code, failureClass: "attachment_fatal", scope: "attachment" };
-    if (code === "BROKER_FATAL")
-        return { errorCode: code, failureClass: "broker_fatal", scope: "broker" };
-    return {};
-}
-function mutationLifecycleResult(entry, literalResult, nextAction) {
-    return {
-        planId: entry.mutationPlanId ?? null,
-        confirmationNonce: entry.confirmationNonce ?? null,
-        rollbackMode: entry.rollbackMode ?? null,
-        literalResult,
-        evidenceRefs: [...entry.evidenceRefs],
-        exitStatus: literalResult === null ? null : 0,
-        nextAction
-    };
-}
-function mutationMetadata(request) {
-    const command = isJsonRecord(request.payload.request) ? request.payload.request : request.payload;
-    const contract = isJsonRecord(command.mutation)
-        ? command.mutation
-        : isJsonRecord(command.launch)
-            ? command.launch
-            : undefined;
-    if (!contract)
-        return {};
-    const confirmation = isJsonRecord(contract.confirmation) ? contract.confirmation : undefined;
-    const rollback = isJsonRecord(contract.rollback) ? contract.rollback : undefined;
-    return {
-        ...(typeof contract.mutationPlanId === "string" ? { mutationPlanId: contract.mutationPlanId } : {}),
-        ...(typeof confirmation?.nonce === "string" ? { confirmationNonce: confirmation.nonce } : {}),
-        ...(typeof rollback?.mode === "string" ? { rollbackMode: rollback.mode } : {})
-    };
-}
-function requestCorrelation(request) {
-    if (!isFocusOperation(request.operation))
-        return {};
-    const sessionId = stringField(request.payload, "sessionId");
-    const resourceId = stringField(request.payload, "resourceId") ?? (sessionId ? `focus-session:${sessionId}` : undefined);
-    return { ...(sessionId ? { sessionId } : {}), ...(resourceId ? { resourceId } : {}) };
-}
-function updateEntryCorrelation(entry, result) {
-    if (!isFocusOperation(entry.operation) || !isJsonRecord(result))
-        return;
-    entry.sessionId = stringField(result, "sessionId") ?? entry.sessionId;
-    entry.resourceId = stringField(result, "resourceId") ?? entry.resourceId ?? (entry.sessionId ? `focus-session:${entry.sessionId}` : undefined);
-}
-function focusedLifecycleProjection(entry, result, error) {
-    if (!isFocusOperation(entry.operation))
-        return undefined;
-    const value = isJsonRecord(result) ? result : undefined;
-    const errorValue = isJsonRecord(error) ? error : undefined;
-    const sessionId = entry.sessionId ?? stringField(value, "sessionId") ?? residualSessionId(errorValue);
-    const resourceId = entry.resourceId ?? stringField(value, "resourceId") ?? (sessionId ? `focus-session:${sessionId}` : undefined);
-    const projection = {
-        requestId: entry.requestId,
-        clientId: entry.clientId,
-        sessionId: sessionId ?? null,
-        resourceId: resourceId ?? null,
-        pid: entry.pid,
-        buildKey: entry.buildKey
-    };
-    if (entry.operation.endsWith("_stop")) {
-        const cleanupAttempted = booleanField(value, "cleanupAttempted") ?? cleanupFlag(errorValue, "cleanupAttempted") ?? Boolean(error);
-        const fullyReleased = booleanField(value, "fullyReleased") ?? cleanupFlag(errorValue, "fullyReleased") ?? false;
-        projection.cleanupAttempted = cleanupAttempted;
-        projection.fullyReleased = fullyReleased;
-        projection.alreadyReleased = booleanField(value, "alreadyReleased") ?? false;
-        projection.cleanupStatus = cleanupStatusProjection(value?.cleanupStatus);
-        projection.residualSessionId = residualSessionId(errorValue) ?? null;
-        projection.residualResourceIds = residualResourceIds(value, errorValue);
-        projection.attachmentDetachStatus = attachmentDetachStatus(value, errorValue, fullyReleased);
-    }
-    return projection;
-}
-function isFocusOperation(operation) {
-    return operation.startsWith("wow_focus_") || operation.startsWith("wow_watch_") || operation === "wow_session_checkpoint";
-}
-function stringField(value, key) {
-    const field = value?.[key];
-    return typeof field === "string" && field.length > 0 ? field : undefined;
-}
-function booleanField(value, key) {
-    const field = value?.[key];
-    return typeof field === "boolean" ? field : undefined;
-}
-function cleanupFlag(error, name) {
-    const direct = booleanField(error, name);
-    if (direct !== undefined)
-        return direct;
-    const message = stringField(error, "message");
-    const match = message?.match(new RegExp(`(?:^|[; ])${name}=(true|false)(?:;|$)`));
-    return match ? match[1] === "true" : undefined;
-}
-function residualSessionId(error) {
-    const direct = stringField(error, "residualSessionId");
-    if (direct)
-        return direct;
-    return stringField(error, "message")?.match(/residualSessionId=([^;\s]+)/)?.[1];
-}
-function residualResourceIds(value, error) {
-    const direct = value?.residualResources ?? error?.residualResources;
-    if (Array.isArray(direct))
-        return direct.filter((item) => typeof item === "string").slice(0, 64);
-    const message = stringField(error, "message");
-    const encoded = message?.match(/residualResources=(\[[^;]*\])/)?.[1];
-    if (!encoded)
-        return [];
-    try {
-        const parsed = JSON.parse(encoded);
-        return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string").slice(0, 64) : [];
-    }
-    catch {
-        return [];
-    }
-}
-function cleanupStatusProjection(value) {
-    if (!isJsonRecord(value))
-        return null;
-    const projection = {};
-    for (const key of ["hooks", "scripts", "interceptors", "cleanupAttempted", "fullyReleased"]) {
-        const field = value[key];
-        if (typeof field === "number" || typeof field === "boolean" || field === null)
-            projection[key] = field;
-    }
-    if (Array.isArray(value.steps))
-        projection.steps = value.steps.slice(0, 32).map(step => {
-            if (!isJsonRecord(step))
-                return null;
-            return { step: stringField(step, "step") ?? null, status: stringField(step, "status") ?? null, ok: booleanField(step, "ok") ?? null };
-        });
-    if (Array.isArray(value.residualErrors))
-        projection.residualErrorCount = value.residualErrors.length;
-    return projection;
-}
-function attachmentDetachStatus(value, error, fullyReleased) {
-    const explicit = stringField(value, "attachmentDetachStatus") ?? stringField(error, "attachmentDetachStatus");
-    if (explicit)
-        return { brokerResourceRelease: fullyReleased ? "complete" : "residual_or_unknown", physicalDetach: explicit, focusManifest: null };
-    const cleanup = isJsonRecord(value?.cleanupStatus) ? value.cleanupStatus : undefined;
-    if (Array.isArray(cleanup?.steps)) {
-        const step = cleanup.steps.find(item => isJsonRecord(item) && (item.step === "detach" || item.step === "detach_deferred_to_broker"));
-        if (isJsonRecord(step))
-            return {
-                brokerResourceRelease: fullyReleased ? "complete" : "residual_or_unknown",
-                physicalDetach: stringField(step, "step") === "detach" ? (stringField(step, "status") ?? "reported") : "not_reported",
-                focusManifest: { step: stringField(step, "step") ?? null, status: stringField(step, "status") ?? null, ok: booleanField(step, "ok") ?? null }
-            };
-    }
-    return { brokerResourceRelease: fullyReleased ? "complete" : "residual_or_unknown", physicalDetach: "not_reported", focusManifest: null };
-}
-function isJsonRecord(value) {
-    return value !== null && value !== undefined && typeof value === "object" && !Array.isArray(value);
-}