hecks 2.8.0 → 2.9.0

data/lib/hecks/forms.rb

@@ -1,41 +1,13 @@
-# The forms surface: `expose` (the DSL a `command_form.bluebook`/
-# `query_form.bluebook` will eventually become — see docs/
-# command-form-and-query-form-bluebook.md), the IR->HTML renderers, and
-# the Rack app that content-negotiates between them and a plain JSON
-# reading of the same dispatch. Not required by `require "hecks"`
-# itself — a project that never boots this file never pays for `rack`,
-# the same lazy-dependency discipline the Gemfile's own comment already
-# holds `pg`/`oauth2`/`aws-sdk-lambda` to.
-#
-# See docs/command-form-and-query-form-bluebook.md for the design this
-# implements and what it deliberately leaves for later.
+# The forms surface: `expose`, the HTML renderers and the Rack app serving them.
+# Not loaded by `require "hecks"`, so `rack` stays a lazy dependency.
 require "hecks"
 require_relative "forms/app"
 
 module Hecks
-  # Per-chapter `expose` configuration, keyed by chapter name and looked up
-  # by the Rack app at request time (`.config`) to decide which chapters'
-  # forms are switched on at all — see the file header above for what
-  # `expose` deliberately does and does not cover.
+  # Per-app `expose` configuration, looked up by the Rack app at request time.
   module Forms
-    # `expose`'s own declaration — "which chapters does this app expose" —
-    # kept outside the `Hecks.*` collector convention (`Hecks.bluebook`,
-    # `Hecks.hecksagon`, ...) and outside `Runtime::Registry` entirely, on
-    # purpose: a real language word goes through `syntax.bluebook` and
-    # `MetaValidator` (see docs/implemented/guides/extending-hecks.md, "a new word is a
-    # declared row before it is a line of Ruby") and is judged by
-    # spec/syntax_conformance_spec.rb + spec/dsl_coverage_spec.rb — gates
-    # this construct has not earned yet. An ordinary Ruby DSL, one level of
-    # module state, no different in kind from a project's own initializer —
-    # see docs/command-form-and-query-form-bluebook.md, "why this isn't
-    # syntax.bluebook yet".
-    #
-    # One `expose` grants a whole chapter, not a command or a query
-    # individually — the future `command_form.bluebook`/`query_form.bluebook`
-    # words are per-declaration (one command, one query, its own form/view,
-    # possibly its own overrides), which `expose` doesn't do today and was
-    # never trying to; it's the coarse "turn this chapter's forms on at
-    # all" switch those finer words will eventually sit inside.
+    # The chapters one app exposes. Plain module state, outside `syntax.bluebook` and
+    # the registry; one `expose` switches on a whole chapter, not a single command or query.
     class Config
       attr_reader :name, :exposes
 

data/lib/hecks/fqn.rb

@@ -24,10 +24,9 @@ module Hecks
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: command, kind: :command)
     end
 
-    # Builds the FQN of one query, either on an aggregate or domain-level.
+    # Builds the FQN of one query, on an aggregate or domain-level.
     #
-    # @param realm [String, nil] deployment identity from the world, or nil for an
-    #   unrealmed address
+    # @param realm [String, nil] deployment identity from the world, or nil if unrealmed
     # @param domain [String] the domain name
     # @param query [String] the query's snake_case verb
     # @param aggregate [String, nil] the aggregate the query belongs to, or nil for
@@ -41,12 +40,8 @@ module Hecks
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: query, kind: :query)
     end
 
-    # One order-dependent parse pipeline: split -> shape-validate -> dispatch
-    # on segment count -> split domain/version -> classify kind -> cross-
-    # field validate -> construct. Each step consumes locals (segments, verb,
-    # kind) the step before it derived; splitting would mean threading all of
-    # them back out as parameters/returns between new methods, for no
-    # readability gain over reading the pipeline top to bottom once.
+    # Parses a `Realm::Domain@version::Aggregate.verb` address.
+    # One method on purpose: each step consumes locals the step before it derived.
     #
     # @param text [String] a `Realm::Domain::Aggregate.verb` address, with domain
     #   optionally `@version`-pinned and aggregate optional for a domain-level query
