hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/dsl/bluebook_builder.rb

@@ -7,7 +7,7 @@ module Hecks
       # builder collecting every `aggregate`/`read_model`/`policy`/
       # `process_manager` a chapter declares, plus the chapter-wide named-
       # given pools those thread down into (see `#aggregate_impl`'s own
-      # comment). `.build` reuses the SAME open builder instance across
+      # comment). `.build` reuses the same open builder instance across
       # several files sharing one chapter name (`self.build`'s own comment),
       # so a chapter split across files accumulates rather than each file
       # silently replacing the last.
@@ -19,6 +19,8 @@ module Hecks
 
         attr_reader :classification
 
+        # @param name [String] the chapter's declared name
+        # @param version [String, nil] the chapter's pinned version, or nil for unversioned
         def initialize(name, version: nil)
           @name       = name
           @version    = version
@@ -26,19 +28,19 @@ module Hecks
           @read_models      = []
           @policies         = []
           @process_managers = []
-          # THE ROOT of the CHAPTER-WIDE given pool — one level wider
+          # The root of the chapter-wide given pool — one level wider
           # than `AggregateBuilder`'s own `@entity_named_givens` (S10
           # extended across an aggregate's whole entity tree, earlier
           # this arc). See `#given`'s own comment for what this closes.
           @chapter_named_givens = {}
-          # EVERY BARE CHAPTER-GIVEN REFERENCE THIS CHAPTER'S OWN FILES
-          # LEFT UNRESOLVED SO FAR — threaded into every aggregate the
+          # Every bare chapter-given reference this chapter's own files
+          # left unresolved so far — threaded into every aggregate the
           # same way `@chapter_named_givens` is. See
           # `AggregateBuilder#pending_chapter_given`'s own comment for
           # what queues here and `#resolve_pending_chapter_givens!`,
           # below, for where it drains.
           @chapter_pending_givens = []
-          # ONE LEVEL WIDER STILL — the CHAPTER-WIDE, ENTITY-SCOPED pool
+          # **One level wider still** — the chapter-wide, entity-scoped pool
           # (the piece analogue of `@chapter_named_givens`, above). See
           # `EntityBuilder#given_impl`'s own comment for what this
           # closes; `docs/implemented/resolution-rules/
@@ -62,46 +64,105 @@ module Hecks
         end
         private :adopt_version
 
+        # Records the chapter's vision statement.
+        #
+        # @param value [String] the vision text, as given to `vision "..."`
+        # @return [void]
         def vision(value)
           # moved to the language: Vision invariant, on Chapter.Declare
 
           @vision = value
         end
 
-        # A domain's own identity can change — this names what it used to
-        # be, so the storage layer can recognize its own history under the
-        # old name instead of minting a brand-new lineage from nothing.
+        # Records the chapter's earlier name, so the storage layer recognizes its own history
+        # under that old name instead of minting a brand-new lineage from nothing — a chapter's
+        # identity can change, and this is where the new declaration says what it was.
+        #
+        # @param value [String, Symbol] the chapter's earlier name
+        # @return [String] `value`, stringified, as stored
         def formerly_known_as(value) = @formerly_known_as = value.to_s
 
-        # A SUB-LANGUAGE NAMES WHERE IT LANDS. ADR 0026's own seam: the core
+        # Names a core grammar context this chapter's sub-language extends.
+        #
+        # **A sub-language names where it lands**. ADR 0026's own seam: the core
         # grammar does not name its extension points, so this chapter names
-        # ITSELF onto them instead — the core contexts (e.g. "Query",
+        # itself onto them instead — the core contexts (e.g. "Query",
         # "ReadModel") whose own admitted words this chapter's `Syntax`
         # aggregate contributes rows for. Variadic, and accumulating across
         # calls the same reason `identified_by`/`group_by` are: nothing here
         # requires one call to name every context at once.
-        # RENAMED FROM `attaches_to` — item #13's full metaprogrammed
-        # dispatch (slice 4c). Not bootstrap-reachable (only sub-language
-        # chapters like Paging use it; the CORE chapters never describe
-        # themselves with it).
+        #
+        # Reached through `calls: "attaches_to_impl"` rather than `GenericDispatch`'s default —
+        # not bootstrap-reachable, since only sub-language chapters like Paging use it, never a
+        # core chapter.
+        #
+        # @param contexts [Array<String>] one or more core grammar context names, such as
+        #   `"Query"`/`"ReadModel"`
+        # @return [Array<String>] every context named so far, this call's included
         def attaches_to_impl(*contexts) = (@attaches_to ||= []).concat(contexts.map(&:to_s))
 
