hecks 5.0.0 → 7.0.0

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

@@ -24,8 +24,7 @@ module Hecks
         # accelerate. Repeats the tail of `SqlQueryBuilder#query` so that module stays untouched.
         def head_phase(declared, uncached, ids, args)
           binds = []
-          clauses = ["id IN (#{ids.map { |id| placeholder(binds, id) }.join(", ")})"]
-          uncached.each { |clause, value| clauses << uncached_clause(clause, value, binds) }
+          clauses = head_clauses(declared, uncached, ids, args, binds)
 
           sql = "SELECT #{select_list} FROM #{from_relation} WHERE #{clauses.join(" AND ")}"
           sql += order_suffix(declared)
@@ -33,6 +32,13 @@ module Hecks
           execute_query(sql, binds)
         end
 
+        # The candidate ids, the clauses the cache could not serve, then the cursor's keyset.
+        def head_clauses(declared, uncached, ids, args, binds)
+          clauses = ["id IN (#{ids.map { |id| placeholder(binds, id) }.join(", ")})"]
+          uncached.each { |clause, value| clauses << uncached_clause(clause, value, binds) }
+          clauses.push(*keyset_clause(declared, args, binds))
+        end
+
         # A clause cache phase could not serve: a null comparison's own predicate, else the
         # operator's `where_clause` against the head view.
         def uncached_clause(clause, value, binds)

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

@@ -0,0 +1,32 @@
+require_relative "events"
+require_relative "sagas"
+require_relative "../postgres/outbox"
+
+module Hecks
+  module Adapters
+    class PostgresEra
+      # The event, saga and outbox tables a database shares across its domains. Only the mint path
+      # creates them, through `Lineage#ensure_base!`; a boot reads them and never provisions them.
+      class SharedTables
+        include Events
+        include Sagas
+        include PostgresOutbox
+
+        # @param db [PG::Connection] the owner connection the mint path holds
+        def initialize(db)
+          @db = db
+        end
+
+        # Creates each shared table that is missing. Every statement is idempotent.
+        #
+        # @return [void]
+        # @raise [PG::Error] if Postgres refuses a statement
+        def provision!
+          create_event_table!
+          create_saga_table!
+          create_outbox_table!
+        end
+      end
+    end
+  end
+end

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

@@ -1,11 +1,29 @@
-# Declares the PostgresEra adapter's port and fields; the class lives in the era plugin.
+# Declares the PostgresEra adapter's port and fields; the class is `postgres_era.rb` beside it.
 # This file is loaded on every boot, so it stays metadata only.
 Hecks.adapter "PostgresEra" do
   port  "persistence"
   field :database
   field :role
   field :schema
+  # The name this domain's history is held under until `era.rename_domain` moves it: `formerly "Old"`.
+  # A storage fact, so the world says it and the bluebook's `formerly_known_as` is the fallback.
+  field :formerly
   # Opt-in to boot over a superuser or BYPASSRLS role, which the era write fence cannot
   # bite. Refused by default; see `Lineage#check_fence_applies!`.
   field :allow_superuser
+  # Whether this copy may migrate the database to a newer storage shape at boot, by minting the
+  # next era through a translation edge. `false` refuses; unset follows
+  # `LineageManager::EraResolver::MINT_BY_DEFAULT`; see `Refusals#refuse_unpermitted_mint!`.
+  field :mint_eras
+  # Declares the store a disposable tooling ledger: a shape change needs no era, edge or mint, an
+  # additive one is applied in place, any other archives the aggregate's rows under a dated name
+  # and starts it empty, and a boot never refuses as unminted or superseded. Unset or `false`
+  # keeps the era guard; see `LineageManager::DisposableLedger`. Never for client data.
+  field :disposable_ledger
+  # The commands whose own record an unminted boot may write: `mints_era "Maintenance.MintEra"`, one
+  # `Aggregate.Command` name or a list. This is where the allowance is declared; a command's own
+  # `mints_era true` is a fallback that must agree. See `Ports::Persistence::MintDoor`.
+  field :mints_era
+  # Rewrites every row of an aggregate in one statement, on the same SQL path as Postgres.
+  provides "set_transform"
 end

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

