hecks 5.0.0 → 7.0.0

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

@@ -0,0 +1,81 @@
+require_relative "set_transform/expressions"
+require_relative "set_transform/assignments"
+require_relative "../../ports/persistence/append_only"
+
+module Hecks
+  module Adapters
+    # A SQL store's `set_transform` (ADR 0129): one update statement, filtered by the query and the
+    # givens and returning every row it changed, for a {Ports::Persistence::SetStatement},
+    # journalled row by row in the same transaction. Mixed into an adapter that includes
+    # {SqlQueryBuilder}, whose filter clauses it reuses, and a
+    # set dialect that supplies the SQL spellings: `typed_placeholder`, `null_safe_equality`,
+    # `text_ordering`, `integer_guard`, `scalar_read`, `scalar_write`, `version_bump`,
+    # `run_set_transform` and `set_transform_dialect`.
+    module SetTransform
+      # Raised when the store refused the statement (an overflow, a lost connection) after it was
+      # sent; the transaction it ran in is rolled back.
+      class Declined < StandardError; end
+
+      include Expressions
+      include Assignments
+
+      # Compiles a statement to SQL without running it.
+      #
+      # @param statement [Ports::Persistence::SetStatement] the command over the query
+      # @return [Array(String, Array)] the update statement and its binds in placeholder order
+      # @raise [SetTransform::Uncompilable] if part of the statement has no form in this dialect
+      def compile_set_transform(statement)
+        build = Build.new([], [], statement.arguments || {})
+        sets, conditions = set_list(statement, build)
+        clauses = where_list(statement, build, conditions)
+        sql = "UPDATE #{quoted_table} SET #{sets.join(", ")}"
+        sql << " WHERE #{clauses.join(" AND ")}" unless clauses.empty?
+        ["#{sql} RETURNING *", build.binds]
+      end
+
+      # Runs a statement and journals every row it updated, inside one transaction (joining an
+      # open one).
+      #
+      # @param statement [Ports::Persistence::SetStatement] the command over the query
+      # @return [Array<Runtime::Instance>] each updated row as it now stands, in no set order
+      # @raise [SetTransform::Uncompilable] before anything is written
+      # @raise [SetTransform::Declined] if the store refused the statement
+      def apply_set_transform(statement)
+        sql, binds = compile_set_transform(statement)
+        transaction do
+          instances = run_set_transform(sql, binds)
+          journal_set(instances)
+          instances
+        end
+      end
+
+      private
+
+      # The query's clauses, the lifecycle's conditions, the givens, then every guard compiling
+      # them collected.
+      def where_list(statement, build, conditions)
+        wheres = query_conditions(statement, build) + conditions +
+                 statement.givens.map { |node| predicate_sql(node, build) }
+        wheres + build.guards.uniq
+      end
+
+      def query_conditions(statement, build)
+        query = statement.query
+        if query.wheres.any? { |clause| SqlQueryBuilder::IN_MEMORY_OPERATORS.include?(clause.op.to_s) } ||
+           query.limit || query.offset
+          raise Uncompilable, "#{dialect_name} cannot rewrite the rows of a paged or partly in-memory query"
+        end
+
+        where_clauses(query, statement.query_args || {}, build.binds)
+      end
+
+      # One journal entry per row, then the checkpoint once, as a row-by-row save would leave it.
+      def journal_set(instances)
+        entries = instances.map do |instance|
+          append(Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup))
+        end
+        advance_checkpoint!(entries.map(&:sequence).max) unless entries.empty?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+require_relative "../../ports/query/cursor"
+
+module Hecks
+  module Adapters
+    # The keyset predicate of a cursor query, compiled for the SQL dialects: the rows that follow
+    # a position `(value, id)` in the query's own `ORDER BY`.
+    #
+    # `Ports::Query::Cursor` states the same rule over Ruby rows, so the two answer alike. Mixed
+    # into {SqlQueryBuilder}; the dialect supplies `placeholder`, `query_expression`,
+    # `comparable_expression` and, when it orders through its own expression, `order_expression`.
+    module SqlKeyset
+      private
+
+      # The wheres, then the cursor's keyset when the ask carries a position.
+      def restricting_clauses(declared, args, binds)
+        where_clauses(declared, args, binds) + [keyset_clause(declared, args, binds)].compact
+      end
+
+      # @param declared [QuerySpecification::Common::Options] a query that may declare `cursor`
+      # @param args [Hash] the ask's arguments; `:after` carries the token
+      # @param binds [Array] filled in place, after the binds already there
+      # @return [String, nil] the predicate, nil when the query has no cursor or no token
+      def keyset_clause(declared, args, binds)
+        position = declared.cursor && Ports::Query::Cursor.decode(args[:after])
+        return unless position
+        return "id > #{placeholder(binds, position.id)}" unless declared.order_by
+
+        keyset_over_field(declared, position, binds)
+      end
+
+      def keyset_over_field(declared, position, binds)
+        order_by = declared.order_by
+        expression = keyset_expression(order_by.field, position.value)
+        beyond = order_by.direction.to_s.downcase == "desc" ? "<" : ">"
+        first = Ports::Query::Cursor.nulls_first?(order_by.direction, declared.null_semantics)
+        return keyset_after_null(expression, beyond, first, position, binds) if position.value.nil?
+
+        keyset_after_value(expression, beyond, first, position, binds)
+      end
+
+      # Rows that follow a null-keyed row: later nulls by id, and every valued row when nulls lead.
+      def keyset_after_null(expression, beyond, nulls_first, position, binds)
+        tied = "(#{expression} IS NULL AND id #{beyond} #{placeholder(binds, position.id)})"
+        nulls_first ? "(#{tied} OR #{expression} IS NOT NULL)" : tied
+      end
+
+      # Rows that follow a valued row: later values, equal values with a later id, and the nulls
+      # when they trail.
+      def keyset_after_value(expression, beyond, nulls_first, position, binds)
+        later = "#{expression} #{beyond} #{placeholder(binds, position.value)}"
+        tied = "(#{expression} = #{placeholder(binds, position.value)} AND id #{beyond} #{placeholder(binds, position.id)})"
+        nulls_first ? "(#{later} OR #{tied})" : "(#{later} OR #{tied} OR #{expression} IS NULL)"
+      end
+
+      def keyset_expression(field, value)
+        expression = respond_to?(:order_expression, true) ? order_expression(field) : query_expression(field, value: value)
+        comparable_expression(expression, value)
+      end
+    end
+  end
+end

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

