hecks 2.6.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2220925ed910b9c63dd34c3fc75448f6cff634a64be3fb67461985d462e83563
-  data.tar.gz: 618319249d19f123171d300578ba8d70556391371457700504c92ba4bd389935
+  metadata.gz: 66f85d62ad01467ff2ae17c6d3be63c706bea69a9e6f7b20839d9f5fc22234a5
+  data.tar.gz: 45413f0bd639bfe548ca9f8f7970d5136ed6aa30a25765870ca0212806af3c90
 SHA512:
-  metadata.gz: a24cd51e0ba290e819645aec45cbc8a55c9978cb1c5fed673180db103a050a77516ebcd224d0102fad523161ce4776866b5702acf790dd0751282c2c399e73a9
-  data.tar.gz: a779523871cd0e81d87c26305bed16e51916723ef544e55ccc30d669b6fdb38b825ee2a05515ae9f8c2f40ff31e4faa57f4d5dffc0dac68146d900d112830d92
+  metadata.gz: b817baff1d4e990f1161080d23f9f10fadd2e1eb8a6f76b1ed551fe021992311f10d64f0eef63218e515905fa2757d879a607abc4b40ecfeb4d0d45a6011a8a6
+  data.tar.gz: '0819f496494a76afe81697f8a83301c07acef480b218501748616f1537f0c5d3c0148d67271dea0fd4eea6b6bcb9bbb278331a203883b3c169c08cd59f384451'

data/exe/hecks

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+# The `hecks` command the gem installs: run, read, check and serve a domain you
+# supply. `hecks` with no arguments lists the subcommands; `hecks <command> --help`
+# prints one's usage. The router is `Hecks::CLI` (lib/hecks/cli.rb).
+#
+# The gem's own `lib` goes first on the load path, as it does for the `bin/`
+# scripts, so this file also runs straight from a checkout.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "hecks/cli"
+
+exit Hecks::CLI.start(ARGV)

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

@@ -6,7 +6,7 @@ module Hecks
   module Adapters
     # **Google's own OIDC handshake** — the `authentication` port's one real
     # implementation today. Consolidates what was hand-rolled per-app
-    # (an embryonaut_console `google_auth.rb` did this on its own) into
+    # (a console app's `google_auth.rb` did this on its own) into
     # one adapter, so any hecks-based app gets Google sign-in for free, the
     # same "one adapter, reusable everywhere" value every other adapter
     # in this directory already has.

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

@@ -29,7 +29,7 @@ module Hecks
       # exist precisely so a domain whose AWS identity predates a rename
       # keeps targeting the stack that is actually live rather than
       # standing up a second, empty one beside it. A real one:
-      # embryonautfoundersapp deploys as `hecksagain-embryonaut`, and no
+      # a client site deploys under a fixed stack name, and no
       # value of `domain` (or of `DOMAIN_NAME`, the deployed-Lambda
       # override callers already pass) can make this computation produce
       # a name with no dash after "hecks". Every Ruby-side read and

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

@@ -217,7 +217,7 @@ module Hecks
       #
       # @param id [Integer] the row id `outbox_enqueue` assigned
       # @return [Boolean] true when the row was pending and is now claimed; false when it is
-      #   unknown or no longer pending
+      #   unknown or not pending
       def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
         row = @outbox.find { |held| held.id == id }
         return false unless row&.pending?

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

@@ -247,7 +247,7 @@ module Hecks
       #   an update to apply; nil writes unconditionally. Ignored for a delete
       # @return [Runtime::Instance, PG::Result, nil] for a save, a new instance over the
       #   entry's state with `version` set to the stored `hecks_version`, or nil when
-      #   `expected_version` no longer matched and nothing was written; for a delete, the
+      #   `expected_version` did not match and nothing was written; for a delete, the
       #   `DELETE` statement's `PG::Result`
       # @raise [PG::Error] if the statement fails
       # rubocop:disable Metrics/AbcSize -- the CAS/plain upsert split is one

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

