@voltro/protocol 0.51.0 → 0.53.0

package/dist/index.d.ts

@@ -136,6 +136,8 @@ export declare interface AppliedScopes {
     readonly removed: ReadonlyArray<string>;
 }
 
+export declare const applyRowPatch: (prev: ReadonlyArray<PatchRow>, patch: RowPatch, options?: ApplyRowPatchOptions) => ReadonlyArray<PatchRow>;
+
 /**
  * Apply a `RowPatch` to `prev`, producing `next`. Exact inverse of
  * `diffRows`: `applyRowPatch(prev, diffRows(prev, next))` deep-equals
@@ -149,7 +151,18 @@ export declare interface AppliedScopes {
  * an `add`) is skipped rather than throwing, so one dropped frame degrades
  * to a slightly stale set instead of a crash.
  */
-export declare const applyRowPatch: (prev: ReadonlyArray<PatchRow>, patch: RowPatch) => ReadonlyArray<PatchRow>;
+export declare interface ApplyRowPatchOptions {
+    /**
+     * The CRDT downstream lane's applier half: fold a `mergeCells` update into
+     * the held cell value. Injected (the patch layer is CRDT-library-free);
+     * `@voltro/local-first` provides the real one. When absent, a `mergeCells`
+     * op REPLACES the cell with the update — wrong for a true incremental
+     * update, which is why the producer only emits `mergeCells` toward
+     * consumers that negotiated it; the fallback keeps an unpaired frame from
+     * crashing the applier.
+     */
+    readonly mergeCell?: (column: string, prevValue: unknown, update: unknown) => unknown;
+}
 
 /**
  * Apply a decision to a Subject, touching nothing but `scopes`.
@@ -902,6 +915,15 @@ export declare interface ConnectionInfoValue {
      * doc comment that claims otherwise.
      */
     readonly credentialExpiresAt?: number;
+    /**
+     * The per-CALL `voltro-resume-from` request header, parsed: the last
+     * subscription revision the client materialised before it lost the
+     * connection. Read by `bindSubscription` to attempt a delta-resume — the
+     * server replays only the missed deltas when the retained ring still
+     * chains this revision, and falls back to a fresh snapshot otherwise.
+     * Absent when the client did not ask to resume (a fresh subscribe).
+     */
+    readonly resumeFrom?: number;
 }
 
 /** The two credential shapes a connection can hold. `oauth2` = an
@@ -1623,6 +1645,13 @@ export declare const defineStream: <const Name extends string, Input extends Sch
     readonly openAccess?: string;
 }) => StreamProcedureDescriptor<Name, Input, Element, Error>;
 
+/**
+ * Declare a raw WebSocket gateway (`*.ws.ts` default export). Validation at
+ * DEFINITION time — a bad path fails the boot that discovers it, not the
+ * first client.
+ */
+export declare const defineWebSocket: (route: WebSocketGatewayRoute) => WebSocketGatewayRoute;
+
 export declare interface DeleteTarget<Input = unknown> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'delete';
@@ -1631,6 +1660,8 @@ export declare interface DeleteTarget<Input = unknown> extends NestedTargetField
     readonly identify?: ((input: Input) => string | ReadonlyArray<string>) | undefined;
 }
 
+export declare const diffRows: (prev: ReadonlyArray<PatchRow>, next: ReadonlyArray<PatchRow>, options?: DiffRowsOptions) => RowPatch;
+
 /**
  * Compute the patch that turns `prev` into `next`, keyed by row id.
  *
@@ -1646,7 +1677,22 @@ export declare interface DeleteTarget<Input = unknown> extends NestedTargetField
  * id-keyed result sets; a result without ids must ship a full snapshot,
  * not a patch.
  */
