Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

29.1 KB
Raw Blame
/**
 * 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:
 *
 *   { "version": 1, "children": ["repoA", "repoB"] }
 *
 * Queries run at the parent federate across the children: `ask` fuses every
 * child's ranked hits with `fuseScopes`, reciprocal-rank fusion, so the big
 * repo can't drown the small one. Scopes INSIDE one repo no longer take that
 * path — they share corpus statistics and a normalization denominator, so they
 * are combined by score (see `ask/fuse.ts`). Separate child repositories have
 * no such shared scale, which is exactly the case rank fusion is for.
 * `grep`/`map`/`check`/`callers` run per child and merge, always labeled
 * `<child>/`.
 *
 * 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 } from "node:path";
import { contextDirFor } from "../context/node-file.js";
import { checkGraph } from "./check.js";
import { loadGraphCached } from "./load.js";
import { buildRepoMap, formatRepoMap } from "./map.js";
import { discoverWorkspaceChildren } from "./scopes.js";
import {
  callersSavings,
  headerOf,
  hitLine,
  looseNoteFor,
} from "./traverse-cli.js";
import { edgeWalk, resolveSymbol, type Direction } from "./traverse.js";
import { wiringPath } from "./write.js";
import type { GraphV1 } from "./types.js";
import {
  ask,
  type AskHit,
  type AskRankingMetadata,
  type AskResult,
} from "../ask/ask.js";
import {
  fileFirstRoundRobin,
  roundRobinQueues,
} from "../ask/file-selection.js";
import { fuseScopes, STRONG_FLOOR, HIGH_FLOOR, type ScopedDoc } from "../ask/fuse.js";
import { grepGraph, type GrepGroup, type GrepResult } from "../search/grep.js";
import { formatGrepResult, zeroHitNote } from "../search/grep-cli.js";
import { withSavings, type Savings } from "../context/savings.js";
import { cmd } from "../brand.js";

/** The parent index written to `<parent>/graft/workspace.json`. Nodes/edges
 * never live at the parent — they live in each child's own `graft/`. */
export interface WorkspaceV1 {
  version: 1;
  /** Immediate child dir names that are git repos, sorted. */
  children: string[];
}

const WORKSPACE_FILE = "workspace.json";

/** Absolute path to the workspace index for a parent root (`<dir>/graft/workspace.json`). */
export function workspacePath(root: string, override?: string): string {
  return join(contextDirFor(root, override), WORKSPACE_FILE);
}

/** 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: string, override?: string): WorkspaceV1 | null {
  const path = workspacePath(root, override);
  try {
    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<WorkspaceV1>;
    if (parsed.version !== 1 || !Array.isArray(parsed.children)) return null;
    return { version: 1, children: parsed.children.map(String) };
  } catch {
    return null;
  }
}

/** Write the workspace index, sorting children for a stable, minimal git diff. */
export function writeWorkspace(root: string, ws: WorkspaceV1, override?: string): string {
  const dir = contextDirFor(root, override);
  mkdirSync(dir, { recursive: true });
  const path = join(dir, WORKSPACE_FILE);
  const sorted: WorkspaceV1 = { version: 1, children: [...ws.children].sort() };
  writeFileSync(path, JSON.stringify(sorted, null, 2) + "\n");
  return path;
}

/** 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: string, override?: string): boolean {
  if (readWorkspace(root, override)) return true;
  if (existsSync(join(root, ".git"))) return false;
  return discoverWorkspaceChildren(root).length >= 2;
}

/** 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: string, override?: string): boolean {
  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: string[]): string {
  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: string, override?: string): void {
  rmSync(contextDirFor(root, override), { recursive: true, force: true });
}

export interface LoadedChild {
  child: string;
  graph: GraphV1;
}

export interface WorkspaceGraphs {
  /** Children (from workspace.json when present, else discovered) that have a
   * built graph, in sorted child order. */
  loaded: LoadedChild[];
  /** Listed children with no built graph yet — surfaced, never silently skipped. */
  missing: string[];
}

