@voltro/runtime 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -39,6 +39,27 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.5.0] — 2026-07-18
+
+### ⚠ BREAKING
+
+- **@voltro/runtime** — `.one()` now fails when a query matches MORE than one row, not only when it matches none. It previously probed with `LIMIT 1`, so a filter that quietly stopped being unique returned an arbitrary row while the thrown error still claimed "expected exactly one row". It now probes with `LIMIT 2` and fails with `NoRowFound({ found: 2 })`. Migration: a `.one()` whose filter is not unique and that meant "any match" becomes `.first()` / `.maybeOne()`; one that meant "the unique row" stays as-is and now fails loudly when that assumption breaks. `NoRowFound` and `OptimisticLockError` are now `Schema.TaggedError`s, so they can be declared directly in a descriptor's `error:` union and caught with `Effect.catchTag`. Previously they carried a `_tag` field that looked declarable but did not typecheck there, forcing every caller to catch and re-wrap them in a hand-written tagged error — that wrapper can be deleted. Constructing one directly now takes an object: `new NoRowFound({ table, found })`, `new OptimisticLockError({ table, expected })`. `instanceof` and `_tag` checks are unaffected.
+
+### Added
+
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/mcp** — Relationship (ReBAC) authorization is now declarative. A descriptor can carry `guards: [{ action, resourceType, resource: (input) => input.id }]` alongside its scope guards; the framework resolves it before the executor (for a mutation, before the transaction opens) and fails with a typed `ScopeError` naming `<resourceType>:<action>`. `defineResourcePolicy` previously enforced nothing on its own. Making it bite required hand-building a map from rpc tag to policy rule and installing an interceptor — undocumented plumbing that nobody wired, and **fail-open by omission**: an rpc missing from the map passed unchecked, with no type error and no boot warning. A guard on the descriptor cannot be forgotten for an rpc that exists, because it is part of the rpc. `setTupleSource` registers where relations are read from — a real registry, not a per-call parameter. Both entrypoints register a default reading `_voltro_rebac_tuples`; an app whose relations already live in its own tables (a `teamMembers` row) registers its own instead of copying data into a framework table. Every unanswerable case DENIES: no tuple source, no policy for the type, an input that does not identify a resource, or a tuple source that throws. An authorization question nobody can answer is a refusal. The capability manifest now carries the declared guards, so a client gates UI on the same declaration the server enforces instead of a hand-kept copy. Only the data crosses the wire — the pure `resource` extractor stays server-side and is reported as `resourceScoped: true`, so a client knows the real answer is per-row and asks rather than assuming. Because guards are re-checked on every subscription delivery, a relationship revoked mid-session now ends the stream rather than continuing to serve it.
+- **@voltro/database, @voltro/runtime, @voltro/cli** — `paginateBy(descriptor, column, cursor, limit, direction?)` generalises `paginateById` to any orderable column. `paginateById` hardcoded `id`, which is right for a sortable key and useless for what feeds actually need — "the next page by `createdAt`" — so apps fell back to hand-rolled `limit + 1` / slice / `hasMore` triples on cursors the helper could not express. `paginateById` is now literally `paginateBy(descriptor, 'id', …)`, so the two cannot drift. `direction` flips the comparison as well as the sort: a `desc` feed pages with `<`. Mismatching those is the classic keyset bug — an ascending comparison under a descending sort returns the same first page forever. The docs example previously demonstrated a related trap (ordering by `createdAt desc` and then calling `paginateById`, which silently re-orders by `id asc`); it now shows the correct form and names the trap. `ctx.load` / `ctx.loadMany` add request-scoped batching. Same-tick reads of one table coalesce into a single `WHERE id IN (...)`, so a breadth-first walk costs one query per LEVEL rather than per node — the assembly shape `relations()` + `.with()` cannot express, because each level's ids come from the level above. Misses are cached too (a repeated dangling reference is fetched once) and a failed batch rejects its waiters without poisoning the cache, so a transient store error does not become "these rows do not exist" for the rest of the request. The cache is request-scoped as a correctness requirement, not a tuning choice: anything longer-lived would serve one subject's rows to another. Workflow steps can now `yield* EffectStore`. Handlers always could; workflow executors could not, so a step reading the store had to lift `ctx.store` with `Effect.tryPromise` — the idiom the rest of the framework tells you to avoid, because it discards the typed `StoreError` channel. The asymmetry was an oversight; the layer is now provided from the workflow context's own store.
+- **@voltro/cli** — `voltro capabilities [--json]` enumerates the framework's export surface by reading the `.d.ts` files in the project's own `node_modules`, so the answer to "what does this framework export" can be verified rather than recalled. The `--json` form is locale-independent and byte-stable, so it can be diffed across upgrades. Symbols that ship but appear nowhere in the project's seeded agent guide are flagged — limited to primitives and hooks, because counting every undocumented export on a real tree gave 1,088 (mostly types and internal Layers), a number too large to act on. `voltro doctor`'s hand-roll detector gained server rules: a hand-written not-found branch on `rows[0]` (→ `.one()`), several sequential `store.query` calls assembling related data (→ `relations()` + `.with()`), `ctx.store` lifted with `Effect.promise` (→ `EffectStore`), an imperative scope check at the top of an executor (→ `guards:`), a credential-shaped column with no `.encrypted()`, a notify/webhook helper at a mutation's tail (→ `defineSubscriber` / `defineReaction`), and hand-rolled cursor pagination (→ `paginateById`). Its scan roots now include the API app directories (`queries/`, `mutations/`, `database/`, …) — without that the server rules could never have fired. The always-loaded agent core now carries a "Pick the SERVER primitive" rubric alongside the client one, and a doc-coverage gate keeps the server surface from drifting out of it.
+- **@voltro/runtime, @voltro/cli** — `ctx.outbox.enqueue(effect, payload, options?)` — a reliable external side effect from a mutation. The enqueue writes through `ctx.store`, which inside a mutation IS the transactional view, so the intent to deliver commits in the same transaction as the domain write or not at all. That closes the window a post-commit tap cannot: `@voltro/plugin-cdc-out` is at-least-once *from enqueue* (its own docs say so — a crash between commit and tap loses the event). Here the enqueue cannot be lost, because losing it means the domain write rolled back too. Delivery after commit remains at-least-once, so handlers must be idempotent; `idempotencyKey` makes that easy to honour. Delivery is declared per effect in a `*.outbox.ts` via `defineOutboxHandler`. The worker is nudged on commit for the fast path and polls every 5s — the poll is the contract, not the optimisation: it recovers rows whose nudge was lost to a crash, rows from another replica, and rows waiting out a backoff. Exponential backoff capped at 5 minutes, configurable `maxAttempts` (default 8), and a dead-letter that stays queryable in `_voltro_outbox` with its `lastError`. An effect with no registered handler is left PENDING rather than dead-lettered — the usual cause is a deploy where the enqueuing code shipped ahead of its handler, and discarding those would turn a rollout ordering detail into permanent loss of a side effect the app believes happened. Two handlers claiming one effect are refused at boot with both filenames. `_voltro_outbox` rides the declarative differ and is created only when the app declares at least one handler. Wired in both `voltro dev` and `voltro serve`.
+- **@voltro/database, @voltro/runtime** — `ctx.store.query()` now returns the row type instead of `Readonly<Record<string, unknown>>`. `QueryDescriptor<R>` carries a phantom row type, so the shape the typed builder already knew survives `.descriptor` into the store: ```ts const rows = await ctx.store.query(database.notes.where(eq('id', id)).descriptor) rows[0].title   // string — previously `rows[0]['title'] as string` ``` The type was always available; it was dropped at exactly this boundary, which is why reading a field meant casting. One downstream app accumulated 2,032 of those casts against a surface that could have typed them all along. `EffectStore.query` is typed the same way, so an Effect-form handler keeps both the row type and the `StoreError` channel. A hand-built descriptor still resolves to `Row` — this never types less than before, so it is additive: existing code keeps compiling, and the casts it contains simply become redundant. The driver-level `DataStore.query` stays untyped deliberately. It is the SPI every dialect store and transactional view implements, and those genuinely do return untyped rows off the wire; the type is re-applied one layer up, at the handler-facing `FluentStore`.
+
+### Fixed
+
+- **@voltro/runtime, @voltro/cli** — Declarative `guards:` are now re-checked before EVERY subscription delivery, not only when the subscription is opened. A subscription is a long-lived authorization grant, and the scopes that justified it can be withdrawn while it is still open — a role revoked, a resource un-shared, a membership ended. Previously the gate ran once at subscribe and every later delivery re-ran the query and pushed rows out without re-asking, so a revoked subject kept receiving live updates until their socket happened to drop. A denial now ends the subscription with the typed `ScopeError` rather than silently freezing the subscriber on its last authorized value, and the re-check runs BEFORE the read, so a revoked subject's rows are never materialised. Both the descriptor and computed-query paths are covered, in both `voltro dev` and `voltro serve`. Non-authorization failures (a bad predicate, a dropped connection) still leave the subscriber on its last good snapshot as before.
+- **@voltro/testing, @voltro/cli** — - **`@voltro/testing`'s context now provides `ctx.load` / `ctx.loadMany`.** The request-scoped batching helpers were added to the handler context but not to the test harness, so `makeTestContext` no longer satisfied `AppContext` — any suite building a context failed to typecheck, and a handler calling `ctx.load` could not be tested at all. The harness now builds a loader over the same underlying store (one per context, so `withSubject` / `withTenant` can't serve one subject's cached rows to another), mirroring the real builder. - **The `.one()` codemod is declared for 0.5.0, not 0.4.0.** It was authored while 0.4.0 was unreleased; since codemods are selected with `from < version <= to`, leaving it at 0.4.0 would have silently skipped it for everyone upgrading from 0.4.0 — exactly the users who need it.
+
+---
+
 ## [0.4.0] — 2026-07-18
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { AnyCheckSpec } from '@voltro/protocol';
 import { AuthStrategy } from '@voltro/protocol';
 import { CaughtUpVerdict } from '@voltro/database';
 import { ChangeEvent } from '@voltro/database';
