@procedures/client 0.8.1 → 0.9.1

package/src/procedures/collection/partition.ts

@@ -0,0 +1,145 @@
+/**
+ * The partitions of a collection (roadmap CLI-17). One `collections.<name>.*` surface serves the
+ * items of several partitions, for example one per tenant, or one per tenant and scope. Each call
+ * reads and writes one partition.
+ *
+ * - The host registers the partitions of a collection with its repository: the storage of each
+ *   partition and the resolver (`ProcedureServer.usePartitions(name, { storageOf, resolve })`).
+ * - The input of a call can ask for a partition (`partition`, for example a scope). The resolver
+ *   gives the partition of the call from its context: the tenant comes from the principal, never
+ *   from the input alone. It can refuse the call.
+ * - A subscriber names the partition that it asks for in the topic, as an input does:
+ *   `collections.<name>.<requested>`. The publisher resolves it in the same way and listens to the
+ *   topic of the resolved partition, so a subscriber cannot name the topic of another tenant.
+ * - A collection without partitions refuses a call or a topic with a partition.
+ */
+import type { ZodLike } from "../../client/validation/types.js";
+import { InvocationError } from "../invoke.js";
+import type { ProcedureContext, RepositoryProvider } from "../types.js";
+import type { CollectionStorage } from "./storage.js";
+
+/** The characters of a partition: letters, digits and `_ . : @ ~ + | / -`, 256 at most. */
+export const PARTITION_PATTERN: RegExp = /^[A-Za-z0-9_.:@~+|/-]{1,256}$/;
+
+/** The field of an input that asks for a partition. */
+export interface PartitionInput {
+  partition?: string;
+}
+
+/**
+ * The resolver of the partition of a call. It gets the context (with `ctx.principal`) and the
+ * partition that the input asks for. It gives the partition, `undefined` for the storage of the
+ * collection without a partition, or `null` to refuse the call (`FORBIDDEN`, reason
+ * `partition-not-allowed`). An error that it throws passes through.
+ *
+ * The contract: the resolver gives a partition of the caller, or `null`. It never gives the
+ * partition of another tenant. A resolver that maps a request of tenant B to the partition of
+ * tenant A is a defect of the app: the events of A then reach B under the topic that B named, and
+ * a `HybridStorage` of B keeps the items of A.
+ */
+export type PartitionResolver = (ctx: ProcedureContext, requested: string | undefined) => string | undefined | null | Promise<string | undefined | null>;
+
+/**
+ * This function adds the field `partition` to the input schema of a collection procedure. The
+ * repository of the call decides at the call if the collection has partitions.
+ */
+export function withPartition<T>(schema: ZodLike<T>): ZodLike<T & PartitionInput> {
+  const validate = (data: unknown): { success: true; data: T & PartitionInput } | { success: false; error: { message: string; errors: { path: (string | number)[]; message: string }[] } } => {
+    const fail = (message: string) => ({ success: false as const, error: { message, errors: [{ path: ["partition"], message }] } });
+    const requested = typeof data === "object" && data !== null && !Array.isArray(data) ? (data as Record<string, unknown>)["partition"] : undefined;
+    if (requested !== undefined && (typeof requested !== "string" || !PARTITION_PATTERN.test(requested))) {
+      return fail("partition must have 1 to 256 letters, digits or the characters _ . : @ ~ + | / -");
+    }
+    const inner = schema.safeParse(data);
+    if (!inner.success) return inner as { success: false; error: { message: string; errors: { path: (string | number)[]; message: string }[] } };
+    const parsed = inner.data as T & PartitionInput;
+    return { success: true, data: requested === undefined ? parsed : { ...parsed, partition: requested as string } };
+  };
+  return {
+    parse(data: unknown) {
+      const result = validate(data);
+      if (result.success) return result.data;
+      throw new Error(result.error.message);
+    },
+    safeParse: validate,
+  } as ZodLike<T & PartitionInput>;
+}
+
+/** The partitions of a collection: the storage of each partition, and the resolver of a call. */
+export interface CollectionPartitions<T = unknown> {
+  /**
+   * The storage of a partition. Give the same storage for the same partition each time: the change
+   * events of a storage keep their order with it.
+   */
+  storageOf(partition: string): CollectionStorage<T>;
+  /** The resolver of the partition of a call. */
+  resolve: PartitionResolver;
+}
+
+/** The refusal of a partition. */
+function partitionRefused(ctx: ProcedureContext, message: string): InvocationError {
+  return new InvocationError("FORBIDDEN", message, ctx.path, "partition-not-allowed");
+}
+
+/**
+ * This function gives the partition of a call to a collection: the resolver of the repository
+ * gives it from the context and the requested partition. It throws `FORBIDDEN` (reason
+ * `partition-not-allowed`) when the resolver refuses, or when the collection has no partitions and
+ * the call asks for one.
+ */
+export async function partitionOfCall(ctx: ProcedureContext, collection: string, requested: string | undefined): Promise<string | undefined> {
+  const repository = ctx.repository;
+  if (!repository?.hasPartitions?.(collection) || !repository.resolvePartition) {
+    if (requested !== undefined) throw partitionRefused(ctx, `The collection ${collection} has no partitions`);
+    return undefined;
+  }
+  const partition = await repository.resolvePartition(collection, ctx, requested);
+  if (partition === null) {
+    throw partitionRefused(ctx, `The call cannot use the partition${requested === undefined ? "" : ` "${requested}"`} of ${collection}`);
+  }
+  if (partition !== undefined && !PARTITION_PATTERN.test(partition)) {
+    throw new Error(`The partition resolver gave a partition that is not valid: ${JSON.stringify(partition).slice(0, 80)}`);
+  }
+  return partition;
+}
+
+/**
+ * This function gives the storage of a call: of the collection, or of its partition. A repository
+ * without `getPartitionStorage` refuses a partition.
+ */
+export function storageOfCall<T>(ctx: ProcedureContext, collection: string, partition: string | undefined): CollectionStorage<T> {
+  const repository = ctx.repository;
+  if (!repository) throw new Error("Repository not available in procedure context");
+  if (partition === undefined) return repository.getStorage<T>(collection);
+  if (!repository.getPartitionStorage) {
+    throw new Error(`The repository has no partitions, so it cannot give the partition "${partition}" of ${collection}`);
+  }
+  return repository.getPartitionStorage<T>(collection, partition);
+}
+
+/**
+ * This function gives the collection and the partition part of a topic of a call, with the
+ * repository of the call: one rule for the read check and for the listener of the publisher.
+ *
+ * - A collection of the repository without partitions whose name is the whole rest of the topic
+ *   wins: its name can have a dot.
+ * - Else the first part after `collections.` names the collection, and the rest is the partition
+ *   that the call asks for. A collection with partitions has no dot in its name.
+ */
+export function collectionTopicTarget(topic: string, repository: RepositoryProvider | undefined): { collection: string; partition: string | undefined } | undefined {
+  if (!topic.startsWith("collections.")) return undefined;
+  const whole = topic.slice("collections.".length);
+  if (whole !== "" && repository?.hasCollection(whole) && !repository.hasPartitions?.(whole)) return { collection: whole, partition: undefined };
+  return collectionTopicPartition(topic);
+}
+
+/**
+ * This function gives the collection and the partition part of a topic `collections.<name>` or
+ * `collections.<name>.<partition>`, or undefined for another topic. It reads the topic alone:
+ * `collectionTopicTarget` also knows the collections of a repository.
+ */
+export function collectionTopicPartition(topic: string): { collection: string; partition: string | undefined } | undefined {
+  const match = /^collections\.([^.]+)(?:\.(.+))?$/.exec(topic);
+  if (!match) return undefined;
+  return { collection: match[1]!, partition: match[2] };
+}

