hecks 1.4.0 → 1.5.0

data/lib/hecks/naming.rb

@@ -18,9 +18,19 @@ module Hecks
 
     module_function
 
-    # The parts of an identity, joined in declaration order.
+    # Joins the parts of an identity in declaration order.
+    #
+    # @param parts [Array<#to_s>, #to_s] one or more identity segments; a bare
+    #   value is wrapped in a single-element Array
+    # @return [String] the segments joined with `IDENTITY_JOIN`
     def identity(parts) = Array(parts).join(IDENTITY_JOIN)
 
+    # Strips a namespace path down to its last segment.
+    #
+    # @param type [Module, String, Symbol, #to_s] a `::`-joined constant path, or
+    #   anything whose `to_s` is one
+    # @return [String] the text after the last `::`, or the whole `to_s` if there
+    #   is none
     def demodulise(type)
       type.to_s.split("::").last.to_s
     end
@@ -28,10 +38,17 @@ module Hecks
     # 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.
+    #
+    # @param text [String, Symbol, #to_s] a snake_case (or already Pascal) name
+    # @return [String] the PascalCase form
     def pascal(text)
       text.to_s.split("_").map { |part| part.sub(/\A(.)/) { Regexp.last_match(1).upcase } }.join
     end
 
+    # PascalCase or camelCase -> snake_case.
+    #
+    # @param text [String, Symbol, #to_s] a Pascal-, camel-, or already snake-case name
+    # @return [String] the lowercase, underscore-separated form
     def snake(text)
       text.to_s
           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
@@ -48,6 +65,9 @@ module Hecks
     # nobody says ("Atm"). First word capitalized, the rest lowercased,
     # so a headword reads as sentence case whatever casing it was
     # declared in.
+    #
+    # @param text [String, Symbol, #to_s] a Pascal-, camel-, or snake-case identifier
+    # @return [String] the space-separated, sentence-cased phrase
     def words(text)
       parts = text.to_s
                   .tr("_", " ")
@@ -61,9 +81,14 @@ module Hecks
       end.join(" ")
     end
 
-    # "A, B, and C" / "A or B" — the Oxford-comma list every English
-    # sentence a projection writes wants; lived in `NarrateProjector`
-    # alone until a second projection needed it.
+    # Joins items into the Oxford-comma list — "A, B, and C" / "A or B" —
+    # every English sentence a projection writes wants; lived in
+    # `NarrateProjector` alone until a second projection needed it.
+    #
+    # @param items [Array<#to_s>] the items to join
+    # @param conj [String] the word before the last item, such as `"and"` or `"or"`
+    # @return [String] `""` for no items, the item's `to_s` for one, and the
+    #   Oxford-comma join for more
     def to_sentence_list(items, conj: "and")
       case items.size
       when 0 then ""
@@ -73,9 +98,12 @@ module Hecks
       end
     end
 
-    # The vowel-letter heuristic — safe here for the same reason
-    # `Projections::Statements#article` gives: a construct name is a
-    # plain word, never "hour" or "university".
+    # Picks the article for `word` by its first letter — the vowel-letter
+    # heuristic, safe here for the same reason `Projections::Statements#article`
+    # gives: a construct name is a plain word, never "hour" or "university".
+    #
+    # @param word [String, Symbol, #to_s] the word the article precedes
+    # @return [String] `"an"` if `word` starts with a vowel letter, `"a"` otherwise
     def a_or_an(word)
       %w[a e i o u].include?(word.to_s[0].to_s.downcase) ? "an" : "a"
     end
@@ -89,6 +117,9 @@ module Hecks
     # the wrong rule against itself. Agreement is not correctness; it never was.
     #
     # So: one pluraliser, three rules, and every collection name flows through it.
+    #
+    # @param text [String, Symbol, #to_s] a singular name
+    # @return [String] the pluralised name
     def plural(text)
       word = text.to_s
       return "#{word[0..-2]}ies" if word.match?(/[^aeiou]y\z/)
