rigortype 0.3.2 → 0.3.4

data/lib/rigor/effects/snapshot.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "yaml"
+
+require_relative "../version"
+require_relative "effect_table"
+require_relative "entry_points"
+require_relative "identity"
+require_relative "registry"
+
+module Rigor
+  module Effects
+    # The committed effect snapshot — `.rigor-effects.yml`, the primary validation mode (ADR-103 WD7 /
+    # WD14, design note § 9.4).
+    #
+    # It is `db/schema.rb` for effects: a generated artefact a project commits, whose diff in a pull
+    # request *is* the review signal, whose freshness CI checks, and where intent is expressed by
+    # committing the regenerated file rather than by annotating code. It emits no diagnostic and never
+    # enters `rigor check`'s stream ([ADR-102](../adr/102-unused-code-reachability-report.md)).
+    #
+    # Two tables, chosen so a diff is **attributable**:
+    #
+    # - `methods:` holds each unit's **direct** summary — origins in the method's own body (block literals
+    #   included) plus catalogued and attributed callees, but never a project callee, which is an edge. An
+    #   entry therefore moves only when its own lines, the catalogue or an attribution moved.
+    # - `reach:` holds the **transitive** footprint at the entry points `effects.snapshot.reach:` names.
+    #   A leaf change fans out here, and the fan-out is the information (blast radius).
+    #
+    # The record is **undischarged**: `tolerated:` is consulted at judgment time by {SnapshotDiff}, never
+    # while writing, so `update --no-tolerated-effects` and `update` write byte-identical files and a
+    # policy change diffs the config rather than the record.
+    #
+    # The serialisation is a hand-rolled **JSON-compatible YAML subset**: string keys, JSON scalars, flow
+    # sequences, sorted keys and sorted labels, no anchors, no tags, no timestamps. `YAML.safe_load` of the
+    # file round-trips through `JSON` unchanged, which is the property a sibling implementation reads it by.
+    class Snapshot
+      # Bumped when the file's shape changes in a way an older reader would misread. A bump makes every
+      # existing file a regeneration event rather than a silent reinterpretation.
+      SCHEMA = 1
+
+      HEADER = "# .rigor-effects.yml — generated by `rigor effects update`. Commit it; review its diff."
+
+      class ParseError < StandardError
+      end
+
+      # One row of either table.
+      #
+      # `effects` and `declared` are sorted label arrays; `unresolved` is the sorted list of taint-cause
+      # renderings behind a false `exhaustive`, and is empty when the row is exhaustive.
+      class Entry < Data.define(:key, :effects, :declared, :exhaustive, :unresolved)
+        def exhaustive?
+          exhaustive
+        end
+
+        # The wire form, with every field the reader can default omitted: `declared:` when empty,
+        # `exhaustive:` when true, `unresolved:` when there is nothing to say. What stays is what a
+        # reviewer reads.
+        def to_h
+          row = { "effects" => effects }
+          row["declared"] = declared unless declared.empty?
+          row["exhaustive"] = false unless exhaustive
+          row["unresolved"] = unresolved unless unresolved.empty?
+          row
+        end
+
+        def self.from_h(key, row)
+          raise ParseError, "entry #{key.inspect} is not a mapping" unless row.is_a?(Hash)
+
+          new(
+            key: key,
+            effects: string_list(row["effects"], key, "effects"),
+            declared: string_list(row["declared"], key, "declared"),
+            exhaustive: row.fetch("exhaustive", true) != false,
+            unresolved: string_list(row["unresolved"], key, "unresolved")
+          )
+        end
+
+        def self.string_list(value, key, field)
+          return [].freeze if value.nil?
+          raise ParseError, "#{key.inspect} #{field}: expected a list, got #{value.class}" unless value.is_a?(Array)
+
+          value.map do |member|
+            raise ParseError, "#{key.inspect} #{field}: expected strings" unless member.is_a?(String)
+
+            member
+          end.freeze
+        end
+        private_class_method :string_list
+      end
+
+      class << self
+        # Builds the snapshot a run's effect table describes.
+        #
+        # @param table [EffectTable] the propagated graph
+        # @param configuration [Rigor::Configuration] supplies the reach globs and the digested block
+        # @param sources [Hash{String=>Array<String>}] `Runner#effect_sources` — where each unit is defined
+        # @param full [Boolean] keep the rows {#omit?} drops
+        # @param registry [Registry] the vocabulary whose version the header carries
+        # @param project_root [String] what `sources` paths are relativised against for glob matching
+        def build(table:, configuration:, sources: {}, full: false, registry: Registry.default,
+                  project_root: Dir.pwd)
+          globs = expand_reach(configuration.effects_snapshot_reach)
+          new(
+            header: {
+              "schema" => SCHEMA,
+              "rigor" => Rigor::VERSION,
+              "vocabulary" => registry.vocabulary_version,
+              "config_digest" => config_digest(configuration)
+            },
+            methods: build_methods(table, full: full),
+            reach: build_reach(table, globs, sources, project_root, full: full)
+          )
+        end
+
+        # The per-origin discharge judgment's input, for the side of a comparison that HAS origins
+        # (#385). `{table => {symbol => [label]}}`: for each row this snapshot carries, the labels that
+        # survive `effects.tolerated:` applied bundle by bundle — direct bundles under `methods:`, the
+        # transitive lane under `reach:`, matching what each table records.
+        #
+        # It is built beside the snapshot and never inside it: the file stays flat and undischarged, and
+        # this index exists only for the duration of one comparison ({SnapshotDiff}).
+        #
+        # @param snapshot [Snapshot] the current side, already built
+        # @param table [EffectTable] the run that produced it
+        # @param discharge [Discharge] the policy
+        # @return [Hash, nil] nil when the policy discharges nothing, which is the common case
+        def undischarged_index(snapshot:, table:, discharge:)
+          return nil if discharge.inert?
+
+          {
+            "methods" => snapshot.methods.keys.filter_map do |key|
+              entry = table[key]
+              [key, discharge.undischarged(entry.direct.bundles).to_a] if entry
+            end.to_h,
+            "reach" => snapshot.reach.keys.filter_map do |key|
+              entry = table[key]
+              [key, entry.undischarged.to_a] if entry
+            end.to_h
+          }.freeze
+        end
+
+        # The `effects:` block of `.rigor.yml`, canonicalised (keys sorted at every depth, rendered as
+        # JSON) and hashed. A Rigor upgrade, a vocabulary bump or a `tolerated:` edit is therefore a
+        # **visible** regeneration event rather than a silent reinterpretation of the record.
+        #
+        # The implementation lives in {Effects::Identity} because the effects CACHE identity (#382) digests
+        # the same block: a header that agreed with the cache key only by convention would eventually stop
+        # agreeing, and the failure would be a silently reused stale sidecar.
+        def config_digest(configuration)
+          Identity.config_digest(configuration)
+        end
+
+        # Resolves `effects.snapshot.reach:` entries to file globs: a preset name becomes the globs it
+        # stands for, a glob stays itself.
+        #
+        # This is where an unknown preset name is caught (#387). `Configuration` cannot: presets are named
+        # by plugins, and plugins load from the configuration being validated. By the time a snapshot is
+        # built the registered set is complete, so a name nothing registered is a real error — most often
+        # `reach: [rails]` in a project that never listed the Rails plugins — and saying so beats a `reach:`
+        # table that comes back mysteriously empty.
+        def expand_reach(entries)
+          entries.flat_map do |entry|
+            next [entry] if EntryPoints.glob?(entry)
+
+            EntryPoints.globs_for(entry) ||
+              raise(EntryPoints::Error,
+                    "effects.snapshot.reach names no registered entry-point preset: #{entry.inspect} " \
+                    "(registered: #{EntryPoints.names.inspect}; a preset is named by the plugin that " \
+                    "models the framework, so listing that plugin is what registers it)")
+          end.uniq.sort.freeze
+        end
+
+        def parse(text)
+          data = YAML.safe_load(text)
+          raise ParseError, "not a mapping" unless data.is_a?(Hash)
+
+          new(
+            header: parse_header(data),
+            methods: parse_table(data["methods"], "methods"),
+            reach: parse_table(data["reach"], "reach")
+          )
+        rescue Psych::Exception => e
+          raise ParseError, e.message
+        end
+
+        def load(path)
+          parse(File.read(path, encoding: "UTF-8"))
+        end
+
+        private
+
+        def parse_header(data)
+          {
+            "schema" => data["schema"],
+            "rigor" => data["rigor"].to_s,
+            "vocabulary" => data["vocabulary"],
+            "config_digest" => data["config_digest"].to_s
+          }
+        end
+
+        def parse_table(value, name)
+          return {} if value.nil?
+          raise ParseError, "#{name}: expected a mapping, got #{value.class}" unless value.is_a?(Hash)
+
+          value.to_h { |key, row| [key.to_s, Entry.from_h(key.to_s, row)] }
+        end
+
+        # `methods:` records the DIRECT summary. Two omissions keep the file to what is worth reading:
+        # a summary that is exhaustive and proves nothing beyond `mutate.local` (which every envelope
+        # tolerates), and a synthesised default accessor summary. `--full` keeps both.
+        def build_methods(table, full:)
+          table.each_with_object({}) do |entry, out|
+            next if !full && omit?(trivial: entry.direct.trivial?, direct: entry.direct,
+                                   proven: entry.direct.proven, declared: entry.direct.declared)
+
+            out[entry.key] = entry_for(entry.key, entry.direct.proven, entry.direct,
+                                       declared: entry.direct.declared)
+          end
+        end
+
+        # `reach:` records the TRANSITIVE footprint, and only at the entry points the configuration names.
+        # A key qualifies when any file that defines it matches a glob — an entry-point glob selects a
+        # *file*, so every unit written in it is one, and the same omission rule then keeps the table to
+        # the entry points worth reading. One that later gains an effect arrives as an added symbol.
+        def build_reach(table, globs, sources, project_root, full:)
+          return {} if globs.empty?
+
+          table.each_with_object({}) do |entry, out|
+            next unless entry_point?(entry.key, globs, sources, project_root)
+            next if !full && omit?(trivial: entry.trivial?, direct: entry.direct,
+                                   proven: entry.proven, declared: entry.declared)
+
+            out[entry.key] = entry_for(entry.key, entry.proven, entry.direct, declared: entry.declared,
+                                                                              exhaustive: entry.exhaustive?,
+                                                                              causes: entry.causes)
+          end
+        end
+
+        def entry_point?(key, globs, sources, project_root)
+          Array(sources[key]).any? do |path|
+            relative = relativize(path, project_root)
+            globs.any? { |glob| File.fnmatch?(glob, relative, File::FNM_PATHNAME) }
+          end
+        end
+
+        def relativize(path, project_root)
+          absolute = File.absolute_path(path.to_s)
+          root = "#{File.absolute_path(project_root.to_s).chomp('/')}/"
+          absolute.start_with?(root) ? absolute[root.length..] : absolute
+        end
+
+        # Each table takes the lanes at ITS own reading: `methods:` records the direct summary, so its
+        # `declared:` is what this method's own body claims, and `reach:` records the transitive one, so
+        # its `declared:` is the fixpoint's — a controller reaching an attributed gem call through two
+        # services carries the claim, exactly as it carries the proven labels.
+        #
+        # The rendering rule applies here and only here: a declared label the row's own proven set already
+        # admits says nothing more, so it is dropped rather than printed as a second fact. The table keeps
+        # both lanes raw.
+        def entry_for(key, proven, direct, declared:, exhaustive: direct.exhaustive?, causes: direct.causes)
+          Entry.new(
+            key: key,
+            effects: proven.to_a,
+            declared: declared.excluding_subsumed_by(proven).to_a,
+            exhaustive: exhaustive,
+            unresolved: exhaustive ? [].freeze : render_causes(causes)
+          )
+        end
+
+        # `unresolved:` says why the row is not exhaustive, from the closed taint-cause enum of
+        # `docs/type-specification/effect-labels.md` — `dynamic-send`, `unresolved-self-call(save!)`. The
+        # design note sketched this field as "call names"; the collector keeps causes rather than names,
+        # and for the causes that have one the detail already IS the call name.
+        def render_causes(causes)
+          causes.map { |cause, detail| detail.nil? || detail.empty? ? cause : "#{cause}(#{detail})" }
+                .uniq.sort.freeze
+        end
+
+        # A synthesised default summary — an `attr_*` writer's `mutate.self`, and the `Struct` / `Data`
+        # accessors that join it when discovery synthesises them — carries no information a reviewer acts
+        # on: it restates the `attr_accessor` line. Recognised by its origins being exactly the synthesised
+        # constructs, so a hand-written `def name=` keeps its row.
+        SYNTHESISED_ORIGINS = %w[construct:attr-writer].to_set.freeze
+        private_constant :SYNTHESISED_ORIGINS
+
+        # A **taint-only** row carries no label in either lane: it says "not exhaustive, and here is why",
+        # and nothing a reviewer ratchets against. The snapshot lists what is attributable (issue #411,
+        # option (b)), so the row is omitted and the exhaustiveness transition stays visible for every row
+        # that does carry a label or a declared bound. `--full` keeps it, and a method that later proves a
+        # label arrives as an added symbol.
+        def omit?(trivial:, direct:, proven:, declared:)
+          return true if trivial
+          return true if proven.empty? && declared.empty?
+          return false unless direct.exhaustive?
+          return false if direct.bundles.empty?
+
+          direct.bundles.each_key.all? { |origin| SYNTHESISED_ORIGINS.include?(origin.to_s) }
+        end
+      end
+
+      attr_reader :header, :methods, :reach
+
+      def initialize(header:, methods: {}, reach: {})
+        @header = header.freeze
+        @methods = sorted(methods)
+        @reach = sorted(reach)
+        freeze
+      end
+
+      def ==(other)
+        other.is_a?(Snapshot) && other.header == @header && other.methods == @methods && other.reach == @reach
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, @header, @methods, @reach].hash
+      end
+
+      # The table a diff category names, so `SnapshotDiff` walks the two by name.
+      def table(name)
+        name == "reach" ? @reach : @methods
+      end
+
+      # The wire form: plain Hashes, Strings, Integers, Booleans and Arrays — nothing a JSON parser would
+      # choke on and nothing a YAML reader has to resolve a tag for.
+      def to_h
+        @header.merge(
+          "methods" => @methods.transform_values(&:to_h),
+          "reach" => @reach.transform_values(&:to_h)
+        )
+      end
+
+      # Renders the file. Hand-rolled rather than `YAML.dump`ed so the leading comment, the key order and
+      # the flow sequences are ours: two runs over one tree must be byte-identical, and a snapshot written
+      # by a pooled run must equal the sequential one bit for bit.
+      def to_yaml
+        lines = [HEADER]
+        lines << "schema: #{@header.fetch('schema')}"
+        lines << "rigor: #{scalar(@header.fetch('rigor'))}"
+        lines << "vocabulary: #{@header.fetch('vocabulary')}"
+        lines << "config_digest: #{scalar(@header.fetch('config_digest'))}"
+        render_table(lines, "methods", @methods)
+        render_table(lines, "reach", @reach)
+        "#{lines.join("\n")}\n"
+      end
+      alias to_s to_yaml
+
+      private
+
+      def render_table(lines, name, table)
+        if table.empty?
+          lines << "#{name}: {}"
+          return
+        end
+
+        lines << "#{name}:"
+        table.each do |key, entry|
+          lines << "  #{scalar(key)}:"
+          entry.to_h.each { |field, value| lines << "    #{field}: #{wire(value)}" }
+        end
+      end
+
+      def wire(value)
+        value.is_a?(Array) ? "[#{value.map { |member| scalar(member) }.join(', ')}]" : value.to_s
+      end
+
+      # JSON string escaping is a valid YAML double-quoted scalar, so one rule covers both formats and a
+      # key carrying `#`, `:` or a leading indicator cannot change the document's shape.
+      def scalar(value)
+        value.to_s.to_json
+      end
+
+      def sorted(table)
+        table.sort_by { |key, _| key }.to_h.freeze
+      end
+    end
+  end
+end

