@nanonets/graft 0.6.0 → 0.7.0

package/README.md

@@ -189,6 +189,7 @@ graft build --extensions .ts .py     # only include these code extensions
 
 graft ask "<task>" [dir]             # query the graph — ranked nodes + exact file:line (no LLM, no key)
 graft ask "<task>" --json            # machine-readable result
+graft ask "<task>" --in <scope>      # narrow to one sub-project of a monorepo/multi-repo folder (see below)
 
 graft callers <symbol> [dir]         # who calls/references/imports/implements/extends a symbol (no LLM, no key)
 graft callers <symbol> --direction out  # the reverse: what the symbol itself calls/references (was `graft callees`)
@@ -259,6 +260,25 @@ scripts/            2 files · 0 symbols
 hotspots: set · method · src/graph/bindings.ts:L21-L23 · 38←  contextDirFor · function · src/context/node-file.ts:L100-L103 · 11←  wiringPath · function · src/graph/write.ts:L20-L22 · 10←  ...
 ```
 
+## Monorepos & multi-repo folders
+
+Graft handles two shapes without any config:
+
+- **A monorepo with one `.git`** (a `pnpm-workspace.yaml`/`package.json`
+  `workspaces`, or per-package `go.mod`/`pyproject.toml`/`Cargo.toml`) —
+  `graft build` discovers each sub-project as a ranking scope. `ask`/`map`
+  rank every scope on its own terms and fuse the results, so the biggest
+  sub-project can't drown a small one; hits carry `[scope/]` labels, and
+  `graft map` groups its directory clusters by scope first.
+- **A folder of separate git repos** (no `.git` at the top) — `graft build`
+  auto-splits: each child keeps its own committable `graft/`, and the parent
+  gets a `graft/workspace.json` index. Queries from the parent federate across
+  every child, always labeled `<child>/`. Run `graft build` inside a child to
+  work on just that repo.
+
+Either way, narrow to one sub-project with `graft ask "<task>" --in <scope>/`
+once you know where you're working.
+
 ## Visualize it (`graft viz`)
 
 `graft viz` opens a local, interactive view of both graphs — no install, no dev

package/dist/ask/ask.d.ts

@@ -1,5 +1,5 @@
 import { type Savings } from "../context/savings.js";
-import type { Relation } from "../graph/types.js";
+import type { NodeV1, Relation } from "../graph/types.js";
 export interface AskHit {
     kind: "concept" | "symbol" | "caller" | "callee";
     title: string;
@@ -13,6 +13,10 @@ export interface AskHit {
      * This is what makes `ask` substitutive — the agent reads the span here
      * instead of opening the file, so no source read happens on top of the query. */
     code?: string;
+    /** Multi-scope repos only: the ranking scope (path prefix, "" = root) this
+     * hit was ranked within — answers "which sub-project is this from?". Drives
+     * the `[scope/] ` label in formatAsk. Absent on single-scope repos. */
+    scope?: string;
 }
 export interface AskResult {
     query: string;
@@ -34,7 +38,45 @@ export interface AskResult {
      * best result, i.e. the pack is probably noise for this prompt. Absent in
      * structural mode — a resolved "who calls X" is itself the relevance signal. */
     coverage?: number;
+    /** Like {@link coverage}, but the top hit's idf-weighted matched share over
+     * its NAME + PATH fields ONLY (body excluded) — a match-STRENGTH signal:
+     * "did the query hit a high-value field, or only incidental body tokens?".
+     * A body-only collision (a variable that happens to share a query word) has
+     * `coverageStrong === 0` while `coverage` can still look respectable. Used by
+     * workspace federation to gate a weak child out of the cross-repo ranking.
+     * Absent in structural mode; same lexical-only contract as `coverage`. */
+    coverageStrong?: number;
+    /** Multi-scope lexical results only: which scopes federated into the fused
+     * ranking, plus scopes that matched too weakly to federate (with their best
+     * doc id). Drives formatAsk's `matched in:` / `also matched:` footer.
+     * Absent on single-scope repos — zero output change there. */
+    scopes?: {
+        federated: string[];
+        alsoMatched: {
+            scope: string;
+            bestId: string;
+        }[];
+    };
 }
+/** Idf-weighted share (0..1) of the query a document matches: each query term
+ * counts by its rarity, so this separates task prompts from chatter in a way a
+ * raw term count can't. A conversational prompt's words are either off-corpus
+ * (rare → heavy, unmatched → sinks the ratio) or generic code words ("list",
+ * "write": common → near-weightless even when they collide with a symbol name);
+ * a task prompt matches exactly its rare, discriminating identifiers. Terms the
+ * corpus has never seen take `dfltIdf` (the df=0 weight). */
+/** The match-STRENGTH share behind `coverageStrong`: idf-weighted share of the
+ * query matched in the node's NAME field ONLY. The PATH field is deliberately
+ * excluded — a coincidental generic directory (`gateway/`) or file basename
+ * (`gateway.ts`) in an unrelated repo would otherwise clear the strength gate
+ * and float that repo to the top; an on-topic path-organized repo is still
+ * rescued by the broad-coverage HIGH_FLOOR clause instead. For the same reason
+ * a `kind:"file"` node contributes zero strength: its `name` is a basename (a
+ * path component), not a symbol name, so a file whose basename happens to share
+ * a query word is not a strong match. */
+export declare function strongShare(q: Map<string, number>, node: NodeV1, doc: {
+    name: Map<string, number>;
+}, idf: Map<string, number>, dfltIdf: number): number;
 export interface AskOptions {
     contextDir?: string;
     limit?: number;
@@ -51,6 +93,12 @@ export interface AskOptions {
      * decision point, ~10× cheaper than the full span — and the pack marks each
      * crux so the agent knows `--full` (or the file itself) has the rest. */
     full?: boolean;
+    /** Narrow the doc/node set to this path prefix BEFORE scoring (segment-aware,
+     * like `scopeOf` — "frontend" never matches "frontend-utils"). Per-scope
+     * IDF/BM25/walk come free: the filtered set is usually one scope, so the
+     * existing multi-scope machinery degrades to its single-scope passthrough
+     * with no scope labels. A prefix matching nothing indexed throws. */
+    in?: string;
 }
 /** Answer a query from the graft/ graph at `dir`. Deterministic, $0. */
 export declare function ask(dir: string, query: string, opts?: AskOptions): AskResult;

package/dist/ask/ask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/ask/ask.ts"],"names":[],"mappings":"AAmBA,OAAO,EAA6B,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGhF,OAAO,KAAK,EAA2B,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAI3E,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd;;qFAEiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;IACzC,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;sFAEkF;IAClF,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD;;;;oFAIgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA2aD,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;qFACiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;sFAEkF;IAClF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;6EAIyE;IACzE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AA0ED,wEAAwE;AACxE,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,SAAS,CA8BhF;AAID,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;2EAE2E;AAC3E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,cAAc,CA8BtG;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAUxD;AAOD,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAsC9C"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/ask/ask.ts"],"names":[],"mappings":"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"}

package/dist/ask/ask.js

@@ -19,7 +19,9 @@ import matter from "gray-matter";
 import { contextDirFor } from "../context/node-file.js";
 import { savingsFooter, savingsFor } from "../context/savings.js";
 import { loadGraphCached, loadAskIndexCached } from "../graph/load.js";
+import { pathUnderPrefix, scopeLabel, scopeOf, scopesHereClause, scopesOfGraph } from "../graph/scopes.js";
 import { resolveSymbol } from "../graph/traverse.js";
+import { rankScopesAndFuse } from "./fuse.js";
 import { personalizedPageRank } from "./graphrank.js";
 import { counts, tokenize } from "./index-file.js";
 /** Max source lines to inline per hit — a definition longer than this is
@@ -144,11 +146,22 @@ function subjectWords(query) {
  * last regardless of outcome, so a caller can name *something* in a fallthrough
  * note even when nothing resolved (e.g. `subjects.length === 0`). This is what
  * makes a qualified/dotted subject like `Cache.get` resolve, where the old
- * plain name-equality lookup (`findSubject`) never matched it. */
-function findSubjectNodes(query, graph) {
+ * plain name-equality lookup (`findSubject`) never matched it.
+ *
+ * `inPrefix`, when given, filters each word's `resolveSymbol` matches down to
+ * nodes under that path prefix BEFORE checking whether any survived — same
+ * "narrow the subject resolution" semantics `callers`/`callees`/`impact --in`
+ * already have (segment-aware here, via `pathUnderPrefix`). A word that
+ * resolves globally but has nothing under the prefix does NOT count as a
+ * match; the next (shorter) word is tried instead, same as an unresolved word
+ * today — and if nothing survives for ANY word, `subjects.length === 0`
+ * naturally falls through to the existing loud fallthrough note. */
+function findSubjectNodes(query, graph, inPrefix) {
     const words = subjectWords(query).sort((a, b) => b.length - a.length);
     for (const w of words) {
-        const nodes = resolveSymbol(graph, w);
+        let nodes = resolveSymbol(graph, w);
+        if (inPrefix)
+            nodes = nodes.filter((n) => pathUnderPrefix(n.path, inPrefix));
         if (nodes.length > 0)
             return { nodes, tried: w };
     }
@@ -158,12 +171,12 @@ function fallthroughNoteFor(subject) {
     return (`structural index: no entries for '${subject}' — showing lexical matches; ` +
         `for exhaustive callers use grep -rn '${subject}'`);
 }
-function structural(query, graph, limit) {
+function structural(query, graph, limit, inPrefix) {
     const wantsIn = INCOMING.test(query);
     const wantsOut = OUTGOING.test(query);
     if (!wantsIn && !wantsOut)
         return null;
-    const { nodes: subjects, tried } = findSubjectNodes(query, graph);
+    const { nodes: subjects, tried } = findSubjectNodes(query, graph, inPrefix);
     if (subjects.length === 0)
         return { fallthroughNote: fallthroughNoteFor(tried) };
     const ids = new Set(subjects.map((n) => n.id));
@@ -232,6 +245,20 @@ function hasTerm(f, t) {
  * "write": common → near-weightless even when they collide with a symbol name);
  * a task prompt matches exactly its rare, discriminating identifiers. Terms the
  * corpus has never seen take `dfltIdf` (the df=0 weight). */
+/** The match-STRENGTH share behind `coverageStrong`: idf-weighted share of the
+ * query matched in the node's NAME field ONLY. The PATH field is deliberately
+ * excluded — a coincidental generic directory (`gateway/`) or file basename
+ * (`gateway.ts`) in an unrelated repo would otherwise clear the strength gate
+ * and float that repo to the top; an on-topic path-organized repo is still
+ * rescued by the broad-coverage HIGH_FLOOR clause instead. For the same reason
+ * a `kind:"file"` node contributes zero strength: its `name` is a basename (a
+ * path component), not a symbol name, so a file whose basename happens to share
+ * a query word is not a strong match. */
+export function strongShare(q, node, doc, idf, dfltIdf) {
+    if (node.kind === "file")
+        return 0;
+    return matchedIdfShare(q, [doc.name], idf, dfltIdf);
+}
 function matchedIdfShare(q, fields, idf, dfltIdf) {
     let matched = 0;
     let total = 0;
@@ -243,14 +270,19 @@ function matchedIdfShare(q, fields, idf, dfltIdf) {
     }
     return total > 0 ? matched / total : 0;
 }
-function lexical(query, corpus, limit, graphRank) {
+function lexical(query, corpus, limit, graphRank, inPrefix) {
     // Binary query terms: a word repeated in a pasted issue body counts once, so a
     // ranty description can't linearly amplify an incidental word.
     const q = new Map([...counts(tokenize(query)).keys()].map((t) => [t, 1]));
     const graph = corpus.graph;
     // ── Pass 1: tokenize every scored field once, and collect per-document token
-    // bags so IDF can down-weight words that occur across the whole corpus. ──
-    const conceptDocs = corpus.concepts.map((c) => ({
+    // bags so IDF can down-weight words that occur across the whole corpus. `--in`
+    // drops a concept unless at least one of its sources falls under the prefix —
+    // filtering happens here, before any scoring, so a narrowed query never sees
+    // an unrelated concept from outside the prefix. ──
+    const conceptDocs = corpus.concepts
+        .filter((c) => !inPrefix || c.sources.some((p) => pathUnderPrefix(p, inPrefix)))
+        .map((c) => ({
         c,
         name: counts(tokenize(c.name)),
         body: counts(tokenize(c.text)),
@@ -262,6 +294,18 @@ function lexical(query, corpus, limit, graphRank) {
     // that — missing, unparseable, unknown version, wrong count, mismatched ids —
     // falls back to live tokenization so results never depend on the sidecar
     // existing; see `readAskIndex`'s own null-on-anything-off contract.
+    //
+    // `--in` does NOT disable the sidecar here: `writeGraph` strips `body_text`
+    // from every node it serializes (see `write.ts`) — the sidecar's per-doc
+    // `docs[].body` bags are the ONLY place a symbol's body tokens survive on a
+    // graph loaded from disk. Bypassing the sidecar under `--in` would silently
+    // empty out `body` for every node (falling back to `n.body_text ?? ""`,
+    // always `""` post-slim-serialization), losing every body-only match under
+    // the filtered prefix. What DOES need bypassing under `--in` is the
+    // sidecar's GLOBAL `df`/`docCount`/`avgBodyLen` — those cover the whole
+    // corpus, not the filtered subset — so each read of those three fields below
+    // is separately gated on `!inPrefix`, while the per-doc bags (used to build
+    // `symbolDocs` right after this) are used unconditionally.
     let docById = null;
     if (corpus.askIndex && graph && corpus.askIndex.docs.length === graph.nodes.length) {
         const map = new Map(corpus.askIndex.docs.map((d) => [d.id, d]));
@@ -272,8 +316,12 @@ function lexical(query, corpus, limit, graphRank) {
     // Symbols AND file nodes are scored: a symbol's body_text is its definition;
     // a file's body_text is the module-level residual (imports/constants not in
     // any symbol). Including files closes the recall gap where a gold file's only
-    // query-relevant text lives outside every function/class.
-    const symbolDocs = (graph?.nodes ?? []).map((n) => {
+    // query-relevant text lives outside every function/class. `--in` filters the
+    // node set here, at the very top, before any scoring — every downstream stat
+    // (idf, avgdl, candidates, the per-scope partition below) then naturally
+    // reflects only the filtered set with no other code needing to know about it.
+    const graphNodes = inPrefix ? (graph?.nodes ?? []).filter((n) => pathUnderPrefix(n.path, inPrefix)) : (graph?.nodes ?? []);
+    const symbolDocs = graphNodes.map((n) => {
         const d = docById?.get(n.id);
         if (d)
             return { n, name: new Map(d.name), path: new Map(d.path), body: new Map(d.body) };
@@ -296,18 +344,25 @@ function lexical(query, corpus, limit, graphRank) {
     // IDF must see the SAME inputs either way: with a sidecar, its `df` (stored
     // WITHOUT concepts) plus these live concept bags reproduces exactly what
     // `computeIdf` below would compute from concept+symbol bags tokenized live.
-    const idf = askIndex
+    // `askIndex.df` is a corpus-GLOBAL count, so `--in` can't use it — the
+    // filtered doc set needs its own idf, computed from (already-filtered)
+    // `symbolDocs`' own bags, regardless of where those bags came from.
+    const idf = askIndex && !inPrefix
         ? computeIdfFromIndex(askIndex, conceptBags)
         : computeIdf([...conceptBags, ...symbolDocs.map((d) => new Set([...d.name.keys(), ...d.path.keys(), ...d.body.keys()]))]);
     // Per-hit idf-weighted coverage, kept out of the public AskHit shape; only
     // the top hit's value survives, as `coverage` on the result. The df=0 weight
     // mirrors idfFromDf's formula at df=0 for whichever corpus size idf was
-    // computed from.
-    const nDocs = askIndex
+    // computed from. Same `--in` reasoning as `idf` above: `askIndex.docCount`
+    // is global.
+    const nDocs = askIndex && !inPrefix
         ? askIndex.docCount + conceptBags.length
         : conceptBags.length + symbolDocs.length;
     const dfltIdf = Math.log(1 + nDocs);
     const matchedOf = new Map();
+    // Parallel to matchedOf, but over NAME+PATH only (body dropped) — the
+    // match-strength signal exported as `coverageStrong`.
+    const matchedStrongOf = new Map();
     // ── Concepts (prose nodes; not in the wiring graph) ──
     const conceptHits = [];
     let maxConcept = 0;
@@ -324,6 +379,7 @@ function lexical(query, corpus, limit, graphRank) {
                 score: total,
             };
             matchedOf.set(hit, matchedIdfShare(q, [name, body], idf, dfltIdf));
+            matchedStrongOf.set(hit, matchedIdfShare(q, [name], idf, dfltIdf)); // concepts have no path field
             conceptHits.push(hit);
         }
     }
@@ -335,56 +391,159 @@ function lexical(query, corpus, limit, graphRank) {
             s += v;
         return s;
     };
-    const avgBodyLen = askIndex
-        ? askIndex.avgBodyLen
-        : symbolDocs.length
-            ? symbolDocs.reduce((a, d) => a + bodyLen(d.body), 0) / symbolDocs.length
-            : 0;
-    const lex = new Map(); // node id → lexical score (>0 only)
-    let maxLex = 0;
-    for (const { n, name, path, body } of symbolDocs) {
-        // Name and path are short identifiers → plain idf-weighted overlap; the body
-        // is length-normalized via BM25 so long definitions don't win on bulk.
-        const total = score(q, name, idf) * 3 +
-            score(q, path, idf) * 2 +
-            bm25(q, body, idf, bodyLen(body), avgBodyLen);
-        if (total > 0) {
-            lex.set(n.id, total);
-            maxLex = Math.max(maxLex, total);
-        }
-    }
-    // ── Graph-rank: let connectivity to the matched set reorder and rescue ──
-    const pr = graphRank && graph && lex.size > 0
-        ? personalizedPageRank(graph, lex)
-        : new Map();
-    // Candidate symbols = everything the query word-matched, plus nodes the walk
-    // found strongly central even without a word match (RESCUE_FLOOR).
-    const candidates = new Set(lex.keys());
-    for (const [id, p] of pr)
-        if (p >= RESCUE_FLOOR)
-            candidates.add(id);
     const docsById = new Map(symbolDocs.map((d) => [d.n.id, d]));
     const symbolHits = [];
-    for (const id of candidates) {
-        const n = byId.get(id);
-        if (!n)
-            continue;
-        const lexN = maxLex > 0 ? (lex.get(id) ?? 0) / maxLex : 0;
-        const blended = lexN + GRAPH_WEIGHT * (pr.get(id) ?? 0);
-        if (blended <= 0)
-            continue;
-        const hit = {
-            kind: "symbol",
-            title: `${n.name} · ${n.kind}`,
-            // A file node points at the whole file (locator, no span) so `--source`
-            // never inlines an entire file; symbol nodes keep their exact span.
-            pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
-            snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
-            score: blended,
-        };
-        const d = docsById.get(id);
-        matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);
-        symbolHits.push(hit);
+    // The single-vs-multi-scope branch keys on `scopesOfGraph` ONLY: one scope
+    // (or no graph) takes the existing path below completely untouched — that
+    // branch is a byte-level regression guarantee for single-scope repos.
+    const scopes = graph ? scopesOfGraph(graph) : null;
+    let scopeMeta;
+    if (scopes && scopes.length > 1) {
+        // ── Multi-scope repo: rank each sub-project against its OWN corpus (its
+        // IDF, its BM25 length prior, its subgraph walk), then fuse the per-scope
+        // orderings by reciprocal rank — the big scope can't drown the small one.
+        // Same scoring functions and blend as the single-scope path, just fed
+        // per-scope inputs; the fusion itself lives in fuse.ts. ──
+        const byScope = new Map();
+        for (const d of symbolDocs) {
+            const s = scopeOf(d.n.path, scopes).prefix;
+            const list = byScope.get(s);
+            if (list)
+                list.push(d);
+            else
+                byScope.set(s, [d]);
+        }
+        const idfOf = new Map();
+        const fusion = rankScopesAndFuse([...byScope.keys()].sort(), {
+            lex: (s) => {
+                const docs = byScope.get(s);
+                // Per-scope IDF/BM25 stats: concepts are repo-level so their bags
+                // fold in everywhere, symbol bags come from this scope only. (The
+                // build sidecar's df/avgBodyLen are corpus-global, so multi-scope
+                // always computes these live — from the sidecar's own token maps.)
+                const sIdf = computeIdf([
+                    ...conceptBags,
+                    ...docs.map((d) => new Set([...d.name.keys(), ...d.path.keys(), ...d.body.keys()])),
+                ]);
+                idfOf.set(s, { idf: sIdf, dflt: Math.log(1 + conceptBags.length + docs.length) });
+                const avg = docs.reduce((a, d) => a + bodyLen(d.body), 0) / docs.length;
+                const out = new Map();
+                for (const { n, name, path, body } of docs) {
+                    const total = score(q, name, sIdf) * 3 +
+                        score(q, path, sIdf) * 2 +
+                        bm25(q, body, sIdf, bodyLen(body), avg);
+                    if (total > 0)
+                        out.set(n.id, total);
+                }
+                return out;
+            },
+            // The participation gate's match-STRENGTH signal, evaluated once per
+            // scope on that scope's raw-lex top doc — same `strongShare`/
+            // `matchedIdfShare` functions and per-scope idf `lex` (above) just
+            // computed, so this reads the SAME strength `federateAsk` gates on
+            // (see fuse.ts's STRONG_FLOOR/HIGH_FLOOR).
+            strength: (s, id) => {
+                const d = docsById.get(id);
+                const si = idfOf.get(s);
+                if (!d || !si)
+                    return { coverage: 0, coverageStrong: 0 };
+                return {
+                    coverage: matchedIdfShare(q, [d.name, d.path, d.body], si.idf, si.dflt),
+                    coverageStrong: strongShare(q, d.n, d, si.idf, si.dflt),
+                };
+            },
+            walk: (s, seeds) => graphRank
+                ? personalizedPageRank(graph, seeds, {
+                    nodeFilter: (id) => {
+                        const path = byId.get(id)?.path ?? "";
+                        return scopeOf(path, scopes).prefix === s && (!inPrefix || pathUnderPrefix(path, inPrefix));
+                    },
+                })
+                : new Map(),
+        }, GRAPH_WEIGHT, RESCUE_FLOOR);
+        for (const rd of fusion.ranked) {
+            const n = byId.get(rd.id);
+            if (!n)
+                continue;
+            const hit = {
+                kind: "symbol",
+                title: `${n.name} · ${n.kind}`,
+                pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
+                snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
+                score: rd.score,
+                scope: rd.scope,
+            };
+            const d = docsById.get(rd.id);
+            const si = idfOf.get(rd.scope);
+            matchedOf.set(hit, d && si ? matchedIdfShare(q, [d.name, d.path, d.body], si.idf, si.dflt) : 0);
+            matchedStrongOf.set(hit, d && si ? strongShare(q, n, d, si.idf, si.dflt) : 0);
+            symbolHits.push(hit);
+        }
+        // Label + footer only when federation actually happened (or a scope was
+        // gated out and is worth mentioning) — a query matching one scope of a
+        // multi-scope repo reads exactly like today.
+        if (fusion.federated.length > 1 || fusion.alsoMatched.length > 0)
+            scopeMeta = { federated: fusion.federated, alsoMatched: fusion.alsoMatched };
+    }
+    else {
+        // Single-scope: the pre-scopes ranking path, byte-identical output when
+        // `--in` is absent (Task 3's regression guarantee: `askIndex && !inPrefix`
+        // reduces to plain `askIndex` when `inPrefix` is undefined, so this line is
+        // a no-op change for every non-`--in` caller). Under `--in`, `askIndex`'s
+        // `avgBodyLen` is corpus-global and must not be reused for the filtered set.
+        const avgBodyLen = askIndex && !inPrefix
+            ? askIndex.avgBodyLen
+            : symbolDocs.length
+                ? symbolDocs.reduce((a, d) => a + bodyLen(d.body), 0) / symbolDocs.length
+                : 0;
+        const lex = new Map(); // node id → lexical score (>0 only)
+        let maxLex = 0;
+        for (const { n, name, path, body } of symbolDocs) {
+            // Name and path are short identifiers → plain idf-weighted overlap; the body
+            // is length-normalized via BM25 so long definitions don't win on bulk.
+            const total = score(q, name, idf) * 3 +
+                score(q, path, idf) * 2 +
+                bm25(q, body, idf, bodyLen(body), avgBodyLen);
+            if (total > 0) {
+                lex.set(n.id, total);
+                maxLex = Math.max(maxLex, total);
+            }
+        }
+        // ── Graph-rank: let connectivity to the matched set reorder and rescue ──
+        // `--in` restricts the walk itself, not just the seeds: without a nodeFilter
+        // here, a RESCUE_FLOOR-qualifying neighbour OUTSIDE the prefix could still
+        // surface, defeating the "filters before scoring" contract.
+        const pr = graphRank && graph && lex.size > 0
+            ? personalizedPageRank(graph, lex, inPrefix ? { nodeFilter: (id) => pathUnderPrefix(byId.get(id)?.path ?? "", inPrefix) } : {})
+            : new Map();
+        // Candidate symbols = everything the query word-matched, plus nodes the walk
+        // found strongly central even without a word match (RESCUE_FLOOR).
+        const candidates = new Set(lex.keys());
+        for (const [id, p] of pr)
+            if (p >= RESCUE_FLOOR)
+                candidates.add(id);
+        for (const id of candidates) {
+            const n = byId.get(id);
+            if (!n)
+                continue;
+            const lexN = maxLex > 0 ? (lex.get(id) ?? 0) / maxLex : 0;
+            const blended = lexN + GRAPH_WEIGHT * (pr.get(id) ?? 0);
+            if (blended <= 0)
+                continue;
+            const hit = {
+                kind: "symbol",
+                title: `${n.name} · ${n.kind}`,
+                // A file node points at the whole file (locator, no span) so `--source`
+                // never inlines an entire file; symbol nodes keep their exact span.
+                pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
+                snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
+                score: blended,
+            };
+            const d = docsById.get(id);
+            matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);
+            matchedStrongOf.set(hit, d ? strongShare(q, n, d, idf, dfltIdf) : 0);
+            symbolHits.push(hit);
+        }
     }
     // Concepts and symbols live on comparable 0..~1.5 scales so they merge fairly:
     // concept scores are normalized to their own max, symbol scores are the
@@ -397,8 +556,14 @@ function lexical(query, corpus, limit, graphRank) {
         query,
         mode: scored.length ? "lexical" : "empty",
         hits: scored.slice(0, limit),
+        scopes: scopeMeta,
         coverage: scored.length && q.size > 0 ? matchedOf.get(scored[0]) ?? 0 : undefined,
-        note: scored.length ? undefined : "no matching nodes — try different words, or `graft build` if graft/ is empty",
+        coverageStrong: scored.length && q.size > 0 ? matchedStrongOf.get(scored[0]) ?? 0 : undefined,
+        // Zero hits on a genuinely multi-scope graph names the scopes that exist,
+        // so a query that missed everywhere still tells the caller where to look.
+        note: scored.length
+            ? undefined
+            : `no matching nodes — try different words, or \`graft build\` if graft/ is empty${scopesHereClause(scopes ?? [])}`,
     };
 }
 /** Parse a `path:Lx-Ly` pointer into its parts, or null if it isn't one
@@ -485,14 +650,26 @@ export function ask(dir, query, opts = {}) {
     const limit = opts.limit ?? 8;
     const corpus = loadCorpus(outDir);
     const graphRank = opts.graphRank ?? true;
+    // Trailing slash(es) stripped ONCE, up front, and this normalized value used
+    // everywhere below (validation, filtering, structural). `ask --in frontend/`
+    // must work exactly like `--in frontend` — `scopeLabel`/the footer's own
+    // `--in <scope>/` suggestion always includes the slash, so rejecting it
+    // would make the tool's own suggested next command fail.
+    const inPrefix = opts.in ? opts.in.replace(/\/+$/, "") : undefined;
+    // `--in` validated up front, before any mode runs: a prefix matching no
+    // indexed node is a caller mistake (typo, wrong sub-project), not a
+    // legitimate zero-hit query, so it's a loud error rather than an empty pack.
+    if (inPrefix && corpus.graph && !corpus.graph.nodes.some((n) => pathUnderPrefix(n.path, inPrefix))) {
+        throw new Error(`nothing indexed under "${inPrefix}/"${scopesHereClause(scopesOfGraph(corpus.graph))} (or any path prefix)`);
+    }
     let result;
     if (corpus.graph) {
-        const outcome = structural(query, corpus.graph, limit);
+        const outcome = structural(query, corpus.graph, limit, inPrefix);
         if (outcome && "result" in outcome) {
             result = outcome.result;
         }
         else {
-            result = lexical(query, corpus, limit, graphRank);
+            result = lexical(query, corpus, limit, graphRank, inPrefix);
             // A structural-intent query that couldn't be answered structurally still
             // gets a prominent note on the lexical fallback result — never silent.
             if (outcome && "fallthroughNote" in outcome) {
@@ -501,7 +678,7 @@ export function ask(dir, query, opts = {}) {
         }
     }
     else {
-        result = lexical(query, corpus, limit, graphRank);
+        result = lexical(query, corpus, limit, graphRank, inPrefix);
     }
     if (opts.source) {
         inlineSource(root, result.hits, corpus.graph, opts.full ?? false);
@@ -592,7 +769,10 @@ export function formatAsk(r) {
     }
     else {
         r.hits.forEach((h, i) => {
-            lines.push(`${i + 1}. ${h.title}  [${h.kind}]`);
+            // Multi-scope results label each hit with its sub-project (root scope
+            // "" stays unlabeled) so a reviewer can tell WHICH codebase answered.
+            const label = r.scopes && h.scope ? `[${h.scope}/] ` : "";
+            lines.push(`${i + 1}. ${label}${h.title}  [${h.kind}]`);
             lines.push(`   ${h.pointer}`);
             if (h.snippet)
                 lines.push(`   ${h.snippet}`);
@@ -602,6 +782,7 @@ export function formatAsk(r) {
                 lines.push("", "```", h.code, "```");
             lines.push("");
         });
+        lines.push(...scopeFooterLines(r));
     }
     const body = lines.join("\n").trimEnd();
     return body + askSavingsFooter(r, body) + escalationNudge(r) + "\n";
@@ -634,4 +815,24 @@ function askSavingsFooter(r, body) {
         `${pack.toLocaleString()} tok vs reading the ${r.saved.files} source file(s) whole ≈ ` +
         `${base.toLocaleString()} tok. Estimate (baseline = those files read in full).`);
 }
+/** Multi-scope footer: answers a reviewer's two questions — "which
+ * sub-projects did this pack come from?" (`matched in:`, displayed-hit counts,
+ * biggest first) and "did anything else match that I should know about?"
+ * (`also matched:` for scopes gated out of fusion, with the flag to narrow).
+ * Empty (zero output) whenever the result isn't a federated multi-scope one. */
+function scopeFooterLines(r) {
+    if (!r.scopes)
+        return [];
+    const perScope = new Map();
+    for (const h of r.hits)
+        if (h.scope !== undefined)
+            perScope.set(h.scope, (perScope.get(h.scope) ?? 0) + 1);
+    const parts = [...perScope]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([s, c]) => `${scopeLabel(s)} (${c})`);
+    const out = parts.length ? [`matched in: ${parts.join(" · ")}`] : [];
+    for (const m of r.scopes.alsoMatched)
+        out.push(`also matched: ${scopeLabel(m.scope)} — narrow with --in ${scopeLabel(m.scope)}`);
+    return out;
+}
 //# sourceMappingURL=ask.js.map