hecks 0.2.0 → 0.3.0

data/lib/hecks/language/translation/translation_aggregate.bluebook

@@ -0,0 +1,267 @@
+Hecks.bluebook "Translation" do
+  aggregate "TranslationAggregate" do
+    description "One aggregate's own move from one pinned era to the next — a table of rules, or a deliberate acknowledgment that a rule is still unresolved."
+
+    belongs_to Translation, as: :translation_ref
+
+    identified_by TranslationAggregateName, as: :name
+
+    # `TranslationAggregateName` — a DEDICATED type for the identity
+    # field, not the shared `TranslationName` every non-identity field
+    # below uses. Found live, not by inspection: reusing one value-
+    # object type for BOTH an aggregate's own identity field and a
+    # sibling non-identity field on the same aggregate broke the
+    # single-field-VO identity-unwrap path — the stored `id` came back
+    # as a stringified Hash (`"{:value=>\"Account\"}"`) instead of the
+    # bare scalar (`"Account"`), so a self-reference to this aggregate
+    # could never find the record `Declare` had just created. Reusing
+    # the SAME type across MULTIPLE identity fields (Translation's own
+    # `TranslationEraName`, for both `from` and `to`) is unaffected —
+    # confirmed directly, not assumed — so the real trigger is identity
+    # + non-identity sharing, not reuse itself. A genuine framework bug,
+    # out of scope to fix here; every other self-hosted construct in
+    # this language already avoids it by convention (a dedicated type
+    # per identity field), which this now matches too.
+    attribute :was,  TranslationName, optional: true
+
+    value_object "TranslationAggregateName" do
+      attribute :value, String
+      invariant("a translation aggregate names itself") { !value.to_s.empty? }
+    end
+
+    # The parent arrives as an ordinary value fact at declaration time. Its
+    # fields mirror Translation's compound identity, while `translation_ref`
+    # above retains the resulting canonical identity as a structural edge.
+    value_object "TranslationIdentity" do
+      attribute :domain, TranslationDomainName
+      attribute :from,   TranslationEraName
+      attribute :to,     TranslationEraName
+    end
+
+    attribute :renames,   list_of(TranslationRename)
+    attribute :moves,     list_of(TranslationMove)
+    attribute :converts,  list_of(TranslationConvert)
+    attribute :drops,     list_of(TranslationName)
+    attribute :retypes,   list_of(TranslationRetype)
+    attribute :computes,  list_of(TranslationCompute)
+    attribute :rekeys,    list_of(TranslationRekey)
+    attribute :backfills, list_of(TranslationBackfill)
+
+    # Field names throughout mirror lib/hecks/bluebook/translation.rb
+    # EXACTLY (`Struct.new(:from, :to)` etc.) — the real Ruby records
+    # TranslationJudge dispatches from, not the builder's own local
+    # parameter names (`move(old_path, to:)`'s `old_path` becomes the
+    # struct's own `from`).
+    value_object "TranslationRename" do
+      attribute :from, TranslationName
+      attribute :to,   TranslationName
+    end
+
+    value_object "TranslationMove" do
+      attribute :from, TranslationName
+      attribute :to,   TranslationName
+    end
+
+    value_object "TranslationConvert" do
+      attribute :from,   TranslationName
+      attribute :to,     TranslationName
+      attribute :values, TranslationLiteralText
+    end
+
+    value_object "TranslationRetype" do
+      attribute :from, TranslationName
+      attribute :to,   TranslationName
+    end
+
+    value_object "TranslationCompute" do
+      attribute :from, TranslationName
+      attribute :to,   TranslationName
+      attribute :sql,  TranslationLiteralText
+    end
+
+    value_object "TranslationRekey" do
+      attribute :sql, TranslationLiteralText
+    end
+
+    value_object "TranslationBackfill" do
+      attribute :name,    TranslationName
+      attribute :default, TranslationLiteralText
+    end
+
+    command "Declare" do
+      role "Deployment"
+      goal "Open one aggregate's own move from one pinned era to the next"
+
+      attribute :translation_ref, TranslationIdentity
+      attribute :name, TranslationAggregateName
+      attribute :was,  TranslationName, optional: true
+
+      sets :translation_ref
+      sets :name
+      sets :was
+
+      emits "TranslationAggregateDeclared"
+    end
+
+    command "AddRename" do
+      role "Deployment"
+      goal "Move data at an old field name to its new one, unchanged"
+
+      attribute :from, TranslationName
+      attribute :to,   TranslationName
+
+      sets :renames, append: { from: :from, to: :to }
+
+      emits "TranslationRenameAdded"
+    end
+
+    command "AddMove" do
+      role "Deployment"
+      goal "Move data at an old path to a new one, unchanged"
+
+      attribute :from, TranslationName
+      attribute :to,   TranslationName
+
+      sets :moves, append: { from: :from, to: :to }
+
+      emits "TranslationMoveAdded"
+    end
+
+    command "AddConvert" do
+      role "Deployment"
+      goal "Move data at an old path to a new one, translating its own values through an exhaustive table"
+
+      attribute :from,   TranslationName
+      attribute :to,     TranslationName
+      attribute :values, TranslationLiteralText
+
+      sets :converts, append: { from: :from, to: :to, values: :values }
+
+      emits "TranslationConvertAdded"
+    end
+
+    command "AddDrop" do
+      role "Deployment"
+      goal "Acknowledge, deliberately, that a field's own data does not survive"
+
+      attribute :value, TranslationName
+
+      sets :drops, append: { value: :value }
+
+      emits "TranslationDropAdded"
+    end
+
+    command "AddRetype" do
+      role "Deployment"
+      goal "Declare that an old type name and a new one mean the same shape"
+
+      attribute :from, TranslationName
+      attribute :to,   TranslationName
+
+      sets :retypes, append: { from: :from, to: :to }
+
+      emits "TranslationRetypeAdded"
+    end
+
+    command "AddCompute" do
+      role "Deployment"
+      goal "Move data at an old path to a new one, transformed by a real SQL expression"
+
+      attribute :from, TranslationName
+      attribute :to,   TranslationName
+      attribute :sql,  TranslationLiteralText
+
+      sets :computes, append: { from: :from, to: :to, sql: :sql }
+
+      emits "TranslationComputeAdded"
+    end
+
+    command "AddRekey" do
+      role "Deployment"
+      goal "Recompute this aggregate's own identity by a real SQL expression"
+
+      attribute :sql, TranslationLiteralText
+
+      sets :rekeys, append: { sql: :sql }
+
+      emits "TranslationRekeyAdded"
+    end
+
+    command "AddBackfill" do
+      role "Deployment"
+      goal "Name a newly required attribute and the value an existing record reads until written for real"
+
+      attribute :name,    TranslationName
+      attribute :default, TranslationLiteralText
+
+      sets :backfills, append: { name: :name, default: :default }
+
+      emits "TranslationBackfillAdded"
+    end
+
+    # HOW TRANSLATIONAGGREGATE IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: TranslationAggregate.
+    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: "rename",          context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "renames", calls: "rename_impl"
+      member word: "move",            context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "moves", calls: "move_impl"
+      member word: "convert",         context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "converts", calls: "convert_impl"
+      member word: "drop",            context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "drops"
+      member word: "retype",          context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "retypes", calls: "retype_impl"
+      member word: "compute",         context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "computes", calls: "compute_impl"
+      member word: "rekey",           context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "rekeys", calls: "rekey_impl"
+      member word: "backfill",        context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "backfills", calls: "backfill_impl"
+      member word: "unresolved",      context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "", calls: "unresolved_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: "rename",          context: "TranslationAggregate", at: "1", named: "", kind: "symbol", required: "true", fills: "old_name"
+      member keyword: "rename",          context: "TranslationAggregate", at: "",  named: "to", kind: "symbol", required: "true", fills: "to"
+      member keyword: "move",            context: "TranslationAggregate", at: "1", named: "", kind: "text", required: "true", fills: "old_path"
+      member keyword: "move",            context: "TranslationAggregate", at: "",  named: "to", kind: "text", required: "true", fills: "to"
+      member keyword: "convert",         context: "TranslationAggregate", at: "1", named: "", kind: "text", required: "true", fills: "old_path"
+      member keyword: "convert",         context: "TranslationAggregate", at: "",  named: "to",      kind: "text",    required: "true", fills: "to"
+      member keyword: "convert",         context: "TranslationAggregate", at: "",  named: "values",  kind: "literal", required: "true", fills: "values"
+      member keyword: "drop",            context: "TranslationAggregate", at: "1", named: "",       kind: "symbol",  required: "true", fills: "name", blank_message: "a drop needs a name"
+      member keyword: "retype",          context: "TranslationAggregate", at: "1", named: "",       kind: "text",    required: "true", fills: "old_type"
+      member keyword: "retype",          context: "TranslationAggregate", at: "",  named: "to", kind: "text", required: "true", fills: "to"
+      member keyword: "compute",         context: "TranslationAggregate", at: "1", named: "", kind: "text", required: "true", fills: "old_path"
+      member keyword: "compute",         context: "TranslationAggregate", at: "",  named: "to",      kind: "text",    required: "true", fills: "to"
+      member keyword: "compute",         context: "TranslationAggregate", at: "",  named: "sql",     kind: "text",    required: "true", fills: "sql"
+      member keyword: "rekey",           context: "TranslationAggregate", at: "",  named: "sql",     kind: "text",    required: "true", fills: "sql"
+      member keyword: "backfill",        context: "TranslationAggregate", at: "1", named: "", kind: "symbol", required: "true", fills: "name"
+      member keyword: "backfill",        context: "TranslationAggregate", at: "",  named: "default", kind: "literal", required: "true", fills: "default"
+      member keyword: "unresolved",      context: "TranslationAggregate", at: "1", named: "", kind: "symbol", required: "true", fills: "name"
+      member keyword: "unresolved",      context: "TranslationAggregate", at: "",  named: "candidates", kind: "list", required: "false", fills: "candidates"
+
+    end
+  end
+end

