permdock 0.0.0 → 0.1.0

package/dist/policy-CInmNGkM.d.ts

@@ -0,0 +1,1959 @@
+import { _ as ResourceNode, d as Permission, f as PermissionKind, p as PermissionTree } from "./permissions-B4apnahQ.js";
+import { a as RoleTree, i as RoleMeta, n as PlanTree, r as Role, t as Plan } from "./vocabulary-Dk0fs-Jk.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/conditions/ast.d.ts
+type ConditionRef = {
+  readonly ref: string;
+};
+type ConditionDate = {
+  readonly date: string;
+};
+type ConditionValue = string | number | boolean | null | readonly ConditionValue[] | ConditionRef | ConditionDate;
+type ComparisonOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "contains";
+type ComparisonCondition = {
+  readonly op: ComparisonOp;
+  readonly field: string;
+  readonly value: ConditionValue;
+};
+type InCondition = {
+  readonly op: "in" | "notIn";
+  readonly field: string;
+  readonly value: readonly ConditionValue[] | ConditionRef;
+};
+type IsNullCondition = {
+  readonly op: "isNull";
+  readonly field: string;
+  readonly value: boolean;
+};
+type AndCondition = {
+  readonly op: "and";
+  readonly conditions: readonly Condition[];
+};
+type OrCondition = {
+  readonly op: "or";
+  readonly conditions: readonly Condition[];
+};
+type NotCondition = {
+  readonly op: "not";
+  readonly condition: Condition;
+};
+type MemberOfCondition = {
+  readonly op: "memberOf";
+  /** A declared scope name (or the `tenant` / `team` alias), or `'resource'`. */
+  readonly scope: string;
+  readonly field: string;
+  readonly roles: readonly string[];
+  readonly resource?: string;
+  readonly parents?: readonly MemberOfParent[];
+};
+/**
+ * A row field holding an ancestor's id. The keyed form matches only a
+ * membership on that resource; a bare field name matches a membership on any
+ * resource whose id equals the field.
+ */
+type MemberOfParent = string | {
+  readonly field: string;
+  readonly resource: string;
+};
+/**
+ * The subject holds `relation` on the `resource` instance whose id the row's
+ * `field` holds, or on one of its ancestors within `depth` parent hops.
+ * Evaluated through a `RelationSource` in process, the closure table in RLS,
+ * and, given relation mappings, a subquery in the `toWhere` compilers.
+ */
+type RelatedCondition = {
+  readonly op: "related";
+  readonly resource: string;
+  readonly relation: string;
+  /** The row's own id field, or (with `parent` or `hops`) the field holding the next instance's id. */
+  readonly field: string;
+  /** Parent hops walked above the first `resource` instance; `0` reads only that instance. */
+  readonly depth: number;
+  /** The row is a child of `resource`, reached through `field`. */
+  readonly parent?: true;
+  /**
+   * To-one links from the row to `resource`: `field` points at the first
+   * hop's resource, each later hop follows `link` on the resource before it,
+   * and the last hop's resource is `resource`.
+   */
+  readonly hops?: readonly RelatedHop[];
+  /**
+   * The `resource` instances the subject holds a resource role on; replaces
+   * the `relation` lookup (`relation` is then empty).
+   */
+  readonly ids?: readonly string[];
+  /**
+   * The row's boolean column that keeps ancestor grants out: with `parent` or
+   * `hops`, a restricted row matches nothing; without, the walk stops at the row.
+   */
+  readonly restricted?: string;
+};
+type RelatedHop = {
+  readonly link: string;
+  readonly resource: string;
+};
+type OpaqueCondition = {
+  readonly op: "opaque";
+  readonly sql: string;
+  readonly fingerprint: string;
+};
+type SqlFunctionField = {
+  readonly field: string;
+};
+type SqlFunctionArg = ConditionValue | SqlFunctionField;
+type SqlFunctionCondition = {
+  readonly op: "sqlFunction";
+  readonly name: string;
+  readonly args: readonly SqlFunctionArg[];
+  readonly twin: Condition;
+};
+type Condition = ComparisonCondition | InCondition | IsNullCondition | AndCondition | OrCondition | NotCondition | MemberOfCondition | RelatedCondition | OpaqueCondition | SqlFunctionCondition;
+declare function isConditionRef(value: unknown): value is ConditionRef;
+declare function isConditionDate(value: unknown): value is ConditionDate;
+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/core/subject.d.ts
+type JsonWebKeyLike = {
+  readonly kty?: string;
+  readonly [key: string]: unknown;
+};
+type Binding = {
+  readonly jkt?: string;
+  readonly "x5t#S256"?: string;
+  readonly jwk?: JsonWebKeyLike;
+  readonly kid?: string;
+};
+/**
+ * One OpenID Connect for Identity Assurance `verified_claims` entry, kept as
+ * the issuer sent it: opaque, frozen evidence for conditions and audit.
+ */
+type VerifiedClaims = {
+  readonly verification: Readonly<Record<string, unknown>> & {
+    readonly trust_framework: string;
+  };
+  readonly claims: Readonly<Record<string, unknown>>;
+};
+type Assurance = {
+  readonly acr?: string;
+  readonly amr?: readonly string[];
+  readonly authTime?: number;
+  readonly verified?: readonly VerifiedClaims[];
+};
+/**
+ * Roles held in one scope instance (`scope` + `id`, with the id of every
+ * ancestor scope in `within`) or on one resource (`on`). Evaluation only sees
+ * the canonical form; `tenant` / `team` are accepted as input for the first
+ * and second declared scope and normalised away.
+ */
+type Membership = {
+  readonly scope?: string;
+  readonly id?: string;
+  readonly within?: Readonly<Record<string, string>>;
+  readonly on?: {
+    readonly resource: string;
+    readonly id: string;
+  };
+  readonly roles: readonly string[];
+  /** Roles the holder may activate here but does not hold; `permdock.activate` writes an elevated membership. */
+  readonly eligible?: readonly string[];
+  readonly via?: string;
+  readonly expiresAt?: number;
+  /** The principal id that wrote this membership: who elevated, consented to or granted the access. */
+  readonly grantedBy?: string;
+  /** Free text recording why the membership was written: the activation or consent justification. */
+  readonly reason?: string;
+  /** A subgroup the holder belongs to inside the instance (`vendor-support`); a `fromJunction` group column fills it. */
+  readonly member?: {
+    readonly group: string;
+  };
+  /** `idp`: the identity provider (SCIM) owns this membership; the application must not edit it. */
+  readonly managedBy?: "idp";
+  /** Seats this membership holds (`dev-mode`, `editor`); `plan()` grantees match them inside the active tenant. */
+  readonly entitlements?: readonly string[];
+  /** Input only: an instance of the first scope. */
+  readonly tenant?: string;
+  /** Input only: an instance of the second scope, inside `tenant`. */
+  readonly team?: string;
+};
+/**
+ * One permission a custom role adds or removes. It names a declared
+ * permission key and carries no condition, approval or limit of its own.
+ */
+type CustomRoleGrant = {
+  readonly permission: string;
+  readonly effect?: "allow" | "deny";
+};
+type CustomRoleBody = {
+  readonly name: string;
+  readonly includes?: readonly string[];
+  readonly grants?: readonly CustomRoleGrant[];
+  readonly meta?: Readonly<Record<string, unknown>>;
+};
+/** A role a tenant defines, held on memberships inside that tenant. */
+type TenantCustomRole = CustomRoleBody & {
+  /** The instance of the first scope that owns the role. */
+  readonly tenant: string;
+  /** The scope the role is held at; defaults to the first scope. Its ceiling is that scope's assignable roles. */
+  readonly scope?: string;
+  /** Pins the role to one instance of `scope`. */
+  readonly id?: string;
+  /** Input only: `scope` = the second scope, `id` = this team. */
+  readonly team?: string;
+};
+/**
+ * A role the platform defines, held through `principal.roles` like a declared
+ * global role. Its ceiling is the allows of the declared global roles marked
+ * `assignable`.
+ */
+type GlobalCustomRole = CustomRoleBody & {
+  readonly scope: "global";
+  readonly tenant?: undefined;
+  readonly id?: undefined;
+  readonly team?: undefined;
+};
+type CustomRole = TenantCustomRole | GlobalCustomRole;
+type Principal = {
+  readonly id: string;
+  readonly issuer?: string;
+  readonly kind?: "user" | "service" | "workload" | "link";
+  readonly roles?: readonly string[];
+  readonly plans?: readonly string[];
+  readonly memberships?: readonly Membership[];
+  /** The token dropped memberships to stay under its size budget; a `claimsFirst` source reads the rest. */
+  readonly membershipsTruncated?: boolean;
+  /** The authorization version the token was minted at (`authz_ver`). */
+  readonly authzVersion?: number;
+  readonly tenant?: string;
+  readonly assurance?: Assurance;
+  readonly binding?: Binding;
+  readonly [key: string]: unknown;
+};
+type Actor = {
+  readonly id: string;
+  readonly kind: string;
+  readonly binding?: Binding;
+  /** `true` narrows every policy delegation to this actor to its read-only permissions (`readOnlyHint`). */
+  readonly readOnly?: boolean;
+  readonly [key: string]: unknown;
+};
+type AuthorizationDetail = {
+  readonly type: string;
+  readonly actions?: readonly string[];
+  readonly [key: string]: unknown;
+};
+type GnapAccess = string | Readonly<Record<string, unknown>>;
+type Delegation = {
+  readonly scopes?: readonly string[];
+  readonly authorizationDetails?: readonly AuthorizationDetail[];
+  readonly access?: readonly GnapAccess[];
+  readonly chain?: unknown;
+};
+type Subject<TPrincipal extends Principal = Principal> = {
+  readonly principal: TPrincipal | null;
+  readonly actor?: Actor;
+  readonly delegation?: Delegation;
+  readonly context: Readonly<Record<string, unknown>>;
+  readonly session?: string;
+  readonly expiresAt?: number;
+  /** The token's memberships are behind the source's authorization version: `fresh` permissions deny. */
+  readonly stale?: 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;
+};
+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/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 Grantee = RoleGrantee | 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 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 = {
+  readonly role: string | null;
+  readonly reason: DenialReason;
+  readonly detail?: unknown;
+  readonly to?: Grantee | readonly Grantee[];
+};
+type MatchedGrant = {
+  readonly role: string | null;
+  readonly permission: string;
+  /** The grant's declared `name`, when it has one. */
+  readonly name?: string;
+  readonly to?: Grantee | readonly Grantee[];
+  readonly where?: Grant["where"];
+  readonly check?: Grant["check"];
+  readonly approval?: "human" | ApprovalRequirement;
+  readonly provider?: string;
+  /** The hosted policy document fingerprint and grant id, when a hosted grant matched. */
+  readonly hosted?: HostedGrantRef;
+  /** A break-glass grant overrode a matching deny. */
+  readonly breakGlass?: true;
+};
+/**
+ * Something the caller owes alongside a granted action. `over-limit`: a soft
+ * `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.
+ */
+type Obligation = {
+  readonly kind: "over-limit" | "near-limit" | "notify" | "review";
+} | {
+  readonly kind: "justify";
+  readonly reason: string;
+};
+/** What is left of the `limit` that applied; `resetsAt` is Unix seconds. */
+type Quota = {
+  readonly remaining: number;
+  readonly resetsAt: number;
+};
+/**
+ * The `detail` of a `limit` denial: the grant's `count`, its window in
+ * seconds and when the window resets (Unix seconds).
+ */
+type LimitDetail = {
+  readonly count: number;
+  readonly window: number;
+  readonly resetsAt: number;
+};
+/**
+ * Why a candidate grant for the permission was passed over before its
+ * condition ran: `via-only` (the subject holds no membership of its kind),
+ * `purpose` (no asserted purpose it lists), `field` (its `fields` do not
+ * cover the requested field), `grantee` (its `to` did not match and added no
+ * denial), `role` (a role it names is not held), `validity` (a deny outside
+ * its `validFrom` / `validUntil`; an inactive allow adds an `inactive-grant`
+ * denial instead), `break-glass-inactive` (a break-glass grant with no
+ * asserted purpose).
+ */
+type TraceSkipReason = "via-only" | "purpose" | "field" | "grantee" | "role" | "validity" | "break-glass-inactive";
+type TraceSkip = {
+  readonly role: string | null;
+  readonly permission: string;
+  readonly effect: "allow" | "deny";
+  readonly why: TraceSkipReason;
+};
+/**
+ * What `explain` saw: how many candidate grants it examined before the
+ * outcome, which allows matched (including the ones a deny overrode), which
+ * denies matched, and which grants it passed over. `denies[0]` is the deny
+ * that produced a `deny` outcome, or the deny a break-glass grant lifted.
+ * Pure local computation; never on a decision event.
+ */
+type Trace = {
+  readonly evaluated: number;
+  readonly allows: readonly MatchedGrant[];
+  readonly denies: readonly MatchedGrant[];
+  readonly skipped: readonly TraceSkip[];
+};
+type GrantedDecision = {
+  readonly outcome: "granted";
+  readonly subject: Subject;
+  readonly matched: MatchedGrant;
+  readonly token: string;
+  readonly obligations?: readonly Obligation[];
+  readonly quota?: Quota;
+  /**
+   * The membership `permdock.activate` produced for the app to write: an
+   * elevated, time-bound, attributed row. Set only by `activate`; a plain
+   * `decide` never writes memberships.
+   */
+  readonly elevation?: Membership;
+  /** Present only with `explain: true`. */
+  readonly trace?: Trace;
+};
+type DeniedDecision = {
+  readonly outcome: "denied";
+  readonly denials: readonly Denial[];
+  readonly alternatives: readonly Permission[];
+  /** Present only with `explain: true`. */
+  readonly trace?: Trace;
+};
+type ApprovalRequiredDecision = {
+  readonly outcome: "approval-required";
+  readonly grant: MatchedGrant;
+  readonly reason: "human";
+  readonly token: string;
+  /** Present only with `explain: true`. */
+  readonly trace?: Trace;
+};
+/** A decision from `explain`: the same union, with the trace always present. */
+type ExplainedDecision = Decision & {
+  readonly trace: Trace;
+};
+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. */
+  readonly where?: Condition;
+  /** A portable condition over the call's input (the proposed row). */
+  readonly check?: Condition;
+  /** The same shape as `allow(..., { approval })`, without `escalation`. */
+  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[]>;
+};
+declare function memoryApprovalPolicies(policies: readonly ApprovalPolicy[]): ApprovalPolicySource;
+//#endregion
+//#region src/core/arazzo.d.ts
+type ArazzoSimulateInput = {
+  readonly arazzo: unknown;
+  readonly openapi: unknown;
+  readonly workflowId?: string;
+  readonly permissions?: PermissionTree;
+  readonly inputs?: Readonly<Record<string, unknown>>;
+};
+type ArazzoStepResult = {
+  readonly stepId: string;
+  /** The nested workflow that owns the step, when it is not the plan's workflow. */
+  readonly workflowId?: string;
+  readonly operationId?: string;
+  readonly permissions: readonly Permission[];
+  readonly decision: Decision;
+  readonly provisional?: true;
+};
+type ArazzoPlan = {
+  readonly workflowId: string;
+  readonly outcome: Decision["outcome"];
+  readonly steps: readonly ArazzoStepResult[];
+};
+type ArazzoFinding = {
+  readonly stepId: string;
+  readonly workflowId: string;
+  readonly reason: "undocumented" | "unsupported" | "validation" | "unknown-key";
+  readonly detail: string;
+};
+declare function arazzoFindings(input: ArazzoSimulateInput, tree: PermissionTree | undefined): readonly ArazzoFinding[];
+declare function simulateArazzo(input: ArazzoSimulateInput, tree: PermissionTree | undefined, decide: (permission: Permission, data: unknown) => Decision): ArazzoPlan;
+//#endregion
+//#region src/core/elevated.d.ts
+/**
+ * The only deny override: a break-glass grant overrides deny grants whose
+ * `name` it lists, and nothing else. It is an allow that stays non-portable
+ * (RLS never compiles it) and grants only once its `requires` are met.
+ */
+declare function breakGlass<T>(permission: Permission<string, T> | readonly Permission<string, T>[], options?: BreakGlassOptions): Omit<Grant, "role" | "scope"> | Omit<Grant, "role" | "scope">[];
+/**
+ * Support access with tenant consent: a role a vendor holds only through a
+ * consented, time-bound `via: 'support'` membership. `actorRequired` denies
+ * every decision under it without an `act`; `forbid` compiles to deny grants
+ * scoped to `via: 'support'`.
+ */
+declare function supportAccess<const S extends string>(options: SupportAccessOptions<S> & {
+  readonly on: S;
+}): RoleBinding<S>;
+/** Support access held in the `tenant` scope. */
+declare function supportAccess(options: SupportAccessOptions<never>): RoleBinding<"tenant">;
+type ActivateInput = {
+  readonly role: string | Role;
+  /** The scope the activation applies in (a declared name or the `tenant` / `team` alias). */
+  readonly scope: string;
+  readonly id: string;
+  /** Ancestor scope ids, keyed by scope name, for a nested-scope activation. */
+  readonly within?: Readonly<Record<string, string>>;
+  /** How long the elevation lasts; capped at the role's `maxDuration`. */
+  readonly duration?: string;
+  readonly reason?: 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 = {
+  readonly id: string;
+  /** The kind of the target's membership in the instance (`staff`, `contact`, ...). */
+  readonly via?: string;
+  /** The roles the target holds in the instance now. */
+  readonly roles?: readonly string[];
+  /** `idp` when the identity provider owns the target's membership: the application cannot change it. */
+  readonly managedBy?: "idp";
+};
+type RoleChange = {
+  readonly kind: "assign" | "revoke" | "transfer";
+  readonly role: string | Role;
+  /** The scope the role is held at (a declared name or alias). */
+  readonly scope: string;
+  /** The scope instance. */
+  readonly id: string;
+  /** Ids of the instance's ancestor scopes; a holder there may assign here. */
+  readonly within?: Readonly<Record<string, string>>;
+  readonly target: RoleChangeTarget;
+  /**
+   * How many principals hold `role` in the instance now, from the
+   * application's store. Without it a role with `min`, `max` or
+   * `transferOnly` is denied.
+   */
+  readonly holders?: number;
+};
+/**
+ * `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/validation.d.ts
+type Boundary = "http-body" | "mcp-args" | "tool-args" | "decision-endpoint" | "manual";
+//#endregion
+//#region src/core/who-can.d.ts
+/** One way a principal holds a permission on an object. */
+type HoldingVia = {
+  readonly kind: "role";
+  readonly role: string;
+  readonly membership: Membership;
+} | {
+  readonly kind: "relation";
+  readonly resource: string;
+  readonly relation: string;
+  /** The instance the relation is held on: the object or one of its ancestors. */
+  readonly id: string;
+} | {
+  readonly kind: "share";
+  readonly resource: string;
+  readonly relation: string;
+  readonly id: string;
+  readonly expiresAt?: number;
+  /** The group the share names, when the principal holds it as one of its members. */
+  readonly group?: RelationGroup;
+};
+type Holder = {
+  readonly principal: {
+    readonly id: string;
+  };
+  readonly via: readonly HoldingVia[];
+};
+/**
+ * Who holds a permission on one object, for share dialogs and access
+ * reviews. It lists and never grants. `complete: false` means some grantee
+ * could not be enumerated (a global role, a plan, a source without `list`,
+ * an unavailable relation): holders may be missing, so check with `decide`.
+ */
+type WhoCan = {
+  readonly permission: string;
+  readonly holders: readonly Holder[];
+  readonly complete: boolean;
+};
+//#endregion
+//#region src/core/hosted.d.ts
+/** One grant authored in PermDock Cloud; its grantee is a declared role, plan or relation. */
+type HostedGrant = {
+  readonly id: string;
+  readonly permission: string;
+  readonly effect?: "allow" | "deny";
+  readonly to: Grantee | readonly Grantee[];
+  readonly where?: Condition;
+  readonly check?: Condition;
+  readonly approval?: "human" | ApprovalRequirement;
+  readonly fields?: readonly string[];
+};
+/** PolicyDocument v1: the payload of a `permdock-policy+jwt` under the `policy` claim. */
+type PolicyDocument = {
+  readonly v: 1;
+  readonly id: string;
+  readonly fingerprint: string;
+  /** The catalog fingerprint the document was authored against. */
+  readonly catalog: string;
+  readonly issuedAt: number;
+  readonly grants: readonly HostedGrant[];
+};
+/**
+ * The channel for hosted grants. `createPermDock` reads `current()` once;
+ * the application calls `refresh()` on its own schedule, never a check.
+ */
+type PolicySource = {
+  current(): PolicyDocument | null;
+  refresh(): Promise<void>;
+};
+type HostedGrantDropReason = "not-hostable" | "unknown-permission" | "unknown-grantee" | "non-portable" | "weaker-approval" | "invalid";
+/** Reported through `on('error')` when a hosted grant is not merged; never thrown. */
+type HostedGrantDropped = {
+  readonly kind: "hosted-grant-dropped";
+  readonly document: string;
+  readonly grant: string;
+  readonly reason: HostedGrantDropReason;
+};
+declare function memoryPolicySource(document?: PolicyDocument | null): PolicySource;
+/** Validates the document envelope; per-grant checks happen at merge time. */
+declare function parsePolicyDocument(json: unknown): PolicyDocument;
+/** True for the portable subset only: no `opaque`, no `sqlFunction`, no unknown op. */
+declare function isPortableCondition(value: unknown): value is Condition;
+/**
+ * The code policy plus the hosted grants that pass every rule. Hosted
+ * allows OR with code allows and any deny still wins, so a hosted grant can
+ * never override a code deny; one that fails a rule is dropped, not thrown.
+ */
+declare function mergeHostedGrants(policy: Policy, document: PolicyDocument | null): {
+  readonly policy: Policy;
+  readonly dropped: readonly HostedGrantDropped[];
+};
+//#endregion
+//#region src/core/permdock.d.ts
+type DecideOptions = {
+  /** `true` skips schema validation for a row the server loaded itself. Otherwise `data` is validated against the resource schema first (`validate: 'boundary'`), and a failure denies with reason `validation`. */
+  readonly trusted?: boolean;
+  /** Where untrusted data came from, reported on validation errors. Defaults to `'manual'`. */
+  readonly boundary?: Boundary;
+  /** Decision clock in Unix seconds, for expiries and limits. Defaults to the current time. */
+  readonly now?: number;
+  /** The call that produced the decision, reported on the decision event. Defaults to `'decide'`. */
+  readonly source?: DecisionEvent["source"];
+  /** The adapter that made the call, reported on the decision event. */
+  readonly adapter?: string;
+  /** Per-call unauthorized handler for `assert`; runs before instance and policy handlers. */
+  readonly onDenied?: (decision: Decision) => never | void;
+  /** The field being read or written; only grants whose `fields` cover it match. */
+  readonly field?: string;
+  /** `true` attaches a `trace` to the decision: the grants evaluated, matched and skipped. Off by default and free when off. */
+  readonly explain?: boolean;
+};
+type SimulateOptions = {
+  /** Decision clock in Unix seconds for the whole batch: grant validity, membership expiry and limits are read as of this instant. Defaults to the current time. */
+  readonly now?: number;
+};
+type RowPair<T> = {
+  readonly current: T;
+  readonly next: T;
+};
+type WhereResult = {
+  readonly condition: Condition | {
+    readonly op: "or";
+    readonly conditions: readonly [];
+  };
+  readonly partial: boolean;
+  /**
+   * The subject `where()` was built for. `toWhere` reads its memberships for
+   * `memberOf` when no `subject` option is passed. Not enumerable, so it never
+   * serialises with the result.
+   */
+  readonly subject?: Subject;
+  /** The policy's scopes, for `memberOf`; not enumerable either. */
+  readonly scopes?: readonly Scope[];
+  /** The policy's resource graph, for `related`; not enumerable either. */
+  readonly resources?: ReadonlyMap<string, ResourceNode>;
+};
+type PermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly can: {
+    (permission: Permission<string, unknown, "instance">, data: unknown, options?: DecideOptions): boolean;
+    (permission: Permission<string, unknown, "collection">, data?: unknown, options?: DecideOptions): boolean;
+  };
+  readonly decide: {
+    (permission: Permission<string, unknown, "instance">, data: unknown, options?: DecideOptions): Decision;
+    (permission: Permission<string, unknown, "collection">, data?: unknown, options?: DecideOptions): Decision;
+  };
+  readonly assert: {
+    (permission: Permission<string, unknown, "instance">, data: unknown, options?: DecideOptions): Extract<Decision, {
+      readonly outcome: "granted";
+    }>;
+    (permission: Permission<string, unknown, "collection">, data?: unknown, options?: DecideOptions): Extract<Decision, {
+      readonly outcome: "granted";
+    }>;
+  };
+  /**
+   * `decide` with `explain: true`: the same decision, with a `trace` that
+   * names the grants evaluated, the allows and denies that matched (so a
+   * `denied` says which deny won) and the grants passed over. Local
+   * computation only; the trace never reaches a `DecisionSink`.
+   */
+  readonly explain: {
+    (permission: Permission<string, unknown, "instance">, data: unknown, options?: Omit<DecideOptions, "explain">): ExplainedDecision;
+    (permission: Permission<string, unknown, "collection">, data?: unknown, options?: Omit<DecideOptions, "explain">): ExplainedDecision;
+  };
+  readonly filter: <T>(permission: Permission<string, T, "instance">, rows: readonly T[], options?: DecideOptions) => T[];
+  readonly pick: <T>(permission: Permission<string, T, "instance">, row: T, options?: DecideOptions) => Partial<T>;
+  readonly where: (permission: Permission) => WhereResult;
+  readonly actions: (resource: Permission | {
+    readonly [key: string]: unknown;
+  }, data: unknown, options?: DecideOptions) => Permission[];
+  readonly simulate: {
+    (checks: readonly (readonly [Permission, unknown?])[], options?: SimulateOptions): Decision[];
+    (preview: {
+      readonly roles?: readonly (string | Role)[];
+      readonly memberships?: readonly Membership[];
+      readonly tenant?: string;
+    }): PermDock<V>;
+    (plan: ArazzoSimulateInput): ArazzoPlan;
+  };
+  readonly snapshot: (options?: {
+    readonly include?: readonly (Permission | {
+      readonly [key: string]: unknown;
+    })[];
+    readonly tenants?: "all";
+    readonly signer?: TokenSigner;
+    readonly audience?: string | readonly string[];
+  }) => Snapshot | Promise<string>;
+  readonly on: (event: "decision" | "denied" | "approval" | "auth" | "error", handler: (payload: unknown) => void) => () => void;
+  readonly tenant: (id: string) => PermDock<V>;
+  readonly team: (id: string) => PermDock<V>;
+  readonly memberships: () => readonly Membership[];
+  readonly tenants: () => readonly string[];
+  /**
+   * Roles held in a tenant (the active one by default), or only on the
+   * memberships of one `scope` (and instance `id`). Ordered by rank: a role
+   * comes before the roles its `assigns` lists.
+   */
+  readonly heldRoles: (options?: {
+    readonly tenant?: string;
+    readonly scope?: string;
+    readonly id?: string;
+  }) => readonly Role[];
+  /** The distinct `meta.audience` values of the roles held in the active tenant, in rank order. */
+  readonly audiences: () => readonly string[];
+  readonly assignableRoles: (options?: {
+    readonly tenant?: string;
+  }) => readonly Role[];
+  /**
+   * The custom-role ceiling the subject may hand out: in a tenant (empty
+   * without one), or with `scope: 'global'` for platform custom roles, the
+   * allows of assignable global roles the subject holds. A snapshot answers
+   * only the tenant form.
+   */
+  readonly assignablePermissions: (options?: {
+    readonly tenant?: string;
+    readonly scope?: "global";
+  }) => readonly Permission[];
+  /**
+   * Whether the subject may assign, revoke or transfer a role in one scope
+   * instance: `assigns`, the ceiling, `for`, `exclusiveWith`, `min`, `max`
+   * and `transferOnly`. It never writes; the application does, and generated
+   * RLS triggers re-check the holder counts at commit. A nested instance's
+   * tenant comes from a live membership the subject holds on it, or from
+   * `change.within` only with `{ trusted: true }`; otherwise `no-membership`.
+   */
+  readonly decideRoleChange: (change: RoleChange, options?: RoleChangeOptions) => RoleChangeDecision;
+  /**
+   * Loads the relation facts `permission` needs for `rows` into this
+   * instance's cache, so `can`, `decide` and `filter` answer synchronously
+   * over an async `RelationSource`. It never grants; a failed load leaves
+   * the checks denied with `relation-unavailable`.
+   */
+  readonly loadRelations: (permission: Permission, rows: readonly unknown[]) => Promise<void>;
+  /**
+   * Who holds `permission` on `resource` and how (role, relation or share),
+   * from `MembershipSource.list` and `RelationSource.related`. It lists and
+   * never grants; `complete: false` means some holders could not be listed.
+   */
+  readonly whoCan: (permission: Permission<string, unknown, "instance">, resource: unknown) => Promise<WhoCan>;
+  /**
+   * Requests a just-in-time activation of an eligible role. It never writes:
+   * a granted decision carries the elevated membership under `elevation` for
+   * the app to write, and `approval-required` comes back first when the
+   * role's `activation` sets `approval`.
+   */
+  readonly activate: (input: ActivateInput) => Decision;
+  readonly roles: V["roles"] extends RoleTree ? V["roles"] : RoleTree;
+  readonly plans: V["plans"] extends PlanTree ? V["plans"] : PlanTree;
+  readonly permissions: V["permissions"] extends Policy["permissions"] ? V["permissions"] : Policy["permissions"];
+  readonly subject: Subject;
+};
+type PermDockOptions = {
+  readonly tenant?: string;
+  /** One source, or several composed with `composeMemberships`. */
+  readonly memberships?: MembershipSource | readonly MembershipSource[];
+  readonly customRoles?: RoleSource;
+  /** Plans and seats from billing, merged into `principal.plans` for the active tenant. */
+  readonly entitlements?: EntitlementSource;
+  readonly actor?: Actor;
+  readonly delegation?: Delegation;
+  readonly sink?: DecisionSink;
+  readonly limits?: LimitStore;
+  readonly session?: string;
+  readonly expiresAt?: number;
+  /** Hosted grants; `current()` is read once, when the instance is created. */
+  readonly policies?: PolicySource;
+  /** The object graph for `through` and edge-table relations; without it they deny with `relation-unavailable`. */
+  readonly relations?: RelationSource;
+  /** Approval requirements kept as data; they add to the code's and never remove one. A throw denies. */
+  readonly approvalPolicies?: ApprovalPolicySource;
+};
+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
+//#region src/core/credential.d.ts
+type CredentialKind = "user" | "service";
+/** One permission (a key) a credential may use: on every instance, or only on `ids`. */
+type CredentialPermission = {
+  readonly permission: string;
+  readonly ids?: readonly string[];
+};
+/**
+ * Credential v1: what a verified API key stands for, never the secret. A
+ * `user` credential acts as its owner (`principal`) narrowed to
+ * `permissions`; a `service` credential is its own `service` principal
+ * holding `roles` in `tenant`, narrowed the same way.
+ */
+type Credential = {
+  readonly v: 1;
+  readonly id: string;
+  readonly kind: CredentialKind;
+  /** The owner of a `user` credential, or the id of the service principal. */
+  readonly principal: string;
+  /** Service only: the instance of the first scope its roles are held in. */
+  readonly tenant?: string;
+  /** Service only: the roles it holds in `tenant`. */
+  readonly roles?: readonly string[];
+  readonly permissions: readonly CredentialPermission[];
+  readonly createdBy: string;
+  /** Seconds since the epoch. */
+  readonly createdAt: number;
+  /** Seconds since the epoch; absent only where a credential policy allows it. */
+  readonly expiresAt?: number;
+  readonly name?: string;
+};
+type CredentialPrincipal = Principal & {
+  readonly credential: Credential;
+};
+/**
+ * What one scope instance allows for API keys created in it. Every rule only
+ * tightens; several policies must all hold.
+ */
+type CredentialPolicy = {
+  /** Longest a key may live, in seconds from `createdAt`. */
+  readonly maxTtl?: number;
+  /** Kinds that may be created. */
+  readonly kinds?: readonly CredentialKind[];
+  /** Creating a key is `approval-required`. */
+  readonly approval?: boolean;
+  /** A key may omit `expiresAt`; without it every key must expire. */
+  readonly allowNoExpiry?: boolean;
+};
+type CredentialPolicyViolation = "kind" | "no-expiry" | "ttl";
+type CredentialPermissionInput = Permission | {
+  readonly permission: Permission;
+  readonly ids: readonly string[];
+};
+type CredentialRequestBase = {
+  readonly id: string;
+  readonly permissions: readonly CredentialPermissionInput[];
+  readonly expiresAt?: number;
+  readonly name?: string;
+};
+type CredentialRequest = (CredentialRequestBase & {
+  readonly kind: "user";
+}) | (CredentialRequestBase & {
+  readonly kind: "service";
+  /** The service principal's id; defaults to the credential id. */
+  readonly principal?: string;
+  readonly tenant: string;
+  readonly roles: readonly string[];
+});
+type CredentialDecision = {
+  readonly outcome: "granted";
+  readonly credential: Credential;
+} | {
+  readonly outcome: "approval-required";
+  readonly credential: Credential;
+  /** Bound to the credential's content and its creator; pass it as `approved` to resume. */
+  readonly token: string;
+} | {
+  readonly outcome: "denied";
+  readonly denials: readonly Denial[];
+};
+type DecideCredentialOptions = {
+  /** Where the tenant's `credentials` policy comes from. Without it, only the no-expiry rule applies. */
+  readonly settings?: SettingsSource;
+  /** The `token` of an approval the application consumed for this request. */
+  readonly approved?: string;
+  /** Seconds since the epoch. */
+  readonly now?: number;
+};
+/**
+ * The first rule of `policy` the credential breaks, or `undefined`. A key
+ * without `expiresAt` passes only when some policy sets `allowNoExpiry` and
+ * none sets `maxTtl`; an empty list therefore refuses it.
+ */
+declare function credentialPolicyViolation(credential: Credential, policy: CredentialPolicy | readonly CredentialPolicy[]): CredentialPolicyViolation | undefined;
+/**
+ * Validates an untrusted credential record and returns a frozen copy with
+ * only the v1 fields, or `undefined`. Unknown fields are dropped; a wrong
+ * type in a known field, a service credential without `tenant` and `roles`,
+ * or a user credential with either, rejects the whole record.
+ */
+declare function parseCredential(input: unknown): Credential | undefined;
+/**
+ * The delegation a credential narrows its principal to: OAuth scopes for
+ * permissions on every instance, one RFC 9396 entry per id otherwise. A key
+ * the definitions no longer declare is dropped, so a credential whose every
+ * key is gone delegates nothing and every check is denied.
+ */
+declare function credentialDelegation(credential: Credential, permissions: PermissionTree): Delegation;
+/**
+ * The subject a verified credential acts as. A `user` credential is its
+ * owner, passed live as `owner` (roles and memberships as of this request),
+ * with the credential's delegation: every check is the owner's rights
+ * intersected with the key's. A `service` credential is a `service`
+ * principal whose only membership is `roles` in `tenant`. An owner whose id
+ * is not the credential's `principal`, or who is not a user, is anonymous.
+ */
+declare function credentialSubject(credential: Credential, options: {
+  readonly permissions: PermissionTree;
+  readonly owner?: Principal;
+}): Subject<CredentialPrincipal> | Subject;
+/**
+ * Decides whether the subject of `permdock` may create the credential in
+ * `request`. The creator must be a signed-in user or service that is not
+ * itself a link or a credential; a delegated creator hands out only what its
+ * delegation covers. A service key's tenant must be one the creator is a
+ * member of, its roles among the creator's `assignableRoles` there and its
+ * permissions within `assignablePermissions` there (`exceeds-creator`). The
+ * `credentials` policy of the key's tenant (a service key's own, a user
+ * key's the creator's active tenant) then applies (`credential-policy`; a
+ * settings source that throws denies with `rule: 'unavailable'`), and
+ * `approval` makes the result `approval-required` until `approved` carries
+ * its token. PermDock never stores the credential; the application does,
+ * after a `granted` result.
+ */
+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;
+  handles(permission: Permission): boolean;
+  decide(request: {
+    readonly permission: Permission;
+    readonly data?: unknown;
+    readonly subject: Subject;
+    readonly local: Decision;
+  }): Promise<Decision>;
+  /**
+   * Ids of the resources of `permission.resource` the subject may act on.
+   * `null` means the provider could not answer and every row is denied;
+   * `undefined` means it cannot list, and each row is decided on its own.
+   */
+  permitted?(request: {
+    readonly permission: Permission;
+    readonly subject: Subject;
+  }): Promise<readonly string[] | null | undefined>;
+};
+type RoleSource = {
+  rolesFor(tenant: string): CustomRole[] | Promise<CustomRole[]>;
+  assignable?(tenant: string): string[] | Promise<string[]>;
+  /** Platform custom roles (`scope: 'global'`), read once per signed-in subject. A role here with a tenant is ignored. */
+  globalRoles?(): CustomRole[] | Promise<CustomRole[]>;
+};
+/** One member of a scope instance, as `MembershipSource.list` returns it. */
+type MemberEntry = {
+  readonly principal: {
+    readonly id: string;
+  };
+  readonly membership: Membership;
+};
+type MembershipSource = {
+  membershipsFor(principal: {
+    readonly id: string;
+    readonly kind?: string;
+  }, options: {
+    readonly tenant?: string;
+  }): Membership[] | Promise<Membership[]>;
+  /** Every membership held in one scope instance, for member lists and access reviews. */
+  list?(query: {
+    readonly scope: string;
+    readonly id: string;
+  }): MemberEntry[] | Promise<MemberEntry[]>;
+  /**
+   * The principal's current authorization version, bumped on every membership
+   * change. A token whose `authzVersion` is behind it is stale for the
+   * policy's `fresh` permissions.
+   */
+  version?(principal: {
+    readonly id: string;
+  }): number | undefined | Promise<number | undefined>;
+  /**
+   * Keep the memberships the verified token carries and read this source only
+   * when the token says they were truncated (`claimsFirst`).
+   */
+  readonly claimsFirst?: boolean;
+};
+/** An object's parent chain, as `RelationSource.ancestors` returns it. */
+type RelationChain = {
+  /** Whether the object itself is restricted: nothing above it reaches it. */
+  readonly restricted?: boolean;
+  /** Ancestors nearest first, at most `depth`; a restricted one ends the walk after itself. */
+  readonly ancestors: readonly {
+    readonly id: string;
+    readonly restricted?: boolean;
+  }[];
+  /** The chain goes on above the last entry. */
+  readonly truncated?: boolean;
+};
+type HolderPeriod = {
+  /** Seconds since the epoch; before it the relation does not hold yet. */
+  readonly startsAt?: number;
+  /** Seconds since the epoch; from it on the relation no longer holds. */
+  readonly expiresAt?: number;
+};
+/** A group holding a relation on an object: whoever holds `relation` on the group's instance holds it too. */
+type RelationGroup = {
+  readonly resource: string;
+  readonly id: string;
+  readonly relation: string;
+};
+/**
+ * One holder of a relation on an object, as `RelationSource.related` returns
+ * it: a principal, or a group (an edge row whose `groups` column names one).
+ */
+type RelationHolder = HolderPeriod & ({
+  readonly principal: {
+    readonly id: string;
+  };
+} | {
+  readonly group: RelationGroup;
+});
+/**
+ * The object graph: parent chains, links and who holds a relation on an
+ * object. A source answers facts and never decides; a thrown or rejected
+ * call, or a Promise the instance has not loaded, denies with
+ * `relation-unavailable`.
+ */
+type RelationSource = {
+  /**
+   * With `through: 'parent'`, the parent chain; with a link name, the one
+   * instance that link points to (`depth` is then 1).
+   */
+  ancestors(query: {
+    readonly resource: string;
+    readonly id: string;
+    readonly through: string;
+    readonly depth: number;
+  }): RelationChain | Promise<RelationChain>;
+  related(query: {
+    readonly resource: string;
+    readonly id: string;
+    readonly relation: string;
+  }): RelationHolder[] | Promise<RelationHolder[]>;
+};
+/** Plan and seat names a principal holds in a tenant, from billing (Stripe Entitlements, a table). */
+type EntitlementSource = {
+  entitlementsFor(principal: {
+    readonly id: string;
+  }, options: {
+    readonly tenant?: string;
+  }): string[] | Promise<string[]>;
+};
+declare function memoryEntitlementSource(entries: Readonly<Record<string, readonly string[]>>): EntitlementSource;
+type JwtClaims = {
+  readonly iss?: string;
+  readonly sub?: string;
+  readonly aud?: string | readonly string[];
+  readonly exp?: number;
+  readonly nbf?: number;
+  readonly iat?: number;
+  readonly [key: string]: unknown;
+};
+type TokenFailureCause = "invalid-signature" | "expired" | "not-yet-valid" | "wrong-audience" | "wrong-issuer" | "wrong-token-type" | "alg-not-allowed" | "alg-none" | "unknown-kid" | "malformed" | "encrypted-token" | "dpop-proof-invalid" | "mtls-binding-mismatch" | "sender-constraint-required" | "token-in-query" | "invalid-claims" | "invalid-chain" | "jwks-unavailable" | "discovery-unavailable" | "discovery-mismatch";
+type VerifiedToken<TClaims extends JwtClaims = JwtClaims> = {
+  readonly ok: true;
+  readonly claims: TClaims;
+  readonly header: {
+    readonly alg: string;
+    readonly kid?: string;
+    readonly typ?: string;
+  };
+};
+type VerificationFailure = {
+  readonly ok: false;
+  readonly reason: "invalid-token";
+  readonly cause: TokenFailureCause;
+};
+type TokenVerifier<TClaims extends JwtClaims = JwtClaims> = {
+  verify(token: string, expectations: {
+    readonly typ?: string | readonly string[];
+    readonly audience?: string | readonly string[];
+    readonly issuer?: string;
+    readonly clockTolerance?: number;
+  }): Promise<VerifiedToken<TClaims> | VerificationFailure>;
+};
+type TokenSigner = {
+  sign(payload: Readonly<Record<string, unknown>>, options: {
+    readonly typ: "permdock-snapshot+jwt" | "permdock-approval+jwt" | "permdock-decisions+jwt" | "permdock-policy+jwt" | "permdock-capability+jwt";
+    readonly audience?: string | readonly string[];
+    readonly expiresAt?: number;
+  }): Promise<string>;
+  readonly kid?: string;
+  jwks?(): Promise<{
+    readonly keys: readonly JsonWebKeyLike[];
+  }>;
+};
+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 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[];
+};
+/** 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[];
+};
+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;
+};
+type SnapshotSource = {
+  get(): Promise<Snapshot | string> | Snapshot | string;
+  subscribe?(listener: () => void): () => void;
+};
+type WhereCompiler<TTarget, TOptions = unknown> = (condition: Condition, target: TTarget, options?: TOptions) => unknown;
+type LimitConsumeInput = {
+  readonly key: string;
+  readonly subjectId: string;
+  readonly count: number;
+  readonly per: string;
+  readonly now?: number;
+  /** The active tenant; a quota counts per subject and tenant. */
+  readonly tenant?: string;
+};
+type LimitRemaining = {
+  readonly remaining: number;
+};
+type LimitStore = {
+  consume(input: LimitConsumeInput): Promise<LimitRemaining> | LimitRemaining;
+  remaining(input: LimitConsumeInput): LimitRemaining | undefined;
+};
+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
+ * for bad input. Verification is the application's (or `apiKeyVerifier`'s),
+ * never core's.
+ */
+type CredentialVerifier = {
+  verify(secret: string): Credential | null | Promise<Credential | null>;
+  /**
+   * Records a successful use at `at` (Unix seconds), for a `lastUsedAt`
+   * column. Called after a key resolved and not awaited; a throw or a
+   * rejection is ignored, so it never changes the subject.
+   */
+  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. */
+  readonly credentials?: CredentialPolicy;
+};
+/**
+ * Per-tenant settings, a subject input like `RoleSource`: they tighten what
+ * a key may be and never grant. A throw denies.
+ */
+type SettingsSource = {
+  settingsFor(tenant: string): TenantSettings | undefined | Promise<TenantSettings | undefined>;
+};
+declare function memorySettings(settings: Readonly<Record<string, TenantSettings>>): SettingsSource;
+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>;
+} & { readonly [K in keyof T]?: T[K] | 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;
+};
+/**
+ * Who may approve: a subject-only grantee, a `relation()` the approver holds
+ * on the requested row (checked when the verdict is given), or `user(id)`.
+ * A list matches an approver who satisfies every item.
+ */
+type Approver = Grantee | UserApprover;
+type ApproverInput = GranteeInput | UserApprover | 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/policy.d.ts
+type ClosureContext = {
+  readonly subject: {
+    readonly principal: Principal | null;
+    readonly actor?: unknown;
+    readonly delegation?: unknown;
+    readonly context: Readonly<Record<string, unknown>>;
+  };
+  readonly actor?: unknown;
+  readonly delegation?: unknown;
+  readonly context: Readonly<Record<string, unknown>>;
+};
+type ClosureGrantFn<T = unknown> = (data: T, ctx: ClosureContext) => boolean;
+/** Who else may approve once a request has waited `after`. */
+type ApprovalEscalation = {
+  /** A duration (`'4h'`) from the request's creation. */
+  readonly after: string;
+  readonly to: Approver | readonly Approver[];
+};
+/** One group of approvers; `quorum` distinct approvers of `by` complete it. */
+type ApprovalStage = {
+  readonly by: Approver | readonly Approver[];
+  /** Absent means 1. */
+  readonly quorum?: number;
+};
+/**
+ * `'any'`: `quorum` approvers from `by`. `'all'`: every stage completes, in
+ * any order. `'sequential'`: stages complete in order; an approver signs
+ * only the first incomplete stage. An approver signs once per request.
+ */
+type ApprovalMode = "any" | "all" | "sequential";
+type ApprovalRequirement = {
+  /** Set when `mode` is `'any'` (the default); absent under `stages`. */
+  readonly by?: Approver | readonly Approver[];
+  /** Absent means `'any'`. */
+  readonly mode?: ApprovalMode;
+  /** Set when `mode` is `'all'` or `'sequential'`. */
+  readonly stages?: readonly ApprovalStage[];
+  /** `false` lets the request's principal approve it; absent means `true`. */
+  readonly distinct?: boolean;
+  /** `'resource-change'` binds the approval to the row's `version` field. */
+  readonly staleOn?: "resource-change";
+  /** Distinct approvers a request needs before it is approved under `by`; absent means 1. */
+  readonly quorum?: number;
+  /** How long a request stays open (`'30m'`); the store's default when absent, and never longer than it. */
+  readonly ttl?: string;
+  readonly escalation?: ApprovalEscalation;
+};
+type ApprovalOption = "human" | {
+  readonly by?: ApproverInput;
+  /** `'all'` or `'sequential'` with `stages`; absent means `'any'` with `by`. */
+  readonly mode?: ApprovalMode;
+  readonly stages?: readonly {
+    readonly by: ApproverInput;
+    readonly quorum?: number;
+  }[];
+  /** `false` lets the request's principal approve it; absent means `true`. */
+  readonly distinct?: boolean;
+  /**
+   * `'resource-change'`: the approval covers the row as it was when it was
+   * requested. The resource must declare `version`; once that field
+   * changes, resuming denies with `stale-approval`.
+   */
+  readonly staleOn?: "resource-change";
+  /** Distinct approvers needed (an integer of at least 1); the same approver counts once. Absent means 1. */
+  readonly quorum?: number;
+  /** How long the request stays open (`'30m'`, `'2d'`); caps the approval store's default. */
+  readonly ttl?: string;
+  /** After `after` (`'4h'`), `to` may approve as well as `by`, at any open stage; same kinds as `by`. */
+  readonly escalation?: {
+    readonly after: string;
+    readonly to: ApproverInput;
+  };
+};
+/**
+ * A quota on a grant. `hard` (the default) denies past `count`; `soft` grants
+ * with an `over-limit` obligation. `alertAt` (a fraction of `count`, above 0
+ * and at most 1) adds a `near-limit` obligation once usage reaches it.
+ */
+type GrantLimit = {
+  readonly count: number;
+  readonly per: string;
+  readonly mode?: "hard" | "soft";
+  readonly alertAt?: number;
+};
+/** How fresh the subject's authentication must be for an elevated grant. */
+type AssuranceRequirement = {
+  /** Seconds since the subject last authenticated (`assurance.authTime`). */
+  readonly maxAge?: number;
+  /** Authentication context class references, any of which satisfies it. */
+  readonly acr?: readonly string[];
+  /** Authentication methods, all of which must be present. */
+  readonly amr?: readonly string[];
+};
+/**
+ * Time-boxed role activation. A role with `activation` is never held
+ * directly: a membership lists it under `eligible`, and `permdock.activate`
+ * mints the elevated membership to write.
+ */
+type ActivationOption = {
+  /** The longest an activation may last, as a duration (`'4h'`, `'30m'`). */
+  readonly maxDuration?: string;
+  /** `'required'` denies an activation without a reason. */
+  readonly justification?: "required" | "optional";
+  /** When set, `activate` returns `approval-required` before the membership can be written. */
+  readonly approval?: ApprovalOption;
+  /** How fresh the activator's authentication must be. */
+  readonly assurance?: AssuranceRequirement;
+};
+type ActivationSpec = {
+  readonly maxDuration?: string;
+  readonly justification: "required" | "optional";
+  readonly approval?: "human" | ApprovalRequirement;
+  readonly assurance?: AssuranceRequirement;
+};
+/** What a break-glass grant demands before it overrides a deny. */
+type BreakGlassRequirements = {
+  /** Purposes of use (`context.purpose`), any of which engages break-glass. */
+  readonly purpose?: readonly string[];
+  /** `true` denies unless the caller supplies `context.reason`. */
+  readonly reason?: boolean;
+  readonly assurance?: AssuranceRequirement;
+};
+type BreakGlassOptions = {
+  /** Names of the deny grants this override lifts; every other deny still wins. */
+  readonly overrides?: readonly string[];
+  readonly requires?: BreakGlassRequirements;
+  /** The longest a break-glass session may last, as a duration. */
+  readonly maxDuration?: string;
+  /** Follow-ups the grant owes: each becomes an obligation on the decision. */
+  readonly obligations?: readonly ("notify" | "review")[];
+};
+/** The normalized break-glass spec carried on a grant. */
+type BreakGlassSpec = {
+  readonly overrides: readonly string[];
+  readonly purpose?: readonly string[];
+  readonly reason: boolean;
+  readonly assurance?: AssuranceRequirement;
+  readonly maxDuration?: string;
+  readonly obligations: readonly ("notify" | "review")[];
+};
+/** How a tenant consents to support access, and for how long. */
+type SupportConsent = {
+  readonly by: GranteeInput;
+  /** The durations a tenant owner may pick, as duration strings. */
+  readonly durations: readonly string[];
+};
+type SupportAccessOptions<S extends string = string> = {
+  /** The role a consented support membership holds. */
+  readonly role: string;
+  /** The scope the support membership sits in; defaults to `tenant`. */
+  readonly on?: S;
+  /** Every decision under the support membership denies with `actor-required` without an `act`. */
+  readonly actorRequired?: boolean;
+  readonly consent: SupportConsent;
+  /** Permissions a support session never reaches, compiled to deny grants scoped to `via: 'support'`. */
+  readonly forbid?: readonly (Permission | PermissionTree)[];
+  /** The subgroup a consented membership records under `member.group`. */
+  readonly group?: string;
+};
+type SupportSpec = {
+  readonly role: string;
+  readonly actorRequired: boolean;
+  readonly consent: {
+    readonly by: Grantee | readonly Grantee[];
+    readonly durations: readonly string[];
+  };
+  readonly group: string;
+};
+type GrantOptions<T = Record<string, unknown>> = {
+  readonly to?: GranteeInput;
+  readonly where?: WhereShorthand<T> | Condition;
+  readonly check?: WhereShorthand<T> | Condition;
+  readonly approval?: ApprovalOption;
+  readonly limit?: GrantLimit;
+  readonly reason?: string;
+  readonly fields?: readonly (keyof T & string)[];
+  /** A name a `breakGlass` override may lift; only meaningful on a deny. */
+  readonly name?: string;
+  /** 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. */
+  readonly validFrom?: string | number;
+  /** The grant stops applying at this instant (exclusive; RFC 3339 string or Unix seconds). */
+  readonly validUntil?: string | number;
+};
+/**
+ * When a grant applies, in Unix seconds. `from` is inclusive, `until`
+ * exclusive; either may be absent. Portable: `where()` drops an inactive
+ * grant at the decision clock and generated RLS compares against `now()`.
+ */
+type GrantValidity = {
+  readonly from?: number;
+  readonly until?: number;
+};
+/** The actor a policy delegation is for: an actor kind, narrowed to one id when `id` is set. */
+type DelegationTarget = {
+  readonly kind: string;
+  readonly id?: string;
+};
+/**
+ * A normalised policy delegation: holders of `from` let actors matching `to`
+ * use `permissions` (keys) on their behalf while `validity` holds, without a
+ * token saying so. Attenuation only: the principal's grants still decide.
+ */
+type PolicyDelegation = {
+  readonly from: Grantee | readonly Grantee[];
+  readonly to: DelegationTarget;
+  readonly permissions: readonly string[];
+  /** The keys of `permissions` whose `readOnlyHint` is true: all a `readOnly` actor may use. */
+  readonly readOnly: readonly string[];
+  readonly validity?: GrantValidity;
+};
+type DelegationInput = {
+  /** Who hands over: the same subject-only selectors as `approval.by` (a role, `authenticated()`, a plan, `assurance()`); not `relation()`. */
+  readonly from: GranteeInput;
+  /** Which actor may act: `actor('eve')`, an actor kind, or `{ kind, id }` for one agent. */
+  readonly to: ActorGrantee | string | DelegationTarget;
+  /** The leaves or subtrees the actor may use; a deny grant still applies. */
+  readonly permissions: readonly (Permission | PermissionTree)[];
+  readonly validFrom?: string | number;
+  readonly validUntil?: string | number;
+};
+/** A declared scope name (or the `tenant` / `team` alias), or the resource a role is held on. */
+type RoleScope<S extends string = string> = S | Permission | PermissionTree | readonly (Permission | PermissionTree)[];
+type RoleOptions<S extends string = string> = {
+  readonly on?: RoleScope<S>;
+  readonly assignable?: boolean;
+  /** Roles nobody may hold together with this one in the same scope instance. */
+  readonly exclusiveWith?: readonly string[];
+  /** Fewest holders a scope instance keeps (checked at commit); default 0. Needs a named-scope `on`. */
+  readonly min?: number;
+  /** Most holders a scope instance may have. Needs a named-scope `on`. */
+  readonly max?: number;
+  /** The holder count of a scope instance never changes: the role only moves by transfer. */
+  readonly transferOnly?: boolean;
+  /**
+   * Roles a holder may assign and revoke. Once any role declares `assigns`,
+   * a role nobody lists is assigned only by `meta.manageRoles` holders.
+   */
+  readonly assigns?: readonly string[];
+  /** Membership kinds (`via`) that may hold the role; others hold it for nothing. */
+  readonly for?: readonly string[];
+  readonly meta?: RoleMeta;
+  /** Time-boxed activation: the role becomes eligible-only and `activate` mints its membership. */
+  readonly activation?: ActivationOption;
+  /** Reserved for restricted credentials; setting it throws until it ships. */
+  readonly restricted?: never;
+};
+/** Where a grant applies: `'global'`, a declared scope name, or one resource. */
+type GrantScope = string | {
+  readonly resource: string;
+};
+type Grant = {
+  readonly permission: Permission;
+  readonly effect: "allow" | "deny";
+  readonly to: Grantee | readonly Grantee[];
+  readonly role: string | null;
+  readonly where?: Condition;
+  readonly check?: Condition;
+  readonly approval?: "human" | ApprovalRequirement;
+  readonly portable: boolean;
+  /** Set when `portable` is false only because the grant reads the relation graph. */
+  readonly graph?: true;
+  readonly closure?: ClosureGrantFn;
+  readonly limit?: GrantLimit;
+  readonly fields?: readonly string[];
+  readonly scope: GrantScope;
+  /** A name a `breakGlass` override may lift; only meaningful on a deny. */
+  readonly name?: string;
+  /** 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. */
+  readonly breakGlass?: BreakGlassSpec;
+  /** The membership kind (`via`) this grant applies under; others never match it. */
+  readonly viaOnly?: string;
+  /** Set only on a grant merged from a hosted policy document. */
+  readonly hosted?: HostedGrantRef;
+  /** When the grant applies; absent means always. */
+  readonly validity?: GrantValidity;
+};
+/** Which hosted policy document and grant a merged grant came from. */
+type HostedGrantRef = {
+  readonly document: string;
+  readonly grant: string;
+};
+type RoleBinding<S extends string = string> = {
+  readonly name: string;
+  readonly grants: readonly Grant[];
+  readonly on?: RoleScope<S>;
+  readonly assignable: boolean;
+  readonly exclusiveWith?: readonly string[];
+  readonly min?: number;
+  readonly max?: number;
+  readonly transferOnly?: boolean;
+  readonly assigns?: readonly string[];
+  readonly for?: readonly string[];
+  readonly meta?: RoleMeta;
+  /** Time-boxed activation: the role is eligible-only, and `activate` mints its membership. */
+  readonly activation?: ActivationSpec;
+  /** Support access: consent and `actorRequired` for a vendor-support membership. */
+  readonly support?: SupportSpec;
+};
+type ValidateMode = "boundary" | "always" | "never";
+/** The declared scopes, in declaration order; empty when the policy declares none. */
+type PolicyScopes = readonly Scope[];
+type PolicyVocabulary = {
+  readonly permissions: PermissionTree;
+  readonly roles?: RoleTree;
+  readonly plans?: PlanTree;
+};
+type VocabularyFromInput<Input> = Input extends PolicyVocabulary ? Input : {
+  readonly permissions: Input & PermissionTree;
+  readonly roles?: RoleTree;
+  readonly plans?: PlanTree;
+};
+type Policy<TUser = unknown, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly permissions: V["permissions"];
+  readonly roles: readonly RoleBinding[];
+  readonly rolesByName: ReadonlyMap<string, RoleBinding>;
+  readonly grants: readonly Grant[];
+  readonly vocabulary: V;
+  readonly scopes: PolicyScopes;
+  principal(user: TUser): TPrincipal | null;
+  subject(user: TUser): TPrincipal | null;
+  context?(user: TUser): Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
+  readonly validate: ValidateMode;
+  readonly onDenied?: (decision: unknown) => never | void;
+  readonly fingerprint: string;
+  readonly resources: ReadonlyMap<string, ResourceNode>;
+  readonly providers?: readonly DecisionProvider[];
+  /** Permission keys a hosted policy document may grant or deny; empty by default. */
+  readonly hostable: readonly string[];
+  /** Permission keys that deny with `stale-credentials` when the subject's token is behind the source. */
+  readonly fresh?: readonly string[];
+  /** Policy delegations in declaration order; absent or empty when the policy declares none. */
+  readonly delegations?: readonly PolicyDelegation[];
+  readonly index: PolicyIndex;
+};
+/** Lookups built once per policy, so a decision does not rescan every role and grant. */
+type PolicyIndex = {
+  readonly declaredRoles: ReadonlySet<string>;
+  readonly supports: readonly SupportSpec[];
+  /** 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;
+type DefinePolicyOptions<TUser, TPrincipal extends Principal, S extends PolicyScopesInput = PolicyScopesInput> = {
+  readonly roles?: readonly RoleBinding<ScopeNames<S>>[];
+  readonly grants?: readonly (Omit<Grant, "role" | "scope"> | readonly Omit<Grant, "role" | "scope">[] | Grant)[];
+  /**
+   * Named scopes in order, each with the row field holding its id and an
+   * optional parent (`within`, an earlier scope). `tenant` and `team` alias
+   * the first and second scope.
+   */
+  readonly scopes?: S;
+  readonly principal?: (user: TUser) => TPrincipal | null;
+  readonly subject?: (user: TUser) => TPrincipal | null;
+  readonly context?: (user: TUser) => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
+  readonly validate?: ValidateMode;
+  readonly onDenied?: (decision: unknown) => never | void;
+  readonly providers?: readonly DecisionProvider[];
+  /**
+   * Leaves or subtrees a hosted policy document (`PolicySource`) may touch.
+   * The default is none, so a policy without it ignores every hosted grant.
+   */
+  readonly hostable?: readonly (Permission | PermissionTree)[];
+  /**
+   * Sensitive permissions that need an up-to-date token: when the subject's
+   * memberships come from a token behind the `MembershipSource` version, they
+   * deny with `stale-credentials`.
+   */
+  readonly fresh?: readonly (Permission | PermissionTree)[];
+  /**
+   * Standing delegations: holders of `from` let actors matching `to` use
+   * `permissions` for them without a token saying so. A token delegation on
+   * the call still applies as well; both must cover.
+   */
+  readonly delegations?: readonly DelegationInput[];
+};
+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;
+  readonly roles: readonly string[];
+};
+type SeparationConflict = {
+  readonly principal: string;
+  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;
+  readonly actor?: Actor;
+  readonly delegation?: Delegation;
+  readonly context: Readonly<Record<string, unknown>>;
+  readonly session?: string;
+  readonly expiresAt?: number;
+};
+//#endregion
+export { DecisionSink as $, relation as $n, RowPair as $t, RoleScope as A, memoryApprovalPolicies as An, isConditionRef as Ar, memoryEntitlementSource as At, normalizeAssurance as B, Obligation as Bn, CredentialPolicy as Bt, Policy as C, ArazzoPlan as Cn, RelatedCondition as Cr, TenantSettings as Ct, PrincipalOf as D, simulateArazzo as Dn, hasConditionOp as Dr, VerificationFailure as Dt, PolicyVocabulary as E, arazzoFindings as En, SqlFunctionCondition as Er, TokenVerifier as Et, ValidateMode as F, DeniedDecision as Fn, Credential as Ft, UserApprover as G, Grantee as Gn, credentialDelegation as Gt, separationConflicts as H, Trace as Hn, CredentialPrincipal as Ht, allow as I, ExplainedDecision as In, CredentialDecision as It, AuthEvent as J, actor as Jn, decideCredential as Jt, user as K, GranteeInput as Kn, credentialPolicyViolation as Kt, definePolicy as L, GrantedDecision as Ln, CredentialKind as Lt, SubjectOf as M, Decision as Mn, memorySettings as Mt, SupportAccessOptions as N, Denial as Nn, WireDecision as Nt, RoleBinding as O, ApprovalPolicy as On, isCondition as Or, VerifiedToken as Ot, SupportConsent as P, DenialReason as Pn, WireDenial as Pt, DecisionProvider as Q, plan as Qn, PermDockOptions as Qt, deny as R, LimitDetail as Rn, CredentialPermission as Rt, MembershipFixture as S, ArazzoFinding as Sn, OpaqueCondition as Sr, SubjectResolver as St, PolicyScopes as T, ArazzoStepResult as Tn, SqlFunctionArg as Tr, TokenSigner as Tt, Approver as U, TraceSkip as Un, CredentialRequest as Ut, role as V, Quota as Vn, CredentialPolicyViolation as Vt, ApproverInput as W, TraceSkipReason as Wn, DecideCredentialOptions as Wt, CredentialVerifier as X, assurance as Xn, DecideOptions as Xt, CredentialEvent as Y, anyone as Yn, parseCredential as Yt, DecisionEvent as Z, authenticated as Zn, PermDock as Zt, GrantLimit as _, RoleChangeOptions as _n, Condition as _r, SnapshotAssignable as _t, ApprovalRequirement as a, HostedGrantDropped as an, Assurance as ar, LimitStore as at, GrantValidity as b, breakGlass as bn, MemberOfCondition as br, SnapshotScope as bt, BreakGlassOptions as c, isPortableCondition as cn, CustomRole as cr, MembershipSource as ct, ClosureContext as d, parsePolicyDocument as dn, GnapAccess as dr, RelationHolder as dt, SimulateOptions as en, PolicyScopesInput as er, DirectoryEvent as et, ClosureGrantFn as f, Holder as fn, JsonWebKeyLike as fr, RelationSource as ft, GrantCondition as g, RoleChangeDecision as gn, VerifiedClaims as gr, Snapshot as gt, Grant as h, RoleChange as hn, Subject as hr, SinkEvent as ht, ApprovalOption as i, HostedGrantDropReason as in, Actor as ir, LimitRemaining as it, SeparationConflict as j, ApprovalRequiredDecision as jn, isSqlFunctionField as jr, memoryRoleSource as jt, RoleOptions as k, ApprovalPolicySource as kn, isConditionDate as kr, WhereCompiler as kt, BreakGlassRequirements as l, memoryPolicySource as ln, CustomRoleGrant as lr, RelationChain as lt, DelegationTarget as m, WhoCan as mn, Principal as mr, SettingsSource as mt, ApprovalEscalation as n, createPermDock as nn, ScopeDeclaration as nr, JwtClaims as nt, ApprovalStage as o, PolicyDocument as on, AuthorizationDetail as or, MemberEntry as ot, DelegationInput as p, HoldingVia as pn, Membership as pr, RoleSource as pt, AccessEvent as q, RelationGrantee as qn, credentialSubject as qt, ApprovalMode as r, HostedGrant as rn, ScopeNames as rr, LimitConsumeInput as rt, AssuranceRequirement as s, PolicySource as sn, Binding as sr, MembershipEvent as st, ActivationOption as t, WhereResult as tn, Scope as tr, EntitlementSource as tt, BreakGlassSpec as u, mergeHostedGrants as un, Delegation as ur, RelationGroup as ut, GrantOptions as v, RoleChangeTarget as vn, ConditionRef as vr, SnapshotGrant as vt, PolicyDelegation as w, ArazzoSimulateInput as wn, RelatedHop as wr, TokenFailureCause as wt, HostedGrantRef as x, supportAccess as xn, MemberOfParent as xr, SnapshotSource as xt, GrantScope as y, ActivateInput as yn, ConditionValue as yr, SnapshotNotEntitled as yt, normalizeApproval as z, MatchedGrant as zn, CredentialPermissionInput as zt };