hecks 1.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 830e92d9660dc86cc7de1af49d85fd7ce5ab611e07341dd11f4633274b920fda
-  data.tar.gz: 1c70b3c2994fd520a604ebd8c8cc8a53e7531e3cb5ba1dd59c6fd751b9b9dd99
+  metadata.gz: 8261eb6f8b8b490fda7cc10deed5d1668e677031b03d67c89ca2c706cb90140a
+  data.tar.gz: 005ef58bad7618ab6085b22c9483465d2b58af9a9c61db7a365e70db81f4a5d6
 SHA512:
-  metadata.gz: 3aeb0240903bed58fbd5684c23ee2069e9b3021aef07082d11e26ffa5052cebccf42d78e3aff243ba192183460056113e0510c7667306d1ed2cde3048ad118c0
-  data.tar.gz: e104c2252f0dbbb1ba5ea97a0f6f56f890cab76e12ff86f246605003738228b94062e317f16db1ebfb376753536d8309cedff86e00275781497232de67b17e1e
+  metadata.gz: 926f57e7d5a1af30ec918269460bc04a20c25dd1feaaf8da910fe0a0ea241f7b4622feec775dfa8390bba16253b6d4b18130b0ea5a0e544259cae70cbd961cbe
+  data.tar.gz: aca0677bd624c1a61d9f6d3dbe6f0e74991d690557d4abed0abf4a3e4a240931434a375b633ba7f424f04c3c36a2454811608ca2894a99d12cbdc2460876ca1b

data/lib/hecks/adapters/driven/identity_registry.rb

@@ -24,8 +24,14 @@ module Hecks
       # @param subject [String] the OIDC subject the issuer vouches for, compared as a String
       # @return [String, nil] the linked identity's id, or nil if nothing has linked this pair
       def resolve(registry, issuer:, subject:)
+        # The resolve verb this registry's declared identity provider names
+        # (`provides "identity", resolve:`), never a hard-coded chapter —
+        # same declared-not-named shape GovernanceAuthorization already holds.
+        provider = registry.bluebooks.values.find { |chapter| chapter.provides?(::Hecks::Bluebook::Capabilities::IDENTITY) }
+        verb = provider&.provided_verb(::Hecks::Bluebook::Capabilities::IDENTITY, :resolve) ||
+               "Identity::ExternalIdentifier.ResolvedBy"
         rows = Runtime::Dispatcher.new(registry).query(
-          "Identity::ExternalIdentifier.ResolvedBy",
+          verb,
           issuer: { value: issuer.to_s }, subject: { value: subject.to_s }
         )
 

data/lib/hecks/bluebook/capabilities.rb

@@ -11,6 +11,17 @@ module Hecks
     #   key => :command | :query   the kind of verb that key must name
     module Capabilities
       AUTHORIZATION = "authorization".freeze
+      # Who may sign in, and with what role — rust/host's Google-OAuth
+      # provision/member_rows resolve this instead of an env var naming
+      # the aggregate (HECKS_MEMBERSHIP_AGGREGATE). Same declared-
+      # not-named shape AUTHORIZATION already is for Governance.
+      MEMBERSHIP = "membership".freeze
+      # A stable organizational identity, independent of how it was
+      # authenticated — recognised by declaration, not the literal name
+      # "Identity". Same declared-not-named shape AUTHORIZATION already
+      # is. rust/host does not build this chapter's payloads; any field
+      # mapping lives on the consuming hecksagon's `translates` ACL.
+      IDENTITY = "identity".freeze
 
       CONTRACTS = {
         AUTHORIZATION => {
@@ -20,6 +31,22 @@ module Hecks
           grant:       :command,
           # every grant of one role acting as another
           transitions: :query
+        }.freeze,
+        MEMBERSHIP    => {
+          # recognize a person who may eventually sign in
+          admit:  :command,
+          # grant an admitted person a role (the access-grant half)
+          grant:  :command,
+          # every admitted person, for the admin listing
+          people: :query
+        }.freeze,
+        IDENTITY      => {
+          # mint a stable identity, independent of how it authenticated
+          register: :command,
+          # associate an (issuer, subject) pair with that identity
+          link:     :command,
+          # look up the identity an authenticated pair resolves to
+          resolve:  :query
         }.freeze
       }.freeze
     end

data/lib/hecks/bluebook/dsl/hecksagon_builder.rb

@@ -27,6 +27,20 @@ module Hecks
           @subscriptions      = []
           @framework_members  = []
           @vendored_bluebooks = []
