branchproof 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c76fa40f75fbd8122fc0fbb45a1c9d460fa3478f783951674e0e4c2707d44175
-  data.tar.gz: b4b0b88c1a0d5e61797ab52174f1841c57f1dde359d405dc1205bcff27810968
+  metadata.gz: 59c4f3efbd178f68f3137bae18e75de19ebc39e2ffc7873a2d84c9d5ce442b05
+  data.tar.gz: 26247e830fecbf4cdd2dd2c0eb5c50838cbe02de06f919ba7dced1c44252fd2d
 SHA512:
-  metadata.gz: c32db269cece96c843093cc72accffd3921e56eb2a6b974b61c2d87cd696444ffd0d7fff25ed50ac3c5cadf2e6c316ccfd99aaf4f6c28344112c30451cf8e22a
-  data.tar.gz: 54a46ff6c7a753e2015bdb814d13fc576bc2d9bd88fa18d0bb4bee8f1f939fbcea62b9f006d31a3c5e99ac0d9c95de8a8bbea8d43db05c1a767c3ff828430f8b
+  metadata.gz: e39262ef9fb55f10d3760a1e72cdff4a159f62d199d57729a19cd93b2df2720ceacf1e87317094cab76d3e15427d0e19c6dfe6968f781b7d35ff2f934d0171d5
+  data.tar.gz: f8e73473d13a6c15ba5890e0613848a1fe71d4cd092f8633ce707f1be7d63b566e9cef854bd35551ded41d2e5cd84e753932ce7f2db8e6348e7a1eba34e690e1

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-18
+
+- Measure contextual predicates, guarded pattern selection, dynamic case splat
+  groups, required pattern matching, and safe-navigation compound assignment.
+- Add coverage for rescue paths, optional argument binding, standalone
+  predicates, value alternatives, iteration, and source-visible callbacks.
+- Preserve Boolean criteria for Boolean decisions and report other choices as
+  alternative coverage, including their source locations and supporting tests.
+- Exercise 144 Ruby construct fixtures and 406 native cases across source inventory, native behavior,
+  runtime evidence, analysis, reports, saved reports, and CLI integration.
+- Preserve nonlocal control transfers on the right side of logical expressions.
+- Harden default-argument, exception, and iteration instrumentation around
+  implicit parameters, nonlocal transfers, nested frames, and deferred callbacks.
+- Remove unreachable integer bitwise alternatives and keep their exclusions out
+  of coverage denominators.
+- Cache repeated value evidence while preserving vector counts, test/phase
+  attribution, and saved-report coverage semantics.
+
 ## [0.8.0] - 2026-09-17
 
 - Derive a reduced decision table for every supported Boolean decision from its

data/README.md

@@ -542,6 +542,13 @@ ID. Repeated equivalent executions aggregate into a vector's `count`, retaining
 the supporting tests. Ternary outcomes likewise describe the predicate, not
 the value returned by the chosen branch.
 
+Value decisions remain enabled by default. For each decision, evidence caches
+the most recent successful completed trace, keyed by its observations, outcome,
+test, and phase. Consecutive equivalent executions increment vector and phase
+counts without repeating serialization and digest work. When observations,
+test, or phase changes, the execution is recorded normally, so alternating
+traces retain their full evidence and attribution.
+
 Other constructs use alternative coverage, separate from MC/DC:
 
 | Construct | Kind | Context | Required alternatives |
@@ -551,6 +558,18 @@ Other constructs use alternative coverage, separate from MC/DC:
 | `receiver&.method` | `implicit` | `safe_navigation` | Receiver nil / non-nil |
 | `lhs ||= rhs` | `implicit` | `or_assignment` | RHS skipped / executed |
 | `lhs &&= rhs` | `implicit` | `and_assignment` | RHS skipped / executed |
+| `receiver&.value ||= rhs` / `&&=` | `multiway` | `or_assignment` / `and_assignment` | Receiver nil / RHS skipped / RHS evaluated |
+| `value => pattern` | `pattern` | `required_pattern` | Matched / mismatch |
+| Rescue regions | `exception` | `rescue` | Normal completion / rescue clause / unhandled exception |
+| Optional positional and keyword arguments | `implicit` | `default_argument` | Supplied / default evaluated |
+| Standalone predicate calls | `implicit` | `predicate` | Falsey / truthy result |
+| `<=>` | `multiway` | `comparison` | Negative / zero / positive / nil |
+| `[]` lookup | `multiway` | `lookup` | Truthy / false / nil result |
+| `send`, `public_send`, and `__send__` | `implicit` | `dispatch` | Successful return / exception |
+| Regular-expression match capture | `implicit` | `match_capture` | False / true |
+| Iterator bodies | `implicit` | `iteration` | Empty / entered |
+| Lazy iterator callbacks | `multiway` | `lazy_callback` | Callback entered |
+| `fetch` with a fallback block | `implicit` | `fetch_fallback` | Value present / fallback entered |
 
 Each safe-navigation operation in a chain is a distinct decision. Assignment
 instrumentation preserves Ruby's native local, instance, class, global,
