hecks 5.0.0 → 7.0.0

data/lib/hecks/adapters/driven/postgres/projection.rb

@@ -0,0 +1,43 @@
+require "json"
+require_relative "../projection/read_model_walk"
+
+# The subclass needs its parent — and postgres.rb requires this file at
+# its bottom, after class Postgres is defined, so the require cycle this
+# creates resolves correctly from either entry point.
+require_relative "../postgres"
+
+module Hecks
+  module Adapters
+    # A Postgres read store rebuilt from the authoritative journal, entry by entry, answering a
+    # rooted read model from its own tables (ADR 0122). Its world names its own `database` and
+    # `schema`, apart from the authoritative store's.
+    class PostgresProjection < Postgres
+      include Projection::ReadModelWalk
+
+      private
+
+      def projected_row(aggregate, id)
+        result = pg_exec_params("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE id = $1", [id])
+        result.ntuples.zero? ? nil : result[0]
+      end
+
+      # A reference column holds the id, so it compares directly against itself.
+      def related_rows(aggregate, matches)
+        clauses = matches.each_with_index.map { |(attribute, _id), index| "#{quote_ident(attribute.name)} = $#{index + 1}" }
+        bind = matches.map { |_attribute, id| id }
+        # Byte order, as the in-process loop sorts ids, whatever the database's collation.
+        sql = "SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE #{clauses.join(" OR ")} ORDER BY id COLLATE \"C\""
+        pg_exec_params(sql, bind).to_a
+      end
+
+      # `pg` answers every column as text: a list or value object parses from JSON, a declared
+      # number coerces back (see Codec#coerce_scalar), and anything else reads as stored.
+      def decode_column(aggregate, attribute, raw)
+        return raw if attribute.nil?
+        return (raw ? JSON.parse(raw) : nil) if json_column?(aggregate, attribute)
+
+        coerce_scalar(attribute, raw)
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres/repository.rb

@@ -104,7 +104,7 @@ module Hecks
         # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
         # @return [Boolean] always true
         # @raise [PG::Error] if either statement fails; the transaction is rolled back
-        def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, not a question
+        def delete(id)
           entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
           transaction do
             append(entry)
@@ -128,7 +128,7 @@ module Hecks
           return "ORDER BY id" unless order_by
 
           name = order_by.to_s.split(".").first
-          unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+          unless @aggregate.lifecycle_field.to_s == name || @aggregate.attribute(name)
             raise Runtime::WiringError,
                   "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"
           end

data/lib/hecks/adapters/driven/postgres/schema_builder.rb

@@ -82,7 +82,8 @@ module Hecks
 
         def index_query!(query)
           query.wheres.each { |clause| index_field!(clause.field) }
-          index_field!(query.order_by.field) if query.order_by
+          field = query.order_by_field
+          index_field!(field) if field
         end
 
         # A list attribute is never indexed: `contains` compiles to EXISTS over

data/lib/hecks/adapters/driven/postgres/set_dialect.rb

@@ -0,0 +1,44 @@
+module Hecks
+  module Adapters
+    class Postgres
+      # Postgres's spellings for the shared {SetTransform} statement (ADR 0129).
+      module SetDialect
+        # The type each placeholder is cast to, so Postgres never has to guess one.
+        PLACEHOLDER_TYPES = { integer: "bigint", float: "double precision", string: "text", json: "jsonb" }.freeze
+
+        # The cast that reads a JSON member back as the type Ruby holds it as.
+        READ_CASTS = { integer: "::bigint", float: "::double precision", string: "" }.freeze
+
+        # @return [String] the dialect the operator ledger's renderings name
+        def set_transform_dialect = "postgres"
+
+        private
+
+        def typed_placeholder(binds, value, type)
+          binds << value
+          "$#{binds.size}::#{PLACEHOLDER_TYPES.fetch(type)}"
+        end
+
+        def null_safe_equality(left, right, negated:) = "(#{left} IS #{"NOT " unless negated}DISTINCT FROM #{right})"
+
+        # The C collation compares by bytes, as Ruby compares Strings; the database's own may not.
+        def text_ordering(sql) = "(#{sql}) COLLATE \"C\""
+
+        # Postgres refuses an overflowing bigint itself, which rolls the statement back.
+        def integer_guard(_sql) = nil
+
+        def scalar_read(column, member, type) = "(#{quote_ident(column)} ->> #{text_literal(member)})#{READ_CASTS.fetch(type)}"
+
+        def scalar_write(member, sql) = "jsonb_build_object(#{text_literal(member)}, #{sql})"
+
+        def version_bump = ["hecks_version = #{quoted_table}.hecks_version + 1"]
+
+        def run_set_transform(sql, binds)
+          pg_exec_params(sql, binds).map { |row| instance_from_row(row) }
+        rescue PG::Error => e
+          raise SetTransform::Declined, "Postgres refused the set transform: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres/shared_connection.rb

