@procedures/client 0.33.0 → 0.35.0

package/src/procedures/collection/topic.ts

@@ -1,95 +1,91 @@
 /**
- * The topics of the change events of a collection (roadmap CLI-15, CLI-17 and CLI-42). This module
- * has the one function that makes a topic, the functions that read it, and the topic rule of a
- * collection. Each part of the client that makes or reads the topic of a collection or of a
+ * The topics of the change events of a collection (roadmap CLI-15, CLI-17, CLI-42 and CLI-75). This
+ * module has the one function that makes a topic, the functions that read it, and the topic rule
+ * of a collection. Each part of the client that makes or reads the topic of a collection or of a
  * partition uses them.
  *
- * - `collections.<name>` is the topic of a collection. The name stays as it is, also with a dot.
- * - `collections.<name>.<partition>` is the topic of a partition. In this form, the name encodes
- *   `%` as `%25` and `.` as `%2E`. Thus the first dot after `collections.` ends the name, and the
- *   partition after that dot can have each character, also `.`, `/` and `%`.
- * - The partition stays as it is, and so does a name without `.` and `%`. Thus each topic of a
- *   partition of a name without `.` and `%` stays the same as before CLI-42.
+ * - `collections.<name>` is the topic of a collection, and `collections.<name>.<partition>` is the
+ *   topic of a partition.
+ * - In each topic, the name encodes `%` as `%25` and `.` as `%2E` (`encodeSegment()`). Thus the
+ *   first dot after `collections.` ends the name, and the partition after that dot can have each
+ *   character, also `.`, `/` and `%`. The partition stays as it is.
+ * - A name without `.` and `%` stays as it is. Thus each topic of such a name stays the same.
+ * - Before CLI-75, the plain topic kept a dotted name as it is: `collections.a.b` was the topic of
+ *   the collection `a.b` and also of the partition `b` of `a`. Now the topic of `a.b` is
+ *   `collections.a%2Eb`, so the two topics are not the same.
  * - Only the canonical form of a topic counts: a parse gives a collection and a partition only when
  *   `collectionChangeTopic(collection, partition)` gives the same topic. Thus `%2e` is no alias of
  *   `%2E`, and a rule or an `allow` function that compares the strings sees each topic one way.
- * - The topic of a collection whose name has a dot, `collections.a.b`, has the same form as the
- *   topic of the partition `b` of the collection `a`. Only the repository knows the collection, so
- *   `collectionTopicTarget()` decides with it.
- * - `ProcedureServer` refuses a storage of `a.b` while `a` has partitions, in each order (roadmap
- *   CLI-57, decision D23). Thus the readers of `a.b` do not get the events of a partition of `a`.
  */
+import { encodeSegment, decodeSegment } from "../segments.js";
 import type { RepositoryProvider } from "../types.js";
 
 /** The prefix of the topic of each collection. */
 const PREFIX = "collections.";
 
