@mark1russell7/coeval 0.4.0 → 0.4.2

package/src/static.ts

@@ -4,7 +4,7 @@ import { ask } from "./ladder.ts";
 import { type PartSlot, pathMatches, splitParts } from "./parts.ts";
 import { type Cap, type Root, ROOTS, isRef } from "./deref.ts";
 import type { ErrorCode } from "./errors.ts";
-import { type Machine, permits } from "./evaluate.ts";
+import { type Machine, partCaps, permits } from "./evaluate.ts";
 
 /** One document that a walk visits. */
 export interface DocVisit {
@@ -32,6 +32,11 @@ export interface DocVisit {
   readonly later: ReadonlySet<string>;
   /** `true` when the position of the document declares an address: a reference there is not a read of a value. */
   readonly address?: true | undefined;
+  /**
+   * The capabilities of the document: the capabilities of the walk, narrowed by the capability rules of the kinds
+   * around it (`Kind.caps`). A walk without capabilities gives none here.
+   */
+  readonly caps?: readonly Cap[] | undefined;
 }
 
 /** A position that a walk cannot read as a document. */
@@ -50,6 +55,8 @@ export interface WalkOptions {
   readonly declaredType?: string;
   /** The names that the host binds at the root. */
   readonly names?: readonly string[];
+  /** The capabilities at the root. With them, each visit gets the capabilities of its document. */
+  readonly caps?: readonly Cap[];
   /**
    * This function gets each position that is not a document.
    *
@@ -169,6 +176,7 @@ class Visit implements DocVisit {
     readonly kind: Kind | undefined,
     readonly typePath: readonly Key[] | undefined,
     readonly address: true | undefined,
+    readonly caps: readonly Cap[] | undefined,
   ) {
     this.#place = place;
     this.#at = at;
@@ -185,14 +193,15 @@ class Visit implements DocVisit {
 
 /**
  * This function visits each document of a document: the root and each part at each depth, by the contracts of the
- * kinds. A part of a kind that the world does not have is not visited. The walk uses no stack of the host for the
+ * kinds. A part of a kind that the world does not have is not visited. With capabilities in the options, the walk
+ * narrows them for each part by the rules of its kind, as a run does. The walk uses no stack of the host for the
  * depth, thus a deep document cannot overflow it. The time and the memory of a walk are linear in the size of the
  * document. A visit makes the keys of its place and of its path only when a reader asks for them.
  *
  * @param world - The world of the kinds.
  * @param doc - The document, as JSON.
  * @param visit - The function that gets each document. It gives `"skip"` to not visit the parts of a document.
- * @param options - The type of a bare root value, the names of the host, and a function for the problems.
+ * @param options - The type of a bare root value, the names, the capabilities and a function for the problems.
  */
 export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => void | "skip", options: WalkOptions = {}): void {
   interface Item {
@@ -206,6 +215,7 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
     readonly address: boolean;
     readonly slot: readonly Key[];
     readonly parent: DocVisit | undefined;
+    readonly caps: readonly Cap[] | undefined;
   }
   const stack: Item[] = [
     {
@@ -219,6 +229,7 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
       address: false,
       slot: [],
       parent: undefined,
+      caps: options.caps,
     },
   ];
   while (stack.length > 0) {
@@ -244,6 +255,7 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
       kind,
       found.ok ? found.path : undefined,
       item.address ? true : undefined,
+      item.caps,
     );
     const answer = visit(here);
     if (answer === "skip" || kind === undefined) continue;
@@ -271,6 +283,7 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
         address: slot.address === true,
         slot: slot.path,
         parent: here,
+        caps: item.caps === undefined || kind.caps === undefined ? item.caps : partCaps(kind.caps, slot.path, item.caps),
       });
     }
   }
@@ -380,10 +393,27 @@ export interface CheckOptions {
   readonly declaredType?: string;
   /** The names that the host binds at the root. `"any"` does not check the names. The default is no names. */
   readonly names?: readonly string[] | "any";
-  /** The capabilities at the root. Without them, the check does not check the effects. */
+  /**
+   * The capabilities at the root. Without them, the check does not check the effects. The check narrows them for
+   * each part by the capability rules of the kinds, as a run does.
+   */
   readonly caps?: readonly Cap[];
 }
 
