hecks 1.4.0 → 1.5.0

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

@@ -8,6 +8,8 @@ module Hecks
       # IR it stores must equal the IR the DSL builder produces". The judge is the
       # first half. This reads the records back and assembles `to_h`.
       #
+      # ## One table, both directions
+      #
       # It is the inverse of the walk and shares its plan: the walk reads a node's
       # lists through the command that appends to each, and this reads them back out
       # of the rows those commands wrote. The retired `experiment/replay.rb` needed
@@ -17,6 +19,12 @@ module Hecks
       # This file is the traversal. The hashes at its tips, and the encodings they
       # undo, are in Shapes.
       #
+      # The parent key of every level is read from the language's own plan, the same
+      # Plan the walk dispatches from — so the two directions really are one table,
+      # which is what the header above has always claimed.
+      #
+      # ## Reads level by level, not through the read model
+      #
       # It reads level by level, through `DeclaredIn`, and not through the read
       # model — which is the difference between a reconstruction that can be the
       # source and one that can only be a check.
@@ -31,9 +39,7 @@ module Hecks
       # `DeclaredIn` preserves it (spec/executes_spec says so), so this asks each
       # level for its own children rather than filtering one sorted gather.
       #
-      # The parent key of every level is read from the language's own plan, the same
-      # Plan the walk dispatches from — so the two directions really are one table,
-      # which is what the header above has always claimed.
+      # ## What it cannot rebuild
       #
       # What it cannot rebuild matters as much as what it can, and
       # spec/round_trip_spec pins the difference as an exact set: a field the language
@@ -43,13 +49,27 @@ module Hecks
         include Readings
         include Shapes
 
+        # Reads one judged chapter back out of `runtime` and assembles it.
+        #
+        # @param runtime [Runtime::Dispatcher] the dispatcher holding the
+        #   judge's own records
+        # @param chapter [String] the chapter's own `hecks_name`
+        # @return [Hash{Symbol => Object}] the reconstructed IR, in the
+        #   shape the DSL builder's own `to_h` produces
+        # @raise [Runtime::NotFound] if `runtime` holds no bluebook named
+        #   `chapter`
         def self.of(runtime, chapter) = new(runtime, chapter).to_h
 
+        # @param runtime [Runtime::Dispatcher] the dispatcher holding the
+        #   judge's own records
+        # @param chapter [String] the chapter's own `hecks_name`
+        # @raise [Runtime::NotFound] if `runtime` holds no bluebook named
+        #   `chapter`
         def initialize(runtime, chapter)
           @runtime = runtime
           @plan    = Plan.for(MetaValidator.grammar_registry)
           @chapter = runtime.query("Bluebook::Bluebook.Called", name: { value: chapter }).first or
-            raise NotFound, "the meta-domain holds no bluebook called #{chapter.inspect}"
+            raise Runtime::NotFound, "the meta-domain holds no bluebook called #{chapter.inspect}"
         end
 
         def to_h

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

@@ -14,6 +14,14 @@ module Hecks
       module Shapes
         # The type came in as the id of what it names, so it goes back out as the
         # name — or, for another aggregate's head, as the encoding the IR spells.
+        #
+        # @param field [Hash{Symbol => Object}] one dispatched attribute row
+        # @param aggregate_id [String] the owning aggregate's own id, to
+        #   strip from an owned value-object type
+        # @return [Hash{Symbol => Object}] `:name` (`Symbol`, `nil`),
+        #   `:type` (`String`), `:list`/`:optional` (`Boolean`), `:default`
+        #   (decoded literal, `nil` when absent), `:pattern`/`:admits`/
+        #   `:relationship` (`String`, `nil` when absent)
         def attribute(field, aggregate_id)
           type = text(field[:type]).to_s
 
@@ -39,6 +47,12 @@ module Hecks
         # A type this aggregate owns, offered as its id and read back as its name.
         # Prefixed with the owner and the identity join, because that is the value
         # object's identity — the aggregate it belongs to, then its name.