/** 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: string, override?: string): WorkspaceGraphs {
  const ws = readWorkspace(root, override);
  const children = (ws ? ws.children : discoverWorkspaceChildren(root)).slice().sort();
  const loaded: LoadedChild[] = [];
  const missing: string[] = [];
  for (const child of children) {
    const graph = loadGraphCached(contextDirFor(join(root, child)));
    if (graph) loaded.push({ child, graph });
    else missing.push(child);
  }
  return { loaded, missing };
}

/** "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: WorkspaceGraphs): string {
  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 ${cmd("graft build")} to cover ${g.missing.join(", ")}`;
}

/** 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: string, pointer: string): string {
  return pointer
    .split(",")
    .map((part) => {
      const t = part.trim();
      if (!t || t.includes(" ")) return part;
      return `${child}/${t}`;
    })
    .join(", ");
}

/** The exact child-relative file owning a lexical symbol hit. File nodes use a
 * bare path; definition hits append `:Lx-Ly`. */
function hitFile(pointer: string): string {
  return pointer.match(/^(.*):L\d+-L\d+$/)?.[1] ?? pointer;
}

export interface FederateAskOptions {
  limit?: number;
  source?: boolean;
  full?: boolean;
  graphRank?: boolean;
  /** Narrow to one child (`repoA`) or a sub-scope within it (`repoA/backend`).
   * A prefix matching NO child throws, listing the repos. */
  in?: string;
  /** @internal File-level child RRF plus an exact workspace baseline top lock. */
  fileTopLock?: boolean;
}

interface ChildRun {
  child: string;
  hits: AskHit[];
  /** The child's top-hit idf-weighted matched share over name+path+body — a
   * RAW, cross-child-comparable magnitude (NOT per-child normalized). */
  coverage: number;
  /** Same, but over name+path ONLY (body dropped) — the match-STRENGTH signal.
   * A body-only incidental collision has `coverageStrong === 0`. */
  coverageStrong: number;
  /** Exact baseline top-hit coverage used only to compute the workspace top lock. */
  baselineCoverage: number;
  baselineCoverageStrong: number;
  /** Present only for the internal file-aware path. */
  ranking?: AskRankingMetadata;
}

// 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. This is now their only
// caller: a share-of-the-query threshold is the best available signal when the
// candidates carry no common score scale, which is the situation across child
// repositories. `rankScopesAndFuse` used to gate on them for the same reason
// and no longer needs to — within one repo the scores are comparable, so a
// weak scope is held back by scoring low rather than by a strength floor.

/**
 * Federated `ask` across a workspace: run each child's own ask pipeline, then
 * fuse ALL the children's scope lists with `fuseScopes` (reciprocal rank). 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.
 *
 * Rank fusion is still right HERE, and only here: each child was scored against
 * its own corpus, so cross-child scores share no scale. Within a single repo
 * that is no longer true — `rankScopesAndFuse` gives every scope the same
 * statistics and the same denominator and combines them by score.
 *
 * Returns a normal `AskResult`; `formatAsk` renders it unchanged, labeling each
 * hit `[<child>/…]` via the standard multi-scope path.
 */