@@ -65,9 +60,7 @@ module Hecks
 
       realm, domain_spec, aggregate = case segments.length
                                       when 3 then segments
-                                      # A two-segment lowercase address is the
-                                      # public realm/domain form for a
-                                      # domain-level read model.
+                                      # realm::domain.query is a domain-level read model
                                       when 2 then query_name?(verb) ? [segments[0], segments[1], nil] : [nil, *segments]
                                       else [nil, segments.first, nil]
                                       end

data/lib/hecks/framework/bluebook/compliance.bluebook

@@ -2,46 +2,16 @@ Hecks.bluebook "Compliance" do
   vision "Something elsewhere already acted to contain a risk; this domain tracks the human review that decides what happens next."
   supporting
 
-  # LIVES HERE (lib/hecks/framework/bluebook/), NOT under some
-  # domain's own examples/ directory, but that's a statement about
-  # SOURCE SHARING, not about how it's consumed — unlike Governance/
-  # Identity (which every real attaching domain only ever wants IN-
-  # PROCESS), Compliance genuinely supports BOTH modes from the same
-  # source: a domain that wants Review handled locally can
-  # `uses_framework "Compliance"` exactly like those two; a domain that
-  # wants it as a real, separately-deployed service — Banking's own
-  # choice, examples/compliance/ — reaches it through `across
-  # "Compliance"` on a policy instead, genuine cross-Lambda delivery.
-  # Nothing about this bluebook's own declarations changes between the
-  # two; only whether the CONSUMER merges it in or deploys it apart.
+  # Supports both modes from one source: `uses_framework "Compliance"` merges it in-process,
+  # or a separately deployed service is reached with `across "Compliance"` on a policy.
+  # examples/compliance/bluebook/compliance.bluebook symlinks here, since a symlink pointing
+  # outside lib/ does not survive `gem build`.
   #
-  # examples/compliance/bluebook/compliance.bluebook is a SYMLINK back
-  # to this file (not the other way around, as it briefly was in
-  # 1.5.0) — a symlink pointing outside lib/ never survives `gem
-  # build` (RubyGems drops it, warning "not supported on all
-  # platforms"), so the real content has to live in the tree the
-  # gemspec actually packages.
+  # Contain first, investigate second: the containing action (a freeze, a box surrender) has
+  # already happened elsewhere. This domain is told the fact and records the review after it.
   #
-  # CONTAIN FIRST, INVESTIGATE SECOND — the real pattern this domain
-  # exists for. Banking's own "Compliance officer" role already acts
-  # directly and synchronously in three places (Customer.Suspend/
-  # Reinstate, Account.Freeze/Unfreeze, OnboardingCase.Clear/Decline) —
-  # this domain is deliberately NOT a fourth. By the time either
-  # aggregate below is opened, the containing action (a freeze, a box
-  # surrender) has ALREADY happened, unilaterally, elsewhere; this
-  # domain never asks permission, it is TOLD a fact and gives the same
-  # officer a place to record what they decided about it afterward.
-  #
-  # TWO AGGREGATES, NOT ONE — found live, designing this: Banking's own
-  # `ReviewOnFreeze`/`ReviewOnBoxSurrender` policies forward their
-  # triggering event's payload VERBATIM (neither declares a `with:`
-  # projection, which policies have gained since), and the two events
-  # carry genuinely different fields (`AccountFrozen`: `number`;
-  # `BoxSurrendered`: `branch_code` + `box_number`). One shared
-  # aggregate would need an artificial union of both shapes — and while
-  # `with:` could now reshape either side into it, that would be
-  # inventing a sameness the domain does not have. Two small aggregates,
-  # each identified by its own subject's own natural key, need neither.
+  # One aggregate per triggering event: the events carry different fields, so a shared
+  # aggregate would need an artificial union of the shapes.
 
   aggregate "AccountFreezeReview" do
     description "The compliance review a frozen account gets, opened the moment Banking::Account.Freeze already happened."
@@ -60,12 +30,8 @@ Hecks.bluebook "Compliance" do
       transition "Escalate" => "escalated", from: "open"
     end
 