+        #
+        # @param type [String] the attribute's own dispatched `type` cell
+        # @param aggregate_id [String] the owning aggregate's own id
+        # @return [String, nil] `type` with the owner's own identity prefix
+        #   stripped, or `nil` if `type` does not carry that prefix (an
+        #   ordinary type name, or a cross-aggregate reference)
         def owned_type(type, aggregate_id)
           prefix = Naming.identity([aggregate_id, ""])
           return nil unless type.start_with?(prefix)
@@ -49,6 +63,9 @@ module Hecks
         # One part of an identity, read back as the path it went in as. The inverse
         # of `Marks#identity_path`, and named the same so the two directions read
         # as one table.
+        #
+        # @param part [Hash{Symbol => Object}] one dispatched identity-part row
+        # @return [String] the identity part's own path text
         def identity_path(part) = text(part[:value]).to_s
 
         # An argument, a parameter, a piece's attribute — the three places an
@@ -76,6 +93,15 @@ module Hecks
         # ordinary type names something declared beside it (`Money`,
         # `AccountNumber`) and never carries a chapter, while a head's id
         # always does.
+        #
+        # @param field [Hash{Symbol => Object}] one dispatched attribute,
+        #   argument, or parameter row
+        # @param aggregate_id [String, nil] the piece's own owning
+        #   aggregate id, passed only for a piece's own attribute
+        # @return [Hash{Symbol => Object}] `:name` (`Symbol`, `nil`),
+        #   `:type` (`String`), `:list`/`:optional` (`Boolean`), `:default`
+        #   (decoded literal, `nil` when absent), `:pattern`/`:admits`/
+        #   `:relationship` (`String`, `nil` when absent)
         def shape_field(field, aggregate_id = nil)
           return attribute(field, aggregate_id) if aggregate_id
 
@@ -102,6 +128,11 @@ module Hecks
         # is a real regex (it matches everything), so keeping it would turn
         # "no pattern" into "a pattern that always passes" and quietly cost the
         # IR its round trip.
+        #
+        # @param text [String, nil] a dispatched cell's own already-unwrapped
+        #   text
+        # @return [String, nil] `text`, or `nil` when `text` is `nil` or
+        #   empty
         def presence(text)
           value = text.to_s
           value.empty? ? nil : value
@@ -113,13 +144,29 @@ module Hecks
         # String, Integer, Float, TrueClass, FalseClass — plus a symbol, and an
         # object literal, which is what `to: { value: "good" }` is: a value object's
         # fields written inline.
+        #
+        # @param text [String, nil] the self-describing wire spelling
+        #   `Readings#encode_literal` wrote
+        # @return [Object] `nil`, `true`, `false`, `Integer`, `Float`,
+        #   `Symbol`, `Hecks::StateRef`, `String`, `Hash`, or `Array` — or
+        #   `text` itself, stripped, when it matches no known spelling
         def decode_literal(text) = Literal.read(text)
 
+        # Reads a rule's plain description/canonical pair, for a
+        # `given`/`invariant`/`ensures`.
+        #
+        # @param row [Hash{Symbol => Object}] one dispatched rule row
+        # @return [Hash{Symbol => String}] `:description` and `:canonical`
         def rule(row) = { description: text(row[:description]), canonical: text(row[:canonical]) }
 
         # S12, ADR 0025 — `projects :name, from: :"reference.remote_field"`,
         # read back the same three plain identifiers `rule` above reads
         # description/canonical as.
+        #
+        # @param row [Hash{Symbol => Object}] one dispatched projected-field
+        #   row
+        # @return [Hash{Symbol => String}] `:name`, `:reference`, and
+        #   `:remote_field`
         def projected_field(row)
           { name: text(row[:name]), reference: text(row[:reference]), remote_field: text(row[:remote_field]) }
         end