-export declare const diffRows: (prev: ReadonlyArray<PatchRow>, next: ReadonlyArray<PatchRow>) => RowPatch;
+export declare interface DiffRowsOptions {
+    /**
+     * The CRDT downstream lane. `columns` names the CRDT-managed columns of
+     * this row set; `incremental(column, prevValue, nextValue)` returns the
+     * SMALL update a holder of prevValue needs to reach nextValue (or
+     * `undefined` to fall back to a plain replace — e.g. a prev the encoder
+     * cannot read). When a changed row's CRDT cells are the only change, the
+     * diff emits ONE `mergeCells` op; when scalars changed too, the `replace`
+     * carries the row WITHOUT its CRDT columns and the `mergeCells` op rides
+     * beside it.
+     */
+    readonly crdt?: {
+        readonly columns: ReadonlySet<string>;
+        readonly incremental: (column: string, prevValue: unknown, nextValue: unknown) => unknown | undefined;
+    };
+}
 
 /**
  * The caller's effective scope set — the merged set published by rbac if
@@ -1996,6 +2042,17 @@ export declare type ExtraErrors = ReadonlyArray<Schema.Schema.All>;
 /** Release a claim after the handler errored, so a retry can re-process. */
 export declare const failIdempotent: (store: IdempotencyStore, scope: string, key: string) => Promise<void>;
 
+/**
+ * The field-addressed issues carried by a wire error, or `[]` when the error
+ * is not field-routable. ONE reader for all three shapes — `ValidationError`,
+ * `ValidationErrors`, and a `BusinessRuleViolation` whose rule pinpointed a
+ * `field` — so the form binding, `<AutoForm>`, and any custom widget kit
+ * cannot disagree about which errors belong on a field. A
+ * `BusinessRuleViolation` WITHOUT a field is form-level, not field-level, and
+ * correctly stays in `submitError`.
+ */
+export declare const fieldIssuesOf: (error: unknown) => ReadonlyArray<ValidationIssueShape>;
+
 /**
  * Report descriptors whose `guards:` declare a per-resource check that nothing
  * will enforce.
@@ -2027,6 +2084,11 @@ export declare const finishIdempotent: (store: IdempotencyStore, scope: string,
 /** A route rendered for humans — logs, the inspect surface, the dashboard. */
 export declare const formatEventRoute: (route: string) => string;
 
+/** Close code a gateway connection receives when its credential expires —
+ *  the same session-expiry contract the rpc socket has (SEC-16), spelled as
+ *  an application close code so foreign clients can reauth + reconnect. */
+export declare const GATEWAY_CREDENTIAL_EXPIRED_CLOSE_CODE = 4001;
+
 /** The currently-registered policy-guard resolver, or `undefined`. */
 export declare const getPolicyGuardResolver: () => PolicyGuardResolver | undefined;
 
@@ -2290,6 +2352,8 @@ export declare const inputLabel: (procedure?: string, guarded?: boolean) => stri
 export declare interface InsertTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'insert';
+    /** Declared junction relations — see {@link TargetRelations}. */
+    readonly relations?: TargetRelations | undefined;
     readonly order?: 'prepend' | 'append' | undefined;
     /**
      * Build the optimistic row from the mutation input. The framework
@@ -2869,6 +2933,16 @@ export declare interface PluginEnvVar {
     readonly description?: string;
     /** Example value for `.env.example`. Never a real secret. */
     readonly example?: string;