+        # Records a capability this chapter answers for other domains.
+        #
+        # A capability this chapter answers for other domains, declared so
+        # nothing has to recognise the chapter by name — Governance's
+        # `provides "authorization", assignments: ..., grant: ...,
+        # transitions: ...`. One row per key, in the order written; what
+        # each capability requires is checked once the chapter is whole
+        # (`Validation#validate_provisions!`), since the verbs it names may
+        # be declared further down the file.
+        #
+        # @param capability [String] the capability's own name, such as `"authorization"`
+        # @param verbs [Hash{Symbol => String}] one command/query reference per capability
+        #   key, e.g. `grant: "RoleAssignment.Assign"`
+        # @return [Array<Bluebook::Chapter::Provision>] every provision row declared so far,
+        #   this capability's included
+        # @raise [Bluebook::DSL::Malformed] if `verbs` is empty
+        def provides_impl(capability, **verbs)
+          if verbs.empty?
+            raise Malformed, "#{@name}'s provides #{capability.inspect} names no verb — say which of this " \
+                             "chapter's commands and queries answer it"
+          end
+
+          rows = verbs.map { |key, verb| Chapter::Provision.new(capability: capability.to_s, key: key.to_s, verb: verb.to_s) }
+          (@provides ||= []).concat(rows)
+        end
+
+        # Classifies this chapter as core to the framework, rather than a domain built on it.
+        #
+        # @return [Symbol] `:core`
         def core       = @classification = :core
+
+        # Classifies this chapter as a supporting piece of the framework, rather than a domain
+        # built on it.
+        #
+        # @return [Symbol] `:supporting`
         def supporting = @classification = :supporting
+
+        # Classifies this chapter as generic infrastructure, rather than a domain built on it.
+        #
+        # @return [Symbol] `:generic`
         def generic    = @classification = :generic
 
+        # Declares an aggregate belonging to this chapter.
+        #
         # `@chapter_named_givens` is threaded into every aggregate this
         # chapter builds — see `AggregateBuilder#given`'s own comment
-        # for the sharing this enables; NOT a new top-level DSL word
-        # itself (an aggregate's own EXISTING `given` already both
+        # for the sharing this enables; not a new top-level DSL word
+        # itself (an aggregate's own existing `given` already both
         # declares locally and write-throughs here as a side effect,
         # the identical shape `EntityBuilder#given`'s own write-through
         # to its owner aggregate's pool already takes — no new spelling
         # for "declare a precondition," one level wider, same word).
-        # RENAMED FROM `aggregate` — item #13's full metaprogrammed
-        # dispatch (slice 4c). Bootstrap-reachable (every core/attached
-        # chapter's own top-level shape is written with it), so also
-        # named in GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        #
+        # Reached through `calls: "aggregate_impl"`, not `GenericDispatch`'s default —
+        # bootstrap-reachable (every core/attached chapter's own top-level shape is written
+        # with it), so also named in `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
+        #
+        # @param name [String] the aggregate's own name
+        # @yield the aggregate body, evaluated against a new `AggregateBuilder`; may be omitted
+        # @return [Array<Bluebook::Aggregate>] every aggregate declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if the aggregate's own body fails any check
+        #   `AggregateBuilder#build` raises
         def aggregate_impl(name, &)
           @aggregates << AggregateBuilder.build(name, chapter_named_givens:          @chapter_named_givens,
                                                       chapter_pending_givens:        @chapter_pending_givens,
@@ -109,6 +170,8 @@ module Hecks
                                                       chapter_entity_pending_givens: @chapter_entity_pending_givens, &)
         end
 
+        # Declares a read model belonging to this chapter.
+        #
         # `read_model` is the word (ADR 0025 reverts `report` — the IR
         # construct, the registry API, and the docs filename all said
         # `read_model` the whole time; no era was ever minted under
@@ -117,30 +180,65 @@ module Hecks
         # bridge) for the same reason `has_many` does — frozen era text
         # that used it must keep booting; live source refuses it, naming
         # the replacement.
+        #
+        # @param name [String] the read model's own name
+        # @yield the read model body, evaluated against a new `ReadModelBuilder`
+        # @return [Array<Bluebook::ReadModel>] every read model declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if the body fails any check `ReadModelBuilder#build`
+        #   raises
         def read_model(name, &)