data/lib/rigor/effects/snapshot_diff.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require_relative "label_set"
+require_relative "snapshot"
+
+module Rigor
+  module Effects
+    # Compares a committed {Snapshot} with the one this run computes, and judges the difference
+    # (ADR-103 WD7; the event vocabulary is design note § 9.4).
+    #
+    # The comparison itself is exact — drift between two observations by the same tool is 100 % precise.
+    # What is *judged* is whether the drift matters, and that has two knobs, applied here and never while
+    # writing the record:
+    #
+    # - the **gate**. `symmetric` (the default) fails on any drift, the `db/schema.rb` model: a removal is
+    #   news too, because a job that stopped enqueueing is a bug rather than an improvement. `additions`
+    #   is the ratchet: only growth fails.
+    # - the **tolerated set**. An event whose labels are all admitted by `effects.tolerated:` is reported
+    #   under its own heading and does not fail the gate unless `strict_tolerated:` is set.
+    #
+    # **Additions are judged per origin; removals by label.** The file is flat — origins are `explain`'s
+    # job and a record keyed by them would churn on every refactor — but the *current* side of a
+    # comparison is a live effect table, so the caller can hand over `undischarged:`, the labels that
+    # survive per-origin discharge for each current symbol (#385). An added label is then tolerated
+    # exactly when every origin that introduces it is discharged, which is the same answer the envelope
+    # check gives, rather than the coarser "the label is on the list". A **removal** has no current-side
+    # origins to consult — the thing that produced it is gone — so it stays judged by label. Without the
+    # index (a caller that has no table, and every parse-only spec) both fall back to the label reading.
+    #
+    # A header mismatch is neither: it is a **regeneration event** — the record was written by a different
+    # Rigor, a different vocabulary or a different `effects:` block, so the two sides are not comparable
+    # in the first place. It fails under both gates, because there is nothing to ratchet against.
+    class SnapshotDiff
+      # Categories, in the order a text rendering emits them. The strings are the JSON contract.
+      MISSING_SNAPSHOT = "missing-snapshot"
+      REGENERATION = "regeneration"
+      SYMBOL_ADDED = "symbol-added"
+      SYMBOL_REMOVED = "symbol-removed"
+      LABEL_ADDED = "label-added"
+      LABEL_REMOVED = "label-removed"
+      DECLARED_ADDED = "declared-added"
+      DECLARED_REMOVED = "declared-removed"
+      MATERIALISED = "materialised"
+      EXHAUSTIVE_LOST = "exhaustive-lost"
+      EXHAUSTIVE_GAINED = "exhaustive-gained"
+
+      # What the `additions` ratchet still fails on: growth in either lane, a new symbol, and a method
+      # that stopped being exhaustive (someone introduced a call the analyzer cannot follow — the one
+      # "removal-shaped" change that is unambiguously a loss of knowledge).
+      ADDITIVE_CATEGORIES = [SYMBOL_ADDED, LABEL_ADDED, DECLARED_ADDED, EXHAUSTIVE_LOST,
+                             MISSING_SNAPSHOT, REGENERATION].freeze
+
+      TABLES = %w[methods reach].freeze
+
+      # One difference.
+      #
+      # `symbol` is the method key (nil for a header event), `label` the label it is about (nil for the
+      # symbol- and exhaustiveness-shaped ones), `detail` any extra the renderer prints verbatim, and
+      # `tolerated` whether policy discharged it.
+      class Event < Data.define(:category, :symbol, :label, :table, :tolerated, :detail, :hedged)
+        def tolerated?
+          tolerated
+        end
+
+        # Whether the current side could not prove an absence. A removal read off a non-exhaustive summary
+        # is rendered hedged — "possibly more" cannot prove that something stopped happening.
+        def hedged?
+          hedged
+        end
+
+        def to_h
+          row = { "category" => category, "symbol" => symbol, "table" => table, "tolerated" => tolerated }
+          row["label"] = label if label
+          row["detail"] = detail if detail
+          row["hedged"] = true if hedged
+          row
+        end
+      end
+
+      # The categories the per-origin judgment is exact for: both are additions in the PROVEN lane, so the
+      # current side's undischarged labels answer them directly. The declared lane's additions are not
+      # here — nothing declared has a proven origin to discharge.
+      ORIGIN_JUDGED_CATEGORIES = [SYMBOL_ADDED, LABEL_ADDED].freeze
+      private_constant :ORIGIN_JUDGED_CATEGORIES
+
+      # Compares `current` against `recorded`. `recorded` may be nil — no snapshot on disk at all, which
+      # is drift with a routed message rather than an error.
+      #
+      # @param undischarged [Hash] `{table name => {symbol => [label]}}` — the current side's labels that
+      #   survive per-origin discharge ({Snapshot.undischarged_index}). Optional; omitting it judges every
+      #   event by label.
+      def self.compare(recorded:, current:, tolerated: [], gate: :symmetric, strict_tolerated: false,
+                       undischarged: nil)
+        new(recorded: recorded, current: current, tolerated: tolerated, gate: gate,
+            strict_tolerated: strict_tolerated, undischarged: undischarged)
+      end
+
+      attr_reader :events, :recorded, :current, :gate
+
+      def initialize(recorded:, current:, tolerated: [], gate: :symmetric, strict_tolerated: false,
+                     undischarged: nil)
+        @recorded = recorded
+        @current = current
+        @gate = gate
+        @strict_tolerated = strict_tolerated
+        @tolerated = LabelSet.new(tolerated)
+        @undischarged = undischarged
+        @added_symbols = 0
+        @removed_symbols = 0
+        @events = build_events.freeze
+        freeze
+      end
+
+      # Whether the record matches what this run computed. A tolerated-only difference is NOT fresh — the
+      # file still needs regenerating — it merely does not fail the gate.
+      def fresh?
+        @events.empty?
+      end
+
+      # Whether `rigor effects check` exits non-zero.
+      def drift?
+        @events.any? { |event| gating?(event) }
+      end
+
+      # Renames are a removal plus an addition and are never reported as a lost effect; the footer is
+      # where the reviewer sees that the two counts balance.
+      def footer
+        { added_symbols: @added_symbols, removed_symbols: @removed_symbols }
+      end
+
+      def events_for(table)
+        @events.select { |event| event.table == table && !event.tolerated? }
+      end
+
+      def tolerated_events
+        @events.select(&:tolerated?)
+      end
+
+      private
+
+      def gating?(event)
+        return false if event.tolerated? && !@strict_tolerated
+        return true if @gate == :symmetric
+
+        ADDITIVE_CATEGORIES.include?(event.category)
+      end
+
+      def build_events
+        return [missing_snapshot_event] if @recorded.nil?
+
+        header_events + TABLES.flat_map { |table| table_events(table) }
+      end
+
+      def missing_snapshot_event
+        event(MISSING_SNAPSHOT, symbol: nil, table: "snapshot",
+                                detail: "no snapshot; run `rigor effects update`")
+      end
+
+      # The header says which record this is. A mismatch on any of its four fields means the recorded
+      # sets were computed under different rules, so every downstream comparison would be noise.
+      def header_events
+        %w[schema rigor vocabulary config_digest].filter_map do |field|
+          was = @recorded.header[field]
+          now = @current.header[field]
+          next if was == now
+
+          event(REGENERATION, symbol: nil, table: "header", detail: "#{field}: #{was.inspect} → #{now.inspect}")
+        end
+      end
+
+      def table_events(table)
+        was = @recorded.table(table)
+        now = @current.table(table)
+        (was.keys | now.keys).sort.flat_map do |symbol|
+          before = was[symbol]
+          after = now[symbol]
+          if before.nil? then added_symbol(symbol, after, table)
+          elsif after.nil? then removed_symbol(symbol, before, table)
+          else changed_symbol(symbol, before, after, table)
+          end
+        end
+      end
+
+      def added_symbol(symbol, entry, table)
+        @added_symbols += 1
+        return [] if quiet?(entry)
+
+        [event(SYMBOL_ADDED, symbol: symbol, table: table, labels: entry.effects,
+                             detail: render_labels(entry))]
+      end
+
+      def removed_symbol(symbol, entry, table)
+        @removed_symbols += 1
+        return [] if quiet?(entry)
+
+        [event(SYMBOL_REMOVED, symbol: symbol, table: table, labels: entry.effects,
+                               detail: render_labels(entry))]
+      end
+
+      # A row carrying nothing — no labels, nothing declared, exhaustive — appears only under `--full`.
+      # Its coming and going is not news; the footer still counts it, so a rename still balances.
+      def quiet?(entry)
+        entry.effects.empty? && entry.declared.empty? && entry.exhaustive?
+      end
+
+      def changed_symbol(symbol, before, after, table)
+        materialised = before.declared & (after.effects - before.effects)
+        lane_events(symbol, before, after, table, materialised) +
+          exhaustiveness_events(symbol, before, after, table)
+      end
+
+      # The proven and declared lanes, with materialisation lifted out of both: a label that was an
+      # authored upper bound and is now proven is ONE event, never a removal plus an addition.
+      def lane_events(symbol, before, after, table, materialised)
+        [[MATERIALISED, materialised],
+         [LABEL_ADDED, after.effects - before.effects - materialised],
+         [LABEL_REMOVED, before.effects - after.effects],
+         [DECLARED_ADDED, after.declared - before.declared],
+         [DECLARED_REMOVED, before.declared - after.declared - materialised]].flat_map do |category, labels|
+          hedged = category == LABEL_REMOVED && !after.exhaustive?
+          labels.map { |label| event(category, symbol: symbol, table: table, label: label, hedged: hedged) }
+        end
+      end
+
+      def exhaustiveness_events(symbol, before, after, table)
+        return [] if before.exhaustive? == after.exhaustive?
+
+        category = after.exhaustive? ? EXHAUSTIVE_GAINED : EXHAUSTIVE_LOST
+        [event(category, symbol: symbol, table: table,
+                         detail: after.exhaustive? ? "not → exhaustive" : "exhaustive → not")]
+      end
+
+      def render_labels(entry)
+        "[#{entry.effects.join(', ')}]#{' …?' unless entry.exhaustive?}"
+      end
+
+      # Policy discharge, at judgment time. A single-label event is tolerated when the policy discharges
+      # that label; a symbol event when it discharges every label the symbol carries — and never when it
+      # carries none, because an empty set is discharged by nothing.
+      def event(category, symbol:, table:, label: nil, labels: nil, detail: nil, hedged: false)
+        Event.new(category: category, symbol: symbol, label: label, table: table, detail: detail,
+                  hedged: hedged, tolerated: tolerated?(category, symbol, table, label, labels))
+      end
+
+      def tolerated?(category, symbol, table, label, labels)
+        members = labels || (label ? [label] : nil)
+        return false if members.nil? || members.empty? || @tolerated.empty?
+
+        surviving = surviving_labels(category, symbol, table)
+        return members.none? { |member| surviving.include?(member) } if surviving
+
+        members.all? { |member| @tolerated.admits?(member) }
+      end
+
+      # The current side's undischarged labels for one symbol, or nil when this event is not one the
+      # per-origin judgment answers — no index, a removal, or a lane with no proven origins.
+      def surviving_labels(category, symbol, table)
+        return nil if @undischarged.nil? || symbol.nil?
+        return nil unless ORIGIN_JUDGED_CATEGORIES.include?(category)
+
+        @undischarged.dig(table, symbol)
+      end
+    end
+  end
+end