hecks 5.0.0 → 7.0.0

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

@@ -0,0 +1,67 @@
+require_relative "../projected_bluebook"
+require_relative "additive_shape"
+
+module Hecks
+  module Translation
+    # The empty edge a shape change needs when no edge file is written.
+    #
+    # A change that scaffolds to no rule, no unresolved line and no retirement, and whose storage
+    # change only adds, carries every row unchanged, so no file has to say so. The boot and the mint
+    # treat it as an empty edge from the held shape to the current one, and the journal records the
+    # era it minted as implicit. Every other change still needs a real edge file.
+    class ImplicitEdge
+      # What the journal stores for an era minted under an implicit edge. A later boot reads
+      # it back, so an audit can tell the edge was never written by hand.
+      RECORD = { kind: "implicit", scaffolded: true }.freeze
+
+      attr_reader :domain, :from, :to
+
+      # @param domain [String] the domain the edge belongs to
+      # @param from [String] the shape label the edge leaves
+      # @param to [String] the shape label the edge reaches
+      def initialize(domain:, from:, to:)
+        @domain = domain
+        @from = from
+        @to = to
+      end
+
+      # An implicit edge declares no aggregate, so it renames, moves, converts and drops nothing.
+      #
+      # @return [Array] always empty
+      def aggregates = []
+
+      # An implicit edge retires no aggregate, as a written edge's `retired` lists none it drops.
+      #
+      # @return [Array] always empty
+      def retired = []
+
+      # @param _name [String, Symbol] an aggregate name
+      # @return [nil] an implicit edge has no rules for any aggregate
+      def for_aggregate(_name) = nil
+
+      # @return [Boolean] always true
+      def implicit? = true
+
+      # The era record a mint writes for this edge, keyed by the label of the era it reaches.
+      #
+      # @return [Hash] `label` and `edge`, as the journal stores them
+      def record = { label: to, edge: RECORD }
+
+      # Whether a storage change needs no edge file: the scaffold finds no rule, no retirement and
+      # no unresolved name, and every aggregate both shapes have only adds: same identity and
+      # lifecycle field, every held attribute held exactly as before (list or scalar included),
+      # and every attribute gained optional. Anything this cannot tell is breaking.
+      #
+      # @param diff [Hash] the scaffold's diff of the held shape against the current one
+      # @param held [Hash, Runtime::ProjectedBluebook, Bluebook::Declaration] the held era's storage
+      #   shape, a view over it, or a declared bluebook
+      # @param current [Bluebook::Declaration] the current bluebook, which says which of its
+      #   attributes are optional
+      # @return [Boolean]
+      def self.qualifies?(diff, held, current)
+        diff[:aggregates].empty? && diff[:retired].empty? && diff[:unclaimed].empty? &&
+          AdditiveShape.additive?(held, current)
+      end
+    end
+  end
+end

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

@@ -78,7 +78,7 @@ module Hecks
       # removed afterwards, without touching the live registry.
       #
       # @param source [String] bluebook source text
