hecks 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8261eb6f8b8b490fda7cc10deed5d1668e677031b03d67c89ca2c706cb90140a
-  data.tar.gz: 005ef58bad7618ab6085b22c9483465d2b58af9a9c61db7a365e70db81f4a5d6
+  metadata.gz: 1fad5f64ba40ddec2720f013efc33d54e7ce5ebaf0926bc0670b642f91e53416
+  data.tar.gz: a714cad37a3a9c02f2ece530fc2c417e019f3ac47e0f0b76fd2c336416c2d55d
 SHA512:
-  metadata.gz: 926f57e7d5a1af30ec918269460bc04a20c25dd1feaaf8da910fe0a0ea241f7b4622feec775dfa8390bba16253b6d4b18130b0ea5a0e544259cae70cbd961cbe
-  data.tar.gz: aca0677bd624c1a61d9f6d3dbe6f0e74991d690557d4abed0abf4a3e4a240931434a375b633ba7f424f04c3c36a2454811608ca2894a99d12cbdc2460876ca1b
+  metadata.gz: 3ed37d25061346166c25415b92be46409ecefa3eb762fef81941c4758ecc3a2681241f29a4c819a28ad360ee0267919612f9fedb9c56c1be00d0a9a70d512e6e
+  data.tar.gz: 7b6b0df13da60ef2a40a002d2a847b284164518c51363227c01f1d00e548e3d544b25a27d28053ff1af2469c6f802f4a5bd94103b6d2a9a9ed491710b9152217

data/lib/hecks/bluebook/capabilities.rb

@@ -8,7 +8,12 @@ module Hecks
     # complete and point at real verbs. `BluebookBuilder::Validation
     # #validate_provisions!` holds every `provides` to this table.
     #
-    #   key => :command | :query   the kind of verb that key must name
+    #   key => :command | :query | :port_operation   the kind of verb that key must name
+    #
+    # A `:port_operation` verb is spelled `"Aggregate.Port.Operation"` and names
+    # an operation the chapter's hecksagon declares on one of its aggregates.
+    # The hecksagon attaches after the chapter is built, so the chapter itself
+    # only checks the spelling; `Registry#verify!` checks the operation exists.
     module Capabilities
       AUTHORIZATION = "authorization".freeze
       # Who may sign in, and with what role — rust/host's Google-OAuth
@@ -22,6 +27,19 @@ module Hecks
       # is. rust/host does not build this chapter's payloads; any field
       # mapping lives on the consuming hecksagon's `translates` ACL.
       IDENTITY = "identity".freeze
+      # Guest-facing newsletter signup: who subscribed, confirmed, or left —
+      # recognised by declaration, not the literal chapter name
+      # "Newsletter". rust/host's newsletter routes dispatch these verbs
+      # and read the subscribing aggregate's instances off `subscribe`.
+      NEWSLETTER = "newsletter".freeze
+      # Taking a payment through an external processor: start one, then
+      # hear the processor's verdict — recognised by declaration, not the
+      # literal chapter name "Payments". rust/host's checkout and webhook
+      # routes dispatch these verbs and read the paying aggregate's
+      # instances off `initiate`. The two verdicts are hecksagon port
+      # operations (the processor's webhook, translated into this chapter's
+      # vocabulary), not commands.
+      PAYMENTS = "payments".freeze
 
       CONTRACTS = {
         AUTHORIZATION => {
@@ -47,6 +65,24 @@ module Hecks
           link:     :command,
           # look up the identity an authenticated pair resolves to
           resolve:  :query
+        }.freeze,
+        NEWSLETTER    => {
+          # a guest signs up; the aggregate it names is the subscriber
+          subscribe:   :command,
+          # attach a display name to an existing subscriber
+          add_name:    :command,
+          # a subscriber confirms their address from the emailed link
+          confirm:     :command,
+          # a subscriber leaves from the emailed link
+          unsubscribe: :command
+        }.freeze,
+        PAYMENTS      => {
+          # start a payment; the aggregate it names is the payment
+          initiate:  :command,
+          # the processor reports the money arrived
+          succeeded: :port_operation,
+          # the processor reports the payment failed or expired
+          failed:    :port_operation
         }.freeze
       }.freeze
     end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation.rb

@@ -113,12 +113,14 @@ module Hecks
           # @param capability [String] the capability the row belongs to, such as
           #   `"authorization"`
           # @param row [Bluebook::Chapter::Provision] the one declared row to check