@@ -12,7 +13,6 @@ import { DialectReplicationAdapter } from '@voltro/database';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
 import { FieldCipher } from '@voltro/database';
-import { GuardCheckSpec } from '@voltro/protocol';
 import * as http from 'node:http';
 import { HttpClient } from '@effect/platform';
 import { HttpRequestInterceptor } from '@voltro/protocol';
@@ -758,6 +758,28 @@ export declare interface AppContext {
      *  triggers. `emit(name, payload)` records the event and fans out to
      *  matching workflow triggers. */
     readonly events?: EventsAppContext;
+    /**
+     * Transactional outbox (`ctx.outbox`). Absent when the app declares no
+     * `*.outbox.ts` handler — an enqueue with nobody to deliver it would be a
+     * side effect the app believes happened and which never will, so the field
+     * simply isn't there rather than silently accepting writes.
+     */
+    readonly outbox?: OutboxFacade;
+    /**
+     * Request-scoped batching (`ctx.load` / `ctx.loadMany`). Coalesces
+     * same-tick reads of one table into a single `WHERE id IN (...)`.
+     *
+     * For assembly whose SHAPE depends on the data — a tree walk where each
+     * level's ids come from the level above — which `relations()` + `.with()`
+     * cannot express statically. Reach for the relation first; this is the
+     * fallback, not the default.
+     *
+     * Scoped to the request on purpose: a longer-lived cache would serve one
+     * subject's rows to another (a data-isolation bug on a tenant-scoped store,
+     * not a performance detail) and would go stale across a mutation.
+     */
+    readonly load: DataLoader['load'];
+    readonly loadMany: DataLoader['loadMany'];
 }
 
 /**
@@ -911,6 +933,9 @@ export declare interface AttachAnalyticsMirrorOptions {
  */
 export declare const awaitServerListening: (server: ReturnType<typeof createServer>, timeoutMs?: number) => Promise<void>;
 
