supercov 0.0.45 → 0.0.46

package/docs/assertions.md

@@ -1,35 +1,71 @@
 # Understanding 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.
+Assertion coverage helps you see which parts of your JavaScript or TypeScript
+code are checked by tests. After a normal run, your coding agent records what
+each assertion checks in `assertions.json`. Supercov combines that map with the
+run's execution evidence and shows an **Assertions** percentage alongside Lines,
+Branches and MC/DC.
+
+## Start with your existing tests
 
 ```sh supercov
 npx supercov -- npm test
-npx supercov runs latest assertions --json
+npx supercov runs latest assertions
+```
+
+Use your project's test command after `--`. Each run creates its own map and
+reuses compatible work from earlier runs of the same command. The assertions
+list shows the map's path and the assertions that still need attention.
+
+Copy the printed run ID before asking an agent to edit the map. This keeps its
+work on the same run even if another test run finishes. You can give it this
+prompt, replacing `<run-id>` with that ID:
+
+```text
+Read the instructions from npx supercov docs assertion-agent. Build or update
+assertion coverage for run <run-id>. Investigate the tests and current source,
+then edit that run's assertions.json. Preserve reusable flows and explain
+uncertainty. Do not change application code or tests. Validate the map and
+show the assertion percentage, remaining gaps, and any missing evidence.
 ```
 
-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:
+You can use your usual coding agent. Supercov does not require a particular
+model or make model calls itself.
+
+## Read the percentage
 
 ```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>
+npx supercov runs <run-id>
 ```
 
-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.
+An illustrative report might show:
 
-## Check what the test asserts
+```text
+Assertions 62.50% (50/80) — agent-assessed statements, whole run
+  18 assertions with flows; 7 without; 29 current flows; 3 stale; 2 draft
+```
+
+Here, 50 of the run's 80 measured statements have a current explanation linking
+them to a passing assertion, with execution recorded in the same test. Each
+statement counts once, even when several assertions check it. Unexecuted code
+stays in the denominator. TypeScript imports that are known to disappear during
+compilation are excluded.
+
+The score describes the whole run. Filtering Lines or MC/DC by test kind does
+not change the assertion percentage. You do not need to rerun tests just to
+recalculate a map: save it and query the run again.
+
+| Report state | What to do |
+| --- | --- |
+| Not assessed | Ask your agent to start explaining the assertions. |
+| Pending | Inspect changed inputs, draft flows or stale flows before using a percentage. |
+| Unavailable | Check for a failed run, invalid map or source that no longer matches the run. |
+| Not applicable | The run has no measured statements. |
+
+A partially written map can have a useful percentage. Check the counts beside
+it: having some flows does not mean every relevant flow has been found.
+
+## Check what an assertion actually protects
 
 Suppose `src/shipping.js` contains:
 
@@ -39,44 +75,58 @@ export function shippingCost() {
 }
 ```
 
-These checks all call the function, but they test different things. Here,
+These tests all call the function, but they check different things. Here,
 `assert` comes from `node:assert/strict`:
 
 | 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. |
-
-Line coverage can be the same in all three cases. The useful test is the one
-that checks the behavior you need to preserve.
+| `shippingCost(); assert.equal(7, 7)` | Nothing about the returned cost. The assertion compares constants. |
 
-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.
+Line coverage can be the same in all three cases. Even a credited statement can
+change without failing a test when the new value still satisfies the assertion.
+Read the mapped observation when deciding whether a test protects your change.
 
-## Inspect and improve the map
+## Inspect a gap
 
 ```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
+npx supercov runs <run-id> assertions --needs-attention --limit 5
+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> source src/shipping.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.
+An assertion detail shows its exact location in the test, its recorded flows,
+and why each source node is credited, not credited or context only. Use this to
+find a missing scenario, strengthen a weak check or correct an explanation.
+See [Investigating assertion evidence](assertion-evidence.md) when execution
+or a passing assertion is missing.
+
+An absence check, such as “no message was received,” can be useful without
+crediting a message-sending statement that never ran. Its map should explain
+what was observed, when observation ended and why that was sufficient.
+
+## Keep the map when code changes
+
+Run the same suite command again after editing source or tests. Supercov copies
+reusable mappings into the new run and identifies flows that need another look.
+One changed dependency can affect a single flow; changing the assertion itself
+can affect all its flows. Your agent can update those parts instead of starting
+over.
+
+Investigation uses your current project files. A run retains the map and file
+identities, but does not keep a complete source checkout. If the source no
+longer matches, rerun tests before continuing the map.
+
+## Use the score to guide changes
+
+Use MC/DC to find missing condition cases and assertion coverage to investigate
+what those tests check. Improve the weakest observations and the gaps relevant
+to your change, then run the full suite again.
+
+Neither percentage proves that every possible bug will fail a test. A high
+score is most useful together with the recorded observations and a review of
+the behavior you intend to preserve. See [Assertion map format](assertion-maps.md)
+for editing and validation, or [Trusting results](verification.md) for the
+broader test-review workflow.

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.46",
   "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.46",
+    "@supercov/cli-darwin-x64": "0.0.46",
+    "@supercov/cli-linux-arm64-gnu": "0.0.46",
+    "@supercov/cli-linux-arm64-musl": "0.0.46",
+    "@supercov/cli-linux-x64-gnu": "0.0.46",
+    "@supercov/cli-linux-x64-musl": "0.0.46",
+    "@supercov/cli-win32-arm64": "0.0.46",
+    "@supercov/cli-win32-x64": "0.0.46"
   },
   "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