@@ -1,9 +1,10 @@
 require "json"
 
-require_relative "../../../../adapters/driven/sql_query_builder"
-require_relative "../../../../adapters/driven/postgres/outbox"
-require_relative "../../../../adapters/driven/postgres/reconnect"
-require_relative "../../../../adapters/driven/postgres/shared_connection"
+require_relative "../../ports/persistence/plugins/era"
+require_relative "sql_query_builder"
+require_relative "postgres/outbox"
+require_relative "postgres/reconnect"
+require_relative "postgres/shared_connection"
 require_relative "postgres_era/lineage"
 require_relative "postgres_era/lineage_manager"
 require_relative "postgres_era/events"
@@ -14,12 +15,12 @@ require_relative "postgres_era/journal"
 require_relative "postgres_era/dialect"
 require_relative "postgres_era/query_phases"
 require_relative "postgres_era/head_writes"
-require_relative "../../../../ports/persistence/append_only"
-require_relative "../../../../query_specification/common/order_by"
-require_relative "../../../../runtime/errors"
-require_relative "../../../../runtime/event"
-require_relative "../../../../runtime/instance"
-require_relative "../../../../runtime/registry"
+require_relative "../../ports/persistence/append_only"
+require_relative "../../query_specification/common/order_by"
+require_relative "../../runtime/errors"
+require_relative "../../runtime/event"
+require_relative "../../runtime/instance"
+require_relative "../../runtime/registry"
 
 module Hecks
   module Adapters
@@ -48,8 +49,8 @@ module Hecks
       # the same transaction as the journal row, so replaying the journal through `project` on
       # boot has nothing left to fix up.
       #
-      # @return [Array<Symbol>] always `[:atomic_put, :cross_process_lock, :atomic_append]`
-      def persistence_capabilities = %i[atomic_put cross_process_lock atomic_append]
+      # @return [Array<Symbol>] atomic_put, cross_process_lock, atomic_append, dispatch_claims
+      def persistence_capabilities = %i[atomic_put cross_process_lock atomic_append dispatch_claims]
 
       # Declares that this adapter can act on shape drift rather than only refuse.
       #
@@ -62,22 +63,22 @@ module Hecks
       def self.tenant_capable? = true
 
       # Joins the process's shared connection for the declared database and schema, so every
-      # aggregate of a domain runs on one connection, then provisions the journal, this
-      # aggregate's head and field caches, and the event, saga and outbox tables. Every step is
-      # idempotent.
+      # aggregate of a domain runs on one connection, then resolves the era it reads and the field
+      # caches that era holds. Reads only: the lineage, head and cache tables are provisioned by the
+      # mint path, and a database no mint has provisioned refuses by name.
       #
       # @param settings [Hash{Symbol, String => Object}] world settings plus what
       #   `RepositoryFactory.build` merges in: `domain`, `era` and `superseded_by`
-      # @raise [Runtime::WiringError] if `database` is missing or the connection is refused
+      # @raise [Runtime::WiringError] if `database` is missing, the connection is refused, or the
+      #   database holds no era
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
         @settings  = settings
-        @db = PostgresSharedConnection.for(aggregate.name, settings, connector: self.class)
+        @db = PostgresSharedConnection.for(aggregate.name, settings, connector: ReadConnector)
         @domain = journal_domain(aggregate, settings)
-        @lineage = Lineage.new(@db, @domain)
-        @lineage.ensure_base!
+        @lineage = Lineage.new(@db, @domain, reading: true)
         resolve_era!(settings)
-        provision!
+        @field_caches = existing_field_caches
       end
 
       # Names this aggregate in storage: the journal's `aggregate` value and the stem of its
@@ -86,6 +87,16 @@ module Hecks
       # @return [String] the aggregate's snake_case storage name
       def table = @aggregate.storage_name
 
+      # Whether this binding's `mints_era` names the command: its own record may be journaled
+      # through a boot whose shape no era holds yet.
+      #
+      # @param aggregate_name [String] the aggregate the command belongs to
+      # @param command_name [String] the command
+      # @return [Boolean]
+      def mints_era_declared?(aggregate_name, command_name)
+        Ports::Persistence::MintDoor.declared?(@settings, aggregate_name, command_name)
+      end
+
       # Reads one record's current state through the head view, translated to the current shape.
       #
       # @param id [String, Object] the record's identity, compared as `id.to_s`
