hecks 2.6.0 → 2.8.0

data/lib/hecks/bluebook/hexagon.rb

@@ -97,9 +97,10 @@ module Hecks
       include Hecks::IR
       include Behaviour::World
 
-      emits_ir(domain: :domain, realm: :realm, latest: :latest, settings: :settings)
+      emits_ir(domain: :domain, realm: :realm, latest: :latest, settings: :settings,
+               default_database: :default_database, default_adapter: :default_adapter)
 
-      attr_reader :domain, :realm, :latest, :settings
+      attr_reader :domain, :realm, :latest, :settings, :default_database, :default_adapter
 
       # @param domain [String, Symbol] the domain this world configures
       # @param realm [String, Symbol, nil] the declared realm/version marker, or `nil`
@@ -108,11 +109,18 @@ module Hecks
       #   if none is declared
       # @param settings [Hash] the declared adapter bind settings, keyed by verb and,
       #   for a qualified entry, `"verb:adapter"`
-      def initialize(domain:, realm: nil, latest: nil, settings: {})
-        @domain   = domain.to_s
-        @realm    = realm&.to_s
-        @latest   = latest&.to_s
-        @settings = settings
+      # @param default_database [String, nil] the connection every chapter's
+      #   database-taking persistence adapter uses unless its own settings name one,
+      #   or `nil` if none is declared
+      # @param default_adapter [String, nil] the persistence adapter every aggregate
+      #   binds to unless its chapter's hecksagon binds it, or `nil` if none is declared
+      def initialize(domain:, realm: nil, latest: nil, settings: {}, default_database: nil, default_adapter: nil)
+        @domain           = domain.to_s
+        @realm            = realm&.to_s
+        @latest           = latest&.to_s
+        @settings         = settings
+        @default_database = default_database&.to_s
+        @default_adapter  = default_adapter&.to_s
       end
     end
   end

data/lib/hecks/bluebook/meta_validator/judge.rb

@@ -302,7 +302,7 @@ module Hecks
         end
 
         # Entity-owned categories have no top-level aggregate for the runtime
-        # to route a bare verb into any more — `Member`'s own "Pair" reaches
+        # to route a bare verb into — `Member`'s own "Pair" reaches
         # the runtime as `ValueObject.Member.Pair`, and a nested one
         # (`Dispatch`, inside `Handler`) reaches it as `ProcessManager.
         # Handler.Dispatch.Bind` — the dotted shape `EntityInterpreter#call`
@@ -567,8 +567,8 @@ module Hecks
         #   Reference  its type is Reference<X>, another aggregate's head
         #   Holds      its type names an entity this aggregate declares
         #
-        # Nothing is skipped any more. Reference and Holds did not exist, so the
-        # walk dropped both kinds and the meta-domain silently did not contain
+        # Nothing is skipped. Without Reference and Holds the walk would drop
+        # both kinds and the meta-domain would silently not contain
         # Account#customer_id or Account#ledger.
         # Each alternate carries its own map, read from the language. Borrowing the
         # primary's map dispatched `type:` where Reference declares `points_at:`,

data/lib/hecks/bluebook/meta_validator/plan.rb

@@ -108,7 +108,7 @@ module Hecks
             # S17, ADR 0026 — Member/Handler/Dispatch are entities now
             # (`entity "Member" do ... end`, nested under `ValueObject`/
             # `ProcessManager`/`Handler`), not their own top-level
-            # aggregates — so `meta.aggregates` alone no longer finds
+            # aggregates — so `meta.aggregates` alone does not find
             # them the way it always found a standalone `aggregate
             # "Member"`. Each still needs its own named category here:
             # `Assembly::Contracts` keeps a bespoke entry for each
@@ -125,8 +125,8 @@ module Hecks
             # itself ever declares are exactly the three this ADR
             # names. `entity_owned: true` records why this is a
             # category at all — the real runtime has no top-level
