supercov 0.0.16 → 0.0.18

package/docs/getting-started.md

@@ -0,0 +1,145 @@
+# Getting started
+
+Supercov measures coverage for JavaScript, TypeScript, and Rust test suites.
+Prefix the command you already run; no config file, import, or reporter is
+required.
+
+```sh
+npx supercov -- npm test
+```
+
+Everything after `--` is your command, executed exactly as written.
+
+## Requirements
+
+| Requirement | Detail |
+| --- | --- |
+| Node.js | 22 or newer |
+| Project | JavaScript or TypeScript, with a runnable test command |
+| Disk | A `.supercov/` directory in the project root, which Supercov creates |
+
+Nothing else is required. Supercov never contacts a network service, and no
+part of your source or evidence leaves the machine.
+
+## Your first run
+
+From the project root:
+
+```sh
+npx supercov -- npm test
+```
+
+The run prints its phases as it goes — initialization, workspace preparation,
+adapter setup, the instrumented build, your unchanged test command, and
+evidence publication — and finishes by publishing one immutable run under
+`.supercov/runs/<run-id>/`. The run id is a UTC timestamp, so run ids sort
+chronologically.
+
+If the command you normally use is not `npm test`, use that instead:
+
+```sh
+npx supercov -- npx playwright test
+npx supercov -- pnpm test:e2e
+npx supercov -- npm run test:unit && npx supercov -- npm run test:e2e
+```
+
+A single Supercov run can collect several runners. Coverage from a command that
+launches Vitest and Playwright ends up in one run, with each test labelled by
+the runner that executed it.
+
+## Read the result
+
+Start with the summary, then narrow. Every query names one run; `latest`
+selects the newest local run.
+
+```sh
+# What runs exist?
+npx supercov runs --limit 5
+
+# How complete is the newest one?
+npx supercov runs latest
+
+# Which files hold the most open obligations?
+npx supercov runs latest gaps --limit 10
+
+# What exactly is open in one file?
+npx supercov runs latest file app/checkout/session.ts
+```
+
+Output is written for an agent reading a terminal: short, paginated, and
+carrying a copyable next-page command. Add `--json` to any query for the stable
+machine format.
+
+## Add a test and prove it landed
+
+Write a test the normal way, then re-run and compare:
+
+```sh
+npx supercov -- npm test
+npx supercov diff <previous-run-id> latest
+```
+
+`diff` reports what the newer run covers that the older one did not. To check
+one specific test's contribution rather than the whole run:
+
+```sh
+npx supercov runs latest test "rejects a locked order"
+```
+
+## What Supercov writes
+
+Supercov owns two marker-protected locations inside your project:
+
+```text
+.supercov/
+  runs/<run-id>/evidence.raw.gz   exact denominator manifest + raw evidence
+  runs/<run-id>/run.json          fingerprints, phase timings, integrity
+supercov/
+  workspace/<project>/            isolated build namespace, reused between runs
+```
+
+Your source files, test files, runner configuration and ordinary build output
+are never modified, overwritten or rebuilt. Both owned locations carry their
+own gitignore; an existing user `supercov/` directory is never adopted.
+
+Storage is bounded by you, not by a background process:
+
+```sh
+npx supercov clean                      # remove every stored run and build cache
+npx supercov clean --keep 20            # retain the 20 newest runs
+npx supercov clean --keep 20 --dry-run  # show what would be removed
+```
+
+## Choosing what counts
+
+Two options change the meaning of a number rather than its presentation, so
+they are worth knowing early.
+
+`--filter` selects which attempts contribute:
+
+- `all` (default) counts every executed attempt, including attempts that later
+  failed. This matches what conventional coverage tools report.
+- `passed` counts only successful attempts of tests that ultimately passed —
+  verified coverage.
+- `failed` counts only failed attempts, which is useful when diagnosing a flaky
+  test's real execution path.
+
+`--kind` selects a semantic test level such as `e2e`, `integration`,
+`component` or `unit`. Kind is resolved from an explicit `SUPERCOV_TEST_KIND`,
+then the Playwright project name, then the test path, then the runner default.
+Queries record how the label was established, so an inferred kind is never
+presented as one you declared.
+
+Filtered queries recompute every obligation from the selected tests instead of
+filtering an already-computed percentage. This matters most for MC/DC, where a
+witness pair assembled from one unit vector and one end-to-end vector counts for
+the combined suite but not for either level alone.
+
+## Where to go next
+
+- [Agent loop](/docs/agent-loop) — the unattended workflow this is designed for.
+- [CLI reference](/docs/cli) — every command and flag.
+- [Coverage model](/docs/coverage-model) — what an obligation is, and why the
+  denominator is larger than lines and branches.
+- [Supported suites](/docs/supported-suites) — where attribution is exact and
+  where it is aggregate.

