supercov 0.0.13 → 0.0.14

package/README.md

@@ -129,10 +129,11 @@ npx supercov diff <older-run> <newer-run>
 npx supercov merge <first-run-id> <second-run-id>
 ```
 
-`supercov runs` is metadata-only for uncached history and never reconstructs
-coverage for twenty runs merely to list them. Runs whose disposable query index
-already exists include their metrics; other rows say `coverage not indexed`.
-Selecting a run with `runs <run-id> coverage` materializes its index lazily.
+`supercov runs` always includes coverage percentages. Supercov derives a
+missing disposable query view from the run's immutable evidence before printing
+that row; whether the view was already available is never exposed in the CLI.
+`supercov runs <run-id>` prints the same summary as
+`supercov runs <run-id> coverage`.
 
 Coverage queries use `--filter all` by default, matching conventional coverage
 tools: every executed attempt contributes, including attempts that later fail.
@@ -244,17 +245,17 @@ state writes use sibling-temp files, fsync, and atomic rename; lock acquisition
 uses exclusive creation and fsync. Published `run.json` is the durable terminal
 record, so terminal work state is not retained.
 
-Retention is deterministic because UTC run IDs sort chronologically:
+Retention is deterministic because run records store their UTC start time:
 
 ```sh
-npx supercov prune --keep 20
-npx supercov prune --keep 20 --dry-run
-npx supercov clean --keep 20   # also removes the shared build cache
+npx supercov clean             # removes all stored runs and the shared build cache
+npx supercov clean --dry-run   # previews the default full cleanup
+npx supercov clean --keep 20   # explicitly retains the 20 newest runs
 ```
 
-Neither operation runs automatically. `prune` removes explicit history beyond
-the requested retention and orphan/terminal transient data while preserving
-the shared cache. `clean` also removes that cache. Both acquire the same lock
+Cleanup never runs automatically. `clean` removes explicit history beyond the
+requested retention, orphan/terminal transient data, and the shared build
+cache. It acquires the same lock
 as a coverage run, refuse to race an active run, and never touch files outside
 `.supercov/`.
 

package/docs/performance.md

@@ -43,6 +43,20 @@ reported separately from Supercov's recorded phases.
 
 ## Reference measurement, not a guarantee
 
+On 2026-08-26, the 30-test Essential SEO Playwright suite running across seven
+cycle-restored VMs produced a 43.02 s uncovered control and two valid warm
+Supercov measurements of 46.30 s and 40.20 s. The slower covered sample is
+1.076x the control and therefore remains below the current 1.1x realistic-suite
+target; the faster result illustrates why multiple alternating pairs are still
+required for a statistically stable benchmark. The 40.20 s run spent 38.63 s
+inside the unchanged test command and 1.04 s total on initialization, workspace
+refresh, adapter restoration and evidence publication. It attributed 6,727
+server records across 30 remote launches with zero corrupt evidence records.
+
+VM-image creation is not included in these warm comparisons. A changed engine
+fingerprint intentionally caused a one-time 119 s rebake before the first
+post-change run; comparing that cold run with a warm control would be invalid.
+
 On 2026-08-24, the 29-test Essential SEO offline suite on the development Mac
 produced this warm pair:
 
@@ -73,8 +87,10 @@ Before raw-evidence-only storage, the reference run retained 4.5 MB of reports
 and 1.7 MB across 178 loose evidence files. Its canonical compressed JSON was
 0.9 MB. The execution evidence alone packed to about 121 KiB; current archives
 also embed the exact denominator manifest and are the sole coverage artifact.
-Every CLI query derives its view from the archive on demand without writing a
-cache.
+Every CLI query derives its view from the archive. The first query builds a
+disposable integrity-bound binary index; later queries reuse it while the run
+identity remains valid. The index is an implementation detail and can always be
+deleted and reconstructed.
 These numbers are application- and filesystem-specific optimization baselines.
 An exact matching Vite build is also reused across runs, removing the measured
 4.87-second repeated build; any source/configuration/toolchain-key change falls
@@ -88,8 +104,8 @@ phase and 40.49 seconds total: 0.07 seconds initialization, 0.36 seconds
 workspace refresh, 0.05 seconds adapter setup, 39.84 seconds in the unchanged
 test command, and 0.12 seconds evidence validation/archive publication. Fresh
 process queries for summary, files, and gaps each took 0.16–0.20 seconds on
-this run while writing no cache. Test execution is still the dominant and
-naturally variable part of the total.
+this run before the reusable query index was introduced. Test execution is
+still the dominant and naturally variable part of the total.
 
 ## Isolation strategy trade-offs
 

package/docs/workspace-isolation.md

@@ -16,7 +16,7 @@ is below the project's `.supercov/` directory:
 | `work/<run>/state.json` | In-flight lifecycle record; removed after atomic run publication. |
 | `work/<run>/run-publication/` | Incomplete run staging; atomically renamed or removed on recovery. |
 | `evidence/<run>/` | Loose in-flight evidence; packed and removed after publication. |
-| `runs/<run>/` | Immutable `evidence.raw.gz` (manifest plus raw execution evidence) and `run.json`; retained until explicit prune/clean. Derived query views are never cached. |
+| `runs/<run>/` | Immutable `evidence.raw.gz` (manifest plus raw execution evidence) and `run.json`; retained until explicit `clean`. Derived query views are cached only after their first query. |
 | `cache/instrumented-workspace/<project>/` | Stable physical fallback and provider snapshot cache. |
 | `cache/instrumented-workspace/.<project>.staging-*` | Unpublished cache transaction; removed on error or recovery. |
 | `cache/instrumented-workspace/.<project>.previous-*` | Last complete cache generation during publication; restored or removed on recovery. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Zero-edit, runner-aware coverage completeness for JavaScript test suites",
   "license": "MIT",
   "repository": {
@@ -63,12 +63,12 @@
     "prepublishOnly": "npm run release:check"
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "0.0.13",
-    "@supercov/cli-darwin-x64": "0.0.13",
-    "@supercov/cli-linux-arm64-gnu": "0.0.13",
-    "@supercov/cli-linux-arm64-musl": "0.0.13",
-    "@supercov/cli-linux-x64-gnu": "0.0.13",
-    "@supercov/cli-linux-x64-musl": "0.0.13"
+    "@supercov/cli-darwin-arm64": "0.0.14",
+    "@supercov/cli-darwin-x64": "0.0.14",
+    "@supercov/cli-linux-arm64-gnu": "0.0.14",
+    "@supercov/cli-linux-arm64-musl": "0.0.14",
+    "@supercov/cli-linux-x64-gnu": "0.0.14",
+    "@supercov/cli-linux-x64-musl": "0.0.14"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",

package/runtime/javascript/atomic.js

@@ -1,4 +1,4 @@
-import { mkdirSync, openSync, closeSync, fsyncSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, openSync, closeSync, fsyncSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 function fsyncDirectory(path) {
@@ -38,6 +38,26 @@ export function atomicWriteFileSync(path, data, options) {
         rmSync(temporary, { force: true });
     }
 }
+/** Append one recoverable JSONL record and make the completed line durable. */
+export function appendJsonLineDurableSync(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    const existed = existsSync(path);
+    const descriptor = openSync(path, "a", 0o600);
+    try {
+        writeFileSync(descriptor, data.endsWith("\n") ? data : `${data}\n`);
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    if (!existed)
+        fsyncDirectory(dirname(path));
+}
+/** Append a complete local record; process exit closes it before publication. */
+export function appendJsonLineSync(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, data.endsWith("\n") ? data : `${data}\n`, { mode: 0o600 });
+}
 /** Atomically publish a fully prepared file or directory and persist its entry. */
 export function atomicRenameSync(source, destination) {
     mkdirSync(dirname(destination), { recursive: true });

package/runtime/javascript/launchSupervisor.js

@@ -190,6 +190,7 @@ export function guestCoverageEnvironment(mapping, coverageEnvironment = process.
         ...translated,
         SUPERCOV_PROJECT_ROOT: mapping.guestRoot,
         SUPERCOV_CJS_INTERCEPT: "1",
+        SUPERCOV_DURABLE_EVIDENCE_EACH_TEST: "1",
         NODE_OPTIONS: appendNodeImport(existingEnvironment.NODE_OPTIONS, registerUrl),
     };
 }
@@ -556,6 +557,11 @@ export function installLaunchSupervisor() {
     const originalLoad = moduleLoader._load;
     moduleLoader._load = function supercovCapabilityLoad(request, parent, isMain) {
         const exports = originalLoad.call(this, request, parent, isMain);
+        // A user's test command may itself be implemented by an installed
+        // package. That package can import a VM/container/process SDK without
+        // any project-owned module ever crossing the SDK boundary. Inspect all
+        // newly loaded export graphs (deduplicated by `exportedValues`) so
+        // capability discovery remains provider- and runner-neutral.
         inspectExports(exports);
         return exports;
     };

package/runtime/javascript/playwright.js

@@ -12,10 +12,11 @@ import { mkdirSync, readFileSync, rmSync } from "node:fs";
 import http from "node:http";
 import https from "node:https";
 import { syncBuiltinESMExports } from "node:module";
-import { dirname, relative, resolve, sep } from "node:path";
+import { relative, resolve, sep } from "node:path";
 import * as standardPlaywright from "@playwright/test";
+import * as coverageRuntime from "./runtime.js";
 import { inferTestProvenance } from "./provenance.js";
-import { atomicWriteFileSync } from "./atomic.js";
+import { appendJsonLineDurableSync, appendJsonLineSync } from "./atomic.js";
 import { COVERAGE_PHASE_HEADER, COVERAGE_PHASE_COOKIE, COVERAGE_SCOPE_COOKIE, COVERAGE_SCOPE_HEADER, COVERAGE_CARRIER_ENV, encodeCoverageCarrier, encodeCoverageScope, serverEvidenceDirectory, serverEvidencePath, } from "./transport.js";
 export * from "@playwright/test";
 const generatedTargetModule = "__SUPERCOV_PLAYWRIGHT_MODULE__";
@@ -32,6 +33,8 @@ const adapter = (targetModule === "@playwright/test"
 const base = (adapter[targetTestExport] ?? adapter.test);
 const baseExpect = adapter.expect;
 const GENERATED_EVIDENCE_DIRECTORY = "__SUPERCOV_EVIDENCE_DIRECTORY__";
+const evidenceWriterIdentity = () => (process.env.SUPERCOV_EXECUTION_LOG_SHARD ?? `pid-${process.pid}`)
+    .replace(/[^A-Za-z0-9_-]/g, "_");
 const GENERATED_RUN_ID = "__SUPERCOV_RUN_ID__";
 const PHASE_STORAGE_KEY = "__supercov_phase";
 const ACTION_METHODS = new Set([
@@ -329,6 +332,11 @@ class CoveragePhaseController {
             },
         });
         this.proxyCache.set(target, proxy);
+        // Playwright's built-in `page` fixture is created through the wrapped
+        // worker-scoped browser. The test-scoped fixture sees that proxy again;
+        // treating our own proxy as a fresh target would nest wrappers, emit two
+        // phases for one operation, and perform every browser activation twice.
+        this.proxyCache.set(proxy, proxy);
         return proxy;
     }
     createPhase(kind, operation, causedByPhaseId, source = callerSource()) {
@@ -467,7 +475,7 @@ class CoveragePhaseController {
 let activeController;
 let bridgedAssertionDepth = 0;
 const controllers = new Map();
-const directRuntime = () => globalThis.__SUPERCOV_DIRECT_RUNTIME__;
+const directRuntime = () => globalThis.__SUPERCOV_DIRECT_RUNTIME__ ?? coverageRuntime;
 globalThis.__SUPERCOV_ASSERTION_PHASE_BRIDGE__ = (operation, source, callback) => {
     const controller = activeController;
     const runtime = directRuntime();
@@ -829,8 +837,6 @@ const instrumentedTest = base.extend({
                     // Emit an artifact even when this test touched no application source.
                     // A complete test-to-coverage matrix must also identify tests that are
                     // removable without changing coverage.
-                    const outputPath = testInfo.outputPath("mcdc.json");
-                    mkdirSync(dirname(outputPath), { recursive: true });
                     const testFile = relative(process.cwd(), testInfo.file)
                         .split(sep)
                         .join("/");
@@ -854,7 +860,6 @@ const instrumentedTest = base.extend({
                         server,
                     };
                     const serialized = `${JSON.stringify(payload)}\n`;
-                    atomicWriteFileSync(outputPath, serialized);
                     // Pool runners may cycle-restore a VM immediately after Playwright
                     // exits, which can discard or overwrite the normal artifact copy.
                     // Write one uniquely named, one-shot evidence file to the runner's
@@ -865,10 +870,10 @@ const instrumentedTest = base.extend({
                             : GENERATED_EVIDENCE_DIRECTORY);
                     if (evidenceDirectory) {
                         const resolvedDirectory = resolve(process.cwd(), evidenceDirectory);
-                        const safeTestId = testInfo.testId.replace(/[^a-zA-Z0-9_-]/g, "_");
-                        const testEvidenceDirectory = resolve(resolvedDirectory, `${safeTestId}-${testInfo.retry}`);
-                        mkdirSync(testEvidenceDirectory, { recursive: true });
-                        atomicWriteFileSync(resolve(testEvidenceDirectory, "mcdc.json"), serialized);
+                        const append = process.env.SUPERCOV_DURABLE_EVIDENCE_EACH_TEST === "1"
+                            ? appendJsonLineDurableSync
+                            : appendJsonLineSync;
+                        append(resolve(resolvedDirectory, `playwright-worker-${evidenceWriterIdentity()}-${process.pid}.mcdc.jsonl`), serialized);
                     }
                 }
                 finally {

package/runtime/javascript/playwrightReporter.js

@@ -1,10 +1,12 @@
-import { mkdirSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 import { inferTestProvenance } from "./provenance.js";
-import { atomicWriteFileSync } from "./atomic.js";
+import { appendJsonLineDurableSync, appendJsonLineSync } from "./atomic.js";
 const GENERATED_EVIDENCE_DIRECTORY = "__SUPERCOV_EVIDENCE_DIRECTORY__";
+const evidenceWriterIdentity = () => (process.env.SUPERCOV_EXECUTION_LOG_SHARD ?? `pid-${process.pid}`)
+    .replace(/[^A-Za-z0-9_-]/g, "_");
 /** Records outcomes even when browser or fixture startup fails before coverage. */
 export default class SupercovPlaywrightReporter {
+    records = [];
     onTestEnd(test, result) {
         const evidenceDirectory = process.env["SUPERCOV_EVIDENCE_DIR"] ??
             (GENERATED_EVIDENCE_DIRECTORY.startsWith("__")
@@ -32,9 +34,18 @@ export default class SupercovPlaywrightReporter {
             browser: [],
             server: [],
         };
-        const safeId = test.id.replace(/[^a-zA-Z0-9_-]/g, "_");
-        const directory = resolve(process.cwd(), evidenceDirectory, `playwright-${safeId}-${result.retry}-status`);
-        mkdirSync(directory, { recursive: true });
-        atomicWriteFileSync(resolve(directory, "mcdc.json"), `${JSON.stringify(payload)}\n`);
+        this.records.push(payload);
+    }
+    onEnd() {
+        const evidenceDirectory = process.env["SUPERCOV_EVIDENCE_DIR"] ??
+            (GENERATED_EVIDENCE_DIRECTORY.startsWith("__")
+                ? undefined
+                : GENERATED_EVIDENCE_DIRECTORY);
+        if (!evidenceDirectory || this.records.length === 0)
+            return;
+        const append = process.env.SUPERCOV_DURABLE_EVIDENCE_EACH_TEST === "1"
+            ? appendJsonLineDurableSync
+            : appendJsonLineSync;
+        append(resolve(process.cwd(), evidenceDirectory, `playwright-status-${evidenceWriterIdentity()}-${process.pid}.mcdc.jsonl`), `${this.records.map(record => JSON.stringify(record)).join("\n")}\n`);
     }
 }

package/runtime/javascript/register.mjs

@@ -64,11 +64,18 @@ if (verboseDiagnostics && !process.__SUPERCOV_DIAGNOSTIC_REPORTER__) {
         });
     }
 }
-// Assertion-call instrumentation also uses this runtime in test processes
-// whose application build is handled by Vite or another compiler. Loading it
-// for every isolated test launch keeps node:assert attribution runner-agnostic.
-globalThis.__SUPERCOV_DIRECT_RUNTIME__ ??= await import("./runtime.js");
-process.__SUPERCOV_DIRECT_RUNTIME__ ??= globalThis.__SUPERCOV_DIRECT_RUNTIME__;
+// Runner adapters and instrumented modules import the runtime when they need
+// it. Keeping the preload itself thin avoids evaluating the full collector in
+// npm launchers, web-server supervisors, and other Node children that never
+// execute measured JavaScript.
+if (process.env.SUPERCOV_DURABLE_EVIDENCE_EACH_TEST === "1") {
+    // A translated remote/VM command can execute an ahead-of-run transformed
+    // test through an opaque runner that bypasses the ordinary Playwright or
+    // node:test import boundary. The remote-launch adapter marks that process;
+    // initialize the runtime before its transformed module can evaluate.
+    globalThis.__SUPERCOV_DIRECT_RUNTIME__ ??= await import("./runtime.js");
+    process.__SUPERCOV_DIRECT_RUNTIME__ ??= globalThis.__SUPERCOV_DIRECT_RUNTIME__;
+}
 // Workers are independent Node processes and an explicit `execArgv: []`
 // otherwise strips the preload that supplies the isolated runtime. Preserve
 // every user option while adding exactly one Supercov import.
@@ -107,6 +114,7 @@ const generatedPlaywrightConfig = process.env.SUPERCOV_GENERATED_PLAYWRIGHT_CONF
 const generatedJestConfig = process.env.SUPERCOV_GENERATED_JEST_CONFIG;
 const entrypoint = process.argv[1]?.replaceAll("\\", "/") ?? "";
 const playwrightTarget = process.env.SUPERCOV_PLAYWRIGHT_MODULE;
+const projectRoot = process.env.SUPERCOV_PROJECT_ROOT?.replaceAll("\\", "/").replace(/\/$/, "");
 const nodeTestWrapper = new URL("./nodeTest.js", import.meta.url).href;
 const nodeAssertWrapper = new URL("./nodeAssert.js", import.meta.url).href;
 const nodeAssertStrictWrapper = new URL("./nodeAssertStrict.js", import.meta.url).href;
@@ -190,6 +198,7 @@ if (generatedPlaywrightConfig &&
 }
 if (process.env.SUPERCOV_CJS_INTERCEPT === "1" &&
     process.env.SUPERCOV_INSIDE_PLAYWRIGHT === "1" &&
+    !isPlaywrightEntrypoint &&
     process.env.SUPERCOV_INSIDE_VITEST !== "1" &&
     process.env.VITEST !== "true") {
     const target = playwrightTarget ?? "@playwright/test";
@@ -222,7 +231,18 @@ if (process.env.SUPERCOV_CJS_INTERCEPT === "1" &&
 // itself imports the native built-in from Supercov's generated directory, so
 // only first-party callers are redirected and recursion is impossible.
 if (process.env.SUPERCOV_CJS_INTERCEPT === "1") {
-    const projectRoot = process.env.SUPERCOV_PROJECT_ROOT?.replaceAll("\\", "/").replace(/\/$/, "");
+    const entrypointBelongsToProject = Boolean(projectRoot && entrypoint.startsWith(`${projectRoot}/`));
+    const runnerCanLoadProjectCode = entrypointBelongsToProject ||
+        entrypoint === "" ||
+        process.env.SUPERCOV_INSIDE_VITEST === "1" ||
+        (process.env.SUPERCOV_INSIDE_PLAYWRIGHT === "1" && !isPlaywrightEntrypoint);
+    if (!runnerCanLoadProjectCode) {
+        // Package-manager and Playwright coordinator processes propagate the
+        // preload to their children but never evaluate project test modules.
+        // Their worker/child entrypoints install these synchronous CJS hooks.
+        // Avoid paying to import three runner adapters in every launcher.
+    }
+    else {
     const nodeTestAdapter = await import(__rewriteRelativeImportExtension(nodeTestWrapper));
     const cjsNodeTestAdapter = Object.assign(nodeTestAdapter.test, nodeTestAdapter);
     const nodeAssertAdapter = await import(__rewriteRelativeImportExtension(nodeAssertWrapper));
@@ -248,4 +268,5 @@ if (process.env.SUPERCOV_CJS_INTERCEPT === "1") {
                 : cjsNodeAssertAdapter;
         return originalLoad.call(this, request, parent, isMain);
     };
+    }
 }

package/runtime/javascript/runtime.js

@@ -1014,6 +1014,52 @@ function mcdcEnd(frame, value) {
   }
   return value;
 }
+const directRuntimeApi = {
+  activateCoverageScope,
+  beginBufferedServerEvidence,
+  bindCoverageContext,
+  coverageCarrier,
+  coverageContextEnvironment,
+  coverageContextHeaders,
+  coverageHit,
+  coverageHitV2,
+  coverageSnapshot,
+  decodeProbeV2Vector,
+  defaultEntered,
+  defaultSelected,
+  enableRuntimeSnapshotEvidence,
+  flushBufferedBackgroundEvidence,
+  flushBufferedServerEvidence,
+  loopBegin,
+  loopEnd,
+  loopEntered,
+  mcdcBegin,
+  mcdcCondition,
+  mcdcEnd,
+  mcdcEndV2,
+  optionalCallBegin,
+  optionalCallContinued,
+  optionalCallEnd,
+  optionalCallReached,
+  optionalSelect,
+  parenthesizedAssignmentValue,
+  registerProbeV2,
+  resetCoverage,
+  selectionBegin,
+  selectionEnd,
+  selectionRight,
+  takeNodeAssertionPhases,
+  tryBegin,
+  tryCatch,
+  tryEnd,
+  withCoverageCarrier,
+  withNodeAssertionPhase,
+  withRequestPhase,
+  writeExclusiveBackgroundRecord
+};
+globalThis.__SUPERCOV_DIRECT_RUNTIME__ ??= directRuntimeApi;
+if (typeof process !== "undefined")
+  process.__SUPERCOV_DIRECT_RUNTIME__ ??= directRuntimeApi;
 export {
   activateCoverageScope,
   beginBufferedServerEvidence,