rigortype 0.3.8 → 0.4.0

data/sig/rigor/analysis/project_scan.rbs

@@ -0,0 +1,74 @@
+module Rigor
+  module Analysis
+    # Frozen snapshot of the project-wide pre-pass state the runner consumes — see
+    # lib/rigor/analysis/project_scan.rb for the full ownership/invalidation contract.
+    class ProjectScan < ::Data
+      # sig-gen gap: #1150 — `Data.define` member reads carry no type; `build_project_scan` fills
+      # this slot with the prepared `Plugin::Loader` result.
+      def plugin_registry: () -> Rigor::Plugin::Registry
+
+      # sig-gen gap: #1150 — as above (`DependencySourceInference::Builder.build` output, or
+      # `Index::EMPTY` when no dependencies are configured).
+      def dependency_source_index: () -> DependencySourceInference::Index
+
+      # `Inference::SyntheticMethodIndex` — the class is not yet declared under `sig/` (#1181
+      # backlog), so `untyped` is the honest member type for now.
+      def synthetic_method_index: () -> untyped
+
+      # `Inference::ProjectPatchedMethods` — unsigned like the slot above.
+      def project_patched_methods: () -> untyped
+
+      # sig-gen gap: #1150 — as above (`plugin_prepare_diagnostics` collects the
+      # `plugin_prepare_error_diagnostic` `Diagnostic`s, `[]` under pool mode).
+      def plugin_prepare_diagnostics: () -> Array[Analysis::Diagnostic]
+
+      # sig-gen gap: #1150 — as above. The pre-eval scanner deliberately emits a Hash shape (it
+      # must not depend on the analysis layer); the runner translates each row to a `Diagnostic`
+      # at the call site.
+      def pre_eval_diagnostics: () -> Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }]
+
+      # `Analysis::TemplateUnits` — unsigned (#1181 backlog), kept `untyped`.
+      def template_units: () -> untyped
+
+      # sig-gen gap: #1150 — as above; constructor keywords mirror the member declarations.
+      def self.new: (
+        plugin_registry: Rigor::Plugin::Registry,
+        dependency_source_index: DependencySourceInference::Index,
+        synthetic_method_index: untyped,
+        project_patched_methods: untyped,
+        plugin_prepare_diagnostics: Array[Analysis::Diagnostic],
+        pre_eval_diagnostics: Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }],
+        template_units: untyped
+      ) -> instance
+      | (
+        Rigor::Plugin::Registry plugin_registry,
+        DependencySourceInference::Index dependency_source_index,
+        untyped synthetic_method_index,
+        untyped project_patched_methods,
+        Array[Analysis::Diagnostic] plugin_prepare_diagnostics,
+        Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }] pre_eval_diagnostics,
+        untyped template_units
+      ) -> instance
+
+      # sig-gen gap: #1150 — as above.
+      def self.[]: (
+        plugin_registry: Rigor::Plugin::Registry,
+        dependency_source_index: DependencySourceInference::Index,
+        synthetic_method_index: untyped,
+        project_patched_methods: untyped,
+        plugin_prepare_diagnostics: Array[Analysis::Diagnostic],
+        pre_eval_diagnostics: Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }],
+        template_units: untyped
+      ) -> instance
+      | (
+        Rigor::Plugin::Registry plugin_registry,
+        DependencySourceInference::Index dependency_source_index,
+        untyped synthetic_method_index,
+        untyped project_patched_methods,
+        Array[Analysis::Diagnostic] plugin_prepare_diagnostics,
+        Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }] pre_eval_diagnostics,
+        untyped template_units
+      ) -> instance
+    end
+  end
+end

data/sig/rigor/analysis/reachability/scan_cache.rbs

@@ -0,0 +1,12 @@
+module Rigor
+  module Analysis
+    module Reachability
+      class ScanCache
+        def self.open: (untyped, ?target_ruby: untyped) -> Rigor::Analysis::Reachability::ScanCache
+        def self.source_digest: () -> String
+        def initialize: (path: untyped, header: untyped) -> void
+        def save: () -> nil
+      end
+    end
+  end
+end

data/sig/rigor/cache.rbs

@@ -16,9 +16,8 @@ module Rigor
       def self.fetch: (loader: untyped, store: untyped) -> untyped
 
       # The generation cap this producer declares to `Cache::Store#evict!`
