hecks 0.2.0 → 1.0.0

data/lib/hecks/ports/clock.rb

@@ -0,0 +1,62 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # WHAT TIME IT IS — the one fact a domain cannot derive and must not invent.
+    #
+    # Resolved exactly the way `Ports::IdentityGeneration` resolves its own
+    # adapter: one adapter registry-wide implements this, not a per-aggregate
+    # binding, because two aggregates in one running app have no real reason to
+    # disagree about the time.
+    #
+    # WHY A PORT AND NOT `Time.now`. A staleness rule — "another agent may take
+    # this claim after fifteen minutes" — is untestable against the real clock:
+    # a spec for it would either sleep for fifteen minutes or never run at all.
+    # Bound to a fixed adapter, the same rule is three lines. That is the whole
+    # argument, and it is the same one `SequentialIdentity` makes next door.
+    #
+    # A PREDICATE STILL CANNOT ASK THE TIME, and this does not change that. The
+    # expression sublanguage has no clock and should not: a `given` that read
+    # the time would evaluate differently on two runs over the same record, and
+    # every replay, audit and fuzz oracle in this repository assumes it does
+    # not. So `now` remains an ARGUMENT the predicate merely reads, and this
+    # port is what lets a caller stop typing it — the door fills it in, the
+    # value is baked into the dispatch, and the recorded step carries the
+    # concrete number forever after.
+    #
+    # WHICH IS WHY THE RUNTIME DOES NOT CALL THIS. `IdentityGeneration`'s own
+    # note works through the replay question for a minted uuid and lands on
+    # "the value gets baked into the caller's args at the first live dispatch".
+    # A clock consulted INSIDE the interpreter would not have that property: a
+    # recorded corpus step replayed tomorrow would silently get tomorrow's
+    # time, and the fuzzer's oracle and the adapter-agreement gate both compare
+    # runs of exactly that shape. So the filling happens at the door, where a
+    # human or an agent is typing, and never on the dispatch path a replay uses.
+    module Clock
+      NAME = "clock"
+
+      module_function
+
+      # SECONDS, AS AN INTEGER, because that is what the sublanguage can do
+      # arithmetic on. `claimed_at.value + window.value <= now.value` is
+      # addition and comparison — the only two things it has — and a Time
+      # object supports neither.
+      def now(registry) = adapter(registry).now
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can say what time it is"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/extraction.port

@@ -0,0 +1,5 @@
+Hecks.port "extraction" do
+  verb    "extracted_by"
+  signal  :reply
+  answers :canonical
+end

data/lib/hecks/ports/extraction.rb

@@ -0,0 +1,37 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    module Extraction
+      NAME = "extraction"
+
+      module_function
+
+      def canonical(block) = adapter.canonical(block)
+
+      def adapter
+        registry = Hecks.current_registry
+        unless registry
+          raise Runtime::WiringError,
+                "extraction resolved outside a boot — a predicate can only be " \
+                "read while a bluebook is loading"
+        end
+
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can recover a " \
+                "predicate's source"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime " \
+                "will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/identity_assignment.port

@@ -0,0 +1,5 @@
+Hecks.port "identity_assignment" do
+  verb    "assigned_by"
+  signal  :reply
+  answers :assign
+end

data/lib/hecks/ports/identity_assignment.rb

@@ -0,0 +1,45 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # WHICH VALUE A CREATING COMMAND'S OWN IDENTITY FIELD GETS, when
+    # neither a slug-from-another-field nor a sequence-with-prefix
+    # mechanically answers it — a driving app's own console, say,
+    # falls back to this when a collection's identity strategy names
+    # "port" rather than "slug"/"sequence" (both of those stay pure
+    # config-driven mechanics, computed by whoever is dispatching,
+    # never by this port).
+    #
+    # Pure delegation, same as every sibling port (AccessControl,
+    # IdentityGeneration): an app's own domain declares what "port"
+    # actually MEANS for it — mint a real UUID via
+    # Ports::IdentityGeneration, derive something else entirely — this
+    # port just resolves the one adapter that domain wired and calls
+    # it, the same "one adapter registry-wide, refuse if zero or many"
+    # resolution every other port here already uses.
+    module IdentityAssignment
+      NAME = "identity_assignment"
+
+      module_function
+
+      def assign(registry, agg_name:, field_name:, args:)
+        adapter(registry).assign(registry, agg_name: agg_name, field_name: field_name, args: args)
+      end
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can assign an identity"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/identity_generation.port