package/docs/supported-suites.md

@@ -0,0 +1,119 @@
+# Supported suites
+
+Supercov wraps a test command and instruments the processes it launches.
+Runner support differs by attribution level: exact per-test attribution or
+aggregate coverage.
+
+## Attribution by runner
+
+| Runner | Attribution | Notes |
+| --- | --- | --- |
+| Playwright | Exact per test | Test, worker, retry and outcome scopes. ESM and CommonJS specs in arbitrary directories, plus project-owned fixture packages. |
+| Vitest | Exact per test | Module-import and setup execution is kept as a separate setup scope. |
+| Jest | Exact per test | Including concurrent and parameterized tests. |
+| `node:test` | Exact per test | Through the generated adapter. |
+| AVA, Mocha, other runners | Aggregate only | First-party structural coverage through inherited process instrumentation. Hits are recorded as background rather than guessed onto tests. |
+| Browser component runners without an adapter | Aggregate only | Same boundary, made explicit in the report. |
+
+Adapters are generated into the isolated workspace. Your test imports, reporter
+list and runner configuration are not modified.
+
+A single command may collect several runners into one run. Each test is then
+labelled with the runner that executed it and the semantic kind it belongs to.
+
+## Builds
+
+| Project shape | How instrumentation is applied |
+| --- | --- |
+| Vite or Vitest | Through the existing Vite graph |
+| Next, Turbopack, Webpack, esbuild, SWC, other build commands | Applied to the disposable source copy, then your unchanged build command runs against it |
+| No build step (ESM or CommonJS) | Direct instrumentation of the disposable source copy |
+
+The ordinary application build is never read as an input, overwritten, or
+rebuilt afterwards.
+
+When the complete source, configuration and toolchain fingerprint is unchanged
+between runs, the previous instrumented output and manifest are carried into the
+refreshed workspace and the build is skipped entirely.
+
+### Build-only environment flags
+
+Before the isolated build, Supercov compares the invoked npm, pnpm, yarn or bun
+script with explicit string-valued `process.env` checks in the project's build
+configuration. A semantic match — a `test:preview` script and a
+`process.env.TEST_PREVIEW === "true"` check, for example — activates that
+build-only flag, and the decision is printed before the build. Values are never
+guessed for unrelated environment variables.
+
+## Browsers
+
+The compatibility workflow exercises Chromium, Firefox and WebKit, along with
+Node 22, 24 and 25, Playwright 1.55 and current, Vite 5 and current, Vitest 2
+and current, and modern JavaScript, JSX, TypeScript and TSX syntax fixtures.
+
+The Playwright adapter covers the `page` and `request` fixtures, API request
+contexts, user-created browser contexts and pages, popups and all of their
+frames, dedicated and service workers, WebSocket handshake headers, and
+test-spawned child processes.
+
+For Chromium documents exposed through the page target, a pre-document probe
+installs the action phase before application JavaScript starts. A newly created
+cross-origin iframe may run in a separate target that cannot be safely paused
+during navigation; its earliest probes use a timing fallback until the frame is
+live. This affects action-level causal precision only — never structural
+coverage or test attribution.
+
+## Servers, background work and child processes
+
+Server-side coverage is safe when Playwright runs multiple workers against one
+application server. Every routed request carries a run, worker, test and retry
+scope; Node async context retains that scope and its current phase across
+awaited work; and each worker writes to a distinct attempt path that only its
+own collecting fixture will accept.
+
+Detached work is never dropped silently or guessed onto whichever test is
+active:
+
+- HTTP callbacks inherit the carrier automatically.
+- Child processes inherit it through their environment.
+- Exported queue helpers cover BullMQ, Bee-Queue, pg-boss, Agenda and
+  in-process schedulers.
+- Anything that still arrives without a carrier is persisted under the
+  background scope.
+
+## Remote and containerised execution
+
+Discovery is structural rather than provider-specific. The preload and a
+narrowly gated ESM transform look for a static `build(options)` capability,
+activate only when those options contain a host-to-guest mount that includes the
+isolated project, scope any existing cache or snapshot identity to the run's
+source fingerprint, and follow the returned object graph. A method whose options
+contain `argv`, `cmd` or `command` receives guest-translated Supercov paths and
+a guest-valid Node preload.
+
+The execution log records this process and capability graph, but hashes long or
+multiline arguments so embedded shell bodies and credentials are never
+persisted.
+
+The boundary is explicit: Supercov follows Node child processes, not arbitrary
+non-Node supervisors, and not a remote control plane that never exposes its
+launches to the local process. CommonJS and pure-ESM executor SDKs,
+object-shaped and positional execution APIs, and opaque returned object graphs
+are all covered when a discoverable build capability exposes the workspace mount
+and an execution capability accepts an environment. Anything that hides all
+launch state behind an out-of-process RPC needs a dedicated adapter, and
+Supercov reports missing evidence rather than claiming those paths are covered.
+
+The public regression suite includes provider-neutral CommonJS and pure-ESM
+opaque executors. CI requires Supercov to discover that structure, scope the
+cache identity, translate paths and the Node preload into the guest, run nested
+Vitest and Playwright commands, parse every concurrent trace shard, and produce
+100% fixture coverage.
+
+## Distributed runs
+
+Each shard produces its own immutable run. `supercov merge` combines runs whose
+source, test, dependency, configuration, instrumenter, schema and denominator
+fingerprints match exactly, publishes a new immutable run atomically, and leaves
+every input untouched. Incompatible shards fail with a clear reason instead of
+being averaged together.

