@procedures/client 0.35.0 → 0.36.0

package/src/procedures/collection/admission.ts

@@ -4,8 +4,10 @@
  * `admission` of `createCollectionProcedures()` gives the rules as data:
  *
  * - `admit` examines each row `{ id, value }` that a read gives. It has the shape of `AdmitItem`,
- *   the output filter of a host. The change events with values give it the same rows for each
- *   subscriber, so the reads and the events obey one rule.
+ *   the output filter of a host. The publisher of the change events gives it the rows of each
+ *   event for each subscriber (roadmap CLI-78). Thus the reads and the events obey one rule.
+ * - `admitsAll` tells that `admit` admits each row of a partition for a call. The events of such a
+ *   subscriber then pass without the filter of each row.
  * - `guard` examines each write `{ op, id, doc, prev }` before the storage changes. A refused write
  *   gets `FORBIDDEN` with the reason `write-not-allowed`.
  * - `versionOf` gives the version of a stored item (roadmap CLI-55). With it, a guarded write
@@ -16,8 +18,11 @@
  * (`admittedStorage()`). Each read and each write of each procedure goes through this view.
  *
  * - A refused row is absent: `get` gives undefined, `has` gives false, and the lists, `size`,
- *   `find` and `changes` do not have it. A delta of `changes` puts the id of a refused row in
- *   `deleted`, so a copy of the caller drops it.
+ *   `find` and `changes` do not have it.
+ * - A delta of `changes` gives only ids that the caller can read (roadmap CLI-78). The view
+ *   does not know which rows the caller read before the delta. Thus a delta with a refused row or
+ *   with a deleted row becomes a full answer of the admitted rows. The copy of the caller then
+ *   drops each other row. When `admitsAll` admits the caller, the delta stays as it is.
  * - An error of `admit` fails the read. It does not hide the rows, so a sync does not delete them.
  * - The guard reads the stored item before the write. With `versionOf`, the write expects the
  *   version of that item (roadmap CLI-16). A change of another writer between the read and the
