@opengeni/contracts 0.50.0 → 1.0.0

package/src/editable-artifact-committed-transaction.ts

@@ -1,5 +1,5 @@
 /**
- * Strict, allocation-bounded inspection of canonical OGACO001 transactions.
+ * Strict, allocation-bounded inspection of canonical OGACO002 transactions.
  *
  * The Rust kernel remains the authority for applying operations. This decoder
  * validates the complete envelope and every typed operation so metadata after
@@ -15,7 +15,7 @@ export const MAX_COMMITTED_TRANSACTION_OPERATIONS = 4_096;
 export const MAX_COMMITTED_TRANSACTION_CAUSAL_REPLICAS = 100_000;
 export const MAX_COMMITTED_TRANSACTION_CELLS = 1_000_000;
 
-const MAGIC = new Uint8Array([0x4f, 0x47, 0x41, 0x43, 0x4f, 0x30, 0x30, 0x31]); // OGACO001
+const MAGIC = new Uint8Array([0x4f, 0x47, 0x41, 0x43, 0x4f, 0x30, 0x30, 0x32]); // OGACO002
 const HEADER_BYTES = 24;
 const CHECKSUM_BYTES = 8;
 const HASH_BYTES = 32;
@@ -24,6 +24,7 @@ const MAX_OPERATION_STRING_BYTES = 4 * 1024 * 1024;
 const MAX_SAFE_U64_HIGH = 0x1f_ffff;
 const U32_SIZE = 0x1_0000_0000;
 const U32_MAX = 0xffff_ffff;
+const MAX_DATE_MILLISECONDS = 8_640_000_000_000_000n;
 const FNV_OFFSET_LOW = 0x8422_2325;
 const FNV_OFFSET_HIGH = 0xcbf2_9ce4;
 const FNV_PRIME_LOW = 0x01b3;
@@ -47,7 +48,7 @@ export type CommittedTransactionSummary = Readonly<{
 }>;
 
 /**
- * Decodes only the metadata of one exact canonical OGACO001 byte envelope.
+ * Decodes only the metadata of one exact canonical OGACO002 byte envelope.
  *
  * This function is synchronous and never mutates or retains `bytes`. The
  * caller remains the owner of the exact canonical envelope.
@@ -55,38 +56,38 @@ export type CommittedTransactionSummary = Readonly<{
 export function decodeCommittedTransactionSummary(bytes: Uint8Array): CommittedTransactionSummary {
   assertInput(bytes);
   if (bytes.byteLength > MAX_COMMITTED_TRANSACTION_BYTES) {
-    throw new RangeError("OGACO001 envelope exceeds its byte limit");
+    throw new RangeError("OGACO002 envelope exceeds its byte limit");
   }
   if (bytes.byteLength < HEADER_BYTES + CHECKSUM_BYTES) {
-    throw new TypeError("truncated OGACO001 envelope");
+    throw new TypeError("truncated OGACO002 envelope");
   }
 
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
   for (let index = 0; index < MAGIC.byteLength; index += 1) {
-    if (bytes[index] !== MAGIC[index]) throw new TypeError("invalid OGACO001 magic");
+    if (bytes[index] !== MAGIC[index]) throw new TypeError("invalid OGACO002 magic");
   }
 
   const version = view.getUint16(8, true);
   if (version !== COMMITTED_TRANSACTION_PROTOCOL_VERSION) {
-    throw new TypeError(`unsupported OGACO001 version: ${version}`);
+    throw new TypeError(`unsupported OGACO002 version: ${version}`);
   }
   if (view.getUint16(10, true) !== 0) {
-    throw new TypeError("reserved OGACO001 header bits are set");
+    throw new TypeError("reserved OGACO002 header bits are set");
   }
 
   const operationCount = view.getUint32(12, true);
   if (operationCount === 0 || operationCount > MAX_COMMITTED_TRANSACTION_OPERATIONS) {
-    throw new RangeError("OGACO001 operation count is outside its canonical bounds");
+    throw new RangeError("OGACO002 operation count is outside its canonical bounds");
   }
 
-  const payloadLength = safeU64At(view, 16, "OGACO001 payload length", false);
-  const payloadEnd = checkedAdd(HEADER_BYTES, payloadLength, "OGACO001 payload length");
-  const expectedLength = checkedAdd(payloadEnd, CHECKSUM_BYTES, "OGACO001 envelope length");
+  const payloadLength = safeU64At(view, 16, "OGACO002 payload length", false);
+  const payloadEnd = checkedAdd(HEADER_BYTES, payloadLength, "OGACO002 payload length");
+  const expectedLength = checkedAdd(payloadEnd, CHECKSUM_BYTES, "OGACO002 envelope length");
   if (bytes.byteLength !== expectedLength) {
     throw new TypeError(
       bytes.byteLength < expectedLength
-        ? "truncated OGACO001 payload"
-        : "trailing bytes after OGACO001 envelope",
+        ? "truncated OGACO002 payload"
+        : "trailing bytes after OGACO002 envelope",
     );
   }
 
@@ -95,7 +96,7 @@ export function decodeCommittedTransactionSummary(bytes: Uint8Array): CommittedT
     view.getUint32(payloadEnd, true) !== checksumLow ||
     view.getUint32(payloadEnd + 4, true) !== checksumHigh
   ) {
-    throw new TypeError("OGACO001 checksum mismatch");
+    throw new TypeError("OGACO002 checksum mismatch");
   }
 
   const reader = new Reader(bytes, HEADER_BYTES, payloadEnd);
@@ -113,7 +114,7 @@ export function decodeCommittedTransactionSummary(bytes: Uint8Array): CommittedT
   for (let index = 0; index < operationCount; index += 1) {
     const operationId = reader.stableId(`operation ${index} id`);
     if (seenOperationIds.has(operationId)) {
-      throw new TypeError("OGACO001 operation ids must be unique");
+      throw new TypeError("OGACO002 operation ids must be unique");
     }
     seenOperationIds.add(operationId);
     operationIds.push(operationId);
@@ -273,7 +274,7 @@ class Reader {
         const endRow = this.u32("clear range end row");
         const endColumn = this.u32("clear range end column");
         if (startRow > endRow || startColumn > endColumn) {
-          throw new TypeError("OGACO001 clear range is not normalized");
+          throw new TypeError("OGACO002 clear range is not normalized");
         }
         return totalCells;
       }
@@ -281,7 +282,7 @@ class Reader {
         this.stableId("selective undo target");
         return totalCells;
       default:
-        throw new TypeError(`invalid OGACO001 collaboration command tag: ${tag}`);
+        throw new TypeError(`invalid OGACO002 collaboration command tag: ${tag}`);
     }
   }
 
@@ -292,18 +293,18 @@ class Reader {
     const rows = this.u32("cell block rows");
     const columns = this.u32("cell block columns");
     if (rows === 0 || columns === 0) {
-      throw new TypeError("OGACO001 cell block dimensions must be nonzero");
+      throw new TypeError("OGACO002 cell block dimensions must be nonzero");
     }
     if (anchorRow > U32_MAX - (rows - 1) || anchorColumn > U32_MAX - (columns - 1)) {
-      throw new RangeError("OGACO001 cell block coordinates overflow u32");
+      throw new RangeError("OGACO002 cell block coordinates overflow u32");
     }
     if (rows > Math.floor(MAX_COMMITTED_TRANSACTION_CELLS / columns)) {
-      throw new RangeError("OGACO001 cell block exceeds its cell limit");
+      throw new RangeError("OGACO002 cell block exceeds its cell limit");
     }
     const cellCount = rows * columns;
     const nextTotal = totalCells + cellCount;
     if (nextTotal > MAX_COMMITTED_TRANSACTION_CELLS) {
-      throw new RangeError("OGACO001 transaction exceeds its cell limit");
+      throw new RangeError("OGACO002 transaction exceeds its cell limit");
     }
     for (let index = 0; index < cellCount; index += 1) this.skipCell();
     return nextTotal;
@@ -313,10 +314,11 @@ class Reader {
     const formulaTag = this.u8("cell formula tag");
     if (formulaTag === 1) {
       if (this.skipString("cell formula") === 0) {
-        throw new TypeError("OGACO001 formula must not be empty");
+        throw new TypeError("OGACO002 formula must not be empty");
       }
+      return;
     } else if (formulaTag !== 0) {
-      throw new TypeError(`invalid OGACO001 cell formula tag: ${formulaTag}`);
+      throw new TypeError(`invalid OGACO002 cell formula tag: ${formulaTag}`);
     }
 
     const valueTag = this.u8("cell value tag");
@@ -334,8 +336,11 @@ class Reader {
       case 5:
         this.skipFormulaError();
         return;
+      case 6:
+        this.skipDate();
+        return;
       default:
-        throw new TypeError(`invalid OGACO001 cell value tag: ${valueTag}`);
+        throw new TypeError(`invalid OGACO002 cell value tag: ${valueTag}`);
     }
   }
 
@@ -344,10 +349,18 @@ class Reader {
     const low = this.#view.getUint32(offset, true);
     const high = this.#view.getUint32(offset + 4, true);
     if (low === 0 && high === 0x8000_0000) {
-      throw new TypeError("OGACO001 cell number uses negative zero");
+      throw new TypeError("OGACO002 cell number uses negative zero");
     }
     if ((high & 0x7ff0_0000) === 0x7ff0_0000) {
-      throw new TypeError("OGACO001 cell numbers must be finite");
+      throw new TypeError("OGACO002 cell numbers must be finite");
+    }
+  }
+
+  skipDate(): void {
+    const offset = this.reserve(8, "cell date");
+    const milliseconds = this.#view.getBigInt64(offset, true);
+    if (milliseconds < -MAX_DATE_MILLISECONDS || milliseconds > MAX_DATE_MILLISECONDS) {
+      throw new TypeError("OGACO002 cell date is outside the ECMAScript range");
     }
   }
 
@@ -358,7 +371,7 @@ class Reader {
       this.skipString("custom formula error");
       return;
     }
-    throw new TypeError(`invalid OGACO001 formula error tag: ${tag}`);
+    throw new TypeError(`invalid OGACO002 formula error tag: ${tag}`);
   }
 
   skipGeneration(label: string): void {
@@ -377,16 +390,16 @@ class Reader {
   }
 
   done(): void {
-    if (this.#offset !== this.#end) throw new TypeError("trailing bytes in OGACO001 payload");
+    if (this.#offset !== this.#end) throw new TypeError("trailing bytes in OGACO002 payload");
   }
 }
 
 function assertInput(bytes: Uint8Array): void {
   if (!(bytes instanceof Uint8Array)) {
-    throw new TypeError("OGACO001 bytes must be a Uint8Array");
+    throw new TypeError("OGACO002 bytes must be a Uint8Array");
   }
   if (typeof SharedArrayBuffer !== "undefined" && bytes.buffer instanceof SharedArrayBuffer) {
-    throw new TypeError("OGACO001 bytes must not use shared mutable memory");
+    throw new TypeError("OGACO002 bytes must not use shared mutable memory");
   }
 }
 

package/src/editable-artifact-live.ts

@@ -3,8 +3,9 @@ import {
   hashEditableArtifactMutationIntentBytes,
   type EditableArtifactCausalEntry,
 } from "./editable-artifacts";
+import { EDITABLE_ARTIFACT_LIVE_WIRE_VERSION } from "./editable-artifact-versions";
 
-const MAGIC = new TextEncoder().encode("OGALV001");
+const MAGIC = new TextEncoder().encode("OGALV002");
 const HEADER_BYTES = 20;
 const MAX_METADATA_BYTES = 64 * 1024;
 const MAX_TOKEN_BYTES = 4_096;
@@ -42,7 +43,7 @@ const MUTATION_REJECTION_CODES = new Set([
   "unavailable",
 ]);
 
-export const EDITABLE_ARTIFACT_LIVE_WIRE_VERSION = 1;
+export { EDITABLE_ARTIFACT_LIVE_WIRE_VERSION } from "./editable-artifact-versions";
 
 export type EditableArtifactId = string;
 export type EditableArtifactRequestHash = string;
@@ -101,8 +102,7 @@ type EditableArtifactLiveResumeCommon = Readonly<{
 export type EditableArtifactLiveResume =
   | (EditableArtifactLiveResumeCommon &
       Readonly<{
-        /** Omitted on OGALV001 for byte-compatible spreadsheet sessions. */
-        modality?: "spreadsheet";
+        modality: "spreadsheet";
         localCausalFrontier: EditableArtifactCausalFrontier;
       }>)
   | (EditableArtifactLiveResumeCommon &
@@ -133,9 +133,10 @@ type EditableArtifactLiveSnapshotCommon = Readonly<{
 export type EditableArtifactLiveSnapshot =
   | (EditableArtifactLiveSnapshotCommon &
       Readonly<{
-        modality?: "spreadsheet";
+        modality: "spreadsheet";
         causalFrontier: EditableArtifactCausalFrontier;
-        protocolVersion: number;
+        operationProtocolVersion: number;
+        snapshotVersion: number;
       }>)
   | (EditableArtifactLiveSnapshotCommon &
       Readonly<{
@@ -157,9 +158,9 @@ type EditableArtifactLiveCommittedTransactionCommon = Readonly<{
 export type EditableArtifactLiveCommittedTransaction =
   | (EditableArtifactLiveCommittedTransactionCommon &
       Readonly<{
-        modality?: "spreadsheet";
+        modality: "spreadsheet";
         causalFrontier: EditableArtifactCausalFrontier;
-        protocolVersion: number;
+        operationProtocolVersion: number;
         /** Exact canonical whole OGACO transaction envelope. */
         committedTransactionBytes: Uint8Array;
       }>)
@@ -252,8 +253,7 @@ export type EditableArtifactLiveServerFrame =
       protocolVersion: number;
       artifactId: EditableArtifactId;
       streamEpoch: string;
-      /** Omitted on the wire for spreadsheet compatibility. */
-      modality?: EditableArtifactLiveModality;
+      modality: EditableArtifactLiveModality;
       writable: boolean;
       headSequence: number;
       minimumReplaySequence: number;
@@ -282,9 +282,10 @@ export type EditableArtifactLiveServerFrame =
     }> &
       (
         | Readonly<{
-            /** Omitted on the wire for spreadsheet compatibility. */
-            modality?: "spreadsheet";
+            modality: "spreadsheet";
             causalFrontier: EditableArtifactCausalFrontier;
+            operationProtocolVersion: number;
+            snapshotVersion: number;
           }>
         | Readonly<{
             modality: "document" | "presentation";
@@ -439,6 +440,7 @@ export function encodeEditableArtifactLiveOpenWireFrame(
       protocolVersion,
       artifactId,
       token,
+      modality: resume.modality,
       localCursor: resume.localCursor,
       localStateHash: resume.localStateHash,
       localCausalFrontier: resume.localCausalFrontier,
@@ -491,28 +493,22 @@ export function encodeEditableArtifactLiveServerWireFrame(
 ): Uint8Array {
   switch (frame.type) {
     case "open": {
-      const { modality, ...metadata } = frame;
       return encodeEnvelope(
         SERVER_OPEN,
-        modality === "document" || modality === "presentation"
-          ? {
-              type: metadata.type,
-              protocolVersion: metadata.protocolVersion,
-              artifactId: metadata.artifactId,
-              streamEpoch: metadata.streamEpoch,
-              modality,
-              writable: metadata.writable,
-              headSequence: metadata.headSequence,
-              minimumReplaySequence: metadata.minimumReplaySequence,
-              maxClientFrameBytes: metadata.maxClientFrameBytes,
-              maxCommandBytes: metadata.maxCommandBytes,
-              maxIntentBytes: metadata.maxIntentBytes,
-              maxCommittedTransactionBytes: metadata.maxCommittedTransactionBytes,
-              maxSnapshotBytes: metadata.maxSnapshotBytes,
-              maxInFlightTransactions: metadata.maxInFlightTransactions,
-              maxInFlightBytes: metadata.maxInFlightBytes,
-            }
-          : metadata,
+        {
+          ...serverFrameIdentity(frame),
+          modality: frame.modality,
+          writable: frame.writable,
+          headSequence: frame.headSequence,
+          minimumReplaySequence: frame.minimumReplaySequence,
+          maxClientFrameBytes: frame.maxClientFrameBytes,
+          maxCommandBytes: frame.maxCommandBytes,
+          maxIntentBytes: frame.maxIntentBytes,
+          maxCommittedTransactionBytes: frame.maxCommittedTransactionBytes,
+          maxSnapshotBytes: frame.maxSnapshotBytes,
+          maxInFlightTransactions: frame.maxInFlightTransactions,
+          maxInFlightBytes: frame.maxInFlightBytes,
+        },
         EMPTY_BYTES,
       );
     }
@@ -555,10 +551,14 @@ export function encodeEditableArtifactLiveServerWireFrame(
               protocolVersion: metadata.protocolVersion,
               artifactId: metadata.artifactId,
               streamEpoch: metadata.streamEpoch,
+              modality,
               sequence: metadata.sequence,
               stateHash: metadata.stateHash,
               causalFrontier: (metadata as { causalFrontier: EditableArtifactCausalFrontier })
                 .causalFrontier,
+              operationProtocolVersion: (metadata as { operationProtocolVersion: number })
+                .operationProtocolVersion,
+              snapshotVersion: (metadata as { snapshotVersion: number }).snapshotVersion,
               digest: metadata.digest,
               kernelVersion: metadata.kernelVersion,
               modelSchemaVersion: metadata.modelSchemaVersion,
@@ -576,9 +576,10 @@ export function encodeEditableArtifactLiveServerWireFrame(
         { modality: "document" | "presentation" }
       >;
       const transactionMetadata =
-        transaction.modality === undefined || transaction.modality === "spreadsheet"
+        transaction.modality === "spreadsheet"
           ? {
               artifactId: transaction.artifactId,
+              modality: transaction.modality,
               transactionId: transaction.transactionId,
               requestHash: transaction.requestHash,
               startSequence: transaction.startSequence,
@@ -586,7 +587,7 @@ export function encodeEditableArtifactLiveServerWireFrame(
               priorStateHash: transaction.priorStateHash,
               stateHash: transaction.stateHash,
               causalFrontier: transaction.causalFrontier,
-              protocolVersion: transaction.protocolVersion,
+              operationProtocolVersion: transaction.operationProtocolVersion,
             }
           : {
               artifactId: serializedTransaction.artifactId,
@@ -603,27 +604,82 @@ export function encodeEditableArtifactLiveServerWireFrame(
             };
       return encodeEnvelope(
         SERVER_TRANSACTION,
-        { ...frame, transaction: transactionMetadata },
+        { ...serverFrameIdentity(frame), transaction: transactionMetadata },
         committedTransactionBytes,
       );
     }
     case "barrier":
-      return encodeEnvelope(SERVER_BARRIER, { ...frame }, EMPTY_BYTES);
+      return encodeEnvelope(
+        SERVER_BARRIER,
+        { ...serverFrameIdentity(frame), sequence: frame.sequence, stateHash: frame.stateHash },
+        EMPTY_BYTES,
+      );
     case "watermark":
-      return encodeEnvelope(SERVER_WATERMARK, { ...frame }, EMPTY_BYTES);
+      return encodeEnvelope(
+        SERVER_WATERMARK,
+        { ...serverFrameIdentity(frame), headSequence: frame.headSequence },
+        EMPTY_BYTES,
+      );
     case "resyncRequired":
-      return encodeEnvelope(SERVER_RESYNC_REQUIRED, { ...frame }, EMPTY_BYTES);
+      return encodeEnvelope(
+        SERVER_RESYNC_REQUIRED,
+        { ...serverFrameIdentity(frame), reason: frame.reason, headSequence: frame.headSequence },
+        EMPTY_BYTES,
+      );
     case "applied":
-      return encodeEnvelope(SERVER_APPLIED, { ...frame }, EMPTY_BYTES);
+      return encodeEnvelope(
+        SERVER_APPLIED,
+        { ...serverFrameIdentity(frame), sequence: frame.sequence, stateHash: frame.stateHash },
+        EMPTY_BYTES,
+      );
     case "authorizationChanged":
-      return encodeEnvelope(SERVER_AUTHORIZATION_CHANGED, { ...frame }, EMPTY_BYTES);
+      return encodeEnvelope(
+        SERVER_AUTHORIZATION_CHANGED,
+        { ...serverFrameIdentity(frame), writable: frame.writable },
+        EMPTY_BYTES,
+      );
     case "mutationAccepted":
-      return encodeEnvelope(SERVER_MUTATION_ACCEPTED, { ...frame }, EMPTY_BYTES);
+      return encodeEnvelope(
+        SERVER_MUTATION_ACCEPTED,
+        {
+          ...serverFrameIdentity(frame),
+          requestHash: frame.requestHash,
+          clientTransactionId: frame.clientTransactionId,
+          transactionId: frame.transactionId,
+          startSequence: frame.startSequence,
+          endSequence: frame.endSequence,
+          stateHash: frame.stateHash,
+        },
+        EMPTY_BYTES,
+      );
     case "mutationRejected":
-      return encodeEnvelope(SERVER_MUTATION_REJECTED, { ...frame }, EMPTY_BYTES);
+      return encodeEnvelope(
+        SERVER_MUTATION_REJECTED,
+        {
+          ...serverFrameIdentity(frame),
+          requestHash: frame.requestHash,
+          code: frame.code,
+          retryable: frame.retryable,
+        },
+        EMPTY_BYTES,
+      );
   }
 }
 
+function serverFrameIdentity(frame: EditableArtifactLiveServerFrame): Readonly<{
+  type: EditableArtifactLiveServerFrame["type"];
+  protocolVersion: number;
+  artifactId: EditableArtifactId;
+  streamEpoch: string;
+}> {
+  return {
+    type: frame.type,
+    protocolVersion: frame.protocolVersion,
+    artifactId: frame.artifactId,
+    streamEpoch: frame.streamEpoch,
+  };
+}
+
 /** Strict inverse used by browser/desktop SDK transports. */
 export function decodeEditableArtifactLiveServerWireFrame(
   bytes: Uint8Array,
@@ -635,7 +691,7 @@ export function decodeEditableArtifactLiveServerWireFrame(
       requireNoPayload(decoded.payload);
       const modality = serverModality(metadata);
       requireServerKeys(metadata, "open", [
-        ...(modality === "spreadsheet" ? [] : ["modality"]),
+        "modality",
         "writable",
         "headSequence",
         "minimumReplaySequence",
@@ -669,15 +725,18 @@ export function decodeEditableArtifactLiveServerWireFrame(
         ),
         maxInFlightBytes: positiveInteger(metadata.maxInFlightBytes, "maxInFlightBytes"),
       } as const;
-      return Object.freeze(modality === "spreadsheet" ? common : { ...common, modality });
+      return Object.freeze({ ...common, modality });
     }
     case SERVER_SNAPSHOT: {
       const modality = serverModality(metadata);
       requireServerKeys(metadata, "snapshot", [
-        ...(modality === "spreadsheet" ? [] : ["modality"]),
+        "modality",
         "sequence",
         "stateHash",
         modality === "spreadsheet" ? "causalFrontier" : "nativeRevision",
+        ...(modality === "spreadsheet"
+          ? (["operationProtocolVersion", "snapshotVersion"] as const)
+          : []),
         "digest",
         "kernelVersion",
         "modelSchemaVersion",
@@ -714,7 +773,13 @@ export function decodeEditableArtifactLiveServerWireFrame(
         modality === "spreadsheet"
           ? {
               ...common,
+              modality,
               causalFrontier: requiredFrontier(metadata.causalFrontier),
+              operationProtocolVersion: positiveInteger(
+                metadata.operationProtocolVersion,
+                "operationProtocolVersion",
+              ),
+              snapshotVersion: positiveInteger(metadata.snapshotVersion, "snapshotVersion"),
             }
           : {
               ...common,
@@ -732,6 +797,7 @@ export function decodeEditableArtifactLiveServerWireFrame(
         modality === "spreadsheet"
           ? [
               "artifactId",
+              "modality",
               "transactionId",
               "requestHash",
               "startSequence",
@@ -739,7 +805,7 @@ export function decodeEditableArtifactLiveServerWireFrame(
               "priorStateHash",
               "stateHash",
               "causalFrontier",
-              "protocolVersion",
+              "operationProtocolVersion",
             ]
           : [
               "artifactId",
@@ -787,8 +853,12 @@ export function decodeEditableArtifactLiveServerWireFrame(
           modality === "spreadsheet"
             ? {
                 ...common.transaction,
+                modality,
                 causalFrontier: requiredFrontier(transaction.causalFrontier),
-                protocolVersion: positiveInteger(transaction.protocolVersion, "protocolVersion"),
+                operationProtocolVersion: positiveInteger(
+                  transaction.operationProtocolVersion,
+                  "operationProtocolVersion",
+                ),
               }
             : {
                 ...common.transaction,
@@ -923,6 +993,7 @@ function decodeOpen(
           "protocolVersion",
           "artifactId",
           "token",
+          "modality",
           "localCursor",
           "localStateHash",
           "localCausalFrontier",
@@ -1125,12 +1196,13 @@ function normalizeResume(resume: EditableArtifactLiveResume): EditableArtifactLi
   if ((localCursor === null) !== (localStateHash === null)) {
     throw invalidFrame("resume cursor and state hash must both be null or both be present");
   }
-  const modality = resume.modality ?? "spreadsheet";
+  const modality = editableArtifactLiveModality(resume.modality);
   if (modality === "spreadsheet") {
     if (!("localCausalFrontier" in resume)) {
       throw invalidFrame("spreadsheet resume requires a causal frontier");
     }
     return Object.freeze({
+      modality,
       localCursor,
       localStateHash,
       localCausalFrontier: requiredFrontier(resume.localCausalFrontier),
@@ -1176,23 +1248,17 @@ function editableArtifactLiveModality(value: unknown): EditableArtifactLiveModal
 function clientOpenModality(
   metadata: Readonly<Record<string, unknown>>,
 ): EditableArtifactLiveModality {
-  return metadata.modality === undefined
-    ? "spreadsheet"
-    : editableArtifactLiveModality(metadata.modality);
+  return editableArtifactLiveModality(metadata.modality);
 }
 
 function serverModality(metadata: Readonly<Record<string, unknown>>): EditableArtifactLiveModality {
-  return metadata.modality === undefined
-    ? "spreadsheet"
-    : editableArtifactLiveModality(metadata.modality);
+  return editableArtifactLiveModality(metadata.modality);
 }
 
 function transactionModality(
   transaction: Readonly<Record<string, unknown>>,
 ): EditableArtifactLiveModality {
-  return transaction.modality === undefined
-    ? "spreadsheet"
-    : editableArtifactLiveModality(transaction.modality);
+  return editableArtifactLiveModality(transaction.modality);
 }
 
 function requireExactKeys(

package/src/editable-artifact-serialized-commit.ts

@@ -22,8 +22,9 @@ import {
   type EditableArtifactMutationIntent,
 } from "./editable-artifacts";
 import { editableArtifactCodecFor } from "./editable-artifact-codec-registry";
+import { EDITABLE_ARTIFACT_SERIALIZED_COMMIT_VERSION } from "./editable-artifact-versions";
 
-export const EDITABLE_ARTIFACT_SERIALIZED_COMMIT_VERSION = 1 as const;
+export { EDITABLE_ARTIFACT_SERIALIZED_COMMIT_VERSION } from "./editable-artifact-versions";
 export const EDITABLE_ARTIFACT_SERIALIZED_COMMIT_MAX_BYTES = 8 * 1024 * 1024;
 export const EDITABLE_ARTIFACT_NATIVE_RECEIPT_MAX_BYTES = 512 * 1024;
 

package/src/editable-artifact-versions.ts

@@ -1,8 +1,29 @@
-/** Shared durable model version without importing any modality codec. */
-export const EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION = 1 as const;
+/** Modality-specific durable semantic/schema versions. */
+export const SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION = 2 as const;
+export const DOCUMENT_ARTIFACT_MODEL_SCHEMA_VERSION = 1 as const;
+export const PRESENTATION_ARTIFACT_MODEL_SCHEMA_VERSION = 1 as const;
 
-/** Shared native snapshot version without importing any modality codec. */
-export const EDITABLE_ARTIFACT_SNAPSHOT_VERSION = 1 as const;
+/** Direct kernel workbook snapshot version (OGARTK02), never the durable CRDT snapshot. */
+export const SPREADSHEET_KERNEL_SNAPSHOT_VERSION = 2 as const;
+
+/** Modality-specific canonical snapshot versions. */
+export const DOCUMENT_ARTIFACT_SNAPSHOT_VERSION = 1 as const;
+export const PRESENTATION_ARTIFACT_SNAPSHOT_VERSION = 1 as const;
+
+/** Canonical internal spreadsheet kernel command-envelope version. */
+export const SPREADSHEET_KERNEL_COMMAND_VERSION = 2 as const;
+
+/** Canonical public, identity-free spreadsheet command-envelope version. */
+export const SPREADSHEET_ARTIFACT_COMMAND_VERSION = 2 as const;
+
+/** Canonical durable spreadsheet collaboration-snapshot version. */
+export const SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION = 2 as const;
 
 /** Canonical committed spreadsheet transaction protocol version. */
-export const COMMITTED_TRANSACTION_PROTOCOL_VERSION = 1 as const;
+export const COMMITTED_TRANSACTION_PROTOCOL_VERSION = 2 as const;
+
+/** Canonical document/presentation serialized-commit protocol version. */
+export const EDITABLE_ARTIFACT_SERIALIZED_COMMIT_VERSION = 1 as const;
+
+/** Canonical editable-artifact live transport protocol version. */
+export const EDITABLE_ARTIFACT_LIVE_WIRE_VERSION = 2 as const;

package/src/editable-artifacts.ts

@@ -9,6 +9,8 @@ export * from "./presentation-artifact-commands";
 export * from "./editable-artifact-codec-registry";
 
 export const EDITABLE_ARTIFACT_INTENT_VERSION = 1 as const;
+/** Semantic protocol carried inside the unchanged OGATX001 envelope. */
+export const EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION = 1 as const;
 export const EDITABLE_ARTIFACT_INTENT_MAX_BYTES = 5 * 1024 * 1024;
 export const EDITABLE_ARTIFACT_COMMAND_MAX_BYTES = 4 * 1024 * 1024;
 export const EDITABLE_ARTIFACT_KERNEL_VERSION_MAX_BYTES = 512;