capdag 0.92.23685 → 0.94.24331

package/capdag.js

@@ -4257,7 +4257,7 @@ class PluginRepoServer {
 }
 
 // ============================================================================
-// Route Notation — compact, round-trippable DAG path identifiers
+// Machine Notation — compact, round-trippable DAG path identifiers
 //
 // Route notation describes capability transformation paths using bracket-
 // delimited statements:
@@ -4268,18 +4268,24 @@ class PluginRepoServer {
 // ============================================================================
 
 /**
- * Error types for route notation parsing.
- * Mirrors Rust RouteNotationError exactly.
+ * Error types for machine notation parsing.
+ * Mirrors Rust MachineSyntaxError exactly.
  */
-class RouteNotationError extends Error {
-  constructor(code, message) {
+class MachineSyntaxError extends Error {
+  /**
+   * @param {string} code - Error code from MachineSyntaxErrorCodes
+   * @param {string} message - Human-readable error message
+   * @param {Object|null} [location] - Source location { start: {offset,line,column}, end: {offset,line,column} }
+   */
+  constructor(code, message, location) {
     super(message);
-    this.name = 'RouteNotationError';
+    this.name = 'MachineSyntaxError';
     this.code = code;
+    this.location = location || null;
   }
 }
 
-const RouteNotationErrorCodes = {
+const MachineSyntaxErrorCodes = {
   EMPTY: 'Empty',
   UNTERMINATED_STATEMENT: 'UnterminatedStatement',
   INVALID_CAP_URN: 'InvalidCapUrn',
@@ -4300,9 +4306,9 @@ const RouteNotationErrorCodes = {
  * media types into a target media type. The isLoop flag indicates
  * ForEach semantics (the capability is applied to each item in a list).
  *
- * Mirrors Rust RouteEdge.
+ * Mirrors Rust MachineEdge.
  */
-class RouteEdge {
+class MachineEdge {
   /**
    * @param {MediaUrn[]} sources - Input media URN(s)
    * @param {CapUrn} capUrn - The capability URN (edge label)
@@ -4326,7 +4332,7 @@ class RouteEdge {
    * - Same isLoop flag
    *
    * Source order does not matter — fan-in sources are compared as sets.
-   * Mirrors Rust RouteEdge::is_equivalent.
+   * Mirrors Rust MachineEdge::is_equivalent.
    */
   isEquivalent(other) {
     if (this.isLoop !== other.isLoop) {
@@ -4370,7 +4376,7 @@ class RouteEdge {
 
   /**
    * Display string for this edge.
-   * Mirrors Rust Display for RouteEdge.
+   * Mirrors Rust Display for MachineEdge.
    */
   toString() {
     const sources = this.sources.map(s => s.toString()).join(', ');
@@ -4380,7 +4386,7 @@ class RouteEdge {
 }
 
 /**
- * A route graph — the semantic model behind route notation.
+ * A route graph — the semantic model behind machine notation.
  *
  * The graph is a collection of directed edges where each edge is a capability
  * that transforms source media types into a target media type.
@@ -4389,11 +4395,11 @@ class RouteEdge {
  * of ordering. Alias names used in the textual notation are not part of
  * the graph model.
  *
- * Mirrors Rust RouteGraph.
+ * Mirrors Rust Machine.
  */
-class RouteGraph {
+class Machine {
   /**
-   * @param {RouteEdge[]} edges
+   * @param {MachineEdge[]} edges
    */
   constructor(edges) {
     this._edges = edges;
@@ -4401,25 +4407,25 @@ class RouteGraph {
 
   /**
    * Create an empty route graph.
-   * @returns {RouteGraph}
+   * @returns {Machine}
    */
   static empty() {
-    return new RouteGraph([]);
+    return new Machine([]);
   }
 
   /**
-   * Parse route notation into a RouteGraph.
+   * Parse machine notation into a Machine.
    * @param {string} input
-   * @returns {RouteGraph}
-   * @throws {RouteNotationError}
+   * @returns {Machine}
+   * @throws {MachineSyntaxError}
    */
   static fromString(input) {
-    return parseRouteNotation(input);
+    return parseMachine(input);
   }
 
   /**
    * Get the edges of this graph.
-   * @returns {RouteEdge[]}
+   * @returns {MachineEdge[]}
    */
   edges() {
     return this._edges;
@@ -4445,10 +4451,10 @@ class RouteGraph {
    * Check if two route graphs are semantically equivalent.
    *
    * Two graphs are equivalent if they have the same set of edges
-   * (compared using RouteEdge.isEquivalent). Edge ordering
+   * (compared using MachineEdge.isEquivalent). Edge ordering
    * does not matter.
    *
-   * Mirrors Rust RouteGraph::is_equivalent.
+   * Mirrors Rust Machine::is_equivalent.
    */
   isEquivalent(other) {
     if (this._edges.length !== other._edges.length) {
@@ -4480,7 +4486,7 @@ class RouteGraph {
    * also produced as targets by any other edge. These are the "root"
    * inputs to the graph.
    *
-   * Mirrors Rust RouteGraph::root_sources.
+   * Mirrors Rust Machine::root_sources.
    * @returns {MediaUrn[]}
    */
   rootSources() {
@@ -4505,7 +4511,7 @@ class RouteGraph {
    * Collect all unique target media URNs that are not consumed as sources
    * by any other edge. These are the "leaf" outputs of the graph.
    *
-   * Mirrors Rust RouteGraph::leaf_targets.
+   * Mirrors Rust Machine::leaf_targets.
    * @returns {MediaUrn[]}
    */
   leafTargets() {
@@ -4530,13 +4536,13 @@ class RouteGraph {
   // =========================================================================
 
   /**
-   * Serialize this route graph to canonical one-line route notation.
+   * Serialize this route graph to canonical one-line machine notation.
    *
    * The output is deterministic: same graph → same string.
-   * Mirrors Rust RouteGraph::to_route_notation.
+   * Mirrors Rust Machine::to_machine_notation.
    * @returns {string}
    */
-  toRouteNotation() {
+  toMachineNotation() {
     if (this._edges.length === 0) {
       return '';
     }
@@ -4587,11 +4593,11 @@ class RouteGraph {
   }
 
   /**
-   * Serialize to multi-line route notation (one statement per line).
-   * Mirrors Rust RouteGraph::to_route_notation_multiline.
+   * Serialize to multi-line machine notation (one statement per line).
+   * Mirrors Rust Machine::to_machine_notation_multiline.
    * @returns {string}
    */
-  toRouteNotationMultiline() {
+  toMachineNotationMultiline() {
     if (this._edges.length === 0) {
       return '';
     }
@@ -4647,7 +4653,7 @@ class RouteGraph {
    * - nodeNames: Map<string, string> (media_urn_canonical → node_name)
    * - edgeOrder: number[] (edge indices in canonical order)
    *
-   * Mirrors Rust RouteGraph::build_serialization_maps.
+   * Mirrors Rust Machine::build_serialization_maps.
    * @private
    */
   _buildSerializationMaps() {
@@ -4714,15 +4720,87 @@ class RouteGraph {
     return { aliases, nodeNames, edgeOrder };
   }
 
+  /**
+   * Generate a Mermaid flowchart string from this machine graph.
+   *
+   * - Root sources: stadium-shaped nodes (rounded)
+   * - Leaf targets: stadium-shaped nodes (rounded)
+   * - Intermediate nodes: rectangular
+   * - Edge labels: op= tag value (or full cap URN if no op)
+   * - LOOP edges: dotted line style with "LOOP" prefix on label
+   * - Node labels: derived MediaUrn type
+   *
+   * @returns {string} Mermaid flowchart definition
+   */
+  toMermaid() {
+    if (this._edges.length === 0) {
+      return 'flowchart LR\n  empty["(empty graph)"]';
+    }
+
+    const { aliases, nodeNames, edgeOrder } = this._buildSerializationMaps();
+    const rootSourceSet = new Set(this.rootSources().map(s => s.toString()));
+    const leafTargetSet = new Set(this.leafTargets().map(t => t.toString()));
+
+    const lines = ['flowchart LR'];
+
+    // Define node shapes based on role
+    for (const [mediaKey, nodeName] of nodeNames) {
+      // Escape special mermaid characters in the label
+      const label = mediaKey.replace(/"/g, '#quot;');
+      if (rootSourceSet.has(mediaKey)) {
+        // Stadium shape for roots
+        lines.push(`  ${nodeName}([${label}])`);
+      } else if (leafTargetSet.has(mediaKey)) {
+        // Stadium shape for leaves
+        lines.push(`  ${nodeName}([${label}])`);
+      } else {
+        // Rectangle for intermediates
+        lines.push(`  ${nodeName}[${label}]`);
+      }
+    }
+
+    // Define edges
+    for (const edgeIdx of edgeOrder) {
+      const edge = this._edges[edgeIdx];
+      // Find alias for this edge
+      let edgeLabel = null;
+      for (const [a, info] of aliases) {
+        if (info.edgeIdx === edgeIdx) {
+          edgeLabel = a;
+          break;
+        }
+      }
+      const opTag = edge.capUrn.getTag('op');
+      const label = opTag !== undefined ? opTag : edgeLabel;
+
+      const targetKey = edge.target.toString();
+      const targetName = nodeNames.get(targetKey);
+
+      for (const src of edge.sources) {
+        const srcKey = src.toString();
+        const srcName = nodeNames.get(srcKey);
+
+        if (edge.isLoop) {
+          // Dotted line for LOOP edges
+          lines.push(`  ${srcName} -. "LOOP ${label}" .-> ${targetName}`);
+        } else {
+          lines.push(`  ${srcName} -- "${label}" --> ${targetName}`);
+        }
+      }
+    }
+
+    return lines.join('\n');
+  }
+
   /**
    * Display string for this graph.
-   * Mirrors Rust Display for RouteGraph.
+   * Mirrors Rust Display for Machine.
    */
   toString() {
     if (this._edges.length === 0) {
-      return 'RouteGraph(empty)';
+      return 'Machine(empty)';
     }
-    return `RouteGraph(${this._edges.length} edges)`;
+    return `Machine(${this._edges.length} edges)`;
   }
 }
 
@@ -4732,7 +4810,7 @@ class RouteGraph {
 // ============================================================================
 
 // Load the Peggy-generated parser
-const routeParser = require('./route-parser.js');
+const routeParser = require('./machine-parser.js');
 
 /**
  * Assign a media URN to a node, or check consistency if already assigned.
@@ -4743,14 +4821,15 @@ const routeParser = require('./route-parser.js');
  * Mirrors Rust assign_or_check_node.
  * @private
  */
-function assignOrCheckNode(node, mediaUrn, nodeMedia, position) {
+function assignOrCheckNode(node, mediaUrn, nodeMedia, position, location) {
   const existing = nodeMedia.get(node);
   if (existing !== undefined) {
     const compatible = existing.isComparable(mediaUrn);
     if (!compatible) {
-      throw new RouteNotationError(
-        RouteNotationErrorCodes.INVALID_WIRING,
-        `invalid wiring at statement ${position}: node '${node}' has conflicting media types: existing '${existing}', new '${mediaUrn}'`
+      throw new MachineSyntaxError(
+        MachineSyntaxErrorCodes.INVALID_WIRING,
+        `invalid wiring at statement ${position}: node '${node}' has conflicting media types: existing '${existing}', new '${mediaUrn}'`,
+        location
       );
     }
   } else {
@@ -4759,25 +4838,20 @@ function assignOrCheckNode(node, mediaUrn, nodeMedia, position) {
 }
 
 /**
- * Parse route notation into a RouteGraph.
- *
- * Uses the Peggy-generated PEG parser to parse the input, then resolves
- * cap URNs and derives media URNs from cap in/out specs.
- *
- * Fails hard — no fallbacks, no guessing, no recovery.
- *
- * Mirrors Rust parse_route_notation exactly.
+ * Internal: run the 4-phase parse pipeline on machine notation input.
+ * Returns { machine, statements, aliasMap, nodeMedia } for full introspection.
  *
  * @param {string} input - Route notation string
- * @returns {RouteGraph}
- * @throws {RouteNotationError}
+ * @returns {{ machine: Machine, statements: Object[], aliasMap: Map, nodeMedia: Map }}
+ * @throws {MachineSyntaxError}
+ * @private
  */
-function parseRouteNotation(input) {
+function _parseMachineInternal(input) {
   const trimmed = input.trim();
   if (trimmed.length === 0) {
-    throw new RouteNotationError(
-      RouteNotationErrorCodes.EMPTY,
-      'route notation is empty'
+    throw new MachineSyntaxError(
+      MachineSyntaxErrorCodes.EMPTY,
+      'machine notation is empty'
     );
   }
 
@@ -4786,15 +4860,18 @@ function parseRouteNotation(input) {
   try {
     stmts = routeParser.parse(trimmed);
   } catch (e) {
-    throw new RouteNotationError(
-      RouteNotationErrorCodes.PARSE_ERROR,
-      `parse error: ${e.message}`
+    // Peggy SyntaxError has .location — propagate it
+    const loc = e.location || null;
+    throw new MachineSyntaxError(
+      MachineSyntaxErrorCodes.PARSE_ERROR,
+      `parse error: ${e.message}`,
+      loc
     );
   }
 
   // Phase 2: Separate headers and wirings (already done by grammar actions)
-  const headers = []; // { alias, capUrn, position }
-  const wirings = []; // { sources, capAlias, target, isLoop, position }
+  const headers = [];
+  const wirings = [];
 
   for (let i = 0; i < stmts.length; i++) {
     const stmt = stmts[i];
@@ -4804,12 +4881,20 @@ function parseRouteNotation(input) {
       try {
         capUrn = CapUrn.fromString(stmt.capUrn);
       } catch (e) {
-        throw new RouteNotationError(
-          RouteNotationErrorCodes.INVALID_CAP_URN,
-          `invalid cap URN in header '${stmt.alias}': ${e.message}`
+        throw new MachineSyntaxError(
+          MachineSyntaxErrorCodes.INVALID_CAP_URN,
+          `invalid cap URN in header '${stmt.alias}': ${e.message}`,
+          stmt.capUrnLocation || stmt.location
         );
       }
-      headers.push({ alias: stmt.alias, capUrn, position: i });
+      headers.push({
+        alias: stmt.alias,
+        capUrn,
+        position: i,
+        location: stmt.location,
+        aliasLocation: stmt.aliasLocation,
+        capUrnLocation: stmt.capUrnLocation,
+      });
     } else if (stmt.type === 'wiring') {
       wirings.push({
         sources: stmt.sources,
@@ -4817,28 +4902,40 @@ function parseRouteNotation(input) {
         target: stmt.target,
         isLoop: stmt.isLoop,
         position: i,
+        location: stmt.location,
+        sourceLocations: stmt.sourceLocations,
+        capAliasLocation: stmt.capAliasLocation,
+        targetLocation: stmt.targetLocation,
       });
     }
   }
 
   // Phase 3: Build alias → CapUrn map, checking for duplicates
-  const aliasMap = new Map(); // alias → { capUrn, position }
+  const aliasMap = new Map();
   for (const header of headers) {
     if (aliasMap.has(header.alias)) {
       const firstPos = aliasMap.get(header.alias).position;
-      throw new RouteNotationError(
-        RouteNotationErrorCodes.DUPLICATE_ALIAS,
-        `duplicate alias '${header.alias}' (first defined at statement ${firstPos})`
+      throw new MachineSyntaxError(
+        MachineSyntaxErrorCodes.DUPLICATE_ALIAS,
+        `duplicate alias '${header.alias}' (first defined at statement ${firstPos})`,
+        header.aliasLocation || header.location
       );
     }
-    aliasMap.set(header.alias, { capUrn: header.capUrn, position: header.position });
+    aliasMap.set(header.alias, {
+      capUrn: header.capUrn,
+      position: header.position,
+      location: header.location,
+      aliasLocation: header.aliasLocation,
+      capUrnLocation: header.capUrnLocation,
+    });
   }
 
-  // Phase 4: Resolve wirings into RouteEdges
+  // Phase 4: Resolve wirings into MachineEdges
   if (wirings.length === 0 && headers.length > 0) {
-    throw new RouteNotationError(
-      RouteNotationErrorCodes.NO_EDGES,
-      'route has headers but no wirings — define at least one edge'
+    throw new MachineSyntaxError(
+      MachineSyntaxErrorCodes.NO_EDGES,
+      'route has headers but no wirings — define at least one edge',
+      headers[headers.length - 1].location
     );
   }
 
@@ -4849,26 +4946,30 @@ function parseRouteNotation(input) {
     // Look up the cap alias
     const aliasEntry = aliasMap.get(wiring.capAlias);
     if (!aliasEntry) {
-      throw new RouteNotationError(
-        RouteNotationErrorCodes.UNDEFINED_ALIAS,
-        `wiring references undefined alias '${wiring.capAlias}'`
+      throw new MachineSyntaxError(
+        MachineSyntaxErrorCodes.UNDEFINED_ALIAS,
+        `wiring references undefined alias '${wiring.capAlias}'`,
+        wiring.capAliasLocation || wiring.location
       );
     }
     const capUrn = aliasEntry.capUrn;
 
     // Check node-alias collisions
-    for (const src of wiring.sources) {
+    for (let si = 0; si < wiring.sources.length; si++) {
+      const src = wiring.sources[si];
       if (aliasMap.has(src)) {
-        throw new RouteNotationError(
-          RouteNotationErrorCodes.NODE_ALIAS_COLLISION,
-          `node name '${src}' collides with cap alias '${src}'`
+        throw new MachineSyntaxError(
+          MachineSyntaxErrorCodes.NODE_ALIAS_COLLISION,
+          `node name '${src}' collides with cap alias '${src}'`,
+          wiring.sourceLocations ? wiring.sourceLocations[si] : wiring.location
         );
       }
     }
     if (aliasMap.has(wiring.target)) {
-      throw new RouteNotationError(
-        RouteNotationErrorCodes.NODE_ALIAS_COLLISION,
-        `node name '${wiring.target}' collides with cap alias '${wiring.target}'`
+      throw new MachineSyntaxError(
+        MachineSyntaxErrorCodes.NODE_ALIAS_COLLISION,
+        `node name '${wiring.target}' collides with cap alias '${wiring.target}'`,
+        wiring.targetLocation || wiring.location
       );
     }
 
@@ -4877,9 +4978,10 @@ function parseRouteNotation(input) {
     try {
       capInMedia = capUrn.inMediaUrn();
     } catch (e) {
-      throw new RouteNotationError(
-        RouteNotationErrorCodes.INVALID_MEDIA_URN,
-        `invalid media URN in cap '${wiring.capAlias}': in= spec: ${e.message}`
+      throw new MachineSyntaxError(
+        MachineSyntaxErrorCodes.INVALID_MEDIA_URN,
+        `invalid media URN in cap '${wiring.capAlias}': in= spec: ${e.message}`,
+        aliasEntry.capUrnLocation || wiring.location
       );
     }
 
@@ -4887,9 +4989,10 @@ function parseRouteNotation(input) {
     try {
       capOutMedia = capUrn.outMediaUrn();
     } catch (e) {
-      throw new RouteNotationError(
-        RouteNotationErrorCodes.INVALID_MEDIA_URN,
-        `invalid media URN in cap '${wiring.capAlias}': out= spec: ${e.message}`
+      throw new MachineSyntaxError(
+        MachineSyntaxErrorCodes.INVALID_MEDIA_URN,
+        `invalid media URN in cap '${wiring.capAlias}': out= spec: ${e.message}`,
+        aliasEntry.capUrnLocation || wiring.location
       );
     }
 
@@ -4899,7 +5002,8 @@ function parseRouteNotation(input) {
       const src = wiring.sources[i];
       if (i === 0) {
         // Primary source: use cap's in= spec
-        assignOrCheckNode(src, capInMedia, nodeMedia, wiring.position);
+        assignOrCheckNode(src, capInMedia, nodeMedia, wiring.position,
+          wiring.sourceLocations ? wiring.sourceLocations[i] : wiring.location);
         sourceUrns.push(capInMedia);
       } else {
         // Secondary source (fan-in): use existing type if assigned,
@@ -4915,26 +5019,64 @@ function parseRouteNotation(input) {
     }
 
     // Assign target media URN
-    assignOrCheckNode(wiring.target, capOutMedia, nodeMedia, wiring.position);
+    assignOrCheckNode(wiring.target, capOutMedia, nodeMedia, wiring.position,
+      wiring.targetLocation || wiring.location);
 
-    edges.push(new RouteEdge(sourceUrns, capUrn, capOutMedia, wiring.isLoop));
+    edges.push(new MachineEdge(sourceUrns, capUrn, capOutMedia, wiring.isLoop));
   }
 
-  return new RouteGraph(edges);
+  return {
+    machine: new Machine(edges),
+    statements: stmts,
+    aliasMap,
+    nodeMedia,
+  };
+}
+
+/**
+ * Parse machine notation into a Machine.
+ *
+ * Uses the Peggy-generated PEG parser to parse the input, then resolves
+ * cap URNs and derives media URNs from cap in/out specs.
+ *
+ * Fails hard — no fallbacks, no guessing, no recovery.
+ *
+ * Mirrors Rust parse_machine exactly.
+ *
+ * @param {string} input - Route notation string
+ * @returns {Machine}
+ * @throws {MachineSyntaxError}
+ */
+function parseMachine(input) {
+  return _parseMachineInternal(input).machine;
+}
+
+/**
+ * Parse machine notation and return both the Machine and the raw AST with locations.
+ *
+ * Use this for LSP tooling — the statements array contains full position information
+ * for every element (aliases, cap URNs, sources, targets).
+ *
+ * @param {string} input - Route notation string
+ * @returns {{ machine: Machine, statements: Object[], aliasMap: Map, nodeMedia: Map }}
+ * @throws {MachineSyntaxError}
+ */
+function parseMachineWithAST(input) {
+  return _parseMachineInternal(input);
 }
 
 // ============================================================================
-// RouteGraphBuilder — programmatic path construction
+// MachineBuilder — programmatic path construction
 // ============================================================================
 
 /**
- * Builder for constructing RouteGraphs programmatically.
+ * Builder for constructing Machines programmatically.
  *
  * Provides a fluent API for building route graphs without writing
- * route notation strings. Useful for constructing paths from graph
+ * machine notation strings. Useful for constructing paths from graph
  * exploration (e.g., selecting paths in the UI).
  */
-class RouteGraphBuilder {
+class MachineBuilder {
   constructor() {
     this._edges = [];
   }
@@ -4945,13 +5087,13 @@ class RouteGraphBuilder {
    * @param {string} capUrnStr - Cap URN string
    * @param {string} targetUrn - Target media URN string
    * @param {boolean} [isLoop=false] - Whether this edge has ForEach semantics
-   * @returns {RouteGraphBuilder} this (for chaining)
+   * @returns {MachineBuilder} this (for chaining)
    */
   addEdge(sourceUrns, capUrnStr, targetUrn, isLoop = false) {
     const sources = sourceUrns.map(s => MediaUrn.fromString(s));
     const capUrn = CapUrn.fromString(capUrnStr);
     const target = MediaUrn.fromString(targetUrn);
-    this._edges.push(new RouteEdge(sources, capUrn, target, isLoop));
+    this._edges.push(new MachineEdge(sources, capUrn, target, isLoop));
     return this;
   }
 
@@ -4959,26 +5101,199 @@ class RouteGraphBuilder {
    * Add a linear chain of edges from CapGraphEdge[] (from CapGraph.findAllPaths).
    *
    * Each CapGraphEdge has fromUrn, toUrn, and cap (with cap.urn).
-   * This converts the path into a series of RouteEdges.
+   * This converts the path into a series of MachineEdges.
    *
    * @param {CapGraphEdge[]} capGraphEdges - Array of CapGraphEdge from pathfinding
-   * @returns {RouteGraphBuilder} this (for chaining)
+   * @returns {MachineBuilder} this (for chaining)
    */
   addCapGraphPath(capGraphEdges) {
     for (const edge of capGraphEdges) {
       const source = MediaUrn.fromString(edge.fromUrn);
       const target = MediaUrn.fromString(edge.toUrn);
-      this._edges.push(new RouteEdge([source], edge.cap.urn, target, false));
+      this._edges.push(new MachineEdge([source], edge.cap.urn, target, false));
     }
     return this;
   }
 
   /**
-   * Build the RouteGraph from the accumulated edges.
-   * @returns {RouteGraph}
+   * Build the Machine from the accumulated edges.
+   * @returns {Machine}
    */
   build() {
-    return new RouteGraph([...this._edges]);
+    return new Machine([...this._edges]);
+  }
+}
+
+// ============================================================================
+// Cap & Media Registry Client
+// Fetches and caches capability and media registries from capdag.com
+// ============================================================================
+
+/**
+ * A capability entry from the registry.
+ * Matches the denormalized view format from capdag.com /api/capabilities.
+ */
+class CapRegistryEntry {
+  constructor(data) {
+    this.urn = data.urn;
+    this.title = data.title || '';
+    this.command = data.command || '';
+    this.description = data.cap_description || '';
+    this.args = data.args || [];
+    this.output = data.output || null;
+    this.mediaSpecs = data.media_specs || [];
+    this.urnTags = data.urn_tags || {};
+    this.inSpec = data.in_spec || '';
+    this.outSpec = data.out_spec || '';
+    this.inMediaTitle = data.in_media_title || '';
+    this.outMediaTitle = data.out_media_title || '';
+  }
+}
+
+/**
+ * A media spec entry from the registry.
+ * Matches the media lookup format from capdag.com /media:*.
+ */
+class MediaRegistryEntry {
+  constructor(data) {
+    this.urn = data.urn;
+    this.title = data.title || '';
+    this.mediaType = data.media_type || '';
+    this.description = data.description || '';
+  }
+}
+
+/**
+ * Client for fetching and caching capability and media registries from capdag.com.
+ *
+ * Uses a time-based cache with configurable TTL. All methods are async.
+ * Fails hard on network errors — no silent degradation.
+ */
+class CapRegistryClient {
+  /**
+   * @param {string} [baseUrl='https://capdag.com'] - Registry base URL
+   * @param {number} [cacheTtlSeconds=300] - Cache TTL in seconds
+   */
+  constructor(baseUrl = 'https://capdag.com', cacheTtlSeconds = 300) {
+    this._baseUrl = baseUrl.replace(/\/$/, '');
+    this._cacheTtl = cacheTtlSeconds * 1000;
+    this._capCache = null;       // { entries: CapRegistryEntry[], fetchedAt: number }
+    this._mediaCache = new Map(); // media_urn_string → { entry: MediaRegistryEntry, fetchedAt: number }
+  }
+
+  /**
+   * Fetch all capabilities from the registry (cached).
+   * @returns {Promise<CapRegistryEntry[]>}
+   */
+  async fetchCapabilities() {
+    if (this._capCache && (Date.now() - this._capCache.fetchedAt) < this._cacheTtl) {
+      return this._capCache.entries;
+    }
+
+    const response = await fetch(`${this._baseUrl}/api/capabilities`);
+    if (!response.ok) {
+      throw new Error(`Cap registry request failed: HTTP ${response.status} from ${this._baseUrl}/api/capabilities`);
+    }
+
+    const data = await response.json();
+    if (!Array.isArray(data)) {
+      throw new Error(`Invalid cap registry response: expected array, got ${typeof data}`);
+    }
+
+    const entries = data.map(d => new CapRegistryEntry(d));
+    this._capCache = { entries, fetchedAt: Date.now() };
+    return entries;
+  }
+
+  /**
+   * Lookup a single capability by URN.
+   * Uses the capabilities cache if available, otherwise falls back to direct lookup.
+   * @param {string} capUrnStr - Cap URN string
+   * @returns {Promise<CapRegistryEntry|null>}
+   */
+  async lookupCap(capUrnStr) {
+    // Try cache first
+    if (this._capCache && (Date.now() - this._capCache.fetchedAt) < this._cacheTtl) {
+      const found = this._capCache.entries.find(e => e.urn === capUrnStr);
+      if (found) return found;
+    }
+
+    // Direct lookup
+    const encoded = encodeURIComponent(capUrnStr);
+    const response = await fetch(`${this._baseUrl}/${encoded}`);
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      throw new Error(`Cap lookup failed: HTTP ${response.status} for ${capUrnStr}`);
+    }
+
+    const data = await response.json();
+    return new CapRegistryEntry(data);
+  }
+
+  /**
+   * Lookup a single media spec by URN.
+   * @param {string} mediaUrnStr - Media URN string
+   * @returns {Promise<MediaRegistryEntry|null>}
+   */
+  async lookupMedia(mediaUrnStr) {
+    // Check cache
+    const cached = this._mediaCache.get(mediaUrnStr);
+    if (cached && (Date.now() - cached.fetchedAt) < this._cacheTtl) {
+      return cached.entry;
+    }
+
+    const encoded = encodeURIComponent(mediaUrnStr);
+    const response = await fetch(`${this._baseUrl}/${encoded}`);
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      throw new Error(`Media lookup failed: HTTP ${response.status} for ${mediaUrnStr}`);
+    }
+
+    const data = await response.json();
+    const entry = new MediaRegistryEntry(data);
+    this._mediaCache.set(mediaUrnStr, { entry, fetchedAt: Date.now() });
+    return entry;
+  }
+
+  /**
+   * Get all known media URNs from cached capabilities (in and out specs).
+   * Fetches capabilities if not cached.
+   * @returns {Promise<string[]>}
+   */
+  async getKnownMediaUrns() {
+    const caps = await this.fetchCapabilities();
+    const urns = new Set();
+    for (const cap of caps) {
+      if (cap.inSpec) urns.add(cap.inSpec);
+      if (cap.outSpec) urns.add(cap.outSpec);
+    }
+    return Array.from(urns).sort();
+  }
+
+  /**
+   * Get all known op= tag values from cached capabilities.
+   * @returns {Promise<string[]>}
+   */
+  async getKnownOps() {
+    const caps = await this.fetchCapabilities();
+    const ops = new Set();
+    for (const cap of caps) {
+      const op = cap.urnTags && cap.urnTags.op;
+      if (op) ops.add(op);
+    }
+    return Array.from(ops).sort();
+  }
+
+  /**
+   * Invalidate all caches. Next call to any method will fetch fresh data.
+   */
+  invalidate() {
+    this._capCache = null;
+    this._mediaCache.clear();
   }
 }
 
@@ -5101,10 +5416,15 @@ module.exports = {
   PluginRepoClient,
   PluginRepoServer,
   // Route notation
-  RouteNotationError,
-  RouteNotationErrorCodes,
-  RouteEdge,
-  RouteGraph,
-  RouteGraphBuilder,
-  parseRouteNotation,
+  MachineSyntaxError,
+  MachineSyntaxErrorCodes,
+  MachineEdge,
+  Machine,
+  MachineBuilder,
+  parseMachine,
+  parseMachineWithAST,
+  // Cap & Media Registry
+  CapRegistryEntry,
+  MediaRegistryEntry,
+  CapRegistryClient,
 };