@gonvex/protocol 0.1.31 → 0.3.0

package/README.md

@@ -30,7 +30,7 @@ The package includes:
 - function manifest types
 - WebSocket client and server message unions
 - live-query result, progress, patch, and revision frames
-- durable sync open/batch-open, snapshot, delta, reset, ready, and cursor types
+- Replica Collection open/batch-open, snapshot, delta, reset, ready, and cursor types
 - browser telemetry and message trace types
 
 ## Related Packages

package/dist/index.d.ts

@@ -1,15 +1,72 @@
-export type FunctionKind = "query" | "mutation" | "action" | "http" | "internalMutation" | "liveGrid" | "sync";
+export type FunctionKind = "query" | "reducer" | "action";
+export type ExecutionScope = "tenant" | "control";
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
+/** The recursive, language-neutral value schema used by TypeScript modules. */
+export type ModuleSchema = StringSchema | NumberSchema | BooleanSchema | NullSchema | AnySchema | IdSchema | LiteralSchema | ArraySchema | ObjectSchema | RecordSchema | OptionalSchema;
+export type StringSchema = {
+    kind: "string";
+    format?: "email" | "uri" | "uuid" | "datetime";
+    minLength?: number;
+    maxLength?: number;
+};
+export type NumberSchema = {
+    kind: "number";
+    integer?: boolean;
+    minimum?: number;
+    maximum?: number;
+};
+export type BooleanSchema = {
+    kind: "boolean";
+};
+export type NullSchema = {
+    kind: "null";
+};
+export type AnySchema = {
+    kind: "any";
+};
+export type IdSchema = {
+    kind: "id";
+    entity: string;
+};
+export type LiteralSchema = {
+    kind: "literal";
+    value: JsonValue;
+};
+export type ArraySchema = {
+    kind: "array";
+    items: ModuleSchema;
+};
+export type ObjectSchema = {
+    kind: "object";
+    fields: Record<string, ModuleSchema>;
+    allowUnknown?: boolean;
+};
+export type RecordSchema = {
+    kind: "record";
+    values: ModuleSchema;
+};
+export type OptionalSchema = {
+    kind: "optional";
+    value: ModuleSchema;
+};
 export type FunctionManifestEntry = {
     kind: FunctionKind;
     handler: string;
     file: string;
+    args?: ModuleSchema;
+    result?: ModuleSchema;
+    internal?: boolean;
+    delivery?: "oneShot" | "live" | "replica";
     dependencies?: FunctionDependencies;
-    sync?: SyncDefinition;
+    replica?: ReplicaCollectionDefinition;
+    /** Reducer delivery policy declared by a TypeScript module. */
+    offline?: JsonValue;
+    /** Ordered atomic optimistic transaction declared by a TypeScript module. */
+    optimistic?: JsonValue;
 };
