hecks 1.2.0 → 1.4.0

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -0,0 +1,180 @@
+module Hecks
+  module Fuzzing
+    # What a sweep target can actually be checked for, read off the
+    # filesystem — never off a stored list.
+    #
+    # `bin/qa_sweep` used to decide its one comparison mode inline: "is
+    # there a Cargo feature named after this directory? then
+    # `:differential`, else `:ruby_only`", and a separate hand-typed abort
+    # for `--persistence-parity` ("does any .hecksagon bind PostgresEra?").
+    # Every further mode the practice adds (era boundary, concurrency, a
+    # WASM front) would have grown one more inline `if`, each one a
+    # policy decision hiding in a script. This module is those decisions
+    # as data: `MODE_REQUIREMENTS` says which capabilities each mode
+    # needs, `infer` says which capabilities a target's own directory
+    # actually has, and `resolve` is the one rule that joins them —
+    # `modes_to_run = enabled ∩ eligible`.
+    #
+    # Inference decides; a stored list only records. `Target.capabilities`
+    # (qa/bluebook/quality_control.bluebook, once PR-1's era lands) is
+    # written by the runner from exactly this inference at release time
+    # so `Target.EligibleFor(mode)` can audit the rotation from the
+    # ledger alone — but the runner re-infers every sweep, because a
+    # stored list that lags yesterday's Cargo feature is precisely the
+    # "quiet divergence" (the chapter's own opening comment) this whole
+    # practice exists to hunt. Nothing here ever reads the ledger.
+    #
+    # Every regex is one the harness already owned, moved here rather than
+    # re-derived, and each one's provenance is named beside it so a
+    # future edit to the original site is a visible drift, not a silent
+    # one: the Cargo feature line (`RustConformanceHelpers#build_rust_for`),
+    # the PostgresEra binding (`bin/qa_sweep`'s old `POSTGRES_ERA_BINDING`),
+    # the translations glob (`IsolatedBoot#strip_translations!`).
+    module TargetCapabilities
+      module_function
+
+      # `RustConformanceHelpers#build_rust_for`'s own test, scoped to the
+      # `[features]` table the way `bin/project_rust`'s Cargo sync scopes
+      # its own lookup (a `[package] name = "rust"` line must never read
+      # as a feature named `rust`).
+      FEATURES_TABLE = /^\[features\](?:\n(?!\[).*)*$/
+
+      # `bin/qa_sweep`'s former `POSTGRES_ERA_BINDING` — both spellings
+      # `IsolatedBoot#rewrite_bindings!` has to catch: aggregate-scoped
+      # (`Directory::Member.persisted_by("PostgresEra")`) and the bare
+      # domain-level default (`persisted_by "PostgresEra"`).
+      POSTGRES_ERA_BINDING = /persisted_by\s*\(?\s*"PostgresEra"/
+
+      # `HecksagonBuilder#uses_framework "X"` — captures which member a
+      # hecksagon attaches, whatever its name. Whether that member answers
+      # a role check is then read off its own declaration (`provides
+      # "authorization"`, via `Framework.providers_of`), the same rule
+      # `Registry#authorization_provider_for` applies at runtime — never a
+      # match on the literal "Governance".
+      FRAMEWORK_ATTACHED = /uses_framework\s*\(?\s*"([^"]+)"/
+
+      # A command-level `role "..."` — the only construct
+      # `refuse_role_mismatch` ever has anything to check a caller against.
+      ROLE_GATED = /^\s*role\s+"/
+
+      # `authorize :vault_access, tenant: :branch_code`
+      # (examples/banking/bluebook/safe_deposit_boxes.bluebook) — the one
+      # `tenant:` spelling the corpus has.
+      TENANT_SCOPED = /\btenant:/
+
+      PROCESS_MANAGER = /^\s*process_manager\s+"/
+
+      # Which capabilities each mode needs before it can say anything true
+      # about a target. An empty list means "any target at all" — every
+      # domain boots under Memory, so Ruby-only properties and the
+      # self-consistency pass are always answerable. `ruby_only` is listed
+      # requirement-free on purpose and then excluded by `resolve` whenever
+      # `differential` resolved too: they are the same seat, and a compiled
+      # Rust binary is strictly the better occupant (item 1 of the
+      # detection plan folded the Ruby-only property battery into the
+      # differential seat, so nothing is lost by the exclusion).
+      #
+      # The four `false`-by-default modes in `QualityControlDials::MODES`
+      # (`adapter_parity_postgres`, `era_boundary`, `concurrency`,
+      # `wasm_front`) are named here with their requirements even though
+      # nothing runs them yet — so `resolved modes:` can already say, per
+      # target, which of them would be eligible the day a human flips the
+      # dial, and so flipping it is a one-line data change rather than a
+      # code change plus a data change.
+      MODE_REQUIREMENTS = {
+        differential:               %w[rust],
+        ruby_only:                  [],
+        self_consistency:           [],
+        properties_in_differential: %w[rust],
+        structural_skip_report:     %w[rust],
+        adapter_parity_sqlite:      %w[sqlite],
+        persistence_parity:         %w[postgres_era],
+        adapter_parity_postgres:    %w[postgres_era],
+        era_boundary:               %w[translations postgres_era],
+        concurrency:                %w[postgres_era],
+        wasm_front:                 %w[rust]
+      }.freeze
+
+      # Which of those modes `bin/qa_sweep` can actually run today.
+      # `MODE_REQUIREMENTS` above says what a mode needs; this says what
+      # exists to do it, and the two are not the same. Conflating them is
+      # how `qa/settings.yml` came to enable `wasm_front` and
+      # `adapter_parity_postgres` with nothing behind either — no seat, no
+      # check folded into the seed loop, no `MODE_EXPECTATIONS` entry — while
+      # `resolved modes:` still printed them per target, so the sweep
+      # advertised coverage it never performed. A mode named in
+      # `MODE_REQUIREMENTS` but absent here is one this practice wants and has
+      # not built: `bin/qa_sweep` refuses to start when a dial or `--modes`
+      # enables it, rather than resolving it into a line nobody can act on.
+      # `spec/qa_sweep_runnable_modes_spec.rb` keeps this list honest from
+      # both sides by grepping the runner itself.
+      RUNNABLE_MODES = %i[differential ruby_only self_consistency properties_in_differential
+                          structural_skip_report adapter_parity_sqlite persistence_parity
+                          era_boundary concurrency].freeze
+
+      # Modes that name a separate, expensive pass of their own rather than
+      # an extra check folded into the ordinary per-seed loop —
+      # `bin/qa_sweep` runs these only when asked by name (`--modes
+      # persistence_parity`, or its older alias `--persistence-parity`) or
+      # as `--all`'s own second wave, never silently inside a plain
+      # single-target sweep (the seed cap `PERSISTENCE_PARITY_SEED_CAP`
+      # exists because that pass pays for real Postgres I/O per dispatch).
+      DEFERRED_MODES = %i[persistence_parity adapter_parity_postgres era_boundary concurrency].freeze
+
+      # Sorted, plain strings — comma-joined by the runner into the
+      # `Target.Release(capabilities:)` value object and printed verbatim
+      # on the `resolved modes:` line, so the same spelling is what a
+      # human reads, what `--all` parses back, and what the ledger stores.
+      def infer(domain_path, rust_dir: File.expand_path("../../../rust", __dir__))
+        capabilities = %w[sqlite]
+        capabilities << "rust" if rust_feature?(domain_path, rust_dir)
+        capabilities << "postgres_era" if any_file?(domain_path, "*.hecksagon", POSTGRES_ERA_BINDING)
+        capabilities << "translations" if Dir.glob(File.join(domain_path, "**", "translations", "*.bluebook")).any?
+        capabilities << "governance" if authorization_attached?(domain_path)
+        capabilities << "role_gated" if any_file?(domain_path, "*.bluebook", ROLE_GATED)
+        capabilities << "tenant" if any_file?(domain_path, "*.bluebook", TENANT_SCOPED)
+        capabilities << "sagas" if any_file?(domain_path, "*.bluebook", PROCESS_MANAGER)
+        capabilities.sort
+      end
+
+      def eligible?(mode, capabilities)
+        required = MODE_REQUIREMENTS.fetch(mode.to_sym) { raise ArgumentError, "unknown sweep mode #{mode.inspect}" }
+        (required - capabilities).empty?
+      end
+
+      # The one rule. `enabled` is whatever the dial (or `--modes`) turned
+      # on, in the dial's own declaration order — that order is preserved
+      # so the printed line reads the same way the dial does. Then the
+      # single exclusion named on `MODE_REQUIREMENTS`.
+      def resolve(enabled, capabilities)
+        resolved = enabled.map(&:to_sym).select { |mode| eligible?(mode, capabilities) }
+        resolved.delete(:ruby_only) if resolved.include?(:differential)
+        resolved
+      end
+
+      def rust_feature?(domain_path, rust_dir)
+        cargo_toml = File.join(rust_dir, "Cargo.toml")
+        return false unless File.file?(cargo_toml)
+
+        feature  = File.basename(domain_path).downcase
+        features = File.read(cargo_toml)[FEATURES_TABLE] || ""
+        features.match?(/^#{Regexp.escape(feature)}\s*=\s*\[\]/)
+      end
+
+      # The capability label stays "governance" — it is the value
+      # `bin/qa_sweep` writes into the QualityControl ledger's
+      # `Target.capabilities`, and renaming it is a ledger change, not
+      # part of dropping the name check.
+      def authorization_attached?(domain_path)
+        attached = Dir.glob(File.join(domain_path, "**", "*.hecksagon"))
+                      .flat_map { |path| File.read(path).scan(FRAMEWORK_ATTACHED).flatten }.uniq
+        providers = Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION)
+        attached.intersect?(providers)
+      end
+
+      def any_file?(domain_path, glob, pattern)
+        Dir.glob(File.join(domain_path, "**", glob)).any? { |path| File.read(path).match?(pattern) }
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/value_generator.rb

@@ -4,7 +4,7 @@ module Hecks
   module Fuzzing
     # One attribute, one value — in the exact JSON shape the hand-written
     # corpus already uses (a value-object-typed attribute is a nested hash keyed
-    # by its own field names ; a reference is the BARE ID of the head it points
+    # by its own field names ; a reference is the bare ID of the head it points
     # at, because that is what a reference is). Everything
     # returned is a plain, JSON-safe Ruby value : String keys throughout, never
     # symbols, so a generated step can be dumped straight to JSON.
@@ -15,7 +15,7 @@ module Hecks
     # codebase," and a fixed corpus of a few dozen examples rarely happens to
     # exercise the boundary that actually breaks. But mostly not : an attribute
     # named `email`/`currency` almost always needs a specific shape just to get
-    # PAST its own invariant (`address.include?("@")`, `currency.size == 3`) —
+    # past its own invariant (`address.include?("@")`, `currency.size == 3`) —
     # banking's very first fuzz run never got past Customer.Register, because
     # no plain random word ever contains "@". Reaching deep state matters more
     # than edge-casing every single field every single time, so the "normal"
@@ -31,7 +31,7 @@ module Hecks
       # (lib/hecks/runtime/value/coercion.rb) has accepted a bare
       # `"large"` in place of `{"value" => "large"}` for any single-field
       # value object since 86727afd — but until this generator actually
-      # PRODUCES that shape, nothing exercises it: neither the adapter-
+      # produces that shape, nothing exercises it: neither the adapter-
       # agreement gate nor the Rust/WASM `from_json` codegen (rust/project/
       # json_codec.rb) can ever be caught drifting on a shape they're
       # never handed.
@@ -44,15 +44,60 @@ module Hecks
       # PRD 05 (numeric-boundary-coverage) — Bignum (`2**100`, past i64's
       # own ceiling, which Ruby's own `Integer` has no such ceiling for —
       # `rust/src/kernel/json.rs`'s own `integral_i64` doc comment names
-      # exactly this: a Rust kernel value CANNOT represent it, so this
+      # exactly this: a Rust kernel value cannot represent it, so this
       # exercises a real cross-runtime capability gap, not a Ruby-only
       # edge) and its negative twin. Both round-trip through Ruby's own
       # arithmetic/JSON cleanly (confirmed directly: `(2**100).clamp(...)`
       # and `JSON.generate(2**100)` both just work — Integer has no
-      # ceiling here), so nothing in THIS runtime needed a fix for these;
+      # ceiling here), so nothing in this runtime needed a fix for these;
       # they're included so a real generated sequence occasionally
       # produces the value at all, since nothing had, repo-wide, before.
       INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648, 2**100, -(2**100)].freeze
