@voltro/runtime 0.53.0 → 0.55.0

package/dist/index.d.ts

@@ -94,6 +94,7 @@ import { SyncLogger } from '@voltro/logger';
 import { TableLike } from '@voltro/database';
 import { TableName } from '@voltro/protocol';
 import { TableValidationFailed } from '@voltro/protocol';
+import { TargetRelation } from '@voltro/protocol';
 import { TenantRowNotFound } from '@voltro/protocol';
 import { TenantScopeViolation } from '@voltro/protocol';
 import { Tracer } from 'effect';
@@ -1124,7 +1125,14 @@ export declare const applyConnectionCredential: (clientId: number, headers: Reco
  * - 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.
+ *   is unusable and says so;
+ * - the DECLARED junction columns must match the junction's real reference
+ *   pair. They are declaration data because the browser drives junction
+ *   auto-optimistic from the same block and cannot derive them; this is the
+ *   one place both readings meet, so a disagreement is refused here — before
+ *   any write — with the correct pair named. Letting it through would mean the
+ *   client patched one column while the server wrote another, and the UI would
+ *   look right until the delta contradicted it.
  */
 export declare const applyDeclaredRelations: (params: {
     readonly store: RelationLinksStore;
@@ -2640,6 +2648,8 @@ export declare const counter: (name: string, description?: string) => Metric.Met
  */
 export declare const countRunningWorkflows: (store: DataStore) => Promise<number>;
 
+export declare const crdtCompactMaxBytes: () => number;
+
 /**
  * Every firing instant of `def` in `(from, to]`, oldest first, bounded by
  * `cap + 1` entries.
@@ -2917,6 +2927,8 @@ export declare const DEFAULT_CLAIM_BUCKET_MS = 60000;
 
 export declare const DEFAULT_COMPRESSION_MIN_BYTES = 1024;
 
+export declare const DEFAULT_CRDT_COMPACT_MAX_BYTES: number;
+
 /**
  * How many subscribers one change event is delivered to CONCURRENTLY.
  *
@@ -3301,7 +3313,12 @@ export declare class Dispatcher {
     /** Re-run the query's `guards:` before every delivery — see
      *  `ActiveSubscription.reauthorize`. Omitted for unguarded queries. */
     reauthorize?: () => Promise<unknown>, 
-    /** Re-resolve row visibility per delivery — see `ActiveSubscription.refilter`. */
+    /** Re-resolve row visibility per delivery — see `ActiveSubscription.refilter`.
+     *
+     *  Optional ONLY in the sense that an app with no registered row filter has
+     *  nothing to resolve; it is not the caller's choice. Omitting it while a
+     *  filter IS registered throws below, because the read would then ignore the
+     *  filter entirely. Build it with `makeDefaultRefilter(subject)`. */
     refilter?: () => Promise<RowFilterScope>): Promise<() => void>;
     /**
      * Tear a subscription down because it can no longer be served CORRECTLY
@@ -5235,6 +5252,17 @@ export declare const ivmValue: (shape: AggregateShape, g: GroupState) => number
  * columns is rejected with a message naming what it found.
  */
 export declare interface JunctionLinks {
+    /**
+     * The junction's two reference columns as RESOLVED for this anchor — the
+     * source of truth a declared `relations:` is verified against. It is exposed
+     * because the pair also has to be stated in the descriptor (the browser
+     * cannot derive it), and a stated fact that nothing compares against is a
+     * divergence waiting to happen.
+     */
+    readonly columns: {
+        readonly anchorColumn: string;
+        readonly targetColumn: string;
+    };
     /** The current target ids linked to the anchor. */
     list(): Promise<ReadonlyArray<string>>;
     /** Reconcile the links to EXACTLY `targetIds` — insert the missing, delete the
@@ -5552,6 +5580,25 @@ export declare const makeCoordinatedScheduler: (deps: CoordinatedScheduleDeps) =
  */
 export declare const makeDataLoader: (deps: LoaderDeps) => DataLoader;
 
+/**
+ * The per-delivery refilter EVERY subscribing transport must hand the
+ * dispatcher — the one that re-resolves this subject's visibility before each
+ * delivery instead of freezing it at subscribe.
+ *
+ * It lives here, beside the registration it reads, because it was a private
+ * helper of the WebSocket entrypoint and the transports that did not import it
+ * did not filter at all. `dispatcher.subscribe` resolves visibility itself and
+ * treats an absent refilter as "this app has no filter", so a transport that
+ * simply omitted the argument read the UNFILTERED descriptor — on the initial
+ * snapshot and on every delta. The SSE and gRPC projections omitted it.
+ *
+ * Returning `undefined` when no filter is registered is the fast path, not an
+ * opt-out: it is what keeps a filterless app free of a per-delivery await, and
+ * `dispatcher.subscribe` refuses the ambiguous case (nothing passed WHILE a
+ * filter is registered) rather than reading it as this one.
+ */
+export declare const makeDefaultRefilter: (subject: Subject, onError?: (error: unknown) => void) => (() => Promise<RowFilterScope>) | undefined;
+
 /** `__voltro.connections.disconnect` — forget the caller's credential. */
 export declare const makeDisconnectConnectionExecutor: (deps: ConnectionBuiltinDeps) => (input: {
     readonly connectionId: string;
@@ -6059,10 +6106,10 @@ export declare interface MutationLike {
         readonly requiresApproval?: AnyApprovalPolicy | undefined;
         readonly target?: {
             readonly table: string;
-            readonly relations?: Readonly<Record<string, string>> | undefined;
+            readonly relations?: Readonly<Record<string, TargetRelation>> | undefined;
         } | ReadonlyArray<{
             readonly table: string;
-            readonly relations?: Readonly<Record<string, string>> | undefined;
+            readonly relations?: Readonly<Record<string, TargetRelation>> | undefined;
         }> | undefined;
     };
     executor(input: unknown, ctx: unknown): unknown;
@@ -6271,6 +6318,16 @@ declare const NoRowFound_base: Schema.TaggedErrorClass<NoRowFound, "NoRowFound",
 /** Note one read against the in-flight procedure. No scope → nothing happens. */
 export declare const noteRead: (descriptor: QueryDescriptor) => void;
 
+/**
+ * Record the resume verdict for one subscription setup. `true` means a ring
+ * was recorded; anything else names why it was not.
+ *
+ * Logs at debug ONCE per (label, verdict) — a hot query must not narrate every
+ * subscribe, and the second identical verdict carries no information the first
+ * did not.
+ */
+export declare const noteResumeVerdict: (rawLabel: string, verdict: true | ResumeExclusion) => void;
+
 export declare interface Notification {
     readonly subscriberId: string;
     readonly fingerprint: string;
@@ -6768,6 +6825,16 @@ export declare const publishEvent: <Name extends string, Key extends Schema.Sche
     readonly deferred: boolean;
 }, EventPublishError>;
 
+/**
+ * A Layer that publishes whatever tracer is in scope when it is built.
+ *
+ * Provided immediately INSIDE the tracer layer at boot, so it captures the
+ * configured tracer rather than the default one. With tracing off it captures
+ * Effect's no-op tracer, which is the correct answer — detached work then
+ * behaves exactly as in-request work does.
+ */
+export declare const publishServerTracerLayer: Layer.Layer<never, never, never>;
+
 /**
  * The two scopes, composed once, for every path that finalises a descriptor.
  *
@@ -6829,9 +6896,23 @@ export declare interface QueryProducerDeps<D> {
 }
 
 export declare interface QuerySubscriberDeps<D> extends QueryProducerDeps<D> {
-    /** Open a dispatcher subscription for a finalized descriptor. */
-    readonly subscribeDescriptor: (descriptor: D, emit: (event: unknown) => void, context: ServeRequestContext) => Promise<() => void>;
-    /** Open a dispatcher subscription for a COMPUTED query (re-runs on source change). */
+    /**
+     * Open a dispatcher subscription for a finalized descriptor.
+     *
+     * `reauthorize` and `refilter` are REQUIRED parameters of this callback, not
+     * optional extras, and the requirement is the guard: they used to be
+     * `dispatcher.subscribe`'s trailing optional arguments, this callback simply
+     * did not pass them, and the dispatcher reads their absence as "this query is
+     * unguarded and this app has no row filter". So the SSE and gRPC projections
+     * re-ran no guard and read the UNFILTERED descriptor — initial snapshot and
+     * every delta — while the WebSocket path (which goes through
+     * `bindSubscription`) did both. Threading them through the signature makes the
+     * next transport unable to repeat that by omission.
+     */
+    readonly subscribeDescriptor: (descriptor: D, emit: (event: unknown) => void, context: ServeRequestContext, reauthorize: (() => Promise<unknown>) | undefined, refilter: (() => Promise<RowFilterScope>) | undefined) => Promise<() => void>;
+    /** Open a dispatcher subscription for a COMPUTED query (re-runs on source change).
+     *  A computed query re-runs its HANDLER per change, so guards and the row
+     *  filter are re-applied by that re-run — it needs no separate pair. */
     readonly subscribeComputed: (computed: ComputedQuery, emit: (event: unknown) => void, context: ServeRequestContext) => Promise<() => void>;
 }
 
@@ -7479,9 +7560,15 @@ export declare interface RegistryTableLike {
  *  request was. */
 export declare const rehydrateGuards: (serialized: ReadonlyArray<SerializedGuard>) => ReadonlyArray<AnyGuardSpec>;
 
-/** The store slice `applyDeclaredRelations` needs. */
+/** The store slice `applyDeclaredRelations` needs. `columns` is the junction's
+ *  DERIVED reference pair — the truth the descriptor's declaration is checked
+ *  against before anything is written. */
 declare interface RelationLinksStore {
     relationLinks(junctionTable: string, anchorTable: string, anchorId: string): {
+        readonly columns: {
+            readonly anchorColumn: string;
+            readonly targetColumn: string;
+        };
         set(targetIds: ReadonlyArray<string>): Promise<unknown>;
     };
 }
@@ -7680,6 +7767,9 @@ export declare const resetEventMetricTagCacheForTests: () => void;
 /** Drop everything recorded. For tests; not called by the runtime. */
 export declare const resetObservedGraph: () => void;
 
+/** Clear the census. For tests; a running app has no reason to forget. */
+export declare const resetResumeCensus: () => void;
+
 /** Test seam. */
 export declare const resetResumeRingsForTest: () => void;
 
@@ -8019,6 +8109,31 @@ export declare type ResumeAnswer =
     readonly kind: 'snapshot';
 };
 
+/** The census as of now, one entry per label that has been subscribed. */
+export declare const resumeCensus: () => ReadonlyArray<ResumeVerdict>;
+
+/**
+ * Why a subscription carries no resume ring.
+ *
+ * - `computed` — the executor returned a value, not a descriptor. There is no
+ *   delta chain to replay: the handler re-runs opaquely and emits snapshots.
+ *   Declaring `tables:` on the row filter cannot change this; returning the
+ *   query builder instead of a mapped value can.
+ * - `row-filter` — the registered filter may narrow this subscription's source
+ *   table, so its row set is re-resolved per delivery. Declaring `tables:`
+ *   fixes it for every source the filter does NOT touch; for a source it does
+ *   touch, the exclusion is the point.
+ * - `eager-load` — the descriptor carries `.with(...)` while a filter is
+ *   registered, and the relation is resolved below the seam that would narrow
+ *   it. Reported only when the base table is NOT itself narrowed, so this
+ *   reason always means: drop the eager load and the subscription resumes.
+ * - `uncanonical-input` — the input cannot be reduced to a stable ring key, so
+ *   two different inputs would collide under one label.
+ * - `not-offered` — the binder was driven without resume input at all (the
+ *   lower-level entrypoint used by tests).
+ */
+export declare type ResumeExclusion = 'computed' | 'row-filter' | 'eager-load' | 'uncanonical-input' | 'not-offered';
+
 /**
  * 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
@@ -8047,6 +8162,14 @@ export declare interface ResumeTunables {
 
 export declare const resumeTunables: () => ResumeTunables;
 
+/** One label's tally. `resumable + Σ excluded` is the number of subscriptions
+ *  set up on this label since the process started. */
+export declare interface ResumeVerdict {
+    readonly label: string;
+    readonly resumable: number;
+    readonly excluded: Readonly<Partial<Record<ResumeExclusion, number>>>;
+}
+
 export { RetentionConflict }
 
 export { RetentionSource }
@@ -8219,7 +8342,85 @@ export declare interface RowFilter<Ctx = unknown> {
      * the handler still carries the check the filter was meant to replace.
      */
     readonly onLoadError?: 'fail' | 'deny';
-}
+    /**
+     * The ONLY tables this filter may narrow. Optional; declaring it buys
+     * delta-resume back for every subscription whose source is not in the set.
+     *
+     * WHY IT EXISTS. A subscription whose row set is re-resolved per delivery
+     * must not replay deltas on reconnect — the answer can change while the
+     * socket is down (a membership ends) and a wrong replay leaks rows. But the
+     * question the framework could ask was only "is a filter registered at
+     * all?", so ONE registration disabled delta-resume for the whole process,
+     * including every subscription reading a table the predicate never returns
+     * anything for.
+     *
+     * WHAT IT DOES NOT BUY, and this bounds the whole feature: a query whose
+     * executor returns a VALUE rather than a descriptor — anything that maps the
+     * rows or wraps them in a page envelope — has no delta chain to resume in
+     * the first place. It re-runs an opaque handler and emits snapshots, filter
+     * or no filter. So the number of subscriptions a declaration can give back
+     * is the number that bind a descriptor, not the number of queries in the
+     * app; declare it anyway (it costs nothing and applies the moment a query
+     * returns a builder), but read `resumeCensus()` — or
+     * `/_voltro/inspect/subscriptions` — before expecting a change.
+     *
+     * WHY A DECLARATION RATHER THAN A PROBE. Resolving the scope at subscribe
+     * and treating `predicate(ctx, source) === undefined` as safe is cheaper and
+     * unsound: the predicate is a function of freshly loaded context, so a table
+     * it does not narrow now may be narrowed on the next delivery — which is the
+     * entire reason the refilter is per-delivery. A static list is a promise
+     * about every future resolution.
+     *
+     * IT IS VERIFIED, not trusted. Returning a predicate for a table outside
+     * this set raises {@link RowFilterDeclarationViolated} at the read that did
+     * it — the request fails and a subscription is revoked, rather than serving
+     * rows under a resume grant the declaration no longer earns. An undeclared
+     * filter (this field absent) keeps the conservative behaviour: no resume
+     * anywhere, no verification.
+     *
+     *     const OWNED = new Set(['documents', 'comments'])
+     *     setRowFilter({
+     *       load,
+     *       predicate: (ctx, table) => (OWNED.has(table) ? eq('ownerId', ctx.userId) : undefined),
+     *       // Derived from the same set the predicate reads. Two hand-kept
+     *       // lists is the shape in which a table lands in exactly one of
+     *       // them — and the penalty here is a failing read, not a warning.
+     *       tables: [...OWNED],
+     *     })
+     */
+    readonly tables?: ReadonlyArray<string>;
+}
+
+/**
+ * A row filter narrowed a table its `tables:` declaration does not list.
+ *
+ * Fail-closed by construction: the declaration is what the framework hands
+ * delta-resume, so a filter that quietly narrows beyond it would have rings
+ * recorded for a table whose visibility CAN change — the leak the exclusion
+ * exists to prevent. Raised at the read that violated it, naming the table and
+ * the fix, rather than degrading to an unfiltered or empty answer.
+ */
+export declare class RowFilterDeclarationViolated extends RowFilterDeclarationViolated_base {
+}
+
+declare const RowFilterDeclarationViolated_base: Schema.TaggedErrorClass<RowFilterDeclarationViolated, "RowFilterDeclarationViolated", {
+    readonly _tag: Schema.tag<"RowFilterDeclarationViolated">;
+} & {
+    /** The table the predicate narrowed. */
+    table: typeof Schema.String;
+    /** The declared set, for the message. */
+    declared: Schema.Array$<typeof Schema.String>;
+}>;
+
+/**
+ * Could the registered filter narrow ANY of `tables`?
+ *
+ * The question delta-resume asks before recording a ring. Answers `true`
+ * whenever it cannot prove otherwise — no declaration means the framework does
+ * not know which tables the predicate may reach, and "unknown" must read as
+ * "yes" or the exclusion stops protecting anything.
+ */
+export declare const rowFilterMayNarrow: (tables: ReadonlyArray<string>) => boolean;
 
 /**
  * Is a row filter registered right now — asked by a path about to serve an
@@ -8342,9 +8543,16 @@ export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
      * http app, so it fires on EVERY request — inspect, webhooks, AND the
      * rpc websocket upgrade — before auth/routing. A non-null return
      * short-circuits with that response (e.g. a rate-limit 429 / geo-block
-     * 451). Absent → no wrapper. Fail-OPEN: a throwing interceptor is
-     * swallowed and the request continues, so a buggy shield can't take
-     * the whole listener down.
+     * 451). Absent → no wrapper.
+     *
+     * FAIL-CLOSED: a throwing interceptor answers 500 and logs, it does NOT
+     * let the request through. The composed chain is where security gates
+     * live (an IP shield, a tenant fence — anything a plugin mounts
+     * pre-auth), and a gate that crashes open has silently stopped
+     * guarding while still reading as installed. An interceptor that must
+     * not take the listener down with its own dependency owns that
+     * decision itself — plugin-ratelimit's httpShield catches its store
+     * failure and degrades to "unlimited, loudly" rather than throwing.
      */
     readonly pluginHttpInterceptor?: HttpRequestInterceptor;
     /**
@@ -9276,12 +9484,19 @@ export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown,
     readonly target?: ReadonlyArray<string>;
 }) => Effect.Effect<unknown, unknown, never>;
 
+/** The published tracer, or `undefined` when tracing is off / no server booted. */
+export declare const serverTracer: () => Tracer.Tracer | undefined;
+
 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;
 
+/** Boot/test override — the slot `wireCrdtTunables` writes. `null` restores
+ *  env/default resolution. */
+export declare const setCrdtCompactMaxBytes: (maxBytes: number | null) => void;
+
 /** Register the field cipher (or clear with `undefined`). */
 export declare const setFieldCipher: (cipher: FieldCipher | undefined) => void;
 
@@ -9305,6 +9520,9 @@ export declare const setRowFilter: <Ctx>(filter: RowFilter<Ctx> | undefined) =>
 /** Install the process-wide secrets backend (called once at boot). */
 export declare const setSecretsBackend: (backend: SecretsBackend) => void;
 
+/** Publish the server's tracer. Called once, from inside the provided scope. */
+export declare const setServerTracer: (tracer: Tracer.Tracer | undefined) => void;
+
 /** Install the finding sink. `undefined` turns recording back off. */
 export declare const setSourceGapSink: (fn: ((finding: string) => void) | undefined) => void;
 
@@ -10742,6 +10960,16 @@ export declare const withRowFilter: <R extends ServeRequestContext>(request: R)
  */
 export declare const withScopedRequest: <R extends ServeRequestContext, A>(requestContext: R, body: (scoped: R) => A | Effect.Effect<A, unknown, never>) => A | Effect.Effect<A, unknown, never>;
 
+/**
+ * Run detached work under the server's tracer, so a span it opens is exported
+ * rather than created and dropped.
+ *
+ * A no-op when nothing is published (a unit test, an embedder, a process with no
+ * rpc server) — never a second tracer, never a throw. The alternative to this
+ * function is not "a different tracer", it is silence.
+ */
+export declare const withServerTracer: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+
 /**
  * What the gate decided. `passthrough` is the common case — no controls
  * declared — and is distinct from `start` so the facade can skip the commit