hecks 2.8.0 → 2.9.0

data/lib/hecks/bluebook/chapter.rb

@@ -4,30 +4,14 @@ require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # The chapter, which is not the namespace it lives in.
-    #
-    # `Hecks::Bluebook` was briefly a class, because dropping the
-    # old `IR::` segment would otherwise have produced
-    # `Bluebook::Bluebook` — a class shadowing its own enclosing module.
-    # Naming the construct what the code already called it everywhere
-    # (a chapter; this file was already chapter.rb) removes the clash
-    # at the source, so the namespace goes back to being a module.
-    #
-    # Measured before changing: `Bluebook` was used as a class in five
-    # places and as a namespace in seventy-seven files.
+    # The chapter, distinct from the `Bluebook` namespace it lives in.
     class Chapter
       include Construct
       include Behaviour::Chapter
       include Hecks::IR
 
-      # **The schema's own version** — not a domain's `version:` (Banking's
-      # "v1", a business fact the author chose), but the shape `to_h`
-      # itself emits. A consumer reading exported IR with no Ruby DSL to
-      # cross-check against (a build-time generator, a stored snapshot)
-      # needs to know which shape it's holding before it can safely
-      # interpret any of the rest of it. Bump this when `to_h`'s own
-      # shape changes in a way a consumer would need to know about —
-      # not when a domain's own declarations change.
+      # The IR shape's own version — bump only when `to_h`'s shape changes,
+      # not when a domain's declared `version:` does.
       IR_VERSION = 1
 
       emits_ir(
@@ -36,32 +20,23 @@ module Hecks
         version:           :version,
         vision:            :vision,
         classification:    :classification,
-        # M10 — a domain rename (`formerly_known_as "OldName"`) drives a
-        # real Postgres schema rename at boot (EraResolver reads
-        # `bluebook.formerly_known_as` off the live Ruby object) and the
-        # meta-validator's cache key is `SHA256(JSON(bluebook.to_h))` — so
-        # a fact this method didn't spell was a fact two chapters
-        # differing only by their old name could hash identically on,
-        # same as read-model filters before them. Spelled here for the
-        # same reason `version`/`vision` are: a plain field, present
-        # (possibly nil) rather than silently absent.
+        # Present (possibly nil) rather than silently absent, so two chapters
+        # differing only by their old name can't hash identically at the
+        # meta-validator's cache key (`SHA256(JSON(bluebook.to_h))`).
         formerly_known_as: :formerly_known_as,
         aggregates:        many(:aggregates),
         read_models:       many(:read_models),
         policies:          many(:policies),
         process_managers:  many(:process_managers),
         attaches_to:       :attaches_to,
-        # A capability this chapter answers (`provides "authorization",
-        # grant: "RoleAssignment.Assign", ...`), one row per key, in the
-        # order written. Present (possibly empty) on every chapter, the
-        # same reading `attaches_to` beside it gives.
+        # One row per declared `provides` capability, in declaration order;
+        # present (possibly empty) like `attaches_to`.
         provides:          -> { provides.map(&:to_h) },
         canonical_form:    -> { Expression::CanonicalForm.table }
       )
 
-      # **One row of a declared capability** — `verb` is chapter-local
-      # ("RoleAssignment.Assign"); `Behaviour::Chapter#provided_verb`
-      # qualifies it with the chapter's own name.
+      # One row of a declared capability — `verb` is chapter-local;
+      # `Behaviour::Chapter#provided_verb` qualifies it with the chapter's own name.
       Provision = Struct.new(:capability, :key, :verb, keyword_init: true) do
         # Coerces one declared or reconstructed `provides` row into a `Provision`.
         #
@@ -80,23 +55,10 @@ module Hecks
       attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,
                   :classification, :read_models, :ports, :formerly_known_as, :attaches_to, :provides
 
-      # @param name [String, Symbol] the chapter's declared name
-      # @param version [String, Symbol, nil] the chapter's declared business version,
-      #   such as `"v1"`, or `nil` if it declares none
-      # @param vision [String, nil] the chapter's declared vision statement
-      # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
       # @param policies [Array<Bluebook::Policy>] every reaction declared across the
       #   chapter's own aggregates, hoisted here
-      # @param process_managers [Array<Bluebook::ProcessManager>] the chapter's declared
-      #   process managers
       # @param classification [String, Symbol, nil] whether this chapter is central to
       #   its project's own domain model, or `nil` if undeclared
