hecks 2.8.0 → 2.9.0

data/lib/hecks/ports/query/in_memory.rb

@@ -6,12 +6,8 @@ require_relative "../../query_specification/common/comparison"
 module Hecks
   module Ports
     module Query
-      # In-memory implementation of a declared query specification:
-      # applies wheres/order_by/offset/limit directly to an Array of
-      # records instead of compiling SQL. Deliberately kept in exact
-      # LIMIT/OFFSET-order agreement with SqlQueryBuilder (see #execute's
-      # own comment) so a query answers the same page regardless of
-      # which adapter backs it.
+      # Applies wheres, order_by, offset and limit to an Array of records, in the same order
+      # as `SqlQueryBuilder` so every adapter answers the same page.
       module InMemory
         FieldPath = QuerySpecification::FieldPath
         Comparison = QuerySpecification::Common::Comparison
@@ -20,17 +16,12 @@ module Hecks
 
         # Filters, orders and pages `records` against a declared query specification.
         #
-        # @param records [Array<Runtime::Instance, Hash>] the candidate records to filter —
-        #   an Instance, a Value, or a plain row hash per record (see `FieldPath.dig`)
-        # @param declared [QuerySpecification::Common::Options,
-        #   Bluebook::Behaviour::ReadModel::FilteredOptions] the specification providing
-        #   `wheres`, `order_by`, `offset` and `limit`
-        # @param args [Hash{Symbol => Object}] bound values for any Symbol placeholder in a
-        #   where clause, `offset`, or `limit`
-        # @param registry [Runtime::Registry, nil] the booted registry, passed through to a
-        #   registry-aware comparison; nil when none is available
-        # @return [Array<Runtime::Instance, Hash>] the matching records, ordered and paged;
-        #   the same element type as `records`
+        # @param records [Array<Runtime::Instance, Hash>] the candidates
+        # @param declared [QuerySpecification::Common::Options] provides `wheres`, `order_by`,
+        #   `offset` and `limit`
+        # @param args [Hash{Symbol => Object}] values for Symbol placeholders
+        # @param registry [Runtime::Registry, nil] passed to registry-aware comparisons
+        # @return [Array<Runtime::Instance, Hash>] the matching records, ordered and paged
         def execute(records, declared, args = {}, registry: nil)
           matched = records.select do |record|
             declared.wheres.all? do |clause|
@@ -40,58 +31,19 @@ module Hecks
           field   = declared.order_by&.field
           matched = Ordering.apply(matched, declared.order_by, declared.null_semantics,
                                    identity: ->(record) { record.id.to_s }) { |record| comparable(FieldPath.dig(record, field)) }
-          # **Offset first, then limit** — the order SQL means by `LIMIT n
-          # OFFSET m`, which is what `SqlQueryBuilder` emits and therefore
-          # what every SQL-backed aggregate already answers. Written the
-          # other way round here, and the two engines disagreed on the
-          # same declaration: `limit 2, offset 1` over three rows is rows
-          # two and three in Postgres and Sqlite, and was row two alone in
-          # memory. Silently — a short page reads exactly like a page that
-          # ran out of rows.
-          #
-          # It gets worse the further you page, which is the case nobody
-          # writing the first page ever sees: at `limit 10, offset 10`,
-          # taking ten and then dropping ten leaves nothing, so page two
-          # of a memory-backed query came back empty however many rows
-          # were really there.
+          # Offset before limit, as SQL means `LIMIT n OFFSET m`; the reverse order returns a short
+          # or empty page (`limit 10, offset 10` would drop everything).
           matched = matched.drop(resolve(declared.offset.value, args).to_i) if declared.offset
           matched = matched.first(resolve(declared.limit.value, args).to_i) if declared.limit
           matched
         end
 
