hecks 0.2.0 → 1.0.0

data/lib/hecks/query_specification/common/dsl.rb

@@ -0,0 +1,58 @@
+require_relative "authorization_spec"
+require_relative "comparators"
+require_relative "cursor_spec"
+require_relative "inspection_spec"
+require_relative "limit_spec"
+require_relative "null_semantics"
+require_relative "offset_spec"
+require_relative "order_by"
+require_relative "where_clause"
+
+module Hecks
+  module QuerySpecification
+    module Common
+      module DSL
+        # RENAMED FROM `where`/`order_by`/`limit`/`offset`/`authorize`
+        # (all below) — item #13's full metaprogrammed dispatch (slice
+        # 4c). A SHARED mixin, same shape `attribute_impl` proved in
+        # slice 3: ONE renamed method each, both Query and ReadModel
+        # Keyword rows name it in `calls:`. `where`/`order_by` are
+        # bootstrap-reachable (every core chapter's own `read_model`
+        # filters its roster with them), so both are in
+        # BOOTSTRAP_CALLS_FALLBACK for the ReadModel context; `limit`/
+        # `offset`/`authorize` are not (checked directly).
+        def where_impl(clauses)
+          @wheres ||= []
+          clauses.each do |field, value|
+            op, operand = split_comparator(value)
+            @wheres << WhereClause.new(field: field, op: op, value: operand)
+          end
+        end
+
+        def order_by_impl(field, direction = :asc)
+          @order_by = OrderBy.new(field: field, direction: direction)
+        end
+
+        def limit_impl(value) = @limit = LimitSpec.new(value: value)
+        def offset_impl(value) = @offset = OffsetSpec.new(value: value)
+        def cursor(value) = @cursor = CursorSpec.new(value: value)
+        def authorize_impl(policy, tenant: nil) = @authorization = AuthorizationSpec.new(policy: policy, tenant: tenant)
+        def nulls(mode) = @null_semantics = NullSemantics.new(mode: mode)
+        def inspect_query(mode = :sql) = @inspection = InspectionSpec.new(mode: mode)
+
+        private
+
+        def split_comparator(value)
+          return [:eq, value] unless value.is_a?(Hash)
+
+          op, operand = value.first
+          unless value.size == 1 && COMPARATORS.include?(op.to_sym)
+            raise ArgumentError,
+                  "unknown comparator #{value.inspect} — expected one of #{COMPARATORS.join(', ')}"
+          end
+          [op.to_sym, operand]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/inspection_spec.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      InspectionSpec = Struct.new(:mode, keyword_init: true) do
+        def to_h = { mode: mode.to_s }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/limit_spec.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      LimitSpec = Struct.new(:value, keyword_init: true) do
+        def to_h = { value: QuerySpecification.render_value(value) }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/null_policy.rb

