capdag 1.426.27 → 1.439.69

package/README.md

@@ -28,10 +28,10 @@ imported, so importing it waits for that (top-level `await`), and a CommonJS
 import { CapUrn, CapUrnBuilder } from "capdag";
 
 const parsed = CapUrn.fromString(
-  'cap:disbind;in="media:ext=pdf";out="media:enc=utf-8;page"'
+  'cap:disbind;in="media:document;ext=pdf";out="media:enc=utf-8;page"'
 );
 const built = new CapUrnBuilder()
-  .inSpec("media:ext=pdf")
+  .inSpec("media:document;ext=pdf")
   .outSpec("media:enc=utf-8;page")
   .marker("disbind")
   .build();
@@ -42,11 +42,63 @@ console.log(parsed.toString() === built.toString());
 Treat URNs as opaque parsed values. Use the package's predicates for
 equivalence, conformance, dispatch, and ranking instead of string surgery.
 
+## Read and write Machine Notation
+
+A machine is read against the definitions of the caps it names: they say what
+each step takes and gives, by name and by type, and what a constant written in
+the machine is held to.
+
+```javascript
+import { Cap, CapArg, CapOutput, ArgSource, CapUrn, CapDefinitions, parseMachine } from "capdag";
+
+const extract = new Cap(
+  CapUrn.fromString('cap:in="media:document;ext=pdf";extract;out="media:enc=utf-8;ext=txt"'),
+  "Extract Text", ["extract"]
+);
+extract.addArg(new CapArg("media:document;ext=pdf", "document", true,
+  [new ArgSource({ stdin: "media:document;ext=pdf" })]));
+extract.addOutput(new CapOutput("media:enc=utf-8;ext=txt", "text", "The text"));
+
+const definitions = new CapDefinitions().addCaps([extract]);
+const machine = parseMachine(
+  '[extract cap:in="media:document;ext=pdf";extract;out="media:enc=utf-8;ext=txt"]' +
+  "[(document=pdf) -> extract -> text]",
+  definitions
+);
+console.log(machine.toMachineNotation());
+```
+
+The definitions can come from the fabric registry instead. A client reads one
+manifest of it — a pinned version, or the one the registry has promoted as its
+latest — fetches each definition it needs, holds each cap to the definition
+rules as it reads it, and then serves as the definitions a machine is parsed
+against, fabric aliases included:
+
+```javascript
+import { FabricRegistryClient, parseMachine } from "capdag";
+
+const fabric = await FabricRegistryClient.latest("https://fabric.capdag.com");
+await fabric.getCap('cap:in="media:document;ext=pdf";extract;out="media:enc=utf-8;ext=txt"');
+const machine = parseMachine(
+  '[extract cap:in="media:document;ext=pdf";extract;out="media:enc=utf-8;ext=txt"]' +
+  "[pdf -> extract -> text]",
+  fabric
+);
+```
+
+`parseMachineWithAST` also returns every statement with where each part of it
+stands in the text, and the name the text gave each node. A machine that names
+other machines in step position is read with a `MachineSource`
+(`MapMachineSource`, or `FileMachineSource` under Node.js). Anything with
+`capDefinition(urn)` and `mediaDefinition(urn)` can stand in for
+`CapDefinitions`.
+
 ## Find the relevant API
 
-- `capdag.js` provides URNs, definitions, dispatch, and matching.
+- `capdag.js` provides URNs, definitions, dispatch, matching, and Machine
+  Notation: reading, resolving and writing machines.
 - `machine-parser.js` is generated from `machine.pegjs`.
-- `planner.js` provides planning and Machine Notation structures.
+- `planner.js` provides the planner's request and result vocabulary.
 - `cap-fab-renderer.js` (`capdag/cap-fab-renderer`) renders graphs; the page
   provides cytoscape and cytoscape-elk.
 - `formal/` is the generated model code, with its WebAssembly program.

package/cap-fab-renderer.js

@@ -28,7 +28,7 @@
 //   * cytoscape-elk extension (registers itself on `cytoscape`)
 //   * elkjs (via cytoscape-elk)
 //   * TaggedUrn (from tagged-urn browser build)
