@mark1russell7/coeval 0.6.3 → 0.7.0

package/src/durable.ts

@@ -0,0 +1,238 @@
+import type { Context } from "./deref.ts";
+import type { Result } from "./errors.ts";
+import { type Machine, type Plan, type PrepareOptions, type Read, prepare } from "./evaluate.ts";
+import { type DocFacts, type FactsOptions, factsOf } from "./facts.ts";
+import { type VerifyOptions, verifyReads } from "./reads.ts";
+
+/*
+ * Two levels of durability (R4 P7, D30). The plan and the facts of a document depend only on the structure: the
+ * machine and the documents. A result also depends on the data: the values that a context gives. A host keeps one
+ * epoch for each level. Thus a change of data keeps each plan and each fact, and it only verifies or evaluates.
+ */
+
+/** The two epochs of a host (DURABLE.EPOCHS). Each epoch counts the changes of its level. */
+export interface Epochs {
+  /** The count of the changes of the structure: a new machine, or an edit of a document. */
+  readonly structure: number;
+  /** The count of the changes of the data. A change of the structure is also a change of the data. */
+  readonly data: number;
+}
+
+/** The work of a durable cache since its start. A schedule reads it as a measure, not as a rule (R4). */
+export interface DurableCounts {
+  /** The compilations: the calls of `prepare`. */
+  readonly compiles: number;
+  /** The calls of `factsOf`. */
+  readonly facts: number;
+  /** The evaluations of a plan. */
+  readonly evaluations: number;
+  /** The calls of `verifyReads`. */
+  readonly verifications: number;
+  /** The results that stayed without an evaluation. */
+  readonly reuses: number;
+}
+
+/** The options of `durable`. */
+export interface DurableOptions {
+  /** The type of a bare root value, for each plan and each fact. */
+  readonly declaredType?: string;
+  /** The verb of each plan and each fact. The default is `eval` (VERB.PREPARE). */
+  readonly verb?: string;
+  /** The volatile reads of the host, as in `factsOf`. A document with such a read is not pure, thus it evaluates again after each change of data. */
+  readonly volatile?: FactsOptions["volatile"];
+  /** The rule of the host for two things, as in `verifyReads`. */
+  readonly equal?: VerifyOptions["equal"];
+}
+
+/**
+ * A cache of plans, facts and results with two levels of durability (D30). A host or a schedule tells the cache each
+ * change of the structure and each change of the data.
+ */
+export interface Durable {
+  /** The machine of the current structure epoch. */
+  readonly machine: Machine;
+  /** The current epochs. A schedule builds again what depends on the whole structure when `structure` changes, for example a graph of the nodes. */
+  readonly epochs: Epochs;
+  /** The work since the start. */
+  readonly counts: DurableCounts;
+  /**
+   * This function gives the plan of a document. A document object compiles one time for a machine (DURABLE.STRUCTURE).
+   * A change of data compiles nothing (DURABLE.DATA).
+   *
+   * @param doc - The document, as JSON.
+   * @returns The plan.
+   */
+  plan(doc: unknown): Plan;
+  /**
+   * This function gives the static facts of a document. A document object computes its facts one time for a machine.
+   *
+   * @param doc - The document, as JSON.
+   * @returns The facts.
+   */
+  facts(doc: unknown): DocFacts;
+  /**
+   * This function gives the result of the document of a node (DURABLE.REUSE). The key names the node, and in one data
+   * epoch the context of a key gives the same data.
+   *
+   * - In the data epoch of its result, a key with the same plan gives that result again.
+   * - After a change of data, a pure document verifies its reads, and it keeps its result when each read is the same.
+   * - Each other document evaluates again.
+   *
+   * @param key - The name of the node in the host, for example the name of a cell.
+   * @param doc - The document of the node.
+   * @param context - The context of the node.
+   * @returns The result.
+   */
+  evaluate(key: unknown, doc: unknown, context: Context): Result;
+  /** This function tells the cache that the data changed: a context gives a new value (DURABLE.EPOCHS). */
+  changeData(): void;
+  /**
+   * This function tells the cache that the structure changed (DURABLE.EPOCHS). An edit of a document gives a new
+   * document object, and only that object compiles. A new machine drops each plan, each fact and each result.
+   *
+   * @param machine - The new machine, or `undefined` for an edit of a document.
+   */
+  changeStructure(machine?: Machine): void;
+  /**
+   * This function drops the result of a node, for example a node that the host removed.
+   *
+   * @param key - The name of the node.
+   */
+  forget(key: unknown): void;
+}
+
+/** The result of one node, with what it depends on. */
+interface Entry {
+  /** The plan of the evaluation. A new document or a new machine gives another plan. */
+  readonly plan: Plan;
+  readonly result: Result;
+  /** The reads of the evaluation, only for a pure document. */
+  readonly reads: readonly Read[] | undefined;
+  /** The data epoch in which the result was last valid. */
+  data: number;
+}
+
+/** The most values that a cache of value documents keeps, as in `planner`. */
+const MAX_VALUES = 1000;
+
+/** No reads. One frozen list serves each result of a pure document without reads. */
+const NO_READS: readonly Read[] = /* @__PURE__ */ Object.freeze([]);
+
+/** The key of the document `-0` in a cache of value documents. A `Map` finds the entry of `0` for `-0`. */
+const NEGATIVE_ZERO = /* @__PURE__ */ Symbol("coeval.negative-zero");
+
+/** This function makes a cache by document. A document object gives its value one time, as PLAN.CACHE says. */
+function byDocument<T>(make: (doc: unknown) => T): (doc: unknown) => T {
+  const objects = new WeakMap<object, T>();
+  const values = new Map<unknown, T>();
+  return (doc) => {
+    if (typeof doc === "object" && doc !== null) {
+      if (objects.has(doc)) return objects.get(doc) as T;
+      const made = make(doc);
+      objects.set(doc, made);
+      return made;
+    }
+    const key = Object.is(doc, -0) ? NEGATIVE_ZERO : doc;
+    if (values.has(key)) return values.get(key) as T;
+    const made = make(doc);
+    if (values.size >= MAX_VALUES) values.clear();
+    values.set(key, made);
+    return made;
+  };
+}
+
+/**
+ * This function makes a cache with two levels of durability for a host or a schedule (R4 P7, D30). The structure is
+ * the machine and the documents. The data is each value that a context gives: the names, `self`, `event`, the
+ * capabilities and the world of the host.
+ *
+ * - A plan and the facts depend only on the structure. A document object compiles one time for a machine, thus a
+ *   change of data compiles nothing (DURABLE.DATA).
+ * - A result depends on the data too. It stays in its data epoch. After a change of data, a pure document verifies
+ *   its reads with `verifyReads`, and each other document evaluates again.
+ * - An edit gives a new document object, thus only that document compiles. A new machine drops each plan, each fact
+ *   and each result (DURABLE.STRUCTURE).
+ *
+ * The host keeps two promises. In one data epoch, the context of a key gives the same data. The values of a
+ * context and the documents do not change in place, as PLAN.CACHE and `verifyReads` say.
+ *
+ * @param machine - The machine of the first structure epoch.
+ * @param options - The type of a bare root value, the verb, the volatile reads and the rule of the host for two things.
+ * @returns The cache.
+ */
+export function durable(machine: Machine, options: DurableOptions = {}): Durable {
+  const prepareOptions: PrepareOptions = {
+    ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }),
+    ...(options.verb === undefined ? {} : { verb: options.verb }),
+  };
+  const factsOptions: FactsOptions = { ...prepareOptions, ...(options.volatile === undefined ? {} : { volatile: options.volatile }) };
+  const verifyOptions: VerifyOptions = options.equal === undefined ? {} : { equal: options.equal };
+  const counts = { compiles: 0, facts: 0, evaluations: 0, verifications: 0, reuses: 0 };
+  const results = new Map<unknown, Entry>();
+  let current = machine;
+  let epochs: Epochs = { structure: 0, data: 0 };
+  const plansOf = (m: Machine): ((doc: unknown) => Plan) =>
+    byDocument((doc) => {
+      counts.compiles += 1;
+      return prepare(m, doc, prepareOptions);
+    });
+  const factsFor = (m: Machine): ((doc: unknown) => DocFacts) =>
+    byDocument((doc) => {
+      counts.facts += 1;
+      return factsOf(m, doc, factsOptions);
+    });
+  let plans = plansOf(machine);
+  let facts = factsFor(machine);
+  return {
+    get machine() {
+      return current;
+    },
+    get epochs() {
+      return epochs;
+    },
+    get counts() {
+      return { ...counts };
+    },
+    plan: (doc) => plans(doc),
+    facts: (doc) => facts(doc),
+    evaluate(key, doc, context) {
+      const plan = plans(doc);
+      const entry = results.get(key);
+      if (entry !== undefined && entry.plan === plan) {
+        if (entry.data === epochs.data) {
+          counts.reuses += 1;
+          return entry.result;
+        }
+        if (entry.reads !== undefined) {
+          counts.verifications += 1;
+          if (verifyReads(plan, entry.reads, context, verifyOptions).same) {
+            entry.data = epochs.data;
+            counts.reuses += 1;
+            return entry.result;
+          }
+        }
+      }
+      // Only a pure document is a function of its reads (FACTS.PURE), thus only its reads can keep its result.
+      const reads: Read[] | undefined = facts(doc).pure ? [] : undefined;
+      counts.evaluations += 1;
+      const result = plan.evaluate(context, reads === undefined ? undefined : { reads });
+      // A list that grows by push keeps room for more reads. A copy of a short list is smaller (PLAN.LEAN).
+      results.set(key, { plan, result, reads: reads === undefined ? undefined : reads.length === 0 ? NO_READS : reads.slice(), data: epochs.data });
+      return result;
+    },
+    changeData() {
+      epochs = { structure: epochs.structure, data: epochs.data + 1 };
+    },
+    changeStructure(next) {
+      epochs = { structure: epochs.structure + 1, data: epochs.data + 1 };
+      if (next === undefined || next === current) return;
+      current = next;
+      plans = plansOf(next);
+      facts = factsFor(next);
+      results.clear();
+    },
+    forget(key) {
+      results.delete(key);
+    },
+  };
+}

