hecks 0.2.0 → 1.0.0

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/differ.rb

@@ -0,0 +1,183 @@
+require_relative "../../storage_shape"
+
+module Hecks
+  module Translation
+    module Scaffold
+      # Diff two eras' storage-shape projections into the edge's
+      # declarations — confident rules by unique signature pairing,
+      # everything ambiguous left unresolved for a human.
+      module Differ
+        # Diff two bluebook IRs into the edge's declarations.
+        def diff(held_bluebook, current_bluebook)
+          held_shapes = projections(held_bluebook)
+          current_shapes = projections(current_bluebook)
+
+          matched = match_aggregates(held_shapes, current_shapes)
+          aggregates = current_bluebook.aggregates.filter_map do |aggregate|
+            held_name = matched[:pairs][aggregate.name]
+            next unless held_name
+
+            rules = attribute_rules(held_shapes[held_name], current_shapes[aggregate.name])
+            was = held_name == aggregate.name ? nil : held_name
+            next if rules.empty? && was.nil?
+
+            ScaffoldedAggregate.new(name: aggregate.name, was: was, rules: rules)
+          end
+
+          { aggregates: aggregates, retired: matched[:retired], unclaimed: matched[:unclaimed] }
+        end
+
+        def projections(bluebook)
+          Runtime::StorageShape.project(bluebook)["aggregates"].to_h { |shape| [shape["name"], shape] }
+        end
+
+        # A vanished aggregate whose full shape reappears under exactly one
+        # new name was renamed. `retired` is only confident when NOTHING
+        # remains it could plausibly have become — a vanished aggregate
+        # beside an unmatched new one might be a rename-plus-reshape, and
+        # writing `retired` there would be a guess that strands data.
+        # Anything ambiguous stays unclaimed, and the coverage gate names
+        # it until a human decides.
+        def match_aggregates(held_shapes, current_shapes)
+          pairs = {}
+          current_shapes.each_key { |name| pairs[name] = held_shapes.key?(name) ? name : nil }
+
+          vanished = held_shapes.keys - current_shapes.keys
+          appeared = current_shapes.keys.select { |name| pairs[name].nil? }
+          unclaimed = []
+          vanished.each do |old_name|
+            old_shape = held_shapes[old_name].merge("name" => nil)
+            candidates = appeared.select { |name| current_shapes[name].merge("name" => nil) == old_shape }
+            if candidates.size == 1
+              pairs[candidates.first] = old_name
+              appeared -= candidates
+            else
+              unclaimed << old_name
+            end
+          end
+
+          retired = appeared.empty? ? unclaimed : []
+          { pairs: pairs, retired: retired, unclaimed: retired.empty? ? unclaimed : [] }
+        end
+
+        # Every changed path in one aggregate, resolved into rules by
+        # signature matching over the FULL path set — top-level names and
+        # dotted members alike. Unique signature pair: a rename (both
+        # top-level) or a move (any dotted end). Same path, same members,
+        # new type name: a retype. Anything else: unresolved, carrying its
+        # type-compatible candidates (an empty list is the arrow toward
+        # compute, or drop).
+        def attribute_rules(held_shape, current_shape)
+          rules = []
+          rules << identity_hint(held_shape, current_shape)
+          rules.compact!
+          held_attrs = (held_shape["attributes"] || []).to_h { |attribute| [attribute["name"], attribute] }
+          current_attrs = (current_shape["attributes"] || []).to_h { |attribute| [attribute["name"], attribute] }
+
+          # retype pass: same attribute name, same member structure, the
+          # TYPE's own name changed
+          (held_attrs.keys & current_attrs.keys).each do |name|
+            held = held_attrs[name]
+            current = current_attrs[name]
+            next if held == current
+            next unless container?(held) && container?(current)
+            next unless held["type"]["members"] == current["type"]["members"] && held["list"] == current["list"]
+
+            rules << { kind: :retype, from: held["type"]["type"], to: current["type"]["type"] }
+          end
+          retyped = rules.filter_map { |rule| rule[:from] if rule[:kind] == :retype }
+
+          vanished = vanished_paths(held_attrs, current_attrs, retyped)
+          appeared = appeared_paths(held_attrs, current_attrs, retyped)
+
+          vanished.each do |path, signature|
+            matches = appeared.select { |_, candidate| candidate == signature }.keys
+            taken = rules.filter_map { |rule| rule[:to] if %i[rename move].include?(rule[:kind]) }
+            matches -= taken
+            if matches.size == 1 && vanished.count { |_, other| other == signature } == 1
+              target = matches.first
+              kind = path.include?(".") || target.include?(".") ? :move : :rename
+              rules << { kind: kind, from: path, to: target }
+            else
+              candidates = matches.empty? ? compatible_candidates(appeared, signature) : matches
+              rules << { kind: :unresolved, from: path, candidates: candidates }
+            end
+          end
+          rules
+        end
+
+        # Held paths that need explaining: whole attributes that vanished,
+        # and members that vanished (or changed type) inside a kept
+        # attribute — mirroring exactly what EraGuard will demand coverage
+        # for.
+        def vanished_paths(held_attrs, current_attrs, retyped)
+          paths = {}
+          held_attrs.each do |name, held|
+            next if retyped.include?(container?(held) ? held["type"]["type"] : nil)
+
+            current = current_attrs[name]
+            if current.nil?
+              paths[name] = held["type"]
+              next
+            end
+            next if held == current
+
+            held_members = members_of(held)
+            current_members = members_of(current)
+            held_members.each do |member, signature|
+              paths["#{name}.#{member}"] = signature if current_members[member] != signature
+            end
+          end
+          paths
+        end
+
+        def appeared_paths(held_attrs, current_attrs, retyped)
+          paths = {}
+          current_attrs.each do |name, current|
+            next if retyped.include?(container?(current) ? current["type"]["type"] : nil)
+
+            held = held_attrs[name]
+            if held.nil?
+              paths[name] = current["type"]
+              next
+            end
+            next if held == current
+
+            held_members = members_of(held)
+            members_of(current).each do |member, signature|
+              paths["#{name}.#{member}"] = signature if held_members[member] != signature
+            end
+          end
+          paths
+        end
+
+        # THE ONE THING `attribute_rules` COULD NOT SEE BEFORE — the shape
+        # projection already carries `"identity"` (`StorageShape
+        # .project_aggregate`), it was simply never read here. An
+        # unresolved placeholder, not a guess: `coverage_check.rb`'s own
+        # `check_identity_unchanged!` is the real gate this only hints
+        # toward, the same "tool proactively guides you" pattern the
+        # generic unresolved message already gives unfed fields.
+        def identity_hint(held_shape, current_shape)
+          return if held_shape["identity"] == current_shape["identity"]
+
+          { kind: :unresolved, from: :identity, candidates: [] }
+        end
+
+        def compatible_candidates(appeared, signature)
+          appeared.select { |_, candidate| scalar_of(candidate) == scalar_of(signature) }.keys
+        end
+
+        def scalar_of(signature) = signature.is_a?(Hash) ? signature["members"] : signature
+
+        def members_of(attribute)
+          return {} unless container?(attribute)
+
+          attribute["type"]["members"].to_h { |member| [member["name"], member["type"]] }
+        end
+
+        def container?(attribute) = attribute["type"].is_a?(Hash)
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/renderer.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Translation
+    module Scaffold
+      # Render an edge into .bluebook text — confident rules inline,
+      # ambiguities as parse-refusing `unresolved` constructs, never
+      # comments, so an unresolved file can only boot into a refusal.
+      module Renderer
+        def render(edge)
+          lines = ["Hecks.data_translation #{edge.domain.inspect}, from: #{edge.from.inspect}, to: #{edge.to.inspect} do"]
+          edge.aggregates.each do |aggregate|
+            header = "  aggregate #{aggregate.name.inspect}"
+            header += ", was: #{aggregate.was.inspect}" if aggregate.was
+            if aggregate.rules.empty?
+              lines << "#{header} do"
+            else
+              lines << "#{header} do"
+              aggregate.rules.each { |rule| lines << "    #{render_rule(rule)}" }
+            end
+            lines << "  end"
+          end
+          edge.retired.each { |name| lines << "  retired #{name.inspect}" }
+          lines << "end"
+          "#{lines.join("\n")}\n"
+        end
+
+        def render_rule(rule)
+          case rule[:kind]
+          when :rename then "rename :#{rule[:from]}, to: :#{rule[:to]}"
+          when :move then "move #{rule[:from].inspect}, to: #{rule[:to].inspect}"
+          when :retype then "retype #{rule[:from].inspect}, to: #{rule[:to].inspect}"
+          when :unresolved
+            candidates = rule[:candidates].map { |candidate| render_path(candidate) }.join(", ")
+            "unresolved #{render_path(rule[:from])}, candidates: [#{candidates}]"
+          end
+        end
+
+        def render_path(path) = path.to_s.include?(".") ? path.to_s.inspect : ":#{path}"
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/writer.rb

