@opengeni/sdk 1.0.1 → 2.3.0-canary.0

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,

package/src/editable-artifacts/open-failure.ts

@@ -0,0 +1,79 @@
+export type EditableArtifactOpenFailureCategory =
+  | "unsupported_old_format"
+  | "byte_corruption"
+  | "authored_causal_mismatch"
+  | "runtime_package_mismatch"
+  | "projection_parity_ci_failure";
+
+/** Content-free, bounded telemetry safe to emit for workbook-open failures. */
+export type EditableArtifactOpenFailureEvent = Readonly<{
+  category: EditableArtifactOpenFailureCategory;
+  code: string;
+}>;
+
+export type EditableArtifactOpenFailureReporter = (event: EditableArtifactOpenFailureEvent) => void;
+
+const BYTE_CORRUPTION_CODES = new Set([
+  "byte_corruption",
+  "artifact_bad_magic",
+  "artifact_checksum_mismatch",
+  "artifact_invalid_collaboration_snapshot",
+  "artifact_invalid_snapshot",
+  "artifact_invalid_tag",
+  "artifact_invalid_utf8",
+  "artifact_non_canonical",
+  "artifact_trailing_bytes",
+  "artifact_truncated",
+]);
+const AUTHORED_CAUSAL_CODES = new Set([
+  "artifact_state_mismatch",
+  "authored_causal_mismatch",
+  "committed_metadata_mismatch",
+  "invalid_frontier",
+  "kernel_diverged",
+]);
+const RUNTIME_PACKAGE_CODES = new Set([
+  "artifact_runtime_incompatible",
+  "artifact_runtime_integrity",
+  "artifact_runtime_manifest_invalid",
+  "artifact_runtime_unavailable",
+  "artifact_runtime_unsupported_target",
+  "incompatible_wasm_build",
+  "runtime_identity_mismatch",
+]);
+
+/** Maps only stable error codes; messages and workbook/formula content are ignored. */
+export function classifyEditableArtifactOpenFailure(
+  error: unknown,
+): EditableArtifactOpenFailureEvent | null {
+  const code = normalizedErrorCode(error);
+  if (code === null) return null;
+  let category: EditableArtifactOpenFailureCategory | null = null;
+  if (code === "unsupported_protocol" || code === "artifact_unsupported_version") {
+    category = "unsupported_old_format";
+  } else if (BYTE_CORRUPTION_CODES.has(code)) {
+    category = "byte_corruption";
+  } else if (AUTHORED_CAUSAL_CODES.has(code)) {
+    category = "authored_causal_mismatch";
+  } else if (RUNTIME_PACKAGE_CODES.has(code)) {
+    category = "runtime_package_mismatch";
+  } else if (code === "artifact_runtime_projection_parity") {
+    category = "projection_parity_ci_failure";
+  }
+  return category === null ? null : Object.freeze({ category, code });
+}
+
+function normalizedErrorCode(error: unknown): string | null {
+  if (typeof error !== "object" || error === null) return null;
+  let descriptor: PropertyDescriptor | undefined;
+  try {
+    descriptor = Object.getOwnPropertyDescriptor(error, "code");
+  } catch {
+    return null;
+  }
+  if (!descriptor || !("value" in descriptor)) return null;
+  const value = descriptor.value;
+  if (typeof value !== "string") return null;
+  const code = value.toLowerCase();
+  return /^[a-z][a-z0-9_]{0,127}$/u.test(code) ? code : null;
+}

package/src/editable-artifacts/storage.ts

@@ -135,7 +135,7 @@ export class MemoryEditableArtifactStorage implements EditableArtifactStoragePor
         stateHash: replica.head.stateHash,
         modality: replica.head.modality,
         ...(replica.head.snapshot.modality === "spreadsheet"
-          ? { protocolVersion: replica.head.snapshot.protocolVersion }
+          ? { operationProtocolVersion: replica.head.snapshot.operationProtocolVersion }
           : {}),
       },
       input,
