@voltro/runtime 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -39,6 +39,56 @@ _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
+
+- **@voltro/protocol, @voltro/plugin-rbac, @voltro/runtime** — **Resource-aware declarative guards + one denial tag.** `guards: [{ scope, resource }]` now actually scopes to a resource. Register a resolver — either `setResourceScopeResolver((req) => Effect<boolean>)` from `@voltro/protocol`, or `rbacPlugin({ resolveResourceRoles: (subject, resourceId) => roleSlugs })` — and the framework asks it, per request, whether the caller holds the scope **on the extracted resource** (a team, workspace, document), before the executor runs (mutations: before the transaction opens). A globally-held scope or `admin:full` still short-circuits without a resolver call; a resolver error fails **closed**. With no resolver registered, `resource` stays advisory (global check) exactly as before, so single-tenant apps are unaffected. **BREAKING — `@voltro/plugin-rbac` no longer exports `Forbidden`.** rbac's `permission()` / `assertPermission()` / `anyPermission()` now fail with protocol's `ScopeError` — the SAME typed error the declarative `guards:` enforcement already raised. One denial tag across the framework: a client that matches `_tag === 'ScopeError'` (or `errorTag(err)`) recognizes both a descriptor-guard denial and a `permission()` denial with one branch. The `@voltro/plugin-rbac/errors` subpath is removed. Migration (the `voltro update` codemod rewrites the mechanical part): - `import { Forbidden } from '@voltro/plugin-rbac/errors'` →   `import { ScopeError } from '@voltro/protocol'`; `import { Forbidden } from '@voltro/plugin-rbac'` →   `import { ScopeError } from '@voltro/plugin-rbac'` (re-exported from the root). - Every `Forbidden` identifier → `ScopeError` (incl. `error: Forbidden` on a descriptor). - By hand: a constructed `new Forbidden({ required, reason })` becomes   `new ScopeError({ required, message })` (the field is `message` and is   REQUIRED); and any `Effect.catchTag('Forbidden', …)` / `err._tag === 'Forbidden'`   string becomes `'ScopeError'`. Guards are normally caught, not constructed, so   most apps only need the import rewrite the codemod does. Also note: `requireScope` / declarative `guards:` enforcement is now async-capable (it awaits the resource resolver when one is registered) — no change to handler code, which never called the internal enforcement directly.
+- **@voltro/client, @voltro/plugin-rbac** — **`@voltro/plugin-rbac/web` is removed — the UI permission gate lives in `@voltro/client`.** The framework shipped `useCan` TWICE, with the same name and the same semantics, over two different React contexts. An app that mounted `<PermissionProvider>` and imported the plugin's `useCan` got an empty scope set and silently hid every gated affordance — no error, just a UI where nothing is permitted. One of the two had to go. `@voltro/client` survives because scopes are a FRAMEWORK concept: `@voltro/protocol` owns `ScopeError`, `guards: [{ scope }]` and `ctx.access`, and rbac is only one way to PRODUCE scopes — an app can register its own `setResourceScopeResolver` over its own tables and never install the plugin. The hook consumes scopes, which is generic; producing them is rbac-specific. Keeping the hook behind the plugin would force an rbac dependency on apps that deliberately don't use rbac, purely to gate a button. `@voltro/plugin-rbac` keeps everything that IS rbac: the roles map, role→scope compilation, the `permission()` / `assertPermission()` / `anyPermission()` server guards, the role tables, and `resolveResourceRoles`. The codemod rewrites every mechanical site: `RbacScopeProvider` → `PermissionProvider`, `canFromScopes` → `canCall`, `canAnyFromScopes` → `canCallAny`, and repoints `useCan` / `useCanAny` / `ADMIN_SCOPE` to `@voltro/client`. A raw `useContext(RbacScopeContext)` is ANNOTATED rather than rewritten — the client equivalent is `usePermissions()`, which returns `{ scopes }` instead of the bare array, so a silent rewrite would compile and then hand back the wrong shape.
+
+### Added
+
+- **@voltro/runtime, @voltro/cli** — **`read({ where })` on aggregates.** Aggregate reads were all-or-nothing, so every consumer that wanted one slice pulled the whole materialised set over the wire and filtered in the component — the cost scaling with the aggregate, not the slice. `where` entries are ANDed; a scalar means strict equality, an array means IN; filtering runs before `orderBy`/`limit`. Deliberately a data filter over already materialised rows, not a predicate language — aggregates stay aggregates.
+- **@voltro/client** — **Two ergonomics that remove the two most-repeated shapes in a Voltro frontend.** - **`mutate(input, options)` — `onSuccess` / `onError` / `notify`.** Every write   site used to re-type `try { await mutate() } catch { toast.error(…) } finally   { setSubmitting(false) }`. `pending` already replaced the `finally`; these   replace the rest. Load-bearing semantic: supplying an error handler (`onError`   or `notify.error`) marks the failure HANDLED — `mutate` resolves with   `undefined` instead of rejecting, which is what actually deletes the try/catch.   With no handler it rejects exactly as before, so unhandled failures stay loud.   `notify` routes to an app-registered sink (`setMutationNotifier`) — the   framework stays unbound to any toast library. - **`useSubscription` now returns `loading` and `isEmpty`, and accepts   `fallback`.** Call sites branched on `data === undefined`, conflating "no   snapshot yet" with "zero rows" — the cause of a flash of empty-state before the   first snapshot. They are now distinct, derived once. `fallback` fills `data`   while loading without lying about `loading`. Also documented: `error` carries a   COLD-START stream failure (check it to avoid an infinite skeleton); a failure   after data arrived deliberately does not blank good data — those reach the   error bus (`useOnRpcError`).
+- **@voltro/cli** — **Make the client hook surface discoverable — and keep it that way.** A downstream app built its whole frontend on three transport hooks (`useSubscription` / `useMutation` / `useAction`) and hand-rolled forms, tables, upload, permission gates, debounce and pagination, because the agent guide documented ~none of the ~40 client hooks that already ship. Three changes: - **The always-loaded core now carries a "Pick the CLIENT primitive" rubric** —   the same decision-rubric treatment the backend primitives get, plus a   "you're about to write X → reach for Y" table (per-field `useState` →   `useFormBinding`, hand-rolled table → `useDataTable`, `FileReader` → `useUpload`,   `useMemo` fan-in → `useDerived`, …). - **The hook reference is complete.** `reference/hooks-overview.md` presented   itself as "the client-side hook surface" while documenting 13 of 44 hooks; it   now enumerates the schema-driven-UI, files/permissions/utilities, and AI   families (en + de). - **A coverage GATE** (`agentsMdTemplate.test.ts`): every exported `use*` hook of   `@voltro/client` must appear in the composed agent-docs corpus, or the test   fails with the list. Docs can no longer silently fall behind the export surface. Plus **`voltro doctor` now flags hand-rolls**: it scans an app's source for the patterns a shipped primitive covers (hand-rolled form/table, `FileReader` upload, `setTimeout` debounce, `useMemo` fan-in, local Next.js compat shims, hand-rolled presence) and names the primitive to use. Advisory, never fatal — a false-positive lecture must not fail a build.
+- **@voltro/cli** — **Generated `matchError` / `AppError` / `AppErrorTag`.** Codegen now emits a per-app exhaustive error matcher into `rpcGroup.generated.ts`, derived BY REFERENCE from every descriptor's `error:` schema plus the cross-cutting plugin errors. `matchError(err, { [tag]: handler }, fallback?)` dispatches on `_tag` with the handler keys constrained to the app's ACTUAL error tags — so a hand-maintained tag list that silently drifts (dead/renamed tags) is gone; a stale tag is a compile error. Browser-safe (reads `_tag` structurally, no runtime dep). Workflows keep their existing `WorkflowErrors`.
+- **@voltro/cli** — **`voltro doctor` + `voltro update --codemods-only`/`--from`** — two upgrade-path ergonomics from AWB adoption feedback: - **`voltro doctor [app]`** (and **`voltro serve --preflight`**) preflights an API   app for production serve: it verifies the precompiled serve bundle exists and,   if not, prints the exact fix and exits 1 — so a Dockerfile / CI step catches   "prod `voltro serve` with no `voltro build`" at BUILD time instead of at   cold-start (0.3.0 made an unbuilt production serve fatal). - **`voltro update --codemods-only` (alias `--run-codemods`) + `--from <version>`**   — re-apply the codemods + manual notes for an explicit `[from, to]` delta   WITHOUT bumping `package.json` or installing. The recovery path for a hand-edited   version bump (`bump package.json` + install first), which otherwise makes   `voltro update` report "already on X — nothing to do" and silently skip the   codemods. `--from` also overrides the auto-detected source version on a normal   update.
+- **@voltro/runtime** — **`encryptField` / `decryptField` — standalone field cipher for raw-SQL paths.** `.encrypted()` columns encrypt/decrypt transparently inside the `ctx.store` middleware, so a code path that reaches the DB by RAW SQL (an auth strategy with no store handle reading/writing a session token, a one-off backfill) bypasses it. `@voltro/runtime` now exposes the SAME registered cipher standalone: `encryptField` encrypts a value; `decryptField` decrypts an `enc:v1:…` value and passes a non-ciphertext value through unchanged (so a raw-SQL path can adopt encryption while pre-existing plaintext rows keep working). Both throw a clear error when no cipher is registered. Encryption stops being all-or-nothing tied to going through `ctx.store`.
+- **@voltro/testing** — **`makeVoltroTestClient` — the missing half of the test story.** The framework shipped a strong BACKEND test story (`makeTestContext`, `mockStore`, `mockAi`, the workflow runner) and nothing for the client. A Voltro frontend is a reactive-data app: with no way to render a component against mocked `useSubscription` / `useMutation` — and to inject a loading state, a stream error, or a failing write — it is structurally untestable, which is why real apps end up with zero frontend tests. `import { makeVoltroTestClient } from '@voltro/testing/client'` returns a `Provider` plus `setSubscription` / `failSubscription` / `resetSubscription` and a `calls` log of every write with its input. A tag ABSENT from the fixture stays in the loading state — the distinction from an empty result is exactly what you want to assert. Deliberately NOT a renderer: it hands you a Provider, so it works with `react-dom/client` + `act`, testing-library, or your own harness, and locks you into none of them.
+- **@voltro/i18n** — **Plurals, Intl formatters, and catalogs a bundler can actually split.** - **`plural(locale, count, forms)` + `usePlural`** — real CLDR categories via   `Intl.PluralRules`. Replaces the hardcoded `"{count} epic(s)"` pattern, whose   literal `(s)` is simply wrong outside English, and which cannot express   languages that distinguish few from many (Polish 2–4 vs 5+). An explicit `zero`   form is honoured for exactly 0; ordinals via `{ type: 'ordinal' }`. - **`useFormatDate` / `useRelativeTime` / `useFormatNumber` / `useFormatCurrency`   / `useFormatters`** — locale-bound `Intl` wrappers, so an app stops carrying   several divergent hand-rolled "X minutes ago" helpers that each round   differently. - **`defineCatalogs` + `LazyI18nProvider`** — code-split catalogs.   `pickCatalog({ en, de })` is a STATIC import map: every locale is a value-level   import, so the bundler must emit them in one chunk and a German-only visitor   downloads English too, growing linearly per locale. A map of `() => import()`   loaders is the only shape a bundler treats as a chunk boundary. `preload(locale)`   before hydration keeps first paint synchronous via `peek()`; the provider's   `fallback` is for a locale SWITCH, not first paint. Unknown locales degrade to   the base catalog, and a failed chunk load stays retryable.
+- **@voltro/protocol, @voltro/client** — **Nested optimistic: `shapeItem` + bulk (multi-item) targets.** Two additive improvements to path-targeted auto-optimistic: - **`shapeItem`** — the nested counterpart of `shape`, typed to the ITEM of the   nested array (not the mutation's output), so a path-target patch reads/returns   the item without casting `current`. (Previously the nested shaper was the flat   `shape`, pinned to the output row — every adopter had to cast. `shape` stays   bound to the output for flat targets; a single field can't be both, so the   nested shaper is its own.) - **Bulk `identify`** — a target's `identify` may now return `string[]` to   patch/delete MANY items (or top-level rows) in one mutation — the group-drag /   batch-edit case where per-item parallel writes used to race. Each patched item   keeps its own key. Runtime-compatible: a nested target that still uses `shape` falls back transparently. No codemod — additive.
+- **@voltro/web, @voltro/client** — **Two hooks apps kept hand-rolling, because nothing shipped them.** - **`useTheme` (`@voltro/web`)** — returns `{ theme, resolvedTheme, setTheme }`   over the framework's own `voltro:theme` cookie and the `html.dark` class. The   bug it removes is specific: an app that hand-rolls a second theme store ends up   with two writers on one class, so the toggle's state and the rendered theme can   disagree, and the pre-paint script flashes the wrong one. `'system'` resolves   through `matchMedia` and tracks live OS changes. - **`useConnectionStatus` (`@voltro/client`)** — `'connected' | 'degraded' |   'offline'`, derived from the only two signals the client honestly has:   `navigator.onLine` (browser says the network is gone) and the rpc error bus (a   call actually failed). `degraded` means "we saw a failure and no success since";   coming back online clears it, because the failures counted during an offline   window ARE that window. Deliberately no polling ping just to colour an   indicator.
+- **@voltro/database** — **`.uniqueActive([cols])` now works on mysql / mariadb** (it previously failed loud at migrate — those engines have no partial index). It lowers automatically to a STORED generated column per key column — `CASE WHEN <predicate> THEN CAST(<col> AS CHAR(255)) ELSE NULL END` — plus a UNIQUE over them. NULL-distinct uniqueness means a soft-deleted row's generated columns are all NULL and never collide, so re-creating the key just works — the same resurrection-safe semantics the partial index gives on postgres/sqlite/mssql. The lowering is applied identically on the emit side and the declared-snapshot side, so it round-trips through the declarative differ (verified live on MariaDB: declare→migrate→introspect→re-plan is a no-diff, and a duplicate among active rows is rejected while soft-deleting one frees the key). You write the same `.uniqueActive([...])` on every dialect.
+
+### Fixed
+
+- **@voltro/cli** — **Standalone `voltro codegen` now emits the SAME `rpcGroup.generated.ts` as `voltro dev` / `voltro build`.** Previously the standalone command skipped the app's plugins, so it dropped every plugin's cross-cutting error union AND its client RPC routes — an inconsistent generated file (typed plugin errors gone, plugin route tags unresolved) vs the dev/serve boot path. The command now loads `app.config` and gathers the plugins' codegen inputs through the SAME `gatherCodegenPluginImports` the boot path uses (single-sourced, so the three paths can't drift).
+- **@voltro/cli** — **The hook-coverage gate was too weak, and it let dead documentation through.** It asked only whether a hook's NAME appeared in the agent-docs corpus — which a one-line row in a link table satisfies. Ten client hooks had exactly that, and six of those rows linked to a page that never mentions the hook, so a reader following the link learned nothing. Two sharper checks replace it: - **Substance** (`agentsMdTemplate.test.ts`): a hook must appear at least once   OUTSIDE a table row, so a bare row no longer counts as documentation. - **Dead references** (`gen-agent-docs.mjs`): a row promising `[`useX`](/docs/…)`   must point at a page that actually mentions `useX`. This lives in the generator   because that is the only thing which reads the docs tree — and it walks BOTH   language trees, since an en-only check leaves every German dead link invisible.
+- **@voltro/cli** — - **Serve bundle: inline the pure-JS SQL drivers (`pg`/`mysql2`/`tedious`) instead of runtime-shimming them.** A production `voltro serve` with a postgres/mysql/mssql store crashed at boot with `Pg.Pool is not a constructor` (and the mysql/mssql equivalents): the driver's `@effect/sql-*` consumer links its leaf as a namespace (`import * as Pg from 'pg'; new Pg.Pool()`), but the native-leaf CJS shim (`module.exports = <leaf>`) did not surface the named members through esbuild's `import * as` interop, so `Pg.Pool` was `undefined`. These drivers are pure JS (no `.node`), so they are now inlined into the serve bundle like the rest of the framework — esbuild links the real module and the namespace resolves correctly. Only genuinely-native leaves (`better-sqlite3`, the turso/libsql addons, `pg-native`) and the dynamically-imported `ioredis`/`nodemailer` still resolve via the runtime shim. Verified end-to-end from a relocated prod tree (a real `POST /rpc` through the inlined `pg`).
+
+---
+
 ## [0.3.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';