-/** This function encodes the name of a collection for a topic with a partition: `%` and `.` become `%25` and `%2E`. */
-function encodeTopicName(name: string): string {
-  return name.replace(/[%.]/g, (char) => (char === "%" ? "%25" : "%2E"));
-}
-
-/** This function decodes the name of a topic with a partition. The parse then checks the canonical form. */
-function decodeTopicName(segment: string): string {
-  return segment.replace(/%(25|2E)/g, (_sequence, code: string) => (code === "25" ? "%" : "."));
-}
-
 /**
  * This function gives the topic of the change events of a collection: `collections.<name>`, or
- * `collections.<name>.<partition>` for a partition (roadmap CLI-17). In the topic of a partition,
- * the name encodes `%` and `.` (roadmap CLI-42), so `collectionTopicPartition()` gives back the
- * same collection and the same partition.
+ * `collections.<name>.<partition>` for a partition (roadmap CLI-17). The name encodes `%` and `.`
+ * (roadmap CLI-42 and CLI-75), so `collectionTopicPartition()` gives back the same collection and
+ * the same partition.
  *
  * @example
  * ```typescript
  * collectionChangeTopic("notes", "t1/board:b1"); // "collections.notes.t1/board:b1"
  * collectionChangeTopic("graph.nodes", "acme/space"); // "collections.graph%2Enodes.acme/space"
- * collectionChangeTopic("graph.nodes"); // "collections.graph.nodes"
+ * collectionChangeTopic("graph.nodes"); // "collections.graph%2Enodes"
  * ```
  */
 export function collectionChangeTopic(collection: string, partition?: string): string {
-  return partition === undefined ? `${PREFIX}${collection}` : `${PREFIX}${encodeTopicName(collection)}.${partition}`;
+  const name = `${PREFIX}${encodeSegment(collection)}`;
+  return partition === undefined ? name : `${name}.${partition}`;
 }
 
 /**
  * This function gives the collection and the partition 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.
+ * `collections.<name>.<partition>`, or undefined for another topic. A host reads the collection
+ * of a topic with it, and not with its own pattern.
  *
- * - The first dot after the name ends the name. In a topic with a partition, the name is decoded:
- *   `%2E` is a dot and `%25` is a `%` (roadmap CLI-42).
+ * - The first dot after the name ends the name. The name is decoded: `%2E` is a dot and `%25` is a
+ *   `%` (roadmap CLI-42 and CLI-75).
  * - Each character after that dot is the partition. A partition has one character at least.
  * - A topic that is not in the canonical form gives undefined: `collectionChangeTopic()` of the
  *   result always gives the topic again. Thus `collections.a%2eb.t1` names no collection.
  * - For each name and each partition, `collectionTopicPartition(collectionChangeTopic(name,
  *   partition))` gives the same name and the same partition.
+ *
+ * @example
+ * ```typescript
+ * collectionTopicPartition("collections.e2e%2Etabs"); // { collection: "e2e.tabs", partition: undefined }
+ * collectionTopicPartition("collections.e2e%2Etabs.t1"); // { collection: "e2e.tabs", partition: "t1" }
+ * ```
  */
 export function collectionTopicPartition(topic: string): { collection: string; partition: string | undefined } | undefined {
   if (!topic.startsWith(PREFIX)) return undefined;
   const rest = topic.slice(PREFIX.length);
   const dot = rest.indexOf(".");
-  if (dot === -1) return rest === "" ? undefined : { collection: rest, partition: undefined };
-  if (dot === 0 || dot === rest.length - 1) return undefined;
-  const collection = decodeTopicName(rest.slice(0, dot));
-  const partition = rest.slice(dot + 1);
+  if (dot === 0 || dot === rest.length - 1 || rest === "") return undefined;
+  const collection = decodeSegment(dot === -1 ? rest : rest.slice(0, dot));
+  const partition = dot === -1 ? undefined : rest.slice(dot + 1);
   // Only the canonical form counts: an alias of an escape names no collection
   return collectionChangeTopic(collection, partition) === topic ? { collection, partition } : undefined;
 }
 
 /**
- * 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.
+ * This function gives the collection and the partition part of a topic of a call: one rule for
+ * the read check and for the listener of the publisher. It gives the result of
+ * `collectionTopicPartition()`.
  *
- * - A collection of the repository whose name is the whole rest of the topic wins, with or without
- *   partitions: its name can have a dot. The call then asks for no partition.
- * - Else `collectionTopicPartition()` reads the topic: the first dot after the name ends the name,
- *   and the rest is the partition that the call asks for. In this form, the name encodes `%` and
- *   `.`, so the name of a collection with partitions can have a dot (roadmap CLI-42).
+ * - Before CLI-75, a collection of the repository whose name was the whole rest of the topic won,
+ *   because the plain topic of a dotted name did not encode the name. Now each topic encodes the
+ *   name, so the function does not read the repository.
+ *
+ * @param repository - Deprecated: not used since roadmap CLI-75. The parameter stays for the
+ *   callers, and a later MINOR removes it. (TSDoc has no `@deprecated` for one parameter, and the
+ *   block tag would deprecate the whole function, which stays.)
  */
 export function collectionTopicTarget(topic: string, repository: RepositoryProvider | undefined): { collection: string; partition: string | undefined } | undefined {
-  if (!topic.startsWith(PREFIX)) return undefined;
-  const whole = topic.slice(PREFIX.length);
-  if (whole !== "" && repository?.hasCollection(whole)) return { collection: whole, partition: undefined };
+  void repository;
   return collectionTopicPartition(topic);
 }
 
