hecks 2.8.0 → 3.0.0

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

@@ -4,20 +4,8 @@ require_relative "scaffold/writer"
 
 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
-    # (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
-    # `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
-    # decision, not a default. Re-running regenerates the file, matched
-    # by shape pair.
+    # Diffs the held era's storage shape against the current one and writes the edge file.
+    # Ambiguities become parse-refusing `unresolved` constructs; it never proposes compute or drop.
     module Scaffold
       Edge = Struct.new(:domain, :from, :to, :ordinal, :label, :aggregates, :retired, keyword_init: true)
       ScaffoldedAggregate = Struct.new(:name, :was, :rules, keyword_init: true)

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

@@ -9,3 +9,4 @@ require_relative "translation/rule_compiler"
 require_relative "translation/scaffold"
 require_relative "translation/audit"
 require_relative "translation/reattest"
+require_relative "translation/approval_file"

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

@@ -11,34 +11,15 @@ module Hecks
   module Ports
     module Persistence
       module Plugins
-        # ADR 0033 — requiring this file is installing the plugin. Nothing in
-        # Hecks core requires it. A boot loads it on demand for a domain that
-        # binds `PostgresEra` (`Runtime::Loader.load_bound_adapters!` resolves the
-        # adapter, which autoloads this file, before the gates are collected). An
-        # app that wants schema-translation support without binding `PostgresEra`
-        # requires it explicitly, the same shape every adapter-specific spec
-        # fixture already uses to load one particular `.adapter` file rather than
-        # all of them.
+        # ADR 0033 — requiring this file installs the plugin; nothing in Hecks core
+        # requires it, so it loads only for a domain that binds `PostgresEra` (or asks explicitly).
         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`:
-          #
-          # `:era_compute_rules` — unconditional, whenever this plugin is
-          # loaded at all. A `compute`/`rekey` rule requires Postgres
-          # whatever adapter is actually bound (ADR 0031's own reasoning,
-          # 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.
-          #
-          # `: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.
+          # Two `:pre_verify` gates: `era_compute_rules` always runs; `era_check` (ADR 0031)
+          # runs only when the registry binds something lineage-capable.
           #
           # @param registry [Runtime::Registry] the registry being booted, asked whether any
           #   bluebook's first aggregate is bound to a lineage-capable adapter

data/lib/hecks/ports/persistence/postgres_dump/connection.rb

@@ -4,39 +4,28 @@ module Hecks
   module Ports
     module Persistence
       class PostgresDump
-        # A Postgres connection URL, split so a password reaches the tools run
-        # against it through their environment and never on a command line, where
-        # any user of the machine can read it from the process list.
+        # A Postgres connection URL, split so a password reaches child-process tools
+        # through their environment, never on a command line the process list exposes.
         class Connection
-          # @param url [String] a `postgres://` or `postgresql://` URL
-          # @raise [PostgresDump::Error] if `url` is not a Postgres URL
           def initialize(url)
             @uri = URI.parse(url)
             raise Error, "not a postgres URL" unless %w[postgres postgresql].include?(@uri.scheme)
           end
 
-          # Names the database the URL points at.
-          #
-          # @return [String] the database name, empty when the URL names none
+          # Names the database the URL points at, empty when the URL names none.
           def database
             @uri.path.to_s.delete_prefix("/")
           end
 
-          # Points the same server and credentials at another database.
-          #
-          # @param name [String] the database to connect to instead
-          # @return [Connection] a new connection; this one is unchanged
+          # Points the same server and credentials at another database; this one is unchanged.
           def with_database(name)
             copy = @uri.dup
             copy.path = "/#{name}"
             self.class.new(copy.to_s)
           end
 