package/docs/verification.md

@@ -0,0 +1,102 @@
+# Verification
+
+Supercov instruments source before the test command runs. Seven release gates
+check that the instrumented program matches the original program and that
+coverage calculations are correct. Any failed gate blocks publication.
+
+## 1. Semantic differential execution
+
+Original and instrumented programs are executed in isolated scopes and compared
+on three axes: return values, thrown errors, and the observable order of side
+effects.
+
+The fixtures deliberately target the places where a naive transform breaks:
+getters, proxies, optional calls and `this` binding, computed logical
+assignments, parameter defaults, `try`/`catch`/`finally`, iterator closing,
+switch fallthrough, labelled loops, async functions and generators.
+
+## 2. Deterministic generated corpus
+
+A generated corpus exercises 160 nested combinations of short-circuiting,
+ternaries, coercion and thrown expressions on every run. It is deterministic, so
+a regression reproduces exactly rather than appearing once in CI and never
+again.
+
+## 3. Property testing
+
+Seeded `fast-check` properties generate a further 500 nested expressions and 300
+control-flow executions per run, with shrinking and a reproducible seed printed
+on failure.
+
+## 4. Coverage oracles
+
+Behaviour equivalence is not enough — the numbers have to be right too. Separate
+oracles assert exact decision vectors, MC/DC witnesses and branch alternatives
+independently of what the program does.
+
+## 5. An independent MC/DC implementation
+
+The same three-condition masking-MC/DC golden cases must produce identical
+verdicts under Supercov and under Clang/LLVM source-based MC/DC: 100% for a
+complete witness set and 33.33% for an incomplete one.
+
+This is the gate that matters most. MC/DC has enough subtlety — masking versus
+unique-cause, short-circuit evaluation, compound conditions — that agreement
+with an independently implemented, widely audited toolchain is far stronger
+evidence than any self-consistent test suite.
+
+## 6. TC39 Test262
+
+Release CI shards the pinned Test262 corpus across 16 workers, runs the official
+harness against original and instrumented sources, and rejects any scenario that
+passes originally but fails after transformation.
+
+Some categories are excluded by construction, with reason counts printed for
+every shard:
+
+| Excluded | Why |
+| --- | --- |
+| Module, async and raw tests | Not comparable under the source-rewrite harness |
+| Parse and resolution negatives | The transform never runs on unparseable input |
+| Annex B sloppy-script extensions | Does not apply to the application modules Supercov instruments |
+| `Function.prototype.toString` and function-source coercion | Exact source reflection necessarily observes a source transform |
+
+The last category is handled in the product, not hidden: when application code
+directly coerces or observes a function's source, Supercov leaves that body
+uninstrumented and records a visible `semantic-safety` completeness blocker.
+Dedicated differential fixtures cover the async and generator cases that Test262
+cannot compare.
+
+## 7. Performance budgets
+
+Transform latency, transactional workspace preparation, output expansion and
+runtime probe overhead are each checked against explicit budgets. A change that
+makes instrumentation correct but unusably slow fails the same way a wrong
+answer does.
+
+## Cross-platform and compatibility gates
+
+Alongside the seven correctness gates, the compatibility workflow runs Node 22,
+24 and 25, Playwright 1.55 and current, Vite 5 and current, Vitest 2 and
+current, Chromium, Firefox and WebKit, and modern JavaScript, JSX, TypeScript
+and TSX syntax fixtures.
+
+Filesystem publication, symlink handling, copy fallback, `ENOSPC`, failed
+rename and forced-termination recovery are all exercised on Ubuntu, macOS and
+Windows.
+
+A clean-room gate packs the npm tarball, invokes it through `npx` in a project
+with no build step, and asserts that not a single source or configuration file
+changed.
+
+## Running the gates yourself
+
+```sh
+npm test
+npm run test:clang-mcdc
+npm run benchmark:check
+TEST262_DIR=/path/to/test262 npm run test:test262
+```
+
+The Clang/LLVM oracle requires `clang` and `llvm` to be installed. The Test262
+gate requires a checkout of the pinned corpus.

