@mark1russell7/coeval 0.23.0 → 0.24.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "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",
@@ -36,8 +36,8 @@
   ],
   "devDependencies": {
     "@mark1russell7/cue": "^2.1.1",
-    "@mark1russell7/rigor-bench": "^0.2.15",
-    "@mark1russell7/rigor-statistics": "^0.1.12",
+    "@mark1russell7/rigor-bench": "^0.2.29",
+    "@mark1russell7/rigor-statistics": "^0.1.16",
     "@types/node": "^26.6.4",
     "esbuild": "^0.28.2",
     "typescript": "^7.0.2",

package/src/agree.ts

@@ -1,7 +1,10 @@
 import { type Key, docEquals, equalWith } from "./doc.ts";
 import { type Context, isHostThing } from "./deref.ts";
-import { type EvalError, type Result, isStackOverflow, thrown } from "./errors.ts";
-import { type Effect, type Machine, type Perform, type Read, JOURNAL, evaluate, makeContext, prepare, run, sharedCopy } from "./evaluate.ts";
+import { type EvalError, type Result, describe, isStackOverflow, thrown } from "./errors.ts";
+import { type CheckOptions, typeCheck } from "./static.ts";
+import { isPrecise, member, typeText } from "./types.ts";
+import { boundariesOf } from "./typing.ts";
+import { type Effect, type Machine, type Perform, type Read, type TraceNode, JOURNAL, evaluate, makeContext, prepare, run, sharedCopy } from "./evaluate.ts";
 import { Held, isClosure } from "./formula.ts";
 import { type Definitions, reference, referenceRun } from "./reference.ts";
 import { type ReplaySettle, recorder, relay, replayer } from "./replay.ts";
@@ -392,6 +395,15 @@ function resolutions(reads: readonly Read[]): readonly Read[] {
   return reads.filter((read) => read.free && read.kept !== true);
 }
 
+/** This function gives the text of a value of a trace. It does not throw for a bigint or a record with a cycle. */
+function valueText(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? describe(value);
+  } catch {
+    return describe(value);
+  }
+}
+
 function pathText(path: readonly unknown[] | undefined): string {
   if (path === undefined) return "no read";
   try {
@@ -537,3 +549,94 @@ export async function agreeRun(machine: Machine, doc: unknown, context: Context
   }
   return compared === undefined ? { ok: true, result, effects: first.effects } : { ok: true, result, effects: first.effects, reads: compared };
 }
+
+/** The result of `agreeTypes`: the agreement of a check of types and a traced evaluation (STATIC.TYPES-AGREE). */
+export type TypeAgreement =
+  | {
+      readonly ok: true;
+      /** `false` when the document has an issue, or a value breaks a position of an imprecise type. The rule then tells nothing. */
+      readonly checked: boolean;
+      /** The number of the values of the trace that the rule examined. */
+      readonly values: number;
+    }
+  | {
+      readonly ok: false;
+      /** `value`: a value is not in the type of its place. `argument`: it is not in the type that its position needs. `error`: a type error of the kernel. */
+      readonly clause: "value" | "argument" | "error";
+      /** The keys of the place, as texts. */
+      readonly place: readonly string[];
+      readonly reason: string;
+    };
+
+/** The options of `agreeTypes`: the options of `check`, and `guards`. */
+export interface AgreeTypesOptions extends CheckOptions {
+  /** `true`: the evaluation tests each boundary (PLAN.GUARD). The rule then holds for each context. The default is `false`. */
+  readonly guards?: boolean;
+}
+
+/** The type errors of the kernel, by the evaluator that gives them (STATIC.TYPES-AGREE). */
+const TYPE_ERRORS: Readonly<Record<string, string>> = {
+  "formula.op": "#NAME?",
+  "formula.if": "#VALUE!",
+  "formula.and": "#VALUE!",
+  "formula.or": "#VALUE!",
+};
+
+/**
+ * This function examines the agreement rule for types (STATIC.TYPES-AGREE, D148). A document with no issue evaluates
+ * with a trace. Each value of the trace is a member of the type of its place. A value of a precise type is also a member
+ * of the type that its position needs. No document with precise parts gives a type error of the kernel.
+ *
+ * A language imports this function for its own property tests, with `agree`. A failure tells that a signature, a type
+ * rule, a cover or a root type does not hold. A value that breaks a position of an imprecise type ends the promise, and
+ * the result then has `checked: false` (TYPE.GRADUAL).
+ *
+ * @param machine - The world and the code of the evaluators, with their type rules.
+ * @param doc - The document.
+ * @param context - The context. Its roots are members of the root types.
+ * @param options - The options of `check`, with the root types, and `guards`.
+ * @returns The agreement, or the first place that breaks it.
+ */
+export function agreeTypes(machine: Machine, doc: unknown, context: Context = makeContext(), options: AgreeTypesOptions = {}): TypeAgreement {
+  const typing = typeCheck(machine, doc, options);
+  if (typing.issues.length > 0) return { ok: true, checked: false, values: 0 };
+  const keyOf = (path: readonly unknown[]): string => JSON.stringify(path.map(String));
+  const places = new Map(typing.places.map((item) => [keyOf(item.place), item]));
+  const domains = machine.domains;
+  const guards = options.guards === true ? boundariesOf(typing, domains) : undefined;
+  const given = { ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }), ...(guards === undefined ? {} : { guards }) };
+  const stack: TraceNode[] = [evaluate(machine, doc, context, given).trace];
+  const nodes: TraceNode[] = [];
+  while (stack.length > 0) {
+    const node = stack.pop() as TraceNode;
+    nodes.push(node);
+    stack.push(...node.children);
+  }
+  // A value that breaks a position of an imprecise type leaves the promise of each later type (K28).
+  for (const node of nodes) {
+    const place = places.get(keyOf(node.path));
+    if (place?.expected === undefined || !node.result.ok || isPrecise(place.type, domains)) continue;
+    if (!member(node.result.value, place.expected, domains)) return { ok: true, checked: false, values: 0 };
+  }
+  // The walk goes from the end, thus a part comes before the kind that reads it, and a finding names the origin.
+  let values = 0;
+  for (const node of nodes.reverse()) {
+    const place = places.get(keyOf(node.path));
+    if (place === undefined) continue;
+    const at = node.path.map(String);
+    if (!node.result.ok) {
+      const parts = node.children.map((child) => places.get(keyOf(child.path)));
+      const decided = node.children.every((child) => child.result.ok) && parts.every((part) => part?.expected !== undefined && isPrecise(part.type, domains));
+      const code = TYPE_ERRORS[node.answer.evaluator ?? ""];
+      if (decided && node.result.error.code === code) return { ok: false, clause: "error", place: at, reason: `The document gives ${code}, but it checks with no issue.` };
+      continue;
+    }
+    const value = node.result.value;
+    values += 1;
+    if (!member(value, place.type, domains)) return { ok: false, clause: "value", place: at, reason: `The value ${valueText(value)} is not a member of ${typeText(place.type)}.` };
+    if (place.expected !== undefined && !member(value, place.expected, domains)) {
+      return { ok: false, clause: "argument", place: at, reason: `The value ${valueText(value)} is not a member of the needed type ${typeText(place.expected)}.` };
+    }
+  }
+  return { ok: true, checked: true, values };
+}

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