export function federateAsk(
  root: string,
  override: string | undefined,
  query: string,
  opts: FederateAskOptions = {},
): AskResult {
  const wg = loadWorkspaceGraphs(root, override);
  const limit = opts.limit ?? 8;
  const fileTopLock = opts.fileTopLock ?? true;

  // `--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: string | undefined;
  let childIn: string | undefined;
  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;
  }

  // Pass 1: run each child's ask; keep its hits + RAW top-hit coverage.
  const runs: ChildRun[] = [];
  for (const { child } of wg.loaded) {
    if (onlyChild && child !== onlyChild) continue;
    let r: AskResult;
    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,
        // The parent owns the final cross-repo ranking. Selecting inside each
        // child would be undone by fusion and could truncate a hybrid list.
        fileFirst: false,
        fileComplement: fileTopLock,
        includeRankingMetadata: fileTopLock,
      });
    } catch {
      continue; // corrupt child, or a sub-scope --in matching nothing here
    }
    if (r.hits.length === 0) continue;
    const topGroup = r.ranking?.groups[0];
    runs.push({
      child,
      hits: r.hits,
      coverage: topGroup?.coverage ?? r.coverage ?? 0,
      coverageStrong: topGroup?.coverageStrong ?? r.coverageStrong ?? 0,
      baselineCoverage: r.ranking?.baselineCoverage ?? r.coverage ?? 0,
      baselineCoverageStrong:
        r.ranking?.baselineCoverageStrong ?? r.coverageStrong ?? 0,
      ranking: r.ranking,
    });
  }

  // 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: { scope: string; bestId: string }[] = [];
  const survivors: ChildRun[] = [];
  const baselineSurvivors: ChildRun[] = [];
  for (const run of runs) {
    const baselineEligible =
      onlyChild ||
      run.baselineCoverageStrong >= STRONG_FLOOR ||
      run.baselineCoverage >= HIGH_FLOOR;
    const fileEligible =
      onlyChild ||
      run.coverageStrong >= STRONG_FLOOR ||
      run.coverage >= HIGH_FLOOR;
    if (baselineEligible) baselineSurvivors.push(run);
    // Distributed file evidence may admit a child, but the exact baseline
    // top lock must never resurrect a child that the final stream calls gated
    // out. The production survivor set is therefore the union of both gates;
    // baselineSurvivors remains the strict baseline subset used only to choose the
    // locked pointer.
    if (baselineEligible || fileEligible) survivors.push(run);
    else {
      const best = run.ranking?.groups[0]?.hits[0] ?? run.hits[0];
      gatedOut.push({ scope: run.child, bestId: prefixPointer(run.child, best.pointer) });
    }
  }

  if (fileTopLock) {
    type WorkspaceGroup = {
      key: string;
      child: string;
      hits: AskHit[];
      baselineHits: AskHit[];
    };
    const qualifyHit = (
      child: string,
      hit: AskHit,
      score = hit.score,
      scope = hit.scope ? `${child}/${hit.scope}` : child,
    ): AskHit => ({
      ...hit,
      score,
      scope,
      pointer: prefixPointer(child, hit.pointer),
    });
    const sameHit = (a: AskHit, b: AskHit): boolean =>
      a.kind === b.kind && a.pointer === b.pointer && a.title === b.title;

    // Baseline workspace stream: reproduce the all-span RRF exactly so the
    // final lock owns the same concrete pointer and fused score as the baseline.
    const baselineDocs: ScopedDoc[] = [];
    const baselineBack = new Map<
      string,
      { child: string; group: string; hit: AskHit }
    >();
    for (const run of baselineSurvivors) {
      const entries = run.ranking?.baseline ?? run.hits.map((hit, index) => ({
        group: `singleton:${index}`,
        hit,
      }));
      entries.forEach((entry, index) => {
        // Keep the legacy id shape so equal-score baseline ties remain exact.
        const id = `${run.child} ${index}`;
        const scope = entry.hit.scope
          ? `${run.child}/${entry.hit.scope}`
          : run.child;
        baselineDocs.push({ id, scope, score: entry.hit.score });
        baselineBack.set(id, {
          child: run.child,
          group: `${run.child}\0${entry.group}`,
          hit: entry.hit,
        });
      });
    }
    const baselineFused = fuseScopes(baselineDocs);
    const baselineTopRanked = baselineFused.ranked[0];
    const baselineTopBack = baselineTopRanked
      ? baselineBack.get(baselineTopRanked.id)
      : undefined;
    const baselineTop = baselineTopRanked && baselineTopBack
      ? qualifyHit(
          baselineTopBack.child,
          baselineTopBack.hit,
          baselineTopRanked.score,
          baselineTopRanked.scope,
        )
      : undefined;

    // File-aware workspace stream: exactly one leader per child/file (concepts stay
    // singleton groups) participates in RRF. Span queues remain in a side map
    // and cannot consume reciprocal-rank positions.
    const fileDocs: ScopedDoc[] = [];
    const fileBack = new Map<string, WorkspaceGroup>();
    for (const run of survivors) {
      const groups = run.ranking?.groups ?? run.hits.map((hit, index) => ({
        key: `singleton:${index}`,
        hits: [hit],
        baselineHits: [hit],
        coverage: 0,
        coverageStrong: 0,
      }));
      groups.forEach((group, index) => {
        const leader = group.hits[0];
        if (!leader) return;
        const id = `${run.child} file ${String(index).padStart(8, "0")}`;
        const scope = leader.scope ? `${run.child}/${leader.scope}` : run.child;
        const key = `${run.child}\0${group.key}`;
        fileDocs.push({ id, scope, score: leader.score });
        fileBack.set(id, {
          key,
          child: run.child,
          hits: group.hits,
          baselineHits: group.baselineHits ?? [leader],
        });
      });
    }
    const fileFused = fuseScopes(fileDocs);
    const rankedGroups: WorkspaceGroup[] = fileFused.ranked.flatMap((ranked) => {
      const group = fileBack.get(ranked.id);
      if (!group) return [];
      return [{
        ...group,
        // These spans are projections of one cross-child file document. Keep
        // their public score on that same RRF scale; child-local tail scores are
        // not comparable after workspace fusion and downstream re-sorting would
        // otherwise silently undo the file ordering.
        hits: group.hits.map((hit) =>
          qualifyHit(
            group.child,
            hit,
            ranked.score,
            hit.scope ? `${group.child}/${hit.scope}` : group.child,
          ),
        ),
        baselineHits: group.baselineHits.map((hit) => qualifyHit(group.child, hit)),
      }];
    });

    let projectedGroups = rankedGroups;
    if (baselineTop && baselineTopBack) {
      const key = baselineTopBack.group;
      const existing = rankedGroups.find((group) => group.key === key);
      const baselineQueue = existing?.baselineHits ?? [baselineTop];
      const projectedScore = existing?.hits[0]?.score ?? baselineTop.score;
      const locked: WorkspaceGroup = existing
        ? {
            ...existing,
            hits: [
              baselineTop,
              ...baselineQueue
                .filter((hit) => !sameHit(hit, baselineTop))
                .map((hit) => ({ ...hit, score: projectedScore })),
            ],
          }
        : {
            key,
            child: baselineTopBack.child,
            hits: [baselineTop],
            baselineHits: [baselineTop],
          };
      projectedGroups = [
        locked,
        ...rankedGroups.filter((group) => group.key !== key),
      ];
    }

    const hits = roundRobinQueues(
      projectedGroups.map((group) => group.hits),
      limit,
    );
    const unmatched = [...fileFused.alsoMatched, ...gatedOut];
    const note = coverageNote(wg);
    const result: AskResult = {
      query,
      mode: hits.length ? "lexical" : "empty",
      hits,
    };
    if (hits.length) {
      const lockedScope = baselineTop?.scope;
      const federated = [
        ...new Set([
          ...(lockedScope ? [lockedScope] : []),
          ...fileFused.federated,
        ]),
      ];
      const federatedSet = new Set(federated);
      result.scopes = {
        federated,
        alsoMatched: unmatched.filter((match) => !federatedSet.has(match.scope)),
      };
    } else {
      result.note = `no matching nodes across ${wg.loaded.length} workspace repo(s) — try different words, or \`${cmd("graft build")}\` at a child`;
    }
    if (note) result.note = result.note ? `${result.note}\n${note}` : note;
    return result;
  }

  // Fuse the survivors' scope lists (within-child fusion is left untouched —
  // each child already ran its own per-scope RRF).
  const docs: ScopedDoc[] = [];
  const back = new Map<string, { child: string; hit: AskHit }>();
  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 });
    });
  }

  const fused = fuseScopes(docs);
  const rankedHits = fused.ranked.map((rd) => {
    const { child, hit } = back.get(rd.id)!;
    const value: AskHit = {
      ...hit,
      score: rd.score,
      scope: rd.scope,
      pointer: prefixPointer(child, hit.pointer),
    };
    return {
      // Lexical symbols share a file queue. Concepts and structural neighbours
      // remain singleton partitions, so this lexical selection layer cannot
      // reorder `who calls` / `dependencies of` answers.
      group: hit.kind === "symbol"
        ? `file:${child}/${hitFile(hit.pointer)}`
        : `singleton:${child}:${rd.id}`,
      value,
    };
  });
  const hits = fileFirstRoundRobin(rankedHits, limit);

  const alsoMatched = [...fused.alsoMatched, ...gatedOut];
  const note = coverageNote(wg);
  const result: AskResult = { 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 };
  } else {
    result.note = `no matching nodes across ${wg.loaded.length} workspace repo(s) — try different words, or \`${cmd("graft build")}\` at a child`;
  }
  if (note) result.note = result.note ? `${result.note}\n${note}` : note;
  return result;
}

