@0xcraft/powershot 1.1.1 → 1.1.2

package/README.md

@@ -20,13 +20,14 @@ PowerShot reviews the failure modes that plausible-looking generated code tends
 hide: invented APIs, undeclared dependencies, dropped guards, swallowed errors,
 tests that prove nothing, bent expectations, stale callers, and duplicated helpers.
 
-It asks compilers, parsers, manifests, reference graphs, and pre/post ASTs first.
-Optional model judges only handle questions that still require judgement.
+It asks self-contained parsers, manifests, and pre/post ASTs first, then uses compiler
+types and reference graphs when the environment can supply them. Optional model judges
+only handle questions that still require judgement.
 
 <table>
   <tr>
     <td width="33%"><strong>Deterministic first</strong><br>Local checks need no model, key, tokens, or network calls.</td>
-    <td width="33%"><strong>Honest completion</strong><br>A partial run cannot present itself as a clean verdict.</td>
+    <td width="33%"><strong>Honest coverage</strong><br>Portable, full, partial, and failed runs stay distinguishable.</td>
     <td width="33%"><strong>CI-native output</strong><br>One run emits terminal, Markdown, JSON, SARIF, manifest, and Code Quality reports.</td>
   </tr>
 </table>
@@ -89,7 +90,7 @@ flowchart LR
 
 1. **Snapshot** resolves the exact tree the review is about.
 2. **Ground** builds the available type, syntax, dependency, and reference oracles.
-3. **Plan** assigns checks and missing capabilities to each file individually.
+3. **Plan** assigns baseline checks and enriched semantic capabilities to each file individually.
 4. **Verify** runs deterministic checks and records what actually executed.
 5. **Judge** optionally reviews bounded bundles of related files.
 6. **Manifest** decides whether the result is complete, partial, or failed.
@@ -108,8 +109,11 @@ Every finding says where it came from:
 | `verified` | `firm` | A deterministic heuristic fired; inspect the evidence |
 | `judged` | `firm` or `tentative` | A model supplied the judgement and provenance |
 
-PowerShot stays silent when a required oracle is unavailable. The missing capability
-is written to the manifest instead of being counted as a pass.
+Portable coverage is the default: self-contained oracles run without bootstrapping the
+reviewed repository, while unavailable compiler/reference depth stays visible in the
+manifest and reports. Set `"coverage": "strict"`, or explicitly select a check with
+`--checks`, when a missing semantic oracle must make the run partial. An unavailable
+oracle is never counted as a pass in either profile.
 
 ## Deterministic checks
 
@@ -174,33 +178,38 @@ commands.
 
 ```mermaid
 flowchart LR
-    START["Selected files and checks"] --> ACCOUNT{"Everything accounted for?"}
-    ACCOUNT -- "yes" --> FINDINGS{"Findings?"}
+    START["Selected files and checks"] --> ACCOUNT{"Required work accounted for?"}
+    ACCOUNT -- "yes" --> DEPTH{"Enriched semantic depth available?"}
+    DEPTH -- "yes" --> FULL["full coverage"]
+    DEPTH -- "no · portable policy" --> PORTABLE["portable coverage · gaps named"]
+    FULL --> FINDINGS{"Findings?"}
+    PORTABLE --> FINDINGS
     FINDINGS -- "no" --> CLEAN["exit 0 · complete and clean"]
     FINDINGS -- "yes" --> FOUND["exit 1 · complete with findings"]
-    ACCOUNT -- "capability or budget gap" --> PARTIAL["exit 3 · partial"]
+    ACCOUNT -- "required oracle or budget gap" --> PARTIAL["exit 3 · partial"]
     ACCOUNT -- "required stage failed" --> FAILED["exit 3 · failed"]
 
     classDef neutral fill:#172033,stroke:#57a6ff,color:#f0f6fc,stroke-width:2px
     classDef good fill:#17251f,stroke:#4ac58b,color:#f0f6fc,stroke-width:2px
     classDef warn fill:#2a2117,stroke:#f2b84b,color:#f0f6fc,stroke-width:2px
     classDef bad fill:#2a191b,stroke:#ff675c,color:#f0f6fc,stroke-width:2px
-    class START,ACCOUNT,FINDINGS neutral
+    class START,ACCOUNT,DEPTH,FINDINGS neutral
     class CLEAN good
-    class FOUND,PARTIAL warn
+    class FULL,PORTABLE,FOUND,PARTIAL warn
     class FAILED bad
 ```
 
 | Exit | Contract |
 |---:|---|