-    # SYSTEM-TRIGGERED, matching `AccountFrozen`'s own payload shape
-    # field for field — `Banking::Account.AccountFrozen`'s `number` is
-    # the ONLY field this ever receives (ReviewOnFreeze's own `on
-    # "Account.AccountFrozen"`), so this declares exactly that and
-    # nothing more; an unrecognized field would refuse at the JSON
-    # boundary rather than silently drop it.
+    # System-triggered. Takes only `number`, the one field `AccountFrozen` carries; an
+    # unrecognized field is refused at the JSON boundary rather than dropped.
     command "Open" do
       role "System"
       goal "Register that a frozen account needs compliance review"
@@ -117,9 +83,7 @@ Hecks.bluebook "Compliance" do
       transition "Escalate" => "escalated", from: "open"
     end
 
-    # Matches `BoxSurrendered`'s own payload field for field
-    # (`ReviewOnBoxSurrender`'s own `on SafeDepositBox::BoxSurrendered`) — the same
-    # discipline `AccountFreezeReview.Open` holds itself to, above.
+    # Takes exactly the fields `BoxSurrendered` carries, as `AccountFreezeReview.Open` does.
     command "Open" do
       role "System"
       goal "Register that a surrendered box needs compliance review"
@@ -149,18 +113,9 @@ Hecks.bluebook "Compliance" do
     end
   end
 
-  # A THIRD SHAPE, NOT A UNION OF THE OTHER TWO — the same restraint the
-  # header above holds Banking's own two events to. `Privacy::Marking`'s
-  # own `Marked` event carries `domain`/`attribute_path`, matching
-  # neither `AccountFrozen` (`number`) nor `BoxSurrendered`
-  # (`branch_code`/`box_number`), so this gets its own aggregate rather
-  # than an artificial union.
-  #
-  # REACHED VIA `translates`, NOT a `policy` this bluebook declares —
-  # which foreign domain's event a consumer conforms to is a wiring
-  # decision (see `HecksagonBuilder#translates`'s own header), so the
-  # reaction lives in whichever `.hecksagon` attaches both Privacy and
-  # Compliance, not here.
+  # A third shape, not a union of the other two: `Privacy::Marking`'s `Marked` event carries
+  # `domain`/`attribute_path`. Reached via `translates` in whichever `.hecksagon` attaches
+  # both Privacy and Compliance, since which foreign event to conform to is wiring.
   aggregate "PrivacyReview" do
     description "The compliance review a newly marked sensitive field gets, opened the moment Privacy::Marking.Mark already happened."
 
@@ -184,12 +139,8 @@ Hecks.bluebook "Compliance" do
       transition "Escalate" => "escalated", from: "open"
     end
 
-    # SYSTEM-TRIGGERED, matching only `Privacy::Marking`'s own identity
-    # fields — the `translates` block that reacts to `Marked` forwards
-    # just `domain`/`attribute_path`, the same restraint
-    # `AccountFreezeReview.Open`/`BoxSurrenderReview.Open` already hold
-    # themselves to above; `category`/`readable_by` stay on the
-    # marking itself, not duplicated here.
+    # System-triggered. Takes only `Marking`'s identity fields; `category`/`readable_by` stay
+    # on the marking.
     command "Open" do
       role "System"
       goal "Register that a newly marked sensitive field needs compliance review"

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

@@ -2,80 +2,38 @@ Hecks.bluebook "ConsoleSettings" do
   vision "A generic admin console's own curated UI facts — nav, columns, state tones, which rows a detail panel shows — as real dispatched data instead of a hand-rewritten YAML file. A UI opinion the DOMAIN it's pointed at has no way to answer, never a business record; see the console app's own presentation_config.rb for the fuller story."
   supporting
 