+      # BUG#35 (QualityControl QA ledger, `lease-clock-json-precision`) —
+      # a Bignum edge case (`2**100`, above) landing on an Integer-typed
+      # clock or count reading fires the already-catalogued `Json::Num`/
+      # f64 precision-loss class (`rust/src/kernel/json.rs`'s
+      # `parse_number` parses every number through `s.parse::<f64>()`
+      # before any target-type conversion runs, and `Json::Num` is a
+      # plain `f64` end to end — see that file's own header) on a new
+      # site every time a new clock/count-shaped field is authored,
+      # without adding any new coverage: both engines already refuse
+      # (`TypeMismatch`, out of `i64` range either way) for this shape,
+      # `tenant_ledger`'s own NOTES.md already logged the identical class
+      # on a stored money attribute, and `spec/support/
+      # rust_conformance_helpers.rb`'s own `reduce_to_wire_precision`
+      # already documents and normalizes past the wire format's own loss
+      # for a query's echoed args. An exact-integer Rust JSON
+      # deserialization path was considered and rejected as this
+      # generator's own fix instead: `Json::Num(f64)` is pattern-matched
+      # throughout `rust/src/kernel` (query_comparators.rs,
+      # query_ordering.rs, read_model.rs, named_query.rs, this kernel's
+      # own `Fielded` impl, arithmetic overflow checks) and emitted by
+      # codegen (`rust/project/reactions.rb`, `rust/codegen/src/
+      # reactions.rs`) — adding a second, exact-integer numeric variant
+      # would mean auditing and updating every one of those sites, a
+      # refactor of the JSON layer itself, not a one-domain fix (exactly
+      # the ledger's own stated concern: "risks affecting every other
+      # domain's large-integer handling"). So instead, per the ledger's
+      # own sanctioned fallback: an Integer-typed field whose name reads
+      # as a clock or a count is capped to a narrower, still-real
+      # edge-case pool below (still exercises the ordinary i32
+      # boundaries, just never a value past f64's own 2**53 exact-
+      # integer ceiling) — every other Integer-typed field (a money
+      # amount, an identity sequence, anything not clock/count-shaped)
+      # still draws from the full `INTEGER_EDGE_CASES` pool above,
+      # unchanged.
+      SAFE_INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648].freeze
+      # Matched against the value object's own declared name plus the
+      # attribute's own name (`value_for`'s `"#{context} #{attribute.
+      # name}"`, e.g. "LeaseInstant value", "RetryCount value") — a
+      # clock reading ("instant"/"clock"/"expir(es/y)"/"ttl"/"now"/
+      # "timestamp"/"epoch") or a quantity capped by a policy ("count").
+      # Deliberately narrow: matches the ledger's own "clock/count"
+      # wording exactly, not every plausibly-large-looking name (an
+      # "amount"/"cents"/"sequence" field is not clock/count-shaped and
+      # keeps the full Bignum edge-case pool).
+      CLOCK_OR_COUNT_NAME_PATTERN = /clock|instant|expir|ttl|\bnow\b|timestamp|epoch|count/i
       # NaN and +/-Infinity — the real find (see `spec/runtime/
       # numeric_boundary_spec.rb`): `Value::Coercion#check_numeric_fields`
       # used to let all three sail through untyped-checked (each really
