@mark1russell7/coeval 0.11.0 → 0.13.0

package/package.json

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

@@ -363,6 +363,8 @@ export function context(parts: Partial<Context> = {}): Context {
 }
 
 const MAX_COLLAPSE = 64;
+/** The reason of a resolution that reaches the bound of collapses without a cycle that it found (DEREF.CHAIN-REASON). It is a plain string, thus a bundle drops it (PKG.PURE). */
+const CHAIN_REASON = "The path follows more than 64 references. One resolution follows at most 64.";
 const NO_HOPS: readonly Hop[] = /* @__PURE__ */ Object.freeze([]);
 
 /** A value that can be a reference document: a record with the type `ref`. The full check comes after. */
@@ -560,7 +562,8 @@ function walkersOf(nav: Navigator, path: readonly unknown[]): KnownWalkers | und
  * - `#NAME?`: the root `names` has no such name.
  * - `#N/A`: a step reaches nothing.
  * - `#STEP?`: a step is not a key and not a step document.
- * - `#CYCLE!`: the references form a cycle.
+ * - `#CYCLE!`: the references form a cycle, or the resolution follows more than 64 references. The reason tells
+ *   which (DEREF.CHAIN-REASON).
  *
  * @param nav - The world and the code of the evaluators.
  * @param ctx - The context.
@@ -590,15 +593,21 @@ function resolveFully(nav: Navigator, ctx: Context, path: readonly unknown[], ho
   const done = hops ?? NO_HOPS;
   const failed = (code: ResolveCode | ErrorCode, reason: string): Resolution => ({ ok: false, code, reason, hops: done });
   let collapses = 0;
+  // The references whose paths are in evaluation. A reference that is in this list again closes a cycle.
+  let open: object[] | undefined;
   const adopt = nav.adopt ?? ((value: unknown): Thing => value);
 
   const collapse = (thing: Thing): Resolution => {
     let here = thing;
     if (nav.plain === true) return { ok: true, thing: here, hops: done };
     while (isRef(here)) {
+      if (open?.includes(here) === true) return failed("#CYCLE!", "The references form a cycle.");
       collapses += 1;
-      if (collapses > MAX_COLLAPSE) return failed("#CYCLE!", "The references form a cycle.");
+      if (collapses > MAX_COLLAPSE) return failed("#CYCLE!", CHAIN_REASON);
+      open ??= [];
+      open.push(here);
       const inner = walk(here.value, undefined);
+      open.pop();
       if (!inner.ok) return inner;
       here = adopt(inner.thing);
       hops?.push({ step: "collapse", thing: here, by: "collapse" });

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. */
@@ -144,14 +145,36 @@ const GRANT = /* @__PURE__ */ Symbol("coeval.grant");
 type Granted = Context & { readonly [GRANT]?: readonly Cap[] };
 
 /**
- * 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, 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.
+ */
+function readable(ctx: Context): Context {
+  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;
 }
@@ -896,15 +919,21 @@ class Session implements Runtime {
     return this.reading !== undefined;
   }
 
+  /**
+   * 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(ctx, path, undefined, options);
+    return this.read(readable(ctx), 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.
+   * 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(ctx: Context, compiled: CompiledPath): Resolution {
+  resolvePath(given: Context, compiled: CompiledPath): Resolution {
+    const ctx = readable(given);
     if (this.reading === undefined && !this.traced && compiled.nav === this.machine) return compiled.resolve(ctx);
     return this.read(ctx, compiled.path, compiled, undefined);
   }

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 };
 }

package/src/world.ts

@@ -270,10 +270,28 @@ export interface World {
   readonly fallback?: Kind;
 }
 
-/** The result of a lookup of a type in the world. */
+/**
+ * The result of a lookup of a type in the world. The reasons of a failure:
+ *
+ * - `unknown`: the world has no entry for a key, and no fallback kind.
+ * - `cycle`: the aliases form a cycle. The lookup reached a path a second time.
+ * - `too-long`: the lookup followed more than 32 aliases without a path a second time (DEREF.CHAIN-REASON).
+ * - `not-a-kind`: the path reaches an entry of the wrong sort. An example is an alias whose target is not in the world.
+ * - `computed`: the type is a computed type, thus it has no keys.
+ */
 export type Lookup =
   | { readonly ok: true; readonly kind: Kind; readonly path: readonly Key[]; readonly aliases: number }
-  | { readonly ok: false; readonly reason: "unknown" | "cycle" | "not-a-kind" | "computed"; readonly path: readonly Key[] };
+  | { readonly ok: false; readonly reason: "unknown" | "cycle" | "too-long" | "not-a-kind" | "computed"; readonly path: readonly Key[] };
+
+/** The most aliases that one lookup follows (WORLD.ALIAS-LIMIT). */
+const MAX_ALIASES = 32;
+
+/** This function tells if two paths of a lookup have the same keys. */
+function samePath(a: readonly Key[], b: readonly Key[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let index = 0; index < a.length; index += 1) if (a[index] !== b[index]) return false;
+  return true;
+}
 
 /**
  * This function tells if an entry of the world is a kind.
@@ -312,7 +330,8 @@ function entryAt(entries: Readonly<Record<string, WorldEntry>>, key: Key): World
 
 /**
  * This function finds the kind that a type names. It walks the path from the root of the world, one key at a
- * time. An alias on the way is followed until a kind answers (collapse). A cycle of aliases stops the lookup. In a
+ * time. An alias on the way is followed until a kind answers (collapse). A cycle of aliases stops the lookup, and so
+ * does a chain of more than 32 aliases. In a
  * namespace with a fallback, a key that the namespace does not have gets the fallback kind. In an open world, a first
  * key that the world does not have gets the fallback kind of the world.
  *
@@ -325,6 +344,8 @@ export function lookupKind(world: World, type: TypeRef): Lookup {
   if (start === undefined) return { ok: false, reason: "computed", path: [] };
   let path: readonly Key[] = start;
   let aliases = 0;
+  // The paths before each alias. The same path again closes a cycle, because the lookup of a path is always the same.
+  let seen: (readonly Key[])[] | undefined;
   for (;;) {
     let entries = world.kinds;
     let fallback: Kind | undefined = world.fallback;
@@ -339,12 +360,16 @@ export function lookupKind(world: World, type: TypeRef): Lookup {
       }
       if (isAlias(entry)) {
         aliases += 1;
-        if (aliases > 32) return { ok: false, reason: "cycle", path };
+        if (aliases > MAX_ALIASES) return { ok: false, reason: "too-long", path };
         const target = entry.value.slice(1);
         if (entry.value[0] !== "world" || !target.every((item) => typeof item === "string" || typeof item === "number")) {
           return { ok: false, reason: "not-a-kind", path };
         }
+        seen ??= [];
+        seen.push(path);
         path = [...(target as readonly Key[]), ...path.slice(index + 1)];
+        const next = path;
+        if (seen.some((before) => samePath(before, next))) return { ok: false, reason: "cycle", path };
         followed = true;
         break;
       }