@@ -72,7 +72,7 @@ module Hecks
         # That's invisible to anything that virtualizes the filesystem at
         # the Ruby level instead of the OS level (e.g. tebako's memfs,
         # which presses a hecks-based app into a single executable —
-        # see domain/README.md's "Deploying" section in lifeadelics for
+        # see domain/README.md's "Deploying" section in a client site's domain for
         # why that matters). ::Prism.parse(File.read(file)) parses the
         # exact same bytes, just read through Ruby's File.read first,
         # which those tools do intercept.
@@ -85,7 +85,7 @@ module Hecks
       # never edited out from under it), but wrong for anything that
       # legitimately reloads an edited file in-process: a stale cached
       # tree reports a `given`/`ensures` block at its old line number,
-      # which no longer matches the freshly re-executed file's own
+      # which does not match the freshly re-executed file's own
       # `block.source_location` — surfacing as "did not survive
       # extraction" on a perfectly valid file. Built for real building
       # `Hecks::Codemod` (lib/hecks/codemod.rb), which needs exactly this

data/lib/hecks/adapters/driven/sqlite/projection.rb

@@ -15,7 +15,7 @@ module Hecks
     # Rebuilds a read store from the authoritative journal, entry by entry.
     # A value object is written as its JSON object and a reference as the
     # bare id it holds — the same shapes the command path writes, so there
-    # is no second representation to accept here any more.
+    # is no second representation to accept here.
     class SqliteProjection < Sqlite
       # Replaces or deletes the read store's row for one journal entry, encoding the entry's
       # state directly rather than through a `Runtime::Instance`.

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

@@ -4,7 +4,7 @@ require "fileutils"
 
 module Hecks
   module Adapters
-    # THE IMPERATIVE HALF of provisioning a tenant, pulled out of
+    # The imperative half of provisioning a tenant, pulled out of
     # `bin/project_tenant` and behind a real driven port
     # (`Deploy::Tenant.port "TenantProvisioning"`) instead — the same
     # hexagonal reasoning `GithubChecks` already gives for its own
@@ -16,34 +16,55 @@ module Hecks
     # `PortOperationInterpreter#ask`'s own "every failure is an answer"
     # comment for why nothing here needs its own rescue.
     #
-    # DELIBERATELY DOES NOT BOOT THE TARGET DOMAIN — that step (proving
+    # ## What it leaves out
+    #
+    # Deliberately does not boot the target domain — that step (proving
     # it boots for real, running the tenant_capable? gate) stays in
-    # `bin/project_tenant` itself, called AFTER this operation answers,
+    # `bin/project_tenant` itself, called after this operation answers,
     # not nested inside it. Booting a whole domain from inside an
     # adapter method that is itself running mid-dispatch (this port
     # operation) is a real, separate concern from writing one file, and
     # keeping the two apart avoids a nested `Hecks.boot` call ever
     # running inside another boot's own dispatch call stack.
     #
-    # RETURNS A HASH SHAPED LIKE `Tenancy::Tenant.Register`'S OWN
-    # ARGUMENTS, on purpose — `tenancy.hecksagon`'s own `translates`
+    # ## Return shape
+    #
+    # Returns a hash shaped like `Tenancy::Tenant.Register`'s own
+    # arguments, on purpose — `tenancy.hecksagon`'s own `translates`
     # reaction forwards an answered event's payload verbatim, so this
-    # adapter's own return value IS the translation from Deploy's
+    # adapter's own return value is the translation from Deploy's
     # vocabulary into Tenancy's, decided here rather than in a mapping
     # layer neither side could see into.
     class TenantProvisioner
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
-      # `directory:` IS REQUIRED, NOT DERIVED FROM `domain` — a real,
+      # Writes the tenant's environment overlay file under its domain directory.
+      #
+      # `directory:` is required, not derived from `domain` — a real,
       # confirmed bug found only under CI's own real-Postgres suite: a
