permdock 0.7.0 → 0.9.0

package/dist/{who-can-BwNsI_Js.js → who-can-BoDJm0Nc.js}

@@ -1,18 +1,18 @@
 import { t as compact } from "./compact-CAf557ZB.js";
-import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
-import { r as ownGet } from "./paths-DXSHAMIa.js";
-import { n as internalsOf } from "./internals-Dk8A8fX3.js";
-import { a as getResource } from "./permission-registry-DpPtSKNZ.js";
-import { a as expandRelation, c as isEdgeRelation, l as isFieldRelation, u as isPrincipalRelation } from "./resource-relations-D_jw0BFx.js";
-import { s as instantAt } from "./time-DkWjdL98.js";
-import { f as scopeList, l as rootScope, o as normalizeMemberships, s as resolveScope } from "./scopes-BHsc-wp-.js";
-import { o as flattenGrantee } from "./grantee-BrRANrpT.js";
-import { r as relationCondition } from "./grantee-conditions-C6P1Tvol.js";
-import { c as nowSeconds, p as scopeField } from "./tenancy-CmeBQ6Nv.js";
-import { t as byCodePoint } from "./compare-pfyVnBjE.js";
-import { D as emptyListeners, t as evaluate } from "./evaluate-B_oqFbWC.js";
-import { n as relationId, t as pendingRelations } from "./relations-BnCWnJGI.js";
-import { t as relationWalk } from "./relation-walk-3OyDBF0S.js";
+import { n as freezeDeep } from "./freeze-jjan0lCv.js";
+import { r as ownGet } from "./paths-CUvURzHp.js";
+import { n as internalsOf } from "./internals-B3IgHrvo.js";
+import { a as getResource } from "./permission-registry-B8tYxPIt.js";
+import { a as expandRelation, c as isEdgeRelation, l as isFieldRelation, u as isPrincipalRelation } from "./resource-relations-8-pCScBO.js";
+import { s as instantAt } from "./time-nR1JesoH.js";
+import { f as scopeList, l as rootScope, o as normalizeMemberships, s as resolveScope } from "./scopes-0Up_UA2t.js";
+import { o as flattenGrantee } from "./grantee-Dke-9rd1.js";
+import { t as byCodePoint } from "./compare-DTfyUunF.js";
+import { r as relationCondition } from "./grantee-conditions-BrYPe-w0.js";
+import { c as nowSeconds, p as scopeField } from "./tenancy-5d1zVBvK.js";
+import { D as emptyListeners, t as evaluate } from "./evaluate-BAmf_AQd.js";
+import { n as relationId, t as pendingRelations } from "./relations-BxvRvDHK.js";
+import { t as relationWalk } from "./relation-walk-DK_gkgL7.js";
 //#region src/core/who-can.ts
 const MAX_ROUNDS = 48;
 async function settle(cache) {
@@ -22,7 +22,10 @@ async function settle(cache) {
 		await Promise.all(pending);
 	}
 }