-  # A FRAMEWORK MEMBER LIKE IDENTITY/GOVERNANCE — attach with
-  # `uses_framework "ConsoleSettings"` in the consuming app's own
-  # `.hecksagon`, plus a `Hecks.hecksagon "ConsoleSettings" do ... end`
-  # persistence binding (Heki is the common case — a small, local,
-  # per-app settings store, no shared database needed). This used to
-  # boot in a SECOND, independent registry (the console app's own
-  # console_settings_domain.rb) specifically so no consuming app needed
-  # any change at all — that property is real and now given up on
-  # purpose, in favor of the one binding mechanism every other
-  # framework member already uses, rather than this being the one
-  # exception with its own private boot path.
-  #
-  # NOT named "Forms" — Hecks::Forms (lib/hecks/forms/) already
-  # names a different, real thing: a dormant prototype (the working half
-  # of command_form.bluebook/query_form.bluebook, see docs/command-form-
-  # and-query-form-bluebook.md) that renders raw forms/query views
-  # straight off any IR, zero config. This chapter is the opposite kind
-  # of surface — a CURATED, hand-authored dashboard's own settings — and
-  # picks a name that doesn't read as the same one.
-  #
-  # SCOPE: everything presentation.yml carries EXCEPT a collection's own
-  # `after_create` (a dispatch chain with a literal-or-$field-or-
-  # count_query arg shape — a harder design problem that shouldn't gate
-  # everything else; Ruby-side PresentationConfig keeps validating it,
-  # same as always, with nowhere yet to persist it). `overview.stats`
-  # (Overview, below) and every `extra_json`/`identity_extra_json`
-  # field throughout this chapter were BOTH originally scoped out on an
-  # "confirmed unused in any real presentation.yml" basis that turned
-  # out to be checked against the wrong file — the console app's own
-  # fixture, never this app's actual, live one. Migrating the real file
-  # found both very much in use.
+  # A framework member like Identity/Governance: attach with
+  # `uses_framework "ConsoleSettings"` in the consuming app's own `.hecksagon`,
+  # plus a `Hecks.hecksagon "ConsoleSettings" do ... end` persistence binding.
+
+  # Named ConsoleSettings, not "Forms" — Hecks::Forms (lib/hecks/forms/) names a
+  # different thing, a raw form/query renderer straight off any IR. This chapter
+  # is a curated, hand-authored dashboard's own settings.
+
+  # Scopes everything presentation.yml carries except a collection's own
+  # `after_create` dispatch chain (a harder arg shape, still validated in Ruby).
+  # `overview.stats` and the `extra_json`/`identity_extra_json` fields below are
+  # real, in-use fields, confirmed against the app's actual presentation.yml.
 
   aggregate "StateStyle" do
     description "One aggregate's one lifecycle state, styled — a tone and whether it needs attention. Every real state gets a row, even a bare one (PresentationConfig's own missing_state_entries! check), so Declare and the two Set commands are separate: a bare row is a real, valid thing to have."
 
     # `agg`, not `aggregate` — the bluebook DSL's own word for what's being
-    # declared right now; naming an attribute that would shadow it invites
-    # exactly the confusion ui_schema.rb's own identity-collision fix
-    # (see [[project_generic_founder_app]]) already had to work around
-    # once for `id`.
+    # declared; an attribute of that name would shadow it, the same collision
+    # ui_schema.rb already had to work around once for `id`.
     attribute :agg,       StateStyleText
     attribute :state,     StateStyleText
     attribute :tone,      one_of("good", "warn", "danger", "muted", "accent"), optional: true
 
     identified_by :agg, :state
-    # `Flag`, wrapping "true"/"false" — not a bare `String` and not
-    # `TrueClass`. Two confirmed-by-trying reasons neither works directly
-    # on an aggregate/command attribute:
-    #   - `TrueClass`/`FalseClass` are real, pre-existing Ruby constants,
-    #     so writing them here resolves through NORMAL Ruby constant
-    #     lookup rather than ever reaching the DSL's own ConstShim (unlike
-    #     a bareword like `Flag`, which has no such constant and so DOES
-    #     reach it) — the meta-validator has no separate case for the
-    #     literal class objects, so it goes looking for a declared value
-    #     object named "TrueClass" and fails. `Attribute::PRIMITIVES`
-    #     lists them, but no real bluebook in this codebase spells one.
-    #   - A bare primitive (`String`, `Integer`) directly on an
-    #     AGGREGATE or COMMAND attribute fails the identical way — every
-    #     real example in this codebase only ever uses `String`/`Integer`
-    #     INSIDE a `value_object do...end` block, never as a top-level
-    #     attribute's own type; reproduced with a 4-line isolated bluebook
-    #     before trusting it as a real rule, not a guess.
-    # PresentationConfig's own Ruby glue converts "true"/"false" at the
-    # boundary.
+    # `Flag` wraps "true"/"false" as a value object: `TrueClass` resolves as a
+    # real Ruby constant rather than reaching ConstShim, and a bare `String`/
+    # `Integer` fails the same way directly on an aggregate/command attribute.
     attribute :attention, Flag, optional: true
 