-        # The comparator table itself lives in
-        # QuerySpecification::Common::Comparison, not duplicated per
-        # caller — this module and Runtime::QueryInterpreter drifted
-        # when each carried its own copy (see that file's own comment
-        # for what it cost). What stays here is how a value is reached
-        # for this path: a registry arrives as an argument rather than
-        # as instance state, and the field is dug through FieldPath
-        # before it arrives.
-        # @param clause [QuerySpecification::Common::WhereClause] the declared comparison
-        # @param held [Object, nil] the record's own value for `clause.field`
-        # @param args [Hash{Symbol => Object}] bound values for a Symbol-named `clause.value`
-        # @param registry [Runtime::Registry, nil] used only by `none_in_state`; see
-        #   `Comparison.holds?`
-        # @return [Boolean] whether the comparison holds
-        # @raise [Runtime::WiringError] if `clause.op` names no comparator in
-        #   `Comparison`'s table, or `none_in_state`'s target aggregate has no wired repository
         def holds?(clause, held, args, registry: nil)
           Comparison.holds?(clause.op, held, comparable(resolve(clause.value, args)), registry: registry)
         end
 
-        # Resolves a where-clause value, looking up a Symbol placeholder in `args`.
-        #
-        # @param value [Object] a literal value, or a Symbol naming a key in `args`
-        # @param args [Hash{Symbol => Object}] bound argument values
-        # @return [Object] `args[value]` when `value` is a Symbol, else `value` unchanged
         def resolve(value, args) = value.is_a?(Symbol) ? args[value] : value
 
-        # Normalises a value into the shape `Comparison` compares against.
-        #
-        # @param value [Runtime::Value, Hash, Object, nil] a held or wanted value; a
-        #   `Runtime::Value` is read through its `to_h`
-        # @return [Object, nil] the sole numeric member, or the sole member, of a Hash-shaped
-        #   value; otherwise `value` unchanged
         def comparable(value) = Comparison.comparable(value)
       end
     end

data/lib/hecks/ports/query/ordering.rb

@@ -3,46 +3,25 @@ require_relative "../../query_specification/common/null_policy"
 module Hecks
   module Ports
     module Query
-      # What order an ask answers in — the meaning of the ask, not a property
-      # of the store that happens to hold it. Declared here once so an adapter
-      # may satisfy it natively but never redefine it : SQLite pushes both
-      # tiers into SQL (NullPolicy.sql_order renders `field DIR, id DIR`),
-      # while Heki and Memory have no query engine and delegate straight back
-      # to InMemory.
+      # The order an ask answers in: the declared order_by, then identity as a total tiebreaker.
       #
-      # Two tiers, in this order : the declared order_by when there is one,
-      # then identity, always. The identity tier is what makes an ask total.
-      # Without it, an ask with no order_by — or a declared order with tied
-      # keys — hands back whatever order the store happened to hold, and
-      # store order was quietly standing in for a rule while every
-      # hand-written query in the corpus stayed green : not one of them
-      # had a tie for store order to decide.
-      #
-      # An adapter that pushes ordering down must push limit down with it.
-      # Re-ordering a page the store already cut would be a top-N of the
-      # wrong N — the one way this can be got quietly, expensively wrong.
+      # An adapter that pushes ordering down must push limit down with it; re-ordering
+      # a page the store already cut yields a top-N of the wrong N.
       module Ordering
         module_function
 
-        # Orders an Array of rows by the declared order, with identity as the total-order
-        # tiebreaker.
+        # Orders rows by `order_by`, breaking ties by `identity`.
         #
-        # @param rows [Array<Object>] the rows to order; any shape `identity` and the block
-        #   can read (a `Runtime::Instance`, a plain Hash row, …)
-        # @param order_by [QuerySpecification::Common::OrderBy, nil] the declared order;
-        #   nil orders by identity alone
-        # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] where a
-        #   nil-valued row sorts, passed to `NullPolicy.order`; nil uses its native default
-        # @param identity [Proc] yields a row, returns its comparable identity value, used
-        #   as the stable tiebreaker
+        # @param rows [Array<Object>] the rows to order
+        # @param order_by [QuerySpecification::Common::OrderBy, nil] nil orders by identity alone
+        # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] where nil values
+        #   sort; nil uses the native default
+        # @param identity [Proc] returns a row's comparable identity value
         # @yieldparam row [Object] one row being ordered
         # @yieldreturn [Object, nil] the row's comparable value for `order_by`'s field
