@mark1russell7/coeval 0.23.0 → 0.24.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "coeval: the kernel of declarative languages. Documents in envelopes, a ladder that finds the evaluator, kind contracts, compiled plans, a static kit, a formula kit and a run side with capabilities.",
   "type": "module",
   "main": "./build/index.js",

package/src/conform.ts

@@ -867,7 +867,7 @@ function instanceOf(env: Env, under: Under, doc: Envelope, split: SplitOk, sampl
     const fn = under.fn;
     return (shot) => {
       const ctx = shot.context;
-      const parts: RunPart[] = split.parts.map((slot, index) => ({ ...handleOf(slot), evaluate: (given?: Context) => shot.steps(index, "evaluate", given ?? ctx) }));
+      const parts: RunPart[] = split.parts.map((slot, index) => ({ ...handleOf(slot), evaluate: (given?: Context) => shot.steps(index, "evaluate", given ?? ctx), handled: () => shot.steps(index, "evaluate", ctx) }));
       const input: RunInput = {
         ...base,
         value: fill(parts),

package/src/effects.ts

@@ -46,7 +46,7 @@ function reaching(machine: Machine, doc: unknown, options: EffectsOptions): read
     doc,
     (v) => {
       const caps = v.caps ?? EACH;
-      for (const kind of declaredEffects(v, "eval", machine)) if (rule(caps, kind)) out.push({ kind, visit: v });
+      for (const kind of declaredEffects(v, "eval", machine)) if (rule(caps, kind) && (v.handled === undefined || !permits(v.handled, kind))) out.push({ kind, visit: v });
       return undefined;
     },
     { caps: options.caps ?? EACH, ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }) },

package/src/evaluate.ts

@@ -109,7 +109,7 @@ export function intersectCaps(a: readonly Cap[], b: readonly Cap[]): readonly Ca
 /** This function gives the capability rules of a kind that cover a part and change its capabilities. */
 function rulesFor(rules: readonly CapsRule[] | undefined, path: readonly Key[]): readonly CapsRule[] {
   if (rules === undefined || rules.length === 0) return NO_RULES;
-  const out = rules.filter((rule) => rule.rule !== "same" && (rule.in === undefined || rule.in.some((pattern) => pathMatches(path, pattern))));
+  const out = rules.filter((rule) => rule.rule !== "same" && rule.rule !== "grant" && (rule.in === undefined || rule.in.some((pattern) => pathMatches(path, pattern))));
   return out.length === 0 ? NO_RULES : out;
 }
 
@@ -136,6 +136,87 @@ export function partCaps(rules: readonly CapsRule[] | undefined, path: readonly
   return capsUnder(rulesFor(rules, path), caps);
 }
 
+/** This function collects the values at a path in a value. The key `"*"` steps into each item of a list. */
+function collectAt(value: unknown, path: readonly Key[], index: number, out: Cap[]): void {
+  if (index === path.length) {
+    if (typeof value === "string" || (Array.isArray(value) && value.every((key) => typeof key === "string" || typeof key === "number"))) out.push(value as Cap);
+    return;
+  }
+  const key = path[index] as Key;
+  if (key === "*") {
+    if (Array.isArray(value)) for (const item of value) collectAt(item, path, index + 1, out);
+    return;
+  }
+  if (typeof value === "object" && value !== null) collectAt((value as Record<Key, unknown>)[key], path, index + 1, out);
+}
+
+/**
+ * This function gives the capabilities that the rules `grant` of a kind give one part (CAP.GRANT). The check and the
+ * walk read them from the document. The kernel gets the same list from the clauses of the runner.
+ *
+ * @param rules - The capability rules of the kind (`Kind.caps`).
+ * @param path - The path of the part in the value of the document.
+ * @param value - The value of the document.
+ * @returns The capabilities that the rules add, or an empty list.
+ */
+export function partGrants(rules: readonly CapsRule[] | undefined, path: readonly Key[], value: unknown): readonly Cap[] {
+  if (rules === undefined) return NO_CAPS;
+  let out: Cap[] | undefined;
+  for (const rule of rules) {
+    if (rule.rule !== "grant" || (rule.in !== undefined && !rule.in.some((pattern) => pathMatches(path, pattern)))) continue;
+    collectAt(value, rule.from, 0, (out ??= []));
+  }
+  return out ?? NO_CAPS;
+}
+
+/**
+ * One clause of a handler (D146): the effects under `op` go to `answer` and not to the host. The clause runs in place,
+ * as a part of the effect that it answers. Its result is the result of that effect.
+ */
+export interface Clause {
+  /** The kind of the effects: the clause answers this kind and each kind under it (CAP.KEYS). */
+  readonly op: Cap;
+  /**
+   * This function answers one effect. It sees only the payload (HANDLE.SEALED).
+   *
+   * @param payload - The data of the effect.
+   * @returns The steps that give the result of the effect.
+   */
+  answer(payload: unknown): Steps;
+}
+
+/** The clauses of one active `handle`, and the frame around it. */
+interface Frame {
+  readonly clauses: readonly Clause[];
+  readonly outer: Frame | undefined;
+  /** The runtime of the evaluation that started the frame. A frame of another evaluation has ended. */
+  readonly owner: Runtime;
+  /** `true` after the body ends. A closure can leave the body with the context of the frame (HANDLE.ENDED). */
+  ended: boolean;
+}
+
+/**
+ * The key of the frame of a context. Like the grant, it stays through a spread of a context, and only the kernel writes
+ * it. It is not a root (D10): a document cannot read it (HANDLE.SEALED).
+ */
+const FRAME = /* @__PURE__ */ Symbol("coeval.frame");
+
+/** A context that can have a frame. */
+type Framed = Context & { readonly [FRAME]?: Frame };
+
+/** This function gives the frame of a context, when it has one. */
+function frameOf(ctx: Context): Frame | undefined {
+  return (ctx as Framed)[FRAME];
+}
+
+/** This function finds the frame and the clause that answer an effect. The innermost frame wins, then the first clause. */
+function clauseFor(start: Frame, keys: readonly Key[]): { readonly frame: Frame; readonly clause: Clause } | undefined {
+  for (let frame: Frame | undefined = start; frame !== undefined; frame = frame.outer) {
+    for (const clause of frame.clauses) if (permits([clause.op], keys)) return { frame, clause };
+  }
+  return undefined;
+}
+
 /**
  * The key of the grant of a context (CAP.NARROW-CODE): the capabilities that the kernel gave the document of the
  * context. A spread of a context keeps its grant. Thus compiled code passes the grant on in each context that it makes
@@ -669,6 +750,14 @@ export interface RunPart {
    * @returns The steps of the evaluation of the part.
    */
   evaluate(context?: Context): Steps;
+  /**
+   * This function evaluates the part under clauses that answer its effects (D146). The kernel sets it on each part of
+   * a kind with a rule `grant`. A part that a runner makes itself has none, and a compiled runner gets no such part.
+   *
+   * @param clauses - The clauses, in order. An effect goes to the first clause that names its kind.
+   * @returns The steps of the evaluation of the part.
+   */
+  handled?(clauses: readonly Clause[]): Steps;
 }
 
 /** The input of a runner: the input of an evaluator, with parts and effects that can wait. */
