hecks 3.0.5 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16dca2d33433ad6c6cd98b8dee40f652df3d84c7bb93df5cd1f7734b99542c08
-  data.tar.gz: '084b92e2ad954b89a488d44997d754cd15388136f502f918f24274fd26cf9e87'
+  metadata.gz: 29694d3639f1ad69a3d0a81bf4e6494c5a6d60a88ca9897af3a01224944d654e
+  data.tar.gz: b9fb1376266fe98b2d09c6127bbbbe3a954c11e9441c3f01976e54f44b63eaf7
 SHA512:
-  metadata.gz: 0f2b6dda10ee042c6cb1bbe3ae9100a66c35dad25b17a031ab7ca6fd0eaf7ea5960b1a3e52024d5a40c3090ca999f1730db9275f7a5ec8b803e8ae0a465102df
-  data.tar.gz: 8aebabbb0a023e9c2ff989df18f665924ec9acf4043a922bcb995588fb424683d8d44bea2e02f2076932beae2b27d63da097153c054131aa4232c132123d33eb
+  metadata.gz: 6eea28ed2426948aeca13df88967f06a5d64acf29dbb376a16b53d82367e90383f3646928ee4940ff9d93969ea7721ed29fb4467096eb8a2b88bc14f7f7ede47
+  data.tar.gz: 52d5f117ce1b1bae946f939dad3c73567a44c5c466257c37cbaf5bb7bcecb0cb3a3ea92e9c41b3edde78efbdb674669d08f56305287f46313c1cb4ce813d3042

data/exe/hecks

@@ -2,12 +2,12 @@
 
 # Hecks's command line — GENERATED by hecks project_cli. Do not edit.
 #
-# A launcher, not a CLI: the verbs, their arguments and their refusals are
+# A launcher, not a CLI: the commands, their arguments and their refusals are
 # projected from the bluebook beside it every time this runs, so a change
 # to the chapter shows up here without re-minting anything.
 #
-#   exe/hecks                  every verb, and every question
-#   exe/hecks <verb> --help    what it wants, and how it refuses
+#   exe/hecks                  every command, and every question
+#   exe/hecks <command> --help    what it wants, and how it refuses
 
 Encoding.default_external = Encoding::UTF_8
 Encoding.default_internal = Encoding::UTF_8
@@ -21,15 +21,17 @@ if LEGACY.include?(ARGV.first)
   exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
 end
 
-# These verbs keep nothing worth a database, so they run on Memory unless told otherwise, and
-# print nothing when they end well.
-MEMORY_VERBS = %w[console].freeze
-ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_VERBS.include?(ARGV.first)
+# These commands keep nothing worth a database, so they run on Memory unless told otherwise.
+# A person is at them: they wait for their result, say why when they are refused, and print
+# no record when they end well.
+MEMORY_COMMANDS = %w[console init].freeze
+ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
+ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARGV.include?("--wait")
 
 require "hecks"
 
 # Usage is answered from the projected chapter alone: no adapter is bound and no
-# database is opened. Only a line that runs a verb boots the domain,
+# database is opened. Only a line that runs a command boots the domain,
 # and it boots from what the usage check already loaded.
 domain = File.expand_path("../lib/hecks/hecks", __dir__)
 program = "hecks"
@@ -44,7 +46,7 @@ text, status, reason = Hecks::Doors::CliRunner.usage(
 )
 unless text
   runtime = begin
-    Hecks::Doors::LauncherOptions.quietly(hold: MEMORY_VERBS.include?(ARGV.first)) { Hecks.boot_described(described, install_doors: false) }
+    Hecks::Doors::LauncherOptions.quietly(hold: MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))) { Hecks.boot_described(described, install_doors: false) }
   rescue StandardError => e
     abort "cannot open Hecks: #{e.message.lines.first.strip}"
   end
@@ -58,9 +60,19 @@ end
 # A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
 # either way, and says why on stderr.
 if reason