@@ -128,16 +175,30 @@ module Hecks
         # does — an object literal, self-describing via Hecks::Literal — one
         # level up: a whole keyword's argument rather than an attribute's
         # `default:`.
+        #
+        # @param row [Hash{Symbol => Object}] a dispatched row carrying a
+        #   `:provenance` cell
+        # @return [Object] the decoded `from:` object literal, or `nil` when
+        #   absent
         def provenance(row) = decode_literal(text(row[:provenance]))
 
         # `command "Debit", from: "open"` — the same literal encoding
         # `provenance`/`default:` already ride (S10, ADR 0025), one
         # state or an array of them, or nil for a command with no
         # lifecycle guard.
+        #
+        # @param row [Hash{Symbol => Object}] a dispatched row carrying a
+        #   `:from` cell
+        # @return [String, Array<String>, nil] the decoded lifecycle guard
+        #   state(s), or `nil` for a command with no lifecycle guard
         def from(row) = decode_literal(text(row[:from]))
 
         # A flag is held as text ("true"/"false") and emitted as a boolean —
         # `Policy#expect_undelivered` on the wire.
+        #
+        # @param row [Hash{Symbol => Object}] a dispatched row carrying an
+        #   `:expect_undelivered` cell
+        # @return [Boolean] whether the flag reads `"true"`
         def expect_undelivered?(row) = text(row[:expect_undelivered]).to_s == "true"
 
         # The option rows, gathered back into the shapes `extra_options_to_h` spells.
@@ -146,12 +207,25 @@ module Hecks
         # several groups told apart by `at`. Grouping by option name and then by `at`
         # rebuilds both without either knowing which options exist — the whole point
         # of holding them as an open map.
+        #
+        # @param row [Hash{Symbol => Object}] a dispatched row carrying an
+        #   `:options` list
+        # @return [Hash{Symbol => Object}] one entry per option name; each
+        #   value is `gathered`'s own return for that option's own parts
         def options_of(row)
           Array(row[:options])
             .group_by { |part| text(part[:option]) }
             .to_h { |option, parts| [option.to_sym, gathered(parts)] }
         end
 
+        # Groups one option's own dispatched parts back into a single
+        # binding, or several `at`-keyed groups for a repeated option.
+        #
+        # @param parts [Array<Hash{Symbol => Object}>] one option's own
+        #   dispatched key/value/at rows
+        # @return [Hash{Symbol => String}, Array<Hash{Symbol => String}>]
+        #   a single `key => value` hash when no part carries `at`;
+        #   otherwise an array of such hashes, one per distinct `at`
         def gathered(parts)
           repeated, single = parts.partition { |part| !text(part[:at]).to_s.empty? }
           return single.to_h { |part| [text(part[:key]).to_sym, text(part[:value])] } if repeated.empty?
@@ -170,11 +244,20 @@ module Hecks
         # back out as the plain string "ceiling", indistinguishable from a
         # literal of the same name. One decode, at the one place that builds
         # the object every comparator actually reads.
+        #
+        # @param row [Hash{Symbol => Object}] one dispatched where-clause row
+        # @return [Hash{Symbol => String}] `:field`, `:op`, and `:value`
+        #   (raw text, undecoded)
         def where_clause(row)
           { field: text(row[:field]), op: text(row[:op]), value: text(row[:value]) }
         end
 
         # One object in the IR, two fields in the language.
+        #
+        # @param row [Hash{Symbol => Object}] a dispatched row carrying
+        #   `:order_field`/`:order_way` cells
+        # @return [Hash{Symbol => String}, nil] `:field` and `:direction`,
+        #   or `nil` when no `order_field` was declared
         def order_by(row)
           field = text(row[:order_field])
           return nil if field.to_s.empty?
@@ -182,6 +265,12 @@ module Hecks
           { field: field, direction: text(row[:order_way]) }
         end
 