+    /**
+     * Set ONLY when the secret is OURS to invent (a signing key, a VAPID scalar)
+     * — `voltro dev` then mints a per-project value into the gitignored
+     * `.env.local`, exactly like an app-declared `envVar.secret({ generate })`.
+     * `p256` mints a base64url raw P-256 private scalar (web push VAPID).
+     * NEVER set it for a third-party credential: an invented value merely looks
+     * right, and the boot failure is the useful outcome. Minting stays dev-only —
+     * in production a missing secret refuses the boot.
+     */
+    readonly generate?: 'base64url' | 'hex' | 'p256';
 }
 
 /**
@@ -2897,12 +2971,19 @@ export declare interface PluginErrorSchema {
 
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 export declare interface PluginHttpRoute {
-    /** HTTP method, or `'*'` for any (the handler decides). */
-    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** HTTP method, or `'*'` for any (the handler decides). PATCH/HEAD/OPTIONS
+     *  are first-class — the REST desugar used to mount `'*'` partly BECAUSE
+     *  this union lacked PATCH; that reason is gone (the `'*'` mount remains
+     *  for its other job: one dispatcher per shared path + a precise 405). */
+    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
     /** Absolute path prefix, e.g. `/_voltro/storage`. Matches the path AND
      *  any sub-path (`/_voltro/storage/abc123`). */
     readonly path: string;
     readonly handle: (req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+    /** Per-route body cap override (bytes) — wins over the listener's shared
+     *  `maxBodyBytes`. NOTE: routes SHARING a path share one body read, so the
+     *  widest override on the path's group applies to the whole group. */
+    readonly maxBodyBytes?: number;
     /**
      * Opt this route's path OUT of the listener's cross-site origin check.
      *
@@ -2941,6 +3022,21 @@ export declare interface PluginHttpRoute {
     readonly originGuard?: 'exempt';
 }
 
+/**
+ * A binary streaming body — the download/export shape. The serve layer pipes
+ * the Web ReadableStream to the socket without buffering, so a response
+ * larger than the heap is fine; the LAZY thunk form defers opening the
+ * source (a provider connection, a file handle) until the response actually
+ * streams.
+ */
+export declare interface PluginHttpRouteByteStream {
+    readonly stream: ReadableStream<Uint8Array> | (() => ReadableStream<Uint8Array>);
+    /** Declared up front when known — lets the client render progress. */
+    readonly contentLength?: number;
+    /** e.g. `attachment; filename="export.zip"`. */
+    readonly contentDisposition?: string;
+}
+
 export declare interface PluginHttpRouteRequest {
     readonly method: string;
     /** Path WITHOUT query string. */
@@ -3052,6 +3148,12 @@ export declare interface PluginHttpRouteResult {
     /** Stream the response (SSE) instead of sending `body`. See
      *  {@link PluginHttpRouteStream}. */
     readonly stream?: PluginHttpRouteStream;
+    /** Stream a BINARY response (a download, an export) instead of sending
+     *  `body` — see {@link PluginHttpRouteByteStream}. Never buffered by the
+     *  serve layer; never compressed (flush timing + Content-Length are the
+     *  contract). Takes precedence over `body`; do not set both `stream` and
+     *  `byteStream`. */
+    readonly byteStream?: PluginHttpRouteByteStream;
 }
 
 /**
@@ -3697,6 +3799,10 @@ export declare const queryToRpc: <Name extends string, Input extends Schema.Sche
         }>, Schema.Struct<{
             op: Schema.Literal<["remove"]>;
             path: typeof Schema.String;
+        }>, Schema.Struct<{
+            op: Schema.Literal<["mergeCells"]>;
+            path: typeof Schema.String;
+            value: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
         }>]>>;
         order: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
     }>;
@@ -3836,6 +3942,19 @@ export declare type RowPatchOp = {
 } | {
     readonly op: 'remove';
     readonly path: string;
+}
+/** The CRDT downstream lane (plan 18): cell-level MERGE instead of
+*  replace. `value` maps column → an INCREMENTAL encoded update (what the
+*  subscriber is missing relative to the previous delivery, not the full
+*  document), and the applier folds it into the held cell with the
+*  injected merger. This is what keeps a 1-character edit ≤1KB on the
+*  subscription wire regardless of document size. A `mergeCells` op may
+*  accompany a `replace` on the same row — the replace then carries the
+*  row WITHOUT its CRDT columns. */
+| {
+    readonly op: 'mergeCells';
+    readonly path: string;
+    readonly value: Readonly<Record<string, unknown>>;
 };
 
 export declare const rowPatchOpSchema: Schema.Union<[Schema.Struct<{
@@ -3865,6 +3984,10 @@ export declare const rowPatchOpSchema: Schema.Union<[Schema.Struct<{
 }>, Schema.Struct<{
     op: Schema.Literal<["remove"]>;
     path: typeof Schema.String;
+}>, Schema.Struct<{
+    op: Schema.Literal<["mergeCells"]>;
+    path: typeof Schema.String;
+    value: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
 }>]>;
 
 export declare const rowPatchSchema: Schema.Struct<{
@@ -3895,6 +4018,10 @@ export declare const rowPatchSchema: Schema.Struct<{
     }>, Schema.Struct<{
         op: Schema.Literal<["remove"]>;
         path: typeof Schema.String;
+    }>, Schema.Struct<{
+        op: Schema.Literal<["mergeCells"]>;
+        path: typeof Schema.String;
+        value: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
     }>]>>;
     order: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
 }>;
@@ -4483,6 +4610,10 @@ export declare const subscriptionEvent: <D extends Schema.Schema.Any>(data: D) =
         }>, Schema.Struct<{
             op: Schema.Literal<["remove"]>;
             path: typeof Schema.String;
+        }>, Schema.Struct<{
+            op: Schema.Literal<["mergeCells"]>;
+            path: typeof Schema.String;
+            value: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
         }>]>>;
         order: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
     }>;
