hecks 0.2.0 → 1.0.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