-          # @param kind [Symbol] `:command` or `:query`, the kind of verb this row's key
-          #   must name (from `Capabilities::CONTRACTS`)
+          # @param kind [Symbol] `:command`, `:query` or `:port_operation`, the kind of
+          #   verb this row's key must name (from `Capabilities::CONTRACTS`)
           # @return [void]
           # @raise [Bluebook::DSL::Malformed] if `row.verb` does not split into a real
           #   aggregate and a member of the right kind that aggregate declares
           def validate_provided_verb!(bluebook, capability, row, kind)
+            return validate_provided_port_operation!(bluebook, capability, row) if kind == :port_operation
+
             aggregate_name, member = row.verb.split(".", 2)
             aggregate = bluebook.aggregate(aggregate_name)
             return if aggregate && member && provided_member_names(aggregate, kind).include?(member)
@@ -127,6 +129,26 @@ module Hecks
                              "which names no #{kind} this chapter declares (spelled \"Aggregate.#{kind.capitalize}\")"
           end
 
+          # Checks the spelling of a `provides` verb that names a hecksagon port
+          # operation. The port itself is declared in the hecksagon, which attaches
+          # after this chapter is built, so all that can be checked here is that the
+          # verb has the `"Aggregate.Port.Operation"` shape and its aggregate is
+          # this chapter's; `Registry#verify!` checks the operation exists.
+          #
+          # @param bluebook [Bluebook::Chapter] the chapter the row was declared on
+          # @param capability [String] the capability the row belongs to
+          # @param row [Bluebook::Chapter::Provision] the one declared row to check
+          # @return [void]
+          # @raise [Bluebook::DSL::Malformed] if the verb is not `"Aggregate.Port.Operation"`
+          #   or names an aggregate this chapter does not declare
+          def validate_provided_port_operation!(bluebook, capability, row)
+            aggregate_name, port, operation = row.verb.split(".", 3)
+            return if bluebook.aggregate(aggregate_name) && port && operation && !operation.include?(".")
+
+            raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                             "which is not spelled \"Aggregate.Port.Operation\" over an aggregate this chapter declares"
+          end
+
           # Names of the members a `provides` verb of the given kind may address.
           #
           # @param aggregate [Bluebook::Aggregate] the aggregate the verb is scoped to

data/lib/hecks/corpus.rb

@@ -284,7 +284,7 @@ module Hecks
       # lifeadelics) — the generated module and Cargo feature are
       # "lifeadelics" now, matching every other domain's own convention.
       #
-      # Lifeadelics also attaches `accounts`/`newsletter`/`payments`
+      # Lifeadelics also attaches `newsletter`/`payments`/`membership`
       # (its own vendored embryonaut_bluebooks packages, see
       # RUST_EXTERNAL_VENDORED_CHAPTERS below) and `Privacy` (an in-repo
       # framework chapter, lib/hecks/framework/bluebook/privacy.bluebook,