-//   * CapUrn, MediaUrn, Cap, createCap, CapFab (from capdag.js)
+//   * CapUrn, MediaUrn, Cap, CapFab (from capdag.js)
 //
 // The renderer owns its own theme observer (<html data-theme>) so hosts do
 // nothing to drive theme sync. It owns its own tooltip element and its own
@@ -41,7 +41,7 @@
 // uses a different name for the same concept, the fix is at the producer,
 // not here.
 
-import { CapUrn, CapFab, MediaUrn, createCap } from './capdag.js';
+import { Cap, CapUrn, CapFab, MediaUrn } from './capdag.js';
 
 // =============================================================================
 // Host dependencies — the page's: cytoscape and cytoscape-elk, loaded as
@@ -72,10 +72,27 @@ function cardinalityLabel(input_is_sequence, output_is_sequence) {
   return `${lhs}\u2192${rhs}`;
 }
 
+// The main output of a cap as it appears in the /api/capabilities JSON: the
+// one of its `outputs` whose media URN is the cap URN's `out=`, compared as
+// media URNs. Null for a cap that declares none (its `out=` is media:void).
+function mainOutputOf(cap) {
+  const outputs = cap.outputs || [];
+  if (!Array.isArray(outputs)) {
+    throw new Error('CapFabRenderer: a cap\'s outputs are a list');
+  }
+  if (outputs.length === 0) return null;
+  const outSpec = MediaUrn.fromString(CapUrn.fromString(cap.urn).getOutSpec());
+  const main = outputs.find(output =>
+    output && typeof output.media_urn === 'string' &&
+    MediaUrn.fromString(output.media_urn).isEquivalent(outSpec)
+  );
+  return main || null;
+}
+
 // Compute the cardinality marker for a cap as it appears in the
 // /api/capabilities JSON. The main input arg is the one whose sources
-// include a stdin source. Matches core Rust `CapArg.is_sequence` and
-// `CapOutput.is_sequence` names exactly.
+// include a stdin source; the output is the cap's MAIN output. Matches core
+// Rust `CapArg.is_sequence` and `CapOutput.is_sequence` names exactly.
 function cardinalityFromCap(cap) {
   if (!cap || typeof cap !== 'object') {
     throw new Error('CapFabRenderer: cardinalityFromCap requires a cap object');
@@ -85,7 +102,8 @@ function cardinalityFromCap(cap) {
     arg && arg.sources && arg.sources.some(src => src && src.stdin !== undefined)
   );
   const input_is_sequence = mainArg ? (mainArg.is_sequence === true) : false;
-  const output_is_sequence = (cap.output && cap.output.is_sequence === true) || false;
+  const mainOutput = mainOutputOf(cap);
+  const output_is_sequence = mainOutput !== null && mainOutput.is_sequence === true;
   return cardinalityLabel(input_is_sequence, output_is_sequence);
 }
 
@@ -440,8 +458,8 @@ function buildStylesheet() {
 
   // Machine mode uses a dedicated palette exposed by the notation
   // editor's CSS (`--graph-node-color`, `--graph-loop-color`,
-  // `--graph-edge-color`, `--graph-text`, `--graph-muted`). Caps
-  // are collapsed into edges so there's no cap-node color.
+  // `--graph-edge-color`, `--graph-text`, `--graph-muted`). A step
+  // node of the resolved machine is outlined in the edge color.
   const machineNodeColor = getCssVar('--graph-node-color');
   const machineLoopColor = getCssVar('--graph-loop-color');
   const machineEdgeColor = getCssVar('--graph-edge-color');
@@ -626,11 +644,12 @@ function buildStylesheet() {
     // -------- Machine / editor-graph mode ------------------------------
     // Shared between the resolved-machine view (`mode: 'machine'`,
     // canonical `Machine::to_render_payload_json`) and the notation
-    // editor's live graph (`mode: 'editor-graph'`, ast-driven). Both
-    // collapse each cap application into a single labeled edge
-    // between its input and output data slots — caps do NOT appear
-    // as separate nodes. Only data slots are nodes; cap semantics
-    // are carried on edges.
+    // editor's live graph (`mode: 'editor-graph'`, ast-driven). Data
+    // slots are `machine-node`s. The editor graph collapses each cap
+    // application into labeled edges between its data slots; the
+    // resolved machine draws each step as a `machine-step` node, and a
+    // constant it is given as a `machine-constant` node, with an edge
+    // per binding and per output taken.
     //
     // Reads the editor's dedicated palette so nodes, edges and
     // loop markers match the text theme.
@@ -660,6 +679,34 @@ function buildStylesheet() {
         'line-style': 'dashed',
       },
     },
+    {
+      selector: 'node.machine-step',
+      style: {
+        'shape': 'rectangle',
+        'background-color': nodeBg,
+        'border-color': machineEdgeColor || 'data(color)',
+        'color': machineText || nodeText,
+        'border-opacity': 1,
+      },
+    },
+    {
+      selector: 'node.machine-step-loop',
+      style: {
+        'border-color': machineLoopColor || nodeBorderActive,
+        'border-style': 'dashed',
+      },
+    },
+    {
+      selector: 'node.machine-constant',
+      style: {
+        'shape': 'tag',
+        'padding': '6px',
+        'border-width': '1px',
+        'background-color': nodeBg,
+        'border-color': machineMuted || nodeBorder,
+        'color': machineMuted || nodeText,
+      },
+    },
   ];
 }
 
