hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,179 @@
+require "json"
+require "fileutils"
+require_relative "heki/snapshot"
+require_relative "heki/journal"
+require_relative "heki/saga_store"
+require_relative "../../ports/persistence/append_only"
+require_relative "../../ports/query/in_memory"
+require_relative "in_memory_ordering"
+require_relative "../../runtime/instance"
+
+module Hecks
+  module Adapters
+    # The file-backed store: a compressed snapshot (heki/snapshot.rb)
+    # plus an append-only journal beside it (heki/journal.rb). What stays
+    # here is the repository surface — find/all/save/delete, and the
+    # entry append/project pair the persistence port drives.
+    class Heki
+      include Snapshot
+      include Journal
+
+      MAGIC = "HEKI"
+      HEADER_BYTES = 8
+
+      class Malformed < StandardError; end
+
+      attr_reader :aggregate, :path
+
+      def initialize(aggregate:, settings: {}, root: nil)
+        @aggregate = aggregate
+        @path      = resolve_path(settings, root)
+        @journal_path = "#{@path}.journal"
+        @events    = []
+        # THE OPTIONAL saga-persistence capability's own scoping (§2/§4)
+        # — falls back to the aggregate's own name for a directly-
+        # instantiated adapter (specs), same fallback shape Postgres's
+        # own @domain already uses.
+        @domain    = (
+          if settings.key?(:domain)
+            settings[:domain]
+          elsif settings.key?("domain")
+            settings["domain"]
+          else
+            aggregate.name
+          end
+        ).to_s
+
+        FileUtils.mkdir_p(File.dirname(@path))
+      end
+
+      def find(id)
+        record = store[id.to_s]
+        return nil unless record
+
+        instance(id.to_s, record)
+      end
+
+      def all(order_by: nil, direction: :asc)
+        records = store.sort_by { |id, _| id }.map { |id, record| instance(id, record) }
+        InMemoryOrdering.ordered(records, aggregate: @aggregate, order_by: order_by, direction: direction)
+      end
+
+      def count = store.size
+
+      # `registry: context[:registry]` — Memory's own `query` already
+      # threads this through; Heki's own never did, which made
+      # `none_in_state?` (Ports::Query::InMemory) unconditionally
+      # return `true` (its own graceful "no registry, no way to look
+      # the target up" default) for EVERY `none_in_state` where-clause
+      # against a Heki-backed aggregate — silently excluding nothing,
+      # always, no matter the actual target state.
+      def query(specification, args = {}, context: {})
+        Ports::Query::InMemory.execute(all, specification, args, registry: context[:registry])
+      end
+
+      def append(entry)
+        @entry_mirrors = entry.mirrors
+        append_entry(entry.operation, entry.id, entry.state)
+        entry
+      ensure
+        @entry_mirrors = nil
+      end
+
+      # Reads fresh rather than trusting the memoized `store` — under
+      # `with_lock`, another process may have projected a snapshot since
+      # this one last read it, and mutating *its* stale copy would
+      # overwrite that write on disk rather than layer on top of it.
+      def project(entry)
+        current = read
+        entry.save? ? current[entry.id] = entry.state.dup : current.delete(entry.id)
+        write(current)
+        @store = current
+        entry
+      end
+
+      def save(instance)
+        entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+        with_lock do
+          append(entry)
+          project(entry)
+        end
+        instance
+      end
+
+      def delete(id)
+        return false unless find(id)
+
+        entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
+        with_lock do
+          append(entry)
+          project(entry)
+        end
+        true
+      end
+
+      def record_event(event) = @events << event
+
+      def events = @events
+
+      # ── the OPTIONAL saga-persistence capability (§2) — Heki's own
+      # shape (a sibling snapshot+journal file pair, `SagaStore`,
+      # heki/saga_store.rb) rather than a table in a store this adapter
+      # doesn't have.
+      def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
+        saga_store.save_saga(@domain, process_manager.to_s, correlation.to_s, state.to_s, memory, completed_compensations)
+      end
+
+      def delete_saga(process_manager:, correlation:)
+        saga_store.delete_saga(@domain, process_manager.to_s, correlation.to_s)
+      end
+
+      def each_saga(&block) = saga_store.each_saga(@domain, &block)
+
+      private
+
+      def saga_store
+        @saga_store ||= SagaStore.new(File.dirname(@path))
+      end
+
+      def instance(id, record)
+        Runtime::Instance.new(
+          aggregate: @aggregate,
+          id:        id,
+          state:     record.transform_keys(&:to_sym)
+        )
+      end
+
+      def store
+        @store ||= read
+      end
+
+      def read
+        snapshot = read_snapshot
+        replay_journal(snapshot)
+      end
+
+      # `dir: :default` — a bare Symbol, the framework's own convention
+      # for "a DECLARED value that resolves by convention, never a silent
+      # fallback" — used to crash `File.join` outright
+      # (`TypeError: no implicit conversion of Symbol into String`):
+      # `resolve_path` only ever checked for a MISSING `dir` setting,
+      # never a Symbol one. Treated the same as no setting at all — falls
+      # back to the existing "data" default, not a new special case.
+      def resolve_path(settings, root)
+        declared =
+          if settings.key?(:dir)
+            settings[:dir]
+          elsif settings.key?("dir")
+            settings["dir"]
+          else
+            "data"
+          end
+        declared = "data" if declared == :default
+        dir      = declared.start_with?("/") ? declared : File.join(root || Dir.pwd, declared)
+
+        File.join(dir, "#{@aggregate.storage_name}.heki")
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/identity_registry.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "IdentityRegistry" do
+  port "identity_resolution"
+end

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

