@zudojs/permissions 1.1.0 → 1.3.0

package/README.md

@@ -2,6 +2,12 @@
 
 Generic authorization engine with RBAC, ABAC, resource authorization, wildcards, role hierarchy, policies, and abilities.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-permissions](https://zudojs.oyinlola.site/docs/packages-permissions) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-permissions.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -102,8 +108,19 @@ await engine.can(actor, "post:update", { ownerId: "user_1" }); // true
 await engine.can(actor, "post:update", { ownerId: "user_9" }); // false
 ```
 
-Conditions may be async. A condition that throws is treated as unmet — an
-authorization check fails closed.
+Conditions may be async. A condition that cannot be evaluated fails closed,
+and what "closed" means depends on the rule's effect:
+
+- an **allow** whose condition throws (or that has a condition but no
+  context) does not apply;
+- a **deny** whose condition throws **applies**. In the example above,
+  `locked-posts` throws when no resource is passed, and the check is denied —
+  treating the deny as unmet would let the role's allow win. The error is
+  reported through `onError`, and the decision is not cached.
+
+A deny also bears on a wildcard check: `can(actor, "post:*")` is refused by a
+deny on `post:delete`, whether it comes from `deniedPermissions`, a deny rule,
+or a policy registered for `post:delete`.
 
 **Combining.** The default is `deny-overrides`: any applicable deny wins,
 whatever its priority. Pass `algorithm: "priority"` for highest-priority-wins,
@@ -118,13 +135,23 @@ Conditions read request-scoped facts from `context.metadata`, supplied per
 check:
 
 ```typescript
+import { createContextManager, getDefaultStorage } from "@zudojs/tenancy";
+
+const tenancy = createContextManager({ storage: getDefaultStorage() });
+
 await engine.can(actor, "invoice:read", invoice, {
-  metadata: { tenantId: request.tenantId },
+  // The *verified* tenant — resolved and trust-checked by @zudojs/tenancy.
+  // `requireCurrentTenant()` is a method on the context manager; it throws
+  // when no tenant context is active, rather than returning undefined.
+  metadata: { tenantId: tenancy.requireCurrentTenant().id },
 });
 ```
 
 `tenantIsolation()` compares that value against the resource's tenant, and
-denies when either is missing.
+denies when either is missing. It is only as good as the value you pass: fill
+`tenantId` from a source the client cannot choose (a verified token claim, or
+the tenant `@zudojs/tenancy` resolved), **never from a request header** — a
+caller would set the header to the resource's tenant and pass.
 
 ## Policies
 
@@ -176,9 +203,14 @@ const policies = createPolicyRegistry();
 const engine = createPermissionEngine({ roles, policies });
 
 roles.define({ name: "auditor", permissions: ["audit:read"] });
-engine.invalidateRoles(); // pick up the change
+roles.remove("reader");
+// both take effect on the next check: the engine subscribes to the registry
 
-policies.define({ name: "lockdown", permissions: ["*:*"], evaluate: () => ({ allowed: false }) });
+policies.define({
+  name: "lockdown",
+  permissions: ["*:*"],
+  evaluate: () => ({ allowed: false }),
+});
 // enforced by the next check — through the engine or an existing Ability
 
 roles.require("auditor"); // throws RoleNotFoundError when unregistered
@@ -188,9 +220,17 @@ All three registries reject a duplicate name — re-registering a role or a
 policy is an authorization rule disappearing without a trace. Pass
 `{ allowOverride: true }` when replacement is what you mean.
 
-`validateConfiguration` (default `true`) applies to a registry as well as to
-an inline array: a role whose grant could never match is rejected when the
-engine looks it up, and the check denies.
+The engine subscribes to a role or policy registry it is given. Every
+`define`, `remove` and `clear` discards the memoized roles **and every cached
+decision**, so revoking a role is not undone by a cache entry written before
+the revocation. `engine.invalidateRoles()` does the same for a custom source.
+
+`validateConfiguration` (default `true`) rejects a pattern that could never
+match wherever it is written — a role grant, a role's rules, a static rule, or
+a policy's `permissions` — because a malformed pattern in a deny or a lockdown
+policy would fail open in silence. Arrays are checked at construction; a
+registry checks on `define` (`InvalidRoleError` / `InvalidPermissionError`),
+and a custom source is checked when the engine reads it.
 
 A permission registry records descriptions and implications:
 
@@ -201,11 +241,17 @@ permissions.define("post:write", { implies: ["post:read"] });
 
 const engine = createPermissionEngine({
   roles,
-  expandImplied: (permission) => permissions.expandImplied(permission),
+  expandImplied: permissions,
 });
 // An actor granted post:admin now passes post:read.
 ```
 
+Pass the registry itself rather than a closure over it. The engine subscribes
+to it, so `permissions.remove("post:admin")` — or redefining it without the
+implication — drops the decisions that were cached while it stood. A bare
+`(permission) => permissions.expandImplied(permission)` still works, but it
+cannot announce a change, so an engine given one caches no decisions at all.
+
 ## Caching
 
 ```typescript
@@ -226,10 +272,13 @@ await engine.can(actor, "post:read", post, { skipCache: true });
 await engine.invalidateActor("user_1");
 ```
 
-Keys include the actor, the permission and the resource id (from
-`resource.id`, or `options.resourceId`), so two resources never share one
-decision. A `|` inside an actor or resource id is escaped, so two different
-(actor, permission, resource) triples can never share a key either.
+Keys include the actor id, a digest of everything else the actor carries
+(`roles`, `permissions`, `type`, any other field a condition may read), the
+permission and the resource id (from `resource.id`, or `options.resourceId`).
+The same user id with different roles — an admin token in one tenant and a
+viewer token in another, or a demoted token — never shares a decision. A `|`
+inside an actor or resource id is escaped, so two different checks can never
+share a key either.
 
 A check is cached only when the key can describe it completely:
 
@@ -239,7 +288,16 @@ A check is cached only when the key can describe it completely:
 - a check carrying `metadata` is **not cached**, because conditions such as
   `tenantIsolation()` read the tenant from there and it is not part of the
   key;
-- a decision produced by a policy marked `cacheable: false` is not stored;
+- an actor carrying something the digest cannot describe (a function, a class
+  instance, a `Map`) is **not cached**;
+- a decision produced by a policy marked `cacheable: false`, or forced by a
+  condition that threw, is not stored;
+- an engine with a `roleResolver` or `permissionResolver` and no
+  `resolverCacheKey` caches **nothing**: the resolver reads state the key
+  cannot describe, so an entry would outlive a grant withdrawn upstream;
+- an engine whose `expandImplied` is a bare function rather than a
+  `createPermissionRegistry()` caches **nothing**, for the same reason: a
+  revoked implication cannot announce itself;
 - a TTL of `0` or less means "do not cache".
 
 `deniedPermissions` is evaluated before the cache is consulted, so a deny
@@ -260,20 +318,40 @@ const engine = createPermissionEngine({
 A resolver that fails is reported through `onError` and the check continues
 fail-closed, rather than throwing out of the authorization path.
 
+A resolver reads authorization state the engine does not own and cannot see
+change, and none of it is in the decision-cache key. **A resolver-backed
+engine therefore caches nothing** unless you describe that state with
+`resolverCacheKey`:
+
+```typescript
+const engine = createPermissionEngine({
+  roles,
+  cache: createMemoryPermissionCache(),
+  permissionResolver: { resolvePermissions: (actor) => db.rulesFor(actor.id) },
+  // Anything that changes when the resolver's answer could change.
+  resolverCacheKey: (actor) => db.grantsVersionFor(actor.id),
+});
+```
+
+Return `undefined` for an actor whose state you cannot describe, and that
+actor's decisions stay uncached.
+
 ## Failure behaviour
 
 Every failure denies:
 
-| Situation                   | Result                                                 |
-| --------------------------- | ------------------------------------------------------ |
-| Unknown role on the actor   | denied; reported to `onError`; other roles still apply |
-| Malformed permission string | denied, `reason: "invalid_permission"`                 |
-| Condition throws            | rule does not apply                                    |
-| A deny rule applies         | denied, `reason: "rule_deny"`, even if a policy allows |
-| Policy throws or times out  | denied, `reason: "policy_error:<name>"`                |
-| Role inheritance cycle      | denied; reported to `onError`                          |
-| Role source throws          | denied; reported to `onError`                          |
-| `signal` aborted            | throws `AuthorizationAbortedError`                     |
+| Situation                     | Result                                                 |
+| ----------------------------- | ------------------------------------------------------ |
+| Unknown role on the actor     | denied; reported to `onError`; other roles still apply |
+| Malformed permission string   | denied, `reason: "invalid_permission"`                 |
+| Allow condition throws        | the allow does not apply                               |
+| Deny condition throws         | denied, `reason: "rule_deny"`; reported to `onError`   |
+| Malformed rule/policy pattern | rejected at construction or `define`                   |
+| A deny rule applies           | denied, `reason: "rule_deny"`, even if a policy allows |
+| Policy throws or times out    | denied, `reason: "policy_error:<name>"`                |
+| Role inheritance cycle        | denied; reported to `onError`                          |
+| Role source throws            | denied; reported to `onError`                          |
+| `signal` aborted              | throws `AuthorizationAbortedError`                     |
 
 A value that is not an `Error` — a policy or resolver that throws a string —
 reaches `onError` wrapped in `PolicyError` or `PermissionResolverError`, with
@@ -324,8 +402,10 @@ emitter.on((event) => auditLog.write(event));
 const engine = createPermissionEngine({ roles, emitter });
 ```
 
-Every check emits — allowed, denied, and the ones that throw. A handler that
-throws cannot break authorization, but it is reported rather than swallowed.
+Every check emits — allowed, denied, and the ones that throw — including
+`explain()` on the engine and on an Ability, which make the same real
+decision. A handler that throws cannot break authorization, but it is reported
+rather than swallowed.
 
 ## HTTP middleware
 
@@ -334,10 +414,14 @@ import { authorize, createActorMiddleware } from "@zudojs/permissions";
 
 const guard = authorize(engine, "post:update", {
   extractActor: (context) => context.state.get("auth:user"),
-  extractResource: (context) => loadPost(context.request.params.get("id")),
+  // May be async: it is awaited, and a loader that rejects denies (403).
+  extractResource: (context) => loadPost(context.request.getParam?.("id")),
+  // The tenant @zudojs/tenancy resolved and trust-checked — never a header.
   extractMetadata: (context) => ({
-    tenantId: context.request.headers.get("x-tenant"),
+    tenantId: context.state.get<{ tenantId: string }>("tenancy:context")
+      ?.tenantId,
   }),
+  onError: (error, source) => logger.warn({ error, source }, "guard denied"),
 });
 ```
 
@@ -351,11 +435,16 @@ const guard = authorize(engine, "post:update", {
   decision.
 - `context.signal` is forwarded, so a client disconnect stops policy
   evaluation.
+- `extractResource` is awaited. A loader that throws or rejects answers
+  **403** (`reason: "resource_error"`) and reports through `onError`; it never
+  lets the request through.
 - `createRequirePermissionsMiddleware(engine, permissions, { mode })` checks
   several permissions, short-circuiting on the first that decides the outcome.
+  An empty list denies in either mode.
 
-`@zudojs/http` is an optional peer dependency; the middleware types are
-mirrored locally so this package works without it.
+The middleware composes with the real `@zudojs/http` pipeline without
+depending on it: the HTTP types are mirrored structurally (headers, params and
+query may be plain objects, as `@zudojs/http` provides them, or maps).
 
 ## Errors
 

package/dist/ability/ability.core.js

@@ -5,33 +5,13 @@
  */
 import { evaluate, evaluateWithTrace } from "../evaluator/evaluator.core.js";
 import { PermissionDeniedError } from "../permissionErrors/index.js";
+import { observed } from "../evaluator/engineSupport/index.js";
 /**
  * Create an Ability for an actor.
  */
 export function createAbility(actor, evaluatorOptions, emitter) {
-    async function run(permission, resource, options) {
-        const start = performance.now();
-        let decision;
-        let failure;
-        try {
-            decision = await evaluate(actor, permission, resource, evaluatorOptions, options);
-            return decision;
-        }
-        catch (error) {
-            failure = error;
-            throw error;
-        }
-        finally {
-            emitter?.emit({
-                actorId: actor.id,
-                permission,
-                allowed: decision?.allowed ?? false,
-                reason: decision?.reason ??
-                    (failure instanceof Error ? `error:${failure.name}` : undefined),
-                durationMs: performance.now() - start,
-                errored: failure !== undefined,
-            });
-        }
+    function run(permission, resource, options) {
+        return observed(emitter, actor, permission, resource, () => evaluate(actor, permission, resource, evaluatorOptions, options), (decision) => decision);
     }
     return {
         actor,
@@ -45,7 +25,7 @@ export function createAbility(actor, evaluatorOptions, emitter) {
             return run(permission, resource, options);
         },
         async explain(permission, resource, options) {
-            return evaluateWithTrace(actor, permission, resource, evaluatorOptions, options);
+            return observed(emitter, actor, permission, resource, () => evaluateWithTrace(actor, permission, resource, evaluatorOptions, options), (result) => result.decision);
         },
         async authorize(permission, resource, options) {
             const decision = await run(permission, resource, options);

package/dist/cache/cache.actorDigest.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Actor digest for the decision cache key.
+ *
+ * A decision depends on everything the actor carries, not only its id:
+ * `roles`, `permissions` and `type` travel on the actor object for each
+ * request (a tenant-scoped token, `auth.checkAccess`), and a condition may
+ * read any other field on it. Keying on the id alone let an admin decision
+ * made in one tenant answer for the same user as a viewer in another, and a
+ * demoted token keep its old grants until the entry expired.
+ *
+ * @module cache/cache.actorDigest
+ */
+import type { PermissionActor } from "../permissionTypes/index.js";
+/** Longest digest worth keying on; a longer one is not cached at all. */
+export declare const MAX_ACTOR_DIGEST_LENGTH = 4096;
+/**
+ * A stable description of everything an actor carries besides its id.
+ *
+ * Returns `undefined` when the actor holds something the digest cannot
+ * describe faithfully — a function, a class instance, a `Map`, nesting past
+ * six levels, or a digest longer than {@link MAX_ACTOR_DIGEST_LENGTH}. The
+ * engine does not cache such a decision rather than key it on a partial
+ * description.
+ */
+export declare function actorCacheDigest(actor: PermissionActor): string | undefined;
+//# sourceMappingURL=cache.actorDigest.d.ts.map

package/dist/cache/cache.actorDigest.js

@@ -0,0 +1,90 @@
+/**
+ * Actor digest for the decision cache key.
+ *
+ * A decision depends on everything the actor carries, not only its id:
+ * `roles`, `permissions` and `type` travel on the actor object for each
+ * request (a tenant-scoped token, `auth.checkAccess`), and a condition may
+ * read any other field on it. Keying on the id alone let an admin decision
+ * made in one tenant answer for the same user as a viewer in another, and a
+ * demoted token keep its old grants until the entry expired.
+ *
+ * @module cache/cache.actorDigest
+ */
+/** Longest digest worth keying on; a longer one is not cached at all. */
+export const MAX_ACTOR_DIGEST_LENGTH = 4096;
+/** Deepest nesting the digest will describe. */
+const MAX_DEPTH = 6;
+/** Marks a value the digest cannot describe faithfully. */
+const UNDESCRIBABLE = Symbol("undescribable");
+function isPlainRecord(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function canonical(value, depth) {
+    if (depth > MAX_DEPTH)
+        return UNDESCRIBABLE;
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return JSON.stringify(value);
+        case "number":
+            return Number.isFinite(value) ? JSON.stringify(value) : UNDESCRIBABLE;
+        case "object":
+            break;
+        default:
+            return UNDESCRIBABLE;
+    }
+    const object = value;
+    if (object instanceof Date) {
+        const time = object.getTime();
+        return Number.isNaN(time) ? UNDESCRIBABLE : `D${JSON.stringify(time)}`;
+    }
+    if (Array.isArray(object)) {
+        const parts = [];
+        for (const entry of object) {
+            const part = canonical(entry, depth + 1);
+            if (part === UNDESCRIBABLE)
+                return UNDESCRIBABLE;
+            parts.push(part);
+        }
+        return `[${parts.join(",")}]`;
+    }
+    if (!isPlainRecord(object))
+        return UNDESCRIBABLE;
+    return canonicalRecord(object, depth, []);
+}
+function canonicalRecord(record, depth, skip) {
+    const parts = [];
+    for (const key of Object.keys(record).sort()) {
+        if (skip.includes(key))
+            continue;
+        const entry = record[key];
+        if (entry === undefined)
+            continue;
+        const part = canonical(entry, depth + 1);
+        if (part === UNDESCRIBABLE)
+            return UNDESCRIBABLE;
+        parts.push(`${JSON.stringify(key)}:${part}`);
+    }
+    return `{${parts.join(",")}}`;
+}
+/**
+ * A stable description of everything an actor carries besides its id.
+ *
+ * Returns `undefined` when the actor holds something the digest cannot
+ * describe faithfully — a function, a class instance, a `Map`, nesting past
+ * six levels, or a digest longer than {@link MAX_ACTOR_DIGEST_LENGTH}. The
+ * engine does not cache such a decision rather than key it on a partial
+ * description.
+ */
+export function actorCacheDigest(actor) {
+    if (typeof actor !== "object" || actor === null)
+        return undefined;
+    const digest = canonicalRecord(actor, 0, ["id"]);
+    if (digest === UNDESCRIBABLE)
+        return undefined;
+    return digest.length > MAX_ACTOR_DIGEST_LENGTH ? undefined : digest;
+}
+//# sourceMappingURL=cache.actorDigest.js.map

package/dist/cache/cache.core.d.ts

@@ -10,8 +10,14 @@ import type { PermissionCache } from "../permissionTypes/index.js";
  * The actor id is delimited, so invalidating actor `1` cannot also clear
  * actors `10` and `123`, and a delimiter inside an id is escaped so two
  * different (actor, permission, resource) triples can never share a key.
+ *
+ * `scope` carries whatever else the decision depends on — the engine passes
+ * a digest of the actor's roles, permissions and attributes, so the same id
+ * holding different grants never shares a key. It sits after the actor
+ * prefix behind a `~`, which no permission string can start with, so
+ * `invalidateActor` still finds every entry for the actor.
  */
-export declare function permissionCacheKey(actorId: string, permission: string, resourceId?: string): string;
+export declare function permissionCacheKey(actorId: string, permission: string, resourceId?: string, scope?: string): string;
 /** Options for {@link createMemoryPermissionCache}. */
 export interface MemoryPermissionCacheOptions {
     /** Default TTL in milliseconds. Defaults to 60,000 (1 minute). */

package/dist/cache/cache.core.js

@@ -27,9 +27,16 @@ function actorPrefix(actorId) {
  * The actor id is delimited, so invalidating actor `1` cannot also clear
  * actors `10` and `123`, and a delimiter inside an id is escaped so two
  * different (actor, permission, resource) triples can never share a key.
+ *
+ * `scope` carries whatever else the decision depends on — the engine passes
+ * a digest of the actor's roles, permissions and attributes, so the same id
+ * holding different grants never shares a key. It sits after the actor
+ * prefix behind a `~`, which no permission string can start with, so
+ * `invalidateActor` still finds every entry for the actor.
  */
-export function permissionCacheKey(actorId, permission, resourceId) {
-    const base = `${actorPrefix(actorId)}${permission}`;
+export function permissionCacheKey(actorId, permission, resourceId, scope) {
+    const scoped = scope === undefined ? "" : `~${escapeSegment(scope)}${KEY_DELIMITER}`;
+    const base = `${actorPrefix(actorId)}${scoped}${permission}`;
     return resourceId
         ? `${base}${KEY_DELIMITER}${escapeSegment(resourceId)}`
         : base;

package/dist/cache/index.d.ts

@@ -4,4 +4,5 @@
  * @module cache
  */
 export { createMemoryPermissionCache, permissionCacheKey, type MemoryPermissionCacheOptions, } from "./cache.core.js";
+export { actorCacheDigest, MAX_ACTOR_DIGEST_LENGTH, } from "./cache.actorDigest.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cache/index.js

@@ -4,4 +4,5 @@
  * @module cache
  */
 export { createMemoryPermissionCache, permissionCacheKey, } from "./cache.core.js";
+export { actorCacheDigest, MAX_ACTOR_DIGEST_LENGTH, } from "./cache.actorDigest.js";
 //# sourceMappingURL=index.js.map

package/dist/evaluator/authorizationEngine.d.ts

@@ -6,14 +6,40 @@
 import type { PermissionActor, PermissionDecision, ExplainResult, PermissionRule, PermissionPolicyDefinition, PermissionCache, PermissionResolver, RoleResolver, RoleDefinition, RuleCombiningAlgorithm, AuthorizationOptions } from "../permissionTypes/index.js";
 import { type Ability } from "../ability/ability.core.js";
 import type { PermissionEventEmitter } from "../observability/observability.core.js";
-/** Anything the engine will accept as its source of roles. */
+/**
+ * Anything the engine will accept as its source of roles.
+ *
+ * A source with `subscribe` (every `createRoleRegistry()`) is watched: a
+ * `define`, `remove` or `clear` discards the engine's memoized roles and
+ * every cached decision, so revoking a role takes effect on the next check.
+ */
 export interface RoleSource {
     get(name: string): RoleDefinition | undefined;
+    subscribe?(listener: () => void): () => void;
 }
-/** Anything the engine will accept as its source of policies. */
+/**
+ * Anything the engine will accept as its source of policies.
+ *
+ * A source with `subscribe` (every `createPolicyRegistry()`) is watched the
+ * same way, so a policy added or removed is not bypassed by a cached decision.
+ */
 export interface PolicySource {
     names(): readonly string[];
     get(name: string): PermissionPolicyDefinition | undefined;
+    subscribe?(listener: () => void): () => void;
+}
+/**
+ * Anything the engine will accept as its source of permission implications.
+ *
+ * A source with `subscribe` (every `createPermissionRegistry()`) is watched
+ * like the role and policy registries: revoking an implication drops every
+ * decision that was cached while it stood. A bare function cannot announce a
+ * change, so an engine given one caches nothing — see
+ * {@link PermissionEngineOptions.expandImplied}.
+ */
+export interface ImpliedPermissionSource {
+    expandImplied(permission: string): readonly string[];
+    subscribe?(listener: () => void): () => void;
 }
 /** Configuration for the permission engine. */
 export interface PermissionEngineOptions {
@@ -41,8 +67,31 @@ export interface PermissionEngineOptions {
     readonly permissionResolver?: PermissionResolver;
     /** Loads additional roles for an actor from an external source. */
     readonly roleResolver?: RoleResolver;
-    /** Expands a permission into the permissions it implies. */
-    readonly expandImplied?: (permission: string) => readonly string[];
+    /**
+     * Describes the state a resolver is answering from, so that decisions it
+     * influenced can be cached safely.
+     *
+     * A resolver reads authorization data the engine does not own and cannot
+     * see change — a grants table, another service. Nothing about it is in the
+     * decision-cache key, so an entry written while the resolver said "allow"
+     * kept answering after the grant was withdrawn upstream. Resolver-backed
+     * engines therefore **do not cache at all** unless this is supplied.
+     *
+     * Return a value that changes whenever the resolver's answer for this actor
+     * could change — a version column, an `updatedAt` stamp, a grants-table
+     * generation. Return `undefined` for an actor whose state cannot be
+     * described, and that actor's decisions stay uncached.
+     */
+    readonly resolverCacheKey?: (actor: PermissionActor) => string | undefined;
+    /**
+     * Expands a permission into the permissions it implies.
+     *
+     * Prefer passing a `createPermissionRegistry()` — the engine subscribes to
+     * it, so revoking an implication invalidates the decisions cached under it.
+     * A bare function cannot announce a change, so an engine given one caches
+     * no decisions rather than serving one from a revoked implication.
+     */
+    readonly expandImplied?: ((permission: string) => readonly string[]) | ImpliedPermissionSource;
     /** Emits an event for every completed check, including failures. */
     readonly emitter?: PermissionEventEmitter;
     /** Reports a failure authorization swallowed to stay fail-closed. */
@@ -79,7 +128,11 @@ export interface PermissionEngine {
     createAbility(actor: PermissionActor): Ability;
     /** Drop cached decisions for one actor. */
     invalidateActor(actorId: string): Promise<void>;
-    /** Re-read the role source, discarding the memoized lookups. */
+    /**
+     * Re-read the role source, discarding the memoized lookups and every
+     * cached decision. Registries created with `createRoleRegistry()` and
+     * `createPolicyRegistry()` trigger this themselves on every change.
+     */
     invalidateRoles(): void;
 }
 /**