hecks 1.5.1 → 2.1.0

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

@@ -17,15 +17,20 @@ module Hecks
         # @raise [Runtime::WiringError] if a bind names an undeclared aggregate, an
         #   adapter cannot satisfy its port's verb or declared `answers`, a world
         #   setting names a field its adapter does not declare, the default adapter
-        #   is unusable, or a command declares a role with no authorization provider
-        #   attached
+        #   is unusable, a command declares a role with no authorization provider
+        #   attached, or a membership chapter is loaded with no identity chapter
         def verify!
           verify_default_adapter!
           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)
+            refuse_unwired_framework_members!(hexagon)
+            refuse_unwired_vendored_bluebooks!(hexagon)
+            refuse_bounded_without_acl!(hexagon)
 
             hexagon.binds.each do |bind|
               # A domain-level default (§0) — `persisted_by "Heki"` bare,
@@ -261,6 +266,115 @@ module Hecks
                 "without that it is silent decoration, the exact defect this refusal exists to catch"
         end
 
+        # A vendored embryonaut bluebook is a bounded context, not a pile of
+        # types the consumer inlines. `uses_embryonaut_bluebook` only loads
+        # the package's `.bluebook` files — persistence, Governance, and the
+        # anti-corruption layer (`translates` field mapping) live on a named
+        # sibling hecksagon the CONSUMER must declare. Without that hexagon
+        # the package has no wiring of its own, and cross-context field
+        # mapping has nowhere to be written. Breaking in 2.0: attaching a
+        # vendored chapter without `Hecks.hecksagon "PackageName"` refuses
+        # at boot rather than silently sharing the consumer's hexagon.
+        def refuse_unwired_vendored_bluebooks!(hexagon)
+          Array(hexagon.vendored_bluebooks).each do |package|
+            chapter_name = Naming.pascal(package)
+            next if hecksagon(chapter_name)
+
+            raise WiringError,
+                  "#{hexagon.domain} attaches vendored bluebook #{package.inspect} " \
+                  "(bounded context #{chapter_name}) but never declared " \
+                  "Hecks.hecksagon #{chapter_name.inspect} — put that sibling " \
+                  "(and any `translates` ACL) in context_map.hecksagon; " \
+                  "same-name blocks merge, order-independent."
+          end
+        end
+
+        # Same gate as vendored packages: `uses_framework` loads a bounded
+        # context, and the consumer must declare the sibling hecksagon that
+        # is its ACL. Governance/Identity/Privacy already follow this in
+        # every real consumer; boot now refuses a silent miss.
+        def refuse_unwired_framework_members!(hexagon)
+          Array(hexagon.framework_members).each do |member|
+            next if hecksagon(member)
+
+            raise WiringError,
+                  "#{hexagon.domain} attaches framework member #{member.inspect} " \
+                  "(bounded context) but never declared Hecks.hecksagon " \
+                  "#{member.inspect} — put that sibling (and any `translates` " \
+                  "ACL) in context_map.hecksagon; same-name blocks merge, " \
+                  "order-independent."
+          end
+        end
+
+        # An explicit `bounded` mark on a consumer chapter always needs an
+        # ACL — at least one `translates` block. Any field can be mapped;
+        # the BC does not list which. `uses_framework` / `uses_embryonaut_bluebook`
+        # mark the ATTACHED chapter bounded (module wrap, no Object shortcut)
+        # and require the sibling hecksagon above; they do not require a
+        # `translates` on that sibling unless the consumer also wrote `bounded`.
+        # rust/host Google sign-in reads `ir.json`'s `membership` and
+        # `identity` keys (Exporter.membership / Exporter.identity) —
+        # never a deploy-time env var. Membership without Identity is
+        # the exact gap that produced a live `google_unlinked` after a
+        # successful Google handshake: provision cannot Register/Link.
+        # Refuse at Ruby boot (and project_rust, which exports the same
+        # pair) so a missing sibling cannot ship.
+        def refuse_membership_without_identity!
+          return unless @bluebooks.values.any? { |chapter| chapter.provides?(Bluebook::Capabilities::MEMBERSHIP) }
+          return if @bluebooks.values.any? { |chapter| chapter.provides?(Bluebook::Capabilities::IDENTITY) }
+
+          raise WiringError,
+                "a chapter that provides \"membership\" is loaded, but none provides " \
+                "\"identity\" — rust/host Google sign-in cannot register or link an " \
+                "identity from the hecksagon/world. Attach Identity (`uses_framework " \
+                "\"Identity\"` plus a sibling Hecks.hecksagon \"Identity\") so the " \
+                "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?
+
+          raise WiringError,
+                "#{hexagon.domain} is marked bounded but never declared a " \
+                "translates ACL — a bounded chapter wraps in its own module and " \
+                "cross-context field mapping lives on the hecksagon, not in " \
+                "rust/host and not as a field list on the bluebook. " \
+                "Add `translates \"Name\" do on Foreign::Event; trigger Local::Command, " \
+                "with: { ... } end` (any field) or drop `bounded`."
+        end
+
         # The suggestion, derived from whichever framework members actually
         # declare `provides "authorization"` — never a hardcoded name.
         def authorization_attachment_hint

data/lib/hecks/runtime/registry.rb

@@ -1,6 +1,7 @@
 require_relative "registry/verification"
 require_relative "registry/saga_persistence"
 require_relative "outbox"
+require_relative "../naming"
 
 module Hecks
   module Runtime
@@ -27,6 +28,7 @@ module Hecks
         @bluebooks    = {}
         @bluebook_sources = {}
         @hecksagons = {}
