hecks 2.6.0 → 2.8.0

data/lib/hecks/embryonaut_bluebook.rb

@@ -13,10 +13,10 @@ module Hecks
   #
   # This module and its `uses_embryonaut_bluebook`
   # DSL word (hecksagon_builder.rb) were built on a prior commit of this
-  # repo (933d1dd), vendored out to a real consumer (lifeadelics/domain,
+  # repo (933d1dd), vendored out to a real consumer (a client site's domain,
   # for embryonaut_bluebooks/payments), and then lost from this repo's own
   # reachable history — a hard reset or rebase left no branch containing
-  # that commit. The lifeadelics vendor snapshot (a `git archive` of that
+  # that commit. The consumer's vendor snapshot (a `git archive` of that
   # commit, committed into their repo) was the only surviving copy; this
   # file is ported forward from it, checked against current `main`'s own
   # conventions rather than copied wholesale, since the two trees had
@@ -64,7 +64,18 @@ module Hecks
   # => "Payments"), not a separate ledger. A vendored package's directory
   # name and its declared `Hecks.bluebook` name are the one convention
   # this reuses from Framework rather than reinventing.
+  #
+  # ## Vendoring
+  #
+  # `vendor!` is the other direction: it pins a package from a local checkout
+  # of the registry into a consuming project's own `vendor/` tree, and is the
+  # one implementation behind `bin/vendor_bluebook` (see Vendoring and Vendor).
   module EmbryonautBluebook
+    autoload :Lock, File.join(__dir__, "embryonaut_bluebook/lock")
+    autoload :Shape, File.join(__dir__, "embryonaut_bluebook/shape")
+    autoload :Vendor, File.join(__dir__, "embryonaut_bluebook/vendor")
+    autoload :VendorCli, File.join(__dir__, "embryonaut_bluebook/vendor_cli")
+
     # Loads a vendored embryonaut bluebook package's `.bluebook` files, once
     # per registry.
     #
@@ -89,10 +100,25 @@ module Hecks
       if files.empty?
         raise Runtime::WiringError,
               "no vendored embryonaut bluebook named #{name.inspect} at #{dir} — " \
-              "run bin/vendor_embryonaut_bluebooks #{name}"
+              "vendor it with bin/vendor_bluebook #{name}"
       end
 
       files.each { |file| Kernel.load(file) }
     end
+
+    # Pins one package of the registry into a project's `vendor/` tree.
+    #
+    # @param name [String, Symbol] the package's directory name, such as `"payments"`
+    # @param from [String] path of a local checkout of the registry repository
+    # @param ref [String, nil] a release version (`"1.2.0"`), a release tag name, any
+    #   commit-ish, or nil for the newest release
+    # @param root [String] the consuming project's root
+    # @param allow_downgrade [Boolean] whether a release older than the vendored one is allowed
+    # @return [Vendor::Result] the commit, version and storage shape now vendored
+    # @raise [Vendoring::Error] if the source, release or files are unusable, or a
+    #   version-policy refusal applies (see Vendor)
+    def self.vendor!(name, from:, root:, ref: nil, allow_downgrade: false)
+      Vendor.new(name, from: from, root: root, ref: ref, allow_downgrade: allow_downgrade).call
+    end
   end
 end

data/lib/hecks/facade/handle.rb

@@ -142,14 +142,14 @@ module Hecks
       # privacy.bluebook): a marking's presence is what makes a read
       # redacted, not a separate flag this class carries itself.
       #
-      # ALWAYS THE STRONG CHECK, never the weak string-only fallback
+      # Always the strong check, never the weak string-only fallback
       # `CommandRules::Authorization#refuse_role_mismatch` allows an
       # unidentified caller — a read gate gone wrong is a leak, not a
       # refused command, so an ambient caller with no `actor_id` (or no
       # caller at all) is masked here, full stop, rather than waved
       # through the way a self-asserted `role` string is for a command.
       #
