@procedures/client 0.8.1 → 0.9.1

package/src/procedures/narrowing.ts

@@ -0,0 +1,357 @@
+/**
+ * The narrowing key of the wire (roadmap CLI-30, `documentation/WIRE-PROTOCOL.md`).
+ *
+ * A call can ask for a narrower capability than its principal holds: a lower clearance, fewer
+ * effects or a shorter time. A narrower capability is always safe, for the same reason as the
+ * deadline (`procedure-timeout`). Thus each face carries the key. HTTP has the header
+ * `Procedure-Narrowing`, and WebSocket has the metadata of a frame. MCP has the `_meta` of a
+ * request, and an invocation in the process has the option `narrow`.
+ *
+ * A request can have more than one source of narrowing, for example the header of a gateway and
+ * the key of `X-Metadata` of the client. No source replaces another: the value of the key
+ * becomes a list of the sources (`addNarrowing`). The invocation of the host applies all the
+ * sources. The clearance is the meet of the clearance order, the effects are the intersection,
+ * and the deadline is the earliest. Thus each source can only narrow, in each sequence.
+ *
+ * A valid part that asks for more has no effect: the meet removes it. A part that is not valid
+ * refuses the call, because the server does not know what that source asks for. Thus a typo of a
+ * gateway does not let the call keep a wider capability. Examples are a text that is not JSON, an
+ * unknown field, a time that is not a number and a clearance outside the order. The notes of
+ * these parts go to the debug reports.
+ *
+ * This module imports no Node code.
+ */
+
+import type { Capability, CapabilityRequest, ClearanceOf, ClearanceOrder, PermittedEffects } from "./types.js";
+import { UNLIMITED_CAPABILITY, narrowCapability } from "./capability.js";
+
+/**
+ * The metadata key of the narrowing of a call. Its value is a `CapabilityRequest` as an object or
+ * as JSON text, or a list of them: each item is one source.
+ */
+export const NARROWING_METADATA_KEY = "procedure-narrowing";
+
+/**
+ * The HTTP header of the narrowing of a call: the JSON of a `CapabilityRequest`, raw or
+ * URI-encoded. The header and the metadata key have the same name.
+ */
+export const NARROWING_HEADER = "Procedure-Narrowing";
+
+/** A part of a narrowing that has no effect or that refuses the call, and the reason. */
+export interface NarrowingNote {
+  /** The part: a whole source, its clearance, its effects or its time. */
+  readonly field: "narrowing" | "clearance" | "effects" | "timeoutMs";
+  /**
+   * - `"widens"`: the part is valid and asks for more than the call holds, so it has no effect.
+   * - `"refused"`: the part is not valid, so the server refuses the call with `code`.
+   */
+  readonly kind: "widens" | "refused";
+  /**
+   * The code of a refusal. `INVALID_REQUEST`: the part is not well formed, for example a text that
+   * is not JSON, an unknown field or a time that is not a number. `FORBIDDEN` (the reason
+   * `clearance`): the clearance is not a value of the order, or the clearances have no meet.
+   */
+  readonly code?: "INVALID_REQUEST" | "FORBIDDEN" | undefined;
+  /** The reason, as a sentence. */
+  readonly message: string;
+}
+
+/** The sources of narrowing from the wire, and the notes of the parts that the decoder did not take. */
+export interface WireNarrowing {
+  /** The sources that the decoder can read, in their sequence. Each one can only narrow. */
+  readonly narrowings: readonly CapabilityRequest<unknown>[];
+  readonly notes: readonly NarrowingNote[];
+}
+
+/** A capability after a narrowing, and the notes of the parts that had no effect. */
+export interface NarrowedCapability<C = ClearanceOf> {
+  /** The narrowed capability. When the narrowing refuses the call, it is the capability that the call held. */
+  readonly capability: Capability<C>;
+  readonly notes: readonly NarrowingNote[];
+  /** The note that refuses the call, or undefined when the call can go on. */
+  readonly refusal?: NarrowingNote | undefined;
+}
+
+/** The fields of a `CapabilityRequest`. */
+const FIELDS: ReadonlySet<string> = new Set(["clearance", "effects", "timeoutMs"]);
+
+/** The fields of `PermittedEffects`. */
+const EFFECT_FIELDS: ReadonlySet<string> = new Set(["reads", "writes", "destructive"]);
+
+/** The depth of the lists and the texts in one value of the key: a list of texts of lists. */
+const MAX_DEPTH = 4;
+
+/** The value of `parseText` for a text that is not JSON. */
+const UNREADABLE: unique symbol = Symbol("unreadable");
+
+/** True for an object that is not an array and not null. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** True for a list of resource names. */
+function isNameList(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((name) => typeof name === "string");
+}
+
+/** True for a time of a narrowing: a finite number of milliseconds, zero or more. */
+function isTime(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+/** The own field of a record, or undefined. A field of the prototype (`__proto__`) does not count. */
+function own(record: Record<string, unknown>, key: string): unknown {
+  return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+
+/** A short text of a value for a note. */
+function describe(value: unknown): string {
+  try {
+    const text = JSON.stringify(value) ?? String(value);
+    return text.length > 80 ? `${text.slice(0, 77)}...` : text;
+  } catch {
+    return String(value);
+  }
+}
+
+/** The JSON value of a text, or `UNREADABLE`. */
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return UNREADABLE;
+  }
+}
+
+/**
+ * The value of a text: its JSON, or the JSON of its URI-decoded form. Two header values that a
+ * server joined with ", " are two JSON objects with a comma between them: the function reads them
+ * as a list.
+ */
+function parseText(text: string): unknown {
+  let decoded: string | undefined;
+  try {
+    decoded = decodeURIComponent(text);
+  } catch {
+    decoded = undefined;
+  }
+  for (const candidate of decoded === undefined || decoded === text ? [text] : [text, decoded]) {
+    for (const json of [candidate, `[${candidate}]`]) {
+      const value = parseJson(json);
+      if (value !== UNREADABLE) return value;
+    }
+  }
+  return UNREADABLE;
+}
+
+/** The permitted effects of a narrowing from the wire, or undefined. Each part that is not valid gets a note. */
+function effectsFromWire(value: unknown, notes: NarrowingNote[]): PermittedEffects | undefined {
+  if (!isRecord(value)) {
+    notes.push({ field: "effects", kind: "refused", code: "INVALID_REQUEST", message: `The effects of the narrowing are not an object: ${describe(value)}` });
+    return undefined;
+  }
+  const result: { reads?: readonly string[] | "any"; writes?: readonly string[] | "any"; destructive?: boolean } = {};
+  for (const kind of ["reads", "writes"] as const) {
+    const permit = own(value, kind);
+    if (permit === undefined) continue;
+    if (permit === "any") result[kind] = "any";
+    else if (isNameList(permit)) result[kind] = Object.freeze([...permit]);
+    else notes.push({ field: "effects", kind: "refused", code: "INVALID_REQUEST", message: `The ${kind} of the narrowing are not "any" or a list of names: ${describe(permit)}` });
+  }
+  const destructive = own(value, "destructive");
+  if (typeof destructive === "boolean") result.destructive = destructive;
+  else if (destructive !== undefined) notes.push({ field: "effects", kind: "refused", code: "INVALID_REQUEST", message: `The destructive flag of the narrowing is not true or false: ${describe(destructive)}` });
+  for (const key of Object.keys(value)) {
+    if (!EFFECT_FIELDS.has(key)) notes.push({ field: "effects", kind: "refused", code: "INVALID_REQUEST", message: `The effects of the narrowing have an unknown field: ${describe(key)}` });
+  }
+  return Object.keys(result).length > 0 ? (Object.freeze(result) as PermittedEffects) : undefined;
+}
+
+/** The source of one object, or undefined when it asks for nothing that the decoder can read. */
+function sourceOf(record: Record<string, unknown>, notes: NarrowingNote[]): CapabilityRequest<unknown> | undefined {
+  const narrowing: CapabilityRequest<unknown> = {};
+  const clearance = own(record, "clearance");
+  if (clearance === null) notes.push({ field: "clearance", kind: "refused", code: "INVALID_REQUEST", message: "The clearance of the narrowing is null" });
+  else if (clearance !== undefined) narrowing.clearance = clearance;
+  const effects = own(record, "effects");
+  if (effects !== undefined) {
+    const permitted = effectsFromWire(effects, notes);
+    if (permitted) narrowing.effects = permitted;
+  }
+  const timeoutMs = own(record, "timeoutMs");
+  if (isTime(timeoutMs)) narrowing.timeoutMs = timeoutMs;
+  else if (timeoutMs !== undefined) notes.push({ field: "timeoutMs", kind: "refused", code: "INVALID_REQUEST", message: `The time of the narrowing is not a number of milliseconds: ${describe(timeoutMs)}` });
+  for (const key of Object.keys(record)) {
+    if (!FIELDS.has(key)) notes.push({ field: "narrowing", kind: "refused", code: "INVALID_REQUEST", message: `The narrowing has an unknown field: ${describe(key)}` });
+  }
+  return Object.keys(narrowing).length > 0 ? narrowing : undefined;
+}
+
+/** This function reads the sources of one value of the key into `sources`. */
+function collect(value: unknown, depth: number, sources: CapabilityRequest<unknown>[], notes: NarrowingNote[]): void {
+  if (value === undefined || value === null || value === "") return;
+  if (depth > MAX_DEPTH) {
+    notes.push({ field: "narrowing", kind: "refused", code: "INVALID_REQUEST", message: "The narrowing has too many nested lists or texts" });
+    return;
+  }
+  if (typeof value === "string") {
+    const parsed = parseText(value);
+    if (parsed === UNREADABLE) notes.push({ field: "narrowing", kind: "refused", code: "INVALID_REQUEST", message: `The narrowing is not JSON: ${describe(value)}` });
+    else collect(parsed, depth + 1, sources, notes);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collect(item, depth + 1, sources, notes);
+    return;
+  }
+  if (!isRecord(value)) {
+    notes.push({ field: "narrowing", kind: "refused", code: "INVALID_REQUEST", message: `The narrowing is not a JSON object: ${describe(value)}` });
+    return;
+  }
+  const source = sourceOf(value, notes);
+  if (source) sources.push(source);
+}
+
+/**
+ * This function reads the narrowing key of a call (CLI-30). The value is a `CapabilityRequest` as
+ * an object or as the JSON text of a header, or a list of them. It reads only the own
+ * fields `clearance`, `effects` and `timeoutMs`. A part that is not valid, and a source that is
+ * not a JSON object, get a note of the kind `"refused"`: the caller refuses the call. An absent
+ * value asks for nothing and gets no note.
+ */
+export function narrowingOf(value: unknown): WireNarrowing {
+  const narrowings: CapabilityRequest<unknown>[] = [];
+  const notes: NarrowingNote[] = [];
+  collect(value, 0, narrowings, notes);
+  return { narrowings, notes };
+}
+
+/**
+ * This function adds a source to the value of the narrowing key. The result is a list of the
+ * sources, so no source replaces another. A face calls it for each source of a request: a header,
+ * a key of `X-Metadata`, the `_meta` of MCP.
+ */
+export function addNarrowing(current: unknown, source: unknown): unknown {
+  if (source === undefined) return current;
+  if (current === undefined) return source;
+  return [...(Array.isArray(current) ? current : [current]), ...(Array.isArray(source) ? source : [source])];
+}
+
+/**
+ * The clearance that a source can apply, or undefined. A value outside the order gets a note, and a
+ * value above the held clearance gets a note too.
+ */
+function clearanceOf<C>(held: C | undefined, asked: C, order: ClearanceOrder<C> | undefined, notes: NarrowingNote[]): C | undefined {
+  if (!order) return asked;
+  try {
+    // A value outside the order throws here: a ladder throws for a value that it does not have
+    order.leq(asked, asked);
+    if (held !== undefined && !Object.is(held, asked) && !order.leq(asked, held)) {
+      notes.push({ field: "clearance", kind: "widens", message: `The clearance ${describe(asked)} is not at or below the clearance of the call (${describe(held)}). The part above it has no effect.` });
+    }
+    return asked;
+  } catch {
+    notes.push({ field: "clearance", kind: "refused", code: "FORBIDDEN", message: `The clearance ${describe(asked)} is not a value of the clearance order of the server` });
+    return undefined;
+  }
+}
+
+/** The result of `meetOf` when the clearances have no meet. */
+const NO_MEET: unique symbol = Symbol("no meet");
+
+/** The meet of the held clearance and the clearances of the sources, or `NO_MEET` with a note. */
+function meetOf<C>(held: C | undefined, asked: readonly C[], order: ClearanceOrder<C> | undefined, notes: NarrowingNote[]): C | undefined | typeof NO_MEET {
+  const values = held === undefined ? [...asked] : [held, ...asked];
+  if (values.length === 0) return undefined;
+  if (!order) {
+    // Without an order, two clearances meet only when they are the same value
+    const distinct = values.filter((value, index) => values.findIndex((other) => Object.is(other, value)) === index);
+    if (distinct.length === 1) return distinct[0];
+    notes.push({ field: "clearance", kind: "refused", code: "FORBIDDEN", message: `The server has no clearance order, so it cannot meet the clearances ${distinct.map(describe).join(" and ")}` });
+    return NO_MEET;
+  }
+  try {
+    return values.reduce((met, value) => order.meet(met, value));
+  } catch (error) {
+    notes.push({ field: "clearance", kind: "refused", code: "FORBIDDEN", message: `The clearance order cannot meet the clearances: ${error instanceof Error ? error.message : String(error)}` });
+    return NO_MEET;
+  }
+}
+
+/** This function adds a note for each part of the asked effects that the held effects do not permit. */
+function noteWiderEffects(held: PermittedEffects | undefined, asked: PermittedEffects, notes: NarrowingNote[]): void {
+  for (const kind of ["reads", "writes"] as const) {
+    const permit = held?.[kind];
+    const wanted = asked[kind];
+    if (wanted === undefined || permit === undefined || permit === "any") continue;
+    const extra = wanted === "any" ? ["any"] : wanted.filter((name) => !permit.includes(name));
+    if (extra.length > 0) {
+      const holds = permit.length > 0 ? permit.join(", ") : "nothing";
+      notes.push({ field: "effects", kind: "widens", message: `The narrowing asks for the ${kind} ${extra.join(", ")}, and the call holds ${holds}. That part has no effect.` });
+    }
+  }
+  if (held?.destructive === false && asked.destructive === true) {
+    notes.push({ field: "effects", kind: "widens", message: "The narrowing permits destructive procedures, and the call does not. That part has no effect." });
+  }
+}
+
+/**
+ * This function narrows a capability with one or more sources that can come from outside the host
+ * (CLI-30). The clearance is the meet of the held clearance and of each source, the effects are the
+ * intersection, and the deadline is the earliest. Thus the result does not depend on the sequence
+ * of the sources, and each source can only make it narrower.
+ *
+ * The function does not throw. A valid part that asks for more than `held` gets a note and has no
+ * effect. A part that is not valid gives `refusal`: a time that is not a number, a clearance
+ * outside the order, or clearances without a meet (two different values and no order). Then the
+ * caller refuses the call.
+ */
+export function narrowWithin<C>(
+  held: Capability<C> | undefined,
+  asked: CapabilityRequest<unknown> | readonly CapabilityRequest<unknown>[] | undefined,
+  order?: ClearanceOrder<C>,
+  now: number = Date.now()
+): NarrowedCapability<C> {
+  const base = held ?? (UNLIMITED_CAPABILITY as Capability<C>);
+  const sources: readonly CapabilityRequest<unknown>[] = asked === undefined ? [] : Array.isArray(asked) ? asked : [asked as CapabilityRequest<unknown>];
+  if (sources.length === 0) return { capability: base, notes: [] };
+  const notes: NarrowingNote[] = [];
+  const clearances: C[] = [];
+  let capability = base;
+  for (const source of sources) {
+    if (source.clearance !== undefined) {
+      const clearance = clearanceOf(base.clearance, source.clearance as C, order, notes);
+      if (clearance !== undefined) clearances.push(clearance);
+    }
+    const part: CapabilityRequest<C> = {};
+    if (source.effects !== undefined) {
+      noteWiderEffects(base.effects, source.effects, notes);
+      part.effects = source.effects;
+    }
+    if (source.timeoutMs !== undefined) {
+      if (!isTime(source.timeoutMs)) {
+        notes.push({ field: "timeoutMs", kind: "refused", code: "INVALID_REQUEST", message: `The time of the narrowing is not a number of milliseconds: ${describe(source.timeoutMs)}` });
+      } else {
+        if (base.deadline !== undefined && now + source.timeoutMs > base.deadline) {
+          notes.push({ field: "timeoutMs", kind: "widens", message: `The narrowing asks for ${source.timeoutMs} ms, and the deadline of the call is earlier. That part has no effect.` });
+        }
+        part.timeoutMs = source.timeoutMs;
+      }
+    }
+    // Without a clearance, the narrowing of the effects and of the time does not throw
+    capability = narrowCapability(capability, part, order, now);
+  }
+  const met = meetOf(base.clearance, clearances, order, notes);
+  const refused = notes.find((note) => note.kind === "refused");
+  if (met === NO_MEET || refused) return { capability: base, notes, refusal: refused };
+  if (met !== undefined) {
+    try {
+      capability = narrowCapability(capability, { clearance: met }, order, now);
+    } catch (error) {
+      const refusal: NarrowingNote = { field: "clearance", kind: "refused", code: "FORBIDDEN", message: `The clearance order cannot meet the clearances: ${error instanceof Error ? error.message : String(error)}` };
+      notes.push(refusal);
+      return { capability: base, notes, refusal };
+    }
+  }
+  return { capability, notes };
+}