-      # domain's own DECLARED NAME (`domain`, e.g. "Scratch") is not a
+      # domain's own declared name (`domain`, e.g. "Scratch") is not a
       # filesystem path, and File.expand_path(domain, Dir.pwd) silently
       # resolved to the wrong directory (relative to whatever the
-      # RUNNING PROCESS' own cwd happened to be) whenever the CLI's own
+      # running process' own cwd happened to be) whenever the CLI's own
       # `--domain=` value didn't happen to equal its own directory
       # argument by coincidence. `bin/project_tenant` passes its own
       # real `domain_directory` local straight through.
-
+      #
+      # Every argument arrives either bare or wrapped as `{ value: ... }`; both are read.
+      #
+      # @param slug [String, Hash] the tenant's slug, which names the overlay file
+      # @param domain [String, Hash] the declared domain name the overlay is for
+      # @param realm [String, Hash] the realm the overlay declares
+      # @param schema [String, Hash] the schema the overlay declares
+      # @param database [String, Hash] the database the overlay declares
+      # @param adapter [String, Hash] the persistence adapter the overlay declares
+      # @param directory [String, Hash] the domain's own directory on disk
+      # @return [Hash{Symbol => Object}] `:slug`, `:domain`, `:realm` and `:schema`, as given
       def provision(slug:, domain:, realm:, schema:, database:, adapter:, directory:)
         domain_directory = File.expand_path(directory[:value] || directory)
 

data/lib/hecks/behaviors/expectations.rb

@@ -228,7 +228,7 @@ module Hecks
       #   the dispatch's own result
       # @return [Hash{Symbol => Object}] the settled record's current state, read
       #   back from the repository; `result.state` (or `{}`) when the result has no
-      #   id or the repository no longer has that aggregate/record
+      #   id or the repository does not have that aggregate/record
       def settled_state(runtime, verb, result)
         return result.state || {} unless result.respond_to?(:id) && result.id
 
@@ -266,7 +266,7 @@ module Hecks
       # only so long as nothing else ever asked it to resolve a port-operation
       # verb. Now that a `policy` can legitimately `trigger` a port operation
       # (`ReactionInvocation#resolve_target`'s own port-operation branch),
-      # that raise no longer happens, so this checks directly instead.
+      # that raise does not happen, so this checks directly instead.
       #
       # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
       #   booted runtime

data/lib/hecks/bluebook/assembly/contract.rb

@@ -151,7 +151,7 @@ module Hecks
       #                         Entity's contract claims `owner: :parent`
       #
       # `shape` and `handler` are not on this list — S17 (ADR 0026) made Member and
-      # Dispatch nested entities, so neither is a parent field any more the way
+      # Dispatch nested entities, so neither is a parent field the way
       # `owner` is. `spec/assembly_spec` derives this set from `Plan` and the
       # contracts directly and fails on any drift, rather than trusting this list to
       # stay in sync with a second hand-written copy kept by the model generator.

data/lib/hecks/bluebook/assembly/contracts.rb

@@ -243,7 +243,7 @@ module Hecks
 
         # S17, ADR 0026 — Handler is a genuine entity now, nested under
         # ProcessManager (`entity "Handler"`, reaction.bluebook). Neither
-        # `position` nor `handler` is a stored field any more: a saga
+        # `position` nor `handler` is a stored field: a saga
         # answers each event once, so `event_type` is Handler's own real,
         # non-positional identity (no walk-minted `position` to derive),
         # and the process manager it belongs to is structural now — which
@@ -429,10 +429,10 @@ module Hecks
         # A member's pairs are an open map, which is why Member is its own root in
         # the language. The IR keeps them as a plain hash on the value object, so
         # they are assembled with their shape rather than as a construct.