-        # @return [Array<Object>] `rows`, ordered by `order_by` then identity (identity
-        #   alone when `order_by` is nil)
+        # @return [Array<Object>] the ordered rows
         def apply(rows, order_by, null_semantics = nil, identity:, &value_of)
-          # Stable, because sort_by is not : two rows whose identity ties would
-          # otherwise swap arbitrarily, and a tier meant to remove store-dependence
-          # would be adding a coin flip of its own.
+          # The index keeps the sort stable; sort_by alone would order tied identities arbitrarily.
           rows = rows.each_with_index.sort_by { |row, index| [identity.call(row), index] }.map(&:first)
           return rows unless order_by
 

data/lib/hecks/ports/query.rb

@@ -1,39 +1,25 @@
 module Hecks
   module Ports
-    # Common query execution boundary. Adapters expose one optional native
-    # hook; all other query behavior remains in the shared interpreter.
-    # Ordering (the meaning of an ask's answer order) and InMemory (the
-    # fallback engine for stores with no query engine of their own) are
-    # its collaborators — query/ordering.rb and query/in_memory.rb.
+    # Query execution boundary: an adapter may expose one native `query` hook, and everything
+    # else runs in the shared interpreter (`query/ordering.rb`, `query/in_memory.rb`).
     module Query
-      # A declared query the chosen adapter cannot honour as written — refused
-      # by `validate!` before the adapter runs it.
+      # A declared query the chosen adapter cannot honour as written.
       class Unsupported < StandardError; end
 
       module_function
 
       # Runs a declared query through the adapter's own `query` hook, if it has one.
       #
-      # A nil answer means "no native engine here", and the caller falls back to the shared
-      # interpreter or to `InMemory.execute`; it never means "no rows", which is `[]`.
+      # nil means "no native engine here" and the caller falls back to `InMemory.execute`; no
+      # rows is `[]`.
       #
-      # @param repository [Persistence::AppendOnly, Object] the repository whose `adapter` is
-      #   asked, or a bare persistence adapter (anything that does not answer `adapter`)
-      # @param specification [QuerySpecification::Common::Options] the declared query: a
-      #   `Bluebook::Query`, a read-model specification, or a delegator wrapping one
-      # @param args [Hash{Symbol => Object}] the caller's arguments, which a where-clause,
-      #   limit or offset written as a Symbol reads its value from
-      # @param context [Hash{Symbol => Object}] passed through to the adapter: `domain:`,
-      #   `aggregate:` and, where a comparator needs one, `registry:`
-      # @return [Array<Runtime::Instance>, nil] the matching records, filtered, ordered and
-      #   paged by the adapter (`[]` when none match); nil if the adapter has no `query`
-      #   method
-      # @raise [Ports::Query::Unsupported] if the specification combines cursor and offset
-      #   pagination, or asks for inspection the adapter cannot provide
-      # @raise [Runtime::WiringError] if a where-clause names an operation no comparator
-      #   handles (raised by the in-memory engine behind `Memory`, `Heki` and the like)
-      # @raise [ArgumentError] if a SQL-backed adapter cannot compile a where-clause's
-      #   operator
+      # @param repository [Persistence::AppendOnly, Object] a repository, or a bare adapter
+      # @param specification [QuerySpecification::Common::Options] the declared query
+      # @param args [Hash{Symbol => Object}] values for Symbol-valued wheres, limit and offset
+      # @param context [Hash{Symbol => Object}] passed to the adapter: `domain:`, `aggregate:`,
+      #   and `registry:` where a comparator needs one
+      # @return [Array<Runtime::Instance>, nil] matches, or nil if the adapter has no `query`
+      # @raise [Ports::Query::Unsupported] see `validate!`
       def execute(repository, specification, args = {}, context: {})
         adapter = repository.respond_to?(:adapter) ? repository.adapter : repository
         return nil unless adapter.respond_to?(:query)
