hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,581 @@
+Hecks.bluebook "Bluebook" do
+  aggregate "Aggregate" do
+    description "One aggregate inside a chapter — the head a domain's declarations attach to."
+
+    reference_to Bluebook
+
+    # THE CHAPTER IT IS IN, AND ITS NAME. `Order` names nothing on its own — two
+    # chapters may both declare one — so the chapter is part of the identity, not
+    # context around it. This is the derivation `MetaValidator::Judge#identify`
+    # spelled by hand as "#{parent_id}::#{name}" for as long as the language could
+    # not say it.
+    identified_by :bluebook, :name
+
+    # SPELLED AS THE IR SPELLS THEM — see the note on Command's fields.
+    attribute :name,          AggregateName
+    attribute :description,   Description
+    attribute :provenance,    LiteralText
+    # SEVERAL PATHS, because the identity is their JOIN. One is the ordinary case ;
+    # more than one is what anything named BENEATH another thing needs, and the
+    # language's own chapters are all of that kind — a command is not named by
+    # `Declare`, which every aggregate here spells, but by the aggregate it belongs
+    # to AND that name. Held as a list for the same reason attributes are : the
+    # order is a fact about the source, and the join reads in it.
+    attribute :identified_by, list_of(IdentityPath)
+    attribute :attributes,    list_of(Field)
+    attribute :value_objects, list_of(ValueName)
+    attribute :state_field,   IdentityField, optional: true
+    attribute :state_start,   IdentityField, optional: true
+    attribute :transitions,   list_of(Transition)
+    # THE AGGREGATE BOUNDARY (S10, ADR 0025 — "Rules") — checked after
+    # every command, before save, the SAME Rule shape Command's own
+    # givens/ensures already carry (description+canonical), declared
+    # again here rather than shared: a closed set/value object is
+    # aggregate-scoped in this self-hosting domain, the same reason
+    # CommandText and LiteralText stay two separate, identically-
+    # shaped value objects rather than one reused across chapters.
+    attribute :invariants,    list_of(Rule)
+    # A PRECONDITION SHARED ACROSS COMMANDS, DECLARED ONCE (S10, ADR
+    # 0025) — the SAME Rule shape, the aggregate's own named `given`s
+    # that a referencing command's own (already-resolved) `given`
+    # entry came from.
+    attribute :preconditions, list_of(Rule)
+    # A FIELD READ THROUGH A REFERENCE, HELD LOCALLY (S12, ADR 0025 —
+    # "Consistency across aggregate boundaries") — the local half of
+    # `projects :name, from: :"reference.remote_field"`. Deliberately
+    # NOT folded into `attributes` — see the comment on
+    # `Aggregate#emits_ir`'s own `projected_fields:` entry for why.
+    attribute :projected_fields, list_of(ProjectedField)
+
+    value_object "AggregateName" do
+      attribute :value, String
+      invariant("an aggregate is named") { !value.to_s.empty? }
+    end
+
+    value_object "Description" do
+      attribute :value, String
+      invariant("a description says something") { !value.to_s.empty? }
+    end
+
+    value_object "IdentityField" do
+      attribute :value, String
+    end
+
+    # ONE PART OF AN IDENTITY — a path down to the SCALAR that carries it, like
+    # "number.value". A part on its own is not an identity ; the identity is every
+    # part joined, in the order they were declared.
+    #
+    # Its field is `value`, like every other one-field value object in this
+    # language, because that is the name the judge wraps a cell under. Spelling it
+    # `path` made `path.path` read nothing, and a given that reads nothing does not
+    # fail — it refuses everything, which is a far quieter way to be wrong.
+    value_object "IdentityPath" do
+      attribute :value, String
+    end
+
+    value_object "Field" do
+      attribute :name,    String
+      attribute :type,    String
+      attribute :list,    String
+      attribute :optional, String, optional: true
+      attribute :pattern,  String, optional: true
+      # Held as a LITERAL, written so its type survives — 0.0 rather than "0.0".
+      # Without this an aggregate attribute's default was simply dropped, and the
+      # reconstruction hardcoded nil, which happened to match every corpus member
+      # and would have lied about the first one that declared a default.
+      attribute :default, String
+      # THE CLOSED SET THIS VALUE MUST BELONG TO, named where it was already
+      # declared — `Vocabulary::QueryComparator`. Qualified by the aggregate that
+      # holds it, because a closed set is a value object INSIDE an aggregate and
+      # the aggregate is the only thing a reference can reach ; `one_of` is the
+      # other word and it can only ever SYNTHESISE a new set, never name one
+      # twice. Absent for almost every attribute, so it is optional.
+      attribute :admits, String, optional: true
+      # `reference_to`, `belongs_to`, `has_one`, or `has_many`; absent on
+      # ordinary value/entity fields. This keeps relationship language through
+      # the self-hosted round trip instead of collapsing it to a reference.
+      attribute :relationship, String, optional: true
+    end
+
+    value_object "ValueName" do
+      attribute :name, String
+    end
+
+    value_object "Transition" do
+      attribute :command,    String
+      attribute :from_state, String
+      attribute :to_state,   String
+    end
+
+    # THE SAME SHAPE Command's own "Rule" value object carries — see
+    # behavior.bluebook — declared again here rather than shared, per
+    # that value object's own comment.
+    value_object "Rule" do
+      attribute :description, String
+      attribute :canonical,   String
+    end
+
+    # S12, ADR 0025 — `name` is this aggregate's own field being
+    # declared; `reference` names the local `reference_to` attribute to
+    # read through; `remote_field` names the scalar on the target. All
+    # three are plain identifiers, the same shape `Field#name`/`#type`
+    # already are.
+    value_object "ProjectedField" do
+      attribute :name,         String
+      attribute :reference,    String
+      attribute :remote_field, String
+    end
+
+    command "Declare" do
+      role "Language"
+      goal "Open an aggregate inside a chapter"
+
+      reference_to Bluebook
+      attribute :name,          AggregateName
+      attribute :description,   Description, optional: true
+      # See Command.Declare's own `provenance` — identical shape, one
+      # level up. LiteralText, not a dedicated value object: the field
+      # rides the same self-describing `inspect` encoding `default:`
+      # already uses, so it needs no invariant of its own.
+      attribute :provenance,    LiteralText, optional: true
+
+      attribute :position, Position, optional: true
+
+      sets :bluebook
+      sets :name
+      sets :description
+      sets :provenance
+      sets :position
+      emits "RootDeclared"
+    end
+
+    # ONE PART OF THE IDENTITY, attached the way one attribute is. It was an
+    # argument on Declare while an identity was a single field ; a list cannot be
+    # carried by one argument, and every other list in this language is filled by
+    # a verb of its own, so this is the shape that was already here.
+    command "Identify" do
+      role "Language"
+      goal "Attach one part of the aggregate's identity"
+
+      attribute :path, IdentityPath
+
+      # AN IDENTITY PART NAMES SOMETHING. This rule used to sit on Seal reading
+      # `empty? || == "id" || includes(".")` — two escapes and a check. The escapes
+      # were the whole of it : `empty?` let an aggregate say nothing and be given a
+      # minted `id`, and `== "id"` let it name that slot outright. Both are gone,
+      # so what is left is the rule itself, and it now runs on every part rather
+      # than on whichever one a single field happened to hold.
+      #
+      # THREE WAYS TO REACH A SCALAR (ADR 0025, "Identity"), and this given no
+      # longer distinguishes them — it used to accept only a dotted path
+      # (`number.value`, a value object's own field) or an `_id`-suffixed
+      # reference, and REFUSED a bare scalar field (`sku`), which is legal
+      # too : a plain primitive attribute IS already a scalar, nothing to
+      # open. That distinction belongs to the BUILDER, which resolves each
+      # spelling before an identity part ever reaches here
+      # (`AttributeCollector#resolve_identity_field!` — the single place
+      # that decides dotted-unwrap vs. reference vs. bare-scalar, and the
+      # only place that can, since it alone holds the attribute's declared
+      # type). What is left for THIS rule to say, once the builder has
+      # already resolved a real shape, is only that a part was actually
+      # given a name at all.
+      given("an identity part names something") { !path.value.to_s.empty? }
+
+      sets :identified_by, append: { value: :path }
+      emits "RootIdentified"
+    end
+
+    # The way back, one level down: the aggregates DECLARED IN a chapter, found by
+    # the chapter that declared them. The parent reference IS the query.
+    #
+    # `bluebook_id` is an IdentityField, not an AggregateName — it holds the id of
+    # the chapter above, and calling that a name for aggregates was sloppiness that
+    # would read as a lie the first time somebody looked.
+    # WHERE IT SITS AMONG ITS SIBLINGS. Declaration order is a FACT ABOUT THE
+    # SOURCE — the IR is a contract read straight from this file,
+    # field for field AND INDEX FOR INDEX. So the language HOLDS it, instead of
+    # inheriting it from whatever order a store happens to iterate: an ask that
+    # does not say how it is ordered is answered in identity order, which is
+    # right for every other ask and fatal for the one that is the SOURCE.
+    value_object "Position" do
+      attribute :value, Integer
+    end
+
+    attribute :position, Position
+
+    query "DeclaredIn" do
+      attribute :bluebook, IdentityField
+      where(bluebook: :bluebook)
+      order_by :position
+    end
+
+    command "Attribute" do
+      role "Language"
+      goal "Attach one attribute to the aggregate"
+
+      # The TYPE is a reference to the value object it names. An attribute
+      # naming an undeclared value object then fails REFERENCE RESOLUTION —
+      # "no Shape with id …" — with no predicate at all.
+      #
+      # This is the rule "attributes must use value-object types", which could
+      # not be a `given` : it needs, for each element of a list, a check against
+      # another list, and the sublanguage has no quantifier and cannot see
+      # inside a list element. As a reference it stops being a predicate and
+      # becomes a consequence of the model.
+      reference_to ValueObject, as: :type
+      attribute :name,    FieldName
+      attribute :list,    ListFlag
+      attribute :optional, ListFlag, optional: true
+      # A PATTERN IS A REGEX, not a flag — see the note on ListFlag below.
+      attribute :pattern,  LiteralText, optional: true
+      attribute :default, LiteralText, optional: true
+      # FREE TEXT, not a reference. A closed set is a value object INSIDE an
+      # aggregate, and `reference_to` reaches heads only — so the qualified name
+      # is carried as text and checked where it is READ, by the reader, which
+      # already raises for the other things the language cannot say about itself.
+      attribute :admits,  LiteralText, optional: true
+      attribute :relationship, LiteralText, optional: true
+
+      sets :attributes, append: { name: :name, type: :type, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits "AttributeAttached"
+    end
+
+    # An attribute that points at ANOTHER aggregate's head.
+    #
+    # `Attribute` types its type as `reference_to ValueObject`, which is what makes
+    # "attributes use value-object types" a consequence of the model rather than a
+    # predicate. A cross-aggregate reference cannot go through it: its type is
+    # `Reference<Customer>`, which is not a value object and never will be. So the
+    # judge SKIPPED every one of them, and the meta-domain did not hold
+    # Account#customer_id at all — the way back was lossy for exactly one
+    # construct, and the comment excusing it said "the language does not model
+    # reference-typed attributes yet".
+    command "Reference" do
+      role "Language"
+      goal "Attach an attribute that points at another aggregate's head"
+
+      # POINTS AT a declared head, and that is the whole rule.
+      #
+      # This carried `attribute :type, ReferenceType` — a STRING — with an invariant
+      # apologising for itself, because the shape that actually tells a reference
+      # from a value object (`Reference<Something>`) is unsayable in the predicate
+      # sublanguage. That was never a sublanguage gap; a string was simply the wrong
+      # model. As a reference it stops being a predicate and becomes a consequence
+      # of the model, exactly as Attribute's type does — and it is STRONGER than the
+      # prefix match, which only ever checked that the text looked right.
+      reference_to Aggregate, as: :points_at
+      attribute :name,    FieldName
+      attribute :list,    ListFlag
+      attribute :optional, ListFlag, optional: true
+      # A PATTERN IS A REGEX, not a flag — see the note on ListFlag below.
+      attribute :pattern,  LiteralText, optional: true
+      attribute :default, LiteralText, optional: true
+      attribute :admits,  LiteralText, optional: true
+      attribute :relationship, LiteralText, optional: true
+
+      sets :attributes, append: { name: :name, type: :points_at, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits "ReferenceAttached"
+    end
+
+    # An attribute whose type names a PIECE this aggregate holds.
+    #
+    # `Account#ledger` is a list of LedgerEntry — neither a value object nor another
+    # aggregate's head — so it fitted no verb and the walk skipped it, the last
+    # construct the way back could not carry. Same trick as Reference: point at the
+    # entity's own declaration, and "an aggregate holds a piece it declared" costs
+    # no predicate at all. Entities are declared before attributes are offered, so
+    # the reference resolves.
+    command "Holds" do
+      role "Language"
+      goal "Attach an attribute whose type is a piece of this aggregate"
+
+      reference_to Entity, as: :holds
+      attribute :name,    FieldName
+      attribute :list,    ListFlag
+      attribute :optional, ListFlag, optional: true
+      # A PATTERN IS A REGEX, not a flag — see the note on ListFlag below.
+      attribute :pattern,  LiteralText, optional: true
+      attribute :default, LiteralText, optional: true
+      attribute :admits,  LiteralText, optional: true
+      attribute :relationship, LiteralText, optional: true
+
+      sets :attributes, append: { name: :name, type: :holds, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits "PieceHeld"
+    end
+
+    # THE ONLY RULE THAT CAN REFUSE AN UNNAMED ATTRIBUTE, and it lives here.
+    #
+    # Attribute, Reference and Holds each carried `given("… is named")` beside
+    # this, and not one of them could ever fire: an EMPTY name builds the value
+    # object and this invariant refuses first, while an ABSENT name builds no
+    # value object and the given did not refuse at all — probed, not reasoned.
+    # Three rules that read as rules and were decoration. A predicate cannot
+    # guard what a type already guards.
+    value_object "FieldName" do
+      attribute :value, String
+      invariant("an attribute is named") { !value.to_s.empty? }
+    end
+
+    value_object "TypeName" do
+      attribute :value, String
+      invariant("a type is named") { !value.to_s.empty? }
+    end
+
+    # A literal written the way it can be read back — see Readings#encode_literal.
+    value_object "LiteralText" do
+      attribute :value, String
+    end
+
+    # TRUE OR FALSE, AND NOTHING ELSE. `list` and `optional` are the two fields
+    # this is about — they are the answers to a yes/no question, written as text
+    # because that is what the wire carries.
+    #
+    # `pattern` was typed with it too, which is not a loose typing but a FALSE
+    # one: a pattern holds a regex, and this invariant admits exactly two strings
+    # neither of which is one. It never fired only because no aggregate-level or
+    # entity-level attribute in the corpus declares a pattern — banking's one
+    # `pattern:` sits on a VALUE OBJECT field, which is built by
+    # `ValueObject.Field` and so went down a different command entirely. The
+    # first head that declared a pattern would have been refused by a rule about
+    # lists. It is `LiteralText` now, which is what the other four element
+    # builders already say a pattern is: free text.
+    value_object "ListFlag" do
+      attribute :value, String
+      invariant("list is true or false") { value.to_s == "true" || value.to_s == "false" }
+    end
+
+    command "Lifecycle" do
+      role "Language"
+      goal "Name the field this aggregate's state machine runs on"
+
+      attribute :state_field, FieldName
+      attribute :state_start, FieldName
+
+      sets :state_field
+      sets :state_start
+
+      emits "LifecycleNamed"
+    end
+
+    command "Transition" do
+      role "Language"
+      goal "Attach one transition to the state machine"
+
+      attribute :command,    FieldName
+      attribute :from_state, FieldName, optional: true
+      attribute :to_state,   FieldName
+
+      sets :transitions, append: { command: :command, from_state: :from_state, to_state: :to_state }
+
+      emits "TransitionAttached"
+    end
+
+    command "Seal" do
+      role "Language"
+      goal "Close an aggregate — the checks that need every declaration present"
+
+      # The builders validate at `build`, once everything is collected. A given
+      # fires at DISPATCH, when later declarations do not exist yet. So the
+      # whole-document rules live on a command dispatched after the aggregate
+      # is fully declared. This is the shape the tier-3 rules need ; whether
+      # the sublanguage can express their CONTENT is the open question.
+
+      # THE RULE THAT WAS HERE WAS NOT TRUE, and nothing could tell us while Seal
+      # went undispatched. `given("an aggregate declares at least one attribute")`
+      # was invented for this command — it is not one of the rules ported from the
+      # builders, so no bluebook was ever written against it. The first time it
+      # ran it refused twenty-five of them, including every aggregate whose state
+      # is a `lifecycle` rather than an `attribute` : a state machine declares no
+      # attribute and is perfectly well formed.
+      #
+      # Seal stays. It is the right SHAPE for a whole-document rule — dispatched
+      # once every declaration is present — and it is now actually dispatched, so
+      # the next rule put here will be seen refusing instead of sitting decorative.
+      # The rule waiting for it is "a mutation names a field the aggregate has",
+      # which lives in AggregateBuilder today because saying it here needs to reach
+      # a list on another root.
+      # AN AGGREGATE SAYS WHAT IT IS KNOWN BY. Nothing falls back to `id` any more.
+      #
+      # The fallback was never a default — it was a MINT. An aggregate that said
+      # nothing got an id invented for it, so the same declaration named a
+      # different record on the next run, and nothing outside the runtime could
+      # name a record at all. The rule that stood here permitted it in as many
+      # words (`empty? || == "id"`), and the comment named exactly who was
+      # leaning on it : the language's own chapters, all fourteen of them.
+      #
+      # They derive now, like everything else does. What each PART must look like
+      # is Identify's rule ; this one only asks that there be one.
+      given("an aggregate says what it is known by") { !identified_by.empty? }
+
+      emits "RootSealed"
+    end
+
+    command "Value" do
+      role "Language"
+      goal "Declare a value object belonging to this aggregate"
+
+      attribute :name, FieldName
+
+      sets :value_objects, append: { name: :name }
+
+      emits "ValueDeclared"
+    end
+
+    # THE AGGREGATE BOUNDARY (S10, ADR 0025 — "Rules") — the same shape
+    # Command.Rule attaches a given with, one level up.
+    command "Invariant" do
+      role "Language"
+      goal "Attach one invariant to the aggregate"
+
+      attribute :description, LiteralText, optional: true
+      attribute :canonical,   LiteralText
+
+      given("a rule says what it means")  { !description.value.to_s.empty? }
+      given("a rule survives extraction") { !canonical.value.to_s.empty? }
+
+      sets :invariants, append: { description: :description, canonical: :canonical }
+
+      emits "InvariantAttached"
+    end
+
+    # A PRECONDITION SHARED ACROSS COMMANDS, DECLARED ONCE (S10, ADR
+    # 0025) — the aggregate's own named `given`, referenced back by a
+    # command rather than re-typed.
+    command "Precondition" do
+      role "Language"
+      goal "Declare one precondition commands can reference by name"
+
+      attribute :description, LiteralText, optional: true
+      attribute :canonical,   LiteralText
+
+      given("a rule says what it means")  { !description.value.to_s.empty? }
+      given("a rule survives extraction") { !canonical.value.to_s.empty? }
+
+      sets :preconditions, append: { description: :description, canonical: :canonical }
+
+      emits "PreconditionAttached"
+    end
+
+    # THE LOCAL HALF OF A CROSS-AGGREGATE READ (S12, ADR 0025) — the
+    # target's own existence and shape are checked elsewhere
+    # (BluebookBuilder#validate_projected_fields!, once every aggregate
+    # in the chapter is real), the same two-tier split a query's own
+    # hop already uses.
+    command "Projects" do
+      role "Language"
+      goal "Declare a field read locally through a reference"
+
+      attribute :name,         FieldName
+      attribute :reference,    FieldName
+      attribute :remote_field, FieldName
+
+      given("a projected field is named")     { !name.value.to_s.empty? }
+      given("a projected field reads through a reference") { !reference.value.to_s.empty? }
+      given("a projected field names a remote field") { !remote_field.value.to_s.empty? }
+
+      sets :projected_fields, append: { name: :name, reference: :reference, remote_field: :remote_field }
+
+      emits "ProjectedFieldAttached"
+    end
+
+    # HOW AGGREGATE IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: Aggregate, Lifecycle.
+    value_object "KeywordSeed" do
+      attribute :word,          String
+      attribute :context,       String, admits: "Syntax::Context"
+      attribute :body,          String, admits: "Syntax::Body"
+      attribute :inner,         String
+      attribute :opens,         String
+      attribute :fills,         String
+      attribute :status,        String, default: "admitted", admits: "Syntax::Status"
+      attribute :was,           String
+      attribute :resolves_via,  String, default: "", admits: "Syntax::ResolutionScope"
+      attribute :disambiguator, String, default: "", admits: "Syntax::Disambiguator"
+
+      member word: "description",     context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "description"
+      member word: "provenance",      context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "provenance", calls: "provenance_impl"
+      member word: "identified_by",   context: "Aggregate", body: "keywords", inner: "ValueObject",   opens: "ValueObject",    fills: "identified_by", calls: "identified_by_impl"
+      member word: "identified_by",   context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "identified_by", calls: "identified_by_impl"
+      member word: "reference_to",    context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "attributes", calls: "reference_to_impl"
+      member word: "has_many",        context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "attributes", calls: "has_many_impl"
+      member word: "has_one",         context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "attributes", calls: "has_one_impl"
+      member word: "belongs_to",      context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "attributes", calls: "belongs_to_impl"
+      member word: "lifecycle",       context: "Aggregate", body: "keywords", inner: "Lifecycle",     opens: "",               fills: "state_field", calls: "lifecycle_impl"
+      member word: "entity",          context: "Aggregate", body: "keywords", inner: "Entity",        opens: "Entity",         fills: "", calls: "entity_impl"
+      member word: "query",           context: "Aggregate", body: "keywords", inner: "Query",         opens: "Query",          fills: "", calls: "query_impl"
+      member word: "policy",          context: "Aggregate", body: "keywords", inner: "Policy",        opens: "Policy",         fills: "", calls: "policy_impl"
+      member word: "value_object",    context: "Aggregate", body: "keywords", inner: "ValueObject",   opens: "ValueObject",    fills: "value_objects"
+      member word: "command",         context: "Aggregate", body: "keywords", inner: "Command",       opens: "Command",        fills: "", calls: "command_impl"
+      member word: "attribute",       context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "attributes", calls: "attribute_impl"
+      member word: "invariant",       context: "Aggregate", body: "source",   inner: "",              opens: "",               fills: "invariants", calls: "invariant_impl"
+      member word: "given",           context: "Aggregate", body: "source",   inner: "",              opens: "",               fills: "preconditions", resolves_via: "owner_keyed", disambiguator: "declared_by", calls: "given_impl"
+      member word: "projects",        context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "projected_fields", calls: "projects_impl"
+      member word: "transition",      context: "Lifecycle", body: "none", inner: "", opens: "",       fills: "transitions", calls: "transition_impl"
+
+    end
+
+    value_object "ArgumentSeed" do
+      attribute :keyword,          String
+      attribute :context,          String, admits: "Syntax::Context"
+      attribute :at,               String
+      attribute :named,            String
+      attribute :kind,             String, admits: "Syntax::ArgumentKind"
+      attribute :required,         String
+      attribute :fills,            String
+      attribute :selects,          String
+      attribute :pair_key_fills,   String
+      attribute :pair_value_fills, String
+      attribute :pairs_shape,      String, admits: "Syntax::PairsShape"
+      attribute :status,           String, default: "admitted", admits: "Syntax::Status"
+      attribute :variadic,         String
+      attribute :minimum,          String
+      attribute :coerce,           String
+      attribute :blank_message,    String
+
+      member keyword: "description",     context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "description", coerce: "false"
+      member keyword: "provenance",      context: "Aggregate", at: "",  named: "from",     kind: "literal",  required: "true",  fills: "provenance"
+      member keyword: "identified_by",   context: "Aggregate", at: "1", named: "",         kind: "symbol",   required: "false", fills: "identified_by", variadic: "true", minimum: "2"
+      member keyword: "identified_by",   context: "Aggregate", at: "1", named: "",         kind: "constant", required: "false", fills: "type"
+      member keyword: "identified_by",   context: "Aggregate", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "reference_to",    context: "Aggregate", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "reference_to",    context: "Aggregate", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "reference_to",    context: "Aggregate", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "has_many",        context: "Aggregate", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "has_many",        context: "Aggregate", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "has_one",         context: "Aggregate", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "has_one",         context: "Aggregate", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "has_one",         context: "Aggregate", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "belongs_to",      context: "Aggregate", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "belongs_to",      context: "Aggregate", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "belongs_to",      context: "Aggregate", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "lifecycle",       context: "Aggregate", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "state_field"
+      member keyword: "lifecycle",       context: "Aggregate", at: "",  named: "default",  kind: "literal",  required: "true",  fills: "state_start"
+      member keyword: "entity",          context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      member keyword: "query",           context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      member keyword: "policy",          context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      member keyword: "value_object",    context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      member keyword: "command",         context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      member keyword: "command",         context: "Aggregate", at: "",  named: "from",     kind: "literal",  required: "false", fills: "from"
+      member keyword: "attribute",       context: "Aggregate", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "name"
+      member keyword: "attribute",       context: "Aggregate", at: "2", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "attribute",       context: "Aggregate", at: "",  named: "default",  kind: "literal",  required: "false", fills: "default"
+      member keyword: "attribute",       context: "Aggregate", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "attribute",       context: "Aggregate", at: "",  named: "pattern",  kind: "text",     required: "false", fills: "pattern"
+      member keyword: "attribute",       context: "Aggregate", at: "",  named: "admits",   kind: "text",     required: "false", fills: "admits"
+      member keyword: "attribute",       context: "Aggregate", at: "",  named: "one_of",   kind: "list",     required: "false", fills: "one_of"
+      member keyword: "invariant",       context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "description"
+      member keyword: "given",           context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "description"
+      member keyword: "given",           context: "Aggregate", at: "",  named: "declared_by", kind: "constant", required: "false", fills: "declared_by"
+      member keyword: "projects",        context: "Aggregate", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "name"
+      member keyword: "projects",        context: "Aggregate", at: "",  named: "from",     kind: "symbol",   required: "true",  fills: "from"
+      member keyword: "transition",      context: "Lifecycle", at: "1", named: "",     kind: "pairs", required: "true",  fills: "", pair_key_fills: "command", pair_value_fills: "to_state", pairs_shape: "fields"
+      member keyword: "transition",      context: "Lifecycle", at: "",  named: "from", kind: "text",  required: "false", fills: "from_state"
+      member keyword: "transition",      context: "Lifecycle", at: "",  named: "from", kind: "list",  required: "false", fills: "from_state"
+
+    end
+  end
+end

data/lib/hecks/language/bluebook/attaches/paging.bluebook

@@ -0,0 +1,76 @@
+Hecks.bluebook "Paging" do
+  vision "The four words a page of results is read through — limit, offset, cursor, nulls — held as their own sub-language rather than as four more rows in the core's own grammar table. ADR 0026's own worked example: the core grammar does not name its extension points, so this chapter names ITSELF onto them, with `attaches_to`."
+  generic
+  attaches_to "Query", "ReadModel"
+
+  # A PLACE TO HOLD ROWS, AND NOTHING ELSE — the same shape `Vocabulary`
+  # (vocabulary.bluebook) already is: no commands, because nothing ever
+  # dispatches this aggregate for real. `SyntaxBoot`'s own generic
+  # discovery reads `KeywordSeed`/`ArgumentSeed`'s rows straight off the
+  # declared IR, the exact way it already reads the core's own — and
+  # dispatches them through the CORE's `Bluebook::Syntax.Keyword`/
+  # `.Argument` verbs, which is why these rows need no entity, no
+  # lifecycle, no creating command of their own here: the verb they ride
+  # already exists, and a second copy of it would be the core's own
+  # machinery duplicated for no reason.
+  aggregate "Syntax" do
+    description "The rows this sub-language contributes to the core's own grammar table."
+    identified_by PagingSyntaxName, as: :name
+
+
+    value_object "PagingSyntaxName" do
+      attribute :value, String
+      invariant("a syntax table is named") { !value.to_s.empty? }
+    end
+
+    # THE SAME EIGHT ROWS syntax.bluebook held directly until now — moved,
+    # not rewritten. `limit`/`offset`/`cursor`/`nulls`, on both `Query`
+    # and `ReadModel`. See syntax.bluebook's own comment at the old site
+    # for why `limit` fills a dedicated field while the other three land
+    # on the open `options` map.
+    value_object "KeywordSeed" do
+      attribute :word,    String
+      attribute :context, String
+      attribute :body,    String
+      attribute :inner,   String
+      attribute :opens,   String
+      attribute :fills,   String
+      attribute :was,     String, optional: true
+
+      member word: "limit",  context: "Query", body: "none", inner: "", opens: "", fills: "limit", calls: "limit_impl"
+      member word: "offset", context: "Query", body: "none", inner: "", opens: "", fills: "options", calls: "offset_impl"
+      member word: "cursor", context: "Query", body: "none", inner: "", opens: "", fills: "options"
+      member word: "nulls",  context: "Query", body: "none", inner: "", opens: "", fills: "options"
+
+      member word: "limit",  context: "ReadModel", body: "none", inner: "", opens: "", fills: "options", calls: "limit_impl"
+      member word: "offset", context: "ReadModel", body: "none", inner: "", opens: "", fills: "options", calls: "offset_impl"
+      member word: "cursor", context: "ReadModel", body: "none", inner: "", opens: "", fills: "options"
+      member word: "nulls",  context: "ReadModel", body: "none", inner: "", opens: "", fills: "options"
+    end
+
+    value_object "ArgumentSeed" do
+      attribute :keyword,           String
+      attribute :context,           String
+      attribute :at,                String, optional: true
+      attribute :named,             String, optional: true
+      attribute :kind,               String
+      attribute :required,           String
+      attribute :fills,              String, optional: true
+      attribute :selects,            String, optional: true
+      attribute :pair_key_fills,     String, optional: true
+      attribute :pair_value_fills,   String, optional: true
+      attribute :pairs_shape,        String, optional: true
+      attribute :variadic,           String, optional: true
+
+      member keyword: "limit",  context: "Query", at: "1", named: "", kind: "number", required: "true", fills: "limit"
+      member keyword: "offset", context: "Query", at: "1", named: "", kind: "number", required: "true", fills: "value"
+      member keyword: "cursor", context: "Query", at: "1", named: "", kind: "symbol", required: "true", fills: "value"
+      member keyword: "nulls",  context: "Query", at: "1", named: "", kind: "symbol", required: "true", fills: "mode"
+
+      member keyword: "limit",  context: "ReadModel", at: "1", named: "", kind: "number", required: "true", fills: "value"
+      member keyword: "offset", context: "ReadModel", at: "1", named: "", kind: "number", required: "true", fills: "value"
+      member keyword: "cursor", context: "ReadModel", at: "1", named: "", kind: "symbol", required: "true", fills: "value"
+      member keyword: "nulls",  context: "ReadModel", at: "1", named: "", kind: "symbol", required: "true", fills: "mode"
+    end
+  end
+end