-        # S17, ADR 0026 — Member is a genuine entity now, nested under
-        # ValueObject (`entity "Member"`, shape.bluebook). It no longer
-        # holds a `shape` field at all (that was the free-text, un-parsed
-        # spelling a standalone root once needed ; an entity's element is
+        # S17, ADR 0026 — Member is a genuine entity, nested under
+        # ValueObject (`entity "Member"`, shape.bluebook). It holds no
+        # `shape` field at all (a free-text, un-parsed spelling would suit
+        # only a standalone root ; an entity's element is
         # never serialized as text) — only `position` (walk-minted, see
         # `entity_own_identity`, judge.rb) and `pairs` (still an open map,
         # still one row per entry, still why a value object cannot hold it

data/lib/hecks/bluebook/assembly/specializer.rb

@@ -21,8 +21,8 @@ module Hecks
       module Specializer
         module_function
 
-        # S17, ADR 0026 — `Handler` is a genuine entity now, nested under
-        # `ProcessManager`, so `.aggregate` alone no longer finds it —
+        # S17, ADR 0026 — `Handler` is a genuine entity, nested under
+        # `ProcessManager`, so `.aggregate` alone does not find it —
         # it hangs off some aggregate's own `.entities` instead
         # (searched recursively, the same reason `Value::Coercion#find_
         # entity` does: a nested entity, like `Dispatch` inside

data/lib/hecks/bluebook/assembly.rb

@@ -31,7 +31,7 @@ module Hecks
     # ## What stays hand-written
     #
     # The containment — which construct holds which — stays hand-written; it is
-    # not a field table. The runtime surface is no longer built here at all — the
+    # not a field table. The runtime surface is not built here at all — the
     # door is a per-boot projection, facade/surface.rb.
     class Assembly
       # Builds the graph the runtime runs from one chapter's declared hash.

data/lib/hecks/bluebook/behaviour/chapter.rb

@@ -91,15 +91,18 @@ module Hecks
           @ports_by_name[port.name] = port
         end
 
-        # A TRANSLATED REACTION IS ALSO DECLARED IN THE HECKSAGON —
+        # A translated reaction is also declared in the hecksagon —
         # `HecksagonBuilder#translates` builds an ordinary `Policy` (same
         # shape, same `PolicyInterpreter` runtime, as one written inside a
         # `policy` block in this chapter's own `.bluebook`) and attaches it
         # here, after the chapter already exists, the same reasoning
         # `add_port` gives one method up. Kept out of the bluebook itself
-        # on purpose: which FOREIGN domain's event this chapter reacts to
+        # on purpose: which foreign domain's event this chapter reacts to
         # is a wiring/context-mapping decision, not a fact the domain
         # states about its own model.
+        #
+        # @param policy [Bluebook::Policy] the translated reaction to attach
+        # @return [Array<Bluebook::Policy>] this chapter's policies, with `policy` appended
         def add_policy(policy)
           @policies << policy
         end

data/lib/hecks/bluebook/behaviour/read_model.rb

@@ -9,6 +9,24 @@ module Hecks
         # @return [Array<Symbol>] each declared `group_by` field's name, in declaration order
         def group_by_fields = @group_by.map { |row| row[:field].to_sym }
 
+        # Reports whether this read model's `group_by` names every identity head
+        # of the aggregate it groups (ADR 0061, decision D1).
+        #
+        # Such a key path cannot be shared by two rows, so it is accepted from the
+        # declaration alone and never checked for a collision at dispatch. Any
+        # other key path is checked per request.
+        #
+        # @param aggregate [Bluebook::Aggregate, nil] the aggregate of this read
+        #   model's one many-side head
+        # @return [Boolean] false when `aggregate` is nil or declares no identity,
+        #   since uniqueness cannot then be shown
+        def groups_by_identity?(aggregate)
+          return false unless aggregate
+
+          identity = Array(aggregate.identity_heads).map(&:to_sym)
+          !identity.empty? && (identity - group_by_fields).empty?
+        end
+
         # `!!` rather than a bare `@count` — the DSL/reconstruction
         # boundary (ReadModel#initialize) already normalises to
         # `true`/`nil`, so this is belt and braces against a future