@@ -341,6 +341,23 @@ export declare interface AggregateQuery {
 }
 
 export declare interface AggregateReadOptions {
+    /**
+     * Filter the materialized rows — the PARAMETERIZED read.
+     *
+     * Without it an aggregate can only ever be "the one global roll-up", so every
+     * tenant-/team-/year-scoped roll-up (most real ones) has to stay client-side.
+     * A row matches when EVERY entry matches: a scalar compares by strict
+     * equality, an array means "one of" (an IN set).
+     *
+     * ```ts
+     * yield* handle.read({ where: { teamId, year: 2026 } })
+     * yield* handle.read({ where: { status: ['open', 'blocked'] } })
+     * ```
+     *
+     * Deliberately DATA, not a predicate function: it stays serializable, so the
+     * filter can later push down to SQL instead of filtering in memory.
+     */
+    readonly where?: Readonly<Record<string, unknown>>;
     /** Reject if last refresh is older than this. Throws `AggregateStale`. */
     readonly maxAgeMs?: number;
     /** Pagination — max rows to return. */
@@ -741,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'];
 }
 
 /**
@@ -894,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
@@ -956,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;
@@ -1278,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`. */
@@ -1288,6 +1353,13 @@ export declare const dataStoreIdempotencyStore: (store: DataStore) => Idempotenc
 /** Build a durable `KvStoreShape` over a raw `DataStore`. */
 export declare const dataStoreKvStore: (store: DataStore) => KvStoreShape;
 
+/** 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
+ *  rows keep working until they're re-written encrypted. Throws only when no
+ *  cipher is registered (a genuine ciphertext with a wrong key throws GCM). */
+export declare const decryptField: (value: string) => string;
+
 /** Default `POST /rpc` body cap: 8 MiB. Generous for any JSON rpc envelope,
  *  small enough to stop a pathological body being buffered into memory. */
 export declare const DEFAULT_MAX_RPC_BODY_BYTES: number;
@@ -1322,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;
@@ -1427,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,
@@ -1472,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 —
@@ -1490,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>;
@@ -1502,6 +1632,19 @@ export declare interface EffectStoreOps {
  *  discovered tables. */
 export declare const emptySchemaRegistry: SchemaRegistry;
 
+/** Encrypt a value with the registered field cipher (same one `.encrypted()`
+ *  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;
@@ -1547,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({...})`. */
@@ -1627,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;
 
@@ -1830,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;
 
@@ -1965,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>>;
@@ -2095,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
@@ -2140,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;
 
 /**
@@ -2160,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;
 
 /**
@@ -2338,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;
 }
@@ -2467,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;
@@ -2492,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;
@@ -2509,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
@@ -3854,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>;
@@ -3894,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 = {
@@ -4464,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.