@@ -150,7 +161,12 @@ module Hecks
       # @yield the dispatch order; an exception rolls the transaction back
       # @return [Object] the block's own value
       # @raise [PG::ConnectionBad] if the connection dropped; it reconnects, then re-raises
-      def with_write_lock(&) = transaction { lock_writes!; yield } # rubocop:disable Style/Semicolon
+      def with_write_lock(&)
+        transaction do
+          lock_writes!
+          yield
+        end
+      end
 
       # Builds the instance an entry describes, writing nothing; the head is derived, so
       # projecting is reading.
@@ -182,7 +198,7 @@ module Hecks
       # @param id [String, Object] the record's identity, journaled as `id.to_s`
       # @return [true] always
       # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
-      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)
         append(entry)
         true
@@ -192,7 +208,7 @@ module Hecks
 
       def refuse_unknown_order_field!(order_by)
         name = order_by.to_s.split(".").first
-        return if @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+        return if @aggregate.lifecycle_field.to_s == name || @aggregate.attribute(name)
 
         raise Runtime::WiringError,
               "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"

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

@@ -10,7 +10,6 @@ module Hecks
       # Not frozen — a real cache, keyed by file path and mutated by
       # #tree_for below (`TREES[file] ||= ...`) and #forget/#forget_all.
       # False positive for Style/MutableConstant.
-      # rubocop:disable-next Style/MutableConstant
       TREES = {}
 
       # The first block node starting on each line, per parsed tree (by identity), built by one
@@ -45,8 +44,8 @@ module Hecks
         file, line = block.source_location
         return nil unless file && File.readable?(file)
 
-        node = block_node_at(file, line)
-        node&.body&.slice
+        body = block_node_at(file, line)&.body
+        body&.slice
       end
 
       # Finds the parsed block node starting on a given line of a file.
@@ -72,7 +71,8 @@ module Hecks
         walk(tree) do |node|
           next unless node.is_a?(::Prism::BlockNode)
 
-          index[node.location.start_line] ||= node
+          location = node.location
+          index[location.start_line] ||= node
         end
         index
       end

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