-      # ONE LEVEL OF NESTING ONLY — `attendee.medications` masks inside
+      # One level of nesting only — `attendee.medications` masks inside
       # the returned `Runtime::Value` via its own `#with`; a marking two
       # levels deep is not supported and is left unmasked rather than
       # silently mishandled, since nothing in this corpus needs it yet.

data/lib/hecks/facade/surface/aggregate_door.rb

@@ -165,7 +165,7 @@ module Hecks
           end
 
           door.define_singleton_method(:method_missing) do |verb, *args, **kwargs, &block|
-            # A BARE CALL starts a Privacy marking chain — see
+            # A bare call starts a Privacy marking chain — see
             # `Bluebook::DSL::BindingProxy#method_missing`'s own header;
             # this is the same mechanism, reached when the constant is
             # already a real, installed door (a second boot in-process)

data/lib/hecks/forms/value_object_shape.rb

@@ -2,7 +2,7 @@ module Hecks
   module Forms
     # The value-object classification every consumer of a resolved VO
     # shape needs, spelled once — `field_shape.rb` (a command's own
-    # form), `ui_schema.rb` (embryonaut_console's table/detail-panel
+    # form), `ui_schema.rb` (the console app's table/detail-panel
     # renderer, a separate app, not this repo), and
     # `adapters/driven/sql_query_builder.rb` (a query's own ORDER BY/
     # where compiler) each grew their own copy of "is this VO money-

data/lib/hecks/framework/bluebook/console_settings.bluebook

@@ -1,5 +1,5 @@
 Hecks.bluebook "ConsoleSettings" do
-  vision "A generic admin console's own curated UI facts — nav, columns, state tones, which rows a detail panel shows — as real dispatched data instead of a hand-rewritten YAML file. A UI opinion the DOMAIN it's pointed at has no way to answer, never a business record; see embryonaut_console's own presentation_config.rb for the fuller story."
+  vision "A generic admin console's own curated UI facts — nav, columns, state tones, which rows a detail panel shows — as real dispatched data instead of a hand-rewritten YAML file. A UI opinion the DOMAIN it's pointed at has no way to answer, never a business record; see the console app's own presentation_config.rb for the fuller story."
   supporting
 
   # A FRAMEWORK MEMBER LIKE IDENTITY/GOVERNANCE — attach with
@@ -7,7 +7,7 @@ Hecks.bluebook "ConsoleSettings" do
   # `.hecksagon`, plus a `Hecks.hecksagon "ConsoleSettings" do ... end`
   # persistence binding (Heki is the common case — a small, local,
   # per-app settings store, no shared database needed). This used to
-  # boot in a SECOND, independent registry (embryonaut_console's own
+  # boot in a SECOND, independent registry (the console app's own
   # console_settings_domain.rb) specifically so no consuming app needed
   # any change at all — that property is real and now given up on
   # purpose, in favor of the one binding mechanism every other
@@ -30,7 +30,7 @@ Hecks.bluebook "ConsoleSettings" do
   # (Overview, below) and every `extra_json`/`identity_extra_json`
   # field throughout this chapter were BOTH originally scoped out on an
   # "confirmed unused in any real presentation.yml" basis that turned
-  # out to be checked against the wrong file — embryonaut_console's own
+  # out to be checked against the wrong file — the console app's own
   # fixture, never this app's actual, live one. Migrating the real file
   # found both very much in use.
 

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -339,6 +339,12 @@ Hecks.bluebook "Bluebook" do
       member refusal: "InvariantViolation", site: "undeclared_set",
              template: "{name} admits {admits}, which this chapter does not declare — a closed set is named " \
                        "Aggregate::SetName, and it must be one the bluebook actually holds"
+      # ADR 0061 decision D1: a group_by leaf holds one row, so two rows
+      # reaching the same full key path refuse at dispatch rather than one
+      # of them being dropped.
+      member refusal: "InvariantViolation", site: "group_by_collision",
+             template: "{read_model} groups by {fields}, but rows {ids} share {key} — a group_by " \
+                       "leaf holds one row; add a field that tells them apart"
       member refusal: "Unauthorized", site: "tenant_required",
              template: "{query} declares authorize with tenant: {field} — pass {field}: to name which " \
                        "{field} this ask is scoped to"
