hecks 0.2.0 → 0.3.0

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/lineage"
+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,76 @@
+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
+
+        def initialize(authoritative, projection, policy: :refresh)
+          @authoritative = authoritative
+          @projection = projection
+          @policy = policy.to_sym
+        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

data/lib/hecks/ports/query.rb

@@ -0,0 +1,36 @@
+module Hecks
+  module Ports
+    # Common query execution boundary. Adapters expose one optional native
+    # hook; all other query behavior remains in the shared interpreter.
+    # Ordering (the meaning of an ask's answer order) and InMemory (the
+    # fallback engine for stores with no query engine of their own) are
+    # its collaborators — query/ordering.rb and query/in_memory.rb.
+    module Query
+      class Unsupported < StandardError; end
+
+      module_function
+
+      def execute(repository, specification, args = {}, context: {})
+        adapter = repository.respond_to?(:adapter) ? repository.adapter : repository
+        return nil unless adapter.respond_to?(:query)
+
+        validate!(specification, adapter)
+        adapter.query(specification, args, context: context)
+      end
+
+      def validate!(specification, adapter)
+        if specification.cursor && specification.offset
+          raise Unsupported, "a query cannot combine cursor and offset pagination"
+        end
+
+        return if specification.inspection.nil? || adapter.respond_to?(:inspect_query)
+        return if specification.inspection.mode.to_s == "sql" && adapter.respond_to?(:query)
+
+        raise Unsupported, "#{adapter.class} cannot inspect generated queries"
+      end
+    end
+  end
+end
+
+require_relative "query/ordering"
+require_relative "query/in_memory"

data/lib/hecks/ports.rb

@@ -0,0 +1,27 @@
+# Hecks::Ports
+#
+# The runtime's named boundaries. Each port is a file beside this one —
+# `ports/persistence.rb`, `ports/query.rb`, … — and a port with supporting
+# cast keeps it in a same-named directory (`ports/persistence/` holds the
+# binding policy, the journal-translation lineage, the repository factory).
+# The `.port` files beside them are the DSL declarations the meta-validator
+# and the Folder adapter load as data.
+
+module Hecks
+  module Ports
+  end
+end
+
+require_relative "ports/loading"
+require_relative "ports/persistence"
+require_relative "ports/query"
+require_relative "ports/projection"
+require_relative "ports/extraction"
+require_relative "ports/identity_generation"
+require_relative "ports/authorization"
+require_relative "ports/identity_resolution"
+require_relative "ports/authentication"
+require_relative "ports/access_control"
+require_relative "ports/identity_assignment"
+require_relative "ports/agent"
+require_relative "ports/clock"