@@ -1288,14 +1377,35 @@ class Session implements Runtime {
     return (effect.outcome = fail("#CALC!", `The mock gave a promise for the effect ${effect.kind}, and an evaluation does not wait.`, { place }));
   }
 
+  /**
+   * This function finds the clause that answers an effect (D146). Without it, the effect goes on to the host. An effect
+   * without a capability gets no clause, thus `record` gives its `#CAP!` (HANDLE.NARROW). A clause of a frame that has
+   * ended gives `#CAP!`, because the capability came from that frame (HANDLE.ENDED).
+   */
+  private clauseOf(given: Context, start: Frame, kind: Cap, place: readonly Key[]): Clause | Result | undefined {
+    const ctx = inEpoch(given, this.epoch) ? granted(given) : ungranted(given, this.epoch);
+    const keys = typeof kind === "string" ? kind.split(".") : kind;
+    if (!this.permitted(ctx, keys)) return undefined;
+    const found = clauseFor(start, keys);
+    if (found === undefined) return undefined;
+    if (found.frame.ended || found.frame.owner !== this) return fail("#CAP!", `The handler of the effect ${keys.join(".")} has ended.`, { place });
+    return found.clause;
+  }
+
   effect(ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result {
     const text = typeof kind === "string" ? kind : kind.join(".");
     if (this.running) return fail("#CALC!", `The effect ${text} needs a runner: in a run, the host does each effect.`, { place });
+    const frame = frameOf(ctx);
+    const clause = frame === undefined ? undefined : this.clauseOf(ctx, frame, kind, place);
+    if (clause !== undefined) return "ok" in clause ? clause : drive(clause.answer(payload), text);
     const made = this.record(ctx, kind, payload, place);
     return "ok" in made ? made : this.answer(made, place);
   }
 
   *runEffect(ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Steps {
+    const frame = frameOf(ctx);
+    const clause = frame === undefined ? undefined : this.clauseOf(ctx, frame, kind, place);
+    if (clause !== undefined) return "ok" in clause ? clause : yield* clause.answer(payload);
     const made = this.record(ctx, kind, payload, place);
     if ("ok" in made) return made;
     const perform = this.perform;
@@ -1771,7 +1881,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
   if (runner !== undefined) {
     let inner: RunCode;
     try {
-      inner = isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill);
+      inner = isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill, kind?.caps?.some((rule) => rule.rule === "grant") === true);
     } catch (error) {
       return failingWith(c, meta, placed(thrown(error, `the runner ${name}`), place));
     }
@@ -2316,7 +2426,25 @@ function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly
   };
 }
 
