@voltro/protocol 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -39,6 +39,26 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [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,16 @@ 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;
+
 export declare interface ClientDescriptor {
     readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'workflow';
     /** Query only: table(s) the cache should match this subscription against. */
@@ -190,6 +203,13 @@ export declare interface ClientTarget {
     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;
+    /** 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;
 }
 
 /** Compose multiple strategies into a single resolver function. The
@@ -287,6 +307,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 +324,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 +392,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,7 +414,7 @@ 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`. */
@@ -406,6 +438,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 +477,43 @@ 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>;
 
+export declare interface GuardCheckSpec {
+    readonly scope: string | ReadonlyArray<string>;
+    readonly mode?: 'all' | 'any';
+}
+
+/** 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 +617,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> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'insert';
     readonly order?: 'prepend' | 'append' | undefined;
@@ -589,6 +662,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 +674,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 +1381,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,7 +1436,8 @@ 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 id of a row, addressed in op paths as `/<id>`. */
@@ -1577,6 +1673,13 @@ 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;
+
 /** 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,7 +2028,7 @@ 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> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'update';
     /** Identify the row to patch. Default: `input.id`. */

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 { 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";
 //#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 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) => {
 	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) => {
+}, Ce = (e, t) => h(e) === h(t), g = (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: m(e.id),
 			value: e
-		}) : be(t, e) || r.push({
+		}) : Ce(t, e) || r.push({
 			op: "replace",
-			path: p(e.id),
+			path: m(e.id),
 			value: e
 		});
 	}
 	for (let t of e) a.has(t.id) || r.push({
 		op: "remove",
-		path: p(t.id)
+		path: m(t.id)
 	});
 	return {
 		ops: r,
 		order: i
 	};
-}, Se = (e) => e.every((e) => {
+}, we = (e) => e.every((e) => {
 	let t = e.id;
 	return typeof t == "string" || typeof t == "number";
-}), Ce = (e, t) => {
+}), Te = (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,
+}, _ = (e) => l.Union(l.Struct({
+	_tag: l.Literal("snapshot"),
+	revision: l.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: 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) => ({
 	kind: "query",
 	name: e.name,
 	input: e.input,
 	output: e.output,
-	error: e.error ?? c.Never,
+	error: e.error ?? l.Never,
 	source: e.source,
 	cache: e.cache,
+	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), _ = (e) => ({
+}), y = (e) => ({
 	kind: "mutation",
 	name: e.name,
 	input: e.input,
 	output: e.output,
-	error: e.error ?? c.Never,
+	error: e.error ?? l.Never,
 	target: e.target,
+	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), v = (e) => ({
+}), b = (e) => ({
 	kind: "action",
 	name: e.name,
 	input: e.input,
 	output: e.output,
-	error: e.error ?? c.Never,
+	error: e.error ?? l.Never,
+	guards: e.guards,
 	publicApi: e.publicApi,
 	exposeAsTool: e.exposeAsTool
-}), we = (e) => ({
+}), Ee = (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 ?? l.Never
+}), x = (e, t) => t && t.length > 0 ? l.Union(e, ...t) : e, S = (e, t) => t && t.length > 0 ? l.Union(e, s) : e, C = (e, t) => u.make(e.name, {
 	payload: e.input,
-	success: h(e.output),
-	error: y(e.error, t),
+	success: _(e.output),
+	error: x(S(e.error, e.guards), t),
 	stream: !0
-}), x = (e, t) => l.make(e.name, {
+}), w = (e, t) => u.make(e.name, {
 	payload: e.input,
 	success: e.output,
-	error: y(e.error, t)
-}), S = (e, t) => l.make(e.name, {
+	error: x(S(e.error, e.guards), t)
+}), T = (e, t) => u.make(e.name, {
 	payload: e.input,
 	success: e.output,
-	error: y(e.error, t)
-}), C = (e, t) => l.make(e.name, {
+	error: x(S(e.error, e.guards), t)
+}), E = (e, t) => u.make(e.name, {
 	payload: e.input,
 	success: e.element,
-	error: y(e.error, t),
+	error: x(e.error, t),
 	stream: !0
-}), Te = (e) => {
+}), D = (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 C(e);
+		case "mutation": return w(e);
+		case "action": return T(e);
+		case "stream": return E(e);
 	}
-}, Ee = (e) => {
+}, De = (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,21 @@ 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 } : {}
 		}))
 	};
