supercov 0.0.45 → 0.0.47

package/docs/assertions.md

@@ -1,82 +1,111 @@
-# Understanding assertion coverage
+# Assertion coverage
 
-After a normal test run, a coding agent can map what each JavaScript or
-TypeScript assertion checks into the run's `assertions.json`. Supercov reads
-that map alongside the recorded execution evidence and displays an assertion
-percentage in the regular coverage report.
+Line coverage shows which code ran. Assertion coverage helps you see what the
+tests checked. Your coding agent traces assertions back to the source, and
+Supercov checks those links against recorded execution from the same test.
 
-```sh supercov
-npx supercov -- npm test
-npx supercov runs latest assertions --json
+Assertion coverage measures JavaScript, TypeScript, Python, Ruby and Rust. The
+map format is the same for every one of them: an assertion is identified by its
+file, line and column, so a project written in more than one language keeps a
+single map.
+
+Python and Ruby report an assertion's line but not its column, so two
+assertions written on one line cannot be told apart and neither is credited.
+Put them on separate lines.
+
+## A passing test can miss a wrong result
+
+This function confirms an order and calculates its total:
+
+```js
+export function checkout(price, quantity) {
+  const total = price * quantity;
+  return { status: 'confirmed', total };
+}
 ```
 
-The run creates the map automatically, reusing the newest available map for the
-same test command and language. Pin the returned run ID and edit `data.map`.
-Ask your agent to follow
-`supercov docs assertion-agent`, read the current project source, and complete the map.
-Then validate and save the acknowledgement tokens for examined flows:
-
-```sh supercov-example
-npx supercov runs <run> assertions validate --json
-# Copy examined expectedBasis tokens into assertions.json; save again.
-npx supercov runs <run> assertions check --require-mappings --require-observed --json
-npx supercov runs <run>
+The test checks the status, but not the total:
+
+```js
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { checkout } from './checkout.js';
+
+test('confirms an order', () => {
+  const order = checkout(25, 2);
+  assert.equal(order.status, 'confirmed');
+});
 ```
 
-The **Assertions** row appears beside Lines, Branches and MC/DC. It is the
-percentage of measured statements credited by current agent-authored flows,
-with exact passing assertion identity and execution in the same test. It uses
-the whole run with matching current source even when structural coverage is filtered. Incomplete
-maps remain useful; unmapped or dirty flows earn no credit.
+Every line in the function runs. The test passes. But it would also pass if the
+total were `49` instead of `50`.
+
+## How the agent finds the gap
+
+1. **Supercov records execution:** which statements ran in each test and which
+   assertions passed.
+2. **Your agent traces each assertion** through the test and source to explain
+   what it checks. It saves those links in the run's `assertions.json` map.
+3. **Supercov checks the map against the run.** A statement needs a current
+   explanation, execution, and a passing assertion in the same test to count.
 
-## Check what the test asserts
+In this example, the agent follows the status assertion back to the returned
+order. It finds no check that reads the total:
 
-Suppose `src/shipping.js` contains:
+- `order.status` → must equal `'confirmed'`.
+- `order.total` → no assertion checks the calculated total.
+
+The agent adds the missing assertion to the existing test:
 
 ```js
-export function shippingCost() {
-  return 4;
-}
+assert.equal(order.total, 50);
 ```
 
-These checks all call the function, but they test different things. Here,
-`assert` comes from `node:assert/strict`:
+It reruns the full suite and updates the map. A total of `49` now fails the
+test: two items at $25 must total $50. Line coverage has not changed, but the
+test now checks the calculation.
+
+## Try it in your project
 
