tmux-ide 2.7.0 → 2.9.0-beta.11

package/packages/daemon/dist/terminal/session-runtime/terminal-delivery-hub.js

@@ -0,0 +1,1399 @@
+import { TERMINAL_DELIVERY_PATCH_TO_SEED_BYTES, TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES, TerminalDeliveryEnvelopeSchemaZ, TerminalDeliveryAckSchemaZ, TerminalDeliveryNackSchemaZ, TerminalDeliveryOfferSchemaZ, TerminalDeliveryVisibilitySchemaZ, } from "@tmux-ide/contracts";
+import { TerminalDeliveryStateTooLargeError, applyTerminalReplicaUpdate, encodeCompactSemanticTerminalUpdate, encodeAnsiTerminalRepresentation, encodeSemanticTerminalUpdate, hashTerminalDeliveryRepresentation, negotiateTerminalDelivery, preaccountSemanticTerminalUpdateBytes, } from "@tmux-ide/core";
+import { SYSTEM_SESSION_RUNTIME_SCHEDULER, } from "./runtime-scheduler.js";
+import { DISABLED_SESSION_RUNTIME_OBSERVABILITY, } from "./runtime-observability.js";
+import { registerTerminalDeliveryObservationOrdinal } from "./terminal-delivery-observation-identity.js";
+export const MAX_CANONICAL_REVISIONS = 128;
+export const MAX_RAW_JOURNAL_BYTES = 4 * 1024 * 1024;
+/** Eight workload conditioning revisions fill the cache before measured samples begin. */
+export const MAX_REPRESENTATION_CACHE_ENTRIES = 8;
+export const MAX_REPRESENTATION_CACHE_BYTES = 16 * 1024 * 1024;
+export const MAX_CLIENTS = 64;
+const MAX_PANES = 32;
+const MAX_CONNECTIONS = MAX_CLIENTS * MAX_PANES;
+const BACKGROUND_CADENCE_MS = 100;
+class ExactSemanticRepresentationSelectionError extends TerminalDeliveryStateTooLargeError {
+    selectionObservation;
+    constructor(bytes, selectionObservation) {
+        super(bytes);
+        this.name = "ExactSemanticRepresentationSelectionError";
+        this.selectionObservation = selectionObservation;
+    }
+}
+class TerminalDeliveryRepresentationSelectionError extends TerminalDeliveryStateTooLargeError {
+    selectionObservation;
+    sizeCapped;
+    atLeastBytes;
+    constructor(bytes, selectionObservation) {
+        super(bytes);
+        this.name = "TerminalDeliveryRepresentationSelectionError";
+        this.selectionObservation = selectionObservation;
+        this.atLeastBytes =
+            selectionObservation.attemptedLegacyPatchAtLeastBytes ??
+                selectionObservation.attemptedLegacySeedAtLeastBytes;
+        this.sizeCapped = this.atLeastBytes !== null;
+        if (this.atLeastBytes !== null)
+            this.message = `Terminal delivery representation is at least ${this.atLeastBytes} bytes; maximum is ${TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES}`;
+    }
+}
+class TerminalDeliveryPreaccountLimitError extends TerminalDeliveryStateTooLargeError {
+    atLeastBytes;
+    sizeCapped = true;
+    constructor(atLeastBytes) {
+        super(atLeastBytes);
+        this.name = "TerminalDeliveryPreaccountLimitError";
+        this.message = `Terminal delivery representation is at least ${atLeastBytes} bytes; maximum is ${TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES}`;
+        this.atLeastBytes = atLeastBytes;
+    }
+}
+/** One bounded, renderer-independent delivery coordinator per SessionRuntime. */
+export class SessionRuntimeTerminalDeliveryHub {
+    generation;
+    workspaceName;
+    #ownerForPane;
+    #scheduler;
+    #observability;
+    #panes = new Map();
+    #clients = new Map();
+    /** Synchronous reservations held while an async pane source is starting. */
+    #pendingClients = new Map();
+    #cache = new Map();
+    #cacheBytes = 0;
+    #coalesced = 0;
+    #reseeds = 0;
+    #nacks = 0;
+    #maxSlowClientMs = 0;
+    #maxQueueDepth = 0;
+    #deliveryOrdinal = 0;
+    #deliveryLifecycleOrdinal = 0;
+    #deliveryStatusOrdinal = 0;
+    #closed = false;
+    constructor(generation, workspaceName, ownerForPane, options = {}) {
+        this.generation = generation;
+        this.workspaceName = workspaceName;
+        this.#ownerForPane = ownerForPane;
+        this.#scheduler = options.scheduler ?? SYSTEM_SESSION_RUNTIME_SCHEDULER;
+        this.#observability = options.observability ?? DISABLED_SESSION_RUNTIME_OBSERVABILITY;
+    }
+    async open(clientId, semanticPaneId, offerInput, accept, diagnosticIdentity = Object.freeze({ clientId, surface: "direct", laneId: clientId })) {
+        if (this.#closed)
+            throw new Error("Terminal delivery hub is closed");
+        const offer = TerminalDeliveryOfferSchemaZ.parse(offerInput);
+        const negotiation = negotiateTerminalDelivery(offer, this.generation, this.#scheduler.createId());
+        if (!negotiation.accepted)
+            return rejectedConnection(negotiation);
+        const key = cacheKey([clientId, semanticPaneId]);
+        if (this.#clients.has(key) || this.#pendingClients.has(key))
+            throw new TypeError("Terminal delivery already open for client/pane");
+        const uniqueClients = new Set([
+            ...[...this.#clients.values()].map((client) => client.clientId),
+            ...this.#pendingClients.values(),
+        ]);
+        if (!uniqueClients.has(clientId) && uniqueClients.size >= MAX_CLIENTS)
+            throw new Error("Terminal delivery client limit reached");
+        if (this.#clients.size + this.#pendingClients.size >= MAX_CONNECTIONS)
+            throw new Error("Terminal delivery connection limit reached");
+        // Reserve before the first await. Without this reservation, a burst of
+        // concurrent opens can all pass the capacity precheck while ensurePane is
+        // awaiting the source and oversubscribe the hub together afterwards.
+        this.#pendingClients.set(key, clientId);
+        try {
+            const pane = await this.#ensurePane(semanticPaneId);
+            if (this.#closed)
+                throw new Error("Terminal delivery hub is closed");
+            let resolveClosed;
+            const closed = new Promise((resolve) => {
+                resolveClosed = resolve;
+            });
+            const client = {
+                key,
+                clientId,
+                diagnosticClientId: diagnosticIdentity.clientId,
+                diagnosticSurface: diagnosticIdentity.surface,
+                diagnosticLaneId: diagnosticIdentity.laneId,
+                diagnosticRequestId: diagnosticIdentity.requestId ?? diagnosticIdentity.laneId,
+                paneId: semanticPaneId,
+                negotiated: negotiation.negotiated,
+                accept,
+                visibility: "visible",
+                baselineRevision: -1,
+                baselineHash: null,
+                reseedRequired: false,
+                inFlight: null,
+                latestRevision: pane.latest?.update.revision ?? null,
+                scheduled: false,
+                closed: false,
+                lifecycleOpenRecorded: false,
+                resolveClosed,
+                outgoing: [],
+                sending: false,
+                retireAfterDrain: false,
+                lastAck: null,
+                sourceClosedFlight: null,
+                backgroundTimer: null,
+            };
+            this.#clients.set(key, client);
+            client.lifecycleOpenRecorded = this.#recordDeliveryLifecycle(client, pane, "open");
+            this.#schedule(client);
+            this.#recordDeliveryStatus(client, pane);
+            return {
+                negotiation,
+                closed,
+                ack: (ack) => this.#ack(client, ack),
+                nack: (nack) => this.#nack(client, nack),
+                setVisibility: (visibilityInput) => {
+                    if (client.closed)
+                        return;
+                    client.visibility = TerminalDeliveryVisibilitySchemaZ.parse(visibilityInput);
+                    if (client.visibility === "visible" || client.visibility === "background")
+                        this.#schedule(client);
+                    this.#recordDeliveryStatus(client, this.#panes.get(client.paneId));
+                },
+                close: async () => this.#closeClient(client),
+            };
+        }
+        finally {
+            this.#pendingClients.delete(key);
+        }
+    }
+    metrics() {
+        const now = this.#scheduler.nowMs();
+        const currentSlow = [...this.#clients.values()].reduce((max, client) => Math.max(max, client.inFlight ? now - client.inFlight.sentAt : 0), 0);
+        return Object.freeze({
+            clients: new Set([...this.#clients.values()].map((client) => client.clientId)).size,
+            connections: this.#clients.size,
+            inFlight: [...this.#clients.values()].filter((client) => client.inFlight).length,
+            latestPointers: [...this.#clients.values()].filter((client) => client.latestRevision !== null)
+                .length,
+            coalesced: this.#coalesced,
+            reseeds: this.#reseeds,
+            nacks: this.#nacks,
+            canonicalRevisions: [...this.#panes.values()].reduce((sum, pane) => sum + pane.revisions.size, 0),
+            representationCacheBytes: this.#cacheBytes,
+            rawJournalBytes: [...this.#panes.values()].reduce((sum, pane) => sum + pane.rawBytes, 0),
+            maxSlowClientMs: Math.max(this.#maxSlowClientMs, currentSlow),
+            queueDepth: [...this.#clients.values()].reduce((sum, client) => sum + client.outgoing.length, 0),
+            maxQueueDepth: this.#maxQueueDepth,
+            inFlightBytes: [...this.#clients.values()].reduce((sum, client) => sum + (client.inFlight?.envelope.representationBytes ?? 0), 0),
+        });
+    }
+    convergenceSnapshot() {
+        return Object.freeze({
+            panes: Object.freeze([...this.#panes.entries()].flatMap(([semanticPaneId, pane]) => pane.latest
+                ? [
+                    Object.freeze({
+                        semanticPaneId,
+                        incarnation: pane.latest.update.incarnation,
+                        revision: pane.latest.update.revision,
+                        stateHash: pane.latest.update.stateHash,
+                    }),
+                ]
+                : [])),
+            clients: Object.freeze([...this.#clients.values()].map((client) => Object.freeze({
+                clientId: client.clientId,
+                semanticPaneId: client.paneId,
+                visibility: client.visibility,
+                baselineRevision: client.baselineRevision,
+                baselineHash: client.baselineHash,
+                inFlightRevision: client.inFlight?.envelope.canonicalRevision ?? null,
+                latestRevision: client.latestRevision,
+                queueDepth: client.outgoing.length,
+            }))),
+        });
+    }
+    async resetForSessionRestart() {
+        for (const client of this.#clients.values()) {
+            client.outgoing.length = 0;
+            client.inFlight = null;
+            this.#enqueue(client, {
+                type: "terminal.delivery.fault",
+                reason: "source-closed",
+                message: "Terminal source restarted",
+                deliveryNonce: client.negotiated.deliveryNonce,
+            });
+            client.retireAfterDrain = true;
+        }
+        const panes = [...this.#panes.values()];
+        this.#panes.clear();
+        for (const pane of panes) {
+            pane.pendingCanonical.length = 0;
+            pane.canonicalScheduled = false;
+        }
+        await Promise.allSettled(panes.map((pane) => pane.source?.close()));
+        this.#clearCache();
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        await this.resetForSessionRestart();
+        await Promise.allSettled([...this.#clients.values()].map((client) => this.#closeClient(client)));
+    }
+    async #ensurePane(semanticPaneId) {
+        let pane = this.#panes.get(semanticPaneId);
+        if (pane) {
+            await pane.start;
+            return pane;
+        }
+        if (this.#panes.size >= MAX_PANES)
+            throw new Error("Terminal delivery pane limit reached");
+        const owner = this.#ownerForPane(semanticPaneId);
+        pane = {
+            owner,
+            source: null,
+            start: Promise.resolve(),
+            current: null,
+            latest: null,
+            revisions: new Map(),
+            raw: new Map(),
+            rawBytes: 0,
+            rawFloorRevision: 0,
+            lastRawRevision: -1,
+            pendingCanonical: [],
+            canonicalScheduled: false,
+            pendingDeliveryTrace: null,
+        };
+        this.#panes.set(semanticPaneId, pane);
+        pane.start = owner
+            .subscribeSource((update, trace) => this.#observeCanonical(semanticPaneId, update, trace), (record) => this.#observeRaw(semanticPaneId, record))
+            .then(async (source) => {
+            if (this.#closed || this.#panes.get(semanticPaneId) !== pane) {
+                await source.close();
+                throw new Error("Terminal delivery source retired during startup");
+            }
+            pane.source = source;
+        })
+            .catch((error) => {
+            if (this.#panes.get(semanticPaneId) === pane)
+                this.#panes.delete(semanticPaneId);
+            throw error;
+        });
+        await pane.start;
+        return pane;
+    }
+    #observeCanonical(semanticPaneId, update, trace) {
+        const pane = this.#panes.get(semanticPaneId);
+        if (!pane)
+            return;
+        pane.pendingCanonical.push({ update, trace });
+        if (pane.canonicalScheduled)
+            return;
+        pane.canonicalScheduled = true;
+        this.#scheduler.microtask(() => {
+            if (this.#panes.get(semanticPaneId) !== pane)
+                return;
+            pane.canonicalScheduled = false;
+            for (const pending of pane.pendingCanonical.splice(0))
+                this.#applyCanonical(semanticPaneId, pane, pending.update, pending.trace);
+        });
+    }
+    #applyCanonical(semanticPaneId, pane, update, trace) {
+        if (update.workspaceName !== this.workspaceName ||
+            update.semanticPaneId !== semanticPaneId ||
+            update.generation !== this.generation)
+            return;
+        const result = applyTerminalReplicaUpdate(pane.current, update);
+        if (result.status !== "applied" && result.status !== "idempotent")
+            return;
+        pane.current = result.state;
+        if (trace)
+            pane.pendingDeliveryTrace = trace;
+        const record = { update, state: result.state, trace: pane.pendingDeliveryTrace };
+        pane.latest = record;
+        pane.revisions.set(update.revision, record);
+        this.#pruneCanonicalRevisions(semanticPaneId);
+        for (const client of this.#clients.values()) {
+            if (client.paneId !== semanticPaneId || client.closed)
+                continue;
+            if (!client.lifecycleOpenRecorded)
+                client.lifecycleOpenRecorded = this.#recordDeliveryLifecycle(client, pane, "open");
+            if (update.type === "terminal.tombstone" &&
+                (client.inFlight !== null || client.visibility !== "visible")) {
+                this.#fault(client, "source-closed", "Terminal source closed before final state delivery");
+                continue;
+            }
+            if (client.latestRevision !== null && client.latestRevision !== update.revision)
+                this.#coalesced += 1;
+            client.latestRevision = update.revision;
+            this.#schedule(client);
+        }
+        if (update.type === "terminal.tombstone") {
+            this.#scheduler.timer(() => {
+                if (this.#panes.get(semanticPaneId) !== pane)
+                    return;
+                this.#panes.delete(semanticPaneId);
+                pane.pendingCanonical.length = 0;
+                pane.canonicalScheduled = false;
+                void pane.source?.close().catch(() => undefined);
+                this.#clearCache();
+            }, 0);
+        }
+    }
+    #observeRaw(semanticPaneId, record) {
+        const pane = this.#panes.get(semanticPaneId);
+        if (!pane)
+            return;
+        if (record.revision <= pane.lastRawRevision)
+            return;
+        if (record.baseRevision === record.revision ||
+            record.baseRevision !== record.revision - 1 ||
+            (pane.lastRawRevision >= 0 && record.baseRevision !== pane.lastRawRevision)) {
+            pane.raw.clear();
+            pane.rawBytes = 0;
+            pane.rawFloorRevision = Math.max(pane.rawFloorRevision, record.revision + 1);
+            pane.lastRawRevision = record.revision;
+            return;
+        }
+        if (!record.contiguous || record.bytes.byteLength > MAX_RAW_JOURNAL_BYTES) {
+            pane.raw.clear();
+            pane.rawBytes = 0;
+            pane.rawFloorRevision = Math.max(pane.rawFloorRevision, record.revision + 1);
+            pane.lastRawRevision = record.revision;
+            return;
+        }
+        pane.raw.set(record.revision, record.bytes);
+        pane.lastRawRevision = record.revision;
+        pane.rawBytes += record.bytes.byteLength;
+        while (pane.rawBytes > MAX_RAW_JOURNAL_BYTES || pane.raw.size > MAX_CANONICAL_REVISIONS) {
+            const first = pane.raw.entries().next().value;
+            if (!first)
+                break;
+            pane.raw.delete(first[0]);
+            pane.rawBytes -= first[1].byteLength;
+            pane.rawFloorRevision = Math.max(pane.rawFloorRevision, first[0] + 1);
+        }
+    }
+    #schedule(client) {
+        if (client.closed ||
+            client.inFlight ||
+            client.latestRevision === null ||
+            client.latestRevision === client.baselineRevision ||
+            client.visibility === "hidden" ||
+            client.visibility === "frozen")
+            return;
+        if (client.visibility === "background") {
+            if (client.backgroundTimer)
+                return;
+            client.backgroundTimer = this.#scheduler.timer(() => {
+                client.backgroundTimer = null;
+                if (!client.closed && !client.inFlight && client.latestRevision !== null)
+                    this.#deliver(client);
+            }, BACKGROUND_CADENCE_MS);
+            return;
+        }
+        if (client.scheduled)
+            return;
+        client.scheduled = true;
+        this.#scheduler.microtask(() => {
+            client.scheduled = false;
+            if (!client.closed && client.visibility === "visible" && !client.inFlight)
+                this.#deliver(client);
+        });
+    }
+    #deliver(client) {
+        const pane = this.#panes.get(client.paneId);
+        const target = pane?.latest;
+        if (!pane || !target || target.update.revision !== client.latestRevision)
+            return;
+        const traceStarted = this.#observability.enabled ? this.#observability.nowMicros() : 0;
+        let encodedRepresentation = null;
+        let failedSelectionObservation = null;
+        let deliveryEnvelope = null;
+        let deliveryOrdinal = null;
+        try {
+            const representation = this.#representation(client, pane, target);
+            encodedRepresentation = representation;
+            const transactionId = this.#scheduler.createId();
+            const chunkCount = Math.max(1, Math.ceil(representation.bytes.byteLength / (256 * 1024)));
+            const envelope = TerminalDeliveryEnvelopeSchemaZ.parse({
+                type: "terminal.delivery",
+                workspaceName: target.update.workspaceName,
+                semanticPaneId: target.update.semanticPaneId,
+                generation: target.update.generation,
+                incarnation: target.update.incarnation,
+                deliveryNonce: client.negotiated.deliveryNonce,
+                transactionId,
+                ...(target.trace ? { performanceTraceId: target.trace.traceId } : {}),
+                protocolVersion: 1,
+                encoding: representation.encoding ?? client.negotiated.encoding,
+                frame: representation.frame,
+                baseRevision: representation.frame === "seed" ? null : Math.max(0, client.baselineRevision),
+                canonicalRevision: target.update.revision,
+                canonicalStateHash: target.update.stateHash,
+                representationHash: representation.representationHash ??
+                    hashTerminalDeliveryRepresentation(representation.bytes),
+                representationBytes: representation.bytes.byteLength,
+                chunkCount,
+                canonicalEquivalent: representation.canonicalEquivalent,
+                history: representation.history,
+                richPlacements: client.negotiated.richPlacements,
+            });
+            deliveryEnvelope = envelope;
+            deliveryOrdinal = ++this.#deliveryOrdinal;
+            registerTerminalDeliveryObservationOrdinal(envelope, deliveryOrdinal);
+            client.inFlight = {
+                envelope,
+                deliveryOrdinal,
+                bytes: representation.bytes,
+                nextChunk: 0,
+                sentAt: this.#scheduler.nowMs(),
+            };
+            this.#enqueue(client, envelope);
+            this.#recordDeliveryStatus(client, pane);
+            if (target.trace?.traceId === pane.pendingDeliveryTrace?.traceId)
+                pane.pendingDeliveryTrace = null;
+        }
+        catch (error) {
+            failedSelectionObservation = semanticSelectionObservationFromError(error);
+            this.#fault(client, error instanceof TerminalDeliveryStateTooLargeError
+                ? "state-too-large"
+                : "protocol-violation", error instanceof Error ? error.message : String(error), failedSelectionObservation);
+        }
+        finally {
+            if (this.#observability.enabled)
+                try {
+                    const metrics = this.metrics();
+                    this.#observability.recordSpan("transport", "terminal-delivery-encode-enqueue", traceStarted, this.#observability.nowMicros(), target.trace, undefined, Object.freeze({
+                        representationCacheBytes: metrics.representationCacheBytes,
+                        rawJournalBytes: metrics.rawJournalBytes,
+                        queueDepth: metrics.queueDepth,
+                        maxQueueDepth: metrics.maxQueueDepth,
+                        inFlight: metrics.inFlight,
+                        inFlightBytes: metrics.inFlightBytes,
+                        ...(encodedRepresentation
+                            ? {
+                                representation: encodedRepresentation.frame,
+                                representationBytes: encodedRepresentation.bytes.byteLength,
+                            }
+                            : {}),
+                        attemptedPatchBytes: encodedRepresentation?.selectionObservation?.attemptedPatchBytes ??
+                            failedSelectionObservation?.attemptedPatchBytes ??
+                            null,
+                        attemptedSeedBytes: encodedRepresentation?.selectionObservation?.attemptedSeedBytes ??
+                            failedSelectionObservation?.attemptedSeedBytes ??
+                            null,
+                        ...((encodedRepresentation?.selectionObservation ?? failedSelectionObservation)
+                            ? terminalSelectionObservation(encodedRepresentation?.selectionObservation ?? failedSelectionObservation)
+                            : {}),
+                        ...(deliveryEnvelope && deliveryOrdinal !== null
+                            ? {
+                                workspaceName: deliveryEnvelope.workspaceName,
+                                semanticPaneId: deliveryEnvelope.semanticPaneId,
+                                canonicalGeneration: deliveryEnvelope.generation,
+                                canonicalIncarnation: deliveryEnvelope.incarnation,
+                                canonicalRevision: deliveryEnvelope.canonicalRevision,
+                                canonicalStateHash: deliveryEnvelope.canonicalStateHash,
+                                deliveryOrdinal,
+                                transactionId: deliveryEnvelope.transactionId,
+                                deliveryClientId: client.diagnosticClientId,
+                                deliverySurface: client.diagnosticSurface,
+                                deliveryLaneId: client.diagnosticLaneId,
+                                deliveryRequestId: client.diagnosticRequestId,
+                                deliveryNonce: deliveryEnvelope.deliveryNonce,
+                            }
+                            : {}),
+                    }));
+                }
+                catch {
+                    // Detailed resource diagnostics never own terminal delivery.
+                }
+        }
+    }
+    #representation(client, pane, target) {
+        const key = cacheKey([
+            target.update.workspaceName,
+            target.update.semanticPaneId,
+            target.update.generation,
+            target.update.incarnation,
+            client.negotiated.encoding,
+            client.negotiated.fallbackEncoding ?? "no-fallback",
+            client.negotiated.richPlacements ? "rich" : "plain",
+            client.baselineRevision,
+            client.baselineHash ?? "none",
+            client.reseedRequired ? "reseed" : "incremental",
+            target.update.revision,
+            target.update.stateHash,
+        ]);
+        const cached = this.#cache.get(key);
+        if (cached)
+            return cached;
+        const baseline = client.reseedRequired
+            ? null
+            : (pane.revisions.get(client.baselineRevision)?.state.snapshot ?? null);
+        const snapshot = target.state.snapshot;
+        let result = null;
+        if (client.negotiated.encoding === "semantic-v1" ||
+            client.negotiated.encoding === "semantic-compact-v1") {
+            const encodeSemantic = client.negotiated.encoding === "semantic-compact-v1"
+                ? encodeCompactSemanticTerminalUpdate
+                : encodeSemanticTerminalUpdate;
+            if (client.reseedRequired) {
+                const payload = semanticSeed(target);
+                let bytes;
+                let actualEncoding = client.negotiated.encoding;
+                let fallbackObservation = null;
+                try {
+                    bytes = encodeSemantic(payload);
+                }
+                catch (error) {
+                    if (!(error instanceof TerminalDeliveryStateTooLargeError))
+                        throw error;
+                    if (client.negotiated.encoding === "semantic-compact-v1" &&
+                        client.negotiated.fallbackEncoding === "semantic-v1") {
+                        try {
+                            bytes = encodeLegacySemanticCandidate(payload);
+                            actualEncoding = "semantic-v1";
+                            fallbackObservation = legacyFallbackObservation("seed", error.bytes, bytes.byteLength);
+                        }
+                        catch (legacyError) {
+                            if (!(legacyError instanceof TerminalDeliveryStateTooLargeError))
+                                throw legacyError;
+                            throw new TerminalDeliveryRepresentationSelectionError(legacyError.bytes, failedCompactAndLegacyObservation("seed", error.bytes, legacyError));
+                        }
+                    }
+                    else {
+                        throw new TerminalDeliveryRepresentationSelectionError(error.bytes, {
+                            attemptedPatchBytes: null,
+                            attemptedSeedBytes: error.bytes,
+                            attemptedLegacyPatchBytes: null,
+                            attemptedLegacySeedBytes: client.negotiated.encoding === "semantic-v1" ? error.bytes : null,
+                            attemptedLegacyPatchAtLeastBytes: null,
+                            attemptedLegacySeedAtLeastBytes: null,
+                            attemptedLegacyPatchSizeCapped: false,
+                            attemptedLegacySeedSizeCapped: false,
+                            attemptedCompactPatchBytes: null,
+                            attemptedCompactSeedBytes: client.negotiated.encoding === "semantic-compact-v1" ? error.bytes : null,
+                            selectedEncoding: client.negotiated.encoding,
+                            selectionStatus: "direct-seed",
+                        });
+                    }
+                }
+                const selectionObservation = fallbackObservation ??
+                    (this.#observability.enabled
+                        ? completeSemanticSelectionObservation({
+                            attemptedPatchBytes: null,
+                            attemptedSeedBytes: bytes.byteLength,
+                            selectionStatus: "direct-seed",
+                        }, client.negotiated.encoding, null)
+                        : null);
+                result = {
+                    bytes,
+                    encoding: actualEncoding,
+                    frame: payload.frame,
+                    canonicalEquivalent: true,
+                    history: payload.frame === "tombstone" ? "not-applicable" : "complete",
+                    ...(selectionObservation ? { selectionObservation } : {}),
+                };
+                this.#reseeds += 1;
+            }
+            else {
+                const patchPayload = semanticPayload(client.baselineRevision, baseline, target);
+                const seedPayload = patchPayload.frame === "tombstone" ? null : semanticSeed(target);
+                const legacyAttempts = null;
+                if (patchPayload.frame !== "patch") {
+                    let bytes;
+                    let actualEncoding = client.negotiated.encoding;
+                    let fallbackObservation = null;
+                    try {
+                        bytes = encodeSemantic(patchPayload);
+                    }
+                    catch (error) {
+                        if (!(error instanceof TerminalDeliveryStateTooLargeError))
+                            throw error;
+                        if (client.negotiated.encoding === "semantic-compact-v1" &&
+                            client.negotiated.fallbackEncoding === "semantic-v1" &&
+                            patchPayload.frame === "seed") {
+                            try {
+                                bytes = encodeLegacySemanticCandidate(patchPayload);
+                                actualEncoding = "semantic-v1";
+                                fallbackObservation = legacyFallbackObservation("seed", error.bytes, bytes.byteLength);
+                            }
+                            catch (legacyError) {
+                                if (!(legacyError instanceof TerminalDeliveryStateTooLargeError))
+                                    throw legacyError;
+                                const directObservation = failedCompactAndLegacyObservation("seed", error.bytes, legacyError);
+                                throw new TerminalDeliveryRepresentationSelectionError(legacyError.bytes, directObservation);
+                            }
+                        }
+                        else {
+                            const directObservation = completeSemanticSelectionObservation({
+                                attemptedPatchBytes: null,
+                                attemptedSeedBytes: patchPayload.frame === "seed" ? error.bytes : null,
+                                selectionStatus: patchPayload.frame === "seed" ? "direct-seed" : "direct-tombstone",
+                            }, client.negotiated.encoding, legacyAttempts);
+                            throw new TerminalDeliveryRepresentationSelectionError(error.bytes, directObservation);
+                        }
+                    }
+                    const directObservation = fallbackObservation ??
+                        (this.#observability.enabled
+                            ? completeSemanticSelectionObservation({
+                                attemptedPatchBytes: null,
+                                attemptedSeedBytes: patchPayload.frame === "seed" ? bytes.byteLength : null,
+                                selectionStatus: patchPayload.frame === "seed" ? "direct-seed" : "direct-tombstone",
+                            }, client.negotiated.encoding, legacyAttempts)
+                            : null);
+                    if (patchPayload.frame === "seed")
+                        this.#reseeds += 1;
+                    result = {
+                        bytes,
+                        encoding: actualEncoding,
+                        frame: patchPayload.frame,
+                        canonicalEquivalent: true,
+                        history: patchPayload.frame === "tombstone" ? "not-applicable" : "complete",
+                        ...(directObservation ? { selectionObservation: directObservation } : {}),
+                    };
+                }
+                else {
+                    let selected = null;
+                    try {
+                        selected = selectExactSemanticRepresentation(() => ({ payload: patchPayload, bytes: encodeSemantic(patchPayload) }), () => {
+                            if (!seedPayload)
+                                throw new TypeError("Patch has no seed representation");
+                            return { payload: seedPayload, bytes: encodeSemantic(seedPayload) };
+                        }, this.#observability.enabled);
+                    }
+                    catch (error) {
+                        if (!(error instanceof ExactSemanticRepresentationSelectionError))
+                            throw error;
+                        if (client.negotiated.encoding === "semantic-compact-v1" &&
+                            client.negotiated.fallbackEncoding === "semantic-v1") {
+                            try {
+                                const legacySelected = selectExactSemanticRepresentation(() => ({
+                                    payload: patchPayload,
+                                    bytes: encodeLegacySemanticCandidate(patchPayload),
+                                }), () => {
+                                    if (!seedPayload)
+                                        throw new TypeError("Patch has no legacy seed representation");
+                                    return {
+                                        payload: seedPayload,
+                                        bytes: encodeLegacySemanticCandidate(seedPayload),
+                                    };
+                                }, true);
+                                const fallbackObservation = legacyFallbackFromSelection(legacySelected.observation, error.selectionObservation, legacySelected.payload.frame);
+                                if (legacySelected.payload.frame === "seed")
+                                    this.#reseeds += 1;
+                                result = {
+                                    bytes: legacySelected.bytes,
+                                    encoding: "semantic-v1",
+                                    frame: legacySelected.payload.frame,
+                                    canonicalEquivalent: true,
+                                    history: legacySelected.payload.frame === "tombstone" ? "not-applicable" : "complete",
+                                    selectionObservation: fallbackObservation,
+                                };
+                            }
+                            catch (legacyError) {
+                                if (!(legacyError instanceof ExactSemanticRepresentationSelectionError))
+                                    throw legacyError;
+                                throw new TerminalDeliveryRepresentationSelectionError(legacyError.bytes, failedCompactAndLegacySelectionObservation(error.selectionObservation, legacyError.selectionObservation));
+                            }
+                        }
+                        else {
+                            throw new TerminalDeliveryRepresentationSelectionError(error.bytes, completeSemanticSelectionObservation(error.selectionObservation, client.negotiated.encoding, legacyAttempts));
+                        }
+                    }
+                    if (selected) {
+                        if (selected.payload.frame === "seed")
+                            this.#reseeds += 1;
+                        const selectionObservation = selected.observation
+                            ? completeSemanticSelectionObservation(selected.observation, client.negotiated.encoding, legacyAttempts)
+                            : null;
+                        result = {
+                            bytes: selected.bytes,
+                            encoding: client.negotiated.encoding,
+                            frame: selected.payload.frame,
+                            canonicalEquivalent: true,
+                            history: selected.payload.frame === "tombstone" ? "not-applicable" : "complete",
+                            ...(selectionObservation ? { selectionObservation } : {}),
+                        };
+                    }
+                }
+            }
+        }
+        else if (client.negotiated.encoding === "ansi-diff-v1") {
+            if (!snapshot)
+                result = emptyTombstone();
+            else {
+                const patch = baseline !== null;
+                result = {
+                    bytes: encodeAnsiTerminalRepresentation(patch ? baseline : null, snapshot),
+                    frame: patch ? "patch" : "seed",
+                    canonicalEquivalent: false,
+                    history: snapshot.history.length > 0 ? "truncated" : "complete",
+                };
+                if (!patch)
+                    this.#reseeds += 1;
+            }
+        }
+        else
+            result = this.#rawRepresentation(client, pane, target);
+        if (!result)
+            throw new TypeError("Terminal delivery representation selection was incomplete");
+        const hashed = {
+            ...result,
+            representationHash: hashTerminalDeliveryRepresentation(result.bytes),
+            cachePaneId: client.paneId,
+            cacheBaseRevision: client.baselineRevision,
+            cacheTargetRevision: target.update.revision,
+        };
+        this.#cacheSet(key, hashed);
+        return hashed;
+    }
+    #rawRepresentation(client, pane, target) {
+        if (client.baselineRevision >= pane.rawFloorRevision - 1) {
+            const parts = [];
+            let contiguous = true;
+            for (let revision = client.baselineRevision + 1; revision <= target.update.revision; revision += 1) {
+                const raw = pane.raw.get(revision);
+                if (!raw) {
+                    contiguous = false;
+                    break;
+                }
+                parts.push(raw);
+            }
+            if (contiguous)
+                return {
+                    bytes: joinBytes(parts),
+                    frame: "patch",
+                    canonicalEquivalent: false,
+                    history: "not-applicable",
+                };
+        }
+        this.#reseeds += 1;
+        return target.state.snapshot
+            ? {
+                bytes: encodeAnsiTerminalRepresentation(null, target.state.snapshot),
+                frame: "seed",
+                canonicalEquivalent: false,
+                history: "not-applicable",
+            }
+            : emptyTombstone();
+    }
+    #ack(client, input) {
+        const ack = TerminalDeliveryAckSchemaZ.parse(input);
+        const flight = client.inFlight;
+        if (!flight) {
+            if (client.lastAck && JSON.stringify(client.lastAck) === JSON.stringify(ack))
+                return;
+            const closed = client.sourceClosedFlight;
+            if (closed &&
+                ack.workspaceName === closed.workspaceName &&
+                ack.semanticPaneId === closed.semanticPaneId &&
+                ack.generation === closed.generation &&
+                ack.incarnation === closed.incarnation &&
+                ack.deliveryNonce === closed.deliveryNonce &&
+                ack.transactionId === closed.transactionId &&
+                ack.canonicalRevision === closed.canonicalRevision &&
+                ack.canonicalStateHash === closed.canonicalStateHash &&
+                ack.representationHash === closed.representationHash)
+                return;
+            this.#fault(client, "protocol-violation", "ACK has no in-flight transaction");
+            return;
+        }
+        const envelope = flight.envelope;
+        if (flight.nextChunk !== envelope.chunkCount ||
+            ack.workspaceName !== envelope.workspaceName ||
+            ack.semanticPaneId !== envelope.semanticPaneId ||
+            ack.generation !== envelope.generation ||
+            ack.incarnation !== envelope.incarnation ||
+            ack.deliveryNonce !== envelope.deliveryNonce ||
+            ack.transactionId !== envelope.transactionId ||
+            ack.canonicalRevision !== envelope.canonicalRevision ||
+            ack.canonicalStateHash !== envelope.canonicalStateHash ||
+            ack.representationHash !== envelope.representationHash) {
+            this.#fault(client, "protocol-violation", "ACK does not identify the in-flight delivery");
+            return;
+        }
+        this.#maxSlowClientMs = Math.max(this.#maxSlowClientMs, this.#scheduler.nowMs() - flight.sentAt);
+        client.baselineRevision = ack.canonicalRevision;
+        client.baselineHash = ack.canonicalStateHash;
+        client.reseedRequired = false;
+        client.inFlight = null;
+        client.lastAck = ack;
+        if (client.latestRevision === ack.canonicalRevision)
+            client.latestRevision = null;
+        this.#pruneAckSupersededCache(client.paneId);
+        this.#pruneCanonicalRevisions(client.paneId);
+        if (this.#observability.enabled)
+            try {
+                const atMicros = this.#observability.nowMicros();
+                const metrics = this.metrics();
+                this.#observability.recordSpan("transport", "terminal-delivery-settled", atMicros, atMicros, envelope.performanceTraceId
+                    ? Object.freeze({
+                        traceId: envelope.performanceTraceId,
+                        scenario: "terminal-input-to-paint",
+                        authority: Object.freeze({
+                            generation: envelope.generation,
+                            incarnation: envelope.incarnation,
+                        }),
+                    })
+                    : null, undefined, Object.freeze({
+                    representationCacheBytes: metrics.representationCacheBytes,
+                    rawJournalBytes: metrics.rawJournalBytes,
+                    queueDepth: metrics.queueDepth,
+                    maxQueueDepth: metrics.maxQueueDepth,
+                    inFlight: metrics.inFlight,
+                    inFlightBytes: metrics.inFlightBytes,
+                    workspaceName: envelope.workspaceName,
+                    semanticPaneId: envelope.semanticPaneId,
+                    canonicalGeneration: envelope.generation,
+                    canonicalIncarnation: envelope.incarnation,
+                    canonicalRevision: envelope.canonicalRevision,
+                    canonicalStateHash: envelope.canonicalStateHash,
+                    deliveryOrdinal: flight.deliveryOrdinal,
+                    transactionId: envelope.transactionId,
+                    deliveryClientId: client.diagnosticClientId,
+                    deliverySurface: client.diagnosticSurface,
+                    deliveryLaneId: client.diagnosticLaneId,
+                    deliveryRequestId: client.diagnosticRequestId,
+                    deliveryNonce: envelope.deliveryNonce,
+                }));
+            }
+            catch {
+                // Detailed settlement diagnostics never own ACK adoption.
+            }
+        this.#schedule(client);
+        this.#recordDeliveryStatus(client, this.#panes.get(client.paneId));
+    }
+    #nack(client, input) {
+        const nack = TerminalDeliveryNackSchemaZ.parse(input);
+        const envelope = client.inFlight?.envelope;
+        if (!envelope ||
+            nack.workspaceName !== envelope.workspaceName ||
+            nack.semanticPaneId !== envelope.semanticPaneId ||
+            nack.generation !== envelope.generation ||
+            nack.incarnation !== envelope.incarnation ||
+            nack.deliveryNonce !== envelope.deliveryNonce ||
+            nack.transactionId !== envelope.transactionId) {
+            this.#fault(client, "protocol-violation", "NACK does not identify the in-flight delivery");
+            return;
+        }
+        this.#nacks += 1;
+        client.reseedRequired = true;
+        client.inFlight = null;
+        this.#pruneCanonicalRevisions(client.paneId);
+        this.#schedule(client);
+        this.#recordDeliveryStatus(client, this.#panes.get(client.paneId));
+    }
+    #fault(client, reason, message, selectionObservation = null) {
+        if (this.#observability.enabled)
+            try {
+                const atMicros = this.#observability.nowMicros();
+                const flight = client.inFlight;
+                const metrics = this.metrics();
+                this.#observability.recordSpan("transport", "terminal-delivery-fault", atMicros, atMicros, null, undefined, Object.freeze({
+                    representationCacheBytes: metrics.representationCacheBytes,
+                    rawJournalBytes: metrics.rawJournalBytes,
+                    queueDepth: metrics.queueDepth,
+                    maxQueueDepth: metrics.maxQueueDepth,
+                    inFlight: metrics.inFlight,
+                    inFlightBytes: metrics.inFlightBytes,
+                    workspaceName: this.workspaceName,
+                    semanticPaneId: client.paneId,
+                    faultReason: reason,
+                    ...(selectionObservation ? terminalSelectionObservation(selectionObservation) : {}),
+                    ...(flight
+                        ? {
+                            canonicalGeneration: flight.envelope.generation,
+                            canonicalIncarnation: flight.envelope.incarnation,
+                            canonicalRevision: flight.envelope.canonicalRevision,
+                            canonicalStateHash: flight.envelope.canonicalStateHash,
+                            deliveryOrdinal: flight.deliveryOrdinal,
+                            transactionId: flight.envelope.transactionId,
+                        }
+                        : {}),
+                }));
+            }
+            catch {
+                // Detailed fault diagnostics never own delivery failure handling.
+            }
+        client.outgoing.length = 0;
+        if (reason === "source-closed")
+            client.sourceClosedFlight = client.inFlight?.envelope ?? null;
+        client.inFlight = null;
+        const fault = {
+            type: "terminal.delivery.fault",
+            reason,
+            message: message.slice(0, 1024),
+            deliveryNonce: client.negotiated.deliveryNonce,
+        };
+        if (reason === "source-closed" && client.sending) {
+            // A data callback may be waiting for renderer credit. Source closure is
+            // authoritative control state, so send it out-of-band and retire after
+            // that small frame has reached the transport instead of waiting behind
+            // a transaction which can no longer become current.
+            void Promise.resolve(client.accept(fault)).then(() => this.#closeClient(client), () => this.#closeClient(client));
+            return;
+        }
+        this.#enqueue(client, fault);
+        client.retireAfterDrain = true;
+    }
+    #enqueue(client, message) {
+        this.#enqueueFactory(client, () => message);
+    }
+    #enqueueFactory(client, create) {
+        if (client.closed)
+            return;
+        client.outgoing.push(create);
+        this.#maxQueueDepth = Math.max(this.#maxQueueDepth, client.outgoing.length);
+        if (client.sending)
+            return;
+        client.sending = true;
+        this.#scheduler.microtask(async () => {
+            try {
+                while (!client.closed) {
+                    const queued = client.outgoing.shift();
+                    let next = queued?.();
+                    const flight = client.inFlight;
+                    if (!next && flight && flight.nextChunk < flight.envelope.chunkCount) {
+                        const index = flight.nextChunk;
+                        flight.nextChunk += 1;
+                        next = {
+                            type: "terminal.delivery.chunk",
+                            transactionId: flight.envelope.transactionId,
+                            index,
+                            bytes: flight.bytes.slice(index * 256 * 1024, Math.min(flight.bytes.byteLength, (index + 1) * 256 * 1024)),
+                        };
+                    }
+                    if (!next)
+                        break;
+                    await this.#withDeadline(Promise.resolve(client.accept(next)), 5_000);
+                }
+            }
+            catch {
+                client.outgoing.length = 0;
+                try {
+                    client.outgoing.length = 0;
+                    await this.#closeClient(client, "sink-failed");
+                }
+                catch {
+                    // Closing a failed source is best effort and cannot escape this task.
+                }
+            }
+            finally {
+                client.sending = false;
+                if (client.retireAfterDrain)
+                    await this.#closeClient(client).catch(() => undefined);
+            }
+        });
+    }
+    async #closeClient(client, reason = "closed") {
+        if (client.closed)
+            return;
+        client.closed = true;
+        client.resolveClosed(reason);
+        if (client.lifecycleOpenRecorded)
+            this.#recordDeliveryLifecycle(client, this.#panes.get(client.paneId), "close");
+        client.backgroundTimer?.cancel();
+        client.outgoing.length = 0;
+        this.#clients.delete(client.key);
+        this.#pruneCanonicalRevisions(client.paneId);
+        if ([...this.#clients.values()].some((candidate) => candidate.paneId === client.paneId))
+            return;
+        const pane = this.#panes.get(client.paneId);
+        this.#panes.delete(client.paneId);
+        if (pane) {
+            pane.pendingCanonical.length = 0;
+            pane.canonicalScheduled = false;
+        }
+        await pane?.source?.close().catch(() => undefined);
+        this.#clearCache();
+    }
+    #recordDeliveryLifecycle(client, pane, event) {
+        if (!this.#observability.enabled)
+            return false;
+        const canonical = pane?.latest?.update;
+        if (!canonical)
+            return false;
+        try {
+            const atMicros = this.#observability.nowMicros();
+            this.#observability.recordSpan("transport", "terminal-delivery-subscriber-lifecycle", atMicros, atMicros, null, undefined, Object.freeze({
+                workspaceName: this.workspaceName,
+                semanticPaneId: client.paneId,
+                canonicalGeneration: this.generation,
+                canonicalIncarnation: canonical.incarnation,
+                canonicalRevision: canonical.revision,
+                canonicalStateHash: canonical.stateHash,
+                deliveryClientId: client.diagnosticClientId,
+                deliverySurface: client.diagnosticSurface,
+                deliveryLaneId: client.diagnosticLaneId,
+                deliveryRequestId: client.diagnosticRequestId,
+                deliveryLifecycleEvent: event,
+                deliveryPurpose: "terminal-surface",
+                deliveryLifecycleOrdinal: ++this.#deliveryLifecycleOrdinal,
+            }));
+            return true;
+        }
+        catch {
+            // Detailed lifecycle evidence is fail-open for product delivery.
+            return false;
+        }
+    }
+    #recordDeliveryStatus(client, pane) {
+        if (!this.#observability.enabled || client.closed)
+            return false;
+        const canonical = pane?.latest?.update;
+        if (!canonical)
+            return false;
+        try {
+            const atMicros = this.#observability.nowMicros();
+            this.#observability.recordSpan("transport", "terminal-delivery-subscriber-status", atMicros, atMicros, null, undefined, Object.freeze({
+                workspaceName: this.workspaceName,
+                semanticPaneId: client.paneId,
+                canonicalGeneration: this.generation,
+                canonicalIncarnation: canonical.incarnation,
+                canonicalRevision: canonical.revision,
+                canonicalStateHash: canonical.stateHash,
+                deliveryClientId: client.diagnosticClientId,
+                deliverySurface: client.diagnosticSurface,
+                deliveryLaneId: client.diagnosticLaneId,
+                deliveryRequestId: client.diagnosticRequestId,
+                deliveryPurpose: "terminal-surface",
+                deliveryStatusOrdinal: ++this.#deliveryStatusOrdinal,
+                deliveryVisibility: client.visibility,
+                deliveryBaselineRevision: client.baselineRevision,
+                deliveryBaselineHash: client.baselineHash,
+                deliveryInFlightRevision: client.inFlight?.envelope.canonicalRevision ?? null,
+                deliveryInFlightHash: client.inFlight?.envelope.canonicalStateHash ?? null,
+                deliveryLatestRevision: client.latestRevision,
+                deliveryClientQueueDepth: client.outgoing.length,
+            }));
+            return true;
+        }
+        catch {
+            // Detailed readiness evidence never owns terminal delivery.
+            return false;
+        }
+    }
+    async #withDeadline(promise, milliseconds) {
+        let timer;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((_, reject) => {
+                    timer = this.#scheduler.timer(() => reject(new Error("Terminal delivery sink timed out")), milliseconds);
+                }),
+            ]);
+        }
+        finally {
+            timer?.cancel();
+        }
+    }
+    #cacheSet(key, value) {
+        if (value.bytes.byteLength > MAX_REPRESENTATION_CACHE_BYTES)
+            return;
+        const previous = this.#cache.get(key);
+        if (previous)
+            this.#cacheBytes -= previous.bytes.byteLength;
+        this.#cache.set(key, value);
+        this.#cacheBytes += value.bytes.byteLength;
+        while (this.#cache.size > MAX_REPRESENTATION_CACHE_ENTRIES ||
+            this.#cacheBytes > MAX_REPRESENTATION_CACHE_BYTES) {
+            const first = this.#cache.entries().next().value;
+            if (!first)
+                break;
+            this.#cache.delete(first[0]);
+            this.#cacheBytes -= first[1].bytes.byteLength;
+        }
+    }
+    #clearCache() {
+        this.#cache.clear();
+        this.#cacheBytes = 0;
+    }
+    #pruneCanonicalRevisions(paneId) {
+        const pane = this.#panes.get(paneId);
+        if (!pane?.latest)
+            return;
+        const latest = pane.latest.update;
+        const reachable = new Set([latest.revision]);
+        for (const client of this.#clients.values()) {
+            if (client.closed || client.paneId !== paneId)
+                continue;
+            const baseline = pane.revisions.get(client.baselineRevision)?.update;
+            if (!client.reseedRequired &&
+                baseline?.incarnation === latest.incarnation &&
+                baseline.stateHash === client.baselineHash)
+                reachable.add(client.baselineRevision);
+            const flight = client.inFlight?.envelope;
+            if (flight?.incarnation === latest.incarnation)
+                reachable.add(flight.canonicalRevision);
+        }
+        // A hidden or slow reader owns at most one baseline and one transaction.
+        // Historical redraws with no reader cannot help a future delivery: new
+        // readers and skipped revisions already receive an atomic current seed.
+        // MAX_CLIENTS bounds this set to 2 * MAX_CLIENTS + 1 per pane.
+        for (const revision of pane.revisions.keys())
+            if (!reachable.has(revision))
+                pane.revisions.delete(revision);
+    }
+    #pruneAckSupersededCache(paneId) {
+        const clients = [...this.#clients.values()].filter((candidate) => !candidate.closed && candidate.paneId === paneId);
+        for (const [key, cached] of this.#cache) {
+            if (cached.cachePaneId !== paneId)
+                continue;
+            const reachable = clients.some((candidate) => cached.cacheBaseRevision === candidate.baselineRevision ||
+                (Number.isSafeInteger(cached.cacheTargetRevision) &&
+                    cached.cacheTargetRevision > candidate.baselineRevision) ||
+                cached.cacheTargetRevision === candidate.inFlight?.envelope.canonicalRevision);
+            if (reachable)
+                continue;
+            this.#cache.delete(key);
+            this.#cacheBytes -= cached.bytes.byteLength;
+        }
+    }
+}
+export function selectExactSemanticRepresentation(encodePatch, encodeSeed, observe = true) {
+    let patch;
+    try {
+        patch = encodePatch();
+    }
+    catch (error) {
+        if (!(error instanceof TerminalDeliveryStateTooLargeError))
+            throw error;
+        let seed;
+        try {
+            seed = encodeSeed();
+        }
+        catch (seedError) {
+            if (!(seedError instanceof TerminalDeliveryStateTooLargeError))
+                throw seedError;
+            throw new ExactSemanticRepresentationSelectionError(seedError.bytes, {
+                attemptedPatchBytes: error.bytes,
+                attemptedSeedBytes: seedError.bytes,
+                selectionStatus: "seed-preferred",
+            });
+        }
+        if (!observe)
+            return seed;
+        return {
+            ...seed,
+            observation: Object.freeze({
+                attemptedPatchBytes: error.bytes,
+                attemptedSeedBytes: seed.bytes.byteLength,
+                selectionStatus: "seed-preferred",
+            }),
+        };
+    }
+    if (patch.payload.frame !== "patch") {
+        if (!observe)
+            return patch;
+        return {
+            ...patch,
+            observation: Object.freeze({
+                attemptedPatchBytes: null,
+                attemptedSeedBytes: patch.payload.frame === "seed" ? patch.bytes.byteLength : null,
+                selectionStatus: patch.payload.frame === "seed" ? "direct-seed" : "direct-tombstone",
+            }),
+        };
+    }
+    if (patch.bytes.byteLength <= TERMINAL_DELIVERY_PATCH_TO_SEED_BYTES) {
+        if (!observe)
+            return patch;
+        return {
+            ...patch,
+            observation: Object.freeze({
+                attemptedPatchBytes: patch.bytes.byteLength,
+                attemptedSeedBytes: null,
+                selectionStatus: "patch-preferred",
+            }),
+        };
+    }
+    try {
+        const seed = encodeSeed();
+        const selected = patch.bytes.byteLength <= seed.bytes.byteLength ? patch : seed;
+        if (!observe)
+            return selected;
+        return {
+            ...selected,
+            observation: Object.freeze({
+                attemptedPatchBytes: patch.bytes.byteLength,
+                attemptedSeedBytes: seed.bytes.byteLength,
+                selectionStatus: selected === patch ? "patch-preferred" : "seed-preferred",
+            }),
+        };
+    }
+    catch (error) {
+        if (!(error instanceof TerminalDeliveryStateTooLargeError))
+            throw error;
+        if (!observe)
+            return patch;
+        return {
+            ...patch,
+            observation: Object.freeze({
+                attemptedPatchBytes: patch.bytes.byteLength,
+                attemptedSeedBytes: error.bytes,
+                selectionStatus: "patch-fallback",
+            }),
+        };
+    }
+}
+function completeSemanticSelectionObservation(observation, selectedEncoding, legacyAttempts) {
+    const compact = selectedEncoding === "semantic-compact-v1";
+    return Object.freeze({
+        ...observation,
+        attemptedLegacyPatchBytes: compact
+            ? (legacyAttempts?.patchBytes ?? null)
+            : observation.attemptedPatchBytes,
+        attemptedLegacySeedBytes: compact
+            ? (legacyAttempts?.seedBytes ?? null)
+            : observation.attemptedSeedBytes,
+        attemptedLegacyPatchAtLeastBytes: null,
+        attemptedLegacySeedAtLeastBytes: null,
+        attemptedLegacyPatchSizeCapped: false,
+        attemptedLegacySeedSizeCapped: false,
+        attemptedCompactPatchBytes: compact ? observation.attemptedPatchBytes : null,
+        attemptedCompactSeedBytes: compact ? observation.attemptedSeedBytes : null,
+        selectedEncoding,
+    });
+}
+function legacyFallbackObservation(frame, compactBytes, legacyBytes) {
+    return Object.freeze({
+        attemptedPatchBytes: frame === "patch" ? legacyBytes : null,
+        attemptedSeedBytes: frame === "seed" ? legacyBytes : null,
+        attemptedLegacyPatchBytes: frame === "patch" ? legacyBytes : null,
+        attemptedLegacySeedBytes: frame === "seed" ? legacyBytes : null,
+        attemptedLegacyPatchAtLeastBytes: null,
+        attemptedLegacySeedAtLeastBytes: null,
+        attemptedLegacyPatchSizeCapped: false,
+        attemptedLegacySeedSizeCapped: false,
+        attemptedCompactPatchBytes: frame === "patch" ? compactBytes : null,
+        attemptedCompactSeedBytes: frame === "seed" ? compactBytes : null,
+        selectedEncoding: "semantic-v1",
+        selectionStatus: frame === "patch" ? "legacy-patch-fallback" : "legacy-seed-fallback",
+    });
+}
+function legacyFallbackFromSelection(legacy, compact, frame) {
+    return Object.freeze({
+        attemptedPatchBytes: legacy.attemptedPatchBytes,
+        attemptedSeedBytes: legacy.attemptedSeedBytes,
+        attemptedLegacyPatchBytes: legacy.attemptedPatchBytes,
+        attemptedLegacySeedBytes: legacy.attemptedSeedBytes,
+        attemptedLegacyPatchAtLeastBytes: null,
+        attemptedLegacySeedAtLeastBytes: null,
+        attemptedLegacyPatchSizeCapped: false,
+        attemptedLegacySeedSizeCapped: false,
+        attemptedCompactPatchBytes: compact.attemptedPatchBytes,
+        attemptedCompactSeedBytes: compact.attemptedSeedBytes,
+        selectedEncoding: "semantic-v1",
+        selectionStatus: frame === "patch" ? "legacy-patch-fallback" : "legacy-seed-fallback",
+    });
+}
+function failedCompactAndLegacyObservation(frame, compactBytes, legacyError) {
+    const capped = legacyError instanceof TerminalDeliveryPreaccountLimitError;
+    return Object.freeze({
+        attemptedPatchBytes: frame === "patch" ? compactBytes : null,
+        attemptedSeedBytes: frame === "seed" ? compactBytes : null,
+        attemptedLegacyPatchBytes: !capped && frame === "patch" ? legacyError.bytes : null,
+        attemptedLegacySeedBytes: !capped && frame === "seed" ? legacyError.bytes : null,
+        attemptedLegacyPatchAtLeastBytes: capped && frame === "patch" ? legacyError.atLeastBytes : null,
+        attemptedLegacySeedAtLeastBytes: capped && frame === "seed" ? legacyError.atLeastBytes : null,
+        attemptedLegacyPatchSizeCapped: capped && frame === "patch",
+        attemptedLegacySeedSizeCapped: capped && frame === "seed",
+        attemptedCompactPatchBytes: frame === "patch" ? compactBytes : null,
+        attemptedCompactSeedBytes: frame === "seed" ? compactBytes : null,
+        selectedEncoding: "semantic-compact-v1",
+        selectionStatus: frame === "patch" ? "patch-preferred" : "direct-seed",
+    });
+}
+function failedCompactAndLegacySelectionObservation(compact, legacy) {
+    return Object.freeze({
+        attemptedPatchBytes: compact.attemptedPatchBytes,
+        attemptedSeedBytes: compact.attemptedSeedBytes,
+        attemptedLegacyPatchBytes: legacy.attemptedPatchBytes,
+        attemptedLegacySeedBytes: legacy.attemptedSeedBytes,
+        attemptedLegacyPatchAtLeastBytes: null,
+        attemptedLegacySeedAtLeastBytes: null,
+        attemptedLegacyPatchSizeCapped: false,
+        attemptedLegacySeedSizeCapped: false,
+        attemptedCompactPatchBytes: compact.attemptedPatchBytes,
+        attemptedCompactSeedBytes: compact.attemptedSeedBytes,
+        selectedEncoding: "semantic-compact-v1",
+        selectionStatus: compact.selectionStatus,
+    });
+}
+function terminalSelectionObservation(observation) {
+    return Object.freeze({
+        selectionStatus: observation.selectionStatus,
+        selectedEncoding: observation.selectedEncoding,
+        attemptedLegacyPatchBytes: observation.attemptedLegacyPatchBytes,
+        attemptedLegacySeedBytes: observation.attemptedLegacySeedBytes,
+        attemptedLegacyPatchAtLeastBytes: observation.attemptedLegacyPatchAtLeastBytes,
+        attemptedLegacySeedAtLeastBytes: observation.attemptedLegacySeedAtLeastBytes,
+        attemptedLegacyPatchSizeCapped: observation.attemptedLegacyPatchSizeCapped,
+        attemptedLegacySeedSizeCapped: observation.attemptedLegacySeedSizeCapped,
+        attemptedCompactPatchBytes: observation.attemptedCompactPatchBytes,
+        attemptedCompactSeedBytes: observation.attemptedCompactSeedBytes,
+    });
+}
+function semanticSelectionObservationFromError(error) {
+    return error instanceof TerminalDeliveryRepresentationSelectionError
+        ? error.selectionObservation
+        : null;
+}
+function semanticPayload(baselineRevision, baseline, target) {
+    const update = target.update;
+    if (!target.state.snapshot) {
+        if (update.type !== "terminal.tombstone")
+            throw new TypeError("Missing tombstone update");
+        return {
+            frame: "tombstone",
+            baseRevision: Math.max(0, baselineRevision),
+            revision: update.revision,
+            tombstone: update.tombstone,
+        };
+    }
+    // Adjacent canonical patches are already the cheapest exact diff. A skipped
+    // revision uses an atomic seed; the m56.2 adjacent reducer is never weakened.
+    if (baseline && update.type === "terminal.patch" && update.baseRevision === baselineRevision)
+        return {
+            frame: "patch",
+            baseRevision: baselineRevision,
+            revision: update.revision,
+            patch: update.patch,
+        };
+    return semanticSeed(target);
+}
+function encodeLegacySemanticCandidate(payload) {
+    const preaccounted = preaccountSemanticTerminalUpdateBytes(payload, TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES);
+    if (!preaccounted.exact)
+        throw new TerminalDeliveryPreaccountLimitError(preaccounted.atLeastBytes);
+    const bytes = encodeSemanticTerminalUpdate(payload);
+    if (bytes.byteLength !== preaccounted.bytes)
+        throw new TypeError("Legacy semantic byte preaccount did not match encoding");
+    return bytes;
+}
+function semanticSeed(target) {
+    if (!target.state.snapshot)
+        throw new TypeError("Cannot seed a tombstone");
+    return { frame: "seed", revision: target.update.revision, snapshot: target.state.snapshot };
+}
+function emptyTombstone() {
+    return {
+        bytes: new Uint8Array(),
+        frame: "tombstone",
+        canonicalEquivalent: false,
+        history: "not-applicable",
+    };
+}
+function cacheKey(parts) {
+    return JSON.stringify(parts);
+}
+function rejectedConnection(negotiation) {
+    return {
+        negotiation,
+        closed: Promise.resolve("closed"),
+        ack: () => undefined,
+        nack: () => undefined,
+        setVisibility: () => undefined,
+        close: async () => undefined,
+    };
+}
+function joinBytes(chunks) {
+    const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+    const joined = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return joined;
+}