@procedures/client 0.14.0 → 0.15.0

package/src/procedures/collection/changes.ts

@@ -26,6 +26,7 @@
 
 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";
 
 /**
@@ -137,13 +138,16 @@ 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 a refused row goes from `values` to `withheld`.
+ * output filter of each subscriber and the rule of the rows of the collection, and a refused row
+ * goes from `values` to `withheld`.
  */
-function withValues(event: CollectionChangeEvent, entries: ReadonlyArray<{ readonly id: string; readonly value: unknown }>): CollectionChangeEvent {
+function withValues(event: CollectionChangeEvent, entries: ReadonlyArray<{ readonly id: string; readonly value: unknown }>, admit: AdmitItem | undefined): CollectionChangeEvent {
   return withRows(
     { ...event, values: entries },
     {
       rows: entries,
+      // The rule of the rows of the collection (roadmap CLI-41): each subscriber applies it too
+      ...(admit && { admit }),
       keep: (admitted) => {
         const withheld = entries.filter((_, index) => !admitted[index]).map(({ id }) => id);
         return {
@@ -157,7 +161,7 @@ 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): Promise<void> {
+async function publish(chain: ChangeChain, storage: ChangeLog, bus: EventBus, topic: string, values: boolean, admit: AdmitItem | undefined): Promise<void> {
   const writes = chain.ended.splice(0);
   // An earlier publish told these writes
   if (writes.length === 0) return;
@@ -194,7 +198,7 @@ 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 }))) : event);
+  bus.emit(topic, values ? withValues(event, changes.changed.map(([id, value]) => ({ id, value })), admit) : event);
 }
 
 /**
@@ -210,6 +214,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)
  */
 export async function writeWithChangeEvent<R>(
   bus: EventBus | undefined,
@@ -219,6 +224,7 @@ export async function writeWithChangeEvent<R>(
   origin: string | undefined,
   write: () => Promise<R>,
   values = false,
+  admit?: AdmitItem,
 ): Promise<R> {
   if (bus === undefined || topic === undefined) return write();
   const chain = chainOf(storage, topic);
@@ -227,7 +233,7 @@ export async function writeWithChangeEvent<R>(
     return await write();
   } finally {
     chain.ended.push(started);
-    const run = chain.tail.then(() => publish(chain, storage, bus, topic, values));
+    const run = chain.tail.then(() => publish(chain, storage, bus, topic, values, admit));
     chain.tail = run.catch(() => undefined);
     await chain.tail;
   }

package/src/procedures/collection/index.ts

@@ -74,12 +74,18 @@ export type { CollectionChangeEvent } from "./changes.js";
 export { PARTITION_PATTERN, collectionTopicPartition, collectionTopicTarget, partitionOfCall, storageOfCall, withPartition } from "./partition.js";
 export type { CollectionPartitions, PartitionInput, PartitionResolver } from "./partition.js";
 
+// 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 storage interface of the core (the shape of client-collections' CollectionStorage)
 export type {
   CollectionStorage,
   StorageChanges,
   StorageMetadata,
   StorageWriteOptions,
+  StorageItemWriteOptions,
+  StorageBatchWriteOptions,
   StorageSetChange,
   StorageDeleteChange,
   StorageClearChange,
@@ -88,6 +94,21 @@ export type {
   StorageObserver,
 } from "./storage.js";
 
+// The precondition of the writes: the expected version and VERSION_CONFLICT (roadmap CLI-16)
+export {
+  MAX_EXPECTED_VERSION_LENGTH,
+  PRECONDITION_NOT_SUPPORTED,
+  VERSION_CONFLICTS_METADATA_KEY,
+  VersionConflictError,
+  asVersionConflictError,
+  isExpectedVersion,
+  preconditionNotSupported,
+  versionConflict,
+  versionConflicts,
+  versionConflictsOf,
+} from "./precondition.js";
+export type { CurrentItem, VersionConflict, VersionOf } from "./precondition.js";
+
 // The query language of the storages: the same JSON on the wire and in query() (roadmap CLI-34:
 // the one copy of the language)
 export {

package/src/procedures/collection/patch-in-parts.ts

@@ -0,0 +1,56 @@
+/**
+ * The patch of an item of a storage (roadmap CLI-14): `patch()` of the storage, or a read, a merge
+ * and a write for a storage without it.
+ */
+import { applyPatch, type StoragePatch } from "./query.js";
+import type { CollectionStorage, StorageWriteOptions } from "./storage.js";
+
+/**
+ * The patches of a storage without `patch()` that run, for each id. A patch of an id waits for the
+ * patch before it, so two patches of one process keep each field. A write of another writer
+ * between the read and the write of a patch is lost: give the storage a `patch()` for one step.
+ */
+const PATCHES = new WeakMap<object, Map<string, Promise<unknown>>>();
+
+/**
+ * This function patches an item of a storage without `patch()`: a read, a merge and a write. The
+ * check gets the stored item and the merged item before the write. An error of the check stops
+ * the patch, and the storage does not change.
+ */
+export function patchInParts(
+  storage: CollectionStorage<unknown>,
+  id: string,
+  fields: StoragePatch,
+  options?: StorageWriteOptions,
+  check?: (prev: unknown, next: unknown) => Promise<void>,
+): Promise<unknown> {
+  let running = PATCHES.get(storage);
+  if (!running) {
+    running = new Map();
+    PATCHES.set(storage, running);
+  }
+  const queue = running;
+  const before = queue.get(id) ?? Promise.resolve();
+  const patch = before.then(async () => {
+    const current = await storage.get(id);
+    if (current === undefined) return undefined;
+    const next = applyPatch(current, fields);
+    if (check) await check(current, next);
+    await storage.set(id, next, options);
+    return next;
+  });
+  const settled = patch.then(
+    () => undefined,
+    () => undefined,
+  );
+  queue.set(id, settled);
+  void settled.then(() => {
+    if (queue.get(id) === settled) queue.delete(id);
+  });
+  return patch;
+}
+
+/** This function patches an item: with `patch()` of the storage, or in parts. It gives the new item, or undefined for a missing id. */
+export function patchItem(storage: CollectionStorage<unknown>, id: string, fields: StoragePatch, options?: StorageWriteOptions): Promise<unknown> {
+  return storage.patch ? storage.patch(id, fields, options) : patchInParts(storage, id, fields, options);
+}

package/src/procedures/collection/precondition.ts

@@ -0,0 +1,180 @@
+/**
+ * The precondition of a collection write (roadmap CLI-16, decision D11).
+ *
+ * - `set` and `delete` take `expectedVersion`. `setBatch` takes `expectedVersions`, with one
+ *   expected version for each id. The value is the version of the current item that the write
+ *   expects. `null` expects no item.
+ * - The version of an item is the value that the function `versionOf` of the storage gives for
+ *   the item, for example a revision field. `HybridStorage` reads the same versions with its own
+ *   `versionOf`, so its queue can send the base version of a write as the expected version.
+ * - The storage tests the precondition and writes in one step. When the version of the current
+ *   item is not the expected version, the write changes nothing, and it rejects with
+ *   `VersionConflictError`.
+ * - The error has the code `VERSION_CONFLICT` (HTTP 409). It has the current item and its version
+ *   for each conflict. On the wire, the conflicts go in the metadata key `conflicts`.
+ * - A storage without `versionOf` cannot test a precondition. It rejects such a write with a
+ *   `TypeError`, and changes nothing. It never ignores a precondition.
+ * - A write without a precondition is the same as before: the last write wins.
+ *
+ * This module has no imports: `@procedures/client/query` exports it for the storage packages.
+ */
+
+/** One conflict of a write with a precondition (roadmap CLI-16). The data is JSON. */
+export interface VersionConflict {
+  /** The id of the item. */
+  readonly id: string;
+  /** The version that the write expected. `null`: the write expected no item. */
+  readonly expected: string | null;
+  /** True when the id has an item now. */
+  readonly found: boolean;
+  /** The current item, when `found` is true. */
+  readonly value?: unknown;
+  /**
+   * The version of the current item: `null` when the id has no item. When the current item has no
+   * version, the field is absent.
+   */
+  readonly version?: string | null;
+}
+
+/** The function that gives the version of an item, or undefined for an item without a version. */
+export type VersionOf<T> = (item: T) => string | undefined;
+
+/** The current state of an id: no item, or an item. */
+export type CurrentItem<T> = { readonly found: false } | { readonly found: true; readonly value: T };
+
+/** The metadata key of the conflicts of a `VERSION_CONFLICT` error on the wire. */
+export const VERSION_CONFLICTS_METADATA_KEY = "conflicts";
+
+/** The longest expected version, in characters. */
+export const MAX_EXPECTED_VERSION_LENGTH = 1024;
+
+/** The message of an error with some conflicts. */
+function conflictMessage(conflicts: readonly VersionConflict[]): string {
+  const ids = conflicts.slice(0, 10).map((conflict) => JSON.stringify(conflict.id)).join(", ");
+  const more = conflicts.length > 10 ? ` and ${conflicts.length - 10} more` : "";
+  return `The version of the current item is not the expected version: ${ids}${more}`;
+}
+
+/**
+ * A write with a precondition found an item with another version (roadmap CLI-16). The write
+ * changed nothing. `conflicts` has the current item and its version for each id of a conflict.
+ */
+export class VersionConflictError extends Error {
+  override readonly name = "VersionConflictError";
+  /** The error code of the protocol: HTTP 409, not retryable. */
+  readonly code = "VERSION_CONFLICT";
+  /** A retry of the same write fails again: the caller reads the current item first. */
+  readonly retryable = false;
+  /** The conflicts, one for each id whose current item does not have the expected version. */
+  readonly conflicts: readonly VersionConflict[];
+
+  constructor(conflicts: readonly VersionConflict[], message?: string) {
+    super(message ?? conflictMessage(conflicts));
+    this.conflicts = conflicts;
+  }
+}
+
+/**
+ * This function gives the conflict of one id, or undefined when the current item has the expected
+ * version. `null` expects no item. An item without a version never has an expected string version.
+ *
+ * @param id - The id of the item
+ * @param expected - The expected version, or `null` for no item
+ * @param current - The current state of the id
+ * @param versionOf - The version of an item
+ */
+export function versionConflict<T>(id: string, expected: string | null, current: CurrentItem<T>, versionOf: VersionOf<T>): VersionConflict | undefined {
+  if (!current.found) return expected === null ? undefined : { id, expected, found: false, version: null };
+  const version = versionOf(current.value);
+  if (expected !== null && version === expected) return undefined;
+  return version === undefined ? { id, expected, found: true, value: current.value } : { id, expected, found: true, value: current.value, version };
+}
+
+/**
+ * This function tests the preconditions of a write against the current items, and gives the
+ * conflicts. The list is empty when each precondition holds.
+ *
+ * @param expected - The expected version of each id
+ * @param currentOf - The current state of an id, before the write
+ * @param versionOf - The version of an item
+ */
+export function versionConflicts<T>(
+  expected: Iterable<readonly [string, string | null]>,
+  currentOf: (id: string) => CurrentItem<T>,
+  versionOf: VersionOf<T>,
+): VersionConflict[] {
+  const conflicts: VersionConflict[] = [];
+  for (const [id, version] of expected) {
+    const conflict = versionConflict(id, version, currentOf(id), versionOf);
+    if (conflict) conflicts.push(conflict);
+  }
+  return conflicts;
+}
+
+/** The code of the error of a write with a precondition on a storage that cannot test it. */
+export const PRECONDITION_NOT_SUPPORTED = "PRECONDITION_NOT_SUPPORTED";
+
+/**
+ * The error of a write with a precondition on a storage that cannot test it: a storage without
+ * `versionOf`. The storage changes nothing. The error is a `TypeError` with the code
+ * `PRECONDITION_NOT_SUPPORTED`, so a sync does not take it for a network failure.
+ *
+ * @param storage - The name of the storage, for the message
+ * @param remedy - What makes the test possible
+ */
+export function preconditionNotSupported(storage: string, remedy = "give it the option versionOf"): TypeError & { readonly code: string; readonly retryable: false } {
+  return Object.assign(new TypeError(`${storage} cannot test expectedVersion: ${remedy}`), { code: PRECONDITION_NOT_SUPPORTED, retryable: false as const });
+}
+
+/** True for a value that a precondition can expect: a string of at most 1024 characters, or `null`. */
+export function isExpectedVersion(value: unknown): value is string | null {
+  return value === null || (typeof value === "string" && value.length <= MAX_EXPECTED_VERSION_LENGTH);
+}
+
+/** The conflicts of untrusted data from the wire, or undefined when the data is not a list of conflicts. */
+function conflictsOfData(data: unknown): VersionConflict[] | undefined {
+  if (!Array.isArray(data)) return undefined;
+  const conflicts: VersionConflict[] = [];
+  for (const entry of data) {
+    if (typeof entry !== "object" || entry === null) return undefined;
+    const record = entry as Record<string, unknown>;
+    const { id, expected, found, version } = record;
+    if (typeof id !== "string" || typeof found !== "boolean" || !(expected === null || typeof expected === "string")) return undefined;
+    if (!(version === undefined || version === null || typeof version === "string")) return undefined;
+    conflicts.push({
+      id,
+      expected,
+      found,
+      ...(found && Object.prototype.hasOwnProperty.call(record, "value") && { value: record["value"] }),
+      ...(version !== undefined && { version }),
+    });
+  }
+  return conflicts;
+}
+
+/**
+ * This function gives the conflicts of an error with the code `VERSION_CONFLICT`: the `conflicts`
+ * of a `VersionConflictError`, or the metadata key `conflicts` of an error from the wire (a
+ * `ClientError`). It gives undefined for another error. A `VERSION_CONFLICT` error without
+ * readable conflicts gives an empty list.
+ */
+export function versionConflictsOf(error: unknown): readonly VersionConflict[] | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  if (error instanceof VersionConflictError) return error.conflicts;
+  const { code, conflicts, metadata } = error as { code?: unknown; conflicts?: unknown; metadata?: unknown };
+  if (code !== "VERSION_CONFLICT") return undefined;
+  const fromMetadata = typeof metadata === "object" && metadata !== null ? (metadata as Record<string, unknown>)[VERSION_CONFLICTS_METADATA_KEY] : undefined;
+  return conflictsOfData(conflicts) ?? conflictsOfData(fromMetadata) ?? [];
+}
+
+/**
+ * This function gives a `VersionConflictError` for an error with the code `VERSION_CONFLICT`, with
+ * its conflicts and its message. It gives undefined for another error.
+ */
+export function asVersionConflictError(error: unknown): VersionConflictError | undefined {
+  if (error instanceof VersionConflictError) return error;
+  const conflicts = versionConflictsOf(error);
+  if (conflicts === undefined) return undefined;
+  const message = error instanceof Error ? error.message : undefined;
+  return new VersionConflictError(conflicts, message);
+}

package/src/procedures/collection/procedures.ts

@@ -56,10 +56,12 @@ import {
   type SetBatchInput,
   type DeleteBatchInput,
 } from "./schemas.js";
-import { DEFAULT_FIND_LIMIT, applyPatch, queryEntries, type StoragePatch, type StorageQueryOptions, type StorageQueryPolicy } from "./query.js";
-import type { CollectionStorage, StorageWriteOptions } from "./storage.js";
+import { DEFAULT_FIND_LIMIT, queryEntries, type StorageQueryOptions, type StorageQueryPolicy } from "./query.js";
+import type { CollectionStorage, StorageBatchWriteOptions, StorageItemWriteOptions, StorageWriteOptions } from "./storage.js";
 import { collectionChangeTopic, startChangeChain, writeWithChangeEvent } from "./changes.js";
 import { partitionOfCall, storageOfCall, withPartition, type PartitionInput } from "./partition.js";
+import { admitsRow, admittedStorage, type CollectionAdmission } from "./admission.js";
+import { patchItem } from "./patch-in-parts.js";
 
 // =============================================================================
 // Handler Factory
@@ -122,6 +124,13 @@ export interface CollectionProceduresOptions {
    * @default true, with the topic `collections.<name>` and no values
    */
   changeEvents?: boolean | CollectionChangeEventsOptions | undefined;
+  /**
+   * The rules of the rows (roadmap CLI-41). `admit` examines each row of each read and of each
+   * change event with values. `guard` examines each write before the storage changes, and a
+   * refused write gets `FORBIDDEN` (reason `write-not-allowed`). Without it, the procedures check
+   * only the partition.
+   */
+  admission?: CollectionAdmission | undefined;
 }
 
 /** The write options of an input with an origin. */
@@ -129,38 +138,17 @@ function writeOptionsOf(input: { origin?: string }): StorageWriteOptions | undef
   return input.origin === undefined ? undefined : { origin: input.origin };
 }
 
-/**
- * The patches of a storage without `patch()` that run, for each id. A patch of an id waits for the
- * patch before it, so two patches of one process keep each field. A write of another writer
- * between the read and the write of a patch is lost: give the storage a `patch()` for one step.
- */
-const PATCHES = new WeakMap<object, Map<string, Promise<unknown>>>();
+/** The write options of `set` and `delete`: the origin, and the expected version (roadmap CLI-16). */
+function itemWriteOptionsOf(input: { origin?: string; expectedVersion?: string | null }): StorageItemWriteOptions | undefined {
+  if (input.expectedVersion === undefined) return writeOptionsOf(input);
+  return { ...writeOptionsOf(input), expectedVersion: input.expectedVersion };
+}
 
-/** This function patches an item of a storage without `patch()`: a read, a merge and a write. */
-function patchInParts(storage: CollectionStorage<unknown>, id: string, fields: StoragePatch, options?: StorageWriteOptions): Promise<unknown> {
-  let running = PATCHES.get(storage);
-  if (!running) {
-    running = new Map();
-    PATCHES.set(storage, running);
-  }
-  const queue = running;
-  const before = queue.get(id) ?? Promise.resolve();
-  const patch = before.then(async () => {
-    const current = await storage.get(id);
-    if (current === undefined) return undefined;
-    const next = applyPatch(current, fields);
-    await storage.set(id, next, options);
-    return next;
-  });
-  const settled = patch.then(
-    () => undefined,
-    () => undefined,
-  );
-  queue.set(id, settled);
-  void settled.then(() => {
-    if (queue.get(id) === settled) queue.delete(id);
-  });
-  return patch;
+/** The write options of `setBatch`: the origin, and the expected version of each item that has one (roadmap CLI-16). */
+function batchWriteOptionsOf(input: SetBatchInput): StorageBatchWriteOptions | undefined {
+  const expectedVersions = input.items.flatMap((item): Array<[string, string | null]> => (item.expectedVersion === undefined ? [] : [[item.id, item.expectedVersion]]));
+  if (expectedVersions.length === 0) return writeOptionsOf(input);
+  return { ...writeOptionsOf(input), expectedVersions };
 }
 
 // =============================================================================
@@ -192,17 +180,20 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     events === false ? undefined : (events !== true && events.topic) || ((name: string, _ctx: ProcedureContext, partition: string | undefined) => collectionChangeTopic(name, partition));
   const topicOf = (ctx: ProcedureContext, partition: string | undefined): string | undefined => topicRule?.(collectionName, ctx, partition);
   const withValues = events !== false && events !== true && events.values === true;
-  /** A write, and then its change event on the bus of the context. */
+  const admission = options.admission;
+  /** A write, and then its change event on the bus of the context. The chain of the events belongs to the storage, not to its view. */
   const changing = <R>(ctx: ProcedureContext, partition: string | undefined, storage: CollectionStorage<unknown>, ids: readonly string[] | "*", origin: string | undefined, write: () => Promise<R>): Promise<R> =>
-    writeWithChangeEvent(ctx.bus, storage, topicRule ? topicOf(ctx, partition) : undefined, ids, origin, write, withValues);
+    writeWithChangeEvent(ctx.bus, storage, topicRule ? topicOf(ctx, partition) : undefined, ids, origin, write, withValues, admission?.admit);
   /**
    * The partition and the storage of a call (roadmap CLI-17). The repository of the call has the
-   * partitions of the collection and their resolver: the tenant comes from the principal.
+   * partitions of the collection and their resolver: the tenant comes from the principal. Each read
+   * and each write goes through the view, with the rules of the rows (roadmap CLI-41).
    */
-  const storageOf = async (input: PartitionInput, ctx: ProcedureContext): Promise<{ storage: CollectionStorage<unknown>; partition: string | undefined }> => {
+  const storageOf = async (input: PartitionInput, ctx: ProcedureContext): Promise<{ storage: CollectionStorage<unknown>; view: CollectionStorage<unknown>; partition: string | undefined }> => {
     const collection = getCollectionFromPath(ctx.path);
     const partition = await partitionOfCall(ctx, collection, input.partition);
-    return { storage: storageOfCall<unknown>(ctx, collection, partition), partition };
+    const storage = storageOfCall<unknown>(ctx, collection, partition);
+    return { storage, view: admittedStorage(storage, admission, ctx), partition };
   };
 
   return [
@@ -217,8 +208,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "read"],
       },
       handler: async (input: GetInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage } = await storageOf(input, ctx);
-        const value = await storage.get(input.id);
+        const { view } = await storageOf(input, ctx);
+        const value = await view.get(input.id);
         if (input.found !== true) return value;
         // The output with `found` keeps a stored null apart from a missing id, in one call
         const output: GetFoundOutput = value === undefined ? { found: false } : { found: true, value };
@@ -237,8 +228,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "write"],
       },
       handler: async (input: SetInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage, partition } = await storageOf(input, ctx);
-        await changing(ctx, partition, storage, [input.id], input.origin, () => storage.set(input.id, input.value, writeOptionsOf(input)));
+        const { storage, view, partition } = await storageOf(input, ctx);
+        await changing(ctx, partition, storage, [input.id], input.origin, () => view.set(input.id, input.value, itemWriteOptionsOf(input)));
       },
     }),
 