-            # aggregate named "Member" to dispatch a bare verb into
-            # any more, so the judge has to build a dotted one instead
+            # aggregate named "Member" to dispatch a bare verb into,
+            # so the judge has to build a dotted one instead
             # (see `Judge#verb_for`).
             #
             # Recurses — `Dispatch` nests inside `Handler`, which nests
@@ -158,7 +158,7 @@ module Hecks
         # Every verb the language declares, spelled as the judge would
         # dispatch it. S17, ADR 0026 — an entity-owned category (its
         # own `entity_owned` flag) has no real top-level aggregate the
-        # runtime can route a bare verb into any more, so it is
+        # runtime can route a bare verb into, so it is
         # spelled dotted here too — `Bluebook::ValueObject.Member.
         # Declare`, `Bluebook::ProcessManager.Handler.Dispatch.Bind` —
         # matching `Judge#verb_for`/`#dotted_prefix`'s own build

data/lib/hecks/bluebook/meta_validator/readings.rb

@@ -364,7 +364,7 @@ module Hecks
           # same way Shapes#provenance reads it back.
           return encode_literal(node.provenance) if field == :provenance
 
-          # `identified_by` is no longer a field of any declaration — it is a list,
+          # `identified_by` is not a field of any declaration — it is a list,
           # filled by Identify one part at a time, so it is read through `identity_rows`
           # like every other list rather than special-cased here. What this branch
           # existed to protect is now structural : a path cannot come back as its head,

data/lib/hecks/bluebook/meta_validator/reconstruction.rb

@@ -228,7 +228,7 @@ module Hecks
         # by its own dotted `ValueObject.Member.Pair`. Its data therefore
         # lives inline on the value object's own dispatched state — same as
         # any other entity list — not behind a separate `DeclaredIn` query:
-        # there is no such query any more, because there is no top-level
+        # there is no such query, because there is no top-level
         # "Member" aggregate left to hold one. Pairs are still an open map,
         # which no value object can hold, so they still come back one pair
         # at a time.
@@ -330,7 +330,7 @@ module Hecks
         # Handler.Dispatch`/`...Dispatch.Bind`. Its data therefore lives
         # inline on the process manager's own dispatched state — same as
         # any other entity list — not behind a separate `DeclaredIn`
