capdag 0.184.465 → 0.187.479

package/RULES.md

@@ -72,33 +72,33 @@ Examples:
 
 ## Validation Rules
 
-### XV5: No Redefinition of Registry Media Specs
+### XV5: No Redefinition of Registry Media Defs
 
-Inline media specs in a capability's `media_specs` table must not redefine media specs that already exist in the global registry or built-in specs.
+Inline media defs in a capability's `media_defs` table must not redefine media defs that already exist in the global registry or built-in specs.
 
 ```javascript
-const { validateNoMediaSpecRedefinitionSync, MEDIA_STRING } = require('capdag');
+const { validateNoMediaDefRedefinitionSync, MEDIA_STRING } = require('capdag');
 
 // This will fail - MEDIA_STRING is a built-in spec
-const mediaSpecs = {
+const mediaDefs = {
   [MEDIA_STRING]: { media_type: 'text/plain', title: 'My String' }
 };
-const result = validateNoMediaSpecRedefinitionSync(mediaSpecs);
+const result = validateNoMediaDefRedefinitionSync(mediaDefs);
 // result: { valid: false, error: 'XV5: ...', redefines: ['media:textable'] }
 
 // This is allowed - custom spec that doesn't exist
 const customSpecs = {
   'media:my-custom-type': { media_type: 'application/json', title: 'My Type' }
 };
-const customResult = validateNoMediaSpecRedefinitionSync(customSpecs);
+const customResult = validateNoMediaDefRedefinitionSync(customSpecs);
 // result: { valid: true }
 ```
 
 For server-side validation with registry access, use the async version:
 ```javascript
-const { validateNoMediaSpecRedefinition } = require('capdag');
+const { validateNoMediaDefRedefinition } = require('capdag');
 
-const result = await validateNoMediaSpecRedefinition(mediaSpecs, {
+const result = await validateNoMediaDefRedefinition(mediaDefs, {
   registryLookup: async (urn) => await mediaStore.get(urn) !== null
 });
 ```

package/build-browser.js

@@ -141,9 +141,9 @@ window.OutputValidator = OutputValidator;
 window.CapValidator = CapValidator;
 window.validateCapArgs = validateCapArgs;
 window.RESERVED_CLI_FLAGS = RESERVED_CLI_FLAGS;
-window.MediaSpec = MediaSpec;
-window.MediaSpecError = MediaSpecError;
-window.MediaSpecErrorCodes = MediaSpecErrorCodes;
+window.MediaDef = MediaDef;
+window.MediaDefError = MediaDefError;
+window.MediaDefErrorCodes = MediaDefErrorCodes;
 window.isBinaryCapUrn = isBinaryCapUrn;
 window.isJSONCapUrn = isJSONCapUrn;
 window.isStructuredCapUrn = isStructuredCapUrn;

package/cap-fab-renderer.js

@@ -742,7 +742,7 @@ function validateStrandStep(step, path) {
       throw new Error(`CapFabRenderer: ${path}.step_type.Cap.output_is_sequence must be a boolean`);
     }
   } else {
-    assertString(body.media_spec, `${path}.step_type.${variant}.media_spec`);
+    assertString(body.media_def, `${path}.step_type.${variant}.media_def`);
   }
 }
 