@@ -572,16 +591,30 @@ that fails before choosing a branch is aborted, not counted as a selected
 alternative. Selected branches and assignment paths remain observed even when
 their bodies or right-hand sides subsequently raise or return.
 
-Unsupported syntax stays visible and outside coverage denominators. Current
-exclusions include guarded `case/in` (`unsupported_pattern_guard`), dynamic
-`when` splats (`unsupported_case_splat`), safe-navigation compound assignment
-(`unsupported_assignment_target`), and rescue alternatives
-(`unsupported_rescue_control_flow`). A guard predicate can still supply Boolean
-evidence when Ruby evaluates it; an unsupported guarded case does not claim
-pattern-match coverage from that evidence. Flip-flops remain
-`unsupported_flip_flop`. Decisions inside `defined?`, contextual regular
-expressions, heredocs, unsafe predicates, and limit overflows retain explicit
-exclusions. Ruby-defined custom `!` methods keep their runtime behavior;
+Guarded pattern alternatives measure the selected clause, including guard
+acceptance. The guard also supplies Boolean evidence when Ruby evaluates it.
+A dynamic `when *candidates` is one static candidate group; the report does not
+claim coverage of individual elements in that runtime collection.
+
+Flip-flops and implicit regular-expression conditions retain Ruby's conditional
+semantics and contribute one atomic predicate outcome. `defined?` measures its
+result without evaluating or instrumenting the operand. Standalone predicate
+calls record returned truthiness as alternative coverage; they do not claim
+short-circuit conditions or coverage of library internals. Eager bitwise `&`,
+`|`, and `^` are excluded because integer results do not represent Ruby
+truthiness decisions: integer `0` is truthy in Ruby. These expressions add no
+decisions or coverage obligations.
+Dynamic dispatch records completion or exception, and preserves the original
+return value. Lazy callback observations arise only when the callback runs.
+Lookup coverage cannot distinguish an absent key from a stored nil; `fetch`
+fallback coverage measures that separate absence-based choice.
+Optional argument probes use generated local flags and preserve parameter
+signatures, defaults, and existing local bindings. Code that enumerates its own
+local variables can see these instrumentation locals.
+
+Unsupported syntax stays visible and outside coverage denominators. Heredocs,
+unsafe predicates, data sections, and limit overflows retain explicit exclusions.
+Ruby-defined custom `!` methods keep their runtime behavior;
 evidence that contradicts Boolean negation is rejected instead of proving
 coverage with an invalid logical model.
 

data/doc/Branchproof/DefaultInstrumentation.md

@@ -0,0 +1,13 @@
+# Module Branchproof::DefaultInstrumentation <a id="module-Branchproof-DefaultInstrumentation"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/default_instrumentation.rb |
+
+Defaults stay inline in their original lexical scope. The owner decision makes
+body entry edits part of the same original AST edit tree as the parameter
+expression edits.
+
+## Public Instance Methods
+### `rewrite(unit:)` <a id="method-i-rewrite"></a> <a id="rewrite-instance_method"></a>
+Not documented.

data/doc/Branchproof/DefaultRuntime.md

@@ -0,0 +1,11 @@
+# Module Branchproof::DefaultRuntime <a id="module-Branchproof-DefaultRuntime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/default_runtime.rb |
+
+Binding events are immediate; no pending state survives a failed default.
+
+## Public Instance Methods
+### `default_binding(decision_id, index)` <a id="method-i-default_binding"></a> <a id="default_binding-instance_method"></a>
+Not documented.

data/doc/Branchproof/DefaultSyntax.md

@@ -0,0 +1,7 @@
+# Module Branchproof::DefaultSyntax <a id="module-Branchproof-DefaultSyntax"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/default_syntax.rb |
+
+Each optional parameter has an independent supplied/defaulted obligation.

data/doc/Branchproof/ExceptionInstrumentation.md

@@ -0,0 +1,9 @@
+# Module Branchproof::ExceptionInstrumentation <a id="module-Branchproof-ExceptionInstrumentation"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/exception_instrumentation.rb |
+
+Textual edits for native rescue control flow.  The edits only add calls at
+Ruby's own protected-region and handler boundaries; exception matching, `$!`,
+retry, ensure ordering, and nonlocal transfers remain Ruby-owned.