@@ -2,8 +2,8 @@ import { type Envelope, type Json, type Key, type TypeRef, isEnvelope, isKey, ty
 import { type PartSlot, type Split, partsOf, pathMatches, scopesOf } from "./parts.ts";
 import { answerOf, ask, type Answer } from "./ladder.ts";
 import type { CapsRule, Kind, KindFacts, Side } from "./world.ts";
-import type { Domain } from "./types.ts";
-import type { TypeRule } from "./typing.ts";
+import { type Domain, type ValueType, member, typeText } from "./types.ts";
+import type { Boundary, TypeRule } from "./typing.ts";
 import type { StaticRead } from "./facts.ts";
 import { type ErrorCode, type EvalError, type Result, Failure, fail, ok, placed, thrown, describe } from "./errors.ts";
 import {
@@ -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. */
@@ -904,6 +993,8 @@ export interface PlanRunOptions {
 export interface RunOptions extends PlanRunOptions {
   /** The type of a bare root value. */
   readonly declaredType?: string;
+  /** The boundaries that test their values (PLAN.GUARD). The default is none. */
+  readonly guards?: readonly Boundary[];
   /** The verb of `run`, for example `format`. The default is `eval` (VERB.PREPARE). */
   readonly verb?: string;
 }
@@ -934,6 +1025,8 @@ export interface EvaluateOptions {
   readonly perform?: Perform;
   /** A list that gets each read, in the order of the resolutions (READS.RECORD). */
   readonly reads?: Read[];
+  /** The boundaries that test their values (PLAN.GUARD). The default is none. */
+  readonly guards?: readonly Boundary[];
 }
 
 /** The options of a resolution without a record of hops, and with one. One object of each serves each call. */
@@ -1288,14 +1381,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;
@@ -1590,6 +1704,11 @@ export interface PrepareOptions {
    * the code without the fold. A plan without folds ignores this option.
    */
   readonly fixed?: { readonly names?: Readonly<Record<string, unknown>> };
+  /**
+   * The boundaries of the document, from `boundariesOf` (PLAN.GUARD, D149). A value that is not a member of the type of
+   * its boundary gives `#VALUE!` at that place. The default is none, and a plan then has no test.
+   */
+  readonly guards?: readonly Boundary[];
 }
 
 /** A compiled document. It evaluates many times, and it does the work of the ladder one time. */
@@ -1630,6 +1749,8 @@ interface Compiler {
   readonly fold: boolean;
   /** The fixed names and their values, or `undefined` when the plan has none (PLAN.FIXED). */
   readonly fixed: Readonly<Record<string, unknown>> | undefined;
+  /** The types of the boundaries by their place, or `undefined` when the plan has no guard (PLAN.GUARD). */
+  readonly guards: ReadonlyMap<string, ValueType> | undefined;
   /** The runtime of the folds of this compilation. The first fold makes it. */
   probe?: Probe;
 }
@@ -1771,11 +1892,12 @@ 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));
     }