@@ -12,7 +12,7 @@ module Hecks
     # transaction. The owning thread re-enters freely, so a nested `transaction` joins the open
     # one, whichever aggregate's adapter opened it.
     class PostgresSharedConnection
-      REGISTRY = {} # rubocop:disable Style/MutableConstant
+      REGISTRY = {}
       REGISTRY_LOCK = Mutex.new
       private_constant :REGISTRY, :REGISTRY_LOCK
 

data/lib/hecks/adapters/driven/postgres.adapter

@@ -2,4 +2,12 @@ Hecks.adapter "Postgres" do
   port  "persistence"
   field :database
   field :schema
+  # Rewrites every row of an aggregate in one statement.
+  provides "set_transform"
+end
+
+Hecks.adapter "PostgresProjection" do
+  port  "projection"
+  field :database
+  field :schema
 end

data/lib/hecks/adapters/driven/postgres.rb

@@ -2,12 +2,15 @@ require "json"
 
 require_relative "sql_query_builder"
 require_relative "postgres/schema_builder"
+require_relative "postgres/name_guard"
 require_relative "postgres/codec"
 require_relative "postgres/dialect"
 require_relative "postgres/events"
 require_relative "postgres/journal"
 require_relative "postgres/repository"
 require_relative "postgres/sagas"
+require_relative "postgres/set_dialect"
+require_relative "set_transform"
 require_relative "../../ports/persistence/append_only"
 require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/common/order_by"
@@ -27,6 +30,7 @@ module Hecks
     class Postgres
       include SqlQueryBuilder
       include SchemaBuilder
+      include NameGuard
       include Codec
       include Repository
       include Journal
@@ -35,15 +39,16 @@ module Hecks
       include PostgresOutbox
       include PostgresReconnect
       include Dialect
+      include SetTransform
+      include SetDialect
 
       SQL_TYPES = { "Integer" => "bigint", "Float" => "double precision" }.freeze
 
       attr_reader :aggregate
 
       # Names the optional persistence capabilities `Ports::Persistence::AppendOnly` may rely on.
-      #
-      # @return [Array<Symbol>] `[:atomic_put, :optimistic_concurrency]`
-      def persistence_capabilities = [:atomic_put, :optimistic_concurrency]
+      # @return [Array<Symbol>] atomic_put, optimistic_concurrency and dispatch_claims
+      def persistence_capabilities = %i[atomic_put optimistic_concurrency dispatch_claims]
 
       # Opens a connection to the database a world declares, scoped to its `schema` if any.
       #
@@ -122,6 +127,7 @@ module Hecks
         # Scopes saga rows; falls back to the aggregate's storage name when
         # settings gives no domain (e.g. a directly-instantiated adapter).
         @domain = settings.fetch(:domain) { aggregate.storage_name }.to_s
+        refuse_orphaned_rows!
         create_tables!
       end
 
@@ -143,3 +149,5 @@ module Hecks
     end
   end
 end
+
+require_relative "postgres/projection"

data/lib/hecks/adapters/driven/postgres_dump/connection.rb

@@ -0,0 +1,57 @@
+require "uri"
+
+module Hecks
+  module Adapters
+    class PostgresDump
+      # 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
+        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, empty when the URL names none.
+        def database
+          @uri.path.to_s.delete_prefix("/")
+        end
+
+        # 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; the
+        # user and password come back percent-decoded.
+        def settings
+          {
+            host: (@uri.host unless @uri.host.to_s.empty?), port: @uri.port,
+            user: decode(@uri.user), password: decode(@uri.password),
+            dbname: (database unless database.empty?), sslmode: query_params["sslmode"]
+          }.compact
+        end
+
+        # Builds the libpq environment variables for a child process.
+        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; the caller closes it.
+        def connect
+          require "pg"
+          PG.connect(**settings)
+        end
+
+        private
+
+        def query_params = URI.decode_www_form(@uri.query.to_s).to_h
+
+        def decode(value)
+          value && URI.decode_www_form_component(value)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres_dump.rb