@@ -104,6 +135,9 @@ module Hecks
     # 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.
+    #
+    # @param text [String, Symbol, #to_s] a plural name
+    # @return [String] the singularised name
     def singularize(text)
       word = text.to_s
       return "#{word[0..-4]}y" if word.length > 3 && word.end_with?("ies")
@@ -124,25 +158,47 @@ module Hecks
       word
     end
 
+    # Derives the attribute name a reference to `type` is stored under.
+    #
+    # @param type [Module, String, Symbol, #to_s] the referenced construct's name
+    #   or a `::`-joined path to it
+    # @return [Symbol] the snake_case, demodulised name, as a Symbol
     def reference_key(type)
       snake(demodulise(type)).to_sym
     end
 
+    # Splits a `qualifier.name` string on its first dot.
+    #
+    # @param dotted [String, Symbol, #to_s] text, optionally containing a dot
+    # @return [Array(String, String)] `[before the first dot, after it]`; the
+    #   second element is `""` when `dotted` has no dot
     def split_dotted(dotted)
       first, second = dotted.to_s.split(".", 2)
       [first.to_s, second.to_s]
     end
 
+    # The part of a dotted name before its first dot.
+    #
+    # @param dotted [String, Symbol, #to_s] text, optionally containing a dot
+    # @return [String, nil] the text before the first dot, or nil if `dotted`
+    #   has no dot
     def qualifier(dotted)
       text = dotted.to_s
       text.include?(".") ? text.split(".", 2).first : nil
     end
 
+    # The part of a dotted name after its first dot.
+    #
+    # @param dotted [String, Symbol, #to_s] text, optionally containing a dot
+    # @return [String] the text after the first dot, or the whole text if
+    #   `dotted` has no dot
     def unqualified(dotted)
       text = dotted.to_s
       text.include?(".") ? text.split(".", 2).last : text
     end
 
+    # Splits a domain-qualified verb into its domain, aggregate, and command parts.
+    #
     # Domain, aggregate, then the REST dot-joined into one command path.
     #
     # The `::` boundary between domain and aggregate is unambiguous by
@@ -166,6 +222,11 @@ module Hecks
     # .kind_for` and `ReactionInvocation#resolve_target` both already
     # assume this contract on their own end; this is what actually
     # delivers it to them.
+    #
+    # @param verb [String, Symbol, #to_s] a `Domain::Aggregate.command` (or
+    #   `.query`) path
+    # @return [Array(String, String, String), nil] `[domain, aggregate, command]`,
+    #   or nil if `verb` has no `.` or no `domain::aggregate` before it
     def split_verb(verb)
       path, command = verb.to_s.split(".", 2)
       return nil unless path && command
@@ -178,6 +239,9 @@ module Hecks
       [domain, aggregate, command]
     end
 
+    # Rewrites a bare command constant's trailing `::` into `.`, matching a
+    # command's own FQN separator; a String or Symbol passes through unchanged.
+    #
     # `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
@@ -195,6 +259,10 @@ module Hecks
     # 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.
+    #
+    # @param value [Symbol, String, Module] the command, as a bare constant (a
+    #   `ScopedConstant` module `ConstShim` resolves) or already-dotted text
+    # @return [String] the dotted command reference
     def command_ref(value)
       return value.to_s if value.is_a?(::String) || value.is_a?(::Symbol)
 
@@ -203,6 +271,9 @@ module Hecks
       path.empty? ? text : "#{path}.#{command}"
     end
 
+    # The event-side twin of `command_ref`, kept as its own name because an
+    # event name is not a command name that happens to share a format.
+    #
     # `emits Account::AccountFrozen` / `on Account::AccountFrozen` — the
     # event-side twin of `command_ref`, above (ADR 0025, S6 — "events
     # first-class"). Identical transform (a bare `ScopedConstant`'s last
@@ -212,8 +283,14 @@ module Hecks
     # own name because the two references mean different things even
     # though the rewrite is byte-identical: an event name is not a
     # command name that happens to share a format.
