@nanonets/graft 0.6.0 → 0.7.0

package/dist/graph/workspace.js

@@ -1,339 +1,395 @@
 /**
- * Workspace federation — a parent directory with >=2 immediate git children
- * and no own `.git` is a WORKSPACE, not a repo. Building there builds each
- * child's graph INTO THE CHILD (`<child>/graft/`, committable in that repo,
- * byte-identical to a standalone build — the parent never influences a child
- * build) and leaves the parent holding ONLY `graft/workspace.json`: a manifest
- * of child dir names, no nodes or edges.
+ * Workspace federation — a "workspace" is a parent directory that holds two or
+ * more immediate git-repo children and has no source graph of its own. Instead
+ * of one mega-graph pooling every repo, each child keeps its OWN committable
+ * `graft/` (byte-identical to building that child standalone), and the parent
+ * holds a single `graft/workspace.json` index:
  *
- * Queries at the parent federate across the children's graphs:
- *   - `ask` merges the child graphs into one virtual corpus whose ranking
- *     scopes are `<child>/<scope>` (child root scope → `<child>`), so the
- *     existing per-scope RRF pipeline (`rankScopesAndFuse`) does the fair
- *     cross-repo fusion — a big repo can't drown a small one, and every hit
- *     is labeled with the repo it came from.
- *   - `grep` / `callers` / `callees` / `impact` run over the same merged
- *     graph: node ids and paths are prefixed `<child>/`, edges never cross
- *     children, so in-degree/coupling stays each child's own.
- *   - `map` and `check` run per child (see {@link buildWorkspaceMap} /
- *     {@link checkWorkspace}).
+ *   { "version": 1, "children": ["repoA", "repoB"] }
  *
- * Migration: a parent that HAS an old combined ("mega") graph gets it replaced
- * by the workspace manifest on the next `graft build` there — loudly, via
- * {@link migrationNote} — and never any other way: a stale mega-graph parent
- * keeps answering `check`/queries as before until the user rebuilds.
+ * Queries run at the parent federate across the children: `ask` fuses every
+ * child's ranked hits with the same RRF `fuseScopes` used inside a single
+ * multi-scope repo (so the big repo can't drown the small one), `grep`/`map`/
+ * `check`/`callers` run per child and merge, always labeled `<child>/`.
  *
- * Unbuilt children are surfaced, never silently skipped: every loader here
- * carries a "N of M workspace repos have graphs; run graft build to cover X"
- * note that each command attaches to its output.
+ * This module owns the pure/core pieces (the format, its readers/writers, graph
+ * loading, and the federated command bodies that return renderable data). The
+ * CLI print/exit wrappers and the per-child build orchestration live in
+ * `workspace-cli.ts`; `mcp/tools.ts` calls the federate* functions directly.
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { contextDirFor, CACHE_DIR } from "../context/node-file.js";
-import { counts, tokenize } from "../ask/index-file.js";
-import { buildGraph } from "./build.js";
+import { join } from "node:path";
+import { contextDirFor } from "../context/node-file.js";
 import { checkGraph } from "./check.js";
-import { loadGraphCached, loadAskIndexCached } from "./load.js";
+import { loadGraphCached } from "./load.js";
 import { buildRepoMap, formatRepoMap } from "./map.js";
-import { discoverWorkspaceChildren, scopesOfGraph } from "./scopes.js";
-import { GRAPH_DIR, wiringPath } from "./write.js";
-export const WORKSPACE_FILE = "workspace.json";
-/** `<contextDir>/workspace.json` — sibling of where `.graph/` would live. */
-export function workspacePath(outDir) {
-    return join(outDir, WORKSPACE_FILE);
+import { discoverWorkspaceChildren } from "./scopes.js";
+import { callersSavings, headerOf, hitLine, looseNoteFor, } from "./traverse-cli.js";
+import { edgeWalk, resolveSymbol } from "./traverse.js";
+import { wiringPath } from "./write.js";
+import { ask } from "../ask/ask.js";
+import { fuseScopes, STRONG_FLOOR, HIGH_FLOOR } from "../ask/fuse.js";
+import { grepGraph } from "../search/grep.js";
+import { formatGrepResult, zeroHitNote } from "../search/grep-cli.js";
+import { savingsFooter } from "../context/savings.js";
+const WORKSPACE_FILE = "workspace.json";
+/** Absolute path to the workspace index for a parent root (`<dir>/graft/workspace.json`). */
+export function workspacePath(root, override) {
+    return join(contextDirFor(root, override), WORKSPACE_FILE);
 }
-/** Read the workspace manifest for the repo/parent at `root` (respecting the
- * `--dir` override like every other reader). Null when absent or malformed —
- * a non-workspace root costs one `existsSync`. */
-export function readWorkspace(root, contextDirOverride) {
-    const path = workspacePath(contextDirFor(resolve(root), contextDirOverride));
-    if (!existsSync(path))
-        return null;
+/** Read the workspace index, or null when the parent has none (not a workspace,
+ * or unparseable/foreign json — treated the same as absent). */
+export function readWorkspace(root, override) {
+    const path = workspacePath(root, override);
     try {
-        const raw = JSON.parse(readFileSync(path, "utf8"));
-        if (!raw ||
-            typeof raw !== "object" ||
-            raw.version !== 1 ||
-            !Array.isArray(raw.children) ||
-            !raw.children.every((c) => typeof c === "string" && c.length > 0)) {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.version !== 1 || !Array.isArray(parsed.children))
             return null;
-        }
-        return { version: 1, children: raw.children };
+        return { version: 1, children: parsed.children.map(String) };
     }
     catch {
         return null;
     }
 }
-/** Write the manifest (children sorted; deterministic bytes, like writeGraph). */
-export function writeWorkspace(outDir, ws) {
-    const path = workspacePath(outDir);
-    mkdirSync(outDir, { recursive: true });
+/** Write the workspace index, sorting children for a stable, minimal git diff. */
+export function writeWorkspace(root, ws, override) {
+    const dir = contextDirFor(root, override);
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, WORKSPACE_FILE);
     const sorted = { version: 1, children: [...ws.children].sort() };
     writeFileSync(path, JSON.stringify(sorted, null, 2) + "\n");
     return path;
 }
-/** Build-time workspace detection: `root` has NO `.git` of its own and >=2
- * immediate git children (a `.git` FILE — worktree/submodule — counts).
- * Returns the sorted child names, or null when `root` is a normal repo/dir. */
-export function isWorkspaceRoot(root) {
-    const absRoot = resolve(root);
-    if (existsSync(join(absRoot, ".git")))
-        return null;
-    const children = discoverWorkspaceChildren(absRoot).sort();
-    return children.length >= 2 ? children : null;
+/** A parent is a workspace BUILD target when it has no own `.git` and ≥2 git
+ * children — or it was already split (a `workspace.json` is present). The
+ * no-own-`.git` guard keeps a normal repo with git submodules from being
+ * mistaken for a workspace. */
+export function isWorkspaceBuildRoot(root, override) {
+    if (readWorkspace(root, override))
+        return true;
+    if (existsSync(join(root, ".git")))
+        return false;
+    return discoverWorkspaceChildren(root).length >= 2;
 }
-/** Load every child's graph via `loadGraphCached` (the only graph loader).
- * Null when `root` is not a workspace (no manifest). */
-export function loadWorkspaceGraphs(root, contextDirOverride) {
-    const ws = readWorkspace(root, contextDirOverride);
-    if (!ws)
-        return null;
-    const absRoot = resolve(root);
-    const built = [];
-    const unbuilt = [];
-    for (const child of ws.children) {
-        // children always use their own default graft/ — that's what makes each
-        // child's graph committable in (and byte-identical to) the child repo.
-        const contextDir = contextDirFor(join(absRoot, child));
-        const graph = loadGraphCached(contextDir);
+/** True when the parent has a mega-graph from an older single-graph build
+ * (`graft/.graph/wiring.json`) — the thing a workspace build migrates away. */
+export function hasMegaGraph(root, override) {
+    return existsSync(wiringPath(contextDirFor(root, override)));
+}
+/** The EXACT split warning printed once, when a mega-graph parent is first
+ * built as a workspace. Templated on the child list so it names the real repos. */
+export function migrationNote(children) {
+    const dirs = children.map((c) => `${c}/graft/`).join(", ");
+    return (`⚠ this folder contains ${children.length} separate git repos — splitting: ` +
+        `each repo now gets its own committable graft/ (${dirs}); the combined graph ` +
+        `here is replaced by a workspace index. Queries from here now search all repos, fairly.`);
+}
+/** Remove the parent's entire `graft/` tree — the mega-graph, its `.cache`, and
+ * any stale cards — so after `writeWorkspace` the parent holds ONLY
+ * workspace.json. Child graphs live in sibling `<child>/graft/`, never under
+ * this dir, so they are untouched. */
+export function clearParentGraft(root, override) {
+    rmSync(contextDirFor(root, override), { recursive: true, force: true });
+}
+/** Load each child's graph via `loadGraphCached`. Children come from
+ * workspace.json when present, otherwise from live git-child discovery (a
+ * not-yet-built workspace). A child without a built graph is counted into
+ * `missing`, not dropped. */
+export function loadWorkspaceGraphs(root, override) {
+    const ws = readWorkspace(root, override);
+    const children = (ws ? ws.children : discoverWorkspaceChildren(root)).slice().sort();
+    const loaded = [];
+    const missing = [];
+    for (const child of children) {
+        const graph = loadGraphCached(contextDirFor(join(root, child)));
         if (graph)
-            built.push({ child, contextDir, graph, askIndex: loadAskIndexCached(contextDir) });
+            loaded.push({ child, graph });
         else
-            unbuilt.push(child);
+            missing.push(child);
     }
-    const note = unbuilt.length
-        ? `${built.length} of ${ws.children.length} workspace repos have graphs; run graft build to cover ${unbuilt.join(", ")}`
-        : undefined;
-    return { children: ws.children, built, unbuilt, note };
+    return { loaded, missing };
 }
-// ── Merging: one virtual graph, everything prefixed `<child>/` ───────────────
-/** Prefix a child's nodes/edges with `<child>/` so ids and paths are unique
- * and workspace-relative (pointers open from the parent cwd). Edge endpoints
- * that aren't node ids (unresolved import module strings) stay untouched. */
-function prefixChild(child, g) {
-    const ids = new Set(g.nodes.map((n) => n.id));
-    const pre = (id) => (ids.has(id) ? `${child}/${id}` : id);
-    return {
-        nodes: g.nodes.map((n) => ({ ...n, id: `${child}/${n.id}`, path: `${child}/${n.path}` })),
-        edges: g.edges.map((e) => ({ ...e, source: pre(e.source), target: pre(e.target) })),
-    };
+/** "2 of 3 workspace repos have graphs; run graft build to cover repoC" — the
+ * coverage line federated commands append when some listed child is unbuilt.
+ * Empty string when every child has a graph. */
+export function coverageNote(g) {
+    if (g.missing.length === 0)
+        return "";
+    const total = g.loaded.length + g.missing.length;
+    return `${g.loaded.length} of ${total} workspace repos have graphs; run graft build to cover ${g.missing.join(", ")}`;
 }
-/** Merge the built children into one virtual graph whose scopes are each
- * child's scopes prefixed `<child>/` (child root scope → `<child>`). With >=2
- * built children this is always multi-scope, so `ask` takes its per-scope
- * RRF path and labels every hit with its repo. Null when nothing is built. */
-export function mergeWorkspaceGraphs(built) {
-    if (built.length === 0)
-        return null;
-    const nodes = [];
-    const edges = [];
-    const langs = new Set();
-    const scopes = [];
-    for (const { child, graph } of built) {
-        const p = prefixChild(child, graph);
-        nodes.push(...p.nodes);
-        edges.push(...p.edges);
-        for (const l of graph.meta.languages)
-            langs.add(l);
-        for (const s of scopesOfGraph(graph)) {
-            const prefix = s.prefix ? `${child}/${s.prefix}` : child;
-            scopes.push({ prefix, label: prefix, markers: s.markers });
+/** Prefix a hit pointer with its child dir so a `path:span` (or concept path
+ * list) opens correctly from the parent. Leaves free-text fragments alone. */
+function prefixPointer(child, pointer) {
+    return pointer
+        .split(",")
+        .map((part) => {
+        const t = part.trim();
+        if (!t || t.includes(" "))
+            return part;
+        return `${child}/${t}`;
+    })
+        .join(", ");
+}
+// STRONG_FLOOR / HIGH_FLOOR (a child federates if its top hit matched a
+// query term in a NAME/PATH field ≥ STRONG_FLOOR, OR its overall name+path+
+// body coverage is broad enough to be real even body-only, ≥ HIGH_FLOOR) are
+// defined ONCE in `../ask/fuse.js` and imported here — `rankScopesAndFuse`
+// (single-graph multi-scope, `src/ask/fuse.ts`) gates on the exact same two
+// floors, so the two paths that solve the identical "a weak scope must not
+// federate beside a strong one" problem can never drift apart again.
+/**
+ * Federated `ask` across a workspace: run each child's own per-scope ask
+ * pipeline, then fuse ALL the children's scope lists with the same
+ * `fuseScopes` used inside a single multi-scope repo. Each child contributes
+ * one fusion scope per intra-child scope, labeled `<child>/<scope>` (or just
+ * `<child>` for a child's root scope), so a big repo can't drown a small one —
+ * rank positions are comparable across repos where raw scores are not.
+ *
+ * Returns a normal `AskResult`; `formatAsk` renders it unchanged, labeling each
+ * hit `[<child>/…]` via the standard multi-scope path.
+ */
+export function federateAsk(root, override, query, opts = {}) {
+    const wg = loadWorkspaceGraphs(root, override);
+    const limit = opts.limit ?? 8;
+    // `--in` scopes to a single child (and, past the first segment, a sub-scope
+    // within it). A prefix naming no known child at all is a caller mistake.
+    let onlyChild;
+    let childIn;
+    if (opts.in) {
+        const prefix = opts.in.replace(/\/+$/, "");
+        const [name, ...rest] = prefix.split("/");
+        const allChildren = [...wg.loaded.map((l) => l.child), ...wg.missing].sort();
+        if (!allChildren.includes(name)) {
+            throw new Error(`no workspace repo "${name}" - repos: ${allChildren.join(", ")}`);
         }
+        onlyChild = name;
+        childIn = rest.length ? rest.join("/") : undefined;
     }
-    // rule-7 ordering (prefix-length desc, then lexicographic) — scopeOf depends on it.
-    scopes.sort((a, b) => b.prefix.length - a.prefix.length || a.prefix.localeCompare(b.prefix));
-    return {
-        meta: {
-            version: 1,
-            nodeCount: nodes.length,
-            edgeCount: edges.length,
-            languages: [...langs].sort(),
-            scopes,
-        },
-        nodes,
-        edges,
-    };
-}
-function addBag(into, pairs) {
-    for (const [t, c] of pairs)
-        into.set(t, (into.get(t) ?? 0) + c);
-}
-/** Merge the children's build-time ask sidecars to match the merged graph:
- * doc ids prefixed, and each doc's path bag gains the child dir's tokens —
- * exactly what live tokenization of the prefixed path would produce, so the
- * sidecar stays a provably exact cache. `df`/`docCount`/`avgBodyLen` are
- * recomputed over the merged docs. Null (→ live-tokenization fallback, same
- * degradation as any stale sidecar) unless EVERY built child has a sidecar
- * that exactly covers its graph. */
-export function mergeWorkspaceAskIndexes(built) {
-    if (built.length === 0)
-        return null;
-    for (const { graph, askIndex } of built) {
-        if (!askIndex || askIndex.docs.length !== graph.nodes.length)
-            return null;
-        const byId = new Set(askIndex.docs.map((d) => d.id));
-        if (!graph.nodes.every((n) => byId.has(n.id)))
-            return null;
+    // Pass 1: run each child's ask; keep its hits + RAW top-hit coverage.
+    const runs = [];
+    for (const { child } of wg.loaded) {
+        if (onlyChild && child !== onlyChild)
+            continue;
+        let r;
+        try {
+            // Over-fetch per child so cross-child fusion has enough candidates to
+            // rank before the final `limit` slice.
+            r = ask(join(root, child), query, {
+                limit: Math.max(limit * 4, 20),
+                source: opts.source,
+                full: opts.full,
+                graphRank: opts.graphRank,
+                in: childIn,
+            });
+        }
+        catch {
+            continue; // corrupt child, or a sub-scope --in matching nothing here
+        }
+        if (r.hits.length === 0)
+            continue;
+        runs.push({ child, hits: r.hits, coverage: r.coverage ?? 0, coverageStrong: r.coverageStrong ?? 0 });
+    }
+    // Cross-child participation gate on match STRENGTH, not a lenient ratio.
+    // Per-child hit scores are each per-child-normalized (top ~1.0 everywhere),
+    // so feeding them to fuseScopes makes its gate vacuous across repos — a junk
+    // body-token collision would federate beside another repo's genuine hits.
+    // Gate: a child federates iff its top hit matched a query term in a NAME/PATH
+    // field (coverageStrong ≥ STRONG_FLOOR — not just an incidental body token)
+    // OR its overall coverage is broad enough to be real (≥ HIGH_FLOOR). A
+    // body-only collision has coverageStrong 0 and coverage ~0.3 → gated to
+    // alsoMatched. Both floors are absolute + scale-invariant (see their docs).
+    // The gate is a cross-child FAIRNESS mechanism: it stops a weak body-token
+    // collision in one repo from federating beside another repo's genuine hits.
+    // An explicit `--in <child>` removes all cross-child competition — the caller
+    // has already chosen the scope — so the gate must NOT apply there, or the
+    // `also matched: <child> — narrow with --in <child>` hint would lead to an
+    // empty result for exactly the weak child it points at. With `onlyChild` set,
+    // every run (there is at most one) survives, matching a standalone child ask.
+    const gatedOut = [];
+    const survivors = [];
+    for (const run of runs) {
+        if (onlyChild || run.coverageStrong >= STRONG_FLOOR || run.coverage >= HIGH_FLOOR)
+            survivors.push(run);
+        else
+            gatedOut.push({ scope: run.child, bestId: prefixPointer(run.child, run.hits[0].pointer) });
     }
+    // Fuse the survivors' scope lists (within-child fusion is left untouched —
+    // each child already ran its own per-scope RRF).
     const docs = [];
-    const df = new Map();
-    let bodyLenSum = 0;
-    for (const { child, askIndex } of built) {
-        const childTokens = [...counts(tokenize(child)).entries()];
-        for (const d of askIndex.docs) {
-            const path = new Map();
-            addBag(path, childTokens);
-            addBag(path, d.path);
-            const doc = { id: `${child}/${d.id}`, name: d.name, path: [...path.entries()], body: d.body };
-            docs.push(doc);
-            const bag = new Set([...doc.name, ...doc.path, ...doc.body].map(([t]) => t));
-            for (const t of bag)
-                df.set(t, (df.get(t) ?? 0) + 1);
-            for (const [, c] of d.body)
-                bodyLenSum += c;
-        }
+    const back = new Map();
+    for (const { child, hits } of survivors) {
+        hits.forEach((hit, i) => {
+            const scope = hit.scope ? `${child}/${hit.scope}` : child;
+            const id = `${child} ${i}`;
+            docs.push({ id, scope, score: hit.score });
+            back.set(id, { child, hit });
+        });
     }
-    return {
-        version: 1,
-        avgBodyLen: docs.length ? bodyLenSum / docs.length : 0,
-        df: [...df.entries()],
-        docCount: docs.length,
-        docs,
-    };
-}
-/** One-call federation for graph-consuming commands (grep, callers/callees,
- * impact, MCP): null when `root` is not a workspace; otherwise the merged
- * graph (null when no child is built) plus the unbuilt-children note. */
-export function loadFederatedGraph(root, contextDirOverride) {
-    const wg = loadWorkspaceGraphs(root, contextDirOverride);
-    if (!wg)
-        return null;
-    return { graph: mergeWorkspaceGraphs(wg.built), note: wg.note };
-}
-/** Federation inputs for `ask`: the merged graph + merged sidecar + each built
- * child's context dir (for its concept nodes). `ask` feeds the merged graph to
- * its existing multi-scope pipeline, so `rankScopesAndFuse` does the fair
- * cross-repo fusion with `<child>/`-prefixed scope labels. */
-export function federateAsk(root, contextDirOverride) {
-    const wg = loadWorkspaceGraphs(root, contextDirOverride);
-    if (!wg)
-        return null;
-    return {
-        graph: mergeWorkspaceGraphs(wg.built),
-        askIndex: mergeWorkspaceAskIndexes(wg.built),
-        built: wg.built.map(({ child, contextDir }) => ({ child, contextDir })),
-        note: wg.note,
-    };
-}
-// ── Build + migration ────────────────────────────────────────────────────────
-/** EXACT migration wording (asserted by tests) for a parent whose old combined
- * graph is being replaced by the workspace manifest. */
-export function migrationNote(children) {
-    return (`⚠ this folder contains ${children.length} separate git repos — splitting: each repo now gets ` +
-        `its own committable graft/ (${children.map((c) => `${c}/graft/`).join(", ")}); the combined ` +
-        `graph here is replaced by a workspace index. Queries from here now search all repos, fairly.`);
-}
-/**
- * `graft build` at a workspace parent: build each child's graph into the child
- * (plain `buildGraph(childDir)` — nothing parent-side touches it, which is what
- * makes the result byte-identical to a standalone build), then write the
- * parent manifest. A pre-existing mega-graph (`graft/.graph/wiring.json` at
- * the parent) is replaced: its `.graph/` and `.cache/` are deleted AFTER the
- * children built successfully, so a failed child build never destroys the old
- * (still-working) graph.
- */
-export async function buildWorkspace(root, opts = {}) {
-    const absRoot = resolve(root);
-    const children = discoverWorkspaceChildren(absRoot).sort();
-    const outDir = contextDirFor(absRoot, opts.contextDir);
-    const hadMegaGraph = existsSync(wiringPath(outDir));
-    const results = [];
-    for (const child of children) {
-        results.push({ child, result: await buildGraph(join(absRoot, child)) });
+    const fused = fuseScopes(docs);
+    const hits = fused.ranked.slice(0, limit).map((rd) => {
+        const { child, hit } = back.get(rd.id);
+        return { ...hit, score: rd.score, scope: rd.scope, pointer: prefixPointer(child, hit.pointer) };
+    });
+    const alsoMatched = [...fused.alsoMatched, ...gatedOut];
+    const note = coverageNote(wg);
+    const result = { query, mode: hits.length ? "lexical" : "empty", hits };
+    if (hits.length) {
+        const federated = fused.federated.length ? fused.federated : [...new Set(hits.map((h) => h.scope))];
+        result.scopes = { federated, alsoMatched };
     }
-    if (hadMegaGraph) {
-        rmSync(join(outDir, GRAPH_DIR), { recursive: true, force: true });
-        rmSync(join(outDir, CACHE_DIR), { recursive: true, force: true });
+    else {
+        result.note = `no matching nodes across ${wg.loaded.length} workspace repo(s) — try different words, or \`graft build\` at a child`;
     }
-    const path = writeWorkspace(outDir, { version: 1, children });
-    return {
-        children: results,
-        workspacePath: path,
-        migrated: hadMegaGraph,
-        migrationNote: hadMegaGraph ? migrationNote(children) : undefined,
-    };
+    if (note)
+        result.note = result.note ? `${result.note}\n${note}` : note;
+    return result;
 }
-/** Human report for a workspace build — the migration note (when migrating)
- * first, then one ✓ line per child, then where the manifest went. */
-export function formatWorkspaceBuild(r) {
-    const lines = [];
-    if (r.migrationNote)
-        lines.push(r.migrationNote);
-    for (const { child, result } of r.children) {
-        lines.push(`✓ ${child}/: ${result.nodes} nodes, ${result.edges} edges, ${result.cards} cards [${result.languages.join(", ")}]`);
-        for (const e of result.errors)
-            lines.push(`✗ ${child}/: ${e}`);
+/** Merge every child's `GrepResult` into one, prefixing group paths with the
+ * child dir and re-sorting by coupling (inDegree desc, path asc) across repos.
+ * In-degree stays each child's own — it comes from that child's graph. */
+export function federateGrep(root, override, pattern, opts = {}) {
+    const wg = loadWorkspaceGraphs(root, override);
+    const groups = [];
+    let filesSearched = 0;
+    let totalHits = 0;
+    const truncated = { files: 0, hits: 0 };
+    let savedFiles = 0;
+    let savedChars = 0;
+    for (const { child, graph } of wg.loaded) {
+        const r = grepGraph(graph, join(root, child), pattern, {
+            ignoreCase: opts.ignoreCase,
+            fixed: opts.fixed,
+        });
+        filesSearched += r.filesSearched;
+        totalHits += r.totalHits;
+        truncated.files += r.truncated.files;
+        truncated.hits += r.truncated.hits;
+        if (r.saved) {
+            savedFiles += r.saved.files;
+            savedChars += r.saved.baselineChars;
+        }
+        for (const g of r.groups) {
+            groups.push({
+                ...g,
+                path: `${child}/${g.path}`,
+                symbol: g.symbol ? { ...g.symbol, path: `${child}/${g.symbol.path}` } : null,
+            });
+        }
     }
-    lines.push(`  → ${r.workspacePath}`);
-    lines.push(`  queries here now federate across: ${r.children.map((c) => `${c.child}/`).join(", ")}`);
-    return lines.join("\n");
+    groups.sort((a, b) => b.inDegree - a.inDegree || a.path.localeCompare(b.path));
+    const saved = savedChars > 0 ? { files: savedFiles, baselineChars: savedChars } : undefined;
+    const result = { pattern, filesSearched, totalHits, groups, truncated, saved };
+    return { result, coverage: coverageNote(wg) };
 }
-/** Per-child drift check ({@link checkGraph} in each child repo). */
-export function checkWorkspace(root, contextDirOverride) {
-    const ws = readWorkspace(root, contextDirOverride);
-    const children = ws?.children ?? [];
-    const absRoot = resolve(root);
-    const rows = children.map((child) => {
-        const result = checkGraph(join(absRoot, child));
-        if (result.missing) {
-            return { child, missing: true, ok: false, summary: "no graph — run `graft build` to cover it", result };
-        }
-        if (result.ok)
-            return { child, missing: false, ok: true, summary: "OK — wiring graph in sync", result };
-        const parts = [];
-        if (result.changed.length)
-            parts.push(`${result.changed.length} changed`);
-        if (result.added.length)
-            parts.push(`${result.added.length} added`);
-        if (result.removed.length)
-            parts.push(`${result.removed.length} removed`);
-        if (result.stale.length)
-            parts.push(`${result.stale.length} stale summaries`);
-        return { child, missing: false, ok: false, summary: `STALE — ${parts.join(", ")} (run \`graft build\` in ${child}/)`, result };
+/** One `graft map` section per child (each child's own map, budget split evenly
+ * across the loaded children), joined under `<child>/` headers. */
+export function federateMap(root, override, opts = {}) {
+    const wg = loadWorkspaceGraphs(root, override);
+    const perChild = opts.maxDirs !== undefined && wg.loaded.length > 0
+        ? Math.max(1, Math.floor(opts.maxDirs / wg.loaded.length))
+        : undefined;
+    const sections = wg.loaded.map(({ child, graph }) => {
+        const map = buildRepoMap(graph, perChild !== undefined ? { maxDirs: perChild } : {});
+        return `## ${child}/\n${formatRepoMap(map).trimEnd()}`;
     });
-    return { children: rows, failed: rows.some((r) => !r.missing && !r.ok) };
-}
-export function formatWorkspaceCheck(c) {
-    const lines = [`workspace check — ${c.children.length} repos`, ""];
-    for (const row of c.children)
-        lines.push(`${row.child}/: ${row.summary}`);
-    lines.push("");
-    lines.push(c.failed
-        ? "workspace check: STALE — rebuild the repos above and commit their graft/."
-        : "workspace check: OK");
-    return lines.join("\n");
+    const head = `workspace map — ${wg.loaded.length} repo(s)`;
+    const parts = [head, "", sections.join("\n\n")];
+    const cov = coverageNote(wg);
+    if (cov)
+        parts.push("", cov);
+    return parts.join("\n") + "\n";
 }
-/** Per-child repo maps, the directory budget split evenly across the built
- * children. Null when `root` is not a workspace. */
-export function buildWorkspaceMap(root, opts = {}) {
-    const wg = loadWorkspaceGraphs(root, opts.contextDir);
-    if (!wg)
-        return null;
-    const per = Math.max(1, Math.floor((opts.maxDirs ?? 16) / Math.max(1, wg.built.length)));
-    return {
-        children: wg.built.map(({ child, graph }) => ({ child, map: buildRepoMap(graph, { maxDirs: per }) })),
-        note: wg.note,
-    };
+/** Per-child drift status. `ok` is false when any BUILT child is stale — an
+ * unbuilt child is surfaced (coverage), never a failure. */
+export function federateCheck(root, override) {
+    const wg = loadWorkspaceGraphs(root, override);
+    const lines = [`workspace check — ${wg.loaded.length + wg.missing.length} repo(s)`, ""];
+    let ok = true;
+    for (const { child } of wg.loaded) {
+        const g = checkGraph(join(root, child));
+        if (g.ok) {
+            lines.push(`${child}/: OK`);
+        }
+        else {
+            ok = false;
+            const bits = [];
+            if (g.added.length)
+                bits.push(`${g.added.length} added`);
+            if (g.removed.length)
+                bits.push(`${g.removed.length} removed`);
+            if (g.changed.length)
+                bits.push(`${g.changed.length} changed`);
+            if (g.stale.length)
+                bits.push(`${g.stale.length} stale`);
+            lines.push(`${child}/: STALE (${bits.join(", ")})`);
+        }
+    }
+    for (const child of wg.missing)
+        lines.push(`${child}/: not built (run graft build)`);
+    const cov = coverageNote(wg);
+    if (cov)
+        lines.push("", cov);
+    return { text: lines.join("\n") + "\n", ok };
 }
-/** One section per child (its own `formatRepoMap` report under a `<child>/`
- * heading), plus the unbuilt-children note when present. */
-export function formatWorkspaceMap(m) {
-    const lines = [`workspace map — ${m.children.length} repo${m.children.length === 1 ? "" : "s"}`];
-    for (const { child, map } of m.children) {
-        lines.push("", `── ${child}/ ──`, formatRepoMap(map).trimEnd());
+/** Resolve a symbol across every child, grouped per child. Reuses the shared
+ * traverse-cli formatters so each block reads exactly like `graft callers`. */
+export function federateCallers(root, override, symbol, opts = {}) {
+    const wg = loadWorkspaceGraphs(root, override);
+    const direction = opts.direction ?? "in";
+    const depth = opts.depth && opts.depth >= 1 ? Math.floor(opts.depth) : 1;
+    const showDepth = depth > 1;
+    const blocks = [];
+    let found = false;
+    for (const { child, graph } of wg.loaded) {
+        const matches = resolveSymbol(graph, symbol, opts.in ? { in: opts.in } : {});
+        if (matches.length === 0)
+            continue;
+        found = true;
+        const results = matches.map((m) => ({ symbol: m, hits: edgeWalk(graph, m, direction, depth) }));
+        const lines = [`## ${child}/`];
+        for (const { symbol: sym, hits } of results) {
+            lines.push(headerOf(sym));
+            if (hits.length === 0)
+                lines.push(looseNoteFor(direction, sym.name));
+            else
+                for (const h of hits)
+                    lines.push(hitLine(direction, h, showDepth));
+        }
+        const body = lines.join("\n");
+        blocks.push(body + savingsFooter(body, callersSavings(graph, results)));
+    }
+    const cov = coverageNote(wg);
+    if (!found) {
+        const base = `no symbol "${symbol}" in any of the ${wg.loaded.length} workspace repo(s) — check spelling or run graft build`;
+        return { text: cov ? `${base}\n${cov}` : base, found: false };
     }
-    if (m.note)
-        lines.push("", m.note);
-    return lines.join("\n") + "\n";
+    let text = blocks.join("\n\n");
+    if (cov)
+        text += `\n\n${cov}`;
+    return { text, found: true };
+}
+/**
+ * Split a parent into a workspace: build each git child (via the supplied
+ * `buildChild` callback, so this stays free of any engine/LLM dependency),
+ * then REPLACE the parent's `graft/` with just `workspace.json`. `onStart`
+ * fires once — before any child is built — carrying whether this build is a
+ * mega-graph migration, so the caller can print the one-time split warning
+ * first, exactly as the spec requires.
+ *
+ * The child build writes into `<child>/graft/` and is byte-identical to
+ * building that child standalone (`buildChild` is just `buildGraph(childDir)`),
+ * because nothing about the parent path enters the child's build.
+ */
+export async function splitWorkspace(root, override, buildChild, onStart) {
+    const children = discoverWorkspaceChildren(root).slice().sort();
+    const migrated = hasMegaGraph(root, override);
+    onStart?.({ children, migrated });
+    for (const child of children)
+        await buildChild(join(root, child), child);
+    clearParentGraft(root, override); // drop the mega-graph/.cache/cards…
+    writeWorkspace(root, { version: 1, children }, override); // …leaving ONLY workspace.json
+    return { children, migrated };
 }
+export { formatGrepResult, zeroHitNote };
 //# sourceMappingURL=workspace.js.map