-        # query : there is no such query any more, the same fix
+        # query : there is no such query, the same fix
         # `Reconstruction#members_of` already made for Member.
         def process_manager(row)
           declaration("ProcessManager", row,

data/lib/hecks/bluebook/meta_validator/shapes.rb

@@ -32,7 +32,7 @@ module Hecks
             default:      decode_literal(text(field[:default])),
             # Read back the same way `list` is — both are booleans about the
             # attribute, held as text, and dropping either would rebuild a
-            # bluebook that no longer says what it said.
+            # bluebook that says something other than what was written.
             optional:     text(field[:optional]).to_s == "true",
             pattern:      presence(text(field[:pattern])),
             # The round trip is the only way in. The grammar registry keeps the

data/lib/hecks/bluebook/meta_validator/syntax_boot.rb

@@ -1,5 +1,6 @@
 require "digest"
 require "fileutils"
+require_relative "../../cache_dir"
 
 module Hecks
   module Bluebook
@@ -145,13 +146,10 @@ module Hecks
         #
         # Fails toward a real boot, never toward a wrong table — same
         # loud-not-silent discipline this codebase already holds CI to
-        # (`postgres_io_relevant_changed`'s own header). A missing file, a
-        # corrupt Marshal blob, a permission error, an unwritable `tmp/` —
-        # every one of these degrades to "no disk cache today", never to a
-        # crash or a served-but-wrong table. `tmp/` is already gitignored
-        # for exactly this kind of local, disposable-but-useful-while-it-
-        # lasts artifact (`Storehouse::LOG_ROOT`'s own header names the
-        # same convention).
+        # (`postgres_io_relevant_changed`'s own header). A missing file, a corrupt
+        # Marshal blob, a permission error or an unwritable cache directory degrades
+        # to "no disk cache today", never to a crash or a served-but-wrong table.
+        # The cache lives under `Hecks::CacheDir`, never the gem's read-only directory.
         #
         # **Atomic write, not a lock** — `qa_sweep --all` spawns up to 4
         # children at once, any of which could reach a cold cache
@@ -166,7 +164,10 @@ module Hecks
         # change, the same shape `Storehouse::BOOT_ROOT`'s own
         # `HECKS_STOREHOUSE_ROOT` override uses, for the day this needs to
         # be ruled out while debugging something else entirely.
-        CACHE_DIR = File.expand_path("../../../../tmp/hecks_syntax_boot_cache", __dir__).freeze
+        #
+        # @return [String] the directory cache entries are written to:
+        #   `hecks_syntax_boot_cache` under `Hecks::CacheDir`
+        def cache_dir = Hecks::CacheDir.path("hecks_syntax_boot_cache")
 
         # Reports whether the cross-process disk cache is turned on.
         #
@@ -203,7 +204,7 @@ module Hecks
           return unless disk_cache_enabled?
 
           path = disk_cache_path(chapters)
-          FileUtils.mkdir_p(CACHE_DIR)
+          FileUtils.mkdir_p(cache_dir)
           tmp_path = "#{path}.#{Process.pid}.tmp"
           File.binwrite(tmp_path, Marshal.dump(result))
           File.rename(tmp_path, path)
@@ -217,7 +218,7 @@ module Hecks
         #   chapter]` pairs to key the cache entry on
         # @return [String] the disk cache file path for `chapters`
         def disk_cache_path(chapters)
-          File.join(CACHE_DIR, "#{disk_cache_key(chapters)}.marshal")
+          File.join(cache_dir, "#{disk_cache_key(chapters)}.marshal")
         end
 
         # Builds the cache key for `chapters`.

data/lib/hecks/bluebook/meta_validator/world_judge.rb

@@ -40,7 +40,9 @@ module Hecks
         def judge!
           domain = @world.domain
           send_to("World::World.Declare", domain, domain: v(domain),
-                  realm: v(@world.realm), latest: v(@world.latest))
+                  realm: v(@world.realm), latest: v(@world.latest),
+                  default_database: v(@world.default_database),
+                  default_adapter: v(@world.default_adapter))
 
           Hash(@world.settings).each do |verb, values|
             # the DSL records each binding twice — once by verb, once by

data/lib/hecks/bluebook/meta_validator.rb

@@ -541,7 +541,7 @@ module Hecks
       # every Paging-attached word (limit/offset/cursor/nulls) because
       # something called it inside this exact window.
       #
-      # SyntaxBoot.call no longer uses this. Gating its cache on "the
+      # SyntaxBoot.call does not use this. Gating its cache on "the
       # whole registry is finished" meant nothing was cached for the
       # entire window, and the window is not narrow — every word routed
       # through `word_gate_dispatch` while the language judged itself

data/lib/hecks/bluebook/model_check/client_profile.rb

@@ -15,60 +15,29 @@ module Hecks
       #
       # ## The rules
       #
-      # - `:client_group_by_row_drop` — a `group_by` whose fields do not include
-      #   the grouped aggregate's whole identity. Rows sharing a key path are
-      #   collapsed to the first, on every adapter (docs/decisions/0061).
       # - `:client_native_read_model` — a read model the SQLite projection
       #   answers natively, where every other path answers it in process
       #   (docs/1.0-readiness.md, "Known gaps at 1.0", item 2).
-      # - `:client_dotted_compute_source` — an era translation `compute` whose
-      #   source is a dotted path, which never fires
-      #   (`Translation::RuleCompiler.compile_compute`).
       module ClientProfile
         # Adapters whose Ruby class implements `query_read_model`, which is what
         # makes `ReadModelInterpreter#project` take the native path. The spec
         # checks this list against the adapter classes themselves.
         NATIVE_READ_MODEL_ADAPTERS = %w[SqliteProjection].freeze
 
