rigortype 0.2.7 → 0.2.8

data/lib/rigor/flow_contribution/conflict.rb

@@ -2,26 +2,20 @@
 
 module Rigor
   class FlowContribution
-    # Records a contradiction between two or more flow contributions
-    # detected during {Merger.merge}. Carried on {MergeResult#conflicts}
-    # so the analyzer / formatter can surface a `:contribution_merge`
-    # diagnostic per ADR-2 § "Plugin Contribution Merging".
+    # Records a contradiction between two or more flow contributions detected during {Merger.merge}. Carried on
+    # {MergeResult#conflicts} so the analyzer / formatter can surface a `:contribution_merge` diagnostic per
+    # ADR-2 § "Plugin Contribution Merging".
     #
-    # ADR-2 § "Plugin Contribution Merging" rules out first-wins /
-    # last-wins behaviour: when contributions conflict, both sources
-    # are reported and the merger falls back to the nearest non-
-    # conflicting higher-tier (or default) value for the affected
-    # `(target, edge, kind)` slot. The conflict object is the
-    # carrier of that report.
+    # ADR-2 § "Plugin Contribution Merging" rules out first-wins / last-wins behaviour: when contributions
+    # conflict, both sources are reported and the merger falls back to the nearest non-conflicting higher-tier
+    # (or default) value for the affected `(target, edge, kind)` slot. The conflict object is the carrier of
+    # that report.
     #
     # Slice-3 conflict reasons:
     #
-    # - `:return_type_collapse` — two return-type contributions
-    #   intersect to `bot`.
-    # - `:exceptional_disagreement` — two contributions assert
-    #   incompatible non-`nil` exceptional effects.
-    # - `:lower_tier_contradiction` — a lower-tier contribution
-    #   would weaken or contradict a higher-tier proof.
+    # - `:return_type_collapse` — two return-type contributions intersect to `bot`.
+    # - `:exceptional_disagreement` — two contributions assert incompatible non-`nil` exceptional effects.
+    # - `:lower_tier_contradiction` — a lower-tier contribution would weaken or contradict a higher-tier proof.
     CONFLICT_VALID_REASONS = %i[
       return_type_collapse
       exceptional_disagreement
@@ -51,19 +45,14 @@ module Rigor
         }
       end
 
-      # ADR-7 § "Slice 5-C" — converts the conflict into a
-      # `Rigor::Analysis::Diagnostic` for the run result.
-      # Carries `source_family: :contribution_merge` so the
-      # qualified-rule formatter (slice 5 formatter half,
-      # `ef730b2`) prefixes the rule id with
-      # `contribution_merge.` and the JSON output side-bands
+      # ADR-7 § "Slice 5-C" — converts the conflict into a `Rigor::Analysis::Diagnostic` for the run result.
+      # Carries `source_family: :contribution_merge` so the qualified-rule formatter (slice 5 formatter half,
+      # `ef730b2`) prefixes the rule id with `contribution_merge.` and the JSON output side-bands
       # `source_family` + `rule` for plugin attribution.
       #