-      # (issue #151). `rigor sig-gen` infers the literal `2` from the base
-      # body; the contract is the wider `Integer`, since a subclass may
-      # override it.
+      # (issue #151). The base body answers `2`; the contract is the wider
+      # `Integer`, since the cap is a knob a subclass may turn.
       def self.generation_cap: () -> Integer
     end
   end

data/sig/rigor/effects/config_envelopes.rbs

@@ -0,0 +1,100 @@
+module Rigor
+  module Effects
+    # `effects.envelopes:` entries resolved against the label vocabulary — the configured stratum of
+    # the envelope precedence (ADR-103 WD1).
+    module ConfigEnvelopes
+      CONFIG_PATH: String
+
+      # One entry, resolved against the vocabulary. `bound` is `LabelSet::TOP` when some member of
+      # `effect:` is unrecognised — the fail-open rule.
+      class Entry < ::Data
+        # sig-gen gap: #1150 — `Data.define` member reads carry no type; `build` proves each of these.
+        def index: () -> Integer
+
+        # sig-gen gap: #1150 — as above (path glob, or nil when `namespace:` is set).
+        def match: () -> String?
+
+        # sig-gen gap: #1150 — as above (constant-path glob, or nil when `match:` is set).
+        def namespace: () -> String?
+
+        # sig-gen gap: #1150 — as above (`LabelSet::TOP` on an unrecognised label).
+        def bound: () -> LabelSet
+
+        # sig-gen gap: #1150 — as above (the `effect:` list exactly as written).
+        def labels: () -> Array[String]
+
+        # sig-gen gap: #1150 — as above (well-formed spellings the registry did not know).
+        def unknown_labels: () -> Array[String]
+
+        # sig-gen gap: #1150 — as above; keyword form mirrors the member declarations.
+        def self.new: (
+          index: Integer,
+          match: String?,
+          namespace: String?,
+          bound: LabelSet,
+          labels: Array[String],
+          unknown_labels: Array[String]
+        ) -> instance
+        | (
+          Integer index,
+          String? match,
+          String? namespace,
+          LabelSet bound,
+          Array[String] labels,
+          Array[String] unknown_labels
+        ) -> instance
+
+        # sig-gen gap: #1150 — as above.
+        def self.[]: (
+          index: Integer,
+          match: String?,
+          namespace: String?,
+          bound: LabelSet,
+          labels: Array[String],
+          unknown_labels: Array[String]
+        ) -> instance
+        | (
+          Integer index,
+          String? match,
+          String? namespace,
+          LabelSet bound,
+          Array[String] labels,
+          Array[String] unknown_labels
+        ) -> instance
+
+        # `.rigor.yml effects.envelopes[N]` — the location spelling diagnostics name.
+        def location: () -> String
+
+        # The bound quoted back in the config's own spelling.
+        def spelling: () -> String
+
+        def top?: () -> bool
+      end
+
+      # `entries` are the shape-validated `Configuration#effects_envelopes` rows (String-keyed
+      # Hashes); `registry` is the `Effects::Registry` vocabulary — unsigned, so `untyped`.
+      def self?.build: (entries: Array[Hash[String, untyped]], registry: untyped) -> Array[Entry]
+
+      # One envelope per selected class, keyed by class name. `sources` is `Runner#effect_sources`'s
+      # shape; `project_root` is what those paths are relativised against.
+      def self?.for_classes: (
+        entries: Array[Entry],
+        class_names: Array[String],
+        ?sources: Hash[String, Array[String]],
+        ?project_root: String
+      ) -> Hash[String, Envelope]
+
+      # The {Envelope} one entry puts on one class.
+      def self?.envelope_for: (Entry entry, String class_name) -> Envelope
+
+      # Whether one entry selects a class — `paths` is `Array()`d, so `untyped` is honest.
+      def self?.selects?: (Entry entry, String class_name, untyped paths) -> bool
+
+      # `File.fnmatch?` with `FNM_PATHNAME` — the ADR-28 path-glob shape.
+      def self?.path_match?: (String glob, String path) -> bool
+
+      # Constant-path glob over the `::`-separated FQN; both arguments are `to_s`d.
+      def self?.namespace_match?: (untyped glob, untyped class_name) -> bool
+    end
+  end
+end

data/sig/rigor/effects/effect_table.rbs