@@ -253,8 +244,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "write"],
       },
       handler: async (input: DeleteInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage, partition } = await storageOf(input, ctx);
-        return changing(ctx, partition, storage, [input.id], input.origin, () => storage.delete(input.id, writeOptionsOf(input)));
+        const { storage, view, partition } = await storageOf(input, ctx);
+        return changing(ctx, partition, storage, [input.id], input.origin, () => view.delete(input.id, itemWriteOptionsOf(input)));
       },
     }),
 
@@ -269,8 +260,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "read"],
       },
       handler: async (input: HasInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage } = await storageOf(input, ctx);
-        return storage.has(input.id);
+        const { view } = await storageOf(input, ctx);
+        return view.has(input.id);
       },
     }),
 
@@ -285,8 +276,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "read"],
       },
       handler: async (input: GetAllInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage } = await storageOf(input, ctx);
-        return storage.getAll();
+        const { view } = await storageOf(input, ctx);
+        return view.getAll();
       },
     }),
 
@@ -301,11 +292,11 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "read"],
       },
       handler: async (input: EntriesInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage } = await storageOf(input, ctx);
-        if (!storage.getEntries) {
+        const { view } = await storageOf(input, ctx);
+        if (!view.getEntries) {
           throw new Error(`The storage of ${collectionName} cannot give the ids of its items`);
         }
-        return (await storage.getEntries()).map(([id, value]) => ({ id, value }));
+        return (await view.getEntries()).map(([id, value]) => ({ id, value }));
       },
     }),
 