-| Assertion | What it checks |
-| --- | --- |
-| `assert.equal(shippingCost(), 4)` | The cost is exactly `4`. Returning `5` would fail. |
-| `assert.ok(shippingCost())` | The cost is truthy. Returning `5` would still pass. |
-| `shippingCost(); assert.equal(7, 7)` | Nothing about the returned cost. The assertion compares two constants. |
+Open your project in your usual coding agent and paste this prompt. The agent
+can install Supercov and run the commands for you.
+
+```text supercov-prompt
+Read npx supercov docs assertion-agent. Run the full test suite through
+Supercov, then build and validate its assertion map. Find one useful
+missing check and add an assertion for the expected behavior.
+Only change tests; do not weaken existing checks. Rerun the same suite
+and update the map. Show the test change, before-and-after assertion
+coverage, and any uncertainty or missing evidence.
+```
 
-Line coverage can be the same in all three cases. The useful test is the one
-that checks the behavior you need to preserve.
+The agent uses your actual test command after `--`, for example
+`npx supercov -- npm test`. On later runs of the same command, Supercov reuses
+compatible mappings and flags explanations that need another look.
 
-The same applies to other results: checking the number of log calls does not
-check their messages, and checking one substring does not check the whole response.
+## Read the result
 
-## Inspect and improve the map
+The agent can show the summary and the statement-level report for a file:
 
