permdock 0.16.0 → 0.18.0

package/dist/{permdock-CprAPN3w.d.ts → permdock-ffY4CMd9.d.ts}

@@ -1,149 +1,98 @@
-import { $n as Quota, G as CustomRoleSource, J as DecisionSink, Jn as ExplainedDecision, K as CustomRoleSourceFactory, Qn as Obligation, T as Policy, Un as Decision, Wt as Instant, X as Intent, Xn as LimitDetail, Y as EntitlementSource, Zt as Snapshot, _ as GrantLimit, br as Condition, et as LimitStore, fr as Membership, h as Grant, hr as Subject, i as ApprovalOption, j as PolicyVocabulary, lr as Delegation, mt as TokenSigner, nt as MembershipSource, on as DecisionEvent, ot as RelationSource, pr as Principal, rn as AuthEvent, rr as Actor, st as SettingsSource, vn as Scope, vr as AdapterId } from "./policy-types-DGIO_gxq.js";
+import { $t as Snapshot, E as Policy, K as CustomRoleSource, Kt as Instant, M as PolicyVocabulary, Qn as ExplainedDecision, Sr as AdapterId, X as EntitlementSource, Y as DecisionSink, Z as Intent, _r as Principal, bn as Scope, cn as DecisionEvent, ct as SettingsSource, er as LimitDetail, gr as Membership, gt as TokenSigner, nr as Obligation, pr as Delegation, q as CustomRoleSourceFactory, qn as Decision, rr as Quota, rt as MembershipSource, sr as Actor, st as RelationSource, tt as LimitStore, v as GrantLimit, wr as Condition, yr as Subject } from "./policy-types-D-GwfQTc.js";
 import { D as RowOf, M as AppData, b as ResourceNode, u as Permission } from "./permission-types-CAY-GU7e.js";
 import { a as RoleTree, n as PlanTree, r as Role } from "./vocabulary-DEJ5j4mR.js";
-import { i as OperationEffect, s as OperationMeta, t as Operation, u as OperationRisk } from "./operations-Ci_rT6Uo.js";
-import { a as HostedPolicies } from "./hosted-DVxlLZMe.js";
-//#region src/core/approval-policies.d.ts
+import { t as Operation } from "./operations-Ci_rT6Uo.js";
+import { t as ApprovalPolicies } from "./approval-policies-oNnckT12.js";
+import { a as HostedPolicies } from "./hosted-BFNXwcjd.js";
+//#region src/core/checks.d.ts
 /**
- * One approval requirement kept as data, for a tenant or the whole platform. It
- * adds to what the code requires and never removes a requirement.
+ * One check of `canAll` or `decideAll`: a permission alone, or with the row it
+ * is checked on.
  */