+        # Reads a read model's own declared row limit.
+        #
+        # @param row [Hash{Symbol => Object}] a dispatched row carrying a
+        #   `:limit` cell
+        # @return [Hash{Symbol => String}, nil] `{value: ceiling}`, or `nil`
+        #   when no limit was declared
         def limit(row)
           ceiling = text(row[:limit])
           return nil if ceiling.to_s.empty?
@@ -189,6 +278,12 @@ module Hecks
           { value: ceiling }
         end
 
+        # Reads one lifecycle transition row.
+        #
+        # @param row [Hash{Symbol => Object}] one dispatched lifecycle
+        #   transition row
+        # @return [Hash{Symbol => String}] `:command`, `:from_state`, and
+        #   `:to_state`
         def transition(row)
           {
             command:    text(row[:command]),
@@ -197,6 +292,13 @@ module Hecks
           }
         end
 
+        # Reads one reference head — a process manager handler's own
+        # aggregate binding.
+        #
+        # @param row [Hash{Symbol => Object}] one dispatched reference-head
+        #   row
+        # @return [Hash{Symbol => Object}] `:aggregate`/`:as` (`String`) and
+        #   `:many` (`Boolean`)
         def head(row)
           {
             aggregate: text(row[:aggregate]),
@@ -207,6 +309,11 @@ module Hecks
           }
         end
 
+        # Reads a read model's own `group_by` field name.
+        #
+        # @param row [Hash{Symbol => Object}] a dispatched row carrying a
+        #   `:field` cell
+        # @return [Hash{Symbol => String}] `{field: ...}`
         def group_by_field(row) = { field: text(row[:field]) }
 
         # `count`'s own boolean, read back the same way `head`'s own
@@ -219,6 +326,11 @@ module Hecks
         # `true`/`nil` pair (never `false`) exactly, rather than the
         # unconditional `true`/`false` `head`'s own `many` needs (every
         # head does get a `Gather` dispatch, declared or derived).
+        #
+        # @param row [Hash{Symbol => Object}] a dispatched row carrying a
+        #   `:count` cell
+        # @return [Boolean, nil] `true` when the flag reads `"true"`, `nil`
+        #   for an undeclared read model's own `count`
         def read_model_count(row) = (true if text(row[:count]).to_s == "true")
 
         # The append flattening, in reverse.
@@ -227,6 +339,11 @@ module Hecks
         # field/kind/source triple, so the walk offers an append once per binding.
         # Rebuilding groups those rows back into the single mutation the IR keeps —
         # the only place here that undoes something rather than simply reading it.
+        #
+        # @param row [Hash{Symbol => Object}] a dispatched row carrying a
+        #   `:mutations` list
+        # @return [Array<Hash{Symbol => Object}>] one hash per distinct
+        #   `target`/`op` pair, each `mutation`'s own return
         def mutations(row)
           Array(row[:mutations])
             .group_by { |change| [text(change[:target]), text(change[:op])] }
@@ -242,6 +359,16 @@ module Hecks
         # Mutation's own `to_h` lambda does, rather than leaving the key
         # silently absent (spec/round_trip_spec's whole point: a field the
         # language does not hold is a named gap, not a byte-for-byte one).
+        #
+        # @param target [String] the mutated field's own name
+        # @param oper [String] the mutation's operation name, such as
+        #   `"set"`, `"append"`, `"delegate"`, or `"corrects"`
+        # @param bindings [Array<Hash{Symbol => Object}>] this target/op
+        #   pair's own dispatched binding rows
+        # @return [Hash{Symbol => Object}] `:target`/`:op` (`Symbol`),
+        #   `:sign` (`String`), plus `:fields` (`appended`'s own return) for
+        #   `"append"`/`"delegate"`/`"corrects"`, or `:source`
+        #   (`classified`'s own return) for anything else
         def mutation(target, oper, bindings)
           base = { target: target.to_sym, op: oper.to_sym, sign: Hecks::Bluebook::Mutation.sign_for(oper) }
           # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