-      # @param read_models [Array<Bluebook::ReadModel>] the chapter's declared read models
-      # @param formerly_known_as [String, Symbol, nil] an earlier name this domain was
-      #   known under, or `nil` if it was never renamed
-      # @param attaches_to [Array<String, Symbol>] the contexts this chapter attaches to
-      # @param provides [Array<Bluebook::Chapter::Provision, Hash>] the capabilities this
-      #   chapter declares it provides
       def initialize(name:, version: nil, vision: nil, aggregates: [], policies: [],
                      process_managers: [], classification: nil, read_models: [], formerly_known_as: nil,
                      attaches_to: [], provides: [])

data/lib/hecks/bluebook/command.rb

@@ -10,19 +10,8 @@ module Hecks
       include Hecks::IR
       include Behaviour::Mutation
 
-      # `sign:` — item #5 of the whole-project table-unification survey:
-      # `increment`/`decrement`'s own +1/-1 comes from `Vocabulary::MutationOp`
-      # here, the same table `Runtime::CommandRules::Arithmetic::MUTATION_OPS`
-      # already reads on the Ruby runtime side, rather than a ternary on the op
-      # name re-deriving it independently in each of two Rust codegen scripts
-      # (rust/project/mutations.rb, rust/codegen/src/mutations.rs).
-      # Reads `Vocabulary::MutationOp` directly (plain data, no framework
-      # dependency — safe during parsing, same reason `RuleReference`'s
-      # own bootstrap concerns don't apply here) rather than requiring
-      # Runtime::CommandRules from the bluebook/IR layer, which would be a
-      # real layering inversion (runtime depends on bluebook, not the
-      # reverse). "" (not nil) for ops with no sign, matching every other
-      # optional IR text field's own absent-is-empty-string convention.
+      # Reads `Vocabulary::MutationOp` directly: runtime depends on bluebook, not the reverse.
+      # Answers "" rather than nil, like every optional IR text field.
       #
       # @param oper [String, Symbol] the mutation's operation name, such as
       #   `"increment"` or `"decrement"`
@@ -34,14 +23,9 @@ module Hecks
 
       emits_ir(target: :target, op: :op, sign: -> { Mutation.sign_for(op) })
 
-      # The one genuinely branching emission in the model: an append (or a
-      # delegate — `CommandBuilder#delegates_to`'s own comment gives the
-      # full reasoning for reusing this exact wire shape rather than
-      # inventing a parallel one) binds several fields at once and carries
-      # `fields:`, everything else carries a single `source:`. Declared
-      # emission covers the fixed head; `super` supplies it and this adds
-      # the tail, which is why a construct with a variable shape needs no
-      # new mixin API.
+      # An append, delegate or correction binds several fields and carries `fields:`;
+      # every other op carries a single `source:`.
+      #
       # @return [Hash{Symbol => Object}] the declared emission — `super`'s fixed
       #   head, plus `fields:` (a Hash of bound field values) for an
       #   append-shaped op, or `source:` (`classified_source`'s own result) for
@@ -53,24 +37,10 @@ module Hecks
       end
     end
 
-    # A command, as a Ruby class.
-    #
-    # Not nested as a constant, and that is a finding rather than a shortcut. A
-    # command and a value object may legitimately share a name inside one
-    # aggregate — the language does it six times, and means it: the command
-    # `Argument` is the verb that appends to the `arguments` list whose element
-    # type is the value object `Argument`, and `Plan` reads exactly that pairing.
-    # So `Bluebook::Command::Argument` cannot be both, and a single constant
-    # namespace cannot index a kind-ambiguous name. The same follows for
-    # `hecks_fqn` : `Bluebook::Command.Argument` names both, which is why the judge's
-    # ids only work per-category, each in its own repository. Identity is
-    # (kind, FQN), not fqn.
+    # A declared command, minted as its own anonymous class.
     #
-    # It is a declaration holder anyway, because that is where the edges live.
-    # `acts_on` answers with the owning construct itself — the Aggregate,
-    # or the entity holder for a piece's verb — rather than the name of one.
-    # The invocation door (`pizza.add_topping`) is the facade's business, a
-    # per-boot projection ; no verb method is defined here.
+    # Not a nested constant: a command and a value object may share a name in one aggregate,
+    # so identity is (kind, FQN), not the name alone.
     class Command
       extend Construct
       extend Hecks::IR
@@ -86,14 +56,7 @@ module Hecks
         ensures:    -> { ensures.map { |rule| Expression::AstJson.rule_row(rule) } },
         mutations:  many(:mutations),
         emits:      :emits,
-        # The lifecycle state this command is admissible from (S10, ADR
-        # 0025 — "lifecycle state becomes a command guard") — a guard,
-        # not a transition: `command "Debit", from: "open"` replaces
-        # `given("account is open") { status == "open" }`, checked
-        # against the owning construct's own lifecycle field the same
-        # way `admissible_transition` already checks a real state
-        # change, but names no target state and moves nothing. Nil for
-        # a command with no such guard — most commands.
+        # The lifecycle state this command is admissible from: a guard, not a transition.
         from:       -> { from },
         provenance: :provenance
       )