+/** Exponential backoff with a ceiling — 1s, 2s, 4s … capped at 5 minutes. */
+export declare const backoffMs: (attempt: number) => number;
+
 /**
  * Override the subject for an active connection. Called from the
  * `auth.signin` (or any "I just authenticated this caller") handler
@@ -973,9 +998,17 @@ cache?: {
     readonly swrMs: number | undefined;
     readonly scope: "subject" | "global";
     readonly baseKey: string;
-}) => Stream.Stream<SubscriptionEvent<T>, never, SubjectService | ConnectionInfo>;
+}, 
+/**
+ * Per-subject authorization re-check, built by
+ * `makeQueryReauthorizer(query, input)` in the serve pipeline. Subscribing
+ * passes `guards:` once; this re-runs them before every delivery so a
+ * revoked grant CLOSES the stream rather than continuing to serve it.
+ * Omitted for a query that declares no guards.
+ */
+reauthorize?: (subject: Subject) => () => Promise<unknown>) => Stream.Stream<SubscriptionEvent<T>, never, SubjectService | ConnectionInfo>;
 
-export declare const bindSubscriptionUntyped: (descriptor: QueryDescriptor, dispatcher: Dispatcher, context: RuntimeContext, indexHint: MatcherIndexHint | undefined, label: string, cacheBinding: SnapshotCacheBinding | undefined) => Stream.Stream<SubscriptionEvent<ReadonlyArray<Row_4>>, never, never>;
+export declare const bindSubscriptionUntyped: (descriptor: QueryDescriptor, dispatcher: Dispatcher, context: RuntimeContext, indexHint: MatcherIndexHint | undefined, label: string, cacheBinding: SnapshotCacheBinding | undefined, reauthorize: (() => Promise<unknown>) | undefined) => Stream.Stream<SubscriptionEvent<ReadonlyArray<Row_4>>, never, never>;
 
 export declare interface BrandedScheduleDefinition extends ScheduleDefinition {
     readonly [SCHEDULE_BRAND]: true;
@@ -1295,6 +1328,21 @@ export declare const currentRoutingContext: () => RoutingContext | undefined;
 /** The trace context active on the current async stack, if any. */
 export declare const currentTraceContext: () => LogTraceContext | undefined;
 
+export declare interface DataLoader {
+    /**
+     * Load one row by primary key. Calls made in the same tick for the same
+     * table are coalesced into ONE `WHERE id IN (...)`.
+     *
+     * Returns `null` for a missing row rather than throwing — a loader is used
+     * to assemble, and a missing edge in a graph walk is usually data, not an
+     * error. Use `.one()` when absence IS an error.
+     */
+    load(table: string, id: string): Promise<Row_4 | null>;
+    /** Load many by key, in the order asked. Missing rows come back as `null`,
+     *  so the result lines up positionally with the input. */
+    loadMany(table: string, ids: ReadonlyArray<string>): Promise<ReadonlyArray<Row_4 | null>>;
+}
+
 export { DataStore }
 
 /** DataStore-backed store over `_voltro_api_keys`. */
@@ -1346,6 +1394,16 @@ export declare const defineAggregate: <Row>(input: AggregateDefinitionInput<Row>
 
 export declare const defineEventTrigger: <EventPayload = unknown, WorkflowPayload = EventPayload>(spec: Omit<WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>, "_tag">) => WorkflowEventTriggerDefinition<EventPayload, WorkflowPayload>;
 
+/**
+ * Declare who delivers an effect. One per `*.outbox.ts` file.
+ *
+ * The handler runs AFTER the enqueuing transaction committed, outside it, and
+ * may do external I/O — that is the entire point. It must be IDEMPOTENT:
+ * delivery is at-least-once, so a process that dies between "the remote
+ * accepted it" and "we marked it delivered" will retry.
+ */
+export declare const defineOutboxHandler: (definition: OutboxHandlerDefinition) => OutboxHandlerDefinition;
+
 /** Declare a reaction. Validates that the MANDATORY guard is present — an
  *  ungated reaction is a spend-storm footgun, so this fails LOUD at boot. */
 export declare const defineReaction: (def: ReactionDefinition) => ReactionDefinition;
@@ -1451,7 +1509,26 @@ export declare class Dispatcher {
     /** Snapshot-cache binding (Layer 3). When present AND `deps.cache` is
      *  wired, the initial snapshot is served through the cache, tagged with
      *  the dependent-table set, and kept warm by the recompute path. */
-    cacheBinding?: SnapshotCacheBinding): Promise<() => void>;
+    cacheBinding?: SnapshotCacheBinding, 
+    /** Re-run the query's `guards:` before every delivery — see
+     *  `ActiveSubscription.reauthorize`. Omitted for unguarded queries. */
+    reauthorize?: () => Promise<unknown>): Promise<() => void>;
+    /**
+     * Tear a subscription down because authorization was WITHDRAWN mid-stream,
+     * and tell the client why.
+     *
+     * A denial is not a transient failure, so it must not be handled like one.
+     * The re-query paths deliberately keep a failing subscriber on its last
+     * good snapshot (a bad predicate shouldn't wedge the stream) — but doing
+     * that for a revoked subject would leave authorized data sitting in a
+     * client that is no longer entitled to it, with no signal that anything
+     * changed. Emitting the typed `ScopeError` and closing is the honest
+     * outcome: the client surfaces the denial and can re-subscribe if the
+     * grant comes back.
+     */
+    private revokeSubscription;
+    /** `revokeSubscription` for the computed path. Same reasoning. */
+    private revokeComputed;
     /**
      * Register a COMPUTED-query subscription. The handler already ran once
      * (its value is `computed.value`); we emit that as the initial snapshot,
@@ -1496,6 +1573,31 @@ export declare interface DispatcherDependencies {
     readonly cache?: SnapshotCache;
 }
 
+export declare interface DrainDeps {
+    readonly store: Pick<DataStore, 'query' | 'update'>;
+    readonly handlers: ReadonlyMap<string, OutboxHandlerDefinition>;
+    readonly now?: () => Date;
+    /** Max rows per drain pass. */
+    readonly batchSize?: number;
+}
+
+/**
+ * One drain pass: claim due rows, run their handler, record the outcome.
+ *
+ * A row whose handler is unknown is left PENDING rather than dead-lettered —
+ * the usual cause is a deploy where the enqueuing code shipped before the
+ * handler, and discarding those would turn a rollout ordering detail into
+ * permanent data loss.
+ */
+export declare const drainOutbox: (deps: DrainDeps) => Promise<DrainResult>;
+
+export declare interface DrainResult {
+    readonly delivered: number;
+    readonly failed: number;
+    readonly dead: number;
+    readonly skipped: number;
+}
+
 /**
  * Up to `limit` wakeups that are due now (`wakeAt <= now`), earliest
  * first. Pending rows are read ordered by `wakeAt`, so the earliest —
@@ -1514,7 +1616,11 @@ export declare class EffectStore extends EffectStore_base {
 declare const EffectStore_base: Context.TagClass<EffectStore, "@voltro/EffectStore", EffectStoreOps>;
 
 export declare interface EffectStoreOps {
-    readonly query: (descriptor: QueryDescriptor) => Effect.Effect<ReadonlyArray<Row_4>, StoreError>;
+    /** Typed the same way `FluentStore.query` is — the row type rides in on the
+     *  descriptor, so an Effect-form handler reads real fields instead of
+     *  casting off `Record<string, unknown>`. Falls back to `Row` for a
+     *  hand-built descriptor. */
+    readonly query: <R = Row_4>(descriptor: QueryDescriptor<R>) => Effect.Effect<ReadonlyArray<R>, StoreError>;
     readonly insert: (table: string, row: Row_4) => Effect.Effect<Row_4, StoreError>;
     readonly update: (table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>) => Effect.Effect<Row_4 | null, StoreError>;
     readonly delete: (table: string, primaryKey: string) => Effect.Effect<boolean, StoreError>;
