hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,379 @@
+Hecks.bluebook "Bluebook" do
+  aggregate "Vocabulary" do
+    # These are DECLARATIONS, not runtime state — a language's admitted sets are
+    # fixed when the language is defined, which is what one_of means. They carry
+    # no commands on purpose : nothing dispatches a vocabulary, the conformance
+    # check READS them from the IR and holds the runtime's hand-typed tables to them.
+    #
+    # Every one of these is a set the runtime must agree with, and every one has
+    # already drifted or leaked at least once :
+    #   Comparison            went disjoint from the grammar chapter's operator table
+    #   NormalisationStrategy is the third, unchecked copy of the canonical-form table
+    #   Primitive             is what "primitives live in value objects only" is ABOUT
+    #   DomainRefusal         is the boundary three raw Ruby TypeErrors crossed tonight
+    description "The closed sets the language admits — the whole of what any runtime may accept, declared once."
+
+    # ITS NAME, and nothing else. A vocabulary hangs under no other thing — the
+    # closed sets are the language's own, declared once — so one path is the whole
+    # identity.
+    identified_by VocabularyName, as: :name
+
+
+    value_object "VocabularyName" do
+      attribute :value, String
+      invariant("a vocabulary is named") { !value.to_s.empty? }
+    end
+
+    # Expression::Evaluator::COMPARISONS — six operators, all reduced by the
+    # evaluator to two primitives (less_than, equal) combined with a small boolean
+    # algebra: compares_less_than and compares_equal choose which primitive(s) OR
+    # together, negated inverts the result. `compare` reads this table instead of
+    # hardcoding a six-way case statement — see Evaluator::COMPARISONS.
+    value_object "Comparison" do
+      attribute :symbol,             String
+      attribute :compares_less_than, String
+      attribute :compares_equal,     String
+      attribute :negated,            String
+
+      member symbol: ">=", compares_less_than: "true",  compares_equal: "false", negated: "true"
+      member symbol: "<=", compares_less_than: "true",  compares_equal: "true",  negated: "false"
+      member symbol: "<",  compares_less_than: "true",  compares_equal: "false", negated: "false"
+      member symbol: ">",  compares_less_than: "true",  compares_equal: "true",  negated: "true"
+      member symbol: "==", compares_less_than: "false", compares_equal: "true",  negated: "false"
+      member symbol: "!=", compares_less_than: "false", compares_equal: "true",  negated: "true"
+    end
+
+    # Expression::Resolver::SIGN_TESTS
+    # Each sign test is comparing against the literal 0, using an operator
+    # Comparison already declares — compares_via names which one, so a sign
+    # test is sugar for an existing operator rather than a second algebra
+    # beside it. `positive?` = value > 0, `negative?` = value < 0, `zero?` =
+    # value == 0.
+    value_object "SignTest" do
+      attribute :name,         String
+      attribute :compares_via, String
+
+      member name: "positive?", compares_via: ">"
+      member name: "negative?", compares_via: "<"
+      member name: "zero?",     compares_via: "=="
+    end
+
+    # `.include?`'s haystack type decides its behaviour : Array does
+    # membership (the same equal? primitive Comparison's == uses), String
+    # does an exact substring match and refuses a non-String needle. Anything
+    # else is always false — not declared here, since it is the fallback
+    # every OTHER haystack type shares, not a case of its own.
+    value_object "IncludeHaystack" do
+      attribute :type,     String
+      attribute :strategy, String
+
+      member type: "Array",  strategy: "membership"
+      member type: "String", strategy: "substring"
+    end
+
+    # `.to_s` admits exactly these scalar types, and every one of them uses
+    # the SAME rule (Ruby's own to_s — nil renders "", a bool its name, a
+    # number its digits, a string itself) — a closed set to admit into, not a
+    # table of different rules per type.
+    value_object "ToStringType" do
+      attribute :type, String, one_of: ["String", "Integer", "Float", "TrueClass", "FalseClass", "NilClass"]
+    end
+
+    # `.size` and `.empty?` admit exactly the same closed set — a list, a
+    # string, or an open map — and each just calls the one Ruby method
+    # already named for it. One declaration for both, since the set itself is
+    # the only thing either needed to say.
+    value_object "SizedType" do
+      attribute :type, String, one_of: ["Array", "String", "Hash"]
+    end
+
+    # Attribute::PRIMITIVES — the scalars a value object may bottom out in
+    value_object "Primitive" do
+      attribute :name, String, one_of: ["String", "Integer", "Float", "TrueClass", "FalseClass"]
+    end
+
+    # Expression::CanonicalForm::STRATEGIES
+    value_object "NormalisationStrategy" do
+      attribute :name, String, one_of: ["collapse_whitespace", "replace"]
+    end
+
+    # the ops Runtime::CommandInterpreter applies. `sign` is the arithmetic
+    # delta increment/decrement share one primitive by — CommandRules#arithmetic
+    # applies `current + sign *
+    # amount`, differing only in which sign. set and append do no arithmetic,
+    # so they carry no sign — ABSENT IS NOT EMPTY, same reading as elsewhere in
+    # this file.
+    value_object "MutationOp" do
+      attribute :name, String
+      attribute :sign, String
+
+      member name: "set",       sign: ""
+      member name: "append",    sign: ""
+      member name: "increment", sign: "1"
+      member name: "decrement", sign: "-1"
+      # Vendored addition, not (yet) upstream hecks (migration plan
+      # task 4, i106 in-DSL math — CommandRules::Arithmetic#multiply/
+      # #clamp): multiply scales (`current * amount`), clamp bounds
+      # (`current.clamp(min, max)`) — neither is an add/subtract, so
+      # neither carries a sign, same reading as set/append above.
+      member name: "multiply",  sign: ""
+      member name: "clamp",     sign: ""
+      # Vendored addition, not (yet) upstream hecks (migration plan
+      # task 4): remove — the list-removal counterpart to append,
+      # matching an element by value. No sign, same reading as append.
+      member name: "remove",    sign: ""
+      # Vendored addition, not (yet) upstream hecks — CommandBuilder
+      # #delegates_to's own comment gives the full reasoning: an
+      # aggregate-level command's synchronous, single-dispatch handoff
+      # into one nested entity command, rather than a policy/saga's own
+      # commit-then-react reentry. Rides the SAME multi-binding wire
+      # shape append does (`with: {...}` is a field map, same as
+      # append's own `fields:`), so it carries no sign, same reading.
+      member name: "delegate",  sign: ""
+      # CommandBuilder#corrects_impl's own comment gives the full
+      # reasoning — a command declaring a past event it amends, rather
+      # than a fresh mutation of its own. Rides the SAME multi-binding
+      # wire shape append/delegate do (`as:`/`reason:`/`reverses:`,
+      # assembled into one `source` hash by hand, same as `with:` is),
+      # so it carries no sign either.
+      member name: "corrects",  sign: ""
+    end
+
+    # QuerySpecification::Common::Comparators::COMPARATORS — a where-clause's
+    # admitted operators. Unlike Comparison, these do not reduce to one shared
+    # boolean algebra (eq/ne compare values, gt/gte/lt/lte order them, in/contains
+    # test membership in opposite directions), so this stays a flat closed set —
+    # the same shape MutationOp had before it grew a sign.
+    # `none_in_state` (the last member) is a vendored addition, not (yet)
+    # upstream hecks (migration plan task 4) — see
+    # query_specification/common/comparators.rb's own comment on
+    # none_in_state. Both closed sets (the Ruby COMPARATORS constant and
+    # this self-hosted grammar entry) must agree, the same two-places-
+    # must-agree discipline MutationOp/multiply/clamp already required
+    # earlier this pass.
+    value_object "QueryComparator" do
+      attribute :name, String, one_of: ["eq", "ne", "gt", "gte", "lt", "lte", "in", "contains", "none_in_state"]
+    end
+
+    # Adapters::Driven::Folder::DOMAIN_ORDER — declarations load in this order
+    value_object "LoadOrder" do
+      attribute :glob, String,
+                one_of: ["*.port", "*.adapter", "*.bluebook", "translations/*.bluebook", "*.hecksagon", "*.world"]
+    end
+
+    # CommandInterpreter#call — an aggregate command's
+    # own interpretation, ending at the events it emits. Reaction (policies,
+    # sagas) is a structurally separate phase and is not part
+    # of this : CommandInterpreter#call returns before it runs, in a
+    # different class — reaction is
+    # what a command's OWN emitted events cause, not what interpreting
+    # the command does. Two conditional steps — assign_creation_attributes only
+    # fires for a creating command, advance_lifecycle only when a transition
+    # applies — so this is the order a command that does both follows,
+    # confirmed by tracing a real dispatch, not read off the source.
+    value_object "AggregateDispatchOrder" do
+      attribute :step, String,
+                one_of: ["refuse_unknown_arguments", "refuse_absent_arguments", "normalize_args",
+                         "refuse_role_mismatch", "resolve_references", "hydrate", "enforce_givens",
+                         "admissible_transition", "assign_creation_attributes", "apply_mutations",
+                         "advance_lifecycle", "delegate_to_entity", "enforce_ensures", "enforce_invariants",
+                         "save", "emit"]
+    end
+
+    # EntityInterpreter#call — the same shape
+    # one level down, on a piece an aggregate holds rather than the aggregate
+    # itself. `refuse_unknown_arguments`/`refuse_absent_arguments` lead it,
+    # the same position they hold in AggregateDispatchOrder — bug audit H1
+    # (docs/audits/2026-08-10-main-bug-audit.md): an entity command used to
+    # run NEITHER at all, on a since-corrected comment claiming it "inherits
+    # its aggregate's own gate" — nothing on this path ever ran one, and a
+    # bogus argument or a silently-nil'd absent one both went straight
+    # through. The only real difference from AggregateDispatchOrder now is
+    # that an entity is never CREATED through this path (no
+    # assign_creation_attributes) — hydrating the parent and locating the
+    # element replace a single hydrate. resolve_references stayed, though —
+    # an entity command can declare a reference-typed attribute the same way
+    # an aggregate command can (CommandRules#resolve_references is shared by
+    # both interpreters), even though nothing in the real corpus does yet.
+    value_object "EntityDispatchOrder" do
+      attribute :step, String,
+                one_of: ["refuse_unknown_arguments", "refuse_absent_arguments", "normalize_args",
+                         "refuse_role_mismatch", "resolve_references", "hydrate_parent",
+                         "locate_element", "enforce_givens", "admissible_transition", "apply_mutations",
+                         "advance_lifecycle", "enforce_ensures", "enforce_invariants", "save", "emit"]
+    end
+
+    # Runtime::Errors::DOMAIN_REFUSALS — what counts as the domain judging,
+    # as opposed to the runtime breaking. Anything outside this set that reaches
+    # a refusal list is a bug wearing a refusal's clothes.
+    value_object "DomainRefusal" do
+      attribute :name, String,
+                one_of: ["AbsentArgument", "AlreadyExists", "AttributeAbsent", "EnsuresNotMet", "GivenNotMet",
+                         "InvariantViolation", "LifecycleRefused", "NothingToCorrect", "NotFound", "ProjectionAbsent",
+                         "RemoteRefusal", "TypeMismatch", "Unauthorized", "UnknownArgument", "UnknownVerb"]
+    end
+
+    # THE WORDING ITSELF, for every DomainRefusal site that is not already
+    # data — `given`/`ensures`/a declared `invariant` already carry their own
+    # description, read at dispatch time off the command or value object that
+    # declared them. Everything here is different in kind: a LANGUAGE-LEVEL
+    # refusal, the same wording for every domain, not authored per-bluebook —
+    # closer to Comparison/SignTest beside it than to a given. So it follows
+    # THEIR pattern, not given's: declared here for a human to read and a
+    # conformance spec to hold equal, and a hand-typed table
+    # (RefusalWording) is what a dispatch
+    # actually reads — the same reason Evaluator::SIGN_TEST_OPERATORS is
+    # hand-typed rather than read live off this very chapter at every call.
+    #
+    # `{name}` markers are placeholders — plain text substitution, not
+    # expression syntax ; a template is read, never evaluated. Two call
+    # sites that happen to raise the same sentence share one `site` row
+    # (entity_interpreter.rb and command_interpreter.rb's own "not found"
+    # messages, for instance) rather than being declared as two facts that
+    # would have to be kept identical by hand.
+    value_object "RefusalTemplate" do
+      attribute :refusal,  String, admits: "Vocabulary::DomainRefusal"
+      attribute :site,     String
+      attribute :template, String
+
+      member refusal: "NotFound", site: "creating_no_identity",
+             template: "{command} creates a {aggregate} — pass {identity}:"
+      member refusal: "AlreadyExists", site: "creating_duplicate",
+             template: "{command} creates a {aggregate} that already exists — {identity} {offered}"
+      member refusal: "AlreadyExists", site: "entity_duplicate",
+             template: "a {entity} already exists on {aggregate} — {identity} {offered}"
+      member refusal: "NotFound", site: "acting_no_identity",
+             template: "{command} acts on an existing {aggregate} — pass {identity}:"
+      member refusal: "NotFound", site: "record_missing",
+             template: "no {aggregate} with {identity} {offered}"
+      member refusal: "NotFound", site: "entity_parent_no_identity",
+             template: "{command} acts on a {aggregate}'s {entity} — pass {identity}:"
+      member refusal: "UnknownVerb", site: "entity_unknown",
+             template: "{aggregate} has no entity {entity}"
+      member refusal: "NotFound", site: "entity_element_no_identity",
+             template: "{command} acts on one {entity} — pass {identity}:"
+      member refusal: "NotFound", site: "entity_element_missing",
+             template: "no {entity} with {identity} {wants} on {aggregate} {parent_id}"
+      member refusal: "NotFound", site: "reference_target_missing",
+             template: "no {target} with {heads} {key}"
+      member refusal: "NotFound", site: "read_model_reference_missing",
+             template: "no {aggregate} with reference {offered}"
+      member refusal: "TypeMismatch", site: "read_model_object_reference",
+             template: "{query} refused — a reference is an id, and {field} arrived as an object"
+      member refusal: "UnknownVerb", site: "no_query",
+             template: "{aggregate} has no query {query}"
+      member refusal: "UnknownVerb", site: "entity_query_missing",
+             template: "{entity} has no query {query}"
+      member refusal: "UnknownVerb", site: "entity_holds_no_list",
+             template: "{aggregate} holds no list of {entity}"
+      member refusal: "UnknownVerb", site: "entity_no_command",
+             template: "{entity} has no command {command}"
+      member refusal: "UnknownVerb", site: "aggregate_no_command",
+             template: "{aggregate} has no command {command}"
+      member refusal: "UnknownVerb", site: "port_no_operation",
+             template: "{port} has no operation {operation}"
+      member refusal: "UnknownVerb", site: "no_domain",
+             template: "no domain {domain} loaded (verb {verb})"
+      member refusal: "UnknownVerb", site: "no_read_model",
+             template: "{domain} has no read model {query}"
+      member refusal: "UnknownVerb", site: "not_fully_qualified",
+             template: "{verb} is not a fully-qualified verb (Domain::Aggregate.Command)"
+      member refusal: "UnknownVerb", site: "no_aggregate",
+             template: "{domain} has no aggregate {aggregate}"
+      member refusal: "LifecycleRefused", site: "transition_blocked",
+             template: "{command} refused — {field} is {current}, and {command} moves it only from {allowed}"
+      member refusal: "TypeMismatch", site: "value_object_shape",
+             template: "{name} is a {type} — pass its fields as an object, not {offered}"
+      member refusal: "TypeMismatch", site: "reference_as_object",
+             template: "{command} refused — a reference is an id, and {attribute} arrived as an object{known_by}"
+      member refusal: "TypeMismatch", site: "multi_field_scalar",
+             template: "{type} has multiple fields and cannot stand in for a scalar"
+      member refusal: "TypeMismatch", site: "composite_identity",
+             template: "{type} is a composite identity — an identity must have exactly one field"
+      member refusal: "TypeMismatch", site: "numeric_field",
+             template: "{type}.{field} expects {expected}, got {offered}"
+      member refusal: "TypeMismatch", site: "non_finite_field",
+             template: "{type}.{field} must be a finite number, got {offered}"
+      member refusal: "TypeMismatch", site: "pattern_mismatch",
+             template: "{type}.{field} must match {pattern}, got {offered}"
+      member refusal: "TypeMismatch", site: "arithmetic_amount",
+             template: "{op} of {target} needs an Integer, got {offered}"
+      member refusal: "TypeMismatch", site: "arithmetic_current",
+             template: "{op} of {target} needs an Integer {target}, got {offered}"
+      member refusal: "TypeMismatch", site: "arithmetic_shared_field",
+             template: "{op} of {target} needs a value object with one shared Integer field"
+      member refusal: "UnknownArgument", site: "unknown_args",
+             template: "{command} does not declare {unknown} — it takes {declared}"
+      member refusal: "AbsentArgument", site: "absent_args",
+             template: "{command} was not given {absent} — it takes {declared}"
+      member refusal: "InvariantViolation", site: "closed_set_member",
+             template: "{type} admits {admitted} — got {offered}"
+      member refusal: "InvariantViolation", site: "value_object_invariant",
+             template: "{name} invariant violated — {description} (given {offered})"
+      member refusal: "InvariantViolation", site: "admits_declared_set",
+             template: "{name} admits {admits} — {admitted} — got {offered}"
+      member refusal: "InvariantViolation", site: "undeclared_set",
+             template: "{name} admits {admits}, which this chapter does not declare — a closed set is named " \
+                       "Aggregate::SetName, and it must be one the bluebook actually holds"
+      member refusal: "Unauthorized", site: "tenant_required",
+             template: "{query} declares authorize with tenant: {field} — pass {field}: to name which " \
+                       "{field} this ask is scoped to"
+      member refusal: "Unauthorized", site: "role_mismatch",
+             template: "{command} refused — role: {role}, and the caller stated {caller_role}"
+      member refusal: "AttributeAbsent", site: "absent_read",
+             template: "{aggregate} {field} is absent on this record — declared, not optional, and " \
+                       "added since it was written. Backfill it in a translation (backfill :{field}, " \
+                       "default: ...), or declare it optional: true"
+      # S12, ADR 0025 — the same silent-wrong-answer class AttributeAbsent
+      # above refuses, one line up: a `projects` field this record predates,
+      # or that no rebuild sweep has populated yet, read by a rule as
+      # though it were a real value rather than one nobody has copied over.
+      member refusal: "ProjectionAbsent", site: "absent_read",
+             template: "{aggregate} {field} is not yet projected on this record — declared via " \
+                       "projects :{field}, but no rebuild sweep has populated it. Run the sweep, " \
+                       "or read {reference}.{remote_field} directly if this rule cannot wait"
+    end
+
+    # SagaInterpreter::REFUSED.
+    #
+    # A leg answers an EVENT — `on "AccountDebited"` — or it answers one of these,
+    # which are not events at all: no aggregate announces that a leg the procedure
+    # dispatched was declined. `on :refused` is the compensating leg, and without
+    # this declaration the word lived only as a magic string in the interpreter,
+    # and a reader of the language could not discover the
+    # trigger existed.
+    value_object "Trigger" do
+      attribute :name, String, one_of: ["refused"]
+    end
+
+    # Hecks::Forms::FieldShape's own EMAIL_HINT/URL_HINT/
+    # TEL_HINT/TEXTAREA_HINT (lib/hecks/forms/field_shape.rb)
+    # — the regexes `text_field` matches a text attribute's own NAME
+    # against (case-insensitively) to guess an HTML input type or a
+    # textarea kind, when nothing more specific (a `pattern:`, an
+    # `admits:`, a closed set) already answered the question. Declared
+    # here for the same reason RefusalTemplate is: a LANGUAGE-LEVEL
+    # rendering convention, the same guess for every domain, not
+    # authored per-bluebook — closer to Comparison/SignTest than to a
+    # given. `pattern` is the regex SOURCE, no delimiters or flags
+    # (Ruby's own `Regexp#source`) — spec/field_hint_conformance_spec.rb
+    # holds FieldShape's four hand-typed constants equal to this, both
+    # directions, the same conformance shape refusal_wording_
+    # conformance_spec.rb already holds RefusalTemplate to.
+    #
+    # `resolves_to` names WHICH Field attribute a match sets — `html_type`
+    # for email/url/tel (three candidates, only one wins, checked in that
+    # order), `kind` for textarea (checked separately, and only once
+    # html_type has already fallen through to "text").
+    value_object "FieldHint" do
+      attribute :name,        String
+      attribute :pattern,     String
+      attribute :resolves_to, String
+
+      member name: "email",    pattern: 'email',                                                 resolves_to: "html_type"
+      member name: "url",      pattern: '\b(url|uri|website|link)\b',                             resolves_to: "html_type"
+      member name: "tel",      pattern: 'phone|\btel(ephone)?\b',                                 resolves_to: "html_type"
+      member name: "textarea", pattern: '\b(text|body|note|notes|description|message|comment)\b', resolves_to: "kind"
+    end
+  end
+end