@@ -0,0 +1,26 @@
+module Hecks
+  module Adapters
+    # THE `identity_resolution` PORT, FULFILLED BY THE Identity FRAMEWORK
+    # BLUEBOOK — same registry, same boot, so this is a dispatch against
+    # records already sitting in the store this adapter is handed, not a
+    # bridge to a second runtime. Same reasoning `GovernanceAuthorization`
+    # gives for itself, one port over.
+    module IdentityRegistry
+      module_function
+
+      # `nil` for a pair nothing has linked, the first match otherwise —
+      # `ResolvedBy` is a lookup by the exact (issuer, subject) an
+      # authenticated token carries, not a listing, so more than one row
+      # would mean two links share a pair, which `Link`'s own natural
+      # key already prevents by construction.
+      def resolve(registry, issuer:, subject:)
+        rows = Runtime::Dispatcher.new(registry).query(
+          "Identity::ExternalIdentifier.ResolvedBy",
+          issuer: { value: issuer.to_s }, subject: { value: subject.to_s }
+        )
+
+        rows.first&.fetch(:identity)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+require_relative "../../ports/query/in_memory"
+require_relative "../../ports/query/ordering"
+require_relative "../../query_specification/common/order_by"
+require_relative "../../query_specification/field_path"
+require_relative "../../runtime/errors"
+
+module Hecks
+  module Adapters
+    # SHARED BY every adapter that holds decoded Ruby records rather than
+    # running real SQL (Memory, Lambda, Heki) — the identical dotted-path
+    # value-object member-picking Postgres/Sqlite/D1's own
+    # order_expression does (numeric member wins, else the one-field
+    # convention "value"), just walked in Ruby instead of compiled to a
+    # JSONB/json_extract path, because there is no query engine
+    # underneath any of these three to hide that walk inside.
+    module InMemoryOrdering
+      module_function
+
+      # order_by IS A RUNTIME VALUE (an HTTP query param, in the
+      # console's case), not framework-authored bluebook source — see
+      # postgres.rb's own all for the full reasoning. Whitelisted the
+      # identical way before FieldPath.dig ever runs.
+      def ordered(records, aggregate:, order_by:, direction:)
+        return records unless order_by
+
+        name = order_by.to_s.split(".").first
+        raise Runtime::WiringError, "#{aggregate.name} has no attribute #{order_by.inspect} to order by" unless aggregate.lifecycle&.field.to_s == name || aggregate.attribute(name)
+
+        path = sortable_path(aggregate, order_by)
+        spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
+        Ports::Query::Ordering.apply(records, spec, nil, identity: ->(record) { record.id.to_s }) do |record|
+          Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(record, path))
+        end
+      end
+
+      def sortable_path(aggregate, field)
+        name, *path = field.to_s.split(".")
+        return field.to_s unless path.empty?
+
+        attribute = aggregate.attribute(name)
+        return field.to_s if aggregate.lifecycle&.field.to_s == name || attribute.nil?
+
+        vo = aggregate.value_object(attribute.type)
+        return field.to_s unless vo
+
+        member = vo.attributes.find { |a| %w[Integer Float].include?(a.type) }&.name || "value"
+        "#{name}.#{member}"
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/lambda/client.rb

