@mark1russell7/coeval 0.22.0 → 0.24.0

package/src/index.ts

@@ -60,9 +60,11 @@ export {
   type World,
   type WorldEntry,
   CIRCULAR_LIMIT,
+  GENERATION_LIMIT,
   argsKey,
   atArgsOf,
   atRuleOf,
+  documentKey,
   circularOf,
   collectOf,
   effectsOfVerb,
@@ -104,6 +106,7 @@ export {
 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 CompiledPath,
   type Context,
   type DerefCode,
   type Hop,
@@ -121,6 +124,7 @@ export {
   type Walker,
   ROOTS,
   THING,
+  compilePath,
   context,
   derefStep,
   isHostThing,
@@ -157,6 +161,7 @@ export {
   type RunFn,
   type RunInput,
   type RunOptions,
+  type Clause,
   type RunPart,
   type Runner,
   type Runtime,
@@ -173,9 +178,11 @@ export {
   narrow,
   nodeAt,
   partCaps,
+  partGrants,
   permits,
   planner,
   prepare,
+  resolveCompiled,
   run,
 } from "./evaluate.ts";
 export {
@@ -255,11 +262,15 @@ export {
   jsTruthy,
 } from "./formula.ts";
 export { decodeDomain, decodeValue, encodeValue } from "./codec.ts";
+export { type CodecFinding, type CodecLaw, type CodecLawsOptions, type CodecProbe, codecLaws } from "./codec-laws.ts";
 export {
   type ParseResult,
   type SyntaxAssoc,
   type SyntaxCalls,
+  type SyntaxConstructs,
   type SyntaxEnvelopes,
+  type SyntaxFinding,
+  type SyntaxFindingCode,
   type SyntaxFixity,
   type SyntaxForm,
   type SyntaxFormArgs,
@@ -270,7 +281,9 @@ export {
   type SyntaxProfile,
   type SyntaxRefPattern,
   type SyntaxRefs,
+  MAX_SYNTAX_ISSUES,
   STD_SYNTAX,
+  checkSyntax,
   parse,
   print,
   syntaxFormat,
@@ -282,12 +295,14 @@ export { sameResult } from "./same.ts";
 export { type PrintOptions, type ReadPrints, type ReadsCheck, type VerifyOptions, printReads, verifyReads } from "./reads.ts";
 export { type Durable, type DurableCounts, type DurableOptions, type Epochs, durable } from "./durable.ts";
 export {
+  type CycleIssue,
   type NodeEdge,
   type NodeInfo,
   type NodeRunOptions,
   type Schedule,
   type ScheduleCounts,
   type ScheduleOptions,
+  checkCycles,
   edgesOf,
   schedule,
 } from "./schedule.ts";

package/src/instances.ts

@@ -504,7 +504,22 @@ function rungReads(b: Builder, id: string): void {
     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);
+  if (declared?.default !== undefined) {
+    termReads(b, termRefs(b, node.kind, `tree.attributes.${key}.default`, declared.default), node, undefined, later);
+    return;
+  }
+  // The document of a higher-order attribute is known only in the run, thus its reads are not known (TREE.HIGHER-CHECK).
+  if (declared?.higher !== undefined) {
+    termReads(b, termRefs(b, node.kind, `tree.attributes.${key}.higher`, declared.higher), node, undefined, later);
+    edge(b, undefined, later);
+    return;
+  }
+  // The last rung reads the attribute `forwards` and an attribute of a node that only the run knows (TREE.FORWARD-CHECK).
+  const forwards = tree?.forwards;
+  if (typeof forwards === "string" && forwards !== key) {
+    edge(b, vertexOf(b, node, forwards), later);
+    edge(b, undefined, later);
+  }
 }
 
 /** This function gives the list children of a node before the run. A node without a rung for it has no children. */

package/src/meaning.ts

@@ -58,12 +58,14 @@ export interface ScheduleEngine {
   read(id: string): Result;
 }
 
-/** What a new engine gets beside its machine: the context of the host, and the type of a bare root value. */
+/** What a new engine gets beside its machine. These are the context of the host, the type of a bare root value and the `self` of each node. */
 export interface ScheduleEngineStart {
   /** The first context of the host, without the root `world`. */
   readonly context: Context;
   /** The type of a bare root value, when the options of the harness name one. */
   readonly declaredType?: string;
+  /** The `self` of each node, when the options of the harness have `selves`. It has the form of the option of `schedule`. */
+  readonly selfOf?: (id: string, host: Context) => unknown;
 }
 
 /**
@@ -110,6 +112,12 @@ export interface AgreeScheduleOptions {
   readonly values?: readonly unknown[];
   /** The contexts of the host at the start of the runs, one after the other. */
   readonly contexts?: readonly Context[];
+  /**
+   * The values of the `self` of a node (SCHED.NODE-AGREES). With them, the option `selfOf` of each engine gives each
+   * node its own `self`. Some nodes then share one document, and a change of data can give a node a new `self`. The
+   * value `undefined` keeps the `self` of the host. The default gives each node the context of the host.
+   */
+  readonly selves?: readonly unknown[];
   /** The number of runs. The default is 100. */
   readonly count?: number;
   /** The number of commands in one run. The default is 30. */
@@ -155,6 +163,10 @@ export interface ScheduleAgreementCounts {
   readonly same: number;
   /** The new machines. */
   readonly machines: number;
+  /** The changes of data with a new `self` of a node, only with the option `selves`. */
+  readonly selves: number;
+  /** The documents that a node shares with another node, only with the option `selves`. */
+  readonly shared: number;
 }
 
 /** The outcome of `agreeSchedule`: what the harness reached, or the first disagreement. */
@@ -266,7 +278,7 @@ function shuffle<T>(items: readonly T[], rng: Random): T[] {
  * This function evaluates each node of a graph from scratch, with the meaning of D31. Each node gets a new plan and
  * one value. The algorithm of Tarjan over the demands finds the cycles. The function keeps nothing between calls.
  */
-function fromScratch(machine: Machine, docs: ReadonlyMap<string, unknown>, base: Context, declaredType: string | undefined): ReadonlyMap<string, Result> {
+function fromScratch(machine: Machine, docs: ReadonlyMap<string, unknown>, base: Context, declaredType: string | undefined, own: ReadonlyMap<string, unknown> | undefined): ReadonlyMap<string, Result> {
   const declared = declaredType === undefined ? {} : { declaredType };
   const values = new Map<string, Result>();
   const index = new Map<string, number>();
@@ -298,7 +310,8 @@ function fromScratch(machine: Machine, docs: ReadonlyMap<string, unknown>, base:
     lowest.set(id, index.get(id) as number);
     component.push(id);
     evaluating.push(id);
-    let result = prepare(machine, docs.get(id), declared).evaluate(ctx);
+    const self = own?.get(id);
+    let result = prepare(machine, docs.get(id), declared).evaluate(self === undefined ? ctx : { ...ctx, self });
     evaluating.pop();
     if ((lowest.get(id) as number) < (index.get(id) as number)) result = cycleOf(id);
     else if (component.splice(component.indexOf(id)).length > 1 || selfReads.has(id)) result = cycleOf(id);
@@ -340,7 +353,8 @@ function named(result: Result): string {
 /**
  * This function examines an engine of a host against an evaluation from scratch (SCHED.AGREES, R4 P4, D58). Each run
  * makes a new engine and a random graph of named nodes from the document generator. Then it gives random commands:
- * edits, new nodes, removed nodes, the same document again, new machines and changes of data.
+ * edits, new nodes, removed nodes, the same document again, new machines and changes of data. The option `selves`
+ * adds a `self` for each node and documents that nodes share (SCHED.NODE-AGREES).
  *
  * - Each read command evaluates the whole graph from scratch two times, with the meaning of D31.
  * - It then demands each node in a random order, or one node, and compares each answer with `sameResult`.
@@ -366,6 +380,7 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
   const hostNames = options.names ?? ["a", "b", "x", "n"];
   const hostValues = options.values ?? standardValues();
   const contexts = options.contexts ?? standardContexts();
+  const selves = options.selves;
   const total = options.count ?? 100;
   const steps = options.steps ?? 30;
   const first = options.seed ?? 9_000_011;
@@ -376,7 +391,7 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
     if (isClosure(a) || isClosure(b)) return isClosure(a) && isClosure(b) && docEquals(closureParams(a), closureParams(b));
     return undefined;
   };
-  const counts = { reads: 0, compared: 0, unrepeatable: 0, values: 0, cycles: 0, runs: 0, data: 0, empty: 0, edits: 0, additions: 0, removes: 0, same: 0, machines: 0 };
+  const counts = { reads: 0, compared: 0, unrepeatable: 0, values: 0, cycles: 0, runs: 0, data: 0, empty: 0, edits: 0, additions: 0, removes: 0, same: 0, machines: 0, selves: 0, shared: 0 };
   const declared = declaredType === undefined ? {} : { declaredType };
   for (let run = 0; run < total; run += 1) {
     const seed = first + run;
@@ -385,7 +400,18 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
     let at = 0;
     let machine = machines[0] as Machine;
     let made = 0;
+    const own = selves === undefined ? undefined : new Map<string, unknown>();
+    const pool: unknown[] = [];
     const make = (): unknown => {
+      if (selves !== undefined && pool.length > 0 && rng.chance(0.4)) {
+        counts.shared += 1;
+        return rng.pick(pool);
+      }
+      const doc = generated();
+      pool.push(doc);
+      return doc;
+    };
+    const generated = (): unknown => {
       if (rng.chance(wired)) return wire(rng, node);
       const roll = rng.int(10);
       if (roll === 0) return value(rng);
@@ -395,15 +421,16 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
       return runs && roll === 9 ? { type: "log", value: [doc] } : doc;
     };
     const docs = new Map<string, unknown>(nodes.map((id) => [id, make()]));
+    if (own !== undefined && selves !== undefined) for (const id of nodes) own.set(id, rng.pick(selves));
     const start = contexts[run % contexts.length] as Context;
     let base: Context = { ...start, names: { ...start.names } };
-    const host = engine(machine, { ...declared, context: base });
+    const host = engine(machine, { ...declared, context: base, ...(own === undefined ? {} : { selfOf: (id: string) => own.get(id) }) });
     for (const [id, doc] of docs) host.set(id, doc);
     for (let step = 0; step < steps; step += 1) {
       const what = rng.int(12);
       if (what < 4) {
-        const fresh = fromScratch(machine, docs, base, declaredType);
-        const again = fromScratch(machine, docs, base, declaredType);
+        const fresh = fromScratch(machine, docs, base, declaredType, own);
+        const again = fromScratch(machine, docs, base, declaredType, own);
         const ids = shuffle([...docs.keys()], rng);
         // Half of the reads demand each node in a random order, and the other half demand one node.
         for (const id of rng.chance(0.5) ? ids : ids.slice(0, 1)) {
@@ -428,9 +455,15 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
           }
         }
       } else if (what < 6) {
-        base = { ...base, names: change(base, rng, hostNames, hostValues) };
+        if (own !== undefined && selves !== undefined && rng.chance(0.5)) {
+          // A new `self` of one node, with the same context object of the host.
+          own.set(rng.pick(nodes), rng.pick(selves));
+          counts.selves += 1;
+        } else {
+          base = { ...base, names: change(base, rng, hostNames, hostValues) };
+          counts.data += 1;
+        }
         host.changeData(base);
-        counts.data += 1;
       } else if (what === 6) {
         // A change of data that changes no value: the same context object again.
         host.changeData(base);

package/src/parts.ts

@@ -41,10 +41,13 @@ export type Split =
   | { readonly ok: false; readonly reason: string; readonly at: readonly Key[] };
 
 class Bad {
-  constructor(
-    readonly reason: string,
-    readonly at: readonly Key[],
-  ) {}
+  readonly reason: string;
+  readonly at: readonly Key[];
+
+  constructor(reason: string, at: readonly Key[]) {
+    this.reason = reason;
+    this.at = at;
+  }
 }
 
 /** This function sets an own data property. Only the key `__proto__` needs `defineProperty`. */

package/src/providers.ts

@@ -150,6 +150,7 @@ function unionOf(types: readonly ValueType[]): ValueType {
 
 /** The state of one reading of a schema: the root, the issues and the definitions that it read. */
 class SchemaReader {
+  readonly root: unknown;
   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>();
@@ -158,7 +159,9 @@ class SchemaReader {
   /** 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) {}
+  constructor(root: unknown) {
+    this.root = root;
+  }
 
   issue(at: readonly Key[], reason: string): void {
     this.issues.push({ at, reason });

package/src/reference.ts

@@ -1,12 +1,27 @@
 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, atArgsOf, atRuleOf, circularOf, collectOf, equationType, lookupKind } from "./world.ts";
+import {
+  type AttributeDeclaration,
+  type CapsRule,
+  type CircularRule,
+  type Kind,
+  type TreeContract,
+  GENERATION_LIMIT,
+  atArgsOf,
+  atRuleOf,
+  circularOf,
+  collectOf,
+  documentKey,
+  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, AT_READERS, STD_EVALUATORS } from "./stdlib.ts";
 import { type EvalError, type Failed, type Result, Failure, describe, fail, ok, placed, thrown } from "./errors.ts";
 import {
   type AllOptions,
+  type Clause,
   type Effect,
   type EvalFn,
   type EvalInput,
@@ -281,6 +296,44 @@ function freeIn(root: Context, ctx: Context, path: readonly unknown[]): boolean
   return bound === Object.hasOwn(root.names, key) && (!bound || Object.is(ctx.names[key], root.names[key]));
 }
 
+/** The clauses of one active `handle`, as SPEC tells: the frame around it, and if its body has ended. */
+interface RefFrame {
+  readonly clauses: readonly Clause[];
+  readonly outer: RefFrame | undefined;
+  /** The list of the effects of the evaluation: a frame of another evaluation has ended. */
+  readonly owner: unknown;
+  ended: boolean;
+}
+
+/** The key of the frame of a context. */
+const REF_FRAME = /* @__PURE__ */ Symbol("coeval.reference.frame");
+
+/** This function gives the frame of a context. */
+function refFrame(ctx: Context): RefFrame | undefined {
+  return (ctx as Context & { readonly [REF_FRAME]?: RefFrame })[REF_FRAME];
+}
+
+/**
+ * This function finds the clause for an effect (HANDLE.DO, HANDLE.FORWARD). An effect without a capability gets no clause
+ * (HANDLE.NARROW). A clause of a frame that has ended gives `#CAP!` (HANDLE.ENDED).
+ */
+function clauseAt(env: Env, ctx: Context, kind: Cap, place: readonly Key[]): Clause | Failed | undefined {
+  let frame = refFrame(ctx);
+  if (frame === undefined) return undefined;
+  const keys = typeof kind === "string" ? kind.split(".") : kind;
+  const machine = env.machine;
+  const allowed = machine.permits === undefined ? permits(ctx.caps, keys) : machine.permits(ctx.caps, keys, ctx);
+  if (!allowed) return undefined;
+  for (; frame !== undefined; frame = frame.outer) {
+    for (const clause of frame.clauses) {
+      if (!permits([clause.op], keys)) continue;
+      if (frame.ended || frame.owner !== env.effects) return fail("#CAP!", `The handler of the effect ${keys.join(".")} has ended.`, { place });
+      return clause;
+    }
+  }
+  return undefined;
+}
+
 /**
  * This function causes an effect when the capabilities permit it (RUN.CAP, CAP.HOOK). It records the effect with its
  * address (RUN.ADDRESS) and its outcome (RUN.OUTCOME). The mock answers the effect at once (RUN.MOCK). Without a
@@ -300,6 +353,8 @@ function cause(env: Env, ctx: Context, kind: Cap, payload: unknown, place: reado
 function causeFromEvaluator(env: Env, ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result {
   const text = typeof kind === "string" ? kind : kind.join(".");
   if (env.running) return fail("#CALC!", `The effect ${text} needs a runner: in a run, the host does each effect.`, { place });
+  const clause = clauseAt(env, ctx, kind, place);
+  if (clause !== undefined) return "ok" in clause ? clause : drive(clause.answer(payload), place, text);
   return cause(env, ctx, kind, payload, place);
 }
 
@@ -309,6 +364,8 @@ function causeFromEvaluator(env: Env, ctx: Context, kind: Cap, payload: unknown,
  * (RUN.OUTCOME).
  */
 function* causeAndWait(env: Env, ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Steps {
+  const clause = clauseAt(env, ctx, kind, place);
+  if (clause !== undefined) return "ok" in clause ? clause : yield* clause.answer(payload);
   if (!env.running) return cause(env, ctx, kind, payload, place);
   const effect = recordEffect(env, ctx, kind, payload, place);
   if ("ok" in effect) return effect;
@@ -466,6 +523,17 @@ function evalInput(env: Env, seen: Seen, at: At): EvalInput {
   };
 }
 
+/** This function evaluates a part under a frame: the part also gets the kinds of the clauses (CAP.GRANT). */
+function* handledAt(env: Env, part: At, clauses: readonly Clause[]): Steps {
+  const frame: RefFrame = { clauses, outer: refFrame(part.ctx), owner: env.effects, ended: false };
+  const ctx = { ...part.ctx, caps: [...part.ctx.caps, ...clauses.map((clause) => clause.op)], [REF_FRAME]: frame };
+  try {
+    return yield* stepsAt(env, { ...part, ctx });
+  } finally {
+    frame.ended = true;
+  }
+}
+
 function runInput(env: Env, seen: Seen, at: At): RunInput {
   const { split, doc } = seen;
   const parts: RunPart[] = split.parts.map((slot) => {
@@ -475,6 +543,7 @@ function runInput(env: Env, seen: Seen, at: At): RunInput {
       path: slot.path,
       ...(name === undefined ? {} : { name }),
       evaluate: (given?: Context) => stepsAt(env, partAt(seen, at, slot, given)),
+      handled: (clauses: readonly Clause[]) => handledAt(env, partAt(seen, at, slot, undefined), clauses),
     };
   });
   const fill = (items: readonly unknown[]): unknown => (split.parts.length === 0 ? doc.value : split.fill(items));
@@ -882,6 +951,55 @@ function collectIn(node: RefNode, name: string, declared: unknown): Result {
   return visit(node) ?? acc;
 }
 
+/** TREE.HIGHER-DEPTH: the depth of each root of a generated document in the reference. */
+const refGenerations = /* @__PURE__ */ new WeakMap<RefNode, number>();
+
+/** TREE.HIGHER-DEPTH: the depth of the nearest root of a generated document at or above a node of the reference, or 0. */
+function generationIn(node: RefNode): number {
+  for (let at: RefNode | undefined = node; at !== undefined; at = at.up) {
+    const depth = refGenerations.get(at);
+    if (depth !== undefined) return depth;
+  }
+  return 0;
+}
+
+/**
+ * TREE.HIGHER: a higher-order attribute. The equation gives a document as data, and the document evaluates with the
+ * node as `self`. The reference compiles each document again, thus a structural key is not a part of the meaning.
+ */
+function higherOf(node: RefNode, name: string, term: Json): Result {
+  const value = equationOf(node, term, {});
+  if (!value.ok) return value;
+  const text = nameOfAttribute(node, name);
+  if (documentKey(value.value) === undefined) return fail("#VALUE!", `The equation of the higher-order attribute ${text} gives a value that is not JSON data.`);
+  const depth = generationIn(node) + 1;
+  if (depth > GENERATION_LIMIT) return fail("#DEPTH!", `The higher-order attribute ${text} is under more than ${GENERATION_LIMIT} generated documents.`);
+  const root = equationOf(node, value.value as Json, {});
+  if (!root.ok) return root;
+  const made = refNodeOf(root.value);
+  if (made === undefined) return fail("#VALUE!", `The document of the higher-order attribute ${text} gives no node of the tree.`);
+  refGenerations.set(made, depth);
+  return root;
+}
+
+/** TREE.FORWARD: the last rung. The attribute `forwards` gives a node, and that node answers through its own ladder. */
+function forwardOf(node: RefNode, name: string): Result | undefined {
+  const target: unknown = node.contract?.forwards;
+  if (target === undefined || target === name) return undefined;
+  const text = nameOfAttribute(node, name);
+  if (typeof target !== "string") return fail("#VALUE!", `The attribute ${text} has a contract with a bad field forwards. It must be a text.`);
+  const value = attributeOf(node, target);
+  if (value === undefined || !value.ok) return value;
+  const to = refNodeOf(value.value);
+  if (to === undefined) return fail("#VALUE!", `The attribute ${target} that ${text} forwards to gives no node of a tree.`);
+  if (!refGenerations.has(to)) {
+    const depth = generationIn(node) + 1;
+    if (depth > GENERATION_LIMIT) return fail("#DEPTH!", `The attribute ${text} forwards through more than ${GENERATION_LIMIT} generated documents.`);
+    refGenerations.set(to, depth);
+  }
+  return attributeOf(to, name);
+}
+
 /**
  * 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.
@@ -912,9 +1030,11 @@ const REF_RUNGS: readonly (readonly [AttributeRung, (node: RefNode, name: string
       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, {});
+      if (declared?.default !== undefined) return equationOf(node, declared.default, {});
+      return declared?.higher === undefined ? undefined : higherOf(node, name, declared.higher);
     },
   ],
+  ["forward", forwardOf],
 ];
 
 /** TREE.LADDER: the answer of the first rung that answers, or `undefined`. */