@mark1russell7/coeval 0.12.0 → 0.14.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "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/conform.ts

@@ -23,6 +23,7 @@ import {
   type Runtime,
   type Steps,
   capKeys,
+  intersectCaps,
   makeContext,
   permits,
   rootContext,
@@ -371,8 +372,8 @@ class Shot implements Runtime {
   /** This function answers an effect as the kernel does: it checks the capability, and it asks the mock. */
   private answer(ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result {
     const keys = capKeys(kind);
-    // The kernel keeps only the capabilities that the document permits (H-GRANT).
-    const caps = ctx.caps.filter((cap) => permits(this.context.caps, cap));
+    // The kernel keeps the capabilities that both the context and the document permit (H-GRANT, CAP.MEET).
+    const caps = intersectCaps(ctx.caps, this.context.caps);
     const allowed = this.machine.permits === undefined ? permits(caps, keys) : this.machine.permits(caps, keys, { ...ctx, caps });
     if (!allowed) return fail("#CAP!", `The context has no capability for the effect ${keys.join(".")}.`, { place });
     if (this.perform === undefined) return ok(payload);

package/src/evaluate.ts

@@ -68,8 +68,9 @@ export function permits(caps: readonly Cap[], kind: Cap): boolean {
 }
 
 /**
- * This function narrows a context for a part: the part keeps only the capabilities that the context of its parent
- * permits. Thus an evaluator cannot give a part more effects than it has.
+ * This function narrows a context for a part. The part keeps the meet `intersectCaps` of its list and the list of its
+ * parent (CAP.MEET). Thus an evaluator cannot give a part more effects than it has. A context whose list the parent
+ * permits stays the same object.
  *
  * @param parent - The context of the parent.
  * @param next - The context that the evaluator gives the part.
@@ -77,8 +78,8 @@ export function permits(caps: readonly Cap[], kind: Cap): boolean {
  */
 export function narrow(parent: Context, next: Context): Context {
   if (next === parent || next.caps === parent.caps) return next;
-  const caps = next.caps.filter((cap) => permits(parent.caps, cap));
-  return caps.length === next.caps.length ? next : { ...next, caps };
+  const caps = intersectCaps(next.caps, parent.caps);
+  return caps === next.caps ? next : { ...next, caps };
 }
 
 /** No capabilities. One list serves each masked part. */
@@ -140,46 +141,73 @@ export function partCaps(rules: readonly CapsRule[] | undefined, path: readonly
  */
 const GRANT = /* @__PURE__ */ Symbol("coeval.grant");
 
-/** A context with the grant of the kernel. */
-type Granted = Context & { readonly [GRANT]?: readonly Cap[] };
+/**
+ * The key of the epoch of a grant (CAP.NARROW-KEPT). The epoch is the list of capabilities that the host gave the root
+ * of the evaluation of the grant. A spread of a context keeps its epoch, as it keeps its grant. An
+ * effect and a resolution read a context of another epoch as a context without a grant.
+ */
+const EPOCH = /* @__PURE__ */ Symbol("coeval.epoch");
+
+/** A context with the grant of the kernel and the epoch of that grant. */
+type Granted = Context & { readonly [GRANT]?: readonly Cap[]; readonly [EPOCH]?: readonly Cap[] | undefined };
 
 /**
- * This function gives a context whose capabilities its grant permits (CAP.NARROW-CODE). A context whose grant is its
- * own list of capabilities stays the same object. Each other context keeps only the capabilities that its grant
- * permits, and a context without a grant keeps none. The result has the grant of its capabilities.
+ * This function gives the capabilities that a context and its grant both permit, the meet `intersectCaps` (CAP.MEET).
+ * A context whose grant is its own list gives that list after one comparison. A context without a grant gives none.
  */
-function granted(ctx: Context): Context {
+function grantedCaps(ctx: Context): readonly Cap[] {
   const grant = (ctx as Granted)[GRANT];
-  if (grant === ctx.caps) return ctx;
-  const caps = grant === undefined ? NO_CAPS : ctx.caps.every((cap) => permits(grant, cap)) ? ctx.caps : ctx.caps.filter((cap) => permits(grant, cap));
+  if (grant === ctx.caps) return grant;
+  return grant === undefined ? NO_CAPS : intersectCaps(ctx.caps, grant);
+}
+
+/**
+ * This function gives a context whose capabilities its grant permits (CAP.NARROW-CODE, CAP.MEET). A context whose grant
+ * is its own list of capabilities stays the same object. Each other context keeps the meet of its list and its grant,
+ * and a context without a grant keeps none. The result has the grant of its capabilities.
+ */
+function granted(ctx: Context): Context {
+  if ((ctx as Granted)[GRANT] === ctx.caps) return ctx;
+  const caps = grantedCaps(ctx);
   const out: Granted = { ...ctx, caps, [GRANT]: caps };
   return out;
 }
 
 /**
- * This function gives the context in which the runtime resolves a path of compiled code (CAP.CAPS-GRANT). A path from
- * the root `caps` reads the capabilities that both the context and its grant permit, and a context without a grant
- * reads none. Thus a context that compiled code widened gives the capabilities of its document, and a context that it
- * narrowed keeps its own list. Each other path, and each context whose grant is its own list, keeps the same context.
+ * This function gives a context of another epoch the epoch of the evaluation, without capabilities (CAP.NARROW-KEPT).
+ * Thus the context reads as a context without a grant. The kernel cannot know the document of the context in this
+ * evaluation.
  */
-function readable(ctx: Context, path: readonly unknown[]): Context {
-  if (path[0] !== "caps") return ctx;
-  const grant = (ctx as Granted)[GRANT];
-  if (grant === ctx.caps) return ctx;
-  const caps = grant === undefined ? NO_CAPS : intersectCaps(ctx.caps, grant);
-  if (caps === ctx.caps) return ctx;
+function ungranted(ctx: Context, epoch: readonly Cap[]): Context {
+  const out: Granted = { ...ctx, caps: NO_CAPS, [GRANT]: NO_CAPS, [EPOCH]: epoch };
+  return out;
+}
+
+/**
+ * This function gives the context in which the runtime resolves a path of compiled code (CAP.CAPS-GRANT, CAP.MEET).
+ * The context has the meet of its list and its grant, and a context without a grant has none. Thus a read of the root
+ * `caps` and a walker of a step document get the capabilities of the document from a widened context.
+ * A context that the code narrowed keeps its own list. A context whose list does not change stays the same object.
+ * A context of another epoch has no capabilities (CAP.NARROW-KEPT).
+ */
+function readable(ctx: Context, epoch: readonly Cap[]): Context {
+  if ((ctx as Granted)[EPOCH] !== epoch) return ctx.caps.length === 0 ? ctx : ungranted(ctx, epoch);
+  const caps = grantedCaps(ctx);
+  if (caps === ctx.caps || (caps.length === 0 && ctx.caps.length === 0)) return ctx;
   const out: Granted = { ...ctx, caps, [GRANT]: caps };
   return out;
 }
 
 /**
  * This function gives the context of a part of a function evaluator. It is the context that the evaluator gives,
- * narrowed by the context of the document (CAP.NARROW), with the grant of its capabilities.
+ * narrowed by the context of the document (CAP.NARROW), with the grant of its capabilities. The grant has the epoch
+ * of the document, because the document permits each of its capabilities (CAP.NARROW-KEPT).
  */
 function handed(parent: Context, next: Context): Context {
   const ctx = narrow(parent, next);
-  if ((ctx as Granted)[GRANT] === ctx.caps) return ctx;
-  const out: Granted = { ...ctx, [GRANT]: ctx.caps };
+  const epoch = (parent as Granted)[EPOCH];
+  if ((ctx as Granted)[GRANT] === ctx.caps && (ctx as Granted)[EPOCH] === epoch) return ctx;
+  const out: Granted = { ...ctx, [GRANT]: ctx.caps, [EPOCH]: epoch };
   return out;
 }
 
@@ -889,6 +917,11 @@ class Session implements Runtime {
 
   constructor(
     readonly machine: Machine,
+    /**
+     * The epoch of the evaluation: the list of capabilities that the host gave the root (CAP.NARROW-KEPT). A context
+     * keeps its grant only in an evaluation of the same epoch.
+     */
+    readonly epoch: readonly Cap[],
     readonly running: boolean,
     readonly traced: boolean,
     readonly perform: Perform | undefined,
@@ -912,18 +945,21 @@ class Session implements Runtime {
     return this.reading !== undefined;
   }
 
-  /** This function resolves a path. A path from the root `caps` reads the capabilities through the grant (CAP.CAPS-GRANT). */
+  /**
+   * This function resolves a path in the context that the grant permits (CAP.CAPS-GRANT, CAP.MEET). Thus the root
+   * `caps` and a walker of a step document get the capabilities of the document.
+   */
   resolve(ctx: Context, path: readonly unknown[], options?: ResolveOptions): Resolution {
-    return this.read(readable(ctx, path), path, undefined, options);
+    return this.read(readable(ctx, this.epoch), path, undefined, options);
   }
 
   /**
    * This function resolves a compiled path (PLAN.PATH). Without a list of reads and without a trace, the compiled
-   * path answers at once. Each other resolution records its read, as `resolve` does. A path from the root `caps` reads
-   * the capabilities through the grant (CAP.CAPS-GRANT).
+   * path answers at once. Each other resolution records its read, as `resolve` does. The path resolves in the context
+   * that the grant permits (CAP.CAPS-GRANT, CAP.MEET).
    */
   resolvePath(given: Context, compiled: CompiledPath): Resolution {
-    const ctx = readable(given, compiled.path);
+    const ctx = readable(given, this.epoch);
     if (this.reading === undefined && !this.traced && compiled.nav === this.machine) return compiled.resolve(ctx);
     return this.read(ctx, compiled.path, compiled, undefined);
   }
@@ -985,10 +1021,11 @@ class Session implements Runtime {
   /**
    * This function checks the capability of an effect, and records the effect with its address (RUN.ADDRESS). The
    * context keeps only the capabilities of its grant, thus compiled code cannot widen the context of its own effect
-   * (CAP.NARROW-CODE).
+   * (CAP.NARROW-CODE). A context of another epoch has no capabilities, thus code cannot keep a context for a later
+   * evaluation with fewer capabilities (CAP.NARROW-KEPT).
    */
   private record(given: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result | Recorded {
-    const ctx = granted(given);
+    const ctx = (given as Granted)[EPOCH] === this.epoch ? granted(given) : ungranted(given, this.epoch);
     const keys = typeof kind === "string" ? kind.split(".") : kind;
     const text = keys.join(".");
     if (!this.permitted(ctx, keys)) return fail("#CAP!", `The context has no capability for the effect ${text}.`, { place });
@@ -1911,15 +1948,16 @@ function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonl
 /**
  * This function gives the context at the root of an evaluation. It is the context of the host, with the world of
  * the machine when the context has none. The host gives the capabilities, thus the root has the grant of each one
- * (CAP.NARROW-CODE). An evaluation and `verifyReads` share it.
+ * (CAP.NARROW-CODE). The list of the host is also the epoch of the grant (CAP.NARROW-KEPT). An evaluation and
+ * `verifyReads` share it.
  *
  * @param machine - The machine.
  * @param ctx - The context of the host.
  * @returns The context at the root.
  */
 export function rootContext(machine: Machine, ctx: Context): Context {
-  if (ctx.world !== null && (ctx as Granted)[GRANT] === ctx.caps) return ctx;
-  const root: Granted = { ...ctx, world: ctx.world === null ? worldThing(machine.world) : ctx.world, [GRANT]: ctx.caps };
+  if (ctx.world !== null && (ctx as Granted)[GRANT] === ctx.caps && (ctx as Granted)[EPOCH] === ctx.caps) return ctx;
+  const root: Granted = { ...ctx, world: ctx.world === null ? worldThing(machine.world) : ctx.world, [GRANT]: ctx.caps, [EPOCH]: ctx.caps };
   return root;
 }
 
@@ -1990,14 +2028,14 @@ class CompiledPlan implements Plan {
   evaluate(context: Context = makeContext(), evalOptions?: EvalOptions): Result {
     const machine = this.machine;
     const ctx = rootContext(machine, context);
-    const s = new Session(machine, false, this.traced, evalOptions?.perform, undefined, evalOptions?.effects, readingOf(evalOptions?.reads, ctx));
+    const s = new Session(machine, ctx.caps, false, this.traced, evalOptions?.perform, undefined, evalOptions?.effects, readingOf(evalOptions?.reads, ctx));
     return this.code(ctx, s);
   }
 
   run(context: Context = makeContext(), runOptions: PlanRunOptions = {}): Promise<Result> {
     const machine = this.machine;
     const ctx = rootContext(machine, context);
-    const s = new Session(machine, true, this.traced, runOptions.perform, runOptions.signal, undefined, readingOf(runOptions.reads, ctx));
+    const s = new Session(machine, ctx.caps, true, this.traced, runOptions.perform, runOptions.signal, undefined, readingOf(runOptions.reads, ctx));
     return driveWaiting(this.runCode()(ctx, s), runOptions.signal);
   }
 }
@@ -2065,7 +2103,7 @@ export function evaluate(machine: Machine, doc: unknown, context: Context = make
     ...(given.verb === undefined ? {} : { verb: given.verb }),
   });
   const ctx = rootContext(machine, context);
-  const s = new Session(machine, false, true, given.perform, undefined, undefined, readingOf(given.reads, ctx));
+  const s = new Session(machine, ctx.caps, false, true, given.perform, undefined, undefined, readingOf(given.reads, ctx));
   const result = (plan as CompiledPlan).code(ctx, s);
   return record(s, result);
 }
@@ -2088,7 +2126,7 @@ export async function run(machine: Machine, doc: unknown, context: Context = mak
     ...(options.verb === undefined ? {} : { verb: options.verb }),
   });
   const ctx = rootContext(machine, context);
-  const s = new Session(machine, true, true, options.perform, options.signal, undefined, readingOf(options.reads, ctx));
+  const s = new Session(machine, ctx.caps, true, true, options.perform, options.signal, undefined, readingOf(options.reads, ctx));
   const result = await driveWaiting((plan as CompiledPlan).runCode()(ctx, s), options.signal);
   return record(s, result);
 }

package/src/reference.ts

@@ -171,11 +171,13 @@ function capsOfPart(rules: readonly CapsRule[] | undefined, path: readonly Key[]
 }
 
 /**
- * This function gives the context of a part. A context that the evaluator gives keeps only the capabilities of the
- * parent (CAP.NARROW). Then the rules of the kind narrow it (CAP.CONTRACT).
+ * This function gives the context of a part. A context that the evaluator gives keeps the effects that both it and
+ * the parent permit (CAP.NARROW, CAP.MEET). A list that the parent permits stays as it is. Then the rules of the kind
+ * narrow it (CAP.CONTRACT).
  */
 function contextOfPart(seen: Seen, slot: PartSlot, parent: Context, given: Context | undefined): Context {
-  const base = given === undefined || given === parent ? parent : { ...given, caps: given.caps.filter((cap) => permits(parent.caps, cap)) };
+  const base =
+    given === undefined || given === parent ? parent : given.caps.every((cap) => permits(parent.caps, cap)) ? given : { ...given, caps: bothPermit(parent.caps, given.caps) };
   const caps = capsOfPart(seen.kind?.caps, slot.path, base.caps);
   return caps === base.caps ? base : { ...base, caps };
 }