hecks 0.2.0 → 1.0.0

data/lib/hecks/codemod.rb

@@ -0,0 +1,342 @@
+require_relative "bluebook/meta_validator"
+
+module Hecks
+  # SHARED MACHINERY for a codemod that migrates real `.bluebook` source
+  # once a DSL builder change makes some previously-required declaration
+  # optional/redundant — pulled out of `bin/codemod_implicit_append_fields`
+  # (the first one built), which needed three real, hard-won fixes before
+  # it could be trusted: a process-lifetime AST cache with no
+  # invalidation, a batch-revert granularity that let one unsafe
+  # candidate sink every other safe one sharing its boot, and (in the
+  # SPINE the codemod migrates FOR, not here) an append-at-end insertion
+  # that only round-tripped correctly for whichever field happened to be
+  # last. None of those are guessable in advance; they only surface by
+  # actually running a real edit against real self-hosted code. This
+  # module is that lesson, kept — the NEXT codemod plugs in two rule-
+  # specific procs (`find_candidates`, `apply_candidate`) and inherits
+  # the boot/safety-net machinery rather than rediscovering it.
+  #
+  # A CODEMOD IS NOT PATTERN-MATCHING ALONE. Deciding "is this line safe
+  # to delete" means knowing what the RUNTIME would resolve it to — so
+  # every codemod built on this module follows the same three steps:
+  #   1. Boot the real domain (or the self-hosted meta-domain) and read
+  #      its IR to find CANDIDATES — provided by the caller's own
+  #      `find_candidates`, since the actual redundancy rule is specific
+  #      to whichever spine change this migration serves.
+  #   2. Locate and remove each candidate's own source text — the
+  #      caller's own `apply_candidate`.
+  #   3. Re-boot from the edited text and diff the full IR export
+  #      against the pre-edit export. Byte-identical -> keep. Anything
+  #      else (including a RAISED exception — the self-hosted
+  #      meta-domain DISPATCHES itself into being, S14, so a bad edit
+  #      can surface as a runtime refusal, not just a differing export)
+  #      -> revert and report SKIPPED, never silently guessed past.
+  #
+  # DESIGN-TIME CHECKLIST for the SPINE change a future codemod migrates
+  # corpus text for — both items below are real bugs THIS module's own
+  # first use found, not hypothetical:
+  #   - Does the resolved value get inserted into an ORDER-SENSITIVE
+  #     list (the exported IR is array-order-sensitive throughout)? If
+  #     so, the spine's own insertion must preserve the ORIGINAL
+  #     position, not just append — an append-at-end insertion only
+  #     round-trips correctly for a value that already happened to be
+  #     last.
+  #   - Does resolution depend on ANOTHER construct already being
+  #     declared (the aggregate/entity a `sets`/`append:` field resolves
+  #     against)? If a creator command can be declared BEFORE the
+  #     construct it creates (real, live: `command "Handler"` before
+  #     `entity "Handler"`, one file down), one-pass resolution
+  #     genuinely cannot see it yet — not a codemod bug, a structural
+  #     limit worth naming rather than working around.
+  module Codemod
+    ROOT = File.expand_path("../..", __dir__)
+
+    EXAMPLE_ROOTS = Dir.glob(File.join(ROOT, "examples", "*")).select { |p| File.directory?(p) }.sort
+    META_FILES    = (Dir.glob(File.join(ROOT, "lib/hecks/grammar/*.bluebook")) +
+                      Dir.glob(File.join(ROOT, "lib/hecks/framework/bluebook/*.bluebook")) +
+                      Dir.glob(File.join(ROOT, "lib/hecks/language/bluebook/**/*.bluebook"))).sort
+
+    # THE SAME LIGHTWEIGHT PATH `spec/spec_helper.rb`'s own
+    # `boot_in_memory` uses — `Hecks.with_registry` satisfies
+    # `Hecks.bluebook`'s own `collect`'s "loaded outside a boot" check
+    # without `Hecks.boot`'s full era-check/adapter-wiring path, which
+    # needs a LIVE Postgres connection for `compliance` and would make
+    # every codemod depend on a database it has no reason to touch — a
+    # codemod only ever reads a chapter's own declared IR, never a
+    # stored record.
+    PERSISTENCE_PORT = File.join(ROOT, "lib/hecks/ports/persistence.port")
+    EXTRACTION_PORT  = File.join(ROOT, "lib/hecks/ports/extraction.port")
+    MEMORY_ADAPTER   = File.join(ROOT, "lib/hecks/adapters/driven/memory.adapter")
+    PRISM_ADAPTER    = File.join(ROOT, "lib/hecks/adapters/driven/prism.adapter")
+
+    def self.export_json(registry) = Hecks::Projector::Exporter.json(registry)
+
+    # `Hecks::Adapters::Prism` caches a file's parsed AST for the
+    # life of the PROCESS, keyed by path — fine for every existing
+    # caller (a file loads once per process: one `bin/ir` run, one
+    # rspec worker), but a codemod legitimately reloads the SAME path
+    # after editing it, and a stale cached tree reports a
+    # `given`/`ensures` block at its OLD line number, which no longer
+    # matches the freshly re-executed file's own `block.source_location`
+    # — surfacing as "did not survive extraction" on a perfectly valid
+    # file. `Prism.forget` is the real invalidation API this module's
+    # own first use motivated (found here, fixed at the source rather
+    # than left as a private `TREES.clear` poke from outside).
+    def self.load_bluebook(path)
+      paths = if path.is_a?(Array)
+                path
+              elsif File.directory?(path)
+                Dir.glob(File.join(path, "*.bluebook"))
+              else
+                [path]
+              end
+      paths.each { |file| Hecks::Adapters::Prism.forget(file) }
+
+      registry = Hecks::Runtime::Registry.new
+      Hecks.with_registry(registry) do
+        Kernel.load(PERSISTENCE_PORT)
+        Kernel.load(EXTRACTION_PORT)
+        Kernel.load(MEMORY_ADAPTER)
+        Kernel.load(PRISM_ADAPTER)
+        Hecks::Bluebook::MetaValidator.defer { paths.each { |file| Kernel.load(file) } }
+        Hecks::Bluebook::MetaValidator.judge_deferred!(registry)
+      end
+      registry
+    end
+
+    # `forget_all`, not a single `forget` — the meta-domain is NINE
+    # files (`MetaValidator::GRAMMAR_FILES`) merged into one registry,
+    # and a caller here (the codemod runner) doesn't generally know in
+    # advance which ONE it just edited.
+    def self.boot_meta
+      Hecks::Adapters::Prism.forget_all
+      Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
+      export_json(Hecks::Bluebook::MetaValidator.grammar_registry)
+    end
+
+    def self.meta_registry
+      Hecks::Adapters::Prism.forget_all
+      Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
+      Hecks::Bluebook::MetaValidator.grammar_registry
+    end
+
+    # Walks every aggregate (and every nested entity, recursively)
+    # across every chapter in a booted registry, yielding [owning
+    # construct, command] pairs — `construct` is whichever
+    # Aggregate/Entity actually OWNS the command, the same distinction
+    # `AggregateBuilder#command` vs `EntityBuilder#command` already
+    # draws. Generic enough for any rule that needs to walk real
+    # commands, not specific to the attribute-redundancy rule.
+    def self.each_command(registry)
+      registry.bluebooks.each_value do |chapter|
+        chapter.aggregates.each do |aggregate|
+          walk = lambda do |construct|
+            construct.commands.each { |command| yield construct, command }
+            construct.entities.each(&walk) if construct.respond_to?(:entities)
+          end
+          walk.call(aggregate)
+        end
+      end
+    end
+
+    def self.owner_attribute(construct, name)
+      construct.attributes.find { |attr| attr.name.to_s == name.to_s }
+    end
+
+    # A LIST attribute's own element construct — the value object or
+    # entity `list_of(...)` names, resolved by `hecks_name` the same way
+    # `AttributeCollector#resolve_identity_field!` already does. Shared
+    # because "what does this list actually hold" is a question any
+    # append-shaped rule needs answered, not just this one.
+    def self.element_construct_for(construct, list_field)
+      list_attr = owner_attribute(construct, list_field)
+      return nil unless list_attr&.list?
+
+      pool = construct.respond_to?(:value_objects) ? construct.value_objects.dup : []
+      pool.concat(construct.entities) if construct.respond_to?(:entities)
+      pool.find { |c| c.hecks_name.to_s == list_attr.type.to_s }
+    end
+
+    # Either a raised exception OR a differing export counts as unsafe
+    # — see the module header on why the meta-domain specifically can
+    # raise. Returns [value_or_nil, error_message_or_nil].
+    def self.safely
+      [yield, nil]
+    rescue StandardError => e
+      [nil, "#{e.class}: #{e.message}"]
+    end
+
+    # THE REUSABLE RUNNER — every real bug fix this module carries lives
+    # here, not in a caller's own script. A caller supplies:
+    #
+    #   find_candidates: ->(registry) { [...] }
+    #     Given a booted registry, return every CANDIDATE this rule
+    #     could migrate. A candidate is whatever shape the caller wants
+    #     — `apply_candidate` is the only other thing that reads it.
+    #
+    #   apply_candidate: ->(text, candidate) { [new_text, changed_bool] }
+    #     Given one file's current text and one candidate, return the
+    #     edited text and whether a match was actually found/removed —
+    #     `false` (text unchanged) when the candidate doesn't apply to
+    #     THIS file, which is how the meta-domain's multi-file search
+    #     below finds the right one without the caller needing to know
+    #     which file a candidate lives in ahead of time.
+    #
+    #   label: ->(candidate) { "..." }
+    #     One-line description for the results report.
+    class Runner
+      def initialize(find_candidates:, apply_candidate:, label:)
+        @find_candidates = find_candidates
+        @apply_candidate = apply_candidate
+        @label = label
+      end
+
+      def run(dry_run: false)
+        results = { applied: [], skipped: [], clean: [] }
+        run_example_domains(results, dry_run)
+        run_meta_domain(results, dry_run)
+        results
+      end
+
+      def report(results, dry_run:)
+        puts "== results (#{dry_run ? 'DRY RUN — nothing written' : 'applied'}) =="
+        puts "clean (no candidates): #{results[:clean].join(', ')}" unless results[:clean].empty?
+        results[:applied].each { |r| puts "APPLIED  #{r[:file]}: #{r[:candidates].join(', ')}" }
+        results[:skipped].each { |r| puts "SKIPPED  #{r[:file]} (#{r[:reason]}): #{Array(r[:candidates]).join(', ')}" }
+      end
+
+      private
+
+      def apply_many(text, candidates)
+        applied = []
+        candidates.each do |c|
+          text, changed = @apply_candidate.call(text, c)
+          applied << c if changed
+        end
+        [text, applied]
+      end
+
+      # The per-candidate write/verify/revert sequence below is one
+      # coherent unit (see the comment ahead of the candidates.each
+      # loop for why it can't batch) — splitting it across methods just
+      # to satisfy the line count would scatter state four ways for no
+      # readability gain.
+      # rubocop:disable-next Metrics/BlockLength
+      def run_example_domains(results, dry_run)
+        Codemod::EXAMPLE_ROOTS.each do |domain_dir|
+          bluebook_files = Dir.glob(File.join(domain_dir, "bluebook", "*.bluebook"))
+          next if bluebook_files.empty?
+
+          before_json = Codemod.export_json(Codemod.load_bluebook(bluebook_files))
+          candidates  = @find_candidates.call(Codemod.load_bluebook(bluebook_files))
+
+          if candidates.empty?
+            results[:clean] << domain_dir
+            next
+          end
+
+          live = bluebook_files.to_h { |file| [file, File.read(file)] }
+          applied_by_file = Hash.new { |hash, file| hash[file] = [] }
+
+          candidates.each do |candidate|
+            target_file = bluebook_files.find { |file| apply_many(live[file], [candidate]).last.any? }
+            unless target_file
+              results[:skipped] << { file: domain_dir, reason: "no matching source line", candidates: [@label.call(candidate)] }
+              next
+            end
+
+            original_text = live[target_file]
+            text, = apply_many(original_text, [candidate])
+            live[target_file] = text
+            File.write(target_file, text)
+            after_json, error = Codemod.safely do
+              Codemod.export_json(Codemod.load_bluebook(bluebook_files))
+            end
+
+            if after_json == before_json && !dry_run
+              applied_by_file[target_file] << candidate
+            elsif after_json == before_json
+              live[target_file] = original_text
+              File.write(target_file, original_text)
+              Codemod.safely { Codemod.load_bluebook(bluebook_files) }
+              applied_by_file[target_file] << candidate
+            else
+              live[target_file] = original_text
+              File.write(target_file, original_text)
+              Codemod.safely { Codemod.load_bluebook(bluebook_files) }
+              reason = error ? "reboot raised after edit (#{error}) — reverted" : "IR changed after edit — reverted"
+              results[:skipped] << { file: target_file, reason: reason, candidates: [@label.call(candidate)] }
+            end
+          end
+
+          applied_by_file.each do |file, applied|
+            results[:applied] << { file: file, candidates: applied.map(&@label) }
+          end
+        end
+      end
+
+      # PER-CANDIDATE, not one batched write-then-verify — the
+      # meta-domain is ONE shared registry (SyntaxBoot DISPATCHES it
+      # into itself, S14), so a single unsafe candidate among many would
+      # otherwise sink every OTHER, genuinely safe candidate in the same
+      # run: this module's first real run found exactly that (25
+      # candidates, one dispatch-time break, all 25 reverted as a batch
+      # before this per-candidate loop existed). `before_meta` stays the
+      # fixed reference throughout — a truly safe candidate never
+      # changes the IR, so the running state's own export should always
+      # still equal the pristine original after each kept edit, by
+      # definition, no moving target needed.
+      def run_meta_domain(results, dry_run)
+        before_meta     = Codemod.boot_meta
+        meta_candidates = @find_candidates.call(Codemod.meta_registry)
+
+        if meta_candidates.empty?
+          results[:clean] << "meta-domain"
+          return
+        end
+
+        live_meta = Codemod::META_FILES.to_h { |f| [f, File.read(f)] }
+        applied_by_file = Hash.new { |h, k| h[k] = [] }
+
+        meta_candidates.each do |candidate|
+          target_file = Codemod::META_FILES.find { |f| apply_many(live_meta[f], [candidate]).last.any? }
+          unless target_file
+            results[:skipped] << { file: "meta-domain", reason: "no matching source line", candidates: [@label.call(candidate)] }
+            next
+          end
+
+          text, = apply_many(live_meta[target_file], [candidate])
+          original_text = live_meta[target_file]
+          live_meta[target_file] = text
+          Codemod::META_FILES.each { |f| File.write(f, live_meta[f]) }
+
+          # DRY RUN STILL VERIFIES — see run_example_domains' own
+          # comment; the edit is always written and rebooted for real,
+          # then always reverted afterward when dry-run (whether or not
+          # it was safe) so the next candidate is judged against the
+          # true original state, never an accumulated hypothetical.
+          after_meta, error = Codemod.safely { Codemod.boot_meta }
+
+          if after_meta == before_meta && !dry_run
+            applied_by_file[target_file] << candidate
+          elsif after_meta == before_meta # dry-run, safe — revert, but count as applied
+            live_meta[target_file] = original_text
+            File.write(target_file, original_text)
+            Codemod.safely { Codemod.boot_meta }
+            applied_by_file[target_file] << candidate
+          else
+            live_meta[target_file] = original_text
+            File.write(target_file, original_text)
+            Codemod.safely { Codemod.boot_meta } # restore cache/memoized state to the reverted text
+            reason = error ? "reboot raised (#{error})" : "IR changed"
+            results[:skipped] << { file: "meta-domain", reason: reason, candidates: [@label.call(candidate)] }
+          end
+        end
+
+        applied_by_file.each do |file, candidates|
+          results[:applied] << { file: file, candidates: candidates.map(&@label) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/construct.rb

@@ -0,0 +1,71 @@
+module Hecks
+  # The invisible field a built construct carries.
+  #
+  # A construct is a RECORD WITH AN OWNER CHAIN — the chapter (Bluebook)
+  # owns its aggregates, an aggregate owns everything declared on it — and the
+  # bluebook identity is carried in its own field, under a `hecks_` prefix that
+  # no domain attribute can collide with. Invisible means exactly that: not an
+  # attribute, not a key in `to_h`, not a reader on instances. Framework
+  # metadata about the construct, not part of the domain it describes.
+  #
+  # The identity is COMPUTED by walking owners rather than stamped, so nothing
+  # has to be re-stamped when a chapter is assembled after its aggregates:
+  #
+  #     Pizzas                     the chapter — no owner
+  #     Pizzas::Pizza              an aggregate joins its chapter with ::
+  #     Pizzas::Pizza.Price        everything else joins its owner with .
+  #
+  # That spelling is not invented here. It is the id `MetaValidator::Judge`
+  # already mints in `#identify`, so a construct and the meta-domain's
+  # record OF that construct carry the same identity, and there is no
+  # translation table between them to be quietly wrong in.
+  #
+  # Usage:
+  #
+  #     price = Class.new(ValueObject)   # a declaration holder
+  #     price.hecks_name  = "Price"
+  #     price.hecks_owner = pizza_ir         # the Aggregate that declares it
+  #     price.hecks_fqn                      # => "Pizzas::Pizza.Price"
+  module Construct
+    # A construct asked for an identity it cannot compute.
+    class Unowned < StandardError; end
+
+    # What declares this one — the chapter above an aggregate, the aggregate
+    # above a value object. nil for a chapter, which is the top.
+    attr_accessor :hecks_owner
+
+    attr_writer :hecks_name
+
+    # A chapter is the only construct that legitimately has no owner. Everything
+    # else is DECLARED IN something, so a missing owner is an unstamped construct
+    # rather than a top — see hecks_fqn.
+    attr_writer :hecks_root
+
+    def hecks_root? = @hecks_root ? true : false
+
+    # The name as the bluebook declares it, never the constant path.
+    def hecks_name = @hecks_name
+
+    # How this construct joins its owner. An aggregate is a member of its
+    # chapter's namespace (`::`) ; everything else is declared ON its owner
+    # (`.`). Overridden by Aggregate, defaulted here for every other construct.
+    def hecks_separator = "."
+
+    # REFUSES rather than guesses. A construct with no owner and no claim to be a
+    # chapter has simply not been stamped yet — entity commands are in that state
+    # while entities are still IR objects — and answering the bare name would be a
+    # plausible half-truth that no test would notice. That shape of falsehood is
+    # what this repo keeps finding, so it goes red instead.
+    def hecks_fqn
+      return hecks_name.to_s if hecks_root?
+
+      unless hecks_owner
+        raise Construct::Unowned,
+              "#{hecks_name.inspect} cannot say what declares it, so it has no " \
+              "identity — it was never stamped with an owner"
+      end
+
+      "#{hecks_owner.hecks_fqn}#{hecks_separator}#{hecks_name}"
+    end
+  end
+end

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

@@ -0,0 +1,219 @@
+# A TOOLING-INTERNAL DOMAIN, not a business one — never attached via
+# `uses_framework`, never seen by an end-user domain. `bin/project_deploy`
+# boots this directory directly (Ports::Loading.bootstrap + load_domain,
+# the same pipeline lib/hecks/runtime/loader.rb uses, minus a
+# `.world`/`.hecksagon` this domain has no need for) and dispatches one
+# command against it before generating anything from a domain's own
+# `deployed_to("AwsLambda")` settings.
+#
+# WHY THIS EXISTS: `world.bluebook`'s `Wiring`/`Setting` is a DELIBERATELY
+# open, untyped map — "a verb's schema is not even contained in the file
+# being parsed" (syntax.bluebook's own header on this). That's the right
+# call for `Wiring` itself (an adapter verb's shape genuinely isn't the
+# world language's business), but it leaves `deployed_to`'s ACTUAL shape
+# validated nowhere — `bin/project_deploy` used to check it by hand
+# (`deploy_settings[:adapter] == "AwsLambda" or abort ...`,
+# `fetch(:region) { abort ... }`), the exact raw-Ruby-refusal pattern
+# every other kind of bluebook mistake in this codebase does NOT use.
+# This closes that gap the same way any other rule gets enforced here:
+# as a real command, real invariants, a real corpus-testable refusal —
+# not a hand-written abort string discovered only by running the script.
+Hecks.bluebook "Deploy" do
+  aggregate "LambdaTarget" do
+    description "One domain's validated AWS Lambda deploy target — what deployed_to(\"AwsLambda\") must resolve to before bin/project_deploy generates anything from it."
+
+    identified_by :domain
+
+    attribute :domain,   DomainName
+    attribute :region,   Region
+    attribute :memory,   Memory
+    attribute :timeout,  Timeout
+    attribute :database, Database
+    attribute :web,      Web
+
+    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
+
+    # "Postgres" (a plain AWS::RDS::DBInstance, Embryonaut's own live
+    # choice — bin/project_deploy's Ruby-side default when a domain's
+    # own deployed_to("AwsLambda") names none, so every domain
+    # declared before this attribute existed keeps generating the
+    # identical template it always has) or "Aurora" (Aurora Serverless
+    # v2, Postgres-compatible — the SAME `Adapters::Postgres`/
+    # `tokio_postgres` code on both the Ruby and rust/host sides
+    # either way; this only changes which CloudFormation resource
+    # bin/project_deploy emits, never a runtime adapter).
+    # "Shared" — no RDS/VPC of this domain's own at all; it borrows
+    # another already-deployed domain's instance instead (the
+    # storehouse), isolated from that domain's own data by a native
+    # Postgres SCHEMA (this domain's own lowercase name), not a
+    # separate database. Requires a sibling `owner "OtherDomain"`
+    # setting inside the SAME deployed_to("AwsLambda") block, naming
+    # which already-deployed domain owns the shared instance —
+    # bin/project_deploy checks for that setting itself (Ruby-level,
+    # the same as `pg_version`/`google_oauth_present` below it), not
+    # here: which domain owns the instance is a deploy-time fact, not
+    # a business invariant this validated aggregate's job to hold.
+    value_object "Database" do
+      attribute :value, String, one_of: ["Postgres", "Aurora", "Shared"]
+    end
+
+    # "None" (the default — nothing changes for a domain that names
+    # neither this nor drops a `lambda_handler.rb`, e.g. Banking) or
+    # "Rust" — the domain's OWN Lambda (rust/host) also serves a public
+    # web UI in-process (rust/host/src/web.rs), reading HECKS_IR_PATH
+    # (a plain-JSON sidecar bin/project_wasm writes beside the .wasm
+    # artifact) and dispatching through the SAME in-process
+    # dispatch::handle/read the internal {"verb"}/{"read"} path already
+    # uses — no second Lambda, no VPC Interface Endpoint, no Ruby.
+    # Deliberately NOT "Ruby" as a third member here: a Ruby WebFunction
+    # is the pre-existing, SEPARATE `lambda_handler.rb`-file-presence
+    # mechanism (Embryonaut's own), untouched by this attribute —
+    # bin/project_deploy refuses generation outright if a domain
+    # declares `web "Rust"` AND has a `lambda_handler.rb`, rather than
+    # silently picking one.
+    value_object "Web" do
+      attribute :value, String, one_of: ["None", "Rust"]
+    end
+
+    # 128-10240 MB — AWS Lambda's own real ceiling and floor, not a
+    # number this domain invented. A typo here used to fail deep inside
+    # a real `sam deploy`, sometimes minutes in; now it refuses before
+    # a single file is generated.
+    value_object "Memory" do
+      attribute :value, Integer
+      invariant("memory is at least 128 MB") { value >= 128 }
+      invariant("memory is at most 10240 MB") { value <= 10240 }
+    end
+
+    # 900s — Lambda's own real ceiling.
+    value_object "Timeout" do
+      attribute :value, Integer
+      invariant("a timeout is positive") { value.positive? }
+      invariant("a timeout fits Lambda's own 900s ceiling") { value <= 900 }
+    end
+
+    # ALL FOUR REQUIRED — deliberately, not `optional: true` +
+    # `default:`. Confirmed directly against CommandInterpreter's own
+    # `normalize_args`/`coerce_declared_arguments` (interpreting.rb):
+    # `next unless normalized.key?(attribute.name)` skips coercion
+    # entirely for an absent key, so a command-level `default:` is
+    # honored ONLY at the JSON/Rust-codegen boundary (`scalar_from_json_
+    # expr`'s own domain), never by Ruby's own direct dispatch — a
+    # `default:` here would be quietly false advertising. "What memory
+    # defaults to when unspecified" stays exactly where it already
+    # lived (bin/project_deploy's own `fetch(:memory, 512)`); this
+    # command validates a FULLY-RESOLVED target, and bin/project_deploy
+    # resolves the default before ever dispatching.
+    command "Declare" do
+      goal "Validate one domain's AwsLambda deploy target before anything is generated from it"
+
+      attribute :domain,   DomainName
+      attribute :region,   Region
+      attribute :memory,   Memory
+      attribute :timeout,  Timeout
+      attribute :database, Database
+      attribute :web,      Web
+
+      sets :domain
+      sets :region
+      sets :memory
+      sets :timeout
+      sets :database
+      sets :web
+
+      emits "LambdaTargetDeclared"
+    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
+  # the Postgres schema, boots once to prove it). Deliberately NOT a
+  # saga/process manager with durable runtime state — every step
+  # `bin/project_tenant` takes is already idempotent by construction
+  # (`CREATE SCHEMA IF NOT EXISTS` — PostgresEra#connect_for's own,
+  # File.write of the overlay — a plain overwrite, `Hecks.boot` itself),
+  # the same "generator script, not a business process" shape
+  # `bin/project_deploy` already is; a saga's own resumability earns
+  # its cost coordinating a real distributed transaction across
+  # multiple ports with real failure boundaries (Payments::Payment's
+  # own PaymentGateway, say) — three local, idempotent, single-process
+  # steps have no such boundary to resume across. A durable, reactable
+  # RUNTIME fact ("this tenant exists, is active, is suspended") is a
+  # different, later, business-facing thing — deliberately not built
+  # here, and deliberately not named Deploy::Tenant to avoid colliding
+  # with this validation-only aggregate should it ever land.
+  aggregate "Tenant" do
+    description "One tenant's validated identity — which realm and Postgres schema `bin/project_tenant` provisions before booting a domain directory under Runtime.boot's own `environment:` overlay for it."
+
+    identified_by :slug
+
+    attribute :slug,   Slug
+    attribute :domain, DomainName
+    attribute :realm,  Realm
+    attribute :schema, Schema
+
+    # LOWERCASE, NO SPACES — a slug becomes both the `environments/
+    # <slug>.world` filename and (by convention, not enforced here —
+    # `schema` is its own, separately-declared field precisely so a
+    # tenant CAN choose a different schema name than its slug)
+    # ordinarily the schema name too.
+    value_object "Slug" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+      invariant("a tenant slug is named") { !value.to_s.empty? }
+    end
+
+    value_object "DomainName" do
+      attribute :value, String
+      invariant("a tenant names the domain it is for") { !value.to_s.empty? }
+    end
+
+    value_object "Realm" do
+      attribute :value, String
+      invariant("a tenant realm is named") { !value.to_s.empty? }
+    end
+
+    # POSTGRES'S OWN REAL IDENTIFIER RULES, loosely — lowercase (this
+    # adapter never quotes a mixed-case identifier back out consistently
+    # once created), letters/digits/underscores, starting with a letter.
+    # NOT a byte-length ceiling too (Postgres's own real 63-byte
+    # NAMEDATALEN limit) — the expression grammar invariants compile
+    # through admits a narrow arithmetic/comparison subset, not
+    # arbitrary method dispatch (`bytesize` included; found live,
+    # writing this: `Bluebook::Expression::Evaluator` tries to resolve
+    # a dotted chain as a FIELD lookup, not a method call, the same
+    # "admits + but not -, no parentheses" narrowness
+    # embryonaut_bluebooks/payments' own Refund command already
+    # documents). Postgres itself refuses a too-long identifier loudly
+    # on its own; not worth fighting the expression grammar for a
+    # corner case this rare.
+    value_object "Schema" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+      invariant("a schema is named") { !value.to_s.empty? }
+    end
+
+    command "Declare" do
+      goal "Validate one tenant's shape before bin/project_tenant provisions its schema and overlay world"
+
+      attribute :slug,   Slug
+      attribute :domain, DomainName
+      attribute :realm,  Realm
+      attribute :schema, Schema
+
+      sets :slug
+      sets :domain
+      sets :realm
+      sets :schema
+
+      emits "TenantDeclared"
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+# The Deploy domain, bound so it boots standing alone.
+Hecks.hecksagon "Deploy" do
+  persisted_by "Memory"
+end

data/lib/hecks/deploy/oidc.json

@@ -0,0 +1,18 @@
+{
+  "audience": "Deploy",
+  "scopes": [
+    {
+      "scope": "deploy:lambda_target.declare",
+      "verb": "Deploy::LambdaTarget.Declare",
+      "role": null
+    },
+    {
+      "scope": "deploy:tenant.declare",
+      "verb": "Deploy::Tenant.Declare",
+      "role": null
+    }
+  ],
+  "roles": [
+
+  ]
+}