hecks 1.5.0 → 2.0.0

data/lib/hecks/projector/exporter.rb

@@ -126,6 +126,54 @@ module Hecks
         }
       end
 
+      # Same seam as `authorization` — which chapter answers "who may
+      # sign in" (`Registry#membership_provider_for`), with its declared
+      # verbs qualified and the membership aggregate named off `admit`.
+      # rust/host reads this instead of HECKS_MEMBERSHIP_AGGREGATE.
+      # `{}` when nothing this domain attaches provides membership.
+      # @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
+
+      # Same seam as `authorization` — which chapter answers "who is this
+      # authenticated pair" (`Registry#identity_provider_for`), with its
+      # declared verbs qualified. rust/host reads this instead of naming
+      # Identity::Identity.Register / ExternalIdentifier.Link. `{}` when
+      # nothing this domain attaches provides identity. 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
+
       # 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/projector/target.rb

@@ -80,12 +80,17 @@ module Hecks
       #   chapter must declare; nil means none
       # @param emits [Symbol] the kind of artifact `self` returns: `:artifact` (the default,
       #   a single Hash or String) or `:files` (a path => contents tree)
+      # @param needs_world [Boolean] whether `self` is an export — a target that reads a
+      #   domain's `.world`/`.hecksagon` bindings, not only its declaration. `false` (the
+      #   default) for an ordinary projection; `true` refuses a `Projector.call` made with
+      #   no `world:`.
       # @return [Symbol] the registered key
-      def projects_as(key, requires: nil, declares: nil, emits: :artifact)
-        @projection_emits    = emits
-        @projection_key      = key.to_sym
-        @projection_declares = Array(declares)
-        @projection_requires = Array(requires)
+      def projects_as(key, requires: nil, declares: nil, emits: :artifact, needs_world: false)
+        @projection_emits       = emits
+        @projection_key         = key.to_sym
+        @projection_declares    = Array(declares)
+        @projection_requires    = Array(requires)
+        @projection_needs_world = needs_world
         Projector.register(@projection_key, self)
         @projection_key
       end
@@ -108,6 +113,14 @@ module Hecks
       # @return [Symbol] the kind of artifact `self` returns: `:artifact` or `:files`
       def projection_emits = @projection_emits || :artifact
 
+      # Tells whether this target is an export — one that needs a domain's
+      # `.world`/`.hecksagon` bindings, passed as `Projector.call`'s `world:`,
+      # rather than only its declaration.
+      #
+      # @return [Boolean] the value given to `projects_as`' `needs_world:`, or false
+      #   before `projects_as` is called
+      def projection_needs_world? = @projection_needs_world || false
+
       # Names the capability module(s) a construct must satisfy, defaulting
       # to plain chapter-hood when `projects_as` named none.
       #

data/lib/hecks/projector.rb

@@ -31,11 +31,13 @@ module Hecks
   #
   #   an export takes a declaration and its bindings and answers
   #   something that is the domain, running elsewhere — rust/project.rb's
-  #   generated crate, the WASM artifact, the SAM template
-  #   bin/project_deploy renders. It needs the `.world`/`.hecksagon` a
-  #   projection never looks at, because a running system has to know how
-  #   it is wired. That is the whole reason bin/project_deploy cannot use
-  #   this protocol: `call(bluebook:, options:)` has no channel for it.
+  #   generated crate, the WASM artifact, the CloudFormation template
+  #   `lib/hecks/projections/deploy` renders. It needs the
+  #   `.world`/`.hecksagon` a projection never looks at, because a
+  #   running system has to know how it is wired. A target that needs
+  #   this declares `needs_world: true` (`Target#projects_as`) and reads
+  #   `options.fetch(:world)`; `Projector.call`'s own `world:` keyword is
+  #   what carries it, merged into `options` before the target ever runs.
   #
   #   a state projection takes records — a domain after dispatch — and is
   #   a read-model question wearing the same word.
@@ -88,17 +90,21 @@ module Hecks
     # @param bluebook [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
     #   IR-emitting construct to project
     # @param options [Hash] projector-specific options, passed through unchanged
+    # @param world [Bluebook::World, nil] the domain's `.world`/`.hecksagon` bindings,
+    #   required by an export (`needs_world: true`); nil for an ordinary projection.
+    #   Merged into `options[:world]` before the target runs — the target never
+    #   receives it as a separate argument.
     # @return [Object] whatever the projector's own `call` returns: typically a
     #   `Hash`/`String` artifact, or a `Hash{String => String}` file tree
     # @raise [UnknownProjector] if no projector is registered under `name`
     # @raise [WrongConstruct] if `bluebook` lacks a capability or aggregate the