@@ -320,10 +311,10 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "read"],
       },
       handler: async (input: IdsInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage } = await storageOf(input, ctx);
-        if (storage.getIds) return storage.getIds();
+        const { view } = await storageOf(input, ctx);
+        if (view.getIds) return view.getIds();
         // A storage without getIds() gives its entries: the values stay on the server
-        if (storage.getEntries) return (await storage.getEntries()).map(([id]) => id);
+        if (view.getEntries) return (await view.getEntries()).map(([id]) => id);
         throw new Error(`The storage of ${collectionName} cannot give the ids of its items`);
       },
     }),
@@ -339,9 +330,9 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "read"],
       },
       handler: async (input: ChangesInput & PartitionInput, ctx: ProcedureContext): Promise<ChangesOutput> => {
-        const { storage, partition } = await storageOf(input, ctx);
-        if (storage.getChangesSince) {
-          const changes = await storage.getChangesSince(input.since);
+        const { storage, view, partition } = await storageOf(input, ctx);
+        if (view.getChangesSince) {
+          const changes = await view.getChangesSince(input.since);
           // The chain of the change events starts at this version: the caller then applies the
           // next event without a read (roadmap CLI-15)
           if (topicRule) startChangeChain(ctx.bus, storage, topicOf(ctx, partition), changes.version);
@@ -354,8 +345,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         }
         // A storage without a change log gives all its items. The empty version asks for all
         // items again at the next call.
-        if (storage.getEntries) {
-          const entries = await storage.getEntries();
+        if (view.getEntries) {
+          const entries = await view.getEntries();
           return { version: "", full: true, changed: entries.map(([id, value]) => ({ id, value })), deleted: [] };
         }
         throw new Error(`The storage of ${collectionName} cannot give its changes or the ids of its items`);
@@ -373,16 +364,16 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "read", "query"],
       },
       handler: async (input: FindInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage } = await storageOf(input, ctx);
+        const { view } = await storageOf(input, ctx);
         const selector = input.selector ?? {};
         const query = queryOptionsOf(input, queryPolicy);
         // The storage runs the selector itself when it can: a database does not read each item. It
         // gets the policy of the host, so it permits what the procedure permits.
-        if (storage.query) return (await storage.query(selector, query, queryPolicy)).map(([id, value]) => ({ id, value }));
-        if (!storage.getEntries) {
+        if (view.query) return (await view.query(selector, query, queryPolicy)).map(([id, value]) => ({ id, value }));
+        if (!view.getEntries) {
           throw new Error(`The storage of ${collectionName} cannot run a selector or give the ids of its items`);
         }
-        return queryEntries(await storage.getEntries(), selector, query, queryPolicy).map(([id, value]) => ({ id, value }));
+        return queryEntries(await view.getEntries(), selector, query, queryPolicy).map(([id, value]) => ({ id, value }));
       },
     }),
 
