@voltro/runtime 0.51.0 → 0.53.0

package/dist/index.d.ts

@@ -69,6 +69,7 @@ import { RetentionSource } from '@voltro/database';
 import { RetentionSpec } from '@voltro/database';
 import { retentionTtlMsFromEnv } from '@voltro/database';
 import { Row } from '@voltro/database';
+import { RowPatch } from '@voltro/protocol';
 import { Rpc } from '@effect/rpc';
 import { RpcGroup } from '@effect/rpc';
 import { RpcInterceptor } from '@voltro/protocol';
@@ -97,6 +98,9 @@ import { TenantRowNotFound } from '@voltro/protocol';
 import { TenantScopeViolation } from '@voltro/protocol';
 import { Tracer } from 'effect';
 import { Unauthenticated } from '@voltro/protocol';
+import { ValidationError } from '@voltro/protocol';
+import { ValidationErrors } from '@voltro/protocol';
+import { WebSocketGatewayRoute } from '@voltro/protocol';
 import { WorkflowParentClosePolicy } from '@voltro/protocol';
 import { WorkflowRunHandle } from '@voltro/protocol';
 import { WorkflowUpdateResult } from '@voltro/protocol';
@@ -150,6 +154,28 @@ export declare interface ActivitySignals {
     readonly activeWorkflowExecutions: () => number;
 }
 
