@voltro/runtime 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -1,9 +1,14 @@
+import { AnyApprovalPolicy } from '@voltro/protocol';
 import { AnyCheckSpec } from '@voltro/protocol';
+import { AnyGuardSpec } from '@voltro/protocol';
+import { AuthMiddleware } from '@voltro/protocol';
 import { AuthStrategy } from '@voltro/protocol';
 import { CaughtUpVerdict } from '@voltro/database';
 import { ChangeEvent } from '@voltro/database';
 import { clearRetentions } from '@voltro/database';
+import { ConnectionCredential } from '@voltro/protocol';
 import { ConnectionInfo } from '@voltro/protocol';
+import { ConnectionInfoMiddleware } from '@voltro/protocol';
 import { ConnectionKind } from '@voltro/protocol';
 import { ConnectionState } from '@voltro/protocol';
 import { Context } from 'effect';
@@ -38,10 +43,12 @@ import { inspectWorkflow } from '@voltro/workflow';
 import { Kv } from '@voltro/kv';
 import { KvStoreShape } from '@voltro/kv';
 import { Layer } from 'effect';
+import { listRetentionConflicts } from '@voltro/database';
 import { listRetentions } from '@voltro/database';
 import { Metric } from 'effect';
 import { MetricBoundaries } from 'effect';
 import { MetricReader } from '@opentelemetry/sdk-metrics';
+import { PendingApproval } from '@voltro/protocol';
 import { PluginHttpRoute } from '@voltro/protocol';
 import { PluginRefOrphanPolicy } from '@voltro/database';
 import { Predicate } from '@voltro/database';
@@ -50,6 +57,8 @@ import { QueryDescriptor } from '@voltro/database';
 import { Redis } from 'ioredis';
 import { registerRetention } from '@voltro/database';
 import { RestRouteDescriptor } from '@voltro/protocol/rest';
+import { RetentionConflict } from '@voltro/database';
+import { RetentionSource } from '@voltro/database';
 import { RetentionSpec } from '@voltro/database';
 import { retentionTtlMsFromEnv } from '@voltro/database';
 import { Row } from '@voltro/database';
@@ -66,6 +75,7 @@ import { spawn } from 'node:child_process';
 import { SqlClient } from '@effect/sql';
 import { Stream } from 'effect';
 import { Subject } from '@voltro/protocol';
+import { SubjectResolution } from '@voltro/protocol';
 import { SubjectService } from '@voltro/protocol';
 import { SubscriptionEvent } from '@voltro/protocol';
 import { sweepRetention } from '@voltro/database';
@@ -527,26 +537,24 @@ export declare type AnalyticsMetric = 'count' | 'unique' | {
     readonly avg: string;
 };
 
-/**
- * A single reactive-table change to mirror into the warehouse. Mirrors
- * the framework's internal `ChangeEvent` but flattened to the shape a
- * sink needs: the table name, the operation, and the row. For `insert`
- * / `update` the post-image is in `row`; for `delete` the pre-image is
- * in `row` (so the sink knows which primary key to remove).
- */
-export declare interface AnalyticsMirrorChange {
-    readonly table: string;
-    readonly op: 'insert' | 'update' | 'delete';
-    /** Post-image for insert/update; pre-image for delete. */
-    readonly row: Readonly<Record<string, unknown>>;
-}
-
 export declare interface AnalyticsMirrorHandle {
     /** Tables actually being mirrored (the sink's `mirror.tables`). Empty
      *  when the sink declares no mirror. */
     readonly tables: ReadonlyArray<string>;
-    /** Detach the `onChange` subscription. */
+    /** Detach the `onChange` subscription and stop the repair loop. */
     readonly detach: () => void;
+    /** Settle every queued + in-flight write. Resolves when the mirror has
+     *  nothing left to apply (or has queued it for repair). */
+    readonly flush: () => Promise<void>;
+    /**
+     * Re-drive every key awaiting repair: re-read its CURRENT row from the
+     * store and re-apply it (upsert when present, remove when gone) under
+     * a fresh version. Runs on the `repairIntervalMs` timer; exposed so an
+     * operator or a shutdown hook can force a pass. Resolves with the
+     * number of keys that landed.
+     */
+    readonly repair: () => Promise<number>;
+    readonly stats: () => AnalyticsMirrorStats;
 }
 
 /**
@@ -561,6 +569,13 @@ export declare interface AnalyticsMirrorHandle {
  * MUST be idempotent — the same change may be re-delivered after a
  * reconnect, and the upsert is keyed on `primaryKey` so re-applying a
  * row is a no-op-equivalent overwrite.
+ *
+ * Idempotent is not enough on its own: re-delivery can also arrive OUT
+ * OF ORDER, so both methods additionally receive a {@link MirrorVersion}
+ * and MUST ignore a write whose version is not greater than the version
+ * already stored for that key (ClickHouse gets this from
+ * `ReplacingMergeTree(version)`; DuckDB from an `ON CONFLICT … WHERE
+ * excluded.version > version` guard).
  */
 export declare interface AnalyticsMirrorImpl {
     /** Reactive tables this sink mirrors. The framework only forwards
@@ -569,10 +584,81 @@ export declare interface AnalyticsMirrorImpl {
     /** Primary-key column the sink upserts/deletes by. Defaults to `'id'`
      *  when omitted. */
     readonly primaryKey?: string;
-    /** Apply an insert/update. Idempotent upsert keyed on `primaryKey`. */
-    readonly upsert: (table: string, row: Readonly<Record<string, unknown>>) => Effect.Effect<void, AnalyticsFailure>;
-    /** Apply a delete. Idempotent — removing an absent key is a no-op. */
-    readonly remove: (table: string, primaryKeyValue: unknown) => Effect.Effect<void, AnalyticsFailure>;
+    /** Apply an insert/update. Idempotent upsert keyed on `primaryKey`,
+     *  version-guarded by `write.version`. */
+    readonly upsert: (write: AnalyticsMirrorUpsert) => Effect.Effect<void, AnalyticsFailure>;
+    /** Apply a delete. Idempotent — removing an absent key is a no-op —
+     *  and version-guarded by `write.version`. */
+    readonly remove: (write: AnalyticsMirrorRemove) => Effect.Effect<void, AnalyticsFailure>;
+}
+
+/** One delete to apply to the mirror. */
+export declare interface AnalyticsMirrorRemove {
+    readonly table: string;
+    /** Primary-key value of the removed row. */
+    readonly primaryKeyValue: unknown;
+    /** See {@link MirrorVersion}. A delete is ordered against upserts of
+     *  the same key by exactly this number. */
+    readonly version: MirrorVersion;
+}
+
+/** Counters a caller (boot log, inspect endpoint, test) can read. */
+export declare interface AnalyticsMirrorStats {
+    /** Writes the sink accepted. */
+    readonly forwarded: number;
+    /** Keys with a queued-but-not-yet-applied write. */
+    readonly pending: number;
+    /** Keys awaiting repair (retries exhausted). */
+    readonly awaitingRepair: number;
+    /** Changes provably lost — repair-queue overflow. */
+    readonly dropped: number;
+}
+
+/**
+ * Every number the mirror picks on the app's behalf, with its default.
+ * Each is also readable from the environment so an operator can tune a
+ * running deployment without a code change.
+ */
+export declare interface AnalyticsMirrorTunables {
+    /**
+     * Total attempts for one mirror write (1 = no retry).
+     * Default `5`. Env: `VOLTRO_ANALYTICS_MIRROR_RETRY_ATTEMPTS`.
+     */
+    readonly retryAttempts: number;
+    /**
+     * First backoff delay; doubles per attempt.
+     * Default `100`ms. Env: `VOLTRO_ANALYTICS_MIRROR_RETRY_BASE_MS`.
+     */
+    readonly retryBaseDelayMs: number;
+    /**
+     * Ceiling for the doubling backoff.
+     * Default `30_000`ms. Env: `VOLTRO_ANALYTICS_MIRROR_RETRY_MAX_MS`.
+     */
+    readonly retryMaxDelayMs: number;
+    /**
+     * How often the repair loop re-drives changes whose retries ran out.
+     * `0` disables the loop (the queue then only drains via an explicit
+     * `handle.repair()`).
+     * Default `60_000`ms. Env: `VOLTRO_ANALYTICS_MIRROR_REPAIR_INTERVAL_MS`.
+     */
+    readonly repairIntervalMs: number;
+    /**
+     * Maximum keys held for repair. Past this, the oldest queued key is
+     * dropped, counted and logged at error level — a bounded queue that
+     * says so beats an unbounded one that ends the process.
+     * Default `10_000`. Env: `VOLTRO_ANALYTICS_MIRROR_REPAIR_QUEUE_LIMIT`.
+     */
+    readonly repairQueueLimit: number;
+}
+
+/** One insert/update to apply to the mirror. */
+export declare interface AnalyticsMirrorUpsert {
+    readonly table: string;
+    /** Post-image of the changed row. */
+    readonly row: Readonly<Record<string, unknown>>;
+    /** See {@link MirrorVersion} — persist it, compare against it, never
+     *  replace it with a local clock reading. */
+    readonly version: MirrorVersion;
 }
 
 /**
@@ -680,6 +766,9 @@ declare type AnyRow = Record<string, unknown>;
 
 declare type AnyRow_2 = Record<string, unknown>;
 
+/** Locked-down policy for an API response. Nothing loads, nothing frames it. */
+export declare const API_CSP = "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
+
 export declare const API_KEYS_TABLE = "_voltro_api_keys";
 
 /** Admin-gated management routes (issue / list / revoke) for the built-in keys.
@@ -924,6 +1013,21 @@ export declare interface AppContext {
     readonly loadMany: DataLoader['loadMany'];
 }
 
+/**
+ * The connection's headers as the auth chain should see them: the transport's
+ * own headers with the bound credential patched over them.
+ *
+ * Returns the input UNCHANGED when nothing is bound — the overwhelmingly common
+ * case is a connection that never re-authenticated, and it must not pay for a
+ * clone.
+ *
+ * Header names are lowercased on the patched keys because the rest of the chain
+ * reads them lowercase (`headers['cookie']`, `headers['authorization']`), and a
+ * patch written as `Authorization` that lands beside an existing `authorization`
+ * is a credential that is present and invisible.
+ */
+export declare const applyConnectionCredential: (clientId: number, headers: Record<string, string | undefined>) => Record<string, string | undefined>;
+
 /**
  * Pure helper backing `ctx.store.applyDefined`. Picks the listed keys from
  * `input` whose value is not `undefined`, so a PATCH sets exactly the fields
@@ -987,6 +1091,72 @@ export declare const applyUndoInvocation: (input: {
     readonly ok: boolean;
 }>;
 
+/** What the dispatch spine hands the gate. */
+export declare interface ApprovalAdmissionInput {
+    readonly procedure: string;
+    readonly kind: 'mutation' | 'action';
+    readonly policy: AnyApprovalPolicy;
+    readonly subject: Subject | null;
+    readonly input: unknown;
+    readonly traceId?: string | undefined;
+    /** Distinguishes a deliberate repeat of an identical request. */
+    readonly nonce?: string | undefined;
+}
+
+/** The slice of AppContext the approval executors need. */
+export declare interface ApprovalExecutorCtx {
+    readonly store: DataStore;
+    readonly request?: {
+        readonly subject?: Subject | null;
+    } | undefined;
+}
+
+export declare interface ApprovalGateApi {
+    /**
+     * ADMIT or REFUSE one approval-requiring call.
+     *
+     * Resolves when the call may proceed (an approval was found and CONSUMED, so
+     * it cannot be spent twice). REJECTS with one of the typed approval errors
+     * otherwise — the caller re-throws it and the rpc layer matches it against the
+     * descriptor's `error:` union.
+     */
+    readonly admit: (input: ApprovalAdmissionInput) => Promise<void>;
+}
+
+/**
+ * The content-addressed identity of an intent.
+ *
+ * LENGTH-PREFIXED, not separator-joined, for the reason `promptVersionDigest`
+ * records: no printable separator is injective over arbitrary prose, and the
+ * repo's rule forbids the NUL that would be. A procedure named `a` with
+ * requester `b:c` must not digest the same as `a:b` with requester `c`.
+ */
+export declare const approvalIntentKey: (input: {
+    readonly procedure: string;
+    readonly requestedBy: string | null;
+    readonly tenantId: string | null;
+    readonly payload: string;
+    /** Distinguishes two DELIBERATELY identical requests. The caller states it;
+     *  the framework never invents one (that would defeat the whole idea). */
+    readonly nonce?: string | undefined;
+}) => string;
+
+/**
+ * Mint a nonce for a DELIBERATE repeat of an identical request.
+ *
+ * Exported for callers that genuinely need two identical intents in flight (the
+ * same refund, twice, on purpose). Never called by the framework: inventing one
+ * per attempt is exactly the too-fine identity the header rejects.
+ */
+export declare const approvalNonce: () => string;
+
+export declare const APPROVALS_TABLE = "_voltro_approvals";
+
+/** `__voltro.approvals.pending` — the calling subject's approval work. */
+export declare const approvalsPendingExecutor: (input: {
+    readonly limit?: number;
+}, ctx: ApprovalExecutorCtx) => Promise<ReadonlyArray<PendingApproval>>;
+
 /**
  * Controls the lifecycle of the app process the orchestrator fronts.
  * Both `start` and `stop` are idempotent so the orchestrator can call
@@ -1021,6 +1191,14 @@ export declare const assertCan: (subject: RebacSubject, action: string, resource
  */
 export declare const assertConnectionCipherConfigured: (definitions: ReadonlyArray<ConnectionDefinition>) => void;
 