data/lib/hecks/language/hecksagon/adapter_binding.bluebook

@@ -0,0 +1,51 @@
+Hecks.bluebook "Hecksagon" do
+  aggregate "AdapterBinding" do
+    description "One aggregate-to-adapter binding inside a hecksagon — the verb it answers, the adapter it names. Its own root because a hecksagon's binds are an open set of verbs (one per declared port), which no value object can hold — the same reasoning Wiring carries for a world's settings."
+
+    # The retained parent edge is structural state. `hecksagon` below is
+    # separately the text component of this binding's own compound identity,
+    # so the relationship keeps the same explicit `_ref` distinction World::
+    # Wiring uses for its parent edge.
+    belongs_to Hecksagon, as: :hecksagon_ref
+
+    # THE HECKSAGON IT IS IN, THE AGGREGATE IT NAMES, THE VERB IT ANSWERS.
+    # One hecksagon binds one adapter per (aggregate, verb) pair — that is
+    # what a binding IS — so the triple identifies it.
+    identified_by :hecksagon, :aggregate, :verb
+
+    attribute :hecksagon, BindingText
+    attribute :aggregate, BindingText
+    attribute :verb,      BindingText
+    attribute :adapter,   BindingText
+    attribute :role,      BindingText, optional: true
+
+    value_object "BindingText" do
+      attribute :value, String
+    end
+
+    command "Bind" do
+      role "Deployment"
+      goal "Name the adapter one aggregate answers one verb through"
+
+      # A creating command receives the parent's identity as an ordinary
+      # value fact. It does not declare a behavioral relationship or use the
+      # parent as a hidden receiver.
+      attribute :hecksagon_ref, HecksagonName
+      attribute :aggregate, BindingText
+      attribute :verb,      BindingText
+      attribute :adapter,   BindingText
+      attribute :role,      BindingText, optional: true
+
+      given("a binding names its verb") { !verb.value.to_s.empty? }
+
+      sets :hecksagon_ref
+      sets :hecksagon
+      sets :aggregate
+      sets :verb
+      sets :adapter
+      sets :role
+
+      emits "Bound"
+    end
+  end
+end

