supercov 0.0.26 → 0.0.28

package/docs/verification.md

@@ -1,39 +1,38 @@
-# Verification
+# Trusting a result
 
-Coverage is useful only if instrumentation preserves program behavior and the
-reported obligations match what actually executed. Supercov fails closed when
-it cannot establish either condition.
+Coverage is useful only when the test command still behaves normally and the
+report distinguishes what was covered from what could not be measured.
+Supercov is designed to fail clearly rather than turn uncertainty into a clean
+percentage.
 
-## What release checks cover
+## Review a test written by an agent
 
-Every release is checked for:
+Before merging, check three things:
 
-- identical return values, thrown errors, and side-effect order before and
-  after instrumentation;
-- short-circuiting, getters, proxies, optional calls, `this` binding, defaults,
-  exceptions, loops, async functions, and generators;
-- exact line, branch, decision-vector, and MC/DC results;
-- JavaScript behavior across a pinned TC39 Test262 corpus;
-- supported JavaScript, TypeScript, and Rust runner contracts;
-- Chromium, Firefox, and WebKit browser execution;
-- source isolation, interrupted-run recovery, and atomic publication; and
-- package installation and execution from a clean project.
+1. **The complete wrapped test command passes.** A focused test command is useful
+   during iteration, but it is not the final gate.
+2. **The diff shows the expected gain.** Look for unexplained coverage losses or
+   a changed source boundary.
+3. **The test protects behavior.** It should make a meaningful assertion without
+   weakening existing assertions or changing application code for the metric.
 
-MC/DC cases are also compared with an independent LLVM implementation so a
-self-consistent error in Supercov's own calculation does not pass unnoticed.
+```sh
+npx supercov diff <baseline-run> <new-run>
+npx supercov runs <new-run> test "new test name"
+```
 
-## What happens when code cannot be measured safely
+Keep the compared run ids in the pull request or agent summary when the result
+needs to be reviewed later.
 
-Supercov does not force a transform through code that observes its own source
-text or creates source dynamically without a stable denominator. It leaves the
-affected behavior uninstrumented and records a completeness blocker with the
-reason and location.
+## Read the status honestly
 
-Similarly, evidence from an unsupported runner or hidden remote boundary is
-reported as aggregate, unattributed, or missing. It is not assigned to a test
-that may not have caused it.
+Supercov separates four states:
 
-Inspect these states with:
+- **covered** — the obligation was measured and observed;
+- **uncovered** — it was measured but not observed, so a test may close it;
+- **measurement limit** — Supercov could not establish a complete boundary;
+- **stale** — the run is valid history but no longer describes the current
+  workspace.
 
 ```sh
 npx supercov runs latest
@@ -41,28 +40,43 @@ npx supercov runs latest scope
 npx supercov runs latest gaps
 ```
 
-## How to review a coverage change
+Do not treat a measurement limit as a test-writing task. Read its reason, fix
+source scope or configuration when possible, and otherwise report the boundary.
 
-For a test added by a coding agent, check three things:
+## How Supercov avoids false confidence
 
-1. The wrapped test command still passes.
-2. `diff` shows the expected obligations gained and no unexplained loss.
-3. The test contains meaningful assertions and does not weaken application
-   behavior merely to improve a percentage.
+- The coverage denominator is derived before the suite runs, so adding tests
+  cannot silently redefine 100%.
+- Instrumentation runs in an isolated copy instead of rewriting your source.
+- Evidence is attributed to a test only when the runner exposes a reliable
+  identity; everything else remains aggregate or background evidence.
+- Completed runs are immutable and checked against the current workspace.
+- Missing, corrupt, contradictory, or unsupported evidence is surfaced as a
+  limitation instead of being guessed or discarded.
 
-```sh
-npx supercov diff <baseline-run> <new-run>
-npx supercov runs <new-run> test "new test name"
-```
+## What happens when code cannot be measured safely
+
+Some code observes its own source text, creates source dynamically, or executes
+behind a launcher Supercov cannot see. Forcing ordinary instrumentation through
+those boundaries could change behavior or invent a denominator.
+
+Supercov leaves the affected behavior uninstrumented and reports the location
+and reason. Likewise, coverage from a runner without exact test identity stays
+aggregate instead of being assigned to whichever test happened to be nearby.
+
+## How releases are checked
 
-Store the compared run ids in the review or agent summary when the evidence
-needs to be reproducible later.
+Release checks cover program behavior before and after instrumentation, line and
+branch results, decision vectors and MC/DC, supported JavaScript, TypeScript,
+and Rust runner contracts, Chromium, Firefox, and WebKit execution, clean
+installation, interrupted-run recovery, and isolated publication.
 
-## Integrity of stored runs
+JavaScript behavior is exercised against a pinned TC39 Test262 corpus. MC/DC
+cases are also compared with an independent LLVM implementation so a
+self-consistent calculation error does not pass unnoticed.
 
-Completed runs are immutable and integrity-bound to their evidence,
-fingerprints, and schema. A run whose bytes are missing, corrupt, stale, or
-incompatible is surfaced as such instead of being opened as a plausible report.
+These checks reduce risk; they do not replace reviewing the assertions and
+behavior protected by a new test.
 
-See [Evidence and runs](/docs/evidence) for retention, comparison, and shard
-merging.
+See [Runs and evidence](evidence.md) for immutable run ids, comparisons, and
+retention.

package/docs/workspace-isolation.md