data/lib/hecks/language/world/wiring.bluebook

@@ -0,0 +1,62 @@
+Hecks.bluebook "World" do
+  aggregate "Wiring" do
+    description "One adapter binding inside a world — the verb it answers, the adapter it names, and the values that adapter needs. Its own root because a world's settings are an open map, which no value object can hold."
+
+    # `as:` is required here — Wiring ALSO holds an ordinary `world` text
+    # attribute below (the same string, but a value rather than a reference),
+    # so the bare reference name would collide with it.
+    belongs_to World, as: :world_ref
+
+    # THE WORLD IT IS IN, AND THE VERB IT ANSWERS. One world binds one adapter per
+    # verb — that is what a binding IS — so the verb names the wiring, and the
+    # world says whose.
+    identified_by :world, :verb
+
+    attribute :world,    WiringText
+    attribute :verb,     WiringText
+    attribute :adapter,  WiringText
+    attribute :settings, list_of(Setting)
+
+    value_object "WiringText" do
+      attribute :value, String
+    end
+
+    value_object "Setting" do
+      attribute :key,   String
+      attribute :value, String
+    end
+
+    command "Declare" do
+      role "Deployment"
+      goal "Bind one adapter in a world"
+
+      attribute :world_ref, WorldName
+      attribute :world,   WiringText
+      attribute :verb,    WiringText
+      attribute :adapter, WiringText
+
+      given("a wiring names its verb") { !verb.value.to_s.empty? }
+
+      sets :world_ref
+      sets :world
+      sets :verb
+      sets :adapter
+
+      emits "WiringDeclared"
+    end
+
+    command "Set" do
+      role "Deployment"
+      goal "Give one value the bound adapter needs"
+
+      attribute :key,   WiringText
+      attribute :value, WiringText
+
+      given("a setting names its key") { !key.value.to_s.empty? }
+
+      sets :settings, append: { key: :key, value: :value }
+
+      emits "SettingGiven"
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+Hecks.bluebook "World" do
+  aggregate "World" do
+    description "One .world — the per-deployment values a domain's adapters need. A sibling artifact to the bluebook, not part of it : the same domain runs in many worlds."
+
+    identified_by WorldName, as: :domain
+
+    attribute :realm,  Realm
+    attribute :latest, Latest
+
+    value_object "WorldName" do
+      attribute :value, String
+      invariant("a world names its domain") { !value.to_s.empty? }
+    end
+
+    value_object "Realm" do
+      attribute :value, String
+      invariant("a realm says something") { !value.to_s.empty? }
+    end
+
+    value_object "Latest" do
+      attribute :value, String
+      invariant("a latest version says something") { !value.to_s.empty? }
+    end
+
+    command "Declare" do
+      role "Deployment"
+      goal "Open a world for a domain"
+
+      attribute :domain, WorldName
+      attribute :realm,  Realm, optional: true
+      attribute :latest, Latest, optional: true
+
+      sets :domain
+      sets :realm
+      sets :latest
+
+      emits "WorldDeclared"
+    end
+
+    # HOW WORLD IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: File, World.
+    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: "world",           context: "File",     body: "keywords", inner: "World",          opens: "World",          fills: ""
+      member word: "realm",           context: "World",     body: "none", inner: "", opens: "", fills: "realm", calls: "realm_impl"
+      member word: "latest",          context: "World",     body: "none", inner: "", opens: "", fills: "latest", calls: "latest_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: "world",           context: "File", at: "1", named: "", kind: "text", required: "true", fills: "domain"
+      member keyword: "realm",           context: "World", at: "1", named: "", kind: "text", required: "true", fills: "realm"
+      member keyword: "latest",          context: "World", at: "1", named: "", kind: "text", required: "true", fills: "latest"
+
+    end
+  end
+end

