capdag 0.93.23689 → 0.94.24331

package/capdag.js

@@ -4272,10 +4272,16 @@ class PluginRepoServer {
  * Mirrors Rust MachineSyntaxError exactly.
  */
 class MachineSyntaxError extends Error {
-  constructor(code, message) {
+  /**
+   * @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 = 'MachineSyntaxError';
     this.code = code;
+    this.location = location || null;
   }
 }
 
@@ -4714,6 +4720,78 @@ class Machine {
     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 Machine.
@@ -4743,14 +4821,15 @@ const routeParser = require('./machine-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 MachineSyntaxError(
         MachineSyntaxErrorCodes.INVALID_WIRING,
-        `invalid wiring at statement ${position}: node '${node}' has conflicting media types: existing '${existing}', new '${mediaUrn}'`
+        `invalid wiring at statement ${position}: node '${node}' has conflicting media types: existing '${existing}', new '${mediaUrn}'`,
+        location
       );
     }
   } else {
@@ -4759,20 +4838,15 @@ function assignOrCheckNode(node, mediaUrn, nodeMedia, position) {
 }
 
 /**
- * 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.
+ * 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 {Machine}
+ * @returns {{ machine: Machine, statements: Object[], aliasMap: Map, nodeMedia: Map }}
  * @throws {MachineSyntaxError}
+ * @private
  */
-function parseMachine(input) {
+function _parseMachineInternal(input) {
   const trimmed = input.trim();
   if (trimmed.length === 0) {
     throw new MachineSyntaxError(
@@ -4786,15 +4860,18 @@ function parseMachine(input) {
   try {
     stmts = routeParser.parse(trimmed);
   } catch (e) {
+    // Peggy SyntaxError has .location — propagate it
+    const loc = e.location || null;
     throw new MachineSyntaxError(
       MachineSyntaxErrorCodes.PARSE_ERROR,
-      `parse error: ${e.message}`
+      `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];
@@ -4806,10 +4883,18 @@ function parseMachine(input) {
       } catch (e) {
         throw new MachineSyntaxError(
           MachineSyntaxErrorCodes.INVALID_CAP_URN,
-          `invalid cap URN in header '${stmt.alias}': ${e.message}`
+          `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 parseMachine(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 MachineSyntaxError(
         MachineSyntaxErrorCodes.DUPLICATE_ALIAS,
-        `duplicate alias '${header.alias}' (first defined at statement ${firstPos})`
+        `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 MachineEdges
   if (wirings.length === 0 && headers.length > 0) {
     throw new MachineSyntaxError(
       MachineSyntaxErrorCodes.NO_EDGES,
-      'route has headers but no wirings — define at least one edge'
+      'route has headers but no wirings — define at least one edge',
+      headers[headers.length - 1].location
     );
   }
 
@@ -4851,24 +4948,28 @@ function parseMachine(input) {
     if (!aliasEntry) {
       throw new MachineSyntaxError(
         MachineSyntaxErrorCodes.UNDEFINED_ALIAS,
-        `wiring references undefined alias '${wiring.capAlias}'`
+        `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 MachineSyntaxError(
           MachineSyntaxErrorCodes.NODE_ALIAS_COLLISION,
-          `node name '${src}' collides with cap alias '${src}'`
+          `node name '${src}' collides with cap alias '${src}'`,
+          wiring.sourceLocations ? wiring.sourceLocations[si] : wiring.location
         );
       }
     }
     if (aliasMap.has(wiring.target)) {
       throw new MachineSyntaxError(
         MachineSyntaxErrorCodes.NODE_ALIAS_COLLISION,
-        `node name '${wiring.target}' collides with cap alias '${wiring.target}'`
+        `node name '${wiring.target}' collides with cap alias '${wiring.target}'`,
+        wiring.targetLocation || wiring.location
       );
     }
 
@@ -4879,7 +4980,8 @@ function parseMachine(input) {
     } catch (e) {
       throw new MachineSyntaxError(
         MachineSyntaxErrorCodes.INVALID_MEDIA_URN,
-        `invalid media URN in cap '${wiring.capAlias}': in= spec: ${e.message}`
+        `invalid media URN in cap '${wiring.capAlias}': in= spec: ${e.message}`,
+        aliasEntry.capUrnLocation || wiring.location
       );
     }
 
@@ -4889,7 +4991,8 @@ function parseMachine(input) {
     } catch (e) {
       throw new MachineSyntaxError(
         MachineSyntaxErrorCodes.INVALID_MEDIA_URN,
-        `invalid media URN in cap '${wiring.capAlias}': out= spec: ${e.message}`
+        `invalid media URN in cap '${wiring.capAlias}': out= spec: ${e.message}`,
+        aliasEntry.capUrnLocation || wiring.location
       );
     }
 
@@ -4899,7 +5002,8 @@ function parseMachine(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,12 +5019,50 @@ function parseMachine(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 MachineEdge(sourceUrns, capUrn, capOutMedia, wiring.isLoop));
   }
 
-  return new Machine(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);
 }
 
 // ============================================================================
@@ -4982,6 +5124,179 @@ class MachineBuilder {
   }
 }
 
+// ============================================================================
+// 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();
+  }
+}
+
 // Export for CommonJS
 module.exports = {
   CapUrn,
@@ -5107,4 +5422,9 @@ module.exports = {
   Machine,
   MachineBuilder,
   parseMachine,
+  parseMachineWithAST,
+  // Cap & Media Registry
+  CapRegistryEntry,
+  MediaRegistryEntry,
+  CapRegistryClient,
 };

package/capdag.test.js

@@ -14,7 +14,8 @@ const {
   validateNoMediaSpecRedefinitionSync,
   CapArgumentValue,
   llmConversationUrn, modelAvailabilityUrn, modelPathUrn,
-  MachineSyntaxError, MachineSyntaxErrorCodes, MachineEdge, Machine, MachineBuilder, parseMachine,
+  MachineSyntaxError, MachineSyntaxErrorCodes, MachineEdge, Machine, MachineBuilder, parseMachine, parseMachineWithAST,
+  CapRegistryEntry, MediaRegistryEntry, CapRegistryClient,
   MEDIA_STRING, MEDIA_INTEGER, MEDIA_NUMBER, MEDIA_BOOLEAN,
   MEDIA_OBJECT, MEDIA_STRING_ARRAY, MEDIA_INTEGER_ARRAY,
   MEDIA_NUMBER_ARRAY, MEDIA_BOOLEAN_ARRAY, MEDIA_OBJECT_ARRAY,
@@ -3300,6 +3301,245 @@ function testMachine_mediaUrnIsComparable() {
   assert(!general.isComparable(unrelated), 'Unrelated should not be comparable');
 }
 
+// ============================================================================
+// Phase 0A: Position tracking tests
+// ============================================================================
+
+function testMachine_parseMachineWithAST_headerLocation() {
+  const input = '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"][doc -> extract -> text]';
+  const result = parseMachineWithAST(input);
+  assert(result.statements.length === 2, 'Should have 2 statements');
+  const stmt = result.statements[0];
+  assertEqual(stmt.type, 'header', 'First statement should be a header');
+  assert(stmt.location !== undefined, 'Header should have location');
+  assert(stmt.location.start !== undefined, 'Location should have start');
+  assert(stmt.location.end !== undefined, 'Location should have end');
+  assert(stmt.location.start.line !== undefined, 'Start should have line');
+  assert(stmt.location.start.column !== undefined, 'Start should have column');
+  assert(stmt.aliasLocation !== undefined, 'Header should have aliasLocation');
+  assert(stmt.capUrnLocation !== undefined, 'Header should have capUrnLocation');
+  assertEqual(stmt.alias, 'extract', 'Alias should be extract');
+}
+
+function testMachine_parseMachineWithAST_wiringLocation() {
+  const input = '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]\n[doc -> extract -> text]';
+  const result = parseMachineWithAST(input);
+  assert(result.statements.length === 2, 'Should have 2 statements');
+  const wiring = result.statements[1];
+  assertEqual(wiring.type, 'wiring', 'Second statement should be a wiring');
+  assert(wiring.location !== undefined, 'Wiring should have location');
+  assert(wiring.sourceLocations !== undefined, 'Wiring should have sourceLocations');
+  assert(wiring.sourceLocations.length === 1, 'Should have 1 source location');
+  assert(wiring.capAliasLocation !== undefined, 'Wiring should have capAliasLocation');
+  assert(wiring.targetLocation !== undefined, 'Wiring should have targetLocation');
+  assertEqual(wiring.target, 'text', 'Target should be text');
+}
+
+function testMachine_parseMachineWithAST_multilinePositions() {
+  const input = '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]\n[doc -> extract -> text]';
+  const result = parseMachineWithAST(input);
+  const headerLoc = result.statements[0].location;
+  const wiringLoc = result.statements[1].location;
+  assertEqual(headerLoc.start.line, 1, 'Header should be on line 1');
+  assertEqual(wiringLoc.start.line, 2, 'Wiring should be on line 2');
+}
+
+function testMachine_parseMachineWithAST_fanInSourceLocations() {
+  const input = [
+    '[describe cap:in="media:image;png";op=describe_image;out="media:image-description;textable"]',
+    '[(thumbnail, model_spec) -> describe -> description]'
+  ].join('\n');
+  const result = parseMachineWithAST(input);
+  const wiring = result.statements[1];
+  assertEqual(wiring.sources.length, 2, 'Fan-in should have 2 sources');
+  assert(wiring.sourceLocations.length === 2, 'Should have 2 source locations');
+}
+
+function testMachine_parseMachineWithAST_aliasMap() {
+  const input = [
+    '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]',
+    '[embed cap:in="media:txt;textable";op=embed;out="media:embedding-vector;record;textable"]',
+    '[doc -> extract -> text]',
+    '[text -> embed -> vectors]',
+  ].join('\n');
+  const result = parseMachineWithAST(input);
+  assert(result.aliasMap.has('extract'), 'aliasMap should have extract');
+  assert(result.aliasMap.has('embed'), 'aliasMap should have embed');
+  assertEqual(result.aliasMap.size, 2, 'aliasMap should have 2 entries');
+  const extractEntry = result.aliasMap.get('extract');
+  assert(extractEntry.capUrn !== undefined, 'Alias entry should have capUrn');
+  assert(extractEntry.location !== undefined, 'Alias entry should have location');
+  assert(extractEntry.aliasLocation !== undefined, 'Alias entry should have aliasLocation');
+  assert(extractEntry.capUrnLocation !== undefined, 'Alias entry should have capUrnLocation');
+}
+
+function testMachine_parseMachineWithAST_nodeMedia() {
+  const input = [
+    '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]',
+    '[doc -> extract -> text]',
+  ].join('\n');
+  const result = parseMachineWithAST(input);
+  assert(result.nodeMedia.has('doc'), 'nodeMedia should have doc');
+  assert(result.nodeMedia.has('text'), 'nodeMedia should have text');
+  assertEqual(result.nodeMedia.get('doc').toString(), 'media:pdf', 'doc should be media:pdf');
+  assertEqual(result.nodeMedia.get('text').toString(), 'media:textable;txt', 'text should be media:textable;txt');
+}
+
+function testMachine_errorLocation_parseError() {
+  try {
+    parseMachine('[this is not valid');
+    throw new Error('Expected MachineSyntaxError');
+  } catch (e) {
+    assertEqual(e.code, MachineSyntaxErrorCodes.PARSE_ERROR, 'Should be PARSE_ERROR');
+    assert(e.location !== null, 'Parse error should have location');
+  }
+}
+
+function testMachine_errorLocation_duplicateAlias() {
+  try {
+    parseMachine(
+      '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]' +
+      '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]' +
+      '[doc -> extract -> text]'
+    );
+    throw new Error('Expected MachineSyntaxError');
+  } catch (e) {
+    assertEqual(e.code, MachineSyntaxErrorCodes.DUPLICATE_ALIAS, 'Should be DUPLICATE_ALIAS');
+    assert(e.location !== null, 'Duplicate alias error should have location');
+  }
+}
+
+function testMachine_errorLocation_undefinedAlias() {
+  try {
+    parseMachine('[doc -> nonexistent -> text]');
+    throw new Error('Expected MachineSyntaxError');
+  } catch (e) {
+    assertEqual(e.code, MachineSyntaxErrorCodes.UNDEFINED_ALIAS, 'Should be UNDEFINED_ALIAS');
+    assert(e.location !== null, 'Undefined alias error should have location');
+  }
+}
+
+// ============================================================================
+// Phase 0C: Machine.toMermaid() tests
+// ============================================================================
+
+function testMachine_toMermaid_linearChain() {
+  const machine = Machine.fromString(
+    '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]' +
+    '[doc -> extract -> text]'
+  );
+  const mermaid = machine.toMermaid();
+  assert(mermaid.startsWith('flowchart LR'), 'Should start with flowchart LR');
+  assert(mermaid.includes('extract'), 'Should include extract label');
+  assert(mermaid.includes('media:pdf'), 'Should include media:pdf node');
+  assert(mermaid.includes('media:textable;txt'), 'Should include media:textable;txt node');
+  assert(mermaid.includes('-->'), 'Should include arrow');
+  // Root source and leaf target should both be stadium shape
+  assert(mermaid.includes('(['), 'Should have stadium shape nodes');
+}
+
+function testMachine_toMermaid_loopEdge() {
+  const machine = Machine.fromString(
+    '[p2t cap:in="media:disbound-page;textable";op=page_to_text;out="media:txt;textable"]' +
+    '[pages -> LOOP p2t -> texts]'
+  );
+  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');
+}
+
+function testMachine_toMermaid_emptyGraph() {
+  const machine = Machine.empty();
+  const mermaid = machine.toMermaid();
+  assert(mermaid.includes('empty graph'), 'Should indicate empty graph');
+}
+
+function testMachine_toMermaid_fanIn() {
+  const machine = Machine.fromString(
+    '[describe cap:in="media:image;png";op=describe_image;out="media:image-description;textable"]' +
+    '[(thumbnail, model_spec) -> describe -> description]'
+  );
+  const mermaid = machine.toMermaid();
+  // Fan-in should produce two arrows pointing to the same target
+  const arrowCount = (mermaid.match(/-->/g) || []).length;
+  assertEqual(arrowCount, 2, 'Fan-in should produce 2 arrows');
+}
+
+function testMachine_toMermaid_fanOut() {
+  const input = [
+    '[meta cap:in="media:pdf";op=extract_metadata;out="media:file-metadata;record;textable"]',
+    '[thumb cap:in="media:pdf";op=generate_thumbnail;out="media:image;png;thumbnail"]',
+    '[doc -> meta -> metadata]',
+    '[doc -> thumb -> thumbnail]'
+  ].join('');
+  const machine = Machine.fromString(input);
+  const mermaid = machine.toMermaid();
+  // Should have 2 edges
+  const arrowCount = (mermaid.match(/-->/g) || []).length;
+  assertEqual(arrowCount, 2, 'Fan-out should produce 2 arrows');
+  // The root source (media:pdf) should appear once as a node definition
+  assert(mermaid.includes('media:pdf'), 'Should include media:pdf');
+}
+
+// ============================================================================
+// Phase 0B: CapRegistryClient tests
+// ============================================================================
+
+function testMachine_capRegistryEntry_construction() {
+  const entry = new CapRegistryEntry({
+    urn: 'cap:in="media:pdf";op=extract;out="media:txt;textable"',
+    title: 'PDF Extractor',
+    command: 'extract',
+    cap_description: 'Extracts text from PDF',
+    args: [{ media_urn: 'media:pdf', required: true }],
+    output: { media_urn: 'media:txt;textable', output_description: 'Extracted text' },
+    media_specs: [],
+    urn_tags: { op: 'extract' },
+    in_spec: 'media:pdf',
+    out_spec: 'media:txt;textable',
+    in_media_title: 'PDF Document',
+    out_media_title: 'Text'
+  });
+  assertEqual(entry.urn, 'cap:in="media:pdf";op=extract;out="media:txt;textable"', 'URN should match');
+  assertEqual(entry.title, 'PDF Extractor', 'Title should match');
+  assertEqual(entry.description, 'Extracts text from PDF', 'Description should match');
+  assertEqual(entry.inSpec, 'media:pdf', 'inSpec should match');
+  assertEqual(entry.outSpec, 'media:txt;textable', 'outSpec should match');
+  assertEqual(entry.urnTags.op, 'extract', 'op tag should match');
+}
+
+function testMachine_mediaRegistryEntry_construction() {
+  const entry = new MediaRegistryEntry({
+    urn: 'media:pdf',
+    title: 'PDF Document',
+    media_type: 'application/pdf',
+    description: 'Portable Document Format'
+  });
+  assertEqual(entry.urn, 'media:pdf', 'URN should match');
+  assertEqual(entry.title, 'PDF Document', 'Title should match');
+  assertEqual(entry.mediaType, 'application/pdf', 'Media type should match');
+  assertEqual(entry.description, 'Portable Document Format', 'Description should match');
+}
+
+function testMachine_capRegistryClient_construction() {
+  const client = new CapRegistryClient('https://example.com', 600);
+  assert(client !== null, 'Client should be constructed');
+  // Invalidate should not throw
+  client.invalidate();
+}
+
+function testMachine_capRegistryEntry_defaults() {
+  // Verify that missing fields default gracefully
+  const entry = new CapRegistryEntry({ urn: 'cap:in=media:;op=test;out=media:' });
+  assertEqual(entry.urn, 'cap:in=media:;op=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.args), 'Args should default to array');
+  assertEqual(entry.args.length, 0, 'Args should be empty');
+}
+
 // Helper for route error tests
 function assertThrowsWithCode(fn, expectedCode) {
   try {
@@ -3621,6 +3861,33 @@ async function runTests() {
   runTest('ROUTE: media_urn_is_equivalent', testMachine_mediaUrnIsEquivalent);
   runTest('ROUTE: media_urn_is_comparable', testMachine_mediaUrnIsComparable);
 
+  // Phase 0A: Position tracking
+  console.log('\n--- route/position_tracking ---');
+  runTest('ROUTE: parseMachineWithAST_headerLocation', testMachine_parseMachineWithAST_headerLocation);
+  runTest('ROUTE: parseMachineWithAST_wiringLocation', testMachine_parseMachineWithAST_wiringLocation);
+  runTest('ROUTE: parseMachineWithAST_multilinePositions', testMachine_parseMachineWithAST_multilinePositions);
+  runTest('ROUTE: parseMachineWithAST_fanInSourceLocations', testMachine_parseMachineWithAST_fanInSourceLocations);
+  runTest('ROUTE: parseMachineWithAST_aliasMap', testMachine_parseMachineWithAST_aliasMap);
+  runTest('ROUTE: parseMachineWithAST_nodeMedia', testMachine_parseMachineWithAST_nodeMedia);
+  runTest('ROUTE: errorLocation_parseError', testMachine_errorLocation_parseError);
+  runTest('ROUTE: errorLocation_duplicateAlias', testMachine_errorLocation_duplicateAlias);
+  runTest('ROUTE: errorLocation_undefinedAlias', testMachine_errorLocation_undefinedAlias);
+
+  // Phase 0C: Machine.toMermaid()
+  console.log('\n--- route/mermaid ---');
+  runTest('ROUTE: toMermaid_linearChain', testMachine_toMermaid_linearChain);
+  runTest('ROUTE: toMermaid_loopEdge', testMachine_toMermaid_loopEdge);
+  runTest('ROUTE: toMermaid_emptyGraph', testMachine_toMermaid_emptyGraph);
+  runTest('ROUTE: toMermaid_fanIn', testMachine_toMermaid_fanIn);
+  runTest('ROUTE: toMermaid_fanOut', testMachine_toMermaid_fanOut);
+
+  // Phase 0B: CapRegistryClient
+  console.log('\n--- registry/client ---');
+  runTest('REGISTRY: capRegistryEntry_construction', testMachine_capRegistryEntry_construction);
+  runTest('REGISTRY: mediaRegistryEntry_construction', testMachine_mediaRegistryEntry_construction);
+  runTest('REGISTRY: capRegistryClient_construction', testMachine_capRegistryClient_construction);
+  runTest('REGISTRY: capRegistryEntry_defaults', testMachine_capRegistryEntry_defaults);
+
   // Summary
   console.log(`\n${passCount + failCount} tests: ${passCount} passed, ${failCount} failed`);
   if (failCount > 0) {

package/machine-parser.js

@@ -203,18 +203,20 @@ function peg$parse(input, options) {
   function peg$f0(stmts) {    return stmts;  }
   function peg$f1(inner) {    return inner;  }
   function peg$f2(a, c) {
-    return { type: 'header', alias: a, capUrn: c };
+    return { type: 'header', alias: a.value, capUrn: c.value, location: location(), aliasLocation: a.location, capUrnLocation: c.location };
   }
   function peg$f3(s, lc, t) {
-    return { type: 'wiring', sources: s, capAlias: lc.alias, isLoop: lc.isLoop, target: t };
+    return { type: 'wiring', sources: s.values, capAlias: lc.alias, isLoop: lc.isLoop, target: t.value, location: location(), sourceLocations: s.locations, capAliasLocation: lc.location, targetLocation: t.location };
   }
-  function peg$f4(a) {    return [a];  }
+  function peg$f4(a) {    return { values: [a.value], locations: [a.location] };  }
   function peg$f5(first, a) {    return a;  }
   function peg$f6(first, rest) {
-    return [first, ...rest];
+    return { values: [first.value, ...rest.map(r => r.value)], locations: [first.location, ...rest.map(r => r.location)] };
   }
-  function peg$f7(a) {    return { alias: a, isLoop: true };  }
-  function peg$f8(a) {    return { alias: a, isLoop: false };  }
+  function peg$f7(a) {    return { alias: a.value, isLoop: true, location: a.location };  }
+  function peg$f8(a) {    return { alias: a.value, isLoop: false, location: a.location };  }
+  function peg$f9(a) {    return { value: a, location: location() };  }
+  function peg$f10(c) {    return { value: c, location: location() };  }
   let peg$currPos = options.peg$currPos | 0;
   let peg$savedPos = peg$currPos;
   const peg$posDetailsCache = [{ line: 1, column: 1 }];
@@ -461,11 +463,11 @@ function peg$parse(input, options) {
     let s0, s1, s2, s3;
 
     s0 = peg$currPos;
-    s1 = peg$parsealias();
+    s1 = peg$parsealias_loc();
     if (s1 !== peg$FAILED) {
       s2 = peg$parse__();
       if (s2 !== peg$FAILED) {
-        s3 = peg$parsecap_urn();
+        s3 = peg$parsecap_urn_loc();
         if (s3 !== peg$FAILED) {
           peg$savedPos = s0;
           s0 = peg$f2(s1, s3);
@@ -489,19 +491,19 @@ function peg$parse(input, options) {
     let s0, s1, s2, s3, s4, s5, s6, s7, s8, s9;
 
     s0 = peg$currPos;
-    s1 = peg$parsesource();
+    s1 = peg$parsesource_loc();
     if (s1 !== peg$FAILED) {
       s2 = peg$parse_();
       s3 = peg$parsearrow();
       if (s3 !== peg$FAILED) {
         s4 = peg$parse_();
-        s5 = peg$parseloop_cap();
+        s5 = peg$parseloop_cap_loc();
         if (s5 !== peg$FAILED) {
           s6 = peg$parse_();
           s7 = peg$parsearrow();
           if (s7 !== peg$FAILED) {
             s8 = peg$parse_();
-            s9 = peg$parsealias();
+            s9 = peg$parsealias_loc();
             if (s9 !== peg$FAILED) {
               peg$savedPos = s0;
               s0 = peg$f3(s1, s5, s9);
@@ -529,22 +531,22 @@ function peg$parse(input, options) {
     return s0;
   }
 
-  function peg$parsesource() {
+  function peg$parsesource_loc() {
     let s0;
 
-    s0 = peg$parsegroup();
+    s0 = peg$parsegroup_loc();
     if (s0 === peg$FAILED) {
-      s0 = peg$parsesingle_alias();
+      s0 = peg$parsesingle_alias_loc();
     }
 
     return s0;
   }
 
-  function peg$parsesingle_alias() {
+  function peg$parsesingle_alias_loc() {
     let s0, s1;
 
     s0 = peg$currPos;
-    s1 = peg$parsealias();
+    s1 = peg$parsealias_loc();
     if (s1 !== peg$FAILED) {
       peg$savedPos = s0;
       s1 = peg$f4(s1);
@@ -554,7 +556,7 @@ function peg$parse(input, options) {
     return s0;
   }
 
-  function peg$parsegroup() {
+  function peg$parsegroup_loc() {
     let s0, s1, s2, s3, s4, s5, s6, s7, s8;
 
     s0 = peg$currPos;
@@ -567,7 +569,7 @@ function peg$parse(input, options) {
     }
     if (s1 !== peg$FAILED) {
       s2 = peg$parse_();
-      s3 = peg$parsealias();
+      s3 = peg$parsealias_loc();
       if (s3 !== peg$FAILED) {
         s4 = [];
         s5 = peg$currPos;
@@ -580,7 +582,7 @@ function peg$parse(input, options) {
         }
         if (s6 !== peg$FAILED) {
           s7 = peg$parse_();
-          s8 = peg$parsealias();
+          s8 = peg$parsealias_loc();
           if (s8 !== peg$FAILED) {
             peg$savedPos = s5;
             s5 = peg$f5(s3, s8);
@@ -605,7 +607,7 @@ function peg$parse(input, options) {
             }
             if (s6 !== peg$FAILED) {
               s7 = peg$parse_();
-              s8 = peg$parsealias();
+              s8 = peg$parsealias_loc();
               if (s8 !== peg$FAILED) {
                 peg$savedPos = s5;
                 s5 = peg$f5(s3, s8);
@@ -653,7 +655,7 @@ function peg$parse(input, options) {
     return s0;
   }
 
-  function peg$parseloop_cap() {
+  function peg$parseloop_cap_loc() {
     let s0, s1, s2, s3;
 
     s0 = peg$currPos;
@@ -667,7 +669,7 @@ function peg$parse(input, options) {
     if (s1 !== peg$FAILED) {
       s2 = peg$parse__();
       if (s2 !== peg$FAILED) {
-        s3 = peg$parsealias();
+        s3 = peg$parsealias_loc();
         if (s3 !== peg$FAILED) {
           peg$savedPos = s0;
           s0 = peg$f7(s3);
@@ -685,7 +687,7 @@ function peg$parse(input, options) {
     }
     if (s0 === peg$FAILED) {
       s0 = peg$currPos;
-      s1 = peg$parsealias();
+      s1 = peg$parsealias_loc();
       if (s1 !== peg$FAILED) {
         peg$savedPos = s0;
         s1 = peg$f8(s1);
@@ -745,6 +747,20 @@ function peg$parse(input, options) {
     return s0;
   }
 
+  function peg$parsealias_loc() {
+    let s0, s1;
+
+    s0 = peg$currPos;
+    s1 = peg$parsealias();
+    if (s1 !== peg$FAILED) {
+      peg$savedPos = s0;
+      s1 = peg$f9(s1);
+    }
+    s0 = s1;
+
+    return s0;
+  }
+
   function peg$parsealias() {
     let s0, s1, s2, s3, s4;
 
@@ -791,6 +807,20 @@ function peg$parse(input, options) {
     return s0;
   }
 
+  function peg$parsecap_urn_loc() {
+    let s0, s1;
+
+    s0 = peg$currPos;
+    s1 = peg$parsecap_urn();
+    if (s1 !== peg$FAILED) {
+      peg$savedPos = s0;
+      s1 = peg$f10(s1);
+    }
+    s0 = s1;
+
+    return s0;
+  }
+
   function peg$parsecap_urn() {
     let s0, s1, s2, s3, s4;
 

package/machine.pegjs

@@ -1,6 +1,7 @@
 // Bracket-delimited machine notation grammar for Peggy.
 //
 // This grammar mirrors the Rust pest grammar in machine.pest exactly.
+// All actions return location() for LSP position tracking.
 //
 // Examples:
 //   [extract cap:in="media:pdf";op=extract;out="media:txt;textable"]
@@ -15,32 +16,38 @@ stmt = "[" _ inner:inner _ "]" _ { return inner; }
 inner = wiring / header
 
 // Header: alias followed by a cap URN starting with "cap:".
-header = a:alias __ c:cap_urn {
-  return { type: 'header', alias: a, capUrn: c };
+header = a:alias_loc __ c:cap_urn_loc {
+  return { type: 'header', alias: a.value, capUrn: c.value, location: location(), aliasLocation: a.location, capUrnLocation: c.location };
 }
 
 // Wiring: source -> loop_cap -> target
-wiring = s:source _ arrow _ lc:loop_cap _ arrow _ t:alias {
-  return { type: 'wiring', sources: s, capAlias: lc.alias, isLoop: lc.isLoop, target: t };
+wiring = s:source_loc _ arrow _ lc:loop_cap_loc _ arrow _ t:alias_loc {
+  return { type: 'wiring', sources: s.values, capAlias: lc.alias, isLoop: lc.isLoop, target: t.value, location: location(), sourceLocations: s.locations, capAliasLocation: lc.location, targetLocation: t.location };
 }
 
-source = group / single_alias
+source_loc = group_loc / single_alias_loc
 
-single_alias = a:alias { return [a]; }
+single_alias_loc = a:alias_loc { return { values: [a.value], locations: [a.location] }; }
 
-group = "(" _ first:alias rest:("," _ a:alias { return a; })+ _ ")" {
-  return [first, ...rest];
+group_loc = "(" _ first:alias_loc rest:("," _ a:alias_loc { return a; })+ _ ")" {
+  return { values: [first.value, ...rest.map(r => r.value)], locations: [first.location, ...rest.map(r => r.location)] };
 }
 
-loop_cap = "LOOP" __ a:alias { return { alias: a, isLoop: true }; }
-         / a:alias { return { alias: a, isLoop: false }; }
+loop_cap_loc = "LOOP" __ a:alias_loc { return { alias: a.value, isLoop: true, location: a.location }; }
+            / a:alias_loc { return { alias: a.value, isLoop: false, location: a.location }; }
 
 arrow = "-"+ ">"
 
+// Alias with location tracking
+alias_loc = a:alias { return { value: a, location: location() }; }
+
 // Alias: starts with alpha or underscore, continues with alphanumeric, underscore, or hyphen.
 // This is atomic — no whitespace skipping inside.
 alias = $( [a-zA-Z_] [a-zA-Z0-9_-]* )
 
+// Cap URN with location tracking
+cap_urn_loc = c:cap_urn { return { value: c, location: location() }; }
+
 // Cap URN: starts with "cap:", reads until the statement-closing "]",
 // except quoted strings can contain "]".
 cap_urn = $( "cap:" cap_urn_body* )

package/package.json

@@ -37,5 +37,5 @@
     "pretest": "npm run build:parser",
     "test": "node capdag.test.js"
   },
-  "version": "0.93.23689"
+  "version": "0.94.24331"
 }