@@ -1,8 +1,11 @@
 require_relative "../../forms/value_object_shape"
+require_relative "../../ports/query/in_memory"
 require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/field_path"
 require_relative "../../runtime/errors"
+require_relative "../../text"
 require_relative "../../runtime/value"
+require_relative "sql_keyset"
 require_relative "sql_value_members"
 
 module Hecks
@@ -13,27 +16,36 @@ module Hecks
     # and dialect_name.
     module SqlQueryBuilder
       include SqlValueMembers
+      include SqlKeyset
 
       COMPARATORS = {
         "eq" => "=", "ne" => "<>", "gt" => ">", "gte" => ">=", "lt" => "<", "lte" => "<="
       }.freeze
 
+      # The operators answered from this store's records in Ruby, not compiled. `none_in_state`
+      # reads another aggregate's records through the registry, which one SQL statement over this
+      # aggregate's table cannot reach. Any other operator this builder cannot compile refuses.
+      IN_MEMORY_OPERATORS = %w[none_in_state].freeze
+
       # Compiles a declared query into one SQL statement and runs it through the dialect's
-      # own `execute_query`, so filtering, ordering and paging all happen in the database.
+      # own `execute_query`, so filtering, ordering and paging all happen in the database. A
+      # query with a where clause in `IN_MEMORY_OPERATORS` is answered over `all` instead.
       #
       # @param declared [QuerySpecification::Common::Options] the declared query: its
       #   `wheres`, `order_by`, `limit` and `offset` are compiled; nothing else is read
       # @param args [Hash{Symbol => Object}] values for the specification's symbolic operands
-      # @param context [Hash] execution context from `Ports::Query.execute`; accepted for the
-      #   port's call shape and not read
-      # @return [Array<Runtime::Instance>] the matching records in declared order, then by
-      #   id; `[]` when none match
+      # @param context [Hash] execution context from `Ports::Query.execute`; its `:registry` is
+      #   read only for a query answered over `all`
+      # @return [Array<Runtime::Instance>] the matches in declared order, then by id; `[]` if none
       # @raise [ArgumentError] if a where clause uses an operator this builder cannot compile,
       #   or `contains` targets a list of a value object with more than one field
       def query(declared, args = {}, context: {})
+        Runtime::Value.check_query_arguments!(@aggregate, declared, args)
+        return in_memory_answer(declared, args, context) if in_memory?(declared)
+
         sql = "SELECT #{select_list} FROM #{from_relation}"
         binds = []