@@ -66,10 +71,23 @@ export type CollectionWriteGuard = (write: CollectionWrite, invocation: Invocati
 export interface CollectionAdmission {
   /**
    * The rule of the rows. It gets each row `{ id, value }` of a read and the invocation of the
-   * call, and it gives true to admit the row. The change events with values apply it for each
-   * subscriber, with the invocation of the subscription.
+   * call, and it gives true to admit the row. The publisher of the change events applies it to the
+   * rows of each event for each subscriber, with the invocation of the subscription (roadmap
+   * CLI-78). A subscriber gets only the ids of the rows that it can read.
    */
   admit?: AdmitItem | undefined;
+  /**
+   * This function tells that the rule `admit` admits each row of a partition for a call (roadmap
+   * CLI-78). It gets the invocation and the partition (undefined for the collection without a
+   * partition). True: the change events reach the subscriber without the filter of each row, as
+   * before CLI-78. The publisher asks at the start of a subscription and at each re-check.
+   *
+   * - Give true only when `admit` admits each row of the partition. Else the subscriber gets the
+   *   ids of rows that it cannot read.
+   * - An error gives false.
+   * - Without it, the publisher examines each row of each event for each subscriber.
+   */
+  admitsAll?: ((invocation: Invocation, partition: string | undefined) => boolean | Promise<boolean>) | undefined;
   /** The guard of each `set`, `patch` and `delete`, also of the batches and of `clear`. */
   guard?: CollectionWriteGuard | undefined;
   /**
@@ -154,8 +172,9 @@ function withoutValue(conflict: VersionConflict): VersionConflict {
  * @param storage - The storage of the call: of the collection, or of its partition
  * @param admission - The rules of the collection
  * @param ctx - The context of the call. The rules get its invocation.
+ * @param partition - The partition of the call. `admitsAll` gets it.
  */
-export function admittedStorage<T>(storage: CollectionStorage<T>, admission: CollectionAdmission | undefined, ctx: ProcedureContext): CollectionStorage<T> {
+export function admittedStorage<T>(storage: CollectionStorage<T>, admission: CollectionAdmission | undefined, ctx: ProcedureContext, partition?: string): CollectionStorage<T> {
   const admit = admission?.admit;
   const guard = admission?.guard;
   if (!admit && !guard) return storage;
@@ -234,6 +253,23 @@ export function admittedStorage<T>(storage: CollectionStorage<T>, admission: Col
     return new VersionConflictError(kept, error instanceof Error ? error.message : undefined);
   };
 
+  /** This function tells if `admitsAll` admits the caller. An error gives false. */
+  const readsAll = async (): Promise<boolean> => {
+    if (!admission?.admitsAll || invocation === undefined) return false;
+    try {
+      return (await admission.admitsAll(invocation, partition)) === true;
+    } catch {
+      return false;
+    }
+  };
+  /** The full answer of `changes`: each admitted row, at a version that the rows include. */
+  const fullAnswer = async (): Promise<StorageChanges<T>> => {
+    const all = await storage.getChangesSince!(undefined);
+    if (all.full) return { version: all.version, full: true, changed: await admitted(all.changed), deleted: [] };
+    // A log that does not give all rows: the rows, read after the version, include that version
+    return { version: all.version, full: true, changed: await entries(), deleted: [] };
+  };
+
   const view: CollectionStorage<T> = {
     async get(id) {
       const value = await storage.get(id);
@@ -322,10 +358,15 @@ export function admittedStorage<T>(storage: CollectionStorage<T>, admission: Col
       if (!admit) return changes;
       const changed = await admitted(changes.changed);
       if (changes.full) return { ...changes, changed };
-      // A delta: the copy of the caller drops each refused row
       const kept = new Set(changed.map(([id]) => id));
       const refused = changes.changed.filter(([id]) => !kept.has(id)).map(([id]) => id);
-      return { ...changes, changed, deleted: [...changes.deleted, ...refused] };
+      // A delta of admitted rows only gives no id that the caller cannot read
+      if (refused.length === 0 && changes.deleted.length === 0) return { ...changes, changed };
+      // A caller that reads each row of the partition gets the delta as before (roadmap CLI-78)
+      if (await readsAll()) return { ...changes, changed, deleted: [...changes.deleted, ...refused] };
+      // The view does not know if the caller read a refused or a deleted row before. A full answer
+      // gives no other id, and the copy of the caller drops each row that it cannot read.
+      return fullAnswer();
     };
   }
   if (storage.query) {

package/src/procedures/collection/changes.ts

@@ -22,12 +22,18 @@
  *   listens to the topic, the procedures publish nothing, and the chain stops.
  * - The publishes of one storage and one topic run one at a time, in the order of the writes. A
  *   write resolves after its event is on the bus. A failed publish never fails the write.
+ * - With the rule `admission.admit`, the publisher filters the ids of each event for each
+ *   subscriber (roadmap CLI-78, `hint-filter.ts`). The event carries the rows after the changes,
+ *   from the change log. While a subscriber has a filter, each write first reads the rows before
+ *   it (`getBatch`). Thus a row that leaves the rule reaches that subscriber as a delete.
  */
 
 import type { EventBus } from "../../events/types.js";
 import { withRows } from "../../events/rows.js";
 import type { AdmitItem } from "../invoke.js";
 import type { StorageChanges } from "./storage.js";
+import type { CollectionAdmission } from "./admission.js";
+import { hasFilteredSubscriber, withHintImages, type HintRowState } from "./hint-filter.js";
 import type { RepositoryProvider } from "../types.js";
 import { collectionTopicTarget } from "./topic.js";
 
@@ -52,8 +58,23 @@ export interface CollectionChangeEvent {
    * Without the option, the event has no values: read them with `changes`.
    */
   readonly values?: ReadonlyArray<{ readonly id: string; readonly value: unknown }> | undefined;
-  /** With the option `values`: the changed ids whose values the filter refused. Read them with `changes`. */
+  /**
+   * With the option `values`: the changed ids whose values the output filter of the host refused.
+   * Read them with `changes`. A row that the rule of the rows refuses is not in the event (roadmap CLI-78).
+   */
   readonly withheld?: readonly string[] | undefined;
+  /**
+   * The version of each changed item, as `versionOf(id)` of the storage gives it (roadmap CLI-77).
+   * A publisher that knows the versions sets it, for example `watchStorageChanges()` of
+   * `@procedures/mongo`. Without it, read the versions with `changes`. A deleted id has no version.
+   */
+  readonly versions?: ReadonlyArray<{ readonly id: string; readonly version: string }> | undefined;
+  /**
+   * True: read the collection in full, with `changes` and no `since` (roadmap CLI-77). A publisher
+   * sets it when it cannot tell what changed, for example `watchStorageChanges()` of
+   * `@procedures/mongo` after it lost its resume token. A read since the cursor can miss changes.
+   */
+  readonly reset?: boolean | undefined;
   /** The origin of the writes, when one origin made all the changes of the event. */
   readonly origin?: string | undefined;
 }
@@ -78,6 +99,8 @@ export function collectionTopicReads(topic: string, repository?: RepositoryProvi
 /** The part of a storage that the change events read. */
 interface ChangeLog {
   getChangesSince?(since?: string): Promise<StorageChanges<unknown>>;
+  /** The stored items of the ids: the rows before a write, for the row filter of the subscribers (roadmap CLI-78). */
+  getBatch?(ids: string[]): Promise<Map<string, unknown>>;
 }
 
 /** A write that ended, and that no event told yet. */
@@ -87,6 +110,8 @@ interface EndedWrite {
   readonly origin: string | undefined;
   /** True when the chain had a version when the write started. */
   readonly anchored: boolean;
+  /** The stored items of the ids before the write, when a subscriber has a row filter (roadmap CLI-78). */
+  before?: ReadonlyMap<string, unknown> | undefined;
 }
 
 /** The chain of the events of one storage and one topic. */
@@ -140,7 +165,8 @@ function hint(version: string | undefined, origin: string | undefined): Collecti
 /**
  * The event of a delta with the values of the changed items. Each row `{ id, value }` passes the
  * output filter of each subscriber and the rule of the rows of the collection, and a refused row
- * goes from `values` to `withheld`.
+ * goes from `values` to `withheld`. The row filter of a subscriber (roadmap CLI-78) first takes the
+ * rows that the rule refuses out of the event. Thus only the output filter of the host withholds a row.
  */
 function withValues(event: CollectionChangeEvent, entries: ReadonlyArray<{ readonly id: string; readonly value: unknown }>, admit: AdmitItem | undefined): CollectionChangeEvent {
   return withRows(
@@ -162,7 +188,8 @@ function withValues(event: CollectionChangeEvent, entries: ReadonlyArray<{ reado
 }
 
 /** One publish: the event of the writes that ended since the last publish. */
-async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, topic: string, values: boolean, admit: AdmitItem | undefined): Promise<void> {
+async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, topic: string, values: boolean, admission: CollectionAdmission | undefined): Promise<void> {
+  const admit = admission?.admit;
   const writes = chain.ended.splice(0);
   // An earlier publish told these writes
   if (writes.length === 0) return;
@@ -199,7 +226,33 @@ async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, to
     deleted: changes.deleted,
     ...(origin !== undefined && { origin }),
   };
-  bus.emit(topic, values ? withValues(event, changes.changed.map(([id, value]) => ({ id, value })), admit) : event);
+  const out = values ? withValues(event, changes.changed.map(([id, value]) => ({ id, value })), admit) : event;
+  // The rows of the event for the row filter of each subscriber (roadmap CLI-78)
+  bus.emit(topic, admit ? withHintImages(out, { after: afterOf(changes), before: beforeOf(writes), admission: admission! }) : out);
+}
+
+/** The rows after the changes, from the change log: a changed id has its item, a deleted id has none. */
+function afterOf(changes: StorageChanges<unknown>): Map<string, HintRowState> {
+  const after = new Map<string, HintRowState>();
+  for (const id of changes.deleted) after.set(id, { found: false });
+  for (const [id, value] of changes.changed) after.set(id, { found: true, value });
+  return after;
+}
+
+/**
+ * The rows before the changes: for each id, the read of the first write that read it. An id
+ * without a read is unknown, so the filter of a subscriber makes a hint without ids for it.
+ */
+function beforeOf(writes: readonly EndedWrite[]): Map<string, HintRowState> {
+  const before = new Map<string, HintRowState>();
+  for (const write of writes) {
+    if (!write.before || write.ids === "*") continue;
+    for (const id of write.ids) {
+      if (before.has(id)) continue;
+      before.set(id, write.before.has(id) ? { found: true, value: write.before.get(id) } : { found: false });
+    }
+  }
+  return before;
 }
 
 /**
@@ -215,7 +268,7 @@ async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, to
  * @param origin - The origin of the write
  * @param write - The write
  * @param values - True: the events carry the values, for the output filter of each subscriber
- * @param admit - The rule of the rows of the collection: each subscriber applies it to the values (roadmap CLI-41)
+ * @param admission - The rules of the rows of the collection: each subscriber applies `admit` to the rows of the event (roadmap CLI-41, CLI-78)
  */
 export async function writeWithChangeEvent<R>(
   bus: EventBus | undefined,
@@ -225,16 +278,24 @@ export async function writeWithChangeEvent<R>(
   origin: string | undefined,
   write: () => Promise<R>,
   values = false,
-  admit?: AdmitItem,
+  admission?: CollectionAdmission,
 ): Promise<R> {
   if (bus === undefined || topic === undefined) return write();
   const chain = chainOf(storage, topic);
   const started: EndedWrite = { ids, origin, anchored: chain.anchor !== undefined };
+  // A subscriber with a row filter: the rows before the write tell it which rows left the rule (roadmap CLI-78)
+  if (admission?.admit && ids !== "*" && ids.length > 0 && storage.getBatch && hasFilteredSubscriber(bus, topic) && bus.hasSubscribers(topic)) {
+    try {
+      started.before = await storage.getBatch([...ids]);
+    } catch {
+      // Without the rows before the write, the filter of a subscriber makes a hint without ids
+    }
+  }
   try {
     return await write();
   } finally {
     chain.ended.push(started);
-    const run = chain.tail.then(() => publish(chain, storage, bus, topic, values, admit));
+    const run = chain.tail.then(() => publish(chain, storage, bus, topic, values, admission));
     chain.tail = run.catch(() => undefined);
     await chain.tail;
   }

package/src/procedures/collection/hint-filter.ts

@@ -0,0 +1,376 @@
+/**
+ * The row filter of the change events of a collection (roadmap CLI-78).
+ *
+ * A change event names the ids that changed. Before CLI-78, each subscriber of a topic got all the
+ * ids, so only a principal that reads the whole partition could subscribe. With CLI-78, the publisher
+ * filters each event row by row for each subscriber, with the rule of the rows of the collection
+ * (`admission.admit`). The reads apply the same rule (`admittedStorage()`).
+ *
+ * - The rule comes from the registry of the call: `createCollectionProcedures()` puts its rules on
+ *   the metadata of its procedures. An event can also carry the rules in its images.
+ * - The rule examines the rows of the images of the event (`withHintImages()`): the row after the
+ *   changes, and the row before them. The publisher does not read a storage.
+ * - A changed row that the rule admits stays in `changed`. A changed row that the rule refuses, or
+ *   a deleted row, goes to `deleted` only when the rule admitted its row before the changes.
+ *   Otherwise the subscriber does not get its id.
+ * - When an image is missing, or the rule fails, the subscriber gets a hint without ids and
+ *   without `since`. It then reads the changes, through the rule of the reads.
+ * - An event without ids, and a `reset` event, pass without ids.
+ * - When the subscriber gets no id of an event, it gets no event. The `since` of its next event is
+ *   then the `version` of the last event that it got. Thus it applies the next delta without a read.
+ * - `admission.admitsAll` tells that a subscriber reads each row of its partition. Its events then
+ *   pass as before CLI-78, with no cost.
+ */
+import type { Invocation } from "../invoke.js";
+import type { AnyProcedure, ProcedureContext } from "../types.js";
+import type { CollectionAdmission } from "./admission.js";
+import { withRows } from "../../events/rows.js";
+import type { EventBus } from "../../events/types.js";
+
+/** The state of one row in an image: the stored item, or no item. */
+export type HintRowState = { readonly found: true; readonly value: unknown } | { readonly found: false };
+
+/**
+ * The rows of a change event, for the row filter of each subscriber (roadmap CLI-78). A missing id
+ * in a map is unknown. The images are on a symbol key, so they stay in this process: JSON does
+ * not take them.
+ */
+export interface HintImages {
+  /** The rows after the changes of the event, by id. */
+  readonly after?: ReadonlyMap<string, HintRowState> | undefined;
+  /** The rows before the changes of the event (at its `since`), by id. */
+  readonly before?: ReadonlyMap<string, HintRowState> | undefined;
+  /**
+   * The rules of the rows of the collection. The publisher uses the rules from its registry
+   * first, and these rules only when the registry has none.
+   */
+  readonly admission?: CollectionAdmission | undefined;
+}
+
+/** The key of the images of an event. */
+const IMAGES: unique symbol = Symbol.for("procedures.hintImages");
+
+/**
+ * This function gives the event with its images, for the row filter of each subscriber (roadmap
+ * CLI-78). The images are not enumerable: a copy or a comparison of the event does not see them.
+ */
+export function withHintImages<T extends object>(event: T, images: HintImages): T {
+  return Object.defineProperty(event, IMAGES, { value: images, enumerable: false, configurable: true });
+}
+
+/** The images of an event, or undefined for an event without images. */
+export function hintImagesOf(event: unknown): HintImages | undefined {
+  if (typeof event !== "object" || event === null) return undefined;
+  const images = (event as { [IMAGES]?: unknown })[IMAGES];
+  return typeof images === "object" && images !== null ? (images as HintImages) : undefined;
+}
+
+/** The key of the rules of a collection on the metadata of its procedures. */
+const RULES: unique symbol = Symbol.for("procedures.collectionRules");
+
+/**
+ * This function puts the rules of a collection on the metadata of its procedures, so the publisher
+ * of the events finds them in the registry. The key is not enumerable.
+ */
+export function withCollectionRules(procedures: AnyProcedure[], admission: CollectionAdmission | undefined): AnyProcedure[] {
+  for (const procedure of procedures) {
+    const metadata = procedure.metadata as object | undefined;
+    if (metadata) Object.defineProperty(metadata, RULES, { value: { admission }, enumerable: false, configurable: true });
+  }
+  return procedures;
+}
+
+/**
+ * The rules of a collection in the registry of a call. It gives the rules, or `null` for a
+ * collection without rules. It gives undefined when the registry does not know the procedures.
+ */
+export function collectionRulesOf(ctx: ProcedureContext, collection: string): CollectionAdmission | null | undefined {
+  const registry = ctx.registry;
+  if (!registry) return undefined;
+  for (const operation of ["changes", "get"]) {
+    const metadata = registry.get(["collections", collection, operation])?.metadata as { [RULES]?: { admission?: CollectionAdmission | undefined } } | undefined;
+    const rules = metadata?.[RULES];
+    if (rules) return rules.admission ?? null;
+  }
+  return undefined;
+}
+
+/**
+ * The invocation that the rules of a collection get for the events of one topic (roadmap CLI-78).
+ * It has the principal, the capability, the metadata and the signal of the subscription. Its path
+ * is the path of `changes` of the collection, and its input has the partition of the topic. Thus
+ * a rule that reads `invocation.input.partition` sees the same input as in a read of the topic.
+ *
+ * @param base - The invocation of the subscription
+ * @param ctx - The context of the subscription. Its registry gives the procedure of `changes`.
+ * @param collection - The collection of the topic
+ * @param partition - The partition that the topic names, before the resolver
+ */
+export function collectionInvocation(base: Invocation | undefined, ctx: ProcedureContext, collection: string, partition: string | undefined): Invocation | undefined {
+  if (base === undefined) return undefined;
+  const procedure = ctx.registry?.get(["collections", collection, "changes"]);
+  return {
+    ...base,
+    ...(procedure !== undefined && { procedure, path: procedure.path }),
+    input: partition === undefined ? {} : { partition },
+  };
+}
+
+/** The subscriptions with a row filter, by bus and by topic: the writes read the rows before them only for these. */
+const FILTERED = new WeakMap<object, Map<string, number>>();
+
+/** The key of the bus under a view of a bus (`withEventBusSignal()`). */
+const BASE_BUS = Symbol.for("procedures.baseBus");
+
+/** The bus under a view of a bus, or the bus itself. */
+function baseOf(bus: EventBus): object {
+  return ((bus as { [BASE_BUS]?: EventBus })[BASE_BUS] as object | undefined) ?? bus;
+}
+
+/**
+ * This function marks a topic of a bus: a subscription of the topic has a row filter. It gives the
+ * function that removes the mark. A second call of that function does nothing.
+ */
+export function markFilteredTopic(bus: EventBus, topic: string): () => void {
+  const base = baseOf(bus);
+  let topics = FILTERED.get(base);
+  if (!topics) {
+    topics = new Map();
+    FILTERED.set(base, topics);
+  }
+  topics.set(topic, (topics.get(topic) ?? 0) + 1);
+  let marked = true;
+  return () => {
+    if (!marked) return;
+    marked = false;
+    const count = (topics.get(topic) ?? 1) - 1;
+    if (count > 0) topics.set(topic, count);
+    else topics.delete(topic);
+  };
+}
+
+/** True when a subscription of the topic of the bus has a row filter. */
+export function hasFilteredSubscriber(bus: EventBus, topic: string): boolean {
+  return (FILTERED.get(baseOf(bus))?.get(topic) ?? 0) > 0;
+}
+
+/** The result of the filter for an event that the subscriber does not get. */
+export const DROPPED: unique symbol = Symbol("procedures.droppedHint");
+
+/**
+ * The mode of a filter. `pass` gives each event as before CLI-78, and `filter` examines each row.
+ * `unknown` uses the rules of the images of each event.
+ */
+export type HintFilterMode = "pass" | "filter" | "unknown";
+
+/** The fields of a change event that the filter reads. */
+interface ChangeEventShape {
+  readonly since?: unknown;
+  readonly version?: unknown;
+  readonly changed: readonly string[];
+  readonly deleted: readonly string[];
+  readonly values?: ReadonlyArray<{ readonly id: string; readonly value: unknown }> | undefined;
+  readonly versions?: ReadonlyArray<{ readonly id: string; readonly version: string }> | undefined;
+  readonly reset?: unknown;
+  readonly origin?: unknown;
+}
+
+/** True for a value with the shape of a change event: the arrays `changed` and `deleted`. */
+function isChangeEvent(data: unknown): data is ChangeEventShape {
+  if (typeof data !== "object" || data === null) return false;
+  const event = data as { changed?: unknown; deleted?: unknown };
+  return Array.isArray(event.changed) && Array.isArray(event.deleted);
+}
+
+/** The fields `version` and `origin` of an event, when they are strings. */
+function headOf(event: ChangeEventShape): { version?: string; origin?: string } {
+  return {
+    ...(typeof event.version === "string" && { version: event.version }),
+    ...(typeof event.origin === "string" && { origin: event.origin }),
+  };
+}
+
+/** What the rule tells of one row: admitted, refused, or unknown (no image, or an error). */
+type Verdict = boolean | undefined;
+
+/** This function does nothing: the end of a filter that failed. */
+function ignore(): void {}
+
+/**
+ * The row filter of one topic of one subscription (roadmap CLI-78). The publisher gives each event
+ * of the topic to `apply()`, one at a time, in the order of the bus.
+ */
+export class RowHintFilter {
+  /** The rules from the registry: undefined when the registry does not know the collection. */
+  private rules: CollectionAdmission | null | undefined;
+  /** The result of `admitsAll` for one set of rules. */
+  private all: { readonly admission: CollectionAdmission; readonly value: boolean } | undefined;
+  /** The `version` of the last event of the chain, also of an event that the subscriber did not get. */
+  private head: string | undefined;
+  /** The `since` that the next event of the chain gets: the `version` of the last event that the subscriber got. */
+  private base: string | undefined;
+  /** The filters, one at a time. */
+  private tail: Promise<unknown> = Promise.resolve();
+
+  constructor(
+    /** The rules of the collection from the registry of the call. */
+    private readonly lookup: () => CollectionAdmission | null | undefined,
+    /** The invocation of the topic (`collectionInvocation()`): the rules get it. */
+    readonly invocation: Invocation | undefined,
+    /** The partition of the topic: `admitsAll` gets it. */
+    private readonly partition: string | undefined,
+  ) {
+    this.rules = lookup();
+  }
+
+  /** The mode of the filter, from the rules and from the last result of `admitsAll`. */
+  get mode(): HintFilterMode {
+    const rules = this.rules;
+    if (rules === undefined) return "unknown";
+    if (rules === null || !rules.admit) return "pass";
+    return this.all?.admission === rules && this.all.value ? "pass" : "filter";
+  }
+
+  /**
+   * This function reads the rules again and asks `admitsAll` again: at the start of the
+   * subscription and at each re-check (roadmap CLI-44). It gives the new mode.
+   */
+  async refresh(): Promise<HintFilterMode> {
+    this.rules = this.lookup();
+    this.all = undefined;
+    if (this.rules?.admit) await this.admitsAll(this.rules);
+    return this.mode;
+  }
+
+  /** This function forgets the chain: the next event keeps its own `since`. */
+  forget(): void {
+    this.head = undefined;
+    this.base = undefined;
+  }
+
+  /**
+   * The event for the subscriber. It gives undefined when the event passes as it is (no wait).
+   * Otherwise it gives a promise of the event for the subscriber, or of `DROPPED` for no event.
+   */
+  apply(data: unknown): Promise<unknown> | undefined {
+    if (!isChangeEvent(data)) return undefined;
+    const mode = this.mode;
+    if (mode === "pass") return undefined;
+    const admission = this.rules ?? hintImagesOf(data)?.admission;
+    if (!admission?.admit) return undefined;
+    const run = this.tail.then(() => this.filter(data, admission));
+    this.tail = run.catch(ignore);
+    return run;
+  }
+
+  /** The result of `admitsAll` for a set of rules. An error gives false. */
+  private async admitsAll(admission: CollectionAdmission): Promise<boolean> {
+    if (this.all?.admission === admission) return this.all.value;
+    let value = false;
+    const invocation = this.invocation;
+    if (admission.admitsAll && invocation) {
+      try {
+        value = (await admission.admitsAll(invocation, this.partition)) === true;
+      } catch {
+        value = false;
+      }
+    }
+    this.all = { admission, value };
+    return value;
+  }
+
+  /** The filter of one event with the rule of the rows. */
+  private async filter(event: ChangeEventShape, admission: CollectionAdmission): Promise<unknown> {
+    // Rules from the images of an event: the subscriber can read each row
+    if (await this.admitsAll(admission)) return event;
+    if (event.reset === true) {
+      this.forget();
+      return { ...headOf(event), changed: [], deleted: [], reset: true };
+    }
+    const since = typeof event.since === "string" ? event.since : undefined;
+    if (event.changed.length === 0 && event.deleted.length === 0) {
+      if (since === undefined) {
+        // A hint: the subscriber reads the changes through the rule of the reads
+        this.forget();
+        return { ...headOf(event), changed: [], deleted: [] };
+      }
+      return this.skip(since, event);
+    }
+    const admit = admission.admit!;
+    const invocation = this.invocation;
+    const images = hintImagesOf(event);
+    const verdict = async (id: string, state: HintRowState | undefined): Promise<Verdict> => {
+      if (state === undefined) return undefined;
+      if (!state.found || invocation === undefined) return false;
+      try {
+        return (await admit({ id, value: state.value }, invocation)) === true;
+      } catch {
+        return undefined;
+      }
+    };
+    const before = (id: string): Promise<Verdict> => verdict(id, images?.before?.get(id));
+    const changed = await Promise.all(
+      event.changed.map(async (id): Promise<"changed" | "deleted" | "none" | undefined> => {
+        const now = await verdict(id, images?.after?.get(id));
+        if (now === true) return "changed";
+        if (now === undefined) return undefined;
+        // The row left the rule, or it has no item: a delete for a subscriber that had it
+        const was = await before(id);
+        return was === undefined ? undefined : was ? "deleted" : "none";
+      }),
+    );
+    const deleted = await Promise.all(event.deleted.map(before));
+    if (changed.includes(undefined) || deleted.includes(undefined)) {
+      // The filter cannot tell the rows: the subscriber reads the changes through the rule of the reads
+      this.forget();
+      return { ...headOf(event), changed: [], deleted: [] };
+    }
+    const visible = event.changed.filter((_, index) => changed[index] === "changed");
+    const gone = [...event.changed.filter((_, index) => changed[index] === "deleted"), ...event.deleted.filter((_, index) => deleted[index] === true)];
+    if (visible.length === 0 && gone.length === 0) {
+      if (since === undefined) return DROPPED;
+      return this.skip(since, event);
+    }
+    const kept = new Set(visible);
+    const chained = since === undefined ? undefined : since === this.head ? this.base : since;
+    if (since !== undefined && typeof event.version === "string") {
+      this.head = event.version;
+      this.base = event.version;
+    } else {
+      this.forget();
+    }
+    const out = {
+      ...(chained !== undefined && { since: chained }),
+      ...(typeof event.version === "string" && { version: event.version }),
+      changed: visible,
+      deleted: gone,
+      ...(event.versions && { versions: event.versions.filter(({ id }) => kept.has(id)) }),
+      ...(typeof event.origin === "string" && { origin: event.origin }),
+    };
+    if (!event.values) return out;
+    const values = event.values.filter(({ id }) => kept.has(id));
+    // The rows pass the output filter of the host for the subscriber, as before
+    return withRows(
+      { ...out, values },
+      {
+        rows: values,
+        keep: (admitted) => {
+          const withheld = values.filter((_, index) => !admitted[index]).map(({ id }) => id);
+          return { ...out, values: values.filter((_, index) => admitted[index]), ...(withheld.length > 0 && { withheld }) };
+        },
+      },
+    );
+  }
+
+  /** An event of the chain that the subscriber does not get: the next event keeps the `since` of the last one. */
+  private skip(since: string, event: ChangeEventShape): typeof DROPPED {
+    const chained = since === this.head ? this.base : since;
+    if (typeof event.version === "string" && chained !== undefined) {
+      this.head = event.version;
+      this.base = chained;
+    } else {
+      this.forget();
+    }
+    return DROPPED;
+  }
+}

package/src/procedures/collection/index.ts

@@ -81,6 +81,9 @@ export type { CollectionPartitions, PartitionInput, PartitionResolver } from "./
 // The rules of the rows of a collection: a filter of the reads and a guard of the writes (roadmap CLI-41)
 export { admittedStorage, admitsRow } from "./admission.js";
 export type { CollectionAdmission, CollectionRow, CollectionWrite, CollectionWriteGuard } from "./admission.js";
+// The images of the rows of a change event, for the row filter of each subscriber (roadmap CLI-78)
+export { withHintImages, hintImagesOf } from "./hint-filter.js";
+export type { HintImages, HintRowState } from "./hint-filter.js";
 
 // The storage interface of the core (the shape of client-collections' CollectionStorage)
 export type {