@@ -0,0 +1,117 @@
+require "open3"
+require "securerandom"
+require_relative "postgres_dump/connection"
+require_relative "../../text"
+require_relative "../../ports/persistence"
+
+module Hecks
+  module Adapters
+    # 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: `tables` is each table's row count, by name.
+      Result = Struct.new(:tables, keyword_init: true)
+
+      # A schema name that needs no quoting: a letter or underscore, then word characters.
+      PLAIN_IDENTIFIER = /\A[a-z_][a-z0-9_]*\z/i
+
+      # 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?(PLAIN_IDENTIFIER)
+
+        @schema = schema
+        @source = Connection.new(url)
+        @verify = Connection.new(verify_url || url)
+      end
+
+      # Writes a custom-format dump of the schema and proves it restores.
+      def call(dest)
+        require "pg"
+        raise Error, "schema #{@schema} has no tables in #{@source.database}" if source_counts.empty?
+
+        run("pg_dump", @source, "--format=custom", "--no-owner", "--no-privileges", "--schema=#{@schema}", "--file=#{dest}")
+        expected = source_counts
+        verify_restore(dest, expected)
+        Result.new(tables: expected)
+      rescue PG::Error => e
+        raise Error, "database error (#{e.class}): #{Text.first_line(e.message)}"
+      end
+
+      private
+
+      # The first few lines of a tool's stderr, enough to say why it failed.
+      def opening_lines(text)
+        head = text.lines.first(3)
+        head.join.strip
+      end
+
+      def source_counts = counting(@source) { |db| counts(db) }
+
+      def verify_restore(dump, expected)
+        scratch = "dump_verify_#{Process.pid}_#{SecureRandom.hex(3)}"
+        counting(@verify) do |admin|
+          admin.exec("CREATE DATABASE #{admin.quote_ident(scratch)}")
+          begin
+            restore_and_compare(dump, scratch, expected)
+          ensure
+            drop(admin, scratch)
+          end
+        end
+      end
+
+      def restore_and_compare(dump, scratch, expected)
+        target = @verify.with_database(scratch)
+        run("pg_restore", target, "--no-owner", "--no-privileges", "--exit-on-error", "--dbname=#{scratch}", dump)
+        actual = counting(target) { |db| counts(db) }
+        raise Error, mismatch(expected, actual) unless actual == expected
+      end
+
+      def counting(connection)
+        db = connection.connect
+        yield db
+      ensure
+        db&.close
+      end
+
+      def counts(db)
+        names = db.exec_params("SELECT table_name FROM information_schema.tables " \
+                               "WHERE table_schema = $1 AND table_type = 'BASE TABLE' ORDER BY 1", [@schema])
+                  .map { |row| row["table_name"] }
+        names.to_h do |name|
+          [name, db.exec("SELECT count(*) FROM #{db.quote_ident(@schema)}.#{db.quote_ident(name)}").getvalue(0, 0).to_i]
+        end
+      end
+
+      def mismatch(expected, actual)
+        differing = (expected.keys | actual.keys).reject { |name| expected[name] == actual[name] }
+        detail = differing.map { |name| "#{name} (source #{expected[name].inspect}, restored #{actual[name].inspect})" }
+        "the restored dump disagrees with the source for #{detail.join(", ")}; " \
+          "if the database took writes during the dump, dump it again"
+      end
+
+      def drop(admin, scratch)
+        admin.exec("DROP DATABASE IF EXISTS #{admin.quote_ident(scratch)} WITH (FORCE)")
+      rescue PG::Error => e
+        warn "could not drop scratch database #{scratch} (#{e.class}); drop it by hand"
+      end
+
+      def run(tool, connection, *)
+        _out, err, status = Open3.capture3(connection.env, tool, *)
+        raise Error, "#{tool} failed: #{opening_lines(err)}" unless status.success?
+      rescue Errno::ENOENT
+        raise Error, "#{tool} is not on PATH"
+      end
+    end
+  end
+
+  module Ports
+    # The persistence port, reopened only to keep the name below.
+    module Persistence
+      # The name embryonaut_platform's handoff tooling reaches it by.
+      PostgresDump = Adapters::PostgresDump
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres_era/boot.rb