package/docs/workspace-isolation.md

@@ -1,9 +1,8 @@
 # Workspace isolation
 
-Supercov's primary filesystem guarantee is stronger than “we clean up when the
-command exits”: the user's source and ordinary build artifacts are never
-Supercov's write targets. Cleanup is useful for space, but correctness cannot
-depend on a signal handler running.
+Supercov writes generated and temporary files only under the project's
+`.supercov/` directory. Application source and ordinary build artifacts are
+not write targets, and cleanup does not depend on a signal handler.
 
 ## Owned paths
 
@@ -17,10 +16,10 @@ is below the project's `.supercov/` directory:
 | `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 `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. |
-| `cache/instrumented-workspace/<project>/.supercov/server-evidence/<run>/` | Server/background transport shared with local or mounted guest processes; archived and removed after publication, interruption, refresh, or cleanup. |
+| `supercov/workspace/<project>/` | Stable physical fallback and provider snapshot cache. The non-dotted ancestor keeps Express/`send` and similar static-file stacks semantically unchanged. |
+| `supercov/workspace/.<project>.staging-*` | Unpublished cache transaction; removed on error or recovery. |
+| `supercov/workspace/.<project>.previous-*` | Last complete cache generation during publication; restored or removed on recovery. |
+| `supercov/workspace/<project>/.supercov/server-evidence/<run>/` | Server/background transport shared with local or mounted guest processes; archived and removed after publication, interruption, refresh, or cleanup. |
 
 The lower-level runtime retains `/tmp/supercov-server-evidence` only as a
 fallback when it is embedded without the Supercov CLI and no owned transport
@@ -30,7 +29,10 @@ translation maps that same root into the guest mount.
 ## Current physical fallback
 
 Builds and opaque VM/container mounts currently use a stable physical namespace
