@omfalos/mokosh 0.5.1 → 0.5.2

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { F as FileNode, C as CallEdge, I as ImportEdge, P as ParseResult, S as StructuredTag } from './types-DWARi8gF.js';
-export { E as ExportedSymbol } from './types-DWARi8gF.js';
+import { F as FileNode, C as CallEdge, I as ImportEdge, P as ParseResult, S as StructuredTag } from './types-B4jVIqMD.js';
+export { E as ExportedSymbol } from './types-B4jVIqMD.js';
 import { N as NormalizedToken } from './tokenizer-D9P-y7lH.js';
-import { F as FileType, N as NodeCategory } from './parse-yamNoaoL.js';
-export { I as ImportType, T as TagKind } from './parse-yamNoaoL.js';
+import { F as FileType, N as NodeCategory, T as TagKind } from './parse-yamNoaoL.js';
+export { I as ImportType } from './parse-yamNoaoL.js';
 
 interface SerializedGraph {
     nodes: FileNode[];
@@ -30,6 +30,9 @@ type CycleEdgeKind = "docReference" | "samePackage";
 interface FindCyclesOptions {
     /** Edge kinds to include in the walk that are otherwise skipped (see {@link CycleEdgeKind}). */
     includeKinds?: CycleEdgeKind[] | undefined;
+    /** When true, return every raw elementary cycle instead of collapsing cycles that share a
+     *  strongly-connected component to one representative each. Default false. */
+    expandComponents?: boolean | undefined;
 }
 /**
  * @description Utility for analyzing the dependency graph for cycles and unused files.
@@ -61,15 +64,55 @@ declare class GraphAnalyzer {
         maxExportUsage: number;
         tightestDep: string;
     }>;
+    /**
+     * @description The structural-import targets of `nodePath` — the outgoing edges a cycle walk
+     *   follows. Excludes unresolved (`!toPath`) and external edges always, and by default the two
+     *   non-`import` synthetic edge kinds: the JVM same-package sibling clique (`isSamePackage`) and
+     *   Markdown link / code-span file references (`isDocReference`, ADR-009). Both are opt-in via
+     *   `include`. Shared by {@link findCycles}' DFS and its strongly-connected-component pass so
+     *   the two agree on exactly which edges exist.
+     * @param nodePath - The file whose outgoing edges to resolve.
+     * @param include - Edge kinds to walk that are otherwise skipped.
+     * @returns Deduplicated target paths, in first-seen order.
+     */
+    private traversableTargets;
     /**
      * @description Detects all circular import chains using DFS with a recursion-stack back-edge check.
      *   Each returned array is one cycle as an ordered list of file paths ending at the entry that closes the loop.
      *   Non-import edge kinds — the synthetic JVM same-package clique and Markdown doc references
      *   (ADR-009) — are skipped by default; pass `includeKinds` to walk them anyway.
-     * @param {FindCyclesOptions} [opts] - `includeKinds` opts specific edge kinds back into the walk.
+     *
+     *   Cycles that share a strongly-connected component are collapsed to one representative each
+     *   (the shortest, ties broken lexicographically). A single hub file cyclically bound to N
+     *   siblings — e.g. `ItemList.tsx` importing four `*CellRenderer.tsx` that each import a type
+     *   back from it — is one dependency knot to untangle, not N findings; the DFS otherwise emits
+     *   one back-edge cycle per sibling. Pass `expandComponents` to get every raw elementary cycle
+     *   instead.
+     * @param {FindCyclesOptions} [opts] - `includeKinds` opts specific edge kinds back into the
+     *   walk; `expandComponents` disables the same-component collapse.
      * @returns {string[][]} Array of cycles; each cycle is an ordered list of file paths forming a loop.
      */
     findCycles(opts?: FindCyclesOptions): string[][];
+    /**
+     * @description Collapses `cycles` so that every strongly-connected component contributes at
+     *   most one — its shortest cycle, ties broken by the joined path string for determinism.
+     *   Every elementary cycle lies wholly within one SCC, so cycles are grouped by the SCC id of
+     *   any member; a graph with no repeated-SCC cycles passes through unchanged (order preserved
+     *   by first appearance).
+     * @param cycles - Raw elementary cycles from the DFS.
+     * @param include - Edge kinds in scope, so the SCC pass walks the same edges the DFS did.
+     * @returns One representative cycle per SCC that had any, in first-appearance order.
+     */
+    private collapseByComponent;
+    /**
+     * @description Tarjan's strongly-connected-components over the cycle-walk edge set, restricted
+     *   to nodes that sit in a component of size ≥ 2 (the only ones that can be on a cycle). Runs
+     *   iteratively — the graphs this analyzes reach tens of thousands of nodes, past a safe
+     *   recursion depth.
+     * @param include - Edge kinds to walk, matching {@link traversableTargets}.
+     * @returns Map from file path to a numeric component id, only for nodes in a non-trivial SCC.
+     */
+    private componentIds;
 }
 
 /** Graph class wrapping the raw node map with DFS traversal, cycle detection, serialization, and reverse-edge helpers. */
@@ -242,6 +285,16 @@ interface MokoshConfig {
          */
         frameworkOverrides?: Record<string, TagFramework>;
     };
+    /**
+     * Tunes which tags count as test-selection labels for `propose_tags`, `apply_tags`,
+     * `list_tags` (default view) and the `tag:` query filter. Both lists are case-insensitive.
+     */
+    tags?: {
+        /** Tag names to treat as noise, added to the built-in curated blocklist. */
+        blocklist?: string[];
+        /** Tag names to keep even when built-in- or user-blocked (overrides `blocklist`). */
+        allowlist?: string[];
+    };
     /** Path to the Istanbul/v8 `coverage-summary.json` file, relative to the project root. When set, `coveragePct` is populated on each node after the graph is built. */
     coverageReportPath?: string;
     /** Default line-coverage threshold (0–100) used by `find_uncovered`. Defaults to `80` when not specified. */
@@ -267,6 +320,26 @@ interface MokoshConfig {
         /** When true, scan generated / vendored files too (default false). Matches involving one are
          *  tagged `signals: ["generated"]`. */
         includeGenerated?: boolean;
+        /** When true, include matches where every occurrence is in a single file (default false) —
+         *  a file's own naturally repetitive structure is usually not actionable copy-paste. Matches
+         *  are always tagged `signals: ["same-file"]` regardless of this setting. */
+        includeSameFile?: boolean;
+        /** When true, include matches whose occurrences are all inline SVG / SVG-shaped JSX markup
+         *  (default false) — two different icons sharing a literal-normalized skeleton (block matcher)
+         *  or a byte-identical `<defs>`/`<filter>` block (`defKind: "jsxElement"`), neither of which is
+         *  usually an authored clone. Matches are always tagged `signals: ["svg-markup"]` regardless
+         *  of this setting. */
+        includeSvgMarkup?: boolean;
+        /** When true, include matches in the `markdown` family (default false) — mirrored prose
+         *  docs (README ↔ *.mdx) are not code duplication. Matches are always tagged
+         *  `signals: ["docs"]` regardless. */
+        includeDocs?: boolean;
+        /** Which duplicates to surface, by test-file involvement (default `"src"`). `"src"` drops
+         *  every cluster with a test-file occurrence; `"tests"` returns only substantive test
+         *  clusters (shared setup/mocks/assertions, not render/snapshot skeletons); `"all"` returns
+         *  everything. The `--scope` CLI flag overrides this. Matches are always tagged
+         *  `signals: ["test"]` regardless of this setting. */
+        scope?: "src" | "tests" | "all";
     };
 }
 /**
@@ -314,15 +387,40 @@ declare function configToGraphOptions(config: MokoshConfig | undefined): {
 declare const DEFAULT_CACHE_DIR = "mokosh-cache";
 /** Filename for the disk-persisted `find_duplicates` token cache within `DEFAULT_CACHE_DIR`. */
 declare const DEFAULT_DUPLICATION_TOKEN_CACHE_FILE = "duplication-tokens.json";
+/** Filename for the disk-persisted `find_duplicates` *result* cache within `DEFAULT_CACHE_DIR`
+ *  (or, on a monorepo, `<pkg-slug>-duplication-result.json` per package). Holds the full
+ *  `{ groups, clusters }` from the last scan, keyed by a digest of every in-scope file's
+ *  mtime/size plus the output-affecting scan params — a match lets a repeat call skip the scan
+ *  entirely. See `src/graph/duplication/result-cache-store.ts`. */
+declare const DEFAULT_DUPLICATION_RESULT_CACHE_FILE = "duplication-result.json";
 /** Filename for the disk-persisted graph cache within `DEFAULT_CACHE_DIR`. Written by the CLI
  *  (`src/cli/graph-loader.ts`) after every build; read by the MCP server (`src/mcp/cache.ts`) to
  *  seed a session's first `analyze` call so it reuses unchanged nodes instead of parsing cold. */
 declare const DEFAULT_GRAPH_CACHE_FILE = "graph.json";
-/** Filename for the disk-persisted *workspace* (monorepo) graph cache within `DEFAULT_CACHE_DIR`.
- *  Written by the MCP server (`src/mcp/cache.ts`) after a `createWorkspaceGraph` build and hydrated
- *  on the next session's first workspace query when the source-file digest still matches — so
- *  repeat sessions against an unchanged monorepo skip the full per-package rebuild. */
+/** Legacy filename for the single-blob disk-persisted *workspace* (monorepo) graph cache within
+ *  `DEFAULT_CACHE_DIR`. Superseded by `DEFAULT_WORKSPACE_CACHE_SUBDIR` (a manifest plus one file
+ *  per package) — retained only so `src/graph/workspace/disk-cache.ts` can unlink a stale copy
+ *  left by an older mokosh. A 190 MB+ single file here was `JSON.parse`d whole and OOM-killed the
+ *  MCP server; see the manifest layout below. */
 declare const DEFAULT_WORKSPACE_GRAPH_CACHE_FILE = "workspace-graph.json";
+/** Subdirectory of `DEFAULT_CACHE_DIR` holding the workspace graph cache as a `manifest.json`
+ *  ("the map file") plus one `<pkg-slug>.json` per package. Each package file is parsed on its
+ *  own, so peak memory on hydrate is bounded by the largest single package rather than the whole
+ *  serialized workspace. Written/read by `src/graph/workspace/disk-cache.ts`, driven from
+ *  `src/mcp/cache.ts`. */
+declare const DEFAULT_WORKSPACE_CACHE_SUBDIR = "workspace";
+/** Filename of the workspace cache manifest within `DEFAULT_WORKSPACE_CACHE_SUBDIR`: the small
+ *  index that carries the layout, the root (non-package-owned) source digest, and one entry per
+ *  package (name, relative root, entry points, per-package digest, node count, cache filename). */
+declare const WORKSPACE_MANIFEST_FILE = "manifest.json";
+/** Schema version stamped into the workspace cache manifest. A mismatch on read discards the
+ *  whole cache (full rebuild) — bump this whenever the serialized `FileNode` shape or the
+ *  manifest structure changes incompatibly. */
+declare const WORKSPACE_CACHE_VERSION = 1;
+/** A single package whose serialized node array exceeds this is not written to the workspace
+ *  cache (and never read back) — that package always rebuilds. Keeps any one per-package
+ *  `JSON.parse` on hydrate within a safe memory envelope. */
+declare const MAX_PACKAGE_CACHE_BYTES: number;
 /** Subdirectory of `DEFAULT_CACHE_DIR` holding one JSON file per commit sha — graphs built for
  *  the "other" ref in a `compareBranches` call (`src/graph/branch-graph-cache.ts`). Keyed by sha
  *  rather than branch name so entries are immutable and never need invalidation. */