@@ -60,7 +105,7 @@ module Hecks
       # (raw `ArgumentError`, not a domain refusal) or `JSON.generate`
       # (`JSON::GeneratorError`, also not a domain refusal) — both fixed
       # at the source now, so these are safe to generate. -0.0 is
-      # deliberately included too even though it was ALREADY safe
+      # deliberately included too even though it was already safe
       # (finite, round-trips through JSON as `-0.0` cleanly) — a signed
       # zero is exactly the kind of boundary a hand-written corpus never
       # happens to type, and the fuzzer existing to cover it is the
@@ -112,10 +157,10 @@ module Hecks
             end
           end
 
-        # `fields.size == 1` — the SAME test `Behaviour::ValueObject#
+        # `fields.size == 1` — the same test `Behaviour::ValueObject#
         # sole_attribute` names: a genuinely single-field value object,
         # not merely "this particular closed-set member happened to pick
-        # one field." Unwrapping ONLY here, not in `invalid_member`
+        # one field." Unwrapping only here, not in `invalid_member`
         # above — a deliberately-wrong combination stays a Hash so its
         # own wrongness is what gets exercised, not a second, unrelated
         # shape question.
@@ -133,10 +178,10 @@ module Hecks
         end
       end
 
-      # THE ID ITSELF. This minted `{"value" => id}` back when a reference was
+      # The ID itself. This minted `{"value" => id}` back when a reference was
       # stored wrapped ; the payload gate refuses that shape now, so a fuzzer
       # still emitting it would have every generated reference refused and