-at `.supercov/cache/instrumented-workspace/<project>`. Refresh has four states:
+at `supercov/workspace/<project>`. The `supercov/` container is owned only when
+its exact marker is present; if a project already owns that name, Supercov uses
+a deterministic non-dotted fallback and copies the user's directory as ordinary
+source rather than adopting or excluding it. Refresh has four states:
 
 1. The last complete source generation remains live while a sibling `staging`
    tree is prepared.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Zero-edit, runner-aware coverage completeness for JavaScript test suites",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,10 @@
     "build": "cargo build -p supercov",
     "sync:rust-assets": "node scripts/sync-rust-package-assets.mjs",
     "test:rust-assets": "node scripts/sync-rust-package-assets.mjs --check",
+    "test:rustc-backend-spike": "node scripts/rustc-backend-spike.mjs",
+    "test:rust-compiler-spikes": "cargo build -p supercov && node scripts/rust-libtest-companion-spike.mjs && node scripts/rust-async-attribution-spike.mjs && node scripts/rust-subprocess-attribution-spike.mjs && node scripts/rust-custom-harness-spike.mjs && node scripts/rust-libtest-builder-lifecycle-spike.mjs",
+    "test:rust-cargo-runner": "cargo build -p supercov && node scripts/rust-cargo-runner-integration.mjs",
+    "test:rust-nextest-runner": "cargo build -p supercov && node scripts/rust-nextest-runner-integration.mjs",
     "test": "cargo test --workspace",
     "test:runtime": "node --test tests/runtime/*.test.mjs",
     "test:fixture": "cargo build -p supercov && node scripts/rust-fixture-matrix.mjs",
@@ -63,12 +67,12 @@
     "prepublishOnly": "npm run release:check"
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "0.0.16",
-    "@supercov/cli-darwin-x64": "0.0.16",
-    "@supercov/cli-linux-arm64-gnu": "0.0.16",
-    "@supercov/cli-linux-arm64-musl": "0.0.16",
-    "@supercov/cli-linux-x64-gnu": "0.0.16",
-    "@supercov/cli-linux-x64-musl": "0.0.16"
+    "@supercov/cli-darwin-arm64": "0.0.18",
+    "@supercov/cli-darwin-x64": "0.0.18",
+    "@supercov/cli-linux-arm64-gnu": "0.0.18",
+    "@supercov/cli-linux-arm64-musl": "0.0.18",
+    "@supercov/cli-linux-x64-gnu": "0.0.18",
+    "@supercov/cli-linux-x64-musl": "0.0.18"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",

package/runtime/javascript/launchSupervisor.js

@@ -19,6 +19,17 @@ const importedCapabilityProxies = new WeakMap();
 const importedMemberProxies = new WeakMap();
 let installed = false;
 let remoteLaunchSequence = 0;
