capdag 0.152.345 → 0.153.347

package/capdag.js

@@ -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
     };
   }
 
@@ -5409,6 +5514,11 @@ module.exports = {
   CartridgeRepoClient,
   CartridgeRepoServer,
   CartridgeChannel,
+  // Registry slug
+  DEV_SLUG,
+  SLUG_HEX_LEN,
+  slugForRegistryUrl,
+  isRegistrySlug,
   // Machine notation
   MachineSyntaxError,
   MachineSyntaxErrorCodes,

package/capdag.test.js

@@ -1646,6 +1646,7 @@ function testJS_mediaSpecConstruction() {
 const sampleRegistry = {
   schemaVersion: '5.0',
   lastUpdated: '2026-02-07T16:48:28Z',
+  registryUrl: 'https://test.example/manifest',
   channels: {
     release: { cartridges: {
     pdfcartridge: {
@@ -1785,6 +1786,7 @@ function test320_cartridgeInfoConstruction() {
   const data = {
     id: 'testcartridge',
     name: 'Test Cartridge',
+    registryUrl: 'https://test.example/manifest',
     channel: 'release',
     version: '1.0.0',
     description: 'A test',
@@ -1815,20 +1817,20 @@ function test320_cartridgeInfoConstruction() {
 
 // TEST321: CartridgeInfo.is_signed() returns true when signature is present
 function test321_cartridgeInfoIsSigned() {
-  const signed = new CartridgeInfo({id: 'test', channel: 'release', teamId: 'TEAM', signedAt: '2026-01-01', cap_groups: []});
+  const signed = new CartridgeInfo({id: 'test', registryUrl: 'https://test.example/manifest', channel: 'release', teamId: 'TEAM', signedAt: '2026-01-01', cap_groups: []});
   assert(signed.isSigned() === true, 'Cartridge with teamId and signedAt should be signed');
 
-  const unsigned1 = new CartridgeInfo({id: 'test', channel: 'release', teamId: '', signedAt: '2026-01-01', cap_groups: []});
+  const unsigned1 = new CartridgeInfo({id: 'test', registryUrl: 'https://test.example/manifest', channel: 'release', teamId: '', signedAt: '2026-01-01', cap_groups: []});
   assert(unsigned1.isSigned() === false, 'Cartridge without teamId should not be signed');
 
-  const unsigned2 = new CartridgeInfo({id: 'test', channel: 'release', teamId: 'TEAM', signedAt: '', cap_groups: []});
+  const unsigned2 = new CartridgeInfo({id: 'test', registryUrl: 'https://test.example/manifest', channel: 'release', teamId: 'TEAM', signedAt: '', cap_groups: []});
   assert(unsigned2.isSigned() === false, 'Cartridge without signedAt should not be signed');
 }
 
 // TEST322: CartridgeInfo.build_for_platform() returns the build matching the current platform
 function test322_cartridgeInfoBuildForPlatform() {
   const withBuilds = new CartridgeInfo({
-    id: 'test', channel: 'release', version: '1.0.0', cap_groups: [],
+    id: 'test', registryUrl: 'https://test.example/manifest', channel: 'release', version: '1.0.0', cap_groups: [],
     versions: {
       '1.0.0': {
         builds: [
@@ -1854,7 +1856,7 @@ function test322_cartridgeInfoBuildForPlatform() {
   assert(platforms.includes('darwin-arm64'), 'Should include darwin-arm64');
   assert(platforms.includes('linux-x86_64'), 'Should include linux-x86_64');
 
-  const noBuilds = new CartridgeInfo({id: 'test', channel: 'release', version: '1.0.0', cap_groups: [], versions: {}, availableVersions: []});
+  const noBuilds = new CartridgeInfo({id: 'test', registryUrl: 'https://test.example/manifest', channel: 'release', version: '1.0.0', cap_groups: [], versions: {}, availableVersions: []});
   assert(noBuilds.buildForPlatform('darwin-arm64') === null, 'Should return null when no versions');
   assert(noBuilds.availablePlatforms().length === 0, 'Should have no platforms');
 }
@@ -1878,7 +1880,7 @@ function test323_cartridgeRepoServerValidateRegistry() {
   // Missing channels object
   threw = false;
   try {
-    new CartridgeRepoServer({schemaVersion: '5.0'});
+    new CartridgeRepoServer({schemaVersion: '5.0', registryUrl: 'https://test.example/manifest'});
   } catch (e) {
     threw = true;
     assert(e.message.includes('channels'), 'Should reject missing channels');
@@ -1888,7 +1890,7 @@ function test323_cartridgeRepoServerValidateRegistry() {
   // Missing one of the two required channels
   threw = false;
   try {
-    new CartridgeRepoServer({schemaVersion: '5.0', channels: {release: {cartridges: {}}}});
+    new CartridgeRepoServer({schemaVersion: '5.0', registryUrl: 'https://test.example/manifest', channels: {release: {cartridges: {}}}});
   } catch (e) {
     threw = true;
     assert(e.message.includes('nightly'), 'Should require nightly channel');
@@ -2046,13 +2048,24 @@ function test330_cartridgeRepoClientUpdateCache() {
   const server = new CartridgeRepoServer(sampleRegistry);
   const cartridges = server.transformToCartridgeArray().map(p => new CartridgeInfo(p));
 
-  client.updateCache('https://example.com/api/cartridges', cartridges);
+  // Cache key is the registry URL the cartridges carry — mismatching
+  // it would orphan the entries (the new cache key is
+  // <registryUrl>:<channel>:<id>). The sampleRegistry stamps every
+  // entry with 'https://test.example/manifest'.
+  const REGISTRY_URL = 'https://test.example/manifest';
+  client.updateCache(REGISTRY_URL, cartridges);
 
-  const cache = client.caches.get('https://example.com/api/cartridges');
+  const cache = client.caches.get(REGISTRY_URL);
   assert(cache !== undefined, 'Cache should exist');
   assert(cache.cartridges.size === 3, 'Should have 3 cartridges in cache (2 release + 1 nightly)');
-  assert(cache.cartridges.has('release:pdfcartridge'), 'Should key by <channel>:<id>');
-  assert(cache.cartridges.has('nightly:jsoncartridge'), 'Should hold nightly entry independently');
+  assert(
+    cache.cartridges.has(`${REGISTRY_URL}:release:pdfcartridge`),
+    'Should key by <registryUrl>:<channel>:<id>'
+  );
+  assert(
+    cache.cartridges.has(`${REGISTRY_URL}:nightly:jsoncartridge`),
+    'Should hold nightly entry independently'
+  );
   assert(cache.capToCartridges.size > 0, 'Should have cap mappings');
 }
 
@@ -2093,27 +2106,38 @@ function test332_cartridgeRepoClientGetCartridge() {
   const server = new CartridgeRepoServer(sampleRegistry);
   const cartridges = server.transformToCartridgeArray().map(p => new CartridgeInfo(p));
 
-  client.updateCache('https://example.com/api/cartridges', cartridges);
+  const REGISTRY_URL = 'https://test.example/manifest';
+  client.updateCache(REGISTRY_URL, cartridges);
 
-  const cartridge = client.getCartridge('release', 'pdfcartridge');
+  const cartridge = client.getCartridge(REGISTRY_URL, 'release', 'pdfcartridge');
   assert(cartridge !== null && cartridge !== undefined, 'Should find cartridge in release');
   assert(cartridge.id === 'pdfcartridge', 'Should have correct ID');
   assert(cartridge.channel === 'release', 'Should report release channel');
+  assert(cartridge.registryUrl === REGISTRY_URL, 'Should report registry URL');
 
-  const json = client.getCartridge('nightly', 'jsoncartridge');
+  const json = client.getCartridge(REGISTRY_URL, 'nightly', 'jsoncartridge');
   assert(json !== null && json !== undefined, 'Should find nightly entry');
   assert(json.channel === 'nightly', 'Should report nightly channel');
 
-  const wrongChannel = client.getCartridge('nightly', 'pdfcartridge');
+  const wrongChannel = client.getCartridge(REGISTRY_URL, 'nightly', 'pdfcartridge');
   assert(wrongChannel === undefined || wrongChannel === null,
     'Should miss when looking up release id in nightly channel');
 
-  const notFound = client.getCartridge('release', 'nonexistent');
+  const notFound = client.getCartridge(REGISTRY_URL, 'release', 'nonexistent');
   assert(notFound === undefined || notFound === null, 'Should miss for unknown id');
 
+  // Two URLs that look similar but differ byte-wise are distinct
+  // registries — looking up one cartridge under the other's URL
+  // misses, even if id+channel match.
+  const wrongRegistry = client.getCartridge(
+    'https://other.example/manifest', 'release', 'pdfcartridge'
+  );
+  assert(wrongRegistry === undefined || wrongRegistry === null,
+    'Should miss when looking up under a different registry URL');
+
   let threw = false;
   try {
-    client.getCartridge('staging', 'pdfcartridge');
+    client.getCartridge(REGISTRY_URL, 'staging', 'pdfcartridge');
   } catch (e) {
     threw = true;
   }
@@ -2166,13 +2190,15 @@ function test335_cartridgeRepoServerClientIntegration() {
   // Client consumes API response
   const client = new CartridgeRepoClient(3600);
   const cartridges = apiResponse.cartridges.map(p => new CartridgeInfo(p));
-  client.updateCache('https://example.com/api/cartridges', cartridges);
+  const REGISTRY_URL = 'https://test.example/manifest';
+  client.updateCache(REGISTRY_URL, cartridges);
 
-  // Client can find cartridge by (channel, id)
-  const cartridge = client.getCartridge('release', 'pdfcartridge');
+  // Client can find cartridge by (registryUrl, channel, id)
+  const cartridge = client.getCartridge(REGISTRY_URL, 'release', 'pdfcartridge');
   assert(cartridge !== null && cartridge !== undefined, 'Client should find cartridge from server data');
   assert(cartridge.isSigned(), 'Cartridge should be signed');
   assert(cartridge.channel === 'release', 'Should report release channel');
+  assert(cartridge.registryUrl === REGISTRY_URL, 'Should report registry URL');
   assert(cartridge.buildForPlatform('darwin-arm64') !== null, 'Cartridge should have darwin-arm64 build');
 
   // Client can get suggestions

package/package.json

@@ -40,5 +40,5 @@
     "pretest": "npm run build:parser",
     "test": "node capdag.test.js"
   },
-  "version": "0.152.345"
+  "version": "0.153.347"
 }