-      # the SILENT guard would report the fuzzer broken rather than
+      # the silent guard would report the fuzzer broken rather than
       # the runtime.
       def reference_value(attribute, random:, known_ids:)
         pool = known_ids[attribute.type.target_name.to_s] || []
@@ -148,7 +193,7 @@ module Hecks
       def primitive(type_name, random:, name: nil)
         case type_name
         when "String"  then string_value(random, name: name)
-        when "Integer" then integer_value(random)
+        when "Integer" then integer_value(random, name: name)
         when "Float"   then float_value(random)
         when "TrueClass", "FalseClass" then random.rand(2).zero?
         else raise ArgumentError, "ValueGenerator does not know primitive type #{type_name.inspect}"
@@ -172,19 +217,26 @@ module Hecks
       # sequence that can never get past one never reaches the state a deeper
       # bug would need. Zero and negative are still real, reachable outcomes —
       # via the edge-case pool, deliberately, not by starving them entirely.
-      def integer_value(random)
-        return INTEGER_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
+      def integer_value(random, name: nil)
+        if random.rand < EDGE_CASE_PROBABILITY
+          pool = clock_or_count_shaped?(name) ? SAFE_INTEGER_EDGE_CASES : INTEGER_EDGE_CASES
+          return pool.sample(random: random)
+        end
 
         random.rand(1..1000)
       end
 
