@voltro/runtime 0.81.0 → 0.82.0

package/THIRD-PARTY-NOTICES.md

@@ -4551,7 +4551,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## undici@8.10.0
+## undici@8.11.2
 
 License: MIT
 

package/dist/index.d.ts

@@ -68,16 +68,19 @@ import { MetricBoundaries } from 'effect';
 import { MetricReader } from '@opentelemetry/sdk-metrics';
 import { MutationIdempotencyScope } from '@voltro/protocol';
 import { NoRowFound } from '@voltro/protocol';
+import { NoSuchResource } from '@voltro/protocol';
 import { PendingApproval } from '@voltro/protocol';
 import { PluginHttpRoute } from '@voltro/protocol';
 import { PluginHttpRouteByteStream } from '@voltro/protocol';
 import { PluginRefOrphanPolicy } from '@voltro/database';
 import { Predicate } from '@voltro/database';
+import { ProcedureWireError } from '@voltro/protocol';
 import { PublicApiSpec } from '@voltro/protocol';
 import { Query } from '@voltro/database';
 import { QueryDescriptor } from '@voltro/database';
 import { Redis } from 'ioredis';
 import { registerRetention } from '@voltro/database';
+import { ResourceMissing } from '@voltro/protocol';
 import { RestRouteDescriptor } from '@voltro/protocol/rest';
 import { RetentionConflict } from '@voltro/database';
 import { RetentionSource } from '@voltro/database';
@@ -132,6 +135,9 @@ import { WorkflowControlRequest } from '@voltro/workflow';
 import { WorkflowControlResult as WorkflowControlResult_2 } from '@voltro/protocol';
 import { WorkflowParentClosePolicy } from '@voltro/protocol';
 import { WorkflowQueuedCancellationResult } from '@voltro/protocol';
+import { WorkflowRestartCommand } from '@voltro/protocol';
+import { WorkflowRestartObservation } from '@voltro/protocol';
+import { WorkflowRestartResult } from '@voltro/protocol';
 import { WorkflowRetryObservation } from '@voltro/protocol';
 import { WorkflowRunHandle } from '@voltro/protocol';
 import { WorkflowRunSnapshot as WorkflowRunSnapshot_2 } from '@voltro/protocol';