package/src/procedures/collection/procedures.ts

@@ -59,6 +59,7 @@ import {
 import { DEFAULT_FIND_LIMIT, applyPatch, queryEntries, type StoragePatch, type StorageQueryOptions, type StorageQueryPolicy } from "./query.js";
 import type { CollectionStorage, StorageWriteOptions } from "./storage.js";
 import { collectionChangeTopic, startChangeChain, writeWithChangeEvent } from "./changes.js";
+import { partitionOfCall, storageOfCall, withPartition, type PartitionInput } from "./partition.js";
 
 // =============================================================================
 // Handler Factory
@@ -75,17 +76,6 @@ function getCollectionFromPath(path: string[]): string {
   return path[1]!;
 }
 
-/**
- * Get storage from context, throwing if repository is not available.
- */
-function getStorage<T>(ctx: ProcedureContext): ReturnType<NonNullable<ProcedureContext["repository"]>["getStorage"]> {
-  if (!ctx.repository) {
-    throw new Error("Repository not available in procedure context");
-  }
-  const collection = getCollectionFromPath(ctx.path);
-  return ctx.repository.getStorage<T>(collection);
-}
-
 /** The options of a query from the input of `find`. */
 function queryOptionsOf(input: FindInput, policy: StorageQueryPolicy): StorageQueryOptions {
   // A find without a limit gets the maxLimit of the policy (roadmap CLI-14)
@@ -100,11 +90,11 @@ function queryOptionsOf(input: FindInput, policy: StorageQueryPolicy): StorageQu
 /** The options of the change events of the collection procedures (roadmap CLI-15). */
 export interface CollectionChangeEventsOptions {
   /**
-   * The topic of the change events of a call, or undefined for no event. The partition of a
-   * collection (roadmap CLI-17) goes into the topic here, for example from the scope of the call.
-   * @default the topic `collections.<name>` of `collectionChangeTopic()`
+   * The topic of the change events of a call, or undefined for no event. It gets the partition of
+   * the call (roadmap CLI-17).
+   * @default `collectionChangeTopic(name, partition)`: `collections.<name>`, or `collections.<name>.<partition>`
    */
-  topic?: ((collection: string, ctx: ProcedureContext) => string | undefined) | undefined;
+  topic?: ((collection: string, ctx: ProcedureContext, partition: string | undefined) => string | undefined) | undefined;
   /**
    * True: the events also carry the values of the changed items. Each row `{ id, value }` passes
    * the output filter of the host (`admitItem`) for each subscriber, and a refused row stays out of
@@ -196,29 +186,38 @@ export function createCollectionProcedures(collectionName: string, options: Coll
   const queryPolicy: StorageQueryPolicy = { ...options.queryPolicy, maxLimit: options.queryPolicy?.maxLimit ?? DEFAULT_FIND_LIMIT };
   // Each collection is a resource of its own (CAPABILITIES-2026-10): a capability can permit one
   const resource = `collection:${collectionName}`;
-  // The topic of the change events of a call (roadmap CLI-15). CLI-17 adds the partition with the option topic.
+  // The topic of the change events of a call (roadmap CLI-15), with its partition (roadmap CLI-17)
   const events = options.changeEvents ?? true;
-  const topicRule: ((collection: string, ctx: ProcedureContext) => string | undefined) | undefined =
-    events === false ? undefined : (events !== true && events.topic) || ((name: string) => collectionChangeTopic(name));
-  const topicOf = (ctx: ProcedureContext): string | undefined => topicRule?.(collectionName, ctx);
+  const topicRule: ((collection: string, ctx: ProcedureContext, partition: string | undefined) => string | undefined) | undefined =
+    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 changing = <R>(ctx: ProcedureContext, storage: CollectionStorage<unknown>, ids: readonly string[] | "*", origin: string | undefined, write: () => Promise<R>): Promise<R> =>
-    writeWithChangeEvent(ctx.bus, storage, topicRule ? topicOf(ctx) : undefined, ids, origin, write, withValues);
+  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);
+  /**
+   * 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.
+   */
+  const storageOf = async (input: PartitionInput, ctx: ProcedureContext): Promise<{ storage: 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 };
+  };
 
   return [
     // Get
     defineProcedure({
       path: [...basePath, "get"],
-      input: getInputSchema,
+      input: withPartition(getInputSchema),
       output: getOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get item from ${collectionName} by ID`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (input: GetInput, ctx : ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: GetInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         const value = await storage.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
@@ -230,47 +229,47 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // Set
     defineProcedure({
       path: [...basePath, "set"],
-      input: setInputSchema,
+      input: withPartition(setInputSchema),
       output: setOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Set item in ${collectionName}`,
         tags: ["collections", collectionName, "write"],
       },
-      handler: async (input: SetInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
-        await changing(ctx, storage, [input.id], input.origin, () => storage.set(input.id, input.value, writeOptionsOf(input)));
+      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)));
       },
     }),
 
     // Delete
     defineProcedure({
       path: [...basePath, "delete"],
-      input: deleteInputSchema,
+      input: withPartition(deleteInputSchema),
       output: deleteOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Delete item from ${collectionName}`,
         tags: ["collections", collectionName, "write"],
       },
-      handler: async (input: DeleteInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
-        return changing(ctx, storage, [input.id], input.origin, () => storage.delete(input.id, writeOptionsOf(input)));
+      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)));
       },
     }),
 
     // Has
     defineProcedure({
       path: [...basePath, "has"],
-      input: hasInputSchema,
+      input: withPartition(hasInputSchema),
       output: hasOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Check if item exists in ${collectionName}`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (input: HasInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: HasInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         return storage.has(input.id);
       },
     }),