@@ -102,29 +65,18 @@ module Hecks
         attr_reader :role, :goal, :attributes, :givens, :ensures, :mutations, :emits, :references,
                     :from, :provenance
 
-        # Mints one command as its own anonymous class, a subclass of whichever
-        # `Command`-descended class `declare` is called on.
+        # Mints one command as its own anonymous subclass of the class `declare` is called on.
         #
         # @param name [String, Symbol] the command's declared name
-        # @param role [String, nil] the command's declared role text
-        # @param goal [String, nil] the command's declared goal text
-        # @param attributes [Array<Bluebook::Attribute>] the command's declared
-        #   arguments
-        # @param givens [Array<Bluebook::Given>] the command's declared
-        #   preconditions
-        # @param ensures [Array<Bluebook::Given>] the command's declared
-        #   postconditions
-        # @param mutations [Array<Bluebook::Mutation>] the state changes this
-        #   command applies
-        # @param emits [Array<String>] the event names this command may emit
-        # @param references [String, Symbol, nil] the aggregate name this verb's
-        #   `reference_to` addresses, or `nil` for a verb declared on the
-        #   aggregate it acts on
-        # @param from [String, Array<String>, nil] the lifecycle state(s) this
-        #   command is admissible from, or `nil` for no such guard
-        # @param provenance [Object, nil] the command's declared canonical
-        #   source, captured exactly as written, or `nil` if it declares none
-        # @return [Class] the new command class
+        # @param role [String, nil] the declared role text; `goal` is the goal text
+        # @param attributes [Array<Bluebook::Attribute>] the declared arguments
+        # @param givens [Array<Bluebook::Given>] the declared preconditions
+        # @param ensures [Array<Bluebook::Given>] the declared postconditions
+        # @param mutations [Array<Bluebook::Mutation>] the state changes it applies
+        # @param emits [Array<String>] the event names it may emit
+        # @param references [String, Symbol, nil] the aggregate its `reference_to` addresses
+        # @param from [String, Array<String>, nil] the lifecycle states it is admissible from
+        # @param provenance [Object, nil] the declared canonical source, as written
         def declare(name:, role: nil, goal: nil, attributes: [], givens: [], ensures: [],
                     mutations: [], emits: [], references: nil, from: nil, provenance: nil)
           verb = Class.new(self)
@@ -135,21 +87,11 @@ module Hecks
           verb
         end
 
-        # Assigns what the language declares, then hands off to the behaviour's
-        # own `settle` — indexing attributes, the one thing not derivable from
-        # the declaration.
+        # Assigns what the language declares, then `settle` indexes the attributes.
+        #
+        # Takes the keywords `declare` takes, minus `name`.
         #
-        # @param role [String, nil] see `declare`
-        # @param goal [String, nil] see `declare`
-        # @param attributes [Array<Bluebook::Attribute>] see `declare`
-        # @param givens [Array<Bluebook::Given>] see `declare`
-        # @param ensures [Array<Bluebook::Given>] see `declare`
-        # @param mutations [Array<Bluebook::Mutation>] see `declare`
-        # @param emits [Array<String>] see `declare`
-        # @param references [String, nil] see `declare`
-        # @param from [String, Array<String>, nil] see `declare`
-        # @param provenance [Object, nil] see `declare`
-        # @return [Class] self, once attributes are indexed
+        # @return [Class] self
         def absorb(role:, goal:, attributes:, givens:, ensures:, mutations:, emits:, references:,
                    from: nil, provenance: nil)
           @role       = role

data/lib/hecks/bluebook/domain_port.rb

@@ -2,17 +2,9 @@ require_relative "behaviour/domain_port"
 
 module Hecks
   module Bluebook
-    # The primary/driving half of hexagonal architecture (Cockburn) — called
-    # by an adapter living outside the bluebook entirely, never by the
-    # domain calling out. That is already `Hecks.port` (persistence,
-    # projection, extraction, loading) plus `Ports::*` : the secondary/
-    # driven half, unchanged by this.
+    # One operation on a driving port: an external call turned into an event in this domain.
     #
-    # An operation carries no `given`/`ensures`/`then_set` — a port is the
-    # anti-corruption boundary that turns an external call into a fact in
-    # this domain's own vocabulary, not a second place business rules live.
-    # Those stay on whatever command a `policy` triggers in reaction to the
-    # event an operation emits.
+    # Carries no `given`/`ensures`/`then_set`; those stay on the command a `policy` triggers.
     class PortOperation
       include Hecks::IR
       include Behaviour::PortOperation