-      # @return [Bluebook::Chapter, nil] the first bluebook the source declares; nil when it
+      # @return [Bluebook::Declaration, nil] the first bluebook the source declares; nil when it
       #   declares none or fails to parse or load for any reason
       def shadow(source)
         file = Tempfile.new(["hecks-reattest-", ".bluebook"])

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "compose"
+require_relative "edge_route"
+require_relative "compose_render"
+require_relative "edge_files"
+
+module Hecks
+  module Translation
+    # Plans `Era.Reconcile` for one domain: the one edge that leads its latest held era to the
+    # current shape, the edge files that edge supersedes, and the named reason a plan is refused.
+    #
+    # Planning reads the held labels, the loaded edges and the edge files, and writes nothing;
+    # `ReconcileFiles` carries out an admitted plan.
+    module Reconcile
+      # What a plan is made from: the domain's name, its held eras (`ordinal:` and `label:`, in
+      # order), the current shape's label, its loaded edges, the edge files of its translations
+      # directory and the directory a composed edge is written under.
+      Scope = Struct.new(:domain, :held, :current, :edges, :files, :directory, keyword_init: true)
+
+      # One domain's plan. `status` is `:no_era`, `:clean`, `:write` or `:refused`; `latest` is the
+      # latest held era (`ordinal:`, `label:`); `edge` is the composed edge when one is needed, and
+      # `removals` the edge files the plan deletes; `refusal` names why a plan is refused.
+      Plan = Struct.new(:domain, :status, :latest, :current, :labels, :edge, :write_path, :text,
+                        :removals, :mints, :refusal, keyword_init: true)
+
+      module_function
+
+      # @param scope [Scope] what the plan is made from
+      # @return [Plan] the plan; `status` is `:refused` with `refusal` naming the reason
+      def plan(scope)
+        return Plan.new(domain: scope.domain, status: :no_era, current: scope.current) if scope.held.empty?
+
+        latest = scope.held.last
+        decide(scope, latest, composition(scope, latest))
+      rescue Runtime::WiringError => e
+        Plan.new(domain: scope.domain, status: :refused, latest: scope.held.last, current: scope.current,
+                 refusal: e.message)
+      end
+
+      # @return [Hash] `chain:` the edges from the latest era, `edge:` the composed edge when the
+      #   chain has more than one step, and `kept:` the edge that already leads to the current shape
+      def composition(scope, latest)
+        chain = EdgeRoute.route(scope.edges, latest[:label], scope.current)
+        return { chain: chain, edge: nil, kept: chain.first } if chain.size <= 1
+
+        edge = Compose.compose(domain: scope.domain, from: latest[:label], to: scope.current, chain: chain)
+        { chain: chain, edge: edge, kept: edge }
+      end
+
+      def decide(scope, latest, composition)
+        removed = superseded(composition, scope.edges, latest)
+        refusal = refusal_for(scope, removed, composition)
+        return refused(scope, latest, refusal) if refusal
+
+        verdict(scope, latest, composition, removed.map { |edge| file_for!(scope, edge) })
+      end
+
+      # The edges a composed plan replaces: every chain step when the chain is composed, and every
+      # other edge leaving the latest held era.
+      def superseded(composition, edges, latest)
+        steps = composition[:chain].size > 1 ? composition[:chain] : []
+        branches = edges.select { |edge| edge.from == latest[:label] && !same?(edge, composition[:kept]) }
+        (steps + branches).uniq { |edge| key(edge) }
+      end
+
+      # The named reason the change is refused: an earlier era still using an edge the change
+      # deletes, or an earlier era the change would leave with no way to the current shape.
+      def refusal_for(scope, removed, composition)
+        after = scope.edges.reject { |edge| removed.any? { |gone| same?(gone, edge) } }
+        after += [composition[:edge]] if composition[:edge]
+        earlier = scope.held[0...-1]
+        still_used(scope.domain, earlier, removed) || uncovered(scope, earlier, after)
+      end
+
+      def still_used(domain, earlier, removed)
+        removed.each do |edge|
+          era = earlier.find { |held| held[:label] == edge.from }
+          next unless era
+
+          return "#{domain}: era #{era[:ordinal]} (#{era[:label]}) still uses the edge #{edge.from} -> " \
+                 "#{edge.to}, which the change would delete"
+        end
+        nil
+      end
+
+      def uncovered(scope, earlier, after)
+        era = earlier.find { |held| !EdgeRoute.reachable?(held[:label], scope.current, after) }
+        return nil unless era
+
+        verb = EdgeRoute.reachable?(era[:label], scope.current, scope.edges) ? "the change would leave" : "no edge leads"
+        "#{scope.domain}: #{verb} era #{era[:ordinal]} (#{era[:label]}) a way to #{scope.current}"
+      end
+
+      def verdict(scope, latest, composition, removal_paths)
+        labels = [latest[:label], *composition[:chain].map(&:to)]
+        edge = composition[:edge]
+        status = edge || removal_paths.any? ? :write : :clean
+        Plan.new(domain: scope.domain, status: status, latest: latest, current: scope.current, labels: labels,
+                 edge: edge, write_path: write_path_for(scope, latest, edge),
+                 text: edge && ComposeRender.render(edge, labels: labels), removals: removal_paths,
+                 mints: latest[:label] != scope.current)
+      end
+
+      def write_path_for(scope, latest, edge)
+        return nil unless edge
+
+        EdgeFiles.path_for(scope.directory, from: latest[:label], to: scope.current)
+      end
+
+      def refused(scope, latest, refusal)
+        Plan.new(domain: scope.domain, status: :refused, latest: latest, current: scope.current, refusal: refusal)
+      end
+
+      # @return [String] the path of the edge file that carries `edge`
+      # @raise [Runtime::WiringError] when no file under the translations directory holds it
+      def file_for!(scope, edge)
+        found = scope.files.find { |file| file.domain == scope.domain && file.from == edge.from && file.to == edge.to }
+        return found.path if found
+
+        raise Runtime::WiringError,
+              "#{scope.domain}: no edge file holds #{edge.from} -> #{edge.to}, so it cannot be removed"
+      end
+
+      def same?(left, right) = !right.nil? && key(left) == key(right)
+
+      def key(edge) = [edge.from, edge.to]
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Hecks
+  module Translation
+    # Carries out an admitted `Reconcile` plan on the translations directory, and puts the files
+    # back when the audit of what was written refuses.
+    module ReconcileFiles
+      module_function
+
+      # Writes the plan's composed edge and deletes the edge files it supersedes.
+      #
+      # @param plan [Reconcile::Plan] a plan with status `:write`
+      # @return [Hash{String => String, nil}] each touched path with the text it held, nil if absent
+      def write!(plan)
+        originals = [plan.write_path, *plan.removals].compact.to_h { |path| [path, read_if_present(path)] }
+        File.write(plan.write_path, plan.text) if plan.write_path
+        plan.removals.each { |path| FileUtils.rm_f(path) }
+        originals
+      end
+
+      # Puts each touched file back as `write!` found it.
+      #
+      # @param originals [Hash{String => String, nil}] what `write!` returned
+      def restore!(originals)
+        originals.each do |path, text|
+          text ? File.write(path, text) : FileUtils.rm_f(path)
+        end
+      end
+
+      def read_if_present(path) = File.exist?(path) ? File.read(path) : nil
+    end
+  end
+end

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