/** 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: string,
  override: string | undefined,
  pattern: string,
  opts: { ignoreCase?: boolean; fixed?: boolean } = {},
): { result: GrepResult; coverage: string } {
  const wg = loadWorkspaceGraphs(root, override);
  const groups: GrepGroup[] = [];
  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,
      });
    }
  }

  groups.sort((a, b) => b.inDegree - a.inDegree || a.path.localeCompare(b.path));
  const saved: Savings | undefined = savedChars > 0 ? { files: savedFiles, baselineChars: savedChars } : undefined;
  const result: GrepResult = { pattern, filesSearched, totalHits, groups, truncated, saved };
  return { result, coverage: coverageNote(wg) };
}

/** 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: string,
  override: string | undefined,
  opts: { maxDirs?: number } = {},
): string {
  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()}`;
  });
  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 drift status. `ok` is false when any BUILT child is stale — an
 * unbuilt child is surfaced (coverage), never a failure. */
export async function federateCheck(
  root: string,
  override?: string,
): Promise<{ text: string; ok: boolean }> {
  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 = await checkGraph(join(root, child));
    if (g.ok) {
      lines.push(`${child}/: OK`);
    } else {
      ok = false;
      const bits: string[] = [];
      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 ${cmd("graft build")})`);
  const cov = coverageNote(wg);
  if (cov) lines.push("", cov);
  return { text: lines.join("\n") + "\n", ok };
}

/** 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: string,
  override: string | undefined,
  symbol: string,
  opts: { direction?: Direction; depth?: number; in?: string } = {},
): { text: string; found: boolean } {
  const wg = loadWorkspaceGraphs(root, override);
  const direction: Direction = opts.direction ?? "in";
  const depth = opts.depth && opts.depth >= 1 ? Math.floor(opts.depth) : 1;
  const showDepth = depth > 1;

  const blocks: string[] = [];
  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, matches.length));
      else for (const h of hits) lines.push(hitLine(direction, h, showDepth));
    }
    const body = lines.join("\n");
    blocks.push(withSavings(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 ${cmd("graft build")}`;
    return { text: cov ? `${base}\n${cov}` : base, found: false };
  }
  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: string,
  override: string | undefined,
  buildChild: (childDir: string, childName: string) => Promise<void>,
  onStart?: (info: { children: string[]; migrated: boolean }) => void,
): Promise<{ children: string[]; migrated: boolean }> {
  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 };