-        clauses = where_clauses(declared, args, binds)
+        clauses = restricting_clauses(declared, args, binds)
         sql << " WHERE #{clauses.join(" AND ")}" unless clauses.empty?
         sql << order_by_sql(declared)
         sql << paging_sql(declared, args, binds)
@@ -42,6 +54,12 @@ module Hecks
 
       private
 
+      def in_memory?(declared) = declared.wheres.any? { |clause| IN_MEMORY_OPERATORS.include?(clause.op.to_s) }
+
+      def in_memory_answer(declared, args, context)
+        Ports::Query::InMemory.execute(all, declared, args, registry: context[:registry])
+      end
+
       # The LIMIT and OFFSET text, with their placeholders bound after the where binds.
       def paging_sql(declared, args, binds)
         sql = +""
@@ -109,7 +127,7 @@ module Hecks
       def in_members(value)
         return value.map(&:to_s).reject(&:empty?) if value.is_a?(Array)
 
-        value.to_s.split(",").map(&:strip).reject(&:empty?)
+        Text.comma_list(value)
       end
 
       # Compiles a declared field into an expression over the stored shape. A value-object
@@ -126,7 +144,7 @@ module Hecks
 
       # Whether a bare field name reads as one plain column: the lifecycle field, or a scalar.
       def plain_field?(name, attribute)
-        @aggregate.lifecycle&.field.to_s == name || (attribute && !value_object?(attribute))
+        @aggregate.lifecycle_field.to_s == name || (attribute && !value_object?(attribute))
       end
 
       def value_object?(attr)
@@ -144,7 +162,9 @@ module Hecks
 
         object = Runtime::Value.value_object_for(@aggregate, attribute.type)
         return "" unless object
-        return object.sole_attribute.name.to_s if object.sole_attribute
+
+        sole = object.sole_attribute
+        return sole.name.to_s if sole
 
         raise ArgumentError,
               "#{dialect_name} query adapter cannot compile contains on #{field} — " \

data/lib/hecks/adapters/driven/sqlite/codec.rb

@@ -72,7 +72,7 @@ module Hecks
         # A NULL `projects` column means never seeded, so it reads back absent as under Heki and
         # PostgresEra; nothing stores a nil projected value. The lifecycle field keeps its NULL.
         def projected_only?(field)
-          @aggregate.lifecycle&.field&.to_sym != field[:name].to_sym &&
+          @aggregate.lifecycle_field&.to_sym != field[:name].to_sym &&
             @aggregate.projected_fields.any? { |projected| projected.name.to_sym == field[:name].to_sym }
         end
       end

data/lib/hecks/adapters/driven/sqlite/ddl.rb

@@ -56,6 +56,13 @@ module Hecks
           )
         SQL
 