@@ -1530,6 +1636,15 @@ export declare const emptySchemaRegistry: SchemaRegistry;
  *  columns use). Throws if no cipher is registered. */
 export declare const encryptField: (plaintext: string) => string;
 
+export declare interface EnqueueOptions {
+    /** Drop this enqueue if an undelivered row already carries the same key. */
+    readonly idempotencyKey?: string;
+    /** Override the handler's `maxAttempts` for this one effect. */
+    readonly maxAttempts?: number;
+    /** Delay the first attempt (ms from now). */
+    readonly delayMs?: number;
+}
+
 /** The always-available default — reads `process.env`. Sync under the hood,
  *  Promise-wrapped to satisfy the async contract. */
 export declare const envSecretsBackend: SecretsBackend;
@@ -1575,7 +1690,25 @@ export declare interface FieldChange {
  */
 export declare const fingerprintFor: (table: string, predicate: Predicate, indexHint?: string) => string;
 
-export declare interface FluentStore extends Omit<MutationStore, 'update' | 'delete'> {
+export declare interface FluentStore extends Omit<MutationStore, 'update' | 'delete' | 'query'> {
+    /**
+     * Execute a query descriptor and return the matching rows — TYPED.
+     *
+     * The row type rides in on the descriptor (`QueryDescriptor<R>`), so
+     * `ctx.store.query(database.notes.where(...).descriptor)` gives you
+     * `ReadonlyArray<Note>`, not `ReadonlyArray<Record<string, unknown>>`. The
+     * builder always knew the shape; it used to be dropped exactly here, which
+     * is why reading a field meant writing `row['title'] as string` — one
+     * downstream app accumulated 2,032 of those casts.
+     *
+     * A hand-built descriptor still resolves to `Row`, i.e. the previous
+     * behaviour. This never types LESS than before.
+     *
+     * The driver-level `DataStore.query` stays untyped on purpose — it is the
+     * 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>>;
     /** Fluent, scope-applying read builder: `select('notes').where(...).all()`. */
     select(table: string): SelectBuilder;
     /** Fluent predicate update: `update('notes').where('id', id).set({...})`. */
@@ -1655,6 +1788,8 @@ export declare const getResourcePolicy: (resourceType: string) => ResourcePolicy
  *  tap feeds it; the inspect endpoint reads it. */
 export declare const getTimelineRecorder: () => TimelineRecorder;
 
+export declare const getTupleSource: () => TupleSource | undefined;
+
 /** Stable group key from the groupBy column values (JSON to disambiguate types). */
 export declare const groupKeyOf: (row: Row_2, groupBy: ReadonlyArray<string> | undefined) => string;
 
@@ -1858,6 +1993,25 @@ export declare interface InspectStream {
 
 export { inspectWorkflow }
 
+/**
+ * Install the resolver that answers `guards: [{ action, resourceType }]`.
+ *
+ * Called once at boot by both entrypoints. Every denial path is explicit
+ * because each one is a place where a plausible implementation would instead
+ * pass:
+ *
+ *   - unknown resource type → DENY. A guard naming a policy that was never
+ *     registered is a misconfiguration, and a misconfigured authorization
+ *     check must not be a permissive one.
+ *   - no tuple source → DENY. Nothing can answer the question.
+ *   - tuple source throws → DENY, and log it. A database blip must not become
+ *     an open door.
+ *
+ * `can()` itself already handles the `admin:full` bypass, anonymous denial and
+ * cross-tenant denial, so this layer does not re-implement them.
+ */
+export declare const installPolicyGuardResolver: () => void;
+
 /** Fire every registered interrupt for `clientId` (called on disconnect). */
 export declare const interruptConnectionStreams: (clientId: number) => void;
 
@@ -1993,6 +2147,13 @@ export declare const listResourcePolicies: () => ReadonlyArray<ResourcePolicy>;
 
 export { listRetentions }
 
+export declare interface LoaderDeps {
+    readonly store: Pick<DataStore, 'query'>;
+    /** Coalesce window. Loads issued within the same microtask batch together;
+     *  the default (a resolved promise tick) needs no timers. */
+    readonly schedule?: (flush: () => void) => void;
+}
+
 /** Load the tuples for one (subject, resource) — the interceptor's tuple source.
  *  Returns [] for an anonymous subject (→ `can` denies anyway). */
 export declare const loadResourceTuples: (store: DataStore, subjectId: string | null, resourceType: string, resourceId: string) => Promise<ReadonlyArray<RelationTuple>>;
@@ -2123,6 +2284,12 @@ export declare const makeBufferingSpanProcessor: (onSpanEnd: (record: TraceSpanR
  */
 export declare const makeCoordinatedScheduler: (deps: CoordinatedScheduleDeps) => ((name: string, intervalMs: number, effect: () => void | Promise<void>) => CoordinatedScheduleHandle);
 
+/**
+ * Build a request-scoped loader. One instance per AppContext — see the module
+ * header for why this must not be shared across requests.
+ */
+export declare const makeDataLoader: (deps: LoaderDeps) => DataLoader;
+
 /**
  * Build the Layer that provides `EffectStore` from a `MutationStore`.
  * dev.ts (CLI) and any standalone test setup uses this to wire up the
@@ -2168,6 +2335,8 @@ export declare const makeLazyWorkflowFacade: (resolve: () => WorkflowsAppContext
  */
 export declare const makeMutationRunner: (deps: MutationRunnerDeps) => (mutation: MutationLike, input: unknown, requestContext: ServeRequestContext) => Promise<unknown>;
 
+export declare const makeOutboxFacade: (deps: OutboxFacadeDeps) => OutboxFacade;
+
 export declare const makePostCommitWorkflowFacade: (base: WorkflowsAppContext, afterCommit: (work: () => Promise<unknown>) => void) => WorkflowsAppContext;
 
 /**
@@ -2188,6 +2357,27 @@ 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>;
 
+/**
+ * Build the per-subscription authorization re-check.
+ *
+ * `guards:` are enforced once when a subscription is opened. That is not
+ * enough on its own: a subscription is a LONG-LIVED grant, and the scopes
+ * that justified it can be withdrawn while it is still open (a role
+ * revoked, a resource un-shared, a membership ended). Without a re-check
+ * the socket keeps delivering rows the subject may no longer read until
+ * the client happens to disconnect.
+ *
+ * So every delivery re-runs the same `checkGuardsEffect` the subscribe-time
+ * gate ran — including the async resource-scope resolver, which is where a
+ * per-row/per-team revocation actually shows up. Returns `null` when the
+ * subject still passes, or the typed `ScopeError` that denied it.
+ *
+ * Returns a closure that always resolves `null` when the descriptor carries
+ * no guards, so the caller needs no branch and an unguarded query pays only
+ * a resolved promise.
+ */
+export declare const makeQueryReauthorizer: (query: MutationLike, input: unknown) => (subject: Subject) => () => Promise<unknown>;
+
 export declare const makeRouterActivity: () => RouterActivity;
 
 /**
@@ -2366,7 +2556,7 @@ export declare interface MutationLike {
     readonly descriptor: {
         readonly name: string;
         readonly source?: string | ReadonlyArray<string> | undefined;
-        readonly guards?: ReadonlyArray<GuardCheckSpec> | undefined;
+        readonly guards?: ReadonlyArray<AnyCheckSpec> | undefined;
     };
     executor(input: unknown, ctx: unknown): unknown;
 }
@@ -2495,14 +2685,25 @@ export declare const noopAnalyticsSpec: AnalyticsSinkSpec;
  *  misses, writes are dropped. Mirrors the cache's `noopCache`. */
 export declare const noopKv: AsyncKv;
 
-/** Thrown by `.one()` when a query that must match exactly one row found
- *  none. Distinct from a found-but-wrong row — this is strictly "0 rows". */
-export declare class NoRowFound extends Error {
-    readonly table: string;
-    readonly _tag = "NoRowFound";
-    constructor(table: string);
+/**
+ * `.one()` matched a number of rows other than exactly one.
+ *
+ * `found` distinguishes the two failure modes without a second error type:
+ * `0` is "the row you required is missing", `2` is "your filter is not as
+ * unique as you assumed" (the terminal probes with LIMIT 2, so `2` means
+ * "at least two" — it never counts the whole set just to report a number).
+ */
+export declare class NoRowFound extends NoRowFound_base {
+    get message(): string;
 }
 
+declare const NoRowFound_base: Schema.TaggedErrorClass<NoRowFound, "NoRowFound", {
+    readonly _tag: Schema.tag<"NoRowFound">;
+} & {
+    table: typeof Schema.String;
+    found: typeof Schema.Number;
+}>;
+
 export declare interface Notification {
     readonly subscriberId: string;
     readonly fingerprint: string;
@@ -2520,13 +2721,17 @@ export declare const onBindConnectionSubject: (listener: (clientId: number, subj
 
 /** Thrown by `.expectVersion(n).set(...)` when the optimistic-lock guard
  *  matched no row (the row was concurrently updated or deleted). */
-export declare class OptimisticLockError extends Error {
-    readonly table: string;
-    readonly expected: number;
-    readonly _tag = "OptimisticLockError";
-    constructor(table: string, expected: number);
+export declare class OptimisticLockError extends OptimisticLockError_base {
+    get message(): string;
 }
 
+declare const OptimisticLockError_base: Schema.TaggedErrorClass<OptimisticLockError, "OptimisticLockError", {
+    readonly _tag: Schema.tag<"OptimisticLockError">;
+} & {
+    table: typeof Schema.String;
+    expected: typeof Schema.Number;
+}>;
+
 export declare interface OrchestratorTickDeps {
     readonly store: DataStore;
     readonly supervisor: AppSupervisor;
@@ -2537,6 +2742,51 @@ export declare interface OrchestratorTickDeps {
     readonly log?: WakeOrchestratorLogger;
 }
 
+export declare const OUTBOX_TABLE = "_voltro_outbox";
+
+export declare interface OutboxFacade {
+    /**
+     * Persist the intent to run `effect` after this transaction commits.
+     *
+     * Returns the outbox row id, which doubles as the delivery id a client can
+     * watch to render external-side-effect progress ("saving… syncing… synced").
+     */
+    enqueue(effect: string, payload: Record<string, unknown>, options?: EnqueueOptions): Promise<string>;
+}
+
+export declare interface OutboxFacadeDeps {
+    /** The REQUEST's store. Inside a mutation this is the transactional view —
+     *  which is what makes the enqueue atomic with the domain write. */
+    readonly store: Pick<DataStore, 'insert' | 'query'>;
+    readonly subject: Subject;
+    readonly traceId: string | null;
+    /** Nudge the drain worker once the transaction commits. Optional: without
+     *  it the row still delivers on the next poll tick, just later. */
+    readonly afterCommit?: (work: () => Promise<unknown>) => void;
+    /** Wake the drain loop. */
+    readonly nudge?: () => void;
+    readonly now?: () => Date;
+}
+
+export declare interface OutboxHandlerContext {
+    readonly payload: Record<string, unknown>;
+    readonly attempt: number;
+    readonly subjectId: string | null;
+    readonly tenantId: string | null;
+    readonly traceId: string | null;
+}
+
+export declare interface OutboxHandlerDefinition {
+    readonly effect: string;
+    readonly handler: (ctx: OutboxHandlerContext) => Promise<unknown>;
+    /** Give up after this many attempts, then dead-letter. Default 8. */
+    readonly maxAttempts?: number;
+}
+
+export declare type OutboxStatus = 'pending' | 'delivering' | 'delivered' | 'dead';
+
+export declare const outboxTable: TableLike;
+
 declare interface P2COptions {
     /**
      * Random selector — `Math.random()` by default. Tests inject a
@@ -3882,7 +4132,17 @@ export declare class SelectBuilder {
     maybeOne(): Promise<Row_4 | null>;
     /** Alias of `maybeOne` — the first row or `null`. */
     first(): Promise<Row_4 | null>;
-    /** Terminal: exactly one row; throws `NoRowFound` on zero matches. */
+    /**
+     * Terminal: EXACTLY one row. Fails with `NoRowFound` on zero matches —
+     * and equally on two or more.
+     *
+     * The over-fetch to LIMIT 2 is deliberate. A `LIMIT 1` probe cannot tell
+     * "the one row you meant" from "the first of several", so a filter that
+     * silently stopped being unique would keep returning an arbitrary row and
+     * the bug would surface far away from its cause. One extra row on the
+     * wire buys a loud failure at the point the assumption breaks. Use
+     * `.first()` / `.maybeOne()` when you genuinely want "any match".
+     */
     one(): Promise<Row_4>;
     /** Terminal: COUNT(*) of matching rows (real aggregate, not a fetch). */
     count(): Promise<number>;
@@ -3922,6 +4182,14 @@ export declare const setSystemStoreHandle: (handle: SystemStoreHandle) => void;
 /** Test seam — swap (or reset with `undefined`) the process recorder. */
 export declare const setTimelineRecorderForTest: (recorder: TimelineRecorder | undefined) => void;
 
+/**
+ * Register (or clear) the process-global tuple source. Last write wins.
+ *
+ * Registering a source is what ACTIVATES relationship guards. Until then they
+ * deny — see `installPolicyGuardResolver`.
+ */
+export declare const setTupleSource: (source: TupleSource | undefined) => void;
+
 export declare const sha256Hex: (input: string) => string;
 
 export declare type ShapeClassification = {
@@ -4492,6 +4760,20 @@ export declare const triggerWorkflow: <EventPayload = unknown, WorkflowPayload =
  */
 export declare const tryClaimWakeup: (store: DataStore, ref: WakeupRef) => Promise<boolean>;
 
+/**
+ * Reads the relationship tuples for one (subject, resource).
+ *
+ * Registered once at boot. The default implementation reads
+ * `_voltro_rebac_tuples`; an app whose relationships live in its own tables
+ * (a `teamMembers` row, say) registers its own instead of copying data into a
+ * framework table.
+ */
+export declare type TupleSource = (req: {
+    readonly subjectId: string | null;
+    readonly resourceType: string;
+    readonly resourceId: string;
+}) => Promise<ReadonlyArray<RelationTuple>> | ReadonlyArray<RelationTuple>;
+
 /**
  * Remove the override for a connection. Called by the WS-close
  * finalizer (or explicit logout flows). Idempotent.