-  puts text
-  warn reason
+  if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
+    why = begin
+      require "json"
+      JSON.parse(text).dig("state", "refusal", "value")
+    rescue JSON::ParserError
+      nil
+    end
+    warn(why ? why.sub(/\A(\w+::)+\w+: /, "") : reason)
+  else
+    puts text
+    warn reason
+  end
   exit status
 end
-exit 0 if status.zero? && MEMORY_VERBS.include?(ARGV.first)
+exit 0 if status.zero? && MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
 status.zero? ? puts(text) : abort(text)

data/lib/hecks/adapters/driven/lambda/client.rb

@@ -7,7 +7,7 @@ module Hecks
       # Runtime::RemoteDispatcher's writes: one Lambda invoke, one JSON round trip.
       #
       # The function name defaults to `"hecks-#{domain.downcase}"`, matching
-      # `hecks deploy project`'s `stack_name` computation. A domain whose stack
+      # `hecks deploy recipe.project`'s `stack_name` computation. A domain whose stack
       # name doesn't follow that pattern must pass `function` explicitly, via
       # a `.world`'s `persisted_by("Lambda")`/`dispatched_by("Lambda")` block.
       class Client

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

@@ -38,7 +38,7 @@ module Hecks
         function = setting(settings, :function, nil)
         # `domain` only prefixes the instances lookup; the function to call is named by
         # DOMAIN_NAME (set in a deployed Lambda, where root is always /var/task), else by
-        # root's basename, which matches hecks deploy project's stack name on a local boot.
+        # root's basename, which matches hecks deploy recipe.project's stack name on a local boot.
         function_domain = ENV["DOMAIN_NAME"] || (root ? File.basename(root) : domain)
         @client = Client.new(domain: function_domain, region: region, function: function)
         @prefix = "#{domain}::#{aggregate.hecks_name}#"

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

@@ -5,8 +5,8 @@ require "fileutils"
 module Hecks
   module Adapters
     # The imperative half of tenant provisioning, behind `Deploy::Tenant.port
-    # "TenantProvisioning"`, for `Tenant.Provision` and for hecks deploy provision; booting the
-    # domain and its capability gate stay in hecks deploy provision.
+    # "TenantProvisioning"`, for `Tenant.Provision` and for hecks deploy tenant.provision; booting
+    # the domain and its capability gate stay in hecks deploy tenant.provision.
     class TenantProvisioner
       # Raised when a value is outside its allow-list or the overlay path leaves `environments/`.
       class Refused < ArgumentError; end

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

@@ -3,7 +3,7 @@ module Hecks
   module Bluebook
     module DSL
       # Parses a `.hecksagon` file's DSL block into a Hecksagon: a domain's adapter bindings,
-      # framework/vendored attachments and subscriptions — wiring, not part of the bluebook.
+      # attachments and subscriptions — wiring, not part of the bluebook.
       class HecksagonBuilder
         GRAMMAR_CONTEXT = "Hecksagon".freeze
 
@@ -57,20 +57,22 @@ module Hecks
           end
         end
 
-        attr_reader :binds, :subscriptions, :framework_members, :vendored_bluebooks, :attached_chapters
+        # The release that drops the deprecated spellings of `attaches`; kept in step with
+        # `Hecks::Doors::REMOVAL`, which this file cannot require.
+        REMOVAL = "3.2.0".freeze
+
+        attr_reader :binds, :subscriptions, :attachments
 
         def initialize(domain)
           @domain             = domain
           @binds              = []
           @subscriptions      = []
-          @framework_members  = []
-          @vendored_bluebooks = []
-          @attached_chapters  = []
+          @attachments        = []
           @bounded            = false
           @translates         = []
         end
 
-        # Marks this chapter as a bounded context; framework/vendored attachments set it too.
+        # Marks this chapter as a bounded context; an attachment marks its chapter bounded too.
         # Must declare at least one `translates` ACL or boot refuses.
         def bounded
           @bounded = true
