hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,316 @@
+Hecks.bluebook "Bluebook" do
+  aggregate "Entity" do
+    description "One entity inside an aggregate — an element with its own identity, state machine, commands and queries. Its own root because it repeats the aggregate's whole shape one level down."
+
+    reference_to Aggregate
+
+    # THE AGGREGATE IT IS IN, AND ITS NAME. Note this is the identity of the RECORD
+    # describing a piece, which is a different thing from the identity that piece
+    # itself declares (`identified_by`, the list below).
+    identified_by :aggregate, :name
+
+    attribute :owner,         EntityText
+    attribute :name,          EntityName
+    attribute :description,   EntityName
+    # SEVERAL PATHS, joined — a piece spells an identity exactly as a head does,
+    # which is the whole point of it being its own root.
+    attribute :identified_by, list_of(IdentityPath)
+    attribute :attributes,    list_of(PieceField)
+    # ADR 0028 — A PRECONDITION SHARED ACROSS THIS PIECE'S OWN COMMANDS,
+    # DECLARED ONCE — the SAME Rule shape Aggregate's own `preconditions`
+    # already carries (that file's own comment on why it's declared
+    # again here rather than shared: a value object is aggregate-scoped
+    # in this self-hosting domain).
+    attribute :preconditions, list_of(Rule)
+    # A PIECE'S OWN SHAPE RULE — the SAME Rule shape, checked (round 7)
+    # against EVERY INSTANCE this piece's own aggregate holds, not the
+    # aggregate's own flat state — `ValueObject#invariants`'s own
+    # relationship to ITS OWN instances, one construct over.
+    attribute :invariants,    list_of(Rule)
+    attribute :state_field, EntityText, optional: true
+    attribute :state_start, EntityText, optional: true
+    attribute :transitions, list_of(PieceTransition)
+
+    value_object "EntityName" do
+      attribute :value, String
+      invariant("an entity is named") { !value.to_s.empty? }
+    end
+
+    value_object "EntityText" do
+      attribute :value, String
+    end
+
+    # See Aggregate's own "Rule" value object — the identical shape,
+    # declared again here rather than shared (that file's own comment
+    # on why).
+    value_object "Rule" do
+      attribute :description, String
+      attribute :canonical,   String
+    end
+
+    # A piece's identity is made of parts the same way a head's is, so it holds
+    # the same shape. Declared here rather than shared because a value object
+    # belongs to the aggregate that uses it.
+    value_object "IdentityPath" do
+      attribute :value, String
+    end
+
+    value_object "PieceField" 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.
+      attribute :admits, String, optional: true
+      attribute :relationship, String, optional: true
+    end
+
+    value_object "PieceTransition" do
+      attribute :command,    String
+      attribute :from_state, String
+      attribute :to_state,   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, EntityText
+      where(aggregate: :aggregate)
+      order_by :position
+    end
+    command "Declare" do
+      role "Language"
+      goal "Open an entity inside an aggregate"
+
+      reference_to Aggregate
+      attribute :owner,         EntityText
+      attribute :name,          EntityName
+      attribute :description,   EntityName, optional: true
+
+      attribute :position, Position, optional: true
+      sets :aggregate
+      sets :owner
+      sets :name
+      sets :description
+      sets :position
+      emits "PieceDeclared"
+    end
+
+    # ONE PART OF THE PIECE'S IDENTITY, attached exactly as an aggregate's is.
+    #
+    # A PIECE MUST SAY WHAT IT IS KNOWN BY — the rule, where the language keeps
+    # its rules. An entity is an element with an identity of ITS OWN ; that is
+    # the whole difference between a piece and a value object, so a command
+    # acting on one must be able to say which one. Undeclared, every reader
+    # has to invent its own answer — fall through to nothing, or assume
+    # `id` — and inventions agree only because every entity in the corpus happened
+    # to declare it: a divergence the
+    # declaration was masking. Requiring it removes the default there was to
+    # disagree about. That requirement now sits on Seal, where a whole-document
+    # rule belongs ; what stays here is the shape of each part.
+    command "Identify" do
+      role "Language"
+      goal "Attach one part of the entity's identity"
+
+      attribute :path, IdentityPath
+
+      # See Aggregate.Identify, where the same rule is written out in full —
+      # the builder resolves the real shape (dotted-unwrap, reference, or
+      # bare scalar) before a part ever reaches here.
+      given("an identity part names something") { !path.value.to_s.empty? }
+
+      sets :identified_by, append: { value: :path }
+      emits "PieceIdentified"
+    end
+
+    command "Seal" do
+      role "Language"
+      goal "Close an entity — the checks that need every declaration present"
+
+      # A piece gets the whole-document shape a head has, for the same reason :
+      # "it said SOMETHING" cannot be asked while the parts are still arriving.
+
+      given("an entity says what it is known by") { !identified_by.empty? }
+
+      emits "PieceSealed"
+    end
+
+    command "Attribute" do
+      role "Language"
+      goal "Attach one attribute to the entity"
+
+      attribute :name,    EntityText
+      attribute :type,    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: :type, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
+
+      emits "PieceAttributeAttached"
+    end
+
+
+    # A PRECONDITION SHARED ACROSS THIS PIECE'S OWN COMMANDS, DECLARED
+    # ONCE (ADR 0028) — see Aggregate.Precondition, the identical shape
+    # one level down: the piece's own named `given`, referenced back by
+    # one of its own commands rather than re-typed.
+    command "Precondition" do
+      role "Language"
+      goal "Declare one precondition this piece's own commands can reference by name"
+
+      attribute :description, EntityText, optional: true
+      attribute :canonical,   EntityText
+
+      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 "PiecePreconditionAttached"
+    end
+
+    # A PIECE'S OWN SHAPE RULE, DECLARED ONCE (round 7) — see
+    # Aggregate.Invariant, the identical shape one level down: checked
+    # against every instance of this piece, not this ONE aggregate's
+    # own flat state.
+    command "Invariant" do
+      role "Language"
+      goal "Attach one shape rule this piece's own instances must hold"
+
+      attribute :description, EntityText, optional: true
+      attribute :canonical,   EntityText
+
+      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 "PieceInvariantAttached"
+    end
+
+    command "Lifecycle" do
+      role "Language"
+      goal "Name the field this entity's state machine runs on"
+
+
+      sets :state_field
+      sets :state_start
+
+      emits "PieceLifecycleNamed"
+    end
+
+    command "Transition" do
+      role "Language"
+      goal "Attach one transition to the entity's state machine"
+
+      attribute :command,    EntityText
+      attribute :from_state, EntityText, optional: true
+      attribute :to_state,   EntityText
+
+      sets :transitions, append: { command: :command, from_state: :from_state, to_state: :to_state }
+
+      emits "PieceTransitionAttached"
+    end
+
+    # HOW ENTITY IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: Entity.
+    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: "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: "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"
+      member word: "lifecycle",       context: "Entity", body: "keywords", inner: "Lifecycle",  opens: "",         fills: "state_field", calls: "lifecycle_impl"
+      member word: "attribute",       context: "Entity", body: "none",     inner: "",           opens: "",         fills: "attributes", calls: "attribute_impl"
+      member word: "reference_to",    context: "Entity", body: "none",     inner: "",           opens: "",         fills: "attributes", calls: "reference_to_impl"
+      member word: "has_many",        context: "Entity", body: "none",     inner: "",           opens: "",         fills: "attributes", calls: "has_many_impl"
+      member word: "has_one",         context: "Entity", body: "none",     inner: "",           opens: "",         fills: "attributes", calls: "has_one_impl"
+      member word: "belongs_to",      context: "Entity", body: "none",     inner: "",           opens: "",         fills: "attributes", calls: "belongs_to_impl"
+      member word: "entity",          context: "Entity", body: "keywords", inner: "Entity",     opens: "Entity",   fills: "", calls: "entity_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: "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"
+      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"
+      member keyword: "identified_by",   context: "Entity", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "command",         context: "Entity", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      member keyword: "command",         context: "Entity", at: "",  named: "from",     kind: "literal",  required: "false", fills: "from"
+      member keyword: "query",           context: "Entity", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      member keyword: "entity",          context: "Entity", at: "1", named: "",         kind: "text",     required: "true",  fills: "name"
+      member keyword: "lifecycle",       context: "Entity", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "state_field"
+      member keyword: "lifecycle",       context: "Entity", at: "",  named: "default",  kind: "literal",  required: "true",  fills: "state_start"
+      member keyword: "attribute",       context: "Entity", at: "1", named: "",         kind: "symbol",   required: "true",  fills: "name"
+      member keyword: "attribute",       context: "Entity", at: "2", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "attribute",       context: "Entity", at: "",  named: "default",  kind: "literal",  required: "false", fills: "default"
+      member keyword: "attribute",       context: "Entity", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "attribute",       context: "Entity", at: "",  named: "pattern",  kind: "text",     required: "false", fills: "pattern"
+      member keyword: "attribute",       context: "Entity", at: "",  named: "admits",   kind: "text",     required: "false", fills: "admits"
+      member keyword: "attribute",       context: "Entity", at: "",  named: "one_of",   kind: "list",     required: "false", fills: "one_of"
+      member keyword: "reference_to",    context: "Entity", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "reference_to",    context: "Entity", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "reference_to",    context: "Entity", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "has_many",        context: "Entity", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "has_many",        context: "Entity", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "has_one",         context: "Entity", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "has_one",         context: "Entity", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "has_one",         context: "Entity", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+      member keyword: "belongs_to",      context: "Entity", at: "1", named: "",         kind: "constant", required: "true",  fills: "type"
+      member keyword: "belongs_to",      context: "Entity", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"
+      member keyword: "belongs_to",      context: "Entity", at: "",  named: "optional", kind: "flag",     required: "false", fills: "optional"
+
+    end
+  end
+end

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