@@ -252,10 +379,24 @@ module Hecks
           base.merge(source: classified(bindings.first))
         end
 
+        # Rebuilds an append's own field -> source map from its flattened
+        # per-binding rows.
+        #
+        # @param bindings [Array<Hash{Symbol => Object}>] one append's own
+        #   dispatched binding rows
+        # @return [Hash{Symbol => String}] each bound field name mapped to
+        #   its own source text
         def appended(bindings)
           bindings.to_h { |binding| [text(binding[:field]).to_sym, text(binding[:source])] }
         end
 
+        # Classifies a single-binding mutation's own source.
+        #
+        # @param binding [Hash{Symbol => Object}] one dispatched binding row
+        # @return [Hash{Symbol => Object}] `{kind: "argument"|"state",
+        #   name: String}` for an argument or state reference, or
+        #   `{kind: "literal", value: Object}` (the decoded literal) for
+        #   anything else
         def classified(binding)
           kind  = text(binding[:kind])
           value = text(binding[:source])

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

@@ -10,23 +10,27 @@ module Hecks
       # coercion/lifecycle-guard door every other command goes through),
       # not merely declared and never exercised.
       #
-      # **The source stays static**. Aggregate-local `KeywordSeed`/
-      # `ArgumentSeed` value objects (still hand-written `member` rows —
-      # now beside the concepts they spell) are what gets written ; this
-      # is what turns them into what gets read. `Judge`/`Reconstruction`
-      # already draw exactly this line everywhere else in the meta-domain
-      # (a chapter's own declarations versus what gets dispatched from
-      # them) — this runs the same distinction one level further out, for
-      # the language's own grammar table.
+      # ## The source stays static
       #
-      # A dedicated runtime, not `MetaValidator.fresh_runtime`. That one
-      # is reserved for `Judge`'s own bootstrap (dispatching a chapter's
-      # declarations into the meta-domain's grammar) — a different act
-      # from this one (dispatching the meta-domain's own grammar table
-      # data into a live "Bluebook" domain instance). Sharing the runtime
-      # would let one boot's own repository state leak into the other's.
+      # Aggregate-local `KeywordSeed`/`ArgumentSeed` value objects (still
+      # hand-written `member` rows — now beside the concepts they spell)
+      # are what gets written ; this is what turns them into what gets
+      # read. `Judge`/`Reconstruction` already draw exactly this line
+      # everywhere else in the meta-domain (a chapter's own declarations
+      # versus what gets dispatched from them) — this runs the same
+      # distinction one level further out, for the language's own grammar
+      # table.
       #
-      # Usage:
+      # ## A dedicated runtime
+      #
+      # Not `MetaValidator.fresh_runtime`. That one is reserved for
+      # `Judge`'s own bootstrap (dispatching a chapter's declarations into
+      # the meta-domain's grammar) — a different act from this one
+      # (dispatching the meta-domain's own grammar table data into a live
+      # "Bluebook" domain instance). Sharing the runtime would let one
+      # boot's own repository state leak into the other's.
+      #
+      # ## Usage
       #
       #   MetaValidator.syntax_table  # => { keywords: [...], arguments: [...] }
       #
@@ -76,6 +80,9 @@ module Hecks
         # tracked. Holding the chapter objects themselves (not their ids)
         # in the key also means a collected chapter can never hand its id
         # to a newcomer behind this cache's back.
+        # @return [Hash{Symbol => Array<Hash{Symbol => String}>}] `:keywords`
+        #   and `:arguments`, each an array of plain, string-valued row
+        #   hashes (`status` included)
         def call
           chapters = MetaValidator.grammar_registry.bluebooks.to_a
           return @call if @call && same_chapters?(@call_chapters, chapters)
@@ -91,6 +98,15 @@ module Hecks
           result
         end
 