@@ -0,0 +1,63 @@
+require "json"
+
+module Hecks
+  module Adapters
+    class Lambda
+      # THE THIN AWS CLIENT — shared by this adapter's own read methods
+      # (Lambda#find/#all/#count/#query) and Runtime::RemoteDispatcher's
+      # write methods. One Lambda invoke, one JSON round trip, nothing
+      # domain-specific: neither caller needs to know an AWS SDK is
+      # involved at all.
+      #
+      # FUNCTION NAME IS COMPUTED, NOT PASSED — `"hecks-#{domain}"`,
+      # lowercased, matches bin/project_deploy's own `stack_name`
+      # exactly (bin/project_deploy: `stack_name = "hecks-#{domain_name}"`,
+      # `domain_name = File.basename(domain)`). `domain` here is the
+      # bluebook's OWN declared name (`Embryonaut`, not the directory);
+      # today's real corpus has directory name == declared name
+      # lowercased for every domain that deploys, so `.downcase` alone
+      # reproduces the same string bin/project_deploy computes from the
+      # directory — this is a real, load-bearing assumption, not a
+      # coincidence to lean on silently forever if that ever stops
+      # holding.
+      class Client
+        def initialize(domain:, region:)
+          require "aws-sdk-lambda"
+          @function_name = "hecks-#{domain.to_s.downcase}"
+          @client = Aws::Lambda::Client.new(region: region)
+        end
+
+        # THE WHOLE DOMAIN, EVERY TIME — matches dispatch::read's own
+        # rehydrate-the-full-journal design (Phase 1, rust/host). No
+        # caching here, deliberately not even per-request: Lambda#all
+        # used to memoize this across calls, which silently served
+        # stale reads for a warm web process's whole lifetime once a
+        # write happened elsewhere — see Lambda#instances's own comment
+        # on the real, live bug that caught it.
+        def read
+          invoke({ "read" => true })
+        end
+
+        def dispatch(verb, args, role: nil)
+          payload = { "verb" => verb, "args" => args }
+          payload["role"] = role if role
+          invoke(payload)
+        end
+
+        private
+
+        def invoke(payload)
+          response = @client.invoke(function_name: @function_name, payload: JSON.generate(payload))
+          body = JSON.parse(response.payload.read)
+
+          if response.function_error
+            raise Runtime::WiringError,
+                  "Lambda #{@function_name} (#{response.function_error}): #{body['errorMessage'] || body}"
+          end
+
+          body
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/lambda.adapter

@@ -0,0 +1,4 @@
+Hecks.adapter "Lambda" do
+  port "persistence"
+  field :region
+end

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

