hecks 2.7.0 → 2.9.0

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

@@ -6,28 +6,10 @@ require_relative "../../runtime/value"
 
 module Hecks
   module Adapters
-    # The one SQL query compilation, shared by the SQLite and Postgres
-    # adapters — one walk rather than a near-line-identical copy per
-    # adapter, because copies can only drift. Every declared operator
-    # compiles fully into SQL or the query refuses loudly; the null-policy
-    # predicate, the comma-separated `in` convention, and the identity
-    # ORDER BY fallback are spelled once, here.
-    #
-    # What a dialect actually differs on is narrow, and each adapter
-    # supplies exactly those hooks:
-    #
-    #   placeholder(binds, value)     — "?" or "$N", recording the bind
-    #   contains_clause(expr, ph)     — instr() or position(), for a scalar field
-    #   list_contains_clause(name, member, ph) — real element containment,
-    #                                  for a `list_of` field (json_each /
-    #                                  jsonb_array_elements)
-    #   empty_in_clause               — "0" or "FALSE"
-    #   comparable_expression(e, v)   — ::numeric cast, where the dialect casts
-    #   plain_column(name)            — a real column or a jsonb path
-    #   nested_expression(name, path, member) — json_extract or state #>>
-    #   order_clause(order_by, policy)
-    #   execute_query(sql, binds)     — run it, return instances
-    #   dialect_name                  — for the refusal message
+    # The SQL query compilation shared by the SQLite and Postgres adapters. Each dialect
+    # supplies hooks: placeholder, contains_clause, list_contains_clause, empty_in_clause,
+    # comparable_expression, plain_column, nested_expression, order_clause, execute_query
+    # and dialect_name.
     module SqlQueryBuilder
       COMPARATORS = {
         "eq" => "=", "ne" => "<>", "gt" => ">", "gte" => ">=", "lt" => "<", "lte" => "<="
@@ -52,11 +34,7 @@ module Hecks
         sql << " WHERE #{clauses.join(' AND ')}" unless clauses.empty?
         sql << order_by_sql(declared)
         sql << " LIMIT #{placeholder(binds, query_value(declared.limit.value, args).to_i)}" if declared.limit
-        # An offset with no declared limit — SQLite refuses a bare OFFSET
-        # outright (LIMIT -1 is its unbounded idiom) while Postgres accepts
-        # one, so the dialect supplies its own unbounded spelling. Found by
-        # the adapter-agreement gate on its first run, not by either
-        # adapter's own spec: each was self-consistent, they just disagreed.
+        # SQLite refuses a bare OFFSET, so the dialect spells its own unbounded limit.
         sql << unbounded_limit if !declared.limit && declared.offset
         sql << " OFFSET #{placeholder(binds, query_value(declared.offset.value, args).to_i)}" if declared.offset
         execute_query(sql, binds)
@@ -64,12 +42,7 @@ module Hecks
 
       private
 
-      # Every declared `where` clause, compiled in declaration order — a
-      # null-policy predicate short-circuits the ordinary comparator path
-      # per clause, same as it did inline. `binds` is populated in place
-      # (the same array `query` goes on to push LIMIT/OFFSET placeholders
-      # into afterward), so pulling this loop out changes nothing about
-      # bind-parameter order.
+      # `binds` is filled in place so LIMIT/OFFSET placeholders follow the where binds.
       def where_clauses(declared, args, binds)
         declared.wheres.each_with_object([]) do |clause, clauses|
           value = query_value(clause.value, args)
@@ -103,71 +76,26 @@ module Hecks
           members = in_members(value)
           return empty_in_clause if members.empty?
 
-          # **Both sides as text**. `in` is a textual reading everywhere else
-          # — Ports::Query::InMemory#holds? compares `held.to_s` against
-          # stringified members, and `in_members` above stringifies its
-          # own — so a numeric field was the one shape where the engines
-          # could not agree: `in_members` binds '100', while the column
-          # expression yields the number 100, and `100 IN ('100','300')`
-          # is false in SQLite (a json_extract result carries no column
-          # affinity to coerce it) where Memory matched. Casting the
-          # expression rather than typing the members keeps one rule for
-          # every field: no type inference, and `in` means the same thing
-          # on a String, an Integer, and a value-object member.
-          #
-          # `eq`/`gt`/`lt` never had this problem because they bind the
-          # value's own type and route through `comparable_expression`,
-          # which Postgres overrides to cast numerics.
+          # `in` reads as text everywhere: casting the column keeps a numeric field
+          # matching the stringified members (SQLite's json_extract carries no affinity).
           "CAST(#{expression} AS TEXT) IN (#{members.map { |member| placeholder(binds, member) }.join(', ')})"
         else
           raise ArgumentError, "#{dialect_name} query adapter does not support #{oper.inspect}"
         end
       end
 
-      # A real array already says where its members end. Splitting one on
-      # commas re-reads a boundary it already drew — and an id is a
-      # domain value (Naming::IDENTITY_JOIN joins a composite identity's
-      # own parts, and the parts it joins are whatever an identity path
-      # pulled out of real data), so a name carrying a comma would
-      # silently become two members matching the wrong rows, or nothing.
-      # Calling `value.to_s` unconditionally would mean only a
-      # comma-joined string ever works here, while
-      # Ports::Query::InMemory and QueryInterpreter's own `members`
-      # handle a real Array — three implementations of `in`,
-      # two readings of it. Narrower than those two on one point,
-      # deliberately: they unwrap a value-object/Hash element to its
-      # own scalar first (`comparable`) before stringifying, a rule
-      # this doesn't reproduce — every real caller of `in` today, and
-      # the cross-aggregate hop this exists for, passes plain scalar
-      # ids, never a value-object element.
+      # A real array is not re-split on commas: an id is a domain value and may hold one.
+      # Unlike the other engines, a Hash or value-object element is not unwrapped.
       def in_members(value)
         return value.map(&:to_s).reject(&:empty?) if value.is_a?(Array)
 
         value.to_s.split(",").map(&:strip).reject(&:empty?)
       end
 
-      # Every declared field compiles into an expression over the stored
-      # shape — or the query never runs. The member-picking rules are the
-      # same in both dialects: a value-object field compares through the
-      # member the bound value (or the declared types) say is numeric,
-      # falling back to the one-field convention `value`.
-      #
-      # A reference is an ID, stored as a bare scalar (never wrapped —
-      # `Runtime::Value.refuse_object_reference` guarantees it), so it
-      # takes the same plain-column path as any other non-value-object
-      # attribute. Excluding it into the value-object member-picking logic
-      # compiles a nested read against a row that has no nested key — a
-      # path that can never match. Measured, not assumed: a `where` on a
-      # has_one/belongs_to/reference_to field returned zero rows against
-      # real data until that exclusion was removed.
-      # `member` resolves through two ordered fallback tiers — the bound
-      # value's own numeric field first, then the declared value object's
-      # numeric-or-sole attribute — each documented above as fixing a
-      # real, measured bug (a reference field matching nothing, a
-      # single-attribute VO silently falling to the wrong convention).
-      # Splitting the tiers apart would separate two writes to the same
-      # `member` local across method boundaries, hiding the fallback
-      # order that makes them correct together.
+      # Compiles a declared field into an expression over the stored shape. A value-object
+      # field compares through its numeric member, else its sole attribute, else `value`.
+      # A reference is a bare id, so it takes the plain-column path.
+      # The two member fallbacks stay in one method so their order is visible.
       # rubocop:disable-next Metrics/CyclomaticComplexity
       # rubocop:disable-next Metrics/PerceivedComplexity
       def query_expression(field, value: nil)
@@ -180,40 +108,20 @@ module Hecks
         member = if path.empty? && value
                    hash = value.is_a?(Runtime::Value) ? value.to_h : value
                    numeric = hash.is_a?(Hash) && hash.find { |_key, item| item.is_a?(Numeric) }
-                   # Not &.-able: `numeric` can be `false` (hash.is_a?(Hash) came
-                   # back false) as well as nil (.find came back empty) — `&.`
-                   # only guards nil, so `false.first` raises. False positive.
+                   # `numeric` can be false, which `&.` does not guard.
                    # rubocop:disable-next Style/SafeNavigation
                    numeric ? numeric.first : nil
                  end
         member ||= if path.empty? && attribute && value_object?(attribute)
                      object = Runtime::Value.value_object_for(@aggregate, attribute.type)
-                     # A sole attribute is the fallback when no member is
-                     # numeric — a single-attribute value object is its one
-                     # field whatever that field is named (`Behaviour::
-                     # ValueObject#sole_attribute`, the same strict rule
-                     # `Runtime::Value`'s own `.value` alias enforces), so
-                     # `EmailAddress{address}` compiles to `$.address`
-                     # rather than falling through to the dialects' own
-                     # `member || "value"` convention and silently matching
-                     # nothing. Multi-field non-numeric shapes still fall
-                     # through to that convention, unchanged — there is no
-                     # single field to honestly pick for them here either.
+                     # A single-attribute value object is its one field, whatever it is named.
                      (Forms::ValueObjectShape.numeric_member(object) || object.sole_attribute)&.name
                    end
         nested_expression(name, path, member)
       end
 
-      # A numeric member wins if the value object has one (Price, Money —
-      # what every ordered comparison in the corpus until now compared),
-      # otherwise the same single-field fallback `query_expression`'s own
-      # `nested_expression(name, path, member || "value")` already
-      # makes for the column side — a plain `attribute :value, String`
-      # value object (IdentityId, RoleName, ...) has no numeric member at
-      # all, and returning nil there silently turned an equality
-      # comparison into `IS NULL`, matching nothing. Both sides of one
-      # comparison have to agree on which field they mean, or they
-      # compare two different things and call it a where clause.
+      # Picks the same member `query_expression` does, so both sides of a comparison
+      # agree on which field they mean.
       def query_value(value, args)
         value = args[value] if value.is_a?(Symbol)
         hash = value.is_a?(Runtime::Value) ? value.to_h : value
@@ -233,17 +141,9 @@ module Hecks
         !attr.list? && !Runtime::Value.value_object_for(@aggregate, attr.type).nil?
       end
 
-      # `contains` on a `list_of` field means real element membership, not
-      # a substring search over the column's raw JSON text — the reading
-      # QueryInterpreter#holds? and Ports::Query::InMemory already give a
-      # real Array, and a substring search would disagree with it (a
-      # substring match over `[{"value":"not_high_risk"}]` falsely matches
-      # "high_risk"). Returns nil for a non-list field (the caller falls
-      # back to `contains_clause`, unchanged), "" for a list of bare
-      # scalars (no member to walk into), or the one field name a
-      # single-field value-object element carries. A list of a
-      # multi-field value object has no one scalar to compare against and
-      # is refused rather than guessed.
+      # `contains` on a list means element membership, not a substring search over JSON text.
+      # Returns nil for a non-list field, "" for bare scalars, else the sole member name.
+      # Raises for a multi-field value object.
       def list_member(field)
         return nil if field.to_s.include?(".")
 

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

@@ -16,18 +16,9 @@ module Hecks
           fields << { name: lifecycle.field, attribute: nil, sql_type: "TEXT" } if lifecycle && fields.none? do |field|
             field[:name] == lifecycle.field
           end
-          # `projects` fields (S12, ADR 0025) are a local column too —
-          # `CommandInterpreter#seed_projected_fields`/`RebuildSweep`
-          # both write one straight into `Instance#state` the same as
-          # any other field, so a column has to exist to hold it or
-          # `save`'s own `columns =`/`values =` build (this file, not
-          # here) silently drops it on every write. No `attribute` of
-          # their own to carry (`ProjectedField` is a bare name/
-          # reference/remote_field triple, not a typed attribute) —
-          # treated as a raw scalar, same as the lifecycle field just
-          # above: every real corpus use projects a status/lifecycle
-          # string, and `encode_field`/`decode` both already pass a
-          # `attribute: nil` field through untouched, not JSON-encoded.
+          # `projects` fields are written straight into `Instance#state`, so they need a column
+          # or `project` drops them. They carry no attribute and are stored as raw scalars,
+          # like the lifecycle field.
           @aggregate.projected_fields.each do |field|
             next if fields.any? { |f| f[:name] == field.name }
 
@@ -37,13 +28,8 @@ module Hecks
         end
 
         def encode(attr, value)
-          # **Never set is not empty**. `then_set ... append:` starts a list at `[]`
-          # the moment the first element lands, but a list attribute nothing has
-          # ever appended to — the shape every other aggregate in the corpus
-          # happened not to carry, until one declared a list-typed head
-          # attribute that no creating command populates by default — has to
-          # stay NULL to answer the same as Memory does. Forcing it to `[]`
-          # here is how a persistence topology invented data no dispatch wrote.
+          # A list nothing has appended to stays NULL, as under Memory; forcing `[]` would
+          # invent data no dispatch wrote.
           return (value.nil? ? nil : state_json(value)) if attr.list?
           return state_json(value) if value.is_a?(Hash) || value.is_a?(Runtime::Value)
 
@@ -56,14 +42,8 @@ module Hecks
           encode(field[:attribute], value)
         end
 
-        # Every JSON column's text goes through the state codec's `encode`
-        # (PR A3) — string keys at every depth, Values materialized.
         def state_json(value) = JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, value))
 