@@ -42,17 +28,8 @@ module Hecks
         adapter.query(specification, args, context: context)
       end
 
-      # Refuses a specification the adapter about to run it cannot honour.
-      #
-      # Inspection is honoured by an adapter with an `inspect_query` method, or, for the
-      # `"sql"` mode alone, by any adapter with a native `query`.
-      #
-      # @param specification [QuerySpecification::Common::Options] the declared query to check
-      # @param adapter [Object] the persistence adapter that would run it; only what it
-      #   responds to (`inspect_query`, `query`) is read
-      # @return [void]
-      # @raise [Ports::Query::Unsupported] if the specification declares both a cursor and
-      #   an offset, or asks for inspection the adapter cannot provide
+      # Refuses cursor with offset pagination, and inspection the adapter cannot provide (`"sql"`
+      # mode needs only a native `query`, other modes an `inspect_query` method).
       def validate!(specification, adapter)
         raise Unsupported, "a query cannot combine cursor and offset pagination" if specification.cursor && specification.offset
 

data/lib/hecks/ports.rb

@@ -1,15 +1,9 @@
 # Hecks::Ports
 #
-# The runtime's named boundaries. Each port is a file beside this one —
-# `ports/persistence.rb`, `ports/query.rb`, … — and a port with supporting
-# cast keeps it in a same-named directory (`ports/persistence/` holds the
-# binding policy, the journal-translation lineage, the repository factory).
-# The `.port` files beside them are the DSL declarations the meta-validator
-# and the Folder adapter load as data.
+# The runtime's named boundaries; each port is a file under `ports/`.
 
 module Hecks
-  # Declared empty here — each `ports/*.rb` file required below reopens it
-  # to add its own port; see the header comment above for what a port is.
+  # The runtime's named boundaries; each port is a file under `ports/`.
   module Ports
   end
 end

data/lib/hecks/projections/bootstrap_table.rb

@@ -2,28 +2,12 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # **The bootstrap-window fallbacks, projected** — lib/hecks/bluebook/dsl/
-    # bootstrap_table.rb rendered from the chapter's own Keyword rows.
+    # Projects lib/hecks/bluebook/dsl/bootstrap_table.rb from the chapter's Keyword rows.
+    # Committed, not built at boot: it is read before the grammar table exists.
     #
     #   Projector.call(:bootstrap_table, bluebook: <the Bluebook chapter>)
     #
-    # While `MetaValidator.bootstrapping?` the grammar table does not exist
-    # yet, so `WordGate#method_missing` and `RuleReference#lookup` cannot
-    # read `calls:`/`resolves_via:`/`disambiguator:` off it — this table is
-    # what they read instead.
-    #
-    # A partition, not a filter: every live row lands in the table, not only
-    # the ones a bootstrap chapter happens to call. Picking a subset by
-    # grepping which words the core chapters use during bootstrap would risk
-    # quietly dropping any word a chapter starts using later. Including
-    # every row instead costs nothing: a builder with its own `def` never
-    # reaches `method_missing` at all, so a row no bootstrap chapter calls
-    # is simply never read.
-    #
-    # The table cannot be built at boot for the same reason it exists: it
-    # is read before the grammar it comes from has been assembled. So it is
-    # committed, like lib/hecks/vocabulary.rb, and spec/bootstrap_table_
-    # spec.rb re-projects it in memory and refuses a diff.
+    # Every live row is included, not only those a bootstrap chapter calls.
     module BootstrapTable
       extend Projector::Target
 
@@ -45,20 +29,13 @@ module Hecks
 
       module_function
 
