@opengeni/sdk 0.52.1 → 1.0.0

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;
@@ -478,6 +479,8 @@ export type EditableArtifactSyncView = {
   writable: boolean;
   pendingTransactions: number;
   blockedPending: readonly EditableArtifactBlockedPending[];
+  /** A command barrier independent of the artifact's edit permission. */
+  authoringBlockedReason?: "pending_conflict" | "prior_writer" | undefined;
   queuedMessages: number;
   reconnectAttempt: number;
   lastError: Error | null;

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,

package/src/editable-artifacts/worker/runtime.ts

@@ -5,9 +5,13 @@ import {
   decodeEditableArtifactMutationIntent,
   hashEditableArtifactMutationIntent,
 } from "@opengeni/contracts/editable-artifacts";
-import { decodeCommittedTransactionSummary } from "@opengeni/contracts/editable-artifact-committed-transaction";
+import {
+  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+  decodeCommittedTransactionSummary,
+} from "@opengeni/contracts/editable-artifact-committed-transaction";
 import { editableArtifactCodecFor } from "@opengeni/contracts/editable-artifact-codec-registry";
 import { decodeEditableArtifactSerializedCommit } from "@opengeni/contracts/editable-artifact-serialized-commit";
+import { SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION } from "@opengeni/contracts/editable-artifact-versions";
 import type {
   EditableArtifactBlockedPending,
   EditableArtifactCausalFrontier,
@@ -269,18 +273,20 @@ export class ArtifactWorkerRuntime {
       snapshot.modality !== initialization.modality ||
       snapshot.modality !== adapter.modality ||
       (snapshot.modality === "spreadsheet" &&
-        snapshot.protocolVersion !== adapter.protocolVersion) ||
-      snapshot.kernelVersion !== adapter.kernelVersion ||
+        (snapshot.operationProtocolVersion !== COMMITTED_TRANSACTION_PROTOCOL_VERSION ||
+          snapshot.snapshotVersion !== SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION)) ||
       snapshot.modelSchemaVersion !== adapter.modelSchemaVersion
     ) {
       throw runtimeError(
         "unsupported_protocol",
-        "snapshot protocol/kernel/schema is incompatible with the loaded collaboration kernel",
+        "snapshot protocol/schema is incompatible with the loaded collaboration kernel",
       );
     }
     const digest = await sha256Hex(ownedBytes);
     this.throwIfCancelled(frame.requestId);
-    requireMatchingHash(digest, snapshot.digest, "snapshot digest");
+    if (digest !== snapshot.digest) {
+      throw runtimeError("byte_corruption", "snapshot digest does not match its bytes");
+    }
     const canonical = requireBytesWithin(
       adapter.canonicalizeSnapshot(ownedBytes),
       initialization.maximumSnapshotBytes,
@@ -298,7 +304,12 @@ export class ArtifactWorkerRuntime {
     try {
       stateHash = await nextConfirmed.stateHash();
       this.throwIfCancelled(frame.requestId);
-      requireMatchingHash(stateHash, snapshot.stateHash, "snapshot state");
+      if (stateHash !== snapshot.stateHash) {
+        throw runtimeError(
+          "authored_causal_mismatch",
+          "snapshot authored state does not match its state hash",
+        );
+      }
       if (
         snapshot.modality !== "spreadsheet" &&
         nextConfirmed.nativeRevision() !== snapshot.nativeRevision
@@ -324,7 +335,7 @@ export class ArtifactWorkerRuntime {
             artifactId: snapshot.artifactId,
             modality: "spreadsheet",
             sequence: snapshot.sequence,
-            protocolVersion: snapshot.protocolVersion,
+            protocolVersion: adapter.protocolVersion,
             kernelVersion: snapshot.kernelVersion,
             modelSchemaVersion: snapshot.modelSchemaVersion,
             stateHash,
@@ -566,7 +577,7 @@ export class ArtifactWorkerRuntime {
     }
     if (
       transaction.modality === "spreadsheet" &&
-      transaction.protocolVersion !== installed.protocolVersion
+      transaction.operationProtocolVersion !== COMMITTED_TRANSACTION_PROTOCOL_VERSION
     )
       throw runtimeError("unsupported_protocol", "committed transaction protocol is incompatible");
     if (transaction.startSequence !== installed.sequence + 1) {
@@ -1046,12 +1057,12 @@ function assertCommittedEnvelopeMatchesOuter(
   } catch (error) {
     throw new ArtifactWorkerProtocolError(
       "invalid_committed_transaction",
-      "committed transaction is not canonical OGACO001",
+      "committed transaction is not canonical OGACO002",
       { cause: error },
     );
   }
   if (
-    summary.operationProtocolVersion !== transaction.protocolVersion ||
+    summary.operationProtocolVersion !== transaction.operationProtocolVersion ||
     summary.transactionId !== transaction.transactionId ||
     summary.priorStateHash !== transaction.priorStateHash ||
     summary.stateHash !== transaction.stateHash ||
@@ -1059,7 +1070,7 @@ function assertCommittedEnvelopeMatchesOuter(
   ) {
     throw runtimeError(
       "committed_metadata_mismatch",
-      "outer committed metadata disagrees with its exact OGACO001 envelope",
+      "outer committed metadata disagrees with its exact OGACO002 envelope",
     );
   }
 }
@@ -1156,8 +1167,9 @@ function asWorkerFailure(error: unknown): WorkerFailure {
     };
   }
   if (error instanceof Error) {
+    const rawCode = (error as Error & { code?: unknown }).code;
     return {
-      code: "kernel_failed",
+      code: typeof rawCode === "string" ? normalizeErrorCode(rawCode) : "kernel_failed",
       message: sanitizeErrorMessage(error.message || "artifact kernel failed"),
       retryable: false,
     };
@@ -1175,7 +1187,8 @@ function asProtocolError(error: unknown): ArtifactWorkerProtocolError {
 }
 
 function normalizeErrorCode(value: string): string {
-  return /^[a-z][a-z0-9_]{0,127}$/.test(value) ? value : "kernel_failed";
+  const normalized = value.toLowerCase();
+  return /^[a-z][a-z0-9_]{0,127}$/.test(normalized) ? normalized : "kernel_failed";
 }
 
 function sanitizeErrorMessage(value: string): string {

package/src/editable-artifacts/worker/wire-codec.ts

@@ -126,7 +126,10 @@ export function encodeSnapshotMetadata(snapshot: EditableArtifactSnapshot): Uint
   if (snapshot.modality === "spreadsheet") {
     writer
       .frontier(snapshot.causalFrontier)
-      .u32(positiveSafeInteger(snapshot.protocolVersion, "snapshot.protocolVersion"));
+      .u32(
+        positiveSafeInteger(snapshot.operationProtocolVersion, "snapshot.operationProtocolVersion"),
+      )
+      .u32(positiveSafeInteger(snapshot.snapshotVersion, "snapshot.snapshotVersion"));
   } else {
     writer.safeUint(nonNegativeSafeInteger(snapshot.nativeRevision, "snapshot.nativeRevision"));
   }
@@ -154,7 +157,11 @@ export function decodeSnapshotMetadata(
           ...common,
           modality,
           causalFrontier: reader.frontier(),
-          protocolVersion: positiveSafeInteger(reader.u32(), "snapshot.protocolVersion"),
+          operationProtocolVersion: positiveSafeInteger(
+            reader.u32(),
+            "snapshot.operationProtocolVersion",
+          ),
+          snapshotVersion: positiveSafeInteger(reader.u32(), "snapshot.snapshotVersion"),
         }
       : {
           ...common,
@@ -195,7 +202,10 @@ export function decodeCommittedMetadata(
           ...common,
           modality,
           causalFrontier: reader.frontier(),
-          protocolVersion: positiveSafeInteger(reader.u32(), "transaction.protocolVersion"),
+          operationProtocolVersion: positiveSafeInteger(
+            reader.u32(),
+            "transaction.operationProtocolVersion",
+          ),
         }
       : {
           ...common,
@@ -427,7 +437,12 @@ function encodeCommittedFields(
   if (transaction.modality === "spreadsheet") {
     writer
       .frontier(transaction.causalFrontier)
-      .u32(positiveSafeInteger(transaction.protocolVersion, "transaction.protocolVersion"));
+      .u32(
+        positiveSafeInteger(
+          transaction.operationProtocolVersion,
+          "transaction.operationProtocolVersion",
+        ),
+      );
   } else {
     writer
       .safeUint(
@@ -461,7 +476,10 @@ function decodeCommittedFields(
           ...common,
           modality,
           causalFrontier: reader.frontier(),
-          protocolVersion: positiveSafeInteger(reader.u32(), "transaction.protocolVersion"),
+          operationProtocolVersion: positiveSafeInteger(
+            reader.u32(),
+            "transaction.operationProtocolVersion",
+          ),
         }
       : {
           ...common,