-        # The row's columns reassembled into the stored state, then decoded
-        # once through the state codec (PR A3) — the same deep, IR-driven
-        # key spelling every other adapter's read now produces, instead of
-        # this codec's own `symbolize_names:` walk.
         def decode(row)
           state = persisted_fields.each_with_object({}) do |field, raw_state|
             attr = field[:attribute]
@@ -79,27 +59,15 @@ module Hecks
               if attr.list? || value_object?(attr)
                 raw ? JSON.parse(raw) : nil
               else
-                # A reference lands here now, with the ordinary scalars. It holds
-                # the id of a head, which is text — `JSON.parse("acct-1")` raises,
-                # so reading it as JSON was only ever survivable while the column
-                # held an object.
+                # A reference holds a head's id, which is text and would fail JSON.parse.
                 raw
               end
           end
           Ports::Persistence::StateCodec.decode(@aggregate, state)
         end
 
-        # A NULL `projects` column is a field never seeded, not a stored
-        # NIL — so it reads back absent, the way Heki/PostgresEra (one blob
-        # holding only what was written) already answer it. A column holds
-        # every persisted field whether or not the record ever had one, so
-        # NULL is the only spelling "never set" has here; and nothing ever
-        # stores a nil projected value to confuse it with —
-        # `CommandInterpreter#seed_projected_fields` and
-        # `RebuildSweep#refresh` both skip a nil remote value. Absent is also
-        # what `RebuildSweep#refresh`'s `record.key?` and
-        # `Registry#projection_current?`'s row comparison expect. The
-        # lifecycle field (the other `attribute: nil` column) keeps its NULL.
+        # 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.projected_fields.any? { |projected| projected.name.to_sym == field[:name].to_sym }

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