@@ -620,6 +626,16 @@ Hecks.bluebook "Bluebook" do
              shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
       member refusal: "InvariantViolation", site: "undeclared_set", argument: "admits",
              shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "group_by_collision", argument: "read_model",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "group_by_collision", argument: "fields",
+             shape: "list", quoting: "none", separator: ", ", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "group_by_collision", argument: "ids",
+             shape: "list", quoting: "inspect", separator: ", ", sorted: "true", when_empty: ""
+      # "field = value" per key-path level, joined with ", " by the caller:
+      # each value is its own `to_s`, the same text the nested Hash keys it by.
+      member refusal: "InvariantViolation", site: "group_by_collision", argument: "key",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
       member refusal: "Unauthorized", site: "tenant_required", argument: "query",
              shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
       member refusal: "Unauthorized", site: "tenant_required", argument: "field",

data/lib/hecks/language/world/world.bluebook

@@ -4,8 +4,10 @@ Hecks.bluebook "World" do
 
     identified_by WorldName, as: :domain
 
-    attribute :realm,  Realm
-    attribute :latest, Latest
+    attribute :realm,            Realm
+    attribute :latest,           Latest
+    attribute :default_database, DefaultDatabase
+    attribute :default_adapter,  DefaultAdapter
 
     value_object "WorldName" do
       attribute :value, String
@@ -22,6 +24,22 @@ Hecks.bluebook "World" do
       invariant("a latest version says something") { !value.to_s.empty? }
     end
 
+    # The connection every chapter's database-taking persistence adapter
+    # uses unless that chapter's own world says otherwise — a world's
+    # per-chapter `persisted_by ... database` block, written once.
+    value_object "DefaultDatabase" do
+      attribute :value, String
+      invariant("a default database says something") { !value.to_s.empty? }
+    end
+
+    # The persistence adapter every aggregate binds to unless its own
+    # chapter's hecksagon binds it — between an explicit bind and the
+    # framework's in-memory fallback.
+    value_object "DefaultAdapter" do
+      attribute :value, String
+      invariant("a default adapter names an adapter") { !value.to_s.empty? }
+    end
+
     command "Declare" do
       role "Deployment"
       goal "Open a world for a domain"
@@ -29,10 +47,14 @@ Hecks.bluebook "World" do
       attribute :domain, WorldName
       attribute :realm,  Realm, optional: true
       attribute :latest, Latest, optional: true
+      attribute :default_database, DefaultDatabase, optional: true
+      attribute :default_adapter,  DefaultAdapter,  optional: true
 
       sets :domain
       sets :realm
       sets :latest
+      sets :default_database
+      sets :default_adapter
 
       emits "WorldDeclared"
     end
@@ -55,6 +77,12 @@ Hecks.bluebook "World" do
       member word: "world",           context: "File",     body: "keywords", inner: "World",          opens: "World",          fills: ""
       member word: "realm",           context: "World",     body: "none", inner: "", opens: "", fills: "realm", calls: "realm_impl"
       member word: "latest",          context: "World",     body: "none", inner: "", opens: "", fills: "latest", calls: "latest_impl"
+      # THE TWO CROSS-CHAPTER DEFAULTS — the same connection string and the
+      # same persistence adapter every chapter of a project repeats, written
+      # once. A chapter's own world (`persisted_by ... database`) and its own
+      # hecksagon bind still win; see docs/implemented/reference/world.md.
+      member word: "default_database", context: "World", body: "none", inner: "", opens: "", fills: "default_database", calls: "default_database_impl"
+      member word: "default_adapter",  context: "World", body: "none", inner: "", opens: "", fills: "default_adapter", calls: "default_adapter_impl"
 
     end
 
@@ -78,6 +106,8 @@ Hecks.bluebook "World" do
       member keyword: "world",           context: "File", at: "1", named: "", kind: "text", required: "true", fills: "domain"
       member keyword: "realm",           context: "World", at: "1", named: "", kind: "text", required: "true", fills: "realm"
       member keyword: "latest",          context: "World", at: "1", named: "", kind: "text", required: "true", fills: "latest"