+/**
+ * Adopt a detached subscription for a resuming client at `fromRevision`.
+ * Undefined — identity unknown, entry dead (an error/revocation while
+ * offline), or the revision does not chain — means: subscribe fresh, send a
+ * snapshot. A failed adoption EXPIRES the entry: its ring cannot serve this
+ * client and keeping a half-dead entry around only risks a second caller
+ * adopting state the first one invalidated.
+ */
+export declare const adoptDetached: (identity: ResumeIdentity, fromRevision: number, now?: number, tunables?: ResumeTunables) => AdoptedSubscription | undefined;
+
+export declare interface AdoptedSubscription {
+    /** The deltas the client missed, in order — replay before going live. */
+    readonly deltas: ReadonlyArray<{
+        readonly revision: number;
+        readonly emittedAt: number;
+        readonly patch: RowPatch;
+    }>;
+    /** Redirect this to the new stream to go live on the SAME revision line. */
+    readonly sink: ResumeSink;
+    readonly unsubscribe: () => void;
+}
+
 export declare interface AggregateContext {
     /** Read-side store for source queries. Note: the build function
      *  runs OUTSIDE any per-request subject, so the auto-stamping a
@@ -807,6 +833,15 @@ export declare interface AnalyticsTopEntry {
     readonly value: number;
 }
 
+/**
+ * Answer a `resumeFrom` for this identity. `fromRevision` is the last
+ * revision the CLIENT materialised. Only revisions inside
+ * [baseRevision, headRevision] chain; everything else — unknown key, aged
+ * ring, a revision the ring no longer covers, a revision AHEAD of the head
+ * (a client from a different life) — is a snapshot.
+ */
+export declare const answerResume: (identity: ResumeIdentity, fromRevision: number, now?: number, tunables?: ResumeTunables) => ResumeAnswer;
+
 declare type AnyRow = Record<string, unknown>;
 
 declare type AnyRow_2 = Record<string, unknown>;
@@ -989,6 +1024,10 @@ export declare interface AppContext {
      *  `ctx.access.has(scope)` / `yield* ctx.access.require(scope)` instead of
      *  reaching into `ctx.request.subject.scopes`. Always present. */
     readonly access: AppAccess;
+    /** Typed server-side field validation — `yield* ctx.validation.fail('email',
+     *  'validation.emailTaken')` routes to the form field that submitted it.
+     *  Always present. */
+    readonly validation: AppValidation;
     /** Cache — always present (memory backend by default). Use
      *  `ctx.cache.wrap(key, { ttlMs, tags }, () => expensive())` to cache
      *  derived work; tagged entries auto-invalidate when a mutation writes a
@@ -1073,6 +1112,28 @@ export declare interface AppContext {
  */
 export declare const applyConnectionCredential: (clientId: number, headers: Record<string, string | undefined>) => Record<string, string | undefined>;
 
+/**
+ * Reconcile a mutation target's declared junction `relations:` against the
+ * input — INSIDE the mutation's transaction, through `ctx.store`, so the
+ * links ride the same undo capture, rule evaluation and rollback as the
+ * mutation's own writes.
+ *
+ * Semantics that must not drift:
+ * - an ABSENT input field touches nothing (absent ≠ empty);
+ * - an empty array is the explicit clear;
+ * - a non-array value is a refusal naming the field — silently ignoring it
+ *   would read as "saved" while the links stayed stale;
+ * - the row id is `output.id`, else `input.id`; with neither the declaration
+ *   is unusable and says so.
+ */
+export declare const applyDeclaredRelations: (params: {
+    readonly store: RelationLinksStore;
+    readonly target: MutationLike["descriptor"]["target"];
+    readonly procedure: string;
+    readonly input: unknown;
+    readonly output: unknown;
+}) => Promise<void>;
+
 /**
  * Pure helper backing `ctx.store.applyDefined`. Picks the listed keys from
  * `input` whose value is not `undefined`, so a PATCH sets exactly the fields
@@ -1219,6 +1280,35 @@ export declare interface AppSupervisor {
     stop: () => Promise<void>;
 }
 
+/** Typed server-side FIELD validation — the executor half of form error
+ *  routing. Each helper fails the procedure with a wire `ValidationError`
+ *  (auto-merged into every mutation's and action's error union), which the
+ *  form binding routes to `errors[field]` instead of `submitError`. */
+export declare interface AppValidation {
+    /** Fail with ONE field error. `message` is a message id
+     *  (`'validation.emailTaken'`) resolved by the client's validation catalog.
+     *
+     *      if (await emailTaken(input.email)) {
+     *        return yield* ctx.validation.fail('email', 'validation.emailTaken')
+     *      }
+     */
+    readonly fail: (field: string, message: string, params?: Record<string, unknown>) => Effect.Effect<never, ValidationError>;
+    /** Fail with several field errors in one round trip. Refuses an empty
+     *  list — a failure with nothing to show is a bug at the call site. */
+    readonly failAll: (issues: ReadonlyArray<{
+        readonly field: string;
+        readonly message: string;
+        readonly params?: Record<string, unknown>;
+    }>) => Effect.Effect<never, ValidationErrors>;
+    /** Guard form: succeed when `condition` holds, else fail the field. */
+    readonly require: (condition: boolean, field: string, message: string, params?: Record<string, unknown>) => Effect.Effect<void, ValidationError>;
+}
+
+/** The ONE `ctx.validation` value. Pure and subject-free, so a single shared
+ *  instance serves every context — request, schedule, workflow, test — and
+ *  the builders cannot each assemble a drifting copy. */
+export declare const appValidation: AppValidation;
+
 /** Effect-style guard for handlers — throws the typed {@link AccessDenied} on a
  *  deny so it surfaces to the client typed. */
 export declare const assertCan: (subject: RebacSubject, action: string, resource: RebacResource, deps: CanDeps) => void;
@@ -1622,7 +1712,14 @@ reauthorize?: (subject: Subject) => () => Promise<unknown>,
  */
 refilter?: (subject: Subject) => () => Promise<RowFilterScope>) => Stream.Stream<SubscriptionEvent<T>, never, SubjectService | ConnectionInfo>;
 
-export declare const bindSubscriptionUntyped: (descriptor: QueryDescriptor, dispatcher: Dispatcher, context: RuntimeContext, indexHint: MatcherIndexHint | undefined, label: string, cacheBinding: SnapshotCacheBinding | undefined, reauthorize: (() => Promise<unknown>) | undefined, refilter?: (() => Promise<RowFilterScope>) | undefined) => Stream.Stream<SubscriptionEvent<ReadonlyArray<Row>>, never, never>;
+export declare const bindSubscriptionUntyped: (descriptor: QueryDescriptor, dispatcher: Dispatcher, context: RuntimeContext, indexHint: MatcherIndexHint | undefined, label: string, cacheBinding: SnapshotCacheBinding | undefined, reauthorize: (() => Promise<unknown>) | undefined, refilter?: (() => Promise<RowFilterScope>) | undefined, backpressure?: {
+    readonly maxBufferedBytes: number;
+    readonly overrunAfterMs: number;
+    readonly oversizedEventBytes: number;
+}, resume?: {
+    readonly input: unknown;
+    readonly fromRevision?: number;
+}) => Stream.Stream<SubscriptionEvent<ReadonlyArray<Row>>, never, never>;
 
 export declare interface BrandedScheduleDefinition extends ScheduleDefinition {
     readonly [SCHEDULE_BRAND]: true;
@@ -1759,6 +1856,8 @@ export declare interface CandidateShape {
     readonly windowed?: boolean;
 }
 
+export declare const canonicalInputKey: (input: unknown) => string;
+
 /* Excluded from this release type: canonicalize */
 
 /**
@@ -2032,6 +2131,22 @@ export declare const composeAnalytics: (specs: ReadonlyArray<AnalyticsSinkSpec>)
  */
 export declare const composeAnalyticsSinks: (sinks: ReadonlyArray<AnalyticsSinkImpl>) => AnalyticsSinkImpl;
 
+export declare interface CompressedResult {
+    readonly bytes: Uint8Array;
+    /** Headers to MERGE onto the response. Always carries Vary for
+     *  compressible types; carries Content-Encoding only when compressed. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly compressed: boolean;
+}
+
+export declare interface CompressionOptions {
+    /** Master switch. Default true. */
+    readonly enabled?: boolean;
+    /** Bodies smaller than this are never compressed (the frame overhead can
+     *  exceed the saving). Default 1024. */
+    readonly minBytes?: number;
+}
+
 declare interface ComputedQuery {
     readonly __voltroComputed: true;
     /** The initial computed value — emitted verbatim as the first snapshot. */
@@ -2800,6 +2915,8 @@ export declare const DEFAULT_APPROVAL_EXPIRY_MS: number;
  *  engine's finest useful cadence. */
 export declare const DEFAULT_CLAIM_BUCKET_MS = 60000;
 
+export declare const DEFAULT_COMPRESSION_MIN_BYTES = 1024;
+
 /**
  * How many subscribers one change event is delivered to CONCURRENTLY.
  *
@@ -2838,6 +2955,10 @@ export declare const DEFAULT_RAW_READ_TRACKING_LIMIT = 32;
 
 export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
 
+export declare const DEFAULT_RESUME_MAX_DELTAS = 256;
+
+export declare const DEFAULT_RESUME_WINDOW_MS = 60000;
+
 /**
  * Retry policy applied to `load` when a filter does not specify one: three
  * attempts total (the initial call plus two retries), backing off exponentially
@@ -2850,6 +2971,14 @@ export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
  */
 export declare const DEFAULT_ROW_FILTER_RETRY: Schedule.Schedule<unknown, unknown>;
 
+/** Defaults, overridable via `app.config.ts` `reactive.socket.*` (+ env) —
+ *  resolved by the boot paths' tunables resolver. */
+export declare const DEFAULT_SOCKET_MAX_BUFFERED_BYTES = 1048576;
+
+export declare const DEFAULT_SOCKET_OVERRUN_AFTER_MS = 10000;
+
+export declare const DEFAULT_SOCKET_OVERSIZED_EVENT_BYTES = 262144;
+
 /**
  * The message of an UNDECLARED throw, bounded, with nothing else attached.
  *
@@ -3055,6 +3184,17 @@ export declare const deliveredRowCount: (value: unknown) => number;
  */
 export declare const deriveKey: (passphrase: string) => Buffer;
 
+/**
+ * Detach a live subscription for possible resume. The sink is redirected to
+ * ring-recording only; after the window the subscription is truly
+ * unsubscribed. If an entry already sits under this identity (an older
+ * incarnation), it is expired first — one identity, one detached entry.
+ */
+export declare const detachForResume: (identity: ResumeIdentity, handle: {
+    readonly sink: ResumeSink;
+    readonly unsubscribe: () => void;
+}, tunables?: ResumeTunables, now?: () => number) => void;
+
 export { DialectReplicationAdapter }
 
 /** Field-level diff for one change. Insert → every field `undefined→value`;
@@ -3235,6 +3375,10 @@ export declare class Dispatcher {
 
 export declare interface DispatcherDependencies {
     readonly store: DataStore;
+    /** CRDT columns per table (schemaRegistry.crdtColumns). Feeds the
+     *  downstream lane: crdt cells diff as incremental mergeCells ops.
+     *  Absent → no crdt tables (tests, embedders) — plain full-value diffs. */
+    readonly crdtColumnsOf?: (table: string) => ReadonlySet<string>;
     /** Optional sink for per-delivery timing. `voltro dev` wires this into
      *  the trace buffer so the dashboards show each data transfer's latency.
      *  No-op when absent (tests, embedders that don't trace). */
@@ -3470,6 +3614,8 @@ export declare const evaluateTouchedRules: (params: {
     readonly subject: unknown;
 }) => Promise<void>;
 
+declare type Event_2 = SubscriptionEvent<ReadonlyArray<Row>>;
+
 /**
  * How many deliveries one client may fall behind before the oldest are dropped.
  *
@@ -4392,6 +4538,14 @@ export declare interface FluentStore extends Omit<MutationStore, 'update' | 'del
      *     await ctx.store.links('post_tags', { postId: post.id }).set(tagIds)
      */
     links(junctionTable: string, anchor: Readonly<Record<string, string>>): JunctionLinks;
+    /**
+     * `links(...)` with the anchor COLUMN derived from the anchored TABLE: the
+     * junction's reference column that points at `anchorTable` becomes the
+     * source. Exactly one column may qualify — a self-junction (both columns
+     * referencing the same table) is refused with the fix, never guessed.
+     * This is what a mutation target's declared `relations:` resolves through.
+     */
+    relationLinks(junctionTable: string, anchorTable: string, anchorId: string): JunctionLinks;
     /**
      * Execute a query descriptor and return the matching rows — TYPED.
      *
@@ -4923,6 +5077,8 @@ export declare const ipToBytes: (ip: string) => Uint8Array | undefined;
 
 export declare const isAggregateDefinition: (value: unknown) => value is AggregateDefinition;
 
+export declare const isCompressibleContentType: (contentType: string | undefined) => boolean;
+
 export declare const isCostBudgetDefinition: (value: unknown) => value is CostBudgetDefinition;
 
 export declare const isEmptyTenantScopedRead: (descriptor: QueryDescriptor, tenantScopedTables: ReadonlySet<string>, tenantId: string | null | undefined) => boolean;
@@ -5605,6 +5761,8 @@ export declare const makeSubmitTokenExecutor: (deps: ConnectionBuiltinDeps) => (
     readonly ok: boolean;
 }>;
 
+export declare const makeSubscriptionOutbox: (options: SubscriptionBackpressureOptions) => SubscriptionOutbox;
+
 /**
  * The factory the serve entrypoints inject into `makeMutationRunner`'s
  * `undoCapture` dep. Collects changes from the wrapped tx; `persist` writes ONE
@@ -5612,7 +5770,7 @@ export declare const makeSubmitTokenExecutor: (deps: ConnectionBuiltinDeps) => (
  * mutation's transaction. The changes are JSON-serialized into a TEXT column —
  * dialect-uniform, no json codec on the path.
  */
-export declare const makeUndoCapture: (rawTx: DataStore) => {
+export declare const makeUndoCapture: (rawTx: DataStore, crdtColumnsOf?: (table: string) => ReadonlySet<string>) => {
     tx: DataStore;
     persist: (store: unknown, meta: {
         readonly tag: string;
@@ -5687,6 +5845,18 @@ export declare const materializeIvm: (shape: AggregateShape, state: IvmState) =>
     readonly value: number | null;
 }>;
 
+/**
+ * Compress a buffered response body if (enabled ∧ type compressible ∧ size ≥
+ * threshold ∧ the client accepts an encoding). Total — never throws; the
+ * uncompressed body with correct Vary is always a valid answer.
+ */
+export declare const maybeCompress: (input: {
+    readonly body: Uint8Array;
+    readonly contentType: string | undefined;
+    readonly acceptEncoding: string | undefined;
+    readonly options?: CompressionOptions | undefined;
+}) => CompressedResult;
+
 /** Told when the membership changes. `restarted` is a `left` + `joined` pair
  *  for one id, reported as such so a deployment drops the old state rather than
  *  resuming it. */
@@ -5889,8 +6059,10 @@ export declare interface MutationLike {
         readonly requiresApproval?: AnyApprovalPolicy | undefined;
         readonly target?: {
             readonly table: string;
+            readonly relations?: Readonly<Record<string, string>> | undefined;
         } | ReadonlyArray<{
             readonly table: string;
+            readonly relations?: Readonly<Record<string, string>> | undefined;
         }> | undefined;
     };
     executor(input: unknown, ctx: unknown): unknown;
@@ -5964,6 +6136,13 @@ export declare interface MutationStore extends DataStore {
     hardDelete(table: string, primaryKey: string): Promise<boolean>;
 }
 
+export declare type NegotiatedEncoding = 'br' | 'gzip';
+
+/** Pick the encoding the client accepts — brotli preferred, gzip second,
+ *  nothing otherwise. Honours q=0 refusals; ignores q-ordering beyond that
+ *  (a client sending both accepts both). */
+export declare const negotiateEncoding: (acceptEncoding: string | undefined) => NegotiatedEncoding | undefined;
+
 /**
  * The backoff curve, extracted so it can be asserted directly — a schedule
  * that backs off wrongly is otherwise only visible as a latency an integration
@@ -6829,6 +7008,25 @@ export declare interface ReactiveConfigInput {
      * warning to name a later one.
      */
     readonly rawReadTrackingLimit?: number;
+    /**
+     * Subscription socket backpressure (plan 01 P1). A slow or dead consumer no
+     * longer retains every event: updates COALESCE onto the newest state while
+     * the socket is blocked, and a consumer persistently over the buffer
+     * threshold is closed with a typed `SubscriptionOverrun` (it re-subscribes
+     * for a fresh snapshot). Resolved by the CLI's `reactiveTunables.ts`; env
+     * overrides win: `VOLTRO_REACTIVE_MAX_BUFFERED_BYTES` /
+     * `VOLTRO_REACTIVE_OVERRUN_AFTER_MS` / `VOLTRO_REACTIVE_OVERSIZED_EVENT_BYTES`.
+     */
+    readonly socket?: {
+        /** Estimated pending bytes per subscription above which a persistently
+         *  blocked consumer is overrun-closed. Default 1 MiB. */
+        readonly maxBufferedBytes?: number;
+        /** How long the pending state must stay over the threshold before the
+         *  terminal close. Default 10_000 ms. */
+        readonly overrunAfterMs?: number;
+        /** Per-event WARN threshold (telemetry, NOT a cap). Default 256 KiB. */
+        readonly oversizedEventBytes?: number;
+    };
 }
 
 export declare interface ReactiveEnv {
@@ -6844,6 +7042,16 @@ export declare type ReactiveReturn<D extends ExecutorDescriptor> = D extends {
     readonly descriptor: QueryDescriptor;
 } : never;
 
+export declare interface ReactiveSocketTunables {
+    readonly maxBufferedBytes: number;
+    readonly overrunAfterMs: number;
+    readonly oversizedEventBytes: number;
+}
+
+/** The resolved tunables, or the defaults when no boot path has set any
+ *  (unit tests, a bare library use). */
+export declare const reactiveSocketTunables: () => ReactiveSocketTunables;
+
 export declare interface ReadClassification {
     /** Tables whose ROWS can reach the caller: the queried table and its joins. */
     readonly composed: ReadonlySet<string>;
@@ -6930,6 +7138,8 @@ export declare interface RebacSubject {
     readonly scopes?: ReadonlyArray<string>;
 }
 
+export declare const recordCoalesced: (label: string, collapsed: number) => void;
+
 export declare const recordCredentialExpiry: (clientId: number, exp: number | undefined) => void;
 
 /** What the framework emit-seams (servePipeline / rpcServer / plugin wrappers)
@@ -6956,6 +7166,15 @@ export declare const recordEventPublished: (event: string) => void;
 /** Subscriber attached (+1) or detached (-1). */
 export declare const recordEventSubscribers: (event: string, delta: number) => void;
 
+/**
+ * Record one emitted event into the identity's ring. Snapshots RESET the ring
+ * (the snapshot's revision becomes the new replay base — a client holding an
+ * older revision is outside the chain); deltas append. An error event drops
+ * the ring: whatever state the client holds, the safe answer after an error
+ * is a fresh snapshot.
+ */
+export declare const recordForResume: (identity: ResumeIdentity, event: SubscriptionEvent<unknown>, now?: number, tunables?: ResumeTunables) => void;
+
 /**
  * A store that notes every read and changes nothing else.
  *
@@ -6966,6 +7185,10 @@ export declare const recordEventSubscribers: (event: string, delta: number) => v
  */
 export declare const recordingStore: (store: DataStore) => DataStore;
 
+export declare const recordOverrun: (label: string) => void;
+
+export declare const recordOversized: (label: string) => void;
+
 /**
  * Record a raw read, opening a scope for the rest of this execution context if
  * none is open yet.
@@ -7256,6 +7479,13 @@ export declare interface RegistryTableLike {
  *  request was. */
 export declare const rehydrateGuards: (serialized: ReadonlyArray<SerializedGuard>) => ReadonlyArray<AnyGuardSpec>;
 
+/** The store slice `applyDeclaredRelations` needs. */
+declare interface RelationLinksStore {
+    relationLinks(junctionTable: string, anchorTable: string, anchorId: string): {
+        set(targetIds: ReadonlyArray<string>): Promise<unknown>;
+    };
+}
+
 /** A relationship tuple — `subjectId` has `relation` on `<resourceType>:<resourceId>`.
  *  In practice these are rows in a relation table; the engine takes them as data. */
 export declare interface RelationTuple {
@@ -7441,15 +7671,24 @@ export declare const resetComputedQueryCacheWarnings: () => void;
 /** Test/dev-only — clear ALL per-connection state. Don't call from app code. */
 export declare const _resetConnectionCredentialsForTest: () => void;
 
+/** Test seam — expire everything immediately. */
+export declare const resetDetachedForTest: () => void;
+
 /** Test seams for the tag-cache guard — the cache is module-private otherwise. */
 export declare const resetEventMetricTagCacheForTests: () => void;
 
 /** Drop everything recorded. For tests; not called by the runtime. */
 export declare const resetObservedGraph: () => void;
 
+/** Test seam. */
+export declare const resetResumeRingsForTest: () => void;
+
 /** Reset to the env default (tests). */
 export declare const resetSecretsBackend: () => void;
 
+/** Test seam. */
+export declare const resetSubscriptionSocketMetrics: () => void;
+
 /**
  * The client address to rate-limit, geo-block and audit by.
  *
@@ -7768,6 +8007,46 @@ export declare const restrictingReadsEffect: <A, E, R>(effect: Effect.Effect<A,
 /** The full ordered list of result variants for a definition, holdout last. */
 export declare const resultVariantNames: (def: ExperimentDefinition) => ReadonlyArray<string>;
 
+export declare type ResumeAnswer = 
+/** The client's revision chains: replay these deltas in order. */
+    {
+    readonly kind: 'deltas';
+    readonly deltas: ReadonlyArray<RingDelta>;
+}
+/** Outside the window / unknown identity / gap — send a snapshot,
+*  `resumed: false`. */
+| {
+    readonly kind: 'snapshot';
+};
+
+/**
+ * The identity a ring is recorded under — and the identity a resume must
+ * present to read it back. `subjectId`/`tenantId` are part of the KEY, so a
+ * login/logout/tenant-switch between disconnect and resume simply misses the
+ * ring and falls back to a snapshot (`resumed: false`) — the blank-on-auth
+ * doctrine, enforced structurally rather than checked.
+ */
+export declare interface ResumeIdentity {
+    readonly label: string;
+    /** Canonicalised query input (JSON with sorted keys). */
+    readonly inputKey: string;
+    readonly subjectId: string;
+    readonly tenantId: string;
+}
+
+export declare const resumeKeyOf: (identity: ResumeIdentity) => string;
+
+export declare interface ResumeSink {
+    current: (event: SubscriptionEvent<unknown>) => void;
+}
+
+export declare interface ResumeTunables {
+    readonly windowMs: number;
+    readonly maxDeltas: number;
+}
+
+export declare const resumeTunables: () => ResumeTunables;
+
 export { RetentionConflict }
 
 export { RetentionSource }
@@ -7776,6 +8055,55 @@ export { RetentionSpec }
 
 export { retentionTtlMsFromEnv }
 
+/**
+ * Drop the ISR cache entries for a path on every `voltro start` replica.
+ *
+ * `path` is a concrete path (`/pricing`) or a declared route pattern
+ * (`/blog/[slug]` = every cached instance). All tenant+locale variants of the
+ * key fall; pass `{ tenant }` to narrow to one tenant's variants.
+ *
+ * Only `renderMode: 'isr'` routes have cache entries to drop — calling this
+ * for a `static` route is reported as an error on the web process (static
+ * HTML is a build artifact `voltro start` never re-renders). Under
+ * `voltro dev` there is no ISR cache and the call is a debug-logged no-op.
+ */
+export declare const revalidatePath: (path: string, options?: {
+    readonly tenant?: string;
+}) => Promise<void>;
+
+/**
+ * Drop the ISR cache entries of every route whose `cacheInvalidatesOn` lists
+ * `table` — the same sink CDC feeds on postgres, callable imperatively. This
+ * is THE invalidation path for dialects without CDC (sqlite, mysql, memory).
+ */
+export declare const revalidateTable: (table: string) => Promise<void>;
+
+/**
+ * Drop the ISR cache entries of every route whose `cacheInvalidatesOn` lists
+ * `tag`. `cacheInvalidatesOn` accepts free strings, so a tag shares one
+ * mechanism (and one entry point) with table invalidation — declare
+ * `cacheInvalidatesOn: ['pricing']` on any number of routes and
+ * `revalidateTag('pricing')` drops them all.
+ */
+export declare const revalidateTag: (tag: string) => Promise<void>;
+
+export declare interface RevalidationMessage {
+    /** What to drop:
+     *  - `path`: a concrete path (`/pricing`) or a declared route pattern
+     *    (`/blog/[slug]` — every cached instance of the route). All
+     *    tenant+locale key variants fall unless `tenant` narrows it.
+     *  - `table`: every route whose `cacheInvalidatesOn` lists the table —
+     *    the same sink CDC feeds, for dialects (or moments) without CDC.
+     *  - `tag`: identical mechanics to `table` — `cacheInvalidatesOn` accepts
+     *    free strings, so a tag is simply a name that never was a table. */
+    readonly kind: 'path' | 'table' | 'tag';
+    readonly value: string;
+    /** For `kind: 'path'`: drop only this tenant's cached variants. */
+    readonly tenant?: string;
+}
+
+export declare type RevalidationPublisher = (message: RevalidationMessage) => Promise<void>;
+
 /**
  * Reverse ONE recorded event over an in-memory row-set (to step BACK across it):
  *   - insert → the row was added, so remove it (by new.id).
@@ -7793,6 +8121,12 @@ export declare const revokedIds: (before: ReadonlyArray<{
     readonly id: string;
 }>) => ReadonlyArray<string>;
 
+declare interface RingDelta {
+    readonly revision: number;
+    readonly emittedAt: number;
+    readonly patch: RowPatch;
+}
+
 /**
  * Live traffic the router fronts — read by idle detection (the orchestrator
  * can't see the app's HTTP/WS load directly when it's scaled to zero, but
@@ -7926,7 +8260,7 @@ declare const RowFilterUnavailable_base: Schema.TaggedErrorClass<RowFilterUnavai
     cause: typeof Schema.String;
 }>;
 
-/** One `_voltro_row_history` row, structurally (from @voltro/plugin-versioning). */
+/** One `_voltro_row_history` row, structurally (from @voltro/plugin-row-history). */
 export declare interface RowHistoryEntry {
     readonly value?: unknown;
     readonly newValue?: unknown;
@@ -8056,6 +8390,45 @@ export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
      * with a `Content-Length` got a clean 413. See `rpcBodyCap.ts`.
      */
     readonly maxRpcBodyBytes?: number;
+    /**
+     * Max body size (bytes) for EVERY other buffered surface on this listener:
+     * plugin HTTP routes (which read `req.arrayBuffer`) and incoming webhook
+     * receivers. The rpc endpoint keeps its own `maxRpcBodyBytes` (a JSON
+     * envelope is never legitimately large; these surfaces legitimately can
+     * be — a webhook provider posting a fat payload is the normal case, which
+     * is why a PluginHttpRoute / webhook handler may override PER ROUTE via
+     * its own `maxBodyBytes`). Same two-shape 413 contract as the rpc cap
+     * (declared Content-Length refused first; the byte counter enforces).
+     * Default {@link DEFAULT_MAX_RPC_BODY_BYTES}; env override
+     * `VOLTRO_MAX_BODY_BYTES`.
+     */
+    readonly maxBodyBytes?: number;
+    /**
+     * Negotiated response compression for the buffered non-rpc surfaces
+     * (plugin routes, webhooks). `POST /rpc` is NEVER compressed (the BREACH
+     * position — see httpCompression.ts) and streams are never compressed.
+     * Default enabled with a 1 KiB threshold; `http.compression` in
+     * app.config.ts feeds this via resolveHttpTunables.
+     */
+    readonly compression?: CompressionOptions;
+    /**
+     * Raw WebSocket gateways (plan 08 §3) — `defineWebSocket` routes discovered
+     * from `*.ws.ts`. Each mounts its own upgrade path beside the rpc socket;
+     * every gateway path joins the upgrade origin guard's set, and
+     * `auth: 'subject'` routes resolve their subject through
+     * {@link RpcServerOptions.resolveGatewaySubject} BEFORE the upgrade.
+     */
+    readonly webSocketGateways?: ReadonlyArray< WebSocketGatewayRoute>;
+    /**
+     * Subject resolution for `auth: 'subject'` gateways — the SAME chain the
+     * boot path hands its REST bindings (cookie/bearer). `null` → 401 before
+     * any socket exists. `credentialExpiresAt` binds the connection's lifetime
+     * exactly like an rpc connection's (SEC-16).
+     */
+    readonly resolveGatewaySubject?: (headers: Readonly<Record<string, string>>) => Promise<{
+        readonly subject: Subject;
+        readonly credentialExpiresAt?: number | undefined;
+    } | null>;
     /**
      * Transport-level security policy for this listener — see
      * {@link TransportSecurityOptions}. `undefined` → the safe defaults.
@@ -8840,6 +9213,12 @@ export declare interface ServeRequestContext {
     readonly subject: unknown;
     readonly traceId: string;
     readonly spanId?: string;
+    /**
+     * Caller-side cancellation (the gRPC deadline / client-cancel path).
+     * Honoured at the ONE place the executor effect runs to a promise, so an
+     * exceeded deadline INTERRUPTS the server work — not merely the response.
+     */
+    readonly signal?: AbortSignal;
     /**
      * Row-level visibility for this request, resolved by `withRowFilter` and read
      * by the context builder when it wraps the store.
@@ -8897,6 +9276,8 @@ export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown,
     readonly target?: ReadonlyArray<string>;
 }) => Effect.Effect<unknown, unknown, never>;
 
+export declare const setBufferedBytes: (label: string, bytes: number) => void;
+
 /** Register the process-wide connection resolver (or clear with `undefined`).
  *  Called by the CLI at boot; tests call it directly. */
 export declare const setConnectionResolver: (resolver: ConnectionResolver | undefined) => void;
@@ -8904,6 +9285,17 @@ export declare const setConnectionResolver: (resolver: ConnectionResolver | unde
 /** Register the field cipher (or clear with `undefined`). */
 export declare const setFieldCipher: (cipher: FieldCipher | undefined) => void;
 
+export declare const setReactiveSocketTunables: (tunables: ReactiveSocketTunables | null) => void;
+
+export declare const setResumeTunables: (tunables: ResumeTunables | null) => void;
+
+/**
+ * Boot-path wiring. `null` clears (shutdown). Registering `null` vs never
+ * registering are deliberately the SAME state — a call before boot wiring and
+ * a call after teardown both deserve the loud error below, not a quiet drop.
+ */
+export declare const setRevalidationPublisher: (publisher: RevalidationPublisher | null) => void;
+
 /**
  * Register (or clear, with `undefined`) the process-global row filter. Call
  * once at boot. Last write wins.
@@ -9025,7 +9417,10 @@ export declare interface SnapshotCacheBinding {
     readonly swrMs: number | undefined;
 }
 
-/** Snapshot the whole registry, normalized to `MetricSample[]`. */
+/** Snapshot the whole registry, normalized to `MetricSample[]` — plus the
+ *  socket-backpressure counters (`subscriptionSocketMetrics.ts`), appended
+ *  HERE so every reader (Prometheus exporter, inspect Metrics panel) sees
+ *  one derivation and the two cannot diverge. */
 export declare const snapshotMetrics: Effect.Effect<ReadonlyArray<MetricSample>>;
 
 /** Eager snapshot for sync callers (the inspect endpoint). */
@@ -9290,6 +9685,22 @@ export declare interface SubscriberDefinition {
     readonly handler: SubscribeHandler;
 }
 
+export declare interface SubscriptionBackpressureOptions {
+    /** Estimated pending bytes above which a persistently-blocked consumer is
+     *  overrun-closed. `reactive.socket.maxBufferedBytes` / env override. */
+    readonly maxBufferedBytes: number;
+    /** How long the pending state must stay over the threshold (with the pump
+     *  blocked) before the terminal close. */
+    readonly overrunAfterMs: number;
+    /** Per-event WARN threshold — telemetry for oversized snapshots/deltas.
+     *  Deliberately NOT a cap: measurability is the goal. */
+    readonly oversizedEventBytes: number;
+    /** Query tag for logs + metrics. */
+    readonly label: string;
+    readonly now?: () => number;
+    readonly warn?: (message: string, fields: Record<string, unknown>) => void;
+}
+
 /**
  * Timing of ONE subscription delivery (the initial snapshot, or a delta
  * pushed on a change). The duration is the real produce→push latency:
@@ -9325,6 +9736,29 @@ export declare interface SubscriptionDeliveryRecord {
     readonly rowCount: number;
 }
 
+export declare interface SubscriptionOutbox {
+    /** SYNC push from the dispatcher's emit callback. */
+    readonly push: (event: Event_2) => void;
+    /** Pump side: resolves with the next event to hand into the stream —
+     *  coalesced when more than one push landed since the last take — or null
+     *  once the outbox is closed and drained. */
+    readonly take: () => Promise<Event_2 | null>;
+    /** True once the overrun policy fired (the error event has been queued;
+     *  the stream ends after it drains). */
+    readonly overrun: () => boolean;
+    readonly close: () => void;
+}
+
+/** The wire shape of the terminal overrun error — documented in
+ *  wire-protocol.md. The client surfaces it as the entry's `error` and
+ *  re-subscribes for a fresh snapshot. */
+export declare interface SubscriptionOverrunError {
+    readonly _tag: 'SubscriptionOverrun';
+    readonly message: string;
+    readonly bufferedBytes: number;
+    readonly maxBufferedBytes: number;
+}
+
 export declare type SubscriptionRecord = {
     readonly id: string;
     readonly table: string;
@@ -9385,6 +9819,35 @@ export declare interface SubscriptionSnapshot {
     readonly subscriberCount: number;
 }
 
+/**
+ * The counters as `MetricSample`s — appended by `snapshotMetrics`
+ * (metrics.ts), which is the ONE derivation both the Prometheus exporter and
+ * the inspect Metrics panel read. Same input → the two cannot diverge.
+ */
+export declare const subscriptionSocketMetricSamples: () => ReadonlyArray< MetricSample>;
+
+export declare interface SubscriptionSocketMetricsSnapshot {
+    /** Sum + per-label current pending bytes across live subscriptions. */
+    readonly bufferedBytes: {
+        readonly total: number;
+        readonly byLabel: Readonly<Record<string, number>>;
+    };
+    readonly coalescedTotal: {
+        readonly total: number;
+        readonly byLabel: Readonly<Record<string, number>>;
+    };
+    readonly overrunTotal: {
+        readonly total: number;
+        readonly byLabel: Readonly<Record<string, number>>;
+    };
+    readonly oversizedTotal: {
+        readonly total: number;
+        readonly byLabel: Readonly<Record<string, number>>;
+    };
+}
+
+export declare const subscriptionSocketMetricsSnapshot: () => SubscriptionSocketMetricsSnapshot;
+
 /** Drop handshake grants past their TTL. Wired into the boot retention sweep;
  *  a grant is worthless the moment it expires and keeping them turns a hot
  *  table into an audit liability. */
@@ -10208,6 +10671,10 @@ export declare const WEBHOOK_VERIFICATION_PROPERTY: "voltroWebhookVerification";
  *  public POST that runs application code, so "nothing verifies it" has to
  *  be a decision somebody wrote down, not the default. */
 export declare interface WebhookRouteHandler {
+    /** Per-route body cap override (bytes) — wins over the listener's
+     *  `maxBodyBytes`. A provider that legitimately posts fat payloads is the
+     *  reason this exists; the DEFAULT stays the shared cap. */
+    readonly maxBodyBytes?: number;
     readonly handle: (request: {
         readonly method: string;
         readonly path: string;
@@ -10251,24 +10718,6 @@ export declare const webhookVerificationOf: (handle: unknown) => WebhookVerifica
  */
 export declare type WhereOp = '=' | '!=' | '<>' | '>' | '>=' | '<' | '<=' | 'in' | 'contains' | 'startsWith' | 'fts';
 
-/**
- * Resolve this request's row-filter scope. A no-op (same object back) when the
- * app registered no filter, so an app that uses none pays nothing.
- *
- * Every runner calls this before building a context. A read path that skipped
- * it would have no row-level security and would look exactly like one that
- * does — which is why it lives in the shared spine rather than in each
- * entrypoint.
- *
- * REJECTS with the raw `RowFilterUnavailable` (via `runProvidedEffect`, not
- * `Effect.runPromise`) when the filter's `onLoadError` is the default `'fail'`
- * and `load` failed every retry. Raw, so the rpc encoder matches it against the
- * descriptor's `error:` schema and the client gets the tag instead of an opaque
- * defect — the same treatment `enforceGuards` gives a `ScopeError`. Proceeding
- * with an unresolved filter is not an option here: the context builder would
- * receive `rowFilter: undefined`, which means "this app registered no filter"
- * and would silently serve the request UNFILTERED.
- */
 export declare const withRowFilter: <R extends ServeRequestContext>(request: R) => Promise<R>;
 
 /**
@@ -10798,7 +11247,7 @@ export declare interface WorkflowWaitOptions {
  * calls (incl. multi-table within one mutation) are. A mutation that writes via
  * a bulk helper simply produces no undo entry (documented).
  */
-export declare const wrapCaptureStore: (tx: DataStore, collect: (c: ForwardChange) => void) => DataStore;
+export declare const wrapCaptureStore: (tx: DataStore, collect: (c: ForwardChange) => void, crdtColumnsOf?: (table: string) => ReadonlySet<string>) => DataStore;
 
 /**
  * Wrap a raw `DataStore` with the storage codec only — `.encrypted()` columns