@procedures/client 0.35.0 → 0.36.0

package/src/adapters/websocket/shared/rpc.ts

@@ -18,6 +18,7 @@ import { withoutInternalKeys } from "../../metadata.js";
 import { StreamSequence, gapOf, itemMetadata } from "../../sequence.js";
 import { DELIVERY_METADATA_KEY } from "../../../client/middleware/items.js";
 import { errorCodeOf, foldedErrorCode, retryableOf } from "../../../protocol.js";
+import { lastResortError } from "../../../server/last-resort.js";
 
 /**
  * A queue of response items that one reader takes in order: push, then end or fail. The reader
@@ -382,8 +383,10 @@ export class IncomingCalls {
     const controller = new AbortController();
     this.inflight.set(frame.id, controller);
     let credit: StreamCredit | undefined;
+    let request: ServerRequest | undefined;
     try {
-      const response = await this.options.handler.handle(this.options.requestOf(frame, controller.signal));
+      request = this.options.requestOf(frame, controller.signal);
+      const response = await this.options.handler.handle(request);
       if (response.stream) {
         credit = typeof frame.credit === "number" && frame.credit > 0 ? new StreamCredit(frame.credit) : undefined;
         if (credit) this.credits.set(frame.id, credit);
@@ -402,7 +405,12 @@ export class IncomingCalls {
         this.send(out);
       }
     } catch (error) {
-      this.sendError(frame.id, error instanceof Error ? error.message : "Internal server error", "INTERNAL_ERROR");
+      // The last resort: the error policy of the server applies here too (CLI-80)
+      const raw = { code: "INTERNAL_ERROR", message: error instanceof Error ? error.message : "Internal server error", retryable: false };
+      const exposed = lastResortError(this.options.handler, error, request, raw);
+      // The wait of a map result (retryAfterMs) goes out as on the usual error path (CLI-80)
+      const wait = exposed.retryAfterMs;
+      this.sendError(frame.id, exposed.message, exposed.code, exposed.retryable === true, typeof wait === "number" && Number.isFinite(wait) && wait >= 0 ? { "retry-after": wait } : undefined);
     } finally {
       // Delete only this request's entries (deep dive TRN-9)
       if (this.inflight.get(frame.id) === controller) {
@@ -463,12 +471,13 @@ export class IncomingCalls {
     if (this.options.isOpen()) this.options.send(frame);
   }
 
-  private sendError(id: string, message: string, code: string): void {
+  private sendError(id: string, message: string, code: string, retryable = false, metadata?: Record<string, unknown>): void {
     this.send({
       id,
       type: "error",
-      status: { type: "error", code, message, retryable: false },
-      error: { code, message, retryable: false },
+      ...(metadata ? { metadata } : {}),
+      status: { type: "error", code, message, retryable },
+      error: { code, message, retryable },
     });
   }
 }

package/src/browser.ts

@@ -64,6 +64,7 @@ export {
   ERROR_REGISTRY,
   getErrorMetadata,
   isKnownError,
+  isKnownErrorCode,
   createError,
   createErrorFromHTTPStatus,
   createErrorFromException,
@@ -76,6 +77,9 @@ export {
 // ============================================================================
 export { Server } from "./server/server.js";
 export type { ServerOptions } from "./server/server.js";
+// The error policy of a server: what an error tells the caller (roadmap CLI-80)
+export type { ServerErrorPolicy, ExposedError, ErrorCall } from "./server/error-policy.js";
+export { exposeError, lastResortError, HIDDEN_ERROR_MESSAGE, DEFAULT_KEPT_METADATA } from "./server/error-policy.js";
 export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream, tokenMatches } from "./server/procedure-server.js";
 // The credentials of a network request (roadmap R18), and the parts that a request hook reads (CLI-2a)
 export { credentialsOf, bearerOf, withoutSecretHeaders, cookiesOf, requestCredentials, LOCAL_CREDENTIALS, isLocalCredentials } from "./server/request-auth.js";
@@ -144,6 +148,9 @@ export {
   // The rules of the rows of a collection (roadmap CLI-41)
   admittedStorage,
   admitsRow,
+  // The images of the rows of a change event, for the row filter of each subscriber (roadmap CLI-78)
+  withHintImages,
+  hintImagesOf,
   // The query language of the collection storages (roadmap CLI-14, CLI-34)
   DEFAULT_FIND_LIMIT,
   DEFAULT_QUERY_OPERATORS,
@@ -333,6 +340,8 @@ export type {
   CollectionChangeEventsOptions,
   CollectionAdmission,
   CollectionRow,
+  HintImages,
+  HintRowState,
   CollectionWrite,
   CollectionWriteGuard,
   CollectionPartitions,
@@ -586,6 +595,8 @@ export type {
   TopicRule,
   TopicCall,
   RightsChange,
+  RightsScope,
+  RightsScopes,
   SubscriptionRecheck,
   EventItem,
   RemoteEvent,

package/src/client/errors/index.ts

@@ -46,6 +46,7 @@ export {
   ERROR_REGISTRY,
   getErrorMetadata,
   isKnownError,
+  isKnownErrorCode,
   getErrorsByCategory,
   getRetryableErrors,
 } from "./registry.js";

package/src/client/errors/registry.ts

@@ -643,6 +643,19 @@ export function isKnownError(code: string): boolean {
   return code in ERROR_REGISTRY;
 }
 
+/**
+ * True when a value is a known error code of the client: a code of the wire protocol
+ * (`ERROR_CODES`) or another code of `ERROR_REGISTRY`, for example `CONFLICT` or `BAD_REQUEST`
+ * (roadmap CLI-80). Only a string can be a known code. A code of the platform (`ECONNREFUSED`,
+ * `ENOENT`) and a number (a code of MongoDB) are not known codes.
+ *
+ * The error policy `expose: "coded"` of a server uses this check: an error with a known code is a
+ * deliberate refusal, so its code and its message go to the caller.
+ */
+export function isKnownErrorCode(code: unknown): code is string {
+  return typeof code === "string" && Object.prototype.hasOwnProperty.call(ERROR_REGISTRY, code);
+}
+
 /**
  * Get all error codes by category.
  */