@@ -1,25 +1,18 @@
-# Workspace isolation
+# Files, privacy, and cleanup
 
 Supercov measures an instrumented copy of the project. It does not rewrite the
-source tree you edit or the ordinary build output your project already owns.
+source tree you edit or send your source and coverage evidence to a hosted
+Supercov service.
 
-## What Supercov may write
+## What uses the network
 
-| Location | Purpose |
-| --- | --- |
-| `.supercov/runs/<run-id>/` | Immutable completed runs |
-| `.supercov/work/` | In-progress state and evidence staging |
-| `.supercov/locks/` | Prevents overlapping run and cleanup operations |
-| `supercov/workspace/<project>/` | Marker-protected isolated source and build cache |
-
-Supercov owns these locations only when its exact marker is present. If the
-project already contains a user-created `supercov/` directory, Supercov does
-not adopt or delete it; it chooses a deterministic fallback location instead.
+The first `npx supercov` invocation may contact the npm registry to download the
+package. Your wrapped test command may also use the network if it normally does.
 
-The managed directories contain their own gitignore rules so run evidence and
-instrumented builds do not become normal repository changes.
+The Supercov CLI does not need a Supercov account or upload a coverage run to
+Supercov. Run evidence and query indexes stay on the machine.
 
-## What remains untouched
+## What stays untouched
 
 Supercov does not intentionally edit:
 
@@ -27,33 +20,57 @@ Supercov does not intentionally edit:
 - imports or dependency declarations;
 - test-runner configuration or reporter lists;
 - the project's ordinary build output; or
-- files outside its marker-owned storage.
+- files outside marker-owned Supercov storage.
+
+The wrapped command still has its normal side effects. If `npm test` writes
+snapshots, calls a service, or changes a database, wrapping it does not remove
+that behavior. The isolation guarantee applies to Supercov's instrumentation
+and evidence work.
 
-The wrapped test command can still create anything it normally creates. The
-isolation guarantee applies to Supercov's additional instrumentation, evidence,
-and build work—not to side effects authored into the command itself.
+Files the wrapped command creates or changes inside the isolated workspace are
+synced back to the project after the run, so `supercov -- npm test -- -u`
+updates snapshots in the repository exactly as `npm test -- -u` would. Two
+exceptions are reported instead of applied: changes the command makes to
+instrumented source files (the instrumented copies must never overwrite your
+sources) and deletions (never propagated automatically).
 
-## Repeated runs
+## Files Supercov creates
+
+| Location | What it is for |
+| --- | --- |
+| `.supercov/runs/<run-id>/` | Completed immutable runs |
+| `.supercov/work/` | Temporary state while a run is being prepared |
+| `.supercov/locks/` | Prevents two operations from racing |
+| `.supercov-workspace/workspace/<project>/` | Isolated source and reusable instrumented build cache (safe to delete) |
 
-When source, configuration, dependencies, toolchain, and build mode match,
-Supercov can reuse the isolated instrumented build. Test-only changes do not
-force an unrelated application rebuild.
+Managed directories include Git ignore rules so run evidence and instrumented
+builds do not become ordinary repository changes.
 
-Workspace updates are prepared separately and published only when complete, so
-a failed refresh does not replace the last complete cache with a partial one.
+Supercov owns a directory only when its exact marker is present. If the project
+already has a user-created `supercov/` directory, the CLI chooses a deterministic
+fallback instead of adopting or deleting it.
 
-## Crashes and concurrent commands
+## Repeated runs and the build cache
 
-One project can have one coverage or cleanup transaction at a time. A second
+When source, dependencies, configuration, toolchain, and build mode still
+match, Supercov can reuse the isolated instrumented build. Test-only changes do
+not force an unrelated application rebuild.
+
+Workspace refreshes are prepared separately and become active only when
+complete. An interrupted refresh does not replace the last complete cache with
+partial output.
+
+## Interrupted and overlapping commands
+
+One project can run one coverage or cleanup transaction at a time. A second
 operation fails clearly instead of racing the first.
 
-In-progress state records allow the next command to recover after interruption,
-forced termination, or host restart. Unpublished staging data is discarded;
-completed runs are published atomically and remain immutable.
+After interruption or host restart, the next command recovers unpublished
+staging state. Completed runs remain immutable.
 
-## Cleanup
+## Clean up local data
 
-Preview cleanup before deleting local Supercov data:
+Preview cleanup before removing anything:
 
 ```sh
 npx supercov clean --dry-run
@@ -61,12 +78,16 @@ npx supercov clean --keep 20
 npx supercov clean
 ```
 
-Cleanup follows marker ownership and refuses to race an active run. It does not
-scan for similarly named directories or delete paths supplied by run metadata.
+The final command removes all runs and the isolated build cache. `--keep 20`
+retains the 20 newest runs. Cleanup follows marker ownership, waits for the
+project lock, and does not scan for similarly named directories.
 
 ## Containers and remote workspaces
 
 When a suite launches a container or VM from a mounted workspace, Supercov uses
-the isolated workspace as the source presented to that environment. If an
-executor hides its launch or mount boundary, Supercov reports the limitation
-instead of claiming that unseen code was measured.
+the isolated workspace as the source presented to that environment. The runtime
+must be able to cross the launch boundary and return evidence.
+
+If a remote executor hides the launch or mount boundary, Supercov reports the
+limitation instead of claiming unseen code was measured. See
+[Supported suites](supported-suites.md) for the current boundary.

package/package.json

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