-          # A read model gathers heads from SEVERAL aggregates, so no single head
+          # A read model gathers heads from several aggregates, so no single head
           # declares it — the chapter does. Its owner is stamped in `build`, where
           # the chapter namespace exists.
           @read_models << ReadModelBuilder.build(name, &)
         end
 
+        # The retired spelling of `read_model`, still answered under shadow-parsing so frozen
+        # era text keeps booting; live source refuses it and names the replacement.
+        #
+        # @param name [String] the read model's own name
+        # @yield the read model body, evaluated against a new `ReadModelBuilder`
+        # @return [Array<Bluebook::ReadModel>] every read model declared so far, this one last,
+        #   under shadow-parsing
+        # @raise [Bluebook::DSL::Malformed] always, outside shadow-parsing — `report` is retired
         def report(name, &)
           return read_model(name, &) if MetaValidator.shadow_parsing?
 
           raise Malformed, "report is gone — read_model is the word now"
         end
 
+        # Declares a policy belonging to this chapter.
+        #
+        # @param name [String] the policy's own name
+        # @yield the policy body, evaluated against a new `PolicyBuilder`
+        # @return [Array<Bluebook::Policy>] every chapter-level policy declared so far,
+        #   this one last
         def policy(name, &)
           @policies << PolicyBuilder.build(name, &)
         end
 
+        # Declares a process manager (saga) belonging to this chapter.
+        #
+        # @param name [String] the process manager's own name
+        # @yield the process manager body, evaluated against a new `ProcessManagerBuilder`
+        # @return [Array<Bluebook::ProcessManager>] every process manager declared so far,
+        #   this one last
         def process_manager(name, &)
           @process_managers << ProcessManagerBuilder.build(name, &)
         end
 
+        # Assembles this builder's accumulated declarations into a judged `Chapter`.
+        #
+        # @return [Bluebook::Chapter] the built chapter, judged by the language when not
+        #   deferring across a multi-file chapter
+        # @raise [Bluebook::DSL::Malformed] if a chapter-wide given reference cannot be
+        #   resolved, if cross-construct validation fails, or if the language's own
+        #   whole-document judgment refuses the chapter
+        # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a process
+        #   manager's own structural check fails
         def build
           # The chapter is the top of the construct chain — `Bluebook` is a
-          # ROOT, and its constructor stamps every aggregate and read model with
+          # root, and its constructor stamps every aggregate and read model with
           # itself as owner, so every `hecks_fqn` below resolves by walking up
           # to it. No constants are installed at load time : the public door is
           # a per-boot projection, installed by `Loader.bind_runtime` once a
@@ -152,25 +250,26 @@ module Hecks
                                            process_managers: @process_managers,
                                            classification: @classification,
                                            formerly_known_as: @formerly_known_as,
-                                           attaches_to: @attaches_to || [])
+                                           attaches_to: @attaches_to || [],
+                                           provides: @provides || [])
 
-          # SAME REASON, SAME GATE — a bare chapter-given may still be
+          # **Same reason, same gate** — a bare chapter-given may still be
           # pending (see `AggregateBuilder#pending_chapter_given`) if a
           # file that would resolve it hasn't loaded yet; resolving now
           # would see the same incomplete `@chapter_named_givens`
           # `validate_assembled!` below would. Deferred to
-          # `MetaValidator.judge_deferred!` the same way, and BEFORE
+          # `MetaValidator.judge_deferred!` the same way, and before
           # `validate_assembled!` there — nothing downstream should ever
           # read an unresolved placeholder's fields.
           resolve_pending_chapter_givens! unless MetaValidator.deferring?
           resolve_pending_chapter_entity_givens! unless MetaValidator.deferring?
 
-          # A CHAPTER MAY BE SPLIT ACROSS FILES (see `self.build`'s own
-          # comment). Every check below needs the WHOLE chapter present —
+          # A chapter may be split across files (see `self.build`'s own
+          # comment). Every check below needs the whole chapter present —
           # a hop, a projection, a correlation key or an event shape can
           # equally name a construct declared in a file that has not
           # loaded yet, and `@aggregates`/`@process_managers` here are
-          # only ever as complete as whatever has loaded SO FAR. So,
+          # only ever as complete as whatever has loaded so far. So,
           # exactly like `MetaValidator.call` below, this is skipped
           # while `MetaValidator.defer` is loading the chapter's files
           # and run once instead — by `MetaValidator.judge_deferred!`,
@@ -187,17 +286,17 @@ module Hecks
           MetaValidator.call(bluebook)
         end
 