@@ -312,7 +312,6 @@ module Hecks
     # same as an in-repo vendored chapter (see
     # `rust_external_vendored_domain_dir`, below).
     RUST_EXTERNAL_VENDORED_CHAPTERS = {
-      "accounts"   => "lifeadelics",
       "newsletter" => "lifeadelics",
       "payments"   => "lifeadelics",
       "membership" => "lifeadelics"
@@ -365,14 +364,12 @@ module Hecks
     # still fail, so an entry that starts passing breaks the build until
     # it is deleted here.
     RUST_COVERAGE_PENDING = {
-      "accounts"    => "query Listing declares no where clause at all (\"every account, alphabetically by " \
-                       "email\") — rust/project/queries.rb's own no_wheres skip refuses to generate an " \
-                       "unfiltered per_instance Listing (\"nothing for filter_entries to bake in\"); a " \
-                       "structural Rust codegen limitation, not a bug in this vendored package",
-      "newsletter"  => "same no_wheres gap as accounts, on all 3 of its own Listing queries " \
-                       "(Delivery/Issue/Subscriber) — see accounts' entry above",
-      "lifeadelics" => "same no_wheres gap as accounts, on Registration.Listing — see accounts' entry above",
-      "membership"  => "same no_wheres gap as accounts, on Person.All — see accounts' entry above"
+      "newsletter"  => "query Listing declares no where clause at all, on all 3 of its own Listing queries " \
+                       "(Delivery/Issue/Subscriber) — rust/project/queries.rb's own no_wheres skip refuses " \
+                       "to generate an unfiltered per_instance Listing (\"nothing for filter_entries to " \
+                       "bake in\"); a structural Rust codegen limitation, not a bug in this vendored package",
+      "lifeadelics" => "same no_wheres gap as newsletter, on Registration.Listing — see newsletter's entry above",
+      "membership"  => "same no_wheres gap as newsletter, on Person.All — see newsletter's entry above"
     }.freeze
 
     # The Cargo `[features]` table's raw text.

data/lib/hecks/language/bluebook/bluebook.bluebook

@@ -296,6 +296,13 @@ Hecks.bluebook "Bluebook", version: "1" do
       member keyword: "provides",        context: "Bluebook", at: "",  named: "register",    kind: "text", required: "false", fills: "provides"
       member keyword: "provides",        context: "Bluebook", at: "",  named: "link",        kind: "text", required: "false", fills: "provides"
       member keyword: "provides",        context: "Bluebook", at: "",  named: "resolve",     kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "subscribe",   kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "add_name",    kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "confirm",     kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "unsubscribe", kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "initiate",    kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "succeeded",   kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "failed",      kind: "text", required: "false", fills: "provides"
       member keyword: "aggregate",       context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "name"
       member keyword: "read_model", context: "Bluebook", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "policy",          context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "name"

data/lib/hecks/projector/exporter.rb

@@ -174,6 +174,60 @@ module Hecks
         }
       end
 
+      # Same seam as `membership` — which chapter answers the guest
+      # newsletter signup (`Registry#newsletter_provider_for`), with its
+      # declared verbs qualified and the subscribing aggregate named off
+      # `subscribe`. rust/host reads this instead of naming
+      # Newsletter::Subscriber.Subscribe and friends. `{}` when nothing
+      # this domain attaches provides newsletter.
+      # @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
+
+      # Same seam as `newsletter` — which chapter takes payments
+      # (`Registry#payments_provider_for`), with its declared verbs
+      # qualified and the paying aggregate named off `initiate`. rust/host
+      # reads this instead of naming Payments::Payment.Initiate and the
+      # PaymentGateway operations. `{}` when nothing this domain attaches
+      # provides payments.
+      # @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
+
       # Translation IR, always as an array, with each aggregate's
       # precompiled SQL attached (`compiled_translation_aggregate`) —
       # this is the export a consumer embeds (`ir.json`'s `translations`

data/lib/hecks/runtime/registry/verification.rb

@@ -24,6 +24,7 @@ module Hecks
           verify_singleton_port_answers!
           refuse_cross_package_bluebook_merge!
           refuse_membership_without_identity!
+          refuse_unresolved_port_operations!
 
           @hecksagons.each_value do |hexagon|
             refuse_ungoverned_roles!(hexagon)
@@ -330,6 +331,37 @@ module Hecks
                 "identity verbs are exported onto ir.json, not guessed at deploy."
         end
 
+        # A `provides` row whose contract kind is `:port_operation` names an
+        # operation the chapter's hecksagon declares, and the hecksagon
+        # attaches after the chapter is built, so this is the first point the
+        # operation can be checked. Without it, a host reading the declared
+        # verb would dispatch to an operation nothing declares.
+        def refuse_unresolved_port_operations!
+          @bluebooks.each_value do |chapter|
+            chapter.provides.each do |row|
+              next unless Bluebook::Capabilities::CONTRACTS.dig(row.capability, row.key.to_sym) == :port_operation
+              next if port_operation_declared?(chapter, row.verb)
+
+              raise WiringError,
+                    "#{chapter.name} provides #{row.capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                    "but its hecksagon declares no such port operation — declare it with " \
+                    "`#{chapter.name}::Aggregate.port \"Port\" do operation \"Operation\" ... end`."
+            end
+          end
+        end
+
+        # Says whether a chapter declares the port operation an
+        # `"Aggregate.Port.Operation"` verb names.
+        #
+        # @param chapter [Bluebook::Chapter] the chapter whose aggregates' ports are searched
+        # @param verb [String] the verb, spelled `"Aggregate.Port.Operation"`
+        # @return [Boolean] whether that aggregate has that port with that operation
+        def port_operation_declared?(chapter, verb)
+          aggregate_name, port_name, operation_name = verb.split(".", 3)
+          ports = chapter.aggregate(aggregate_name)&.ports || []
+          ports.any? { |port| port.name == port_name && port.operations.any? { |op| op.hecks_name == operation_name } }
+        end
+
         def refuse_bounded_without_acl!(hexagon)
           return unless hexagon.bounded?
           return if hexagon.translates.any?