@@ -4,10 +4,29 @@ require_relative "expression_sql"
 module Hecks
   module Translation
     # Compiles one TranslationAggregate's declared rules into a jsonb-transforming SQL
-    # expression, shared by Ruby's own mint path and any other SQL-emitting caller.
+    # expression, shared by Ruby's own mint path and any other SQL-emitting caller. Each rule's
+    # Postgres form is a template read from the translation execution ledger
+    # (`lib/hecks/grammar/translation_rules.json`); this module only fills its holes.
     module RuleCompiler
       module_function
 
+      # Every admitted rule kind's Postgres template, read once from the replayed ledger.
+      #
+      # @return [Hash{String => String}] rule kind to its template, with `%{name}` holes
+      def postgres_forms
+        @postgres_forms ||= begin
+          require "hecks/grammar"
+          Grammar.rule_executions("postgres").freeze
+        end
+      end
+
+      # Fills one rule kind's Postgres template.
+      #
+      # @param kind [String] the rule kind, such as `"rename"`
+      # @param holes [Hash{Symbol => String}] the SQL each `%{name}` hole takes
+      # @return [String] the filled SQL
+      def form(kind, **holes) = format(postgres_forms.fetch(kind), **holes)
+
       # Compiles one edge's derive/rename/move/convert/drop/backfill rules into a nested
       # SQL expression over `state`, composed innermost-first in that phase order.
       def compile_rules(declared)
@@ -29,11 +48,8 @@ module Hecks
       # Wraps `expression` so a derive's text lands at its destination when the expression has a
       # value; the expression reads the stored `state`, never the rules composed before it.
       def compile_derive(expression, derive)