-        GROUP_BY_TRACKER = "docs/decisions/0061-query-dsl-aggregation-count-sum-group-by.md".freeze
         NATIVE_READ_MODEL_TRACKER = "docs/1.0-readiness.md (Known gaps at 1.0, item 2)".freeze
-        DOTTED_COMPUTE_TRACKER = "Translation::RuleCompiler.compile_compute, and the pending example " \
-                                 "\"applies the SQL of a compute whose source is a dotted member\" in " \
-                                 "spec/adapters/driven/postgres_era/migration_data_safety_spec.rb".freeze
 
         module_function
 
-        # Runs every client-profile rule over one chapter and its translations.
+        # Runs every client-profile rule over one chapter.
         #
         # @param bluebook [Bluebook::Chapter] the assembled chapter to check
         # @param hecksagon [Bluebook::Hecksagon, nil] the chapter's sibling wiring file; without
         #   one no aggregate is projected, so the native-read-model rule has nothing to find
-        # @param translations [Array<Bluebook::Translation>] the data translations declared for
-        #   this chapter's domain
         # @return [Array<ModelCheck::Finding>] one error-severity finding per construct refused
-        def call(bluebook, hecksagon: nil, translations: [])
+        def call(bluebook, hecksagon: nil)
           bluebook.read_models.flat_map do |model|
-            group_by_findings(bluebook, model) + native_read_model_findings(model, hecksagon)
-          end + dotted_compute_findings(translations)
-        end
-
-        # Refuses a `group_by` that cannot prove each of its key paths names one row.
-        #
-        # The interpreter's `nest` keeps `stripped.first` per key path, whichever adapter
-        # supplied the rows, because a `group_by` model never reaches the native path. Grouping
-        # by the aggregate's whole identity is the one shape that cannot collide.
-        #
-        # @param bluebook [Bluebook::Chapter] the chapter the read model is declared in
-        # @param model [Bluebook::ReadModel] the read model to inspect
-        # @return [Array<ModelCheck::Finding>] one finding, or `[]` when `model` declares no
-        #   `group_by` or groups by its aggregate's whole identity
-        def group_by_findings(bluebook, model)
-          return [] if model.group_by.empty? || groups_by_identity?(bluebook, model)
-
-          [finding(:client_group_by_row_drop, model.name,
-                   "group_by #{model.group_by_fields.map(&:inspect).join(', ')} does not cover the grouped " \
-                   "aggregate's whole identity, so rows sharing a key path are silently reduced to the " \
-                   "first. Tracked in #{GROUP_BY_TRACKER}.")]
+            native_read_model_findings(model, hecksagon)
+          end
         end
 
         # Refuses a read model that the SQLite projection would answer natively.
@@ -95,26 +64,6 @@ module Hecks
                    "is not, and nothing checks the two agree. Tracked in #{NATIVE_READ_MODEL_TRACKER}.")]
         end
 
-        # Refuses a translation `compute` whose source names a member of a value object.
-        #
-        # `compile_compute` guards the compute with `__s ? '<from>'`, a top-level key test, so a
-        # dotted source never matches, the mint succeeds and the record keeps its old value.
-        #
-        # @param translations [Array<Bluebook::Translation>] the translations to inspect
-        # @return [Array<ModelCheck::Finding>] one finding per dotted-source compute
-        def dotted_compute_findings(translations)
-          translations.flat_map do |translation|
-            translation.aggregates.flat_map do |aggregate|
-              aggregate.computes.select { |compute| compute.from.to_s.include?(".") }.map do |compute|
-                finding(:client_dotted_compute_source, "#{translation.domain}::#{aggregate.name}",
-                        "compute #{compute.from.to_s.inspect} has a dotted source, which the compiled SQL " \
-                        "never matches, so the mint succeeds and leaves the old value in place. " \
-                        "Tracked in #{DOTTED_COMPUTE_TRACKER}.")
-              end
-            end
-          end
-        end
-
         # Reports whether a model's shape sends it down the native path in `#project`.
         #
         # @param model [Bluebook::ReadModel] the read model to inspect
