hecks 6.0.0 → 7.0.0

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

@@ -10,6 +10,8 @@ Hecks.bluebook "Bluebook" do
     attribute :name,          AggregateName
     attribute :description,   Description
     attribute :provenance,    LiteralText
+    attribute :formerly_known_as, AggregateFormerlyKnownAs, optional: true
+    attribute :created_by, AggregateCreatedBy, optional: true
     # Several paths, because the identity is their join in declared order: a command is named
     # by its aggregate and its own name.
     attribute :identified_by, list_of(IdentityPath)
@@ -42,6 +44,18 @@ Hecks.bluebook "Bluebook" do
       invariant("a description says something") { !value.to_s.empty? }
     end
 
+    # The aggregate's name before a rename; a rename keeps the old name resolving.
+    value_object "AggregateFormerlyKnownAs" do
+      attribute :value, String
+      invariant("an aggregate's formerly_known_as says something") { !value.to_s.empty? }
+    end
+
+    # The command that creates this aggregate's records, which a missing-record refusal names.
+    value_object "AggregateCreatedBy" do
+      attribute :value, String
+      invariant("an aggregate's created_by says something") { !value.to_s.empty? }
+    end
+
     value_object "IdentityField" do
       attribute :value, String
     end
@@ -115,6 +129,8 @@ Hecks.bluebook "Bluebook" do
       attribute :description,   Description, optional: true
       # LiteralText: rides the same `inspect` encoding as `default:`, so it needs no invariant.
       attribute :provenance,    LiteralText, optional: true
+      attribute :formerly_known_as, AggregateFormerlyKnownAs, optional: true
+      attribute :created_by, AggregateCreatedBy, optional: true
 
       attribute :position, Position, optional: true
 
@@ -122,6 +138,8 @@ Hecks.bluebook "Bluebook" do
       sets :name
       sets :description
       sets :provenance
+      sets :formerly_known_as
+      sets :created_by
       sets :position
       emits RootDeclared
     end
@@ -392,6 +410,8 @@ Hecks.bluebook "Bluebook" do
 
       member word: "description",     context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "description"
       member word: "provenance",      context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "provenance", calls: "provenance_impl"
+      member word: "formerly_known_as", context: "Aggregate", body: "none",   inner: "",              opens: "",               fills: "formerly_known_as", calls: "formerly_known_as_impl"
+      member word: "created_by", context: "Aggregate", body: "none",   inner: "",              opens: "",               fills: "created_by", calls: "created_by_impl"
       member word: "identified_by",   context: "Aggregate", body: "keywords", inner: "ValueObject",   opens: "ValueObject",    fills: "identified_by", calls: "identified_by_impl"
       member word: "identified_by",   context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "identified_by", calls: "identified_by_impl"
       member word: "reference_to",    context: "Aggregate", body: "none",     inner: "",              opens: "",               fills: "attributes", calls: "reference_to_impl"
@@ -437,6 +457,8 @@ Hecks.bluebook "Bluebook" do
 
       member keyword: "description",     context: "Aggregate", at: "1", named: "",         kind: "text",     required: "true",  fills: "description", coerce: "false"
       member keyword: "provenance",      context: "Aggregate", at: "",  named: "from",     kind: "literal",  required: "true",  fills: "provenance"
+      member keyword: "formerly_known_as", context: "Aggregate", at: "1", named: "",    kind: "text",     required: "true",  fills: "formerly_known_as"
+      member keyword: "created_by", context: "Aggregate", at: "1", named: "",    kind: "text",     required: "true",  fills: "created_by"
       member keyword: "identified_by",   context: "Aggregate", at: "1", named: "",         kind: "symbol",   required: "false", fills: "identified_by", variadic: "true", minimum: "2"
       member keyword: "identified_by",   context: "Aggregate", at: "1", named: "",         kind: "constant", required: "false", fills: "type"
       member keyword: "identified_by",   context: "Aggregate", at: "",  named: "as",       kind: "symbol",   required: "false", fills: "name"

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

@@ -41,6 +41,19 @@ Hecks.bluebook "Bluebook", version: "1" do
     # Capabilities this bluebook answers for other domains, one row per (capability, key, verb).
     # Absent is not empty: most bluebooks provide nothing.
     attribute :provides, list_of(Provision)
+    # The modules grouping this bluebook's aggregates by task (ADR 0163), one row per aggregate.
+    # Absent is not empty: most bluebooks group nothing.
+    attribute :modules, list_of(ModuleMembership)
+
+    value_object "ModuleMembership" do
+      attribute :name,      String
+      attribute :vision,    String
+      attribute :aggregate, String
+    end
+
+    value_object "ModuleText" do
+      attribute :value, String
+    end
 
     value_object "Provision" do
       attribute :capability, String
