@procedures/client 0.2.3 → 0.4.0

package/src/procedures/core/meta.ts

@@ -14,6 +14,7 @@ import {
   parseProcedureJson,
   stringifyProcedureJson,
   isAnyProcedureRef,
+  isProcedureRef,
   isOutputRef,
   isPlainObject,
   resolveOutputRef,
@@ -58,18 +59,37 @@ const ImportOutputSchema = z.looseObject({
 
 type ImportProcedure = Procedure<ImportInput, ImportOutput, { description: string; tags: string[] }>;
 
+/**
+ * This function gives true for the runtime form of a procedure reference whose path is a list of
+ * texts. `client.import` accepts only such a value at the top level.
+ */
+function isImportableRef(value: unknown): boolean {
+  if (!isProcedureRef(value)) return false;
+  const path = (value as { path?: unknown }).path;
+  return Array.isArray(path) && path.length > 0 && path.every((segment) => typeof segment === "string");
+}
+
 const importProcedure: ImportProcedure = defineProcedure({
   path: ["import"],
   input: ImportInputSchema,
   output: ImportOutputSchema,
   metadata: {
-    description: "Parse procedure aggregation from JSON string",
+    description:
+      "Parse a procedure reference ({ $proc, input }) from JSON text. Other JSON, for example a number or a list, gives success false.",
     tags: ["core", "meta"],
   },
   handler: async (input: ImportInput): Promise<ImportOutput> => {
     try {
       if (input.json) {
         const procedure = parseProcedureJson(input.json);
+        // Before, each JSON value gave success true, for example 42 (catalog test, roadmap R29)
+        if (!isImportableRef(procedure)) {
+          return {
+            procedure: null,
+            success: false,
+            error: "The JSON is not a procedure reference. A reference is an object whose $proc is a list of texts.",
+          };
+        }
         return { procedure, success: true };
       }
       if (input.path) {
@@ -107,8 +127,19 @@ interface ExportInput {
   pretty?: boolean | undefined;
 }
 
+/**
+ * This function gives a schema of a required value: undefined has no JSON text, so the input
+ * schema refuses it with `VALIDATION_ERROR`. Before, the call failed with
+ * `OUTPUT_VALIDATION_ERROR` (catalog test, roadmap R29).
+ */
+const definedValue = (description: string) =>
+  z
+    .unknown()
+    .refine((value) => value !== undefined, { message: "The value is missing: undefined has no JSON text" })
+    .describe(description);
+
 const ExportInputSchema = z.object({
-  procedure: z.unknown().optional().describe("Procedure reference to serialize"),
+  procedure: definedValue("The procedure reference to serialize. The procedure refuses a missing value (undefined) with VALIDATION_ERROR, because undefined has no JSON text."),
   pretty: z.boolean().optional().describe("Pretty print JSON output"),
 });
 
@@ -134,13 +165,15 @@ const exportProcedure: ExportProcedure = defineProcedure({
   input: ExportInputSchema,
   output: ExportOutputSchema,
   metadata: {
-    description: "Serialize procedure aggregation to JSON string",
+    description: "Serialize a procedure reference to JSON text. It refuses a missing procedure (undefined) with VALIDATION_ERROR.",
     // The refs of the input are data: exec() must not run them (deep dive CORE-5)
     tags: ["core", "meta", RAW_INPUT_TAG],
   },
   handler: async (input: ExportInput): Promise<ExportOutput> => {
     try {
-      const json = stringifyProcedureJson(input.procedure, input.pretty ? 2 : undefined);
+      const json = stringifyProcedureJson(input.procedure, input.pretty ? 2 : undefined) as string | undefined;
+      // A function or a symbol has no JSON text either: an error result, not an invalid output
+      if (json === undefined) return { json: "", success: false, error: "The procedure has no JSON text" };
       return { json, success: true };
     } catch (error) {
       return {
@@ -268,7 +301,7 @@ interface StringifyJsonInput {
 }
 
 const StringifyJsonInputSchema = z.object({
-  value: z.unknown().optional().describe("Value to stringify"),
+  value: definedValue("The value to write as JSON. The procedure refuses a missing value (undefined) with VALIDATION_ERROR, because undefined has no JSON text."),
   pretty: z.boolean().optional().describe("Pretty print with indentation"),
   indent: z.union([z.number(), z.string()]).optional().describe("Custom indentation (number of spaces or string)"),
 });
@@ -280,13 +313,16 @@ const stringifyJsonProcedure: StringifyJsonProcedure = defineProcedure({
   input: StringifyJsonInputSchema,
   output: stringOutput("The JSON text"),
   metadata: {
-    description: "Stringify value to JSON (with procedure ref support)",
+    description: "Stringify value to JSON (with procedure ref support). It refuses a missing value (undefined) with VALIDATION_ERROR.",
     // The refs of the input are data: exec() must not run them (deep dive CORE-5)
     tags: ["core", "meta", RAW_INPUT_TAG],
   },
   handler: async (input: StringifyJsonInput): Promise<string> => {
     const indent = input.pretty ? (input.indent ?? 2) : input.indent;
-    return stringifyProcedureJson(input.value, indent as number);
+    const json = stringifyProcedureJson(input.value, indent as number) as string | undefined;
+    // A function or a symbol has no JSON text either: a clear error, not an invalid output
+    if (json === undefined) throw new Error("The value has no JSON text");
+    return json;
   },
 });
 
@@ -331,7 +367,8 @@ const lookupProcedure: LookupProcedure = defineProcedure({
   handler: async (input: LookupInput, ctx): Promise<LookupOutput> => {
     // The registry of the caller (a server or a client with its own registry)
     const proc = (ctx?.registry ?? PROCEDURE_REGISTRY).get(input.path);
-    if (proc) {
+    // A procedure outside the expose rule of the host does not exist for its callers (R17)
+    if (proc && (!ctx?.expose || ctx.expose(proc.path))) {
       return {
         exists: true,
         metadata: proc.metadata,

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/core/type.ts

@@ -10,6 +10,7 @@ import { anyOutput, booleanOutput, stringOutput } from "./outputs.js";
 import { defineProcedure, namespace } from "../define.js";
 import type { AnyProcedure, Procedure } from "../types.js";
 import { PURE_EFFECTS, withEffects } from "../effects.js";
+import { isPlainObject } from "../ref.js";
 
 // =============================================================================
 // Typeof Procedure
@@ -168,11 +169,12 @@ const isObjectProcedure: IsObjectProcedure = defineProcedure({
   input: IsObjectInputSchema,
   output: booleanOutput("True for a plain object"),
   metadata: {
-    description: "Check if value is a plain object (not array, not null)",
+    description: "Check if value is a plain object (not array, not null, not a Date or another class instance)",
     tags: ["core", "type"],
   },
   handler: async (input: IsObjectInput): Promise<boolean> => {
-    return typeof input.value === "object" && input.value !== null && !Array.isArray(input.value);
+    // Before, a Date or a Map gave true (catalog test, roadmap R29)
+    return isPlainObject(input.value);
   },
 });
 

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/discovery.ts

@@ -1,13 +1,11 @@
 /**
  * Procedure Registration Helpers
  *
- * Manual registration helpers for procedures. For compile-time auto-discovery,
- * use the CLI: `npx client-registry discover`
+ * These helpers add procedures to the global registry.
  *
- * Libraries that depend on client should:
- * 1. Add `"client": { "procedures": "./dist/register.js" }` to package.json
- * 2. Create a register.ts that uses createAndRegister()
- * 3. Consumers run `npx client-registry discover` to generate imports
+ * A package with procedures declares `"client": { "procedures": "./dist/register.js" }` in its
+ * `package.json`. Its `src/register.ts` registers its module. `mark` finds the packages by the
+ * `client.procedures` field, and an app imports the `/register` entry of each package that it uses.
  */
 
 import { PROCEDURE_REGISTRY } from "./registry.js";

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.