+        # Compares the in-process cache key against the registry's current
+        # chapters.
+        #
+        # @param cached [Array<Array(String, Object)>] the `[name, chapter]`
+        #   pairs `call` last cached against
+        # @param current [Array<Array(String, Object)>] the registry's
+        #   current `[name, chapter]` pairs
+        # @return [Boolean] whether `cached` and `current` name the same
+        #   chapters, by identity, in the same order
         def same_chapters?(cached, current)
           cached.size == current.size &&
             cached.zip(current).all? do |(cached_name, cached_chapter), (name, chapter)|
@@ -152,8 +168,19 @@ module Hecks
         # be ruled out while debugging something else entirely.
         CACHE_DIR = File.expand_path("../../../../tmp/hecks_syntax_boot_cache", __dir__).freeze
 
+        # Reports whether the cross-process disk cache is turned on.
+        #
+        # @return [Boolean] whether the cross-process disk cache is turned
+        #   on (`HECKS_SYNTAX_BOOT_CACHE=off` turns it off)
         def disk_cache_enabled? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
 
+        # Reads an already-written cache entry for `chapters`, if any.
+        #
+        # @param chapters [Array<Array(String, Object)>] the `[name,
+        #   chapter]` pairs to key the cache entry on
+        # @return [Hash{Symbol => Array<Hash{Symbol => String}>}, nil] the
+        #   cached syntax table, or `nil` if the cache is disabled, no entry
+        #   exists yet, or the entry could not be read
         def read_disk_cache(chapters)
           return nil unless disk_cache_enabled?
 
@@ -165,6 +192,13 @@ module Hecks
           nil
         end
 
+        # Writes `result` to the disk cache for `chapters`, atomically.
+        #
+        # @param chapters [Array<Array(String, Object)>] the `[name,
+        #   chapter]` pairs to key the cache entry on
+        # @param result [Hash{Symbol => Array<Hash{Symbol => String}>}] the
+        #   syntax table to persist
+        # @return [void]
         def write_disk_cache(chapters, result)
           return unless disk_cache_enabled?
 
@@ -177,10 +211,21 @@ module Hecks
           nil
         end
 
+        # Builds the disk cache file path for `chapters`.
+        #
+        # @param chapters [Array<Array(String, Object)>] the `[name,
+        #   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")
         end
 
+        # Builds the cache key for `chapters`.
+        #
+        # @param chapters [Array<Array(String, Object)>] the `[name,
+        #   chapter]` pairs to key the cache entry on
+        # @return [String] a SHA-256 digest of the chapter names and the
+        #   current grammar source
         def disk_cache_key(chapters)
           names = chapters.map { |name, _chapter| name }
           Digest::SHA256.hexdigest("#{names.join(',')}:#{grammar_content_digest}")
@@ -196,12 +241,20 @@ module Hecks
         # chapter it belongs to) — deliberately, since under-covering this
         # set is a correctness bug (a stale table survives a real grammar
         # edit) and over-covering it is only ever a wasted cache miss.
+        # @return [String] a SHA-256 digest of every grammar file's own
+        #   current content, sorted for a stable digest
         def grammar_content_digest
           files = (MetaValidator::GRAMMAR_FILES + MetaValidator::WORLD_GRAMMAR + MetaValidator::HECKSAGON_GRAMMAR +
                     Dir.glob(File.join(MetaValidator::ATTACHED_GRAMMAR_DIR, "*.bluebook"))).sort
           Digest::SHA256.hexdigest(files.map { |file| File.read(file) }.join("\0"))
         end
 
+        # Dispatches every seed row into a fresh "Bluebook" instance and
+        # reads the result back.
+        #
+        # @return [Hash{Symbol => Array<Hash{Symbol => String}>}] `:keywords`
+        #   and `:arguments`, each an array of plain, string-valued row
+        #   hashes (`status` included)
         def boot
           bluebook = MetaValidator.grammar_registry.bluebook("Bluebook")
           # `MetaValidator.fresh_runtime`, not a brand-new `Runtime::