@@ -0,0 +1,28 @@
+require "fileutils"
+
+module Hecks
+  module Translation
+    module Scaffold
+      # Put the rendered edge on disk, regenerating in place when a file
+      # for the same shape pair already exists.
+      module Writer
+        # The edge file, regenerated in place when one for the same shape
+        # pair already exists (matched textually — an unresolved file
+        # cannot be LOADED to ask, that being the whole point of
+        # unresolved).
+        def write!(directory, edge)
+          translations_dir = File.join(directory, "translations")
+          FileUtils.mkdir_p(translations_dir)
+
+          existing = Dir[File.join(translations_dir, "*.bluebook")].find do |path|
+            text = File.read(path)
+            text.include?("from: #{edge.from.inspect}") && text.include?("to: #{edge.to.inspect}")
+          end
+          path = existing || File.join(translations_dir, "#{edge.ordinal}-#{edge.label}.bluebook")
+          File.write(path, render(edge))
+          path
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold.rb

@@ -0,0 +1,30 @@
+require_relative "scaffold/differ"
+require_relative "scaffold/renderer"
+require_relative "scaffold/writer"
+
+module Hecks
+  module Translation
+    # The scaffold writes translations; humans resolve ambiguity. It
+    # diffs the held era's storage-shape projection against the current
+    # one (scaffold/differ.rb) and WRITES the edge file
+    # (scaffold/renderer.rb, scaffold/writer.rb): confident rules inline
+    # (unique signature pairs → rename/move, aggregate renames → `was:`,
+    # type renames with identical members → retype, aggregates gone
+    # without a successor → retired), ambiguities as parse-refusing
+    # `unresolved` constructs — never comments, so an unresolved file can
+    # only boot into a refusal, never a guess. It NEVER proposes a
+    # `compute` (a computation takes domain judgment no mechanical diff
+    # can infer) — an empty-candidate `unresolved` is what points the
+    # author there. It never proposes a `drop` either: data loss is a
+    # decision, not a default. Re-running regenerates the file, matched
+    # by shape pair.
+    module Scaffold
+      Edge = Struct.new(:domain, :from, :to, :ordinal, :label, :aggregates, :retired, keyword_init: true)
+      ScaffoldedAggregate = Struct.new(:name, :was, :rules, keyword_init: true)
+
+      extend Differ
+      extend Renderer
+      extend Writer
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation.rb