@@ -1793,7 +1799,7 @@ export declare const bindConnectionCredential: (clientId: number, credential: Co
  * interrupt registry subscriptions use — so one reconnect policy, one devtools
  * view, one connection lifecycle for both primitives.
  */
-export declare const bindEvent: (input: BindEventInput) => Stream.Stream<EventStreamEvent<unknown>, ScopeError | Unauthenticated, SubjectService | ConnectionInfo>;
+export declare const bindEvent: (input: BindEventInput) => Stream.Stream<EventStreamEvent<unknown>, ScopeError | Unauthenticated | NoSuchResource, SubjectService | ConnectionInfo>;
 
 export declare interface BindEventInput {
     readonly bus: EventBus;
@@ -2639,6 +2645,12 @@ export declare interface CoordinatedScheduleDeps {
      * it holds. Without either, a REMOTE replica's enqueue produces no local
      * event, and a disarmed task would sleep through it forever. The backoff
      * ceiling exists for exactly that case and is the correct choice there.
+     *
+     * The task's half of the bargain: an idle tick disarms only when it returns
+     * `nextDueInMs: null` ("nothing is scheduled"). Work that comes due on a
+     * clock is not an arrival, so the tick reports its instant as `nextDueInMs`
+     * and the task is armed for exactly then. An idle tick that says neither
+     * backs off instead of disarming.
      */
     readonly disarmWhenIdle?: boolean;
 }
@@ -2705,16 +2717,25 @@ export declare interface CoordinatedTickOutcome {
     readonly idle: boolean;
     /**
      * Milliseconds until the earliest thing this task already knows is coming —
-     * a debounce window closing, a lease expiring. Caps the backoff, so a task
-     * that is idle RIGHT NOW but has a deadline in 400 ms is armed for 400 ms
-     * rather than for 30 s.
+     * a debounce window closing, a lease expiring, a retry or a re-poll whose
+     * time arrives. Caps the backoff, so a task that is idle RIGHT NOW but has a
+     * deadline in 400 ms is armed for 400 ms rather than for 30 s.
+     *
+     * `null` is a statement, not an absence: "I looked, and nothing is scheduled
+     * — the next piece of work can only arrive as a write". It is the ONLY idle
+     * report that lets a `disarmWhenIdle` task stop ticking. Omitting the field
+     * means "I did not say", and a task that did not say backs off toward the
+     * ceiling instead of disarming.
      *
-     * This is the part a fixed interval cannot express and the part that makes
-     * the backoff safe: without it, backing off is a bet that nothing time-based
-     * is pending, and deferring controls are exactly the case where that bet is
-     * wrong.
+     * The distinction exists because the failure is silent and permanent. Work
+     * that becomes due on a CLOCK — a row released with a future `enqueuedAt`, a
+     * lease that runs out — produces no write, so no change event, so no
+     * `wake()`. A dispatcher that reported `{ idle: true }` while holding such a
+     * row disarmed and never came back; the row sat until an unrelated write
+     * happened to wake it. Making "nothing scheduled" an explicit answer turns a
+     * forgotten deadline into a slower tick rather than a hang.
      */
-    readonly nextDueInMs?: number;
+    readonly nextDueInMs?: number | null;
 }
 
 export declare type CoordinationOutcome = 'single' | 'wonLock' | 'lostLock' | 'external' | 'cluster';
@@ -3269,6 +3290,18 @@ export declare const decideApprovalInvocation: (input: {
     readonly status: "approved" | "rejected";
 }>;
 
+/**
+ * `unknown` when the executor's failures are all declared; otherwise a type the
+ * handler cannot satisfy, whose one property spells out the undeclared tag(s)
+ * and the three ways to resolve them — that text is what the compile error at
+ * the handler shows.
+ */
+export declare type DeclaredFailureCheck<D extends ExecutorDescriptor, R> = [
+UndeclaredErrorTags<D, R>
+] extends [never] ? unknown : {
+    readonly undeclaredFailure: `'${UndeclaredErrorTags<D, R>}' is not in this procedure's wire union — add it to the descriptor's \`error:\`, register it through a plugin's \`errorSchemas\`, or map it away (Effect.orDie for a defect)`;
+};
+
 /**
  * Decrypt a value produced by `encryptField` or by an `.encrypted()` column —
  * one encoding, so that sentence is now true in both directions.
@@ -3539,7 +3572,7 @@ export declare const defineEventTrigger: <EventPayload = unknown, WorkflowPayloa
  * Runtime identity — returns `fn` unchanged; the whole value is the compile-time
  * check. See the module header for the failure it prevents.
  */
-export declare const defineExecutor: <D extends ExecutorDescriptor, F extends (input: ExecutorInput<D>, ctx: AppContext) => ExecutorReturn<D, unknown, unknown>>(_descriptor: D, fn: F) => ((input: ExecutorInput<D>, ctx: AppContext) => ReturnType<F>);
+export declare const defineExecutor: <D extends ExecutorDescriptor, F extends (input: ExecutorInput<D>, ctx: AppContext) => ExecutorReturn<D, unknown, unknown>>(_descriptor: D, fn: F & DeclaredFailureCheck<D, ReturnType<F>>) => ((input: ExecutorInput<D>, ctx: AppContext) => ReturnType<F>);
 
 /**
  * Declare a data-quality expectation. Validates the shape at declaration time so
@@ -3843,6 +3876,9 @@ export declare class Dispatcher {
     /** Query labels already warned about for an undeclared raw read, so a hot
      *  subscription logs once rather than once per subscriber. */
     private readonly rawReadWarned;
+    /** The CRDT-managed columns of `table` (empty when it has none) — what a
+     *  subscription's backpressure outbox folds incrementally. */
+    crdtColumnsFor(table: string): ReadonlySet<string>;
     constructor(deps: DispatcherDependencies);
     /**
      * REL-14 — a raw read that nothing can invalidate, said out loud.
@@ -4100,7 +4136,10 @@ export declare interface DrainResult {
      */
     readonly scanned: number;
     /**
-     * When the earliest NOT-yet-due pending row comes due, as an epoch ms.
+     * When the queue next has work that no write will announce, as an epoch ms:
+     * the earliest NOT-yet-due pending row, or the earliest `delivering` claim
+     * whose lease runs out (its deliverer may be gone, and the reclaim is due
+     * then).
      *
      * `undefined` means nothing in the read window is waiting. A LOWER bound (the
      * window is capped by `batchSize`), which is the safe direction: understating
@@ -4108,7 +4147,10 @@ export declare interface DrainResult {
      *
      * This is what lets the runner arm for a backoff instead of polling until it
      * expires — the one thing in this loop that genuinely needs a clock, since a
-     * retry becoming due is not a write anybody can be notified about.
+     * retry becoming due, or a lease running out, is not a write anybody can be
+     * notified about. A runner that stopped ticking on an empty due window
+     * without this would leave a lost deliverer's row claimed until something
+     * unrelated wrote to the table.
      */
     readonly nextAttemptAt?: number;
 }
@@ -4700,8 +4742,13 @@ export declare interface ExecutorDescriptor {
     readonly kind: 'query' | 'mutation' | 'action';
     readonly input: Schema.Schema.Any;
     readonly output: Schema.Schema.Any;
+    readonly error: Schema.Schema.All;
 }
 
+/** The failure type of an executor's return, when it returns an Effect. A
+ *  Promise's rejection is untyped and a plain value cannot fail. */
+declare type ExecutorFailure<R> = R extends Effect.Effect<infer _A, infer E, infer _R> ? E : never;
+
 /** The decoded INPUT a handler receives (the Type side of the input schema). */
 export declare type ExecutorInput<D extends ExecutorDescriptor> = Schema.Schema.Type<D['input']>;
 
@@ -5304,6 +5351,14 @@ export declare type ExternalTriggerOutcome =
 
 export { extractDbCause }
 
+/** The literal `_tag`s of a failure type. `any` contributes none (nothing can
+ *  be proven about it); `UnknownException` — Effect's wrapper for a failure it
+ *  could not type, e.g. `Effect.tryPromise` without `catch` — counts as
+ *  untagged, which is what it means. */
+declare type FailureTag<E> = 0 extends (1 & E) ? never : E extends {
+    readonly _tag: infer T;
+} ? T extends 'UnknownException' ? never : T extends string ? T : never : never;
+
 export declare interface FieldChange {
     readonly from: unknown;
     readonly to: unknown;
@@ -6660,8 +6715,18 @@ export declare const makeEventPublisher: (ctx: EventPublishContext) => EventPubl
 
 export declare const makeEventsFacade: (options: EventsFacadeOptions) => EventsAppContext;
 
-/** Convenience: derive a key from a passphrase and build the cipher. */
-export declare const makeFieldCipher: (passphrase: string) => FieldCipher;
+/**
+ * Derive a key from a passphrase and build the cipher — with the keys a
+ * ROTATION retires, when there are any.
+ *
+ * Writes use the current key; reads try the current one, then each previous
+ * one. GCM authenticates, so a wrong key fails its tag rather than producing
+ * garbage, and trying them in turn is safe. Without this, a key change made
+ * every value written before it unreadable — measured: every sleeping or
+ * suspended run of an `encrypted: true` workflow failed its replay with
+ * `MalformedMessage`, and every `.encrypted()` column read failed.
+ */
+export declare const makeFieldCipher: (passphrase: string, previous?: ReadonlyArray<string>) => FieldCipher;
 
 /** Build the fluent `select` / `update` / `delete` entry functions over a
  *  backend + scope. Wired into `wrapStoreWithMixinBehaviour` so they hang
@@ -7103,6 +7168,16 @@ declare interface MemoryRywOptions {
  */
 export declare const memoryRywPositionStore: (options?: MemoryRywOptions) => RywPositionStore;
 
+/**
+ * Merge a compression result's headers onto a response's own. `Vary` is a
+ * LIST: a route that already varies (`Vary: Authorization, Cookie` — a
+ * cached answer that differs per credential) keeps its fields and gains
+ * `Accept-Encoding`. Spreading the two objects instead let the lower-case
+ * `vary` replace the route's `Vary` (HTTP header names are case-insensitive),
+ * and a shared cache could then serve one caller's answer to another.
+ */
+export declare const mergeCompressionHeaders: <V>(own: Readonly<Record<string, V>>, compression: Readonly<Record<string, string>>) => Record<string, V | string>;
+
 /**
  * Merge a name→value map into a `Cookie` header string, replacing same-named
  * pairs and preserving every other cookie the connection carries.
@@ -7847,6 +7922,10 @@ export declare interface OutboxFacadeDeps {
     readonly afterCommit?: (work: () => Promise<unknown>) => void;
     /** Wake the drain loop. */
     readonly nudge?: () => void;
+    /** The declared handler's `maxAttempts` for an effect. The row carries its
+     *  attempt budget from the moment it is enqueued, so this is where a
+     *  handler's `maxAttempts` takes effect; an enqueue's own option wins. */
+    readonly maxAttemptsOf?: (effect: string) => number | undefined;
     readonly now?: () => Date;
 }
 
@@ -8857,7 +8936,7 @@ export declare const recordTableAccess: (table: string, op: ObservedOp) => void;
 
 /** Feed a committed change into the process recorder (gated + loop-safe). The
  *  serve paths call this from their `store.onChange` tap. */
-export declare const recordTimelineEvent: (change: CdcChange & {
+export declare const recordTimelineEvent: (change: CdcChange & Pick<ChangeEvent, "oversized" | "netChange"> & {
     readonly tenantId?: string | null;
 }) => void;
 
@@ -10691,10 +10770,13 @@ export declare type ScheduleFireInterceptor = (next: () => Promise<void>, ctx: S
  * thing that silently did nothing. Same bridge a file-based migration's `up`
  * has carried since it shipped.
  *
- * The app supplies its outbound HttpClient, including its tracing and SSRF
- * policy. Other requirements must be provided by the handler.
+ * The app supplies its outbound HttpClient (tracing and SSRF policy
+ * included) AND the same service layer a mutation handler runs under —
+ * plugin services such as `MailService`, the app's own layers — so a schedule
+ * may `yield*` them. Both `voltro dev` and `voltro serve` build the runner
+ * from that layer; the type is open on requirements for exactly that reason.
  */
-export declare type ScheduleHandler = (ctx: ScheduleContext) => void | Promise<void> | Effect.Effect<unknown, unknown, HttpClient.HttpClient>;
+export declare type ScheduleHandler = (ctx: ScheduleContext) => void | Promise<void> | Effect.Effect<unknown, unknown, HttpClient.HttpClient | unknown>;
 
 /** What happens when a firing arrives while the previous run of the
  *  same schedule is still in flight. */
@@ -11899,6 +11981,19 @@ export declare interface SubscriptionBackpressureOptions {
     readonly oversizedEventBytes: number;
     /** Query tag for logs + metrics. */
     readonly label: string;
+    /**
+     * The subscription's CRDT columns (plan 18), when its table has any. Its
+     * deltas carry those cells as INCREMENTAL updates (`mergeCells`), so the
+     * rows kept here fold them into the held cells (`merge`), and a coalesced
+     * patch diffs them incrementally again (`incremental`). Without it a held
+     * cell would become the last increment, and a coalesced patch would REPLACE
+     * the client's whole text with it.
+     */
+    readonly crdt?: {
+        readonly columns: ReadonlySet<string>;
+        readonly merge: (column: string, held: unknown, update: unknown) => unknown;
+        readonly incremental: (column: string, prevValue: unknown, nextValue: unknown) => unknown | undefined;
+    };
     readonly now?: () => number;
     readonly warn?: (message: string, fields: Record<string, unknown>) => void;
 }
@@ -12159,6 +12254,9 @@ export declare const TERMINAL_RUN_STATUSES: ReadonlySet<string>;
 export declare type TimeBucket = 'minute' | 'hour' | 'day' | 'week' | 'month';
 
 export declare interface TimelineEvent {
+    /** Preserves the store's warning that images are not original commit images. */
+    readonly oversized?: ChangeEvent['oversized'];
+    readonly netChange?: ChangeEvent['netChange'];
     /** Monotonic per-process sequence — the scrubber's x-axis. */
     readonly seq: number;
     /** Wall-clock ms when recorded. */
@@ -12192,13 +12290,18 @@ export declare class TimelineRecorder {
     private readonly mode;
     private readonly capacity;
     private readonly now;
+    /** Identity of this bounded history; sequence numbers are only meaningful within it. */
+    private historyId;
+    get recorderId(): string;
+    /** A proven delivery gap makes every earlier reconstruction unsafe. */
+    invalidate(): void;
     private readonly ring;
     private seqCounter;
     constructor(mode?: TimelineMode, capacity?: number, now?: () => number);
     get enabled(): boolean;
     /** Record one change (assigns the next seq, redacts, applies the mode gate +
      *  the no-feedback skip). Returns the assigned seq, or -1 when skipped. */
-    record(change: CdcChange & {
+    record(change: CdcChange & Pick<ChangeEvent, 'oversized' | 'netChange'> & {
         readonly tenantId?: string | null;
     }): number;
     /** The highest seq recorded so far (the scrubber's "now"). */
@@ -12482,6 +12585,17 @@ export declare const tryClaimWakeup: (store: DataStore, ref: WakeupRef) => Promi
  * `_voltro_rebac_tuples`; an app whose relationships live in its own tables
  * (a `teamMembers` row, say) registers its own instead of copying data into a
  * framework table.
+ *
+ * Return `'missing'` when the resource itself does not exist for this caller:
+ * the guard then refuses with the typed `NoSuchResource` instead of
+ * `ScopeError`, so an id-route can answer "not found" before its executor runs.
+ * The source is the only place that can know — an empty tuple list means "no
+ * relation", never "no row", because inferring absence from it would tell any
+ * caller which ids exist. Decide the disclosure yourself: answer `'missing'`
+ * from a tenant-scoped read (a row in another tenant then reads as missing, not
+ * as "exists, not yours"), and never for a resource the caller could not have
+ * learnt about otherwise. An anonymous caller never receives it, whatever the
+ * source answers.
  */
 export declare type TupleSource = (req: {
     readonly subjectId: string | null;
@@ -12527,7 +12641,7 @@ export declare type TupleSource = (req: {
      * legitimately have no request.
      */
     readonly load: DataLoader | undefined;
-}) => Promise<ReadonlyArray<RelationTuple>> | ReadonlyArray<RelationTuple>;
+}) => Promise<ReadonlyArray<RelationTuple> | ResourceMissing> | ReadonlyArray<RelationTuple> | ResourceMissing;
 
 /** The mutation runner's key for opening the read-version map on a transaction
  *  view it obtained from the dialect store directly. */
@@ -12546,6 +12660,32 @@ declare interface TypedUpsertOptions<T extends AnyWritableTable> {
  */
 export declare const unbindConnection: (clientId: number) => void;
 
+/**
+ * The tagged failures an executor can produce that its procedure's wire union
+ * does not carry.
+ *
+ * Such a failure does not reach the caller as itself. On a mutation or action
+ * the server refuses to encode a tag its union cannot represent and sends
+ * `InternalError` instead; on a query it arrives under a tag the client's typed
+ * union does not know. Either way the error the author raised is not the error
+ * the caller can match on — and before this check, widening a shared helper's
+ * error type compiled at every call site while every one of them started
+ * failing that way.
+ *
+ * UNTAGGED failures (`Error`, `unknown`) are not reported: they never claimed to
+ * be a typed outcome, and the runtime treats them as defects by construction.
+ *
+ * Nor are the STORE's refusals (`StoreError`: `ConstraintViolation`,
+ * `TenantScopeViolation`, …). The framework raises them, not the handler's
+ * author, and what an undeclared one does is a documented contract: it reaches
+ * the caller as `InternalError` carrying its own sentence; declare it to surface
+ * it typed. Every `EffectStore` write carries the whole set in its failure
+ * channel, so counting them made the check fire on every write executor —
+ * measured on one app: 550 of 564 findings, burying the 14 that were the
+ * app's own tags, which is what this check exists to find.
+ */
+export declare type UndeclaredErrorTags<D extends ExecutorDescriptor, R> = Exclude<FailureTag<ExecutorFailure<R>>, FailureTag<ProcedureWireError<D>> | FailureTag<StoreError>>;
+
 export declare class UndeclaredTableAccess extends Error {
     readonly table: string;
     readonly operation: string;
@@ -13213,11 +13353,10 @@ export declare interface WorkflowFacadeOptions {
      *  Inspect HTTP + the `voltro workflows retry` CLI delegate to the same
      *  implementation. */
     readonly retry?: (runId: string, options: WorkflowRetryOptions) => Promise<WorkflowRetryResult>;
-    /** Backs {@link WorkflowsAppContext.redrive}. Supplied by the CLI's facade
-     *  builder, which owns the runs/steps store query + the cluster journal
-     *  adapter. Inspect HTTP + `voltro workflows redrive` delegate to the same
-     *  implementation. */
-    readonly redrive?: (runId: string) => Promise<WorkflowRedriveResult>;
+    /** Shared resident-authorized restart command and receipt adapters. */
+    readonly restart?: (command: WorkflowRestartCommand) => Promise<WorkflowRestartResult>;
+    readonly readRestart?: (target: Pick<WorkflowRestartCommand, 'runId' | 'requestId'>) => Promise<WorkflowRestartObservation>;
+    readonly withdrawRestart?: (command: WorkflowRestartCommand) => Promise<WorkflowRestartObservation>;
     /** Fired (fire-and-forget) right after a workflow is ENQUEUED — a start,
      *  child, or run. The CLI wires this to a cross-replica "wake" broadcast so
      *  the replica that OWNS the new run's shard polls immediately instead of
@@ -13395,16 +13534,6 @@ export declare interface WorkflowReadCtx {
     } | undefined;
 }
 
-/** Result of {@link WorkflowsAppContext.redrive} — whether the failed run's
- *  durable journal was re-driven, how many failed step attempts were reset so
- *  they re-execute, and a `reason` when it declined (no journal / still
- *  running / already succeeded). */
-export declare interface WorkflowRedriveResult {
-    readonly redriven: boolean;
-    readonly activitiesReset: number;
-    readonly reason: string | null;
-}
-
 /** Options for {@link WorkflowsAppContext.retry}. */
 export declare interface WorkflowRetryOptions {
     /** Persist once per deliberate retry and reuse after a lost response. */
@@ -13592,14 +13721,13 @@ export declare interface WorkflowsAppContext {
     retry(runId: string, options: WorkflowRetryOptions): Promise<WorkflowRetryResult>;
     /** Observe a durable retry intent without submitting another attempt. */
     readRetry(runId: string, requestId: string): Promise<WorkflowRetryObservation>;
-    /** Re-drive a terminally-`failed` run from the step it died on, reusing
-     *  its durable journal — the counterpart to {@link retry} (fresh execution,
-     *  empty journal) and to {@link resume} (which only re-drives a *suspended*
-     *  run). Addressed by run id (`wfrun_…`). Completed steps replay from the
-     *  journal; only the failed steps re-execute. Fix the downstream cause
-     *  first, then redrive. Refuses a run that is not a not-yet-discarded
-     *  failure. */
-    redrive(runId: string): Promise<WorkflowRedriveResult>;
+    /** Restart a failed run with its recorded successful steps. Persist the request
+     * ID and selection before submitting; a pending receipt is not engine entry. */
+    restart(runId: string, options: Omit<WorkflowRestartCommand, 'runId'>): Promise<WorkflowRestartResult>;
+    /** Read a saved restart request without dispatching work. */
+    readRestart(runId: string, requestId: string): Promise<WorkflowRestartObservation>;
+    /** Permanently fence an unreserved request. Accepted work is returned unchanged. */
+    withdrawRestart(runId: string, options: Omit<WorkflowRestartCommand, 'runId'>): Promise<WorkflowRestartObservation>;
 }
 
 export declare interface WorkflowSignalTarget {
@@ -13751,3 +13879,10 @@ export declare const wrapStoreWithMixinBehaviour: (rawUnderlying: DataStore, ctx
 export declare const writeReplicaObservation: (store: DataStore, kind: ReplicaObservationKind, payload: unknown) => Promise<void>;
 
 export { }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroPluginErrors {
+        readonly '@fixture/errors#RegisteredByPlugin': RegisteredByPlugin;
+    }
+}