@@ -0,0 +1,145 @@
+require_relative "lambda/client"
+require_relative "../../ports/query/in_memory"
+require_relative "../../ports/persistence/remote_runtime"
+require_relative "in_memory_ordering"
+require_relative "../../runtime/instance"
+
+module Hecks
+  module Adapters
+    # THE READ-SIDE HALF OF LAMBDA ROUTING — `persisted_by("Lambda")`'s
+    # own adapter, resolved through the SAME `Ports::Persistence`
+    # machinery `persisted_by("Postgres")`/`persisted_by("Memory")`
+    # already use (`Runtime::Registry#repository`, `RepositoryFactory
+    # .build`) — no new framework plumbing, just a new adapter class at
+    # the name the existing lookup already expects. See
+    # `Runtime::RemoteDispatcher` for the write-side half; the two
+    # compose through one shared `Client` per domain rather than each
+    # inventing its own AWS wiring.
+    #
+    # READ-ONLY, DELIBERATELY — `append`/`project` raise rather than
+    # silently no-op. A write reaching this class would mean
+    # `Runtime::CommandInterpreter` ran locally against a Lambda-routed
+    # domain, which is exactly the bypass `Runtime::RemoteDispatcher`
+    # exists to prevent (business-rule validation must happen in Rust
+    # for these domains, not be pre-computed here against an
+    # incomplete local view). A loud failure here is the correct
+    # outcome, not a bug to route around.
+    class Lambda
+      include Ports::Persistence::RemoteRuntime
+
+      attr_reader :aggregate
+
+      def initialize(aggregate:, settings: {}, root: nil)
+        @aggregate = aggregate
+        domain =
+          if settings.key?(:domain)
+            settings[:domain]
+          elsif settings.key?("domain")
+            settings["domain"]
+          else
+            aggregate.name
+          end
+        region =
+          if settings.key?(:region)
+            settings[:region]
+          elsif settings.key?("region")
+            settings["region"]
+          else
+            "us-east-1"
+          end
+        # TWO DIFFERENT "domain"s, deliberately not conflated: `domain`
+        # (this aggregate's OWN bluebook name — "Identity", "Governance")
+        # only ever prefixes the instances lookup, since that's how
+        # rust/host's own `Store::instances()` keys every record
+        # (`registry.rb`'s own `"#{a[:domain_name]}::#{a[:name]}#"`
+        # dump format, unchanged by which chapter attached it). The
+        # FUNCTION to actually call is a different question: Governance
+        # and Identity aggregates are compiled into the ATTACHING
+        # domain's own Lambda (one merged `Store` per target — Phase 0's
+        # framework-bluebook work), never a function of their own, so
+        # `settings[:domain]` is the wrong signal for `Client.new`.
+        # `root` is the boot's own directory (`Registry#root`, shared by
+        # EVERY bluebook in one registry regardless of which one
+        # attached it) — `File.basename(root)` reproduces the exact
+        # same string `bin/project_deploy`'s own `stack_name` computes
+        # from the domain PATH, so the two can never name two
+        # different functions for the same deploy... on a LOCAL boot,
+        # where `root` is a real project directory. Inside the deployed
+        # Lambda itself `root` is ALWAYS `/var/task` (every Lambda's own
+        # fixed code root, regardless of domain) — `File.basename` gives
+        # "task", not the domain name, and invokes the wrong function
+        # entirely. A real, live AccessDeniedException on
+        # "hecks-task" caught this: invisible through every earlier
+        # phase's own verify step, all run from a local boot, until
+        # WebFunction became the first Ruby process to EVER make this
+        # exact call from inside a deployed Lambda. `DOMAIN_NAME` (set
+        # by bin/project_deploy's own WebFunction Environment) is the
+        # real, unambiguous signal in that specific context; the
+        # root-basename heuristic stays as the local-boot fallback,
+        # unchanged.
+        function_domain = ENV["DOMAIN_NAME"] || (root ? File.basename(root) : domain)
+        @client = Client.new(domain: function_domain, region: region)
+        @prefix = "#{domain}::#{aggregate.hecks_name}#"
+      end
+
+      def find(id)
+        instances[id.to_s]
+      end
+
+      def all(order_by: nil, direction: :asc)
+        InMemoryOrdering.ordered(instances.values, aggregate: @aggregate, order_by: order_by, direction: direction)
+      end
+
+      def count = instances.size
+
+      def query(specification, args = {}, context: {})
+        Ports::Query::InMemory.execute(instances.values, specification, args)
+      end
+
+      # `entries`/`append`/`project` — the append-only contract
+      # `Ports::Persistence::AppendOnly` requires of every adapter
+      # (raises at construction if any are missing). Answered by
+      # `Ports::Persistence::RemoteRuntime`, included above: `entries` is
+      # `[]` unconditionally (Lambda's own Postgres is already the
+      # durable store — rust/host's rehydrate-and-replay journal, Phase
+      # 1 — there is no local write-ahead log for `recover!` to replay),
+      # `append`/`project` raise rather than silently no-op.
+
+      private
+
+      # RE-FETCHED EVERY CALL, deliberately NOT memoized across them —
+      # this adapter itself is long-lived (one instance per aggregate,
+      # held by the registry `RUNTIME = Hecks.boot(...)` builds ONCE
+      # per Lambda web process — WebFunction's own top-level constant,
+      # reused warm across every HTTP request that process serves, not
+      # rebuilt per request the way a memoize-for-one-request comment
+      # here used to assume). A real, live bug caught this: a mutation
+      # dispatched fine (RemoteDispatcher always calls the dispatch
+      # Lambda fresh) and the very next `.all` on the SAME warm
+      # container kept returning the state from BEFORE that mutation,
+      # forever, until the container cold-started — memoizing here
+      # made every write invisible to every read on a warm container.
+      # Keyed by bare id (the part after "Domain::Aggregate#"), not the
+      # full "Domain::Aggregate#id" string — callers already know which
+      # aggregate they're asking this instance about.
+      def instances
+        @client.read.fetch("instances", {}).filter_map { |key, state|
+          next unless key.start_with?(@prefix)
+
+          [key.delete_prefix(@prefix), build_instance(key.delete_prefix(@prefix), state)]
+        }.to_h
+      end
+
+      # Lambda's own JSON response is already Ruby-decoded with STRING
+      # keys (plain `JSON.parse`, no `symbolize_names:`) — every other
+      # adapter's own `instance(row)` builder (Postgres, Sqlite) hands
+      # `Runtime::Instance.new` a SYMBOL-keyed state hash instead. A
+      # round trip through `JSON.generate`/`JSON.parse` is simpler and
+      # safer than a hand-rolled deep-symbolize helper for what is not
+      # a hot path.
+      def build_instance(id, state)
+        Runtime::Instance.new(aggregate: @aggregate, id: id, state: JSON.parse(JSON.generate(state), symbolize_names: true))
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/memory.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "Memory" do
+  port   "persistence"
+end

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

