hecks 1.3.0 → 1.5.0

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

@@ -2,23 +2,22 @@ require "json"
 
 module Hecks
   module Translation
-    # The closed, PURE half of Postgres's own SQL compiler
-    # (adapters/driven/postgres_era/lineage/head_compiler.rb) — the part
-    # that turns one TranslationAggregate's declared rules into a
-    # jsonb-transforming SQL expression. No database connection, no
-    # watermark, no era chain, no catalog lookup: those stay exactly
-    # where they were, in head_compiler.rb's own per-mint assembly,
-    # which calls into this module instead of defining these methods
-    # itself.
+    # The closed, pure half of Postgres's own SQL compiler
+    # (ports/persistence/plugins/era/postgres_era/lineage/head_compiler.rb)
+    # — the part that turns one TranslationAggregate's declared rules into
+    # a jsonb-transforming SQL expression. No database connection, no
+    # watermark, no era chain, no catalog lookup: those live in
+    # head_compiler.rb's own per-mint assembly, which calls into this
+    # module instead of defining these methods itself.
     #
-    # Extracted here — not left as private methods on
-    # Adapters::PostgresEra::Lineage — so a SECOND, adapter-agnostic
+    # A module of its own — not private methods on
+    # Adapters::PostgresEra::Lineage — so a second, adapter-agnostic
     # caller (Exporter.translation_aggregate's build-time SQL export,
     # feeding rust/host's own future boot-time mint) can call the exact
-    # SAME code Ruby's own mint path runs, not a hand-ported duplicate
-    # that could silently drift the way `Exporter.translation_hash`
-    # drifted from `hecks_eras`/`hecks_approvals`' real schema before
-    # this file existed (rekeys/backfills were missing for years).
+    # same code Ruby's own mint path runs, not a hand-ported duplicate
+    # that could silently drift the way a hand-kept
+    # `Exporter.translation_hash` can drift from `hecks_eras`/
+    # `hecks_approvals`' real schema (leaving out rekeys and backfills).
     module RuleCompiler
       module_function
 
@@ -27,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|
@@ -51,31 +57,47 @@ module Hecks
         expression
       end
 
-      # Whether THIS edge's declared rules for this aggregate include a
+      # Whether this edge's declared rules for this aggregate include a
       # rekey — checked directly off the raw IR object, the same way
       # every other rule kind is already read in `compile_rules`
       # (`declared.computes`, `declared.moves`, ...), not through the
       # `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
+      # The only two places `aggregate_id` needs to change — guarded so
       # the generated SQL for the overwhelming common case (no rekey
       # declared) stays the bare `aggregate_id` passthrough it always
-      # was — this CASE only appears in an edge that actually declares
+      # 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
 
-      # THE REKEY'S OWN SQL — reading `state` directly, not the
+      # The rekey's own SQL — reading `state` directly, not the
       # progressively-built `expression` chain `compile_compute` reads
       # from. A rekey doesn't consume or move any field the way a move
       # or compute does, so there is no same-edge rename/move ordering
       # 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)"
@@ -85,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
@@ -96,7 +124,7 @@ module Hecks
           "LATERAL (SELECT (__s ->> #{text_literal(from)}) AS #{quote(from)}) __fields)"
       end
 
-      # `PG::Connection.quote_ident` needs the `pg` gem LOADED, not
+      # `PG::Connection.quote_ident` needs the `pg` gem loaded, not
       # connected — required here, lazily, the same "a domain that
       # never wires PostgresEra should never need the gem" reasoning
       # `PostgresEra.connect_for`'s own `require "pg"` already holds
@@ -104,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[]"

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/differ.rb

@@ -8,6 +8,13 @@ module Hecks
       # everything ambiguous left unresolved for a human.
       module Differ
         # Diff two bluebook IRs into the edge's declarations.
