@opengeni/contracts 0.40.0 → 0.44.1

package/dist/editable-artifact-live.d.ts

@@ -0,0 +1,276 @@
+import { type EditableArtifactCausalEntry } from "./editable-artifacts.js";
+export declare const EDITABLE_ARTIFACT_LIVE_WIRE_VERSION = 1;
+export type EditableArtifactId = string;
+export type EditableArtifactRequestHash = string;
+export type EditableArtifactStateHash = string;
+export type EditableArtifactContentHash = string;
+export type EditableArtifactTransactionId = string;
+export type EditableArtifactClientTransactionId = string;
+export type EditableArtifactCausalFrontier = readonly EditableArtifactCausalEntry[];
+export type EditableArtifactLiveModality = "document" | "spreadsheet" | "presentation";
+export type EditableArtifactLiveErrorCode = "invalid_ticket" | "ticket_expired" | "ticket_replayed" | "protocol_mismatch" | "permission_changed" | "invalid_frame" | "oversized_frame" | "stale_epoch" | "invalid_ack" | "durable_gap" | "retention_gap" | "slow_client" | "closed";
+/** Shared transport error: core and SDK must classify the same frame identically. */
+export declare class EditableArtifactLiveError extends Error {
+    readonly code: EditableArtifactLiveErrorCode;
+    readonly options: Readonly<{
+        retryable?: boolean;
+        requiresSnapshot?: boolean;
+        cause?: unknown;
+    }>;
+    constructor(code: EditableArtifactLiveErrorCode, message: string, options?: Readonly<{
+        retryable?: boolean;
+        requiresSnapshot?: boolean;
+        cause?: unknown;
+    }>);
+    get retryable(): boolean;
+    get requiresSnapshot(): boolean;
+}
+type EditableArtifactLiveResumeCommon = Readonly<{
+    localCursor: number | null;
+    localStateHash: EditableArtifactStateHash | null;
+    requireSnapshot: boolean;
+}>;
+export type EditableArtifactLiveResume = (EditableArtifactLiveResumeCommon & Readonly<{
+    /** Omitted on OGALV001 for byte-compatible spreadsheet sessions. */
+    modality?: "spreadsheet";
+    localCausalFrontier: EditableArtifactCausalFrontier;
+}>) | (EditableArtifactLiveResumeCommon & Readonly<{
+    modality: "document" | "presentation";
+    localNativeRevision: number | null;
+}>);
+export type EditableArtifactLiveTicket = Readonly<{
+    artifactId: EditableArtifactId;
+    modality: EditableArtifactLiveModality;
+    replicaId: string;
+    token: string;
+    expiresAt: string;
+    protocolVersion: number;
+}>;
+type EditableArtifactLiveSnapshotCommon = Readonly<{
+    artifactId: EditableArtifactId;
+    sequence: number;
+    stateHash: EditableArtifactStateHash;
+    digest: EditableArtifactContentHash;
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    bytes: Uint8Array;
+}>;
+export type EditableArtifactLiveSnapshot = (EditableArtifactLiveSnapshotCommon & Readonly<{
+    modality?: "spreadsheet";
+    causalFrontier: EditableArtifactCausalFrontier;
+    protocolVersion: number;
+}>) | (EditableArtifactLiveSnapshotCommon & Readonly<{
+    modality: "document" | "presentation";
+    nativeRevision: number;
+}>);
+type EditableArtifactLiveCommittedTransactionCommon = Readonly<{
+    artifactId: EditableArtifactId;
+    transactionId: EditableArtifactTransactionId;
+    requestHash: EditableArtifactRequestHash;
+    startSequence: number;
+    endSequence: number;
+    priorStateHash: EditableArtifactStateHash;
+    stateHash: EditableArtifactStateHash;
+    committedTransactionBytes: Uint8Array;
+}>;
+export type EditableArtifactLiveCommittedTransaction = (EditableArtifactLiveCommittedTransactionCommon & Readonly<{
+    modality?: "spreadsheet";
+    causalFrontier: EditableArtifactCausalFrontier;
+    protocolVersion: number;
+    /** Exact canonical whole OGACO transaction envelope. */
+    committedTransactionBytes: Uint8Array;
+}>) | (EditableArtifactLiveCommittedTransactionCommon & Readonly<{
+    modality: "document" | "presentation";
+    priorNativeRevision: number;
+    nativeRevision: number;
+    commitProtocolVersion: number;
+    /** Exact canonical whole OGAST transaction envelope. */
+    committedTransactionBytes: Uint8Array;
+}>);
+type EditableArtifactLiveHeadCommon = Readonly<{
+    headSequence: number;
+    stateHash: EditableArtifactStateHash;
+    minimumReplaySequence: number;
+}>;
+export type EditableArtifactLiveHead = (EditableArtifactLiveHeadCommon & Readonly<{
+    modality: "spreadsheet";
+    causalFrontier: EditableArtifactCausalFrontier;
+}>) | (EditableArtifactLiveHeadCommon & Readonly<{
+    modality: "document" | "presentation";
+    nativeRevision: number;
+}>);
+export type EditableArtifactLiveBootstrap = EditableArtifactLiveHead & Readonly<{
+    resumeAccepted: boolean;
+    resumeSequence: number;
+    resumeStateHash: EditableArtifactStateHash;
+    snapshot: EditableArtifactLiveSnapshot | null;
+}>;
+export type EditableArtifactLiveAppliedClientFrame = Readonly<{
+    type: "applied";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    sequence: number;
+    stateHash: EditableArtifactStateHash;
+}>;
+export type EditableArtifactLiveMutationClientFrame = Readonly<{
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    requestHash: EditableArtifactRequestHash;
+    /** Exact bounded OGATX001 client-intent envelope, never canonical operations. */
+    intentBytes: Uint8Array;
+}>;
+export type EditableArtifactLiveClientFrame = EditableArtifactLiveAppliedClientFrame;
+export type EditableArtifactLiveCloseReason = "closed" | "ticket_expired" | "ticket_replayed" | "protocol_mismatch" | "permission_changed" | "invalid_frame" | "oversized_frame" | "stale_epoch" | "invalid_ack" | "retention_gap" | "durable_gap" | "slow_client" | "transport_error";
+export type EditableArtifactLiveClose = Readonly<{
+    reason: EditableArtifactLiveCloseReason;
+    retryable: boolean;
+    requiresSnapshot: boolean;
+}>;
+export type EditableArtifactLiveMutationReceipt = Readonly<{
+    clientTransactionId: EditableArtifactClientTransactionId;
+    requestHash: EditableArtifactRequestHash;
+    transaction: EditableArtifactLiveCommittedTransaction;
+}>;
+export type EditableArtifactLiveServerFrame = Readonly<{
+    type: "open";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    /** Omitted on the wire for spreadsheet compatibility. */
+    modality?: EditableArtifactLiveModality;
+    writable: boolean;
+    headSequence: number;
+    minimumReplaySequence: number;
+    maxClientFrameBytes: number;
+    maxCommandBytes: number;
+    maxIntentBytes: number;
+    maxCommittedTransactionBytes: number;
+    maxSnapshotBytes: number;
+    maxInFlightTransactions: number;
+    maxInFlightBytes: number;
+}> | (Readonly<{
+    type: "snapshot";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    sequence: number;
+    stateHash: EditableArtifactStateHash;
+    digest: EditableArtifactContentHash;
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    offset: number;
+    totalBytes: number;
+    final: boolean;
+    bytes: Uint8Array;
+}> & (Readonly<{
+    /** Omitted on the wire for spreadsheet compatibility. */
+    modality?: "spreadsheet";
+    causalFrontier: EditableArtifactCausalFrontier;
+}> | Readonly<{
+    modality: "document" | "presentation";
+    nativeRevision: number;
+}>)) | Readonly<{
+    type: "transaction";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    transaction: EditableArtifactLiveCommittedTransaction;
+}> | Readonly<{
+    type: "barrier";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    sequence: number;
+    stateHash: EditableArtifactStateHash;
+}> | Readonly<{
+    type: "watermark";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    headSequence: number;
+}> | Readonly<{
+    type: "resyncRequired";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    reason: "retention_gap" | "durable_gap" | "invalid_ack" | "slow_client" | "oversized_frame";
+    headSequence: number;
+}> | Readonly<{
+    type: "applied";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    sequence: number;
+    stateHash: EditableArtifactStateHash;
+}> | Readonly<{
+    type: "authorizationChanged";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    writable: boolean;
+}> | Readonly<{
+    type: "mutationAccepted";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    requestHash: EditableArtifactRequestHash;
+    clientTransactionId: EditableArtifactClientTransactionId;
+    transactionId: EditableArtifactTransactionId;
+    startSequence: number;
+    endSequence: number;
+    stateHash: EditableArtifactStateHash;
+}> | Readonly<{
+    type: "mutationRejected";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    requestHash: EditableArtifactRequestHash;
+    code: "invalid_request" | "forbidden" | "conflict" | "unsupported" | "unavailable";
+    retryable: boolean;
+}>;
+export type EditableArtifactLiveOpenWireFrame = Readonly<{
+    type: "open";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    token: string;
+    resume: EditableArtifactLiveResume;
+}>;
+export type EditableArtifactLiveAppliedWireFrame = Readonly<{
+    type: "applied";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    sequence: number;
+    stateHash: EditableArtifactStateHash;
+}>;
+export type EditableArtifactLiveMutationWireFrame = Readonly<{
+    type: "mutation";
+    protocolVersion: number;
+    artifactId: EditableArtifactId;
+    streamEpoch: string;
+    requestHash: EditableArtifactRequestHash;
+    /** Exact OGATX001 bytes. No client-authored operation/state projection exists. */
+    intentBytes: Uint8Array;
+}>;
+export type EditableArtifactLiveClientWireFrame = EditableArtifactLiveOpenWireFrame | EditableArtifactLiveAppliedWireFrame | EditableArtifactLiveMutationWireFrame;
+/**
+ * One bounded binary WebSocket envelope. Metadata is strict canonical JSON;
+ * snapshots, OGATX intents, and committed OGACO transactions remain opaque
+ * binary payloads and are never base64-encoded or reserialized by transport.
+ */
+export declare function decodeEditableArtifactLiveClientWireFrame(bytes: Uint8Array): EditableArtifactLiveClientWireFrame;
+export declare function encodeEditableArtifactLiveOpenWireFrame(frame: EditableArtifactLiveOpenWireFrame): Uint8Array;
+export declare function encodeEditableArtifactLiveAppliedWireFrame(frame: EditableArtifactLiveAppliedWireFrame): Uint8Array;
+export declare function encodeEditableArtifactLiveMutationWireFrame(frame: EditableArtifactLiveMutationWireFrame): Uint8Array;
+export declare function encodeEditableArtifactLiveServerWireFrame(frame: EditableArtifactLiveServerFrame): Uint8Array;
+/** Strict inverse used by browser/desktop SDK transports. */
+export declare function decodeEditableArtifactLiveServerWireFrame(bytes: Uint8Array): EditableArtifactLiveServerFrame;
+/** Header-level inspection for transport tests and SDK adapters. */
+export declare function inspectEditableArtifactLiveWireEnvelope(bytes: Uint8Array): Readonly<{
+    kind: number;
+    metadata: Readonly<Record<string, unknown>>;
+    payload: Uint8Array;
+}>;
+export {};