@mark1russell7/coeval 0.24.0 → 0.25.0

package/src/syntax.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 entries(form: Form | undefined): Record<string, Json> {
-    const owner = form === undefined ? "record" : `form ${form.name}`;
+  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, 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);
   }

package/src/types.ts

@@ -722,6 +722,71 @@ function narrowAt(type: unknown, path: readonly string[], at: number, narrowed:
   return { record: fields, ...(optional.length === 0 ? {} : { optional }), ...(form.closed ? { closed: true } : {}) };
 }
 
+/**
+ * What the result of a test proves of the value at one path (STATIC.OCCURRENCE, D147). The path starts at a root, or at
+ * `names` and a name, and each later key is a field of a record. The fact `is` tells that the value is a member of the
+ * type, and `not` tells that it is not. The facts `present` and `absent` tell if the path reaches a value.
+ */
+export type Proof =
+  | { readonly path: readonly string[]; readonly fact: "is" | "not"; readonly type: ValueType }
+  | { readonly path: readonly string[]; readonly fact: "present" | "absent" };
+
+/** This function gives the type of a value that is a member of both types. The result is the narrower known type. */
+function meetOf(type: ValueType, proved: ValueType, domains: Readonly<Record<string, Domain>> | undefined): ValueType {
+  if (isUnknown(proved, domains)) return type;
+  const form = formOf(type, domains);
+  if (form.t === "one") return { one: form.values.filter((value) => member(value, proved, domains)) };
+  return !isUnknown(type, domains) && isPrecise(type, domains) && fits(type, proved, domains) ? type : proved;
+}
+
+/** This function gives the type of a value of the first type that is not a member of the second type. */
+function withoutOf(type: ValueType, removed: ValueType, domains: Readonly<Record<string, Domain>> | undefined): ValueType {
+  if (isUnknown(removed, domains)) return type;
+  const form = formOf(type, domains);
+  if (form.t === "one") return { one: form.values.filter((value) => !member(value, removed, domains)) };
+  if (form.t === "union") {
+    const members = form.members.map((each) => withoutOf(each, removed, domains)).filter((each) => each !== "never");
+    return members.length === 0 ? "never" : members.length === 1 ? (members[0] as ValueType) : { union: members };
+  }
+  // Only a precise type can leave: a gradual type fits each type, but its values do not.
+  return isPrecise(type, domains) && fits(type, removed, domains) ? "never" : type;
+}
+
+/**
+ * This function gives a type with one proof at a path (STATIC.OCCURRENCE). A path that leaves the records of the type
+ * gives the type back. A fact about a field also tells if the field exists. A value of a type without `undefined`
+ * exists. An optional field without a remaining type does not.
+ *
+ * @param type - The type of the value at the first `at` keys of the path.
+ * @param proof - The proof.
+ * @param at - The number of keys of the path that the type already holds.
+ * @param domains - The domains of the machine.
+ * @returns The narrowed type.
+ */
+export function narrowType(type: ValueType, proof: Proof, at: number, domains: Readonly<Record<string, Domain>> | undefined): ValueType {
+  if (at === proof.path.length) {
+    if (proof.fact === "is") return meetOf(type, proof.type, domains);
+    return proof.fact === "not" ? withoutOf(type, proof.type, domains) : type;
+  }
+  const form = formOf(type, domains);
+  const key = proof.path[at] as string;
+  if (form.t !== "record" || !Object.hasOwn(form.fields, key)) return type;
+  const before = form.fields[key] as ValueType;
+  const optional = new Set(form.optional);
+  let after: ValueType | undefined = narrowType(before, proof, at + 1, domains);
+  if (at + 1 === proof.path.length && optional.has(key)) {
+    if (proof.fact === "present" || (proof.fact === "is" && !member(undefined, proof.type, domains))) optional.delete(key);
+    else if (proof.fact === "absent" || after === "never") after = undefined;
+  }
+  const fields: Record<string, ValueType> = {};
+  for (const name of Object.keys(form.fields)) if (name !== key) setOwn(fields, name, form.fields[name] as ValueType);
+  // The absent case removes the field of a closed record. An open record keeps it as an optional field of the type `never`.
+  if (after !== undefined) setOwn(fields, key, after);
+  else if (form.closed) optional.delete(key);
+  else setOwn(fields, key, "never");
+  return { record: fields, ...(optional.size === 0 ? {} : { optional: [...optional] }), ...(form.closed ? { closed: true } : {}) };
+}
+
 /**
  * This function is the split rule of `fits` (TYPE.FITS-FINITE, D84, TYPE.FITS-PATH, D89). A record type fits when each
  * record of its split fits. A split takes the first field in the order of `splitsOf`. Each member of the field gives a

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 Proof, type ValueType, domainOf, fits, isPrecise, isUnknown, narrowType, typeIssues, typeText } from "./types.ts";
 import { type Kind, type Shape, eachKind, kindAt } from "./world.ts";
 
 /*
@@ -58,6 +58,27 @@ export interface TypeInput {
    * @returns The type.
    */
   contract(type: unknown, what: string): ValueType;