@@ -0,0 +1,58 @@
+require_relative "../../../indifferent_key"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # Connects a boot to its database without provisioning it: the connection selects the declared
+      # schema and creates nothing. Only the mint path opens with `PostgresEra.connect_for`, which
+      # creates the schema.
+      module ReadConnector
+        # @param name [String] the domain or aggregate name, used only in refusal messages
+        # @param settings [Hash{Symbol, String => Object}] the persistence settings of the boot
+        # @return [PG::Connection] an open connection that writes no schema
+        def self.connect_for(name, settings) = PostgresEra.connect_for(name, settings, provision: false)
+      end
+
+      # The steps `PostgresEra#initialize` runs after joining the shared connection: naming the
+      # journal, resolving the era it reads, and reading the field caches that era holds. A boot
+      # writes nothing; the mint path provisions everything.
+      module Boot
+        private
+
+        # Journal name: the owning bluebook's declared name, matching the key rust/host derives its
+        # advisory lock from (ADR 0036). A bare aggregate with no owner falls back to its own name.
+        def journal_domain(aggregate, settings)
+          owner = aggregate.hecks_owner
+          self.class.setting(
+            settings, :domain, default: owner&.name || aggregate.storage_name
+          ).to_s
+        end
+
+        # Resolves the era this boot reads. A database that holds no era has never been minted, so
+        # the boot refuses by name rather than reading an absent lineage.
+        #
+        # The era is read from the held eras, never written: the factory passes `era:` once the
+        # boot gate resolved it, and nil can never be a real override.
+        def resolve_era!(settings)
+          @era = IndifferentKey.read(settings, :era)
+          held = @lineage.eras
+          refuse_unminted! if held.empty?
+          @era ||= held.last[:ordinal]
+          # Non-nil only for a held-but-superseded boot. `append` and `atomic_put` refuse on it
+          # because a superuser walks through the RLS fence.
+          @superseded_by = IndifferentKey.read(settings, :superseded_by)
+          # True only for a boot whose shape no held era matches and that carries no mint request.
+          # It reads the latest era and refuses writes until a mint runs.
+          @unminted = IndifferentKey.read(settings, :unminted) == true
+        end
+
+        # @raise [Runtime::WiringError] always: the database holds no era for a boot to read
+        def refuse_unminted!
+          raise Runtime::WiringError,
+                "cannot boot #{@domain}: no era held; the database is unminted, so run the mint entry " \
+                "point (`hecks era.hold_first! <domain directory> --confirm`) to provision and hold the first era"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/{ports/persistence/plugins/era → adapters/driven}/postgres_era/class_methods.rb

@@ -1,4 +1,4 @@
-require_relative "../../../../../runtime/errors"
+require_relative "../../../runtime/errors"
 
 module Hecks
   module Adapters
@@ -12,15 +12,32 @@ module Hecks
         # @param settings [Hash{Symbol, String => Object}] persistence settings; needs `database`
         # @param directory [String, nil] where `HECKS_SCAFFOLD=1` writes a translation edge
         # @return [Integer, nil] the ordinal of the era this boot minted, or nil when none
-        # @raise [Runtime::WiringError] if the database is unreachable or the mint refuses
+        # @raise [Runtime::WiringError] if the database is unreachable or the mint refuses, or the
+        #   binding's `mints_era` and the bluebook's command words disagree
         # @raise [Bluebook::DSL::Malformed] if a held era's text parses under no grammar
         def era_check!(registry:, bluebook:, current_text:, settings:, directory: nil)
+          Ports::Persistence::MintDoor.check!(bluebook, settings)
           LineageManager.check!(
             registry: registry, bluebook: bluebook, current_text: current_text,
             settings: settings, directory: directory
           )
         end
 
+        # What a boot of this bluebook would resolve, read from its own database over a connection
+        # that can only read. The boot's `era_check!` records the same answer. See
+        # `LineageManager::EraResolution`.
+        #
+        # @param registry [Runtime::Registry] the loaded registry, for its translation edges
+        # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+        # @param settings [Hash{Symbol, String => Object}] persistence settings; needs `database`
+        # @param directory [String, nil] the domain's bluebook directory
+        # @return [LineageManager::EraResolution::Answer]
+        # @raise [Runtime::WiringError] if the database is unreachable or a held text was altered
+        def era_status(registry:, bluebook:, settings:, directory: nil)
+          LineageManager::EraResolution.read(bluebook: bluebook, settings: settings,
+                                             translations: registry.translations, directory: directory)
+        end
+
         # Reads one setting under either its Symbol or String spelling.
         #
         # Uses `key?` rather than `||` so a stored `false` is not mistaken for an absent key.
@@ -40,13 +57,15 @@ module Hecks
         #
         # @param name [String] the domain or aggregate name, used only in refusal messages
         # @param settings [Hash{Symbol, String => Object}] `database` is a name or `postgres://` URL
+        # @param provision [Boolean] whether a declared `schema` that does not exist yet is created;
+        #   a mint or an owner write passes true, a boot passes false and reads what is there
         # @return [PG::Connection] an open connection
         # @raise [Runtime::WiringError] if `database` is missing or Postgres refuses a statement
