@mark1russell7/coeval 0.20.1 → 0.21.0

package/src/providers.ts

@@ -33,13 +33,106 @@ const NOTES: ReadonlySet<string> = /* @__PURE__ */ new Set([
 ]);
 
 /** The keywords that the reading reads. Each other keyword gives an issue and tests nothing. */
-const READ: ReadonlySet<string> = /* @__PURE__ */ new Set(["type", "properties", "required", "additionalProperties", "items", "enum", "const", "anyOf", "oneOf"]);
+const READ: ReadonlySet<string> = /* @__PURE__ */ new Set([
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "enum",
+  "const",
+  "anyOf",
+  "oneOf",
+  "allOf",
+  "$ref",
+]);
+
+/**
+ * The keywords that can permit more values than the other keywords permit. A dynamic reference can reach a schema
+ * outside this schema, and `nullable` of OpenAPI 3.0 permits `null`. Thus a schema with one of them reads as `unknown`.
+ */
+const WIDENING: ReadonlySet<string> = /* @__PURE__ */ new Set(["$dynamicRef", "$recursiveRef", "nullable"]);
+
+/** The keywords of an object without the keyword `type`. They test only the values that are records. */
+const OBJECT_KEYS: readonly string[] = ["properties", "required", "additionalProperties"];
+
+/** The form of a local reference: a definition in `$defs` or `definitions` of the root schema. */
+const LOCAL_REF = /^#\/(\$defs|definitions)\/([^/]*)$/;
+
+/** The most pairs of members that the meet of two unions builds. A larger meet keeps the first type, which is sound. */
+const MAX_MEET_PAIRS = 64;
+
+/** The keywords of one JSON type without the keyword `type`: they test only the records or only the lists. */
+interface Condition {
+  readonly on: "record" | "list";
+  readonly type: ValueType;
+  readonly at: readonly Key[];
+}
+
+/** A record type of the reading. */
+type RecordType = Extract<ValueType, { readonly record: unknown }>;
+
+/** This function tells if a field of a record type can be absent. */
+function isOptional(type: RecordType, key: string): boolean {
+  return type.optional?.includes(key) === true;
+}
 
 /**
- * The keywords that can permit more values than the other keywords permit. Older drafts ignore each keyword beside
- * `$ref`, and `nullable` of OpenAPI 3.0 permits `null`. Thus a schema with one of them reads as `unknown`.
+ * This function gives the meet of two types of a reading: a type that holds each value of both types. A schema is
+ * the conjunction of its keywords, thus its type is the meet of their types. The meet is exact for the forms that a
+ * reading makes: base types, lists, records, unions and `one`. A meet of two different forms is `never`.
  */