@@ -397,12 +388,12 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "write"],
       },
       handler: async (input: PatchInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage, partition } = await storageOf(input, ctx);
+        const { storage, view, partition } = await storageOf(input, ctx);
         const write = writeOptionsOf(input);
-        const value = await changing(ctx, partition, storage, [input.id], input.origin, () =>
-          storage.patch ? storage.patch(input.id, input.fields, write) : patchInParts(storage, input.id, input.fields, write),
-        );
-        const output: GetFoundOutput = value === undefined ? { found: false } : { found: true, value };
+        const value = await changing(ctx, partition, storage, [input.id], input.origin, () => patchItem(view, input.id, input.fields, write));
+        if (value === undefined) return { found: false } satisfies GetFoundOutput;
+        // The new item is a row too: a caller gets it only when the rule of the rows admits it (roadmap CLI-41)
+        const output: GetFoundOutput = (await admitsRow(admission, ctx, input.id, value)) ? { found: true, value } : { found: true };
         return output;
       },
     }),
@@ -418,8 +409,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "read"],
       },
       handler: async (input: SizeInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage } = await storageOf(input, ctx);
-        return storage.size();
+        const { view } = await storageOf(input, ctx);
+        return view.size();
       },
     }),
 
@@ -434,8 +425,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "write"],
       },
       handler: async (input: ClearInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage, partition } = await storageOf(input, ctx);