@@ -123,21 +72,6 @@ module Hecks
           !model.reference_target.nil? && model.group_by.empty? && !model.count? && !model.median_field
         end
 
-        # Reports whether a `group_by` names every identity path of the aggregate it groups.
-        #
-        # @param bluebook [Bluebook::Chapter] the chapter the read model is declared in
-        # @param model [Bluebook::ReadModel] a read model that declares a `group_by`
-        # @return [Boolean] false when the many-side aggregate is not a top-level aggregate or
-        #   declares no identity, since uniqueness cannot then be shown
-        def groups_by_identity?(bluebook, model)
-          target = model.aggregate_heads.find { |head| head[:many] }
-          aggregate = target && bluebook.aggregate(target[:aggregate])
-          return false unless aggregate
-
-          identity = Array(aggregate.identity_heads).map(&:to_sym)
-          !identity.empty? && (identity - model.group_by_fields.map(&:to_sym)).empty?
-        end
-
         # Builds one error-severity finding of this profile.
         #
         # @param kind [Symbol] the finding's kind, one of the `:client_*` rules above

data/lib/hecks/bluebook/model_check.rb

@@ -25,7 +25,7 @@ module Hecks
       # **A finding shipped, not silenced** — the coverage-gate idiom, empty
       # allowlists enforced both directions (spec/model_check_spec.rb holds
       # this exact table: an error the checker reports and this does not
-      # name is a regression, an entry the checker no longer reports is
+      # name is a regression, an entry the checker does not report is
       # stale and must be deleted). bin/model_check reads this same
       # constant, so the tool and the spec can never drift apart.
       #
@@ -44,9 +44,9 @@ module Hecks
       # was a `state "x"` line never named by any handler's own from:/to:, a
       # pure declaration-drift artifact. States are derived from the
       # transitions that name them now (ProcessManagerBuilder#derived_
-      # states), so a state nothing ever transitions into or out of no
-      # longer exists to be unreachable — the finding that entry allowlisted
-      # cannot occur any more, by construction.
+      # states), so a state nothing ever transitions into or out of does
+      # not exist to be unreachable — the finding that entry allowlisted
+      # cannot occur, by construction.
       #
       # "banking"/NotifyOnClosure, FlagKeyReturn — gone from here, moved
       # to banking. `across "Notifications"` names a domain that does not
@@ -145,15 +145,11 @@ module Hecks
       #   findings for constructs known to answer wrongly without refusing;
       #   `nil` (the default) adds nothing and leaves every other finding as
       #   it was
-      # @param translations [Array<Bluebook::Translation>] the data
-      #   translations declared for this chapter's domain, read only by the
-      #   `:client` profile — they live on the registry, not the chapter, so
-      #   the caller supplies them the way it supplies `hecksagon`
       # @return [Array<Finding>] every finding this bluebook triggers,
       #   across its lifecycles, sagas, policies, and Rust-reserved names
       # @raise [ArgumentError] if `profile` is neither `nil` nor `:client`
       def call(bluebook, hecksagon: nil, known_domains: nil, global_emitted_events: nil, rust_target: false, strict: false,
-               profile: nil, translations: [])
+               profile: nil)
         unless profile.nil? || PROFILES.include?(profile)
           raise ArgumentError, "unknown profile #{profile.inspect} (known: #{PROFILES.inspect})"
         end
@@ -170,7 +166,7 @@ module Hecks
         findings.concat(rust_reserved_name_findings(domain_name: bluebook.name,
                                                     aggregate_names: bluebook.aggregates.map(&:hecks_name),
                                                     rust_target: rust_target, strict: strict))
-        findings.concat(ClientProfile.call(bluebook, hecksagon: hecksagon, translations: translations)) if profile == :client
+        findings.concat(ClientProfile.call(bluebook, hecksagon: hecksagon)) if profile == :client
         findings
       end
 
@@ -659,6 +655,9 @@ module Hecks
       #   sibling wiring file, if the caller loaded one
       # @param known_domains [Set<String>, nil] every bluebook/hecksagon
       #   name the caller has booted anywhere in this corpus scan