+    #
+    # @param value [Symbol, String, Module] the event, as a bare constant (a
+    #   `ScopedConstant` module `ConstShim` resolves) or already-dotted text
+    # @return [String] the dotted event reference
     def event_ref(value) = command_ref(value)
 
+    # Strips a process manager's event reference down to its bare event name.
+    #
     # `transition Account::AccountDebited => "state"` / `starts_on
     # Transfer::TransferRequested` / `ends_on Transfer::TransferSettled`
     # — a process manager's own event references (ADR 0025, S6),
@@ -240,6 +317,10 @@ module Hecks
     # passes through unchanged either way, exactly like `command_ref`'s
     # own legacy branch — this corpus never spelled one dotted to begin
     # with, so there is nothing here to strip.
+    #
+    # @param value [Symbol, String, Module] the event, as a bare constant (a
+    #   `ScopedConstant` module `ConstShim` resolves) or already-dotted text
+    # @return [String] the bare event name, with any qualifier stripped
     def event_name_ref(value) = demodulise(value)
   end
 end

data/lib/hecks/ports/access_control.rb

@@ -28,8 +28,7 @@ module Hecks
       # No adapter or spec double for this port ships in this repository, so every shape
       # below other than `registry` is adapter-defined: the port forwards it untouched.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param identity_id [Object] adapter-defined identity key, forwarded unchanged
       # @return [Object] adapter-defined session representation
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
@@ -44,8 +43,7 @@ module Hecks
       # answers `issuer`, `subject` and `email`), but nothing in this repository wires the
       # two together, so their shapes here are adapter-defined.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param email [Object] adapter-defined, forwarded unchanged; the person's email
       # @param issuer [Object] adapter-defined, forwarded unchanged; the OIDC issuer that
       #   authenticated the person
@@ -60,8 +58,7 @@ module Hecks
 
       # Asks the domain's adapter which roles it can grant.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @return [Object] adapter-defined collection of grantable roles
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
       #   (see `adapter`)
@@ -71,8 +68,7 @@ module Hecks
 
       # Grants a role to a person, by whatever means the domain's adapter records a grant.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param email [Object] adapter-defined, forwarded unchanged; the person receiving the role
       # @param role [Object] adapter-defined, forwarded unchanged; the role to grant
       # @return [Object] adapter-defined representation of the grant
@@ -84,8 +80,7 @@ module Hecks
 
       # Lists every person the domain's adapter knows about.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @return [Object] adapter-defined collection of people
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
       #   (see `adapter`)

data/lib/hecks/ports/authorization.rb

@@ -31,8 +31,7 @@ module Hecks
 
       # Answers whether an actor holds a live (not ended) grant of a role.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param actor_id [String] the actor whose grants are checked
       # @param role [String, Symbol] the role name to look for, compared as a String
       # @param as_of [Integer, nil] Unix epoch seconds (from `Ports::Clock.now`); a grant whose
@@ -51,8 +50,7 @@ module Hecks
 
       # Answers whether one role may act as another.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param from_role [String, Symbol] the role the caller holds, compared as a String
       # @param to_role [String, Symbol] the role the caller wants to act as, compared as a
       #   String
@@ -67,8 +65,7 @@ module Hecks
 
       # Looks up the role an actor holds right now, rather than checking a guessed one.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param actor_id [String] the actor to look up
       # @return [String, nil] the role name of the actor's first live (not ended) grant, or
       #   nil if it has none; the caller supplies any fallback

data/lib/hecks/ports/identity_assignment.rb

@@ -27,8 +27,7 @@ module Hecks
       # No adapter, spec double or caller of this port ships in this repository, so every
       # shape below other than `registry` is adapter-defined: the port forwards it untouched.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param agg_name [Object] adapter-defined, forwarded unchanged; names the aggregate
       #   whose identity field is being assigned
       # @param field_name [Object] adapter-defined, forwarded unchanged; names the identity

data/lib/hecks/ports/identity_resolution.rb

