hecks 0.3.0 → 1.0.1

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

@@ -146,7 +146,7 @@ Hecks.bluebook "Bluebook" do
       sets :description
       sets :provenance
       sets :position
-      emits "RootDeclared"
+      emits RootDeclared
     end
 
     # ONE PART OF THE IDENTITY, attached the way one attribute is. It was an
@@ -182,7 +182,7 @@ Hecks.bluebook "Bluebook" do
       given("an identity part names something") { !path.value.to_s.empty? }
 
       sets :identified_by, append: { value: :path }
-      emits "RootIdentified"
+      emits RootIdentified
     end
 
     # The way back, one level down: the aggregates DECLARED IN a chapter, found by
@@ -238,7 +238,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :attributes, append: { name: :name, type: :type, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
 
-      emits "AttributeAttached"
+      emits AttributeAttached
     end
 
     # An attribute that points at ANOTHER aggregate's head.
@@ -276,7 +276,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :attributes, append: { name: :name, type: :points_at, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
 
-      emits "ReferenceAttached"
+      emits ReferenceAttached
     end
 
     # An attribute whose type names a PIECE this aggregate holds.
@@ -303,7 +303,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :attributes, append: { name: :name, type: :holds, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
 
-      emits "PieceHeld"
+      emits PieceHeld
     end
 
     # THE ONLY RULE THAT CAN REFUSE AN UNNAMED ATTRIBUTE, and it lives here.
@@ -357,7 +357,7 @@ Hecks.bluebook "Bluebook" do
       sets :state_field
       sets :state_start
 
-      emits "LifecycleNamed"
+      emits LifecycleNamed
     end
 
     command "Transition" do
@@ -370,7 +370,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :transitions, append: { command: :command, from_state: :from_state, to_state: :to_state }
 
-      emits "TransitionAttached"
+      emits TransitionAttached
     end
 
     command "Seal" do
@@ -410,7 +410,7 @@ Hecks.bluebook "Bluebook" do
       # 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"
+      emits RootSealed
     end
 
     command "Value" do
@@ -421,7 +421,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :value_objects, append: { name: :name }
 
-      emits "ValueDeclared"
+      emits ValueDeclared
     end
 
     # THE AGGREGATE BOUNDARY (S10, ADR 0025 — "Rules") — the same shape
@@ -438,7 +438,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :invariants, append: { description: :description, canonical: :canonical }
 
-      emits "InvariantAttached"
+      emits InvariantAttached
     end
 
     # A PRECONDITION SHARED ACROSS COMMANDS, DECLARED ONCE (S10, ADR
@@ -456,7 +456,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :preconditions, append: { description: :description, canonical: :canonical }
 
-      emits "PreconditionAttached"
+      emits PreconditionAttached
     end
 
     # THE LOCAL HALF OF A CROSS-AGGREGATE READ (S12, ADR 0025) — the
@@ -478,7 +478,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :projected_fields, append: { name: :name, reference: :reference, remote_field: :remote_field }
 
-      emits "ProjectedFieldAttached"
+      emits ProjectedFieldAttached
     end
 
     # HOW AGGREGATE IS SPELLED. These rows live with the concept

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

@@ -136,7 +136,7 @@ Hecks.bluebook "Bluebook", version: "1" do
       sets :version
       sets :formerly_known_as
 
-      emits "ChapterDeclared"
+      emits ChapterDeclared
     end
 
     # ONE CONTEXT THE CHAPTER ATTACHES TO, appended the way one identity
@@ -156,7 +156,7 @@ Hecks.bluebook "Bluebook", version: "1" do
       # ledger entry was posted") { ledger.size == old.ledger.size + 1
       # } — one more row than before, never fewer, never the same.
       ensures("the list grew by exactly one") { attaches_to.size == old.attaches_to.size + 1 }
-      emits "ChapterAttached"
+      emits ChapterAttached
     end
 
     # THE WAY BACK.
@@ -192,7 +192,7 @@ Hecks.bluebook "Bluebook", version: "1" do
         replacement: :replacement, boundary: :boundary, position: :position
       }
 
-      emits "NormalisationAttached"
+      emits NormalisationAttached
     end
 
     # HOW BLUEBOOK IS SPELLED. These rows live with the concept

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

@@ -161,7 +161,7 @@ Hecks.bluebook "Bluebook" do
       sets :provenance
       sets :from
       sets :position
-      emits "VerbDeclared"
+      emits VerbDeclared
     end
 
     command "Argument" do
@@ -190,7 +190,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :attributes, append: { name: :name, type: :type, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
 
-      emits "ArgumentAttached"
+      emits ArgumentAttached
     end
 
     # An argument that points at ANOTHER aggregate's head — the same word
@@ -223,7 +223,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :attributes, append: { name: :name, type: :points_at, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
 
-      emits "ArgumentReferenceAttached"
+      emits ArgumentReferenceAttached
     end
 
     value_object "ArgName" do
@@ -248,7 +248,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :givens, append: { description: :description, canonical: :canonical }
 
-      emits "RuleAttached"
+      emits RuleAttached
     end
 
     command "Ensure" do
@@ -263,7 +263,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :ensures, append: { description: :description, canonical: :canonical }
 
-      emits "EnsureAttached"
+      emits EnsureAttached
     end
 
     value_object "RuleText" do
@@ -289,7 +289,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :mutations, append: { target: :target, op: :op, field: :field, kind: :kind, source: :source }
 
-      emits "ChangeAttached"
+      emits ChangeAttached
     end
 
     value_object "FieldRef" do
@@ -319,7 +319,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :references, to: :root
 
-      emits "ReferenceNamed"
+      emits ReferenceNamed
     end
 
     command "Announce" do
@@ -332,7 +332,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :emits, append: { name: :announces }
 
-      emits "AnnouncementNamed"
+      emits AnnouncementNamed
     end
 
     # HOW COMMAND IS SPELLED. These rows live with the concept
@@ -375,6 +375,19 @@ Hecks.bluebook "Bluebook" do
       member word: "state",           context: "Command", body: "none",   inner: "", opens: "", fills: "mutations"
       member word: "attribute",       context: "Command", body: "none",   inner: "", opens: "", fills: "attributes", calls: "attribute_impl"
       member word: "ensures", context: "Command", body: "source", inner: "", opens: "", fills: "ensures"
+      # RETROACTIVE CORRECTION — a command that amends a specific past
+      # event rather than acting fresh (see this domain's own ADR on why:
+      # sagas only compensate their OWN anticipated failures, eras only
+      # reinterpret stored shape, and the event log stays append-only —
+      # so nothing existing lets a command say "this is amending a fact
+      # we already announced, and here is why"). STORED AS A MUTATION,
+      # not a new Command field — the same reasoning `delegates_to`'s own
+      # comment gives in full: `mutations:` is ALREADY a fully round-
+      # tripped part of the self-hosted meta-domain's own contract, and a
+      # genuinely new top-level Command field is not. `corrects` rides the
+      # SAME multi-binding wire shape `append`/`delegate` already use
+      # (CommandBuilder#corrects_impl's own comment has the rest).
+      member word: "corrects",        context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", calls: "corrects_impl"
 
     end
 
@@ -422,6 +435,15 @@ Hecks.bluebook "Bluebook" do
       member keyword: "then_set",        context: "Command", at: "",  named: "remove",     kind: "literal",  required: "false", fills: "source", selects: "op=remove"
       member keyword: "delegates_to",    context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "target"
       member keyword: "delegates_to",    context: "Command", at: "",  named: "with",      kind: "literal",  required: "false", fills: "source", selects: "op=delegate"
+      # BARE CONSTANT ACCEPTED (ADR 0025, S6 — "events first-class"),
+      # `emits Account::AccountFrozen`, same `kind: "constant"` +
+      # `kind: "text"` pair `on`'s own row in `policy.bluebook` carries
+      # — both stay admitted, the old spelling not refused, for the
+      # same reason (event names aren't 100% corpus-migrated the way
+      # command references are). `CommandBuilder#emits` (hand-written,
+      # no `calls:` needed — the single-fill path already invokes it by
+      # its own word name) resolves either shape via `Naming.event_ref`.
+      member keyword: "emits",           context: "Command", at: "1", named: "",          kind: "constant", required: "true",  fills: "emits"
       member keyword: "emits",           context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "emits"
       member keyword: "state",           context: "Command", at: "1", named: "",          kind: "symbol",   required: "true",  fills: "source"
       member keyword: "attribute",       context: "Command", at: "1", named: "",          kind: "symbol",   required: "true",  fills: "name"
@@ -431,6 +453,18 @@ Hecks.bluebook "Bluebook" do
       member keyword: "attribute",       context: "Command", at: "",  named: "pattern",   kind: "text",     required: "false", fills: "pattern"
       member keyword: "attribute",       context: "Command", at: "",  named: "admits",    kind: "text",     required: "false", fills: "admits"
       member keyword: "attribute",       context: "Command", at: "",  named: "one_of",    kind: "list",     required: "false", fills: "one_of"
+      # `corrects` — see the KeywordSeed row's own comment. `event` is the
+      # only positional and the only required-by-the-grammar argument;
+      # `reason` is required IN PRACTICE (CommandBuilder#corrects_impl
+      # refuses its absence by hand, the same way `sets` refuses two ops
+      # at once — a fact about runtime state, not a pure per-row fill, so
+      # it stays hand-enforced rather than declared `required: "true"`
+      # here, which would only gate the row's OWN presence, not a sibling
+      # kwarg's).
+      member keyword: "corrects",        context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "target"
+      member keyword: "corrects",        context: "Command", at: "",  named: "as",        kind: "symbol",   required: "false", fills: "source"
+      member keyword: "corrects",        context: "Command", at: "",  named: "reason",    kind: "text",     required: "false", fills: "source"
+      member keyword: "corrects",        context: "Command", at: "",  named: "reverses",  kind: "flag",     required: "false", fills: "source"
 
     end
   end

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

@@ -107,7 +107,7 @@ Hecks.bluebook "Bluebook" do
       sets :name
       sets :description
       sets :position
-      emits "PieceDeclared"
+      emits PieceDeclared
     end
 
     # ONE PART OF THE PIECE'S IDENTITY, attached exactly as an aggregate's is.
@@ -134,7 +134,7 @@ Hecks.bluebook "Bluebook" do
       given("an identity part names something") { !path.value.to_s.empty? }
 
       sets :identified_by, append: { value: :path }
-      emits "PieceIdentified"
+      emits PieceIdentified
     end
 
     command "Seal" do
@@ -146,15 +146,23 @@ Hecks.bluebook "Bluebook" do
 
       given("an entity says what it is known by") { !identified_by.empty? }
 
-      emits "PieceSealed"
+      emits PieceSealed
     end
 
     command "Attribute" do
       role "Language"
       goal "Attach one attribute to the entity"
 
+      # THE TYPE IS A REFERENCE TO THE VALUE OBJECT IT NAMES — the same rule
+      # Aggregate.Attribute enforces one construct over (see that command's own
+      # comment). An entity declares no value objects of its own (Entity never
+      # answers `value_object` — entity.rb's own comment says why); its
+      # attributes read the SAME pool its enclosing aggregate declares, so this
+      # still resolves as a reference, not free text. An entity attribute naming
+      # an undeclared value object failed to fail: `type` rode as plain text, so
+      # reference resolution never ran and a typo'd or invented type boots clean.
+      reference_to ValueObject, as: :type
       attribute :name,    EntityText
-      attribute :type,    EntityText
       attribute :list,    EntityText
       attribute :optional, EntityText, optional: true
       attribute :pattern,  EntityText, optional: true
@@ -164,7 +172,66 @@ Hecks.bluebook "Bluebook" do
 
       sets :attributes, append: { name: :name, type: :type, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
 
-      emits "PieceAttributeAttached"
+      emits PieceAttributeAttached
+    end
+
+    # An attribute that points at ANOTHER AGGREGATE'S HEAD — the SAME
+    # construct Aggregate.Reference is, one level down (see that
+    # command's own comment for why the type cannot be text): `belongs_to`/
+    # `has_one`/`has_many`/`reference_to` are declared on an entity by the
+    # same DSL (`EntityBuilder`/`AttributeCollector`) an aggregate uses,
+    # and a real fixture already exercises it (`spec/relationship_
+    # declaration_spec.rb`'s "uses the same relationship declarations on
+    # an entity", `docs/reference/entity.md`). Without this verb such an
+    # attribute fell to the SAME `Attribute` verb above, which reads
+    # `type` as a value-object reference — so a cross-aggregate reference
+    # declared on a piece failed reference resolution against the wrong
+    # pool the moment entity attributes started being checked at all.
+    command "Reference" do
+      role "Language"
+      goal "Attach an attribute that points at another aggregate's head"
+
+      reference_to Aggregate, as: :points_at
+      attribute :name,    EntityText
+      attribute :list,    EntityText
+      attribute :optional, EntityText, optional: true
+      attribute :pattern,  EntityText, optional: true
+      attribute :default, EntityText, optional: true
+      attribute :admits,  EntityText, optional: true
+      attribute :relationship, EntityText, optional: true
+
+      sets :attributes, append: { name: :name, type: :points_at, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits PieceReferenceAttached
+    end
+
+    # An attribute whose type names a PIECE NESTED INSIDE THIS ONE — the
+    # SAME construct Aggregate.Holds is, one level down (see that
+    # command's own comment): `attribute :dispatches, list_of(Dispatch)`
+    # inside `entity "Handler"` (S17, ADR 0026's own two-level chain) is
+    # exactly `Account#ledger` one level further in. Without this verb
+    # such an attribute fell to the SAME `Attribute` verb above, which
+    # reads `type` as a value-object reference — so a piece nested inside
+    # a piece failed reference resolution against the wrong pool the
+    # moment entity attributes started being checked at all (found live:
+    # the meta-grammar's own `Handler.dispatches` naming `Dispatch`,
+    # nested inside Handler itself).
+    command "Holds" do
+      role "Language"
+      goal "Attach an attribute whose type is a piece nested inside this one"
+
+      reference_to Entity, as: :holds
+      attribute :name,    EntityText
+      attribute :list,    EntityText
+      attribute :optional, EntityText, optional: true
+      attribute :pattern,  EntityText, optional: true
+      attribute :default, EntityText, optional: true
+      attribute :admits,  EntityText, optional: true
+      attribute :relationship, EntityText, optional: true
+
+      sets :attributes, append: { name: :name, type: :holds, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits PieceHeld
     end
 
 
@@ -184,7 +251,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :preconditions, append: { description: :description, canonical: :canonical }
 
-      emits "PiecePreconditionAttached"
+      emits PiecePreconditionAttached
     end
 
     # A PIECE'S OWN SHAPE RULE, DECLARED ONCE (round 7) — see
@@ -203,7 +270,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :invariants, append: { description: :description, canonical: :canonical }
 
-      emits "PieceInvariantAttached"
+      emits PieceInvariantAttached
     end
 
     command "Lifecycle" do
@@ -214,7 +281,7 @@ Hecks.bluebook "Bluebook" do
       sets :state_field
       sets :state_start
 
-      emits "PieceLifecycleNamed"
+      emits PieceLifecycleNamed
     end
 
     command "Transition" do
@@ -227,7 +294,7 @@ Hecks.bluebook "Bluebook" do
 
       sets :transitions, append: { command: :command, from_state: :from_state, to_state: :to_state }
 
-      emits "PieceTransitionAttached"
+      emits PieceTransitionAttached
     end
 
     # HOW ENTITY IS SPELLED. These rows live with the concept
@@ -248,7 +315,7 @@ Hecks.bluebook "Bluebook" do
       member word: "description",     context: "Entity", body: "none",     inner: "",           opens: "",         fills: "description"
       member word: "identified_by",   context: "Entity", body: "keywords", inner: "ValueObject", opens: "ValueObject", fills: "identified_by", calls: "identified_by_impl"
       member word: "identified_by",   context: "Entity", body: "none",     inner: "",           opens: "",         fills: "identified_by", calls: "identified_by_impl"
-      member word: "given",           context: "Entity", body: "source",   inner: "",           opens: "",         fills: "preconditions", calls: "given_impl"
+      member word: "given",           context: "Entity", body: "source",   inner: "",           opens: "",         fills: "preconditions", resolves_via: "owner_keyed", disambiguator: "declared_by", calls: "given_impl"
       member word: "invariant",       context: "Entity", body: "source",   inner: "",           opens: "",         fills: "invariants", calls: "invariant_impl"
       member word: "command",         context: "Entity", body: "keywords", inner: "Command",    opens: "Command",  fills: "", calls: "command_impl"
       member word: "query",           context: "Entity", body: "keywords", inner: "Query",      opens: "Query",    fills: "", calls: "query_impl"
@@ -282,6 +349,15 @@ Hecks.bluebook "Bluebook" do
 
       member keyword: "description",     context: "Entity", at: "1", named: "",         kind: "text",     required: "true",  fills: "description", coerce: "false"
       member keyword: "given",           context: "Entity", at: "1", named: "",         kind: "text",     required: "true",  fills: "description"
+      # PLAIN TEXT, not `kind: "constant"` — unlike `Aggregate`'s own
+      # `declared_by:` (which names a real aggregate constant), a piece
+      # has no first-class, independently-addressable reference anywhere
+      # in this language. "AggregateName.EntityName" ships as a string,
+      # the same way `admits:` shipped textual before its own
+      # constant-bridge existed — see `EntityBuilder#given_impl`'s own
+      # comment for why this is a deliberate, not temporary-by-oversight,
+      # divergence.
+      member keyword: "given",           context: "Entity", at: "",  named: "declared_by", kind: "text",     required: "false", fills: "declared_by"
       member keyword: "invariant",       context: "Entity", at: "1", named: "",         kind: "text",     required: "true",  fills: "description"
       member keyword: "identified_by",   context: "Entity", at: "1", named: "",         kind: "symbol",   required: "false", fills: "identified_by", variadic: "true", minimum: "2"
       member keyword: "identified_by",   context: "Entity", at: "1", named: "",         kind: "constant", required: "false", fills: "type"

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

@@ -105,7 +105,7 @@ Hecks.bluebook "Bluebook" do
       sets :where
       sets :for_each
       sets :position
-      emits "ReactionDeclared"
+      emits ReactionDeclared
     end
 
     command "Bind" do
@@ -117,12 +117,28 @@ Hecks.bluebook "Bluebook" do
 
       sets :with_spec, append: { key: :key, value: :value }
 
-      emits "TriggerBindingAttached"
+      emits TriggerBindingAttached
     end
 
     # HOW POLICY IS SPELLED. These rows live with the concept
     # they describe; SyntaxBoot discovers every aggregate-local seed table.
     # Contexts represented here: Policy.
+    #
+    # `on`'s ArgumentSeed gained a `kind: "constant"` row alongside its
+    # existing `kind: "text"` one (ADR 0025, S6 — "events first-class"),
+    # same shape `trigger`'s own pair already carries — `on
+    # Account::AccountFrozen`, a bare constant, now parses the same way
+    # `trigger Account::Debit` does. `calls: "on_impl"` routes the word
+    # through a hand-written method (`PolicyBuilder#on_impl`) instead of
+    # the generic single-fill coercion, mirroring `trigger`'s own
+    # `calls: "trigger_impl"` on the row below. UNLIKE `trigger`,
+    # `on_impl` does NOT refuse the quoted-text form outside
+    # `shadow_parse` — command references were safe to refuse that way
+    # only because they're 100% migrated across the live corpus; event
+    # names (`emits`/`on`) are not (only Account's `AccountFrozen` is,
+    # this pass), so refusing the old spelling here would break every
+    # live `.bluebook` site this pass didn't touch. Both forms stay
+    # admitted until a full corpus migration lands.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"
@@ -135,7 +151,7 @@ Hecks.bluebook "Bluebook" do
       attribute :resolves_via,  String, default: "", admits: "Syntax::ResolutionScope"
       attribute :disambiguator, String, default: "", admits: "Syntax::Disambiguator"
 
-      member word: "on",              context: "Policy",    body: "none", inner: "", opens: "",       fills: "on_event"
+      member word: "on",              context: "Policy",    body: "none", inner: "", opens: "",       fills: "on_event", calls: "on_impl"
       member word: "trigger",         context: "Policy",    body: "none", inner: "", opens: "",       fills: "trigger_command", calls: "trigger_impl"
       member word: "across",          context: "Policy",    body: "none", inner: "", opens: "",       fills: "target_domain"
       member word: "where",           context: "Policy",    body: "source", inner: "", opens: "", fills: "where"
@@ -160,7 +176,8 @@ Hecks.bluebook "Bluebook" do
       attribute :coerce,           String
       attribute :blank_message,    String
 
-      member keyword: "on",              context: "Policy", at: "1", named: "", kind: "text", required: "true", fills: "on_event"
+      member keyword: "on",              context: "Policy", at: "1", named: "", kind: "constant", required: "true", fills: "on_event"
+      member keyword: "on",              context: "Policy", at: "1", named: "", kind: "text",     required: "true", fills: "on_event"
       member keyword: "trigger",         context: "Policy", at: "1", named: "", kind: "constant", required: "true", fills: "trigger_command"
       member keyword: "trigger",         context: "Policy", at: "1", named: "", kind: "text",     required: "true", fills: "trigger_command"
       member keyword: "across",          context: "Policy", at: "1", named: "", kind: "text", required: "true", fills: "target_domain"