@@ -154,6 +167,21 @@ Hecks.bluebook "Bluebook", version: "1" do
       emits CapabilityProvided
     end
 
+    # One aggregate's place in a module: `domain_module "Deliver"` offers one row per aggregate its
+    # block declares, each carrying the module's vision.
+    command "Group" do
+      role "Language"
+      goal "Declare that an aggregate belongs to a module"
+
+      attribute :name,      ModuleText
+      attribute :vision,    ModuleText
+      attribute :aggregate, ModuleText
+
+      sets :modules, append: { name: :name, vision: :vision, aggregate: :aggregate }
+
+      emits AggregateGrouped
+    end
+
     # Reads a bluebook back out, not only in.
     # Named to finish a sentence: the bluebook CALLED "Pizzas".
     query "Called" do
@@ -206,6 +234,8 @@ Hecks.bluebook "Bluebook", version: "1" do
       member word: "policy",          context: "Bluebook", body: "keywords", inner: "Policy",         opens: "Policy",         fills: ""
       member word: "process_manager", context: "Bluebook", body: "keywords", inner: "ProcessManager", opens: "ProcessManager", fills: ""
 
+
+      member word: "domain_module", context: "Bluebook", body: "keywords", inner: "Bluebook", opens: "Bluebook", fills: ""
     end
 
     value_object "ArgumentSeed" do
@@ -254,6 +284,10 @@ Hecks.bluebook "Bluebook", version: "1" do
       member keyword: "provides", context: "Bluebook", at: "", named: "live_assignments", kind: "text", required: "false", fills: "provides"
 
       member keyword: "provides", context: "Bluebook", at: "", named: "live_transitions", kind: "text", required: "false", fills: "provides"
+
+      member keyword: "aggregate", context: "Bluebook", at: "", named: "kind", kind: "text", required: "false", fills: "kind"
+
+      member keyword: "domain_module", context: "Bluebook", at: "1", named: "", kind: "text", required: "true", fills: "name"
     end
   end
 end

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

@@ -16,6 +16,9 @@ Hecks.bluebook "Bluebook" do
     attribute :role,       Actor
     # Every role that may run the command, when more than one may; `role` is then the first.
     attribute :roles,      list_of(Permission)
+    # Who the command is listed for: person, agent, ci or record (ADR 0163). Empty lists it for
+    # a person and an agent; it decides what a launcher shows, never who may run the command.
+    attribute :audience,   list_of(Audience)
     attribute :goal,       Goal
     attribute :emits,      list_of(Announcement)
     attribute :references, EventName, optional: true
@@ -30,6 +33,9 @@ Hecks.bluebook "Bluebook" do
     # `idempotent`: delivering the command twice leaves the same state as delivering it once, so a
     # saga redrive may deliver it again after a crash that left its outcome unknown.
     attribute :idempotent, CommandText, optional: true
+    # `mints_era true`: this command's own record may be written through an unminted boot, so the
+    # command that mints the Hecks domain's held era can persist its request.
+    attribute :mints_era, CommandText, optional: true
     # Lifecycle guard as a literal (`from: "open"` or `from: ["open", "frozen"]`); ADR 0025.
     attribute :from,       CommandText, optional: true
 
@@ -60,6 +66,11 @@ Hecks.bluebook "Bluebook" do
       attribute :name, String
     end
 
+    # One audience the command is listed for, as a row of `audience`.
+    value_object "Audience" do
+      attribute :name, String
+    end
+
     value_object "Need" do
       attribute :fact, String
     end
@@ -118,6 +129,7 @@ Hecks.bluebook "Bluebook" do
       attribute :goal,  Goal, optional: true
       attribute :provenance, CommandText, optional: true
       attribute :idempotent, CommandText, optional: true
+      attribute :mints_era,  CommandText, optional: true
       attribute :from,       CommandText, optional: true
 
       attribute :position, Position, optional: true
@@ -128,6 +140,7 @@ Hecks.bluebook "Bluebook" do
       sets :goal
       sets :provenance
       sets :idempotent
+      sets :mints_era
       sets :from
       sets :position
       emits VerbDeclared
@@ -289,6 +302,23 @@ Hecks.bluebook "Bluebook" do
       attribute :value, String
     end
 
+    command "Address" do
+      role "Language"
+      goal "Name an audience this command is listed for"
+
+      attribute :addressed, AudienceName
+
+      given("an audience is named") { !addressed.value.to_s.empty? }
+
+      sets :audience, append: { name: :addressed }
+
+      emits AudienceAddressed
+    end
+
+    value_object "AudienceName" do
+      attribute :value, String
+    end
+
     command "Need" do
       role "Language"
       goal "Name an outside fact the runtime supplies before any given runs"