+/**
+ * Boot gate: every mounted incoming-webhook route must carry a verification
+ * declaration. Throws `UnverifiedWebhookRoute` for the first that does not.
+ */
+export declare const assertWebhookRoutesDeclareVerification: (routes: ReadonlyMap<string, {
+    readonly handle: unknown;
+}> | undefined) => void;
+
 /**
  * Assign a subject to a variant — STABLE (same subject ⇒ same variant, always)
  * and BALANCED (proportions converge to the weights over many subjects). The
@@ -1092,12 +1270,10 @@ export declare interface AsyncKv {
  * Wire the sink's CDC-mirror to the store's change stream. No-op (and
  * returns an empty handle) when the sink declares no `mirror` — so the
  * caller can always call this unconditionally.
- *
- * Returns the set of mirrored tables (for boot logging) + a detach.
  */
 export declare const attachAnalyticsMirror: (options: AttachAnalyticsMirrorOptions) => AnalyticsMirrorHandle;
 
-export declare interface AttachAnalyticsMirrorOptions {
+export declare interface AttachAnalyticsMirrorOptions extends Partial<AnalyticsMirrorTunables> {
     readonly store: DataStore;
     readonly sink: AnalyticsSinkImpl;
     readonly log: SyncLogger;
@@ -1193,6 +1369,10 @@ export declare interface AuditableQuery {
     readonly source?: string | ReadonlyArray<string> | undefined;
 }
 
+export declare interface AuthMiddlewareLayerOptions {
+    readonly resolveSubject: ResolveSubjectFn;
+}
+
 /**
  * An Effect that is ALSO awaitable.
  *
@@ -1241,7 +1421,18 @@ export declare interface BeginOAuthResult {
     readonly state: string;
 }
 
-export declare const bindConnectionSubject: (clientId: number, subject: Subject) => void;
+/**
+ * Present a new credential on an ALREADY-OPEN connection.
+ *
+ * Called from a handler that has just authenticated the caller — `auth.signin`,
+ * a tenant switch — with the credential it minted (typically the session cookie
+ * it is about to `Set-Cookie`). Every subsequent call on this connection is
+ * resolved by the FULL auth chain against these headers, so the caller gets
+ * exactly what a reconnect would give them and nothing more.
+ *
+ * Idempotent; a second bind replaces the first.
+ */
+export declare const bindConnectionCredential: (clientId: number, credential: ConnectionCredential) => void;
 
 /**
  * Bind one client's subscription to a declared event.
@@ -1522,6 +1713,14 @@ export declare interface CandidateShape {
 }
 
 /* Excluded from this release type: canonicalize */
+
+/**
+ * Canonical JSON — object keys sorted recursively, so two structurally equal
+ * inputs that differ only in key order digest identically. A retry from a
+ * different client build must not mint a second approval.
+ */
+export declare const canonicalJson: (value: unknown) => string;
+
 export { CaughtUpVerdict }
 
 /** A CDC change event, structurally — what the reactive engine already emits
@@ -1632,6 +1831,17 @@ export declare const CLAIM_RETENTION_BUCKETS = 64;
  */
 export declare const claimGraceMs: (bucketWidthMs: number | undefined) => number;
 
+/**
+ * Decide whether a state-changing request may proceed.
+ *
+ * `headers` keys must already be lowercased (the rpc server lowercases once per
+ * request and passes the same bag to every guard).
+ */
+export declare const classifyRequestOrigin: (input: {
+    readonly headers: Readonly<Record<string, string>>;
+    readonly config: OriginGuardConfig;
+}) => OriginDecision;
+
 /**
  * Decide whether a candidate matches a maintainable shape. Conservative by
  * design — anything not provably maintainable is rejected (→ full recompute),
@@ -1639,6 +1849,9 @@ export declare const claimGraceMs: (bucketWidthMs: number | undefined) => number
  */
 export declare const classifyShape: (c: CandidateShape) => ShapeClassification;
 
+/** Test seam. */
+export declare const clearApprovalGate: () => void;
+
 /** Test seam — the in-flight map is module state; a test that asserts
  *  single-flight must be able to start from empty. */
 export declare const clearConnectionRefreshFlights: () => void;
@@ -1651,6 +1864,14 @@ export { clearRetentions }
 /** Clear the process-wide handle (test teardown). */
 export declare const clearSystemStoreHandle: () => void;
 
+export declare interface ClientAddressInput {
+    /** `socket.remoteAddress` — the only unforgeable value in the request. */
+    readonly socketAddress: string | undefined;
+    /** Raw `x-forwarded-for` header, if present. */
+    readonly xForwardedFor: string | undefined;
+    readonly config: TrustedProxyConfig;
+}
+
 /**
  * Collect the declared rules from the discovered tables.
  *
@@ -1867,13 +2088,6 @@ export declare interface ConnectionsFacadeDeps {
 /** Test-only — number of streams currently registered for a client. */
 export declare const _connectionStreamCount: (clientId: number) => number;
 
-/** Snapshot for diagnostics / dashboard. */
-export declare const connectionSubjectsSnapshot: () => ReadonlyArray<{
-    clientId: number;
-    subjectType: string;
-    tenantId: string | null;
-}>;
-
 /** A resolved token set. `expiresAt` is an absolute epoch-ms deadline. */
 export declare interface ConnectionTokens {
     readonly accessToken: string;
@@ -2049,6 +2263,8 @@ export declare interface CostBudgetDefinition {
     /** Resolved tumbling-window length in ms, or `null` for a cumulative budget. */
     readonly windowMs: number | null;
     readonly severity: CostBudgetSeverity;
+    /** Resolved breach behaviour — `'observe'` unless the app opted in. */
+    readonly onExceeded: CostBudgetOnExceeded;
     readonly description?: string;
 }
 
@@ -2073,14 +2289,50 @@ export declare interface CostBudgetDefinitionInput {
     readonly window?: string;
     /** Alerting priority carried on the breach signal. Default `'warn'`. */
     readonly severity?: CostBudgetSeverity;
+    /**
+     * What a breach DOES. Default `'observe'` — signal only, the behaviour this
+     * module shipped with.
+     *
+     * `'suspend'` opts the budget into stopping the next spend: a durable run
+     * reaching a pre-spend gate for this budget parks on a
+     * `_voltro_budget_holds` row and resumes when the budget recovers. Opt-in,
+     * because parking a run is a change in what the app DOES and a default that
+     * silently stalls work is worse than one that silently allows it.
+     */
+    readonly onExceeded?: CostBudgetOnExceeded;
     /** Human-facing note surfaced in devtools / the breach message. */
     readonly description?: string;
 }
 
+/**
+ * What a breach DOES, as opposed to how loudly it is reported.
+ *
+ * This file used to state flatly that "the framework never BLOCKS compute on a
+ * budget … an observability-grade signal over work that already happened", and
+ * that was accurate: a cost event arrives after its compute, so a budget here
+ * genuinely cannot refuse the work that produced it.
+ *
+ * What it can do — and now does — is stop the NEXT one. `'suspend'` marks the
+ * budget as one that parks durable runs: a run reaching a pre-spend gate for
+ * this budget SUSPENDS on a `_voltro_budget_holds` row (`@voltro/workflow`'s
+ * `suspendForBudget`) instead of proceeding. The suspension is therefore still
+ * not retroactive, and saying so is the honest version: it bounds future spend,
+ * and the work already metered is already paid for.
+ *
+ * This flag is a DECLARATION, not a wiring. Nothing here subscribes the
+ * accountant's `recovered` signal to `releaseBudgetHolds` — whether a recovered
+ * compute budget should wake a run held on a DIFFERENT (e.g. AI-USD) budget is
+ * an app decision, and a hold re-checks on its own durable clock regardless, so
+ * no run is stranded by the absence. An app that wants the immediate release
+ * subscribes: `registry.subscribe((s) => s.kind === 'recovered' && …)`.
+ *
+ * `'observe'` (default) keeps the previous behaviour exactly — signal only.
+ */
+export declare type CostBudgetOnExceeded = 'observe' | 'suspend';
+
 /** 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. */
+ *  alerting priority — orthogonal to {@link CostBudgetOnExceeded}, which decides
+ *  whether anything STOPS. */
 export declare type CostBudgetSeverity = 'info' | 'warn' | 'critical';
 
 /** Emitted when a budget crosses a threshold for a tenant. `warn` / `exceeded`
@@ -2107,6 +2359,9 @@ export declare interface CostBudgetState {
     readonly warnThreshold: number;
     /** The unit this budget meters, or `null` for a total-across-units budget. */
     readonly unit: string | null;
+    /** What a breach of this budget DOES — carried on the state so an operator
+     *  view can tell an observed breach from one that is holding runs. */
+    readonly onExceeded: CostBudgetOnExceeded;
     /** When the current window opened (windowed budgets), else `null`. */
     readonly windowStartedAt: number | null;
     /** When this budget last entered its current `status`. */
@@ -2222,10 +2477,14 @@ export declare const crud: {
         readonly id: string;
     }, ctx: AppContext) => Promise<Row | null>;
     /** Insert the input as a new row (id / tenant / audit auto-stamped). The echoed
-     *  row is redacted. Guard the DESCRIPTOR — this does not gate. */
+     *  row is redacted, and an input that sets a `.serverOnly()` column is REFUSED
+     *  with `ServerOnlyColumnWrite`. Guard the DESCRIPTOR — this does not gate. */
     create: (table: string, options?: CrudWriteOptions) => (input: Row, ctx: AppContext) => Promise<Row>;
     /** Patch a row by id (`{ id, ...patch }`); returns the updated row or `null`.
-     *  Redacted. Guard the DESCRIPTOR. */
+     *  Redacted, and a patch that sets a `.serverOnly()` column is REFUSED with
+     *  `ServerOnlyColumnWrite`. On a `tenant()` table the keyed write resolves the
+     *  row inside the caller's tenant (`TenantRowNotFound` otherwise — see
+     *  `storeMiddleware`). Guard the DESCRIPTOR. */
     update: (table: string, options?: CrudWriteOptions) => (input: {
         readonly id: string;
     } & Record<string, unknown>, ctx: AppContext) => Promise<Row | null>;
@@ -2362,6 +2621,9 @@ export declare interface CrudWriteOptions {
     readonly redact?: ReadonlyArray<string>;
 }
 
+/** Every raw read recorded in the current scope; empty outside one. */
+export declare const currentRawReads: () => ReadonlyArray<RawReadObservation>;
+
 /**
  * The current request's loader, or `undefined` outside a request.
  *
@@ -2404,6 +2666,37 @@ export declare const dataStoreIdempotencyStore: (store: DataStore) => Idempotenc
 /** Build a durable `KvStoreShape` over a raw `DataStore`. */
 export declare const dataStoreKvStore: (store: DataStore) => KvStoreShape;
 
+/**
+ * Approve or reject ONE intent, applying every refusal in a fixed order.
+ *
+ * The order is asserted in the tests and is not arbitrary: identity checks come
+ * before authority checks so a requester with the approver scope is told they
+ * cannot approve their OWN request (the accurate reason) rather than being
+ * silently allowed through on a scope they do hold.
+ */
+export declare const decideApproval: (store: DataStore, input: DecideApprovalInput) => Promise<{
+    readonly approvalId: string;
+    readonly status: "approved" | "rejected";
+}>;
+
+export declare interface DecideApprovalInput {
+    readonly approvalId: string;
+    readonly decision: 'approve' | 'reject';
+    readonly note?: string | undefined;
+    readonly approver: Subject | null;
+    readonly now?: () => number;
+}
+
+/** `__voltro.approvals.decide` — approve or reject one pending intent. */
+export declare const decideApprovalInvocation: (input: {
+    readonly approvalId: string;
+    readonly decision: "approve" | "reject";
+    readonly note?: string;
+}, ctx: ApprovalExecutorCtx) => Promise<{
+    readonly approvalId: string;
+    readonly status: "approved" | "rejected";
+}>;
+
 /** Decrypt a value produced by `encryptField` / an `.encrypted()` column. A
  *  value that is NOT ciphertext (`enc:v1:…`) is returned unchanged — so a
  *  raw-SQL read path can be switched to encryption while pre-existing plaintext
@@ -2411,10 +2704,35 @@ export declare const dataStoreKvStore: (store: DataStore) => KvStoreShape;
  *  cipher is registered (a genuine ciphertext with a wrong key throws GCM). */
 export declare const decryptField: (value: string) => string;
 
+export declare const DEFAULT_ANALYTICS_MIRROR_TUNABLES: AnalyticsMirrorTunables;
+
+/** Default life of a pending intent when neither the descriptor nor the app
+ *  says otherwise. 24 h: long enough to survive a weekend handoff being missed
+ *  by a few hours, short enough that a forgotten queue empties itself. */
+export declare const DEFAULT_APPROVAL_EXPIRY_MS: number;
+
 /** Assumed distance between buckets when a caller passes none — the cron
  *  engine's finest useful cadence. */
 export declare const DEFAULT_CLAIM_BUCKET_MS = 60000;
 
+/**
+ * How many subscribers one change event is delivered to CONCURRENTLY.
+ *
+ * 8 rather than 1 (fully serial, what this replaced) or unbounded. Serial makes
+ * one slow guard's round-trip the prefix of every later subscriber's latency —
+ * measured at 50 subscribers × a 5 ms guard, the last delivery landed 699 ms
+ * after the write. Unbounded would open one DB round-trip per subscriber at the
+ * same instant, which on a 10-connection pool is slower than serial AND starves
+ * the request path that shares it. 8 sits under a default pool and still
+ * collapses the serial chain by roughly its own factor.
+ */
+export declare const DEFAULT_DELIVERY_CONCURRENCY = 8;
+
+/** 180 days + subdomains. Deliberately NOT `preload`: preload is effectively
+ *  irreversible for a domain, so it must be a deployment decision, never a
+ *  framework default. */
+export declare const DEFAULT_HSTS = "max-age=15552000; includeSubDomains";
+
 /** Ceiling the idle backoff climbs to. Deliberately short enough to be a
  *  FLOOR under a missed wake rather than a substitute for one. */
 export declare const DEFAULT_MAX_IDLE_INTERVAL_MS = 30000;
@@ -2423,6 +2741,16 @@ export declare const DEFAULT_MAX_IDLE_INTERVAL_MS = 30000;
  *  small enough to stop a pathological body being buffered into memory. */
 export declare const DEFAULT_MAX_RPC_BODY_BYTES: number;
 
+/**
+ * How many raw-SQL reads one request records for the undeclared-`dependsOn`
+ * diagnostic. A bound rather than none: the recording lives for as long as the
+ * async context that opened it, and a long-lived non-request context (a
+ * subscriber runner, a boot seed) would otherwise accumulate one entry per raw
+ * read forever. Reads beyond the bound are dropped, not remembered — this is a
+ * diagnostic, and a diagnostic that leaks memory is worse than a missing one.
+ */
+export declare const DEFAULT_RAW_READ_TRACKING_LIMIT = 32;
+
 export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
 
 /**
@@ -2693,7 +3021,33 @@ export declare class Dispatcher {
      */
     private readonly computedSubs;
     private readonly computedByTable;
+    /** Resolved delivery tunables. Read once here so `voltro dev` and
+     *  `voltro serve` cannot disagree about them — see `reactiveConfig.ts`. */
+    private readonly reactive;
+    /** Query labels already warned about for an undeclared raw read, so a hot
+     *  subscription logs once rather than once per subscriber. */
+    private readonly rawReadWarned;
     constructor(deps: DispatcherDependencies);
+    /**
+     * REL-14 — a raw read that nothing can invalidate, said out loud.
+     *
+     * `store.raw(...)` is opaque to every mechanism that makes a query live: the
+     * matcher reads a predicate, the dependency graph reads an eager spec, and a
+     * raw fragment is a string neither can parse. `dependsOn` is how an author
+     * tells us; omitting it produces a subscription that opens, delivers once and
+     * then never updates. Nothing throws, nothing logs, and the bug looks like
+     * ours.
+     *
+     * Wired HERE, in the dispatcher, and called from BOTH `subscribe` and
+     * `subscribeComputed` — the one place every reactive subscription passes
+     * through, on both boot paths. `voltro dev` and `voltro serve` build their own
+     * rpc bridges and have drifted before; a check that lives in one of them is
+     * not a check. There is no second place to put this, which is the point.
+     *
+     * Once per query label. A per-subscriber warning on a hot query is its own
+     * kind of useless.
+     */
+    private warnUndeclaredRawReads;
     /**
      * Register a logical subscription. The caller's `emit` receives:
      *   - exactly one `snapshot` event with the initial query result,
@@ -2817,6 +3171,13 @@ export declare interface DispatcherDependencies {
      *  present → subscriptions whose descriptor opted in (a `cacheBinding`
      *  is passed to `subscribe`) share + cache their initial snapshot. */
     readonly cache?: SnapshotCache;
+    /**
+     * Tunables of the delivery loop — see `reactiveConfig.ts`. Absent → the
+     * documented defaults. Resolved ONCE, in the constructor, so the two boot
+     * paths cannot each derive their own answer; an env override wins over
+     * whatever is passed here.
+     */
+    readonly reactive?: ReactiveConfigInput;
 }
 
 /** Bookkeeping tenant key for the `_voltro_wakeups` rows that dormant schedules
@@ -2882,6 +3243,25 @@ export declare interface DrainResult {
     readonly failed: number;
     readonly dead: number;
     readonly skipped: number;
+    /**
+     * How many rows this pass had to look at. `0` means the queue is EMPTY, which
+     * a caller cannot otherwise tell from "everything delivered" — both leave
+     * `delivered` at whatever it was, and only one of them means the poll has
+     * nothing left to do.
+     */
+    readonly scanned: number;
+    /**
+     * When the earliest NOT-yet-due pending row comes due, as an epoch ms.
+     *
+     * `undefined` means nothing in the read window is waiting. A LOWER bound (the
+     * window is capped by `batchSize`), which is the safe direction: understating
+     * it costs one early pass, overstating it delays a delivery.
+     *
+     * This is what lets the runner arm for a backoff instead of polling until it
+     * expires — the one thing in this loop that genuinely needs a clock, since a
+     * retry becoming due is not a write anybody can be notified about.
+     */
+    readonly nextAttemptAt?: number;
 }
 
 /**
@@ -2926,6 +3306,23 @@ export declare const enableGraphObservation: () => void;
  *  columns use). Throws if no cipher is registered. */
 export declare const encryptField: (plaintext: string) => string;
 
