hecks 2.7.0 → 2.9.0

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 no longer declares, 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)

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)

data/lib/hecks/ports/projection.rb

@@ -4,40 +4,18 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # Projection is a read-side port. Its stores are rebuildable consumers of
-    # authoritative entries and never participate in command decisions.
+    # Read-side port: rebuildable stores fed from authoritative entries, never read by commands.
     module Projection
       NAME = "projection".freeze
       VERB = "projected_by".freeze
 
       module_function
 
-      # Lists the `projected_by` binds a domain's hecksagon declares for one aggregate.
-      #
-      # @param registry [Runtime::Registry] the booted registry to search
-      # @param domain [String, Symbol] name of the domain the aggregate belongs to
-      # @param aggregate [Bluebook::Aggregate] the aggregate to find projection binds for
-      # @return [Array<Bluebook::Bind>] the binds naming the aggregate, or failing that the
-      #   hecksagon's aggregate-less `projected_by` binds; `[]` if there are none or the
-      #   domain declares no hecksagon
       def binds_for(registry, domain, aggregate)
         registry.hecksagon(domain)&.binds_for(aggregate.hecks_name, VERB) || []
       end
 
-      # Builds a worker that catches one projection's store up to its authoritative journal.
-      #
-      # @param registry [Runtime::Registry] the booted registry to resolve binds against
-      # @param domain [String, Symbol] name of the domain the aggregate belongs to
-      # @param aggregate [Bluebook::Aggregate] the aggregate being projected
-      # @param policy [Symbol, String] `:refresh` (reset the store and rebuild it) or
-      #   `:strict` (refuse on divergent history) — see `Worker::VALID_POLICIES`
-      # @return [Ports::Projection::Worker, nil] a worker for the aggregate's first declared
-      #   bind, or nil if it has no projection bind
-      # @raise [Runtime::WiringError] if the aggregate's authoritative persistence bind does
-      #   not resolve (see `Persistence.repository`), or the projection's adapter is unknown,
-      #   answers a different verb, is given a setting it does not declare, has no Ruby
-      #   implementation, or lacks a method the append-only contract requires
-      # @raise [ArgumentError] if `policy` is not one of `Worker::VALID_POLICIES`
+      # Builds a worker for the aggregate's first `projected_by` bind; nil when it has none.
       def worker(registry, domain, aggregate, policy: :refresh)
         bind = binds_for(registry, domain, aggregate).first
         return unless bind
@@ -48,38 +26,15 @@ module Hecks
         Worker.new(authoritative, target, policy: policy)
       end
 
-      # Catches one projection's store up to its authoritative journal:
-      # replays whatever entries the store hasn't yet appended/projected.
-      # Constructed via Projection.worker; #catch_up! runs from a
-      # separate process or scheduler, never from the command-side write
-      # path.
+      # Catches one projection store up to its authoritative journal; run from a separate
+      # process or scheduler, never from the command-side write path.
       class Worker
-        # @return [Persistence::AppendOnly] the projection store this worker catches up
         attr_reader :projection
 
-        # The only two policies anything in this codebase ever passes
-        # (`bin/project`, every spec) — there is no third, legitimate
-        # "lenient append" policy on record anywhere. This list is the
-        # contract for what a valid policy is: `catch_up!` enforces
-        # history agreement only for the exact symbol `:strict`, so any
-        # other unrecognised value — a typo like `:strikt` — would fall
-        # through the `consistent?` check below and append onto
-        # divergent history without a word. A caller-supplied String
-        # `"strict"` is accepted on purpose, normalised by `policy.to_sym`
-        # in `initialize` before it is checked against this list, not by
-        # the accident of duck typing.
-        # Refusing loudly at construction, once, for anything outside
-        # this list turns a silent no-op into an immediate, named error
-        # — the "refuse rather than silently skip" reading of L1, since
-        # `:strict` really is meant to be the only enforcing contract.
+        # Only `:strict` enforces history agreement, so an unknown policy (a typo) would append
+        # onto divergent history silently; construction refuses anything else.
         VALID_POLICIES = %i[refresh strict].freeze
 