data/lib/hecks/bluebook/capabilities.rb

@@ -19,11 +19,11 @@ module Hecks
       # Who may sign in, and with what role — rust/host's Google-OAuth
       # provision/member_rows resolve this instead of an env var naming
       # the aggregate (HECKS_MEMBERSHIP_AGGREGATE). Same declared-
-      # not-named shape AUTHORIZATION already is for Governance.
+      # not-named shape `AUTHORIZATION` already is for Governance.
       MEMBERSHIP = "membership".freeze
       # A stable organizational identity, independent of how it was
       # authenticated — recognised by declaration, not the literal name
-      # "Identity". Same declared-not-named shape AUTHORIZATION already
+      # "Identity". Same declared-not-named shape `AUTHORIZATION` already
       # is. rust/host does not build this chapter's payloads; any field
       # mapping lives on the consuming hecksagon's `translates` ACL.
       IDENTITY = "identity".freeze

data/lib/hecks/bluebook/chapter.rb

@@ -4,7 +4,7 @@ require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # The chapter, and no longer the namespace it lives in.
+    # The chapter, which is not the namespace it lives in.
     #
     # `Hecks::Bluebook` was briefly a class, because dropping the
     # old `IR::` segment would otherwise have produced

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

@@ -198,7 +198,7 @@ module Hecks
         # never `[]`). Wave 6 (identity-and-relationships arc) un-deprecates
         # all three for real: a relationship word now retains the author's
         # domain concept in IR — still stored as one or more target
-        # identities, but no longer collapsed to a bare `reference_to`
+        # identities, but not collapsed to a bare `reference_to`
         # during assembly. `MetaValidator.shadow_parsing?` still routes to
         # `legacy_has_many`/`legacy_has_one` so frozen era text written
         # under the old (lying/collapsing) meaning still parses the way it
@@ -511,7 +511,7 @@ module Hecks
         # are this construct's own refusal wording, not shared, since
         # `declared_by:` only exists here so far. Unresolved (no
         # candidate yet, or `declared_by:` naming an aggregate that
-        # hasn't declared it yet) is no longer a fourth branch that
+        # hasn't declared it yet) is not a fourth branch that
         # raises here — see `#pending_chapter_given`, below, for why:
         # a chapter split across files can genuinely reference a
         # precondition a later file declares, and "not found among

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

@@ -77,7 +77,7 @@ module Hecks
         end
 
         def method_missing(verb, *args, **kwargs, &block)
-          # A BARE CALL — no args, no kwargs, no block — starts (or
+          # **A bare call** — no args, no kwargs, no block — starts (or
           # continues, on `AttributePath` itself below) a Privacy
           # marking chain: `Registration.attendee.medications.has_phi(
           # readable_by: "Privacy officer")`. No existing real
@@ -115,10 +115,15 @@ module Hecks
           @path = path
         end
 
+        # Records a `has_<category>` marking, or extends the attribute path by one segment.
+        #
         # @param verb [Symbol] `has_<category>` to record the marking and end the chain;
         #   any other bare name to extend the path one segment further
         # @param readable_by [String] required only for a `has_<category>` call — the
         #   Governance role a read must hold to see this field unredacted
+        # @param args [Array] must be empty; a positional argument is refused
+        # @param kwargs [Hash] must be empty; any keyword but `readable_by:` is refused
+        # @param block [Proc, nil] must be absent; a block is refused
         # @return [Bluebook::DSL::AttributePath, nil] a longer chain for a plain segment;
         #   `nil` (nothing further to chain) for a `has_<category>` call
         # @raise [Malformed] if a `has_<category>` call omits `readable_by:`, or any call

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

@@ -431,9 +431,9 @@ module Hecks
         #   manager's own structural check fails
         def self.build(name, version: nil, &block)
           registry = Hecks.current_registry
