@opengeni/sdk 1.0.1 → 2.3.0-canary.0

package/src/codex-realtime-controller.ts

@@ -50,6 +50,7 @@ export const CODEX_REALTIME_NEGOTIATION_TIMEOUT_MS = 20_000;
 // OpenGeni policy: rotate conservatively without asserting an upstream lifetime.
 const DEFAULT_CONNECTION_ROTATION_INTERVAL_MS = 15 * 60_000;
 const DEFAULT_RECONNECT_BACKOFF_MS = [250, 1_000, 2_000, 5_000] as const;
+const MAX_BROWSER_TIMEOUT_MS = 2_147_483_647;
 const OWNER_RECORD_VERSION = 1;
 const OWNER_DELEGATION_REPLAY_VERSION = 1;
 const OWNER_DELEGATION_REPLAY_MAX_CALLS = 4_096;
@@ -224,6 +225,7 @@ export type CreateCodexRealtimeControllerOptions = {
   createPeerConnection?: (() => RTCPeerConnection) | undefined;
   getUserMedia?: ((constraints: MediaStreamConstraints) => Promise<MediaStream>) | undefined;
   randomUUID?: (() => string) | undefined;
+  now?: (() => Date) | undefined;
   setInterval?: ((callback: () => void, delayMs: number) => unknown) | undefined;
   clearInterval?: ((handle: unknown) => void) | undefined;
   setTimeout?: ((callback: () => void, delayMs: number) => unknown) | undefined;
@@ -316,6 +318,7 @@ export function createCodexRealtimeController(
   );
   const model = options.model ?? "gpt-live-1-boulder-alpha";
   const randomUUID = options.randomUUID ?? defaultRandomUUID;
+  const now = options.now ?? (() => new Date());
   const scheduleInterval =
     options.setInterval ?? ((callback, delay) => globalThis.setInterval(callback, delay));
   const unscheduleInterval =
@@ -362,6 +365,7 @@ export function createCodexRealtimeController(
   let rotationTimer: unknown = null;
   let reconnectTimer: unknown = null;
   let negotiationTimer: unknown = null;
+  let lostOwnerExpiryTimer: unknown = null;
   let closed = false;
   let stopping = false;
   let generation = 0;
@@ -456,11 +460,13 @@ export function createCodexRealtimeController(
     if (rotationTimer !== null) unscheduleTimeout(rotationTimer);
     if (reconnectTimer !== null) unscheduleTimeout(reconnectTimer);
     if (negotiationTimer !== null) unscheduleTimeout(negotiationTimer);
+    if (lostOwnerExpiryTimer !== null) unscheduleTimeout(lostOwnerExpiryTimer);
     heartbeatTimer = null;
     syncTimer = null;
     rotationTimer = null;
     reconnectTimer = null;
     negotiationTimer = null;
+    lostOwnerExpiryTimer = null;
   };
 
   const stopNegotiationTimers = (): void => {
@@ -1255,6 +1261,12 @@ export function createCodexRealtimeController(
       if (!record || record.operationId !== lifecycle.operationId) {
         closeBrowserResources();
         owner = null;
+        const leaseExpiresAt = Date.parse(lifecycle.leaseExpiresAt);
+        const remainingLeaseMs = leaseExpiresAt - now().getTime();
+        if (Number.isFinite(remainingLeaseMs) && remainingLeaseMs <= 0) {
+          transitionEnded("Realtime lease expired");
+          return;
+        }
         const message =
           "Realtime is active in another browser owner. It can resume after that owner stops or its lease expires.";
         publish({
@@ -1265,6 +1277,15 @@ export function createCodexRealtimeController(
           diagnostic: diagnostic("lost_owner", message, false),
           error: message,
         });
+        if (Number.isFinite(remainingLeaseMs) && remainingLeaseMs <= MAX_BROWSER_TIMEOUT_MS) {
+          const observedRealtimeId = lifecycle.realtimeId;
+          lostOwnerExpiryTimer = scheduleTimeout(() => {
+            lostOwnerExpiryTimer = null;
+            if (state.status === "lost_owner" && state.realtimeId === observedRealtimeId) {
+              transitionEnded("Realtime lease expired");
+            }
+          }, remainingLeaseMs);
+        }
         return;
       }
       if (connectionTask || state.status === "starting") return;

package/src/company-brain.ts

@@ -0,0 +1,99 @@
+import type {
+  CompanyBrainContextReceiptPage as ContractCompanyBrainContextReceiptPage,
+  CompanyBrainKnowledgeProposalPage as ContractCompanyBrainKnowledgeProposalPage,
+  CompanyBrainOkfPackage as ContractCompanyBrainOkfPackage,
+  KnowledgeBrowseRequest as ContractKnowledgeBrowseRequest,
+  KnowledgeBrowseResponse as ContractKnowledgeBrowseResponse,
+  KnowledgeGetResponse as ContractKnowledgeGetResponse,
+  KnowledgeRecord as ContractKnowledgeRecord,
+  KnowledgeSearchRequest as ContractKnowledgeSearchRequest,
+  KnowledgeSearchResponse as ContractKnowledgeSearchResponse,
+} from "@opengeni/contracts";
+
+export type CompanyBrainOkfPackage = ContractCompanyBrainOkfPackage;
+export type CompanyBrainContextReceiptPage = ContractCompanyBrainContextReceiptPage;
+export type CompanyBrainKnowledgeProposalPage = ContractCompanyBrainKnowledgeProposalPage;
+export type CompanyBrainKnowledgeSearchRequest = ContractKnowledgeSearchRequest;
+export type CompanyBrainKnowledgeSearchResponse = ContractKnowledgeSearchResponse;
+export type CompanyBrainKnowledgeBrowseRequest = ContractKnowledgeBrowseRequest;
+export type CompanyBrainKnowledgeBrowseResponse = ContractKnowledgeBrowseResponse;
+export type CompanyBrainKnowledgeGetResponse = ContractKnowledgeGetResponse;
+export type CompanyBrainKnowledgeRecord = ContractKnowledgeRecord;
+
+export type CompanyBrainContextReceiptListOptions = {
+  attemptId?: string;
+  cursor?: string;
+  limit?: number;
+};
+
+export type CompanyBrainKnowledgeProposalListOptions = {
+  limit?: number;
+};
+
+export type CompanyBrainInspectorTransport = {
+  requestJson<T>(method: string, path: string, body?: unknown): Promise<T>;
+};
+
+function inspectorPath(workspaceId: string, suffix: string): string {
+  return `/v1/workspaces/${workspaceId}/company-brain/${suffix}`;
+}
+
+/** Human-authorized, permission-first Knowledge search for Company Brain inspectors. */
+export function searchCompanyBrainKnowledge(
+  client: CompanyBrainInspectorTransport,
+  workspaceId: string,
+  request: CompanyBrainKnowledgeSearchRequest,
+): Promise<CompanyBrainKnowledgeSearchResponse> {
+  return client.requestJson("POST", inspectorPath(workspaceId, "knowledge/search"), request);
+}
+
+export function getCompanyBrainKnowledge(
+  client: CompanyBrainInspectorTransport,
+  workspaceId: string,
+  recordId: string,
+): Promise<CompanyBrainKnowledgeGetResponse> {
+  return client.requestJson(
+    "GET",
+    `${inspectorPath(workspaceId, "knowledge/record")}?id=${encodeURIComponent(recordId)}`,
+  );
+}
+
+export function browseCompanyBrainKnowledge(
+  client: CompanyBrainInspectorTransport,
+  workspaceId: string,
+  request: CompanyBrainKnowledgeBrowseRequest = {},
+): Promise<CompanyBrainKnowledgeBrowseResponse> {
+  return client.requestJson("POST", inspectorPath(workspaceId, "knowledge/browse"), request);
+}
+
+export function listCompanyBrainContextReceipts(
+  client: CompanyBrainInspectorTransport,
+  workspaceId: string,
+  options: CompanyBrainContextReceiptListOptions = {},
+): Promise<CompanyBrainContextReceiptPage> {
+  const params = new URLSearchParams();
+  if (options.attemptId) params.set("attemptId", options.attemptId);
+  if (options.cursor) params.set("cursor", options.cursor);
+  if (options.limit !== undefined) params.set("limit", String(options.limit));
+  const query = params.toString();
+  return client.requestJson(
+    "GET",
+    `${inspectorPath(workspaceId, "context-receipts")}${query ? `?${query}` : ""}`,
+  );
+}
+
+export function listCompanyBrainKnowledgeProposals(
+  client: CompanyBrainInspectorTransport,
+  workspaceId: string,
+  options: CompanyBrainKnowledgeProposalListOptions = {},
+): Promise<CompanyBrainKnowledgeProposalPage> {
+  const query =
+    options.limit === undefined ? "" : `?limit=${encodeURIComponent(String(options.limit))}`;
+  return client.requestJson("GET", `${inspectorPath(workspaceId, "knowledge-proposals")}${query}`);
+}
+
+export type CompanyBrainOkfDownload = {
+  content: string;
+  contentType: string;
+  filename: string;
+};

package/src/company-profile.ts

@@ -21,7 +21,10 @@ export type CompanyProfileRevision = CompanyProfileRevisionIdentity & {
   accountId: string;
   intent: "active" | "proposal";
   profile: CompanyProfileContent;
-  provenance: { source: "human" | "durable_learning" | "migration"; sourceId: string | null };
+  provenance: {
+    source: "human" | "agent_admin" | "durable_learning" | "migration";
+    sourceId: string | null;
+  };
   supersedesRevisionId: string | null;
   createdBySubjectId: string;
   createdAt: string;

package/src/editable-artifacts/browser-session.ts

@@ -1,6 +1,8 @@
-import { DOCUMENT_ARTIFACT_COMMAND_VERSION } from "@opengeni/contracts/document-artifact-commands";
-import { PRESENTATION_ARTIFACT_COMMAND_VERSION } from "@opengeni/contracts/presentation-artifact-commands";
-import { SPREADSHEET_ARTIFACT_COMMAND_VERSION } from "@opengeni/contracts/spreadsheet-artifact-commands";
+import { EDITABLE_ARTIFACT_LIVE_WIRE_VERSION } from "@opengeni/contracts/editable-artifact-live";
+import {
+  EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION,
+  currentEditableArtifactCompatibility,
+} from "@opengeni/contracts/editable-artifacts";
 
 import type { EditableArtifactCacheAuthority } from "./controller";
 import {
@@ -10,6 +12,7 @@ import {
 import { createEditableArtifactSession, type EditableArtifactSession } from "./session";
 import type { EditableArtifactStoragePort } from "./storage";
 import type { EditableArtifactModality } from "./types";
+import type { EditableArtifactOpenFailureReporter } from "./open-failure";
 import {
   createBrowserEditableArtifactWorkerKernel,
   type CreateBrowserEditableArtifactWorkerKernelOptions,
@@ -20,10 +23,11 @@ export type EditableArtifactBrowserRuntime = Omit<
   "modality" | "kernelVersion" | "protocolVersion" | "modelSchemaVersion" | "commandVersion"
 > &
   Readonly<{
-    /** Exact native/WASM build identity admitted by the API. */
+    /** Exact package/executable build identity; the API records but does not compatibility-gate it. */
     kernelVersion: string;
     modelSchemaVersion: number;
-    protocolVersion?: number;
+    /** Exact OGATX001 intent protocol version. */
+    protocolVersion: number;
     commandVersion: number;
   }>;
 
@@ -36,11 +40,21 @@ export type CreateBrowserEditableArtifactSessionOptions = Readonly<{
   runtime: EditableArtifactBrowserRuntime;
   transport?: Omit<
     CreateEditableArtifactHttpLiveTransportOptions,
-    "baseUrl" | "workspaceId" | "protocolVersion" | "kernelVersion" | "modelSchemaVersion"
+    | "baseUrl"
+    | "workspaceId"
+    | "modality"
+    | "liveProtocolVersion"
+    | "kernelVersion"
+    | "modelSchemaVersion"
+    | "snapshotVersion"
+    | "commandProtocolVersion"
+    | "committedTransactionProtocolVersion"
   >;
   storage?: EditableArtifactStoragePort;
   /** Reuse the replica used to create the artifact when opening it immediately. */
   replicaId?: string;
+  /** Receives bounded categories/codes only; never workbook or formula content. */
+  onOpenFailure?: EditableArtifactOpenFailureReporter;
 }>;
 
 /**
@@ -53,17 +67,23 @@ export function createBrowserEditableArtifactSession(
   const baseUrl = canonicalBaseUrl(options.baseUrl);
   const workspaceId = boundedIdentity(options.workspaceId, "workspaceId");
   assertCacheAuthority(options.storageAuthority, baseUrl, workspaceId);
-  const protocolVersion = positiveVersion(options.runtime.protocolVersion ?? 1, "protocolVersion");
+  const protocolVersion = positiveVersion(options.runtime.protocolVersion, "protocolVersion");
+  if (protocolVersion !== EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION) {
+    throw new TypeError("protocolVersion is incompatible with the current intent protocol");
+  }
   const modelSchemaVersion = positiveVersion(
     options.runtime.modelSchemaVersion,
     "modelSchemaVersion",
   );
   const kernelVersion = boundedIdentity(options.runtime.kernelVersion, "kernelVersion", 512);
   const commandVersion = positiveVersion(options.runtime.commandVersion, "commandVersion");
-  const expectedCommandVersion = commandVersionFor(options.artifact.modality);
-  if (commandVersion !== expectedCommandVersion) {
+  const current = currentEditableArtifactCompatibility(options.artifact.modality);
+  if (
+    modelSchemaVersion !== current.modelSchemaVersion ||
+    commandVersion !== current.commandProtocolVersion
+  ) {
     throw new TypeError(
-      `commandVersion ${commandVersion} is incompatible with ${options.artifact.modality} ${expectedCommandVersion}`,
+      `runtime versions are incompatible with current ${options.artifact.modality} compatibility`,
     );
   }
   const {
@@ -87,9 +107,13 @@ export function createBrowserEditableArtifactSession(
       ...options.transport,
       baseUrl,
       workspaceId,
-      protocolVersion,
+      modality: options.artifact.modality,
+      liveProtocolVersion: EDITABLE_ARTIFACT_LIVE_WIRE_VERSION,
       kernelVersion,
       modelSchemaVersion,
+      snapshotVersion: current.snapshotVersion,
+      commandProtocolVersion: current.commandProtocolVersion,
+      committedTransactionProtocolVersion: current.committedTransactionProtocolVersion,
     });
     return createEditableArtifactSession({
       artifactId: options.artifact.id,
@@ -102,6 +126,7 @@ export function createBrowserEditableArtifactSession(
       modelSchemaVersion,
       commandVersion,
       protocolVersion,
+      ...(options.onOpenFailure ? { onOpenFailure: options.onOpenFailure } : {}),
       ...(replicaId ? { writerReplicaIdFactory: () => replicaId } : {}),
       ownsWorker: true,
     });
@@ -121,17 +146,6 @@ export function createEditableArtifactReplicaId(): string {
   }
 }
 
-function commandVersionFor(modality: EditableArtifactModality): number {
-  switch (modality) {
-    case "spreadsheet":
-      return SPREADSHEET_ARTIFACT_COMMAND_VERSION;
-    case "document":
-      return DOCUMENT_ARTIFACT_COMMAND_VERSION;
-    case "presentation":
-      return PRESENTATION_ARTIFACT_COMMAND_VERSION;
-  }
-}
-
 function canonicalBaseUrl(value: string | URL): URL {
   const url = new URL(value);
   if (url.username || url.password || url.search || url.hash) {

package/src/editable-artifacts/controller.ts

@@ -2,16 +2,24 @@ import {
   decodeEditableArtifactMutationIntent,
   EDITABLE_ARTIFACT_COMMAND_MAX_BYTES,
   EDITABLE_ARTIFACT_INTENT_MAX_BYTES,
+  EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION,
   EDITABLE_ARTIFACT_PRODUCT_MAX_SNAPSHOT_BYTES,
   hashEditableArtifactMutationIntentBytes,
 } from "@opengeni/contracts/editable-artifacts";
 import {
+  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
   decodeCommittedTransactionSummary,
   MAX_COMMITTED_TRANSACTION_BYTES,
 } from "@opengeni/contracts/editable-artifact-committed-transaction";
 import { editableArtifactCodecFor } from "@opengeni/contracts/editable-artifact-codec-registry";
+import { EDITABLE_ARTIFACT_LIVE_WIRE_VERSION } from "@opengeni/contracts/editable-artifact-live";
 import { decodeEditableArtifactSerializedCommit } from "@opengeni/contracts/editable-artifact-serialized-commit";
+import { SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION } from "@opengeni/contracts/editable-artifact-versions";
 import { EditableArtifactSyncError } from "./errors";
+import {
+  classifyEditableArtifactOpenFailure,
+  type EditableArtifactOpenFailureReporter,
+} from "./open-failure";
 import { EditableArtifactStorageConflictError } from "./storage";
 import type { EditableArtifactStoragePort, EditableArtifactStorageScope } from "./storage";
 import type {
@@ -42,7 +50,6 @@ import type {
   EditableArtifactWorkerKernel,
 } from "./types";
 
-const DEFAULT_PROTOCOL_VERSION = 1;
 const DEFAULT_REPLAY_PAGE_SIZE = 256;
 const DEFAULT_MAX_QUEUE_MESSAGES = 512;
 const DEFAULT_MAX_QUEUE_BYTES = 8 * 1024 * 1024;
@@ -70,7 +77,7 @@ export type CreateEditableArtifactSyncControllerOptions = {
   kernelVersion: string;
   modelSchemaVersion: number;
   commandVersion: number;
-  protocolVersion?: number;
+  protocolVersion: number;
   replayPageSize?: number;
   maxQueuedMessages?: number;
   maxQueuedBytes?: number;
@@ -87,6 +94,8 @@ export type CreateEditableArtifactSyncControllerOptions = {
   maxReconnectAttempts?: number;
   scheduler?: EditableArtifactSyncScheduler;
   clientTransactionIdFactory?: () => string;
+  /** Receives bounded categories/codes only; never workbook or formula content. */
+  onOpenFailure?: EditableArtifactOpenFailureReporter;
   /** Tests/embedded runtimes may inject; defaults to a fresh per-controller UUID. */
   writerReplicaIdFactory?: () => string;
 };
@@ -186,6 +195,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
   private readonly maxReconnectAttempts: number;
   private readonly scheduler: EditableArtifactSyncScheduler;
   private readonly clientTransactionIdFactory: () => string;
+  private readonly onOpenFailure: EditableArtifactOpenFailureReporter | undefined;
 
   private readonly abortController = new AbortController();
   private readonly listeners = new Set<EditableArtifactSyncListener>();
@@ -258,10 +268,10 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     );
     this.modelSchemaVersion = positiveSafeInteger(options.modelSchemaVersion, "modelSchemaVersion");
     this.commandVersion = positiveSafeInteger(options.commandVersion, "commandVersion");
-    this.protocolVersion = positiveSafeInteger(
-      options.protocolVersion ?? DEFAULT_PROTOCOL_VERSION,
-      "protocolVersion",
-    );
+    this.protocolVersion = positiveSafeInteger(options.protocolVersion, "protocolVersion");
+    if (this.protocolVersion !== EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION) {
+      throw new TypeError("protocolVersion is incompatible with the current intent protocol");
+    }
     this.replayPageSize = positiveSafeInteger(
       options.replayPageSize ?? DEFAULT_REPLAY_PAGE_SIZE,
       "replayPageSize",
@@ -324,6 +334,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     this.scheduler = options.scheduler ?? defaultScheduler;
     this.clientTransactionIdFactory =
       options.clientTransactionIdFactory ?? (() => crypto.randomUUID());
+    this.onOpenFailure = options.onOpenFailure;
   }
 
   start(): void {
@@ -331,6 +342,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     this.runTask = this.run().catch((error: unknown) => {
       if (this.abortController.signal.aborted) return;
       const failure = asError(error);
+      this.reportOpenFailure(failure);
       if (failure instanceof EditableArtifactSyncError && failure.code === "unsupported_protocol") {
         this.lastError = failure;
         this.setState("unsupported");
@@ -664,7 +676,8 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     try {
       await this.restoreReplica(stored);
       await this.replacePendingOverlay();
-    } catch {
+    } catch (error) {
+      this.reportOpenFailure(error);
       await this.kernel.reset();
       this.replica = null;
       this.retainedTailTransactions = 0;
@@ -680,8 +693,8 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       stored.snapshot,
       this.artifactId,
       this.modality,
-      this.protocolVersion,
-      this.kernelVersion,
+      COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+      SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
       this.modelSchemaVersion,
       this.maxSnapshotBytes,
     );
@@ -706,7 +719,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
         transaction,
         this.artifactId,
         this.modality,
-        this.protocolVersion,
+        COMMITTED_TRANSACTION_PROTOCOL_VERSION,
         this.maxCommittedTransactionBytes,
       );
       if (transaction.startSequence !== cursor + 1) {
@@ -776,6 +789,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
           delayMs = this.reconnectDelayMs;
         }
         const failure = asError(error);
+        this.reportOpenFailure(failure);
         this.lastError = failure;
         if (failure instanceof EditableArtifactSyncError && failure.requiresSnapshot) {
           this.requireSnapshot = true;
@@ -956,14 +970,11 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     if (bootstrap.modality !== this.modality) {
       throw invalidBootstrap("bootstrap modality does not match the controller");
     }
-    this.requireProtocol(bootstrap.protocolVersion);
-    if (
-      bootstrap.kernelVersion !== this.kernelVersion ||
-      bootstrap.modelSchemaVersion !== this.modelSchemaVersion
-    ) {
+    this.requireLiveProtocol(bootstrap.liveProtocolVersion);
+    if (bootstrap.modelSchemaVersion !== this.modelSchemaVersion) {
       throw new EditableArtifactSyncError(
         "unsupported_protocol",
-        `artifact kernel/schema ${bootstrap.kernelVersion}/${bootstrap.modelSchemaVersion} is incompatible with ${this.kernelVersion}/${this.modelSchemaVersion}`,
+        `artifact schema ${bootstrap.modelSchemaVersion} is incompatible with ${this.modelSchemaVersion}`,
       );
     }
     requireSha256(bootstrap.headStateHash, "bootstrap.headStateHash");
@@ -1035,8 +1046,8 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       snapshot,
       this.artifactId,
       this.modality,
-      this.protocolVersion,
-      this.kernelVersion,
+      COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+      SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
       this.modelSchemaVersion,
       this.maxSnapshotBytes,
     );
@@ -1136,7 +1147,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
           transaction,
           this.artifactId,
           this.modality,
-          this.protocolVersion,
+          COMMITTED_TRANSACTION_PROTOCOL_VERSION,
           this.maxCommittedTransactionBytes,
         );
         pageBytes += estimateCommittedTransactionBytes(transaction);
@@ -1167,7 +1178,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
         message,
         this.artifactId,
         this.modality,
-        this.protocolVersion,
+        COMMITTED_TRANSACTION_PROTOCOL_VERSION,
         this.maxCommittedTransactionBytes,
       );
       bytes = estimateLiveMessageBytes(message);
@@ -1271,7 +1282,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
       transaction,
       this.artifactId,
       this.modality,
-      this.protocolVersion,
+      COMMITTED_TRANSACTION_PROTOCOL_VERSION,
       this.maxCommittedTransactionBytes,
     );
     if (embeddedPending) {
@@ -1568,7 +1579,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
         receipt.committed,
         this.artifactId,
         this.modality,
-        this.protocolVersion,
+        COMMITTED_TRANSACTION_PROTOCOL_VERSION,
         this.maxCommittedTransactionBytes,
       );
       this.recordAcceptedMapping(receipt);
@@ -1641,7 +1652,7 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
         "sync ticket is not bound to the requested writer replica",
       );
     }
-    this.requireProtocol(ticket.protocolVersion);
+    this.requireLiveProtocol(ticket.protocolVersion);
     boundedNonEmpty(ticket.token, "ticket.token", MAX_TICKET_BYTES);
     const expiresAt = Date.parse(ticket.expiresAt);
     if (!Number.isFinite(expiresAt)) {
@@ -1758,11 +1769,11 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     );
   }
 
-  private requireProtocol(actual: number): void {
-    if (actual !== this.protocolVersion) {
+  private requireLiveProtocol(actual: number): void {
+    if (actual !== EDITABLE_ARTIFACT_LIVE_WIRE_VERSION) {
       throw new EditableArtifactSyncError(
         "unsupported_protocol",
-        `artifact protocol ${actual} is incompatible with client ${this.protocolVersion}`,
+        `live protocol ${actual} is incompatible with ${EDITABLE_ARTIFACT_LIVE_WIRE_VERSION}`,
       );
     }
   }
@@ -1794,6 +1805,16 @@ class EditableArtifactSyncControllerImpl implements EditableArtifactSyncControll
     this.liveWaiters.clear();
   }
 
+  private reportOpenFailure(error: unknown): void {
+    const event = classifyEditableArtifactOpenFailure(error);
+    if (event === null || this.onOpenFailure === undefined) return;
+    try {
+      this.onOpenFailure(event);
+    } catch {
+      // Observability must never change recovery or availability behavior.
+    }
+  }
+
   private fail(error: Error): void {
     this.lastError = error;
     this.setState("failed");
@@ -1971,7 +1992,7 @@ function validateCommittedTransaction(
   transaction: EditableArtifactCommittedTransaction,
   artifactId: EditableArtifactId,
   modality: EditableArtifactModality,
-  protocolVersion: number,
+  operationProtocolVersion: number,
   maxCommittedTransactionBytes: number,
 ): Readonly<{
   clientTransactionId: string;
@@ -2000,10 +2021,10 @@ function validateCommittedTransaction(
     throw invalidSequence("transaction committedTransactionBytes exceeds the configured bound");
   }
   if (transaction.modality === "spreadsheet") {
-    if (transaction.protocolVersion !== protocolVersion) {
+    if (transaction.operationProtocolVersion !== operationProtocolVersion) {
       throw new EditableArtifactSyncError(
         "unsupported_protocol",
-        `transaction protocol ${transaction.protocolVersion} is incompatible with client ${protocolVersion}`,
+        `transaction operation protocol ${transaction.operationProtocolVersion} is incompatible with ${operationProtocolVersion}`,
       );
     }
     validateFrontier(transaction.causalFrontier, "causalFrontier");
@@ -2015,7 +2036,7 @@ function validateCommittedTransaction(
     }
     if (
       summary.transactionId !== transaction.transactionId ||
-      summary.operationProtocolVersion !== transaction.protocolVersion ||
+      summary.operationProtocolVersion !== transaction.operationProtocolVersion ||
       summary.priorStateHash !== transaction.priorStateHash ||
       summary.stateHash !== transaction.stateHash ||
       !frontiersEqual(summary.resultingCausalFrontier, transaction.causalFrontier)
@@ -2061,8 +2082,8 @@ function validateSnapshot(
   snapshot: EditableArtifactStoredReplica["snapshot"],
   artifactId: EditableArtifactId,
   modality: EditableArtifactModality,
-  protocolVersion: number,
-  kernelVersion: string,
+  operationProtocolVersion: number,
+  snapshotVersion: number,
   modelSchemaVersion: number,
   maxSnapshotBytes: number,
 ): void {
@@ -2076,22 +2097,22 @@ function validateSnapshot(
   positiveSafeInteger(snapshot.modelSchemaVersion, "snapshot.modelSchemaVersion");
   if (snapshot.modality === "spreadsheet") {
     validateFrontier(snapshot.causalFrontier, "snapshot.causalFrontier");
-    if (snapshot.protocolVersion !== protocolVersion) {
+    if (
+      snapshot.operationProtocolVersion !== operationProtocolVersion ||
+      snapshot.snapshotVersion !== snapshotVersion
+    ) {
       throw new EditableArtifactSyncError(
         "unsupported_protocol",
-        `snapshot protocol ${snapshot.protocolVersion} is incompatible with client ${protocolVersion}`,
+        `snapshot operation/state versions ${snapshot.operationProtocolVersion}/${snapshot.snapshotVersion} are incompatible with ${operationProtocolVersion}/${snapshotVersion}`,
       );
     }
   } else {
     requireNativeRevision(snapshot.nativeRevision, "snapshot.nativeRevision");
   }
-  if (
-    snapshot.kernelVersion !== kernelVersion ||
-    snapshot.modelSchemaVersion !== modelSchemaVersion
-  ) {
+  if (snapshot.modelSchemaVersion !== modelSchemaVersion) {
     throw new EditableArtifactSyncError(
       "unsupported_protocol",
-      `snapshot kernel/schema ${snapshot.kernelVersion}/${snapshot.modelSchemaVersion} is incompatible with ${kernelVersion}/${modelSchemaVersion}`,
+      `snapshot schema ${snapshot.modelSchemaVersion} is incompatible with ${modelSchemaVersion}`,
     );
   }
   if (!(snapshot.bytes instanceof Uint8Array)) {
@@ -2131,7 +2152,7 @@ function validateLiveMessage(
   message: EditableArtifactLiveMessage,
   artifactId: EditableArtifactId,
   modality: EditableArtifactModality,
-  protocolVersion: number,
+  operationProtocolVersion: number,
   maxCommittedTransactionBytes: number,
 ): void {
   if (!message || typeof message !== "object") {
@@ -2142,7 +2163,7 @@ function validateLiveMessage(
       message.transaction,
       artifactId,
       modality,
-      protocolVersion,
+      operationProtocolVersion,
       maxCommittedTransactionBytes,
     );
     return;
@@ -2198,7 +2219,7 @@ function estimateCommittedTransactionBytes(
 function requireStateHash(actual: string, expected: string, source: string): void {
   if (actual !== expected) {
     throw new EditableArtifactSyncError(
-      "kernel_diverged",
+      "authored_causal_mismatch",
       `${source} produced state hash ${actual}; expected ${expected}`,
       { retryable: true, requiresSnapshot: true },
     );
@@ -2209,7 +2230,7 @@ function requireDigest(actual: string, expected: string, source: string): void {
   requireSha256(actual, `${source} computed digest`);
   if (actual !== expected) {
     throw new EditableArtifactSyncError(
-      "kernel_diverged",
+      "byte_corruption",
       `${source} bytes produced digest ${actual}; expected ${expected}`,
       { retryable: true, requiresSnapshot: true },
     );
@@ -2230,7 +2251,7 @@ function requireFrontier(
     )
   ) {
     throw new EditableArtifactSyncError(
-      "kernel_diverged",
+      "authored_causal_mismatch",
       `${source} causal frontier does not match the authoritative barrier`,
       { retryable: true, requiresSnapshot: true },
     );
@@ -2416,7 +2437,7 @@ function requireNativeRevisionEqual(actual: number, expected: number, source: st
   requireNativeRevision(expected, `${source} expected native revision`);
   if (actual !== expected) {
     throw new EditableArtifactSyncError(
-      "kernel_diverged",
+      "authored_causal_mismatch",
       `${source} native revision ${actual} does not match ${expected}`,
       { retryable: true, requiresSnapshot: true },
     );

package/src/editable-artifacts/errors.ts

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