data/lib/hecks/language/hecksagon/domain_port.bluebook

@@ -0,0 +1,76 @@
+Hecks.bluebook "Hecksagon" do
+  aggregate "DomainPort" do
+    description "A primary port — the boundary between a domain and its adapters, in hexagonal terms, is exactly what a hecksagon already IS for every other port. Root-level (belongs to the chapter) or aggregate-scoped (reached the same way persisted_by is, through the open Const.verb(...) door). One of two shapes, never both: a list of operations translating an inbound fact into this domain's own events, or a bare verb naming a swappable resource port (the same Hecks.port a project's own .port file declares, reached from inside the hecksagon instead)."
+
+    identified_by PortName, as: :name
+
+    attribute :verb, PortVerb, optional: true
+
+    value_object "PortName" do
+      attribute :value, String
+      invariant("a port is named") { !value.to_s.empty? }
+    end
+
+    value_object "PortVerb" do
+      attribute :value, String
+      invariant("a verb is named") { !value.to_s.empty? }
+    end
+
+    # HOW DOMAINPORT IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: DomainPort.
+    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: "operation",       context: "DomainPort",    body: "keywords", inner: "PortOperation", opens: "PortOperation", fills: "", calls: "tells_impl"
+      member word: "tells",           context: "DomainPort",    body: "keywords", inner: "PortOperation", opens: "PortOperation", fills: "", calls: "tells_impl"
+      member word: "asks",            context: "DomainPort",    body: "keywords", inner: "PortOperation", opens: "PortOperation", fills: "", calls: "asks_impl"
+      member word: "verb",            context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "verb"
+
+    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: "operation",       context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "name"
+      member keyword: "tells",           context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "name"
+      member keyword: "asks",            context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "name"
+      member keyword: "verb",            context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "verb"
+
+      # THE RECEIVING AGGREGATE — PortOperationBuilder's own `reference_to`
+      # (inside the block) is refused (#335); this is the sanctioned
+      # replacement, named directly on the word that opens the block
+      # rather than a statement inside it. `kind: "constant"`, matching
+      # `reference_to`'s own first positional argument
+      # (port_operation.bluebook) — same bareword-constant resolution,
+      # just moved.
+      member keyword: "operation",       context: "DomainPort", at: "", named: "to", kind: "constant", required: "false", fills: "to"
+      member keyword: "tells",           context: "DomainPort", at: "", named: "to", kind: "constant", required: "false", fills: "to"
+      member keyword: "asks",            context: "DomainPort", at: "", named: "to", kind: "constant", required: "false", fills: "to"
+
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+Hecks.bluebook "Hecksagon" do
+  aggregate "Hecksagon" do
+    description "One .hecksagon — the events a domain subscribes to, and the root every binding hangs off. A sibling artifact to the bluebook, not part of it."
+
+    identified_by HecksagonName, as: :domain
+
+    attribute :subscriptions,      list_of(Subscription)
+    attribute :framework_members,  list_of(FrameworkMember)
+    attribute :vendored_bluebooks, list_of(VendoredBluebook)
+
+    value_object "HecksagonName" do
+      attribute :value, String
+      invariant("a hecksagon names its domain") { !value.to_s.empty? }
+    end
+
+    value_object "Subscription" do
+      attribute :value, String
+      invariant("a subscription names an event") { !value.to_s.empty? }
+    end
+
+    # A `framework/bluebook/` member this hecksagon attaches — Governance,
+    # Identity, whatever else lands beside them. Same shape as
+    # `Subscription` beside it, one word over.
+    value_object "FrameworkMember" do
+      attribute :value, String
+      invariant("a framework member is named") { !value.to_s.empty? }
+    end
+
+    # A vendored, external bluebook this hecksagon attaches — one level
+    # further out than `FrameworkMember`: not a member shipped inside
+    # hecks's own lib/, but a separate package vendored into the
+    # consuming project's own checkout. Same shape as `FrameworkMember`
+    # beside it, one word over — see EmbryonautBluebook's own header.
+    value_object "VendoredBluebook" do
+      attribute :value, String
+      invariant("a vendored bluebook is named") { !value.to_s.empty? }
+    end
+
+    command "Declare" do
+      role "Deployment"
+      goal "Open a hecksagon for a domain"
+
+      attribute :domain, HecksagonName
+
+      sets :domain
+
+      emits "HecksagonDeclared"
+    end
+
+    command "Subscribe" do
+      role "Deployment"
+      goal "Take a hecksagon's own event, from outside the domain's own bluebook"
+
+      attribute :event, Subscription
+
+      sets :subscriptions, append: { value: :event }
+
+      emits "SubscriptionAdded"
+    end
+
+    command "UsesFramework" do
+      role "Deployment"
+      goal "Attach a framework/bluebook/ member to this hecksagon"
+
+      attribute :member, FrameworkMember
+
+      sets :framework_members, append: { value: :member }
+
+      emits "FrameworkMemberAttached"
+    end
+
+    command "UsesEmbryonautBluebook" do
+      role "Deployment"
+      goal "Attach a vendored, external bluebook to this hecksagon"
+
+      attribute :package, VendoredBluebook
+
+      sets :vendored_bluebooks, append: { value: :package }
+
+      emits "VendoredBluebookAttached"
+    end
+
+    # HOW HECKSAGON IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: File, Hecksagon.
+    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: "hecksagon",       context: "File",     body: "keywords", inner: "Hecksagon",      opens: "Hecksagon",      fills: ""
+      member word: "subscribe",       context: "Hecksagon", body: "none", inner: "", opens: "", fills: "subscriptions"
+      member word: "uses_framework",  context: "Hecksagon", body: "none", inner: "", opens: "", fills: "framework_members"
+      member word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "vendored_bluebooks"
+      member word: "port",            context: "Hecksagon",     body: "keywords", inner: "DomainPort",    opens: "DomainPort",    fills: "", calls: "port_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: "hecksagon",       context: "File", at: "1", named: "", kind: "text", required: "true", fills: "domain"
+      member keyword: "subscribe",       context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "subscriptions"
+      member keyword: "uses_framework",  context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "framework_members"
+      member keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "vendored_bluebooks"
+      member keyword: "port",            context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name"
+
+    end
+  end
+end