hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,264 @@
+Hecks.bluebook "Bluebook" do
+  aggregate "ProcessManager" do
+    description "One process manager — what correlates its instances, what starts and ends it, and the states it moves through."
+
+    reference_to Bluebook
+
+    # THE CHAPTER IT IS IN, AND ITS NAME — the same shape a policy takes, and for
+    # the same reason.
+    identified_by :bluebook, :name
+
+    attribute :name,      ProcessManagerName
+    attribute :correlates_by, ProcessManagerText
+    attribute :starts_on,     ProcessManagerText
+    attribute :ends_on,       ProcessManagerText
+    attribute :states,    list_of(SagaState)
+    # S17, ADR 0026 — Handler nested here (see `entity "Handler"`, below),
+    # an entity rather than its own root aggregate. `list_of(Handler)`
+    # forward-references it the same way banking's own `attribute :ledger,
+    # list_of(LedgerEntry)` names LedgerEntry before it is declared.
+    attribute :handlers,  list_of(Handler)
+
+    value_object "ProcessManagerName" do
+      attribute :value, String
+      invariant("a process manager is named") { !value.to_s.empty? }
+    end
+
+    value_object "ProcessManagerText" do
+      attribute :value, String
+    end
+
+    value_object "SagaState" do
+      attribute :name, String
+    end
+
+    # S17, ADR 0026 — HandlerText/DispatchText/Binding, hoisted up from
+    # the old standalone `aggregate "Handler"`/`aggregate "Dispatch"`. An
+    # entity cannot declare its own `value_object` (EntityBuilder has no
+    # such method — a piece borrows its owning aggregate's, the same way
+    # LedgerEntry borrows Account's Money), so these live here now, at
+    # the ROOT, where BOTH `entity "Handler"` and its own nested `entity
+    # "Dispatch"` can still reach them — a piece mints no value objects
+    # of its own AT ANY DEPTH, so there is exactly one pool however deep
+    # the nesting goes (`EntityBuilder#entity`'s own comment).
+    value_object "HandlerText" do
+      attribute :value, String
+    end
+
+    value_object "DispatchText" do
+      attribute :value, String
+    end
+
+    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, ProcessManagerText
+      where(bluebook: :bluebook)
+      order_by :position
+    end
+    command "Declare" do
+      role "Language"
+      goal "Open a process manager on a chapter"
+
+      reference_to Bluebook
+      attribute :name,      ProcessManagerName
+      attribute :correlates_by, ProcessManagerText
+      attribute :starts_on,     ProcessManagerText
+      # A PROCEDURE NEED NOT DECLARE AN ENDING. The runtime has always held
+      # this optional — ProcessManagerBuilder defaults `@ends_on` to nil,
+      # validates only correlates_by/starts_on/states/handlers,
+      # and fills it only if the line is written. The
+      # language was the one saying it was required, and nothing in the corpus
+      # had to disagree because every procedure in it happens to end.
+      attribute :ends_on,       ProcessManagerText, optional: true
+
+      attribute :position, Position, optional: true
+      sets :bluebook
+      sets :name
+      sets :correlates_by
+      sets :starts_on
+      sets :ends_on
+      sets :position
+      emits "SagaDeclared"
+    end
+
+    command "State" do
+      role "Language"
+      goal "Attach one state to the process manager"
+
+      attribute :name, ProcessManagerText
+
+      sets :states, append: { name: :name }
+
+      emits "SagaStateAttached"
+    end
+
+    # THE HANDLER'S OWN CREATION. S17, ADR 0026 — Handler is a genuine
+    # ENTITY now (`entity "Handler"`, below), and an entity is never
+    # created through its own dotted verb — banking's own LedgerEntry is
+    # created by `Account.LogEntry`, an ordinary append on the OWNER,
+    # never by a `LedgerEntry.Declare` of its own
+    # (`EntityInterpreter#element_of` only LOCATES an element already on
+    # the list — it has no path that creates one). So Handler's creation
+    # moved here, onto ProcessManager, mirroring `State` beside it: a
+    # bare, aggregate-level append.
+    command "Handler" do
+      role "Language"
+      goal "Open a handler inside a process manager"
+
+      attribute :event_type, HandlerText
+      # A LEG ALWAYS SAYS WHERE IT MOVES FROM. There is no wildcard leg to be
+      # optional for: `on "Event", transition: { from => to }` is the only
+      # spelling the runtime reads, and it refuses anything else —
+      # `single_transition` raises unless the hash holds exactly one from => to
+      # pair, so a leg without one
+      # is never built at all. `optional: true` here was
+      # the language admitting a leg the runtime cannot parse.
+      attribute :from_state, HandlerText
+      attribute :to_state,   HandlerText
+
+      sets :handlers, append: { event_type: :event_type, from_state: :from_state, to_state: :to_state }
+
+      emits "LegDeclared"
+    end
+
+    # S17, ADR 0026 — ONE HANDLER, nested rather than its own root
+    # aggregate. No `saga` field. It named the old word for a process
+    # manager, held nothing — ProcessManagerHandler has no such reader,
+    # so every Handler record's saga was empty — and repeated the parent
+    # that its own containment already carries. A field that names the
+    # wrong thing, holds nothing, and duplicates the reference beside it.
+    #
+    # `event_type` is an event name, or one of the Trigger vocabulary's
+    # members when the leg answers something no aggregate announces — and
+    # is Handler's own real, non-positional identity now : a saga answers
+    # each event ONCE, so the event names the leg, and the process
+    # manager it belongs to is structural (which list this element sits
+    # in), not a stored field any more.
+    entity "Handler" do
+      description "One handler inside a process manager — the event it answers, the state move it makes, and the commands it sends. Nested under the process manager because a handler holds nested dispatches, which hold nested bindings."
+
+      identified_by HandlerText, as: :event_type
+
+      attribute :from_state, HandlerText
+      attribute :to_state,   HandlerText
+      # S17, ADR 0026 — Dispatch nested here too (see `entity "Dispatch"`,
+      # below), one level further in than Handler itself.
+      attribute :dispatches, list_of(Dispatch)
+
+      # THE DISPATCH'S OWN CREATION — same reason Handler's own creation
+      # lives on ProcessManager, one level up: an entity is never created
+      # through its own dotted verb. Reached as a DOTTED verb itself
+      # (`ProcessManager.Handler.Dispatch`) since Handler, the owner
+      # doing the creating here, is an entity too, not a real aggregate
+      # with a bare verb of its own to dispatch into.
+      command "Dispatch" do
+        role "Language"
+        goal "Open a dispatch inside a handler"
+
+        attribute :command_name, DispatchText
+
+        sets :dispatches, append: { command_name: :command_name }
+
+        emits "SendDeclared"
+      end
+
+      # S17, ADR 0026 — ONE COMMAND A HANDLER DISPATCHES, nested two
+      # levels in rather than its own root aggregate — "no life outside
+      # its Handler" (the ADR's own words). The bindings are an open
+      # map, which no value object can hold — that was always a reason
+      # it could not be one, never a reason it could not be an entity.
+      # `command_name` is Dispatch's own real, non-positional identity,
+      # the same shape Handler's own `event_type` just took one level up.
+      entity "Dispatch" do
+        description "One command a handler dispatches, with the arguments it binds. Nested under the handler because the bindings are an open map, which no value object can hold."
+
+        identified_by DispatchText, as: :command_name
+
+        attribute :with_spec, list_of(Binding)
+
+        command "Bind" do
+          role "Language"
+          goal "Bind one argument of the dispatched command"
+
+          attribute :key,   DispatchText
+          attribute :value, DispatchText
+
+          sets :with_spec, append: { key: :key, value: :value }
+
+          emits "BindingAttached"
+        end
+      end
+    end
+
+    # HOW PROCESSMANAGER IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: ProcessManager, Handler.
+    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: "correlates_by",   context: "ProcessManager", body: "none",     inner: "",        opens: "",        fills: "correlates_by"
+      member word: "starts_on",       context: "ProcessManager", body: "none",     inner: "",        opens: "",        fills: "starts_on"
+      member word: "ends_on",         context: "ProcessManager", body: "none",     inner: "",        opens: "",        fills: "ends_on"
+      member word: "transition",      context: "ProcessManager", body: "keywords", inner: "Handler", opens: "Handler", fills: "", calls: "transition_impl"
+      member word: "transition",      context: "ProcessManager", body: "none",     inner: "",        opens: "",        fills: "", calls: "transition_impl"
+      member word: "dispatch",        context: "Handler",        body: "none",     inner: "",        opens: "Dispatch", fills: "", calls: "dispatch_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 :coerce,           String
+      attribute :blank_message,    String
+
+      member keyword: "correlates_by",   context: "ProcessManager", at: "1", named: "",           kind: "symbol", required: "true", fills: "correlates_by"
+      member keyword: "starts_on",       context: "ProcessManager", at: "1", named: "",           kind: "text",   required: "true", fills: "starts_on"
+      member keyword: "ends_on",         context: "ProcessManager", at: "1", named: "",           kind: "text",   required: "true", fills: "ends_on"
+      member keyword: "transition",      context: "ProcessManager", at: "1", named: "",           kind: "pairs",  required: "true", fills: "", pair_key_fills: "event_type", pair_value_fills: "to_state", pairs_shape: "fields"
+      member keyword: "transition",      context: "ProcessManager", at: "",  named: "from",       kind: "text",   required: "true",  fills: "from_state"
+      member keyword: "transition",      context: "ProcessManager", at: "",  named: "from",       kind: "list",   required: "false", fills: "from_state"
+      member keyword: "dispatch",        context: "Handler", at: "1", named: "",     kind: "constant", required: "true", fills: "command_name"
+      member keyword: "dispatch",        context: "Handler", at: "1", named: "",     kind: "text",  required: "true",  fills: "command_name"
+      member keyword: "dispatch",        context: "Handler", at: "",  named: "with", kind: "pairs", required: "false", fills: "with_spec", pairs_shape: "verbatim"
+
+    end
+  end
+end

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

