@procedures/client 0.14.0 → 0.15.0

package/src/adapters/http/server/handler.ts

@@ -29,6 +29,7 @@ import { ms, type Duration } from "../../../duration.js";
 import { NDJSON_MEDIA_TYPE as NDJSON, defaultNdjsonError as errorOf, keepAliveMsOf, writeNdjsonStream } from "./ndjson.js";
 import { applyCors, corsOrigins, corsPolicy, type CorsOptions, type CorsPolicy } from "./cors.js";
 import { urlAddressing, type Addressing } from "./addressing.js";
+import { BodyError, readJsonBody } from "./body.js";
 import { NARROWING_METADATA_KEY, addNarrowing } from "../../../procedures/narrowing.js";
 
 /** The parts of a request that a URL strategy of `procedureHandler` reads. */
@@ -71,7 +72,9 @@ export interface ProcedureHandlerOptions extends BrowserGuardOptions {
   readonly addressing?: Addressing | undefined;
   /**
    * The CORS headers of the requests on the path. `true` uses the defaults: each origin, without
-   * credentials. The permitted origins of the browser checks follow the CORS origins.
+   * credentials. The permitted origins of the browser checks follow the CORS origins. An origin
+   * that the CORS does not permit gets no `Access-Control-*` header. With a list or a function of
+   * origins, each response gets `Vary: Origin`.
    * @default false
    */
   readonly cors?: boolean | CorsOptions | undefined;
@@ -163,16 +166,6 @@ export interface HandlerCompat {
   readonly face?: { readonly name: string; readonly originOption: string } | undefined;
 }
 
-/** The error of a request body or of a header that the handler cannot read. */
-class BodyError extends Error {
-  constructor(
-    message: string,
-    readonly httpStatus: number
-  ) {
-    super(message);
-  }
-}
-
 /** True when a stream response has no end (`STREAM_METADATA_KEY` of procedure-server.ts). */
 function isUnboundedStream(response: { metadata?: Record<string, unknown> | undefined }): boolean {
   return response.metadata?.["stream"] === "unbounded";
@@ -295,8 +288,9 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
   const clock = options.clock ?? realClock;
   const corsOptions: CorsOptions | undefined = options.cors === true ? {} : options.cors === false ? undefined : options.cors;
   // A list of origins or a function: the default sends the credentials. "*" with credentials is invalid.
+  // An origin that is not permitted gets no CORS header, and each response still varies by the origin (CLI-56)
   const cors: CorsPolicy | undefined =
-    corsOptions === undefined || compat.corsOutside ? undefined : corsPolicy(corsOptions, (corsOptions.origin ?? "*") !== "*");
+    corsOptions === undefined || compat.corsOutside ? undefined : { ...corsPolicy(corsOptions, (corsOptions.origin ?? "*") !== "*"), permittedOnly: true };
   const guard: BrowserGuardOptions = {
     allowedOrigins: options.allowedOrigins ?? corsOrigins(corsOptions),
     allowedHosts: options.allowedHosts,
@@ -353,26 +347,7 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
    * The request body. A body parser of a framework (`express.json({ strict: false })`) gives
    * `req.body`. Without one, the handler reads the JSON body itself (deep dive TRN-10).
    */
-  const readBody = async (req: IncomingMessage): Promise<unknown> => {
-    const parsed = (req as { body?: unknown }).body;
-    if (parsed !== undefined) return parsed;
-    if (req.method === "GET" || req.method === "HEAD" || req.readableEnded) return undefined;
-    const chunks: Buffer[] = [];
-    let size = 0;
-    for await (const chunk of req as AsyncIterable<Buffer | string>) {
-      const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
-      size += buffer.length;
-      if (size > bodyLimit) throw new BodyError(`The request body is larger than ${bodyLimit} bytes`, 413);
-      chunks.push(buffer);
-    }
-    const text = Buffer.concat(chunks).toString("utf8");
-    if (text.trim() === "") return undefined;
-    try {
-      return JSON.parse(text) as unknown;
-    } catch {
-      throw new BodyError("The request body is not valid JSON", 400);
-    }
-  };
+  const readBody = (req: IncomingMessage): Promise<unknown> => readJsonBody(req, bodyLimit);
 
   /**
    * This function converts an HTTP request to a `ServerRequest`, or gives null when the addressing
@@ -486,12 +461,15 @@ export function createProcedureHandler(server: RequestHandler, options: Procedur
     if (hasRetryAfter) res.setHeader("Retry-After", String(Math.ceil(retryAfterMs / 1000)));
     // The reason of a FORBIDDEN error travels on each face (roadmap R25)
     const reason = typeof metadata["reason"] === "string" ? metadata["reason"] : undefined;
+    // The current items of a VERSION_CONFLICT error (roadmap CLI-16)
+    const conflicts = Array.isArray(metadata["conflicts"]) ? metadata["conflicts"] : undefined;
     sendJson(res, httpStatusCode, {
       error: status.message,
       code: status.code,
       retryable: status.retryable,
       ...(hasRetryAfter ? { retryAfterMs } : {}),
       ...(reason !== undefined ? { reason } : {}),
+      ...(conflicts !== undefined ? { conflicts } : {}),
     });
   };
 

package/src/adapters/local/client/transport.ts

@@ -15,6 +15,7 @@ import { narrowCapability } from "../../../procedures/capability.js";
 import type { Capability, ClearanceOrder } from "../../../procedures/types.js";
 import { methodToPath } from "../../../server/method.js";
 import { errorCodeOf } from "../../../protocol.js";
+import { VERSION_CONFLICTS_METADATA_KEY, versionConflictsOf } from "../../../procedures/collection/precondition.js";
 import type { EventPublisher } from "../../../events/publisher.js";
 
 /** The value of `untilAborted` when the signal aborts first. */
@@ -236,6 +237,9 @@ export class LocalTransport implements Transport {
       const item = errorItem<TRes>(message.id, code, error instanceof Error ? error.message : "Unknown error");
       // The reason of a FORBIDDEN error travels on each face (roadmap R25)
       if (error instanceof InvocationError && error.reason) item.metadata = { reason: error.reason };
+      // The current items of a VERSION_CONFLICT error travel on each face (roadmap CLI-16)
+      const conflicts = versionConflictsOf(error);
+      if (conflicts !== undefined) item.metadata = { ...item.metadata, [VERSION_CONFLICTS_METADATA_KEY]: conflicts };
       yield item;
     }
   }

package/src/browser.ts

@@ -4,7 +4,8 @@
  * This module exports everything of the package except the Node server transports
  * (`HttpServerTransport` and `WebSocketServerTransport`, which use `http` and `ws`).
  * A browser bundle imports "@procedures/client/browser". The root entry point
- * re-exports this module and adds the server transports.
+ * re-exports this module. It also adds the server transports as deprecated aliases: their entry
+ * is "@procedures/client/node", and the next MINOR removes them from the root (CLI-6).
  *
  * Collections (maps, caches, collection storage) are in @procedures/collections.
  * The program store, the storage backends that need a Client (ApiStorage, HybridStorage) and the
@@ -130,6 +131,9 @@ export {
   PARTITION_PATTERN,
   collectionTopicPartition,
   collectionTopicTarget,
+  // The rules of the rows of a collection (roadmap CLI-41)
+  admittedStorage,
+  admitsRow,
   // The query language of the collection storages (roadmap CLI-14, CLI-34)
   DEFAULT_FIND_LIMIT,
   DEFAULT_QUERY_OPERATORS,
@@ -145,6 +149,17 @@ export {
   queryEntries,
   queryOptionsProblems,
   selectorProblems,
+  // The precondition of the collection writes (roadmap CLI-16)
+  MAX_EXPECTED_VERSION_LENGTH,
+  PRECONDITION_NOT_SUPPORTED,
+  VERSION_CONFLICTS_METADATA_KEY,
+  VersionConflictError,
+  asVersionConflictError,
+  isExpectedVersion,
+  preconditionNotSupported,
+  versionConflict,
+  versionConflicts,
+  versionConflictsOf,
   // Manual registration helpers
   registerModule,
   registerProcedures,
@@ -264,6 +279,11 @@ export type {
   StorageChanges,
   StorageMetadata,
   StorageWriteOptions,
+  StorageItemWriteOptions,
+  StorageBatchWriteOptions,
+  CurrentItem,
+  VersionConflict,
+  VersionOf,
   StorageSetChange,
   StorageDeleteChange,
   StorageClearChange,
@@ -281,6 +301,10 @@ export type {
   StorageQueryPolicy,
   CollectionProceduresOptions,
   CollectionChangeEventsOptions,
+  CollectionAdmission,
+  CollectionRow,
+  CollectionWrite,
+  CollectionWriteGuard,
   CollectionPartitions,
   PartitionInput,
   PartitionResolver,

package/src/client/client.ts

@@ -799,7 +799,7 @@ export class Client<TContext = {}> {
     // Yield payloads, handling errors
     for await (const item of responseStream) {
       if (item.status.type === "error" && this.throwOnError) {
-        throw new ClientError(item.status, item.id);
+        throw new ClientError(item.status, item.id, item.metadata);
       }
 
       yield item.payload;

package/src/client/errors/registry.ts

@@ -85,6 +85,7 @@ const PROTOCOL_CATEGORIES: Readonly<Record<ProtocolErrorCode, ErrorCategory>> =
   CONNECTION_NOT_FOUND: ErrorCategory.CLIENT,
   TOPIC_NOT_FOUND: ErrorCategory.CLIENT,
   TOPIC_CLEARED: ErrorCategory.CANCELLED,
+  VERSION_CONFLICT: ErrorCategory.CLIENT,
 };
 
 /**

package/src/client/types.ts

@@ -326,12 +326,20 @@ export type AccumulateContext<
  * Client error thrown when response has error status.
  */
 export class ClientError extends Error {
+  /**
+   * The metadata of the error response, for example `reason` of a `FORBIDDEN` error, or
+   * `conflicts` of a `VERSION_CONFLICT` error (roadmap CLI-16). Empty when the response has none.
+   */
+  public readonly metadata: Metadata;
+
   constructor(
     public readonly status: Extract<Status, { type: "error" }>,
     public readonly responseId: string,
+    metadata: Metadata = {},
   ) {
     super(status.message);
     this.name = "ClientError";
+    this.metadata = metadata;
   }
 
   get code(): string {

package/src/events/publisher.ts

@@ -26,7 +26,7 @@
 
 import { z } from "zod";
 import { createProcedure } from "../procedures/define.js";
-import { InvocationError } from "../procedures/invoke.js";
+import { InvocationError, type Invocation } from "../procedures/invoke.js";
 import { capabilityRefusal } from "../procedures/capability.js";
 import { collectionChangeTopic, collectionTopicReads } from "../procedures/collection/changes.js";
 import { collectionTopicTarget, partitionOfCall } from "../procedures/collection/partition.js";
@@ -177,6 +177,8 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     private readonly onClose: (subscription: TopicSubscription) => void,
     /** The output filter of the host for this subscriber: each row of a value passes it */
     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,
   ) {
     this.confirmation = { type: "subscribed", topics: routes.map(([topic]) => topic) };
     // Before, clear() removed the listeners, and the subscriber saw no end (EVENTS.md)
@@ -214,12 +216,13 @@ 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 subscriber gets only the admitted rows.
+   * host for this subscriber and the rule of the rows, and the subscriber gets only the admitted rows.
    */
   private deliver(event: Extract<EventItem, { type: "event" }>): Promise<IteratorResult<EventItem>> {
     const item = this.withDropped(event) as Extract<EventItem, { type: "event" }>;
-    if (!this.admit || !rowsOf(item.data)) return Promise.resolve({ value: item, done: false });
-    return admittedValue(item.data, this.admit).then((data): IteratorResult<EventItem> => ({ value: { ...item, data }, done: false }));
+    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 }));
   }
 
   /** The event with the number of events that the publisher dropped before it. */
@@ -407,7 +410,7 @@ export class EventPublisher {
     }
     const routes: Array<readonly [string, string]> = [];
     for (const topic of unique) routes.push([topic, await this.busTopic(topic, ctx)]);
-    const subscription = new TopicSubscription(this.bus, routes, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit);
+    const subscription = new TopicSubscription(this.bus, routes, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit, ctx.invocation);
     this.open.add(subscription);
     return subscription.closeIfAborted();
   }

package/src/events/rows.ts

@@ -7,7 +7,12 @@
  * reaches a subscriber only through the same filter as a read.
  *
  * The rows are on a symbol key, so they stay in this process: JSON does not take them.
+ *
+ * The rows can have a rule of their own too (`admit`): the rule of the rows of a collection
+ * (roadmap CLI-41). Each subscriber applies it after the filter of the host, with the invocation
+ * of its subscription.
  */
+import type { AdmitItem, Invocation } from "../procedures/invoke.js";
 
 /** The rows of a published value, and the function that makes the value of the admitted rows. */
 export interface PublishedRows {
@@ -15,6 +20,8 @@ export interface PublishedRows {
   readonly rows: readonly unknown[];
   /** This function gives the value for a subscriber: `admitted[i]` tells if row `i` stays. */
   keep(admitted: readonly boolean[]): unknown;
+  /** The rule of the rows themselves, with the invocation of the subscription. A row stays only when it gives true. */
+  readonly admit?: AdmitItem | undefined;
 }
 
 /** The key of the rows of a published value. */
@@ -36,13 +43,19 @@ export function rowsOf(value: unknown): PublishedRows | undefined {
 }
 
 /**
- * The value of a published value for one subscriber: each row passes the filter, and the value
- * keeps the admitted rows. An error of the filter refuses the row. Without rows or a filter, the
- * value stays as it is.
+ * The value of a published value for one subscriber: each row passes the filter of the host and
+ * the rule of the rows, and the value keeps the admitted rows. An error of a filter refuses the
+ * row. A rule of the rows refuses each row of a subscription without an invocation. Without rows,
+ * or without a filter and a rule, the value stays as it is.
  */
-export async function admittedValue(value: unknown, admit: ((item: unknown) => Promise<boolean>) | undefined): Promise<unknown> {
+export async function admittedValue(value: unknown, admit: ((item: unknown) => Promise<boolean>) | undefined, invocation?: Invocation): Promise<unknown> {
   const rows = rowsOf(value);
-  if (!rows || !admit) return value;
-  const admitted = await Promise.all(rows.rows.map((row) => admit(row).catch(() => false)));
+  const own = rows?.admit;
+  if (!rows || (!admit && !own)) return value;
+  const admits = async (row: unknown): Promise<boolean> => {
+    if (admit && !(await admit(row))) return false;
+    return !own || (invocation !== undefined && (await own(row, invocation)) === true);
+  };
+  const admitted = await Promise.all(rows.rows.map((row) => admits(row).catch(() => false)));
   return rows.keep(admitted);
 }

package/src/index.ts

@@ -5,7 +5,9 @@
  * and transport adapters.
  *
  * This entry point is for Node. It exports the browser-safe entry point
- * ("@procedures/client/browser") and the server transports, which use `http` and `ws`.
+ * ("@procedures/client/browser"). It also exports the server transports, which use `http` and
+ * `ws`, but these exports are deprecated (CLI-6 step 1). Their entry is "@procedures/client/node".
+ * The next MINOR removes them from this entry, so the root imports no `http` and no `ws`.
  *
  * The `WebSocketTransport` of this entry uses the global `WebSocket`, because some applications
  * bundle this entry for a browser. The Node entry "@procedures/client/node" has a
@@ -17,11 +19,11 @@ export * from "./browser.js";
 // ============================================================================
 // Server Transports (Node only)
 // ============================================================================
-export {
-  HttpServerTransport,
-  defaultServerUrlStrategy,
-  rpcServerUrlStrategy,
-} from "./server/index.js";
+export { defaultServerUrlStrategy, rpcServerUrlStrategy } from "./adapters/http/server/strategies.js";
+// Deprecated (CLI-6 step 1): import these from "@procedures/client/node". The next MINOR removes
+// them from the root. ./server/index.ts holds the deprecated aliases, so an editor marks each old
+// import, and each alias is the same class or type as the export of ./node.
+export { HttpServerTransport } from "./server/index.js";
 export type {
   HttpServerTransportOptions,
   HttpUrlStrategy,
@@ -29,6 +31,7 @@ export type {
 export { WebSocketServerTransport } from "./server/index.js";
 export { checkBrowserRequest, hasAmbientCredentials, isLoopbackHost, isLoopbackAddress, hostNameOf } from "./server/browser-guard.js";
 export type { BrowserGuardOptions, GuardedRequest, GuardResult } from "./server/browser-guard.js";
+// Deprecated (CLI-6 step 1): import these from "@procedures/client/node"
 export type {
   WebSocketServerTransportOptions,
   WebSocketAuthHandler,

package/src/node.ts

@@ -18,6 +18,11 @@
  * The option `addressing` of `procedureHandler` gives the method and the payload of a request
  * (CLI-31). `urlAddressing()` is the default, and `bodyPathAddressing()` reads the path from the
  * body of a single endpoint.
+ *
+ * The server transports are in this entry too (CLI-6): `HttpServerTransport`, the Express shim
+ * over `procedureHandler`, and `WebSocketServerTransport`. The root and `./server` also export
+ * them, but these exports are deprecated. The next MINOR removes them, so the root imports no
+ * `http` and no `ws`.
  */
 
 export { WebSocketTransport } from "./adapters/websocket/client/node.js";
@@ -25,13 +30,20 @@ export type { WebSocketTransportOptions, WebSocketClass } from "./adapters/webso
 export { writeNdjsonStream } from "./adapters/http/server/ndjson.js";
 export type { WriteNdjsonStreamOptions, NdjsonError } from "./adapters/http/server/ndjson.js";
 export { procedureHandler } from "./adapters/http/server/handler.js";
+// The JSON body of a request, read to a limit: the procedure handler and the MCP face read it so (CLI-35)
+export { readJsonBody, BodyError } from "./adapters/http/server/body.js";
 export type { ProcedureHandlerOptions, NodeProcedureHandler, NodeUrlStrategy, UrlRequest } from "./adapters/http/server/handler.js";
-export type { CorsOptions } from "./adapters/http/server/cors.js";
+export type { CorsOptions, CredentialedCorsOptions } from "./adapters/http/server/cors.js";
+// The credentialed CORS of the trusted origins of a host, for a route of the app (CLI-49)
+export { credentialedCors } from "./adapters/http/server/cors.js";
 export type { RoutedRequest } from "./adapters/http/server/strategies.js";
 export { defaultServerUrlStrategy, rpcServerUrlStrategy } from "./adapters/http/server/strategies.js";
 // The addressing of a request: the URL (the default), or the path in the body of a single endpoint (CLI-31)
 export { urlAddressing, bodyPathAddressing } from "./adapters/http/server/addressing.js";
 export type { Addressing, CallAddress, UrlAddressingOptions, BodyPathAddressingOptions } from "./adapters/http/server/addressing.js";
+// The server transports (CLI-6): the root and ./server export them only until the next MINOR
+export { HttpServerTransport } from "./adapters/http/server/transport.js";
+export type { HttpServerTransportOptions, HttpUrlStrategy } from "./adapters/http/server/types.js";
 export { upgradeHandler } from "./adapters/websocket/server/upgrade.js";
 export type { UpgradeHandlerOptions, NodeUpgradeHandler } from "./adapters/websocket/server/upgrade.js";
 export { WebSocketServerTransport } from "./adapters/websocket/server/transport.js";

package/src/procedures/collection/admission.ts

@@ -0,0 +1,243 @@
+/**
+ * The rules of the rows of a served collection (roadmap CLI-41). A right can depend on the
+ * document: a `when` condition of Graph, or `accessAdmitItem()` of `@procedures/access`. The option
+ * `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.
+ * - `guard` examines each write `{ op, id, doc, prev }` before the storage changes. A refused write
+ *   gets `FORBIDDEN` with the reason `write-not-allowed`.
+ *
+ * The procedures apply the rules in one place: the view of the storage of a call
+ * (`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.
+ * - 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. CLI-16 (`expectedVersion`) closes the gap of
+ *   a write of another writer between that read and the write.
+ * - The rules get the invocation of the call (`ctx.invocation`). A call without an invocation gets
+ *   no row and makes no write.
+ */
+import { InvocationError, type AdmitItem, type Invocation } from "../invoke.js";
+import type { ProcedureContext } from "../types.js";
+import { applyPatch, type StoragePatch, type StorageQueryOptions, type StorageQueryPolicy, type StorageSelector } from "./query.js";
+import type { CollectionStorage, StorageChanges, StorageWriteOptions } from "./storage.js";
+import { patchInParts } from "./patch-in-parts.js";
+
+/** A row of a collection: the id and the stored item. The rule `admit` examines one row at a time. */
+export interface CollectionRow {
+  readonly id: string;
+  readonly value: unknown;
+}
+
+/** A write of a collection, as the guard examines it. */
+export interface CollectionWrite {
+  /**
+   * The operation. `setBatch` gives one `set` for each item. `deleteBatch` and `clear` give one
+   * `delete` for each id.
+   */
+  readonly op: "set" | "patch" | "delete";
+  /** The id of the item. */
+  readonly id: string;
+  /** The item after the write: the value of a `set`, or the merged item of a `patch`. Undefined for a `delete`. */
+  readonly doc: unknown;
+  /** The stored item before the write. Undefined when the id has no item. */
+  readonly prev: unknown;
+}
+
+/**
+ * The guard of the writes of a collection. It gets each write and the invocation of the call. It
+ * gives true to permit the write. An error that it throws passes through, and the storage does
+ * not change.
+ */
+export type CollectionWriteGuard = (write: CollectionWrite, invocation: Invocation) => boolean | Promise<boolean>;
+
+/** The rules of the rows of a served collection (roadmap CLI-41). Each rule is optional. */
+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.
+   */
+  admit?: AdmitItem | undefined;
+  /** The guard of each `set`, `patch` and `delete`, also of the batches and of `clear`. */
+  guard?: CollectionWriteGuard | undefined;
+}
+
+/** The size of a page of a query of the storage, when the policy gives no `maxLimit`. */
+const QUERY_PAGE = 1000;
+
+/** The refusal of a write. */
+function writeRefused(ctx: ProcedureContext, write: CollectionWrite): InvocationError {
+  return new InvocationError("FORBIDDEN", `The rule of the collection does not permit the ${write.op} of "${write.id}"`, ctx.path, "write-not-allowed");
+}
+
+/**
+ * This function tells if the rule of the rows admits a row for a call. Without a rule, it gives
+ * true. A call without an invocation gets no row.
+ */
+export async function admitsRow(admission: CollectionAdmission | undefined, ctx: ProcedureContext, id: string, value: unknown): Promise<boolean> {
+  const admit = admission?.admit;
+  if (!admit) return true;
+  const invocation = ctx.invocation;
+  return invocation !== undefined && (await admit({ id, value }, invocation)) === true;
+}
+
+/**
+ * This function gives the view of the storage of a call: the storage, with the rules of the
+ * collection for each read and each write. Without rules, it gives the storage itself.
+ *
+ * @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.
+ */
+export function admittedStorage<T>(storage: CollectionStorage<T>, admission: CollectionAdmission | undefined, ctx: ProcedureContext): CollectionStorage<T> {
+  const admit = admission?.admit;
+  const guard = admission?.guard;
+  if (!admit && !guard) return storage;
+  const invocation = ctx.invocation;
+
+  const admits = (id: string, value: unknown): Promise<boolean> => admitsRow(admission, ctx, id, value);
+  /** The entries that the rule admits, in their order. */
+  const admitted = async (entries: Array<[string, T]>): Promise<Array<[string, T]>> => {
+    if (!admit) return entries;
+    const keep = await Promise.all(entries.map(([id, value]) => admits(id, value)));
+    return entries.filter((_, index) => keep[index]);
+  };
+  /** The entries of the storage that the rule admits. The rule needs the ids, so the storage must give them. */
+  const entries = async (): Promise<Array<[string, T]>> => {
+    if (!storage.getEntries) throw new Error("The storage cannot give the ids of its items, so the rule of the rows cannot examine them");
+    return admitted(await storage.getEntries());
+  };
+  /** This function throws `FORBIDDEN` unless the guard permits each write. */
+  const permit = async (writes: readonly CollectionWrite[]): Promise<void> => {
+    if (!guard) return;
+    for (const write of writes) {
+      if (invocation === undefined || (await guard(write, invocation)) !== true) throw writeRefused(ctx, write);
+    }
+  };
+
+  const view: CollectionStorage<T> = {
+    async get(id) {
+      const value = await storage.get(id);
+      return value === undefined || (await admits(id, value)) ? value : undefined;
+    },
+    async getAll() {
+      return admit ? (await entries()).map(([, value]) => value) : storage.getAll();
+    },
+    async find(predicate) {
+      return admit ? (await entries()).map(([, value]) => value).filter(predicate) : storage.find(predicate);
+    },
+    async has(id) {
+      return admit ? (await view.get(id)) !== undefined : storage.has(id);
+    },
+    async size() {
+      return admit ? (await entries()).length : storage.size();
+    },
+    async getBatch(ids) {
+      const found = await storage.getBatch(ids);
+      if (!admit) return found;
+      const kept = await admitted([...found.entries()]);
+      return new Map(kept);
+    },
+
+    async set(id, value, options) {
+      if (guard) await permit([{ op: "set", id, doc: value, prev: await storage.get(id) }]);
+      return storage.set(id, value, options);
+    },
+    async delete(id, options) {
+      if (guard) await permit([{ op: "delete", id, doc: undefined, prev: await storage.get(id) }]);
+      return storage.delete(id, options);
+    },
+    async clear(options) {
+      if (!guard) return storage.clear(options);
+      // Each item is a delete that the guard examines. The storage deletes only the items that it examined.
+      if (!storage.getEntries) throw new Error("The storage cannot give the ids of its items, so the guard cannot examine a clear");
+      const all = await storage.getEntries();
+      await permit(all.map(([id, prev]) => ({ op: "delete" as const, id, doc: undefined, prev })));
+      if (all.length > 0) await storage.deleteBatch(all.map(([id]) => id), options);
+    },
+    async setBatch(items, options) {
+      if (guard) {
+        const before = await storage.getBatch(items.map(([id]) => id));
+        await permit(items.map(([id, value]) => ({ op: "set" as const, id, doc: value, prev: before.get(id) })));
+      }
+      return storage.setBatch(items, options);
+    },
+    async deleteBatch(ids, options) {
+      if (guard) {
+        const before = await storage.getBatch(ids);
+        await permit(ids.map((id) => ({ op: "delete" as const, id, doc: undefined, prev: before.get(id) })));
+      }
+      return storage.deleteBatch(ids, options);
+    },
+    async patch(id: string, fields: StoragePatch, options?: StorageWriteOptions): Promise<T | undefined> {
+      const check = async (prev: unknown, doc: unknown): Promise<void> => permit([{ op: "patch", id, doc, prev }]);
+      if (!storage.patch) return patchInParts(storage as CollectionStorage<unknown>, id, fields, options, guard ? check : undefined) as Promise<T | undefined>;
+      if (guard) {
+        const prev = await storage.get(id);
+        // A patch of a missing id changes nothing
+        if (prev === undefined) return undefined;
+        await check(prev, applyPatch(prev, fields));
+      }
+      return storage.patch(id, fields, options);
+    },
+    close: () => storage.close(),
+  };
+
+  if (storage.getEntries) view.getEntries = async () => (admit ? entries() : storage.getEntries!());
+  if (admit ? storage.getEntries : storage.getIds) {
+    view.getIds = async () => (admit ? (await entries()).map(([id]) => id) : storage.getIds!());
+  }
+  if (storage.getChangesSince) {
+    view.getChangesSince = async (since?: string): Promise<StorageChanges<T>> => {
+      const changes = await storage.getChangesSince!(since);
+      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] };
+    };
+  }
+  if (storage.query) {
+    view.query = async (selector: StorageSelector, options?: StorageQueryOptions, policy?: StorageQueryPolicy) =>
+      admit ? admittedQuery(storage, admitted, selector, options ?? {}, policy) : storage.query!(selector, options, policy);
+  }
+  return view;
+}
+
+/**
+ * The query of a storage with the rule of the rows. The storage runs the selector and the order,
+ * page by page. The skip and the limit count the admitted rows only, so a page of the caller is full.
+ */
+async function admittedQuery<T>(
+  storage: CollectionStorage<T>,
+  admitted: (entries: Array<[string, T]>) => Promise<Array<[string, T]>>,
+  selector: StorageSelector,
+  options: StorageQueryOptions,
+  policy: StorageQueryPolicy | undefined,
+): Promise<Array<[string, T]>> {
+  const page = policy?.maxLimit !== undefined && Number.isFinite(policy.maxLimit) ? policy.maxLimit : QUERY_PAGE;
+  const skip = options.skip ?? 0;
+  const limit = options.limit;
+  const out: Array<[string, T]> = [];
+  let skipped = 0;
+  for (let offset = 0; ; offset += page) {
+    const rows = await storage.query!(selector, { ...(options.sort !== undefined && { sort: options.sort }), skip: offset, limit: page }, policy);
+    for (const entry of await admitted(rows)) {
+      if (skipped < skip) {
+        skipped++;
+        continue;
+      }
+      out.push(entry);
+      if (limit !== undefined && out.length >= limit) return out;
+    }
+    if (rows.length < page) return out;
+  }
+}
+