permdock 0.4.0 → 0.5.0

package/dist/{index-UdVQgq48.d.ts → index-DOVf7RJv.d.ts}

@@ -1,6 +1,12 @@
-import { Br as SqlFunctionArg, Dr as Membership, E as Policy, G as EntitlementSource, I as SeparationConflict, Ir as OpaqueCondition, Mr as ConditionRef, N as RoleBinding, O as PolicyDelegation, Or as Principal, P as RoleOptions, Sr as CustomRole, V as VocabularyFromInput, Vr as SqlFunctionCondition, Y as LimitStore, Z as MembershipSource, _ as GrantCondition, an as Snapshot, at as SnapshotSource, g as Grant, i as ApprovalOption, in as LocalSnapshotManifest, it as SettingsSource, j as PolicyVocabulary, jt as PermDock, kr as Subject, mn as PolicyScopesInput, nt as RoleSource, p as DefinePolicyOptions, s as AssuranceRequirement, sr as DenialReason, st as TenantSettings, tt as RelationSource, vn as AccessEvent, w as MembershipFixture, wr as Delegation, xn as DecisionEvent } from "./policy-types-sp9P1iIV.js";
-import { C as ResourceRelationInput, T as ResourceXTree, b as ResourceOptions, d as Permission, f as PermissionKind, h as ResourceInit, i as DefinePermissionsOptions, n as ActionMeta, p as PermissionTree, t as ActionList, u as InferPermissionTree, v as ResourceMeta, w as ResourceRestricted, x as ResourceParent, y as ResourceNode } from "./permission-types-Dg39z9Kv.js";
-import { r as Role } from "./vocabulary-hhEFLFoL.js";
+import { $n as Delegation, Bt as LocalSnapshotManifest, C as MembershipFixture, D as PolicyDelegation, I as SeparationConflict, In as DenialReason, J as EntitlementSource, Kt as AccessEvent, Lt as InstanceHandle, N as RoleBinding, Nn as Decision, P as RoleOptions, Pn as Denial, Qt as DeliveryEvent, R as SupportAccessOptions, Rt as Instant, T as Policy, V as VocabularyFromInput, Vt as Snapshot, W as CustomRoleSource, Xt as DecisionEvent, Y as JwtClaims, Zn as CustomRole, at as SettingsSource, c as BreakGlassOptions, ct as TenantSettings, et as MembershipSource, g as GrantCondition, h as Grant, i as ApprovalOption, ir as Subject, it as RelationSource, j as PolicyVocabulary, k as PolicyOptions, mr as OpaqueCondition, nr as Membership, nt as RelationGroup, ot as SnapshotSource, rn as SinkEvent, rr as Principal, s as AssuranceRequirement, sn as PolicyScopesInput, ur as ConditionRef, ut as TokenSigner, vr as SqlFunctionArg, yr as SqlFunctionCondition } from "./policy-types-DzwivBgR.js";
+import { C as InferPermissionTree, D as PermissionsOptions, E as PermissionTree, F as ResourceParent, L as ResourceRelationInput, M as ResourceMeta, N as ResourceNode, P as ResourceOptions, R as ResourceRestricted, T as PermissionKind, g as ActionMeta, h as ActionList, k as ResourceInit, r as Role, w as Permission, z as ResourceXTree } from "./vocabulary-D6lPdb4Z.js";
+import { i as PermDockOptions, r as PermDock } from "./permdock-D7eeLJER.js";
+import { a as PolicyDocument } from "./hosted-DBDX0M-P.js";
+import { m as ApprovalStore } from "./types-CCpc2Dcv.js";
+import { t as InstanceOptions } from "./instance-options-Omfd793B.js";
+import { n as PermDockWrap } from "./wrap-Bd1Tejur.js";
+import { t as JsonSchemaNode } from "./json-schema-CN_iLFH2.js";
+import { i as CatalogEventData, s as CloudEvent } from "./sink-Bj_lDUDq.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/conditions/refs.d.ts
 type KnownRefField = "id" | "issuer" | "kind" | "tenant" | "team" | "roles" | "plans" | "memberships" | "assurance" | "binding" | "session";
@@ -74,9 +80,24 @@ declare function emptySnapshot(): Snapshot;
 declare function requiresApproval(approval: Grant["approval"] | undefined): boolean;
 //#endregion
 //#region src/core/policy.d.ts