@@ -79,35 +81,37 @@ module Hecks
         # Subscribes to an event from outside this domain's own bluebook.
         def subscribe(event) = @subscriptions << event.to_s
 
-        # Attaches a framework member (e.g. Governance) and loads it into the current registry.
+        # Attaches a chapter by name and loads it into the current registry, marked bounded.
+        #
+        # Without `from:` the name is a chapter the gem carries (a framework member such as
+        # Governance, or a language chapter such as Deploy) with the ports and adapters it
+        # ships. `from: :vendor` loads `vendor/embryonaut_bluebooks/<name>/bluebook` instead,
+        # and is never a fallback for a misspelt gem name.
+        #
+        # @param name [String, Symbol] a gem chapter's name or a vendored package's directory name
+        # @param from [Symbol, nil] `:vendor` for a vendored package, nil for a gem chapter
+        # @raise [Runtime::WiringError] if the name is unknown, or `from:` names another source
+        def attaches(name, from: nil)
+          unless [nil, :vendor].include?(from)
+            raise Runtime::WiringError,
+                  "attaches #{name.to_s.inspect}, from: #{from.inspect} — `from:` takes only :vendor"
+          end
+
+          from == :vendor ? attach_vendored(name) : attach_gem(name)
+        end
+
+        # The deprecated spelling of `attaches "Name"` for a framework member.
         def uses_framework(name)
-          @framework_members << name.to_s
-          Hecks::Framework.load!(name)
-          # Marks the framework member as bounded; the consumer's own hecksagon is the
-          # anti-corruption layer.
+          deprecated_word("uses_framework", "attaches #{name.to_s.inspect}")
+          @attachments << Attachment.new(name: name.to_s, source: :gem)
+          self.class.with_real_modules { Hecks::Framework.load!(name) }
           Hecks.current_registry&.mark_bounded(name.to_s)
         end
 
-        # Attaches a vendored embryonaut bluebook to this domain and loads its files into the
-        # registry. Recorded separately from @framework_members, which is load-bearing for
-        # governance checks.
+        # The deprecated spelling of `attaches "name", from: :vendor`.
         def uses_embryonaut_bluebook(name)
-          @vendored_bluebooks << name.to_s
-          Hecks::EmbryonautBluebook.load!(name)
-          # Marks the chapter bounded, same as `uses_framework`; the directory name Pascal-cases
-          # to the chapter name (`"membership"` → `Membership`).
-          Hecks.current_registry&.mark_bounded(Hecks::Naming.pascal(name.to_s))
-        end
-
-        # Attaches a chapter the gem carries (the language, Expression, Tenancy, Deploy,
-        # QualityControl) by name and loads its files into the registry, with the ports and
-        # adapters it ships. Marked bounded like a framework member, since this hecksagon is its
-        # anti-corruption layer.
-        def attaches(name)
-          require_relative "../../chapters"
-          @attached_chapters << name.to_s
-          self.class.with_real_modules { Hecks::Chapters.load!(name) }
-          Hecks.current_registry&.mark_bounded(name.to_s)
+          deprecated_word("uses_embryonaut_bluebook", "attaches #{name.to_s.inspect}, from: :vendor")
+          attach_vendored(name)
         end
 
         # Declares a port at the hecksagon's root — the chapter as a whole, not one aggregate.