-```sh supercov-example
-npx supercov runs <run> assertions --limit 5
-npx supercov runs <run> assertion <assertion-id>
-npx supercov runs <run> source src/shipping.js
-npx supercov runs <run> assertions --view statements --file src/shipping.js --limit 20
+```sh
+npx supercov runs <run-id>
+npx supercov runs <run-id> assertions report --view statements --file checkout.js
 ```
 
-Each assertion keeps its exact test source anchor, the behavior it observes,
-and flows to explicit production statements. Follow those links when deciding
-whether a test needs another scenario or a stronger assertion. The model owns
-the semantic assessment; Supercov validates syntax, source references, evidence
-and freshness without reconstructing the reasoning.
-
-After changing code or tests, run the same suite command again. Its new map
-automatically carries forward unchanged entries;
-changed or ambiguous references stay dirty until reviewed. Source files are
-read from the project; each run retains file hashes and the map, without storing
-complete source copies. A stale checkout makes assertion coverage unavailable
-until tests are rerun. See the
-[map reference](assertion-maps.md) for the format, commands and limitations.
-
-MC/DC measures independent condition effects. Assertion coverage measures the
-statements linked to checks by the reviewed map. Maximizing either number does
-not prove every edit will fail a test: the exact property in `observes` matters.
+**Assertions** is the percentage of measured source statements linked to
+passing assertions by the agent's map. It is not a count of assertions. Each
+statement counts once; statements that never ran remain in the total.
+
+An unmapped statement is a place to investigate, not proof of a missing test:
+the agent may not have mapped its existing check yet.
+
+The strength of the check still matters. `assert.ok(order.total)` accepts both
+`49` and `50`; `assert.equal(order.total, 50)` distinguishes them. Review the
+expected behavior, not just the percentage.
+
+Supercov does not generate or execute mutated code for this assessment. Unlike
+mutation testing, it does not test whether deliberately introduced bugs are
+caught. The agent's explanations still need review.
+
+For the detailed workflow, see [Mapping assertions with an agent](assertion-agent.md).
+For a result you cannot explain, see [Investigating assertion evidence](assertion-evidence.md).

package/docs/cli.md

@@ -100,20 +100,37 @@ npx supercov runs latest assertions --help
 Assertion queries read the run-owned map. `source <path>` reads the matching current
 file directly. It prints source code with line numbers, preserving indentation;
 add `--json` only when you want structured `{line, text}` items. `--offset` is
-zero-based and `--limit` controls the number of source lines. Source and assertion analysis require the current
-checkout to match the run. Changed source makes assertion coverage unavailable;
-rerun tests to inherit mappings. The old `assertions inventory` and nested
-`assertions source --file` commands are replaced by these resource queries.
-Use read-only `assertions validate --json` to obtain expected acknowledgement tokens.
-After investigating, copy those tokens into `assertions.json`, save, and run
-`assertions check`. The `review` command is removed. `--require-mappings` requires
-a current explanation per recognized passing site, without implying completeness.
-Use `assertions --needs-attention` and `assertions report --view changes` to resume work.
-The regular run summary automatically includes the assertion percentage when
-that map exists, in text and `data.assertionCoverage` JSON. Read
-[Understanding assertion coverage](assertions.md) for the workflow or run
-`npx supercov docs assertion-agent` for instructions to give a coding agent.
-The [map reference](assertion-maps.md) covers syntax and verification gates.
+zero-based and `--limit` controls the number of source lines. Source and assertion
+investigation require current files that match the run. Rerun the suite after
+source changes to inherit the map into a new run.
+
+### Assertion coverage
+
+The regular run summary includes assertion coverage when a map has been
+assessed. JSON reports expose it under `data.assertionCoverage`. Start with
+[Understanding assertion coverage](assertions.md), or use these commands to
+inspect and check a map:
+
+```sh supercov-example
+npx supercov runs <run-id> assertions --needs-attention
+npx supercov runs <run-id> assertion <assertion-id>
+npx supercov runs <run-id> assertions report --view statements --file src/shipping.js
+npx supercov runs <run-id> assertions report --view excludedStatements
+npx supercov runs <run-id> assertions validate --json
+npx supercov runs <run-id> assertions check --require-mappings
+```
+
+Edit the file shown by `assertions`. Validation returns `expectedBasis` tokens;
+after examining a flow, save its token in the map before running `check`.
+`--require-mappings` requires explanations for recognized assertions observed
+passing. Add `--require-observed` when every mapped site and selector should have
+passing evidence, or `--min <percentage>` for a chosen target.
+
+To inspect one large flow, add `--flow <flow-id> --view nodes` or `--view edges`
+to the assertion detail command. `--compact` omits repeated source text from the
+report. Follow the printed next-page command or JSON `pagination.nextOffset`.
+Validation supports `--view flows`, `--view changes` and `--view errors` for large
+maps. The [map reference](assertion-maps.md) describes all fields and gates.
 
 ## Narrow a view
 

package/docs/coverage-model.md

@@ -33,6 +33,7 @@ npx supercov runs latest scope
 | Branch | Did each alternative execute? |
 | Decision vector | Which combinations of boolean conditions occurred? |
 | MC/DC witness | Was each condition shown to affect the decision independently? |
+| Assertion coverage | Which measured statements are linked to passing checks by the agent-authored map? |
 | Value path | Did defaults, optional chains, logical assignments, and similar constructs take each meaningful path? |
 
 The exact obligations depend on the language and source construct. You do not
@@ -71,6 +72,11 @@ does not mean the product has no bugs, the assertions are meaningful, or every
 possible input was tested. Review test quality and user-visible behavior, not
 only the percentage.
 
+TypeScript imports known to disappear during compilation do not add runtime
+statement obligations. The assertion report's `excludedStatements` view lists
+these locations. Imports that still execute, including side-effect imports,
+remain in the denominator.
+
 To review what your JavaScript and TypeScript tests actually check, see
 [Understanding assertions](assertions.md).
 

package/docs/evidence.md

@@ -109,3 +109,31 @@ npx supercov clean
 Preview cleanup first. The final command removes all runs and the isolated build
 cache; `--keep 20` preserves the 20 newest runs. Cleanup removes only
 marker-owned Supercov data.
+
+## Understand test kinds
+
+Reports group tests by kind, such as unit, integration or E2E. Supercov uses
+recognized file names and runner information; a kind is a classification, not
+proof of what the test checks. A name such as `gatewayE2e.test.ts` identifies an
+E2E test. Ambiguous names keep the runner's default, and the report tells you
+how many tests use that default.
+
+If your suite has a known kind, set it when running the command:
+
+```sh supercov-example
+SUPERCOV_TEST_KIND=integration npx supercov -- npm test
+```
+
+Supported values are `unit`, `component`, `integration` and `e2e`. Use separate
+runs when different suites need different classifications.
+
+## When assertion evidence is missing
+
+A test can make assertions without executing measured application code. It
+might check static data or a dependency, or use work performed in shared setup.
+Missing attribution across an asynchronous boundary can also leave a gap.
+
+The assertion detail explains why a mapped node did or did not receive credit.
+Use [Investigating assertion evidence](assertion-evidence.md) to distinguish
+these cases. The report's runtime action-phase counts are separate from the
+assertion map; zero action-phase lines does not mean zero asserted statements.

package/docs/performance.md

@@ -82,3 +82,19 @@ npx supercov clean
 Use `--dry-run` to preview cleanup. Keep enough run history for active reviews
 and automation; remove the cache only when reclaiming space matters more than a
 faster next run.
+
+## Keep assertion investigation fast
+
+Save `assertions.json` and query the run to see the updated score. Supercov does
+not rerun tests or call a model to calculate the report. Repeated queries reuse
+the previous assessment while checking that your source still matches the run.
+Editing the map automatically refreshes that assessment.
+
+For large maps, ask for a short page instead of the whole graph. Within one
+flow, `--view nodes` or `--view edges` pages the details; `--compact` omits repeated
+source text while keeping locations and credit reasons. See
+[Investigating assertion evidence](assertion-evidence.md#read-a-large-flow).
+
+The disposable `assertions.report.cache.json` file lives beside the map. A missing
+or damaged cache is rebuilt. Removing it affects the next query's speed, not
+your saved explanations.

package/docs/supported-suites.md

@@ -45,7 +45,7 @@ Supercov reports the level it actually observed. It does not guess.
 | --- | --- |
 | Playwright | Exact per test, worker, retry, outcome, action, and assertion phase |
 | Vitest | Exact per test, with setup execution kept separate |
-| Jest | Exact per test, including parameterized tests, with the user's own configuration, setup files and reporters kept; `expect` assertions link the evidence they check |
+| Jest | Exact per test, including parameterized tests, with the user's own configuration, setup files and reporters kept; passing `expect` occurrences are identified for assertion maps |
 | `node:test` | Exact per test |
 | AVA and Mocha | Aggregate structural coverage |
 | Other Node-based runners | Aggregate when their processes remain visible to Supercov |
@@ -63,19 +63,15 @@ TypeScript, and TSX are supported.
 Supercov instruments an isolated copy. It does not ask you to add an import,
 reporter, plugin, or alternate build output.
 
-A suite that runs its own compiled output is built before the tests start.
-Supercov reads the tests: one that imports from `dist/`, or launches a package
-script that does—`spawn("npm", ["run", "start"])`, `execSync("npm run
-start")`, or any launch handed to the shell as one string—means the build is
-part of the run, and a `build` script is run inside the isolated copy first.
-Without it the server under test would never exist. A launch that only names a
-build subcommand, such as `vite build`, is not taken as consuming a build.
+If tests import compiled output such as `dist/` or launch a script that uses it,
+Supercov runs the project's build inside the isolated copy before testing.
+Keep using your normal test and build commands. Instrumentation does not
+require changing the project's TypeScript settings.
 
-Instrumented TypeScript is exempt from the host's type policy whether the
-compile is Supercov's own build step or the test command's own `tsc`.
-Instrumentation necessarily rewrites control-flow expressions in ways a type
-checker cannot narrow through, so a project that compiles inside its test
-command builds under measurement exactly as it does without it.
+For assertion maps, Node, Vitest, Jest and Playwright's Node-side assertions
+supply supported passing-occurrence evidence. Custom assertion wrappers and
+browser-side checks can have additional observation limits. See
+[Assertion evidence](assertion-evidence.md) before interpreting a missing occurrence.
 
 ### Browsers, servers, and child processes
 
@@ -114,22 +110,16 @@ whatever was still buffered.
 | cargo-nextest | Exact test, attempt, retry, and binary identity | cargo-nextest 0.9.138 or 0.9.140 |
 
 Supercov preserves Cargo's test selection, scheduling, fail-fast behavior,
-environment, and exit status. Doctests are measured like any other test:
-Supercov stands in for rustdoc during `cargo test --doc`, runs each doctest
-in its own process, and attributes what it executed to that doctest by name.
-With nextest, Supercov is nextest's target runner, so nextest's own
-scheduling, retries and output stay as they are and each attempt is recorded
-separately. The measured source is what rustc compiles: every crate root and
-the modules it reaches through `mod` declarations, `#[path]` attributes and
-literal `include!` calls; a `.rs` file nothing declares as a module, such as
-one embedded with `include_str!`, is left untouched. Statements, functions,
-`if`/`while`/match-guard decisions with their conditions (let chains
-included), match arms, `&&` and `||`, `for` and `while` loops and the `?`
-operator each take a probe; what a thread recorded before it passed an
-`assert!`, `assert_eq!` or `assert_ne!` is linked to that assertion, so the
-report can separate code a test checked from code it merely ran; const contexts and macro expansions stay in the
-denominator behind an explicit limitation. Use the repository's normal flags after the
-wrapped command:
+environment and exit status. Doctests run with their own identities; nextest
+retries remain separate attempts.
+
+Measured source follows the modules rustc compiles, including `#[path]` and
+literal `include!` calls. Undeclared `.rs` files are not treated as application
+modules. Statements, functions, branches, boolean decisions, loops and error
+propagation are measured. Const contexts and macro expansions remain visible
+with explicit measurement limitations.
+
+Use the repository's normal flags after the wrapped command:
 
 ```sh
 npx supercov -- cargo test --workspace
@@ -149,35 +139,22 @@ attribution.
 | pytest-rerunfailures | Exact per attempt; flaky tests are reported as such | |
 | `python -m unittest` | Exact test and setUp/test/tearDown phase identity | Serial in-process; skips and expected failures are recorded; subtest failures roll up to the parent test |
 
-Evidence a test records before its first assertion is linked to that assertion
-when the test passes, so a line reads "linked to a passing assertion" rather
-than "execution only". Under pytest this covers plain `assert` statements,
-through pytest's assertion-pass hook, which Supercov turns on for a rewrite
-cache of its own so plain runs keep theirs, and `pytest.raises` and
-`pytest.warns` blocks; every `unittest` `assert*` method counts under both
-runners. What a test runs after its first assertion is execution only.
-
-Supercov measures Python through CPython's own monitoring interface. Nothing is
-copied, rewritten, or compiled differently: the project runs in place with its
-own interpreter and virtual environment, and Supercov only adds a start-up hook
-through `PYTHONPATH`, a pytest plugin through `PYTEST_PLUGINS`, one pytest
-option (`enable_assertion_pass_hook`) through `PYTEST_ADDOPTS`, and a few
-`SUPERCOV_*` variables. Child interpreters started with `subprocess` or
-`multiprocessing` inherit the exact test identity; threads and thread pools
-carry it through `contextvars`.
-
-Each interpreter writes commit-framed evidence to a process-owned mmap. A hard
-kill preserves completed observations and an incomplete tail is ignored; an
-exhausted transport or corrupt committed frame fails the run closed.
-
-Measured obligations are statements (including several on one line), function
-entry, boolean decisions with MC/DC vectors, `for` and comprehension iteration,
-`and`/`or` short-circuiting, `match` case selection, and `try` completion,
-handler selection and exception propagation, all derived from CPython's own
-instruction positions rather than from exception hooks.
-
-Interpreters launched with `-I`, `-E`, or `-S` ignore `PYTHONPATH` and are not
-measured. Code compiled from strings at runtime has no source obligations.
+Your project runs in place with its own interpreter and virtual environment.
+Supercov adds its monitoring and runner hooks through the process environment;
+you do not need to rewrite tests or configure a different build.
+
+Coverage includes statements, functions, boolean decisions, loops,
+comprehensions, short-circuit operators, `match` cases and exception paths.
+Child interpreters, threads and thread pools can retain the calling test's
+identity. The report also distinguishes execution before a passing assertion
+from later execution. These phase records alone do not prove which values the
+assertion checks.
+
+Interpreters launched with `-I`, `-E` or `-S` ignore the required startup hook
+and are not measured. Code compiled from strings at runtime has no source
+obligations. Completed observations can survive a hard kill, but a corrupt or
+exhausted evidence channel fails the run rather than reporting partial data as
+complete.
 
 ```sh
 npx supercov -- pytest
@@ -197,95 +174,35 @@ npx supercov -- python -m unittest
 | Thread-parallel Minitest (`parallelize_me!`, `parallelize(with: :threads)`) | Probe observations exact per test; line, method and simple-branch observations made while phases overlapped go to the run, declared | |
 | Cucumber | Exact scenario identity (`features/x.feature:LINE`), hook steps as setup/teardown | `cucumber`, `bundle exec cucumber` |
 
-Evidence a test records before its first assertion is linked to that assertion
-when the test passes: Minitest's `assert`/`refute` family, RSpec's
-`expect(...).to` and `not_to` (in Cucumber steps too) and test-unit's
-assertions all count. What a test runs after its first assertion is execution
-only.
-
-Supercov measures Ruby with Ruby's own `Coverage` module plus probe calls it
-splices into application files in memory as they load. Nothing on disk is
-rewritten or copied; the project runs with its own interpreter and bundle, and
-Supercov only adds a `-r` entry to `RUBYOPT` and a few `SUPERCOV_*` variables.
-No insertion adds a line, so backtraces keep their line numbers.
-
-Measured obligations are statements, method definitions, `if`/`unless`/
-ternary/`while`/`until` decisions with MC/DC vectors over `&&`/`||` operands,
-`while`/`until`/`for` iteration and the idiomatic iterator blocks (`each`,
-`map`, `times`, `select`, ...), `&&`/`||`/`||=`/`&&=` short-circuiting,
-`case`/`when`, `case`/`in` and `&.` selection, and `begin`/`rescue` completion,
-handler selection and propagation. `||=` and `&&=` on method-call, index and
-constant targets are exact too: an arrival probe and a right-side probe count
-the skipped side without re-reading the target. Blocks and lambdas are
-statements inside their methods, not function entry points, and that includes
-a `define_method` block: Ruby's own method coverage reports one entry per
-method it defines, but the block's body is measured statement by statement
-instead of as a definition.
-
-A statement on a line Ruby's own line table never counts (`x = case`, a
-multi-line literal assignment, a bare `begin`, `if false`) gets a probe at load
-time instead.
-
-On Ruby 3.4 and newer, Supercov asks the `Coverage` module for line events
-alone. Each test phase is sampled from `Coverage`, and asking for its branch
-and method tables too made every sample rebuild both for every loaded file,
-gems included, which was most of what a Ruby test suite paid under Supercov.
-Instead, the statement that starts a branch body or a method body proves the
-branch, the method and the decision outcome it witnesses, and what has no such
-statement is probed: an `if` without `else`, a modifier `if`, a ternary, `&.`,
-a `case` without `else`, an empty body. Ruby 3.3 cannot apply probes and keeps
-reading `Coverage`'s branch and method keys.
-`if true`/`if false`/`if nil` and other literal predicates are folded the way
-Ruby folds them: no branch, and the dead arm is not an obligation. Code inside
-a `Ractor.new` block gets no probes: a non-main Ractor cannot read the probe
-receiver, so a probe there would raise where the untouched program ran. Its
-lines are still counted; what only a probe could have proven inside it is
-declared unmeasured at the block. A Spring
-preloader started before the run has no hook and fails closed; JRuby and
-TruffleRuby are not supported.
-
-The runtime loads through `RUBYOPT` before Bundler and requires only
-`coverage`, so it never activates a gem an application's Gemfile pins
-differently. Insertions are checked against Ruby itself by a sweep
-(`scripts/ruby-corpus-sweep.sh`, which drives `scripts/ruby-position-sweep.rb`)
-over Ruby's whole standard library and the Rails, Rack, RSpec, Minitest,
-test-unit and Cucumber gems, about 4,300 files installed once into a stable
-corpus directory: every file is transformed and compiled with its line count
-intact, every branch key Ruby 3.3 reads is compared with what Ruby reports for
-the untouched source, and each file is loaded twice, untouched and
-transformed, so the probes are proven to preserve behaviour and define the
-same methods.
-
-A `begin` whose body ends in an expression that can `return` from inside
-itself has its handlers and propagation measured as usual, but its normal
-completion is declared instead of probed unless every branch of that
-expression can carry the probe: Ruby cannot pass such an expression as an
-argument, which is what a probe wrapper does.
-
-Measuring never breaks the program being measured. If a file cannot be
-compiled with its probes, it loads unmodified: Ruby's `Coverage` still
-measures its lines, methods and own branches, and only the obligations a
-probe would have proven are declared for that file. Setting
-`SUPERCOV_RUBY_SKIP_PROBES` to a comma-separated list of path fragments puts
-chosen files on that same path deliberately, which is the escape hatch if
-instrumentation ever disagrees with one of yours.
-
-Ruby 3.3 does not apply its `Coverage` module to code compiled by a load hook,
-so on 3.3 Supercov measures through `Coverage` alone: lines, methods and the
-branches Ruby reports itself. Everything that needs a probe (multi-condition
-decisions, `||=`, loops, `rescue` flow, a second statement on a line) is
-declared unmeasured on that interpreter rather than shown as a gap. Ruby 3.4
-and newer measure everything.
-
-Ruby reads its own coverage as the interpreter exits, and that shapes what a
-stopped process keeps. A process ended by a signal it can catch—`SIGTERM`
-from a test's teardown, `SIGINT`—unwinds through that exit and reports
-everything it measured. A process killed with `SIGKILL`, or one that leaves
-through `exit!`, never gets there and takes with it whatever it observed since
-its last test boundary. Supercov cannot recover that or say which lines it
-would have been, so the run declares that a process did not report, which
-blocks completeness, rather than counting those lines against the code. Stop a
-Ruby server with `SIGTERM`, or wait for it to exit, and it reports.
+Your project runs in place with its own interpreter and bundle. Supercov loads
+through `RUBYOPT`; application files on disk and their backtrace line numbers
+stay unchanged. RSpec, Minitest and test-unit assertions can identify execution
+before a passing assertion. That timing evidence alone does not show which
+values the assertion checks.
+
+Ruby 3.4 and newer support statement, method, branch and MC/DC measurement,
+including loops, iterator blocks, short-circuit operators, pattern matching,
+optional calls and exception paths. Ruby 3.3 supplies Ruby's own line, method
+and branch coverage; obligations requiring additional instrumentation are
+reported as measurement limits.
+
+Some constructs have narrower coverage. Code in a non-main Ractor keeps line
+coverage but may lack other observations. Certain nested-return expressions
+limit normal-completion measurement. Constant predicates are folded as Ruby
+folds them, so unreachable alternatives do not become obligations.
+
+If a file cannot be instrumented safely, Supercov loads it unchanged and reports
+the remaining limits. To apply that fallback to a known incompatible file, set
+`SUPERCOV_RUBY_SKIP_PROBES` to a comma-separated list of path fragments. This
+reduces measurement; it is not a way to claim that skipped obligations are covered.
+
+A Spring preloader started before the run has no coverage hook. Restart it
+within the measured command. JRuby and TruffleRuby are not supported.
+
+Stop test-owned Ruby servers with `SIGTERM` or wait for normal exit so they can
+report their evidence. `SIGKILL` and `exit!` can lose observations since the last
+test boundary. A process that does not report leaves a measurement limit; its
+missing evidence is not counted as uncovered application code.
 
 ```sh
 npx supercov -- rspec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "description": "Coverage for coding agents and software factories \ud83c\udf19",
   "license": "MIT",
   "repository": {
@@ -87,19 +87,21 @@
     "test:python-monitoring": "cargo build -p supercov && node scripts/python-monitoring-integration.mjs",
     "test:ruby-coverage": "cargo build -p supercov && node scripts/ruby-coverage-integration.mjs",
     "test:rust-public-cargo": "cargo build -p supercov && node scripts/rust-public-cargo-integration.mjs",
-    "test:assertion-maps": "cargo build -p supercov && node scripts/assertion-map-schema.mjs --check && node scripts/assertion-map-integration.mjs && node scripts/assertion-map-js-integration.mjs",
-    "test:assertion-maps:js": "cargo build -p supercov && node scripts/assertion-map-schema.mjs --check && node scripts/assertion-map-js-integration.mjs",
-    "sync:assertion-schema": "cargo build -p supercov && node scripts/assertion-map-schema.mjs"
+    "test:assertion-maps": "cargo build -p supercov && node scripts/assertion-map-schema.mjs --check && node scripts/assertion-map-integration.mjs && node scripts/assertion-map-js-integration.mjs && node scripts/assertion-dogfood-integration.mjs",
+    "test:assertion-maps:js": "cargo build -p supercov && node scripts/assertion-map-schema.mjs --check && node scripts/assertion-map-js-integration.mjs && node scripts/assertion-dogfood-integration.mjs",
+    "sync:assertion-schema": "cargo build -p supercov && node scripts/assertion-map-schema.mjs",
+    "docs:sync": "node scripts/sync-docs.mjs",
+    "docs:check": "node scripts/sync-docs.mjs --check"
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "0.0.45",
-    "@supercov/cli-darwin-x64": "0.0.45",
-    "@supercov/cli-linux-arm64-gnu": "0.0.45",
-    "@supercov/cli-linux-arm64-musl": "0.0.45",
-    "@supercov/cli-linux-x64-gnu": "0.0.45",
-    "@supercov/cli-linux-x64-musl": "0.0.45",
-    "@supercov/cli-win32-arm64": "0.0.45",
-    "@supercov/cli-win32-x64": "0.0.45"
+    "@supercov/cli-darwin-arm64": "0.0.47",
+    "@supercov/cli-darwin-x64": "0.0.47",
+    "@supercov/cli-linux-arm64-gnu": "0.0.47",
+    "@supercov/cli-linux-arm64-musl": "0.0.47",
+    "@supercov/cli-linux-x64-gnu": "0.0.47",
+    "@supercov/cli-linux-x64-musl": "0.0.47",
+    "@supercov/cli-win32-arm64": "0.0.47",
+    "@supercov/cli-win32-x64": "0.0.47"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",

package/runtime/javascript/launchSupervisor.mjs

@@ -578,6 +578,11 @@ function injectChildEnvironment(method, args) {
     const environment = existingEnvironment
         ? { ...existingEnvironment, ...inherited }
         : { ...process.env, ...inherited };
+    // The runtime child wrapper has captured the current async test scope in
+    // these options. An inherited setup/unscoped carrier from the launcher
+    // must not overwrite it when we restore the other coverage variables.
+    if (existingEnvironment?.SUPERCOV_CONTEXT !== undefined)
+        environment.SUPERCOV_CONTEXT = existingEnvironment.SUPERCOV_CONTEXT;
     // The register path must come from THIS module's own location, never from
     // the environment or the working directory. Monorepo runners both defeat
     // the old derivation at once: turbo's strict env strips SUPERCOV_PROJECT_ROOT