@voltro/protocol 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -39,6 +39,35 @@ _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

package/dist/index.d.ts

@@ -173,6 +173,23 @@ export declare const checkFrameworkCompat: (pluginName: string, range: string |
  */
 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. */
@@ -202,7 +219,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 +227,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 +438,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,9 +499,20 @@ 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
@@ -617,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> 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 +668,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
@@ -1440,6 +1477,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 +1736,14 @@ export declare type ServerErrorSource = 'rest' | 'aggregate' | 'subscriber' | 'r
  */
 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.
@@ -2028,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> 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,30 +1,30 @@
-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 { Rpc as u } 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 xe = 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({
-	op: l.Literal("add"),
-	path: l.String,
-	value: d
-}), l.Struct({
-	op: l.Literal("replace"),
-	path: l.String,
-	value: d
-}), l.Struct({
-	op: l.Literal("remove"),
-	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) => {
+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);
-}, Ce = (e, t) => h(e) === h(t), g = (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 xe = l.Union(l.String, l.Number), d = l.Record({
 		let t = n.get(e.id);
 		t === void 0 ? r.push({
 			op: "add",
-			path: m(e.id),
+			path: g(e.id),
 			value: e
-		}) : Ce(t, e) || r.push({
+		}) : we(t, e) || r.push({
 			op: "replace",
-			path: m(e.id),
+			path: g(e.id),
 			value: e
 		});
 	}
 	for (let t of e) a.has(t.id) || r.push({
 		op: "remove",
-		path: m(t.id)
+		path: g(t.id)
 	});
 	return {
 		ops: r,
 		order: i
 	};
-}, we = (e) => e.every((e) => {
+}, Ee = (e) => e.every((e) => {
 	let t = e.id;
 	return typeof t == "string" || typeof t == "number";
-}), Te = (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,82 +62,82 @@ var xe = l.Union(l.String, l.Number), d = l.Record({
 		t !== void 0 && r.push(t);
 	}
 	return r;
-}, _ = (e) => l.Union(l.Struct({
-	_tag: l.Literal("snapshot"),
-	revision: l.Number,
+}, v = (e) => d.Union(d.Struct({
+	_tag: d.Literal("snapshot"),
+	revision: d.Number,
 	data: e,
-	computed: l.optional(l.Boolean)
-}), l.Struct({
-	_tag: l.Literal("delta"),
-	revision: l.Number,
-	emittedAt: l.Number,
-	patch: p
-}), l.Struct({
-	_tag: l.Literal("error"),
-	error: l.Unknown,
-	revision: l.optional(l.Number)
-})), v = (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 ?? l.Never,
+	error: e.error ?? d.Never,
 	source: e.source,
 	cache: e.cache,
 	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), y = (e) => ({
+}), b = (e) => ({
 	kind: "mutation",
 	name: e.name,
 	input: e.input,
 	output: e.output,
-	error: e.error ?? l.Never,
+	error: e.error ?? d.Never,
 	target: e.target,
 	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), b = (e) => ({
+}), x = (e) => ({
 	kind: "action",
 	name: e.name,
 	input: e.input,
 	output: e.output,
-	error: e.error ?? l.Never,
+	error: e.error ?? d.Never,
 	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), Ee = (e) => ({
+}), Oe = (e) => ({
 	kind: "stream",
 	name: e.name,
 	input: e.input,
 	element: e.element,
-	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, {
+	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: _(e.output),
-	error: x(S(e.error, e.guards), t),
+	success: v(e.output),
+	error: S(C(e.error, e.guards), t),
 	stream: !0
-}), w = (e, t) => u.make(e.name, {
+}), T = (e, t) => f.make(e.name, {
 	payload: e.input,
 	success: e.output,
-	error: x(S(e.error, e.guards), t)
-}), T = (e, t) => u.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: x(S(e.error, e.guards), t)
-}), E = (e, t) => u.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: x(e.error, t),
+	error: S(e.error, t),
 	stream: !0
-}), D = (e) => {
+}), ke = (e) => {
 	switch (e.kind) {
-		case "query": return C(e);
-		case "mutation": return w(e);
-		case "action": return T(e);
-		case "stream": return E(e);
+		case "query": return w(e);
+		case "mutation": return T(e);
+		case "action": return E(e);
+		case "stream": return D(e);
 	}
-}, De = (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",
@@ -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) => {
+}, je = (e) => e, Me = (e) => e, Ne = (e) => {
 	if (e.length !== 0) return (t, n) => e.reduceRight((e, t) => t(e, n), t);
-}, je = (e, t) => {
-	let n = ye.GenericTag(e);
+}, Pe = (e, t) => {
+	let n = u.GenericTag(e);
 	return {
 		Tag: n,
-		Live: be.succeed(n, t)
+		Live: xe.succeed(n, t)
 	};
-}, Me = (e, t, n) => {
+}, Fe = (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 (!Ie(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, Ie = (e, t) => {
 	if (e === "*") return !0;
 	if (e.startsWith("^")) {
 		let n = O(e.slice(1));
@@ -230,173 +231,173 @@ 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({
-	id: l.String,
-	workflowName: l.String,
-	executionId: l.String,
-	status: l.Literal("running")
-}), M = l.Struct({
-	id: l.String,
-	tag: l.String,
-	executionId: l.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: l.Unknown,
-	workflowVersion: l.NullOr(l.String),
-	workflowPatches: l.NullOr(l.Unknown),
-	output: l.NullOr(l.Unknown),
-	subject: l.NullOr(l.Unknown),
-	source: l.NullOr(l.String),
-	errorTag: l.NullOr(l.String),
-	errorMessage: l.NullOr(l.String),
-	cancelled: l.Boolean,
-	startedAt: l.Date,
-	completedAt: l.NullOr(l.Date),
-	durationMs: l.NullOr(l.Number),
-	traceId: l.NullOr(l.String),
-	parentExecutionId: l.NullOr(l.String),
-	parentClosePolicy: l.NullOr(j)
-}), N = l.Struct({
-	tag: l.optional(l.String),
-	status: l.optional(A),
-	limit: l.optional(l.Number)
-}), P = l.Struct({
-	id: l.String,
-	runId: l.String,
-	stepName: l.String,
-	attempt: l.Number,
-	status: l.Literal("running", "succeeded", "failed"),
-	input: l.NullOr(l.Unknown),
-	retryPolicy: l.NullOr(l.Unknown),
-	output: l.NullOr(l.Unknown),
-	errorTag: l.NullOr(l.String),
-	errorMessage: l.NullOr(l.String),
-	errorCause: l.NullOr(l.Unknown),
-	startedAt: l.Date,
-	completedAt: l.NullOr(l.Date),
-	durationMs: l.NullOr(l.Number)
-}), F = l.Struct({
-	id: l.String,
-	runId: l.String,
-	eventType: l.String,
-	payload: l.NullOr(l.Unknown),
-	occurredAt: l.Date,
-	stepName: l.NullOr(l.String),
-	attempt: l.NullOr(l.Number)
-}), I = l.Struct({
-	id: l.String,
-	name: l.String,
-	payload: l.Unknown,
-	source: l.String,
-	subject: l.NullOr(l.Unknown),
-	traceId: l.NullOr(l.String),
-	occurredAt: l.Date
-}), L = l.Struct({
-	id: l.String,
-	eventId: l.String,
-	eventName: l.String,
-	triggerId: l.String,
-	workflowName: l.String,
-	executionId: l.NullOr(l.String),
-	status: l.Literal("starting", "started", "skipped", "failed"),
-	idempotencyKey: l.String,
-	skipped: l.Boolean,
-	errorMessage: l.NullOr(l.String),
-	createdAt: l.Date,
-	completedAt: l.NullOr(l.Date)
-}), R = l.Struct({ id: l.String }), z = l.Struct({ runId: l.String }), B = l.Struct({
-	name: l.optional(l.String),
-	limit: l.optional(l.Number)
-}), V = l.Struct({ eventId: l.String }), H = l.Struct({
-	workflowName: l.String,
-	executionId: l.String
-}), U = l.Struct({
-	id: l.String,
-	signalName: l.String,
-	payload: l.optional(l.Unknown)
-}), W = l.Struct({
-	id: l.String,
-	updateName: l.String,
-	payload: l.optional(l.Unknown),
-	timeoutMs: l.optional(l.Number)
-}), G = l.Struct({
-	eventId: l.String,
-	updateId: l.String,
-	completedEventId: l.String,
-	result: l.Unknown
-}), Fe = v({
+	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: l.Array(M)
-}), Ie = v({
+	output: d.Array(M)
+}), ze = y({
 	name: "__voltro.workflow.runs",
 	source: "_voltro_workflow_runs",
 	input: N,
-	output: l.Array(M)
-}), Le = v({
+	output: d.Array(M)
+}), Be = y({
 	name: "__voltro.workflow.run.steps",
 	source: "_voltro_workflow_run_steps",
 	input: z,
-	output: l.Array(P)
-}), Re = v({
+	output: d.Array(P)
+}), Ve = y({
 	name: "__voltro.workflow.run.events",
 	source: "_voltro_workflow_run_events",
 	input: z,
-	output: l.Array(F)
-}), ze = v({
+	output: d.Array(F)
+}), He = y({
 	name: "__voltro.workflow.domainEvents",
 	source: "_voltro_workflow_events",
 	input: B,
-	output: l.Array(I)
-}), Be = v({
+	output: d.Array(I)
+}), Ue = y({
 	name: "__voltro.workflow.event.deliveries",
 	source: "_voltro_workflow_event_deliveries",
 	input: V,
-	output: l.Array(L)
-}), Ve = b({
+	output: d.Array(L)
+}), We = x({
 	name: "__voltro.workflow.cancel",
 	input: H,
-	output: l.Struct({ ok: l.Boolean })
-}), He = b({
+	output: d.Struct({ ok: d.Boolean })
+}), Ge = x({
 	name: "__voltro.workflow.resume",
 	input: H,
-	output: l.Struct({ ok: l.Boolean })
-}), Ue = b({
+	output: d.Struct({ ok: d.Boolean })
+}), Ke = x({
 	name: "__voltro.workflow.signal",
 	input: U,
-	output: l.Struct({ eventId: l.String })
-}), We = b({
+	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 = l.Struct({
-	id: l.String,
-	tag: l.String,
-	label: l.NullOr(l.String),
-	undone: l.Boolean,
-	crossesAction: l.Boolean,
-	createdAt: l.String
-}), 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({
+}), 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: l.Struct({ limit: l.optional(l.Number) }),
-	output: l.Array(Y)
-}), Ke = y({
+	input: d.Struct({ limit: d.optional(d.Number) }),
+	output: d.Array(Y)
+}), Ye = b({
 	name: q,
-	input: l.Struct({ invocationId: l.String }),
-	output: l.Struct({ ok: l.Boolean }),
+	input: d.Struct({ invocationId: d.String }),
+	output: d.Struct({ ok: d.Boolean }),
 	error: $
-}), qe = y({
+}), Xe = b({
 	name: J,
-	input: l.Struct({ invocationId: l.String }),
-	output: l.Struct({ ok: l.Boolean }),
+	input: d.Struct({ invocationId: d.String }),
+	output: d.Struct({ ok: d.Boolean }),
 	error: $
-}), Je = (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;
-}, Ye = 1;
+}, Qe = 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 { 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

@@ -32,8 +32,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. */
@@ -129,7 +130,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 +148,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
@@ -486,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> 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-0wjvKwGO.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.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.3.0",
+    "@voltro/database": "0.4.0",
     "jose": "^6.2.3"
   },
   "peerDependencies": {