@@ -0,0 +1,172 @@
+Hecks.bluebook "Bluebook" do
+  aggregate "Policy" do
+    description "One policy — the event it watches, the command it fires, and the domain that command belongs to."
+
+    reference_to Bluebook
+
+    # THE CHAPTER IT IS IN, AND ITS NAME. A policy hangs off the chapter rather
+    # than an aggregate, so the chapter is the part above it.
+    identified_by :bluebook, :name
+
+    attribute :name,            PolicyName
+    # WHICH HEAD DECLARED IT, empty for a reaction the chapter owns.
+    #
+    # A policy written inside an aggregate is hoisted onto the chapter by the
+    # builder, and the chapter is where the runtime reads it — so nothing was ever
+    # lost at runtime. What was lost is where it was WRITTEN, which is a fact about
+    # the source, and facts about the source are what this language holds.
+    # `Aggregate#to_h` does not carry it and does not need to: the wire format is
+    # a contract, and the language may hold more than it.
+    attribute :aggregate,       PolicyText
+    attribute :on_event,        PolicyText
+    attribute :trigger_command, PolicyText
+    attribute :target_domain,   PolicyText
+    # THE GUARD, CARRIED AS TEXT — same discipline `Command.givens`
+    # already holds: the block that wrote it is never called at
+    # runtime, only its EXTRACTED SOURCE is (Ports::Extraction), so
+    # what the language holds is the string, not a live Proc no wire
+    # format could carry. Optional — most policies fire unconditionally.
+    attribute :where,           PolicyText, optional: true
+    # THE FAN-OUT SOURCE — a query verb ("Aggregate.query_name" or
+    # "Domain::Aggregate.query_name"), same text shape as
+    # `trigger_command`/`target_domain` beside it. Optional — most
+    # policies fire once, not once per row.
+    attribute :for_each,        PolicyText, optional: true
+    # WHAT THE TRIGGER IS GIVEN, when the event's own shape is not it.
+    # Empty means the whole payload forwards verbatim — what every policy
+    # did before this existed, and still the right default for a trigger
+    # shaped like its event.
+    #
+    # The same `Binding` list a saga's own `Dispatch` carries, for the
+    # same reason: a reaction crosses an aggregate boundary, and the
+    # event on one side is under no obligation to be shaped like the
+    # command on the other. Without it the target has to declare every
+    # field the event happens to carry — banking's own `FreezeAccount`
+    # grew an attribute it never reads, and Account grew two duplicated
+    # value objects to type it, before this word existed.
+    attribute :with_spec,       list_of(Binding)
+
+    value_object "PolicyName" do
+      attribute :value, String
+      invariant("a policy is named") { !value.to_s.empty? }
+    end
+
+    value_object "PolicyText" do
+      attribute :value, String
+    end
+
+    # DECLARED HERE RATHER THAN SHARED WITH `Dispatch`'s own — a value
+    # object belongs to the aggregate that uses it, and everything that
+    # walks an aggregate's own scope has nowhere else to look.
+    value_object "Binding" do
+      attribute :key,   String
+      attribute :value, String
+    end
+
+    # The way back: everything DECLARED IN the chapter 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 :bluebook, PolicyText
+      where(bluebook: :bluebook)
+      order_by :position
+    end
+    command "Declare" do
+      role "Language"
+      goal "Declare a policy on a chapter"
+
+      reference_to Bluebook
+      attribute :name,            PolicyName
+      attribute :aggregate,       PolicyText, optional: true
+      attribute :on_event,        PolicyText
+      attribute :trigger_command, PolicyText
+      attribute :target_domain,   PolicyText, optional: true
+      attribute :where,           PolicyText, optional: true
+      attribute :for_each,        PolicyText, optional: true
+
+      attribute :position, Position, optional: true
+      sets :bluebook
+      sets :name
+      sets :aggregate
+      sets :on_event
+      sets :trigger_command
+      sets :target_domain
+      sets :where
+      sets :for_each
+      sets :position
+      emits "ReactionDeclared"
+    end
+
+    command "Bind" do
+      role "Language"
+      goal "Bind one argument of the triggered command"
+
+      attribute :key,   PolicyText
+      attribute :value, PolicyText
+
+      sets :with_spec, append: { key: :key, value: :value }
+
+      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.
+    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: "on",              context: "Policy",    body: "none", inner: "", opens: "",       fills: "on_event"
+      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"
+      member word: "for_each",        context: "Policy",    body: "none", inner: "", opens: "", fills: "for_each"
+
+    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: "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"
+      member keyword: "for_each",        context: "Policy", at: "1", named: "", kind: "text", required: "true", fills: "for_each"
+      member keyword: "trigger", context: "Policy", at: "", named: "with", kind: "pairs", required: "false", fills: "with_spec", pairs_shape: "verbatim"
+
+    end
+  end
+end