capdag 0.152.345 → 0.157.363

package/capdag.js

@@ -3142,13 +3142,13 @@ class CapArgumentValue {
 
 
 // ============================================================================
-// CAP GRAPH - Directed graph of capability conversions
+// CAPFAB - Directed graph of capability conversions
 // ============================================================================
 
 /**
  * An edge in the capability graph representing a conversion from one media URN to another.
  */
-class CapGraphEdge {
+class CapFabEdge {
   /**
    * @param {string} fromUrn - The input media URN
    * @param {string} toUrn - The output media URN
@@ -3168,7 +3168,7 @@ class CapGraphEdge {
 /**
  * Statistics about a capability graph.
  */
-class CapGraphStats {
+class CapFabStats {
   /**
    * @param {number} nodeCount - Number of unique media URN nodes
    * @param {number} edgeCount - Number of edges (capabilities)
@@ -3187,7 +3187,7 @@ class CapGraphStats {
  * A directed graph where nodes are media URNs and edges are capabilities.
  * This graph enables discovering conversion paths between different media formats.
  */
-class CapGraph {
+class CapFab {
   constructor() {
     this.edges = [];
     this.outgoing = new Map();  // fromUrn -> edge indices
@@ -3211,7 +3211,7 @@ class CapGraph {
 
     // Create edge
     const edgeIndex = this.edges.length;
-    const edge = new CapGraphEdge(fromUrn, toUrn, cap, registryName, specificity);
+    const edge = new CapFabEdge(fromUrn, toUrn, cap, registryName, specificity);
     this.edges.push(edge);
 
     // Update outgoing index
@@ -3237,7 +3237,7 @@ class CapGraph {
 
   /**
    * Get all edges in the graph.
-   * @returns {CapGraphEdge[]}
+   * @returns {CapFabEdge[]}
    */
   getEdges() {
     return [...this.edges];
@@ -3247,7 +3247,7 @@ class CapGraph {
    * Get all edges where the provided URN satisfies the edge's input requirement.
    * Uses conformsTo-based matching instead of exact string matching.
    * @param {string} urn - The media URN
-   * @returns {CapGraphEdge[]}
+   * @returns {CapFabEdge[]}
    */
   getOutgoing(urn) {
     // Use TaggedUrn matching: find all edges where the provided URN (instance)
@@ -3268,7 +3268,7 @@ class CapGraph {
   /**
    * Get all edges targeting a media URN.
    * @param {string} urn - The media URN
-   * @returns {CapGraphEdge[]}
+   * @returns {CapFabEdge[]}
    */
   getIncoming(urn) {
     const indices = this.incoming.get(urn) || [];
@@ -3289,7 +3289,7 @@ class CapGraph {
    * Get all direct edges from one URN to another, sorted by specificity (highest first).
    * @param {string} fromUrn - The source media URN
    * @param {string} toUrn - The target media URN
-   * @returns {CapGraphEdge[]}
+   * @returns {CapFabEdge[]}
    */
   getDirectEdges(fromUrn, toUrn) {
     const edges = this.getOutgoing(fromUrn).filter(edge => edge.toUrn === toUrn);
@@ -3338,7 +3338,7 @@ class CapGraph {
    * Find the shortest conversion path from one URN to another.
    * @param {string} fromUrn - The source media URN
    * @param {string} toUrn - The target media URN
-   * @returns {CapGraphEdge[]|null} Array of edges representing the path, or null if no path exists
+   * @returns {CapFabEdge[]|null} Array of edges representing the path, or null if no path exists
    */
   findPath(fromUrn, toUrn) {
     if (fromUrn === toUrn) {
@@ -3393,7 +3393,7 @@ class CapGraph {
    * @param {string} fromUrn - The source media URN
    * @param {string} toUrn - The target media URN
    * @param {number} maxDepth - Maximum path length to search
-   * @returns {CapGraphEdge[][]} Array of paths (each path is an array of edges)
+   * @returns {CapFabEdge[][]} Array of paths (each path is an array of edges)
    */
   findAllPaths(fromUrn, toUrn, maxDepth) {
     if (!this.nodes.has(fromUrn) || !this.nodes.has(toUrn)) {
@@ -3447,7 +3447,7 @@ class CapGraph {
    * @param {string} fromUrn - The source media URN
    * @param {string} toUrn - The target media URN
    * @param {number} maxDepth - Maximum path length to search
-   * @returns {CapGraphEdge[]|null} Array of edges representing the best path, or null if no path exists
+   * @returns {CapFabEdge[]|null} Array of edges representing the best path, or null if no path exists
    */
   findBestPath(fromUrn, toUrn, maxDepth) {
     const allPaths = this.findAllPaths(fromUrn, toUrn, maxDepth);
@@ -3488,10 +3488,10 @@ class CapGraph {
 
   /**
    * Get statistics about the graph.
-   * @returns {CapGraphStats}
+   * @returns {CapFabStats}
    */
   stats() {
-    return new CapGraphStats(
+    return new CapFabStats(
       this.nodes.size,
       this.edges.length,
       this.outgoing.size,
@@ -3613,6 +3613,54 @@ class CartridgeCapGroup {
   }
 }
 
+// =============================================================================
+// Cartridge registry slug
+// =============================================================================
+//
+// Deterministic mapping from a registry URL to a top-level folder
+// name under the cartridges install root. Mirrors
+// capdag::cartridge_slug byte-for-byte: SHA-256 of the URL bytes,
+// lowercase hex, first 16 chars. The literal string "dev" is
+// reserved for dev cartridges that have no registry.
+//
+// JS uses Web Crypto's SubtleCrypto for SHA-256. The function is
+// async because `crypto.subtle.digest` returns a Promise; consumers
+// in synchronous contexts must await.
+
+const DEV_SLUG = "dev";
+const SLUG_HEX_LEN = 16;
+
+/**
+ * Compute the on-disk slug for a registry URL.
+ *
+ * @param {string|null|undefined} registryUrl - The registry URL, or
+ *   null/undefined for dev installs.
+ * @returns {Promise<string>} The slug — `DEV_SLUG` for null,
+ *   otherwise the first 16 lowercase-hex characters of
+ *   sha256(registryUrl).
+ */
+async function slugForRegistryUrl(registryUrl) {
+  if (registryUrl === null || registryUrl === undefined) {
+    return DEV_SLUG;
+  }
+  const bytes = new TextEncoder().encode(registryUrl);
+  // Web Crypto exposes SHA-256 via crypto.subtle. Node 16+ exposes
+  // it through globalThis.crypto.subtle.
+  const digestBuffer = await crypto.subtle.digest("SHA-256", bytes);
+  const digestBytes = new Uint8Array(digestBuffer);
+  let hex = "";
+  for (const b of digestBytes) {
+    hex += b.toString(16).padStart(2, "0");
+  }
+  return hex.slice(0, SLUG_HEX_LEN);
+}
+
+function isRegistrySlug(s) {
+  return typeof s === "string"
+      && s.length === SLUG_HEX_LEN
+      && /^[0-9a-f]+$/.test(s);
+}
+
 /**
  * Cartridge information from registry
  */
@@ -3640,6 +3688,16 @@ class CartridgeInfo {
       throw new Error(`CartridgeInfo ${data.id || '?'}: invalid or missing channel '${data.channel}'`);
     }
     this.channel = data.channel;
+    // Registry URL: verbatim string the registry was fetched from.
+    // Required and non-empty — every CartridgeInfo carries the URL of
+    // the registry that served it so downstream consumers can build
+    // the (registryUrl, channel, id) identity tuple without
+    // re-deriving it. The registry transformer stamps this onto every
+    // entry at flatten time.
+    if (typeof data.registryUrl !== 'string' || data.registryUrl.length === 0) {
+      throw new Error(`CartridgeInfo ${data.id || '?'}: registryUrl is required and must be a non-empty string`);
+    }
+    this.registryUrl = data.registryUrl;
   }
 
   /** All caps flattened across all cap_groups, deduplicated by URN */
@@ -3688,9 +3746,13 @@ class CartridgeInfo {
 }
 
 /**
- * Cartridge suggestion for a missing cap. `channel` reports which
- * channel the suggesting cartridge lives in so consumers can render
- * the release/nightly distinction.
+ * Cartridge suggestion for a missing cap.
+ *
+ * `(registryUrl, channel, cartridgeId)` is the suggesting
+ * cartridge's full identity — installs of the same id from
+ * different registries × channels are independent records and the
+ * client keeps both visible. `registryUrl` is required and
+ * non-empty; suggestions never come from dev installs.
  */
 class CartridgeSuggestion {
   constructor(data) {
@@ -3706,25 +3768,29 @@ class CartridgeSuggestion {
       throw new Error(`CartridgeSuggestion: invalid or missing channel '${data.channel}'`);
     }
     this.channel = data.channel;
+    if (typeof data.registryUrl !== 'string' || data.registryUrl.length === 0) {
+      throw new Error("CartridgeSuggestion: registryUrl is required and must be a non-empty string");
+    }
+    this.registryUrl = data.registryUrl;
   }
 }
 
 /**
  * Cartridge registry cache entry. The cartridges map is keyed by
- * `<channel>:<id>` so the same id can independently coexist in both
- * channels.
+ * `<registryUrl>:<channel>:<id>` so the same id can independently
+ * coexist across multiple registries × both channels.
  */
 class CartridgeRepoCache {
   constructor(repoUrl) {
-    this.cartridges = new Map(); // "<channel>:<id>" -> CartridgeInfo
-    this.capToCartridges = new Map(); // cap_urn -> [{channel, id}]
+    this.cartridges = new Map(); // "<registryUrl>:<channel>:<id>" -> CartridgeInfo
+    this.capToCartridges = new Map(); // cap_urn -> [{registryUrl, channel, id}]
     this.lastUpdated = Date.now();
     this.repoUrl = repoUrl;
   }
 }
 
-function _cacheKey(channel, id) {
-  return `${channel}:${id}`;
+function _cacheKey(registryUrl, channel, id) {
+  return `${registryUrl}:${channel}:${id}`;
 }
 
 /**
@@ -3756,6 +3822,21 @@ class CartridgeRepoClient {
     if (data.schemaVersion !== '5.0') {
       throw new Error(`Cartridge registry from ${repoUrl} has schemaVersion '${data.schemaVersion}'; required: 5.0`);
     }
+    // Self-referential check: the manifest declares its own URL via
+    // `registryUrl`. It must match the URL we just fetched from
+    // byte-for-byte — a mismatch is a manifest-corruption signal
+    // (publisher wrote the wrong URL, or manifest is being served
+    // from an unexpected mirror). Identity downstream depends on
+    // this string; refuse to ingest on mismatch.
+    if (typeof data.registryUrl !== 'string' || data.registryUrl.length === 0) {
+      throw new Error(`Cartridge registry from ${repoUrl}: missing required top-level 'registryUrl' field`);
+    }
+    if (data.registryUrl !== repoUrl) {
+      throw new Error(
+        `Cartridge registry from ${repoUrl}: declared registryUrl '${data.registryUrl}' ` +
+        `does not match the URL it was fetched from. These must match byte-for-byte.`
+      );
+    }
     if (!data.channels || typeof data.channels !== 'object') {
       throw new Error(`Cartridge registry from ${repoUrl}: missing channels object`);
     }
@@ -3771,7 +3852,12 @@ class CartridgeRepoClient {
           ...c,
           id,
           version: c.latestVersion,
-          channel
+          channel,
+          // Stamp registryUrl onto every entry — verbatim from the
+          // registry self-reference (which we just verified equals
+          // the fetched URL). Identity comparison downstream is
+          // byte equality.
+          registryUrl: data.registryUrl
         }));
       }
     }
@@ -3794,7 +3880,10 @@ class CartridgeRepoClient {
     const cache = new CartridgeRepoCache(repoUrl);
 
     for (const cartridge of cartridges) {
-      cache.cartridges.set(_cacheKey(cartridge.channel, cartridge.id), cartridge);
+      cache.cartridges.set(
+        _cacheKey(cartridge.registryUrl, cartridge.channel, cartridge.id),
+        cartridge
+      );
 
       for (const cap of cartridge.allCaps()) {
         const normalized = CapUrn.fromString(cap.urn).toString();
@@ -3802,6 +3891,7 @@ class CartridgeRepoClient {
           cache.capToCartridges.set(normalized, []);
         }
         cache.capToCartridges.get(normalized).push({
+          registryUrl: cartridge.registryUrl,
           channel: cartridge.channel,
           id: cartridge.id
         });
@@ -3866,7 +3956,7 @@ class CartridgeRepoClient {
       if (!refs) continue;
 
       for (const ref of refs) {
-        const cartridge = cache.cartridges.get(_cacheKey(ref.channel, ref.id));
+        const cartridge = cache.cartridges.get(_cacheKey(ref.registryUrl, ref.channel, ref.id));
         if (!cartridge) continue;
 
         const capInfo = cartridge.allCaps().find(c => {
@@ -3891,7 +3981,8 @@ class CartridgeRepoClient {
           latestVersion: cartridge.version,
           repoUrl: cache.repoUrl,
           pageUrl: pageUrl,
-          channel: cartridge.channel
+          channel: cartridge.channel,
+          registryUrl: cartridge.registryUrl
         }));
       }
     }
@@ -3928,16 +4019,23 @@ class CartridgeRepoClient {
   }
 
   /**
-   * Get cartridge info by `(channel, id)`. Channel is required —
-   * the same id can independently exist in both channels with
-   * different metadata. Returns `null` when not found.
+   * Get cartridge info by `(registryUrl, channel, id)`. All three
+   * are required — the same id can independently exist across
+   * multiple registries × both channels with different metadata.
+   * Returns `null` when not found. `registryUrl` is the verbatim
+   * URL the cache was indexed under.
    */
-  getCartridge(channel, cartridgeId) {
+  getCartridge(registryUrl, channel, cartridgeId) {
+    if (typeof registryUrl !== 'string' || registryUrl.length === 0) {
+      throw new Error('getCartridge: registryUrl must be a non-empty string');
+    }
     if (channel !== 'release' && channel !== 'nightly') {
       throw new Error(`Invalid channel '${channel}' — must be 'release' or 'nightly'`);
     }
-    const key = _cacheKey(channel, cartridgeId);
-    for (const cache of this.caches.values()) {
+    const key = _cacheKey(registryUrl, channel, cartridgeId);
+    // Cache outer key is also the registry URL, so look up directly.
+    const cache = this.caches.get(registryUrl);
+    if (cache) {
       const cartridge = cache.cartridges.get(key);
       if (cartridge) {
         return cartridge;
@@ -4001,6 +4099,9 @@ class CartridgeRepoServer {
     if (this.registry.schemaVersion !== '5.0') {
       throw new Error(`Unsupported registry schema version: ${this.registry.schemaVersion}. Required: 5.0`);
     }
+    if (typeof this.registry.registryUrl !== 'string' || this.registry.registryUrl.length === 0) {
+      throw new Error('Registry must have a non-empty top-level `registryUrl` field (self-referential URL)');
+    }
     const channels = this.registry.channels;
     if (!channels || typeof channels !== 'object') {
       throw new Error('Registry must have a channels object');
@@ -4082,7 +4183,11 @@ class CartridgeRepoServer {
       tags: cartridge.tags,
       versions: cartridge.versions,
       availableVersions,
-      channel
+      channel,
+      // Stamp the manifest's self-referential URL onto every entry —
+      // verbatim from the registry. Identity comparison downstream is
+      // byte equality.
+      registryUrl: this.registry.registryUrl
     };
   }
 
@@ -5078,16 +5183,16 @@ class MachineBuilder {
   }
 
   /**
-   * Add a linear chain of edges from CapGraphEdge[] (from CapGraph.findAllPaths).
+   * Add a linear chain of edges from CapFabEdge[] (from CapFab.findAllPaths).
    *
-   * Each CapGraphEdge has fromUrn, toUrn, and cap (with cap.urn).
+   * Each CapFabEdge has fromUrn, toUrn, and cap (with cap.urn).
    * This converts the path into a series of MachineEdges.
    *
-   * @param {CapGraphEdge[]} capGraphEdges - Array of CapGraphEdge from pathfinding
+   * @param {CapFabEdge[]} capFabEdges - Array of CapFabEdge from pathfinding
    * @returns {MachineBuilder} this (for chaining)
    */
-  addCapGraphPath(capGraphEdges) {
-    for (const edge of capGraphEdges) {
+  addCapFabPath(capFabEdges) {
+    for (const edge of capFabEdges) {
       const source = MediaUrn.fromString(edge.fromUrn);
       const target = MediaUrn.fromString(edge.toUrn);
       this._edges.push(new MachineEdge([source], edge.cap.urn, target, false));
@@ -5396,9 +5501,9 @@ module.exports = {
   mediaUrnForType,
   modelAvailabilityUrn,
   modelPathUrn,
-  CapGraphEdge,
-  CapGraphStats,
-  CapGraph,
+  CapFabEdge,
+  CapFabStats,
+  CapFab,
   StdinSource,
   StdinSourceKind,
   // Cartridge Repository
@@ -5409,6 +5514,11 @@ module.exports = {
   CartridgeRepoClient,
   CartridgeRepoServer,
   CartridgeChannel,
+  // Registry slug
+  DEV_SLUG,
+  SLUG_HEX_LEN,
+  slugForRegistryUrl,
+  isRegistrySlug,
   // Machine notation
   MachineSyntaxError,
   MachineSyntaxErrorCodes,