permdock 0.3.1 → 0.4.0

package/dist/{version-BvacVTZR.js → version-BEogC-rB.js}

@@ -1,4 +1,4 @@
-import { t as packageRoot } from "./package-root-zGkxO3oN.js";
+import { t as packageRoot } from "./package-root-DtNnpmUd.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/cli/version.ts

package/dist/{views-Soe7bGSC.js → views-CJsrBS1f.js}

@@ -1,3 +1,4 @@
+import { t as describe } from "./describe-Cgkp7eP0.js";
 //#region src/client/views.ts
 function permissionSet(store, permissions, data) {
 	const granted = [];
@@ -64,6 +65,12 @@ function protectedView(local, root, permission, data, scoped) {
 		slot: "pending"
 	};
 	const decision = state.decision;
+	if (decision.outcome === "approval-required") return {
+		allowed: false,
+		status: state.status,
+		decision,
+		slot: "approval"
+	};
 	if (!state.allowed || decision.outcome !== "granted") return {
 		...state,
 		slot: "fallback"
@@ -91,5 +98,20 @@ function approvalHandle(store, decision) {
 		request: (note) => store.requestApproval(decision, note)
 	};
 }
+function slotContent(slot, own, defaults) {
+	switch (slot) {
+		case "pending": return own.pending ?? defaults?.pending;
+		case "fallback": return own.fallback ?? defaults?.fallback;
+		case "approval": return own.approval ?? own.fallback ?? defaults?.approval ?? defaults?.fallback;
+		default: return slot;
+	}
+}
+/** `describe` with the provider's `messages`; a call's own `messages` win. */
+function describeWith(messages) {
+	return (decision, options) => describe(decision, messages === void 0 || options?.messages !== void 0 ? options : {
+		...options,
+		messages
+	});
+}
 //#endregion
-export { protectedView as a, subjectView as c, permissionSet as i, tenantView as l, filterResult as n, rolesView as o, livePermDock as r, scopedTenant as s, approvalHandle as t };
+export { permissionSet as a, scopedTenant as c, tenantView as d, livePermDock as i, slotContent as l, describeWith as n, protectedView as o, filterResult as r, rolesView as s, approvalHandle as t, subjectView as u };

package/dist/{vocabulary-DA8a8zif.d.ts → vocabulary-hhEFLFoL.d.ts}

@@ -1,7 +1,16 @@
-import { n as ActionMeta } from "./permissions-DttnqqxC.js";
+import { A as WithX, O as AppDataSchema, n as ActionMeta } from "./permission-types-Dg39z9Kv.js";
 //#region src/core/vocabulary.d.ts
 declare const ROLE_KIND: "role";
 declare const PLAN_KIND: "plan";
+/** `defineRoles` and `definePlans` options. */
+type VocabularyOptions<X = never> = {
+  /**
+   * A Standard Schema for every leaf's `meta.x`, validated synchronously at
+   * definition time. On a role tree it also checks the `meta.x` of custom
+   * roles a `RoleSource` returns; an invalid one is dropped, not the role.
+   */
+  readonly x?: AppDataSchema<X>;
+};
 /**
  * A role's metadata. `audience` names the surface its holders use (`'staff'`,
  * `'portal'`, `'platform'`); `permdock.audiences()` lists the distinct
@@ -43,14 +52,14 @@ type Vocabulary = {
   readonly roles?: RoleTree;
   readonly plans?: PlanTree;
 };
-type InferRoleTree<Input> = { readonly [K in keyof Input & string]: Role<K>; };
-type InferPlanTree<Input> = { readonly [K in keyof Input & string]: Plan<K>; };
+type InferRoleTree<Input, X = never> = { readonly [K in keyof Input & string]: WithX<Role<K>, X>; };
+type InferPlanTree<Input, X = never> = { readonly [K in keyof Input & string]: WithX<Plan<K>, X>; };
 declare function isRole(value: unknown): value is Role;
 declare function isPlan(value: unknown): value is Plan;
-declare function defineRoles<const Input extends Record<string, RoleInit>>(input: Input): InferRoleTree<Input>;
-declare function definePlans<const Input extends Record<string, PlanInit>>(input: Input): InferPlanTree<Input>;
+declare function defineRoles<const Input extends Record<string, RoleInit>, X = never>(input: Input, options?: VocabularyOptions<X>): InferRoleTree<Input, X>;
+declare function definePlans<const Input extends Record<string, PlanInit>, X = never>(input: Input, options?: VocabularyOptions<X>): InferPlanTree<Input, X>;
 declare function listRoles(tree: RoleTree | undefined): readonly Role[];
 declare function listPlans(tree: PlanTree | undefined): readonly Plan[];
 declare function findRole(tree: RoleTree | undefined, key: string): Role | undefined;
 //#endregion
-export { RoleTree as a, defineRoles as c, isRole as d, listPlans as f, RoleMeta as i, findRole as l, PlanTree as n, Vocabulary as o, listRoles as p, Role as r, definePlans as s, Plan as t, isPlan as u };
+export { RoleTree as a, definePlans as c, isPlan as d, isRole as f, RoleMeta as i, defineRoles as l, listRoles as m, PlanTree as n, Vocabulary as o, listPlans as p, Role as r, VocabularyOptions as s, Plan as t, findRole as u };

package/dist/vue/index.d.ts

@@ -1,36 +1,39 @@
-import { Ft as TokenVerifier, Mr as Membership, Tt as Snapshot, Yn as Decision } from "../policy-IB6yxpC3.js";
-import { f as Permission } from "../permissions-DttnqqxC.js";
-import { r as Role } from "../vocabulary-DA8a8zif.js";
-import { n as requiredPlans } from "../problem-details-DX075l9V.js";
-import { i as describe } from "../describe-DMYiCjJV.js";
+import { Dr as Membership, an as Snapshot, ir as Decision, rr as ApprovalRequiredDecision, ut as TokenVerifier } from "../policy-types-sp9P1iIV.js";
+import { d as Permission } from "../permission-types-Dg39z9Kv.js";
+import { r as Role } from "../vocabulary-hhEFLFoL.js";
+import { n as requiredPlans } from "../problem-details-rIIo8B2C.js";
+import { i as describe, r as DescribeOptions, t as DecisionDescription } from "../describe-C3ldA9os.js";
 import { t as PermissionBoundaryState } from "../boundary-BmHxVH1J.js";
 import { t as approvalHeaders } from "../headers-Cf-zWvsO.js";
-import { a as FilterResult, c as SubjectView, i as ClientStatus, l as TenantView, n as ApprovalState, o as PermissionSet, r as ClientPermDock, s as PermissionState, t as ApprovalHandle, u as UseRolesOptions } from "../types-CKNSyIf_.js";
-import { ComputedRef, DefineComponent, MaybeRefOrGetter, Plugin } from "vue";
+import { a as ClientPermDock, c as PermissionSet, d as SubjectView, f as TenantView, i as ApprovalState, l as PermissionState, o as ClientStatus, p as UseRolesOptions, r as ApprovalHandle, s as FilterResult, u as ProviderOptionsBase } from "../store-9KO4BlkB.js";
+import { ComputedRef, DefineComponent, MaybeRefOrGetter, Plugin, VNode } from "vue";
 //#region src/vue/types.d.ts
-type PermDockPluginOptions = {
+type PermDockPluginOptions = ProviderOptionsBase & {
   /**
    * A ref or getter re-hydrates the store when it changes; a promise keeps
    * the store `pending` until it settles (await the same promise in an async
    * `setup` under `<Suspense>`).
    */
   readonly snapshot: MaybeRefOrGetter<Snapshot | string> | PromiseLike<Snapshot | string>;
-  /**
-   * The AuthZEN evaluations endpoint for checks the snapshot cannot answer.
-   * `false` never calls one: such a check is denied with reason `server-only`.
-   */
-  readonly endpoint?: string | false;
-  /** Where `refresh()` fetches a fresh snapshot. Defaults to `endpoint`. */
-  readonly snapshotUrl?: string;
-  readonly approvals?: string;
   /** A ref or getter switches the active tenant (`refresh({ tenant })`) when it changes. */
   readonly tenant?: MaybeRefOrGetter<string | undefined>;
-  readonly fetch?: typeof fetch;
   /** Read on every request: a ref or getter carries a rotated token without rebuilding the store. */
   readonly headers?: MaybeRefOrGetter<Readonly<Record<string, string>> | undefined>;
-  readonly maxAge?: number;
   /** Read on every verification; set it at install to verify signed snapshots. */
   readonly verifier?: MaybeRefOrGetter<TokenVerifier | undefined>;
+  /** What every `<Protected>` renders for a slot it leaves out. */
+  readonly defaults?: PermDockDefaults;
+};
+type SlotOutput = VNode | VNode[] | string | null;
+/** Render functions for the `<Protected>` slots a component leaves out; they get the slot props. */
+type PermDockDefaults = {
+  readonly pending?: () => SlotOutput;
+  readonly fallback?: (props: {
+    readonly decision: Decision;
+  }) => SlotOutput;
+  readonly approval?: (props: {
+    readonly decision: ApprovalRequiredDecision;
+  }) => SlotOutput;
 };
 //#endregion
 //#region src/vue/composables.d.ts
