@opengeni/sdk 0.52.1 → 1.0.0

package/src/editable-artifacts/controller.ts

@@ -2,16 +2,24 @@ import {
   decodeEditableArtifactMutationIntent,
   EDITABLE_ARTIFACT_COMMAND_MAX_BYTES,
   EDITABLE_ARTIFACT_INTENT_MAX_BYTES,
+  EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION,
   EDITABLE_ARTIFACT_PRODUCT_MAX_SNAPSHOT_BYTES,
   hashEditableArtifactMutationIntentBytes,
 } from "@opengeni/contracts/editable-artifacts";
 import {
+  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
   decodeCommittedTransactionSummary,
   MAX_COMMITTED_TRANSACTION_BYTES,
 } from "@opengeni/contracts/editable-artifact-committed-transaction";
 import { editableArtifactCodecFor } from "@opengeni/contracts/editable-artifact-codec-registry";
+import { EDITABLE_ARTIFACT_LIVE_WIRE_VERSION } from "@opengeni/contracts/editable-artifact-live";
 import { decodeEditableArtifactSerializedCommit } from "@opengeni/contracts/editable-artifact-serialized-commit";
+import { SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION } from "@opengeni/contracts/editable-artifact-versions";
 import { EditableArtifactSyncError } from "./errors";
