@voltro/protocol 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

@@ -29,6 +29,12 @@ export declare const ADMIN_SCOPE = "admin:full";
 
 export declare const anonymousSubject: (tenantId: string | null) => Subject;
 
+/** A guard entry is either a scope check or a relationship check. */
+export declare type AnyCheckSpec = GuardCheckSpec | PolicyCheckSpec;
+
+/** A guard is either a scope check or a relationship check. */
+export declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input>;
+
 /**
  * Apply a `RowPatch` to `prev`, producing `next`. Exact inverse of
  * `diffRows`: `applyRowPatch(prev, diffRows(prev, next))` deep-equals
@@ -171,7 +177,24 @@ export declare const checkFrameworkCompat: (pluginName: string, range: string |
  * mutations, before the transaction opens). The `admin:full` bypass passes
  * everything.
  */
-export declare const checkGuards: (subject: Subject, guards: ReadonlyArray<GuardCheckSpec> | undefined) => ScopeError | null;
+export declare const checkGuards: (subject: Subject, guards: ReadonlyArray<AnyCheckSpec> | undefined) => ScopeError | null;
+
+/**
+ * The resource-aware counterpart of `checkGuards`. Identical semantics when no
+ * resource-scope resolver is registered (or no guard carries a `resource`
+ * extractor) — it delegates to the pure `checkGuards` and succeeds/denies
+ * exactly the same, allocation-light. When BOTH a resolver is registered AND a
+ * guard has a `resource`, it extracts the resource id from `input` and asks the
+ * resolver whether the caller holds each scope on THAT resource. A globally-held
+ * scope (or the `admin:full` bypass) still satisfies without a resolver call;
+ * only the gap ("no global grant") falls through to the resolver. A failed
+ * resolver Effect is treated as a denial (fail-closed).
+ *
+ * Returns a typed `ScopeError` naming the first unmet scope, or `null` when
+ * every guard passes. The runtime calls this in the dispatch spine BEFORE the
+ * executor (mutations: before the transaction opens).
+ */
+export declare const checkGuardsEffect: (subject: Subject, guards: ReadonlyArray<AnyCheckSpec> | undefined, input: unknown) => Effect.Effect<ScopeError | null>;
 
 export declare interface ClientDescriptor {
     readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'workflow';
@@ -202,7 +225,7 @@ export declare interface ClientTarget {
     readonly op: 'insert' | 'update' | 'delete';
     readonly order?: 'prepend' | 'append' | undefined;
     readonly shape?: ((input: Record<string, unknown>, optimisticIdOrCurrent?: unknown) => Record<string, unknown>) | undefined;
-    readonly identify?: ((input: Record<string, unknown>) => string) | undefined;
+    readonly identify?: ((input: Record<string, unknown>) => string | ReadonlyArray<string>) | undefined;
     /** Nested/path-targeted optimistic (see `NestedTargetFields`). Carried to the
      *  client so item-level patches into a JSON array / computed value happen
      *  automatically. Functions survive because the codegen references the live
@@ -210,6 +233,10 @@ export declare interface ClientTarget {
     readonly path?: string | undefined;
     readonly by?: string | undefined;
     readonly match?: ((value: unknown, input: Record<string, unknown>) => boolean) | undefined;
+    /** Nested-item shaper (erased). The client uses this instead of `shape` when
+     *  `path` is set. 2nd arg is the optimistic id (insert) or the current item
+     *  (update) — `unknown` here since the erased view spans both; normalize casts. */
+    readonly shapeItem?: ((input: Record<string, unknown>, currentOrOptimisticId: unknown) => Record<string, unknown>) | undefined;
 }
 
 /** Compose multiple strategies into a single resolver function. The
@@ -417,8 +444,9 @@ export declare const defineStream: <const Name extends string, Input extends Sch
 export declare interface DeleteTarget<Input = unknown> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'delete';
-    /** Identify the row to remove. Default: `input.id`. */
-    readonly identify?: ((input: Input) => string) | undefined;
+    /** Identify the row(s) to remove. Default: `input.id`. Return an ARRAY to
+     *  remove MANY rows/items in one mutation. */
+    readonly identify?: ((input: Input) => string | ReadonlyArray<string>) | undefined;
 }
 
 /**
@@ -477,14 +505,28 @@ export declare const failIdempotent: (store: IdempotencyStore, scope: string, ke
 /** Record a completed response for replay. */
 export declare const finishIdempotent: (store: IdempotencyStore, scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
 
+/** The currently-registered policy-guard resolver, or `undefined`. */
+export declare const getPolicyGuardResolver: () => PolicyGuardResolver | undefined;
+
+/** The currently-registered resource-scope resolver, or `undefined`. */
+export declare const getResourceScopeResolver: () => ResourceScopeResolver | undefined;
+
 export declare interface GuardCheckSpec {
     readonly scope: string | ReadonlyArray<string>;
     readonly mode?: 'all' | 'any';
+    /**
+     * PURE `input → resource id` extractor (the erased runtime form of
+     * `GuardSpec.resource`). When present AND a resource-aware resolver is
+     * registered (`setResourceScopeResolver`), the guard is checked against THAT
+     * resource, not just the caller's global scopes. Absent / no resolver →
+     * global-scope check (the extractor is advisory), exactly as before.
+     */
+    readonly resource?: (input: unknown) => string | undefined;
 }
 
 /** One or more declarative guards on a descriptor. All must pass (AND across
  *  entries; `mode` controls AND/OR WITHIN one entry's scope array). */
-export declare type Guards<Input = unknown> = ReadonlyArray<GuardSpec<Input>>;
+export declare type Guards<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input>>;
 
 export declare interface GuardSpec<Input = unknown> {
     /** Required permission scope(s). A single string, or an array combined by
@@ -617,7 +659,7 @@ export declare interface IdempotencyStore {
  *  corrupt the pointer. */
 export declare const idToPath: (id: RowId) => string;
 
-export declare interface InsertTarget<Input = unknown, Row = unknown> extends NestedTargetFields<Input> {
+export declare interface InsertTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'insert';
     readonly order?: 'prepend' | 'append' | undefined;
@@ -635,9 +677,13 @@ export declare interface InsertTarget<Input = unknown, Row = unknown> extends Ne
      *
      * The `optimisticId` parameter is exposed for rare cases where the
      * shape function needs to reference it (e.g., setting a foreign key
-     * on a child row spread in the same optimistic insert).
+     * on a child row spread in the same optimistic insert). For a NESTED
+     * (`path`) insert, use `shapeItem` instead — it is typed to the item.
      */
     readonly shape?: ((input: Input, optimisticId: string) => Omit<Row, 'id' | 'optimistic'>) | undefined;
+    /** NESTED (`path`) insert: build the ITEM to insert, typed to the item (not
+     *  the output). 2nd arg is the optimistic id. */
+    readonly shapeItem?: ((input: Input, optimisticId: string) => Item) | undefined;
 }
 
 /** True when every row in the set carries an `id`. The dispatcher uses
@@ -646,6 +692,12 @@ export declare interface InsertTarget<Input = unknown, Row = unknown> extends Ne
  *  diffed by id and falls back to shipping the full data. */
 export declare const isIdKeyed: (rows: ReadonlyArray<Readonly<Record<string, unknown>>>) => rows is ReadonlyArray<PatchRow>;
 
+/** Runtime narrowing for the relationship variant. */
+export declare const isPolicyCheck: (g: AnyCheckSpec) => g is PolicyCheckSpec;
+
+/** Narrow a guard entry to the relationship variant. */
+export declare const isPolicyGuard: <I>(g: AnyGuardSpec<I>) => g is PolicyGuardSpec<I>;
+
 export declare const isSystemSubject: (subject: Subject) => boolean;
 
 /** In-memory store — the default for single-process dev + the test double. */
@@ -1304,6 +1356,61 @@ export declare interface PluginTemplate {
  */
 export declare type PluginUninstallHook = (ctx: PluginLifecycleContext) => Effect.Effect<void, unknown> | Promise<void> | void;
 
+/** The runtime-erased form of `PolicyGuardSpec` — a relationship check. */
+export declare interface PolicyCheckSpec {
+    readonly action: string;
+    readonly resourceType: string;
+    readonly resource: (input: unknown) => string | undefined;
+}
+
+/** The question the runtime asks a registered policy-guard resolver. */
+export declare interface PolicyGuardRequest {
+    readonly subject: Subject;
+    /** The action named in the resource policy's `actions` map. */
+    readonly action: string;
+    readonly resourceType: string;
+    /** The id the guard's pure `resource` extractor produced. */
+    readonly resourceId: string;
+}
+
+/**
+ * Answers "does `subject` have `action` on `<resourceType>:<resourceId>`".
+ * Registered once at boot via `setPolicyGuardResolver`. A failed Effect is
+ * treated as a DENIAL — a resolver wanting another posture catches its own
+ * errors.
+ */
+export declare type PolicyGuardResolver = (req: PolicyGuardRequest) => Effect.Effect<boolean, unknown>;
+
+/**
+ * A relationship (ReBAC) guard — "may this subject perform ACTION on THIS row?"
+ *
+ * The scope guard above answers "what may this subject do at all"; this answers
+ * "on which row". Both live in the same `guards:` array on purpose, because the
+ * alternative is what apps actually built: a hand-maintained map from rpc tag →
+ * policy rule, installed as an interceptor. That map is FAIL-OPEN BY OMISSION —
+ * add an rpc, forget the entry, and it is silently unguarded. A declaration on
+ * the descriptor cannot be forgotten for an rpc that exists, because it IS the
+ * rpc.
+ *
+ * Browser-safe by the same construction as `GuardSpec`: strings plus a PURE
+ * `resource` extractor. Resolution — reading relationship tuples, applying the
+ * policy's `implies` closure — happens server-side through the registered
+ * policy resolver. With no resolver registered the check FAILS CLOSED: an
+ * unanswerable authorization question is a denial, never a pass.
+ *
+ * Because it is data, the same declaration compiles into the capability
+ * manifest the client reads, so a UI gate and the server check cannot drift.
+ */
+export declare interface PolicyGuardSpec<Input = unknown> {
+    /** The action to authorize, as named in the resource policy's `actions`. */
+    readonly action: string;
+    /** Which registered resource policy governs the check. */
+    readonly resourceType: string;
+    /** PURE `input → resource id`. Returning undefined DENIES — an unidentifiable
+     *  resource is not a reason to skip the check. */
+    readonly resource: (input: Input) => string | undefined;
+}
+
 export declare type ProcedureDescriptor = QueryProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | MutationProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | ActionProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | StreamProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All>;
 
 export declare const PROTOCOL_VERSION: 1;
@@ -1440,6 +1547,25 @@ export declare const queryToRpc: <Name extends string, Input extends Schema.Sche
  *  Checks the EFFECTIVE set so role-derived scopes count. */
 export declare const requireScope: (subject: Subject, scope: string) => Effect.Effect<void, ScopeError>;
 
+/** The question the runtime asks a registered resource-scope resolver. */
+export declare interface ResourceScopeRequest {
+    /** The authenticated caller. */
+    readonly subject: Subject;
+    /** The single scope being checked (guards with a scope array ask once per scope). */
+    readonly scope: string;
+    /** The resource id the guard's `resource` extractor produced (e.g. a teamId). */
+    readonly resource: string;
+}
+
+/**
+ * A process-global resolver that answers "does `subject` hold `scope` on
+ * `resource`". Registered once at boot via `setResourceScopeResolver`. Returns
+ * an Effect so it can read the app's role tables. It should NOT leak errors —
+ * `checkGuardsEffect` treats a failed resolver as a DENIAL (fail-closed), so a
+ * resolver that wants a different posture must catch its own errors.
+ */
+export declare type ResourceScopeResolver = (req: ResourceScopeRequest) => Effect.Effect<boolean, unknown>;
+
 /** The id of a row, addressed in op paths as `/<id>`. */
 export declare type RowId = string | number;
 
@@ -1680,6 +1806,19 @@ export declare type ServerErrorSource = 'rest' | 'aggregate' | 'subscriber' | 'r
  */
 export declare const setEffectiveScopes: (subject: Subject, scopes: ReadonlyArray<string>) => void;
 
+/** Register (or clear) the process-global policy-guard resolver. Last write
+ *  wins. The runtime installs one backed by the resource-policy registry and
+ *  the registered tuple source. */
+export declare const setPolicyGuardResolver: (resolver: PolicyGuardResolver | undefined) => void;
+
+/**
+ * Register (or clear, with `undefined`) the process-global resource-scope
+ * resolver. Call once at boot — from `@voltro/plugin-rbac`'s wiring, or directly
+ * from an app that resolves per-resource permissions against its own tables.
+ * Last write wins.
+ */
+export declare const setResourceScopeResolver: (resolver: ResourceScopeResolver | undefined) => void;
+
 /** A strategy's verdict on a request.
  *  - `matched`: this strategy claims the request; here's the Subject.
  *  - `skip`: not my request (e.g. cookie absent); try next strategy.
@@ -2028,13 +2167,19 @@ export declare const undoRedoDescriptor: MutationProcedureDescriptor<"__voltro.u
     ok: typeof Schema.Boolean;
 }>, Schema.Union<[typeof UndoNotFound, typeof UndoForbidden, typeof UndoConflict]>>;
 
-export declare interface UpdateTarget<Input = unknown, Row = unknown> extends NestedTargetFields<Input> {
+export declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'update';
-    /** Identify the row to patch. Default: `input.id`. */
-    readonly identify?: ((input: Input) => string) | undefined;
-    /** Build the patch. Default: merges input over current. */
+    /** Identify the row(s) to patch. Default: `input.id`. Return an ARRAY to patch
+     *  MANY rows/items in one mutation (a bulk edit — where the per-item
+     *  parallel-write race lived). */
+    readonly identify?: ((input: Input) => string | ReadonlyArray<string>) | undefined;
+    /** Build the patch for a FLAT target (`current` is the OUTPUT row). Default:
+     *  merges input over current. For a NESTED (`path`) target use `shapeItem`. */
     readonly shape?: ((input: Input, current: Row) => Row) | undefined;
+    /** NESTED (`path`) update: build the item patch. `current` is the existing
+     *  ITEM (not the mutation output), so no cast is needed. */
+    readonly shapeItem?: ((input: Input, current: Item) => Item) | undefined;
 }
 
 export declare interface VoltroPlugin {

package/dist/index.js

@@ -1,9 +1,9 @@
-import { a as e, c as t, d as n, f as r, g as i, h as a, i as o, l as s, m as ee, n as te, o as ne, p as re, r as ie, s as ae, t as oe, u as se } from "./serverErrorBus-BrqfEV84.js";
-import { a as ce, c as le, d as ue, f as de, i as fe, l as pe, n as me, o as he, r as ge, s as c, t as _e, u as ve } from "./auth-DCE6m7Bo.js";
-import { Context as ye, Layer as be, Schema as l } from "effect";
+import { S as e, _ as t, a as n, b as r, c as i, d as a, f as o, g as ee, h as te, i as ne, l as s, m as c, n as re, o as ie, p as ae, r as oe, s as se, t as ce, u as le, v as ue, x as de, y as fe } from "./serverErrorBus-XDdIJk0c.js";
+import { a as pe, c as me, d as he, f as ge, i as _e, l as ve, n as ye, o as be, r as xe, s as Se, t as Ce, u as we } from "./auth-DCE6m7Bo.js";
+import { Context as Te, Layer as Ee, Schema as l } from "effect";
 import { Rpc as u } from "@effect/rpc";
 //#region src/rowPatch.ts
-var xe = l.Union(l.String, l.Number), d = l.Record({
+var De = l.Union(l.String, l.Number), d = l.Record({
 	key: l.String,
 	value: l.Unknown
 }).pipe(l.filter((e) => "id" in e, { message: () => "patch row must carry an id" })), f = l.Union(l.Struct({
@@ -19,12 +19,12 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	path: l.String
 })), p = l.Struct({
 	ops: l.Array(f),
-	order: l.Array(xe)
-}), m = (e) => `/${String(e).replace(/~/g, "~0").replace(/\//g, "~1")}`, Se = (e) => (e.startsWith("/") ? e.slice(1) : e).replace(/~1/g, "/").replace(/~0/g, "~"), h = (e) => {
+	order: l.Array(De)
+}), m = (e) => `/${String(e).replace(/~/g, "~0").replace(/\//g, "~1")}`, Oe = (e) => (e.startsWith("/") ? e.slice(1) : e).replace(/~1/g, "/").replace(/~0/g, "~"), h = (e) => {
 	let t = Object.keys(e).sort(), n = {};
 	for (let r of t) n[r] = e[r];
 	return JSON.stringify(n);
-}, Ce = (e, t) => h(e) === h(t), g = (e, t) => {
+}, ke = (e, t) => h(e) === h(t), Ae = (e, t) => {
 	let n = /* @__PURE__ */ new Map();
 	for (let t of e) n.set(t.id, t);
 	let r = [], i = [], a = /* @__PURE__ */ new Set();
@@ -35,7 +35,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 			op: "add",
 			path: m(e.id),
 			value: e
-		}) : Ce(t, e) || r.push({
+		}) : ke(t, e) || r.push({
 			op: "replace",
 			path: m(e.id),
 			value: e
@@ -49,10 +49,10 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 		ops: r,
 		order: i
 	};
-}, we = (e) => e.every((e) => {
+}, je = (e) => e.every((e) => {
 	let t = e.id;
 	return typeof t == "string" || typeof t == "number";
-}), Te = (e, t) => {
+}), Me = (e, t) => {
 	let n = /* @__PURE__ */ new Map();
 	for (let t of e) n.set(t.id, t);
 	for (let e of t.ops) (e.op === "add" || e.op === "replace") && n.set(e.value.id, e.value);
@@ -62,7 +62,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 		t !== void 0 && r.push(t);
 	}
 	return r;
-}, _ = (e) => l.Union(l.Struct({
+}, g = (e) => l.Union(l.Struct({
 	_tag: l.Literal("snapshot"),
 	revision: l.Number,
 	data: e,
@@ -76,7 +76,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	_tag: l.Literal("error"),
 	error: l.Unknown,
 	revision: l.optional(l.Number)
-})), v = (e) => ({
+})), Ne = (e) => e.action !== void 0 && e.resourceType !== void 0, _ = (e) => ({
 	kind: "query",
 	name: e.name,
 	input: e.input,
@@ -87,7 +87,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), y = (e) => ({
+}), v = (e) => ({
 	kind: "mutation",
 	name: e.name,
 	input: e.input,
@@ -97,7 +97,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), b = (e) => ({
+}), y = (e) => ({
 	kind: "action",
 	name: e.name,
 	input: e.input,
@@ -106,7 +106,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), Ee = (e) => ({
+}), b = (e) => ({
 	kind: "stream",
 	name: e.name,
 	input: e.input,
@@ -114,7 +114,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	error: e.error ?? l.Never
 }), x = (e, t) => t && t.length > 0 ? l.Union(e, ...t) : e, S = (e, t) => t && t.length > 0 ? l.Union(e, s) : e, C = (e, t) => u.make(e.name, {
 	payload: e.input,
-	success: _(e.output),
+	success: g(e.output),
 	error: x(S(e.error, e.guards), t),
 	stream: !0
 }), w = (e, t) => u.make(e.name, {
@@ -130,14 +130,14 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	success: e.element,
 	error: x(e.error, t),
 	stream: !0
-}), D = (e) => {
+}), Pe = (e) => {
 	switch (e.kind) {
 		case "query": return C(e);
 		case "mutation": return w(e);
 		case "action": return T(e);
 		case "stream": return E(e);
 	}
-}, De = (e) => {
+}, Fe = (e) => {
 	let t = e.input, n = t === void 0 ? {} : { input: t }, r = e.output, i = r === void 0 ? {} : { output: r };
 	if (e.kind === "query") return {
 		kind: "query",
@@ -174,18 +174,19 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 			..."identify" in e && e.identify !== void 0 ? { identify: e.identify } : {},
 			..."path" in e && e.path !== void 0 ? { path: e.path } : {},
 			..."by" in e && e.by !== void 0 ? { by: e.by } : {},
-			..."match" in e && e.match !== void 0 ? { match: e.match } : {}
+			..."match" in e && e.match !== void 0 ? { match: e.match } : {},
+			..."shapeItem" in e && e.shapeItem !== void 0 ? { shapeItem: e.shapeItem } : {}
 		}))
 	};
-}, Oe = (e) => e, ke = (e) => e, Ae = (e) => {
+}, Ie = (e) => e, Le = (e) => e, Re = (e) => {
 	if (e.length !== 0) return (t, n) => e.reduceRight((e, t) => t(e, n), t);
-}, je = (e, t) => {
-	let n = ye.GenericTag(e);
+}, ze = (e, t) => {
+	let n = Te.GenericTag(e);
 	return {
 		Tag: n,
-		Live: be.succeed(n, t)
+		Live: Ee.succeed(n, t)
 	};
-}, Me = (e, t, n) => {
+}, D = (e, t, n) => {
 	if (!t) return { ok: !0 };
 	let r = O(n);
 	if (!r) return {
@@ -195,7 +196,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	let i = t.trim();
 	if (i === "*" || i === "") return { ok: !0 };
 	let a = i.split(/\s+/).filter((e) => e.length > 0);
-	for (let i of a) if (!Ne(i, r)) return {
+	for (let i of a) if (!Be(i, r)) return {
 		ok: !1,
 		reason: `plugin "${e}" requires framework ${t}, running ${n}`
 	};
@@ -208,7 +209,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 		patch: Number(t[3]),
 		pre: t[4] ?? ""
 	} : null;
-}, k = (e, t) => e.major === t.major ? e.minor === t.minor ? e.patch === t.patch ? e.pre && !t.pre ? -1 : !e.pre && t.pre ? 1 : e.pre && t.pre ? e.pre < t.pre ? -1 : +(e.pre > t.pre) : 0 : e.patch - t.patch : e.minor - t.minor : e.major - t.major, Ne = (e, t) => {
+}, k = (e, t) => e.major === t.major ? e.minor === t.minor ? e.patch === t.patch ? e.pre && !t.pre ? -1 : !e.pre && t.pre ? 1 : e.pre && t.pre ? e.pre < t.pre ? -1 : +(e.pre > t.pre) : 0 : e.patch - t.patch : e.minor - t.minor : e.major - t.major, Be = (e, t) => {
 	if (e === "*") return !0;
 	if (e.startsWith("^")) {
 		let n = O(e.slice(1));
@@ -230,7 +231,7 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	}
 	let r = O(e);
 	return r ? k(t, r) === 0 : !1;
-}, A = l.Literal("running", "succeeded", "failed", "cancelled", "suspended"), j = l.Literal("cancel", "terminate", "abandon"), Pe = l.Struct({
+}, A = l.Literal("running", "succeeded", "failed", "cancelled", "suspended"), j = l.Literal("cancel", "terminate", "abandon"), Ve = l.Struct({
 	id: l.String,
 	workflowName: l.String,
 	executionId: l.String,
@@ -323,49 +324,49 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 	updateId: l.String,
 	completedEventId: l.String,
 	result: l.Unknown
-}), Fe = v({
+}), He = _({
 	name: "__voltro.workflow.run",
 	source: "_voltro_workflow_runs",
 	input: R,
 	output: l.Array(M)
-}), Ie = v({
+}), Ue = _({
 	name: "__voltro.workflow.runs",
 	source: "_voltro_workflow_runs",
 	input: N,
 	output: l.Array(M)
-}), Le = v({
+}), We = _({
 	name: "__voltro.workflow.run.steps",
 	source: "_voltro_workflow_run_steps",
 	input: z,
 	output: l.Array(P)
-}), Re = v({
+}), Ge = _({
 	name: "__voltro.workflow.run.events",
 	source: "_voltro_workflow_run_events",
 	input: z,
 	output: l.Array(F)
-}), ze = v({
+}), Ke = _({
 	name: "__voltro.workflow.domainEvents",
 	source: "_voltro_workflow_events",
 	input: B,
 	output: l.Array(I)
-}), Be = v({
+}), qe = _({
 	name: "__voltro.workflow.event.deliveries",
 	source: "_voltro_workflow_event_deliveries",
 	input: V,
 	output: l.Array(L)
-}), Ve = b({
+}), Je = y({
 	name: "__voltro.workflow.cancel",
 	input: H,
 	output: l.Struct({ ok: l.Boolean })
-}), He = b({
+}), Ye = y({
 	name: "__voltro.workflow.resume",
 	input: H,
 	output: l.Struct({ ok: l.Boolean })
-}), Ue = b({
+}), Xe = y({
 	name: "__voltro.workflow.signal",
 	input: U,
 	output: l.Struct({ eventId: l.String })
-}), We = b({
+}), Ze = y({
 	name: "__voltro.workflow.update",
 	input: W,
 	output: G
@@ -379,24 +380,24 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 }), X = class extends l.TaggedError()("UndoNotFound", { invocationId: l.String }) {}, Z = class extends l.TaggedError()("UndoForbidden", { invocationId: l.String }) {}, Q = class extends l.TaggedError()("UndoConflict", {
 	invocationId: l.String,
 	reason: l.Literal("conflict", "action")
-}) {}, $ = l.Union(X, Z, Q), Ge = v({
+}) {}, $ = l.Union(X, Z, Q), Qe = _({
 	name: K,
 	source: "_voltro_undo_log",
 	input: l.Struct({ limit: l.optional(l.Number) }),
 	output: l.Array(Y)
-}), Ke = y({
+}), $e = v({
 	name: q,
 	input: l.Struct({ invocationId: l.String }),
 	output: l.Struct({ ok: l.Boolean }),
 	error: $
-}), qe = y({
+}), et = v({
 	name: J,
 	input: l.Struct({ invocationId: l.String }),
 	output: l.Struct({ ok: l.Boolean }),
 	error: $
-}), Je = (e) => {
+}), tt = (e) => {
 	let t = e instanceof Date ? e.getTime() : typeof e == "number" ? e : typeof e == "string" ? new Date(e).getTime() : 0;
 	return Number.isNaN(t) ? 0 : t;
-}, Ye = 1;
+}, nt = 1;
 //#endregion
-export { t as ADMIN_SCOPE, _e as AuthMiddleware, me as ConnectionInfo, ge as ConnectionInfoMiddleware, Ye as PROTOCOL_VERSION, s as ScopeError, fe as Subject, ce as SubjectService, q as UNDO_APPLY_TAG, K as UNDO_LOG_TAG, J as UNDO_REDO_TAG, he as Unauthenticated, Q as UndoConflict, Z as UndoForbidden, Y as UndoLogEntry, X as UndoNotFound, H as WorkflowControlInputSchema, I as WorkflowDomainEventRowSchema, B as WorkflowDomainEventsInputSchema, V as WorkflowEventDeliveriesInputSchema, L as WorkflowEventDeliveryRowSchema, j as WorkflowParentClosePolicySchema, F as WorkflowRunEventRowSchema, Pe as WorkflowRunHandleSchema, R as WorkflowRunRefSchema, M as WorkflowRunRowSchema, A as WorkflowRunStatusSchema, P as WorkflowRunStepRowSchema, z as WorkflowRunTableRefSchema, N as WorkflowRunsInputSchema, U as WorkflowSignalInputSchema, W as WorkflowUpdateInputSchema, G as WorkflowUpdateResultSchema, T as actionToRpc, c as anonymousSubject, Te as applyRowPatch, le as assertAuthenticated, ie as beginIdempotent, Me as checkFrameworkCompat, se as checkGuards, pe as composeAuthStrategies, Ae as composeRpcInterceptors, b as defineAction, y as defineMutation, Oe as definePlugin, ke as definePluginRoute, je as definePluginService, v as defineQuery, Ee as defineStream, g as diffRows, n as effectiveScopes, o as failIdempotent, e as finishIdempotent, ve as hasCallbackRoutes, r as hasEffectiveScope, re as hasScope, m as idToPath, ne as idempotencyScope, we as isIdKeyed, ue as isSystemSubject, ae as memoryIdempotencyStore, w as mutationToRpc, De as normalizeDescriptor, Se as pathToId, oe as publishServerError, C as queryToRpc, ee as requireScope, f as rowPatchOpSchema, p as rowPatchSchema, a as setEffectiveScopes, E as streamToRpc, i as subjectScopes, te as subscribeServerErrors, _ as subscriptionEvent, de as systemSubject, D as toRpc, Je as tsMs, Ke as undoApplyDescriptor, Ge as undoLogQueryDescriptor, qe as undoRedoDescriptor, Ve as workflowCancelDescriptor, ze as workflowDomainEventsQueryDescriptor, Be as workflowEventDeliveriesQueryDescriptor, He as workflowResumeDescriptor, Re as workflowRunEventsQueryDescriptor, Fe as workflowRunQueryDescriptor, Le as workflowRunStepsQueryDescriptor, Ie as workflowRunsQueryDescriptor, Ue as workflowSignalDescriptor, We as workflowUpdateDescriptor };
+export { i as ADMIN_SCOPE, Ce as AuthMiddleware, ye as ConnectionInfo, xe as ConnectionInfoMiddleware, nt as PROTOCOL_VERSION, s as ScopeError, _e as Subject, pe as SubjectService, q as UNDO_APPLY_TAG, K as UNDO_LOG_TAG, J as UNDO_REDO_TAG, be as Unauthenticated, Q as UndoConflict, Z as UndoForbidden, Y as UndoLogEntry, X as UndoNotFound, H as WorkflowControlInputSchema, I as WorkflowDomainEventRowSchema, B as WorkflowDomainEventsInputSchema, V as WorkflowEventDeliveriesInputSchema, L as WorkflowEventDeliveryRowSchema, j as WorkflowParentClosePolicySchema, F as WorkflowRunEventRowSchema, Ve as WorkflowRunHandleSchema, R as WorkflowRunRefSchema, M as WorkflowRunRowSchema, A as WorkflowRunStatusSchema, P as WorkflowRunStepRowSchema, z as WorkflowRunTableRefSchema, N as WorkflowRunsInputSchema, U as WorkflowSignalInputSchema, W as WorkflowUpdateInputSchema, G as WorkflowUpdateResultSchema, T as actionToRpc, Se as anonymousSubject, Me as applyRowPatch, me as assertAuthenticated, oe as beginIdempotent, D as checkFrameworkCompat, le as checkGuards, a as checkGuardsEffect, ve as composeAuthStrategies, Re as composeRpcInterceptors, y as defineAction, v as defineMutation, Ie as definePlugin, Le as definePluginRoute, ze as definePluginService, _ as defineQuery, b as defineStream, Ae as diffRows, o as effectiveScopes, ne as failIdempotent, n as finishIdempotent, ae as getPolicyGuardResolver, c as getResourceScopeResolver, we as hasCallbackRoutes, te as hasEffectiveScope, ee as hasScope, m as idToPath, ie as idempotencyScope, je as isIdKeyed, t as isPolicyCheck, Ne as isPolicyGuard, he as isSystemSubject, se as memoryIdempotencyStore, w as mutationToRpc, Fe as normalizeDescriptor, Oe as pathToId, ce as publishServerError, C as queryToRpc, ue as requireScope, f as rowPatchOpSchema, p as rowPatchSchema, fe as setEffectiveScopes, r as setPolicyGuardResolver, de as setResourceScopeResolver, E as streamToRpc, e as subjectScopes, re as subscribeServerErrors, g as subscriptionEvent, ge as systemSubject, Pe as toRpc, tt as tsMs, $e as undoApplyDescriptor, Qe as undoLogQueryDescriptor, et as undoRedoDescriptor, Je as workflowCancelDescriptor, Ke as workflowDomainEventsQueryDescriptor, qe as workflowEventDeliveriesQueryDescriptor, Ye as workflowResumeDescriptor, Ge as workflowRunEventsQueryDescriptor, He as workflowRunQueryDescriptor, We as workflowRunStepsQueryDescriptor, Ue as workflowRunsQueryDescriptor, Xe as workflowSignalDescriptor, Ze as workflowUpdateDescriptor };

package/dist/rest.d.ts

@@ -15,6 +15,9 @@ declare interface ActionProcedureDescriptor<Name extends string, Input extends S
     readonly exposeAsTool: ExposeAsTool | undefined;
 }
 