-const WIDENING: ReadonlySet<string> = /* @__PURE__ */ new Set(["$ref", "$dynamicRef", "$recursiveRef", "nullable"]);
+function meet(a: ValueType, b: ValueType, depth: number): ValueType {
+  if (depth > MAX_SCHEMA_DEPTH) return a;
+  if (isUnknown(a, undefined)) return b;
+  if (isUnknown(b, undefined)) return a;
+  if (a === "never" || b === "never") return "never";
+  if (typeof a !== "string" && "one" in a) return { one: a.one.filter((value) => member(value, b)) };
+  if (typeof b !== "string" && "one" in b) return { one: b.one.filter((value) => member(value, a)) };
+  if (typeof b !== "string" && "union" in b && !(typeof a !== "string" && "union" in a)) return meet(b, a, depth);
+  if (typeof a !== "string" && "union" in a) {
+    const others = typeof b !== "string" && "union" in b ? b.union : [b];
+    if (a.union.length * others.length > MAX_MEET_PAIRS) return a;
+    return unionOf(a.union.flatMap((item) => others.map((other) => meet(item, other, depth + 1))));
+  }
+  if (typeof a === "string" || typeof b === "string") return a === b ? a : "never";
+  if ("list" in a && "list" in b) return { list: meet(a.list, b.list, depth + 1) };
+  if ("record" in a && "record" in b) return meetRecords(a, b, depth + 1);
+  // A list and a record have no common value. Each other pair keeps the first type, which is sound.
+  return ("list" in a || "record" in a) && ("list" in b || "record" in b) ? "never" : a;
+}
+
+/**
+ * This function gives the meet of two record types. A field of both records gets the meet of its types, and it is
+ * optional only when both records permit its absence. A closed record has no other field, thus a field of only the
+ * other record is absent. When the other record needs that field, no value fits both records.
+ */
+function meetRecords(a: RecordType, b: RecordType, depth: number): ValueType {
+  const fields: Record<string, ValueType> = {};
+  const optional: string[] = [];
+  const keys = [...Object.keys(a.record), ...Object.keys(b.record).filter((key) => !Object.hasOwn(a.record, key))];
+  for (const key of keys) {
+    const inA = Object.hasOwn(a.record, key);
+    const inB = Object.hasOwn(b.record, key);
+    if ((!inA && a.closed === true) || (!inB && b.closed === true)) {
+      if ((inA && !isOptional(a, key)) || (inB && !isOptional(b, key))) return "never";
+      continue;
+    }
+    const type = inA && inB ? meet(a.record[key] as ValueType, b.record[key] as ValueType, depth) : ((inA ? a.record[key] : b.record[key]) as ValueType);
+    setOwn(fields, key, type);
+    if ((!inA || isOptional(a, key)) && (!inB || isOptional(b, key))) optional.push(key);
+  }
+  const closed = a.closed === true || b.closed === true;
+  return { record: fields, ...(optional.length === 0 ? {} : { optional }), ...(closed ? { closed: true } : {}) };
+}
+
+/** This function applies a condition to a type: each member of the JSON type of the condition meets its type. */
+function narrow(type: ValueType, condition: Condition): ValueType {
+  if (typeof type === "string") return type;
+  if ("union" in type) return unionOf(type.union.map((item) => narrow(item, condition)));
+  if ("one" in type) return { one: type.one.filter((value) => !(condition.on === "list" ? Array.isArray(value) : isRecord(value)) || member(value, condition.type)) };
+  return condition.on in type ? meet(type, condition.type, 0) : type;
+}
 
 /** The base type of each name of the keyword `type`. */
 const BASES: Readonly<Record<string, ValueType>> = { null: "null", boolean: "bool", number: "number", integer: "number", string: "text" };
@@ -55,25 +148,55 @@ function unionOf(types: readonly ValueType[]): ValueType {
   return types.reduce<ValueType>((all, type) => join(all, type), "never");
 }
 