@@ -19,8 +19,7 @@ module Hecks
 
       # Looks up the id of the identity an authenticated (issuer, subject) pair is linked to.
       #
-      # @param registry [Runtime::Registry] the booted registry, used to resolve the adapter
-      #   and handed on to it
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param issuer [String] the OIDC issuer that authenticated the caller
       # @param subject [String] the OIDC subject the issuer vouches for
       # @return [String, nil] the linked identity's id, usable as an `actor_id` for

data/lib/hecks/ports/key_vault.port

@@ -0,0 +1,6 @@
+Hecks.port "key_vault" do
+  verb    "vaulted_by"
+  signal  :reply
+  answers :issue
+  answers :destroy
+end

data/lib/hecks/ports/key_vault.rb

@@ -0,0 +1,58 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # A subject's own encryption key lives here, one boundary removed from
+    # any event or bluebook attribute — cryptoshredding depends on the key
+    # material never being reachable except through this port's opaque
+    # reference (see `Privacy::SubjectKey`, `lib/hecks/framework/bluebook/
+    # privacy.bluebook`). Resolved the same way `Ports::IdentityGeneration`
+    # resolves its own adapter: one adapter registry-wide answers this
+    # port, not a per-aggregate binding.
+    module KeyVault
+      NAME = "key_vault".freeze
+
+      module_function
+
+      # Mints a fresh per-subject encryption key and hands back an opaque reference to it.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @param subject_id [String] the data subject the key is being issued for
+      # @return [String] an opaque key reference; the key material itself never leaves the
+      #   bound adapter, and is never suitable to store on an event or a bluebook attribute
+      def issue(registry, subject_id:) = adapter(registry).issue(subject_id: subject_id)
+
+      # Irrevocably destroys a key that {#issue} already returned a reference for.
+      #
+      # Ciphertext produced under `key_reference` becomes permanently unrecoverable the
+      # moment this returns — the mechanism a right-to-erasure request satisfies without
+      # rewriting or deleting any event.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @param key_reference [String] the opaque reference {#issue} returned
+      # @return [Boolean] true when a live key was destroyed; false when this reference was
+      #   already destroyed, or was never issued
+      def destroy(registry, key_reference:) = adapter(registry).destroy(key_reference: key_reference)
+
+      # Finds the single adapter bound to this port, refusing an ambiguous wiring.
+      #
+      # @param registry [Runtime::Registry] the booted registry to search
+      # @return [Module] the adapter module or class implementing this port
+      # @raise [Runtime::WiringError] if no adapter, or more than one, implements this port
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can issue or destroy a key"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/tail_merge.rb

@@ -196,6 +196,12 @@ module Hecks
           # duplicate manually after a merge; teaching this intersect
           # about a rekey mapping is real, separate work, deliberately
           # out of scope for rekey's first pass.
+          # @param aggregate [Bluebook::Aggregate] the aggregate to check for conflicting ids
+          # @param edges [Hash] the fork's own era edges, as `names_by_era` reads them
+          # @param era [Integer] the new world's own era
+          # @param cut [Integer] the ordinal the fork happened at
+          # @return [Array<Array(String, String)>] `[storage_name, aggregate_id]` pairs touched
+          #   by both worlds since the cut
           def conflict_ids(aggregate, edges, era, cut)
             names = names_by_era(aggregate, edges)
             olds = (1...era).map { |ancestor| text_literal(names[:storage][ancestor - 1]) }.join(", ")

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/minter.rb

@@ -139,10 +139,28 @@ module Hecks
                   "human approved no longer cover the data; re-run bin/translation_audit with --approve"
           end
 
+          # Refuses a mint that found no translation edge, naming the authoring tools —
+          # or, with scaffolding on, the file it just wrote.
+          #
           # No edge yet: the boot refuses toward the authoring loop —
           # naming both tools and the era ordinal. With HECKS_SCAFFOLD=1
           # the boot runs the scaffold first (an explicit flag, never a
           # silent side-effect) and the refusal names the file it wrote.
