hecks 2.8.0 → 2.9.0

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

@@ -1,67 +1,18 @@
 Hecks.bluebook "Bluebook" do
   aggregate "Syntax" do
-    # HOW A BLUEBOOK IS SPELLED — the layer the language did not have.
+    # How a bluebook is spelled: every word, the body it opens and the field it fills.
+    # Declarations only, so there are no commands; spec/syntax_conformance_spec reads it.
     #
-    # Every other file in this directory declares SHAPE. `Aggregate` has an
-    # `identified_by` that is a `list_of(IdentityPath)` ; `Field` has a name, a
-    # type and a cardinality. Nothing anywhere said that the field is SPELLED
-    # `identified_by`, that a block opens with `do`, or that a symbol argument
-    # starts with `:`. Grep this directory for keyword, token or syntax before
-    # this file existed and the only hit was a comment.
-    #
-    # That gap is why the parser could not be projected, and it is also where the
-    # bugs were. When `identified_by` became `list_of(IdentityPath)` the projected
-    # struct regenerated to a list of strings with nobody touching it, and was
-    # correct. The HAND-WRITTEN halves broke : a hand-written parser could not read
-    # `identified_by do` at all and swallowed whole aggregate bodies in silence,
-    # and a dispatcher that read the field as a scalar got nothing on an array
-    # and fell through to a minted `"id"`. The declared half survived. The
-    # undeclared halves did not.
-    #
-    # DECLARATIONS, NOT RUNTIME STATE — the same reading as Vocabulary beside it,
-    # and no commands for the same reason. A domain does not declare its own
-    # syntax ; the syntax is fixed when the language is defined. Nothing
-    # dispatches this, `Plan` skips it by construction (a category with nothing
-    # to offer contributes nothing), and `spec/syntax_conformance_spec` READS it
-    # from the IR and holds each builder to it in both directions.
-    #
-    # WHY THE KEYWORD BELONGS TO THE CATEGORY AND NOT TO A RECORD. The word
-    # `aggregate` is a fact about the Aggregate CATEGORY, not about
-    # `Pizzas::Pizza` — and the meta-domain's records are instances. So there is
-    # nothing for a dispatched syntax to hang off, and this is a closed set.
-    #
-    # WHAT IS NOT HERE. Only the `.bluebook` surface. `.port`, `.adapter`,
-    # `.hecksagon`, `.world` and `translations/*.bluebook` are SIBLING artifacts
-    # with their own builders and their own files ; a parser projected from this
-    # reads bluebooks, and half-covering the siblings would say less than naming
-    # the exclusion does.
-    #
-    # THIS IS ALSO WHY THE GENERIC-BLUEBOOK-READER ARC STOPS HERE.
-    # A generic reader driven by THIS table
-    # covers every keyword whose argument-binding this table can
-    # express (M1-M7), down to `member`'s and `sets`' pairs, which turned out
-    # to need a schema correction rather than new machinery. What stays
-    # outside the table either isn't ONE shape a bigger table
-    # would close (`attribute`, three separate irregularities) or isn't
-    # covered by this table AT ALL : `.hecksagon`/`.world`'s open adapter-verb
-    # vocabulary is the one truly PERMANENT exclusion, for the same reason
-    # named above — a verb's schema is not even contained in the file being
-    # parsed, registered instead by host application code
-    # (`Hecks.port("post") { verb "posted_by" }`), so no table this file
-    # could hold would ever be enough.
+    # Covers the `.bluebook` surface only; `.hecksagon` and `.world` adapter verbs are
+    # registered by host code, so no table here could hold them.
     description "How a bluebook is SPELLED — every word the surface admits, the body it may open, and the field it fills. The layer every other file in this directory does not have."
 
     belongs_to Bluebook
 
-    # ITS NAME, and nothing else — a syntax hangs under no other thing, exactly
-    # as a vocabulary does.
+    # Identified by name alone; a syntax hangs under no other thing.
     identified_by SyntaxName, as: :name
 
