capdag 1.222.603 → 1.233.649

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
@@ -3308,14 +3312,25 @@ function test6294_Machine_fanInSecondaryUnassignedGetsWildcard() {
   assertEqual(g.edges()[0].sources[1].toString(), 'media:');
 }
 
-// TEST6306: Machine loop edge
-function test6306_Machine_loopEdge() {
-  const g = Machine.fromString(
-    '[p2t cap:in="media:disbound-page;enc=utf-8";page-to-text;out="media:enc=utf-8;ext=txt"]' +
-    '[pages -> LOOP p2t -> texts]'
+// TEST6306: The retired LOOP keyword is no longer grammar. A wiring that still
+// writes `LOOP <cap>` before the cap alias no longer parses — `LOOP` is now an
+// ordinary alias, so `pages -> LOOP p2t -> texts` is two aliases in the cap
+// position with no arrow between them, which is a syntax error.
+function test6306_Machine_loopKeywordIsNotGrammar() {
+  assertThrowsWithCode(
+    () => Machine.fromString(
+      '[p2t cap:in="media:disbound-page;enc=utf-8";page-to-text;out="media:enc=utf-8;ext=txt"]' +
+      '[pages -> LOOP p2t -> texts]'
+    ),
+    MachineSyntaxErrorCodes.PARSE_ERROR
+  );
+
+  // `LOOP` on its own in the cap position parses fine — it is just an alias —
+  // but resolves to nothing, proving it carries no special meaning.
+  assertThrowsWithCode(
+    () => Machine.fromString('[pages -> LOOP -> texts]'),
+    MachineSyntaxErrorCodes.UNDEFINED_ALIAS
   );
-  assertEqual(g.edgeCount(), 1);
-  assertEqual(g.edges()[0].isLoop, true);
 }
 
 // TEST6308: Machine undefined alias fails
@@ -3416,14 +3431,16 @@ function test6331_Machine_lineBasedTwoStepChain() {
   assertEqual(g.edgeCount(), 2);
 }
 
-// TEST6334: Machine line based loop
-function test6334_Machine_lineBasedLoop() {
-  const g = Machine.fromString(
-    'p2t cap:in="media:disbound-page;enc=utf-8";page-to-text;out="media:enc=utf-8;ext=txt"\n' +
-    'pages -> LOOP p2t -> texts'
+// TEST6334: The retired LOOP keyword is not grammar in line-based mode either —
+// `pages -> LOOP p2t -> texts` is a syntax error, same as the bracketed form.
+function test6334_Machine_lineBasedLoopKeywordIsNotGrammar() {
+  assertThrowsWithCode(
+    () => Machine.fromString(
+      'p2t cap:in="media:disbound-page;enc=utf-8";page-to-text;out="media:enc=utf-8;ext=txt"\n' +
+      'pages -> LOOP p2t -> texts'
+    ),
+    MachineSyntaxErrorCodes.PARSE_ERROR
   );
-  assertEqual(g.edgeCount(), 1);
-  assertEqual(g.edges()[0].isLoop, true);
 }
 
 // TEST6337: Machine line based fan in
@@ -3835,8 +3852,12 @@ function test6415_Machine_roundtripFanOut() {
     'Fan-out round-trip failed: ' + notation);
 }
 
-// TEST6417: Machine roundtrip loop edge
-function test6417_Machine_roundtripLoopEdge() {
+// TEST6417: A per-item map (`is_loop`) edge serializes WITHOUT any LOOP marker —
+// `is_loop` is a derived cardinality property, not authored notation text. The
+// pure-JS parse path has no cap definitions to re-derive cardinality, so the
+// reparsed edge has `isLoop === false`; editors get the derived value from the
+// engine, not from re-parsing.
+function test6417_Machine_loopEdgeSerializesWithoutLoopText() {
   const original = new Machine([new MachineEdge(
     [MediaUrn.fromString('media:disbound-page;enc=utf-8')],
     CapUrn.fromString('cap:in="media:disbound-page;enc=utf-8";page-to-text;out="media:enc=utf-8;ext=txt"'),
@@ -3844,9 +3865,17 @@ function test6417_Machine_roundtripLoopEdge() {
     true
   )]);
   const notation = original.toMachineNotation();
+  assert(!notation.includes('LOOP'), 'serialized notation must not contain the retired LOOP keyword');
+
   const reparsed = Machine.fromString(notation);
-  assert(original.isEquivalent(reparsed), 'Loop round-trip failed');
-  assertEqual(reparsed.edges()[0].isLoop, true, 'isLoop must be preserved');
+  assertEqual(reparsed.edgeCount(), 1);
+  assertEqual(reparsed.edges()[0].isLoop, false,
+    'pure-JS parse path cannot derive cardinality — isLoop defaults to false');
+  // The structural payload (sources, cap, target) round-trips intact.
+  assert(reparsed.edges()[0].capUrn.isEquivalent(original.edges()[0].capUrn),
+    'cap URN must round-trip');
+  assert(reparsed.edges()[0].target.isEquivalent(original.edges()[0].target),
+    'target media must round-trip');
 }
 
 // TEST6419: Machine serialization is deterministic
@@ -4203,16 +4232,21 @@ function test6462_Machine_toMermaid_linearChain() {
   assert(mermaid.includes('(['), 'Should have stadium shape nodes');
 }
 
-// TEST6463: Machine to mermaid loop edge
+// TEST6463: Mermaid renders a per-item map (`is_loop`) edge with a dotted line
+// — `is_loop` is a kept render property — but emits NO "LOOP" text, since that
+// keyword is retired. The loop edge is built programmatically because the
+// grammar no longer has any way to author one.
 function test6463_Machine_toMermaid_loopEdge() {
-  const machine = Machine.fromString(
-    '[p2t cap:in="media:disbound-page;enc=utf-8";page-to-text;out="media:enc=utf-8;ext=txt"]' +
-    '[pages -> LOOP p2t -> texts]'
-  );
+  const machine = new Machine([new MachineEdge(
+    [MediaUrn.fromString('media:disbound-page;enc=utf-8')],
+    CapUrn.fromString('cap:in="media:disbound-page;enc=utf-8";page-to-text;out="media:enc=utf-8;ext=txt"'),
+    MediaUrn.fromString('media:enc=utf-8;ext=txt'),
+    true
+  )]);
   const mermaid = machine.toMermaid();
-  assert(mermaid.includes('LOOP'), 'Should include LOOP label');
-  assert(mermaid.includes('-.'), 'Should use dotted line for LOOP');
-  assert(mermaid.includes('.->'), 'Should use dotted arrow for LOOP');
+  assert(!mermaid.includes('LOOP'), 'Must not emit the retired LOOP label');
+  assert(mermaid.includes('-.'), 'Should use dotted line for the per-item map edge');
+  assert(mermaid.includes('.->'), 'Should use dotted arrow for the per-item map edge');
 }
 
 // TEST6464: Machine to mermaid empty graph
@@ -4307,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');
 }
@@ -6307,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();
@@ -6319,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');
@@ -6489,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');
 
@@ -6749,7 +6944,7 @@ async function runTests() {
   runTest('MACHINE:fan_out', test6290_Machine_fanOut);
   runTest('MACHINE:fan_in_secondary_assigned_by_prior_wiring', test6292_Machine_fanInSecondaryAssignedByPriorWiring);
   runTest('MACHINE:fan_in_secondary_unassigned_gets_wildcard', test6294_Machine_fanInSecondaryUnassignedGetsWildcard);
-  runTest('MACHINE:loop_edge', test6306_Machine_loopEdge);
+  runTest('MACHINE:loop_keyword_is_not_grammar', test6306_Machine_loopKeywordIsNotGrammar);
   runTest('MACHINE:undefined_alias_fails', test6308_Machine_undefinedAliasFails);
   runTest('MACHINE:node_alias_collision', test6310_Machine_nodeAliasCollision);
   runTest('MACHINE:conflicting_media_types_fail', test6312_Machine_conflictingMediaTypesFail);
@@ -6762,7 +6957,7 @@ async function runTests() {
   console.log('\n--- machine/parser.rs (line-based) ---');
   runTest('MACHINE:line_based_simple_chain', test6327_Machine_lineBasedSimpleChain);
   runTest('MACHINE:line_based_two_step_chain', test6331_Machine_lineBasedTwoStepChain);
-  runTest('MACHINE:line_based_loop', test6334_Machine_lineBasedLoop);
+  runTest('MACHINE:line_based_loop_keyword_is_not_grammar', test6334_Machine_lineBasedLoopKeywordIsNotGrammar);
   runTest('MACHINE:line_based_fan_in', test6337_Machine_lineBasedFanIn);
   runTest('MACHINE:mixed_bracketed_and_line_based', test6341_Machine_mixedBracketedAndLineBased);
   runTest('MACHINE:line_based_equivalent_to_bracketed', test6345_Machine_lineBasedEquivalentToBracketed);
@@ -6797,7 +6992,7 @@ async function runTests() {
   runTest('MACHINE:roundtrip_single_edge', test6410_Machine_roundtripSingleEdge);
   runTest('MACHINE:roundtrip_two_edge_chain', test6413_Machine_roundtripTwoEdgeChain);
   runTest('MACHINE:roundtrip_fan_out', test6415_Machine_roundtripFanOut);
-  runTest('MACHINE:roundtrip_loop_edge', test6417_Machine_roundtripLoopEdge);
+  runTest('MACHINE:loop_edge_serializes_without_loop_text', test6417_Machine_loopEdgeSerializesWithoutLoopText);
   runTest('MACHINE:serialization_is_deterministic', test6419_Machine_serializationIsDeterministic);
   runTest('MACHINE:reordered_edges_produce_same_notation', test6421_Machine_reorderedEdgesProduceSameNotation);
   runTest('MACHINE:multiline_serialize_format', test6429_Machine_multilineSerializeFormat);
@@ -6957,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) {