@timurproko/a1 0.1.8-dev.322 → 0.1.8-dev.332

package/dist/integrations/pi/engine/adapter.js

@@ -14,6 +14,11 @@ import { PINNED_PI_SETTINGS_CALLBACKS, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from
 import { createPiRuntimeIntegration } from "./runtime-integration.js";
 import { PiSessionCommandIntegration } from "./session-integration.js";
 import { PiSettingsIntegration } from "./settings-integration.js";
+import { PendingEngineDelivery } from "./pending-delivery.js";
+/** Explicit flush failure when required delivery was interrupted rather than completed. */
+export class EngineDeliveryError extends Error {
+    constructor() { super("Engine delivery did not complete"); this.name = "EngineDeliveryError"; }
+}
 const execFileAsync = promisify(execFile);
 /**
  * Engine events delivered before the queue hands the event loop a turn. Small enough
@@ -24,7 +29,6 @@ const execFileAsync = promisify(execFile);
 // be expensive in long sessions; a larger synchronous batch starves terminal
 // input and makes an in-progress mouse selection appear frozen.
 const EVENT_DELIVERY_BATCH = 1;
-const TOOL_UPDATE_COALESCE_MS = 50;
 const AUTH_REFRESH_TIMEOUT_MS = 15_000;
 // Provenance: Pi 0.84.2 core/model-resolver.ts defaultModelPerProvider.
 const PINNED_DEFAULT_MODEL_BY_PROVIDER = Object.freeze({
@@ -87,7 +91,7 @@ export class PiEngineAdapter {
     #sessionForkPrompt;
     #workflowHost;
     #workflowInteraction;
-    #listeners = new Set();
+    #listeners = new Map();
     #runtime;
     #session;
     #unsubscribe;
@@ -103,6 +107,7 @@ export class PiEngineAdapter {
         submitEnabled: false,
     };
     #sessionGeneration = 0;
+    #sessionBindingGeneration = 0;
     #status = {
         title: "Pi",
         workingMessage: null,
@@ -121,14 +126,20 @@ export class PiEngineAdapter {
     #messageFallbackIds = new Map();
     #toolBlockIds = new Map();
     #transcriptImageAssets = new Map();
-    #pendingToolUpdates = new Map();
-    #toolUpdateFlush = null;
     #usageCache;
     #nextBlockSequence = 0;
     #diagnostics = [];
-    #eventQueue = [];
+    #eventQueue = new PendingEngineDelivery();
     #eventQueueProcessing;
-    #droppedEventCount = 0;
+    #overload;
+    #overloads = 0;
+    #deliveryFailed = false;
+    #admissionStopped = false;
+    #runningCommands = 0;
+    #invalidatedEvents = 0;
+    #pendingCommands = new Map();
+    #reservedOutcomes = new Map();
+    #pendingWorkflows = new Set();
     #agentRunActive = false;
     #agentRunSequence = 0;
     #assistantResponseSequence = 0;
@@ -171,6 +182,8 @@ export class PiEngineAdapter {
     get sessionGeneration() {
         return this.#sessionGeneration;
     }
+    /** Actual session replacements, excluding delivery-only invalidation of callbacks. */
+    get sessionBindingGeneration() { return this.#sessionBindingGeneration; }
     get cwd() {
         return this.#runtime?.cwd ?? this.#cwd;
     }
@@ -209,7 +222,7 @@ export class PiEngineAdapter {
         const session = this.#session;
         const runtime = this.#runtime;
         const activeModel = this.#activeModel;
-        if (this.#disposed || session === undefined || runtime === undefined || request.signal.aborted
+        if (this.#disposed || this.#overload !== undefined || this.#admissionStopped || session === undefined || runtime === undefined || request.signal.aborted
             || identity.sessionId !== this.#sessionId
             || identity.sessionGeneration !== this.#sessionGeneration
             || identity.runSequence !== this.#agentRunSequence
@@ -290,6 +303,8 @@ export class PiEngineAdapter {
             hardwareCursor: runtime.services.settingsManager?.getShowHardwareCursor?.() ?? this.#terminal.hardwareCursor,
         };
         runtime.setRebindSession(async (session) => {
+            if (this.#overload !== undefined || this.#admissionStopped || this.#disposed)
+                return;
             this.#bindSession(session);
             this.#emitView();
         });
@@ -343,14 +358,24 @@ export class PiEngineAdapter {
         this.#emitView();
     }
     onEvent(listener) {
-        this.#listeners.add(listener);
-        listener(this.#event({ type: "session-view", view: this.view() }));
+        const initial = this.#event({ type: "session-view", view: this.view() });
+        this.#listeners.set(listener, initial.sequence);
+        listener(initial);
         return () => this.#listeners.delete(listener);
     }
+    /** Developer-only pressure evidence; never mirrored into visible diagnostic/status arrays. */
+    deliveryDiagnostics() {
+        return { ...this.#eventQueue.diagnostics(), overloads: this.#overloads, recovering: this.#overload !== undefined,
+            pendingCommands: this.#pendingCommands.size + this.#pendingWorkflows.size, reservedOutcomes: this.#reservedOutcomes.size, invalidatedEvents: this.#invalidatedEvents };
+    }
     async flushEvents() {
-        this.#flushPendingToolUpdates();
+        const failed = this.#deliveryFailed;
         while (this.#eventQueueProcessing)
             await this.#eventQueueProcessing;
+        if (failed || this.#deliveryFailed || this.#disposed && this.#lifecycle !== "stopped") {
+            this.#deliveryFailed = false;
+            throw new EngineDeliveryError();
+        }
     }
     nonVisualResources() {
         const loader = this.#runtime?.services.resourceLoader;
@@ -1028,6 +1053,24 @@ export class PiEngineAdapter {
         return null;
     }
     async executeWorkflow(request) {
+        const cancelled = workflowResult(request.command, "cancelled", "", undefined, "silent");
+        if (this.#overload !== undefined || this.#admissionStopped || this.#disposed
+            || this.#pendingCommands.size + this.#pendingWorkflows.size >= 32)
+            return cancelled;
+        let cancel;
+        const cancellation = new Promise(resolve => { cancel = () => resolve(cancelled); });
+        const pending = { command: request.command, cancel };
+        this.#pendingWorkflows.add(pending);
+        this.#runningCommands++;
+        const operation = this.#runWorkflow(request).finally(() => { this.#runningCommands--; });
+        try {
+            return await Promise.race([operation, cancellation]);
+        }
+        finally {
+            this.#pendingWorkflows.delete(pending);
+        }
+    }
+    async #runWorkflow(request) {
         try {
             return await this.#performWorkflow(request);
         }
@@ -1094,6 +1137,9 @@ export class PiEngineAdapter {
         if (this.#disposed || !this.#runtime || !this.#session) {
             return this.#finishCommand(command, "rejected", "engine adapter is not running");
         }
+        // Invariant: the bounded out-of-band cancellation path has one slot per admitted command.
+        if (this.#overload !== undefined || this.#admissionStopped || this.#pendingCommands.size + this.#pendingWorkflows.size >= 32)
+            return { outcome: "rejected", diagnostic: null };
         const existing = this.#completedCommands.get(command.correlationId);
         if (existing)
             return existing;
@@ -1101,33 +1147,64 @@ export class PiEngineAdapter {
             return this.#finishCommand(command, "rejected", "duplicate engine command correlation id");
         }
         this.#activeCommandIds.push(command.correlationId);
-        this.#emitEvent({
-            type: "command-outcome",
-            correlationId: command.correlationId,
-            outcome: "accepted",
-            diagnostic: null,
+        const generation = this.#sessionGeneration;
+        let cancelled = false;
+        const cancellation = new Promise(resolve => {
+            this.#pendingCommands.set(command.correlationId, { type: command.type, cancel: () => {
+                    if (cancelled)
+                        return;
+                    cancelled = true;
+                    resolve(this.#recordCommand(command, "failed", null));
+                } });
         });
+        this.#emitEvent({ type: "command-outcome", correlationId: command.correlationId, outcome: "accepted", diagnostic: null });
+        const operation = async () => {
+            try {
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                this.#runningCommands++;
+                try {
+                    await this.#perform(command);
+                }
+                finally {
+                    this.#runningCommands--;
+                }
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                if (generation === this.#sessionGeneration)
+                    this.#emitView();
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                return this.#recordCommand(command, "completed", null);
+            }
+            catch (error) {
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                const diagnostic = error instanceof Error ? error.message : String(error);
+                this.#addDiagnostic("error", "engine-command", diagnostic, true);
+                if (generation === this.#sessionGeneration)
+                    this.#emitView();
+                return this.#recordCommand(command, "failed", diagnostic);
+            }
+        };
         try {
-            await this.#perform(command);
-            this.#emitView();
-            return this.#recordCommand(command, "completed", null);
+            return await Promise.race([operation(), cancellation]);
         }
-        catch (error) {
-            const diagnostic = error instanceof Error ? error.message : String(error);
-            this.#addDiagnostic("error", "engine-command", diagnostic, true);
-            this.#emitView();
-            return this.#recordCommand(command, "failed", diagnostic);
+        finally {
+            this.#pendingCommands.delete(command.correlationId);
         }
     }
     async dispose() {
         if (this.#disposed)
             return;
         this.#disposed = true;
-        if (this.#toolUpdateFlush !== null) {
-            clearTimeout(this.#toolUpdateFlush);
-            this.#toolUpdateFlush = null;
-        }
-        this.#pendingToolUpdates.clear();
+        for (const pending of this.#pendingCommands.values())
+            if (pending.type !== "shutdown")
+                pending.cancel();
+        // Compatibility: /quit owns normal disposal and must report its actual completion, not cancel itself.
+        for (const pending of this.#pendingWorkflows)
+            if (pending.command !== "quit")
+                pending.cancel();
         this.#transcriptImageAssets.clear();
         this.#extensionBound = false;
         this.#extensionUi = undefined;
@@ -1140,7 +1217,13 @@ export class PiEngineAdapter {
         this.#lifecycle = "stopped";
         this.#emitEvent({ type: "session-lifecycle", lifecycle: "stopped", reason: null });
         this.#emitView();
-        await this.flushEvents();
+        try {
+            await this.flushEvents();
+        }
+        catch (error) {
+            if (!(error instanceof EngineDeliveryError))
+                throw error;
+        }
     }
     async #performWorkflow(request) {
         const session = this.#requireWorkflowSession();
@@ -1821,6 +1904,7 @@ export class PiEngineAdapter {
     async #perform(command) {
         const runtime = this.#runtime;
         const session = this.#session;
+        const generation = this.#sessionGeneration;
         if (!runtime || !session)
             throw new Error("engine session is unavailable");
         switch (command.type) {
@@ -1848,7 +1932,8 @@ export class PiEngineAdapter {
                     throw new Error(`model is unavailable: ${command.model.providerId}/${command.model.modelId}`);
                 }
                 await session.setModel(model);
-                this.#activeModel = { ...command.model };
+                if (generation === this.#sessionGeneration && this.#overload === undefined && !this.#admissionStopped)
+                    this.#activeModel = { ...command.model };
                 return;
             }
             case "set-thinking-level":
@@ -1876,7 +1961,13 @@ export class PiEngineAdapter {
     }
     #bindSession(session) {
         this.#unsubscribe?.();
+        for (const pending of this.#pendingCommands.values()) {
+            if (pending.type !== "new-session" && pending.type !== "resume-session")
+                pending.cancel();
+        }
         this.#sessionGeneration += 1;
+        this.#sessionBindingGeneration += 1;
+        this.#invalidatedEvents += this.#eventQueue.discardObsolete(this.#sessionGeneration);
         this.#session = session;
         this.#activeCommandIds = [];
         this.#completedCommands.clear();
@@ -1899,7 +1990,11 @@ export class PiEngineAdapter {
         this.#thinkingLevel = readThinkingLevel(session.thinkingLevel);
         this.#transcriptImageAssets.clear();
         this.#rebuildTranscript(session.messages, "finalized");
-        this.#unsubscribe = session.subscribe(event => this.#handlePiEvent(event));
+        const generation = this.#sessionGeneration;
+        this.#unsubscribe = session.subscribe(event => {
+            if (generation === this.#sessionGeneration && !this.#disposed)
+                this.#handlePiEvent(event);
+        });
         if (this.#extensionUi !== undefined)
             void this.#bindExtensionUiToSession();
     }
@@ -2059,15 +2154,11 @@ export class PiEngineAdapter {
                 return;
             case "tool_execution_start":
             case "tool_execution_end": {
-                // Concurrency: the end supersedes any update still waiting on the coalescing timer.
-                const toolCallId = stringValue(event.toolCallId);
-                if (toolCallId !== undefined)
-                    this.#pendingToolUpdates.delete(toolCallId);
                 this.#upsertToolExecutionBlock(event);
                 return;
             }
             case "tool_execution_update":
-                this.#coalesceToolExecutionUpdate(event);
+                this.#upsertToolExecutionBlock(event);
                 return;
             case "agent_settled":
             case "agent_end": {
@@ -2079,7 +2170,7 @@ export class PiEngineAdapter {
                 if (finalMessages.length > 0)
                     this.#rebuildTranscript(finalMessages, "finalized");
                 else
-                    this.#setTranscript(this.#transcript.map(block => block.status === "live" ? { ...block, status: "finalized" } : block));
+                    this.#setTranscript(this.#transcript.map(block => block.status === "live" ? { ...block, status: "finalized", revision: block.revision + 1 } : block));
                 // Compatibility: ending a turn leaves the working state, as the recorded pinned baseline does, but
                 // it leaves only that state: a compaction or retry being shown outlives the turn
                 // that ended under it. Settlement ends the run, and with it every state — the
@@ -2401,30 +2492,6 @@ export class PiEngineAdapter {
         }
         return references;
     }
-    // Performance: coalescing each tool to its newest chunk bounds work by frames, not stream events.
-    #coalesceToolExecutionUpdate(event) {
-        const toolCallId = stringValue(event.toolCallId);
-        if (!toolCallId)
-            return;
-        this.#pendingToolUpdates.set(toolCallId, event);
-        this.#toolUpdateFlush ??= setTimeout(() => {
-            this.#toolUpdateFlush = null;
-            if (!this.#disposed)
-                this.#flushPendingToolUpdates();
-        }, TOOL_UPDATE_COALESCE_MS);
-    }
-    #flushPendingToolUpdates() {
-        if (this.#toolUpdateFlush !== null) {
-            clearTimeout(this.#toolUpdateFlush);
-            this.#toolUpdateFlush = null;
-        }
-        if (this.#pendingToolUpdates.size === 0)
-            return;
-        const pending = [...this.#pendingToolUpdates.values()];
-        this.#pendingToolUpdates.clear();
-        for (const update of pending)
-            this.#upsertToolExecutionBlock(update);
-    }
     #upsertToolExecutionBlock(event) {
         const toolCallId = stringValue(event.toolCallId);
         if (!toolCallId)
@@ -2457,6 +2524,9 @@ export class PiEngineAdapter {
         const index = this.#transcriptIndex.get(block.id);
         if (index !== undefined) {
             const existing = this.#transcript[index];
+            // Invariant: an obsolete partial cannot revive finalized content after a completion barrier.
+            if (existing?.status === "finalized" && block.status === "live")
+                return;
             // Performance: nothing is emitted for a block that repeats itself, and keeping the
             // revision keeps the rows it already rendered.
             if (existing !== undefined && sameBlockContent(existing, block))
@@ -2540,52 +2610,118 @@ export class PiEngineAdapter {
         this.#enqueueEvent(event);
     }
     #enqueueEvent(event) {
-        const capacity = 1_024;
-        if (this.#eventQueue.length >= capacity) {
-            const coalescible = this.#eventQueue.findIndex(queued => queued.type === "session-view"
-                || queued.type === "status"
-                || queued.type === "editor-state"
-                || queued.type === "transcript-block");
-            if (coalescible >= 0)
-                this.#eventQueue.splice(coalescible, 1);
-            else
-                this.#eventQueue.shift();
-            this.#droppedEventCount += 1;
-            if (this.#droppedEventCount === 1 || this.#droppedEventCount % 128 === 0) {
-                this.#recordDiagnostic("warning", "event-backpressure", `owned UI coalesced ${this.#droppedEventCount} engine events under backpressure`, true);
+        if (this.#overload !== undefined) {
+            if (event.type === "command-outcome" && event.outcome !== "accepted" && this.#pendingCommands.has(event.correlationId)) {
+                this.#reservedOutcomes.set(event.correlationId, { outcome: event.outcome, diagnostic: event.diagnostic });
+            }
+            return;
+        }
+        if (!this.#eventQueue.push(event, this.#sessionGeneration, event.type === "transcript-block"
+            ? this.#blockReconciliation(event.block.id, event.sequence) : undefined)) {
+            this.#beginOverload();
+            if (event.type === "command-outcome" && event.outcome !== "accepted" && this.#pendingCommands.has(event.correlationId)
+                && !this.#reservedOutcomes.has(event.correlationId)) {
+                this.#reservedOutcomes.set(event.correlationId, { outcome: event.outcome, diagnostic: event.diagnostic });
             }
         }
-        this.#eventQueue.push(event);
         this.#eventQueueProcessing ??= Promise.resolve().then(() => this.#processEventQueue());
     }
+    // Performance: capture only identity, not the complete block/event retained by an earlier revision.
+    #blockReconciliation(id, sequence) {
+        return () => ({ type: "transcript-block", sessionId: this.#sessionId, sequence, block: this.#transcriptBlock(id) });
+    }
+    #beginOverload() {
+        if (this.#overload !== undefined)
+            return;
+        this.#overloads = Math.min(Number.MAX_SAFE_INTEGER, this.#overloads + 1);
+        this.#deliveryFailed = true;
+        // Concurrency: reserve before cancellation; outcomes produced reentrantly must not enter the saturated queue.
+        this.#overload = Promise.resolve(false);
+        for (const pending of this.#pendingCommands.values())
+            pending.cancel();
+        for (const pending of this.#pendingWorkflows)
+            pending.cancel();
+        const session = this.#session;
+        this.#overload = new Promise(resolve => {
+            const timer = setTimeout(() => resolve(false), 2000);
+            void Promise.resolve().then(() => session?.abort()).then(() => {
+                clearTimeout(timer);
+                resolve(true);
+            }, () => { clearTimeout(timer); resolve(false); });
+        });
+    }
+    #deliver(event) {
+        for (const [listener, subscribedAt] of this.#listeners) {
+            if (event.sequence <= subscribedAt)
+                continue;
+            try {
+                listener(event);
+            }
+            catch (error) {
+                this.#deliveryFailed = true;
+                this.#recordDiagnostic("warning", "event-listener", error instanceof Error ? error.message : String(error), true);
+            }
+        }
+    }
+    async #reconcileOverload() {
+        const cancelled = await this.#overload;
+        const canResume = cancelled === true && this.#runningCommands === 0;
+        this.#admissionStopped = !canResume;
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        ++this.#sessionGeneration;
+        this.#agentRunActive = false;
+        this.#statusKind = null;
+        this.#status = { ...this.#status, workingMessage: null };
+        this.#lifecycle = this.#disposed ? "stopped" : canResume ? "ready" : "failed";
+        this.#editor = { ...this.#editor, submitEnabled: canResume && !this.#disposed };
+        this.#viewRevision += 1;
+        this.#setTranscript(this.#transcript.map(block => block.status === "live" ? { ...block, status: "finalized", revision: block.revision + 1 } : block));
+        for (const [correlationId, result] of this.#reservedOutcomes) {
+            this.#deliver(this.#event({ type: "command-outcome", correlationId, ...result }));
+            await new Promise(resolve => setImmediate(resolve));
+        }
+        this.#reservedOutcomes.clear();
+        // Invariant: one out-of-band authoritative reconciliation, not an emergency transcript/event log.
+        this.#deliver(this.#event({ type: "session-view", view: this.view() }));
+        if (this.#disposed)
+            this.#deliver(this.#event({ type: "session-lifecycle", lifecycle: "stopped", reason: null }));
+        if (canResume && !this.#disposed && this.#session !== undefined) {
+            const generation = this.#sessionGeneration;
+            this.#unsubscribe = this.#session.subscribe(event => {
+                if (generation === this.#sessionGeneration && !this.#disposed)
+                    this.#handlePiEvent(event);
+            });
+        }
+        this.#overload = undefined;
+    }
     async #processEventQueue() {
         try {
             let deliveredSinceYield = 0;
-            while (this.#eventQueue.length > 0) {
-                const event = this.#eventQueue.shift();
-                if (!event)
+            while (this.#eventQueue.size > 0) {
+                const pending = this.#eventQueue.shift();
+                if (pending === undefined)
+                    continue;
+                if (pending.generation !== this.#sessionGeneration && pending.event.type !== "command-outcome") {
+                    this.#invalidatedEvents = Math.min(Number.MAX_SAFE_INTEGER, this.#invalidatedEvents + 1);
                     continue;
-                for (const listener of this.#listeners) {
-                    try {
-                        listener(event);
-                    }
-                    catch (error) {
-                        this.#recordDiagnostic("warning", "event-listener", error instanceof Error ? error.message : String(error), true);
-                    }
                 }
+                this.#deliver(pending.event);
                 deliveredSinceYield += 1;
                 // Concurrency: a microtask chain runs to exhaustion before the loop turns, so a streaming
                 // burst would hold typed input, pointer reports, and timed indicators until it
                 // drained. Yielding on a macrotask hands those their turn between batches.
-                if (deliveredSinceYield >= EVENT_DELIVERY_BATCH && this.#eventQueue.length > 0) {
+                if (deliveredSinceYield >= EVENT_DELIVERY_BATCH && this.#eventQueue.size > 0) {
                     deliveredSinceYield = 0;
                     await new Promise(resolve => { setImmediate(resolve); });
                 }
             }
+            if (this.#overload !== undefined)
+                await this.#reconcileOverload();
         }
         finally {
             this.#eventQueueProcessing = undefined;
-            if (this.#eventQueue.length > 0) {
+            if (this.#eventQueue.size > 0) {
                 this.#eventQueueProcessing = Promise.resolve().then(() => this.#processEventQueue());
             }
         }

package/dist/integrations/pi/engine/pending-delivery.d.ts

@@ -0,0 +1,26 @@
+import type { OwnedUiEvent } from "../../../contracts/owned-ui/index.js";
+export declare const MAX_PENDING_EVENTS = 1024;
+export declare const MAX_PENDING_EVENT_BYTES: number;
+/** Actual shell semantics: only live complete block state has no independent side effect. */
+export declare function replaceableEventKey(event: OwnedUiEvent): string | null;
+/** Intrusive FIFO + segment index: replacement unlinks in O(1), never changes source ordering. */
+export declare class PendingEngineDelivery {
+    #private;
+    get size(): number;
+    diagnostics(): {
+        pending: number;
+        bytes: number;
+        protected: number;
+        superseded: number;
+        peakNodes: number;
+        peakBytes: number;
+    };
+    /** False means not admitted. The caller must enter its reserved recovery protocol, never evict. */
+    push(event: OwnedUiEvent, generation: number, reconcile?: () => OwnedUiEvent): boolean;
+    /** Session replacement invalidates old view state without resolving its lazy block references. */
+    discardObsolete(generation: number): number;
+    shift(): {
+        event: OwnedUiEvent;
+        generation: number;
+    } | undefined;
+}

package/dist/integrations/pi/engine/pending-delivery.js

@@ -0,0 +1,149 @@
+export const MAX_PENDING_EVENTS = 1024;
+export const MAX_PENDING_EVENT_BYTES = 8 * 1024 * 1024;
+/** Actual shell semantics: only live complete block state has no independent side effect. */
+export function replaceableEventKey(event) {
+    switch (event.type) {
+        case "transcript-block": return event.block.status === "live" && !(typeof event.block.payload === "object" && event.block.payload !== null && "isError" in event.block.payload && event.block.payload.isError === true) ? event.block.id : null;
+        case "session-view": // Invariant: may clear compaction work, replace editor/session state, or preempt presentation.
+        case "status": // Invariant: retry/compaction transitions invalidate suggestion work.
+        case "editor-state":
+        case "terminal-surface":
+        case "session-lifecycle":
+        case "agent-run-started":
+        case "agent-run-settled":
+        case "assistant-message-completed":
+        case "command-outcome":
+        case "diagnostic":
+        case "dialog":
+        case "overlay":
+        case "customization": return null;
+        default: {
+            const exhaustive = event;
+            return exhaustive;
+        }
+    }
+}
+/** Intrusive FIFO + segment index: replacement unlinks in O(1), never changes source ordering. */
+export class PendingEngineDelivery {
+    #replaceable = new Map();
+    #head;
+    #tail;
+    #size = 0;
+    #bytes = 0;
+    #protected = 0;
+    #generation = -1;
+    #superseded = 0;
+    #peakNodes = 0;
+    #peakBytes = 0;
+    get size() { return this.#size; }
+    diagnostics() {
+        return { pending: this.#size, bytes: this.#bytes, protected: this.#protected,
+            superseded: this.#superseded, peakNodes: this.#peakNodes, peakBytes: this.#peakBytes };
+    }
+    /** False means not admitted. The caller must enter its reserved recovery protocol, never evict. */
+    push(event, generation, reconcile) {
+        const key = replaceableEventKey(event);
+        if (generation !== this.#generation || key === null) {
+            if (!this.#seal())
+                return false;
+            this.#generation = generation;
+        }
+        const prior = key === null ? undefined : this.#replaceable.get(key);
+        let bytes = retainedEventBytes(event);
+        const marker = key !== null && bytes > 64 * 1024 && reconcile !== undefined;
+        if (marker)
+            bytes = 128;
+        if (this.#size - (prior === undefined ? 0 : 1) >= MAX_PENDING_EVENTS
+            || this.#bytes - (prior?.bytes ?? 0) + bytes > MAX_PENDING_EVENT_BYTES)
+            return false;
+        if (prior !== undefined) {
+            this.#unlink(prior);
+            this.#superseded = Math.min(Number.MAX_SAFE_INTEGER, this.#superseded + 1);
+        }
+        const node = { key, generation, bytes, ...(marker ? { resolve: reconcile } : { event }) };
+        node.previous = this.#tail;
+        if (this.#tail !== undefined)
+            this.#tail.next = node;
+        else
+            this.#head = node;
+        this.#tail = node;
+        this.#size++;
+        this.#bytes += bytes;
+        if (key === null)
+            this.#protected++;
+        else
+            this.#replaceable.set(key, node);
+        this.#peakNodes = Math.max(this.#peakNodes, this.#size);
+        this.#peakBytes = Math.max(this.#peakBytes, this.#bytes);
+        return true;
+    }
+    /** Session replacement invalidates old view state without resolving its lazy block references. */
+    discardObsolete(generation) {
+        let discarded = 0;
+        let node = this.#head;
+        while (node !== undefined) {
+            const next = node.next;
+            if (node.generation !== generation && node.event?.type !== "command-outcome") {
+                this.#unlink(node);
+                discarded++;
+            }
+            node = next;
+        }
+        this.#replaceable.clear();
+        this.#generation = generation;
+        return discarded;
+    }
+    shift() {
+        const node = this.#head;
+        if (node === undefined)
+            return undefined;
+        const event = node.event ?? node.resolve();
+        this.#unlink(node);
+        return { event, generation: node.generation };
+    }
+    // Invariant: a barrier freezes lazy authoritative markers before a later segment can change them.
+    #seal() {
+        for (const node of this.#replaceable.values()) {
+            if (node.resolve === undefined)
+                continue;
+            const event = node.resolve();
+            const bytes = retainedEventBytes(event);
+            if (this.#bytes - node.bytes + bytes > MAX_PENDING_EVENT_BYTES)
+                return false;
+            this.#bytes += bytes - node.bytes;
+            node.bytes = bytes;
+            node.event = event;
+            node.resolve = undefined;
+            this.#peakBytes = Math.max(this.#peakBytes, this.#bytes);
+        }
+        this.#replaceable.clear();
+        return true;
+    }
+    #unlink(node) {
+        if (node.previous !== undefined)
+            node.previous.next = node.next;
+        else
+            this.#head = node.next;
+        if (node.next !== undefined)
+            node.next.previous = node.previous;
+        else
+            this.#tail = node.previous;
+        this.#size--;
+        this.#bytes -= node.bytes;
+        if (node.key === null)
+            this.#protected--;
+        else if (this.#replaceable.get(node.key) === node)
+            this.#replaceable.delete(node.key);
+    }
+}
+/** Conservative UTF-16 payload bound. String length is O(1); never encode accumulated text per chunk. */
+function retainedEventBytes(value) {
+    if (typeof value === "string")
+        return 16 + value.length * 2;
+    if (value === null || typeof value !== "object")
+        return 8;
+    let bytes = 32;
+    for (const [key, item] of Object.entries(value))
+        bytes += 16 + key.length * 2 + retainedEventBytes(item);
+    return bytes;
+}