-    # S14, ADR 0026 — Keyword/Argument nested here (see `entity
-    # "Keyword"`/`entity "Argument"`, below), entities rather than
-    # closed-set value-object members. `list_of(...)` forward-references
-    # them the same way banking's own `attribute :ledger,
-    # list_of(LedgerEntry)` names LedgerEntry before it is declared.
+    # Keyword and Argument are nested entities, forward-referenced by `list_of`.
     attribute :keywords,  list_of(Keyword)
     attribute :arguments, list_of(Argument)
 
@@ -70,19 +21,9 @@ Hecks.bluebook "Bluebook" do
       invariant("a syntax is named") { !value.to_s.empty? }
     end
 
-    # WHERE A WORD MAY BE TYPED. Mostly a category, but not always : `OneOf`,
-    # `Lifecycle` and `Type` are bodies with no category of their own, and `File`
-    # is the outside of every body. A context is not the same question as a
-    # category, which is why this is its own set rather than a list of the
-    # thirteen.
-    #
-    # `Lifecycle` is a DECLARED FOLD — contracts.rb folds state_field,
-    # state_start and transitions onto whichever of Aggregate or Entity opened
-    # it — so a word typed there fills a field of the ENCLOSING category, not of
-    # a Lifecycle that does not exist.
-    #
-    # `Type` is the second argument of `attribute`, which is a place words are
-    # spelled (`list_of`, `one_of`) and so is a context like any other.
+    # Where a word may be typed. Not always a category: `OneOf`, `Lifecycle` and `Type`
+    # are bodies without one, and `File` is the outside of every body.
+    # A word in `Lifecycle` fills a field of the enclosing Aggregate or Entity.
     value_object "Context" do
       attribute :name, String,
                 one_of: ["File", "Bluebook", "Aggregate", "Entity", "Command", "Query", "ValueObject", "OneOf",
@@ -91,142 +32,58 @@ Hecks.bluebook "Bluebook" do
                          "TranslationAggregate"]
     end
 
-    # WHAT A WORD'S BLOCK IS, and the three answers are genuinely different
-    # things to a parser :
-    #
-    #   keywords  a nested body of more words — `aggregate "X" do … end`
-    #   source    a block that is NEVER CALLED. Its text is the declaration —
-    #             `given("…") { balance >= amount }`, `identified_by :name`.
-    #             Recovered through Ports::Extraction, which is why `number.value`
-    #             needs no method called `number` to exist.
-    #   rows      a body of `member` rows and nothing else — `one_of do … end`
-    #   none      no block at all
-    #
-    # A `source` body IS the thing the word declares : `given`'s body is the
-    # rule's canonical text, `identified_by`'s body is the identity paths. A
-    # `keywords` or `rows` body fills the record the word opens.
+    # What a word's block is:
+    #   keywords  nested words, `aggregate "X" do … end`
+    #   source    never called; its text is the declaration, `given("…") { … }`
+    #   rows      `member` rows only, `one_of do … end`
+    #   none      no block
     value_object "Body" do
       attribute :name, String, one_of: ["none", "keywords", "source", "rows"]
     end
 
-    # WHERE A WORD STANDS IN ITS OWN LIFE. The same shape the expression
-    # grammar's Operator carries (proposed → admitted → retired), plus
-    # `deprecated` — a word still read but on its way out, which an operator
-    # never needed because nothing outside this repo writes expressions yet.
-    # A row DEFAULTS to admitted, so the table below stays a table of words
-    # rather than a table of words-with-ceremony; only a word entering or
-    # leaving the language spells its status. The projections read this:
-    # a proposed or retired word reaches no generated parser table, so to
-    # every projected reader it simply does not exist — the operator rule,
-    # at the syntax layer.
+    # Where a word stands in its life. A row defaults to admitted; a proposed or retired
+    # word reaches no generated parser table.
     value_object "Status" do
       attribute :name, String, one_of: ["proposed", "admitted", "deprecated", "retired"]
     end
 