@@ -222,21 +275,35 @@ module Hecks
           read_back(runtime, bluebook)
         end
 
+        # Wraps `text` as a single-field value-object payload, for a
+        # dispatch's own `with:`.
+        #
         # An Integer stays an Integer — `position` is `Position`-typed
         # (`attribute :value, Integer`), so stringifying it fails the type
         # gate rather than feeding it, the same reading `Judge#v` gives.
+        #
+        # @param text [String, Integer] the scalar to wrap
+        # @return [Hash{Symbol => String, Integer}] `{value: text}`,
+        #   stringified unless `text` is already an Integer
         def v(text)
           return { value: text } if text.is_a?(Integer)
 
           { value: text.to_s }
         end
 
+        # Wraps `text` as an `optional: true` command argument's own
+        # payload, or omits it.
+        #
         # Absent stays absent. A seed row's own optional columns ("was",
         # "at", "named", ...) are empty strings, not nil — `Literal`/CSV-
         # shaped grammar data has no `nil` to write — so this is the one
         # place that decides "" means "not given" for the purpose of an
         # `optional: true` command argument, the same reading `Judge#v`
         # makes for the meta-domain's own dispatches.
+        #
+        # @param text [String, nil] the seed row's own column value
+        # @return [Hash{Symbol => String}, nil] `v(text)`, or `nil` when
+        #   `text` is `nil` or empty
         def optional(text)
           return nil if text.nil? || text.to_s.empty?
 
@@ -251,6 +318,13 @@ module Hecks
         # declared first, named after the real chapter, purely to satisfy
         # the reference — its own vision/classification are never read
         # by anything this boot does.
