@mark1russell7/coeval 0.4.0 → 0.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "coeval: the kernel of declarative languages. Documents in envelopes, a ladder that finds the evaluator, kind contracts, compiled plans, a static kit, a formula kit and a run side with capabilities.",
   "type": "module",
   "main": "./build/index.js",

package/src/evaluate.ts

@@ -1,7 +1,7 @@
 import { type Envelope, type Json, type Key, type TypeRef, isEnvelope, typeName } from "./doc.ts";
-import { type Split, splitParts } from "./parts.ts";
+import { type Split, pathMatches, splitParts } from "./parts.ts";
 import { ask, type Answer } from "./ladder.ts";
-import { type Lookup, type Side, type World, lookupKind } from "./world.ts";
+import { type CapsRule, type Lookup, type Side, type World, lookupKind } from "./world.ts";
 import { type ErrorCode, type EvalError, type Result, fail, ok, placed, thrown, describe } from "./errors.ts";
 import {
   type Cap,
@@ -74,6 +74,58 @@ export function narrow(parent: Context, next: Context): Context {
   return caps.length === next.caps.length ? next : { ...next, caps };
 }
 
+/** No capabilities. One list serves each masked part. */
+const NO_CAPS: readonly Cap[] = Object.freeze([]);
+
+/** No capability rules. One list serves each part that no rule narrows. */
+const NO_RULES: readonly CapsRule[] = Object.freeze([]);
+
+/**
+ * This function gives the capabilities that two lists both permit. An effect is permitted by the result when each
+ * list permits it. When the list `b` permits each capability of `a`, the result is the list `a` itself.
+ *
+ * @param a - The first list, for example the capabilities of a document.
+ * @param b - The second list, for example the list of a rule `only`.
+ * @returns The capabilities that both lists permit.
+ */
+export function intersectCaps(a: readonly Cap[], b: readonly Cap[]): readonly Cap[] {
+  if (a.every((cap) => permits(b, cap))) return a;
+  const out: Cap[] = [];
+  for (const cap of b) if (permits(a, cap)) out.push(cap);
+  for (const cap of a) if (permits(b, cap) && !permits(out, cap)) out.push(cap);
+  return out;
+}
+
+/** This function gives the capability rules of a kind that cover a part and change its capabilities. */
+function rulesFor(rules: readonly CapsRule[] | undefined, path: readonly Key[]): readonly CapsRule[] {
+  if (rules === undefined || rules.length === 0) return NO_RULES;
+  const out = rules.filter((rule) => rule.rule !== "same" && (rule.in === undefined || rule.in.some((pattern) => pathMatches(path, pattern))));
+  return out.length === 0 ? NO_RULES : out;
+}
+
+/** This function applies the rules that cover a part to the capabilities of its document. */
+function capsUnder(rules: readonly CapsRule[], caps: readonly Cap[]): readonly Cap[] {
+  let out = caps;
+  for (const rule of rules) {
+    if (rule.rule === "mask") return NO_CAPS;
+    if (rule.rule === "only") out = intersectCaps(out, rule.caps);
+  }
+  return out;
+}
+
+/**
+ * This function gives the capabilities that a kind gives one of its parts, by the capability rules of its contract.
+ * The kernel and the static kit both use it, thus a run and a check narrow the same way.
+ *
+ * @param rules - The capability rules of the kind (`Kind.caps`).
+ * @param path - The path of the part in the value of the document.
+ * @param caps - The capabilities of the document.
+ * @returns The capabilities of the part: the same list or a smaller one.
+ */
+export function partCaps(rules: readonly CapsRule[] | undefined, path: readonly Key[], caps: readonly Cap[]): readonly Cap[] {
+  return capsUnder(rulesFor(rules, path), caps);
+}
+
 /**
  * The steps of an evaluation that can wait. It yields a promise only when the host makes it wait. A runner takes the
  * result of a part with `yield*`, thus a run goes on at once until an effect waits. A runner does not yield a
@@ -892,7 +944,10 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
   }
   const parts: CompiledPart[] = split.parts.map((slot) => {
     const item = slot.item;
-    const compiled = compileNode(c, item, place.concat(slot.path), slot.of, depth + 1, slot.address === true);
+    // The capability rules of the contract narrow the context of the part, thus no evaluator can forget them.
+    const own = compileNode(c, item, place.concat(slot.path), slot.of, depth + 1, slot.address === true);
+    const rules = rulesFor(kind?.caps, slot.path);
+    const compiled = rules.length === 0 ? own : gated(rules, own);
     // The binding name is in the header of an envelope. Most parts have no name, thus the cheap test comes first.
     const header = typeof (item as { readonly name?: unknown } | null)?.name === "string" && isEnvelope(item) ? (item as { readonly name: string }).name : undefined;
     return header === undefined
@@ -942,6 +997,20 @@ function placedCode(inner: Code, place: readonly Key[], name: string): Code {
   };
 }
 
+/**
+ * This function gives the code of a part that capability rules cover. The code narrows the context of the part by
+ * the rules before the part starts.
+ */
+function gated(rules: readonly CapsRule[], part: { readonly code: Code; readonly run: RunCode }): { readonly code: Code; readonly run: RunCode } {
+  const inner = part.code;
+  const steps = part.run;
+  const under = (ctx: Context): Context => {
+    const caps = capsUnder(rules, ctx.caps);
+    return caps === ctx.caps || (caps.length === 0 && ctx.caps.length === 0) ? ctx : { ...ctx, caps };
+  };
+  return { code: (ctx, rt) => inner(under(ctx), rt), run: (ctx, rt) => steps(under(ctx), rt) };
+}
+
 /** This function gives the steps of a runner, with the place of each error and of each exception. */
 function placedRun(inner: RunCode, place: readonly Key[], name: string): RunCode {
   return function* (ctx, rt) {

package/src/index.ts

@@ -36,6 +36,7 @@ export {
 } from "./errors.ts";
 export {
   type Alias,
+  type CapsRule,
   type Kind,
   type Lookup,
   type Namespace,
@@ -127,9 +128,11 @@ export {
   evaluate,
   failures,
   flatten,
+  intersectCaps,
   makeContext,
   narrow,
   nodeAt,
+  partCaps,
   permits,
   planner,
   prepare,

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;
   /**