hecks 3.4.2 → 3.6.0

data/lib/hecks/projector/exporter/translations.rb

@@ -0,0 +1,127 @@
+module Hecks
+  module Projector
+    module Exporter
+      # The registered translation edges as Hashes and JSON: the declared rules a digest hashes,
+      # and the same rules with each aggregate's precompiled SQL attached.
+      module Translations
+        # Every registered translation, with each aggregate's precompiled SQL attached —
+        # `values:` serializes as `[key, value]` pairs since a convert's keys are typed.
+        #
+        # @param registry [Runtime::Registry] the booted registry to export translations from
+        # @return [Array<Hash>] every registered translation, as `compiled_translation_hash`
+        #   builds
+        def translations(registry)
+          registry.translations.map { |translation| compiled_translation_hash(translation) }
+        end
+
+        # Exports one translation, its aggregates' compiled SQL included.
+        #
+        # @param translation [Bluebook::Translation] the translation to export
+        # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
+        #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
+        #   (each `compiled_translation_aggregate`'s own Hash)
+        def compiled_translation_hash(translation)
+          {
+            domain:     translation.domain,
+            from:       translation.from,
+            to:         translation.to,
+            retired:    translation.retired,
+            aggregates: translation.aggregates.map { |aggregate| compiled_translation_aggregate(aggregate) }
+          }
+        end
+
+        # Exports every registered translation as JSON.
+        #
+        # @param registry [Runtime::Registry] the booted registry to export translations from
+        # @return [String] `translations`' output, as pretty-printed JSON
+        def translations_json(registry)
+          JSON.pretty_generate(translations(registry))
+        end
+
+        # The digest-relevant shape `ApprovalDigest.edge_digest` hashes — declared rules only,
+        # never the compiled SQL, so a compiler-output change can't invalidate an approval.
+        #
+        # @param translation [Bluebook::Translation] the translation to digest
+        # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
+        #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
+        #   (each `translation_aggregate`'s own Hash)
+        def translation_hash(translation)
+          {
+            domain:     translation.domain,
+            from:       translation.from,
+            to:         translation.to,
+            retired:    translation.retired,
+            aggregates: translation.aggregates.map { |aggregate| translation_aggregate(aggregate) }
+          }
+        end
+
+        # Digests one aggregate's own declared translation rules.
+        #
+        # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
+        #   translation rules to digest
+        # @return [Hash{Symbol => Object}] `:name` (String), `:was` (String, nil),
+        #   `:renames` (`Hash{String => String}`), `:moves`/`:converts`/`:retypes`/
+        #   `:computes`/`:rekeys`/`:backfills` (each an `Array<Hash>`), `:drops`
+        #   (`Array<String>`)
+        def translation_aggregate(aggregate)
+          structural_rules(aggregate).merge(typed_rules(aggregate)).merge(computed_rules(aggregate))
+        end
+
+        # `translation_aggregate`'s fields, plus precompiled SQL from the same
+        # `Translation::RuleCompiler` mint time uses (ADR 0033 governs its fallback).
+        #
+        # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
+        #   translation rules to compile and export
+        # @return [Hash{Symbol => Object}] `translation_aggregate`'s own Hash, plus
+        #   `:compiled_state_expression` (String) and `:compiled_id_expression`
+        #   (String, nil) when the era persistence plugin is loaded
+        def compiled_translation_aggregate(aggregate)
+          return translation_aggregate(aggregate) unless Ports::Persistence.plugin?(:era)
+
+          translation_aggregate(aggregate).merge(
+            compiled_state_expression: Translation::RuleCompiler.compile_rules(aggregate),
+            compiled_id_expression:    (if Translation::RuleCompiler.rekeyed?(aggregate)
+                                          Translation::RuleCompiler.compile_id_expression(aggregate)
+                                        end)
+          )
+        end
+
+        private
+
+        # The aggregate's name, former name, renames and moves.
+        def structural_rules(aggregate)
+          {
+            name:    aggregate.name,
+            was:     aggregate.was,
+            renames: aggregate.renames.transform_keys(&:to_s).transform_values(&:to_s),
+            moves:   aggregate.moves.map { |move| { from: move.from, to: move.to } }
+          }
+        end
+
+        # The converts, drops and retypes of an aggregate.
+        def typed_rules(aggregate)
+          {
+            converts: aggregate.converts.map do |convert|
+              { from: convert.from, to: convert.to, values: convert.values.map { |key, value| [key, value] } }
+            end,
+            drops:    aggregate.drops.map(&:to_s),
+            retypes:  aggregate.retypes.map { |retype| { from: retype.from, to: retype.to } }
+          }
+        end
+
+        # The computes, rekeys and backfills of an aggregate.
+        #
+        # `rekeys`/`backfills` are digest-relevant too — a rekey with no compute
+        # would otherwise collide with any other, letting its SQL change silently
+        # invalidate nothing.
+        def computed_rules(aggregate)
+          {
+            computes:  aggregate.computes.map { |compute| { from: compute.from, to: compute.to, sql: compute.sql } },
+            rekeys:    aggregate.rekeys.map { |rekey| { sql: rekey.sql } },
+            backfills: aggregate.backfills.map { |backfill| { name: backfill.name.to_s, default: backfill.default } }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/exporter.rb

@@ -1,10 +1,16 @@
 require "json"
 require_relative "../ports/persistence"
+require_relative "exporter/bindings"
+require_relative "exporter/translations"
 
 module Hecks
   module Projector
     # Registry-wide serialization to Hash/JSON, for the canonical bluebook IR,
     # binding facts, and translation edges (declared and compiled).
+    #
+    # The capability bindings (`authorization`, `membership`, ...) are `Exporter::Bindings` and
+    # the translation edges (`translations`, `translation_hash`, ...) are `Exporter::Translations`;
+    # both are reachable as methods of `Exporter` itself.
     module Exporter
       module_function
 
@@ -66,285 +72,8 @@ module Hecks
         { aggregates: aggregates }
       end
 
-      # Which chapter this domain's role checks resolve against
-      # (`Registry#authorization_provider_for`); `{}` if none does.
-      #
-      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-      # @param domain_name [String] the domain to export the authorization binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), `:grant`, `:assignments`
-      #   (both provided-verb names), and `:assignment_aggregate` (`:assignments`' own
-      #   leading aggregate name); `{}` if nothing this domain attaches provides
-      #   authorization
-      def authorization(registry, domain_name)
-        provider = registry.authorization_provider_for(domain_name)
-        return {} unless provider
-
-        capability = Bluebook::Capabilities::AUTHORIZATION
-        assignments = provider.provided_verb(capability, :assignments)
-        {
-          provider:             provider.name,
-          grant:                provider.provided_verb(capability, :grant),
-          assignments:          assignments,
-          assignment_aggregate: assignments&.split(".")&.first
-        }
-      end
-
-      # Which chapter answers "who may sign in" (`Registry#membership_provider_for`),
-      # with the membership aggregate named off `admit`; `{}` if none does.
-      #
-      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-      # @param domain_name [String] the domain to export the membership binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), `:admit`, `:grant`,
-      #   `:people` (qualified verbs), and `:aggregate` (`:admit`'s own leading
-      #   aggregate name); `{}` if nothing this domain attaches provides membership
-      def membership(registry, domain_name)
-        provider = registry.membership_provider_for(domain_name)
-        return {} unless provider
-
-        capability = Bluebook::Capabilities::MEMBERSHIP
-        admit = provider.provided_verb(capability, :admit)
-        {
-          provider:  provider.name,
-          admit:     admit,
-          grant:     provider.provided_verb(capability, :grant),
-          people:    provider.provided_verb(capability, :people),
-          aggregate: admit&.split(".")&.first
-        }
-      end
-
-      # Which chapter answers "who is this authenticated pair"; `{}` if none does.
-      # Breaking in 2.0: Link's reference field is `identity`, never `identity_id`.
-      #
-      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-      # @param domain_name [String] the domain to export the identity binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), `:register`, `:link`,
-      #   `:resolve` (qualified verbs); `{}` if nothing this domain attaches provides identity
-      def identity(registry, domain_name)
-        provider = registry.identity_provider_for(domain_name)
-        return {} unless provider
-
-        capability = Bluebook::Capabilities::IDENTITY
-        {
-          provider: provider.name,
-          register: provider.provided_verb(capability, :register),
-          link:     provider.provided_verb(capability, :link),
-          resolve:  provider.provided_verb(capability, :resolve)
-        }
-      end
-
-      # Which chapter answers the guest newsletter signup
-      # (`Registry#newsletter_provider_for`); `{}` if none does.
-      #
-      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-      # @param domain_name [String] the domain to export the newsletter binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), `:subscribe`, `:add_name`,
-      #   `:confirm`, `:unsubscribe` (qualified verbs), and `:aggregate` (`:subscribe`'s own
-      #   leading qualified aggregate name); `{}` if nothing this domain attaches provides
-      #   newsletter
-      def newsletter(registry, domain_name)
-        provider = registry.newsletter_provider_for(domain_name)
-        return {} unless provider
-
-        capability = Bluebook::Capabilities::NEWSLETTER
-        subscribe = provider.provided_verb(capability, :subscribe)
-        {
-          provider:    provider.name,
-          subscribe:   subscribe,
-          add_name:    provider.provided_verb(capability, :add_name),
-          confirm:     provider.provided_verb(capability, :confirm),
-          unsubscribe: provider.provided_verb(capability, :unsubscribe),
-          aggregate:   subscribe&.split(".")&.first
-        }
-      end
-
-      # Which chapter answers sending a newsletter issue
-      # (`Registry#newsletter_issues_provider_for`); `{}` if none does.
-      #
-      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-      # @param domain_name [String] the domain to export the issue-sending binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), `:send_issue`,
-      #   `:record_delivery` (qualified verbs), `:issue_aggregate` and `:delivery_aggregate`
-      #   (each verb's own leading qualified aggregate name); `{}` if nothing this domain
-      #   attaches provides newsletter_issues
-      def newsletter_issues(registry, domain_name)
-        provider = registry.newsletter_issues_provider_for(domain_name)
-        return {} unless provider
-
-        capability = Bluebook::Capabilities::NEWSLETTER_ISSUES
-        send_issue = provider.provided_verb(capability, :send_issue)
-        record_delivery = provider.provided_verb(capability, :record_delivery)
-        {
-          provider:           provider.name,
-          send_issue:         send_issue,
-          record_delivery:    record_delivery,
-          issue_aggregate:    send_issue&.split(".")&.first,
-          delivery_aggregate: record_delivery&.split(".")&.first
-        }
-      end
-
-      # Which chapter answers scheduling sessions and taking registrations
-      # (`Registry#registrations_provider_for`); `{}` if none does.
-      #
-      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-      # @param domain_name [String] the domain to export the registrations binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), `:schedule`, `:request`
-      #   (qualified verbs), `:event_aggregate` and `:registration_aggregate` (each verb's own
-      #   leading qualified aggregate name); `{}` if nothing this domain attaches provides
-      #   registrations
-      def registrations(registry, domain_name)
-        provider = registry.registrations_provider_for(domain_name)
-        return {} unless provider
-
-        capability = Bluebook::Capabilities::REGISTRATIONS
-        schedule = provider.provided_verb(capability, :schedule)
-        request = provider.provided_verb(capability, :request)
-        {
-          provider:               provider.name,
-          schedule:               schedule,
-          request:                request,
-          event_aggregate:        schedule&.split(".")&.first,
-          registration_aggregate: request&.split(".")&.first
-        }
-      end
-
-      # Which chapter owns the payment-processor connection
-      # (`Registry#payment_connection_provider_for`); `{}` if none does.
-      #
-      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-      # @param domain_name [String] the domain to export the payment-connection binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), one qualified verb per
-      #   contract key (`:connect`, `:reconnect`, `:disconnect`, `:suspend`, `:resume`,
-      #   `:enable`, `:disable`) and `:aggregate` (`:connect`'s own leading qualified
-      #   aggregate name); `{}` if nothing this domain attaches provides payment_connection
-      def payment_connection(registry, domain_name)
-        provider = registry.payment_connection_provider_for(domain_name)
-        return {} unless provider
-
-        capability = Bluebook::Capabilities::PAYMENT_CONNECTION
-        verbs = Bluebook::Capabilities::CONTRACTS.fetch(capability).keys.to_h { |key| [key, provider.provided_verb(capability, key)] }
-        { provider: provider.name, **verbs, aggregate: verbs[:connect]&.split(".")&.first }
-      end
-
-      # Which chapter takes payments (`Registry#payments_provider_for`);
-      # `{}` if none does.
-      #
-      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-      # @param domain_name [String] the domain to export the payments binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), `:initiate`, `:succeeded`,
-      #   `:failed` (qualified verbs), and `:aggregate` (`:initiate`'s own leading qualified
-      #   aggregate name); `{}` if nothing this domain attaches provides payments
-      def payments(registry, domain_name)
-        provider = registry.payments_provider_for(domain_name)
-        return {} unless provider
-
-        capability = Bluebook::Capabilities::PAYMENTS
-        initiate = provider.provided_verb(capability, :initiate)
-        {
-          provider:  provider.name,
-          initiate:  initiate,
-          succeeded: provider.provided_verb(capability, :succeeded),
-          failed:    provider.provided_verb(capability, :failed),
-          aggregate: initiate&.split(".")&.first
-        }
-      end
-
-      # Every registered translation, with each aggregate's precompiled SQL attached —
-      # `values:` serializes as `[key, value]` pairs since a convert's keys are typed.
-      #
-      # @param registry [Runtime::Registry] the booted registry to export translations from
-      # @return [Array<Hash>] every registered translation, as `compiled_translation_hash`
-      #   builds
-      def translations(registry)
-        registry.translations.map { |translation| compiled_translation_hash(translation) }
-      end
-
-      # Exports one translation, its aggregates' compiled SQL included.
-      #
-      # @param translation [Bluebook::Translation] the translation to export
-      # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
-      #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
-      #   (each `compiled_translation_aggregate`'s own Hash)
-      def compiled_translation_hash(translation)
-        {
-          domain:     translation.domain,
-          from:       translation.from,
-          to:         translation.to,
-          retired:    translation.retired,
-          aggregates: translation.aggregates.map { |aggregate| compiled_translation_aggregate(aggregate) }
-        }
-      end
-
-      # Exports every registered translation as JSON.
-      #
-      # @param registry [Runtime::Registry] the booted registry to export translations from
-      # @return [String] `translations`' output, as pretty-printed JSON
-      def translations_json(registry)
-        JSON.pretty_generate(translations(registry))
-      end
-
-      # The digest-relevant shape `ApprovalDigest.edge_digest` hashes — declared rules only,
-      # never the compiled SQL, so a compiler-output change can't invalidate an approval.
-      #
-      # @param translation [Bluebook::Translation] the translation to digest
-      # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
-      #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
-      #   (each `translation_aggregate`'s own Hash)
-      def translation_hash(translation)
-        {
-          domain:     translation.domain,
-          from:       translation.from,
-          to:         translation.to,
-          retired:    translation.retired,
-          aggregates: translation.aggregates.map { |aggregate| translation_aggregate(aggregate) }
-        }
-      end
-
-      # Digests one aggregate's own declared translation rules.
-      #
-      # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
-      #   translation rules to digest
-      # @return [Hash{Symbol => Object}] `:name` (String), `:was` (String, nil),
-      #   `:renames` (`Hash{String => String}`), `:moves`/`:converts`/`:retypes`/
-      #   `:computes`/`:rekeys`/`:backfills` (each an `Array<Hash>`), `:drops`
-      #   (`Array<String>`)
-      def translation_aggregate(aggregate)
-        {
-          name:      aggregate.name,
-          was:       aggregate.was,
-          renames:   aggregate.renames.transform_keys(&:to_s).transform_values(&:to_s),
-          moves:     aggregate.moves.map { |move| { from: move.from, to: move.to } },
-          converts:  aggregate.converts.map do |convert|
-            { from: convert.from, to: convert.to, values: convert.values.map { |key, value| [key, value] } }
-          end,
-          drops:     aggregate.drops.map(&:to_s),
-          retypes:   aggregate.retypes.map { |retype| { from: retype.from, to: retype.to } },
-          computes:  aggregate.computes.map { |compute| { from: compute.from, to: compute.to, sql: compute.sql } },
-          # `rekeys`/`backfills` are digest-relevant too — a rekey with no compute
-          # would otherwise collide with any other, letting its SQL change silently
-          # invalidate nothing.
-          rekeys:    aggregate.rekeys.map { |rekey| { sql: rekey.sql } },
-          backfills: aggregate.backfills.map { |backfill| { name: backfill.name.to_s, default: backfill.default } }
-        }
-      end
-
-      # `translation_aggregate`'s fields, plus precompiled SQL from the same
-      # `Translation::RuleCompiler` mint time uses (ADR 0033 governs its fallback).
-      #
-      # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
-      #   translation rules to compile and export
-      # @return [Hash{Symbol => Object}] `translation_aggregate`'s own Hash, plus
-      #   `:compiled_state_expression` (String) and `:compiled_id_expression`
-      #   (String, nil) when the era persistence plugin is loaded
-      def compiled_translation_aggregate(aggregate)
-        return translation_aggregate(aggregate) unless Ports::Persistence.plugin?(:era)
-
-        translation_aggregate(aggregate).merge(
-          compiled_state_expression: Translation::RuleCompiler.compile_rules(aggregate),
-          compiled_id_expression:    (if Translation::RuleCompiler.rekeyed?(aggregate)
-                                        Translation::RuleCompiler.compile_id_expression(aggregate)
-                                      end)
-        )
-      end
+      extend Bindings
+      extend Translations
     end
   end
 end

data/lib/hecks/projector/narrate_projector/commands.rb

@@ -0,0 +1,108 @@
+module Hecks
+  module Projector
+    module NarrateProjector
+      # The prose for the verbs of an aggregate or entity: one paragraph per command, each
+      # sentence quoting a declared `goal`, `role`, argument, `given` or `ensure`.
+      module Commands
+        module_function
+
+        # The "What can happen to ..." section for `holder`, or `nil` when it has no commands.
+        def verbs_narrative(holder, depth)
+          return nil if holder.commands.empty?
+
+          name   = holder.hecks_name
+          header = DocsProjector.h(depth, "What can happen to #{NarrateProjector.a_or_an(name)} #{name}")
+          body   = holder.commands.map { |command| command_paragraph(command, holder) }.join("\n\n")
+          "#{header}\n\n#{body}"
+        end
+
+        # Each sentence states one independent fact, so nil-or-string plus `compact.join` suffices.
+        def command_paragraph(command, holder)
+          [
+            command_headline_sentence(command),
+            command_role_sentence(command),
+            command_creation_sentence(command, holder),
+            command_arguments_sentence(command),
+            command_references_sentence(command),
+            command_conditions_sentence(command, holder),
+            command_guarantees_sentence(command),
+            command_emits_sentence(command)
+          ].compact.join(" ")
+        end
+
+        # The goal is quoted exactly as declared, never recased to fit mid-sentence.
+        def command_headline_sentence(command)
+          "**#{command.hecks_name}**#{command.goal ? " — #{command.goal}." : "."}"
+        end
+
+        def command_role_sentence(command)
+          return nil unless command.role
+
+          "Issued by #{NarrateProjector.a_or_an(command.role)} #{command.role}."
+        end
+
+        # `acts_on.nil?`, not `creates?`: `creates?` is true for every entity verb, which would
+        # wrongly say `LedgerEntry.Amend` creates a new ledger entry.
+        def command_creation_sentence(command, holder)
+          return nil unless command.acts_on.nil?
+
+          "This is how a new #{holder.hecks_name} comes into being."
+        end
+
+        def command_arguments_sentence(command)
+          arguments = command.attributes.reject(&:reference?)
+          return nil if arguments.empty?
+
+          labels = arguments.map { |a| Forms::Humanize.label(a.name.to_s).downcase }
+          "It takes #{NarrateProjector.to_sentence_list(labels)}."
+        end
+
+        def command_references_sentence(command)
+          refs = command.attributes.select(&:reference?)
+          return nil if refs.empty?
+
+          "It's aimed at one existing #{NarrateProjector.to_sentence_list(refs.map { |r| r.type.target_name })}, by id."
+        end
+
+        def command_conditions_sentence(command, holder)
+          conditions = conditions_of(command, holder)
+          return nil if conditions.empty?
+
+          "It only goes through if #{conditions.join("; ")}."
+        end
+
+        def command_guarantees_sentence(command)
+          guarantees = command.ensures.map(&:description)
+          return nil if guarantees.empty?
+
+          "When it succeeds: #{guarantees.join("; ")}."
+        end
+
+        def command_emits_sentence(command)
+          return nil if command.emits.empty?
+
+          "It records `#{command.emits.join("`, `")}` as a fact."
+        end
+
+        # Required conditions stated positively ("only goes through if X"), from the lifecycle
+        # edge and the command's `given`s.
+        def conditions_of(command, holder)
+          lifecycle_conditions(command, holder.lifecycle) + command.givens.map(&:description)
+        end
+
+        # The condition that the record is in a state the lifecycle allows the command from.
+        def lifecycle_conditions(command, lifecycle)
+          return [] unless lifecycle
+
+          froms = lifecycle.transitions.filter_map do |name, transition|
+            Array(transition.from) if name.to_s == command.hecks_name
+          end.flatten.uniq
+          return [] if froms.empty?
+
+          states = NarrateProjector.to_sentence_list(froms.map { |f| "`#{f}`" }, conj: "or")
+          ["its `#{lifecycle.field}` is currently #{states}"]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/narrate_projector/reactions.rb

@@ -0,0 +1,33 @@
+module Hecks
+  module Projector
+    module NarrateProjector
+      # The prose for what a chapter causes on its own: its policies and its sagas.
+      module Reactions
+        module_function
+
+        # The "Reactions" section, or `nil` when the chapter has no policies or sagas.
+        def narrative(bluebook, depth)
+          return nil if bluebook.policies.empty? && bluebook.process_managers.empty?
+
+          [DocsProjector.h(depth, "Reactions"), *bluebook.policies.map { |policy| policy_sentence(policy) },
+           *bluebook.process_managers.map { |saga| saga_sentence(saga) }].join("\n\n")
+        end
+
+        # A policy as the sentence saying it fires on its own.
+        def policy_sentence(policy)
+          elsewhere = policy.target_domain ? " in #{policy.target_domain}" : ""
+          "Whenever `#{policy.on_event}` happens, `#{policy.trigger_command}` fires on its own#{elsewhere} — " \
+            "nobody has to ask for it."
+        end
+
+        # A saga as the sentence saying where it starts, ends and what it moves through.
+        def saga_sentence(saga)
+          shape = saga.to_h
+          "**#{shape[:name]}** is a saga: it starts when `#{shape[:starts_on]}` happens and ends when " \
+            "`#{shape[:ends_on]}` happens, with each run tracked by its `#{shape[:correlates_by]}`. Along the " \
+            "way it moves through #{Array(shape[:states]).map { |s| "`#{s}`" }.join(" → ")}."
+        end
+      end
+    end
+  end
+end