+/**
+ * The dispatch-spine entry point. A no-op for a descriptor with no policy; a
+ * REFUSAL when a policy exists and no gate was installed.
+ *
+ * Fail-closed is the whole point: "the approvals store is not wired, so run the
+ * refund" is precisely the hole the declaration exists to close, and it is the
+ * shape a boot-path parity miss would produce.
+ */
+export declare const enforceApproval: (input: {
+    readonly procedure: string;
+    readonly kind: "mutation" | "action";
+    readonly policy: AnyApprovalPolicy | undefined;
+    readonly subject: unknown;
+    readonly input: unknown;
+    readonly traceId?: string | undefined;
+}) => Promise<void>;
+
 export declare interface EnqueueOptions {
     /** Drop this enqueue if an undelivered row already carries the same key. */
     readonly idempotencyKey?: string;
@@ -3577,8 +3974,12 @@ export declare interface ExperimentDefinition {
         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;
+     *  string, or `null` when the row carries no subject. `null` for a
+     *  `variantFrom` experiment, which assigns nothing. */
+    readonly subject: ((row: Readonly<Record<string, unknown>>) => string | null) | null;
+    /** Resolved arm reader for a `variantFrom` experiment; `null` when the
+     *  experiment assigns its own arms. Exactly one of these two is non-null. */
+    readonly variantFrom: ((row: Readonly<Record<string, unknown>>) => string | null) | null;
     readonly variants: ReadonlyArray<ExperimentVariant>;
     /** Resolved holdout fraction in [0, 1); `0` when none. */
     readonly holdout: number;
@@ -3599,8 +4000,33 @@ export declare interface ExperimentDefinitionInput {
         readonly table: string;
         readonly where?: (row: Readonly<Record<string, unknown>>) => boolean;
     };
-    /** The stable assignment key extractor. */
-    readonly subject: ExperimentSubject;
+    /**
+     * The stable assignment key extractor — the experiment ASSIGNS.
+     *
+     * Exactly one of `subject` / `variantFrom` is required. They are the two ways
+     * an experiment can know which arm a row belongs to, and they are mutually
+     * exclusive by construction: declaring both would mean two answers to one
+     * question, which is the defect this exclusion exists to prevent.
+     */
+    readonly subject?: ExperimentSubject;
+    /**
+     * READ the arm off the row instead of assigning it — for measuring an
+     * assignment something ELSE already made and persisted.
+     *
+     * This is what makes `plugin-flags` + `defineExperiment` one product rather
+     * than two that happen to sit in the same app. A flag serves a variant by its
+     * own deterministic bucketing (FNV-1a over the flag key); an experiment in
+     * `subject` mode buckets independently (FNV-1a over the EXPERIMENT name). Both
+     * are stable, both are uniform, and they DISAGREE — so measuring a flag's
+     * rollout with a `subject`-mode experiment reports the uplift of an arm
+     * assignment nobody was ever served. Reading the arm the flag actually served
+     * (write `flagVariant(ctx, f)` onto the row, point `variantFrom` at that
+     * column) makes the served arm and the measured arm the same fact.
+     *
+     * Persisting the arm is also the only version that survives a weight change:
+     * a re-hash at read time silently re-labels every historical row.
+     */
+    readonly variantFrom?: ExperimentVariantSource;
     /** 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
@@ -3630,9 +4056,23 @@ export declare class ExperimentEvaluator {
     private readonly now;
     private seeded;
     private lastUpdatedAt;
+    /** The declared arm names — the admissible set in `variantFrom` mode. */
+    private readonly declaredVariants;
     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. */
+    /**
+     * The variant an in-scope row belongs to, or `null` when the row is out of the
+     * `where` population, carries no subject, or (in `variantFrom` mode) carries
+     * an arm this experiment does not declare.
+     *
+     * The two modes meet here and only here — the maintainers behind this are
+     * identical either way, which is the point: an experiment that MEASURES an
+     * arm somebody else assigned rides the same per-write IVM aggregate as one
+     * that assigns its own.
+     *
+     * An unrecognised arm name is EXCLUDED, never folded into a neighbour. A typo
+     * that silently landed in the baseline would corrupt the one number every
+     * other row's lift is divided by.
+     */
     private variantOf;
     private inScope;
     /** Seed both maintainers from the current base rows. Never emits (there is no
@@ -3778,6 +4218,17 @@ export declare interface ExperimentVariantResult {
     readonly diff: number | null;
 }
 
+/**
+ * Where the ARM comes from when the experiment did not assign it.
+ *
+ * A column NAME whose value IS the variant, or a function returning it.
+ * `null` / `undefined` / a name that is not one of the declared variants ⇒ the
+ * row is UNASSIGNED and excluded from every arm — an unrecognised arm name is
+ * never folded into a neighbour, because a typo that silently lands in
+ * `control` corrupts the baseline the whole result is measured against.
+ */
+declare type ExperimentVariantSource = string | ((row: Readonly<Record<string, unknown>>) => string | null | undefined);
+
 /** 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 {
@@ -3980,12 +4431,15 @@ export declare const gauge: (name: string, description?: string) => Metric.Metri
 /** Generate a fresh token `<prefix><40-char-base64url>`. */
 export declare const generateApiKeyToken: (prefix?: string) => string;
 
+export declare const getApprovalGate: () => ApprovalGateApi | undefined;
+
+/** The credential bound to a connection, if any. Exposed for diagnostics and
+ *  for `applyConnectionCredential`; the auth chain goes through the latter. */
+export declare const getConnectionCredential: (clientId: number) => ConnectionCredential | undefined;
+
 /** The registered resolver, if the app declared any connections. */
 export declare const getConnectionResolver: () => ConnectionResolver | undefined;
 
-/** Look up the override for a connection. Returns `undefined` if no override is set. */
-export declare const getConnectionSubject: (clientId: number) => Subject | undefined;
-
 export declare const getCredentialExpiry: (clientId: number) => number | undefined;
 
 /** The registered field cipher, if any. The store middleware reads this. */
@@ -4058,6 +4512,10 @@ export declare const historyProvenance: (history: ReadonlyArray<RowHistoryEntry>
  *  this name when `holdout > 0`. */
 export declare const HOLDOUT_VARIANT = "holdout";
 
+/** Safe-for-any-page policy: closes clickjacking + base-tag injection + plugin
+ *  embedding without constraining what the page itself loads. */
+export declare const HTML_CSP = "frame-ancestors 'none'; base-uri 'none'; object-src 'none'";
+
 /** 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;
@@ -4255,6 +4713,8 @@ export declare interface InspectStream {
 
 export { inspectWorkflow }
 
+export declare const installApprovalGate: (gate: ApprovalGateApi) => void;
+
 /**
  * Install the resolver that answers `guards: [{ action, resourceType }]`.
  *
@@ -4341,6 +4801,9 @@ export declare type InverseOp = {
  *  inverse needs (e.g. a hard-delete with no captured `prev`). */
 export declare const invertChange: (c: ForwardChange) => InverseOp | null;
 
+/** Parse an already-normalized address into its bytes (4 for v4, 16 for v6). */
+export declare const ipToBytes: (ip: string) => Uint8Array | undefined;
+
 export declare const isAggregateDefinition: (value: unknown) => value is AggregateDefinition;
 
 export declare const isCostBudgetDefinition: (value: unknown) => value is CostBudgetDefinition;
@@ -4367,6 +4830,34 @@ export declare const isInfraError: (e: unknown) => boolean;
 
 export declare const isObservingGraph: () => boolean;
 
+/**
+ * Shadow an INHERITED scope with a fresh one; do nothing when there is none.
+ *
+ * Two decisions here, and both were measured rather than reasoned.
+ *
+ * WHY IT ISOLATES INSTEAD OF REUSING. Nothing stops a non-request caller from
+ * building a handler-facing store on a long-lived context — a boot seed,
+ * `runAsSystem`, a subscriber runner. A scope opened there is found by every
+ * request that runs underneath it (async-local lookup walks outward), so reusing
+ * it would collect every request's raw reads into one bag and let a warning name
+ * a query that never issued the read. A diagnostic that names the WRONG query is
+ * worse than a missing one.
+ *
+ * WHY IT DOES NOTHING WHEN THERE IS NO SCOPE, rather than opening one eagerly.
+ * `enterWith` is not free after it returns: each live frame taxes every
+ * subsequent `await` in that context. Measured — a bare `await Promise.resolve()`
+ * costs 0.165 µs with no frame, 0.256 µs with one, and 0.524 µs with six; they
+ * STACK. Opening a scope for every request would put that on the request path in
+ * exchange for nothing on the overwhelming majority of requests, which never
+ * touch raw SQL at all. `recordRawRead` opens one on demand instead, so the cost
+ * lands only on a request that already paid for a database round-trip.
+ *
+ * What this costs is a raw read inside `store.transactional(...)`: the
+ * transaction's re-wrap isolates, so the read lands in the transaction's scope
+ * and the subscribe never sees it. A missed warning, not a wrong one.
+ */
+export declare const isolateRawReadScope: () => void;
+
 /**
  * A subject that AUTHENTICATED but resolved with NO active org — a `user` (not
  * `anonymous`/`system`) carrying the empty-string tenant sentinel. Every
@@ -4415,6 +4906,10 @@ export declare const isScheduleDefinition: (v: unknown) => v is BrandedScheduleD
  */
 export declare const isSoftDelete: (change: ChangeEvent) => boolean;
 
+/** The methods that can change state. A GET cannot be a CSRF write, and the WS
+ *  upgrade is a GET — so the upgrade is guarded by PATH, not by method. */
+export declare const isStateChangingMethod: (method: string) => boolean;
+
 /** A freshly issued key — `token` is shown ONCE and never stored in clear. */
 export declare interface IssuedApiKey {
     readonly id: string;
@@ -4442,6 +4937,9 @@ export declare interface IssueInput {
     readonly metadata?: Readonly<Record<string, unknown>> | null;
 }
 
+/** Is `address` one of the peers we are willing to take a forwarded chain from? */
+export declare const isTrustedProxy: (address: string | undefined, config: TrustedProxyConfig) => boolean;
+
 export declare const isWorkflowEventTriggerDefinition: (value: unknown) => value is WorkflowEventTriggerDefinition;
 
 /** A maintainable aggregate op. (countDistinct / window funcs are NOT here —
@@ -4551,6 +5049,8 @@ export declare const listConnectionStates: (store: VaultStore, registry: Connect
 
 export declare const listResourcePolicies: () => ReadonlyArray<ResourcePolicy>;
 
+export { listRetentionConflicts }
+
 export { listRetentions }
 
 export declare interface LoaderDeps {
@@ -4704,10 +5204,44 @@ export declare const makeApiKeyUsageFlusher: (store: ApiKeyStore) => (id: string
  *  the test-context factory so `ctx.access` can't drift between them. */
 export declare const makeAppAccess: (subject: Subject) => AppAccess;
 
+/**
+ * Build the gate over a live store. ONE construction, called by the shared cli
+ * builder both boot paths use — the dev/serve parity rule applied to a control
+ * whose absence is a silent open door rather than a crash.
+ */
+export declare const makeApprovalGate: (options: MakeApprovalGateOptions) => ApprovalGateApi;
+
+export declare interface MakeApprovalGateOptions {
+    readonly store: DataStore;
+    /** App-level default expiry (the `approvals.expiresIn` tunable), already
+     *  resolved to ms by the caller. Falls back to 24 h. */
+    readonly defaultExpiryMs?: number;
+    readonly now?: () => number;
+}
+
 /** Build the `ctx.kv` facade. `KV_BACKEND` picks the backend; unknown values
  *  fall back to `database`. */
 export declare const makeAsyncKv: ({ store, env }: KvFacadeOptions) => Promise<KvFacade>;
 
+/**
+ * The `AuthMiddleware` + `ConnectionInfoMiddleware` pair every rpc surface
+ * needs, wired to one app's strategy chain.
+ *
+ * Per call, in this order:
+ *
+ *  1. patch the connection's soft-reauth credential over the transport headers
+ *     (a no-op for a connection that never re-authenticated);
+ *  2. run the FULL chain on the result — strategies, session revocation,
+ *     `resolveScopes`, the scope cache;
+ *  3. record what the strategy verified about the credential's lifetime, so
+ *     `ConnectionInfo.credentialExpiresAt` reports the token's own `exp` rather
+ *     than a cookie derivation that only ever saw one auth shape.
+ *
+ * Step 1 is the only thing a re-authenticated connection gets. It changes WHICH
+ * credential is presented and nothing about how it is judged.
+ */
+export declare const makeAuthMiddlewareLayers: (options: AuthMiddlewareLayerOptions) => Layer.Layer<AuthMiddleware | ConnectionInfoMiddleware>;
+
 /**
  * Detect a serial jump per origin, and report it as a proven count.
  *
@@ -4838,6 +5372,35 @@ export declare const makeMutationRunner: (deps: MutationRunnerDeps) => (mutation
  */
 export declare const makeOneShotQueryRunner: <D>(deps: OneShotQueryRunnerDeps<D>) => (query: MutationLike, input: unknown, requestContext: ServeRequestContext) => Promise<unknown>;
 
+/**
+ * Build the per-boot "is this path outside the origin check" predicate.
+ *
+ * Everything not named here is guarded. The three inputs, and why each is a
+ * different KIND of exemption:
+ *
+ *   - `INSPECT_PREFIX` — structural, above.
+ *   - `webhookPaths` — the `*.webhook.tsx` mounts. Their caller is a third
+ *     party and `assertWebhookRoutesDeclareVerification` refuses to boot one
+ *     that has not declared how it authenticates that caller, so the signature
+ *     — not the cookie — is the authority. (Most send no `Origin` and would
+ *     pass anyway; naming them means a provider that DOES send one is not a
+ *     mystery 403 in production.)
+ *   - `exemptRoutePaths` — DECLARED, per route, via
+ *     `PluginHttpRoute.originGuard: 'exempt'`. The claim and the test to apply
+ *     are documented on that field.
+ *
+ * A path shared by SEVERAL routes is exempt only when EVERY route on it
+ * declares the exemption — the pre-routing check cannot know which route in the
+ * group will end up owning the method, so the strictest member decides.
+ */
+export declare const makeOriginGuardExemption: (input: {
+    readonly webhookPaths?: Iterable<string> | undefined;
+    readonly httpRoutes?: Iterable<{
+        readonly path: string;
+        readonly originGuard?: "exempt" | undefined;
+    }> | undefined;
+}) => ((path: string) => boolean);
+
 export declare const makeOutboxFacade: (deps: OutboxFacadeDeps) => OutboxFacade;
 
 export declare const makePostCommitWorkflowFacade: (base: WorkflowsAppContext, afterCommit: (work: () => Promise<unknown>) => void) => WorkflowsAppContext;
@@ -5137,6 +5700,17 @@ declare interface MemoryRywOptions {
  */
 export declare const memoryRywPositionStore: (options?: MemoryRywOptions) => RywPositionStore;
 
+/**
+ * Merge a name→value map into a `Cookie` header string, replacing same-named
+ * pairs and preserving every other cookie the connection carries.
+ *
+ * Replacing the whole header would be simpler and wrong: a rebinder knows its
+ * own cookie and nothing about the CSRF token, the locale, or the second app on
+ * the same host. Values are percent-encoded on the way in because `readCookie`
+ * percent-decodes on the way out, and the round trip has to be lossless.
+ */
+export declare const mergeCookieHeader: (existing: string | undefined, patch: Readonly<Record<string, string>>) => string;
+
 export { MetricBoundaries }
 
 export declare interface MetricBucketPoint {
@@ -5174,6 +5748,23 @@ export declare type MetricSampleType = 'counter' | 'gauge' | 'histogram' | 'summ
  *  into the OTel MeterProvider when a `metricReader` is configured. */
 export declare type MetricsMode = 'off' | 'console' | 'otlp' | 'memory';
 
+/**
+ * Ordering token for one mirrored write.
+ *
+ * **The sink MUST persist this and MUST NOT invent its own.** It is
+ * assigned by the framework at the moment the change leaves the store's
+ * change channel — i.e. in COMMIT order — so a write with a lower
+ * version is, by construction, an older image of that row. Stamping a
+ * version at sink-call time instead (a `Date.now()` inside `upsert`)
+ * makes a late-arriving STALE image outrank the fresh one and win
+ * permanently; that is the bug this type exists to make unrepresentable.
+ *
+ * Monotonically increasing within a process, and wall-clock-derived
+ * (microseconds since the epoch, bumped by one on collision) so it also
+ * increases across a restart.
+ */
+export declare type MirrorVersion = number;
+
 export declare interface MutationLifecycle {
     readonly afterCommit: (work: () => Promise<unknown>) => void;
 }
@@ -5183,6 +5774,9 @@ export declare interface MutationLike {
         readonly name: string;
         readonly source?: string | ReadonlyArray<string> | undefined;
         readonly guards?: ReadonlyArray<AnyCheckSpec> | undefined;
+        /** The second-human control (mutation/action only). Enforced by
+         *  `enforceApprovalGate`, immediately after `enforceGuards`. */
+        readonly requiresApproval?: AnyApprovalPolicy | undefined;
         readonly target?: {
             readonly table: string;
         } | ReadonlyArray<{
@@ -5278,6 +5872,9 @@ export declare const nextWakeup: (store: DataStore) => Promise<Wakeup | null>;
  *  registered, or for a system subject. */
 export declare const NO_ROW_FILTER: RowFilterScope;
 
+/** Nothing trusted: the socket address is the client address. The default. */
+export declare const NO_TRUSTED_PROXIES: TrustedProxyConfig;
+
 /**
  * The real single-node supervisor: `spawn`s the app command and considers
  * it healthy once `healthUrl` returns 2xx. Stopping sends `stopSignal`
@@ -5346,6 +5943,15 @@ export declare const noopAnalyticsSpec: AnalyticsSinkSpec;
  *  misses, writes are dropped. Mirrors the cache's `noopCache`. */
 export declare const noopKv: AsyncKv;
 
+/** Strip the decorations a real-world address string arrives with:
+ *  `[::1]:443` → `::1`, `::ffff:10.0.0.1` → `10.0.0.1`, `fe80::1%eth0` → `fe80::1`. */
+export declare const normalizeIp: (raw: string) => string | undefined;
+
+/** `HTTPS://Example.com:443/x` → `https://example.com`. Returns the lowercased
+ *  input when it is not a parseable absolute URL, so an unparseable Origin can
+ *  never accidentally compare equal to a real one. */
+export declare const normalizeOrigin: (raw: string) => string;
+
 /**
  * `.one()` matched a number of rows other than exactly one.
  *
@@ -5442,14 +6048,6 @@ export declare interface ObservedProcedure {
  */
 export declare const observeStore: <S extends object>(store: S) => S;
 
-/**
- * Listen for re-bind events. Returns an unsubscribe function. Used by
- * the dispatcher to re-scope active subscriptions when a connection's
- * subject changes (e.g. anonymous → authenticated user on a different
- * tenant — subscriptions filtered by tenantId need re-evaluation).
- */
-export declare const onBindConnectionSubject: (listener: (clientId: number, subject: Subject) => void) => () => void;
-
 export declare interface OneShotQueryRunnerDeps<D> extends QueryProducerDeps<D> {
     /**
      * Execute a FINALIZED (tenant-scoped) descriptor → rows. On the WS path the
@@ -5499,6 +6097,26 @@ export declare interface OrchestratorTickDeps {
     readonly log?: WakeOrchestratorLogger;
 }
 
+export declare type OriginDecision = {
+    readonly allowed: true;
+    readonly reason: 'guard-off' | 'same-origin' | 'loopback' | 'allowlisted' | 'no-browser-origin';
+} | {
+    readonly allowed: false;
+    readonly reason: 'cross-origin' | 'opaque-origin' | 'cross-site-metadata';
+    /** What the request claimed, for the log line. Never echoed to the client. */
+    readonly origin: string;
+};
+
+export declare interface OriginGuardConfig {
+    readonly mode: OriginGuardMode;
+    /** Extra origins to accept, normalised to `scheme://host[:port]`. Needed for
+     *  a split deployment where the web app and the api sit on different hosts. */
+    readonly allowedOrigins: ReadonlyArray<string>;
+}
+
+/** `off` disables the check entirely; `same-origin` (default) enforces it. */
+export declare type OriginGuardMode = 'off' | 'same-origin';
+
 /**
  * Map an `import('@effect/opentelemetry')` rejection to what the reader needs.
  *
@@ -5648,6 +6266,13 @@ declare interface P2COptions {
     readonly random?: () => number;
 }
 
+/**
+ * Parse an interval string (`'30m'`, `'4h'`, `'7d'`) to ms, or `null`.
+ * A local copy for the same reason `finops.ts` keeps one — this module must not
+ * grow a dependency for five lines of regex.
+ */
+export declare const parseApprovalInterval: (spec: string) => number | null;
+
 /** Parse a `traceparent` header. Returns null when malformed or when
  *  the all-zero invalid ids are present (per the spec those are
  *  treated as "no parent"). */
@@ -5683,6 +6308,19 @@ export declare const payloadPropertyNames: (schema: Schema.Schema.Any) => {
     readonly optional: ReadonlyArray<string>;
 };
 
+/**
+ * The calling subject's approval work: intents they may DECIDE, plus intents
+ * they REQUESTED that are still live.
+ *
+ * Subject-scoped in here rather than by a descriptor guard — see the descriptor
+ * comment for why. An anonymous caller gets an empty list, which is the correct
+ * answer and not a refusal: they have no work.
+ */
+export declare const pendingApprovalsFor: (store: DataStore, subject: Subject | null, options?: {
+    readonly limit?: number | undefined;
+    readonly now?: () => number;
+}) => Promise<ReadonlyArray<PendingApproval>>;
+
 /** One resolved rule: "when <targetTable> loses a row, do <policy> to <table.column>". */
 export declare interface PluginRefRule {
     readonly table: string;
@@ -5893,6 +6531,27 @@ export declare interface QuerySubscriberDeps<D> extends QueryProducerDeps<D> {
     readonly subscribeComputed: (computed: ComputedQuery, emit: (event: unknown) => void, context: ServeRequestContext) => Promise<() => void>;
 }
 
+/** One `store.raw(...)` call, as the reactive engine needs to see it. */
+export declare interface RawReadObservation {
+    /** The fragment's STATIC text, joined with `?` where a value was bound.
+     *  Never the values — they are user data and this string reaches a log. */
+    readonly sql: string;
+    /** The tables the caller declared, from `opts.dependsOn` or the fragment.
+     *  Empty is the whole point of this module. */
+    readonly dependsOn: ReadonlyArray<string>;
+}
+
+/**
+ * The static text of a captured fragment, with every bound value rendered as
+ * `?`.
+ *
+ * The values are deliberately NOT included. This string is written to a log and
+ * a raw fragment's values are the caller's data — a customer email, a token
+ * being looked up. The static text is what identifies the query to its author,
+ * which is all the warning needs.
+ */
+export declare const rawSqlPreview: (strings: ReadonlyArray<string>) => string;
+
 /** What a reaction does when it fires — run an agent or start a workflow. Both
  *  identified by name; the serve layer resolves + runs them as `agentActor`. */
 export declare type ReactionAct = {
@@ -6026,6 +6685,32 @@ export declare interface ReactionRunDeps {
     readonly now?: () => number;
 }
 
+/** The reactive tunables a caller may declare. Every field optional; every
+ *  default above. */
+export declare interface ReactiveConfigInput {
+    /**
+     * How many subscribers a single change event is delivered to at once.
+     *
+     * Raise it when deliveries are dominated by I/O the framework performs on the
+     * subscriber's behalf — a `guards:` resource resolver or a row-filter loader
+     * that hits the database once per subscriber. Lower it (to `1`, fully serial)
+     * only if you have measured your connection pool being starved by reactive
+     * traffic; the delivery loop shares the pool with the request path.
+     */
+    readonly deliveryConcurrency?: number;
+    /**
+     * How many raw-SQL reads one request records for the `dependsOn` diagnostic.
+     * Only worth raising if a handler issues many raw reads and you want the
+     * warning to name a later one.
+     */
+    readonly rawReadTrackingLimit?: number;
+}
+
+export declare interface ReactiveEnv {
+    readonly VOLTRO_REACTIVE_DELIVERY_CONCURRENCY?: string;
+    readonly VOLTRO_RAW_READ_TRACKING_LIMIT?: string;
+}
+
 /** A reactive query returns a builder descriptor instead of a value; the store
  *  runs it and streams the rows. Only queries may do this. */
 export declare type ReactiveReturn<D extends ExecutorDescriptor> = D extends {
@@ -6136,6 +6821,21 @@ export declare const recordEventPublished: (event: string) => void;
 /** Subscriber attached (+1) or detached (-1). */
 export declare const recordEventSubscribers: (event: string, delta: number) => void;
 
+/**
+ * Record a raw read, opening a scope for the rest of this execution context if
+ * none is open yet.
+ *
+ * Opening it HERE is what keeps the request path free of an async-local frame it
+ * would almost never use — see `isolateRawReadScope`. The scope then lives for
+ * the remainder of this context, which is the request, which is exactly long
+ * enough for the subscribe that follows to read it.
+ *
+ * Bounded by `rawReadTrackingLimit`, and DEDUPED by sql text: a handler that
+ * raw-reads in a loop must not turn a diagnostic into a leak, and the tenth
+ * identical read tells the reader nothing the first did not.
+ */
+export declare const recordRawRead: (observation: RawReadObservation) => void;
+
 /**
  * Record one framework sample into the Effect metric registry. Synchronous —
  * metric updates are pure, so `runSync` is cheap and safe to call from the
@@ -6366,6 +7066,11 @@ export declare interface RegistryTableLike {
     readonly validatePatchSchema?: Schema.Schema.Any;
 }
 
+/** Rebuild checkable guards from the row. The stored resource id becomes a
+ *  constant extractor, so the decision is scoped to the SAME resource the
+ *  request was. */
+export declare const rehydrateGuards: (serialized: ReadonlyArray<SerializedGuard>) => ReadonlyArray<AnyGuardSpec>;
+
 /** A relationship tuple — `subjectId` has `relation` on `<resourceType>:<resourceId>`.
  *  In practice these are rows in a relation table; the engine takes them as data. */
 export declare interface RelationTuple {
@@ -6548,8 +7253,8 @@ export declare interface ResendOptions {
 /** Exported for tests — the warn-once set is process-global by design. */
 export declare const resetComputedQueryCacheWarnings: () => void;
 
-/** Test/dev-only — clear ALL overrides. Don't call from app code. */
-export declare const _resetConnectionSubjectsForTest: () => void;
+/** Test/dev-only — clear ALL per-connection state. Don't call from app code. */
+export declare const _resetConnectionCredentialsForTest: () => void;
 
 /** Test seams for the tag-cache guard — the cache is module-private otherwise. */
 export declare const resetEventMetricTagCacheForTests: () => void;
@@ -6560,6 +7265,23 @@ export declare const resetObservedGraph: () => void;
 /** Reset to the env default (tests). */
 export declare const resetSecretsBackend: () => void;
 
+/**
+ * The client address to rate-limit, geo-block and audit by.
+ *
+ * The rules, in the order they fire:
+ *
+ *  1. No `x-forwarded-for` → the socket address. (Nothing to decide.)
+ *  2. `trustAll` → the leftmost forwarded token. The pre-fix behaviour, now an
+ *     explicit opt-in for an ingress that OVERWRITES the header.
+ *  3. Hop mode (`trustedProxies: ['2']`) → walk `n` hops in from the right of
+ *     `[...forwarded, socket]`.
+ *  4. Otherwise the immediate peer must itself be trusted; if it is not, the
+ *     chain is a client-supplied string and is ignored entirely.
+ *  5. With a trusted peer, walk the chain right-to-left past every trusted hop;
+ *     the first address that is NOT a configured proxy is the client.
+ */
+export declare const resolveClientAddress: (input: ClientAddressInput) => string | undefined;
+
 /**
  * Resolve the calling subject's credential for one connection, refreshed.
  *
@@ -6656,6 +7378,11 @@ export declare interface ResolvedConnection {
  */
 export declare const resolveDependentTables: (descriptor: QueryDescriptor) => ReadonlySet<string>;
 
+export declare interface ResolvedReactiveConfig {
+    readonly deliveryConcurrency: number;
+    readonly rawReadTrackingLimit: number;
+}
+
 /**
  * A `WorkflowCallerContext` after the engine has filled in what a workflow
  * always needs. A run started by a request carries the caller's subject; a
@@ -6678,8 +7405,39 @@ export declare interface ResolvedWorkflowCallerContext extends WorkflowCallerCon
     readonly traceId: string;
 }
 
+/**
+ * Resolve the guard's configuration.
+ *
+ * Precedence: explicit `app.config.ts` values (threaded through
+ * `RpcServerOptions.security`) → env override → safe default. An unrecognised
+ * mode falls back to enforcement rather than to `off`: a typo in a security
+ * knob must not silently disable it.
+ */
+export declare const resolveOriginGuardConfig: (configured?: {
+    readonly mode?: OriginGuardMode | undefined;
+    readonly allowedOrigins?: ReadonlyArray<string> | undefined;
+} | undefined, env?: Readonly<Record<string, string | undefined>>) => OriginGuardConfig;
+
+export declare const resolveReactiveConfig: (config?: ReactiveConfigInput | undefined, env?: ReactiveEnv) => ResolvedReactiveConfig;
+
 export declare const resolveRedirectUri: (definition: OAuth2ConnectionDefinition, publicUrl: string) => string;
 
+/**
+ * Whether the request reached the app over TLS.
+ *
+ * `x-forwarded-proto` is believed only from a trusted proxy, for exactly the
+ * reason `x-forwarded-for` is: it is a client-writable header. Getting this
+ * wrong in the permissive direction would let any client make the framework
+ * emit HSTS (harmless) — and, more importantly, would let it claim `https` in
+ * an audit record, so it is gated the same way.
+ */
+export declare const resolveRequestIsHttps: (input: {
+    readonly socketEncrypted: boolean;
+    readonly socketAddress: string | undefined;
+    readonly xForwardedProto: string | undefined;
+    readonly config: TrustedProxyConfig;
+}) => boolean;
+
 /** Rebuild the flagged groups from the (already-committed) base rows + merge —
  *  the caller's resolution of a min/max rescan signal. `baseRows` is the full
  *  current table (or at least every row in the rescan groups). */
@@ -6739,6 +7497,21 @@ export declare const resolveSecretsBackend: (config: SecretsBackendConfig | unde
  *  await (e.g. deriving a permission host from a key). Bypasses remote backends. */
 export declare const resolveSecretSync: (key: string) => string | undefined;
 
+/**
+ * Resolve the header configuration.
+ *
+ * Precedence: explicit `app.config.ts` values → env override → defaults. Env
+ * knobs: `VOLTRO_SECURITY_HEADERS` (`off|default|strict`), `VOLTRO_CSP`,
+ * `VOLTRO_CSP_HTML`, `VOLTRO_HSTS` — each accepting `off` to drop just that one.
+ */
+export declare const resolveSecurityHeaders: (configured?: SecurityHeadersOptions | undefined, env?: Readonly<Record<string, string | undefined>>) => SecurityHeadersConfig;
+
+/** The app's composed strategy chain — `buildResolveSubject`'s return value. */
+export declare type ResolveSubjectFn = (input: {
+    headers: Record<string, string | undefined>;
+    clientId: number;
+}) => Promise<SubjectResolution>;
+
 /**
  * Resolve the recording mode. `VOLTRO_TIMELINE=off|interesting|all` (also
  * on/1 = interesting, 0 = off) overrides; default `interesting` outside
@@ -6748,6 +7521,18 @@ export declare const resolveSecretSync: (key: string) => string | undefined;
  */
 export declare const resolveTimelineMode: (env?: Record<string, string | undefined>) => TimelineMode;
 
+/**
+ * Resolve the trusted-proxy configuration.
+ *
+ * Precedence: explicit config (from `app.config.ts`, threaded through
+ * `RpcServerOptions.security.trustedProxies`) beats the `VOLTRO_TRUSTED_PROXIES`
+ * env override, which beats the safe default of trusting nothing. The env var
+ * exists so an operator can correct a misconfigured deployment without a
+ * rebuild; the config field exists because it is a tunable and tunables belong
+ * in `app.config.ts`.
+ */
+export declare const resolveTrustedProxies: (configured?: ReadonlyArray<string> | undefined, env?: Readonly<Record<string, string | undefined>>) => TrustedProxyConfig;
+
 /** Per-resource-type policy. `actions` maps an action to the relations that
  *  grant it (ANY-of). `implies` is relation implication (owner ⇒ editor ⇒
  *  viewer), applied as a transitive closure before the action check. */
@@ -6760,6 +7545,10 @@ export declare interface ResourcePolicy {
 /** The full ordered list of result variants for a definition, holdout last. */
 export declare const resultVariantNames: (def: ExperimentDefinition) => ReadonlyArray<string>;
 
+export { RetentionConflict }
+
+export { RetentionSource }
+
 export { RetentionSpec }
 
 export { retentionTtlMsFromEnv }
@@ -7001,15 +7790,36 @@ export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
         readonly ping?: () => Promise<boolean>;
     };
     /**
-     * Max `Content-Length` (bytes) accepted on the buffered `POST /rpc` JSON
-     * endpoint. A JSON rpc mutation/action/query envelope is never legitimately
-     * large, so an oversized body is a memory-DoS attempt — rejected with 413
-     * BEFORE the body is buffered. Applies ONLY to `/rpc` (JSON); file uploads
-     * ride separate plugin routes with their own `limits.maxBytes`, and WS frames
-     * are capped by the `ws` library default (100 MiB). Per-IP rate limiting +
-     * the primary body cap belong at the ingress. Default {@link DEFAULT_MAX_RPC_BODY_BYTES}.
+     * Max body size (bytes) accepted on the buffered `POST /rpc` JSON endpoint. A
+     * JSON rpc mutation/action/query envelope is never legitimately large, so an
+     * oversized body is a memory-DoS attempt — refused with `413` and never
+     * buffered past the cap. Applies ONLY to `/rpc` (JSON); file uploads ride
+     * separate plugin routes with their own `limits.maxBytes`, and WS frames are
+     * capped by the `ws` library default (100 MiB). Per-IP rate limiting + the
+     * primary body cap belong at the ingress. Default
+     * {@link DEFAULT_MAX_RPC_BODY_BYTES}.
+     *
+     * **Both shapes end in a `413`, and the byte counter is what enforces it.**
+     * A declared `Content-Length` over the cap is refused first, before the client
+     * uploads anything — a courtesy, not the enforcement, since a
+     * `Transfer-Encoding: chunked` body declares no length. The counter runs over
+     * the arriving bytes, stops accumulating the moment the running total crosses
+     * the cap, drains the remainder and answers `413`.
+     *
+     * This paragraph used to claim the counter was the enforcement while the
+     * declared check was the courtesy, and observably it was the other way round:
+     * the counter bounded MEMORY correctly and produced no client-visible status
+     * at all. It cut the body by destroying the request, that took the socket with
+     * it, and the 413 it had just built was written into a dead connection —
+     * `curl: (56) Recv failure: Connection reset by peer` where the same bytes
+     * with a `Content-Length` got a clean 413. See `rpcBodyCap.ts`.
      */
     readonly maxRpcBodyBytes?: number;
+    /**
+     * Transport-level security policy for this listener — see
+     * {@link TransportSecurityOptions}. `undefined` → the safe defaults.
+     */
+    readonly security?: TransportSecurityOptions;
 }
 
 /**
@@ -7150,6 +7960,16 @@ export declare const runWithDeadlockRetry: <T>(work: () => Promise<T>, options?:
  */
 export declare const runWithObservedProcedure: <T>(procedure: ObservedProcedure, work: () => T) => T;
 
+/**
+ * Run `fn` inside a FRESH raw-read scope, restoring whatever was current before.
+ *
+ * The wrapping form, for callers that have a callback: the dispatcher, which
+ * wraps a computed query's recompute so a raw read issued by a LATER handler run
+ * is attributed to that run rather than to whatever opened the request; and
+ * tests, which need a scope that provably does not outlive them.
+ */
+export declare const runWithRawReadScope: <T>(fn: () => T) => T;
+
 /**
  * Run `fn` with `loader` current, restoring whatever was current before.
  *
@@ -7619,6 +8439,9 @@ declare interface ScopeCtx {
     readonly rowFilter?: RowFilterScope;
 }
 
+/** The scope strings a UI shows ("ask someone with …"). */
+export declare const scopeStringsOf: (serialized: ReadonlyArray<SerializedGuard>) => ReadonlyArray<string>;
+
 export declare interface SecretsBackend {
     /** Resolve a secret by key. `undefined` when absent. */
     readonly get: (key: string) => Promise<string | undefined>;
@@ -7633,6 +8456,49 @@ export declare type SecretsBackendConfig = 'env' | {
     readonly backend: SecretsBackend;
 };
 
+export declare interface SecurityHeadersConfig {
+    readonly mode: SecurityHeadersMode;
+    /** CSP for non-HTML responses. `false` → do not send one. */
+    readonly csp: string | false;
+    /** CSP for `text/html` responses. `false` → do not send one. */
+    readonly cspHtml: string | false;
+    /** `Strict-Transport-Security` value; only emitted over https. */
+    readonly hsts: string | false;
+    readonly frameOptions: string | false;
+    readonly referrerPolicy: string | false;
+    readonly contentTypeOptions: string | false;
+    /** Anything else the app wants on every response (e.g. `Permissions-Policy`,
+     *  `Cross-Origin-Resource-Policy`). Deliberately not defaulted: both of those
+     *  break legitimate cross-origin dashboards when guessed wrong. */
+    readonly extra: Readonly<Record<string, string>>;
+}
+
+/**
+ * The headers to ADD to one response. The caller must not overwrite a header
+ * the route already set.
+ *
+ * `https` gates HSTS only: announcing a year of HTTPS-only from a plain-http
+ * response is either ignored (per RFC 6797) or, on a dev box reached over
+ * `http://localhost`, actively harmful.
+ */
+export declare const securityHeadersFor: (config: SecurityHeadersConfig, request: {
+    readonly contentType: string | undefined;
+    readonly https: boolean;
+}) => Readonly<Record<string, string>>;
+
+export declare type SecurityHeadersMode = 'off' | 'default' | 'strict';
+
+export declare interface SecurityHeadersOptions {
+    readonly mode?: SecurityHeadersMode | undefined;
+    readonly csp?: string | false | undefined;
+    readonly cspHtml?: string | false | undefined;
+    readonly hsts?: string | false | undefined;
+    readonly frameOptions?: string | false | undefined;
+    readonly referrerPolicy?: string | false | undefined;
+    readonly contentTypeOptions?: string | false | undefined;
+    readonly extra?: Readonly<Record<string, string>> | undefined;
+}
+
 export declare class SelectBuilder {
     private readonly backend;
     private readonly scope;
@@ -7684,6 +8550,25 @@ export declare class SelectBuilder {
     get descriptor(): QueryDescriptor;
 }
 
+/** A guard, flattened to something a row can hold. */
+export declare type SerializedGuard = {
+    readonly kind: 'scope';
+    readonly scope: ReadonlyArray<string>;
+    readonly mode: 'all' | 'any';
+    readonly resource: string | null;
+} | {
+    readonly kind: 'policy';
+    readonly action: string;
+    readonly resourceType: string;
+    readonly resource: string | null;
+};
+
+/**
+ * Flatten the descriptor's approver guards, resolving each `resource` extractor
+ * against the REQUEST's input while it is still available.
+ */
+export declare const serializeGuards: (guards: ReadonlyArray<AnyGuardSpec>, input: unknown) => ReadonlyArray<SerializedGuard>;
+
 export declare interface ServeRequestContext {
     readonly subject: unknown;
     readonly traceId: string;
@@ -7707,6 +8592,33 @@ export declare interface ServeRequestContext {
  */
 export declare const serverOnlyColumnNames: (tableName: string) => ReadonlyArray<string>;
 
+/**
+ * A generated CRUD write (`crud.create` / `crud.update`) was handed a
+ * `.serverOnly()` column in its INPUT.
+ *
+ * `.serverOnly()` is the WIRE-exposure axis: the column never crosses the
+ * boundary in EITHER direction. Reads strip it; a write that accepts it is the
+ * same violation mirrored — mass assignment of a column the schema declared the
+ * client may not see, let alone set.
+ *
+ * Refused rather than silently stripped: a stripped field makes an attack
+ * indistinguishable from a no-op and leaves an honest caller wondering why the
+ * value it sent never landed. `columns` names what was rejected so the fix
+ * (drop the field from the descriptor's input schema, or from the caller) is
+ * mechanical.
+ */
+export declare class ServerOnlyColumnWrite extends ServerOnlyColumnWrite_base {
+}
+
+declare const ServerOnlyColumnWrite_base: Schema.TaggedErrorClass<ServerOnlyColumnWrite, "ServerOnlyColumnWrite", {
+    readonly _tag: Schema.tag<"ServerOnlyColumnWrite">;
+} & {
+    /** The table the write targeted. */
+    table: typeof Schema.String;
+    /** The `.serverOnly()` columns the input tried to set. */
+    columns: Schema.Array$<typeof Schema.String>;
+}>;
+
 /** One leak: a wire query that declares a serverOnly column in its output. */
 export declare interface ServerOnlyLeak {
     readonly query: string;
@@ -7985,7 +8897,7 @@ export declare interface StoreCredentialInput {
  * a mutation's `error:` schema when you want every kind surfaced
  * typed to the client.
  */
-export declare type StoreError = TenantScopeViolation | StoreOperationFailed | TableValidationFailed;
+export declare type StoreError = TenantScopeViolation | TenantRowNotFound | ServerOnlyColumnWrite | StoreOperationFailed | TableValidationFailed;
 
 export declare interface StoreMiddlewareContext {
     readonly subject: Subject;
@@ -8343,6 +9255,41 @@ export declare interface TenantCostState {
     readonly lastUpdatedAt: number | null;
 }
 
+/**
+ * A keyed-by-primary-key write (`ctx.store.update(table, id, patch)`,
+ * `delete(table, id)`, `hardDelete(table, id)`, `patchJson(table, id, …)`) on a
+ * `tenant()`-scoped table did not resolve to a row inside the CALLER's tenant.
+ *
+ * **One error for two situations, on purpose.** It is raised identically when
+ * the row does not exist at all and when it exists but belongs to another
+ * tenant, and it carries no field that separates them. That is the whole point:
+ *
+ *   - Reporting "forbidden" for a foreign row and "not found" for a missing one
+ *     turns any keyed write into a cross-tenant EXISTENCE ORACLE — an attacker
+ *     walks ids and learns which ones are real in someone else's tenant, which
+ *     is exactly the isolation the `tenant()` mixin exists to provide.
+ *   - Collapsing the other way — silently affecting zero rows — is worse than
+ *     either: the handler reads it as "the row is gone", not "you may not touch
+ *     it", so a genuine isolation breach shows up in an app as a confusing
+ *     absent-row branch and never as a security signal.
+ *
+ * So both cases fail LOUDLY and IDENTICALLY. `id` is the key the caller itself
+ * supplied — never another tenant's data.
+ */
+export declare class TenantRowNotFound extends TenantRowNotFound_base {
+}
+
+declare const TenantRowNotFound_base: Schema.TaggedErrorClass<TenantRowNotFound, "TenantRowNotFound", {
+    readonly _tag: Schema.tag<"TenantRowNotFound">;
+} & {
+    /** The table the keyed write targeted. */
+    table: typeof Schema.String;
+    /** The primary key the CALLER supplied. Echoing it leaks nothing. */
+    id: typeof Schema.String;
+    /** Human-readable explanation for diagnostics + UI. */
+    reason: typeof Schema.String;
+}>;
+
 /**
  * A write was attempted against a `tenant()`-scoped table, but the
  * authenticated subject's `tenantId` is null — either anonymous, or
@@ -8566,6 +9513,41 @@ export declare interface TransactionalStore {
     transactional<T>(work: (tx: unknown) => Promise<T>): Promise<T>;
 }
 
+/**
+ * Transport-level security policy for the api listener.
+ *
+ * Every field is a TUNABLE, so its home is the app's `app.config.ts`
+ * (`security: { … }`, threaded to here by `voltro dev` and `voltro serve`
+ * through one shared resolver); each also carries an env override, for
+ * correcting a deployment without a rebuild. An embedder calling
+ * `startRpcServer` directly passes the same object.
+ *
+ * `undefined` on every field → the safe defaults documented on each resolver:
+ * origin checking ON, `x-forwarded-for` IGNORED, security headers ON.
+ */
+export declare interface TransportSecurityOptions {
+    /** Cross-site protection for `POST /rpc` + the WS upgrade.
+     *  `'same-origin'` (default) accepts a browser request only when its
+     *  `Origin` matches the `Host` it was sent to or is in `allowedOrigins`;
+     *  a request with NO browser origin signal (the in-process SSR loader,
+     *  a mobile SDK, another service) is allowed — see `originGuard.ts`.
+     *  Env override: `VOLTRO_ORIGIN_GUARD=off`. */
+    readonly originGuard?: OriginGuardMode;
+    /** Extra origins to accept, for a split web/api deployment where the
+     *  browser's `Origin` is a different host than the api's `Host`.
+     *  Env override: `VOLTRO_ALLOWED_ORIGINS` (comma-separated). */
+    readonly allowedOrigins?: ReadonlyArray<string>;
+    /** Whose `x-forwarded-for` to believe. Empty (the default) → the header is
+     *  IGNORED and `socket.remoteAddress` is the client address. Accepts IPs,
+     *  CIDRs, the presets `loopback` / `private`, a hop count (`['2']`), or
+     *  `['*']` to trust any peer. Env override: `VOLTRO_TRUSTED_PROXIES`. */
+    readonly trustedProxies?: ReadonlyArray<string>;
+    /** Security response headers. Env override: `VOLTRO_SECURITY_HEADERS`
+     *  (`off|default|strict`), plus `VOLTRO_CSP` / `VOLTRO_CSP_HTML` /
+     *  `VOLTRO_HSTS`. */
+    readonly headers?: SecurityHeadersOptions;
+}
+
 /**
  * Declare a workflow trigger.
  *
@@ -8597,6 +9579,16 @@ export declare const triggerWorkflow: <EventPayload = unknown, WorkflowPayload =
     };
 })) => WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>;
 
+/** How much of the forwarded chain we are willing to believe. */
+export declare interface TrustedProxyConfig {
+    /** Literal IPs / CIDR blocks / presets (`loopback`, `private`) to trust. */
+    readonly entries: ReadonlyArray<string>;
+    /** `*` — believe the leftmost XFF token from ANY peer. */
+    readonly trustAll: boolean;
+    /** Hop count (express's numeric `trust proxy`). `undefined` → not hop mode. */
+    readonly hops?: number;
+}
+
 /**
  * Atomically claim a pending wakeup for waking — CAS `pending → fired`.
  * Returns `true` iff THIS caller won the claim (the row was pending).
@@ -8642,10 +9634,10 @@ export declare type TupleSource = (req: {
 }) => Promise<ReadonlyArray<RelationTuple>> | ReadonlyArray<RelationTuple>;
 
 /**
- * Remove the override for a connection. Called by the WS-close
- * finalizer (or explicit logout flows). Idempotent.
+ * Drop everything this connection accumulated. Called by the WS-close finalizer
+ * and by explicit sign-out flows. Idempotent.
  */
-export declare const unbindConnectionSubject: (clientId: number) => void;
+export declare const unbindConnection: (clientId: number) => void;
 
 /** The store surface an inverse op needs (a subset of the framework DataStore). */
 export declare interface UndoApplyStore {
@@ -8722,6 +9714,29 @@ export declare class UndoStack<E> {
     };
 }
 
+/**
+ * Is the undo WIRE SURFACE present — the three `__voltro.undo.*` descriptors in
+ * the client's generated rpc group, and the matching routes on the server?
+ *
+ * **Deliberately NOT `undoCaptureEnabled()`, and the difference is the whole
+ * point.** The client half of that surface is a BUILD ARTEFACT:
+ * `rpcGroup.generated.ts` is written by `voltro dev`'s codegen and `voltro
+ * build` does not regenerate it. So the artefact froze whatever
+ * `undoCaptureEnabled()` answered on the developer's machine — on, by its
+ * NODE_ENV default — while the production process it ships to answers off and
+ * binds nothing. The failure appears only after deploy, and only when someone
+ * presses undo.
+ *
+ * The surface therefore reads ONLY the explicit declaration: `VOLTRO_UNDO=off`
+ * removes it everywhere (codegen + both boot paths agree, because nothing in
+ * the answer depends on when or where the code ran), and anything else keeps
+ * it. Whether the mutations are actually RECORDED stays environment-aware —
+ * that is the cost decision, and it is a genuine one. With capture off the
+ * executors answer honestly rather than 404: the log is empty because nothing
+ * was captured, and an apply/redo cannot find its row.
+ */
+export declare const undoSurfaceEnabled: (env?: Record<string, string | undefined>) => boolean;
+
 /** One `source:` entry that resolves to no declared table. */
 export declare interface UnresolvedSource {
     /** The procedure that declares it. */
@@ -8730,6 +9745,9 @@ export declare interface UnresolvedSource {
     readonly source: string;
     /** A declared table whose name is close — the rename case, usually. */
     readonly didYouMean: string | undefined;
+    /** True when the name is in the `channel:` namespace: it named a reactivity
+     *  channel nobody declared, which is a different repair from a stale table. */
+    readonly channel: boolean;
 }
 
 /**
@@ -8743,6 +9761,14 @@ export declare const unresolvedSources: (procedures: ReadonlyArray<{
     readonly source: string | ReadonlyArray<string> | undefined;
 }>, declared: ReadonlySet<string>) => ReadonlyArray<UnresolvedSource>;
 
+/** Thrown at boot; the message is the whole point, so it names the path and the
+ *  three ways out. */
+export declare class UnverifiedWebhookRoute extends Error {
+    readonly path: string;
+    readonly name = "UnverifiedWebhookRoute";
+    constructor(path: string);
+}
+
 export declare class UpdateBuilder {
     private readonly backend;
     private readonly scope;
@@ -8800,6 +9826,11 @@ export declare const useExperiment: (def: ExperimentDefinition) => Effect.Effect
 
 declare type VaultStore = Pick<DataStore, 'query' | 'insert' | 'update' | 'updateMany' | 'delete' | 'upsert'>;
 
+/** A mounted incoming-webhook handler that has declared how it authenticates. */
+export declare type VerificationDeclared<T> = T & {
+    readonly [WEBHOOK_VERIFICATION_PROPERTY]: WebhookVerification;
+};
+
 /** The pure core of live revocation: given a subject + action + a row-set,
  *  return ONLY the rows the subject may still see. The reactive matcher calls
  *  this on a permission-changing write and diffs against the prior visible set;
@@ -8830,6 +9861,16 @@ export declare const VOLTRO_SOFT_DELETE_MIXIN_ID: "voltro/softDelete";
 
 export declare const VOLTRO_TENANT_MIXIN_ID: "voltro/tenant";
 
+/**
+ * One pending (or historical) approval intent.
+ *
+ * Reactive on purpose — the requester's client subscribes to
+ * `__voltro.approvals.pending` and sees its own row flip `pending → approved`
+ * without polling, which is the whole answer to "what does the caller see
+ * meanwhile".
+ */
+export declare const _voltroApprovalsTable: TableLike;
+
 /**
  * `_voltro_connection_grants` — an IN-FLIGHT oauth2 handshake. Separate from
  * the credential table on purpose: a handshake is a short-lived, single-use
@@ -8966,10 +10007,22 @@ export declare interface WakeupRef {
  *  next register cleanly overwrites it). */
 export declare type WakeupStatus = 'pending' | 'fired';
 
+/** The property `mountIncomingWebhook` stamps onto the handler it returns.
+ *  A plain string property rather than a symbol so it survives the structural
+ *  hand-off between packages that do not import each other. */
+export declare const WEBHOOK_VERIFICATION_PROPERTY: "voltroWebhookVerification";
+
 /** Stage 4 webhook-route surface — kept transport-agnostic so the
  *  plugin can pipe its IncomingResponse through unchanged. The
  *  rpc server reads the request body (UTF-8 / binary) + headers
- *  and dispatches by path. */
+ *  and dispatches by path.
+ *
+ *  `handle` MUST carry a `voltroWebhookVerification` declaration — the
+ *  property `@voltro/plugin-webhooks`' `mountIncomingWebhook` stamps onto
+ *  the handler it returns. `startRpcServer` refuses to mount a route
+ *  without one (see `webhookVerification.ts`): an incoming webhook is a
+ *  public POST that runs application code, so "nothing verifies it" has to
+ *  be a decision somebody wrote down, not the default. */
 export declare interface WebhookRouteHandler {
     readonly handle: (request: {
         readonly method: string;
@@ -8985,6 +10038,21 @@ export declare interface WebhookRouteHandler {
 
 export declare type WebhooksAppContext = unknown;
 
+/** How an incoming webhook authenticates its caller. */
+export declare type WebhookVerification = 
+/** The framework verifies an HMAC signature (+ replay window) before the
+*  handler runs, using the webhook's configured shared secret. */
+'signature'
+/** The handler / provider integration verifies with the provider's own SDK
+*  (Stripe's `constructEvent`, etc.). The framework does not second-guess it. */
+| 'provider'
+/** Deliberately unverified — the endpoint is behind a separate trust boundary
+*  (gateway + IP allow-list). A visible decision, never a default. */
+| 'none';
+
+/** Read the declaration off a mounted handler. `undefined` → never declared. */
+export declare const webhookVerificationOf: (handle: unknown) => WebhookVerification | undefined;
+
 /**
  * Comparison operators accepted by the ergonomic `.where(col, op, value)`
  * form. `fts` falls back to a `contains` (LIKE) match here; the index-backed
@@ -9209,6 +10277,31 @@ export declare interface WorkflowLayerExecutionContext {
 export declare interface WorkflowLayerOptions<Context> {
     readonly buildContext: (callerContext: ResolvedWorkflowCallerContext, execution: WorkflowLayerExecutionContext) => Context;
     readonly resolveStartContext?: (workflowName: string, executionId: string) => WorkflowCallerContext | undefined | Promise<WorkflowCallerContext | undefined>;
+    /**
+     * Put AUTHORITY back on a restored caller identity, at execution time
+     * (REL-24).
+     *
+     * `resolveStartContext` returns IDENTITY — the start-context table strips
+     * scopes on write and on read, because a `json()` column read by another
+     * runner days later is authority frozen and made durable, which is REL-5's
+     * cookie one layer down. This hook is what re-establishes the authority, from
+     * the app's live source, on every execution attempt.
+     *
+     * Called ONLY for a run that has a recorded caller. A bootstrap run — no
+     * recorded context — is `SYSTEM_SUBJECT` and is not put through it:
+     * `SYSTEM_SUBJECT` already states its own authority, and running it through
+     * an app resolver keyed on a null id would be asking a question with no
+     * answer.
+     *
+     * Absent ⇒ the identity runs with no scopes. That is the fail-closed
+     * direction and it matches what a cookie-authenticated request already gets
+     * from an app that wires no resolver.
+     *
+     * Rejecting FAILS the attempt. Do not swallow it into "fewer scopes": a run
+     * that skips the branch it was not allowed to take looks exactly like one
+     * whose business logic said no.
+     */
+    readonly resolveAuthority?: (identity: unknown) => Promise<unknown>;
 }
 
 /**