-        value = ExpressionSql.compile(derive.tree, "state")
-        "(SELECT CASE WHEN __d IS NULL THEN __s " \
-          "ELSE hecks_tr_insert(__s, #{path_literal(derive.to)}, to_jsonb(__d), " \
-          "#{text_literal("derive #{derive.to}")}) END " \
-          "FROM (SELECT (#{expression}) AS __s) __outer, LATERAL (SELECT #{value} AS __d) __derived)"
+        form("derive", expression: expression, to: path_literal(derive.to),
+                       value: ExpressionSql.compile(derive.tree, "state"), rule: text_literal("derive #{derive.to}"))
       end
 
       # Folds each rule of one kind into `expression`, innermost-first.
@@ -53,26 +69,26 @@ module Hecks
 
       # Wraps `expression` in the rename of one top-level key.
       def compile_rename(expression, old_name, new_name)
-        "hecks_tr_rename(#{expression}, #{text_literal(old_name)}, #{text_literal(new_name)})"
+        form("rename", expression: expression, from: text_literal(old_name), to: text_literal(new_name))
       end
 
       # Wraps `expression` in the move of one path to another.
       def compile_move(expression, move)
-        "hecks_tr_move(#{expression}, #{path_literal(move.from)}, #{path_literal(move.to)}, " \
-          "#{text_literal("move #{move.from} to: #{move.to}")})"
+        form("move", expression: expression, from: path_literal(move.from), to: path_literal(move.to),
+                     rule: text_literal("move #{move.from} to: #{move.to}"))
       end
 
       # Wraps `expression` in the conversion of one path's value through a lookup table.
       def compile_convert(expression, convert)
         pairs = JSON.generate(convert.values.map { |key, value| [key, value] })
-        "hecks_tr_convert(#{expression}, #{path_literal(convert.from)}, #{path_literal(convert.to)}, " \
-          "#{text_literal(pairs)}::jsonb, #{text_literal(convert.from)}, " \
-          "#{text_literal("convert #{convert.from} to: #{convert.to}")})"
+        form("convert", expression: expression, from: path_literal(convert.from), to: path_literal(convert.to),
+                        values: text_literal(pairs), source: text_literal(convert.from),
+                        rule: text_literal("convert #{convert.from} to: #{convert.to}"))
       end
 
       # Wraps `expression` in the removal of one path.
       def compile_drop(expression, name)
-        "hecks_tr_drop(#{expression}, #{path_literal(name)})"
+        form("drop", expression: expression, path: path_literal(name))
       end
 
       # Reports whether an edge's declared rules for an aggregate include a rekey, read
@@ -90,18 +106,15 @@ module Hecks
       def compile_id_expression(declared)
         rekey = declared.rekeys.first
         derive = declared.derives.find { |candidate| candidate.to == rekey.to }
-        "COALESCE(#{ExpressionSql.compile(derive.tree, "state")}, aggregate_id)"
+        form("rekey_to", value: ExpressionSql.compile(derive.tree, "state"))
       end
 
       # Wraps `expression` so a backfill's default lands at its declared path only when
       # nothing is already there, the same rule `Lineage#translate`'s own pass holds to.
       def compile_backfill(expression, backfill)
         name = backfill.name.to_s
-        default_json = JSON.generate(backfill.default)
-        "(SELECT CASE WHEN (hecks_tr_extract(__s, #{path_literal(name)})).present THEN __s " \
-          "ELSE hecks_tr_insert(__s, #{path_literal(name)}, #{text_literal(default_json)}::jsonb, " \
-          "#{text_literal("backfill #{name}")}) END " \
-          "FROM (SELECT (#{expression}) AS __s) __outer)"
+        form("backfill", expression: expression, path: path_literal(name),
+                         default: text_literal(JSON.generate(backfill.default)), rule: text_literal("backfill #{name}"))
       end
 
       # Renders a Ruby value as a single-quoted SQL text literal, escaping embedded quotes.

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