-      # Projects the bootstrap fallback table — the only real work this projector
-      # does, `bluebook` unused because the table is the whole language's grammar,
-      # not any one chapter's.
+      # Projects the bootstrap fallback table; both arguments are ignored (the table is
+      # the whole grammar) and exist for the `Projector::Target` calling convention.
       #
-      # @param bluebook [Bluebook::Chapter] ignored; present to satisfy the
-      #   `Projector::Target` calling convention
-      # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
-      #   `Projector::Target` calling convention
       # @return [String] the rendered `lib/hecks/bluebook/dsl/bootstrap_table.rb` source
       def call(bluebook:, options: {}) = render(bluebook)
 
-      # Retired rows are out of the language; admitted and deprecated rows
-      # still dispatch — the same `status != "retired"` reading
-      # `GenericDispatch.shape_for` gives the live table.
+      # Every keyword row that is not retired; admitted and deprecated rows still dispatch.
       #
       # @return [Array<Hash{Symbol => String}>] every non-retired keyword row, each with
       #   at least `:context`, `:word`, `:status`, `:calls`, `:resolves_via` and
@@ -67,11 +44,8 @@ module Hecks
         Bluebook::MetaValidator::SyntaxBoot.call[:keywords].reject { |row| row[:status] == "retired" }
       end
 
-      # `[context, word] => :method` — WordGate's own key order.
-      #
-      # An overloaded word has one row per argument shape, and they all
-      # name the same method. Two that don't would make the table keep
-      # whichever came last, so that is refused instead.
+      # `[context, word] => :method`, in WordGate's key order.
+      # Overloaded rows must all name the same method; a mismatch raises rather than last-wins.
       #
       # @param rows [Array<Hash{Symbol => String}>] the keyword rows to build from,
       #   defaulting to every live one
@@ -90,9 +64,7 @@ module Hecks
             end
       end
 
-      # `[word, context] => { resolves_via:, disambiguator: }` —
-      # RuleReference's own key order, blank columns omitted, the same
-      # shape its live `lookup` answers.
+      # `[word, context] => { resolves_via:, disambiguator: }`, in RuleReference's key order.
       #
       # @param rows [Array<Hash{Symbol => String}>] the keyword rows to build from,
       #   defaulting to every live one
@@ -106,13 +78,9 @@ module Hecks
         end
       end
 
-      # Renders the bootstrap table as committable Ruby source — `CALLS` and
-      # `RESOLVES` frozen Hash literals under the generated-file header.
+      # Renders the `CALLS` and `RESOLVES` frozen Hash literals as Ruby source.
       #
-      # @param _bluebook [Bluebook::Chapter] ignored; the table draws from the whole
-      #   language's grammar, not this argument
-      # @return [String] the full `lib/hecks/bluebook/dsl/bootstrap_table.rb` source,
-      #   ready to write to disk
+      # @return [String] the full `lib/hecks/bluebook/dsl/bootstrap_table.rb` source
       def render(_bluebook)
         rows = live_keywords
         calls_lines = calls(rows).map { |key, target| "          #{key.inspect} => #{target.inspect}" }

data/lib/hecks/projections/deploy/fargate/assembly.rb

@@ -5,25 +5,12 @@ module Hecks
   module Projections
     module Deploy
       module Fargate
-        # Fills the optional sections of a rendered Fargate template.
-        #
-        # The template text carries `# TMPL:<name>` marker lines where an
-        # optional section belongs. `apply` replaces each with what the stack's
-        # `Settings::Plan` calls for, and with nothing when the plan sets
-        # nothing there, so a world that uses none of the optional settings
-        # renders the template it always did.
+        # Fills the optional `# TMPL:<name>` sections of a rendered Fargate template with
+        # what the plan calls for, or nothing when a world uses none of them.
         module Assembly
           module_function
 
           # Replaces every optional-section marker in a rendered template.