@@ -0,0 +1,60 @@
+module Rigor
+  module Effects
+    # The propagated result of the fixpoint walk: every method's direct summary plus the transitive
+    # `proven` / `undischarged` / `declared` lanes, the exhaustiveness bit, and the resolved callee keys.
+    class EffectTable
+      # One row of the closed table.
+      class Entry < ::Data
+        # sig-gen gap: #1150 — `Data.define` member reads carry no type.
+        def key: () -> String
+        # sig-gen gap: #1150
+        def direct: () -> Summary
+        # sig-gen gap: #1150
+        def proven: () -> LabelSet
+        # sig-gen gap: #1150
+        def undischarged: () -> LabelSet
+        # sig-gen gap: #1150
+        def declared: () -> LabelSet
+        # sig-gen gap: #1150
+        def exhaustive: () -> bool
+        # sig-gen gap: #1150 — `causes` are frozen `[cause, detail]` pairs.
+        def causes: () -> Array[[String, String?]]
+        # sig-gen gap: #1150 — resolved callee keys (`"Class#m"` strings).
+        def edges: () -> Array[String]
+        # sig-gen gap: #1150
+        def unclaimed: () -> bool
+
+        # sig-gen gap: #1150 — the custom `initialize` supplies defaults for `undischarged` (=
+        # `proven`), `declared` (= empty) and `unclaimed` (= false); it accepts kwargs only, so the
+        # member constructor has no positional arm.
+        def self.new: (key: String, direct: Summary, proven: LabelSet, exhaustive: bool,
+                       causes: Array[[String, String?]], edges: Array[String],
+                       ?undischarged: LabelSet?, ?declared: LabelSet?, ?unclaimed: bool) -> instance
+        # sig-gen gap: #1150 — as above.
+        def self.[]: (key: String, direct: Summary, proven: LabelSet, exhaustive: bool,
+                      causes: Array[[String, String?]], edges: Array[String],
+                      ?undischarged: LabelSet?, ?declared: LabelSet?, ?unclaimed: bool) -> instance
+
+        def unclaimed?: () -> bool
+
+        # The declared labels worth printing beside `proven` — those the proven lane does not already
+        # admit.
+        def rendered_declared: () -> LabelSet
+
+        def exhaustive?: () -> bool
+        def trivial?: () -> bool
+      end
+
+      def self.empty: () -> EffectTable
+
+      def initialize: (Hash[String, Entry] entries) -> void
+
+      def []: (String key) -> Entry?
+      def keys: () -> Array[String]
+      def each: () { (Entry) -> untyped } -> void
+      include Enumerable[Entry]
+      def size: () -> Integer
+      def empty?: () -> bool
+    end
+  end
+end

data/sig/rigor/effects/envelope.rbs

@@ -0,0 +1,97 @@
+module Rigor
+  module Effects
+    # An author-declared upper bound on one method's effect labels (ADR-103 WD1). A `Data` record —
+    # see lib/rigor/effects/envelope.rb for the member semantics.
+    class Envelope < ::Data
+      # {#source} for a bound written in `.rigor.yml` rather than on a declaration.
+      CONFIG_SOURCE: :config_envelope
+
+      # sig-gen gap: #1150 — `Data.define` member reads carry no type; `build` proves each of these.
+      def owner_key: () -> String
+
+      # sig-gen gap: #1150 — as above; `LabelSet::TOP` means "no envelope" (the fail-open reading).
+      def bound: () -> LabelSet
+
+      # sig-gen gap: #1150 — as above; the four documented producers are the closed set.
+      def source: () -> (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope)
+
+      # sig-gen gap: #1150 — as above (`path:line`, the `.rigor.yml` key path, or nil).
+      def location: () -> String?
+
+      # sig-gen gap: #1150 — as above (the author's own annotation text, or nil).
+      def spelling: () -> String?
+
+      # sig-gen gap: #1150 — as above (sorted, de-duplicated by `build`; #384 reads them).
+      def unknown_labels: () -> Array[String]
+
+      # sig-gen gap: #1150 — as above (every token the tag listed, recognised or not).
+      def declared_labels: () -> Array[String]
+
+      # sig-gen gap: #1150 — as above; keyword form mirrors the member declarations.
+      def self.new: (
+        owner_key: String,
+        bound: LabelSet,
+        source: (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope),
+        location: String?,
+        spelling: String?,
+        unknown_labels: Array[String],
+        declared_labels: Array[String]
+      ) -> instance
+      | (
+        String owner_key,
+        LabelSet bound,
+        (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope) source,
+        String? location,
+        String? spelling,
+        Array[String] unknown_labels,
+        Array[String] declared_labels
+      ) -> instance
+
+      # sig-gen gap: #1150 — as above.
+      def self.[]: (
+        owner_key: String,
+        bound: LabelSet,
+        source: (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope),
+        location: String?,
+        spelling: String?,
+        unknown_labels: Array[String],
+        declared_labels: Array[String]
+      ) -> instance
+      | (
+        String owner_key,
+        LabelSet bound,
+        (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope) source,
+        String? location,
+        String? spelling,
+        Array[String] unknown_labels,
+        Array[String] declared_labels
+      ) -> instance
+
+      # Normalising constructor — sorts/dedupes `unknown_labels` and freezes `declared_labels`.
+      def self.build: (
+        owner_key: String,
+        bound: LabelSet,
+        source: (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope),
+        ?location: String?,
+        ?spelling: String?,
+        ?unknown_labels: Array[String],
+        ?declared_labels: Array[String]
+      ) -> Envelope
+
+      # Whether this reads as ⊤ — no bound at all.
+      def top?: () -> bool
+
+      # `label` is `to_s`-compared through {LabelSet#admits?}; `mutate.local` always tolerates.
+      def tolerates?: (untyped label) -> bool
+
+      # The members of `label_set` this envelope does NOT admit, sorted.
+      def exceeded_by: (LabelSet label_set) -> Array[String]
+
+      # Whether the bound was written in `.rigor.yml`.
+      def config?: () -> bool
+
+      # The same bound on another method key — the class-level distribution seam.
+      def rebind: (String key) -> Envelope
+    end
+  end
+end