-    #   projector requires
-    def call(name, bluebook:, options: {})
+    #   projector requires, or if the projector needs `world:` and none is given
+    def call(name, bluebook:, options: {}, world: nil)
       projector = registry.fetch(name.to_sym) do
         raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
       end
-      admits!(name, projector, bluebook)
-      projector.call(bluebook: bluebook, options: options)
+      admits!(name, projector, bluebook, world)
+      projector.call(bluebook: bluebook, options: world ? options.merge(world: world) : options)
     end
 
     # Refuses `construct` if it lacks a capability or declared aggregate
@@ -116,13 +122,17 @@ module Hecks
     # @param name [String, Symbol] the projector's registered key, used in the message
     #   when refusing
     # @param projector [Module, Class, #call] the target being checked; consulted for
-    #   `projection_requires` and `projection_declares` when it answers them
+    #   `projection_requires`, `projection_declares`, and `projection_needs_world?` when
+    #   it answers them
     # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
     #   IR-emitting construct offered to the projector
+    # @param world [Bluebook::World, nil] the `world:` given to `Projector.call`, checked
+    #   against the target's own `needs_world:` declaration
     # @return [void]
-    # @raise [WrongConstruct] if `construct` lacks a required capability, or the
-    #   chapter it is declares no aggregate the projector needs
-    def admits!(name, projector, construct)
+    # @raise [WrongConstruct] if `construct` lacks a required capability, the chapter it
+    #   is declares no aggregate the projector needs, or the projector needs `world:`
+    #   and `world` is nil
+    def admits!(name, projector, construct, world = nil)
       needed = projector.respond_to?(:projection_requires) ? projector.projection_requires : []
       missing = needed.reject { |capability| capable?(construct, capability) }
       unless missing.empty?
@@ -133,11 +143,15 @@ module Hecks
 
       declared = projector.respond_to?(:projection_declares) ? projector.projection_declares : []
       absent   = declared.reject { |named| construct.aggregate(named) }
-      return if absent.empty?
+      unless absent.empty?
+        raise WrongConstruct,
+              "#{name.inspect} needs a chapter declaring #{absent.join(' and ')}; " \
+              "#{construct.name} declares no such aggregate."
+      end
+
+      return unless projector.respond_to?(:projection_needs_world?) && projector.projection_needs_world? && world.nil?
 
-      raise WrongConstruct,
-            "#{name.inspect} needs a chapter declaring #{absent.join(' and ')}; " \
-            "#{construct.name} declares no such aggregate."
+      raise WrongConstruct, "#{name.inspect} needs .world/.hecksagon bindings — pass world: to Projector.call."
     end
 
     # Tells whether `construct` has the capability `admits!` requires of it.

data/lib/hecks/router/namespace_installer.rb

@@ -138,12 +138,22 @@ module Hecks
         current_entries.reject { |entry| entry.fqn.aggregate.nil? }
                        .group_by { |entry| [entry.fqn.aggregate, entry.fqn.verb] }
                        .each do |(aggregate, verb), candidates|
+          # Bounded chapters wrap in their own module (`Domain::Aggregate`)
+          # so two BCs can both declare `Person` without colliding on
+          # Object::Person. Folder-spread files of the SAME chapter still
+          # get the shortcut — they are not BCs.
+          next if bounded_chapter?(candidates)
+
           shortcut_target(aggregate).define_singleton_method(verb) do |**args|
             installer.send(:dispatch_short, candidates, **args)
           end
         end
       end
 
+      def bounded_chapter?(candidates)
+        candidates.any? { |entry| entry.dispatcher.registry.bounded?(entry.fqn.domain) }
+      end
+
       def dispatch_short(candidates, **args)
         if candidates.length > 1
           shown = candidates.map { |entry| entry.fqn.to_s }.sort.join(", ")

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

@@ -17,15 +17,19 @@ 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!
 
           @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 +265,84 @@ 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
+
+        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,66 @@ 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)
+        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) }
+        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) }
+      end
+
       # Resolves and memoizes `aggregate`'s authoritative repository.
       #
       # @param domain [String, Symbol] name of the domain `aggregate` belongs to
@@ -437,12 +520,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.0".freeze
+  VERSION = "2.0.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Chris Young
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-20 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -378,6 +378,9 @@ files:
 - lib/hecks/ports/query/ordering.rb
 - lib/hecks/projections.rb
 - lib/hecks/projections/bootstrap_table.rb
+- lib/hecks/projections/deploy/fargate.rb
+- lib/hecks/projections/deploy/lambda.rb
+- lib/hecks/projections/deploy/shared.rb
 - lib/hecks/projections/diagrams.rb
 - lib/hecks/projections/glossary.rb
 - lib/hecks/projections/glossary/html.rb

data/lib/hecks/framework/bluebook/compliance.bluebook

@@ -1 +0,0 @@
-../../../../examples/compliance/bluebook/compliance.bluebook