@@ -145,9 +149,32 @@ module Hecks
         # No ungoverned-role check here — it runs once on the merged result at verify! time.
         def build
           Hecksagon.new(domain: @domain, binds: @binds, subscriptions: @subscriptions,
-                        framework_members: @framework_members, vendored_bluebooks: @vendored_bluebooks,
-                        attached_chapters: @attached_chapters, bounded: @bounded, translates: @translates)
+                        attachments: @attachments, bounded: @bounded, translates: @translates)
+        end
+
+        # Loads a chapter the gem carries and records it as attached from the gem.
+        def attach_gem(name)
+          require_relative "../../chapters"
+          @attachments << Attachment.new(name: name.to_s, source: :gem)
+          self.class.with_real_modules { Hecks::Chapters.attach!(name) }
+          Hecks.current_registry&.mark_bounded(name.to_s)
+        end
+        private :attach_gem
+
+        # Loads a vendored package and records it as attached from `vendor/`. The directory name
+        # Pascal-cases to the chapter name (`"membership"` becomes `Membership`).
+        def attach_vendored(name)
+          @attachments << Attachment.new(name: name.to_s, source: :vendor)
+          Hecks::EmbryonautBluebook.load!(name)
+          Hecks.current_registry&.mark_bounded(Hecks::Naming.pascal(name.to_s))
+        end
+        private :attach_vendored
+
+        # Tells the author that a word is going away.
+        def deprecated_word(word, instead)
+          warn "[hecks] `#{word}` is deprecated and is removed in #{REMOVAL}; use `#{instead}`"
         end
+        private :deprecated_word
 
         # Records any verb the grammar doesn't own as a domain-wide default bind, e.g. bare
         # `persisted_by "Heki"` at the top of a block, applied unless an aggregate overrides it.

data/lib/hecks/bluebook/hexagon.rb

@@ -20,6 +20,23 @@ module Hecks
       def aggregate_name = Naming.demodulise(aggregate)
     end
 
+    # One chapter a hecksagon attaches, with where it was found.
+    #
+    # `source` is `:gem` for a chapter the gem carries (a framework member such as Governance,
+    # or a language chapter such as Deploy) and `:vendor` for a package vendored into the
+    # consuming project, whose `name` is the package's directory name (`"membership"`).
+    Attachment = Struct.new(:name, :source, keyword_init: true) do
+      # @return [Boolean] whether the chapter is a vendored package
+      def vendor? = source == :vendor
+
+      # @return [String] the chapter's name in the registry: a gem chapter's own name, a
+      #   vendored package's directory name in Pascal case
+      def chapter_name = vendor? ? Naming.pascal(name) : name
+
+      # @return [Hash{Symbol => String}] the attachment as plain data
+      def to_h = { name: name.to_s, source: source.to_s }
+    end
+
     # The built form of a `.hecksagon` file, produced by `DSL::HecksagonBuilder`.
     # `Behaviour::Hecksagon` supplies the bind lookups; this class holds the declared data.
     class Hecksagon
@@ -27,39 +44,31 @@ module Hecks
       include Behaviour::Hecksagon
 
       emits_ir(
-        domain:             :domain,
-        binds:              many(:binds),
-        subscriptions:      -> { subscriptions.map(&:to_s) },
-        framework_members:  -> { framework_members.map(&:to_s) },
-        vendored_bluebooks: -> { vendored_bluebooks.map(&:to_s) },
-        attached_chapters:  -> { attached_chapters.map(&:to_s) },
-        bounded:            :bounded?,
-        translates:         -> { translates.map(&:to_s) }
+        domain:        :domain,
+        binds:         many(:binds),
+        subscriptions: -> { subscriptions.map(&:to_s) },
+        attachments:   -> { attachments.map(&:to_h) },
+        bounded:       :bounded?,
+        translates:    -> { translates.map(&:to_s) }
       )
 
-      attr_reader :domain, :binds, :subscriptions, :framework_members, :vendored_bluebooks,
-                  :attached_chapters, :translates
+      attr_reader :domain, :binds, :subscriptions, :attachments, :translates
 
       # @param domain [String, Symbol] the domain this hecksagon wires
       # @param binds [Array<Bluebook::Bind>] the declared adapter binds
       # @param subscriptions [Array<String, Symbol>] the external events this domain
       #   subscribes to
