@mark1russell7/coeval 0.23.0 → 0.24.1

package/src/schedule.ts

@@ -294,6 +294,8 @@ export function schedule(machine: Machine, options: ScheduleOptions = {}): Sched
   // The nodes that finished in a kept read, and if that read met a node in evaluation below it (D143).
   const keptNodes: string[] = [];
   let keptMet = false;
+  // The count of the visits at the start of the kept read. A node with a lower number started below the read.
+  let keptFrom = 0;
   let count = 0;
   let ahead = 0;
   // The node that stopped the evaluation of a walk, because the walk has no result for it.
@@ -370,8 +372,12 @@ export function schedule(machine: Machine, options: ScheduleOptions = {}): Sched
     const reader = stack[stack.length - 1];
     const known = epoch.values.get(id);
     if (known !== undefined) {
-      // A finished node of an open component is on a cycle with its reader too.
-      if (reader !== undefined && onOpen.has(id)) lower(reader, order.get(id) as number);
+      if (reader !== undefined && onOpen.has(id)) {
+        // The path from that component to a kept read has a read that no evaluation asked for (SCHED.KEPT-OPEN).
+        if (keptAt >= 0 && (order.get(id) as number) < keptFrom) keptMet = true;
+        // A finished node of an open component is on a cycle with its reader too.
+        else lower(reader, order.get(id) as number);
+      }
       return known;
     }
     if (busy.has(id)) {
@@ -592,9 +598,11 @@ export function schedule(machine: Machine, options: ScheduleOptions = {}): Sched
     keeping(read) {
       const outer = keptAt;
       const outerMet = keptMet;
+      const outerFrom = keptFrom;
       const from = keptNodes.length;
       keptAt = stack.length;
       keptMet = false;
+      keptFrom = count;
       try {
         return read();
       } finally {
@@ -609,6 +617,7 @@ export function schedule(machine: Machine, options: ScheduleOptions = {}): Sched
         }
         keptAt = outer;
         keptMet = outerMet;
+        keptFrom = outerFrom;
       }
     },
   });

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;
@@ -250,10 +258,14 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
       continue;
     }
     const { sees, later } = scopesOf(kind.scope, doc.value, split.parts);
+    // The rules of a grant are read one time for each kind, not for each part. A kind without such a rule gives no list (K238).
+    const grantRules = kind.caps !== undefined && kind.caps.some((rule) => rule.rule === "grant") ? kind.caps : undefined;
     for (let index = split.parts.length - 1; index >= 0; index -= 1) {
       const slot = split.parts[index] as PartSlot;
       const extra = sees[index] ?? [];
       const hidden = later[index] ?? [];
+      const grants = grantRules === undefined ? undefined : partGrants(grantRules, slot.path, doc.value);
+      const granted = grants !== undefined && grants.length > 0 ? grants : undefined;
       stack.push({
         value: slot.item,
         place: slot.path.length === 0 ? item.place : { up: item.place, keys: slot.path },
@@ -265,7 +277,14 @@ 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),
+        // A part with no grant keeps the list of partCaps, with no copy (K238).
+        caps:
+          item.caps === undefined || kind.caps === undefined
+            ? item.caps
+            : granted === undefined
+              ? partCaps(kind.caps, slot.path, item.caps)
+              : [...partCaps(kind.caps, slot.path, item.caps), ...granted],
+        handled: granted === undefined ? item.handled : [...(item.handled ?? []), ...granted],
         bound: extra,
         expect: slot.expect,
       });
@@ -361,6 +380,45 @@ export function mapRefs(world: World, doc: unknown, change: (use: RefUse) => unk
   return out;
 }
 