+          @bounded            = false
+          @translates         = []
+        end
+
+        # Marks THIS chapter as a bounded context — a consumer-owned chapter
+        # that `uses_framework` / `uses_embryonaut_bluebook` will not load.
+        # Framework and vendored packages get the mark automatically from
+        # those words; they never write `bounded` in their own bluebooks.
+        # A bounded chapter wraps in its own module (no Object shortcut)
+        # and must declare at least one `translates` ACL or boot refuses.
+        #
+        # @return [Boolean] true
+        def bounded
+          @bounded = true
         end
 
         # Subscribes this hecksagon to an event it takes from outside the domain's own bluebook.
@@ -54,6 +68,11 @@ module Hecks
         def uses_framework(name)
           @framework_members << name.to_s
           Hecks::Framework.load!(name)
+          # Automatic bounded mark — the framework member is a bounded
+          # context; the consumer's sibling `Hecks.hecksagon "Name"` is
+          # the anti-corruption layer. Not written in the framework
+          # bluebook itself.
+          Hecks.current_registry&.mark_bounded(name.to_s)
         end
 
         # Attaches a vendored embryonaut bluebook to this domain and loads its files into the
@@ -83,6 +102,10 @@ module Hecks
         def uses_embryonaut_bluebook(name)
           @vendored_bluebooks << name.to_s
           Hecks::EmbryonautBluebook.load!(name)
+          # Automatic bounded mark — same as `uses_framework`. The
+          # package's directory name Pascal-cases to the chapter
+          # (`"membership"` → `Membership`).
+          Hecks.current_registry&.mark_bounded(Hecks::Naming.pascal(name.to_s))
         end
 
         # Declares a port at the hecksagon's root and attaches it to the registered bluebook.
@@ -173,6 +196,7 @@ module Hecks
           resolver = ->(const) { ConstShim::ScopedConstant.for(const) }
           built = ConstShim.with(resolver) { PolicyBuilder.build(name, &block) }
 
+          @translates << name.to_s
           bluebook_ir.add_policy(built)
         end
 
@@ -197,7 +221,8 @@ module Hecks
         #   with any other block declared for the same domain
         def build
           Hecksagon.new(domain: @domain, binds: @binds, subscriptions: @subscriptions,
-                        framework_members: @framework_members, vendored_bluebooks: @vendored_bluebooks)
+                        framework_members: @framework_members, vendored_bluebooks: @vendored_bluebooks,
+                        bounded: @bounded, translates: @translates)
         end
 
         # Records any verb the grammar does not own as a domain-wide bind to the named adapter.

data/lib/hecks/bluebook/hexagon.rb

@@ -51,10 +51,13 @@ module Hecks
         binds:              many(:binds),
         subscriptions:      -> { subscriptions.map(&:to_s) },
         framework_members:  -> { framework_members.map(&:to_s) },
-        vendored_bluebooks: -> { vendored_bluebooks.map(&:to_s) }
+        vendored_bluebooks: -> { vendored_bluebooks.map(&:to_s) },
+        bounded:            :bounded,
+        translates:         -> { translates.map(&:to_s) }
       )
 
-      attr_reader :domain, :binds, :subscriptions, :framework_members, :vendored_bluebooks
+      attr_reader :domain, :binds, :subscriptions, :framework_members, :vendored_bluebooks,
+                  :translates
 
       # @param domain [String, Symbol] the domain this hecksagon wires
       # @param binds [Array<Bluebook::Bind>] the declared adapter binds
@@ -64,13 +67,25 @@ module Hecks
       #   (`Governance`, `Identity`, ...) this domain attaches
       # @param vendored_bluebooks [Array<String, Symbol>] the vendored embryonaut
       #   bluebook package names this domain attaches
-      def initialize(domain:, binds: [], subscriptions: [], framework_members: [], vendored_bluebooks: [])
+      # @param bounded [Boolean] whether this chapter is an explicit bounded context
+      #   (consumer-owned; `uses_framework` / `uses_embryonaut_bluebook` mark
+      #   attached chapters bounded on the registry instead)
+      # @param translates [Array<String>] names of `translates` ACL blocks declared here
+      def initialize(domain:, binds: [], subscriptions: [], framework_members: [],
+                     vendored_bluebooks: [], bounded: false, translates: [])
         @domain             = domain.to_s
         @binds              = binds
         @subscriptions      = subscriptions
         @framework_members  = framework_members
         @vendored_bluebooks = vendored_bluebooks