-          #
-          # @param template [String] the rendered template holding `# TMPL:` marker lines
-          # @param plan [Settings::Plan] the stack's checked optional settings
-          # @param context [Hash{Symbol => Object}] `:stack_name`, `:vpc_ref`, `:listener_id`,
-          #   `:alb_id`, `:distribution_id` and `:db_secret_ref`
-          # @return [String] the template with the markers replaced
-          # @raise [ArgumentError] if `domain_env` removes a variable the generator does not set, or
-          #   the finished template declares one logical id or parameter twice
           def apply(template, plan, context)
             text = override_domain_env(template, plan.domain_env)
             sections(plan, context).each { |marker, block| text = Yaml.splice(text, marker, block) }

data/lib/hecks/projections/deploy/fargate/cdn.rb

@@ -7,38 +7,7 @@ module Hecks
     module Deploy
       module Fargate
         # The CloudFront distribution in front of the load balancer.
-        #
-        # With no `cdn` setting the stack gets `default_yaml`: the default
-        # certificate, one origin, and one behavior that caches nothing. A
-        # `cdn` setting replaces that with a distribution described by the
-        # world.
-        #
-        # ## Settings
-        #
-        # `cdn` is a hash with these optional keys:
-        #
-        # - `aliases`: hostnames the distribution answers to. Needs `certificate_arn`.
-        # - `certificate_arn`: an `ACM` certificate in us-east-1, or an intrinsic such as
-        #   `"!Ref CertArn"`.
-        # - `minimum_protocol`: the TLS policy for the certificate; `TLSv1.2_2021` by default.
-        # - `origin_id`: the id of the load-balancer origin; `<AlbId>Origin` by default.
-        # - `origin_ssl_protocols`: the TLS versions CloudFront may use to reach the origin, such
-        #   as `["TLSv1.2"]`.
-        # - `explicit_origin_ports`: false leaves `HTTPPort` and `HTTPSPort` unset; true by
-        #   default.
-        # - `origin_secret`: `{header:, parameter:}` sends a secret header to the origin, filled
-        #   from a `NoEcho` template parameter the stack declares under that name.
-        # - `extra_origins`: S3 origins, each `{id:, domain_name:, origin_access_control_id:}`.
-        # - `default_behavior`: `{origin:, viewer_protocol:, methods:, compress:, cache_policy:,
-        #   origin_request_policy:}`.
-        # - `behaviors`: entries of the same shape with a required `path`; the first match wins,
-        #   so order matters.
-        # - `retain`: true keeps the distribution when the stack is deleted or replaces it.
-        #
-        # A cache or origin-request policy is a managed policy's name (`caching_disabled`,
-        # `caching_optimized`, `all_viewer`, `all_viewer_except_host`, or `none` to omit an origin
-        # request policy) or the id of a policy in the account. `methods` is `all`, `read` or
-        # `get_head`.
+        # With no `cdn` setting the stack gets `default_yaml`; settings are in the DSL reference.
         module Cdn
           module_function
 