+/**
+ * The answer of the function of `mapDocs` for one document.
+ *
+ * - `undefined`: keep the document and go into its parts.
+ * - `"skip"`: keep the document and stop there.
+ * - `{ to }`: put `to` in the place of the document and stop there.
+ * - `{ to, into: true }`: put `to` in the place of the document, then go into the parts of the old document. Thus
+ *   `to` must keep the path of each such part.
+ */
+export type DocChange = undefined | "skip" | { readonly to: unknown; readonly into?: boolean };
+
+/**
+ * This function changes the documents of a document, from the root to the parts (STATIC.MAPDOCS). The function
+ * `change` reads only the original documents. It decides at each node, and it can stop at a node. The kinds of a
+ * position come from the world, thus this function names no kind. The document is not changed: the function gives a
+ * new document that shares each part without a change.
+ *
+ * @param world - The world of the kinds.
+ * @param doc - The document, as JSON.
+ * @param change - The function that gives the answer for each visit. See `DocChange`.
+ * @param options - The type of a bare root value, and the names that the host binds at the root.
+ * @returns The new document, or `doc` itself when no document changes.
+ */
+export function mapDocs(world: World, doc: unknown, change: (visit: DocVisit) => DocChange, options: WalkOptions = {}): unknown {
+  let out = doc;
+  walk(
+    world,
+    doc,
+    (visit) => {
+      const next = change(visit);
+      if (next === undefined || next === "skip") return next;
+      out = setAt(out, visit.at, next.to);
+      return next.into === true ? undefined : "skip";
+    },
+    options,
+  );
+  return out;
+}
+
 /** A problem that a check finds before a document runs. */
 export interface Issue {
   readonly code: ErrorCode;
@@ -770,6 +828,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" },
@@ -170,7 +192,8 @@ export const STD_WORLD: World = {
  * A literal in a place that takes a document gets its data envelope (K159, D65). Such a place is a part of `if`,
  * `list`, `seq` or `pure`, the value of `write`, or the whole text. The document after a header name is such a place
  * too. Thus `list(1, "a")` evaluates to `[1, "a"]`. The forms `add`, `multiply` and `greater` write an operator document that its operator
- * does not write, for example `add(5)` (K163).
+ * does not write, for example `add(5)` (K163). The field `with` of `handle` is a field of data, thus each clause is a
+ * record between braces in a list between brackets (D177).
  *
  * A host with more kinds spreads this profile and adds its forms to `calls.forms`. `STD_SYNTAX` stays the profile of
  * the formula kit.
@@ -201,6 +224,8 @@ export const WORLD_SYNTAX: SyntaxProfile = /* @__PURE__ */ Object.freeze({
       { name: "tree.named", kind: "tree.named", args: "named", fields: ["name", "in"] },
       { name: "tree.at", kind: "tree.at", args: "named", fields: ["attr", "args"] },
       { name: "tree.quote", kind: "tree.quote", args: "literal" },
+      // The clauses are data with documents in it, for example handle(with: [{op: "log", do: payload + 1}], body: log(2)) (D177).
+      { name: "handle", kind: "handle", args: "named", fields: ["with", "return", "body"], data: ["with"], wrap: ["return", "body"] },
       // An operator document with fewer terms than its operator takes, for example add(5) (K163, D65).
       { name: "add", kind: "add" },
       { name: "multiply", kind: "multiply" },
@@ -813,6 +838,7 @@ function leaderOnHost(n: LoopNode, key: string, rule: CircularRule & { readonly
 /**
  * This function gives an attribute of a node with circular attributes, or an attribute in an open fixed point (D113).
  * The memo and the marks of the node do not hold the attribute. An open fixed point does not use the cells of the host.
+ * With the cells of a host, only a circular attribute comes here outside a fixed point. A plain attribute takes its cell.
  */
 function circularRead(n: LoopNode, key: string): Result | undefined {
   const rule = circularRule(n.tree, key);
@@ -1199,7 +1225,8 @@ function treeThing(input: EvalInput, place: readonly Key[], build: TreeBuild, ou
           const text = attributeText(key, type, place);
           if (marks.has(key)) return busyAt(state, key);
           if (tree === undefined && up?.tree === undefined && !parts.some((item) => item.key === key)) return undefined;
-          if (circular || openPoint !== undefined) return circularRead(state, key);
+          // Outside a fixed point, a plain attribute of a node with a circular attribute also takes the cell of the host.
+          if (openPoint !== undefined || (circular && circularRule(tree, key) !== undefined)) return circularRead(state, key);
           marks.set(key, BUSY);
           demands.push({ cells: marks, key, text });
           let thrown: unknown = NOT_THROWN;
@@ -1493,6 +1520,39 @@ 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));
+}
+
+/**
+ * This function gives the runner of an `if` with its own truth (RUN.IF-TRUTH). A branch can wait for the host, thus a
+ * language with the function `truthy` of a profile does not need a copy of `if`. A missing test and a test without a
+ * truth give `#VALUE!`, a failed test gives its failure, and a missing branch gives `null`.
+ *
+ * @param truth - The function that gives the truth of a value, or `undefined` for a value without a truth.
+ * @returns The runner.
+ */
+export function ifRunner(truth: (value: unknown) => boolean | undefined): Runner {
+  return function* ({ parts }) {
+    const test = parts.find((part) => part.key === "test");
+    if (test === undefined) return fail("#VALUE!", "if needs a test.");
+    const chosen = yield* test.evaluate();
+    if (!chosen.ok) return chosen;
+    const held = truth(chosen.value);
+    if (held === undefined) return fail("#VALUE!", "The test of if must give a truth value.");
+    const branch = parts.find((part) => part.key === (held ? "then" : "else"));
+    return branch === undefined ? ok(null) : yield* branch.evaluate();
+  };
+}
+
 /**
  * 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,15 +1576,33 @@ 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();
   },
-  "control.if": function* ({ parts }) {
-    const test = parts.find((part) => part.key === "test");
-    if (test === undefined) return fail("#VALUE!", "if needs a test.");
-    const chosen = yield* test.evaluate();
-    if (!chosen.ok) return chosen;
-    if (typeof chosen.value !== "boolean") return fail("#VALUE!", "The test of if must give a truth value.");
-    const branch = parts.find((part) => part.key === (chosen.value === true ? "then" : "else"));
-    return branch === undefined ? ok(null) : yield* branch.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": /* @__PURE__ */ ifRunner((value) => (typeof value === "boolean" ? value : undefined)),
   "list.all": function* ({ parts }) {
     const all = yield* inOrder(parts);
     return "error" in all ? all.error : ok(all.values);