capdag 1.226.626 → 1.233.649

package/cap-fab-renderer.js

@@ -1125,7 +1125,7 @@ function buildBrowseGraphData(capabilities) {
     // Parsing the URN canonicalizes it and validates it — fail hard on
     // malformed registry data.
     const parsedUrn = CapUrn.fromString(capData.urn);
-    const cap = createCap(parsedUrn, title, capData.command || '');
+    const cap = createCap(parsedUrn, title, capData.aliases || []);
     const capFabEdgeIndex = capFab.edges.length;
     capFab.addCap(cap, 'registry');
 

package/capdag.js

@@ -2530,21 +2530,22 @@ class Cap {
    * @param {Object|null} metadataJson - Optional arbitrary metadata as JSON object
    * @param {string|null} documentation - Optional long-form markdown documentation. Rendered in capability info panels, the cap navigator, capdag-dot-com, and anywhere else a rich-text explanation of the cap is useful.
    */
-  constructor(urn, title, command, capDescription = null, metadata = {}, metadataJson = null, documentation = null) {
+  constructor(urn, title, aliases, capDescription = null, metadata = {}, metadataJson = null, documentation = null) {
     if (!(urn instanceof CapUrn)) {
       throw new Error('URN must be a CapUrn instance');
     }
     if (!title || typeof title !== 'string') {
       throw new Error('Title is required and must be a string');
     }
-    if (!command || typeof command !== 'string') {
-      throw new Error('Command is required and must be a string');
+    if (!Array.isArray(aliases) || aliases.length === 0) {
+      throw new Error('Aliases are required and must be a non-empty array');
     }
 
     this.urn = urn;
     this.version = 0;
     this.title = title;
-    this.command = command;
+    this.aliases = aliases;
+    this.is_abstract = false;
     this.cap_description = capDescription;
     this.documentation = documentation;
     this.metadata = metadata || {};
@@ -2752,7 +2753,8 @@ class Cap {
 
     return this.urn.equals(other.urn) &&
            this.title === other.title &&
-           this.command === other.command &&
+           JSON.stringify([...this.aliases].sort()) === JSON.stringify([...other.aliases].sort()) &&
+           this.is_abstract === other.is_abstract &&
            this.cap_description === other.cap_description &&
            this.documentation === other.documentation &&
            JSON.stringify(this.metadata) === JSON.stringify(other.metadata) &&
@@ -2772,7 +2774,7 @@ class Cap {
     const result = {
       urn: this.urn.toString(),
       title: this.title,
-      command: this.command,
+      aliases: this.aliases,
       cap_description: this.cap_description,
       metadata: this.metadata,
       args: this.args.map(a => a.toJSON()),
@@ -2783,6 +2785,10 @@ class Cap {
       result.version = this.version;
     }
 
+    if (this.is_abstract) {
+      result.abstract = true;
+    }
+
     // Long-form markdown documentation. Only emitted when set, to match
     // the Rust serializer which skips this field when None.
     if (typeof this.documentation === 'string' && this.documentation.length > 0) {
@@ -2821,7 +2827,11 @@ class Cap {
     const documentation = (typeof json.documentation === 'string' && json.documentation.length > 0)
       ? json.documentation
       : null;
-    const cap = new Cap(urn, json.title, json.command, json.cap_description, json.metadata, json.metadata_json, documentation);
+    if (!Array.isArray(json.aliases) || json.aliases.length === 0) {
+      throw new Error(`cap '${json.urn}' must declare at least one alias (the 'aliases' field is required and non-empty)`);
+    }
+    const cap = new Cap(urn, json.title, json.aliases, json.cap_description, json.metadata, json.metadata_json, documentation);
+    cap.is_abstract = json.abstract === true;
     cap.version = (typeof json.version === 'number' && json.version !== 0) ? json.version : 0;
     // Parse args (new format)
     if (json.args && Array.isArray(json.args)) {
@@ -3046,20 +3056,20 @@ class CapManifest {
 /**
  * Helper functions for creating capabilities
  */
-function createCap(urn, title, command) {
-  return new Cap(urn, title, command);
+function createCap(urn, title, aliases) {
+  return new Cap(urn, title, aliases);
 }
 
-function createCapWithDescription(urn, title, command, description) {
-  return new Cap(urn, title, command, description);
+function createCapWithDescription(urn, title, aliases, description) {
+  return new Cap(urn, title, aliases, description);
 }
 
-function createCapWithMetadata(urn, title, command, metadata) {
-  return new Cap(urn, title, command, null, metadata);
+function createCapWithMetadata(urn, title, aliases, metadata) {
+  return new Cap(urn, title, aliases, null, metadata);
 }
 
-function createCapWithDescriptionAndMetadata(urn, title, command, description, metadata) {
-  return new Cap(urn, title, command, description, metadata);
+function createCapWithDescriptionAndMetadata(urn, title, aliases, description, metadata) {
+  return new Cap(urn, title, aliases, description, metadata);
 }
 
 // ============================================================================
@@ -3747,9 +3757,9 @@ class CapValidator {
       });
     }
 
-    if (!cap.command || typeof cap.command !== 'string') {
+    if (!Array.isArray(cap.aliases) || cap.aliases.length === 0) {
       throw new ValidationError('InvalidCapSchema', capUrn, {
-        issue: 'Cap must have a valid command'
+        issue: 'Cap must have at least one alias'
       });
     }
 
@@ -4355,37 +4365,55 @@ class CartridgeCapGroup {
 // in synchronous contexts must await.
 
 const DEV_SLUG = "dev";
-const SLUG_HEX_LEN = 16;
 
 /**
- * Compute the on-disk slug for a registry URL.
+ * The authority (host[:port]) of a registry URL: after `://` up to the next
+ * `/`, `?`, or `#` (path/query/fragment discarded).
+ */
+function authorityOfRegistryUrl(url) {
+  const i = url.indexOf("://");
+  const afterScheme = i >= 0 ? url.slice(i + 3) : url;
+  const m = afterScheme.search(/[/?#]/);
+  return m >= 0 ? afterScheme.slice(0, m) : afterScheme;
+}
+
+/**
+ * Compute the on-disk slug for a registry URL. Mirrors
+ * capdag::cartridge_slug::slug_for byte-for-byte: `DEV_SLUG` for null/undefined,
+ * otherwise a path-safe transform of the URL's authority (host[:port]) —
+ * ASCII-lowercased, every character outside `[a-z0-9.-]` replaced by `-`.
+ * Depends ONLY on the authority; path/version/query/trailing-slash/host-case
+ * do not change it.
  *
- * @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).
+ * @param {string|null|undefined} registryUrl
+ * @returns {string}
  */
-async function slugForRegistryUrl(registryUrl) {
+function slugForRegistryUrlSync(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");
+  let out = "";
+  for (const ch of authorityOfRegistryUrl(registryUrl)) {
+    const lc = ch >= "A" && ch <= "Z" ? ch.toLowerCase() : ch;
+    out += (lc >= "a" && lc <= "z") || (lc >= "0" && lc <= "9") || lc === "." || lc === "-" ? lc : "-";
   }
-  return hex.slice(0, SLUG_HEX_LEN);
+  return out;
+}
+
+/**
+ * Async wrapper retained for callers that `await` the slug. The computation is
+ * synchronous (no hashing) — the authority transform needs no crypto.
+ * @returns {Promise<string>}
+ */
+async function slugForRegistryUrl(registryUrl) {
+  return slugForRegistryUrlSync(registryUrl);
 }
 
 function isRegistrySlug(s) {
   return typeof s === "string"
-      && s.length === SLUG_HEX_LEN
-      && /^[0-9a-f]+$/.test(s);
+      && s.length > 0
+      && s !== DEV_SLUG
+      && /^[a-z0-9.-]+$/.test(s);
 }
 
 // =============================================================================
@@ -4744,6 +4772,18 @@ class CartridgeRepoClient {
     if (data.schemaVersion !== '5.0') {
       throw new Error(`Cartridge registry from ${repoUrl} has schemaVersion '${data.schemaVersion}'; required: 5.0`);
     }
+    // Cartridge registry regime version. v0 was the pre-versioning legacy at
+    // the bare /manifest path; this speaks only v1 at /v1/manifest. A manifest
+    // from a different regime version is rejected, not reinterpreted.
+    if (data.registryVersion !== 1) {
+      throw new Error(`Cartridge registry from ${repoUrl} has registryVersion '${data.registryVersion}'; this build speaks v1`);
+    }
+    // A cartridge registry must declare the fabric its caps resolve against. The
+    // client cross-checks this equals its own fabric (so every registry it uses
+    // shares one fabric); here we require it is at least present.
+    if (typeof data.fabricRegistryUrl !== 'string' || data.fabricRegistryUrl.length === 0) {
+      throw new Error(`Cartridge registry from ${repoUrl}: missing required 'fabricRegistryUrl' (the fabric its caps resolve against)`);
+    }
     // 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
@@ -5021,6 +5061,12 @@ class CartridgeRepoServer {
     if (this.registry.schemaVersion !== '5.0') {
       throw new Error(`Unsupported registry schema version: ${this.registry.schemaVersion}. Required: 5.0`);
     }
+    if (this.registry.registryVersion !== 1) {
+      throw new Error(`Unsupported cartridge registry version: ${this.registry.registryVersion}. This build speaks v1.`);
+    }
+    if (typeof this.registry.fabricRegistryUrl !== 'string' || this.registry.fabricRegistryUrl.length === 0) {
+      throw new Error('Registry must declare a non-empty `fabricRegistryUrl` (the fabric its caps resolve against)');
+    }
     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)');
     }
@@ -5450,24 +5496,15 @@ class InstalledCartridgeRecord {
 /**
  * Synchronous on-disk slug for a registry URL. Mirrors
  * capdag::bifaci::cartridge_slug::slug_for byte-for-byte: `null`/`undefined`
- * (a dev cartridge) → the literal `DEV_SLUG`; otherwise the first
- * SLUG_HEX_LEN lowercase-hex characters of sha256(url bytes).
- *
- * The async `slugForRegistryUrl` above uses Web Crypto for browser parity;
- * discovery runs only under Node and needs a synchronous slug in tight
- * per-file loops, so this uses Node's synchronous `crypto.createHash`. Both
- * produce identical output.
+ * (a dev cartridge) → the literal `DEV_SLUG`; otherwise a path-safe transform
+ * of the URL's authority (host[:port]). Identical output to the async
+ * `slugForRegistryUrl` above — no hashing, so both are trivially in sync.
  *
  * @param {string|null|undefined} registryUrl
  * @returns {string}
  */
 function slugForSync(registryUrl) {
-  if (registryUrl === null || registryUrl === undefined) {
-    return DEV_SLUG;
-  }
-  const crypto = require('crypto');
-  const hex = crypto.createHash('sha256').update(registryUrl, 'utf8').digest('hex');
-  return hex.slice(0, SLUG_HEX_LEN);
+  return slugForRegistryUrlSync(registryUrl);
 }
 
 /**
@@ -5838,14 +5875,21 @@ class DiscoveryIdentity {
    * @param {string|null} opts.registryUrl - Some(url) for release/nightly
    *   hosts, null for dev hosts.
    * @param {number} opts.fabricManifestVersion
+   * @param {number} opts.cartridgeRegistryVersion - The registry regime version
+   *   this host speaks; an on-disk PATH level ({slug}/v{N}/{channel}/…), pinned
+   *   like the channel so a v1 host never scans a v2 tree.
    */
-  constructor({ channel, registryUrl, fabricManifestVersion }) {
+  constructor({ channel, registryUrl, fabricManifestVersion, cartridgeRegistryVersion }) {
     if (channel !== CartridgeChannel.Release && channel !== CartridgeChannel.Nightly) {
       throw new Error(`DiscoveryIdentity: invalid channel '${channel}'`);
     }
+    if (!Number.isInteger(cartridgeRegistryVersion) || cartridgeRegistryVersion < 1) {
+      throw new Error(`DiscoveryIdentity: cartridgeRegistryVersion must be an integer >= 1, got '${cartridgeRegistryVersion}'`);
+    }
     this.channel = channel;
     this.registryUrl = registryUrl !== undefined ? registryUrl : null;
     this.fabricManifestVersion = fabricManifestVersion;
+    this.cartridgeRegistryVersion = cartridgeRegistryVersion;
   }
 
   /** This host's own baked-registry slug (`dev` when registryUrl is null). */
@@ -6175,7 +6219,9 @@ async function discoverCartridges(cartridgesRoot, identity) {
       continue;
     }
     const expectedSlug = slugEntry.name;
-    const scanRoot = path.join(slugDir, identity.channel);
+    // {slug}/v{cartridgeRegistryVersion}/{channel}/… — the registry regime
+    // version is a path level pinned to the host's version (like the channel).
+    const scanRoot = path.join(slugDir, `v${identity.cartridgeRegistryVersion}`, identity.channel);
     let scanStat;
     try { scanStat = fs.statSync(scanRoot); } catch (_e) { continue; }
     if (!scanStat.isDirectory()) continue;
@@ -7425,7 +7471,8 @@ class FabricRegistryEntry {
   constructor(data) {
     this.urn = data.urn;
     this.title = data.title || '';
-    this.command = data.command || '';
+    this.aliases = data.aliases || [];
+    this.isAbstract = data.abstract === true;
     this.description = data.cap_description || '';
     this.args = data.args || [];
     this.output = data.output || null;
@@ -7880,8 +7927,30 @@ 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 = {
+  // 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,
@@ -8087,7 +8156,7 @@ module.exports = {
   discoverCartridges,
   // Registry slug
   DEV_SLUG,
-  SLUG_HEX_LEN,
+  slugForRegistryUrlSync,
   slugForRegistryUrl,
   isRegistrySlug,
   // Machine notation

package/capdag.test.js

@@ -126,14 +126,14 @@ function test6204_Urn(tags) {
 // Helper to create a Cap for testing
 function makeCap(urnString, title) {
   const capUrn = CapUrn.fromString(urnString);
-  return new Cap(capUrn, title, 'test', title);
+  return new Cap(capUrn, title, ['test'], title);
 }
 
 // Helper to create caps with specific in/out media URNs for graph testing
 function makeGraphCap(inUrn, outUrn, title) {
   const urnString = `cap:in="${inUrn}";convert;out="${outUrn}"`;
   const capUrn = CapUrn.fromString(urnString);
-  return new Cap(capUrn, title, 'convert', title);
+  return new Cap(capUrn, title, ['convert'], title);
 }
 
 // ============================================================================
@@ -1271,7 +1271,7 @@ function test116_capArgConstructors() {
 // TEST150: JSON roundtrip
 function test150_capManifestJsonSerialization() {
   const capUrn = CapUrn.fromString(test6204_Urn('extract;target=metadata'));
-  const cap = new Cap(capUrn, 'Extract Metadata', 'extract-metadata');
+  const cap = new Cap(capUrn, 'Extract Metadata', ['extract-metadata']);
   cap.addArg(new CapArg('media:ext=pdf', true, [new ArgSource({ stdin: 'media:ext=pdf' })]));
   cap.addArg(new CapArg(
     'media:chunk-size;enc=utf-8;numeric',
@@ -1719,7 +1719,7 @@ function test6242_JS_resolveMediaUrnFromSpecs() {
 // TEST6246: J s cap j s o n serialization
 function test6246_JS_capJSONSerialization() {
   const urn = CapUrn.fromString(test6204_Urn('test'));
-  const cap = new Cap(urn, 'Test Cap', 'test_command');
+  const cap = new Cap(urn, 'Test Cap', ['test_command']);
   cap.arguments = {
     required: [{ name: 'input', media_urn: MEDIA_STRING }],
     optional: []
@@ -1742,7 +1742,7 @@ function test6246_JS_capJSONSerialization() {
 // surface as failures here.
 function test6249_JS_capDocumentationRoundTrip() {
   const urn = CapUrn.fromString(test6204_Urn('documented'));
-  const cap = new Cap(urn, 'Documented Cap', 'documented');
+  const cap = new Cap(urn, 'Documented Cap', ['documented']);
   const body = '# Documented Cap\r\n\nDoes the thing.\n\n```bash\necho "hi"\n```\n\nSee also: \u2605\n';
   cap.setDocumentation(body);
   assertEqual(cap.getDocumentation(), body, 'Setter must store the body verbatim');
@@ -1764,7 +1764,7 @@ function test6249_JS_capDocumentationRoundTrip() {
 // (which has no null sentinel) and pollute generated JSON.
 function test6253_JS_capDocumentationOmittedWhenNull() {
   const urn = CapUrn.fromString(test6204_Urn('undocumented'));
-  const cap = new Cap(urn, 'Undocumented Cap', 'undocumented');
+  const cap = new Cap(urn, 'Undocumented Cap', ['undocumented']);
   assertEqual(cap.getDocumentation(), null, 'Default documentation must be null');
 
   const json = cap.toJSON();
@@ -1854,8 +1854,10 @@ function test6269_JS_mediaDefConstruction() {
 // to assert on. Tests that need an empty channel use literals inline.
 const sampleRegistry = {
   schemaVersion: '5.0',
+  registryVersion: 1,
   lastUpdated: '2026-02-07T16:48:28Z',
   registryUrl: 'https://test.example/manifest',
+  fabricRegistryUrl: 'https://fabric.test',
   channels: {
     release: { cartridges: {
     pdfcartridge: {
@@ -2089,7 +2091,7 @@ function test323_cartridgeRepoServerValidateRegistry() {
   // Missing channels object
   threw = false;
   try {
-    new CartridgeRepoServer({schemaVersion: '5.0', registryUrl: 'https://test.example/manifest'});
+    new CartridgeRepoServer({schemaVersion: '5.0', registryVersion: 1, fabricRegistryUrl: 'https://fabric.test', registryUrl: 'https://test.example/manifest'});
   } catch (e) {
     threw = true;
     assert(e.message.includes('channels'), 'Should reject missing channels');
@@ -2099,7 +2101,7 @@ function test323_cartridgeRepoServerValidateRegistry() {
   // Missing one of the two required channels
   threw = false;
   try {
-    new CartridgeRepoServer({schemaVersion: '5.0', registryUrl: 'https://test.example/manifest', channels: {release: {cartridges: {}}}});
+    new CartridgeRepoServer({schemaVersion: '5.0', registryVersion: 1, fabricRegistryUrl: 'https://fabric.test', registryUrl: 'https://test.example/manifest', channels: {release: {cartridges: {}}}});
   } catch (e) {
     threw = true;
     assert(e.message.includes('nightly'), 'Should require nightly channel');
@@ -2581,7 +2583,9 @@ function test1874_registryUrlFromBuildEnvRejectsEmptyString() {
 function discoveryInstallFixture(root, slug, channelFolder, name, version, cartridgeJson, entry) {
   const fs = require('fs');
   const path = require('path');
-  const dir = path.join(root, slug, channelFolder, name, version);
+  // {slug}/v1/{channel}/{name}/{version} — the version level pins to the host
+  // registry version (the tests construct identities at cartridgeRegistryVersion 1).
+  const dir = path.join(root, slug, 'v1', channelFolder, name, version);
   fs.mkdirSync(dir, { recursive: true });
   if (cartridgeJson !== null && cartridgeJson !== undefined) {
     fs.writeFileSync(path.join(dir, 'cartridge.json'), cartridgeJson);
@@ -2634,7 +2638,7 @@ async function test1875_scanAllReachesBothDevAndRegistrySlugs() {
     const url = 'https://cartridges.example.com/manifest';
     const rslug = slugForSync(url);
     // Host baked for a DIFFERENT registry than the on-disk registry cartridge.
-    const host = new DiscoveryIdentity({ channel: 'nightly', registryUrl: 'https://other.example.com/manifest', fabricManifestVersion: 1 });
+    const host = new DiscoveryIdentity({ channel: 'nightly', registryUrl: 'https://other.example.com/manifest', fabricManifestVersion: 1, cartridgeRegistryVersion: 1 });
     discoveryInstallFixture(root, 'dev', 'nightly', 'devcart', '1.0.0', discoveryDevCartridgeJson('nightly', 1), 'cart');
     discoveryInstallFixture(root, rslug, 'nightly', 'regcart', '1.0.0', discoveryRegistryCartridgeJson(url, 'nightly', 1), 'cart');
     const out = await discoverCartridges(root, host);
@@ -2658,7 +2662,7 @@ async function test1876_otherChannelSubtreeIsSkipped() {
     const url = 'https://cartridges.example.com/manifest';
     const rslug = slugForSync(url);
     discoveryInstallFixture(root, rslug, 'release', 'regcart', '1.0.0', discoveryRegistryCartridgeJson(url, 'release', 1), 'cart');
-    const out = await discoverCartridges(root, new DiscoveryIdentity({ channel: 'nightly', registryUrl: null, fabricManifestVersion: 1 }));
+    const out = await discoverCartridges(root, new DiscoveryIdentity({ channel: 'nightly', registryUrl: null, fabricManifestVersion: 1, cartridgeRegistryVersion: 1 }));
     assertEqual(out.length, 0, 'a release-only slug must be invisible to a nightly host');
   } finally {
     discoveryRemoveRoot(root);
@@ -2675,7 +2679,7 @@ async function test1877_registryCartridgeUnderWrongSlugIsBadInstall() {
     const wrongSlug = slugForSync('https://somewhere-else.example.com/manifest');
     const json = discoveryRegistryCartridgeJson(url, 'nightly', 1);
     discoveryInstallFixture(root, wrongSlug, 'nightly', 'cart', '1.0.0', json, 'cart');
-    const out = await discoverCartridges(root, new DiscoveryIdentity({ channel: 'nightly', registryUrl: null, fabricManifestVersion: 1 }));
+    const out = await discoverCartridges(root, new DiscoveryIdentity({ channel: 'nightly', registryUrl: null, fabricManifestVersion: 1, cartridgeRegistryVersion: 1 }));
     discoveryExpectIncompatible(out, CartridgeAttachmentErrorKind.BAD_INSTALLATION);
   } finally {
     discoveryRemoveRoot(root);
@@ -2703,7 +2707,7 @@ async function test1878_bundledProviderWithoutBakedHashIsRejected() {
       installed_at: '2024-01-01T00:00:00Z', installed_from: 'bundle', fabric_manifest_version: 1,
     });
     discoveryInstallFixture(root, 'dev', 'nightly', 'cart', '1.0.0', json, 'cart');
-    const out = await discoverCartridges(root, new DiscoveryIdentity({ channel: 'nightly', registryUrl: null, fabricManifestVersion: 1 }));
+    const out = await discoverCartridges(root, new DiscoveryIdentity({ channel: 'nightly', registryUrl: null, fabricManifestVersion: 1, cartridgeRegistryVersion: 1 }));
     discoveryExpectIncompatible(out, CartridgeAttachmentErrorKind.BAD_INSTALLATION);
     assert(out[0].error.message.includes('bundled provider integrity'),
       `message should name the bundled-integrity failure: ${out[0].error.message}`);
@@ -2954,7 +2958,7 @@ function test6544_builderRejectsStructuralKeys() {
 // TEST1294: RULE11 - void-input cap with stdin source rejected
 function test1294_rule11VoidInputWithStdinRejected() {
   const urn = CapUrn.fromString('cap:in="media:void";test;out="media:string"');
-  const cap = new Cap(urn, 'Test', 'test-cmd');
+  const cap = new Cap(urn, 'Test', ['test-cmd']);
   const stdinSource = ArgSource.fromJSON({ stdin: 'media:string' });
   cap.args = [new CapArg('media:string', true, [stdinSource])];
   try {
@@ -2969,7 +2973,7 @@ function test1294_rule11VoidInputWithStdinRejected() {
 // TEST1295: RULE11 - non-void-input cap without stdin source rejected
 function test1295_rule11NonVoidInputWithoutStdinRejected() {
   const urn = CapUrn.fromString('cap:in="media:string";test;out="media:string"');
-  const cap = new Cap(urn, 'Test', 'test-cmd');
+  const cap = new Cap(urn, 'Test', ['test-cmd']);
   const posSource = ArgSource.fromJSON({ cli_flag: '--name' });
   cap.args = [new CapArg('media:string', true, [posSource])];
   try {
@@ -2984,7 +2988,7 @@ function test1295_rule11NonVoidInputWithoutStdinRejected() {
 // TEST1296: RULE11 - void-input cap with only cli_flag sources passes
 function test1296_rule11VoidInputCliFlagOnly() {
   const urn = CapUrn.fromString('cap:in="media:void";test;out="media:string"');
-  const cap = new Cap(urn, 'Test', 'test-cmd');
+  const cap = new Cap(urn, 'Test', ['test-cmd']);
   const flagSource = ArgSource.fromJSON({ cli_flag: '--name' });
   cap.args = [new CapArg('media:string', true, [flagSource])];
   // Should not throw
@@ -2994,7 +2998,7 @@ function test1296_rule11VoidInputCliFlagOnly() {
 // TEST1297: RULE11 - non-void-input cap with stdin source passes
 function test1297_rule11NonVoidInputWithStdin() {
   const urn = CapUrn.fromString('cap:in="media:string";test;out="media:string"');
-  const cap = new Cap(urn, 'Test', 'test-cmd');
+  const cap = new Cap(urn, 'Test', ['test-cmd']);
   const stdinSource = ArgSource.fromJSON({ stdin: 'media:string' });
   cap.args = [new CapArg('media:string', true, [stdinSource])];
   // Should not throw
@@ -4337,7 +4341,7 @@ function test6470_Machine_capRegistryEntry_defaults() {
   assertEqual(entry.urn, 'cap:in=media:;test;out=media:', 'URN should match');
   assertEqual(entry.title, '', 'Title should default to empty');
   assertEqual(entry.description, '', 'Description should default to empty');
-  assertEqual(entry.command, '', 'Command should default to empty');
+  assert(Array.isArray(entry.aliases) && entry.aliases.length === 0, 'Aliases should default to an empty array');
   assert(Array.isArray(entry.args), 'Args should default to array');
   assertEqual(entry.args.length, 0, 'Args should be empty');
 }
@@ -6337,7 +6341,7 @@ function test6736_axisWeightingDecodedLayout() {
 // TEST6737: Cap with version=0 round-trips with no `version` key on wire
 function test6737_capVersionZeroOmittedOnWire() {
   const urn = CapUrn.fromString('cap:in="media:void";test-op;out="media:enc=utf-8;record"');
-  const cap = new Cap(urn, 'Test Cap', 'test-op');
+  const cap = new Cap(urn, 'Test Cap', ['test-op']);
   // version defaults to 0
   assertEqual(cap.version, 0, 'Default version should be 0');
   const json = cap.toJSON();
@@ -6349,7 +6353,7 @@ function test6737_capVersionZeroOmittedOnWire() {
 // TEST1848: Cap with version=N round-trips with `version: N` on wire
 function test1848_capVersionNonZeroOnWire() {
   const urn = CapUrn.fromString('cap:in="media:void";versioned-op;out="media:enc=utf-8;record"');
-  const cap = new Cap(urn, 'Versioned Cap', 'versioned-op');
+  const cap = new Cap(urn, 'Versioned Cap', ['versioned-op']);
   cap.version = 42;
   const json = cap.toJSON();
   assert('version' in json, 'version!=0 must appear on wire');
@@ -6519,6 +6523,167 @@ function test1196_aliasedSerializationUsesAliasAndDropsHeader() {
 // Test runner
 // ============================================================================
 
+
+// ============================================================================
+// Unified planner plan-space (planner.js) — TEST1450+
+// ============================================================================
+
+const plannerNS = require('./planner.js');
+
+/** Planner-specific throw assertion: any PlanStateError counts. */
+function assertThrowsPlanState(fn, message) {
+  try {
+    fn();
+  } catch (error) {
+    if (error instanceof plannerNS.PlanStateError) return;
+    throw new Error(`Expected PlanStateError but got ${error.name}: ${error.message} (${message})`);
+  }
+  throw new Error(`Expected PlanStateError but function succeeded: ${message}`);
+}
+
+// TEST1450: a defaults-only request is AUTO with every knob at its default,
+// and the proto JSON carries the documented wire shape.
+function test1450_planRequestDefaults() {
+  const request = new plannerNS.PlanRequest({
+    sources: [{ mediaUrn: 'media:ext=pdf', isSequence: false }],
+    exactTargets: ['media:enc=utf-8;ext=txt'],
+  });
+  assertEqual(request.isConfigured, false, 'defaults are not configured');
+  const wire = request.toProtoJSON();
+  assertEqual(wire.mode, 0, 'AUTO mode');
+  assertEqual(wire.ranking, 0, 'intent ranking');
+  assertEqual(wire.convergence.presence, 0, 'auto presence');
+  assertEqual(wire.convergence.mechanism, 0, 'any mechanism');
+  assertEqual(wire.sources[0].media_urn, 'media:ext=pdf', 'snake_case source field');
+  assertEqual(wire.sources[0].is_sequence, false, 'snake_case sequence field');
+  assertEqual(wire.max_depth, 0, '0 = engine default depth');
+}
+
+// TEST1451: at-depth REQUIRES a positive depth; a depth anywhere else is
+// invalid; ranking never flips the request to CONFIGURED but any
+// space-constraining knob does (mode is forced to CONFIGURED on the wire).
+function test1451_planRequestKnobValidation() {
+  assertThrowsPlanState(() => new plannerNS.PlanRequest({
+    sources: [{ mediaUrn: 'media:ext=pdf', isSequence: false }],
+    exactTargets: ['media:enc=utf-8;ext=txt'],
+    convergenceLocation: 'at-depth',
+  }), 'at-depth without a depth must throw');
+
+  assertThrowsPlanState(() => new plannerNS.PlanRequest({
+    sources: [{ mediaUrn: 'media:ext=pdf', isSequence: false }],
+    exactTargets: ['media:enc=utf-8;ext=txt'],
+    convergenceAtDepth: 2,
+  }), 'a depth without at-depth must throw');
+
+  const ranked = new plannerNS.PlanRequest({
+    sources: [{ mediaUrn: 'media:ext=pdf', isSequence: false }],
+    exactTargets: ['media:enc=utf-8;ext=txt'],
+    ranking: 'shortest',
+  });
+  assertEqual(ranked.isConfigured, false, 'ranking alone never configures');
+  assertEqual(ranked.toProtoJSON().mode, 0, 'ranking alone stays AUTO');
+
+  const constrained = new plannerNS.PlanRequest({
+    sources: [{ mediaUrn: 'media:ext=pdf', isSequence: false }],
+    exactTargets: ['media:enc=utf-8;ext=txt'],
+    convergenceMechanism: 'collect',
+  });
+  assertEqual(constrained.isConfigured, true, 'a mechanism constrains');
+  assertEqual(constrained.toProtoJSON().mode, 1, 'constrained ⇒ CONFIGURED on the wire');
+
+  assertThrowsPlanState(() => new plannerNS.PlanRequest({
+    sources: [],
+    exactTargets: ['media:enc=utf-8;ext=txt'],
+  }), 'no sources must throw');
+  assertThrowsPlanState(() => new plannerNS.PlanRequest({
+    sources: [{ mediaUrn: 'media:ext=pdf', isSequence: false }],
+    exactTargets: [],
+  }), 'no targets must throw');
+}
+
+// TEST1452: every knob round-trips value → proto number → value, and an
+// unknown value/number fails hard in both directions.
+function test1452_knobProtoRoundTrip() {
+  const knobs = [
+    plannerNS.ConvergencePresence, plannerNS.ConvergenceLocation,
+    plannerNS.ConvergenceMechanism, plannerNS.ConvergenceArity,
+    plannerNS.DivergencePresence, plannerNS.DivergenceLocation,
+    plannerNS.RankPolicy, plannerNS.PlanMode,
+  ];
+  for (const knob of knobs) {
+    for (const value of knob.values) {
+      assertEqual(knob.fromProto(knob.toProto(value)), value, `${knob.name} round-trips ${value}`);
+    }
+    assertThrowsPlanState(() => knob.toProto('no-such-value'), `${knob.name} rejects unknown value`);
+    assertThrowsPlanState(() => knob.fromProto(999), `${knob.name} rejects unknown number`);
+  }
+}
+
+// TEST1453: candidate/target parsers accept realistic proto-JSON and sort
+// candidates by rank; malformed payloads (missing field, wrong type) fail
+// hard with the offending path in the message.
+function test1453_planResponseParsers() {
+  const candidates = plannerNS.parsePlanCandidates({
+    candidates: [
+      {
+        notation: '[n0 -> edge_1 -> n1]',
+        label: 'Convert each',
+        rank: 1,
+        profile: { source_media: ['media:ext=pdf'], target_media: ['media:enc=utf-8;ext=txt'], apexes: [], converged: false, diverged: false },
+        cost: { cap_steps: 2, total_steps: 2, max_leg_depth: 0, intent_score: 0.5 },
+      },
+      {
+        notation: '[(n0, n1) -> edge_0 -> n2]',
+        label: 'Combine via text',
+        rank: 0,
+        profile: {
+          source_media: ['media:ext=pdf', 'media:ext=md'],
+          target_media: ['media:enc=utf-8;ext=txt'],
+          apexes: [{ media_urn: 'media:enc=utf-8;page', mechanism: 2, depth: 1 }],
+          converged: true,
+          diverged: false,
+        },
+        cost: { cap_steps: 3, total_steps: 4, max_leg_depth: 1, intent_score: 0.8 },
+      },
+    ],
+  });
+  assertEqual(candidates.length, 2, 'two candidates');
+  assertEqual(candidates[0].rank, 0, 'sorted by rank');
+  assertEqual(candidates[0].profile.apexes[0].mechanism, 'collect', 'proto mechanism decoded to knob value');
+  assertEqual(candidates[0].profile.converged, true, 'converged carried');
+
+  assertThrowsPlanState(
+    () => plannerNS.parsePlanCandidates({ candidates: [{ label: 'missing notation', rank: 0 }] }),
+    'a candidate without notation must fail hard'
+  );
+
+  const targets = plannerNS.parseConvergentTargets({
+    targets: [
+      {
+        media_def: 'media:enc=utf-8;ext=txt',
+        display_name: 'Plain Text',
+        min_total_steps: 3,
+        apex: { media_urn: 'media:enc=utf-8;page', mechanism: 2, depth: 1 },
+        convergent: true,
+        file_extension: 'txt',
+      },
+      {
+        media_def: 'media:ext=png;image',
+        display_name: 'PNG Image',
+        min_total_steps: 2,
+        convergent: false,
+        file_extension: 'png',
+      },
+    ],
+  });
+  assertEqual(targets[0].apex.mediaUrn, 'media:enc=utf-8;page', 'apex carried');
+  assertEqual(targets[1].apex, null, 'independent target has no apex');
+  assertThrowsPlanState(
+    () => plannerNS.parseConvergentTargets({ targets: [{ display_name: 'no media_def' }] }),
+    'a target without media_def must fail hard'
+  );
+}
+
 async function runTests() {
   console.log('Running capdag-js tests...\n');
 
@@ -6987,6 +7152,13 @@ async function runTests() {
   runTest('TEST1896: cached_cap_aliases_filters_to_cap',     test1896_cachedCapAliasesFiltersToCapTargets);
   runTest('TEST1196: aliased_serialization_uses_alias',      test1196_aliasedSerializationUsesAliasAndDropsHeader);
 
+  // planner.js: unified plan-space vocabulary
+  console.log('--- planner.js ---');
+  runTest('TEST1450: plan_request_defaults', test1450_planRequestDefaults);
+  runTest('TEST1451: plan_request_knob_validation', test1451_planRequestKnobValidation);
+  runTest('TEST1452: knob_proto_round_trip', test1452_knobProtoRoundTrip);
+  runTest('TEST1453: plan_response_parsers', test1453_planResponseParsers);
+
   // Summary
   console.log(`\n${passCount + failCount} tests: ${passCount} passed, ${failCount} failed`);
   if (failCount > 0) {

package/package.json

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