-    # WHATEVER A STATE ENTRY CARRIES THAT ISN'T tone/attention — a
-    # display `label` (e.g. Client's own "active" reading "Active
-    # client", not the raw state name) or a `note`, confirmed live as
-    # real, in-use fields this schema didn't model. Serialized, not
-    # decomposed — the same verified-then-opaque reasoning Overview's
-    # own `where_json` already documents: PresentationConfig's own
-    # reshape/write is where the real key set is enumerated and
-    # subtracted from, in Ruby, not here.
+    # Carries whatever a state entry has beyond tone/attention (e.g. a display
+    # `label` or a `note`) — serialized, not decomposed; PresentationConfig's
+    # own reshape/write enumerates the real key set in Ruby, not here.
     attribute :extra_json, StateStyleExtra, optional: true
 
     value_object "StateStyleText" do
@@ -87,10 +45,8 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :value, String
     end
 
-    # A bare `String` fails directly on an aggregate/command attribute
-    # (StateStyleText's own comment gives the confirmed-by-trying
-    # reason) — this wraps extra_json's own opaque JSON text the same
-    # way every other scalar field in this chapter already wraps one.
+    # Wraps extra_json's opaque JSON text — a bare `String` fails directly on
+    # an aggregate/command attribute (see the `Flag` comment above).
     value_object "StateStyleExtra" do
       attribute :value, String
     end
@@ -158,23 +114,17 @@ Hecks.bluebook "ConsoleSettings" do
     attribute :identity_strategy,    one_of("slug", "sequence", "port"), optional: true
     attribute :identity_source,      SettingsText, optional: true
     attribute :identity_prefix,      SettingsText, optional: true
-    # `pad` (a sequence strategy's own zero-padding width, e.g. "C-004"
-    # vs "C-4") confirmed live as real, in-use — not modeled as its own
-    # attribute for the same reason `identity_source`/`identity_prefix`
-    # aren't a closed set either: whatever a real identity rule carries
-    # beyond field/strategy/source/prefix, opaque, same as extra_json
-    # below.
+    # `pad` (a sequence strategy's zero-padding width, e.g. "C-004" vs "C-4")
+    # is real but unmodeled here, same as identity_source/identity_prefix —
+    # carried opaquely in identity_extra_json below.
     attribute :identity_extra_json,  CollectionExtra, optional: true
     attribute :columns,              list_of(Column)
     attribute :detail_fields,        list_of(DetailField)
     attribute :detail_field_columns, list_of(DetailFieldColumn)
     attribute :preconditions,        list_of(Precondition)
     attribute :field_formats,        list_of(FieldFormat)
-    # WHATEVER A COLLECTION ENTRY CARRIES beyond the fields above —
-    # `noun_sing`, `create_label`, `nav_group` confirmed live as real,
-    # in-use fields this schema didn't model (10/8/2 real occurrences
-    # respectively). Same verified-then-opaque reasoning as StateStyle's
-    # own extra_json.
+    # Carries real, in-use fields this schema doesn't model (e.g. `noun_sing`,
+    # `create_label`, `nav_group`) — opaque, same as StateStyle's extra_json.
     attribute :extra_json,           CollectionExtra, optional: true
 
     value_object "SettingsText" do
@@ -186,21 +136,15 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :value, Integer
     end
 
-    # A bare `String` fails directly on an aggregate/command attribute —
-    # see StateStyleExtra's own comment. Shared by both extra_json and
-    # identity_extra_json; both are opaque JSON text, no reason for two
-    # separate wrapper types.
+    # Shared by extra_json and identity_extra_json — both opaque JSON text, no
+    # reason for two wrapper types. A bare `String` fails on an attribute directly.
     value_object "CollectionExtra" do
       attribute :value, String
     end
 