+/** A guard is either a scope check or a relationship check. */
+declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input>;
+
 /**
  * Project every descriptor carrying a `publicApi` annotation into a REST
  * route, in stable (path) order. The boot layer feeds these straight into
@@ -32,8 +35,9 @@ export declare const defineRestRoute: <I, O>(descriptor: RestRouteDescriptor<I,
 declare interface DeleteTarget<Input = unknown> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'delete';
-    /** Identify the row to remove. Default: `input.id`. */
-    readonly identify?: ((input: Input) => string) | undefined;
+    /** Identify the row(s) to remove. Default: `input.id`. Return an ARRAY to
+     *  remove MANY rows/items in one mutation. */
+    readonly identify?: ((input: Input) => string | ReadonlyArray<string>) | undefined;
 }
 
 /** query→GET, mutation/action→POST, unless the spec overrides. */
@@ -76,7 +80,7 @@ declare interface ExposeAsToolSpec {
 
 /** One or more declarative guards on a descriptor. All must pass (AND across
  *  entries; `mode` controls AND/OR WITHIN one entry's scope array). */
-declare type Guards<Input = unknown> = ReadonlyArray<GuardSpec<Input>>;
+declare type Guards<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input>>;
 
 declare interface GuardSpec<Input = unknown> {
     /** Required permission scope(s). A single string, or an array combined by
@@ -129,7 +133,7 @@ declare interface IdempotencyStore {
     readonly release: (scope: string, key: string) => Promise<void>;
 }
 
-declare interface InsertTarget<Input = unknown, Row = unknown> extends NestedTargetFields<Input> {
+declare interface InsertTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'insert';
     readonly order?: 'prepend' | 'append' | undefined;
@@ -147,9 +151,13 @@ declare interface InsertTarget<Input = unknown, Row = unknown> extends NestedTar
      *
      * The `optimisticId` parameter is exposed for rare cases where the
      * shape function needs to reference it (e.g., setting a foreign key
-     * on a child row spread in the same optimistic insert).
+     * on a child row spread in the same optimistic insert). For a NESTED
+     * (`path`) insert, use `shapeItem` instead — it is typed to the item.
      */
     readonly shape?: ((input: Input, optimisticId: string) => Omit<Row, 'id' | 'optimistic'>) | undefined;
+    /** NESTED (`path`) insert: build the ITEM to insert, typed to the item (not
+     *  the output). 2nd arg is the optimistic id. */
+    readonly shapeItem?: ((input: Input, optimisticId: string) => Item) | undefined;
 }
 
 /** Extract `:name` path params by aligning the route PATTERN with the request
@@ -248,6 +256,36 @@ declare interface PluginHttpRouteResult {
     readonly headers?: Record<string, string>;
 }
 
+/**
+ * A relationship (ReBAC) guard — "may this subject perform ACTION on THIS row?"
+ *
+ * The scope guard above answers "what may this subject do at all"; this answers
+ * "on which row". Both live in the same `guards:` array on purpose, because the
+ * alternative is what apps actually built: a hand-maintained map from rpc tag →
+ * policy rule, installed as an interceptor. That map is FAIL-OPEN BY OMISSION —
+ * add an rpc, forget the entry, and it is silently unguarded. A declaration on
+ * the descriptor cannot be forgotten for an rpc that exists, because it IS the
+ * rpc.
+ *
+ * Browser-safe by the same construction as `GuardSpec`: strings plus a PURE
+ * `resource` extractor. Resolution — reading relationship tuples, applying the
+ * policy's `implies` closure — happens server-side through the registered
+ * policy resolver. With no resolver registered the check FAILS CLOSED: an
+ * unanswerable authorization question is a denial, never a pass.
+ *
+ * Because it is data, the same declaration compiles into the capability
+ * manifest the client reads, so a UI gate and the server check cannot drift.
+ */
+declare interface PolicyGuardSpec<Input = unknown> {
+    /** The action to authorize, as named in the resource policy's `actions`. */
+    readonly action: string;
+    /** Which registered resource policy governs the check. */
+    readonly resourceType: string;
+    /** PURE `input → resource id`. Returning undefined DENIES — an unidentifiable
+     *  resource is not a reason to skip the check. */
+    readonly resource: (input: Input) => string | undefined;
+}
+
 /** A descriptor kind that can be projected to REST (streams are not, in v1). */
 export declare type PublicApiDescriptor = QueryProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | MutationProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | ActionProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All>;
 
@@ -486,13 +524,19 @@ declare type Target<Input = unknown, Row = unknown> = TargetSpec<Input, Row> | R
 
 declare type TargetSpec<Input = unknown, Row = unknown> = InsertTarget<Input, Row> | UpdateTarget<Input, Row> | DeleteTarget<Input>;
 
-declare interface UpdateTarget<Input = unknown, Row = unknown> extends NestedTargetFields<Input> {
+declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'update';
-    /** Identify the row to patch. Default: `input.id`. */
-    readonly identify?: ((input: Input) => string) | undefined;
-    /** Build the patch. Default: merges input over current. */
+    /** Identify the row(s) to patch. Default: `input.id`. Return an ARRAY to patch
+     *  MANY rows/items in one mutation (a bulk edit — where the per-item
+     *  parallel-write race lived). */
+    readonly identify?: ((input: Input) => string | ReadonlyArray<string>) | undefined;
+    /** Build the patch for a FLAT target (`current` is the OUTPUT row). Default:
+     *  merges input over current. For a NESTED (`path`) target use `shapeItem`. */
     readonly shape?: ((input: Input, current: Row) => Row) | undefined;
+    /** NESTED (`path`) update: build the item patch. `current` is the existing
+     *  ITEM (not the mutation output), so no cast is needed. */
+    readonly shapeItem?: ((input: Input, current: Item) => Item) | undefined;
 }
 
 export { }

package/dist/rest.js

@@ -1,4 +1,4 @@
-import { a as e, i as t, o as n, r, t as i } from "./serverErrorBus-BrqfEV84.js";
+import { a as e, i as t, o as n, r, t as i } from "./serverErrorBus-XDdIJk0c.js";
 import { s as a } from "./auth-DCE6m7Bo.js";
 import { Effect as o, Schema as s } from "effect";
 //#region src/publicApi.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The Voltro wire + plugin contract — defineQuery/Mutation/Action/Stream, definePlugin, sessions / JWT / API-keys, and the RPC protocol.",
   "keywords": [
     "voltro",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@effect/sql": "^0.51.1",
-    "@voltro/database": "0.3.0",
+    "@voltro/database": "0.5.0",
     "jose": "^6.2.3"
   },
   "peerDependencies": {