@@ -97,21 +93,22 @@ export function collectionTopicTarget(topic: string, repository: RepositoryProvi
  * This function gives the topic rule of a collection for `EventPublisher` (the option `topics`):
  * the topic of the collection, and the pattern of the topics of its partitions (roadmap CLI-42).
  * Build the rule of a collection with it. Do not join the parts yourself: a dotted name needs its
- * encoded form in the pattern.
+ * encoded form.
  *
  * - The rule always has the two forms. For a collection with partitions, the plain topic asks for
  *   no partition, and the resolver of the partition decides.
  * - For a collection without partitions, a topic of a partition passes the rule. The publisher then
  *   refuses it with `FORBIDDEN` (reason `partition-not-allowed`).
- * - The pattern matches only the canonical form of a topic, so an alias of an escape gets
+ * - The rule matches only the canonical form of a topic, so an alias of an escape gets
  *   `TOPIC_NOT_FOUND`.
  *
  * @example
  * ```typescript
- * collectionTopicRule("graph.nodes"); // ["collections.graph.nodes", "collections.graph%2Enodes.*"]
+ * collectionTopicRule("graph.nodes"); // ["collections.graph%2Enodes", "collections.graph%2Enodes.*"]
  * new EventPublisher({ bus, topics: ["orders.*", ...collectionTopicRule("graph.nodes")] });
  * ```
  */
 export function collectionTopicRule(collection: string): string[] {
-  return [collectionChangeTopic(collection), `${PREFIX}${encodeTopicName(collection)}.*`];
+  const topic = collectionChangeTopic(collection);
+  return [topic, `${topic}.*`];
 }

package/src/procedures/core/schemas.ts

@@ -47,8 +47,30 @@ export const anySchema: ZodLike<any> & StandardSchemaV1<unknown, any> & { readon
 };
 
 /**
- * Typed version of anySchema for specific type annotations.
- * Useful when you want to assert a specific type at compile time.
+ * This function gives a pass-through schema for the type `T`: it validates nothing and has no JSON
+ * Schema. The type parameter only gives the TypeScript type.
+ *
+ * Use it for internal procedures where a real schema adds nothing. Give a real schema (zod) to a
+ * procedure that an MCP server or the CLI exposes. Then the host validates its input, and its
+ * tools and help describe the fields (roadmap 2.1).
+ *
+ * ```ts
+ * createProcedure().path(["a", "b"]).input(typed<{ id: string }>()).output(typed<number>())
+ * ```
+ */
+export function typed<T>(): ZodLikeSchema<T> & StandardSchemaV1<unknown, T> {
+  return {
+    parse: (data: unknown) => data as T,
+    safeParse: (data: unknown) => ({ success: true as const, data: data as T }),
+    _output: undefined as unknown as T,
+    "~standard": passThrough<T>(),
+  };
+}
+
+/**
+ * This function gives a pass-through schema for the type `T`.
+ *
+ * @deprecated Use `typed<T>()`. A later MINOR removes `typedAnySchema` (tracker item O58, decision D13).
  */
 export function typedAnySchema<T>(): ZodLike<T> & StandardSchemaV1<unknown, T> {
   return {
@@ -63,11 +85,16 @@ export function typedAnySchema<T>(): ZodLike<T> & StandardSchemaV1<unknown, T> {
 // =============================================================================
 
 /**
- * Gives a zod schema the type of a procedure schema (`ZodLikeSchema<T>`). A zod 4 schema is a
- * Standard Schema already, so the function returns it unchanged: the validation and the JSON
- * Schema come from zod itself.
+ * This function gives a zod schema the type of a procedure schema (`ZodLikeSchema<T>`). A zod 4
+ * schema is a Standard Schema already, so the function returns it unchanged: the validation and
+ * the JSON Schema come from zod itself.
  *
  * An object with only a `parse` method gets `safeParse` and `~standard` around that method.
+ *
+ * @deprecated Give the zod schema to `input()` and `output()` directly: they take each Standard
+ * Schema and infer its type. To check a schema against a type, write `const s: z.ZodType<T> = ...`.
+ * For a parse-only object, write a Standard Schema (`~standard`). A later MINOR removes
+ * `zodAdapter` (tracker item O58, decision D13).
  */
 export function zodAdapter<T>(schema: { parse: (data: unknown) => T }): ZodLikeSchema<T> {
   if (isStandardSchema(schema) && typeof (schema as { safeParse?: unknown }).safeParse === "function") {
@@ -106,18 +133,10 @@ export function zodAdapter<T>(schema: { parse: (data: unknown) => T }): ZodLikeS
 // =============================================================================
 
 /**
- * A pass-through schema: it validates nothing and has no JSON Schema. The type parameter only
- * gives the TypeScript type.
+ * This function gives a pass-through schema for the type `T`.
  *
- * Use it for internal procedures where a real schema adds nothing. A procedure that an MCP
- * server exposes, or that a user calls from the CLI, takes a real schema (zod), so its input
- * is validated and its tools and help describe the fields (roadmap 2.1).
+ * @deprecated Use `typed<T>()`. A later MINOR removes `outputSchema` (tracker item O58, decision D13).
  */
 export function outputSchema<T>(): ZodLikeSchema<T> & StandardSchemaV1<unknown, T> {
-  return {
-    parse: (data: unknown) => data as T,
-    safeParse: (data: unknown) => ({ success: true as const, data: data as T }),
-    _output: undefined as unknown as T,
-    "~standard": passThrough<T>(),
-  };
+  return typed<T>();
 }

package/src/procedures/define-procedure.ts

@@ -37,7 +37,7 @@ import type {
   Effects,
 } from "./types.js";
 import { z } from "zod";
-import { anySchema, zodAdapter } from "./core/schemas.js";
+import { anySchema } from "./core/schemas.js";
 import { keyToPath, pathToKey } from "./types.js";
 import {
   createRefScope,
@@ -326,7 +326,7 @@ export const defineProcedureProcedure: Procedure<
       throw new Error('procedure.define: the aggregation must be a procedure ref: { "$proc": [...], "input": {...} }');
     }
 
-    const pathKey = path.join(".");
+    const pathKey = pathToKey(path);
     const existing = registry.get(path);
     // A procedure outside the expose rule of the host is not the caller's to replace (R17)
     if (existing && ctx?.expose && !ctx.expose(path)) {
@@ -463,7 +463,7 @@ export const getProcedureProcedure: Procedure<
   ProcedureMetadata
 > = defineProcedure({
   path: ["procedure", "get"],
-  input: zodAdapter(getInputSchema),
+  input: getInputSchema,
   output: GetOutputSchema,
   metadata: {
     description: "Describe a procedure by path or key",
@@ -503,7 +503,7 @@ export const listProceduresProcedure: Procedure<
   ProcedureMetadata
 > = defineProcedure({
   path: ["procedure", "list"],
-  input: zodAdapter(listInputSchema),
+  input: listInputSchema,
   output: ListOutputSchema,
   metadata: {
     description: "List the registered procedures",
@@ -530,9 +530,7 @@ export const listProceduresProcedure: Procedure<
  */
 export const manifestProcedure: Procedure<{ namespace?: string | undefined }, ProcedureManifest, ProcedureMetadata> = defineProcedure({
   path: ["procedure", "manifest"],
-  input: zodAdapter(
-    z.object({ namespace: z.string().optional().describe("Only the procedures under this first path segment") }) as z.ZodType<{ namespace?: string | undefined }>,
-  ),
+  input: z.object({ namespace: z.string().optional().describe("Only the procedures under this first path segment") }) as z.ZodType<{ namespace?: string | undefined }>,
   output: ManifestOutputSchema,
   metadata: {
     description: "The manifest of the registry: each exposed procedure with its schemas and effects",

package/src/procedures/index.ts

@@ -38,6 +38,8 @@ export type {
 
 // Type utilities
 export { pathToKey, keyToPath } from "./types.js";
+// The escape of a segment with a dot, for a method name, a key and a topic (roadmap CLI-75)
+export { encodeSegment, decodeSegment, segmentsToTopic, topicToSegments } from "./segments.js";
 
 // Capabilities (CAPABILITIES-2026-10)
 export {
@@ -134,7 +136,7 @@ export {
   collectionTopicPartition,
   collectionTopicTarget,
   collectionTopicRule,
-  // The refusal of a storage whose topic is the topic of a partition (roadmap CLI-57)
+  // The refusal of a storage whose topic is the topic of a partition (roadmap CLI-57). Deprecated since CLI-75
   CollectionTopicCollisionError,
   // The rules of the rows of a collection (roadmap CLI-41)
   admittedStorage,
@@ -212,12 +214,13 @@ export {
 export {
   clientModule,
   defineModule,
+  definePackage,
   moduleClosure,
   registerModules,
   createRegistry,
   registerClientProcedures,
 } from "./module.js";
-export type { ModuleInput } from "./module.js";
+export type { ModuleInput, PackageDefinition } from "./module.js";
 // One call for a registry of some modules, `invokePath` and `outputValue`
 export { callerOf } from "./caller.js";
 export type { Caller, CallerOptions } from "./caller.js";
@@ -345,6 +348,7 @@ export {
   tryCatchProcedure,
   // Schemas and result types
   anySchema,
+  typed,
   typedAnySchema,
   zodAdapter,
   outputSchema,

package/src/procedures/module.ts

@@ -42,6 +42,40 @@ export function defineModule(
   return { name, procedures: [...procedures], requires };
 }
 
+/** The module of a package and the function that registers it. `definePackage` gives one. */
+export interface PackageDefinition {
+  /** The module: the procedures as data. The `./module` entry of the package exports it. */
+  readonly module: ProcedureModule;
+  /**
+   * This function registers the procedures of the module, and of the modules that it uses, in a
+   * registry. The default is the global registry. The `./register` entry of the package starts it.
+   */
+  readonly register: (registry?: ProcedureRegistry) => void;
+}
+
+/**
+ * This function gives the module of a package and its `register` function. The call registers
+ * nothing, so the `./module` entry of a package can use it.
+ *
+ * ```ts
+ * // src/module.ts
+ * const vitest: PackageDefinition = definePackage("@procedures/vitest", [vitestRunProcedure]);
+ * export const vitestModule: ProcedureModule = vitest.module;
+ * export const registerVitestProcedures: PackageDefinition["register"] = vitest.register;
+ * ```
+ */
+export function definePackage(
+  name: string,
+  procedures: readonly AnyProcedure[],
+  requires: readonly ProcedureModule[] = []
+): PackageDefinition {
+  const module = defineModule(name, procedures, requires);
+  const register = (registry: ProcedureRegistry = PROCEDURE_REGISTRY): void => {
+    registerModules(registry, [module]);
+  };
+  return { module, register };
+}
+
 /**
  * The modules and their required modules, each one time, with each required module before the
  * module that requires it.

package/src/procedures/registry.ts

@@ -53,7 +53,8 @@ const RESERVED_SEGMENTS: ReadonlySet<string> = new Set(["__proto__", "constructo
  * This function checks a procedure path: at least one segment, each a non-empty string, and
  * none of `__proto__`, `constructor` or `prototype`. A reserved segment reaches
  * `Object.prototype` in a tree walk (deep dive CORE-6). A segment can contain a dot
- * (`["fs", "read.json"]`), but the registry rejects two different paths with the same key.
+ * (`["collections", "e2e.tabs", "find"]`). The key encodes the dot (roadmap CLI-75), so two
+ * different paths do not have the same key.
  *
  * @throws RegistryError when the path is not valid
  */
@@ -141,7 +142,8 @@ export class ProcedureRegistry {
     if (hintRefusal) throw new RegistryError(`${hintRefusal} (${key})`, path);
 
     const replaced = this.procedures.get(key);
-    // The key joins the segments with dots: ["a.b", "c"] and ["a", "b.c"] have one key
+    // The key encodes each segment (roadmap CLI-75), so ["a.b", "c"] and ["a", "b.c"] have different
+    // keys. The check stays as a guard: two different paths must never share one key
     if (replaced && !samePath(replaced.path, path)) {
       throw new RegistryError(
         `Procedure path ${JSON.stringify(path)} has the same key as ${JSON.stringify(replaced.path)}: ${key}`,

package/src/procedures/segments.ts

@@ -0,0 +1,74 @@
+/**
+ * The one escape of a segment of a procedure path or of a topic (roadmap CLI-75, decision D36).
+ *
+ * A method name, a registry key and a topic join their segments with ".". Before, a segment with a
+ * dot did not come back: `["collections", "e2e.tabs", "find"]` went over the wire as
+ * `collections.e2e.tabs.find` and came back as four segments. Now each segment encodes `%` as
+ * `%25` and then `.` as `%2E` before the join.
+ *
+ * - A segment without `.` and `%` encodes to itself. Thus the wire text of each such name stays the same.
+ * - The decode changes `%2E` and `%2e` to `.`, and `%25` to `%`. It keeps each other `%` sequence,
+ *   so the raw `%` of an old client stays a `%`.
+ * - For each segment, `decodeSegment(encodeSegment(segment))` gives the same segment.
+ */
+
+/**
+ * This function encodes one segment for a text with dots between the segments. It encodes `%` as
+ * `%25` and then `.` as `%2E`. A segment without `.` and `%` stays the same.
+ *
+ * @example
+ * ```typescript
+ * encodeSegment("notes"); // "notes"
+ * encodeSegment("e2e.tabs"); // "e2e%2Etabs"
+ * encodeSegment("50%"); // "50%25"
+ * ```
+ */
+export function encodeSegment(segment: string): string {
+  return segment.replace(/[%.]/g, (char) => (char === "%" ? "%25" : "%2E"));
+}
+
+/**
+ * This function decodes one segment of a text with dots between the segments. `%2E` and `%2e`
+ * become `.`, and `%25` becomes `%`. Each other `%` sequence stays the same.
+ *
+ * @example
+ * ```typescript
+ * decodeSegment("e2e%2Etabs"); // "e2e.tabs"
+ * decodeSegment("50%25"); // "50%"
+ * decodeSegment("50%"); // "50%"
+ * ```
+ */
+export function decodeSegment(segment: string): string {
+  return segment.replace(/%(25|2[Ee])/g, (_sequence, code: string) => (code === "25" ? "%" : "."));
+}
+
+/**
+ * This function gives the text of a list of raw segments: it encodes each segment and joins them
+ * with dots. Use it for a topic, so that a segment with a dot stays one segment.
+ * `topicToSegments()` gives the segments again.
+ *
+ * @example
+ * ```typescript
+ * segmentsToTopic(["orders", "created"]); // "orders.created"
+ * segmentsToTopic(["collections", "e2e.tabs"]); // "collections.e2e%2Etabs"
+ * ```
+ */
+export function segmentsToTopic(segments: readonly string[]): string {
+  // A segment that is not a string becomes text as with join(): null and undefined give "" (a
+  // caller can check a path that is not valid, for example the compiler)
+  return segments.map((segment: unknown) => encodeSegment(segment === null || segment === undefined ? "" : String(segment))).join(".");
+}
+
+/**
+ * This function gives the raw segments of a text with dots between the segments: it splits the
+ * text on each dot and decodes each part. For each list of segments with one segment or more,
+ * `topicToSegments(segmentsToTopic(segments))` gives the same list.
+ *
+ * @example
+ * ```typescript
+ * topicToSegments("collections.e2e%2Etabs"); // ["collections", "e2e.tabs"]
+ * ```
+ */
+export function topicToSegments(topic: string): string[] {
+  return topic.split(".").map(decodeSegment);
+}

package/src/procedures/types.ts

@@ -15,6 +15,7 @@ import type { EventBus } from "../events/types.js";
 import type { HydrationEvent } from "./ref.js";
 import type { Principal } from "../server/types.js";
 import type { Invocation } from "./invoke.js";
+import { segmentsToTopic, topicToSegments } from "./segments.js";
 
 // =============================================================================
 // Procedure Path
@@ -33,17 +34,20 @@ import type { Invocation } from "./invoke.js";
 export type ProcedurePath = string[];
 
 /**
- * Convert path array to dot-separated key.
+ * This function gives the key of a path: the segments with dots between them. Each segment encodes
+ * `%` as `%25` and `.` as `%2E` (`encodeSegment()`, roadmap CLI-75). Thus the key of
+ * `["a.b", "c"]` is `a%2Eb.c`, and not the key of `["a", "b", "c"]`. A plain path keeps its key.
  */
 export function pathToKey(path: ProcedurePath): string {
-  return path.join(".");
+  return segmentsToTopic(path);
 }
 
 /**
- * Parse dot-separated key to path array.
+ * This function gives the path of a key: it splits the key on each dot and decodes each segment
+ * (`decodeSegment()`, roadmap CLI-75). For each path, `keyToPath(pathToKey(path))` gives the path.
  */
 export function keyToPath(key: string): ProcedurePath {
-  return key.split(".");
+  return topicToSegments(key);
 }
 
 // =============================================================================

package/src/server/host-policy.ts

@@ -22,7 +22,7 @@
  *   keyed limiter for each limit, and refuses a call above a limit with `RATE_LIMITED`.
  */
 
-import type { Capability, ClearanceOrder, ProcedurePath, ResourcesOf } from "../procedures/types.js";
+import { pathToKey, type Capability, type ClearanceOrder, type ProcedurePath, type ResourcesOf } from "../procedures/types.js";
 import type { AdmitItem, Interceptor, Invocation } from "../procedures/invoke.js";
 import { narrowCapability } from "../procedures/capability.js";
 import type { PrincipalOf, ServerRequest } from "./types.js";
@@ -53,7 +53,8 @@ export function exposePatterns(patterns: readonly string[]): (path: ProcedurePat
   }
   return (path) => {
     if (all) return true;
-    const key = path.join(".");
+    // The key encodes a dot in a segment (roadmap CLI-75), as the method name does
+    const key = pathToKey(path);
     return exact.has(key) || prefixes.some((prefix) => key.startsWith(prefix));
   };
 }
@@ -62,7 +63,7 @@ export function exposePatterns(patterns: readonly string[]): (path: ProcedurePat
 export function surfaceRule(surface: ToolSurface): (path: ProcedurePath) => boolean {
   const namespaces = new Set(surface.namespaces);
   const excluded = new Set(surface.exclude ?? []);
-  return (path) => namespaces.has(path[0] ?? "") && !excluded.has(path.join("."));
+  return (path) => namespaces.has(path[0] ?? "") && !excluded.has(pathToKey(path));
 }
 
 /** The options of `hostPolicy()`. */
@@ -162,7 +163,7 @@ function exposeOf(options: HostPolicyOptions): ((path: ProcedurePath) => boolean
           : surfaceRule(expose as ToolSurface);
   const excluded = new Set(options.exclude ?? []);
   if (excluded.size === 0) return rule;
-  return (path) => !excluded.has(path.join(".")) && (rule ? rule(path) : true);
+  return (path) => !excluded.has(pathToKey(path)) && (rule ? rule(path) : true);
 }
 
 /** This function builds the policy of a host from its options. */

package/src/server/index.ts

@@ -44,6 +44,8 @@ export type { ServerOptions } from "./server.js";
 export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream } from "./procedure-server.js";
 export type { ProcedureServerOptions, RegisterProcedureOptions, StorageConfig, StopOptions, StopParts, StorageHandle, UseStorageOptions } from "./procedure-server.js";
 export { pathToMethod, methodToPath, methodName } from "./method.js";
+// The escape of a segment with a dot, for a method name, a key and a topic (roadmap CLI-75)
+export { encodeSegment, decodeSegment, segmentsToTopic, topicToSegments } from "../procedures/segments.js";
 export {
   HandlerNotFoundError,
   ServerError,

package/src/server/method.ts

@@ -8,26 +8,41 @@
  * (deep dive architecture review 3.3).
  *
  * `methodToPath` splits both the service and the operation on ".", so it reads both forms.
+ *
+ * Each segment encodes `%` as `%25` and then `.` as `%2E` before the join (`encodeSegment()`,
+ * roadmap CLI-75). Thus the path `["collections", "e2e.tabs", "find"]` is the method
+ * `{ service: "collections.e2e%2Etabs", operation: "find" }`, and `methodToPath` gives the same
+ * three segments again. A segment without `.` and `%` stays the same, so a plain path keeps its method.
  */
 
 import type { Method } from "../client/types.js";
 import type { ProcedurePath } from "../procedures/types.js";
+import { encodeSegment, topicToSegments } from "../procedures/segments.js";
 
 /**
  * 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.
+ * operation, and the other segments, joined with dots, are the service. Each segment is encoded
+ * first (`encodeSegment()`, roadmap CLI-75). A path of one segment, for example `["morning"]`, has
+ * the empty service (CLI-28). An empty path throws.
+ *
+ * @example
+ * ```typescript
+ * pathToMethod(["docker", "compose", "up"]); // { service: "docker.compose", operation: "up" }
+ * pathToMethod(["collections", "e2e.tabs", "find"]); // { service: "collections.e2e%2Etabs", operation: "find" }
+ * ```
  */
 export function pathToMethod(path: readonly string[]): Method {
   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]! };
+  const segments = path.map(encodeSegment);
+  return { service: segments.slice(0, -1).join("."), operation: segments[segments.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`).
+ * service of a path of one segment (`morning`). The segments of the method are already encoded,
+ * so the name of `["collections", "e2e.tabs", "find"]` is `collections.e2e%2Etabs.find`.
  */
 export function methodName(method: Pick<Method, "service" | "operation">): string {
   return method.service === "" ? method.operation : `${method.service}.${method.operation}`;
@@ -36,10 +51,12 @@ export function methodName(method: Pick<Method, "service" | "operation">): strin
 /**
  * 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"]`.
+ * It splits on each dot and then decodes each segment (`decodeSegment()`, roadmap CLI-75): `%2E`
+ * gives `.` and `%25` gives `%`.
  */
 export function methodToPath(method: Pick<Method, "service" | "operation">): ProcedurePath {
   // 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(".")];
+  const service = method.service === "" ? [] : topicToSegments(method.service);
+  return [...service, ...topicToSegments(method.operation)];
 }