hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,437 @@
+Hecks.bluebook "Bluebook" do
+  aggregate "Command" do
+    description "One command declared on an aggregate — its arguments, its rules, and what it announces."
+
+    reference_to Aggregate
+
+    # WHICH PIECE DECLARED IT, when a piece did. A command argument with no
+    # attribute to land in does not persist — the same lesson `disputed_by` taught
+    # on CardPayment — so the field has to exist here for Command.Declare's
+    # `entity_id` to be held at all.
+    reference_to Entity, as: :entity_id, optional: true
+
+    # SPELLED AS THE IR SPELLS THEM. The judge walks a built IR and offers each
+    # field by name, so a field named differently here would need a translation
+    # table between two vocabularies for the same thing — and a table is a place
+    # to be wrong quietly. One spelling, and the walk reads straight through.
+    # THE IMMEDIATE OWNER, AND ITS NAME. Almost every chapter declares a
+    # `Declare` ; the owner is what tells one from another.
+    #
+    # `owner_id` NOT `aggregate_id` : a command declared on an ENTITY is that
+    # entity's, not its aggregate's — `Banking:Account:LedgerEntry:Amend` is
+    # LedgerEntry's Amend, and `Banking:Account:LedgerEntry` is what tells it
+    # apart from a same-named command on some OTHER entity of the same
+    # aggregate. `aggregate_id` (kept, below, as data) still names the true
+    # root, for the DeclaredIn walk that gathers every command under a
+    # chapter’s aggregate whichever piece declared it ; `owner_id` names only
+    # whichever declared THIS one. `owner_id` is not a declared attribute —
+    # it is the WALK's immediate parent, read the same way `position` is.
+    identified_by :owner_id, :name
+
+    attribute :name,       CommandName
+    attribute :role,       Actor
+    attribute :goal,       Goal
+    attribute :emits,      list_of(Announcement)
+    attribute :references, EventName, optional: true
+    attribute :attributes, list_of(Argument)
+    attribute :givens,     list_of(Rule)
+    # THE POSTCONDITIONS — same Rule shape as givens, checked on the other
+    # side of the mutations: a given says what must hold to begin, an
+    # ensures says what must hold to have finished. Meyer's third leg.
+    attribute :ensures,    list_of(Rule)
+    attribute :mutations,  list_of(Change)
+    attribute :provenance, CommandText
+    # LIFECYCLE STATE AS A COMMAND GUARD (S10, ADR 0025) — a LITERAL,
+    # the same shape `provenance`/`default:` already carry (`from:
+    # "open"` or `from: ["open", "frozen"]`, encoded and decoded the
+    # same way any other Ruby literal on this construct is), not a
+    # dedicated list-of-value-object the way `givens` is — the guard
+    # names no target state and moves nothing, so it needs no Rule-
+    # shaped predicate at all, only the states it admits.
+    attribute :from,       CommandText, optional: true
+
+    value_object "CommandName" do
+      attribute :value, String
+      invariant("a command is named") { !value.to_s.empty? }
+    end
+
+    value_object "Actor" do
+      attribute :value, String
+      # RELAXED for the experiment : banking leaves 19 of 40 commands without a
+      # role, and the hand-written CommandBuilder never required one. Whether
+      # role/goal are mandatory is a language decision — the meta-domain found
+      # the drift the moment it enforced uniformly.
+    end
+
+    value_object "Goal" do
+      attribute :value, String
+      # RELAXED — see Actor above.
+    end
+
+    value_object "EventName" do
+      attribute :value, String
+    end
+
+    value_object "Announcement" do
+      attribute :name, String
+    end
+
+    value_object "Argument" do
+      attribute :name,    String
+      attribute :type,    String
+      attribute :list,    String
+      attribute :optional, String, optional: true
+      attribute :pattern,  String, optional: true
+      attribute :default, String
+      # The closed set this value must belong to — see Aggregate::Field, which is
+      # the same declaration, spelled for a command's arguments.
+      attribute :admits, String, optional: true
+      attribute :relationship, String, optional: true
+    end
+
+    value_object "Rule" do
+      attribute :description, String
+      attribute :canonical,   String
+    end
+
+    value_object "Change" do
+      attribute :target, String
+      # The same word, one aggregate over. `OpName` used to carry
+      # `set || append || increment || decrement` in an invariant — Vocabulary's
+      # MutationOp written out a second time, one level in, with nothing
+      # comparing the two. Naming the set is the whole of what that invariant was
+      # trying to say, and it says it where the set actually lives.
+      attribute :op,     String, admits: "Vocabulary::MutationOp"
+      attribute :field,  String
+      attribute :kind,   String
+      attribute :source, String
+    end
+
+    # A plain string holder, for the id of the aggregate above. Command had no
+    # generic text value object and the alternatives all meant something else —
+    # RuleText is a predicate, FieldRef is a field, ArgType is a type. Reusing one
+    # of those would read as a lie, the way `bluebook_id` typed AggregateName did.
+    value_object "CommandText" do
+      attribute :value, String
+    end
+    # The way back: everything DECLARED IN the aggregate above. The parent
+    # reference IS the query.
+    # 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 :aggregate, CommandText
+      where(aggregate: :aggregate)
+      order_by :position
+    end
+    command "Declare" do
+      role "Language"
+      goal "Open a command on an aggregate"
+
+      reference_to Aggregate
+      # DECLARED ON AN AGGREGATE, or on one of its ENTITIES. The IR uses the same
+      # Command for both — an entity's commands are Command objects — so the
+      # language uses the same Command, and says which piece declared it when a piece
+      # did. Absent for an aggregate's own commands, and ABSENT is not EMPTY.
+      reference_to Entity, as: :entity_id, optional: true
+      attribute :name,  CommandName
+      attribute :role,  Actor, optional: true
+      attribute :goal,  Goal, optional: true
+      # See Aggregate.Declare's own `provenance` — identical shape, one
+      # level down.
+      attribute :provenance, CommandText, optional: true
+      # See this aggregate's own `from` field comment, above.
+      attribute :from,       CommandText, optional: true
+
+      attribute :position, Position, optional: true
+      sets :aggregate
+      sets :entity_id
+      sets :name
+      sets :role
+      sets :goal
+      sets :provenance
+      sets :from
+      sets :position
+      emits "VerbDeclared"
+    end
+
+    command "Argument" do
+      role "Language"
+      goal "Attach one argument to the command"
+
+      attribute :name,    ArgName
+      attribute :type,    ArgType
+      attribute :list,    ArgType
+      attribute :optional, ArgType, optional: true
+      attribute :pattern,  ArgType, optional: true
+      attribute :default, ArgType, optional: true
+      # The closed set this argument's value must belong to — see
+      # Aggregate.Attribute, which carries the same word for a head's attributes.
+      attribute :admits,  ArgType, optional: true
+      # Whether this argument was minted verbatim from the owning aggregate/
+      # entity's own reference-typed attribute (`sets :field` importing a
+      # `reference_to`/`has_many`/`has_one`/`belongs_to` field rather than
+      # retyping it) — see Aggregate.Attribute, which carries the same word
+      # for a head's own attributes. Missing here, a round trip through the
+      # self-hosted meta-domain silently dropped it for every command
+      # argument, even though the live DSL builder set it correctly in
+      # memory (CommandBuilder#resolve_bare_set!) — the wire just never
+      # carried it back.
+      attribute :relationship, ArgType, optional: true
+
+      sets :attributes, append: { name: :name, type: :type, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits "ArgumentAttached"
+    end
+
+    # An argument that points at ANOTHER aggregate's head — the same word
+    # `reference_to`, written on a command instead of on the head.
+    #
+    # `Argument` types its type as text, so a reference argument arrived as the
+    # STRING "Reference<Customer>" and the language held a spelling rather than a
+    # reference. That left "a reference points at a declared head" enforceable
+    # only by a `raise Malformed` in the DSL, for three of the four places the
+    # word can be written. As a reference it is a consequence of the model here
+    # too, exactly as Aggregate.Reference made it one on a head.
+    command "Reference" do
+      role "Language"
+      goal "Attach an argument that points at another aggregate's head"
+
+      reference_to Aggregate, as: :points_at
+      # No `given` that the name is present : ArgName already carries that
+      # invariant, and a value object's invariant fires during coercion — before
+      # any given is reached. A rule that cannot be the one to refuse is
+      # decoration, and this language has paid for that mistake before.
+      attribute :name,    ArgName
+      attribute :list,    ArgType
+      attribute :optional, ArgType, optional: true
+      attribute :pattern,  ArgType, optional: true
+      attribute :default, ArgType, optional: true
+      attribute :admits,  ArgType, optional: true
+      # See Argument's own :relationship, just above — the same gap, one
+      # verb over.
+      attribute :relationship, ArgType, optional: true
+
+      sets :attributes, append: { name: :name, type: :points_at, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits "ArgumentReferenceAttached"
+    end
+
+    value_object "ArgName" do
+      attribute :value, String
+      invariant("an argument is named") { !value.to_s.empty? }
+    end
+
+    value_object "ArgType" do
+      attribute :value, String
+      # list / default reuse this shape and are legitimately empty
+    end
+
+    command "Rule" do
+      role "Language"
+      goal "Attach one given to the command"
+
+      attribute :description, RuleText, optional: true
+      attribute :canonical,   RuleText
+
+      given("a rule says what it means")  { !description.value.to_s.empty? }
+      given("a rule survives extraction") { !canonical.value.to_s.empty? }
+
+      sets :givens, append: { description: :description, canonical: :canonical }
+
+      emits "RuleAttached"
+    end
+
+    command "Ensure" do
+      role "Language"
+      goal "Attach one postcondition to the command"
+
+      attribute :description, RuleText, optional: true
+      attribute :canonical,   RuleText
+
+      given("a rule says what it means")  { !description.value.to_s.empty? }
+      given("a rule survives extraction") { !canonical.value.to_s.empty? }
+
+      sets :ensures, append: { description: :description, canonical: :canonical }
+
+      emits "EnsureAttached"
+    end
+
+    value_object "RuleText" do
+      attribute :value, String
+    end
+
+    command "Change" do
+      role "Language"
+      goal "Attach one mutation to the command"
+
+      attribute :target, FieldRef
+      # NAMED ON THE ARGUMENT, not only on the Change row it fills. The row is
+      # what the IR holds ; THIS is what a caller hands in, so this is where a
+      # bad op has to be refused — `OpName`'s deleted invariant was refusing
+      # exactly here, and the link has to reach the same door to replace it.
+      attribute :op,     OpName, admits: "Vocabulary::MutationOp"
+      attribute :field,  FieldRef
+      attribute :kind,   FieldRef
+      attribute :source, FieldRef
+
+      given("a mutation names a target")     { !target.value.to_s.empty? }
+      given("a mutation does something")     { !op.value.to_s.empty? }
+
+      sets :mutations, append: { target: :target, op: :op, field: :field, kind: :kind, source: :source }
+
+      emits "ChangeAttached"
+    end
+
+    value_object "FieldRef" do
+      attribute :value, String
+    end
+
+    # THE SET IT ADMITS IS NAMED, NOT RESTATED. This carried
+    # `set || append || increment || decrement` — Vocabulary::MutationOp written
+    # out a second time, one level in, which is exactly the kind of copy
+    # that drifts. `Change.op` now says `admits:
+    # Vocabulary::MutationOp`, so there is no second list left to drift.
+    value_object "OpName" do
+      attribute :value, String
+    end
+
+    command "ActsOn" do
+      role "Language"
+      goal "Name the aggregate this command reaches through"
+
+      # NAMED `root`, not `references` : a command argument SHADOWS the aggregate
+      # field of the same name inside a given, so a once-only rule cannot read
+      # the state it guards unless the two differ.
+      attribute :root, EventName
+
+      given("a command names what it acts on") { !root.value.to_s.empty? }
+      given("a command acts on ONE root")      { references.value.to_s.empty? }
+
+      sets :references, to: :root
+
+      emits "ReferenceNamed"
+    end
+
+    command "Announce" do
+      role "Language"
+      goal "Name the event this command emits"
+
+      attribute :announces, EventName
+
+      given("an event is named") { !announces.value.to_s.empty? }
+
+      sets :emits, append: { name: :announces }
+
+      emits "AnnouncementNamed"
+    end
+
+    # HOW COMMAND IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: Command.
+    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: "role",            context: "Command", body: "none",   inner: "", opens: "", fills: "role", calls: "role_impl"
+      member word: "goal",            context: "Command", body: "none",   inner: "", opens: "", fills: "goal"
+      member word: "provenance",      context: "Command", body: "none",   inner: "", opens: "", fills: "provenance", calls: "provenance_impl"
+      member word: "reference_to",    context: "Command", body: "none",   inner: "", opens: "", fills: "references", calls: "reference_to_impl"
+      member word: "given",           context: "Command", body: "source", inner: "", opens: "", fills: "givens", resolves_via: "hash_chain", calls: "given_impl"
+      member word: "sets",            context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", calls: "sets_impl"
+      # RENAMED spelling of `sets`, above — its own dedicated, deprecated row
+      # (not `sets`'s own `was:`, syntax_conformance_spec.rb's own "no
+      # renamed-away spelling as a row of its own AND a was:" rule), kept
+      # here refusing live ONLY so `MetaValidator.shadow_parsing?` can still
+      # read frozen era text that used it (CommandBuilder#then_set_impl's
+      # own comment).
+      member word: "then_set",        context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", status: "deprecated", calls: "then_set_impl"
+      # A command's synchronous handoff into one nested entity command
+      # (CommandBuilder#delegates_to_impl's own comment gives the full
+      # reasoning) — a new word, not a migrated one.
+      member word: "delegates_to",    context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", calls: "delegates_to_impl"
+      member word: "emits",           context: "Command", body: "none",   inner: "", opens: "", fills: "emits"
+      # A VALUE, NOT A DECLARATION — `state(:field)` is written INSIDE a
+      # `sets` (`append: { knights: state(:knights) }`, `to: state(:ply)`)
+      # and names the record's own field as that mutation's source; it
+      # fills nothing of its own, the `sets` it sits in fills `mutations`.
+      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"
+
+    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 :coerce,           String
+      attribute :blank_message,    String
+
+      member keyword: "role",            context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "role"
+      member keyword: "goal",            context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "goal", coerce: "false"
+      member keyword: "provenance",      context: "Command", at: "",  named: "from",      kind: "literal",  required: "true",  fills: "provenance"
+      member keyword: "reference_to",    context: "Command", at: "1", named: "",          kind: "constant", required: "true",  fills: "type"
+      member keyword: "reference_to",    context: "Command", at: "",  named: "as",        kind: "symbol",   required: "false", fills: "name"
+      member keyword: "reference_to",    context: "Command", at: "",  named: "optional",  kind: "flag",     required: "false", fills: "optional"
+      member keyword: "given",           context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "description"
+      member keyword: "ensures",         context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "description"
+      member keyword: "sets",            context: "Command", at: "1", named: "",          kind: "symbol",   required: "true",  fills: "target"
+      member keyword: "sets",            context: "Command", at: "",  named: "to",        kind: "literal",  required: "false", fills: "source", selects: "op=set"
+      member keyword: "sets",            context: "Command", at: "",  named: "append",    kind: "literal",  required: "false", fills: "source", selects: "op=append"
+      member keyword: "sets",            context: "Command", at: "",  named: "increment", kind: "literal",  required: "false", fills: "source", selects: "op=increment"
+      member keyword: "sets",            context: "Command", at: "",  named: "decrement", kind: "literal",  required: "false", fills: "source", selects: "op=decrement"
+      member keyword: "sets",            context: "Command", at: "",  named: "multiply",  kind: "literal",  required: "false", fills: "source", selects: "op=multiply"
+      member keyword: "sets",            context: "Command", at: "",  named: "clamp",     kind: "literal",  required: "false", fills: "source", selects: "op=clamp"
+      member keyword: "sets",            context: "Command", at: "",  named: "remove",    kind: "literal",  required: "false", fills: "source", selects: "op=remove"
+      member keyword: "then_set",        context: "Command", at: "1", named: "",           kind: "symbol",   required: "true",  fills: "target"
+      member keyword: "then_set",        context: "Command", at: "",  named: "to",         kind: "literal",  required: "false", fills: "source", selects: "op=set"
+      member keyword: "then_set",        context: "Command", at: "",  named: "from",       kind: "literal",  required: "false", fills: "source", selects: "op=set"
+      member keyword: "then_set",        context: "Command", at: "",  named: "append",     kind: "literal",  required: "false", fills: "source", selects: "op=append"
+      member keyword: "then_set",        context: "Command", at: "",  named: "increment",  kind: "literal",  required: "false", fills: "source", selects: "op=increment"
+      member keyword: "then_set",        context: "Command", at: "",  named: "decrement",  kind: "literal",  required: "false", fills: "source", selects: "op=decrement"
+      member keyword: "then_set",        context: "Command", at: "",  named: "multiply",   kind: "literal",  required: "false", fills: "source", selects: "op=multiply"
+      member keyword: "then_set",        context: "Command", at: "",  named: "clamp",      kind: "literal",  required: "false", fills: "source", selects: "op=clamp"
+      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"
+      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"
+      member keyword: "attribute",       context: "Command", at: "2", named: "",          kind: "constant", required: "true",  fills: "type"
+      member keyword: "attribute",       context: "Command", at: "",  named: "default",   kind: "literal",  required: "false", fills: "default"
+      member keyword: "attribute",       context: "Command", at: "",  named: "optional",  kind: "flag",     required: "false", fills: "optional"
+      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"
+
+    end
+  end
+end