-    # WHICH OF THE THREE SHARED RESOLUTION PRIMITIVES (Hecks::
-    # Bluebook::DSL::RuleReference — a "declared once, referenced by
-    # name" family word's own bare form resolves through, once it has
-    # one: `hash_chain` (an ordered chain of flat pools, first match
-    # wins — `given` on Command), `owner_keyed` (one pool keyed by
-    # declaring owner, needing `disambiguator` below to pick among more
-    # than one candidate — `given` on Aggregate), `sibling_scan` (a
-    # live scan over already-built sibling objects, no separate pool at
-    # all — `invariant` on ValueObject). BLANK for every OTHER word —
-    # most of the language declares once and is never referenced back,
-    # so `Keyword#resolves_via` stays optional rather than forcing every
-    # existing row to spell "none."
+    # Which shared resolution primitive (Hecks::Bluebook::DSL::RuleReference) a word's bare
+    # form resolves through: an ordered chain of pools, one pool keyed by owner, or a scan
+    # of sibling objects. Blank for words that are never referenced back.
     value_object "ResolutionScope" do
       attribute :name, String, one_of: ["hash_chain", "owner_keyed", "sibling_scan"]
     end
 
-    # WHICH DISAMBIGUATOR KEYWORD a bare reference may supply when its
-    # own `resolves_via` is `owner_keyed` and more than one candidate is
-    # registered — `declared_by:` is the only one that exists today
-    # (`AggregateBuilder#given`'s own chapter-wide sharing,
-    # docs/implemented/resolution-rules/chapter-given.md). A closed set of one,
-    # deliberately, not a boolean flag — the SAME reason `Body`/`Status`
-    # above are closed sets rather than booleans even where today's
-    # count is small: a second disambiguator kind, if this family ever
-    # grows one, is a new MEMBER of this set, not a second attribute.
+    # The keyword a bare reference may supply to pick among `owner_keyed` candidates.
+    # A closed set rather than a flag, so a second kind is a new member.
     value_object "Disambiguator" do
       attribute :name, String, one_of: ["declared_by"]
     end
 
-    # WHAT AN ARGUMENT LOOKS LIKE WHEN IT IS TYPED. Lexical, not semantic — two
-    # arguments of the same kind are read the same way and mean whatever the
-    # field they fill means.
-    #
-    # `literal` is the widest : a default is written so its TYPE survives — `0`
-    # rather than `"0"`, `0.0` rather than `"0.0"` — which is what LiteralText is
-    # about, and why it is not `text`.
+    # What an argument looks like when typed; lexical, not semantic.
+    # `literal` keeps its type (`0` rather than `"0"`), which is why it is not `text`.
     value_object "ArgumentKind" do
       attribute :name, String,
                 one_of: ["text", "symbol", "number", "flag", "literal", "constant", "pairs", "list"]
     end
 
-    # WHAT A `pairs` ARGUMENT'S OWN PAIR(S) DO. Found by tracing every real
-    # `pairs` reader (parse_where_line, parse_pm_handler, parse_lifecycle,
-    # parse_with_hash, `one_of`'s member builder, `sets`' append: builder) —
-    # four genuinely different shapes were hiding under one `kind`:
-    #
-    #   fields    ONE pair, contributing two NAMED SUB-FIELDS to the single
-    #             compound this keyword invocation is already building — the
-    #             same role a positional argument plays, just sourced from a
-    #             pair instead of a bare token. `on`'s `transition:` sets
-    #             `from_state`/`to_state` on the ProcessManagerHandler its
-    #             OWN `event_type` argument is also filling ; Lifecycle's
-    #             `transition` sets `command`/`to_state` on the Transition
-    #             its own `from:` argument also fills.
-    #   elements  EACH pair independently becomes a NEW compound, appended to
-    #             the keyword's own list field (`where`'s own `fills:
-    #             "wheres"`, declared at the Keyword level, same as
-    #             `attribute`'s). `where(balance: {gte: 100}, status: "open")`
-    #             is two WhereClauses from one line, not one.
-    #   verbatim  each pair is captured as-is, key and value both left as
-    #             text — `dispatch`'s `with:` : resolution (`:name` reference
-    #             vs literal) happens at DISPATCH time, not parse time, so
-    #             there is nothing to interpret here at all.
-    #   sibling   the pair's KEY names a field of an ALREADY-DECLARED sibling
-    #             construct — `member`'s keys are the enclosing value
-    #             object's own attributes ; `sets`' `append:` keys are the
-    #             target entity/value-object's own attributes. Not a static
-    #             fact this table can enumerate (the valid keys differ per
-    #             domain) — named here so a reader knows to resolve
-    #             dynamically rather than assume an omission.
+    # What a `pairs` argument's pairs do:
+    #   fields    one pair supplying two named sub-fields of the compound being built
+    #   elements  each pair becomes a new compound appended to the keyword's list field
+    #   verbatim  each pair kept as text; resolved at dispatch time, not parse time
+    #   sibling   the key names a field of an already-declared sibling; resolved dynamically
     value_object "PairsShape" do
       attribute :name, String, one_of: ["fields", "elements", "verbatim", "sibling"]
     end
 
