@opengeni/contracts 0.50.0 → 2.2.0-canary.0

package/src/connector-attachments.ts

@@ -0,0 +1,327 @@
+import { z } from "zod";
+
+export const CONNECTOR_ATTACHMENT_TRANSFER_VERSION = 1 as const;
+export const CONNECTOR_ATTACHMENT_RECEIPT_VERSION = 1 as const;
+export const CONNECTOR_ATTACHMENT_TRANSFER_META_KEY =
+  "opengeni/connector-attachment-transfers" as const;
+export const CONNECTOR_ATTACHMENT_RECEIPT_META_KEY =
+  "opengeni/connector-attachment-receipts" as const;
+export const CONNECTOR_ATTACHMENT_MAX_COUNT = 16;
+// Must remain byte-for-byte aligned with Channel A's exact workspace importer.
+export const CONNECTOR_ATTACHMENT_MAX_BYTES = 5_000_000_000;
+export const CONNECTOR_ATTACHMENT_FILENAME_MAX_UTF8_BYTES = 255;
+export const CONNECTOR_ATTACHMENT_MEDIA_TYPE_MAX_UTF8_BYTES = 256;
+export const CONNECTOR_ATTACHMENT_PROVIDER_MAX_UTF8_BYTES = 128;
+export const CONNECTOR_ATTACHMENT_PROVIDER_ID_MAX_UTF8_BYTES = 512;
+export const CONNECTOR_ATTACHMENT_SOURCE_URL_MAX_UTF8_BYTES = 8 * 1024;
+export const CONNECTOR_ATTACHMENT_SANDBOX_PATH_MAX_UTF8_BYTES = 2 * 1024;
+
+const PROVIDER_PATTERN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/u;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const MEDIA_TYPE_PATTERN =
+  /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+(?:\s*;\s*[a-z0-9!#$&^_.+-]+=(?:[a-z0-9!#$&^_.+-]+|"[^"\r\n]*"))*$/iu;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/u;
+const HTTP_URL_REFERENCE_PATTERN = /(?:https?:)?\/\/[^\s]/iu;
+const PORTABLE_FILENAME_FORBIDDEN_PATTERN = /[<>:"|?*]/u;
+const PORTABLE_FILENAME_RESERVED_PATTERN = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu;
+const textEncoder = new TextEncoder();
+
+function utf8Bytes(value: string): number {
+  return textEncoder.encode(value).byteLength;
+}
+
+function boundedString(maxUtf8Bytes: number) {
+  return z.string().refine((value) => utf8Bytes(value) <= maxUtf8Bytes, {
+    message: `must be at most ${maxUtf8Bytes} UTF-8 bytes`,
+  });
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function containsHttpUrlReference(value: string): boolean {
+  return HTTP_URL_REFERENCE_PATTERN.test(value);
+}
+
+function isPrivateUrlCredentialQueryName(value: string): boolean {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9]/gu, "");
+  return (
+    normalized === "sig" ||
+    normalized === "auth" ||
+    normalized.endsWith("signature") ||
+    normalized.endsWith("token") ||
+    normalized.endsWith("credential") ||
+    normalized.endsWith("secret") ||
+    normalized.endsWith("password") ||
+    normalized.endsWith("passcode") ||
+    normalized.endsWith("authorization") ||
+    normalized.endsWith("apikey") ||
+    normalized.endsWith("accesskey") ||
+    normalized.endsWith("securitytoken") ||
+    normalized.endsWith("sas") ||
+    normalized === "googleaccessid"
+  );
+}
+
+function privateUrlCredentialValues(value: string): string[] {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return [];
+  }
+  const credentials = new Set<string>();
+  for (const [name, credential] of parsed.searchParams) {
+    if (credential && isPrivateUrlCredentialQueryName(name)) credentials.add(credential);
+  }
+  for (const pair of parsed.search.slice(1).split("&")) {
+    if (!pair) continue;
+    const separator = pair.indexOf("=");
+    const rawName = separator === -1 ? pair : pair.slice(0, separator);
+    const rawCredential = separator === -1 ? "" : pair.slice(separator + 1);
+    let decodedName: string;
+    try {
+      decodedName = decodeURIComponent(rawName.replace(/\+/gu, " "));
+    } catch {
+      continue;
+    }
+    if (rawCredential && isPrivateUrlCredentialQueryName(decodedName)) {
+      credentials.add(rawCredential);
+    }
+  }
+  return [...credentials];
+}
+
+function publicMetadataContainsCredential(publicValue: string, credential: string): boolean {
+  return publicValue.includes(credential);
+}
+
+export const ConnectorAttachmentProviderIdentity = z
+  .object({
+    provider: boundedString(CONNECTOR_ATTACHMENT_PROVIDER_MAX_UTF8_BYTES).regex(PROVIDER_PATTERN),
+    kind: z.literal("attachment"),
+    value: boundedString(CONNECTOR_ATTACHMENT_PROVIDER_ID_MAX_UTF8_BYTES)
+      .min(1)
+      .refine((value) => !CONTROL_CHARACTER_PATTERN.test(value), {
+        message: "must not contain control characters",
+      })
+      .refine((value) => !isHttpUrl(value) && !containsHttpUrlReference(value), {
+        message: "must be an opaque provider attachment identity, not a URL",
+      }),
+  })
+  .strict();
+export type ConnectorAttachmentProviderIdentity = z.infer<
+  typeof ConnectorAttachmentProviderIdentity
+>;
+
+export const ConnectorAttachmentFileName = boundedString(
+  CONNECTOR_ATTACHMENT_FILENAME_MAX_UTF8_BYTES,
+)
+  .min(1)
+  .refine(
+    (value) =>
+      value !== "." &&
+      value !== ".." &&
+      value === value.trim() &&
+      !value.includes("/") &&
+      !value.includes("\\") &&
+      !CONTROL_CHARACTER_PATTERN.test(value) &&
+      !PORTABLE_FILENAME_FORBIDDEN_PATTERN.test(value) &&
+      !/[ .]$/u.test(value) &&
+      !PORTABLE_FILENAME_RESERVED_PATTERN.test(value),
+    { message: "must be a safe leaf filename" },
+  );
+
+export const ConnectorAttachmentMediaType = boundedString(
+  CONNECTOR_ATTACHMENT_MEDIA_TYPE_MAX_UTF8_BYTES,
+)
+  .regex(MEDIA_TYPE_PATTERN)
+  .refine((value) => !containsHttpUrlReference(value), {
+    message: "must not contain an HTTP URL reference",
+  });
+
+export const ConnectorAttachmentSha256 = z.string().regex(SHA256_PATTERN);
+
+export const ConnectorAttachmentPrivateSource = z
+  .object({
+    url: boundedString(CONNECTOR_ATTACHMENT_SOURCE_URL_MAX_UTF8_BYTES).superRefine(
+      (value, context) => {
+        let parsed: URL;
+        try {
+          parsed = new URL(value);
+        } catch {
+          context.addIssue({
+            code: "custom",
+            message: "must be an absolute URL",
+          });
+          return;
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+          context.addIssue({ code: "custom", message: "must use http or https" });
+        }
+        if (parsed.username || parsed.password) {
+          context.addIssue({
+            code: "custom",
+            message: "must not contain URL userinfo",
+          });
+        }
+        if (parsed.hash) {
+          context.addIssue({
+            code: "custom",
+            message: "must not contain a URL fragment",
+          });
+        }
+      },
+    ),
+    expiresAt: z.iso.datetime({ offset: true }),
+  })
+  .strict();
+export type ConnectorAttachmentPrivateSource = z.infer<typeof ConnectorAttachmentPrivateSource>;
+
+export const ConnectorAttachmentTransfer = z
+  .object({
+    providerAttachmentId: ConnectorAttachmentProviderIdentity,
+    fileName: ConnectorAttachmentFileName,
+    mediaType: ConnectorAttachmentMediaType,
+    byteSize: z.number().int().min(0).max(CONNECTOR_ATTACHMENT_MAX_BYTES),
+    contentSha256: ConnectorAttachmentSha256,
+    source: ConnectorAttachmentPrivateSource,
+  })
+  .strict()
+  .superRefine((attachment, context) => {
+    const publicValues = [
+      attachment.providerAttachmentId.value,
+      attachment.fileName,
+      attachment.mediaType,
+    ];
+    for (const credential of privateUrlCredentialValues(attachment.source.url)) {
+      if (publicValues.some((value) => publicMetadataContainsCredential(value, credential))) {
+        context.addIssue({
+          code: "custom",
+          message: "private source credentials must not appear in public attachment metadata",
+        });
+        return;
+      }
+    }
+  });
+export type ConnectorAttachmentTransfer = z.infer<typeof ConnectorAttachmentTransfer>;
+
+export const ConnectorAttachmentTransferEnvelope = z
+  .object({
+    version: z.literal(CONNECTOR_ATTACHMENT_TRANSFER_VERSION),
+    attachments: z.array(ConnectorAttachmentTransfer).min(1).max(CONNECTOR_ATTACHMENT_MAX_COUNT),
+  })
+  .strict()
+  .superRefine((envelope, context) => {
+    const identities = new Set<string>();
+    for (const [index, attachment] of envelope.attachments.entries()) {
+      const identity = `${attachment.providerAttachmentId.provider}\0${attachment.providerAttachmentId.value}`;
+      if (identities.has(identity)) {
+        context.addIssue({
+          code: "custom",
+          message: "provider attachment identities must be unique",
+          path: ["attachments", index, "providerAttachmentId"],
+        });
+      }
+      identities.add(identity);
+    }
+  });
+export type ConnectorAttachmentTransferEnvelope = z.infer<
+  typeof ConnectorAttachmentTransferEnvelope
+>;
+
+export const ConnectorAttachmentSandboxPath = boundedString(
+  CONNECTOR_ATTACHMENT_SANDBOX_PATH_MAX_UTF8_BYTES,
+)
+  .min(1)
+  .refine(
+    (value) => {
+      if (
+        value !== value.trim() ||
+        value.startsWith("/") ||
+        /^[A-Za-z]:[\\/]/u.test(value) ||
+        value.includes("\\") ||
+        CONTROL_CHARACTER_PATTERN.test(value)
+      ) {
+        return false;
+      }
+      const segments = value.split("/");
+      if (
+        segments.length !== 5 ||
+        segments[0] !== ".opengeni" ||
+        segments[1] !== "connector-attachments" ||
+        !PROVIDER_PATTERN.test(segments[2] ?? "") ||
+        !/^[0-9a-f]{32}$/u.test(segments[3] ?? "") ||
+        !ConnectorAttachmentFileName.safeParse(segments[4]).success
+      ) {
+        return false;
+      }
+      return segments.every(
+        (segment) =>
+          segment.length > 0 &&
+          segment !== "." &&
+          segment !== ".." &&
+          !PORTABLE_FILENAME_FORBIDDEN_PATTERN.test(segment) &&
+          !/[ .]$/u.test(segment) &&
+          !PORTABLE_FILENAME_RESERVED_PATTERN.test(segment),
+      );
+    },
+    { message: "must be a confined connector attachment sandbox path" },
+  );
+
+export const ConnectorAttachmentReceipt = z
+  .object({
+    providerAttachmentId: ConnectorAttachmentProviderIdentity,
+    fileName: ConnectorAttachmentFileName,
+    mediaType: ConnectorAttachmentMediaType,
+    byteSize: z.number().int().min(0).max(CONNECTOR_ATTACHMENT_MAX_BYTES),
+    contentSha256: ConnectorAttachmentSha256,
+    sandboxPath: ConnectorAttachmentSandboxPath,
+  })
+  .strict()
+  .superRefine((receipt, context) => {
+    const segments = receipt.sandboxPath.split("/");
+    if (segments[2] !== receipt.providerAttachmentId.provider) {
+      context.addIssue({
+        code: "custom",
+        message: "sandbox path provider must match the provider attachment identity",
+        path: ["sandboxPath"],
+      });
+    }
+    if (segments[4] !== receipt.fileName) {
+      context.addIssue({
+        code: "custom",
+        message: "sandbox path filename must match the attachment filename",
+        path: ["sandboxPath"],
+      });
+    }
+  });
+export type ConnectorAttachmentReceipt = z.infer<typeof ConnectorAttachmentReceipt>;
+
+export const ConnectorAttachmentReceiptEnvelope = z
+  .object({
+    version: z.literal(CONNECTOR_ATTACHMENT_RECEIPT_VERSION),
+    attachments: z.array(ConnectorAttachmentReceipt).min(1).max(CONNECTOR_ATTACHMENT_MAX_COUNT),
+  })
+  .strict();
+export type ConnectorAttachmentReceiptEnvelope = z.infer<typeof ConnectorAttachmentReceiptEnvelope>;
+
+export function parseConnectorAttachmentTransferEnvelope(
+  value: unknown,
+  options: { nowMs?: number } = {},
+): ConnectorAttachmentTransferEnvelope {
+  const envelope = ConnectorAttachmentTransferEnvelope.parse(value);
+  const nowMs = options.nowMs ?? Date.now();
+  for (const attachment of envelope.attachments) {
+    if (Date.parse(attachment.source.expiresAt) <= nowMs) {
+      throw new Error("connector attachment source is expired");
+    }
+  }
+  return envelope;
+}

package/src/editable-artifact-codec-registry.ts

@@ -54,13 +54,24 @@ import {
   encodeSpreadsheetArtifactKernelQuery,
 } from "./spreadsheet-artifact-query";
 import {
-  EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,
-  EDITABLE_ARTIFACT_SNAPSHOT_VERSION,
+  DOCUMENT_ARTIFACT_MODEL_SCHEMA_VERSION,
+  DOCUMENT_ARTIFACT_SNAPSHOT_VERSION,
+  EDITABLE_ARTIFACT_LIVE_WIRE_VERSION,
+  EDITABLE_ARTIFACT_SERIALIZED_COMMIT_VERSION,
+  PRESENTATION_ARTIFACT_MODEL_SCHEMA_VERSION,
+  PRESENTATION_ARTIFACT_SNAPSHOT_VERSION,
+  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+  SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
+  SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
 } from "./editable-artifact-versions";
 
 export {
-  EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,
-  EDITABLE_ARTIFACT_SNAPSHOT_VERSION,
+  DOCUMENT_ARTIFACT_MODEL_SCHEMA_VERSION,
+  DOCUMENT_ARTIFACT_SNAPSHOT_VERSION,
+  PRESENTATION_ARTIFACT_MODEL_SCHEMA_VERSION,
+  PRESENTATION_ARTIFACT_SNAPSHOT_VERSION,
+  SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
+  SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
 } from "./editable-artifact-versions";
 
 export type EditableArtifactModality = "spreadsheet" | "document" | "presentation";
@@ -68,13 +79,22 @@ export type EditableArtifactConcurrencySemantics =
   | "causal-crdt-v1"
   | "authoritative-serialized-stale-base-v1";
 
+export type CurrentEditableArtifactCompatibility = Readonly<{
+  modality: EditableArtifactModality;
+  liveProtocolVersion: number;
+  modelSchemaVersion: number;
+  snapshotVersion: number;
+  commandProtocolVersion: number;
+  committedTransactionProtocolVersion: number;
+}>;
+
 export type EditableArtifactCodecDescriptor = Readonly<{
   modality: EditableArtifactModality;
-  modelSchemaVersion: typeof EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION;
-  snapshotVersion: typeof EDITABLE_ARTIFACT_SNAPSHOT_VERSION;
+  modelSchemaVersion: 1 | 2;
+  snapshotVersion: 1 | 2;
   command: Readonly<{
-    magic: "OGASC001" | "OGADC001" | "OGAPC001";
-    version: 1;
+    magic: "OGASC002" | "OGADC001" | "OGAPC001";
+    version: 1 | 2;
     maximumBytes: number;
     maximumCommands: number;
     encode: (value: unknown) => Uint8Array;
@@ -97,17 +117,17 @@ export type EditableArtifactCodecDescriptor = Readonly<{
   }>;
   concurrency: Readonly<{
     semantics: EditableArtifactConcurrencySemantics;
-    collaborationEnvelope: "OGACO001" | null;
+    collaborationEnvelope: "OGACO002" | null;
     staleBaseMustBeRejected: boolean;
   }>;
 }>;
 
 const spreadsheet = Object.freeze({
   modality: "spreadsheet",
-  modelSchemaVersion: 1,
-  snapshotVersion: 1,
+  modelSchemaVersion: SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
+  snapshotVersion: SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
   command: Object.freeze({
-    magic: "OGASC001",
+    magic: "OGASC002",
     version: SPREADSHEET_ARTIFACT_COMMAND_VERSION,
     maximumBytes: SPREADSHEET_ARTIFACT_COMMAND_MAX_BYTES,
     maximumCommands: SPREADSHEET_ARTIFACT_COMMAND_MAX_COMMANDS,
@@ -140,15 +160,15 @@ const spreadsheet = Object.freeze({
   }),
   concurrency: Object.freeze({
     semantics: "causal-crdt-v1",
-    collaborationEnvelope: "OGACO001",
+    collaborationEnvelope: "OGACO002",
     staleBaseMustBeRejected: false,
   }),
 }) satisfies EditableArtifactCodecDescriptor;
 
 const document = Object.freeze({
   modality: "document",
-  modelSchemaVersion: 1,
-  snapshotVersion: 1,
+  modelSchemaVersion: DOCUMENT_ARTIFACT_MODEL_SCHEMA_VERSION,
+  snapshotVersion: DOCUMENT_ARTIFACT_SNAPSHOT_VERSION,
   command: Object.freeze({
     magic: "OGADC001",
     version: DOCUMENT_ARTIFACT_COMMAND_VERSION,
@@ -188,8 +208,8 @@ const document = Object.freeze({
 
 const presentation = Object.freeze({
   modality: "presentation",
-  modelSchemaVersion: 1,
-  snapshotVersion: 1,
+  modelSchemaVersion: PRESENTATION_ARTIFACT_MODEL_SCHEMA_VERSION,
+  snapshotVersion: PRESENTATION_ARTIFACT_SNAPSHOT_VERSION,
   command: Object.freeze({
     magic: "OGAPC001",
     version: PRESENTATION_ARTIFACT_COMMAND_VERSION,
@@ -233,6 +253,24 @@ export const EDITABLE_ARTIFACT_CODEC_REGISTRY: Readonly<
   Record<EditableArtifactModality, EditableArtifactCodecDescriptor>
 > = Object.freeze({ spreadsheet, document, presentation });
 
+/** One exact current compatibility tuple per durable modality. */
+export function currentEditableArtifactCompatibility(
+  modality: EditableArtifactModality,
+): CurrentEditableArtifactCompatibility {
+  const descriptor = EDITABLE_ARTIFACT_CODEC_REGISTRY[modality];
+  return Object.freeze({
+    modality,
+    liveProtocolVersion: EDITABLE_ARTIFACT_LIVE_WIRE_VERSION,
+    modelSchemaVersion: descriptor.modelSchemaVersion,
+    snapshotVersion: descriptor.snapshotVersion,
+    commandProtocolVersion: descriptor.command.version,
+    committedTransactionProtocolVersion:
+      modality === "spreadsheet"
+        ? COMMITTED_TRANSACTION_PROTOCOL_VERSION
+        : EDITABLE_ARTIFACT_SERIALIZED_COMMIT_VERSION,
+  });
+}
+
 /**
  * Selects solely from the durable artifact modality plus persisted versions.
  * Modality intentionally never enters OGATX001: the durable artifact row is

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");
   }
 }