-    # A list/table column. `sortable`/`sort_default` are optional — most
-    # columns take the frontend's own default (sortable, no forced order).
-    # `sort_default` stays a plain String, not a closed set — narrow
-    # enough (and PresentationConfig.validate! already checks it in
-    # Ruby) that a dedicated `one_of: [...]` (S3, ADR 0025 — the field's
-    # own keyword now, no sibling value object or `admits:` indirection
-    # needed) still isn't worth it for this one field.
+    # A list/table column. `sortable`/`sort_default` are optional (most columns
+    # take the frontend's default). `sort_default` stays a plain String rather
+    # than a closed `one_of` (ADR 0025) — PresentationConfig.validate! checks it.
     value_object "Column" do
       attribute :field,        String
       attribute :sortable,     String, optional: true  # "true"/"false" — see StateStyle.attention's own comment
@@ -211,14 +155,9 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :extra_json,   String, optional: true
     end
 
-    # One field the detail panel shows. `state_filter` only means anything
-    # on an entity-backed rows field (ui_schema.rb's own apply_row_state_
-    # filter checks this at read time, same as it does today) — nothing
-    # here refuses a state_filter on the wrong shape of field, since that
-    # check needs the APP's own live IR, which this domain can't see; it
-    # stays a Ruby-side PresentationConfig.validate! check, same as always.
-    # `display` is a plain String for the same nested-`one_of` collision
-    # reason `sort_default` is, above.
+    # One field the detail panel shows. `state_filter` only applies to an
+    # entity-backed rows field; nothing here enforces that, since it needs the
+    # app's own live IR — PresentationConfig.validate! checks it in Ruby.
     value_object "DetailField" do
       attribute :field,        String
       attribute :display,      String, optional: true
@@ -229,10 +168,9 @@ Hecks.bluebook "ConsoleSettings" do
       attribute :extra_json,   String, optional: true
     end
 
-    # A rows-shaped detail field's own sub-column filter, FLATTENED to one
-    # row per (field, column) pair rather than nested inside DetailField —
-    # grouped back by `field` on the way out. The same flattening
-    # Query::AskOption already uses for a compound option's own parts.
+    # A rows-shaped detail field's sub-column filter, flattened to one row per
+    # (field, column) pair and grouped back by `field` on the way out — the
+    # same flattening Query::AskOption uses for a compound option's parts.
     value_object "DetailFieldColumn" do
       attribute :field,  String
       attribute :column, String
@@ -397,15 +335,9 @@ Hecks.bluebook "ConsoleSettings" do
     end
   end
 
-  # THE DASHBOARD'S OWN STAT CARDS — domain-WIDE, not per-aggregate the
-  # way Collection is (a stat can name any collection, or none in
-  # particular), so this is a SINGLETON: exactly one row, ever, for the
-  # whole console. `attribute :key, OverviewKey` holds a literal constant
-  # ("overview") rather than anything a person chooses — the same reason
-  # a creating command needs SOME identity to hydrate against (hydrate's
-  # own "an identity that is invented is neither derived from the record
-  # nor permanently associated with it" comment), just with the value
-  # fixed instead of derived from what's being declared.
+  # Domain-wide, not per-aggregate: exactly one row, ever, for the whole
+  # console. `key` holds a literal constant ("overview") rather than anything
+  # chosen, since a creating command still needs some identity to hydrate against.
   aggregate "Overview" do
     description "The console's own dashboard stat cards, whole. One row, ever — `key` is always the literal 'overview', never chosen. Every stat gets replaced as a whole list on save, the same 'replace whole, never patch one' convention Collection's own columns/detail_fields/preconditions/field_formats already use."
 
@@ -420,20 +352,9 @@ Hecks.bluebook "ConsoleSettings" do
       invariant("is the one true singleton key") { value == "overview" }
     end
 
