@voltro/runtime 0.28.0 → 0.30.0

package/dist/index.d.ts

@@ -56,6 +56,7 @@ import { Row } from '@voltro/database';
 import { Rpc } from '@effect/rpc';
 import { RpcGroup } from '@effect/rpc';
 import { RpcInterceptor } from '@voltro/protocol';
+import { RuleReadStore } from '@voltro/database';
 import { Sampler } from '@opentelemetry/sdk-trace-base';
 import { Schedule } from 'effect';
 import { Schema } from 'effect';
@@ -677,6 +678,8 @@ export declare interface AnalyticsTopEntry {
 
 declare type AnyRow = Record<string, unknown>;
 
+declare type AnyRow_2 = Record<string, unknown>;
+
 export declare const API_KEYS_TABLE = "_voltro_api_keys";
 
 /** Admin-gated management routes (issue / list / revoke) for the built-in keys.
@@ -1018,6 +1021,17 @@ export declare const assertCan: (subject: RebacSubject, action: string, resource
  */
 export declare const assertConnectionCipherConfigured: (definitions: ReadonlyArray<ConnectionDefinition>) => void;
 
+/**
+ * Assign a subject to a variant — STABLE (same subject ⇒ same variant, always)
+ * and BALANCED (proportions converge to the weights over many subjects). The
+ * assignment is salted with the experiment `name`, so one subject buckets
+ * independently across different experiments.
+ *
+ * A `holdout` fraction is carved off the top of the interval FIRST; the
+ * remaining space is split by variant weight. Pure — a client can reproduce it.
+ */
+export declare const assignVariant: (def: ExperimentDefinition, subject: string) => string;
+
 /**
  * Async cache surface exposed as `ctx.cache` to non-Effect handlers — the
  * facade over the Effect-native `Cache` service from `@voltro/cache`
@@ -1095,6 +1109,82 @@ export declare interface AttachAnalyticsMirrorOptions {
     readonly run?: (effect: Effect.Effect<void, unknown>) => Promise<unknown>;
 }
 
+/**
+ * Wire every discovered expectation onto the store's CDC channel + a clock tick,
+ * and expose the live signal via a registry. Returns the registry impl + a
+ * detach for graceful shutdown — the SAME shape as the aggregate runner.
+ *
+ * Both boot paths (`voltro dev`, `voltro serve`) must call this and provide the
+ * resulting `ExpectationRegistry` layer, exactly like `AggregateRegistry`.
+ */
+export declare const attachExpectations: (options: AttachExpectationsOptions) => ExpectationRunnerHandle;
+
+export declare interface AttachExpectationsOptions {
+    readonly discovered: ReadonlyArray<{
+        readonly definition: ExpectationDefinition;
+    }>;
+    readonly store: DataStore;
+    readonly log: SyncLogger;
+    /** Wall clock. Default `Date.now`. */
+    readonly now?: () => number;
+    /** How often the time-dependent invariants (freshness) are re-checked against
+     *  the clock. Default 30s. Ignored when no expectation is time-dependent. */
+    readonly tickIntervalMs?: number;
+    /** Periodic full re-seed interval (drift healing), mirroring the aggregate
+     *  runner's reconcile. Default 5m. */
+    readonly reconcileIntervalMs?: number;
+}
+
+/**
+ * Wire every discovered experiment onto the store's CDC channel and expose the
+ * live results via a registry. Returns the registry impl + a detach for graceful
+ * shutdown — the SAME shape as `attachExpectations` / `attachFinops`.
+ *
+ * Both boot paths (`voltro dev`, `voltro serve`) must call this and provide the
+ * resulting `ExperimentRegistry` layer, exactly like `AggregateRegistry`
+ * (deferred cli work — see the NOTE at the bottom of this file).
+ */
+export declare const attachExperiments: (options: AttachExperimentsOptions) => ExperimentRunnerHandle;
+
+export declare interface AttachExperimentsOptions {
+    readonly discovered: ReadonlyArray<{
+        readonly definition: ExperimentDefinition;
+    }>;
+    readonly store: DataStore;
+    readonly log: SyncLogger;
+    /** Wall clock. Default `Date.now`. */
+    readonly now?: () => number;
+    /** Periodic full re-seed interval (drift healing), mirroring the aggregate
+     *  runner's reconcile. Default 5m. */
+    readonly reconcileIntervalMs?: number;
+}
+
+/**
+ * Wire every discovered cost budget into a `CostAccountant` + a clock tick, and
+ * expose the live attribution + budget signal via a `CostRegistry`. Returns the
+ * registry impl + the `record` ingestion entry point + a detach — the SAME shape
+ * as `attachExpectations`.
+ *
+ * Both boot paths (`voltro dev`, `voltro serve`) must call this and provide the
+ * resulting `CostRegistry` layer, exactly like `ExpectationRegistry`; the
+ * `record` returned here is the seam the dispatcher's recompute + the query path
+ * call to emit cost events (see the NOTE at the bottom of this file — that call-
+ * site instrumentation + `*.budget.ts` discovery are the deferred cli work).
+ */
+export declare const attachFinops: (options: AttachFinopsOptions) => FinopsRunnerHandle;
+
+export declare interface AttachFinopsOptions {
+    readonly discovered: ReadonlyArray<{
+        readonly definition: CostBudgetDefinition;
+    }>;
+    readonly log: SyncLogger;
+    /** Wall clock. Default `Date.now`. */
+    readonly now?: () => number;
+    /** How often windowed budgets are re-checked against the clock for a rollover
+     *  recovery. Default 30s. Ignored when no budget is windowed. */
+    readonly tickIntervalMs?: number;
+}
+
 /** The descriptor shape the audit needs — a `defineQuery` result carries it. */
 export declare interface AuditableQuery {
     readonly name: string;
@@ -1184,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
@@ -1770,6 +1883,206 @@ export declare interface Coordinator {
     tryClaim(scheduleName: string, scheduledAt: Date): Promise<boolean>;
 }
 
+/**
+ * The standing compute-cost accountant. Fold `CostEvent`s in with `record`;
+ * read attribution + budget state through the getters; roll windows with `tick`.
+ * Every method is synchronous and allocation-light — it is on the reactive
+ * recompute hot path.
+ */
+export declare class CostAccountant {
+    private readonly now;
+    private readonly attribution;
+    private readonly counters;
+    private readonly budgetsByName;
+    private readonly totalBudgets;
+    private readonly unitBudgets;
+    constructor(definitions: ReadonlyArray<CostBudgetDefinition>, deps?: CostAccountantDeps);
+    private counterFor;
+    /** Attribute one cost event and evaluate every budget that watches its unit.
+     *  Returns the threshold-crossing signals produced (empty in the common,
+     *  no-crossing case). */
+    record(event: CostEvent): ReadonlyArray<CostBudgetSignal>;
+    /** Roll every windowed budget whose window has elapsed, with no event —
+     *  a budget recovers when its window passes even if the tenant went quiet.
+     *  Returns the `recovered` signals produced. */
+    tick(): ReadonlyArray<CostBudgetSignal>;
+    /** Reset attribution + every budget counter for one tenant, or ALL tenants
+     *  when `tenantId` is `undefined` (the system tenant is `null`, and IS
+     *  targetable). Returns the `recovered` signals for any budget that was
+     *  breached. Use for a chargeback-period rollover the windows don't express,
+     *  or a test reset. */
+    reset(tenantId?: string | null): ReadonlyArray<CostBudgetSignal>;
+    private allCounterTenants;
+    attributionSnapshot(): ReadonlyArray<TenantCostState>;
+    tenantState(tenantId: string | null): TenantCostState | null;
+    budgetStates(): ReadonlyArray<CostBudgetState>;
+    budgetState(name: string, tenantId: string | null): CostBudgetState | null;
+    breaches(): ReadonlyArray<CostBudgetState>;
+}
+
+export declare interface CostAccountantDeps {
+    /** Wall clock. Injectable for deterministic tests. Default `Date.now`. */
+    readonly now?: () => number;
+    readonly log?: SyncLogger;
+}
+
+export declare interface CostBudgetDefinition {
+    /** Brand marker — lets the cli discriminate default-exported budget
+     *  definitions from arbitrary objects during file discovery. */
+    readonly _voltroCostBudget: true;
+    readonly name: string;
+    readonly limit: number;
+    /** Resolved cost unit, or `null` for a total-across-all-units budget. */
+    readonly unit: string | null;
+    readonly warnAt: number;
+    /** Resolved tumbling-window length in ms, or `null` for a cumulative budget. */
+    readonly windowMs: number | null;
+    readonly severity: CostBudgetSeverity;
+    readonly description?: string;
+}
+
+export declare interface CostBudgetDefinitionInput {
+    /** Stable id within the app. Unique across all cost budgets. */
+    readonly name: string;
+    /** The per-tenant ceiling, in the budget's `unit` (or the tenant's grand
+     *  total when `unit` is omitted). A tenant crossing this is `exceeded`. */
+    readonly limit: number;
+    /** Which cost unit this budget meters. Omitted ⇒ the tenant's TOTAL across
+     *  every unit (the common "total compute per tenant" cap). When set, only
+     *  `CostEvent`s of this unit count toward the budget. */
+    readonly unit?: string;
+    /** Fraction of `limit` (0..1) at which the budget goes `warn` — the early
+     *  signal before the hard cap. Default `0.8`. Set `1` to disable the warn
+     *  band (straight ok→exceeded). */
+    readonly warnAt?: number;
+    /** Tumbling window as an interval string (`'1h'`, `'24h'`). The per-tenant
+     *  counter resets at each window boundary (and a breached budget RECOVERS).
+     *  Omitted ⇒ a cumulative budget that only resets on an explicit
+     *  `reset(tenantId)` — the since-boot chargeback ceiling. */
+    readonly window?: string;
+    /** Alerting priority carried on the breach signal. Default `'warn'`. */
+    readonly severity?: CostBudgetSeverity;
+    /** Human-facing note surfaced in devtools / the breach message. */
+    readonly description?: string;
+}
+
+/** How loud a budget breach is. A classification carried on the signal for
+ *  alerting priority — the framework never BLOCKS compute on a budget here
+ *  (that is a caller's choice, the way `requireAiBudget` fails a call); a cost
+ *  budget is an observability-grade signal over work that already happened. */
+export declare type CostBudgetSeverity = 'info' | 'warn' | 'critical';
+
+/** Emitted when a budget crosses a threshold for a tenant. `warn` / `exceeded`
+ *  are upward crossings (event-driven, with a cause); `recovered` is a window
+ *  rollover / reset back to `ok` (no cause). */
+export declare interface CostBudgetSignal {
+    readonly kind: 'warn' | 'exceeded' | 'recovered';
+    readonly state: CostBudgetState;
+    readonly cause: CostCause | null;
+}
+
+/** The live state of one budget for one tenant — the row an inspect endpoint /
+ *  dashboard reads. */
+export declare interface CostBudgetState {
+    readonly budget: string;
+    readonly tenantId: string | null;
+    readonly status: CostBudgetStatus;
+    readonly severity: CostBudgetSeverity;
+    /** The metered cost against this budget in the current window. */
+    readonly spent: number;
+    /** The hard ceiling. */
+    readonly limit: number;
+    /** The absolute warn ceiling (`warnAt * limit`). */
+    readonly warnThreshold: number;
+    /** The unit this budget meters, or `null` for a total-across-units budget. */
+    readonly unit: string | null;
+    /** When the current window opened (windowed budgets), else `null`. */
+    readonly windowStartedAt: number | null;
+    /** When this budget last entered its current `status`. */
+    readonly since: number | null;
+    readonly lastUpdatedAt: number | null;
+    /** The most recent breach's cause, retained across recovery for the audit
+     *  trail. `null` if it has never been breached. */
+    readonly lastCause: CostCause | null;
+    readonly description?: string;
+}
+
+/** A budget's status for one tenant. `ok` below the warn band, `warn` at/over
+ *  `warnAt * limit`, `exceeded` at/over `limit`. Monotonic within a window;
+ *  resets to `ok` on window rollover / explicit reset. */
+export declare type CostBudgetStatus = 'ok' | 'warn' | 'exceeded';
+
+/** What incurred the cost that tipped a budget across a threshold — resolved
+ *  from the `CostEvent`. `null` when the transition was window-driven (a budget
+ *  RECOVERING because its window rolled over, with no event). */
+export declare interface CostCause {
+    readonly unit: string;
+    readonly subscriptionId?: string | null;
+    readonly procedure?: string | null;
+    readonly traceId?: string | null;
+}
+
+/**
+ * One unit of attributed compute. A compute site (a reactive recompute in the
+ * dispatcher, a query, a fan-out delivery, or any pluggable cost source) emits
+ * one of these tagged with the tenant/subscription that caused it, and the
+ * accountant folds it into the standing per-tenant total AND every budget that
+ * watches its `unit`.
+ *
+ * `amount` is a NORMALISED cost figure in whatever unit the caller chose — 1 per
+ * recompute, rows scanned, milliseconds elapsed, a priced micro-USD. The
+ * framework does not impose a cost model; `unit` names which one this event is
+ * denominated in, and a budget either targets that named unit or the tenant's
+ * grand total. This is the "pluggable cost unit" seam.
+ */
+export declare interface CostEvent {
+    /** Active org id the compute is attributed to. `null` = system / untenanted
+     *  work (a schedule, a resumed workflow — `SYSTEM_SUBJECT.tenantId`). */
+    readonly tenantId: string | null;
+    /** The live subscription that drove this compute, when the cost came from a
+     *  reactive recompute — the per-subscription attribution the plan calls for.
+     *  Absent for non-subscription compute (a one-shot query). */
+    readonly subscriptionId?: string | null;
+    /** Which cost unit `amount` is denominated in — `'recompute'`, `'query'`,
+     *  `'fanout'`, or any custom unit the caller meters. */
+    readonly unit: string;
+    /** The normalised cost contribution in `unit`. Non-finite / negative amounts
+     *  are ignored by the accountant (a cost cannot be negative). */
+    readonly amount: number;
+    /** The rpc tag of the call that incurred the cost, for the "why is my bill
+     *  high" breakdown + the breach cause. */
+    readonly procedure?: string | null;
+    /** The trace the offending compute ran under — joins to `voltro logs --trace`. */
+    readonly traceId?: string | null;
+    /** Wall-clock ms the cost was incurred. Default: the accountant's clock. */
+    readonly at?: number;
+}
+
+/**
+ * Framework-provided registry of per-tenant compute-cost attribution + every
+ * budget the cli discovered. Handler / inspect code reads the live signal here,
+ * exactly as it reads `ExpectationRegistry`.
+ */
+export declare class CostRegistry extends CostRegistry_base {
+}
+
+declare const CostRegistry_base: Context.TagClass<CostRegistry, "@voltro/CostRegistry", CostRegistryApi>;
+
+export declare interface CostRegistryApi {
+    /** Per-tenant compute-cost attribution — the chargeback feed. */
+    readonly attribution: () => ReadonlyArray<TenantCostState>;
+    /** One tenant's attribution, or `null` when nothing has been attributed. */
+    readonly tenant: (tenantId: string | null) => TenantCostState | null;
+    /** Every (budget, tenant) state — the full budget snapshot. */
+    readonly budgets: () => ReadonlyArray<CostBudgetState>;
+    /** One budget's state for one tenant, or `null` when unseen. */
+    readonly budget: (name: string, tenantId: string | null) => CostBudgetState | null;
+    /** Only the currently warn/exceeded budget states — the alerting view. */
+    readonly breaches: () => ReadonlyArray<CostBudgetState>;
+    /** Subscribe to budget threshold crossings. Returns an unsubscribe fn. */
+    readonly subscribe: (listener: (s: CostBudgetSignal) => void) => () => void;
+}
+
 /** Define a cumulative counter. Increment with `incrementMetric` / `Metric.increment`. */
 export declare const counter: (name: string, description?: string) => Metric.Metric.Counter<number>;
 
@@ -2005,6 +2318,32 @@ export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
  */
 export declare const DEFAULT_ROW_FILTER_RETRY: Schedule.Schedule<unknown, unknown>;
 
+/**
+ * The message of an UNDECLARED throw, bounded, with nothing else attached.
+ *
+ * An executor that throws a plain `TypeError` produces a DEFECT, not a typed
+ * failure — so `catchIf(isInfraError)` above never sees it (that guards the E
+ * channel) and the rpc encoder tried to match it against the descriptor's
+ * `error:` union. It cannot match, by definition: a defect is precisely the
+ * thing that is not in the union. What reached the browser was the entire
+ * decode tree — every union member, the full `ExitEncoded<…>` type, and the
+ * real cause on the last line. ~2 KB of type names, which one consumer's
+ * account page rendered verbatim where a reason belonged, and which every app
+ * otherwise has to condense heuristically to avoid putting a schema on screen.
+ *
+ * `message` ONLY — no stack, no `cause` chain, no own fields. The same
+ * reasoning as `wireErrorFromCause`: a nested object can carry a DSN or a
+ * token. A message is what the server already logged and what a human needs;
+ * the full original stays in the server log via `logHandlerFailure`.
+ *
+ * Note the deliberate asymmetry with `isInfraError`, which collapses to the
+ * generic text instead: a `SqlError`'s message names internal `table.column`
+ * detail, so its text is withheld on purpose. An arbitrary app defect has no
+ * such known shape — withholding it too would leave the app exactly where it
+ * started, with a reason it cannot show.
+ */
+export declare const defectMessage: (defect: unknown) => string;
+
 /**
  * Construct an aggregate definition. The returned object brands itself
  * so the cli's file-discovery pass picks it up from default exports.
@@ -2043,6 +2382,27 @@ export declare const defineAggregate: <Row>(input: AggregateDefinitionInput<Row>
  */
 export declare const defineConnection: <D extends ConnectionDefinition>(definition: D) => D;
 
+/**
+ * Declare a per-tenant compute-cost budget. Validates the shape at declaration
+ * time so a malformed budget fails LOUD at boot rather than silently never
+ * firing (the same discipline as `defineExpectation`).
+ *
+ * ```ts
+ * // apps/api/budgets/tenantCompute.budget.ts
+ * import { defineCostBudget } from '@voltro/runtime'
+ *
+ * export default defineCostBudget({
+ *   name: 'tenant-recompute-hourly',
+ *   unit: 'recompute',
+ *   limit: 100_000,          // 100k recomputes per tenant per hour
+ *   warnAt: 0.8,             // warn at 80k
+ *   window: '1h',
+ *   severity: 'warn',
+ * })
+ * ```
+ */
+export declare const defineCostBudget: (input: CostBudgetDefinitionInput) => CostBudgetDefinition;
+
 export declare const defineEventTrigger: <EventPayload = unknown, WorkflowPayload = EventPayload>(spec: Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag"> | (Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag" | "event"> & {
     /** A declared event. Its `name` becomes the matched event. */
     readonly on: {
@@ -2058,6 +2418,46 @@ export declare const defineEventTrigger: <EventPayload = unknown, WorkflowPayloa
  */
 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>);
 
+/**
+ * Declare a data-quality expectation. Validates the shape at declaration time so
+ * a malformed contract fails LOUD at boot rather than silently never firing.
+ *
+ * ```ts
+ * // apps/api/expectations/orderFreshness.expectation.ts
+ * import { defineExpectation } from '@voltro/runtime'
+ *
+ * export default defineExpectation({
+ *   name: 'orders-fresh',
+ *   on: { table: 'orders' },
+ *   invariant: { kind: 'freshness', column: 'createdAt', maxAgeMs: 10 * 60_000 },
+ *   severity: 'critical',
+ * })
+ * ```
+ */
+export declare const defineExpectation: (input: ExpectationDefinitionInput) => ExpectationDefinition;
+
+/**
+ * Declare an online experiment. Validates the shape at declaration time so a
+ * malformed experiment fails LOUD at boot rather than silently never producing a
+ * result (the same discipline as `defineExpectation` / `defineCostBudget`).
+ *
+ * ```ts
+ * // apps/api/experiments/checkoutColor.experiment.ts
+ * import { defineExperiment } from '@voltro/runtime'
+ *
+ * export default defineExperiment({
+ *   name: 'checkout-button-color',
+ *   on: { table: 'orders' },
+ *   subject: 'userId',                       // stable per-user bucketing
+ *   variants: [{ name: 'control' }, { name: 'green' }],
+ *   holdout: 0.1,                            // 10% see nothing, for a clean baseline
+ *   metric: { kind: 'conversionRate', column: 'completed' },
+ *   baseline: 'control',
+ * })
+ * ```
+ */
+export declare const defineExperiment: (input: ExperimentDefinitionInput) => ExperimentDefinition;
+
 /**
  * Declare who delivers an effect. One per `*.outbox.ts` file.
  *
@@ -2129,6 +2529,21 @@ export { DialectReplicationAdapter }
  *  delete → every field `value→undefined`; update → only the changed fields. */
 export declare const diffChange: (c: CdcChange) => RowDiff;
 
+export declare interface DiscoveredCostBudget {
+    readonly file: string;
+    readonly definition: CostBudgetDefinition;
+}
+
+export declare interface DiscoveredExpectation {
+    readonly file: string;
+    readonly definition: ExpectationDefinition;
+}
+
+export declare interface DiscoveredExperiment {
+    readonly file: string;
+    readonly definition: ExperimentDefinition;
+}
+
 export declare interface DiscoveredWorkflowLike<Context = unknown> {
     readonly definition: WorkflowDefinitionLike;
     readonly buildExecute: (ctx: Context) => (payload: never, executionId: string) => Effect.Effect<unknown, unknown, unknown>;
@@ -2266,6 +2681,19 @@ export declare interface DispatcherDependencies {
      *  the trace buffer so the dashboards show each data transfer's latency.
      *  No-op when absent (tests, embedders that don't trace). */
     readonly recordDelivery?: (delivery: SubscriptionDelivery) => void;
+    /**
+     * Optional reactive-compute cost sink (the finops runner's `record`). Called
+     * once per reactive RECOMPUTE delivery — a change re-ran an affected
+     * subscription and pushed it a delta — with `unit: 'recompute', amount: 1`
+     * attributed to the subscription's tenant. Sibling to `recordDelivery`: same
+     * call sites, a different ledger (chargeback / budget vs latency trace).
+     *
+     * No-op when absent (tests, embedders, apps with no `*.budget.ts`). The hot
+     * path pays nothing in that case — the `CostEvent` is only allocated inside
+     * the `recordCost !== undefined` guard, never eagerly. Wired by both boot
+     * paths ONLY when finops is attached; see `attachFinops`.
+     */
+    readonly recordCost?: (event: CostEvent) => void;
     /** Optional snapshot cache (Layer 3). Absent → queries are never cached;
      *  present → subscriptions whose descriptor opted in (a `cacheBinding`
      *  is passed to `subscribe`) share + cache their initial snapshot. */
@@ -2402,6 +2830,21 @@ export declare const enterRequestLoader: (loader: DataLoader) => void;
  *  Promise-wrapped to satisfy the async contract. */
 export declare const envSecretsBackend: SecretsBackend;
 
+/**
+ * Evaluate every declared rule of every touched table's rows. Throws the first
+ * error-severity `BusinessRuleViolation` (rolling back the transaction);
+ * warning-severity violations log and continue.
+ *
+ * A predicate that itself throws a `BusinessRuleViolation` (the author built one
+ * directly) is re-thrown as-is; any OTHER thrown value propagates unchanged — a
+ * real failure (a DB error) must not be silently reclassified as a violation.
+ */
+export declare const evaluateTouchedRules: (params: {
+    readonly touched: ReadonlyArray<TouchedRow>;
+    readonly store: RuleReadStore;
+    readonly subject: unknown;
+}) => Promise<void>;
+
 /**
  * How many deliveries one client may fall behind before the oldest are dropped.
  *
@@ -2778,6 +3221,451 @@ export declare type ExecutorOutput<D extends ExecutorDescriptor> = Schema.Schema
  */
 export declare type ExecutorReturn<D extends ExecutorDescriptor, E, R> = ExecutorOutput<D> | Promise<ExecutorOutput<D>> | Effect.Effect<ExecutorOutput<D>, E, R> | ReactiveReturn<D>;
 
+/** The write that tipped an expectation into violation, resolved from the CDC
+ *  `ChangeEvent` that caused it — the provenance link the plan calls for. `null`
+ *  when the transition was CLOCK-driven (a freshness SLA aging out with no
+ *  write) rather than write-driven: the honest answer is "no write caused this;
+ *  the ABSENCE of writes did". */
+export declare interface ExpectationCause {
+    readonly table: string;
+    readonly op: 'insert' | 'update' | 'delete';
+    /** The trace the offending write ran under — joins to `voltro logs --trace`
+     *  and the audit sink. */
+    readonly traceId?: string | null;
+    /** The acting identity behind the offending write. */
+    readonly subjectId?: string | null;
+    /** The rpc tag of the call that made the offending write, when carried. */
+    readonly procedure?: string | null;
+}
+
+export declare interface ExpectationDefinition {
+    /** Brand marker — lets the cli discriminate default-exported expectation
+     *  definitions from arbitrary objects during file discovery. */
+    readonly _voltroExpectation: true;
+    readonly name: string;
+    readonly on: {
+        readonly table: string;
+        readonly where?: (row: Readonly<Record<string, unknown>>) => boolean;
+    };
+    readonly invariant: ExpectationInvariant;
+    readonly severity: ExpectationSeverity;
+    readonly description?: string;
+}
+
+export declare interface ExpectationDefinitionInput {
+    /** Stable id within the app. Unique across all expectations. */
+    readonly name: string;
+    /** The watched table. Its CDC deltas drive re-evaluation. An optional `where`
+     *  narrows the population the invariant is asserted over — a pure predicate
+     *  evaluated server-side per row (rows failing it are excluded from the
+     *  metric). It never leaves the server, so it can be any predicate. */
+    readonly on: {
+        readonly table: string;
+        readonly where?: (row: Readonly<Record<string, unknown>>) => boolean;
+    };
+    readonly invariant: ExpectationInvariant;
+    /** Alerting priority carried on the violation signal. Default `'warn'`. */
+    readonly severity?: ExpectationSeverity;
+    /** Human-facing note surfaced in devtools / the violation message. */
+    readonly description?: string;
+}
+
+/**
+ * Evaluates ONE expectation. Seed once, then feed CDC deltas via `applyChange`
+ * and (for a time-dependent invariant) clock ticks via `tick`. Each call
+ * re-reads the maintained metric, updates the live state, and returns a
+ * transition when the holding/violated boundary is crossed.
+ */
+export declare class ExpectationEvaluator {
+    private readonly def;
+    private readonly deps;
+    private readonly engine;
+    private readonly now;
+    private seeded;
+    private status;
+    private metric;
+    private threshold;
+    private since;
+    private lastEvaluatedAt;
+    private lastCause;
+    constructor(def: ExpectationDefinition, deps: ExpectationEvaluatorDeps);
+    get timeDependent(): boolean;
+    /** Whether a row is in the asserted population (honours `on.where`). */
+    private inScope;
+    /** Seed the metric from the current base rows and evaluate the initial state.
+     *  Never emits a transition (there is no prior state to cross from). */
+    seed(): Promise<void>;
+    /**
+     * Apply one CDC change and re-evaluate. Returns a transition if the change
+     * (or the reshaped population) crossed the boundary. A change to a row that is
+     * out of scope on BOTH images is ignored.
+     */
+    applyChange(event: ChangeEvent): Promise<ExpectationTransition | null>;
+    /** Re-evaluate against the current clock WITHOUT a write — for a
+     *  time-dependent invariant (freshness) whose metric ages on its own. Returns
+     *  a transition if the clock alone crossed the boundary. */
+    tick(): ExpectationTransition | null;
+    private commitReading;
+    state(): ExpectationState;
+}
+
+export declare interface ExpectationEvaluatorDeps {
+    /** Read the full current base rows — used to SEED and to resolve a min/max
+     *  rescan (freshness) from the post-commit table. */
+    readonly queryBase: () => Promise<ReadonlyArray<Row_5>>;
+    /** Wall clock. Injectable for deterministic tests. Default `Date.now`. */
+    readonly now?: () => number;
+    readonly log?: SyncLogger;
+}
+
+/**
+ * The data-quality invariant an expectation asserts. Each variant is chosen so
+ * it reduces the watched table to a SINGLE incrementally-maintained metric that
+ * rides the IVM engine (or a delta-driven filtered count), then compares that
+ * metric against a threshold:
+ *
+ *  - `freshness`   — max(column) → `age = now - max`; violated when
+ *                    `age > maxAgeMs`. Rides the IVM `max` maintainer (incl. its
+ *                    rescan-on-extreme-delete protocol). TIME-DEPENDENT: it is
+ *                    re-checked on a clock tick as well as on write, because the
+ *                    metric ages with the wall clock even when no write arrives —
+ *                    which is exactly when a freshness SLA matters.
+ *  - `nullRate`    — fraction of rows whose `column` is null; violated when
+ *                    `rate > maxRate`. Delta-maintained filtered count.
+ *  - `rowCount`    — COUNT(*) of the table; violated when out of `[min, max]`.
+ *  - `valueBounds` — fraction of rows whose numeric `column` falls outside
+ *                    `[min, max]` (the distribution / range check). Violated when
+ *                    that fraction exceeds `maxViolationRate`, or — when no rate
+ *                    is given — when ANY row is out of bounds.
+ */
+export declare type ExpectationInvariant = {
+    readonly kind: 'freshness';
+    readonly column: string;
+    readonly maxAgeMs: number;
+} | {
+    readonly kind: 'nullRate';
+    readonly column: string;
+    readonly maxRate: number;
+} | {
+    readonly kind: 'rowCount';
+    readonly min?: number;
+    readonly max?: number;
+} | {
+    readonly kind: 'valueBounds';
+    readonly column: string;
+    readonly min?: number;
+    readonly max?: number;
+    /** When set, the expectation tolerates up to this FRACTION (0..1) of
+     *  out-of-bounds rows before firing. Omitted ⇒ a single out-of-bounds row
+     *  violates. */
+    readonly maxViolationRate?: number;
+};
+
+/**
+ * Framework-provided registry of every expectation the cli discovered + the
+ * evaluator maintains. Handler / inspect code reads the live signal here.
+ */
+export declare class ExpectationRegistry extends ExpectationRegistry_base {
+}
+
+declare const ExpectationRegistry_base: Context.TagClass<ExpectationRegistry, "@voltro/ExpectationRegistry", ExpectationRegistryApi>;
+
+export declare interface ExpectationRegistryApi {
+    /** Snapshot every registered expectation's current state — the inspect feed. */
+    readonly snapshot: () => ReadonlyArray<ExpectationState>;
+    /** One expectation's state by name, or `null` when unknown. */
+    readonly get: (name: string) => ExpectationState | null;
+    /** Only the currently-violated expectations — the alerting view. */
+    readonly violations: () => ReadonlyArray<ExpectationState>;
+    /** Subscribe to holding/violated transitions. Returns an unsubscribe fn. */
+    readonly subscribe: (listener: (t: ExpectationTransition) => void) => () => void;
+}
+
+export declare interface ExpectationRunnerHandle {
+    readonly registry: ExpectationRegistryApi;
+    readonly detach: () => void;
+    readonly registered: ReadonlyArray<string>;
+    /** Test/debug seam: run one clock re-check of the time-dependent
+     *  expectations at `nowMs` (or the injected clock) and return the snapshot.
+     *  This is what the periodic tick timer calls. */
+    readonly runTick: () => void;
+}
+
+/** How loud a violation is. Purely a classification carried on the signal —
+ *  the framework never blocks a write on any severity (that is a business
+ *  rule's job); severity drives alerting priority downstream. */
+export declare type ExpectationSeverity = 'info' | 'warn' | 'critical';
+
+/** The live state of one expectation — the row an inspect endpoint / dashboard
+ *  reads. */
+export declare interface ExpectationState {
+    readonly name: string;
+    readonly table: string;
+    readonly invariant: ExpectationInvariant['kind'];
+    readonly severity: ExpectationSeverity;
+    readonly status: ExpectationStatus;
+    /** The measured metric: freshness → age in ms; nullRate / valueBounds(rate) →
+     *  a fraction; rowCount → the count; valueBounds(count) → number of bad rows.
+     *  `null` when the metric is undefined over the current data. */
+    readonly metric: number | null;
+    /** The threshold the metric is compared against (for display). */
+    readonly threshold: number | null;
+    /** When the expectation entered its current `status`. */
+    readonly since: Date | null;
+    /** When it was last (re-)evaluated. */
+    readonly lastEvaluatedAt: Date | null;
+    /** The most recent violation's provenance, retained across recovery for the
+     *  audit trail. `null` if it has never been violated. */
+    readonly lastCause: ExpectationCause | null;
+    readonly description?: string;
+}
+
+/** Whether an expectation currently HOLDS. `unknown` = not yet seeded, or a
+ *  metric that is undefined over the current data (e.g. freshness of an empty
+ *  table — neither fresh nor stale). Transitions are emitted only into/out of
+ *  `violated`. */
+export declare type ExpectationStatus = 'holding' | 'violated' | 'unknown';
+
+/** Emitted when an expectation crosses the holding/violated boundary. */
+export declare interface ExpectationTransition {
+    readonly kind: 'violated' | 'recovered';
+    readonly state: ExpectationState;
+    /** The causing write (present for a write-driven violation; `null` for a
+     *  clock-driven one or a recovery). */
+    readonly cause: ExpectationCause | null;
+}
+
+/** What caused a live recompute — resolved from the CDC `ChangeEvent`. `null`
+ *  for a non-write recompute (a reconcile re-seed). */
+export declare interface ExperimentCause {
+    readonly table: string;
+    readonly op: 'insert' | 'update' | 'delete';
+    /** The trace the write ran under — joins to `voltro logs --trace`. */
+    readonly traceId?: string | null;
+    /** The acting identity behind the write. */
+    readonly subjectId?: string | null;
+    /** The rpc tag of the call that made the write, when carried. */
+    readonly procedure?: string | null;
+}
+
+export declare interface ExperimentDefinition {
+    /** Brand marker — lets the cli discriminate default-exported experiment
+     *  definitions from arbitrary objects during file discovery. */
+    readonly _voltroExperiment: true;
+    readonly name: string;
+    readonly on: {
+        readonly table: string;
+        readonly where?: (row: Readonly<Record<string, unknown>>) => boolean;
+    };
+    /** Resolved to a function: reads the subject and normalises it to a non-empty
+     *  string, or `null` when the row carries no subject. */
+    readonly subject: (row: Readonly<Record<string, unknown>>) => string | null;
+    readonly variants: ReadonlyArray<ExperimentVariant>;
+    /** Resolved holdout fraction in [0, 1); `0` when none. */
+    readonly holdout: number;
+    readonly metric: ExperimentMetric;
+    readonly baseline: string;
+    readonly description?: string;
+}
+
+export declare interface ExperimentDefinitionInput {
+    /** Stable id within the app. Unique across all experiments. Also the
+     *  assignment SALT, so the same subject buckets independently per experiment. */
+    readonly name: string;
+    /** The watched table. Its CDC deltas drive the live recompute. An optional
+     *  `where` narrows the population the experiment observes — a pure predicate
+     *  evaluated server-side per row (rows failing it are excluded). It never
+     *  leaves the server, so it can be any predicate. */
+    readonly on: {
+        readonly table: string;
+        readonly where?: (row: Readonly<Record<string, unknown>>) => boolean;
+    };
+    /** The stable assignment key extractor. */
+    readonly subject: ExperimentSubject;
+    /** The arms. At least two (a control + one treatment). */
+    readonly variants: ReadonlyArray<ExperimentVariantSpec>;
+    /** Fraction (0..1) of subjects held out ENTIRELY — assigned to the reserved
+     *  `holdout` variant and never to a treatment. Omitted ⇒ no holdout. */
+    readonly holdout?: number;
+    /** The success metric maintained per variant. */
+    readonly metric: ExperimentMetric;
+    /** Which variant lift/difference is computed AGAINST. Must name one of
+     *  `variants`. Default: the first variant (by convention the control). */
+    readonly baseline?: string;
+    /** Human-facing note surfaced in devtools / the results view. */
+    readonly description?: string;
+}
+
+/**
+ * Evaluates ONE experiment. Seed once from the base rows, then feed CDC deltas
+ * via `applyChange`; each call re-maintains the per-variant metric + exposure and
+ * recomputes the live result. Returns an `ExperimentUpdate` for any relevant
+ * write (one whose old OR new image is assigned), else `null`.
+ */
+export declare class ExperimentEvaluator {
+    private readonly def;
+    private readonly deps;
+    private readonly exposure;
+    private readonly metric;
+    private readonly metricIsCount;
+    private readonly now;
+    private seeded;
+    private lastUpdatedAt;
+    constructor(def: ExperimentDefinition, deps: ExperimentEvaluatorDeps);
+    /** The variant an in-scope row is assigned to, or `null` when the row is out
+     *  of the `where` population or carries no subject. */
+    private variantOf;
+    private inScope;
+    /** Seed both maintainers from the current base rows. Never emits (there is no
+     *  prior result to compare). */
+    seed(): Promise<void>;
+    /**
+     * Apply one CDC change and recompute. Returns an update when the change was
+     * relevant (assigned on either image), else `null`. A change to a row that is
+     * out of scope on BOTH images is ignored.
+     */
+    applyChange(event: ChangeEvent): ExperimentUpdate | null;
+    /** The live result — per-variant metric + lift/diff vs the baseline. */
+    result(): ExperimentResult;
+    /** Resolve one variant's metric value, filling the "no group yet" gap: `count`
+     *  → 0, `sum` → 0 (empty sum), `avg` / `conversionRate` → `null` (undefined
+     *  over no samples). */
+    private metricValueFor;
+    get isSeeded(): boolean;
+}
+
+export declare interface ExperimentEvaluatorDeps {
+    /** Read the full current base rows — used to SEED and to reconcile. */
+    readonly queryBase: () => Promise<ReadonlyArray<Row_6>>;
+    /** Wall clock. Injectable for deterministic tests. Default `Date.now`. */
+    readonly now?: () => number;
+    readonly log?: SyncLogger;
+}
+
+/** The success metric an experiment maintains PER VARIANT. Every kind reduces to
+ *  a bounded IVM aggregate grouped by the assigned variant, so it rides the same
+ *  incremental engine as `defineAggregate` (no batch re-scan):
+ *
+ *   - `count`          — rows assigned to the variant. The metric IS the
+ *                        exposure (sample size).
+ *   - `sum`            — Σ of a numeric `column` over the variant's rows.
+ *   - `avg`            — mean of a numeric `column` — the per-observation
+ *                        average (revenue-per-order, latency, …). Comparable
+ *                        across variants of unequal size.
+ *   - `conversionRate` — the FRACTION of the variant's rows that "converted":
+ *                        `row[column]` is truthy, or `=== equals` when given.
+ *                        Modelled as `avg` of a 0/1 projection, so it too is a
+ *                        live IVM aggregate. The classic A/B success metric.
+ *
+ *  `count` / `sum` reflect BOTH exposure and effect, so their cross-variant
+ *  comparison only means "more/less total"; `avg` / `conversionRate` are
+ *  per-subject rates and are the ones a lift reads honestly. The result always
+ *  carries each variant's `exposure`, so an unequal split is visible either way. */
+export declare type ExperimentMetric = {
+    readonly kind: 'count';
+} | {
+    readonly kind: 'sum';
+    readonly column: string;
+} | {
+    readonly kind: 'avg';
+    readonly column: string;
+} | {
+    readonly kind: 'conversionRate';
+    readonly column: string;
+    /** When set, a row converted iff `row[column] === equals`. Omitted ⇒
+     *  converted iff `row[column]` is truthy. */
+    readonly equals?: unknown;
+};
+
+export declare type ExperimentMetricKind = ExperimentMetric['kind'];
+
+/**
+ * Framework-provided registry of every experiment the cli discovered + the
+ * evaluator maintains. Handler / inspect code reads the live results here,
+ * exactly as it reads `ExpectationRegistry` / `CostRegistry`.
+ */
+export declare class ExperimentRegistry extends ExperimentRegistry_base {
+}
+
+declare const ExperimentRegistry_base: Context.TagClass<ExperimentRegistry, "@voltro/ExperimentRegistry", ExperimentRegistryApi>;
+
+export declare interface ExperimentRegistryApi {
+    /** Snapshot every registered experiment's current result — the inspect feed. */
+    readonly snapshot: () => ReadonlyArray<ExperimentResult>;
+    /** One experiment's result by name, or `null` when unknown. */
+    readonly get: (name: string) => ExperimentResult | null;
+    /** Subscribe to live result recomputes. Returns an unsubscribe fn. */
+    readonly subscribe: (listener: (u: ExperimentUpdate) => void) => () => void;
+}
+
+/** The live state of one experiment — the row an inspect endpoint / results
+ *  dashboard reads. Recomputed on every relevant write. */
+export declare interface ExperimentResult {
+    readonly name: string;
+    readonly table: string;
+    readonly metric: ExperimentMetricKind;
+    readonly baseline: string;
+    /** Rows assigned to ANY variant (Σ exposure). */
+    readonly totalExposure: number;
+    readonly variants: ReadonlyArray<ExperimentVariantResult>;
+    /** When the result was last recomputed (a relevant write arrived). */
+    readonly lastUpdatedAt: Date | null;
+    readonly description?: string;
+}
+
+export declare interface ExperimentRunnerHandle {
+    readonly registry: ExperimentRegistryApi;
+    readonly detach: () => void;
+    readonly registered: ReadonlyArray<string>;
+}
+
+/** How the assignment key is read from a row. A column NAME (its value is the
+ *  subject) or a function returning the subject (a composite key, a tenant id,
+ *  a hashed cookie). Returning `null` / `undefined` / an empty value ⇒ the row
+ *  is UNASSIGNED and excluded from every variant. */
+export declare type ExperimentSubject = string | ((row: Readonly<Record<string, unknown>>) => string | number | null | undefined);
+
+/** Emitted whenever an experiment's result recomputes on a relevant write. The
+ *  results view subscribes to this to update in real time. */
+export declare interface ExperimentUpdate {
+    readonly result: ExperimentResult;
+    readonly cause: ExperimentCause | null;
+}
+
+/** Resolved variant — weight defaulted. */
+export declare interface ExperimentVariant {
+    readonly name: string;
+    readonly weight: number;
+}
+
+/** One variant's live result within an experiment. */
+export declare interface ExperimentVariantResult {
+    readonly variant: string;
+    /** True for the variant lift/diff is measured against. */
+    readonly isBaseline: boolean;
+    /** True for the reserved holdout arm. */
+    readonly isHoldout: boolean;
+    /** Sample size — rows assigned to this variant (the exposure). */
+    readonly exposure: number;
+    /** The maintained metric value. `null` when the metric is undefined over the
+     *  variant's current data (no valid samples for an avg / rate). */
+    readonly metric: number | null;
+    /** Relative lift vs the baseline: `(metric − baseMetric) / baseMetric`. `null`
+     *  when either value is null or the baseline metric is 0 (undefined lift).
+     *  Always `null` on the baseline row itself. */
+    readonly lift: number | null;
+    /** Absolute difference vs the baseline: `metric − baseMetric`. `null` when
+     *  either value is null. Always `null` on the baseline row. */
+    readonly diff: number | null;
+}
+
+/** A named arm of the experiment. `weight` skews the split (default 1 = equal);
+ *  a subject is assigned in proportion to its weight over the total. */
+export declare interface ExperimentVariantSpec {
+    readonly name: string;
+    readonly weight?: number;
+}
+
 /** Build an Effect `ExternalSpan` parent from a `traceparent` header so
  *  inbound HTTP work continues the caller's trace. Returns undefined
  *  when the header is missing/invalid (no parent → a fresh root span). */
@@ -2800,6 +3688,20 @@ export declare interface FieldChange {
  */
 export declare const fingerprintFor: (table: string, predicate: Predicate, indexHint?: string) => string;
 
+export declare interface FinopsRunnerHandle {
+    readonly registry: CostRegistryApi;
+    /** The ingestion entry point compute sites call to attribute one unit of
+     *  cost. Emits any budget-crossing signals to the registry's subscribers. */
+    readonly record: (event: CostEvent) => void;
+    /** Reset attribution + budgets for one tenant (or all). */
+    readonly reset: (tenantId?: string | null) => void;
+    readonly detach: () => void;
+    readonly registered: ReadonlyArray<string>;
+    /** Test/debug seam: run one clock re-check of the windowed budgets. This is
+     *  what the periodic tick timer calls. */
+    readonly runTick: () => void;
+}
+
 export declare interface FluentStore extends Omit<MutationStore, 'update' | 'delete' | 'query'> {
     /**
      * Diff-based many-to-many link writer for a junction table. `anchor` names the
@@ -2828,7 +3730,7 @@ export declare interface FluentStore extends Omit<MutationStore, 'update' | 'del
      * SPI every dialect store implements, and it genuinely does return untyped
      * rows off the wire. The type is re-applied here, at the handler boundary.
      */
-    query<R = Row_5>(descriptor: QueryDescriptor<R>): Promise<ReadonlyArray<R>>;
+    query<R = Row_7>(descriptor: QueryDescriptor<R>): Promise<ReadonlyArray<R>>;
     /**
      * Terminal: EXACTLY one row, TYPED. Fails with `NoRowFound` on zero matches
      * and equally on two or more.
@@ -2849,18 +3751,18 @@ export declare interface FluentStore extends Omit<MutationStore, 'update' | 'del
      * IS `query()` underneath — the probe just asks for one row more than it
      * needs so "the first of several" cannot masquerade as "the one you meant".
      */
-    one<R = Row_5>(query: QueryLike<R>): Promise<R>;
+    one<R = Row_7>(query: QueryLike<R>): Promise<R>;
     /** Terminal: the first matching row or `null`, TYPED. Use when "any match" is
      *  genuinely what you mean. */
-    first<R = Row_5>(query: QueryLike<R>): Promise<R | null>;
+    first<R = Row_7>(query: QueryLike<R>): Promise<R | null>;
     /** Alias of `first` — the first matching row or `null`, TYPED. */
-    maybeOne<R = Row_5>(query: QueryLike<R>): Promise<R | null>;
+    maybeOne<R = Row_7>(query: QueryLike<R>): Promise<R | null>;
     /** Fluent, scope-applying read builder: `select('notes').where(...).all()`. */
     select(table: string): SelectBuilder;
     /** Fluent predicate update: `update('notes').where('id', id).set({...})`. */
     update(table: string): UpdateBuilder;
     /** Keyed update by primary key — returns the post-image. */
-    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row_5 | null>;
+    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row_7 | null>;
     /** Fluent predicate delete: `delete('notes').where('id', id).soft()`. */
     delete(table: string): DeleteBuilder;
     /** Keyed delete by primary key. */
@@ -2885,6 +3787,31 @@ export declare interface FluentStoreBackend {
     readonly delete: DataStore['delete'];
 }
 
+/**
+ * The columns a given SUBJECT may not see on the wire for `tableName`: the
+ * union of the table's `.serverOnly()` columns (hidden from EVERYONE, so
+ * subject-independent) and its `.readableBy(...)` columns whose scope set the
+ * subject does NOT intersect (Part B — field-level read permissions).
+ *
+ * A subject sees a `.readableBy(...)` column iff it holds AT LEAST ONE of the
+ * declared scopes, checked against its EFFECTIVE scope set (raw subject scopes ∪
+ * rbac role-derived scopes) via `hasEffectiveScope` — so `admin:full` sees every
+ * such column, exactly as it satisfies every guard.
+ *
+ * SUBJECT-INDEPENDENCE is deliberate and load-bearing: when the table declares
+ * NO `.readableBy(...)` column, this returns exactly `serverOnlyColumnNames` —
+ * the same set for every subject — so the Dispatcher's per-subscriber strip
+ * collapses to Part A's behaviour and its read/diff memo still shares one array
+ * across all subscribers of a change. Only a table that actually carries a
+ * `.readableBy(...)` column pays the per-subject cost (different subjects get
+ * different stripped arrays, the same accepted cost `.serverOnly()` already has
+ * whenever it strips anything).
+ *
+ * An unknown / unregistered table forbids nothing (returns `[]`) rather than
+ * throwing — same posture as `serverOnlyColumnNames`.
+ */
+export declare const forbiddenColumnsForSubject: (tableName: string, subject: Subject) => ReadonlyArray<string>;
+
 /** Forget the calling subject's credential. Returns whether a row was removed. */
 export declare const forgetCredential: (store: VaultStore, connectionId: string, subjectId: string) => Promise<boolean>;
 
@@ -2988,6 +3915,14 @@ export declare interface GroupState {
 /** What a user handler may return. */
 export declare type HandlerBody = void | Promise<unknown> | Effect.Effect<unknown, unknown, never>;
 
+/**
+ * Deterministic hash of a string into the unit interval `[0, 1)` — FNV-1a
+ * (32-bit), no `node:crypto`, so it runs identically on server and client. The
+ * distribution is uniform enough for balanced bucketing; it is NOT a
+ * cryptographic hash and is not meant to be one (an assignment is not a secret).
+ */
+export declare const hashUnitInterval: (s: string) => number;
+
 /** Define a histogram. `boundaries` default to the framework duration buckets. */
 export declare const histogramMetric: (name: string, boundaries?: MetricBoundaries.MetricBoundaries, description?: string) => Metric.Metric.Histogram<number>;
 
@@ -2998,6 +3933,12 @@ export declare const histogramMetric: (name: string, boundaries?: MetricBoundari
  */
 export declare const historyProvenance: (history: ReadonlyArray<RowHistoryEntry>, key: ProvenanceKey) => ProvenanceResult;
 
+/** The reserved variant name a `holdout` fraction is assigned to. A holdout is
+ *  carved off the TOP of the unit interval BEFORE the weighted split, so it is
+ *  never influenced by adding/removing a treatment. No user variant may take
+ *  this name when `holdout > 0`. */
+export declare const HOLDOUT_VARIANT = "holdout";
+
 /** A secrets backend over a plain JSON HTTP API — no SDK. Wraps fetch + cache.
  *  Vault (`/v1/secret/data/...`), Doppler, and the cloud control-plane all fit. */
 export declare const httpSecretsBackend: (opts: HttpSecretsOptions) => SecretsBackend;
@@ -3283,8 +4224,14 @@ export declare const invertChange: (c: ForwardChange) => InverseOp | null;
 
 export declare const isAggregateDefinition: (value: unknown) => value is AggregateDefinition;
 
+export declare const isCostBudgetDefinition: (value: unknown) => value is CostBudgetDefinition;
+
 export declare const isEmptyTenantScopedRead: (descriptor: QueryDescriptor, tenantScopedTables: ReadonlySet<string>, tenantId: string | null | undefined) => boolean;
 
+export declare const isExpectationDefinition: (value: unknown) => value is ExpectationDefinition;
+
+export declare const isExperimentDefinition: (value: unknown) => value is ExperimentDefinition;
+
 /** Foreign-key-violation SQLSTATE / errno across dialects (pg 23503, mysql/maria
  *  1452, mssql 547, sqlite). Used to turn an opaque tenant-FK SqlError into a
  *  typed error. */
@@ -3828,6 +4775,18 @@ export declare const makeQuerySubscriber: <D>(deps: QuerySubscriberDeps<D>) => (
 
 export declare const makeRouterActivity: () => RouterActivity;
 
+/**
+ * Wrap a transactional store so single-row writes on USER tables are recorded
+ * as their POST-WRITE row. Inserts and updates are captured; a delete removes
+ * the row (there is no post-write state to validate), so — like undo's bulk
+ * boundary — deletes are NOT re-validated in v1. Everything else delegates
+ * untouched. Multiple writes to the same (table, id) keep the latest row.
+ */
+export declare const makeRuleCapture: (tx: unknown) => {
+    readonly tx: unknown;
+    drain(): ReadonlyArray<TouchedRow>;
+};
+
 /**
  * Build the registry from a list of table descriptors. Cheap — runs once
  * at boot. The returned object is read-only.
@@ -4093,6 +5052,11 @@ export declare interface MutationLike {
         readonly name: string;
         readonly source?: string | ReadonlyArray<string> | undefined;
         readonly guards?: ReadonlyArray<AnyCheckSpec> | undefined;
+        readonly target?: {
+            readonly table: string;
+        } | ReadonlyArray<{
+            readonly table: string;
+        }> | undefined;
     };
     executor(input: unknown, ctx: unknown): unknown;
 }
@@ -4347,9 +5311,13 @@ export declare interface OneShotQueryRunnerDeps<D> extends QueryProducerDeps<D>
     /**
      * Execute a FINALIZED (tenant-scoped) descriptor → rows. On the WS path the
      * dispatcher owns this step; a ONE-SHOT read (a `publicApi` REST GET, where
-     * there is no subscription to drive) needs it inline.
+     * there is no subscription to drive) needs it inline. The resolved request
+     * `context` is handed alongside so the caller can apply the SAME
+     * subject-aware wire-column strip the dispatcher does (`.serverOnly()` ∪ the
+     * `.readableBy(...)` columns this subject lacks) — the parity that keeps the
+     * REST projection from shipping a column the socket path would strip.
      */
-    readonly queryRows: (descriptor: D) => Promise<ReadonlyArray<unknown>>;
+    readonly queryRows: (descriptor: D, context: ServeRequestContext) => Promise<ReadonlyArray<unknown>>;
 }
 
 /**
@@ -4606,7 +5574,7 @@ export declare interface PreviewStore {
 /** Project a stored row into the wire shape. Deliberately total over the
  *  columns the descriptor declares — and deliberately silent about the token
  *  columns, which have no wire representation at all. */
-export declare const projectConnectionState: (definition: ConnectionDefinition, row: AnyRow | undefined) => ConnectionState;
+export declare const projectConnectionState: (definition: ConnectionDefinition, row: AnyRow_2 | undefined) => ConnectionState;
 
 /** Exact-match property filter. Values are AND'd. */
 export declare type PropertyFilter = Readonly<Record<string, string | number | boolean | null>>;
@@ -4746,7 +5714,7 @@ export declare interface QueryFinalizeOptions {
 
 /** A typed builder or its descriptor — the single-row terminals accept either,
  *  so a call site never has to reach for `.descriptor` just to use them. */
-export declare type QueryLike<R = Row_5> = QueryDescriptor<R> | {
+export declare type QueryLike<R = Row_7> = QueryDescriptor<R> | {
     readonly descriptor: QueryDescriptor<R>;
 };
 
@@ -4778,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 {
@@ -4804,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;
     };
 }
 
@@ -4815,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;
@@ -4836,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;
 }
@@ -5124,6 +6155,8 @@ export declare interface RegistryTableLike {
             readonly expr: string;
             readonly stored: boolean;
         };
+        /** `crdtText()` column — server-merged on write (see crdtColumns above). */
+        readonly crdtManaged?: boolean;
     }>;
     readonly appliedMixins?: ReadonlyArray<{
         readonly id?: string;
@@ -5546,6 +6579,9 @@ export declare interface ResourcePolicy {
     readonly implies?: Readonly<Record<string, ReadonlyArray<string>>>;
 }
 
+/** The full ordered list of result variants for a definition, holdout last. */
+export declare const resultVariantNames: (def: ExperimentDefinition) => ReadonlyArray<string>;
+
 export { RetentionSpec }
 
 export { retentionTtlMsFromEnv }
@@ -5605,6 +6641,10 @@ declare type Row_4 = Readonly<Record<string, unknown>>;
 
 declare type Row_5 = Readonly<Record<string, unknown>>;
 
+declare type Row_6 = Readonly<Record<string, unknown>>;
+
+declare type Row_7 = Readonly<Record<string, unknown>>;
+
 export declare interface RowDiff {
     readonly table: string;
     readonly op: 'insert' | 'update' | 'delete';
@@ -6273,6 +7313,12 @@ export declare interface SchemaInfo {
      * them and the dialect rejects an explicit value.
      */
     readonly generatedColumns: ReadonlySet<string>;
+    /**
+     * CRDT-managed columns (`crdtText()`). The MutationStore folds an incoming
+     * encoded update into the stored state (`mergeCrdtStates`) before the write,
+     * so concurrent clients converge. Empty set for the common non-CRDT table.
+     */
+    readonly crdtColumns: ReadonlySet<string>;
     /**
      * Columns that a query predicate can hit and benefit from an index:
      *   - column-level `.index()`-flagged columns
@@ -6321,6 +7367,10 @@ export declare interface SchemaRegistry {
      *  optional half. */
     hasExpires(table: string): boolean;
     hasTenant(table: string): boolean;
+    /** True when the table carries `localFirst()` — it is mirrored to the client,
+     *  synced bi-directionally, and its `crdtText()` fields converge via CRDT
+     *  merge. The discovery signal for the client-sync-set builder. */
+    hasLocalFirst(table: string): boolean;
     /** Field-existence check — used to skip stamping a column that the
      *  table doesn't actually declare (extra defensive). */
     hasField(table: string, field: string): boolean;
@@ -6362,6 +7412,12 @@ export declare interface SchemaRegistry {
      * Postgres reject an explicit value.
      */
     generatedColumns(table: string): ReadonlySet<string>;
+    /**
+     * CRDT-managed columns (`crdtText()`) for a table. Empty set if none.
+     * Read by the MutationStore write path to run the authoritative server-side
+     * CRDT merge (`mergeCrdtStates`) before an INSERT/UPDATE persists.
+     */
+    crdtColumns(table: string): ReadonlySet<string>;
     /**
      * Optional pre-INSERT schema decoder for a table. `undefined` when
      * the table didn't ship `.validate(schema)`. The MutationStore runs
@@ -6468,6 +7524,13 @@ export declare interface ServeRequestContext {
     readonly rowFilter?: RowFilterScope;
 }
 
+/**
+ * The `.serverOnly()` column names of a table by NAME, or `[]` when the table is
+ * not registered (a computed query, a raw-SQL descriptor, an unknown source) —
+ * an unknown table strips nothing rather than throwing.
+ */
+export declare const serverOnlyColumnNames: (tableName: string) => ReadonlyArray<string>;
+
 /** One leak: a wire query that declares a serverOnly column in its output. */
 export declare interface ServerOnlyLeak {
     readonly query: string;
@@ -6490,6 +7553,18 @@ export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown,
     readonly subject: unknown;
     readonly traceId: string;
     readonly spanId?: string;
+    /**
+     * The declared write-target TABLE names of this mutation/action, derived
+     * from the descriptor's `target:` block. Absent when the descriptor
+     * declares no target (and always absent for queries).
+     *
+     * Carried so an interceptor — the audit sink is the motivating consumer —
+     * can see WHICH tables an operation writes without reaching for the
+     * descriptor registry. Purely additive: an interceptor that ignores it is
+     * unaffected. It is the descriptor's DECLARED target, not the rows actually
+     * written; a change-set carry (the rows/ids) is a separate, heavier seam.
+     */
+    readonly target?: ReadonlyArray<string>;
 }) => Effect.Effect<unknown, unknown, never>;
 
 /** Register the process-wide connection resolver (or clear with `undefined`).
@@ -6780,6 +7855,45 @@ declare const StoreOperationFailed_base: Schema.TaggedErrorClass<StoreOperationF
     cause: typeof Schema.String;
 }>;
 
+/**
+ * Drop `columns` from every row. Preserves array AND per-row object identity when
+ * nothing is actually removed: an empty column set returns the input array
+ * unchanged, and a row that carries none of the columns is returned as-is. That
+ * identity preservation is load-bearing for the dispatcher's diff memo, which
+ * keys on `prev` object identity — a gratuitous clone would defeat it.
+ */
+export declare const stripColumnsFromRows: <R extends Row>(rows: ReadonlyArray<R>, columns: ReadonlyArray<string>) => ReadonlyArray<R>;
+
+/**
+ * Strip a source table's columns this SUBJECT may not see — `.serverOnly()` ∪
+ * the `.readableBy(...)` columns the subject lacks a scope for — from a row set
+ * produced for the wire. The subject-aware counterpart of
+ * {@link stripServerOnlyForWire}; the two share the same value-level
+ * {@link stripColumnsFromRows} pass (and its array/row identity preservation),
+ * so a table with no `.serverOnly()` and no `.readableBy(...)` column returns the
+ * input array unchanged for every subject.
+ *
+ * Same ACCEPTED GAP as `stripServerOnlyForWire`: only TOP-LEVEL columns of
+ * `tableName` are matched — an eager-loaded relation or a renamed projection
+ * changes the shape and is not covered here.
+ */
+export declare const stripForbiddenForWire: <R extends Row>(tableName: string, rows: ReadonlyArray<R>, subject: Subject) => ReadonlyArray<R>;
+
+/**
+ * Strip a source table's `.serverOnly()` columns from a row set produced for the
+ * wire. The runtime half of the exposure policy: declare `.serverOnly()` ONCE at
+ * the schema and every query/subscription output respects it, regardless of
+ * whether the handler was hand-written or a `crud.*` helper.
+ *
+ * ACCEPTED GAP (documented): only TOP-LEVEL columns of `tableName` are matched.
+ * An eager-loaded relation nests another table's columns under a relation key,
+ * and a computed/renamed projection changes the shape — neither is covered here
+ * (mark the nested column `.serverOnly()` on ITS table and read it through a
+ * `crud.*`/redacted path, or omit it from the output schema so the boot audit
+ * blocks it). The marker + `crud.*` path covers the common flat-row case.
+ */
+export declare const stripServerOnlyForWire: <R extends Row>(tableName: string, rows: ReadonlyArray<R>) => ReadonlyArray<R>;
+
 export declare interface SubscribeContext {
     /** Logger scoped to the subscriber file (`subscribe:<filename>`). */
     readonly log: SyncLogger;
@@ -7037,6 +8151,22 @@ declare const TableValidationFailed_base: Schema.TaggedErrorClass<TableValidatio
     }>>;
 }>;
 
+/** The standing compute-cost attribution for one tenant — the chargeback /
+ *  showback row + the "why is my bill high" breakdown. Maintained incrementally:
+ *  every `CostEvent` folds into `total`, `byUnit`, and `bySubscription` in O(1).
+ *  Cumulative since boot (or since the last `reset(tenantId)`). */
+export declare interface TenantCostState {
+    readonly tenantId: string | null;
+    /** Grand total across every unit. */
+    readonly total: number;
+    /** Per-unit breakdown (`recompute` → n, `query` → n, …). */
+    readonly byUnit: Readonly<Record<string, number>>;
+    /** Per-subscription breakdown — the per-subscription attribution. Only
+     *  subscription-tagged events contribute. */
+    readonly bySubscription: Readonly<Record<string, number>>;
+    readonly lastUpdatedAt: number | null;
+}
+
 /**
  * A write was attempted against a `tenant()`-scoped table, but the
  * authenticated subject's `tenantId` is null — either anonymous, or
@@ -7138,6 +8268,14 @@ export declare interface TopNQuery {
     readonly tenantId?: string | null;
 }
 
+/** A row a mutation wrote, carried to rule evaluation. `row` is the POST-WRITE
+ *  state (insert result / update result). */
+declare interface TouchedRow {
+    readonly table: string;
+    readonly id: string;
+    readonly row: AnyRow;
+}
+
 export declare interface TraceContext {
     readonly traceId: string;
     readonly spanId: string;
@@ -7472,6 +8610,18 @@ export declare const useAggregate: <Row>(def: AggregateDefinition<Row>) => Effec
  */
 export declare const useAnalytics: () => Effect.Effect<AnalyticsSinkImpl, never, AnalyticsSink>;
 
+/** Sugar: read one budget's current state for a tenant from a handler. Returns
+ *  `null` when the budget name is not registered (none attached, or a typo). */
+export declare const useCostBudget: (def: CostBudgetDefinition, tenantId: string | null) => Effect.Effect<CostBudgetState | null, never, CostRegistry>;
+
+/** Sugar: read one expectation's current state from a handler. Returns `null`
+ *  when the name is not registered (no expectations attached, or a typo). */
+export declare const useExpectation: (def: ExpectationDefinition) => Effect.Effect<ExpectationState | null, never, ExpectationRegistry>;
+
+/** Sugar: read one experiment's current result from a handler. Returns `null`
+ *  when the name is not registered (none attached, or a typo). */
+export declare const useExperiment: (def: ExperimentDefinition) => Effect.Effect<ExperimentResult | null, never, ExperimentRegistry>;
+
 declare type VaultStore = Pick<DataStore, 'query' | 'insert' | 'update' | 'updateMany' | 'delete' | 'upsert'>;
 
 /** The pure core of live revocation: given a subject + action + a row-set,
@@ -7496,6 +8646,10 @@ export declare const VOLTRO_AUDIT_MIXIN_ID: "voltro/audit";
  *  consumer). Kept in step by `expiresMixinId.test.ts`. */
 export declare const VOLTRO_EXPIRES_MIXIN_ID: "voltro/expires";
 
+/** Re-declared here for the same reason as the ids above (no mixin import).
+ *  Kept in step by `localFirstMixinId.test.ts`. */
+export declare const VOLTRO_LOCAL_FIRST_MIXIN_ID: "voltro/localFirst";
+
 export declare const VOLTRO_SOFT_DELETE_MIXIN_ID: "voltro/softDelete";
 
 export declare const VOLTRO_TENANT_MIXIN_ID: "voltro/tenant";
@@ -7689,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;
@@ -7703,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;
@@ -7790,6 +8995,17 @@ 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>;
 }
 
 export declare interface WorkflowLayerExecutionContext {
@@ -7830,6 +9046,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
@@ -7861,6 +9091,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.
@@ -7967,6 +9215,14 @@ 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 */
@@ -7975,8 +9231,14 @@ export declare interface WorkflowStartOptions {
 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 {