@@ -64,14 +33,6 @@ module Hecks
           HOSTNAME = /\A(\*\.)?([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z]{2,}\z/
 
           # Reads and checks the `cdn` setting.
-          #
-          # @param setting [Hash, nil] the world's `cdn` value, or nil when it sets none
-          # @param default_origin_id [String] the load-balancer origin's id when `origin_id` is not
-          #   set
-          # @return [Hash{Symbol => Object}, nil] the checked options with defaults applied, or nil
-          #   for none
-          # @raise [ArgumentError] if an option is unknown, malformed, or names an origin that does
-          #   not exist
           def normalize(setting, default_origin_id:)
             return nil if setting.nil?
 
@@ -87,9 +48,6 @@ module Hecks
           end
 
           # Lists the template parameters the options need.
-          #
-          # @param options [Hash, nil] the checked options from `normalize`
-          # @return [String] flush-left parameter text, or empty
           def parameters_yaml(options)
             secret = options && options[:origin_secret]
             return "" unless secret
@@ -103,11 +61,6 @@ module Hecks
           end
 
           # Renders the distribution for a set of checked options.
-          #
-          # @param options [Hash] the checked options from `normalize`
-          # @param distribution_id [String] the logical id the distribution is given
-          # @param alb_id [String] the logical id of the load balancer the origin points at
-          # @return [String] the flush-left resource text ending in a newline
           def yaml(options, distribution_id:, alb_id:)
             lines = ["#{distribution_id}:", "  Type: AWS::CloudFront::Distribution"]
             lines.push("  DeletionPolicy: Retain", "  UpdateReplacePolicy: Retain") if options[:retain]

data/lib/hecks/projections/deploy/fargate/cdn_default.rb

@@ -6,17 +6,8 @@ module Hecks
         module Cdn
           module_function
 
-          # The distribution a stack gets when its world sets no `cdn` options.
-          #
-          # Real HTTPS in front of the load balancer's HTTP-only listener, and
-          # the one safe caching default the generator can offer: every route
-          # is treated as session-driven, so nothing is cached. The comment
-          # inside the rendered block explains why, and reaches the generated
-          # template unchanged.
-          #
-          # @param alb_id [String] the logical id of the load balancer
-          # @param distribution_id [String] the logical id the distribution is given
-          # @return [String] the flush-left resource text with its comments, ending in a newline
+          # The distribution a stack gets when its world sets no `cdn` options: HTTPS in
+          # front of the HTTP-only ALB, caching disabled since every route is session-driven.
           def default_yaml(alb_id:, distribution_id:)
             <<~DEFAULT
               # Real HTTPS (the ALB's own Listener above is HTTP-only —

data/lib/hecks/projections/deploy/fargate/check.rb

@@ -2,15 +2,8 @@ module Hecks
   module Projections
     module Deploy
       module Fargate
-        # Validation for the optional settings a `deployed_to("AwsFargate")`
-        # block accepts beyond the required ones.
-        #
-        # `FargateTarget.Declare` in deploy.bluebook owns the baseline
-        # settings (`cpu`, `memory`, `port`, `database`, `web`). The keys added
-        # for multi-container stacks are nested shapes (lists of hashes, maps),
-        # which that aggregate's flat attributes cannot describe, so they are
-        # checked here. Every check raises `ArgumentError` naming the setting
-        # it was reading, so a mistake in a `.world` file points at its line.
+        # Validation for the optional Fargate settings beyond the baseline ones.
+        # Every check raises `ArgumentError` naming the setting it was reading.
         module Check
           module_function
 
@@ -71,7 +64,7 @@ module Hecks
                                  "(letters and digits, starting with a letter), got #{value.inspect}"
           end
 
-          # Checks that a value is a name AWS accepts for a container, repository or stack resource.
+          # Checks that a value is a name AWS accepts for a container, repository or stack.
           #
           # @param value [Object] the name as written in the world file
           # @param where [String] the setting's name, used in the error message
@@ -116,7 +109,7 @@ module Hecks
           # @param min [Integer] the fewest entries allowed
           # @param max [Integer, nil] the most entries allowed, or nil for no limit
           # @return [Array<String>] the entries as strings
-          # @raise [ArgumentError] if the value is not a list of strings or its size is out of range
+          # @raise [ArgumentError] if the value is not a list of strings or is out of size range
           def strings!(value, where, min: 0, max: nil)
             list = value.is_a?(Array) ? value : nil
             ok = list&.all? { |item| (item.is_a?(String) || item.is_a?(Symbol)) && !item.to_s.empty? }
@@ -128,9 +121,7 @@ module Hecks
           end
 
           # Checks that a value is a map of names to strings and returns it string-keyed.
-          #
-          # A `nil` value is kept: for the domain container's environment it
-          # removes a default variable.
+          # A `nil` value is kept: the domain container's env setting removes a variable with it.
           #
           # @param value [Object] the map as written in the world file
           # @param where [String] the setting's name, used in the error message