@@ -13,9 +13,7 @@ require_relative "../sqlite"
 module Hecks
   module Adapters
     # Rebuilds a read store from the authoritative journal, entry by entry.
-    # A value object is written as its JSON object and a reference as the
-    # bare id it holds — the same shapes the command path writes, so there
-    # is no second representation to accept here any more.
+    # Values are written as JSON, references as bare ids — the shapes the command path writes.
     class SqliteProjection < Sqlite
       # Replaces or deletes the read store's row for one journal entry, encoding the entry's
       # state directly rather than through a `Runtime::Instance`.
@@ -36,68 +34,31 @@ module Hecks
         entry
       end
 
-      # Execute a declared read model against the projected aggregate-head
-      # tables. The report shape is assembled from SQL-selected rows, rather
-      # than scanning repositories and matching references in Ruby.
+      # Executes a declared read model against the projected read-store tables.
       #
-      # M19 (docs/audits/2026-08-10-main-bug-audit.md,
-      # docs/audits/2026-08-11-bug-triage.md) — this agrees with
-      # `Runtime::ReadModelInterpreter#project` (the in-process path) on
-      # the two counts where a native path can most easily diverge:
+      # A missing root raises, matching the in-process interpreter; a head
+      # matches against any already-projected source, not only the root.
       #
