permdock 0.8.0 → 0.9.0

package/dist/{openapi-CBZUhA3l.js → openapi-BIpw3Mb7.js}

@@ -80,7 +80,7 @@ const emit = defineLeaf({
 		}
 	},
 	async run(ctx, { flags }) {
-		return (await import("./openapi-VeHHU2l9.js")).runOpenapi({
+		return (await import("./openapi-BGeuunWC.js")).runOpenapi({
 			cwd: ctx.cwd,
 			config: ctx.config,
 			rest: ["emit"],
@@ -122,7 +122,7 @@ const importDocument = defineLeaf({
 	async run(ctx, { flags }) {
 		const doc = given(flags.doc);
 		if (doc === void 0) throw missingInput("openapi import", ["--doc"], "the OpenAPI document to import");
-		return (await import("./import-_YqhhwvX.js")).runOpenapiImport({
+		return (await import("./import-ACkOrv6g.js")).runOpenapiImport({
 			cwd: ctx.cwd,
 			doc,
 			out: fileOut("openapi import", flags.out),

package/dist/orpc/index.d.ts

@@ -1,11 +1,11 @@
-import { T as Policy, j as PolicyVocabulary, sr as Principal } from "../policy-types-CCiDRZBH.js";
+import { T as Policy, j as PolicyVocabulary, pr as Principal } from "../policy-types-DGIO_gxq.js";
 import { u as Permission } from "../permission-types-CAY-GU7e.js";
 import { a as OperationInput, t as Operation } from "../operations-Ci_rT6Uo.js";
-import { a as PermDock } from "../permdock-B6Sf4T_S.js";
+import { a as PermDock } from "../permdock-CprAPN3w.js";
 import { n as RevocationFeed } from "../revocations-BaUXHM1N.js";
-import { D as ConnectionOptions, T as Connection, i as OpenApiHooks } from "../server-types-CIlpSA2G.js";
-import { t as ServerAdapterOptions } from "../bind-Cp2hBHzP.js";
-import { t as StreamProtectOptions } from "../stream-ltuLdtTG.js";
+import { D as ConnectionOptions, T as Connection, i as OpenApiHooks } from "../server-types-CyRN0-Cd.js";
+import { t as ServerAdapterOptions } from "../bind-YYjvfpB9.js";
+import { t as StreamProtectOptions } from "../stream-9y9qw51m.js";
 import { AnySchema, MetaPlugin, Middleware, Procedure, Schema } from "@orpc/server";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/orpc/operations.d.ts

package/dist/orpc/index.js

@@ -2,9 +2,9 @@ import { t as compact } from "../compact-CAf557ZB.js";
 import { o as isPermission } from "../permission-registry-B8tYxPIt.js";
 import { o as problemMessage } from "../http-DKLXrFGk.js";
 import { t as problemFromError } from "../map-error-pasIGqMT.js";
-import { n as attached } from "../bind-D_sZSVA3.js";
+import { n as attached } from "../bind-BNQA9JK9.js";
 import { i as isAsyncIterable, o as reloadAfter } from "../stream-CDvF0sJm.js";
-import { i as rpcCode, n as guardStream, r as problemBody, t as bindRpcKernel } from "../rpc-fNqAIqQk.js";
+import { i as rpcCode, n as guardStream, r as problemBody, t as bindRpcKernel } from "../rpc-vHIwyXCp.js";
 import { ORPCError, os } from "@orpc/server";
 //#region src/orpc/operations.ts
 const root = os;

package/dist/otel/index.d.ts

@@ -1,6 +1,6 @@
-import { j as PolicyVocabulary } from "../policy-types-CCiDRZBH.js";
-import { a as PermDock } from "../permdock-B6Sf4T_S.js";
-import { a as OtelOptions, i as OtelApi, n as GEN_AI_TOOL_CALL_ID, o as OtelWrap, r as GEN_AI_TOOL_NAME, s as StructuralLogger, t as GENAI_SEMCONV_PIN } from "../types-DHKPcqzr.js";
+import { j as PolicyVocabulary } from "../policy-types-DGIO_gxq.js";
+import { a as PermDock } from "../permdock-CprAPN3w.js";
+import { a as OtelOptions, i as OtelApi, n as GEN_AI_TOOL_CALL_ID, o as OtelWrap, r as GEN_AI_TOOL_NAME, s as StructuralLogger, t as GENAI_SEMCONV_PIN } from "../types-B6ExllNo.js";
 //#region src/otel/instrument.d.ts
 /**
  * Listens on one instance. Spans carry no duration and no histogram is

package/dist/{output-tkju6U7R.js → output-DV5dwOTs.js}

@@ -1,5 +1,5 @@
 import { s as cliVersion } from "./version-DMQ0dnN5.js";
-import { t as DOCS_BASE } from "./manifest-Cgiq5oqc.js";
+import { t as DOCS_BASE } from "./manifest-B2QPh19C.js";
 //#region src/cli/core/output.ts
 const CLI_RESULT_SCHEMA = "https://permdock.com/schemas/cli-result-v1.json";
 function envelope(input) {

package/dist/{ownership-B4L59T9u.js → ownership-DA5YdYTm.js}

@@ -11,7 +11,7 @@ import { i as qualifySqlTable } from "./sql-0WjxIp9g.js";
 import { a as scopeMembershipTable, i as scopeColumn, s as relatedSql } from "./compile-EzEMB-7v.js";
 import { l as roleColumn } from "./sources-CMAM-2A3.js";
 import { A as quoteQualified, D as qualified, E as helperSchema, L as sqlType, M as textArrayLiteral, O as quoteIdent, R as tenantTypeOf, S as CLAIM, T as declaredArray, _ as subjectClaimJsonSql, b as tenantClaimSql, d as keyTenantSql, f as kindFilterSql, h as roleKindSql, j as quoteTable, k as quoteLiteral, m as memberVia, p as liveSessionSql, s as signedIn, t as CUSTOM_ROLES, u as globalKindFilterSql, v as subjectClaimSql, y as subjectIdSql } from "./shared-Afctg7B0.js";
-import { $ as graphSqlText, A as claimKeptLines, B as hasCustomRoleChecksFor, F as globalRoleRows, I as membershipRows, L as roleRows, M as memberColumn, N as sourceFilters, P as sourcesKeep, U as storedTenant, X as CLOSURE, Z as graphHelper, _t as activeMembershipSql, c as holderSources, ct as memberIdsHelper, d as sourceRowsSql, f as sourceTransferTriggerSql, g as OWNERSHIP, gt as activeInstancesSql, h as ASSIGNMENTS, ht as scopeTable, it as linkHelper, j as disabledColumn, l as pairsSql, m as transferTriggerSql, mt as scopeSources, nt as inheritedRowsHelper, p as holdersTriggerSql, pt as restrictedHelper, st as memberForTable, u as sourceHoldersTriggerSql, ut as memberRoleOf, yt as activeUserSql } from "./tables-DeMNEy6V.js";
+import { $ as graphSqlText, A as claimKeptLines, B as hasCustomRoleChecksFor, F as globalRoleRows, I as membershipRows, L as roleRows, M as memberColumn, N as sourceFilters, P as sourcesKeep, U as storedTenant, X as CLOSURE, Z as graphHelper, _t as activeMembershipSql, c as holderSources, ct as memberIdsHelper, d as sourceRowsSql, f as sourceTransferTriggerSql, g as OWNERSHIP, gt as activeInstancesSql, h as ASSIGNMENTS, ht as scopeTable, it as linkHelper, j as disabledColumn, l as pairsSql, m as transferTriggerSql, mt as scopeSources, nt as inheritedRowsHelper, p as holdersTriggerSql, pt as restrictedHelper, st as memberForTable, u as sourceHoldersTriggerSql, ut as memberRoleOf, yt as activeUserSql } from "./tables-BqrxBCir.js";
 //#region src/cli/sql/conditions.ts
 const MAX_CLAIM_DEPTH = 8;
 /**
@@ -319,6 +319,10 @@ function sqlFunctionNames(condition) {
 		default: return condition;
 	}
 }
+function candidateIds(ctx, field, wrap) {
+	return ctx.candidates === void 0 ? "" : wrap(`array(select ${quoteIdent(field)}::text from ${ctx.candidates})`);
+}
+const idsArgument = (ids) => `, ${ids}`;
 /**
 * A `related` condition as uncorrelated subqueries, so Postgres runs the helper
 * once per statement: the row's field in the closure's descendants of the ids
@@ -331,12 +335,13 @@ function compileRelatedSql(condition, ctx) {
 	const type = ctx.columnTypes?.[condition.field];
 	const cast = type === void 0 || type === "text" ? "" : `::${type}`;
 	const column = type === void 0 ? `${quoteIdent(condition.field)}::text` : quoteIdent(condition.field);
-	const helper = condition.permission === void 0 ? `${qualified(ctx, graphHelper(condition.resource))}(${quoteLiteral(condition.relation)})` : `${qualified(ctx, inheritedRowsHelper(condition.resource))}(${quoteLiteral(condition.permission)})`;
+	const helper = condition.permission === void 0 ? `${qualified(ctx, graphHelper(condition.resource))}(${quoteLiteral(condition.relation)})` : `${qualified(ctx, inheritedRowsHelper(condition.resource))}(${quoteLiteral(condition.permission)}${condition.depth === 0 ? candidateIds(ctx, condition.field, idsArgument) : ""})`;
 	const cap = ctx.graph?.closures[condition.resource];
 	let inner;
 	if (condition.depth > 0 && cap !== void 0) {
 		const depth = condition.depth < cap ? ` and depth <= ${String(condition.depth)}` : "";
-		inner = `select descendant${cast} from ${qualified(ctx, CLOSURE.table)} where resource = ${quoteLiteral(condition.resource)}${depth} and ancestor = any (array(select ${helper}))`;
+		const narrowed = candidateIds(ctx, condition.field, (ids) => ` and descendant = any (${ids})`);
+		inner = `select descendant${cast} from ${qualified(ctx, CLOSURE.table)} where resource = ${quoteLiteral(condition.resource)}${depth}${narrowed} and ancestor = any (array(select ${helper}))`;
 	} else inner = cast === "" ? `select ${helper}` : `select p.id${cast} from ${helper} as p(id)`;
 	const reach = `${column} in (${inner})`;
 	if (condition.parent === true && condition.restricted !== void 0) return `(${reach} and ${quoteIdent(condition.restricted)} is not true)`;
@@ -358,7 +363,7 @@ function compileHoppedSql(condition, ctx) {
 		closureDepths: ctx.graph?.closures ?? {},
 		qualify: qualifySqlTable,
 		holders: (resource, relation) => [{ text: `select ${schema}.${graphHelper(resource)}(${quoteLiteral(relation)})` }],
-		permitted: (resource, permission) => [{ text: `select ${schema}.${inheritedRowsHelper(resource)}(${quoteLiteral(permission)})` }],
+		permitted: (resource, permission) => [{ text: `select ${schema}.${inheritedRowsHelper(resource)}(${quoteLiteral(permission)}${condition.hops?.length === 1 ? candidateIds(ctx, condition.field, idsArgument) : ""})` }],
 		restrictedRows: (resource) => [{ text: `select ${schema}.${restrictedHelper(resource)}()` }],
 		linked: (resource, link, targets) => [
 			{ text: `select ${schema}.${linkHelper(resource, link)}(array(` },

package/dist/{parse-local-manifest-BQhTlLQS.d.ts → parse-local-manifest-CCmbhnxP.d.ts}

@@ -1,4 +1,4 @@
-import { Ut as LocalSnapshotManifest } from "./policy-types-CCiDRZBH.js";
+import { Yt as LocalSnapshotManifest } from "./policy-types-DGIO_gxq.js";
 //#region src/core/parse-local-manifest.d.ts
 /**
  * Whether `value` has the shape `localSnapshotManifest(policy)` writes, with no

package/dist/pdp/index.d.ts

@@ -1,6 +1,6 @@
-import { K as DecisionProvider, T as Policy, j as PolicyVocabulary, sr as Principal } from "../policy-types-CCiDRZBH.js";
-import { o as PermDockOptions } from "../permdock-B6Sf4T_S.js";
-import { a as RelationMap, c as RemotePdpEndpoints, d as SpiceDbCheck, f as SpiceDbOptions, i as PdpPermDock, l as RemotePdpMapping, n as OpenFgaTuple, o as RemotePdpAuth, r as PdpFactory, s as RemotePdpCache, t as OpenFgaOptions, u as RemotePdpOptions } from "../types-B4uqKDnp.js";
+import { T as Policy, j as PolicyVocabulary, pr as Principal, q as DecisionProvider } from "../policy-types-DGIO_gxq.js";
+import { o as PermDockOptions } from "../permdock-CprAPN3w.js";
+import { a as RelationMap, c as RemotePdpEndpoints, d as SpiceDbCheck, f as SpiceDbOptions, i as PdpPermDock, l as RemotePdpMapping, n as OpenFgaTuple, o as RemotePdpAuth, r as PdpFactory, s as RemotePdpCache, t as OpenFgaOptions, u as RemotePdpOptions } from "../types-DlelvQk4.js";
 //#region src/pdp/create.d.ts
 /**
  * The PDP-aware instance, built synchronously like core `getPermDockSync`; use

package/dist/pdp/index.js

@@ -6,7 +6,7 @@ import { n as internalsOf, t as attachInternals } from "../internals-B3IgHrvo.js
 import { a as getResource, c as listPermissions } from "../permission-registry-B8tYxPIt.js";
 import { n as toWireDelegation } from "../wire-delegation-Cv3W2eaM.js";
 import { r as decideAllAsync, t as canAllAsync } from "../checks-CGkP3Z7A.js";
-import { n as getPermDockSync$1, t as getPermDock$1 } from "../permdock-L-_I_3zP.js";
+import { n as getPermDockSync$1, t as getPermDock$1 } from "../permdock-BvjivVb9.js";
 import { a as postJson, c as ttlMs, i as joinUrl, n as denied, o as resourceIdOf, r as granted, s as ttlCache, t as cacheKey } from "../shared-l0oGGetg.js";
 //#region src/pdp/create.ts
 function withoutProviders(policy) {

package/dist/{permdock-L-_I_3zP.js → permdock-BvjivVb9.js}

@@ -11,8 +11,8 @@ 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-Dd8Ta0Ie.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--JWiTrvO.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 { 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";
@@ -512,6 +512,96 @@ 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
@@ -585,6 +675,21 @@ function hasScope(granted, scopes) {
 	return scopes.some((scope) => granted?.includes(scope) === true);
 }
 //#endregion
+//#region src/core/source-memo.ts
+/**
+* One memo per `getPermDock` call. A read that throws is not kept, so the next
+* caller tries again.
+*/
+function sourceMemo() {
+	const answers = /* @__PURE__ */ new Map();
+	return (key, read) => {
+		if (answers.has(key)) return answers.get(key);
+		const answer = read();
+		answers.set(key, answer);
+		return answer;
+	};
+}
+//#endregion
 //#region src/core/resolve-subject.ts
 /**
 * The tenant a user API key holds its owner to (`Credential.tenant`): only the
@@ -599,13 +704,14 @@ function heldTenantOf(principal) {
 function outsideHeld(held, options) {
 	return held !== void 0 && options.tenant !== void 0 && options.tenant !== held;
 }
-function assemblePrincipal(policy, user, options, auth) {
+function assemblePrincipal(policy, user, options, auth, memo) {
 	let principal;
 	let context = {};
 	let actor = options.actor;
 	let delegation = options.delegation;
 	let session = options.session;
 	let expiresAt = options.expiresAt;
+	let issuedAt;
 	let liveSession;
 	try {
 		if (user === null || user === void 0) principal = policy.subject(user);
@@ -616,6 +722,7 @@ function assemblePrincipal(policy, user, options, auth) {
 			delegation = user.delegation ?? delegation;
 			session = user.session ?? session;
 			expiresAt = user.expiresAt ?? expiresAt;
+			issuedAt = typeof user.issuedAt === "number" && Number.isFinite(user.issuedAt) ? user.issuedAt : void 0;
 			liveSession = user.liveSession === true ? true : void 0;
 		} else principal = policy.subject(user);
 	} catch {
@@ -631,7 +738,10 @@ function assemblePrincipal(policy, user, options, auth) {
 			return from.membershipsFor(compact({
 				id: of.id,
 				kind: of.kind
-			}), compact({ tenant: options.tenant }));
+			}), compact({
+				tenant: options.tenant,
+				memo
+			}));
 		} catch {
 			auth.push({
 				reason: "source-threw",
@@ -647,10 +757,13 @@ function assemblePrincipal(policy, user, options, auth) {
 		live = true;
 		memberships = read(source, principal);
 	} else if (principal?.memberships !== void 0 && fromClaims && source.onStale === "reread" && source.version !== void 0) {
-		const reread = rereadStale(source, principal, principal.memberships, () => read(source, principal), auth, source.globalRolesFor === void 0 ? void 0 : () => source.globalRolesFor?.(compact({
+		const reread = rereadStale(source, principal, issuedAt, {
+			memo,
+			intent: options.intent ?? "write"
+		}, () => read(source, principal), auth, source.globalRolesFor === void 0 ? void 0 : () => source.globalRolesFor?.(compact({
 			id: principal.id,
 			kind: principal.kind
-		})) ?? []);
+		}), { memo }) ?? []);
 		memberships = reread.memberships;
 		stale = reread.stale;
 		roles = reread.roles;
@@ -663,78 +776,21 @@ function assemblePrincipal(policy, user, options, auth) {
 		delegation: expandOAuthScopes(policy, delegation),
 		session,
 		expiresAt,
+		issuedAt,
 		memberships,
 		live,
 		stale,
 		liveSession: principal === null ? void 0 : liveSession
 	});
 }
-function versionQuery(principal) {
-	return compact({
-		id: principal.id,
-		roles: principal.roles,
-		memberships: principal.memberships
-	});
-}
-function rereadStale(source, principal, claims, read, auth, readRoles) {
-	const claimed = principal.authzVersion;
-	const judge = (current) => typeof claimed === "number" && current !== void 0 && claimed >= current ? "fresh" : "reread";
-	const unknown = () => {
-		auth.push({
-			reason: "source-threw",
-			source: "memberships",
-			...sourceName(source)
-		});
-		return "unknown";
-	};
-	let freshness;
-	try {
-		const current = source.version?.(versionQuery(principal));
-		freshness = isThenable(current) ? Promise.resolve(current).then(judge, unknown) : judge(current);
-	} catch {
-		freshness = unknown();
-	}
-	const failed = () => {
-		auth.push({
-			reason: "source-threw",
-			source: "memberships",
-			...sourceName(source)
-		});
-		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)
-	});
-}
 function finishSubject(policy, assembled, context, input, options, extra) {
 	if (assembled.principal === null) return freezeCopy(compact({
 		...anonymousSubject(context),
 		actor: assembled.actor,
 		delegation: assembled.delegation,
 		session: assembled.session,
-		expiresAt: assembled.expiresAt
+		expiresAt: assembled.expiresAt,
+		issuedAt: assembled.issuedAt
 	}));
 	const scopes = scopeList(policy.scopes);
 	const held = heldTenantOf(assembled.principal);
@@ -760,6 +816,7 @@ function finishSubject(policy, assembled, context, input, options, extra) {
 		context: freezeCopy(context),
 		session: assembled.session,
 		expiresAt: assembled.expiresAt,
+		issuedAt: assembled.issuedAt,
 		stale: extra.stale ? true : void 0,
 		liveSession: assembled.liveSession
 	}));
@@ -807,37 +864,6 @@ function settle(value, fallback, onError) {
 	});
 	return value;
 }
-/**
-* 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, assembled, options, auth) {
-	const principal = assembled.principal;
-	if ((policy.fresh ?? []).length === 0 || principal === null || assembled.live) return false;
-	if (assembled.stale !== void 0) return assembled.stale;
-	const source = options.memberships === void 0 ? void 0 : asMembershipSource(options.memberships);
-	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));
-		return isThenable(current) ? settle(Promise.resolve(current).then(compare), true, () => {
-			auth.push({
-				reason: "source-threw",
-				source: "memberships",
-				...sourceName(source)
-			});
-		}) : compare(current);
-	} catch {
-		auth.push({
-			reason: "source-threw",
-			source: "memberships",
-			...sourceName(source)
-		});
-		return true;
-	}
-}
 function cleanNames(list) {
 	return Array.isArray(list) ? list.filter((item) => typeof item === "string" && item !== "") : [];
 }
@@ -891,25 +917,33 @@ function withRequestContext(request, resolved) {
 		...resolved
 	};
 }
-function resolveSubject(policy, user, options, auth) {
-	const first = assemblePrincipal(policy, user, options, auth);
+function resolveSubject(policy, user, options, auth, memo = sourceMemo()) {
+	const first = assemblePrincipal(policy, user, options, auth, memo);
 	const apply = (roles) => resolveAssembled(policy, roles === void 0 || first.principal === null ? first : {
 		...first,
 		principal: {
 			...first.principal,
 			roles
 		}
-	}, options, auth);
+	}, options, auth, memo);
 	return isThenable(first.roles) ? Promise.resolve(first.roles).then(apply) : apply(first.roles);
 }
-function resolveAssembled(policy, assembled, options, auth) {
+function resolveAssembled(policy, assembled, options, auth, memo) {
 	const memberships = settle(assembled.memberships, [], () => {
 		auth.push({
 			reason: "source-threw",
 			source: "memberships"
 		});
 	});
-	const stale = staleness(policy, assembled, options, auth);
+	const stale = staleness(policy, assembled.principal, options.memberships === void 0 ? void 0 : asMembershipSource(options.memberships), {
+		live: assembled.live,
+		stale: assembled.stale,
+		issuedAt: assembled.issuedAt,
+		context: {
+			memo,
+			intent: options.intent ?? "write"
+		}
+	}, 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([
 		Promise.resolve(assembled.context),
@@ -934,7 +968,7 @@ function resolveAssembled(policy, assembled, options, auth) {
 }
 //#endregion
 //#region src/core/permdock.ts
-function instantiate(codePolicy, subject, options, auth) {
+function instantiate(codePolicy, subject, options, auth, memo) {
 	const { policy, errors } = options.policies?.apply(codePolicy) ?? {
 		policy: codePolicy,
 		errors: []
@@ -942,7 +976,7 @@ function instantiate(codePolicy, subject, options, auth) {
 	const scopes = scopeList(policy.scopes);
 	const tenants = tenantsOf(subject.principal, scopes);
 	const roleSource = roleSourceFor(options.customRoles, subject, auth);
-	const customRoles = customRolesFor(roleSource, tenants, auth, subject.principal === null ? void 0 : subject.principal.roles ?? [], (tenant) => heldRoleNamesIn(subject.principal, scopes, tenant));
+	const customRoles = customRolesFor(roleSource, tenants, auth, subject.principal === null ? void 0 : subject.principal.roles ?? [], (tenant) => heldRoleNamesIn(subject.principal, scopes, tenant), memo);
 	const assignable = assignableNamesFor(roleSource, tenants, auth);
 	const approvals = options.approvalPolicies?.load(policy, tenants, auth);
 	const build = (roles, names, approvalPolicies) => {
@@ -971,6 +1005,7 @@ function instantiate(codePolicy, subject, options, auth) {
 				context: {}
 			}, compact({
 				tenant,
+				intent: options.intent,
 				memberships: options.memberships,
 				customRoles: options.customRoles,
 				entitlements: options.entitlements,
@@ -991,9 +1026,10 @@ function instantiate(codePolicy, subject, options, auth) {
 function create(policy, user, given) {
 	const options = withApp(policy, given);
 	const auth = [];
-	const subject = resolveSubject(policy, user, options, auth);
-	if (isThenable(subject)) return subject.then((resolved) => instantiate(policy, resolved, options, auth));
-	return instantiate(policy, subject, options, auth);
+	const memo = sourceMemo();
+	const subject = resolveSubject(policy, user, options, auth, memo);
+	if (isThenable(subject)) return subject.then((resolved) => instantiate(policy, resolved, options, auth, memo));
+	return instantiate(policy, subject, options, auth, memo);
 }
 /**
 * The instance for `user`, built synchronously. Every input must answer

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

@@ -1,8 +1,8 @@
-import { G as CustomRoleSourceFactory, Gt as Snapshot, Hn as ExplainedDecision, J as EntitlementSource, Kn as Obligation, Ln as Decision, Q as LimitStore, Rt as Instant, T as Policy, W as CustomRoleSource, Wn as LimitDetail, Zn as Actor, Zt as AuthEvent, _ as GrantLimit, at as SettingsSource, en as DecisionEvent, et as MembershipSource, fn as Scope, fr as AdapterId, h as Grant, i as ApprovalOption, it as RelationSource, j as PolicyVocabulary, lr as Subject, mr as Condition, or as Membership, q as DecisionSink, qn as Quota, rr as Delegation, sr as Principal, ut as TokenSigner } from "./policy-types-CCiDRZBH.js";
+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 { 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-Cmtxogd0.js";
+import { a as HostedPolicies } from "./hosted-DVxlLZMe.js";
 //#region src/core/approval-policies.d.ts
 /**
  * One approval requirement kept as data, for a tenant or the whole platform. It
@@ -595,6 +595,13 @@ type PermDockOptions = {
   readonly tenant?: string;
   /** One source, or several composed with `composeMemberships`. */
   readonly memberships?: MembershipSource | readonly MembershipSource[];
+  /**
+   * `'read'` lets `claimsFirst(source, { versions })` judge the token from the
+   * shared version cache, at most its `maxStaleMs` stale; `'write'` (the
+   * default) reads the version live. Pick `'read'` for rendering and `GET`
+   * handlers, never for a mutation.
+   */
+  readonly intent?: Intent;
   readonly customRoles?: CustomRoleSource | CustomRoleSourceFactory;
   /**
    * Plans and seats from billing, merged into `principal.plans` for the active

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

@@ -1,4 +1,4 @@
-import { c as crud } from "./src-DZ0l9UAg.js";
+import { c as crud } from "./src-C_pi2Rnh.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/{policy-Ba4bDhaj.d.ts → policy-BycVKnXv.d.ts}

@@ -1,4 +1,4 @@
-import { T as Policy, lr as Subject, sr as Principal } from "./policy-types-CCiDRZBH.js";
+import { T as Policy, hr as Subject, pr as Principal } from "./policy-types-DGIO_gxq.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-from-catalog-CJgOm6aq.js → policy-from-catalog-CU3An8uP.js}

@@ -11,7 +11,7 @@ import { o as isPortableCondition } from "./hosted-D0IzESu_.js";
 import { t as definePermissions } from "./permissions-CVXmRILq.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-ITwYKvvH.js";
+import { n as parsePushedPolicy } from "./pushed-policy-CDuOL2de.js";
 //#region src/catalog/json-schema-validator.ts
 const ANNOTATIONS = /* @__PURE__ */ new Set([
 	"$schema",