@geml/geml 1.3.2 → 1.4.3

package/README.md

@@ -46,28 +46,105 @@ Requires Node ≥ 22.
 
 ## CLI
 
+The CLI is built around one question: can a single agent author and maintain an
+entire `.geml` file from the command line — create, add, edit, delete, and copy
+blocks in from other files? Three tests keep the command set honest:
+
+- **Complete** — every step of a document's life has a verb, so an agent never
+  rewrites the whole file to change one block.
+- **Ergonomic** — few flags, sensible defaults, and pipeline-friendly I/O, so
+  multi-step edits chain without ceremony.
+- **Consistent** — behavior is uniform and predictable: name a target `#id` and
+  the content adopts it, every write is guarded, a file is edited in place while
+  `-` streams to stdout.
+
+The command set borrows from two settled models rather than inventing one, and
+they overlap where it counts. **A document is a table**: a block is a row, its
+`#id` is the primary key (unique per document), and `[[#id]]`/`[t](#id)`/`[^id]`/
+`data=#id` are foreign keys — so `get`/`add`/`set`/`delete` are
+SELECT/INSERT/UPDATE/DELETE. **A block is also a resource** at a URI-like address
+(`file#id`), named before the operation, the way REST puts the noun first. Both
+models agree on a small orthogonal verb set instead of a method per use case, and
+they agree on idempotence: `set` and `delete` are idempotent (deleting a missing
+id is a no-op, so a retry is safe), `add` is not.
+
+Where they diverge, each covers what the other cannot. The relational view names
+the integrity rules: the write guard is a constraint check with rollback, and
+`delete` merely *warning* about references it leaves dangling is a **deferred**
+foreign-key check, not `ON DELETE RESTRICT`. It also explains `rename`, the verb
+most open to "can this be cut" — a **primary-key update with a cascading
+foreign-key rewrite**, irreducible because `delete` + `add` would leave every
+reference dangling and nothing else rewrites references in bulk. HTTP has no
+method for that at all. The REST view supplies what a database deliberately does
+not: every call is **stateless** — no session, no current document, no config
+file, no environment variable — which is what lets calls be retried,
+parallelized, and piped.
+
+Both pay off in undo. Because the verbs are orthogonal, each edit has exactly one
+inverse, so `revert` never needs to know which verb made a change — it reconciles
+a block to a revision in three cases (content changed, row missing, row extra)
+and there is no fourth, while `rename` is its own inverse and needs no history at
+all. A wider, RPC-shaped verb set (`replace`, `move`, `merge`, `split`, …) would
+need a per-verb inverse and an operation log to pick one — an undo-stack engine
+instead of three branches. Full rationale:
+[`docs/design/specs/2026-07-24-geml-block-mutation-cli-design.md`](../docs/design/specs/2026-07-24-geml-block-mutation-cli-design.md).
+
 Every command reads a file path, or `-` for stdin. Exit codes: `0` ok ·
 `1` document/operation error · `2` usage error.
 
 ```sh
-geml get    file.geml '#id'      # print ONE block by id — a heading id yields its whole section
-geml set    file.geml '#id' --from new.geml  # replace just that block; re-parsed, refused if it breaks the doc
-geml check  file.geml            # validate only: diagnostics + exit code
-geml check --json file.geml      # machine-readable: diagnostics array (or {"error":…} on IO failure)
-geml        file.geml            # full document-model JSON
-geml history <commit|verify|show|restore|log> file.geml [...]   # .gemlhistory version sidecar
-geml revert file.geml '#id' [--to -1]  # roll ONE block back to an earlier revision (-N | latest | id)
-geml render file.geml -o out.html  # one self-contained, interactive HTML file
-geml export file.geml -o out.md    # project to GitHub-Flavored Markdown (lossy; notes on stderr)
-geml convert in.md     -o out.geml # Markdown -> GEML
-geml fmt    file.geml            # canonical re-format (idempotent)
-geml codemap <build|verify|render|serve|refresh|find|mcp>  # your codebase's call graph as GEML docs
-geml --help | --version          # --version --json prints {"parser","spec"}
+geml doc.geml                       # document-model JSON (default --to json)
+geml doc.geml --to md|html|geml     # convert; geml notes.md -> GEML
+geml get    doc.geml ['#id']        # list addressable ids, or print one block (heading id = its section)
+geml set    doc.geml '#id' [--head|--body] [--in F[#src]]   # replace a block's content (id kept)
+geml add    doc.geml (--append|--before #id|--after #id) [--in F[#src]]   # insert a fragment
+geml delete doc.geml '#id' ['#id2' …]     # remove one or more blocks
+geml rename doc.geml '#old' '#new'        # rename an id + every reference to it
+geml revert doc.geml '#id' [--rev -1]     # undo a block: splice / resurrect / remove
+geml check  doc.geml [--root <dir>]       # validate only: diagnostics + exit code (--json for the array)
+geml history <commit|verify|show|restore|log> doc.geml [...]   # .gemlhistory version sidecar
+geml codemap <build|verify|render|serve|refresh|find|mcp>      # your codebase's call graph as GEML docs
+geml --help | --version             # --version --json prints {"parser","spec"}
 ```
 
