@voltro/protocol 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -39,6 +39,55 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [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
+
+- **@voltro/cli** — `voltro build` precompiles the whole serve path (framework + effect + `@voltro` inlined, app modules as lazy chunks) into a single **serve bundle**, and `voltro serve` boots from it in-process — cutting `serve: ready` from ~1000 ms to ~180 ms (5–6×; the win is larger on a cold scale-to-zero container). The app's declared SQL driver is inlined (only the native leaf like `pg` stays external, resolved at runtime so it survives the deploy relocation). **Production now serves ONLY from the bundle and NEVER transpiles on demand:** the bundle build externalises unresolvable optional peers (e.g. `@react-email/render` behind `@voltro/plugin-mail`) so it always builds; a bundle-build failure is **fatal** (`voltro build` exits non-zero); and an unbuilt production `voltro serve` fails loud instead of falling back to tsx. The build toolchain (`tsx`, `esbuild`, `vite`, `@vitejs/plugin-react`, `@tailwindcss/vite` + their native tree: rolldown/lightningcss/postcss/jiti) moves to **`optionalDependencies`** of `@voltro/cli`, so `pnpm --prod --no-optional deploy` yields a serve image with none of it — a prod API image's `node_modules` drops ~305 MB → ~131 MB, structurally, with no fragile prune list. `voltro dev` and a non-production local `voltro serve` are unchanged (still tsx). **Migration:** in production (`NODE_ENV=production`) run `voltro build` before `voltro serve`. The generated Dockerfiles already do; a custom Dockerfile / start script adds a `voltro build .` step before `voltro serve .` (`voltro update` prints this — see the 0.3.0 codemod note).
+
+### Added
+
+- **@voltro/protocol, @voltro/runtime, @voltro/plugin-rbac** — Declarative authorization `guards:` on `defineMutation` / `defineQuery` / `defineAction`. The framework enforces the declared scope(s) in the dispatch spine BEFORE the executor (for a mutation, before the transaction opens), fails with a typed `ScopeError`, and auto-merges `ScopeError` into the wire error union so the client decodes the denial typed. Guards are browser-safe DATA (scope strings + a pure `resource: (input) => id` extractor). Checks run against the caller's EFFECTIVE scope set — raw subject scopes ∪ `@voltro/plugin-rbac` role-derived scopes — via a new canonical effective-scope seam in `@voltro/protocol` (`effectiveScopes` / `setEffectiveScopes` / `checkGuards`), which rbac now publishes to (so a role-granted scope satisfies a `guards:` entry and the in-handler `permission()` identically). Adds `ctx.access` (`has` / `hasAny` / `require` / `scopes`) — the cast-free typed authorization slice on every handler context. Enforcement is single-sourced in the shared serve pipeline, so `voltro dev` and `voltro serve` can't drift.
+- **@voltro/protocol, @voltro/client** — Nested / path-targeted auto-optimistic. A mutation `target` can now patch a nested array INSIDE a query's value — a JSON array column (`snapshot.projects`) or a computed/shaped result — at item granularity, via `path` (dot-path to the array), `by` (item key, default `id`), and `match` (a pure predicate that scopes the patch to the entries whose current value satisfies it, preventing a patch bleeding across sibling subscriptions that share a source table). Previously auto-optimistic only patched the flat top-level row array keyed by `id`; nested values needed a hand-written `.withOptimistic` reducer. `path`/`by`/`match` are browser-safe descriptor data (a dot-path string + pure predicate), same discipline as `identify`/`shape`. A path insert is applied even on a computed entry (it targets a known document, not a blind top-level add).
+- **@voltro/runtime** — `ctx.store.applyDefined(input, keys)` (and a standalone `applyDefined` export from `@voltro/runtime`) — builds a partial-update patch keeping only the listed keys whose value the caller actually provided (`!== undefined`; a defined falsy value like `0`/`''`/`false` is kept). Collapses the per-field `if (input.x !== undefined) patch.x = input.x` idiom every partial-update mutation hand-writes.
+- **@voltro/database** — `.uniqueActive([cols], opts?)` on the table builder — a portable partial-UNIQUE constraint that holds only among the rows matching a predicate (default `"deletedAt" IS NULL`, pairing with `.softDelete()`). Emits `CREATE UNIQUE INDEX … WHERE` on postgres / sqlite / mssql, so a soft-deleted row leaves the active set and a NEW row with the same key inserts cleanly — no hand-written `generatedAs("CASE WHEN …")` column and no resurrection footgun. On mysql / mariadb (no partial-index support) it FAILS LOUDLY at migrate time rather than silently emitting a full unique index that would forbid re-creating a soft-deleted key — the generated-STORED-column lowering for those dialects is a follow-up. Kept out of the declarative index snapshot (the incremental planner is predicate-blind and would misclassify a unique+partial index as a full constraint), so the fresh-schema DDL path is its sole emitter and there is no re-diff churn. Live-verified against postgres.
+- **@voltro/cli** — `voltro update` upgrades an app to the latest framework: it bumps every `@voltro/*` dependency, installs with the detected package manager, and runs the codemods shipped with the target version. Codemods are authored with `defineCodemod` + an import-scoped ts-morph helper toolkit (`renameImport`, `renameModuleSpecifier`, `renameJsxProp`, `renameObjectKey`, `add`/`removeImport`, structural `changeCallArgs`/`wrapCall`, `annotate`) and run against the app source; a `manual` kind surfaces written steps for changes that can't be automated. Breaking public-API changes now ship a codemod (or an explicit `codemod: none`), enforced by the changelog gate. Framework-owned `_voltro_*` table changes continue to ride the declarative differ on `voltro db apply` / `voltro dev` boot — `update` does not touch the database.
+
+### Fixed
+
+- **@voltro/database** — The core-table registry (`registerCoreTables` / `requireActors` / `requireTenants`) now stores its state on a process-global `Symbol.for` singleton, the same mechanism the main table registry already uses — instead of module-local `let` bindings. Module-local state splits when the `@voltro/database` module is duplicated in a process (e.g. resolved through both the `.` and `./sql` entry points, or a bundled framework copy alongside an externally-resolved one): one instance's `registerCoreTables` becomes invisible to the instance that reads it, surfacing as a spurious `core 'actors' table not registered` at store construction. Pinning it to `globalThis` makes every copy share one store, matching the table registry's already-global behaviour.
+
+---
+
 ## [0.2.2] — 2026-07-17
 
 ### Added

package/dist/index.d.ts

@@ -14,6 +14,9 @@ export declare interface ActionProcedureDescriptor<Name extends string, Input ex
     readonly input: Input;
     readonly output: Output;
     readonly error: Error;
+    /** Declarative authorization guard(s) — enforced before the executor runs,
+     *  failing with a typed `ScopeError`. Absent → no framework-level authz. */
+    readonly guards: Guards | undefined;
     /** Opt this action into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this action into the auto-synthesized agent toolset (innovation/07). */
@@ -160,6 +163,33 @@ export declare const checkFrameworkCompat: (pluginName: string, range: string |
     reason: string;
 };
 
+/**
+ * Check a descriptor's declared `guards:` against a subject's EFFECTIVE scopes.
+ * Returns a typed `ScopeError` naming the first unmet scope, or `null` when
+ * every guard is satisfied (or there are no guards). Pure + synchronous — the
+ * runtime calls it in the dispatch spine BEFORE the executor (and, for
+ * mutations, before the transaction opens). The `admin:full` bypass passes
+ * everything.
+ */
+export declare const checkGuards: (subject: Subject, guards: ReadonlyArray<GuardCheckSpec> | 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<GuardCheckSpec> | undefined, input: unknown) => Effect.Effect<ScopeError | null>;
+
 export declare interface ClientDescriptor {
     readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'workflow';
     /** Query only: table(s) the cache should match this subscription against. */
@@ -189,7 +219,18 @@ 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
+     *  descriptor by value. */
+    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
@@ -287,6 +328,10 @@ export declare const defineAction: <const Name extends string, Input extends Sch
     readonly input: Input;
     readonly output: Output;
     readonly error?: Error;
+    /** Declarative authorization guard(s) — the caller must hold the named
+     *  scope(s) or the action fails with a typed `ScopeError` before the executor
+     *  runs. `ScopeError` is auto-merged into the wire error union. */
+    readonly guards?: Guards<Schema.Schema.Type<Input>>;
     /** Project this action as a public REST endpoint (innovation/11). */
     readonly publicApi?: PublicApiSpec;
     /** Expose this action as an agent tool (innovation/07). */
@@ -300,6 +345,10 @@ export declare const defineMutation: <const Name extends string, Input extends S
     readonly error?: Error;
     /** Optional declarative target(s) — drives auto-optimistic. */
     readonly target?: Target<Schema.Schema.Type<Input>, Schema.Schema.Type<Output>>;
+    /** Declarative authorization guard(s) — the caller must hold the named
+     *  scope(s) or the mutation fails with a typed `ScopeError` BEFORE the
+     *  transaction opens. `ScopeError` is auto-merged into the wire error union. */
+    readonly guards?: Guards<Schema.Schema.Type<Input>>;
     /** Project this mutation as a public REST endpoint (innovation/11). */
     readonly publicApi?: PublicApiSpec;
     /** Expose this mutation as an agent tool (innovation/07). */
@@ -364,6 +413,10 @@ export declare const defineQuery: <const Name extends string, Input extends Sche
     readonly source?: string | ReadonlyArray<string>;
     /** Opt into server-side snapshot caching with auto-invalidation. */
     readonly cache?: QueryCacheConfig;
+    /** Declarative authorization guard(s) — the caller must hold the named
+     *  scope(s) or the query fails with a typed `ScopeError` before the executor
+     *  runs. `ScopeError` is auto-merged into the wire error union. */
+    readonly guards?: Guards<Schema.Schema.Type<Input>>;
     /** Project this query as a public REST endpoint (innovation/11). */
     readonly publicApi?: PublicApiSpec;
     /** Expose this query as an agent tool (innovation/07). */
@@ -382,11 +435,12 @@ export declare const defineStream: <const Name extends string, Input extends Sch
     readonly error?: Error;
 }) => StreamProcedureDescriptor<Name, Input, Element, Error>;
 