data/doc/Branchproof/ExceptionRuntime.md

@@ -0,0 +1,27 @@
+# Module Branchproof::ExceptionRuntime <a id="module-Branchproof-ExceptionRuntime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/exception_runtime.rb |
+
+Record native clause selection and escaping exceptions. Generated wrappers
+re-raise the same exception; nonlocal transfers remain aborted observations.
+
+## Public Instance Methods
+### `exception_enter(decision_id, unhandled_index)` <a id="method-i-exception_enter"></a> <a id="exception_enter-instance_method"></a>
+Not documented.
+
+### `exception_finish(decision_id, value)` <a id="method-i-exception_finish"></a> <a id="exception_finish-instance_method"></a>
+Not documented.
+
+### `exception_leave(decision_id)` <a id="method-i-exception_leave"></a> <a id="exception_leave-instance_method"></a>
+Not documented.
+
+### `exception_path(decision_id, index)` <a id="method-i-exception_path"></a> <a id="exception_path-instance_method"></a>
+Not documented.
+
+### `exception_unhandled(decision_id)` <a id="method-i-exception_unhandled"></a> <a id="exception_unhandled-instance_method"></a>
+Not documented.
+
+### `exception_value(decision_id, value, index)` <a id="method-i-exception_value"></a> <a id="exception_value-instance_method"></a>
+Not documented.

data/doc/Branchproof/ExceptionSyntax.md

@@ -0,0 +1,9 @@
+# Module Branchproof::ExceptionSyntax <a id="module-Branchproof-ExceptionSyntax"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/exception_syntax.rb |
+
+Replaces unsupported standalone rescue-clause records with decisions for
+Ruby's enclosing protected region.  Ruby chooses a rescue clause as part of
+executing BeginNode; a RescueNode by itself is not executable syntax.

data/doc/Branchproof/ExtendedAlternativeRuntime.md

@@ -0,0 +1,19 @@
+# Module Branchproof::ExtendedAlternativeRuntime <a id="module-Branchproof-ExtendedAlternativeRuntime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/extended_alternative_runtime.rb |
+
+Runtime hooks for decisions whose native evaluation has a third path. Runtime
+includes this module explicitly; it is kept separate so the ordinary two-path
+helpers remain unchanged.
+
+## Public Instance Methods
+### `flow_assignment_finish(decision_id, value, default_path = nil)` <a id="method-i-flow_assignment_finish"></a> <a id="flow_assignment_finish-instance_method"></a>
+Not documented.
+
+### `flow_assignment_path(decision_id, index)` <a id="method-i-flow_assignment_path"></a> <a id="flow_assignment_path-instance_method"></a>
+Not documented.
+
+### `flow_assignment_receiver(decision_id, receiver)` <a id="method-i-flow_assignment_receiver"></a> <a id="flow_assignment_receiver-instance_method"></a>
+Not documented.

data/doc/Branchproof/Instrumenter.md

@@ -3,7 +3,7 @@
 |  |  |
 | --- | --- |
 | **Inherits** | Object |
-| **Includes** | [Branchproof::FlowInstrumentation](FlowInstrumentation.md) |
+| **Includes** | [Branchproof::DefaultInstrumentation](DefaultInstrumentation.md), [Branchproof::ExceptionInstrumentation](ExceptionInstrumentation.md), [Branchproof::FlowInstrumentation](FlowInstrumentation.md), [Branchproof::IterationInstrumentation](IterationInstrumentation.md), [Branchproof::ValueInstrumentation](ValueInstrumentation.md) |
 | **Defined in** | lib/branchproof/instrumenter.rb |
 
 Applies the smallest possible source edits around inventoried expressions. The

data/doc/Branchproof/IterationInstrumentation.md

@@ -0,0 +1,7 @@
+# Module Branchproof::IterationInstrumentation <a id="module-Branchproof-IterationInstrumentation"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/iteration_instrumentation.rb |
+
+Keep matching and iteration in the original lexical scope.

data/doc/Branchproof/IterationRuntime.md