@@ -21,31 +13,17 @@ module Hecks
 
       attr_reader :hecks_name, :attributes, :emits, :direction, :answers, :refuses, :to
 
-      # Two directions through one door.
-      #
-      # `:inbound` is what this class has always been — `tells`, spelled
-      # `operation` before it had a twin: an external fact arriving, turned
-      # into this domain's own event. It emits and that is all; there is no
-      # channel back to whoever called.
-      #
-      # `:outbound` is `asks` — the domain wanting something from outside
-      # and having to live with either answer. It names both: `answers` for
-      # what the adapter came back with, `refuses` for what it said instead.
-      # Naming only the happy one would put the failure somewhere the model
-      # cannot see, which is the whole reason a boundary is worth modelling.
+      # `:inbound` (`tells`) is an external fact arriving as an event; it emits and nothing more.
+      # `:outbound` (`asks`) is the domain wanting something from outside, naming both
+      # `answers` and `refuses` so the failure is visible to the model.
       #
       # @param name [String, Symbol] the operation's declared name
-      # @param attributes [Array<Bluebook::Attribute>] the operation's declared payload
-      #   fields
-      # @param emits [Array<String>] the events an inbound operation declares it records
-      # @param direction [Symbol, String] `:inbound` for a `tells`/`operation`, `:outbound`
-      #   for an `asks`
-      # @param answers [String, nil] an outbound operation's declared event for what the
-      #   adapter came back with
-      # @param refuses [String, nil] an outbound operation's declared event for what the
-      #   adapter said instead
-      # @param to [String, nil] the aggregate this operation routes to, or `nil` if it
-      #   declares no routing target
+      # @param attributes [Array<Bluebook::Attribute>] the declared payload fields
+      # @param emits [Array<String>] the events an inbound operation records
+      # @param direction [Symbol, String] `:inbound` or `:outbound`
+      # @param answers [String, nil] an outbound operation's event for the adapter's answer
+      # @param refuses [String, nil] an outbound operation's event for the adapter's refusal
+      # @param to [String, nil] the aggregate this operation routes to, if any
       def initialize(name:, attributes: [], emits: [], direction: :inbound, answers: nil, refuses: nil, to: nil)
         @hecks_name = name.to_s
         @attributes = attributes
@@ -67,31 +45,8 @@ module Hecks
       # @return [Boolean] whether this operation is a `tells`/`operation`
       def inbound?  = @direction == :inbound
 
-      # No root reference of its own — unlike a command, every attribute
-      # equally describes the payload, including whichever one identifies
-      # the record its emitted event belongs to. Kept only so
-      # CommandInterpreter::ArgumentGate's `reference_key` can ask for it
-      # without learning this isn't a command.
-
-      # `direction`/`answers`/`refuses` are deliberately outside `emits_ir`'s
-      # declared shape and added here only for an outbound operation — an
-      # ordinary inbound one (`tells`, still spelled `operation` everywhere
-      # in the existing corpus) keeps the exact prior IR shape, byte for
-      # byte. Pizzas' `PaymentGateway` port is inbound-only and is checked
-      # against `hecks-parse`'s own Rust output for byte-identity
-      # (parser_parity_spec.rb) — the Rust side has no notion of `asks` yet,
-      # so an unconditional new key here would break that parity for a
-      # domain that never asked for the feature. Only a chapter that
-      # actually declares `asks` (this extraction's own QualityControl
-      # ledger, not yet in any Rust-parity corpus) pays for it.
-      # `to` — same "deliberately outside emits_ir, merged in only when
-      # present" treatment as direction/answers/refuses just above, and
-      # for the identical reason: an operation still spelled the old way
-      # (`reference_to` inside the block, shadow-parsing only — see
-      # reference_to_impl's own comment) or one that simply hasn't
-      # migrated yet keeps the exact prior IR shape, byte for byte,
-      # instead of an unconditional new key breaking parser_parity_spec
-      # for every domain that never touched this.
+      # `direction`/`answers`/`refuses`/`to` are merged in only when set: the Rust parser
+      # emits none of them, so an unconditional key would break parser_parity_spec.
       #
       # @return [Hash] the declared emission, plus `direction`/`answers`/`refuses` for an
       #   outbound operation and `to` when a routing target is declared
@@ -103,11 +58,7 @@ module Hecks
       end
     end
 
-    # A named group of operations an aggregate (or, later, a chapter)
-    # exposes to whatever adapter calls in — the contract that today lives
-    # only as a bare `verb`/`signal` pair in a standalone `.port` file.
-    # Superseding those is the goal ; for now they keep working untouched,
-    # and this is additive.
+    # A named group of operations an aggregate exposes to whatever adapter calls in.
     class DomainPort
       include Hecks::IR
       include Behaviour::DomainPort