package/src/client/index.ts

@@ -15,6 +15,7 @@ export {
   ERROR_REGISTRY,
   getErrorMetadata,
   isKnownError,
+  isKnownErrorCode,
   createError,
   createErrorFromHTTPStatus,
   createErrorFromException,

package/src/events/bus.ts

@@ -444,6 +444,9 @@ export function resetGlobalEventBus(): void {
   globalBus = undefined;
 }
 
+/** The key of the bus under a view of a bus. */
+const BASE_BUS = Symbol.for("procedures.baseBus");
+
 /**
  * A view of a bus whose `stream()` and `once()` use a signal when the caller gives none. The
  * context of a procedure gets this view: when the invocation aborts, the handler's waits on
@@ -455,7 +458,7 @@ export function resetGlobalEventBus(): void {
  */
 export function withEventBusSignal(bus: EventBus, signal: AbortSignal): EventBus {
   const waitOptions = (options?: EventWaitOptions): EventWaitOptions => ({ signal: options?.signal ?? signal });
-  return {
+  const view: EventBus = {
     emit: (channel, data) => bus.emit(channel, data),
     on: (channel, handler, options) => bus.on(channel, handler, options),
     once: (channel, options) => bus.once(channel, waitOptions(options)),
@@ -466,6 +469,8 @@ export function withEventBusSignal(bus: EventBus, signal: AbortSignal): EventBus
     clear: (channel) => bus.clear(channel),
     clearAll: () => bus.clearAll(),
   };
+  // The bus under the view: the marks of the row filters of the events belong to it (roadmap CLI-78)
+  return Object.defineProperty(view, BASE_BUS, { value: (bus as { [BASE_BUS]?: EventBus })[BASE_BUS] ?? bus, enumerable: false });
 }
 
 // =============================================================================

package/src/events/index.ts

@@ -59,7 +59,7 @@ export {
 // The remote events: a peer subscribes to the topics of the bus of another peer (EVENTS.md)
 export { EventPublisher, topicMatcher, MAX_SUBSCRIPTION_TOPICS, MAX_TOPIC_LENGTH } from "./publisher.js";
 export type { EventPublisherOptions, TopicRule, TopicCall } from "./publisher.js";
-export type { RightsChange, SubscriptionRecheck } from "./recheck.js";
+export type { RightsChange, RightsScope, RightsScopes, SubscriptionRecheck } from "./recheck.js";
 export { EVENTS_SUBSCRIBE_PATH, SubscriptionError, remoteEvents, subscribeRemote } from "./remote.js";
 export type {
   EventItem,

package/src/events/publisher.ts

@@ -20,6 +20,12 @@
  *   (`ctx.admit`): each row passes the filter, and the subscriber gets only the admitted rows.
  * - An open subscription gets the same checks again at a change of the rights (`rightsChanged()`,
  *   `recheck.rightsChanges`) and after `recheck.maxAge` (roadmap CLI-44). A refusal ends it.
+ * - The change events of a collection with a rule of the rows (`admission.admit`) reach each
+ *   subscriber through a row filter (roadmap CLI-78, `hint-filter.ts`). The subscriber gets only the
+ *   ids of the rows that it can read. A re-check at a change of the rights gives such a subscriber a
+ *   `reset` hint, so it reads its rows again.
+ * - The `seq` of an event counts the events that the subscriber gets. An event that the row filter
+ *   takes out gets no number, so the subscriber sees no gap.
  *
  * The delivery is at most once. The queue of a subscription holds at most `buffer` events. When
  * it is full, the publisher drops the oldest event, and the next event tells the number of lost
@@ -39,7 +45,8 @@ import { getGlobalEventBus } from "./bus.js";
 import { EVENTS_SUBSCRIBE_PATH, type EventItem, type SubscribeInput } from "./remote.js";
 import { admittedValue, rowsOf } from "./rows.js";
 import { realClock, type Clock } from "../clock.js";
-import { SubscriptionRechecks, type RightsChange, type SubscriptionRecheck } from "./recheck.js";
+import { SubscriptionRechecks, type RecheckCause, type RightsChange, type RightsScope, type RightsScopes, type SubscriptionRecheck } from "./recheck.js";
+import { DROPPED, RowHintFilter, collectionInvocation, collectionRulesOf, markFilteredTopic, type HintFilterMode } from "../procedures/collection/hint-filter.js";
 
 /** The number of topics that one subscription can name. */
 export const MAX_SUBSCRIPTION_TOPICS = 64;
@@ -172,7 +179,45 @@ const eventItemSchema = z.discriminatedUnion("type", [
 ]);
 
 /** A topic of a subscriber, and the topic of the bus that it listens to. */
-type Route = readonly [topic: string, busTopic: string];
+interface Route {
+  readonly topic: string;
+  readonly busTopic: string;
+  /** The collection of a topic of a collection, and its resolved partition (roadmap CLI-78). */
+  readonly collection?: string | undefined;
+  readonly partition?: string | undefined;
+  /** The partition that the topic names, before the resolver: the input of the rules has it. */
+  readonly requested?: string | undefined;
+}
+
+/** True when a change of the rights with this scope touches the rows of the route (roadmap CLI-78). */
+function inScope(route: Route, scope: RightsScopes | undefined): boolean {
+  if (scope === undefined) return true;
+  const scopes: readonly RightsScope[] = Array.isArray(scope) ? scope : [scope as RightsScope];
+  return scopes.some(({ collection, partition }) => matchesName(collection, route.collection) && matchesName(partition, route.partition));
+}
+
+/** True when a name of a route matches a field of a scope. A test that throws matches. */
+function matchesName(field: RightsScope["collection"], name: string | undefined): boolean {
+  if (field === undefined) return true;
+  if (name === undefined) return false;
+  if (typeof field === "string") return field === name;
+  try {
+    return field(name) === true;
+  } catch {
+    return true;
+  }
+}
+
+/** An event of the bus that waits in the queue of a subscription. It gets its `seq` when the subscriber gets it. */
+interface QueuedEvent {
+  readonly topic: string;
+  readonly data: unknown;
+}
+
+/** The `reset` hint that a re-check gives to a subscriber with a row filter (roadmap CLI-78). */
+function resetHint(): unknown {
+  return { changed: [], deleted: [], reset: true };
+}
 
 /**
  * One subscription: the listeners on the bus and the queue of its events. It is the async
@@ -182,7 +227,7 @@ type Route = readonly [topic: string, busTopic: string];
  */
 class TopicSubscription implements AsyncIterableIterator<EventItem> {
   private confirmation: EventItem | undefined;
-  private readonly queue: Array<Extract<EventItem, { type: "event" }>> = [];
+  private readonly queue: QueuedEvent[] = [];
   private seq = 0;
   private dropped = 0;
   private waiter:
@@ -207,10 +252,12 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     private readonly admit: ((item: unknown) => Promise<boolean>) | undefined,
     /** The invocation of the subscription: the rule of the rows of a value gets it (roadmap CLI-41) */
     private readonly invocation?: Invocation | undefined,
+    /** The row filter of each topic of a collection, by the topic of the subscriber (roadmap CLI-78) */
+    private readonly filters?: ReadonlyMap<string, RowHintFilter> | undefined,
   ) {
-    this.confirmation = { type: "subscribed", topics: routes.map(([topic]) => topic) };
+    this.confirmation = { type: "subscribed", topics: routes.map(({ topic }) => topic) };
     // Before, clear() removed the listeners, and the subscriber saw no end (EVENTS.md)
-    this.unsubscribes = routes.map(([topic, busTopic]) =>
+    this.unsubscribes = routes.map(({ topic, busTopic }) =>
       bus.on(busTopic, (data) => this.push(topic, data), { onClear: () => this.fail(clearedError(topic), { keepQueue: true }) }),
     );
     signal?.addEventListener("abort", this.onAbort, { once: true });
@@ -227,7 +274,7 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
   /** This function takes one event of the bus. It never waits. */
   private push(topic: string, data: unknown): void {
     if (this.closed) return;
-    const event = { type: "event" as const, topic, data, seq: ++this.seq };
+    const event: QueuedEvent = { topic, data };
     const waiter = this.waiter;
     if (waiter && this.queue.length === 0 && !this.recheck) {
       this.waiter = undefined;
@@ -243,22 +290,44 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
   }
 
   /**
-   * The item of an event for the subscriber. The rows of its data pass the output filter of the
-   * host for this subscriber and the rule of the rows, and the subscriber gets only the admitted rows.
+   * This function gives a `reset` hint to the subscriber on a topic (roadmap CLI-78): its rights
+   * changed, so it reads its rows again. The hint goes after the events of the queue.
    */
-  private deliver(event: Extract<EventItem, { type: "event" }>): Promise<IteratorResult<EventItem>> {
-    const item = this.withDropped(event) as Extract<EventItem, { type: "event" }>;
-    const rows = rowsOf(item.data);
-    if (!rows || (!this.admit && !rows.admit)) return Promise.resolve({ value: item, done: false });
-    return admittedValue(item.data, this.admit, this.invocation).then((data): IteratorResult<EventItem> => ({ value: { ...item, data }, done: false }));
+  reset(topic: string): void {
+    this.filters?.get(topic)?.forget();
+    this.push(topic, resetHint());
+  }
+
+  /**
+   * The item of an event for the subscriber. The ids of a change event pass the row filter of the
+   * topic (roadmap CLI-78). The rows of its data pass the output filter of the host for this
+   * subscriber and the rule of the rows. The subscriber gets only the admitted rows. An event
+   * that the row filter takes out goes, and the subscriber gets the next event.
+   */
+  private deliver(event: QueuedEvent): Promise<IteratorResult<EventItem>> {
+    const filtered = this.filters?.get(event.topic)?.apply(event.data);
+    if (!filtered) return this.item(event.topic, event.data);
+    return filtered.then(
+      (data) => (data === DROPPED ? this.next() : this.item(event.topic, data)),
+      // A filter that fails: the subscriber reads the changes itself
+      () => this.item(event.topic, { changed: [], deleted: [] }),
+    );
   }
 
-  /** The event with the number of events that the publisher dropped before it. */
-  private withDropped(event: Extract<EventItem, { type: "event" }>): EventItem {
-    if (this.dropped === 0) return event;
+  /**
+   * The item of the data of an event. It gets the next `seq`, and the number of events that the
+   * publisher dropped before it. A dropped event keeps its number, so the subscriber sees the gap.
+   */
+  private item(topic: string, data: unknown): Promise<IteratorResult<EventItem>> {
     const dropped = this.dropped;
     this.dropped = 0;
-    return { ...event, dropped };
+    this.seq += dropped;
+    const item: Extract<EventItem, { type: "event" }> = { type: "event", topic, data, seq: ++this.seq, ...(dropped > 0 && { dropped }) };
+    const rows = rowsOf(data);
+    if (!rows || (!this.admit && !rows.admit)) return Promise.resolve({ value: item, done: false });
+    // The rule of the rows of a topic of a collection gets the invocation of that topic (roadmap CLI-78)
+    const invocation = this.filters?.get(topic)?.invocation ?? this.invocation;
+    return admittedValue(data, this.admit, invocation).then((admitted): IteratorResult<EventItem> => ({ value: { ...item, data: admitted }, done: false }));
   }
 
   next(): Promise<IteratorResult<EventItem>> {
@@ -441,10 +510,15 @@ export class EventPublisher {
    * and the partition. Its events wait for the check. A refusal ends the subscription with its
    * error, for example `FORBIDDEN`. The promise ends when each check ends, and it does not reject.
    *
+   * The change can also have a scope (roadmap CLI-78): the collections or the partitions whose rows
+   * it touches. Then only the topics of the scope with a row filter get a `reset` hint and a new
+   * `admitsAll`. Each touched subscription still gets the checks of its start.
+   *
    * @param change - The subscriptions that the change touches. Without it, each open subscription gets a check.
+   * @param scope - The rows that the change touches. Without it, the change touches each topic.
    */
-  rightsChanged(change?: RightsChange): Promise<void> {
-    return this.rechecks.rightsChanged(change);
+  rightsChanged(change?: RightsChange, scope?: RightsScopes): Promise<void> {
+    return this.rechecks.rightsChanged(change, scope);
   }
 
   /**
@@ -459,9 +533,9 @@ export class EventPublisher {
    */
   private async route(topic: string, ctx: ProcedureContext): Promise<Route> {
     const target = collectionTopicTarget(topic, ctx.repository);
-    if (!target) return [topic, topic];
+    if (!target) return { topic, busTopic: topic };
     const partition = await partitionOfCall(ctx, target.collection, target.partition);
-    return [topic, collectionChangeTopic(target.collection, partition)];
+    return { topic, busTopic: collectionChangeTopic(target.collection, partition), collection: target.collection, partition, requested: target.partition };
   }
 
   /**
@@ -506,14 +580,30 @@ export class EventPublisher {
    * because the listener has the old partition.
    */
   private async readmit(routes: ReadonlyArray<Route>, ctx: ProcedureContext): Promise<void> {
-    this.admitTopics(routes.map(([topic]) => topic), ctx);
-    for (const [topic, busTopic] of routes) {
-      if ((await this.route(topic, ctx))[1] !== busTopic) {
+    this.admitTopics(routes.map(({ topic }) => topic), ctx);
+    for (const { topic, busTopic } of routes) {
+      if ((await this.route(topic, ctx)).busTopic !== busTopic) {
         throw new InvocationError("FORBIDDEN", `The partition of the topic "${topic}" changed, so the subscription ends`, ctx.path, "partition-not-allowed");
       }
     }
   }
 
+  /**
+   * The row filters of the topics of the collections of a subscription (roadmap CLI-78). Each one
+   * gets the rules of its collection and the result of `admitsAll`.
+   */
+  private async filtersOf(routes: ReadonlyArray<Route>, ctx: ProcedureContext): Promise<Map<string, RowHintFilter>> {
+    const filters = new Map<string, RowHintFilter>();
+    for (const { topic, collection, partition, requested } of routes) {
+      if (collection === undefined) continue;
+      // The rules get an invocation of the collection and its partition, not the call of `events.subscribe`
+      const filter = new RowHintFilter(() => collectionRulesOf(ctx, collection), collectionInvocation(ctx.invocation, ctx, collection, requested), partition);
+      await filter.refresh();
+      filters.set(topic, filter);
+    }
+    return filters;
+  }
+
   /**
    * The stream of one subscription. The publisher examines each topic before it adds a listener:
    * the topic rule, the reads, `allow`, and the partition. A call with one bad topic makes no subscription.
@@ -523,10 +613,44 @@ export class EventPublisher {
     this.admitTopics(unique, ctx);
     const routes: Route[] = [];
     for (const topic of unique) routes.push(await this.route(topic, ctx));
-    const subscription = new TopicSubscription(this.bus, routes, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit, ctx.invocation);
+    const filters = await this.filtersOf(routes, ctx);
+    const subscription = new TopicSubscription(this.bus, routes, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit, ctx.invocation, filters);
     this.open.add(subscription);
+    // The marks of the topics with a row filter: the writes of these topics read the rows before them (roadmap CLI-78)
+    const marks = new Map<string, () => void>();
+    let ended = false;
+    const mark = (route: Route, mode: HintFilterMode): void => {
+      if (ended) return;
+      const marked = marks.get(route.topic);
+      if (mode === "pass") {
+        marked?.();
+        marks.delete(route.topic);
+      } else if (!marked) {
+        marks.set(route.topic, markFilteredTopic(this.bus, route.busTopic));
+      }
+    };
+    for (const route of routes) {
+      const filter = filters.get(route.topic);
+      if (filter) mark(route, filter.mode);
+    }
+    subscription.onEnd(() => {
+      ended = true;
+      for (const unmark of marks.values()) unmark();
+      marks.clear();
+    });
     // The same checks run again at a change of the rights and after the max age (roadmap CLI-44)
-    this.rechecks.watch(subscription, ctx.principal, () => this.readmit(routes, ctx));
+    this.rechecks.watch(subscription, ctx.principal, async (cause: RecheckCause, scope?: RightsScopes) => {
+      await this.readmit(routes, ctx);
+      // The rights can change the rows that the subscriber reads: a `reset` hint makes it read them again (roadmap CLI-78)
+      for (const route of routes) {
+        const filter = filters.get(route.topic);
+        if (!filter || !inScope(route, scope)) continue;
+        const before = filter.mode;
+        const after = await filter.refresh();
+        mark(route, after);
+        if (after !== before || (cause === "rights" && after === "filter")) subscription.reset(route.topic);
+      }
+    });
     return subscription.closeIfAborted();
   }
 }

package/src/events/recheck.ts

@@ -27,6 +27,24 @@ import type { Principal } from "../server/types.js";
  */
 export type RightsChange = string | ((principal: Principal | undefined) => boolean);
 
+/**
+ * The rows that a change of the rights touches (roadmap CLI-78): the rows of the collections and
+ * of the partitions of the scope. The partition is the partition after the resolver. Without a
+ * collection, the scope touches each collection. Without a partition, it touches each partition.
+ *
+ * - A string matches one name.
+ * - A test matches each name that it admits, for example each partition of a tenant. A test that
+ *   throws matches: a `reset` hint too many is safe, and a missing one is not.
+ * - A partition matches only a topic with a partition.
+ */
+export interface RightsScope {
+  readonly collection?: string | ((collection: string) => boolean) | undefined;
+  readonly partition?: string | ((partition: string) => boolean) | undefined;
+}
+
+/** One scope or a list of scopes of a change of the rights. A list touches the rows of each scope. */
+export type RightsScopes = RightsScope | readonly RightsScope[];
+
 /** The options of the re-check of the open subscriptions of a publisher (roadmap CLI-44). */
 export interface SubscriptionRecheck {
   /**
@@ -41,9 +59,12 @@ export interface SubscriptionRecheck {
    * removes the listener. Each call of the listener is a call of `rightsChanged()`: without a
    * change, each subscription gets a check.
    */
-  readonly rightsChanges?: ((listener: (change?: RightsChange) => void) => () => void) | undefined;
+  readonly rightsChanges?: ((listener: (change?: RightsChange, scope?: RightsScopes) => void) => () => void) | undefined;
 }
 
+/** The cause of a re-check: a change of the rights, or the max age. */
+export type RecheckCause = "rights" | "age";
+
 /** A subscription that the re-checks can hold and watch. */
 export interface RecheckedSubscription {
   /**
@@ -61,7 +82,7 @@ interface Watch {
   /** The timer of the max age, or undefined. */
   timer: Cancel | undefined;
   /** This function starts a check at once. The promise ends when the check ends. */
-  readonly recheck: () => Promise<void>;
+  readonly recheck: (cause: RecheckCause, scope?: RightsScopes) => Promise<void>;
 }
 
 /** True when the change touches a subscription of the principal. A test that throws touches it. */
@@ -76,10 +97,13 @@ function touches(change: RightsChange | undefined, principal: Principal | undefi
 }
 
 /** The promise of a check. A check that throws at once gives a rejected promise. */
-function started(check: () => Promise<void>): Promise<void> {
-  return new Promise<void>((resolve) => resolve(check()));
+function started(check: RecheckCheck, cause: RecheckCause, scope: RightsScopes | undefined): Promise<void> {
+  return new Promise<void>((resolve) => resolve(check(cause, scope)));
 }
 
+/** The check of a subscription. A check of a change of the rights can get the scope of the change. */
+type RecheckCheck = (cause: RecheckCause, scope?: RightsScopes) => Promise<void>;
+
 /**
  * The re-checks of the open subscriptions of one publisher (roadmap CLI-44). The publisher gives
  * each new subscription to `watch()`, with the check of its admission.
@@ -110,15 +134,16 @@ export class SubscriptionRechecks {
 
   /**
    * This function watches a subscription until it ends. A change of the rights of its principal
-   * and its max age start the check. The check must throw the refusal.
+   * and its max age start the check. The check gets the cause and the scope of the change. It must
+   * throw the refusal.
    */
-  watch(subscription: RecheckedSubscription, principal: Principal | undefined, check: () => Promise<void>): void {
+  watch(subscription: RecheckedSubscription, principal: Principal | undefined, check: RecheckCheck): void {
     const watch: Watch = {
       principal,
       timer: undefined,
-      recheck: () => {
+      recheck: (cause, scope) => {
         this.stopTimer(watch);
-        return subscription.hold(started(check)).then(() => {
+        return subscription.hold(started(check, cause, scope)).then(() => {
           // A check that passes gives the admission a new age
           if (this.watches.has(watch)) this.startTimer(watch);
         });
@@ -130,7 +155,7 @@ export class SubscriptionRechecks {
     this.startTimer(watch);
     if (this.source && !this.stopListening) {
       try {
-        this.stopListening = this.source((change) => void this.rightsChanged(change));
+        this.stopListening = this.source((change, scope) => void this.rightsChanged(change, scope));
       } catch (error) {
         // A source that cannot listen cannot tell a revocation: the subscription ends
         void subscription.hold(Promise.reject(error));
@@ -140,12 +165,12 @@ export class SubscriptionRechecks {
 
   /**
    * This function starts a check of each watched subscription that the change touches. The
-   * promise ends when each check ends.
+   * promise ends when each check ends. Each check gets the scope of the change.
    */
-  rightsChanged(change?: RightsChange): Promise<void> {
+  rightsChanged(change?: RightsChange, scope?: RightsScopes): Promise<void> {
     const checks: Array<Promise<void>> = [];
     for (const watch of [...this.watches]) {
-      if (touches(change, watch.principal)) checks.push(watch.recheck());
+      if (touches(change, watch.principal)) checks.push(watch.recheck("rights", scope));
     }
     return Promise.all(checks).then(() => undefined);
   }
@@ -166,7 +191,7 @@ export class SubscriptionRechecks {
     this.stopTimer(watch);
     const timer = this.clock.after(this.maxAgeMs, () => {
       if (watch.timer === timer) watch.timer = undefined;
-      void watch.recheck();
+      void watch.recheck("age");
     });
     // A check does not keep a Node process alive
     timer.unref?.();