-      # @param framework_members [Array<String, Symbol>] attached framework members (`Governance`)
-      # @param vendored_bluebooks [Array<String, Symbol>] the vendored embryonaut
-      #   bluebook package names this domain attaches
-      # @param attached_chapters [Array<String, Symbol>] chapters the gem carries, attached by name
+      # @param attachments [Array<Bluebook::Attachment>] every chapter this hecksagon attaches,
+      #   each with its source (`:gem` or `:vendor`)
       # @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)
+      #   (consumer-owned; `attaches` marks 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: [], attached_chapters: [], bounded: false, translates: [])
+      def initialize(domain:, binds: [], subscriptions: [], attachments: [], bounded: false,
+                     translates: [])
         @domain             = domain.to_s
         @binds              = binds
         @subscriptions      = subscriptions
-        @framework_members  = framework_members
-        @vendored_bluebooks = vendored_bluebooks
-        @attached_chapters  = attached_chapters
+        @attachments        = attachments
         @bounded            = bounded ? true : false
         @translates         = Array(translates).map(&:to_s)
       end
@@ -69,11 +78,22 @@ module Hecks
       # @return [Boolean] whether `bounded` was declared on this block
       def bounded? = @bounded
 
-      # Every chapter this hecksagon brings into its domain's registry: framework members and
-      # attached chapters alike, which resolve the same way.
+      # Every chapter this hecksagon brings into its domain's registry, gem and vendored alike.
+      #
+      # @return [Array<String>] the chapters' names as the registry holds them, in the order
+      #   they were attached
+      def member_chapters = attachments.map(&:chapter_name)
+
+      # Says whether this hecksagon attaches a chapter, whatever its source.
+      #
+      # @param chapter [String, Symbol] a chapter's name as the registry holds it
+      # @return [Boolean] whether that chapter is attached here
+      def attaches?(chapter) = member_chapters.include?(chapter.to_s)
+
+      # The vendored packages this hecksagon attaches.
       #
-      # @return [Array<String>] the chapters' names, framework members first
-      def member_chapters = (framework_members + attached_chapters).map(&:to_s)
+      # @return [Array<String>] their directory names, in the order they were attached
+      def vendored_packages = attachments.select(&:vendor?).map { |attachment| attachment.name.to_s }
     end
 
     # The built form of a `.world` file, produced by `DSL::WorldBuilder`.

data/lib/hecks/bluebook/model_check.rb

@@ -27,7 +27,7 @@ module Hecks
       # @param hecksagon [Bluebook::Hecksagon, nil] this bluebook's own sibling wiring
       #   file, if the caller loaded one
       # @param known_domains [Set<String>, nil] every bluebook/hecksagon name booted
-      #   anywhere in this corpus scan, checked to catch a typo'd across/uses_framework target
+      #   anywhere in this corpus scan, checked to catch a typo'd across/attaches target
       # @param global_emitted_events [Set<String>, nil] every event emitted anywhere in
       #   the corpus, checked as a fallback so a translates reaction isn't flagged deaf
       # @param profile [Symbol, nil] :client adds ClientProfile's error findings
@@ -371,7 +371,7 @@ module Hecks
         findings
       end
 
-      # `uses_framework` is a Shared Kernel relationship (X merges in, no boundary);
+      # `attaches` is a Shared Kernel relationship (X merges in, no boundary);
       # `across` is Customer/Supplier (real cross-Lambda RPC). This checks the choice
       # between them instead of leaving it as an unenforced comment. (ADR 0025)
       def cross_domain_policy_findings(policy, hecksagon, known_domains)
@@ -382,13 +382,13 @@ module Hecks
         target = policy.target_domain
         findings = []
 
-        if hecksagon.framework_members.include?(target)
+        if hecksagon.attaches?(target)
           # Shared Kernel and Customer/Supplier are mutually exclusive claims about
           # the same target — declaring both means either a pointless RPC to a