@@ -0,0 +1,126 @@
+require_relative "../../../runtime/instance"
+require_relative "../../../runtime/value"
+require_relative "../../../runtime/errors"
+require_relative "../../../runtime/refusal_wording"
+require_relative "../../../rendering"
+require_relative "../../../ports/query/in_memory"
+require_relative "row_decoding"
+
+module Hecks
+  module Adapters
+    # What a projection adapter shares, whatever its SQL dialect.
+    module Projection
+      # The read-model answer a projection gives from its own tables, the same walk
+      # `Runtime::ReadModelInterpreter` makes in process (ADR 0122 checks they agree).
+      #
+      # The including adapter supplies `projected_row(aggregate, id)`, the raw row for one id
+      # or nil, and `related_rows(aggregate, matches)`, the raw rows whose reference column
+      # holds any of the `[attribute, id]` pairs, ordered by id; `RowDecoding` turns each row
+      # into an instance through the adapter's own `decode_column`.
+      module ReadModelWalk
+        include RowDecoding
+
+        # The state of one `query_read_model` call, threaded through its per-head steps.
+        ReadModelRun = Struct.new(:model, :args, :bluebook, :reference_id, :eligible, :projected)
+
+        # Executes a declared read model against the projected read-store tables.
+        #
+        # A missing root raises, matching the in-process interpreter; a head
+        # matches against any already-projected source, not only the root.
+        #
+        # @param _domain [String, Symbol] domain name; not read
+        # @param model [Bluebook::ReadModel, Runtime::TenantScope::Scoped] read model to answer
+        # @param args [Hash] arguments; `model.reference_name` holds the root id
+        # @param bluebook [Bluebook::Declaration, nil] resolves each included aggregate; nil refused
+        # @return [Array<Hash>] one-element Array of the report, keyed by each head's `as`
+        # @raise [ArgumentError] if bluebook is nil
+        # @raise [Runtime::NotFound] if no projected row matches the referenced root id
+        def query_read_model(_domain, model, args, bluebook = nil)
+          raise ArgumentError, "projection query needs its domain bluebook" unless bluebook
+
+          # Read the same way ReadModelInterpreter reads it: an identity is a
+          # declared path, not unwrapped.
+          reference_id = args.fetch(model.reference_name).to_s
+          # Plural (ADR 0055): `on:` lets `where`/`order_by`/`limit`/`offset`
+          # each name a different many-side head, so more than one may be
+          # eligible in the same read model.
+          run = ReadModelRun.new(model, args, bluebook, reference_id, model.filtered_head_names, [])
+          [ordered_heads(model).to_h { |head| [head[:as], resolve_head(run, head)] }]
+        end
+
+        private
+
+        # Root first, always (see `query_read_model`'s own header): a later head's
+        # join must match against a root or head already resolved.
+        def ordered_heads(model)
+          root_heads, other_heads = model.aggregate_heads.partition { |head| head[:aggregate] == model.reference_target }
+          root_heads + other_heads
+        end
+
+        # Reads one head's rows, records them as projected so later heads can join against them,
+        # and returns the head's report entry.
+        def resolve_head(run, head)
+          rows = head_rows(run, head, run.bluebook.aggregate(head[:aggregate]))
+          rows = filter_rows(run, head, rows)
+          run.projected << { aggregate: head[:aggregate], rows: rows }
+          head_report(head, rows)
+        end
+
+        # Applies the head's `where`/`order_by`/`limit`/`offset` when the read model names it.
+        def filter_rows(run, head, rows)
+          return rows unless run.eligible.include?(head[:as])
+
+          Ports::Query::InMemory.execute(rows, run.model.options_for(head[:as]), run.args)
+        end
+
+        def head_report(head, rows)
+          return rows.map { |row| Runtime::Value.materialize(row.to_h) } if head[:many]
+
+          rows.first && Runtime::Value.materialize(rows.first.to_h)
+        end
+
+        def head_rows(run, head, aggregate)
+          model = run.model
+          return select_related(aggregate, run.projected) unless head[:aggregate] == model.reference_target
+
+          [select_projected(aggregate, run.reference_id) || raise(Runtime::NotFound, missing_root_wording(run, head))]
+        end
+
+        def missing_root_wording(run, head)
+          Runtime::RefusalWording.render_site("NotFound", "read_model_reference_missing",
+                                              aggregate: head[:aggregate],
+                                              offered:   Hecks::Rendering.describe(run.reference_id))
+        end
+
+        def select_projected(aggregate, id)
+          row = projected_row(aggregate, id.to_s)
+          row && projected_instance(aggregate, row)
+        end
+
+        # Matches every already-projected source, not just the root, so a head
+        # referencing another included head still matches. A head that names no aggregate of the
+        # bluebook (an entity, such as the language's `Handler`) has no rows, as the in-process loop
+        # reads it.
+        def select_related(aggregate, projected)
+          return [] unless aggregate
+
+          matches = projected.flat_map { |source| reference_matches(aggregate, source) }
+          return [] if matches.empty?
+
+          related_rows(aggregate, matches).map { |row| projected_instance(aggregate, row) }
+        end
+
+        # Every (reference attribute, id) pair by which `aggregate` points at one projected source.
+        def reference_matches(aggregate, source)
+          references = aggregate.attributes.select do |attribute|
+            attribute.target_name == source[:aggregate].to_s
+          end
+          return [] if references.empty?
+
+          ids = source[:rows].map { |row| row.id.to_s }
+          references.product(ids)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+require_relative "../../../runtime/instance"
+
+module Hecks
+  module Adapters
+    module Projection
+      # Reads a projected row of any aggregate back into an instance, so one adapter can answer
+      # every head of a read model and not only its own aggregate.
+      #
+      # The including adapter supplies `decode_column(aggregate, attribute, raw)`: how one
+      # declared column's stored text reads back in its dialect.
+      module RowDecoding
+        private
+
+        def projected_instance(aggregate, row)
+          Runtime::Instance.new(aggregate: aggregate, id: row["id"], state: decode_for(aggregate, row))
+        end
+
+        def decode_for(aggregate, row)
+          decode_fields(fields_for(aggregate), aggregate, row)
+        end
+
+        # Declared attributes plus the lifecycle field and any unlisted
+        # `projects` fields, all read back raw (see `decode_fields`).
+        def fields_for(aggregate)
+          fields = aggregate.attributes.map { |attribute| [attribute.name, attribute] }
+          # `projects` fields (ADR 0025) read back raw too, as `persisted_fields` writes them.
+          lifecycle = aggregate.lifecycle
+          raw_names = (lifecycle ? [lifecycle.field] : []) + aggregate.projected_fields.map(&:name)
+          raw_names.each { |raw| fields << [raw, nil] unless fields.any? { |name, _| name == raw } }
+          fields
+        end
+
+        # Decoded through the state codec against the row's own aggregate, so a NULL
+        # projected-only column reads back absent.
+        def decode_fields(fields, aggregate, row)
+          state = fields.each_with_object({}) do |(name, attribute), raw_state|
+            raw = row[name.to_s]
+            next if unset_projected?(aggregate, name, attribute, raw)
+
+            raw_state[name] = decode_column(aggregate, attribute, raw)
+          end
+          Ports::Persistence::StateCodec.decode(aggregate, state)
+        end
+
+        # A NULL column with no attribute reads back absent, except the lifecycle field.
+        def unset_projected?(aggregate, name, attribute, raw)
+          attribute.nil? && raw.nil? && aggregate.lifecycle_field&.to_sym != name.to_sym
+        end
+
+        # Whether `attribute` is stored as JSON: a list, or a value object of `aggregate`.
+        def json_column?(aggregate, attribute)
+          attribute.list? || !aggregate.value_object(attribute.type).nil?
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/set_transform/assignments.rb