-    const run = placedRun(inner, place, name);
+    const guard = guardOf(c, place);
+    const run = placedRun(guard === undefined ? inner : guardRun(inner, guard, c.machine.domains), place, name);
     return finish(c, meta, runnerCode(run, place, kindText), run);
   }
 
@@ -1785,8 +1907,9 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
   } catch (error) {
     return failingWith(c, meta, placed(thrown(error, `the evaluator ${name}`), place));
   }
+  const guard = guardOf(c, place);
   // Code that cannot fail needs no place and no catch, and it does not read the context of its grant (PLAN.TOTAL).
-  const done = finish(c, meta, TOTAL.has(inner) ? inner : placedCode(inner, place, name), undefined);
+  const done = finish(c, meta, guard !== undefined ? placedCode(guardCode(inner, guard, c.machine.domains), place, name) : TOTAL.has(inner) ? inner : placedCode(inner, place, name), undefined);
   if (frees === undefined || kind === undefined || !pureCode(c, envelope, kind, typePath, name, quick)) return done;
   const free = freeOf(doc, kind, split.parts, frees);
   if (free === undefined) return done;
@@ -2198,6 +2321,34 @@ function gated(rules: readonly CapsRule[], part: Compiled): Compiled {
  * This function gives the steps of a runner, with the place of each error and of each exception. The steps get the
  * context that its grant permits (CAP.NARROW-CODE).
  */
+/** This function gives the key of a place in the guards of a plan. */
+function guardKey(place: readonly Key[]): string {
+  return JSON.stringify(place.map(String));
+}
+
+/** This function gives the type of the boundary at a place, when the plan has one (PLAN.GUARD). */
+function guardOf(c: Compiler, place: readonly Key[]): ValueType | undefined {
+  return c.guards?.get(guardKey(place));
+}
+
+/** This function gives the result of a part of a boundary: a value that is not a member gives `#VALUE!` (PLAN.GUARD). */
+function guarded(result: Result, type: ValueType, domains: Readonly<Record<string, Domain>> | undefined): Result {
+  if (!result.ok || member(result.value, type, domains)) return result;
+  return fail("#VALUE!", `The value is not a member of ${typeText(type)}, the type of its boundary.`);
+}
+
+/** This function adds the test of a boundary to the code of a part. */
+function guardCode(inner: Code, type: ValueType, domains: Readonly<Record<string, Domain>> | undefined): Code {
+  return (ctx, rt) => guarded(inner(ctx, rt), type, domains);
+}
+
+/** This function adds the test of a boundary to the steps of a part. */
+function guardRun(inner: RunCode, type: ValueType, domains: Readonly<Record<string, Domain>> | undefined): RunCode {
+  return function* (ctx, rt) {
+    return guarded(yield* inner(ctx, rt), type, domains);
+  };
+}
+
 function placedRun(inner: RunCode, place: readonly Key[], name: string): RunCode {
   return function* (ctx, rt) {
     try {
@@ -2316,7 +2467,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 +2496,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,
@@ -2390,7 +2561,8 @@ export function prepare(machine: Machine, doc: unknown, options: PrepareOptions
   const traced = options.trace === true;
   const fold = !traced && options.fold !== false;
   const fixed = fold ? fixedNamesOf(options.fixed?.names) : undefined;
-  const c: Compiler = { machine, traced, maxDepth: machine.maxDepth ?? 1000, verb, noAnswer, fold, fixed };
+  const guards = options.guards === undefined || options.guards.length === 0 ? undefined : new Map(options.guards.map((each) => [guardKey(each.place), each.type]));
+  const c: Compiler = { machine, traced, maxDepth: machine.maxDepth ?? 1000, verb, noAnswer, fold, fixed, guards };
   let root: Compiled;
   try {
     root = compileNode(c, doc, [], options.declaredType, 0);
@@ -2513,6 +2685,7 @@ export function evaluate(machine: Machine, doc: unknown, context: Context = make
     trace: true,
     ...(declaredType === undefined ? {} : { declaredType }),
     ...(given.verb === undefined ? {} : { verb: given.verb }),
+    ...(given.guards === undefined ? {} : { guards: given.guards }),
   });
   const ctx = rootContext(machine, context);
   const s = new Session(machine, ctx.caps, false, true, given.perform, undefined, undefined, readingOf(given.reads, ctx));
@@ -2535,6 +2708,7 @@ export async function run(machine: Machine, doc: unknown, context: Context = mak
   const plan = prepare(machine, doc, {
     trace: true,
     ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }),
+    ...(options.guards === undefined ? {} : { guards: options.guards }),
     ...(options.verb === undefined ? {} : { verb: options.verb }),
   });
   const ctx = rootContext(machine, context);

package/src/formula.ts

@@ -420,6 +420,7 @@ function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule
     "formula.lit": { synth: (input) => valueType(input.doc.value) },
 
     "formula.ref": {
+      read: true,
       synth: (input, report) => {
         const path = input.doc.value;
         // An address gives a thing, not a value. The check gives #VALUE! for a path that is not a list.

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,
@@ -195,6 +197,7 @@ export {
   STD_EVALUATORS,
   STD_MACHINE,
   STD_RUNNERS,
+  ifRunner,
   STD_WALKERS,
   STD_WORLD,
   WORLD_SYNTAX,
@@ -225,6 +228,7 @@ export {
 } from "./context.ts";
 export {
   type CheckOptions,
+  type DocChange,
   type DocVisit,
   type Issue,
   type RefUse,
@@ -235,6 +239,7 @@ export {
   type WorldOptions,
   check,
   checkWorld,
+  mapDocs,
   mapRefs,
   refsOf,
   typeCheck,
@@ -267,6 +272,8 @@ export {
   type SyntaxCalls,
   type SyntaxConstructs,
   type SyntaxEnvelopes,
+  type SyntaxFinding,
+  type SyntaxFindingCode,
   type SyntaxFixity,
   type SyntaxForm,
   type SyntaxFormArgs,
@@ -279,12 +286,13 @@ export {
   type SyntaxRefs,
   MAX_SYNTAX_ISSUES,
   STD_SYNTAX,
+  checkSyntax,
   parse,
   print,
   syntaxFormat,
 } from "./syntax.ts";
 export { type Definitions, type ReferenceOptions, type ReferenceRunOptions, STD_DEFINITIONS, formulaDefinitions, reference, referenceRun } from "./reference.ts";
-export { type AgreeOptions, type AgreeRunOptions, type Agreement, type Tier, type TierInput, type TierResult, agree, agreeRun, sameValue } from "./agree.ts";
+export { type AgreeOptions, type AgreeRunOptions, type Agreement, type AgreeTypesOptions, type TypeAgreement, agreeTypes, type Tier, type TierInput, type TierResult, agree, agreeRun, sameValue } from "./agree.ts";
 export { type ConformOptions, type ConformProbe, type Finding, type Obligation, conforms } from "./conform.ts";
 export { sameResult } from "./same.ts";
 export { type PrintOptions, type ReadPrints, type ReadsCheck, type VerifyOptions, printReads, verifyReads } from "./reads.ts";
@@ -341,5 +349,5 @@ export {
 } from "./replay.ts";
 export { type GenerateOptions, type Random, generate, random, typesOf } from "./generate.ts";
 export { type Domain, type DomainCodec, type TypeIssue, type ValueType, STD_DOMAINS, fits, join, member, typeIssues, typeText } from "./types.ts";
-export { type Declared, type PartType, type RootTypes, type TypeInput, type TypeProblem, type TypeRule, type Typed, CAPS_TYPE } from "./typing.ts";
+export { type Boundary, type Declared, type PartType, type RootTypes, type TypeInput, type TypeProblem, type TypeRule, type Typed, CAPS_TYPE, boundariesOf } from "./typing.ts";
 export { type SampleOptions, type TypeReading, typeFromSamples, typeFromSchema } from "./providers.ts";

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));