@mark1russell7/coeval 0.10.0 → 0.12.0

package/package.json

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

@@ -363,6 +363,8 @@ export function context(parts: Partial<Context> = {}): Context {
 }
 
 const MAX_COLLAPSE = 64;
+/** The reason of a resolution that reaches the bound of collapses without a cycle that it found (DEREF.CHAIN-REASON). It is a plain string, thus a bundle drops it (PKG.PURE). */
+const CHAIN_REASON = "The path follows more than 64 references. One resolution follows at most 64.";
 const NO_HOPS: readonly Hop[] = /* @__PURE__ */ Object.freeze([]);
 
 /** A value that can be a reference document: a record with the type `ref`. The full check comes after. */
@@ -560,7 +562,8 @@ function walkersOf(nav: Navigator, path: readonly unknown[]): KnownWalkers | und
  * - `#NAME?`: the root `names` has no such name.
  * - `#N/A`: a step reaches nothing.
  * - `#STEP?`: a step is not a key and not a step document.
- * - `#CYCLE!`: the references form a cycle.
+ * - `#CYCLE!`: the references form a cycle, or the resolution follows more than 64 references. The reason tells
+ *   which (DEREF.CHAIN-REASON).
  *
  * @param nav - The world and the code of the evaluators.
  * @param ctx - The context.
