@voltro/protocol 0.52.0 → 0.54.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
@@ -1638,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.
  *
@@ -1653,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
@@ -2003,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.
@@ -2302,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
@@ -2881,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';
 }
 
 /**
@@ -3737,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]>>;
     }>;
@@ -3876,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<{
@@ -3905,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<{
@@ -3935,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]>>;
 }>;
@@ -4523,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]>>;
     }>;
@@ -4613,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>;
 
 /**
@@ -4725,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]>>;
     }>;
@@ -4876,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). */
@@ -4888,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