@voltro/protocol 0.34.0 → 0.36.0

package/dist/rest.d.ts

@@ -121,7 +121,8 @@ export declare const derivePublicPath: (tag: string, spec: PublicApiSpec) => str
  * side effect when the method isn't its own — so probing the group in order and
  * taking the FIRST non-405 result yields the route that owns the request's
  * method. This is what lets the standard GET + POST on one resource path
- * coexist: the serve pipeline mounts ONE dispatcher per path (the underlying
+ * coexist: the runtime's rpc server (`rpcServer.ts`, started by both boot
+ * paths) mounts ONE dispatcher per path (the underlying
  * router rejects two mounts on the same `(method, path)`). A single-route group
  * returns that route's result directly (its own 405 included); when no route in
  * the group owns the method, the last 405 stands.
@@ -158,13 +159,32 @@ declare interface GuardSpec<Input = unknown> {
      *  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.
+     * PURE `input → resource id` extractor. Browser-safe (no DB, no server
+     * import) — exactly like `target.identify`. Omit for a plain subject-scope
+     * guard.
+     *
+     * **On a `GuardSpec` this id is ADVISORY.** A scope guard answers "what may
+     * this subject do at all", against the subject's global scope set; the id is
+     * carried for logging and for a future subject-scope resolver that narrows by
+     * resource. It does not, on its own, make the check per-resource.
+     *
+     * **If your authority is per-resource, you want {@link PolicyGuardSpec}, not
+     * this field** — `guards: [{ action, resourceType, resource }]`, backed by
+     * `defineResourcePolicy` + a tuple source you register. That is built, wired
+     * on both boot paths, fail-closed without a resolver, and documented under
+     * *Authentication → Authorization*. An app whose relationships already live
+     * in its own tables (a `teamMembers` row, say) registers its own tuple source
+     * rather than copying data across; see `policyGuardResolver.ts`.
+     *
+     * That paragraph is here because its absence cost a consumer their access
+     * gate. This comment used to describe the resolver as "a future ReBAC /
+     * `accessPolicy()` resolver" — written before the ReBAC path shipped and
+     * never updated. They read the type, quoted the sentence, concluded there was
+     * "nothing in between" declaring an untruth and turning the gate off, and set
+     * `security: { defaultDeny: false }` on an app with 565 undecided procedures.
+     * The capability they needed was two fields away. A doc comment that says
+     * "future" about something shipped is not a small inaccuracy: it is the only
+     * thing a careful reader has, and it argued them out of a feature.
      */
     readonly resource?: (input: Input) => string | undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "The Voltro wire + plugin contract — defineQuery/Mutation/Action/Stream, definePlugin, sessions / JWT / API-keys, and the RPC protocol.",
   "keywords": [
     "voltro",
@@ -54,8 +54,8 @@
   },
   "dependencies": {
     "@effect/sql": "^0.52.0",
-    "@voltro/database": "0.34.0",
-    "@voltro/logger": "0.34.0",
+    "@voltro/database": "0.36.0",
+    "@voltro/logger": "0.36.0",
     "jose": "^6.2.4"
   },
   "peerDependencies": {