+        DISPATCH_CLAIMS = <<~SQL.freeze
+          CREATE TABLE IF NOT EXISTS hecks_dispatch_claims (
+            claim_key   TEXT PRIMARY KEY,
+            claimed_at  TEXT NOT NULL
+          )
+        SQL
+
         CHECKPOINTS = <<~SQL.freeze
           CREATE TABLE IF NOT EXISTS hecks_checkpoints (
             aggregate_table TEXT PRIMARY KEY,

data/lib/hecks/adapters/driven/sqlite/dialect.rb

@@ -10,9 +10,10 @@ module Hecks
         def dialect_name = "SQLite"
         def empty_in_clause = "0"
 
+        # Numbered, so a statement may place its binds' text in any order (ADR 0129).
         def placeholder(binds, value)
           binds << value
-          "?"
+          "?#{binds.size}"
         end
 
         def contains_clause(expression, placeholder)

data/lib/hecks/adapters/driven/sqlite/dispatch_claims.rb

@@ -0,0 +1,28 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # Saga dispatches already applied, one row per dispatch key in the aggregate's own database
+      # file so a claim joins the save's transaction. See `Runtime::DispatchClaim`.
+      module DispatchClaims
+        # Whether the dispatch with this key has been applied.
+        #
+        # @param key [String] the dispatch key a saga leg stamped on the command
+        # @return [Boolean] true once `dispatch_claim` has accepted the key
+        def dispatch_applied?(key)
+          !@db.get_first_row("SELECT 1 FROM hecks_dispatch_claims WHERE claim_key = ?", [key]).nil?
+        end
+
+        # Records that the dispatch with this key is being applied, refusing a second claim.
+        #
+        # @param key [String] the dispatch key a saga leg stamped on the command
+        # @return [Boolean] true when the key was new and is now held; false when already held
+        # @raise [SQLite3::Exception] if the insert fails
+        def dispatch_claim(key)
+          @db.execute("INSERT OR IGNORE INTO hecks_dispatch_claims (claim_key, claimed_at) VALUES (?, ?)",
+                      [key, Time.now.utc.iso8601])
+          @db.changes.positive?
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/sqlite/journal.rb

@@ -92,8 +92,54 @@ module Hecks
           removed
         end
 
+        # Reads the chain heads the ledger sealed beside this journal, oldest first.
+        #
+        # @return [Array<Hash>] `through:` the highest sequence a seal covers, `head:` the chain
+        #   digest at that point and `previous:` the head the seal followed (genesis digest first)
+        # @raise [SQLite3::Exception] if a statement fails
+        def ledger_anchors
+          ensure_ledger_anchors!
+          @db.execute(
+            "SELECT through_sequence, head, previous FROM hecks_ledger_anchors " \
+            "WHERE aggregate_table = ? ORDER BY through_sequence", [table]
+          ).map { |row| { through: row["through_sequence"].to_i, head: row["head"], previous: row["previous"] } }
+        end
+
+        # Seals a chain head beside this journal. Sealing the same point twice with the same head
+        # changes nothing; a different head for a sealed point is refused, never overwritten.
+        #
+        # @param through [Integer] the highest journal sequence the head covers
+        # @param head [String] the chain digest at `through`
+        # @param previous [String] the head of the seal before this one
+        # @return [void]
+        # @raise [Runtime::WiringError] if the point is already sealed with another head
+        # @raise [SQLite3::Exception] if a statement fails
+        def record_ledger_anchor(through:, head:, previous:)
+          ensure_ledger_anchors!
+          sealed = ledger_anchors.find { |anchor| anchor[:through] == through }
+          if sealed
+            return if sealed[:head] == head
+
+            raise Runtime::WiringError, "#{table} is already sealed through #{through} with another head: the journal changed"
+          end
+
+          @db.execute(
+            "INSERT INTO hecks_ledger_anchors (aggregate_table, through_sequence, head, previous) " \
+            "VALUES (?, ?, ?, ?)", [table, through, head, previous]
+          )
+        end
+
         private
 
+        def ensure_ledger_anchors!
+          @db.execute(
+            "CREATE TABLE IF NOT EXISTS hecks_ledger_anchors (" \
+            "aggregate_table TEXT NOT NULL, through_sequence INTEGER NOT NULL, head TEXT NOT NULL, " \
+            "previous TEXT NOT NULL, sealed_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, " \
+            "PRIMARY KEY (aggregate_table, through_sequence))"
+          )
+        end
+
         # Shared decode step for `entries`/`entries_since` — runs a query already selecting
         # `aggregate_id, operation, state, mirrors, sequence` and builds one Entry per row.
         def entries_matching(sql, binds = [])

data/lib/hecks/adapters/driven/sqlite/name_guard.rb

@@ -0,0 +1,25 @@
+require_relative "../../../ports/persistence/stored_name_guard"
+
+module Hecks
+  module Adapters
+    class Sqlite
+      # Reads how many rows a table holds before any table is created, for the stored-name guard.
+      module NameGuard
+        private
+
+        def refuse_orphaned_rows!
+          Ports::Persistence::StoredNameGuard.check!(@aggregate, row_count: method(:rows_under))
+        end
+
+        def rows_under(name)
+          [name, "#{name}_entries"].sum { |table| table_rows(table) }
+        end
+
+        def table_rows(table)
+          exists = @db.get_first_value("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", [table])
+          exists ? @db.get_first_value("SELECT COUNT(*) FROM #{quote_ident(table)}").to_i : 0
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/sqlite/outbox.rb

@@ -30,7 +30,7 @@ module Hecks
         # @return [Boolean] true when the row was pending and is now claimed; false when it is
         #   unknown or another claimer got there first
         # @raise [SQLite3::Exception] if the update fails
-        def outbox_claim(id) # rubocop:disable Naming/PredicateMethod -- the outbox port's verb
+        def outbox_claim(id)
           @db.execute(
             "UPDATE hecks_outbox SET status = 'claimed', attempts = attempts + 1, claimed_at = ? " \
             "WHERE id = ? AND status = 'pending'",
@@ -48,7 +48,7 @@ module Hecks
         # @param error [String, nil] the failure description, or nil to store NULL
         # @return [Boolean] true when exactly one row was updated; false when no row has `id`
         # @raise [SQLite3::Exception] if the update fails
-        def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod -- the outbox port's verb
+        def outbox_settle(id, status:, error: nil)
           @db.execute(
             "UPDATE hecks_outbox SET status = ?, error = ?, settled_at = ? WHERE id = ?",
             [status.to_s, error, Time.now.utc.iso8601, id]
@@ -64,7 +64,8 @@ module Hecks
         #   keys; `[]` when none match
         # @raise [SQLite3::Exception] if the statement fails
         def outbox_rows(status: nil)
-          sql   = "SELECT * FROM hecks_outbox WHERE aggregate = ?"
+          sql   = "SELECT *, CAST(strftime('%s', 'now') AS INTEGER) - CAST(strftime('%s', claimed_at) AS INTEGER) " \
+                  "AS claimed_for FROM hecks_outbox WHERE aggregate = ?"
           binds = [table]
           if status
             sql << " AND status = ?"
@@ -89,7 +90,7 @@ module Hecks
             id: row["id"], delivery_id: row["delivery_id"], event_uid: row["event_uid"], aggregate: row["aggregate"],
             domain: row["domain"], kind: row["kind"], consumer: row["consumer"],
             event: JSON.parse(row["event"], symbolize_names: true), status: row["status"],
-            attempts: row["attempts"].to_i, error: row["error"]
+            attempts: row["attempts"].to_i, error: row["error"], claimed_for: row["claimed_for"]&.to_f
           )
         end
       end

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

@@ -1,9 +1,5 @@
-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 "json"
+require_relative "../projection/read_model_walk"
 
 # The subclass needs its parent — and sqlite.rb requires this file at
 # its bottom, after class Sqlite is defined, so the require cycle this
@@ -15,8 +11,7 @@ module Hecks
     # Rebuilds a read store from the authoritative journal, entry by entry.
     # Values are written as JSON, references as bare ids — the shapes the command path writes.
     class SqliteProjection < Sqlite
-      # The state of one `query_read_model` call, threaded through its per-head steps.
-      ReadModelRun = Struct.new(:model, :args, :bluebook, :reference_id, :eligible, :projected)
+      include Projection::ReadModelWalk
 
       # Replaces or deletes the read store's row for one journal entry, encoding the entry's
       # state directly rather than through a `Runtime::Instance`.
@@ -33,147 +28,26 @@ module Hecks
         entry
       end
 
-      # 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::Chapter, 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)
-        return select_related(aggregate, run.projected) unless head[:aggregate] == run.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 row_values(entry)
         [entry.id.to_s] + persisted_fields.map { |field| encode_field(field, entry.state[field[:name]]) }
       end
 
-      def select_projected(aggregate, id)
-        row = @db.get_first_row("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE id = ?", [id.to_s])
-        row && projected_instance(aggregate, row)
+      def projected_row(aggregate, id)
+        @db.get_first_row("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE id = ?", [id])
       end
 
-      # Matches every already-projected source, not just the root, so a head
-      # referencing another included head still matches.
-      def select_related(aggregate, projected)
-        matches = projected.flat_map { |source| reference_matches(aggregate, source) }
-        return [] if matches.empty?
-
-        # A reference column holds the id, so it compares directly against itself.
+      # A reference column holds the id, so it compares directly against itself.
+      def related_rows(aggregate, matches)
         clauses = matches.map { |attribute, _id| "#{quote_ident(attribute.name)} = ?" }
         bind = matches.map { |_attribute, id| id }
         @db.execute("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE #{clauses.join(" OR ")} ORDER BY id", bind)
-           .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.reference? && attribute.type.target_name == source[:aggregate].to_s
-        end
-        return [] if references.empty?
-
-        ids = source[:rows].map { |row| row.id.to_s }
-        references.product(ids)
-      end
-
-      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 — see `persisted_fields`.
-        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 —
-      # see Codec#decode for why 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
 
+      # A reference is a scalar id (see Codec#decode); a list or value object is JSON.
       def decode_column(aggregate, attribute, raw)
-        return raw if attribute.nil?
-        # A reference is a scalar id — see Codec#decode.
-        return raw unless attribute.list? || !aggregate.value_object(attribute.type).nil?
+        return raw if attribute.nil? || !json_column?(aggregate, attribute)
 
         raw ? JSON.parse(raw) : nil
       end

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

@@ -97,7 +97,7 @@ module Hecks
         # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
         # @return [Boolean] always true
         # @raise [SQLite3::Exception] if either statement fails
-        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)
           project(entry)
@@ -110,7 +110,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