+        #
+        # @param held_bluebook [Bluebook::Chapter] the era being translated from
+        # @param current_bluebook [Bluebook::Chapter] the era being translated to
+        # @return [Hash{Symbol => Object}] `:aggregates` (Array<Scaffold::ScaffoldedAggregate>,
+        #   one per matched aggregate carrying a rename or a rule), `:retired` (Array<String>,
+        #   vanished aggregate names with no successor), `:unclaimed` (Array<String>, vanished
+        #   aggregate names left ambiguous)
         def diff(held_bluebook, current_bluebook)
           held_shapes = projections(held_bluebook)
           current_shapes = projections(current_bluebook)
@@ -27,17 +34,31 @@ module Hecks
           { aggregates: aggregates, retired: matched[:retired], unclaimed: matched[:unclaimed] }
         end
 
+        # Projects a bluebook's storage shape and indexes its aggregates by name.
+        #
+        # @param bluebook [Bluebook::Chapter] the bluebook to project
+        # @return [Hash{String => Hash}] the bluebook's storage-shape aggregates (see
+        #   `Runtime::StorageShape.project`), keyed by aggregate name
         def projections(bluebook)
           Runtime::StorageShape.project(bluebook)["aggregates"].to_h { |shape| [shape["name"], shape] }
         end
 
         # A vanished aggregate whose full shape reappears under exactly one
-        # new name was renamed. `retired` is only confident when NOTHING
+        # new name counts as a rename. `retired` is only confident when nothing
         # remains it could plausibly have become — a vanished aggregate
         # beside an unmatched new one might be a rename-plus-reshape, and
         # writing `retired` there would be a guess that strands data.
         # Anything ambiguous stays unclaimed, and the coverage gate names
         # it until a human decides.
+        #
+        # @param held_shapes [Hash{String => Hash}] the held era's aggregate shapes, keyed by
+        #   name (see `projections`)
+        # @param current_shapes [Hash{String => Hash}] the current era's aggregate shapes,
+        #   keyed by name
+        # @return [Hash{Symbol => Object}] `:pairs` (Hash{String => String, nil}, each current
+        #   name to its matched held name, or nil when unmatched), `:retired` (Array<String>,
+        #   vanished names with no successor), `:unclaimed` (Array<String>, vanished names
+        #   left ambiguous)
         def match_aggregates(held_shapes, current_shapes)
           pairs = {}
           current_shapes.each_key { |name| pairs[name] = held_shapes.key?(name) ? name : nil }
@@ -61,12 +82,19 @@ module Hecks
         end
 
         # Every changed path in one aggregate, resolved into rules by
-        # signature matching over the FULL path set — top-level names and
+        # signature matching over the full path set — top-level names and
         # dotted members alike. Unique signature pair: a rename (both
         # top-level) or a move (any dotted end). Same path, same members,
         # new type name: a retype. Anything else: unresolved, carrying its
         # type-compatible candidates (an empty list is the arrow toward
         # compute, or drop).
+        #
+        # @param held_shape [Hash{String => Object}] the held era's aggregate shape (see
+        #   `projections`)
+        # @param current_shape [Hash{String => Object}] the current era's aggregate shape
+        # @return [Array<Hash{Symbol => Object}>] one rule Hash per changed path — `:kind`
+        #   plus `:from`/`:to` for `:rename`/`:move`/`:retype`, or `:from`/`:candidates` for
+        #   `:unresolved` (see `Renderer#render_rule`); `[]` when nothing changed
         def attribute_rules(held_shape, current_shape)
           rules = []
           rules << identity_hint(held_shape, current_shape)
@@ -81,7 +109,7 @@ module Hecks
           appeared = appeared_paths(held_attrs, current_attrs, retyped)
 
           # Mutates `rules` in place (not build-and-concat, like the two
-          # passes above) because it must READ its own earlier writes:
+          # passes above) because it must read its own earlier writes:
           # `taken`, below, is recomputed from `rules` at the top of every
           # iteration, so a target this same loop already claimed for an
           # earlier vanished path is excluded from a later one. Passing a