@@ -0,0 +1,103 @@
+require_relative "../../ports/persistence/append_only"
+require_relative "../../ports/query/in_memory"
+require_relative "in_memory_ordering"
+require_relative "../../runtime/instance"
+
+module Hecks
+  module Adapters
+    class Memory
+      # TENANT-CAPABLE TRIVIALLY — see Runtime::TenantCheck's own header
+      # for the full reasoning. `@records` is a plain instance variable;
+      # two `Runtime.boot` calls build two entirely separate Registry
+      # objects and, through them, two entirely separate Memory
+      # instances, so two tenant boots never share this adapter's state
+      # by construction — nothing here needs to know "tenant" exists.
+      def self.tenant_capable? = true
+      def persistence_capabilities = [:atomic_put]
+
+      attr_reader :aggregate
+
+      def initialize(aggregate:, settings: {}, root: nil)
+        @aggregate = aggregate
+        @records   = {}
+        @events    = []
+        @entries   = []
+      end
+
+      def find(id) = @records[id.to_s]
+      def count    = @records.size
+
+      def all(order_by: nil, direction: :asc)
+        InMemoryOrdering.ordered(@records.values, aggregate: @aggregate, order_by: order_by, direction: direction)
+      end
+
+      def query(specification, args = {}, context: {})
+        Ports::Query::InMemory.execute(all, specification, args, registry: context[:registry])
+      end
+
+      def append(entry)
+        @entries << entry
+        entry
+      end
+
+      def project(entry)
+        if entry.save?
+          @records[entry.id] = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state.dup)
+        else
+          @records.delete(entry.id)
+        end
+      end
+
+      def save(instance)
+        entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+        append(entry)
+        project(entry)
+      end
+
+      # One in-memory critical section in the only thread touching this plain
+      # Hash: classify and replace without a preliminary repository lookup.
+      # Durable append and projection remain ordered exactly as ordinary save.
+      def atomic_put(entry, insert_only: false)
+        exists = @records.key?(entry.id.to_s)
+        return :conflicted if insert_only && exists
+
+        status = exists ? :replaced : :inserted
+        append(entry)
+        project(entry)
+        status
+      end
+
+      def delete(id)
+        entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
+        append(entry)
+        project(entry)
+      end
+
+      def record_event(event) = @events << event
+
+      def events = @events
+
+      def entries = @entries.dup
+
+      # Every other driven adapter (Postgres/PostgresEra/Sqlite/D1)
+      # already implements this — `Ports::Persistence::AppendOnly#reset!`
+      # forwards to it and only raises when the wrapped adapter doesn't
+      # respond to `reset!` at all, which was always this adapter's own
+      # gap, not a deliberate omission (nothing about "in memory" implies
+      # "cannot be cleared"). Existing callers that fully re-`Hecks.boot`
+      # a domain per test case don't need this — they get a brand new
+      # `Memory` instance, with brand new empty `@records`/`@events`/
+      # `@entries`, for free. This is for the other case: a caller that
+      # deliberately keeps ONE booted runtime across many cases (to skip
+      # `load_domain`'s own per-boot parse/verify cost) and wants each
+      # case to start from the same clean slate `Hecks.boot` would have
+      # given it, without paying for a fresh boot to get there.
+      def reset!
+        @records = {}
+        @events  = []
+        @entries = []
+        self
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/mock_stripe_adapter.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "MockStripeAdapter" do
+  port "checkout"
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    # A GENERIC STAND-IN for a real Checkout-Session-style adapter — no
+    # network call, no real account, matching whatever real payment
+    # adapter a project pairs it with by shape alone
+    # (`create_session(event:, registration_id:, success_url:, cancel_url:)
+    # -> a URL string`), the same way `Memory` stands in for a real
+    # persistence adapter without knowing anything about the domain bound
+    # to it. Never reads `event`'s own fields — a real adapter needs the
+    # price/name inside it to build a session a payer actually sees;
+    # this only needs to look enough like one to swap in.
+    #
+    # The URL it returns carries the same `registration_id` a real
+    # webhook's metadata would, so a caller building its own signed
+    # webhook against it (a smoke test, CI) has something real to key
+    # off of — the real shape production has, minus the network hop.
+    class MockStripeAdapter
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      def create_session(event:, registration_id:, success_url:, cancel_url:)
+        separator = success_url.include?("?") ? "&" : "?"
+        "#{success_url}#{separator}mock_checkout=1&mock_registration_id=#{registration_id}"
+      end
+    end
+  end
+end