-    # `where_json` carries the stat's own recursive filter expression
-    # (`not:` wrapping another whole where clause, `state:`/
-    # `has_related:`/`not_has_related:` combined by implicit AND) —
-    # serialized, not decomposed into the bluebook's own closed
-    # attribute grammar. That tree is genuinely open-ended (arbitrary
-    # nesting depth via `not:`, an arbitrary literal attribute name as
-    # a where key for anything that isn't `state`), and hecks's
-    # attribute types have no way to express "arbitrary nested map" at
-    # all — the same reason `sort_default`/`display`/`format` above stay
-    # plain Strings rather than a nested `one_of`. PresentationConfig's
-    # own `validate_where!`/`validate_has_related!` still walk and check
-    # the REAL structure, in Ruby, against the app's own live IR, before
-    # this is ever serialized and dispatched — this field is the
-    # verified-then-opaque storage, not an unchecked one.
+    # `where_json` carries the stat's recursive filter expression, serialized
+    # rather than decomposed — the tree is open-ended and hecks's attribute
+    # types can't express it. PresentationConfig.validate_where! checks it in Ruby.
     value_object "Stat" do
       attribute :label,      String
       attribute :collection, String
@@ -464,17 +385,9 @@ Hecks.bluebook "ConsoleSettings" do
     end
   end
 
-  # BOTH ROOTLESS — bulk, no root record, no id argument at dispatch —
-  # and grouped by an aggregate's own full identity, which is what makes
-  # each leaf exactly one row rather than an arbitrary collision (see
-  # `group_by`'s own reference doc). PresentationConfig.rb's own read
-  # side (`reshape_states`/`reshape_collections`) dispatches these
-  # instead of hand-rolling the unwrap/grouping in Ruby — see its own
-  # header for what's still Ruby (the detail_field_columns/detail_fields
-  # join, which isn't a report concern at all — two list attributes on
-  # the SAME record, not two aggregates — and Overview's own stat cards,
-  # which are read straight off Overview.find, a singleton needing
-  # neither grouping nor unwrapping either).
+  # Both read models are rootless (bulk, no id at dispatch) and grouped by an
+  # aggregate's full identity, so each leaf is exactly one row. Dispatched from
+  # PresentationConfig's read side rather than hand-rolled in Ruby.
   read_model "Styles" do
     description "Every StateStyle row, nested by the aggregate and state it styles."
     include StateStyle

data/lib/hecks/framework/bluebook/framework.hecksagon

@@ -1,21 +1,13 @@
-# The framework members, bound so they can boot standing alone —
-# `Hecks.boot("lib/hecks/framework")` rather than only as something
-# another domain attached with `uses_framework`.
-#
-# `uses_framework` does NOT read this file (Framework.load! loads a
-# member's bluebook and nothing else, deliberately — see framework.rb),
-# so an attaching domain still declares its own binding for these
-# aggregates, exactly as before. This only answers the case where the
-# framework is the domain being booted.
+# The framework members bound to Memory so they can boot standing alone with
+# `Hecks.boot("lib/hecks/framework")`. `uses_framework` does not read this file.
 Hecks.hecksagon "Compliance" do
-  # Every command here declares `role "Compliance officer"` — only real
-  # access control once Governance can check it against something (S8).
+  # Every command declares `role "Compliance officer"`; the role check needs Governance.
   uses_framework "Governance"
   persisted_by "Memory"
 end
 
 Hecks.hecksagon "ConsoleSettings" do
-  # Same reason as Compliance, above — S8.
+  # Same reason as Compliance.
   uses_framework "Governance"
   persisted_by "Memory"
 end
@@ -25,8 +17,7 @@ Hecks.hecksagon "Governance" do
 end
 
 Hecks.hecksagon "Identity" do
-  # `Identity::Identity.Register` declares `role "Identity registrar"` —
-  # same reason as Compliance/ConsoleSettings, above — S8.
+  # `Identity.Register` declares `role "Identity registrar"`; same reason as Compliance.
   uses_framework "Governance"
   persisted_by "Memory"
 end

data/lib/hecks/framework/bluebook/governance.bluebook

@@ -2,10 +2,9 @@ Hecks.bluebook "Governance" do
   vision "Organizational authority is explicit, reviewable, and historically explainable."
   supporting
 