@@ -53,6 +56,8 @@ export declare function useAssignablePermissions(options?: MaybeRefOrGetter<{
 }>): ComputedRef<readonly Permission[]>;
 export declare function useSubject(): ComputedRef<SubjectView>;
 export declare function useApproval(decision: MaybeRefOrGetter<Decision>): ComputedRef<ApprovalHandle>;
+/** `describe` with the plugin's `messages`; a call's own `messages` win. */
+export declare function useDescribe(): (decision: Decision, options?: DescribeOptions) => DecisionDescription;
 //#endregion
 //#region src/vue/boundary.d.ts
 /**
@@ -76,4 +81,4 @@ type ProtectedProps = {
 };
 export declare const Protected: DefineComponent<ProtectedProps>;
 //#endregion
-export { type ApprovalHandle, type ApprovalState, type ClientPermDock, type ClientStatus, type FilterResult, type PermDockPluginOptions, type PermissionBoundaryState, type PermissionSet, type PermissionState, type ProtectedProps, type SubjectView, type TenantView, type UseRolesOptions, approvalHeaders, describe, requiredPlans };
+export { type ApprovalHandle, type ApprovalState, type ClientPermDock, type ClientStatus, type FilterResult, type PermDockDefaults, type PermDockPluginOptions, type PermissionBoundaryState, type PermissionSet, type PermissionState, type ProtectedProps, type SubjectView, type TenantView, type UseRolesOptions, approvalHeaders, describe, requiredPlans };

package/dist/vue/index.js

@@ -1,13 +1,14 @@
-import { r as requiredPlans } from "../problem-details-_AMOYz-w.js";
-import { t as describe } from "../describe-B_gVZEVi.js";
+import { r as requiredPlans } from "../problem-details-DECUnXAn.js";
+import { t as describe } from "../describe-Cgkp7eP0.js";
 import { t as approvalHeaders } from "../headers-BZSDieNT.js";
-import { i as isPromiseLike } from "../store-options-ByhZq1jV.js";
-import { a as protectedView, c as subjectView, i as permissionSet, l as tenantView, n as filterResult, o as rolesView, r as livePermDock, s as scopedTenant, t as approvalHandle } from "../views-Soe7bGSC.js";
+import { i as isPromiseLike } from "../store-options-CbUHDoSe.js";
+import { a as permissionSet, c as scopedTenant, d as tenantView, i as livePermDock, l as slotContent, n as describeWith, o as protectedView, r as filterResult, s as rolesView, t as approvalHandle, u as subjectView } from "../views-CJsrBS1f.js";
 import { n as boundaryFallback, t as boundaryDigest } from "../boundary-BM8a_P6E.js";
-import { n as switchTenant, t as providerStore } from "../provider-store-Cfbvo4DE.js";
+import { n as switchTenant, t as providerStore } from "../provider-store-Ctt-81Ni.js";
 import { computed, defineComponent, effectScope, getCurrentScope, inject, isRef, onErrorCaptured, onScopeDispose, provide, shallowRef, toValue, watch } from "vue";
 //#region src/vue/context.ts
 const permDockKey = Symbol("permdock");
+const permDockUiKey = Symbol("permdock-ui");
 //#endregion
 //#region src/vue/composables.ts
 function useStore() {
@@ -87,6 +88,10 @@ function useApproval(decision) {
 		return approvalHandle(store, toValue(decision));
 	});
 }
+/** `describe` with the plugin's `messages`; a call's own `messages` win. */
+function useDescribe() {
+	return describeWith(inject(permDockUiKey, {}).messages);
+}
 //#endregion
 //#region src/vue/boundary.ts
 const boundaryKey = Symbol("permdock-boundary");
