@mark1russell7/coeval 0.4.2 → 0.5.0

package/package.json

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

@@ -74,8 +74,14 @@ export type Agreement =
 /**
  * This function tells if two values are the same for `agree`. Lists and plain records compare item by item and field
  * by field, and the order of the fields does not matter. Each other leaf compares with `Object.is`, thus `-0` is not
- * `0`, and `NaN` is `NaN`. Two closures of `fn` are the same when they have the same parameters. Two `Held` values
- * are the same when their errors have the same code and place. Identity is not compared.
+ * `0`, and `NaN` is `NaN`. The identity of a list or of a plain record is not compared.
+ *
+ * Two closures of `fn` are the same when they have the same parameters. Two `Held` values are the same when their
+ * errors have the same code and place. Each other object is the same only as itself, unless the rule of the caller
+ * tells otherwise.
+ *
+ * `docEquals` uses the same rules for lists, plain records and the other objects. It has no rules for closures, for
+ * `Held` values and for a rule of the caller. Thus two closures are equal there only when they are the same function.
  *
  * @param a - The first value.
  * @param b - The second value.

package/src/doc.ts

@@ -221,9 +221,17 @@ export function fromJson(value: unknown): Envelope | undefined {
 }
 
 /**
- * This function tells if two JSON values are equal. Equal values have the same texts, numbers and truth values,
- * the same items in the same order, and the same fields. The order of the fields does not matter. It does not use the stack for the
- * depth, thus a deep document cannot overflow it.
+ * This function tells if two values are equal. Plain JSON compares by its structure. Equal values have the same
+ * texts, numbers and truth values, the same items in the same order, and the same fields. The order of the fields
+ * does not matter. Each leaf compares with `Object.is`, thus `-0` is not `0`, and `NaN` is `NaN`.
+ *
+ * Only lists and plain records (`isRecord`) compare by their items and fields. Each other object compares by
+ * identity: a date, a map, a function and an instance of a class are equal only to themselves. Thus an early cutoff
+ * with this function does not keep a stale host value.
+ *
+ * The function does not use the stack for the depth, thus a deep document cannot overflow it. A cycle of lists or
+ * records does not make it loop. `sameValue` of `agree` uses the same rules, and it adds rules for closures and for
+ * a rule of the caller.
  *
  * @param a - The first value.
  * @param b - The second value.
@@ -231,15 +239,25 @@ export function fromJson(value: unknown): Envelope | undefined {
  */
 export function docEquals(a: unknown, b: unknown): boolean {
   const stack: [unknown, unknown][] = [[a, b]];
+  // The pairs of containers that the comparison already visits. It is made at the first pair of containers.
+  let seen: Map<object, Set<object>> | undefined;
   while (stack.length > 0) {
     const [x, y] = stack.pop() as [unknown, unknown];
     if (Object.is(x, y)) continue;
-    if (typeof x !== "object" || typeof y !== "object" || x === null || y === null) return false;
-    if (Array.isArray(x) !== Array.isArray(y)) return false;
-    if (Array.isArray(x)) {
+    const list = Array.isArray(x);
+    if (list !== Array.isArray(y)) return false;
+    // An object that is not a list and not a plain record is a host value: Object.is above compared it.
+    if (!list && (!isRecord(x) || !isRecord(y))) return false;
+    seen ??= new Map();
+    const pairs = seen.get(x as object);
+    if (pairs?.has(y as object) === true) continue;
+    if (pairs === undefined) seen.set(x as object, new Set([y as object]));
+    else pairs.add(y as object);
+    if (list) {
+      const xs = x as readonly unknown[];
       const ys = y as readonly unknown[];
-      if (x.length !== ys.length) return false;
-      for (let index = 0; index < x.length; index += 1) stack.push([x[index], ys[index]]);
+      if (xs.length !== ys.length) return false;
+      for (let index = 0; index < xs.length; index += 1) stack.push([xs[index], ys[index]]);
       continue;
     }
     const xr = x as Readonly<Record<string, unknown>>;

package/src/errors.ts

@@ -105,9 +105,11 @@ export class Failure extends Error {
  */
 export function isStackOverflow(error: unknown): boolean {
   try {
-    return error instanceof RangeError && /call stack/i.test(error.message);
+    // A regular expression that compiles near the limit of the stack throws a SyntaxError with the same message.
+    // Thus the test reads the message with includes, and it accepts a SyntaxError.
+    return (error instanceof RangeError || error instanceof SyntaxError) && error.message.includes("call stack");
   } catch {
-    // Near the limit of the stack, the test itself overflows: the regular expression throws a SyntaxError.
+    // Near the limit of the stack, the test itself can overflow.
     return true;
   }
 }

package/src/evaluate.ts

@@ -1,7 +1,7 @@
 import { type Envelope, type Json, type Key, type TypeRef, isEnvelope, typeName } from "./doc.ts";
-import { type Split, pathMatches, splitParts } from "./parts.ts";
+import { type Split, partsOf, pathMatches } from "./parts.ts";
 import { ask, type Answer } from "./ladder.ts";
-import { type CapsRule, type Lookup, type Side, type World, lookupKind } from "./world.ts";
+import type { CapsRule, Kind, Side, World } from "./world.ts";
 import { type ErrorCode, type EvalError, type Result, fail, ok, placed, thrown, describe } from "./errors.ts";
 import {
   type Cap,
@@ -428,6 +428,7 @@ export type Runner = RunFn | CompiledRunner;
  *
  * - `maxDepth`: the deepest nesting of documents. The default is 1000.
  * - `permits`: the rule of the host for an effect. The default is the function `permits` on the capabilities.
+ * - `known`: the names that the evaluators know, for `check`. Without it, `check` does not check such names.
  */
 export interface Machine extends Navigator {
   readonly evaluators: Readonly<Record<string, Evaluator>>;
@@ -435,6 +436,16 @@ export interface Machine extends Navigator {
   readonly runners?: Readonly<Record<string, Runner>>;
   readonly maxDepth?: number;
   readonly permits?: (caps: readonly Cap[], kind: readonly Key[], context: Context) => boolean;
+  /**
+   * This function tells if an evaluator knows the name in the path of a kind. An example is the operation
+   * `["ops", "add"]` of a formula language: a fallback kind names it, and the evaluator finds it in a table.
+   * `check` asks it for each document with an evaluator. The function must be pure.
+   *
+   * @param path - The keys of the kind of the document, after each alias.
+   * @param evaluator - The name of the evaluator that the ladder gives the document.
+   * @returns `true` when the evaluator knows the name, or else the reason of the `#NAME?` that a run gives.
+   */
+  readonly known?: (path: readonly Key[], evaluator: string) => true | string;
 }
 
 /** One evaluation in a trace. The children are the evaluations of its parts, in the order that they started. */
@@ -894,12 +905,12 @@ function finish(c: Compiler, meta: Meta, code: Code, run: RunCode): { readonly c
  * This function finds the evaluator of the verb `eval` without the record of the rungs, for a compilation without a
  * trace. It gives the same evaluator as `ask`: the own entry, then the kind, then the default of the world.
  */
-function evaluatorOf(world: World, envelope: Envelope | undefined, found: Lookup): { readonly name?: string; readonly unknown: boolean } {
+function evaluatorOf(world: World, envelope: Envelope | undefined, kind: Kind | undefined): { readonly name?: string; readonly unknown: boolean } {
   const own = envelope?.own;
   const ownName = own !== undefined && Object.hasOwn(own, "eval") ? own["eval"] : undefined;
   if (ownName !== undefined) return { name: ownName, unknown: false };
-  if (!found.ok) return { unknown: true };
-  const verbs = found.kind.verbs;
+  if (kind === undefined) return { unknown: true };
+  const verbs = kind.verbs;
   const name = Object.hasOwn(verbs, "eval") ? verbs["eval"] : Object.hasOwn(world.defaults, "eval") ? world.defaults["eval"] : undefined;
   return name === undefined ? { unknown: false } : { name, unknown: false };
 }
@@ -908,17 +919,17 @@ function evaluatorOf(world: World, envelope: Envelope | undefined, found: Lookup
 const NO_META: Meta = Object.freeze({ path: [], doc: { type: "?", value: null }, declared: false, answer: NO_ANSWER, side: "derive" });
 
 function compileNode(c: Compiler, value: unknown, place: readonly Key[], declared: string | undefined, depth: number, address = false): { readonly code: Code; readonly run: RunCode } {
-  const envelope = isEnvelope(value) ? (value as Envelope) : undefined;
-  const doc: Envelope = envelope ?? { type: declared ?? "?", value: value as Json };
-  const meta0: Meta = c.traced ? { path: place.map(String), doc, declared: envelope === undefined, answer: NO_ANSWER, side: "derive" } : NO_META;
-  if (envelope === undefined && declared === undefined) {
-    return failing(c, meta0, place, "#PART?", "The value has no envelope, and its position declares no type.");
+  const world = c.machine.world;
+  const read = partsOf(world, value, declared);
+  if (!read.ok) {
+    const meta: Meta = c.traced ? { path: place.map(String), doc: { type: "?", value: value as Json }, declared: true, answer: NO_ANSWER, side: "derive" } : NO_META;
+    return failing(c, meta, place, read.code, read.reason);
   }
+  const { doc, kind, split } = read;
+  const envelope = read.declared ? undefined : doc;
+  const meta0: Meta = c.traced ? { path: place.map(String), doc, declared: read.declared, answer: NO_ANSWER, side: "derive" } : NO_META;
   if (depth > c.maxDepth) return failing(c, meta0, place, "#DEPTH!", `The nesting is deeper than ${c.maxDepth} documents.`);
 
-  const world = c.machine.world;
-  const found = lookupKind(world, doc.type);
-  const kind = found.ok ? found.kind : undefined;
   let meta = meta0;
   let name: string | undefined;
   let unknown: boolean;
@@ -928,7 +939,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     name = answer.evaluator;
     unknown = answer.error === "unknown-kind";
   } else {
-    const quick = evaluatorOf(world, envelope, found);
+    const quick = evaluatorOf(world, envelope, kind);
     name = quick.name;
     unknown = quick.unknown;
   }
@@ -941,11 +952,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     return failing(c, meta, place, "#NOEVAL", `No rung gives an evaluator for ${kindText}.`);
   }
 
-  const split = splitParts(kind?.parts, doc.value);
-  if (!split.ok) {
-    const at = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
-    return failing(c, meta, place, "#VALUE!", `${split.reason}${at} The kind is ${kindText}.`);
-  }
+  if (!split.ok) return failing(c, meta, place, "#VALUE!", split.reason);
   const parts: CompiledPart[] = split.parts.map((slot) => {
     const item = slot.item;
     // The capability rules of the contract narrow the context of the part, thus no evaluator can forget them.
@@ -958,7 +965,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
       ? { key: slot.key, path: slot.path, code: compiled.code, run: compiled.run }
       : { key: slot.key, path: slot.path, name: header, code: compiled.code, run: compiled.run };
   });
-  const typePath = found.ok ? found.path : [];
+  const typePath = read.typePath ?? [];
   const input: CompileInput = {
     kind: kindText,
     typePath,

package/src/formula.ts

@@ -1,4 +1,4 @@
-import { type Json, isRecord } from "./doc.ts";
+import { type Json, type Key, isRecord } from "./doc.ts";
 import type { Kind, WorldEntry } from "./world.ts";
 import { type Context, type Resolution, valueOfThing } from "./deref.ts";
 import { type EvalError, type Failed, type Result, Failure, fail, ok, thrown } from "./errors.ts";
@@ -142,7 +142,7 @@ export function formulaKinds(): Readonly<Record<string, WorldEntry>> {
     },
     fn: {
       verbs: { eval: "formula.fn" },
-      parts: { shape: "record", fields: { body: term }, required: ["params", "body"] },
+      parts: { shape: "record", fields: { params: { shape: "list", item: { shape: "text" }, distinct: true }, body: term }, required: ["params", "body"] },
       scope: [{ names: { listAt: ["params"] }, in: [["body"]] }],
       summary: "A function: its parameters are names for its body.",
     },
@@ -474,18 +474,60 @@ export function formulaEvaluators(profile: FormulaProfile = {}): Readonly<Record
   };
 }
 
+/**
+ * This function makes the hook `known` of the formula kit for one profile (STATIC.KNOWN). The evaluator
+ * `formula.op` knows an operation of `lazy` or of `ops`. A profile whose `ops` is a function answers through a call
+ * of that function. A function that throws counts as an answer, because the run then gives `#CALC!`. The evaluator
+ * `formula.ext` knows an extension of `ext` and each standard extension. The hook knows each name of the other
+ * evaluators.
+ *
+ * @param profile - The operations and the extensions of the language.
+ * @returns The hook: `true`, or the reason of the `#NAME?` that the evaluator gives in a run.
+ */
+export function formulaKnown(profile: FormulaProfile = {}): (path: readonly Key[], evaluator: string) => true | string {
+  const hasOp = (name: string): boolean => {
+    if (profile.lazy !== undefined && Object.hasOwn(profile.lazy, name)) return true;
+    const ops = profile.ops;
+    if (ops === undefined) return false;
+    if (typeof ops !== "function") return Object.hasOwn(ops, name);
+    try {
+      return ops(name) !== undefined;
+    } catch {
+      return true;
+    }
+  };
+  const hasExt = (name: string): boolean => (profile.ext !== undefined && Object.hasOwn(profile.ext, name)) || Object.hasOwn(STD_EXT, name);
+  return (path, evaluator) => {
+    if (evaluator !== "formula.op" && evaluator !== "formula.ext") return true;
+    // The evaluators give the same reasons when they do not find the name.
+    const name = path.slice(1).join(".");
+    if (evaluator === "formula.op") return hasOp(name) ? true : `The language has no operation ${name}.`;
+    return hasExt(name) ? true : `The language has no extension ${name}.`;
+  };
+}
+
 /**
  * This function makes a machine for a formula language. The machine has the kinds and the evaluators of the
- * formula kit. It also has the kinds, the evaluators and the walkers that the language adds.
+ * formula kit. It also has the kinds, the evaluators and the walkers that the language adds. Its hook `known` comes
+ * from the profile (`formulaKnown`). A hook `known` of the language answers each name that the kit knows.
  *
  * @param profile - The operations and the rules of the language.
  * @param more - The parts of a machine that the language adds. Its kinds win over the kinds of the kit.
  * @returns The machine.
  */
 export function formulaMachine(profile: FormulaProfile = {}, more: Partial<Machine> = {}): Machine {
+  const kit = formulaKnown(profile);
+  // An evaluator or a runner of the language with the name of an evaluator of the kit replaces it, and the kit does not answer for it.
+  const replaced = (name: string): boolean => (more.evaluators !== undefined && Object.hasOwn(more.evaluators, name)) || (more.runners !== undefined && Object.hasOwn(more.runners, name));
+  const theirs = more.known;
+  const known = (path: readonly Key[], evaluator: string): true | string => {
+    const answer = replaced(evaluator) ? true : kit(path, evaluator);
+    return answer === true && theirs !== undefined ? theirs(path, evaluator) : answer;
+  };
   return {
     ...more,
     world: { kinds: { ...formulaKinds(), ...more.world?.kinds }, defaults: { ...more.world?.defaults } },
     evaluators: { ...formulaEvaluators(profile), ...more.evaluators },
+    known,
   };
 }

package/src/generate.ts

@@ -1,7 +1,7 @@
-import { type Json, type Key, docEquals, isEnvelope } from "./doc.ts";
+import { type Json, type Key, docEquals, isEnvelope, typePath } from "./doc.ts";
 import { type Kind, type ScopeRule, type Shape, type World, type WorldEntry, isAlias, isKind, isNamespace, lookupKind } from "./world.ts";
 import { pathMatches } from "./parts.ts";
-import { ROOTS } from "./deref.ts";
+import { ROOTS, type Root } from "./deref.ts";
 
 /** A source of random numbers with a seed. The same seed gives the same numbers. */
 export interface Random {
@@ -70,6 +70,10 @@ export interface GenerateOptions {
   readonly own?: readonly string[];
   /** The keys for the steps of a path after its root and its name. */
   readonly keys?: readonly Key[];
+  /** The roots that a path can start at. The default is each root. */
+  readonly roots?: readonly Root[];
+  /** The most steps of a path after its root and its name. The default is 2. */
+  readonly steps?: number;
 }
 
 /**
@@ -125,8 +129,9 @@ interface Scope {
 /**
  * This function builds a random document for a world from the contracts of its kinds. It reads the shapes of the
  * parts, the declared types, the permitted kinds and the names that the scope rules bind. Some choices are malformed
- * on purpose. Examples are an unknown kind, a value without its shape, a bare value without a type and a name that
- * nothing binds. The depth and the size have limits.
+ * on purpose, for example an unknown kind or an unknown name under a namespace with a fallback. Other examples are a
+ * value without its shape, a bare value without a type and a name that nothing binds. The depth and the size have
+ * limits.
  *
  * @param world - The world.
  * @param options - The seed, the types, the limits and the data of the leaves.
@@ -139,10 +144,19 @@ export function generate(world: World, options: GenerateOptions): unknown {
   const maxSize = options.maxSize ?? 24;
   const malformed = options.malformed ?? 0.05;
   const keys = options.keys ?? KEYS;
+  const steps = options.steps ?? 2;
+  const roots: readonly Root[] = options.roots ?? ROOTS;
   const stepTypes = types.filter((type) => {
     const found = lookupKind(world, type);
     return found.ok && 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)
+    .filter((key) => {
+      const entry = world.kinds[key];
+      return isNamespace(entry) && entry.fallback !== undefined;
+    })
+    .map((key) => [key, "nope"]);
   let size = 0;
 
   const kindOf = (type: readonly Key[]): Kind | undefined => {
@@ -194,11 +208,13 @@ export function generate(world: World, options: GenerateOptions): unknown {
   /** A path from a root (D10). It uses the names in scope, and sometimes a step document. */
   const pathFor = (pos: Position, refKind: Kind | undefined): Json => {
     if (rng.chance(malformed)) return rng.pick<Json>(["names", [], { names: "a" }, ["nowhere", "a"]]);
-    const root = pos.names.length > 0 && rng.chance(0.75) ? "names" : rng.pick(ROOTS.filter((name) => name !== "names"));
+    const others = roots.filter((name) => name !== "names");
+    const named = roots.includes("names") && pos.names.length > 0 && (others.length === 0 || rng.chance(0.75));
+    const root = named || others.length === 0 ? "names" : rng.pick(others);
     const path: Json[] = [root];
     if (root === "names") path.push(pickName(pos.names));
     if (root === "world") path.push(String(rng.pick(types)[0]));
-    for (let index = rng.int(3); index > 0; index -= 1) {
+    for (let index = rng.int(steps + 1); index > 0; index -= 1) {
       if (stepTypes.length > 0 && rng.chance(0.2)) {
         const type = rng.pick(stepTypes);
         const kind = kindOf(type);
@@ -332,9 +348,18 @@ export function generate(world: World, options: GenerateOptions): unknown {
     }
   };
 
-  /** A malformed document: an unknown kind, a bad shape, a bare value without a type, or a bad reference. */
+  /**
+   * A malformed document: an unknown kind, or an unknown name under a namespace with a fallback. It can also be a
+   * bad shape, a bare value without a type, or a bad reference.
+   */
   const brokenAt = (pos: Position): Json => {
     const roll = rng.int(5);
+    if (roll === 0 && unknownNames.length > 0 && rng.chance(0.5)) {
+      // The fallback kind answers the name, and its evaluator does not know it, for example an unknown operation.
+      const type = rng.pick(unknownNames);
+      const kind = kindOf(type);
+      return envelope(type, kind?.parts === undefined ? dataOf(type) : valueOf(kind.parts, [], pos, scopeOf(kind), type));
+    }
     if (roll === 0) return { type: rng.pick<Json>(["nothing", ["no", "such"]]), value: 1 };
     if (roll === 1) return pos.declared === undefined ? rng.pick<Json>([7, "bare", [1]]) : { type: "ref", value: ["names", "unbound"] };
     if (roll === 2) {
@@ -349,7 +374,11 @@ export function generate(world: World, options: GenerateOptions): unknown {
     size += 1;
     const leaf = pos.depth >= maxDepth || size >= maxSize;
     if (rng.chance(malformed)) return brokenAt(pos);
-    if (pos.declared !== undefined && rng.chance(leaf ? 0.7 : 0.3)) return dataOf([pos.declared]);
+    if (pos.declared !== undefined && rng.chance(leaf ? 0.7 : 0.3)) {
+      const bare = dataOf([pos.declared]);
+      // A bare value with the form of an envelope is a document of its own type, and the position must permit that type.
+      if (!isEnvelope(bare) || permitted(typePath(bare.type) ?? [], pos.kinds)) return bare;
+    }
     let candidates = types.filter((type) => permitted(type, pos.kinds) && (!leaf || leafKind(kindOf(type))));
     if (pos.hint !== undefined && rng.chance(0.6)) {
       const hinted = candidates.filter((type) => pos.hint?.some((hint) => hint.length === type.length && hint.every((key, index) => key === type[index])));

package/src/index.ts

@@ -95,7 +95,7 @@ export {
   worldThing,
 } from "./deref.ts";
 export { type Classification, type Shape, classify, tag } from "./classify.ts";
-export { type PartSlot, type Split, pathMatches, splitParts } from "./parts.ts";
+export { type DocParts, type PartSlot, type Split, partsOf, pathMatches, splitParts } from "./parts.ts";
 export {
   type AllOptions,
   type Code,
@@ -181,10 +181,11 @@ export {
   STD_EXT,
   formulaEvaluators,
   formulaKinds,
+  formulaKnown,
   formulaMachine,
   isClosure,
   jsTruthy,
 } from "./formula.ts";
-export { type Definitions, type ReferenceOptions, formulaDefinitions, reference } from "./reference.ts";
+export { type Definitions, type ReferenceOptions, STD_DEFINITIONS, formulaDefinitions, reference } from "./reference.ts";
 export { type AgreeOptions, type Agreement, type Tier, type TierResult, agree, sameValue } from "./agree.ts";
 export { type GenerateOptions, type Random, generate, random, typesOf } from "./generate.ts";

package/src/parts.ts

@@ -1,5 +1,5 @@
-import { type Json, type Key, docEquals, isEnvelope, isRecord, typeName, typePath } from "./doc.ts";
-import type { Shape } from "./world.ts";
+import { type Envelope, type Json, type Key, docEquals, isEnvelope, isRecord, typeName, typePath } from "./doc.ts";
+import { type Kind, type Shape, type World, lookupKind } from "./world.ts";
 
 /** One part of a value: its place in the value, the JSON of the part, and the type that its position declares. */
 export interface PartSlot {
@@ -56,6 +56,11 @@ function hasSlots(template: Template): boolean {
   return template.t !== "data";
 }
 
+/** This function tells if a shape holds only data: no value of the shape can hold a part. */
+function isData(shape: Shape): boolean {
+  return shape.shape === "none" || shape.shape === "text" || shape.shape === "number" || shape.shape === "one";
+}
+
 /** This function gives the reason why a value is not data of a shape, or `undefined` when it is. */
 function dataFault(spec: Extract<Shape, { readonly shape: "text" | "number" | "one" }>, item: Json): string | undefined {
   if (spec.shape === "text") return typeof item === "string" ? undefined : "The value must be a text.";
@@ -127,7 +132,9 @@ export function splitParts(shape: Shape | undefined, value: Json): Split {
         if (twice !== -1) throw new Bad("The items of the list must be different.", [...path, twice]);
       }
       const each: Shape = spec.item ?? { shape: "term", ...(spec.of === undefined ? {} : { of: spec.of }) };
-      return { t: "list", items: list.map((child, index) => walk(each, child, [...path, index])) };
+      const items = list.map((child, index) => walk(each, child, [...path, index]));
+      // A list of data is data, also when it is empty. Only a list that can hold parts gives null in the data.
+      return isData(each) ? { t: "data", value: item } : { t: "list", items };
     }
     if (!isRecord(item)) throw new Bad("The value must be a record.", path);
     if (spec.shape === "map") {
@@ -181,6 +188,55 @@ export function splitParts(shape: Shape | undefined, value: Json): Split {
   return { ok: true, parts, data: strip(template) ?? null, fill: (handles) => fillWith(template, handles) };
 }
 
+/**
+ * The kind and the parts of one document: what `partsOf` gives. `ok` is `false` only when the value is not a
+ * document: it has no envelope, and its position declares no type. A value without the shape of its kind gives a
+ * failed `split`.
+ */
+export type DocParts =
+  | {
+      readonly ok: true;
+      /** The document. A bare value gets the type that its position declares. */
+      readonly doc: Envelope;
+      /** `true` when the type came from the position and not from an envelope. */
+      readonly declared: boolean;
+      /** The kind, or `undefined` when the world has no kind for the type. Then the value is data. */
+      readonly kind: Kind | undefined;
+      /** The keys of the kind after each alias, or `undefined` without a kind. */
+      readonly typePath: readonly Key[] | undefined;
+      /**
+       * The split of the value by the shape of the kind. The reason of a failed split is the reason of the `#VALUE!`
+       * of an evaluation: it names the kind. Its `at` gives the keys from the value to the problem.
+       */
+      readonly split: Split;
+    }
+  | { readonly ok: false; readonly code: "#PART?"; readonly reason: string };
+
+/**
+ * This function reads one document by the contracts of the world. It finds the kind of the type. A bare value gets
+ * the type that its position declares. Then the function splits the value by the shape of the kind. The plan, the
+ * reference interpreter and the static kit read each document with this function. Thus they see the same parts.
+ *
+ * @param world - The world of the kinds.
+ * @param value - The document, or a bare value.
+ * @param declaredType - The type that the position of a bare value declares.
+ * @returns The document, its kind and its parts, or the reason why the value is not a document.
+ */
+export function partsOf(world: World, value: unknown, declaredType?: string): DocParts {
+  const envelope = isEnvelope(value) ? (value as Envelope) : undefined;
+  if (envelope === undefined && declaredType === undefined) return { ok: false, code: "#PART?", reason: "The value has no envelope, and its position declares no type." };
+  const doc: Envelope = envelope ?? { type: declaredType as string, value: value as Json };
+  const found = lookupKind(world, doc.type);
+  const kind = found.ok ? found.kind : undefined;
+  const split = splitParts(kind?.parts, doc.value);
+  const typePath = found.ok ? found.path : undefined;
+  if (split.ok) return { ok: true, doc, declared: envelope === undefined, kind, typePath, split };
+  // The reason names the place in the value and the kind, as each reader of the document gives it.
+  const where = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
+  const reason = `${split.reason}${where} The kind is ${typeName(doc.type)}.`;
+  return { ok: true, doc, declared: envelope === undefined, kind, typePath, split: { ok: false, reason, at: split.at } };
+}
+
 /**
  * This function tells if the path of a part matches a pattern of a scope rule. The key `"*"` of a pattern matches
  * each key.