@@ -0,0 +1,11 @@
+module Hecks
+  # The era-translation toolchain: scaffold drafts a translation from two
+  # eras' shapes, audit judges a written one, reattest re-seals it.
+  module Translation
+  end
+end
+
+require_relative "translation/rule_compiler"
+require_relative "translation/scaffold"
+require_relative "translation/audit"
+require_relative "translation/reattest"

data/lib/hecks/ports/persistence/plugins/era.rb

@@ -0,0 +1,48 @@
+require_relative "../plugin"
+require_relative "era/era_check"
+require_relative "era/era_guard"
+require_relative "era/era_tamper"
+require_relative "era/storage_shape"
+require_relative "era/lineage"
+require_relative "era/postgres_era"
+require_relative "era/translation"
+
+module Hecks
+  module Ports
+    module Persistence
+      module Plugins
+        # ADR 0033 — requiring THIS FILE is installing the plugin. Nothing in
+        # Hecks core requires it; an app that binds `PostgresEra`, or wants
+        # schema-translation support at all, requires it explicitly — the
+        # same shape every adapter-specific spec fixture already uses to
+        # load one particular `.adapter` file rather than all of them.
+        module Era
+          module_function
+
+          # `Runtime::Loader.run_boot_gates!` asks every loaded persistence
+          # plugin to contribute here, generically — it never mentions
+          # `EraCheck` or "era" by name. Two gates, both `:pre_verify`:
+          #
+          # `:era_compute_rules` — unconditional, whenever this plugin is
+          # loaded at all. A `compute`/`rekey` rule requires Postgres
+          # whatever adapter is actually bound (ADR 0031's own reasoning,
+          # unchanged) — this is the rich, adapter-aware version of that
+          # check; `Runtime::Loader`'s own structural backstop (plain
+          # `Bluebook::Translation` data, no plugin-specific class) only
+          # ever fires when NO persistence plugin is loaded at all.
+          #
+          # `:era_check` — conditional, exactly ADR 0031's own gate,
+          # unchanged: registered only when this registry has an aggregate
+          # actually bound to a lineage-capable adapter.
+          def contribute_boot_gates(registry, gates)
+            gates.register(:era_compute_rules, ->(reg, _dir) { Runtime::EraCheck.check_compute_rules_for_registry!(reg) }, phase: :pre_verify)
+            gates.register(:era_check, Runtime::EraCheck.method(:check_lineage!), phase: :pre_verify) if
+              Runtime::EraCheck.lineage_capable_registry?(registry)
+          end
+        end
+      end
+    end
+  end
+end
+
+Hecks::Ports::Persistence.register_plugin(:era, Hecks::Ports::Persistence::Plugins::Era)