-          # domain already local, or a uses_framework that isn't doing its job.
+          # domain already local, or an attaches that isn't doing its job.
           findings << Finding.new(kind: :contradictory_relationship, severity: :error, subject: policy.name,
                                   message: "across #{target.inspect} dispatches over RPC (Customer/Supplier), " \
-                                           "but this hecksagon also uses_framework #{target.inspect} (Shared " \
+                                           "but this hecksagon also attaches #{target.inspect} (Shared " \
                                            "Kernel) — #{target} is already loaded in-process here, so the two " \
                                            "relationship declarations contradict each other for the same " \
                                            "target domain")
@@ -399,7 +399,7 @@ module Hecks
                                   message: "across #{target.inspect} declares a Customer/Supplier " \
                                            "relationship, but nothing in this hecksagon records the " \
                                            "expectation — add subscribe \"#{target}.SomeEvent\" for what " \
-                                           "you expect back from it, or uses_framework #{target.inspect} to " \
+                                           "you expect back from it, or attaches #{target.inspect} to " \
                                            "attach it in-process instead")
         end
 
@@ -426,7 +426,7 @@ module Hecks
         reached = []
         reached << "#{target} is a domain this corpus boots" if known_domains&.include?(target)
         if hecksagon
-          reached << "this hecksagon uses_framework #{target.inspect}" if hecksagon.framework_members.include?(target)
+          reached << "this hecksagon attaches #{target.inspect}" if hecksagon.attaches?(target)
           if hecksagon.subscriptions.any? { |subscribed| Naming.qualifier(subscribed) == target }
             reached << "this hecksagon subscribes to #{target}"
           end

data/lib/hecks/chapters.rb

@@ -1,11 +1,12 @@
 require_relative "naming"
+require_relative "framework"
 require_relative "runtime/registry"
 require_relative "bluebook/meta_validator"
 
 module Hecks
   # The chapters the gem carries that a hecksagon can attach by name (ADR 0080): the language
-  # declared in itself, Expression, Tenancy, Deploy and QualityControl. Framework members stay in
-  # `Framework`.
+  # declared in itself, Expression, Tenancy, Deploy, Site and QualityControl. Framework members stay
+  # in `Framework`; `table` and `attach!` find a name across both.
   #
   # A chapter is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
   # Beside its bluebook a chapter may carry what every hecksagon attaching it needs, whatever
@@ -14,7 +15,7 @@ module Hecks
   module Chapters
     # Where attachable chapters live, relative to `lib/hecks/`.
     GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
