@voltro/runtime 0.29.0 → 0.30.1

package/dist/index.d.ts

@@ -1274,7 +1274,30 @@ export declare interface BindEventInput {
     readonly guards?: Guards<unknown> | undefined;
 }
 
-export declare const bindMutation: <Input, Output, E = never>(execute: (input: Input, context: RuntimeContext) => Output | Promise<Output> | Effect.Effect<Output, E, never>, input: Input, spanName?: string, codec?: MutationOutputCodec<unknown>, idempotency?: IdempotencyBinding) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
+export declare const bindMutation: <Input, Output, E = never>(execute: (input: Input, context: RuntimeContext) => Output | Promise<Output> | Effect.Effect<Output, E, never>, input: Input, spanName?: string, codec?: MutationOutputCodec<unknown>, idempotency?: IdempotencyBinding, 
+/**
+ * This procedure's DECLARED error union (`descriptor.error`).
+ *
+ * The third category of failure, and the one two guards below could not see.
+ * A value that is TAGGED but not representable by this union is undeclared by
+ * construction: the untagged catch skips it (it has a `_tag`), the infra list
+ * skips it (it is not on a curated list), and the rpc encoder then cannot
+ * match it and ships the whole `ExitEncoded<…>` decode tree to the browser —
+ * ~2 KB for a one-line cause, with the message at the END so every tool that
+ * truncates shows the useless half.
+ *
+ * A consumer met it with `TenantScopeViolation`. Adding that tag to
+ * `INFRA_ERROR_TAGS` would have been wrong: `effectStore.ts` documents
+ * `error: Schema.Union(TenantScopeViolation, StoreOperationFailed, …)` as a
+ * supported declaration, so an app that DECLARES it must still receive it
+ * typed. The question is therefore not "is this tag infra" but "can THIS
+ * descriptor represent it" — which only the descriptor can answer.
+ *
+ * Omitted ⇒ the check is skipped entirely. A call site that cannot supply a
+ * schema keeps exactly the old behaviour rather than collapsing errors it
+ * cannot classify.
+ */
+declaredError?: Schema.Schema.All) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
 
 /**
  * Bind a non-reactive server→client stream (A3). The executor builds a
@@ -5723,6 +5746,26 @@ export declare type ReactionAct = {
 } | {
     readonly kind: 'workflow';
     readonly workflow: string;
+    /**
+     * Shape the workflow's payload from the change. Omit and the CHANGED ROW is
+     * the payload, as before.
+     *
+     * Without this the workflow's payload schema is dictated by the watched
+     * TABLE's row shape rather than by what the workflow needs, which drags two
+     * problems into every reaction-started workflow:
+     *
+     *   • every column travels, including ones the workflow has no business
+     *     seeing — a reaction on a users table hands the whole row to a
+     *     narration workflow;
+     *   • the row shape is DIALECT-dependent at the edges. A `timestamp()`
+     *     column arrives as a `Date` on MariaDB and a number elsewhere, so an
+     *     app normalising on both sides of an idempotency key is doing the
+     *     framework's job.
+     *
+     * A mapper fixes both at the declaration: the workflow declares the payload
+     * it wants and the reaction adapts.
+     */
+    readonly payload?: (event: ReactionEvent) => unknown;
 };
 
 export declare interface ReactionDefinition {
@@ -5749,10 +5792,35 @@ export declare interface ReactionGuards {
     /** Per-tenant AI spend ceiling (USD). Checked via the injected `checkBudget`
      *  (the app wires `requireAiBudget`). Over budget → the reaction refuses. */
     readonly costBudgetUsd?: number;
-    /** Per-reaction rate cap — at most `limit` firings per `windowMs`. */
+    /**
+     * Rate cap — at most `limit` firings per `windowMs`, PER KEY.
+     *
+     * ── Two defects this shape replaces, both reported from production ────────
+     *
+     * It read as a per-key cap and was neither. The runner keyed the limiter on
+     * the REACTION NAME, so one cap covered every row and every tenant the
+     * reaction watched: an app with a hundred tenants got a hundredth of the
+     * throughput it declared, and the busiest tenant starved the rest.
+     *
+     * And the limiter was in-memory, per process. With three replicas the
+     * effective cap was 3×, and nothing about the declaration said so — the same
+     * config produced a different limit depending on how many pods happened to be
+     * running.
+     *
+     * `key` is now REQUIRED to get per-entity behaviour, and the limiter is
+     * DURABLE (a claim in the shared store, the same INSERT-wins arbiter the cron
+     * scheduler uses), so the cap is the cap regardless of replica count.
+     *
+     * Omitting `key` keeps the old GLOBAL meaning — which is a legitimate thing to
+     * want (a cap on a scarce downstream), just not what the old field appeared to
+     * offer.
+     */
     readonly rateLimit?: {
         readonly limit: number;
         readonly windowMs: number;
+        /** Partitions the cap. `(event) => event.new.tenantId` for per-tenant,
+         *  `(event) => String(event.new.id)` for per-row. */
+        readonly key?: (event: ReactionEvent) => string;
     };
 }
 
@@ -5760,7 +5828,17 @@ export declare type ReactionOp = 'insert' | 'update' | 'delete';
 
 export declare type ReactionOutcome = 'acted' | 'skipped-op' | 'skipped-when' | 'skipped-dedupe' | 'skipped-ratelimit' | 'skipped-budget';
 
-/** A simple per-key sliding-window rate limiter (in-memory, per process). */
+/**
+ * A per-key sliding-window rate limiter — IN-MEMORY, PER PROCESS.
+ *
+ * Correct for a single-process deployment and wrong for every other one: with N
+ * replicas the effective cap is N×, silently. It stays as the FALLBACK the
+ * runner uses when no durable claimer is wired (dev on the memory store), and
+ * the runner logs once when it falls back, because "my limit is 3× what I
+ * declared" is not something anyone discovers by reading config.
+ *
+ * Prefer {@link ReactionRunDeps.claimRateSlot}.
+ */
 export declare class ReactionRateLimiter {
     private readonly hits;
     allow(key: string, limit: number, windowMs: number, now: number): boolean;
@@ -5781,6 +5859,14 @@ export declare interface ReactionRunDeps {
     /** Per-tenant AI budget check — true = within budget. Injected (wraps
      *  requireAiBudget). Only consulted when `guards.costBudgetUsd` is set. */
     readonly checkBudget?: (tenantId: string | null, budgetUsd: number) => boolean | Promise<boolean>;
+    /**
+     * Atomically claim ONE rate slot. `true` = we got it and may fire.
+     *
+     * Injected by the serve layer over the shared store, so the cap holds across
+     * replicas. Absent → the runner falls back to {@link ReactionRateLimiter},
+     * which is per-process and therefore N× on N replicas.
+     */
+    readonly claimRateSlot?: (key: string) => Promise<boolean>;
     readonly rateLimiter?: ReactionRateLimiter;
     readonly now?: () => number;
 }
@@ -8757,6 +8843,44 @@ export declare type WhereOp = '=' | '!=' | '<>' | '>' | '>=' | '<' | '<=' | 'in'
  */
 export declare const withRowFilter: <R extends ServeRequestContext>(request: R) => Promise<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
+ * bookkeeping entirely rather than calling a no-op.
+ */
+export declare type WorkflowAdmissionOutcome = {
+    readonly kind: 'passthrough';
+} | {
+    readonly kind: 'start';
+    /** What to start WITH. Differs from the caller's payload only for a batch
+     *  that filled up on this arrival. */
+    readonly payload: unknown;
+    /** Called once the engine returns an execution id: links the ledger row,
+     *  consumes any batched intents, evicts a singleton incumbent. */
+    readonly commit: (executionId: string) => Promise<void>;
+} | {
+    readonly kind: 'queued';
+    readonly intentId: string;
+    readonly mode: string;
+    readonly dueAt: number;
+} | {
+    readonly kind: 'dropped';
+    readonly retryAfterMs: number;
+} | {
+    readonly kind: 'skipped';
+    readonly executionId: string;
+};
+
+export declare interface WorkflowAdmissionRequest {
+    readonly workflowName: string;
+    readonly payload: unknown;
+    readonly callerContext: WorkflowCallerContext | undefined;
+    /** `true` for `run(...)` and `start(..., { wait: true })` — a caller blocking
+     *  for the RESULT. A deferring control has no coherent answer for one, so the
+     *  gate refuses it by name rather than doing something surprising. */
+    readonly waiting: boolean;
+}
+
 export declare interface WorkflowCallerContext {
     readonly subject?: unknown;
     readonly traceId?: string | null;
@@ -8771,6 +8895,19 @@ export declare interface WorkflowChildOptions {
     /* Excluded from this release type: callerContext */
 }
 
+/**
+ * Reject a blocking caller on a workflow whose flow control can DEFER.
+ *
+ * `run(...)` and `start({ wait: true })` block for the run's RESULT, and there
+ * is no result to return for a start that was collapsed into a future run.
+ * Silently starting it anyway would break the declared limit; silently
+ * returning nothing would break the caller's type. So it is an error that names
+ * both halves.
+ */
+export declare class WorkflowDeferredResultError extends Error {
+    constructor(workflowName: string, method: string, mode: string);
+}
+
 export declare interface WorkflowDefinitionLike {
     readonly name: string;
     readonly payloadSchema: Schema.Schema.Any;
@@ -8858,6 +8995,32 @@ export declare interface WorkflowFacadeOptions {
      *  waiting for its next storage tick. No-op when unset (single replica / no
      *  broker → the poll interval covers it). */
     readonly onEnqueue?: () => void;
+    /**
+     * Declarative flow control — the admission boundary every start passes
+     * through when the workflow declares `debounce` / `singleton` / `concurrency`
+     * / `throttle` / `rateLimit` / `batch`, or when an operator paused it.
+     *
+     * Injected, and absent by default, for the same reason `listRuns` is: the
+     * runtime stays storage-agnostic and the CLI owns the tables. Absent ⇒ every
+     * start takes exactly the path it took before flow control existed, which is
+     * what makes this feature free for a workflow that declares none.
+     */
+    readonly admitStart?: (input: WorkflowAdmissionRequest) => Promise<WorkflowAdmissionOutcome>;
+    /**
+     * What an ARRIVING start's payload is validated against, when that differs
+     * from the workflow's own `payload` schema.
+     *
+     * Exactly one control needs this: `batch`. A batching workflow's own payload
+     * is the accumulated `{ items: [...] }` — that is the declaration contract
+     * `validateFlowControl` enforces — while callers start it with a SINGLE item.
+     * Validating the caller's item against the batch shape rejects every start
+     * before the gate is reached, which is what shipped.
+     *
+     * Injected rather than derived, for the same reason `admitStart` is: the
+     * runtime does not know flow control exists. Returns `undefined` for every
+     * workflow that does not batch, which is the common case and costs nothing.
+     */
+    readonly startPayloadSchema?: (workflowName: string) => unknown | undefined;
 }
 
 export declare interface WorkflowLayerExecutionContext {
@@ -8898,6 +9061,20 @@ export declare class WorkflowPayloadError extends Error {
     missingFields: ReadonlyArray<string>, detail: string);
 }
 
+/**
+ * A blocking caller hit a `rateLimit` cap.
+ *
+ * `start()` reports a drop through the handle, because a fire-and-forget caller
+ * has somewhere to put it. `run()` has no such place — its return type is the
+ * workflow's success value — so the drop has to be an error, or it would look
+ * like a run that returned `undefined`.
+ */
+export declare class WorkflowRateLimitedError extends Error {
+    readonly workflowName: string;
+    readonly retryAfterMs: number;
+    constructor(workflowName: string, retryAfterMs: number);
+}
+
 /** 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
@@ -8929,6 +9106,24 @@ export declare interface WorkflowRunListFilter {
     readonly workflowName?: string;
     readonly tag?: string;
     readonly status?: WorkflowRunRecordStatus;
+    /** Several statuses at once (`['failed', 'cancelled']`). Ignored when the
+     *  single `status` is also set — one of them has to win, and the singular,
+     *  older spelling is the one existing callers already rely on. */
+    readonly statuses?: ReadonlyArray<WorkflowRunRecordStatus>;
+    /** Case-insensitive substring match on the workflow tag — the search-box
+     *  semantic, where `tag`/`workflowName` are exact. */
+    readonly tagContains?: string;
+    /** Exact match on the run's recorded `source` (`workflow-rpc`,
+     *  `app-context`, `inspect`, `schedule:<name>`, …). */
+    readonly source?: string;
+    /** Prefix match against the run id OR the execution id — what a human
+     *  pastes from a log line. Case-sensitive, because ids are. */
+    readonly idPrefix?: string;
+    /** Only runs started at/after this instant. With `startedBefore` this is
+     *  the time-range view; each bound works alone too. */
+    readonly startedAfter?: Date;
+    /** Only runs started strictly before this instant. */
+    readonly startedBefore?: Date;
     /** The DEAD-LETTER view: failed runs an operator has NOT yet discarded
      *  (`status = 'failed' AND discardedAt IS NULL`). Since the framework applies no
      *  retry, a `failed` run is terminal — this is the queue of unhandled failures.
@@ -9035,16 +9230,31 @@ export declare interface WorkflowSignalTarget {
     readonly workflowName?: string;
 }
 
+/** A blocking caller lost a `singleton: { mode: 'skip' }` race. Carries the
+ *  incumbent's execution id, so the caller can wait on THAT run instead. */
+export declare class WorkflowSingletonHeldError extends Error {
+    readonly workflowName: string;
+    readonly executionId: string;
+    constructor(workflowName: string, executionId: string);
+}
+
 export declare interface WorkflowStartOptions {
     readonly wait?: boolean;
     /* Excluded from this release type: callerContext */
+    /* Excluded from this release type: admitted */
 }
 
 export declare const workflowToRpc: (workflow: WorkflowDefinitionLike) => Rpc.Rpc<string, Schema.Schema.Any, Schema.Struct<{
     id: typeof Schema.String;
     workflowName: typeof Schema.String;
-    executionId: typeof Schema.String;
-    status: Schema.Literal<["running"]>;
+    executionId: Schema.NullOr<typeof Schema.String>;
+    status: Schema.Literal<["running", "queued", "dropped", "skipped"]>;
+    deferral: Schema.optional<Schema.Struct<{
+        mode: typeof Schema.String;
+        dueAt: Schema.NullOr<typeof Schema.Number>;
+        retryAfterMs: Schema.NullOr<typeof Schema.Number>;
+        intentId: Schema.NullOr<typeof Schema.String>;
+    }>>;
 }>, Schema.Schema.All, never>;
 
 export declare interface WorkflowUpdateOptions {