@@ -974,73 +1021,115 @@ function validateEditorGraphPayload(data) {
   });
 }
 
-// `validateResolvedMachinePayload` checks the canonical machine
-// render payload produced by Rust `Machine::to_render_payload_json`.
+// `validateResolvedMachinePayload` checks the canonical machine render
+// payload every capdag library writes (`Machine.to_render_payload_json`).
 // Shape:
 //   {
 //     "strands": [
 //       {
-//         "nodes": [{"id": "n0", "urn": "media:ext=pdf"}, ...],
+//         "nodes": [{"id": "n0", "urn": "media:document;ext=pdf", "title": "PDF"}, ...],
 //         "edges": [{
 //           "alias": "edge_0",
 //           "cap_urn": "...",
+//           "title": "Extract Text",
 //           "is_loop": false,
-//           "assignment": [{"cap_arg_media_urn": "media:ext=pdf", "source_node": "n0"}, ...],
-//           "target_node": "n1"
+//           "retry": 0,
+//           "on_error": "fail",
+//           "included_as": [],
+//           "assignment": [
+//             {"cap_arg_media_urn": "media:document;ext=pdf", "arg_name": "input", "source_node": "n0"},
+//             {"cap_arg_media_urn": "media:integer;window", "arg_name": "window", "constant": 20}
+//           ],
+//           "outputs": [{"output_media_urn": "media:...", "output_name": "output", "node": "n1"}]
 //         }, ...],
 //         "input_anchor_nodes": ["n0"],
-//         "output_anchor_nodes": ["n2"]
+//         "output_anchor_nodes": ["n1"]
 //       },
 //       ...
 //     ]
 //   }
+//
+// A binding is fed by a node of its strand or by a constant, never both and
+// never neither. A step with no binding is a source, one with no output a
+// sink. Every node a binding, an output or an anchor names is a node of the
+// strand.
 function validateResolvedMachinePayload(data) {
   if (!data || typeof data !== 'object') {
     throw new Error('CapFabRenderer machine mode: data must be an object');
   }
   assertArray(data.strands, 'machine mode data.strands');
   data.strands.forEach((strand, sIdx) => {
+    const at = `machine mode data.strands[${sIdx}]`;
     if (!strand || typeof strand !== 'object') {
-      throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}] is not an object`);
+      throw new Error(`CapFabRenderer ${at} is not an object`);
     }
-    assertArray(strand.nodes, `machine mode data.strands[${sIdx}].nodes`);
+    assertArray(strand.nodes, `${at}.nodes`);
+    const nodeIds = new Set();
     strand.nodes.forEach((n, nIdx) => {
       if (!n || typeof n !== 'object') {
-        throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}].nodes[${nIdx}] is not an object`);
+        throw new Error(`CapFabRenderer ${at}.nodes[${nIdx}] is not an object`);
       }