+      # @param global_emitted_events [Set<String>, nil] every event name emitted anywhere in the
+      #   corpus, consulted only as a fallback for a `translates` reaction; nil when the caller
+      #   has no cross-domain set to offer
       # @return [Array<Finding>] every `deaf_policy`/`unknown_trigger`
       #   finding this policy triggers, or `cross_domain_policy_findings`'s
       #   own return for a cross-domain policy
@@ -680,12 +679,12 @@ module Hecks
         # (`across "Compliance"`), which exits this method one line above
         # before the mismatch is ever reached.
         # `global_emitted_events` — a `translates` (hecksagon-level)
-        # reaction is BUILT as the exact same same-domain-target `Policy`
+        # reaction is built as the exact same same-domain-target `Policy`
         # an ordinary `policy` block is (no `target_domain`, so it never
         # reaches `cross_domain_policy_findings` above), but its whole
-        # point is to react to a FOREIGN domain's own event — this
+        # point is to react to a foreign domain's own event — this
         # domain's own `emitted_events(bluebook)` was never going to
-        # contain it. Checked only as a FALLBACK, after the local check
+        # contain it. Checked only as a fallback, after the local check
         # already failed, so a real same-domain typo still gets flagged
         # exactly as before whenever the caller has no cross-domain set
         # to offer (nil — every existing call site, unchanged) or the
@@ -793,7 +792,7 @@ module Hecks
 
         # **Typo detection, deliberately weaker** — `known_domains` can only
         # ever be a monorepo-scoped heuristic: a real external hecks
-        # consumer's own domain (this repo's own embryonaut/lifeadelics-
+        # consumer's own domain (this repo's own embryonaut client-
         # shaped case) lives in a genuinely separate repository this
         # corpus scan can never see, so a target this check cannot find
         # is "unknown to THIS corpus," never proof of a typo. A target

data/lib/hecks/cache_dir.rb

@@ -0,0 +1,103 @@
+require "etc"
+require "fileutils"
+require "tmpdir"
+
+module Hecks
+  # The one place the runtime's own scratch files live, outside the gem.
+  #
+  # The syntax-boot cache and the Storehouse audit log are written on a
+  # normal run, so they cannot sit under the gem's own directory: an
+  # installed gem is read-only, and a checkout's `tmp/` is not a place a
+  # library gets to assume. Both ask this module for a subdirectory instead.
+  #
+  # ## Where the root is
+  #
+  # The first of these that can be made a private directory wins:
+  #
+  # 1. `$XDG_CACHE_HOME/hecks`, when `XDG_CACHE_HOME` is set to an absolute path
+  # 2. `~/.cache/hecks`
+  # 3. `<system temp dir>/hecks-<uid>`
+  #
+  # ## Private, or not used
+  #
+  # The syntax-boot cache is read back with `Marshal.load`, so a directory
+  # another account can write to is a way to run code as this one. A
+  # candidate is accepted only if it is owned by the current user and
+  # writable by nobody else; the shared temp directory in particular is
+  # where a predictable name can be planted by someone else. When no candidate
+  # qualifies, a fresh per-process directory stands in: the cache still
+  # works within the process and is never shared with a stranger.
+  module CacheDir
+    module_function
+
+    # The directory a named piece of scratch state lives in.
+    #
+    # @param name [String] the subdirectory, such as `"storehouse"`
+    # @return [String] the absolute path of `name` under the cache root; the
+    #   directory itself is created by whoever writes to it
+    def path(name)
+      File.join(root, name)
+    end
+
+    # The cache root, resolved once per process.
+    #
+    # @return [String] the absolute path of the directory every `path` lives under
+    def root
+      @root ||= resolve
+    end
+
+    # Forgets the resolved root so the next call resolves again.
+    #
+    # @return [void]
+    def reset!
+      @root = nil
+    end
+
+    # Picks the cache root from the environment.
+    #
+    # @param env [Hash{String => String}] the environment to read
+    #   `XDG_CACHE_HOME` and `HOME` from
+    # @param tmpdir [String] the system temp directory
+    # @param uid [Integer] the current user id, used in the temp fallback's name
+    # @return [String] the absolute path of the first candidate that is a
+    #   private directory owned by this user, else a per-process directory
+    def resolve(env: ENV, tmpdir: Dir.tmpdir, uid: Process.uid)
+      candidates(env, tmpdir, uid).each do |candidate|
+        return candidate if private_dir?(candidate)
+      end
+      Dir.mktmpdir("hecks-", tmpdir)
+    rescue StandardError
+      File.join(tmpdir, "hecks-#{uid}")
+    end
+
+    # The roots to try, most preferred first.
+    #
+    # @param env [Hash{String => String}] the environment
+    # @param tmpdir [String] the system temp directory
+    # @param uid [Integer] the current user id
+    # @return [Array<String>] absolute candidate paths
+    def candidates(env, tmpdir, uid)
+      xdg  = env["XDG_CACHE_HOME"].to_s
+      home = env["HOME"].to_s
+      list = []
+      list << File.join(xdg, "hecks") if File.absolute_path?(xdg)
+      list << File.join(home, ".cache", "hecks") if File.absolute_path?(home)
+      list << File.join(tmpdir, "hecks-#{uid}")
+    end
+    private_class_method :candidates
+
+    # Creates `dir` if needed and says whether it is private to this user.
+    #
+    # @param dir [String] the candidate directory
+    # @return [Boolean] true when `dir` is a directory owned by this user that
+    #   no other user can write to; false on any failure
+    def private_dir?(dir)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      stat = File.stat(dir)
+      stat.directory? && stat.owned? && stat.mode.nobits?(0o022) && File.writable?(dir)
+    rescue StandardError
+      false
+    end
+    private_class_method :private_dir?
+  end
+end