-               deploy/bluebook/*.bluebook quality_control/*.bluebook].freeze
+               deploy/bluebook/*.bluebook site/bluebook/*.bluebook quality_control/*.bluebook].freeze
 
     # Every attachable chapter, by name, with the files that declare it.
     #
@@ -26,6 +27,33 @@ module Hecks
                       .freeze
     end
 
+    # Every chapter the gem carries, whichever module loads it: the one lookup table `attaches`
+    # finds a name in.
+    #
+    # @return [Hash{String => Array<String>}] chapter name to its files' absolute paths, the
+    #   framework members (`Framework.members`) and the attachable chapters (`index`) together
+    def self.table
+      Framework.members.transform_values { |path| [path] }.merge(index)
+    end
+
+    # Loads one gem chapter by name, found in `table`: a framework member through
+    # `Framework.load!`, any other chapter through `load!`.
+    #
+    # @param name [String, Symbol] the chapter's name, such as `"Governance"` or `"Deploy"`
+    # @return [Boolean, nil] true when this call loaded it, nil when it was already held
+    # @raise [Runtime::WiringError] if the gem carries no chapter of that name; the message
+    #   lists the known names and says how to attach a vendored package
+    def self.attach!(name)
+      key = name.to_s
+      return Framework.load!(key) if Framework.members.key?(key)
+      return load!(key) if index.key?(key)
+
+      raise Runtime::WiringError,
+            "attaches #{name.inspect}: the gem carries no chapter of that name — known: " \
+            "#{table.keys.sort.join(', ')}. To attach a vendored package, write " \
+            "`attaches #{name.to_s.inspect}, from: :vendor`"
+    end
+
     # Loads a chapter's files into the current registry, unless it already holds the chapter.
     #
     # The files load together inside `MetaValidator.defer`, so a chapter spread over several files

data/lib/hecks/cli/check_era.rb

@@ -28,7 +28,7 @@ module Hecks
       # @raise [Errno::ENOENT, Errno::EACCES] if the file cannot be read
       # @raise [Runtime::EraCheck::ExpectedEra::Unreachable] if the host cannot be reached
       # @raise [Runtime::EraCheck::ExpectedEra::BadResponse] if it answers no era
-      def assess(url, file, timeout: 10)
+      def assess(url, file, timeout:)
         expected = Runtime::EraCheck::ExpectedEra
         allowed  = expected.parse(File.read(file))
         document = expected.fetch_version(url, timeout: timeout)

data/lib/hecks/cli/deploy_template_diff.rb

@@ -5,7 +5,7 @@ require_relative "../projections/deploy/template_diff"
 
 module Hecks
   module CLI
-    # The command behind `hecks deploy diff` and `hecks deploy diff`: compares two
+    # The command behind `hecks deploy template_comparison.diff`: compares two
     # CloudFormation templates offline and reports differences by logical id; `--strict` also
     # counts cosmetic differences (comments, key order).
     module DeployTemplateDiff

data/lib/hecks/cli/doc_coverage.rb

@@ -24,7 +24,7 @@ module Hecks
         return 0 if clean
 
         err.puts "docs/implemented/reference/ is behind the language. " \
-                 "Regenerate with hecks project_reference to see the words in place."
+                 "Regenerate with hecks language_run.project_reference to see the words in place."
         1
       end
     end

data/lib/hecks/cli/domain_stub.rb

@@ -0,0 +1,128 @@
+require_relative "../naming"
+
+module Hecks
+  module CLI
+    # The files `hecks init` writes: a stub domain that boots as it stands and that the author
+    # then edits into a real one (ADR 0087).
+    #
+    # Pure: it answers the text of each file and writes none, so the adapter that does the writing
+    # can check every target before it writes the first, and a spec can boot the result.
+    module DomainStub
+      # A domain's name: a capital, then letters and digits, as its bluebook spells it.
+      NAME = /\A[A-Z][A-Za-z0-9]*\z/
+
+      SQLITE_URL = 'default_database "data/%<snake>s.db"'.freeze
+      POSTGRES_URL = 'default_database "postgres://localhost/%<snake>s"'.freeze
+      private_constant :SQLITE_URL, :POSTGRES_URL
+
+      # Persistence adapters a stub can be bound to, each with the world lines that bind it, the
+      # data it keeps under `data/` (so a `.gitignore` is written), and whether it needs a server
+      # (so a memory overlay is written and the first run needs no database).
+      ADAPTERS = {
+        "Memory"            => { world: ['default_adapter "Memory"'], local_data: false, server: false },
+        "SqlitePersistence" => { world: ['default_adapter "SqlitePersistence"', SQLITE_URL],
+                                 local_data: true, server: false },
+        "Heki"              => { world: ['default_adapter "Heki"', 'persisted_by("Heki") { dir "data" }'],
+                    local_data: true, server: false },
+        "Postgres"          => { world: ['default_adapter "Postgres"', POSTGRES_URL],
+                        local_data: false, server: true },
+        "PostgresEra"       => { world: ['default_adapter "PostgresEra"', POSTGRES_URL],
+                           local_data: false, server: true }
+      }.freeze
+
+      # What `init` binds a stub to when no adapter is named: it needs no server and keeps its data.
+      DEFAULT_ADAPTER = "SqlitePersistence".freeze
+
+      module_function
+
+      # @return [Array<String>] the adapter names `init` accepts
+      def adapters = ADAPTERS.keys
+
+      # @param name [String] the domain's name, as its bluebook spells it (`Lending`)
+      # @param adapter [String, nil] an adapter named in `ADAPTERS`; the default when nil
+      # @return [Hash{String => String}] each file's path under the domain directory, and its text
+      # @raise [ArgumentError] when the name is not a capitalised word or the adapter is unknown
+      def files(name:, adapter: nil)
+        adapter ||= DEFAULT_ADAPTER
+        check!(name, adapter)
+        { "bluebook/#{Naming.snake(name)}.bluebook" => bluebook(name) }.merge(support_files(name: name, adapter: adapter))
+      end
+
+      # The files around a domain's bluebook: its world bound to the adapter, the memory overlay for
+      # an adapter that needs a server, and a `.gitignore` for one that keeps data. `hecks init`
+      # writes them beside a stub, and an interview draft beside the bluebook it renders (ADR 0088).
+      #
+      # @param name [String] the domain's name
+      # @param adapter [String, nil] an adapter named in `ADAPTERS`; the default when nil
+      # @return [Hash{String => String}] each file's path under the domain directory, and its text
+      # @raise [ArgumentError] when the name is not a capitalised word or the adapter is unknown
+      def support_files(name:, adapter: nil)
+        adapter ||= DEFAULT_ADAPTER
+        check!(name, adapter)
+        snake = Naming.snake(name)
+        files = { "bluebook/#{snake}.world" => world(name, snake, adapter) }
+        files["bluebook/environments/memory.world"] = overlay(name) if ADAPTERS.fetch(adapter).fetch(:server)
+        files[".gitignore"] = "data/\n" if ADAPTERS.fetch(adapter).fetch(:local_data)
+        files
+      end
+
+      # @param name [String] a domain name
+      # @return [String] the directory `init` writes into when none is named
+      def directory(name) = Naming.snake(name)
+
+      # @api private
+      def check!(name, adapter)
+        unless name.to_s.match?(NAME)
+          raise ArgumentError, "#{name.inspect} is not a domain name: a capital, then letters and digits (Lending)"
+        end
+        return if ADAPTERS.key?(adapter)
+
+        raise ArgumentError, "unknown adapter #{adapter.inspect}; choose one of #{adapters.join(', ')}"
+      end
+
+      # @api private
+      def bluebook(name)
+        <<~BLUEBOOK
+          Hecks.bluebook "#{name}" do
+            vision "TODO: say in one sentence what #{name} is for."
+            supporting
+
+            # TODO: rename Example to the main thing #{name} keeps track of.
+            aggregate "Example" do
+              description "TODO: describe what an Example is."
+
+              identified_by :name
+
+              attribute :name, ExampleName
+
+              value_object "ExampleName" do
+                attribute :value, String, pattern: '[^ \\t\\n\\r]'
+              end
+
+              # TODO: replace Create with the first thing that happens to an Example.
+              command "Create" do
+                goal "TODO: say what Create does"
+
+                attribute :name, ExampleName
+
+                emits "ExampleCreated"
+              end
+            end
+          end
+        BLUEBOOK
+      end
+
+      # @api private
+      def world(name, snake, adapter)
+        lines = ADAPTERS.fetch(adapter).fetch(:world).map { |line| "  #{format(line, snake: snake)}" }
+        note = adapter == "PostgresEra" ? "  # PostgresEra refuses a superuser role; use an ordinary one in the URL.\n" : ""
+        "Hecks.world \"#{name}\" do\n  realm \"#{name}\"\n#{note}#{lines.join("\n")}\nend\n"
+      end
+
+      # @api private
+      def overlay(name)
+        "Hecks.world \"#{name}\" do\n  default_adapter \"Memory\"\nend\n"
+      end
+    end
+  end
+end