-      assertString(n.id, `machine mode data.strands[${sIdx}].nodes[${nIdx}].id`);
-      assertString(n.urn, `machine mode data.strands[${sIdx}].nodes[${nIdx}].urn`);
-      assertString(n.title, `machine mode data.strands[${sIdx}].nodes[${nIdx}].title`);
+      assertString(n.id, `${at}.nodes[${nIdx}].id`);
+      assertString(n.urn, `${at}.nodes[${nIdx}].urn`);
+      assertString(n.title, `${at}.nodes[${nIdx}].title`);
+      nodeIds.add(n.id);
     });
-    assertArray(strand.edges, `machine mode data.strands[${sIdx}].edges`);
+    const assertNode = (id, path) => {
+      assertString(id, path);
+      if (!nodeIds.has(id)) {
+        throw new Error(`CapFabRenderer ${path} names "${id}", which is no node of the strand`);
+      }
+    };
+    assertArray(strand.edges, `${at}.edges`);
     strand.edges.forEach((e, eIdx) => {
+      const edgeAt = `${at}.edges[${eIdx}]`;
       if (!e || typeof e !== 'object') {
-        throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}].edges[${eIdx}] is not an object`);
+        throw new Error(`CapFabRenderer ${edgeAt} is not an object`);
       }
-      assertString(e.alias, `machine mode data.strands[${sIdx}].edges[${eIdx}].alias`);
-      assertString(e.cap_urn, `machine mode data.strands[${sIdx}].edges[${eIdx}].cap_urn`);
-      assertString(e.title, `machine mode data.strands[${sIdx}].edges[${eIdx}].title`);
+      assertString(e.alias, `${edgeAt}.alias`);
+      assertString(e.cap_urn, `${edgeAt}.cap_urn`);
+      assertString(e.title, `${edgeAt}.title`);
       if (typeof e.is_loop !== 'boolean') {
-        throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}].edges[${eIdx}].is_loop must be boolean`);
+        throw new Error(`CapFabRenderer ${edgeAt}.is_loop must be boolean`);
+      }
+      if (!Number.isInteger(e.retry) || e.retry < 0) {
+        throw new Error(`CapFabRenderer ${edgeAt}.retry must be a whole number of further attempts`);
+      }
+      if (e.on_error !== 'fail' && e.on_error !== 'absent') {
+        throw new Error(`CapFabRenderer ${edgeAt}.on_error must be "fail" or "absent"`);
       }