-function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonly P[]) => unknown): RunCode {
+/**
+ * This function runs a part under a new frame (D146). The part gets the capabilities of the document and the kinds of
+ * the clauses (CAP.GRANT), with the grant of the kernel. A rule around an effect narrows them as it narrows any other
+ * capability (HANDLE.NARROW). The frame ends with the steps.
+ */
+function* handling(given: Context, clauses: readonly Clause[], rt: Runtime, run: (ctx: Context) => Steps): Steps {
+  const ctx = granted(given);
+  const frame: Frame = { clauses, outer: frameOf(ctx), owner: rt, ended: false };
+  const caps = [...ctx.caps];
+  for (const clause of clauses) if (!permits(caps, clause.op)) caps.push(clause.op);
+  const inner: Granted & Framed = { ...ctx, caps, [GRANT]: caps, [EPOCH]: epochOf(ctx), [FRAME]: frame };
+  try {
+    return yield* run(inner);
+  } finally {
+    frame.ended = true;
+  }
+}
+
+function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonly P[]) => unknown, grants: boolean): RunCode {
   const { kind, typePath, doc, data, place, machine } = input;
   const refill = input.fill;
   const compiled = input.parts;
@@ -2327,6 +2455,8 @@ function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonl
       path: part.path,
       ...(part.name === undefined ? {} : { name: part.name }),
       evaluate: (override?: Context) => part.run(override === undefined ? ctx : handed(ctx, override), rt),
+      // Only a kind with a rule grant pays for this function: most runners stay as fast as before.
+      ...(grants ? { handled: (clauses: readonly Clause[]) => handling(ctx, clauses, rt, (inner) => part.run(inner, rt)) } : {}),
     }));
     return fn({
       kind,

package/src/index.ts

@@ -161,6 +161,7 @@ export {
   type RunFn,
   type RunInput,
   type RunOptions,
+  type Clause,
   type RunPart,
   type Runner,
   type Runtime,
@@ -177,6 +178,7 @@ export {
   narrow,
   nodeAt,
   partCaps,
+  partGrants,
   permits,
   planner,
   prepare,
@@ -267,6 +269,8 @@ export {
   type SyntaxCalls,
   type SyntaxConstructs,
   type SyntaxEnvelopes,
+  type SyntaxFinding,
+  type SyntaxFindingCode,
   type SyntaxFixity,
   type SyntaxForm,
   type SyntaxFormArgs,
@@ -279,6 +283,7 @@ export {
   type SyntaxRefs,
   MAX_SYNTAX_ISSUES,
   STD_SYNTAX,
+  checkSyntax,
   parse,
   print,
   syntaxFormat,

package/src/reference.ts

@@ -21,6 +21,7 @@ import { type AttributeRung, AT_READERS, STD_EVALUATORS } from "./stdlib.ts";
 import { type EvalError, type Failed, type Result, Failure, describe, fail, ok, placed, thrown } from "./errors.ts";
 import {
   type AllOptions,
+  type Clause,
   type Effect,
   type EvalFn,
   type EvalInput,
@@ -295,6 +296,44 @@ function freeIn(root: Context, ctx: Context, path: readonly unknown[]): boolean
   return bound === Object.hasOwn(root.names, key) && (!bound || Object.is(ctx.names[key], root.names[key]));
 }
 
+/** The clauses of one active `handle`, as SPEC tells: the frame around it, and if its body has ended. */
+interface RefFrame {
+  readonly clauses: readonly Clause[];
+  readonly outer: RefFrame | undefined;
+  /** The list of the effects of the evaluation: a frame of another evaluation has ended. */
+  readonly owner: unknown;
+  ended: boolean;
+}
+
+/** The key of the frame of a context. */
+const REF_FRAME = /* @__PURE__ */ Symbol("coeval.reference.frame");
+
+/** This function gives the frame of a context. */
+function refFrame(ctx: Context): RefFrame | undefined {
+  return (ctx as Context & { readonly [REF_FRAME]?: RefFrame })[REF_FRAME];
+}
+
+/**
+ * This function finds the clause for an effect (HANDLE.DO, HANDLE.FORWARD). An effect without a capability gets no clause
+ * (HANDLE.NARROW). A clause of a frame that has ended gives `#CAP!` (HANDLE.ENDED).
+ */
+function clauseAt(env: Env, ctx: Context, kind: Cap, place: readonly Key[]): Clause | Failed | undefined {
+  let frame = refFrame(ctx);
+  if (frame === undefined) return undefined;
+  const keys = typeof kind === "string" ? kind.split(".") : kind;
+  const machine = env.machine;
+  const allowed = machine.permits === undefined ? permits(ctx.caps, keys) : machine.permits(ctx.caps, keys, ctx);
+  if (!allowed) return undefined;
+  for (; frame !== undefined; frame = frame.outer) {
+    for (const clause of frame.clauses) {
+      if (!permits([clause.op], keys)) continue;
+      if (frame.ended || frame.owner !== env.effects) return fail("#CAP!", `The handler of the effect ${keys.join(".")} has ended.`, { place });
+      return clause;
+    }
+  }
+  return undefined;
+}
+
 /**
  * This function causes an effect when the capabilities permit it (RUN.CAP, CAP.HOOK). It records the effect with its
  * address (RUN.ADDRESS) and its outcome (RUN.OUTCOME). The mock answers the effect at once (RUN.MOCK). Without a
@@ -314,6 +353,8 @@ function cause(env: Env, ctx: Context, kind: Cap, payload: unknown, place: reado
 function causeFromEvaluator(env: Env, ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result {
   const text = typeof kind === "string" ? kind : kind.join(".");
   if (env.running) return fail("#CALC!", `The effect ${text} needs a runner: in a run, the host does each effect.`, { place });
+  const clause = clauseAt(env, ctx, kind, place);
+  if (clause !== undefined) return "ok" in clause ? clause : drive(clause.answer(payload), place, text);
   return cause(env, ctx, kind, payload, place);
 }
 
@@ -323,6 +364,8 @@ function causeFromEvaluator(env: Env, ctx: Context, kind: Cap, payload: unknown,
  * (RUN.OUTCOME).
  */
 function* causeAndWait(env: Env, ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Steps {
+  const clause = clauseAt(env, ctx, kind, place);
+  if (clause !== undefined) return "ok" in clause ? clause : yield* clause.answer(payload);
   if (!env.running) return cause(env, ctx, kind, payload, place);
   const effect = recordEffect(env, ctx, kind, payload, place);
   if ("ok" in effect) return effect;
@@ -480,6 +523,17 @@ function evalInput(env: Env, seen: Seen, at: At): EvalInput {
   };
 }
 
+/** This function evaluates a part under a frame: the part also gets the kinds of the clauses (CAP.GRANT). */
+function* handledAt(env: Env, part: At, clauses: readonly Clause[]): Steps {
+  const frame: RefFrame = { clauses, outer: refFrame(part.ctx), owner: env.effects, ended: false };
+  const ctx = { ...part.ctx, caps: [...part.ctx.caps, ...clauses.map((clause) => clause.op)], [REF_FRAME]: frame };
+  try {
+    return yield* stepsAt(env, { ...part, ctx });
+  } finally {
+    frame.ended = true;
+  }
+}
+
 function runInput(env: Env, seen: Seen, at: At): RunInput {
   const { split, doc } = seen;
   const parts: RunPart[] = split.parts.map((slot) => {
@@ -489,6 +543,7 @@ function runInput(env: Env, seen: Seen, at: At): RunInput {
       path: slot.path,
       ...(name === undefined ? {} : { name }),
       evaluate: (given?: Context) => stepsAt(env, partAt(seen, at, slot, given)),
+      handled: (clauses: readonly Clause[]) => handledAt(env, partAt(seen, at, slot, undefined), clauses),
     };
   });
   const fill = (items: readonly unknown[]): unknown => (split.parts.length === 0 ? doc.value : split.fill(items));

package/src/static.ts

@@ -4,7 +4,7 @@ import { answerOf, ask } from "./ladder.ts";
 import { type PartSlot, partsOf, rulesCover, scopesOf } from "./parts.ts";
 import { type Cap, type Context, type Root, ROOTS, context, isRef, walkerOf, worldThing } from "./deref.ts";
 import type { ErrorCode } from "./errors.ts";
-import { type Machine, partCaps, permits, waitedReason } from "./evaluate.ts";
+import { type Machine, partCaps, partGrants, permits, waitedReason } from "./evaluate.ts";
 import type { ValueType } from "./types.ts";
 import { type RootTypes, type TypeNode, type Typed, machineTypeIssues, typePass } from "./typing.ts";
 import { cycleIssues } from "./instances.ts";
@@ -41,6 +41,8 @@ export interface DocVisit {
    * around it (`Kind.caps`). A walk without capabilities gives none here.
    */
   readonly caps?: readonly Cap[] | undefined;
+  /** The kinds of effects that a handler around the document answers (CAP.GRANT, D146). Such an effect does not reach the host. */
+  readonly handled?: readonly Cap[] | undefined;
 }
 
 /** A position that a walk cannot read as a document. */
@@ -114,6 +116,7 @@ class Visit implements DocVisit {
   readonly typePath: readonly Key[] | undefined;
   readonly address: true | undefined;
   readonly caps: readonly Cap[] | undefined;
+  readonly handled: readonly Cap[] | undefined;
   readonly #place: Trail | undefined;
   readonly #at: Trail | undefined;
   readonly #bound: readonly string[];
@@ -135,6 +138,7 @@ class Visit implements DocVisit {
     caps: readonly Cap[] | undefined,
     bound: readonly string[],
     expect: ValueType | undefined,
+    handled: readonly Cap[] | undefined,
   ) {
     this.doc = doc;
     this.declared = declared;
@@ -147,6 +151,7 @@ class Visit implements DocVisit {
     this.typePath = typePath;
     this.address = address;
     this.caps = caps;
+    this.handled = handled;
     this.#place = place;
     this.#at = at;
     this.#bound = bound;
@@ -199,6 +204,7 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
     readonly caps: readonly Cap[] | undefined;
     readonly bound: readonly string[];
     readonly expect: ValueType | undefined;
+    readonly handled: readonly Cap[] | undefined;
   }
   const stack: Item[] = [
     {
@@ -213,6 +219,7 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
       slot: [],
       parent: undefined,
       caps: options.caps,
+      handled: undefined,
       bound: [],
       expect: undefined,
     },
@@ -241,6 +248,7 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
       item.caps,
       item.bound,
       item.expect,
+      item.handled,
     );
     const answer = visit(here);
     if (answer === "skip" || kind === undefined) continue;
@@ -254,6 +262,7 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
       const slot = split.parts[index] as PartSlot;
       const extra = sees[index] ?? [];
       const hidden = later[index] ?? [];
+      const grants = partGrants(kind.caps, slot.path, doc.value);
       stack.push({
         value: slot.item,
         place: slot.path.length === 0 ? item.place : { up: item.place, keys: slot.path },
@@ -265,7 +274,8 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
         address: slot.address === true,
         slot: slot.path,
         parent: here,
-        caps: item.caps === undefined || kind.caps === undefined ? item.caps : partCaps(kind.caps, slot.path, item.caps),
+        caps: item.caps === undefined || kind.caps === undefined ? item.caps : [...partCaps(kind.caps, slot.path, item.caps), ...grants],
+        handled: grants.length === 0 ? item.handled : [...(item.handled ?? []), ...grants],
         bound: extra,
         expect: slot.expect,
       });
@@ -770,6 +780,7 @@ const KEEPS_SELF: ReadonlySet<string> = /* @__PURE__ */ new Set([
   "control.seq",
   "control.pure",
   "control.if",
+  "control.handle",
   "list.all",
   "effect.log",
   "effect.write",

package/src/stdlib.ts

@@ -1,7 +1,8 @@
-import { type Json, type Key, docEquals, field, isRecord } from "./doc.ts";
+import { type Json, type Key, docEquals, field, isKey, isRecord } from "./doc.ts";
 import {
   type EvalInput,
   type Evaluator,
+  type Clause,
   type InputWithRuntime,
   type Machine,
   type Plan,
@@ -144,6 +145,27 @@ export const STD_WORLD: World = {
       lazy: [{ after: 1 }],
       summary: "It evaluates its part without capabilities, thus an effect in it fails.",
     },
+    handle: {
+      verbs: { eval: "control.handle", view: "view.op" },
+      parts: {
+        shape: "record",
+        fields: {
+          with: { shape: "list", item: { shape: "record", fields: { op: { shape: "none" }, do: { shape: "term" }, abort: { shape: "term" } }, required: ["op"], closed: true } },
+          return: { shape: "term" },
+          body: { shape: "term" },
+        },
+        required: ["with", "body"],
+        closed: true,
+      },
+      scope: [
+        { names: { fixed: ["payload"] }, in: [["with", "*", "do"], ["with", "*", "abort"]] },
+        { names: { fixed: ["result"] }, in: [["return"]] },
+      ],
+      caps: [{ rule: "grant", from: ["with", "*", "op"], in: [["body"]] }],
+      // A clause runs at an effect of the body, and the clause return runs only after a body without a failure.
+      lazy: [{ in: [["with", "*", "do"], ["with", "*", "abort"], ["return"]] }],
+      summary: "It answers the effects of its body with its clauses, in place, thus a mock, a retry or a log is a document.",
+    },
     log: {
       verbs: { eval: "effect.log", view: "view.op" },
       parts: { shape: "list", of: "text" },
@@ -1493,6 +1515,18 @@ function* inOrder(parts: readonly RunPart[]): Generator<Promise<unknown>, { read
   return { values };
 }
 
+/** The value of a `handle` document, with a part in the place of each part. */
+interface HandleValue {
+  readonly with: readonly { readonly op: Cap; readonly do?: RunPart; readonly abort?: RunPart }[];
+  readonly return?: RunPart;
+  readonly body?: RunPart;
+}
+
+/** This function tells if a value names a kind of effects: a text, or a list of keys. */
+function isOp(value: unknown): value is Cap {
+  return typeof value === "string" || (Array.isArray(value) && value.every(isKey));
+}
+
 /**
  * The runners of the standard world, by name: the kinds that can hold effects. Each one evaluates its parts in
  * order. In a run, an effect ends before the next step starts.
@@ -1516,6 +1550,32 @@ export const STD_RUNNERS: Readonly<Record<string, Runner>> = {
     if (only === undefined || parts.length > 1) return fail("#VALUE!", "pure needs exactly one part.");
     return yield* only.evaluate();
   },
+  // A clause gets the context of the handle document, thus it has no more authority than its parent (HANDLE.CLAUSE).
+  "control.handle": function* ({ value, context }) {
+    const { with: list, return: after, body } = value as HandleValue;
+    if (body?.handled === undefined) return fail("#VALUE!", "handle needs a body.");
+    let stopped: Result | undefined;
+    const clauses: Clause[] = [];
+    for (const item of list) {
+      const part = item.do ?? item.abort;
+      if (!isOp(item.op)) return fail("#VALUE!", "The op of a clause of handle must be a text or a list of keys.");
+      if (part === undefined || (item.do !== undefined && item.abort !== undefined)) return fail("#VALUE!", "Each clause of handle needs exactly one of do and abort.");
+      const stops = item.do === undefined;
+      clauses.push({
+        op: item.op,
+        answer: function* (payload) {
+          const result = yield* part.evaluate({ ...context, names: { ...context.names, payload } });
+          if (!stops) return result;
+          stopped ??= result;
+          return fail("#CALC!", "A clause abort of handle stopped the body.");
+        },
+      });
+    }
+    const result = yield* body.handled(clauses);
+    if (stopped !== undefined) return stopped;
+    if (!result.ok || after === undefined) return result;
+    return yield* after.evaluate({ ...context, names: { ...context.names, result: result.value } });
+  },
   "control.if": function* ({ parts }) {
     const test = parts.find((part) => part.key === "test");
     if (test === undefined) return fail("#VALUE!", "if needs a test.");