@@ -1,4 +1,5 @@
 require_relative "../../storage_shape"
+require_relative "../../projected_bluebook"
 require_relative "path_diff"
 
 module Hecks
@@ -9,14 +10,19 @@ module Hecks
       module Differ
         include PathDiff
 
-        # Diffs two bluebook IRs into the edge's declarations.
+        # Diffs two storage shapes into the edge's declarations. Either side is a storage shape, a
+        # `Runtime::ProjectedBluebook` over one, or a declared bluebook, which is projected first.
         #
-        # @param held_bluebook [Bluebook::Chapter] the era being translated from
-        # @param current_bluebook [Bluebook::Chapter] the era being translated to
+        # @param held_bluebook [Hash, Runtime::ProjectedBluebook, Bluebook::Declaration] the era
+        #   being translated from
+        # @param current_bluebook [Hash, Runtime::ProjectedBluebook, Bluebook::Declaration] the era
+        #   being translated to
         # @return [Hash{Symbol => Object}] `:aggregates` (Array<Scaffold::ScaffoldedAggregate>),
         #   `:retired` (Array<String>, vanished names with no successor), `:unclaimed`
         #   (Array<String>, vanished names left ambiguous)
         def diff(held_bluebook, current_bluebook)
+          held_bluebook = Runtime::ProjectedBluebook.wrap(held_bluebook)
+          current_bluebook = Runtime::ProjectedBluebook.wrap(current_bluebook)
           held_shapes = projections(held_bluebook)
           current_shapes = projections(current_bluebook)
 
@@ -40,9 +46,11 @@ module Hecks
           ScaffoldedAggregate.new(name: aggregate.name, was: was, rules: rules)
         end
 
-        # Projects a bluebook's storage shape, indexing its aggregates by name.
+        # A side's storage shape, its aggregates indexed by name: a view's stored shape as it is, a
+        # declared bluebook's as `StorageShape.project` answers it.
         def projections(bluebook)
-          Runtime::StorageShape.project(bluebook)["aggregates"].to_h { |shape| [shape["name"], shape] }
+          shape = bluebook.is_a?(Runtime::ProjectedBluebook) ? bluebook.projection : Runtime::StorageShape.project(bluebook)
+          shape["aggregates"].to_h { |aggregate| [aggregate["name"], aggregate] }
         end
 
         # Pairs vanished aggregates with new ones whose full shape reappears under exactly one

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

@@ -7,5 +7,10 @@ end
 
 require_relative "translation/rule_compiler"
 require_relative "translation/scaffold"
+require_relative "translation/implicit_edge"
 require_relative "translation/audit"
+require_relative "translation/compose"
+require_relative "translation/edge_files"
+require_relative "translation/reconcile"
+require_relative "translation/reconcile_files"
 require_relative "translation/reattest"

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

@@ -1,10 +1,10 @@
 require_relative "../plugin"
 require_relative "era/era_check"
+require_relative "era/era_status"
 require_relative "era/era_guard"
 require_relative "era/era_tamper"
 require_relative "era/storage_shape"
 require_relative "era/lineage"
-require_relative "era/postgres_era"
 require_relative "era/translation"
 
 module Hecks

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

@@ -9,11 +9,12 @@ module Hecks
         # 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`
+        # @raise [Runtime::WiringError] always, pointing the caller at
+        #   `Adapters::Lambda::RemoteDispatcher`
         def append(*)
           raise Runtime::WiringError,
                 "#{self.class.name} is a remote-runtime delegate — dispatch through " \
-                "Runtime::RemoteDispatcher instead of writing through the repository directly"
+                "Adapters::Lambda::RemoteDispatcher instead of writing through the repository directly"
         end
         alias project append
 

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

@@ -43,7 +43,7 @@ module Hecks
         # @param bind [Bluebook::Bind] the bind naming the adapter
         # @param settings_verb [String] the verb whose settings configure the adapter
         # @return [Hash] the declared settings, under the adapter's own declared defaults, plus