-      assertArray(e.assignment, `machine mode data.strands[${sIdx}].edges[${eIdx}].assignment`);
+      assertArray(e.included_as, `${edgeAt}.included_as`);
+      e.included_as.forEach((step, iIdx) => assertString(step, `${edgeAt}.included_as[${iIdx}]`));
+      assertArray(e.assignment, `${edgeAt}.assignment`);
       e.assignment.forEach((b, bIdx) => {
+        const bindingAt = `${edgeAt}.assignment[${bIdx}]`;
         if (!b || typeof b !== 'object') {
-          throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}].edges[${eIdx}].assignment[${bIdx}] is not an object`);
+          throw new Error(`CapFabRenderer ${bindingAt} is not an object`);
         }
-        assertString(b.cap_arg_media_urn, `machine mode data.strands[${sIdx}].edges[${eIdx}].assignment[${bIdx}].cap_arg_media_urn`);
-        assertString(b.source_node, `machine mode data.strands[${sIdx}].edges[${eIdx}].assignment[${bIdx}].source_node`);
+        assertString(b.cap_arg_media_urn, `${bindingAt}.cap_arg_media_urn`);
+        assertString(b.arg_name, `${bindingAt}.arg_name`);
+        const byNode = Object.prototype.hasOwnProperty.call(b, 'source_node');
+        const byConstant = Object.prototype.hasOwnProperty.call(b, 'constant');
+        if (byNode === byConstant) {
+          throw new Error(`CapFabRenderer ${bindingAt} must have exactly one of source_node and constant`);
+        }
+        if (byNode) assertNode(b.source_node, `${bindingAt}.source_node`);
+      });
+      assertArray(e.outputs, `${edgeAt}.outputs`);
+      e.outputs.forEach((o, oIdx) => {
+        const outputAt = `${edgeAt}.outputs[${oIdx}]`;
+        if (!o || typeof o !== 'object') {
+          throw new Error(`CapFabRenderer ${outputAt} is not an object`);
+        }
+        assertString(o.output_media_urn, `${outputAt}.output_media_urn`);
+        assertString(o.output_name, `${outputAt}.output_name`);
+        assertNode(o.node, `${outputAt}.node`);
       });
-      assertString(e.target_node, `machine mode data.strands[${sIdx}].edges[${eIdx}].target_node`);
-    });
-    assertArray(strand.input_anchor_nodes, `machine mode data.strands[${sIdx}].input_anchor_nodes`);
-    strand.input_anchor_nodes.forEach((id, iIdx) => {
-      assertString(id, `machine mode data.strands[${sIdx}].input_anchor_nodes[${iIdx}]`);
-    });
-    assertArray(strand.output_anchor_nodes, `machine mode data.strands[${sIdx}].output_anchor_nodes`);
-    strand.output_anchor_nodes.forEach((id, oIdx) => {
-      assertString(id, `machine mode data.strands[${sIdx}].output_anchor_nodes[${oIdx}]`);
     });
+    assertArray(strand.input_anchor_nodes, `${at}.input_anchor_nodes`);
+    strand.input_anchor_nodes.forEach((id, iIdx) => assertNode(id, `${at}.input_anchor_nodes[${iIdx}]`));
+    assertArray(strand.output_anchor_nodes, `${at}.output_anchor_nodes`);
+    strand.output_anchor_nodes.forEach((id, oIdx) => assertNode(id, `${at}.output_anchor_nodes[${oIdx}]`));
   });
 }
 
@@ -1173,10 +1262,11 @@ function buildBrowseGraphData(capabilities) {
     const edgeId = `edge-${edges.length}`;
     const title = capData.title || '';
 
-    // 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.aliases || []);
+    // The cap as the fabric defines it — its args and outputs with their
+    // names — so a path through the graph is a machine its caps resolve.
+    // Reading it validates the URN and the record: malformed registry data
+    // fails hard.
+    const cap = Cap.fromJSON(capData);
     const capFabEdgeIndex = capFab.edges.length;
     capFab.addCap(cap, 'registry');
 
@@ -2239,7 +2329,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:ext=pdf;list` source_media_urn) and the
+  // already a list (e.g. `media:document;ext=pdf;list` source_media_urn) and the
   // ForEach iterates it directly.
   let seqProducerStepIdx = -1;
   let seqProducerStep = null;