@@ -0,0 +1,5 @@
+Hecks.port "identity_generation" do
+  verb    "generated_by"
+  signal  :reply
+  answers :uuid
+end

data/lib/hecks/ports/identity_generation.rb

@@ -0,0 +1,49 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # A creating command with no natural key needs a value from
+    # SOMEWHERE to be its identity — this is that somewhere. Resolved
+    # the same way `Ports::Extraction` resolves its own adapter (one
+    # adapter registry-wide implements this port, not a per-aggregate
+    # binding the way persistence needs — different aggregates have no
+    # real reason to want different id-generation strategies within
+    # one running app).
+    #
+    # REPLAY NEEDS NO SUPPRESSION HERE, ON PURPOSE. A UUID minted for a
+    # creating command's identity gets baked into that step's own args
+    # — an ordinary string value — the moment it's generated, by
+    # whoever issues the first, live dispatch. A recorded corpus
+    # script or a captured fuzz-replay step already holds that
+    # concrete value; replaying it calls `dispatch` with the SAME
+    # args, and this module is never consulted again, for the same
+    # reason `SecureRandom.uuid` never runs twice for one
+    # already-recorded step today. `Event#occurred_at`
+    # (`command_rules/emission.rb`) is the one other "environmental
+    # fact, not caller-supplied" this codebase has, and it's handled
+    # the identical way: it fires on every dispatch, replay included,
+    # and comparison simply excludes it.
+    module IdentityGeneration
+      NAME = "identity_generation"
+
+      module_function
+
+      def uuid(registry) = adapter(registry).uuid
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can mint an identity"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/identity_resolution.port

@@ -0,0 +1,5 @@
+Hecks.port "identity_resolution" do
+  verb    "resolved_by"
+  signal  :reply
+  answers :resolve
+end

data/lib/hecks/ports/identity_resolution.rb

@@ -0,0 +1,40 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # AN AUTHENTICATED (issuer, subject) PAIR, RESOLVED TO A STABLE
+    # `Identity` — the other half of the same symmetry `Authorization`
+    # already has for Governance: one adapter registry-wide answers this
+    # port, resolved the same zero/one/many way, so an application never
+    # has to name `Identity` directly to ask "who is this."
+    #
+    # Answers `nil` for a pair nothing has linked — the caller decides
+    # what that means (refuse, prompt to register, whatever), the same
+    # way `Authorization#holds_role?` answering `false` decides nothing
+    # on its own.
+    module IdentityResolution
+      NAME = "identity_resolution"
+
+      module_function
+
+      def resolve(registry, issuer:, subject:)
+        adapter(registry).resolve(registry, issuer: issuer, subject: subject)
+      end
+
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+
+        case implementations.size
+        when 1 then registry.adapter_class(implementations.first.name)
+        when 0
+          raise Runtime::WiringError,
+                "no adapter implements the #{NAME} port — nothing can resolve an identity"
+        else
+          raise Runtime::WiringError,
+                "#{implementations.size} adapters implement the #{NAME} port " \
+                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/loading.port

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

data/lib/hecks/ports/loading.rb

