@procedures/compiler 0.0.0-stage → 0.3.0

package/src/effects.ts

@@ -0,0 +1,231 @@
+/**
+ * The effects pass: the effects of the whole program, from the bottom up.
+ *
+ * - `may` is the upper bound: the effects of each call that can start. A sequence and the
+ *   branches give the union. A call that does not declare its effects, or whose program the
+ *   compiler cannot see, makes the effects unknown: the check fails closed.
+ * - `must` is the lower bound: the effects of each run in which no call fails. A sequence gives
+ *   the union. Two branches give the condition and the intersection of the branches. A part
+ *   that can start zero times (a later operand of `and`, the `fn` of `map`) gives nothing.
+ */
+
+import { isDestructive, isReadOnly, type Effects, type ProcedureEntry, type ProcedurePath } from "@procedures/client/browser";
+import type { CallNode, DynamicNode, IRNode, ItemsSpec, Pointer } from "./ir.js";
+import type { ProcedureFacts } from "./facts.js";
+
+/** The upper bound of the effects. An undefined list: the compiler does not know it. */
+export interface MayEffects {
+  readonly reads: ReadonlySet<string> | undefined;
+  readonly writes: ReadonlySet<string> | undefined;
+  /** True: a call can delete or overwrite data. */
+  readonly destructive: boolean;
+  /** True: each call that writes is idempotent. */
+  readonly idempotent: boolean;
+}
+
+/** The lower bound of the effects. */
+export interface MustEffects {
+  readonly reads: ReadonlySet<string>;
+  readonly writes: ReadonlySet<string>;
+}
+
+/** The effects of a node. */
+export interface EffectSummary {
+  readonly may: MayEffects;
+  readonly must: MustEffects;
+}
+
+const EMPTY_SET: ReadonlySet<string> = new Set();
+
+/** The effects of a part that does nothing. */
+export const NO_EFFECTS: EffectSummary = {
+  may: { reads: EMPTY_SET, writes: EMPTY_SET, destructive: false, idempotent: true },
+  must: { reads: EMPTY_SET, writes: EMPTY_SET },
+};
+
+/** The effects of a part that the compiler does not know. */
+export const UNKNOWN_EFFECTS: EffectSummary = {
+  may: { reads: undefined, writes: undefined, destructive: true, idempotent: false },
+  must: { reads: EMPTY_SET, writes: EMPTY_SET },
+};
+
+function union(a: ReadonlySet<string> | undefined, b: ReadonlySet<string> | undefined): ReadonlySet<string> | undefined {
+  if (!a || !b) return undefined;
+  if (a.size === 0) return b;
+  if (b.size === 0) return a;
+  return new Set([...a, ...b]);
+}
+
+function unionMust(a: ReadonlySet<string>, b: ReadonlySet<string>): ReadonlySet<string> {
+  return union(a, b) ?? EMPTY_SET;
+}
+
+/** The effects of two parts that both start, one after the other. */
+export function sequence(...parts: EffectSummary[]): EffectSummary {
+  return parts.reduce(
+    (a, b) => ({
+      may: {
+        reads: union(a.may.reads, b.may.reads),
+        writes: union(a.may.writes, b.may.writes),
+        destructive: a.may.destructive || b.may.destructive,
+        idempotent: a.may.idempotent && b.may.idempotent,
+      },
+      must: { reads: unionMust(a.must.reads, b.must.reads), writes: unionMust(a.must.writes, b.must.writes) },
+    }),
+    NO_EFFECTS,
+  );
+}
+
+/** The effects of a part that can start zero times. */
+export function optional(part: EffectSummary): EffectSummary {
+  return { may: part.may, must: NO_EFFECTS.must };
+}
+
+/** The effects of one of two parts. */
+export function either(a: EffectSummary, b: EffectSummary): EffectSummary {
+  const intersect = (x: ReadonlySet<string>, y: ReadonlySet<string>): ReadonlySet<string> => new Set([...x].filter((name) => y.has(name)));
+  return {
+    may: sequence(a, b).may,
+    must: { reads: intersect(a.must.reads, b.must.reads), writes: intersect(a.must.writes, b.must.writes) },
+  };
+}
+
+/** The effects that an entry declares. Absent effects, or an absent list, are unknown. */
+export function declaredEffects(entry: ProcedureEntry | undefined): EffectSummary {
+  const effects = entry?.effects;
+  if (!effects) return UNKNOWN_EFFECTS;
+  return {
+    may: {
+      reads: effects.reads ? new Set(effects.reads) : undefined,
+      writes: effects.writes ? new Set(effects.writes) : undefined,
+      destructive: isDestructive(effects),
+      idempotent: isReadOnly(effects) || effects.idempotent === true,
+    },
+    must: { reads: new Set(effects.reads ?? []), writes: new Set(effects.writes ?? []) },
+  };
+}
+
+/** True when the effects are not fully known. */
+export function isUnknown(summary: EffectSummary): boolean {
+  return summary.may.reads === undefined || summary.may.writes === undefined;
+}
+
+/** The effects as the `Effects` of a manifest: an unknown list is absent. */
+export function toEffects(may: MayEffects): Effects {
+  return {
+    ...(may.reads ? { reads: [...may.reads].sort() } : {}),
+    ...(may.writes ? { writes: [...may.writes].sort() } : {}),
+    destructive: may.destructive,
+    idempotent: may.idempotent,
+  };
+}
+
+/** The result of the pass. */
+export interface EffectsAnalysis {
+  readonly program: EffectSummary;
+  /** The effects of each node. */
+  readonly byNode: ReadonlyMap<IRNode, EffectSummary>;
+  /** The effects of the program that each data-driven call runs (its body), when the compiler knows them. */
+  readonly nested: ReadonlyMap<IRNode, EffectSummary>;
+  /** The pointers of the calls whose effects the compiler does not know. */
+  readonly unknownAt: readonly Pointer[];
+}
+
+/** The effects of the body of a defined procedure, or undefined when the compiler cannot see it. */
+export type BodyEffects = (path: ProcedurePath) => EffectSummary | undefined;
+
+/** This function infers the effects of each node and of the program. */
+export function inferEffects(root: IRNode, facts: ProcedureFacts, bodyEffects: BodyEffects): EffectsAnalysis {
+  const byNode = new Map<IRNode, EffectSummary>();
+  const nested = new Map<IRNode, EffectSummary>();
+  const unknownAt: Pointer[] = [];
+
+  const items = (spec: ItemsSpec): { summary: EffectSummary; nonEmpty: boolean } =>
+    spec.kind === "list"
+      ? { summary: sequence(...spec.items.map(infer)), nonEmpty: spec.items.length > 0 }
+      : { summary: infer(spec.value), nonEmpty: false };
+
+  /** The effects of what a data-driven procedure runs. */
+  const inner = (node: CallNode | DynamicNode, entry: ProcedureEntry | undefined): EffectSummary => {
+    if (node.kind === "dynamic") {
+      if (node.model) return infer(node.model);
+      if (node.reason === "invalid-control-flow") return NO_EFFECTS;
+      if (node.reason === "raw-input" && entry && !entry.dataDriven) return NO_EFFECTS;
+      // procedure.define runs nothing now: the body runs when the new procedure starts
+      if (node.key === "procedure.define" && entry?.dataDriven) return NO_EFFECTS;
+    }
+    if (entry && !entry.dataDriven) return NO_EFFECTS;
+    if (entry) {
+      const body = bodyEffects(node.path);
+      if (body) return body;
+    }
+    return UNKNOWN_EFFECTS;
+  };
+
+  const infer = (node: IRNode): EffectSummary => {
+    let summary: EffectSummary;
+    switch (node.kind) {
+      case "literal":
+      case "reference":
+      case "fail":
+        summary = NO_EFFECTS;
+        break;
+      case "object":
+        summary = sequence(...node.entries.map((entry) => infer(entry.value)));
+        break;
+      case "array":
+        summary = sequence(...node.items.map(infer));
+        break;
+      case "deferred":
+        summary = infer(node.input);
+        break;
+      case "call":
+      case "dynamic": {
+        const entry = facts.entry(node.path);
+        const runs = inner(node, entry);
+        if (runs !== NO_EFFECTS) nested.set(node, runs);
+        summary = sequence(infer(node.input), declaredEffects(entry), runs);
+        if (isUnknown(declaredEffects(entry)) || isUnknown(runs)) unknownAt.push(node.pointer);
+        break;
+      }
+      case "chain":
+        summary = sequence(declaredEffects(facts.entry(node.path)), ...(node.initialInput ? [infer(node.initialInput)] : []), ...node.steps.map((step) => infer(step.node)));
+        break;
+      case "parallel":
+        summary = sequence(declaredEffects(facts.entry(node.path)), ...node.tasks.map(infer));
+        break;
+      case "conditional": {
+        const thenEffects = node.then ? infer(node.then) : NO_EFFECTS;
+        const elseEffects = node.else ? infer(node.else) : NO_EFFECTS;
+        summary = sequence(declaredEffects(facts.entry(node.path)), infer(node.condition), either(thenEffects, elseEffects));
+        break;
+      }
+      case "try":
+        summary = sequence(declaredEffects(facts.entry(node.path)), infer(node.try), optional(infer(node.catch)));
+        break;
+      case "and":
+      case "or": {
+        const [first, ...rest] = node.values.map(infer);
+        summary = sequence(declaredEffects(facts.entry(node.path)), ...(first ? [first] : []), ...rest.map(optional));
+        break;
+      }
+      case "map": {
+        const { summary: itemEffects, nonEmpty } = items(node.items);
+        const fn = node.fn ? infer(node.fn) : NO_EFFECTS;
+        summary = sequence(declaredEffects(facts.entry(node.path)), itemEffects, nonEmpty ? fn : optional(fn));
+        break;
+      }
+      case "reduce": {
+        const itemPart = node.items ? items(node.items) : { summary: NO_EFFECTS, nonEmpty: false };
+        const fn = node.fn ? infer(node.fn) : NO_EFFECTS;
+        summary = sequence(declaredEffects(facts.entry(node.path)), itemPart.summary, infer(node.initial), itemPart.nonEmpty ? fn : optional(fn));
+        break;
+      }
+    }
+    byNode.set(node, summary);
+    return summary;
+  };
+
+  const program = infer(root);
+  return { program, byNode, nested, unknownAt };
+}