-export type SyncDefinition = {
+export type ReplicaCollectionDefinition = {
     table: string;
     key: string;
     columns: string[];
@@ -23,30 +80,68 @@ export type SyncDefinition = {
     maxBytes?: number;
     retentionMs?: number;
 };
-export type SyncCursor = {
+export type ReplicaCursor = {
     epoch: string;
     revision: number;
 };
+export type ReplicaChange = {
+    entity: string;
+    id: string;
+    operation: "insert" | "update" | "delete";
+    oldValue?: JsonValue;
+    newValue?: JsonValue;
+    changedColumns?: string[];
+};
 export type FunctionDependencies = {
-    reads?: Array<{
-        table: string;
-        columns?: string[];
-        filters?: string[];
-        ordersBy?: string[];
-        windowed?: boolean;
-        predicate?: string;
-    }>;
-    writes?: Array<{
-        table: string;
-        columns?: string[];
-    }>;
-    readsEphemeral?: boolean;
-    writesEphemeral?: boolean;
     shareByPermissions?: boolean;
-    shareByVisibility?: string;
+    liveQueryPlan?: LiveQueryPlan;
+    nonOptimisticReason?: string;
     shareResultFrom?: string;
     shareResultField?: string;
 };
+export type LiveQueryPlan = {
+    table: string;
+    key: string;
+    columns?: string[];
+    resultPath?: string[];
+    where?: LiveExpression;
+    search?: {
+        argument: string;
+        columns: string[];
+    };
+    filters?: {
+        argument: string;
+        allowedColumns: string[];
+        allowedOperators: FilterOperator[];
+    };
+    sort?: {
+        columnArgument: string;
+        directionArgument: string;
+        defaultColumn: string;
+        defaultDirection: "asc" | "desc";
+        allowedColumns: string[];
+    };
+    window?: {
+        offsetArgument: string;
+        limitArgument: string;
+        defaultLimit: number;
+        maxLimit: number;
+        count?: "exact";
+    };
+    serverOnly?: boolean;
+};
+export type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "empty" | "notEmpty" | "oneOf" | "lessThan" | "lessThanOrEqual" | "greaterThan" | "greaterThanOrEqual" | "inRange";
+export type LiveExpression = {
+    operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "contains" | "containsInsensitive" | "range" | "and" | "or" | "not" | "server";
+    column?: string;
+    value?: LiveValue;
+    valueTo?: LiveValue;
+    children?: LiveExpression[];
+};
+export type LiveValue = {
+    argument?: string;
+    literal?: JsonValue;
+};
 export type SubscriptionRevision = {
     epoch: string;
     sequence: number;
@@ -54,8 +149,8 @@ export type SubscriptionRevision = {
 export type MessageTrace = {
     clientSentAtMs?: number;
     serverReceivedAtMs?: number;
-    serverMutationStartedAtMs?: number;
-    serverMutationCommittedAtMs?: number;
+    serverReducerStartedAtMs?: number;
+    serverReducerCommittedAtMs?: number;
     serverCompletedAtMs?: number;
     serverBroadcastScheduledAtMs?: number;
     serverChangeCommittedAtMs?: number;
@@ -81,71 +176,69 @@ export type BrowserTelemetryInfo = {
     connectionType?: string;
     effectiveConnectionType?: string;
 };
-export type QueryCacheDirective = {
+export type ReplicaDirective = {
     protocolVersion: 1;
     scope: string;
-    /**
-     * Visibility-only scope (project/tenant/user/permissions, no code epoch)
-     * under which sync collections are persisted and resumed. Unlike `scope`,
-     * it survives deploys; resume safety comes from the server's authoritative
-     * reconcile. Absent on runtimes that predate deploy-stable sync scopes.
-     */
-    syncScope?: string;
+    /** Visibility-only scope for persistent, authoritatively reconciled rows. */
+    visibilityScope: string;
     epoch: string;
-    maxAgeMs: number;
 };
 export type ServerCapabilities = {
     /** WebSocket protocol generation implemented by this runtime. */
     protocolVersion?: number;
     /** Exact runtime build identifier, normally the deployed Git commit SHA. */
     runtimeVersion?: string;
-    syncBatch?: 1;
-    /** sync.ready frames always carry a collection integrity digest. */
-    syncIntegrity?: 1;
+    replicaBatch?: 1;
+    /** replica.ready frames always carry a collection integrity digest. */
+    replicaIntegrity?: 1;
     /** Server accepts `query.subscribeMany` batched subscription frames. */
     queryBatch?: 1;
     /** Server emits several independent query updates in one WebSocket frame. */
     queryResultBatch?: 1;
-    /** Server accepts `mutation.callMany` batched offline-queue flushes. */
-    mutationBatch?: 1;
-    /** Server emits connection-level sync revision watermarks. */
-    syncWatermark?: 1;
+    /** Server accepts `reducer.callMany` batched command-outbox flushes. */
+    reducerBatch?: 1;
+    /** Server emits connection-level replica revision watermarks. */
+    replicaWatermark?: 1;
 };
 export type QuerySubscribeRequest = {
     id: string;
     path: string;
     args: JsonValue;
-    cacheRevision?: string;
+    scope?: ExecutionScope;
+    windowRevision?: string;
 };
-export type MutationCallRequest = {
+export type ReducerCallRequest = {
     id: string;
     path: string;
     args: JsonValue;
+    scope?: ExecutionScope;
     trace?: MessageTrace;
+    /** Stable key for a replayable command; see the `reducer.call` message. */
+    idempotencyKey?: string;
 };
-export type SyncOpenRequest = {
+export type ReplicaOpenRequest = {
     id: string;
     path: string;
     args: JsonValue;
-    cursor?: SyncCursor;
+    cursor?: ReplicaCursor;
     keys?: string[];
     hashes?: Record<string, string>;
     digest?: string;
     fullIntegrity?: boolean;
 };
-export type SyncReady = {
+export type ReplicaReady = {
     id: string;
     path?: string;
-    cursor: SyncCursor;
+    cursor: ReplicaCursor;
     mode?: "eager" | "progressive";
-    digest?: string;
+    digest: string;
     truncated?: boolean;
 };
 export type ClientCapabilities = {
-    /** Client accepts coalesced `sync.readyMany` server frames. */
-    syncReadyMany?: 1;
-    /** Client accepts connection-level `sync.watermark` server frames. */
-    syncWatermark?: 1;
+    /** Client accepts coalesced `replica.readyMany` server frames. */
+    replicaReadyMany?: 1;
+    /** Client accepts connection-level `replica.watermark` server frames. */
+    replicaWatermark?: 1;
     /** Client accepts keyed patches for object results with a `page` row array. */
     queryPagePatch?: 1;
     /** Client atomically applies keyed patches to named arrays in object results. */
@@ -177,57 +270,86 @@ export type ClientMessage = {
     token?: string;
     project?: string;
     tenant?: string;
+    controlOnly?: boolean;
     device?: BrowserTelemetryInfo;
     capabilities?: ClientCapabilities;
+} | {
+    type: "query.call";
+    id: string;
+    path: string;
+    args: JsonValue;
+    scope?: ExecutionScope;
 } | {
     type: "query.subscribe";
     id: string;
     path: string;
     args: JsonValue;
-    cacheRevision?: string;
+    scope?: ExecutionScope;
+    windowRevision?: string;
 } | {
     type: "query.unsubscribe";
     id: string;
 } | {
-    type: "sync.open";
+    type: "replica.open";
     id: string;
     path: string;
     args: JsonValue;
-    cursor?: SyncCursor;
+    cursor?: ReplicaCursor;
     keys?: string[];
     hashes?: Record<string, string>;
     digest?: string;
     fullIntegrity?: boolean;
 } | {
-    type: "sync.openMany";
-    opens: SyncOpenRequest[];
+    type: "replica.openMany";
+    opens: ReplicaOpenRequest[];
 } | {
     type: "query.subscribeMany";
     subscribes: QuerySubscribeRequest[];
 } | {
-    type: "sync.close";
+    type: "replica.close";
     id: string;
 } | {
-    type: "mutation.call";
+    type: "reducer.call";
     id: string;
     path: string;
     args: JsonValue;
+    scope?: ExecutionScope;
     trace?: MessageTrace;
+    /**
+     * Stable key for a replayable command from the client outbox. The runtime
+     * executes the reducer once per key and serves the stored result to
+     * every duplicate delivery.
+     */
+    idempotencyKey?: string;
 } | {
-    type: "mutation.callMany";
-    calls: MutationCallRequest[];
+    type: "reducer.callMany";
+    calls: ReducerCallRequest[];
 } | {
     type: "action.call";
     id: string;
     path: string;
     args: JsonValue;
+    scope?: ExecutionScope;
+    idempotencyKey?: string;
     trace?: MessageTrace;
+} | {
+    type: "error.register";
+    id: string;
+    release?: string;
+    environment?: string;
+} | {
+    type: "error.envelope";
+    id: string;
+    events: JsonValue[];
+} | {
+    type: "error.heartbeat";
+    id: string;
 } | {
     type: "telemetry.event";
     id: string;
-    kind: "query" | "mutation" | "action";
+    kind: "query" | "reducer" | "action";
     path: string;
-    reason?: "initial" | "invalidate" | "recover";
+    reason?: "initial" | "change" | "recover";
     outcome: "ok" | "error";
     error?: string;
     clientSentAtMs?: number;
@@ -245,10 +367,10 @@ export type ServerMessage = {
     ids: string[];
     path?: string;
     result?: JsonValue;
-    reason?: "initial" | "invalidate" | "recover";
+    reason?: "initial" | "change" | "recover";
     trace?: MessageTrace;
-    cacheScope?: string;
-    cacheRevision?: string;
+    replicaScope?: string;
+    windowRevision?: string;
     subscriptionRevision?: SubscriptionRevision;
     baseRevision?: SubscriptionRevision;
     throughRevision?: SubscriptionRevision;
@@ -259,16 +381,18 @@ export type ServerMessage = {
     prepend?: string[];
     append?: string[];
     collections?: Record<string, KeyedCollectionPatch>;
-    mutationIds?: string[];
+    originCommandIds?: string[];
+} | {
+    type: "replica.transaction";
+    cursor: ReplicaCursor;
+    originCommandId?: string;
+    changes: ReplicaChange[];
 } | {
     type: "session.ready";
     project?: string;
     tenant?: string;
-    queryCache?: QueryCacheDirective;
+    replica?: ReplicaDirective;
     capabilities?: ServerCapabilities;
-} | {
-    type: "session.scope";
-    queryCache?: QueryCacheDirective;
 } | {
     type: "auth.result";
     id: string;
@@ -277,30 +401,40 @@ export type ServerMessage = {
     type: "auth.error";
     id: string;
     error: string;
+} | {
+    type: "error.ack";
+    id: string;
+    accepted?: number;
+    fingerprints?: string[];
+    error?: string;
+} | {
+    type: "support.command";
+    id: string;
+    result: JsonValue;
 } | {
     type: "query.result";
     id: string;
     path?: string;
     result: JsonValue;
-    reason?: "initial" | "invalidate" | "recover";
+    reason?: "initial" | "change" | "recover";
     trace?: MessageTrace;
-    cacheScope?: string;
-    cacheRevision?: string;
+    replicaScope?: string;
+    windowRevision?: string;
     subscriptionRevision?: SubscriptionRevision;
-    mutationIds?: string[];
+    originCommandIds?: string[];
 } | {
     type: "query.progress";
     id: string;
     path?: string;
-    reason?: "initial" | "invalidate" | "recover";
+    reason?: "initial" | "change" | "recover";
     throughRevision: SubscriptionRevision;
     trace?: MessageTrace;
-    mutationIds?: string[];
+    originCommandIds?: string[];
 } | {
     type: "query.patch";
     id: string;
     path?: string;
-    reason?: "initial" | "invalidate" | "recover";
+    reason?: "initial" | "change" | "recover";
     baseRevision: SubscriptionRevision;
     subscriptionRevision: SubscriptionRevision;
     inserted?: JsonValue[];
@@ -309,15 +443,15 @@ export type ServerMessage = {
     order?: string[];
     prepend?: string[];
     append?: string[];
-    cacheScope?: string;
-    cacheRevision?: string;
+    replicaScope?: string;
+    windowRevision?: string;
     trace?: MessageTrace;
-    mutationIds?: string[];
+    originCommandIds?: string[];
 } | {
     type: "query.pagePatch";
     id: string;
     path?: string;
-    reason?: "initial" | "invalidate" | "recover";
+    reason?: "initial" | "change" | "recover";
     baseRevision: SubscriptionRevision;
     subscriptionRevision: SubscriptionRevision;
     result?: JsonValue;
@@ -327,28 +461,28 @@ export type ServerMessage = {
     order?: string[];
     prepend?: string[];
     append?: string[];
-    cacheScope?: string;
-    cacheRevision?: string;
+    replicaScope?: string;
+    windowRevision?: string;
     trace?: MessageTrace;
-    mutationIds?: string[];
+    originCommandIds?: string[];
 } | {
     type: "query.objectPatch";
     id: string;
     path?: string;
-    reason?: "initial" | "invalidate" | "recover";
+    reason?: "initial" | "change" | "recover";
     baseRevision: SubscriptionRevision;
     subscriptionRevision: SubscriptionRevision;
     collections: Record<string, KeyedCollectionPatch>;
-    cacheScope?: string;
-    cacheRevision?: string;
+    replicaScope?: string;
+    windowRevision?: string;
     trace?: MessageTrace;
-    mutationIds?: string[];
+    originCommandIds?: string[];
 } | {
-    type: "sync.snapshot";
+    type: "replica.snapshot";
     id: string;
     path?: string;
     result: JsonValue[];
-    cursor: SyncCursor;
+    cursor: ReplicaCursor;
     key: string;
     orderBy?: string;
     orderDirection?: "asc" | "desc";
@@ -357,40 +491,39 @@ export type ServerMessage = {
     maxBytes?: number;
     hashes?: Record<string, string>;
 } | {
-    type: "sync.delta";
+    type: "replica.delta";
     id: string;
     path?: string;
-    cursor: SyncCursor;
+    cursor: ReplicaCursor;
     upserts?: JsonValue[];
     deleted?: string[];
-    mutationIds?: string[];
+    originCommandIds?: string[];
     hashes?: Record<string, string>;
     digest?: string;
 } | ({
-    type: "sync.ready";
-    digest?: string;
-} & SyncReady) | {
-    type: "sync.readyMany";
-    ready: SyncReady[];
+    type: "replica.ready";
+} & ReplicaReady) | {
+    type: "replica.readyMany";
+    ready: ReplicaReady[];
 } | {
-    type: "sync.watermark";
+    type: "replica.watermark";
     revision: number;
 } | {
-    type: "sync.needHashes";
+    type: "replica.needHashes";
     id: string;
     path?: string;
 } | {
-    type: "sync.syncing";
+    type: "replica.syncing";
     id: string;
     path?: string;
     reason: "disconnected" | "reconciling" | "listener-reconnecting" | "integrity-reconciling";
 } | {
-    type: "sync.reset";
+    type: "replica.reset";
     id: string;
     path?: string;
     reason: "cursor-expired" | "definition-changed" | "visibility-changed" | "integrity-mismatch" | "integrity-missing" | "recover";
 } | {
-    type: "sync.error";
+    type: "replica.error";
     id: string;
     path?: string;
     error: string;
@@ -400,13 +533,15 @@ export type ServerMessage = {
     path?: string;
     error: string;
 } | {
-    type: "mutation.result";
+    type: "reducer.result";
     id: string;
     path?: string;
     result: JsonValue;
+    originCommandId: string;
+    committedRevision?: number;
     trace?: MessageTrace;
 } | {
-    type: "mutation.error";
+    type: "reducer.error";
     id: string;
     path?: string;
     error: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonvex/protocol",
-  "version": "0.1.31",
+  "version": "0.3.0",
   "type": "module",
   "publishConfig": {
     "access": "public"