data/lib/hecks/runtime/registry.rb

@@ -375,20 +375,59 @@ module Hecks
       # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s membership
       #   questions, or nil if none does
       def membership_provider_for(domain)
+        vendored_provider_for(domain, Bluebook::Capabilities::MEMBERSHIP)
+      end
+
+      # The chapter that answers the guest newsletter signup for `domain` —
+      # the domain's own chapter, a framework member, or a vendored
+      # embryonaut bluebook it attaches, that declares `provides
+      # "newsletter"`. Nil when none does. Newsletter is recognised by
+      # what it declares (Subscribe/AddName/Confirm/Unsubscribe), so a
+      # chapter that declares the same thing is recognised the same way.
+      #
+      # @param domain [String, Symbol] the domain whose newsletter chapter is being resolved
+      # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s newsletter
+      #   signup, or nil if none does
+      def newsletter_provider_for(domain)
+        vendored_provider_for(domain, Bluebook::Capabilities::NEWSLETTER)
+      end
+
+      # The chapter that takes payments for `domain` — the domain's own
+      # chapter, a framework member, or a vendored embryonaut bluebook it
+      # attaches, that declares `provides "payments"`. Nil when none does.
+      # Payments is recognised by what it declares (Initiate and the
+      # processor's two verdicts), so a chapter that declares the same
+      # thing is recognised the same way.
+      #
+      # @param domain [String, Symbol] the domain whose payments chapter is being resolved
+      # @return [Bluebook::Chapter, nil] the chapter that takes `domain`'s payments, or nil
+      #   if none does
+      def payments_provider_for(domain)
+        vendored_provider_for(domain, Bluebook::Capabilities::PAYMENTS)
+      end
+
+      # The chapter that provides `capability` for `domain`: the domain's
+      # own chapter, any framework member its hecksagon attaches, or any
+      # vendored embryonaut bluebook it attaches, that declares it. Falls
+      # back to any loaded chapter that does, because a consuming domain
+      # often wires a vendored chapter as its own `Hecks.hecksagon "Name"`
+      # (so that chapter can attach Governance on that named hexagon)
+      # rather than via `uses_embryonaut_bluebook` on itself — the chapter
+      # is loaded, it just isn't listed on the consumer's own hexagon.
+      #
+      # @param domain [String, Symbol] the domain the provider is resolved for
+      # @param capability [String] the capability's name, such as
+      #   `Bluebook::Capabilities::MEMBERSHIP`
+      # @return [Bluebook::Chapter, nil] the providing chapter, or nil if none loaded does
+      def vendored_provider_for(domain, capability)
         hexagon = hecksagon(domain)
         vendored = Array(hexagon&.vendored_bluebooks).map { |name| Naming.pascal(name) }
         names = [domain.to_s, *Array(hexagon&.framework_members), *vendored]
         attached = names.filter_map { |name| bluebook(name) }
-                        .find { |chapter| chapter.provides?(Bluebook::Capabilities::MEMBERSHIP) }
+                        .find { |chapter| chapter.provides?(capability) }
         return attached if attached
 
-        # Sibling hecksagons — Lifeadelics vendors Membership as
-        # `Hecks.hecksagon "Membership"` (so Person::Admit can attach
-        # Governance on that named hexagon), not via uses_embryonaut_bluebook
-        # on the consuming domain. The chapter is loaded; it just isn't
-        # listed on Lifeadelics' own hexagon. Any loaded chapter that
-        # provides membership is the bounded-context answer.
-        @bluebooks.values.find { |chapter| chapter.provides?(Bluebook::Capabilities::MEMBERSHIP) }
+        @bluebooks.values.find { |chapter| chapter.provides?(capability) }
       end
 
       # Resolves and memoizes `aggregate`'s authoritative repository.

data/lib/hecks/version.rb

@@ -12,5 +12,5 @@ module Hecks
   # it there, or even in the consuming Gemfile, never closed the gap,
   # because gemspec evaluation happens before anything Bundler
   # resolves is actually loadable yet.
-  VERSION = "2.0.0".freeze
+  VERSION = "2.2.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Chris Young
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-24 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism