hecks 1.4.0 → 1.5.0

data/lib/hecks/codemod.rb

@@ -2,20 +2,26 @@ require_relative "bluebook/meta_validator"
 require_relative "corpus"
 
 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.
+  # Shared machinery for a codemod that migrates real `.bluebook` source.
+  #
+  # ## Why this module exists
+  #
+  # For migrating source once a DSL builder change turns a required
+  # declaration into an optional, redundant one — 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.
+  #
+  # ## The three-step contract
   #
   # **A codemod is not pattern-matching alone**. Deciding "is this line safe
   # to delete" means knowing what the runtime would resolve it to — so
@@ -33,9 +39,11 @@ module Hecks
   #      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:
+  # ## Design-time checklist for a future codemod
+  #
+  # 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
@@ -70,6 +78,10 @@ module Hecks
     MEMORY_ADAPTER   = File.join(ROOT, "lib/hecks/adapters/driven/memory.adapter")
     PRISM_ADAPTER    = File.join(ROOT, "lib/hecks/adapters/driven/prism.adapter")
 
+    # Exports a booted registry's canonical IR as JSON, for a before/after diff.
+    #
+    # @param registry [Runtime::Registry] the booted registry to export
+    # @return [String] the pretty-printed JSON IR export
     def self.export_json(registry) = Hecks::Projector::Exporter.json(registry)
 
     # `Hecks::Adapters::Prism` caches a file's parsed AST for the
@@ -83,6 +95,10 @@ module Hecks
     # 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).
+    #
+    # @param path [String, Array<String>] a single `.bluebook` file, a directory
+    #   to glob every `.bluebook` file from, or an explicit list of file paths
+    # @return [Runtime::Registry] a fresh registry with every file loaded and judged
     def self.load_bluebook(path)
       paths = if path.is_a?(Array)
                 path
@@ -109,12 +125,17 @@ module Hecks
     # 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.
+    # @return [String] the freshly re-derived meta-domain's canonical IR, as JSON
     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
 
+    # Forces the self-hosted meta-domain to re-derive from its current source,
+    # discarding any cached parse trees or memoized registry.
+    #
+    # @return [Runtime::Registry] the freshly re-derived meta-domain's registry
     def self.meta_registry
       Hecks::Adapters::Prism.forget_all
       Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
@@ -128,6 +149,14 @@ module Hecks
     # `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.
+    #
+    # @param registry [Runtime::Registry] a booted registry
+    # @yield [construct, command] every command in the registry, once per aggregate
+    #   and once per nested entity
+    # @yieldparam construct [Bluebook::Aggregate, Bluebook::Entity] whichever
+    #   aggregate or entity actually owns `command`
+    # @yieldparam command [Bluebook::Command] the command
+    # @return [Hash{String => Bluebook::Chapter}] `registry.bluebooks`, unchanged
     def self.each_command(registry)
       registry.bluebooks.each_value do |chapter|
         chapter.aggregates.each do |aggregate|
@@ -140,6 +169,12 @@ module Hecks
       end
     end
 
+    # Finds one construct's own attribute by name.
+    #
+    # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct to search
+    # @param name [String, Symbol, #to_s] the attribute's declared name
+    # @return [Bluebook::Attribute, nil] the matching attribute, or nil if `construct`
+    #   declares no attribute named `name`
     def self.owner_attribute(construct, name)
       construct.attributes.find { |attr| attr.name.to_s == name.to_s }
     end
@@ -149,18 +184,48 @@ module Hecks
     # `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.
+    #
+    # Nothing in the DSL stops a value object and an entity nested under
+    # the same aggregate from sharing a `hecks_name` — they are declared
+    # through two separate collections with no cross-kind uniqueness
+    # check between them. A silent value-objects-before-entities pick
+    # would resolve such a pair the same way every time regardless of
+    # which one `list_field` actually names, so a genuine collision is
+    # refused instead, the same "never first-wins silently" call
+    # `EntityBuilder#install_closed_sets!` already makes for a same-named
+    # closed set.
+    #
+    # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+    #   declaring `list_field`
+    # @param list_field [String, Symbol, #to_s] the name of the `list_of(...)` attribute
+    # @return [Bluebook::Entity, Bluebook::ValueObject, nil] the construct
+    #   `list_field` holds a list of, or nil if `list_field` names no attribute,
+    #   isn't a list, or names no known value object or entity
+    # @raise [RuntimeError] if a value object and an entity both match `list_field`'s type
     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 }
+      value_objects = construct.respond_to?(:value_objects) ? construct.value_objects : []
+      entities      = construct.respond_to?(:entities) ? construct.entities : []
+      matches = (value_objects + entities).select { |c| c.hecks_name.to_s == list_attr.type.to_s }
+
+      if matches.size > 1
+        raise "#{construct.hecks_name}##{list_field} names #{list_attr.type}, held by both a value " \
+              "object and an entity — ambiguous, cannot resolve which one the list holds"
+      end
+
+      matches.first
     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].
+    #
+    # @yield the risky boot/export step to run
+    # @return [Array(Object, nil), Array(nil, String)] `[the block's result, nil]`
+    #   on success, or `[nil, "ExceptionClass: message"]` if the block raises
+    #   any StandardError
     def self.safely
       [yield, nil]
     rescue StandardError => e
@@ -186,12 +251,29 @@ module Hecks
     #   label: ->(candidate) { "..." }
     #     One-line description for the results report.
     class Runner
+      # @param find_candidates [Proc] `->(registry) { [...] }` — given a booted
+      #   registry, returns every candidate this rule could migrate; a candidate's
+      #   shape is the caller's own, read back only by `apply_candidate`
+      # @param apply_candidate [Proc] `->(text, candidate) { [new_text, changed_bool] }`
+      #   — given one file's current text and one candidate, returns the edited text
+      #   and whether a match was found; `false` means the candidate doesn't apply to
+      #   this file
+      # @param label [Proc] `->(candidate) { "..." }` — a one-line description of a
+      #   candidate, for the results report
       def initialize(find_candidates:, apply_candidate:, label:)
         @find_candidates = find_candidates
         @apply_candidate = apply_candidate
         @label = label
       end
 
+      # Runs this rule's codemod across every example domain and the meta-domain.
+      #
+      # @param dry_run [Boolean] when true, every safe edit is still written and
+      #   reverified, then reverted rather than kept
+      # @return [Hash{Symbol => Array}] `:applied` (`Array<Hash{file: String,
+      #   candidates: Array<String>}>`), `:skipped` (`Array<Hash{file: String,
+      #   reason: String, candidates: Array<String>}>`), and `:clean`
+      #   (`Array<String>` of domain directories or `"meta-domain"` with no candidates)
       def run(dry_run: false)
         results = { applied: [], skipped: [], clean: [] }
         run_example_domains(results, dry_run)
@@ -199,6 +281,11 @@ module Hecks
         results
       end
 
+      # Prints `run`'s results to stdout.
+      #
+      # @param results [Hash{Symbol => Array}] a `run` result
+      # @param dry_run [Boolean] whether this was a dry run, for the report's own heading
+      # @return [void]
       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?

data/lib/hecks/construct.rb

@@ -1,6 +1,8 @@
 module Hecks
   # The invisible field a built construct carries.
   #
+  # ## Identity
+  #
   # 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
@@ -20,7 +22,7 @@ module Hecks
   # record of that construct carry the same identity, and there is no
   # translation table between them to be quietly wrong in.
   #
-  # Usage:
+  # ## Usage
   #
   #     price = Class.new(ValueObject)   # a declaration holder
   #     price.hecks_name  = "Price"
@@ -41,14 +43,21 @@ module Hecks
     # rather than a top — see hecks_fqn.
     attr_writer :hecks_root
 
+    # Whether this construct is the top of its own owner chain.
+    #
+    # @return [Boolean] true for a chapter, which sets `hecks_root`; false otherwise
     def hecks_root? = @hecks_root ? true : false
 
     # The name as the bluebook declares it, never the constant path.
+    #
+    # @return [String] the construct's own name, without any owner prefix
     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.
+    #
+    # @return [String] `"."`, the separator this construct uses in `hecks_fqn`
     def hecks_separator = "."
 
     # Refuses rather than guesses. A construct with no owner and no claim to be a
@@ -56,6 +65,11 @@ module Hecks
     # 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.
+    #
+    # @return [String] the fully-qualified name, joining every owner from the
+    #   chapter down to this construct
+    # @raise [Construct::Unowned] if this construct has no owner and is not itself
+    #   a chapter (root)
     def hecks_fqn
       return hecks_name.to_s if hecks_root?
 

data/lib/hecks/corpus.rb

@@ -4,14 +4,13 @@ module Hecks
   # **The corpus, discovered** — every place in this repo that holds a real
   # domain, named once.
   #
-  # This used to be spelled out separately by every consumer that walks
-  # it — spec/corpus_spec.rb, spec/model_check_spec.rb, bin/model_check,
-  # spec/parser_parity_spec.rb, bin/fuzz, Fuzzing::CombinationMiner — and
-  # the copies had already drifted: only the model checker saw
+  # One table here, rather than each consumer spelling out its own copy —
+  # spec/corpus_spec.rb, spec/model_check_spec.rb, bin/model_check,
+  # spec/parser_parity_spec.rb, bin/fuzz, Fuzzing::CombinationMiner all did,
+  # and the copies had already drifted: only the model checker saw
   # `qa/bluebook`, only parser parity saw `spec/fixtures`, and nothing but
-  # bin/fuzz's own sweep ever saw `qa/stress_domains`. One table here, and
-  # each consumer names the KINDS it walks rather than re-deriving where
-  # those kinds live.
+  # bin/fuzz's own sweep ever saw `qa/stress_domains`. Each consumer names
+  # the `KINDS` it walks rather than re-deriving where those kinds live.
   #
   # Plain Dir/File only — bin/ scripts require this before (or without)
   # booting anything.
@@ -25,7 +24,19 @@ module Hecks
     DIRECTORY_KINDS = {
       example:   "examples/*",
       stress:    "qa/stress_domains/*",
-      semantics: "spec/corpus/semantics/domains/*"
+      semantics: "spec/corpus/semantics/domains/*",
+      # A PACKAGE VENDORED VIA `uses_embryonaut_bluebook` — same real
+      # mechanism `uses_framework` is (`lib/hecks/embryonaut_bluebook.rb`'s
+      # own header: "same shape as Framework"), one level further out: not
+      # a chapter shipped inside THIS gem's own `lib/hecks/framework/
+      # bluebook/` (the `:framework` FILE_KIND, below), but a directory
+      # nested inside the CONSUMING example's own checkout
+      # (`<domain>/vendor/embryonaut_bluebooks/<name>/bluebook/`,
+      # EmbryonautBluebook.load!'s own resolution path) — hence its own
+      # DIRECTORY_KIND rather than reuse of `:framework`'s shape. First
+      # real member: docs/decisions/0058's own
+      # examples/embryonaut_vendoring_demo/vendor/embryonaut_bluebooks/widgets.
+      vendored:  "examples/*/vendor/embryonaut_bluebooks/*"
     }.freeze
 
     # **One chapter per file**. Stemmed by the path below the glob's fixed
@@ -37,6 +48,7 @@ module Hecks
       qa:        "qa/bluebook/*.bluebook",
       language:  "lib/hecks/language/**/*.bluebook",
       deploy:    "lib/hecks/deploy/bluebook/*.bluebook",
+      tenancy:   "lib/hecks/tenancy/bluebook/*.bluebook",
       fixture:   "spec/fixtures/**/*.bluebook"
     }.freeze
 
@@ -88,6 +100,13 @@ module Hecks
 
     module_function
 
+    # Lists corpus members of the given kinds (every kind, by default).
+    #
+    # @param kinds [Array<Symbol>] corpus kinds to include, from `KINDS`; every kind
+    #   when empty
+    # @param root [String] repository root to search under
+    # @return [Array<Member>] matching members
+    # @raise [ArgumentError] if `kinds` names a kind not in `KINDS`
     def members(*kinds, root: ROOT)
       kinds = KINDS if kinds.empty?
       kinds.flat_map do |kind|
@@ -107,6 +126,10 @@ module Hecks
     # What a boot loads for a member: a directory kind's bluebook
     # directory, a file kind's own file. `nil` for a directory holding no
     # bluebook at all.
+    #
+    # @param member [Member] the corpus member
+    # @return [String, nil] the path to boot, or nil when a directory member holds
+    #   no bluebook
     def source_of(member)
       DIRECTORY_KINDS.key?(member.kind) ? bluebook_dir(member.path) : member.path
     end
@@ -114,6 +137,9 @@ module Hecks
     # Where a domain path keeps its bluebooks — `<domain>/bluebook/*.bluebook`
     # (every example and stress domain), or the directory itself
     # (`qa/bluebook`). `nil` when neither holds a bluebook.
+    #
+    # @param domain_path [String] path to a domain directory
+    # @return [Array<String>, nil] `.bluebook` file paths found, or nil when none
     def bluebook_files(domain_path)
       [File.join(domain_path, "bluebook"), domain_path].each do |dir|
         files = Dir[File.join(dir, "*.bluebook")]
@@ -122,6 +148,11 @@ module Hecks
       nil
     end
 
+    # The directory holding `domain_path`'s bluebooks.
+    #
+    # @param domain_path [String] path to a domain directory
+    # @return [String, nil] directory of the first `.bluebook` file found, or nil
+    #   when `domain_path` holds none
     def bluebook_dir(domain_path)
       files = bluebook_files(domain_path)
       files && File.dirname(files.first)
@@ -129,6 +160,9 @@ module Hecks
 
     # The route a repo-relative path takes instead of the sweep — the
     # first one it matches — or `nil` when the sweep boots it.
+    #
+    # @param relative_path [String] a corpus member's path, relative to the repo root
+    # @return [Route, nil] the first matching route, or nil when the sweep boots it
     def route_for(relative_path)
       ROUTES.find { |route| route.pattern.match?(relative_path) }
     end
@@ -139,8 +173,12 @@ module Hecks
     # member a route already sends to a destination of its own: the
     # broken-on-purpose model_check fixtures must produce their findings
     # there, so a clean-corpus gate here would be the wrong check for them.
-    MODEL_CHECK_KINDS = %i[example grammar framework qa stress fixture].freeze
+    MODEL_CHECK_KINDS = %i[example grammar framework vendored qa stress fixture].freeze
 
+    # Every corpus member `bin/model_check` and `spec/model_check_spec.rb` walk.
+    #
+    # @param root [String] repository root to search under
+    # @return [Array<Member>] members of `MODEL_CHECK_KINDS`, less any routed elsewhere
     def model_check_members(root: ROOT)
       members(*MODEL_CHECK_KINDS, root: root).reject { |member| route_for(member.path.delete_prefix("#{root}/")) }
     end
@@ -162,6 +200,10 @@ module Hecks
     # puts a domain in the rotation and nothing tied that list to the
     # corpus. Promotion only ever printed the `target.identify` line for a
     # human to run.
+    #
+    # @param root [String] repository root to search under
+    # @return [Hash{String => String}] each rotation member's stem/reference mapped
+    #   to its repo-relative path
     def rotation_targets(root: ROOT)
       members(:example, :stress, root: root)
         .to_h { |member| [member.stem, member.path.delete_prefix("#{root}/")] }
@@ -171,6 +213,9 @@ module Hecks
     # Every bootable domain in the project, not a hand-kept list — any
     # directory holding a `.bluebook` no route sends elsewhere, a
     # `bluebook/` folder standing for the domain directory around it.
+    #
+    # @param root [String] repository root to search under
+    # @return [Array<String>] absolute paths of every sweepable domain directory
     def sweepable_domains(root = ROOT)
       Dir.chdir(root) do
         Dir.glob("**/*.bluebook")
@@ -184,6 +229,9 @@ module Hecks
 
     # The domain directory a member stands for, spelled the way
     # `sweepable_domains` spells it: a `bluebook/` folder is its parent.
+    #
+    # @param member [Member] the corpus member
+    # @return [String] the member's owning domain directory path
     def domain_dir_of(member)
       dir = File.directory?(member.path) ? member.path : File.dirname(member.path)
       File.basename(dir) == "bluebook" ? File.dirname(dir) : dir
@@ -192,10 +240,10 @@ module Hecks
     # ── The Rust-facing corpus ─────────────────────────────────────────
     #
     # Every Rust-facing list (the fuzz bridge, the codegen drift check,
-    # rust coverage, codegen parity) used to be typed out by hand, and
-    # each had drifted from `rust/Cargo.toml`'s `[features]`: fuzzing saw
-    # 8 of 20 features. These read the one source instead. The
-    # `rust/src/generated/` modules split into buckets, and
+    # rust coverage, codegen parity) reads `rust/Cargo.toml`'s `[features]`
+    # as its one source, rather than being typed out by hand per consumer
+    # and drifting from it — hand-typed, fuzzing once saw only 8 of 20
+    # features. The `rust/src/generated/` modules split into buckets, and
     # spec/corpus_rust_spec.rb proves every Cargo feature and every
     # generated module lands in exactly one of them:
     #
@@ -232,15 +280,27 @@ module Hecks
     # it is deleted here.
     RUST_COVERAGE_PENDING = {}.freeze
 
+    # The Cargo `[features]` table's raw text.
+    #
+    # @param root [String] repository root to search under
+    # @return [String] the table's text, or `""` when `rust/Cargo.toml` has none
     def cargo_features_table(root: ROOT)
       File.read(File.join(root, "rust/Cargo.toml"))[Fuzzing::TargetCapabilities::FEATURES_TABLE] || ""
     end
 
+    # Every feature name Cargo declares with no dependency array of its own.
+    #
+    # @param root [String] repository root to search under
+    # @return [Array<String>] feature names, in file order
     def cargo_features(root: ROOT)
       cargo_features_table(root: root).scan(/^(\w+)\s*=\s*\[\]/).flatten
     end
 
     # The feature `bin/project_rust` last wrote as Cargo's `default`.
+    #
+    # @param root [String] repository root to search under
+    # @return [String, nil] the default feature's name, or nil when Cargo.toml
+    #   declares none
     def cargo_default(root: ROOT)
       cargo_features_table(root: root)[/^default\s*=\s*\["(\w+)"\]/, 1]
     end
@@ -250,6 +310,9 @@ module Hecks
     # decides which directory it came from — a directory name alone is not
     # enough: spec/fixtures/qa_discover_external_domains vendors a second
     # `examples/pizzas` that no Cargo feature was ever generated from.
+    #
+    # @param root [String] repository root to search under
+    # @return [Array<RustDomain>] each Rust-facing domain, sorted by directory path
     def rust_domains(root: ROOT)
       features = cargo_features(root: root)
       members(*RUST_DOMAIN_KINDS, root: root)
@@ -260,6 +323,12 @@ module Hecks
         .map { |dir, kind| RustDomain.new(File.basename(dir).downcase, dir, kind) }
     end
 
+    # Tells whether `dir` is the real source directory for its Cargo feature.
+    #
+    # @param dir [String] a candidate domain directory
+    # @param features [Array<String>] known Cargo feature names
+    # @param root [String] repository root `dir` is rooted under
+    # @return [Boolean]
     def rust_domain_dir?(dir, features, root)
       feature = File.basename(dir).downcase
       source = generated_source(feature, root: root)
@@ -269,36 +338,83 @@ module Hecks
     # Where a generated module came from, read off the stamp bin/project_rust
     # writes into its metadata.rs — `examples/pizzas`, `/abs/path/embryonaut`,
     # `the self-hosted language (lib/hecks/language/bluebook)`, with any
-    # ` (uses_framework "X")` suffix dropped. `nil` when not generated.
-    SOURCE_STAMP = %r{GENERATED by bin/project_rust — (.+?)(?: \(uses_framework "\w+"\))?'s own canonical IR,}
-
+    # ` (uses_framework "X")` or ` (uses_embryonaut_bluebook "X")` suffix
+    # dropped. `nil` when not generated.
+    SOURCE_STAMP = %r{
+      GENERATED\ by\ bin/project_rust\ —\ (.+?)
+      (?:\ \((?:uses_framework|uses_embryonaut_bluebook)\ "\w+"\))?
+      's\ own\ canonical\ IR,
+    }x
+
+    # Where a generated module came from, read off the stamp `bin/project_rust`
+    # writes into its metadata.rs.
+    #
+    # @param module_name [String] a generated module's name
+    # @param root [String] repository root to search under
+    # @return [String, nil] the source path the stamp names, or nil when the module
+    #   is not generated
     def generated_source(module_name, root: ROOT)
       metadata = File.join(root, GENERATED_DIR, module_name, "metadata.rs")
       File.file?(metadata) ? File.read(metadata)[SOURCE_STAMP, 1] : nil
     end
 
+    # Every module directory under `rust/src/generated`.
+    #
+    # @param root [String] repository root to search under
+    # @return [Array<String>] generated module names, sorted
     def generated_modules(root: ROOT)
       Dir.children(File.join(root, GENERATED_DIR)).select { |name| File.directory?(File.join(root, GENERATED_DIR, name)) }.sort
     end
 
+    # Tells whether `feature` has already been generated (has a merged.rs).
+    #
+    # @param feature [String] a Cargo feature / domain name
+    # @param root [String] repository root to search under
+    # @return [Boolean]
     def generated?(feature, root: ROOT)
       File.file?(File.join(root, GENERATED_DIR, feature, "merged.rs"))
     end
 
-    # Framework members `bin/project_rust` writes a module for as a side
-    # effect of some `uses_framework` domain — a module, no merged.rs.
-    def rust_framework_chapters(root: ROOT)
+    # Chapters attached via `kind` (`:framework` or `:vendored`) that
+    # `bin/project_rust` writes a module for as a side effect of the
+    # attaching domain — a module, no merged.rs of its own. Both kinds
+    # share this shape: `bin/project_rust`'s own generated module name is
+    # always `chapter_name.downcase` (rust/src/generated/mod.rs's own
+    # convention), and for either kind that downcased name is always the
+    # original lowercase directory stem again — confirmed live for a
+    # framework member and for a vendored package alike (a vendored
+    # package's own bluebook stem doesn't have to equal its declared
+    # chapter name the way a framework member's does — `EmbryonautBluebook.
+    # load!` resolves it as `Naming.pascal(dir_name)`, e.g. "widgets" ->
+    # "Widgets" — but downcasing a `Naming.pascal`-derived name always
+    # returns the original lowercase stem again).
+    #
+    # @param kind [Symbol] :framework or :vendored
+    # @param root [String] repository root to search under
+    # @return [Array<String>] stems with a generated module but no merged.rs
+    #   of their own
+    def rust_side_chapters(kind, root: ROOT)
       modules = generated_modules(root: root)
-      members(:framework, root: root).map(&:stem)
-                                     .select { |stem| modules.include?(stem) && !generated?(stem, root: root) }
+      members(kind, root: root).map(&:stem)
+                               .select { |stem| modules.include?(stem) && !generated?(stem, root: root) }
     end
 
-    # The regeneration order the drift check runs. Sorted by path, so
+    def rust_framework_chapters(root: ROOT)
+      rust_side_chapters(:framework, root: root)
+    end
+
+    def rust_vendored_chapters(root: ROOT)
+      rust_side_chapters(:vendored, root: root)
+    end
+
+    # THE REGENERATION ORDER the drift check runs. Sorted by path, so
     # which domain runs last — and so wins Cargo's `default`, mod.rs's cfg
     # comments and the shared framework modules' attribution stamp — is a
-    # fact of the sorted list, not a hand-picked order. (The old hand list
-    # put waybill last; PR #667 moved to the sort, which makes
-    # has_many_fixture last.) spec/corpus_rust_spec.rb pins last == default.
+    # fact of the sorted list, not a hand-picked order: today that is
+    # `has_many_fixture`. spec/corpus_rust_spec.rb pins last == default.
+    #
+    # @param root [String] repository root to search under
+    # @return [Array<RustDomain>] already-generated Rust domains, in regeneration order
     def rust_regen_order(root: ROOT)
       rust_domains(root: root).select { |domain| generated?(domain.feature, root: root) }
     end
@@ -308,6 +424,11 @@ module Hecks
     # file is named after its role, `aggregate.bluebook`, while its
     # chapter is always "Bluebook"). Scans the whole file: a framework
     # member's header comment can run past any fixed line cap.
+    #
+    # @param bluebook_path [String, Array<String>] a `.bluebook` file path, or an
+    #   array whose first element is used
+    # @return [String, nil] the declared chapter name, or nil when the file never
+    #   declares one
     def chapter_name_of(bluebook_path)
       bluebook_path = Array(bluebook_path).first
       header = File.foreach(bluebook_path).find { |line| line =~ /\A\s*Hecks\.bluebook\s+"([^"]+)"/ }

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

@@ -1,4 +1,23 @@
 # The Deploy domain, bound so it boots standing alone.
 Hecks.hecksagon "Deploy" do
   persisted_by "Memory"
+
+  # THE IMPERATIVE HALF, BEHIND A REAL PORT — `bin/project_tenant`
+  # dispatches this `asks` once `Tenant.Declare` has already validated
+  # the request; `TenantProvisioner` (lib/hecks/adapters/driven/
+  # tenant_provisioner.rb) writes the overlay file and answers or
+  # refuses. `database`/`adapter`/`directory` are declared here, not on
+  # `Tenant` itself — CLI-only facts this validated request never
+  # needed to hold as its own state. `directory` is the real
+  # filesystem path being provisioned — NOT re-derivable from `Tenant`'s
+  # own `domain` (its declared NAME, e.g. "Scratch", never a path).
+  Deploy::Tenant.port "TenantProvisioning" do
+    asks "Provision", to: Tenant do
+      attribute :database,  DatabaseName
+      attribute :adapter,   AdapterName
+      attribute :directory, DirectoryPath
+      answers "TenantProvisioned"
+      refuses "ProvisioningRefused"
+    end
+  end
 end