@@ -0,0 +1,21 @@
+# Module Branchproof::IterationRuntime <a id="module-Branchproof-IterationRuntime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/iteration_runtime.rb |
+
+Runtime support for callback based iteration, including lazy receivers whose
+callbacks execute after the constructing call has returned.
+
+## Public Instance Methods
+### `flow_iteration_begin(decision_id, receiver, alternative_count = 2)` <a id="method-i-flow_iteration_begin"></a> <a id="flow_iteration_begin-instance_method"></a>
+Not documented.
+
+### `flow_iteration_callback(decision_id, alternative_count = 2)` <a id="method-i-flow_iteration_callback"></a> <a id="flow_iteration_callback-instance_method"></a>
+rubocop:disable-next Metrics/MethodLength
+
+### `flow_iteration_finish(decision_id, value, default_path = nil)` <a id="method-i-flow_iteration_finish"></a> <a id="flow_iteration_finish-instance_method"></a>
+Not documented.
+
+### `flow_iteration_leave(decision_id)` <a id="method-i-flow_iteration_leave"></a> <a id="flow_iteration_leave-instance_method"></a>
+Not documented.

data/doc/Branchproof/IterationSyntax.md

@@ -0,0 +1,11 @@
+# Module Branchproof::IterationSyntax <a id="module-Branchproof-IterationSyntax"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/iteration_syntax.rb |
+
+Observe entry into source-visible callback bodies, not library internals.
+
+## Constants
+### `ITERATORS` <a id="constant-ITERATORS"></a> <a id="ITERATORS-constant"></a>
+Not documented.

data/doc/Branchproof/Runtime.md

@@ -2,7 +2,7 @@
 
 |  |  |
 | --- | --- |
-| **Extended by** | [Branchproof::RuntimeFlow](RuntimeFlow.md) |
+| **Extended by** | [Branchproof::DefaultRuntime](DefaultRuntime.md), [Branchproof::ExceptionRuntime](ExceptionRuntime.md), [Branchproof::ExtendedAlternativeRuntime](ExtendedAlternativeRuntime.md), [Branchproof::IterationRuntime](IterationRuntime.md), [Branchproof::RuntimeFlow](RuntimeFlow.md), [Branchproof::ValueRuntime](ValueRuntime.md) |
 | **Defined in** | lib/branchproof/runtime.rb |
 
 Process-local execution recorder. It deliberately never coerces or stores
@@ -23,21 +23,66 @@ Not documented.
 ### `context(test_id:, phase:)` <a id="method-c-context"></a> <a id="context-class_method"></a>
 Not documented.
 
+### `default_binding(decision_id, index)` <a id="method-c-default_binding"></a> <a id="default_binding-class_method"></a>
+Not documented.
+
 ### `diagnostics()` <a id="method-c-diagnostics"></a> <a id="diagnostics-class_method"></a>
 Not documented.
 
+### `dispatch_path(decision_id, value, raised)` <a id="method-c-dispatch_path"></a> <a id="dispatch_path-class_method"></a>
+Not documented.
+
 ### `enter(decision_id)` <a id="method-c-enter"></a> <a id="enter-class_method"></a>
 Not documented.
 
+### `exception_enter(decision_id, unhandled_index)` <a id="method-c-exception_enter"></a> <a id="exception_enter-class_method"></a>
+Not documented.
+
+### `exception_finish(decision_id, value)` <a id="method-c-exception_finish"></a> <a id="exception_finish-class_method"></a>
+Not documented.
+
+### `exception_leave(decision_id)` <a id="method-c-exception_leave"></a> <a id="exception_leave-class_method"></a>
+Not documented.
+
+### `exception_path(decision_id, index)` <a id="method-c-exception_path"></a> <a id="exception_path-class_method"></a>
+Not documented.
+
+### `exception_unhandled(decision_id)` <a id="method-c-exception_unhandled"></a> <a id="exception_unhandled-class_method"></a>
+Not documented.
+
+### `exception_value(decision_id, value, index)` <a id="method-c-exception_value"></a> <a id="exception_value-class_method"></a>
+Not documented.
+
 ### `finish(decision_id, value)` <a id="method-c-finish"></a> <a id="finish-class_method"></a>
 Not documented.
 
+### `flow_assignment_finish(decision_id, value, default_path = nil)` <a id="method-c-flow_assignment_finish"></a> <a id="flow_assignment_finish-class_method"></a>
+Not documented.
+
+### `flow_assignment_path(decision_id, index)` <a id="method-c-flow_assignment_path"></a> <a id="flow_assignment_path-class_method"></a>
+Not documented.
+
+### `flow_assignment_receiver(decision_id, receiver)` <a id="method-c-flow_assignment_receiver"></a> <a id="flow_assignment_receiver-class_method"></a>
+Not documented.
+
 ### `flow_candidate(decision_id, index)` <a id="method-c-flow_candidate"></a> <a id="flow_candidate-class_method"></a>
 Not documented.
 
 ### `flow_finish(decision_id, value, default_path = nil)` <a id="method-c-flow_finish"></a> <a id="flow_finish-class_method"></a>
 Not documented.
 