-export declare interface DeleteTarget<Input = unknown> {
+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;
 }
 
 /**
@@ -406,6 +460,13 @@ export declare interface DeleteTarget<Input = unknown> {
  */
 export declare const diffRows: (prev: ReadonlyArray<PatchRow>, next: ReadonlyArray<PatchRow>) => RowPatch;
 
+/**
+ * The caller's effective scope set — the merged set published by rbac if
+ * present, else the raw `subject.scopes`. This is what declarative guards and
+ * `ctx.access` check against.
+ */
+export declare const effectiveScopes: (subject: Subject) => ReadonlyArray<string>;
+
 /** Normalize the `exposeAsTool` shorthand. `true` is only valid when the
  *  descriptor carries a top-level `description`; callers pass that in. */
 export declare type ExposeAsTool = boolean | ExposeAsToolSpec;
@@ -438,9 +499,54 @@ 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 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 interface GuardSpec<Input = unknown> {
+    /** Required permission scope(s). A single string, or an array combined by
+     *  `mode`. Scope strings are the same values `hasScope` / rbac roles use. */
+    readonly scope: string | ReadonlyArray<string>;
+    /** How an array of scopes combines. `'all'` (default) = AND (hold every
+     *  scope); `'any'` = OR (hold at least one). Ignored for a single scope. */
+    readonly mode?: 'all' | 'any';
+    /**
+     * PURE `input → resource id` extractor for a row/resource-scoped guard.
+     * Browser-safe (no DB, no server import) — exactly like `target.identify`.
+     * The framework passes the extracted id to a resource-aware scope resolver
+     * (a future ReBAC / `accessPolicy()` resolver) so the check can be scoped to
+     * THAT resource. With only the default (subject-global) resolver installed
+     * the id is advisory and the guard checks the subject's global scopes. Omit
+     * for a plain subject-scope guard.
+     */
+    readonly resource?: (input: Input) => string | undefined;
+}
+
 export declare const hasCallbackRoutes: (s: AuthStrategy) => s is AuthStrategyWithCallback;
 