-        await changing(ctx, partition, storage, "*", input.origin, () => storage.clear(writeOptionsOf(input)));
+        const { storage, view, partition } = await storageOf(input, ctx);
+        await changing(ctx, partition, storage, "*", input.origin, () => view.clear(writeOptionsOf(input)));
       },
     }),
 
@@ -450,8 +441,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "read", "batch"],
       },
       handler: async (input: GetBatchInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage } = await storageOf(input, ctx);
-        const result = await storage.getBatch(input.ids);
+        const { view } = await storageOf(input, ctx);
+        const result = await view.getBatch(input.ids);
         // Convert Map to plain object
         return Object.fromEntries(result);
       },
@@ -468,12 +459,12 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "write", "batch"],
       },
       handler: async (input: SetBatchInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage, partition } = await storageOf(input, ctx);
+        const { storage, view, partition } = await storageOf(input, ctx);
         const items: Array<[string, unknown]> = input.items.map((item) => [
           item.id,
           item.value,
         ]);
-        await changing(ctx, partition, storage, items.map(([id]) => id), input.origin, () => storage.setBatch(items, writeOptionsOf(input)));
+        await changing(ctx, partition, storage, items.map(([id]) => id), input.origin, () => view.setBatch(items, batchWriteOptionsOf(input)));
       },
     }),
 
@@ -488,8 +479,8 @@ export function createCollectionProcedures(collectionName: string, options: Coll
         tags: ["collections", collectionName, "write", "batch"],
       },
       handler: async (input: DeleteBatchInput & PartitionInput, ctx: ProcedureContext) => {
-        const { storage, partition } = await storageOf(input, ctx);
-        return changing(ctx, partition, storage, input.ids, input.origin, () => storage.deleteBatch(input.ids, writeOptionsOf(input)));
+        const { storage, view, partition } = await storageOf(input, ctx);
+        return changing(ctx, partition, storage, input.ids, input.origin, () => view.deleteBatch(input.ids, writeOptionsOf(input)));
       },
     }),
   ];