-}, w = (e) => e, T = (e) => e, E = (e) => {
+}, Oe = (e) => e, ke = (e) => e, Ae = (e) => {
 	if (e.length !== 0) return (t, n) => e.reduceRight((e, t) => t(e, n), t);
-}, D = (e, t) => {
-	let n = ge.GenericTag(e);
+}, je = (e, t) => {
+	let n = ye.GenericTag(e);
 	return {
 		Tag: n,
-		Live: _e.succeed(n, t)
+		Live: be.succeed(n, t)
 	};
-}, De = (e, t, n) => {
+}, Me = (e, t, n) => {
 	if (!t) return { ok: !0 };
 	let r = O(n);
 	if (!r) return {
@@ -189,7 +195,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 (!Ne(i, r)) return {
 		ok: !1,
 		reason: `plugin "${e}" requires framework ${t}, running ${n}`
 	};
@@ -202,7 +208,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, Ne = (e, t) => {
 	if (e === "*") return !0;
 	if (e.startsWith("^")) {
 		let n = O(e.slice(1));
@@ -224,173 +230,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 = 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,
 	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: 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({
 	name: "__voltro.workflow.run",
 	source: "_voltro_workflow_runs",
 	input: R,
-	output: c.Array(M)
-}), je = g({
+	output: l.Array(M)
+}), Ie = v({
 	name: "__voltro.workflow.runs",
 	source: "_voltro_workflow_runs",
 	input: N,
-	output: c.Array(M)
-}), Me = g({
+	output: l.Array(M)
+}), Le = v({
 	name: "__voltro.workflow.run.steps",
 	source: "_voltro_workflow_run_steps",
 	input: z,
-	output: c.Array(P)
-}), Ne = g({
+	output: l.Array(P)
+}), Re = v({
 	name: "__voltro.workflow.run.events",
 	source: "_voltro_workflow_run_events",
 	input: z,
-	output: c.Array(F)
-}), Pe = g({
+	output: l.Array(F)
+}), ze = v({
 	name: "__voltro.workflow.domainEvents",
 	source: "_voltro_workflow_events",
 	input: B,
-	output: c.Array(I)
-}), Fe = g({
+	output: l.Array(I)
+}), Be = v({
 	name: "__voltro.workflow.event.deliveries",
 	source: "_voltro_workflow_event_deliveries",
 	input: V,
-	output: c.Array(L)
-}), Ie = v({
+	output: l.Array(L)
+}), Ve = b({
 	name: "__voltro.workflow.cancel",
 	input: H,
-	output: c.Struct({ ok: c.Boolean })
-}), Le = v({
+	output: l.Struct({ ok: l.Boolean })
+}), He = b({
 	name: "__voltro.workflow.resume",
 	input: H,
-	output: c.Struct({ ok: c.Boolean })
-}), Re = v({
+	output: l.Struct({ ok: l.Boolean })
+}), Ue = b({
 	name: "__voltro.workflow.signal",
 	input: U,
-	output: c.Struct({ eventId: c.String })
-}), ze = v({
+	output: l.Struct({ eventId: l.String })
+}), We = b({
 	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 = 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({
 	name: K,
 	source: "_voltro_undo_log",
-	input: c.Struct({ limit: c.optional(c.Number) }),
-	output: c.Array(Y)
-}), Ve = _({
+	input: l.Struct({ limit: l.optional(l.Number) }),
+	output: l.Array(Y)
+}), Ke = y({
 	name: q,
-	input: c.Struct({ invocationId: c.String }),
-	output: c.Struct({ ok: c.Boolean }),
+	input: l.Struct({ invocationId: l.String }),
+	output: l.Struct({ ok: l.Boolean }),
 	error: $
-}), He = _({
+}), qe = y({
 	name: J,
-	input: c.Struct({ invocationId: c.String }),
-	output: c.Struct({ ok: c.Boolean }),
+	input: l.Struct({ invocationId: l.String }),
+	output: l.Struct({ ok: l.Boolean }),
 	error: $
-}), Ue = (e) => {
+}), Je = (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;
+}, Ye = 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 { 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 };

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,7 +29,7 @@ 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`. */
@@ -71,6 +74,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 +129,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> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'insert';
     readonly order?: 'prepend' | 'append' | undefined;
@@ -144,12 +170,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 +339,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,7 +486,7 @@ 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> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'update';
     /** Identify the row to patch. Default: `input.id`. */

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-BrqfEV84.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.3.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.3.0",
     "jose": "^6.2.3"
   },
   "peerDependencies": {