capdag 1.311.160 → 1.363.10

package/capdag.js

@@ -1,12 +1,36 @@
 // Cap URN JavaScript Implementation
 // Follows the exact same rules as Rust, Go, and Objective-C implementations
-
-// Import TaggedUrn from the tagged-urn package
-const {
-  TaggedUrn,
-  valuesMatch: taggedUrnValuesMatch,
-  scoreTagValue
-} = require('tagged-urn');
+//
+// Dispatch, acceptance, equivalence and specificity are decided by code
+// generated from the proved model in ../formal (Lean) by lungo, in ./formal,
+// not written here. It runs as WebAssembly, instantiated once when this module
+// is first imported.
+
+import { TaggedUrn } from 'tagged-urn';
+import * as machineParser from './machine-parser.js';
+import { load } from './formal/index.js';
+
+const model = await load();
+
+// Node's modules, for what works with the file system and with processes:
+// cartridge discovery, installation records and directory hashes. They exist
+// only under Node; elsewhere this module loads without them, and asking for
+// them there is an error naming what needed them.
+const node = (typeof process !== 'undefined' && process.versions && process.versions.node)
+  ? {
+      fs: await import('node:fs'),
+      path: await import('node:path'),
+      crypto: await import('node:crypto'),
+      childProcess: await import('node:child_process'),
+    }
+  : null;
+
+function nodeModules(what) {
+  if (node === null) {
+    throw new Error(`capdag: ${what} needs Node's file system and processes, which this runtime does not have`);
+  }
+  return node;
+}
 
 /**
  * Error types for Cap URN operations
@@ -83,7 +107,7 @@ function processDirectionTag(taggedUrn, tagName) {
  */
 function canonicalizeDirectionSpec(spec, tagName) {
   if (spec === 'media:' || spec === '*') {
-    return spec;
+    return 'media:';
   }
 
   try {
@@ -106,7 +130,7 @@ function canonicalizeDirectionSpec(spec, tagName) {
  */
 function validatePreservedDirectionSpec(spec, tagName) {
   if (spec === 'media:' || spec === '*') {
-    return spec;
+    return 'media:';
   }
 
   try {
@@ -195,6 +219,27 @@ function validateNonStructuralTags(tags) {
   }
 }
 
+/**
+ * A tagged URN as capdag's model takes it. Each program generated for
+ * JavaScript runs in a WebAssembly instance of its own, so tagged-urn's model
+ * value of a URN cannot pass here: this program makes its own, from the same
+ * tags, with the same function of the same model.
+ */
+function modelUrn(urn) {
+  const made = model.make(urn.prefix, urn.modelTags());
+  if (made === null) {
+    throw new Error(`capdag: the model refused ${urn.toString()}, whose keys are sorted`);
+  }
+  return made;
+}
+
+const MODEL_EFFECTS = Object.freeze({
+  declared: Object.freeze({ kind: 'declared' }),
+  none: Object.freeze({ kind: 'none' }),
+  patch: Object.freeze({ kind: 'patch' }),
+  '?': Object.freeze({ kind: 'unspecified' }),
+});
+
 class CapUrn {
   // Per-axis weights for cap-URN specificity. Two orders of
   // magnitude separate each axis to keep them in distinct digit
@@ -224,6 +269,20 @@ class CapUrn {
     }
     validateNonStructuralTags(this.tags);
     this._validateAdmissible();
+    // The same cap on the proved model's side: its three URNs and its effect.
+    // Dispatch, acceptance, equivalence and specificity are asked of it. Made
+    // here, from the same fields, and the cap is frozen, so the two can never
+    // describe different caps; it is not enumerable, so it is not part of what
+    // a cap serializes or compares as.
+    const formal = {
+      input: modelUrn(MediaUrn.fromString(this.inSpec)._urn),
+      output: modelUrn(MediaUrn.fromString(this.outSpec)._urn),
+      other: modelUrn(new TaggedUrn('cap', this.tags)),
+      effect: MODEL_EFFECTS[this.effectValue],
+    };
+    Object.defineProperty(this, 'formal', { value: formal, enumerable: false });
+    Object.freeze(this.tags);
+    Object.freeze(this);
   }
 
   /**
@@ -587,79 +646,38 @@ class CapUrn {
   }
 
   /**
-   * Check if this cap (pattern/handler) accepts a request (instance).
+   * Whether `cap` fits this cap read as a PATTERN over caps — what a search
+   * asks: `cap`'s input is within this pattern's, its output covers the
+   * pattern's, its effect is the pattern's (a pattern's `?effect` fits any),
+   * and its cap-tags — complete: a cap has the tags it has — satisfy the
+   * pattern's.
    *
-   * Direction (in/out) uses TaggedUrn.accepts()/conformsTo() (via MediaUrn matching):
-   * - Input: capIn.accepts(requestIn) — cap's input spec is pattern, request's input is instance
-   * - Output: capOut.conformsTo(requestOut) — cap's output is instance, request's output is pattern
-   * For other tags:
-   * - For each tag in the request: cap has same value, wildcard (*), or missing tag
-   * - For each tag in the cap: if request is missing that tag, that's fine (cap is more specific)
-   * Missing tags (except in/out) are treated as wildcards (less specific, can handle any value).
+   * A side the pattern leaves open is not asked about. `cap:candle` fits every
+   * cap tagged `candle`, whatever it takes and gives: its open output is "not
+   * established", not the type "anything".
    *
-   * @param {CapUrn} request - The request cap to check
-   * @returns {boolean} Whether this cap accepts the request
+   * Decided by the proved model (CapDAG.Exec.accepts, which is CapDAG.fits).
+   * For a question no cap URN can spell — "what gives this, whatever it
+   * takes" — ask a CapQuery.
+   *
+   * @param {CapUrn} cap - The cap to test against this pattern
+   * @returns {boolean} Whether the cap fits
    */
-  accepts(request) {
-    if (!request) {
+  accepts(cap) {
+    if (!cap) {
       return true;
     }
-
-    // Input direction: pattern accepts instance. `media:` on the pattern side is
-    // the wildcard top and skips the check.
-    if (this.inSpec !== 'media:' && this.inSpec !== '*') {
-      const capIn = MediaUrn.fromString(this.inSpec);
-      const requestIn = MediaUrn.fromString(request.inSpec);
-      if (!capIn.accepts(requestIn)) {
-        return false;
-      }
-    }
-
-    // Output direction: candidate output must conform to requested output.
-    // `media:` on the pattern side is wildcard top and skips the check.
-    if (this.outSpec !== 'media:' && this.outSpec !== '*') {
-      const capOut = MediaUrn.fromString(this.outSpec);
-      const requestOut = MediaUrn.fromString(request.outSpec);
-      if (!capOut.conformsTo(requestOut)) {
-        return false;
-      }
-    }
-
-    if (this.effectValue !== CapEffect.ANY && this.effectValue !== request.effectValue) {
-      return false;
-    }
-
-    // Y-axis: every tag's per-key match runs through the six-form
-    // truth table (taggedUrnValuesMatch). Walk the union of all keys
-    // appearing on either side so missing-on-pattern and
-    // missing-on-instance cells both get evaluated.
-    const allKeys = new Set([
-      ...Object.keys(this.tags),
-      ...Object.keys(request.tags),
-    ]);
-    for (const key of allKeys) {
-      const patt = Object.prototype.hasOwnProperty.call(this.tags, key)
-        ? this.tags[key]
-        : undefined;
-      const inst = Object.prototype.hasOwnProperty.call(request.tags, key)
-        ? request.tags[key]
-        : undefined;
-      if (!taggedUrnValuesMatch(inst, patt)) {
-        return false;
-      }
-    }
-    return true;
+    return model.accepts(this.formal, cap.formal);
   }
 
   /**
-   * Check if this cap (instance) conforms to another cap (pattern).
-   * Equivalent to cap.accepts(this).
+   * Whether this cap fits `pattern`: `pattern.accepts(this)`.
    *
-   * @param {CapUrn} cap - The cap to check conformance against
-   * @returns {boolean} Whether this cap conforms to the given cap
+   * @param {CapUrn} pattern
+   * @returns {boolean}
    */
-  conformsTo(cap) {
-    return cap.accepts(this);
+  conformsTo(pattern) {
+    return pattern.accepts(this);
   }
 
   /**
@@ -689,16 +707,8 @@ class CapUrn {
    * @returns {number} The specificity score
    */
   specificity() {
-    const inUrn = MediaUrn.fromString(this.inSpec);
-    const outUrn = MediaUrn.fromString(this.outSpec);
-
-    let yScore = 0;
-    for (const value of Object.values(this.tags)) {
-      yScore += scoreTagValue(value);
-    }
-    return CapUrn.WEIGHT_OUT * outUrn.specificity()
-         + CapUrn.WEIGHT_IN  * inUrn.specificity()
-         + yScore;
+    // Computed by the proved model (CapDAG.Exec.specificity).
+    return Number(model.specificity(this.formal));
   }
 
   /**
@@ -781,7 +791,7 @@ class CapUrn {
    * @returns {boolean}
    */
   isComparable(other) {
-    return this.accepts(other) || other.accepts(this);
+    return model.comparable(this.formal, other.formal);
   }
 
   /**
@@ -792,7 +802,7 @@ class CapUrn {
    * @returns {boolean}
    */
   isEquivalent(other) {
-    return this.accepts(other) && other.accepts(this);
+    return model.equivalent(this.formal, other.formal);
   }
 
   /**
@@ -851,51 +861,62 @@ class CapUrn {
   }
 
   /**
-   * Check if this candidate can dispatch the given request.
+   * Whether this candidate SERVES `request` — the predicate routing and
+   * dispatch act on.
+   *
+   * The candidate takes at least what the request sends, gives at least what
+   * the request needs, has the effect asked for unless the request says
+   * `?effect`, and has the cap-tags asked for — its own tags being complete, so
+   * a request for `!x` is served by a candidate that does not mention `x`, and
+   * a candidate may carry tags the request does not ask about.
+   *
+   * An input the request leaves open is not established: the caller has not
+   * said what it will send, and every candidate passes that side. That is
+   * "some input", not "any input" — `media:` on a CANDIDATE's input does mean
+   * it takes anything.
+   *
+   * This is a guarantee. What only could serve does not; see mayDispatch and
+   * CapQuery.grade. Decided by the proved model (CapDAG.Exec.dispatch, which is
+   * CapDAG.serves). Not symmetric.
    *
    * @param {CapUrn} request
    * @returns {boolean}
    */
   isDispatchable(request) {
-    return this._inputDispatchable(request)
-      && this._outputDispatchable(request)
-      && this._effectDispatchable(request)
-      && this._capTagsDispatchable(request);
-  }
-
-  _inputDispatchable(request) {
-    if (request.inSpec === 'media:') return true;
-    if (this.inSpec === 'media:') return true;
-    return MediaUrn.fromString(request.inSpec).conformsTo(MediaUrn.fromString(this.inSpec));
+    return model.dispatch(this.formal, request.formal);
   }
 
-  _outputDispatchable(request) {
-    if (request.outSpec === 'media:') return true;
-    if (this.outSpec === 'media:') return false;
-    return MediaUrn.fromString(this.outSpec).conformsTo(MediaUrn.fromString(request.outSpec));
+  /**
+   * Whether this candidate COULD serve `request`: not guaranteed, not
+   * excluded. For exploring what the fabric might do — never for routing a
+   * call, which must be served.
+   *
+   * @param {CapUrn} request
+   * @returns {boolean}
+   */
+  mayDispatch(request) {
+    return model.mayDispatch(this.formal, request.formal);
   }
 
-  _effectDispatchable(request) {
-    return request.effectValue === CapEffect.ANY || this.effectValue === request.effectValue;
+  /**
+   * Whether what this cap gives, `next` takes: the edge of a route.
+   *
+   * @param {CapUrn} next
+   * @returns {boolean}
+   */
+  flowsInto(next) {
+    return model.flows(this.formal, next.formal);
   }
 
-  _capTagsDispatchable(request) {
-    const allKeys = new Set([
-      ...Object.keys(this.tags),
-      ...Object.keys(request.tags),
-    ]);
-    for (const key of allKeys) {
-      const patt = Object.prototype.hasOwnProperty.call(request.tags, key)
-        ? request.tags[key]
-        : undefined;
-      const inst = Object.prototype.hasOwnProperty.call(this.tags, key)
-        ? this.tags[key]
-        : undefined;
-      if (!taggedUrnValuesMatch(inst, patt)) {
-        return false;
-      }
-    }
-    return true;
+  /**
+   * Whether what this cap gives COULD be something `next` takes: an edge a
+   * search may explore and a run has to check.
+   *
+   * @param {CapUrn} next
+   * @returns {boolean}
+   */
+  mayFlowInto(next) {
+    return model.mayFlow(this.formal, next.formal);
   }
 
   /**
@@ -908,7 +929,9 @@ class CapUrn {
     const declaredIn = this.inMediaUrn();
     const declaredOut = this.outMediaUrn();
 
-    if (!runtimeInput.conformsTo(declaredIn)) {
+    // A runtime media URN is the media of a value that exists, so it is read
+    // complete: it SATISFIES the declared type, or does not.
+    if (!runtimeInput.satisfies(declaredIn)) {
       throw new CapUrnError(
         ErrorCodes.INVALID_EFFECT_APPLICATION,
         `Runtime input '${runtimeInput}' does not conform to declared input '${declaredIn}'`
@@ -940,7 +963,7 @@ class CapUrn {
         );
     }
 
-    if (!runtimeOut.conformsTo(declaredOut)) {
+    if (!runtimeOut.satisfies(declaredOut)) {
       throw new CapUrnError(
         ErrorCodes.INVALID_EFFECT_APPLICATION,
         `Inferred runtime output '${runtimeOut}' does not conform to declared output '${declaredOut}'`
@@ -984,7 +1007,7 @@ class CapUrn {
       case CapEffect.PATCH:
         return runtimeOutput.isEquivalent(inferred);
       case CapEffect.DECLARED:
-        return runtimeOutput.conformsTo(inferred);
+        return runtimeOutput.satisfies(inferred);
       default:
         throw new CapUrnError(
           ErrorCodes.INVALID_EFFECT_APPLICATION,
@@ -1128,6 +1151,109 @@ class CapUrnBuilder {
   }
 }
 
+/**
+ * How a registered cap answers a CapQuery.
+ *
+ * - EXACT: guaranteed, and exactly what was asked on every side that was asked.
+ * - GUARANTEED: whatever the cap takes and gives, it is what was asked.
+ * - POSSIBLE: not guaranteed and not excluded — only running it tells. For
+ *   exploring; a call is never routed on it.
+ * - NONE: excluded.
+ */
+const MatchGrade = Object.freeze({
+  EXACT: 'exact',
+  GUARANTEED: 'guaranteed',
+  POSSIBLE: 'possible',
+  NONE: 'none',
+});
+
+/** Whether routing may act on a grade. */
+function gradeIsGuaranteed(grade) {
+  return grade === MatchGrade.EXACT || grade === MatchGrade.GUARANTEED;
+}
+
+/** The cap-tag pattern a query asks for: `cap:` with these tags (none asks for none). */
+function queryTagPattern(tags) {
+  return modelUrn(new TaggedUrn('cap', { ...(tags || {}) }));
+}
+
+/**
+ * A question about caps.
+ *
+ * A request is not a cap. A cap takes this and gives that; a request is a
+ * QUESTION about caps, and may leave a side unasked: "what gives me this file,
+ * whatever it takes?", "what can this input become?". Those are not cap URNs
+ * with `media:` on a side — `media:` is the type "anything", a claim about
+ * every input — they are queries with that side unknown.
+ *
+ * A cap URN read as a request or as a pattern is one (fromRequest, fromPattern)
+ * — which is what CapUrn.isDispatchable and CapUrn.accepts ask — and so are the
+ * questions no cap URN can spell (producing, consuming, between). Every answer
+ * is decided by the proved model (formal/CapDAG/Query.lean).
+ */
+class CapQuery {
+  constructor(formal, asked) {
+    Object.defineProperty(this, 'formal', { value: formal, enumerable: false });
+    this.asked = asked;
+    Object.freeze(this);
+  }
+
+  toString() {
+    return this.asked;
+  }
+
+  /** The cap URN `request`, read as a request: an input it leaves open is not established. */
+  static fromRequest(request) {
+    return new CapQuery(model.queryOfRequest(request.formal), `request ${request}`);
+  }
+
+  /** The cap URN `pattern`, read as a pattern over caps: an output it leaves open is not established. */
+  static fromPattern(pattern) {
+    return new CapQuery(model.queryOfPattern(pattern.formal), `pattern ${pattern}`);
+  }
+
+  /** Caps that GIVE `output`, whatever they take, with the cap-tags `tags` asks for. */
+  static producing(output, tags) {
+    return new CapQuery(
+      model.queryProducing(modelUrn(output._urn), queryTagPattern(tags)),
+      `anything giving ${output}`);
+  }
+
+  /** Caps that TAKE `input`, whatever they give: what this input can become in one step. */
+  static consuming(input, tags) {
+    return new CapQuery(
+      model.queryConsuming(modelUrn(input._urn), queryTagPattern(tags)),
+      `anything taking ${input}`);
+  }
+
+  /** Caps that take `input` and give `output`: nothing unknown. */
+  static between(input, output, tags) {
+    return new CapQuery(
+      model.queryBetween(modelUrn(input._urn), modelUrn(output._urn), queryTagPattern(tags)),
+      `anything taking ${input} and giving ${output}`);
+  }
+
+  /** Whether `cap` is guaranteed to be what is asked. */
+  admits(cap) {
+    return model.queryAdmits(this.formal, cap.formal);
+  }
+
+  /** Whether `cap` could be what is asked. */
+  mayAdmit(cap) {
+    return model.queryMayAdmit(this.formal, cap.formal);
+  }
+
+  /** How `cap` answers: one of MatchGrade. */
+  grade(cap) {
+    const answer = model.queryGrade(this.formal, cap.formal);
+    const grade = { exact: MatchGrade.EXACT, guaranteed: MatchGrade.GUARANTEED, possible: MatchGrade.POSSIBLE, none: MatchGrade.NONE }[answer.kind];
+    if (grade === undefined) {
+      throw new Error(`capdag: the model answered with a grade this mirror does not know: ${JSON.stringify(answer)}`);
+    }
+    return grade;
+  }
+}
+
 /**
  * Cap Matcher utility class
  */
@@ -1637,6 +1763,34 @@ class MediaUrn {
    */
   accepts(instance) { return this._urn.accepts(instance._urn); }
 
+  /**
+   * Whether this media type and `other` COULD describe the same value: not a
+   * guarantee (conformsTo), and not excluded. `media:ext` meets
+   * `media:ext=pdf`; `media:ext=pdf` does not meet `media:ext=png`.
+   * @param {MediaUrn} other
+   * @returns {boolean}
+   */
+  meets(other) { return this._urn.meets(other._urn); }
+
+  /**
+   * Whether a VALUE whose media this is satisfies the type `pattern`.
+   *
+   * conformsTo compares two types, and a type that does not mention a key
+   * says nothing about it. A value that exists is complete: the tags it does
+   * not have, it does not have. Use this where the receiver is the media of
+   * actual data — a stream that arrived, an output that was produced.
+   * @param {MediaUrn} pattern
+   * @returns {boolean}
+   */
+  satisfies(pattern) { return this._urn.satisfies(pattern._urn); }
+
+  /**
+   * Whether a value whose media this is COULD satisfy `pattern`.
+   * @param {MediaUrn} pattern
+   * @returns {boolean}
+   */
+  maySatisfy(pattern) { return this._urn.maySatisfy(pattern._urn); }
+
   /** @returns {number} Specificity score (tag count based) */
   specificity() { return this._urn.specificity(); }
 
@@ -2742,13 +2896,14 @@ class Cap {
   }
 
   /**
-   * Check if this capability accepts a request string
+   * Whether this capability, as a candidate, can serve the request
+   * (CapUrn.isDispatchable).
    * @param {string} request - The request string
-   * @returns {boolean} Whether this capability accepts the request
+   * @returns {boolean} Whether this capability serves the request
    */
   acceptsRequest(request) {
     const requestUrn = CapUrn.fromString(request);
-    return this.urn.accepts(requestUrn);
+    return this.urn.isDispatchable(requestUrn);
   }
 
   /**
@@ -5365,16 +5520,17 @@ class CartridgeRepoServer {
   }
 
   /**
-   * Get cartridges that provide a specific cap.
+   * Get every cartridge with a cap that can SERVE the requested URN.
    *
-   * The request URN is parsed via CapUrn.fromString. Each declared
-   * cartridge cap is parsed and matched with `conformsTo`: cap dispatch
-   * is the partial-order question "does the declared cap conform to
-   * (i.e. refine, equal, or be more specific than) the requested
-   * pattern?". Only `in` and `out` tags are semantically meaningful —
-   * no string comparison, no special role for the `op` tag. A malformed
-   * input URN throws; a malformed declared URN in the registry also
-   * throws (registry corruption is not a fallback condition).
+   * The request URN is parsed via CapUrn.fromString; each declared
+   * cartridge cap is parsed too and asked `isDispatchable` — "can this
+   * declared candidate serve the request?" (it takes at least what is
+   * sent, gives at least what is needed, has the tags asked for; a side the
+   * request leaves open is not asked about). This is deliberately looser
+   * than the equivalence used to resolve an alias to its exact cap: here
+   * everything capable is enumerated. A malformed input URN throws; a
+   * malformed declared URN in the registry also throws (registry corruption
+   * is not a fallback condition).
    */
   getCartridgesByCap(capUrn) {
     const requested = CapUrn.fromString(capUrn);
@@ -5383,7 +5539,7 @@ class CartridgeRepoServer {
       (p.cap_groups || []).some(g =>
         (g.caps || []).some(c => {
           const declared = CapUrn.fromString(c.urn);
-          return declared.conformsTo(requested);
+          return declared.isDispatchable(requested);
         })
       )
     );
@@ -6172,8 +6328,7 @@ class CartridgeJson {
    * @throws {CartridgeJsonError}
    */
   static readFromDir(versionDir, expectedSlug) {
-    const fs = require('fs');
-    const path = require('path');
+    const { fs, path } = nodeModules('reading cartridge.json');
     const jsonPath = path.join(versionDir, 'cartridge.json');
 
     if (!fs.existsSync(jsonPath)) {
@@ -6255,7 +6410,7 @@ class CartridgeJson {
    * @returns {string}
    */
   resolveEntryPoint(versionDir) {
-    const path = require('path');
+    const { path } = nodeModules('resolving an entry point');
     return path.join(versionDir, this.entry);
   }
 }
@@ -6272,9 +6427,7 @@ class CartridgeJson {
  * @returns {string} Lowercase hex SHA256.
  */
 function hashCartridgeDirectory(dir) {
-  const fs = require('fs');
-  const path = require('path');
-  const crypto = require('crypto');
+  const { fs, path, crypto } = nodeModules('hashing a cartridge directory');
 
   const files = [];
   const collect = (current) => {
@@ -6577,7 +6730,7 @@ function encodeHelloFrame() {
  * @throws {Error} when the handshake/probe fails.
  */
 function probeCartridgeCapGroups(entryPath) {
-  const { spawn } = require('child_process');
+  const { spawn } = nodeModules('probing a cartridge').childProcess;
   return new Promise((resolve, reject) => {
     let child;
     try {
@@ -6714,8 +6867,7 @@ function probeCartridgeCapGroups(entryPath) {
  * @returns {Promise<Array<DiscoveredCartridge>>}
  */
 async function discoverCartridges(cartridgesRoot, identity) {
-  const fs = require('fs');
-  const path = require('path');
+  const { fs, path } = nodeModules('discovering cartridges');
   const discovered = [];
 
   let rootStat;
@@ -6755,8 +6907,7 @@ async function discoverCartridges(cartridgesRoot, identity) {
  * Mirrors capdag::cartridge_discovery::scan_channel_root.
  */
 async function scanChannelRoot(scanRoot, expectedSlug, identity, discovered) {
-  const fs = require('fs');
-  const path = require('path');
+  const { fs, path } = nodeModules('discovering cartridges');
 
   let nameEntries;
   try {
@@ -7645,7 +7796,6 @@ class Machine {
 // ============================================================================
 
 // Load the Peggy-generated parser
-const machineParser = require('./machine-parser.js');
 
 /**
  * Assign a media URN to a node, or check consistency if already assigned.
@@ -8026,22 +8176,13 @@ class MediaRegistryEntry {
  * implementations (capdag, capdag-js, capdag-py, capdag-go, capdag-objc)
  * use this same algorithm so a URN's key is identical across languages.
  *
- * Runtime detection: `crypto.subtle` is available in browsers and
- * modern Node (≥ 16, exposed via `globalThis.crypto`); CommonJS Node
- * also has the synchronous `crypto` module. We prefer subtle for
- * portability and fall back to the Node module when subtle is absent.
+ * `crypto.subtle` is on `globalThis` in browsers and in every Node this
+ * package supports.
  */
 async function sha256Hex(s) {
   const utf8 = new TextEncoder().encode(s);
-  if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.subtle) {
-    const buf = await globalThis.crypto.subtle.digest('SHA-256', utf8);
-    return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
-  }
-  // Node CommonJS fallback. require() may throw in strict ESM contexts;
-  // we let it propagate because every supported runtime has a crypto API.
-  // eslint-disable-next-line global-require
-  const nodeCrypto = require('crypto');
-  return nodeCrypto.createHash('sha256').update(utf8).digest('hex');
+  const buf = await globalThis.crypto.subtle.digest('SHA-256', utf8);
+  return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
 }
 
 /**
@@ -8445,12 +8586,7 @@ class Manifest {
   }
 }
 
-// Unified configurable planner vocabulary (mirrors Rust plan_space.rs and the
-// PlanMachines/DiscoverConvergentTargets proto surface).
-const planner = require('./planner.js');
-
-// Export for CommonJS
-module.exports = {
+export {
   // Registry trust vocabulary — one verdict per registry, shared by every
   // cartridge that claims provenance from it.
   RegistryVerdict,
@@ -8466,24 +8602,6 @@ module.exports = {
   registryVerdictRemedy,
   MANIFEST_SIG_FORMAT,
   RELEASE_KEY_CERT_FORMAT,
-  // Planner plan-space vocabulary
-  PlanStateError: planner.PlanStateError,
-  ConvergencePresence: planner.ConvergencePresence,
-  ConvergenceLocation: planner.ConvergenceLocation,
-  ConvergenceMechanism: planner.ConvergenceMechanism,
-  ConvergenceArity: planner.ConvergenceArity,
-  DivergencePresence: planner.DivergencePresence,
-  DivergenceLocation: planner.DivergenceLocation,
-  RankPolicy: planner.RankPolicy,
-  PlanMode: planner.PlanMode,
-  PlanRequest: planner.PlanRequest,
-  parsePlanApex: planner.parsePlanApex,
-  parsePlanProfile: planner.parsePlanProfile,
-  parsePlanCost: planner.parsePlanCost,
-  parsePlanCandidate: planner.parsePlanCandidate,
-  parsePlanCandidates: planner.parsePlanCandidates,
-  parseConvergentTarget: planner.parseConvergentTarget,
-  parseConvergentTargets: planner.parseConvergentTargets,
   ALIAS_TARGET_CAP,
   ALIAS_TARGET_MEDIA,
   tokenIsUrn,
@@ -8498,6 +8616,9 @@ module.exports = {
   CapEffect,
   CapUrnBuilder,
   CapMatcher,
+  CapQuery,
+  MatchGrade,
+  gradeIsGuaranteed,
   CapUrnError,
   ErrorCodes,
   MediaUrn,
@@ -8541,7 +8662,7 @@ module.exports = {
   MEDIA_OBJECT,
   // List types
   MEDIA_LIST,
-  MEDIA_TEXTABLE_LIST: MEDIA_STRING_LIST,
+  MEDIA_STRING_LIST as MEDIA_TEXTABLE_LIST,
   MEDIA_STRING_LIST,
   MEDIA_INTEGER_LIST,
   MEDIA_NUMBER_LIST,
@@ -8705,3 +8826,25 @@ module.exports = {
   MediaRegistryEntry,
   FabricRegistryClient,
 };
+
+// Unified configurable planner vocabulary (mirrors Rust plan_space.rs and the
+// PlanMachines/DiscoverConvergentTargets proto surface).
+export {
+  PlanStateError,
+  ConvergencePresence,
+  ConvergenceLocation,
+  ConvergenceMechanism,
+  ConvergenceArity,
+  DivergencePresence,
+  DivergenceLocation,
+  RankPolicy,
+  PlanMode,
+  PlanRequest,
+  parsePlanApex,
+  parsePlanProfile,
+  parsePlanCost,
+  parsePlanCandidate,
+  parsePlanCandidates,
+  parseConvergentTarget,
+  parseConvergentTargets,
+} from './planner.js';