-/** The state of one reading of a schema: the issues that it found. */
+/** The state of one reading of a schema: the root, the issues and the definitions that it read. */
 class SchemaReader {
   readonly issues: TypeIssue[] = [];
+  /** The type of each definition that a reference reached. Each reading of a definition is sound, thus the first stays. */
+  readonly defs = new Map<string, ValueType>();
+  /** The definitions that the reading has not finished. A reference to one of them is a cycle. */
+  readonly open = new Set<string>();
+  /** The number of schemas with an own `$id` around the current schema. A reference inside them has another base. */
+  inner = 0;
+
+  constructor(readonly root: unknown) {}
 
   issue(at: readonly Key[], reason: string): void {
     this.issues.push({ at, reason });
   }
 
-  /** This method reads one schema. */
+  /** This method reads one schema: the meet of the types of its keywords, then its conditions. */
   read(schema: unknown, at: readonly Key[], depth: number): ValueType {
+    const types: ValueType[] = [];
+    const conditions: Condition[] = [];
+    this.parts(schema, at, depth, types, conditions);
+    let type = types.reduce<ValueType>((all, item) => meet(all, item, 0), "unknown");
+    for (const condition of conditions) {
+      if (isUnknown(type, undefined)) {
+        this.issue(condition.at, "The schema has no keyword type. Thus a value of each JSON type fits it, and the type reads it as unknown.");
+        break;
+      }
+      type = narrow(type, condition);
+    }
+    return type;
+  }
+
+  /**
+   * This method adds the type of each keyword of a schema to `types`, and its conditions to `conditions`. Each type
+   * holds each value that the schema accepts. The parts of `allOf` add their keywords too.
+   */
+  parts(schema: unknown, at: readonly Key[], depth: number, types: ValueType[], conditions: Condition[]): void {
     if (depth > MAX_SCHEMA_DEPTH) {
       this.issue(at, `The schema is deeper than ${MAX_SCHEMA_DEPTH} levels. The type reads it as unknown.`);
-      return "unknown";
+      return;
+    }
+    if (schema === true) return;
+    if (schema === false) {
+      types.push("never");
+      return;
     }
-    if (schema === true) return "unknown";
-    if (schema === false) return "never";
     if (!isRecord(schema)) {
       this.issue(at, "A schema is a record or a truth value. The type reads this value as unknown.");
-      return "unknown";
+      return;
     }
     let widens = false;
     for (const key of Object.keys(schema)) {
@@ -85,31 +208,85 @@ class SchemaReader {
         this.issue([...at, key], `The type does not read the keyword ${key}. It does not test what the keyword tests.`);
       }
     }
-    if (widens) return "unknown";
-    // A schema is the conjunction of its keywords. The reading keeps one of them, and each one alone holds each value.
-    const sides: { readonly key: string; readonly type: ValueType }[] = [];
-    if (Object.hasOwn(schema, "type")) sides.push({ key: "type", type: this.byType(schema, at, depth) });
-    else if (["properties", "required", "additionalProperties", "items"].some((key) => Object.hasOwn(schema, key)) && !["enum", "const", "anyOf", "oneOf"].some((key) => Object.hasOwn(schema, key))) {
-      this.issue(at, "The schema has no keyword type. Thus a value of each JSON type fits it, and the type reads it as unknown.");
+    if (widens) return;
+    const nested = schema !== this.root && Object.hasOwn(schema, "$id");
+    if (nested) this.inner += 1;
+    try {
+      this.keywords(schema, at, depth, types, conditions);
+    } finally {
+      if (nested) this.inner -= 1;
+    }
+  }
+
+  /** This method reads the keywords of a schema that does not permit more values (WIDENING). */
+  keywords(schema: Readonly<Record<string, unknown>>, at: readonly Key[], depth: number, types: ValueType[], conditions: Condition[]): void {
+    if (Object.hasOwn(schema, "$ref")) {
+      // Older drafts ignore each keyword beside $ref. The target alone holds each value in each draft.
+      for (const key of Object.keys(schema)) if (READ.has(key) && key !== "$ref") this.issue([...at, key], `The type reads only the target of $ref. It does not test the keyword ${key} beside it.`);
+      const type = this.target(schema["$ref"], [...at, "$ref"], depth);
+      if (type !== undefined) types.push(type);
+      return;
+    }
+    if (Object.hasOwn(schema, "type")) types.push(this.byType(schema, at, depth));
+    else {
+      if (OBJECT_KEYS.some((key) => Object.hasOwn(schema, key))) conditions.push({ on: "record", type: this.object(schema, at, depth), at });
+      if (Object.hasOwn(schema, "items")) conditions.push({ on: "list", type: this.array(schema, at, depth), at });
     }
-    for (const key of ["anyOf", "oneOf"]) {
+    for (const key of ["anyOf", "oneOf", "allOf"]) {
       if (!Object.hasOwn(schema, key)) continue;
       const items = schema[key];
       if (!Array.isArray(items)) {
         this.issue([...at, key], `The value of ${key} is a list of schemas.`);
         continue;
       }
+      // Each part of allOf holds each value of the schema, thus its keywords join the keywords of the schema.
+      if (key === "allOf") for (const [index, item] of items.entries()) this.parts(item, [...at, key, index], depth + 1, types, conditions);
       // A union holds each value of oneOf too. It does not test that only one schema fits.
-      sides.push({ key, type: unionOf(items.map((item, index) => this.read(item, [...at, key, index], depth + 1))) });
+      else types.push(unionOf(items.map((item, index) => this.read(item, [...at, key, index], depth + 1))));
     }
-    // A finite set of values meets each other keyword exactly: the type keeps each value that each side holds.
     const values = this.values(schema, at);
-    if (values !== undefined) return { one: values.filter((value) => sides.every((side) => member(value, side.type))) };
-    const known = sides.filter((side) => !isUnknown(side.type, undefined));
-    const kept = known[0];
-    if (kept === undefined) return "unknown";
-    for (const side of known.slice(1)) this.issue([...at, side.key], `The type reads the keyword ${kept.key}, and not the keyword ${side.key}.`);
-    return kept.type;
+    if (values !== undefined) types.push({ one: values });
+  }
+
+  /** This method reads the target of a reference: a definition of the root schema, or `undefined` for each value. */
+  target(ref: unknown, at: readonly Key[], depth: number): ValueType | undefined {
+    const match = typeof ref === "string" ? LOCAL_REF.exec(ref) : null;
+    let name: string | undefined;
+    try {
+      // The name is a step of a JSON Pointer in a URI fragment.
+      name = match === null ? undefined : decodeURIComponent(match[2] ?? "").replace(/~1/g, "/").replace(/~0/g, "~");
+    } catch {
+      name = undefined;
+    }
+    if (match === null || name === undefined) {
+      this.issue(at, "The type reads only a $ref to #/$defs/<name> or #/definitions/<name> of the same schema. Thus it reads the schema as unknown.");
+      return undefined;
+    }
+    if (this.inner > 0) {
+      this.issue(at, "A $ref inside a schema with its own $id has another base. Thus the type reads the schema as unknown.");
+      return undefined;
+    }
+    const group = match[1] as string;
+    const defs = isRecord(this.root) ? this.root[group] : undefined;
+    if (!isRecord(defs) || !Object.hasOwn(defs, name)) {
+      this.issue(at, `The schema has no definition ${String(ref)}. Thus the type reads the reference as unknown.`);
+      return undefined;
+    }
+    const key = `${group}/${name}`;
+    const known = this.defs.get(key);
+    if (known !== undefined) return known;
+    if (this.open.has(key)) {
+      this.issue(at, `The reference ${String(ref)} is in a cycle. The type reads this reference as unknown.`);
+      return undefined;
+    }
+    this.open.add(key);
+    try {
+      const type = this.read(defs[name], [group, name], depth + 1);
+      this.defs.set(key, type);
+      return type;
+    } finally {
+      this.open.delete(key);
+    }
   }
 
   /** This method reads `enum` and `const`: the values that the schema permits, or `undefined` without them. */
@@ -196,17 +373,20 @@ class SchemaReader {
  * - `properties`, `required` and `additionalProperties` give a record. `false` closes it, and a property that is not
  *   in `required` is optional.
  * - `items` gives a list. `enum` and `const` give `one`. `anyOf` and `oneOf` give a union.
+ * - `$ref` reads a definition in `$defs` or `definitions` of the same schema (TYPE.SCHEMA-REF). Another reference, a
+ *   missing definition and a reference in a cycle read as `unknown`.
+ * - `allOf` and the other keywords of a schema give the meet of their types (TYPE.SCHEMA-ALLOF). Records merge their
+ *   fields, and a closed part keeps the merge closed.
  *
  * The type holds each value that the schema accepts. Each keyword that the function does not read tests nothing, as
- * `unknown`, and the issues name it. Examples are `minimum`, `pattern` and `allOf`. A schema with `$ref` or `nullable`
- * reads as `unknown`, because these keywords can permit more values. A schema with more than one of `type`, `anyOf`
- * and `oneOf` gives the type of the first, and an issue for each other. The function does not throw.
+ * `unknown`, and the issues name it. Examples are `minimum` and `pattern`. A schema with `nullable` or `$dynamicRef`
+ * reads as `unknown`, because these keywords can permit more values. The function does not throw.
  *
  * @param schema - The schema, as JSON.
  * @returns The type, and the problems of the reading with their keys in the schema.
  */
 export function typeFromSchema(schema: unknown): TypeReading {
-  const reader = new SchemaReader();
+  const reader = new SchemaReader(schema);
   try {
     return { type: reader.read(schema, [], 0), issues: reader.issues };
   } catch (error) {

package/src/reference.ts

@@ -1,6 +1,6 @@
 import { type Envelope, type Json, type Key, docEquals, isEnvelope, isKey, isRecord, typeName } from "./doc.ts";
 import { ask } from "./ladder.ts";
-import { type AttributeDeclaration, type CapsRule, type CircularRule, type Kind, type TreeContract, circularOf, equationType, lookupKind } from "./world.ts";
+import { type AttributeDeclaration, type CapsRule, type CircularRule, type Kind, type TreeContract, circularOf, collectOf, equationType, lookupKind } from "./world.ts";
 import { type PartSlot, type Split, partsOf, pathMatches } from "./parts.ts";
 import { type Cap, type Context, type HostThing, type Resolution, type ResolveOptions, type Thing, ROOTS, THING, isHostThing, resolve, valueOfThing, worldThing } from "./deref.ts";
 import { type AttributeRung, STD_EVALUATORS } from "./stdlib.ts";
@@ -754,6 +754,8 @@ interface RefTree {
 interface RefNode {
   readonly tree: RefTree;
   readonly kind: string;
+  /** The binding name from the header of the document of the node (TREE.NAMED). */
+  readonly name: string | undefined;
   readonly place: readonly Key[];
   readonly parts: readonly Part[];
   readonly ctx: Context;
@@ -831,6 +833,52 @@ function foldOf(node: RefNode, name: string, fold: NonNullable<AttributeDeclarat
   return acc;
 }
 
+/**
+ * TREE.COLLECT and TREE.NAMED: the node, then each node of this tree in each list `children`, in the order of the
+ * lists. Each node counts one time. The registry `names` maps each binding name to its node.
+ */
+function collectIn(node: RefNode, name: string, declared: unknown): Result {
+  const rule = collectOf(declared);
+  if (!rule.ok) return fail("#VALUE!", `The attribute ${nameOfAttribute(node, name)} has a bad declaration collect. ${rule.reason}`);
+  const registry: Record<string, unknown> = {};
+  const first = new Map<string, RefNode>();
+  let acc: Result = rule.names ? ok(registry) : equationOf(node, rule.unit, {});
+  if (!acc.ok) return acc;
+  const done: RefNode[] = [];
+  // The contribution of a node comes before the nodes of its list children. A failure ends the collection.
+  const visit = (at: RefNode): Result | undefined => {
+    if (done.includes(at)) return undefined;
+    done.push(at);
+    if (rule.names && at.name !== undefined) {
+      const earlier = first.get(at.name);
+      if (earlier !== undefined) {
+        return fail("#VALUE!", `Two nodes have the name ${at.name} in the registry ${nameOfAttribute(node, name)}: ${earlier.kind} at [${earlier.place.join(", ")}] and ${at.kind} at [${at.place.join(", ")}].`);
+      }
+      first.set(at.name, at);
+      Object.defineProperty(registry, at.name, { value: at.thing, enumerable: true, writable: true, configurable: true });
+    }
+    const term = rule.names ? undefined : termIn(at.contract?.contributes, name);
+    if (!rule.names && term !== undefined) {
+      const item = equationOf(at, term, {});
+      if (!item.ok) return item;
+      acc = equationOf(node, rule.combine, { acc: acc.ok ? acc.value : null, item: item.value });
+      if (!acc.ok) return acc;
+    }
+    const children = attributeOf(at, "children");
+    if (children === undefined) return undefined;
+    if (!children.ok) return children;
+    if (!Array.isArray(children.value)) return fail("#VALUE!", `The collection of ${name} needs a list in children of ${at.kind} at [${at.place.join(", ")}].`);
+    for (const item of children.value) {
+      const child = refNodeOf(item);
+      if (child === undefined || child.tree !== node.tree) continue;
+      const failed = visit(child);
+      if (failed !== undefined) return failed;
+    }
+    return undefined;
+  };
+  return visit(node) ?? acc;
+}
+
 /**
  * TREE.LADDER: the rungs of the ladder of an attribute, in their order. A rung gives `undefined` when it does not
  * answer, and the next rung then tries.
@@ -860,6 +908,7 @@ const REF_RUNGS: readonly (readonly [AttributeRung, (node: RefNode, name: string
     (node, name) => {
       const declared = termIn(node.contract?.attributes, name);
       if (declared?.fold !== undefined) return foldOf(node, name, declared.fold);
+      if (declared?.collect !== undefined) return collectIn(node, name, declared.collect);
       return declared?.default === undefined ? undefined : equationOf(node, declared.default, {});
     },
   ],
@@ -1065,7 +1114,7 @@ function plainValue(value: unknown, open: readonly object[]): Result {
  * tree gives its JSON. A step on the thing reads an attribute, and a failed attribute throws its own error. The node
  * reads `self` only through `resolve` (C4, TREE.SELF).
  */
-const treeDefinition: EvalFn = ({ parts, context, kind, place, machine, typePath, resolve: walk }) => {
+const treeDefinition: EvalFn = ({ parts, context, kind, place, machine, typePath, resolve: walk, doc }) => {
   const reached = walk(["self"]);
   const parent: Thing | undefined = reached.ok ? reached.thing : undefined;
   const outer = refNodeOf(parent);
@@ -1076,6 +1125,7 @@ const treeDefinition: EvalFn = ({ parts, context, kind, place, machine, typePath
   const node: RefNode = {
     tree: nested ? outer.tree : { open: true },
     kind,
+    name: doc.name,
     place,
     parts,
     ctx: context,

package/src/static.ts

@@ -1,7 +1,7 @@
 import { type Envelope, type Json, type Key, isKey, isRecord, typeName } from "./doc.ts";
-import { type Kind, type World, type WorldEntry, circularOf, eachKind, effectsOfVerb, equationType, isKind, isNamespace } from "./world.ts";
-import { ask } from "./ladder.ts";
-import { type PartSlot, partsOf, scopesOf } from "./parts.ts";
+import { type Kind, type LazyRule, type World, type WorldEntry, circularOf, collectOf, eachKind, effectsOfVerb, equationType, isKind, isNamespace } from "./world.ts";
+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";
@@ -405,6 +405,19 @@ export interface Typing {
   readonly places: readonly Typed[];
 }
 
+/**
+ * This function gives the parts that the code of a runner evaluates itself, without a wait (RUN.DRIVES, D119). The
+ * answer of the hook `facts` for the code wins over the contract. The contract describes only the code of its kind for
+ * `eval`. Without a declaration, the runner passes each wait of its parts through.
+ */
+function driveRules(machine: Machine, v: DocVisit, kind: Kind, name: string, rung: string | undefined, verb: string): readonly LazyRule[] | undefined {
+  if (verb !== "eval") return undefined;
+  const hook = machine.facts?.(v.typePath ?? [], name)?.drives;
+  if (hook !== undefined) return hook;
+  const described = v.declared || rung !== "own" || name === answerOf(machine.world, undefined, kind, verb)?.name;
+  return described ? kind.drives : undefined;
+}
+
 /** The least authority: the capability `[]` permits each effect (CAP.KEYS). */
 const EACH: readonly Cap[] = /* @__PURE__ */ Object.freeze([[]]);
 
@@ -412,16 +425,42 @@ const EACH: readonly Cap[] = /* @__PURE__ */ Object.freeze([[]]);
 const NO_EFFECTS: readonly (readonly Key[])[] = /* @__PURE__ */ Object.freeze([]);
 
 /**
- * This function gives the effects that the contract of the kind of a visit declares for a verb, as keys
- * (FACTS.EFFECTS, VERB.EFFECTS). The text `"type"` gives the type of the document after each alias. A visit without a
- * kind declares no effect. `check`, `factsOf` and `effectsOf` read the declarations with this one function (D27).
+ * This function gives the effects that the code of a visit declares for a verb, as keys (FACTS.EFFECTS, VERB.EFFECTS).
+ * The text `"type"` gives the type of the document after each alias. A visit without a kind declares no effect.
+ * `check`, `factsOf`, `effectsOf` and `checkLatent` read the declarations with this one function (D27).
+ *
+ * For `eval`, the answer of the hook `facts` of the machine for the code of the visit wins over the contract of the
+ * kind (CAP.OWN-EFFECTS, D118). Thus a language gives the effects of an own entry for another evaluator. Without a
+ * machine, or without the field `effects` in the answer, the contract gives the effects.
  *
  * @param v - The visit.
  * @param verb - The verb. The default is `eval`. A kind without a declaration for the verb gives no effect.
- * @returns The keys of each declared effect, in the order of the contract.
+ * @param machine - The machine with the hook `facts`, when the caller has it.
+ * @param name - The name of the evaluator of the visit, when the caller knows it. Else the ladder gives it.
+ * @returns The keys of each declared effect, in the order of the declaration.
  */
-export function declaredEffects(v: DocVisit, verb = "eval"): readonly (readonly Key[])[] {
-  return verbDeclared(v, verb) ?? NO_EFFECTS;
+export function declaredEffects(v: DocVisit, verb = "eval", machine?: Machine, name?: string): readonly (readonly Key[])[] {
+  return hookEffects(v, verb, machine, name) ?? verbDeclared(v, verb) ?? NO_EFFECTS;
+}
+
+/**
+ * This function gives the effects that the hook `facts` gives for the code of a visit, as keys (D118). The result is
+ * `undefined` for another verb than `eval`, without the hook, or when the answer has no field `effects`.
+ */
+function hookEffects(v: DocVisit, verb: string, machine: Machine | undefined, name: string | undefined): readonly (readonly Key[])[] | undefined {
+  if (verb !== "eval" || machine?.facts === undefined || v.kind === undefined) return undefined;
+  const code = name ?? answerOf(machine.world, v.declared ? undefined : v.doc.own, v.kind, "eval")?.name;
+  const effects = code === undefined ? undefined : machine.facts(v.typePath ?? [], code)?.effects;
+  return effects === undefined ? undefined : effectKeys(v, effects);
+}
+
+/**
+ * This function gives the keys of a declaration of effects at a visit (D27). The text `"type"` gives the type of the
+ * document after each alias.
+ */
+export function effectKeys(v: DocVisit, effects: "type" | readonly string[]): readonly (readonly Key[])[] {
+  if (effects.length === 0) return NO_EFFECTS;
+  return effects === "type" ? [v.typePath ?? []] : effects.map((kind) => kind.split("."));
 }
 
 /**
@@ -433,8 +472,7 @@ function verbDeclared(v: DocVisit, verb: string): readonly (readonly Key[])[] |
   if (v.kind === undefined) return verb === "eval" ? NO_EFFECTS : undefined;
   const effects = effectsOfVerb(v.kind, verb);
   if (effects === undefined) return undefined;
-  if (effects.length === 0) return NO_EFFECTS;
-  return effects === "type" ? [v.typePath ?? []] : effects.map((kind) => kind.split("."));
+  return effectKeys(v, effects);
 }
 
 /**
@@ -637,7 +675,8 @@ const FOLD_NAMES: readonly string[] = /* @__PURE__ */ Object.freeze(["acc", "ite
 
 /**
  * This function gives each equation of the tree contract of a kind, with the names that it sees (D42). An equation of
- * `equations`, a `unit` and a `default` see no names. `check` and `factsOf` read the equations with this one function.
+ * `equations`, a `unit`, a `default` and a contribution see no names. `check` and `factsOf` read the equations with
+ * this one function.
  */
 export function equationsOf(kind: Kind): readonly Equation[] {
   const tree = kind.tree;
@@ -651,7 +690,14 @@ export function equationsOf(kind: Kind): readonly Equation[] {
       out.push({ label: `tree.attributes.${name}.fold.combine`, term: declared.fold.combine, names: FOLD_NAMES, attribute: name, down: false });
     }
     if (declared.default !== undefined) out.push({ label: `tree.attributes.${name}.default`, term: declared.default, names: [], attribute: name, down: false });
+    const collect = declared.collect === undefined ? undefined : collectOf(declared.collect);
+    if (collect?.ok === true && !collect.names) {
+      out.push({ label: `tree.attributes.${name}.collect.unit`, term: collect.unit, names: [], attribute: name, down: false });
+      out.push({ label: `tree.attributes.${name}.collect.combine`, term: collect.combine, names: FOLD_NAMES, attribute: name, down: false });
+    }
   }
+  // A contribution is not the attribute of its node, thus an own part of its name does not hide it (D122).
+  for (const [name, term] of Object.entries(tree.contributes ?? {})) out.push({ label: `tree.contributes.${name}`, term, names: [], attribute: name, down: false, contributes: true });
   return out;
 }
 
@@ -665,6 +711,8 @@ export interface Equation {
   readonly attribute: string;
   /** `true` for an equation of `down`: it gives the attribute of a child. */
   readonly down: boolean;
+  /** `true` for an equation of `contributes`: it gives a contribution to a collection (TREE.COLLECT). */
+  readonly contributes?: true;
 }
 
 /**
@@ -837,7 +885,7 @@ export function answered(world: World, node: SeenNode, name: string): boolean {
   if (hasEntry(tree?.equations, name)) return true;
   if (node.parent === undefined ? downNames(world).has(name) : hasEntry(node.parent.kind.tree?.down, name)) return true;
   const declared = tree?.attributes !== undefined && Object.hasOwn(tree.attributes, name) ? tree.attributes[name] : undefined;
-  return declared !== undefined && (declared.copy === true || declared.fold !== undefined || declared.default !== undefined);
+  return declared !== undefined && (declared.copy === true || declared.fold !== undefined || declared.collect !== undefined || declared.default !== undefined);
 }
 
 /**
@@ -853,10 +901,10 @@ function equationIssues(machine: Machine, kind: Kind, kindText: string, options:
   state.needs.set(kind, needs);
   for (const name of Object.keys(kind.tree?.attributes ?? {})) needs.push({ name, why: "the kind declares it", hidden: undefined });
   const self: SeenNode = { kind, text: kindText, own: undefined, parent: undefined };
-  for (const { label, term, names, attribute, down } of equationsOf(kind)) {
+  for (const { label, term, names, attribute, down, contributes } of equationsOf(kind)) {
     const inner: CheckOptions = { names, ...(of === undefined ? {} : { declaredType: of }), ...(options.caps === undefined ? {} : { caps: [] }) };
     const read = (name: string): void => {
-      needs.push({ name, why: `the equation ${label} reads it`, hidden: down ? undefined : attribute });
+      needs.push({ name, why: `the equation ${label} reads it`, hidden: down || contributes === true ? undefined : attribute });
     };
     for (const issue of checkAll(machine, term, inner, undefined, state, { node: self, read })) {
       out.push({ code: issue.code, place: [], reason: `In the equation ${label} of the kind ${kindText}: ${issue.reason}` });
@@ -868,12 +916,13 @@ function equationIssues(machine: Machine, kind: Kind, kindText: string, options:
 /**
  * This function finds the issues of the contract of a tree kind (TREE.CHECK-RESERVED). An attribute with the name of a
  * structural step gets no read. A tree kind of the run side contradicts the evaluation on demand of its attributes. A
- * declaration `circular` without a start value or with a bad limit gives `#VALUE!` (TREE.CIRCULAR-CHECK).
+ * declaration `circular` without a start value or with a bad limit gives `#VALUE!` (TREE.CIRCULAR-CHECK). A declaration
+ * `collect` without its form gives `#VALUE!` too (TREE.COLLECT).
  */
 function contractIssues(kind: Kind, kindText: string): readonly Issue[] {
   const out: Issue[] = [];
   const tree = kind.tree;
-  for (const table of ["equations", "down", "attributes"] as const) {
+  for (const table of ["equations", "down", "attributes", "contributes"] as const) {
     for (const name of Object.keys(tree?.[table] ?? {})) {
       const why = Object.hasOwn(STRUCTURAL, name) ? STRUCTURAL[name] : undefined;
       if (why !== undefined) out.push({ code: "#NAME?", place: [], reason: `The kind ${kindText} gives the reserved attribute tree.${table}.${name}: ${why}.` });
@@ -883,6 +932,8 @@ function contractIssues(kind: Kind, kindText: string): readonly Issue[] {
   for (const [name, declared] of Object.entries(tree?.attributes ?? {})) {
     const rule = declared.circular === undefined ? undefined : circularOf(declared.circular);
     if (rule !== undefined && !rule.ok) out.push({ code: "#VALUE!", place: [], reason: `The kind ${kindText} has a bad declaration tree.attributes.${name}.circular. ${rule.reason}` });
+    const collect = declared.collect === undefined ? undefined : collectOf(declared.collect);
+    if (collect !== undefined && !collect.ok) out.push({ code: "#VALUE!", place: [], reason: `The kind ${kindText} has a bad declaration tree.attributes.${name}.collect. ${collect.reason}` });
   }
   if (kind.side === "run") {
     out.push({ code: "#CALC!", place: [], reason: `The tree kind ${kindText} is on the run side: a node evaluates its attributes on demand, thus in no fixed order.` });
@@ -971,6 +1022,9 @@ function checkAll(
   // run, and a drive for a runner under an evaluator. A document without code fails before its parts, thus it is not
   // in the map.
   const waits = options.run === true ? new Map<DocVisit, Waits>() : undefined;
+  // The parts that the code of a runner evaluates itself, without a wait (RUN.DRIVES). They get no wait, as under an
+  // evaluator. Only a runner that declares `drives` is in the map.
+  const driven = new Map<DocVisit, readonly LazyRule[]>();
   const drives: Drive[] = [];
   const maxDepth = machine.maxDepth ?? 1000;
   const anyName = options.names === "any";
@@ -1026,7 +1080,7 @@ function checkAll(
         if (known !== true) push({ code: "#NAME?", place: v.place, reason: known, at: v.at });
       }
       const caps = v.caps;
-      const stated = verbDeclared(v, verb);
+      const stated = hookEffects(v, verb, machine, name) ?? verbDeclared(v, verb);
       const declared = stated ?? NO_EFFECTS;
       if (allowed !== undefined && caps !== undefined) {
         for (const kind of declared) {
@@ -1035,7 +1089,9 @@ function checkAll(
       }
       if (waits !== undefined && coded) {
         // The parent of the root is the driver of the run, and it can wait. An evaluator gives its parts no wait.
-        const up = v.parent === undefined ? true : waits.get(v.parent);
+        let up = v.parent === undefined ? true : waits.get(v.parent);
+        const rules = v.parent === undefined ? undefined : driven.get(v.parent);
+        if (up !== false && rules !== undefined && v.parent !== undefined && rulesCover(rules, v.parent.kind?.parts, v.parent.doc.value as Json, v.slot)) up = false;
         let chain: Waits = false;
         if (runner && up === false) {
           // The run drives a runner under an evaluator, and only a real wait fails (RUN.DRIVE-NESTED). Its issue goes in
@@ -1047,6 +1103,10 @@ function checkAll(
           chain = up ?? true;
         }
         waits.set(v, chain);
+        if (runner && v.kind !== undefined) {
+          const own = driveRules(machine, v, v.kind, name, answer.rung, verb);
+          if (own !== undefined && own.length > 0) driven.set(v, own);
+        }
         // A runner waits only for an effect that reaches the host (C6). A refused effect gives #CAP! without a wait. A
         // runner without a declaration for the verb can cause each effect, thus it can wait.
         if (typeof chain === "object" && !chain.wait) {