-The agent loop: `geml get` a block → edit it → `geml set` (guarded splice) →
+The agent loop: `geml get` a block → `set`/`add`/`delete`/`rename` it →
 `geml check` → `geml history commit` — small, precise, verifiable edits.
 
+Conversion is one entry — `geml <file> [--to json|html|md|geml]`; the input
+format is inferred (`--from` overrides > extension > GEML), the target is `--to`
+(default: GEML → JSON, Markdown → GEML), and `-o` names the output path.
+
+`set` and `add` take their content from `--in F` (F's block whose id equals the
+target), `--in F#src` (F's block `#src`), or stdin (raw bytes). `set` **replaces
+a whole block** and normalizes the content's id to the target — so you can fork
+any block into this slot without hand-editing its id (`--head` swaps just the
+head line, `--body` just the body). `add` **inserts a fragment** (one or more
+blocks, or bare prose) at `--append` / `--before #id` / `--after #id`, keeping
+the content's own ids (a collision is refused). `delete` removes one or more
+ids; `rename` rewrites an id's declaration and every reference to it.
+
+Mutations (`set`/`add`/`delete`/`rename`) write the **whole updated document**:
+in place when the input is a file, or to **stdout** when the input is `-`; `-o`
+redirects the write (`-o -` forces stdout), so edits pipe cleanly. Every write
+is guarded — re-parsed and refused if it would break the document or drop an id
+(a reference left dangling by `delete` is a warning, not a refusal; `geml check`
+flags it later).
+
+Undo is `revert`, which reconciles one block to a past revision (`--rev`, default
+`-1`): it **splices** back changed content, **resurrects** a deleted block (placed
+by its old neighbours, or `--append`/`--before`/`--after`), or **removes** a block
+that did not exist then. So each forward edit has an inverse:
+
+| forward edit | undo |
+|---|---|
+| `set #id` | `revert #id` (splice) |
+| `delete #id` | `revert #id` (resurrect) |
+| `add #id` | `revert #id` (remove) — or `delete #id` |
+| `rename #old #new` | `rename #new #old` (self-inverse) |
+
+`revert` reads the `.gemlhistory` sidecar, so `set`/`delete`/`add` undo needs a
+prior `geml history commit`; `rename` is its own inverse and needs no history.
+
 A **heading's** `#id` addresses its whole **section** — the heading line through
 the line before the next heading of the same-or-higher level — so the prose
 under a heading is block-editable with no extra syntax.

package/codemap/build.mjs

@@ -46,6 +46,7 @@ import { loadOrSeedFoldings } from "./foldings.mjs";
 import { detectEntries } from "./entries.mjs";
 import { discoverModuleRoots } from "./normalize.mjs";
 import { recipeFingerprint, trustRecipe, RECIPE_VERSION } from "./recipe-trust.mjs";
+import { buildCrossStackOverlay } from "./cross-stack.mjs";
 
 const args = process.argv.slice(2);
 const flag = (name, dflt) => {
@@ -407,11 +408,40 @@ if (excludedCount) {
   );
 }
 
+// Cross-stack API links: detect frontend HTTP call sites + backend route
+// declarations across the merged graph and append `http` edges wiring each
+// caller's enclosing symbol to the handler's — the seam that joins a full
+// stack's two otherwise-disjoint trees. Kept OUT of the verified `calls`
+// relation (own edge kind + confidence). Best-effort: a detector failure must
+// never sink an otherwise-good build.
+try {
+  const rootAbs = resolve(root);
+  const scanFiles = [...new Set(symbols.map((s) => s.file))];
+  const { edges: httpEdges, audit } = buildCrossStackOverlay({
+    symbols,
+    files: scanFiles,
+    readText: (rel) => { try { return readFileSync(join(rootAbs, ...rel.split("/")), "utf8"); } catch { return null; } },
+  });
+  for (const e of httpEdges) edges.push(e);
+  if (httpEdges.length) {
+    console.error(
+      `cross-stack: ${httpEdges.length} api link(s) across ${audit.endpoints} endpoint(s)`
+      + (audit.divergent.length ? `, ${audit.divergent.length} method-divergent` : "")
+      + (audit.deadRoutes.length ? `, ${audit.deadRoutes.length} uncalled route(s)` : ""));
+    mkdirSync(join(outDir, "_index"), { recursive: true });
+    const auditPath = join(outDir, "_index", "cross-stack.json");
+    const auditContent = JSON.stringify(audit, null, 2) + "\n";
+    if (!existsSync(auditPath) || readFileSync(auditPath, "utf8") !== auditContent) writeFileSync(auditPath, auditContent);
+  }
+} catch (e) {
+  console.error(`cross-stack overlay skipped: ${e.message}`);
+}
+
 // Exchange format on disk — the layer contract (§3). Deterministic order so
 // the jsonl files diff cleanly across builds.
 symbols.sort((a, b) => a.anchor.localeCompare(b.anchor));
 edges.sort((a, b) =>
-  a.from.localeCompare(b.from) || a.kind.localeCompare(b.kind)
+  String(a.from ?? a.from_text ?? "").localeCompare(String(b.from ?? b.from_text ?? "")) || a.kind.localeCompare(b.kind)
   || String(a.to ?? a.to_text).localeCompare(String(b.to ?? b.to_text)));
 mkdirSync(buildDir, { recursive: true });
 const jsonl = (rows) => rows.map((r) => JSON.stringify(r)).join("\n") + "\n";

package/codemap/cross-stack.mjs

@@ -0,0 +1,303 @@
+// geml-code-graph cross-stack API links — connect the two disjoint trees a
+// full-stack repo produces (frontend call sites ⇄ backend route handlers).
+//
+// A frontend "call" to the backend is not a symbol reference — it is an HTTP
+// string crossing a network boundary, so SCIP/Joern never link it. The join
+// key is `METHOD + normalized path`. These links are inherently NOT
+// compiler-verifiable, so they are emitted as their OWN edge kinds
+// (`http-call` / `http-serve`) with a `confidence`, kept strictly separate
+// from the verified `calls` graph — the codemap never launders a heuristic
+// guess into a verified reference.
+//
+// Pluggable + framework-agnostic by design: framework knowledge lives ONLY in
+// the per-language detectors below; the matcher/overlay speak a single
+// normalized shape ({method, path}). Adding a framework = adding a detector.
+//
+// Pure: given the indexed `files` list + an injectable `readText`, and the
+// already-merged graph (`symbols`/`edges`), it appends synthetic endpoint
+// bridge nodes + link edges. No filesystem walking of its own.
+
+// ───────────────────────── path normalization ──────────────────────────────
+// {id} / :id / ${x} path params all collapse to a single wildcard token so a
+// frontend `/users/${id}` matches a backend `/users/{id}` matches `/users/:id`.
+function normPath(p) {
+  let s = String(p).split("?")[0].split("#")[0];
+  s = s.replace(/\$\{[^}]*\}/g, "{}").replace(/\{[^}]*\}/g, "{}").replace(/:[A-Za-z0-9_]+/g, "{}");
+  s = s.replace(/\{\}(?:\{\})+/g, "{}");
+  if (s.length > 1 && s.endsWith("/")) s = s.slice(0, -1);
+  return s || "/";
+}
+const pathSegs = (p) => normPath(p).split("/");
+function exactEq(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i] && a[i] !== "{}" && b[i] !== "{}") return false;
+  return true;
+}
+function prefixCover(pre, fe) {
+  if (fe.length < pre.length) return false;
+  for (let i = 0; i < pre.length; i++) if (pre[i] !== "" && pre[i] !== fe[i] && pre[i] !== "{}" && fe[i] !== "{}") return false;
+  return true;
+}
+const methodOk = (fe, be) => fe === "ANY" || be === "ANY" || fe === be;
+
+// ─────────────────────────── backend detectors ─────────────────────────────
+// Each returns [{ method, path, prefix?, line, via }]. `prefix:true` means the
+// route matches any path beginning with `path` (Spring "/x/**", Rust
+// starts_with guards). `method:"ANY"` means the declaration does not pin one.
+
+// Spring MVC: class-level @RequestMapping prefix + method-level mappings.
+function detectSpringRoutes(text) {
+  const routes = [];
+  const METHOD_OF = { Get: "GET", Post: "POST", Put: "PUT", Delete: "DELETE", Patch: "PATCH", Request: "ANY" };
+  // class-level prefix: the last @RequestMapping("...") that precedes `class `.
+  let classPrefix = "";
+  // `\bclass\s` (linear) — NOT `(?:public\s+|…)*class\s`, whose repeated
+  // `\s+` group backtracks O(N^2) on a long `public ` run with no `class`
+  // (crafted .java DoS). The leading modifiers don't affect the index we need
+  // (the text before `class`, scanned for @RequestMapping).
+  const classIdx = text.search(/\bclass\s/);
+  if (classIdx > 0) {
+    const head = text.slice(0, classIdx);
+    const cm = [...head.matchAll(/@RequestMapping\s*\(([^)]*)\)/g)].pop();
+    if (cm) { const p = pathsFromJavaAnno(cm[1])[0]; if (p) classPrefix = p.replace(/\/$/, ""); }
+  }
+  const lines = text.split(/\r?\n/);
+  const RE = /@(Get|Post|Put|Delete|Patch|Request)Mapping\s*\(([^)]*)\)/g;
+  for (let i = 0; i < lines.length; i++) {
+    let m; RE.lastIndex = 0;
+    while ((m = RE.exec(lines[i]))) {
+      // skip the class-level annotation itself (line is followed by a class decl)
+      if (/\bclass\s/.test(lines[i]) || (lines[i + 1] && /\bclass\s/.test(lines[i + 1]))) continue;
+      const method = METHOD_OF[m[1]];
+      for (const raw of pathsFromJavaAnno(m[2])) {
+        const full = joinPath(classPrefix, raw);
+        routes.push({ method, path: full, line: i + 1, via: "spring" });
+      }
+    }
+  }
+  return routes;
+}
+// Extract path string(s) from a Spring annotation arg list, honoring
+// `value=`/`path=`, brace lists {"a","b"}, and ignoring produces=/consumes=.
+function pathsFromJavaAnno(argstr) {
+  const braced = /(?:value|path)\s*=\s*\{([^}]*)\}/.exec(argstr);
+  if (braced) return [...braced[1].matchAll(/"([^"]*)"/g)].map((x) => x[1]);
+  const named = /(?:value|path)\s*=\s*"([^"]*)"/.exec(argstr);
+  if (named) return [named[1]];
+  const brace = /^\s*\{([^}]*)\}/.exec(argstr);
+  if (brace) return [...brace[1].matchAll(/"([^"]*)"/g)].map((x) => x[1]);
+  const first = /"([^"]*)"/.exec(argstr);
+  return first ? [first[1]] : [""];
+}
+function joinPath(prefix, sub) {
+  if (!prefix) return sub || "/";
+  if (!sub || sub === "/" || sub === "") return prefix || "/";
+  return (prefix + "/" + sub).replace(/\/{2,}/g, "/");
+}
+
+// Rust CF-worker / bespoke router: `match (method, path)` tuple arms +
+// `if path == "…"` / `path.starts_with("…")` guards.
+const RUST_BROAD = new Set(["/admin", "/admin/", "/accounts", "/accounts/", "/", "/console", "/console/", "/api", "/api/"]);
+function detectRustRoutes(text) {
+  const routes = [];
+  const lines = text.split(/\r?\n/);
+  const TUPLE = /\(\s*"(GET|POST|PUT|DELETE|PATCH)"\s*,\s*"([^"]+)"\s*\)/g;
+  const TUPLE_SW = /\(\s*"(GET|POST|PUT|DELETE|PATCH)"\s*,\s*[a-z_]+\s*\)\s*if\s+[a-z_]+\.starts_with\(\s*"([^"]+)"/g;
+  const GUARD_EQ = /\bpath\s*==\s*"([^"]+)"/g;
+  const GUARD_SW = /\bpath\.starts_with\(\s*"([^"]+)"\s*\)/g;
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i]; let m;
+    TUPLE.lastIndex = 0; while ((m = TUPLE.exec(ln))) if (m[2].startsWith("/")) routes.push({ method: m[1], path: m[2], line: i + 1, via: "rust-worker" });
+    TUPLE_SW.lastIndex = 0; while ((m = TUPLE_SW.exec(ln))) if (m[2].startsWith("/")) routes.push({ method: m[1], path: m[2], prefix: true, line: i + 1, via: "rust-worker" });
+    GUARD_EQ.lastIndex = 0; while ((m = GUARD_EQ.exec(ln))) if (m[1].startsWith("/") && !RUST_BROAD.has(m[1])) routes.push({ method: "ANY", path: m[1], line: i + 1, via: "rust-guard" });
+    GUARD_SW.lastIndex = 0; while ((m = GUARD_SW.exec(ln))) { const p = m[1].replace(/\/$/, ""); if (m[1].startsWith("/") && !RUST_BROAD.has(m[1])) routes.push({ method: "ANY", path: p, prefix: true, line: i + 1, via: "rust-guard" }); }
+  }
+  return routes;
+}
+
+function detectBackendRoutes(relFile, text) {
+  if (relFile.endsWith(".java")) return detectSpringRoutes(text);
+  if (relFile.endsWith(".rs")) return detectRustRoutes(text);
+  return [];
+}
+
+// ─────────────────────────── frontend detector ─────────────────────────────
+// Hub-aware: raw fetch/$fetch/useFetch AND object-hub calls. Covers both the
+// standard verbs (`api.get('/x')`, `axios.put(...)`) and the common wrapped-hub
+// convention (`request.sendGet('/x')`, `http.sendJson(...)`, `req.send(...)`).
+// The "resolved path must start with /" filter drops non-API `.get()`/`.send()`
+// noise (Map.get('k'), emitter.send(evt), etc.). Verb → HTTP method below.
+const FE_VERB = "get|post|put|delete|patch|sendGet|sendPost|sendPut|sendDelete|sendPatch|sendJson|send|request";
+const FE_CALL = new RegExp(`\\b(?:\\$fetch|useFetch|fetch)\\s*\\(|\\b[\\w$]+\\.(${FE_VERB})\\s*\\(`, "g");
+const VERB_METHOD = {
+  get: "GET", post: "POST", put: "PUT", delete: "DELETE", patch: "PATCH",
+  sendGet: "GET", sendPost: "POST", sendPut: "PUT", sendDelete: "DELETE",
+  sendPatch: "PATCH", sendJson: "POST", send: "ANY", request: "ANY",
+};
+function readCallArg(src, startIdx) {
+  let depth = 0, i = startIdx, arg = "", inStr = null;
+  // A real API-call first argument is short. Cap the scan so an UNBALANCED
+  // `fetch(` (no matching close paren) can't walk to end-of-file on every match
+  // (crafted-source DoS); a truncated arg simply fails to resolve as a path.
+  const max = Math.min(src.length, startIdx + 4096);
+  for (; i < max; i++) {
+    const c = src[i];
+    if (inStr) { arg += c; if (c === inStr && src[i - 1] !== "\\") inStr = null; continue; }
+    if (c === '"' || c === "'" || c === "`") { inStr = c; arg += c; continue; }
+    if (c === "(" || c === "[" || c === "{") { depth++; arg += c; continue; }
+    if (c === ")" || c === "]" || c === "}") { if (depth === 0) break; depth--; arg += c; continue; }
+    if (c === "," && depth === 0) break;
+    arg += c;
+  }
+  return { arg: arg.trim(), end: i };
+}
+function resolveFeUrl(arg) {
+  arg = arg.trim();
+  let body = null;
+  if (arg.startsWith("`")) body = arg.slice(1, arg.lastIndexOf("`"));
+  else { const m = /^(['"])(.*?)\1/.exec(arg); if (m) body = m[2]; }
+  if (body === null) return { path: null, dynamic: true };
+  // strip scheme://authority and a leading base interpolation (${apiBase}/…)
+  let s = body.replace(/^https?:\/\/[^/]*/i, "").replace(/^\$\{[^}]*\}/, "");
+  if (!s.startsWith("/")) return { path: null, dynamic: true }; // non-path first arg → not an API call
+  s = s.split("?")[0].split("#")[0].replace(/\$\{[^}]*\}/g, "{}");
+  return { path: normPath(s), dynamic: false };
+}
+function detectFrontendCalls(relFile, text) {
+  if (!/\.(vue|svelte|ts|tsx|js|jsx|mjs|cjs)$/.test(relFile)) return [];
+  const calls = [];
+  let m; FE_CALL.lastIndex = 0;
+  while ((m = FE_CALL.exec(text))) {
+    const { arg, end } = readCallArg(text, FE_CALL.lastIndex);
+    FE_CALL.lastIndex = end; // resume PAST the consumed arg — not re-scan it (O(N^2))
+    const { path, dynamic } = resolveFeUrl(arg);
+    if (dynamic || !path) continue;
+    // method: verb from the hub call, else `method:` in the options object, else GET
+    let method = "GET";
+    if (m[1] && VERB_METHOD[m[1]]) method = VERB_METHOD[m[1]];
+    else { const mm = /method\s*:\s*['"`]?(GET|POST|PUT|DELETE|PATCH)/i.exec(text.slice(end, end + 220)); if (mm) method = mm[1].toUpperCase(); }
+    const line = text.slice(0, m.index).split(/\r?\n/).length;
+    calls.push({ method, path, line, raw: arg.slice(0, 80) });
+  }
+  return calls;
+}
+
+// ───────────────────────────── surface scan ────────────────────────────────
+export function scanApiSurface({ files = [], root, readText }) {
+  const calls = [], routes = [];
+  for (const rel of files) {
+    let text; try { text = readText(rel); } catch { continue; }
+    if (text == null) continue;
+    for (const c of detectFrontendCalls(rel, text)) calls.push({ ...c, file: rel });
+    for (const r of detectBackendRoutes(rel, text)) routes.push({ ...r, file: rel });
+  }
+  return { calls, routes };
+}
+
+// ─────────────────────────────── matching ──────────────────────────────────
+// For each FE call, find the backend route it hits. A route is a candidate if
+// its (possibly-prefix) path covers the call path; method must agree unless one
+// side is ANY. Records method-divergent hits (path matches, verb differs) as a
+// contract-drift signal rather than dropping them.
+export function matchLinks({ calls, routes }) {
+  const links = [], unmatchedFE = [], divergent = [];
+  const hitRoute = new Set();
+  const routeKey = (r) => `${r.method} ${r.path} ${r.file}:${r.line}`;
+  // Segment each route ONCE, not once per (call, route) pair — the split was
+  // the dominant cost of the O(calls×routes) match.
+  const routeSegs = routes.map((r) => ({ r, segs: pathSegs(r.path) }));
+  for (const c of calls) {
+    const cs = pathSegs(c.path);
+    let pathHit = null, methodHit = null;
+    for (const { r, segs } of routeSegs) {
+      const ok = r.prefix ? prefixCover(segs, cs) : exactEq(segs, cs);
+      if (!ok) continue;
+      if (!pathHit) pathHit = r;
+      if (methodOk(c.method, r.method)) { methodHit = r; break; }
+    }
+    if (methodHit) {
+      links.push({ call: c, route: methodHit, confidence: methodHit.prefix ? "medium" : "high" });
+      hitRoute.add(routeKey(methodHit));
+    } else if (pathHit) {
+      divergent.push({ call: c, route: pathHit });
+      links.push({ call: c, route: pathHit, confidence: "low", methodDivergent: true });
+      hitRoute.add(routeKey(pathHit));
+    } else {
+      unmatchedFE.push(c);
+    }
+  }
+  const deadRoutes = routes.filter((r) => !hitRoute.has(routeKey(r)));
+  return { links, unmatchedFE, divergent, deadRoutes };
+}
+
+// ─────────────────────────── overlay assembly ──────────────────────────────
+// Turn matched links into cross-stack graph edges. The endpoint (METHOD +
+// normalized path) is carried as an edge LABEL, not a node — one `http` edge
+// per matched call runs directly from the frontend caller's enclosing symbol
+// to the backend handler's enclosing symbol, so the two otherwise-disjoint
+// trees become one connected graph without inventing a node kind that emit's
+// function-centric model (and the viewer) would have to learn.
+function enclosingIndex(symbols) {
+  const byFile = new Map();
+  for (const s of symbols) {
+    if (!s.file) continue;
+    if (!byFile.has(s.file)) byFile.set(s.file, []);
+    byFile.get(s.file).push(s);
+  }
+  return (file, line) => {
+    const list = byFile.get(file);
+    if (!list) return null;
+    let best = null, bestSpan = Infinity;
+    for (const s of list) {
+      if (s.kind === "File") continue; // never attribute to a file node — its
+      // block is only emitted in multi-file containers, so a ref to it can
+      // dangle; the caller falls back to `file:line` text (lenient in verify).
+      const a = s.line_start ?? 0, b = s.line_end ?? a;
+      if (line >= a && line <= b && b - a < bestSpan) { best = s; bestSpan = b - a; }
+    }
+    return best; // a function/test symbol, or null when none encloses the line
+  };
+}
+
+export function buildCrossStackOverlay({ symbols = [], files = [], readText }) {
+  const scan = scanApiSurface({ files, readText });
+  const { links, unmatchedFE, divergent, deadRoutes } = matchLinks(scan);
+  const enclosing = enclosingIndex(symbols);
+  const httpEdges = [];
+  const endpoints = new Set();
+  for (const { call, route, confidence, methodDivergent } of links) {
+    const method = route.method === "ANY" ? call.method : route.method;
+    const endpoint = `${method} ${normPath(route.path)}`;
+    endpoints.add(endpoint);
+    const feFn = enclosing(call.file, call.line);
+    // A route declaration often sits just ABOVE its handler (Spring's
+    // `@GetMapping` annotation, a decorator): if the exact line lands on the
+    // file node rather than a function, probe a few lines down for the handler.
+    let beFn = enclosing(route.file, route.line);
+    for (let d = 1; d <= 3 && !beFn; d++) beFn = enclosing(route.file, route.line + d);
+    httpEdges.push({
+      kind: "http",
+      from: feFn ? feFn.anchor : undefined,
+      from_text: feFn ? undefined : `${call.file}:${call.line}`,
+      to: beFn ? beFn.anchor : undefined,
+      to_text: beFn ? undefined : `${route.file}:${route.line}`,
+      endpoint,
+      confidence,
+      methodDivergent: methodDivergent || undefined,
+      site: { file: call.file, line: call.line },
+    });
+  }
+  return {
+    edges: httpEdges,
+    audit: {
+      matched: links.length,
+      endpoints: endpoints.size,
+      divergent: divergent.map((d) => ({ fe: `${d.call.method} ${d.call.path}`, feSite: `${d.call.file}:${d.call.line}`, be: `${d.route.method} ${normPath(d.route.path)}`, beSite: `${d.route.file}:${d.route.line}` })),
+      unmatchedFE: unmatchedFE.map((c) => ({ call: `${c.method} ${c.path}`, site: `${c.file}:${c.line}` })),
+      deadRoutes: deadRoutes.map((r) => ({ route: `${r.method} ${normPath(r.path)}`, site: `${r.file}:${r.line}` })),
+    },
+  };
+}
+
+// exported for unit tests
+export const _internal = { normPath, detectSpringRoutes, detectRustRoutes, detectFrontendCalls, enclosingIndex };

package/codemap/emit.mjs

@@ -177,6 +177,27 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
       unresBySym.get(e.from).add(e.to_text);
     }
   }
+
+  // ---- edges (stage B: cross-stack `http` links) ----
+  // Heuristic frontend-caller → backend-handler links (codemap/cross-stack.mjs),
+  // emitted into their OWN #api-calls / #api-served-by tables so they never mix
+  // with the verified `calls` graph. Either endpoint may be unresolved (a call
+  // or route outside any indexed function) — then the *_text file:line rides in
+  // the cell instead of a #ref.
+  const httpOut = new Map(); // FE-fn anchor -> [http edge]
+  const httpIn = new Map();  // BE-fn anchor -> [http edge]
+  for (const e of edges) {
+    if (e.kind !== "http") continue;
+    if (e.from !== undefined && docOfAnchor.has(e.from)) {
+      if (!httpOut.has(e.from)) httpOut.set(e.from, []);
+      httpOut.get(e.from).push(e);
+    }
+    if (e.to !== undefined && docOfAnchor.has(e.to)) {
+      if (!httpIn.has(e.to)) httpIn.set(e.to, []);
+      httpIn.get(e.to).push(e);
+    }
+  }
+
   const isLeaf = (s) =>
     (s.kind === "Function" || s.kind === "Test") &&
     !(outCalls.get(s.anchor) > 0) && (inBySym.get(s.anchor)?.length ?? 0) >= 1;
@@ -325,6 +346,33 @@ export function emit({ symbols, edges, outDir, buildDir, repoName, container = "
     const unTable = csv("unresolved", ["from", "to"], unRows, " hidden");
     if (unTable) chunks.push(unTable);
 
+    // #api-calls — frontend functions in this doc that hit a backend endpoint.
+    // `to` points cross-tree to the handler's doc#id (the two trees, joined);
+    // `endpoint` is the METHOD + normalized path; `confidence` carries a
+    // `method-mismatch` marker when the verb disagrees (contract drift).
+    const apiOutRows = [];
+    for (const s of c.methods) {
+      for (const e of (httpOut.get(s.anchor) ?? []).slice().sort((x, y) => x.endpoint.localeCompare(y.endpoint) || String(x.to ?? x.to_text).localeCompare(String(y.to ?? y.to_text)))) {
+        const target = e.to !== undefined && docOfAnchor.has(e.to) ? refTo(e.to, doc) : csvCell(e.to_text ?? "?");
+        const conf = e.methodDivergent ? `${e.confidence} method-mismatch` : e.confidence;
+        apiOutRows.push([`#${idOf.get(s.anchor)}`, target, csvCell(e.endpoint), conf]);
+      }
+    }
+    const apiCallsTable = csv("api-calls", ["from", "to", "endpoint", "confidence"], apiOutRows);
+    if (apiCallsTable) chunks.push(apiCallsTable);
+
+    // #api-served-by — backend handlers in this doc reached from the frontend.
+    const apiInRows = [];
+    for (const s of c.methods) {
+      for (const e of (httpIn.get(s.anchor) ?? []).slice().sort((x, y) => x.endpoint.localeCompare(y.endpoint) || (x.site?.file ?? "").localeCompare(y.site?.file ?? "") || (x.site?.line ?? 0) - (y.site?.line ?? 0))) {
+        const from = e.from !== undefined && docOfAnchor.has(e.from) ? refTo(e.from, doc) : csvCell(e.from_text ?? "?");
+        const site = e.site ? `${e.site.file}:${e.site.line}` : "";
+        apiInRows.push([from, `#${idOf.get(s.anchor)}`, csvCell(e.endpoint), csvCell(site)]);
+      }
+    }
+    const apiInTable = csv("api-served-by", ["from", "to", "endpoint", "site"], apiInRows);
+    if (apiInTable) chunks.push(apiInTable);
+
     writeIfChanged(doc, chunks.join("\n"));
     indexRows.push({ module: dispLabel, doc, methods: c.methods.length, entries: entries.length, tests: testCount });
   }

package/codemap/normalize.mjs

@@ -102,7 +102,10 @@ export function declaredModuleRoots(root, { readFile = readFileSync } = {}) {
   // is a relative directory path.
   const pom = read("pom.xml");
   if (pom) {
-    for (const m of pom.matchAll(/<module>\s*([^<]+?)\s*<\/module>/g)) {
+    // `[^<]*` (linear) + trim, NOT `\s*([^<]+?)\s*` — the latter's ambiguous
+    // whitespace partition backtracks super-linearly on a crafted root pom.xml
+    // (`<module>` + a long whitespace run and no close), hanging every build.
+    for (const m of pom.matchAll(/<module>([^<]*)<\/module>/g)) {
       const dir = m[1].trim().replace(/\\/g, "/").replace(/\/+$/, "");
       if (dir) roots.add(dir);
     }

package/codemap/verify.mjs

@@ -80,6 +80,10 @@ for (const f of files) {
 
 // ---- pass 2: codemap profile references ----
 const REF_TABLES = new Set(["calls", "called-by", "ref-by"]);
+// Cross-stack link tables: `from`/`to` may be a #ref (resolved cross-tree
+// link — checked) OR plain `file:line` text (a call/route outside any indexed
+// function — tolerated, nothing to resolve).
+const LINK_TABLES = new Set(["api-calls", "api-served-by"]);
 const relDoc = (f) => relative(rootDir, f).replace(/\\/g, "/");
 const docs = new Map(); // relPath -> { ids:Set, blocks }
 const collectIds = (blocks, ids) => {
@@ -101,11 +105,11 @@ const err = (doc, where, msg) => {
   refErrors++;
   console.error(`REF  ${doc} ${where}: ${msg}`);
 };
-const checkRef = (fromDoc, where, ref) => {
+const checkRef = (fromDoc, where, ref, lenient = false) => {
   ref = String(ref).trim();
-  if (!ref) return err(fromDoc, where, "empty reference cell");
+  if (!ref) return lenient ? undefined : err(fromDoc, where, "empty reference cell");
   const h = ref.indexOf("#");
-  if (h < 0) return err(fromDoc, where, `not a reference: \`${ref}\``);
+  if (h < 0) return lenient ? undefined : err(fromDoc, where, `not a reference: \`${ref}\``);
   let targetDoc = fromDoc;
   if (h > 0) targetDoc = posix.normalize(posix.join(posix.dirname(fromDoc), ref.slice(0, h)));
   const id = ref.slice(h + 1);
@@ -119,13 +123,14 @@ const checkRef = (fromDoc, where, ref) => {
 for (const [docPath, { blocks }] of docs) {
   for (const b of blocks) {
     if (b.kind !== "block") continue;
-    if (b.type === "table" && REF_TABLES.has(b.id) && b.table) {
+    if (b.type === "table" && (REF_TABLES.has(b.id) || LINK_TABLES.has(b.id)) && b.table) {
+      const lenient = LINK_TABLES.has(b.id);
       const fromCol = b.table.columns.indexOf("from");
       const toCol = b.table.columns.indexOf("to");
       if (fromCol < 0 || toCol < 0) { err(docPath, `#${b.id}`, "missing from/to columns"); continue; }
       b.table.rows.forEach((row, i) => {
-        checkRef(docPath, `#${b.id} row ${i + 1} from`, row[fromCol]?.text ?? "");
-        checkRef(docPath, `#${b.id} row ${i + 1} to`, row[toCol]?.text ?? "");
+        checkRef(docPath, `#${b.id} row ${i + 1} from`, row[fromCol]?.text ?? "", lenient);
+        checkRef(docPath, `#${b.id} row ${i + 1} to`, row[toCol]?.text ?? "", lenient);
       });
     }
     if (b.type === "meta" && b.data?.entry) {

package/dist/block-edit.d.ts

@@ -0,0 +1 @@
+export declare function normalizeBlockId(blockSrc: string, newId: string): string;