data/sig/rigor/effects/envelope_index.rbs

@@ -0,0 +1,33 @@
+module Rigor
+  module Effects
+    # The envelopes a call site may import as a `≤` bound (ADR-103 WD6; #386) — per-method
+    # annotation, class-level annotation, `effects.envelopes:`, then the accepted signature stratum.
+    class EnvelopeIndex
+      # The index a run with no declaration of any kind uses — and the fail-soft answer for a build
+      # that raised.
+      def self.empty: () -> EnvelopeIndex
+
+      # Reads every stratum this index serves, once per process. `environment` supplies the accepted
+      # stratum through its RBS loader (nil drops it, fail-quiet); `plugin_facts` is the plugins'
+      # compiled `Effects::PluginFacts` contributions (nil where no plugin set was loaded).
+      def self.build: (configuration: Configuration, ?environment: Rigor::Environment?,
+                       ?plugin_facts: PluginFacts?) -> EnvelopeIndex
+
+      def initialize: (
+        ?method_envelopes: Hash[String, Envelope],
+        ?class_envelopes: Hash[String, Envelope],
+        ?config_entries: Array[ConfigEnvelopes::Entry],
+        ?accepted: Hash[String, Envelope]
+      ) -> void
+
+      # Whether no stratum has anything to say — the scan's fast path.
+      def empty?: () -> bool
+
+      # The envelope bounding `owner`'s `selector`, or nil — never a ⊤ envelope.
+      def []: (String? owner, bool singleton, untyped selector) -> Envelope?
+
+      # Whether ANY stratum carries an annotation for this key — ⊤ envelopes included (#391).
+      def annotated?: (String? owner, bool singleton, untyped selector) -> bool
+    end
+  end
+end

data/sig/rigor/effects/file_collection.rbs