-/** The holders on each instance a graph relation reads, or `undefined` when the graph cannot say. */
+/**
+* The holders on each instance a graph relation reads, or `undefined` when the
+* graph cannot say.
+*/
 async function walkHolders(condition, row, reader, cache) {
 	let walk = relationWalk(condition, row, reader);
 	if (walk === "relation-unavailable") {
@@ -246,11 +249,11 @@ function memberLister(source, scopes) {
 	};
 }
 /**
-* Who holds `permission` on `resource` for the instance's policy and how
-* (role, relation or share), from `MembershipSource.list` and
-* `RelationSource.related`. It lists and never grants; `complete: false`
-* means some holders could not be listed. An instance built from a
-* snapshot answers an empty, incomplete list.
+* Who holds `permission` on `resource` for the instance's policy and how (role,
+* relation or share), from `MembershipSource.list` and
+* `RelationSource.related`. It lists and never grants; `complete: false` means
+* some holders could not be listed. An instance built from a snapshot answers
+* an empty, incomplete list.
 */
 function whoCan(permdock, permission, resource) {
 	const internals = internalsOf(permdock);

package/dist/workflow/index.d.ts

@@ -1,5 +1,5 @@
-import { a as AutomationSource, i as AutomationRequest, l as memoryAutomationSource, n as AutomationDecision, r as AutomationMode, s as MemoryAutomationSource, t as Automation, u as parseAutomation } from "../automation-DOtAFWdy.js";
-import { i as pollingApprovalWaiter, n as ApprovalWaiter, r as PollingApprovalWaiterOptions, t as ApprovalWaitOptions } from "../waiter-DwEyouan.js";
-import { a as WorkflowPermDockOptions, i as WorkflowPermDock, n as AwaitApprovalOptions, o as createPermDock, r as StartAutomationResult, t as AutomationOptions } from "../create-QHuuPw3q.js";
+import { a as AutomationSource, i as AutomationRequest, l as memoryAutomationSource, n as AutomationDecision, r as AutomationMode, s as MemoryAutomationSource, t as Automation, u as parseAutomation } from "../automation-C6Jg75xq.js";
+import { i as pollingApprovalWaiter, n as ApprovalWaiter, r as PollingApprovalWaiterOptions, t as ApprovalWaitOptions } from "../waiter-CqUKX6CY.js";
+import { a as WorkflowPermDockOptions, i as WorkflowPermDock, n as AwaitApprovalOptions, o as createPermDock, r as StartAutomationResult, t as AutomationOptions } from "../create-BamXmeob.js";
 import "../index-CaxrMD1A.js";
 export { type ApprovalWaitOptions, type ApprovalWaiter, type Automation, type AutomationDecision, type AutomationMode, type AutomationOptions, type AutomationRequest, type AutomationSource, type AwaitApprovalOptions, type MemoryAutomationSource, type PollingApprovalWaiterOptions, type StartAutomationResult, type WorkflowPermDock, type WorkflowPermDockOptions, createPermDock, memoryAutomationSource, parseAutomation, pollingApprovalWaiter };

package/dist/workflow/index.js

@@ -1,13 +1,13 @@
 import { t as compact } from "../compact-CAf557ZB.js";
-import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
-import { n as findPermission } from "../permission-registry-DpPtSKNZ.js";
-import { n as isThenable } from "../thenable-yD7SabqG.js";
-import { n as memoryAutomationSource, r as parseAutomation } from "../automation-ySsxp_Yp.js";
-import { l as withApp, t as getPermDock } from "../permdock-BfWEeMqk.js";
-import { o as automationEvent } from "../sink-BEZSlMS_.js";
-import { a as requestApproval, s as resumeDecision } from "../helpers-DY3vXuGs.js";
-import { i as subjectFromRunTicket, r as signRunTicket } from "../run-ticket-B5d_63Ma.js";
-import { t as pollingApprovalWaiter } from "../waiter-BGUtGYoU.js";
+import { n as freezeDeep } from "../freeze-jjan0lCv.js";
+import { n as findPermission } from "../permission-registry-B8tYxPIt.js";
+import { n as isThenable } from "../thenable-BNSM1U2R.js";
+import { n as memoryAutomationSource, r as parseAutomation } from "../automation-x3KEUusw.js";
+import { l as withApp, t as getPermDock } from "../permdock-BvjivVb9.js";
+import { o as automationEvent } from "../sink-D9_vh372.js";
+import { a as requestApproval, s as resumeDecision } from "../helpers-DJicaG6f.js";
+import { i as subjectFromRunTicket, r as signRunTicket } from "../run-ticket-Dv7aF7Dk.js";
+import { t as pollingApprovalWaiter } from "../waiter-aBLM63_f.js";
 //#region src/workflow/create.ts
 function writeQuietly(sink, event) {
 	try {
@@ -47,10 +47,10 @@ function targetOf(permission, data, resource) {
 	});
 }
 /**
-* Creates the PermDock for durable runs of published automations. A run
-* acts as the automation's principal with that principal's rights at each
-* step, narrowed to the automation's operations; the trigger is recorded
-* and never grants.
+* Creates the PermDock for durable runs of published automations. A run acts as
+* the automation's principal with that principal's rights at each step,
+* narrowed to the automation's operations; the trigger is recorded and never
+* grants.
 */
 function createPermDock(policy, given) {
 	const { signer, verifier, principals, automations, store: approvals, waiter, audience, issuer, expiresIn = DEFAULT_TTL, onAuth, ...permdockOptions } = withApp(policy, given);

package/dist/workflow-sdk/index.d.ts

@@ -1,13 +1,16 @@
-import { Ln as Decision } from "../policy-types-B-F-qAZk.js";
-import { u as Permission } from "../permission-types-DhNEmoRG.js";
-import { a as PermDock } from "../permdock-Dco6dyCK.js";
-import { n as ApprovalWaiter } from "../waiter-DwEyouan.js";
-import { i as WorkflowPermDock, r as StartAutomationResult, t as AutomationOptions } from "../create-QHuuPw3q.js";
+import { Un as Decision } from "../policy-types-DGIO_gxq.js";
+import { u as Permission } from "../permission-types-CAY-GU7e.js";
+import { a as PermDock } from "../permdock-CprAPN3w.js";
+import { n as ApprovalWaiter } from "../waiter-CqUKX6CY.js";
+import { i as WorkflowPermDock, r as StartAutomationResult, t as AutomationOptions } from "../create-BamXmeob.js";
 //#region src/workflow-sdk/index.d.ts
-/** The part of a Workflow SDK `Hook` the waiter reads: awaiting it suspends the run. */
+/**
+ * The part of a Workflow SDK `Hook` the waiter reads: awaiting it suspends the
+ * run.
+ */
 export type WorkflowSdkHook = {
   readonly then: PromiseLike<unknown>["then"];
-  dispose(): void;
+  dispose: () => void;
 };
 /** `createHook` from `workflow`; valid only inside a `"use workflow"` function. */
 export type WorkflowSdkCreateHook = (options: {
@@ -22,16 +25,19 @@ export type WorkflowSdkStart<TArgs extends unknown[], TRun> = (workflow: (ticket
 export type WorkflowSdkWaiterOptions = {
   readonly createHook: WorkflowSdkCreateHook;
   readonly resumeHook: WorkflowSdkResumeHook;
-  /** With `sleep`, a wait ends at the request's `expiresAt`; without it, only a wake ends it. */
+  /**
+   * With `sleep`, a wait ends at the request's `expiresAt`; without it, only a
+   * wake ends it.
+   */
   readonly sleep?: WorkflowSdkSleep;
 };
 /** The Workflow SDK hook token a run parks on while approval `token` is pending. */
 export declare function approvalHookToken(token: string): string;
 /**
  * An `ApprovalWaiter` over Workflow SDK hooks. `wait` parks the run on a hook
- * and must run inside the workflow function; `wake` resumes it from an
- * approval handler. The hook carries no verdict: the run decides again from
- * the approval store after it wakes.
+ * and must run inside the workflow function; `wake` resumes it from an approval
+ * handler. The hook carries no verdict: the run decides again from the approval
+ * store after it wakes.
  */
 export declare function workflowSdkWaiter(options: WorkflowSdkWaiterOptions): ApprovalWaiter;
 export type StartAutomationRunResult<TRun> = (Extract<StartAutomationResult, {
@@ -49,8 +55,8 @@ export type StartAutomationRunResult<TRun> = (Extract<StartAutomationResult, {
 export declare function startAutomation<TArgs extends unknown[], TRun>(workflow: Pick<WorkflowPermDock, "start">, start: WorkflowSdkStart<TArgs, TRun>, run: (ticket: string, ...args: TArgs) => Promise<unknown>, id: string, args: TArgs, options?: AutomationOptions): Promise<StartAutomationRunResult<TRun>>;
 /**
  * Resumes hook `token` with `payload` only when `caller` is granted
- * `permission` on `row`. A token alone never resumes a run. A hook that is
- * gone or a resume that throws denies with `validation`.
+ * `permission` on `row`. A token alone never resumes a run. A hook that is gone
+ * or a resume that throws denies with `validation`.
  */
 export declare function authorizeHook(resumeHook: WorkflowSdkResumeHook, caller: PermDock, permission: Permission, row: unknown, token: string, payload: unknown): Promise<Decision>;
 //#endregion

package/dist/workflow-sdk/index.js

@@ -1,4 +1,4 @@
-import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+import { n as freezeDeep } from "../freeze-jjan0lCv.js";
 //#region src/workflow-sdk/index.ts
 const HOOK_PREFIX = "permdock:approval:";
 /** The Workflow SDK hook token a run parks on while approval `token` is pending. */
@@ -7,9 +7,9 @@ function approvalHookToken(token) {
 }
 /**
 * An `ApprovalWaiter` over Workflow SDK hooks. `wait` parks the run on a hook
-* and must run inside the workflow function; `wake` resumes it from an
-* approval handler. The hook carries no verdict: the run decides again from
-* the approval store after it wakes.
+* and must run inside the workflow function; `wake` resumes it from an approval
+* handler. The hook carries no verdict: the run decides again from the approval
+* store after it wakes.
 */
 function workflowSdkWaiter(options) {
 	const { createHook, resumeHook, sleep } = options;
@@ -61,8 +61,8 @@ function hookDenied() {
 }
 /**
 * Resumes hook `token` with `payload` only when `caller` is granted
-* `permission` on `row`. A token alone never resumes a run. A hook that is
-* gone or a resume that throws denies with `validation`.
+* `permission` on `row`. A token alone never resumes a run. A hook that is gone
+* or a resume that throws denies with `validation`.
 */
 async function authorizeHook(resumeHook, caller, permission, row, token, payload) {
 	const decision = caller.decide(permission, row);

package/dist/{wrap-CiSc_KCq.js → wrap-B2wziJI_.js}

@@ -1,10 +1,10 @@
-import { n as internalsOf, t as attachInternals } from "./internals-Dk8A8fX3.js";
-import { i as decideAllWith, n as canAllWith } from "./checks-BC_0mPIq.js";
+import { n as internalsOf, t as attachInternals } from "./internals-B3IgHrvo.js";
+import { i as decideAllWith, n as canAllWith } from "./checks-CGkP3Z7A.js";
 //#region src/core/wrap.ts
 /**
 * A frozen copy of `permdock` with the members `overrides` returns replaced.
-* `overrides` runs again for every instance `tenant()`, `team()` and
-* `derive()` return, so a wrapper never falls off a derived instance.
+* `overrides` runs again for every instance `tenant()`, `team()` and `derive()`
+* return, so a wrapper never falls off a derived instance.
 */
 function wrapPermDock(permdock, overrides) {
 	const wrap = (next) => wrapPermDock(next, overrides);

package/dist/{wrap-B6R0cMRL.d.ts → wrap-DxXB54Wu.d.ts}

@@ -1,14 +1,17 @@
-import { j as PolicyVocabulary } from "./policy-types-B-F-qAZk.js";
-import { a as PermDock } from "./permdock-Dco6dyCK.js";
+import { j as PolicyVocabulary } from "./policy-types-DGIO_gxq.js";
+import { a as PermDock } from "./permdock-CprAPN3w.js";
 //#region src/core/wrap.d.ts
 /** A wrapper an adapter applies to each instance it builds, as `withOtel` does. */
 type PermDockWrap = <V extends PolicyVocabulary>(permdock: PermDock<V>) => PermDock<V>;
-/** The members `wrapPermDock` replaces; it re-wraps the derived instances itself. */
+/**
+ * The members `wrapPermDock` replaces; it re-wraps the derived instances
+ * itself.
+ */
 type PermDockOverrides<V extends PolicyVocabulary = PolicyVocabulary> = Partial<Omit<PermDock<V>, "tenant" | "team" | "derive">>;
 /**
  * A frozen copy of `permdock` with the members `overrides` returns replaced.
- * `overrides` runs again for every instance `tenant()`, `team()` and
- * `derive()` return, so a wrapper never falls off a derived instance.
+ * `overrides` runs again for every instance `tenant()`, `team()` and `derive()`
+ * return, so a wrapper never falls off a derived instance.
  */
 declare function wrapPermDock<V extends PolicyVocabulary = PolicyVocabulary>(permdock: PermDock<V>, overrides: (permdock: PermDock<V>) => PermDockOverrides<V>): PermDock<V>;
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "permdock",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Typed permissions for TypeScript apps, APIs, databases, and AI agents, with the permdock CLI and test runners.",
   "keywords": [
     "ai-agents",
@@ -353,8 +353,8 @@
     "ajv": "8.20.0",
     "astro": "7.4.0",
     "babel-plugin-react-compiler": "1.0.0",
-    "better-supabase": "0.12.0",
-    "better-supabase-floor": "npm:better-supabase@0.11.0",
+    "better-supabase": "0.13.0",
+    "better-supabase-floor": "npm:better-supabase@0.13.0",
     "chat": "4.42.0",
     "diff": "9.0.0",
     "drizzle-orm": "1.0.0-rc.5-5935859",
@@ -364,12 +364,12 @@
     "fastest-levenshtein": "1.0.16",
     "fastify": "5.12.7",
     "h3": "2.0.2",
-    "happy-dom": "20.14.5",
+    "happy-dom": "21.0.4",
     "hono": "4.13.13",
     "jose": "6.2.12",
     "kysely": "0.29.6",
     "next": "16.4.1",
-    "oxlint": "1.88.0",
+    "oxlint": "1.89.0",
     "oxlint-tsgolint": "7.0.2004",
     "package-manager-detector": "1.9.0",
     "pg": "8.23.1",
@@ -411,7 +411,7 @@
     "@trpc/server": ">=11",
     "ai": ">=5",
     "astro": ">=5",
-    "better-supabase": ">=0.11.0 <0.13.0",
+    "better-supabase": ">=0.13.0",
     "chat": ">=4",
     "drizzle-orm": ">=0.40 || >=1.0.0-rc.0",
     "elysia": ">=1",
@@ -420,12 +420,12 @@
     "fastify": ">=5",
     "h3": ">=2",
     "hono": ">=4",
-    "jose": "^6",
+    "jose": ">=6",
     "kysely": ">=0.27",
     "next": ">=16.3",
     "pg": ">=8",
     "pgsql-parser": ">=18",
-    "react": "^19",
+    "react": ">=19",
     "reflect-metadata": ">=0.1",
     "resend": ">=6",
     "rxjs": ">=7",

package/schemas/catalog-v1.json

@@ -274,6 +274,9 @@
               "type": "string"
             }
           },
+          "orderedLevels": {
+            "const": true
+          },
           "hostable": {
             "const": true
           },

package/schemas/supabase-manifest-v1.json

@@ -329,6 +329,38 @@
         }
       }
     },
+    "names": {
+      "description": "The SQL names the generated RLS exposes to application SQL, unqualified, in `schema`: per scope and per resource, as `resolveNames` gives them. Absent from a manifest written before 0.8.",
+      "type": "object",
+      "required": ["schema", "gucPrefix", "claims", "scopes", "resources"],
+      "properties": {
+        "schema": { "type": "string" },
+        "gucPrefix": { "type": "string" },
+        "claims": {
+          "type": "object",
+          "required": ["tenant", "role"],
+          "properties": {
+            "tenant": { "type": "string" },
+            "role": { "type": "string" }
+          }
+        },
+        "teamScope": { "type": "string" },
+        "scopes": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          }
+        },
+        "resources": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          }
+        }
+      }
+    },
     "requires": {
       "description": "The supabase/sdk capability-matrix feature ids the hook, the helpers and subjectFromSupabase depend on, as of the matrix release tag.",
       "type": "object",
@@ -457,7 +489,7 @@
     },
     "helperName": {
       "type": "string",
-      "pattern": "^(permdock_has(_for)?|permitted_[a-z][a-z0-9_]*_(ids|permission_keys)(_for)?|permitted_[a-z][a-z0-9_]*_users|member_[a-z][a-z0-9_]*_ids(_for)?|permdock_can_assign(_any|_custom_role)?(_for)?|permdock_api_key_allows|permdock_token_scope_allows|permdock_actor_may_write|permdock_is_approver|permdock_user_id)$"
+      "pattern": "^(permdock_has(_for)?|permitted_[a-z][a-z0-9_]*_(ids|permission_keys)(_for)?|permitted_[a-z][a-z0-9_]*_users|member_[a-z][a-z0-9_]*_ids(_for|_of)?|permdock_can_assign(_any|_custom_role)?(_for)?|permdock_api_key_allows|permdock_token_scope_allows|permdock_actor_may_write|permdock_is_approver|permdock_user_id)$"
     },
     "column": {
       "type": "object",

package/skills/permdock-credentials/references/tokens-keys-links.md

@@ -47,11 +47,13 @@ const decision = await decideCredential(
 );
 if (decision.outcome === "granted") {
   const key = generateApiKey(decision.credential.id);
-  await db.insert(apiKeys).values({
-    id: decision.credential.id,
-    hash: await hashApiKey(key),
-    credential: decision.credential,
-  });
+  await db
+    .insert(apiKeys)
+    .values({
+      id: decision.credential.id,
+      hash: await hashApiKey(key),
+      credential: decision.credential,
+    });
   return key; // shown once
 }
 ```
@@ -123,7 +125,7 @@ const subject = await subjectFromCapability(token, {
 - The result is a `kind: 'link'` principal with one `{ on, roles, via: 'link' }` membership. It never holds a scope or global role.
 - `linkPolicy` returns the tenant's `LinkPolicy` (`maxLifetime`, `redeemers`, `once`). Passing the same policy to `signCapability` refuses to mint a link the resolver would refuse.
 - Never an unguessable id without expiry, and never a security-definer RPC that reads the guest page's rows.
-- The one exception is resolving a stored link. When links live in better-supabase's share-links block, its `resolve_share_link` is `security definer` and reads only the link table. `subjectFromShareLink(token, { shareLinks, links, ttl })` from `permdock/better-supabase` turns the row into the same link subject. The page's rows are then read through `exchangeCapability` and RLS, as for a signed link. `links` maps each `subjectType` to a resource and maps the row's role to PermDock roles. An unmapped type or role, and a revoked or expired row, are anonymous. A link pinned to a version is refused, because a capability reads the current rows; read it through better-supabase's `versions.getShared(token)`. See [row-backed links](https://permdock.com/docs/concepts/capabilities#row-backed-links).
+- The one exception is resolving a stored link. When links live in better-supabase's share-links block, its `resolve_share_link` is `security definer` and reads only the link table. `subjectFromShareLink(token, { shareLinks, links, ttl })` from `permdock/better-supabase` turns the row into the same link subject. The page's rows are then read through `exchangeCapability` and RLS, as for a signed link. `links` maps each subject type (`subject.type` from better-supabase 0.14, `subjectType` before it) to a resource and maps the row's role to PermDock roles. An unmapped type or role, and a revoked or expired row, are anonymous. A link pinned to a version is refused, because a capability reads the current rows; read it through better-supabase's `versions.getShared(token)`. See [row-backed links](https://permdock.com/docs/concepts/capabilities#row-backed-links).
 
 With Supabase, let RLS serve the link through an exchange, never the link token itself:
 

package/skills/permdock-data/references/queries-and-rls.md

@@ -36,9 +36,10 @@ pnpm exec permdock rls verify --introspect
 ```
 
 - List the scope instances a permission reaches in process with `permdock.permittedIds(permission, scope, { within })`, never a loop of `can` over memberships with a made-up row.
-- Generated policies call `permdock_has('<key>')` and one `permitted_<scope>_ids('<key>')` per declared scope, which Postgres runs once per statement. Hand-written policies that only need membership (an organization switcher) call `member_<scope>_ids()` instead of inventing a permission key. Trusted SQL that acts for a stored user (a job, a trigger, a deferred approval) calls `permdock_has_for(p_user, '<key>')` and `permitted_<scope>_ids_for(p_user, '<key>')` in `database` mode, or the generated `permitted_<resource>_rows_for`, never a hand-written function that rewrites `request.jwt.claims`. With `rls.rowHelpers`, a hand-written policy or function that needs the rows a permission reaches through the graph calls `permitted_<resource>_rows('<permission key>')` instead of restating closure walks, link hops and `includes`. A table's own `select` or `insert` policy calls the row-valued `permitted_<resource>_row(<table>, '<permission key>')` instead, so `insert ... returning` sees the new row. Hand-written policies and functions that apply no row condition call `permitted_<scope>_ids_by_permission('<permission key>')` or `permdock_has_permission('<permission key>')` instead of spelling a positional `#n` grant key. A screen or RPC that checks many permissions on one organization calls `permitted_<scope>_permission_keys(<id>)` once (or `(<id>, array['<key>', ...])` for a few keys) instead of one helper call per key. A role editor or admin screen lists a role's keys with `permdock_role_permissions(p_role, p_scope, p_tenant, p_scope_id)` (declared roles, and custom roles of the caller's tenant in `database` mode) and the catalog with `permdock_permission_keys()` (`permdock_permission_keys('<scope>')` for the keys a role on that scope can hold), instead of joining `role_permissions` and the custom-role tables by hand; server code reads any tenant's roles with `permdock_trusted_role_permissions`, granted through `rls.trustedReaders`. Set `--tenant-type` (or `rls.tenantType`, `rls.scopeTypes`) to the scope columns' types.
+- Generated policies call `permdock_has('<key>')` and one `permitted_<scope>_ids('<key>')` per declared scope, which Postgres runs once per statement. Hand-written policies that only need membership (an organization switcher) call `member_<scope>_ids()` instead of inventing a permission key. A policy that passes a user id, such as better-supabase's team sharing, calls `member_team_ids_of(<user>)` on Supabase: it answers only when the id is the caller's. Trusted SQL that acts for a stored user (a job, a trigger, a deferred approval) calls `permdock_has_for(p_user, '<key>')` and `permitted_<scope>_ids_for(p_user, '<key>')` in `database` mode, or the generated `permitted_<resource>_rows_for`, never a hand-written function that rewrites `request.jwt.claims`. With `rls.rowHelpers`, a hand-written policy or function that needs the rows a permission reaches through the graph calls `permitted_<resource>_rows('<permission key>')` instead of restating closure walks, link hops and `includes`. A table's own `select` or `insert` policy calls the row-valued `permitted_<resource>_row(<table>, '<permission key>')` instead, so `insert ... returning` sees the new row. A function that checks a known set of rows (one tenant's, a page, a batch) calls `permitted_<resource>_rows('<permission key>', <text[] of ids>)`, which reads only those ids, instead of the one-argument form, which reads the whole table, or a `permitted_<resource>_row` call per row. Hand-written policies and functions that apply no row condition call `permitted_<scope>_ids_by_permission('<permission key>')` or `permdock_has_permission('<permission key>')` instead of spelling a positional `#n` grant key. A screen or RPC that checks many permissions on one organization calls `permitted_<scope>_permission_keys(<id>)` once (or `(<id>, array['<key>', ...])` for a few keys) instead of one helper call per key. A role editor or admin screen lists a role's keys with `permdock_role_permissions(p_role, p_scope, p_tenant, p_scope_id)` (declared roles, and custom roles of the caller's tenant in `database` mode) and the catalog with `permdock_permission_keys()` (`permdock_permission_keys('<scope>')` for the keys a role on that scope can hold), instead of joining `role_permissions` and the custom-role tables by hand; server code reads any tenant's roles with `permdock_trusted_role_permissions`, granted through `rls.trustedReaders`. Set `--tenant-type` (or `rls.scopeTypes`, keyed by scope name or `tenant` and `team`) to the scope columns' types.
 - `--authorize database` (default) reads the membership tables per statement; map each under `rls.memberships.scopes.<scope>` with `columns` for its id and its ancestors', and `via` so roles with `for` apply: a column name, or `{ value: 'staff' }` when every row has that kind (never add a generated column for it). `--authorize jwt` reads token claims and stays stale until the token refreshes; keep the token lifetime at 3600 seconds or less (PD019).
 - When the role column holds values that are not role keys, give the membership source `role: { column, map: { value: 'role' } }`; a value mapped to `null` grants nothing. `permdock rls explain` prints the tables, membership sources, custom roles table and triggers a generate run binds to, without writing a file. `rls.seeds: 'function'` writes the `role_permissions` rows as `<schema>.seed()` instead of inserts; run `select <schema>.seed();` after each deploy, and PD054 checks the function body.
+- `rls verify --introspect` checks each `security definer` helper by its full signature, so every overload is checked on its own. A helper finding id names the signature (`helper-definer:permdock.permdock_has(text):helper`); write `rls.verify.ignore` entries with it.
 - `permdock rls verify --kind pgtap` writes `supabase/tests/permdock_rls.test.sql` (or `--out`) and, in `database` mode, inserts each fixture's memberships before it switches role.
 - The helpers narrow to the tenant claim (`rls.tenantClaim`) whenever the token carries one; the Supabase hook writes it from `activeFrom`. When the app takes the tenant from the URL and one session spans tenants, set `rls.tenants: 'all'` so the database admits every member tenant, and keep filtering each query by the URL's tenant.
 - `--policy-per-role` keeps one policy per role for review. `--custom-roles` (or `rls.customRoles: true`) resolves tenant-defined roles inside the `permdock_ceiling` view. In `database` mode, save a custom role with `permdock_replace_custom_role_grants(tenant, scope, scope_id, role, allow, deny, include)` and rename or delete it with `permdock_rename_custom_role_grants` and `permdock_delete_custom_role_grants`, never with hand-written `security definer` functions or direct writes; failures raise `22023` or `42501` with the reason as the `hint`. A platform custom role passes a null tenant and scope `global`; a shared custom role passes a null tenant and scope id at its scope. Seeds, jobs and backends with no member caller use the `permdock_trusted_*` variants, which keep the definition checks; grant `execute` on them to a backend role in a migration of your own, never to `authenticated`. Set `rls.customRoleWrites.requires` to the permission your role editor asserts (or `'manageRoles'`) so the database refuses members who may not manage roles (`manage-roles`).

package/skills/permdock-tenancy/references/ownership-and-custom-roles.md

@@ -79,7 +79,7 @@ type CustomRole = {
 
 - The ceiling of a scope is the code allows of the declared roles marked `assignable` in that scope. A custom role never exceeds it, and hosted grants never widen it.
 - An own allow inherits the conditions of the ceiling grants for that permission. To keep a narrower condition ("own posts only"), include the declared role that has it.
-- A resource may declare `levels: { own: { ownerId: principal.id }, team: { teamId: { in: principal.teamIds } }, all: {} }`. A grant `{ permission: 'job.read', level: 'team' }` ANDs that condition into the ceiling grant. An undeclared level, or a level on a collection action, is dropped as `unknown-level` and removes the permission; a level on a deny is `condition-not-allowed`. `permdock.assignableLevels(leaf)` lists the levels the subject may hand out.
+- A resource may declare `levels: { own: { ownerId: principal.id }, team: { teamId: { in: principal.teamIds } }, all: {} }`. A grant `{ permission: 'job.read', level: 'team' }` ANDs that condition into the ceiling grant. An undeclared level, or a level on a collection action, is dropped as `unknown-level` and removes the permission; a level on a deny is `condition-not-allowed`. `permdock.assignableLevels(leaf)` lists the levels the subject may hand out. Levels are unordered: holding `team` does not hand out `own`. Add `orderedLevels: true` to the resource when the levels nest from narrowest to widest in declaration order; a held level then also hands out every earlier one, and evaluation is unchanged.
 - An own deny removes the permission from this custom role only. Deny it in code when it must win across roles.
 - Pass a `CustomRoleSource` (`memoryCustomRoleSource(roles)` in tests), or a `CustomRoleSourceFactory` `(subject) => CustomRoleSource` when the source reads one principal's roles, as `customRoles` on `createPermDock` or any adapter. To add every role of a tenant on a role-management request, `await permdock.derive({ customRoles })` instead of building a second instance. Build it with `customRoleSource({ rolesFor })`, where `rolesFor(tenant)` reads every custom role of the tenant, not only the held ones: `assignableRoles` and `decideRoleChange` see only what the source returns. `{ read: 'held', policy }` skips the read on requests that never manage roles. Check it with `testCustomRoleSource(source, { every })`.
 - `permdock.assignableRoles({ tenant })` lists declared roles, then the tenant's custom roles whose every permission and level the subject may hand out at the custom role's scope. `decideRoleChange` assigns and revokes a custom role like a declared one, with no holder count; it inherits `for` and `exclusiveWith` from its included roles.
@@ -90,4 +90,4 @@ type CustomRole = {
 - A stored grant under a key renamed with `definePermissions(..., { renamed })` still resolves; `validateCustomRole` lists it in `renamed` as `{ from, to }`, and `permdock doctor` PD055 prints the `update` that rewrites it.
 - For generated RLS, add `--custom-roles` (or `rls.customRoles: true`) to `permdock rls generate`. Platform roles are rows with `scope = 'global'` and a null `tenant_id`, or the top-level `role_grants` claim in `jwt` mode. With levels, `custom_role_permissions` gains a `level` column and the claim writes `key@level`.
 - To adopt custom roles the app already stores in its own tables, set `rls.customRoles.from` and `rls.customRoleWrites.roles`, then run `permdock rls generate --backfill-out <migrations dir>/`. The migration saves each role through the trusted replace function, drops entries outside the ceiling with a warning, and skips roles that already have rows; never write the copy by hand ([backfill](https://permdock.com/docs/cli/rls#backfill-from-existing-tables)).
-- To keep the copy current instead of copying once, set `rls.customRoles.from.sync: 'trigger'`: after-row triggers on the app's permission and include tables rewrite the copy through the trusted replace function. The generated name guard on `rls.customRoleWrites.roles` refuses a tenant row named like a declared role (`declared-role`) or a shared role (`name-taken`). A stored entry is `<permission>[@<level>]`; check one with `parseCustomRoleEntry(policy, entry, { scope })` in process or `permdock_custom_role_entry_problem(p_scope, p_entry)` in SQL, which answer `unknown-permission`, `outside-ceiling` or `unknown-level`.
+- To keep the copy current instead of copying once, set `rls.customRoles.from.sync: 'trigger'`: after-row triggers on the app's permission and include tables rewrite the copy through the trusted replace function. Before-row triggers hold a signed-in write to the checks of `permdock_replace_custom_role_grants` against the copy as it stood before the statement, so a member who manages roles cannot add a permission they lack, even to a role they hold. A write path of your own calls the stable `permdock_custom_role_guard(p_tenant, p_scope, p_scope_id, p_role)` first, then `permdock_custom_role_beyond(p_tenant, p_scope, p_scope_id, p_allow, p_deny, p_include)` on the new entries only, from a `security definer` trigger that runs before the copy changes. The generated name guard on `rls.customRoleWrites.roles` refuses a tenant row named like a declared role (`declared-role`) or a shared role (`name-taken`). A stored entry is `<permission>[@<level>]`; check one with `parseCustomRoleEntry(policy, entry, { scope })` in process or `permdock_custom_role_entry_problem(p_scope, p_entry)` in SQL, which answer `unknown-permission`, `outside-ceiling` or `unknown-level`.

package/skills/permdock-wire/references/adapters.md

@@ -17,9 +17,7 @@ export const {
   requirePermission,
   PermDockProvider,
   permdockHandler,
-} = createPermDock(policy, {
-  subject: async () => getUser(),
-});
+} = createPermDock(policy, { subject: async () => getUser() });
 ```
 
 Needs Next.js 16.3 or later. Guard with `getPermission(permissions.post.update, post)` or `assert`. For a page or Server Action that must stop on a denial, `await requirePermission(permission, data, { tenant })` calls `forbidden()` (or `unauthorized()` for a signed-out user); enable `experimental.authInterrupts` and add `app/forbidden.tsx` and `app/unauthorized.tsx`. When only part of a page is gated, let a Server Component `assert` inside `<PermissionBoundary denied={...} approval={...}>` from `permdock/next/client` (with a `Suspense` inside it); `usePermissionBoundary()` in the fallback gives the permission, the approval `token` and `retry()`. Client components use `permdock/react` inside the server `PermDockProvider`, which never awaits: it streams a `snapshotPromise`, and permission hooks answer `pending` until it lands (add `suspend` to make them suspend).
@@ -104,9 +102,7 @@ import { createPermDock } from "permdock/authzen";
 
 export const { permdockHandler } = createPermDock(policy, {
   subject: fromBearer,
-  resources: {
-    post: { data: (id) => loadPost(id), list: () => listPosts() },
-  },
+  resources: { post: { data: (id) => loadPost(id), list: () => listPosts() } },
 });
 ```
 
@@ -137,7 +133,7 @@ import { PermDockProvider, usePermission } from "permdock/react-native";
 
 `subjectId` is required: the signed-in user's id, or `null` when signed out. A stored snapshot of another principal is cleared. `storage` is `{ getItem, setItem, removeItem }`; `secureStoreStorage(SecureStore)` and `mmkvStorage(mmkv)` wrap Expo SecureStore and MMKV. `snapshotUrl` revalidates in the background; `subscribeForeground={appStateForeground(AppState)}` revalidates on return to the foreground. For Expo Router guards use `usePermissionGuard(permission, data?)`, which is `false` while `pending`, and `useSnapshotReady()` for a splash screen. `permdock.clear()` drops the persisted snapshot on sign-out. Do not import `policy.ts` on the client.
 
-To answer guards from synced rows, write `localSnapshotManifest(policy)` (from `permdock`) to a JSON file at build time and pass `source={localSnapshot({ manifest, read, subscribe })}`. `read()` returns `{ principal: { id, tenant, roles, memberships, attributes }, customRoles }` from the local database; `subscribe` re-reads on row changes. It decides like the server snapshot except relation grantees (server-only) and the assignable lists (empty). Never import `policy.ts` into the app for this. Docs: [local snapshot](https://permdock.com/docs/adapters/react-native#local-snapshot).
+To answer guards from synced rows, write `localSnapshotManifest(policy)` (from `permdock`) to a JSON file at build time and pass `source={localSnapshot({ manifest, read, subscribe })}`. `read()` returns `{ principal: { id, tenant, roles, memberships, attributes }, customRoles }` from the local database; `subscribe` re-reads on row changes. It decides like the server snapshot except relation grantees (server-only). With a `tenant`, the assignable roles, permissions and levels match the server's for the same rows. Never import `policy.ts` into the app for this. Docs: [local snapshot](https://permdock.com/docs/adapters/react-native#local-snapshot).
 
 For an offline app on PowerSync, set `powersync: { out: 'sync-config.yaml' }` in `permdock.config.ts` and run `permdock powersync generate`: one edition 3 Sync Stream per resource, from the `rls.tables` and `rls.memberships` the RLS generator reads. It under-syncs, never over-syncs: a resource with a deny grant gets no stream, and a grant with a global role, approval, break-glass, validity, request context or a condition without a Sync Streams form syncs nothing, each with a warning. The app reads what does not sync from the server. It also writes `permdock_*` streams for the user's own membership, global-role and custom-role rows; with `powersync.manifest` set it writes the manifest too, and `powerSyncSource(db, { manifest, queries, read })` from `permdock/react-native` builds the local snapshot from `db.watch` queries. `permdock powersync verify` fails when a stream holds a fixture row the policy denies; doctor PD058 flags a stale file or manifest. Doctor PD065 lists server-only grants read from React Native code, which the device denies offline. Docs: [`permdock powersync`](https://permdock.com/docs/cli/powersync).
 
@@ -193,11 +189,13 @@ export const { middleware, protect } = createPermDock(policy, {
   subject: ({ store }) => store.user ?? null,
 });
 
-const app = new Elysia().use(middleware()).delete("/posts/:id", handler, {
-  beforeHandle: protect(permissions.post.delete, ({ params }) =>
-    loadPost(params.id),
-  ),
-});
+const app = new Elysia()
+  .use(middleware())
+  .delete("/posts/:id", handler, {
+    beforeHandle: protect(permissions.post.delete, ({ params }) =>
+      loadPost(params.id),
+    ),
+  });
 ```
 
 Fetch-native plugin via `derive`. Denials are `403 application/problem+json`; anonymous callers get `401` plus `WWW-Authenticate`. For `.ws` routes, `connection(ws, { permission })` in `open` returns the socket's connection (memoised); it closes the socket with `1008` when revoked.
@@ -278,9 +276,7 @@ import { createPermDock } from "permdock/node";
 
 export const { getPermDock, protect, send, permdockHandler } = createPermDock(
   policy,
-  {
-    subject: (req) => userFromCookie(req.headers.cookie),
-  },
+  { subject: (req) => userFromCookie(req.headers.cookie) },
 );
 ```
 
@@ -360,9 +356,7 @@ import { PermDockProvider, Protected, usePermission } from 'permdock/solid';
 ```ts
 import { instrument } from "permdock/otel";
 
-instrument(permdock, {
-  logger: { info: console.info, warn: console.warn },
-});
+instrument(permdock, { logger: { info: console.info, warn: console.warn } });
 ```
 
 HTTP adapters accept the same options as `otel`. `@opentelemetry/api` is optional; without it the adapter writes only through `logger`.
@@ -507,7 +501,7 @@ const subject = subjectFromSupabase(claims, {
 
 Write the claims with `permdock supabase hook generate`; `permdock supabase inspect --out` writes the manifest (helper names, tenant claim, budget, claims written) that `authorizationProvider` from `permdock/better-supabase` turns into better-supabase's `authorization` config. No `@supabase/supabase-js` peer. Pair with `permdock rls generate`, or keep SQL as authority and run `permdock rls verify --db-url-stdin` against `sqlFunction` twins ([database-first](https://permdock.com/docs/adapters/rls)); the generic RLS workflow is in the `permdock-data` skill.
 
-With better-supabase, set `authorization: authorizationProvider({ manifest, catalog })` in `better-supabase.config.ts` (with `rls.customRoles` its `canAssign` and `canAssignFor` call `permdock_can_assign_any` and its `_for` form, so custom roles are assignable through better-supabase; regenerate the manifest after turning custom roles on), pass `authorizer({ policy })` to the server (`createNext`, `createHono`, `createMcp`) so every `permission` a resource, action, route guard or tool declares is decided by PermDock from the verified claims (`operations` maps tables for `permissions: true`; a missing or anonymous claim denies), build bucket and topic `access` policies with `bucketPolicy` and `topicPolicy`, and map its session with `subjectFromBetterSupabase(session)` (all from `permdock/better-supabase`): the active tenant's `features` become `principal.plans`. Pass `plans: { keys }` when better-supabase's `entitlements.claim.keys` shortens feature keys, and `apiKeys: { permissions, manifest }` so an `apiKey` session maps to the key's credential subject instead of the anonymous one. For `createMcp` tools, put the permission in `meta` and spread `toolPolicy({ permdock })` into the options: tools without one are hidden and refused, and approval-required calls are refused because `createMcp` collects no approvals. Wrap a `CredentialProvider` with `credentialGuard(provider, { permdock, use, revoke? })` so PermDock decides each token use. `authorizationProvider({ ..., approver })` lets holders of that permission approve AI tool calls, never their own. `approvers: { 'ai-tool': holder(p), 'support-session': ..., 'invoice.send': ... }` fills `isApprover` through `permdock_is_approver` (needs `rls.approvals`); only `user()`, `holder()` and `anyOf()` approvers, and a kind it does not name has no approver. `accessReviewApplier({ client, reviews, policy, demoteTo?, email?, permdockFor? })` applies a review's revoked items: `update_member_role` to the `demoteTo` role when that role lacks the permission, else `remove_member`, plus `revoke_invitation` for the member's matching invitations, then `markApplied`; pass the reviewer's client so the blocks' own checks run. better-supabase's `createAgentRuntime({ toolApproval })` takes `toolApproval` from `permdock/ai-sdk` as it is. Validate its claims with `betterSupabase.claims(supabaseClaims().extend(appSchema))` (`supabaseClaims` from `permdock/supabase`, any Standard Schema as `appSchema`) instead of a hand-written copy of the claim shape. A `supabase.hook.claims` function that needs the user's organizations calls `<schema>.member_organization_ids_for(user_id)` (generated by `rls generate`, executable by `supabase_auth_admin` only) instead of querying the membership tables itself. A token Supabase's OAuth server issued to a third-party app (`client_id`) becomes an `oauth-client` actor limited to its `scope`; `deny(permission, { to: actor('oauth-client') })` keeps such apps out, in the app and, through `rls generate`, in Postgres. A better-supabase support session (`act.kind: 'support'`) is actor kind `support` with `sessionId` and `readOnly`, and `actingAs` (`act.kind: 'impersonation'`) is kind `impersonation`; neither has a delegation, so they reach nothing until a policy delegation names `actor('support')` or `actor('impersonation')`, and `readOnly: true` (also when `read_only` is absent) narrows that to read-only permissions. Generated RLS reads memberships, not `act`, so a support token sent to the Data API writes as the user: add a restrictive `for update` (and `insert` / `delete`) policy per writable table that requires `act ->> 'read_only' = 'false'` when `act` is a support or session level ([support access](https://permdock.com/docs/guides/support-access)). With `rls.anonymousSignIns: 'deny'`, pass `anonymousSignIns: 'deny'` to the subject mapper too (doctor PD057). Check a deployed database against the generated policies with `permdock rls verify --introspect`.
+With better-supabase, set `authorization: authorizationProvider({ manifest, catalog })` in `better-supabase.config.ts` (with `rls.customRoles` its `canAssign` and `canAssignFor` call `permdock_can_assign_any` and its `_for` form, so custom roles are assignable through better-supabase; regenerate the manifest after turning custom roles on), pass `authorizer({ policy })` to the server (`createNext`, `createHono`, `createMcp`) so every `permission` a resource, action, route guard or tool declares is decided by PermDock from the verified claims (`operations` maps tables for `permissions: true`; a missing or anonymous claim denies), build bucket and topic `access` policies with `bucketPolicy` and `topicPolicy`, and map its session with `subjectFromBetterSupabase(session)` (all from `permdock/better-supabase`): the active tenant's `features` become `principal.plans`. Pass `plans: { keys }` when better-supabase's `entitlements.claim.keys` shortens feature keys, and `apiKeys: { permissions, manifest }` so an `apiKey` session maps to the key's credential subject instead of the anonymous one. For `createMcp` tools, put the permission in `meta` and spread `toolPolicy({ permdock })` into the options: tools without one are hidden and refused, and approval-required calls are refused because `createMcp` collects no approvals. Wrap a `CredentialProvider` with `credentialGuard(provider, { permdock, use, revoke? })` so PermDock decides each token use. `authorizationProvider({ ..., approver })` lets holders of that permission approve AI tool calls, never their own. `approvers: { 'ai-tool': holder(p), 'support-session': ..., 'invoice.send': ... }` fills `isApprover` through `permdock_is_approver` (needs `rls.approvals`); only `user()`, `holder()` and `anyOf()` approvers, and a kind it does not name has no approver. `accessReviewApplier({ client, reviews, policy, demoteTo?, email?, permdockFor? })` applies a review's revoked items: `update_member_role` to the `demoteTo` role when that role lacks the permission, else `remove_member`, plus `revoke_invitation` for the member's matching invitations, then `markApplied`; pass the reviewer's client so the blocks' own checks run. better-supabase's `createAgentRuntime({ toolApproval })` takes `toolApproval` from `permdock/ai-sdk` as it is. Validate its claims with `betterSupabase.claims(supabaseClaims().extend(appSchema))` (`supabaseClaims` from `permdock/supabase`, any Standard Schema as `appSchema`) instead of a hand-written copy of the claim shape. A `supabase.hook.claims` function that needs the user's organizations calls `<schema>.member_organization_ids_for(user_id)` (generated by `rls generate`, executable by `supabase_auth_admin` only) instead of querying the membership tables itself. With a scope named `team` or `teams`, `authorizationProvider` fills better-supabase's `teamIdsOf` with `<schema>.member_team_ids_of(user)`, which answers only for the caller, so with `blocks.access.model: 'provider'` better-supabase's `team_ids_of()` and team-sharing policies read PermDock's memberships. A token Supabase's OAuth server issued to a third-party app (`client_id`) becomes an `oauth-client` actor limited to its `scope`; `deny(permission, { to: actor('oauth-client') })` keeps such apps out, in the app and, through `rls generate`, in Postgres. A better-supabase support session (`act.kind: 'support'`) is actor kind `support` with `sessionId` and `readOnly`, and `actingAs` (`act.kind: 'impersonation'`) is kind `impersonation`; neither has a delegation, so they reach nothing until a policy delegation names `actor('support')` or `actor('impersonation')`, and `readOnly: true` (also when `read_only` is absent) narrows that to read-only permissions. Generated RLS reads memberships, not `act`, so a support token sent to the Data API writes as the user: add a restrictive `for update` (and `insert` / `delete`) policy per writable table that requires `act ->> 'read_only' = 'false'` when `act` is a support or session level ([support access](https://permdock.com/docs/guides/support-access)). With `rls.anonymousSignIns: 'deny'`, pass `anonymousSignIns: 'deny'` to the subject mapper too (doctor PD057). Check a deployed database against the generated policies with `permdock rls verify --introspect`.
 
 The other better-supabase slots, all from `permdock/better-supabase` ([better-supabase](https://permdock.com/docs/adapters/better-supabase)): `hookCan(permdock)` and `handlerCan({ getPermDock })` are the `can` options of `authorizeHook` and `protectWebHandler` in `better-supabase/workflow-sdk`; they decide with no row, so a permission with a row condition denies there and is checked inside the handler, and `handlerCan` answers `undefined` (401) without a signed-in principal. `supportPolicy({ policy, options?, writable?, approval?, approved? })` is the `authorize` option of `supportSessions`; it decides each start with `decideSupportSession` as the admin, and an `approval-required` start passes only once `approved(input, pending)` returns `{ approvedBy }` for an approver other than the admin. `subscriberPolicy({ policy, principals, events, row?, sender? })` filters outbox, webhook or realtime subscribers to those who may read the event (exact type, then the longest `prefix.*`, then `*`; a type with no entry reaches no one). `principalSource({ claims, identities? })` is a `PrincipalSource` over the claims better-supabase mints, for `decideFor`, `subscribersFor` and delivery; only links the app created through a signed-in flow or a verified address go in `identities`. `authorizationHooks({ policy, claims, service?, principals?, events?, approvers?, support?, tickets? })` is the `authorization` option of `createServer`: it answers automation publish and run-as, delegated OAuth scopes, `approverOf`, identities, delivery audiences, support sessions and run tickets from the claims better-supabase mints now, never from the request.
 
@@ -523,7 +517,8 @@ Supabase specifics for generated RLS (the generic flags and parity checks are in
 - Under `migra`, generate `--split helpers,seeds,policies,hook --out supabase/schemas/identity/056_permdock_{part}.sql --seeds-out supabase/migrations/` and write the schema and function privileges and the `security_invoker` view option with `--grants-out` into a migration created by `supabase migration new` after the first `db diff`; `db diff` drops those, so never append them to a migration by hand. Table grants and policies stay in the schema files, where `db diff` keeps them. Keep the helpers part ahead of every file that calls the helpers in `schema_paths` (`permdock doctor` PD042, PD043).
 - `--authorize jwt` reads the hook's claims: enable the printed `[auth.hook.custom_access_token]` stanza in `supabase/config.toml`. The generated hook writes the canonical `memberships` claim from the `rls.memberships.scopes` tables, so do not hand-write one.
 - For more than one membership table, declare `tableMembershipSource` / `junctionMembershipSource` sources once (from `permdock/supabase`, with a `query` on the server), pass the array as `memberships` (wrapped in `claimsFirst(sources, { version: authzVersion({ query }) })` to trust the token until it is truncated or stale), put the same sources under `supabase.hook.memberships` in `permdock.config.ts`, and run `permdock supabase hook generate`; add the printed `config.toml` block (`jwt_expiry = 900`). List member-removal and payout permissions in `definePolicy({ fresh })`.
-- When the server has only supabase-js (no `SqlQuery`), never re-read memberships, global roles or custom roles with the admin client: grant `subject_for(p_user)` and `authz_version_for(p_user)` (written next to the hook) to the backend role, expose them through `public` wrappers when `permdock` is not an exposed schema, and use `postgrestSources(admin, { schema, fn, versionFn, policy })`: `claimsFirst(sources.memberships)` (with `onStale: 'reread'` a fresh token costs one version call, and with `policy` a token that claims a custom role costs one `subject_for` call), `customRoles: sources.customRoles(principal)`, and `await sources.subject(userId)` for a job acting for a stored user.
+- When the server has only supabase-js (no `SqlQuery`), never re-read memberships, global roles or custom roles with the admin client: grant `subject_for(p_user)` and `authz_version_for(p_user)` (written next to the hook) to the backend role, expose them through `public` wrappers when `permdock` is not an exposed schema, and use `postgrestSources(admin, { schema, fn, versionFn, policy })`: `claimsFirst(sources.memberships)` (with `onStale: 'reread'` a fresh token costs one version call, and with `policy` a token that claims a custom role costs one `subject_for` call), `customRoles: sources.customRoles(principal)`, and `await sources.subject(userId)` for a job acting for a stored user. Create `postgrestSources` and the `claimsFirst` source once at module scope, never per request or per cache scope: they keep no answers, and `getPermDock` shares each read within one instance.
+- When a page builds many instances (Next.js `'use cache: private'` islands, PPR) or an API serves many `GET`s per user, add `versions: memoryVersionCache({ maxStaleMs: 5_000 })` to `claimsFirst(sources.memberships, { onStale: 'reread' })` at module scope. Rendering and `GET` / `HEAD` / `OPTIONS` use intent `read` and share one version call per `maxStaleMs`; `protectAction`, other HTTP methods and core `getPermDock` use `write` and read live. Before a mutation outside `protectAction` in Next.js, call `getPermDock({ intent: 'write' })`. After a role change call `versions.evict(userId)` ([freshness and the version cache](https://permdock.com/docs/adapters/supabase#freshness-and-the-version-cache)).
 - When a role table stores a role id (`user_roles.role_id`, `organization_users.role_id` referencing `roles`), read the key through it with `{ through: 'roles', on: { role_id: 'id' }, column: 'key' }`: in `rls.roles`, in `tableMembershipSource` `columns.role` or `junctionMembershipSource` `roles`, and in an `rls.memberships` table's `role`. Never copy keys into the membership table. Keep tenant custom-role keys apart from declared role names.
 - When one membership row holds roles in several columns (a `tier` and a `role_id`), list them instead of building a union view: `role: ['tier', { through: 'roles', on: { role_id: 'id' }, column: 'key' }]` in `rls.memberships` and `tableMembershipSource` `columns.role`, `roles: { sources: [...] }` in `junctionMembershipSource`. The row holds every non-null key, and the holder-count triggers stay on the real table.
 - When a membership table names a profile instead of a login (`customer_contacts.contact_profile_id` referencing `contact_profiles`, whose `user_id` is the login), read the user through it with `junctionMembershipSource` `user` or `tableMembershipSource` `columns.user`: `{ through: 'contact_profiles', on: { contact_profile_id: 'id' }, column: 'user_id' }`. Never copy `user_id` onto the membership rows. Keep `contact_profiles.user_id` server-owned (PD028).
@@ -540,9 +535,7 @@ import { createPermDock } from "permdock/supabase/middleware";
 const { withPermDock, permdockHandler } = createPermDock(policy, {
   subject: (ctx) =>
     subjectFromSupabase(ctx.jwtClaims, {
-      claims: {
-        roles: "user_role",
-      },
+      claims: { roles: "user_role" },
       declared: ["member", "admin"],
     }),
 });

package/dist/catalog-BCCjSAdH.js

@@ -1 +0,0 @@
-export { t as catalogFile, n as runCatalog } from "./catalog-D69WhFii.js";

package/dist/collect-k_Dulxr5.js

@@ -1 +0,0 @@
-export { r as runCollect } from "./collect-BaWeMjwV.js";