-      # The `rule` identifier is the kebab-case form of the
-      # conflict reason (`return_type_collapse` →
-      # `return-type-collapse`, etc.) so the qualified rule
-      # reads `[contribution_merge.return-type-collapse]` in
-      # the standard text stream.
+      # The `rule` identifier is the kebab-case form of the conflict reason (`return_type_collapse` →
+      # `return-type-collapse`, etc.) so the qualified rule reads `[contribution_merge.return-type-collapse]`
+      # in the standard text stream.
       def to_diagnostic(path:, line:, column:, severity: :error)
         require_relative "../analysis/diagnostic" unless defined?(Rigor::Analysis::Diagnostic)
         Rigor::Analysis::Diagnostic.new(

data/lib/rigor/flow_contribution/element.rb

@@ -2,20 +2,15 @@
 
 module Rigor
   class FlowContribution
-    # Tagged element flattening of a {FlowContribution} bundle —
-    # the analyzer-internal representation [ADR-2 § "Flow
-    # Contribution Bundle"](../../../docs/adr/2-extension-api.md)
-    # routes through the {Merger}.
+    # Tagged element flattening of a {FlowContribution} bundle — the analyzer-internal representation
+    # [ADR-2 § "Flow Contribution Bundle"](../../../docs/adr/2-extension-api.md) routes through the {Merger}.
     #
-    # The flattening is **mechanical, deterministic, and round-
-    # trippable** with the bundle: every non-empty slot expands
-    # into one or more elements keyed by `(target, edge, kind)`,
-    # and an array of elements rebuilds an equivalent bundle when
-    # routed through `Merger.merge`.
+    # The flattening is **mechanical, deterministic, and round-trippable** with the bundle: every non-empty slot
+    # expands into one or more elements keyed by `(target, edge, kind)`, and an array of elements rebuilds an
+    # equivalent bundle when routed through `Merger.merge`.
     #
-    # Plugin authors should not depend on the element shape — the
-    # bundle is the public contract; the element list is the
-    # implementation surface the merge policy operates over.
+    # Plugin authors should not depend on the element shape — the bundle is the public contract; the element
+    # list is the implementation surface the merge policy operates over.
     ELEMENT_VALID_EDGES = %i[normal truthy falsey post_return exceptional].freeze
     ELEMENT_VALID_KINDS = %i[
       return_type

data/lib/rigor/flow_contribution/fact.rb

@@ -2,63 +2,43 @@
 
 module Rigor
   class FlowContribution
-    # Canonical slot payload for the four edge-aware fact slots
-    # (`truthy_facts`, `falsey_facts`, `post_return_facts`, plus
-    # the equivalent under `mutations` / `invalidations` /
-    # `role_conformance` once those carriers grow Fact-shaped
-    # variants).
+    # Canonical slot payload for the four edge-aware fact slots (`truthy_facts`, `falsey_facts`,
+    # `post_return_facts`, plus the equivalent under `mutations` / `invalidations` / `role_conformance` once
+    # those carriers grow Fact-shaped variants).
     #
-    # ADR-7 § "Slice 4-A" pins this object as the **single
-    # canonical translation target** for the four parallel
+    # ADR-7 § "Slice 4-A" pins this object as the **single canonical translation target** for the four parallel
     # contribution carriers the engine has carried so far:
     #
-    # 1. Built-in narrowing rules' direct fact emission
-    #    (Inference::Narrowing#predicate_scopes).
-    # 2. RBS::Extended `predicate-if-*` directives
-    #    (`Rigor::RbsExtended::PredicateEffect`).
-    # 3. RBS::Extended `assert*` directives
-    #    (`Rigor::RbsExtended::AssertEffect`).
+    # 1. Built-in narrowing rules' direct fact emission (Inference::Narrowing#predicate_scopes).
+    # 2. RBS::Extended `predicate-if-*` directives (`Rigor::RbsExtended::PredicateEffect`).
+    # 3. RBS::Extended `assert*` directives (`Rigor::RbsExtended::AssertEffect`).
     # 4. Plugin contributions via `narrowing_facts` DSL (ADR-52).
     #
-    # Each of those four carriers translates to / from Fact at
-    # its boundary; downstream of {Rigor::FlowContribution#to_element_list}
-    # and {Rigor::FlowContribution::Merger.merge}, every slot
-    # payload is a Fact (or a value that the merger compares by
-    # equality and never inspects). The typed `RbsExtended::*Effect`
-    # carriers stay internal to the parser side — they hold the
-    # source-text shape, but lose their identity at the
-    # `read_flow_contribution` boundary.
+    # Each of those four carriers translates to / from Fact at its boundary; downstream of
+    # {Rigor::FlowContribution#to_element_list} and {Rigor::FlowContribution::Merger.merge}, every slot payload
+    # is a Fact (or a value that the merger compares by equality and never inspects). The typed
+    # `RbsExtended::*Effect` carriers stay internal to the parser side — they hold the source-text shape, but
+    # lose their identity at the `read_flow_contribution` boundary.
     #
     # ## Field set
     #
-    # - `target_kind`: `:parameter` (call-site argument), `:self`
-    #   (receiver), or `:local` (a named local in the surrounding
-    #   scope). v0.1.8 Pillar 2 Slice 1 added `:local` so plugins
-    #   recognising bespoke call shapes (`expect(x).to be_a(T)`)
-    #   can narrow a specific scope-bound local without routing
-    #   through the parameter-name lookup that requires an
-    #   authoritative RBS sig on the called method. Future slices
-    #   may extend further (`:ivar`, `:result`). The merger is
-    #   agnostic to the concrete kinds and only requires equality.
-    # - `target_name`: a `Symbol`. For `:parameter` it's the
-    #   declared parameter name. For `:self` it is the literal
-    #   `:self` symbol so the field stays non-nil and the merge
-    #   key is well-defined. For `:local` it's the local-variable
-    #   name (e.g. `:x` for `expect(x).to be_a(T)`).
-    # - `type`: a `Rigor::Type::*` (Nominal, Refined,
-    #   IntegerRange, Difference, …) the fact narrows the
-    #   target toward (when `negative` is false) or away from
-    #   (when `negative` is true).
-    # - `negative`: `true` for the `~T` negation form
-    #   (`predicate-if-true x is ~Integer`), `false` for the
-    #   plain positive form. Mirrors the `negative` field on
-    #   `PredicateEffect` / `AssertEffect`.
+    # - `target_kind`: `:parameter` (call-site argument), `:self` (receiver), or `:local` (a named local in the
+    #   surrounding scope). v0.1.8 Pillar 2 Slice 1 added `:local` so plugins recognising bespoke call shapes
+    #   (`expect(x).to be_a(T)`) can narrow a specific scope-bound local without routing through the
+    #   parameter-name lookup that requires an authoritative RBS sig on the called method. Future slices may
+    #   extend further (`:ivar`, `:result`). The merger is agnostic to the concrete kinds and only requires
+    #   equality.
+    # - `target_name`: a `Symbol`. For `:parameter` it's the declared parameter name. For `:self` it is the
+    #   literal `:self` symbol so the field stays non-nil and the merge key is well-defined. For `:local` it's
+    #   the local-variable name (e.g. `:x` for `expect(x).to be_a(T)`).
+    # - `type`: a `Rigor::Type::*` (Nominal, Refined, IntegerRange, Difference, …) the fact narrows the target
+    #   toward (when `negative` is false) or away from (when `negative` is true).
+    # - `negative`: `true` for the `~T` negation form (`predicate-if-true x is ~Integer`), `false` for the plain
+    #   positive form. Mirrors the `negative` field on `PredicateEffect` / `AssertEffect`.
     #
-    # The `target` accessor returns `:self` for self-targeted
-    # facts and `[:parameter, name]` otherwise — that's the
-    # value {Element#target} keys on, so two facts that narrow
-    # the same parameter from different contribution sources
-    # land in the same merge bucket.
+    # The `target` accessor returns `:self` for self-targeted facts and `[:parameter, name]` otherwise — that's
+    # the value {Element#target} keys on, so two facts that narrow the same parameter from different
+    # contribution sources land in the same merge bucket.
     FACT_VALID_TARGET_KINDS = %i[parameter self local].freeze
 
     class Fact < Data.define(:target_kind, :target_name, :type, :negative)
@@ -77,15 +57,11 @@ module Rigor
         super
       end
 
-      # Composite target identifier the merger keys on. `:self`
-      # for self-targeted facts; otherwise `[kind, name]` so two
-      # contributions that narrow the same `(kind, name)` pair —
-      # regardless of source family — land in the same merge
-      # bucket. `:local` and `:parameter` facts that name the
-      # same symbol stay in separate buckets, which is the
-      # correct semantics: a `:local` fact narrows the surrounding
-      # scope's named local, a `:parameter` fact narrows the
-      # call-site argument matching the parameter declaration.
+      # Composite target identifier the merger keys on. `:self` for self-targeted facts; otherwise
+      # `[kind, name]` so two contributions that narrow the same `(kind, name)` pair — regardless of source
+      # family — land in the same merge bucket. `:local` and `:parameter` facts that name the same symbol stay
+      # in separate buckets, which is the correct semantics: a `:local` fact narrows the surrounding scope's
+      # named local, a `:parameter` fact narrows the call-site argument matching the parameter declaration.
       def target
         target_kind == :self ? :self : [target_kind, target_name]
       end

data/lib/rigor/flow_contribution/merge_result.rb

@@ -2,16 +2,13 @@
 
 module Rigor
   class FlowContribution
-    # Result of folding any number of {FlowContribution} bundles
-    # through {Merger.merge}. Surfaces the merged content slot-by-
-    # slot, the ordered list of contributing provenances, and the
-    # {Conflict} list collected along the way.
+    # Result of folding any number of {FlowContribution} bundles through {Merger.merge}. Surfaces the merged
+    # content slot-by-slot, the ordered list of contributing provenances, and the {Conflict} list collected
+    # along the way.
     #
-    # The merge result is a sibling shape of {FlowContribution} —
-    # the analyzer reads from it to drive narrowing / dispatch /
-    # diagnostics, and the formatter reads from it to surface
-    # plugin / RBS::Extended provenance. The shape is derived per
-    # ADR-2 § "Plugin Contribution Merging"; see
+    # The merge result is a sibling shape of {FlowContribution} — the analyzer reads from it to drive narrowing
+    # / dispatch / diagnostics, and the formatter reads from it to surface plugin / RBS::Extended provenance.
+    # The shape is derived per ADR-2 § "Plugin Contribution Merging"; see
     # [`docs/internal-spec/flow-contribution-merger.md`](../../../docs/internal-spec/flow-contribution-merger.md)
     # for the slice-3 normative description.
     class MergeResult

data/lib/rigor/flow_contribution/merger.rb

@@ -6,55 +6,44 @@ require_relative "merge_result"
 
 module Rigor
   class FlowContribution
-    # Composes any number of {FlowContribution} bundles into a
-    # single {MergeResult} per ADR-2 § "Plugin Contribution
-    # Merging". The merger is the **single point of integration**
-    # the analyzer uses to combine contributions from built-in
-    # narrowing rules, `RBS::Extended` annotations, and plugins;
-    # slice 4 routes the existing internal narrowing through it
-    # and slice 6 wires plugin-side cache producers around it.
+    # Composes any number of {FlowContribution} bundles into a single {MergeResult} per ADR-2 § "Plugin
+    # Contribution Merging". The merger is the **single point of integration** the analyzer uses to combine
+    # contributions from built-in narrowing rules, `RBS::Extended` annotations, and plugins; slice 4 routes
+    # the existing internal narrowing through it and slice 6 wires plugin-side cache producers around it.
     #
     # ## Authority tiers
     #
-    # - Tier 0: `:builtin` — Core Ruby semantics and accepted RBS
-    #   contracts. Authoritative; lower tiers may not contradict.
-    # - Tier 1: `:rbs_extended` (`RBS::Extended` directive bundles,
-    #   v0.0.9 group D reference impl) and `:generated` (generated
-    #   signatures / metadata).
+    # - Tier 0: `:builtin` — Core Ruby semantics and accepted RBS contracts. Authoritative; lower tiers may
+    #   not contradict.
+    # - Tier 1: `:rbs_extended` (`RBS::Extended` directive bundles, v0.0.9 group D reference impl) and
+    #   `:generated` (generated signatures / metadata).
     # - Tier 2: `:plugin` and `plugin.<id>` source families.
     # - Tier 3: anything else — treated as the lowest tier.
     #
-    # Within a tier, contributions are merged in deterministic
-    # order: provenance-supplied `plugin_id` alphabetical (nil
-    # plugin ids sort first to keep `:rbs_extended` / `:generated`
-    # pre-plugin contributions stable), then by their original
-    # input position as the final tie-break.
+    # Within a tier, contributions are merged in deterministic order: provenance-supplied `plugin_id`
+    # alphabetical (nil plugin ids sort first to keep `:rbs_extended` / `:generated` pre-plugin contributions
+    # stable), then by their original input position as the final tie-break.
     #
     # ## Composition rules (ADR-2)
     #
-    # - `:return_type` — Intersect via `Type::Combinator.intersection`;
-    #   collapse to bot raises `:return_type_collapse`.
-    # - `:truthy_fact` / `:falsey_fact` / `:post_return_fact` —
-    #   Edge-local; accumulate while deduping by payload equality.
-    # - `:mutation` / `:invalidation` / `:role` — Union; dedupe by
-    #   equality.
-    # - `:exception` — Single-valued. Two non-`nil` non-equal
-    #   exceptional effects raise `:exceptional_disagreement`.
+    # - `:return_type` — Intersect via `Type::Combinator.intersection`; collapse to bot raises
+    #   `:return_type_collapse`.
+    # - `:truthy_fact` / `:falsey_fact` / `:post_return_fact` — Edge-local; accumulate while deduping by
+    #   payload equality.
+    # - `:mutation` / `:invalidation` / `:role` — Union; dedupe by equality.
+    # - `:exception` — Single-valued. Two non-`nil` non-equal exceptional effects raise
+    #   `:exceptional_disagreement`.
     #
     # ## Cross-tier contradictions
     #
-    # Lower tiers may refine higher tiers but must not weaken them.
-    # Slice 3 surfaces contradictions through `:lower_tier_contradiction`
-    # when:
+    # Lower tiers may refine higher tiers but must not weaken them. Slice 3 surfaces contradictions through
+    # `:lower_tier_contradiction` when:
     #
-    # - the higher tier already pinned a `return_type` and a lower
-    #   tier's intersection collapses to `bot`;
-    # - the higher tier set `exceptional` to a non-`nil` value and a
-    #   lower tier disagrees.
+    # - the higher tier already pinned a `return_type` and a lower tier's intersection collapses to `bot`;
+    # - the higher tier set `exceptional` to a non-`nil` value and a lower tier disagrees.
     #
-    # In every conflict case the result keeps the higher-tier value
-    # for that slot, records a {Conflict} with both provenances, and
-    # continues processing the remaining slots / contributions.
+    # In every conflict case the result keeps the higher-tier value for that slot, records a {Conflict} with
+    # both provenances, and continues processing the remaining slots / contributions.
     module Merger
       AUTHORITY_TIERS = {
         builtin: 0,
@@ -91,8 +80,8 @@ module Rigor
         private
 
         def order_contributions(contributions)
-          # Stable sort: tier ascending, then provenance plugin_id
-          # alphabetical (nil first), then original input position.
+          # Stable sort: tier ascending, then provenance plugin_id alphabetical (nil first), then original
+          # input position.
           contributions.each_with_index
                        .sort_by { |c, i| [tier_for(c.provenance), plugin_id_key(c.provenance), i] }
                        .map { |c, _| c }
@@ -140,13 +129,10 @@ module Rigor
           state.return_type_tier = [state.return_type_tier, tier].min
         end
 
-        # Two types' intersection collapses to bot when neither
-        # accepts the other under gradual mode — i.e. the value
-        # domains are disjoint. `Rigor::Type::Combinator.intersection`
-        # itself does not collapse incompatible nominals (`String ∩
-        # Integer` builds a structurally-empty `Intersection`
-        # carrier), so the merger checks the disjointness condition
-        # directly via the `accepts` trinary.
+        # Two types' intersection collapses to bot when neither accepts the other under gradual mode — i.e.
+        # the value domains are disjoint. `Rigor::Type::Combinator.intersection` itself does not collapse
+        # incompatible nominals (`String ∩ Integer` builds a structurally-empty `Intersection` carrier), so
+        # the merger checks the disjointness condition directly via the `accepts` trinary.
         def intersection_empty?(lhs, rhs)
           return false if lhs.equal?(rhs)
 
@@ -227,9 +213,8 @@ module Rigor
         end
       end
 
-      # Internal accumulator carried through a single merge call.
-      # Not part of the public API; folds into a {MergeResult} at
-      # the end via {#to_result}.
+      # Internal accumulator carried through a single merge call. Not part of the public API; folds into a
+      # {MergeResult} at the end via {#to_result}.
       class MergeState
         attr_accessor :return_type, :return_type_tier, :return_type_provenance,
                       :exceptional, :exceptional_tier, :exceptional_provenance

data/lib/rigor/flow_contribution.rb

@@ -3,33 +3,26 @@
 require_relative "flow_contribution/element"
 
 module Rigor
-  # The public packaging of a flow contribution at a single call edge.
-  # Plugins, `RBS::Extended` annotations, and built-in narrowing rules
-  # all hand the analyzer this same bundle shape; the inference engine
-  # merges contributions through the policy described in
-  # [ADR-2 § "Plugin Contribution Merging"](../../docs/adr/2-extension-api.md)
-  # rather than letting any one source override another silently.
+  # The public packaging of a flow contribution at a single call edge. Plugins, `RBS::Extended` annotations,
+  # and built-in narrowing rules all hand the analyzer this same bundle shape; the inference engine merges
+  # contributions through the policy described in
+  # [ADR-2 § "Plugin Contribution Merging"](../../docs/adr/2-extension-api.md) rather than letting any one
+  # source override another silently.
   #
-  # Eight content slots plus a {Provenance} block. A slot left as `nil`
-  # (or, for collection-shaped slots, an empty collection) means the
-  # contribution does not assert anything in that dimension; the merge
-  # policy treats it as absent.
+  # Eight content slots plus a {Provenance} block. A slot left as `nil` (or, for collection-shaped slots, an
+  # empty collection) means the contribution does not assert anything in that dimension; the merge policy
+  # treats it as absent.
   #
-  # The struct is the only shape plugin authors need to learn. Richer
-  # or more permissive shapes are not part of the first public
-  # contract — see ADR-2 § "Flow Contribution Bundle" for the binding
-  # definition.
+  # The struct is the only shape plugin authors need to learn. Richer or more permissive shapes are not part
+  # of the first public contract — see ADR-2 § "Flow Contribution Bundle" for the binding definition.
   #
-  # `to_element_list` and `Merger` are implemented; plugin authors
-  # should not depend on the `Element` shape — the bundle is the
-  # public contract.
+  # `to_element_list` and `Merger` are implemented; plugin authors should not depend on the `Element` shape —
+  # the bundle is the public contract.
   class FlowContribution
-    # Provenance carries the metadata every contribution needs for
-    # diagnostic attribution and cache invalidation. `source_family`
-    # mirrors {Rigor::Analysis::Diagnostic::DEFAULT_SOURCE_FAMILY};
-    # `descriptor` is the {Rigor::Cache::Descriptor} this
-    # contribution attaches to (or `nil` when the contribution does
-    # not need its own cache slice).
+    # Provenance carries the metadata every contribution needs for diagnostic attribution and cache
+    # invalidation. `source_family` mirrors {Rigor::Analysis::Diagnostic::DEFAULT_SOURCE_FAMILY}; `descriptor`
+    # is the {Rigor::Cache::Descriptor} this contribution attaches to (or `nil` when the contribution does not
+    # need its own cache slice).
     class Provenance < Data.define(:source_family, :plugin_id, :node, :descriptor)
       def self.builtin
         new(source_family: :builtin, plugin_id: nil, node: nil, descriptor: nil)
@@ -49,27 +42,20 @@ module Rigor
 
     attr_reader(*SLOT_NAMES, :provenance)
 
-    # @param return_type [Object, nil] normal-edge return type. Use
-    #   `nil` when the contribution does not refine the return type
-    #   selected from the RBS contract.
-    # @param truthy_facts [Array, nil] facts that hold only on the
-    #   truthy control-flow edge. Edge-local: a truthy-edge fact does
-    #   NOT imply its falsey-edge complement (ADR-2 § "Plugin
-    #   Contribution Merging").
+    # @param return_type [Object, nil] normal-edge return type. Use `nil` when the contribution does not
+    #   refine the return type selected from the RBS contract.
+    # @param truthy_facts [Array, nil] facts that hold only on the truthy control-flow edge. Edge-local: a
+    #   truthy-edge fact does NOT imply its falsey-edge complement (ADR-2 § "Plugin Contribution Merging").
     # @param falsey_facts [Array, nil] dual of `truthy_facts`.
-    # @param post_return_facts [Array, nil] facts that hold after the
-    #   call returns normally on every edge — the carrier for
-    #   assertion-style contributions.
-    # @param mutations [Array, nil] receiver and argument mutation
-    #   effects.
-    # @param invalidations [Array, nil] targeted fact invalidations
-    #   beyond what mutation effects already imply.
-    # @param exceptional [Object, nil] non-returning, raising, or
-    #   unreachable effect.
-    # @param role_conformance [Array, nil] capability-role conformance
-    #   facts the contribution provides.
-    # @param provenance [Provenance] source-family, plugin-id, node,
-    #   and cache-descriptor metadata. Defaults to `Provenance.builtin`.
+    # @param post_return_facts [Array, nil] facts that hold after the call returns normally on every edge —
+    #   the carrier for assertion-style contributions.
+    # @param mutations [Array, nil] receiver and argument mutation effects.
+    # @param invalidations [Array, nil] targeted fact invalidations beyond what mutation effects already
+    #   imply.
+    # @param exceptional [Object, nil] non-returning, raising, or unreachable effect.
+    # @param role_conformance [Array, nil] capability-role conformance facts the contribution provides.
+    # @param provenance [Provenance] source-family, plugin-id, node, and cache-descriptor metadata. Defaults
+    #   to `Provenance.builtin`.
     # rubocop:disable Metrics/ParameterLists
     def initialize(return_type: nil, truthy_facts: nil, falsey_facts: nil,
                    post_return_facts: nil, mutations: nil, invalidations: nil,
@@ -88,9 +74,8 @@ module Rigor
       freeze
     end
 
-    # @return [Boolean] true when every content slot is unset (nil or
-    #   an empty collection). Provenance does not count toward
-    #   emptiness — an empty bundle still carries source attribution.
+    # @return [Boolean] true when every content slot is unset (nil or an empty collection). Provenance does
+    #   not count toward emptiness — an empty bundle still carries source attribution.
     def empty?
       SLOT_NAMES.all? { |slot| slot_empty?(public_send(slot)) }
     end
@@ -101,10 +86,9 @@ module Rigor
       end
     end
 
-    # Flattens this bundle into a tagged element list keyed by
-    # `(target, edge, kind)`. The flattening is mechanical and
-    # round-trippable through {Merger.merge}: feeding the result
-    # back through the merger produces an equivalent bundle.
+    # Flattens this bundle into a tagged element list keyed by `(target, edge, kind)`. The flattening is
+    # mechanical and round-trippable through {Merger.merge}: feeding the result back through the merger
+    # produces an equivalent bundle.
     #
     # Layout:
     #
@@ -150,11 +134,9 @@ module Rigor
       Element.new(target: target, edge: edge, kind: kind, payload: payload, provenance: provenance)
     end
 
-    # Best-effort target extraction. Payloads that expose a
-    # `#target` accessor (typed-fact carriers, mutation effects)
-    # provide their own; everything else falls through with the
-    # payload itself as the merge key, which keeps deduplication
-    # well-defined for opaque entries.
+    # Best-effort target extraction. Payloads that expose a `#target` accessor (typed-fact carriers, mutation
+    # effects) provide their own; everything else falls through with the payload itself as the merge key,
+    # which keeps deduplication well-defined for opaque entries.
     def fact_target(payload)
       return payload.target if payload.respond_to?(:target)