data/lib/hecks/ports/persistence/remote_runtime.rb

@@ -0,0 +1,42 @@
+require_relative "../../runtime/registry"
+
+module Hecks
+  module Ports
+    module Persistence
+      # THE OTHER SHAPE AN ADAPTER CAN BE. `AppendOnly` names one shape
+      # already — something that stores bytes, locally (Postgres, SQLite,
+      # Heki) or over the network (D1), doesn't matter, the point is it
+      # does real local interpretation and has real entries to replay.
+      # This names the second, different shape: not "storage reached
+      # remotely," but the real INTERPRETER itself living behind a call
+      # boundary — `append`/`project` don't do partial local work and
+      # then fail, they raise unconditionally, because there is no local
+      # write-ahead log to have; `entries` is always `[]` for the same
+      # reason (`AppendOnly#recover!` replaying zero entries here is a
+      # correct no-op, not a lie).
+      #
+      # `Adapters::Lambda` is the first adapter to `include` this, not
+      # the only one meant to — any future adapter for some other
+      # remote-runtime target (a different compute platform, a gRPC
+      # stub, whatever) gets this shape for free by including one module
+      # instead of re-deriving the same raise-on-write/always-empty-
+      # entries boilerplate from scratch. And because it's a real,
+      # checkable module rather than an adapter's own ad hoc
+      # implementation, a caller can ask "is this adapter a remote-
+      # runtime delegate?" as a genuine capability check
+      # (`registry.adapter_class(name) <= RemoteRuntime`,
+      # `Runtime::RemoteDispatcher`'s own use) instead of comparing
+      # adapter names by string.
+      module RemoteRuntime
+        def append(*)
+          raise Runtime::WiringError,
+                "#{self.class.name} is a remote-runtime delegate — dispatch through " \
+                "Runtime::RemoteDispatcher instead of writing through the repository directly"
+        end
+        alias_method :project, :append
+
+        def entries = []
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/repository_factory.rb

@@ -0,0 +1,30 @@
+require_relative "append_only"
+
+module Hecks
+  module Ports
+    module Persistence
+      # Turns a declared adapter binding plus its world configuration into a
+      # concrete repository. Selection policy stays out of adapter creation.
+      module RepositoryFactory
+        module_function
+
+        def build(registry, domain, aggregate, bind, recover: true, settings_verb: VERB)
+          registry.check_verb(bind)
+          settings = (registry.world(domain)&.for_binding(settings_verb, bind.adapter) || {})
+                     .reject { |key, _| key.to_sym == :role }
+          registry.check_settings(bind, settings)
+          # The domain and the resolved era ride along after the
+          # declared-settings check: a lineage adapter journals per
+          # DOMAIN and writes into its own ERA's partition — neither of
+          # which a world's settings carry.
+          adapter = registry.adapter_class(bind.adapter)
+                            .new(aggregate: aggregate,
+                                 settings:  settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s]),
+                                 root:      registry.root)
+          repository = AppendOnly.new(adapter)
+          recover ? repository.recover! : repository
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence.port

@@ -0,0 +1,4 @@
+Hecks.port "persistence" do
+  verb   "persisted_by"   
+  signal :reply           
+end

data/lib/hecks/ports/persistence.rb

