@mark1russell7/coeval 0.7.0 → 0.8.0

package/src/types.ts

@@ -54,6 +54,33 @@ export interface Domain {
    * a step with the key into a member reaches a member of the type. A key without a type gives `unknown`.
    */
   readonly steps?: Readonly<Record<string, ValueType>>;
+  /**
+   * The codec of the members: it writes a member as JSON and reads it again (D40). A document holds a member as the
+   * standard extension `ext.domain`. A domain without a codec has no such document.
+   */
+  readonly codec?: DomainCodec;
+}
+
+/**
+ * The codec of a domain: it writes a member of the domain as JSON, and it reads the JSON again (D40). Both functions
+ * must be pure. `decode(encode(v))` must equal `v` by `sameValue` (EXT.ROUNDTRIP). The codec must give one JSON
+ * value for each member, thus the same value has the same document in each language (D12).
+ */
+export interface DomainCodec {
+  /**
+   * This function writes a member of the domain as JSON.
+   *
+   * @param value - A member of the domain.
+   * @returns The JSON of the member.
+   */
+  readonly encode: (value: unknown) => Json;
+  /**
+   * This function reads the JSON of a member again. It throws for JSON that does not write a member.
+   *
+   * @param data - The JSON that `encode` gave.
+   * @returns The member.
+   */
+  readonly decode: (data: Json) => unknown;
 }
 
 /** A problem of a value type: the keys from the root of the term to the problem, and the reason. */
@@ -102,7 +129,7 @@ const TOP: Form = { t: "top" };
 const BOTTOM: Form = { t: "bottom" };
 
 /** This function gives the domain of a base type: the domain of the machine, or else the domain of the kernel. */
-function domainOf(name: string, domains: Readonly<Record<string, Domain>> | undefined): Domain | undefined {
+export function domainOf(name: string, domains: Readonly<Record<string, Domain>> | undefined): Domain | undefined {
   // The top and the bottom are not domains. A table entry with their names has no effect.
   if (name === "unknown" || name === "never") return undefined;
   const found = domains !== undefined && Object.hasOwn(domains, name) ? domains[name] : Object.hasOwn(STD_DOMAINS, name) ? STD_DOMAINS[name] : undefined;

package/src/world.ts

@@ -121,6 +121,51 @@ export interface KindFacts {
   readonly lazy?: readonly LazyRule[];
 }
 
+/**
+ * The declaration of one attribute of the nodes of a kind (D42). The last two rungs of the ladder of an attribute
+ * read it (TREE.LADDER). Each term is a document. A bare term gets the type `of` of the parts of the kind.
+ *
+ * - `copy`: `true` gives a node without an answer of the first three rungs the same attribute of its parent
+ *   (TREE.COPY).
+ * - `fold`: the value of a node without an answer of the first four rungs. The fold starts with the term `unit`.
+ *   Then the term `combine` adds the attribute of each node in the list `children`, one at a time (TREE.FOLD).
+ *   `combine` sees the names `acc` and `item`.
+ * - `default`: the term that gives the value when no rung before it answers and the declaration has no fold.
+ */
+export interface AttributeDeclaration {
+  readonly copy?: boolean;
+  readonly fold?: { readonly unit: Json; readonly combine: Json };
+  readonly default?: Json;
+}
+
+/**
+ * The tree contract of a kind (D42): the equations of the attributes of its nodes. Each equation is a document that
+ * evaluates with the node as `self` and without capabilities. A bare equation gets the type `of` of the parts of the
+ * kind.
+ *
+ * - `equations`: the attributes of the node itself. An equation sees no names.
+ * - `down`: the attributes of each child of the node. `self` is this node. An equation sees the names `child`,
+ *   `index` and `prev` (TREE.DOWN).
+ * - `attributes`: the declarations of the attributes of the node, for the rungs `copy` and `default`.
+ */
+export interface TreeContract {
+  readonly equations?: Readonly<Record<string, Json>>;
+  readonly down?: Readonly<Record<string, Json>>;
+  readonly attributes?: Readonly<Record<string, AttributeDeclaration>>;
+}
+
+/**
+ * This function gives the type of a bare equation of a kind (D42). It is the type `of` of the shape of its parts, or
+ * else the type `of` of the shape `rest` of a record. The plan, the reference and `check` read it with this one function.
+ *
+ * @param kind - The kind.
+ * @returns The type, or `undefined` when the shape declares none.
+ */
+export function equationType(kind: Kind): string | undefined {
+  const parts = kind.parts as { readonly of?: string; readonly rest?: { readonly of?: string } } | undefined;
+  return parts?.of ?? parts?.rest?.of;
+}
+
 /**
  * A kind gives the name of an evaluator for each verb, and the contract of its value. The contract serves each verb.
  * For each verb, the kernel splits the parts and narrows their capabilities by it, and `check` reads its scope rules.
@@ -157,6 +202,11 @@ export interface Kind extends KindFacts {
    * document of the kind, in the place of the type that the rule of the evaluator synthesizes.
    */
   readonly result?: ValueType;
+  /**
+   * The equations and the declarations of the attributes of a node of the decorated tree (D42). Only the evaluator
+   * `tree.node` reads them, and `check` checks each equation one time (TREE.LADDER).
+   */
+  readonly tree?: TreeContract;
   /** One sentence that tells what the kind is. */
   readonly summary?: string;
 }