@mark1russell7/coeval 0.23.0 → 0.24.1

package/src/syntax.ts

@@ -1,4 +1,4 @@
-import { type Json, type JsonRecord, type Key, isEnvelope, isRecord, typePath } from "./doc.ts";
+import { type Json, type JsonRecord, type Key, docEquals, isEnvelope, isRecord, typePath } from "./doc.ts";
 import { type Result, describe, fail, isStackOverflow, ok } from "./errors.ts";
 import type { EvalFn, Part } from "./evaluate.ts";
 import type { MachinePart } from "./merge.ts";
@@ -109,6 +109,18 @@ export interface SyntaxForm {
    * form `literal` takes no `wrap`, and a form `list` takes only `true`.
    */
   readonly wrap?: boolean | readonly string[];
+  /**
+   * The fields that take data with documents in it (L1c, D177), for example the clauses of `handle`. Such an
+   * argument is a list between brackets, a record between braces, or a document. A literal in it stays its data. A
+   * record of data has no key `type`. A name of `data` is a field of the form, and it is not in `wrap`.
+   */
+  readonly data?: readonly string[];
+  /**
+   * The name of a domain with a codec (K143, D141). A form `literal` of the kind `ext.domain` needs it. The text
+   * `date("2026-01-02")` then gives the value `{ domain: "date", data: "2026-01-02" }`. The syntax does not read the
+   * data: the codec of the machine reads it at evaluation. Each other form takes no `domain`.
+   */
+  readonly domain?: string;
 }
 
 /** The way that the arguments of a call form make the value of its document (D63). */
@@ -248,6 +260,10 @@ interface Form {
   readonly min: number;
   /** The arguments that take a document: `true` for each, or the names of the fields. */
   readonly wrap: boolean | ReadonlySet<string>;
+  /** The domain of a form literal of `ext.domain` (D141). */
+  readonly domain: string | undefined;
+  /** The fields that take data with documents in it (D177). */
+  readonly data: ReadonlySet<string>;
 }
 
 /** The type of a data envelope, and its key for a comparison with the path of a type. */
@@ -291,6 +307,8 @@ interface Compiled {
   readonly reserved: ReadonlySet<string>;
   readonly opWords: ReadonlySet<string>;
   readonly maxDepth: number;
+  /** `true` when a form has a field of data (D177). Such a field reads brackets and braces. */
+  readonly brackets: boolean;
 }
 
 const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -376,6 +394,14 @@ function compileConstructs(given: SyntaxConstructs | undefined, ops: Pick<Compil
   return { constructs, constructKinds };
 }
 
+/** This function examines the field `domain` of a call form (D141). A form `literal` of `ext.domain` needs a name, and each other form refuses it. */
+function compileDomain(given: SyntaxForm, args: SyntaxFormArgs): string | undefined {
+  const writes = args === "literal" && given.kind === "ext.domain";
+  if (writes && (typeof given.domain !== "string" || given.domain === "")) throw new TypeError(`The call form "${given.name}" of ext.domain needs the name of its domain.`);
+  if (!writes && given.domain !== undefined) throw new TypeError(`The call form "${given.name}" takes no domain: only a form literal of ext.domain has one.`);
+  return given.domain;
+}
+
 /** This function examines the field `wrap` of a call form (K159). A name that is not a field of the form throws. */
 function compileWrap(given: SyntaxForm, args: SyntaxFormArgs): boolean | ReadonlySet<string> {
   const wrap = given.wrap;
@@ -390,6 +416,17 @@ function compileWrap(given: SyntaxForm, args: SyntaxFormArgs): boolean | Readonl
 }
 
 /** This function gives the types of the data envelopes of a profile (K159), or `undefined` without them. */
