tmux-ide 2.9.10 → 2.9.12

package/packages/daemon/src/terminal/session-runtime/registry.ts

@@ -30,6 +30,7 @@ import {
   type CanonicalTerminalReplicaUpdate,
   type CausalCellFailureReasonV1,
   type CausalCellProbeV1,
+  type PaneStreamInputLifetime,
   type TerminalDeliveryAck,
   type TerminalDeliveryNack,
   type TerminalDeliveryOffer,
@@ -244,6 +245,7 @@ export interface SessionRuntimeConsumer {
     performanceTraceId?: string,
     causalProbe?: CausalCellProbeV1,
     onCausalResult?: (result: CausalCellLedgerResult) => void,
+    expectedLifetime?: PaneStreamInputLifetime,
   ): void;
   failCausalCellProbe(
     semanticPaneId: string,
@@ -896,13 +898,16 @@ export class SessionRuntimeRegistry implements PaneStreamMirror {
     return result;
   }
 
-  async describeSessionAuthority(session: string): Promise<{
+  async describeSessionAuthority(
+    session: string,
+    expectedSemanticPaneIds?: readonly string[],
+  ): Promise<{
     readonly description: MirrorSessionDescription;
     readonly runtimeSessionId: string;
   }> {
     const runtime = this.#runtime(session);
     await runtime.whenReady();
-    const authority = await this.#mirror.describeSessionAuthority(session);
+    const authority = await this.#mirror.describeSessionAuthority(session, expectedSemanticPaneIds);
     if (this.#disposed || this.#sessions.get(session) !== runtime) {
       const error = new Error(`session runtime ${session} changed topology`);
       error.name = "MirrorTopologyChangedError";
@@ -1589,6 +1594,7 @@ class SessionRuntime {
     performanceTraceId?: string,
     rawCausalProbe?: CausalCellProbeV1,
     onCausalResult?: (result: CausalCellLedgerResult) => void,
+    expectedLifetime?: PaneStreamInputLifetime,
   ): void {
     this.assertController(lease, clientId);
     const inputLease = this.#authority.leaseFor(clientId, "input");
@@ -1626,7 +1632,10 @@ class SessionRuntime {
           })
         : null;
     const started = this.#observability.enabled ? this.#observability.nowMicros() : 0;
-    const replicaOwner = this.#terminalReplicaOwner(semanticPaneId);
+    const replicaOwner = expectedLifetime
+      ? this.#terminalReplicas.get(semanticPaneId)
+      : this.#terminalReplicaOwner(semanticPaneId);
+    if (!replicaOwner) throw new Error("Input target lifetime unavailable");
     if (causalProbe) {
       this.#activeCausalCellProbes += 1;
       let settled = false;
@@ -1649,6 +1658,15 @@ class SessionRuntime {
       this.#outputTraces.arm(semanticPaneId, trace);
     }
     try {
+      // Synchronous final admission: never create a new owner to satisfy a stale
+      // held-input fence, and never await between this check and mirror dispatch.
+      if (
+        expectedLifetime &&
+        (expectedLifetime.generation !== this.generation ||
+          this.#terminalReplicas.get(semanticPaneId) !== replicaOwner ||
+          replicaOwner.inputAdmissionIncarnation() !== expectedLifetime.incarnation)
+      )
+        throw new Error("Input target lifetime changed");
       if (input.kind === "text")
         this.#mirror.sendText(
           this.session,
@@ -2323,6 +2341,7 @@ class SessionRuntimeConsumerImpl implements SessionRuntimeConsumer {
     performanceTraceId?: string,
     causalProbe?: CausalCellProbeV1,
     onCausalResult?: (result: CausalCellLedgerResult) => void,
+    expectedLifetime?: PaneStreamInputLifetime,
   ): void {
     this.#assertOpen();
     this.#runtime.sendInput(
@@ -2333,6 +2352,7 @@ class SessionRuntimeConsumerImpl implements SessionRuntimeConsumer {
       performanceTraceId,
       causalProbe,
       onCausalResult,
+      expectedLifetime,
     );
   }
 
@@ -2452,6 +2472,8 @@ class SessionRuntimeConsumerImpl implements SessionRuntimeConsumer {
       negotiation: upstream.negotiation,
       closed: upstream.closed,
       ack: (ack: TerminalDeliveryAck) => upstream.ack(ack),
+      ...(upstream.projectionReceipt ? { projectionReceipt: upstream.projectionReceipt } : {}),
+      ...(upstream.materialize ? { materialize: upstream.materialize } : {}),
       nack: (nack: TerminalDeliveryNack) => upstream.nack(nack),
       setVisibility: (visibility: TerminalDeliveryVisibility) => upstream.setVisibility(visibility),
       close: async () => {

package/packages/daemon/src/terminal/session-runtime/runtime-observability.ts

@@ -81,7 +81,7 @@ export interface SessionRuntimeStageSpan {
     readonly attemptedLegacySeedSizeCapped?: boolean;
     readonly attemptedCompactPatchBytes?: number | null;
     readonly attemptedCompactSeedBytes?: number | null;
-    readonly selectedEncoding?: "semantic-v1" | "semantic-compact-v1";
+    readonly selectedEncoding?: "semantic-v1" | "semantic-compact-v1" | "semantic-binary-v1";
     readonly selectionStatus?:
       | "patch-preferred"
       | "seed-preferred"

package/packages/daemon/src/terminal/session-runtime/terminal-delivery-hub.ts

@@ -1,3 +1,15 @@
+import { prepareProjection, type ProjectionBaseline } from "./terminal-projection-delivery.ts";
+import {
+  TerminalProjectionEnvelopeSchemaZ,
+  TerminalProjectionReceiptSchemaZ,
+  TerminalProjectionMaterializeSchemaZ,
+  type TerminalProjectionEnvelope,
+  type TerminalProjectionReceipt,
+  type TerminalProjectionMaterialize,
+  type TerminalProjectionPayload,
+} from "@tmux-ide/contracts";
+import { encodeTerminalProjectionCooperatively } from "@tmux-ide/core";
+type DeliveryEnvelope = TerminalDeliveryEnvelope | TerminalProjectionEnvelope;
 import type { KittyImage } from "../graphics/kitty-graphics.ts";
 import { StockCaptureTabUnavailableError } from "./stock-capture-fidelity.ts";
 import {
@@ -37,6 +49,8 @@ import {
   applyTerminalReplicaUpdate,
   applyTerminalReplicaUpdateCooperatively,
   terminalReplicaUpdateNeedsCooperativeReduction,
+  encodeBinarySemanticTerminalUpdate,
+  encodeBinarySemanticTerminalUpdateCooperatively,
   encodeCompactSemanticTerminalUpdate,
   encodeCompactSemanticTerminalUpdateCooperatively,
   terminalSemanticUpdateNeedsCooperativeEncoding,
@@ -124,6 +138,8 @@ export interface TerminalDeliveryConnection {
   readonly closed: Promise<"closed" | "sink-failed">;
   readonly negotiation: TerminalDeliveryNegotiationResult;
   ack(ack: TerminalDeliveryAck): void;
+  projectionReceipt?(receipt: TerminalProjectionReceipt): void;
+  materialize?(request: TerminalProjectionMaterialize): void;
   nack(nack: TerminalDeliveryNack): void;
   setVisibility(visibility: TerminalDeliveryVisibility): void;
   close(): Promise<void>;
@@ -205,9 +221,14 @@ interface ClientState {
   visibility: TerminalDeliveryVisibility;
   baselineRevision: number;
   baselineHash: string | null;
+  projectionBaseline: ProjectionBaseline | null;
+  materializeRequested: boolean;
+  lastProjectionReceipt: TerminalProjectionReceipt | null;
+  lastMaterialize: TerminalProjectionMaterialize | null;
   reseedRequired: boolean;
   inFlight: {
-    envelope: TerminalDeliveryEnvelope;
+    envelope: DeliveryEnvelope;
+    projection: ProjectionBaseline | null;
     deliveryOrdinal: number;
     bytes: Uint8Array;
     nextChunk: number;
@@ -226,7 +247,7 @@ interface ClientState {
   captureUnavailable: boolean;
   lastAck: TerminalDeliveryAck | null;
   /** Delivery displaced by authoritative source close; its racing ACK is benign. */
-  sourceClosedFlight: TerminalDeliveryEnvelope | null;
+  sourceClosedFlight: DeliveryEnvelope | null;
   backgroundTimer: SessionRuntimeTimer | null;
 }
 
@@ -246,6 +267,11 @@ interface PendingClientEncoding {
   readonly reseedRequired: boolean;
   readonly traceStarted: number;
 }
+class DeferredProjectionEncoding extends Error {
+  constructor(readonly payload: TerminalProjectionPayload) {
+    super("Deferred projection encoding");
+  }
+}
 class DeferredSeedEncoding extends Error {
   constructor(readonly payload: TerminalSemanticDeliveryPayload) {
     super("Deferred compact seed encoding");
@@ -254,10 +280,16 @@ class DeferredSeedEncoding extends Error {
 
 interface CachedRepresentation {
   readonly bytes: Uint8Array;
-  readonly encoding?: "semantic-v1" | "semantic-compact-v1";
+  readonly encoding?:
+    | "semantic-v1"
+    | "semantic-compact-v1"
+    | "semantic-binary-v1"
+    | "alternate-projection-binary-v1";
+  readonly projection?: ProjectionBaseline;
+  readonly projectionBaseRevision?: number | null;
   readonly frame: "seed" | "patch" | "tombstone";
   readonly canonicalEquivalent: boolean;
-  readonly history: "complete" | "truncated" | "not-applicable";
+  readonly history: "complete" | "truncated" | "not-applicable" | "deferred";
   readonly representationHash?: string;
   /** Internal reachability metadata; never serialized onto the wire. */
   readonly cachePaneId?: string;
@@ -274,7 +306,7 @@ interface CachedRepresentation {
     attemptedLegacySeedSizeCapped: boolean;
     attemptedCompactPatchBytes: number | null;
     attemptedCompactSeedBytes: number | null;
-    selectedEncoding: "semantic-v1" | "semantic-compact-v1";
+    selectedEncoding: "semantic-v1" | "semantic-compact-v1" | "semantic-binary-v1";
     selectionStatus:
       | "patch-preferred"
       | "seed-preferred"
@@ -432,6 +464,10 @@ export class SessionRuntimeTerminalDeliveryHub {
         visibility: "visible",
         baselineRevision: -1,
         baselineHash: null,
+        projectionBaseline: null,
+        materializeRequested: false,
+        lastProjectionReceipt: null,
+        lastMaterialize: null,
         reseedRequired: false,
         inFlight: null,
         latestRevision: pane.latest?.update.revision ?? null,
@@ -456,6 +492,8 @@ export class SessionRuntimeTerminalDeliveryHub {
         negotiation,
         closed,
         ack: (ack) => this.#ack(client, ack),
+        projectionReceipt: (receipt) => this.#projectionReceipt(client, receipt),
+        materialize: (request) => this.#materialize(client, request),
         nack: (nack) => this.#nack(client, nack),
         setVisibility: (visibilityInput) => {
           if (client.closed) return;
@@ -956,7 +994,10 @@ export class SessionRuntimeTerminalDeliveryHub {
         client.lifecycleOpenRecorded = this.#recordDeliveryLifecycle(client, pane, "open");
       if (
         update.type === "terminal.tombstone" &&
-        (client.inFlight !== null || client.encoding !== null || client.visibility !== "visible")
+        (client.inFlight !== null ||
+          client.encoding !== null ||
+          client.visibility !== "visible" ||
+          client.projectionBaseline !== null)
       ) {
         this.#fault(client, "source-closed", "Terminal source closed before final state delivery");
         continue;
@@ -1079,15 +1120,22 @@ export class SessionRuntimeTerminalDeliveryHub {
     let deferred = false;
     let encodedRepresentation: CachedRepresentation | null = null;
     let failedSelectionObservation: SemanticSelectionObservation | null = null;
-    let deliveryEnvelope: TerminalDeliveryEnvelope | null = null;
+    let deliveryEnvelope: DeliveryEnvelope | null = null;
     let deliveryOrdinal: number | null = null;
     try {
       const representation = this.#representation(client, pane, target, completed?.outcome);
       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",
+      const envelope = (
+        representation.projection
+          ? TerminalProjectionEnvelopeSchemaZ
+          : TerminalDeliveryEnvelopeSchemaZ
+      ).parse({
+        type: representation.projection ? "terminal.projection" : "terminal.delivery",
+        ...(representation.projection
+          ? { projectionStateHash: representation.projection.hash }
+          : {}),
         workspaceName: client.deliveryWorkspaceName,
         semanticPaneId: target.update.semanticPaneId,
         generation: target.update.generation,
@@ -1098,7 +1146,11 @@ export class SessionRuntimeTerminalDeliveryHub {
         protocolVersion: 1,
         encoding: representation.encoding ?? client.negotiated.encoding,
         frame: representation.frame,
-        baseRevision: representation.frame === "seed" ? null : Math.max(0, client.baselineRevision),
+        baseRevision: representation.projection
+          ? representation.projectionBaseRevision
+          : representation.frame === "seed"
+            ? null
+            : Math.max(0, client.baselineRevision),
         canonicalRevision: target.update.revision,
         canonicalStateHash: target.update.stateHash,
         representationHash:
@@ -1115,6 +1167,7 @@ export class SessionRuntimeTerminalDeliveryHub {
       registerTerminalDeliveryObservationOrdinal(envelope, deliveryOrdinal);
       client.inFlight = {
         envelope,
+        projection: representation.projection ?? null,
         deliveryOrdinal,
         bytes: representation.bytes,
         nextChunk: 0,
@@ -1125,9 +1178,16 @@ export class SessionRuntimeTerminalDeliveryHub {
       if (target.trace?.traceId === pane.pendingDeliveryTrace?.traceId)
         pane.pendingDeliveryTrace = null;
     } catch (error) {
-      if (error instanceof DeferredSeedEncoding) {
+      if (error instanceof DeferredSeedEncoding || error instanceof DeferredProjectionEncoding) {
         deferred = true;
-        this.#startEncoding(client, pane, target, error.payload, traceStarted);
+        this.#startEncoding(
+          client,
+          pane,
+          target,
+          error.payload,
+          traceStarted,
+          error instanceof DeferredProjectionEncoding,
+        );
         return;
       }
       failedSelectionObservation = semanticSelectionObservationFromError(error);
@@ -1205,8 +1265,9 @@ export class SessionRuntimeTerminalDeliveryHub {
     client: ClientState,
     pane: PaneState,
     target: RevisionRecord,
-    payload: TerminalSemanticDeliveryPayload,
+    payload: TerminalSemanticDeliveryPayload | TerminalProjectionPayload,
     traceStarted: number,
+    projection = false,
   ): void {
     const key = cacheKey([
       target.update.workspaceName,
@@ -1217,6 +1278,9 @@ export class SessionRuntimeTerminalDeliveryHub {
       target.update.stateHash,
       client.negotiated.encoding,
       client.negotiated.richPlacements ? "rich" : "plain",
+      projection
+        ? `projection:${client.projectionBaseline?.revision ?? -1}:${client.projectionBaseline?.hash ?? "none"}`
+        : "complete",
     ]);
     let job = this.#pendingEncodings.get(key);
     let created = false;
@@ -1250,10 +1314,19 @@ export class SessionRuntimeTerminalDeliveryHub {
     };
     owned.clients.add(client);
     if (!created) return;
-    void encodeCompactSemanticTerminalUpdateCooperatively(payload, {
-      signal: owned.abort.signal,
-      yieldControl: () => this.#yieldEncoding(owned),
-    }).then(
+    const options = { signal: owned.abort.signal, yieldControl: () => this.#yieldEncoding(owned) };
+    const result = projection
+      ? encodeTerminalProjectionCooperatively(payload as TerminalProjectionPayload, options)
+      : client.negotiated.encoding === "semantic-binary-v1"
+        ? encodeBinarySemanticTerminalUpdateCooperatively(
+            payload as TerminalSemanticDeliveryPayload,
+            options,
+          )
+        : encodeCompactSemanticTerminalUpdateCooperatively(
+            payload as TerminalSemanticDeliveryPayload,
+            options,
+          );
+    void result.then(
       (bytes) => this.#completeEncoding(owned, { bytes }),
       (error) => this.#completeEncoding(owned, { error }),
     );
@@ -1328,6 +1401,32 @@ export class SessionRuntimeTerminalDeliveryHub {
     target: RevisionRecord,
     seedOutcome?: SeedEncodingOutcome,
   ): CachedRepresentation {
+    const snapshotForProjection = target.state.snapshot;
+    if (
+      client.negotiated.alternateScreenProjection &&
+      !client.materializeRequested &&
+      (client.baselineRevision < 0 || client.projectionBaseline !== null) &&
+      snapshotForProjection?.modes.alternateScreen &&
+      snapshotForProjection.history.length > 0
+    ) {
+      const { payload, retained } = prepareProjection(
+        snapshotForProjection,
+        target.update.revision,
+        target.update.incarnation,
+        client.reseedRequired ? null : client.projectionBaseline,
+      );
+      if (!seedOutcome) throw new DeferredProjectionEncoding(payload);
+      if ("error" in seedOutcome) throw seedOutcome.error;
+      return {
+        bytes: seedOutcome.bytes,
+        encoding: "alternate-projection-binary-v1",
+        frame: payload.frame,
+        history: "deferred",
+        canonicalEquivalent: false,
+        projection: retained,
+        projectionBaseRevision: payload.frame === "seed" ? null : payload.baseRevision,
+      };
+    }
     const key = cacheKey([
       target.update.workspaceName,
       target.update.semanticPaneId,
@@ -1351,17 +1450,27 @@ export class SessionRuntimeTerminalDeliveryHub {
     let result: CachedRepresentation | null = null;
     if (
       client.negotiated.encoding === "semantic-v1" ||
-      client.negotiated.encoding === "semantic-compact-v1"
+      client.negotiated.encoding === "semantic-compact-v1" ||
+      client.negotiated.encoding === "semantic-binary-v1"
     ) {
       const encodeSemantic = (payload: TerminalSemanticDeliveryPayload): Uint8Array => {
-        if (client.negotiated.encoding !== "semantic-compact-v1")
+        if (
+          client.negotiated.encoding !== "semantic-compact-v1" &&
+          client.negotiated.encoding !== "semantic-binary-v1"
+        )
           return encodeSemanticTerminalUpdate(payload);
-        if (terminalSemanticUpdateNeedsCooperativeEncoding(payload)) {
+        if (
+          payload.frame === "seed" &&
+          (client.negotiated.encoding === "semantic-binary-v1" ||
+            terminalSemanticUpdateNeedsCooperativeEncoding(payload))
+        ) {
           if (!seedOutcome) throw new DeferredSeedEncoding(payload);
           if ("error" in seedOutcome) throw seedOutcome.error;
           return seedOutcome.bytes;
         }
-        return encodeCompactSemanticTerminalUpdate(payload);
+        return client.negotiated.encoding === "semantic-binary-v1"
+          ? encodeBinarySemanticTerminalUpdate(payload)
+          : encodeCompactSemanticTerminalUpdate(payload);
       };
       if (client.reseedRequired) {
         const payload = semanticSeed(target);
@@ -1693,6 +1802,10 @@ export class SessionRuntimeTerminalDeliveryHub {
       return;
     }
     const envelope = flight.envelope;
+    if (envelope.type !== "terminal.delivery") {
+      this.#fault(client, "protocol-violation", "Canonical ACK cannot acknowledge a projection");
+      return;
+    }
     if (
       flight.nextChunk !== envelope.chunkCount ||
       ack.workspaceName !== envelope.workspaceName ||
@@ -1712,6 +1825,8 @@ export class SessionRuntimeTerminalDeliveryHub {
       this.#maxSlowClientMs,
       this.#scheduler.nowMs() - flight.sentAt,
     );
+    client.projectionBaseline = null;
+    client.lastProjectionReceipt = null;
     client.baselineRevision = ack.canonicalRevision;
     client.baselineHash = ack.canonicalStateHash;
     client.reseedRequired = false;
@@ -1769,6 +1884,85 @@ export class SessionRuntimeTerminalDeliveryHub {
     this.#recordDeliveryStatus(client, this.#panes.get(client.paneId));
   }
 
+  #projectionReceipt(client: ClientState, input: TerminalProjectionReceipt): void {
+    const receipt = TerminalProjectionReceiptSchemaZ.parse(input);
+    if (
+      client.lastProjectionReceipt &&
+      JSON.stringify(client.lastProjectionReceipt) === JSON.stringify(receipt)
+    )
+      return;
+    const flight = client.inFlight;
+    const envelope = flight?.envelope;
+    if (
+      !flight ||
+      !flight.projection ||
+      envelope?.type !== "terminal.projection" ||
+      flight.nextChunk !== envelope.chunkCount ||
+      receipt.workspaceName !== envelope.workspaceName ||
+      receipt.semanticPaneId !== envelope.semanticPaneId ||
+      receipt.generation !== envelope.generation ||
+      receipt.incarnation !== envelope.incarnation ||
+      receipt.deliveryNonce !== envelope.deliveryNonce ||
+      receipt.transactionId !== envelope.transactionId ||
+      receipt.canonicalRevision !== envelope.canonicalRevision ||
+      receipt.canonicalStateHash !== envelope.canonicalStateHash ||
+      receipt.projectionStateHash !== envelope.projectionStateHash ||
+      receipt.representationHash !== envelope.representationHash
+    ) {
+      this.#fault(
+        client,
+        "protocol-violation",
+        "Projection receipt does not identify the in-flight projection",
+      );
+      return;
+    }
+    client.projectionBaseline = flight.projection;
+    client.lastProjectionReceipt = receipt;
+    client.reseedRequired = false;
+    client.inFlight = null;
+    if (client.latestRevision === receipt.canonicalRevision) client.latestRevision = null;
+    if (client.materializeRequested)
+      client.latestRevision = this.#panes.get(client.paneId)?.latest?.update.revision ?? null;
+    this.#pruneCanonicalRevisions(client.paneId);
+    this.#schedule(client);
+    this.#recordDeliveryStatus(client, this.#panes.get(client.paneId));
+  }
+
+  #materialize(client: ClientState, input: TerminalProjectionMaterialize): void {
+    const request = TerminalProjectionMaterializeSchemaZ.parse(input);
+    if (
+      client.lastMaterialize &&
+      JSON.stringify(client.lastMaterialize) === JSON.stringify(request)
+    )
+      return;
+    const baseline = client.projectionBaseline;
+    if (
+      !client.negotiated.alternateScreenProjection ||
+      !baseline ||
+      request.workspaceName !== client.deliveryWorkspaceName ||
+      request.semanticPaneId !== client.paneId ||
+      request.generation !== client.negotiated.generation ||
+      request.incarnation !== baseline.incarnation ||
+      request.deliveryNonce !== client.negotiated.deliveryNonce ||
+      request.canonicalRevision !== baseline.revision ||
+      request.projectionStateHash !== baseline.hash
+    ) {
+      this.#fault(
+        client,
+        "protocol-violation",
+        "History request does not identify the retained projection",
+      );
+      return;
+    }
+    client.lastMaterialize = request;
+    client.materializeRequested = true;
+    this.#cancelEncoding(client);
+    client.latestRevision = this.#panes.get(client.paneId)?.latest?.update.revision ?? null;
+    // A queued projection still owns its transaction until its receipt arrives.
+    // The following complete seed then supersedes it, including at the same revision.
+    this.#schedule(client);
+  }
+
   #nack(client: ClientState, input: TerminalDeliveryNack): void {
     const nack = TerminalDeliveryNackSchemaZ.parse(input);
     const closed = client.sourceClosedFlight;
@@ -2224,7 +2418,7 @@ export function selectExactSemanticRepresentation<T extends { readonly frame: st
 
 function completeSemanticSelectionObservation(
   observation: ExactSemanticSelectionObservation,
-  selectedEncoding: "semantic-v1" | "semantic-compact-v1",
+  selectedEncoding: "semantic-v1" | "semantic-compact-v1" | "semantic-binary-v1",
   legacyAttempts: Readonly<{ patchBytes: number | null; seedBytes: number | null }> | null,
 ): SemanticSelectionObservation {
   const compact = selectedEncoding === "semantic-compact-v1";

package/packages/daemon/src/terminal/session-runtime/terminal-delivery-observation-identity.ts

@@ -1,9 +1,12 @@
-import type { TerminalDeliveryEnvelope } from "@tmux-ide/contracts";
+import type { TerminalDeliveryEnvelope, TerminalProjectionEnvelope } from "@tmux-ide/contracts";
 
-const deliveryOrdinals = new WeakMap<TerminalDeliveryEnvelope, number>();
+const deliveryOrdinals = new WeakMap<
+  TerminalDeliveryEnvelope | TerminalProjectionEnvelope,
+  number
+>();
 
 export function registerTerminalDeliveryObservationOrdinal(
-  envelope: TerminalDeliveryEnvelope,
+  envelope: TerminalDeliveryEnvelope | TerminalProjectionEnvelope,
   ordinal: number,
 ): void {
   if (!Number.isSafeInteger(ordinal) || ordinal < 1)
@@ -12,7 +15,7 @@ export function registerTerminalDeliveryObservationOrdinal(
 }
 
 export function terminalDeliveryObservationOrdinal(
-  envelope: TerminalDeliveryEnvelope,
+  envelope: TerminalDeliveryEnvelope | TerminalProjectionEnvelope,
 ): number | null {
   return deliveryOrdinals.get(envelope) ?? null;
 }

package/packages/daemon/src/terminal/session-runtime/terminal-projection-delivery.ts

@@ -0,0 +1,59 @@
+import type {
+  TerminalProjectionPayload,
+  TerminalProjectionSnapshot,
+  TerminalReplicaSnapshot,
+} from "@tmux-ide/contracts";
+import {
+  hashTerminalProjection,
+  projectAlternateSnapshot,
+  terminalReplicaRowsEqual,
+} from "@tmux-ide/core";
+
+/** A projection receipt never becomes a complete canonical baseline. */
+export interface ProjectionBaseline {
+  readonly revision: number;
+  readonly incarnation: string;
+  readonly hash: string;
+  readonly snapshot: TerminalProjectionSnapshot;
+}
+
+export function prepareProjection(
+  snapshot: TerminalReplicaSnapshot,
+  revision: number,
+  incarnation: string,
+  baseline: ProjectionBaseline | null,
+): { payload: TerminalProjectionPayload; retained: ProjectionBaseline } {
+  const projected = projectAlternateSnapshot(snapshot);
+  const retained = {
+    revision,
+    incarnation,
+    hash: hashTerminalProjection(projected),
+    snapshot: projected,
+  };
+  if (
+    !baseline ||
+    baseline.incarnation !== incarnation ||
+    baseline.snapshot.cols !== projected.cols ||
+    baseline.snapshot.rows !== projected.rows
+  )
+    return { payload: { frame: "seed", revision, projection: projected }, retained };
+  const rows = projected.grid.flatMap((row, index) =>
+    terminalReplicaRowsEqual(row, baseline.snapshot.grid[index]!) ? [] : [{ index, row }],
+  );
+  return {
+    retained,
+    payload: {
+      frame: "patch",
+      baseRevision: baseline.revision,
+      revision,
+      patch: {
+        rows,
+        deferredHistory: projected.deferredHistory,
+        cursor: projected.cursor,
+        modes: projected.modes,
+        placements: projected.placements,
+        bootstrap: projected.bootstrap,
+      },
+    },
+  };
+}