-        # THE OTHER HALF OF A CHAPTER-WIDE `given` REFERENCE —
+        # The other half of a chapter-wide `given` reference —
         # `AggregateBuilder#pending_chapter_given` recognised an
         # unresolved bare reference and deferred it here, unable to
-        # check further: a later file in this SAME chapter might still
+        # check further: a later file in this same chapter might still
         # declare the real thing. Runs once every file has loaded,
         # against the now-complete `@chapter_named_givens` pool — the
-        # IDENTICAL lookup `reference_named_chapter_given` already does,
+        # identical lookup `reference_named_chapter_given` already does,
         # just late enough to see every aggregate's own declarations,
         # not only the ones loaded before the referencing one.
         #
-        # MUTATES each placeholder `Given` IN PLACE rather than
+        # Mutates each placeholder `Given` in place rather than
         # replacing it — it is already embedded, by Ruby object
         # reference, in the referencing aggregate's own `preconditions`
         # and in any command (same aggregate) that separately
@@ -208,6 +307,12 @@ module Hecks
         # which only exists on the builder instance still open for this
         # chapter (`MetaValidator.judge_deferred!` reaches it via
         # `registry.bluebook_builder(name)`, guaranteed already present).
+        #
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if a pending reference's own `description` names no
+        #   precondition any aggregate in this chapter declares, is ambiguous across several
+        #   aggregates with no `declared_by:` to disambiguate, or `declared_by:` names an
+        #   aggregate that does not declare it
         def resolve_pending_chapter_givens!
           @chapter_pending_givens.each do |entry|
             resolved = resolve_pending_chapter_given(entry)
@@ -247,9 +352,15 @@ module Hecks
         end
         private :resolve_pending_chapter_given
 
-        # THE ENTITY-SCOPED ANALOGUE, one level down — see
+        # The entity-scoped analogue, one level down — see
         # `#resolve_pending_chapter_givens!`'s own comment; identical
         # shape, resolved against `@chapter_entity_named_givens` instead.
+        #
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if a pending reference's own `description` names no
+        #   precondition any piece in this chapter declares, is ambiguous across several pieces
+        #   with no `declared_by:` to disambiguate, or `declared_by:` names a piece that does
+        #   not declare it
         def resolve_pending_chapter_entity_givens!
           @chapter_entity_pending_givens.each do |entry|
             resolved = resolve_pending_chapter_entity_given(entry)
@@ -289,34 +400,55 @@ module Hecks
         end
         private :resolve_pending_chapter_entity_given
 
-        # A CHAPTER MAY BE DECLARED IN SEVERAL FILES, meant to merge into ONE
+        # Builds a `Chapter` from a `Hecks.bluebook "Name" do ... end` block, reusing the same
+        # open builder across several files that share one chapter name.
+        #
+        # A chapter may be declared in several files, meant to merge into one
         # domain — `lib/hecks/language/bluebook/*.bluebook` all open
-        # `Hecks.bluebook "Bluebook" do ... end`. Each `Hecks.bluebook` call used to
-        # mint a fresh builder, so a second file with the same chapter name
-        # silently replaced the first's aggregates instead of adding to them.
+        # `Hecks.bluebook "Bluebook" do ... end`. The registry holds the builder open across
+        # calls — the first file for a name creates it, every later file for the same name
+        # reuses the same instance — rather than minting a fresh builder per call, which would
+        # let a second file with the same chapter name silently replace the first's aggregates
+        # instead of adding to them.
         #
-        # The registry now holds the builder OPEN across calls : the first file
-        # for a name creates it, every later file for the same name reuses the
-        # same instance, so `@aggregates`/`@read_models` accumulate. `#build` is
-        # safe to call once per file on the same builder — it constructs a fresh
+        # `@aggregates`/`@read_models` accumulate across calls on the reused instance. `#build`
+        # is safe to call once per file on the same builder — it constructs a fresh
         # `Bluebook` from whatever is currently held and re-`Namespace.install`s
-        # over the previous one, so the LAST file's call leaves every aggregate
+        # over the previous one, so the last file's call leaves every aggregate
         # seen so far reachable, and each call's IR is a strict superset of the
         # one before. `Registry#add_bluebook` still simply stores by name — with
         # this in place, "last write wins" is the cumulative, correct write.