@@ -4573,6 +4704,22 @@ declare const TableValidationFailed_base: Schema.TaggedErrorClass<TableValidatio
 
 export declare type Target<Input = unknown, Row = unknown> = TargetSpec<Input, Row> | ReadonlyArray<TargetSpec<Input, Row>>;
 
+/**
+ * Declared many-to-many RELATIONS of a write target: `{ inputField:
+ * junctionTable }`. After the executor succeeds — inside the SAME
+ * transaction — the framework reconciles the junction's links for the
+ * written row against `input[inputField]` (an array of target ids) via the
+ * diff-based `store.relationLinks`, so a form's multi-reference field saves
+ * in one mutation with no hand-written junction code. The anchor column is
+ * derived from the junction's `reference()` targets (a self-junction is
+ * refused, never guessed).
+ *
+ * An ABSENT input field leaves the links untouched (absent ≠ empty — an
+ * empty array is the explicit "clear them all"). The row id is the
+ * executor's `output.id`, falling back to `input.id`.
+ */
+export declare type TargetRelations = Readonly<Record<string, string>>;
+
 export declare type TargetSpec<Input = unknown, Row = unknown> = InsertTarget<Input, Row> | UpdateTarget<Input, Row> | DeleteTarget<Input>;
 
 /**
@@ -4685,6 +4832,10 @@ export declare const toRpc: <Name extends string, Input extends Schema.Schema.An
         }>, Schema.Struct<{
             op: Schema.Literal<["remove"]>;
             path: typeof Schema.String;
+        }>, Schema.Struct<{
+            op: Schema.Literal<["mergeCells"]>;
+            path: typeof Schema.String;
+            value: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
         }>]>>;
         order: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
     }>;
@@ -4836,6 +4987,8 @@ export declare const undoRedoDescriptor: MutationProcedureDescriptor<"__voltro.u
 export declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'update';
+    /** Declared junction relations — see {@link TargetRelations}. */
+    readonly relations?: TargetRelations | undefined;
     /** Identify the row(s) to patch. Default: `input.id`. Return an ARRAY to patch
      *  MANY rows/items in one mutation (a bulk edit — where the per-item
      *  parallel-write race lived). */
@@ -4848,6 +5001,52 @@ export declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Rec
     readonly shapeItem?: ((input: Input, current: Item) => Item) | undefined;
 }
 