+  /**
+   * This function gives the path that a part reads, from the rule `reads` of the part (STATIC.OCCURRENCE).
+   *
+   * @param path - The path of the part in the value.
+   * @returns The path of the read, or `undefined` for each other part.
+   */
+  readOf(path: readonly Key[]): readonly string[] | undefined;
+  /**
+   * This function gives what the result of a part proves. Only a rule with `usesProofs` gets this, for a part that the
+   * check typed before.
+   *
+   * @param path - The path of the part in the value.
+   * @returns The proofs of the part.
+   */
+  provenBy(path: readonly Key[]): Proven;
+}
+
+/** What a test proves of its paths: `yes` when the test is true, and `no` when it is false (STATIC.OCCURRENCE). */
+export interface Proven {
+  readonly yes: readonly Proof[];
+  readonly no: readonly Proof[];
 }
 
 /** What a type rule tells for one part: the type that the part must have, and the types of the names of the part. */
@@ -73,6 +94,10 @@ export interface PartType {
    * Each other root keeps its type. The parts of an evaluator without a rule get `unknown` for each of these roots.
    */
   readonly roots?: Omit<RootTypes, "names">;
+  /** The proofs that hold in the part (STATIC.OCCURRENCE). They narrow the names and the roots of the part. */
+  readonly narrow?: readonly Proof[];
+  /** `true` when the proofs of `narrow` also hold in each later part. */
+  readonly keep?: boolean;
 }
 
 /**
@@ -82,7 +107,7 @@ export interface PartType {
  *
  * The host keeps the types true: each root of the context holds a member of its type. A host thing, or a machine
  * with `adopt`, keeps each step true too. The context binds each name of `names`, thus the option `names` of `check`
- * lists it too.
+ * lists it too. A narrowing also needs one value for two reads of one path (STATIC.OCCURRENCE).
  */
 export interface RootTypes {
   /** The type of each name that the host binds. A name of the host without a type here has the type `unknown`. */
@@ -116,6 +141,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.
@@ -142,6 +169,24 @@ export interface TypeRule {
    * @returns The value types that the rule reads, and the problems that the rule finds in its declarations.
    */
   readonly declared?: () => readonly Declared[];
+  /** The field of the value that the check types before each other part. A branch then reads the proofs of its test. */
+  readonly first?: string;
+  /** `true` when the rule reads `provenBy`. The check asks the rule `proves` only of a part of such a rule. */
+  readonly usesProofs?: boolean;
+  /**
+   * This function gives the path that the document reads. A path with a computed step is not such a path.
+   *
+   * @param input - The document.
+   * @returns The path, or `undefined`.
+   */
+  readonly reads?: (input: TypeInput) => readonly string[] | undefined;
+  /**
+   * This function gives what the result of the document proves (STATIC.OCCURRENCE).
+   *
+   * @param input - The document and its parts.
+   * @returns The proofs of a true result and of a false result.
+   */
+  readonly proves?: (input: TypeInput) => Proven;
 }
 
 /**
@@ -174,6 +219,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. */
@@ -191,6 +263,9 @@ export interface TypeNode {
   marked: boolean;
 }
 
+/** The result of a test that proves nothing. */
+const NO_PROOFS: Proven = { yes: [], no: [] };
+
 /** The result of the pass of types. */
 export interface TypePass {
   readonly type: ValueType;
@@ -226,8 +301,11 @@ interface Frame {
   next: number;
   readonly typed: Map<string, ValueType>;
   readonly needs: readonly Need[];
-  readonly names: ReadonlyMap<string, ValueType>;
-  readonly roots: Roots;
+  /** The types of the names for the parts. A part with `keep` changes them for the later parts. */
+  names: ReadonlyMap<string, ValueType>;
+  roots: Roots;
+  /** The proofs of the typed parts, for a rule with `usesProofs`. */
+  proven: Map<string, Proven> | undefined;
 }
 
 function pathKey(path: readonly Key[]): string {
@@ -238,12 +316,16 @@ 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;
 }
 
-/** This function gives the order of the parts of a document: first the parts that give the names of a rule `keysAt`. */
-function orderOf(node: TypeNode, nodes: readonly TypeNode[]): readonly number[] {
+/** This function gives the order of the parts of a document. The part `first` of the rule comes first, or else the parts that give the names of a rule `keysAt`. */
+function orderOf(node: TypeNode, nodes: readonly TypeNode[], first: string | undefined): readonly number[] {
+  if (first !== undefined) {
+    const isFirst = (index: number): boolean => String((nodes[index] as TypeNode).visit.slot[0]) === first;
+    return [...node.children.filter(isFirst), ...node.children.filter((index) => !isFirst(index))];
+  }
   const sources = (node.visit.kind?.scope ?? []).flatMap((rule) => ("keysAt" in rule.names ? [rule.names.keysAt] : []));
   if (sources.length === 0 || node.children.length < 2) return node.children;
   const gives = (index: number): boolean => {
@@ -269,7 +351,7 @@ function message(error: unknown): string {
  * @param rootTypes - The types of the roots and of the names of the host.
  * @returns The type of the root, the type issues in the order of the document, and the type of each document.
  */
-export function typePass(machine: Machine, nodes: readonly TypeNode[], verb: string, expect: ValueType | undefined, rootTypes: RootTypes = {}): TypePass {
+export function typePass(machine: Machine, nodes: readonly TypeNode[], verb: string, expect: ValueType | undefined, rootTypes: RootTypes = {}, hasEffect: (node: TypeNode) => boolean = () => false): TypePass {
   if (nodes.length === 0) return { type: "unknown", issues: [], places: [] };
   const domains = machine.domains;
   const contracts = verb === "eval";
@@ -277,6 +359,28 @@ export function typePass(machine: Machine, nodes: readonly TypeNode[], verb: str
   const types = new Array<ValueType>(nodes.length);
   const needed = new Array<ValueType | undefined>(nodes.length);
   const seen = new Set<unknown>();
+  const inputs = new Array<TypeInput>(nodes.length);
+  let changes: boolean | undefined;
+
+  // A document with an effect can change a root between two reads, thus only its names narrow (STATIC.OCCURRENCE-EFFECT).
+  const rootsChange = (): boolean => (changes ??= nodes.some(hasEffect));
+
+  const narrowed = (names: ReadonlyMap<string, ValueType>, roots: Roots, proofs: readonly Proof[]): { readonly names: ReadonlyMap<string, ValueType>; readonly roots: Roots } => {
+    let nextNames = names;
+    let nextRoots = roots;
+    for (const proof of proofs) {
+      const head = proof.path[0];
+      if (head === "names") {
+        const name = proof.path[1];
+        if (name === undefined) continue;
+        if (nextNames === names) nextNames = new Map(names);
+        (nextNames as Map<string, ValueType>).set(name, narrowType(nextNames.get(name) ?? "unknown", proof, 2, domains));
+      } else if ((head === "self" || head === "world" || head === "event") && !rootsChange()) {
+        nextRoots = { ...nextRoots, [head]: narrowType(nextRoots[head], proof, 1, domains) };
+      }
+    }
+    return { names: nextNames, roots: nextRoots };
+  };
 
   const issueAt = (index: number, problem: TypeProblem): void => {
     const visit = (nodes[index] as TypeNode).visit;
@@ -316,8 +420,18 @@ export function typePass(machine: Machine, nodes: readonly TypeNode[], verb: str
       nameType: (name) => names.get(name),
       rootType: (root) => (root === "caps" ? CAPS_TYPE : root === "self" || root === "world" || root === "event" ? roots[root] : "unknown"),
       contract: (type, what) => contract(index, type, what),
+      readOf: (path) => {
+        const key = pathKey(path);
+        const part = node.children.find((child) => pathKey((nodes[child] as TypeNode).visit.slot) === key);
+        const read = part === undefined ? undefined : ruleOf(machine, (nodes[part] as TypeNode).evaluator)?.reads;
+        return read === undefined || (nodes[part as number] as TypeNode).marked ? undefined : read(inputs[part as number] as TypeInput);
+      },
+      provenBy: (path) => frame.proven?.get(pathKey(path)) ?? NO_PROOFS,
     };
-    return { index, rule: node.marked ? undefined : ruleOf(machine, node.evaluator), input, order: orderOf(node, nodes), next: 0, typed, needs, names, roots };
+    inputs[index] = input;
+    const rule = node.marked ? undefined : ruleOf(machine, node.evaluator);
+    const frame: Frame = { index, rule, input, order: orderOf(node, nodes, rule?.first), next: 0, typed, needs, names, roots, proven: undefined };
+    return frame;
   };
 
   const ruleFailed = (frame: Frame, error: unknown): void => {
@@ -362,6 +476,16 @@ export function typePass(machine: Machine, nodes: readonly TypeNode[], verb: str
       if (contracts && node.expect !== undefined) need(contract(child, node.expect, `expected type of the ${what}`), what);
       if (part.expect !== undefined) need(part.expect, part.what ?? what);
       let names = frame.names;
+      let kept = frame.roots;
+      if (part.narrow !== undefined && part.narrow.length > 0) {
+        const after = narrowed(names, kept, part.narrow);
+        names = after.names;
+        kept = after.roots;
+        if (part.keep === true) {
+          frame.names = names;
+          frame.roots = kept;
+        }
+      }
       if (node.bound.length > 0) {
         // Each name that the scope rules bind hides the name around it. A name without a type from the rule gets `unknown`.
         const copy = new Map(names);
@@ -369,7 +493,7 @@ export function typePass(machine: Machine, nodes: readonly TypeNode[], verb: str
         names = copy;
       }
       // No contract tells how an evaluator changes the roots, thus only a rule keeps their types for its parts (TYPE.ROOTS).
-      let roots = frame.rule === undefined ? UNKNOWN_ROOTS : frame.roots;
+      let roots = frame.rule === undefined ? UNKNOWN_ROOTS : kept;
       const changes = part.roots;
       if (typeof changes === "object" && changes !== null) {
         const copy: Record<(typeof CHANGING)[number], ValueType> = { ...roots };
@@ -403,12 +527,23 @@ export function typePass(machine: Machine, nodes: readonly TypeNode[], verb: str
     }
     types[frame.index] = type;
     needed[frame.index] = frame.needs.length === 0 ? undefined : (frame.needs[frame.needs.length - 1] as Need).type;
-    stack[stack.length - 1]?.typed.set(pathKey(node.visit.slot), type);
+    const parent = stack[stack.length - 1];
+    if (parent === undefined) continue;
+    const key = pathKey(node.visit.slot);
+    parent.typed.set(key, type);
+    if (parent.rule?.usesProofs === true && frame.rule?.proves !== undefined) {
+      try {
+        (parent.proven ??= new Map()).set(key, frame.rule.proves(frame.input));
+      } catch (error) {
+        ruleFailed(frame, error);
+      }
+    }
   }
 
   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 });