+        #
+        # @param runtime [Runtime::Dispatcher] the fresh runtime to
+        #   dispatch into
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read for its `hecks_name` and `"Syntax"`
+        #   aggregate
+        # @return [void]
         def declare_syntax(runtime, bluebook)
           syntax = bluebook.aggregate("Syntax")
           runtime.dispatch("Bluebook::Bluebook.Declare",
@@ -264,14 +338,19 @@ module Hecks
 
         # `to: "Syntax"` names the record already opened by `declare_syntax`
         # above — an append onto an existing aggregate, not a second creation
-        # of it. This used to smuggle `name: v("Syntax")` into the payload
-        # instead, the pre-routing convention `Judge#appends` (the same
-        # append shape, for `ValueObject.Member`/`ProcessManager.Handler`)
-        # already left behind for `to:`/`with:` — carrying the receiver in
-        # the payload made `Syntax.Keyword`'s own `command.creates?` (true:
-        # it declares no `reference_to`) look like a fresh identity to mint,
-        # which collided with the very "Syntax" row `declare_syntax` had
-        # just opened.
+        # of it. Smuggling `name: v("Syntax")` into the payload instead — the
+        # pre-routing convention `Judge#appends` (the same append shape, for
+        # `ValueObject.Member`/`ProcessManager.Handler`) already left behind
+        # for `to:`/`with:` — would carry the receiver in the payload,
+        # making `Syntax.Keyword`'s own `command.creates?` (true: it
+        # declares no `reference_to`) look like a fresh identity to mint,
+        # colliding with the very "Syntax" row `declare_syntax` just opened.
+        #
+        # @param runtime [Runtime::Dispatcher] the fresh runtime to
+        #   dispatch into
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read for its `KeywordSeed` rows
+        # @return [void]
         def admit_keywords(runtime, bluebook)
           all_rows(bluebook, "KeywordSeed").each_with_index do |row, index|
             runtime.dispatch("Bluebook::Syntax.Keyword", to:   "Syntax",
@@ -289,6 +368,14 @@ module Hecks
           end
         end
 
+        # Admits every `ArgumentSeed` row as a `Syntax.Argument`, the same
+        # `to: "Syntax"` append shape `admit_keywords` uses one type over.
+        #
+        # @param runtime [Runtime::Dispatcher] the fresh runtime to
+        #   dispatch into
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read for its `ArgumentSeed` rows
+        # @return [void]
         def admit_arguments(runtime, bluebook)
           all_rows(bluebook, "ArgumentSeed").each_with_index do |row, index|
             runtime.dispatch("Bluebook::Syntax.Argument", to:   "Syntax",
@@ -315,6 +402,14 @@ module Hecks
         # Port, Adapter, Translation), and attached sub-languages alike.
         # Concatenated into one sequence because `position` is minted from the
         # walk index and must not collide across concepts.
+        #
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read first, before every other loaded
+        #   chapter
+        # @param name [String] the local value-object name to collect rows
+        #   of, such as `"KeywordSeed"`
+        # @return [Array<Hash{Symbol => String}>] every matching row, across
+        #   every loaded chapter, in chapter order
         def all_rows(bluebook, name)
           seed_chapters(bluebook).flat_map { |chapter| rows(chapter, name) }
         end
@@ -323,6 +418,11 @@ module Hecks
         # sibling/extension. The name rejection avoids reading the same core
         # object twice without relying on object identity across fixpoint
         # assembly.
+        #
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter
+        # @return [Array<Bluebook::Chapter>] `bluebook` first, then every
+        #   other chapter the grammar registry holds
         def seed_chapters(bluebook)
           [bluebook] + MetaValidator.grammar_registry.bluebooks.values.reject { |chapter| chapter.name == bluebook.name }
         end
@@ -331,6 +431,13 @@ module Hecks
         # every aggregate that owns a same-named local value object. Repeating
         # the value-object shape is deliberate: each concept remains readable
         # by itself, while this discovery is the only grouping mechanism.
+        #
+        # @param bluebook [Bluebook::Chapter] the chapter to search
+        # @param name [String] the local value-object name to collect rows
+        #   of, such as `"KeywordSeed"`
+        # @return [Array<Hash{Symbol => String}>] one hash per member row,
+        #   `[]` if no aggregate in `bluebook` owns a value object named
+        #   `name`
         def rows(bluebook, name)
           bluebook.aggregates.flat_map do |aggregate|
             value_object = aggregate.value_objects.find { |vo| vo.hecks_name == name }
@@ -344,6 +451,14 @@ module Hecks
         # above hands the seed data in as — plain hashes, string values,
         # `status` included — so `ParserTable`/`syntax_conformance_spec`
         # need not know or care that a real dispatch happened in between.
+        #
+        # @param runtime [Runtime::Dispatcher] the runtime `boot` dispatched
+        #   every seed row into
+        # @param bluebook [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter, read for its `"Syntax"` aggregate
+        # @return [Hash{Symbol => Array<Hash{Symbol => String}>}] `:keywords`
+        #   and `:arguments`, each an array of plain, string-valued row
+        #   hashes (`status` included)
         def read_back(runtime, bluebook)
           syntax = bluebook.aggregate("Syntax")
           repository = runtime.registry.repository("Bluebook", syntax)
@@ -355,12 +470,23 @@ module Hecks
           }
         end
 
+        # Flattens one dispatched record into a plain, string-valued row.
+        #
+        # @param row [Object] one dispatched keyword or argument record,
+        #   answering `to_h`
+        # @return [Hash{Symbol => String}] `row`'s own fields, each value
+        #   unwrapped and stringified
         def stringify(row)
           row.to_h.transform_values do |cell|
             scalar(cell).to_s
           end
         end
 
+        # Unwraps one field's stored value to its bare scalar.
+        #
+        # @param cell [Object] one field's stored value
+        # @return [Object] `cell`'s sole wrapped value, if `cell` is a
+        #   to_h-able non-String; `cell` unchanged otherwise
         def scalar(cell)
           return cell.to_h.values.first if cell.respond_to?(:to_h) && !cell.is_a?(String)