+/**
+ * A server-side validation failure pinned to ONE field.
+ *
+ *     return yield* ctx.validation.fail('email', 'validation.emailTaken')
+ *
+ * Routed by the form binding to `errors.email`; the mutation's transaction is
+ * rolled back (or, thrown before any write, never opened).
+ */
+export declare class ValidationError extends ValidationError_base {
+}
+
+declare const ValidationError_base: Schema.TaggedErrorClass<ValidationError, "ValidationError", {
+    readonly _tag: Schema.tag<"ValidationError">;
+} & {
+    field: typeof Schema.String;
+    message: typeof Schema.String;
+    params: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>;
+
+/** Several field-addressed failures at once — one round trip, every field
+ *  marked. `issues` is non-empty by construction (`ctx.validation.failAll`
+ *  refuses an empty list rather than shipping a failure with nothing to show). */
+export declare class ValidationErrors extends ValidationErrors_base {
+}
+
+declare const ValidationErrors_base: Schema.TaggedErrorClass<ValidationErrors, "ValidationErrors", {
+    readonly _tag: Schema.tag<"ValidationErrors">;
+} & {
+    issues: Schema.filter<Schema.Array$<Schema.Struct<{
+        field: typeof Schema.String;
+        message: typeof Schema.String;
+        params: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    }>>>;
+}>;
+
+/** One field-addressed validation issue: `field` is the form path
+ *  (`'email'`, `'address.city'`, `'entries.0.startsAt'`), `message` is a
+ *  message id (or verbatim text), `params` feed the message template. */
+export declare const ValidationIssue: Schema.Struct<{
+    field: typeof Schema.String;
+    message: typeof Schema.String;
+    params: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>;
+
+export declare type ValidationIssueShape = Schema.Schema.Type<typeof ValidationIssue>;
+
 export declare interface VoltroPlugin {
     /**
      * Plugin identifier — printed in `voltro dev` boot logs + surfaced in
@@ -5216,6 +5415,48 @@ export declare interface VoltroPlugin {
 export declare interface VoltroTableNames {
 }
 
+/** What a gateway's connection handler receives. Transport-agnostic on
+ *  purpose — the runtime adapts the platform socket to this. */
+export declare interface WebSocketGatewayConnection {
+    /** Send a text or binary frame. */
+    readonly send: (data: string | Uint8Array) => void;
+    /** Close the connection (application close codes 4000-4999 are yours). */
+    readonly close: (code?: number, reason?: string) => void;
+    /** Register a message listener (binary-safe; text arrives as bytes). */
+    readonly onMessage: (listener: (data: Uint8Array) => void) => void;
+    /** The authenticated subject — `null` only on an `auth: 'public'` route. */
+    readonly subject: Subject | null;
+    /** Lowercased request headers of the upgrade. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The mounted path. */
+    readonly path: string;
+}
+
+export declare interface WebSocketGatewayRoute {
+    /** Absolute upgrade path (`/gateways/yjs`). Must not collide with the rpc
+     *  socket (`/ws` or the configured `transport.wsPath`) or `/rpc`. */
+    readonly path: `/${string}`;
+    /**
+     * REQUIRED, no default: who may connect.
+     * - `'subject'` — the upgrade resolves a Subject through the SAME auth
+     *   chain as rpc/SSR (cookie/bearer); an unauthenticated upgrade is a 401
+     *   BEFORE any socket exists, and the connection closes with
+     *   {@link GATEWAY_CREDENTIAL_EXPIRED_CLOSE_CODE} when the credential
+     *   expires.
+     * - `'public'` — deliberately unauthenticated (a device fleet with its own
+     *   protocol-level auth). A decision somebody wrote down, not a default.
+     */
+    readonly auth: 'subject' | 'public';
+    /**
+     * Runs once per accepted connection. The returned function is the
+     * connection's TEARDOWN — taken at construction (the `startOutboxRunner`
+     * rule): it runs on client disconnect, on credential expiry, and on
+     * server shutdown, so whatever the handler opened cannot outlive the
+     * socket.
+     */
+    readonly onConnection: (connection: WebSocketGatewayConnection) => void | (() => void) | Promise<void | (() => void)>;
+}
+
 /**
  * The error union a procedure ACTUALLY puts on the wire — `descriptor.error`
  * plus everything the framework can produce for it before or around the