@@ -391,6 +489,57 @@ interface ApiSurface {
      */
     testFiles: string[];
 }
+/**
+ * A compact, token-bounded projection of an {@link ApiSurface}, suitable as the default
+ * response of a "what's the public API?" query. Every unbounded list in `ApiSurface` is
+ * replaced by a count; `publicExports` is reduced to a capped `{ name, kind }` sample plus a
+ * `byKind` histogram over the full set. `unreachableFromEntry` — the one directly actionable
+ * signal (missed entry points / dead code) — keeps its list, capped.
+ */
+interface ApiSurfaceSummary {
+    /** Entry points, capped (see `entryPointsTruncated`). */
+    entryPoints: string[];
+    /** True number of entry points. */
+    entryPointCount: number;
+    /** Present and `true` when `entryPoints` was truncated. */
+    entryPointsTruncated?: true;
+    /** True number of accessible public exports. */
+    publicExportCount: number;
+    /** Capped `{ name, kind }` sample of the public exports, alphabetical. */
+    publicExports: Array<{
+        name: string;
+        kind: ExportKind;
+    }>;
+    /** Present and `true` when `publicExports` was truncated. */
+    publicExportsTruncated?: true;
+    /** Count of public exports per {@link ExportKind}, over the full (un-capped) set. */
+    byKind: Partial<Record<ExportKind, number>>;
+    /** Number of non-test implementation files reachable from an entry point. */
+    internalFileCount: number;
+    /** Number of non-test files not reachable from any entry point. */
+    unreachableFromEntryCount: number;
+    /** The unreachable non-test files, capped (see `unreachableFromEntryTruncated`). */
+    unreachableFromEntry: string[];
+    /** Present and `true` when `unreachableFromEntry` was truncated. */
+    unreachableFromEntryTruncated?: true;
+    /** Number of unreachable test files. */
+    testFileCount: number;
+    /** How to obtain the full lists this summary omits. */
+    hint: string;
+}
+/**
+ * Reduces a full {@link ApiSurface} to a token-bounded {@link ApiSurfaceSummary}.
+ *
+ * @param {ApiSurface} surface - The full surface report from {@link buildApiSurface}.
+ * @param {{ maxExports?: number; maxUnreachable?: number }} [opts] - `maxExports` caps the
+ *   `publicExports` sample (default 30; pass `Infinity` to keep all names); `maxUnreachable`
+ *   caps the `unreachableFromEntry` list (default 50).
+ * @returns {ApiSurfaceSummary} The compact projection.
+ */
+declare function summarizeApiSurface(surface: ApiSurface, opts?: {
+    maxExports?: number;
+    maxUnreachable?: number;
+}): ApiSurfaceSummary;
 /**
  * Attempts to auto-detect the primary public entry point by reading `package.json` from `root`.
  * Handles modern conditional-exports objects as well as plain `main`/`module` fields.
@@ -544,17 +693,27 @@ declare function loadChangeImpactCache(cachePath: string): ChangeImpactCache | n
 
 /**
  * Language-family partitioning for duplicate detection. `findDuplicates` never compares files
- * across a family boundary — see docs/adr-013-duplicate-detection-noise-reduction.md. The
- * immediate driver is CSS-family declarations: they share a small, finite vocabulary (property
+ * across a family boundary — see docs/adr-013-duplicate-detection-noise-reduction.md.
+ *
+ * The original driver was CSS: style declarations share a small, finite vocabulary (property
  * names, common value keywords) that the shared `KEYWORDS` denylist in `tokenizer.ts` doesn't
- * cover, so unrelated style rules with the same declaration *shape* but different selectors/
- * properties/values were hashing identically to unrelated TS/JS/Python shapes too. Splitting by
- * family also lets later phases tune `windowSize`/`minLines`/vocabulary per family without one
- * family's tuning affecting another's.
+ * cover, so unrelated rules with the same declaration *shape* hashed identically to unrelated
+ * code shapes. The same argument applies, more weakly, *within* code: Java, Go, and TS/JS all use
+ * C-style `if (…) { … }` / `for (…; …; …)` blocks, so a `for` loop that pushes onto a list
+ * tokenizes almost identically in all three once identifiers collapse to `ID` — a polyglot repo
+ * then reports phantom control-flow "duplicates" across languages that share nothing. So code is
+ * split by paradigm too, not lumped into one family.
+ *
+ * Grouping (not one family per `FileType`) is deliberate: JavaScript↔TypeScript and
+ * CoffeeScript/LiveScript→JavaScript ports are real, common, cross-`FileType` duplication worth
+ * detecting, so those languages share the `"js"` family. The JVM languages interoperate and share
+ * idioms, so they share `"jvm"` — and, being their own family, never match against `"js"`, which
+ * is the case that motivated this split. Splitting by family also lets later phases tune
+ * `windowSize`/`minLines`/vocabulary per family without one family's tuning affecting another's.
  */
 
 /** One partition of `findDuplicates` matching — files in different families are never compared. */