@@ -2707,17 +2797,21 @@ function editorGraphSignature(data) {
 // so we can pass them straight through to cytoscape without name
 // collisions.
 //
-// Each cap edge is rendered as one cytoscape edge per
-// (assignment.source_node, target_node) pair. The common
-// single-input cap produces exactly one rendered edge; multi-input
-// (fan-in) caps produce one edge per source-arg slot, all sharing
-// the cap title and color so they read as a single fan-in.
+// Each step is a node of its own, between the data it is given and the
+// data it makes: an edge into it per binding, labelled with the arg's name,
+// and an edge out of it per output it is taken from, labelled with the
+// output's name. A step may be given nothing (a source) or have nothing taken
+// (a sink), and a binding may be a constant, which is drawn as a small node of
+// its own: none of these has a single input-to-output edge to be drawn on. A
+// step that runs once per item draws its node and its edges in the loop style.
 function buildResolvedMachineGraphData(data) {
   validateResolvedMachinePayload(data);
 
   const nodes = [];
   const edges = [];
   const seenNodeIds = new Set();
+  let stepCounter = 0;
+  let constantCounter = 0;
   let edgeCounter = 0;
 
   data.strands.forEach((strand, strandIdx) => {
@@ -2725,10 +2819,8 @@ function buildResolvedMachineGraphData(data) {
     const outputAnchorSet = new Set(strand.output_anchor_nodes);
 
     for (const node of strand.nodes) {
-      // Each node id is unique across the whole machine; the
-      // Rust side guarantees this via its global counter. If a
-      // duplicate appears it indicates a malformed payload, so
-      // fail hard rather than silently dropping.
+      // Node ids are unique across the whole machine: every library names
+      // them from one counter. A duplicate is a malformed payload.
       if (seenNodeIds.has(node.id)) {
         throw new Error(
           `CapFabRenderer machine mode: duplicate node id "${node.id}" in strand ${strandIdx}`
@@ -2753,36 +2845,86 @@ function buildResolvedMachineGraphData(data) {
     }
 
     for (const edge of strand.edges) {
-      const cardinality = edge.is_loop ? 'n\u21921' : '1\u21921';
-      const capUrn = edge.cap_urn;
-      const capTitle = edge.title;
-      const label = cardinality === '1\u21921'
-        ? edge.alias
-        : `${edge.alias} (${cardinality})`;
-
+      const stepId = `machine-step-${stepCounter}`;
+      stepCounter++;
+      const policy = [];
+      if (edge.retry > 0) policy.push(`retry=${edge.retry}`);
+      if (edge.on_error === 'absent') policy.push('on_error=absent');
       const color = edge.is_loop
         ? 'var(--graph-loop-color)'
-        : edgeHueColor(edgeCounter);
-      const baseClasses = edge.is_loop
-        ? 'machine-edge machine-loop'
-        : 'machine-edge';
+        : edgeHueColor(stepCounter - 1);
+      const edgeClasses = edge.is_loop ? 'machine-edge machine-loop' : 'machine-edge';
+
+      nodes.push({
+        group: 'nodes',
+        data: {
+          id: stepId,
+          label: policy.length > 0 ? `${edge.title}\n{${policy.join(', ')}}` : edge.title,
+          fullUrn: edge.cap_urn,
+          alias: edge.alias,
+          strandIndex: strandIdx,
+          isLoop: edge.is_loop,
+          retry: edge.retry,
+          onError: edge.on_error,
+          includedAs: edge.included_as.slice(),
+          color,
+        },
+        classes: edge.is_loop ? 'machine-step machine-step-loop' : 'machine-step',
+      });
 
       for (const binding of edge.assignment) {
+        let source = binding.source_node;
+        if (source === undefined) {
+          source = `machine-constant-${constantCounter}`;
+          constantCounter++;
+          nodes.push({
+            group: 'nodes',
+            data: {
+              id: source,
+              label: JSON.stringify(binding.constant),
+              fullUrn: binding.cap_arg_media_urn,
+              strandIndex: strandIdx,
+            },
+            classes: 'machine-constant',
+          });
+        }
         edges.push({
           group: 'edges',
           data: {
             id: `machine-edge-${edgeCounter}`,
-            source: binding.source_node,
-            target: edge.target_node,
-            label,
-            title: `${capTitle} (${binding.cap_arg_media_urn})`,
-            fullUrn: capUrn,
+            source,
+            target: stepId,
+            label: binding.arg_name,
+            title: `${edge.title}: ${binding.arg_name} (${binding.cap_arg_media_urn})`,
+            fullUrn: binding.cap_arg_media_urn,
             color,
             strandIndex: strandIdx,
+            argName: binding.arg_name,
             capArgMediaUrn: binding.cap_arg_media_urn,
             isLoop: edge.is_loop,
           },
-          classes: baseClasses,
+          classes: edgeClasses,
+        });
+        edgeCounter++;
+      }
+
+      for (const output of edge.outputs) {
+        edges.push({
+          group: 'edges',
+          data: {
+            id: `machine-edge-${edgeCounter}`,
+            source: stepId,
+            target: output.node,
+            label: output.output_name,
+            title: `${edge.title}: ${output.output_name} (${output.output_media_urn})`,
+            fullUrn: output.output_media_urn,
+            color,
+            strandIndex: strandIdx,
+            outputName: output.output_name,
+            outputMediaUrn: output.output_media_urn,
+            isLoop: edge.is_loop,
+          },
+          classes: edgeClasses,
         });
         edgeCounter++;
       }