hecks 0.2.0 → 0.3.0

data/lib/hecks/ports/identity_generation.rb

@@ -0,0 +1,49 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # A creating command with no natural key needs a value from
+    # SOMEWHERE to be its identity — this is that somewhere. Resolved
+    # the same way `Ports::Extraction` resolves its own adapter (one
+    # adapter registry-wide implements this port, not a per-aggregate
+    # binding the way persistence needs — different aggregates have no
+    # real reason to want different id-generation strategies within
+    # one running app).
+    #
+    # REPLAY NEEDS NO SUPPRESSION HERE, ON PURPOSE. A UUID minted for a
+    # creating command's identity gets baked into that step's own args
+    # — an ordinary string value — the moment it's generated, by
+    # whoever issues the first, live dispatch. A recorded corpus
+    # script or a captured fuzz-replay step already holds that
+    # concrete value; replaying it calls `dispatch` with the SAME
+    # args, and this module is never consulted again, for the same
+    # reason `SecureRandom.uuid` never runs twice for one
+    # already-recorded step today. `Event#occurred_at`
+    # (`command_rules/emission.rb`) is the one other "environmental
+    # fact, not caller-supplied" this codebase has, and it's handled
+    # the identical way: it fires on every dispatch, replay included,
+    # and comparison simply excludes it.
+    module IdentityGeneration
+      NAME = "identity_generation"
+
+      module_function
+
+      def uuid(registry) = adapter(registry).uuid
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then Adapters.const_get(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can mint an identity"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/identity_resolution.port

@@ -0,0 +1,4 @@
+Hecks.port "identity_resolution" do
+  verb   "resolved_by"
+  signal :reply
+end

data/lib/hecks/ports/identity_resolution.rb

@@ -0,0 +1,40 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # AN AUTHENTICATED (issuer, subject) PAIR, RESOLVED TO A STABLE
+    # `Identity` — the other half of the same symmetry `Authorization`
+    # already has for Governance: one adapter registry-wide answers this
+    # port, resolved the same zero/one/many way, so an application never
+    # has to name `Identity` directly to ask "who is this."
+    #
+    # Answers `nil` for a pair nothing has linked — the caller decides
+    # what that means (refuse, prompt to register, whatever), the same
+    # way `Authorization#holds_role?` answering `false` decides nothing
+    # on its own.
+    module IdentityResolution
+      NAME = "identity_resolution"
+
+      module_function
+
+      def resolve(registry, issuer:, subject:)
+        adapter(registry).resolve(registry, issuer: issuer, subject: subject)
+      end
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then Adapters.const_get(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can resolve an identity"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/loading.port

@@ -0,0 +1,4 @@
+Hecks.port "loading" do
+  verb   "loaded_by"   
+  signal :reply        
+end

data/lib/hecks/ports/loading.rb

@@ -0,0 +1,13 @@
+require_relative "../adapters/driven/folder"
+
+module Hecks
+  module Ports
+    module Loading
+      NAME = "loading"
+
+      module_function
+
+      def bootstrap = Adapters::Folder.new
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+require_relative "../../runtime/registry"
+require_relative "execution"
+
+module Hecks
+  module Ports
+    module Persistence
+      # `mirrors` is durable replication intent.  It is part of the same
+      # append as the authoritative state, never a second outbox store.
+      Entry = Struct.new(:operation, :id, :state, :mirrors, keyword_init: true) do
+        def save? = operation == "save"
+        def delete? = operation == "delete"
+      end
+
+      # Makes append-before-projection a port invariant. Adapters retain
+      # control of their durable format, but every one must accept the same
+      # entry stream and materialize current state from it.
+      class AppendOnly
+        attr_reader :adapter
+
+        def aggregate = @adapter.aggregate
+
+        def initialize(adapter)
+          @adapter = adapter
+          required = %i[append project entries]
+          missing = required.reject { |method| adapter.respond_to?(method) }
+          raise Runtime::WiringError,
+                "#{adapter.class} does not implement append-only persistence: #{missing.join(', ')}" unless missing.empty?
+        end
+
+        def find(id) = @adapter.find(id)
+        def all(**opts) = @adapter.all(**opts)
+        def count = @adapter.count
+        def entries = @adapter.entries
+
+        def capabilities
+          return [] unless @adapter.respond_to?(:persistence_capabilities)
+
+          Array(@adapter.persistence_capabilities).map(&:to_sym).freeze
+        end
+
+        def reset!
+          raise Runtime::WiringError, "append-only adapter cannot reset" unless @adapter.respond_to?(:reset!)
+
+          @adapter.reset!
+        end
+
+        # NOT an endless `def events = ... if ...` — that modifier binds to
+        # the WHOLE `def`, not just its body, so it evaluates against
+        # `@adapter` while `@adapter` is still nil (class-body time,
+        # before `initialize` ever runs) and silently skips defining the
+        # method at all. Found live: nothing in this codebase called
+        # `AppendOnly#events` before Memory got a `reset!` test that did.
+        def events
+          @adapter.events if @adapter.respond_to?(:events)
+        end
+
+        # An append is durable before a projection is attempted. Replaying the
+        # log restores a snapshot/table after a crash in that small window.
+        def recover!
+          entries.each { |entry| project(entry) }
+          self
+        end
+
+        def append(entry) = @adapter.append(entry)
+        def project(entry) = @adapter.project(entry)
+
+        def save(instance)
+          entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+          append(entry)
+          project(entry)
+          instance
+        end
+
+        def atomic_put(instance, insert_only: false)
+          unless capabilities.include?(:atomic_put) && @adapter.respond_to?(:atomic_put)
+            raise Runtime::WiringError, "#{@adapter.class} advertises no atomic_put persistence capability"
+          end
+
+          entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+          status = @adapter.atomic_put(entry, insert_only: insert_only)
+          Outcome.new(status: status, instance: instance)
+        end
+
+        def delete(id)
+          return false unless find(id)
+
+          entry = Entry.new(operation: "delete", id: id.to_s, state: nil)
+          append(entry)
+          project(entry)
+          true
+        end
+
+        def record_event(event) = @adapter.record_event(event) if @adapter.respond_to?(:record_event)
+        def query_read_model(domain, model, args, bluebook = nil)
+          return unless @adapter.respond_to?(:query_read_model)
+
+          @adapter.query_read_model(domain, model, args, bluebook)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+require_relative "../../bluebook/hexagon"
+require_relative "../../runtime/registry"
+
+module Hecks
+  module Ports
+    module Persistence
+      # Resolves one aggregate's persistence topology. An unmarked binding is
+      # authoritative; roles are deliberately opt-in so a second adapter can
+      # never silently become a read source.
+      module BindingPolicy
+        module_function
+
+        def resolve(registry, domain, aggregate)
+          hexagon = registry.hecksagon(domain)
+          return default_binding(aggregate) unless hexagon
+
+          bindings = hexagon.binds_for(aggregate.hecks_name, VERB)
+          raise missing_binding(domain, aggregate) if bindings.empty?
+
+          authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }
+          raise ambiguous_binding(domain, aggregate, authoritative) unless authoritative.size == 1
+          raise unsupported_roles(domain, aggregate, bindings - authoritative) unless (bindings - authoritative).empty?
+
+          authoritative.first
+        end
+
+        def default_binding(aggregate)
+          Bluebook::Bind.new(aggregate: aggregate.hecks_name, verb: VERB, adapter: DEFAULT_ADAPTER)
+        end
+
+        def missing_binding(domain, aggregate)
+          Runtime::WiringError.new(
+            "#{domain}::#{aggregate.hecks_name} has no #{VERB} bind. #{domain} declares a " \
+            "hecksagon, so its wiring is being decided explicitly and an aggregate " \
+            "left out is a forgotten decision. Bind it, or say " \
+            "#{aggregate.hecks_name}.#{VERB}(#{DEFAULT_ADAPTER.inspect}) to keep it in memory on purpose."
+          )
+        end
+
+        def ambiguous_binding(domain, aggregate, authoritative)
+          Runtime::WiringError.new(
+            "#{domain}::#{aggregate.hecks_name} has #{authoritative.size} authoritative #{VERB} bindings. " \
+            "Declare exactly one adapter without a role."
+          )
+        end
+
+        def unsupported_roles(domain, aggregate, bindings)
+          Runtime::WiringError.new(
+            "#{domain}::#{aggregate.hecks_name} uses persistence role#{bindings.size == 1 ? '' : 's'} " \
+            "#{bindings.map(&:role).map(&:inspect).join(', ')}. Only persisted_by is supported."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module Hecks
+  module Ports
+    module Persistence
+      # Adapter outcomes are runtime facts, never command lifecycle.
+      Outcome = Struct.new(:status, :instance, keyword_init: true) do
+        STATUSES = %i[inserted replaced updated conflicted missing saved].freeze
+
+        def initialize(status:, instance: nil)
+          normalized = status.to_sym
+          raise ArgumentError, "unknown persistence outcome #{status.inspect}" unless STATUSES.include?(normalized)
+
+          super(status: normalized, instance: instance)
+          freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,277 @@
+require_relative "../../naming"
+require_relative "append_only"
+require_relative "../../runtime/registry"
+
+module Hecks
+  module Ports
+    module Persistence
+      # Translates a journal entry written under an old shape into the one
+      # the current bluebook declares — a renamed attribute, a renamed
+      # aggregate, or a field crossing a value-object boundary. Applied
+      # wherever entries are read, so replay derives the current head from
+      # history that was never rewritten — the port owns the meaning,
+      # adapters stay oblivious.
+      class Lineage
+        # `ancestor_name` is the declared name a rename came from (matches
+        # the held bluebook's own aggregate names); `ancestor_storage_name`
+        # is its derived, snake_case file/table name. Both are nil unless
+        # the aggregate itself was renamed.
+        attr_reader :ancestor_name, :ancestor_storage_name
+
+        def self.for(registry, domain, aggregate)
+          translation = registry.translations.find do |candidate|
+            candidate.domain == domain.to_s && candidate.for_aggregate(aggregate.name)
+          end
+          return nil unless translation
+
+          from_declared(translation.for_aggregate(aggregate.name), aggregate.name)
+        end
+
+        # One SPECIFIC edge's rules for one aggregate — what the mint
+        # path uses, where `for` would happily answer with whichever
+        # edge in the registry mentioned the aggregate first.
+        def self.from_declared(declared, aggregate_name)
+          return nil unless declared
+
+          renamed_aggregate = declared.was && declared.was != aggregate_name.to_s
+          ancestor_name = renamed_aggregate ? declared.was : nil
+          ancestor_storage_name = renamed_aggregate ? Naming.snake(declared.was) : nil
+
+          new(declared.renames, declared.moves, declared.converts, declared.drops,
+              retypes: declared.retypes, computes: declared.computes, rekeys: declared.rekeys,
+              backfills: declared.backfills,
+              ancestor_name: ancestor_name, ancestor_storage_name: ancestor_storage_name)
+        end
+
+        def initialize(renames, moves = [], converts = [], drops = [], retypes: [], computes: [], rekeys: [],
+                       backfills: [], ancestor_name: nil, ancestor_storage_name: nil)
+          @renames = renames
+          @moves = moves
+          @converts = converts
+          @drops = drops
+          @retypes = retypes
+          @computes = computes
+          @rekeys = rekeys
+          @backfills = backfills
+          @ancestor_name = ancestor_name
+          @ancestor_storage_name = ancestor_storage_name
+        end
+
+        # Whether any rule in this edge is a compute — the one rule kind
+        # with no in-process implementation at all. An aggregate carrying
+        # one refuses to boot anywhere but Postgres, per-rule and by name,
+        # before the general drift machinery says anything vaguer.
+        def computes? = !@computes.empty?
+
+        # THE SINGLE SOURCE OF TRUTH for "does this edge rekey this
+        # aggregate" — every consumer (coverage_check.rb's identity gate,
+        # minter.rb's approval gate, layer_two.rb's audit, head_compiler.rb's
+        # SQL compilation) asks THIS, never re-derives it from `declared`
+        # independently. One accessor to change if what a rekey rule means
+        # ever needs to change, not four call sites in four files.
+        def rekey? = !@rekeys.empty?
+
+        # The rekey's own SQL — first-and-only rule, same one-per-aggregate
+        # assumption `compute` makes about its own list where it matters
+        # (an edge with more than one is a DSL-level decision, not
+        # something this reader arbitrates).
+        def rekey_sql = @rekeys.first&.sql
+
+        # The reference semantics for the five PORTABLE rule kinds —
+        # rename, move, convert, drop, and the aggregate-level `was:`.
+        # `retype` moves nothing (stored state never carries a type name)
+        # and `compute` is deliberately not applied here: its SQL is its
+        # only implementation, so this transform neither imitates nor
+        # checks it — the source field passes through untouched, and the
+        # audit verifies compute output against the matview alone.
+        def translate(entry)
+          return entry unless entry.save? && entry.state
+
+          # Deep, not shallow: a move or convert reaches INTO a nested
+          # value-object hash, and a shallow dup would quietly mutate
+          # the caller's copy of the original entry.
+          state = deep_dup(entry.state)
+          @renames.each { |old_name, new_name| state[new_name] = state.delete(old_name) if state.key?(old_name) }
+          @moves.each { |move| apply_move(state, move) }
+          @converts.each { |convert| apply_convert(state, convert) }
+          @drops.each { |name| apply_drop(state, name) }
+          # LAST, and only where nothing already answered — a backfill
+          # fills the gap a rename/move/convert left untouched, never
+          # overwrites a value that already made it across.
+          @backfills.each { |backfill| state[backfill.name] = backfill.default unless state.key?(backfill.name) }
+          Entry.new(operation: entry.operation, id: entry.id, state: state, mirrors: entry.mirrors)
+        end
+
+        # Whether this translation names `path` as an old key it accounts
+        # for — the rename, move, or convert it came from, or an explicit
+        # drop. `path` is a bare name ("cost") or a dotted value-object
+        # member ("price.currency"); a rule covering the WHOLE top-level
+        # attribute (a rename, a top-level move/convert/drop) also covers
+        # anything nested under it, since the whole value travels or goes
+        # away together. Used to catch a field — or a value object's own
+        # member — that vanished (or silently changed type) without
+        # anything explaining it, even when some OTHER field is covered.
+        #
+        # `backfills` matches on the WHOLE name only, never a dotted
+        # prefix — a backfill names a top-level attribute that is new
+        # outright (nothing to be a prefix of on the held side), unlike
+        # every rule above it, which explains a path that existed and
+        # moved, converted, or vanished.
+        def explains?(path)
+          path = path.to_s
+          top = path.split(".").first
+
+          @renames.key?(top.to_sym) ||
+            @moves.any? { |move| move.from == path || move.from.split(".").first == top } ||
+            @converts.any? { |convert| convert.from == path || convert.from.split(".").first == top } ||
+            @drops.any? { |drop| drop.to_s == path || drop.to_s.split(".").first == top } ||
+            @computes.any? { |compute| compute.from == path || compute.from.split(".").first == top } ||
+            @backfills.any? { |backfill| backfill.name.to_s == top }
+        end
+
+        # THE DESTINATION-SIDE TWIN of `explains?` above, which only ever
+        # asks about a rule's SOURCE. `unsafe_additions` asks a different
+        # question — not "was this vanished path accounted for" but "does
+        # an existing record end up with a value here" — and a move or
+        # convert whose `to:` lands a old field inside a BRAND-NEW
+        # top-level attribute (`weight` becoming `contents.weight` when
+        # `Contents` did not exist before) fills that attribute for an
+        # existing record exactly as a `backfill` would, even though
+        # nothing named `contents` explains any vanished path. `compute`
+        # counts on the same terms `explains?` already grants it
+        # elsewhere in this file — Postgres-only and audited, not
+        # actually applied by THIS method, the same gap the vanish side
+        # already lives with.
+        #
+        # `@renames.value?` belongs here too, and used to be missing: a
+        # bare `rename :cost, to: :amount` is the plainest possible
+        # covering rule there is (`translate` above applies it
+        # unconditionally, no lookup table, no per-record ambiguity —
+        # simpler than a move or convert, which both got their `fills?`
+        # entry from the start), and its absence meant `unsafe_additions`
+        # reported the new name as an unexplained required addition on
+        # EVERY rename-only edge, the single most common translation
+        # shape there is. `explains?` already checked the source side
+        # (`@renames.key?`); `fills?` is the symmetric destination-side
+        # check that was never added alongside it.
+        def fills?(path)
+          path = path.to_s
+
+          @renames.value?(path.to_sym) ||
+            @moves.any? { |move| move.to.split(".").first == path } ||
+            @converts.any? { |convert| convert.to.split(".").first == path } ||
+            @computes.any? { |compute| compute.to.split(".").first == path } ||
+            @backfills.any? { |backfill| backfill.name.to_s == path }
+        end
+
+        # Whether a declared retype says the pair of TYPE names means the
+        # same shape — a value object or entity whose own name changed
+        # with its members intact. Nothing in the stored data carries the
+        # type name, so this never moves a value; it only satisfies the
+        # era diff's literal type-name comparison.
+        def retype?(held_type, current_type)
+          @retypes.any? { |retype| retype.from == held_type.to_s && retype.to == current_type.to_s }
+        end
+
+        private
+
+        def deep_dup(node)
+          case node
+          when Hash then node.transform_values { |value| deep_dup(value) }
+          when Array then node.map { |item| deep_dup(item) }
+          else node
+          end
+        end
+
+        def apply_drop(state, name)
+          name = name.to_s
+          top, member = name.split(".", 2)
+          top = top.to_sym
+
+          if member
+            nested = state[top]
+            if nested.is_a?(Hash)
+              nested.delete(member)
+              state.delete(top) if nested.empty?
+            end
+          else
+            state.delete(top)
+          end
+        end
+
+        # A dotted path's first segment is a top-level (symbol) key; a
+        # second segment reaches into a value-object member, stored with a
+        # string key exactly as the adapter's own journal reader loaded it.
+        def apply_move(state, move)
+          old_top, old_member = move.from.split(".", 2)
+          new_top, new_member = move.to.split(".", 2)
+          old_top = old_top.to_sym
+
+          value, present = extract(state, old_top, old_member)
+          return unless present
+
+          insert(state, new_top.to_sym, new_member, value, rule: "move #{move.from} to: #{move.to}")
+        end
+
+        # A convert is a move whose value has nothing in common with its
+        # replacement — the same path machinery, plus a lookup. A value
+        # with no entry in the table refuses loudly rather than carry an
+        # unrecognized value silently into the new era.
+        def apply_convert(state, convert)
+          old_top, old_member = convert.from.split(".", 2)
+          new_top, new_member = convert.to.split(".", 2)
+          old_top = old_top.to_sym
+
+          raw, present = extract(state, old_top, old_member)
+          return unless present
+
+          unless convert.values.key?(raw)
+            raise Runtime::WiringError,
+                  "cannot translate #{convert.from}: #{raw.inspect} has no mapping in its " \
+                  "convert's values: table. Add #{raw.inspect} => ... to cover it."
+          end
+
+          insert(state, new_top.to_sym, new_member, convert.values[raw], rule: "convert #{convert.from} to: #{convert.to}")
+        end
+
+        def extract(state, top, member)
+          return [nil, false] unless state.key?(top)
+          return [state.delete(top), true] unless member
+
+          nested = state[top]
+          return [nil, false] unless nested.is_a?(Hash) && nested.key?(member)
+
+          value = nested.delete(member)
+          state.delete(top) if nested.empty?
+          [value, true]
+        end
+
+        # ADVERSARIAL FINDING, not a hypothetical: a destination whose
+        # top segment ALREADY holds a value — most commonly a reference,
+        # stored as a bare scalar id — used to be silently clobbered with
+        # an empty hash the moment a dotted destination needed to nest
+        # under it (`state[top] ||= {}` only guards nil/false, so a
+        # truthy non-Hash sailed straight through to `state[top][member] =`,
+        # i.e. `"team-1"["detail"] =`, which is String#[]=  and raised an
+        # unrelated-looking IndexError). Whether it crashed or silently
+        # replaced the value, this is a `drop` that never declared
+        # itself — the one thing this language exists to make explicit
+        # (see apply_convert's own refusal above, the same shape). Refuse
+        # by name instead, on both sides: the SQL half (hecks_tr_insert)
+        # raises the identical wording.
+        def insert(state, top, member, value, rule:)
+          return state[top] = value unless member
+
+          if state.key?(top) && !state[top].is_a?(Hash)
+            raise Runtime::WiringError,
+                  "cannot #{rule}: #{top} already holds #{state[top].inspect}, not a value this can nest " \
+                  "under — moving into it would discard that value silently. Rename or drop #{top} first."
+          end
+
+          state[top] ||= {}
+          state[top][member] = value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Hecks
+  module Ports
+    module Persistence
+      # THE NO-OP SAGA STORE — what `Registry#saga_persistence` hands
+      # back for a domain whose resolved adapter doesn't implement the
+      # (optional) saga-persistence capability: Memory, deliberately
+      # (sagas stay in-memory-only, exactly as they always have), and
+      # any `RemoteRuntime`-shaped adapter (Lambda; the real durability
+      # for those lives on the other side of the call — Phase 1, not
+      # here). `SagaInterpreter`'s hook points call through
+      # `saga_persistence(domain)` unconditionally; this is what makes
+      # that safe without a `respond_to?` check at every call site,
+      # mirroring the same optional-capability shape
+      # `Ports::Persistence::AppendOnly` already gives adapters that
+      # don't implement `reset!`/`events`/`record_event`.
+      class NullSagaStore
+        def save_saga(**) = nil
+        def delete_saga(**) = nil
+        def each_saga(*) = nil
+      end
+
+      NULL_SAGA_STORE = NullSagaStore.new
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+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.
+      module RemoteRuntime
+        def append(*)
+          raise Runtime::WiringError,
+                "#{self.class.name} is a remote-runtime delegate — dispatch through " \
+                "Runtime::RemoteDispatcher instead of writing through the repository directly"
+        end
+        alias_method :project, :append
+
+        def entries = []
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+require_relative "append_only"
+
+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.
+      module RepositoryFactory
+        module_function
+
+        def build(registry, domain, aggregate, bind, recover: true, settings_verb: VERB)
+          registry.check_verb(bind)
+          settings = (registry.world(domain)&.for_binding(settings_verb, bind.adapter) || {})
+                     .reject { |key, _| key.to_sym == :role }
+          registry.check_settings(bind, settings)
+          # The domain and the resolved era ride along after the
+          # declared-settings check: a lineage adapter journals per
+          # DOMAIN and writes into its own ERA's partition — neither of
+          # which a world's settings carry.
+          adapter = registry.adapter_class(bind.adapter)
+                            .new(aggregate: aggregate,
+                                 settings:  settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s]),
+                                 root:      registry.root)
+          repository = AppendOnly.new(adapter)
+          recover ? repository.recover! : repository
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence.port

@@ -0,0 +1,4 @@
+Hecks.port "persistence" do
+  verb   "persisted_by"   
+  signal :reply           
+end