+
+function isClassConstructor(value) {
+    if (typeof value !== "function")
+        return false;
+    try {
+        return /^class(?:\s|\{)/u.test(Function.prototype.toString.call(value));
+    }
+    catch {
+        return false;
+    }
+}
 function executionLogPath(path) {
     const shard = (process.env["SUPERCOV_EXECUTION_LOG_SHARD"] ?? "host").replace(/[^A-Za-z0-9_.-]/g, "_");
     const suffix = `.${shard}.${process.pid}.jsonl`;
@@ -275,6 +286,13 @@ function wrapImportedMember(member, receiver, invoke) {
  */
 export function wrapCapabilityCallbacks(value, mapping, depth = 0, seen = new WeakMap()) {
     if (typeof value === "function") {
+        // A class is a nominal value as well as a callable capability. Replacing
+        // it with a Proxy changes strict constructor identity in registries such
+        // as Lexical, ORMs and dependency-injection containers. Static builder
+        // methods are supervised at the export boundary; classes passed through
+        // ordinary configuration must remain the exact original value.
+        if (isClassConstructor(value))
+            return value;
         const cached = seen.get(value);
         if (cached)
             return cached;
@@ -320,6 +338,10 @@ export function wrapCapabilityCallbacks(value, mapping, depth = 0, seen = new We
 export function wrapCapabilityObject(value, mapping) {
     if ((!value || typeof value !== "object") && typeof value !== "function")
         return value;
+    if (isClassConstructor(value)) {
+        patchBuilder(value);
+        return value;
+    }
     const object = value;
     const cached = capabilityProxies.get(object);
     if (cached)
@@ -379,6 +401,10 @@ export function wrapCapabilityObject(value, mapping) {
 export function wrapImportedCapability(value) {
     if ((!value || typeof value !== "object") && typeof value !== "function")
         return value;
+    if (isClassConstructor(value)) {
+        patchBuilder(value);
+        return value;
+    }
     const object = value;
     const cached = importedCapabilityProxies.get(object);
     if (cached)
@@ -408,6 +434,10 @@ export function wrapImportedCapability(value) {
             if (fixed.fixed)
                 return fixed.value;
             const member = Reflect.get(target, property, target);
+            if (isClassConstructor(member)) {
+                patchBuilder(member);
+                return member;
+            }
             if (typeof member !== "function")
                 return wrapImportedCapability(member);
             return wrapImportedMember(member, target, invoke);

package/runtime/javascript/playwright.js

@@ -666,7 +666,7 @@ function wrapMatchers(matchers, path = "expect") {
                         }, (error) => {
                             if (phase && controller)
                                 controller.finish(phase, error);
-                            throw error;
+                            throw coverageRuntime.cleanInstrumentationStack(error);
                         });
                     }
                     if (phase && controller)
@@ -676,7 +676,7 @@ function wrapMatchers(matchers, path = "expect") {
                 catch (error) {
                     if (phase && controller)
                         controller.finish(phase, error);
-                    throw error;
+                    throw coverageRuntime.cleanInstrumentationStack(error);
                 }
             };
         },

package/runtime/javascript/runtime.js

@@ -149,6 +149,7 @@ function createState() {
     serverBuffers: /* @__PURE__ */ new Map(),
     persistedServerRecords: /* @__PURE__ */ new Set(),
     backgroundBuffers: /* @__PURE__ */ new Map(),
+    backgroundWriters: /* @__PURE__ */ new Map(),
     backgroundSequence: 0,
     runtimeSnapshots: false,
     assertionPhases: /* @__PURE__ */ new Map(),
@@ -371,28 +372,12 @@ function flushAllBufferedServerEvidence() {
     flushBufferedBackgroundEvidence(runId);
 }
 function flushBufferedBackgroundEvidence(runId) {
-  var _a8;
   if (isBrowser)
     return void 0;
   const records = state.backgroundBuffers.get(runId);
   if (!records || records.size === 0)
     return void 0;
-  const fs = getFs();
-  if (!fs)
-    return void 0;
-  const directory = backgroundEvidenceDirectory(runId);
-  const shard = (_a8 = process.env["SUPERCOV_EXECUTION_LOG_SHARD"]) != null ? _a8 : "process";
-  const writer = `${shard}-${process.pid}`;
-  const payload = [...records.values()].map((record) => JSON.stringify(record)).join("\n") + "\n";
-  try {
-    fs.mkdirSync(directory, { recursive: true });
-    const nextSequence = writeExclusiveBackgroundRecord(fs, runId, writer, state.backgroundSequence, payload);
-    state.backgroundSequence = nextSequence;
-    state.backgroundBuffers.delete(runId);
-    return backgroundEvidencePath(runId, `${writer}-${nextSequence - 1}`);
-  } catch (e) {
-    return void 0;
-  }
+  return state.backgroundWriters.get(runId);
 }
 function writeExclusiveBackgroundRecord(fs, runId, writer, initialSequence, payload) {
   let sequence = initialSequence;
@@ -409,6 +394,30 @@ function writeExclusiveBackgroundRecord(fs, runId, writer, initialSequence, payl
   }
   throw Object.assign(new Error("Could not allocate a collision-free Supercov background evidence record"), { code: "SUPERCOV_BACKGROUND_COLLISION_LIMIT" });
 }
+function appendDurableBackgroundRecord(fs, runId, record) {
+  var _a8;
+  const records = state.backgroundBuffers.get(runId) != null ? state.backgroundBuffers.get(runId) : /* @__PURE__ */ new Map();
+  const key = serverRecordKey(record);
+  if (records.has(key))
+    return state.backgroundWriters.get(runId);
+  const directory = backgroundEvidenceDirectory(runId);
+  const payload = JSON.stringify(record) + "\n";
+  fs.mkdirSync(directory, { recursive: true });
+  let path = state.backgroundWriters.get(runId);
+  if (!path) {
+    const shard = (_a8 = process.env["SUPERCOV_EXECUTION_LOG_SHARD"]) != null ? _a8 : "process";
+    const writer = `${shard}-${process.pid}`;
+    const nextSequence = writeExclusiveBackgroundRecord(fs, runId, writer, state.backgroundSequence, payload);
+    state.backgroundSequence = nextSequence;
+    path = backgroundEvidencePath(runId, `${writer}-${nextSequence - 1}`);
+    state.backgroundWriters.set(runId, path);
+  } else {
+    fs.appendFileSync(path, payload);
+  }
+  records.set(key, record);
+  state.backgroundBuffers.set(runId, records);
+  return path;
+}
 var _a7;
 if (!isBrowser) {
   const flushers = (_a7 = runtimeGlobal.__SUPERCOV_BUFFER_FLUSHERS__) != null ? _a7 : /* @__PURE__ */ new Set();
@@ -475,18 +484,19 @@ function appendServer(record) {
     if (deduplicationKey && state.persistedServerRecords.has(deduplicationKey))
       return;
     if (!path) {
-      const buffered = (_d = state.backgroundBuffers.get(runId)) != null ? _d : /* @__PURE__ */ new Map();
-      buffered.set(serverRecordKey(serialized), serialized);
-      state.backgroundBuffers.set(runId, buffered);
-      if (buffered.size >= 4096)
-        flushBufferedBackgroundEvidence(runId);
+      appendDurableBackgroundRecord(fs, runId, serialized);
       return;
     }
     fs.mkdirSync(directory, { recursive: true });
     fs.appendFileSync(path, JSON.stringify(serialized) + "\n");
     if (deduplicationKey)
       state.persistedServerRecords.add(deduplicationKey);
-  } catch (e) {
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    const failure = new Error(`Supercov could not persist coverage evidence for run ${runId}: ${detail}`);
+    failure.code = "SUPERCOV_EVIDENCE_TRANSPORT_FAILED";
+    failure.cause = cause;
+    throw failure;
   }
 }
 function environmentRequestContext() {
@@ -542,6 +552,20 @@ function finishAssertionPhase(phase, error) {
   if (error !== void 0)
     phase.error = error instanceof Error ? error.message : String(error);
 }
+
+function cleanInstrumentationStack(error) {
+  if (!error || typeof error !== "object" || typeof error.stack !== "string")
+    return error;
+  const lines = error.stack.split("\n");
+  const visible = lines.filter((line, index) => index === 0 || !/[\\/]\.supercov[\\/](?:playwright|nodeTest|vitest|runtime|launchSupervisor|nodeAssert|nodeAssertStrict|nodeAssertAdapter|register|resolve-loader)\.(?:js|mjs)(?::|\))/u.test(line));
+  if (visible.length !== lines.length) {
+    try {
+      error.stack = visible.join("\n");
+    } catch (e) {
+    }
+  }
+  return error;
+}
 function withNodeAssertionPhase(operation, source, callback) {
   var _a8;
   const context = currentRequestContext();
@@ -571,13 +595,13 @@ function withNodeAssertionPhase(operation, source, callback) {
         return value;
       }, (error) => {
         finishAssertionPhase(phase, error);
-        throw error;
+        throw cleanInstrumentationStack(error);
       });
     finishAssertionPhase(phase);
     return result;
   } catch (error) {
     finishAssertionPhase(phase, error);
-    throw error;
+    throw cleanInstrumentationStack(error);
   }
 }
 function takeNodeAssertionPhases(scope) {
@@ -1021,6 +1045,7 @@ const directRuntimeApi = {
   coverageCarrier,
   coverageContextEnvironment,
   coverageContextHeaders,
+  cleanInstrumentationStack,
   coverageHit,
   coverageHitV2,
   coverageSnapshot,
@@ -1067,6 +1092,7 @@ export {
   coverageCarrier,
   coverageContextEnvironment,
   coverageContextHeaders,
+  cleanInstrumentationStack,
   coverageHit,
   coverageHitV2,
   coverageSnapshot,