+      member keyword: "default_database", context: "World", at: "1", named: "", kind: "text", required: "true", fills: "default_database"
+      member keyword: "default_adapter",  context: "World", at: "1", named: "", kind: "text", required: "true", fills: "default_adapter"
 
     end
   end

data/lib/hecks/mcp_door_scope.rb

@@ -0,0 +1,176 @@
+require_relative "runtime/errors"
+
+module Hecks
+  # What one spawned `bin/hecks_mcp_door` may do: every tool against any domain under
+  # `Storehouse::BOOT_ROOT` (the default), or, in reader mode, only the reader tools
+  # against the domains its spawner named. ADR 0072, decision 2.
+  #
+  # ## Reach, not identity
+  #
+  # This is a capability allowlist, not authentication. It identifies no one and adds no
+  # secret: whoever can spawn the door chooses its mode, and whoever can write to its stdin
+  # gets whatever that mode allows. What it buys is a smaller surface per agent. A reader
+  # door cannot dispatch, cannot run `.behaviors` files, and cannot `Kernel.load` Ruby from
+  # a domain its spawner did not name.
+  #
+  # ## Why `HECKS_DOOR_*` and not `HECKS_MCP_*`
+  #
+  # `McpStdioGuard` refuses every `HECKS_MCP_*` variable except
+  # `HECKS_MCP_TRANSPORT=stdio`, and every argument except `--stdio`, so that no option can
+  # ask a server for another transport. Those refusals belong to ADR 0062. The settings
+  # here live under their own prefix so the guard stays exactly as that ADR describes it,
+  # and an unknown `HECKS_DOOR_*` name is refused here, the same fail-closed way.
+  #
+  # ## The settings
+  #
+  # - `HECKS_DOOR_TOOLS=readers` turns reader mode on. Unset means every tool, as before.
+  #   Any other value refuses to start.
+  # - `HECKS_DOOR_DOMAINS` lists the domains a reader door may name, separated by
+  #   `File::PATH_SEPARATOR` (`:` on Unix), each resolved against `Storehouse::BOOT_ROOT`.
+  #   Required in reader mode and refused without it.
+  #
+  # ## The allowed set is named, not loaded
+  #
+  # The door boots a domain afresh on every call and keeps nothing loaded between calls,
+  # so there is no set of already-loaded domains to check against. The allowed set is the
+  # list the spawner named, resolved to absolute paths at startup. A call's `domain:` is
+  # resolved the same way and compared before anything boots, so a path outside the set
+  # never reaches `Kernel.load`. The comparison is on resolved path text: a symlink under a
+  # named path is followed when that domain boots, as it is for every domain today.
+  class McpDoorScope
+    ENV_PREFIX       = "HECKS_DOOR_".freeze
+    TOOLS_VARIABLE   = "HECKS_DOOR_TOOLS".freeze
+    DOMAINS_VARIABLE = "HECKS_DOOR_DOMAINS".freeze
+    READERS          = "readers".freeze
+    EXIT_STATUS      = 2
+
+    # The tools a reader door serves. Each reads a domain or the door's own audit log and
+    # writes no domain state. `query` and `state` still append their call to that audit
+    # log. `validate` boots the domain it is given, so it is held to the allowed set like
+    # every other domain-scoped tool. `domains` lists directories and loads nothing.
+    READER_TOOLS = %w[query events state catalog describe validate domains history follow].freeze
+
+    # Reads the door's mode from its environment.
+    #
+    # @param env [Hash{String => String}] the process environment
+    # @return [McpDoorScope] an unrestricted scope when no `HECKS_DOOR_*` variable is set;
+    #   otherwise a reader scope over the named domains
+    # @raise [ArgumentError] with every problem found, one per line, when the settings are
+    #   not a mode this door knows
+    # @raise [Runtime::TypeMismatch] if a named domain resolves outside
+    #   `Storehouse::BOOT_ROOT`
+    def self.from_env(env = ENV)
+      problems = setting_problems(env)
+      raise ArgumentError, problems.join("\n") unless problems.empty?
+      return new(allowed_domains: nil) unless env[TOOLS_VARIABLE]
+
+      new(allowed_domains: env[DOMAINS_VARIABLE].split(File::PATH_SEPARATOR).reject(&:empty?))
+    end
+
+    # Reads the door's mode, or refuses to start on settings it does not know.
+    #
+    # Everything goes to `stderr`, because stdout carries the MCP protocol.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param env [Hash{String => String}] the process environment
+    # @param stderr [IO] where a refusal is written
+    # @return [McpDoorScope] the door's scope
+    # @raise [SystemExit] with status `EXIT_STATUS` when `from_env` refuses the settings
+    def self.start!(server:, env: ENV, stderr: $stderr)
+      from_env(env)
+    rescue ArgumentError, Runtime::TypeMismatch => e
+      e.message.each_line { |line| stderr.puts("#{server}: refusing to start: #{line.chomp}") }
+      exit(EXIT_STATUS)
+    end
+
+    # @api private
+    def self.setting_problems(env)
+      unknown = env.keys.select { |name| name.start_with?(ENV_PREFIX) } - [TOOLS_VARIABLE, DOMAINS_VARIABLE]
+      problems = unknown.map do |name|
+        "environment #{name} is not accepted; the door takes only #{TOOLS_VARIABLE} and #{DOMAINS_VARIABLE}"
+      end
+      problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE])
+    end
+
+    # @api private
+    def self.mode_problems(tools, domains)
+      if tools.nil?
+        domains.nil? ? [] : ["#{DOMAINS_VARIABLE} is set without #{TOOLS_VARIABLE}=#{READERS}; it only narrows a reader door"]
+      elsif tools != READERS
+        ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the only value is #{READERS.inspect}"]
+      elsif domains.to_s.split(File::PATH_SEPARATOR).none? { |path| !path.empty? }
+        ["#{TOOLS_VARIABLE}=#{READERS} needs #{DOMAINS_VARIABLE}, the domains this door may read"]
+      else
+        []
+      end
+    end
+
+    # The named domains, resolved against `Storehouse::BOOT_ROOT`; nil when unrestricted.
+    #
+    # @return [Array<String>, nil]
+    attr_reader :allowed_domains
+
+    # @param allowed_domains [Array<String>, nil] the domains a reader door may name, as
+    #   given; nil for an unrestricted door
+    # @raise [Runtime::TypeMismatch] if a named domain resolves outside `Storehouse::BOOT_ROOT`
+    def initialize(allowed_domains:)
+      @allowed_domains = allowed_domains&.map { |path| Storehouse.confine!(path, DOMAINS_VARIABLE) }.freeze
+    end
+
+    # Tells whether this door runs in reader mode.
+    #
+    # @return [Boolean] true when the spawner set `HECKS_DOOR_TOOLS=readers`
+    def restricted?
+      !@allowed_domains.nil?
+    end
+
+    # Tells whether this door serves a tool.
+    #
+    # @param name [String] the tool name from a `tools/call` request
+    # @return [Boolean] true for every name on an unrestricted door; on a reader door, true
+    #   only for `READER_TOOLS`
+    def permits_tool?(name)
+      !restricted? || READER_TOOLS.include?(name)
+    end
+
+    # Builds the answer to a call for a tool this door does not serve.
+    #
+    # @param name [String] the tool name from a `tools/call` request
+    # @return [Hash{Symbol => Object}] `{ok: false, error:}`, the error naming the mode and
+    #   the tools it serves
+    def refusal(name)
+      { ok:    false,
+        error: "#{name.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}), " \
+               "which serves only #{READER_TOOLS.join(', ')}" }
+    end
+
+    # Checks a call's `domain:` against the allowed set, before anything boots.
+    #
+    # @param domain [String, nil] the caller's `domain:` argument
+    # @return [String, nil] `domain` unchanged, so an unrestricted door boots exactly what
+    #   it did before
+    # @raise [Runtime::TypeMismatch] on a reader door, if `domain` resolves outside
+    #   `Storehouse::BOOT_ROOT` or to a path its spawner did not name
+    def admit_domain!(domain)
+      return domain unless restricted?
+      return domain if @allowed_domains.include?(Storehouse.confine!(domain, "domain"))
+
+      raise Runtime::TypeMismatch,
+            "domain: #{domain.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}) " \
+            "and reads only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}"
+    end
+
+    # The startup warning lines that describe this door's mode.
+    #
+    # @return [Array<String>] empty when unrestricted; on a reader door, what it serves,
+    #   what it refuses, the domains it reads, and that it identifies no one
+    def notes
+      return [] unless restricted?
+
+      ["Reader mode (#{TOOLS_VARIABLE}=#{READERS}): serves #{READER_TOOLS.join(', ')}; " \
+       "refuses dispatch (with dry_run and steps), behaviors and every other tool.",
+       "domain: boots only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}.",
+       "Reader mode limits reach and identifies no one; it is not authentication."]
+    end
+  end
+end

