@opengeni/sdk 0.52.1 → 1.0.0

package/dist/codex-realtime-controller.d.ts

@@ -38,6 +38,9 @@ export type CodexRealtimeControllerClient = {
     negotiateGatewayRealtime?(workspaceId: string, sessionId: string, request: GatewayRealtimeConnectRequest, options?: {
         signal?: AbortSignal | undefined;
     }): Promise<GatewayRealtimeConnectResponse>;
+    negotiateXaiSubscriptionRealtime?(workspaceId: string, sessionId: string, request: GatewayRealtimeConnectRequest, options?: {
+        signal?: AbortSignal | undefined;
+    }): Promise<GatewayRealtimeConnectResponse>;
     activateCodexRealtimeConnection(workspaceId: string, sessionId: string, realtimeId: string, connectionId: string, request: ActivateCodexRealtimeConnectionRequest, options?: {
         signal?: AbortSignal | undefined;
     }): Promise<SessionRealtimeMutationResponse>;
@@ -69,6 +72,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;
@@ -80,6 +84,8 @@ export type CreateCodexRealtimeControllerOptions = {
     model?: SessionRealtimeModel | undefined;
     ownerStorageNamespace?: string | undefined;
     startTransport?: RealtimeControllerTransportStarter | undefined;
+    /** Model-visible application context captured with each durable realtime message. */
+    getModelContext?: (() => string | undefined) | undefined;
 };
 export type RealtimeControllerTransportStarter = (input: {
     client: CodexRealtimeControllerClient;

package/dist/codex-realtime-controller.js

@@ -5,8 +5,8 @@ import {
   projectSessionRealtimeLifecycle,
   sessionRealtimeOwnerStorageKey,
   sessionRealtimeOwnerStorageNamespace
-} from "./chunk-KIHGPM7H.js";
-import "./chunk-V5F253OG.js";
+} from "./chunk-2UXZUCEZ.js";
+import "./chunk-V6GIY62B.js";
 export {
   CODEX_REALTIME_NEGOTIATION_TIMEOUT_MS,
   createCodexRealtimeController,

package/dist/codex-realtime-v3.d.ts

@@ -1,11 +1,11 @@
-import type { SyncSessionRealtimeLedgerRequest, SyncSessionRealtimeLedgerResponse } from "./types.js";
+import type { SessionRealtimeInboundEntry, SyncSessionRealtimeLedgerRequest, SyncSessionRealtimeLedgerResponse } from "./types.js";
 export { CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES, CODEX_REALTIME_V3_MAX_EVENT_BYTES, CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES, CODEX_REALTIME_V3_MAX_TEXT_BYTES, contextAppendChunks, encodeCodexRealtimeV3DelegationContextAppend, encodeCodexRealtimeV3SessionContextAppend, parseCodexRealtimeV3Event, } from "./codex-realtime-v3-wire.js";
 export type { CodexRealtimeV3ContextAppendChannel, CodexRealtimeV3DelegationContextAppend, CodexRealtimeV3Event, CodexRealtimeV3ParseFailure, CodexRealtimeV3ParseResult, CodexRealtimeV3SessionContextAppend, } from "./codex-realtime-v3-wire.js";
 export declare const CODEX_REALTIME_V3_SYNC_MAX_ENTRIES = 64;
 export declare const CODEX_REALTIME_V3_PENDING_MAX_ENTRIES = 256;
 export declare const CODEX_REALTIME_V3_PENDING_MAX_BYTES: number;
 export type CodexRealtimeV3BridgeFatal = {
-    code: "pending_overflow";
+    code: "pending_overflow" | "replay_journal_failed";
     message: string;
 };
 export type CodexRealtimeV3BridgeSnapshot = {
@@ -35,6 +35,17 @@ export type CodexRealtimeV3BridgeOptions = {
     owner: Pick<SyncSessionRealtimeLedgerRequest, "browserInstanceId" | "ownerKey" | "expectedVersion">;
     sync(request: SyncSessionRealtimeLedgerRequest): Promise<SyncSessionRealtimeLedgerResponse>;
     randomUUID?: (() => string) | undefined;
+    /** Model-visible application context captured once for each durable message-bearing entry. */
+    getModelContext?: (() => string | undefined) | undefined;
+    /** Controller-lifetime delegation identities shared across provider connection rotations. */
+    acceptedDelegationItemIds?: Set<string> | undefined;
+    /** Unsynced delegation snapshots retained exactly across provider connection rotations. */
+    pendingDelegations?: Map<string, SessionRealtimeInboundEntry> | undefined;
+    /** Persist exact delegation replay state before it becomes browser-reload-sensitive. */
+    onDelegationReplayStateChange?: ((state: {
+        acceptedDelegationItemIds: ReadonlySet<string>;
+        pendingDelegations: ReadonlyMap<string, SessionRealtimeInboundEntry>;
+    }) => void) | undefined;
     /** The controller installs its activation FIFO first, then enables this listener synchronously. */
     listen?: boolean | undefined;
     onSnapshot?: ((snapshot: CodexRealtimeV3BridgeSnapshot) => void) | undefined;

package/dist/company-brain.d.ts

@@ -0,0 +1,22 @@
+import type { CompanyBrainContextReceiptPage as ContractCompanyBrainContextReceiptPage, CompanyBrainKnowledgeProposalPage as ContractCompanyBrainKnowledgeProposalPage, CompanyBrainOkfPackage as ContractCompanyBrainOkfPackage } from "@opengeni/contracts";
+export type CompanyBrainOkfPackage = ContractCompanyBrainOkfPackage;
+export type CompanyBrainContextReceiptPage = ContractCompanyBrainContextReceiptPage;
+export type CompanyBrainKnowledgeProposalPage = ContractCompanyBrainKnowledgeProposalPage;
+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>;
+};
+export declare function listCompanyBrainContextReceipts(client: CompanyBrainInspectorTransport, workspaceId: string, options?: CompanyBrainContextReceiptListOptions): Promise<CompanyBrainContextReceiptPage>;
+export declare function listCompanyBrainKnowledgeProposals(client: CompanyBrainInspectorTransport, workspaceId: string, options?: CompanyBrainKnowledgeProposalListOptions): Promise<CompanyBrainKnowledgeProposalPage>;
+export type CompanyBrainOkfDownload = {
+    content: string;
+    contentType: string;
+    filename: string;
+};

package/dist/company-profile.d.ts

@@ -24,7 +24,7 @@ export type CompanyProfileRevision = CompanyProfileRevisionIdentity & {
     intent: "active" | "proposal";
     profile: CompanyProfileContent;
     provenance: {
-        source: "human" | "durable_learning" | "migration";
+        source: "human" | "agent_admin" | "durable_learning" | "migration";
         sourceId: string | null;
     };
     supersedesRevisionId: string | null;
@@ -87,6 +87,19 @@ export type CompanyProfileMutationResponse = {
     head: CompanyProfileHead | null;
     event: CompanyProfileActivationEvent | null;
 };
+export type CompanyProfileAgentPolicyMode = "off" | "suggest" | "automatic";
+export type CompanyProfileAgentPolicy = {
+    organizationId: string;
+    mode: CompanyProfileAgentPolicyMode;
+    version: number;
+    updatedAt: string;
+    changed?: boolean;
+};
+export type UpdateCompanyProfileAgentPolicyRequest = {
+    mode: CompanyProfileAgentPolicyMode;
+    expectedVersion: number;
+    operationId: string;
+};
 export type CompanyProfileDiffRequest = {
     fromRevisionId: string;
     toRevisionId: string;

package/dist/core.d.ts

@@ -1,5 +1,11 @@
-export { OpenGeniClient as OpenGeniCoreClient } from "./client.js";
-export type { FetchLike, OpenGeniClientOptions, OpenGeniRequestOptions, SendMessageInput, SteerMessageResult, TranscribeAudioInput, WorkspaceControlEventPage, } from "./client.js";
-export { OpenGeniApiContractMismatchError, OpenGeniApiError, OpenGeniSessionListCursorError, OpenGeniStreamError, isRetryableStreamError, } from "./errors.js";
+/** Backward-compatible non-artifact client surface. */
+export { OpenGeniDocumentAuthorityClient as OpenGeniCoreClient } from "./document-authority-client.js";
+export { OpenGeniToolCallError, OpenGeniToolReapprovalRequiredError, OpenGeniToolsClient, } from "./tools.js";
+export type { OpenGeniGeneratedTools, OpenGeniDynamicToolNode, OpenGeniToolCallOptions, OpenGeniToolFunction, OpenGeniToolsFacade, OpenGeniWorkspaceTools, } from "./tools.js";
+export type { FetchLike, FetchResponse, GetSessionOptions, OpenGeniClientOptions, OpenGeniRequestOptions, SendMessageInput, SteerMessageResult, TranscribeAudioInput, WorkspaceControlEventPage, } from "./client.js";
+export { OpenGeniApiContractMismatchError, OpenGeniApiError, OpenGeniSetupError, OpenGeniSecureContextRequiredError, OpenGeniSessionListCursorError, OpenGeniStreamError, formatErrorMessage, isRetryableStreamError, } from "./errors.js";
+export type { OpenGeniSecureContextRequiredReason } from "./errors.js";
+export { parseDeprecationNotice } from "./deprecation.js";
+export type { OpenGeniDeprecationHandler, OpenGeniDeprecationNotice } from "./deprecation.js";
 export { resolveWorkspaceVoiceInputEnabled } from "./transcription.js";
 export { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types.js";

package/dist/core.js

@@ -2,29 +2,48 @@ import {
   resolveWorkspaceVoiceInputEnabled
 } from "./chunk-VYCTL62C.js";
 import {
-  OpenGeniClient
-} from "./chunk-ILQZR5N6.js";
+  OpenGeniDocumentAuthorityClient
+} from "./chunk-HMGADJGZ.js";
+import {
+  OpenGeniToolCallError,
+  OpenGeniToolReapprovalRequiredError,
+  OpenGeniToolsClient
+} from "./chunk-4SMEOV3P.js";
+import {
+  parseDeprecationNotice
+} from "./chunk-FG3OO5LM.js";
+import "./chunk-APXVSSSY.js";
+import {
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_API_CONTRACT_REVISION
+} from "./chunk-YIKA2QT4.js";
+import "./chunk-NC57YMUO.js";
 import {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
+  OpenGeniSecureContextRequiredError,
   OpenGeniSessionListCursorError,
+  OpenGeniSetupError,
   OpenGeniStreamError,
+  formatErrorMessage,
   isRetryableStreamError
-} from "./chunk-V5F253OG.js";
-import "./chunk-MZWTWOX6.js";
-import {
-  OPENGENI_API_CONTRACT_HEADER,
-  OPENGENI_API_CONTRACT_REVISION
-} from "./chunk-FRJFNDIR.js";
+} from "./chunk-V6GIY62B.js";
 export {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
-  OpenGeniClient as OpenGeniCoreClient,
+  OpenGeniDocumentAuthorityClient as OpenGeniCoreClient,
+  OpenGeniSecureContextRequiredError,
   OpenGeniSessionListCursorError,
+  OpenGeniSetupError,
   OpenGeniStreamError,
+  OpenGeniToolCallError,
+  OpenGeniToolReapprovalRequiredError,
+  OpenGeniToolsClient,
+  formatErrorMessage,
   isRetryableStreamError,
+  parseDeprecationNotice,
   resolveWorkspaceVoiceInputEnabled
 };
 //# sourceMappingURL=core.js.map

package/dist/deprecation.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Deprecation notices advertised by the OpenGeni API.
+ *
+ * Per the public API compatibility policy, a route whose behaviour is scheduled
+ * for removal answers with the standard `Deprecation` (RFC 9745) and `Sunset`
+ * (RFC 8594) headers plus `Link: <notes>; rel="deprecation"`. The client
+ * surfaces them through `OpenGeniClientOptions.onDeprecation`, or by default
+ * as a one-time `console.warn` per route, so an integrator pinned to an older
+ * SDK learns about a removal well before it happens.
+ */
+export type OpenGeniDeprecationNotice = {
+    /** Request method, upper case. */
+    method: string;
+    /** Request path with ids collapsed (`/v1/workspaces/:id/...`), stable per route. */
+    route: string;
+    /** Exact request path. */
+    path: string;
+    /** When the deprecation was announced, if the header carried a date. */
+    deprecatedAt: Date | null;
+    /** Earliest removal on the server, if advertised. */
+    sunset: Date | null;
+    /** Migration notes (`rel="deprecation"`), if advertised. */
+    link: string | null;
+    /** Replacement (`rel="successor-version"`), if advertised. */
+    successor: string | null;
+};
+/** `false` silences notices; a function receives each route's notice once per client. */
+export type OpenGeniDeprecationHandler = (notice: OpenGeniDeprecationNotice) => void;
+type HeaderBag = {
+    get(name: string): string | null;
+};
+/** Read a deprecation notice from response headers; `null` when none is advertised. */
+export declare function parseDeprecationNotice(method: string, url: string, headers: HeaderBag): OpenGeniDeprecationNotice | null;
+/** The default handler: one `console.warn` per route per process. */
+export declare function warnDeprecationOnce(notice: OpenGeniDeprecationNotice): void;
+type FetchFunction<R extends {
+    headers: HeaderBag;
+}> = (input: string | URL | Request, init?: RequestInit) => Promise<R>;
+/**
+ * Wrap a fetch implementation so every response is inspected for a deprecation
+ * notice. The handler runs at most once per route for this wrapper and never
+ * affects the request: a throwing handler is swallowed.
+ */
+export declare function withDeprecationNotices<R extends {
+    headers: HeaderBag;
+}>(fetchImpl: FetchFunction<R>, handler: OpenGeniDeprecationHandler | false | undefined): FetchFunction<R>;
+export {};

package/dist/desktop.d.ts

@@ -30,12 +30,20 @@ export interface DesktopRfbLike {
     clipViewport: boolean;
     addEventListener(type: "connect" | "disconnect" | "securityfailure", cb: (e?: unknown) => void): void;
     removeEventListener?: (type: "connect" | "disconnect" | "securityfailure", cb: (e?: unknown) => void) => void;
+    /** Send clipboard text over the already-open RFB connection. */
+    clipboardPasteFrom?(text: string): void;
+    /** Send one RFB key event. A missing `down` emits a complete key press. */
+    sendKey?(keysym: number, code: string, down?: boolean): void;
+    /** Focus or release the RFB keyboard sink without reconnecting. */
+    focus?(options?: FocusOptions): void;
+    blur?(): void;
     disconnect(): void;
 }
 export type DesktopRfbFactory = (target: HTMLElement, url: string, opts: {
     credentials?: {
         password?: string | undefined;
     } | undefined;
+    wsProtocols?: string[] | undefined;
 }) => DesktopRfbLike;
 export type DesktopConnectionState = "idle" | "negotiating" | "connecting" | "connected" | "rotating" | "reconnecting" | "error" | "ended";
 export type DesktopStreamEvent = {

package/dist/document-authority-client.d.ts

@@ -0,0 +1,51 @@
+import type { CompanyBrainOkfDownload, CompanyBrainOkfPackage } from "./company-brain.js";
+import { OpenGeniClient as OpenGeniCoreClient } from "./client.js";
+import type { ApiKey, UpdateOrganizationApiKeyRequest, Document, IssueUserResourceGrantRequest, UserResourceGrantMutationResponse, DocumentBase, FileDownloadUrlResponse, DocumentAuthorityReclassification, DocumentDefaultCollectionBackfill, DocumentDefaultCollectionBackfillAudit, GetDocumentDefaultCollectionBackfillAuditOptions, ListDocumentAuthorityReclassificationsOptions, ListDocumentAuthorityReclassificationsResponse, ListDocumentDefaultCollectionBackfillRunsResponse, ListOrganizationDocumentAuthorityReclassificationsResponse, ReclassifyDocumentAuthorityRequest, RunDocumentDefaultCollectionBackfillRequest } from "./types.js";
+/**
+ * Operator-only authority administration and Document tenancy-backfill surface.
+ *
+ * The public root and legacy `core` clients extend this class for compatibility.
+ * Browser consoles that import `@opengeni/sdk/browser` do not retain these
+ * methods or their routes.
+ */
+export declare class OpenGeniDocumentAuthorityClient extends OpenGeniCoreClient {
+    /** Read organization-key metadata and policy; never returns the secret token. */
+    getOrganizationApiKey(organizationId: string, apiKeyId: string): Promise<ApiKey>;
+    /** Update metadata or replace the policy. Policy narrowing applies on the next request. */
+    updateOrganizationApiKey(organizationId: string, apiKeyId: string, request: UpdateOrganizationApiKeyRequest): Promise<ApiKey>;
+    /** Issue an exact-session or standing personal-resource grant. */
+    issueUserResourceGrant(workspaceId: string, authorityId: string, request: IssueUserResourceGrantRequest): Promise<UserResourceGrantMutationResponse>;
+    listDocumentBases(workspaceId: string): Promise<DocumentBase[]>;
+    /**
+     * List every Document the current human can manage from this workspace,
+     * including portable personal and organization-scoped Documents whose
+     * immutable ingestion workspace is different.
+     */
+    listAccessibleDocuments(workspaceId: string): Promise<Document[]>;
+    /** Mint a source-file URL through the Document's effective authority. */
+    createDocumentOriginalFileDownloadUrl(workspaceId: string, documentId: string): Promise<FileDownloadUrlResponse>;
+    /** Retry indexing for a failed document. */
+    reindexDocument(workspaceId: string, baseId: string, documentId: string): Promise<Document>;
+    /** Permission-filtered Company Brain package with authorized guidance bodies. */
+    getCompanyBrain(workspaceId: string): Promise<CompanyBrainOkfPackage>;
+    /** Download the deterministic Markdown/YAML Company Brain package. */
+    exportCompanyBrainOkf(workspaceId: string): Promise<CompanyBrainOkfDownload>;
+    /**
+     * Atomically reclassify a Document's authority and every indexed chunk.
+     * The operation is replay-safe and rejects a stale expected authority tuple.
+     */
+    reclassifyDocumentAuthority(workspaceId: string, documentId: string, request: ReclassifyDocumentAuthorityRequest): Promise<DocumentAuthorityReclassification>;
+    /** List the current actor's durable authority-reclassification receipts. */
+    listDocumentAuthorityReclassifications(workspaceId: string, documentId: string, options?: ListDocumentAuthorityReclassificationsOptions): Promise<ListDocumentAuthorityReclassificationsResponse>;
+    /**
+     * Advance one resumable, organization-scoped Default collection backfill.
+     * Reusing an operation ID is idempotent; keep the run ID across batches.
+     */
+    runDocumentDefaultCollectionBackfill(workspaceId: string, request: RunDocumentDefaultCollectionBackfillRequest): Promise<DocumentDefaultCollectionBackfill>;
+    /** List organization-scoped Default collection backfill runs (organization admin only). */
+    listDocumentDefaultCollectionBackfillRuns(workspaceId: string, options?: ListDocumentAuthorityReclassificationsOptions): Promise<ListDocumentDefaultCollectionBackfillRunsResponse>;
+    /** Read bounded operation and workspace receipts for one Default-collection backfill run. */
+    getDocumentDefaultCollectionBackfillAudit(workspaceId: string, runId: string, options?: GetDocumentDefaultCollectionBackfillAuditOptions): Promise<DocumentDefaultCollectionBackfillAudit>;
+    /** List organization-wide Document authority changes (organization admin only). */
+    listOrganizationDocumentAuthorityReclassifications(workspaceId: string, options?: ListDocumentAuthorityReclassificationsOptions): Promise<ListOrganizationDocumentAuthorityReclassificationsResponse>;
+}

package/dist/document-authority.d.ts

@@ -0,0 +1,2 @@
+export { OpenGeniDocumentAuthorityClient } from "./document-authority-client.js";
+export type { DocumentAuthorityReclassification, DocumentDefaultCollectionBackfill, DocumentDefaultCollectionBackfillAudit, DocumentDefaultCollectionBackfillOperationAudit, DocumentDefaultCollectionBackfillReceiptAudit, DocumentDefaultCollectionBackfillRunAudit, GetDocumentDefaultCollectionBackfillAuditOptions, ListDocumentAuthorityReclassificationsOptions, ListDocumentAuthorityReclassificationsResponse, ListDocumentDefaultCollectionBackfillRunsResponse, ListOrganizationDocumentAuthorityReclassificationsResponse, OrganizationDocumentAuthorityReclassification, ReclassifyDocumentAuthorityRequest, RunDocumentDefaultCollectionBackfillRequest, } from "./types.js";

package/dist/document-authority.js

@@ -0,0 +1,12 @@
+import {
+  OpenGeniDocumentAuthorityClient
+} from "./chunk-HMGADJGZ.js";
+import "./chunk-FG3OO5LM.js";
+import "./chunk-APXVSSSY.js";
+import "./chunk-YIKA2QT4.js";
+import "./chunk-NC57YMUO.js";
+import "./chunk-V6GIY62B.js";
+export {
+  OpenGeniDocumentAuthorityClient
+};
+//# sourceMappingURL=document-authority.js.map

package/dist/document-authority.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/editable-artifacts/browser-session.d.ts

@@ -3,12 +3,14 @@ import { type CreateEditableArtifactHttpLiveTransportOptions } from "./http-live
 import { type EditableArtifactSession } from "./session.js";
 import type { EditableArtifactStoragePort } from "./storage.js";
 import type { EditableArtifactModality } from "./types.js";
+import type { EditableArtifactOpenFailureReporter } from "./open-failure.js";
 import { type CreateBrowserEditableArtifactWorkerKernelOptions } from "./worker/browser-client.js";
 export type EditableArtifactBrowserRuntime = Omit<CreateBrowserEditableArtifactWorkerKernelOptions, "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;
 }>;
 export type CreateBrowserEditableArtifactSessionOptions = Readonly<{
@@ -21,10 +23,12 @@ export type CreateBrowserEditableArtifactSessionOptions = Readonly<{
     /** Exact login/grant partition; rotate authorizationEpoch on authority changes. */
     storageAuthority: EditableArtifactCacheAuthority;
     runtime: EditableArtifactBrowserRuntime;
-    transport?: Omit<CreateEditableArtifactHttpLiveTransportOptions, "baseUrl" | "workspaceId" | "protocolVersion" | "kernelVersion" | "modelSchemaVersion">;
+    transport?: Omit<CreateEditableArtifactHttpLiveTransportOptions, "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;
 }>;
 /**
  * One production browser composition point: verified WASM Worker, durable WAL,

package/dist/editable-artifacts/controller.d.ts

@@ -1,3 +1,4 @@
+import { type EditableArtifactOpenFailureReporter } from "./open-failure.js";
 import type { EditableArtifactStoragePort } from "./storage.js";
 import type { EditableArtifactId, EditableArtifactModality, EditableArtifactPendingTransaction, EditableArtifactSyncListener, EditableArtifactSyncScheduler, EditableArtifactSyncTransport, EditableArtifactSyncView, EditableArtifactWorkerKernel } from "./types.js";
 export type CreateEditableArtifactSyncControllerOptions = {
@@ -11,7 +12,7 @@ export type CreateEditableArtifactSyncControllerOptions = {
     kernelVersion: string;
     modelSchemaVersion: number;
     commandVersion: number;
-    protocolVersion?: number;
+    protocolVersion: number;
     replayPageSize?: number;
     maxQueuedMessages?: number;
     maxQueuedBytes?: number;
@@ -28,6 +29,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;
 };

package/dist/editable-artifacts/errors.d.ts

@@ -1,4 +1,4 @@
-export type EditableArtifactSyncErrorCode = "unsupported_protocol" | "invalid_bootstrap" | "invalid_sequence" | "kernel_diverged" | "queue_overflow" | "resync_required" | "permission_changed" | "storage_failed" | "pending_conflict" | "reconnect_exhausted";
+export type EditableArtifactSyncErrorCode = "unsupported_protocol" | "invalid_bootstrap" | "invalid_sequence" | "kernel_diverged" | "byte_corruption" | "authored_causal_mismatch" | "queue_overflow" | "resync_required" | "permission_changed" | "storage_failed" | "pending_conflict" | "reconnect_exhausted";
 export declare class EditableArtifactSyncError extends Error {
     readonly code: EditableArtifactSyncErrorCode;
     readonly retryable: boolean;

package/dist/editable-artifacts/http-live-transport.d.ts

@@ -1,4 +1,4 @@
-import type { EditableArtifactSyncTransport } from "./types.js";
+import type { EditableArtifactModality, EditableArtifactSyncTransport } from "./types.js";
 export type EditableArtifactWebSocketMessageEvent = Readonly<{
     data: unknown;
 }>;
@@ -24,9 +24,13 @@ export type EditableArtifactWebSocketLike = {
 export type CreateEditableArtifactHttpLiveTransportOptions = Readonly<{
     baseUrl: string | URL;
     workspaceId: string;
-    protocolVersion: number;
+    modality: EditableArtifactModality;
+    liveProtocolVersion: number;
     kernelVersion: string;
     modelSchemaVersion: number;
+    snapshotVersion: number;
+    commandProtocolVersion: number;
+    committedTransactionProtocolVersion: number;
     apiKey?: string;
     headers?: Readonly<Record<string, string>> | (() => Readonly<Record<string, string>>);
     credentials?: RequestCredentials;

package/dist/editable-artifacts/index.d.ts

@@ -3,6 +3,8 @@ export { createBrowserEditableArtifactSession, createEditableArtifactReplicaId,
 export type { CreateBrowserEditableArtifactSessionOptions, EditableArtifactBrowserRuntime, } from "./browser-session.js";
 export { EditableArtifactSyncError, EditableArtifactTransportError } from "./errors.js";
 export type { EditableArtifactSyncErrorCode } from "./errors.js";
+export { classifyEditableArtifactOpenFailure } from "./open-failure.js";
+export type { EditableArtifactOpenFailureCategory, EditableArtifactOpenFailureEvent, EditableArtifactOpenFailureReporter, } from "./open-failure.js";
 export { createEditableArtifactHttpLiveTransport } from "./http-live-transport.js";
 export type { CreateEditableArtifactHttpLiveTransportOptions, EditableArtifactWebSocketCloseEvent, EditableArtifactWebSocketLike, EditableArtifactWebSocketMessageEvent, } from "./http-live-transport.js";
 export { EditableArtifactStorageConflictError, IndexedDbEditableArtifactStorage, MemoryEditableArtifactStorage, } from "./storage.js";

package/dist/editable-artifacts/open-failure.d.ts

@@ -0,0 +1,9 @@
+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;
+/** Maps only stable error codes; messages and workbook/formula content are ignored. */
+export declare function classifyEditableArtifactOpenFailure(error: unknown): EditableArtifactOpenFailureEvent | null;

package/dist/editable-artifacts/types.d.ts

@@ -33,7 +33,8 @@ type EditableArtifactSnapshotCommon = {
 export type EditableArtifactSpreadsheetSnapshot = EditableArtifactSnapshotCommon & {
     modality: "spreadsheet";
     causalFrontier: EditableArtifactCausalFrontier;
-    protocolVersion: number;
+    operationProtocolVersion: number;
+    snapshotVersion: number;
 };
 export type EditableArtifactSerializedSnapshot = EditableArtifactSnapshotCommon & {
     modality: EditableArtifactSerializedModality;
@@ -54,7 +55,7 @@ type EditableArtifactCommittedTransactionCommon = {
 export type EditableArtifactSpreadsheetCommittedTransaction = EditableArtifactCommittedTransactionCommon & {
     modality: "spreadsheet";
     causalFrontier: EditableArtifactCausalFrontier;
-    protocolVersion: number;
+    operationProtocolVersion: number;
     /** Exact whole canonical OGACO committed-transaction envelope. */
     committedTransactionBytes: Uint8Array;
 };
@@ -202,7 +203,7 @@ export type EditableArtifactStoredReplica = {
 };
 type EditableArtifactBootstrapCommon = {
     artifactId: EditableArtifactId;
-    protocolVersion: number;
+    liveProtocolVersion: number;
     headSequence: number;
     headStateHash: string;
     kernelVersion: string;
@@ -402,6 +403,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/dist/editable-artifacts/worker/kernel-adapter.d.ts

@@ -2,7 +2,7 @@ import type { ArtifactWorkerInitializeInput } from "./wire-codec.js";
 import type { EditableArtifactModality } from "../types.js";
 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;