permdock 0.16.0 → 0.17.0

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

@@ -1,149 +1,85 @@
-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-IRJVABmm.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-9VagPixq.js";
+import { a as HostedPolicies } from "./hosted-DxRLLiFU.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. */
+  customRoles: (source: CustomRoleSource) => CustomRoleSource;
+  /** `source` with every answer kept for `maxAgeMs`, per principal and tenant. */
+  entitlements: (source: EntitlementSource) => EntitlementSource;
+  /** Drops `principal`'s instances and entitlements. */
+  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;
+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.
+ * 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.
  */
-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.
- */
-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 +261,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 +545,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 +596,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 +616,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 { InstanceCache as C, instanceCache as D, InstanceCacheStats as E, PermissionCheck as O, memoryLimitStore as S, InstanceCacheOptions 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, PermissionState 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, InstanceCacheKey as w, limits as x, PermittedIdsOptions as y };

package/dist/{permdock-BvjivVb9.js → permdock-DdzMv5-F.js}

@@ -6,18 +6,18 @@ import { t as attachInternals } from "./internals-B3IgHrvo.js";
 import { _ as keyToScope, a as getResource, c as listPermissions, g as formerScopes } from "./permission-registry-B8tYxPIt.js";
 import { n as isThenable } from "./thenable-BNSM1U2R.js";
 import { i as readAppData } from "./app-data-UNNm07jV.js";
-import { f as scopeList, h as tenantOf, o as normalizeMemberships } from "./scopes-0Up_UA2t.js";
+import { d as scopeList, o as normalizeMemberships, p as tenantOf } from "./scopes-BSdYaGHs.js";
 import { o as pickVisible, s as sanitizeContext } from "./validity-Buc7w8E9.js";
 import { t as byCodePoint } from "./compare-DTfyUunF.js";
-import { c as nowSeconds, d as resolveActiveTenant, m as tenantsOf, p as scopeField, t as heldRoleNamesIn, u as relatesTo } from "./tenancy-5d1zVBvK.js";
-import { d as policyX } from "./policy-CLQ8__GF.js";
-import { D as emptyListeners, E as emitSafe, N as contactMemberships, O as finish, P as isContact, i as customRolesFor, o as roleSourceFor, r as assignableNamesFor, s as sourceName, t as evaluate, u as customGrantsFor, w as unknownLevelsFor } from "./evaluate-BAmf_AQd.js";
-import { c as heldRoleNames, d as audiencesOf, g as asMembershipSource, i as assignableIn, l as roleLeaf, o as collectSnapshotGrants, s as whereGrant, t as snapshotOf, u as applyRoleKinds } from "./instance-snapshot-DuWf1cT3.js";
+import { c as nowSeconds, d as resolveActiveTenant, m as tenantsOf, p as scopeField, t as heldRoleNamesIn, u as relatesTo } from "./tenancy-DvOHHk3-.js";
+import { d as policyX } from "./policy-DxQyHKPB.js";
+import { r as isSubject, t as anonymousSubject } from "./subject-C7RddW0G.js";
+import { D as emptyListeners, E as emitSafe, N as contactMemberships, O as finish, P as isContact, i as customRolesFor, o as roleSourceFor, r as assignableNamesFor, s as sourceName, t as evaluate, u as customGrantsFor, w as unknownLevelsFor } from "./evaluate-CsjXeLRo.js";
+import { c as heldRoleNames, d as audiencesOf, g as asMembershipSource, i as assignableIn, l as roleLeaf, o as collectSnapshotGrants, s as whereGrant, t as snapshotOf, u as applyRoleKinds } from "./instance-snapshot-BgOGtyCy.js";
 import { r as relationReader, t as pendingRelations } from "./relations-BxvRvDHK.js";