@@ -227,10 +227,9 @@ type MemoryStoredReplica = {
 
 type IndexedDbStoredReplicaHead = Omit<StoredReplicaHead, "snapshot"> & {
   namespace: string;
-  /** Absent only on legacy spreadsheet records. */
-  modality?: EditableArtifactModality;
+  modality: EditableArtifactModality;
   /** Spreadsheet-only; absent for serialized modalities. */
-  protocolVersion?: number;
+  operationProtocolVersion?: number;
   tailCount: number;
   tailBytes: number;
 };
@@ -240,10 +239,10 @@ type IndexedDbCommittedTransaction = EditableArtifactCommittedTransaction & {
 };
 type IndexedDbPendingTransaction = EditableArtifactPendingTransaction & {
   namespace: string;
-  /** V3 IndexedDB key-path alias; always exactly clientTransactionId. */
+  /** IndexedDB key-path alias; always exactly clientTransactionId. */
   transactionId: string;
 };
-const DATABASE_VERSION = 3;
+const DATABASE_VERSION = 4;
 const REPLICA_HEAD_STORE = "replicas";
 const SNAPSHOT_STORE = "snapshots";
 const COMMITTED_STORE = "committedTransactions";
@@ -352,7 +351,7 @@ export class IndexedDbEditableArtifactStorage implements EditableArtifactStorage
     assertStoredHeadAccounting(head, tail.length, retainedTailBytes);
     const {
       namespace: _headNamespace,
-      protocolVersion: retainedProtocolVersion,
+      operationProtocolVersion: retainedOperationProtocolVersion,
       tailCount: _tailCount,
       tailBytes: _tailBytes,
       ...storedHead
@@ -364,13 +363,12 @@ export class IndexedDbEditableArtifactStorage implements EditableArtifactStorage
         normalizeStoredCommitted(value, ownedScope.modality),
       )
       .sort(compareCommittedTransactions);
-    const headModality = head.modality ?? "spreadsheet";
-    if (headModality !== ownedScope.modality) {
+    if (head.modality !== ownedScope.modality) {
       throw new TypeError("retained head modality does not match its storage scope");
     }
     if (
       storedSnapshot.modality === "spreadsheet" &&
-      retainedProtocolVersion !== storedSnapshot.protocolVersion
+      retainedOperationProtocolVersion !== storedSnapshot.operationProtocolVersion
     )
       throw new TypeError("retained head protocol does not match its snapshot");
     const replica: EditableArtifactStoredReplica = {
@@ -643,7 +641,11 @@ function assertStoredReplica(replica: EditableArtifactStoredReplica): void {
   assertSha256(replica.snapshot.digest, "snapshot.digest");
   if (replica.snapshot.modality === "spreadsheet") {
     assertFrontier(replica.snapshot.causalFrontier, "snapshot.causalFrontier");
-    assertPositiveInteger(replica.snapshot.protocolVersion, "snapshot.protocolVersion");
+    assertPositiveInteger(
+      replica.snapshot.operationProtocolVersion,
+      "snapshot.operationProtocolVersion",
+    );
+    assertPositiveInteger(replica.snapshot.snapshotVersion, "snapshot.snapshotVersion");
   } else {
     assertSequence(replica.snapshot.nativeRevision, "snapshot.nativeRevision");
   }
@@ -676,7 +678,7 @@ function assertStoredReplica(replica: EditableArtifactStoredReplica): void {
     if (
       transaction.modality === "spreadsheet" &&
       replica.snapshot.modality === "spreadsheet" &&
-      transaction.protocolVersion !== replica.snapshot.protocolVersion
+      transaction.operationProtocolVersion !== replica.snapshot.operationProtocolVersion
     )
       throw new TypeError("stored committed tail protocol does not match its snapshot");
     if (transaction.modality !== "spreadsheet") {
@@ -805,11 +807,11 @@ function assertCommittedTransaction(
   }
   if (transaction.modality === "spreadsheet") {
     assertFrontier(transaction.causalFrontier, "causalFrontier");
-    assertPositiveInteger(transaction.protocolVersion, "protocolVersion");
+    assertPositiveInteger(transaction.operationProtocolVersion, "operationProtocolVersion");
     const summary = decodeCommittedTransactionSummary(transaction.committedTransactionBytes);
     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)
@@ -907,8 +909,8 @@ function assertPendingTransaction(transaction: EditableArtifactPendingTransactio
 
 function assertAppendCanApply(
   head: Pick<StoredReplicaHead, "cursor" | "stateHash"> & {
-    modality?: EditableArtifactModality;
-    protocolVersion?: number;
+    modality: EditableArtifactModality;
+    operationProtocolVersion?: number;
   },
   input: EditableArtifactAppendCommittedInput,
 ): void {
@@ -917,15 +919,14 @@ function assertAppendCanApply(
       `artifact ${input.artifactId} retained head no longer matches append expectation`,
     );
   }
-  const headModality = head.modality ?? "spreadsheet";
-  if (input.transaction.modality !== headModality) {
+  if (input.transaction.modality !== head.modality) {
     throw new EditableArtifactStorageConflictError(
       `artifact ${input.artifactId} append modality does not match retained snapshot`,
     );
   }
   if (
     input.transaction.modality === "spreadsheet" &&
-    input.transaction.protocolVersion !== head.protocolVersion
+    input.transaction.operationProtocolVersion !== head.operationProtocolVersion
   ) {
     throw new EditableArtifactStorageConflictError(
       `artifact ${input.artifactId} append protocol does not match retained snapshot`,
@@ -936,7 +937,7 @@ function assertAppendCanApply(
 function assertReplacementCanApply(
   head:
     | (Pick<StoredReplicaHead, "cursor" | "stateHash"> & {
-        protocolVersion?: number;
+        operationProtocolVersion?: number;
       })
     | undefined,
   expectedHead: EditableArtifactExpectedStoredHead,
@@ -1028,7 +1029,7 @@ function committedTransactionsEqual(
     left.priorStateHash === right.priorStateHash &&
     left.stateHash === right.stateHash &&
     (left.modality === "spreadsheet" && right.modality === "spreadsheet"
-      ? left.protocolVersion === right.protocolVersion &&
+      ? left.operationProtocolVersion === right.operationProtocolVersion &&
         frontiersEqual(left.causalFrontier, right.causalFrontier)
       : left.modality !== "spreadsheet" &&
         right.modality !== "spreadsheet" &&
@@ -1107,9 +1108,7 @@ function normalizeStoredSnapshot(
   snapshot: Omit<IndexedDbStoredSnapshot, "namespace">,
   modality: EditableArtifactModality,
 ): EditableArtifactSnapshot {
-  const retainedModality =
-    (snapshot as { modality?: EditableArtifactModality }).modality ?? "spreadsheet";
-  if (retainedModality !== modality) {
+  if (snapshot.modality !== modality) {
     throw new TypeError("retained snapshot modality does not match its storage scope");
   }
   return { ...snapshot, modality } as EditableArtifactSnapshot;
@@ -1119,9 +1118,7 @@ function normalizeStoredCommitted(
   transaction: Omit<IndexedDbCommittedTransaction, "namespace">,
   modality: EditableArtifactModality,
 ): EditableArtifactCommittedTransaction {
-  const retainedModality =
-    (transaction as { modality?: EditableArtifactModality }).modality ?? "spreadsheet";
-  if (retainedModality !== modality) {
+  if (transaction.modality !== modality) {
     throw new TypeError("retained transaction modality does not match its storage scope");
   }
   return { ...transaction, modality } as EditableArtifactCommittedTransaction;
@@ -1131,9 +1128,7 @@ function normalizeStoredPending(
   transaction: Omit<IndexedDbPendingTransaction, "namespace" | "transactionId">,
   modality: EditableArtifactModality,
 ): EditableArtifactPendingTransaction {
-  const retainedModality =
-    (transaction as { modality?: EditableArtifactModality }).modality ?? "spreadsheet";
-  if (retainedModality !== modality) {
+  if (transaction.modality !== modality) {
     throw new TypeError("retained pending modality does not match its storage scope");
   }
   return { ...transaction, modality } as EditableArtifactPendingTransaction;
@@ -1269,18 +1264,12 @@ function openDatabase(factory: IDBFactory, databaseName: string): Promise<IDBDat
     };
     request.onupgradeneeded = (event) => {
       const database = request.result;
-      if (event.oldVersion < 2) {
-        // V1 records had no principal partition. They cannot be attributed
-        // safely, so discard this rebuildable cache instead of guessing scope.
+      if (event.oldVersion < DATABASE_VERSION) {
+        // All local artifact state is reconstructible. A format hard cut drops
+        // confirmed state and pending commands instead of interpreting old bytes.
         for (const name of [REPLICA_HEAD_STORE, SNAPSHOT_STORE, PENDING_STORE, COMMITTED_STORE]) {
           if (database.objectStoreNames.contains(name)) database.deleteObjectStore(name);
         }
-      } else if (event.oldVersion < 3) {
-        // V2 heads did not retain constant-time journal accounting. Confirmed
-        // state is reconstructible, so rebuild it while preserving the pending WAL.
-        for (const name of [REPLICA_HEAD_STORE, SNAPSHOT_STORE, COMMITTED_STORE]) {
-          if (database.objectStoreNames.contains(name)) database.deleteObjectStore(name);
-        }
       }
       if (!database.objectStoreNames.contains(REPLICA_HEAD_STORE)) {
         database.createObjectStore(REPLICA_HEAD_STORE, {
@@ -1373,7 +1362,9 @@ function replaceIndexedDbReplica(
               updatedAt: replica.updatedAt,
               modality: replica.modality,
               ...(replica.snapshot.modality === "spreadsheet"
-                ? { protocolVersion: replica.snapshot.protocolVersion }
+                ? {
+                    operationProtocolVersion: replica.snapshot.operationProtocolVersion,
+                  }
                 : {}),
               tailCount: replica.tail.length,
               tailBytes: committedTailBytes(replica.tail),

package/src/editable-artifacts/types.ts

@@ -39,7 +39,8 @@ type EditableArtifactSnapshotCommon = {
 export type EditableArtifactSpreadsheetSnapshot = EditableArtifactSnapshotCommon & {
   modality: "spreadsheet";
   causalFrontier: EditableArtifactCausalFrontier;
-  protocolVersion: number;
+  operationProtocolVersion: number;
+  snapshotVersion: number;
 };
 
 export type EditableArtifactSerializedSnapshot = EditableArtifactSnapshotCommon & {
@@ -67,7 +68,7 @@ export type EditableArtifactSpreadsheetCommittedTransaction =
   EditableArtifactCommittedTransactionCommon & {
     modality: "spreadsheet";
     causalFrontier: EditableArtifactCausalFrontier;
-    protocolVersion: number;
+    operationProtocolVersion: number;
     /** Exact whole canonical OGACO committed-transaction envelope. */
     committedTransactionBytes: Uint8Array;
   };
@@ -236,7 +237,7 @@ export type EditableArtifactStoredReplica = {
 
 type EditableArtifactBootstrapCommon = {
   artifactId: EditableArtifactId;
-  protocolVersion: number;
+  liveProtocolVersion: number;
   headSequence: number;
   headStateHash: string;
   kernelVersion: string;

package/src/editable-artifacts/worker/kernel-adapter.ts

@@ -4,15 +4,24 @@ import {
   EDITABLE_ARTIFACT_INTENT_VERSION,
   EDITABLE_ARTIFACT_PRODUCT_MAX_SNAPSHOT_BYTES,
   SPREADSHEET_ARTIFACT_COMMAND_VERSION,
+  SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
 } from "@opengeni/contracts/editable-artifacts";
-import { MAX_COMMITTED_TRANSACTION_BYTES } from "@opengeni/contracts/editable-artifact-committed-transaction";
+import {
+  SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
+  SPREADSHEET_KERNEL_COMMAND_VERSION,
+  SPREADSHEET_KERNEL_SNAPSHOT_VERSION,
+} from "@opengeni/contracts/editable-artifact-versions";
+import {
+  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+  MAX_COMMITTED_TRANSACTION_BYTES,
+} from "@opengeni/contracts/editable-artifact-committed-transaction";
 import type { ArtifactWorkerInitializeInput } from "./wire-codec";
 import type { EditableArtifactModality } from "../types";
 import { ArtifactWorkerProtocolError } from "./rpc-protocol";
 
 export type ArtifactWorkerKernelSession = {
   readonly modality: EditableArtifactModality;
-  /** Replays one exact whole canonical OGACO001 transaction. */
+  /** Replays one exact whole canonical OGACO002 transaction. */
   applyCommitted: (committedTransactionBytes: Uint8Array) => void;
   /** Authors and applies one exact OGATX001 intent over the current frontier. */
   applyPending: (intentBytes: Uint8Array) => void;
@@ -129,6 +138,7 @@ type WasmCapabilities = Readonly<{
   editableArtifactIntentVersion: number;
   kernelSnapshotVersion: number;
   spreadsheetCommandVersion: number;
+  spreadsheetModelSchemaVersion: number;
   maxCellsPerBatch: number;
   maxCommandBytes: number;
   maxCommands: number;
@@ -579,6 +589,7 @@ function decodeCapabilities(bytes: Uint8Array): WasmCapabilities {
     "safeRust",
     "sessionForks",
     "spreadsheetCommandVersion",
+    "spreadsheetModelSchemaVersion",
     "statefulSessions",
     "textLayout",
     "textLayoutFontBundleVersion",
@@ -637,6 +648,10 @@ function decodeCapabilities(bytes: Uint8Array): WasmCapabilities {
       value.spreadsheetCommandVersion,
       "spreadsheetCommandVersion",
     ),
+    spreadsheetModelSchemaVersion: positiveInteger(
+      value.spreadsheetModelSchemaVersion,
+      "spreadsheetModelSchemaVersion",
+    ),
     maxCellsPerBatch: positiveInteger(value.maxCellsPerBatch, "maxCellsPerBatch"),
     maxCommands: positiveInteger(value.maxCommands, "maxCommands"),
     maxSnapshotBytes: positiveInteger(value.maxSnapshotBytes, "maxSnapshotBytes"),
@@ -765,16 +780,17 @@ function decodeCapabilities(bytes: Uint8Array): WasmCapabilities {
     normalized.canonicalStateHash !== "sha256:canonical-snapshot" ||
     normalized.editableArtifactIntentVersion !== EDITABLE_ARTIFACT_INTENT_VERSION ||
     normalized.spreadsheetCommandVersion !== SPREADSHEET_ARTIFACT_COMMAND_VERSION ||
-    normalized.collaborationSnapshotVersion !== 1 ||
-    normalized.commandSchemaVersion !== 1 ||
-    normalized.committedTransactionVersion !== 1 ||
+    normalized.spreadsheetModelSchemaVersion !== SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION ||
+    normalized.collaborationSnapshotVersion !== SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION ||
+    normalized.commandSchemaVersion !== SPREADSHEET_KERNEL_COMMAND_VERSION ||
+    normalized.committedTransactionVersion !== COMMITTED_TRANSACTION_PROTOCOL_VERSION ||
     normalized.documentCommandVersion !== 1 ||
     normalized.documentQueryResponseVersion !== 1 ||
     normalized.documentQueryVersion !== 1 ||
     normalized.documentReceiptVersion !== 1 ||
     normalized.documentSnapshotVersion !== 1 ||
     normalized.documentStatefulSessions !== normalized.document ||
-    normalized.kernelSnapshotVersion !== 1 ||
+    normalized.kernelSnapshotVersion !== SPREADSHEET_KERNEL_SNAPSHOT_VERSION ||
     normalized.maxCellsPerBatch !== WASM_MAX_CELLS_PER_BATCH ||
     normalized.maxCommandBytes !== WASM_MAX_COMMAND_BYTES ||
     normalized.maxSpreadsheetCommandBytes !== EDITABLE_ARTIFACT_COMMAND_MAX_BYTES ||
@@ -868,7 +884,7 @@ function capabilityProfile(modality: EditableArtifactModality, capabilities: Was
       );
     }
     return {
-      modelSchemaVersion: capabilities.collaborationSnapshotVersion,
+      modelSchemaVersion: capabilities.spreadsheetModelSchemaVersion,
       commandVersion: capabilities.spreadsheetCommandVersion,
       maximumSnapshotBytes: capabilities.maxSnapshotBytes,
       maximumCommandBytes: capabilities.maxSpreadsheetCommandBytes,