-      # **Missing root**: the in-process path's own `fetch` refuses with
-      # `NotFound` when the reference argument names no record, and so
-      # does this. Answering a silent `{root: nil, ...}` instead would
-      # make this the one path where a caller could dispatch a read model
-      # against a record that never existed and get back something that
-      # looks like an empty report rather than the refusal every other
-      # path gives.
-      #
-      # **Chained-include join scope**: matching a non-root head against
-      # the root's own id alone, regardless of what it actually
-      # references, is correct for a head that references the root
-      # directly and silently empty for one that references another
-      # included head instead (`Leaf` -> `Mid` -> `Root`, `Leaf` itself
-      # has no attribute referencing `Root` at all, so its `references`
-      # would always be `[]`). The in-process path
-      # (`ReadModelInterpreter#project`'s "root first, always" comment)
-      # matches a head against any already-projected source, not
-      # only the root — `select_related` does the same: each head is
-      # matched against every source resolved so far (root first, then
-      # declared order — the same one-level-of-declaration-order
-      # dependency the in-process path itself has, documented
-      # there as L2, not a gap introduced here).
-      #
-      # @param _domain [String, Symbol] name of the domain declaring the read model; not read
-      # @param model [Bluebook::ReadModel, Runtime::TenantScope::Scoped] the read model to
-      #   answer, or the tenant-scoping delegator around one; must have a reference target
-      # @param args [Hash{Symbol => Object}] the read model's arguments; the entry under
-      #   `model.reference_name` is the root record's id
-      # @param bluebook [Bluebook::Chapter, nil] the domain's bluebook, which resolves each
-      #   included aggregate by name; nil is refused
-      # @return [Array<Hash>] a one-element Array holding the report Hash, keyed by each
-      #   head's `as` name: an Array of plain state Hashes (each with `:id`) for a `many`
-      #   head, otherwise one such Hash, or nil when that head matched no row
-      # @raise [ArgumentError] if `bluebook` is nil
-      # @raise [KeyError] if `args` has no entry for the model's reference argument
-      # @raise [Runtime::NotFound] if no projected row has the referenced root id
-      # @raise [SQLite3::Exception] if a statement fails
+      # @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
 