@@ -750,8 +750,8 @@ function validateStrandPayload(data) {
   if (!data || typeof data !== 'object') {
     throw new Error('CapFabRenderer strand mode: data must be an object');
   }
-  assertString(data.source_spec, 'strand mode data.source_spec');
-  assertString(data.target_spec, 'strand mode data.target_spec');
+  assertString(data.source_media_urn, 'strand mode data.source_media_urn');
+  assertString(data.target_media_urn, 'strand mode data.target_media_urn');
   assertArray(data.steps, 'strand mode data.steps');
   data.steps.forEach((step, idx) => {
     validateStrandStep(step, `strand mode data.steps[${idx}]`);
@@ -789,6 +789,18 @@ function validateBodyOutcome(outcome, path) {
   }
 }
 
+function validateRunIOItem(item, path) {
+  assertObject(item, path);
+  assertString(item.label, `${path}.label`);
+  assertString(item.path, `${path}.path`);
+  if (typeof item.is_directory !== 'boolean') {
+    throw new Error(`CapFabRenderer run mode: ${path}.is_directory must be a boolean`);
+  }
+  if (typeof item.file_count !== 'number' || item.file_count < 0) {
+    throw new Error(`CapFabRenderer run mode: ${path}.file_count must be a non-negative number`);
+  }
+}
+
 function validateRunPayload(data) {
   if (!data || typeof data !== 'object') {
     throw new Error('CapFabRenderer run mode: data must be an object');
@@ -812,6 +824,23 @@ function validateRunPayload(data) {
   if (typeof data.total_body_count !== 'number' || data.total_body_count < 0) {
     throw new Error('CapFabRenderer run mode: data.total_body_count must be a non-negative number');
   }
+  if (data.input_items !== undefined) {
+    assertArray(data.input_items, 'run mode data.input_items');
+    data.input_items.forEach((item, idx) => {
+      validateRunIOItem(item, `run mode data.input_items[${idx}]`);
+    });
+  }
+  if (data.input_runs !== undefined) {
+    assertArray(data.input_runs, 'run mode data.input_runs');
+    data.input_runs.forEach((run, idx) => {
+      assertObject(run, `run mode data.input_runs[${idx}]`);
+      validateRunIOItem(run.input, `run mode data.input_runs[${idx}].input`);
+      assertArray(run.outputs, `run mode data.input_runs[${idx}].outputs`);
+      run.outputs.forEach((output, outIdx) => {
+        validateRunIOItem(output, `run mode data.input_runs[${idx}].outputs[${outIdx}]`);
+      });
+    });
+  }
 }
 
 function validateEditorGraphPayload(data) {
@@ -1087,7 +1116,7 @@ function classifyStrandCapSteps(steps) {
 //     edge to body_entry, and prev_node_id becomes body_exit.
 //
 // Node labels come from the `media_display_names` map keyed by the
-// step's canonical URN (or source_spec/target_spec for the boundary
+// step's canonical URN (or source_media_urn/target_media_urn for the boundary
 // nodes). ForEach and Collect nodes display "for each" / "collect".
 // Cap edges carry the cap title plus cardinality marker when either
 // input or output is a sequence.
@@ -1095,8 +1124,8 @@ function buildStrandGraphData(data) {
   validateStrandPayload(data);
 
   const mediaDisplayNames = data.media_display_names || {};
-  const sourceSpec = canonicalMediaUrn(data.source_spec);
-  const targetSpec = canonicalMediaUrn(data.target_spec);
+  const sourceMediaUrn = canonicalMediaUrn(data.source_media_urn);
+  const targetMediaUrn = canonicalMediaUrn(data.target_media_urn);
 
   // Look up a display name for a media URN via the host-supplied map.
   // Uses `MediaUrn.isEquivalent` so tag-order variation doesn't defeat
@@ -1151,9 +1180,9 @@ function buildStrandGraphData(data) {
     edgeCounter++;
   }
 
-  // Entry node — the strand's source media spec.
+  // Entry node — the strand's source media def.
   const inputSlotId = 'input_slot';
-  addNode(inputSlotId, displayNameFor(sourceSpec), sourceSpec, 'strand-source');
+  addNode(inputSlotId, displayNameFor(sourceMediaUrn), sourceMediaUrn, 'strand-source');
 
   let prevNodeId = inputSlotId;
 
@@ -1311,7 +1340,7 @@ function buildStrandGraphData(data) {
 
   // Final output node. Mirrors plan_builder.rs:430-432.
   const outputId = 'output';
-  addNode(outputId, displayNameFor(targetSpec), targetSpec, 'strand-target');
+  addNode(outputId, displayNameFor(targetMediaUrn), targetMediaUrn, 'strand-target');
   addEdge(prevNodeId, outputId, '', '', '', 'strand-cap-edge');
 
   // Return the raw plan-builder topology. Strand mode collapses
@@ -1319,7 +1348,7 @@ function buildStrandGraphData(data) {
   // `strandCytoscapeElements`); run mode keeps them as explicit
   // nodes because body replicas anchor at the ForEach/Collect
   // junctions.
-  return { nodes, edges, sourceSpec, targetSpec };
+  return { nodes, edges, sourceMediaUrn, targetMediaUrn };
 }
 
 // Transform the plan-builder strand topology into the render shape
@@ -1349,7 +1378,7 @@ function buildStrandGraphData(data) {
 //      post-collect cap's `input_is_sequence=true` flag.
 //
 //   4. If the last cap step's `to_spec` is semantically equivalent
-//      to the strand's `target_spec` (via MediaUrn.isEquivalent),
+//      to the strand's `target_media_urn` (via MediaUrn.isEquivalent),
 //      the separate `output` target node is dropped and the last
 //      cap edge lands on that merged endpoint. Removes the visible
 //      duplicate node.
@@ -1548,8 +1577,255 @@ function stripRunBackboneReplicaNodes(built, dropStepIds) {
   return {
     nodes: keptNodes,
     edges: keptEdges,
-    sourceSpec: built.sourceSpec,
-    targetSpec: built.targetSpec,
+    sourceMediaUrn: built.sourceMediaUrn,
+    targetMediaUrn: built.targetMediaUrn,
+  };
+}
+
+function emptyRunBackbone() {
+  return {
+    nodes: [],
+    edges: [],
+    sourceMediaUrn: '',
+    targetMediaUrn: '',
+  };
+}
+
+function buildExternalInputRunGraphData(
+  data,
+  inputRuns,
+  allOutcomes,
+  visibleSuccess,
+  visibleFailure,
+  hiddenSuccessCount,
+  hiddenFailureCount,
+  displayNameFor
+) {
+  if (inputRuns.length <= 1 || allOutcomes.length === 0) return null;
+
+  const capSteps = data.resolved_strand.steps
+    .filter(step => Object.keys(step.step_type)[0] === 'Cap')
+    .map(step => step.step_type.Cap);
+  if (capSteps.length === 0) {
+    throw new Error('CapFabRenderer run mode: external multi-input runs require at least one Cap step in resolved_strand.');
+  }
+
+  const visibleOutcomes = visibleSuccess.concat(visibleFailure);
+  const CapUrn = requireHostDependency('CapUrn');
+  const sourceCanonical = canonicalMediaUrn(data.resolved_strand.source_media_urn);
+  const targetCanonical = canonicalMediaUrn(data.resolved_strand.target_media_urn);
+  const anchorNodeId = 'external-input-anchor';
+  const replicaNodes = [{
+    group: 'nodes',
+    data: {
+      id: anchorNodeId,
+      label: displayNameFor(sourceCanonical),
+      fullUrn: sourceCanonical,
+    },
+    classes: 'strand-source',
+  }];
+  const replicaEdges = [];
+  const showMoreNodes = [];
+
+  for (const outcome of allOutcomes) {
+    if (outcome.body_index >= inputRuns.length) {
+      throw new Error(
+        `CapFabRenderer run mode: body_outcomes[body_index=${outcome.body_index}] exceeds input_runs length ${inputRuns.length}`
+      );
+    }
+  }
+
+  function buildReplica(outcome) {
+    const runDef = inputRuns[outcome.body_index];
+    const success = outcome.success;
+    const nodeClass = success ? 'body-success' : 'body-failure';
+    const edgeClass = success ? 'body-success' : 'body-failure';
+    const edgeColor = success ? 'var(--graph-body-edge-success)' : 'var(--graph-body-edge-failure)';
+    const bodyKey = `external-body-${outcome.body_index}`;
+    const sourceNodeId = `${bodyKey}-input`;
+    const sourceLabel = typeof outcome.title === 'string' && outcome.title.length > 0
+      ? outcome.title
+      : runDef.input.label;
+
+    replicaNodes.push({
+      group: 'nodes',
+      data: {
+        id: sourceNodeId,
+        label: sourceLabel,
+        fullUrn: runDef.input.path,
+        bodyIndex: outcome.body_index,
+        bodyTitle: sourceLabel,
+      },
+      classes: `${nodeClass} run-input-item`,
+    });
+    replicaEdges.push({
+      group: 'edges',
+      data: {
+        id: `${bodyKey}-entry`,
+        source: anchorNodeId,
+        target: sourceNodeId,
+        label: '',
+        title: runDef.input.path,
+        fullUrn: '',
+        color: getCssVar('--graph-edge-color'),
+        bodyIndex: outcome.body_index,
+      },
+      classes: edgeClass,
+    });
+
+    let traceEnd = capSteps.length;
+    if (!success) {
+      if (typeof outcome.failed_cap === 'string' && outcome.failed_cap.length > 0) {
+        const failedCap = CapUrn.fromString(outcome.failed_cap);
+        traceEnd = 0;
+        for (let i = 0; i < capSteps.length; i++) {
+          const candidate = CapUrn.fromString(capSteps[i].cap_urn);
+          if (candidate.isEquivalent(failedCap)) {
+            traceEnd = i + 1;
+            break;
+          }
+        }
+      } else {
+        traceEnd = 0;
+      }
+    }
+
+    let prevNodeId = sourceNodeId;
+    for (let i = 0; i < traceEnd; i++) {
+      const cap = capSteps[i];
+      const targetMedia = canonicalMediaUrn(i === capSteps.length - 1 ? data.resolved_strand.target_media_urn : data.resolved_strand.steps.filter(step => Object.keys(step.step_type)[0] === 'Cap')[i].to_spec);
+      const isLastExecutedStep = i === traceEnd - 1;
+      const outputs = success ? runDef.outputs : [];
+
+      if (success && isLastExecutedStep && outputs.length > 0) {
+        outputs.forEach((output, outputIdx) => {
+          const outputNodeId = `${bodyKey}-output-${outputIdx}`;
+          replicaNodes.push({
+            group: 'nodes',
+            data: {
+              id: outputNodeId,
+              label: output.label,
+              fullUrn: output.path,
+              bodyIndex: outcome.body_index,
+              bodyTitle: sourceLabel,
+            },
+            classes: nodeClass,
+          });
+          replicaEdges.push({
+            group: 'edges',
+            data: {
+              id: `${bodyKey}-output-edge-${i}-${outputIdx}`,
+              source: prevNodeId,
+              target: outputNodeId,
+              label: outputIdx === 0 ? cap.title : '',
+              title: cap.title,
+              fullUrn: cap.cap_urn,
+              color: edgeColor,
+              bodyIndex: outcome.body_index,
+            },
+            classes: edgeClass,
+          });
+        });
+        return;
+      }
+
+      const stepNodeId = `${bodyKey}-step-${i}`;
+      replicaNodes.push({
+        group: 'nodes',
+        data: {
+          id: stepNodeId,
+          label: displayNameFor(isLastExecutedStep ? targetCanonical : targetMedia),
+          fullUrn: isLastExecutedStep ? targetCanonical : targetMedia,
+          bodyIndex: outcome.body_index,
+          bodyTitle: sourceLabel,
+        },
+        classes: nodeClass,
+      });
+      replicaEdges.push({
+        group: 'edges',
+        data: {
+          id: `${bodyKey}-step-edge-${i}`,
+          source: prevNodeId,
+          target: stepNodeId,
+          label: cap.title,
+          title: cap.title,
+          fullUrn: cap.cap_urn,
+          color: edgeColor,
+          bodyIndex: outcome.body_index,
+        },
+        classes: edgeClass,
+      });
+      prevNodeId = stepNodeId;
+    }
+  }
+
+  visibleOutcomes.forEach(buildReplica);
+
+  if (hiddenSuccessCount > 0) {
+    showMoreNodes.push({
+      group: 'nodes',
+      data: {
+        id: 'show-more-success',
+        label: `+${hiddenSuccessCount} more succeeded`,
+        fullUrn: '',
+        showMoreGroup: 'success',
+        hiddenCount: hiddenSuccessCount,
+      },
+      classes: 'show-more body-success',
+    });
+    replicaEdges.push({
+      group: 'edges',
+      data: {
+        id: 'show-more-success-edge',
+        source: anchorNodeId,
+        target: 'show-more-success',
+        label: '',
+        title: '',
+        fullUrn: '',
+        color: 'var(--graph-body-edge-success)',
+      },
+      classes: 'body-success',
+    });
+  }
+  if (hiddenFailureCount > 0) {
+    showMoreNodes.push({
+      group: 'nodes',
+      data: {
+        id: 'show-more-failure',
+        label: `+${hiddenFailureCount} failed`,
+        fullUrn: '',
+        showMoreGroup: 'failure',
+        hiddenCount: hiddenFailureCount,
+      },
+      classes: 'show-more body-failure',
+    });
+    replicaEdges.push({
+      group: 'edges',
+      data: {
+        id: 'show-more-failure-edge',
+        source: anchorNodeId,
+        target: 'show-more-failure',
+        label: '',
+        title: '',
+        fullUrn: '',
+        color: 'var(--graph-body-edge-failure)',
+      },
+      classes: 'body-failure',
+    });
+  }
+
+  return {
+    strandBuilt: emptyRunBackbone(),
+    replicaNodes,
+    replicaEdges,
+    showMoreNodes,
+    totals: {
+      hiddenSuccessCount,
+      hiddenFailureCount,
+      totalBodyCount: data.total_body_count,
+      visibleSuccessCount: visibleSuccess.length,
+      visibleFailureCount: visibleFailure.length,
+    },
   };
 }
 
@@ -1566,19 +1842,36 @@ function buildRunGraphData(data) {
   const strandBuiltRaw = buildStrandGraphData(strandInput);
   let strandBuiltCollapsed = collapseStrandShapeTransitions(strandBuiltRaw);
 
-  // Run mode overrides the input_slot node's label with the
-  // host-supplied `source_display` (runtime input filename).
-  // Strand mode ignores this field so the abstract graph shows
-  // the media spec's title from `media_display_names`.
-  if (typeof data.source_display === 'string' && data.source_display.length > 0) {
-    strandBuiltCollapsed = {
-      nodes: strandBuiltCollapsed.nodes.map(n =>
-        n.id === 'input_slot' ? Object.assign({}, n, { label: data.source_display }) : n),
-      edges: strandBuiltCollapsed.edges,
-      sourceSpec: strandBuiltCollapsed.sourceSpec,
-      targetSpec: strandBuiltCollapsed.targetSpec,
-    };
-  }
+  const inputItems = Array.isArray(data.input_items) ? data.input_items : [];
+  const inputRuns = Array.isArray(data.input_runs) ? data.input_runs : [];
+  const inputReplicaNodes = [];
+  const inputReplicaEdges = [];
+  inputItems.forEach((item, idx) => {
+    const nodeId = `input-item-${idx}`;
+    inputReplicaNodes.push({
+      group: 'nodes',
+      data: {
+        id: nodeId,
+        label: item.label,
+        fullUrn: item.path,
+        inputIndex: idx,
+        inputPath: item.path,
+      },
+      classes: 'run-input-item',
+    });
+    inputReplicaEdges.push({
+      group: 'edges',
+      data: {
+        id: `input-item-edge-${idx}`,
+        source: nodeId,
+        target: 'input_slot',
+        label: '',
+        title: item.path,
+        fullUrn: '',
+        color: getCssVar('--graph-edge-color'),
+      },
+    });
+  });
 
   // Locate the ForEach/Collect span in the raw steps. Positional
   // IDs survive the collapse (node IDs are `step_${i}` from the
@@ -1605,6 +1898,36 @@ function buildRunGraphData(data) {
   const hiddenFailureCount = failures.length - visibleFailure.length;
   const visibleOutcomes = visibleSuccess.concat(visibleFailure);
 
+  // Look up a display name for a media URN via the host-supplied
+  // `media_display_names` map. Uses `MediaUrn.isEquivalent` for
+  // semantic URN equality.
+  const MediaUrn = requireHostDependency('MediaUrn');
+  const mediaDisplayNames = data.media_display_names || {};
+  const displayEntries = [];
+  for (const [urn, display] of Object.entries(mediaDisplayNames)) {
+    if (typeof display !== 'string' || display.length === 0) continue;
+    try {
+      displayEntries.push({ media: MediaUrn.fromString(urn), display });
+    } catch (_) { /* ignore malformed keys */ }
+  }
+  function displayNameFor(canonicalUrn) {
+    return requireExplicitDisplayName(canonicalUrn, displayEntries, 'run node');
+  }
+
+  const externalInputRunBuilt = buildExternalInputRunGraphData(
+    data,
+    inputRuns,
+    allOutcomes,
+    visibleSuccess,
+    visibleFailure,
+    hiddenSuccessCount,
+    hiddenFailureCount,
+    displayNameFor
+  );
+  if (externalInputRunBuilt !== null) {
+    return externalInputRunBuilt;
+  }
+
   // Per-body replicas only fire when there's a ForEach AND at
   // least one visible outcome. Without outcomes, the strand
   // backbone renders the "plan preview" unchanged.
@@ -1628,8 +1951,8 @@ function buildRunGraphData(data) {
   if (!shouldExpand) {
     return {
       strandBuilt: strandBuiltCollapsed,
-      replicaNodes: [],
-      replicaEdges: [],
+      replicaNodes: inputReplicaNodes,
+      replicaEdges: inputReplicaEdges,
       showMoreNodes: [],
       totals: {
         hiddenSuccessCount,
@@ -1664,7 +1987,7 @@ function buildRunGraphData(data) {
   // labels the anchor→entry edge on the first body.
   //
   // Without such a preceding sequence cap, the source itself is
-  // already a list (e.g. `media:pdf;list` source_spec) and the
+  // already a list (e.g. `media:pdf;list` source_media_urn) and the
   // ForEach iterates it directly.
   let seqProducerStepIdx = -1;
   let seqProducerStep = null;
@@ -1729,24 +2052,10 @@ function buildRunGraphData(data) {
 
   const replicaNodes = [];
   const replicaEdges = [];
+  replicaNodes.push(...inputReplicaNodes);
+  replicaEdges.push(...inputReplicaEdges);
   let replicasBuiltCount = 0;
 
-  // Look up a display name for a media URN via the host-supplied
-  // `media_display_names` map. Uses `MediaUrn.isEquivalent` for
-  // semantic URN equality.
-  const MediaUrn = requireHostDependency('MediaUrn');
-  const mediaDisplayNames = data.media_display_names || {};
-  const displayEntries = [];
-  for (const [urn, display] of Object.entries(mediaDisplayNames)) {
-    if (typeof display !== 'string' || display.length === 0) continue;
-    try {
-      displayEntries.push({ media: MediaUrn.fromString(urn), display });
-    } catch (_) { /* ignore malformed keys */ }
-  }
-  function displayNameFor(canonicalUrn) {
-    return requireExplicitDisplayName(canonicalUrn, displayEntries, 'run node');
-  }
-
   // The per-body "entry" node represents one item of the
   // sequence being iterated. Its URN is:
   //   * the sequence producer cap's `to_spec` (if such a cap