data/lib/hecks/ports/key_vault.rb

@@ -47,7 +47,7 @@ module Hecks
       #
       # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
       #   dispatcher both the lookup query and the `Shred` dispatch run through
-      # @param domain [String] the subject's own domain FQN, e.g. `"Lifeadelics::Registration"`
+      # @param domain [String] the subject's own domain FQN, e.g. `"Site::Registration"`
       # @param subject_id [String] the data subject to erase
       # @return [Boolean] true when a live key was found and shredded by this call; false
       #   when no `SubjectKey` record exists for this subject, or it was already shredded

data/lib/hecks/ports/persistence/append_only.rb

@@ -308,7 +308,7 @@ module Hecks
         #
         # @param id [Integer] the row id assigned by `outbox_enqueue`
         # @return [Boolean] true when this call claimed the row; false when it is missing or
-        #   no longer pending
+        #   not pending
         def outbox_claim(id) = @adapter.outbox_claim(id)
 
         # Records the final status of a claimed outbox row.

data/lib/hecks/ports/persistence/binding_policy.rb

@@ -15,6 +15,13 @@ module Hecks
         # A domain with no hecksagon gets the default in-memory bind. A domain that has one
         # must bind the aggregate exactly once without a role.
         #
+        # A `default_adapter` a world declares (`Registry#default_adapter_for` — the
+        # chapter's own world, else the project's) stands in wherever the hecksagon binds
+        # nothing for the aggregate, and replaces the in-memory fallback for a domain
+        # with no hecksagon. It is never consulted once the hecksagon binds the aggregate
+        # or declares a domain-level default of its own, so an explicit chapter decision
+        # always wins.
+        #
         # @param registry [Runtime::Registry] the registry holding the domain's hecksagon
         # @param domain [String, Symbol] name of the domain the aggregate belongs to
         # @param aggregate [Bluebook::Aggregate] the aggregate whose binding is wanted