@@ -0,0 +1,92 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      module NullPolicy
+        module_function
+
+        # STABLE on purpose : rows arrive already in identity order from
+        # Ports::Query::Ordering, and that base is what makes a tie deterministic
+        # rather than store-dependent. A plain sort_by is not stable in Ruby, so
+        # equal keys would shuffle and the identity tier would be lost exactly
+        # where it is needed. Descending reverses both partitions, so a tie reads
+        # identity-descending too — the same total order sql_order renders as
+        # `field DESC, id DESC`.
+        def order(records, direction:, policy: nil, &key)
+          null_rows, valued_rows = records.partition { |record| key.call(record).nil? }
+          sorted = valued_rows.each_with_index.sort_by { |record, index| [key.call(record), index] }.map(&:first)
+          if direction.to_s == "desc"
+            sorted.reverse!
+            null_rows.reverse!
+          end
+          case policy&.mode.to_s
+          when "first" then null_rows + sorted
+          when "last" then sorted + null_rows
+          else direction.to_s == "desc" ? sorted + null_rows : null_rows + sorted
+          end
+        end
+
+        # M3 — an UNDECLARED (`native`) null policy used to render no
+        # `NULLS ...` clause at all here, leaving each dialect's own
+        # default to decide: Postgres puts nulls LAST on ASC (and FIRST
+        # on DESC), while `#order` above — this same "native" default,
+        # for Memory — puts nulls FIRST on ASC (and LAST on DESC), the
+        # SQLite convention. Same query, same data, different row order
+        # depending only on which adapter ran it. Rendered explicitly
+        # here instead, so an undeclared policy means the SAME total
+        # order everywhere rather than "whatever this store already does"
+        # — matching `#order`'s own default rather than the other way
+        # round, since that default is unconditional (Memory/Heki have no
+        # dialect to defer to) and SQLite already agrees with it natively.
+        def sql_order(expression, direction, policy)
+          direction = direction.to_s.downcase == "desc" ? "DESC" : "ASC"
+          nulls = case policy&.mode.to_s
+                  when "first" then " NULLS FIRST"
+                  when "last" then " NULLS LAST"
+                  else direction == "DESC" ? " NULLS LAST" : " NULLS FIRST"
+                  end
+          "#{expression} #{direction}#{nulls}, id #{direction}"
+        end
+
+        # THE COMPARATORS A NULL CANNOT SATISFY — the other half of
+        # `sql_predicate` below. That one answers "the value COMPARED TO is
+        # null" (`eq: nil` -> IS NULL, `ne: nil` -> IS NOT NULL, a real
+        # convention both adapters already shared). This one answers the
+        # case nothing covered: the ROW'S OWN value is null and the value
+        # compared to is not.
+        #
+        # SQL says unknown. `NULL <> 'red'` is NULL, not true, so the row
+        # is not returned. Ruby says `nil != "red"` is true, so it is. The
+        # two adapters therefore answered the SAME query on the SAME data
+        # differently — Memory returning a row SQLite omitted — which is
+        # not a difference of opinion a caller can plan around.
+        #
+        # Resolved toward SQL, and not because SQL is the store: an absent
+        # or null field is UNKNOWN, not a value, and a comparison against
+        # unknown is unknown rather than true. Making SQL match Ruby
+        # instead would mean compiling every `ne:` to
+        # `(col <> $1 OR col IS NULL)` — more to get right in two
+        # dialects, and a reliable way to lose an index — to make a real
+        # query engine agree with an in-memory one.
+        #
+        # `none_in_state` is deliberately NOT here: it is a 9th, vendored
+        # comparator whose `held` is a reference id, and a row holding no
+        # reference is genuinely "not in that state" rather than unknown.
+        NULL_UNMATCHABLE = %w[eq ne lt lte gt gte in contains].freeze
+
+        def unmatchable?(operation, held, want)
+          held.nil? && !want.nil? && NULL_UNMATCHABLE.include?(operation.to_s)
+        end
+
+        def sql_predicate(expression, operation, value)
+          if value.nil? && operation.to_s == "eq"
+            ["#{expression} IS NULL", []]
+          elsif value.nil? && operation.to_s == "ne"
+            ["#{expression} IS NOT NULL", []]
+          else
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/null_semantics.rb

@@ -0,0 +1,11 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      NullSemantics = Struct.new(:mode, keyword_init: true) do
+        def to_h = { mode: mode.to_s }
+
+        def self.default = new(mode: :native)
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/offset_spec.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      OffsetSpec = Struct.new(:value, keyword_init: true) do
+        def to_h = { value: QuerySpecification.render_value(value) }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/options.rb

