@mark1russell7/coeval 0.16.0 → 0.17.0

package/src/index.ts

@@ -174,6 +174,7 @@ export {
   STD_RUNNERS,
   STD_WALKERS,
   STD_WORLD,
+  WORLD_SYNTAX,
   attributeTrace,
   nearestWalker,
   placeOf,
@@ -238,8 +239,11 @@ export {
   type ParseResult,
   type SyntaxAssoc,
   type SyntaxCalls,
+  type SyntaxEnvelopes,
   type SyntaxFixity,
   type SyntaxForm,
+  type SyntaxFormArgs,
+  type SyntaxHeader,
   type SyntaxIssue,
   type SyntaxLiterals,
   type SyntaxOperator,
@@ -277,7 +281,25 @@ export {
   agreeSchedule,
 } from "./meaning.ts";
 export { type GraphCycle, type GraphEdge, type GraphNode, type GraphOptions, type NodeGraph, components, cycles, heights, necessary, nodeLayers } from "./graph.ts";
-export { type Recorder, type ReplayEntry, type ReplayLog, type ReplayOptions, type ReplaySettle, recorder, replayer } from "./replay.ts";
+export {
+  type Recorder,
+  type ReplayCausePartsJson,
+  type ReplayEntry,
+  type ReplayEntryJson,
+  type ReplayErrorJson,
+  type ReplayExceptionJson,
+  type ReplayLog,
+  type ReplayLogJson,
+  type ReplayPartJson,
+  type ReplayPartsJson,
+  type ReplayOptions,
+  type ReplayResultJson,
+  type ReplaySettle,
+  decodeLog,
+  encodeLog,
+  recorder,
+  replayer,
+} 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 PartType, type RootTypes, type TypeInput, type TypeProblem, type TypeRule, type Typed, CAPS_TYPE } from "./typing.ts";

package/src/merge.ts

@@ -89,32 +89,53 @@ function same(a: unknown, b: unknown): boolean {
 
 /**
  * Two domains are the same when they are one object. They are also the same when they have the same test `is`,
- * parents, summary and steps. Thus two languages that give one test under one name give one domain.
+ * parents, summary, steps, codec, list of values and covers. Thus two languages that give one test under one name give one
+ * domain. Two codecs are the same when they have the same functions `encode` and `decode` (D80).
  */
 function sameDomain(a: Domain, b: Domain): boolean {
-  return a === b || (a.is === b.is && same(a.under ?? [], b.under ?? []) && a.summary === b.summary && same(a.steps ?? {}, b.steps ?? {}));
+  if (a === b) return true;
+  // The type names each field of Domain, thus a new field fails the check of types until the merge compares it (K180).
+  const fields: { readonly [K in keyof Domain]-?: boolean } = {
+    is: a.is === b.is,
+    under: same(a.under ?? [], b.under ?? []),
+    summary: a.summary === b.summary,
+    steps: same(a.steps ?? {}, b.steps ?? {}),
+    codec: same(a.codec ?? null, b.codec ?? null),
+    values: same(a.values ?? null, b.values ?? null),
+    covers: same(a.covers ?? [], b.covers ?? []),
+  };
+  return Object.values(fields).every(Boolean);
 }
 
-/** What `extendDomain` adds to a domain: more parents, and the types of more steps. */
+/** What `extendDomain` adds to a domain: more parents, the types of more steps, and more covers. */
 export interface DomainExtension {
   /** The names of the parents to add. A member of the domain then also passes the test of each new parent. */
   readonly under?: readonly string[];
   /** The types of the steps to add. A step with the key of an earlier step replaces its type. */
   readonly steps?: Readonly<Record<string, ValueType>>;
+  /**
+   * The covers to add (TYPE.FITS-COVER, D85). A cover that the domain has already does not change. The language that
+   * adds a cover keeps it true, because `fits` trusts it.
+   */
+  readonly covers?: readonly (readonly string[])[];
 }
 
 /**
- * This function makes a part of a merge that adds parents or steps to a domain of an earlier part (TYPE.PARENTS). An
- * example is a domain of another language. The part reads the domain from the merge before it (`prev`). It gives a
- * copy with the same test and summary, and it names `["domains", name]` in `replaces` (D17). A domain of the kernel
- * that the earlier parts do not name comes from `STD_DOMAINS`.
+ * This function makes a part of a merge that adds parents, steps or covers to a domain of an earlier part
+ * (TYPE.PARENTS). An example is a domain of another language. The part reads the domain from the merge before it
+ * (`prev`). It gives a copy with the same test, summary, codec and list of values, and it names `["domains", name]`
+ * in `replaces` (D17).
+ * A domain of the kernel that the earlier parts do not name comes from `STD_DOMAINS`.
+ *
+ * An extension does not change the codec. Thus each member keeps its document (D80).
  *
  * A new parent adds its test to the domain (TYPE.MEMBER). Thus `fits` stays sound, but a value that fails the test of
  * the parent is no longer a member. The language that adds the parent keeps the signatures of the other language
- * true. A name without a domain gives an empty part, and `typeIssues` reports each use of that name.
+ * true. A new parent of a domain in a cover of another domain can make that cover false (D85). A name without a
+ * domain gives an empty part, and `typeIssues` reports each use of that name.
  *
  * @param name - The name of the domain.
- * @param more - The parents and the steps to add.
+ * @param more - The parents, the steps and the covers to add.
  * @returns The part, as a function of the merge before it.
  */
 export function extendDomain(name: string, more: DomainExtension): (prev: Machine) => MachinePart {
@@ -125,14 +146,25 @@ export function extendDomain(name: string, more: DomainExtension): (prev: Machin
     const under = [...(found.under ?? [])];
     for (const parent of more.under ?? []) if (parent !== name && !under.includes(parent)) under.push(parent);
     const steps = { ...found.steps, ...more.steps };
-    const domain: Domain = {
+    const covers = [...(found.covers ?? [])];
+    for (const cover of more.covers ?? []) if (!covers.some((each) => same(each, cover))) covers.push([...cover]);
+    // The type names each field of Domain, thus a new field fails the check of types until the copy reads it (K180).
+    const fields: { readonly [K in keyof Domain]-?: Domain[K] | undefined } = {
       is: found.is,
-      ...(under.length === 0 ? {} : { under }),
-      ...(found.summary === undefined ? {} : { summary: found.summary }),
-      ...(Object.keys(steps).length === 0 ? {} : { steps }),
+      under: under.length === 0 ? undefined : under,
+      summary: found.summary,
+      steps: Object.keys(steps).length === 0 ? undefined : steps,
+      // A new parent only adds a test, thus each member keeps its document (D80).
+      codec: found.codec,
+      // A new parent only adds a test, thus the list of values stays complete (TYPE.FITS-FINITE).
+      values: found.values,
+      // A new parent only adds a test, thus each cover stays true (TYPE.FITS-COVER). A new cover is a claim of the extension.
+      covers: covers.length === 0 ? undefined : covers,
     };
+    const domain: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(fields)) if (value !== undefined) domain[key] = value;
     const domains: Record<string, Domain> = {};
-    setOwn(domains, name, domain);
+    setOwn(domains, name, domain as unknown as Domain);
     return { domains, replaces: [["domains", name]] };
   };
 }

package/src/reference.ts

@@ -1,8 +1,8 @@
-import { type Envelope, type Json, type Key, isEnvelope, isRecord, typeName } from "./doc.ts";
+import { type Envelope, type Json, type Key, isEnvelope, isKey, isRecord, typeName } from "./doc.ts";
 import { ask } from "./ladder.ts";
 import { type AttributeDeclaration, type CapsRule, type Kind, type TreeContract, 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, THING, isHostThing, resolve, valueOfThing, worldThing } from "./deref.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";
 import { type EvalError, type Failed, type Result, Failure, describe, fail, ok, placed, thrown } from "./errors.ts";
 import {
@@ -14,6 +14,7 @@ import {
   type Machine,
   type Part,
   type Perform,
+  type Read,
   type RunFn,
   type RunInput,
   type RunPart,
@@ -23,6 +24,7 @@ import {
   makeContext,
   permits,
   placeText,
+  reachedOf,
   waitedReason,
 } from "./evaluate.ts";
 import { type FormulaProfile, type OpFn, Held, STD_EXT } from "./formula.ts";
@@ -57,6 +59,12 @@ export interface ReferenceOptions {
    * each verb by the same rules (VERB.AGREE).
    */
   readonly verb?: string;
+  /**
+   * A list that gets each read of a resolution, in its order (REF.READS). A read has the shape of a read of a plan:
+   * the path, what it reached and the mark `free`. The reads of a closure and of an equation of a tree go in the
+   * same list. The reference adds no kept reads, because it has no static reads of a closure.
+   */
+  readonly reads?: Read[];
 }
 
 /** The options of a run of the reference: the options of an evaluation, with the host and a signal (REF.RUN). */
@@ -80,6 +88,13 @@ interface Scope {
   alls: number;
 }
 
+/** The record of the reads of one evaluation of the reference (REF.READS). */
+interface Reading {
+  readonly list: Read[];
+  /** The context at the root of the evaluation. A free read reads this context. */
+  readonly root: Context;
+}
+
 /** The state of one evaluation of the reference. */
 interface Env {
   readonly machine: Machine;
@@ -95,6 +110,8 @@ interface Env {
   readonly verb: string;
   /** The scope of the code that evaluates at this time. `all` changes it for each item. */
   scope: Scope;
+  /** The record of the reads. A nested evaluation for an equation of a tree keeps the record of its tree. */
+  readonly reading: Reading | undefined;
 }
 
 /** The code that answers a document: a function evaluator, a runner, or a gap of the reference. */
@@ -221,6 +238,44 @@ function resolveFully(machine: Machine, ctx: Context, path: readonly unknown[],
   return options?.hops === true ? found : { ...found, hops: [] };
 }
 
+/** The text that names a resolution in the error of an exception of the host (READS.RECORD). */
+const READ_FAILED = "the resolution of a path";
+
+/**
+ * This function resolves a path for a document, and records the read when the evaluation has a list (REF.READS,
+ * READS.RECORD). An exception of the host gives the error value of the read, and the exception goes on.
+ */
+function readAt(env: Env, ctx: Context, path: readonly unknown[], options?: ResolveOptions): Resolution {
+  const reading = env.reading;
+  if (reading === undefined) return resolveFully(env.machine, ctx, path, options);
+  const free = freeIn(reading.root, ctx, path);
+  let found: Resolution;
+  try {
+    found = resolveFully(env.machine, ctx, path, options);
+  } catch (error) {
+    reading.list.push({ path, reached: thrown(error, READ_FAILED), free });
+    throw error;
+  }
+  reading.list.push(options?.hops === true ? { path, reached: reachedOf(found), free, hops: found.hops } : { path, reached: reachedOf(found), free });
+  return found;
+}
+
+/**
+ * This function tells if a read reads the context at the root of the evaluation (READS.FREE). The reference reads
+ * the rule from SPEC. A name that a kind binds, a `self` that a kind sets and a path without a root are not free. A
+ * name that a kind does not bind keeps its value from the root.
+ */
+function freeIn(root: Context, ctx: Context, path: readonly unknown[]): boolean {
+  const head = path[0];
+  if (head === "self") return Object.is(ctx.self, root.self);
+  if (head !== "names") return typeof head === "string" && (ROOTS as readonly string[]).includes(head);
+  const name = path[1];
+  if (ctx.names === root.names || !isKey(name)) return true;
+  const key = String(name);
+  const bound = Object.hasOwn(ctx.names, key);
+  return bound === Object.hasOwn(root.names, key) && (!bound || Object.is(ctx.names[key], root.names[key]));
+}
+
 /**
  * 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
@@ -385,7 +440,7 @@ function evalInput(env: Env, seen: Seen, at: At): EvalInput {
     place: at.place,
     machine: env.machine,
     ...(at.address ? { address: true } : {}),
-    resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
+    resolve: (path, options) => readAt(env, at.ctx, path, options),
     effect: (kind, payload) => causeFromEvaluator(env, at.ctx, kind, payload, at.place),
     fill,
   };
@@ -413,7 +468,7 @@ function runInput(env: Env, seen: Seen, at: At): RunInput {
     context: at.ctx,
     place: at.place,
     machine: env.machine,
-    resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
+    resolve: (path, options) => readAt(env, at.ctx, path, options),
     effect: (kind, payload) => causeAndWait(env, at.ctx, kind, payload, at.place),
     all: (list, options) => together(env, list, options),
     fill,
@@ -458,6 +513,7 @@ function* together(env: Env, list: readonly RunPart[], options: AllOptions = {})
   outer.alls += 1;
   let failed = false;
   let started = 0;
+  let before = 0;
   const end = (index: number, result: Result): void => {
     results[index] = result;
     if (failFast && !result.ok) failed = true;
@@ -508,10 +564,11 @@ function* together(env: Env, list: readonly RunPart[], options: AllOptions = {})
   };
   startMore();
   while (waiting.length > 0 && !failed) {
-    const chosen = env.journal?.next?.(address, waiting.map((waiter) => waiter.index));
+    const chosen = env.journal?.next?.(address, waiting.map((waiter) => waiter.index), before);
     const pick = chosen === undefined ? undefined : waiting.find((waiter) => waiter.index === chosen);
     const resumed = (yield pick === undefined ? Promise.race(waiting.map((waiter) => waiter.next)) : pick.next) as Resumed;
     env.journal?.settled?.(address, resumed.waiter.index);
+    before += 1;
     waiting.splice(waiting.indexOf(resumed.waiter), 1);
     goOn(resumed.waiter.index, resumed.waiter.steps, resumed);
     startMore();
@@ -543,9 +600,18 @@ function* together(env: Env, list: readonly RunPart[], options: AllOptions = {})
  * @returns The result.
  */
 export function reference(machine: Machine, doc: unknown, context: Context = makeContext(), options: ReferenceOptions = {}): Result {
-  const env = envOf(machine, options, false);
+  return evaluateRoot(machine, doc, context, options, undefined);
+}
+
+/**
+ * This function evaluates a document from its root. An equation of a tree gives the record of its tree. Thus the
+ * reads of the equation go in the list of the outer evaluation (REF.READS).
+ */
+function evaluateRoot(machine: Machine, doc: unknown, context: Context, options: ReferenceOptions, outer: Reading | undefined): Result {
+  const at = rootAt(machine, doc, context, options);
+  const env = envOf(machine, options, false, at.ctx, outer);
   try {
-    return within(env, () => evaluateAt(env, rootAt(machine, doc, context, options)));
+    return within(env, () => evaluateAt(env, at));
   } catch (error) {
     return placed(thrown(error, "the reference"), []);
   }
@@ -567,13 +633,17 @@ export function reference(machine: Machine, doc: unknown, context: Context = mak
  * @returns The result, when the run ends.
  */
 export function referenceRun(machine: Machine, doc: unknown, context: Context = makeContext(), options: ReferenceRunOptions = {}): Promise<Result> {
-  const env = envOf(machine, options, true);
-  const steps = stepsAt(env, rootAt(machine, doc, context, options));
+  const at = rootAt(machine, doc, context, options);
+  const env = envOf(machine, options, true, at.ctx, undefined);
+  const steps = stepsAt(env, at);
   return driveRun(env, steps, options.signal).catch((error: unknown) => placed(thrown(error, "the reference"), []));
 }
 
-/** This function makes the state of the reference for one evaluation or one run. */
-function envOf(machine: Machine, options: ReferenceOptions, running: boolean): Env {
+/**
+ * This function makes the state of the reference for one evaluation or one run. The record of the reads comes from
+ * the evaluation around it, or from the list of the options.
+ */
+function envOf(machine: Machine, options: ReferenceOptions, running: boolean, root: Context, outer: Reading | undefined): Env {
   const perform = options.perform;
   return {
     machine,
@@ -585,6 +655,7 @@ function envOf(machine: Machine, options: ReferenceOptions, running: boolean): E
     running,
     verb: options.verb ?? "eval",
     scope: { prefix: "", counts: new Map(), alls: 0 },
+    reading: outer ?? (options.reads === undefined ? undefined : { list: options.reads, root }),
   };
 }
 
@@ -698,13 +769,14 @@ function refNodeOf(thing: unknown): RefNode | undefined {
 
 /**
  * TREE.LADDER: an equation of the kind of a node evaluates in the reference. It gets the node as `self`, the names of
- * its rung and no capabilities. A bare equation gets the type `of` of the parts of the kind.
+ * its rung and no capabilities. A bare equation gets the type `of` of the parts of the kind. The reads of the
+ * equation go in the record of the evaluation that made the node (REF.READS).
  */
 function equationOf(node: RefNode, term: Json, names: Readonly<Record<string, unknown>>): Result {
   const env = node.env;
   if (env === undefined) return fail("#NOEVAL", "The evaluation of an equation needs the machine.");
   const ctx: Context = { ...node.ctx, names, caps: [], self: node.thing };
-  return reference(env.machine, term, ctx, { definitions: env.definitions, ...(node.of === undefined ? {} : { declaredType: node.of }) });
+  return evaluateRoot(env.machine, term, ctx, { definitions: env.definitions, ...(node.of === undefined ? {} : { declaredType: node.of }) }, env.reading);
 }
 
 function termIn<T>(table: Readonly<Record<string, T>> | undefined, name: string): T | undefined {
@@ -960,7 +1032,11 @@ export function formulaDefinitions(profile: FormulaProfile = {}): Definitions {
     // FORMULA.LET: a path through a name whose binding failed gives the error of the binding.
     const head = path[0] === "names" && typeof path[1] === "string" ? path[1] : undefined;
     const bound = head === undefined ? undefined : own(context.names, head);
-    if (bound instanceof Held) return { ok: false, error: bound.error };
+    if (bound instanceof Held) {
+      // The result comes from the binding of the name, thus the name is a read (READS.RECORD).
+      walk(["names", head]);
+      return { ok: false, error: bound.error };
+    }
     const found = walk(steps);
     if (!found.ok) return fail(found.code, found.reason);
     // FORMULA.ADDRESS: an address gives what the path reaches.