-/** True if the subject holds `scope` (or the `admin:full` bypass). */
+/** True if the subject holds `scope` (or the `admin:full` bypass), checking
+ *  the EFFECTIVE set (role-derived scopes included). Prefer this over
+ *  `hasScope` anywhere rbac roles should count. */
+export declare const hasEffectiveScope: (subject: Subject, scope: string) => boolean;
+
+/** True if the subject holds `scope` (or the `admin:full` bypass). Checks only
+ *  the RAW subject scopes — use `hasEffectiveScope` to include rbac roles. */
 export declare const hasScope: (subject: Subject, scope: string) => boolean;
 
 /**
@@ -544,7 +650,7 @@ export declare interface IdempotencyStore {
  *  corrupt the pointer. */
 export declare const idToPath: (id: RowId) => string;
 
-export declare interface InsertTarget<Input = unknown, Row = unknown> {
+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;
@@ -562,9 +668,13 @@ export declare interface InsertTarget<Input = unknown, Row = unknown> {
      *
      * 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
@@ -589,6 +699,10 @@ export declare interface MutationProcedureDescriptor<Name extends string, Input
      *  query-invalidation analytics). Mutations without a target run
      *  normally but skip auto-optimistic. */
     readonly target: Target | undefined;
+    /** Declarative authorization guard(s) — enforced before the transaction
+     *  opens, failing with a typed `ScopeError`. Absent → no framework-level
+     *  authz (author gates in-handler, or the mutation is unguarded). */
+    readonly guards: Guards | undefined;
     /** Opt this mutation into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this mutation into the auto-synthesized agent toolset (innovation/07). */
@@ -597,6 +711,21 @@ export declare interface MutationProcedureDescriptor<Name extends string, Input
 
 export declare const mutationToRpc: <Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: MutationProcedureDescriptor<Name, Input, Output, Err>, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Output, Schema.Schema.All, never>;
 
+export declare interface NestedTargetFields<Input = unknown> {
+    /** Dot-path to the nested array within the query VALUE to patch (e.g.
+     *  `'snapshot.projects'`). Absent → patch the top-level row array (default). */
+    readonly path?: string | undefined;
+    /** Item key within the nested array (default `'id'`). Only meaningful with
+     *  `path`. */
+    readonly by?: string | undefined;
+    /** Guard WHICH cached query entries this target patches: only entries whose
+     *  CURRENT value satisfies the predicate. Pure + browser-safe. Prevents a
+     *  patch from bleeding across sibling subscriptions that share a source table
+     *  (the guard AWB hand-writes as `roadmap.id === input.roadmapId`). Absent →
+     *  every entry matching the target `table` is patched. */
+    readonly match?: ((value: unknown, input: Input) => boolean) | undefined;
+}
+
 /**
  * Project a runtime descriptor down to the subset the client needs.
  * Functions (`shape`, `identify`) are passed through by reference —
@@ -1289,6 +1418,9 @@ export declare interface QueryProcedureDescriptor<Name extends string, Input ext
     /** Server-side snapshot cache config. Absent → never cached (the
      *  default; the dispatcher already keeps live subscriptions fresh). */
     readonly cache: QueryCacheConfig | undefined;
+    /** Declarative authorization guard(s) — enforced before the executor runs,
+     *  failing with a typed `ScopeError`. Absent → no framework-level authz. */
+    readonly guards: Guards | undefined;
     /** Opt this query into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this query into the auto-synthesized agent toolset (innovation/07). */
@@ -1341,9 +1473,29 @@ export declare const queryToRpc: <Name extends string, Input extends Schema.Sche
     revision: Schema.optional<typeof Schema.Number>;
 }>]>, Schema.Schema.All>, typeof Schema.Never, never>;
 