+/**
+ * This function gives the reason of a `#CAP!`. When a kind around the document narrowed the capabilities, the
+ * reason names the nearest such kind.
+ */
+function capReason(v: DocVisit, kind: readonly Key[]): string {
+  const text = kind.join(".");
+  for (let up = v.parent; up !== undefined; up = up.parent) {
+    if (up.caps !== undefined && permits(up.caps, kind)) {
+      return `The capabilities do not permit the effect ${text} here. The kind ${typeName(up.doc.type)} around it narrows them for its parts.`;
+    }
+  }
+  return `The capabilities do not permit the effect ${text}.`;
+}
+
 /**
  * This function checks a document before an evaluation, by the contracts of its kinds. It finds the problems
  * that an evaluation finds when it reaches them:
@@ -395,7 +425,7 @@ export interface CheckOptions {
  * - `#DEPTH!`: too much nesting.
  * - `#REF!` and `#STEP?`: a bad path.
  * - `#NAME?`: a name that nothing binds.
- * - `#CAP!`: an effect that the capabilities do not permit.
+ * - `#CAP!`: an effect that the capabilities of its document do not permit. A kind around the document can narrow them.
  *
  * @param machine - The world and the code of the evaluators.
  * @param doc - The document, as JSON.
@@ -426,10 +456,11 @@ export function check(machine: Machine, doc: unknown, options: CheckOptions = {}
       if (name === undefined || (!has(machine.evaluators, name) && !has(machine.runners, name))) {
         issues.push({ code: "#NOEVAL", place: v.place, reason: `No rung gives an evaluator for ${typeName(v.doc.type)}.`, at: v.at });
       }
-      if (options.caps !== undefined && v.kind?.effects !== undefined) {
+      const caps = v.caps;
+      if (caps !== undefined && v.kind?.effects !== undefined) {
         const kinds: readonly (readonly Key[])[] = v.kind.effects === "type" ? [v.typePath ?? []] : v.kind.effects.map((kind) => kind.split("."));
         for (const kind of kinds) {
-          if (!permits(options.caps, kind)) issues.push({ code: "#CAP!", place: v.place, reason: `The capabilities do not permit the effect ${kind.join(".")}.`, at: v.at });
+          if (!permits(caps, kind)) issues.push({ code: "#CAP!", place: v.place, reason: capReason(v, kind), at: v.at });
         }
       }
       const isPath = isRef(v.doc);
@@ -472,6 +503,7 @@ export function check(machine: Machine, doc: unknown, options: CheckOptions = {}
     {
       ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }),
       ...(Array.isArray(options.names) ? { names: options.names } : {}),
+      ...(options.caps === undefined ? {} : { caps: options.caps }),
       problem: (problem) => issues.push({ code: problem.code, place: problem.place, reason: problem.reason, at: problem.at }),
     },
   );

package/src/stdlib.ts

@@ -69,18 +69,21 @@ export const STD_WORLD: World = {
     pure: {
       verbs: { eval: "control.pure", view: "view.op" },
       parts: { shape: "list" },
+      caps: [{ rule: "mask" }],
       summary: "It evaluates its part without capabilities, thus an effect in it fails.",
     },
     log: {
       verbs: { eval: "effect.log", view: "view.op" },
       parts: { shape: "list", of: "text" },
       side: "run",
+      effects: ["log"],
       summary: "It writes the result of its part to the log. This is an effect.",
     },
     write: {
       verbs: { eval: "effect.write", view: "view.op" },
       parts: { shape: "record", fields: ["value"] },
       side: "run",
+      effects: ["write"],
       summary: "It writes the result of its part to the store, at its key. This is an effect.",
     },
   },
@@ -269,10 +272,11 @@ export const STD_RUNNERS: Readonly<Record<string, Runner>> = {
     }
     return ok(last);
   },
-  "control.pure": function* ({ parts, context }) {
+  // The contract of pure masks the capabilities of its part, and the kernel applies it. Thus the runner does not.
+  "control.pure": function* ({ parts }) {
     const only = parts[0];
     if (only === undefined) return fail("#VALUE!", "pure needs one part.");
-    return yield* only.evaluate({ ...context, caps: [] });
+    return yield* only.evaluate();
   },
   "control.if": function* ({ parts }) {
     const test = parts.find((part) => part.key === "test");

package/src/world.ts

@@ -1,4 +1,5 @@
 import { type Envelope, type Json, type Key, type TypeRef, field, isRecord, typePath } from "./doc.ts";
+import type { Cap } from "./deref.ts";
 
 /** The two sides of evaluation. `derive` is pure. `run` causes effects in order. */
 export type Side = "derive" | "run";
@@ -69,6 +70,22 @@ export interface ScopeRule {
   readonly sequential?: boolean;
 }
 
+/**
+ * A capability rule of a kind: what the kind gives some of its parts from the capabilities of its document. A rule
+ * only narrows. A part does not get a capability that its document does not have (CAP.NARROW).
+ *
+ * - `same`: the parts get the capabilities of the document. This is the default.
+ * - `mask`: the parts get no capabilities, as the part of `pure`.
+ * - `only`: the parts get only the effects that the capabilities of the document and the list `caps` both permit.
+ *
+ * `in` names the parts that the rule covers, as patterns of their paths in the value. The key `"*"` matches each
+ * key. A rule without `in` covers each part.
+ */
+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[])[] };
+
 /** A kind gives the name of an evaluator for each verb, and the contract of its value. */
 export interface Kind {
   readonly verbs: Readonly<Record<string, string>>;
@@ -76,6 +93,13 @@ export interface Kind {
   readonly parts?: Shape;
   /** The names that the kind binds for its parts. */
   readonly scope?: readonly ScopeRule[];
+  /**
+   * The capabilities that the kind gives its parts, as rules. A part that no rule covers gets the capabilities of
+   * the document. A part that several rules cover gets only what each rule permits. The static kit reads the rules,
+   * and the kernel narrows the context of each part by them. Thus an evaluator does not narrow the capabilities
+   * itself.
+   */
+  readonly caps?: readonly CapsRule[];
   /** The side of the kind. A kind of the run side causes effects. The default is `derive`. */
   readonly side?: Side;
   /**