+import {
+  classifyEditableArtifactOpenFailure,
+  type EditableArtifactOpenFailureReporter,
+} from "./open-failure";
 import { EditableArtifactStorageConflictError } from "./storage";
 import type { EditableArtifactStoragePort, EditableArtifactStorageScope } from "./storage";
 import type {
@@ -42,7 +50,6 @@ import type {
   EditableArtifactWorkerKernel,
 } from "./types";
 
-const DEFAULT_PROTOCOL_VERSION = 1;
 const DEFAULT_REPLAY_PAGE_SIZE = 256;
 const DEFAULT_MAX_QUEUE_MESSAGES = 512;
 const DEFAULT_MAX_QUEUE_BYTES = 8 * 1024 * 1024;
@@ -70,7 +77,7 @@ export type CreateEditableArtifactSyncControllerOptions = {
   kernelVersion: string;
   modelSchemaVersion: number;
   commandVersion: number;
-  protocolVersion?: number;
+  protocolVersion: number;
   replayPageSize?: number;
   maxQueuedMessages?: number;
   maxQueuedBytes?: number;
@@ -87,6 +94,8 @@ export type CreateEditableArtifactSyncControllerOptions = {
   maxReconnectAttempts?: number;
   scheduler?: EditableArtifactSyncScheduler;
   clientTransactionIdFactory?: () => string;
+  /** Receives bounded categories/codes only; never workbook or formula content. */
+  onOpenFailure?: EditableArtifactOpenFailureReporter;
   /** Tests/embedded runtimes may inject; defaults to a fresh per-controller UUID. */
   writerReplicaIdFactory?: () => string;
 };
@@ -186,6 +195,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
   private readonly maxReconnectAttempts: number;
   private readonly scheduler: EditableArtifactSyncScheduler;
   private readonly clientTransactionIdFactory: () => string;
+  private readonly onOpenFailure: EditableArtifactOpenFailureReporter | undefined;
 
   private readonly abortController = new AbortController();
   private readonly listeners = new Set<EditableArtifactSyncListener>();
@@ -258,10 +268,10 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     );
     this.modelSchemaVersion = positiveSafeInteger(options.modelSchemaVersion, "modelSchemaVersion");
     this.commandVersion = positiveSafeInteger(options.commandVersion, "commandVersion");
-    this.protocolVersion = positiveSafeInteger(
-      options.protocolVersion ?? DEFAULT_PROTOCOL_VERSION,
-      "protocolVersion",
-    );
+    this.protocolVersion = positiveSafeInteger(options.protocolVersion, "protocolVersion");
+    if (this.protocolVersion !== EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION) {
+      throw new TypeError("protocolVersion is incompatible with the current intent protocol");
+    }
     this.replayPageSize = positiveSafeInteger(
       options.replayPageSize ?? DEFAULT_REPLAY_PAGE_SIZE,
       "replayPageSize",
@@ -324,6 +334,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     this.scheduler = options.scheduler ?? defaultScheduler;
     this.clientTransactionIdFactory =
       options.clientTransactionIdFactory ?? (() => crypto.randomUUID());
+    this.onOpenFailure = options.onOpenFailure;
   }
 
   start(): void {
@@ -331,6 +342,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     this.runTask = this.run().catch((error: unknown) => {
       if (this.abortController.signal.aborted) return;
       const failure = asError(error);
+      this.reportOpenFailure(failure);
       if (failure instanceof EditableArtifactSyncError && failure.code === "unsupported_protocol") {
         this.lastError = failure;
         this.setState("unsupported");
@@ -366,6 +378,15 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
   }
 
   getView(): EditableArtifactSyncView {
+    const blockedPending = this.allBlockedPending();
+    const authoringBlockedReason =
+      this.modality !== "spreadsheet" && blockedPending.length > 0
+        ? "pending_conflict"
+        : this.orderedPending().some(
+              (transaction) => transaction.replicaId !== this.writerReplicaId,
+            )
+          ? "prior_writer"
+          : undefined;
     return {
       artifactId: this.artifactId,
       modality: this.modality,
@@ -374,7 +395,8 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       headSequence: this.headSequence,
       writable: this.writable,
       pendingTransactions: this.pending.size,
-      blockedPending: this.allBlockedPending(),
+      blockedPending,
+      authoringBlockedReason,
       queuedMessages: this.liveQueue.length,
       reconnectAttempt: this.reconnectAttempt,
       lastError: this.lastError,
@@ -664,7 +686,8 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     try {
       await this.restoreReplica(stored);
       await this.replacePendingOverlay();
-    } catch {
+    } catch (error) {
+      this.reportOpenFailure(error);
       await this.kernel.reset();
       this.replica = null;
       this.retainedTailTransactions = 0;
@@ -680,8 +703,8 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       stored.snapshot,
       this.artifactId,
       this.modality,
-      this.protocolVersion,
-      this.kernelVersion,
+      COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+      SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
       this.modelSchemaVersion,
       this.maxSnapshotBytes,
     );
@@ -701,12 +724,19 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       stored.snapshot.modality === "spreadsheet" ? stored.snapshot.causalFrontier : null;
     let nativeRevision =
       stored.snapshot.modality === "spreadsheet" ? null : stored.snapshot.nativeRevision;
+    const retainedAcceptances: {
+      transaction: EditableArtifactCommittedTransaction;
+      pending: Pick<
+        EditableArtifactPendingTransaction,
+        "clientTransactionId" | "requestHash" | "intentBytes"
+      >;
+    }[] = [];
     for (const transaction of stored.tail) {
-      validateCommittedTransaction(
+      const embeddedPending = validateCommittedTransaction(
         transaction,
         this.artifactId,
         this.modality,
-        this.protocolVersion,
+        COMMITTED_TRANSACTION_PROTOCOL_VERSION,
         this.maxCommittedTransactionBytes,
       );
       if (transaction.startSequence !== cursor + 1) {
@@ -715,6 +745,15 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       requireStateHash(transaction.priorStateHash, stateHash, "retained transaction prior state");
       const applied = await this.kernel.applyRecovered(transaction);
       requireStateHash(applied.stateHash, transaction.stateHash, "retained transaction");
+      if (embeddedPending) {
+        const pending = this.pending.get(embeddedPending.clientTransactionId);
+        if (
+          pending?.requestHash === embeddedPending.requestHash &&
+          bytesEqual(pending.intentBytes, embeddedPending.intentBytes)
+        ) {
+          retainedAcceptances.push({ transaction, pending: embeddedPending });
+        }
+      }
       cursor = transaction.endSequence;
       stateHash = transaction.stateHash;
       if (transaction.modality === "spreadsheet") {
@@ -750,6 +789,14 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     this.retainedTailTransactions = stored.tail.length;
     this.cursor = cursor;
     this.headSequence = cursor;
+    // Reload may interrupt between retaining a commit and deleting its WAL entry.
+    // Only settle exact embedded identities after the entire retained head verifies;
+    // otherwise speculative replay mistakes our own committed edit for a conflict.
+    // Callers restore the pending overlay after this confirmed projection is ready.
+    for (const { transaction, pending } of retainedAcceptances) {
+      this.recordAcceptedMappingIdentity(transaction.transactionId, pending);
+      await this.settlePending(transaction, true);
+    }
   }
 
   private async run(): Promise<void> {
@@ -776,6 +823,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
           delayMs = this.reconnectDelayMs;
         }
         const failure = asError(error);
+        this.reportOpenFailure(failure);
         this.lastError = failure;
         if (failure instanceof EditableArtifactSyncError && failure.requiresSnapshot) {
           this.requireSnapshot = true;
@@ -956,14 +1004,11 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     if (bootstrap.modality !== this.modality) {
       throw invalidBootstrap("bootstrap modality does not match the controller");
     }
-    this.requireProtocol(bootstrap.protocolVersion);
-    if (
-      bootstrap.kernelVersion !== this.kernelVersion ||
-      bootstrap.modelSchemaVersion !== this.modelSchemaVersion
-    ) {
+    this.requireLiveProtocol(bootstrap.liveProtocolVersion);
+    if (bootstrap.modelSchemaVersion !== this.modelSchemaVersion) {
       throw new EditableArtifactSyncError(
         "unsupported_protocol",
-        `artifact kernel/schema ${bootstrap.kernelVersion}/${bootstrap.modelSchemaVersion} is incompatible with ${this.kernelVersion}/${this.modelSchemaVersion}`,
+        `artifact schema ${bootstrap.modelSchemaVersion} is incompatible with ${this.modelSchemaVersion}`,
       );
     }
     requireSha256(bootstrap.headStateHash, "bootstrap.headStateHash");
@@ -1035,8 +1080,8 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       snapshot,
       this.artifactId,
       this.modality,
-      this.protocolVersion,
-      this.kernelVersion,
+      COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+      SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
       this.modelSchemaVersion,
       this.maxSnapshotBytes,
     );
@@ -1136,7 +1181,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
           transaction,
           this.artifactId,
           this.modality,
-          this.protocolVersion,
+          COMMITTED_TRANSACTION_PROTOCOL_VERSION,
           this.maxCommittedTransactionBytes,
         );
         pageBytes += estimateCommittedTransactionBytes(transaction);
@@ -1167,7 +1212,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
         message,
         this.artifactId,
         this.modality,
-        this.protocolVersion,
+        COMMITTED_TRANSACTION_PROTOCOL_VERSION,
         this.maxCommittedTransactionBytes,
       );
       bytes = estimateLiveMessageBytes(message);
@@ -1271,7 +1316,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       transaction,
       this.artifactId,
       this.modality,
-      this.protocolVersion,
+      COMMITTED_TRANSACTION_PROTOCOL_VERSION,
       this.maxCommittedTransactionBytes,
     );
     if (embeddedPending) {
@@ -1568,7 +1613,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
         receipt.committed,
         this.artifactId,
         this.modality,
-        this.protocolVersion,
+        COMMITTED_TRANSACTION_PROTOCOL_VERSION,
         this.maxCommittedTransactionBytes,
       );
       this.recordAcceptedMapping(receipt);
@@ -1641,7 +1686,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
         "sync ticket is not bound to the requested writer replica",
       );
     }
-    this.requireProtocol(ticket.protocolVersion);
+    this.requireLiveProtocol(ticket.protocolVersion);
     boundedNonEmpty(ticket.token, "ticket.token", MAX_TICKET_BYTES);
     const expiresAt = Date.parse(ticket.expiresAt);
     if (!Number.isFinite(expiresAt)) {
@@ -1758,11 +1803,11 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     );
   }
 
-  private requireProtocol(actual: number): void {
-    if (actual !== this.protocolVersion) {
+  private requireLiveProtocol(actual: number): void {
+    if (actual !== EDITABLE_ARTIFACT_LIVE_WIRE_VERSION) {
       throw new EditableArtifactSyncError(
         "unsupported_protocol",
-        `artifact protocol ${actual} is incompatible with client ${this.protocolVersion}`,
+        `live protocol ${actual} is incompatible with ${EDITABLE_ARTIFACT_LIVE_WIRE_VERSION}`,
       );
     }
   }
@@ -1794,6 +1839,16 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     this.liveWaiters.clear();
   }
 
+  private reportOpenFailure(error: unknown): void {
+    const event = classifyEditableArtifactOpenFailure(error);
+    if (event === null || this.onOpenFailure === undefined) return;
+    try {
+      this.onOpenFailure(event);
+    } catch {
+      // Observability must never change recovery or availability behavior.
+    }
+  }
+
   private fail(error: Error): void {
     this.lastError = error;
     this.setState("failed");
@@ -1971,7 +2026,7 @@ function validateCommittedTransaction(
   transaction: EditableArtifactCommittedTransaction,
   artifactId: EditableArtifactId,
   modality: EditableArtifactModality,
-  protocolVersion: number,
+  operationProtocolVersion: number,
   maxCommittedTransactionBytes: number,
 ): Readonly<{
   clientTransactionId: string;
@@ -2000,10 +2055,10 @@ function validateCommittedTransaction(
     throw invalidSequence("transaction committedTransactionBytes exceeds the configured bound");
   }
   if (transaction.modality === "spreadsheet") {
-    if (transaction.protocolVersion !== protocolVersion) {
+    if (transaction.operationProtocolVersion !== operationProtocolVersion) {
       throw new EditableArtifactSyncError(
         "unsupported_protocol",
-        `transaction protocol ${transaction.protocolVersion} is incompatible with client ${protocolVersion}`,
+        `transaction operation protocol ${transaction.operationProtocolVersion} is incompatible with ${operationProtocolVersion}`,
       );
     }
     validateFrontier(transaction.causalFrontier, "causalFrontier");
@@ -2015,7 +2070,7 @@ function validateCommittedTransaction(
     }
     if (
       summary.transactionId !== transaction.transactionId ||
-      summary.operationProtocolVersion !== transaction.protocolVersion ||
+      summary.operationProtocolVersion !== transaction.operationProtocolVersion ||
       summary.priorStateHash !== transaction.priorStateHash ||
       summary.stateHash !== transaction.stateHash ||
       !frontiersEqual(summary.resultingCausalFrontier, transaction.causalFrontier)
@@ -2061,8 +2116,8 @@ function validateSnapshot(
   snapshot: EditableArtifactStoredReplica["snapshot"],
   artifactId: EditableArtifactId,
   modality: EditableArtifactModality,
-  protocolVersion: number,
-  kernelVersion: string,
+  operationProtocolVersion: number,
+  snapshotVersion: number,
   modelSchemaVersion: number,
   maxSnapshotBytes: number,
 ): void {
@@ -2076,22 +2131,22 @@ function validateSnapshot(
   positiveSafeInteger(snapshot.modelSchemaVersion, "snapshot.modelSchemaVersion");
   if (snapshot.modality === "spreadsheet") {
     validateFrontier(snapshot.causalFrontier, "snapshot.causalFrontier");
-    if (snapshot.protocolVersion !== protocolVersion) {
+    if (
+      snapshot.operationProtocolVersion !== operationProtocolVersion ||
+      snapshot.snapshotVersion !== snapshotVersion
+    ) {
       throw new EditableArtifactSyncError(
         "unsupported_protocol",
-        `snapshot protocol ${snapshot.protocolVersion} is incompatible with client ${protocolVersion}`,
+        `snapshot operation/state versions ${snapshot.operationProtocolVersion}/${snapshot.snapshotVersion} are incompatible with ${operationProtocolVersion}/${snapshotVersion}`,
       );
     }
   } else {
     requireNativeRevision(snapshot.nativeRevision, "snapshot.nativeRevision");
   }
-  if (
-    snapshot.kernelVersion !== kernelVersion ||
-    snapshot.modelSchemaVersion !== modelSchemaVersion
-  ) {
+  if (snapshot.modelSchemaVersion !== modelSchemaVersion) {
     throw new EditableArtifactSyncError(
       "unsupported_protocol",
-      `snapshot kernel/schema ${snapshot.kernelVersion}/${snapshot.modelSchemaVersion} is incompatible with ${kernelVersion}/${modelSchemaVersion}`,
+      `snapshot schema ${snapshot.modelSchemaVersion} is incompatible with ${modelSchemaVersion}`,
     );
   }
   if (!(snapshot.bytes instanceof Uint8Array)) {
@@ -2131,7 +2186,7 @@ function validateLiveMessage(
   message: EditableArtifactLiveMessage,
   artifactId: EditableArtifactId,
   modality: EditableArtifactModality,
-  protocolVersion: number,
+  operationProtocolVersion: number,
   maxCommittedTransactionBytes: number,
 ): void {
   if (!message || typeof message !== "object") {
@@ -2142,7 +2197,7 @@ function validateLiveMessage(
       message.transaction,
       artifactId,
       modality,
-      protocolVersion,
+      operationProtocolVersion,
       maxCommittedTransactionBytes,
     );
     return;
@@ -2198,7 +2253,7 @@ function estimateCommittedTransactionBytes(
 function requireStateHash(actual: string, expected: string, source: string): void {
   if (actual !== expected) {
     throw new EditableArtifactSyncError(
-      "kernel_diverged",
+      "authored_causal_mismatch",
       `${source} produced state hash ${actual}; expected ${expected}`,
       { retryable: true, requiresSnapshot: true },
     );
@@ -2209,7 +2264,7 @@ function requireDigest(actual: string, expected: string, source: string): void {
   requireSha256(actual, `${source} computed digest`);
   if (actual !== expected) {
     throw new EditableArtifactSyncError(
-      "kernel_diverged",
+      "byte_corruption",
       `${source} bytes produced digest ${actual}; expected ${expected}`,
       { retryable: true, requiresSnapshot: true },
     );
@@ -2230,7 +2285,7 @@ function requireFrontier(
     )
   ) {
     throw new EditableArtifactSyncError(
-      "kernel_diverged",
+      "authored_causal_mismatch",
       `${source} causal frontier does not match the authoritative barrier`,
       { retryable: true, requiresSnapshot: true },
     );
@@ -2416,7 +2471,7 @@ function requireNativeRevisionEqual(actual: number, expected: number, source: st
   requireNativeRevision(expected, `${source} expected native revision`);
   if (actual !== expected) {
     throw new EditableArtifactSyncError(
-      "kernel_diverged",
+      "authored_causal_mismatch",
       `${source} native revision ${actual} does not match ${expected}`,
       { retryable: true, requiresSnapshot: true },
     );

package/src/editable-artifacts/errors.ts

@@ -3,6 +3,8 @@ export type EditableArtifactSyncErrorCode =
   | "invalid_bootstrap"
   | "invalid_sequence"
   | "kernel_diverged"
+  | "byte_corruption"
+  | "authored_causal_mismatch"
   | "queue_overflow"
   | "resync_required"
   | "permission_changed"

package/src/editable-artifacts/http-live-transport.ts

@@ -11,6 +11,7 @@ import {
   EDITABLE_ARTIFACT_COMMAND_MAX_BYTES,
   EDITABLE_ARTIFACT_INTENT_MAX_BYTES,
   EDITABLE_ARTIFACT_PRODUCT_MAX_SNAPSHOT_BYTES,
+  currentEditableArtifactCompatibility,
   hashEditableArtifactMutationIntentBytes,
 } from "@opengeni/contracts/editable-artifacts";
 import { MAX_COMMITTED_TRANSACTION_BYTES } from "@opengeni/contracts/editable-artifact-committed-transaction";
@@ -34,7 +35,7 @@ import type {
 } from "./types";
 
 const LIVE_PATH = "/v1/editable-artifacts/live";
-const LIVE_SUBPROTOCOL = "opengeni-artifact-v1";
+const LIVE_SUBPROTOCOL = "opengeni-artifact-v2";
 const DEFAULT_MAX_SERVER_FRAME_BYTES = 8 * 1024 * 1024 + 64 * 1024;
 const DEFAULT_MAX_SNAPSHOT_BYTES = EDITABLE_ARTIFACT_PRODUCT_MAX_SNAPSHOT_BYTES;
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 20_000;
@@ -81,9 +82,13 @@ export type EditableArtifactWebSocketLike = {
 export type CreateEditableArtifactHttpLiveTransportOptions = Readonly<{
   baseUrl: string | URL;
   workspaceId: string;
-  protocolVersion: number;
+  modality: EditableArtifactModality;
+  liveProtocolVersion: number;
   kernelVersion: string;
   modelSchemaVersion: number;
+  snapshotVersion: number;
+  commandProtocolVersion: number;
+  committedTransactionProtocolVersion: number;
   apiKey?: string;
   headers?: Readonly<Record<string, string>> | (() => Readonly<Record<string, string>>);
   credentials?: RequestCredentials;
@@ -111,9 +116,13 @@ class HttpLiveTransport implements EditableArtifactSyncTransport {
   private readonly baseUrl: URL;
   private readonly socketUrl: URL;
   private readonly workspaceId: string;
-  private readonly protocolVersion: number;
+  private readonly modality: EditableArtifactModality;
+  private readonly liveProtocolVersion: number;
   private readonly kernelVersion: string;
   private readonly modelSchemaVersion: number;
+  private readonly snapshotVersion: number;
+  private readonly commandProtocolVersion: number;
+  private readonly committedTransactionProtocolVersion: number;
   private readonly apiKey: string | undefined;
   private readonly headerSource: CreateEditableArtifactHttpLiveTransportOptions["headers"];
   private readonly credentials: RequestCredentials;
@@ -132,9 +141,34 @@ class HttpLiveTransport implements EditableArtifactSyncTransport {
     const insecure = options.allowInsecureDevelopmentTransport ?? false;
     requireTransportSecurity(this.baseUrl, this.socketUrl, insecure);
     this.workspaceId = boundedString(options.workspaceId, "workspaceId", 256);
-    this.protocolVersion = positiveU16(options.protocolVersion, "protocolVersion");
+    const current = currentEditableArtifactCompatibility(options.modality);
+    this.modality = options.modality;
+    this.liveProtocolVersion = exactVersion(
+      options.liveProtocolVersion,
+      current.liveProtocolVersion,
+      "liveProtocolVersion",
+    );
     this.kernelVersion = boundedString(options.kernelVersion, "kernelVersion", 512);
-    this.modelSchemaVersion = positiveU16(options.modelSchemaVersion, "modelSchemaVersion");
+    this.modelSchemaVersion = exactVersion(
+      options.modelSchemaVersion,
+      current.modelSchemaVersion,
+      "modelSchemaVersion",
+    );
+    this.snapshotVersion = exactVersion(
+      options.snapshotVersion,
+      current.snapshotVersion,
+      "snapshotVersion",
+    );
+    this.commandProtocolVersion = exactVersion(
+      options.commandProtocolVersion,
+      current.commandProtocolVersion,
+      "commandProtocolVersion",
+    );
+    this.committedTransactionProtocolVersion = exactVersion(
+      options.committedTransactionProtocolVersion,
+      current.committedTransactionProtocolVersion,
+      "committedTransactionProtocolVersion",
+    );
     this.apiKey = options.apiKey;
     if (this.apiKey !== undefined) boundedString(this.apiKey, "apiKey", 16 * 1024);
     this.headerSource = options.headers;
@@ -187,9 +221,13 @@ class HttpLiveTransport implements EditableArtifactSyncTransport {
         },
         body: JSON.stringify({
           replicaId: input.replicaId,
-          protocolVersion: this.protocolVersion,
+          modality: this.modality,
+          liveProtocolVersion: this.liveProtocolVersion,
           kernelVersion: this.kernelVersion,
           modelSchemaVersion: this.modelSchemaVersion,
+          snapshotVersion: this.snapshotVersion,
+          commandProtocolVersion: this.commandProtocolVersion,
+          committedTransactionProtocolVersion: this.committedTransactionProtocolVersion,
         }),
         signal: input.signal,
       });
@@ -211,7 +249,7 @@ class HttpLiveTransport implements EditableArtifactSyncTransport {
       );
     }
     const value = await readBoundedJson(response, MAX_TICKET_RESPONSE_BYTES);
-    return validateTicket(value, input.artifactId, input.replicaId, this.protocolVersion);
+    return validateTicket(value, input.artifactId, input.replicaId, this.liveProtocolVersion);
   }
 
   async openLive(input: {
@@ -246,6 +284,7 @@ class HttpLiveTransport implements EditableArtifactSyncTransport {
       input.resume.modality === "spreadsheet"
         ? {
             ...commonResume,
+            modality: "spreadsheet",
             localCausalFrontier: cloneFrontier(input.resume.causalFrontier),
           }
         : {
@@ -458,7 +497,7 @@ class HttpLiveConnection implements EditableArtifactLiveConnection {
     }
     const commonBootstrap = {
       artifactId: this.ticket.artifactId,
-      protocolVersion: this.ticket.protocolVersion,
+      liveProtocolVersion: this.ticket.protocolVersion,
       headSequence: boundarySequence,
       headStateHash: boundaryStateHash,
       kernelVersion: snapshot?.kernelVersion ?? this.kernelVersion,
@@ -549,12 +588,6 @@ class HttpLiveConnection implements EditableArtifactLiveConnection {
     if (pending.artifactId !== this.ticket.artifactId) {
       throw new TypeError("pending transaction belongs to another artifact");
     }
-    if (pending.protocolVersion !== this.ticket.protocolVersion) {
-      throw new EditableArtifactTransportError("pending protocol does not match live stream", {
-        code: "unsupported",
-        retryable: false,
-      });
-    }
     if (
       pending.commandBytes.byteLength >
       Math.min(open.maxCommandBytes, EDITABLE_ARTIFACT_COMMAND_MAX_BYTES)
@@ -581,7 +614,7 @@ class HttpLiveConnection implements EditableArtifactLiveConnection {
     }
     const frame = encodeEditableArtifactLiveMutationWireFrame({
       type: "mutation",
-      protocolVersion: pending.protocolVersion,
+      protocolVersion: this.ticket.protocolVersion,
       artifactId: pending.artifactId,
       streamEpoch: open.streamEpoch,
       requestHash: pending.requestHash,
@@ -756,15 +789,9 @@ class HttpLiveConnection implements EditableArtifactLiveConnection {
         if (frame.transaction.artifactId !== this.ticket.artifactId) {
           throw new TypeError("live transaction belongs to another artifact");
         }
-        if (transactionModality(frame.transaction) !== this.ticket.modality) {
+        if (frame.transaction.modality !== this.ticket.modality) {
           throw new TypeError("live transaction modality mismatch");
         }
-        if (
-          (frame.transaction.modality === undefined ||
-            frame.transaction.modality === "spreadsheet") &&
-          frame.transaction.protocolVersion !== this.ticket.protocolVersion
-        )
-          throw new TypeError("live transaction protocol mismatch");
         if (
           frame.transaction.committedTransactionBytes.byteLength >
           this.limits.maxCommittedTransactionBytes
@@ -849,7 +876,7 @@ class HttpLiveConnection implements EditableArtifactLiveConnection {
     if (frame.protocolVersion !== this.ticket.protocolVersion) {
       throw new TypeError("live snapshot protocol mismatch");
     }
-    if (serverModality(frame.modality) !== this.ticket.modality) {
+    if (frame.modality !== this.ticket.modality) {
       throw new TypeError("live snapshot modality mismatch");
     }
     if (this.snapshotAssembly === null) {
@@ -895,7 +922,8 @@ class HttpLiveConnection implements EditableArtifactLiveConnection {
             ...commonSnapshot,
             modality: "spreadsheet" as const,
             causalFrontier: cloneFrontier(frame.causalFrontier),
-            protocolVersion: frame.protocolVersion,
+            operationProtocolVersion: frame.operationProtocolVersion,
+            snapshotVersion: frame.snapshotVersion,
           })
         : Object.freeze({
             ...commonSnapshot,
@@ -968,7 +996,7 @@ class HttpLiveConnection implements EditableArtifactLiveConnection {
     if (frame.protocolVersion !== this.ticket.protocolVersion) {
       throw new TypeError("live server frame protocol mismatch");
     }
-    if (frame.type === "open" && serverModality(frame.modality) !== this.ticket.modality) {
+    if (frame.type === "open" && frame.modality !== this.ticket.modality) {
       throw new TypeError("live open modality does not match its ticket");
     }
     if (this.openFrame && frame.streamEpoch !== this.openFrame.streamEpoch) {
@@ -1113,16 +1141,6 @@ function cloneCommitted(
   };
 }
 
-function transactionModality(
-  transaction: EditableArtifactCommittedTransaction | ContractCommittedTransaction,
-): EditableArtifactModality {
-  return transaction.modality ?? "spreadsheet";
-}
-
-function serverModality(value: EditableArtifactModality | undefined): EditableArtifactModality {
-  return value ?? "spreadsheet";
-}
-
 function serializedBoundaryRevision(
   snapshot: EditableArtifactSnapshot | null,
   resume:
@@ -1148,8 +1166,7 @@ function snapshotChunkAuthorityEqual(
   frame: Extract<EditableArtifactLiveServerFrame, { type: "snapshot" }>,
   metadata: SnapshotAssembly["metadata"],
 ): boolean {
-  const modality = serverModality(frame.modality);
-  if (modality !== serverModality(metadata.modality)) return false;
+  if (frame.modality !== metadata.modality) return false;
   if ("causalFrontier" in frame) {
     if (!("causalFrontier" in metadata)) return false;
     return frontiersEqual(frame.causalFrontier, metadata.causalFrontier);
@@ -1414,6 +1431,14 @@ function positiveU16(value: unknown, label: string): number {
   return number;
 }
 
+function exactVersion(value: unknown, expected: number, label: string): number {
+  const actual = positiveU16(value, label);
+  if (actual !== expected) {
+    throw new TypeError(`${label} ${actual} is incompatible with current version ${expected}`);
+  }
+  return actual;
+}
+
 function positiveBounded(value: unknown, maximum: number, label: string): number {
   if (!Number.isSafeInteger(value) || (value as number) <= 0 || (value as number) > maximum) {
     throw new TypeError(`${label} is invalid`);

package/src/editable-artifacts/index.ts

@@ -16,6 +16,12 @@ export type {
 } from "./browser-session";
 export { EditableArtifactSyncError, EditableArtifactTransportError } from "./errors";
 export type { EditableArtifactSyncErrorCode } from "./errors";
+export { classifyEditableArtifactOpenFailure } from "./open-failure";
+export type {
+  EditableArtifactOpenFailureCategory,
+  EditableArtifactOpenFailureEvent,
+  EditableArtifactOpenFailureReporter,
+} from "./open-failure";
 export { createEditableArtifactHttpLiveTransport } from "./http-live-transport";
 export type {
   CreateEditableArtifactHttpLiveTransportOptions,