+### `flow_iteration_begin(decision_id, receiver, alternative_count = 2)` <a id="method-c-flow_iteration_begin"></a> <a id="flow_iteration_begin-class_method"></a>
+Not documented.
+
+### `flow_iteration_callback(decision_id, alternative_count = 2)` <a id="method-c-flow_iteration_callback"></a> <a id="flow_iteration_callback-class_method"></a>
+rubocop:disable-next Metrics/MethodLength
+
+### `flow_iteration_finish(decision_id, value, default_path = nil)` <a id="method-c-flow_iteration_finish"></a> <a id="flow_iteration_finish-class_method"></a>
+Not documented.
+
+### `flow_iteration_leave(decision_id)` <a id="method-c-flow_iteration_leave"></a> <a id="flow_iteration_leave-class_method"></a>
+Not documented.
+
 ### `flow_path(decision_id, index)` <a id="method-c-flow_path"></a> <a id="flow_path-class_method"></a>
 Not documented.
 
@@ -56,5 +101,15 @@ Not documented.
 ### `register_test(test:)` <a id="method-c-register_test"></a> <a id="register_test-class_method"></a>
 Not documented.
 
+### `set_alternative_count(decision_id, count)` <a id="method-c-set_alternative_count"></a> <a id="set_alternative_count-class_method"></a>
+rubocop:enable Style/CaseEquality, Metrics/CyclomaticComplexity,
+Metrics/PerceivedComplexity
+
 ### `snapshot()` <a id="method-c-snapshot"></a> <a id="snapshot-class_method"></a>
 Not documented.
+
+### `value_path(decision_id, value, domain)` <a id="method-c-value_path"></a> <a id="value_path-class_method"></a>
+rubocop:disable-next Metrics/MethodLength -- trace state branches are
+explicit. rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity,
+Metrics/PerceivedComplexity -- domain dispatch mirrors the observable value
+contract.

data/doc/Branchproof/Source.md

@@ -3,7 +3,7 @@
 |  |  |
 | --- | --- |
 | **Inherits** | Object |
-| **Includes** | [Branchproof::DecisionSyntax](DecisionSyntax.md) |
+| **Includes** | [Branchproof::DecisionSyntax](DecisionSyntax.md), [Branchproof::DefaultSyntax](DefaultSyntax.md), [Branchproof::ExceptionSyntax](ExceptionSyntax.md), [Branchproof::IterationSyntax](IterationSyntax.md), [Branchproof::ValueSyntax](ValueSyntax.md) |
 | **Defined in** | lib/branchproof/source.rb |
 
 Inventories supported condition and decision occurrences from Ruby files.
@@ -22,3 +22,9 @@ Returns the value of attribute root.
 
 ### `inventory(paths:)` <a id="method-i-inventory"></a> <a id="inventory-instance_method"></a>
 - **@raise** [ArgumentError]
+
+### `value_decisions_for(program, bytes, source_id, nodes: = nil, occupied_ranges: = {}, file_reasons: = [], encoding: = "UTF-8")` <a id="method-i-value_decisions_for"></a> <a id="value_decisions_for-instance_method"></a>
+<code>nodes:</code> is supplied by Source's fused AST walk. It remains
+optional for the standalone discovery API used by focused syntax tests.
+rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists -- source
+seam mirrors Source#decisions_for.

data/doc/Branchproof/ValueInstrumentation.md

@@ -0,0 +1,7 @@
+# Module Branchproof::ValueInstrumentation <a id="module-Branchproof-ValueInstrumentation"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/value_instrumentation.rb |
+
+Source rewrite for value observations; it preserves the wrapped value.

data/doc/Branchproof/ValueRuntime.md

@@ -0,0 +1,26 @@
+# Module Branchproof::ValueRuntime <a id="module-Branchproof-ValueRuntime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/value_runtime.rb |
+
+Runtime mapping for value observations.
+
+## Public Class Methods
+### `comparison_index(value)` <a id="method-c-comparison_index"></a> <a id="comparison_index-class_method"></a>
+rubocop:disable Style/CaseEquality, Metrics/CyclomaticComplexity,
+Metrics/PerceivedComplexity
+
+## Public Instance Methods
+### `dispatch_path(decision_id, value, raised)` <a id="method-i-dispatch_path"></a> <a id="dispatch_path-instance_method"></a>
+Not documented.
+
+### `set_alternative_count(decision_id, count)` <a id="method-i-set_alternative_count"></a> <a id="set_alternative_count-instance_method"></a>
+rubocop:enable Style/CaseEquality, Metrics/CyclomaticComplexity,
+Metrics/PerceivedComplexity
+
+### `value_path(decision_id, value, domain)` <a id="method-i-value_path"></a> <a id="value_path-instance_method"></a>
+rubocop:disable-next Metrics/MethodLength -- trace state branches are
+explicit. rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity,
+Metrics/PerceivedComplexity -- domain dispatch mirrors the observable value
+contract.