data/lib/hecks/literal.rb

@@ -0,0 +1,125 @@
+module Hecks
+  # THE ONE SPELLING FOR A CAPTURED RUBY LITERAL ON THE WIRE.
+  #
+  # Several `to_h` fields hold a value the author wrote in a bluebook —
+  # `where(status: { eq: "open" })`, `then_set append: { direction: { value:
+  # "credit" } }`, `dispatch ... with: { number: :source }`, an attribute's
+  # `default:` — as TEXT, because the export has to stand on its own and a
+  # String field cannot say "this one was a Symbol". Every such field is the
+  # same question and now gets the same answer.
+  #
+  # It was three answers before, and they disagreed on both axes that matter.
+  # `Mutation#appended_fields` spelled a Symbol BARE and everything else
+  # `inspect`; `QuerySpecification.render_value` spelled a Symbol with a COLON
+  # and everything else `to_s`. So `:amount` crossed as "amount" in a mutation
+  # and ":amount" in a saga binding — the same value, two spellings, and each
+  # reader had to know which field it was looking at. Worse, `to_s`/`inspect`
+  # on a Hash is Ruby's OWN rendering, which moved under us: 3.3 writes
+  # `{:value=>"credit"}` and 3.4 writes `{value: "credit"}` for the identical
+  # Hash, so the wire format was silently pinned to an interpreter version.
+  #
+  # SELF-DESCRIBING IS THE RULE, stated once here rather than inherited from
+  # whatever `inspect` happens to do: a symbol wears its colon, a string wears
+  # its quotes, a hash wears `{key: value}` braces, a list wears its brackets,
+  # and a number, a boolean and nil are bare. `read` is the exact inverse, and
+  # is the only thing that should ever take one of these strings apart.
+  # A MUTATION SOURCE THAT READS THE RECORD'S OWN STATE — `sets :positions,
+  # append: { knights: state(:knights) }`. A bare Symbol in a mutation
+  # source always names a command ARGUMENT (and imports it as one when
+  # the target's own field carries the same name — `CommandBuilder
+  # #resolve_append_fields!`); before this there was no way to say "the
+  # value this field already holds", so a command could not snapshot its
+  # own record — chess's threefold repetition needs exactly that, a
+  # position copied off the board every ply. Spelled `state(:name)` on
+  # the wire, read back by `Literal.read`; classified `kind: "state"` in
+  # a set's own source (`Behaviour::Mutation#classified_source`).
+  StateRef = Struct.new(:name) do
+    def to_s = "state(:#{name})"
+  end
+
+  module Literal
+    module_function
+
+    def render(value)
+      case value
+      when nil            then "nil"
+      when StateRef       then value.to_s
+      when true, false    then value.to_s
+      when Symbol         then ":#{value}"
+      when Integer, Float then value.to_s
+      when String         then quote(value)
+      when Hash           then "{#{value.map { |key, held| "#{key}: #{render(held)}" }.join(', ')}}"
+      when Array          then "[#{value.map { |held| render(held) }.join(', ')}]"
+      else
+        raise ArgumentError, "#{value.class} has no pinned literal spelling — teach Literal.render one " \
+                             "rather than letting #to_s decide it"
+      end
+    end
+
+    # Read one back. Tolerant of a bare word on purpose: the language stores a
+    # closed set's members and a few hand-written fields as plain text that was
+    # never rendered, and those must stay the strings they are.
+    def read(text)
+      raw = text.to_s.strip
+      return nil if raw.empty? || raw == "nil"
+      return true if raw == "true"
+      return false if raw == "false"
+      return raw.to_i if raw.match?(/\A-?\d+\z/)
+      return raw.to_f if raw.match?(/\A-?\d+\.\d+\z/)
+      return raw[1..].to_sym if raw.start_with?(":")
+      return StateRef.new(raw[7..-2].to_sym) if raw.match?(/\Astate\(:[A-Za-z_][A-Za-z0-9_]*\)\z/)
+      return unquote(raw) if quoted?(raw)
+      return read_hash(raw) if raw.start_with?("{") && raw.end_with?("}")
+      return read_array(raw) if raw.start_with?("[") && raw.end_with?("]")
+
+      raw
+    end
+
+    ESCAPED = { '"' => '\\"', "\\" => "\\\\" }.freeze
+
+    def quote(text) = "\"#{text.gsub(/["\\]/) { |char| ESCAPED[char] }}\""
+
+    def quoted?(raw) = raw.length >= 2 && raw.start_with?('"') && raw.end_with?('"')
+
+    def unquote(raw) = raw[1..-2].gsub(/\\(.)/) { ::Regexp.last_match(1) }
+
+    def read_hash(raw)
+      split_items(raw[1..-2]).to_h do |item|
+        key, _, held = item.partition(":")
+        [key.strip.to_sym, read(held)]
+      end
+    end
+
+    def read_array(raw) = split_items(raw[1..-2]).map { |item| read(item) }
+
+    # Split on the commas that are actually SEPARATORS — never one inside a
+    # quoted string or a nested brace/bracket. Scanned rather than
+    # `String#split(", ")`, which tore `"a, b"` in half and lost the second
+    # field of anything nested.
+    def split_items(body)
+      items = []
+      current = +""
+      depth = 0
+      quoting = false
+      escaping = false
+
+      body.each_char do |char|
+        current << char
+        next (escaping = false) if escaping
+        next (escaping = true) if quoting && char == "\\"
+        next (quoting = !quoting) if char == '"'
+        next if quoting
+
+        depth += 1 if "{[".include?(char)
+        depth -= 1 if "}]".include?(char)
+        next unless char == "," && depth.zero?
+
+        current.chop!
+        items << current
+        current = +""
+      end
+      items << current
+      items.map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/hecks/naming.rb