-        #   the domain, resolved era and superseding era
+        #   the domain, resolved era, superseding era and whether the shape is unminted
         def adapter_settings(registry, domain, aggregate, bind, settings_verb)
           registry.check_verb(bind)
           settings = registry.binding_settings(domain, settings_verb, bind.adapter)
@@ -52,8 +52,16 @@ module Hecks
           settings = registry.with_adapter_defaults(bind.adapter, aggregate, settings)
           # domain, resolved era and superseding era ride along outside the declared
           # settings: a lineage adapter needs them to journal per domain, per-era.
-          settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s],
-                         superseded_by: registry.superseded_eras[domain.to_s])
+          settings.merge(boot_marks(registry, domain))
+        end
+
+        # The per-domain marks the boot gate left on the registry, merged into an adapter's settings.
+        #
+        # @return [Hash] the domain, resolved era, superseding era and whether the shape is unminted
+        def boot_marks(registry, domain)
+          name = domain.to_s
+          { domain: name, era: registry.resolved_eras[name], superseded_by: registry.superseded_eras[name],
+            unminted: registry.unminted_eras.key?(name) }
         end
       end
     end

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

@@ -0,0 +1,29 @@
+module Hecks
+  module Ports
+    module Persistence
+      # One command applied to every row of a query, said without SQL (ADR 0129): the runtime
+      # builds it from the bluebook, and a store that provides `set_transform` compiles it to one
+      # statement in its own dialect. It names fields and parsed expressions, never columns.
+      #
+      # - `query`, `query_args`: the query's specification and arguments, as the store answers it
+      # - `givens`: each given's parsed predicate, every one of which a row must meet
+      # - `assignments`: each {SetStatement::Assignment} the command makes
+      # - `transition`: the lifecycle cases in order, each `[from_states or nil, target]`; nil when
+      #   the command moves no lifecycle
+      # - `from_guard`: the lifecycle states the command is admissible from, or nil
+      # - `arguments`: the command's arguments by name, each a plain scalar an expression reads
+      SetStatement = Struct.new(:query, :query_args, :givens, :assignments, :transition, :from_guard, :arguments,
+                                keyword_init: true)
+
+      class SetStatement
+        # One field a statement writes. `kind` says what `value` is:
+        #
+        # - `:constant`: the value every row takes, already shaped as the record holds it
+        # - `:copy`: the name of the field whose value each row copies
+        # - `:expression`: a parsed expression over the row and the arguments
+        # - `:step`: the Integer added to the field (negative to take away)
+        Assignment = Struct.new(:target, :kind, :value, keyword_init: true)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+require_relative "set_statement"
+
+module Hecks
+  module Ports
+    module Persistence
+      # The repository's door to its adapter's one-statement rewrite (ADR 0129). Mixed into
+      # `AppendOnly`, which supplies `@adapter`.
+      module SetTransforming
+        # Whether the adapter answers a {SetStatement} with one statement. The declared
+        # `provides "set_transform"` says a store should; this says this adapter does.
+        #
+        # @return [Boolean]
+        def set_transform? = @adapter.respond_to?(:apply_set_transform) && @adapter.respond_to?(:set_transform_dialect)
+
+        # @return [String, nil] the dialect the adapter's statement is written in, such as
+        #   `"sqlite"`; nil when it answers no statement
+        def set_transform_dialect = (@adapter.set_transform_dialect if set_transform?)
+
+        # Rewrites every row a statement selects, in one statement, and journals each.
+        #
+        # @param statement [SetStatement] the command over the query
+        # @return [Array<Runtime::Instance>] the rows it updated, as they now stand
+        # @raise [Adapters::SetTransform::Uncompilable] before anything is written, when part of
+        #   the statement has no form in the adapter's dialect
+        # @raise [Adapters::SetTransform::Declined] if the store refused the statement
+        def apply_set_transform(statement) = @adapter.apply_set_transform(statement)
+      end
+    end
+  end
+end

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

@@ -159,7 +159,7 @@ module Hecks
         # Decodes one 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