+        @bounded_chapters = {}
         @ports = {}
         @adapters     = {}
         @worlds       = {}
@@ -186,8 +188,29 @@ module Hecks
       def add_hecksagon(item)
         existing = @hecksagons[item.domain]
         @hecksagons[item.domain] = existing ? merge_hecksagons(existing, item) : item
+        mark_bounded(item.domain) if item.bounded?
       end
 
+      # Marks `name` as a bounded context — called automatically by
+      # `uses_framework` / `uses_embryonaut_bluebook`, and by
+      # `add_hecksagon` when the block itself declared `bounded`.
+      # A bounded chapter wraps in its own module (no Object shortcut)
+      # and must have a `translates` ACL or boot refuses.
+      #
+      # @param name [String, Symbol] the chapter name to mark bounded
+      # @return [void]
+      def mark_bounded(name)
+        @bounded_chapters[name.to_s] = true
+      end
+
+      # Says whether `name` is a bounded context — attached via
+      # `uses_framework` / `uses_embryonaut_bluebook`, or a consumer
+      # chapter that declared `bounded` on its own hecksagon.
+      #
+      # @param name [String, Symbol] the chapter name to check
+      # @return [Boolean] whether that chapter is bounded
+      def bounded?(name) = @bounded_chapters[name.to_s] ? true : false
+
       # Registers a loaded port, keyed by its own declared name.
       #
       # @param item [Bluebook::Port, Bluebook::DomainPort] the loaded port
@@ -308,6 +331,91 @@ module Hecks
         @bluebooks.values.select { |chapter| chapter.provides?(Bluebook::Capabilities::AUTHORIZATION) }
       end
 
+      # The chapter that answers "who is this authenticated pair" for
+      # `domain` — the domain's own chapter, or any framework member its
+      # hecksagon attaches, that declares `provides "identity"`. Nil when
+      # none does. Replaces every check for the literal name "Identity":
+      # Identity is recognised by what it declares (Register/Link/ResolvedBy),
+      # and a chapter that declares the same thing is recognised the same way.
+      #
+      # @param domain [String, Symbol] the domain whose identity chapter is being resolved
+      # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s identity
+      #   questions, or nil if none does
+      def identity_provider_for(domain)
+        names = [domain.to_s, *Array(hecksagon(domain)&.framework_members)]
+        attached = names.filter_map { |name| bluebook(name) }
+                        .find { |chapter| chapter.provides?(Bluebook::Capabilities::IDENTITY) }
+        return attached if attached
+
+        # Sibling hecksagons — a consuming domain often wires Identity as
+        # `Hecks.hecksagon "Identity"` (so Register can attach Governance
+        # on that named hexagon), not only via uses_framework on the
+        # consuming domain. The chapter is loaded; it just isn't listed
+        # on the consumer's own hexagon.
+        @bluebooks.values.find { |chapter| chapter.provides?(Bluebook::Capabilities::IDENTITY) }
+      end
+
+      # The chapter that answers "who may sign in" for `domain` — the
+      # domain's own chapter, any framework member its hecksagon attaches,
+      # or any vendored embryonaut bluebook it attaches, that declares
+      # `provides "membership"`. Nil when none does. Replaces rust/host's
+      # own HECKS_MEMBERSHIP_AGGREGATE env var: Membership is recognised
+      # by what it declares (Person.Admit/GrantAccess/All), and a chapter
+      # that declares the same thing (Embryonaut::Member, say) is
+      # recognised the same way.
+      #
+      # Vendored packages are included here and not in
+      # `authorization_provider_for` because membership is a vendored
+      # embryonaut_bluebooks chapter (`uses_embryonaut_bluebook
+      # "membership"`), not a framework member shipped inside hecks.
+      # `Naming.pascal` is the same directory-to-chapter convention
+      # `EmbryonautBluebook.load!` already uses.
+      #
+      # @param domain [String, Symbol] the domain whose sign-in aggregate is being resolved
+      # @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 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?(capability) }
+        return attached if attached
+
+        @bluebooks.values.find { |chapter| chapter.provides?(capability) }
+      end
+
       # Resolves and memoizes `aggregate`'s authoritative repository.
       #
       # @param domain [String, Symbol] name of the domain `aggregate` belongs to
@@ -437,12 +545,20 @@ module Hecks
       # @return [Bluebook::Hecksagon] a new wiring with every list-shaped fact
       #   concatenated, `base` then `overlay`
       def merge_hecksagons(base, overlay)
+        # Same-name blocks concatenate regardless of which file they came
+        # from (`lifeadelics.hecksagon`, `context_map.hecksagon`, an
+        # environment overlay). Order-independent: list facts uniq, so
+        # loading context_map before or after the domain file is the same
+        # merged hecksagon. Binds stay concatenated (BindingPolicy still
+        # refuses a genuine double-bind).
         Bluebook::Hecksagon.new(
           domain:             base.domain,
           binds:              base.binds + overlay.binds,
-          subscriptions:      base.subscriptions + overlay.subscriptions,
-          framework_members:  base.framework_members + overlay.framework_members,
-          vendored_bluebooks: base.vendored_bluebooks + overlay.vendored_bluebooks
+          subscriptions:      (base.subscriptions + overlay.subscriptions).uniq,
+          framework_members:  (base.framework_members + overlay.framework_members).uniq,
+          vendored_bluebooks: (base.vendored_bluebooks + overlay.vendored_bluebooks).uniq,
+          bounded:            base.bounded? || overlay.bounded?,
+          translates:         (base.translates + overlay.translates).uniq
         )
       end
 

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 = "1.5.1".freeze
+  VERSION = "2.1.0".freeze
 end

metadata

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