permdock 0.3.0 → 0.4.0

package/dist/{policy-IB6yxpC3.d.ts → policy-types-sp9P1iIV.d.ts}

@@ -1,6 +1,5 @@
-import { f as Permission, m as PermissionTree, p as PermissionKind, y as ResourceNode } from "./permissions-DttnqqxC.js";
-import { a as RoleTree, i as RoleMeta, n as PlanTree, r as Role, t as Plan } from "./vocabulary-DA8a8zif.js";
-import { StandardSchemaV1 } from "@standard-schema/spec";
+import { D as AppData, O as AppDataSchema, d as Permission, f as PermissionKind, k as MetaValue, p as PermissionTree, y as ResourceNode } from "./permission-types-Dg39z9Kv.js";
+import { a as RoleTree, i as RoleMeta, n as PlanTree, r as Role, t as Plan } from "./vocabulary-hhEFLFoL.js";
 //#region src/conditions/ast.d.ts
 type ConditionRef = {
   readonly ref: string;
@@ -133,6 +132,38 @@ declare function isCondition(value: unknown): value is Condition;
 declare function isSqlFunctionField(value: unknown): value is SqlFunctionField;
 declare function hasConditionOp(condition: Condition | undefined, op: Condition["op"]): boolean;
 //#endregion
+//#region src/conditions/normalize.d.ts
+type FieldOperator = {
+  readonly eq?: unknown;
+  readonly ne?: unknown;
+  readonly gt?: unknown;
+  readonly gte?: unknown;
+  readonly lt?: unknown;
+  readonly lte?: unknown;
+  readonly contains?: unknown;
+  readonly in?: unknown;
+  readonly notIn?: unknown;
+  readonly isNull?: boolean;
+};
+type WhereShorthand<T = Record<string, unknown>> = {
+  readonly and?: readonly WhereShorthand<T>[];
+  readonly or?: readonly WhereShorthand<T>[];
+  readonly not?: WhereShorthand<T>;
+} & ("subject" extends keyof T ? { readonly [K in keyof T as Exclude<K, "subject">]?: FieldWhere<T[K]>; } & {
+  readonly subject?: SubjectWhere | FieldWhere<T["subject"]>;
+} : { readonly [K in keyof T]?: FieldWhere<T[K]>; } & {
+  /** Holds only when the resolver checked the session live (`liveSession: true`). */
+  readonly subject?: SubjectWhere;
+});
+type SubjectWhere = {
+  readonly session: {
+    readonly live: true;
+  };
+};
+type FieldWhere<V> = V | FieldOperator | {
+  readonly ref: string;
+};
+//#endregion
 //#region src/core/subject.d.ts
 type JsonWebKeyLike = {
   readonly kty?: string;
@@ -197,6 +228,13 @@ type Membership = {
    * Every other grant, allow or deny, ignores it, and so do role listings.
    */
   readonly keep?: readonly string[];
+  /**
+   * Data the application owns about this membership (a department, a seat
+   * label). Plain JSON from a trusted membership source, checked by
+   * `definePolicy(…, { x: { membership } })`. Never read in evaluation,
+   * 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`. */
@@ -216,7 +254,12 @@ type CustomRoleBody = {
   readonly name: string;
   readonly includes?: readonly string[];
   readonly grants?: readonly CustomRoleGrant[];
-  readonly meta?: Readonly<Record<string, unknown>>;
+  /**
+   * Display text and app data, carried onto the role leaf
+   * `assignableRoles()` returns. `x` is checked by the role tree's
+   * `defineRoles(…, { x })` schema; an invalid `x` is dropped, not the role.
+   */
+  readonly meta?: RoleMeta;
 };
 /** A role a tenant defines, held on memberships inside that tenant. */
 type TenantCustomRole = CustomRoleBody & {
@@ -296,98 +339,26 @@ type Subject<TPrincipal extends Principal = Principal> = {
   readonly liveSession?: true;
 };
 //#endregion
-//#region src/core/scopes.d.ts
-/** One entry of `definePolicy({ scopes })`: the row field holding the scope id, and its parent scope. */
-type ScopeDeclaration = {
-  readonly key: string;
-  readonly within?: string;
+//#region src/core/decision.d.ts
+type DenialReason = "no-grant" | "condition" | "deny" | "inactive-grant" | "closure-error" | "opaque-condition" | "server-only" | "anonymous" | "not-delegated" | "no-delegation" | "insufficient-user-authentication" | "not-entitled" | "purpose" | "reason-required" | "actor-required" | "limit" | "limit-unavailable" | "relation-depth" | "relation-unavailable" | "validation" | "tenant-mismatch" | "no-membership" | "scope" | "expired-membership" | "stale-credentials" | "unknown-role" | "last-holder" | "max-holders" | "transfer-only" | "not-assignable-by" | "self-demotion" | "externally-managed" | "not-allowed-for-membership" | "conflicting-role" | "approval" | "stale-approval" | "pdp-denied" | "pdp-unavailable" | "pdp-invalid-response" | "undocumented" | "unsupported" | "exceeds-creator" | "credential-policy";
+/** The `detail` each denial reason carries, where PermDock sets a structured one. */
+type DenialDetails = {
+  readonly limit: LimitDetail;
+  /** The window the inactive allow applies in. */
+  readonly "inactive-grant": GrantValidity;
+  /** The matching deny's declared `name`. */
+  readonly deny: {
+    readonly name?: string;
+  };
 };
-type PolicyScopesInput = Readonly<Record<string, ScopeDeclaration>>;
 /**
- * A declared scope, in declaration order. `key` is absent only on the
- * implicit `tenant` / `team` pair of a policy that declares no scopes.
+ * Why a candidate grant did not apply. `Denial<"limit">` types `detail` for a
+ * reason in `DenialDetails`; any other reason's detail is `unknown`.
  */
-type Scope = {
-  readonly name: string;
-  readonly key?: string;
-  readonly within?: string;
-};
-/** The names `role(..., { on })`, `memberOf` and memberships may use: declared names plus the aliases. */
-type ScopeNames<S> = [S] extends [PolicyScopesInput] ? string extends keyof S ? string : (keyof S & string) | "tenant" | "team" : string;
-//#endregion
-//#region src/core/grantee.d.ts
-type RoleGrantee = {
-  readonly kind: "role";
-  readonly role: string;
-  /** `'global'`, a scope name, or one resource. */
-  readonly scope: string | {
-    readonly resource: string;
-  };
-};
-type AnyoneGrantee = {
-  readonly kind: "anyone";
-};
-type AuthenticatedGrantee = {
-  readonly kind: "authenticated";
-};
-type RelationGrantee = {
-  readonly kind: "relation";
-  readonly resource: string;
-  readonly relation: string;
-  /**
-   * `'parent'`: follow the row's `parent` chain upward to `resource`, then its
-   * own parents. A list of link names: follow those to-one links from the row
-   * to `resource`, then walk its parents only when `depth` is set.
-   */
-  readonly through?: "parent" | readonly string[];
-  /** Parent hops walked above the first `resource` instance; absent means `DEFAULT_RELATION_DEPTH` for `'parent'` and `0` for links. */
-  readonly depth?: number;
-};
-type PlanGrantee = {
-  readonly kind: "plan";
-  readonly plan: string;
-};
-type ActorGrantee = {
-  readonly kind: "actor";
-  readonly actor: string;
-};
-type AssuranceGrantee = {
-  readonly kind: "assurance";
-  readonly acr?: readonly string[];
-  readonly amr?: readonly string[];
-  readonly maxAge?: number;
-};
-type InheritGrantee = {
-  readonly kind: "inherit";
-  readonly permission: string;
-  readonly resource: string;
-  readonly through: "parent" | readonly string[];
-};
-type Grantee = RoleGrantee | InheritGrantee | AnyoneGrantee | AuthenticatedGrantee | RelationGrantee | PlanGrantee | ActorGrantee | AssuranceGrantee;
-type GranteeInput = Grantee | Role | Plan | string | readonly GranteeInput[];
-declare function anyone(): AnyoneGrantee;
-declare function authenticated(): AuthenticatedGrantee;
-declare function relation(resource: Permission | PermissionTree, name: string, options?: {
-  readonly through?: "parent" | readonly string[];
-  readonly depth?: number;
-}): RelationGrantee;
-declare function inherit(permission: Permission, options: {
-  readonly through: "parent" | readonly string[];
-}): InheritGrantee;
-declare function plan(name: Plan | string): PlanGrantee;
-declare function actor(kind: string): ActorGrantee;
-declare function assurance(options: {
-  readonly acr?: string | readonly string[];
-  readonly amr?: string | readonly string[];
-  readonly maxAge?: number;
-}): AssuranceGrantee;
-//#endregion
-//#region src/core/decision.d.ts
-type DenialReason = "no-grant" | "condition" | "deny" | "inactive-grant" | "closure-error" | "opaque-condition" | "server-only" | "anonymous" | "not-delegated" | "no-delegation" | "insufficient-user-authentication" | "not-entitled" | "purpose" | "reason-required" | "actor-required" | "limit" | "limit-unavailable" | "relation-depth" | "relation-unavailable" | "validation" | "tenant-mismatch" | "no-membership" | "scope" | "expired-membership" | "stale-credentials" | "unknown-role" | "last-holder" | "max-holders" | "transfer-only" | "not-assignable-by" | "self-demotion" | "externally-managed" | "not-allowed-for-membership" | "conflicting-role" | "approval" | "stale-approval" | "pdp-denied" | "pdp-unavailable" | "pdp-invalid-response" | "undocumented" | "unsupported" | "exceeds-creator" | "credential-policy";
-type Denial = {
+type Denial<R extends DenialReason = DenialReason> = {
   readonly role: string | null;
-  readonly reason: DenialReason;
-  readonly detail?: unknown;
+  readonly reason: R;
+  readonly detail?: [R] extends [keyof DenialDetails] ? DenialDetails[R] : unknown;
   readonly to?: Grantee | readonly Grantee[];
 };
 type MatchedGrant = {
@@ -395,6 +366,8 @@ type MatchedGrant = {
   readonly permission: string;
   /** The grant's declared `name`, when it has one. */
   readonly name?: string;
+  /** The grant's declared `meta`, when it has one; PermDock never reads it. */
+  readonly meta?: GrantMeta;
   readonly to?: Grantee | readonly Grantee[];
   readonly where?: Grant["where"];
   readonly check?: Grant["check"];
@@ -410,12 +383,21 @@ type MatchedGrant = {
  * `limit` was past its count; `near-limit`: usage reached `alertAt`.
  * `notify` / `review`: a break-glass grant's declared follow-ups.
  * `justify`: the break-glass reason, carried so audit records why.
+ * `app`: a follow-up the application declared on the grant
+ * (`allow(p, { obligations })`); PermDock carries it and never acts on it.
  */
 type Obligation = {
   readonly kind: "over-limit" | "near-limit" | "notify" | "review";
 } | {
   readonly kind: "justify";
   readonly reason: string;
+} | AppObligation;
+/** An obligation the application declares on an allow and handles itself. */
+type AppObligation = {
+  readonly kind: "app";
+  /** Lower case letters, digits, `_` and `-`, starting with a letter. */
+  readonly name: string;
+  readonly detail?: MetaValue;
 };
 /** What is left of the `limit` that applied; `resetsAt` is Unix seconds. */
 type Quota = {
@@ -479,6 +461,11 @@ type GrantedDecision = {
 };
 type DeniedDecision = {
   readonly outcome: "denied";
+  /**
+   * The key of the permission that was checked. Absent on a denial for a
+   * check that named no declared permission.
+   */
+  readonly permission?: string;
   readonly denials: readonly Denial[];
   readonly alternatives: readonly Permission[];
   /** Present only with `explain: true`. */
@@ -498,64 +485,116 @@ type ExplainedDecision = Decision & {
 };
 type Decision = GrantedDecision | DeniedDecision | ApprovalRequiredDecision;
 //#endregion
-//#region src/core/approval-policies.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.
- */
-type ApprovalPolicy = {
-  /** The permission key; a former key from `renamed` resolves. */
-  readonly permission: string;
-  /** 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;
+//#region src/core/grantee.d.ts
+type RoleGrantee = {
+  readonly kind: "role";
+  readonly role: string;
+  /** `'global'`, a scope name, or one resource. */
+  readonly scope: string | {
+    readonly resource: string;
+  };
+};
+type AnyoneGrantee = {
+  readonly kind: "anyone";
+};
+type AuthenticatedGrantee = {
+  readonly kind: "authenticated";
+};
+type RelationGrantee = {
+  readonly kind: "relation";
+  readonly resource: string;
+  readonly relation: string;
   /**
-   * The same shape as `allow(..., { approval })`. An `escalation` here widens
-   * only this entry's stages, never the code's.
+   * `'parent'`: follow the row's `parent` chain upward to `resource`, then its
+   * own parents. A list of link names: follow those to-one links from the row
+   * to `resource`, then walk its parents only when `depth` is set.
    */
-  readonly approval: ApprovalOption;
+  readonly through?: "parent" | readonly string[];
+  /** Parent hops walked above the first `resource` instance; absent means `DEFAULT_RELATION_DEPTH` for `'parent'` and `0` for links. */
+  readonly depth?: number;
+};
+type PlanGrantee = {
+  readonly kind: "plan";
+  readonly plan: string;
+};
+type ActorGrantee = {
+  readonly kind: "actor";
+  readonly actor: string;
+};
+type AssuranceGrantee = {
+  readonly kind: "assurance";
+  readonly acr?: readonly string[];
+  readonly amr?: readonly string[];
+  readonly maxAge?: number;
+};
+type InheritGrantee = {
+  readonly kind: "inherit";
+  readonly permission: string;
+  readonly resource: string;
+  readonly through: "parent" | readonly string[];
+};
+type Grantee = RoleGrantee | InheritGrantee | AnyoneGrantee | AuthenticatedGrantee | RelationGrantee | PlanGrantee | ActorGrantee | AssuranceGrantee;
+type GranteeInput = Grantee | Role | Plan | string | readonly GranteeInput[];
+declare function anyone(): AnyoneGrantee;
+declare function authenticated(): AuthenticatedGrantee;
+declare function relation(resource: Permission | PermissionTree, name: string, options?: {
+  readonly through?: "parent" | readonly string[];
+  readonly depth?: number;
+}): RelationGrantee;
+declare function inherit(permission: Permission, options: {
+  readonly through: "parent" | readonly string[];
+}): InheritGrantee;
+declare function plan(name: Plan | string): PlanGrantee;
+declare function actor(kind: string): ActorGrantee;
+declare function assurance(options: {
+  readonly acr?: string | readonly string[];
+  readonly amr?: string | readonly string[];
+  readonly maxAge?: number;
+}): AssuranceGrantee;
+//#endregion
+//#region src/core/approvers.d.ts
+/** One named approver, by principal id. */
+type UserApprover = {
+  readonly kind: "user";
+  readonly id: string;
 };
 /**
- * Data-driven approval requirements, a subject input like `RoleSource`:
- * 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.
+ * Whoever holds `permission` in the request's tenant, through any role,
+ * custom roles included. Checked only through verdict facts
+ * (`ApprovalVerdict.permissions`) that the handler computes from the
+ * approver's own instance.
  */
-type ApprovalPolicySource = {
-  approvalPoliciesFor(query: {
-    readonly tenants: readonly string[];
-  }): readonly ApprovalPolicy[] | Promise<readonly ApprovalPolicy[]>;
+type PermissionApprover = {
+  readonly kind: "permission";
+  readonly permission: string;
+};
+/** An approver who matches at least one item; an item that is a list matches when every entry does. */
+type AnyOfApprover = {
+  readonly kind: "any-of";
+  readonly of: readonly (Approver | readonly Approver[])[];
 };
-/** The denial detail when an `ApprovalPolicySource` fails: every call an allow would grant denies with reason `approval`. */
-declare const APPROVAL_POLICY_UNAVAILABLE = "approval-policy-unavailable";
-declare function memoryApprovalPolicies(policies: readonly ApprovalPolicy[]): ApprovalPolicySource;
 /**
- * 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`.
+ * 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.
  */
-type ApprovalPolicyProblem = "unknown-permission" | "invalid" | "where-on-collection" | "stale-on-without-version";
-type ApprovalPolicyValidation = {
-  readonly ok: true;
-} | {
-  readonly ok: false;
-  readonly problem: ApprovalPolicyProblem;
+type Approver = Grantee | UserApprover | PermissionApprover | AnyOfApprover;
+type ApproverInput = GranteeInput | UserApprover | PermissionApprover | {
+  readonly kind: "any-of";
+  readonly of: readonly ApproverInput[];
+} | readonly ApproverInput[];
+/** Approves when the approver holds `permission` in the request's tenant (any role, custom roles included). */
+declare function holder(permission: Permission): PermissionApprover;
+/** Approves when the approver matches any one of `items`. */
+declare function anyOf(...items: readonly ApproverInput[]): {
+  readonly kind: "any-of";
+  readonly of: readonly ApproverInput[];
 };
-/**
- * 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;
+/** Approves when the approver matches every one of `items`; the same as a list. */
+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;
 //#endregion
 //#region src/core/arazzo.d.ts
 type ArazzoSimulateInput = {
@@ -618,6 +657,218 @@ type ActivateInput = {
   readonly reason?: string;
 };
 //#endregion
+//#region src/core/wire-denial.d.ts
+/**
+ * A denial as it leaves the process: in a decision event, a Problem Details
+ * body, an MCP or WebMCP refusal and the decision endpoint. `detail` is a
+ * JSON value (a string, or `LimitDetail` on `limit`); what a closure threw
+ * and a validation error stay in process.
+ */
+type WireDenial = {
+  readonly role: string | null;
+  readonly reason: DenialReason;
+  readonly to?: Grantee | readonly Grantee[];
+  readonly detail?: unknown;
+};
+/** A `Decision` whose denials are `WireDenial`s, as the decision endpoint sends it. */
+type WireDecision = GrantedDecision | ApprovalRequiredDecision | (Omit<DeniedDecision, "denials"> & {
+  readonly denials: readonly WireDenial[];
+});
+//#endregion
+//#region src/core/event-types.d.ts
+type DirectoryEvent = {
+  readonly type: "directory";
+  readonly at: string;
+  readonly source: "scim";
+  readonly operation: "create" | "replace" | "patch" | "delete";
+  readonly tenant: string;
+  readonly resource: {
+    readonly type: "User" | "Group";
+    readonly id: string;
+  };
+  readonly credential: {
+    readonly kind: "token";
+  } | {
+    readonly kind: "jwt";
+    readonly iss?: string;
+  };
+  readonly active?: boolean;
+};
+type MembershipEvent = {
+  readonly type: "membership";
+  readonly at: string;
+  readonly source: string;
+  readonly operation: "added" | "removed" | "changed";
+  readonly principal: {
+    readonly id: string;
+  };
+  /** A declared scope name, or the `tenant` / `team` alias; absent for a global role change. */
+  readonly scope?: string;
+  /** The scope instance; present exactly when `scope` is. */
+  readonly id?: string;
+  /** The id of every ancestor scope, keyed by scope name. */
+  readonly within?: Readonly<Record<string, string>>;
+  readonly via?: string;
+  /** When the membership lapses, in seconds since the epoch. */
+  readonly expiresAt?: number;
+  readonly roles: {
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+  };
+  readonly by?: {
+    readonly id: string;
+    readonly kind: string;
+  };
+};
+/**
+ * An API key's lifecycle: `created`, `rotated` and `revoked` from the
+ * application or a credential store, `used` from `subjectFromApiKey`. A
+ * `used` event carries `sample`, the fraction of uses reported.
+ */
+type CredentialEvent = {
+  readonly type: "credential";
+  readonly at: string;
+  readonly source: string;
+  readonly operation: "created" | "used" | "rotated" | "revoked";
+  readonly credential: {
+    readonly id: string;
+    readonly kind: CredentialKind;
+  };
+  readonly principal: {
+    readonly id: string;
+  };
+  readonly tenant?: string;
+  readonly expiresAt?: number;
+  readonly by?: {
+    readonly id: string;
+    readonly kind: string;
+  };
+  readonly sample?: number;
+};
+type SinkEvent = DecisionEvent | DirectoryEvent | MembershipEvent | CredentialEvent | AccessEvent;
+/**
+ * A support-access session lifecycle event: a tenant consented to vendor
+ * support (`started`), the session lapsed (`ended`), or the tenant pulled
+ * consent early (`revoked`). It never decides; it records what happened for
+ * audit and revocation.
+ */
+type AccessEvent = {
+  readonly type: "access";
+  readonly at: string;
+  readonly source: string;
+  readonly operation: "started" | "ended" | "revoked";
+  readonly tenant: string;
+  readonly principal: {
+    readonly id: string;
+  };
+  /** The membership kind the session runs under (`support`). */
+  readonly via: string;
+  readonly roles: readonly string[];
+  readonly member?: {
+    readonly group: string;
+  };
+  readonly expiresAt?: number;
+  /** The tenant principal that consented. */
+  readonly grantedBy?: string;
+  readonly reason?: string;
+  readonly actor?: {
+    readonly id: string;
+    readonly kind: string;
+  };
+};
+type DecisionEvent = {
+  readonly type: "decision";
+  readonly at: string;
+  readonly outcome: "granted" | "denied" | "approval-required";
+  readonly permission: string;
+  readonly scope: string;
+  readonly resource: {
+    readonly type: string;
+    readonly id?: string;
+  };
+  readonly subject: {
+    readonly principal: {
+      readonly id: string;
+      readonly roles: readonly string[];
+      readonly tenant?: string;
+    } | null;
+    readonly actor?: {
+      readonly id: string;
+      readonly kind: string;
+    };
+    readonly delegation?: {
+      readonly scopes?: readonly string[];
+      readonly authorizationDetails?: readonly unknown[];
+    };
+    /** The API key the subject came from. */
+    readonly credential?: {
+      readonly id: string;
+      readonly kind: CredentialKind;
+    };
+  };
+  readonly tenant?: string;
+  readonly membership?: Membership;
+  readonly via?: string | null;
+  readonly matched?: {
+    readonly role: string | null;
+    readonly permission: string;
+    /** The grant's declared `name`. */
+    readonly name?: string;
+    /** The grant's declared `meta`; PermDock never reads it. */
+    readonly meta?: GrantMeta;
+    readonly to?: Grantee | readonly Grantee[];
+    readonly hosted?: HostedGrantRef;
+    readonly breakGlass?: true;
+  };
+  /** What a granted decision owes, as on `GrantedDecision.obligations`. */
+  readonly obligations?: readonly Obligation[];
+  /** Purposes of use the caller asserted (`context.purpose`); present when any was. */
+  readonly purpose?: readonly string[];
+  /** The justification the caller supplied (`context.reason`); present when set. */
+  readonly reason?: string;
+  readonly denials?: readonly WireDenial[];
+  readonly alternatives?: readonly string[];
+  readonly token?: string;
+  readonly trusted: boolean;
+  readonly source: "can" | "decide" | "assert" | "filter" | "endpoint" | "adapter" | "approval" | "simulate" | "explain";
+  readonly adapter?: string;
+  readonly phase?: "requested" | "resolved";
+  readonly counts?: {
+    readonly granted: number;
+    readonly denied: number;
+    readonly approvalRequired: number;
+  };
+};
+type AuthEvent = {
+  readonly reason: "invalid-token" | "schema" | "unknown-role" | "groups-overflow" | "source-threw";
+  readonly cause?: string;
+  readonly source: string;
+  readonly kid?: string;
+  readonly alg?: string;
+  readonly typ?: string;
+  readonly issuer?: string;
+  readonly requestId?: string;
+};
+//#endregion
+//#region src/core/scopes.d.ts
+/** One entry of `definePolicy({ scopes })`: the row field holding the scope id, and its parent scope. */
+type ScopeDeclaration = {
+  readonly key: string;
+  readonly within?: string;
+};
+type PolicyScopesInput = Readonly<Record<string, ScopeDeclaration>>;
+/**
+ * A declared scope, in declaration order. `key` is absent only on the
+ * implicit `tenant` / `team` pair of a policy that declares no scopes.
+ */
+type Scope = {
+  readonly name: string;
+  readonly key?: string;
+  readonly within?: string;
+};
+/** The names `role(..., { on })`, `memberOf` and memberships may use: declared names plus the aliases. */
+type ScopeNames<S> = [S] extends [PolicyScopesInput] ? string extends keyof S ? string : (keyof S & string) | "tenant" | "team" : string;
+//#endregion
 //#region src/core/ownership.d.ts
 /** Who a role change is about: their principal id and their membership in the scope instance. */
 type RoleChangeTarget = {
@@ -643,41 +894,168 @@ type RoleChangeBase = {
   readonly holders?: number;
 };
 /**
- * A role held at a named scope instance (`scope` is a declared name or alias
- * and `id` the instance), or a global role: `scope: 'global'` with no `id`.
- * A global change has no tenant, so `within` and `holders` do not apply to it.
- */
-type RoleChange = RoleChangeBase & ({
-  /** The scope the role is held at (a declared name or alias). */
-  readonly scope: string;
-  /** The scope instance. */
-  readonly id: string;
-} | {
-  readonly scope: "global";
-  readonly id?: undefined;
-});
-/**
- * `granted` names the role that authorised the change (`null` when a
- * `meta.manageRoles` holder or the declared-role ceiling did); `denied` lists
- * every rule the change breaks.
+ * A role held at a named scope instance (`scope` is a declared name or alias
+ * and `id` the instance), or a global role: `scope: 'global'` with no `id`.
+ * A global change has no tenant, so `within` and `holders` do not apply to it.
+ */
+type RoleChange = RoleChangeBase & ({
+  /** The scope the role is held at (a declared name or alias). */
+  readonly scope: string;
+  /** The scope instance. */
+  readonly id: string;
+} | {
+  readonly scope: "global";
+  readonly id?: undefined;
+});
+/**
+ * `granted` names the role that authorised the change (`null` when a
+ * `meta.manageRoles` holder or the declared-role ceiling did); `denied` lists
+ * every rule the change breaks.
+ */
+type RoleChangeDecision = {
+  readonly outcome: "granted";
+  readonly change: RoleChange;
+  readonly role: string | null;
+} | {
+  readonly outcome: "denied";
+  readonly change: RoleChange;
+  readonly denials: readonly Denial[];
+};
+type RoleChangeOptions = {
+  /**
+   * `true` when the application loaded `change.within` from its own store
+   * (the instance's stored parent), not from the request. Without it, a
+   * nested instance's tenant comes only from a live membership the actor
+   * holds on that instance or under it.
+   */
+  readonly trusted?: boolean;
+};
+//#endregion
+//#region src/core/snapshot-types.d.ts
+type Snapshot = {
+  readonly v: 1;
+  readonly issuedAt: number;
+  readonly subject: {
+    readonly principal: {
+      readonly id: string;
+      readonly roles: readonly string[];
+      readonly plans?: readonly string[];
+      readonly tenant?: string;
+      readonly memberships?: readonly Membership[];
+    } | null;
+    readonly delegation?: Subject["delegation"];
+    readonly context: Readonly<Record<string, unknown>>;
+  };
+  /** Roles held in the active tenant, in rank order. */
+  readonly roles: readonly string[];
+  /** The distinct `meta.audience` values of `roles`, in rank order; absent when none has one. */
+  readonly audiences?: readonly string[];
+  readonly grants: readonly SnapshotGrant[];
+  readonly tenants: readonly string[];
+  readonly include?: readonly string[];
+  readonly simulated?: true;
+  readonly expiresAt?: number;
+  readonly vocabulary?: {
+    readonly roles?: Readonly<Record<string, Role>>;
+    readonly plans?: Readonly<Record<string, Plan>>;
+  };
+  /** The policy's scopes in order, so a client checks the row against each membership's instance. */
+  readonly scopes?: readonly SnapshotScope[];
+  /** One entry per tenant in `tenants`: what the subject may hand out there. Absent without tenants. */
+  readonly assignable?: readonly SnapshotAssignable[];
+  /**
+   * Allow grants of held roles that only a plan the subject lacks keeps
+   * from applying; they grant nothing and name the plan a denial asks for.
+   */
+  readonly notEntitled?: readonly SnapshotNotEntitled[];
+  /**
+   * The row id field per resource whose `id` option is not `id`, for the
+   * grants in `grants`. Absent when every one reads `id`.
+   */
+  readonly ids?: Readonly<Record<string, string>>;
+  /**
+   * The permission keys the policy's delegations let the actor use for the
+   * principal, sorted; present only when one applies. Outside it a check is
+   * `not-delegated`; inside it a token delegation, when there is one, must
+   * still cover.
+   */
+  readonly delegated?: readonly string[];
+};
+/** A grant the subject would hold on another plan: its permission, role and `to`. */
+type SnapshotNotEntitled = {
+  readonly permission: string;
+  readonly role: string | null;
+  readonly to: Grantee | readonly Grantee[];
+};
+/** One declared scope as a snapshot carries it. */
+type SnapshotScope = {
+  readonly name: string;
+  readonly key: string;
+  readonly within?: string;
+  /** Resources whose rows this scope's key partitions, from their `memberOf` relations. */
+  readonly resources?: readonly string[];
+  /** Resource name to the field holding this scope's id, for a resource whose field is not `key` (its own `id`). */
+  readonly fields?: Readonly<Record<string, string>>;
+};
+/** The declared roles and the custom-role ceiling the subject may assign in one tenant. */
+type SnapshotAssignable = {
+  readonly tenant: string;
+  readonly roles: readonly string[];
+  readonly permissions: readonly Permission[];
+  /** Permission key to the levels the subject may hand out; only permissions whose resource declares levels. */
+  readonly levels?: Readonly<Record<string, readonly string[]>>;
+};
+type SnapshotGrant = {
+  readonly permission: string;
+  readonly effect: "allow" | "deny";
+  readonly role: string | null;
+  readonly to: Grantee | readonly Grantee[];
+  readonly where?: Condition;
+  readonly check?: Condition;
+  readonly approval?: "human" | ApprovalRequirement;
+  /** A scope name or one resource; absent for a global grant. */
+  readonly scope?: string | {
+    readonly resource: string;
+  };
+  readonly membership?: Membership;
+  readonly portable?: false;
+  readonly fields?: readonly string[];
+  /** When the grant applies (Unix seconds, `from` inclusive, `until` exclusive); absent means always. */
+  readonly validity?: GrantValidity;
+  /** The grant's declared `name`. */
+  readonly name?: string;
+  /** The grant's declared `meta`; visible to the client that holds the snapshot. */
+  readonly meta?: GrantMeta;
+  /** The app obligations an allow declares, emitted on a granted decision. */
+  readonly obligations?: readonly AppObligation[];
+};
+/**
+ * What a policy grants, as JSON a client builds snapshots from without the
+ * policy: `localSnapshotManifest(policy)` writes it, `localSnapshot` in
+ * `permdock/react-native` reads it.
  */
-type RoleChangeDecision = {
-  readonly outcome: "granted";
-  readonly change: RoleChange;
-  readonly role: string | null;
-} | {
-  readonly outcome: "denied";
-  readonly change: RoleChange;
-  readonly denials: readonly Denial[];
+type LocalSnapshotManifest = {
+  readonly v: 1;
+  readonly scopes?: readonly SnapshotScope[];
+  readonly vocabulary?: Snapshot["vocabulary"];
+  /** Declared role names; a custom role cannot take one. */
+  readonly roles: readonly string[];
+  /** Declared role names in rank order, when an `assigns` graph ranks them. */
+  readonly rank?: readonly string[];
+  /** Every declared grant, without a membership. */
+  readonly grants: readonly SnapshotGrant[];
+  /** Per custom-role scope (`global` for platform roles): the grants each entry resolves to. */
+  readonly custom: Readonly<Record<string, LocalCustomRoleTable>>;
 };
-type RoleChangeOptions = {
-  /**
-   * `true` when the application loaded `change.within` from its own store
-   * (the instance's stored parent), not from the request. Without it, a
-   * nested instance's tenant comes only from a live membership the actor
-   * holds on that instance or under it.
-   */
-  readonly trusted?: boolean;
+/** Grants a custom role entry resolves to, held by a placeholder role the client renames. */
+type LocalCustomRoleTable = {
+  /** `{ permission }` per permission key, and `{ permission, level }` per declared level. */
+  readonly permissions: Readonly<Record<string, {
+    readonly all: readonly SnapshotGrant[];
+    readonly levels?: Readonly<Record<string, readonly SnapshotGrant[]>>;
+  }>>;
+  /** `includes: [role]` per declared role. */
+  readonly includes: Readonly<Record<string, readonly SnapshotGrant[]>>;
 };
 //#endregion
 //#region src/core/validation.d.ts
@@ -722,6 +1100,65 @@ type WhoCan = {
   readonly complete: boolean;
 };
 //#endregion
+//#region src/core/approval-policies.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.
+ */
+type ApprovalPolicy = {
+  /** The permission key; a former key from `renamed` resolves. */
+  readonly permission: string;
+  /** 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;
+};
+/**
+ * Data-driven approval requirements, a subject input like `RoleSource`:
+ * 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 = {
+  approvalPoliciesFor(query: {
+    readonly tenants: readonly string[];
+  }): readonly ApprovalPolicy[] | Promise<readonly ApprovalPolicy[]>;
+};
+/** The denial detail when an `ApprovalPolicySource` fails: every call an allow would grant denies with reason `approval`. */
+declare const APPROVAL_POLICY_UNAVAILABLE = "approval-policy-unavailable";
+declare function memoryApprovalPolicies(policies: readonly ApprovalPolicy[]): ApprovalPolicySource;
+/**
+ * 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;
+};
+/**
+ * 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;
+//#endregion
 //#region src/core/hosted.d.ts
 /** One grant authored in PermDock Cloud; its grantee is a declared role, plan or relation. */
 type HostedGrant = {
@@ -1014,6 +1451,11 @@ type PermDockOptions = {
   readonly relations?: RelationSource;
   /** Approval requirements kept as data; they add to the code's and never remove one. A throw denies. */
   readonly approvalPolicies?: ApprovalPolicySource;
+  /**
+   * Request values an adapter's `context` hook derived on the server, merged
+   * into `subject.context`; keys from `policy.context` win on a clash.
+   */
+  readonly context?: Readonly<Record<string, unknown>>;
 };
 declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, user: TUser | Subject | null, options?: PermDockOptions): PermDock<V> | Promise<PermDock<V>>;
 //#endregion
@@ -1162,24 +1604,6 @@ declare function credentialSubject(credential: Credential, options: {
  */
 declare function decideCredential(permdock: PermDock, request: CredentialRequest, options?: DecideCredentialOptions): Promise<CredentialDecision>;
 //#endregion
-//#region src/core/wire-denial.d.ts
-/**
- * A denial as it leaves the process: in a decision event, a Problem Details
- * body, an MCP or WebMCP refusal and the decision endpoint. `detail` is a
- * JSON value (a string, or `LimitDetail` on `limit`); what a closure threw
- * and a validation error stay in process.
- */
-type WireDenial = {
-  readonly role: string | null;
-  readonly reason: DenialReason;
-  readonly to?: Grantee | readonly Grantee[];
-  readonly detail?: unknown;
-};
-/** A `Decision` whose denials are `WireDenial`s, as the decision endpoint sends it. */
-type WireDecision = GrantedDecision | ApprovalRequiredDecision | (Omit<DeniedDecision, "denials"> & {
-  readonly denials: readonly WireDenial[];
-});
-//#endregion
 //#region src/core/interfaces.d.ts
 type DecisionProvider = {
   readonly name: string;
@@ -1334,7 +1758,6 @@ type EntitlementSource = {
     readonly tenant?: string;
   }): string[] | Promise<string[]>;
 };
-declare function memoryEntitlementSource(entries: Readonly<Record<string, readonly string[]>>): EntitlementSource;
 type JwtClaims = {
   readonly iss?: string;
   readonly sub?: string;
@@ -1380,126 +1803,7 @@ type TokenSigner = {
 };
 type SubjectResolver<TInput, TPrincipal extends Principal = Principal> = (input: TInput, options?: {
   readonly tenant?: string;
-}) => Subject<TPrincipal> | Promise<Subject<TPrincipal>>;
-type Snapshot = {
-  readonly v: 1;
-  readonly issuedAt: number;
-  readonly subject: {
-    readonly principal: {
-      readonly id: string;
-      readonly roles: readonly string[];
-      readonly plans?: readonly string[];
-      readonly tenant?: string;
-      readonly memberships?: readonly Membership[];
-    } | null;
-    readonly delegation?: Subject["delegation"];
-    readonly context: Readonly<Record<string, unknown>>;
-  };
-  /** Roles held in the active tenant, in rank order. */
-  readonly roles: readonly string[];
-  /** The distinct `meta.audience` values of `roles`, in rank order; absent when none has one. */
-  readonly audiences?: readonly string[];
-  readonly grants: readonly SnapshotGrant[];
-  readonly tenants: readonly string[];
-  readonly include?: readonly string[];
-  readonly simulated?: true;
-  readonly expiresAt?: number;
-  readonly vocabulary?: {
-    readonly roles?: Readonly<Record<string, Role>>;
-    readonly plans?: Readonly<Record<string, Plan>>;
-  };
-  /** The policy's scopes in order, so a client checks the row against each membership's instance. */
-  readonly scopes?: readonly SnapshotScope[];
-  /** One entry per tenant in `tenants`: what the subject may hand out there. Absent without tenants. */
-  readonly assignable?: readonly SnapshotAssignable[];
-  /**
-   * Allow grants of held roles that only a plan the subject lacks keeps
-   * from applying; they grant nothing and name the plan a denial asks for.
-   */
-  readonly notEntitled?: readonly SnapshotNotEntitled[];
-  /**
-   * The row id field per resource whose `id` option is not `id`, for the
-   * grants in `grants`. Absent when every one reads `id`.
-   */
-  readonly ids?: Readonly<Record<string, string>>;
-  /**
-   * The permission keys the policy's delegations let the actor use for the
-   * principal, sorted; present only when one applies. Outside it a check is
-   * `not-delegated`; inside it a token delegation, when there is one, must
-   * still cover.
-   */
-  readonly delegated?: readonly string[];
-};
-/** A grant the subject would hold on another plan: its permission, role and `to`. */
-type SnapshotNotEntitled = {
-  readonly permission: string;
-  readonly role: string | null;
-  readonly to: Grantee | readonly Grantee[];
-};
-/** One declared scope as a snapshot carries it. */
-type SnapshotScope = {
-  readonly name: string;
-  readonly key: string;
-  readonly within?: string;
-  /** Resources whose rows this scope's key partitions, from their `memberOf` relations. */
-  readonly resources?: readonly string[];
-  /** Resource name to the field holding this scope's id, for a resource whose field is not `key` (its own `id`). */
-  readonly fields?: Readonly<Record<string, string>>;
-};
-/** The declared roles and the custom-role ceiling the subject may assign in one tenant. */
-type SnapshotAssignable = {
-  readonly tenant: string;
-  readonly roles: readonly string[];
-  readonly permissions: readonly Permission[];
-  /** Permission key to the levels the subject may hand out; only permissions whose resource declares levels. */
-  readonly levels?: Readonly<Record<string, readonly string[]>>;
-};
-type SnapshotGrant = {
-  readonly permission: string;
-  readonly effect: "allow" | "deny";
-  readonly role: string | null;
-  readonly to: Grantee | readonly Grantee[];
-  readonly where?: Condition;
-  readonly check?: Condition;
-  readonly approval?: "human" | ApprovalRequirement;
-  /** A scope name or one resource; absent for a global grant. */
-  readonly scope?: string | {
-    readonly resource: string;
-  };
-  readonly membership?: Membership;
-  readonly portable?: false;
-  readonly fields?: readonly string[];
-  /** When the grant applies (Unix seconds, `from` inclusive, `until` exclusive); absent means always. */
-  readonly validity?: GrantValidity;
-};
-/**
- * What a policy grants, as JSON a client builds snapshots from without the
- * policy: `localSnapshotManifest(policy)` writes it, `localSnapshot` in
- * `permdock/react-native` reads it.
- */
-type LocalSnapshotManifest = {
-  readonly v: 1;
-  readonly scopes?: readonly SnapshotScope[];
-  readonly vocabulary?: Snapshot["vocabulary"];
-  /** Declared role names; a custom role cannot take one. */
-  readonly roles: readonly string[];
-  /** Declared role names in rank order, when an `assigns` graph ranks them. */
-  readonly rank?: readonly string[];
-  /** Every declared grant, without a membership. */
-  readonly grants: readonly SnapshotGrant[];
-  /** Per custom-role scope (`global` for platform roles): the grants each entry resolves to. */
-  readonly custom: Readonly<Record<string, LocalCustomRoleTable>>;
-};
-/** Grants a custom role entry resolves to, held by a placeholder role the client renames. */
-type LocalCustomRoleTable = {
-  /** `{ permission }` per permission key, and `{ permission, level }` per declared level. */
-  readonly permissions: Readonly<Record<string, {
-    readonly all: readonly SnapshotGrant[];
-    readonly levels?: Readonly<Record<string, readonly SnapshotGrant[]>>;
-  }>>;
-  /** `includes: [role]` per declared role. */
-  readonly includes: Readonly<Record<string, readonly SnapshotGrant[]>>;
-};
+}) => Subject<TPrincipal> | Promise<Subject<TPrincipal>>;
 type SnapshotSource = {
   get(): Promise<Snapshot | string> | Snapshot | string;
   subscribe?(listener: () => void): () => void;
@@ -1525,106 +1829,6 @@ type DecisionSink = {
   write(events: readonly SinkEvent[]): Promise<void> | void;
   flush?(): Promise<void>;
 };
-type DirectoryEvent = {
-  readonly type: "directory";
-  readonly at: string;
-  readonly source: "scim";
-  readonly operation: "create" | "replace" | "patch" | "delete";
-  readonly tenant: string;
-  readonly resource: {
-    readonly type: "User" | "Group";
-    readonly id: string;
-  };
-  readonly credential: {
-    readonly kind: "token";
-  } | {
-    readonly kind: "jwt";
-    readonly iss?: string;
-  };
-  readonly active?: boolean;
-};
-type MembershipEvent = {
-  readonly type: "membership";
-  readonly at: string;
-  readonly source: string;
-  readonly operation: "added" | "removed" | "changed";
-  readonly principal: {
-    readonly id: string;
-  };
-  /** A declared scope name, or the `tenant` / `team` alias; absent for a global role change. */
-  readonly scope?: string;
-  /** The scope instance; present exactly when `scope` is. */
-  readonly id?: string;
-  /** The id of every ancestor scope, keyed by scope name. */
-  readonly within?: Readonly<Record<string, string>>;
-  readonly via?: string;
-  /** When the membership lapses, in seconds since the epoch. */
-  readonly expiresAt?: number;
-  readonly roles: {
-    readonly added: readonly string[];
-    readonly removed: readonly string[];
-  };
-  readonly by?: {
-    readonly id: string;
-    readonly kind: string;
-  };
-};
-/**
- * An API key's lifecycle: `created`, `rotated` and `revoked` from the
- * application or a credential store, `used` from `subjectFromApiKey`. A
- * `used` event carries `sample`, the fraction of uses reported.
- */
-type CredentialEvent = {
-  readonly type: "credential";
-  readonly at: string;
-  readonly source: string;
-  readonly operation: "created" | "used" | "rotated" | "revoked";
-  readonly credential: {
-    readonly id: string;
-    readonly kind: CredentialKind;
-  };
-  readonly principal: {
-    readonly id: string;
-  };
-  readonly tenant?: string;
-  readonly expiresAt?: number;
-  readonly by?: {
-    readonly id: string;
-    readonly kind: string;
-  };
-  readonly sample?: number;
-};
-type SinkEvent = DecisionEvent | DirectoryEvent | MembershipEvent | CredentialEvent | AccessEvent;
-/**
- * A support-access session lifecycle event: a tenant consented to vendor
- * support (`started`), the session lapsed (`ended`), or the tenant pulled
- * consent early (`revoked`). It never decides; it records what happened for
- * audit and revocation.
- */
-type AccessEvent = {
-  readonly type: "access";
-  readonly at: string;
-  readonly source: string;
-  readonly operation: "started" | "ended" | "revoked";
-  readonly tenant: string;
-  readonly principal: {
-    readonly id: string;
-  };
-  /** The membership kind the session runs under (`support`). */
-  readonly via: string;
-  readonly roles: readonly string[];
-  readonly member?: {
-    readonly group: string;
-  };
-  readonly expiresAt?: number;
-  /** The tenant principal that consented. */
-  readonly grantedBy?: string;
-  readonly reason?: string;
-  readonly actor?: {
-    readonly id: string;
-    readonly kind: string;
-  };
-};
 /**
  * Looks up the credential an API key stands for. `null` for a key that is
  * malformed, unknown, revoked or whose secret does not match; never throws
@@ -1640,73 +1844,6 @@ type CredentialVerifier = {
    */
   touch?(id: string, at: number): void | Promise<void>;
 };
-type DecisionEvent = {
-  readonly type: "decision";
-  readonly at: string;
-  readonly outcome: "granted" | "denied" | "approval-required";
-  readonly permission: string;
-  readonly scope: string;
-  readonly resource: {
-    readonly type: string;
-    readonly id?: string;
-  };
-  readonly subject: {
-    readonly principal: {
-      readonly id: string;
-      readonly roles: readonly string[];
-      readonly tenant?: string;
-    } | null;
-    readonly actor?: {
-      readonly id: string;
-      readonly kind: string;
-    };
-    readonly delegation?: {
-      readonly scopes?: readonly string[];
-      readonly authorizationDetails?: readonly unknown[];
-    };
-    /** The API key the subject came from. */
-    readonly credential?: {
-      readonly id: string;
-      readonly kind: CredentialKind;
-    };
-  };
-  readonly tenant?: string;
-  readonly membership?: Membership;
-  readonly via?: string | null;
-  readonly matched?: {
-    readonly role: string | null;
-    readonly permission: string;
-    readonly to?: Grantee | readonly Grantee[];
-    readonly hosted?: HostedGrantRef;
-    readonly breakGlass?: true;
-  };
-  /** Purposes of use the caller asserted (`context.purpose`); present when any was. */
-  readonly purpose?: readonly string[];
-  /** The justification the caller supplied (`context.reason`); present when set. */
-  readonly reason?: string;
-  readonly denials?: readonly WireDenial[];
-  readonly alternatives?: readonly string[];
-  readonly token?: string;
-  readonly trusted: boolean;
-  readonly source: "can" | "decide" | "assert" | "filter" | "endpoint" | "adapter" | "approval" | "simulate" | "explain";
-  readonly adapter?: string;
-  readonly phase?: "requested" | "resolved";
-  readonly counts?: {
-    readonly granted: number;
-    readonly denied: number;
-    readonly approvalRequired: number;
-  };
-};
-type AuthEvent = {
-  readonly reason: "invalid-token" | "schema" | "unknown-role" | "groups-overflow" | "source-threw";
-  readonly cause?: string;
-  readonly source: string;
-  readonly kid?: string;
-  readonly alg?: string;
-  readonly typ?: string;
-  readonly issuer?: string;
-  readonly requestId?: string;
-};
 /** What one tenant configures for itself. Every field only tightens. */
 type TenantSettings = {
   /** Rules for API keys created in, or used against, this tenant. */
@@ -1719,92 +1856,11 @@ type TenantSettings = {
 type SettingsSource = {
   settingsFor(tenant: string): TenantSettings | undefined | Promise<TenantSettings | undefined>;
 };
-declare function memorySettings(settings: Readonly<Record<string, TenantSettings>>): SettingsSource;
-/** Memberships keyed by principal id; `tenant` is not a filter, as for a database source. */
-declare function memoryMembershipSource(entries: Readonly<Record<string, readonly Membership[]>>): MembershipSource;
-/** A snapshot held in memory; `set` replaces it and notifies every subscriber. */
-declare function memorySnapshotSource(initial: Snapshot | string): SnapshotSource & {
-  set(snapshot: Snapshot | string): void;
-};
-declare function memoryRoleSource(customRoles: readonly CustomRole[]): RoleSource;
-//#endregion
-//#region src/conditions/normalize.d.ts
-type FieldOperator = {
-  readonly eq?: unknown;
-  readonly ne?: unknown;
-  readonly gt?: unknown;
-  readonly gte?: unknown;
-  readonly lt?: unknown;
-  readonly lte?: unknown;
-  readonly contains?: unknown;
-  readonly in?: unknown;
-  readonly notIn?: unknown;
-  readonly isNull?: boolean;
-};
-type WhereShorthand<T = Record<string, unknown>> = {
-  readonly and?: readonly WhereShorthand<T>[];
-  readonly or?: readonly WhereShorthand<T>[];
-  readonly not?: WhereShorthand<T>;
-} & ("subject" extends keyof T ? { readonly [K in keyof T as Exclude<K, "subject">]?: FieldWhere<T[K]>; } & {
-  readonly subject?: SubjectWhere | FieldWhere<T["subject"]>;
-} : { readonly [K in keyof T]?: FieldWhere<T[K]>; } & {
-  /** Holds only when the resolver checked the session live (`liveSession: true`). */
-  readonly subject?: SubjectWhere;
-});
-type SubjectWhere = {
-  readonly session: {
-    readonly live: true;
-  };
-};
-type FieldWhere<V> = V | FieldOperator | {
-  readonly ref: string;
-};
 //#endregion
-//#region src/core/approvers.d.ts
-/** One named approver, by principal id. */
-type UserApprover = {
-  readonly kind: "user";
-  readonly id: string;
-};
-/**
- * Whoever holds `permission` in the request's tenant, through any role,
- * custom roles included. Checked only through verdict facts
- * (`ApprovalVerdict.permissions`) that the handler computes from the
- * approver's own instance.
- */
-type PermissionApprover = {
-  readonly kind: "permission";
-  readonly permission: string;
-};
-/** An approver who matches at least one item; an item that is a list matches when every entry does. */
-type AnyOfApprover = {
-  readonly kind: "any-of";
-  readonly of: readonly (Approver | readonly Approver[])[];
-};
-/**
- * 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.
- */
-type Approver = Grantee | UserApprover | PermissionApprover | AnyOfApprover;
-type ApproverInput = GranteeInput | UserApprover | PermissionApprover | {
-  readonly kind: "any-of";
-  readonly of: readonly ApproverInput[];
-} | readonly ApproverInput[];
-/** Approves when the approver holds `permission` in the request's tenant (any role, custom roles included). */
-declare function holder(permission: Permission): PermissionApprover;
-/** Approves when the approver matches any one of `items`. */
-declare function anyOf(...items: readonly ApproverInput[]): {
-  readonly kind: "any-of";
-  readonly of: readonly ApproverInput[];
-};
-/** Approves when the approver matches every one of `items`; the same as a list. */
-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;
+//#region src/core/policy-fingerprint.d.ts
+declare const POLICY_X: unique symbol;
 //#endregion
-//#region src/core/policy.d.ts
+//#region src/core/policy-types.d.ts
 type ClosureContext = {
   readonly subject: {
     readonly principal: Principal | null;
@@ -1988,9 +2044,20 @@ type GrantOptions<T = Record<string, unknown>> = {
   readonly limit?: GrantLimit;
   readonly reason?: string;
   readonly fields?: readonly (keyof T & string)[];
-  /** A name a `breakGlass` override may lift; only meaningful on a deny. */
+  /**
+   * A stable name for the grant. On a deny, a `breakGlass` override may lift
+   * it; on any grant, it is reported on `decision.matched.name` and on
+   * decision events.
+   */
   readonly name?: string;
   readonly group?: string;
+  /** Display text and app data for the grant, reported on `decision.matched.meta`; never read in evaluation. */
+  readonly meta?: GrantMeta;
+  /**
+   * Follow-ups the application owes when this allow grants: each becomes a
+   * `{ kind: 'app', name, detail? }` obligation on the decision. Allows only.
+   */
+  readonly obligations?: readonly ObligationInput[];
   /** Purposes of use (`context.purpose`) that make the grant apply; non-portable. */
   readonly purpose?: readonly string[];
   /** The grant applies from this instant on (RFC 3339 string or Unix seconds); before it an allow denies with `inactive-grant` and a deny does not apply. */
@@ -2004,6 +2071,17 @@ type GrantOptions<T = Record<string, unknown>> = {
    */
   readonly requires?: Permission | readonly Permission[];
 };
+/** A grant's metadata. PermDock carries it to decisions, events, snapshots and the catalog and never reads `x`. */
+type GrantMeta = {
+  readonly description?: string;
+  /** Data the application owns. Plain JSON, checked by `definePolicy(…, { x: { grant } })`. */
+  readonly x?: AppData;
+};
+/** An app obligation as declared on an allow: its name, or its name and detail. */
+type ObligationInput = string | {
+  readonly name: string;
+  readonly detail?: MetaValue;
+};
 /**
  * When a grant applies, in Unix seconds. `from` is inclusive, `until`
  * exclusive; either may be absent. Portable: `where()` drops an inactive
@@ -2091,9 +2169,12 @@ type Grant = {
   readonly limit?: GrantLimit;
   readonly fields?: readonly string[];
   readonly scope: GrantScope;
-  /** A name a `breakGlass` override may lift; only meaningful on a deny. */
+  /** The grant's stable name: a `breakGlass` override lifts a named deny, and `decision.matched.name` reports it. */
   readonly name?: string;
   readonly group?: string;
+  readonly meta?: GrantMeta;
+  /** App obligations an allow adds to its granted decision. */
+  readonly obligations?: readonly AppObligation[];
   /** Purposes of use that make the grant apply (`context.purpose`); non-portable. */
   readonly purpose?: readonly string[];
   /** Set on a break-glass allow: it overrides named denies and carries obligations. */
@@ -2158,6 +2239,8 @@ type Policy<TUser = unknown, TPrincipal extends Principal = Principal, V extends
   readonly onDenied?: (decision: unknown) => never | void;
   readonly fingerprint: string;
   readonly resources: ReadonlyMap<string, ResourceNode>;
+  /** The app data schemas `definePolicy` was given; symbol-keyed so freezing the policy leaves the schemas alone. */
+  readonly [POLICY_X]?: PolicyAppDataSchemas;
   readonly providers?: readonly DecisionProvider[];
   /** Permission keys a hosted policy document may grant or deny; empty by default. */
   readonly hostable: readonly string[];
@@ -2187,23 +2270,21 @@ type PolicyIndex = {
   /** The grants `grantList` returns, by permission key, in the same order. */
   readonly grantsByKey: ReadonlyMap<string, readonly Grant[]>;
 };
-declare function normalizeApproval(approval: ApprovalOption | undefined, permission?: string): Grant["approval"];
 type GrantCondition<T, K extends PermissionKind> = K extends "collection" ? Omit<GrantOptions<T>, "where" | "fields"> | ClosureGrantFn<T> : GrantOptions<T> | ClosureGrantFn<T>;
-declare function allow<T, K extends PermissionKind = PermissionKind>(permission: Permission<string, T, K> | readonly Permission<string, T, K>[], condition?: GrantCondition<T, K>): Omit<Grant, "role" | "scope"> | Omit<Grant, "role" | "scope">[];
-declare function deny<T, K extends PermissionKind = PermissionKind>(permission: Permission<string, T, K> | readonly Permission<string, T, K>[], condition?: GrantCondition<T, K>): Omit<Grant, "role" | "scope"> | Omit<Grant, "role" | "scope">[];
-type RoleGrants = readonly (Omit<Grant, "role" | "scope"> | readonly Omit<Grant, "role" | "scope">[])[];
-/** A role held at a named scope: `on` is checked against `definePolicy({ scopes })`. */
-declare function role<const S extends string>(name: string | Role, grants: RoleGrants, options: RoleOptions<S> & {
-  readonly on: S;
-}): RoleBinding<S>;
-/** A global role, or one held on a resource. */
-declare function role(name: string | Role, grants: RoleGrants, options?: RoleOptions<never>): RoleBinding<never>;
-/** Options built at runtime: the scope name is only checked by `definePolicy`. */
-declare function role(name: string | Role, grants: RoleGrants, options?: RoleOptions): RoleBinding;
-declare function normalizeAssurance(input: AssuranceRequirement | undefined): AssuranceRequirement | undefined;
 /** Resource name to level name to its normalised condition. */
 type PolicyLevels = Readonly<Record<string, Readonly<Record<string, Condition>>>>;
+/**
+ * Standard Schemas for the app data a policy carries. `grant` checks every
+ * grant's `meta.x` at `definePolicy` and throws on invalid data; `membership`
+ * checks `Membership.x` as each subject resolves, dropping an invalid `x`
+ * (never the membership) with an `on('auth')` event of reason `schema`.
+ */
+type PolicyAppDataSchemas = {
+  readonly grant?: AppDataSchema<unknown>;
+  readonly membership?: AppDataSchema<unknown>;
+};
 type DefinePolicyOptions<TUser, TPrincipal extends Principal, S extends PolicyScopesInput = PolicyScopesInput> = {
+  readonly x?: PolicyAppDataSchemas;
   readonly roles?: readonly RoleBinding<ScopeNames<S>>[];
   readonly grants?: readonly (Omit<Grant, "role" | "scope"> | readonly Omit<Grant, "role" | "scope">[] | Grant)[];
   /**
@@ -2243,7 +2324,6 @@ type DefinePolicyOptions<TUser, TPrincipal extends Principal, S extends PolicySc
    */
   readonly oauthScopes?: Readonly<Record<string, readonly (Permission | PermissionTree)[]>>;
 };
-declare function definePolicy<TUser, TPrincipal extends Principal, const Input extends PermissionTree | PolicyVocabulary, const S extends PolicyScopesInput = PolicyScopesInput>(permissions: Input, options: DefinePolicyOptions<TUser, TPrincipal, S>): Policy<TUser, TPrincipal, VocabularyFromInput<Input>>;
 type MembershipFixture = {
   readonly principal?: string;
   readonly tenant?: string;
@@ -2254,7 +2334,6 @@ type SeparationConflict = {
   readonly tenant?: string;
   readonly roles: readonly [string, string];
 };
-declare function separationConflicts(policy: Policy, memberships: readonly MembershipFixture[]): readonly SeparationConflict[];
 type PrincipalOf<P> = P extends Policy<unknown, infer TPrincipal> ? TPrincipal : Principal;
 type SubjectOf<P> = {
   readonly principal: PrincipalOf<P> | null;
@@ -2265,4 +2344,4 @@ type SubjectOf<P> = {
   readonly expiresAt?: number;
 };
 //#endregion
-export { AccessEvent as $, ExplainedDecision as $n, CredentialPrincipal as $t, RoleOptions as A, RoleChangeOptions as An, GnapAccess as Ar, SnapshotSource as At, normalizeApproval as B, simulateArazzo as Bn, MemberOfParent as Br, memoryMembershipSource as Bt, Policy as C, mergeHostedGrants as Cn, Actor as Cr, SettingsSource as Ct, PolicyVocabulary as D, WhoCan as Dn, CustomRole as Dr, SnapshotGrant as Dt, PolicyScopes as E, HoldingVia as En, Binding as Er, SnapshotAssignable as Et, SupportConsent as F, ArazzoFinding as Fn, VerifiedClaims as Fr, TokenVerifier as Ft, Approver as G, ApprovalPolicyValidation as Gn, SqlFunctionArg as Gr, WireDenial as Gt, role as H, ApprovalPolicy as Hn, RelatedCondition as Hr, memorySettings as Ht, ValidateMode as I, ArazzoPlan as In, Condition as Ir, VerificationFailure as It, UserApprover as J, ApprovalRequiredDecision as Jn, isCondition as Jr, CredentialKind as Jt, ApproverInput as K, memoryApprovalPolicies as Kn, SqlFunctionCondition as Kr, Credential as Kt, allow as L, ArazzoSimulateInput as Ln, ConditionRef as Lr, VerifiedToken as Lt, SeparationConflict as M, ActivateInput as Mn, Membership as Mr, TenantSettings as Mt, SubjectOf as N, breakGlass as Nn, Principal as Nr, TokenFailureCause as Nt, PrincipalOf as O, RoleChange as On, CustomRoleGrant as Or, SnapshotNotEntitled as Ot, SupportAccessOptions as P, supportAccess as Pn, Subject as Pr, TokenSigner as Pt, user as Q, DeniedDecision as Qn, CredentialPolicyViolation as Qt, definePolicy as R, ArazzoStepResult as Rn, ConditionValue as Rr, WhereCompiler as Rt, MembershipFixture as S, memoryPolicySource as Sn, ScopeNames as Sr, RoleSourceFactory as St, PolicyOAuthScope as T, Holder as Tn, AuthorizationDetail as Tr, Snapshot as Tt, separationConflicts as U, ApprovalPolicyProblem as Un, RelatedHop as Ur, memorySnapshotSource as Ut, normalizeAssurance as V, APPROVAL_POLICY_UNAVAILABLE as Vn, OpaqueCondition as Vr, memoryRoleSource as Vt, AnyOfApprover as W, ApprovalPolicySource as Wn, RestrictedAncestors as Wr, WireDecision as Wt, anyOf as X, Denial as Xn, isConditionRef as Xr, CredentialPermissionInput as Xt, allOf as Y, Decision as Yn, isConditionDate as Yr, CredentialPermission as Yt, holder as Z, DenialReason as Zn, isSqlFunctionField as Zr, CredentialPolicy as Zt, GrantLimit as _, HostedGrantDropReason as _n, plan as _r, RelationChain as _t, ApprovalRequirement as a, decideCredential as an, Trace as ar, DecisionSink as at, GrantValidity as b, PolicySource as bn, Scope as br, RelationSource as bt, BreakGlassOptions as c, DeriveOptions as cn, Grantee as cr, JwtClaims as ct, ClosureContext as d, RowPair as dn, RelationGrantee as dr, LimitStore as dt, CredentialRequest as en, GrantedDecision as er, AuthEvent as et, ClosureGrantFn as f, SimulateOptions as fn, actor as fr, LocalCustomRoleTable as ft, GrantCondition as g, HostedGrant as gn, inherit as gr, MembershipSource as gt, Grant as h, createPermDock as hn, authenticated as hr, MembershipEvent as ht, ApprovalOption as i, credentialSubject as in, Quota as ir, DecisionProvider as it, RoleScope as j, RoleChangeTarget as jn, JsonWebKeyLike as jr, SubjectResolver as jt, RoleBinding as k, RoleChangeDecision as kn, Delegation as kr, SnapshotScope as kt, BreakGlassRequirements as l, PermDock as ln, GranteeInput as lr, LimitConsumeInput as lt, DelegationTarget as m, WhereResult as mn, assurance as mr, MemberEntry as mt, ApprovalEscalation as n, credentialDelegation as nn, MatchedGrant as nr, CredentialVerifier as nt, ApprovalStage as o, parseCredential as on, TraceSkip as or, DirectoryEvent as ot, DelegationInput as p, SnapshotOptions as pn, anyone as pr, LocalSnapshotManifest as pt, PermissionApprover as q, validateApprovalPolicy as qn, hasConditionOp as qr, CredentialDecision as qt, ApprovalMode as r, credentialPolicyViolation as rn, Obligation as rr, DecisionEvent as rt, AssuranceRequirement as s, DecideOptions as sn, TraceSkipReason as sr, EntitlementSource as st, ActivationOption as t, DecideCredentialOptions as tn, LimitDetail as tr, CredentialEvent as tt, BreakGlassSpec as u, PermDockOptions as un, InheritGrantee as ur, LimitRemaining as ut, GrantOptions as v, HostedGrantDropped as vn, relation as vr, RelationGroup as vt, PolicyDelegation as w, parsePolicyDocument as wn, Assurance as wr, SinkEvent as wt, HostedGrantRef as x, isPortableCondition as xn, ScopeDeclaration as xr, RoleSource as xt, GrantScope as y, PolicyDocument as yn, PolicyScopesInput as yr, RelationHolder as yt, deny as z, arazzoFindings as zn, MemberOfCondition as zr, memoryEntitlementSource as zt };
+export { RelationGroup as $, inherit as $n, validateApprovalPolicy as $t, PolicyScopes as A, ArazzoFinding as An, VerifiedClaims as Ar, DeriveOptions as At, ValidateMode as B, UserApprover as Bn, SqlFunctionArg as Br, HostedGrantDropped as Bt, HostedGrantRef as C, MembershipEvent as Cn, CustomRoleGrant as Cr, DecideCredentialOptions as Ct, PolicyAppDataSchemas as D, ActivateInput as Dn, Membership as Dr, decideCredential as Dt, Policy as E, WireDenial as En, JsonWebKeyLike as Er, credentialSubject as Et, RoleScope as F, simulateArazzo as Fn, MemberOfParent as Fr, SnapshotOptions as Ft, EntitlementSource as G, Grantee as Gn, isConditionRef as Gr, mergeHostedGrants as Gt, CredentialVerifier as H, anyOf as Hn, hasConditionOp as Hr, PolicySource as Ht, SeparationConflict as I, AnyOfApprover as In, OpaqueCondition as Ir, WhereResult as It, LimitRemaining as J, RelationGrantee as Jn, ApprovalPolicy as Jt, JwtClaims as K, GranteeInput as Kn, isSqlFunctionField as Kr, parsePolicyDocument as Kt, SubjectOf as L, Approver as Ln, RelatedCondition as Lr, createPermDock as Lt, PrincipalOf as M, ArazzoSimulateInput as Mn, ConditionRef as Mr, PermDockOptions as Mt, RoleBinding as N, ArazzoStepResult as Nn, ConditionValue as Nr, RowPair as Nt, PolicyDelegation as O, breakGlass as On, Principal as Or, parseCredential as Ot, RoleOptions as P, arazzoFindings as Pn, MemberOfCondition as Pr, SimulateOptions as Pt, RelationChain as Q, authenticated as Qn, memoryApprovalPolicies as Qt, SupportAccessOptions as R, ApproverInput as Rn, RelatedHop as Rr, HostedGrant as Rt, GrantValidity as S, DirectoryEvent as Sn, CustomRole as Sr, CredentialRequest as St, ObligationInput as T, WireDecision as Tn, GnapAccess as Tr, credentialPolicyViolation as Tt, DecisionProvider as U, holder as Un, isCondition as Ur, isPortableCondition as Ut, VocabularyFromInput as V, allOf as Vn, SqlFunctionCondition as Vr, PolicyDocument as Vt, DecisionSink as W, user as Wn, isConditionDate as Wr, memoryPolicySource as Wt, MemberEntry as X, anyone as Xn, ApprovalPolicySource as Xt, LimitStore as Y, actor as Yn, ApprovalPolicyProblem as Yt, MembershipSource as Z, assurance as Zn, ApprovalPolicyValidation as Zt, GrantCondition as _, ScopeNames as _n, TraceSkipReason as _r, CredentialPermission as _t, ApprovalRequirement as a, Snapshot as an, Denial as ar, SnapshotSource as at, GrantOptions as b, CredentialEvent as bn, AuthorizationDetail as br, CredentialPolicyViolation as bt, BreakGlassOptions as c, SnapshotNotEntitled as cn, DeniedDecision as cr, TokenFailureCause as ct, ClosureContext as d, RoleChangeDecision as dn, LimitDetail as dr, VerificationFailure as dt, Holder as en, plan as er, RelationHolder as et, ClosureGrantFn as f, RoleChangeOptions as fn, MatchedGrant as fr, VerifiedToken as ft, Grant as g, ScopeDeclaration as gn, TraceSkip as gr, CredentialKind as gt, DelegationTarget as h, Scope as hn, Trace as hr, CredentialDecision as ht, ApprovalOption as i, LocalSnapshotManifest as in, Decision as ir, SettingsSource as it, PolicyVocabulary as j, ArazzoPlan as jn, Condition as jr, PermDock as jt, PolicyOAuthScope as k, supportAccess as kn, Subject as kr, DecideOptions as kt, BreakGlassRequirements as l, SnapshotScope as ln, ExplainedDecision as lr, TokenSigner as lt, DelegationInput as m, PolicyScopesInput as mn, Quota as mr, Credential as mt, ApprovalEscalation as n, WhoCan as nn, AppObligation as nr, RoleSource as nt, ApprovalStage as o, SnapshotAssignable as on, DenialDetails as or, SubjectResolver as ot, DefinePolicyOptions as p, RoleChangeTarget as pn, Obligation as pr, WhereCompiler as pt, LimitConsumeInput as q, InheritGrantee as qn, APPROVAL_POLICY_UNAVAILABLE as qt, ApprovalMode as r, LocalCustomRoleTable as rn, ApprovalRequiredDecision as rr, RoleSourceFactory as rt, AssuranceRequirement as s, SnapshotGrant as sn, DenialReason as sr, TenantSettings as st, ActivationOption as t, HoldingVia as tn, relation as tr, RelationSource as tt, BreakGlassSpec as u, RoleChange as un, GrantedDecision as ur, TokenVerifier as ut, GrantLimit as v, AccessEvent as vn, Actor as vr, CredentialPermissionInput as vt, MembershipFixture as w, SinkEvent as wn, Delegation as wr, credentialDelegation as wt, GrantScope as x, DecisionEvent as xn, Binding as xr, CredentialPrincipal as xt, GrantMeta as y, AuthEvent as yn, Assurance as yr, CredentialPolicy as yt, SupportConsent as z, PermissionApprover as zn, RestrictedAncestors as zr, HostedGrantDropReason as zt };