@@ -590,15 +593,21 @@ function resolveFully(nav: Navigator, ctx: Context, path: readonly unknown[], ho
   const done = hops ?? NO_HOPS;
   const failed = (code: ResolveCode | ErrorCode, reason: string): Resolution => ({ ok: false, code, reason, hops: done });
   let collapses = 0;
+  // The references whose paths are in evaluation. A reference that is in this list again closes a cycle.
+  let open: object[] | undefined;
   const adopt = nav.adopt ?? ((value: unknown): Thing => value);
 
   const collapse = (thing: Thing): Resolution => {
     let here = thing;
     if (nav.plain === true) return { ok: true, thing: here, hops: done };
     while (isRef(here)) {
+      if (open?.includes(here) === true) return failed("#CYCLE!", "The references form a cycle.");
       collapses += 1;
-      if (collapses > MAX_COLLAPSE) return failed("#CYCLE!", "The references form a cycle.");
+      if (collapses > MAX_COLLAPSE) return failed("#CYCLE!", CHAIN_REASON);
+      open ??= [];
+      open.push(here);
       const inner = walk(here.value, undefined);
+      open.pop();
       if (!inner.ok) return inner;
       here = adopt(inner.thing);
       hops?.push({ step: "collapse", thing: here, by: "collapse" });

package/src/evaluate.ts

@@ -156,6 +156,22 @@ function granted(ctx: Context): Context {
   return out;
 }
 
+/**
+ * This function gives the context in which the runtime resolves a path of compiled code (CAP.CAPS-GRANT). A path from
+ * the root `caps` reads the capabilities that both the context and its grant permit, and a context without a grant
+ * reads none. Thus a context that compiled code widened gives the capabilities of its document, and a context that it
+ * narrowed keeps its own list. Each other path, and each context whose grant is its own list, keeps the same context.
+ */
+function readable(ctx: Context, path: readonly unknown[]): Context {
+  if (path[0] !== "caps") return ctx;
+  const grant = (ctx as Granted)[GRANT];
+  if (grant === ctx.caps) return ctx;
+  const caps = grant === undefined ? NO_CAPS : intersectCaps(ctx.caps, grant);
+  if (caps === ctx.caps) return ctx;
+  const out: Granted = { ...ctx, caps, [GRANT]: caps };
+  return out;
+}
+
 /**
  * This function gives the context of a part of a function evaluator. It is the context that the evaluator gives,
  * narrowed by the context of the document (CAP.NARROW), with the grant of its capabilities.
@@ -785,17 +801,13 @@ export interface StopSignal {
   addEventListener(type: "abort", listener: () => void, options?: { readonly once?: boolean }): void;
 }
 
-/** The options of a run. */
-export interface RunOptions {
+/**
+ * The options of `plan.run`. A plan keeps the verb and the declared type of its `prepare`, thus these options do not
+ * have them (PLAN.RUN-OPTIONS).
+ */
+export interface PlanRunOptions {
   /** The host code that does each effect. Without it, an effect gives its payload, as in an evaluation. */
   readonly perform?: Perform;
-  /** The type of a bare root value. */
-  readonly declaredType?: string;
-  /**
-   * The verb of `run`, for example `format`. The default is `eval` (VERB.PREPARE). A plan keeps the verb of its
-   * `prepare`, thus `plan.run` does not read this option.
-   */
-  readonly verb?: string;
   /** A signal of the host. When it aborts, the run stops with `#ABORT`. */
   readonly signal?: StopSignal;
   /**
@@ -805,6 +817,14 @@ export interface RunOptions {
   readonly reads?: Read[];
 }
 
+/** The options of `run`: the options of `plan.run`, and the type of a bare root value and the verb for `prepare`. */
+export interface RunOptions extends PlanRunOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The verb of `run`, for example `format`. The default is `eval` (VERB.PREPARE). */
+  readonly verb?: string;
+}
+
 /** The options of an evaluation of a plan. */
 export interface EvalOptions {
   /** A list that gets each effect, in its order. */
@@ -892,15 +912,18 @@ class Session implements Runtime {
     return this.reading !== undefined;
   }
 
+  /** This function resolves a path. A path from the root `caps` reads the capabilities through the grant (CAP.CAPS-GRANT). */
   resolve(ctx: Context, path: readonly unknown[], options?: ResolveOptions): Resolution {
-    return this.read(ctx, path, undefined, options);
+    return this.read(readable(ctx, path), path, undefined, options);
   }
 
   /**
    * This function resolves a compiled path (PLAN.PATH). Without a list of reads and without a trace, the compiled
-   * path answers at once. Each other resolution records its read, as `resolve` does.
+   * path answers at once. Each other resolution records its read, as `resolve` does. A path from the root `caps` reads
+   * the capabilities through the grant (CAP.CAPS-GRANT).
    */
-  resolvePath(ctx: Context, compiled: CompiledPath): Resolution {
+  resolvePath(given: Context, compiled: CompiledPath): Resolution {
+    const ctx = readable(given, compiled.path);
     if (this.reading === undefined && !this.traced && compiled.nav === this.machine) return compiled.resolve(ctx);
     return this.read(ctx, compiled.path, compiled, undefined);
   }
@@ -1303,7 +1326,7 @@ export interface Plan {
    * @param options - The host code that does the effects, a signal to stop the run and a list that gets the reads.
    * @returns The result, when the run ends.
    */
-  run(context?: Context, options?: RunOptions): Promise<Result>;
+  run(context?: Context, options?: PlanRunOptions): Promise<Result>;
 }
 
 interface Compiler {
@@ -1471,7 +1494,8 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
   } catch (error) {
     return failingWith(c, meta, placed(thrown(error, `the evaluator ${name}`), place));
   }
-  const done = finish(c, meta, placedCode(inner, place, name), undefined);
+  // Code that cannot fail needs no place and no catch, and it does not read the context of its grant (PLAN.TOTAL).
+  const done = finish(c, meta, TOTAL.has(inner) ? inner : placedCode(inner, place, name), undefined);
   if (frees === undefined || kind === undefined || !pureCode(c, envelope, kind, typePath, name, quick)) return done;
   const free = freeOf(doc, kind, split.parts, frees);
   if (free === undefined) return done;
@@ -1721,6 +1745,24 @@ function copyPlain(value: unknown, memo: Map<object, unknown>): unknown {
  * the split of the value. Thus a plan with these helpers keeps only its code.
  */
 
+/**
+ * The compiled code that cannot fail (PLAN.TOTAL). Such code gives a value and throws nothing. It does not read its
+ * context or its runtime. Only the kits of the kernel mark code, thus the code of a host always gets its grant.
+ */
+const TOTAL: WeakSet<Code> = /* @__PURE__ */ new WeakSet();
+
+/**
+ * This function marks compiled code that cannot fail (PLAN.TOTAL). Then `compileNode` does not wrap the code in
+ * `placedCode`, thus a literal costs one call. The kits of the kernel use it. The package does not export it.
+ *
+ * @param code - The code. It gives a value and throws nothing. It does not read its context or its runtime.
+ * @returns The same code.
+ */
+export function totalCode(code: Code): Code {
+  TOTAL.add(code);
+  return code;
+}
+
 /**
  * This function gives the code of a document: the code of its evaluator, with the place of each error and of each
  * exception. The code gets the context that its grant permits, thus a compiled parent cannot widen it (CAP.NARROW-CODE).
@@ -1952,7 +1994,7 @@ class CompiledPlan implements Plan {
     return this.code(ctx, s);
   }
 
-  run(context: Context = makeContext(), runOptions: RunOptions = {}): Promise<Result> {
+  run(context: Context = makeContext(), runOptions: PlanRunOptions = {}): Promise<Result> {
     const machine = this.machine;
     const ctx = rootContext(machine, context);
     const s = new Session(machine, true, this.traced, runOptions.perform, runOptions.signal, undefined, readingOf(runOptions.reads, ctx));

package/src/formula.ts

@@ -2,7 +2,7 @@ import { type Json, type Key, docEquals, isKey, isRecord } from "./doc.ts";
 import type { Kind, KindFacts, LazyRule, WorldEntry } from "./world.ts";
 import { type CompiledPath, type Context, type Resolution, compilePath, valueOfThing } 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 } from "./evaluate.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";
 import { type Domain, type ValueType, HEADER_KEYS, STD_DOMAINS, callable, fieldOf, fits, fnOf, holdsEnvelope, isPrecise, isUnknown, itemOf, join, member, stepType, typeText } from "./types.ts";
 import type { TypeInput, TypeRule } from "./typing.ts";
@@ -697,8 +697,9 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
 
   return {
     "formula.lit": compiled(({ doc }) => {
+      // A literal cannot fail, thus its code needs no place (PLAN.TOTAL).
       const result = ok(doc.value);
-      return () => result;
+      return totalCode(() => result);
     }),
 
     "formula.ref": compiled(({ doc, parts, fill, address, machine }) => {
@@ -718,7 +719,7 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
       // A step document without parts is its own value. A step document with parts gets the result of each part.
       if (parts.length === 0) {
         const same = ok(doc);
-        return () => same;
+        return totalCode(() => same);
       }
       return (ctx, rt) => {
         const values = valuesOf(parts, ctx, rt);

package/src/generate.ts

@@ -146,9 +146,11 @@ export function generate(world: World, options: GenerateOptions): unknown {
   const keys = options.keys ?? KEYS;
   const steps = options.steps ?? 2;
   const roots: readonly Root[] = options.roots ?? ROOTS;
+  // A kind with the verb step walks a step document. With a default of step, each other kind walks one too (GEN.STEPS).
+  const defaultStep = Object.hasOwn(world.defaults, "step");
   const stepTypes = types.filter((type) => {
     const found = lookupKind(world, type);
-    return found.ok && Object.hasOwn(found.kind.verbs, "step");
+    return found.ok && (defaultStep || Object.hasOwn(found.kind.verbs, "step"));
   });
   // A name under each namespace with a fallback that no evaluator knows, for example ["ops", "nope"].
   const unknownNames: readonly (readonly Key[])[] = Object.keys(world.kinds)
@@ -205,7 +207,10 @@ export function generate(world: World, options: GenerateOptions): unknown {
     return out;
   };
 
-  /** A path from a root (D10). It uses the names in scope, and sometimes a step document. */
+  /**
+   * A path from a root (D10). It uses the names in scope, and sometimes a step document. The kind of a step document
+   * has the verb `step`, or the default of the world for `step` serves it.
+   */
   const pathFor = (pos: Position, refKind: Kind | undefined): Json => {
     if (rng.chance(malformed)) return rng.pick<Json>(["names", [], { names: "a" }, ["nowhere", "a"]]);
     const others = roots.filter((name) => name !== "names");

package/src/index.ts

@@ -134,6 +134,7 @@ export {
   type Part,
   type Perform,
   type Plan,
+  type PlanRunOptions,
   type PrepareOptions,
   type Read,
   type Run,

package/src/world.ts

@@ -270,10 +270,28 @@ export interface World {
   readonly fallback?: Kind;
 }
 
-/** The result of a lookup of a type in the world. */
+/**
+ * The result of a lookup of a type in the world. The reasons of a failure:
+ *
+ * - `unknown`: the world has no entry for a key, and no fallback kind.
+ * - `cycle`: the aliases form a cycle. The lookup reached a path a second time.
+ * - `too-long`: the lookup followed more than 32 aliases without a path a second time (DEREF.CHAIN-REASON).
+ * - `not-a-kind`: the path reaches an entry of the wrong sort. An example is an alias whose target is not in the world.
+ * - `computed`: the type is a computed type, thus it has no keys.
+ */
 export type Lookup =
   | { readonly ok: true; readonly kind: Kind; readonly path: readonly Key[]; readonly aliases: number }
-  | { readonly ok: false; readonly reason: "unknown" | "cycle" | "not-a-kind" | "computed"; readonly path: readonly Key[] };
+  | { readonly ok: false; readonly reason: "unknown" | "cycle" | "too-long" | "not-a-kind" | "computed"; readonly path: readonly Key[] };
+
+/** The most aliases that one lookup follows (WORLD.ALIAS-LIMIT). */
+const MAX_ALIASES = 32;
+
+/** This function tells if two paths of a lookup have the same keys. */
+function samePath(a: readonly Key[], b: readonly Key[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let index = 0; index < a.length; index += 1) if (a[index] !== b[index]) return false;
+  return true;
+}
 
 /**
  * This function tells if an entry of the world is a kind.
@@ -312,7 +330,8 @@ function entryAt(entries: Readonly<Record<string, WorldEntry>>, key: Key): World
 
 /**
  * This function finds the kind that a type names. It walks the path from the root of the world, one key at a
- * time. An alias on the way is followed until a kind answers (collapse). A cycle of aliases stops the lookup. In a
+ * time. An alias on the way is followed until a kind answers (collapse). A cycle of aliases stops the lookup, and so
+ * does a chain of more than 32 aliases. In a
  * namespace with a fallback, a key that the namespace does not have gets the fallback kind. In an open world, a first
  * key that the world does not have gets the fallback kind of the world.
  *
@@ -325,6 +344,8 @@ export function lookupKind(world: World, type: TypeRef): Lookup {
   if (start === undefined) return { ok: false, reason: "computed", path: [] };
   let path: readonly Key[] = start;
   let aliases = 0;
+  // The paths before each alias. The same path again closes a cycle, because the lookup of a path is always the same.
+  let seen: (readonly Key[])[] | undefined;
   for (;;) {
     let entries = world.kinds;
     let fallback: Kind | undefined = world.fallback;
@@ -339,12 +360,16 @@ export function lookupKind(world: World, type: TypeRef): Lookup {
       }
       if (isAlias(entry)) {
         aliases += 1;
-        if (aliases > 32) return { ok: false, reason: "cycle", path };
+        if (aliases > MAX_ALIASES) return { ok: false, reason: "too-long", path };
         const target = entry.value.slice(1);
         if (entry.value[0] !== "world" || !target.every((item) => typeof item === "string" || typeof item === "number")) {
           return { ok: false, reason: "not-a-kind", path };
         }
+        seen ??= [];
+        seen.push(path);
         path = [...(target as readonly Key[]), ...path.slice(index + 1)];
+        const next = path;
+        if (seen.some((before) => samePath(before, next))) return { ok: false, reason: "cycle", path };
         followed = true;
         break;
       }