-        # @param authoritative [Persistence::AppendOnly] the authoritative repository whose
-        #   journal the projection is caught up to
-        # @param projection [Persistence::AppendOnly] the projection store being caught up
-        # @param policy [Symbol, String] one of `VALID_POLICIES`, as a Symbol or its String
-        #   spelling
-        # @raise [ArgumentError] if `policy` is not one of `VALID_POLICIES`
         def initialize(authoritative, projection, policy: :refresh)
           @authoritative = authoritative
           @projection = projection
@@ -91,45 +46,55 @@ module Hecks
           end
         end
 
-        # Appends and projects every authoritative entry the projection store lacks.
+        # Appends and projects every authoritative entry the store lacks.
         #
-        # Invoke from a separate process or scheduler. The command-side write
-        # path never calls this method.
-        #
-        # Under `:refresh` the store is reset first and rebuilt from the whole journal. Under
-        # `:strict` the store's own entries must be a prefix of the authoritative journal
-        # (same operation, id and state, in order); only the entries after that prefix are
-        # replayed.
-        #
-        # @return [Persistence::AppendOnly] the projection store, now caught up
-        # @raise [Runtime::WiringError] under `:strict`, if the projection's history is not a
-        #   prefix of the authoritative journal; under `:refresh`, if the projection's
-        #   adapter cannot `reset!`
+        # `:refresh` never reads journal history — it rebuilds from the aggregate's own current
+        # records, which the authoritative table already holds directly, so it stays correct
+        # past a compacted journal. `:strict` verifies its own entries are a real prefix of the
+        # authoritative journal, which genuinely needs that history; it refuses rather than
+        # silently misreading a compacted journal's surviving rows as if they started at
+        # position zero.
         def catch_up!
-          entries = Queue.new(@authoritative).entries
+          return refresh! if @policy == :refresh
+
+          compacted_through = @authoritative.respond_to?(:compacted_through) ? @authoritative.compacted_through : 0
           present = @projection.entries
-          if @policy == :refresh
-            @projection.reset!
-            present = []
+          if present.length < compacted_through
+            raise Runtime::WiringError,
+                  ":strict catch-up needs journal history the authoritative store has already " \
+                  "compacted (through sequence #{compacted_through}, this projection has only " \
+                  "consumed #{present.length}) — use :refresh instead"
           end
-          unless consistent?(entries, present)
-            raise Runtime::WiringError, "projection history does not match its authoritative history" if @policy == :strict
+
+          entries = Queue.new(@authoritative).entries
+          present_tail = present.drop(compacted_through)
+          unless consistent?(entries, present_tail)
+            raise Runtime::WiringError, "projection history does not match its authoritative history"
           end
-          entries.drop(present.length).each do |entry|
+
+          entries.drop(present_tail.length).each do |entry|
             @projection.append(entry)
             @projection.project(entry)
           end
           @projection
         end
 
-        # Counts the entries the projection store holds, which is how far it has caught up.
-        #
-        # @return [Integer] number of journal entries already appended to the projection
-        #   store; 0 for a store that has never caught up
         def checkpoint = @projection.entries.length
 
         private
 
+        # Resets the store and rebuilds it from the aggregate's own current records — one
+        # synthetic save per live record, never a replay of deleted or superseded history.
+        def refresh!
+          @projection.reset!
+          @authoritative.all.each do |instance|
+            entry = Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+            @projection.append(entry)
+            @projection.project(entry)
+          end
+          @projection
+        end
+
         def same_entry?(left, right) = left.operation == right.operation && left.id == right.id && left.state == right.state
 
         def consistent?(entries, present)
@@ -139,18 +104,11 @@ module Hecks
         end
       end
 
-      # The authoritative append-only journal is the durable projection queue.
-      # It is committed before a worker sees it; projection entries are the
-      # worker's durable checkpoint, so delivery is at-least-once and safe to replay.
+      # The authoritative journal doubles as the queue: entries are committed before a worker
+      # sees them, so delivery is at-least-once and safe to replay.
       class Queue
-        # @param authoritative [Persistence::AppendOnly] the authoritative repository to read
-        #   entries from
         def initialize(authoritative) = @authoritative = authoritative
 
-        # Reads the whole authoritative journal, the work a projection worker replays from.
-        #
-        # @return [Array<Persistence::Entry>] every committed entry, oldest first; `[]` for
-        #   an empty journal
         def entries = @authoritative.entries
       end
     end