-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>>;
+declare function definePolicy<TUser, TPrincipal extends Principal, const Input extends PermissionTree | PolicyVocabulary, const S extends PolicyScopesInput = PolicyScopesInput>(permissions: Input, options: PolicyOptions<TUser, TPrincipal, S>): Policy<TUser, TPrincipal, VocabularyFromInput<Input>>;
 declare function separationConflicts(policy: Policy, memberships: readonly MembershipFixture[]): readonly SeparationConflict[];
 //#endregion
+//#region src/core/permission-registry.d.ts
+declare function getResource<RX = never>(tree: PermissionTree & ResourceXTree<RX>, name: string): ([RX] extends [never] ? ResourceNode : ResourceNode & {
+  readonly meta?: ResourceMeta<Readonly<RX>>;
+}) | undefined;
+declare function listPermissions(tree: PermissionTree | Permission): readonly Permission[];
+declare function findPermission(tree: PermissionTree, keyOrScope: string): Permission | undefined;
+/**
+ * A permission leaf: string `key`, `scope`, `resource` and `action` plus an
+ * object `meta`. `kind` is non-enumerable and does not survive
+ * `JSON.stringify`, so a leaf that crossed a serialisation boundary passes
+ * without it; when present it must be `instance` or `collection`.
+ */
+declare function isPermission(value: unknown): value is Permission;
+declare function mergePermissions<const Trees extends readonly PermissionTree[]>(...trees: Trees): PermissionTree;
+//#endregion
 //#region src/conditions/opaque.d.ts
 declare function opaque(input: {
   readonly sql: string;
@@ -91,14 +112,18 @@ declare function sqlFunction(name: string, options: {
 //#endregion
 //#region src/core/memory-sources.d.ts
 declare function memoryEntitlementSource(entries: Readonly<Record<string, readonly string[]>>): EntitlementSource;
-declare function memorySettings(settings: Readonly<Record<string, TenantSettings>>): SettingsSource;
+declare function memorySettingsSource(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;
+declare function memoryCustomRoleSource(customRoles: readonly CustomRole[]): CustomRoleSource;
+//#endregion
+//#region src/core/approval-state.d.ts
+/** The denial detail when an `ApprovalPolicySource` threw or returned an invalid entry. */
+declare const APPROVAL_POLICY_UNAVAILABLE = "approval-policy-unavailable";
 //#endregion
 //#region src/core/memberships.d.ts
 /**
@@ -160,19 +185,13 @@ type StripeEntitlementsClient = {
  * tenant to its customer id; no tenant or no customer means no entitlements.
  * Pass it as `entitlements`, and grant with `plan('<lookup_key>')`.
  */
-declare function fromStripeEntitlements(options: {
+declare function stripeEntitlementSource(options: {
   readonly stripe: StripeEntitlementsClient;
   readonly customer: (tenant: string, principal: {
     readonly id: string;
   }) => string | undefined | PromiseLike<string | undefined>;
 }): EntitlementSource;
 //#endregion
-//#region src/core/limits.d.ts
-declare function memoryLimitStore(): LimitStore & {
-  /** Live counters, for tests and diagnostics. */
-  size(): number;
-};
-//#endregion
 //#region src/core/memory-relations.d.ts
 type MemoryEdge = {
   /** The object's id. */
@@ -181,7 +200,7 @@ type MemoryEdge = {
   readonly startsAt?: number;
   readonly expiresAt?: number;
 };
-type MemoryRelationsData = {
+type MemoryRelationSourceData = {
   /** Rows per resource: parent pointers, links, restricted flags and relation columns are read from them. */
   readonly rows?: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
   /** Edge-table rows per resource and relation. */
@@ -197,7 +216,129 @@ type MemoryRelationsData = {
  * An in-process `RelationSource` over plain rows and edges, read against the
  * resource definitions in `permissions`. For tests, fixtures and small apps.
  */
-declare function memoryRelations(permissions: PermissionTree, data?: MemoryRelationsData): RelationSource;
+declare function memoryRelationSource(permissions: PermissionTree, data?: MemoryRelationSourceData): RelationSource;
+//#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;
+};
+/**
+ * Who holds `permission` on `resource` for the instance's policy 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. An instance built from a
+ * snapshot answers an empty, incomplete list.
+ */
+declare function whoCan(permdock: InstanceHandle, permission: Permission<string, unknown, "instance">, resource: unknown): Promise<WhoCan>;
+//#endregion
+//#region src/core/policy-sign.d.ts
+type SignPolicyDocumentOptions = {
+  /** `aud`: the environment URL `cloud().policies` checks it against. */
+  readonly audience: string | readonly string[];
+  /** `exp`, a NumericDate; the signer's default (one hour after `iat`) when absent. */
+  readonly expiresAt?: number;
+};
+/**
+ * Signs `document` as a `vnd.permdock.policy+jwt`: the `policy` claim holds
+ * every field but `id` and `issuedAt`, which become `jti` and `iat`, so
+ * `policyDocumentFromClaims` reads it back. `iss` is the signer's own.
+ */
+declare function signPolicyDocument(document: PolicyDocument, signer: TokenSigner, options: SignPolicyDocumentOptions): Promise<string>;
+//#endregion
+//#region src/core/snapshot-sign.d.ts
+type SignSnapshotOptions = {
+  /** `aud`; a signer with no default audience refuses to sign without one. */
+  readonly audience?: string | readonly string[];
+};
+/**
+ * Signs `snapshot` as a `vnd.permdock.snapshot+jwt`. `issuedAt` and
+ * `expiresAt` become `iat` and `exp` and leave the `snapshot` claim, so the
+ * registered claims are the only times a verifier reads.
+ */
+declare function signSnapshot(snapshot: Snapshot, signer: TokenSigner, options?: SignSnapshotOptions): Promise<string>;
+/**
+ * The snapshot a verified `vnd.permdock.snapshot+jwt` carries, parsed as
+ * `parseSnapshot` parses it, with `issuedAt` and `expiresAt` from `iat` and
+ * `exp`. `null` when the claim is missing or not a valid snapshot.
+ */
+declare function snapshotFromClaims(claims: JwtClaims): Snapshot | null;
+//#endregion
+//#region src/core/delivery-event.d.ts
+declare function deliveryEvent(input: Omit<DeliveryEvent, "type" | "at"> & {
+  /** An RFC 3339 instant; defaults to now. */
+  readonly at?: string;
+}): DeliveryEvent;
+//#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[];
+/**
+ * Walks an Arazzo workflow against `permdock`: each step's operation is
+ * decided as `permdock.simulate` would, and a server instance emits one
+ * simulate event for the whole plan. Works on an instance built from a
+ * snapshot too.
+ */
+declare function simulateArazzo(permdock: PermDock, input: ArazzoSimulateInput): ArazzoPlan;
 //#endregion
 //#region src/core/local-manifest.d.ts
 /**
@@ -207,6 +348,71 @@ declare function memoryRelations(permissions: PermissionTree, data?: MemoryRelat
  */
 declare function localSnapshotManifest(policy: Policy): LocalSnapshotManifest;
 //#endregion
+//#region src/core/app.d.ts
+/**
+ * How strict `defineApp` is about the services the policy needs. `dev`
+ * fills in in-process defaults (a memory approval store and a memory limit
+ * store) so a new app runs before any infrastructure exists. `prod` throws at startup when a grant needs a
+ * service the app does not configure, instead of denying at run time.
+ */
+type AppProfile = "dev" | "prod";
+/**
+ * Everything an app wires once and every adapter reads: the data sources,
+ * the opt-in features and the services. An adapter's own options win over
+ * these, key by key.
+ */
+type AppOptions = InstanceOptions & Pick<PermDockOptions, "settings"> & {
+  /** Where approval requests open and resume, for every adapter. */
+  readonly store?: ApprovalStore;
+  readonly profile?: AppProfile;
+};
+//#endregion
+//#region src/app/define-app.d.ts
+/**
+ * Binds the app's sources, features and services to `policy`. The result
+ * is a policy: pass it wherever a policy goes (`createPermDock`, every
+ * adapter, the CLI) and each picks up the app definition, with its own
+ * options taking precedence. The profile defaults to `prod`.
+ */
+declare function defineApp<TUser, TPrincipal extends Principal, V extends PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options?: AppOptions): Policy<TUser, TPrincipal, V>;
+//#endregion
+//#region src/core/shadow.d.ts
+/** The application's existing check, asked the same question PermDock is. */
+type LegacyCheck = (input: {
+  readonly permission: Permission;
+  readonly data: unknown;
+  readonly subject: Subject;
+}) => boolean;
+/** One check where the legacy system and PermDock disagree. */
+type ShadowMismatch = {
+  readonly permission: string;
+  readonly principal: string | null;
+  /** What the legacy check answered; `false` when it threw. */
+  readonly legacy: boolean;
+  readonly permdock: Decision["outcome"];
+  /** `true` when PermDock's answer was the one returned. */
+  readonly enforced: boolean;
+};
+type ShadowOptions = {
+  readonly legacy: LegacyCheck;
+  /**
+   * Permissions PermDock decides; every other check returns the legacy
+   * answer. `"all"` once every mismatch is resolved; default none.
+   */
+  readonly enforce?: readonly Permission[] | "all";
+  /** Called for each disagreement; a throw here is ignored. */
+  readonly onMismatch?: (mismatch: ShadowMismatch) => void;
+};
+/**
+ * Runs PermDock beside the application's existing checks while adopting
+ * it. Each `can`, `decide`, `decideEach`, `filter` and `assert` asks both;
+ * the legacy answer is returned unless the permission is in `enforce`, and
+ * every disagreement reaches `onMismatch`. Promote permissions one by one
+ * as their mismatches are resolved, then remove the wrap. Pass it as an
+ * adapter's `wrap` option, or call it on a core instance.
+ */
+declare function shadowMode(options: ShadowOptions): PermDockWrap;
+//#endregion
 //#region src/core/may-access.d.ts
 /**
  * An optimistic routing hint for a proxy or middleware, never a decision.
@@ -219,37 +425,11 @@ declare function mayAccess(policy: Policy, user: unknown, permission: Permission
   readonly tenant?: string;
 }): boolean;
 //#endregion
-//#region src/core/may-use.d.ts
-/**
- * Whether `permission` could be granted to this instance's subject for some
- * row: the grants its snapshot carries for the active tenant, minus an
- * unconditional deny, within its delegation. A listing hint for tools and
- * skills, never a decision; the call itself is decided in full.
- */
-declare function mayUse(permdock: PermDock, permission: Permission): boolean;
-type PermittedIdsOptions = {
-  readonly within?: string;
-  readonly conditioned?: boolean;
-};
-/**
- * The instances of `scope` in which the subject holds `permission`, from its
- * live memberships of exactly that scope, within its delegation: by default
- * those with an allow that carries no row condition (`where`, `check`, a
- * validity window or a non-portable test; a `fields` limit is not a row
- * condition), minus the instances any deny of the permission reaches. The
- * in-process mirror of the SQL `permitted_<scope>_ids_by_permission`. With
- * `conditioned: true` it also lists the instances where a conditioned allow
- * applies, minus only unconditional denies, as
- * `permitted_<scope>_ids_by_permission(p_permission, true)` does. A listing,
- * never a decision: a row's own check still runs `can`.
- */
-declare function permittedIds(permdock: PermDock, permission: Permission, scope: string, options?: PermittedIdsOptions): readonly string[];
-//#endregion
 //#region src/core/custom-role-source.d.ts
 /** Reads custom roles from the application's store, as `customRoleSource` takes them. */
 type CustomRoleReader = {
   /** Every custom role of `tenant`, whether or not anyone in the request holds it. */
-  rolesOf(tenant: string): CustomRole[] | Promise<CustomRole[]>;
+  rolesFor(tenant: string): CustomRole[] | Promise<CustomRole[]>;
   assignable?(tenant: string): string[] | Promise<string[]>;
   /** Platform custom roles (`scope: 'global'`). */
   globalRoles?(): CustomRole[] | Promise<CustomRole[]>;
@@ -263,12 +443,12 @@ type CustomRoleSourceOptions = {
   readonly policy: Policy;
 };
 /**
- * A `RoleSource` over a reader that returns every custom role of a tenant.
+ * A `CustomRoleSource` over a reader that returns every custom role of a tenant.
  * It keeps only the roles of the requested tenant. With `read: 'held'` it
  * skips a tenant's read, and `globalRoles`, when the subject holds only
  * declared roles there.
  */
-declare function customRoleSource(reader: CustomRoleReader, options?: CustomRoleSourceOptions): RoleSource;
+declare function customRoleSource(reader: CustomRoleReader, options?: CustomRoleSourceOptions): CustomRoleSource;
 //#endregion
 //#region src/core/instance-snapshot.d.ts
 type SnapshotInclude = readonly (Permission | {
@@ -283,14 +463,14 @@ type SnapshotForOptions = {
   readonly memberships?: readonly Membership[];
   /** The tenant's custom roles, typically from a shared, tagged cache. */
   readonly customRoles?: readonly CustomRole[];
-  /** Per tenant, the role names `RoleSource.assignable` returns; narrows `assignable`. */
+  /** Per tenant, the role names `CustomRoleSource.assignable` returns; narrows `assignable`. */
   readonly assignable?: Readonly<Record<string, readonly string[]>>;
   /** Plans of the active tenant; replaces `principal.plans`. */
   readonly plans?: readonly string[];
   readonly include?: SnapshotInclude;
   readonly tenants?: "all";
-  /** Epoch seconds for `issuedAt` and membership expiry. Defaults to the clock. */
-  readonly now?: number;
+  /** The instant for `issuedAt` and membership expiry. Defaults to the clock. */
+  readonly now?: Instant;
 };
 /**
  * Builds the serializable access snapshot for a subject without a request,
@@ -301,22 +481,7 @@ type SnapshotForOptions = {
 declare function snapshotFor<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, user: TUser | Subject | null, options?: SnapshotForOptions): Snapshot;
 //#endregion
 //#region src/core/permissions.d.ts
-declare function definePermissions<const Input, PX = never, RX = never>(input: Input, options?: DefinePermissionsOptions<PX, RX>): InferPermissionTree<Input, "", PX> & ResourceXTree<RX>;
-//#endregion
-//#region src/core/permission-registry.d.ts
-declare function getResource<RX = never>(tree: PermissionTree & ResourceXTree<RX>, name: string): ([RX] extends [never] ? ResourceNode : ResourceNode & {
-  readonly meta?: ResourceMeta<Readonly<RX>>;
-}) | undefined;
-declare function listPermissions(tree: PermissionTree | Permission): readonly Permission[];
-declare function findPermission(tree: PermissionTree, keyOrScope: string): Permission | undefined;
-/**
- * A permission leaf: string `key`, `scope`, `resource` and `action` plus an
- * object `meta`. `kind` is non-enumerable and does not survive
- * `JSON.stringify`, so a leaf that crossed a serialisation boundary passes
- * without it; when present it must be `instance` or `collection`.
- */
-declare function isPermission(value: unknown): value is Permission;
-declare function mergePermissions<const Trees extends readonly PermissionTree[]>(...trees: Trees): PermissionTree;
+declare function definePermissions<const Input, PX = never, RX = never>(input: Input, options?: PermissionsOptions<PX, RX>): InferPermissionTree<Input, "", PX> & ResourceXTree<RX>;
 //#endregion
 //#region src/core/permission-leaf.d.ts
 /**
@@ -405,13 +570,193 @@ declare function deny<T, K extends PermissionKind = PermissionKind>(permission:
 //#region src/core/approval-normalize.d.ts
 declare function normalizeApproval(approval: ApprovalOption | undefined, permission?: string): Grant["approval"];
 //#endregion
-//#region src/core/duration.d.ts
-declare function parseDuration(input: unknown): number | undefined;
+//#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>>;
+  /** Seconds the elevation lasts; capped at the role's `maxDuration`. */
+  readonly duration?: number;
+  readonly reason?: string;
+};
+/**
+ * Requests a just-in-time role activation. It never writes: a granted
+ * decision carries the elevated membership under `elevation` for the app to
+ * write. `approval-required` comes back first when the role's `activation`
+ * sets `approval`. Fail-closed: an unknown role, an ineligible subject, a
+ * missing justification or stale authentication all deny.
+ */
+/**
+ * Requests a just-in-time activation of an eligible role for the subject of
+ * `permdock`. 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`. An instance built from a snapshot denies with `unsupported`.
+ */
+declare function activate(permdock: InstanceHandle, input: ActivateInput): Decision;
+//#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 RoleChangeBase = {
+  readonly kind: "assign" | "revoke" | "transfer";
+  readonly role: string | Role;
+  /** 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;
+};
+/**
+ * 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;
+};
+/**
+ * The one rule check behind `permdock.decideRoleChange`. The actor is always
+ * the instance's own principal; nothing in `change` can stand in for it.
+ */
+/**
+ * Whether the subject of `permdock` 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`. An instance built from a snapshot denies with
+ * `unsupported`.
+ */
+declare function decideRoleChange(permdock: InstanceHandle, change: RoleChange, options?: RoleChangeOptions): RoleChangeDecision;
+//#endregion
+//#region src/core/parse-sink-events.d.ts
+/**
+ * Validates one untrusted sink event against its family's schema and returns
+ * a frozen copy, or `null` for anything else. Never throws.
+ */
+declare function parseSinkEvent(value: unknown): SinkEvent | null;
+/**
+ * Validates an untrusted list of sink events, such as a request body a sink
+ * receiver read. Each event that fails its schema is dropped, and a value
+ * that is not an array yields no events. Never throws.
+ */
+declare function parseSinkEvents(value: unknown): readonly SinkEvent[];
+/** Validates the data of a `com.permdock.catalog.*` CloudEvent; `null` when it does not match. */
+declare function parseCatalogEventData(value: unknown): CatalogEventData | null;
+/**
+ * Validates one CloudEvent against the closed type list, its `dataschema` and
+ * its data shape; `null` for anything else, a reserved type included. Never
+ * throws.
+ */
+declare function parseCloudEvent(value: unknown): CloudEvent | null;
+/**
+ * Validates a CloudEvents JSON batch (`application/cloudevents-batch+json`):
+ * `null` unless the value is an array and every event in it is valid.
+ */
+declare function parseCloudEventBatch(value: unknown): readonly CloudEvent[] | null;
+//#endregion
+//#region src/core/event-schemas.d.ts
+/** The URL each event family's schema is published at, and its CloudEvents `dataschema`. */
+declare const EVENT_SCHEMA_IDS: {
+  readonly decision: "https://permdock.com/schemas/decision-event-v1.json";
+  readonly directory: "https://permdock.com/schemas/directory-event-v1.json";
+  readonly membership: "https://permdock.com/schemas/membership-event-v1.json";
+  readonly credential: "https://permdock.com/schemas/credential-event-v1.json";
+  readonly access: "https://permdock.com/schemas/access-event-v1.json";
+  readonly automation: "https://permdock.com/schemas/automation-event-v1.json";
+  readonly catalog: "https://permdock.com/schemas/catalog-event-v1.json";
+  readonly delivery: "https://permdock.com/schemas/delivery-event-v1.json";
+};
+declare const DECISION_EVENT_SCHEMA: JsonSchemaNode;
+declare const DIRECTORY_EVENT_SCHEMA: JsonSchemaNode;
+declare const MEMBERSHIP_EVENT_SCHEMA: JsonSchemaNode;
+declare const CREDENTIAL_EVENT_SCHEMA: JsonSchemaNode;
+declare const ACCESS_EVENT_SCHEMA: JsonSchemaNode;
+declare const AUTOMATION_EVENT_SCHEMA: JsonSchemaNode;
+declare const CATALOG_EVENT_SCHEMA: JsonSchemaNode;
+declare const DELIVERY_EVENT_SCHEMA: JsonSchemaNode;
+/** Every sink event family's schema, keyed by the event's `type`. */
+declare const SINK_EVENT_SCHEMAS: {
+  readonly decision: JsonSchemaNode;
+  readonly directory: JsonSchemaNode;
+  readonly membership: JsonSchemaNode;
+  readonly credential: JsonSchemaNode;
+  readonly access: JsonSchemaNode;
+  readonly automation: JsonSchemaNode;
+  readonly delivery: JsonSchemaNode;
+};
 //#endregion
 //#region src/core/ocsf.d.ts
 /** The OCSF schema version `toOcsf` emits. */
-declare const OCSF_VERSION = "1.3.0";
-/** An OCSF Authorize Session (class 3003, category Identity and Access Management) event. */
+declare const OCSF_VERSION = "1.9.0";
+/**
+ * An OCSF Authorize Session (class 3003, category Identity and Access Management) event.
+ * API Activity (6003) would fit a per-request decision, but it requires `api` and
+ * `src_endpoint`, which a decision event does not carry.
+ */
 type OcsfAuthorizeSession = {
   readonly class_uid: 3003;
   readonly category_uid: 3;
@@ -420,7 +765,8 @@ type OcsfAuthorizeSession = {
   readonly severity_id: 1 | 4;
   readonly time: number;
   readonly status_id: 0 | 1 | 2 | 99;
-  readonly status: "Unknown" | "Success" | "Failure" | "Other";
+  /** OCSF requires a source label for status 99: `Approval Required`. */
+  readonly status: "Unknown" | "Success" | "Failure" | "Approval Required";
   readonly status_detail?: string;
   readonly message: string;
   readonly privileges: readonly string[];
@@ -452,7 +798,7 @@ type OcsfAuthorizeSession = {
     readonly outcome: DecisionEvent["outcome"];
     readonly scope: string;
     readonly resource: DecisionEvent["resource"];
-    readonly source: DecisionEvent["source"];
+    readonly call: DecisionEvent["call"];
     readonly phase?: DecisionEvent["phase"];
     readonly role?: string | null;
     /** The matched grant's declared `name`. */
@@ -466,19 +812,23 @@ type OcsfAuthorizeSession = {
     readonly reason?: string;
   };
 };
-/** Projects a decision or approval event onto OCSF Authorize Session; the event itself is unchanged. */
-declare function toOcsf(event: DecisionEvent): OcsfAuthorizeSession;
 /**
- * An OCSF Account Change (class 3001) event for a support-access lifecycle
+ * Projects a decision or approval event onto OCSF Authorize Session; the event itself is unchanged.
+ * An event whose `at` does not parse has no OCSF `time` and projects to `undefined`.
+ */
+declare function toOcsf(event: DecisionEvent): OcsfAuthorizeSession | undefined;
+/**
+ * An OCSF User Management (class 3007) event for a support-access lifecycle
  * event: `started` enables the session, `ended` and `revoked` disable it.
  * Support access is high severity, so a SIEM can alert on vendor access.
+ * OCSF 1.9.0 deprecates Account Change (3001) in favour of this class.
  */
-type OcsfAccountChange = {
-  readonly class_uid: 3001;
+type OcsfUserManagement = {
+  readonly class_uid: 3007;
   readonly category_uid: 3;
-  /** 2 Enable for `started`, 5 Disable for `ended` and `revoked`. */
-  readonly activity_id: 2 | 5;
-  readonly type_uid: 300102 | 300105;
+  /** 4 Enable for `started`, 5 Disable for `ended` and `revoked`. */
+  readonly activity_id: 4 | 5;
+  readonly type_uid: 300704 | 300705;
   readonly severity_id: 4;
   readonly time: number;
   readonly message: string;
@@ -509,7 +859,8 @@ type OcsfAccountChange = {
     readonly reason?: string;
   };
 };
-declare function accessToOcsf(event: AccessEvent): OcsfAccountChange;
+/** An access event whose `at` does not parse projects to `undefined`. */
+declare function accessToOcsf(event: AccessEvent): OcsfUserManagement | undefined;
 //#endregion
 //#region src/core/csv.d.ts
 /** The CSV export columns, in order; the header row of every CSV file. */
@@ -522,8 +873,7 @@ declare function toCsvRow(event: DecisionEvent): string;
 //#endregion
 //#region src/core/catalog-fingerprint.d.ts
 /**
- * The catalog v1 fingerprint: base64url SHA-256 of canonical JSON (keys
- * sorted, no whitespace) without `generatedAt`, `generator`, `fingerprint`
+ * The catalog v1 fingerprint: the `sha-256:` digest of its RFC 8785 JSON without `generatedAt`, `generator`, `fingerprint`
  * and every `permissions[].usages`, so neither the CLI version, the clock nor
  * call sites change it.
  */
@@ -547,4 +897,4 @@ declare function coveredByDelegation(permission: DelegatedPermission, delegation
  */
 declare function delegatedPermissions(delegations: readonly PolicyDelegation[] | undefined, subject: Subject, heldRoles: ReadonlySet<string>, now: number): ReadonlySet<string> | undefined;
 //#endregion
-export { sqlFunction as $, CustomRoleReader as A, memoryRelations as B, getResource as C, definePermissions as D, mergePermissions as E, permittedIds as F, composeMemberships as G, StripeEntitlementsClient as H, mayAccess as I, memoryEntitlementSource as J, countHolders as K, localSnapshotManifest as L, customRoleSource as M, PermittedIdsOptions as N, SnapshotForOptions as O, mayUse as P, memorySnapshotSource as Q, MemoryEdge as R, findPermission as S, listPermissions as T, fromStripeEntitlements as U, memoryLimitStore as V, claimsFirst as W, memoryRoleSource as X, memoryMembershipSource as Y, memorySettings as Z, crud as _, toCsvRow as a, fromSnapshot as at, formerKeys as b, OcsfAuthorizeSession as c, CustomRoleDropReason as ct, parseDuration as d, ResolvedCustomRole as dt, opaque as et, normalizeApproval as f, customRoleClaim as ft, role as g, principal as gt, normalizeAssurance as h, context as ht, CSV_COLUMNS as i, emptySnapshot as it, CustomRoleSourceOptions as j, snapshotFor as k, accessToOcsf as l, CustomRoleRename as lt, deny as m, validateCustomRole as mt, delegatedPermissions as n, separationConflicts as nt, OCSF_VERSION as o, parseSnapshot as ot, allow as p, resolveCustomRole as pt, isExternallyManaged as q, catalogFingerprint as r, requiresApproval as rt, OcsfAccountChange as s, CustomRoleDrop as st, coveredByDelegation as t, definePolicy as tt, toOcsf as u, CustomRoleValidation as ut, readable as v, isPermission as w, resource as x, writable as y, MemoryRelationsData as z };
+export { ShadowMismatch as $, CustomRoleValidation as $t, decideRoleChange as A, isExternallyManaged as At, crud as B, getResource as Bt, parseCloudEventBatch as C, MemoryRelationSourceData as Ct, RoleChangeDecision as D, claimsFirst as Dt, RoleChange as E, stripeEntitlementSource as Et, normalizeApproval as F, memorySettingsSource as Ft, definePermissions as G, separationConflicts as Gt, writable as H, listPermissions as Ht, allow as I, memorySnapshotSource as It, CustomRoleReader as J, fromSnapshot as Jt, SnapshotForOptions as K, requiresApproval as Kt, deny as L, sqlFunction as Lt, activate as M, memoryCustomRoleSource as Mt, breakGlass as N, memoryEntitlementSource as Nt, RoleChangeOptions as O, composeMemberships as Ot, supportAccess as P, memoryMembershipSource as Pt, LegacyCheck as Q, CustomRoleRename as Qt, normalizeAssurance as R, opaque as Rt, parseCloudEvent as S, MemoryEdge as St, parseSinkEvents as T, StripeEntitlementsClient as Tt, formerKeys as U, mergePermissions as Ut, readable as V, isPermission as Vt, resource as W, definePolicy as Wt, customRoleSource as X, CustomRoleDrop as Xt, CustomRoleSourceOptions as Y, parseSnapshot as Yt, mayAccess as Z, CustomRoleDropReason as Zt, DIRECTORY_EVENT_SCHEMA as _, signPolicyDocument as _t, toCsvRow as a, principal as an, localSnapshotManifest as at, SINK_EVENT_SCHEMAS as b, WhoCan as bt, OcsfUserManagement as c, ArazzoSimulateInput as ct, ACCESS_EVENT_SCHEMA as d, simulateArazzo as dt, ResolvedCustomRole as en, ShadowOptions as et, AUTOMATION_EVENT_SCHEMA as f, deliveryEvent as ft, DELIVERY_EVENT_SCHEMA as g, SignPolicyDocumentOptions as gt, DECISION_EVENT_SCHEMA as h, snapshotFromClaims as ht, CSV_COLUMNS as i, context as in, AppProfile as it, ActivateInput as j, APPROVAL_POLICY_UNAVAILABLE as jt, RoleChangeTarget as k, countHolders as kt, accessToOcsf as l, ArazzoStepResult as lt, CREDENTIAL_EVENT_SCHEMA as m, signSnapshot as mt, delegatedPermissions as n, resolveCustomRole as nn, defineApp as nt, OCSF_VERSION as o, ArazzoFinding as ot, CATALOG_EVENT_SCHEMA as p, SignSnapshotOptions as pt, snapshotFor as q, emptySnapshot as qt, catalogFingerprint as r, validateCustomRole as rn, AppOptions as rt, OcsfAuthorizeSession as s, ArazzoPlan as st, coveredByDelegation as t, customRoleClaim as tn, shadowMode as tt, toOcsf as u, arazzoFindings as ut, EVENT_SCHEMA_IDS as v, Holder as vt, parseSinkEvent as w, memoryRelationSource as wt, parseCatalogEventData as x, whoCan as xt, MEMBERSHIP_EVENT_SCHEMA as y, HoldingVia as yt, role as z, findPermission as zt };