package/src/effects.ts

@@ -0,0 +1,110 @@
+import type { Key } from "./doc.ts";
+import type { Cap } from "./deref.ts";
+import { type Machine, capKeys, permits } from "./evaluate.ts";
+import { type DocVisit, type Issue, declaredEffects, permitsOf, walk } from "./static.ts";
+
+/*
+ * The effects that reach the host (R2 P3, D27). The contract of each kind declares the effects of its documents, and
+ * its capability rules narrow the capabilities of its parts (D14). One walk narrows the capabilities as a run does. An
+ * effect that the capabilities of its document do not permit fails in the run, thus it does not reach the host.
+ *
+ * A procedure value keeps the capabilities of the document that made it, as the closure of `fn` does. Thus its latent
+ * effects are the effects of its body, under the capabilities of the body, and the fold needs no effect variables.
+ */
+
+/** The options of `effectsOf`. */
+export interface EffectsOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /**
+   * The capabilities at the root. With them, the result keeps only the effects that the rule of the machine permits at
+   * their documents, as a run does (CAP.PERMITS). Without them, the root has each capability, and only the capability
+   * rules of the kinds remove an effect.
+   */
+  readonly caps?: readonly Cap[];
+}
+
+/** Each capability: one capability with no keys. It permits each effect, because each kind starts with no keys (CAP.KEYS). */
+const EACH: readonly Cap[] = /* @__PURE__ */ Object.freeze([[]]);
+
+/** One declared effect that can reach the host: its keys and the visit of its document. */
+interface Reaching {
+  readonly kind: readonly Key[];
+  readonly visit: DocVisit;
+}
+
+/**
+ * This function finds each declared effect that can reach the host, in the order of the document. It is the one
+ * inference of `effectsOf` and `checkLatent`. `check` and `factsOf` read the same declarations (`declaredEffects`).
+ */
+function reaching(machine: Machine, doc: unknown, options: EffectsOptions): readonly Reaching[] {
+  const out: Reaching[] = [];
+  // Without capabilities, the host has no rule to ask. The capability rules of the kinds still narrow each capability.
+  const rule = options.caps === undefined ? permits : permitsOf(machine);
+  walk(
+    machine.world,
+    doc,
+    (v) => {
+      const caps = v.caps ?? EACH;
+      for (const kind of declaredEffects(v)) if (rule(caps, kind)) out.push({ kind, visit: v });
+      return undefined;
+    },
+    { caps: options.caps ?? EACH, ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }) },
+  );
+  return out;
+}
+
+/**
+ * This function gives the effects of a document that can reach the host (CAP.EFFECTS-OF, R2 P3). The result is the
+ * effects that the contract of each kind declares, without the effects that the capability rules around them remove.
+ * A rule `mask` removes each effect of its parts, and a rule `only` removes each effect outside its list.
+ *
+ * Without capabilities in the options, the result is the least authority of the document. A host that grants these
+ * kinds as capabilities grants each effect that a run of the document can give it. With capabilities, the result keeps
+ * only the effects that the rule of the machine permits at their documents.
+ *
+ * The result covers each effect that an evaluation or a run gives the host (CAP.EFFECTS-SOUND). A procedure value keeps
+ * the capabilities of the document that made it, thus the effects of its body count at the body (CAP.LATENT). The
+ * contract describes the code of its kind. The code of an own entry for another evaluator is outside the result.
+ *
+ * @param machine - The world and its contracts, and the hook `permits`.
+ * @param doc - The document, as JSON.
+ * @param options - The type of a bare root value and the capabilities at the root.
+ * @returns The kinds of the effects, as texts with dots, each one time, in the order of the document.
+ */
+export function effectsOf(machine: Machine, doc: unknown, options: EffectsOptions = {}): readonly string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const { kind } of reaching(machine, doc, options)) {
+    const text = kind.join(".");
+    if (seen.has(text)) continue;
+    seen.add(text);
+    out.push(text);
+  }
+  return out;
+}
+
+/**
+ * This function compares the latent effects that a procedure declares with the body of the procedure (CAP.LATENT). A
+ * procedure entry is a kind whose code evaluates the document of a procedure. Its field `effects` declares the latent
+ * effects: the effects that a call of the procedure can cause. `check` tests each call against this declaration.
+ *
+ * The function gives a `#CAP!` for each effect of the body that can reach the host and that the declaration does not
+ * permit. An effect that a kind in the body masks fails in the body, thus it is not a latent effect.
+ *
+ * @param machine - The world and its contracts.
+ * @param declared - The latent effects that the procedure declares, for example the field `effects` of its kind.
+ * @param body - The document of the procedure, as JSON.
+ * @param options - The type of a bare root value.
+ * @returns The issues, in the order of the body.
+ */
+export function checkLatent(machine: Machine, declared: readonly Cap[], body: unknown, options: Omit<EffectsOptions, "caps"> = {}): readonly Issue[] {
+  const issues: Issue[] = [];
+  const list = declared.map((cap) => capKeys(cap).join(".")).join(", ");
+  const head = declared.length === 0 ? "The procedure declares no latent effect" : `The procedure declares the latent effects ${list}`;
+  for (const { kind, visit } of reaching(machine, body, options.declaredType === undefined ? {} : { declaredType: options.declaredType })) {
+    if (permits(declared, kind)) continue;
+    issues.push({ code: "#CAP!", place: visit.place, reason: `${head}, and its body can cause the effect ${kind.join(".")} here.`, at: visit.at });
+  }
+  return issues;
+}

package/src/errors.ts

@@ -17,7 +17,8 @@ export type KernelCode =
   | "#CALC!"
   | "#DEPTH!"
   | "#ABORT"
-  | "#REPLAY!";
+  | "#REPLAY!"
+  | "#TYPE!";
 
 /** The code of an error value. A language can add its own codes. Each code starts with `#`. */
 export type ErrorCode = KernelCode | `#${string}`;