@@ -92,7 +120,14 @@ module Hecks
         end
 
         # retype pass: same attribute name, same member structure, the
-        # TYPE's own name changed
+        # type's own name changed
+        #
+        # @param held_attrs [Hash{String => Hash}] the held era's attributes, keyed by name
+        # @param current_attrs [Hash{String => Hash}] the current era's attributes, keyed by
+        #   name
+        # @return [Array<Hash{Symbol => String}>] one `{kind: :retype, from:, to:}` rule per
+        #   attribute whose members are unchanged but whose type name changed; `[]` when none
+        #   match
         def retype_rules(held_attrs, current_attrs)
           (held_attrs.keys & current_attrs.keys).filter_map do |name|
             held = held_attrs[name]
@@ -105,6 +140,16 @@ module Hecks
           end
         end
 
+        # Resolves each vanished path into a rename, move or unresolved rule, appended to
+        # `rules` in place.
+        #
+        # @param rules [Array<Hash{Symbol => Object}>] the rule list to append to; also read
+        #   for `:rename`/`:move` targets an earlier iteration already claimed
+        # @param vanished [Hash{String => Object}] vanished paths to type signature (see
+        #   `vanished_paths`)
+        # @param appeared [Hash{String => Object}] appeared paths to type signature (see
+        #   `appeared_paths`)
+        # @return [void]
         def resolve_vanished_rules!(rules, vanished, appeared)
           vanished.each do |path, signature|
             matches = appeared.select { |_, candidate| candidate == signature }.keys
@@ -125,6 +170,14 @@ module Hecks
         # and members that vanished (or changed type) inside a kept
         # attribute — mirroring exactly what EraGuard will demand coverage
         # for.
+        #
+        # @param held_attrs [Hash{String => Hash}] the held era's attributes, keyed by name
+        # @param current_attrs [Hash{String => Hash}] the current era's attributes, keyed by
+        #   name
+        # @param retyped [Array<String>] type names already claimed by a `:retype` rule,
+        #   excluded here
+        # @return [Hash{String => Object}] each vanished or changed path, dotted for a member,
+        #   valued by that path's type signature
         def vanished_paths(held_attrs, current_attrs, retyped)
           paths = {}
           held_attrs.each do |name, held|
@@ -146,6 +199,17 @@ module Hecks
           paths
         end
 
+        # Current paths that need explaining: whole attributes that appeared, and members
+        # that appeared (or changed type) inside a kept attribute — the mirror of
+        # `vanished_paths`.
+        #
+        # @param held_attrs [Hash{String => Hash}] the held era's attributes, keyed by name
+        # @param current_attrs [Hash{String => Hash}] the current era's attributes, keyed by
+        #   name
+        # @param retyped [Array<String>] type names already claimed by a `:retype` rule,
+        #   excluded here
+        # @return [Hash{String => Object}] each appeared or changed path, dotted for a
+        #   member, valued by that path's type signature
         def appeared_paths(held_attrs, current_attrs, retyped)
           paths = {}
           current_attrs.each do |name, current|
@@ -166,31 +230,58 @@ module Hecks
           paths
         end
 
-        # THE ONE THING `attribute_rules` COULD NOT SEE BEFORE — the shape
+        # The one thing `attribute_rules` could not see before — the shape
         # projection already carries `"identity"` (`StorageShape
         # .project_aggregate`), it was simply never read here. An
         # unresolved placeholder, not a guess: `coverage_check.rb`'s own
         # `check_identity_unchanged!` is the real gate this only hints
         # toward, the same "tool proactively guides you" pattern the
         # generic unresolved message already gives unfed fields.
+        #
+        # @param held_shape [Hash{String => Object}] the held era's aggregate shape
+        # @param current_shape [Hash{String => Object}] the current era's aggregate shape
+        # @return [Hash{Symbol => Object}, nil] `{kind: :unresolved, from: :identity,
+        #   candidates: []}` when the identity paths differ; nil when they match
         def identity_hint(held_shape, current_shape)
           return if held_shape["identity"] == current_shape["identity"]
 
           { kind: :unresolved, from: :identity, candidates: [] }
         end
 