package/src/procedures/types.ts

@@ -259,6 +259,22 @@ export interface RepositoryProvider {
    */
   getStorage<T>(collection: string): CollectionStorage<T>;
 
+  /**
+   * The storage of one partition of a collection (roadmap CLI-17), for example the items of one
+   * tenant. A repository without this method has no partitions: the collection procedures then
+   * refuse a call with a partition, and never give it the storage of all partitions.
+   */
+  getPartitionStorage?<T>(collection: string, partition: string): CollectionStorage<T>;
+
+  /** True when the collection has partitions (roadmap CLI-17). Then a call resolves its partition with `resolvePartition`. */
+  hasPartitions?(collection: string): boolean;
+
+  /**
+   * The partition of a call to a partitioned collection (roadmap CLI-17): from the context (the
+   * tenant of `ctx.principal`) and the partition that the call asks for. `null` refuses the call.
+   */
+  resolvePartition?(collection: string, ctx: ProcedureContext, requested: string | undefined): string | undefined | null | Promise<string | undefined | null>;
+
   /**
    * Check if a collection exists.
    *
@@ -383,6 +399,13 @@ export interface ProcedureContext {
    */
   caller?: AnyProcedure | undefined;
 
+  /**
+   * The absolute path of the root of the files, for a procedure that a host confines to it
+   * (roadmap R33). `confineToRoot()` of `@procedures/fs` sets it for each procedure with rules. A
+   * procedure that starts a program uses it to keep the program in the root. Absent without a root.
+   */
+  fsRoot?: string | undefined;
+
   /**
    * The principal of the call: who sends it. The server sets it from its authentication (the
    * token, the request hook `principalOf`, `authenticate`). The nested calls get the same

package/src/server/index.ts

@@ -39,7 +39,7 @@ export type { ServerOptions } from "./server.js";
 
 export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream } from "./procedure-server.js";
 export type { ProcedureServerOptions, StorageConfig, StopOptions, UseStorageOptions } from "./procedure-server.js";
-export { pathToMethod, methodToPath } from "./method.js";
+export { pathToMethod, methodToPath, methodName } from "./method.js";
 export {
   HandlerNotFoundError,
   ServerError,
@@ -51,6 +51,7 @@ export {
   type PrincipalOf,
   type RequestIdentity,
   type AmbientCredentials,
+  type ServerDebugReport,
   type ServerHandler,
   type ServerMiddleware,
   type ServerContext,

package/src/server/method.ts

@@ -14,20 +14,32 @@ import type { Method } from "../client/types.js";
 import type { ProcedurePath } from "../procedures/types.js";
 
 /**
- * This function gives the transport method of a procedure path. A path needs at least two
- * segments, because a method has a service and an operation.
+ * This function gives the transport method of a procedure path. The last segment is the
+ * operation, and the other segments, joined with dots, are the service. A path of one segment,
+ * for example `["morning"]`, has the empty service (CLI-28). An empty path throws.
  */
 export function pathToMethod(path: readonly string[]): Method {
-  if (path.length < 2) {
-    throw new Error(`Invalid procedure path (it needs two segments or more): ${path.join(".")}`);
+  if (path.length === 0) {
+    throw new Error("Invalid procedure path: it needs one segment or more");
   }
   return { service: path.slice(0, -1).join("."), operation: path[path.length - 1]! };
 }
 
+/**
+ * The name of a method with dots: `docker.compose.up`, or only the operation for the empty
+ * service of a path of one segment (`morning`).
+ */
+export function methodName(method: Pick<Method, "service" | "operation">): string {
+  return method.service === "" ? method.operation : `${method.service}.${method.operation}`;
+}
+
 /**
  * This function gives the procedure path of a transport method. It accepts both encodings:
  * `{ service: "a.b", operation: "c" }` and `{ service: "a", operation: "b.c" }` give `["a", "b", "c"]`.
  */
 export function methodToPath(method: Pick<Method, "service" | "operation">): ProcedurePath {
-  return [...method.service.split("."), ...method.operation.split(".")].filter((segment) => segment !== "");
+  // The empty service of a path of one segment has no segment. Each other empty segment stays, so
+  // a method with ".." or a stray dot names no procedure: the registry has no empty segment (CLI-28)
+  const service = method.service === "" ? [] : method.service.split(".");
+  return [...service, ...method.operation.split(".")];
 }

package/src/server/procedure-server.ts

@@ -18,7 +18,8 @@ import { pathToKey } from "../procedures/types.js";
 import { ProcedureRegistry, PROCEDURE_REGISTRY } from "../procedures/registry.js";
 import { createCollectionProcedures } from "../procedures/collection/procedures.js";
 import { InvocationError, invokeProcedure, type AdmitItem, type Interceptor, type Invocation } from "../procedures/invoke.js";
-import type { Capability, ClearanceOrder, ResourcesOf } from "../procedures/types.js";
+import type { Capability, ClearanceOrder, ProcedureContext, ResourcesOf } from "../procedures/types.js";
+import type { CollectionPartitions } from "../procedures/collection/partition.js";
 import { TIMEOUT_METADATA_KEY, effectsOf, joinNarrowing, narrowCapability } from "../procedures/capability.js";
 import { IdempotencyCache, idempotencyKeyOf, isRepeatable, type IdempotencyOptions } from "../procedures/idempotency.js";
 import { optionalMs, type Duration } from "../duration.js";
@@ -29,6 +30,8 @@ import { errorCodeOf } from "../protocol.js";
 import { EventPublisher, type EventPublisherOptions } from "../events/publisher.js";
 import { getGlobalEventBus } from "../events/bus.js";
 import type { CollectionProceduresOptions } from "../procedures/collection/procedures.js";
+import type { NarrowingNote } from "../procedures/narrowing.js";
+import type { ServerDebugReport } from "./types.js";
 
 // =============================================================================
 // Types
@@ -165,6 +168,15 @@ export interface ProcedureServerOptions extends ServerOptions {
    * `stop()` ends each subscription first, with `UNAVAILABLE`.
    */
   events?: EventPublisherOptions | EventPublisher | undefined;
+
+  /**
+   * The debug reports of the server. `true` writes each report with `console.debug`, and a
+   * function gets each report. The server reports each part of the narrowing of a call that has
+   * no effect (CLI-30). Such a part asks for more than the call holds, or it is not valid. The
+   * call goes on without that part. The server also reports a source that refuses the call.
+   * @default false
+   */
+  debug?: boolean | ((report: ServerDebugReport) => void) | undefined;
 }
 
 /**
@@ -316,6 +328,8 @@ export function errorResponse(id: string, error: unknown): ServerResponse<unknow
 export class ProcedureServer extends Server implements RepositoryProvider {
   private readonly procedureRegistry: ProcedureRegistry;
   private readonly storages = new Map<string, CollectionStorage<unknown>>();
+  /** The partitions of each partitioned collection: their storages and their resolver (roadmap CLI-17) */
+  private readonly partitions = new Map<string, CollectionPartitions<unknown>>();
   /** For each storage: the calls in flight that took it, and the closes that wait for them */
   private readonly storageUses = new Map<CollectionStorage<unknown>, { calls: number; waiters: Array<() => void> }>();
   /** The clock of the wait of `useStorage` */
@@ -358,6 +372,8 @@ export class ProcedureServer extends Server implements RepositoryProvider {
    * read it: they trust such a request only from a named origin (CSRF).
    */
   readonly ambientCredentials: AmbientCredentials | undefined;
+  /** The receiver of the debug reports, or undefined when the option `debug` is off. */
+  private readonly debugReport: ((report: ServerDebugReport) => void) | undefined;
 
   constructor(options: ProcedureServerOptions = {}) {
     super(options);
@@ -379,6 +395,12 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     this.authenticate = options.authenticate;
     const ambient = options.ambientCredentials ?? (this.principalOf ? "always" : this.authenticate ? "cookies" : undefined);
     this.ambientCredentials = ambient === false ? undefined : ambient;
+    this.debugReport =
+      typeof options.debug === "function"
+        ? options.debug
+        : options.debug === true
+          ? (report) => console.debug(`[ProcedureServer] ${report.topic} of ${report.requestId}: ${report.message}`)
+          : undefined;
     // The remote events: the server pins events.subscribe, as it pins host.health (EVENTS.md)
     this.publisher = options.events instanceof EventPublisher ? options.events : options.events ? new EventPublisher(options.events) : undefined;
     if (this.publisher) this.registerProcedure(this.publisher.procedure);
@@ -421,7 +443,59 @@ export class ProcedureServer extends Server implements RepositoryProvider {
    * @param collection - Collection name
    */
   hasCollection(collection: string): boolean {
-    return this.storages.has(collection);
+    return this.storages.has(collection) || this.partitions.has(collection);
+  }
+
+  /**
+   * The storage of one partition of a collection (roadmap CLI-17).
+   *
+   * @throws Error if the collection has no partitions
+   */
+  getPartitionStorage<T>(collection: string, partition: string): CollectionStorage<T> {
+    const partitions = this.partitions.get(collection);
+    if (!partitions) {
+      throw new Error(`Collection has no partitions: ${collection}`);
+    }
+    return partitions.storageOf(partition) as CollectionStorage<T>;
+  }
+
+  /** True when the collection has partitions (roadmap CLI-17). */
+  hasPartitions(collection: string): boolean {
+    return this.partitions.has(collection);
+  }
+
+  /**
+   * The partition of a call to a partitioned collection (roadmap CLI-17), from the resolver of
+   * `usePartitions`. `null` refuses the call.
+   *
+   * @throws Error if the collection has no partitions
+   */
+  resolvePartition(collection: string, ctx: ProcedureContext, requested: string | undefined): string | undefined | null | Promise<string | undefined | null> {
+    const partitions = this.partitions.get(collection);
+    if (!partitions) {
+      throw new Error(`Collection has no partitions: ${collection}`);
+    }
+    return partitions.resolve(ctx, requested);
+  }
+
+  /**
+   * Configure the partitions of a collection (roadmap CLI-17). `resolve` gives the partition of
+   * each call from its context (the tenant of `ctx.principal`) and the partition that the call asks
+   * for: the collection procedures and the subscriptions of `EventPublisher` use it. `storageOf`
+   * gives the storage of a partition: give the same storage for the same partition each time.
+   *
+   * @param name - Collection name, without a dot
+   * @param partitions - The storage of each partition, and the resolver
+   * @returns this (for chaining)
+   * @throws Error if the name has a dot
+   */
+  usePartitions<T>(name: string, partitions: CollectionPartitions<T>): this {
+    // The topic `collections.<name>.<partition>` names the partition after the first dot
+    if (name.includes(".")) {
+      throw new Error(`A collection with partitions cannot have a dot in its name: ${name}`);
+    }
+    this.partitions.set(name, partitions as CollectionPartitions<unknown>);
+    return this;
   }
 
   // ===========================================================================
@@ -503,17 +577,20 @@ export class ProcedureServer extends Server implements RepositoryProvider {
   private callRepository(): { repository: RepositoryProvider; release: () => void } {
     const taken = new Set<CollectionStorage<unknown>>();
     let released = false;
+    const take = <T>(storage: CollectionStorage<unknown>): CollectionStorage<T> => {
+      if (!released && !taken.has(storage)) {
+        taken.add(storage);
+        const use = this.storageUses.get(storage) ?? { calls: 0, waiters: [] };
+        use.calls++;
+        this.storageUses.set(storage, use);
+      }
+      return storage as CollectionStorage<T>;
+    };
     const repository: RepositoryProvider = {
-      getStorage: <T>(collection: string): CollectionStorage<T> => {
-        const storage = this.getStorage<unknown>(collection);
-        if (!released && !taken.has(storage)) {
-          taken.add(storage);
-          const use = this.storageUses.get(storage) ?? { calls: 0, waiters: [] };
-          use.calls++;
-          this.storageUses.set(storage, use);
-        }
-        return storage as CollectionStorage<T>;
-      },
+      getStorage: <T>(collection: string): CollectionStorage<T> => take<T>(this.getStorage<unknown>(collection)),
+      getPartitionStorage: <T>(collection: string, partition: string): CollectionStorage<T> => take<T>(this.getPartitionStorage<unknown>(collection, partition)),
+      hasPartitions: (collection: string): boolean => this.hasPartitions(collection),
+      resolvePartition: (collection: string, ctx: ProcedureContext, requested: string | undefined) => this.resolvePartition(collection, ctx, requested),
       hasCollection: (collection: string): boolean => this.hasCollection(collection),
     };
     const release = (): void => {
@@ -564,7 +641,7 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     if (!procedure.handler) {
       throw new Error(`Procedure at ${pathToKey(procedure.path)} has no handler`);
     }
-    // The path must make a method: this throws for a path of one segment
+    // The path must make a method: this throws for an empty path. One segment or more is valid (CLI-28)
     pathToMethod(procedure.path);
     this.pinnedProcedures.set(pathToKey(procedure.path), procedure);
   }
@@ -784,6 +861,9 @@ export class ProcedureServer extends Server implements RepositoryProvider {
    * The capability of a request. It comes from the server, never from the request. The remaining
    * time of the caller and the narrowing of the request can only make it narrower
    * (CAPABILITIES-2026-10, decision 9). Two different clearances without an order throw.
+   *
+   * The narrowing key of the call (`procedure-narrowing`, CLI-30) is not part of it. The
+   * invocation applies the key for each face, after the narrowing of the request hook.
    */
   private capabilityOf(request: ServerRequest<unknown>): Capability | undefined {
     const { capability, clearanceOrder } = this.capabilityOptions;
@@ -791,6 +871,17 @@ export class ProcedureServer extends Server implements RepositoryProvider {
     return request.narrowing ? narrowCapability(base, request.narrowing, clearanceOrder) : base;
   }
 
+  /** The debug reports of the notes of the narrowing of a request (CLI-30), or undefined when `debug` is off. */
+  private narrowingReports(request: ServerRequest<unknown>): ((notes: readonly NarrowingNote[]) => void) | undefined {
+    const report = this.debugReport;
+    if (!report) return undefined;
+    return (notes) => {
+      for (const note of notes) {
+        report({ topic: "narrowing", requestId: request.id, method: request.method, message: note.message, detail: { field: note.field, kind: note.kind, ...(note.code ? { code: note.code } : {}) } });
+      }
+    };
+  }
+
   /** Run a procedure for a request with a signal. */
   private async run(procedure: AnyProcedure, request: ServerRequest<unknown>, signal: AbortSignal | undefined): Promise<ServerResponse<unknown>> {
     // The call uses the storages that it takes until its end: the end of a stream, for a stream
@@ -822,6 +913,8 @@ export class ProcedureServer extends Server implements RepositoryProvider {
         clearanceOrder,
         resources,
         admitItem,
+        // The parts of the narrowing key without effect go to the debug reports (CLI-30)
+        onNarrowingNotes: this.narrowingReports(request),
         // The principal of the authentication: ctx.principal, and the nested calls (R18)
         ...(request.principal !== undefined ? { principal: request.principal } : {}),
         // The bus of the remote events is the bus of the procedures (EVENTS.md)