@procedures/client 0.2.3 → 0.3.0

package/src/procedures/core/object.ts

@@ -11,15 +11,46 @@ import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";
 import { PURE_EFFECTS, withEffects } from "../effects.js";
 
+// =============================================================================
+// Helpers: own keys only (roadmap R6)
+// =============================================================================
+
+/** The path segments that reach a prototype. The registry refuses them in paths too. */
+const PROTOTYPE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * The segments of a dotted path. A segment that reaches a prototype is an error: before,
+ * `client.set` with the path `__proto__.x` changed the prototype of its result (roadmap R6).
+ */
+function segmentsOf(path: string): string[] {
+  const parts = path.split(".");
+  for (const part of parts) {
+    if (PROTOTYPE_KEYS.has(part)) {
+      throw new Error(`The path "${path}" has the segment "${part}", which reaches a prototype`);
+    }
+  }
+  return parts;
+}
+
+function hasOwn(obj: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+/** This function sets an own data property: a "__proto__" key of the data stays data. */
+function put(target: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+}
+
 // =============================================================================
 // Helper: Get nested value by path
 // =============================================================================
 
 function getByPath(obj: unknown, path: string): unknown {
-  const parts = path.split(".");
+  const parts = segmentsOf(path);
   let current: unknown = obj;
   for (const part of parts) {
-    if (current === null || current === undefined) {
+    // Only own fields: before, "toString" gave a function of the prototype
+    if (current === null || typeof current !== "object" || !hasOwn(current, part)) {
       return undefined;
     }
     current = (current as Record<string, unknown>)[part];
@@ -33,22 +64,22 @@ function getByPath(obj: unknown, path: string): unknown {
 
 function setByPath(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown> {
   const result = { ...obj };
-  const parts = path.split(".");
+  const parts = segmentsOf(path);
   let current: Record<string, unknown> = result;
 
   for (let i = 0; i < parts.length - 1; i++) {
     const part = parts[i]!;
-    if (!(part in current) || typeof current[part] !== "object" || current[part] === null) {
-      current[part] = {};
+    if (!hasOwn(current, part) || typeof current[part] !== "object" || current[part] === null) {
+      put(current, part, {});
     } else {
-      current[part] = { ...(current[part] as Record<string, unknown>) };
+      put(current, part, { ...(current[part] as Record<string, unknown>) });
     }
     current = current[part] as Record<string, unknown>;
   }
 
   const lastPart = parts[parts.length - 1];
   if (lastPart !== undefined) {
-    current[lastPart] = value;
+    put(current, lastPart, value);
   }
   return result;
 }
@@ -139,16 +170,17 @@ function deepMerge(target: Record<string, unknown>, source: Record<string, unkno
       typeof source[key] === "object" &&
       source[key] !== null &&
       !Array.isArray(source[key]) &&
+      hasOwn(result, key) &&
       typeof result[key] === "object" &&
       result[key] !== null &&
       !Array.isArray(result[key])
     ) {
-      result[key] = deepMerge(
+      put(result, key, deepMerge(
         result[key] as Record<string, unknown>,
         source[key] as Record<string, unknown>
-      );
+      ));
     } else {
-      result[key] = source[key];
+      put(result, key, source[key]);
     }
   }
   return result;
@@ -166,7 +198,8 @@ const mergeProcedure: MergeProcedure = defineProcedure({
     if (input.deep) {
       return input.objects.reduce((acc, obj) => deepMerge(acc, obj), {});
     }
-    return Object.assign({}, ...input.objects);
+    // Object.assign sets a "__proto__" key of the data as the prototype: spread keeps it data
+    return input.objects.reduce<Record<string, unknown>>((acc, obj) => ({ ...acc, ...obj }), {});
   },
 });
 
@@ -307,8 +340,9 @@ const pickProcedure: PickProcedure = defineProcedure({
   handler: async (input: PickInput): Promise<Record<string, unknown>> => {
     const result: Record<string, unknown> = {};
     for (const key of input.keys) {
-      if (key in input.object) {
-        result[key] = input.object[key];
+      // Only own fields: before, "toString" picked a function of the prototype
+      if (hasOwn(input.object, key)) {
+        put(result, key, input.object[key]);
       }
     }
     return result;
@@ -344,7 +378,7 @@ const omitProcedure: OmitProcedure = defineProcedure({
     const result: Record<string, unknown> = {};
     for (const key of Object.keys(input.object)) {
       if (!keysToOmit.has(key)) {
-        result[key] = input.object[key];
+        put(result, key, input.object[key]);
       }
     }
     return result;

package/src/procedures/core/operands.ts

@@ -7,6 +7,8 @@ import type { ProcedureContext, ProcedurePath } from "../types.js";
 import { PROCEDURE_REGISTRY } from "../registry.js";
 import {
   isAnyProcedureRef,
+  getRefWhen,
+  WHEN_NEVER,
   normalizeRef,
   hydrateInput,
   createRefScope,
@@ -73,6 +75,11 @@ export async function callOperand(
   ctx: ProcedureContext,
   options: { scope?: RefScope | undefined; extra?: Record<string, unknown> | undefined } = {},
 ): Promise<unknown> {
+  // A $never operand is data with its full input, as a $never call anywhere (roadmap R4: before,
+  // only a chain step obeyed it, and a $never branch, task or fn started)
+  if (getRefWhen(ref) === WHEN_NEVER) {
+    return ref;
+  }
   const normalized = normalizeRef(ref);
   const raw = rawRule(ctx)(normalized.path);
   let input: unknown = raw ? normalized.input : await hydrateOperand(normalized.input, ctx, options.scope);

package/src/procedures/core/string.ts

@@ -132,7 +132,9 @@ const replaceProcedure: ReplaceProcedure = defineProcedure({
     if (input.all) {
       return input.value.split(input.search).join(input.replace);
     }
-    return input.value.replace(input.search, input.replace);
+    // A function gives the replacement as text. Before, "$$" became "$" and "$&" became the match
+    // (catalog test, roadmap R29).
+    return input.value.replace(input.search, () => input.replace);
   },
 });
 
@@ -382,7 +384,7 @@ interface TemplateInput {
 }
 
 const TemplateInputSchema = z.object({
-  template: z.string().describe("The template text, with {name} placeholders"),
+  template: z.string().describe("The template text, with {{name}} placeholders"),
   values: z.record(z.string(), z.unknown()).describe("The values"),
 });
 

package/src/procedures/define-procedure.ts

@@ -34,6 +34,7 @@ import type {
   ProcedureContext,
   AnyProcedure,
   ProcedureRegistryLike,
+  Effects,
 } from "./types.js";
 import { z } from "zod";
 import { anySchema, zodAdapter } from "./core/schemas.js";
@@ -47,7 +48,10 @@ import {
   rawInputRule,
   RUNS_REFS_TAG,
 } from "./ref.js";
-import { PURE_EFFECTS, REGISTRY_READ_EFFECTS, withEffects } from "./effects.js";
+import { INFERRED_EFFECTS_METADATA_KEY, PURE_EFFECTS, REGISTRY_READ_EFFECTS, effectsValue, withEffects } from "./effects.js";
+import { MANIFEST_FORMAT, describeProcedure as describeEntry, describeRegistry, type ProcedureManifest } from "./manifest.js";
+import type { JsonSchema } from "./schema.js";
+import { isRuntimeDefined, markRuntimeProgram, runtimeProgramOfHandler } from "./runtime-programs.js";
 
 // Input schemas of procedure.define and procedure.delete (roadmap 2.1)
 const procedurePathField = z.array(z.string().min(1)).min(1);
@@ -151,7 +155,24 @@ const GetOutputSchema = z.looseObject({
   metadata: descriptionFields.metadata,
   hasInputSchema: z.boolean().optional().describe("True when the procedure has an input schema"),
   hasOutputSchema: z.boolean().optional().describe("True when the procedure has an output schema"),
-}) as z.ZodType<{ found: false } | (ProcedureDescription & { found: true; hasInputSchema: boolean; hasOutputSchema: boolean })>;
+  input: z.record(z.string(), z.unknown()).optional().describe("The JSON Schema of the input"),
+  output: z.record(z.string(), z.unknown()).optional().describe("The JSON Schema of the output"),
+  effects: z.unknown().optional().describe("The declared effects: reads, writes, idempotent, destructive"),
+}) as z.ZodType<{ found: false } | (ProcedureDescription & GetSchemas & { found: true; hasInputSchema: boolean; hasOutputSchema: boolean })>;
+
+/** The JSON Schemas and the effects that `procedure.get` gives (roadmap R17). */
+interface GetSchemas {
+  input?: JsonSchema | undefined;
+  output?: JsonSchema | undefined;
+  effects?: Effects | undefined;
+}
+
+/** The output of `procedure.manifest` */
+const ManifestOutputSchema = z.looseObject({
+  format: z.literal(MANIFEST_FORMAT).describe("The format of the manifest"),
+  hash: z.string().describe("A hash of the entries: two manifests with the same hash describe the same procedures"),
+  procedures: z.array(z.looseObject({ path: z.array(z.string()), key: z.string() })).describe("The procedures, in the order of their keys"),
+}) as unknown as z.ZodType<ProcedureManifest>;
 
 /** The output of `procedure.list` */
 const ListOutputSchema = z.looseObject({
@@ -204,26 +225,15 @@ function createAggregationHandler(
 // Runtime-Defined Procedures
 // =============================================================================
 
-/**
- * The handlers that `procedure.define` made, with the program (the aggregation) of each. The
- * registry is the only store of the procedures: a procedure is runtime-defined when its handler
- * is a key here. (Before, a separate map kept them, and `procedure.delete` removed only the map
- * entry: deep dive CORE-3.) The program is kept here, not only in the metadata: a caller that
- * gives its own metadata to `procedure.define` replaces the metadata.
- */
-const RUNTIME_PROGRAMS = new WeakMap<object, AggregationDefinition>();
-
-/** True for a procedure that `procedure.define` made. */
-export function isRuntimeDefined(procedure: { handler?: unknown }): boolean {
-  return typeof procedure.handler === "function" && RUNTIME_PROGRAMS.has(procedure.handler);
-}
+// The store of the programs of procedure.define (runtime-programs.ts, which imports nothing)
+export { isRuntimeDefined } from "./runtime-programs.js";
 
 /**
  * The program (the aggregation) of a procedure that `procedure.define` made, or undefined for a
  * code procedure. A program store saves it and defines it again after a restart (roadmap 3.2).
  */
 export function runtimeProgramOf(procedure: { handler?: unknown }): AggregationDefinition | undefined {
-  return typeof procedure.handler === "function" ? RUNTIME_PROGRAMS.get(procedure.handler) : undefined;
+  return runtimeProgramOfHandler(procedure.handler) as AggregationDefinition | undefined;
 }
 
 type RegistryOf = Pick<ProcedureRegistryLike, "get" | "getAll" | "unregister">;
@@ -327,6 +337,10 @@ export const defineProcedureProcedure: Procedure<
       throw new Error(`Procedure already exists at path: ${pathKey}`);
     }
 
+    // The effects of the body that the host found (roadmap R22). Only an interceptor of the host
+    // can give them: each transport removes the key from a request.
+    const inferred = effectsValue(ctx?.metadata?.[INFERRED_EFFECTS_METADATA_KEY]);
+
     // Create the procedure
     const procedure: AnyProcedure = defineProcedure({
       path,
@@ -341,13 +355,15 @@ export const defineProcedureProcedure: Procedure<
         // No effects of its own, as client.chain: the admission examines each nested call of a
         // data-driven procedure. The framework sets it, so the metadata of a caller cannot claim less
         effects: PURE_EFFECTS,
+        // The framework sets this field too: the effects of the body, for the tool hints
+        ...(inferred ? { inferredEffects: inferred } : { inferredEffects: undefined }),
       },
       handler: createAggregationHandler(aggregation),
     });
 
     // Its behavior comes from data: a server with an expose rule lets it call only exposed procedures
     markDataDriven(procedure);
-    RUNTIME_PROGRAMS.set(procedure.handler!, aggregation);
+    markRuntimeProgram(procedure.handler!, aggregation);
 
     // Validate the procedure
     validateProcedure(procedure);
@@ -435,7 +451,7 @@ const getInputSchema: z.ZodType<ProcedureGetInput> = z.object({
  */
 export const getProcedureProcedure: Procedure<
   ProcedureGetInput,
-  { found: false } | (ProcedureDescription & { found: true; hasInputSchema: boolean; hasOutputSchema: boolean }),
+  { found: false } | (ProcedureDescription & GetSchemas & { found: true; hasInputSchema: boolean; hasOutputSchema: boolean }),
   ProcedureMetadata
 > = defineProcedure({
   path: ["procedure", "get"],
@@ -450,14 +466,20 @@ export const getProcedureProcedure: Procedure<
   handler: async (input: ProcedureGetInput, ctx?: ProcedureContext) => {
     const path = typeof input.path === "string" ? keyToPath(input.path) : input.path;
     const procedure = (ctx?.registry ?? PROCEDURE_REGISTRY).get(path);
-    if (!procedure) {
+    // A procedure outside the expose rule of the host is not found (R17)
+    if (!procedure || (ctx?.expose && !ctx.expose(procedure.path))) {
       return { found: false as const };
     }
+    const entry = describeEntry(procedure);
     return {
       found: true as const,
       ...describeProcedure(procedure, true),
       hasInputSchema: !!procedure.input,
       hasOutputSchema: !!procedure.output,
+      // The JSON Schemas and the effects of the one manifest type (R17)
+      ...(entry.input ? { input: entry.input } : {}),
+      ...(entry.output ? { output: entry.output } : {}),
+      ...(entry.effects ? { effects: entry.effects } : {}),
     };
   },
 });
@@ -484,6 +506,8 @@ export const listProceduresProcedure: Procedure<
   },
   handler: async (input: ProcedureListInput, ctx?: ProcedureContext) => {
     let all = (ctx?.registry ?? PROCEDURE_REGISTRY).getAll();
+    // Only the procedures that the host exposes (R17)
+    if (ctx?.expose) all = all.filter((procedure) => ctx.expose!(procedure.path));
     if (input.runtime) all = all.filter(isRuntimeDefined);
     if (input.namespace) all = all.filter((procedure) => procedure.path[0] === input.namespace);
     const procedures = all.map((procedure) => describeProcedure(procedure, input.includeMetadata ?? false));
@@ -491,6 +515,31 @@ export const listProceduresProcedure: Procedure<
   },
 });
 
+/**
+ * The manifest of the caller's registry (roadmap R17): each procedure that the host exposes, with
+ * its JSON Schemas, effects and command-line metadata, and a hash. The compiler and the SDK
+ * generators read it.
+ */
+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 }>,
+  ),
+  output: ManifestOutputSchema,
+  metadata: {
+    description: "The manifest of the registry: each exposed procedure with its schemas and effects",
+    tags: ["core", "meta"],
+    args: [],
+    shorts: { namespace: "n" },
+    output: "json",
+  },
+  handler: async (input: { namespace?: string | undefined }, ctx?: ProcedureContext) =>
+    describeRegistry(ctx?.registry ?? PROCEDURE_REGISTRY, {
+      ...(ctx?.expose ? { expose: ctx.expose } : {}),
+      ...(input.namespace ? { include: (procedure: AnyProcedure) => procedure.path[0] === input.namespace } : {}),
+    }),
+});
+
 /**
  * Delete a runtime-defined procedure.
  */
@@ -532,6 +581,10 @@ export const deleteProcedureProcedure: Procedure<
 export const metaProcedures: AnyProcedure[] = [
   // They read the registry. define and delete change it (CAPABILITIES-2026-10).
   ...withEffects({ reads: ["registry"], writes: ["registry"] }, [defineProcedureProcedure as AnyProcedure]),
-  ...withEffects(REGISTRY_READ_EFFECTS, [getProcedureProcedure as AnyProcedure, listProceduresProcedure as AnyProcedure]),
+  ...withEffects(REGISTRY_READ_EFFECTS, [
+    getProcedureProcedure as AnyProcedure,
+    listProceduresProcedure as AnyProcedure,
+    manifestProcedure as AnyProcedure,
+  ]),
   ...withEffects({ reads: ["registry"], writes: ["registry"] }, [deleteProcedureProcedure as AnyProcedure]),
 ];

package/src/procedures/effects.ts

@@ -11,6 +11,41 @@ export const PURE_EFFECTS: Effects = Object.freeze({ reads: Object.freeze([]), w
 /** The effects of a procedure that reads the procedure registry and changes nothing. */
 export const REGISTRY_READ_EFFECTS: Effects = Object.freeze({ reads: Object.freeze(["registry"]), writes: Object.freeze([]) });
 
+/**
+ * The metadata key of the effects that a host found for the body of `procedure.define`
+ * (`programCheckInterceptor` of `@procedures/compiler`, roadmap R22). The key starts with `__`, so
+ * each transport removes it from a request: only an interceptor of the host can set it.
+ */
+export const INFERRED_EFFECTS_METADATA_KEY = "__inferredEffects";
+
+function isNameList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((name) => typeof name === "string");
+}
+
+/**
+ * The effects that a host found for a data-driven procedure (`metadata.inferredEffects`), or
+ * undefined. They are information for the tool hints and the explanations. The admission still
+ * examines each nested call of the procedure.
+ */
+export function inferredEffectsOf(source: { readonly metadata?: unknown } | Record<string, unknown> | undefined): Effects | undefined {
+  const metadata = source && "metadata" in source ? (source as { metadata?: unknown }).metadata : source;
+  const value = (metadata as { inferredEffects?: unknown } | undefined)?.inferredEffects;
+  return effectsValue(value);
+}
+
+/** An `Effects` value with known reads and writes, or undefined. */
+export function effectsValue(value: unknown): Effects | undefined {
+  if (value === null || typeof value !== "object") return undefined;
+  const { reads, writes, destructive, idempotent } = value as Record<string, unknown>;
+  if (!isNameList(reads) || !isNameList(writes)) return undefined;
+  return Object.freeze({
+    reads: Object.freeze([...reads]),
+    writes: Object.freeze([...writes]),
+    ...(typeof destructive === "boolean" ? { destructive } : {}),
+    ...(typeof idempotent === "boolean" ? { idempotent } : {}),
+  });
+}
+
 /**
  * This function gives copies of the procedures with the effects in their metadata. A procedure
  * that declares its own effects keeps them.

package/src/procedures/idempotency.ts

@@ -0,0 +1,152 @@
+/**
+ * Idempotency of calls (roadmap R1).
+ *
+ * The retry middleware gives each call one idempotency key, and each try of the call sends the
+ * same key. `ProcedureServer` keeps the result of a keyed call to a procedure that is not
+ * repeatable. A second try with the same key gets that result, and the handler does not run
+ * again. So a retry cannot do a write two times.
+ */
+
+import type { Method } from "../client/types.js";
+import { methodToPath } from "../server/method.js";
+import type { AnyProcedure, Effects, ProcedurePath } from "./types.js";
+import { optionalMs, type Duration } from "../duration.js";
+import { TIMER_DEFAULTS } from "../timers.js";
+
+// This file imports no module of the invocation, so the retry middleware stays small in a browser
+
+/** The metadata key of the idempotency key of a call. Each try of one call sends the same key. */
+export const IDEMPOTENCY_KEY_METADATA = "idempotency-key";
+
+/** The longest idempotency key that a server accepts. A longer key is ignored. */
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 200;
+
+/**
+ * True when a second call with the same input changes nothing more: the procedure is idempotent,
+ * or it changes nothing (`writes: []`). Undeclared effects are not repeatable.
+ */
+export function isRepeatable(effects: Effects | undefined): boolean {
+  if (effects === undefined) return false;
+  if (effects.idempotent === true) return true;
+  return effects.writes !== undefined && effects.writes.length === 0;
+}
+
+/**
+ * This function gives the `idempotent` option of the retry middleware from the procedures that
+ * the client knows: true for a repeatable procedure, false for another one, and undefined for a
+ * path that the registry does not have.
+ */
+export function idempotentIn(registry: { get(path: ProcedurePath): AnyProcedure | undefined }): (method: Method) => boolean | undefined {
+  return (method) => {
+    const procedure = registry.get(methodToPath(method));
+    if (procedure === undefined) return undefined;
+    const effects = (procedure.metadata as { effects?: Effects } | undefined)?.effects;
+    return isRepeatable(effects !== null && typeof effects === "object" ? effects : undefined);
+  };
+}
+
+/**
+ * This function gives the effects of the procedures that the client knows, by method: the
+ * `effects` option of the cache middleware (roadmap R13). A path that the registry does not have
+ * gives undefined.
+ */
+export function effectsIn(registry: { get(path: ProcedurePath): AnyProcedure | undefined }): (method: Method) => Effects | undefined {
+  return (method) => {
+    const effects = (registry.get(methodToPath(method))?.metadata as { effects?: Effects } | undefined)?.effects;
+    return effects !== null && typeof effects === "object" ? effects : undefined;
+  };
+}
+
+/** This function makes a new idempotency key: a random UUID. */
+export function newIdempotencyKey(): string {
+  const random = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto?.randomUUID;
+  if (random) return random.call(globalThis.crypto);
+  // An older runtime without randomUUID: 128 random bits from Math.random
+  let key = "";
+  for (let index = 0; index < 4; index++) key += Math.floor(Math.random() * 0x100000000).toString(16).padStart(8, "0");
+  return key;
+}
+
+/** The idempotency key of a call, from its metadata, or undefined. */
+export function idempotencyKeyOf(metadata: Record<string, unknown> | undefined): string | undefined {
+  const key = metadata?.[IDEMPOTENCY_KEY_METADATA];
+  return typeof key === "string" && key.length > 0 && key.length <= MAX_IDEMPOTENCY_KEY_LENGTH ? key : undefined;
+}
+
+/** The options of the idempotency cache of a server. */
+export interface IdempotencyOptions {
+  /** How long the server keeps a result after the call ends. The default is 10 minutes. */
+  readonly ttl?: Duration;
+  /** The most results that the server keeps. The oldest finished result goes first. The default is 1000. */
+  readonly maxEntries?: number;
+  /** The clock of the cache, in milliseconds. The default is `Date.now`. */
+  readonly now?: () => number;
+}
+
+interface Entry<T> {
+  readonly done: Promise<T>;
+  /** The end time of the call, or undefined while it runs. */
+  settledAt: number | undefined;
+}
+
+/**
+ * The results of keyed calls. The first call with a key runs. A call with the same key while the
+ * first runs waits for it. A later call gets the same result until the time to live ends.
+ */
+export class IdempotencyCache<T> {
+  private readonly entries = new Map<string, Entry<T>>();
+  private readonly ttlMs: number;
+  private readonly maxEntries: number;
+  private readonly now: () => number;
+
+  constructor(options: IdempotencyOptions = {}) {
+    this.ttlMs = optionalMs(options.ttl, "ttl") ?? TIMER_DEFAULTS.idempotency.ttlMs;
+    this.maxEntries = options.maxEntries ?? 1000;
+    this.now = options.now ?? Date.now;
+  }
+
+  /** The number of results and calls that the cache holds. */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /**
+   * The result of the call with this key. `run` starts only for the first call. `keep` tells if
+   * the cache keeps a result: a result that is not kept lets the next call with the key run again.
+   */
+  run(key: string, run: () => Promise<T>, keep: (result: T) => boolean): { result: Promise<T>; first: boolean } {
+    this.evict();
+    const existing = this.entries.get(key);
+    if (existing) return { result: existing.done, first: false };
+    const entry: Entry<T> = {
+      done: run().then(
+        (result) => {
+          if (keep(result)) entry.settledAt = this.now();
+          else if (this.entries.get(key) === entry) this.entries.delete(key);
+          return result;
+        },
+        (error: unknown) => {
+          if (this.entries.get(key) === entry) this.entries.delete(key);
+          throw error;
+        },
+      ),
+      settledAt: undefined,
+    };
+    this.entries.set(key, entry);
+    return { result: entry.done, first: true };
+  }
+
+  /** This function removes the expired results, and the oldest finished results above the limit. */
+  private evict(): void {
+    const now = this.now();
+    for (const [key, entry] of this.entries) {
+      if (entry.settledAt !== undefined && now - entry.settledAt >= this.ttlMs) this.entries.delete(key);
+    }
+    if (this.entries.size < this.maxEntries) return;
+    // A Map keeps the order of insertion, so the first finished entries are the oldest
+    for (const [key, entry] of this.entries) {
+      if (this.entries.size < this.maxEntries) break;
+      if (entry.settledAt !== undefined) this.entries.delete(key);
+    }
+  }
+}

package/src/procedures/index.ts

@@ -54,7 +54,22 @@ export {
   explainInvocation,
   checkEffects,
 } from "./capability.js";
-export { PURE_EFFECTS, REGISTRY_READ_EFFECTS, withEffects } from "./effects.js";
+export { PURE_EFFECTS, REGISTRY_READ_EFFECTS, withEffects, INFERRED_EFFECTS_METADATA_KEY, inferredEffectsOf, effectsValue } from "./effects.js";
+// One manifest type (roadmap R17)
+export { MANIFEST_FORMAT, describeProcedure as describeProcedureEntry, describeRegistry, exposedProcedures, hashOf } from "./manifest.js";
+export type { ProcedureEntry, ProcedureManifest, CliDescription, DescribeOptions, DescribeRegistryOptions } from "./manifest.js";
+// Idempotency of calls (roadmap R1)
+export {
+  IDEMPOTENCY_KEY_METADATA,
+  MAX_IDEMPOTENCY_KEY_LENGTH,
+  IdempotencyCache,
+  idempotencyKeyOf,
+  idempotentIn,
+  effectsIn,
+  isRepeatable,
+  newIdempotencyKey,
+} from "./idempotency.js";
+export type { IdempotencyOptions } from "./idempotency.js";
 export type { ToolHints, CapabilityRefusal, CapabilityRefusalReason, InvocationExplanation, EffectsViolation } from "./capability.js";
 
 // Registry
@@ -73,7 +88,7 @@ export type { ProcedureDefinition, ProcedureStub } from "./define.js";
 
 // Collection procedures
 export { createCollectionProcedures } from "./collection/index.js";
-export type { CollectionStorage, StorageMetadata } from "./collection/index.js";
+export type { CollectionStorage, StorageChanges, StorageMetadata } from "./collection/index.js";
 
 // Manual registration helpers
 export {
@@ -211,6 +226,7 @@ export type {
 export {
   defineProcedureProcedure,
   getProcedureProcedure,
+  manifestProcedure,
   listProceduresProcedure,
   deleteProcedureProcedure,
   metaProcedures,