-type DuplicateFamily = "style" | "code";
+type DuplicateFamily = "style" | "js" | "jvm" | "python" | "go" | "lua" | "markdown" | "gherkin" | "other";
 
 /**
  * Sliding-window (shingle) hashing over a normalized token stream, plus chain-merging of
@@ -572,14 +731,32 @@ interface DuplicateOccurrence {
     file: string;
     startLine: number;
     endLine: number;
+    /** The variable/type name declared at this location. Set only on `kind: "definition"` groups
+     *  (`style-vars.ts`, `type-defs.ts`) — block matches have no single declared name. */
+    name?: string | undefined;
+    /** This occurrence's own normalized value. Set only on `defKind: "cssVar"` groups tagged
+     *  `signals: ["value-drift"]`, where occurrences disagree and the value itself is the point. */
+    value?: string | undefined;
 }
 /**
  * Advisory tags on a {@link DuplicateGroup} that help a caller (and issue 6's query layer) judge
  * whether a match is worth acting on: `"same-file"` — every occurrence is in one file (an
  * internally repeated block); `"generated"` — at least one occurrence is in a file only scanned
- * because `includeGenerated: true` was passed. Designed to grow (issue 7 adds more).
- */
-type DuplicateSignal = "same-file" | "generated";
+ * because `includeGenerated: true` was passed; `"value-drift"` — a `defKind: "cssVar"` group
+ * where the same variable *name* holds different values across files (as opposed to the default
+ * consolidation case: different names, same value); `"svg-markup"` — every occurrence's source
+ * span is predominantly inline SVG / SVG-shaped JSX markup (a block match where two *different*
+ * icons share a literal-normalized skeleton, or a `defKind: "jsxElement"` match on an identical
+ * `<defs>`/`<filter>` block — see `svg-markup.ts`); `"test"` — at least one occurrence is in a
+ * test file (`__tests__/`, `__mocks__/`, `*.test.*`, `*.spec.*`, `__snapshots__/`); `"docs"` —
+ * the group is in the `markdown` family (mirrored prose docs, `README.md` ↔ `*.mdx`).
+ * `"same-file"`, `"svg-markup"` and `"docs"` groups are excluded from `findDuplicates`' results
+ * by default (opt back in with `includeSameFile` / `includeSvgMarkup` / `includeDocs`); `"test"`
+ * groups are filtered by the `scope` option (see `findDuplicates`), which separates substantive
+ * shared test logic from render/snapshot skeletons. The tag is always attached regardless of any
+ * filter. Designed to grow (issue 7 adds more).
+ */
+type DuplicateSignal = "same-file" | "generated" | "value-drift" | "svg-markup" | "test" | "docs";
 interface DuplicateGroup {
     /** Every location sharing this duplicated block (two or more) — locations that pairwise
      *  chain-match are clustered into one group instead of being reported once per pair, so a
@@ -587,10 +764,20 @@ interface DuplicateGroup {
     occurrences: DuplicateOccurrence[];
     /** Line span of the largest single pairwise match clustered into this group (each pair's own
      *  span is the shorter of its two occurrences) — the best-verified size for this block, not an
-     *  average or a value shrunk by a more weakly-matching cluster member. */
+     *  average or a value shrunk by a more weakly-matching cluster member. For `kind: "definition"`
+     *  groups this is the declaration's own line span instead (1 for a single-line `cssVar` decl). */
     lines: number;
-    /** Token-window length backing this block, after chain-merging adjacent windows. */
+    /** Token-window length backing this block, after chain-merging adjacent windows. For
+     *  `kind: "definition"` groups this is the member/field count instead (1 for `cssVar`). */
     tokens: number;
+    /** Count of *logic-bearing* tokens (keywords + operators, not `ID`/`NUM`/`STR`/punctuation —
+     *  see {@link isSignificantToken}) in the verified span. `findDuplicates` ranks and (with
+     *  `minScore`) filters on this so a large low-information block — a Flow `type Props`, a JSX
+     *  icon wrapper, a schema object literal — no longer outranks real shared logic. Set on
+     *  `kind: "block"` groups by `suffix-duplicates.ts`; absent on `kind: "definition"` groups
+     *  (already content-verified) — those are ranked by `lines` instead. See
+     *  docs/adr-019-logic-token-scoring.md. */
+    score?: number | undefined;
     /** Which language family both occurrences belong to (set by `findDuplicates`, which never
      *  matches across families — see docs/adr-013-duplicate-detection-noise-reduction.md).
      *  Absent when called directly with a token stream that isn't family-scoped, e.g. in tests. */
@@ -598,6 +785,84 @@ interface DuplicateGroup {
     /** Advisory tags for filtering — see {@link DuplicateSignal}. Absent (not `[]`) when no
      *  signal applies. */
     signals?: DuplicateSignal[] | undefined;
+    /** `"block"` (the default, and absent on every group predating this field) is a token/structural
+     *  match over a span of code; `"definition"` is a declaration-level match — see `defKind`. */
+    kind?: "block" | "definition" | undefined;
+    /** What kind of declaration a `kind: "definition"` group matched on. Absent for `kind: "block"`
+     *  (or absent-`kind`) groups. */
+    defKind?: "cssVar" | "interface" | "type" | "objectLiteral" | "jsxElement" | undefined;
+}
+
+/**
+ * Groups `DuplicateGroup`s that share the exact same set of files into one `DuplicateCluster`,
+ * addressing the "window-splitting" noise class `applyDominanceFilter` (suffix-duplicates.ts)
+ * deliberately doesn't touch: two files that share several genuinely non-nested matches (different
+ * start positions, no containment relationship — see
+ * docs/adr-015-suffix-array-duplicate-detection.md's addendum) still surface as one `DuplicateGroup`
+ * per match, so a single real duplication between two files can legitimately report a dozen-plus
+ * rows. A file pair matched by 14 separate groups (same two files, non-nested spans) becomes one
+ * cluster with `matchCount: 14` instead of 14 rows a caller has to manually recognize as "the same
+ * underlying duplication" — the `ContentExplorer.tsx`/`ContentPicker.js` case from the dogfooding
+ * report this responds to.
+ *
+ * **This module previously clustered by connected file-component (union-find: any two files that
+ * co-occur in some group's occurrences are connected, transitively) instead of exact file-set
+ * equality, and that was wrong — caught by a follow-up dogfood pass before anyone relied on it.**
+ * Connected-component clustering is single-linkage clustering, and single-linkage is notorious for
+ * "chaining": on a real repo, one file sharing a single incidental block each with dozens of
+ * otherwise-unrelated files is enough to transitively merge all of them into one cluster, since
+ * connectivity only ever needs one bridge edge, never a strong one. Confirmed in practice on a
+ * production monorepo: 803 files and 4,853 groups collapsed into a single "cluster" — a regression,
+ * not a summary, and strictly less useful than the flat `groups` list it was meant to compress.
+ * Exact file-set equality can't chain this way: a group between `{A, B}` and a group between
+ * `{B, C}` (B is a genuine bridge — it duplicates code with both, but that doesn't mean A and C
+ * relate to each other) land in two separate clusters, not one, because their occurrence sets
+ * differ. The trade-off this accepts: a true N-way clone family reported as several exact-N-way
+ * groups already merges correctly (same set every time); one reported as several *different-sized*
+ * subsets (a 3-file match here, a 2-file subset of it there) does not merge into one cluster. That
+ * residual case is deliberately left alone rather than resolved with more graph theory — a
+ * conservative under-merge is a far safer default than the chaining failure mode above.
+ *
+ * **Coverage.** `matchCount: 14` still reads as "14 things," not "one relationship" — the same
+ * gap SonarQube's duplication check closes by reporting a merged duplication-*density* percentage
+ * per file instead of an enumerated match list. {@link DuplicateCluster.coverage} does the same
+ * here: union each cluster's occurrence spans per file (so overlapping/adjacent sub-matches count
+ * once, not once each) and divide by that file's total line count — turning
+ * `matchCount: 14, files: ["ContentExplorer.tsx", "ContentPicker.js"]` into
+ * `"ContentExplorer.tsx: 62% (312/501 lines) duplicated with ContentPicker.js"`, which is a much
+ * more decisive triage signal than the match count alone: high coverage on both sides says "these
+ * are near-duplicate files," low coverage says "one shared helper embedded in two otherwise-
+ * unrelated files."
+ */
+
+interface DuplicateClusterFileCoverage {
+    file: string;
+    /** Total lines this cluster's occurrences cover in `file`, after merging overlapping/adjacent
+     *  spans across every group in the cluster — never double-counts a line two groups both touch. */
+    coveredLines: number;
+    /** `file`'s total line count, when known (the caller passed `fileLineCounts` and had an entry
+     *  for it) — `undefined` otherwise, e.g. a cache-hit file scanned without re-reading its source. */
+    totalLines: number | undefined;
+    /** `coveredLines / totalLines * 100`, rounded to one decimal place — `undefined` when
+     *  `totalLines` isn't known or is 0. */
+    coveragePct: number | undefined;
+}
+interface DuplicateCluster {
+    /** The exact set of files every group in this cluster shares occurrences in, sorted. */
+    files: string[];
+    /** This cluster's member groups, largest-`lines`-first — the same `DuplicateGroup` objects
+     *  `findDuplicates` would otherwise report standalone, unmodified. */
+    groups: DuplicateGroup[];
+    /** `groups.length` — how many separate matches this cluster bundles. A cluster with
+     *  `matchCount: 1` is just a single group reported through the same shape for consistency. */
+    matchCount: number;
+    /** The largest `lines` value across this cluster's groups — the single best-verified size for
+     *  "how big is this duplication," independent of how many rows it fragmented into. */
+    longestMatch: number;
+    /** Per-file duplication coverage, same order as `files` — see this module's top-of-file
+     *  comment. Every entry has `coveredLines`; `totalLines`/`coveragePct` are only present when
+     *  `buildDuplicateClusters` was given a line count for that file. */
+    coverage: DuplicateClusterFileCoverage[];
 }
 
 /** One file's cached tokenize result, fingerprinted by `mtime`/`size`/`ignoreLiterals` — any
@@ -658,6 +923,156 @@ declare function isGeneratedPath(relPath: string, ignoreGlobs?: readonly string[
  */
 declare function hasGeneratedMarker(source: string): boolean;
 
+/** The output-affecting `findDuplicates` knobs — everything that changes which groups/clusters
+ *  the scan produces. Folded into the cache key via {@link duplicationResultCacheKey}; a
+ *  mismatch is a cache miss. `filter` is deliberately absent — the cache only ever holds an
+ *  unfiltered scan. Any new output-affecting option wired into `findDuplicates` (e.g. a future
+ *  `minScore`) must be added here too, or a run that changes it will read a stale result. */
+interface DuplicationResultParams {
+    minLines: number;
+    ignoreLiterals: boolean;
+    maxPunctuationRatio: number;
+    /** The per-scan cap passed to `findDuplicates` — the stored result holds at most this many
+     *  groups per package, so a later run wanting more must re-scan. */
+    limit: number;
+    scope: string | undefined;
+    includeGenerated: boolean;
+    includeSameFile: boolean;
+    includeSvgMarkup: boolean;
+    includeDocs: boolean;
+    ignoreDirs: string[];
+    ignoreGlobs: string[];
+}
+interface CachedDuplicationResult {
+    /** {@link duplicationDigest} of the in-scope files at write time. */
+    digest: string;
+    /** {@link duplicationResultCacheKey} of the scan params at write time. */
+    paramsKey: string;
+    groups: DuplicateGroup[];
+    clusters: DuplicateCluster[];
+}
+/**
+ * @description One `path\0mtime\0size` line per node, sha256'd over the sorted set — the same
+ *   unit `computeWorkspaceSourceDigest` (`src/index.ts`) hashes, but sourced from the in-memory
+ *   graph (every `FileNode` already carries `mtime`/`size`) so no `fs.stat` walk is needed.
+ *   Passing the whole node set (a superset of what `findDuplicates` actually scans) is
+ *   intentional: an out-of-scope change over-invalidates, which is safe.
+ * @param {Iterable<{ path: string; mtime: number; size: number }>} nodes - Graph file nodes.
+ * @returns {string} Hex sha-256 digest.
+ */
+declare function duplicationDigest(nodes: Iterable<{
+    path: string;
+    mtime: number;
+    size: number;
+}>): string;
+/**
+ * @description Stable string form of the scan params for the cache key — keys emitted in a fixed
+ *   order, arrays sorted — so equivalent params always produce the same string regardless of how
+ *   the caller assembled them.
+ * @param {DuplicationResultParams} params - The output-affecting scan knobs.
+ * @returns {string} A canonical JSON string to compare byte-for-byte.
+ */
+declare function duplicationResultCacheKey(params: DuplicationResultParams): string;
+/**
+ * @description Reads a `CachedDuplicationResult` written by {@link saveDuplicationResult} and
+ *   returns its `{ groups, clusters }` only when the stored `digest` and `paramsKey` both still
+ *   match — i.e. no in-scope file changed and the scan params are identical. Any other outcome
+ *   (missing file, corrupt JSON, wrong shape, stale digest, different params) returns `null`,
+ *   which the caller treats as "run the scan". Never throws.
+ * @param {string} cachePath - Path to the JSON file written by `saveDuplicationResult`.
+ * @param {string} digest - The current {@link duplicationDigest} to validate against.
+ * @param {string} paramsKey - The current {@link duplicationResultCacheKey} to validate against.
+ * @returns {{ groups: DuplicateGroup[]; clusters: DuplicateCluster[] } | null} The cached result,
+ *   or `null` on any miss.
+ */
+declare function loadDuplicationResult(cachePath: string, digest: string, paramsKey: string): {
+    groups: DuplicateGroup[];
+    clusters: DuplicateCluster[];
+} | null;
+/**
+ * @description Serializes the full scan result to `cachePath` (creating parent dirs), stamped
+ *   with the `digest` / `paramsKey` it is valid for. A write failure is logged to stderr and
+ *   otherwise swallowed — the result cache is pure acceleration and must never fail the call
+ *   that produced it.
+ * @param {string} cachePath - Destination path; parent directories are created automatically.
+ * @param {string} digest - The {@link duplicationDigest} this result was computed against.
+ * @param {string} paramsKey - The {@link duplicationResultCacheKey} this result was computed
+ *   against.
+ * @param {readonly DuplicateGroup[]} groups - The full pre-`limit` group list from the scan.
+ * @param {readonly DuplicateCluster[]} clusters - The full cluster list from the scan.
+ * @returns {void}
+ */
+declare function saveDuplicationResult(cachePath: string, digest: string, paramsKey: string, groups: readonly DuplicateGroup[], clusters: readonly DuplicateCluster[]): void;
+
+/**
+ * Response-shaping helpers shared by the `find_duplicates` MCP handler and the `--find-duplicates`
+ * CLI command: a triage-first `summary` block and the compact ("slim") group/cluster projections.
+ * Kept separate from `index.ts` (the scan) and `dup-filter.ts` (the predicate) so both consumers
+ * present duplicate results identically.
+ */
+
+/** First path segment of a project-relative path (`"packages/app/x.ts"` -> `"packages"`), or
+ *  `"."` when the file sits at the repo root — the bucket key for `summary.byTopDir`. */
+declare function topDir(relPath: string): string;
+/** The triage-first `summary` block. */
+interface DuplicatesSummary {
+    /** How many groups matched (post-`filter`, before any response `limit`). A lower bound when a
+     *  per-package scan cap clipped on a very large monorepo; exact otherwise. */
+    matched: number;
+    /** Group count per language `family`. */
+    byFamily: Record<string, number>;
+    /** Group count per top-level directory — a group touching two dirs counts in both. */
+    byTopDir: Record<string, number>;
+    /** Occurrence-signal frequency across the matched groups. */
+    bySignal: Record<string, number>;
+    /** Largest `lines` value among the matched groups. */
+    largestLines: number;
+    /** Only set on a `view: "full"` response: how many groups were dropped from the returned
+     *  `groups` list because a returned multi-member cluster already represents them (see
+     *  {@link dedupeGroupsAgainstClusters}). */
+    clusteredGroups?: number;
+}
+/**
+ * @description Drops from `groups` every group that is a member of a multi-member cluster in
+ *   `clusters` — that cluster already represents it (with a better signal: per-file `coverage`),
+ *   so returning both is redundant. Groups whose file pair matched only once (no multi-member
+ *   cluster) are kept. Used only for the `view: "full"` response, the one path that returns both
+ *   lists.
+ * @param {readonly DuplicateGroup[]} groups - The ordered, pre-`limit` group list.
+ * @param {readonly DuplicateCluster[]} clusters - The clusters that will be returned alongside.
+ * @returns {DuplicateGroup[]} `groups` minus the ones folded into a returned multi-member cluster.
+ */
+declare function dedupeGroupsAgainstClusters(groups: readonly DuplicateGroup[], clusters: readonly DuplicateCluster[]): DuplicateGroup[];
+/**
+ * @description Builds the {@link DuplicatesSummary} for a `find_duplicates` response — the counts
+ *   a caller reads once to decide which targeted `filter` call to make next, without pulling the
+ *   full group list.
+ * @param {readonly DuplicateGroup[]} groups - Every group that survived the `filter` predicate,
+ *   before the response `limit` truncates the list.
+ * @returns {DuplicatesSummary} The aggregate counts.
+ */
+declare function summarizeDuplicates(groups: readonly DuplicateGroup[]): DuplicatesSummary;
+/** Compact `["path:startLine-endLine", …]` rendering of a group's occurrences. */
+declare function slimOccurrences(group: DuplicateGroup): string[];
+/**
+ * @description Slim per-group projection: size / score / classification / signals plus
+ *   `"path:start-end"` occurrence strings — no duplicated source text, no per-occurrence
+ *   metadata objects. Preserves a `package` field when `findDuplicates`' caller tagged one.
+ * @param {DuplicateGroup} group - A finalized duplicate group.
+ * @returns {Record<string, unknown>} The compact object.
+ */
+declare function slimDupGroup(group: DuplicateGroup): Record<string, unknown>;
+/**
+ * @description Slim per-cluster projection: the file set, match count, best-verified size,
+ *   per-file coverage, and the `"path:start-end"` span of the cluster's longest match — without
+ *   the nested member-group bodies. `longestMatchAt` is what makes a slim cluster actionable on
+ *   its own: it answers "where do I look" without the caller also pulling the `groups` list.
+ * @param {DuplicateCluster} cluster - A built cluster. `cluster.groups` is largest-`lines`-first
+ *   (see `buildDuplicateClusters`), so `groups[0]` is the longest match.
+ * @returns {Record<string, unknown>} The compact object.
+ */
+declare function slimDupCluster(cluster: DuplicateCluster): Record<string, unknown>;
+
 /** Configures whether/how tokenizing is offloaded to a `piscina` worker pool. `false` always
  *  tokenizes in-process. */
 type ParallelTokenizingOption = boolean | {
@@ -691,6 +1106,52 @@ interface FindDuplicatesOptions {
      *  actionable copy-paste. Set true to scan them anyway; matches involving one are tagged
      *  `signals: ["generated"]`. See docs/adr-013-duplicate-detection-noise-reduction.md. */
     includeGenerated?: boolean | undefined;
+    /** When false (default), skip matches where every occurrence is in a single file — a file's
+     *  own naturally repetitive structure (a long class with many similar methods, a Markdown doc
+     *  table, a big object literal) shows up as "duplicating itself" far more often than it
+     *  represents an actionable copy-paste bug. Dogfooding found this was the single largest noise
+     *  class in `groups` (32% in one measurement). Set true to see them anyway; they're always
+     *  tagged `signals: ["same-file"]` regardless of this flag, so a caller already relying on that
+     *  tag to filter manually is unaffected either way. Mirrors `includeGenerated`'s
+     *  default-off/opt-in-back-in shape. */
+    includeSameFile?: boolean | undefined;
+    /** When false (default), skip matches where every occurrence's source span is predominantly
+     *  inline SVG / SVG-shaped JSX markup. Two mechanisms produce these: the token-shingle block
+     *  matcher (under the default `ignoreLiterals: true` the `d=` path string and filter constants
+     *  that actually tell two icons apart normalize to a placeholder, so *different* icons
+     *  token-match on their shared skeleton), and the `defKind: "jsxElement"` detector (two icons
+     *  sharing a byte-identical `<defs>`/`<filter>` block — boilerplate, not an authored clone).
+     *  Both are excluded here. Set true to see them anyway; they're always tagged
+     *  `signals: ["svg-markup"]` regardless. Mirrors `includeSameFile`'s default-off/opt-in shape.
+     *  See `svg-markup.ts`. */
+    includeSvgMarkup?: boolean | undefined;
+    /** When false (default), skip matches in the `markdown` family — prose docs (`README.md` ↔
+     *  `*.mdx`, `*.md` ↔ `*.md`) that mirror each other are not code duplication, and their
+     *  fenced code blocks tokenize densely enough to top the score-ranked list. Set true to see
+     *  them anyway; they're always tagged `signals: ["docs"]` regardless. Mirrors
+     *  `includeSameFile`'s default-off/opt-in shape. */
+    includeDocs?: boolean | undefined;
+    /** Minimum logic-token score (keywords + operators in the verified span — see
+     *  {@link significantTokenCount}) for a `kind: "block"` match to be reported. Default `0`
+     *  (off): every match is still returned, but `groups` and `clusters` are now *ranked* by score
+     *  regardless. A positive value drops boilerplate-shaped blocks — a Flow `type Props`, a JSX
+     *  icon-component wrapper, a schema object literal all score in the single digits; a real
+     *  30-line function scores 25–40. Never filters `kind: "definition"` groups (already
+     *  content-verified). See docs/adr-019-logic-token-scoring.md. */
+    minScore?: number | undefined;
+    /** Which duplicates to surface, by whether test files are involved (default `"src"`). A group
+     *  with any occurrence in a test file (`__tests__/`, `__mocks__/`, `*.test.*`, `*.spec.*`,
+     *  `__snapshots__/`) is always tagged `signals: ["test"]`; this option decides which of those
+     *  reach `groups`/`clusters`:
+     *  - `"src"` (default) — drop every cluster that has a test-file occurrence. Auditing product
+     *    code shouldn't be buried under `render(<Icon/>); expect(…).toMatchSnapshot()` repeated
+     *    across hundreds of icon tests.
+     *  - `"tests"` — surface *only* test clusters, and only the substantive ones: a cluster with
+     *    ≥ {@link TEST_SUBSTANTIVE_BLOCKS} distinct shared blocks across ≤ {@link
+     *    TEST_SUBSTANTIVE_MAX_FILES} files, or one block ≥ {@link TEST_SUBSTANTIVE_TOKENS} tokens —
+     *    i.e. shared setup / mocks / assertions worth a helper, not a one-block render skeleton.
+     *  - `"all"` — every cluster, test or not, subject only to the other filters. */
+    scope?: "src" | "tests" | "all" | undefined;
     /** Extra generated-file patterns merged with the built-in list (from
      *  `MokoshConfig.duplication.ignoreGlobs`). Two shapes only — `**​/name/**` (path segment) and
      *  `*.suffix` (basename) — not full glob syntax. */
@@ -705,10 +1166,33 @@ interface FindDuplicatesOptions {
      *  call's) skip tokenizing entirely. Mutated in place; omit for one-shot callers (e.g. the CLI).
      *  See {@link DuplicationTokenCache} and docs/adr-014-duplicate-detection-scale.md. */
     tokenCache?: DuplicationTokenCache | undefined;
+    /** Optional `key:value` result filter (see `src/query/dup-parser.ts` / `DuplicateQuery`).
+     *  Applied as a per-group predicate *before* clustering, so `clusters` stay consistent with the
+     *  narrowed `groups`. Only the predicate keys act here — the DSL's `sort`/`limit` are the
+     *  caller's to apply (via `sortLimitDupGroups`), since on a monorepo `findDuplicates` runs
+     *  once per package and a global order/cap can only be decided after the per-package results
+     *  merge. A parse error in the string is thrown, not swallowed. */
+    filter?: string | undefined;
 }
 interface FindDuplicatesResult {
     /** Duplicate blocks, largest-first, capped at `limit`. */
     groups: DuplicateGroup[];
+    /** `groups` (before `limit` truncation) bucketed by *exact* occurrence file set — every group
+     *  is merged into one cluster with every other group whose occurrences touch the identical set
+     *  of files, so N separate non-nested matches between the same two files (the "window-splitting"
+     *  case, see docs/known_issues/09-duplicate-clone-family-noise.md) read as one `matchCount: N`
+     *  entry instead of N rows a caller has to manually recognize as the same underlying
+     *  duplication. Deliberately *not* transitive across partially-overlapping file sets (a group
+     *  over `{A, B}` and one over `{B, C}` land in separate clusters) — an earlier connected-
+     *  component version was chaining unrelated files through shared bridge files into one
+     *  incomprehensible supercluster on real repos; see `src/graph/duplication/clusters.ts`'s
+     *  top-of-file comment. Largest-`longestMatch`-first, capped at `limit` clusters (each cluster's
+     *  own `groups` are never truncated). No group is dropped or altered to build this — every group
+     *  in `groups` (subject to `limit`) also appears inside exactly one cluster here. Each cluster
+     *  also carries per-file duplication `coverage` — merged occurrence spans divided by that
+     *  file's total line count — so `matchCount: 14` reads as "62% of this file" rather than just
+     *  a row count; see `src/graph/duplication/clusters.ts`'s `DuplicateClusterFileCoverage`. */
+    clusters: DuplicateCluster[];
 }
 /**
  * @description Scans every file already present in `graph` for cross-file (and within-file)
@@ -720,8 +1204,11 @@ interface FindDuplicatesResult {
  *   identifiers (and, by default, literals) are normalized to placeholders so renamed-variable
  *   copies still match, then a sliding token window is hashed and chain-merged into contiguous
  *   blocks. Token-shingled files are additionally partitioned into language families
- *   ({@link getDuplicateFamily} — `"style"` for Stylus, `"code"` for everything else) so
- *   matching never crosses that boundary — see docs/adr-013-duplicate-detection-noise-reduction.md.
+ *   ({@link getDuplicateFamily} — `"js"` for JS/TS/Coffee/LS, `"jvm"` for Java/Kotlin/Scala/
+ *   Groovy, `"style"` for Stylus, and one family each for Python, Go, Lua, Markdown, Gherkin) so
+ *   matching never crosses a family boundary — a `for` loop tokenizes almost identically in Java,
+ *   Go and TS, so a single `"code"` family produced phantom cross-language matches on polyglot
+ *   repos. See docs/adr-013-duplicate-detection-noise-reduction.md.
  * @param graph - The graph to scan; its node paths (already ignore-rule-filtered) are the file
  *   list, re-read from disk since duplication data isn't cached on `FileNode`.
  * @param rootDir - Absolute project root that graph paths are relative to.
@@ -730,13 +1217,24 @@ interface FindDuplicatesResult {
  *   token-shingle path only (CSS/Less/SCSS always match on literal declaration content);
  *   `maxPunctuationRatio` gates out token-shingle blocks that are mostly object/array-literal
  *   structural punctuation (e.g. schema/object-literal boilerplate) rather than substantive
- *   shared logic; `ignoreDirs` excludes files under matching directory names; `limit` caps
- *   results; `parallelTokenizing` offloads per-file tokenizing to a worker pool once the
- *   candidate file count is large enough to be worth it. Lock files are always excluded,
- *   independent of `ignoreDirs`.
+ *   shared logic; `ignoreDirs` excludes files under matching directory names; `includeSameFile`
+ *   controls whether same-file-only matches are returned (excluded by default — see its doc
+ *   comment); `includeSvgMarkup` likewise controls whether inline-SVG-markup matches are returned
+ *   (excluded by default — two different icons share a literal-normalized skeleton); `scope`
+ *   filters whole clusters by test-file involvement — `"src"` (default) drops every test cluster,
+ *   `"tests"` returns only the substantive ones, `"all"` returns everything; `filter` is an
+ *   optional `key:value` DSL string (see `DuplicateQuery`) applied as a per-group predicate
+ *   before clustering; `limit` caps results; `parallelTokenizing` offloads per-file tokenizing
+ *   to a worker pool once the candidate file count is large enough to be worth it. Lock files and
+ *   `type: "unknown"` nodes (non-code assets like `.svg`/`.json` pulled in via an explicit
+ *   `import`) are always excluded, independent of `ignoreDirs`.
  * @returns `groups` — duplicate blocks (each tagged with its `family`), two or more occurrences
  *   per block, every block that pairwise chain-matches another clustered into one group instead
- *   of one per pair, sorted largest-first across all families.
+ *   of one per pair, sorted largest-first across all families (same-file-only and svg-markup
+ *   matches excluded unless `includeSameFile` / `includeSvgMarkup`; test matches filtered per
+ *   `scope`). `clusters` — the same groups
+ *   bucketed by exact file set, with
+ *   per-file duplication coverage, see {@link FindDuplicatesResult.clusters}.
  */
 declare function findDuplicates(graph: Graph, rootDir: string, options?: FindDuplicatesOptions): Promise<FindDuplicatesResult>;
 
@@ -1040,6 +1538,46 @@ declare function registerMonorepoDetector(detector: MonorepoDetector): void;
 
 /** WorkspaceGraph holds one per-package Graph for a monorepo and exposes cross-package blast-radius queries. */
 
+/**
+ * @description Whether `relPath` falls under `pkg`'s own `relativeRoot` — i.e. the package owns
+ *   that file, as opposed to merely importing it across a package boundary. Each per-package
+ *   `Graph` also carries "borrowed" nodes for cross-package files it imports (so outward
+ *   traversal reaches them); this predicate is how callers that iterate every package's graph
+ *   avoid double-counting a file that two packages both import.
+ * @param {string} relPath - A monorepo-root-relative file path.
+ * @param {Pick<WorkspacePackage, "relativeRoot">} pkg - The package to test ownership against.
+ * @returns {boolean} `true` if `relPath` is `pkg.relativeRoot` or sits beneath it.
+ */
+declare function packageOwnsFile(relPath: string, pkg: Pick<WorkspacePackage, "relativeRoot">): boolean;
+/** @description A whole-workspace `Graph` (one namespace, all packages' own nodes, cross-package
+ *   edges intact) paired with a path → owning-package-name lookup. Produced by
+ *   {@link WorkspaceGraph.flatten}. */
+interface FlatWorkspaceGraph {
+    graph: Graph;
+    packageOf: Map<string, string>;
+}
+/** @description Compact, capped cross-package blast radius — the response shape of
+ *   {@link WorkspaceGraph.summarizeAffectedAcrossPackages}. */
+interface WorkspaceAffectedSummary {
+    /** The changed file the blast radius was computed for. */
+    file: string;
+    /** Total affected files across every package (the real count, never capped). */
+    totalAffected: number;
+    /** Number of distinct packages with at least one affected file. */
+    packageCount: number;
+    /** Per-package breakdown, sorted by `count` descending. */
+    byPackage: Array<{
+        package: string;
+        /** Real affected-file count for this package. */
+        count: number;
+        /** Up to `maxFilesPerPackage` example paths. */
+        sample: string[];
+        /** `count - sample.length` — files omitted from `sample`. */
+        more: number;
+    }>;
+    /** `true` if any package's `sample` was capped (`more > 0` somewhere). */
+    truncated: boolean;
+}
 /** @description JSON-safe snapshot of a `WorkspaceGraph`, suitable for writing to disk and restoring via `WorkspaceGraph.deserialize`. */
 interface SerializedWorkspaceGraph {
     monorepoRoot: string;
@@ -1062,6 +1600,9 @@ declare class WorkspaceGraph {
         graph: Graph;
         pkg: WorkspacePackage;
     }>;
+    /** Lazily-built merged view; see {@link flatten}. Never invalidated — a rebuild replaces the
+     *  whole `WorkspaceGraph` instance rather than mutating this one. */
+    private flattened?;
     /**
      * @param {string} monorepoRoot - Absolute path to the monorepo root directory.
      * @param {string} type - Primary detected monorepo tool (e.g. `"turborepo"`, `"pnpm"`), or `"none"`.
@@ -1084,6 +1625,19 @@ declare class WorkspaceGraph {
      *   Call once after all packages are registered.
      */
     annotateCrossPackageEdges(): void;
+    /**
+     * @description Merges every package's own nodes into a single `Graph` sharing one path
+     *   namespace, plus a `path → package name` lookup. "Borrowed" cross-package nodes are
+     *   dropped (each is contributed by its owning package instead), so no file appears twice.
+     *   Cross-package import edges already carry real monorepo-root-relative `toPath`s, so
+     *   `Graph.traverse` and `Graph.findCycles` span package boundaries on the returned graph
+     *   with no special-casing — this is the basis for whole-workspace blast radius, call
+     *   graphs, symbol search and queries. The graph is read-only: `FileNode`s are shared by
+     *   reference with the per-package graphs, never cloned.
+     *   Result is memoized for the life of this `WorkspaceGraph`.
+     * @returns {FlatWorkspaceGraph} The merged graph and its package lookup.
+     */
+    flatten(): FlatWorkspaceGraph;
     /**
      * @description Returns the workspace package whose `relativeRoot` is a path prefix of `relPath`.
      * @param {string} relPath - A monorepo-root-relative file path to look up.
@@ -1098,9 +1652,10 @@ declare class WorkspaceGraph {
     getPackageDependencies(): Map<string, string[]>;
     /**
      * @description Cross-package blast-radius analysis. Returns every file (with its package name)
-     *   that could be affected if the given monorepo-root-relative path changes.
-     *   Step 1: traverses incoming edges within the owning package graph for intra-package dependents.
-     *   Step 2: surfaces files in other packages that hold workspace import edges pointing at the owner.
+     *   transitively affected if the given monorepo-root-relative path changes — a full incoming
+     *   traversal over the flattened whole-workspace graph, so it follows real import edges across
+     *   package boundaries. The full, unbounded list: on a large monorepo this can be most of the
+     *   repo, so prefer {@link summarizeAffectedAcrossPackages} for an agent-facing response.
      * @param {string} relPath - Monorepo-root-relative path of the changed file.
      * @returns {Array<{ file: string; package: string }>} Each affected file paired with its package name.
      */
@@ -1108,6 +1663,19 @@ declare class WorkspaceGraph {
         file: string;
         package: string;
     }>;
+    /**
+     * @description Agent-friendly form of {@link getAffectedAcrossPackages}: the blast radius
+     *   grouped by owning package, with each package's file list capped so the response stays
+     *   small even when thousands of files are affected. Packages are sorted by affected count
+     *   (descending).
+     * @param {string} relPath - Monorepo-root-relative path of the changed file.
+     * @param {{ maxFilesPerPackage?: number }} [opts] - `maxFilesPerPackage` caps each package's
+     *   `sample` list (default 10; `0` = counts only, no file lists).
+     * @returns {WorkspaceAffectedSummary} Totals plus a capped per-package breakdown.
+     */
+    summarizeAffectedAcrossPackages(relPath: string, opts?: {
+        maxFilesPerPackage?: number;
+    }): WorkspaceAffectedSummary;
     /**
      * @description Serializes the workspace graph to a plain JSON-safe object.
      *   `root` is omitted from package entries as it is not needed after build time.
@@ -1284,6 +1852,7 @@ interface SlimNode {
     exports: string[];
     tags: string[];
     importsFiles: string[];
+    package?: string;
     description?: string;
     testedBy?: string[];
     coveragePct?: number;
@@ -1330,6 +1899,14 @@ declare function hasCoverageData(graph: Graph): boolean;
  * @returns Whether any node has a defined `commitCount90d`.
  */
 declare function hasChurnData(graph: Graph): boolean;
+/**
+ * @description Returns `true` if at least one node has a last-commit timestamp — i.e. `analyze`
+ *   ran with `gitStats` enabled. `check_doc_drift` needs this: without it `enrichDocDrift`
+ *   populates no `staleFor`, so an empty result would be indistinguishable from "no drift".
+ * @param graph - The graph to check.
+ * @returns Whether any node has a defined `lastCommitAt`.
+ */
+declare function hasGitTimestampData(graph: Graph): boolean;
 interface RiskHotspotEntry {
     file: string;
     name: string;
@@ -1376,6 +1953,13 @@ interface BuildGraphAtRefOptions {
     pathAliases?: Record<string, string[]> | undefined;
     /** Extra directory names to skip during test/doc discovery, on top of the built-in list. Sourced from `MokoshConfig.ignoreDirs`. */
     additionalIgnoreDirs?: string[] | undefined;
+    /** Monorepo roots only. When set, the base-ref graph is built by calling this with the
+     *  worktree directory — the caller builds a whole `WorkspaceGraph` there and returns its
+     *  flattened `Graph`, so cross-package edges survive. Bypasses the entry-point-seeded
+     *  `GraphBuilder` path (which has no `workspaceMap` and would miss `@org/*` imports).
+     *  Injected rather than imported to keep `compare.ts` free of the `createWorkspaceGraph`
+     *  dependency cycle. */
+    workspaceBuilder?: ((worktreeDir: string) => Promise<Graph>) | undefined;
 }
 /**
  * @description Builds the dependency graph as it existed at `ref`, rather than the current
@@ -1560,12 +2144,89 @@ declare const EXPORT_TRACKING_TYPES: ReadonlySet<FileType>;
 declare const IMPORT_SYMBOL_TYPES: ReadonlySet<FileType>;
 /** File types whose parser records function-level call edges (`FileNode.callEdges`). */
 declare const CALL_EDGE_TYPES: ReadonlySet<FileType>;
+/** File types whose parser populates the per-function complexity breakdown (`FileNode.functions`)
+ *  plus file-level `complexity` / `cognitiveComplexity`. */
+declare const FUNCTION_COMPLEXITY_TYPES: ReadonlySet<FileType>;
+/** File types with a dedicated test-tag strategy (`src/tags/strategies/`) — a framework-aware
+ *  applier, not the generic path-glob fallback. */
+declare const TEST_TAG_STRATEGY_TYPES: ReadonlySet<FileType>;
+/** File types the type graph (`buildTypeGraph`) can extract interfaces/classes/enums/aliases from. */
+declare const TYPE_GRAPH_TYPES: ReadonlySet<FileType>;
+/** A graph-analysis capability that only some languages' parsers feed. */
+type LanguageFeature = "callEdges" | "functionComplexity" | "typeGraph";
+/**
+ * @description Returns an explanatory note when none of the graphs contain a language whose
+ *   parser feeds `feature` — so an empty tool result (`count: 0`) reads as "language not
+ *   supported" rather than "nothing found". Returns `undefined` when at least one supported-
+ *   language file is present (the empty result is then genuine).
+ * @param graphs - One graph, or the per-package graphs of a workspace.
+ * @param feature - The capability the calling tool depends on.
+ * @returns A one-sentence note, or `undefined`.
+ */
+declare function languageSupportNote(graphs: Graph | Graph[], feature: LanguageFeature): string | undefined;
+/** How completely a single analysis axis is implemented for one language:
+ *  - `"full"` — implemented with language-aware handling; results are call/symbol-level accurate.
+ *  - `"partial"` — implemented but known-lossy (index-based resolution, module-level exports,
+ *    constructor-only call edges, heuristic categories, the generic token duplicate pipeline).
+ *  - `"none"` — not implemented, or not applicable to this language. */
+type FidelityLevel = "full" | "partial" | "none";
+/** Per-language fidelity across every precision-relevant analysis axis. The four axes backed by
+ *  a `*_TYPES` set above are kept in exact sync with it by a test; the rest are a maintained
+ *  judgement, cross-checked against `docs/language-support.md`. */
+interface LanguageFidelity {
+    /** Raw import/require specifiers → resolved graph edges. */
+    importResolution: FidelityLevel;
+    /** `FileNode.exports` populated with named symbols. Backed by {@link EXPORT_TRACKING_TYPES}. */
+    exportSymbols: FidelityLevel;
+    /** `ImportEdge.symbols` — which names each import pulls in. Backed by {@link IMPORT_SYMBOL_TYPES}. */
+    importSymbols: FidelityLevel;
+    /** Function-level call edges (`FileNode.callEdges`). Backed by {@link CALL_EDGE_TYPES}. */
+    callEdges: FidelityLevel;
+    /** Per-function + file-level complexity. Backed by {@link FUNCTION_COMPLEXITY_TYPES}. */
+    complexity: FidelityLevel;
+    /** Accuracy of the `logic`/`ui`/`test`/`config`/… category classification. */
+    category: FidelityLevel;
+    /** Duplicate detection: `"full"` = language-aware structural comparator (CSS family),
+     *  `"partial"` = the generic cross-language token pipeline (the norm — works, no language
+     *  semantics), `"none"` = not scanned. */
+    duplication: FidelityLevel;
+    /** A framework-aware test-tag strategy. Backed by {@link TEST_TAG_STRATEGY_TYPES}. */
+    testTags: FidelityLevel;
+}
+/**
+ * Authoritative per-language fidelity matrix — see `docs/language-support.md` for the same table
+ * with per-language known-limitations prose and ADR links, and `docs/known_issues/08-cross-language-reliability.md`
+ * for the plan this closes the first slice of. Every {@link FileType} has an entry.
+ */
+declare const LANGUAGE_FIDELITY: Record<FileType, LanguageFidelity>;
+/**
+ * @description Returns one advisory sentence per language present in `graphs` whose `axis`
+ *   fidelity is `"partial"` or `"none"` — so a tool whose result is real but *lossy* for the
+ *   languages in play (e.g. `get_call_graph` on a Java repo: constructors only) can say so
+ *   instead of returning a confident-looking result. Complements {@link languageSupportNote},
+ *   which only fires when the result is fully empty *and* no supported-language file is present.
+ * @param graphs - One graph, or the per-package graphs of a workspace.
+ * @param axis - The fidelity axis the calling tool depends on.
+ * @returns Sorted, de-duplicated caveat sentences; empty when every present language is `"full"`
+ *   for `axis` (or the only files are markdown/unknown).
+ */
+declare function languageCaveats(graphs: Graph | Graph[], axis: keyof LanguageFidelity): string[];
+/**
+ * @description Aggregates {@link languageCaveats} across the precision-relevant axes
+ *   ({@link SUMMARY_AXES}) for an `analyze` response, so a caller sees upfront — from the first
+ *   call — where results for this repo's languages will be lossy.
+ * @param graphs - One graph, or the per-package graphs of a workspace.
+ * @returns Sorted, de-duplicated caveat sentences; empty for an all-`full` (e.g. all-TS) repo.
+ */
+declare function languageCaveatsSummary(graphs: Graph | Graph[]): string[];
 interface LanguageCoverage {
     type: FileType;
     fileCount: number;
     exportsTracked: boolean;
     importSymbolsTracked: boolean;
     callEdgesTracked: boolean;
+    /** The full per-axis fidelity for this language — see {@link LANGUAGE_FIDELITY}. */
+    fidelity: LanguageFidelity;
 }
 /**
  * @description Reports which precision-relevant data mokosh actually tracks for each language
@@ -1612,6 +2273,90 @@ interface SymbolMatch {
  */
 declare function findSymbol(graph: Graph, name: string): SymbolMatch[];
 
+/** Tag kinds worth surfacing for `tag:<name>` querying by default — the shared
+ *  {@link SELECTION_TAG_KINDS} (`comment-marker` + `import`). The other kinds (`function` /
+ *  `variable` / `library`) are declaration/dependency names, not test-selection labels. */
+declare const SUMMARY_TAG_KINDS: readonly TagKind[];
+/** Default `minCount` floor — drops the single-occurrence long tail. */
+declare const DEFAULT_TAG_MIN_COUNT = 2;
+/** Default `limit` when the caller gives none. 50 count-ranked tags ≈ ~1K tokens and covers
+ *  the discovery need; the tail past it is uniformly low-count. */
+declare const DEFAULT_TAG_LIMIT = 50;
+/** Absolute ceiling on the returned `tags` array. `limit` is clamped to this; no argument
+ *  combination can exceed it. ~250 `{name,count,kinds}` entries ≈ ~1.5K tokens. */
+declare const TAG_RESPONSE_HARD_CAP = 250;
+/** One distinct tag name, aggregated across every kind and node it appears on. */
+interface TagAggregateEntry {
+    name: string;
+    /** Total node occurrences, summed across every kind this name appears with. */
+    count: number;
+    /** Distinct kinds seen for this name, in `TagKind` declaration order. */
+    kinds: TagKind[];
+}
+/** The full tag inventory for one or more graphs, before any filtering. */
+interface TagInventory {
+    /** name → aggregate, first-seen insertion order. */
+    entries: Map<string, TagAggregateEntry>;
+    /** Distinct tag *names* per kind (a name carrying two kinds counts once under each). */
+    byKind: Partial<Record<TagKind, number>>;
+    /** `entries.size` — distinct tag names across all kinds. */
+    totalDistinct: number;
+}
+/** Knobs for {@link summarizeTagInventory}. Each may be `undefined` (unset) so callers can
+ *  forward optional args straight through under `exactOptionalPropertyTypes`. */
+interface TagSummaryOptions {
+    /** Restrict to one kind, or `"all"` for every kind. Default: {@link SUMMARY_TAG_KINDS}. */
+    kind?: TagKind | "all" | undefined;
+    /** Case-insensitive substring match on the tag name. */
+    prefix?: string | undefined;
+    /** Minimum node count for a tag to appear. Default: {@link DEFAULT_TAG_MIN_COUNT}. */
+    minCount?: number | undefined;
+    /** Max tags returned. Default: {@link DEFAULT_TAG_LIMIT}; hard-capped at
+     *  {@link TAG_RESPONSE_HARD_CAP}. */
+    limit?: number | undefined;
+}
+/** The bounded `list_tags` response. */
+interface TagSummary {
+    /** Filtered, sorted (count desc, then name asc), capped. */
+    tags: Array<{
+        name: string;
+        count: number;
+        kinds: TagKind[];
+    }>;
+    /** `tags.length` after the cap. */
+    count: number;
+    /** Names passing the `kind` + `prefix` + `minCount` filter, before the cap. */
+    matched: number;
+    /** Distinct tag names across ALL kinds, before any filter. */
+    totalDistinct: number;
+    /** Distinct names per kind over the FULL inventory (always every kind). */
+    byKind: Partial<Record<TagKind, number>>;
+    /** Set when `matched > count` (the cap or `limit` clipped the list). */
+    truncated?: true;
+    /** How to narrow further. */
+    hint: string;
+}
+/**
+ * @description Aggregates every tag on every node of the given graphs into one inventory:
+ *   per-name occurrence count, the set of kinds each name carries, and a `byKind` histogram
+ *   of distinct names per kind. Replaces the ad-hoc count loop the MCP handler and CLI command
+ *   each used to run.
+ * @param {readonly Graph[]} graphs - Graphs to scan (one for a single package, many for a
+ *   workspace fan-out).
+ * @returns {TagInventory} The full, unfiltered inventory.
+ */
+declare function buildTagInventory(graphs: readonly Graph[]): TagInventory;
+/**
+ * @description Filters, sorts and caps a {@link TagInventory} into the bounded `list_tags`
+ *   response. The returned `tags` array never exceeds {@link TAG_RESPONSE_HARD_CAP}, whatever
+ *   the options; `byKind` and `totalDistinct` always describe the full inventory so a caller
+ *   can see what the cap hid.
+ * @param {TagInventory} inventory - Output of {@link buildTagInventory}.
+ * @param {TagSummaryOptions} [opts] - `kind` / `prefix` / `minCount` / `limit` knobs.
+ * @returns {TagSummary} The bounded response object.
+ */
+declare function summarizeTagInventory(inventory: TagInventory, opts?: TagSummaryOptions): TagSummary;
+
 /** A config matcher: substring, regex, or predicate tested against the lowercase basename. */
 type ConfigMatcher = string | RegExp | ((baseName: string) => boolean);
 /**
@@ -1683,6 +2428,10 @@ interface NodeQuery {
     /** AND match — all entries must be present (use `tag:a+b` syntax in query strings). */
     allTags?: string[];
     path?: string;
+    /** Exact match on the node's owning workspace package name. Prefix with `"!"` to negate.
+     *  Only meaningful when a `packageOf` lookup is supplied to `filterGraph`/`matchNode`
+     *  (i.e. querying a flattened workspace graph); ignored otherwise. */
+    package?: string;
     isExternal?: boolean;
     /** Substring match on `imp.toPath` — node must import a file whose path contains this string. */
     importsFile?: string;
@@ -1726,23 +2475,202 @@ interface NodeQuery {
     /** OR-group: node matches if it satisfies ANY sub-query in this array, ANDed with all other top-level fields on this NodeQuery. Populated by `any(key:val|key:val)` syntax in query strings. */
     any?: NodeQuery[];
 }
+/** Sortable axes for `find_duplicates` results (`DuplicateQuery.sort`). */
+type DupSortField = "lines" | "score" | "occurrences";
+/**
+ * Criteria for filtering `find_duplicates` results — the duplicate-group/cluster analogue of
+ * {@link NodeQuery}. Parsed from a `"key:value,key:value"` string by `parseDupQuery`
+ * (AND across keys); applied per group by `matchDupGroup`. String fields support a `"!"` prefix
+ * for negation. A group's occurrences never span more than one language family or `FileType`
+ * (matching never crosses a family boundary), so `family`/`type` are effectively group-level.
+ */
+interface DuplicateQuery {
+    /** Substring match on occurrence paths — matches when *at least one* occurrence's path
+     *  contains this. `"!substr"` matches when *no* occurrence's path contains it. */
+    path?: string;
+    /** Substring match — matches only when *every* occurrence's path contains this (an
+     *  entirely-within-one-module duplicate). `"!substr"` negates (no occurrence contains it). */
+    allPaths?: string;
+    /** Exact match on the group's `family` (`js`, `jvm`, `style`, `python`, `go`, `lua`,
+     *  `markdown`, `gherkin`, `other`). `"!"` to negate. */
+    family?: string;
+    /** Exact match on the `FileType` shared by every occurrence (derived from each occurrence's
+     *  path). `"!lang"` matches when no occurrence is of that type. */
+    type?: string;
+    /** `"block"` (a span match) or `"definition"` (a declaration-level match). */
+    kind?: string;
+    /** Exact match on a definition group's `defKind` (`cssVar` | `interface` | `type` |
+     *  `objectLiteral` | `jsxElement`). `"!"` to negate. */
+    defKind?: string;
+    /** Minimum / maximum duplicated block size in lines (`DuplicateGroup.lines`). */
+    minLines?: number;
+    maxLines?: number;
+    /** Minimum / maximum logic-token score (`DuplicateGroup.score`, falling back to `lines` for
+     *  definition groups, which carry no score). */
+    minScore?: number;
+    maxScore?: number;
+    /** Minimum number of occurrences (`DuplicateGroup.occurrences.length`). */
+    minOccurrences?: number;
+    /** `true` = occurrences span ≥2 distinct files; `false` = every occurrence is in one file. */
+    crossFile?: boolean;
+    /** OR match across positive entries (`DuplicateSignal` names); `"!name"` entries are
+     *  mandatory exclusions, evaluated independently. */
+    signals?: string[];
+    /** Result ordering for the flat `groups` list. */
+    sort?: DupSortField;
+    /** Direction for `sort`. Defaults to `"desc"`. */
+    sortDir?: "asc" | "desc";
+    /** Cap on the number of results. */
+    limit?: number;
+}
+
+/** Applies DuplicateQuery predicates to `find_duplicates` groups: path, family, type, size, score,
+ *  occurrence count, cross-file, and signal filters, plus DSL-driven sort/limit. */
+
+/**
+ * @description Whether a single {@link DuplicateGroup} satisfies every clause in `query` (AND
+ *   across keys). An empty query matches every group.
+ * @param {DuplicateGroup} group - The group to test.
+ * @param {DuplicateQuery} query - Parsed filter criteria.
+ * @returns {boolean} `true` when the group passes all set criteria.
+ */
+declare function matchDupGroup(group: DuplicateGroup, query: DuplicateQuery): boolean;
+/**
+ * @description Applies the DSL's `sort` / `sortDir` / `limit` to an already-filtered group list.
+ *   When no `sort` is given the input order is preserved (callers pass groups already ranked by
+ *   `findDuplicates`). Pure — returns a new array. Split from {@link applyDupQuery} so consumers
+ *   that received predicate-filtered groups from `findDuplicates` can re-order/cap them without a
+ *   redundant second predicate pass.
+ * @param {DuplicateGroup[]} groups - Groups to order and cap.
+ * @param {DuplicateQuery} query - Parsed criteria; only `sort`/`sortDir`/`limit` are read.
+ * @returns {DuplicateGroup[]} The groups, ordered and capped per the query.
+ */
+declare function sortLimitDupGroups(groups: DuplicateGroup[], query: DuplicateQuery): DuplicateGroup[];
+/**
+ * @description Filters `groups` by `query`, then orders and caps them via
+ *   {@link sortLimitDupGroups}. Pure — returns a new array.
+ * @param {DuplicateGroup[]} groups - Groups to filter and shape.
+ * @param {DuplicateQuery} query - Parsed filter criteria.
+ * @returns {DuplicateGroup[]} The matching groups, ordered and capped per the query.
+ */
+declare function applyDupQuery(groups: DuplicateGroup[], query: DuplicateQuery): DuplicateGroup[];
+
+/** Parses a `key:value` filter string for `find_duplicates` results into a structured DuplicateQuery. */
+
+/**
+ * @description Parses a `"key:value,key:value"` filter string (AND across keys) into a
+ *   structured {@link DuplicateQuery} for use with `matchDupGroup` / `applyDupQuery`. An empty
+ *   or whitespace-only string yields an empty query (matches everything).
+ * @param {string} queryString - Comma-separated `key:value` pairs, e.g.
+ *   `"crossFile:true,type:typescript,path:!test"`.
+ * @returns {DuplicateQuery} The structured query object.
+ * @throws {Error} On an unknown key, a malformed clause, a non-numeric numeric value, or an
+ *   invalid `sort` value — surfaced to the caller rather than silently ignored, so a typo'd
+ *   filter fails loudly instead of returning zero groups.
+ */
+declare function parseDupQuery(queryString: string): DuplicateQuery;
 
 /** Filters a graph by applying NodeQuery predicates: category, type, tag, path, imports, coverage, and more. */
 
+/** @description Optional extras for {@link filterGraph}. */
+interface FilterGraphOptions {
+    /** Path → owning-package-name lookup, from a flattened `WorkspaceGraph`. When supplied,
+     *  enables the `package:` query key and stamps each result node with its `package`. */
+    packageOf?: Map<string, string> | undefined;
+}
 /**
  * @description Filters a serialized graph to only nodes matching all criteria in `query`,
  *   then trims each node's import list to edges whose target is also in the result set.
  *   Optionally sorts the result and applies a `limit`.
  * @param {SerializedGraph} graph - The serialized graph to filter.
  * @param {NodeQuery} query - Filter criteria; omitted fields are treated as wildcards.
+ * @param {FilterGraphOptions} [options] - Optional `packageOf` lookup for workspace-scoped queries.
  * @returns {SerializedGraph} A new `SerializedGraph` containing only the matching subgraph.
  */
-declare function filterGraph(graph: SerializedGraph, query: NodeQuery): SerializedGraph;
+declare function filterGraph(graph: SerializedGraph, query: NodeQuery, options?: FilterGraphOptions): SerializedGraph;
 
 /** Parses a key:value query string into a structured NodeQuery for use with filterGraph. */
 
 declare function parseQuery(queryString: string): NodeQuery;
 
+/**
+ * Shared definition of a **test-selection tag** — a tag name that is a plausible
+ * `vitest --grep` / native-framework-tag term for "given this source change, which tests run?".
+ *
+ * Graph tags are produced generously (every top-level declaration name, every imported symbol,
+ * every `@word` in a test title, every third-party package). Most of those are noise for test
+ * selection: a `library` tag like `vitest` matches every test under grep, a `function` tag is
+ * the name of a helper in the test file itself, `test`/`barrel` are on every node of their
+ * kind. This module is the one place that decides which tags survive, reused by
+ * `propose_tags` (`src/tags/proposer.ts`), `apply_tags` (`src/tags/applier.ts`),
+ * `list_tags` (`src/graph/tag-inventory.ts`) and the `tag:` query filter
+ * (`src/query/matchers.ts`).
+ *
+ * The blocklist is configured from `mokosh.config` via {@link configureTagQuality}, called by
+ * `applyConfig` — the same reset-then-apply lifecycle as the classify registries.
+ */
+
+/** Tag kinds that can denote a test-selection label. `function` / `variable` are declaration
+ *  names (a helper in the test file, or a symbol on a source file — neither is a grep term);
+ *  `library` is a third-party package name (present on nearly every test). `class` / `type`
+ *  are never produced. */
+declare const SELECTION_TAG_KINDS: readonly TagKind[];
+/** Tag names that are just a file's `category` echoed as a tag — present on every node of that
+ *  category, so they have zero selectivity. */
+declare const CATEGORY_MARKER_TAGS: ReadonlySet<string>;
+/** A tag name must be a bare identifier: no `@`, `:`, `/`, spaces. (Moved here from
+ *  `src/tags/applier.ts`.) */
+declare const VALID_TAG_NAME_RE: RegExp;
+/**
+ * Curated generic names that appear in almost every codebase and carry no domain signal, so
+ * they never make a useful test-selection tag. Deliberately **conservative** — real subsystem
+ * names (`graph`, `parser`, `resolver`, `cache`, …) are left queryable; a project narrows
+ * further with `mokosh.config` `tags.blocklist`. Mirrors the `rename-singles` denylist
+ * philosophy: small, evidence-driven, extended only when a name is shown to be noise.
+ *
+ * Seeded from `applier.ts`'s former `GENERIC_TAG_BLOCKLIST` plus the generic offenders seen
+ * dominating `list_tags` on real repos (structural filenames + common code words).
+ */
+declare const DEFAULT_TAG_BLOCKLIST: ReadonlySet<string>;
+/** User overrides from `mokosh.config` `tags`. */
+interface TagQualityConfig {
+    /** Names added to {@link DEFAULT_TAG_BLOCKLIST} (case-insensitive). */
+    blocklist?: string[];
+    /** Names removed from the effective blocklist — kept even if built-in or user-blocked. */
+    allowlist?: string[];
+}
+/**
+ * @description Recomputes the process-wide effective tag blocklist:
+ *   `(DEFAULT_TAG_BLOCKLIST ∪ cfg.blocklist) \ cfg.allowlist`, all lower-cased. Called by
+ *   `applyConfig` after `resetTagQuality`, so each analyzed root fully replaces the previous
+ *   config rather than accumulating.
+ * @param {TagQualityConfig} [cfg] - The `tags` section of the loaded `mokosh.config`.
+ */
+declare function configureTagQuality(cfg?: TagQualityConfig): void;
+/** @description Restores the built-in blocklist, dropping any prior {@link configureTagQuality}. */
+declare function resetTagQuality(): void;
+/**
+ * @description The kind-independent half of {@link isSelectionTag}: a bare identifier, not a
+ *   `category` echo (`test`/`barrel`), and not blocklisted. Use when you already have just a
+ *   tag name (e.g. the `list_tags` inventory aggregates names across kinds).
+ * @param {string} name - The tag name to test.
+ * @returns {boolean} `true` when the name is not noise.
+ */
+declare function isSelectionTagName(name: string): boolean;
+/**
+ * @description Whether a tag is usable as a test-selection label: a selection kind, plus
+ *   {@link isSelectionTagName}.
+ * @param {StructuredTag} tag - The structured tag to test.
+ * @returns {boolean} `true` when the tag should be surfaced for test selection.
+ */
+declare function isSelectionTag(tag: StructuredTag): boolean;
+/**
+ * @description Distinct names of the selection-quality tags on a node, in first-seen order.
+ * @param {readonly StructuredTag[]} tags - A node's `tags` array.
+ * @returns {string[]} Deduplicated selection tag names.
+ */
+declare function selectionTagNames(tags: readonly StructuredTag[]): string[];
+
 /**
  * @description Result for a single file processed by {@link applyTagsToFile}.
  */
@@ -1768,10 +2696,12 @@ interface ApplyTagsResult {
     files: ApplyTagsFileResult[];
 }
 /**
- * @description Iterates every test node in the graph, extracts `"import"` kind tags that pass
- *   a name validity check and generic-name blocklist, then delegates writing to the strategy
- *   selected by `mokosh.config.*` (`tagApplier.framework`, default `"vitest"`). Non-test nodes
- *   are skipped.
+ * @description Iterates every test node in the graph, keeps its selection-quality tags
+ *   (see {@link isSelectionTag} — `import` filename/symbol tags and deliberate `comment-marker`
+ *   markers, minus declaration/library names, `test`/`barrel`, and blocklisted generics), then
+ *   delegates writing to the strategy selected by `mokosh.config.*` (`tagApplier.framework`,
+ *   default `"vitest"`). Non-test nodes are skipped. Assumes `applyConfig` has already run for
+ *   this root so any `tags.blocklist` / `tags.allowlist` is active.
  * @param {Graph} graph - The fully-enriched dependency graph.
  * @param {string} rootDir - Absolute path to the project root.
  * @param {{ dryRun: boolean }} options - Pass `dryRun: true` to preview changes without disk writes.
@@ -1809,9 +2739,10 @@ interface ProposeTagsOptions {
  * @description Proposes Vitest tags to run based on which files changed.
  *
  * Traverses the incoming dependency graph from each changed file. Test nodes
- * that can reach the changed file contribute their tags. Feature hubs act as
- * boundaries: the hub's tag is emitted and traversal stops there, preventing
- * combinatorial blowup in large graphs.
+ * that can reach the changed file contribute their **selection-quality** tags
+ * (see {@link selectionTagNames} — drops declaration/library names, `test`/`barrel`,
+ * and blocklisted generics). Feature hubs act as boundaries: the hub's tag is
+ * emitted and traversal stops there, preventing combinatorial blowup in large graphs.
  * @param {Graph} graph - The full project dependency graph.
  * @param {string[]} changedFiles - Relative paths of files that were modified (e.g. from git diff).
  * @param {ProposeTagsOptions} [options] - Optional: custom test identifier and feature-detection settings.
@@ -1867,6 +2798,23 @@ declare function computeWorkspaceSourceDigest(rootDir: string): {
     digest: string;
     files: string[];
 };
+/**
+ * @description Buckets the monorepo's source files by owning package and digests each bucket
+ *   independently — plus a `rootDigest` over files owned by no package (top-level configs,
+ *   lockfiles, root docs). Lets the workspace disk cache (`src/graph/workspace/disk-cache.ts`)
+ *   tell which individual packages are still current, instead of one whole-tree digest that any
+ *   single edit invalidates.
+ * @param rootDir - Absolute monorepo root.
+ * @param packages - Packages to bucket into; each needs `name` and `relativeRoot`.
+ * @param files - A pre-computed `getAllProjectFiles(rootDir)` result (e.g. from
+ *   `computeWorkspaceSourceDigest`), reused so the tree is walked only once.
+ * @returns `rootDigest` and a `packageDigests` map keyed by package name (every package in
+ *   `packages` gets an entry, even if it owns no files).
+ */
+declare function computeWorkspacePackageDigests(rootDir: string, packages: ReadonlyArray<Pick<WorkspacePackage, "name" | "relativeRoot">>, files: string[]): {
+    rootDigest: string;
+    packageDigests: Map<string, string>;
+};
 /**
  * @description Auto-detects the monorepo layout under `rootDir` and builds a per-package
  *   dependency graph, stitching them together into a single WorkspaceGraph.
@@ -1897,4 +2845,4 @@ declare function createWorkspaceGraph(rootDir: string, options?: {
  */
 declare function getAllProjectFiles(rootDir: string, options?: ScanOptions): string[];
 
-export { type ApiSurface, type ApplyTagsFileResult, type ApplyTagsResult, type BranchComparison, type BranchComparisonSummary, type BuildGraphAtRefOptions, CALL_EDGE_TYPES, type CachedFileTokens, CallEdge, type CalleeEntry, type CallerEntry$1 as CallerEntry, type ChangeImpactCache, type CompareBranchesOptions, type ComplexFunctionEntry, type ComplexityDelta, type CoverageDelta, type CycleEdgeKind, DEFAULT_BRANCH_GRAPH_CACHE_DIR, DEFAULT_CACHE_DIR, DEFAULT_DUPLICATION_TOKEN_CACHE_FILE, DEFAULT_EXTENSIONS, DEFAULT_GRAPH_CACHE_FILE, DEFAULT_IGNORE_DIRS, DEFAULT_WORKSPACE_GRAPH_CACHE_FILE, type DependencyGraph, type DocDriftDelta, type DuplicateFamily, type DuplicateGroup, type DuplicateOccurrence, type DuplicateSignal, type DuplicationDelta, type DuplicationTokenCache, EXPORT_TRACKING_TYPES, type ExportKind, type FeatureDetectionOptions, type FeatureDomain, type FeatureGraph, type FeatureGraphOptions, type FeatureInfo, type FileDiff, FileNode, FileType, type FindComplexFunctionsOptions, type FindCyclesOptions, type FindDuplicatesOptions, type FindDuplicatesResult, type FindRiskHotspotsOptions, type FunctionCallInfo, type GetAffectedOptions, type GetCallersOptions, Graph, GraphAnalyzer, type CallerEntry as GraphCallerEntry, type GraphExporter, IMPORT_SYMBOL_TYPES, ImportEdge, type LanguageCoverage, MermaidExporter, type ModuleResponsibility, type ModuleRole, type MokoshConfig, type MonorepoDetector, type MonorepoLayout, NodeCategory, type NodeMeta, type NodeQuery, type ParallelParsingOption, type PathWithSymbols, type ProposeTagsOptions, type PublicExport, type ResponsibilityGraph, type RiskHotspotEntry, type RiskHotspotsResult, type ScanOptions, type SerializedGraph, type SerializedWorkspaceGraph, type SlimNode, type SlimSerializedGraph, type StaleReference, StructuredTag, type SummarizeOptions, type SymbolCaller, type SymbolImporter, type SymbolMatch, type SymbolPrecision, SymbolTraversalContext, type TestNodeIdentifier, type TraversalOptions, type TraversalVisitor, type TypeEdge, type TypeGraph, type TypeKind, type TypeNode, type TypeQueryResult, WorkspaceGraph, type WorkspaceLayoutPackageSummary, type WorkspaceLayoutSummary, type WorkspacePackage, type WorkspacePackageSummary, type WorkspacePackagesSummary, applyConfig, applyTags, buildApiSurface, buildChangeImpactCache, buildFeatureGraph, buildGraphAtRef, buildResponsibilityGraph, buildTypeGraph, compareBranches, computeGraphHash, computeWorkspaceSourceDigest, configToGraphOptions, createImportMap, createWorkspaceGraph, detectAllEntryPoints, detectEntryPoint, detectFeatures, detectMonorepo, filterGraph, findComplexFunctions, findDuplicates, findRiskHotspots, findSymbol, getAffected, getAllProjectFiles, getCallers, getDependencies, getDependents, getLanguageCoverage, getNodeMeta, hasChurnData, hasCoverageData, hasGeneratedMarker, isChangeImpactCacheValid, isGeneratedPath, loadChangeImpactCache, loadCoverageMap, loadMokoshConfig, loadTokenCacheFromDisk, parseQuery, proposeAffectedTests, proposeTags, queryCallGraph, queryChangeImpact, queryTypeGraph, registerConfigMatcher, registerMonorepoDetector, registerParser, registerTestLibrary, registerTestPattern, resetClassifyRegistries, saveChangeImpactCache, saveTokenCacheToDisk, slimSerialize, summarizeBranchComparison, summarizeWorkspaceLayout, summarizeWorkspacePackages, toMermaid };
+export { type ApiSurface, type ApiSurfaceSummary, type ApplyTagsFileResult, type ApplyTagsResult, type BranchComparison, type BranchComparisonSummary, type BuildGraphAtRefOptions, CALL_EDGE_TYPES, CATEGORY_MARKER_TAGS, type CachedDuplicationResult, type CachedFileTokens, CallEdge, type CalleeEntry, type CallerEntry$1 as CallerEntry, type ChangeImpactCache, type CompareBranchesOptions, type ComplexFunctionEntry, type ComplexityDelta, type CoverageDelta, type CycleEdgeKind, DEFAULT_BRANCH_GRAPH_CACHE_DIR, DEFAULT_CACHE_DIR, DEFAULT_DUPLICATION_RESULT_CACHE_FILE, DEFAULT_DUPLICATION_TOKEN_CACHE_FILE, DEFAULT_EXTENSIONS, DEFAULT_GRAPH_CACHE_FILE, DEFAULT_IGNORE_DIRS, DEFAULT_TAG_BLOCKLIST, DEFAULT_TAG_LIMIT, DEFAULT_TAG_MIN_COUNT, DEFAULT_WORKSPACE_CACHE_SUBDIR, DEFAULT_WORKSPACE_GRAPH_CACHE_FILE, type DependencyGraph, type DocDriftDelta, type DuplicateCluster, type DuplicateClusterFileCoverage, type DuplicateFamily, type DuplicateGroup, type DuplicateOccurrence, type DuplicateQuery, type DuplicateSignal, type DuplicatesSummary, type DuplicationDelta, type DuplicationResultParams, type DuplicationTokenCache, EXPORT_TRACKING_TYPES, type ExportKind, FUNCTION_COMPLEXITY_TYPES, type FeatureDetectionOptions, type FeatureDomain, type FeatureGraph, type FeatureGraphOptions, type FeatureInfo, type FidelityLevel, type FileDiff, FileNode, FileType, type FindComplexFunctionsOptions, type FindCyclesOptions, type FindDuplicatesOptions, type FindDuplicatesResult, type FindRiskHotspotsOptions, type FlatWorkspaceGraph, type FunctionCallInfo, type GetAffectedOptions, type GetCallersOptions, Graph, GraphAnalyzer, type CallerEntry as GraphCallerEntry, type GraphExporter, IMPORT_SYMBOL_TYPES, ImportEdge, LANGUAGE_FIDELITY, type LanguageCoverage, type LanguageFeature, type LanguageFidelity, MAX_PACKAGE_CACHE_BYTES, MermaidExporter, type ModuleResponsibility, type ModuleRole, type MokoshConfig, type MonorepoDetector, type MonorepoLayout, NodeCategory, type NodeMeta, type NodeQuery, type ParallelParsingOption, type PathWithSymbols, type ProposeTagsOptions, type PublicExport, type ResponsibilityGraph, type RiskHotspotEntry, type RiskHotspotsResult, SELECTION_TAG_KINDS, SUMMARY_TAG_KINDS, type ScanOptions, type SerializedGraph, type SerializedWorkspaceGraph, type SlimNode, type SlimSerializedGraph, type StaleReference, StructuredTag, type SummarizeOptions, type SymbolCaller, type SymbolImporter, type SymbolMatch, type SymbolPrecision, SymbolTraversalContext, TAG_RESPONSE_HARD_CAP, TEST_TAG_STRATEGY_TYPES, TYPE_GRAPH_TYPES, type TagAggregateEntry, type TagInventory, TagKind, type TagQualityConfig, type TagSummary, type TagSummaryOptions, type TestNodeIdentifier, type TraversalOptions, type TraversalVisitor, type TypeEdge, type TypeGraph, type TypeKind, type TypeNode, type TypeQueryResult, VALID_TAG_NAME_RE, WORKSPACE_CACHE_VERSION, WORKSPACE_MANIFEST_FILE, type WorkspaceAffectedSummary, WorkspaceGraph, type WorkspaceLayoutPackageSummary, type WorkspaceLayoutSummary, type WorkspacePackage, type WorkspacePackageSummary, type WorkspacePackagesSummary, applyConfig, applyDupQuery, applyTags, buildApiSurface, buildChangeImpactCache, buildFeatureGraph, buildGraphAtRef, buildResponsibilityGraph, buildTagInventory, buildTypeGraph, compareBranches, computeGraphHash, computeWorkspacePackageDigests, computeWorkspaceSourceDigest, configToGraphOptions, configureTagQuality, createImportMap, createWorkspaceGraph, dedupeGroupsAgainstClusters, detectAllEntryPoints, detectEntryPoint, detectFeatures, detectMonorepo, duplicationDigest, duplicationResultCacheKey, filterGraph, findComplexFunctions, findDuplicates, findRiskHotspots, findSymbol, getAffected, getAllProjectFiles, getCallers, getDependencies, getDependents, getLanguageCoverage, getNodeMeta, hasChurnData, hasCoverageData, hasGeneratedMarker, hasGitTimestampData, isChangeImpactCacheValid, isGeneratedPath, isSelectionTag, isSelectionTagName, languageCaveats, languageCaveatsSummary, languageSupportNote, loadChangeImpactCache, loadCoverageMap, loadDuplicationResult, loadMokoshConfig, loadTokenCacheFromDisk, matchDupGroup, packageOwnsFile, parseDupQuery, parseQuery, proposeAffectedTests, proposeTags, queryCallGraph, queryChangeImpact, queryTypeGraph, registerConfigMatcher, registerMonorepoDetector, registerParser, registerTestLibrary, registerTestPattern, resetClassifyRegistries, resetTagQuality, saveChangeImpactCache, saveDuplicationResult, saveTokenCacheToDisk, selectionTagNames, slimDupCluster, slimDupGroup, slimOccurrences, slimSerialize, sortLimitDupGroups, summarizeApiSurface, summarizeBranchComparison, summarizeDuplicates, summarizeTagInventory, summarizeWorkspaceLayout, summarizeWorkspacePackages, toMermaid, topDir };