-          # Lists the connection settings the URL carries, in `PG.connect` keyword form.
-          #
-          # @return [Hash{Symbol => String, Integer}] `host`, `port`, `user`, `password`,
-          #   `dbname` and `sslmode`, each only when the URL gives one; the user and password
-          #   are percent-decoded
+          # Lists the connection settings the URL carries, in `PG.connect` keyword form; the
+          # user and password come back percent-decoded.
           def settings
             {
               host: (@uri.host unless @uri.host.to_s.empty?), port: @uri.port,
@@ -46,16 +35,11 @@ module Hecks
           end
 
           # Builds the libpq environment variables for a child process.
-          #
-          # @return [Hash{String => String}] `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`,
-          #   `PGDATABASE` and `PGSSLMODE`, each only when `settings` has the matching key
           def env
             settings.to_h { |key, value| ["PG#{key.to_s.sub('dbname', 'database').upcase}", value.to_s] }
           end
 
-          # Opens a connection with the `pg` gem.
-          #
-          # @return [PG::Connection] an open connection; the caller closes it
+          # Opens a connection with the `pg` gem; the caller closes it.
           def connect
             require "pg"
             PG.connect(**settings)

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

@@ -5,42 +5,16 @@ require_relative "postgres_dump/connection"
 module Hecks
   module Ports
     module Persistence
-      # Dumps one schema of a Postgres database and proves the dump restores.
-      #
-      # ## What the proof is
-      #
-      # A dump nobody has restored is a hope. After `pg_dump` writes the file,
-      # the dump is restored into a scratch database (on the source server, or on a
-      # separate `verify_url` server such as the one the dump will be loaded
-      # into) and every table's row count is compared with the source. That shows
-      # the dump is complete and loadable. It does not re-derive current state
-      # from an event journal, so a caller who needs that proves it separately.
-      #
-      # ## Credentials
-      #
-      # URLs are split by `Connection`: the password travels in the child
-      # process's environment, never in `argv`.
-      #
-      # ## Requirements
-      #
-      # The `pg` gem, and `pg_dump` and `pg_restore` on `PATH` at a version no older
-      # than the server's. Neither the gem nor the tools are a dependency of
-      # hecks; nothing here loads until a dump is asked for.
+      # Dumps one schema of a Postgres database and proves the dump restores, by
+      # restoring it into a scratch database and comparing every table's row count.
       class PostgresDump
         # Raised for a refusal or a failed tool.
         class Error < StandardError; end
 
-        # What a verified dump holds.
-        #
-        # @!attribute [r] tables
-        #   @return [Hash{String => Integer}] row count of every table in the schema, by name
+        # What a verified dump holds: `tables` is each table's row count, by name.
         Result = Struct.new(:tables, keyword_init: true)
 
-        # @param url [String] the source database's `postgres://` URL
-        # @param schema [String] the schema to dump, a plain identifier
-        # @param verify_url [String, nil] the server to restore into for the proof; the source
-        #   server when nil
-        # @raise [Error] if `schema` is not a plain identifier or a URL is not a Postgres URL
+        # Splits `url` and `verify_url` into connections and validates `schema`.
         def initialize(url:, schema:, verify_url: nil)
           raise Error, "schema #{schema.inspect} is not a plain identifier" unless schema.to_s.match?(/\A[a-z_][a-z0-9_]*\z/i)
 
@@ -50,11 +24,6 @@ module Hecks
         end
 
         # Writes a custom-format dump of the schema and proves it restores.
-        #
-        # @param dest [String] the file to write
-        # @return [Result] the verified row counts
-        # @raise [Error] if the schema has no tables, a tool fails, the database refuses, or
-        #   the restored counts differ from the source's
         def call(dest)
           require "pg"
           raise Error, "schema #{@schema} has no tables in #{@source.database}" if counting(@source) { |db| counts(db) }.empty?

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

@@ -3,30 +3,8 @@ require_relative "../../runtime/registry"
 module Hecks
   module Ports
     module Persistence
-      # 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
-      # 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
-      # reason (`AppendOnly#recover!` replaying zero entries here is a
-      # correct no-op, not a lie).
-      #
-      # `Adapters::Lambda` is the first adapter to `include` this, not
-      # the only one meant to — any future adapter for some other
-      # remote-runtime target (a different compute platform, a gRPC
-      # stub, whatever) gets this shape for free by including one module
-      # instead of re-deriving the same raise-on-write/always-empty-
-      # entries boilerplate from scratch. And because it's a real,
-      # checkable module rather than an adapter's own ad hoc
-      # implementation, a caller can ask "is this adapter a remote-
-      # runtime delegate?" as a genuine capability check
-      # (`registry.adapter_class(name) <= RemoteRuntime`,
-      # `Runtime::RemoteDispatcher`'s own use) instead of comparing
-      # adapter names by string.
+      # Adapter shape for an interpreter behind a call boundary: no local log, so writes raise.
+      # Detect it with `registry.adapter_class(name) <= RemoteRuntime`, not by adapter name.
       module RemoteRuntime
         # Refuses every local write; `project` is an alias and refuses the same way.
         #

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

@@ -4,48 +4,29 @@ 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.
+      # Turns a declared adapter binding into a concrete repository, guarding every
+      # adapter it builds (`CodecBoundary.guard!`) before `recover!` or anything else touches it.
       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.binding_settings(domain, settings_verb, bind.adapter)
                              .reject { |key, _| key.to_sym == :role }
           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
-          # is superseded (`PostgresEra#append`, BUG#24) — none of which a
-          # world's settings carry.
+          # domain, resolved era and superseding era ride along outside the declared
+          # settings: a lineage adapter needs them to journal per domain, per-era.
           adapter = registry.adapter_class(bind.adapter)
                             .new(aggregate: aggregate,
                                  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(CodecBoundary.guard!(adapter))
-          recover ? repository.recover! : repository
+          # `:atomic_append` (PostgresEra) means `append` already committed the
+          # projected state in the same transaction as the journal row, so a
+          # boot-time replay through `project` has nothing left to fix up.
+          recover && !repository.capabilities.include?(:atomic_append) ? repository.recover! : repository
         end
       end
     end

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

@@ -4,58 +4,11 @@ require_relative "../../runtime/value"
 module Hecks
   module Ports
     module Persistence
-      # One spelling of an aggregate's state across the store boundary
-      # (Phase 2, Track A, PR A2). This codec is the single, IR-driven
-      # answer every adapter converges on, because adapters left to decode
-      # their own way disagree: symbolizing the top level only (a Heki head,
-      # a journal reader), symbolizing deep (a SQL or Lambda head), or never
-      # serializing at all (Memory's shallow `state.dup`).
-      # spec/ports/persistence_legacy_decode_spec.rb pins that bytes written
-      # without the codec still decode to the one canonical shape. Every
-      # adapter writes through `encode` and reads through `decode`
-      # (Memory through `copy`; PR A3), and `CodecBoundary` — installed on every
-      # adapter `RepositoryFactory.build` makes — refuses an `Instance`
-      # built inside an adapter call from state `decoded?` rejects.
+      # Canonical spelling of an aggregate's state across the store boundary;
+      # every adapter's `encode`, `decode` and `copy` route through here.
       #
-      # ## The three operations
-      #
-      # - `encode` — canonical and JSON-ready: string keys at every depth,
-      #   `Runtime::Value`s materialized, only JSON scalars at the leaves.
-      #   Needs no IR (JSON has one spelling), but takes it for symmetry.
-      # - `decode` — walks the aggregate's IR: attributes, value objects
-      #   (their fields, recursively), `list_of` value objects and entities
-      #   (entity fields, nested entities, the entity's own lifecycle),
-      #   references, the lifecycle field, and projected fields. A declared
-      #   key becomes a symbol at every depth, whichever spelling arrived.
-      # - `copy` — `decode(encode(state))`: what a durable adapter would hand
-      #   back, for Memory, with no JSON text in between.
-      #
-      # ## What decode never does
-      #
-      # It never invents a key. A declared field absent from the stored
-      # state stays absent — not a present nil — because the runtime reads
-      # absence as "this record predates the field": `Instance.
-      # hydrate_with_defaults` fills a declared `default:` only when the key
-      # is missing (spec/runtime/hydrate_defaults_spec.rb), Era translation
-      # backfills only `unless state.key?` (era/lineage.rb#translate), and a
-      # required declared-but-absent field reads as a named refusal rather
-      # than nil (spec/runtime/attribute_absence_spec.rb). A present nil
-      # would silently suppress all three. For the same reason it never
-      # drops a key, nil or not: a stored nil stays a stored nil.
-      #
-      # It never touches an undeclared key's value — a retired field, or a
-      # member a value object does not declare, is exactly what an Era
-      # translation (rename/move/drop) still has to read. Its key keeps its
-      # spelling below the top level; at the top level every key is a
-      # symbol, declared or not, because every adapter has always
-      # symbolized the top level and `Lineage#translate` reads retired
-      # top-level names as symbols.
-      #
-      # ## When both spellings arrive
-      #
-      # When a hash carries both spellings of one declared key, the symbol
-      # spelling wins: it can only have been written by Ruby after the
-      # string one was read.
+      # `decode` never invents or drops a declared key: absence must stay absence, since
+      # defaults, era translation and required-field checks all key off it.
       module StateCodec
         JSON_SCALARS = [String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
 
@@ -95,14 +48,8 @@ module Hecks
 
         # Maps every declared top-level field name to its attribute.
         #
-        # The field walk Sqlite::Codec#persisted_fields does for columns,
-        # as name => Attribute (nil for the lifecycle field and projected
-        # fields: bare scalars with no attribute of their own). The same
-        # three sources, the same precedence — an attribute that happens to
-        # share the lifecycle's or a projected field's name keeps its type.
-        # An entity (no `projected_fields` of its own) gets its entity
-        # field set — `decoded?` is asked about any `Instance`, and an
-        # entity is "structurally interchangeable with an aggregate".
+        # An attribute that shares a name with the lifecycle field or a projected field keeps
+        # its declared type; an entity (no `projected_fields` of its own) gets its entity fields.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct to walk
         # @return [Hash{Symbol => Bluebook::Attribute, nil}] a new Hash of field name to
@@ -117,12 +64,8 @@ module Hecks
 
         # Checks whether state already has the shape `decode` produces.
         #
-        # Whether `decode` would hand `state` back unchanged — every
-        # top-level key a Symbol, every declared key below it a Symbol, no
-        # hash carrying both spellings of a declared key. Allocates
-        # nothing; `CodecBoundary` asks it of every `Instance` an adapter
-        # builds. A `Runtime::Value` (hydrated state, a save's own entry)
-        # already is the declared shape, so it answers true.
+        # `CodecBoundary` asks this of every `Instance` an adapter builds; a `Runtime::Value`
+        # already is the declared shape, so it answers true without allocating.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the state
         #   belongs to
@@ -134,8 +77,6 @@ module Hecks
           hash_decoded?(aggregate, declared_top_level(aggregate), state, top: true)
         end
 
-        # ── encode ──────────────────────────────────────────────────────
-
         # Encodes one value, recursing through Hashes, Arrays and `Runtime::Value`s.
         #
         # @param value [Object] any state value; a `Runtime::Value` is encoded as its `to_h`
@@ -155,21 +96,15 @@ module Hecks
           end
         end
 
-        # ── decode ──────────────────────────────────────────────────────
-
         # Decodes one Hash level, symbolizing its declared keys and recursing into their values.
+        # Key order is kept; a string key is skipped when the symbol spelling is also present.
         #
-        # `fields` is name => Attribute-or-nil for this level. Key order is
-        # kept; a string key is skipped when the same hash also holds its
-        # symbol spelling, so the symbol wins wherever either one sits.
-        #
-        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct, through
-        #   which nested value objects and entities resolve
-        # @param fields [Hash{Symbol => Bluebook::Attribute, nil}] the fields declared at
-        #   this level
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct nested
+        #   value objects and entities resolve through
+        # @param fields [Hash{Symbol => Bluebook::Attribute, nil}] the fields declared at this level
         # @param raw [Hash] the stored Hash for this level
-        # @param symbolize_undeclared [Boolean] true to symbolize undeclared keys too, as the
-        #   top level does; false to leave their spelling alone
+        # @param symbolize_undeclared [Boolean] true to symbolize undeclared keys too (the top
+        #   level does); false to leave their spelling alone
         # @return [Hash] a new Hash in `raw`'s key order
         def decode_hash(aggregate, fields, raw, symbolize_undeclared: false)
           raw.each_with_object({}) do |(key, value), out|
@@ -186,12 +121,8 @@ module Hecks
 
         # Decodes the stored value of one declared field.
         #
-        # One declared field's value, by the four shapes `Value::Coercion`
-        # names (scalar / list / optional / composite). nil, a reference (a
-        # bare id or a list of them), and a scalar pass through untouched; a
-        # value object or entity recurses only when the stored value really
-        # is the Hash/Array its declaration says — anything else (a legacy
-        # bare scalar for a one-field value object) is left for hydration.
+        # A value object or entity recurses only when the stored value matches its declared
+        # Hash/Array shape; anything else (a legacy bare scalar) is left for hydration.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct, through
         #   which the field's type resolves
@@ -235,11 +166,8 @@ module Hecks
         # Maps an entity's (or aggregate's) attribute names, plus its lifecycle field, to
         # their attributes.
         #
-        # An entity is "structurally interchangeable with an aggregate"
-        # (behaviour/entity.rb): its attributes plus its own lifecycle field.
-        # Its value objects and nested entities resolve through the root
-        # aggregate, the same way `EntityListCoercion#hydrate_entity_list`
-        # resolves them.
+        # Nested value objects and entities resolve through the root aggregate, the same way
+        # `EntityListCoercion#hydrate_entity_list` resolves them.
         #
         # @param entity [Bluebook::Entity, Bluebook::Aggregate] the construct to walk
         # @return [Hash{Symbol => Bluebook::Attribute, nil}] a new Hash of field name to
@@ -251,23 +179,15 @@ module Hecks
           fields
         end
 
-        # ── decoded? ────────────────────────────────────────────────────
-
         # Checks one Hash level for keys `decode` would respell.
+        # The mirror of `decode_hash`: an undeclared nested key keeps its own spelling.
         #
-        # The mirror of `decode_hash`: a key `decode` would respell (any
-        # non-Symbol at the top, a non-Symbol declared key below it) means
-        # "not decoded"; an undeclared nested key keeps whatever spelling
-        # it has, exactly as `decode` keeps it.
-        #
-        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct, through
-        #   which nested types resolve
-        # @param fields [Hash{Symbol => Bluebook::Attribute, nil}] the fields declared at
-        #   this level
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct nested
+        #   types resolve through
+        # @param fields [Hash{Symbol => Bluebook::Attribute, nil}] the fields declared at this level
         # @param hash [Hash] the Hash to inspect
         # @param top [Boolean] true for the top level, where every key must be a Symbol
-        # @return [Boolean] true when this level and every declared composite below it is
-        #   decoded
+        # @return [Boolean] true when this level and every declared composite below it is decoded
         def hash_decoded?(aggregate, fields, hash, top: false)
           hash.all? do |key, value|
             if key.is_a?(Symbol)
@@ -291,7 +211,16 @@ module Hecks
           return true if attribute.nil? || value.nil? || attribute.reference?
           return composite_decoded?(aggregate, attribute.type.to_s, value) unless attribute.list?
 
-          !value.is_a?(Array) || value.all? { |element| composite_decoded?(aggregate, attribute.type.to_s, element) }
+          return true unless value.is_a?(Array)
+
+          # The element type resolves once per list, not once per element.
+          fields = :unresolved
+          value.all? do |element|
+            next true unless element.is_a?(Hash)
+
+            fields = composite_fields(aggregate, attribute.type.to_s) if fields == :unresolved
+            fields.nil? || hash_decoded?(aggregate, fields, element)
+          end
         end
 
         # Checks one stored value object or entity, the mirror of `decode_composite`.
@@ -305,13 +234,23 @@ module Hecks
         def composite_decoded?(aggregate, type, value)
           return true unless value.is_a?(Hash)
 
+          fields = composite_fields(aggregate, type)
+          fields.nil? || hash_decoded?(aggregate, fields, value)
+        end
+
+        # Maps the declared keys of a stored value object or entity, looked up by type name.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct that
+        #   declares, or whose chapter declares, the type
+        # @param type [String] the declared type name
+        # @return [Hash{Symbol => Bluebook::Attribute, nil}, nil] the entity's fields, else the
+        #   unambiguous value object's; nil when `type` names neither
+        def composite_fields(aggregate, type)
           entity = Runtime::Value.find_entity(aggregate, type)
-          return hash_decoded?(aggregate, entity_fields(entity), value) if entity
+          return entity_fields(entity) if entity
 
           value_object = Runtime::Value.value_object_for(aggregate, type)
-          return true unless value_object
-
-          hash_decoded?(aggregate, value_object.attributes.to_h { |field| [field.name, field] }, value)
+          value_object&.attributes&.to_h { |field| [field.name, field] }
         end
       end
     end

data/lib/hecks/ports/persistence.rb

@@ -23,29 +23,22 @@ Hecks::Ports::Persistence.autoload(:PostgresDump, File.join(__dir__, "persistenc
 
 module Hecks
   module Ports
-    # Reopened once `BindingPolicy`/`RepositoryFactory` (required above) are
-    # loaded, to add the persistence port's actual call surface: resolving
-    # which adapter authoritatively binds an aggregate and building the
-    # repository that reads/writes it.
+    # Reopened once BindingPolicy/RepositoryFactory are loaded, adding the port's
+    # call surface for resolving binds and building repositories.
     module Persistence
       module_function
 
-      # Builds the repository that reads and writes one aggregate's authoritative store.
-      #
-      # The public persistence port owns only authoritative aggregate heads. The repository
-      # comes back already recovered: every journal entry has been re-projected.
+      # Builds the repository that reads and writes one aggregate's authoritative store,
+      # already recovered from its journal.
       #
       # @param registry [Runtime::Registry] the booted registry holding the domain's
       #   hecksagon, world and adapters
       # @param domain [String, Symbol] name of the domain the aggregate belongs to
       # @param aggregate [Bluebook::Aggregate] the aggregate to persist
       # @return [Persistence::AppendOnly] repository over the aggregate's authoritative
-      #   adapter, or over a `Memory` adapter when the domain declares no hecksagon
-      # @raise [Runtime::WiringError] if the aggregate has no authoritative bind, more than
-      #   one, or a bind with a role this port does not support; or if the bound adapter is
-      #   unknown, answers a different verb, is given a setting it does not declare, has no
-      #   Ruby implementation, or lacks a method its port's `answers` list or the
-      #   append-only contract (`append`, `project`, `entries`) requires
+      #   adapter, or a `Memory` adapter when the domain declares no hecksagon
+      # @raise [Runtime::WiringError] if the aggregate's authoritative bind is missing,
+      #   ambiguous, or the bound adapter cannot satisfy the append-only contract
       def repository(registry, domain, aggregate)
         authoritative = BindingPolicy.resolve(registry, domain, aggregate)
         RepositoryFactory.build(registry, domain, aggregate, authoritative)