@@ -0,0 +1,81 @@
+module Rigor
+  module Effects
+    # The per-file unit of the collection window (ADR-103): the direct summaries, the call edges, and
+    # the as-written ancestry a file contributes. {merge_all} folds a run's collections in one pass.
+    class FileCollection
+      # An ancestry entry that names nothing and can never resolve (#1039).
+      OPAQUE_ANCESTOR: String
+
+      # One recorded call edge: who the receiver's class is, which lane (`:instance` / `:singleton`)
+      # the selector dispatches on, and the bits that decide what an unresolved edge seeds.
+      class Edge < ::Data
+        # sig-gen gap: #1150 — `Data.define` member reads carry no type.
+        def receiver_class: () -> String?
+        # sig-gen gap: #1150
+        def kind: () -> (:instance | :singleton)
+        # sig-gen gap: #1150
+        def selector: () -> String
+        # sig-gen gap: #1150
+        def self_call: () -> bool
+        # sig-gen gap: #1150
+        def super_call: () -> bool
+        # sig-gen gap: #1150
+        def unclaimed: () -> bool
+        # sig-gen gap: #1150
+        def constant_receiver: () -> bool
+        # sig-gen gap: #1150 — the `[cause, detail]` pair an unresolved edge seeds, when the row
+        # named a `taint:`.
+        def taint_if_unresolved: () -> [String, String?]?
+        # sig-gen gap: #1150 — the plugin's lookup-order retry selectors (#1065).
+        def fallback_selectors: () -> Array[String]?
+
+        # sig-gen gap: #1150 — member constructor. The custom `initialize` accepts kwargs only and
+        # defaults every member after `self_call`, so there is no positional arm.
+        def self.new: (receiver_class: String?, kind: (:instance | :singleton), selector: String,
+                       self_call: bool, ?super_call: bool, ?unclaimed: bool,
+                       ?constant_receiver: bool, ?taint_if_unresolved: [String, String?]?,
+                       ?fallback_selectors: Array[String]?) -> instance
+        # sig-gen gap: #1150 — as above.
+        def self.[]: (receiver_class: String?, kind: (:instance | :singleton), selector: String,
+                      self_call: bool, ?super_call: bool, ?unclaimed: bool,
+                      ?constant_receiver: bool, ?taint_if_unresolved: [String, String?]?,
+                      ?fallback_selectors: Array[String]?) -> instance
+      end
+
+      # The collection a file with nothing to say contributes.
+      def self.empty: (?String? path) -> FileCollection
+
+      # sig-gen gap: #1154 — `initialize` freezes the kwarg tables rather than assigning them
+      # verbatim, so sig-gen proposes the default constant's shape for each reader.
+      attr_reader path: String?
+      # sig-gen gap: #1154 — `{ "Class#m" => Summary }`.
+      attr_reader summaries: Hash[String, Summary]
+      # sig-gen gap: #1154 — `{ "Class#m" => [Edge] }`, sorted and de-duplicated.
+      attr_reader edges: Hash[String, Array[Edge]]
+      # sig-gen gap: #1154 — `{ class_name => superclass_name }`, `OPAQUE_ANCESTOR` included.
+      attr_reader superclasses: Hash[String, String]
+      # sig-gen gap: #1154 — `{ class_name => [module_name] }`, include/prepend merged.
+      attr_reader includes: Hash[String, Array[String]]
+
+      def initialize: (?path: String?, ?summaries: Hash[String, Summary],
+                       ?edges: Hash[String, Array[Edge]], ?superclasses: Hash[String, String],
+                       ?includes: Hash[String, Array[String]], ?failed: bool) -> void
+
+      # Whether the collector gave up on this file entirely (the fail-soft path).
+      def failed?: () -> bool
+
+      # Whether this collection contributes nothing.
+      def empty?: () -> bool
+
+      # Two-collection fold — {merge_all} for a whole run.
+      def merge: (FileCollection other) -> FileCollection
+
+      # Folds a run's collections in one linear pass; order-independent except `superclasses`.
+      def self.merge_all: (Enumerable[FileCollection] collections) -> FileCollection
+
+      def ==: (untyped other) -> bool
+      alias eql? ==
+      def hash: () -> Integer
+    end
+  end
+end

data/sig/rigor/effects/label.rbs

@@ -0,0 +1,26 @@
+module Rigor
+  module Effects
+    # The effect-label grammar and segment-aware prefix subsumption (ADR-103 WD1). Every predicate is
+    # total — a malformed input is answered, never raised on — so the parameters are `untyped` on
+    # purpose.
+    module Label
+      PATTERN: Regexp
+
+      def self?.valid?: (untyped str) -> bool
+
+      # `[]` for a malformed label, the segments otherwise.
+      def self?.segments: (untyped label) -> Array[String]
+
+      def self?.subsumes?: (untyped bound, untyped label) -> bool
+
+      # One segment shallower; nil for a root and for a malformed label.
+      def self?.parent: (untyped label) -> String?
+
+      # Proper ancestors, outermost first; `[]` for a root and for a malformed label.
+      def self?.ancestors: (untyped label) -> Array[String]
+
+      # The outermost segment; nil for a malformed label.
+      def self?.root: (untyped label) -> String?
+    end
+  end
+end

data/sig/rigor/effects/label_set.rbs