+      def clock_or_count_shaped?(name)
+        name.to_s.match?(CLOCK_OR_COUNT_NAME_PATTERN)
+      end
+
       def float_value(random)
         return FLOAT_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
 
         random.rand(0.01..1000.0).round(2)
       end
 
-      # The bare scalar a generated IDENTITY value stands for, for recording into
+      # The bare scalar a generated identity value stands for, for recording into
       # `known_ids`. An identity is declared as a value object, so this opens one ;
       # a reference pointing at this record is already that scalar and needs no
       # opening at all. The two used to be the same reading and are not any more.

data/lib/hecks/fuzzing.rb

@@ -8,5 +8,16 @@ end
 require_relative "fuzzing/value_generator"
 require_relative "fuzzing/invalid_value_generator"
 require_relative "fuzzing/sequence_generator"
+require_relative "fuzzing/nondeterministic"
 require_relative "fuzzing/replay"
+require_relative "fuzzing/shrinker"
 require_relative "fuzzing/properties"
+require_relative "fuzzing/qa_settings"
+require_relative "fuzzing/rotation_priority"
+require_relative "fuzzing/sweep_depth"
+require_relative "fuzzing/persistence_parity"
+require_relative "fuzzing/form_census"
+require_relative "fuzzing/target_capabilities"
+require_relative "fuzzing/rust_gap_manifest"
+require_relative "fuzzing/structural_skips"
+require_relative "fuzzing/coverage_campaign"

data/lib/hecks/grammar/evolve.rb

@@ -1,7 +1,7 @@
 module Hecks
   module Grammar
     # The file surgery under bin/evolve: reading and rewriting the
-    # aggregate-local KeywordSeed/ArgumentSeed rows as TEXT, so a
+    # aggregate-local KeywordSeed/ArgumentSeed rows as text, so a
     # proposed word enters the table exactly as a hand would write it
     # and an admitted one loses its ceremony (an absent status reads as
     # admitted — the grown-column convention).
@@ -18,7 +18,7 @@ module Hecks
       module_function
 
       # bin/evolve's own `--name value` flag reader. Only consumes the
-      # NEXT argv element as the value when that element doesn't itself
+      # next argv element as the value when that element doesn't itself
       # look like a flag — otherwise `--foo --bar` would swallow `--bar`
       # as `--foo`'s value (and `--bar` would then never be seen at
       # all), and a value-less `--foo` at the end of argv would bypass