@@ -321,9 +351,13 @@ Hecks.bluebook "Bluebook" do
 
       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"
+      # Names who a launcher lists the command for (CommandBuilder#audience_impl; ADR 0163).
+      member word: "audience",        context: "Command", body: "none",   inner: "", opens: "", fills: "audience", calls: "audience_impl"
       member word: "provenance",      context: "Command", body: "none",   inner: "", opens: "", fills: "provenance", calls: "provenance_impl"
       # Declares the command safe to deliver twice (CommandBuilder#idempotent_impl).
       member word: "idempotent",      context: "Command", body: "none",   inner: "", opens: "", fills: "idempotent", calls: "idempotent_impl"
+      # Lets this command's own record through an unminted boot (CommandBuilder#mints_era_impl).
+      member word: "mints_era",       context: "Command", body: "none",   inner: "", opens: "", fills: "mints_era", calls: "mints_era_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"
@@ -364,6 +398,7 @@ Hecks.bluebook "Bluebook" do
 
       member keyword: "role",            context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "role", variadic: "true"
       member keyword: "goal",            context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "goal", coerce: "false"
+      member keyword: "audience",        context: "Command", at: "1", named: "",          kind: "symbol",   required: "true",  fills: "audience", variadic: "true"
       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"

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

@@ -11,6 +11,10 @@ Hecks.bluebook "Bluebook" do
     attribute :correlates_by, ProcessManagerText
     attribute :starts_on,     ProcessManagerText
     attribute :ends_on,       ProcessManagerText
+    # Every event that ends an instance, in declaration order; empty when only `ends_on` is declared.
+    attribute :endings,       list_of(ProcessManagerText), optional: true
+    # The command that resumes each stage, one `stage=command` entry per stage; empty when none is declared.
+    attribute :resumes,       list_of(ProcessManagerText), optional: true
     attribute :states,    list_of(SagaState)
     # Handler is a nested entity (below); list_of forward-references it.
     attribute :handlers,  list_of(Handler)
@@ -73,6 +77,8 @@ Hecks.bluebook "Bluebook" do
       attribute :starts_on,     ProcessManagerText
       # A procedure need not declare an ending; ProcessManagerBuilder defaults @ends_on to nil.
       attribute :ends_on,       ProcessManagerText, optional: true
+      attribute :endings,       list_of(ProcessManagerText), optional: true
+      attribute :resumes,       list_of(ProcessManagerText), optional: true
 
       attribute :position, Position, optional: true
       sets :bluebook
@@ -80,6 +86,8 @@ Hecks.bluebook "Bluebook" do
       sets :correlates_by
       sets :starts_on
       sets :ends_on
+      sets :endings
+      sets :resumes
       sets :position
       emits SagaDeclared
     end
@@ -207,11 +215,13 @@ Hecks.bluebook "Bluebook" do
       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"
+      # correlates_by takes a dotted path or a bare aggregate name, so it routes through a hand-written impl.
+      member word: "correlates_by",   context: "ProcessManager", body: "none",     inner: "",        opens: "",        fills: "", calls: "correlates_by_impl"
       # starts_on and ends_on accept a bare constant or text; they route through hand-written impls
       # because COERCE_BY_KIND has no "constant" entry and Naming.event_ref must resolve it.
       member word: "starts_on",       context: "ProcessManager", body: "none",     inner: "",        opens: "",        fills: "", calls: "starts_on_impl"
       member word: "ends_on",         context: "ProcessManager", body: "none",     inner: "",        opens: "",        fills: "", calls: "ends_on_impl"
+      member word: "resumes",         context: "ProcessManager", body: "none",     inner: "",        opens: "",        fills: "", calls: "resumes_impl"
       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"
       # Two rows per dispatch: one with a block (opening `compensates`), one without.
@@ -239,10 +249,13 @@ Hecks.bluebook "Bluebook" do
       attribute :blank_message,    String
 
       member keyword: "correlates_by",   context: "ProcessManager", at: "1", named: "",           kind: "symbol", required: "true", fills: "correlates_by"
+      # A bare aggregate name (`correlates_by Message`), which the bluebook resolves to its identity.
+      member keyword: "correlates_by",   context: "ProcessManager", at: "1", named: "",           kind: "constant", required: "true", fills: "correlates_by"
       member keyword: "starts_on",       context: "ProcessManager", at: "1", named: "",           kind: "constant", required: "true", fills: "starts_on"
       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: "constant", required: "true", fills: "ends_on"
       member keyword: "ends_on",         context: "ProcessManager", at: "1", named: "",           kind: "text",   required: "true", fills: "ends_on"
+      member keyword: "resumes",         context: "ProcessManager", at: "1", named: "",           kind: "text",   required: "true", fills: "resumes"
       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"