-          # WHICH FILE CALLED `Hecks.bluebook`, recorded for
+          # Which file called `Hecks.bluebook`, recorded for
           # `Registry#record_bluebook_source` — two frames up: this
-          # method's own caller is `Hecks.bluebook` (hecks.rb), and ITS
+          # method's own caller is `Hecks.bluebook` (hecks.rb), and its
           # caller is the real `.bluebook` file's own top-level call site.
           caller_location = caller_locations(2, 1)&.first
           registry&.record_bluebook_source(name, caller_location&.path)

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

@@ -82,6 +82,8 @@ module Hecks
           ["Type", "one_of"] => :one_of_impl,
           ["World", "realm"] => :realm_impl,
           ["World", "latest"] => :latest_impl,
+          ["World", "default_database"] => :default_database_impl,
+          ["World", "default_adapter"] => :default_adapter_impl,
           ["DomainPort", "operation"] => :tells_impl,
           ["DomainPort", "tells"] => :tells_impl,
           ["DomainPort", "asks"] => :asks_impl,

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

@@ -22,7 +22,7 @@ module Hecks
         # same as an absent `to:` and falls through to `from` (also
         # absent), so `then_set :accepted, to: false` raised "names no
         # operation" for the one value most likely to be written that way
-        # (a boolean flip). Confirmed real, live: miette's
+        # (a boolean flip). Confirmed real, live: an external project's
         # dream_interpretation.bluebook (`then_set :accepted, to: false`)
         # and transparency.bluebook (`then_set :always, to: false`). TODO
         # upstream via bin/evolve.
@@ -262,7 +262,7 @@ module Hecks
         # era keeps booting, which is the whole point of the rename column.
         #
         # Vendored addition, not (yet) upstream hecks: `then_set
-        # :target, from: :source_field` (hecks_conception/miette, found
+        # :target, from: :source_field` (an external project, found
         # live in body/doctor/bluebook/doctor.bluebook) -- semantically
         # identical to `to:` (copy this argument/field into the target),
         # different word. TODO upstream via bin/evolve (migration plan
@@ -271,7 +271,7 @@ module Hecks
         #
         # Vendored addition, not (yet) upstream hecks (migration plan
         # task 4, i106 in-DSL math): `multiply:`/`clamp:` -- per-tick organ
-        # math (miette's body/organs/bluebook: strength decays ×0.98,
+        # math (an external project's organ bluebook: strength decays ×0.98,
         # weight/strength clamp to [0, 1]), moved into the bluebook itself
         # from shell-side awk. `multiply:` mirrors
         # increment/decrement's shape exactly (a Numeric amount, applied

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

@@ -243,7 +243,7 @@ module Hecks
         # since ADR 0028, `command` only queues a descriptor and actually
         # builds at `#drain_pending!` time, well after this whole block
         # (including every `given` in it) has already run, so textual
-        # order within the block no longer actually matters here; named
+        # order within the block does not actually matter here; named
         # for the reader anyway, since `given`'s own resolution logic
         # (`CommandBuilder#reference_named_given`) still reads whatever
         # `@named_givens` holds at the command's own build time, not by

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

@@ -8,7 +8,7 @@ module Hecks
       # already shipped) only checks a word's admissibility; this module
       # executes the safe, mechanical subset of what a word actually
       # does, read live off the same self-hosted grammar table — so a
-      # builder method for one of these words no longer needs to be
+      # builder method for one of these words need not be
       # hand-written at all. Called from `WordGate#method_missing`'s own
       # "admitted here, no builder method for it yet" branch, so it only
       # ever sees a word whose (context, word) pair the grammar already

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

@@ -31,7 +31,7 @@ module Hecks
           @translates         = []
         end
 
-        # Marks THIS chapter as a bounded context — a consumer-owned chapter
+        # Marks this chapter as a bounded context — a consumer-owned chapter
         # that `uses_framework` / `uses_embryonaut_bluebook` will not load.
         # Framework and vendored packages get the mark automatically from
         # those words; they never write `bounded` in their own bluebooks.