data/doc/Branchproof/ValueSyntax.md

@@ -0,0 +1,26 @@
+# Module Branchproof::ValueSyntax <a id="module-Branchproof-ValueSyntax"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/value_syntax.rb |
+
+Inventory for expressions whose result is itself the observable value. This
+deliberately excludes control-flow predicates already owned by Source.
+
+## Constants
+### `BOOLEAN_OPERATORS` <a id="constant-BOOLEAN_OPERATORS"></a> <a id="BOOLEAN_OPERATORS-constant"></a>
+Not documented.
+
+### `DISPATCH_METHODS` <a id="constant-DISPATCH_METHODS"></a> <a id="DISPATCH_METHODS-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `additional_decisions_for(program, bytes, source_id, file_reasons, encoding, decisions:, collected:)` <a id="method-i-additional_decisions_for"></a> <a id="additional_decisions_for-instance_method"></a>
+rubocop:disable-next Metrics/ParameterLists -- source seam mirrors
+Source#decisions_for.
+
+### `value_decisions_for(program, bytes, source_id, nodes: = nil, occupied_ranges: = {}, file_reasons: = [], encoding: = "UTF-8")` <a id="method-i-value_decisions_for"></a> <a id="value_decisions_for-instance_method"></a>
+<code>nodes:</code> is supplied by Source's fused AST walk. It remains
+optional for the standalone discovery API used by focused syntax tests.
+rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists -- source
+seam mirrors Source#decisions_for.

data/doc/Branchproof.md

@@ -2,10 +2,11 @@
 
 |  |  |
 | --- | --- |
-| **Defined in** | lib/branchproof.rb, lib/branchproof/cli.rb, lib/branchproof/limits.rb, lib/branchproof/loader.rb, lib/branchproof/report.rb, lib/branchproof/source.rb, lib/branchproof/worker.rb, lib/branchproof/project.rb, lib/branchproof/records.rb, lib/branchproof/runtime.rb, lib/branchproof/version.rb, lib/branchproof/analyzer.rb, lib/branchproof/evidence.rb, lib/branchproof/minimizer.rb, lib/branchproof/comparison.rb, lib/branchproof/constraints.rb, lib/branchproof/instrumenter.rb, lib/branchproof/runtime_flow.rb, lib/branchproof/saved_report.rb, lib/branchproof/rails_support.rb, lib/branchproof/coverage_index.rb, lib/branchproof/decision_table.rb, lib/branchproof/focused_report.rb, lib/branchproof/decision_syntax.rb, lib/branchproof/minitest_adapter.rb, lib/branchproof/comparison_report.rb, lib/branchproof/flow_instrumentation.rb |
+| **Defined in** | lib/branchproof.rb, lib/branchproof/cli.rb, lib/branchproof/limits.rb, lib/branchproof/loader.rb, lib/branchproof/report.rb, lib/branchproof/source.rb, lib/branchproof/worker.rb, lib/branchproof/project.rb, lib/branchproof/records.rb, lib/branchproof/runtime.rb, lib/branchproof/version.rb, lib/branchproof/analyzer.rb, lib/branchproof/evidence.rb, lib/branchproof/minimizer.rb, lib/branchproof/comparison.rb, lib/branchproof/constraints.rb, lib/branchproof/instrumenter.rb, lib/branchproof/runtime_flow.rb, lib/branchproof/saved_report.rb, lib/branchproof/value_syntax.rb, lib/branchproof/rails_support.rb, lib/branchproof/value_runtime.rb, lib/branchproof/coverage_index.rb, lib/branchproof/decision_table.rb, lib/branchproof/default_syntax.rb, lib/branchproof/focused_report.rb, lib/branchproof/decision_syntax.rb, lib/branchproof/default_runtime.rb, lib/branchproof/exception_syntax.rb, lib/branchproof/iteration_syntax.rb, lib/branchproof/minitest_adapter.rb, lib/branchproof/comparison_report.rb, lib/branchproof/exception_runtime.rb, lib/branchproof/iteration_runtime.rb, lib/branchproof/flow_instrumentation.rb, lib/branchproof/value_instrumentation.rb, lib/branchproof/default_instrumentation.rb, lib/branchproof/exception_instrumentation.rb, lib/branchproof/iteration_instrumentation.rb, lib/branchproof/extended_alternative_runtime.rb |
 