@@ -0,0 +1,13 @@
+require_relative "../adapters/driven/folder"
+
+module Hecks
+  module Ports
+    module Loading
+      NAME = "loading"
+
+      module_function
+
+      def bootstrap = Adapters::Folder.new
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+require_relative "../../runtime/registry"
+require_relative "execution"
+
+module Hecks
+  module Ports
+    module Persistence
+      # `mirrors` is durable replication intent.  It is part of the same
+      # append as the authoritative state, never a second outbox store.
+      Entry = Struct.new(:operation, :id, :state, :mirrors, keyword_init: true) do
+        def save? = operation == "save"
+        def delete? = operation == "delete"
+      end
+
+      # Makes append-before-projection a port invariant. Adapters retain
+      # control of their durable format, but every one must accept the same
+      # entry stream and materialize current state from it.
+      class AppendOnly
+        attr_reader :adapter
+
+        def aggregate = @adapter.aggregate
+
+        def initialize(adapter)
+          @adapter = adapter
+          required = %i[append project entries]
+          missing = required.reject { |method| adapter.respond_to?(method) }
+          raise Runtime::WiringError,
+                "#{adapter.class} does not implement append-only persistence: #{missing.join(', ')}" unless missing.empty?
+        end
+
+        def find(id) = @adapter.find(id)
+        def all(**opts) = @adapter.all(**opts)
+        def count = @adapter.count
+        def entries = @adapter.entries
+
+        def capabilities
+          return [] unless @adapter.respond_to?(:persistence_capabilities)
+
+          Array(@adapter.persistence_capabilities).map(&:to_sym).freeze
+        end
+
+        def reset!
+          raise Runtime::WiringError, "append-only adapter cannot reset" unless @adapter.respond_to?(:reset!)
+
+          @adapter.reset!
+        end
+
+        # NOT an endless `def events = ... if ...` — that modifier binds to
+        # the WHOLE `def`, not just its body, so it evaluates against
+        # `@adapter` while `@adapter` is still nil (class-body time,
+        # before `initialize` ever runs) and silently skips defining the
+        # method at all. Found live: nothing in this codebase called
+        # `AppendOnly#events` before Memory got a `reset!` test that did.
+        def events
+          @adapter.events if @adapter.respond_to?(:events)
+        end
+
+        # An append is durable before a projection is attempted. Replaying the
+        # log restores a snapshot/table after a crash in that small window.
+        def recover!
+          entries.each { |entry| project(entry) }
+          self
+        end
+
+        def append(entry) = @adapter.append(entry)
+        def project(entry) = @adapter.project(entry)
+
+        # Returns an `Outcome`, not a bare `Instance` — every call site
+        # (`CommandInterpreter`/`EntityInterpreter`'s own `step_save`,
+        # `RebuildSweep#refresh`) reads it that way.
+        #
+        # `expected_version:` requests optimistic-concurrency CAS — commit
+        # only if the stored record's version still matches what THIS
+        # instance was read at. It is `nil` both when a caller explicitly
+        # doesn't want CAS (`RebuildSweep#refresh`'s own projection-field
+        # touch-up, which has no `given` to protect) and when the instance
+        # is brand new (never read from storage, so `instance.version` is
+        # nil) — both cases fall through to the plain, unconditional
+        # `project(entry)` below, byte-for-byte today's behavior. Only an
+        # adapter that both receives a non-nil `expected_version` AND
+        # declares `:optimistic_concurrency` gets CAS treatment; every
+        # other adapter/call site is unaffected.
+        def save(instance, expected_version: nil)
+          entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+          append(entry)
+          if expected_version && capabilities.include?(:optimistic_concurrency)
+            saved = @adapter.project(entry, expected_version: expected_version)
+            return Outcome.new(status: :stale, instance: instance) if saved.nil?
+
+            return Outcome.new(status: :saved, instance: saved)
+          end
+          saved = @adapter.project(entry)
+          Outcome.new(status: :saved, instance: saved || instance)
+        end
+
+        def atomic_put(instance, insert_only: false)
+          unless capabilities.include?(:atomic_put) && @adapter.respond_to?(:atomic_put)
+            raise Runtime::WiringError, "#{@adapter.class} advertises no atomic_put persistence capability"
+          end
+
+          entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+          status = @adapter.atomic_put(entry, insert_only: insert_only)
+          Outcome.new(status: status, instance: instance)
+        end
+
+        def delete(id)
+          return false unless find(id)
+
+          entry = Entry.new(operation: "delete", id: id.to_s, state: nil)
+          append(entry)
+          project(entry)
+          true
+        end
+
+        # NOT an endless `def record_event = ... if ...` — same gotcha as
+        # `events` above, and it bit for real here: this guard evaluated
+        # against `@adapter` at class-body time (nil, always false), so
+        # `record_event` was never defined at all. `emission.rb`'s own
+        # `repository.record_event(event) if repository.respond_to?(:record_event)`
+        # therefore never fired for any adapter, ever — every declared
+        # `emits` was computed and reported in `registry.event_log` (an
+        # in-process array, gone at exit) but never durably recorded.
+        # Caught because a live tail of a domain's own persisted events
+        # found nothing to tail. `sqlite_spec.rb`/`postgres_spec.rb`/
+        # `postgres_era_spec.rb` all call `adapter.record_event` directly,
+        # bypassing this wrapper — which is exactly why no spec noticed.
+        def record_event(event)
+          @adapter.record_event(event) if @adapter.respond_to?(:record_event)
+        end
+
+        def query_read_model(domain, model, args, bluebook = nil)
+          return unless @adapter.respond_to?(:query_read_model)
+
+          @adapter.query_read_model(domain, model, args, bluebook)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+require_relative "../../bluebook/hexagon"
+require_relative "../../runtime/registry"
+
+module Hecks
+  module Ports
+    module Persistence
+      # Resolves one aggregate's persistence topology. An unmarked binding is
+      # authoritative; roles are deliberately opt-in so a second adapter can
+      # never silently become a read source.
+      module BindingPolicy
+        module_function
+
+        def resolve(registry, domain, aggregate)
+          hexagon = registry.hecksagon(domain)
+          return default_binding(aggregate) unless hexagon
+
+          bindings = hexagon.binds_for(aggregate.hecks_name, VERB)
+          raise missing_binding(domain, aggregate) if bindings.empty?
+
+          authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }
+          raise ambiguous_binding(domain, aggregate, authoritative) unless authoritative.size == 1
+          raise unsupported_roles(domain, aggregate, bindings - authoritative) unless (bindings - authoritative).empty?
+
+          authoritative.first
+        end
+
+        def default_binding(aggregate)
+          Bluebook::Bind.new(aggregate: aggregate.hecks_name, verb: VERB, adapter: DEFAULT_ADAPTER)
+        end
+
+        def missing_binding(domain, aggregate)
+          Runtime::WiringError.new(
+            "#{domain}::#{aggregate.hecks_name} has no #{VERB} bind. #{domain} declares a " \
+            "hecksagon, so its wiring is being decided explicitly and an aggregate " \
+            "left out is a forgotten decision. Bind it, or say " \
+            "#{aggregate.hecks_name}.#{VERB}(#{DEFAULT_ADAPTER.inspect}) to keep it in memory on purpose."
+          )
+        end
+
+        def ambiguous_binding(domain, aggregate, authoritative)
+          Runtime::WiringError.new(
+            "#{domain}::#{aggregate.hecks_name} has #{authoritative.size} authoritative #{VERB} bindings. " \
+            "Declare exactly one adapter without a role."
+          )
+        end
+
+        def unsupported_roles(domain, aggregate, bindings)
+          Runtime::WiringError.new(
+            "#{domain}::#{aggregate.hecks_name} uses persistence role#{bindings.size == 1 ? '' : 's'} " \
+            "#{bindings.map(&:role).map(&:inspect).join(', ')}. Only persisted_by is supported."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Hecks
+  module Ports
+    module Persistence
+      # Adapter outcomes are runtime facts, never command lifecycle.
+      Outcome = Struct.new(:status, :instance, keyword_init: true) do
+        # `:stale` is an optimistic-concurrency conflict on a plain `save`
+        # (someone else committed since this instance was read) — never a
+        # domain refusal, distinct from `:conflicted` (a `creates?`
+        # command's identity already exists, `AlreadyExists`). See
+        # `Runtime::StaleWrite` (runtime/errors.rb) and `AppendOnly#save`.
+        STATUSES = %i[inserted replaced updated conflicted missing saved stale].freeze
+
+        def initialize(status:, instance: nil)
+          normalized = status.to_sym
+          raise ArgumentError, "unknown persistence outcome #{status.inspect}" unless STATUSES.include?(normalized)
+
+          super(status: normalized, instance: instance)
+          freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Hecks
+  module Ports
+    module Persistence
+      # THE NO-OP SAGA STORE — what `Registry#saga_persistence` hands
+      # back for a domain whose resolved adapter doesn't implement the
+      # (optional) saga-persistence capability: Memory, deliberately
+      # (sagas stay in-memory-only, exactly as they always have), and
+      # any `RemoteRuntime`-shaped adapter (Lambda; the real durability
+      # for those lives on the other side of the call — Phase 1, not
+      # here). `SagaInterpreter`'s hook points call through
+      # `saga_persistence(domain)` unconditionally; this is what makes
+      # that safe without a `respond_to?` check at every call site,
+      # mirroring the same optional-capability shape
+      # `Ports::Persistence::AppendOnly` already gives adapters that
+      # don't implement `reset!`/`events`/`record_event`.
+      class NullSagaStore
+        def save_saga(**) = nil
+        def delete_saga(**) = nil
+        def each_saga(*) = nil
+      end
+
+      NULL_SAGA_STORE = NullSagaStore.new
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+module Hecks
+  module Ports
+    module Persistence
+      # A tiny, real seam — ADR 0033. Core never names a persistence plugin;
+      # a plugin makes itself known as a side effect of being `require`d, the
+      # same way an adapter's own `.rb` file already registers itself
+      # (`Runtime::Registry#add_adapter`) rather than core listing adapter
+      # names anywhere. `register_plugin` is the ENTIRE contract a plugin
+      # must satisfy: anything responding to `contribute_boot_gates(registry,
+      # gates)` (a no-op is a valid implementation).
+      #
+      # This is deliberately NOT the same registry `Hecks::Projector` uses
+      # (ADR 0027) or `Runtime::BootGates` (ADR 0031) — each of those is
+      # scoped to its own seam (IR-in/artifact-out; per-boot phased gates).
+      # A shared base is deferred until a third registry actually wants one.
+      #
+      # NAME-KEYED, PROCESS-WIDE, NOT PER-BOOT — unlike `BootGates` (one
+      # instance per `Loader.boot` call, because gate REGISTRATION is
+      # capability-conditional per registry), a persistence plugin is either
+      # `require`d into this process or it isn't; there is no "this boot's
+      # registry doesn't need it" case to isolate against, so a plain
+      # module-level hash is the right shape here, not an instantiable class.
+      module Plugin
+        @plugins = {}
+
+        class << self
+          def register(name, plugin)
+            @plugins[name.to_sym] = plugin
+          end
+
+          def registered?(name)
+            @plugins.key?(name.to_sym)
+          end
+
+          def each(&)
+            @plugins.each_value(&)
+          end
+
+          def any? = !@plugins.empty?
+        end
+      end
+
+      # `Ports::Persistence.plugin?(:era)` / `.each_plugin` — the ordinary
+      # call surface; `Plugin.register`/`.registered?`/`.each` stay reachable
+      # directly for a plugin's own file to call at require-time.
+      module_function
+
+      def register_plugin(name, plugin) = Plugin.register(name, plugin)
+      def plugin?(name) = Plugin.registered?(name)
+      def each_plugin(&) = Plugin.each(&)
+      def plugins_loaded? = Plugin.any?
+    end
+  end
+end