@@ -0,0 +1,267 @@
+Hecks.bluebook "Bluebook" do
+  aggregate "ReadModel" do
+    description "One read model — the aggregate heads it gathers and the reference it hangs from."
+
+    reference_to Bluebook
+
+    # THE CHAPTER IT IS IN, AND ITS NAME.
+    identified_by :bluebook, :name
+
+    attribute :name,             ReadModelName
+    attribute :description,      ProjectionPurpose
+    attribute :query_name,       ReadModelText
+    attribute :reference_name,   ReadModelText
+    attribute :reference_target, ReadModelText
+    attribute :aggregate_heads,  list_of(Head)
+    # The same open map a query carries — see Query's AskOption. A read model
+    # inherits every specification option an ask has, so it holds them the same way.
+    attribute :options,          list_of(ProjectionOption)
+    # WHICH of the eligible head's own fields to nest its rows under, in
+    # declared order. Rows, not a single value object with N fields — an
+    # arbitrary NUMBER of fields, the same reason `aggregate_heads`/
+    # `options` are lists rather than fixed attributes.
+    attribute :group_by,         list_of(GroupByField)
+    # `count`/`median_field` are the OTHER two reductions a read model
+    # may declare over its one eligible head, siblings of `group_by`
+    # rather than of `options` — same permissive `ReadModelText` shape,
+    # and the same UNmarked-optional spelling `reference_name`/
+    # `reference_target` already use just above (permissiveness lives
+    # in `ReadModelText`'s own lack of an invariant, not in an
+    # `optional:` flag this chapter's aggregate-level attributes never
+    # carry) — "true"/"" for `count`, a field name or "" for
+    # `median_field`, both legitimately absent on a read model that
+    # declares neither.
+    attribute :count,            ReadModelText, optional: true
+    attribute :median_field,     ReadModelText, optional: true
+
+    value_object "ReadModelName" do
+      attribute :value, String
+      invariant("a read model is named") { !value.to_s.empty? }
+    end
+
+    value_object "ReadModelText" do
+      # deliberately permissive : query_name / ref_name / ref_target are
+      # legitimately empty on a read model that has not named them yet
+      attribute :value, String
+    end
+
+    value_object "ProjectionPurpose" do
+      attribute :value, String
+      invariant("a description says something") { !value.to_s.empty? }
+    end
+
+    value_object "Head" do
+      attribute :aggregate, String
+      attribute :as,        String
+      attribute :many,      String
+    end
+
+    value_object "ProjectionOption" do
+      attribute :option, String
+      attribute :key,    String
+      attribute :value,  String
+      attribute :at,     String
+    end
+
+    value_object "GroupByField" do
+      attribute :field, String
+      invariant("a group_by field is named") { !field.to_s.empty? }
+    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, ReadModelText
+      where(bluebook: :bluebook)
+      order_by :position
+    end
+    command "Declare" do
+      role "Language"
+      goal "Open a read model on a chapter"
+
+      reference_to Bluebook
+      attribute :name,             ReadModelName
+      attribute :description,      ProjectionPurpose, optional: true
+      attribute :query_name,       ReadModelText
+      # Both optional now — a ROOTLESS read model (no `reference_to`
+      # declared at all) has neither. Permanently empty, not "not yet
+      # set" — see Gather's own comment below for why that distinction
+      # matters.
+      attribute :reference_name,   ReadModelText, optional: true
+      attribute :reference_target, ReadModelText, optional: true
+
+      attribute :position, Position, optional: true
+      sets :bluebook
+      sets :name
+      sets :description
+      sets :query_name
+      sets :reference_name
+      sets :reference_target
+      sets :position
+      emits "ProjectionDeclared"
+    end
+
+    command "Gather" do
+      role "Language"
+      goal "Attach one aggregate head to the read model"
+
+      # A HEAD IS THE AGGREGATE IT NAMES. There is no head with nothing gathered:
+      # `add_aggregate_head` is only ever reached from an `include Target`,
+      # so the builder cannot produce one
+      # without it — the field is a plain
+      # required, non-empty name. `as` and
+      # `many` are both DERIVED from it when the author does not spell them, which
+      # is the clearest statement that it is the part that cannot be missing.
+      attribute :aggregate, ReadModelText
+      attribute :as,        ReadModelText
+      attribute :many,      ReadModelText
+
+      # NOT "reference_target must already be set" anymore — reference_target
+      # is fixed forever at Declare time (nothing ever changes it later), so
+      # that rule was really "this read model must have SOME reference, ever"
+      # — exactly the constraint a ROOTLESS read model (bulk, no root,
+      # `group_by`'s own real use) deliberately doesn't meet, permanently,
+      # on purpose, not by omission. Removed rather than relaxed: there is
+      # no runtime fact left here that distinguishes "forgot to declare a
+      # reference" from "declared rootless on purpose" — both look
+      # identical (`reference_target` empty) by the time Gather is judged.
+
+      sets :aggregate_heads, append: { aggregate: :aggregate, as: :as, many: :many }
+
+      emits "HeadGathered"
+    end
+
+    command "GroupBy" do
+      role "Language"
+      goal "Nest one collection's own rows by one of its own fields"
+
+      attribute :field, ReadModelText
+
+      given("a group_by field is named") { !field.value.to_s.empty? }
+
+      sets :group_by, append: { field: :field }
+
+      emits "GroupByFieldAdded"
+    end
+
+    # `count`/`median` are LATE-SET scalars, the same shape `Lifecycle`'s
+    # own `state_field`/`state_start` already are on `Aggregate`
+    # (aggregate.bluebook) — a command carrying its own value and a bare
+    # `sets field, to: field` copying it onto the record, rather
+    # than an `append:` (they are not lists, and there is only ever one
+    # of each). `count`/`median_field` are declared here, not folded
+    # into `Declare`, for the same reason `GroupBy` is its own command
+    # above: neither is known until the DSL body runs past `include`.
+    command "Count" do
+      role "Language"
+      goal "Mark the read model as a bare row count over its one eligible collection"
+
+
+      sets :count
+
+      emits "CountDeclared"
+    end
+
+    command "Median" do
+      role "Language"
+      goal "Mark the read model as the median of one numeric field across its one eligible collection"
+
+
+      given("a median field is named") { !median_field.value.to_s.empty? }
+
+      sets :median_field
+
+      emits "MedianFieldSet"
+    end
+
+    command "Option" do
+      role "Language"
+      goal "Attach one part of one specification option to the read model"
+
+      attribute :option, ReadModelText
+      attribute :key,    ReadModelText
+      # Same reading as Query.Option above — an option key may stand alone.
+      attribute :value,  ReadModelText, optional: true
+      attribute :at,     ReadModelText, optional: true
+
+      given("an option is named") { !option.value.to_s.empty? }
+
+      sets :options, append: { option: :option, key: :key, value: :value, at: :at }
+
+      emits "OptionAttached"
+    end
+
+    # HOW READMODEL IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: ReadModel.
+    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: "ReadModel", body: "none", inner: "", opens: "", fills: "description"
+      member word: "reference_to",    context: "ReadModel", body: "none", inner: "", opens: "", fills: "reference_target", calls: "reference_to_impl"
+      member word: "include",         context: "ReadModel", body: "none", inner: "", opens: "", fills: "aggregate_heads", calls: "include_impl"
+      member word: "group_by",        context: "ReadModel", body: "none", inner: "", opens: "", fills: "group_by", calls: "group_by_impl"
+      member word: "count",           context: "ReadModel", body: "none", inner: "", opens: "", fills: "count"
+      member word: "median",          context: "ReadModel", body: "none", inner: "", opens: "", fills: "median_field"
+      member word: "where",           context: "ReadModel", body: "none", inner: "", opens: "", fills: "options", calls: "where_impl"
+      member word: "order_by",        context: "ReadModel", body: "none", inner: "", opens: "", fills: "options", calls: "order_by_impl"
+      member word: "authorize",       context: "ReadModel", body: "none", inner: "", opens: "", fills: "options", calls: "authorize_impl"
+      member word: "inspect_query",   context: "ReadModel", body: "none", inner: "", opens: "", fills: "options"
+
+    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: "description",     context: "ReadModel", at: "1", named: "",        kind: "text",     required: "true",  fills: "description", coerce: "false"
+      member keyword: "reference_to",    context: "ReadModel", at: "1", named: "",        kind: "constant", required: "true",  fills: "reference_target"
+      member keyword: "reference_to",    context: "ReadModel", at: "",  named: "as",      kind: "symbol",   required: "false", fills: "reference_name"
+      member keyword: "include",         context: "ReadModel", at: "1", named: "",        kind: "constant", required: "true",  fills: "aggregate"
+      member keyword: "include",         context: "ReadModel", at: "",  named: "as",      kind: "symbol",   required: "false", fills: "as"
+      member keyword: "group_by",        context: "ReadModel", at: "1", named: "",        kind: "symbol",   required: "true",  fills: "group_by", variadic: "true"
+      member keyword: "median",          context: "ReadModel", at: "1", named: "",        kind: "symbol",   required: "true",  fills: "median_field"
+      member keyword: "where",           context: "ReadModel", at: "1", named: "",        kind: "pairs",    required: "true",  fills: ""
+      member keyword: "order_by",        context: "ReadModel", at: "1", named: "",        kind: "symbol",   required: "true",  fills: "field"
+      member keyword: "order_by",        context: "ReadModel", at: "2", named: "",        kind: "symbol",   required: "false", fills: "direction"
+      member keyword: "authorize",       context: "ReadModel", at: "1", named: "",        kind: "symbol",   required: "true",  fills: "policy"
+      member keyword: "authorize",       context: "ReadModel", at: "",  named: "tenant",  kind: "symbol",   required: "false", fills: "tenant"
+      member keyword: "inspect_query",   context: "ReadModel", at: "1", named: "",        kind: "symbol",   required: "false", fills: "mode"
+
+    end
+  end
+end