-    # THE SPELLINGS LIVE WITH THEIR DOMAIN CONCEPTS. Each aggregate declares
-    # its own KeywordSeed and ArgumentSeed value objects beside the behavior
-    # those rows describe. SyntaxBoot discovers and combines those local tables
-    # automatically; this aggregate owns only the live Keyword/Argument records
-    # and the genuinely shared lexical vocabulary below.
-
+    # Spelling rows live in each aggregate's own KeywordSeed and ArgumentSeed; SyntaxBoot
+    # combines them. This aggregate owns the live records and the shared vocabulary.
 
-    # S14, ADR 0026 — "`Status` becomes a real `lifecycle` with declared
-    # transitions, so the ordering is enforced by declaration and the
-    # model checker can finally see it" (the ADR's own words). A value
-    # object has no identity, so it cannot transition — it can only be
-    # replaced wholesale (this file's own prior header, before this
-    # slice) — so Keyword and Argument become genuine ENTITIES of
-    # Syntax, each carrying a real `lifecycle :status`.
-    #
-    # THE REAL RECORD, not the source. The aggregate-local `KeywordSeed` rows
-    # are what get WRITTEN — hand-typed grammar data, still the
-    # natural way to spell ~106 static facts. `Keyword` is what gets
-    # READ : `SyntaxBoot` (meta_validator/syntax_boot.rb) dispatches one
-    # `Syntax.Keyword` per seed row, once, at boot, into a REAL "Bluebook"
-    # domain runtime — the same distinction `Reconstruction`/`Judge`
-    # already draw everywhere else between what a chapter DECLARES and
-    # what gets DISPATCHED from it, just run once more, for the
-    # language's own grammar table this time.
+    # Keyword and Argument are entities so each can carry a real `lifecycle :status`.
+    # SyntaxBoot dispatches one `Syntax.Keyword` per seed row at boot.
     #
-    # `identified_by :position` — POSITIONAL, the same reason Member's
-    # own is (S17): a keyword row has no other field guaranteed unique on
-    # its own (the same word is legitimately admitted in more than one
-    # context), and declaration order is a fact about the SOURCE the
-    # language already holds deliberately elsewhere.
+    # Identified by position: the same word is legitimately admitted in more than one
+    # context, so no other field is unique.
     value_object "KeywordPosition" do
       attribute :value, Integer
     end
@@ -243,47 +100,18 @@ Hecks.bluebook "Bluebook" do
       attribute :opens,   KeywordSeedText
       attribute :fills,   KeywordSeedText
       attribute :was,     KeywordSeedText, optional: true
-      # WHICH SHARED PRIMITIVE (Hecks::Bluebook::DSL::
-      # RuleReference) this word's own bare form resolves through, once
-      # it has one — see `ResolutionScope`'s own comment, above, for the
-      # three real values and which existing word declares each.
-      # BLANK for every other word.
+      # The shared primitive this word's bare form resolves through; see `ResolutionScope`.
       attribute :resolves_via,   KeywordSeedText, admits: "Syntax::ResolutionScope", optional: true