-Keep each bounded source rewrite together so its evaluation order can be
-audited. rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+Keep source-boundary and parameter-binding rules together for auditing.
+rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity,
+Metrics/MethodLength, Metrics/ModuleLength, Metrics/PerceivedComplexity
 
 ## Constants
 ### `VERSION` <a id="constant-VERSION"></a> <a id="VERSION-constant"></a>
@@ -22,11 +23,21 @@ Not documented.
 - [Branchproof/CoverageIndex.md](Branchproof/CoverageIndex.md)
 - [Branchproof/DecisionSyntax.md](Branchproof/DecisionSyntax.md)
 - [Branchproof/DecisionTable.md](Branchproof/DecisionTable.md)
+- [Branchproof/DefaultInstrumentation.md](Branchproof/DefaultInstrumentation.md)
+- [Branchproof/DefaultRuntime.md](Branchproof/DefaultRuntime.md)
+- [Branchproof/DefaultSyntax.md](Branchproof/DefaultSyntax.md)
 - [Branchproof/Error.md](Branchproof/Error.md)
 - [Branchproof/Evidence.md](Branchproof/Evidence.md)
+- [Branchproof/ExceptionInstrumentation.md](Branchproof/ExceptionInstrumentation.md)
+- [Branchproof/ExceptionRuntime.md](Branchproof/ExceptionRuntime.md)
+- [Branchproof/ExceptionSyntax.md](Branchproof/ExceptionSyntax.md)
+- [Branchproof/ExtendedAlternativeRuntime.md](Branchproof/ExtendedAlternativeRuntime.md)
 - [Branchproof/FlowInstrumentation.md](Branchproof/FlowInstrumentation.md)
 - [Branchproof/FocusedReport.md](Branchproof/FocusedReport.md)
 - [Branchproof/Instrumenter.md](Branchproof/Instrumenter.md)
+- [Branchproof/IterationInstrumentation.md](Branchproof/IterationInstrumentation.md)
+- [Branchproof/IterationRuntime.md](Branchproof/IterationRuntime.md)
+- [Branchproof/IterationSyntax.md](Branchproof/IterationSyntax.md)
 - [Branchproof/Limits.md](Branchproof/Limits.md)
 - [Branchproof/Loader.md](Branchproof/Loader.md)
 - [Branchproof/Minimizer.md](Branchproof/Minimizer.md)
@@ -40,6 +51,9 @@ Not documented.
 - [Branchproof/RuntimeFlow.md](Branchproof/RuntimeFlow.md)
 - [Branchproof/SavedReport.md](Branchproof/SavedReport.md)
 - [Branchproof/Source.md](Branchproof/Source.md)
+- [Branchproof/ValueInstrumentation.md](Branchproof/ValueInstrumentation.md)
+- [Branchproof/ValueRuntime.md](Branchproof/ValueRuntime.md)
+- [Branchproof/ValueSyntax.md](Branchproof/ValueSyntax.md)
 - [Branchproof/Worker.md](Branchproof/Worker.md)
 - [CHANGELOG.md](CHANGELOG.md)
 - [README.md](README.md)

data/doc/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-18
+
+- Measure contextual predicates, guarded pattern selection, dynamic case splat
+  groups, required pattern matching, and safe-navigation compound assignment.
+- Add coverage for rescue paths, optional argument binding, standalone
+  predicates, value alternatives, iteration, and source-visible callbacks.
+- Preserve Boolean criteria for Boolean decisions and report other choices as
+  alternative coverage, including their source locations and supporting tests.
+- Exercise 144 Ruby construct fixtures and 406 native cases across source inventory, native behavior,
+  runtime evidence, analysis, reports, saved reports, and CLI integration.
+- Preserve nonlocal control transfers on the right side of logical expressions.
+- Harden default-argument, exception, and iteration instrumentation around
+  implicit parameters, nonlocal transfers, nested frames, and deferred callbacks.
+- Remove unreachable integer bitwise alternatives and keep their exclusions out
+  of coverage denominators.
+- Cache repeated value evidence while preserving vector counts, test/phase
+  attribution, and saved-report coverage semantics.
+
 ## [0.8.0] - 2026-09-17
 
 - Derive a reduced decision table for every supported Boolean decision from its

data/doc/README.md

@@ -542,6 +542,13 @@ ID. Repeated equivalent executions aggregate into a vector's `count`, retaining
 the supporting tests. Ternary outcomes likewise describe the predicate, not
 the value returned by the chosen branch.
 