data/lib/hecks/cli/document.rb

@@ -0,0 +1,104 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/docs`, `bin/narrate`, `hecks docs` and `hecks narrate`:
+    # one domain's document, projected from its own bluebook, to stdout.
+    #
+    # `:docs` answers the usage document a console's `<Domain>.docs` prints; `:narrate`
+    # answers the same chapter read back in English, for the subject-matter expert
+    # (`Projector::NarrateProjector`). Nothing is written for the caller: redirect it,
+    # so the caller decides where a generated file lands and git decides whether it
+    # drifted.
+    #
+    # ## Every failure is a sentence
+    #
+    # A misspelled aggregate refuses by name rather than printing nothing and exiting
+    # 0. A caller cannot tell an empty document from an empty domain, so this refuses
+    # instead and names what is actually there.
+    #
+    # ## Standing in a domain is enough
+    #
+    # `Adapters::Folder#domain_root` walks up for the nearest `.hecksagon`, which makes
+    # the first argument ambiguous. The rule: a directory is a domain, anything else
+    # is an aggregate name, and the two-argument form says which is which.
+    module Document
+      # Build output and other trees under a root that hold no domain a caller means.
+      # Matched against the path relative to the root, because a substring test
+      # against an absolute path tests wherever somebody happened to clone.
+      IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
+
+      module_function
+
+      # Prints `projection` for the domain and optional aggregate `argv` names.
+      #
+      # @param argv [Array<String>] an optional domain directory, then an optional
+      #   aggregate name
+      # @param projection [Symbol] `:docs` or `:narrate`
+      # @param program [String] the name the usage message calls this command by
+      # @param root [String] the directory whose domains are listed when no domain
+      #   is found
+      # @return [void]
+      # @raise [SystemExit] when no domain is found, it cannot boot, it loads no
+      #   bluebook, or the aggregate does not exist
+      def call(argv, projection:, program:, root:)
+        here = Adapters::Folder.new.domain_root
+        path, aggregate = target(argv, here)
+        refuse_without_domain(program, root) unless path
+
+        begin
+          runtime = Hecks.boot(path, install_facade: false)
+        rescue StandardError => e
+          abort "cannot read #{path}: #{e.message.lines.first.strip}"
+        end
+
+        # The domain's own chapter, not a framework member it attached: insertion
+        # order, the same distinction `Runtime::Loader.dispatcher_for` draws.
+        bluebook = runtime.registry.bluebooks.values.first
+        abort "#{path} loaded no bluebook" unless bluebook
+
+        begin
+          puts Projector.call(projection, bluebook: bluebook, options: aggregate ? { aggregate: aggregate } : {})
+        rescue Runtime::NotFound => e
+          abort e.message
+        end
+      end
+
+      # Lists every directory under `root` that `Hecks.boot` would accept.
+      #
+      # Found by their wiring, not their chapters: a `.hecksagon` is what says "this
+      # is a domain, and here is how its aggregates are stored", while most
+      # `.bluebook` files (era translations, the language's own grammar,
+      # `spec/fixtures`) are not domains anybody boots.
+      #
+      # @param root [String] the directory to search under
+      # @return [Array<String>] domain directory paths relative to `root`,
+      #   deduplicated and sorted
+      def domains(root)
+        Dir.glob(File.join(root, "**/*.hecksagon"))
+           .map    { |path| File.basename(File.dirname(path)) == "bluebook" ? File.dirname(path, 2) : File.dirname(path) }
+           .map    { |path| path.delete_prefix("#{root}/") }
+           .grep_v(IGNORED)
+           .uniq.sort
+      end
+
+      # @api private
+      def target(argv, here)
+        if argv.empty?              then [here, nil]
+        elsif argv.length > 1       then [argv[0], argv[1]]
+        elsif File.directory?(argv[0]) then [argv[0], nil]
+        else [here, argv[0]]
+        end
+      end
+
+      # @api private
+      def refuse_without_domain(program, root)
+        warn "usage: #{program} [domain-path] [aggregate]"
+        warn ""
+        warn "No bluebook here — #{Dir.pwd} is not inside a domain. Name one:"
+        domains(root).each { |candidate| warn "  #{candidate}" }
+        exit 1
+      end
+    end
+  end
+end