@@ -0,0 +1,39 @@
+module Hecks
+  module Ports
+    module Persistence
+      NAME = "persistence"
+      VERB = "persisted_by"
+      DEFAULT_ADAPTER = "Memory"
+    end
+  end
+end
+
+require_relative "persistence/binding_policy"
+require_relative "persistence/plugin"
+require_relative "persistence/repository_factory"
+require_relative "persistence/append_only"
+require_relative "persistence/execution"
+require_relative "persistence/remote_runtime"
+require_relative "persistence/null_saga_store"
+
+module Hecks
+  module Ports
+    module Persistence
+      module_function
+
+      # The public persistence port owns only authoritative aggregate heads.
+      def repository(registry, domain, aggregate)
+        authoritative = BindingPolicy.resolve(registry, domain, aggregate)
+        RepositoryFactory.build(registry, domain, aggregate, authoritative)
+      end
+
+      def binds_for(registry, domain, aggregate)
+        [BindingPolicy.resolve(registry, domain, aggregate), []]
+      end
+
+      def bind_for(registry, domain, aggregate)
+        binds_for(registry, domain, aggregate).first
+      end
+    end
+  end
+end

data/lib/hecks/ports/projection.port

@@ -0,0 +1,4 @@
+Hecks.port "projection" do
+  verb   "projected_by"
+  signal :effect
+end

data/lib/hecks/ports/projection.rb

@@ -0,0 +1,96 @@
+require_relative "persistence"
+require_relative "persistence/repository_factory"
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # Projection is a read-side port. Its stores are rebuildable consumers of
+    # authoritative entries and never participate in command decisions.
+    module Projection
+      NAME = "projection"
+      VERB = "projected_by"
+
+      module_function
+
+      def binds_for(registry, domain, aggregate)
+        registry.hecksagon(domain)&.binds_for(aggregate.hecks_name, VERB) || []
+      end
+
+      def worker(registry, domain, aggregate, policy: :refresh)
+        bind = binds_for(registry, domain, aggregate).first
+        return unless bind
+
+        authoritative = Persistence.repository(registry, domain, aggregate)
+        target = Persistence::RepositoryFactory.build(registry, domain, aggregate, bind,
+                                                      recover: true, settings_verb: VERB)
+        Worker.new(authoritative, target, policy: policy)
+      end
+
+      class Worker
+        attr_reader :projection
+
+        # The only two policies anything in this codebase ever passes
+        # (`bin/project`, every spec) — there is no third, legitimate
+        # "lenient append" policy on record anywhere. Before this, any
+        # value OTHER than the exact symbol `:strict` silently fell
+        # through the `consistent?` check below and appended onto
+        # divergent history without a word — not just a real typo like
+        # `:strikt`, but a caller-supplied String `"strict"` too (this
+        # duck-typed fine via `policy.to_sym`, but that was luck, not a
+        # contract: nothing here declared what a valid policy even was).
+        # Refusing loudly at construction, once, for anything outside
+        # this list turns a silent no-op into an immediate, named error
+        # — the "refuse rather than silently skip" reading of L1, since
+        # `:strict` really is meant to be the only enforcing contract.
+        VALID_POLICIES = %i[refresh strict].freeze
+
+        def initialize(authoritative, projection, policy: :refresh)
+          @authoritative = authoritative
+          @projection = projection
+          @policy = policy.to_sym
+          unless VALID_POLICIES.include?(@policy)
+            raise ArgumentError,
+                  "unknown projection catch_up! policy #{@policy.inspect} — expected one of " \
+                  "#{VALID_POLICIES.map(&:inspect).join(' or ')}"
+          end
+        end
+
+        # Invoke from a separate process or scheduler. The command-side write
+        # path never calls this method.
+        def catch_up!
+          entries = Queue.new(@authoritative).entries
+          present = @projection.entries
+          if @policy == :refresh
+            @projection.reset!
+            present = []
+          end
+          unless consistent?(entries, present)
+            raise Runtime::WiringError, "projection history does not match its authoritative history" if @policy == :strict
+          end
+          entries.drop(present.length).each { |entry| @projection.append(entry); @projection.project(entry) }
+          @projection
+        end
+
+        def checkpoint = @projection.entries.length
+
+        private
+
+        def same_entry?(left, right) = left.operation == right.operation && left.id == right.id && left.state == right.state
+
+        def consistent?(entries, present)
+          present.length <= entries.length && entries.first(present.length).zip(present).all? { |left, right|
+            same_entry?(left, right)
+          }
+        end
+      end
+
+      # The authoritative append-only journal is the durable projection queue.
+      # It is committed before a worker sees it; projection entries are the
+      # worker's durable checkpoint, so delivery is at-least-once and safe to replay.
+      class Queue
+        def initialize(authoritative) = @authoritative = authoritative
+        def entries = @authoritative.entries
+      end
+    end
+  end
+end

data/lib/hecks/ports/query/in_memory.rb