+Value decisions remain enabled by default. For each decision, evidence caches
+the most recent successful completed trace, keyed by its observations, outcome,
+test, and phase. Consecutive equivalent executions increment vector and phase
+counts without repeating serialization and digest work. When observations,
+test, or phase changes, the execution is recorded normally, so alternating
+traces retain their full evidence and attribution.
+
 Other constructs use alternative coverage, separate from MC/DC:
 
 | Construct | Kind | Context | Required alternatives |
@@ -551,6 +558,18 @@ Other constructs use alternative coverage, separate from MC/DC:
 | `receiver&.method` | `implicit` | `safe_navigation` | Receiver nil / non-nil |
 | `lhs ||= rhs` | `implicit` | `or_assignment` | RHS skipped / executed |
 | `lhs &&= rhs` | `implicit` | `and_assignment` | RHS skipped / executed |
+| `receiver&.value ||= rhs` / `&&=` | `multiway` | `or_assignment` / `and_assignment` | Receiver nil / RHS skipped / RHS evaluated |
+| `value => pattern` | `pattern` | `required_pattern` | Matched / mismatch |
+| Rescue regions | `exception` | `rescue` | Normal completion / rescue clause / unhandled exception |
+| Optional positional and keyword arguments | `implicit` | `default_argument` | Supplied / default evaluated |
+| Standalone predicate calls | `implicit` | `predicate` | Falsey / truthy result |
+| `<=>` | `multiway` | `comparison` | Negative / zero / positive / nil |
+| `[]` lookup | `multiway` | `lookup` | Truthy / false / nil result |
+| `send`, `public_send`, and `__send__` | `implicit` | `dispatch` | Successful return / exception |
+| Regular-expression match capture | `implicit` | `match_capture` | False / true |
+| Iterator bodies | `implicit` | `iteration` | Empty / entered |
+| Lazy iterator callbacks | `multiway` | `lazy_callback` | Callback entered |
+| `fetch` with a fallback block | `implicit` | `fetch_fallback` | Value present / fallback entered |
 
 Each safe-navigation operation in a chain is a distinct decision. Assignment
 instrumentation preserves Ruby's native local, instance, class, global,
@@ -572,16 +591,30 @@ that fails before choosing a branch is aborted, not counted as a selected
 alternative. Selected branches and assignment paths remain observed even when
 their bodies or right-hand sides subsequently raise or return.
 
-Unsupported syntax stays visible and outside coverage denominators. Current
-exclusions include guarded `case/in` (`unsupported_pattern_guard`), dynamic
-`when` splats (`unsupported_case_splat`), safe-navigation compound assignment
-(`unsupported_assignment_target`), and rescue alternatives
-(`unsupported_rescue_control_flow`). A guard predicate can still supply Boolean
-evidence when Ruby evaluates it; an unsupported guarded case does not claim
-pattern-match coverage from that evidence. Flip-flops remain
-`unsupported_flip_flop`. Decisions inside `defined?`, contextual regular
-expressions, heredocs, unsafe predicates, and limit overflows retain explicit
-exclusions. Ruby-defined custom `!` methods keep their runtime behavior;
+Guarded pattern alternatives measure the selected clause, including guard
+acceptance. The guard also supplies Boolean evidence when Ruby evaluates it.
+A dynamic `when *candidates` is one static candidate group; the report does not
+claim coverage of individual elements in that runtime collection.
+
+Flip-flops and implicit regular-expression conditions retain Ruby's conditional
+semantics and contribute one atomic predicate outcome. `defined?` measures its
+result without evaluating or instrumenting the operand. Standalone predicate
+calls record returned truthiness as alternative coverage; they do not claim
+short-circuit conditions or coverage of library internals. Eager bitwise `&`,
+`|`, and `^` are excluded because integer results do not represent Ruby
+truthiness decisions: integer `0` is truthy in Ruby. These expressions add no
+decisions or coverage obligations.
+Dynamic dispatch records completion or exception, and preserves the original
+return value. Lazy callback observations arise only when the callback runs.
+Lookup coverage cannot distinguish an absent key from a stored nil; `fetch`
+fallback coverage measures that separate absence-based choice.
+Optional argument probes use generated local flags and preserve parameter
+signatures, defaults, and existing local bindings. Code that enumerates its own
+local variables can see these instrumentation locals.
+
+Unsupported syntax stays visible and outside coverage denominators. Heredocs,
+unsafe predicates, data sections, and limit overflows retain explicit exclusions.
+Ruby-defined custom `!` methods keep their runtime behavior;
 evidence that contradicts Boolean negation is rejected instead of proving
 coverage with an invalid logical model.