+        # Finds appeared paths type-compatible with a vanished path's own signature.
+        #
+        # @param appeared [Hash{String => Object}] appeared paths to type signature (see
+        #   `appeared_paths`)
+        # @param signature [Object] the vanished path's own type signature to match against
+        # @return [Array<String>] appeared paths whose scalar signature (see `scalar_of`)
+        #   matches `signature`'s
         def compatible_candidates(appeared, signature)
           appeared.select { |_, candidate| scalar_of(candidate) == scalar_of(signature) }.keys
         end
 
+        # Reduces a type signature to the shape `compatible_candidates` compares by.
+        #
+        # @param signature [Object, Hash] a path's type signature
+        # @return [Object] `signature["members"]` for a container Hash, else `signature`
+        #   unchanged
         def scalar_of(signature) = signature.is_a?(Hash) ? signature["members"] : signature
 
+        # Reads a container attribute's own members, keyed by name.
+        #
+        # @param attribute [Hash{String => Object}] one path's type signature
+        # @return [Hash{String => Object}] each member's name to its type; `{}` when
+        #   `attribute` is not a container
         def members_of(attribute)
           return {} unless container?(attribute)
 
           attribute["type"]["members"].to_h { |member| [member["name"], member["type"]] }
         end
 
+        # Reports whether a type signature is a container (value object or entity), not a
+        # scalar.
+        #
+        # @param attribute [Hash{String => Object}] one path's type signature
+        # @return [Boolean] true if `attribute["type"]` is a Hash, false for a scalar
         def container?(attribute) = attribute["type"].is_a?(Hash)
       end
     end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/renderer.rb

@@ -5,6 +5,10 @@ module Hecks
       # ambiguities as parse-refusing `unresolved` constructs, never
       # comments, so an unresolved file can only boot into a refusal.
       module Renderer
+        # Renders a scaffolded edge as loadable `.bluebook` translation source.
+        #
+        # @param edge [Scaffold::Edge] the edge to render
+        # @return [String] the edge's `.bluebook` text, ending in a newline
         def render(edge)
           lines = ["Hecks.data_translation #{edge.domain.inspect}, from: #{edge.from.inspect}, to: #{edge.to.inspect} do"]
           edge.aggregates.each do |aggregate|
@@ -19,6 +23,12 @@ module Hecks
           "#{lines.join("\n")}\n"
         end
 
+        # Renders one scaffolded rule as a line of `.bluebook` source.
+        #
+        # @param rule [Hash{Symbol => Object}] a rule Hash as `Differ#attribute_rules` builds
+        #   it: `:kind` plus `:from`/`:to`, or `:from`/`:candidates` for `:unresolved`
+        # @return [String, nil] the rendered line; nil if `rule[:kind]` is none of `:rename`,
+        #   `:move`, `:retype` or `:unresolved`
         def render_rule(rule)
           case rule[:kind]
           when :rename then "rename :#{rule[:from]}, to: :#{rule[:to]}"
@@ -30,6 +40,11 @@ module Hecks
           end
         end
 
+        # Renders a path as bluebook source: a Symbol literal when bare, a String literal
+        # when dotted.
+        #
+        # @param path [String, Symbol] a bare or dotted path
+        # @return [String] `":name"` for a bare path, `path.inspect` for a dotted one
         def render_path(path) = path.to_s.include?(".") ? path.to_s.inspect : ":#{path}"
       end
     end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/writer.rb

@@ -6,10 +6,18 @@ module Hecks
       # Put the rendered edge on disk, regenerating in place when a file
       # for the same shape pair already exists.
       module Writer
+        # Renders an edge and writes it under `directory/translations`, regenerating in
+        # place when a file for the same shape pair already exists.
+        #
         # The edge file, regenerated in place when one for the same shape
         # pair already exists (matched textually — an unresolved file