+        @bounded            = bounded ? true : false
+        @translates         = Array(translates).map(&:to_s)
       end
+
+      # Says whether this hecksagon marked its own chapter `bounded`.
+      #
+      # @return [Boolean] whether `bounded` was declared on this block
+      def bounded? = @bounded
     end
 
     # The built form of a `.world` file, produced by `DSL::WorldBuilder` —

data/lib/hecks/corpus.rb

@@ -265,20 +265,115 @@ module Hecks
     Elsewhere = Struct.new(:check, :destination, :names, :why)
 
     RUST_ELSEWHERE = {
-      "meta"       => Elsewhere.new(:named_in, "spec/codegen_parity_spec.rb", "bluebook_language",
-                                    "the self-hosted grammar (lib/hecks/language), not a domain directory — every " \
-                                    "bin/project_rust run rewrites it (so the drift check diffs it), codegen parity " \
-                                    "checks it as bluebook_language, and there is no directory to fuzz"),
-      "embryonaut" => Elsewhere.new(:external, "~/Projects/embryonautfoundersapp", "embryonaut",
-                                    "an external product's domain — its bluebook, regeneration and parity are owed " \
-                                    "by its own repo; here bin/rust_coverage checks only the committed snapshot")
+      "meta"        => Elsewhere.new(:named_in, "spec/codegen_parity_spec.rb", "bluebook_language",
+                                     "the self-hosted grammar (lib/hecks/language), not a domain directory — every " \
+                                     "bin/project_rust run rewrites it (so the drift check diffs it), codegen parity " \
+                                     "checks it as bluebook_language, and there is no directory to fuzz"),
+      "embryonaut"  => Elsewhere.new(:external, "~/Projects/embryonautfoundersapp", "embryonaut",
+                                     "an external product's domain — its bluebook, regeneration and parity are owed " \
+                                     "by its own repo; here bin/rust_coverage checks only the committed snapshot"),
+      # Lifeadelics — same external-product shape as "embryonaut" above,
+      # first generated 2026-09-19 fixing a live era-shape-drift outage.
+      # Its directory used to be named "domain" (a generic, collision-
+      # prone Cargo feature/module name — the chapter name is, and
+      # always was, "Lifeadelics"), so the generated module and Cargo
+      # feature were "domain" too, read off `metadata.rs`'s own stamp
+      # the same way `generated_source` reads any other module's. Fixed
+      # 2026-09-20 by renaming the directory itself
+      # (~/Projects/lifeadelics/domain -> ~/Projects/lifeadelics/
+      # lifeadelics) — the generated module and Cargo feature are
+      # "lifeadelics" now, matching every other domain's own convention.
+      #
+      # Lifeadelics also attaches `accounts`/`newsletter`/`payments`
+      # (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,
+      # generated into Rust for the first time by any domain here).
+      # `rust_side_chapters` only ever looks for the attaching domain
+      # among `rust_domains` — an in-repo directory — so it can attribute
+      # neither module to lifeadelics on its own; `rust_attachment_
+      # hecksagon_text`, below, reads every `:external` domain's own
+      # hecksagon files too, the same way it reads an in-repo domain's,
+      # so `Privacy`'s own bucket membership (already correct — it is a
+      # real in-repo framework member with no merged.rs) can still be
+      # proven attached.
+      "lifeadelics" => Elsewhere.new(:external, "~/Projects/lifeadelics", "lifeadelics",
+                                     "an external product's domain — its bluebook, regeneration and parity are owed " \
+                                     "by its own repo; here bin/rust_coverage checks only the committed snapshot")
     }.freeze
 