@@ -0,0 +1,46 @@
+module Rigor
+  module Effects
+    # An immutable, sorted, de-duplicated set of effect labels (ADR-103 WD1) — the carrier of a
+    # summary lane and of an envelope's bound. `TOP` is the unbounded sentinel: it admits every
+    # label, absorbs every join, and answers `[]` from `to_a`.
+    class LabelSet
+      # `labels` is any enumerable of label Strings (`#to_a` is called on it); `top:` is internal —
+      # it exists to build {TOP} and is not part of the public surface.
+      def initialize: (?untyped labels, ?top: bool) -> void
+
+      TOP: LabelSet
+      EMPTY: LabelSet
+
+      def top?: () -> bool
+
+      # {TOP} is not empty: it records nothing because it stands for everything.
+      def empty?: () -> bool
+
+      # The members, sorted. {TOP} yields `[]` — consult {top?} first.
+      def to_a: () -> Array[String]
+
+      # Exact membership — `include?` is not subsumption ({admits?} is).
+      def include?: (untyped label) -> bool
+
+      # Whether some member subsumes `label`. {TOP} admits every well-formed label.
+      def admits?: (untyped label) -> bool
+
+      # Union — {TOP} absorbs. May return `self`/`other` without allocating.
+      def join: (LabelSet other) -> LabelSet
+
+      # The members `other` does not already admit — the declared lane's rendering rule.
+      def excluding_subsumed_by: (LabelSet other) -> LabelSet
+
+      # The envelope check, modulo policy discharge. {TOP} is bounded only by {TOP}.
+      def subsumed_by?: (LabelSet bound_set) -> bool
+
+      def ==: (untyped other) -> bool
+
+      # `alias eql? ==` — no sig-gen shape for alias rows; unmarked residue.
+      def eql?: (untyped other) -> bool
+
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+  end
+end

data/sig/rigor/effects/method_key.rbs

@@ -0,0 +1,24 @@
+module Rigor
+  module Effects
+    # The `Owner#selector` / `Owner.selector` key spelling (ADR-103 WD14). `key` parameters accept any
+    # object — every entry point `to_s`s its input — so they are `untyped` on purpose.
+    module MethodKey
+      TEMPLATE_UNIT_PREFIX: String
+
+      # `[owner, separator, selector]`, or nil when `key` is not a method key at all.
+      def self?.split: (untyped key) -> [String, String, String]?
+
+      def self?.valid?: (untyped key) -> bool
+
+      # The owner half of a method key, or nil.
+      def self?.owner: (untyped key) -> String?
+
+      # `view:`-prefixed template-unit keys are NOT method keys (#393).
+      def self?.template_unit?: (untyped key) -> bool
+
+      # The name an `effects.envelopes:` entry selects a key by — the owner class for a method key,
+      # the unit key itself for a template unit.
+      def self?.envelope_owner: (untyped key) -> String?
+    end
+  end
+end

data/sig/rigor/effects/origin.rbs

@@ -0,0 +1,50 @@
+module Rigor
+  module Effects
+    # Where one bundle of labels in a summary came from (ADR-103 WD14): a callee/construct `name`
+    # plus which `source` coloured it.
+    class Origin < ::Data
+      CONSTRUCT: :construct
+      CATALOGUE: :catalogue
+      ATTRIBUTION: :attribution
+      ENVELOPE: :envelope
+      PLUGIN: :plugin
+
+      # sig-gen gap: #1150 — `Data.define` member reads carry no type; every factory below proves
+      # `name` a `to_s`d String and `source` one of the five constants.
+      def name: () -> String
+
+      # sig-gen gap: #1150 — as above; the five source constants are the closed set.
+      def source: () -> (:construct | :catalogue | :attribution | :envelope | :plugin)
+
+      # sig-gen gap: #1150 — as above.
+      def self.new: (
+        name: String,
+        source: (:construct | :catalogue | :attribution | :envelope | :plugin)
+      ) -> instance
+      | (
+        String name,
+        (:construct | :catalogue | :attribution | :envelope | :plugin) source
+      ) -> instance
+
+      # sig-gen gap: #1150 — as above.
+      def self.[]: (
+        name: String,
+        source: (:construct | :catalogue | :attribution | :envelope | :plugin)
+      ) -> instance
+      | (
+        String name,
+        (:construct | :catalogue | :attribution | :envelope | :plugin) source
+      ) -> instance
+
+      # `name` is `to_s`d, so any object is acceptable — `untyped` is the honest parameter.
+      def self.construct: (untyped name) -> Origin
+      def self.catalogue: (untyped name) -> Origin
+      def self.attribution: (untyped name) -> Origin
+      def self.envelope: (untyped name) -> Origin
+      def self.plugin: (untyped name) -> Origin
+
+      # `"source:name"` — the rendering the report and the JSON payload key on.
+      def to_s: () -> String
+    end
+  end
+end