-        # The reference's own shape, read the same way ReadModelInterpreter
-        # reads it — not the identity unwrap, which is gone : an identity is
-        # declared as a path and followed.
+        # 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 can be
-        # eligible in the same read model now.
+        # each name a different many-side head, so more than one may be
+        # eligible in the same read model.
         eligible = model.filtered_head_names
 
-        # **Root first, always** — see this method's own header. Mirrors
-        # `ReadModelInterpreter#project`'s identical partition, for the
-        # identical reason: a later head's own join has to be able to
-        # match against a root (or another head) already resolved.
+        # Root first, always (see this method's own header): a later head's
+        # join must match against a root or head already resolved.
         root_heads, other_heads = model.aggregate_heads.partition { |head| head[:aggregate] == model.reference_target }
         projected = []
         reports = {}
@@ -130,12 +91,8 @@ module Hecks
         row && projected_instance(aggregate, row)
       end
 
-      # Matched against every source already projected (root first, then
-      # declared order — see this class's own `query_read_model` header),
-      # not only the root — a head whose own reference points at another
-      # included head rather than the root directly would otherwise match
-      # nothing at all, since its reference attribute would be compared
-      # against a target (the root) it never names.
+      # 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 do |source|
           references = aggregate.attributes.select do |attribute|
@@ -150,10 +107,7 @@ module Hecks
         end
         return [] if matches.empty?
 
-        # A reference column holds the ID, so it compares as itself. The
-        # `json_extract(col,'$.value') = ? OR col = ?` this replaced was
-        # reading both shapes because both existed — one written by the
-        # command path, one by older journals. There is one shape now.
+        # A reference column holds the id, so it compares directly against itself.
         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)
@@ -168,37 +122,27 @@ module Hecks
         decode_fields(fields_for(aggregate), aggregate, row)
       end
 
-      # The field list a row decodes against: every declared attribute,
-      # plus the lifecycle field and any `projects` fields not already
-      # among them (both read back raw — see `decode_fields`).
+      # 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] }
         if (lifecycle = aggregate.lifecycle) && fields.none? { |name, _| name == lifecycle.field }
           fields << [lifecycle.field, nil]
         end
-        # `projects` fields (S12, ADR 0025) need reading back too — `project`
-        # (above) already writes one into its own column via `persisted_fields`
-        # (`Codec#persisted_fields`, this class's own superclass module), but
-        # this method built its own independent field list that never
-        # consulted it — a column `project` populated correctly, silently
-        # dropped on every read back out. Same raw-passthrough treatment as
-        # the lifecycle field just above: `attribute: nil` down in the loop.
+        # `projects` fields (ADR 0025) read back raw too — see `persisted_fields`.
         aggregate.projected_fields.each do |field|
           fields << [field.name, nil] unless fields.any? { |name, _| name == field.name }
         end
         fields
       end
 
-      # Decoded through the state codec (PR A3) against the row's own
-      # aggregate — see Codec#decode, including why a NULL projected-only
-      # column reads back absent.
+      # 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]
           # rubocop:disable Lint/DuplicateBranch -- the nil-attribute and
-          # reference-id branches both just answer `raw`, coincidentally, for
-          # two unrelated reasons (see each branch's own comment); merging
-          # them would blur that distinction.
+          # reference-id branches both just answer `raw`, for unrelated reasons.
           next if attribute.nil? && raw.nil? && aggregate.lifecycle&.field&.to_sym != name.to_sym
 
           raw_state[name] =