@@ -154,6 +159,10 @@ const permdockPlugin = { install(app, options) {
 		store.dispose();
 	});
 	app.provide(permDockKey, store);
+	app.provide(permDockUiKey, {
+		defaults: options.defaults,
+		messages: options.messages
+	});
 } };
 //#endregion
 //#region src/vue/protected.ts
@@ -176,6 +185,7 @@ const Protected = defineComponent({
 	setup(props, { slots }) {
 		const local = usePermission(() => props.permission, () => props.data);
 		const root = usePermDock();
+		const { defaults } = inject(permDockUiKey, {});
 		const scoped = computed(() => scopedTenant(root, props.tenant));
 		return () => {
 			const view = protectedView({
@@ -183,9 +193,15 @@ const Protected = defineComponent({
 				status: local.status.value,
 				decision: local.decision.value
 			}, root, props.permission, props.data, scoped.value);
+			const own = {
+				pending: slots["pending"],
+				fallback: slots["fallback"],
+				approval: slots["approval"]
+			};
 			switch (view.slot) {
-				case "pending": return slots["pending"]?.() ?? null;
-				case "fallback": return slots["fallback"]?.({ decision: view.decision }) ?? null;
+				case "pending": return slotContent("pending", own, defaults)?.() ?? null;
+				case "fallback": return slotContent("fallback", own, defaults)?.({ decision: view.decision }) ?? null;
+				case "approval": return slotContent("approval", own, defaults)?.({ decision: view.decision }) ?? null;
 				case "default": return slots["default"]?.({ decision: view.decision }) ?? null;
 				default: return view;
 			}
@@ -193,4 +209,4 @@ const Protected = defineComponent({
 	}
 });
 //#endregion
-export { PermissionBoundary, Protected, approvalHeaders, describe, permdockPlugin, requiredPlans, useApproval, useAssignablePermissions, useAssignableRoles, useFilter, useMemberships, usePermDock, usePermission, usePermissionBoundary, usePermissions, useRoles, useSubject, useTenant };
+export { PermissionBoundary, Protected, approvalHeaders, describe, permdockPlugin, requiredPlans, useApproval, useAssignablePermissions, useAssignableRoles, useDescribe, useFilter, useMemberships, usePermDock, usePermission, usePermissionBoundary, usePermissions, useRoles, useSubject, useTenant };

package/dist/watch-C8TpsAl4.js

@@ -0,0 +1,2 @@
+import { n as createCollectScheduler } from "./watch-zeucB7eF.js";
+export { createCollectScheduler };

package/dist/{watch-DVBJ9cBq.js → watch-zeucB7eF.js}

@@ -1,7 +1,7 @@
 import { i as describeError } from "./errors-CWfoNg9N.js";
-import { t as defaultSrcPath } from "./files-DWUN9PzI.js";
-import { r as runCollect } from "./collect-DSTE3ml9.js";
-import { n as isConfigFile, r as loadConfig } from "./config-BJiM-xAm.js";
+import { t as defaultSrcPath } from "./files-D_JIzUrP.js";
+import { r as runCollect } from "./collect-2SrB7lfk.js";
+import { n as isConfigFile, r as loadConfig } from "./config-BIjREpyE.js";
 import { watch } from "node:fs";
 import { basename, dirname, relative, resolve, sep } from "node:path";
 //#region src/cli/watch.ts
@@ -19,7 +19,7 @@ function within(dirs, file) {
 		return path !== "" && !path.startsWith("..") && !path.startsWith(sep);
 	});
 }
-async function collectOnce(cwd, options, check, fresh, configFile) {
+async function collectOnce(cwd, options, check, fresh, configFile, now = () => /* @__PURE__ */ new Date()) {
 	const config = await loadConfig(cwd, configFile, { fresh });
 	const collect = {
 		...config.collect,
@@ -30,7 +30,7 @@ async function collectOnce(cwd, options, check, fresh, configFile) {
 		config,
 		collect,
 		check,
-		now: /* @__PURE__ */ new Date(),
+		now: now(),
 		fresh
 	});
 	const inputs = [
@@ -67,7 +67,7 @@ function createCollectScheduler(cwd, options, settings) {
 	async function run(check) {
 		const fresh = loaded;
 		loaded = true;
-		const result = await collectOnce(cwd, options, check, fresh, settings?.configFile);
+		const result = await collectOnce(cwd, options, check, fresh, settings?.configFile, settings?.now);
 		ignored = new Set(result.written);
 		inputs = result.inputs;
 		sources = result.sources;

package/dist/webmcp/index.d.ts

@@ -1,5 +1,5 @@
-import { Tt as Snapshot, Yn as Decision } from "../policy-IB6yxpC3.js";
-import { f as Permission, m as PermissionTree } from "../permissions-DttnqqxC.js";
+import { an as Snapshot, ir as Decision } from "../policy-types-sp9P1iIV.js";
+import { d as Permission, p as PermissionTree } from "../permission-types-Dg39z9Kv.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/webmcp/types.d.ts
 type WebMcpClientStatus = "ready" | "pending" | "stale" | "server-only";

package/dist/webmcp/index.js

@@ -1,15 +1,11 @@
-import { t as compact } from "../compact-y6vfu2_f.js";
-import { _ as listPermissions, h as isRegistryTree, s as getRegistry, t as annotationsFor, x as resourceOfNode } from "../permissions-DVoF6dMt.js";
-import { n as PermDockValidationError } from "../validation-error-CnjZ4t92.js";
-import { a as wireDenials } from "../problem-details-_AMOYz-w.js";
-import { t as describe } from "../describe-B_gVZEVi.js";
-import { n as isThenable, t as ignoreRejection } from "../thenable-okc2xDsj.js";
+import { r as isRecord, t as compact } from "../compact-CAf557ZB.js";
+import { n as isThenable, t as ignoreRejection } from "../thenable-QSmvt-vZ.js";
+import { n as PermDockValidationError } from "../validation-error-ZfUHbKvf.js";
+import { c as listPermissions, f as resourceOfNode, i as getRegistry, m as annotationsFor, s as isRegistryTree } from "../permission-registry-BsblpB-z.js";
 import { n as resourceRef } from "../resource-ref-CaS9yVPi.js";
+import { n as deniedToolRefusal, r as toolErrorResult, t as approvalToolRefusal } from "../tool-refusal-CQ7OEia9.js";
 //#region src/webmcp/register.ts
 const MISSING_CONTEXT = "permdock/webmcp: document.modelContext is absent; registerTools is a no-op.";
-function isRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 const CURRENT = Symbol.for("permdock.current");
 function current(permdock) {
 	const latest = permdock[CURRENT];
@@ -100,43 +96,23 @@ function bindTenant(input, tenantKey, tenant) {
 		}
 	};
 }
-function alternativesOf(decision) {
-	return decision.alternatives.map((leaf) => leaf.key);
-}
 function deniedResult(decision, permission, data) {
-	const described = describe(decision);
-	const alternatives = alternativesOf(decision);
-	const suffix = alternatives.length === 0 ? "" : ` You may: ${alternatives.join(", ")}.`;
-	return {
-		isError: true,
-		content: [{
-			type: "text",
-			text: `Denied: ${permission.key}.${suffix}`
-		}],
-		structuredContent: compact({
-			outcome: "denied",
-			permission: permission.key,
-			resource: resourceRef(permission, permission.kind === "collection" ? void 0 : data),
-			denials: wireDenials(decision.denials),
-			alternatives,
-			detail: described.detail
-		})
-	};
+	return toolErrorResult(deniedToolRefusal(decision, permission, refOf(permission, data)));
 }
 function approvalResult(decision, permission, data) {
+	const refusal = approvalToolRefusal(decision, permission, refOf(permission, data));
 	return {
 		content: [{
 			type: "text",
-			text: describe(decision).detail
+			text: refusal.text
 		}],
-		structuredContent: {
-			outcome: "approval-required",
-			permission: permission.key,
-			resource: resourceRef(permission, permission.kind === "collection" ? void 0 : data),
-			token: decision.token
-		}
+		structuredContent: refusal.structured
 	};
 }
+/** A collection permission names the resource type only, never an id from the input. */
+function refOf(permission, data) {
+	return resourceRef(permission, permission.kind === "collection" ? void 0 : data);
+}
 function validationResult(error) {
 	return {
 		isError: true,

package/dist/wrap-Cr93qqdP.d.ts

@@ -0,0 +1,14 @@
+import { j as PolicyVocabulary, jt as PermDock } from "./policy-types-sp9P1iIV.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. */
+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.
+ */
+declare function wrapPermDock<V extends PolicyVocabulary = PolicyVocabulary>(permdock: PermDock<V>, overrides: (permdock: PermDock<V>) => PermDockOverrides<V>): PermDock<V>;
+//#endregion
+export { PermDockWrap as n, wrapPermDock as r, PermDockOverrides as t };

package/dist/wrap-DWsU_5Bd.js

@@ -0,0 +1,26 @@
+//#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.
+*/
+function wrapPermDock(permdock, overrides) {
+	const wrap = (next) => wrapPermDock(next, overrides);
+	return Object.freeze({
+		...permdock,
+		...overrides(permdock),
+		tenant: (id) => wrap(permdock.tenant(id)),
+		team: (id) => wrap(permdock.team(id)),
+		derive: (options) => {
+			const derived = permdock.derive(options);
+			return derived instanceof Promise ? derived.then(wrap) : wrap(derived);
+		}
+	});
+}
+/** `otel`, then `wrap`. */
+function composeWraps(otel, wrap) {
+	if (otel === void 0 || wrap === void 0) return otel ?? wrap;
+	return (permdock) => wrap(otel(permdock));
+}
+//#endregion
+export { wrapPermDock as n, composeWraps as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "permdock",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Typed permissions for TypeScript apps, APIs, databases, and AI agents, with the permdock CLI and test runners.",
   "keywords": [
     "ai-agents",
@@ -263,7 +263,7 @@
     "smol-toml": "1.9.0"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.288",
+    "@anthropic-ai/claude-agent-sdk": "0.3.289",
     "@arethetypeswrong/cli": "0.18.5",
     "@babel/core": "8.0.6",
     "@modelcontextprotocol/client": "2.3.0",
@@ -272,9 +272,9 @@
     "@nestjs/core": "12.1.2",
     "@nestjs/platform-express": "12.1.2",
     "@openai/agents": "0.18.0",
-    "@orpc/contract": "2.0.0-beta.41",
-    "@orpc/openapi": "2.0.0-beta.41",
-    "@orpc/server": "2.0.0-beta.41",
+    "@orpc/contract": "2.0.0-beta.42",
+    "@orpc/openapi": "2.0.0-beta.42",
+    "@orpc/server": "2.0.0-beta.42",
     "@permdock/ox-config": "0.0.0",
     "@permdock/typescript-config": "0.0.0",
     "@supabase/middleware": "1.0.0",
@@ -290,14 +290,14 @@
     "ai": "7.0.127",
     "ajv": "8.20.0",
     "babel-plugin-react-compiler": "1.0.0",
-    "better-supabase": "0.7.0",
+    "better-supabase": "0.8.0",
     "drizzle-orm": "1.0.0-rc.5-5935859",
     "elysia": "1.4.30",
     "eve": "0.71.3",
     "express": "5.2.1",
     "fastify": "5.12.5",
     "happy-dom": "20.14.5",
-    "hono": "4.13.12",
+    "hono": "4.13.13",
     "jose": "6.2.12",
     "kysely": "0.29.6",
     "next": "16.3.8",
@@ -334,7 +334,7 @@
     "@supabase/middleware": ">=1",
     "@trpc/server": ">=11",
     "ai": ">=5",
-    "better-supabase": ">=0.6.0 <0.8.0",
+    "better-supabase": ">=0.6.0 <0.9.0",
     "drizzle-orm": ">=0.40 || >=1.0.0-rc.0",
     "elysia": ">=1",
     "eve": ">=0.40",

package/schemas/catalog-v1.json

@@ -53,6 +53,9 @@
             "items": {
               "type": "string"
             }
+          },
+          "meta": {
+            "type": "object"
           }
         }
       }
@@ -485,6 +488,9 @@
           },
           "portable": {
             "const": false
+          },
+          "meta": {
+            "type": "object"
           }
         }
       }

package/skills/permdock-credentials/SKILL.md

@@ -30,7 +30,7 @@ Authentication is upstream: core never verifies a token. A `subjectFrom*` resolv
 
 ## Workflow
 
-1. **Verify access tokens.** Resolve the subject with `subjectFromJwt(token, { discovery, audience })` from `permdock/jwt`, or `subjectFromIntrospection` when the app already called introspection. -> [references/tokens-keys-links.md](references/tokens-keys-links.md)
+1. **Verify access tokens.** Create one `createJwtSubjectResolver({ discovery, audience })` per issuer from `permdock/jwt` for the life of the process, because it caches Discovery and the JWKS; `subjectFromJwt(token, options)` caches nothing and suits a one-off check. Or use `subjectFromIntrospection` when the app already called introspection. -> [references/tokens-keys-links.md](references/tokens-keys-links.md)
    ✓ An ID token, a token for another audience and an expired token each resolve to the anonymous subject.
 2. **Issue API keys, when the product has them.** Guard the creation endpoint with its own permission, call `decideCredential(permdock, request, { settings })`, store the hash with the returned `Credential`, and show the key once. -> [references/tokens-keys-links.md](references/tokens-keys-links.md#api-keys-and-service-accounts)
    ✓ A service key wider than its creator is denied with `exceeds-creator`.

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

@@ -5,14 +5,19 @@ Owning pages: [JWT adapter](https://permdock.com/docs/adapters/jwt), [authentica
 ## Access tokens — `permdock/jwt`
 
 ```ts
-import { subjectFromJwt } from "permdock/jwt";
+import { createJwtSubjectResolver } from "permdock/jwt";
 
-const subject = await subjectFromJwt(token, {
+// One resolver per issuer for the life of the process: it caches Discovery and the JWKS.
+const resolve = createJwtSubjectResolver({
   discovery: "https://issuer.example.com",
   audience: "https://api.example.com",
 });
+
+const subject = await resolve(token, request);
 ```
 
+`subjectFromJwt(token, options)` takes the same options but builds a new verifier per call, so each call fetches Discovery and the JWKS again. Use it for a one-off check such as a CLI or a test.
+
 - Prefer `discovery: '<issuer>'` over a hand-copied `jwks` URL. Set `audience` to the resource identifier. Write algorithms as `Ed25519`, `ES256` or `PS256`; never `EdDSA`, `none` or `RSA1_5`.
 - Keep the default `accept: 'access-token'`, so an ID token never authorises an API call.
 - `jose` is an optional peer. A failure is the anonymous subject, never a throw; the cause is reported through `on('auth')`. A claimed `act` chain that does not nest is anonymous with cause `invalid-chain`.

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

@@ -57,6 +57,10 @@ When the database already holds the rules, skip `generate`. Map each helper in `
 
 When hand-written policies call the app's own helpers (`org_ids_with_permission`, `has_org_permission`), map each under `rls.migrate.helpers` with its `form` (`ids`, `row`, `scoped`, `global`, `membership`) and the legacy keys under `rls.migrate.keys` or `prefixes`. Run `permdock rls migrate`, read the skipped calls, and apply with `--write`. Generate with `--helpers-only` while the policies stay hand-written. A `row-conditions` skip means that table's policy should be generated, not migrated.
 
+When the old helpers read a permissions table that triggers keep in step (`user_permissions`), list it under `rls.migrate.tables`. `permdock rls migrate` then reports its refresh triggers and every policy, view or function that still reads it, and `permdock doctor` reports PD066 while the migrations still create it. Rewrite each reader, then run `permdock rls migrate --retire-out <migrations dir>/`, which exits `1` and writes nothing while a reader remains. Never hand-write the drop with `cascade` ([retire a materialised table](https://permdock.com/docs/cli/rls#retire-a-materialised-table)).
+
+Triggers the app owns on generated tables (an audit trigger, a notification) go in `rls.triggers` or `rls.audit`, so they live in the generated files; never in a migration that patches the generated tables afterwards ([triggers and audit](https://permdock.com/docs/cli/rls#triggers-and-audit)).
+
 ## Attributes RLS cannot see
 
 A grant condition on `context.*` cannot be enforced by the database (PD027). Compare with a server-set `principal.claims.*` claim instead, never one from `user_metadata`. On Supabase, `supabase.hook.attrs` lists only server-owned columns or `app_metadata.<key>` entries clients cannot update (PD028). A check that must refuse a sign-in (single sign-on enforcement, a locked account) goes in `supabase.hook.before` as a schema-qualified `(event jsonb) returns jsonb` function the generated hook calls first; never a second hook or a hand edit of the generated one. The hook, declarative schemas (`--split`) and `fromTable` / `fromJunction` membership sources are on the [Supabase adapter](https://permdock.com/docs/adapters/supabase) and [Supabase hook](https://permdock.com/docs/adapters/supabase-hook) pages.

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

@@ -87,3 +87,4 @@ type CustomRole = {
 - A platform custom role (`scope: 'global'`, no `tenant`, `team` or `id`) is held through `principal.roles` and capped by the allows of declared global roles marked `assignable`. `RoleSource.globalRoles({ held })` returns them; `customRoleSource(reader, { read: 'held', policy })` skips that read while every held global role is declared.
 - 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)).

package/skills/permdock-wire/SKILL.md

@@ -110,7 +110,7 @@ Install each with `npx skills add ScaleDockHQ/PermDock --skill <name>` when the
 
 ## Reference index
 
-- [references/adapters.md](references/adapters.md): factory shapes for Next.js, HTTP frameworks, RPC frameworks, UI frameworks, AuthZEN, OpenAPI, OpenTelemetry, SCIM, Cloud, Better Auth, Clerk, Supabase, the remote PDP and collect-only frameworks.
-- [references/policy-options.md](references/policy-options.md): limits, disclosure, plans, validity windows, step-up, and CLI starting points (OpenAPI import, Arazzo, Cloud push).
+- [references/adapters.md](references/adapters.md): factory shapes for Next.js, HTTP frameworks, RPC frameworks, UI frameworks, AuthZEN, OpenAPI, OpenTelemetry, SCIM, Cloud, Better Auth, Clerk, Supabase, the remote PDP, collect-only frameworks, and the `onDenied`, `context` and `wrap` adapter hooks.
+- [references/policy-options.md](references/policy-options.md): limits, disclosure, plans, validity windows, step-up, app data and app obligations, and CLI starting points (OpenAPI import, Arazzo, Cloud push).
 - The `permdock` skill: the mental model, `explain` for an unexpected denial, and the docs MCP.
 - Docs: [policies](https://permdock.com/docs/concepts/policies), [conditions](https://permdock.com/docs/concepts/conditions), [decisions](https://permdock.com/docs/concepts/decisions), [adapters](https://permdock.com/docs/adapters).

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

@@ -313,6 +313,14 @@ instrument(permdock, {
 
 HTTP adapters accept the same options as `otel`. `@opentelemetry/api` is optional; without it the adapter writes only through `logger`.
 
+## Adapter hooks
+
+Every HTTP adapter, `permdock/mcp` and `permdock/ai-sdk` take three hooks ([extend PermDock](https://permdock.com/docs/guides/extending)):
+
+- `onDenied`: on HTTP, `({ decision, problem, request })` returns Problem Details with extra members, a `Response`, or `undefined`; a status below 300 or a throw keeps the default. On MCP and the AI SDK it returns replacement text only. On Next.js the factory `onDenied` also runs for `requireAccess`.
+- `context`: returns plain JSON merged into `subject.context`. Return only server-derived values, never a header, body field or tool argument; it is visible in the snapshot.
+- `wrap`: wraps each instance after `otel`; `permdock/next` takes it too. Build it with `wrapPermDock(permdock, (inner) => ({ … }))` so `tenant()`, `team()` and `derive()` stay wrapped.
+
 ## SCIM — `permdock/scim`
 
 No factory. Mount `scimHandler` and pass `directoryMembershipSource(store)` as `memberships`:
@@ -402,7 +410,7 @@ const subject = subjectFromSupabase(claims, {
 
 Write the claims with `permdock supabase hook generate`; `permdock supabase inspect --json` prints the manifest (helper names, tenant claim, budget, claims written) which `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` 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), 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. 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 --db $DATABASE_URL`.
+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), on 0.8 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. 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 --db $DATABASE_URL`.
 
 `claims` is whatever Supabase verified: `data.claims` from `supabase.auth.getClaims()` on an `@supabase/ssr` server client, or `jwtClaims` from `@supabase/server` (`ctx.jwtClaims` in `withSupabase` or a `pipeline`, and `c.var.jwtClaims` after a framework bridge such as `toHono([withClaims(), withPermDock()])`). `@supabase/server/adapters/*` and `c.var.supabaseContext` are deprecated and removed on 1 December 2026; do not write new code against them ([Hono, H3, Elysia and NestJS](https://permdock.com/docs/adapters/supabase#hono-h3-elysia-and-nestjs)). Pass `null` for anonymous callers; never `getSession().access_token` (unverified). An API-key auth mode (`secret`, `publishable`) has `jwtClaims: null` and is the anonymous subject, not a user.
 

package/skills/permdock-wire/references/policy-options.md

@@ -33,10 +33,19 @@ Hardware-key step-up is `to: assurance({ amr: ['hwk'], maxAge: 300 })` and rende
 Adopting PermDock in an app with its own keys, SQL helpers and tokens is a step-by-step guide ([existing apps](https://permdock.com/docs/getting-started/existing-apps)):
 
 - Keep the app's keys. Map verbs such as `view` to SQL with `rls.actions`, and give colliding resources a distinct `name` on `resource()`.
-- Put application-owned metadata in `meta.x`; PermDock carries it and never reads it.
+- Put application-owned metadata in `meta.x`; PermDock carries it and never reads it (see App data below).
 - Rename a key later with `definePermissions(tree, { renamed: { "old.key": "new.key" } })`. Remove the alias only when `permdock doctor` PD055 and PD056 are quiet; `permdock diff` reports the removal as the breaking `alias-removed`.
 - Generate helpers beside legacy SQL with `permdock rls generate --helpers-only --shims`, then rewrite policies with `permdock rls migrate --write`.
 
+## App data and app obligations
+
+Owning page: [extend PermDock](https://permdock.com/docs/guides/extending).
+
+- Type `x` with one Standard Schema per kind: `definePermissions(tree, { x: { permission, resource } })`, `defineRoles(tree, { x })`, `definePlans(tree, { x })`, `definePolicy(…, { x: { grant, membership } })`. Each schema validates synchronously. Invalid `x` in code throws; invalid `Membership.x` or custom-role `meta.x` from a source is dropped and the row stays.
+- Describe a grant with `allow(p, { name, meta: { description, x } })`. It reaches `decision.matched`, decision events, snapshot grants and catalog grants, and stays out of the policy fingerprint.
+- Steer code on a grant with `allow(p, { obligations: ['watermark', { name, detail }] })`, never on a deny. Read `{ kind: 'app', name, detail? }` from `decision.obligations` on a granted decision.
+- Snapshots carry grant `meta`, membership `x` and every leaf's `meta` to the client: never put a secret in them.
+
 ## CLI starting points
 
 - When the app already has an OpenAPI document and no definitions yet, start from `permdock openapi import --doc <doc> --out src/permissions.generated.ts --schema zod` and review each action's `meta.inferredFrom`.

package/dist/catalog-CRW5Mx_B.js

@@ -1,2 +0,0 @@
-import { t as runCatalog } from "./catalog-DWF5cYqB.js";
-export { runCatalog };

package/dist/collect-DSWOk19R.js

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