@@ -0,0 +1,32 @@
+require_relative "null_semantics"
+
+module Hecks
+  module QuerySpecification
+    module Common
+      class Options
+        attr_reader :wheres, :order_by, :limit, :offset, :cursor,
+                    :authorization, :null_semantics, :inspection
+
+        def initialize(wheres: [], order_by: nil, limit: nil, offset: nil, cursor: nil,
+                       authorization: nil,
+                       inspection: nil, null_semantics: NullSemantics.default)
+          @wheres, @order_by, @limit, @offset, @cursor = wheres, order_by, limit, offset, cursor
+          @authorization, @null_semantics, @inspection = authorization, null_semantics, inspection
+        end
+
+        def options_to_h
+          { wheres: @wheres.map(&:to_h), order_by: @order_by&.to_h, limit: @limit&.to_h,
+            offset: @offset&.to_h, cursor: @cursor&.to_h, authorization: @authorization&.to_h,
+            null_semantics: @null_semantics&.to_h, inspection: @inspection&.to_h }
+        end
+
+        def extra_options_to_h
+          options_to_h.reject { |key, value|
+            value.nil? || value == [] || (key == :null_semantics && value == { mode: "native" })
+          }
+                      .reject { |key, _| %i[wheres order_by limit].include?(key) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/order_by.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      OrderBy = Struct.new(:field, :direction, keyword_init: true) do
+        def to_h = { field: field.to_s, direction: direction.to_s }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/specification.rb

@@ -0,0 +1,10 @@
+require_relative "comparators"
+require_relative "where_clause"
+require_relative "order_by"
+require_relative "limit_spec"
+require_relative "offset_spec"
+require_relative "cursor_spec"
+require_relative "authorization_spec"
+require_relative "null_semantics"
+require_relative "inspection_spec"
+require_relative "options"

data/lib/hecks/query_specification/common/where_clause.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      WhereClause = Struct.new(:field, :op, :value, keyword_init: true) do
+        def to_h = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/field_path.rb

@@ -0,0 +1,107 @@
+module Hecks
+  module QuerySpecification
+    # ONE reading of a dotted query-field path, shared by every place that
+    # used to invent its own. The reference interpreter did a bare
+    # `record[field]` lookup (a dotted path silently matched nothing), the
+    # SQL side split dots but judged numericness from the FIRST nested
+    # segment only (a two-level path quietly compared text), and the build
+    # seal walked the declaration graph a third way. Three
+    # implementations of "what does pizza.price_cents.cents mean" is two
+    # more than a language gets to have.
+    #
+    # Two sides, deliberately in one file so they cannot drift:
+    #
+    #   dig(holder, field)        — VALUE side: walk a record's held state,
+    #                               segment by segment, through Value
+    #                               objects and plain hashes alike.
+    #   leaf_attribute / numeric? — DECLARATION side: walk the declared
+    #                               shape to the attribute a path lands on.
+    #                               Callers supply value-object lookup as a
+    #                               block, because an Aggregate and a
+    #                               mid-build AggregateBuilder hold their
+    #                               shapes differently but walk the same.
+    module FieldPath
+      module_function
+
+      NUMERIC_PRIMITIVES = %w[Integer Float].freeze
+      SCALAR_PRIMITIVES  = %w[String Integer Float TrueClass FalseClass].freeze
+
+      # The held value a dotted field names, or nil — never a raise. The
+      # first segment reads off the record (an Instance, a Value, or a
+      # plain row hash); the rest read through whatever each step holds. A
+      # stored nested value object is a plain hash by the time it is read
+      # back, keyed by symbol in memory and by string off a wire decode,
+      # so both spellings are tried — `key?` first, never `||`, because
+      # `||` falls through a genuinely-stored `false` to the OTHER
+      # spelling (usually absent) and returns `nil` instead. The seal
+      # admits boolean leaves (`SCALAR_PRIMITIVES` below), so a `false`
+      # here is a real, held answer, not a missing one.
+      def dig(holder, field)
+        return nil if field.nil?
+
+        field.to_s.split(".").reduce(holder) { |current, segment| read(current, segment) }
+      end
+
+      def read(current, segment)
+        return nil if current.nil?
+
+        if current.is_a?(Hash)
+          sym = segment.to_sym
+          return current.key?(sym) ? current[sym] : current[segment]
+        end
+
+        # M5 — "or nil, never raise" is this method's whole contract, and
+        # an Array broke it: `Array#[]` demands an Integer index, so
+        # `current[segment]` (a String) raised `TypeError` straight
+        # through `dig` instead of answering nil. A dotted path stepping
+        # INTO a list_of attribute (`where "tags.name" == "x"` against a
+        # bare list, rather than each element) has no single member a
+        # bare index would name anyway — nil is the honest answer, the
+        # same one a dangling reference or a missing key already gets.
+        return nil if current.is_a?(Array)
+
+        current[segment]
+      end
+
+      # The declared attribute a path lands on, or nil. `segments` is the
+      # dotted tail — for a bare field it is empty and the root attribute
+      # is its own leaf. The walk stops dead at a reference (an id is a
+      # scalar; nothing nests under it) and at any member the declared
+      # value object does not carry.
+      def leaf_attribute(attribute, segments)
+        current = attribute
+        segments.each do |segment|
+          return nil if current.nil? || current.reference?
+
+          shape = yield(current.type.to_s)
+          current = shape&.attributes&.find { |member| member.name.to_s == segment }
+        end
+        current
+      end
+
+      # May an ordered comparator (lt/lte/gt/gte) land here, and may an
+      # ORDER BY cast here numerically? A bare field keeps the one-level
+      # convention every adapter already implements: a numeric primitive,
+      # or a value object carrying at least one numeric member. A dotted
+      # path must land on a numeric primitive itself — the convention does
+      # not reach through a named path, it IS the absence of one.
+      def numeric?(attribute, segments, &value_object)
+        leaf = leaf_attribute(attribute, segments, &value_object)
+        return false if leaf.nil? || leaf.list? || leaf.reference?
+        return true if NUMERIC_PRIMITIVES.include?(leaf.type.to_s)
+        return false unless segments.empty?
+
+        shape = yield(leaf.type.to_s)
+        !shape.nil? && shape.attributes.any? { |member| NUMERIC_PRIMITIVES.include?(member.type.to_s) }
+      end
+
+      # A dotted path must end on a SCALAR member — landing on a value
+      # object would hand SQL a JSON object where the reference
+      # interpreter unwraps a hash, and the two would answer differently.
+      def scalar_leaf?(attribute, segments, &value_object)
+        leaf = leaf_attribute(attribute, segments, &value_object)
+        !leaf.nil? && !leaf.list? && !leaf.reference? && SCALAR_PRIMITIVES.include?(leaf.type.to_s)
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/hop_path.rb

@@ -0,0 +1,132 @@
+require_relative "../naming"
+
+module Hecks
+  module QuerySpecification
+    # ONE reading of a dotted query-field path that hops THROUGH a
+    # reference into another aggregate's own shape — FieldPath's
+    # sibling, not its member. FieldPath walks a SHAPE, which cannot
+    # loop, and answers nil, never raising, because there is nothing
+    # left to say beyond "not found." HopPath walks the REFERENCE
+    # GRAPH instead — `BluebookBuilder#validate_no_bidirectional_references!`
+    # refuses any reference CYCLE at declaration time (ADR 0025,
+    # "References" — widened from a direct pair to any ring, DFS over
+    # the chapter's own reference graph), so what's left to guard here
+    # is depth, not cycles: MAX_HOPS below, and this module's own
+    # `refusal` states for a target the chapter doesn't resolve. A walk
+    # here still needs to say WHY it stopped, not just that it did.
+    #
+    # Every method below takes an ATTRIBUTE ARRAY, never a "shape"
+    # object — deliberately, because the two real callers hold their
+    # attributes differently. `AggregateBuilder` (tier-1 seal, mid-
+    # build) exposes `attributes` as a plain reader, but its own
+    # `attribute(name, type = String, ...)` is the DSL's attribute-
+    # DECLARING method — calling it as a finder would silently mint a
+    # new String attribute instead of looking one up. A sealed
+    # `Aggregate` (tier-2 seal, and every runtime target) has a
+    # real `attribute(name)` finder, but taking the array either way
+    # sidesteps the mismatch instead of asking every caller to know
+    # which kind of object it holds.
+    module HopPath
+      module_function
+
+      Hop = Struct.new(:attribute, :target_name, :target, keyword_init: true)
+
+      # refusal: nil (clean), :unresolvable (a hop's target cannot be
+      # found — cross-domain, or simply not declared in this chapter),
+      # :too_deep (see MAX_HOPS below).
+      Plan = Struct.new(:hops, :tail, :refusal, keyword_init: true)
+
+      # A hop chain long enough to matter is long enough to be a
+      # mistake — NOT a guard against a walk that cannot terminate.
+      # Nothing here loops forever regardless of how the reference
+      # graph is shaped: a hop chain is a literal dotted string, fixed
+      # at declaration time, and every step consumes exactly one of
+      # its own segments — the walk is bounded by what was TYPED, not
+      # by the graph. A self-referential aggregate hopping through
+      # itself more than once (`"parent.parent.name"`, a grandparent
+      # query) is real, common, and perfectly safe; this exists only
+      # to refuse a chain nobody meant to write this long.
+      MAX_HOPS = 8
+
+      # The segment name a Reference answers to in a hop path — its own
+      # declared attribute name, unchanged (ADR 0025, "References":
+      # `reference_to` mints that bare name now, no `_id`, so there is
+      # no derivation left to apply). `proposal/client` (a query hop)
+      # and `proposal.client` (the Ruby accessor,
+      # `Facade::Handle#define_reference_accessors`) name the same
+      # concept the same way.
+      def hop_name(attribute) = attribute.name.to_s
+
+      # Does this path's HEAD cross into another record via `/`? THE
+      # OPERATOR IS THE ANSWER NOW, not a name collision to arbitrate —
+      # `.` walks fields inside this record, `/` crosses into another
+      # one, so a path with no `/` is never a hop, full stop, and the
+      # OLD "a real local attribute wins first" rule (needed only
+      # because `.` was overloaded for both meanings, and `client_id`
+      # vs `client` was how the two were told apart) has nothing left
+      # to arbitrate. Answerable from `attributes` alone — a Reference
+      # knows its own `target_name` at declaration, before it can
+      # `resolve` it — which is what lets the AGGREGATE seal recognise
+      # a hop it cannot yet check.
+      def hop_head?(field, attributes)
+        head, rest = field.to_s.split("/", 2)
+        return false unless rest
+
+        attributes.any? { |candidate| candidate.reference? && hop_name(candidate) == head }
+      end
+
+      # ONE STEP: does `field`'s head hop through one of `attributes`'
+      # own references? Answers the resolved `Hop` plus the string
+      # still left to walk (itself possibly another `/`-hop, against
+      # the TARGET's own attributes, or a plain `.`-dotted field walk
+      # once the hops run out) — or nil, when the head names nothing or
+      # the path has no `/` at all. This is the one primitive
+      # Runtime::ReferenceHop needs: it recurses hop by hop through its
+      # own `apply`, one ordinary same-aggregate query at a time, and
+      # never needs the whole chain resolved up front the way a seal
+      # does.
+      def next_hop(field, attributes)
+        head, rest = field.to_s.split("/", 2)
+        return nil unless rest
+
+        attribute = attributes.find { |candidate| candidate.reference? && hop_name(candidate) == head }
+        return nil unless attribute
+
+        hop = Hop.new(attribute: attribute, target_name: attribute.type.target_name, target: attribute.type.resolve)
+        [hop, rest]
+      end
+
+      # The WHOLE chain, resolved — every hop's target found, in
+      # order — for the one caller that needs it all at once:
+      # BluebookBuilder#validate_query_hops!, checking a hop chain
+      # before anything ever dispatches it.
+      def plan(field, attributes)
+        hops = []
+        remaining = field.to_s
+        current = attributes
+
+        loop do
+          step = next_hop(remaining, current)
+          break unless step
+
+          hop, rest = step
+          return Plan.new(hops: hops, tail: nil, refusal: :too_deep) if hops.size >= MAX_HOPS
+
+          # Pushed even unresolved — a caller reporting :unresolvable
+          # needs THIS hop's own target_name (real, known at
+          # declaration, regardless of whether resolve succeeded), not
+          # whatever hop came before it. `.target` is nil on this one
+          # entry; every caller checking `hops.last.target` already has
+          # to handle that, the same way `next_hop`'s own caller does.
+          hops << hop
+          return Plan.new(hops: hops, tail: nil, refusal: :unresolvable) unless hop.target
+
+          current = hop.target.attributes
+          remaining = rest
+        end
+
+        Plan.new(hops: hops, tail: remaining, refusal: nil)
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/read_model/specification.rb

@@ -0,0 +1,18 @@
+require_relative "../common/options"
+
+module Hecks
+  module QuerySpecification
+    module ReadModel
+      class Specification < Common::Options
+        attr_reader :joins
+
+        def initialize(joins: [], **options)
+          super(**options)
+          @joins = joins
+        end
+
+        def to_h = options_to_h.merge(joins: @joins)
+      end
+    end
+  end
+end

data/lib/hecks/query_specification.rb

@@ -0,0 +1,14 @@
+module Hecks
+  # The declarative shape of an ask — what a query says, held apart from
+  # any engine that answers it. `common/` is the vocabulary every ask
+  # shares; `read_model/` the read-model-specific specification.
+  module QuerySpecification
+  end
+end
+
+require_relative "query_specification/common/specification"
+require_relative "query_specification/common/null_policy"
+require_relative "query_specification/common/dsl"
+require_relative "query_specification/field_path"
+require_relative "query_specification/hop_path"
+require_relative "query_specification/read_model/specification"

data/lib/hecks/rendering.rb

@@ -0,0 +1,48 @@
+require "json"
+
+module Hecks
+  # HOW A VALUE READS INSIDE A REFUSAL, in one place, because a refusal is an
+  # ANSWER and its wording is contract — pinned byte-for-byte by the corpus.
+  #
+  # `inspect` and JSON agree on scalars and disagree on everything composite :
+  # a hash is `{"cents"=>100}` against `{"cents":100}`, an array is `["a", "b"]`
+  # against `["a","b"]`. Each such spelling is invisible until a composite
+  # actually reaches a message, which is why both known cases were found by
+  # something deliberately passing the wrong shape rather than by review — the
+  # first by hand in spec/corpus/banking.json, the second by bin/fuzz, at a
+  # different site, after the first was patched where it was found.
+  #
+  # So it lives here rather than in whichever file noticed it, and the house style
+  # is JSON because that is what every other refusal in the corpus already prints.
+  module Rendering
+    module_function
+
+    def describe(value)
+      case value
+      when nil then "nil"
+      when Hash, Array then JSON.generate(value)
+      else
+        # A Hecks::Runtime::Value reaching a refusal message (an
+        # arithmetic op's own `amount`/`current`, an Admissibility
+        # `current`, ...) had no case here, falling straight through to
+        # Ruby's own #inspect and leaking a raw object pointer
+        # ("#<Hecks::Runtime::Value:0x...>") into an otherwise
+        # correct domain refusal. Duck-typed on `respond_to?(:to_h)`
+        # rather than naming `Runtime::Value` directly — `Runtime::Value`
+        # itself requires THIS file (`runtime/value.rb`'s own
+        # `require_relative "../rendering"`), so naming it here would be
+        # circular. A single-field wrapper (the overwhelming common case
+        # — an amount, an id, a lifecycle field) unwraps to its bare
+        # scalar, described recursively; a genuinely multi-field value
+        # renders as its fields' JSON, same as a bare Hash already does
+        # two lines up.
+        if value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
+          fields = value.to_h
+          fields.size == 1 ? describe(fields.values.first) : JSON.generate(fields)
+        else
+          value.inspect
+        end
+      end
+    end
+  end
+end