-| `0` | Review completed and found nothing at the selected severity |
-| `1` | Review completed and reported findings |
+| `0` | Review completed in full or portable coverage and found nothing at the selected severity |
+| `1` | Review completed in full or portable coverage and reported findings |
 | `2` | Command or Git input was invalid |
 | `3` | Review is incomplete; findings may be missing |
 
-“No findings” and “PowerShot could not look” are intentionally different pipeline
-outcomes. Use `--format manifest` to inspect file dispositions, executed checks,
-skips, failures, judge units, and `notLookedAt`.
+“No findings in portable coverage”, “No findings”, and “PowerShot could not look” are
+intentionally different outcomes. Use `--format manifest` to inspect `coverage`, file
+dispositions, executed and unavailable checks, failures, judge units, and
+`notLookedAt`.
 
 ## CI integration
 
@@ -211,8 +220,6 @@ The composite action is the shortest setup for GitHub:
   with:
     fetch-depth: 0
 
-- run: npm ci --ignore-scripts
-
 - uses: xcrft/powershot@v1
   with:
     verify-only: 'true'
@@ -222,11 +229,11 @@ The composite action is the shortest setup for GitHub:
     fail-on-findings: 'true'
 ```
 
-Install the checked-out project's dependencies before PowerShot so TypeScript can
-resolve its declared ambient types. The example disables lifecycle scripts because
-pull-request code is untrusted; use the equivalent safe install for another package
-manager. In a monorepo, install from the workspace root or add safe install steps for
-the affected package roots.
+The default portable profile needs no install from the checked-out repository. That is
+the safe default for private monorepos and fork pull requests: do not expose a package
+registry credential merely to enrich a review of untrusted code. If a trusted job
+already has dependencies, PowerShot uses their TypeScript declarations automatically.
+Set `"coverage": "strict"` when missing compiler/reference oracles must block instead.
 
 PowerShot discovers `tsconfig.json` and `tsconfig.*.json` along the ancestor chain of
 each changed file. One review can use several independent package projects, skip
@@ -266,6 +273,7 @@ Anthropic, OpenAI, and Gemini providers are supported.
   "judges": {
     "enable": ["plausible-logic", "test-adequacy", "intent"]
   },
+  "coverage": "portable",
   "minSeverity": "low",
   "ignore": ["**/generated/**"],
   "promptCache": true
@@ -300,8 +308,11 @@ psh review --verify-only --absorb /tmp/powershot-findings.json
 | C | Syntax-backed checks that do not require exception semantics |
 | Solidity | Declared syntax-backed checks |
 
-PowerShot loads a bounded number of grammars per run. Unsupported or unavailable
-coverage is named in the manifest.
+Every declared language is parsed in disposable, language-isolated workers. Sources
+are sent in bounded batches, so a mixed-language monorepo does not accumulate every
+compiled WASM grammar in one process. If a declared parser cannot run, the review
+fails loudly; it is never silently waived. All eleven packs plus TypeScript and
+JavaScript are exercised together by the integration suite.
 
 ## Project guide
 

package/dist/cli/reports.js

@@ -1,4 +1,5 @@
 import { writeFileSync } from 'node:fs';
+import { unavailableCoverage } from '#app/manifest.js';
 import { dim } from '#app/report/ansi.js';
 import { codeQuality } from '#app/report/codequality.js';
 import { compact } from '#app/report/compact.js';
@@ -44,6 +45,8 @@ export function renderReport(format, result, manifest, target) {
         ...result.stats,
         state: manifest.state,
         notLookedAt: manifest.notLookedAt,
+        coverage: manifest.coverage,
+        unavailableCoverage: unavailableCoverage(manifest),
     });
 }
 export function publishReports(options) {

package/dist/cli/review-command.js

@@ -5,7 +5,7 @@ import { loadConfig, policyChanged } from '#app/config.js';
 import { absorbDelegated, delegateBrief } from '#app/delegate.js';
 import { baseRefOf, checkRange, headSha, repoRoot, shaOf } from '#app/git.js';
 import { JUDGES } from '#app/judges/prompts.js';
-import { RunManifest, coverageProblems, hashOf, writeManifest } from '#app/manifest.js';
+import { RunManifest, coverageProblems, hashOf, unavailableCoverage, writeManifest } from '#app/manifest.js';
 import { Trace } from '#app/otel.js';
 import { PACKAGE_VERSION } from '#app/package-meta.js';
 import { dim, yellow } from '#app/report/ansi.js';
@@ -225,6 +225,7 @@ export async function runReviewCommand(command, values, positionals) {
         },
         files: result.plan?.items() ?? [],
         skippedChecks: result.skippedChecks ?? [],
+        unavailableChecks: result.unavailableChecks ?? [],
         findings: {
             total: result.findings.length,
             verified: result.stats.verified,
@@ -246,7 +247,12 @@ export async function runReviewCommand(command, values, positionals) {
         record.notLookedAt.push(failure);
         process.stderr.write(yellow(' ◇ manifest') + dim(' ' + gaps.join('; ')) + '\n');
     }
-    session?.saveReport(result.findings, { state: record.state, notLookedAt: record.notLookedAt });
+    session?.saveReport(result.findings, {
+        state: record.state,
+        notLookedAt: record.notLookedAt,
+        coverage: record.coverage,
+        unavailableCoverage: unavailableCoverage(record),
+    });
     writeManifest(root, record);
     publishReports({
         format: values.format,

package/dist/cli/session-command.js

@@ -42,6 +42,8 @@ export function runSessionCommand(positionals) {
             started: session.started,
             state: session.report.state ?? 'unknown',
             notLookedAt: session.report.notLookedAt ?? ['session predates verdict recording'],
+            coverage: session.report.coverage,
+            unavailableCoverage: session.report.unavailableCoverage,
         }));
         process.stdout.write(output + '\n');
         return 0;

package/dist/config.js

@@ -9,6 +9,7 @@ const DEFAULTS = {
     // security may duplicate SAST; convention needs repository idioms in the diff
     judges: ['plausible-logic', 'test-adequacy', 'intent'],
     minSeverity: 'low',
+    coverage: 'portable',
     // findings in vendored trees are not decisions made by this repository
     ignore: [
         '**/node_modules/**', '**/dist/**', '**/build/**', '**/*.generated.*', '**/*.min.js',
@@ -33,6 +34,7 @@ export function policyChanged(root, baseRef) {
 }
 const KEYS = new Set([...Object.keys(DEFAULTS), 'checks']);
 const PROVIDERS = new Set(['anthropic', 'openai', 'gemini']);
+const COVERAGE = new Set(['portable', 'strict']);
 /** A misspelled name in the config is the quietest way to get a clean review. */
 export function validateConfig(raw, known) {
     const problems = [];
@@ -50,6 +52,9 @@ export function validateConfig(raw, known) {
     if (raw.minSeverity !== undefined && !SEVERITIES.includes(raw.minSeverity)) {
         problems.push('minSeverity "' + String(raw.minSeverity) + '" is not one of: ' + SEVERITIES.join(', '));
     }
+    if (raw.coverage !== undefined && !COVERAGE.has(String(raw.coverage))) {
+        problems.push('coverage "' + String(raw.coverage) + '" is not one of: ' + [...COVERAGE].join(', '));
+    }
     for (const [field, names] of [['verifiers', known.verifiers], ['judges', known.judges]]) {
         const value = raw[field];
         if (value === undefined)

package/dist/ground.js

@@ -2,7 +2,7 @@ import { Project, SyntaxKind } from 'ts-morph';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { decode } from './text.js';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { packFor, parse } from './lang/packs.js';
+import { PACKS, packFor, parseIsolated } from './lang/packs.js';
 import { insideRepo, isSymlink, repoPath } from './fspolicy.js';
 const CODE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
 const TS_CONFIG = /^tsconfig(?:\..+)?\.json$/i;
@@ -360,7 +360,7 @@ export function readEnvManifest(root) {
     return undefined;
 }
 async function parseForeign(root, changed, signal) {
-    const out = [];
+    const byLanguage = new Map();
     for (const c of changed) {
         // parsing thousands of files is where a large scan spends its time, so a signal
         // has to be honoured here rather than only once the checks begin
@@ -376,13 +376,66 @@ async function parseForeign(root, changed, signal) {
         // costs seconds to produce findings nobody acts on
         if ((statSync(abs, { throwIfNoEntry: false })?.size ?? 0) > 512 * 1024)
             continue;
-        const tree = await parse(pack, decode(readFileSync(abs)));
-        if (!tree)
-            continue;
-        const beforeTree = c.before === undefined ? undefined : await parse(pack, c.before);
-        out.push({ path: c.path, pack, tree, beforeTree, changed: c });
+        const list = byLanguage.get(pack.name) ?? [];
+        list.push({
+            changed: c,
+            source: decode(readFileSync(abs)),
+            // A generated base can be arbitrarily larger than the reviewed result. Do not
+            // smuggle it past the current-file limit through the before/after channel.
+            beforeSource: c.before !== undefined && Buffer.byteLength(c.before) <= 512 * 1024
+                ? c.before
+                : undefined,
+        });
+        byLanguage.set(pack.name, list);
     }
-    return out;
+    const parsed = new Map();
+    // A worker holds one grammar and a bounded source batch. This keeps both WASM
+    // compilation and structured-clone payloads independent of monorepo size.
+    const MAX_BATCH_BYTES = 8 * 1024 * 1024;
+    const MAX_BATCH_FILES = 128;
+    for (const pack of PACKS) {
+        const candidates = byLanguage.get(pack.name) ?? [];
+        for (let start = 0; start < candidates.length;) {
+            let end = start;
+            let bytes = 0;
+            while (end < candidates.length && end - start < MAX_BATCH_FILES) {
+                const candidate = candidates[end];
+                const next = Buffer.byteLength(candidate.source) + Buffer.byteLength(candidate.beforeSource ?? '');
+                if (end > start && bytes + next > MAX_BATCH_BYTES)
+                    break;
+                bytes += next;
+                end++;
+            }
+            const batch = candidates.slice(start, end);
+            const sources = batch.flatMap((candidate) => candidate.beforeSource === undefined
+                ? [candidate.source]
+                : [candidate.source, candidate.beforeSource]);
+            const trees = await parseIsolated(pack, sources, signal);
+            let index = 0;
+            for (const candidate of batch) {
+                const tree = trees[index++];
+                const beforeTree = candidate.beforeSource === undefined ? undefined : trees[index++];
+                if (!tree)
+                    continue;
+                parsed.set(candidate.changed.path, {
+                    path: candidate.changed.path,
+                    pack,
+                    tree,
+                    beforeTree,
+                    changed: candidate.changed,
+                });
+            }
+            start = end;
+            if (signal?.aborted)
+                break;
+        }
+        if (signal?.aborted)
+            break;
+    }
+    return changed.flatMap((file) => {
+        const result = parsed.get(file.path);
+        return result ? [result] : [];
+    });
 }
 function buildSymbolIndex(sourceFiles, root) {
     const index = new Map();

package/dist/lang/packs.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
+import { Worker } from 'node:worker_threads';
 /** Shared defaults; a pack overrides only what its grammar spells differently. */
 const COMMON_NODES = {
     identifier: ['identifier'],
@@ -498,15 +499,6 @@ export function packFor(path) {
 }
 let ready;
 const parsers = new Map();
-/**
- * Measured, not guessed, and the measurement is worth writing down because the naive
- * one is misleading. Loading grammars is cheap — all eleven load for ~143MB. Parsing
- * with them is not: V8 tiers up each wasm module in the background, and RSS climbed
- * 63 → 690MB across eleven before the process died inside that compilation. Six
- * grammars sat at ~131MB and were comfortable.
- */
-const MAX_GRAMMARS = 6;
-export const skippedLanguages = [];
 /**
  * Grammars load lazily and once. A repository with no Python pays nothing for
  * Python, and the wasm runtime is only initialised when a foreign file appears.
@@ -515,11 +507,6 @@ async function parserFor(pack) {
     const cached = parsers.get(pack.name);
     if (cached)
         return cached;
-    if (parsers.size >= MAX_GRAMMARS) {
-        if (!skippedLanguages.includes(pack.name))
-            skippedLanguages.push(pack.name);
-        return undefined;
-    }
     try {
         if (!ready) {
             ready = (async () => {
@@ -554,4 +541,100 @@ export async function parse(pack, source) {
         return undefined;
     }
 }
+/** Turn a native WASM-backed tree into data that can cross a worker boundary. */
+export function serializeTree(tree) {
+    const copy = (raw, field) => {
+        const node = raw;
+        const children = [];
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child)
+                children.push(copy(child, node.fieldNameForChild(i) ?? undefined));
+        }
+        return {
+            type: node.type,
+            startIndex: node.startIndex,
+            endIndex: node.endIndex,
+            startPosition: { ...node.startPosition },
+            endPosition: { ...node.endPosition },
+            named: node.isNamed,
+            field,
+            children,
+        };
+    };
+    return { root: copy(tree.rootNode) };
+}
+/** Restore the small Node interface the language-independent verifiers consume. */
+function hydrateTree(source, tree) {
+    const hydrate = (data) => {
+        const children = data.children.map(hydrate);
+        return {
+            type: data.type,
+            get text() { return source.slice(data.startIndex, data.endIndex); },
+            startPosition: { ...data.startPosition },
+            endPosition: { ...data.endPosition },
+            childCount: children.length,
+            child: (index) => children[index] ?? null,
+            namedChildren: children.filter((_, index) => data.children[index]?.named),
+            childForFieldName: (name) => {
+                const index = data.children.findIndex((child) => child.field === name);
+                return index < 0 ? null : (children[index] ?? null);
+            },
+        };
+    };
+    return { rootNode: hydrate(tree.root) };
+}
+/**
+ * Parse one language in a disposable worker.
+ *
+ * V8 keeps compiled WASM grammars alive longer than their JS parsers. Eleven
+ * grammars in one process reached ~690MB and killed real mixed-language runs.
+ * One worker owns one grammar, returns plain trees, and is then terminated, so
+ * compiled-grammar memory is bounded by one language rather than by the monorepo's
+ * language count. Plain trees still scale with the selected diff.
+ */
+export function parseIsolated(pack, sources, signal) {
+    if (sources.length === 0)
+        return Promise.resolve([]);
+    if (signal?.aborted)
+        return Promise.resolve(sources.map(() => undefined));
+    return new Promise((resolve) => {
+        let worker;
+        let settled = false;
+        const empty = () => sources.map(() => undefined);
+        const finish = (trees) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener('abort', abort);
+            // Resolve only after V8 has released this worker's WASM grammar. Otherwise a
+            // fast next batch can overlap termination and recreate the memory spike this
+            // isolation boundary exists to prevent.
+            void worker.terminate().then(() => resolve(trees), () => resolve(trees));
+        };
+        const abort = () => finish(empty());
+        try {
+            worker = new Worker(new URL('./parse-worker.js', import.meta.url), {
+                workerData: { language: pack.name, sources },
+            });
+        }
+        catch {
+            resolve(empty());
+            return;
+        }
+        signal?.addEventListener('abort', abort, { once: true });
+        worker.once('message', (raw) => {
+            if (!Array.isArray(raw) || raw.length !== sources.length) {
+                finish(empty());
+                return;
+            }
+            finish(raw.map((tree, index) => tree ? hydrateTree(sources[index], tree) : undefined));
+        });
+        worker.once('error', () => finish(empty()));
+        worker.once('exit', () => finish(empty()));
+        // Close the narrow race between the early check and listener registration.
+        if (signal?.aborted)
+            abort();
+    });
+}
 //# sourceMappingURL=packs.js.map

package/dist/lang/parse-worker.js

@@ -0,0 +1,15 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { PACKS, parse, serializeTree } from './packs.js';
+async function run(input) {
+    const pack = PACKS.find((candidate) => candidate.name === input.language);
+    if (!pack || !Array.isArray(input.sources))
+        return [];
+    const trees = [];
+    for (const source of input.sources) {
+        const tree = await parse(pack, source);
+        trees.push(tree ? serializeTree(tree) : undefined);
+    }
+    return trees;
+}
+void run(workerData).then((trees) => parentPort?.postMessage(trees), () => parentPort?.postMessage([]));
+//# sourceMappingURL=parse-worker.js.map

package/dist/lang/python-deps.js

@@ -135,11 +135,20 @@ const SKIP_DIRS = new Set([
     'node_modules', '.git', '.venv', 'venv', 'env', '__pycache__', 'dist', 'build',
     '.mypy_cache', '.pytest_cache', '.tox', 'site-packages', 'target', '.next',
 ]);
-export function localModules(root) {
+/**
+ * Importable names near one changed Python file.
+ *
+ * Only direct entries in its ancestor chain and conventional source roots are read.
+ * That bounds work by path depth instead of repository size, while still covering
+ * `src/pkg` beside `tests/test_pkg.py` and namespace packages without __init__.py.
+ */
+export function localModules(root, from = root) {
     const local = new Set();
-    const walk = (dir, depth) => {
-        if (depth > 6 || local.size > 4000)
+    const scanned = new Set();
+    const inspect = (dir) => {
+        if (scanned.has(dir))
             return;
+        scanned.add(dir);
         let entries;
         try {
             entries = readdirSync(dir, { withFileTypes: true });
@@ -147,21 +156,25 @@ export function localModules(root) {
         catch {
             return;
         }
-        const isPackage = entries.some((e) => e.isFile() && e.name === '__init__.py');
         for (const entry of entries) {
             if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name))
                 continue;
             if (entry.isDirectory()) {
-                // a package directory is importable by name; so is a plain source folder
+                // Namespace packages are importable without __init__.py too.
                 local.add(entry.name);
-                walk(join(dir, entry.name), depth + 1);
             }
-            else if (entry.name.endsWith('.py') && (isPackage || depth <= 2)) {
+            else if (entry.isFile() && entry.name.endsWith('.py') && entry.name !== '__init__.py') {
                 local.add(entry.name.slice(0, -3));
             }
         }
     };
-    walk(root, 0);
+    for (let dir = from;; dir = dirname(dir)) {
+        inspect(dir);
+        for (const source of ['src', 'lib', 'python'])
+            inspect(join(dir, source));
+        if (dir === root || dirname(dir) === dir)
+            break;
+    }
     return local;
 }
 export function isPhantom(importName, manifest, local) {

package/dist/manifest.js

@@ -2,6 +2,23 @@ import { createHash } from 'node:crypto';
 import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 export const SCHEMA = 'powershot.run/v1';
+/** Human-readable optional depth, kept separate from verdict-blocking notLookedAt. */
+export function unavailableCoverage(record) {
+    const out = [];
+    const files = (record.files ?? []).filter((file) => file.unavailable?.length);
+    if (files.length > 0) {
+        out.push(files.length + ' file(s) without enriched semantic coverage: ' +
+            files.slice(0, 5).map((file) => file.path + ' (' + file.unavailable.join(', ') + ')').join(', ') +
+            (files.length > 5 ? ', …' : ''));
+    }
+    const checks = record.checks?.unavailable ?? [];
+    if (checks.length > 0) {
+        out.push(checks.length + ' enriched check(s) unavailable: ' +
+            checks.slice(0, 8).map((check) => check.check + ' (no ' + check.missing + ')').join(', ') +
+            (checks.length > 8 ? ', …' : ''));
+    }
+    return out;
+}
 /** The single state machine behind manifests, benches, renderers and exit codes. */
 export function completionOf(parts) {
     const waivedUnits = parts.units.filter((unit) => unit.outcome === 'waived').length;
@@ -65,12 +82,20 @@ export class RunManifest {
                 ...file,
                 checks: [...file.checks],
                 missing: file.missing ? [...file.missing] : undefined,
+                unavailable: file.unavailable ? [...file.unavailable] : undefined,
             })),
             units: this.units.map((unit) => ({ ...unit })),
             checks: {
                 ran: [...this.ranChecks],
                 skipped: parts.skippedChecks.map((check) => ({ ...check })),
+                ...((parts.unavailableChecks?.length ?? 0) > 0
+                    ? { unavailable: parts.unavailableChecks.map((check) => ({ ...check })) }
+                    : {}),
             },
+            coverage: parts.files.some((file) => file.missing?.length || file.unavailable?.length) ||
+                parts.skippedChecks.length > 0 || (parts.unavailableChecks?.length ?? 0) > 0
+                ? 'portable'
+                : 'full',
             findings: { ...parts.findings },
             usage: { ...parts.usage },
             state: completion.state,
@@ -118,6 +143,15 @@ export function coverageProblems(m) {
         if (f.disposition !== 'selected' && f.checks.length > 0) {
             problems.push(f.path + ': ' + f.disposition + ' file received checks');
         }
+        if (f.disposition !== 'selected' && f.unavailable?.length) {
+            problems.push(f.path + ': ' + f.disposition + ' file has unavailable coverage');
+        }
+        const missingCaps = new Set(f.missing ?? []);
+        for (const capability of f.unavailable ?? []) {
+            if (missingCaps.has(capability)) {
+                problems.push(f.path + ': capability is both required and unavailable: ' + capability);
+            }
+        }
         const local = new Set();
         for (const check of f.checks) {
             if (local.has(check))
@@ -157,6 +191,21 @@ export function coverageProblems(m) {
         if (ran.has(check.check))
             problems.push('check counted as both ran and skipped: ' + check.check);
     }
+    const unavailable = new Set();
+    for (const check of m.checks.unavailable ?? []) {
+        if (unavailable.has(check.check))
+            problems.push('check counted twice as unavailable: ' + check.check);
+        unavailable.add(check.check);
+        if (skipped.has(check.check))
+            problems.push('check counted as both skipped and unavailable: ' + check.check);
+    }
+    const expectedCoverage = m.files.some((file) => file.missing?.length || file.unavailable?.length) ||
+        m.checks.skipped.length > 0 || (m.checks.unavailable?.length ?? 0) > 0
+        ? 'portable'
+        : 'full';
+    if (m.coverage !== undefined && m.coverage !== expectedCoverage) {
+        problems.push('coverage is ' + m.coverage + ' but accounting says ' + expectedCoverage);
+    }
     // a judged run that reports complete must have reached every unit it selected
     const unreached = m.units.filter((u) => u.outcome === 'failed' || u.outcome === 'waived');
     if (m.state === 'complete' && unreached.length > 0) {

package/dist/plan.js

@@ -67,6 +67,13 @@ export class SelectionPlan {
             row.missing = [...new Set([...(row.missing ?? []), ...missing])];
         }
     }
+    /** Record optional semantic depth that this environment could not provide. */
+    noteUnavailable(path, unavailable) {
+        const row = this.rows.get(path);
+        if (row && row.disposition === 'selected' && unavailable.length > 0) {
+            row.unavailable = [...new Set([...(row.unavailable ?? []), ...unavailable])];
+        }
+    }
     /** Record coverage at the same file granularity used to decide applicability. */
     checked(path, check) {
         const row = this.rows.get(path);

package/dist/report/markdown.js

@@ -1,3 +1,4 @@
+import { unavailableCoverage } from '#app/manifest.js';
 const MARK = { verified: '▣', judged: '▚' };
 /** Untrusted prose encoded as literal CommonMark text. */
 function text(s) {
@@ -63,12 +64,27 @@ export function markdown(findings, run) {
             '',
         ]
         : [];
+    const portable = run?.state === 'complete' && run.coverage === 'portable';
+    const coverage = portable
+        ? [
+            '> [!NOTE]',
+            '> **Portable coverage.** Self-contained oracles ran; enriched semantic depth was unavailable:',
+            ...unavailableCoverage(run).map((reason) => '> - ' + text(reason)),
+            '',
+        ]
+        : [];
     if (findings.length === 0) {
-        return ['## PowerShot', '', ...banner, incomplete ? 'No findings *from what it managed to review*.' : 'No findings.', ''].join('\n');
+        return [
+            '## PowerShot', '', ...banner, ...coverage,
+            incomplete
+                ? 'No findings *from what it managed to review*.'
+                : portable ? 'No findings in portable coverage.' : 'No findings.',
+            '',
+        ].join('\n');
     }
     const verified = findings.filter((f) => f.class === 'verified').length;
     const judged = findings.length - verified;
-    const out = ['## PowerShot', '', ...banner];
+    const out = ['## PowerShot', '', ...banner, ...coverage];
     out.push('**' + verified + ' verified** (deterministic, 0 tokens) · **' + judged + ' judged** (agent)', '');
     for (const [file, list] of group(findings)) {
         out.push('### `' + path(file) + '`', '');