-      # WHICH DISAMBIGUATOR keyword argument a bare reference may supply
-      # when `resolves_via` is `owner_keyed` — see `Disambiguator`'s own
-      # comment. BLANK unless `resolves_via` is `owner_keyed` AND more
-      # than one candidate can register (today: `given` on Aggregate,
-      # and `given` on Entity, one level down — chapter-wide sharing at
-      # each scope it has grown to).
+      # Blank unless `resolves_via` is `owner_keyed` and several candidates can register.
       attribute :disambiguator,  KeywordSeedText, admits: "Syntax::Disambiguator", optional: true
-      # THE ESCAPE HATCH — item #13's full metaprogrammed dispatch (slice
-      # 3, whole-project table-unification survey). BLANK for every word
-      # `GenericDispatch` fills/opens/zero-args directly off `fills:`/
-      # `opens:`. NON-EMPTY names a real Ruby method this word's whole
-      # call (args, kwargs, block, untouched) forwards to instead — for
-      # words whose own logic is genuinely too complex to re-derive from
-      # argument shape alone (`attribute`'s own type-quoting/closed-set-
-      # synthesis/pattern validation). The method itself stays exactly
-      # what it always was, hand-written, unchanged — this column only
-      # says WHICH one answers the word, the same way `resolves_via`
-      # already names which shared primitive a bare reference resolves
-      # through, one level up. Read DURING bootstrap too (`WordGate`'s
-      # own `BOOTSTRAP_CALLS_FALLBACK`, a small explicit table naming
-      # the SAME (context, word) -> method pairs this column would say,
-      # since the real table doesn't exist yet at that point) — the one
-      # place in this whole arc a bootstrap fallback was worth building,
-      # because it duplicates NO logic, only a method NAME.
+      # Escape hatch: blank means `GenericDispatch` fills/opens the word directly. Non-empty
+      # names the Ruby method the whole call forwards to, for words too complex to derive
+      # from argument shape. Read during bootstrap via `WordGate`'s BOOTSTRAP_CALLS_FALLBACK.
       attribute :calls, KeywordSeedText, optional: true
 
       lifecycle :status, default: "admitted" do
-        # NOT `proposed` : nothing in the real table is ever declared
-        # proposed today, and the lifecycle's own default has to stay
-        # "admitted" to match every existing row's own implicit status —
-        # changing it would make every one of the ~106 rows silently
-        # start "proposed" instead. Declaring `proposed` as a state
-        # reachable from nowhere would be exactly the kind of decorative,
-        # unused declaration this whole ADR series exists to catch — so
-        # it is left out, honestly, rather than declared and unreachable.
+        # No `proposed` state: no row is declared proposed, and the default must stay
+        # "admitted" to match every existing row.
         transition "Deprecate" => "deprecated", from: "admitted"
         transition "Retire"    => "retired",    from: ["admitted", "deprecated"]
       end
@@ -303,11 +131,7 @@ Hecks.bluebook "Bluebook" do
       end
     end
 
-    # S14, ADR 0026 — same reason Keyword's own is, one construct over.
-    # `identified_by :position` — positional, the SAME field name as
-    # Keyword's own on purpose: an Argument row's identity is never
-    # compared against a Keyword row's, so the shared name costs nothing
-    # and names the same fact both times.
+    # Identified by position, as Keyword is; Argument and Keyword rows are never compared.
     value_object "ArgumentPosition" do
       attribute :value, Integer
     end
@@ -329,42 +153,14 @@ Hecks.bluebook "Bluebook" do
       attribute :pair_value_fills, ArgumentSeedText, optional: true
       attribute :pairs_shape,      ArgumentSeedText, optional: true
       attribute :variadic,         ArgumentSeedText, optional: true
-      # Minimum positional count for a variadic form. `identified_by` uses
-      # two so one symbol can retire without retiring compound keys.
+      # Minimum positional count for a variadic form.
       attribute :minimum,          ArgumentSeedText, optional: true
