@mark1russell7/coeval 0.20.0 → 0.21.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.20.0",
+  "version": "0.21.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

@@ -214,6 +214,8 @@ interface Sample {
   readonly otherSplit: SplitOk;
   /** `true` for each part that a lazy rule covers. */
   readonly lazy: readonly boolean[];
+  /** `true` for each part that a rule `drives` covers: the runner can evaluate it with its code (D119). */
+  readonly driven: readonly boolean[];
   /** The names that the scope rules give each part. */
   readonly names: readonly (readonly string[])[];
 }
@@ -282,6 +284,8 @@ interface Contract {
   readonly declared: readonly Cap[];
   readonly pure: boolean;
   readonly lazy: readonly LazyRule[] | undefined;
+  /** The parts that the runner evaluates with its code, without a wait (RUN.DRIVES). */
+  readonly drives: readonly LazyRule[] | undefined;
   /** `true` when the facts describe the verb: they describe only `eval`. */
   readonly describes: boolean;
   /** `true` when the contract declares the effects of the verb: for `eval`, and for a verb in `verbEffects`. */
@@ -315,6 +319,8 @@ class Shot implements Runtime {
     readonly context: Context,
     /** The key of each part, for the reasons. */
     readonly keys: readonly string[],
+    /** `true` for each part that the runner can evaluate with its code, by the rules `drives` (D119). */
+    private readonly driven: readonly boolean[],
     private readonly perform: Perform | undefined,
     /** The resolutions of an earlier evaluation. Each resolution with the same path gets the same answer (C4). */
     private readonly replay: readonly Asked[] | undefined,
@@ -334,8 +340,8 @@ class Shot implements Runtime {
     this.calls.push({ part, via, context: ctx, later: this.afterwards });
     const key = this.keys[part] ?? String(part);
     if (via === "run" && !this.runner) this.problems.push(`The code of an evaluator starts the steps of the part ${key}. Only a runner waits.`);
-    if (via === "code" && this.runner && this.running) {
-      this.problems.push(`The runner evaluates the part ${key} with its code, and that code cannot wait. A runner evaluates a part with its steps (K65).`);
+    if (via === "code" && this.runner && this.running && this.driven[part] !== true) {
+      this.problems.push(`The runner evaluates the part ${key} with its code, and that code cannot wait. A runner evaluates a part with its steps, or its contract declares the part in drives (D119).`);
     }
     return this.scenario.results[part] ?? NO_RESULT;
   }
@@ -498,13 +504,15 @@ function typesNaming(world: World, name: string, verb: string): readonly TypeRef
 function contractOf(env: Env, kind: Kind, typePath: readonly Key[], caps: readonly Cap[] | undefined): Contract {
   const facts = env.machine.facts?.(typePath, env.name);
   // A verb without a declaration keeps the effects of eval for the capabilities of the probes, as before D49.
-  const own = effectsOfVerb(kind, env.verb);
+  // For eval, the effects of the answer of the hook win over the contract, as in check (D118).
+  const own = (env.verb === "eval" ? facts?.effects : undefined) ?? effectsOfVerb(kind, env.verb);
   const effects = own ?? kind.effects;
   const declared: readonly Cap[] = effects === undefined ? [] : effects === "type" ? [typePath] : effects;
   return {
     declared,
     pure: (facts?.pure ?? kind.pure) === true,
     lazy: facts?.lazy ?? kind.lazy,
+    drives: env.verb === "eval" ? (facts?.drives ?? kind.drives) : undefined,
     describes: env.verb === "eval",
     declares: own !== undefined,
     caps: caps ?? [...declared, "probe"],
@@ -637,6 +645,7 @@ function samplesOf(type: TypeRef, typePath: readonly Key[], kind: Kind, contract
       other: { type, value: otherValue },
       otherSplit,
       lazy: split.parts.map((_slot, index) => contract.lazy?.some((rule) => covers(rule, split.parts, index)) === true),
+      driven: split.parts.map((_slot, index) => contract.drives?.some((rule) => covers(rule, split.parts, index)) === true),
       names: scopesOf(kind.scope, value, split.parts).sees,
     });
   }
@@ -769,7 +778,7 @@ function instanceOf(env: Env, under: Under, doc: Envelope, split: SplitOk, sampl
 /** This function evaluates a probe document one time in a new shot. */
 function shoot(env: Env, instance: Instance, sample: Sample, scenario: Scenario, more: { readonly context?: Context; readonly replay?: readonly Asked[] } = {}): Shot {
   const context = more.context ?? rootContext(env.machine, makeContext(env.names, scenario.caps));
-  const shot = new Shot(env.machine, env.runner, scenario, context, sample.split.parts.map((slot) => slot.key), env.perform, more.replay);
+  const shot = new Shot(env.machine, env.runner, scenario, context, sample.split.parts.map((slot) => slot.key), sample.driven, env.perform, more.replay);
   instance(shot);
   return shot;
 }

package/src/deref.ts

@@ -2,6 +2,7 @@ import { type Envelope, type Json, type JsonRecord, type Key, type TypeRef, fiel
 import { type Kind, type World, entriesAsJson, lookupKind } from "./world.ts";
 import { answerOf } from "./ladder.ts";
 import type { ErrorCode } from "./errors.ts";
+import type { ValueType } from "./types.ts";
 
 /**
  * The brand of a host thing: an object of the host that answers the steps of a path itself. The brand is a
@@ -169,8 +170,37 @@ export interface WalkInput {
   readonly visit?: (key: Key, thing: Thing) => void;
 }
 
-/** A walker: the code of the verb `step` of a kind of step documents. */
-export type Walker = (input: WalkInput) => WalkResult;
+/** The input of the type rule of a walker: the data of the step document, and the type of the thing before the step. */
+export interface WalkTypeInput {
+  /** The value of the step document. A step document with parts has no type rule, thus this value holds no part. */
+  readonly data: Json;
+  /** The type of the thing that the path reached before this step. */
+  readonly here: ValueType;
+}
+
+/**
+ * A walker: the code of the verb `step` of a kind of step documents. A plain function is a walker.
+ *
+ * A walker can hold a type rule in its field `type` (TYPE.WALKER, D121). The rule gives the type of each thing that
+ * the walker reaches from a thing of the type `here`. It must be sound, as the rule of an evaluator. A walker
+ * without a rule reaches the type `unknown`. A host gives the rule with `Object.assign(walker, { type })`.
+ */
+export interface Walker {
+  /**
+   * This function answers the step document on the thing that the path reached.
+   *
+   * @param input - The data of the step document, the thing before the step and the ladder.
+   * @returns What the step reached, or the reason of a failure.
+   */
+  (input: WalkInput): WalkResult;
+  /**
+   * This optional function gives the type of what the walker reaches.
+   *
+   * @param input - The data of the step document and the type before the step.
+   * @returns The type of each thing that the walker reaches.
+   */
+  readonly type?: (input: WalkTypeInput) => ValueType;
+}
 
 /**
  * What a resolution needs: the world, and the code of the `deref` evaluators and of the walkers.

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)) if (rule(caps, kind)) out.push({ kind, visit: v });
+      for (const kind of declaredEffects(v, "eval", machine)) if (rule(caps, kind)) out.push({ kind, visit: v });
       return undefined;
     },
     { caps: options.caps ?? EACH, ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }) },
@@ -65,7 +65,9 @@ function reaching(machine: Machine, doc: unknown, options: EffectsOptions): read
  *
  * The result covers each effect that an evaluation or a run gives the host (CAP.EFFECTS-SOUND). A procedure value keeps
  * the capabilities of the document that made it, thus the effects of its body count at the body (CAP.LATENT). The
- * contract describes the code of its kind. The code of an own entry for another evaluator is outside the result.
+ * contract describes the code of its kind. The contract does not describe the code of an own entry for another
+ * evaluator. The answer of the hook `facts` for that code gives its effects (CAP.OWN-EFFECTS, D118). Without an
+ * answer, its effects are outside the result.
  *
  * @param machine - The world and its contracts, and the hook `permits`.
  * @param doc - The document, as JSON.

package/src/evaluate.ts

@@ -1792,6 +1792,8 @@ function pureCode(c: Compiler, envelope: Envelope | undefined, kind: Kind, typeP
   } catch {
     return false;
   }
+  // The effects of the answer of the hook make the code not pure, also for an own entry (D118).
+  if (answer?.effects !== undefined && answer.effects.length > 0) return false;
   // The contract of the kind describes the code of its own name, or an own entry that names the same code (D24).
   const described = c.verb === "eval" && (envelope === undefined || quick?.rung !== "own" || name === answerOf(c.machine.world, undefined, kind, c.verb)?.name);
   const pure = described ? (answer?.pure ?? kind.pure) : answer?.pure;

package/src/facts.ts

@@ -4,7 +4,7 @@ import { answerOf } from "./ladder.ts";
 import { pathMatches, splitParts } from "./parts.ts";
 import { type Root, ROOTS, isRef } from "./deref.ts";
 import type { Machine } from "./evaluate.ts";
-import { type DocVisit, type WalkOptions, declaredEffects, equationsOf, walk } from "./static.ts";
+import { type DocVisit, type WalkOptions, declaredEffects, effectKeys, equationsOf, walk } from "./static.ts";
 
 /**
  * One read of a document: a free reference, with its marks (FACTS.READS). A plan resolves the path of the reference
@@ -272,7 +272,8 @@ export function factsOf(machine: Machine, doc: unknown, options: FactsOptions =
         }
         // check and effectsOf read the declared effects with the same function (D27). The verb of the facts selects the
         // declaration: effects for eval, and the entry of verbEffects for another verb (D49, D111).
-        const declared = declaredEffects(v, verb);
+        // The answer of the hook for the code of eval wins over the contract, also for an own entry (D118).
+        const declared = verb === "eval" && answer?.effects !== undefined ? effectKeys(v, answer.effects) : declaredEffects(v, verb);
         // The field side gives the side of eval. For another verb, a declared effect needs a runner, as in check, thus
         // the run side (FACTS.VERB-SIDE).
         const runs = verb === "eval" ? kind.side === "run" : declared.length > 0;

package/src/formula.ts

@@ -1,6 +1,7 @@
-import { type Json, type Key, docEquals, isKey, isRecord } from "./doc.ts";
+import { type Json, type Key, docEquals, isKey, isRecord, typeName } from "./doc.ts";
+import { partsOf as docParts } from "./parts.ts";
 import type { Kind, KindFacts, LazyRule, WorldEntry } from "./world.ts";
-import { type CompiledPath, type Context, type Resolution, compilePath, valueOfThing } from "./deref.ts";
+import { type CompiledPath, type Context, type Resolution, compilePath, valueOfThing, walkerOf } from "./deref.ts";
 import { type EvalError, type Failed, type Result, Failure, fail, ok, thrown } from "./errors.ts";
 import { type Code, type CompileInput, type CompiledEvaluator, type CompiledPart, type Evaluator, type Machine, type Runtime, resolveCompiled, totalCode } from "./evaluate.ts";
 import { type MachinePart, mergeMachines } from "./merge.ts";
@@ -278,6 +279,29 @@ function paramsOf(value: unknown): readonly string[] {
   return Array.isArray(params) ? params.filter((param): param is string => typeof param === "string") : [];
 }
 
+/** This function gives the text of a step of a path: a key, or the kind of a step document in parentheses. */
+function stepText(step: unknown): string {
+  if (isKey(step)) return String(step);
+  return isRecord(step) ? `(${typeName(step["type"] as Parameters<typeof typeName>[0])})` : "(step)";
+}
+
+/**
+ * This function gives the type of what a step document reaches (TYPE.WALKER, D121). The type rule of its walker gives
+ * it. A step document with parts gets its data in the run, thus its type is `unknown`, as for a walker without a rule.
+ *
+ * @param input - The input of the rule of the reference.
+ * @param step - The step document.
+ * @param here - The type before the step.
+ * @returns The type of what the step reaches.
+ */
+function walkType(input: TypeInput, step: unknown, here: ValueType): ValueType {
+  const rule = walkerOf(input.machine, step)?.type;
+  if (rule === undefined) return "unknown";
+  const read = docParts(input.machine.world, step);
+  if (!read.ok || !read.split.ok || read.split.parts.length > 0) return "unknown";
+  return input.contract(rule({ data: read.doc.value, here }), `type of the step ${typeName(read.doc.type)}`);
+}
+
 /**
  * This function makes the type rules of the formula kit for one profile (TYPE.SYNTH, D25). Each evaluator of the kit
  * holds its rule. The rules read the rules of the profile that change a type: `truthy`, `truthType`, `logic`,
@@ -395,12 +419,14 @@ function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule
           if (isUnknown(type, domains) || (!plain && holdsEnvelope(type, domains))) return "unknown";
           if (index >= path.length) return type;
           const step = path[index];
-          // A step document gives what its walker reaches. It has no type yet.
-          if (!isKey(step)) return "unknown";
+          if (!isKey(step)) {
+            type = walkType(input, step, type);
+            continue;
+          }
           const next = stepType(type, step, domains, input.contract);
           if ("missing" in next) {
             const fields = next.missing.length === 0 ? "" : ` Its fields are ${listText(next.missing)}.`;
-            report({ reason: `The value at ${path.slice(0, index).map(String).join(".")} has no field ${String(step)}.${fields}` });
+            report({ reason: `The value at ${path.slice(0, index).map(stepText).join(".")} has no field ${String(step)}.${fields}` });
             return "unknown";
           }
           type = next.type;

package/src/index.ts

@@ -40,6 +40,8 @@ export {
   type CapsRule,
   type CircularDeclaration,
   type CircularRule,
+  type CollectDeclaration,
+  type CollectRule,
   type Kind,
   type KindFacts,
   type LazyRule,
@@ -56,6 +58,7 @@ export {
   type WorldEntry,
   CIRCULAR_LIMIT,
   circularOf,
+  collectOf,
   effectsOfVerb,
   entriesAsJson,
   equationType,
@@ -92,6 +95,7 @@ export {
   kindNamed,
   kindOf,
 } from "./ladder.ts";
+export { type StepKey, type StepLadder, type StepNeed, type StepReason, type StepRefusal, type StepWalk, checkStep, isStep, stepLadder, stepOf, stepRank } from "./steps.ts";
 export {
   type Cap,
   type Context,
@@ -107,6 +111,7 @@ export {
   type Thing,
   type WalkInput,
   type WalkResult,
+  type WalkTypeInput,
   type Walker,
   ROOTS,
   THING,

package/src/instances.ts

@@ -1,5 +1,5 @@
 import { type Json, type Key, field, isKey, isRecord, typeName } from "./doc.ts";
-import { type Kind, equationType } from "./world.ts";
+import { type CollectRule, type Kind, collectOf, equationType } from "./world.ts";
 import { ask } from "./ladder.ts";
 import { isRef, walkerOf } from "./deref.ts";
 import type { Machine } from "./evaluate.ts";
@@ -460,9 +460,58 @@ function rungReads(b: Builder, id: string): void {
     termReads(b, termRefs(b, node.kind, `tree.attributes.${key}.fold.combine`, fold.combine), node, undefined, combined ? later : { ...later, lazy: true });
     return;
   }
+  const collect = declared?.collect === undefined ? undefined : collectOf(declared.collect);
+  if (collect?.ok === true) {
+    collectReads(b, node, key, collect, later);
+    return;
+  }
   if (declared?.default !== undefined) termReads(b, termRefs(b, node.kind, `tree.attributes.${key}.default`, declared.default), node, undefined, later);
 }
 
+/** This function gives the list children of a node before the run. A node without a rung for it has no children. */
+function childrenOf(b: Builder, at: NodeInfo): Value {
+  const part = at.parts.get("children");
+  if (part !== undefined) return valueOf(part);
+  const tree = at.kind.tree;
+  if (hasOwnEntry(tree?.equations, "children") || hasOwnEntry(tree?.attributes, "children")) return "unknown";
+  if (at.up === undefined) return downNames(b.machine.world).has("children") ? "unknown" : "data";
+  return at.up !== null && hasOwnEntry(at.up.kind.tree?.down, "children") ? "unknown" : "data";
+}
+
+/**
+ * This function adds the reads of a collection (TREE.COLLECT, D122), in the order of the run. Each node of the subtree
+ * gives the reads of its contribution and of its list `children`. A list that only the run knows gives an edge with an
+ * unknown source. The registry of names reads only the lists `children`.
+ */
+function collectReads(b: Builder, node: NodeInfo, key: string, rule: CollectRule & { readonly ok: true }, later: Reader): void {
+  if (!rule.names) termReads(b, termRefs(b, node.kind, `tree.attributes.${key}.collect.unit`, rule.unit), node, undefined, later);
+  let combined = false;
+  const done = new Set<NodeInfo>();
+  const stack: NodeInfo[] = [node];
+  while (stack.length > 0) {
+    const at = stack.pop() as NodeInfo;
+    if (done.has(at)) continue;
+    done.add(at);
+    const term = rule.names || !hasOwnEntry(at.kind.tree?.contributes, key) ? undefined : at.kind.tree?.contributes?.[key];
+    if (term !== undefined) {
+      termReads(b, termRefs(b, at.kind, `tree.contributes.${key}`, term), at, undefined, later);
+      combined = true;
+    }
+    edge(b, vertexOf(b, at, "children"), later);
+    const children = childrenOf(b, at);
+    if (children === "unknown") edge(b, undefined, later);
+    else if (typeof children === "object" && "list" in children) {
+      const items = itemsOf(children.list);
+      for (let index = items.length - 1; index >= 0; index -= 1) {
+        const child = items[index]?.node;
+        if (child !== undefined && child.up === at) stack.push(child);
+      }
+    }
+  }
+  // The combine evaluates once for each contribution, thus without a known contribution its reads are lazy.
+  if (!rule.names) termReads(b, termRefs(b, node.kind, `tree.attributes.${key}.collect.combine`, rule.combine), node, undefined, combined ? later : { ...later, lazy: true });
+}
+
 /** The vertices and the edges of a document, and the roots of the demand of the run: the own parts of each tree root. */
 interface Built {
   readonly b: Builder;

package/src/parts.ts

@@ -1,5 +1,5 @@
 import { type Envelope, type Json, type Key, docEquals, isEnvelope, isRecord, typeName, typePath } from "./doc.ts";
-import { type Kind, type NamesSource, type ScopeRule, type Shape, type World, lookupKind } from "./world.ts";
+import { type Kind, type LazyRule, type NamesSource, type ScopeRule, type Shape, type World, lookupKind } from "./world.ts";
 import type { ValueType } from "./types.ts";
 
 /** One part of a value: its place in the value, the JSON of the part, and the type that its position declares. */
@@ -269,6 +269,35 @@ export function pathMatches(path: readonly Key[], pattern: readonly Key[]): bool
   return true;
 }
 
+/**
+ * This function tells if a list of rules in the form of the lazy rules covers a part (D24, D119). A rule without
+ * `in` covers each part. With `after: n`, a rule covers only the parts after the first `n` parts that it matches.
+ *
+ * @param rules - The rules.
+ * @param shape - The shape of the parts of the parent.
+ * @param value - The value of the parent.
+ * @param slot - The path of the part in the value.
+ * @returns `true` when a rule covers the part.
+ */
+export function rulesCover(rules: readonly LazyRule[], shape: Shape | undefined, value: Json, slot: readonly Key[]): boolean {
+  for (const rule of rules) {
+    if (rule.in !== undefined && !rule.in.some((pattern) => pathMatches(slot, pattern))) continue;
+    const after = rule.after ?? 0;
+    if (after <= 0) return true;
+    const split = splitParts(shape, value);
+    let count = 0;
+    for (const part of split.ok ? split.parts : []) {
+      if (rule.in !== undefined && !rule.in.some((pattern) => pathMatches(part.path, pattern))) continue;
+      if (part.path.length === slot.length && pathMatches(part.path, slot)) {
+        if (count >= after) return true;
+        break;
+      }
+      count += 1;
+    }
+  }
+  return false;
+}
+
 function valueAt(value: unknown, path: readonly Key[]): unknown {
   let here: unknown = value;
   for (const key of path) {