-/** Gate a handler on a scope; fails with a typed `ScopeError` if missing. */
+/** Gate a handler on a scope; fails with a typed `ScopeError` if missing.
+ *  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;
 
@@ -1577,6 +1729,21 @@ declare type ServerErrorListener = (event: ServerErrorEvent) => void;
 
 export declare type ServerErrorSource = 'rest' | 'aggregate' | 'subscriber' | 'reaction' | 'schedule' | 'workflow' | 'webhook' | 'startup';
 
+/**
+ * Publish the caller's fully-resolved scope set for this request (raw subject
+ * scopes ∪ role-derived scopes ∪ any extra grants). Called by the rbac
+ * interceptor; safe to call more than once (last write wins).
+ */
+export declare const setEffectiveScopes: (subject: Subject, scopes: ReadonlyArray<string>) => 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.
@@ -1925,13 +2092,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> {
+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,30 +1,30 @@
-import { a as e, c as t, d as n, f as r, i, l as a, n as o, o as ee, r as te, s, t as ne, u as re } from "./auth-DCE6m7Bo.js";
-import { a as ie, c as ae, d as oe, f as se, i as ce, l as le, n as ue, o as de, r as fe, s as pe, t as me, u as he } from "./serverErrorBus-C1KVL0dr.js";
-import { Context as ge, Layer as _e, Schema as c } from "effect";
-import { Rpc as l } from "@effect/rpc";
+import { _ as e, a as t, c as n, d as r, f as i, g as a, h as o, i as ee, l as s, m as te, n as ne, o as re, p as ie, r as ae, s as oe, t as c, u as se, v as ce, y as le } from "./serverErrorBus-0wjvKwGO.js";
+import { a as ue, c as de, d as fe, f as pe, i as me, l as he, n as ge, o as _e, r as ve, s as ye, t as be, u as l } from "./auth-DCE6m7Bo.js";
+import { Context as u, Layer as xe, Schema as d } from "effect";
+import { Rpc as f } from "@effect/rpc";
 //#region src/rowPatch.ts
-var ve = c.Union(c.String, c.Number), u = c.Record({
-	key: c.String,
-	value: c.Unknown
-}).pipe(c.filter((e) => "id" in e, { message: () => "patch row must carry an id" })), d = c.Union(c.Struct({
-	op: c.Literal("add"),
-	path: c.String,
-	value: u
-}), c.Struct({
-	op: c.Literal("replace"),
-	path: c.String,
-	value: u
-}), c.Struct({
-	op: c.Literal("remove"),
-	path: c.String
-})), f = c.Struct({
-	ops: c.Array(d),
-	order: c.Array(ve)
-}), p = (e) => `/${String(e).replace(/~/g, "~0").replace(/\//g, "~1")}`, ye = (e) => (e.startsWith("/") ? e.slice(1) : e).replace(/~1/g, "/").replace(/~0/g, "~"), m = (e) => {
+var Se = d.Union(d.String, d.Number), p = d.Record({
+	key: d.String,
+	value: d.Unknown
+}).pipe(d.filter((e) => "id" in e, { message: () => "patch row must carry an id" })), m = d.Union(d.Struct({
+	op: d.Literal("add"),
+	path: d.String,
+	value: p
+}), d.Struct({
+	op: d.Literal("replace"),
+	path: d.String,
+	value: p
+}), d.Struct({
+	op: d.Literal("remove"),
+	path: d.String
+})), h = d.Struct({
+	ops: d.Array(m),
+	order: d.Array(Se)
+}), g = (e) => `/${String(e).replace(/~/g, "~0").replace(/\//g, "~1")}`, Ce = (e) => (e.startsWith("/") ? e.slice(1) : e).replace(/~1/g, "/").replace(/~0/g, "~"), _ = (e) => {
 	let t = Object.keys(e).sort(), n = {};
 	for (let r of t) n[r] = e[r];
 	return JSON.stringify(n);
-}, be = (e, t) => m(e) === m(t), xe = (e, t) => {
+}, we = (e, t) => _(e) === _(t), Te = (e, t) => {
 	let n = /* @__PURE__ */ new Map();
 	for (let t of e) n.set(t.id, t);
 	let r = [], i = [], a = /* @__PURE__ */ new Set();
@@ -33,26 +33,26 @@ var ve = c.Union(c.String, c.Number), u = c.Record({
 		let t = n.get(e.id);
 		t === void 0 ? r.push({
 			op: "add",
-			path: p(e.id),
+			path: g(e.id),
 			value: e
-		}) : be(t, e) || r.push({
+		}) : we(t, e) || r.push({
 			op: "replace",
-			path: p(e.id),
+			path: g(e.id),
 			value: e
 		});
 	}
 	for (let t of e) a.has(t.id) || r.push({
 		op: "remove",
-		path: p(t.id)
+		path: g(t.id)
 	});
 	return {
 		ops: r,
 		order: i
 	};
-}, Se = (e) => e.every((e) => {
+}, Ee = (e) => e.every((e) => {
 	let t = e.id;
 	return typeof t == "string" || typeof t == "number";
-}), Ce = (e, t) => {
+}), De = (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,79 +62,82 @@ var ve = c.Union(c.String, c.Number), u = c.Record({
 		t !== void 0 && r.push(t);
 	}
 	return r;
-}, h = (e) => c.Union(c.Struct({
-	_tag: c.Literal("snapshot"),
-	revision: c.Number,
+}, v = (e) => d.Union(d.Struct({
+	_tag: d.Literal("snapshot"),
+	revision: d.Number,
 	data: e,
-	computed: c.optional(c.Boolean)
-}), c.Struct({
-	_tag: c.Literal("delta"),
-	revision: c.Number,
-	emittedAt: c.Number,
-	patch: f
-}), c.Struct({
-	_tag: c.Literal("error"),
-	error: c.Unknown,
-	revision: c.optional(c.Number)
-})), g = (e) => ({
+	computed: d.optional(d.Boolean)
+}), d.Struct({
+	_tag: d.Literal("delta"),
+	revision: d.Number,
+	emittedAt: d.Number,
+	patch: h
+}), d.Struct({
+	_tag: d.Literal("error"),
+	error: d.Unknown,
+	revision: d.optional(d.Number)
+})), y = (e) => ({
 	kind: "query",
 	name: e.name,
 	input: e.input,
 	output: e.output,
-	error: e.error ?? c.Never,
+	error: e.error ?? d.Never,
 	source: e.source,
 	cache: e.cache,
+	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), _ = (e) => ({
+}), b = (e) => ({
 	kind: "mutation",
 	name: e.name,
 	input: e.input,
 	output: e.output,
-	error: e.error ?? c.Never,
+	error: e.error ?? d.Never,
 	target: e.target,
+	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), v = (e) => ({
+}), x = (e) => ({
 	kind: "action",
 	name: e.name,
 	input: e.input,
 	output: e.output,
-	error: e.error ?? c.Never,
+	error: e.error ?? d.Never,
+	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), we = (e) => ({
+}), Oe = (e) => ({
 	kind: "stream",
 	name: e.name,
 	input: e.input,
 	element: e.element,
-	error: e.error ?? c.Never
-}), y = (e, t) => t && t.length > 0 ? c.Union(e, ...t) : e, b = (e, t) => l.make(e.name, {
+	error: e.error ?? d.Never
+}), S = (e, t) => t && t.length > 0 ? d.Union(e, ...t) : e, C = (e, t) => t && t.length > 0 ? d.Union(e, s) : e, w = (e, t) => f.make(e.name, {
 	payload: e.input,
-	success: h(e.output),
-	error: y(e.error, t),
+	success: v(e.output),
+	error: S(C(e.error, e.guards), t),
 	stream: !0
-}), x = (e, t) => l.make(e.name, {
+}), T = (e, t) => f.make(e.name, {
 	payload: e.input,
 	success: e.output,
-	error: y(e.error, t)
-}), S = (e, t) => l.make(e.name, {
+	error: S(C(e.error, e.guards), t)
+}), E = (e, t) => f.make(e.name, {
 	payload: e.input,
 	success: e.output,
-	error: y(e.error, t)
-}), C = (e, t) => l.make(e.name, {
+	error: S(C(e.error, e.guards), t)
+}), D = (e, t) => f.make(e.name, {
 	payload: e.input,
 	success: e.element,
-	error: y(e.error, t),
+	error: S(e.error, t),
 	stream: !0
-}), Te = (e) => {
+}), ke = (e) => {
 	switch (e.kind) {
-		case "query": return b(e);
-		case "mutation": return x(e);
-		case "action": return S(e);
-		case "stream": return C(e);
+		case "query": return w(e);
+		case "mutation": return T(e);
+		case "action": return E(e);
+		case "stream": return D(e);
 	}
-}, Ee = (e) => {
+}, Ae = (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",
@@ -168,18 +171,22 @@ var ve = c.Union(c.String, c.Number), u = c.Record({
 			op: e.op,
 			..."order" in e && e.order !== void 0 ? { order: e.order } : {},
 			..."shape" in e && e.shape !== void 0 ? { shape: e.shape } : {},
-			..."identify" in e && e.identify !== void 0 ? { identify: e.identify } : {}
+			..."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 } : {},
+			..."shapeItem" in e && e.shapeItem !== void 0 ? { shapeItem: e.shapeItem } : {}
 		}))
 	};
-}, w = (e) => e, T = (e) => e, E = (e) => {
+}, je = (e) => e, Me = (e) => e, Ne = (e) => {
 	if (e.length !== 0) return (t, n) => e.reduceRight((e, t) => t(e, n), t);
-}, D = (e, t) => {
-	let n = ge.GenericTag(e);
+}, Pe = (e, t) => {
+	let n = u.GenericTag(e);
 	return {
 		Tag: n,
-		Live: _e.succeed(n, t)
+		Live: xe.succeed(n, t)
 	};
-}, De = (e, t, n) => {
+}, Fe = (e, t, n) => {
 	if (!t) return { ok: !0 };
 	let r = O(n);
 	if (!r) return {
@@ -189,7 +196,7 @@ var ve = c.Union(c.String, c.Number), u = c.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 (!Oe(i, r)) return {
+	for (let i of a) if (!Ie(i, r)) return {
 		ok: !1,
 		reason: `plugin "${e}" requires framework ${t}, running ${n}`
 	};
@@ -202,7 +209,7 @@ var ve = c.Union(c.String, c.Number), u = c.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, Oe = (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, Ie = (e, t) => {
 	if (e === "*") return !0;
 	if (e.startsWith("^")) {
 		let n = O(e.slice(1));
@@ -224,173 +231,173 @@ var ve = c.Union(c.String, c.Number), u = c.Record({
 	}
 	let r = O(e);
 	return r ? k(t, r) === 0 : !1;
-}, A = c.Literal("running", "succeeded", "failed", "cancelled", "suspended"), j = c.Literal("cancel", "terminate", "abandon"), ke = c.Struct({
-	id: c.String,
-	workflowName: c.String,
-	executionId: c.String,
-	status: c.Literal("running")
-}), M = c.Struct({
-	id: c.String,
-	tag: c.String,
-	executionId: c.String,
+}, A = d.Literal("running", "succeeded", "failed", "cancelled", "suspended"), j = d.Literal("cancel", "terminate", "abandon"), Le = d.Struct({
+	id: d.String,
+	workflowName: d.String,
+	executionId: d.String,
+	status: d.Literal("running")
+}), M = d.Struct({
+	id: d.String,
+	tag: d.String,
+	executionId: d.String,
 	status: A,
-	payload: c.Unknown,
-	workflowVersion: c.NullOr(c.String),
-	workflowPatches: c.NullOr(c.Unknown),
-	output: c.NullOr(c.Unknown),
-	subject: c.NullOr(c.Unknown),
-	source: c.NullOr(c.String),
-	errorTag: c.NullOr(c.String),
-	errorMessage: c.NullOr(c.String),
-	cancelled: c.Boolean,
-	startedAt: c.Date,
-	completedAt: c.NullOr(c.Date),
-	durationMs: c.NullOr(c.Number),
-	traceId: c.NullOr(c.String),
-	parentExecutionId: c.NullOr(c.String),
-	parentClosePolicy: c.NullOr(j)
-}), N = c.Struct({
-	tag: c.optional(c.String),
-	status: c.optional(A),
-	limit: c.optional(c.Number)
-}), P = c.Struct({
-	id: c.String,
-	runId: c.String,
-	stepName: c.String,
-	attempt: c.Number,
-	status: c.Literal("running", "succeeded", "failed"),
-	input: c.NullOr(c.Unknown),
-	retryPolicy: c.NullOr(c.Unknown),
-	output: c.NullOr(c.Unknown),
-	errorTag: c.NullOr(c.String),
-	errorMessage: c.NullOr(c.String),
-	errorCause: c.NullOr(c.Unknown),
-	startedAt: c.Date,
-	completedAt: c.NullOr(c.Date),
-	durationMs: c.NullOr(c.Number)
-}), F = c.Struct({
-	id: c.String,
-	runId: c.String,
-	eventType: c.String,
-	payload: c.NullOr(c.Unknown),
-	occurredAt: c.Date,
-	stepName: c.NullOr(c.String),
-	attempt: c.NullOr(c.Number)
-}), I = c.Struct({
-	id: c.String,
-	name: c.String,
-	payload: c.Unknown,
-	source: c.String,
-	subject: c.NullOr(c.Unknown),
-	traceId: c.NullOr(c.String),
-	occurredAt: c.Date
-}), L = c.Struct({
-	id: c.String,
-	eventId: c.String,
-	eventName: c.String,
-	triggerId: c.String,
-	workflowName: c.String,
-	executionId: c.NullOr(c.String),
-	status: c.Literal("starting", "started", "skipped", "failed"),
-	idempotencyKey: c.String,
-	skipped: c.Boolean,
-	errorMessage: c.NullOr(c.String),
-	createdAt: c.Date,
-	completedAt: c.NullOr(c.Date)
-}), R = c.Struct({ id: c.String }), z = c.Struct({ runId: c.String }), B = c.Struct({
-	name: c.optional(c.String),
-	limit: c.optional(c.Number)
-}), V = c.Struct({ eventId: c.String }), H = c.Struct({
-	workflowName: c.String,
-	executionId: c.String
-}), U = c.Struct({
-	id: c.String,
-	signalName: c.String,
-	payload: c.optional(c.Unknown)
-}), W = c.Struct({
-	id: c.String,
-	updateName: c.String,
-	payload: c.optional(c.Unknown),
-	timeoutMs: c.optional(c.Number)
-}), G = c.Struct({
-	eventId: c.String,
-	updateId: c.String,
-	completedEventId: c.String,
-	result: c.Unknown
-}), Ae = g({
+	payload: d.Unknown,
+	workflowVersion: d.NullOr(d.String),
+	workflowPatches: d.NullOr(d.Unknown),
+	output: d.NullOr(d.Unknown),
+	subject: d.NullOr(d.Unknown),
+	source: d.NullOr(d.String),
+	errorTag: d.NullOr(d.String),
+	errorMessage: d.NullOr(d.String),
+	cancelled: d.Boolean,
+	startedAt: d.Date,
+	completedAt: d.NullOr(d.Date),
+	durationMs: d.NullOr(d.Number),
+	traceId: d.NullOr(d.String),
+	parentExecutionId: d.NullOr(d.String),
+	parentClosePolicy: d.NullOr(j)
+}), N = d.Struct({
+	tag: d.optional(d.String),
+	status: d.optional(A),
+	limit: d.optional(d.Number)
+}), P = d.Struct({
+	id: d.String,
+	runId: d.String,
+	stepName: d.String,
+	attempt: d.Number,
+	status: d.Literal("running", "succeeded", "failed"),
+	input: d.NullOr(d.Unknown),
+	retryPolicy: d.NullOr(d.Unknown),
+	output: d.NullOr(d.Unknown),
+	errorTag: d.NullOr(d.String),
+	errorMessage: d.NullOr(d.String),
+	errorCause: d.NullOr(d.Unknown),
+	startedAt: d.Date,
+	completedAt: d.NullOr(d.Date),
+	durationMs: d.NullOr(d.Number)
+}), F = d.Struct({
+	id: d.String,
+	runId: d.String,
+	eventType: d.String,
+	payload: d.NullOr(d.Unknown),
+	occurredAt: d.Date,
+	stepName: d.NullOr(d.String),
+	attempt: d.NullOr(d.Number)
+}), I = d.Struct({
+	id: d.String,
+	name: d.String,
+	payload: d.Unknown,
+	source: d.String,
+	subject: d.NullOr(d.Unknown),
+	traceId: d.NullOr(d.String),
+	occurredAt: d.Date
+}), L = d.Struct({
+	id: d.String,
+	eventId: d.String,
+	eventName: d.String,
+	triggerId: d.String,
+	workflowName: d.String,
+	executionId: d.NullOr(d.String),
+	status: d.Literal("starting", "started", "skipped", "failed"),
+	idempotencyKey: d.String,
+	skipped: d.Boolean,
+	errorMessage: d.NullOr(d.String),
+	createdAt: d.Date,
+	completedAt: d.NullOr(d.Date)
+}), R = d.Struct({ id: d.String }), z = d.Struct({ runId: d.String }), B = d.Struct({
+	name: d.optional(d.String),
+	limit: d.optional(d.Number)
+}), V = d.Struct({ eventId: d.String }), H = d.Struct({
+	workflowName: d.String,
+	executionId: d.String
+}), U = d.Struct({
+	id: d.String,
+	signalName: d.String,
+	payload: d.optional(d.Unknown)
+}), W = d.Struct({
+	id: d.String,
+	updateName: d.String,
+	payload: d.optional(d.Unknown),
+	timeoutMs: d.optional(d.Number)
+}), G = d.Struct({
+	eventId: d.String,
+	updateId: d.String,
+	completedEventId: d.String,
+	result: d.Unknown
+}), Re = y({
 	name: "__voltro.workflow.run",
 	source: "_voltro_workflow_runs",
 	input: R,
-	output: c.Array(M)
-}), je = g({
+	output: d.Array(M)
+}), ze = y({
 	name: "__voltro.workflow.runs",
 	source: "_voltro_workflow_runs",
 	input: N,
-	output: c.Array(M)
-}), Me = g({
+	output: d.Array(M)
+}), Be = y({
 	name: "__voltro.workflow.run.steps",
 	source: "_voltro_workflow_run_steps",
 	input: z,
-	output: c.Array(P)
-}), Ne = g({
+	output: d.Array(P)
+}), Ve = y({
 	name: "__voltro.workflow.run.events",
 	source: "_voltro_workflow_run_events",
 	input: z,
-	output: c.Array(F)
-}), Pe = g({
+	output: d.Array(F)
+}), He = y({
 	name: "__voltro.workflow.domainEvents",
 	source: "_voltro_workflow_events",
 	input: B,
-	output: c.Array(I)
-}), Fe = g({
+	output: d.Array(I)
+}), Ue = y({
 	name: "__voltro.workflow.event.deliveries",
 	source: "_voltro_workflow_event_deliveries",
 	input: V,
-	output: c.Array(L)
-}), Ie = v({
+	output: d.Array(L)
+}), We = x({
 	name: "__voltro.workflow.cancel",
 	input: H,
-	output: c.Struct({ ok: c.Boolean })
-}), Le = v({
+	output: d.Struct({ ok: d.Boolean })
+}), Ge = x({
 	name: "__voltro.workflow.resume",
 	input: H,
-	output: c.Struct({ ok: c.Boolean })
-}), Re = v({
+	output: d.Struct({ ok: d.Boolean })
+}), Ke = x({
 	name: "__voltro.workflow.signal",
 	input: U,
-	output: c.Struct({ eventId: c.String })
-}), ze = v({
+	output: d.Struct({ eventId: d.String })
+}), qe = x({
 	name: "__voltro.workflow.update",
 	input: W,
 	output: G
-}), K = "__voltro.undo.log", q = "__voltro.undo.apply", J = "__voltro.undo.redo", Y = c.Struct({
-	id: c.String,
-	tag: c.String,
-	label: c.NullOr(c.String),
-	undone: c.Boolean,
-	crossesAction: c.Boolean,
-	createdAt: c.String
-}), X = class extends c.TaggedError()("UndoNotFound", { invocationId: c.String }) {}, Z = class extends c.TaggedError()("UndoForbidden", { invocationId: c.String }) {}, Q = class extends c.TaggedError()("UndoConflict", {
-	invocationId: c.String,
-	reason: c.Literal("conflict", "action")
-}) {}, $ = c.Union(X, Z, Q), Be = g({
+}), K = "__voltro.undo.log", q = "__voltro.undo.apply", J = "__voltro.undo.redo", Y = d.Struct({
+	id: d.String,
+	tag: d.String,
+	label: d.NullOr(d.String),
+	undone: d.Boolean,
+	crossesAction: d.Boolean,
+	createdAt: d.String
+}), X = class extends d.TaggedError()("UndoNotFound", { invocationId: d.String }) {}, Z = class extends d.TaggedError()("UndoForbidden", { invocationId: d.String }) {}, Q = class extends d.TaggedError()("UndoConflict", {
+	invocationId: d.String,
+	reason: d.Literal("conflict", "action")
+}) {}, $ = d.Union(X, Z, Q), Je = y({
 	name: K,
 	source: "_voltro_undo_log",
-	input: c.Struct({ limit: c.optional(c.Number) }),
-	output: c.Array(Y)
-}), Ve = _({
+	input: d.Struct({ limit: d.optional(d.Number) }),
+	output: d.Array(Y)
+}), Ye = b({
 	name: q,
-	input: c.Struct({ invocationId: c.String }),
-	output: c.Struct({ ok: c.Boolean }),
+	input: d.Struct({ invocationId: d.String }),
+	output: d.Struct({ ok: d.Boolean }),
 	error: $
-}), He = _({
+}), Xe = b({
 	name: J,
-	input: c.Struct({ invocationId: c.String }),
-	output: c.Struct({ ok: c.Boolean }),
+	input: d.Struct({ invocationId: d.String }),
+	output: d.Struct({ ok: d.Boolean }),
 	error: $
-}), Ue = (e) => {
+}), Ze = (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;
-}, We = 1;
+}, Qe = 1;
 //#endregion
-export { ae as ADMIN_SCOPE, ne as AuthMiddleware, o as ConnectionInfo, te as ConnectionInfoMiddleware, We as PROTOCOL_VERSION, le as ScopeError, i as Subject, e as SubjectService, q as UNDO_APPLY_TAG, K as UNDO_LOG_TAG, J as UNDO_REDO_TAG, ee 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, ke 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, S as actionToRpc, s as anonymousSubject, Ce as applyRowPatch, t as assertAuthenticated, fe as beginIdempotent, De as checkFrameworkCompat, a as composeAuthStrategies, E as composeRpcInterceptors, v as defineAction, _ as defineMutation, w as definePlugin, T as definePluginRoute, D as definePluginService, g as defineQuery, we as defineStream, xe as diffRows, ce as failIdempotent, ie as finishIdempotent, re as hasCallbackRoutes, he as hasScope, p as idToPath, de as idempotencyScope, Se as isIdKeyed, n as isSystemSubject, pe as memoryIdempotencyStore, x as mutationToRpc, Ee as normalizeDescriptor, ye as pathToId, me as publishServerError, b as queryToRpc, oe as requireScope, d as rowPatchOpSchema, f as rowPatchSchema, C as streamToRpc, se as subjectScopes, ue as subscribeServerErrors, h as subscriptionEvent, r as systemSubject, Te as toRpc, Ue as tsMs, Ve as undoApplyDescriptor, Be as undoLogQueryDescriptor, He as undoRedoDescriptor, Ie as workflowCancelDescriptor, Pe as workflowDomainEventsQueryDescriptor, Fe as workflowEventDeliveriesQueryDescriptor, Le as workflowResumeDescriptor, Ne as workflowRunEventsQueryDescriptor, Ae as workflowRunQueryDescriptor, Me as workflowRunStepsQueryDescriptor, je as workflowRunsQueryDescriptor, Re as workflowSignalDescriptor, ze as workflowUpdateDescriptor };
+export { n as ADMIN_SCOPE, be as AuthMiddleware, ge as ConnectionInfo, ve as ConnectionInfoMiddleware, Qe as PROTOCOL_VERSION, s as ScopeError, me as Subject, ue as SubjectService, q as UNDO_APPLY_TAG, K as UNDO_LOG_TAG, J as UNDO_REDO_TAG, _e 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, Le 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, E as actionToRpc, ye as anonymousSubject, De as applyRowPatch, de as assertAuthenticated, ae as beginIdempotent, Fe as checkFrameworkCompat, se as checkGuards, r as checkGuardsEffect, he as composeAuthStrategies, Ne as composeRpcInterceptors, x as defineAction, b as defineMutation, je as definePlugin, Me as definePluginRoute, Pe as definePluginService, y as defineQuery, Oe as defineStream, Te as diffRows, i as effectiveScopes, ee as failIdempotent, t as finishIdempotent, ie as getResourceScopeResolver, l as hasCallbackRoutes, te as hasEffectiveScope, o as hasScope, g as idToPath, re as idempotencyScope, Ee as isIdKeyed, fe as isSystemSubject, oe as memoryIdempotencyStore, T as mutationToRpc, Ae as normalizeDescriptor, Ce as pathToId, c as publishServerError, w as queryToRpc, a as requireScope, m as rowPatchOpSchema, h as rowPatchSchema, e as setEffectiveScopes, ce as setResourceScopeResolver, D as streamToRpc, le as subjectScopes, ne as subscribeServerErrors, v as subscriptionEvent, pe as systemSubject, ke as toRpc, Ze as tsMs, Ye as undoApplyDescriptor, Je as undoLogQueryDescriptor, Xe as undoRedoDescriptor, We as workflowCancelDescriptor, He as workflowDomainEventsQueryDescriptor, Ue as workflowEventDeliveriesQueryDescriptor, Ge as workflowResumeDescriptor, Ve as workflowRunEventsQueryDescriptor, Re as workflowRunQueryDescriptor, Be as workflowRunStepsQueryDescriptor, ze as workflowRunsQueryDescriptor, Ke as workflowSignalDescriptor, qe as workflowUpdateDescriptor };

package/dist/rest.d.ts

@@ -6,6 +6,9 @@ declare interface ActionProcedureDescriptor<Name extends string, Input extends S
     readonly input: Input;
     readonly output: Output;
     readonly error: Error;
+    /** Declarative authorization guard(s) — enforced before the executor runs,
+     *  failing with a typed `ScopeError`. Absent → no framework-level authz. */
+    readonly guards: Guards | undefined;
     /** Opt this action into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this action into the auto-synthesized agent toolset (innovation/07). */
@@ -26,11 +29,12 @@ export declare const collectPublicApiRoutes: (entries: ReadonlyArray<PublicApiEn
  */
 export declare const defineRestRoute: <I, O>(descriptor: RestRouteDescriptor<I, O>) => RestRouteDescriptor<I, O>;
 
-declare interface DeleteTarget<Input = unknown> {
+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. */
@@ -71,6 +75,29 @@ declare interface ExposeAsToolSpec {
     readonly maxPerRun?: number;
 }
 
+/** 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 interface GuardSpec<Input = unknown> {
+    /** Required permission scope(s). A single string, or an array combined by
+     *  `mode`. Scope strings are the same values `hasScope` / rbac roles use. */
+    readonly scope: string | ReadonlyArray<string>;
+    /** How an array of scopes combines. `'all'` (default) = AND (hold every
+     *  scope); `'any'` = OR (hold at least one). Ignored for a single scope. */
+    readonly mode?: 'all' | 'any';
+    /**
+     * PURE `input → resource id` extractor for a row/resource-scoped guard.
+     * Browser-safe (no DB, no server import) — exactly like `target.identify`.
+     * The framework passes the extracted id to a resource-aware scope resolver
+     * (a future ReBAC / `accessPolicy()` resolver) so the check can be scoped to
+     * THAT resource. With only the default (subject-global) resolver installed
+     * the id is advisory and the guard checks the subject's global scopes. Omit
+     * for a plain subject-scope guard.
+     */
+    readonly resource?: (input: Input) => string | undefined;
+}
+
 declare interface IdempotencyRecord {
     readonly scope: string;
     readonly key: string;
@@ -103,7 +130,7 @@ declare interface IdempotencyStore {
     readonly release: (scope: string, key: string) => Promise<void>;
 }
 
-declare interface InsertTarget<Input = unknown, Row = unknown> {
+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;
@@ -121,9 +148,13 @@ declare interface InsertTarget<Input = unknown, Row = unknown> {
      *
      * 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
@@ -144,12 +175,31 @@ declare interface MutationProcedureDescriptor<Name extends string, Input extends
      *  query-invalidation analytics). Mutations without a target run
      *  normally but skip auto-optimistic. */
     readonly target: Target | undefined;
+    /** Declarative authorization guard(s) — enforced before the transaction
+     *  opens, failing with a typed `ScopeError`. Absent → no framework-level
+     *  authz (author gates in-handler, or the mutation is unguarded). */
+    readonly guards: Guards | undefined;
     /** Opt this mutation into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this mutation into the auto-synthesized agent toolset (innovation/07). */
     readonly exposeAsTool: ExposeAsTool | undefined;
 }
 
+declare interface NestedTargetFields<Input = unknown> {
+    /** Dot-path to the nested array within the query VALUE to patch (e.g.
+     *  `'snapshot.projects'`). Absent → patch the top-level row array (default). */
+    readonly path?: string | undefined;
+    /** Item key within the nested array (default `'id'`). Only meaningful with
+     *  `path`. */
+    readonly by?: string | undefined;
+    /** Guard WHICH cached query entries this target patches: only entries whose
+     *  CURRENT value satisfies the predicate. Pure + browser-safe. Prevents a
+     *  patch from bleeding across sibling subscriptions that share a source table
+     *  (the guard AWB hand-writes as `roadmap.id === input.roadmapId`). Absent →
+     *  every entry matching the target `table` is patched. */
+    readonly match?: ((value: unknown, input: Input) => boolean) | undefined;
+}
+
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 declare interface PluginHttpRoute {
     /** HTTP method, or `'*'` for any (the handler decides). */
@@ -294,6 +344,9 @@ declare interface QueryProcedureDescriptor<Name extends string, Input extends Sc
     /** Server-side snapshot cache config. Absent → never cached (the
      *  default; the dispatcher already keeps live subscriptions fresh). */
     readonly cache: QueryCacheConfig | undefined;
+    /** Declarative authorization guard(s) — enforced before the executor runs,
+     *  failing with a typed `ScopeError`. Absent → no framework-level authz. */
+    readonly guards: Guards | undefined;
     /** Opt this query into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this query into the auto-synthesized agent toolset (innovation/07). */
@@ -438,13 +491,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> {
+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,5 +1,5 @@
-import { s as e } from "./auth-DCE6m7Bo.js";
-import { a as t, i as n, o as r, r as i, t as a } from "./serverErrorBus-C1KVL0dr.js";
+import { a as e, i as t, o as n, r, t as i } from "./serverErrorBus-0wjvKwGO.js";
+import { s as a } from "./auth-DCE6m7Bo.js";
 import { Effect as o, Schema as s } from "effect";
 //#region src/publicApi.ts
 var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.path ?? `/${t.version ?? "v1"}/${e.replace(/\./g, "/")}`, u = (e, t) => {
@@ -95,7 +95,7 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 				}, f);
 				p = t.value;
 			}
-			let h = l.resolveSubject ? await l.resolveSubject(s.headers) : e(s.headers["x-tenant"] ?? null), g = {
+			let h = l.resolveSubject ? await l.resolveSubject(s.headers) : a(s.headers["x-tenant"] ?? null), g = {
 				subject: h,
 				headers: s.headers,
 				store: l.store
@@ -104,9 +104,9 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 				let t = await e(g);
 				if (t) return m(t.status, { error: t.message }, f);
 			}
-			let b = l.idempotency, x = b && y.has(c.method) ? s.headers[b.header.toLowerCase()] : void 0, S = b && x ? r(h.tenantId, c.method, c.path) : "";
+			let b = l.idempotency, x = b && y.has(c.method) ? s.headers[b.header.toLowerCase()] : void 0, S = b && x ? n(h.tenantId, c.method, c.path) : "";
 			if (b && x) {
-				let e = await i(b.store, S, x, b.ttlMs, Date.now());
+				let e = await r(b.store, S, x, b.ttlMs, Date.now());
 				if (e.kind === "replay") return m(e.response.status, e.response.body, {
 					...f,
 					"Idempotency-Replayed": "true"
@@ -114,17 +114,17 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 				if (e.kind === "conflict") return m(409, { error: "A request with this Idempotency-Key is already being processed" }, f);
 			}
 			try {
-				let e = await c.handler(p, g), n = await o.runPromise(d(e));
-				return b && x && await t(b.store, S, x, {
+				let t = await c.handler(p, g), n = await o.runPromise(d(t));
+				return b && x && await e(b.store, S, x, {
 					status: 200,
 					body: n
 				}, Date.now()), m(200, n, f);
 			} catch (e) {
-				if (b && x && await n(b.store, S, x), typeof e == "object" && e && typeof e.status == "number") {
+				if (b && x && await t(b.store, S, x), typeof e == "object" && e && typeof e.status == "number") {
 					let t = e;
 					return m(t.status, { error: t.message ?? "Error" }, f);
 				}
-				return a({
+				return i({
 					error: e,
 					source: "rest",
 					name: `${c.method} ${c.path}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.2.2",
+  "version": "0.4.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.2.2",
+    "@voltro/database": "0.4.0",
     "jose": "^6.2.3"
   },
   "peerDependencies": {