@voltro/runtime 0.27.0 → 0.29.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.
@@ -957,7 +960,7 @@ export declare const applyInverses: (store: UndoApplyStore, ops: ReadonlyArray<I
  * finds nothing — an orphan rule firing on a row nobody references is the
  * normal case, not an error.
  */
-export declare const applyPluginRefRules: (store: PluginRefStore, rules: ReadonlyArray<PluginRefRule>, change: PluginRefChange) => Promise<ReadonlyArray<{
+export declare const applyPluginRefRules: (store: PluginRefStore, rules: ReadonlyArray<PluginRefRule>, change: ChangeEvent) => Promise<ReadonlyArray<{
     readonly rule: PluginRefRule;
     readonly affected: number;
 }>>;
@@ -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;
@@ -1770,6 +1860,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 +2295,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 +2359,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 +2395,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 +2506,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 +2658,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 +2807,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 +3198,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 +3665,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 +3707,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 +3728,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 +3764,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 +3892,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 +3910,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 +4201,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. */
@@ -3347,7 +4271,7 @@ export declare const isScheduleDefinition: (v: unknown) => v is BrandedScheduleD
  * The transition matters, not the value: a row that was already deleted and is
  * updated again must not re-fire the rule.
  */
-export declare const isSoftDelete: (change: PluginRefChange) => boolean;
+export declare const isSoftDelete: (change: ChangeEvent) => boolean;
 
 /** A freshly issued key — `token` is shown ONCE and never stored in clear. */
 export declare interface IssuedApiKey {
@@ -3782,6 +4706,10 @@ export declare const makeProcessAdapter: (supervisor: AppSupervisor) => WakeAdap
  */
 export declare const makeQueryDescriptorProducer: <D>(deps: QueryProducerDeps<D>) => (query: MutationLike, input: unknown) => (requestContext: ServeRequestContext) => D | ComputedQuery | Effect.Effect<D | ComputedQuery, unknown, never>;
 
+export declare const makeQueryFinalizer: (options: QueryFinalizeOptions) => ((descriptor: QueryDescriptor, subject: {
+    readonly tenantId?: string | null;
+}) => QueryDescriptor);
+
 /**
  * Build the per-subscription authorization re-check.
  *
@@ -3824,6 +4752,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.
@@ -4089,6 +5029,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;
 }
@@ -4343,9 +5288,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>>;
 }
 
 /**
@@ -4556,18 +5505,6 @@ export declare const payloadPropertyNames: (schema: Schema.Schema.Any) => {
     readonly optional: ReadonlyArray<string>;
 };
 
-/** A change as the post-commit channel reports it. */
-export declare interface PluginRefChange {
-    readonly table: string;
-    readonly op: 'insert' | 'update' | 'delete';
-    readonly rowId: string;
-    readonly tenantId?: string | null;
-    /** The row before, when there was one — used to spot a soft delete. */
-    readonly old?: Record<string, unknown> | null;
-    /** The row after, when there is one. */
-    readonly new?: Record<string, unknown> | null;
-}
-
 /** One resolved rule: "when <targetTable> loses a row, do <policy> to <table.column>". */
 export declare interface PluginRefRule {
     readonly table: string;
@@ -4614,7 +5551,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>>;
@@ -4715,9 +5652,46 @@ export declare const publishEvent: <Name extends string, Key extends Schema.Sche
     readonly deferred: boolean;
 }, EventPublishError>;
 
+/**
+ * The two scopes, composed once, for every path that finalises a descriptor.
+ *
+ * **The primitives above were extracted so there is "no second copy that could
+ * drift" — and then the COMPOSITION became the second copy.** `voltro dev`
+ * wrapped them in a local helper; `serveApi` inlined the same pair in the other
+ * spelling. They agreed, which is the dangerous state: nothing kept them
+ * agreeing, and adding a third scoping concern would have landed in whichever
+ * file the author had open.
+ *
+ * That is the shape this repo has shipped seven times and the one a
+ * source-reading parity guard cannot see — both paths supply something, both
+ * look right at their own call site, and they disagree about content. The fix is
+ * not detection. It is having one function, so the disagreement has nowhere to
+ * live.
+ *
+ * `observe` is where the paths are ALLOWED to differ: `voltro dev` warns about
+ * an org-less subject, an empty tenant scope and a non-indexed predicate, and
+ * production does not want any of that on the hot path. A hook that cannot
+ * change the descriptor keeps the difference to the part that is genuinely
+ * dev-only. It receives a COPY of the descriptor: a hook that could rewrite the
+ * query would let the two paths disagree again through the one seam built to
+ * stop them.
+ */
+export declare interface QueryFinalizeOptions {
+    readonly tenantScopedTables: ReadonlySet<string>;
+    readonly softDeleteScopedTables: ReadonlySet<string>;
+    readonly observe?: {
+        /** Before scoping — sees what the handler asked for. */
+        readonly beforeScope?: (descriptor: QueryDescriptor, subject: {
+            readonly tenantId?: string | null;
+        }) => void;
+        /** After scoping — sees what will actually run. */
+        readonly afterScope?: (descriptor: QueryDescriptor) => void;
+    };
+}
+
 /** 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>;
 };
 
@@ -5095,6 +6069,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;
@@ -5517,6 +6493,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 }
@@ -5576,6 +6555,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';
@@ -5771,7 +6754,7 @@ export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
  * Exported separately from the execution so the matching is testable without a
  * store: which rules fire is the part with the edge cases.
  */
-export declare const rulesFor: (rules: ReadonlyArray<PluginRefRule>, change: PluginRefChange) => ReadonlyArray<PluginRefRule>;
+export declare const rulesFor: (rules: ReadonlyArray<PluginRefRule>, change: ChangeEvent) => ReadonlyArray<PluginRefRule>;
 
 /**
  * Run `fn` with `SubjectService` bound to a `system` subject and a
@@ -6244,6 +7227,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
@@ -6292,6 +7281,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;
@@ -6333,6 +7326,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
@@ -6439,6 +7438,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;
@@ -6461,6 +7467,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`).
@@ -6751,6 +7769,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;
@@ -7008,6 +8065,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
@@ -7109,6 +8182,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;
@@ -7443,6 +8524,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,
@@ -7467,6 +8560,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";