-      # ABSENT means "apply the uniform, kind-driven coercion" (text ->
-      # .to_s, symbol -> .to_sym) — item #13's full metaprogrammed
-      # dispatch (slice 1, whole-project table-unification survey) reads
-      # this to decide whether a GENERATED fill method may coerce its own
-      # argument before storing it. `"false"` marks the six real
-      # exceptions a full builder-method audit found (read the real Ruby
-      # source, not inferred): `vision`/`description`(x4)/`goal` all
-      # store a `kind: "text"` argument RAW, with no `.to_s` at all —
-      # `.to_s` on an actual String is a same-object no-op for every real
-      # corpus use, but a direct Ruby API call passing something else
-      # (`vision(42)`) would see genuinely different stored behavior, so
-      # this couldn't be assumed uniform across every text-kind row the
-      # way it turned out to genuinely be for every OTHER text-kind
-      # argument in the whole grammar.
+      # Absent means the uniform kind-driven coercion (text -> .to_s, symbol -> .to_sym).
+      # "false" marks the words (`vision`, `description`, `goal`) that store a text argument raw.
       attribute :coerce,           ArgumentSeedText, optional: true
-      # ABSENT means "an empty value is stored same as any other" — item
-      # #13's full metaprogrammed dispatch (slice 2, whole-project
-      # table-unification survey). NON-EMPTY names the exact Malformed
-      # message a real word's own hand-written method raised on a blank
-      # value BEFORE storing it (`Translation#retired`: "a retired needs
-      # an aggregate name"; `TranslationAggregate#drop`: "a drop needs a
-      # name") — `required: "true"` alone only gates Ruby's own ARITY
-      # (an argument omitted entirely), never a present-but-blank one,
-      # so this is a genuinely separate fact the table did not already
-      # carry. Most `required: "true"` rows do NOT raise on blank
-      # (confirmed by reading every one migrated in slice 1 —
-      # `Policy#on`/`ProcessManager#correlates_by`/etc. all accept and
-      # store an empty string same as any other), so this could not be
-      # assumed uniform from `required:` either. Carries the REAL text
-      # rather than a generated one — refusal wording is itself a
-      # checked contract in this codebase (item #2, whole-project
-      # table-unification survey, `RefusalWording::TEMPLATES`), not
-      # throwaway UX text a generic template could safely replace.
+      # Absent means a blank value is stored like any other. Non-empty is the exact Malformed
+      # message raised on a blank value; `required` only gates arity. Refusal wording is a
+      # checked contract (`RefusalWording::TEMPLATES`), so the real text is carried.
       attribute :blank_message,    ArgumentSeedText, optional: true
 
       lifecycle :status, default: "admitted" do
@@ -395,10 +191,7 @@ Hecks.bluebook "Bluebook" do
       attribute :value, String
     end
 
-    # THE SYNTAX RECORD ITSELF. There is only ever one — the language
-    # describes its own single surface, not several — so unlike every
-    # other aggregate's own creating command, this carries no `position`:
-    # there are no siblings to order among.
+    # There is only ever one Syntax record, so this carries no `position`.
     command "Declare" do
       role "Language"
       goal "Open the language's own syntax table"
@@ -412,12 +205,8 @@ Hecks.bluebook "Bluebook" do
       emits SyntaxDeclared
     end
 
-    # THE KEYWORD'S OWN CREATION. An entity is never created through its
-    # own dotted verb (S17's own finding, EntityInterpreter#element_of
-    # only LOCATES) — so, mirroring `ValueObject.Member`/`ProcessManager.
-    # Handler`, this is a bare, aggregate-level append. `position` is
-    # minted by `SyntaxBoot` as the seed row's own index — the same walk-
-    # index convention Member's own `position` already uses.
+    # An entity is never created by its own dotted verb, so this is an aggregate-level append.
+    # `position` is minted by `SyntaxBoot` as the seed row's index.
     command "Keyword" do
       role "Language"
       goal "Admit one word the bluebook surface accepts"