@@ -278,15 +277,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // GetAll
     defineProcedure({
       path: [...basePath, "getAll"],
-      input: getAllInputSchema,
+      input: withPartition(getAllInputSchema),
       output: getAllOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get all items from ${collectionName}`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (_input: GetAllInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: GetAllInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         return storage.getAll();
       },
     }),
@@ -294,15 +293,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // Entries: each item with its id, for a sync (roadmap R2)
     defineProcedure({
       path: [...basePath, "entries"],
-      input: entriesInputSchema,
+      input: withPartition(entriesInputSchema),
       output: entriesOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get all items of ${collectionName} with their ids`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (_input: EntriesInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: EntriesInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         if (!storage.getEntries) {
           throw new Error(`The storage of ${collectionName} cannot give the ids of its items`);
         }
@@ -313,15 +312,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // Ids: the ids of the items without the values, for a full sync
     defineProcedure({
       path: [...basePath, "ids"],
-      input: idsInputSchema,
+      input: withPartition(idsInputSchema),
       output: idsOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get the ids of the items of ${collectionName}, without the values`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (_input: IdsInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: IdsInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         if (storage.getIds) return storage.getIds();
         // A storage without getIds() gives its entries: the values stay on the server
         if (storage.getEntries) return (await storage.getEntries()).map(([id]) => id);
@@ -332,20 +331,20 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // Changes: the items that changed after a version, for a delta sync (roadmap R28)
     defineProcedure({
       path: [...basePath, "changes"],
-      input: changesInputSchema,
+      input: withPartition(changesInputSchema),
       output: changesOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get the items of ${collectionName} that changed after a version`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (input: ChangesInput, ctx: ProcedureContext): Promise<ChangesOutput> => {
-        const storage = getStorage(ctx);
+      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);
           // 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), changes.version);
+          if (topicRule) startChangeChain(ctx.bus, storage, topicOf(ctx, partition), changes.version);
           return {
             version: changes.version,
             full: changes.full,
@@ -366,15 +365,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // Find: the items that match a JSON selector, with an order, a skip and a limit (roadmap CLI-14)
     defineProcedure({
       path: [...basePath, "find"],
-      input: findInputSchemaOf(queryPolicy),
+      input: withPartition(findInputSchemaOf(queryPolicy)),
       output: findOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Find the items of ${collectionName} that match a selector, with their ids, an order, a skip and a limit`,
         tags: ["collections", collectionName, "read", "query"],
       },
-      handler: async (input: FindInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: FindInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = 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
@@ -390,17 +389,17 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // Patch: merge fields into one item, a JSON Merge Patch (roadmap CLI-14)
     defineProcedure({
       path: [...basePath, "patch"],
-      input: patchInputSchema,
+      input: withPartition(patchInputSchema),
       output: patchOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Merge fields into one item of ${collectionName}: a JSON Merge Patch, or the operations $set and $unset`,
         tags: ["collections", collectionName, "write"],
       },
-      handler: async (input: PatchInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: PatchInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage, partition } = await storageOf(input, ctx);
         const write = writeOptionsOf(input);
-        const value = await changing(ctx, storage, [input.id], input.origin, () =>
+        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 };
@@ -411,15 +410,15 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // Size
     defineProcedure({
       path: [...basePath, "size"],
-      input: sizeInputSchema,
+      input: withPartition(sizeInputSchema),
       output: sizeOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get number of items in ${collectionName}`,
         tags: ["collections", collectionName, "read"],
       },
-      handler: async (_input: SizeInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: SizeInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         return storage.size();
       },
     }),
@@ -427,31 +426,31 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // Clear
     defineProcedure({
       path: [...basePath, "clear"],
-      input: clearInputSchema,
+      input: withPartition(clearInputSchema),
       output: clearOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Clear all items from ${collectionName}`,
         tags: ["collections", collectionName, "write"],
       },
-      handler: async (input: ClearInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
-        await changing(ctx, storage, "*", input.origin, () => storage.clear(writeOptionsOf(input)));
+      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)));
       },
     }),
 
     // GetBatch
     defineProcedure({
       path: [...basePath, "getBatch"],
-      input: getBatchInputSchema,
+      input: withPartition(getBatchInputSchema),
       output: getBatchOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [] },
         description: `Get multiple items from ${collectionName}`,
         tags: ["collections", collectionName, "read", "batch"],
       },
-      handler: async (input: GetBatchInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: GetBatchInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage } = await storageOf(input, ctx);
         const result = await storage.getBatch(input.ids);
         // Convert Map to plain object
         return Object.fromEntries(result);
@@ -461,36 +460,36 @@ export function createCollectionProcedures(collectionName: string, options: Coll
     // SetBatch
     defineProcedure({
       path: [...basePath, "setBatch"],
-      input: setBatchInputSchema,
+      input: withPartition(setBatchInputSchema),
       output: setBatchOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Set multiple items in ${collectionName}`,
         tags: ["collections", collectionName, "write", "batch"],
       },
-      handler: async (input: SetBatchInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
+      handler: async (input: SetBatchInput & PartitionInput, ctx: ProcedureContext) => {
+        const { storage, partition } = await storageOf(input, ctx);
         const items: Array<[string, unknown]> = input.items.map((item) => [
           item.id,
           item.value,
         ]);
-        await changing(ctx, storage, items.map(([id]) => id), input.origin, () => storage.setBatch(items, writeOptionsOf(input)));
+        await changing(ctx, partition, storage, items.map(([id]) => id), input.origin, () => storage.setBatch(items, writeOptionsOf(input)));
       },
     }),
 
     // DeleteBatch
     defineProcedure({
       path: [...basePath, "deleteBatch"],
-      input: deleteBatchInputSchema,
+      input: withPartition(deleteBatchInputSchema),
       output: deleteBatchOutputSchema,
       metadata: {
         effects: { reads: [resource], writes: [resource], idempotent: true },
         description: `Delete multiple items from ${collectionName}`,
         tags: ["collections", collectionName, "write", "batch"],
       },
-      handler: async (input: DeleteBatchInput, ctx: ProcedureContext) => {
-        const storage = getStorage(ctx);
-        return changing(ctx, storage, input.ids, input.origin, () => storage.deleteBatch(input.ids, writeOptionsOf(input)));
+      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)));
       },
     }),
   ];

package/src/procedures/index.ts

@@ -107,6 +107,9 @@ export type { ToolHintOverride } from "./hints.js";
 export { untrustedText, untrustedFieldsOf, untrustedTextsOf } from "./untrusted.js";
 export type { UntrustedText, UntrustedSource, UntrustedValue } from "./untrusted.js";
 export type { ToolHints, CapabilityRefusal, CapabilityRefusalReason, InvocationExplanation, EffectsViolation } from "./capability.js";
+// The narrowing key of a call (CLI-30)
+export { NARROWING_METADATA_KEY, NARROWING_HEADER, narrowingOf, narrowWithin, addNarrowing } from "./narrowing.js";
+export type { NarrowingNote, WireNarrowing, NarrowedCapability } from "./narrowing.js";
 
 // Registry
 export { ProcedureRegistry, RegistryError, PROCEDURE_REGISTRY, assertValidPath } from "./registry.js";
@@ -127,6 +130,9 @@ export {
   createCollectionProcedures,
   collectionChangeTopic,
   collectionTopicReads,
+  PARTITION_PATTERN,
+  collectionTopicPartition,
+  collectionTopicTarget,
   DEFAULT_FIND_LIMIT,
   DEFAULT_QUERY_OPERATORS,
   DEFAULT_QUERY_POLICY,
@@ -146,6 +152,9 @@ export type {
   CollectionProceduresOptions,
   CollectionChangeEventsOptions,
   CollectionChangeEvent,
+  CollectionPartitions,
+  PartitionInput,
+  PartitionResolver,
   StoragePatchOperations,
   StorageQueryOperator,
   StorageQueryPolicy,

package/src/procedures/invoke.ts

@@ -39,6 +39,7 @@ import { PROCEDURE_REGISTRY } from "./registry.js";
 import { nestedCallRefusal } from "./policy.js";
 import { scopeOf, withScope, type HydrationEvent } from "./ref.js";
 import { UNLIMITED_CAPABILITY, capabilityRefusal, examinesNestedCall, narrowCapability, type CapabilityRefusalReason } from "./capability.js";
+import { NARROWING_METADATA_KEY, narrowWithin, narrowingOf, type NarrowingNote } from "./narrowing.js";
 import { timeoutAfterMs } from "./interceptors.js";
 import type { Elicit } from "./elicit.js";
 import type { ReportProgress } from "./progress.js";
@@ -73,8 +74,10 @@ export type InvocationErrorCode =
  *   to such a host (`createHttpModule({ allow })` of `@procedures/http`).
  * - `topic-not-allowed`: the `allow` function of an `EventPublisher` refuses a topic of a
  *   subscription (`documentation/EVENTS.md`).
+ * - `partition-not-allowed`: the partition resolver of the collection procedures refuses the
+ *   partition of a call (roadmap CLI-17).
  */
-export type ForbiddenReason = CapabilityRefusalReason | "outside-root" | "host-not-allowed" | "topic-not-allowed";
+export type ForbiddenReason = CapabilityRefusalReason | "outside-root" | "host-not-allowed" | "topic-not-allowed" | "partition-not-allowed";
 
 /** An error of the invocation itself. An error that the handler throws passes through unchanged. */
 export class InvocationError extends Error {
@@ -84,7 +87,7 @@ export class InvocationError extends Error {
   readonly retryable: boolean = false;
   /**
    * The reason of a `FORBIDDEN` error: `effects-undeclared`, `effects-exceeded`, `clearance`,
-   * `deadline`, `outside-root`, `host-not-allowed` or `topic-not-allowed`.
+   * `deadline`, `outside-root`, `host-not-allowed`, `topic-not-allowed` or `partition-not-allowed`.
    */
   readonly reason: ForbiddenReason | undefined;
 
@@ -158,6 +161,18 @@ export interface InvokeOptions {
    * from its authentication. The nested calls get it, or a narrower one. Absent: no limits.
    */
   capability?: Capability | undefined;
+  /**
+   * A narrower capability that the caller asks for (CLI-30). The invocation of the host combines
+   * it with the narrowing key of `metadata` (`procedure-narrowing`) by the meet, so each source can
+   * only narrow. A part that asks for more has no effect. The nested calls get the narrowed
+   * capability.
+   */
+  narrow?: CapabilityRequest | undefined;
+  /**
+   * This function gets the notes of the narrowing of the call (CLI-30): each part that has no
+   * effect, and the part that refuses the call. A server gives them to its debug reports.
+   */
+  onNarrowingNotes?: ((notes: readonly NarrowingNote[]) => void) | undefined;
   /** The order of the clearance values. Narrowing two different clearances needs it. */
   clearanceOrder?: ClearanceOrder | undefined;
   /** The resources of an invocation for its capability (`ctx.resources`). */
@@ -306,6 +321,28 @@ async function* validatedItems(
   }
 }
 
+/**
+ * The options of an invocation with its narrowing applied (CLI-30). The sources are the narrowing
+ * key of the metadata, for the call of a host only (the nested calls get the metadata of their
+ * caller), and the option `narrow`. They combine by the meet. A part that is not valid throws:
+ * `INVALID_REQUEST` for a part that is not well formed, `FORBIDDEN` (reason `clearance`) for a
+ * clearance outside the order or clearances without a meet.
+ */
+function narrowedOptions(path: ProcedurePath, options: InvokeOptions): InvokeOptions {
+  const metadata = options.parent === undefined ? options.metadata : undefined;
+  const keyed = metadata !== undefined && Object.hasOwn(metadata, NARROWING_METADATA_KEY);
+  if (!keyed && !options.narrow) return options;
+  const wire = metadata !== undefined && keyed ? narrowingOf(metadata[NARROWING_METADATA_KEY]) : narrowingOf(undefined);
+  const sources = options.narrow ? [...wire.narrowings, options.narrow] : wire.narrowings;
+  const narrowed = narrowWithin(options.capability, sources, options.clearanceOrder);
+  const notes = [...wire.notes, ...narrowed.notes];
+  if (notes.length > 0) options.onNarrowingNotes?.(notes);
+  const refusal = notes.find((note) => note.kind === "refused");
+  if (refusal?.code === "FORBIDDEN") throw new InvocationError("FORBIDDEN", refusal.message, path, "clearance");
+  if (refusal) throw Object.assign(new Error(refusal.message), { code: "INVALID_REQUEST" });
+  return { ...options, narrow: undefined, capability: narrowed.capability };
+}
+
 /**
  * This function runs a procedure: it validates the input, makes the context, runs the handler
  * and validates the output. It throws an `InvocationError` for an invocation that cannot run,
@@ -318,6 +355,9 @@ export async function invokeProcedure<TOutput = unknown>(
   options: InvokeOptions = {},
 ): Promise<ProcedureOutput<TOutput>> {
   const { path } = procedure;
+  // The narrowing of the call applies one time, here, for each face and each path of the process:
+  // the nested calls get the result (CLI-30)
+  options = narrowedOptions(path, options);
   if (!procedure.handler) {
     throw new InvocationError("NO_HANDLER", `Procedure has no handler: ${pathToKey(path)}`, path);
   }