data/lib/hecks/cli/ir.rb

@@ -0,0 +1,47 @@
+require_relative "../../hecks"
+# ADR 0033 — a domain wired to PostgresEra needs this plugin loaded
+# explicitly; the era/lineage subsystem does not load with core.
+require_relative "../ports/persistence/plugins/era"
+
+module Hecks
+  module CLI
+    # The command behind `bin/ir` and `hecks ir`: a booted domain's IR as JSON, the
+    # same `to_h` the golden specs pin and `StorageShape` hashes into an era, for
+    # reading rather than asserting on.
+    module Ir
+      module_function
+
+      # Prints the IR `argv` asks for.
+      #
+      # `--meta` prints the language's own IR, the chapters under
+      # `lib/hecks/language/bluebook/` merged into one. It is reached through
+      # `Bluebook::MetaValidator.grammar_registry`, the real boot sequence, so it
+      # cannot drift from what `MetaValidator` itself loads.
+      #
+      # @param argv [Array<String>] a domain path and `--translations`, or `--meta`
+      # @param program [String] the name the usage message calls this command by
+      # @param default_domain [String, nil] the domain booted when `argv` names none;
+      #   nil makes a domain argument required
+      # @return [void]
+      # @raise [SystemExit] when no domain is named and there is no default
+      def call(argv, program:, default_domain: nil)
+        argv = argv.dup
+        if argv.delete("--meta")
+          require_relative "../bluebook/meta_validator"
+          puts Projector::Exporter.json(Bluebook::MetaValidator.grammar_registry)
+          return
+        end
+
+        translations_only = argv.delete("--translations")
+        domain = argv.shift || default_domain or abort "usage: #{program} <domain> [--translations] | #{program} --meta"
+        runtime = Hecks.boot(domain)
+
+        if translations_only
+          puts Projector::Exporter.translations_json(runtime.registry)
+        else
+          puts Projector::Exporter.json(runtime.registry)
+        end
+      end
+    end
+  end
+end