-        # cannot be LOADED to ask, that being the whole point of
+        # cannot be loaded to ask, that being the whole point of
         # unresolved).
+        #
+        # @param directory [String] the domain's root directory
+        # @param edge [Scaffold::Edge] the edge to render and write
+        # @return [String] the path written, either the matched existing file or a new
+        #   `<ordinal>-<label>.bluebook`
         def write!(directory, edge)
           translations_dir = File.join(directory, "translations")
           FileUtils.mkdir_p(translations_dir)

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

@@ -6,13 +6,13 @@ module Hecks
   module Translation
     # The scaffold writes translations; humans resolve ambiguity. It
     # diffs the held era's storage-shape projection against the current
-    # one (scaffold/differ.rb) and WRITES the edge file
+    # one (scaffold/differ.rb) and writes the edge file
     # (scaffold/renderer.rb, scaffold/writer.rb): confident rules inline
     # (unique signature pairs → rename/move, aggregate renames → `was:`,
     # type renames with identical members → retype, aggregates gone
     # without a successor → retired), ambiguities as parse-refusing
     # `unresolved` constructs — never comments, so an unresolved file can
-    # only boot into a refusal, never a guess. It NEVER proposes a
+    # only boot into a refusal, never a guess. It never proposes a
     # `compute` (a computation takes domain judgment no mechanical diff
     # can infer) — an empty-candidate `unresolved` is what points the
     # author there. It never proposes a `drop` either: data loss is a

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

@@ -11,7 +11,7 @@ module Hecks
   module Ports
     module Persistence
       module Plugins
-        # ADR 0033 — requiring THIS FILE is installing the plugin. Nothing in
+        # ADR 0033 — requiring this file is installing the plugin. Nothing in
         # Hecks core requires it; an app that binds `PostgresEra`, or wants
         # schema-translation support at all, requires it explicitly — the
         # same shape every adapter-specific spec fixture already uses to
@@ -19,6 +19,8 @@ module Hecks
         module Era
           module_function
 
+          # Registers this plugin's era gates on one boot's gate list.
+          #
           # `Runtime::Loader.run_boot_gates!` asks every loaded persistence
           # plugin to contribute here, generically — it never mentions
           # `EraCheck` or "era" by name. Two gates, both `:pre_verify`:
@@ -29,11 +31,19 @@ module Hecks
           # unchanged) — this is the rich, adapter-aware version of that
           # check; `Runtime::Loader`'s own structural backstop (plain
           # `Bluebook::Translation` data, no plugin-specific class) only
-          # ever fires when NO persistence plugin is loaded at all.
+          # ever fires when no persistence plugin is loaded at all.
           #
           # `:era_check` — conditional, exactly ADR 0031's own gate,
           # unchanged: registered only when this registry has an aggregate
           # actually bound to a lineage-capable adapter.