@@ -0,0 +1,101 @@
+module Hecks
+  module Adapters
+    module SetTransform
+      # Compiles a statement's writes, its `SET` list, and the lifecycle conditions they bring:
+      # each assignment as its field is stored, and a lifecycle transition as a `CASE` over the
+      # states it moves from.
+      module Assignments
+        private
+
+        # @return [Array(Array<String>, Array<String>)] the assignments and the filter conditions
+        #   the lifecycle adds
+        def set_list(statement, build)
+          sets = statement.assignments.map { |assignment| assignment_sql(assignment, build) }
+          lifecycle_sets, conditions = lifecycle_moves(statement, build)
+          [sets + lifecycle_sets + version_bump, conditions]
+        end
+
+        # The lifecycle's assignment and the filter conditions its transition and `from:` guard add.
+        def lifecycle_moves(statement, build)
+          sets = []
+          conditions = []
+          if statement.transition
+            case_sql, condition = transition_sql(statement.transition, build)
+            sets << "#{quote_ident(@aggregate.lifecycle_field)} = #{case_sql}"
+            conditions << condition
+          end
+          conditions << state_in(statement.from_guard, build) if statement.from_guard
+          [sets, conditions]
+        end
+
+        def assignment_sql(assignment, build)
+          field = writable_field(assignment.target)
+          "#{quote_ident(field.name)} = #{assigned_value(field, assignment, build)}"
+        end
+
+        def assigned_value(field, assignment, build)
+          case assignment.kind
+          when :constant then constant_sql(field, assignment.value, build)
+          when :copy then copied_sql(field, assignment.value)
+          when :expression then expression_write(field, value_sql(assignment.value, build, strict: true), build)
+          when :step then stepped_sql(field, assignment.value, build)
+          else raise Uncompilable, "#{dialect_name} has no set-transform form for a #{assignment.kind} write"
+          end
+        end
+
+        # A constant is encoded once by this store's own codec, so every row holds what a save
+        # of that value would have written.
+        def constant_sql(field, value, build)
+          encoded = encode(@aggregate.attribute(field.name), value)
+          encoded.nil? ? "NULL" : typed_placeholder(build.binds, encoded, :json)
+        end
+
+        def copied_sql(field, source)
+          same_shape = @aggregate.attribute(source)&.type == @aggregate.attribute(field.name).type
+          raise Uncompilable, "#{dialect_name} copies a field only from one of the same type" unless same_shape
+
+          quote_ident(source)
+        end
+
+        def expression_write(field, operand, build)
+          raise Uncompilable, "#{field.name} holds #{field.type}, not #{operand.type}" unless operand.type == field.type
+
+          build.guards << "#{operand.sql} IS NOT NULL"
+          scalar_write(field.member, operand.sql)
+        end
+
+        def stepped_sql(field, amount, build)
+          raise Uncompilable, "#{dialect_name} steps only an Integer field" unless field.type == :integer
+
+          current = scalar_read(field.name, field.member, field.type)
+          build.guards << "#{current} IS NOT NULL"
+          sum = "(#{current} + #{typed_placeholder(build.binds, amount, :integer)})"
+          guard = integer_guard(sum)
+          build.guards << guard if guard
+          scalar_write(field.member, sum)
+        end
+
+        def writable_field(name)
+          field = Runtime::ScalarField.of(@aggregate, name)
+          return field if field&.writable?
+
+          raise Uncompilable, "#{dialect_name} writes #{name} only through a dispatch"
+        end
+
+        # Each case in order: the first whose states hold the current one, or that names none.
+        def transition_sql(cases, build)
+          conditions = cases.map { |from, _| from ? state_in(from, build) : "TRUE" }
+          whens = conditions.zip(cases).map do |condition, (_, target)|
+            "WHEN #{condition} THEN #{typed_placeholder(build.binds, target.to_s, :string)}"
+          end
+          ["CASE #{whens.join(" ")} END", "(#{conditions.join(" OR ")})"]
+        end
+
+        def state_in(states, build)
+          slots = Array(states).map { |state| typed_placeholder(build.binds, state.to_s, :string) }
+          "(COALESCE(#{quote_ident(@aggregate.lifecycle_field)}, '') IN (#{slots.join(", ")}))"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/set_transform/expressions.rb