+    # Vendored embryonaut_bluebooks packages attached only by an external
+    # RUST_ELSEWHERE domain — `members(:vendored)` can't find them
+    # itself; that glob only reaches `examples/*/vendor/
+    # embryonaut_bluebooks/*`, never an external checkout. Declared once,
+    # by hand, the same manual-commit contract "embryonaut" itself
+    # already carries: stem => the RUST_ELSEWHERE feature that attaches
+    # it. spec/corpus_rust_spec.rb checks each is really attached, the
+    # 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"
+    }.freeze
+
+    # Every external vendored chapter's own stem.
+    #
+    # @return [Array<String>] stems declared in RUST_EXTERNAL_VENDORED_CHAPTERS
+    def rust_external_vendored_chapters
+      RUST_EXTERNAL_VENDORED_CHAPTERS.keys
+    end
+
+    # Where an external vendored chapter's own bluebook lives — somewhere
+    # under `<destination>/**/vendor/embryonaut_bluebooks/<stem>`, the
+    # same layout `EmbryonautBluebook.load!` resolves for an in-repo
+    # vendored member, one level further out. Globbed rather than joined
+    # directly: `RUST_ELSEWHERE`'s own `destination` names the external
+    # product's checkout root, not necessarily the exact directory its
+    # own bluebook lives under (confirmed live against lifeadelics's own
+    # checkout: `~/Projects/lifeadelics/lifeadelics/vendor/
+    # embryonaut_bluebooks/accounts/bluebook`, one level below
+    # `~/Projects/lifeadelics` itself).
+    #
+    # @param stem [String] an external vendored chapter's stem
+    # @return [String, nil] the vendored member's own directory, or nil when none is found
+    def rust_external_vendored_domain_dir(stem)
+      feature = RUST_EXTERNAL_VENDORED_CHAPTERS.fetch(stem)
+      destination = File.expand_path(RUST_ELSEWHERE.fetch(feature).destination)
+      Dir.glob(File.join(destination, "**", "vendor", "embryonaut_bluebooks", stem)).first
+    end
+
+    # Every place a Rust-facing domain's own `uses_framework`/
+    # `uses_embryonaut_bluebook` attachment could be declared — every
+    # in-repo Rust domain's own hecksagon files, plus each `:external`
+    # RUST_ELSEWHERE domain's own (its `destination`, expanded, is a
+    # real checkout on this machine, read the same way an in-repo
+    # domain's own hecksagon files already are).
+    #
+    # @param root [String] repository root to search under
+    # @return [String] every reachable hecksagon file's own text, joined by newlines
+    def rust_attachment_hecksagon_text(root: ROOT)
+      in_repo = rust_domains(root: root).flat_map { |domain| Dir.glob(File.join(domain.dir, "**", "*.hecksagon")) }
+      external = RUST_ELSEWHERE.values.select { |route| route.check == :external }
+                               .flat_map { |route| Dir.glob(File.join(File.expand_path(route.destination), "**", "*.hecksagon")) }
+      (in_repo + external).map { |path| File.read(path) }.join("\n")
+    end
+
     # **Shrink-only**. A generated module `bin/rust_coverage` still reports a
     # gap for. `bin/corpus --rust-coverage` requires each of these to
     # still fail, so an entry that starts passing breaks the build until
     # it is deleted here.
-    RUST_COVERAGE_PENDING = {}.freeze
+    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"
+    }.freeze
 
     # The Cargo `[features]` table's raw text.
     #
@@ -396,7 +491,26 @@ module Hecks
     def rust_side_chapters(kind, root: ROOT)
       modules = generated_modules(root: root)
       members(kind, root: root).map(&:stem)
-                               .select { |stem| modules.include?(stem) && !generated?(stem, root: root) }
+                               .select do |stem|
+                                 module_name = Naming.pascal(stem).downcase
+                                 modules.include?(module_name) && !generated?(module_name, root: root)
+                               end
+    end
+
+    # The generated module name a `:framework`/`:vendored` stem writes
+    # under — `Naming.pascal(stem).downcase` (`bin/project_rust`'s own
+    # convention, see `rust_side_chapters`'s header); a chapter whose
+    # stem holds an underscore ("console_settings") writes to a
+    # different, underscore-free module name ("consolesettings"), so a
+    # bucket-membership check against `generated_modules` (a directory
+    # name) needs this mapping rather than the raw stem
+    # `rust_framework_chapters`/`rust_vendored_chapters` still return
+    # (every other caller wants the stem, to build a bluebook file path).
+    #
+    # @param stem [String] a `:framework`/`:vendored` corpus member's stem
+    # @return [String] the generated module's own directory name
+    def rust_side_module_name(stem)
+      Naming.pascal(stem).downcase
     end
 
     def rust_framework_chapters(root: ROOT)

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -133,6 +133,111 @@ Hecks.bluebook "Deploy" do
     end
   end
 