@@ -158,12 +158,12 @@ module Hecks
           bluebook_ir.add_port(built)
         end
 
-        # A TRANSLATION BOUNDARY, NOT A BUSINESS RULE — `translates "Name"
+        # A translation boundary, not a business rule — `translates "Name"
         # do on Foreign::Domain::SomeEvent; trigger Local.Command; end`
-        # builds the EXACT SAME `Policy` a `policy` block inside this
+        # builds the exact same `Policy` a `policy` block inside this
         # domain's own `.bluebook` would (same `on_impl`/`trigger_impl`,
         # same `PolicyInterpreter` runtime — reusing `PolicyBuilder`
-        # directly, zero new runtime semantics). What's new is only WHERE
+        # directly, zero new runtime semantics). What's new is only where
         # it can be written: a cross-domain reaction is a wiring/context-
         # mapping decision (this chapter conforming to a foreign chapter's
         # published event), the same kind of decision `port`/
@@ -171,23 +171,28 @@ module Hecks
         # model states about itself, which `policy` (inside the bluebook)
         # remains the right word for.
         #
-        # MUST BE A BLOCK, not `translates Event, into: Command` — a flat
-        # call's arguments are evaluated eagerly, under THIS builder's own
+        # Must be a block, not `translates Event, into: Command` — a flat
+        # call's arguments are evaluated eagerly, under this builder's own
         # `ConstShim` resolver (`BindingProxy.namespace`, set up by
-        # `self.build` below), which mints a `BindingProxy` INSTANCE per
+        # `self.build` below), which mints a `BindingProxy` instance per
         # segment and cannot answer a further `::` (it is not a Module) —
         # a multi-segment reference like `Deploy::Tenant::TenantProvisioned`
         # would raise before this method ever ran. `port_impl`'s own
         # `ConstShim.with(->(const) { const })` swap only works because
         # its own callers never pass a multi-segment bare constant as an
         # eagerly-evaluated argument — everything of that shape lives
-        # inside ITS block, evaluated later, under the swapped resolver.
+        # inside its block, evaluated later, under the swapped resolver.
         # A block defers evaluation the same way; a flat call cannot.
+        #
+        # @param name [String, Symbol] the reaction's name
+        # @yield the `on`/`trigger` block, evaluated later under the scoped resolver
+        # @return [Array<Bluebook::Policy>] the chapter's policies, with the new one appended
+        # @raise [Malformed] if no bluebook is registered for this domain to attach the reaction to
         def translates(name, &block)
           bluebook_ir = Hecks.current_registry.bluebook(@domain) or
             raise Malformed, "#{@domain} declares no such bluebook — translates needs one to attach its reaction to"
 
-          # SAME RESOLVER BluebookBuilder ITSELF uses for a `policy`
+          # Same resolver BluebookBuilder itself uses for a `policy`
           # block's own `on`/`trigger` (bluebook_builder.rb) — a
           # `ScopedConstant`, not the bare passthrough `port_impl` swaps
           # to, because `on`/`trigger` here take genuinely multi-segment

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

@@ -34,7 +34,7 @@ module Hecks
         # only external facts with attribute" the refusal message
         # describes) rather than folding `to:` into identity_attribute's
         # existing Reference-attribute scan, which every operation already
-        # in the corpus (Banking, pizzas, lifeadelics' own vendored
+        # in the corpus (Banking, pizzas, a client site's own vendored
         # PaymentGateway) still relies on unchanged.
         #
         # @param name [String] the operation's name

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

@@ -147,8 +147,8 @@ module Hecks
                   .find { |rule| rule.description == description }
         end
 
-        # **Which construct uses which primitive** — no longer a Ruby-only
-        # Hash (that was this constant's own shape, one round ago): the
+        # **Which construct uses which primitive** — not a Ruby-only
+        # Hash, because the
         # user's own correction — "my goal is that if they read the same
         # table they behave identically" — means a table only Ruby ever
         # reads cannot deliver that, no matter how faithfully it is