-type ApprovalPolicy = {
-  /**
-   * The permission key; a former key from `renamed` resolves. Absent: every
-   * permission, which needs `risk` or `effects`.
-   */
-  readonly permission?: string;
-  /**
-   * Matches an operation call whose `meta.risk` is one of these; a call that
-   * names no operation never matches.
-   */
-  readonly risk?: readonly OperationRisk[];
-  /**
-   * Matches an operation call whose `meta.effects` includes one of these; a
-   * call that names no operation never matches.
-   */
-  readonly effects?: readonly OperationEffect[];
-  /** Absent: every tenant. */
-  readonly tenant?: string;
-  /**
-   * Actor kinds it applies to (`['agent']`); absent: every call. A call without
-   * an actor never matches a list.
-   */
-  readonly actors?: readonly string[];
-  /**
-   * A portable condition over the row; instance permissions only, since a
-   * collection action has no row.
-   */
-  readonly where?: Condition;
-  /** A portable condition over the call's input (the proposed row). */
-  readonly check?: Condition;
-  /**
-   * The same shape as `allow(..., { approval })`. An `escalation` here widens
-   * only this entry's stages, never the code's.
-   */
-  readonly approval: ApprovalOption;
+type PermissionCheck = Permission | readonly [permission: Permission, data?: unknown];
+/** One entry of `getPermissions`: plain JSON, safe across a cache boundary. */
+type PermissionState = {
+  readonly allowed: boolean;
+  readonly outcome: Decision["outcome"];
+  /** The first denial's reason; absent unless `outcome` is `denied`. */
+  readonly reason?: string;
 };
-/**
- * Data-driven approval requirements, a subject input like `CustomRoleSource`:
- * read once per instance for the subject's tenants (entries without a tenant
- * always apply). A throw, a rejected promise or an invalid entry denies every
- * call an allow would otherwise permit.
- */
-type ApprovalPolicySource = {
-  /** Names the implementation in errors and events. */
-  readonly name?: string;
-  approvalPoliciesFor: (query: {
-    readonly tenants: readonly string[];
-  }) => readonly ApprovalPolicy[] | Promise<readonly ApprovalPolicy[]>;
+//#endregion
+//#region src/core/instance-cache.d.ts
+type InstanceCacheStats = {
+  /** Instances and source answers built or read. */
+  readonly builds: number;
+  /** Calls answered by a build already in flight. */
+  readonly shared: number;
+  /** Calls answered from an entry. */
+  readonly hits: number;
+  readonly evictions: number;
+  readonly size: number;
 };
 /**
- * The denial detail when an `ApprovalPolicySource` fails: every call an allow
- * would grant denies with reason `approval`.
- */
-/**
- * The in-process `ApprovalPolicySource`, usable directly as the
- * `approvalPolicies` option: it is the source and its feature at once.
+ * The key of one cached instance: who it serves, at which authorization
+ * version, for which tenant and intent. `parts` holds everything else that
+ * shapes the instance (the claims, the request scope); it is hashed.
  */
-declare function memoryApprovalPolicySource(policies: readonly ApprovalPolicy[]): ApprovalPolicySource & ApprovalPolicies;
-/** An entry checked against the policy and ready to match. */
-type LoadedApprovalPolicy = {
-  readonly permission?: string;
-  readonly risk?: ReadonlySet<OperationRisk>;
-  readonly effects?: ReadonlySet<OperationEffect>;
+type InstanceCacheKey = {
+  readonly principal: string;
+  readonly version: number;
   readonly tenant?: string;
-  readonly actors?: ReadonlySet<string>;
-  readonly where?: Condition;
-  readonly check?: Condition;
-  readonly approval: NonNullable<Grant["approval"]>;
+  readonly intent: "read" | "write";
+  readonly parts: unknown;
 };
-/** `"failed"`: the source threw or returned something that cannot be applied. */
-/** What `tightenApproval` reads besides the code's approval. */
-type TightenInput = Parameters<typeof tightenApproval>[2];
-/**
- * Approval policies loaded for an instance: the tightening the evaluator
- * applies to each allow, or `"failed"` when the source threw or returned an
- * invalid entry (every allow then denies).
- */
-type LoadedApprovalPolicies = {
-  readonly tighten: (code: Grant["approval"], input: TightenInput) => Grant["approval"];
-} | "failed";
 /**
- * Approval policies kept as data, as an instance option: `approvalPolicies:
- * approvalPolicies(source)`. The loading and tightening code ships only with an
- * app that imports this function.
+ * Instances shared across requests: a subject at a known authorization version
+ * gets the instance built for it, until `maxAgeMs` passes or `evict` drops it.
+ * An instance whose version is unknown is never cached.
  */
-type ApprovalPolicies = {
-  readonly feature: "approval-policies";
-  readonly load: (policy: Policy, tenants: readonly string[], auth: AuthEvent[]) => LoadedApprovalPolicies | Promise<LoadedApprovalPolicies>;
+type InstanceCache = {
+  readonly name?: string;
+  /** The longest an instance, a custom role or an entitlement is reused. */
+  readonly maxAgeMs: number;
+  /**
+   * The instance for `key`: a stored one, the build in flight, or `build()`. A
+   * rejected build is not stored.
+   */
+  instance: <T>(key: InstanceCacheKey, owners: readonly unknown[], build: () => Promise<T>) => Promise<T>;
+  /**
+   * `source` with every answer kept for `maxAgeMs`, keyed by its arguments.
+   * With `of`, the answers are keyed by `of.owner` and `of.principal` instead
+   * of `source`, so the new source a `CustomRoleSourceFactory` returns per
+   * subject reuses them, and `evict(of.principal)` drops them.
+   */
+  customRoles: (source: CustomRoleSource, of?: CustomRoleOwner) => CustomRoleSource;
+  /** `source` with every answer kept for `maxAgeMs`, per principal and tenant. */
+  entitlements: (source: EntitlementSource) => EntitlementSource;
+  /**
+   * Drops `principal`'s instances, entitlements and the answers of custom-role
+   * sources cached for it.
+   */
+  evict: (principal: string) => void;
+  stats: () => InstanceCacheStats;
 };
-declare function approvalPolicies(source: ApprovalPolicySource): ApprovalPolicies;
-/**
- * Why an `ApprovalPolicy` entry does not load. `unknown-permission`: the policy
- * declares no such key (the entry applies to nothing). `invalid`: a field has
- * the wrong shape or the approval option does not normalise.
- * `where-on-collection`: `where` reads a row, which a collection action never
- * has, so the entry could never match; use `check` over the input.
- * `stale-on-without-version`: `staleOn` needs an instance permission whose
- * resource declares `version`.
- */
-type ApprovalPolicyProblem = "unknown-permission" | "invalid" | "where-on-collection" | "stale-on-without-version";
-type ApprovalPolicyValidation = {
-  readonly ok: true;
-} | {
-  readonly ok: false;
-  readonly problem: ApprovalPolicyProblem;
+/** The factory and principal a per-subject custom-role source belongs to. */
+type CustomRoleOwner = {
+  readonly owner: object;
+  readonly principal: string;
+};
+type InstanceCacheOptions = {
+  /** Entries kept; the least recently used goes first. Default 10,000. */
+  readonly maxEntries?: number;
+  /**
+   * Milliseconds an entry is reused: the longest a custom-role or entitlement
+   * change waits to reach an instance. Default 5,000; clamped to 0 to 60,000.
+   */
+  readonly maxAgeMs?: number;
+  /** Epoch milliseconds. */
+  readonly now?: () => number;
 };
 /**
- * Checks one entry against the policy the way `approvalPoliciesFor` loads it,
- * for an application to refuse a bad entry when it is saved instead of finding
- * every call denied. Never throws.
- */
-declare function validateApprovalPolicy(policy: Policy, entry: unknown): ApprovalPolicyValidation;
-/**
- * `code` with every matching entry added as further stages: the result needs
- * all of them (`'sequential'` when any part is ordered), keeps the code's
- * escalation, the shortest `ttl`, and `distinct` unless every part opts out.
- * Without a matching entry, `code` unchanged.
- */
-declare function tightenApproval(code: Grant["approval"], entries: readonly LoadedApprovalPolicy[], input: {
-  readonly permission: string;
-  readonly tenant: string | undefined;
-  readonly subject: Subject;
-  readonly current: unknown;
-  readonly next: unknown;
-  readonly now: number;
-  readonly scopes: readonly Scope[];
-  /** The meta of the operation the call decides, when it names one. */
-  readonly operation?: OperationMeta | undefined;
-}): Grant["approval"];
-//#endregion
-//#region src/core/checks.d.ts
-/**
- * One check of `canAll` or `decideAll`: a permission alone, or with the row it
- * is checked on.
+ * An in-process `InstanceCache`: a bounded LRU that shares builds in flight.
+ * Create it once at module scope and pass it as `instances` to every adapter of
+ * the app; adapters with the same sources and policy share entries.
  */
-type PermissionCheck = Permission | readonly [permission: Permission, data?: unknown];
+declare function instanceCache(options?: InstanceCacheOptions): InstanceCache;
 //#endregion
 //#region src/core/limits.d.ts
 declare function memoryLimitStore(): LimitStore & {
@@ -325,6 +274,13 @@ type DecideOptions = {
    * arguments. Never read when deciding.
    */
   readonly args?: unknown;
+  /**
+   * The `approvalFingerprint` of the exact operation the call runs. An
+   * `approval-required` token binds it, the request records it, and resuming
+   * under another fingerprint denies with `approval-fingerprint-mismatch`.
+   * Never read when deciding.
+   */
+  readonly fingerprint?: string;
   /**
    * The application's own data for the decision event (a request id, a route).
    * Plain JSON; a value that is not is dropped. Never read when deciding.
@@ -602,6 +558,14 @@ type PermDockOptions = {
    * handlers, never for a mutation.
    */
   readonly intent?: Intent;
+  /**
+   * The principal's authorization version this request already read, such as
+   * `bsb.bootstrap()`'s `authz_ver`: the memberships source's `version` is not
+   * called. Anything but a non-negative integer is ignored.
+   */
+  readonly version?: {
+    readonly known: number;
+  };
   readonly customRoles?: CustomRoleSource | CustomRoleSourceFactory;
   /**
    * Plans and seats from billing, merged into `principal.plans` for the active
@@ -645,6 +609,12 @@ type PermDockOptions = {
    * into `subject.context`; keys from `policy.context` win on a clash.
    */
   readonly context?: Readonly<Record<string, unknown>>;
+  /**
+   * Reuses the instance built for a subject at a known authorization version
+   * across requests, until the version moves or `maxAgeMs` passes: one
+   * `instanceCache()` at module scope. `getPermDockSync` ignores it.
+   */
+  readonly instances?: InstanceCache;
 };
 /**
  * The instance for `user`, built synchronously. Every input must answer
@@ -659,4 +629,4 @@ declare function getPermDockSync<TUser, TPrincipal extends Principal = Principal
  */
 declare function getPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, user: TUser | Subject | null, options?: PermDockOptions): Promise<PermDock<V>>;
 //#endregion
-export { memoryApprovalPolicySource as A, PermissionCheck as C, ApprovalPolicySource as D, ApprovalPolicyProblem as E, ApprovalPolicyValidation as O, memoryLimitStore as S, ApprovalPolicy as T, PrincipalSource as _, PermDock as a, Limits as b, RowPair as c, UncheckedData as d, WhereResult as f, PrincipalIdentityLink as g, PrincipalIdentity as h, LoadedRows as i, validateApprovalPolicy as j, approvalPolicies as k, SimulateOptions as l, getPermDockSync as m, DecideOptions as n, PermDockOptions as o, getPermDock as p, DeriveOptions as r, RowData as s, DecideIdsOptions as t, SnapshotOptions as u, memoryPrincipalSource as v, ApprovalPolicies as w, limits as x, PermittedIdsOptions as y };
+export { PermissionState as A, CustomRoleOwner as C, InstanceCacheStats as D, InstanceCacheOptions as E, instanceCache as O, memoryLimitStore as S, InstanceCacheKey as T, PrincipalSource as _, PermDock as a, Limits as b, RowPair as c, UncheckedData as d, WhereResult as f, PrincipalIdentityLink as g, PrincipalIdentity as h, LoadedRows as i, PermissionCheck as k, SimulateOptions as l, getPermDockSync as m, DecideOptions as n, PermDockOptions as o, getPermDock as p, DeriveOptions as r, RowData as s, DecideIdsOptions as t, SnapshotOptions as u, memoryPrincipalSource as v, InstanceCache as w, limits as x, PermittedIdsOptions as y };

package/dist/{permissions-CYcHj_w7.js → permissions-B3ggI88M.js}

@@ -1,7 +1,7 @@
-import { c as crud } from "./src-C_pi2Rnh.js";
+import { c as crud } from "./src-Brzq_0in.js";
 import { v as resource } from "./permission-registry-B8tYxPIt.js";
 import { f as definePlans, p as defineRoles } from "./grantee-Dke-9rd1.js";
-import { t as definePermissions } from "./permissions-CVXmRILq.js";
+import { t as definePermissions } from "./permissions-BaoLxy66.js";
 //#region src/testing/saas/schema.ts
 function accepts(kind, value) {
 	switch (kind) {

package/dist/{permissions-CVXmRILq.js → permissions-BaoLxy66.js}

@@ -1,18 +1,6 @@
 import { n as freezeDeep } from "./freeze-jjan0lCv.js";
 import { d as attachRegistry, p as walk, r as formerByKey, t as assertKeys } from "./permission-registry-B8tYxPIt.js";
 import { r as assertGraphTargets } from "./resource-relations-8-pCScBO.js";
-//#region src/core/operation-risks.ts
-/** Every `meta.risk` level, lowest first. */
-const OPERATION_RISKS = Object.freeze([
-	"low",
-	"medium",
-	"high",
-	"critical"
-]);
-function isOperationRisk(value) {
-	return OPERATION_RISKS.some((risk) => risk === value);
-}
-//#endregion
 //#region src/core/permissions.ts
 function definePermissions(input, options) {
 	const registry = /* @__PURE__ */ new Map();
@@ -27,4 +15,4 @@ function definePermissions(input, options) {
 	return freezeDeep(attachRegistry(tree, registry, leaves));
 }
 //#endregion
-export { OPERATION_RISKS as n, isOperationRisk as r, definePermissions as t };
+export { definePermissions as t };

package/dist/{pg-DQTqRrou.js → pg-Ddxsd5ZB.js}

@@ -1,5 +1,5 @@
-import { n as CliError } from "./errors-Vpu6rKHl.js";
-import { i as requirePeer } from "./peer-Q0fuZ6hx.js";
+import { n as CliError } from "./errors-BhRkoNS7.js";
+import { i as requirePeer } from "./peer-BuK9F53f.js";
 //#region src/cli/pg.ts
 const CONNECT_TIMEOUT_MS = 1e4;
 const STATEMENT_TIMEOUT_MS = 6e4;

package/dist/{policy-BycVKnXv.d.ts → policy-BtKSApSt.d.ts}

@@ -1,4 +1,4 @@
-import { T as Policy, hr as Subject, pr as Principal } from "./policy-types-DGIO_gxq.js";
+import { E as Policy, _r as Principal, yr as Subject } from "./policy-types-D-GwfQTc.js";
 import { c as saasPlans, l as saasRoles, s as saasPermissions } from "./permissions-Bx6UI8n1.js";
 //#region src/testing/saas/policy.d.ts
 /** Daily API-key quota per subject; the bucket should be per tenant too. */

package/dist/{policy-CLQ8__GF.js → policy-cV_wwPb8.js}

@@ -1,16 +1,17 @@
 import { t as compact } from "./compact-CAf557ZB.js";
 import { n as freezeDeep } from "./freeze-jjan0lCv.js";
-import { c as withGrantSchema, d as assertApprovalVersions, i as completeGrant, o as flattenGrants, p as normalizeWhere, s as flattenPermissions, u as assertApprovalRelations } from "./role-builder-BK2-T6oD.js";
+import { c as withGrantSchema, i as completeGrant, l as normalizeWhere, o as flattenGrants, s as flattenPermissions } from "./role-builder-CMW4wWzn.js";
 import { c as listPermissions, i as getRegistry, m as annotationsFor, n as findPermission, s as isRegistryTree } from "./permission-registry-B8tYxPIt.js";
 import { d as isSelfParented, l as isFieldRelation } from "./resource-relations-8-pCScBO.js";
 import { t as canonicalJson } from "./canonical-json-DwilZ1iB.js";
 import { r as sha256Digest } from "./sha256-C-4WXKIu.js";
-import { n as defineScopes, s as resolveScope } from "./scopes-0Up_UA2t.js";
+import { n as defineScopes, s as resolveScope } from "./scopes-BSdYaGHs.js";
 import { o as flattenGrantee, r as asGrantee, v as listRoles } from "./grantee-Dke-9rd1.js";
+import { i as assertApprovalVersions, r as assertApprovalRelations } from "./approval-normalize-CUjgSsOl.js";
 import { n as normalizeValidity } from "./validity-Buc7w8E9.js";
 import { t as byCodePoint } from "./compare-DTfyUunF.js";
-import { a as relationStart, i as relationHops, n as isGraphRelation, t as inheritCondition } from "./grantee-conditions-BrYPe-w0.js";
-import { a as memberOfFields, p as scopeField, u as relatesTo } from "./tenancy-5d1zVBvK.js";
+import { a as relationStart, i as relationHops, n as isGraphRelation, t as inheritCondition } from "./grantee-conditions-DX4K_gGI.js";
+import { a as memberOfFields, p as scopeField, u as relatesTo } from "./tenancy-DvOHHk3-.js";
 //#region src/core/policy-assertions.ts
 function assertParentGraph(resources) {
 	for (const node of resources.values()) {

package/dist/{policy-from-catalog-CU3An8uP.js → policy-from-catalog-B68hGC0S.js}

@@ -1,17 +1,18 @@
 import { r as isRecord, t as compact } from "./compact-CAf557ZB.js";
 import { n as freezeDeep } from "./freeze-jjan0lCv.js";
-import { p as normalizeWhere } from "./role-builder-BK2-T6oD.js";
+import { l as normalizeWhere } from "./role-builder-CMW4wWzn.js";
 import { n as PermDockValidationError } from "./validation-error-CYg2kJEw.js";
 import { i as getRegistry, n as findPermission, v as resource } from "./permission-registry-B8tYxPIt.js";
-import { n as defineScopes } from "./scopes-0Up_UA2t.js";
+import { n as defineScopes } from "./scopes-BSdYaGHs.js";
 import { f as definePlans, p as defineRoles } from "./grantee-Dke-9rd1.js";
+import { o as readWireApproval } from "./approval-normalize-CUjgSsOl.js";
 import { r as readWireValidity } from "./validity-Buc7w8E9.js";
-import { a as indexPolicy, f as normalizeDelegation } from "./policy-CLQ8__GF.js";
-import { o as isPortableCondition } from "./hosted-D0IzESu_.js";
-import { t as definePermissions } from "./permissions-CVXmRILq.js";
+import { a as indexPolicy, f as normalizeDelegation } from "./policy-cV_wwPb8.js";
+import { o as isPortableCondition } from "./hosted-waouw2V-.js";
+import { t as definePermissions } from "./permissions-BaoLxy66.js";
 import { n as copyJson, t as checkSchema } from "./json-schema-BPGa-RjQ.js";
-import { t as parseCatalog } from "./parse-1_ZheTW5.js";
-import { n as parsePushedPolicy } from "./pushed-policy-CDuOL2de.js";
+import { t as parseCatalog } from "./parse-UTC-sDrt.js";
+import { n as parsePushedPolicy } from "./pushed-policy-BecMsTtM.js";
 //#region src/catalog/json-schema-validator.ts
 const ANNOTATIONS = /* @__PURE__ */ new Set([
 	"$schema",
@@ -292,7 +293,7 @@ function buildGrant(tree, raw) {
 		role: raw.role,
 		where,
 		check: condition(raw.check, `grant '${raw.permission}' check`, raw.portable !== false),
-		approval: raw.approval,
+		approval: readWireApproval(raw.approval),
 		portable: raw.portable !== false,
 		limit: raw.limit,
 		fields: raw.fields,

package/dist/{policy-types-DGIO_gxq.d.ts → policy-types-D-GwfQTc.d.ts}

@@ -193,7 +193,7 @@ type ActorKind = OpenUnion<"mcp-client" | "oauth-client" | "support" | "imperson
  * The adapter a decision event names: a PermDock entry, or an integrator's own
  * adapter.
  */
-type AdapterId = OpenUnion<"server" | "next" | "hono" | "express" | "fastify" | "elysia" | "nest" | "node" | "h3" | "sveltekit" | "astro" | "solid-start" | "tanstack-start" | "trpc" | "orpc" | "supabase-middleware" | "convex" | "authzen" | "mcp" | "a2a" | "agent" | "ai-sdk" | "claude-agent" | "openai" | "eve" | "terminal" | "webmcp" | "workflow" | "chat" | "delivery">;
+type AdapterId = OpenUnion<"server" | "next" | "hono" | "express" | "fastify" | "elysia" | "nest" | "node" | "h3" | "sveltekit" | "astro" | "solid-start" | "tanstack-start" | "trpc" | "orpc" | "supabase-middleware" | "better-supabase" | "convex" | "authzen" | "mcp" | "a2a" | "agent" | "ai-sdk" | "claude-agent" | "openai" | "eve" | "terminal" | "webmcp" | "workflow" | "chat" | "delivery">;
 /**
  * How a membership was obtained (`membership.via`); `viaOnly` and support rules
  * match it by equality.
@@ -289,10 +289,6 @@ type Membership = {
    * conditions or RLS, and never written into token claims.
    */
   readonly x?: AppData;
-  /** Input only: an instance of the first scope. */
-  readonly tenant?: string;
-  /** Input only: an instance of the second scope, inside `tenant`. */
-  readonly team?: string;
 };
 /**
  * One permission a custom role adds or removes. It names a declared permission
@@ -595,6 +591,11 @@ type ApprovalRequiredDecision = {
   readonly grant: MatchedGrant;
   readonly reason: "human";
   readonly token: string;
+  /**
+   * The `fingerprint` the call passed, bound into `token`; the request it opens
+   * records it, and a resume under another fingerprint is refused.
+   */
+  readonly fingerprint?: string;
   /** Present only with `explain: true`. */
   readonly trace?: Trace;
 };
@@ -690,6 +691,16 @@ type PermissionApprover = {
   readonly kind: "permission";
   readonly permission: string;
 };
+/**
+ * The requester's manager, or anyone up the chain within `levels` (default 1),
+ * read from the `manager` relation on the requester's `user` record. Checked
+ * only through verdict facts (`ApprovalVerdict.relations`) that the handler
+ * reads from its `RelationSource`.
+ */
+type ManagerApprover = {
+  readonly kind: "manager";
+  readonly levels?: number;
+};
 /**
  * An approver who matches at least one item; an item that is a list matches
  * when every entry does.
@@ -701,11 +712,11 @@ type AnyOfApprover = {
 /**
  * Who may approve: a subject-only grantee, a `relation()` the approver holds on
  * the requested row (checked when the verdict is given), `user(id)`,
- * `holder(permission)`, or `anyOf(...)`. A list (or `allOf(...)`) matches an
- * approver who satisfies every item.
+ * `holder(permission)`, `manager()`, or `anyOf(...)`. A list (or `allOf(...)`)
+ * matches an approver who satisfies every item.
  */
-type Approver = Grantee | UserApprover | PermissionApprover | AnyOfApprover;
-type ApproverInput = GranteeInput | UserApprover | PermissionApprover | {
+type Approver = Grantee | UserApprover | PermissionApprover | ManagerApprover | AnyOfApprover;
+type ApproverInput = GranteeInput | UserApprover | PermissionApprover | ManagerApprover | {
   readonly kind: "any-of";
   readonly of: readonly ApproverInput[];
 } | readonly ApproverInput[];
@@ -723,6 +734,13 @@ declare function anyOf(...items: readonly ApproverInput[]): {
 declare function allOf(...items: readonly ApproverInput[]): readonly ApproverInput[];
 /** A named approver for `approval.by`, matched on the approver's principal id. */
 declare function user(id: string): UserApprover;
+/**
+ * Approves when the approver manages the requester, directly or within `levels`
+ * steps up the chain (1 to `MAX_MANAGER_LEVELS`, default 1).
+ */
+declare function manager(options?: {
+  readonly levels?: number;
+}): ManagerApprover;
 //#endregion
 //#region src/core/scopes.d.ts
 /**
@@ -1183,6 +1201,13 @@ type Snapshot = {
    * still cover.
    */
   readonly delegated?: readonly string[];
+  /**
+   * The token's authorization version (`authz_ver`) the snapshot was built
+   * from. A client compares it with the version in a refresh signal.
+   */
+  readonly authzVersion?: number;
+  /** The Auth session (`session_id`) the snapshot was built for. */
+  readonly sessionId?: string;
 };
 /**
  * A grant the subject would hold on another plan: its permission, role and
@@ -1371,6 +1396,15 @@ type LocalSnapshotRows = {
     readonly permissions: string;
     readonly includes: string;
   };
+  /**
+   * The user's authorization version row (`permdock_authz_version`), the value
+   * the token hook stamps `authz_ver` from.
+   */
+  readonly version?: {
+    readonly table: string;
+    readonly user: string;
+    readonly version: string;
+  };
 };
 /**
  * Grants a custom role entry resolves to, held by a placeholder role the client
@@ -1721,6 +1755,16 @@ type DecisionProvider = {
  * query and no answer outlives the instance.
  */
 type SourceMemo = <T>(key: string, read: () => T) => T;
+/**
+ * One read a source made, for an `onSourceCall` hook: `cached` is `true` when
+ * the instance's `SourceMemo` answered it without a query.
+ */
+type SourceCall = {
+  readonly source: string;
+  readonly method: string;
+  readonly durationMs: number;
+  readonly cached: boolean;
+};
 /** What `getPermDock` passes to every source call besides its query. */
 type SourceContext = {
   /** Absent when the source is called outside `getPermDock`. */
@@ -2089,16 +2133,22 @@ type ApprovalStage = {
  * order. `'sequential'`: stages complete in order; an approver signs only the
  * first incomplete stage. An approver signs once per request.
  */
-type ApprovalMode = "any" | "all" | "sequential";
+type ApprovalCombine = "any" | "all" | "sequential";
+/**
+ * `'authorize'` (the default): someone other than the request's principal
+ * approves. `'confirm'`: the principal may approve their own request. Neither
+ * is met by an approver acting through an agent or a delegated token.
+ */
+type ApprovalMode = "confirm" | "authorize";
 type ApprovalRequirement = {
-  /** Set when `mode` is `'any'` (the default); absent under `stages`. */
+  /** Set when `combine` is `'any'` (the default); absent under `stages`. */
   readonly by?: Approver | readonly Approver[];
   /** Absent means `'any'`. */
-  readonly mode?: ApprovalMode;
-  /** Set when `mode` is `'all'` or `'sequential'`. */
+  readonly combine?: ApprovalCombine;
+  /** Set when `combine` is `'all'` or `'sequential'`. */
   readonly stages?: readonly ApprovalStage[];
-  /** `false` lets the request's principal approve it; absent means `true`. */
-  readonly distinct?: boolean;
+  /** Absent means `'authorize'`. */
+  readonly mode?: ApprovalMode;
   /** `'resource-change'` binds the approval to the row's `version` field. */
   readonly staleOn?: "resource-change";
   /**
@@ -2119,7 +2169,7 @@ type ApprovalOption = "human" | {
    * `'all'` or `'sequential'` with `stages`; absent means `'any'` with
    * `by`.
    */
-  readonly mode?: ApprovalMode;
+  readonly combine?: ApprovalCombine;
   readonly stages?: readonly {
     readonly by: ApproverInput;
     readonly quorum?: number;
@@ -2129,8 +2179,11 @@ type ApprovalOption = "human" | {
       readonly to: ApproverInput;
     };
   }[];
-  /** `false` lets the request's principal approve it; absent means `true`. */
-  readonly distinct?: boolean;
+  /**
+   * `'confirm'` lets the request's principal approve it; absent means
+   * `'authorize'`.
+   */
+  readonly mode?: ApprovalMode;
   /**
    * `'resource-change'`: the approval covers the row as it was when it was
    * requested. The resource must declare `version`; once that field
@@ -2676,4 +2729,4 @@ type SubjectOf<P> = {
   readonly expiresAt?: number;
 };
 //#endregion
-export { LimitRemaining as $, Quota as $n, SnapshotGrant as $t, PolicyScopes as A, Grantee as An, SqlFunctionCondition as Ar, CredentialDecision as At, ValidateMode as B, relation as Bn, decideCredential as Bt, MembershipFixture as C, ApproverInput as Cn, MemberOfCondition as Cr, SupportSessionDecision as Ct, PolicyDelegation as D, anyOf as Dn, RelatedHop as Dr, parseSupportSession as Dt, PolicyAppDataSchemas as E, allOf as En, RelatedCondition as Er, decideSupportSession as Et, RoleScope as F, anyone as Fn, isSqlFunctionField as Fr, CredentialPolicyViolation as Ft, CustomRoleSource as G, DenialDetails as Gn, LocalCustomRoleTable as Gt, WireValidity as H, ApprovalRequiredDecision as Hn, parseCredential as Ht, SeparationConflict as I, assurance as In, CredentialRequest as It, DecisionSink as J, ExplainedDecision as Jn, LocalRowValue as Jt, CustomRoleSourceFactory as K, DenialReason as Kn, LocalMembershipRows as Kt, SubjectOf as L, authenticated as Ln, DecideCredentialOptions as Lt, PrincipalOf as M, InheritGrantee as Mn, isCondition as Mr, CredentialPermission as Mt, RoleBinding as N, RelationGrantee as Nn, isConditionDate as Nr, CredentialPermissionInput as Nt, PolicyOAuthScope as O, holder as On, RestrictedAncestors as Or, ApiKeyPrincipal as Ot, RoleOptions as P, actor as Pn, isConditionRef as Pr, CredentialPolicy as Pt, LimitConsumeInput as Q, Obligation as Qn, SnapshotAssignable as Qt, SupportAccessOptions as R, inherit as Rn, credentialDelegation as Rt, HostedGrantRef as S, Approver as Sn, ConditionValue as Sr, SupportSession as St, Policy as T, UserApprover as Tn, OpaqueCondition as Tr, SupportSessionRequest as Tt, CredentialVerifier as U, Decision as Un, InstanceHandle as Ut, VocabularyFromInput as V, AppObligation as Vn, isFeedId as Vt, CustomRoleContext as W, Denial as Wn, Instant as Wt, Intent as X, LimitDetail as Xn, LocalSnapshotRows as Xt, EntitlementSource as Y, GrantedDecision as Yn, LocalSnapshotManifest as Yt, JwtClaims as Z, MatchedGrant as Zn, Snapshot as Zt, GrantLimit as _, PolicyScopesInput as _n, ActorKind as _r, VerifiedToken as _t, ApprovalRequirement as a, CredentialEvent as an, AuthorizationDetail as ar, RelationHolder as at, GrantScope as b, ScopeNames as bn, Condition as br, WhereCompiler as bt, BreakGlassOptions as c, DeliveryEvent as cn, CustomRoleGrant as cr, SnapshotSource as ct, ClosureContext as d, EmailCategory as dn, JsonWebKeyLike as dr, SubjectResolver as dt, SnapshotNotEntitled as en, Trace as er, LimitStore as et, ClosureGrantFn as f, MembershipEvent as fn, Membership as fr, TenantSettings as ft, GrantCondition as g, WireDelegation as gn, VerifiedClaims as gr, VerificationFailure as gt, Grant as h, WireDenial as hn, Subject as hr, TokenVerifier as ht, ApprovalOption as i, AutomationEvent as in, Assurance as ir, RelationGroup as it, PolicyVocabulary as j, GranteeInput as jn, hasConditionOp as jr, CredentialKind as jt, PolicyOptions as k, user as kn, SqlFunctionArg as kr, Credential as kt, BreakGlassRequirements as l, DeliveryFailureCause as ln, Delegation as lr, SourceContext as lt, DelegationTarget as m, WireDecision as mn, SharedCustomRole as mr, TokenSigner as mt, ApprovalEscalation as n, AccessEvent as nn, TraceSkipReason as nr, MembershipSource as nt, ApprovalStage as o, DecisionEvent as on, Binding as or, RelationSource as ot, DelegationInput as p, SinkEvent as pn, Principal as pr, TokenFailureCause as pt, DecisionProvider as q, DeniedDecision as qn, LocalRowColumn as qt, ApprovalMode as r, AuthEvent as rn, Actor as rr, RelationChain as rt, AssuranceRequirement as s, DeliveryChannel as sn, CustomRole as sr, SettingsSource as st, ActivationOption as t, SnapshotScope as tn, TraceSkip as tr, MemberEntry as tt, BreakGlassSpec as u, DirectoryEvent as un, GnapAccess as ur, SourceMemo as ut, GrantMeta as v, Scope as vn, AdapterId as vr, VersionContext as vt, ObligationInput as w, PermissionApprover as wn, MemberOfParent as wr, SupportSessionPolicy as wt, GrantValidity as x, AnyOfApprover as xn, ConditionRef as xr, DecideSupportSessionOptions as xt, GrantOptions as y, ScopeDeclaration as yn, MembershipVia as yr, VersionQuery as yt, SupportConsent as z, plan as zn, credentialPolicyViolation as zt };
+export { LimitConsumeInput as $, GrantedDecision as $n, Snapshot as $t, PolicyOptions as A, anyOf as An, RelatedCondition as Ar, ApiKeyPrincipal as At, SupportConsent as B, assurance as Bn, credentialDelegation as Bt, HostedGrantRef as C, AnyOfApprover as Cn, MembershipVia as Cr, DecideSupportSessionOptions as Ct, PolicyAppDataSchemas as D, PermissionApprover as Dn, MemberOfCondition as Dr, SupportSessionRequest as Dt, Policy as E, ManagerApprover as En, ConditionValue as Er, SupportSessionPolicy as Et, RoleOptions as F, GranteeInput as Fn, hasConditionOp as Fr, CredentialPermissionInput as Ft, CustomRoleContext as G, AppObligation as Gn, InstanceHandle as Gt, VocabularyFromInput as H, inherit as Hn, decideCredential as Ht, RoleScope as I, InheritGrantee as In, isCondition as Ir, CredentialPolicy as It, DecisionProvider as J, Denial as Jn, LocalMembershipRows as Jt, CustomRoleSource as K, ApprovalRequiredDecision as Kn, Instant as Kt, SeparationConflict as L, RelationGrantee as Ln, isConditionDate as Lr, CredentialPolicyViolation as Lt, PolicyVocabulary as M, manager as Mn, RestrictedAncestors as Mr, CredentialDecision as Mt, PrincipalOf as N, user as Nn, SqlFunctionArg as Nr, CredentialKind as Nt, PolicyDelegation as O, UserApprover as On, MemberOfParent as Or, decideSupportSession as Ot, RoleBinding as P, Grantee as Pn, SqlFunctionCondition as Pr, CredentialPermission as Pt, JwtClaims as Q, ExplainedDecision as Qn, LocalSnapshotRows as Qt, SubjectOf as R, actor as Rn, isConditionRef as Rr, CredentialRequest as Rt, GrantValidity as S, ScopeNames as Sn, AdapterId as Sr, WhereCompiler as St, ObligationInput as T, ApproverInput as Tn, ConditionRef as Tr, SupportSessionDecision as Tt, WireValidity as U, plan as Un, isFeedId as Ut, ValidateMode as V, authenticated as Vn, credentialPolicyViolation as Vt, CredentialVerifier as W, relation as Wn, parseCredential as Wt, EntitlementSource as X, DenialReason as Xn, LocalRowValue as Xt, DecisionSink as Y, DenialDetails as Yn, LocalRowColumn as Yt, Intent as Z, DeniedDecision as Zn, LocalSnapshotManifest as Zt, GrantCondition as _, WireDenial as _n, Principal as _r, TokenVerifier as _t, ApprovalOption as a, AuthEvent as an, TraceSkip as ar, RelationGroup as at, GrantOptions as b, Scope as bn, VerifiedClaims as br, VersionContext as bt, AssuranceRequirement as c, DecisionEvent as cn, Assurance as cr, SettingsSource as ct, BreakGlassSpec as d, DeliveryFailureCause as dn, CustomRole as dr, SourceContext as dt, SnapshotAssignable as en, LimitDetail as er, LimitRemaining as et, ClosureContext as f, DirectoryEvent as fn, CustomRoleGrant as fr, SourceMemo as ft, Grant as g, WireDecision as gn, Membership as gr, TokenSigner as gt, DelegationTarget as h, SinkEvent as hn, JsonWebKeyLike as hr, TokenFailureCause as ht, ApprovalMode as i, AccessEvent as in, Trace as ir, RelationChain as it, PolicyScopes as j, holder as jn, RelatedHop as jr, Credential as jt, PolicyOAuthScope as k, allOf as kn, OpaqueCondition as kr, parseSupportSession as kt, BreakGlassOptions as l, DeliveryChannel as ln, AuthorizationDetail as lr, SnapshotSource as lt, DelegationInput as m, MembershipEvent as mn, GnapAccess as mr, TenantSettings as mt, ApprovalCombine as n, SnapshotNotEntitled as nn, Obligation as nr, MemberEntry as nt, ApprovalRequirement as o, AutomationEvent as on, TraceSkipReason as or, RelationHolder as ot, ClosureGrantFn as p, EmailCategory as pn, Delegation as pr, SubjectResolver as pt, CustomRoleSourceFactory as q, Decision as qn, LocalCustomRoleTable as qt, ApprovalEscalation as r, SnapshotScope as rn, Quota as rr, MembershipSource as rt, ApprovalStage as s, CredentialEvent as sn, Actor as sr, RelationSource as st, ActivationOption as t, SnapshotGrant as tn, MatchedGrant as tr, LimitStore as tt, BreakGlassRequirements as u, DeliveryEvent as un, Binding as ur, SourceCall as ut, GrantLimit as v, WireDelegation as vn, SharedCustomRole as vr, VerificationFailure as vt, MembershipFixture as w, Approver as wn, Condition as wr, SupportSession as wt, GrantScope as x, ScopeDeclaration as xn, ActorKind as xr, VersionQuery as xt, GrantMeta as y, PolicyScopesInput as yn, Subject as yr, VerifiedToken as yt, SupportAccessOptions as z, anyone as zn, isSqlFunctionField as zr, DecideCredentialOptions as zt };