supercov 0.0.4 → 0.0.6

package/dist/query.js

@@ -3,39 +3,79 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { coverageSummaryForTests, isIndependencePair } from "./analyze.js";
 import { EVIDENCE_ARCHIVE_SCHEMA_VERSION } from "./evidenceArchive.js";
-import { analyzeCoverageArchive } from "./runAnalysis.js";
+import { analyzeCoverageArchiveCached, readCoverageQueryIndex, } from "./queryCache.js";
 import { compareRunIntegrity, createRunIntegrity } from "./integrity.js";
 import { discoverCoverageProject } from "./project.js";
-function parseOptions(args) {
+import { agentPagination, agentSuccessJson, SupercovError, } from "./agentJson.js";
+function parseOptions(command, args) {
     const options = {
+        command: command === "runs" || command === "diff" || command === "help"
+            ? command
+            : `coverage.${command}`,
         limit: 20,
         offset: 0,
         json: false,
         filter: "all",
+        target: 100,
+        metric: "all",
         positional: [],
     };
     for (let index = 0; index < args.length; index += 1) {
         const value = args[index];
         if (value === "--json")
             options.json = true;
-        else if (value === "--run")
-            options.run = args[++index];
-        else if (value === "--kind")
-            options.kind = args[++index]?.toLowerCase();
-        else if (value === "--runner")
-            options.runner = args[++index]?.toLowerCase();
+        else if (value === "--run") {
+            const run = args[++index];
+            if (!run)
+                throw new SupercovError("INVALID_ARGUMENT", "--run requires a run ID");
+            options.run = run;
+        }
+        else if (value === "--kind") {
+            const kind = args[++index]?.toLowerCase();
+            if (!kind)
+                throw new SupercovError("INVALID_ARGUMENT", "--kind requires a test kind");
+            options.kind = kind;
+        }
+        else if (value === "--runner") {
+            const runner = args[++index]?.toLowerCase();
+            if (!runner)
+                throw new SupercovError("INVALID_ARGUMENT", "--runner requires a runner name");
+            options.runner = runner;
+        }
+        else if (value === "--target") {
+            const target = Number(args[++index]);
+            if (!Number.isFinite(target) || target < 0 || target > 100)
+                throw new SupercovError("INVALID_ARGUMENT", "--target must be between 0 and 100");
+            options.target = target;
+        }
+        else if (value === "--metric") {
+            const metric = args[++index]?.toLowerCase();
+            if (!metric || !["all", "lines", "statements", "functions", "branches", "mcdc"].includes(metric))
+                throw new SupercovError("INVALID_ARGUMENT", "--metric must be all, lines, statements, functions, branches, or mcdc");
+            options.metric = metric;
+        }
         else if (value === "--filter") {
             const filter = args[++index]?.toLowerCase();
             if (filter !== "all" && filter !== "passed" && filter !== "failed")
-                throw new Error("--filter must be all, passed, or failed");
+                throw new SupercovError("INVALID_ARGUMENT", "--filter must be all, passed, or failed");
             options.filter = filter;
         }
-        else if (value === "--limit")
-            options.limit = Math.max(1, Number(args[++index]) || 20);
-        else if (value === "--offset")
-            options.offset = Math.max(0, Number(args[++index]) || 0);
+        else if (value === "--limit") {
+            const limit = Number(args[++index]);
+            if (!Number.isSafeInteger(limit) || limit < 1)
+                throw new SupercovError("INVALID_ARGUMENT", "--limit must be a positive integer");
+            options.limit = limit;
+        }
+        else if (value === "--offset") {
+            const offset = Number(args[++index]);
+            if (!Number.isSafeInteger(offset) || offset < 0)
+                throw new SupercovError("INVALID_ARGUMENT", "--offset must be a non-negative integer");
+            options.offset = offset;
+        }
         else if (value.startsWith("--"))
-            throw new Error(`Unknown option: ${value}`);
+            throw new SupercovError("INVALID_ARGUMENT", `Unknown option: ${value}`, {
+                details: { option: value },
+            });
         else
             options.positional.push(value);
     }
@@ -46,7 +86,7 @@ function filteredCoverage(report, options) {
         return report;
     const filtered = report.filters?.[options.filter];
     if (!filtered) {
-        throw new Error("This run does not contain outcome-filtered coverage. Create a new coverage run.");
+        throw new SupercovError("FILTER_UNAVAILABLE", "This run does not contain outcome-filtered coverage. Create a new coverage run.");
     }
     return filtered;
 }
@@ -80,24 +120,32 @@ function discoverRuns(root) {
     }
     return [...runs.values()].sort((left, right) => right.id.localeCompare(left.id));
 }
-function analyzeStoredRun(run) {
-    return analyzeCoverageArchive(run.evidencePath, {
+function storedRunAnalysisOptions(run) {
+    return {
         runId: run.id,
         testExitCode: run.metadata?.testExitCode,
         integrity: run.metadata?.integrity,
         generatedAt: run.metadata?.startedAt,
-    });
+    };
+}
+function analyzeStoredRun(run) {
+    return analyzeCoverageArchiveCached(run.evidencePath, storedRunAnalysisOptions(run));
 }
-function selectRun(root, selector, currentIntegrity) {
+function readStoredRunIndex(run) {
+    return readCoverageQueryIndex(run.evidencePath, storedRunAnalysisOptions(run));
+}
+function selectRun(root, selector, currentIntegrity, quiet = false) {
     const runs = discoverRuns(root);
     if (runs.length === 0)
-        throw new Error("No local coverage runs. Run supercov first.");
+        throw new SupercovError("NO_RUNS", "No local coverage runs. Run supercov first.");
     const selected = !selector || selector === "latest"
         ? runs[0]
         : (runs.find((run) => run.id === selector) ??
             runs.find((run) => run.id.startsWith(selector)));
     if (!selected)
-        throw new Error(`Coverage run not found: ${selector}`);
+        throw new SupercovError("RUN_NOT_FOUND", `Coverage run not found: ${selector}`, {
+            details: { selector },
+        });
     const report = analyzeStoredRun(selected);
     if (currentIntegrity) {
         const comparison = compareRunIntegrity(selected.metadata?.integrity ?? report.integrity, currentIntegrity);
@@ -106,7 +154,7 @@ function selectRun(root, selector, currentIntegrity) {
             stale: comparison.stale,
             staleReasons: comparison.reasons,
         };
-        if (comparison.stale) {
+        if (comparison.stale && !quiet) {
             console.error(`[supercov] stale run ${selected.id}: ${comparison.reasons.join(", ")}`);
         }
     }
@@ -123,8 +171,11 @@ function currentProjectIntegrity(root) {
 function page(values, options) {
     return values.slice(options.offset, options.offset + options.limit);
 }
-function output(value, options, text) {
-    console.log(options.json ? JSON.stringify(value, null, 2) : text);
+function output(value, options, text, pagination) {
+    process.stdout.write(options.json ? agentSuccessJson(options.command, value, pagination) : `${text}\n`);
+}
+function queryPagination(total, returned, options) {
+    return agentPagination(options.offset, options.limit, returned, total);
 }
 function pct(value) {
     return `${value.toFixed(2)}%`;
@@ -132,6 +183,175 @@ function pct(value) {
 function shellQuote(value) {
     return `'${value.replaceAll("'", `'\\''`)}'`;
 }
+function optionKey(option) {
+    return [...new Set(option)].sort().join("\0");
+}
+function minimumTestObligations(report, candidates) {
+    const tests = new Map(report.tests.map((test) => [test.id, test]));
+    const testsByFile = new Map();
+    for (const test of report.tests) {
+        if (test.role !== "test" || !test.file || !candidates.has(test.id))
+            continue;
+        const ids = testsByFile.get(test.file) ?? [];
+        ids.push(test.id);
+        testsByFile.set(test.file, ids);
+    }
+    const evidenceChoices = (ids) => {
+        const options = [];
+        for (const id of ids) {
+            const test = tests.get(id);
+            if (!test)
+                continue;
+            if (test.role === "background")
+                options.push([]);
+            else if (test.role === "setup" && test.file)
+                options.push(...(testsByFile.get(test.file) ?? []).map((candidate) => [candidate]));
+            else if (candidates.has(id))
+                options.push([id]);
+        }
+        return [...new Map(options.map((option) => [optionKey(option), option])).values()];
+    };
+    const obligations = [];
+    const uniqueLines = new Map();
+    for (const line of report.lines)
+        uniqueLines.set(`${line.file}:${line.line}`, line);
+    for (const [id, line] of uniqueLines)
+        obligations.push({ id: `line:${id}`, metric: "lines", options: evidenceChoices(line.tests) });
+    for (const point of report.points)
+        obligations.push({
+            id: `${point.meta.kind}:${point.meta.id}`,
+            metric: point.meta.kind === "statement" ? "statements" : "functions",
+            options: evidenceChoices(point.tests),
+        });
+    for (const branch of report.branches)
+        for (const alternative of branch.alternatives)
+            obligations.push({
+                id: `branch:${branch.meta.id}:${alternative.id}`,
+                metric: "branches",
+                options: evidenceChoices(alternative.tests),
+            });
+    for (const decision of report.decisions) {
+        for (let condition = 0; condition < decision.meta.conditions.length; condition += 1) {
+            const options = [];
+            for (let left = 0; left < decision.vectorObservations.length; left += 1) {
+                for (let right = left + 1; right < decision.vectorObservations.length; right += 1) {
+                    const first = decision.vectorObservations[left];
+                    const second = decision.vectorObservations[right];
+                    if (!isIndependencePair(first.vector, second.vector, condition))
+                        continue;
+                    for (const firstChoice of evidenceChoices(first.tests))
+                        for (const secondChoice of evidenceChoices(second.tests))
+                            options.push([...new Set([...firstChoice, ...secondChoice])].sort());
+                }
+            }
+            obligations.push({
+                id: `mcdc:${decision.meta.id}:${condition}`,
+                metric: "mcdc",
+                options: [...new Map(options.map((option) => [optionKey(option), option])).values()],
+            });
+        }
+    }
+    return {
+        obligations,
+        expand(selected) {
+            const expanded = new Set(selected);
+            for (const test of report.tests) {
+                if (test.role === "background")
+                    expanded.add(test.id);
+                else if (test.role === "setup" &&
+                    test.file &&
+                    (testsByFile.get(test.file) ?? []).some((id) => selected.has(id)))
+                    expanded.add(test.id);
+            }
+            return expanded;
+        },
+    };
+}
+function obligationSatisfied(obligation, selected) {
+    return obligation.options.some((option) => option.every((test) => selected.has(test)));
+}
+/** Exact branch-and-bound solver; MC/DC obligations retain their witness-pair structure. */
+export function minimumTestSet(report, target = 100, metric = "all") {
+    const unattributed = report.tests.filter((test) => test.role === "background" &&
+        (test.hits.length > 0 || test.decisions.some((decision) => decision.vectors.length > 0)));
+    if (unattributed.length > 0) {
+        throw new SupercovError("UNATTRIBUTED_EVIDENCE", "Cannot minimize exactly: this coverage view contains background/unattributed evidence. Use a runner with exact test attribution or select a fully attributed coverage view.");
+    }
+    const candidateTests = report.tests
+        .filter((test) => test.role === "test")
+        .map((test) => test.id)
+        .sort();
+    const candidates = new Set(candidateTests);
+    const model = minimumTestObligations(report, candidates);
+    const metrics = metric === "all"
+        ? ["lines", "statements", "functions", "branches", "mcdc"]
+        : [metric];
+    const obligations = model.obligations.filter((obligation) => metrics.includes(obligation.metric));
+    const totals = new Map();
+    for (const obligation of obligations)
+        totals.set(obligation.metric, (totals.get(obligation.metric) ?? 0) + 1);
+    const skipLimits = new Map();
+    for (const selectedMetric of metrics) {
+        const total = totals.get(selectedMetric) ?? 0;
+        const required = Math.ceil((total * target) / 100);
+        skipLimits.set(selectedMetric, total - required);
+    }
+    let best = new Set(candidateTests);
+    const fullExpanded = model.expand(best);
+    const fullSummary = coverageSummaryForTests(report, fullExpanded);
+    const percentage = (selectedMetric, summary) => selectedMetric === "mcdc" ? summary.conditionCoveragePct : summary[selectedMetric].percentage;
+    const impossible = metrics.find((selectedMetric) => percentage(selectedMetric, fullSummary) + 1e-9 < target);
+    if (impossible)
+        throw new SupercovError("TARGET_UNREACHABLE", `The full selected test view reaches only ${percentage(impossible, fullSummary).toFixed(2)}% ${impossible}; target ${target}% is impossible`, { details: { metric: impossible, target, reachable: percentage(impossible, fullSummary) } });
+    let exploredStates = 0;
+    const seen = new Set();
+    const search = (selected, skipped, skippedByMetric) => {
+        exploredStates += 1;
+        if (selected.size >= best.size)
+            return;
+        const stateKey = `${[...selected].sort().join(",")}|${[...skipped].sort().join(",")}`;
+        if (seen.has(stateKey))
+            return;
+        seen.add(stateKey);
+        const unmet = obligations.filter((obligation) => !skipped.has(obligation.id) && !obligationSatisfied(obligation, selected));
+        if (unmet.length === 0) {
+            best = new Set(selected);
+            return;
+        }
+        const obligation = unmet.sort((left, right) => {
+            const feasible = (value) => value.options.filter((option) => option.some((test) => !selected.has(test))).length;
+            return feasible(left) - feasible(right) || left.id.localeCompare(right.id);
+        })[0];
+        const additions = [...new Map(obligation.options
+                .map((option) => option.filter((test) => !selected.has(test)))
+                .filter((option) => option.length > 0)
+                .map((option) => [optionKey(option), option])).values()].sort((left, right) => left.length - right.length || optionKey(left).localeCompare(optionKey(right)));
+        for (const addition of additions) {
+            if (selected.size + addition.length >= best.size)
+                continue;
+            search(new Set([...selected, ...addition]), skipped, skippedByMetric);
+        }
+        const skippedCount = skippedByMetric.get(obligation.metric) ?? 0;
+        if (skippedCount < (skipLimits.get(obligation.metric) ?? 0)) {
+            const nextSkipped = new Set(skipped);
+            nextSkipped.add(obligation.id);
+            const nextCounts = new Map(skippedByMetric);
+            nextCounts.set(obligation.metric, skippedCount + 1);
+            search(selected, nextSkipped, nextCounts);
+        }
+    };
+    search(new Set(), new Set(), new Map());
+    const expanded = model.expand(best);
+    return {
+        optimal: true,
+        target,
+        metric,
+        selected: [...best].sort(),
+        expanded: [...expanded].sort(),
+        summary: coverageSummaryForTests(report, expanded),
+        exploredStates,
+    };
+}
 function coverageCommand(runId, options, child) {
     return [
         "npx supercov runs",
@@ -168,7 +388,9 @@ function selectedTestIds(report, options) {
         ]
             .filter(Boolean)
             .join(", ");
-        throw new Error(`No tests match ${filter}`);
+        throw new SupercovError("TEST_FILTER_EMPTY", `No tests match ${filter}`, {
+            details: { kind: options.kind, runner: options.runner },
+        });
     }
     return new Set(selected.map((test) => test.id));
 }
@@ -240,6 +462,13 @@ function filterLabel(options) {
         .filter(Boolean)
         .join(", ");
 }
+function queryFilters(options) {
+    return {
+        outcome: options.filter,
+        kind: options.kind ?? null,
+        runner: options.runner ?? null,
+    };
+}
 function attribution(report, selected) {
     const phases = selected
         ? report.phases.filter((phase) => selected.has(phase.test))
@@ -251,7 +480,7 @@ function attribution(report, selected) {
         serverFallback: phases.reduce((sum, phase) => sum + phase.inferredServerEvents, 0),
     };
 }
-function fileGaps(report, selected) {
+export function fileGaps(report, selected) {
     const files = new Map();
     const get = (file) => {
         const existing = files.get(file);
@@ -264,6 +493,8 @@ function fileGaps(report, selected) {
             uncoveredFunctions: 0,
             missingBranches: 0,
             missingMcdcConditions: 0,
+            measurementLimitations: 0,
+            limitationKinds: [],
             coveredByOtherTests: {
                 lines: 0,
                 statements: 0,
@@ -325,55 +556,117 @@ function fileGaps(report, selected) {
             }
         }
     }
+    for (const limitation of report.limitations ?? []) {
+        const gap = get(limitation.file);
+        gap.measurementLimitations += 1;
+        if (!gap.limitationKinds.includes(limitation.kind))
+            gap.limitationKinds.push(limitation.kind);
+    }
     for (const gap of files.values()) {
+        gap.limitationKinds.sort();
         gap.score =
             gap.uncoveredLines +
                 gap.uncoveredFunctions * 2 +
                 gap.missingBranches * 2 +
-                gap.missingMcdcConditions * 3;
+                gap.missingMcdcConditions * 3 +
+                gap.measurementLimitations * 3;
     }
     return [...files.values()].sort((left, right) => right.score - left.score || left.file.localeCompare(right.file));
 }
 function findFile(report, selector) {
-    const files = [...new Set(report.lines.map((line) => line.file))];
+    const files = [
+        ...new Set([
+            ...report.lines.map((line) => line.file),
+            ...(report.limitations ?? []).map((limitation) => limitation.file),
+        ]),
+    ];
     if (files.includes(selector))
         return selector;
     const matches = files.filter((file) => file.includes(selector));
     if (matches.length === 1)
         return matches[0];
     if (matches.length === 0)
-        throw new Error(`Source file not found: ${selector}`);
-    throw new Error(`Ambiguous file selector: ${matches.join(", ")}`);
+        throw new SupercovError("SOURCE_NOT_FOUND", `Source file not found: ${selector}`, {
+            details: { selector },
+        });
+    throw new SupercovError("AMBIGUOUS_SELECTOR", `Ambiguous file selector: ${matches.join(", ")}`, {
+        details: { selector, matches },
+    });
+}
+export function coverageMeasurement(report) {
+    const limitations = report.limitations ?? [];
+    const byKind = {
+        "dynamic-code": 0,
+        "semantic-safety": 0,
+        "source-scope": 0,
+    };
+    for (const limitation of limitations)
+        byKind[limitation.kind] += 1;
+    return {
+        complete: limitations.length === 0,
+        limitations: limitations.length,
+        // Every current limitation removes source from the measured denominator.
+        blocking: limitations.length,
+        files: new Set(limitations.map((limitation) => limitation.file)).size,
+        byKind,
+    };
 }
 function locationSelector(selector) {
     const match = /^(.*):(\d+)(?::\d+)?$/.exec(selector);
     if (!match)
-        throw new Error("Expected <source-file>:<line>");
+        throw new SupercovError("INVALID_ARGUMENT", "Expected <source-file>:<line>", {
+            details: { selector },
+        });
     return { file: match[1], line: Number(match[2]) };
 }
 function vectorText(values, outcome) {
     return `${values.map((value) => (value === null ? "-" : value ? "T" : "F")).join("")} -> ${outcome ? "T" : "F"}`;
 }
-function help() {
-    console.log(`Agent-oriented local coverage queries:
+const helpText = `Agent-oriented local coverage queries:
   supercov runs [--limit N] [--json]
   supercov runs <run-id> coverage [--filter all|passed|failed] [--kind e2e] [--runner playwright] [--json]
   supercov runs <run-id> coverage kinds [--json]
   supercov runs <run-id> coverage runners [--json]
+  supercov runs <run-id> coverage scope [--limit N] [--offset N] [--json]
   supercov runs <run-id> coverage files [--filter all|passed|failed] [--limit N] [--offset N] [--json]
   supercov runs <run-id> coverage gaps [--filter all|passed|failed] [--kind e2e] [--limit N] [--offset N] [--json]
   supercov runs <run-id> coverage file <source-file> [--kind e2e] [--limit N] [--offset N] [--json]
   supercov runs <run-id> coverage decision <id|source-file:line> [--kind e2e] [--json]
   supercov runs <run-id> coverage covers <source-file:line> [--kind e2e] [--json]
   supercov runs <run-id> coverage test <id|name-fragment> [--kind e2e] [--limit N] [--json]
+  supercov runs <run-id> coverage minimize [--target 0..100] [--metric all|lines|statements|functions|branches|mcdc] [--filter all|passed|failed] [--limit N] [--offset N] [--json]
   supercov diff <older-run> <newer-run> [--limit N] [--json]
+  supercov merge <run-id> <run-id> [...]
   supercov prune [--keep N] [--dry-run]
   supercov clean [--keep N] [--dry-run]
 
 Use "latest" as <run-id> to query the newest local run.
 
 Create a run with:
-  supercov -- <test command>`);
+  supercov -- <test command>`;
+function help(options) {
+    if (options.json) {
+        return output({
+            usage: "supercov -- <test command>",
+            runSelector: "Use latest as <run-id> to query the newest local run.",
+            queryCommands: [
+                "runs",
+                "runs <run-id> coverage",
+                "runs <run-id> coverage kinds",
+                "runs <run-id> coverage runners",
+                "runs <run-id> coverage scope",
+                "runs <run-id> coverage files",
+                "runs <run-id> coverage gaps",
+                "runs <run-id> coverage file <source-file>",
+                "runs <run-id> coverage decision <id|source-file:line>",
+                "runs <run-id> coverage covers <source-file:line>",
+                "runs <run-id> coverage test <id|name-fragment>",
+                "runs <run-id> coverage minimize",
+                "diff <older-run> <newer-run>",
+            ],
+        }, options, helpText);
+    }
+    console.log(helpText);
 }
 /** Resolve the instance-first coverage resource syntax. */
 export function resolveCoverageQueryInvocation(command, args) {
@@ -391,15 +684,17 @@ export function resolveCoverageQueryInvocation(command, args) {
         "summary",
         "kinds",
         "runners",
+        "scope",
         "files",
         "gaps",
         "file",
         "decision",
         "covers",
         "test",
+        "minimize",
     ]);
     if (!coverageCommands.has(child)) {
-        throw new Error(`Unknown coverage query: ${child}. Try supercov help.`);
+        throw new SupercovError("UNKNOWN_COMMAND", `Unknown coverage query: ${child}. Try supercov help.`, { details: { command: child } });
     }
     return {
         command: child,
@@ -409,20 +704,22 @@ export function resolveCoverageQueryInvocation(command, args) {
 export async function runQueryCommand(command, args, root = process.cwd()) {
     const resolved = resolveCoverageQueryInvocation(command, args);
     command = resolved.command;
-    const options = parseOptions(resolved.args);
+    const options = parseOptions(command, resolved.args);
     if (command === "help")
-        return help();
+        return help(options);
     const currentIntegrity = currentProjectIntegrity(root);
     if (command === "runs") {
         const availableRuns = discoverRuns(root);
         const runs = page(availableRuns, options).map((run) => {
-            const report = filteredCoverage(analyzeStoredRun(run), options);
+            const cached = readStoredRunIndex(run);
+            const report = cached ? filteredCoverage(cached, options) : undefined;
             return {
                 id: run.id,
-                generatedAt: report.generatedAt,
-                lines: report.summary.lines.percentage,
-                branches: report.summary.branches.percentage,
-                mcdc: report.summary.conditionCoveragePct,
+                generatedAt: report?.generatedAt ?? run.metadata?.startedAt,
+                coverageIndexed: Boolean(report),
+                lines: report?.summary.lines.percentage ?? null,
+                branches: report?.summary.branches.percentage ?? null,
+                mcdc: report?.summary.conditionCoveragePct ?? null,
                 command: run.metadata?.command,
                 durationMs: run.metadata?.durationMs,
                 timings: run.metadata?.timings,
@@ -436,18 +733,18 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
         });
         const runsBase = `npx supercov runs${options.filter !== "all" ? ` --filter ${options.filter}` : ""}`;
         const runsNext = nextPageCommand(runsBase, availableRuns.length, runs.length, options);
-        return output(runs, options, runs
-            .map((run) => `${run.id}  lines ${pct(run.lines ?? 0)}  branches ${pct(run.branches ?? 0)}  MC/DC ${pct(run.mcdc ?? 0)}${run.stale ? `  STALE (${run.reasons.join(", ")})` : ""}`)
+        return output({ filters: queryFilters(options), runs }, options, runs
+            .map((run) => `${run.id}  ${run.coverageIndexed ? `lines ${pct(run.lines)}  branches ${pct(run.branches)}  MC/DC ${pct(run.mcdc)}` : "coverage not indexed"}${run.stale ? `  STALE (${run.reasons.join(", ")})` : ""}`)
             .join("\n") +
             `\n${pageLabel(availableRuns.length, runs.length, options)}` +
-            (runsNext ? `\nnext page: ${runsNext}` : ""));
+            (runsNext ? `\nnext page: ${runsNext}` : ""), queryPagination(availableRuns.length, runs.length, options));
     }
     if (command === "diff") {
         const [olderSelector, newerSelector] = options.positional;
         if (!olderSelector || !newerSelector)
-            throw new Error("Usage: supercov diff <older-run> <newer-run>");
-        const olderSelected = selectRun(root, olderSelector, currentIntegrity);
-        const newerSelected = selectRun(root, newerSelector, currentIntegrity);
+            throw new SupercovError("INVALID_ARGUMENT", "Usage: supercov diff <older-run> <newer-run>");
+        const olderSelected = selectRun(root, olderSelector, currentIntegrity, options.json);
+        const newerSelected = selectRun(root, newerSelector, currentIntegrity, options.json);
         const older = {
             ...olderSelected,
             report: filteredCoverage(olderSelected.report, options),
@@ -502,6 +799,7 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
             .map(([, label]) => label)
             .sort();
         const result = {
+            filters: queryFilters(options),
             older: older.run.id,
             newer: newer.run.id,
             delta: {
@@ -540,9 +838,9 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
             .filter(Boolean)
             .join(" ");
         const diffNext = nextPageCommand(diffBase, diffTotal, diffReturned, options);
-        return output(result, options, `${older.run.id} -> ${newer.run.id}\nlines ${result.delta.lines >= 0 ? "+" : ""}${result.delta.lines}pp, branches ${result.delta.branches >= 0 ? "+" : ""}${result.delta.branches}pp, MC/DC ${result.delta.mcdc >= 0 ? "+" : ""}${result.delta.mcdc}pp\ngained: ${gainedLines.length} lines, ${gainedBranches.length} branches, ${gainedMcdc.length} MC/DC conditions\nlost: ${lostLines.length} lines, ${lostBranches.length} branches, ${lostMcdc.length} MC/DC conditions\n${result.gained.lines.map((line) => `+ line ${line}`).join("\n")}${result.gained.branches.length ? `\n${result.gained.branches.map((item) => `+ branch ${item}`).join("\n")}` : ""}${result.gained.mcdc.length ? `\n${result.gained.mcdc.map((item) => `+ MC/DC ${item}`).join("\n")}` : ""}\n${pageLabel(diffTotal, diffReturned, options)} per category${diffNext ? `\nnext page: ${diffNext}` : ""}`);
+        return output(result, options, `${older.run.id} -> ${newer.run.id}\nlines ${result.delta.lines >= 0 ? "+" : ""}${result.delta.lines}pp, branches ${result.delta.branches >= 0 ? "+" : ""}${result.delta.branches}pp, MC/DC ${result.delta.mcdc >= 0 ? "+" : ""}${result.delta.mcdc}pp\ngained: ${gainedLines.length} lines, ${gainedBranches.length} branches, ${gainedMcdc.length} MC/DC conditions\nlost: ${lostLines.length} lines, ${lostBranches.length} branches, ${lostMcdc.length} MC/DC conditions\n${result.gained.lines.map((line) => `+ line ${line}`).join("\n")}${result.gained.branches.length ? `\n${result.gained.branches.map((item) => `+ branch ${item}`).join("\n")}` : ""}${result.gained.mcdc.length ? `\n${result.gained.mcdc.map((item) => `+ MC/DC ${item}`).join("\n")}` : ""}\n${pageLabel(diffTotal, diffReturned, options)} per category${diffNext ? `\nnext page: ${diffNext}` : ""}`, queryPagination(diffTotal, diffReturned, options));
     }
-    const selectedRun = selectRun(root, options.run, currentIntegrity);
+    const selectedRun = selectRun(root, options.run, currentIntegrity, options.json);
     const run = selectedRun.run;
     const report = filteredCoverage(selectedRun.report, options);
     const selectedTestSet = selectedTestIds(report, options);
@@ -551,6 +849,7 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
             ? coverageSummaryForTests(report, selectedTestSet)
             : report.summary;
         const gaps = fileGaps(report, selectedTestSet).filter((gap) => gap.score > 0);
+        const measurement = coverageMeasurement(report);
         const selectedTests = report.tests.filter((test) => !selectedTestSet || selectedTestSet.has(test.id));
         const testCount = selectedTests.filter((test) => (test.role ?? "test") === "test").length;
         const setupCount = selectedTests.filter((test) => test.role === "setup").length;
@@ -560,18 +859,19 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
         ]));
         const result = {
             run: run.id,
-            filter: options.filter,
-            ...(filterLabel(options) ? { filter: filterLabel(options) } : {}),
+            filters: queryFilters(options),
             generatedAt: report.generatedAt,
             valid: run.metadata?.testExitCode === 0,
             stale: report.integrity?.stale ?? false,
             staleReasons: report.integrity?.staleReasons ?? [],
-            structurallyComplete: summary.coverageComplete,
+            structurallyComplete: summary.coverageComplete && measurement.complete,
             complete: options.filter === "passed" &&
                 run.metadata?.testExitCode === 0 &&
                 !report.integrity?.stale &&
-                summary.coverageComplete,
+                summary.coverageComplete &&
+                measurement.complete,
             coverage: summary,
+            measurement,
             coverageByKind: report.coverageByKind,
             coverageByRunner: report.coverageByRunner,
             attribution: attribution(report, selectedTestSet),
@@ -588,11 +888,94 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
                 }
                 : {}),
             filesWithGaps: gaps.length,
+            filesWithCoverageGaps: gaps.filter((gap) => gap.uncoveredLines > 0 ||
+                gap.uncoveredStatements > 0 ||
+                gap.uncoveredFunctions > 0 ||
+                gap.missingBranches > 0 ||
+                gap.missingMcdcConditions > 0).length,
+            filesWithMeasurementLimitations: measurement.files,
             tests: testCount,
             setups: setupCount,
             testOutcomes,
+            sourceScope: report.scope
+                ? {
+                    mode: report.scope.mode,
+                    roots: report.scope.roots,
+                    included: report.scope.entries.filter((entry) => entry.status === "included").length,
+                    excluded: report.scope.entries.filter((entry) => entry.status === "excluded").length,
+                    ambiguous: report.scope.entries.filter((entry) => entry.status === "ambiguous").length,
+                }
+                : undefined,
         };
-        return output(result, options, `run ${run.id}${filterLabel(options) ? ` (${filterLabel(options)})` : ""}${run.metadata?.testExitCode !== 0 ? ` [INVALID: test exit ${run.metadata?.testExitCode ?? "unknown"}]` : ""}${report.integrity?.stale ? ` [STALE: ${(report.integrity.staleReasons ?? []).join(", ")}]` : ""}\nlines ${pct(summary.lines.percentage)} (${summary.lines.covered}/${summary.lines.total})\nbranches ${pct(summary.branches.percentage)} (${summary.branches.covered}/${summary.branches.total})\nMC/DC ${pct(summary.conditionCoveragePct)} (${summary.coveredConditions}/${summary.conditions})${!selectedTestSet ? `\nconfidence: ${report.lines.filter((line) => line.confidence?.level === "asserted").length} asserted lines, ${report.lines.filter((line) => line.confidence?.level === "action").length} action-linked, ${report.lines.filter((line) => line.confidence?.level === "executed").length} execution-only; ${report.decisions.reduce((total, decision) => total + decision.conditions.filter((condition) => condition.assertionCovered).length, 0)} assertion-linked MC/DC conditions` : ""}\n${testCount} test(s)${setupCount ? ` + ${setupCount} setup scope(s)` : ""}; outcomes ${Object.entries(testOutcomes).filter(([, count]) => count > 0).map(([outcome, count]) => `${outcome}=${count}`).join(", ") || "none"}; ${gaps.length} file(s) have remaining obligations${(report.limitations?.length ?? 0) ? `; ${report.limitations.length} completeness blocker(s)` : ""}`);
+        return output(result, options, `run ${run.id}${filterLabel(options) ? ` (${filterLabel(options)})` : ""}${run.metadata?.testExitCode !== 0 ? ` [INVALID: test exit ${run.metadata?.testExitCode ?? "unknown"}]` : ""}${report.integrity?.stale ? ` [STALE: ${(report.integrity.staleReasons ?? []).join(", ")}]` : ""}\nlines ${pct(summary.lines.percentage)} (${summary.lines.covered}/${summary.lines.total})\nbranches ${pct(summary.branches.percentage)} (${summary.branches.covered}/${summary.branches.total})\nMC/DC ${pct(summary.conditionCoveragePct)} (${summary.coveredConditions}/${summary.conditions})\nmeasurement: ${measurement.complete ? "complete" : `incomplete — ${measurement.blocking} blocking limitation(s) in ${measurement.files} file(s)`}${!selectedTestSet ? `\nconfidence: ${report.lines.filter((line) => line.confidence?.level === "asserted").length} asserted lines, ${report.lines.filter((line) => line.confidence?.level === "action").length} action-linked, ${report.lines.filter((line) => line.confidence?.level === "executed").length} execution-only; ${report.decisions.reduce((total, decision) => total + decision.conditions.filter((condition) => condition.assertionCovered).length, 0)} assertion-linked MC/DC conditions` : ""}\n${testCount} test(s)${setupCount ? ` + ${setupCount} setup scope(s)` : ""}; outcomes ${Object.entries(testOutcomes).filter(([, count]) => count > 0).map(([outcome, count]) => `${outcome}=${count}`).join(", ") || "none"}; ${gaps.length} file(s) have unresolved coverage or measurement gaps`);
+    }
+    if (command === "minimize") {
+        const solverReport = selectedTestSet
+            ? {
+                ...report,
+                tests: report.tests.filter((test) => selectedTestSet.has(test.id)),
+            }
+            : report;
+        const minimized = minimumTestSet(solverReport, options.target, options.metric);
+        const selectedDetails = minimized.selected.map((id) => {
+            const test = report.tests.find((candidate) => candidate.id === id);
+            return {
+                id,
+                name: test.name,
+                file: test.file,
+                runner: test.provenance.runner,
+                kind: test.provenance.kind,
+            };
+        });
+        const selectedPage = page(selectedDetails, options);
+        const base = `${coverageCommand(run.id, options, "minimize")} --target ${options.target}${options.metric !== "all" ? ` --metric ${options.metric}` : ""}`;
+        const next = nextPageCommand(base, selectedDetails.length, selectedPage.length, options);
+        return output({
+            run: run.id,
+            filters: queryFilters(options),
+            ...minimized,
+            selectedCount: selectedDetails.length,
+            totalCandidateTests: solverReport.tests.filter((test) => test.role === "test").length,
+            tests: selectedPage,
+        }, options, `exact minimum ${selectedDetails.length}/${solverReport.tests.filter((test) => test.role === "test").length} test(s) for ${options.target}% ${options.metric === "all" ? "coverage across all measured metrics" : options.metric}; explored ${minimized.exploredStates} state(s)\nlines ${pct(minimized.summary.lines.percentage)}, statements ${pct(minimized.summary.statements.percentage)}, functions ${pct(minimized.summary.functions.percentage)}, branches ${pct(minimized.summary.branches.percentage)}, MC/DC ${pct(minimized.summary.conditionCoveragePct)}\n${selectedPage.map((test) => `${test.id}  ${test.kind}/${test.runner}  ${test.file ?? "unknown"}  ${test.name}`).join("\n")}\n${pageLabel(selectedDetails.length, selectedPage.length, options)}${next ? `\nnext page: ${next}` : ""}`, queryPagination(selectedDetails.length, selectedPage.length, options));
+    }
+    if (command === "scope") {
+        if (!report.scope)
+            throw new SupercovError("SCOPE_UNAVAILABLE", "This run does not contain a source-scope inventory.");
+        const limitationsByFile = new Map();
+        for (const limitation of report.limitations ?? []) {
+            const existing = limitationsByFile.get(limitation.file) ?? [];
+            existing.push(limitation);
+            limitationsByFile.set(limitation.file, existing);
+        }
+        const ordered = report.scope.entries.map((entry) => {
+            const limitations = limitationsByFile.get(entry.file) ?? [];
+            return {
+                ...entry,
+                measurementLimitations: limitations.length,
+                limitationKinds: [...new Set(limitations.map((item) => item.kind))].sort(),
+            };
+        }).sort((left, right) => {
+            const rank = { ambiguous: 0, included: 1, excluded: 2 };
+            return rank[left.status] - rank[right.status] || left.file.localeCompare(right.file);
+        });
+        const selectedEntries = page(ordered, options);
+        const base = coverageCommand(run.id, options, "scope");
+        const next = nextPageCommand(base, ordered.length, selectedEntries.length, options);
+        const counts = {
+            included: ordered.filter((entry) => entry.status === "included").length,
+            excluded: ordered.filter((entry) => entry.status === "excluded").length,
+            ambiguous: ordered.filter((entry) => entry.status === "ambiguous").length,
+        };
+        return output({
+            run: run.id,
+            filters: queryFilters(options),
+            mode: report.scope.mode,
+            roots: report.scope.roots,
+            counts,
+            measurement: coverageMeasurement(report),
+            entries: selectedEntries,
+        }, options, `mode ${report.scope.mode}; roots ${report.scope.roots.join(", ") || "none"}; included ${counts.included}, excluded ${counts.excluded}, ambiguous ${counts.ambiguous}; measurement ${coverageMeasurement(report).complete ? "complete" : `${coverageMeasurement(report).blocking} blocking limitation(s)`}\n${selectedEntries.map((entry) => `${entry.status.toUpperCase()}  ${entry.file}  ${entry.reason}${entry.measurementLimitations ? `  [measurement limitations: ${entry.measurementLimitations} ${entry.limitationKinds.join(", ")}]` : ""}${entry.packageRoot ? `  [package ${entry.packageRoot}]` : ""}`).join("\n")}\n${pageLabel(ordered.length, selectedEntries.length, options)}${next ? `\nnext page: ${next}` : ""}`, queryPagination(ordered.length, selectedEntries.length, options));
     }
     if (command === "kinds" || command === "runners") {
         const dimension = command === "kinds" ? report.coverageByKind : report.coverageByRunner;
@@ -600,8 +983,7 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
         const dimensionNext = nextPageCommand(coverageCommand(run.id, options, command), dimension.length, selectedDimension.length, options);
         return output({
             run: run.id,
-            total: dimension.length,
-            offset: options.offset,
+            filters: queryFilters(options),
             [command]: selectedDimension,
         }, options, selectedDimension
             .map((entry) => {
@@ -610,7 +992,7 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
         })
             .join("\n") +
             `\n${pageLabel(dimension.length, selectedDimension.length, options)}` +
-            (dimensionNext ? `\nnext page: ${dimensionNext}` : ""));
+            (dimensionNext ? `\nnext page: ${dimensionNext}` : ""), queryPagination(dimension.length, selectedDimension.length, options));
     }
     if (command === "files" || command === "gaps") {
         const files = fileGaps(report, selectedTestSet);
@@ -624,25 +1006,31 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
             : undefined;
         return output({
             run: run.id,
-            ...(filterLabel(options) ? { filter: filterLabel(options) } : {}),
-            total: all.length,
-            offset: options.offset,
+            filters: queryFilters(options),
             [command]: selectedFiles,
         }, options, selectedFiles
             .map((gap) => {
-            const status = gap.score === 0
-                ? "complete"
+            const missing = gap.uncoveredLines +
+                gap.uncoveredStatements +
+                gap.uncoveredFunctions +
+                gap.missingBranches +
+                gap.missingMcdcConditions;
+            const status = missing === 0
+                ? "coverage complete"
                 : `missing: lines ${gap.uncoveredLines}  stmts ${gap.uncoveredStatements}  funcs ${gap.uncoveredFunctions}  branches ${gap.missingBranches}  MC/DC ${gap.missingMcdcConditions}`;
-            return `${gap.file}  ${status}${selectedTestSet ? `  [covered elsewhere: ${Object.values(gap.coveredByOtherTests).reduce((sum, value) => sum + value, 0)}; nowhere: ${Object.values(gap.uncoveredEverywhere).reduce((sum, value) => sum + value, 0)}]` : ""}`;
+            const limitations = gap.measurementLimitations
+                ? `  measurement limitations ${gap.measurementLimitations} (${gap.limitationKinds.join(", ")})`
+                : "";
+            return `${gap.file}  ${status}${limitations}${selectedTestSet ? `  [covered elsewhere: ${Object.values(gap.coveredByOtherTests).reduce((sum, value) => sum + value, 0)}; nowhere: ${Object.values(gap.uncoveredEverywhere).reduce((sum, value) => sum + value, 0)}]` : ""}`;
         })
             .join("\n") +
             `\nshowing ${pageStart}-${pageEnd} of ${all.length}` +
-            (nextCommand ? `\nnext page: ${nextCommand}` : ""));
+            (nextCommand ? `\nnext page: ${nextCommand}` : ""), queryPagination(all.length, selectedFiles.length, options));
     }
     if (command === "file") {
         const selector = options.positional.join(" ");
         if (!selector)
-            throw new Error("Usage: supercov runs <run-id> coverage file <source-file>");
+            throw new SupercovError("INVALID_ARGUMENT", "Usage: supercov runs <run-id> coverage file <source-file>");
         const file = findFile(report, selector);
         const uncoveredLines = report.lines
             .filter((line) => line.file === file &&
@@ -707,6 +1095,16 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
             ...branches,
             ...mcdc,
         ].sort((left, right) => left.line - right.line || left.kind.localeCompare(right.kind));
+        const allFileLimitations = (report.limitations ?? [])
+            .filter((limitation) => limitation.file === file)
+            .map((limitation) => ({
+            ...limitation,
+            blocking: true,
+            effect: "outside-measured-denominator",
+        }))
+            .sort((left, right) => left.line - right.line ||
+            left.column - right.column ||
+            left.id.localeCompare(right.id));
         const allFileTests = report.tests
             .filter((test) => (!selectedTestSet || selectedTestSet.has(test.id)) &&
             test.lines.some((line) => line.file === file))
@@ -717,15 +1115,16 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
         }));
         const tests = page(allFileTests, options);
         const selected = page(obligations, options);
-        const filePageTotal = Math.max(obligations.length, allFileTests.length);
-        const filePageReturned = Math.max(selected.length, tests.length);
+        const limitations = page(allFileLimitations, options);
+        const filePageTotal = Math.max(obligations.length, allFileTests.length, allFileLimitations.length);
+        const filePageReturned = Math.max(selected.length, tests.length, limitations.length);
         const nextFileOffset = options.offset + filePageReturned;
         const nextFileCommand = filePageReturned > 0 && nextFileOffset < filePageTotal
             ? `${coverageCommand(run.id, options, "file")} ${shellQuote(file)} --offset ${nextFileOffset}${options.limit !== 20 ? ` --limit ${options.limit}` : ""}`
             : undefined;
         const result = {
             run: run.id,
-            ...(filterLabel(options) ? { filter: filterLabel(options) } : {}),
+            filters: queryFilters(options),
             file,
             counts: {
                 uncoveredLines: uncoveredLines.length,
@@ -733,14 +1132,16 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
                 uncoveredFunctions: functions.length,
                 missingBranches: branches.length,
                 missingMcdcConditions: mcdc.length,
+                measurementLimitations: allFileLimitations.length,
             },
             tests,
             totalTests: allFileTests.length,
             totalObligations: obligations.length,
-            offset: options.offset,
             obligations: selected,
+            totalLimitations: allFileLimitations.length,
+            limitations,
         };
-        return output(result, options, `${file}\nlines ${uncoveredLines.length}, statements ${statements.length}, functions ${functions.length}, branches ${branches.length}, MC/DC ${mcdc.length}\ncovered by ${allFileTests.length} test(s)\n${selected
+        return output(result, options, `${file}\nlines ${uncoveredLines.length}, statements ${statements.length}, functions ${functions.length}, branches ${branches.length}, MC/DC ${mcdc.length}, measurement limitations ${allFileLimitations.length}\ncovered by ${allFileTests.length} test(s)\n${selected
             .map((item) => item.kind === "line"
             ? `line ${item.line}: ${item.otherCoverage.coveredElsewhere ? `covered only by ${item.otherCoverage.kinds.join(", ")}/${item.otherCoverage.runners.join(", ")}` : "uncovered everywhere"}`
             : item.kind === "statement"
@@ -750,12 +1151,12 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
                     : item.kind === "branch"
                         ? `branch ${item.line}:${item.column}: missing ${item.missing}${item.otherCoverage.coveredElsewhere ? ` [covered only by ${item.otherCoverage.kinds.join(", ")}/${item.otherCoverage.runners.join(", ")}]` : ""}`
                         : `MC/DC ${item.line}:${item.column} [${item.id}]: ${item.missingCondition}${item.otherCoverage.coveredElsewhere ? ` [covered only by ${item.otherCoverage.kinds.join(", ")}/${item.otherCoverage.runners.join(", ")}]` : ""}`)
-            .join("\n")}\n${pageLabel(filePageTotal, filePageReturned, options)} obligations/tests${nextFileCommand ? `\nnext page: ${nextFileCommand}` : ""}`);
+            .join("\n")}${selected.length && limitations.length ? "\n" : ""}${limitations.map((limitation) => `LIMITATION ${limitation.kind} ${limitation.line}:${limitation.column} [${limitation.id}]\n  ${limitation.reason}\n  source: ${limitation.source}\n  effect: outside measured denominator`).join("\n")}\n${pageLabel(filePageTotal, filePageReturned, options)} obligations/tests/limitations per category${nextFileCommand ? `\nnext page: ${nextFileCommand}` : ""}`, queryPagination(filePageTotal, filePageReturned, options));
     }
     if (command === "decision") {
         const selector = options.positional[0];
         if (!selector)
-            throw new Error("Usage: supercov runs <run-id> coverage decision <id|source-file:line>");
+            throw new SupercovError("INVALID_ARGUMENT", "Usage: supercov runs <run-id> coverage decision <id|source-file:line>");
         let matches = report.decisions.filter((decision) => decision.meta.id === selector);
         if (matches.length === 0 && /:\d+(?::\d+)?$/.test(selector)) {
             const location = locationSelector(selector);
@@ -763,7 +1164,9 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
                 decision.meta.line === location.line);
         }
         if (matches.length === 0)
-            throw new Error(`Decision not found: ${selector}`);
+            throw new SupercovError("DECISION_NOT_FOUND", `Decision not found: ${selector}`, {
+                details: { selector },
+            });
         if (matches.length > 1) {
             const matchingDecisions = page(matches, options).map((decision) => ({
                 id: decision.meta.id,
@@ -775,10 +1178,9 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
             const matchesNext = nextPageCommand(`${coverageCommand(run.id, options, "decision")} ${shellQuote(selector)}`, matches.length, matchingDecisions.length, options);
             return output({
                 run: run.id,
-                total: matches.length,
-                offset: options.offset,
+                filters: queryFilters(options),
                 decisions: matchingDecisions,
-            }, options, `${matchingDecisions.map((decision) => `${decision.id}  ${decision.file}:${decision.line}:${decision.column}  ${decision.source}`).join("\n")}\n${pageLabel(matches.length, matchingDecisions.length, options)} matching decisions${matchesNext ? `\nnext page: ${matchesNext}` : ""}`);
+            }, options, `${matchingDecisions.map((decision) => `${decision.id}  ${decision.file}:${decision.line}:${decision.column}  ${decision.source}`).join("\n")}\n${pageLabel(matches.length, matchingDecisions.length, options)} matching decisions${matchesNext ? `\nnext page: ${matchesNext}` : ""}`, queryPagination(matches.length, matchingDecisions.length, options));
         }
         matches = matches.map((decision) => filterDecision(decision, selectedTestSet));
         const totalDecisionEvidence = Math.max(0, ...matches.map((decision) => Math.max(decision.vectorObservations.length, decision.conditions.length, decision.tests.length)));
@@ -796,7 +1198,7 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
         const decisionNext = nextPageCommand(`${coverageCommand(run.id, options, "decision")} ${shellQuote(selector)}`, totalDecisionEvidence, returnedDecisionEvidence, options);
         const result = {
             run: run.id,
-            ...(filterLabel(options) ? { filter: filterLabel(options) } : {}),
+            filters: queryFilters(options),
             decisions: matches,
         };
         return output(result, options, matches
@@ -805,12 +1207,12 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
             .join("\n")}\nconfidence ${decision.confidence?.level ?? "unknown"}; asserted MC/DC ${decision.conditions.filter((condition) => condition.assertionCovered).length}/${decision.conditions.length}\nvectors:\n${decision.vectorObservations.map((observation) => `  ${vectorText(observation.vector.values, observation.vector.outcome)}  tests=${observation.tests.length} confidence=${observation.confidence?.level ?? "unknown"}`).join("\n") || "  none"}`)
             .join("\n\n") +
             `\n${pageLabel(totalDecisionEvidence, returnedDecisionEvidence, options)} conditions/vectors/tests per decision` +
-            (decisionNext ? `\nnext page: ${decisionNext}` : ""));
+            (decisionNext ? `\nnext page: ${decisionNext}` : ""), queryPagination(totalDecisionEvidence, returnedDecisionEvidence, options));
     }
     if (command === "covers") {
         const selector = options.positional[0];
         if (!selector)
-            throw new Error("Usage: supercov runs <run-id> coverage covers <source-file:line>");
+            throw new SupercovError("INVALID_ARGUMENT", "Usage: supercov runs <run-id> coverage covers <source-file:line>");
         const location = locationSelector(selector);
         const line = report.lines.find((candidate) => candidate.file === location.file && candidate.line === location.line);
         const allTests = (line?.tests ?? [])
@@ -843,7 +1245,7 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
         const coversNext = nextPageCommand(`${coverageCommand(run.id, options, "covers")} ${shellQuote(selector)}`, coversTotal, coversReturned, options);
         const result = {
             run: run.id,
-            ...(filterLabel(options) ? { filter: filterLabel(options) } : {}),
+            filters: queryFilters(options),
             location,
             covered: includesSelectedTest(line?.tests ?? [], selectedTestSet),
             confidence: line?.confidence,
@@ -852,16 +1254,18 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
             tests,
             phases,
         };
-        return output(result, options, `${location.file}:${location.line} ${result.covered ? "covered" : "uncovered"}; confidence ${result.confidence?.level ?? "unknown"}${result.confidence?.e2e ? "; E2E-covered" : ""}\n${tests.map((test) => `test: ${test.name} [${test.id}] (${test.provenance?.kind ?? "unknown"}/${test.provenance?.runner ?? "unknown"})`).join("\n") || "no covering tests"}\n${phases.map((phase) => `phase: ${phase.operation}${phase.status ? ` (${phase.status})` : ""}${phase.source ? ` at ${phase.source}` : ""}`).join("\n")}\n${pageLabel(coversTotal, coversReturned, options)} tests/phases${coversNext ? `\nnext page: ${coversNext}` : ""}`);
+        return output(result, options, `${location.file}:${location.line} ${result.covered ? "covered" : "uncovered"}; confidence ${result.confidence?.level ?? "unknown"}${result.confidence?.e2e ? "; E2E-covered" : ""}\n${tests.map((test) => `test: ${test.name} [${test.id}] (${test.provenance?.kind ?? "unknown"}/${test.provenance?.runner ?? "unknown"})`).join("\n") || "no covering tests"}\n${phases.map((phase) => `phase: ${phase.operation}${phase.status ? ` (${phase.status})` : ""}${phase.source ? ` at ${phase.source}` : ""}`).join("\n")}\n${pageLabel(coversTotal, coversReturned, options)} tests/phases${coversNext ? `\nnext page: ${coversNext}` : ""}`, queryPagination(coversTotal, coversReturned, options));
     }
     if (command === "test") {
         const selector = options.positional.join(" ").toLowerCase();
         if (!selector)
-            throw new Error("Usage: supercov runs <run-id> coverage test <id|name-fragment>");
+            throw new SupercovError("INVALID_ARGUMENT", "Usage: supercov runs <run-id> coverage test <id|name-fragment>");
         const matches = report.tests.filter((test) => (!selectedTestSet || selectedTestSet.has(test.id)) &&
             (test.id === selector || test.name.toLowerCase().includes(selector)));
         if (matches.length === 0)
-            throw new Error(`Test not found: ${selector}`);
+            throw new SupercovError("TEST_NOT_FOUND", `Test not found: ${selector}`, {
+                details: { selector },
+            });
         const testBase = `${coverageCommand(run.id, options, "test")} ${shellQuote(options.positional.join(" "))}`;
         if (matches.length > 1) {
             const matchingTests = page(matches, options).map((test) => ({
@@ -873,10 +1277,9 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
             const matchesNext = nextPageCommand(testBase, matches.length, matchingTests.length, options);
             return output({
                 run: run.id,
-                total: matches.length,
-                offset: options.offset,
+                filters: queryFilters(options),
                 tests: matchingTests,
-            }, options, `${matchingTests.map((test) => `${test.name} [${test.id}] — ${test.outcome}`).join("\n")}\n${pageLabel(matches.length, matchingTests.length, options)} matching tests${matchesNext ? `\nnext page: ${matchesNext}` : ""}`);
+            }, options, `${matchingTests.map((test) => `${test.name} [${test.id}] — ${test.outcome}`).join("\n")}\n${pageLabel(matches.length, matchingTests.length, options)} matching tests${matchesNext ? `\nnext page: ${matchesNext}` : ""}`, queryPagination(matches.length, matchingTests.length, options));
         }
         const test = matches[0];
         const allPhases = report.phases
@@ -909,11 +1312,11 @@ export async function runQueryCommand(command, args, root = process.cwd()) {
         const testNext = nextPageCommand(testBase, testTotal, testReturned, options);
         return output({
             run: run.id,
-            ...(filterLabel(options) ? { filter: filterLabel(options) } : {}),
+            filters: queryFilters(options),
             tests: [selected],
-        }, options, `${selected.name}\noutcome ${selected.outcome}${selected.attempts.length ? `; ${selected.attempts.map((attempt) => `retry ${attempt.retry}=${attempt.status}`).join(", ")}` : ""}\n${selected.totals.lines} lines, ${selected.totals.hits} hits, ${selected.totals.decisions} decisions, ${selected.totals.phases} phases\n${selected.lines.map((line) => `line: ${line.file}:${line.line}`).join("\n")}${selected.lines.length && selected.phases.length ? "\n" : ""}${selected.phases.map((phase) => `${phase.kind}: ${phase.operation}${phase.source ? ` at ${phase.source}` : ""}`).join("\n")}\n${pageLabel(testTotal, testReturned, options)} per evidence category${testNext ? `\nnext page: ${testNext}` : ""}`);
+        }, options, `${selected.name}\noutcome ${selected.outcome}${selected.attempts.length ? `; ${selected.attempts.map((attempt) => `retry ${attempt.retry}=${attempt.status}`).join(", ")}` : ""}\n${selected.totals.lines} lines, ${selected.totals.hits} hits, ${selected.totals.decisions} decisions, ${selected.totals.phases} phases\n${selected.lines.map((line) => `line: ${line.file}:${line.line}`).join("\n")}${selected.lines.length && selected.phases.length ? "\n" : ""}${selected.phases.map((phase) => `${phase.kind}: ${phase.operation}${phase.source ? ` at ${phase.source}` : ""}`).join("\n")}\n${pageLabel(testTotal, testReturned, options)} per evidence category${testNext ? `\nnext page: ${testNext}` : ""}`, queryPagination(testTotal, testReturned, options));
     }
-    throw new Error(`Unknown coverage query: ${command}. Try supercov help.`);
+    throw new SupercovError("UNKNOWN_COMMAND", `Unknown coverage query: ${command}. Try supercov help.`, { details: { command } });
 }
 export const coverageQueryCommands = new Set(["help", "runs", "diff"]);
 //# sourceMappingURL=query.js.map