+  # A sibling of `LambdaTarget`, not a shared shape with it — value objects
+  # are not shared across aggregates in this DSL (`Tenant`'s own
+  # `DomainName`/`Realm`/`Schema` below already make the same point), so
+  # this aggregate carries its own copies of `DomainName`/`Region`/
+  # `Database`/`Web` rather than reaching into `LambdaTarget`'s.
+  aggregate "FargateTarget" do
+    description "One domain's validated AWS Fargate deploy target — what deployed_to(\"AwsFargate\") must resolve to before bin/project_deploy generates anything from it."
+
+    identified_by :domain
+
+    attribute :domain,   DomainName
+    attribute :region,   Region
+    attribute :cpu,      Cpu
+    attribute :memory,   Memory
+    attribute :database, Database
+    attribute :web,      Web
+    attribute :port,     Port
+
+    value_object "DomainName" do
+      attribute :value, String
+      invariant("a domain is named") { !value.to_s.empty? }
+    end
+
+    value_object "Region" do
+      attribute :value, String
+      invariant("a region is named") { !value.to_s.empty? }
+    end
+
+    # A positive integer, nothing more — AWS's real cpu/memory
+    # combinations (256 cpu units needs 512-2048 MB of `memory`, say)
+    # are a pairing `ECS` itself enforces at deploy time; encoding that
+    # whole table here would duplicate AWS's own rules for no benefit
+    # this generator needs. This only catches a typo (zero, negative)
+    # before a single file is generated, the same floor `Memory`/`Port`
+    # below hold for their own ranges.
+    value_object "Cpu" do
+      attribute :value, Integer
+      invariant("cpu is positive") { value.positive? }
+    end
+
+    # Fargate's own valid range, not Lambda's 128-10240 MB —
+    # `LambdaTarget`'s own `Memory` value object (above) is scoped to
+    # that aggregate alone, so this is a distinct value object under the
+    # same name rather than a shared one. A plain sanity floor and
+    # ceiling, not AWS's own cpu-paired table (see `Cpu`'s own comment).
+    value_object "Memory" do
+      attribute :value, Integer
+      invariant("memory is positive") { value.positive? }
+      invariant("memory is at most 122880 MB") { value <= 122880 }
+    end
+
+    # Same shape and reasoning as `LambdaTarget`'s own `Database` —
+    # "Postgres"/"Aurora" provision this domain's own RDS instance;
+    # "Shared" borrows another already-deployed domain's instance,
+    # isolated by a native Postgres schema. See that value object's own
+    # comment for the full reasoning; it applies unchanged here.
+    value_object "Database" do
+      attribute :value, String, one_of: ["Postgres", "Aurora", "Shared"]
+    end
+
+    # Same shape and reasoning as `LambdaTarget`'s own `Web` — "Rust"
+    # means the domain's own task also serves its public web UI
+    # in-process, over the port this aggregate's own `Port` attribute
+    # declares.
+    value_object "Web" do
+      attribute :value, String, one_of: ["None", "Rust"]
+    end
+
+    # The container port the task listens on and the target group
+    # routes to — a real TCP port, not an arbitrary integer.
+    value_object "Port" do
+      attribute :value, Integer
+      invariant("a port is at least 1") { value >= 1 }
+      invariant("a port is at most 65535") { value <= 65535 }
+    end
+
+    # All seven required, for the identical reason `LambdaTarget.Declare`
+    # requires all of its own attributes — see that command's own
+    # comment on `normalize_args`/`coerce_declared_arguments`. This
+    # validates a fully-resolved target, after `bin/project_deploy`'s own
+    # defaulting (`cpu`/`memory`/`port` each fall back to a Ruby-side
+    # default before this ever dispatches), not instead of it.
+    command "Declare" do
+      goal "Validate one domain's AwsFargate deploy target before anything is generated from it"
+
+      attribute :domain,   DomainName
+      attribute :region,   Region
+      attribute :cpu,      Cpu
+      attribute :memory,   Memory
+      attribute :database, Database
+      attribute :web,      Web
+      attribute :port,     Port
+
+      sets :domain
+      sets :region
+      sets :cpu
+      sets :memory
+      sets :database
+      sets :web
+      sets :port
+
+      emits "FargateTargetDeclared"
+    end
+  end
+
   # `bin/project_tenant`'S OWN VALIDATED SHAPE — same split LambdaTarget
   # draws with `bin/project_deploy`: this aggregate validates, that
   # script GENERATES/ACTS (writes `environments/<slug>.world`, ensures

data/lib/hecks/deploy/oidc.json

@@ -1,6 +1,11 @@
 {
   "audience": "Deploy",
   "scopes": [
+    {
+      "scope": "deploy:fargate_target.declare",
+      "verb": "Deploy::FargateTarget.Declare",
+      "role": null
+    },
     {
       "scope": "deploy:lambda_target.declare",
       "verb": "Deploy::LambdaTarget.Declare",