-        def connect_for(name, settings)
+        def connect_for(name, settings, provision: true)
           require_pg!(name)
           declared = declared_database(name, settings)
           connection = open_connection(declared)
-          prepare_session!(connection, setting(settings, :schema))
+          prepare_session!(connection, setting(settings, :schema), provision: provision)
           connection
         rescue StandardError => e
           # PG is only defined once the gem loads, so the clause cannot name it.
@@ -81,14 +100,15 @@ module Hecks
 
         # A declared `schema` means the instance is shared; search_path makes every unqualified
         # name this adapter and its lineage classes build resolve inside that schema.
-        def prepare_session!(connection, schema)
+        def prepare_session!(connection, schema, provision:)
           if schema.to_s != ""
-            # Idempotent: the schema may not exist yet on the first boot.
-            connection.exec("CREATE SCHEMA IF NOT EXISTS #{connection.quote_ident(schema)}")
+            # A mint creates the schema, idempotently; a read leaves it uncreated. An unknown
+            # search_path names no relation, so the lineage reads as unminted.
+            connection.exec("CREATE SCHEMA IF NOT EXISTS #{connection.quote_ident(schema)}") if provision
             connection.exec("SET search_path TO #{connection.quote_ident(schema)}")
           end
 
-          # Provisioning re-runs CREATE ... IF NOT EXISTS on every boot; silence the notices.
+          # Provisioning runs CREATE ... IF NOT EXISTS on every mint; silence the notices.
           # Warnings and above still surface.
           connection.exec("SET client_min_messages = warning")
         end

data/lib/hecks/{ports/persistence/plugins/era → adapters/driven}/postgres_era/dialect.rb

@@ -94,14 +94,19 @@ module Hecks
 
         def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
 
-        # Where-fields of the aggregate's and its entities' queries that a cache table can
-        # represent; order_by-only fields never needed a cache.
-        def ensure_field_caches!
-          cached_where_fields.to_h do |field|
-            [field, @lineage.ensure_field_cache!(table, @era, field, query_expression(field))]
+        # The cache tables of this era a boot may read: each cached where-field whose table exists.
+        # A boot creates none; the mint that held the era created them.
+        #
+        # @return [Hash{String => String}] each cached field mapped to its existing cache table
+        def existing_field_caches
+          cached_where_fields.each_with_object({}) do |field, found|
+            name = @lineage.field_cache(table, @era, field)
+            found[field] = name if @lineage.table_exists?(name)
           end
         end
 
+        # Where-fields of the aggregate's and its entities' queries that a cache table can
+        # represent; order_by-only fields never needed a cache.
         def cached_where_fields
           fields = declared_queries.flat_map do |q|
             q.wheres.map do |clause|
@@ -118,7 +123,7 @@ module Hecks
         # List fields are excluded: a one-value cache row cannot hold `contains` membership.
         def cacheable_field?(field)
           name = field.to_s.split(".").first
-          return true if @aggregate.lifecycle&.field.to_s == name
+          return true if @aggregate.lifecycle_field.to_s == name
 
           attribute = @aggregate.attribute(name)
           !attribute.nil? && !attribute.list?

data/lib/hecks/adapters/driven/postgres_era/field_cache_provisioner.rb

@@ -0,0 +1,39 @@
+require_relative "../sql_query_builder"
+require_relative "dialect"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # Creates and backfills one aggregate's field caches for one era. Only the mint path that
+      # compiles an era's head, and the first-era hold, run it; a boot reads the caches that exist.
+      class FieldCacheProvisioner
+        include SqlQueryBuilder
+        include Dialect
+
+        # @param lineage [Lineage] the owner lineage whose connection the caches are written on
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose where-fields are cached
+        # @param era [Integer] the ordinal of the era the caches belong to
+        def initialize(lineage, aggregate, era)
+          @lineage = lineage
+          @aggregate = aggregate
+          @era = era
+        end
+
+        # Names the aggregate in storage, as the adapter's `table` does.
+        #
+        # @return [String] the aggregate's snake_case storage name
+        def table = @aggregate.storage_name
+
+        # Creates each cached where-field's table if missing, then backfills it from the era's head.
+        #
+        # @return [Hash{String => String}] each cached field mapped to its cache table's name
+        # @raise [PG::Error] if Postgres refuses the DDL, a source read or an upsert
+        def provision!
+          cached_where_fields.to_h do |field|
+            [field, @lineage.ensure_field_cache!(table, @era, field, query_expression(field))]
+          end
+        end
+      end
+    end
+  end
+end