@@ -0,0 +1,121 @@
+module Hecks
+  module Naming
+    # WHAT SEPARATES THE PARTS OF A DERIVED IDENTITY.
+    #
+    # An identity of several parts is their JOIN, and the join has to be spelled the
+    # same everywhere or two readers name two different records off one declaration.
+    # It was spelled three ways at once here — "::" for an aggregate under a
+    # chapter, "." for everything under an aggregate, "#" for the three that keyed
+    # off position — and each was written where it happened to be needed. Once the
+    # runtime derived the same identity, the runtime made a FOURTH, and a reference
+    # that resolved by string comparison found nothing.
+    IDENTITY_JOIN = ":".freeze
+
+    module_function
+
+    # The parts of an identity, joined in declaration order.
+    def identity(parts) = Array(parts).join(IDENTITY_JOIN)
+
+    def demodulise(type)
+      type.to_s.split("::").last.to_s
+    end
+
+    # snake_case -> PascalCase. The name a synthesised closed-set value object
+    # takes when an attribute declares one inline. The derivation is part of
+    # the IR contract: the same bluebook must always produce the same name.
+    def pascal(text)
+      text.to_s.split("_").map { |part| part.sub(/\A(.)/) { Regexp.last_match(1).upcase } }.join
+    end
+
+    def snake(text)
+      text.to_s
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+    end
+
+    # The name a COLLECTION of something takes.
+    #
+    # There were two of these and one was wrong. A read model's gathered heads
+    # derived their name with a bare `"#{snake(target)}s"`, so the meta-domain's
+    # own whole-bluebook read model handed back `querys`, `entitys`, `policys`
+    # and `dispatchs` — and every check was green, because the checks compared
+    # the wrong rule against itself. Agreement is not correctness; it never was.
+    #
+    # So: one pluraliser, three rules, and every collection name flows through it.
+    def plural(text)
+      word = text.to_s
+      return "#{word[0..-2]}ies" if word.match?(/[^aeiou]y\z/)
+      return "#{word}es"         if word.match?(/(s|x|z|ch|sh)\z/)
+
+      "#{word}s"
+    end
+
+    # `has_many`'s undo — the plural WRITTEN, back to the singular the target
+    # aggregate is actually named. Deliberately the crude half of a pair: `plural`
+    # above earns its precision (three suffix rules) because getting a COLLECTION
+    # name wrong reads as a typo forever ; this only ever recovers a name someone
+    # already wrote as a real aggregate, so "ies -> y, trailing s dropped" is the
+    # whole rule — enough for `has_many Invoices` to resolve to the aggregate
+    # actually named Invoice.
+    def singularize(text)
+      word = text.to_s
+      return "#{word[0..-4]}y" if word.length > 3 && word.end_with?("ies")
+      return word[0..-2]       if word.length > 1 && word.end_with?("s")
+
+      word
+    end
+
+    def reference_key(type)
+      snake(demodulise(type)).to_sym
+    end
+
+    def split_dotted(dotted)
+      first, second = dotted.to_s.split(".", 2)
+      [first.to_s, second.to_s]
+    end
+
+    def qualifier(dotted)
+      text = dotted.to_s
+      text.include?(".") ? text.split(".", 2).first : nil
+    end
+
+    def unqualified(dotted)
+      text = dotted.to_s
+      text.include?(".") ? text.split(".", 2).last : text
+    end
+
+    def split_verb(verb)
+      path, command = verb.to_s.split(".", 2)
+      domain, aggregate = path.to_s.split("::", 2)
+      return nil unless domain && aggregate && command
+
+      [domain, aggregate, command]
+    end
+
+    # `trigger Account::Debit` / `dispatch Account::Debit` — a bare
+    # CONSTANT reference (`ConstShim`'s own `ScopedConstant`, S0b), not
+    # text (ADR 0025, "events and reactions" — command references become
+    # first-class). Ruby's `::` joins EVERY segment the same way a
+    # constant path always does, but a command's own `hecks_fqn` joins
+    # its aggregate with `.` (`Construct#hecks_separator`'s default,
+    # only an AGGREGATE overrides it to `::`) — so only the LAST `::`
+    # becomes a `.`; everything before it (the chapter, when a domain is
+    # spelled at all: `Banking::Account::Debit`) stays `::`-joined.
+    #
+    # A STRING PASSES THROUGH UNCHANGED, on purpose — legacy era text
+    # (S0a's own shadow-parsed spelling) already mixes `::` (domain) and
+    # `.` (command) correctly on its own, e.g. `"Banking::Account.Debit"`,
+    # and re-splitting that by content rather than by TYPE would corrupt
+    # it (its own last `::` sits between the domain and the aggregate,
+    # not the aggregate and the command). Only an actual constant object
+    # — never seen holding a `.` of its own — needs the rewrite at all.
+    def command_ref(value)
+      return value.to_s if value.is_a?(::String) || value.is_a?(::Symbol)
+
+      text = value.to_s
+      path, _, command = text.rpartition("::")
+      path.empty? ? text : "#{path}.#{command}"
+    end
+  end
+end

data/lib/hecks/ports/access_control.port

@@ -0,0 +1,4 @@
+Hecks.port "access_control" do
+  verb   "granted_by"
+  signal :reply
+end