+        #
+        # @param name [String] the chapter's declared name
+        # @param version [String, nil] the chapter's pinned version, or nil for unversioned
+        # @yield the chapter's body, `instance_eval`'d against the builder, with a `const_missing`
+        #   resolver installed so a bare constant resolves to a `ConstShim::ScopedConstant`
+        # @return [Bluebook::Chapter] the built, judged chapter
+        # @raise [Bluebook::DSL::Malformed] if this call's `version` conflicts with a version
+        #   already adopted for this chapter name, or if the built chapter fails any check
+        #   `#build` raises
+        # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a process
+        #   manager's own structural check fails
         def self.build(name, version: nil, &block)
           registry = Hecks.current_registry
-          builder  = registry ? registry.bluebook_builder(name) { new(name, version: version) } : new(name, version: version)
+          # WHICH FILE CALLED `Hecks.bluebook`, recorded for
+          # `Registry#record_bluebook_source` — two frames up: this
+          # method's own caller is `Hecks.bluebook` (hecks.rb), and ITS
+          # caller is the real `.bluebook` file's own top-level call site.
+          caller_location = caller_locations(2, 1)&.first
+          registry&.record_bluebook_source(name, caller_location&.path)
+          builder = registry ? registry.bluebook_builder(name) { new(name, version: version) } : new(name, version: version)
           builder.__send__(:adopt_version, version)
-          # A bare constant in a bluebook — `attribute :name, PizzaName` — is a NAME,
+          # A bare constant in a bluebook — `attribute :name, PizzaName` — is a name,
           # not a reference to something Ruby has heard of. `const_missing` hands
           # over a `ConstShim::ScopedConstant` (S0b, const_shim.rb's own comment),
           # and that is still the whole answer for a bare name: `Attribute` spells
-          # it with `to_s`, so the `TypeName` wrapper this used to build existed
-          # only long enough to be stringified. The concept still has a home — the
+          # it with `to_s`, so the concept never needed a `TypeName` wrapper class
+          # of its own — any such wrapper would exist only long enough to be
+          # stringified. The concept still has a home — the
           # language declares `value_object "TypeName"` — it just needed no Ruby
           # class of its own. A Module rather than a Symbol is what also lets
-          # `Account::Debit`/`admits: Account::LedgerDirection` answer their OWN
+          # `Account::Debit`/`admits: Account::LedgerDirection` answer their own
           # `::` — a plain Symbol cannot.
           resolver = ->(const) { ConstShim::ScopedConstant.for(const) }
           ConstShim.with(resolver) { builder.instance_eval(&block) } if block

data/lib/hecks/bluebook/dsl/bootstrap_table.rb