@@ -172,7 +172,7 @@ module Hecks
         # after `grammar_registry` is fully built and memoized, so reads
         # the real table, every time, no exception.
         #
-        # No longer kept in sync by hand — the same `resolves_via`/
+        # Not kept in sync by hand — the same `resolves_via`/
         # `disambiguator` columns, projected ahead of time into the
         # committed lib/hecks/bluebook/dsl/bootstrap_table.rb
         # (bin/project_bootstrap_table, pinned by spec/bootstrap_table_spec.rb).

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

@@ -268,7 +268,7 @@ module Hecks
       # Parses a whole `.translation` file into a `Translation` — the
       # domain's own `from:`/`to:` era pair, its list of `aggregate`
       # translation blocks (each built by `TranslationAggregateBuilder`
-      # above), and any `retired` aggregates that no longer exist in the
+      # above), and any `retired` aggregates that do not exist in the
       # destination era.
       class TranslationBuilder
         GRAMMAR_CONTEXT = "Translation".freeze

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

@@ -11,8 +11,22 @@ module Hecks
         # Starts with no settings recorded.
         def initialize = @values = {}
 
-        def method_missing(key, *args, &)
-          @values[key.to_sym] = args.size == 1 ? args.first : args
+        # A call with a block records the block's own settings as a nested Hash, so a bind can
+        # group settings (`preview do ... end`); a call without one records its argument.
+        #
+        # @param key [Symbol] the setting's name, recorded verbatim
+        # @param args [Array] the setting's value: one argument is kept as is, several as an array
+        # @param block [Proc, nil] a nested settings block, evaluated on a fresh collector
+        # @return [Object] the value recorded under `key`
+        def method_missing(key, *args, &block)
+          @values[key.to_sym] =
+            if block
+              nested = SettingsCollector.new
+              nested.instance_eval(&block)
+              nested.to_h
+            else
+              args.size == 1 ? args.first : args
+            end
         end
 
         def respond_to_missing?(_name, _include_private = false) = true
@@ -96,6 +110,35 @@ module Hecks
           @latest = required(value, "latest version")
         end
 
+        # Names the connection every chapter's database-taking persistence adapter uses
+        # unless that chapter's own world settings name one.
+        #
+        # Answers the `default_database` word through the table's `calls:` column, the
+        # same way `realm_impl` does. A chapter's own
+        # `persisted_by("Adapter") { database ... }` still wins for that adapter.
+        #
+        # @param value [String] the connection, such as a database URL; blankness is
+        #   judged by the world language at `build`, not here
+        # @return [String] the connection as stored
+        def default_database_impl(value)
+          @default_database = required(value, "default database")
+        end
+
+        # Names the persistence adapter every aggregate binds to unless its own chapter's
+        # hecksagon binds it.
+        #
+        # Answers the `default_adapter` word through the table's `calls:` column, the same
+        # way `realm_impl` does. Sits between an explicit bind and the framework's
+        # in-memory fallback; whether the adapter really is a persistence adapter is
+        # judged at boot, where adapters are known.
+        #
+        # @param value [String, Symbol] the adapter's declared name, such as `"PostgresEra"`;
+        #   blankness is judged by the world language at `build`, not here
+        # @return [String] the adapter name as stored
+        def default_adapter_impl(value)
+          @default_adapter = required(value, "default adapter")
+        end
+
         def method_missing(verb, *args, **kwargs, &block)
           result = word_gate_dispatch(verb, args, kwargs, block)
           return result unless result.equal?(WordGate::NOT_ADMITTED)
@@ -134,7 +177,8 @@ module Hecks
         #   as a blank `realm`
         def build
           MetaValidator.call_world(
-            World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings)
+            World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings,
+                      default_database: @default_database, default_adapter: @default_adapter)
           )
         end