+/** This function examines the field `data` of a call form (D177). Each name is a field of the form, and no name is in `wrap`. */
+function compileData(given: SyntaxForm, wrap: boolean | ReadonlySet<string>): ReadonlySet<string> {
+  const data = given.data ?? [];
+  if (data.length > 0 && given.fields === undefined) throw new TypeError(`The call form "${given.name}" takes data only with fields.`);
+  for (const name of data) {
+    if (given.fields?.includes(name) !== true) throw new TypeError(`The call form "${given.name}" has no field ${name} for its data.`);
+    if (wrap === true || (wrap !== false && wrap.has(name))) throw new TypeError(`The call form "${given.name}" has the field ${name} in wrap and in data.`);
+  }
+  return new Set(data);
+}
+
 function compileEnvelopes(given: SyntaxEnvelopes | undefined): Compiled["envelopes"] {
   if (given === undefined) return undefined;
   const out: { number?: EnvelopeKind; text?: EnvelopeKind; bool?: EnvelopeKind } = {};
@@ -423,10 +460,16 @@ function compileProfile(profile: SyntaxProfile): Compiled {
     if (!FORM_ARGS.includes(args)) throw new TypeError(`The call form "${given.name}" has the unknown arguments ${String(args)}.`);
     if ((args === "fields") !== (given.fields !== undefined) && args !== "named") throw new TypeError(`The call form "${given.name}" with the arguments ${args} ${args === "fields" ? "needs" : "takes no"} fields.`);
     if (given.min !== undefined && (args === "named" || args === "literal")) throw new TypeError(`The call form "${given.name}" with the arguments ${args} takes no min.`);
-    const form: Form = { name: given.name, type, args, fields: given.fields, min: given.min ?? given.fields?.length ?? 0, wrap: compileWrap(given, args) };
+    const wrap = compileWrap(given, args);
+    const form: Form = { name: given.name, type, args, fields: given.fields, min: given.min ?? given.fields?.length ?? 0, wrap, domain: compileDomain(given, args), data: compileData(given, wrap) };
     forms.set(form.name, form);
     addTo(formsByKind, key, form);
   }
+  // A field of data reads brackets and braces, thus no operator starts with one of them (D177).
+  const brackets = [...forms.values()].some((form) => form.data.size > 0);
+  for (const symbol of brackets ? [...ops.prefixSymbols, ...ops.binarySymbols] : []) {
+    if (/^[[\]{}]/.test(symbol)) throw new TypeError(`The operator "${symbol}" reads the text of a field of data.`);
+  }
   const compiled: Compiled = {
     ...ops,
     numbers: literals.numbers ?? true,
@@ -450,6 +493,7 @@ function compileProfile(profile: SyntaxProfile): Compiled {
     ...compileConstructs(profile.constructs, ops),
     reserved: new Set([...words.keys(), ...ops.opWords, ...roots]),
     maxDepth: profile.maxDepth ?? 256,
+    brackets,
   };
   compiledProfiles.set(profile, compiled);
   return compiled;
@@ -888,7 +932,7 @@ class Parser {
 
   /** This method stops at a token where a group or a list must end. A list can also continue with its separator. */
   protected noEnd(close: string, list: boolean): never {
-    const closer = close === ")" ? "parenthesis" : "brace";
+    const closer = closerName(close);
     const before = list ? `"${this.syn.separator}" or a ` : "";
     return this.stop(`A ${before}closing ${closer} is missing.`, this.pos, this.tokenLength());
   }
@@ -914,17 +958,33 @@ class Parser {
         this.pos += 1;
         return args;
       }
-      if (this.pos >= this.text.length) this.stop(`A closing ${close === ")" ? "parenthesis" : "brace"} is missing.`, open, 1);
+      if (this.pos >= this.text.length) this.stop(`A closing ${closerName(close)} is missing.`, open, 1);
       this.noEnd(close, true);
     }
   }
 
   /**
-   * This method reads the entries `key: expr` into a record: the arguments of a form `named` (SYNTAX.RECORD), or the
-   * entries between braces without a form (SYNTAX.RECORD-TEXT).
+   * This method reads the argument of a field of data (D177): a list between brackets, a record between braces, or a
+   * document. A literal in it stays its data.
+   */
+  private data(): Json {
+    this.skip();
+    const start = this.pos;
+    const c = this.text[start];
+    if (c !== "[" && c !== "{") return this.bound();
+    this.depth += 1;
+    if (this.depth > this.syn.maxDepth) this.stop(`The text is deeper than ${String(this.syn.maxDepth)} levels.`, start, 0);
+    const value = c === "[" ? this.argumentsOf(() => this.data(), "]") : this.entries(undefined, true);
+    this.depth -= 1;
+    return value;
+  }
+
+  /**
+   * This method reads the entries `key: expr` into a record. The record is the arguments of a form `named`
+   * (SYNTAX.RECORD), or the entries between braces (SYNTAX.RECORD-TEXT). It is also a record of data (D177).
    */
-  private entries(form: Form | undefined): Record<string, Json> {
-    const owner = form === undefined ? "record" : `form ${form.name}`;
+  private entries(form: Form | undefined, data = false): Record<string, Json> {
+    const owner = data ? "record of data" : form === undefined ? "record" : `form ${form.name}`;
     const value: Record<string, Json> = {};
     const entry = (): void => {
       this.skip();
@@ -936,9 +996,10 @@ class Parser {
         this.stop(`Each ${form === undefined ? "entry" : "argument"} of the ${owner} is a key, a ":" and a document.`, at, Math.max(end - at, this.tokenLength()));
       }
       if (form?.fields !== undefined && !form.fields.includes(key)) this.stop(`The form ${form.name} has no field ${key}.`, at, end - at);
+      if (data && key === "type") this.stop("A record of data has no key type, because the key type makes a document.", at, end - at);
       if (Object.hasOwn(value, key)) this.stop(`The ${owner} has the field ${key} two times.`, at, end - at);
       this.pos += 1;
-      const arg = this.bound();
+      const arg = data || form?.data.has(key) === true ? this.data() : this.bound();
       setOwn(value, key, form !== undefined && wraps(form, key) ? envelop(this.syn, arg) : arg);
     };
     this.argumentsOf(entry, form === undefined ? "}" : ")");
@@ -948,11 +1009,16 @@ class Parser {
   private call(name: string, start: number, nameLength: number): Json {
     const form = this.syn.forms.get(name);
     if (form?.args === "named") return opDoc(form, this.entries(form));
-    const args = this.argumentsOf(() => this.bound());
+    let index = 0;
+    const args = this.argumentsOf(() => {
+      const key = form?.fields?.[index];
+      index += 1;
+      return key !== undefined && form?.data.has(key) === true ? this.data() : this.bound();
+    });
     if (form?.args === "literal") {
       const [only] = args;
       if (args.length !== 1 || !isScalar(only)) this.stop(`The form ${name} takes one literal that JSON writes.`, start, this.pos - start);
-      return opDoc(form, only);
+      return opDoc(form, form.domain === undefined ? only : { domain: form.domain, data: only });
     }
     if (form !== undefined) {
       const most = form.fields?.length ?? Number.POSITIVE_INFINITY;
@@ -979,17 +1045,23 @@ class Parser {
 class End {}
 
 function hasBraces(syn: Compiled): boolean {
-  return syn.constructs.record !== undefined || syn.constructs.let !== undefined;
+  return syn.constructs.record !== undefined || syn.constructs.let !== undefined || syn.brackets;
+}
+
+/** This function gives the name of a closer in a message. */
+function closerName(close: string): string {
+  return close === ")" ? "parenthesis" : close === "]" ? "bracket" : "brace";
 }
 
 /** This function gives the closer of an opening bracket of a profile, or `undefined` for each other character. */
 function closerOf(syn: Compiled, c: string | undefined): string | undefined {
   if (c === "(") return ")";
+  if (c === "[" && syn.brackets) return "]";
   return c === "{" && hasBraces(syn) ? "}" : undefined;
 }
 
 function isCloser(syn: Compiled, c: string | undefined): boolean {
-  return c === ")" || (c === "}" && hasBraces(syn));
+  return c === ")" || (c === "]" && syn.brackets) || (c === "}" && hasBraces(syn));
 }
 
 /** This function gives the position after a quoted text at `at`, or after one other character. An open quote gives `Infinity`. */
@@ -1173,7 +1245,7 @@ type SubText = (child: unknown, path: readonly Key[], wrapped?: boolean) => Resu
 type Shape =
   | { readonly tag: "text"; readonly text: string }
   | { readonly tag: "op"; readonly op: Op; readonly terms: readonly unknown[] }
-  | { readonly tag: "call"; readonly name: string; readonly args: readonly (readonly [Key, unknown, boolean?])[]; readonly named?: boolean }
+  | { readonly tag: "call"; readonly name: string; readonly args: readonly (readonly [Key, unknown, boolean?, boolean?])[]; readonly named?: boolean }
   | { readonly tag: "path"; readonly segments: readonly (string | readonly [Key, unknown])[] }
   | { readonly tag: "bind"; readonly name: string; readonly doc: unknown }
   | ConstructShape
@@ -1256,6 +1328,8 @@ function refShape(syn: Compiled, value: unknown): Shape {
 
 function callName(syn: Compiled, keys: readonly Key[]): string | undefined {
   if (keys.length === 0 || !keys.every((key) => typeof key === "string" && NAME.test(key))) return undefined;
+  // `parse` reads the dots of a call name as field steps, thus a profile without them has no such text (D142).
+  if (keys.length > 1 && !syn.fields) return undefined;
   const name = keys.join(".");
   if (syn.forms.has(name) || syn.opWords.has(keys[0] as string)) return undefined;
   return syn.ops === true || syn.ops.has(name) ? name : undefined;
@@ -1281,17 +1355,24 @@ function wrappedShape(syn: Compiled, doc: unknown): Shape | undefined {
   return literal.tag === "text" ? literal : undefined;
 }
 
+/** This function tells if a value of `ext.domain` is a record with this domain and its data, and no other key. */
+function holdsDomain(value: unknown, domain: string): boolean {
+  return isRecord(value) && value["domain"] === domain && Object.hasOwn(value, "data") && Object.keys(value).length === 2;
+}
+
 function formShape(syn: Compiled, form: Form, value: unknown): Shape | undefined {
   if (form.args === "literal") {
-    if (!isScalar(value)) return undefined;
-    const literal = literalShape(syn, value);
+    if (form.domain !== undefined && !holdsDomain(value, form.domain)) return undefined;
+    const data = form.domain === undefined ? value : (value as Readonly<Record<string, unknown>>)["data"];
+    if (!isScalar(data)) return undefined;
+    const literal = literalShape(syn, data);
     return literal.tag === "text" ? { tag: "text", text: `${form.name}(${literal.text})` } : undefined;
   }
   if (form.args === "named") {
     if (!isRecord(value)) return undefined;
     const keys = Object.keys(value);
     if (form.fields !== undefined && !keys.every((key) => form.fields?.includes(key) === true)) return undefined;
-    return { tag: "call", name: form.name, args: keys.map((key) => [key, value[key], wraps(form, key)] as const), named: true };
+    return { tag: "call", name: form.name, args: keys.map((key) => [key, value[key], wraps(form, key), form.data.has(key)] as const), named: true };
   }
   if (form.fields === undefined) {
     if (!Array.isArray(value) || value.length < form.min) return undefined;
@@ -1302,7 +1383,7 @@ function formShape(syn: Compiled, form: Form, value: unknown): Shape | undefined
   const count = Object.keys(value).length;
   const present = form.fields.slice(0, count);
   if (count < form.min || present.length < count || !present.every((key) => Object.hasOwn(value, key))) return undefined;
-  return { tag: "call", name: form.name, args: present.map((key) => [key, value[key], wraps(form, key)] as const) };
+  return { tag: "call", name: form.name, args: present.map((key) => [key, value[key], wraps(form, key), form.data.has(key)] as const) };
 }
 
 /** This function tells if a record has exactly these two keys. */
@@ -1422,6 +1503,20 @@ function bracesText(syn: Compiled, record: JsonRecord, path: readonly Key[], sub
   return ok(`{${texts.value.map((text, index) => `${keyText(keys[index] as string)}: ${text}`).join(`${syn.separator} `)}}`);
 }
 
+/**
+ * This function writes the argument of a field of data (D177): a list between brackets, or a record between braces.
+ * The function `sub` writes a literal and a document. A record that is an envelope is a document.
+ */
+function dataText(syn: Compiled, value: unknown, path: readonly Key[], sub: SubText): Result<string> {
+  const each: SubText = (child, at) => dataText(syn, child, at, sub);
+  if (Array.isArray(value)) {
+    const texts = partTexts(value.map((item, index) => [index, item] as const), path, each);
+    return texts.ok ? ok(`[${texts.value.join(`${syn.separator} `)}]`) : texts;
+  }
+  // A record with the key type that is not an envelope goes to sub, which gives no text for it. The parser refuses its text.
+  return isRecord(value) && !isEnvelope(value) && !Object.hasOwn(value, "type") ? bracesText(syn, value, path, each) : sub(value, path);
+}
+
 /** This function writes a construct form (K145). */
 function constructText(syn: Compiled, shape: ConstructShape, sub: SubText): Result<string> {
   if (shape.tag === "record") return bracesText(syn, shape.entries, [], sub);
@@ -1468,8 +1563,8 @@ function printNode(syn: Compiled, doc: unknown, sub: SubText): Result<string> {
     return ok(texts.join("."));
   }
   const texts: string[] = [];
-  for (const [key, arg, wrapped] of shape.args) {
-    const result = sub(arg, [key], wrapped);
+  for (const [key, arg, wrapped, data] of shape.args) {
+    const result = data === true ? dataText(syn, arg, [key], sub) : sub(arg, [key], wrapped);
     if (!result.ok) return result;
     texts.push(shape.named === true ? `${keyText(String(key))}: ${result.value}` : result.value);
   }
@@ -1531,3 +1626,210 @@ export function syntaxFormat(profile: SyntaxProfile): MachinePart {
   };
   return { world: { defaults: { format: "syntax.format" } }, evaluators: { "syntax.format": code } };
 }
+
+// === The check of a profile ===
+
+/**
+ * The name of a finding of `checkSyntax` (D140). Each name holds a rule of the parser or the printer.
+ *
+ * - `invalid`: `parse` throws a `TypeError` for the profile. The reason is its message.
+ * - `operator`: the document of one operator does not come back. A negative precedence stops an infix operator,
+ *   because an expression starts at the precedence `0`. The kinds `ref`, `lit` and `ext.number` have their own text.
+ * - `grouping`: an operator with a second operator in a term does not come back. The parser reads a term from the
+ *   precedence plus `1`, and the printer compares precedences, thus a gap under `1` loses the tree. A postfix operator
+ *   at the precedence of a `right` infix operator loses it too.
+ * - `longest-match`: the printer writes two postfix operators without a space, and a longer symbol reads their text.
+ * - `word`: a word of `literals.words` does not read as its value. A word operator reads first, and a word that is
+ *   not a plain name has no token.
+ * - `root`: a root does not come back. A word operator reads first, and a literal word reads a root without steps.
+ * - `pattern`: a pattern of references reads a text that has another meaning, because the parser tries patterns first.
+ * - `form`: the document of a call form does not come back. A word operator reads first, the last form of a name
+ *   hides the others, and a `min` above the fields permits no text.
+ * - `call`: a name of `calls.ops` does not come back. A form of the name wins, a word operator reads first, and a name
+ *   with dots needs the field steps.
+ * - `separator`: the separator does not end an argument, and a neutral separator keeps the same document. An operator
+ *   reads first, the parser skips a space before it, or a name or a bracket at its start changes the term.
+ * - `construct`: the document of a construct form does not come back, for example two forms have one kind.
+ */
+export type SyntaxFindingCode = "invalid" | "operator" | "grouping" | "longest-match" | "word" | "root" | "pattern" | "form" | "call" | "separator" | "construct";
+
+/** One fault of a syntax profile: its name, its place in the profile and the reason (D140). */
+export interface SyntaxFinding {
+  /** The name of the fault. */
+  readonly code: SyntaxFindingCode;
+  /** The keys from the root of the profile to the entry, for example `["operators", 3]`. A default list has keys too. */
+  readonly place: readonly Key[];
+  /** The rule that the entry breaks, and the text that shows it. */
+  readonly reason: string;
+}
+
+/** The state of one check: the profile, its compiled form, a leaf document and the two functions that record a fault. */
+interface ProfileCheck {
+  readonly profile: SyntaxProfile;
+  readonly syn: Compiled;
+  readonly leaf: Json;
+  /** This function adds a finding. A pattern that reads the start of `text` takes the code and the place. */
+  readonly report: (code: SyntaxFindingCode, place: readonly Key[], text: string, reason: string) => void;
+  /** This function reports a document that breaks the law, and it tells if the law holds. `start` stands for a refused text. */
+  readonly keeps: (code: SyntaxFindingCode, place: readonly Key[], rule: string, doc: Json, start?: string) => boolean;
+}
+
+/** This function tells how a document breaks `parse(print(doc))`. It gives `undefined` when the document comes back. */
+function lawBreak(profile: SyntaxProfile, doc: Json): { readonly text: string | undefined; readonly why: string } | undefined {
+  const printed = print(profile, doc);
+  if (!printed.ok) return { text: undefined, why: printed.error.reason };
+  const text = printed.value;
+  const back = parse(profile, text);
+  if (back.ok) return docEquals(back.doc, doc) ? undefined : { text, why: `The text ${text} reads as ${JSON.stringify(back.doc)}.` };
+  return { text, why: `The text ${text} gives the issue: ${back.issues[0]?.message ?? ""}` };
+}
+
+/** This function gives the index of the first pattern that `parse` uses at the start of a text, or `-1`. */
+function patternAt(syn: Compiled, text: string): number {
+  return syn.patterns.findIndex(({ sticky }) => {
+    sticky.lastIndex = 0;
+    const match = sticky.exec(text)?.[0];
+    return match !== undefined && match !== "" && !/[A-Za-z0-9_$(]/.test(text[match.length] ?? "");
+  });
+}
+
+/** This function gives each small document of an operator with `term` in one term. A `flat` operator also has three terms. */
+function operatorDocs(op: Op, term: Json, leaf: Json): readonly Json[] {
+  if (op.fixity !== "infix") return [opDoc(op, [term])];
+  const pairs = [[term, leaf], [leaf, term]];
+  return (op.assoc === "flat" ? [...pairs, [term, leaf, leaf], [leaf, term, leaf]] : pairs).map((terms) => opDoc(op, terms));
+}
+
+/** This function gives the longer symbol that reads two postfix operators without a space, or `undefined`. */
+function gluedSymbol(syn: Compiled, outer: Op, inner: Op): string | undefined {
+  if (outer.word || inner.word || outer.fixity !== "postfix" || inner.fixity !== "postfix") return undefined;
+  const glued = inner.symbol + outer.symbol;
+  const read = syn.binarySymbols.find((symbol) => glued.startsWith(symbol));
+  return read === inner.symbol ? undefined : read;
+}
+
+function checkOperators({ profile, syn, leaf, keeps }: ProfileCheck): void {
+  const ops = (profile.operators ?? []).map((given) => (given.fixity === "prefix" ? syn.prefix : syn.binary).get(given.symbol) as Op);
+  const sound = ops.filter((op, index) => operatorDocs(op, leaf, leaf).every((doc) => keeps("operator", ["operators", index], `The operator ${op.symbol} does not come back.`, doc)));
+  for (const outer of sound) {
+    const place = ["operators", ops.indexOf(outer)];
+    for (const inner of sound) {
+      const glued = gluedSymbol(syn, outer, inner);
+      const code = glued === undefined ? "grouping" : "longest-match";
+      const rule = glued === undefined ? `The operator ${outer.symbol} with ${inner.symbol} in a term loses the tree.` : `The symbol ${glued} reads the postfix operators ${inner.symbol} and ${outer.symbol}.`;
+      for (const term of operatorDocs(inner, leaf, leaf)) for (const doc of operatorDocs(outer, term, leaf)) keeps(code, place, rule, doc);
+    }
+  }
+}
+
+function checkLiterals({ profile, syn, report }: ProfileCheck): void {
+  for (const [word, value] of syn.words) {
+    const back = parse(profile, word);
+    if (!back.ok || !docEquals(back.doc, envelop(syn, literalDoc(value)))) report("word", ["literals", "words", word], word, `The word ${word} does not read as its value.`);
+  }
+  for (const value of [0, -1, "a"]) {
+    const shape = literalShape(syn, value);
+    if (shape.tag === "text" && patternAt(syn, shape.text) >= 0) report("pattern", [], shape.text, `The literal ${shape.text} reads as a reference.`);
+  }
+}
+
+function checkRoots({ profile, syn, keeps }: ProfileCheck): void {
+  (profile.refs?.roots ?? DEFAULT_ROOTS).forEach((root, index) => {
+    for (const path of syn.fields ? [[root], [root, "x"]] : [[root]]) {
+      keeps("root", ["refs", "roots", index], `The root ${root} does not come back.`, { type: "ref", value: path }, path.join("."));
+    }
+  });
+}
+
+/** This function gives a value that a call form writes: the fewest arguments, and at least one. */
+function formValue(given: SyntaxForm, leaf: Json): Json {
+  const args = given.args ?? (given.fields === undefined ? "list" : "fields");
+  const least = Math.max(given.min ?? given.fields?.length ?? 0, 1);
+  if (args === "literal") return 1;
+  if (args === "list") return Array.from({ length: least }, () => leaf);
+  const keys = (given.fields ?? ["x"]).slice(0, args === "named" ? 1 : least);
+  return Object.fromEntries(keys.map((key) => [key, leaf]));
+}
+
+function checkCalls({ profile, syn, leaf, keeps }: ProfileCheck): void {
+  const calls = profile.calls ?? {};
+  (calls.forms ?? []).forEach((form, index) => {
+    keeps("form", ["calls", "forms", index], `The form ${form.name} does not come back.`, { type: typeOfKind(form.kind).type, value: formValue(form, leaf) });
+  });
+  // The dotted text of a call name needs the field steps. A profile with `ops: true` and no field steps has no dotted call.
+  if (syn.ops === true && syn.fields) keeps("call", ["calls", "ops"], "A call name with a dot does not come back.", { type: ["ops", "m", "p"], value: [leaf] });
+  if (typeof calls.ops === "boolean" || calls.ops === undefined) return;
+  calls.ops.forEach((name, index) => {
+    keeps("call", ["calls", "ops", index], `The call ${name} does not come back.`, { type: ["ops", ...name.split(".")], value: [leaf] });
+  });
+}
+
+/** This function writes two terms with the separator. It blames the separator only when a neutral separator keeps the document. */
+function checkSeparator({ profile, syn, leaf, report }: ProfileCheck): void {
+  if (syn.ops !== true && syn.ops.size === 0 && syn.forms.size === 0 && syn.constructKinds.size === 0) return;
+  const open: SyntaxProfile = { ...profile, calls: { ...profile.calls, ops: true } };
+  const neutral: SyntaxProfile = { ...profile, calls: { ...open.calls, separator: "\u0001" } };
+  const postfix = [...syn.binary.values()].filter((op) => op.fixity === "postfix").map((op) => opDoc(op, [leaf]));
+  const terms: Json[] = [leaf, { type: "ref", value: [syn.bare, "b c"] }, "a", 1, ...postfix];
+  const docs = terms.map((term): Json => ({ type: ["ops", "probe__"], value: [term, leaf] }));
+  const entries = { x: leaf, y: leaf };
+  const { record, let: bind } = syn.constructs;
+  if (record !== undefined) docs.push({ type: record, value: entries });
+  if (bind !== undefined) docs.push({ type: bind, value: { bind: entries, body: leaf } });
+  for (const doc of docs) {
+    const broken = lawBreak(neutral, doc) === undefined ? lawBreak(open, doc) : undefined;
+    if (broken !== undefined) report("separator", ["calls", "separator"], "", `The separator "${syn.separator}" does not end an argument. ${broken.why}`);
+  }
+}
+
+function checkConstructs({ syn, leaf, keeps }: ProfileCheck): void {
+  const entries = { x: leaf };
+  const values: Readonly<Record<keyof SyntaxConstructs, Json>> = { record: entries, let: { bind: entries, body: leaf }, fn: { params: ["x"], body: leaf }, call: { fn: leaf, args: [leaf] } };
+  for (const name of CONSTRUCTS) {
+    const type = syn.constructs[name];
+    if (type !== undefined) keeps("construct", ["constructs", name], `The form ${name} does not come back.`, { type, value: values[name] });
+  }
+}
+
+/**
+ * This function finds the faults of a syntax profile before a host uses it (SYNTAX.PROFILE-CHECK, D140). A fault is a
+ * document of an entry that breaks `parse(print(doc))`, or a text of an entry that reads another way. The function
+ * writes and reads one small document for each entry, for each pair of operators and for each root. Thus an empty list
+ * tells that these small documents come back. It does not prove the law for each document. `parse` and `print` do not
+ * call this function, thus it adds no cost to them.
+ *
+ * @param profile - The syntax profile.
+ * @returns At most one finding for each code and place, in the order of the operators, the literals, the references, the calls and the constructs.
+ * @throws An error of a `read` or a `write` function of a pattern.
+ */
+export function checkSyntax(profile: SyntaxProfile): readonly SyntaxFinding[] {
+  // A small `maxDepth` is a limit that the host chose, not a fault, thus each probe has the default limit.
+  const open: SyntaxProfile = { ...profile, maxDepth: 256 };
+  let syn: Compiled;
+  try {
+    syn = compileProfile(open);
+  } catch (error) {
+    if (error instanceof TypeError) return [{ code: "invalid", place: [], reason: error.message }];
+    throw error;
+  }
+  const found = new Map<string, SyntaxFinding>();
+  const report: ProfileCheck["report"] = (code, place, text, reason) => {
+    const index = patternAt(syn, text);
+    const finding: SyntaxFinding = index < 0 ? { code, place, reason } : { code: "pattern", place: ["refs", "patterns", index], reason: `The pattern reads the start of the text ${text}. ${reason}` };
+    const key = JSON.stringify([finding.code, finding.place]);
+    if (!found.has(key)) found.set(key, finding);
+  };
+  const keeps: ProfileCheck["keeps"] = (code, place, rule, doc, start = "") => {
+    const broken = lawBreak(open, doc);
+    if (broken !== undefined) report(code, place, broken.text ?? start, `${rule} ${broken.why}`);
+    return broken === undefined;
+  };
+  const check: ProfileCheck = { profile: open, syn, leaf: { type: "ref", value: [syn.bare, "a"] }, report, keeps };
+  checkOperators(check);
+  checkLiterals(check);
+  checkRoots(check);
+  checkCalls(check);
+  checkSeparator(check);
+  checkConstructs(check);
+  return [...found.values()];
+}

package/src/typing.ts

@@ -1,7 +1,7 @@
 import { type Envelope, type Key, isRecord, typeName } from "./doc.ts";
 import type { Machine } from "./evaluate.ts";
 import type { DocVisit, Issue, WorldIssue } from "./static.ts";
-import { type ValueType, domainOf, fits, isUnknown, typeIssues, typeText } from "./types.ts";
+import { type Domain, type ValueType, domainOf, fits, isPrecise, isUnknown, typeIssues, typeText } from "./types.ts";
 import { type Kind, type Shape, eachKind, kindAt } from "./world.ts";
 
 /*
@@ -116,6 +116,8 @@ export interface TypeProblem {
  * (TYPE.RULE).
  */
 export interface TypeRule {
+  /** `true` when the document reads a value from outside the document. The check then has no proof of its type (PLAN.GUARD-BOUNDARY). */
+  readonly read?: true;
   /**
    * This function tells the type that a part must have, and the types of the names for the part. The check asks it
    * before it types the part. The parts that give the names of a rule `keysAt` come first.
@@ -174,6 +176,33 @@ export interface Typed {
   readonly type: ValueType;
   /** The type that the position of the document needs, when it needs one. */
   readonly expected?: ValueType;
+  /** `true` when the rule of the document tells a read of a value that comes from outside the document. */
+  readonly read?: true;
+}
+
+/** A place where a promise of the types holds only with a test at run time (PLAN.GUARD). */
+export interface Boundary {
+  /** The keys from the root document to the document. */
+  readonly place: readonly Key[];
+  /** The type that the value of the place must have. */
+  readonly type: ValueType;
+}
+
+/**
+ * This function gives the boundaries of a check. A part with an imprecise type at a position that needs a type is a
+ * boundary. A read of a known type is a boundary too, because the check trusts the root types (PLAN.GUARD-BOUNDARY).
+ *
+ * @param typing - The places of a check of types.
+ * @param domains - The domains of the machine.
+ * @returns The boundaries, in the order of the document.
+ */
+export function boundariesOf(typing: { readonly places: readonly Typed[] }, domains?: Readonly<Record<string, Domain>>): readonly Boundary[] {
+  const found: Boundary[] = [];
+  for (const item of typing.places) {
+    if (item.expected !== undefined && item.expected !== "unknown" && !isPrecise(item.type, domains)) found.push({ place: item.place, type: item.expected });
+    else if (item.read === true && item.type !== "unknown") found.push({ place: item.place, type: item.type });
+  }
+  return found;
 }
 
 /** One document that the walk of a check visited, with what the pass of types needs. The package does not export it. */
@@ -238,7 +267,7 @@ function pathKey(path: readonly Key[]): string {
 export function ruleOf(machine: Machine, name: string | undefined): TypeRule | undefined {
   if (name === undefined || (machine.runners !== undefined && Object.hasOwn(machine.runners, name))) return undefined;
   const evaluator = Object.hasOwn(machine.evaluators, name) ? machine.evaluators[name] : undefined;
-  const rule = typeof evaluator === "object" && evaluator !== null ? (evaluator as { readonly type?: unknown }).type : undefined;
+  const rule = (typeof evaluator === "object" && evaluator !== null) || typeof evaluator === "function" ? (evaluator as { readonly type?: unknown }).type : undefined;
   return typeof rule === "object" && rule !== null && typeof (rule as TypeRule).synth === "function" ? (rule as TypeRule) : undefined;
 }
 
@@ -408,7 +437,8 @@ export function typePass(machine: Machine, nodes: readonly TypeNode[], verb: str
 
   const places = nodes.map((node, index) => {
     const want = needed[index];
-    const entry = { type: types[index] ?? "unknown", ...(want === undefined ? {} : { expected: want }) } as Typed;
+    const read = !node.marked && ruleOf(machine, node.evaluator)?.read === true;
+    const entry = { type: types[index] ?? "unknown", ...(want === undefined ? {} : { expected: want }), ...(read ? { read } : {}) } as Typed;
     // The keys of a place are made only when a reader asks for them, as a visit does.
     Object.defineProperty(entry, "place", { enumerable: true, get: () => node.visit.place });
     Object.defineProperty(entry, "at", { enumerable: true, get: () => node.visit.at });

package/src/world.ts

@@ -89,7 +89,13 @@ export interface ScopeRule {
 export type CapsRule =
   | { readonly rule: "same"; readonly in?: readonly (readonly Key[])[] }
   | { readonly rule: "mask"; readonly in?: readonly (readonly Key[])[] }
-  | { readonly rule: "only"; readonly caps: readonly Cap[]; readonly in?: readonly (readonly Key[])[] };
+  | { readonly rule: "only"; readonly caps: readonly Cap[]; readonly in?: readonly (readonly Key[])[] }
+  /**
+   * The parts that the rule covers get each capability that the value of the document holds at the path `from`. The
+   * code of the kind answers these effects with its own clauses (`RunPart.handled`), thus they do not reach the host.
+   * The key `"*"` in `from` steps into each item (CAP.GRANT, D146).
+   */
+  | { readonly rule: "grant"; readonly from: readonly Key[]; readonly in?: readonly (readonly Key[])[] };
 
 /**
  * A lazy rule of a kind names the parts that an evaluation can skip and still give a value. An example is the