+          #
+          # @param registry [Runtime::Registry] the registry, forwarded to `scaffold!` when
+          #   scaffolding is on
+          # @param bluebook [Bluebook::Chapter] the domain, named in the refusal
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, forwarded
+          #   to `scaffold!` when scaffolding is on
+          # @param latest [Hash{Symbol => Object}] the newest held era, forwarded to
+          #   `scaffold!` when scaffolding is on
+          # @param ordinal [Integer] the ordinal of the era about to be minted, named in
+          #   the refusal
+          # @param directory [String, nil] the domain's bluebook directory; scaffolding
+          #   requires this to be present as well as `HECKS_SCAFFOLD=1`
+          # @return [void] never returns
+          # @raise [Runtime::WiringError] always; the message names the scaffolded file
+          #   when `HECKS_SCAFFOLD=1` and `directory` wrote one
           def refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory)
             if ENV["HECKS_SCAFFOLD"] == "1" && directory
               path = scaffold!(registry, bluebook, lineage, latest, directory)
@@ -157,9 +175,19 @@ module Hecks
                   "check it with bin/translation_audit, then boot again"
           end
 
-          # Diff the held era against the current shape and write the edge
+          # Diffs the held era against the current shape and writes the edge
           # file — confident rules inline, ambiguities as parse-refusing
-          # `unresolved` lines. Returns the file path.
+          # `unresolved` lines.
+          #
+          # @param _registry [Runtime::Registry] unused; kept so the signature matches its
+          #   caller's own arguments
+          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage; named so
+          #   `ensure_named!` can mint a name for `latest` first if it has none
+          # @param latest [Hash{Symbol => Object}] the newest held era, as `Lineage#eras`
+          #   returns it
+          # @param directory [String] the domain's bluebook directory to write the edge under
+          # @return [String] the path `Translation::Scaffold::Writer#write!` wrote
           def scaffold!(_registry, bluebook, lineage, latest, directory)
             ensure_named!(lineage, latest)
             latest = lineage.eras.last
@@ -179,9 +207,17 @@ module Hecks
             Translation::Scaffold.write!(directory, edge)
           end
 
+          # Mints a name for an era that has none yet, leaving an already-named era untouched.
+          #
           # Era names are minted once. An era held before any drift was
           # seen has no name yet; it gets one the moment an edge needs to
           # leave it.
+          #
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, which
+          #   records the minted name
+          # @param era [Hash{Symbol => Object}] the era to name, as `Lineage#eras` returns it;
+          #   `:hash` present means it is already named
+          # @return [void]
           def ensure_named!(lineage, era)
             return if era[:hash]
 

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_two.rb

@@ -92,6 +92,12 @@ module Hecks
         # header names. Only reached once `layer_two!` has already ruled
         # out "no declared edge" and "rekeyed" (see its own comment on
         # that second guard); this method assumes both are false.
+        # @param violations [Array<String>] mutated in place with one message per divergent id
+        # @param aggregate [Bluebook::Aggregate] the aggregate being audited
+        # @param declared [Bluebook::Translation] the declared translation to check against
+        # @param before [Hash{String => Hash}] the old world's own records, keyed by id
+        # @param after [Hash{String => Hash}] the new world's own records, keyed by id
+        # @return [void]
         def check_value_preservation!(violations, aggregate, declared, before, after)
           rules = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
           compute_paths = declared.computes.flat_map { |compute| [compute.from, compute.to] }.map(&:to_s)

data/lib/hecks/ports/persistence/plugins/era/translation/rule_compiler.rb

@@ -26,6 +26,13 @@ module Hecks
       # in the reference transform's phase order (renames, moves,
       # converts, drops), computes last. `retype` compiles to nothing:
       # stored state never carries a type name.
+      # Compiles a declared edge's rename/move/convert/drop/compute rules into one nested SQL
+      # expression over the `state` jsonb column.
+      #
+      # @param declared [Bluebook::TranslationAggregate] this edge's declared rules for one
+      #   aggregate
+      # @return [String] a SQL expression, `"state"` unchanged when `declared` declares none
+      #   of the five rule kinds
       def compile_rules(declared)
         expression = "state"
         declared.renames.each do |old_name, new_name|