-  # WHAT THIS CHAPTER ANSWERS FOR EVERY DOMAIN THAT ATTACHES IT. The role
-  # check at dispatch, boot's refusal of an ungoverned `role`, the
-  # authorization adapter and the fuzzer's grant steering all read these
-  # three verbs from here, rather than recognising "Governance" by name.
+  # What this chapter answers for every attaching domain: the role check at dispatch, boot's
+  # refusal of an ungoverned `role`, the authorization adapter and the fuzzer's grant
+  # steering read these three verbs from here rather than recognising "Governance" by name.
   provides "authorization",
            assignments: "RoleAssignment.AssignmentsForActor",
            grant:       "RoleAssignment.Assign",
@@ -14,12 +13,9 @@ Hecks.bluebook "Governance" do
   aggregate "RoleAssignment" do
     description "One actor holding one role, over one scope, from one point in time — revoked by setting when it ended, never deleted."
 
-    # THE IDENTITY IS THE EVENT, not the (actor, role) pair — an actor can
-    # hold the same role again later, after a prior assignment ended, and
-    # that is a SECOND real assignment, not a state to overwrite. No UUID
-    # adapter exists yet in this codebase to mint a synthetic id, and none
-    # is needed: `starts_at` already makes "this actor started holding this
-    # role at this time" unique on its own.
+    # The identity is the event, not the (actor, role) pair: an actor can hold a role again
+    # after a prior assignment ended, and that is a second assignment. `starts_at` makes each
+    # one unique.
     attribute :actor_id,  IdentityId
     attribute :role_name, RoleName
     attribute :scope,     Scope
@@ -78,21 +74,10 @@ Hecks.bluebook "Governance" do
     end
   end
 
-  # WHO HOLDS A ROLE is `RoleAssignment`'s question. This is a different one:
-  # may role X ACT AS role Y — the fact `act_as` (the plan's §2) needs before
-  # a caller is allowed to dispatch under a role it does not itself hold.
-  # Same event-log shape as RoleAssignment : a natural key, `ends_at` for
-  # revocation, no delete — and, like RoleAssignment, THE IDENTITY IS THE
-  # GRANT, not the (from_role, to_role) pair. `starts_at` used to be
-  # missing from here — the one field RoleAssignment's own identity adds
-  # beyond its own (actor, role) pair specifically so a second, later
-  # assignment is a SECOND real record rather than a collision. Without
-  # it, `identified_by :from_role, :to_role` alone made a revoked pair's
-  # own identity permanently occupied: `Grant` is a creating command, the
-  # same (from_role, to_role) pair is the SAME id forever, and a repeat
-  # `Grant` after a `Revoke` was refused as `AlreadyExists` no matter how
-  # long ago the prior grant ended — an absorbing "revoked" state this
-  # very comment already claimed didn't exist.
+  # Whether role X may act as role Y, which `act_as` needs before a caller dispatches under a
+  # role it does not hold. Same event-log shape as RoleAssignment, and the identity is the
+  # grant: without `starts_at`, a revoked pair would occupy its id forever and a repeat
+  # `Grant` would be refused as `AlreadyExists`.
   aggregate "RoleTransition" do
     description "Role X is authorized to act as role Y, from one point in time — until revoked, and grantable again afterward, exactly like RoleAssignment."
 
@@ -135,15 +120,9 @@ Hecks.bluebook "Governance" do
       emits RoleTransitionRevoked
     end
 
-    # EVERY GRANT OF THIS PAIR, current or historical — same deferral
-    # `AssignmentsForActor` already makes for RoleAssignment: the where
-    # clause has no way to ask "and ends_at is absent", so the query
-    # answers with every row and the CALLER reads `ends_at` to tell a
-    # live grant from a revoked one, exactly as it already must for
-    # every assignment. Can answer MORE than one row now that `starts_at`
-    # is part of the identity — a pair granted again after a revocation is
-    # a SECOND row, not an overwrite of the first, the same way a
-    # re-assigned actor/role is for RoleAssignment.
+    # Every grant of this pair, current or historical: `where` cannot ask "ends_at is absent",
+    # so the caller reads `ends_at` to tell a live grant from a revoked one. A pair granted
+    # again after a revocation is a second row.
     query "Allowed" do
       description "Every role transition granted for this exact pair, current or historical."
       attribute :from_role, RoleName