@@ -23,10 +30,12 @@ module Hecks
         # @raise [Runtime::WiringError] if the hecksagon has no `persisted_by` bind for the
         #   aggregate, more or fewer than one bind without a role, or any bind with a role
         def resolve(registry, domain, aggregate)
-          hexagon = registry.hecksagon(domain)
-          return default_binding(aggregate) unless hexagon
+          hexagon  = registry.hecksagon(domain)
+          declared = registry.default_adapter_for(domain)
+          return default_binding(aggregate, declared || DEFAULT_ADAPTER) unless hexagon
 
           bindings = hexagon.binds_for(aggregate.hecks_name, VERB)
+          bindings = [default_binding(aggregate, declared)] if bindings.empty? && declared
           raise missing_binding(domain, aggregate) if bindings.empty?
 
           authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }
@@ -39,9 +48,11 @@ module Hecks
         # Builds the bind an aggregate gets when its domain declares no hecksagon.
         #
         # @param aggregate [Bluebook::Aggregate] the aggregate to bind
-        # @return [Bluebook::Bind] a roleless `persisted_by` bind to `DEFAULT_ADAPTER`
-        def default_binding(aggregate)
-          Bluebook::Bind.new(aggregate: aggregate.hecks_name, verb: VERB, adapter: DEFAULT_ADAPTER)
+        # @param adapter [String] the adapter to bind it to; the framework's in-memory
+        #   default unless a world declared one
+        # @return [Bluebook::Bind] a roleless `persisted_by` bind to `adapter`
+        def default_binding(aggregate, adapter = DEFAULT_ADAPTER)
+          Bluebook::Bind.new(aggregate: aggregate.hecks_name, verb: VERB, adapter: adapter)
         end
 
         # Builds, without raising, the error for an aggregate a hecksagon leaves unbound.