@@ -57,6 +64,11 @@ module Hecks
       # `Ports::Persistence::Lineage` wrapper the app-level consumers
       # (coverage_check.rb, minter.rb, layer_two.rb) go through — this
       # module builds SQL straight off the IR either way.
+      # Reports whether an edge's declared rules for an aggregate include a rekey.
+      #
+      # @param declared [Bluebook::TranslationAggregate, nil] this edge's declared rules for
+      #   one aggregate; nil for an aggregate the edge declares nothing about
+      # @return [Boolean] true when `declared` is present and its `rekeys` is non-empty
       def rekeyed?(declared) = declared && !declared.rekeys.empty?
 
       # The only two places `aggregate_id` needs to change — guarded so
@@ -64,6 +76,12 @@ module Hecks
       # declared) stays the bare `aggregate_id` passthrough it always
       # was — this case only appears in an edge that actually declares
       # one.
+      #
+      # @param guard [String] a SQL boolean expression gating when the rekey applies, such as
+      #   `"operation = 'save'"`
+      # @param declared [Bluebook::TranslationAggregate] this edge's declared rules; must
+      #   declare a rekey (`rekeyed?(declared)` true)
+      # @return [String] a `"CASE WHEN ... END AS aggregate_id"` SQL expression
       def id_case(guard, declared)
         "CASE WHEN #{guard} THEN #{compile_id_expression(declared)} ELSE aggregate_id END AS aggregate_id"
       end
@@ -75,6 +93,11 @@ module Hecks
       # it needs to see first — it reads the record's stored fields
       # exactly as they already are, the same `__s` convention
       # `compile_compute` exposes.
+      #
+      # @param declared [Bluebook::TranslationAggregate] this edge's declared rules; its
+      #   first `rekeys` entry supplies the SQL
+      # @return [String] a SQL expression evaluating the rekey's own SQL against the record's
+      #   current `state`
       def compile_id_expression(declared)
         rekey = declared.rekeys.first
         "(SELECT (#{rekey.sql}) FROM (SELECT (state) AS __s) __outer)"
@@ -84,6 +107,12 @@ module Hecks
       # — evaluated exclusively inside the compiled head, never
       # in-process. The old field is exposed under its own name (as
       # text, exactly as the author's expression expects to cast it).
+      #
+      # @param expression [String] the SQL expression built so far by `compile_rules`, read as
+      #   `__s` inside the compute's own SQL
+      # @param compute [Bluebook::TranslationCompute] the declared compute rule
+      # @return [String] `expression` wrapped so the compute's field lands at its declared
+      #   destination when the source field is present, unchanged otherwise
       def compile_compute(expression, compute)
         from = compute.from.to_s
         to = compute.to.to_s
@@ -103,13 +132,24 @@ module Hecks
       # non-Postgres-bound domain (there are none today, but nothing
       # here should assume there never will be) doesn't gain a hard
       # dependency on `pg` just by loading this file.
+      #
+      # @param name [String, Symbol] the identifier to quote
+      # @return [String] `name` as a double-quoted Postgres identifier
       def quote(name)
         require "pg"
         PG::Connection.quote_ident(name.to_s)
       end
 
+      # Renders a Ruby value as a single-quoted SQL text literal, escaping embedded quotes.
+      #
+      # @param text [String, Symbol, Object] the value to render; converted with `to_s`
+      # @return [String] a single-quoted SQL literal
       def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
 
+      # Renders a dotted path as a SQL `text[]` array literal, one element per segment.
+      #
+      # @param path [String, Symbol] a bare or dotted path, such as `"price.cents"`
+      # @return [String] a SQL `ARRAY[...]::text[]` expression
       def path_literal(path)
         segments = path.to_s.split(".").map { |segment| text_literal(segment) }
         "ARRAY[#{segments.join(', ')}]::text[]"