+          #
+          # @param registry [Runtime::Registry] the registry being booted, asked whether any
+          #   bluebook's first aggregate is bound to a lineage-capable adapter
+          # @param gates [Runtime::BootGates] this boot's gate list, registered onto in place
+          # @return [Runtime::BootGates, nil] `gates` when `:era_check` was registered; nil when
+          #   the registry binds nothing lineage-capable, so only `:era_compute_rules` was added
+          # @raise [Runtime::WiringError] if an aggregate's persistence binding is missing,
+          #   ambiguous, or carries an unsupported role
           def contribute_boot_gates(registry, gates)
             gates.register(:era_compute_rules, lambda { |reg, _dir|
               Runtime::EraCheck.check_compute_rules_for_registry!(reg)

data/lib/hecks/ports/persistence/remote_runtime.rb

@@ -3,12 +3,12 @@ require_relative "../../runtime/registry"
 module Hecks
   module Ports
     module Persistence
-      # THE OTHER SHAPE AN ADAPTER CAN BE. `AppendOnly` names one shape
+      # The other shape an adapter can be. `AppendOnly` names one shape
       # already — something that stores bytes, locally (Postgres, SQLite,
       # Heki) or over the network (D1), doesn't matter, the point is it
       # does real local interpretation and has real entries to replay.
       # This names the second, different shape: not "storage reached
-      # remotely," but the real INTERPRETER itself living behind a call
+      # remotely," but the real interpreter itself living behind a call
       # boundary — `append`/`project` don't do partial local work and
       # then fail, they raise unconditionally, because there is no local
       # write-ahead log to have; `entries` is always `[]` for the same
@@ -28,6 +28,10 @@ module Hecks
       # `Runtime::RemoteDispatcher`'s own use) instead of comparing
       # adapter names by string.
       module RemoteRuntime
+        # Refuses every local write; `project` is an alias and refuses the same way.
+        #
+        # @return [void] never returns
+        # @raise [Runtime::WiringError] always, pointing the caller at `Runtime::RemoteDispatcher`
         def append(*)
           raise Runtime::WiringError,
                 "#{self.class.name} is a remote-runtime delegate — dispatch through " \
@@ -35,6 +39,9 @@ module Hecks
         end
         alias project append
 
+        # Reports an empty journal, since a remote-runtime delegate keeps no local log.
+        #
+        # @return [Array] always `[]`
         def entries = []
       end
     end

data/lib/hecks/ports/persistence/repository_factory.rb

@@ -1,13 +1,33 @@
 require_relative "append_only"
+require_relative "codec_boundary"
 
 module Hecks
   module Ports
     module Persistence
       # Turns a declared adapter binding plus its world configuration into a
       # concrete repository. Selection policy stays out of adapter creation.
+      #
+      # Every adapter it builds is guarded (`CodecBoundary.guard!`) before
+      # anything else touches it — `recover!` included — so no adapter a
+      # runtime reaches can build an `Instance` from undecoded state.
       module RepositoryFactory
         module_function
 
+        # Instantiates the adapter a bind names, guards it, and wraps it as a repository.
+        #
+        # @param registry [Runtime::Registry] the registry supplying the adapter class, the
+        #   domain's world settings, its resolved eras and the root path
+        # @param domain [String, Symbol] name of the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate to persist
+        # @param bind [Bluebook::Bind] the bind naming the adapter, as `BindingPolicy.resolve`
+        #   or the projection port chose it
+        # @param recover [Boolean] true to replay the journal through `project` before returning
+        # @param settings_verb [String] the verb whose world settings configure the adapter;
+        #   `"persisted_by"` by default, `Ports::Projection::VERB` for a projection
+        # @return [Persistence::AppendOnly] the repository over the guarded adapter
+        # @raise [Runtime::WiringError] if the bind's verb or settings fail the registry's
+        #   checks, no `Hecks::Adapters` constant matches the adapter name, or the adapter
+        #   lacks `append`, `project` or `entries`
         def build(registry, domain, aggregate, bind, recover: true, settings_verb: VERB)
           registry.check_verb(bind)
           settings = (registry.world(domain)&.for_binding(settings_verb, bind.adapter) || {})
@@ -15,8 +35,8 @@ module Hecks
           registry.check_settings(bind, settings)
           # The domain, the resolved era, and (for an old checkout) the era
           # that superseded it ride along after the declared-settings
-          # check: a lineage adapter journals per DOMAIN, writes into its
-          # own ERA's partition, and refuses to write at all once that era
+          # check: a lineage adapter journals per domain, writes into its
+          # own era's partition, and refuses to write at all once that era
           # is superseded (`PostgresEra#append`, BUG#24) — none of which a
           # world's settings carry.
           adapter = registry.adapter_class(bind.adapter)
@@ -24,7 +44,7 @@ module Hecks
                                  settings:  settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s],
                                                            superseded_by: registry.superseded_eras[domain.to_s]),
                                  root:      registry.root)
-          repository = AppendOnly.new(adapter)
+          repository = AppendOnly.new(CodecBoundary.guard!(adapter))
           recover ? repository.recover! : repository
         end
       end