+        #   declares, or whose bluebook declares, the type
         # @param type [String] the declared type name, such as `"Address"`
         # @param value [Object] the stored value
         # @return [Hash, Object] a new decoded Hash; `value` unchanged when it is not a Hash or
@@ -249,7 +249,7 @@ module Hecks
         # Checks one stored value object or entity, the mirror of `decode_composite`.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct that
-        #   declares, or whose chapter declares, the type
+        #   declares, or whose bluebook declares, the type
         # @param type [String] the declared type name
         # @param value [Object] the value to inspect
         # @return [Boolean] true when `value` is not a Hash, `type` names neither an entity nor
@@ -264,7 +264,7 @@ module Hecks
         # 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
+        #   declares, or whose bluebook 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

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

@@ -0,0 +1,36 @@
+require_relative "../../runtime/errors"
+
+module Hecks
+  module Ports
+    module Persistence
+      # Refuses the boot that would store an aggregate in a new, empty table beside rows an earlier
+      # name still holds. A renamed aggregate's rows are found by its `stored_as`; if that line is
+      # missing or wrong, the adapter would create the empty table the new name implies and the
+      # rows would seem gone. This names the table the rows are in instead, and creates nothing.
+      module StoredNameGuard
+        module_function
+
+        # @param aggregate [Bluebook::Aggregate] the aggregate about to be stored
+        # @param row_count [#call] given a table's base name, the rows it holds (0 when absent)
+        # @return [void]
+        # @raise [Runtime::WiringError] when the aggregate's own table holds no rows and a prior
+        #   name's table does
+        def check!(aggregate, row_count:)
+          return if row_count.call(aggregate.storage_name).positive?
+
+          held = aggregate.prior_storage_names.to_h { |name| [name, row_count.call(name)] }.select { |_, rows| rows.positive? }
+          return if held.empty?
+
+          raise Runtime::WiringError, refusal(aggregate, held)
+        end
+
+        def refusal(aggregate, held)
+          name, rows = held.first
+          "cannot boot #{aggregate.name}: it would be stored in #{aggregate.storage_name.inspect}, which holds no rows, " \
+            "but #{name.inspect} holds rows (#{rows}) from an earlier name. Point the world at them with " \
+            "`stored_as #{aggregate.name}: #{name.inspect}`, or move the rows first. Nothing was created."
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence.rb

@@ -2,16 +2,14 @@ require_relative "persistence/constants"
 require_relative "persistence/binding_policy"
 require_relative "persistence/plugin"
 require_relative "persistence/repository_factory"
+require_relative "persistence/mint_door"
+require_relative "persistence/stored_name_guard"
 require_relative "persistence/append_only"
 require_relative "persistence/execution"
 require_relative "persistence/remote_runtime"
 require_relative "persistence/null_saga_store"
 require_relative "persistence/state_codec"
 
-# Loaded on first mention: nothing about a domain's own boot needs the dump
-# tooling, and it wants the optional `pg` gem.
-Hecks::Ports::Persistence.autoload(:PostgresDump, File.join(__dir__, "persistence/postgres_dump"))
-
 module Hecks
   module Ports
     # Reopened once BindingPolicy/RepositoryFactory are loaded, adding the port's

data/lib/hecks/ports/projection.rb

@@ -16,11 +16,14 @@ module Hecks
       end
 
       # Builds a worker for the aggregate's first `projected_by` bind; nil when it has none.
+      #
+      # It reads the registry's own authoritative repository, so a projection of an in-process
+      # store (Memory) sees the records the registry holds, not a fresh empty store.
       def worker(registry, domain, aggregate, policy: :refresh)
         bind = binds_for(registry, domain, aggregate).first
         return unless bind
 
-        authoritative = Persistence.repository(registry, domain, aggregate)
+        authoritative = registry.repository(domain, aggregate)
         target = Persistence::RepositoryFactory.build(registry, domain, aggregate, bind,
                                                       recover: true, settings_verb: VERB)
         Worker.new(authoritative, target, policy: policy)