@@ -0,0 +1,116 @@
+# Generated — projected from the language's own Keyword rows (the
+# `calls:`, `resolves_via:` and `disambiguator:` columns of every
+# KeywordSeed under lib/hecks/language/).
+#
+# Do not edit. spec/bootstrap_table_spec.rb re-projects this in memory
+# and refuses a diff — run bin/project_bootstrap_table instead.
+#
+# Plain data, no requires: this is read while the grammar table it was
+# projected from is still being built (`MetaValidator.bootstrapping?`).
+
+module Hecks
+  module Bluebook
+    module DSL
+      module BootstrapTable
+        # [context, word] => the method a word's whole call forwards to.
+        CALLS = {
+          ["Aggregate", "provenance"] => :provenance_impl,
+          ["Aggregate", "identified_by"] => :identified_by_impl,
+          ["Aggregate", "reference_to"] => :reference_to_impl,
+          ["Aggregate", "has_many"] => :has_many_impl,
+          ["Aggregate", "has_one"] => :has_one_impl,
+          ["Aggregate", "belongs_to"] => :belongs_to_impl,
+          ["Aggregate", "lifecycle"] => :lifecycle_impl,
+          ["Aggregate", "entity"] => :entity_impl,
+          ["Aggregate", "query"] => :query_impl,
+          ["Aggregate", "policy"] => :policy_impl,
+          ["Aggregate", "command"] => :command_impl,
+          ["Aggregate", "attribute"] => :attribute_impl,
+          ["Aggregate", "invariant"] => :invariant_impl,
+          ["Aggregate", "given"] => :given_impl,
+          ["Aggregate", "projects"] => :projects_impl,
+          ["Lifecycle", "transition"] => :transition_impl,
+          ["Bluebook", "attaches_to"] => :attaches_to_impl,
+          ["Bluebook", "provides"] => :provides_impl,
+          ["Bluebook", "aggregate"] => :aggregate_impl,
+          ["Command", "role"] => :role_impl,
+          ["Command", "provenance"] => :provenance_impl,
+          ["Command", "reference_to"] => :reference_to_impl,
+          ["Command", "given"] => :given_impl,
+          ["Command", "sets"] => :sets_impl,
+          ["Command", "then_set"] => :then_set_impl,
+          ["Command", "delegates_to"] => :delegates_to_impl,
+          ["Command", "attribute"] => :attribute_impl,
+          ["Command", "corrects"] => :corrects_impl,
+          ["Entity", "identified_by"] => :identified_by_impl,
+          ["Entity", "given"] => :given_impl,
+          ["Entity", "invariant"] => :invariant_impl,
+          ["Entity", "command"] => :command_impl,
+          ["Entity", "query"] => :query_impl,
+          ["Entity", "lifecycle"] => :lifecycle_impl,
+          ["Entity", "attribute"] => :attribute_impl,
+          ["Entity", "reference_to"] => :reference_to_impl,
+          ["Entity", "has_many"] => :has_many_impl,
+          ["Entity", "has_one"] => :has_one_impl,
+          ["Entity", "belongs_to"] => :belongs_to_impl,
+          ["Entity", "entity"] => :entity_impl,
+          ["Policy", "on"] => :on_impl,
+          ["Policy", "trigger"] => :trigger_impl,
+          ["Policy", "across"] => :across_impl,
+          ["ProcessManager", "starts_on"] => :starts_on_impl,
+          ["ProcessManager", "ends_on"] => :ends_on_impl,
+          ["ProcessManager", "transition"] => :transition_impl,
+          ["Handler", "dispatch"] => :dispatch_impl,
+          ["Dispatch", "compensates"] => :compensates_impl,
+          ["ReadModel", "reference_to"] => :reference_to_impl,
+          ["ReadModel", "include"] => :include_impl,
+          ["ReadModel", "group_by"] => :group_by_impl,
+          ["ReadModel", "where"] => :where_impl,
+          ["ReadModel", "order_by"] => :order_by_impl,
+          ["ReadModel", "authorize"] => :authorize_impl,
+          ["Query", "attribute"] => :attribute_impl,
+          ["Query", "reference_to"] => :reference_to_impl,
+          ["Query", "where"] => :where_impl,
+          ["Query", "order_by"] => :order_by_impl,
+          ["Query", "authorize"] => :authorize_impl,
+          ["ValueObject", "attribute"] => :attribute_impl,
+          ["ValueObject", "one_of"] => :one_of_impl,
+          ["ValueObject", "invariant"] => :invariant_impl,
+          ["ValueObject", "member"] => :member_impl,
+          ["OneOf", "member"] => :member_impl,
+          ["Type", "list_of"] => :list_of_impl,
+          ["Type", "one_of"] => :one_of_impl,
+          ["World", "realm"] => :realm_impl,
+          ["World", "latest"] => :latest_impl,
+          ["DomainPort", "operation"] => :tells_impl,
+          ["DomainPort", "tells"] => :tells_impl,
+          ["DomainPort", "asks"] => :asks_impl,
+          ["Hecksagon", "port"] => :port_impl,
+          ["PortOperation", "reference_to"] => :reference_to_impl,
+          ["PortOperation", "attribute"] => :attribute_impl,
+          ["Translation", "aggregate"] => :aggregate_impl,
+          ["TranslationAggregate", "rename"] => :rename_impl,
+          ["TranslationAggregate", "move"] => :move_impl,
+          ["TranslationAggregate", "convert"] => :convert_impl,
+          ["TranslationAggregate", "retype"] => :retype_impl,
+          ["TranslationAggregate", "compute"] => :compute_impl,
+          ["TranslationAggregate", "rekey"] => :rekey_impl,
+          ["TranslationAggregate", "backfill"] => :backfill_impl,
+          ["TranslationAggregate", "unresolved"] => :unresolved_impl,
+          ["Query", "limit"] => :limit_impl,
+          ["Query", "offset"] => :offset_impl,
+          ["ReadModel", "limit"] => :limit_impl,
+          ["ReadModel", "offset"] => :offset_impl
+        }.freeze
+
+        # [word, context] => the RuleReference primitive a bare reference resolves through.
+        RESOLVES = {
+          ["given", "Aggregate"] => { resolves_via: "owner_keyed", disambiguator: "declared_by" }.freeze,
+          ["given", "Command"] => { resolves_via: "hash_chain" }.freeze,
+          ["given", "Entity"] => { resolves_via: "owner_keyed", disambiguator: "declared_by" }.freeze,
+          ["invariant", "ValueObject"] => { resolves_via: "sibling_scan" }.freeze
+        }.freeze
+      end
+    end
+  end
+end