@@ -97,7 +97,7 @@ module Hecks
         row = %(#{indent}member word: "#{word}", context: "#{context}", body: "#{body}", ) +
               %(inner: "#{inner}", opens: "#{opens}", fills: "#{fills}", status: "proposed"\n)
 
-        # At the END of the one_of — grouping by context is a courtesy of
+        # At the end of the one_of — grouping by context is a courtesy of
         # the hand; a proposed row sits at the bottom until admission,
         # when whoever admits it may move it home.
         closing = block.rindex(/^\s*end\s*$/)
@@ -119,7 +119,7 @@ module Hecks
           next line unless member_row?(line, word, context)
 
           stripped = line.sub(/,\s*status: "[^"]*"/, "")
-          # Admitted is the default and stays UNSPELLED — only a word
+          # Admitted is the default and stays unspelled — only a word
           # entering or leaving the language carries its status.
           to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
         end.join
@@ -219,10 +219,10 @@ module Hecks
         block
       end
 
-      # From `value_object "KeywordSeed"` to ITS OWN closing `end` — `member`
+      # From `value_object "KeywordSeed"` to its own closing `end` — `member`
       # rows sit bare now (S3, ADR 0025 — the `one_of do ... end` wrapper
       # is gone), so the first bare `end` line after the opener already
-      # IS the value object's own, the same fact the original one_of-
+      # is the value object's own, the same fact the original one_of-
       # nested version of this method leaned on (nothing else nested
       # inside it either, before or after).
       def keyword_blocks(source) = seed_blocks(source, "KeywordSeed")
@@ -230,7 +230,7 @@ module Hecks
 
       # ── the Argument rows — a word's own arguments, at last with tooling
       # of their own rather than the rename-only cascade above. A word may
-      # carry SEVERAL argument rows (one per position, one per named
+      # carry several argument rows (one per position, one per named
       # kwarg), so identity here is the full (keyword, context, at, named)
       # tuple, not the two-field key a Keyword row answers to.
 
@@ -250,7 +250,7 @@ module Hecks
         end
       end
 
-      # `pairs_shape` — for a `pairs` argument that fills ONE field with a
+      # `pairs_shape` — for a `pairs` argument that fills one field with a
       # whole key/value list rather than naming a field per pair (the
       # shape `Handler.dispatch`'s own `with:` already carries). Without
       # it, `spec/syntax_conformance_spec.rb` reads a pairs argument
@@ -315,7 +315,7 @@ module Hecks
 
       def argument_identity(row) = [row[:keyword], row[:context], row[:at], row[:named]]
 
-      # The rename cascade, ROW-AWARE — only the rows that actually belong
+      # The rename cascade, row-aware — only the rows that actually belong
       # to the renamed word, spelling updated in place, rather than a
       # blind `gsub` on every `keyword: "word",` substring in the file
       # (which a coincidentally-matching row elsewhere could have
@@ -337,7 +337,7 @@ module Hecks
         end
       end
 
-      # From `value_object "ArgumentSeed"` to ITS OWN closing `end` — see
+      # From `value_object "ArgumentSeed"` to its own closing `end` — see
       # `keyword_block`'s own comment for why the first bare `end` after
       # the opener is already the right one, now that `member` rows sit
       # bare (S3, ADR 0025).

data/lib/hecks/grammar.rb

@@ -7,12 +7,12 @@ require_relative "../hecks"
 
 module Hecks
   # The sublanguage grammar domains (grammar/*.bluebook) and the one boot
-  # path for reading them as DATA — the expression chapter replayed
+  # path for reading them as data — the expression chapter replayed
   # through its own admission ledger, so anything derived from it (the
   # operator projections, the conformance specs) reads the set that
   # actually survived the Admit gates, never a hand-copied list.
   #
-  # Booted on CALL, never at require: the Prism adapter normalises every
+  # Booted on call, never at require: the Prism adapter normalises every
   # predicate through CanonicalForm while a bluebook loads, so the
   # expression machinery cannot boot the chapter that configures it —
   # this module exists precisely so generators and specs boot it in a
@@ -42,7 +42,7 @@ module Hecks
       JSON.parse(File.read(LEDGER)).fetch("steps").each do |step|
         args = symbolize(step.fetch("args"))
         begin
-          dispatcher.dispatch(step.fetch("verb"), **args)
+          dispatcher.dispatch_flat(step.fetch("verb"), args)
         rescue *Runtime::DOMAIN_REFUSALS => e
           raise Runtime::WiringError,
                 "the admission ledger refused at #{step['verb']} #{step['args']} — #{e.message}"
@@ -77,15 +77,15 @@ module Hecks
       registry.repository("Expression", aggregate).all
     end
 
-    # THE OPERATORS THE LANGUAGE STANDS ON. Every guard and invariant in
+    # The operators the language stands on. Every guard and invariant in
     # the language's own chapters — the meta-domain (Bluebook, World) and
     # the grammar chapters beside this file — evaluates through the very
     # operator table the ledger admits. An operator one of those
-    # predicates uses is SELF-BEARING: retire it and the language can no
+    # predicates uses is self-bearing: retire it and the language can no
     # longer read its own rules — found the hard way, as a projection
     # missing `!=` that could not boot the chapter to fix itself. This
     # derives the set, with a usage site per operator, so the generator
-    # and the conformance spec can refuse the retirement BY NAME instead
+    # and the conformance spec can refuse the retirement by name instead
     # of wedging.
     def self_bearing_operators
       sites = Hash.new { |h, k| h[k] = [] }
@@ -146,7 +146,7 @@ module Hecks
       walk_operators(node, evaluator).uniq
     end
 
-    # A recursive descent over a CLOSED, declared set of AST node types
+    # A recursive descent over a closed, declared set of AST node types
     # (Evaluator's boolean/compare/include nodes, Resolver's arithmetic
     # nodes, and the generic Struct fallback) — each branch does the
     # same one thing (name the node's own operator, recurse into its

data/lib/hecks/ir.rb

@@ -1,19 +1,19 @@
 module Hecks
-  # WHAT A CONSTRUCT EMITS, DECLARED RATHER THAN WRITTEN OUT.
+  # What a construct emits, declared rather than written out.
   #
-  # `IR` is a thing this framework PRODUCES, not a thing its model IS.
+  # `IR` is a thing this framework produces, not a thing its model is.
   # The language self-hosts, and its own bluebook declares aggregates
   # named `Bluebook`, `Aggregate`, `Command`, `Entity`, `ValueObject`,
   # `Policy`, `ReadModel` — there is no `IR` aggregate anywhere in the
   # grammar. Where the grammar's own vision line does say IR it means the
-  # emission: "the IR it STORES must equal the IR the DSL builder
-  # PRODUCES". `IR_VERSION` says the same thing structurally — a version
+  # emission: "the IR it stores must equal the IR the DSL builder
+  # produces". `IR_VERSION` says the same thing structurally — a version
   # stamped on `to_h`'s output rather than on the object is a version of
-  # the EMISSION, which only makes sense if the two are different things.
+  # the emission, which only makes sense if the two are different things.
   #
-  # So emitting IR is a CAPABILITY a construct has, and this is that
+  # So emitting IR is a capability a construct has, and this is that
   # capability: `include Hecks::IR` and declare the shape once.
-  # The model it emits FROM is `Hecks::Bluebook` — a chapter class
+  # The model it emits from is `Hecks::Bluebook` — a chapter class
   # nesting everything a chapter declares. It is deliberately not named
   # after this, its own output.
   #
@@ -36,18 +36,18 @@ module Hecks
   #     canonical_form: -> { CanonicalForm.table } # anything else
   #   )
   #
-  # KEY ORDER IS THE DECLARATION ORDER, and that is load-bearing rather
+  # Key order is the declaration order, and that is load-bearing rather
   # than cosmetic: `spec/golden/ir/*.json` pins the emitted form exactly,
   # so a reordered declaration is a changed artifact and the golden specs
   # will say so.
   module IR
-    # THE TWO SHAPES A CONSTRUCT COMES IN, and why this module has two
+    # The two shapes a construct comes in, and why this module has two
     # doors instead of hiding the difference.
     #
     # `Bluebook`/`Aggregate`/`Policy`/`ReadModel` are ordinary objects —
     # metadata records, one instance per declaration. `Command`/`Entity`/
-    # `ValueObject` are anonymous CLASSES (`Class.new(self)`, see
-    # `Command.declare`), because those three are referenced as TYPES in
+    # `ValueObject` are anonymous classes (`Class.new(self)`, see
+    # `Command.declare`), because those three are referenced as types in
     # a bluebook (`attribute :price, Money`) and a type has to be a real
     # Ruby constant to be named.
     #
@@ -87,7 +87,7 @@ module Hecks
       def one(source)  = One.new(source)
 
       # Walks the superclass chain so a `Class.new(ValueObject)` — which
-      # is what every declared value object actually IS — inherits the
+      # is what every declared value object actually is — inherits the
       # shape its base declared, rather than each anonymous subclass
       # having to redeclare it.
       def ir_spec
@@ -112,7 +112,7 @@ module Hecks
       private
 
       # An instance reads its class's declaration; a class-shaped
-      # construct IS the declaration holder.
+      # construct is the declaration holder.
       def ir_spec_for(construct)
         return construct.ir_spec if construct.respond_to?(:ir_spec)
 

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

@@ -73,6 +73,26 @@ Hecks.bluebook "Bluebook", version: "1" do
     # chapters attach to nothing, and ABSENT IS NOT EMPTY, the same
     # reading `version`/`formerly_known_as` above give.
     attribute :attaches_to, list_of(AttachesToContext)
+    # A CAPABILITY THIS CHAPTER ANSWERS FOR OTHER DOMAINS — declared, so
+    # nothing downstream has to recognise the chapter BY NAME. One row
+    # per (capability, key, verb): `provides "authorization", grant:
+    # "RoleAssignment.Assign"` is the row (authorization, grant,
+    # RoleAssignment.Assign). The runtime's role check, boot's
+    # ungoverned-role refusal, the authorization adapter and the fuzzer
+    # all read the rows rather than the literal "Governance". Most
+    # chapters provide nothing, and ABSENT IS NOT EMPTY, the same reading
+    # `attaches_to` above gives.
+    attribute :provides, list_of(Provision)
+
+    value_object "Provision" do
+      attribute :capability, String
+      attribute :key,        String
+      attribute :verb,       String
+    end
+
+    value_object "ProvisionText" do
+      attribute :value, String
+    end
 
     value_object "RuleText" do
       # deliberately permissive : source_token and replacement are legitimately
@@ -159,6 +179,22 @@ Hecks.bluebook "Bluebook", version: "1" do
       emits ChapterAttached
     end
 
+    # ONE ROW OF ONE CAPABILITY — `provides "authorization", assignments:
+    # ..., grant: ..., transitions: ...` offers three, one per key, in the
+    # order they were written.
+    command "Provide" do
+      role "Language"
+      goal "Declare one verb this chapter answers a capability with"
+
+      attribute :capability, ProvisionText
+      attribute :key,        ProvisionText
+      attribute :verb,       ProvisionText
+
+      sets :provides, append: { capability: :capability, key: :key, verb: :verb }
+
+      emits CapabilityProvided
+    end
+
     # THE WAY BACK.
     #
     # Until these existed the meta-domain was write-only: twelve categories, 34
@@ -214,6 +250,7 @@ Hecks.bluebook "Bluebook", version: "1" do
       member word: "vision", context: "Bluebook", body: "none", inner: "", opens: "", fills: "vision"
       member word: "formerly_known_as", context: "Bluebook", body: "none",   inner: "",               opens: "",               fills: "formerly_known_as"
       member word: "attaches_to",     context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "attaches_to", calls: "attaches_to_impl"
+      member word: "provides",        context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "provides", calls: "provides_impl"
       member word: "core",            context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
       member word: "supporting",      context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
       member word: "generic",         context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
@@ -246,6 +283,10 @@ Hecks.bluebook "Bluebook", version: "1" do
       member keyword: "vision",          context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "vision", coerce: "false"
       member keyword: "formerly_known_as", context: "Bluebook", at: "1", named: "",      kind: "text",     required: "true",  fills: "formerly_known_as"
       member keyword: "attaches_to",     context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "attaches_to", variadic: "true"
+      member keyword: "provides",        context: "Bluebook", at: "1", named: "",            kind: "text", required: "true",  fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "assignments", kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "grant",       kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "transitions", kind: "text", required: "false", fills: "provides"
       member keyword: "aggregate",       context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "name"
       member keyword: "read_model", context: "Bluebook", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "policy",          context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "name"