package/src/explain.ts

@@ -0,0 +1,194 @@
+/**
+ * The explanation of a program (roadmap R23): the check and `explainInvocation()` of the client
+ * in one result.
+ *
+ * The result has the effects of the program, each call with its declared effects, the answer of
+ * the capability for the call, and the diagnostics. A short text in plain words tells the same.
+ * An application can show the text to a user before the user starts the program.
+ */
+
+import {
+  explainInvocation,
+  type AnyProcedure,
+  type Capability,
+  type CapabilityRefusalReason,
+  type Effects,
+  type ProcedurePath,
+} from "@procedures/client/browser";
+import { isCallLike, walk, type IRNode, type Pointer } from "./ir.js";
+import { isStringPath, withDefinitions, type ProcedureFacts } from "./facts.js";
+import { findDefinitions } from "./normalize.js";
+import { baseFacts, checkProgram, type CheckOptions, type MustEffects } from "./program.js";
+import type { Diagnostic } from "./diagnostics.js";
+
+/** The kind of a call: a call of a procedure, a control-flow call or a dynamic call. */
+export type CallKind = "call" | "control" | "dynamic";
+
+/** The explanation of one call of a program. */
+export interface CallExplanation {
+  /** The key of the procedure: its path with dots. */
+  readonly key: string;
+  readonly path: ProcedurePath;
+  /** The JSON pointer of the call in the program. */
+  readonly pointer: Pointer;
+  readonly kind: CallKind;
+  /** The effects that the procedure declares. Absent: the procedure does not declare its effects. */
+  readonly effects?: Effects | undefined;
+  /** True when the host has a procedure at the path. */
+  readonly known: boolean;
+  /** True when the host has the procedure and its expose rule lets a program call it. */
+  readonly exposed: boolean;
+  /** True when the capability permits the call (`explainInvocation()` of the client). */
+  readonly permitted: boolean;
+  /** The reason of a refusal, or `not-found` for a path without a procedure. */
+  readonly reason?: CapabilityRefusalReason | "not-found" | undefined;
+  /** The answer of `explainInvocation()` in words. */
+  readonly message: string;
+}
+
+/** The result of `explainProgram()`. */
+export interface ProgramExplanation {
+  /** True when no diagnostic is an error. A host starts the program only then. */
+  readonly ok: boolean;
+  /** The effects that a run can have (the upper bound). An absent `reads` or `writes`: not known. */
+  readonly effects: Effects;
+  /** The effects of each run in which no call fails (the lower bound). */
+  readonly mustEffects: MustEffects;
+  /** The calls of the program, in the order of the tree: a call comes before the calls of its input. */
+  readonly calls: CallExplanation[];
+  /** The problems that the check found, in the order of the program. */
+  readonly diagnostics: Diagnostic[];
+  /** The hash of the manifest that the check used. */
+  readonly registryHash: string;
+  /** The explanation in short sentences of plain words. */
+  readonly summary: string;
+}
+
+/** A capability without its deadline: the static check does not know the time of the run. */
+function withoutDeadline(capability: Capability<unknown> | undefined): Capability<unknown> | undefined {
+  if (!capability || capability.deadline === undefined) return capability;
+  const { deadline: _deadline, ...rest } = capability;
+  return rest;
+}
+
+/** A registry for `explainInvocation()` that has a procedure with the declared effects for each known path. */
+function registryOf(facts: ProcedureFacts): { get(path: ProcedurePath): AnyProcedure | undefined } {
+  return {
+    get: (path) => {
+      const entry = facts.entry(path);
+      return entry ? ({ path, metadata: entry.effects ? { effects: entry.effects } : {} } as unknown as AnyProcedure) : undefined;
+    },
+  };
+}
+
+function kindOf(node: IRNode): CallKind {
+  return node.kind === "call" ? "call" : node.kind === "dynamic" ? "dynamic" : "control";
+}
+
+/** A list in words: "a", "a and b", "a, b and c". */
+function listText(items: readonly string[]): string {
+  if (items.length <= 1) return items.join("");
+  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+
+function count(value: number, noun: string): string {
+  return `${value} ${noun}${value === 1 ? "" : "s"}`;
+}
+
+/** Each call of a list with its place, at most three, and the number of the others. */
+function callsText(calls: readonly CallExplanation[]): string {
+  const shown = calls.slice(0, 3).map((call) => `${call.key} at ${call.pointer === "" ? "the root" : call.pointer}`);
+  return calls.length > 3 ? `${shown.join(", ")} and ${calls.length - 3} more` : listText(shown);
+}
+
+/** The sentences of the effects. */
+function effectsText(effects: Effects, must: MustEffects): string[] {
+  const sentences: string[] = [];
+  const names = (list: readonly string[]): string => (list.length === 0 ? "nothing" : listText(list));
+  if (effects.reads && effects.writes) {
+    const reads = effects.reads.length === 0 ? "reads nothing" : `can read ${names(effects.reads)}`;
+    const writes = effects.writes.length === 0 ? "changes nothing" : `can change ${names(effects.writes)}`;
+    sentences.push(`The program ${reads} and ${writes}.`);
+  } else if (effects.reads) {
+    sentences.push(`The program ${effects.reads.length === 0 ? "reads nothing" : `can read ${names(effects.reads)}`}. The compiler does not know what it changes.`);
+  } else if (effects.writes) {
+    sentences.push(`The compiler does not know what the program reads. It ${effects.writes.length === 0 ? "changes nothing" : `can change ${names(effects.writes)}`}.`);
+  } else {
+    sentences.push("The compiler does not know the effects of the program: a call does not declare them, or it runs a program that the compiler cannot see.");
+  }
+  if (effects.writes && effects.writes.length > 0 && effects.destructive) sentences.push("A call can delete or overwrite data.");
+  if (must.reads.length > 0 || must.writes.length > 0) {
+    const parts = [...(must.reads.length > 0 ? [`reads ${names(must.reads)}`] : []), ...(must.writes.length > 0 ? [`changes ${names(must.writes)}`] : [])];
+    sentences.push(`Each run in which no call fails ${parts.join(" and ")}.`);
+  }
+  return sentences;
+}
+
+/** The text of the explanation, in short sentences. */
+function summaryOf(explanation: Omit<ProgramExplanation, "summary">): string {
+  const { calls, diagnostics } = explanation;
+  const sentences: string[] = [];
+  const keys = new Set(calls.map((call) => call.key));
+  sentences.push(`The program has ${count(calls.length, "call")} of ${count(keys.size, "procedure")}.`);
+  sentences.push(...effectsText(explanation.effects, explanation.mustEffects));
+  const unknown = calls.filter((call) => !call.known);
+  if (unknown.length > 0) sentences.push(`The host has no procedure for ${count(unknown.length, "call")}: ${callsText(unknown)}.`);
+  const hidden = calls.filter((call) => call.known && !call.exposed);
+  if (hidden.length > 0) sentences.push(`The host does not expose ${count(hidden.length, "call")}: ${callsText(hidden)}.`);
+  const refused = calls.filter((call) => call.known && !call.permitted);
+  if (refused.length > 0) sentences.push(`The capability refuses ${count(refused.length, "call")}: ${callsText(refused)}.`);
+  const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
+  const warnings = diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length;
+  sentences.push(
+    errors === 0
+      ? "The check found no error, so the host can start the program."
+      : `The check found ${count(errors, "error")}, so the host does not start the program.`,
+  );
+  if (warnings > 0) sentences.push(`The check also found ${count(warnings, "warning")}.`);
+  return sentences.join(" ");
+}
+
+/**
+ * This function explains a program before it starts. It checks the program, and it asks
+ * `explainInvocation()` of the client about each call. No call of the program starts.
+ */
+export function explainProgram(program: unknown, options: CheckOptions): ProgramExplanation {
+  const base = baseFacts(options);
+  const facts = withDefinitions(base, findDefinitions(program));
+  const result = checkProgram(program, { ...options, facts: base });
+  const capability = withoutDeadline(options.capability);
+  const registry = registryOf(facts);
+  const calls: CallExplanation[] = [];
+  const visit = (node: IRNode): void => {
+    if (!isCallLike(node)) return;
+    const path = node.path;
+    if (isStringPath(path) && path.length > 0 && path.every((segment) => segment.length > 0)) {
+      const entry = facts.entry(path);
+      const answer = explainInvocation(path, capability, registry);
+      calls.push({
+        key: node.key,
+        path: [...path],
+        pointer: node.pointer,
+        kind: kindOf(node),
+        ...(entry?.effects ? { effects: entry.effects } : {}),
+        known: entry !== undefined,
+        exposed: entry !== undefined && facts.exposed(path),
+        permitted: answer.permitted,
+        ...(answer.reason !== undefined ? { reason: answer.reason } : {}),
+        message: answer.message,
+      });
+    }
+    // The program that a dynamic call runs, when the compiler can see it (client.eval of a literal path)
+    if (node.kind === "dynamic" && node.model) walk(node.model, visit);
+  };
+  walk(result.ir.root, visit);
+  const explanation: Omit<ProgramExplanation, "summary"> = {
+    ok: result.ok,
+    effects: result.effects,
+    mustEffects: result.mustEffects,
+    calls,
+    diagnostics: result.diagnostics,
+    registryHash: result.registryHash,
+  };
+  return { ...explanation, summary: summaryOf(explanation) };
+}

package/src/facts.ts

@@ -0,0 +1,161 @@
+/**
+ * The facts about procedures that the compiler reads. They are the manifest entry of a path,
+ * the expose rule, the raw-input rule and the body of a defined procedure.
+ *
+ * A browser has only a manifest (`procedure.manifest`, roadmap R17). A host has the registry.
+ * The two functions of this module give the same facts from each source, so the passes do not
+ * know the source.
+ */
+
+import {
+  allCoreProcedures,
+  describeProcedureEntry,
+  describeRegistry,
+  hashOf,
+  isControlFlowPath,
+  pathToKey,
+  runtimeProgramOf,
+  RAW_INPUT_TAG,
+  RUNS_REFS_TAG,
+  type AnyProcedure,
+  type ProcedureEntry,
+  type ProcedureManifest,
+  type ProcedurePath,
+} from "@procedures/client/browser";
+
+/** The procedure facts of the compiler. */
+export interface ProcedureFacts {
+  /** The hash of the manifest that the host gives (`procedure.manifest`). */
+  readonly hash: string;
+  /** The keys of the procedures that take raw input, without the control-flow procedures. */
+  readonly rawKeys: readonly string[];
+  /** The manifest entry of a path, or undefined when the source does not have the path. */
+  entry(path: ProcedurePath): ProcedureEntry | undefined;
+  /** True when the host lets a data-driven procedure call the path. */
+  exposed(path: ProcedurePath): boolean;
+  /** True when hydration gives the procedure its input raw (`rawInputRule()` of the client). */
+  rawInput(path: ProcedurePath): boolean;
+  /** The program of a procedure that `procedure.define` made, when the source can see it. */
+  body(path: ProcedurePath): unknown;
+  /** The core procedure at the path, when the entry describes exactly that procedure. */
+  core(path: ProcedurePath): AnyProcedure | undefined;
+}
+
+/** A registry, as the compiler reads it. */
+export interface RegistryLike {
+  get(path: ProcedurePath): AnyProcedure | undefined;
+  getAll(): AnyProcedure[];
+}
+
+/** The options of the fact sources. */
+export interface FactsOptions {
+  /** The expose rule of the host. The default exposes each procedure. */
+  readonly expose?: ((path: ProcedurePath) => boolean) | undefined;
+}
+
+/** True when an entry takes its input raw: the rule of `takesRawInput()`, from the manifest. */
+export function entryTakesRawInput(entry: ProcedureEntry): boolean {
+  const tags = entry.tags ?? [];
+  return isControlFlowPath(entry.path) || tags.includes(RUNS_REFS_TAG) || tags.includes(RAW_INPUT_TAG);
+}
+
+/** True when the path elements are strings: only such a path can name a procedure. */
+export function isStringPath(path: readonly unknown[]): path is ProcedurePath {
+  return path.every((segment) => typeof segment === "string");
+}
+
+let coreDescriptions: Map<string, { procedure: AnyProcedure; hash: string }> | undefined;
+
+/** The core procedures by key, with the hash of their manifest entries. */
+function coreByKey(): Map<string, { procedure: AnyProcedure; hash: string }> {
+  if (!coreDescriptions) {
+    coreDescriptions = new Map(
+      allCoreProcedures.map((procedure) => [pathToKey(procedure.path), { procedure, hash: hashOf(describeProcedureEntry(procedure)) }]),
+    );
+  }
+  return coreDescriptions;
+}
+
+/**
+ * This function gives the core procedure that an entry describes. The entry must be the same as
+ * the description of the core procedure: a host can register a different procedure at a core path.
+ */
+export function coreProcedureOf(entry: ProcedureEntry | undefined): AnyProcedure | undefined {
+  if (!entry) return undefined;
+  const core = coreByKey().get(entry.key);
+  return core && core.hash === hashOf(entry) ? core.procedure : undefined;
+}
+
+/** The facts of a manifest. The manifest has only the procedures that its host exposes. */
+export function manifestFacts(manifest: ProcedureManifest, options: FactsOptions = {}): ProcedureFacts {
+  const byKey = new Map(manifest.procedures.map((entry) => [entry.key, entry]));
+  const expose = options.expose;
+  const rawKeys = manifest.procedures.filter((entry) => entryTakesRawInput(entry) && !isControlFlowPath(entry.path)).map((entry) => entry.key);
+  // The key of a path, as the registry finds it: the segments joined with dots, also for a segment that is not a string
+  const lookup = (path: ProcedurePath): ProcedureEntry | undefined => byKey.get(pathToKey(path));
+  return {
+    hash: manifest.hash,
+    rawKeys,
+    entry: lookup,
+    exposed: (path) => (expose ? expose(path) : true),
+    rawInput: (path) => {
+      const entry = lookup(path);
+      return entry ? entryTakesRawInput(entry) : isControlFlowPath(path);
+    },
+    body: () => undefined,
+    core: (path) => coreProcedureOf(lookup(path)),
+  };
+}
+
+/**
+ * The facts of a registry. The entries include the procedures that the host does not expose, so
+ * the check can tell "not exposed" from "unknown". The hash is the hash of `procedure.manifest` on
+ * the host: the manifest of the exposed procedures.
+ */
+export function registryFacts(registry: RegistryLike, options: FactsOptions = {}): ProcedureFacts {
+  const manifest = describeRegistry(registry, { withoutHandler: true });
+  const expose = options.expose;
+  const exposedEntries = manifest.procedures.filter((entry) => entry.hasHandler && (!expose || expose(entry.path)));
+  const facts = manifestFacts({ ...manifest, hash: hashOf(exposedEntries) }, options);
+  return {
+    ...facts,
+    body: (path) => {
+      if (!isStringPath(path)) return undefined;
+      const procedure = registry.get(path);
+      return procedure ? runtimeProgramOf(procedure) : undefined;
+    },
+  };
+}
+
+/**
+ * The facts with the procedures that the program defines (`procedure.define` with a literal path
+ * and body). A later call of such a path is known, and its body gives its effects.
+ */
+export function withDefinitions(facts: ProcedureFacts, definitions: ReadonlyMap<string, Definition>): ProcedureFacts {
+  if (definitions.size === 0) return facts;
+  const defined = (path: ProcedurePath): Definition | undefined => (isStringPath(path) ? definitions.get(pathToKey(path)) : undefined);
+  const definedRaw = [...definitions.values()].filter((definition) => entryTakesRawInput(definition.entry)).map((definition) => definition.entry.key);
+  return {
+    hash: facts.hash,
+    rawKeys: [...new Set([...facts.rawKeys, ...definedRaw])],
+    entry: (path) => defined(path)?.entry ?? facts.entry(path),
+    exposed: (path) => facts.exposed(path),
+    rawInput: (path) => {
+      const definition = defined(path);
+      return definition ? entryTakesRawInput(definition.entry) : facts.rawInput(path);
+    },
+    body: (path) => {
+      const definition = defined(path);
+      return definition ? definition.body : facts.body(path);
+    },
+    core: (path) => (defined(path) ? undefined : facts.core(path)),
+  };
+}
+
+/** A procedure that the program defines with `procedure.define`. */
+export interface Definition {
+  readonly entry: ProcedureEntry;
+  readonly body: unknown;
+  /** The pointer of the aggregation in the program. */
+  readonly pointer: string;
+}