@@ -0,0 +1,138 @@
+require_relative "../../../bluebook/expression"
+require_relative "../../../naming"
+require_relative "../../../runtime/scalar_field"
+
+module Hecks
+  module Adapters
+    module SetTransform
+      # Raised while compiling, before anything is written, when an expression or a write has no
+      # SQL form that means what Ruby means by it.
+      class Uncompilable < StandardError; end
+
+      # One compiled operand: its SQL text and the type Ruby would hold it as (`:integer`,
+      # `:float`, `:string`, or `:null` for a literal nil).
+      Operand = Struct.new(:sql, :type)
+
+      # What one statement collects while it compiles: the binds in placeholder order, the guards
+      # every updated row must also meet, and the command's arguments an expression reads.
+      Build = Struct.new(:binds, :guards, :arguments)
+
+      # Compiles a parsed bluebook expression to SQL in the including adapter's dialect. Every
+      # column an ordering comparison, an arithmetic operator or a sign test reads gets an
+      # `IS NOT NULL` guard, and every integer result the dialect's integer guard, so a row where
+      # Ruby would fault is never updated: the statement skips it and Ruby decides.
+      module Expressions
+        EVALUATOR = Bluebook::Expression::Evaluator
+        RESOLVER  = Bluebook::Expression::Resolver
+        ORDERING  = %w[< > <= >=].freeze
+        NUMERIC   = %i[integer float].freeze
+        SIGN_TESTS = { "positive?" => "> 0", "negative?" => "< 0", "zero?" => "= 0" }.freeze
+        ARITHMETIC = { RESOLVER::Addition => "+", RESOLVER::Subtraction => "-", RESOLVER::Multiplication => "*" }.freeze
+
+        private
+
+        def predicate_sql(node, build)
+          case node
+          when EVALUATOR::Or  then "(#{predicate_sql(node.left, build)} OR #{predicate_sql(node.right, build)})"
+          when EVALUATOR::And then "(#{predicate_sql(node.left, build)} AND #{predicate_sql(node.right, build)})"
+          when EVALUATOR::Not then "(NOT #{predicate_sql(node.node, build)})"
+          when EVALUATOR::Compare then compare_sql(node, build)
+          when EVALUATOR::Resolve then test_sql(node.expr, build)
+          else uncompilable(node)
+          end
+        end
+
+        def compare_sql(node, build)
+          symbol = node.operator_symbol
+          ordering = ORDERING.include?(symbol)
+          left, right = [node.left, node.right].map { |side| value_sql(side, build, strict: ordering) }
+          return equality_sql(left, right, symbol, node) unless ordering
+
+          uncompilable(node) unless ordered_pair?(left, right)
+          "(#{ordered_text(left)} #{symbol} #{ordered_text(right)})"
+        end
+
+        def equality_sql(left, right, symbol, node)
+          uncompilable(node) unless %w[== !=].include?(symbol) && comparable?(left, right)
+          null_safe_equality(left.sql, right.sql, negated: symbol == "!=")
+        end
+
+        def ordered_pair?(left, right)
+          (NUMERIC.include?(left.type) && NUMERIC.include?(right.type)) || [left.type, right.type] == %i[string string]
+        end
+
+        def comparable?(left, right)
+          left.type == :null || right.type == :null || ordered_pair?(left, right)
+        end
+
+        def ordered_text(operand) = operand.type == :string ? text_ordering(operand.sql) : operand.sql
+
+        def test_sql(node, build)
+          case node
+          when RESOLVER::SignTest then sign_test_sql(node, build)
+          when RESOLVER::Assignment
+            "(#{value_sql(node.receiver, build, strict: false).sql} IS #{"NOT " unless node.negated}NULL)"
+          else uncompilable(node)
+          end
+        end
+
+        def sign_test_sql(node, build)
+          receiver = value_sql(node.receiver, build, strict: true)
+          uncompilable(node) unless NUMERIC.include?(receiver.type) && SIGN_TESTS.key?(node.test)
+          "(#{receiver.sql} #{SIGN_TESTS.fetch(node.test)})"
+        end
+
+        def value_sql(node, build, strict:)
+          case node
+          when RESOLVER::IntegerLiteral, RESOLVER::FloatLiteral, RESOLVER::StringLiteral then scalar_bind(node.value, build)
+          when RESOLVER::NilLiteral then strict ? uncompilable(node) : Operand.new("NULL", :null)
+          when RESOLVER::Lookup then lookup_sql(node, build, strict)
+          when *ARITHMETIC.keys then arithmetic_sql(node, build)
+          else uncompilable(node)
+          end
+        end
+
+        # An argument is read before a field of the same name, as Ruby reads it.
+        def lookup_sql(node, build, strict)
+          name = node.path.to_sym
+          return argument_sql(build.arguments[name], build, strict, node) if build.arguments.key?(name)
+
+          field = Runtime::ScalarField.of(@aggregate, node.path) || uncompilable(node)
+          operand = Operand.new(field_read(field), field.type)
+          build.guards << "#{operand.sql} IS NOT NULL" if strict
+          operand
+        end
+
+        def argument_sql(value, build, strict, node)
+          return Operand.new("NULL", :null) if value.nil? && !strict
+
+          scalar_bind(value, build) || uncompilable(node)
+        end
+
+        def arithmetic_sql(node, build)
+          left, right = [node.left, node.right].map { |side| value_sql(side, build, strict: true) }
+          uncompilable(node) unless [left.type, right.type] == %i[integer integer]
+
+          sql = "(#{left.sql} #{ARITHMETIC.fetch(node.class)} #{right.sql})"
+          guard = integer_guard(sql)
+          build.guards << guard if guard
+          Operand.new(sql, :integer)
+        end
+
+        # A bound literal or argument, typed by the Ruby value it holds; nil for any other value.
+        def scalar_bind(value, build)
+          type = { Integer => :integer, Float => :float, String => :string }.find { |klass, _| value.is_a?(klass) }&.last
+          type && Operand.new(typed_placeholder(build.binds, value, type), type)
+        end
+
+        def field_read(field)
+          field.lifecycle? ? quote_ident(field.name) : scalar_read(field.name, field.member, field.type)
+        end
+
+        def uncompilable(node)
+          raise Uncompilable, "#{dialect_name} has no set-transform form for #{Naming.demodulise(node.class)}"
+        end
+      end
+    end
+  end
+end