@@ -0,0 +1,60 @@
+require_relative "ordering"
+require_relative "../../runtime/value"
+require_relative "../../query_specification/field_path"
+require_relative "../../query_specification/common/comparison"
+
+module Hecks
+  module Ports
+    module Query
+      module InMemory
+        FieldPath = QuerySpecification::FieldPath
+        Comparison = QuerySpecification::Common::Comparison
+
+        module_function
+
+        def execute(records, declared, args = {}, registry: nil)
+          matched = records.select do |record|
+            declared.wheres.all? { |clause|
+              holds?(clause, comparable(FieldPath.dig(record, clause.field)), args, registry: registry)
+            }
+          end
+          field   = declared.order_by&.field
+          matched = Ordering.apply(matched, declared.order_by, declared.null_semantics,
+                                   identity: ->(record) { record.id.to_s }) { |record| comparable(FieldPath.dig(record, field)) }
+          # OFFSET FIRST, THEN LIMIT — the order SQL means by `LIMIT n
+          # OFFSET m`, which is what `SqlQueryBuilder` emits and therefore
+          # what every SQL-backed aggregate already answers. Written the
+          # other way round here, and the two engines disagreed on the
+          # same declaration: `limit 2, offset 1` over three rows is rows
+          # two and three in Postgres and Sqlite, and was row two alone in
+          # memory. Silently — a short page reads exactly like a page that
+          # ran out of rows.
+          #
+          # It gets worse the further you page, which is the case nobody
+          # writing the first page ever sees: at `limit 10, offset 10`,
+          # taking ten and then dropping ten leaves NOTHING, so page two
+          # of a memory-backed query came back empty however many rows
+          # were really there.
+          matched = matched.drop(resolve(declared.offset.value, args).to_i) if declared.offset
+          matched = matched.first(resolve(declared.limit.value, args).to_i) if declared.limit
+          matched
+        end
+
+        # The comparator table itself lives in
+        # QuerySpecification::Common::Comparison — this module and
+        # Runtime::QueryInterpreter used to carry a copy each, and the two
+        # drifted (see that file's own comment for what it cost). What
+        # stays here is how a value is REACHED for this path: a registry
+        # arrives as an argument rather than as instance state, and the
+        # field is dug through FieldPath before it arrives.
+        def holds?(clause, held, args, registry: nil)
+          Comparison.holds?(clause.op, held, comparable(resolve(clause.value, args)), registry: registry)
+        end
+
+        def resolve(value, args) = value.is_a?(Symbol) ? args[value] : value
+
+        def comparable(value) = Comparison.comparable(value)
+      end
+    end
+  end
+end

data/lib/hecks/ports/query/ordering.rb

@@ -0,0 +1,41 @@
+require_relative "../../query_specification/common/null_policy"
+
+module Hecks
+  module Ports
+    module Query
+      # What order an ask ANSWERS IN — the meaning of the ask, not a property
+      # of the store that happens to hold it. Declared here once so an adapter
+      # may satisfy it natively but never redefine it : SQLite pushes both
+      # tiers into SQL (NullPolicy.sql_order renders `field DIR, id DIR`),
+      # while Heki and Memory have no query engine and delegate straight back
+      # to InMemory.
+      #
+      # Two tiers, in this order : the DECLARED order_by when there is one,
+      # then IDENTITY, always. The identity tier is what makes an ask total.
+      # Without it, an ask with no order_by — or a declared order with tied
+      # keys — hands back whatever order the store happened to hold, and
+      # store order was quietly standing in for a rule while every
+      # hand-written query in the corpus stayed green : not one of them
+      # had a tie for store order to decide.
+      #
+      # An adapter that pushes ordering down MUST push limit down with it.
+      # Re-ordering a page the store already cut would be a top-N of the
+      # wrong N — the one way this can be got quietly, expensively wrong.
+      module Ordering
+        module_function
+
+        def apply(rows, order_by, null_semantics = nil, identity:, &value_of)
+          # STABLE, because sort_by is not : two rows whose identity ties would
+          # otherwise swap arbitrarily, and a tier meant to REMOVE store-dependence
+          # would be adding a coin flip of its own.
+          rows = rows.each_with_index.sort_by { |row, index| [identity.call(row), index] }.map(&:first)
+          return rows unless order_by
+
+          QuerySpecification::Common::NullPolicy.order(
+            rows, direction: order_by.direction, policy: null_semantics, &value_of
+          )
+        end
+      end
+    end
+  end
+end