data/lib/hecks/ports/persistence/plugins/era/era_check.rb

@@ -4,6 +4,7 @@ require_relative "lineage"
 require_relative "../../../../naming"
 require_relative "../../../../framework"
 require_relative "../../../../runtime/registry"
+require_relative "expected_era"
 
 module Hecks
   module Runtime
@@ -122,7 +123,7 @@ module Hecks
       #
       # The domain's own directory first, matched by name — a real app's
       # directory may hold more than one file once `uses_framework`
-      # exists, so ".first" alone can no longer be trusted, the exact
+      # exists, so ".first" alone cannot be trusted, the exact
       # way it silently wasn't the day this was found: three domains
       # booted together, one real source text read once (the domain's
       # own, ".first"'d), and every other domain's era-1 held that text
@@ -295,7 +296,7 @@ module Hecks
                 "it could be found (checked #{directory.inspect} and the framework registry)"
         end
 
-        settings = registry.world(bluebook.name)&.for_binding(Ports::Persistence::VERB, adapter_name) || {}
+        settings = registry.binding_settings(bluebook.name, Ports::Persistence::VERB, adapter_name)
         registry.adapter_class(adapter_name).era_check!(
           registry: registry, bluebook: bluebook, current_text: current_text, settings: settings,
           directory: directory

data/lib/hecks/ports/persistence/plugins/era/era_guard.rb

@@ -131,7 +131,7 @@ module Hecks
       # Normal parse first, shadow only as a fallback — never shadow-parsing
       # unconditionally. A handful of DSL
       # defaults fork on `MetaValidator.shadow_parsing?` for a reason
-      # that has nothing to do with syntax the live grammar can no longer
+      # that has nothing to do with syntax the live grammar cannot
       # read at all (`identified_by { }`, `belongs_to`, `has_one`,
       # `has_many` — genuinely removed spellings, exactly what shadow-
       # parsing exists to keep readable): `reference_to`'s own default
@@ -158,7 +158,7 @@ module Hecks
       # interpretation, the same one `label_of`/`mint_hash` on the same
       # source text always computes, whoever's asking. Only on a
       # `Malformed` refusal — the one signal that actually means "this
-      # spelling doesn't exist anymore" — fall back to the legacy
+      # spelling is not in the live grammar" — fall back to the legacy
       # grammar. Any other exception (a
       # genuine syntax error, an unrelated validation refusal) propagates
       # unchanged; swallowing it here to retry under shadow mode would

data/lib/hecks/ports/persistence/plugins/era/era_tamper.rb

@@ -5,7 +5,7 @@ require_relative "storage_shape"
 
 module Hecks
   module Runtime
-    # The refusal wording for a held era whose digest no longer matches its
+    # The refusal wording for a held era whose digest does not match its
     # frozen text — the digest mismatch alone is what detects tampering (a
     # plain SHA256 comparison over raw bytes, unrelated to any of this);
     # this only supplies the wording once that's already fired.
@@ -28,7 +28,7 @@ module Hecks
     module EraTamper
       module_function
 
-      # Words the boot refusal for a held era text whose digest no longer matches.
+      # Words the boot refusal for a held era text whose digest does not match.
       #
       # @param domain [String] name of the domain whose era was edited
       # @param ordinal [Integer] the edited era's ordinal in `hecks_eras`