-import { i as snapshotGrant } from "./snapshot-CXlzi69u.js";
-import { a as decideForTarget, i as permittedIds, o as deniedFor, r as mayUse, s as signSnapshot, t as whereFromGrants } from "./where-scope-DlCdCM_8.js";
-import { i as decideAllWith, n as canAllWith } from "./checks-CGkP3Z7A.js";
-import { r as isSubject, t as anonymousSubject } from "./subject-BGoM5o8B.js";
+import { i as snapshotGrant } from "./snapshot-DN_8J27z.js";
+import { a as decideForTarget, i as permittedIds, o as deniedFor, r as mayUse, s as signSnapshot, t as whereFromGrants } from "./where-scope-BKrqUDVk.js";
+import { i as decideAllWith, n as canAllWith } from "./checks-fyDOhcz0.js";
 //#region src/core/app.ts
 const APP = Symbol.for("permdock.app");
 /**
@@ -41,6 +41,187 @@ function withApp(policy, options) {
 	return merged;
 }
 //#endregion
+//#region src/core/freshness.ts
+function versionQuery(principal, issuedAt) {
+	return compact({
+		id: principal.id,
+		roles: principal.roles,
+		memberships: principal.memberships,
+		authzVersion: principal.authzVersion,
+		issuedAt
+	});
+}
+/** `known` when it is a version, otherwise the source's answer. */
+function currentVersion(source, query, context, known) {
+	return known !== void 0 && Number.isSafeInteger(known) && known >= 0 ? known : source.version?.(query, context);
+}
+function threw(source, auth) {
+	auth.push({
+		reason: "source-threw",
+		source: "memberships",
+		...sourceName(source)
+	});
+}
+/**
+* `onStale: 'reread'`: a token behind the source's version has its memberships
+* (and global roles, with `readRoles`) read live; a version that cannot be read
+* keeps the claims and marks the subject stale.
+*/
+function rereadStale(source, principal, issuedAt, context, read, auth, readRoles, known) {
+	const claims = principal.memberships ?? [];
+	const claimed = principal.authzVersion;
+	const judge = (current) => typeof claimed === "number" && current !== void 0 && claimed >= current ? "fresh" : "reread";
+	const unknown = () => {
+		threw(source, auth);
+		return "unknown";
+	};
+	let freshness;
+	try {
+		const current = currentVersion(source, versionQuery(principal, issuedAt), context, known);
+		freshness = isThenable(current) ? Promise.resolve(current).then(judge, unknown) : judge(current);
+	} catch {
+		freshness = unknown();
+	}
+	const failed = () => {
+		threw(source, auth);
+		return [];
+	};
+	const rolesOf = (found) => {
+		if (found !== "reread" || readRoles === void 0) return;
+		try {
+			const roles = readRoles();
+			return isThenable(roles) ? Promise.resolve(roles).catch(failed) : roles;
+		} catch {
+			return failed();
+		}
+	};
+	if (isThenable(freshness)) {
+		const settled = freshness.then((found) => ({
+			found,
+			roles: rolesOf(found)
+		}));
+		return {
+			memberships: settled.then(({ found }) => found === "reread" ? read() : claims),
+			stale: settled.then(({ found }) => found === "unknown"),
+			roles: settled.then(({ roles }) => roles)
+		};
+	}
+	return compact({
+		memberships: freshness === "reread" ? read() : claims,
+		stale: freshness === "unknown",
+		roles: rolesOf(freshness)
+	});
+}
+/**
+* Whether the token's memberships are behind the source for `fresh`
+* permissions. Live memberships are never stale; token memberships are stale
+* unless a source reports a version the token's `authzVersion` has reached.
+*/
+function staleness(policy, principal, source, given, auth) {
+	if ((policy.fresh ?? []).length === 0 || principal === null || given.live) return false;
+	if (given.stale !== void 0) return given.stale;
+	const claimed = principal.authzVersion;
+	if (source?.version === void 0 || typeof claimed !== "number") return true;
+	const compare = (current) => current === void 0 || claimed < current;
+	try {
+		const current = currentVersion(source, versionQuery(principal, given.issuedAt), given.context, given.known);
+		return isThenable(current) ? Promise.resolve(current).then(compare, () => {
+			threw(source, auth);
+			return true;
+		}) : compare(current);
+	} catch {
+		threw(source, auth);
+		return true;
+	}
+}
+//#endregion
+//#region src/core/cached-instance.ts
+/** Options that shape an instance by value; the rest by identity. */
+const DATA_KEYS = /* @__PURE__ */ new Set([
+	"tenant",
+	"intent",
+	"actor",
+	"delegation",
+	"session",
+	"expiresAt",
+	"context"
+]);
+function principalOf(policy, user) {
+	if (user === null || user === void 0) return null;
+	if (isSubject(user)) return user.principal === null ? null : compact({
+		principal: user.principal,
+		issuedAt: user.issuedAt
+	});
+	try {
+		const principal = policy.subject(user);
+		return principal === null ? null : { principal };
+	} catch {
+		return null;
+	}
+}
+function isVersion(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+* The cache key of an instance, with the options to build it with: the version
+* read for the key is passed on as `version.known`, so the build reads none.
+* `undefined` when the subject or its version is unknown.
+*/
+async function cacheKey(policy, user, options) {
+	const resolved = principalOf(policy, user);
+	if (resolved === null) return;
+	const intent = options.intent ?? "write";
+	let version = options.version?.known;
+	if (!isVersion(version) && options.memberships !== void 0) try {
+		version = await asMembershipSource(options.memberships).version?.(versionQuery(resolved.principal, resolved.issuedAt), { intent });
+	} catch {
+		return;
+	}
+	if (!isVersion(version)) return;
+	const data = {};
+	const owners = [policy];
+	for (const name of Object.keys(options).toSorted()) {
+		const value = Reflect.get(options, name);
+		if (DATA_KEYS.has(name)) data[name] = value;
+		else if (name !== "version") owners.push(value);
+	}
+	return {
+		key: compact({
+			principal: resolved.principal.id,
+			version,
+			tenant: options.tenant,
+			intent,
+			parts: {
+				user,
+				data
+			}
+		}),
+		owners,
+		options: {
+			...options,
+			version: { known: version }
+		}
+	};
+}
+function cachedSources(options, instances) {
+	const { customRoles, entitlements } = options;
+	return {
+		...options,
+		...customRoles === void 0 || typeof customRoles === "function" ? {} : { customRoles: instances.customRoles(customRoles) },
+		...entitlements === void 0 ? {} : { entitlements: instances.entitlements(entitlements) }
+	};
+}
+/**
+* `create` through `instances`: a subject whose authorization version is known
+* gets the instance built for it at that version, with the cache's custom-role
+* and entitlement memos; any other subject gets a new one.
+*/
+async function cachedInstance(policy, user, options, instances, create) {
+	const cached = await cacheKey(policy, user, options);
+	if (cached === void 0) return create(options);
+	return instances.instance(cached.key, cached.owners, () => Promise.resolve(create(cachedSources(cached.options, instances))));
+}
+//#endregion
 //#region src/core/assert-decision.ts
 /**
 * `assert`'s outcome: the granted decision, or the error a refusal throws after
@@ -512,96 +693,6 @@ function buildInstance(policy, subject, envBase, team) {
 	return Object.freeze(instance);
 }
 //#endregion
-//#region src/core/freshness.ts
-function versionQuery(principal, issuedAt) {
-	return compact({
-		id: principal.id,
-		roles: principal.roles,
-		memberships: principal.memberships,
-		authzVersion: principal.authzVersion,
-		issuedAt
-	});
-}
-function threw(source, auth) {
-	auth.push({
-		reason: "source-threw",
-		source: "memberships",
-		...sourceName(source)
-	});
-}
-/**
-* `onStale: 'reread'`: a token behind the source's version has its memberships
-* (and global roles, with `readRoles`) read live; a version that cannot be read
-* keeps the claims and marks the subject stale.
-*/
-function rereadStale(source, principal, issuedAt, context, read, auth, readRoles) {
-	const claims = principal.memberships ?? [];
-	const claimed = principal.authzVersion;
-	const judge = (current) => typeof claimed === "number" && current !== void 0 && claimed >= current ? "fresh" : "reread";
-	const unknown = () => {
-		threw(source, auth);
-		return "unknown";
-	};
-	let freshness;
-	try {
-		const current = source.version?.(versionQuery(principal, issuedAt), context);
-		freshness = isThenable(current) ? Promise.resolve(current).then(judge, unknown) : judge(current);
-	} catch {
-		freshness = unknown();
-	}
-	const failed = () => {
-		threw(source, auth);
-		return [];
-	};
-	const rolesOf = (found) => {
-		if (found !== "reread" || readRoles === void 0) return;
-		try {
-			const roles = readRoles();
-			return isThenable(roles) ? Promise.resolve(roles).catch(failed) : roles;
-		} catch {
-			return failed();
-		}
-	};
-	if (isThenable(freshness)) {
-		const settled = freshness.then((found) => ({
-			found,
-			roles: rolesOf(found)
-		}));
-		return {
-			memberships: settled.then(({ found }) => found === "reread" ? read() : claims),
-			stale: settled.then(({ found }) => found === "unknown"),
-			roles: settled.then(({ roles }) => roles)
-		};
-	}
-	return compact({
-		memberships: freshness === "reread" ? read() : claims,
-		stale: freshness === "unknown",
-		roles: rolesOf(freshness)
-	});
-}
-/**
-* Whether the token's memberships are behind the source for `fresh`
-* permissions. Live memberships are never stale; token memberships are stale
-* unless a source reports a version the token's `authzVersion` has reached.
-*/
-function staleness(policy, principal, source, given, auth) {
-	if ((policy.fresh ?? []).length === 0 || principal === null || given.live) return false;
-	if (given.stale !== void 0) return given.stale;
-	const claimed = principal.authzVersion;
-	if (source?.version === void 0 || typeof claimed !== "number") return true;
-	const compare = (current) => current === void 0 || claimed < current;
-	try {
-		const current = source.version(versionQuery(principal, given.issuedAt), given.context);
-		return isThenable(current) ? Promise.resolve(current).then(compare, () => {
-			threw(source, auth);
-			return true;
-		}) : compare(current);
-	} catch {
-		threw(source, auth);
-		return true;
-	}
-}
-//#endregion
 //#region src/core/oauth-scopes.ts
 /**
 * Every OAuth scope a token may carry to the permission keys it reaches: each
@@ -763,7 +854,7 @@ function assemblePrincipal(policy, user, options, auth, memo) {
 		}, () => read(source, principal), auth, source.globalRolesFor === void 0 ? void 0 : () => source.globalRolesFor?.(compact({
 			id: principal.id,
 			kind: principal.kind
-		}), { memo }) ?? []);
+		}), { memo }) ?? [], options.version?.known);
 		memberships = reread.memberships;
 		stale = reread.stale;
 		roles = reread.roles;
@@ -942,7 +1033,8 @@ function resolveAssembled(policy, assembled, options, auth, memo) {
 		context: {
 			memo,
 			intent: options.intent ?? "write"
-		}
+		},
+		known: options.version?.known
 	}, auth);
 	const withPlans = (resolved) => entitlementsOf(assembled, activeTenantOf(policy, assembled, applyRoleKinds(policy, assembled.principal?.roles, normalizeMemberships(resolved, scopeList(policy.scopes))).memberships, options), options, auth);
 	if (isThenable(assembled.context) || isThenable(memberships) || isThenable(stale)) return Promise.all([
@@ -1050,7 +1142,8 @@ function getPermDockSync(policy, user, options = {}) {
 * `getPermDockSync` is the synchronous twin.
 */
 function getPermDock(policy, user, options = {}) {
-	return Promise.resolve().then(() => create(policy, user, options));
+	const { instances, ...rest } = options;
+	return Promise.resolve().then(() => instances === void 0 ? create(policy, user, rest) : cachedInstance(policy, user, rest, instances, (cached) => create(policy, user, cached)));
 }
 //#endregion
 export { delegatedScopeMap as a, APP as c, challengeScope as i, withApp as l, getPermDockSync as n, hasScope as o, resolveSubject as r, scopesReaching as s, getPermDock as t };

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

@@ -1,4 +1,4 @@
-import { c as crud } from "./src-C_pi2Rnh.js";
+import { c as crud } from "./src-nYNBfmgq.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";

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-CTNl7pvN.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-IRJVABmm.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-DxQyHKPB.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-BrmOcXch.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-4KxMRdJC.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()) {