hecks 2.8.0 → 3.0.0

data/lib/hecks/persistence_legacy_fixture/regenerate.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "tmpdir"
+
+module Hecks
+  module PersistenceLegacyFixture
+    # Regenerates the persistence legacy fixtures by writing the seed records through the real
+    # adapters: Heki, SQLite, D1, Postgres and PostgresEra. It needs a reachable Postgres (which
+    # scratch databases are made in) and the `sqlite3` program (which dumps the SQLite database).
+    #
+    # The fixtures are the baseline later adapters are compared with, so a caller confirms before
+    # this is run, and it is not re-run once adapters write through the state codec: it would
+    # overwrite the baseline.
+    class Regenerate
+      # The scratch database each Postgres-backed store is written to.
+      SCRATCH = {
+        postgres:     "hecks_persistence_legacy_postgres",
+        postgres_era: "hecks_persistence_legacy_postgres_era"
+      }.freeze
+
+      # Raised when a fixture cannot be written.
+      class Failure < StandardError; end
+
+      # Rewrites every fixture set.
+      #
+      # @param dir [String] where the fixtures stand
+      # @return [String] `wrote <dir>`
+      # @raise [Failure] when the `sqlite3` dump fails
+      def self.call(dir: PersistenceLegacyFixture::DIR)
+        new(dir).call
+      end
+
+      # @param dir [String] where the fixtures stand
+      def initialize(dir)
+        @dir = dir
+      end
+
+      # @return [String] `wrote <dir>`
+      def call
+        require "hecks/ports/persistence/plugins/era"
+        require "pg"
+        instances = PersistenceLegacyFixture.instances
+        write_heki(instances)
+        write_sqlite(instances)
+        write_d1(instances)
+        with_scratch_databases do
+          write_postgres(instances)
+          write_postgres_era(instances)
+        end
+        "wrote #{@dir}"
+      end
+
+      private
+
+      def reset_dir(name)
+        dir = File.join(@dir, name)
+        FileUtils.rm_rf(dir)
+        FileUtils.mkdir_p(dir)
+        dir
+      end
+
+      def write_json(relative, value)
+        File.write(File.join(@dir, relative), "#{JSON.pretty_generate(value)}\n")
+      end
+
+      def with_scratch_databases
+        admin = PG.connect(dbname: "postgres")
+        admin.exec("SET client_min_messages = warning")
+        SCRATCH.each_value do |name|
+          admin.exec("DROP DATABASE IF EXISTS #{name} WITH (FORCE)")
+          admin.exec("CREATE DATABASE #{name}")
+        end
+        yield
+      ensure
+        SCRATCH.each_value { |name| admin&.exec("DROP DATABASE IF EXISTS #{name} WITH (FORCE)") }
+        admin&.close
+      end
+
+      def write_heki(instances)
+        out = reset_dir("heki")
+        Dir.mktmpdir("hecks-legacy-heki-") do |tmp|
+          instances.each do |instance|
+            Hecks::Adapters::Heki.new(aggregate: instance.aggregate, settings: { dir: "." }, root: tmp).save(instance)
+            %w[heki heki.journal].each do |ext|
+              FileUtils.cp(File.join(tmp, "#{instance.aggregate.storage_name}.#{ext}"), out)
+            end
+          end
+        end
+      end
+
+      def write_sqlite(instances)
+        out = reset_dir("sqlite")
+        Dir.mktmpdir("hecks-legacy-sqlite-") do |tmp|
+          instances.each do |instance|
+            Hecks::Adapters::Sqlite.new(aggregate: instance.aggregate, settings: { database: "banking.sqlite3" },
+                                        root: tmp).save(instance)
+          end
+          dump, status = Open3.capture2("sqlite3", File.join(tmp, "banking.sqlite3"), ".dump")
+          raise Failure, "sqlite3 .dump failed" unless status.success?
+
+          File.write(File.join(out, "banking.sql"), dump)
+        end
+      end
+
+      def write_d1(instances)
+        reset_dir("d1")
+        connection = PersistenceLegacyFixture.fake_d1_connection
+        tables = instances.flat_map do |instance|
+          PersistenceLegacyFixture.with_d1_connection(connection) do
+            Hecks::Adapters::D1.new(aggregate: instance.aggregate,
+                                    settings:  { account_id: "acc", database_id: "db", api_token: "tok" }).save(instance)
+          end
+          [instance.aggregate.storage_name, "#{instance.aggregate.storage_name}_entries"]
+        end
+        write_json("d1/rows.json",
+                   tables.to_h { |table| [table, connection.execute(%(SELECT * FROM "#{table}" ORDER BY rowid))] })
+      end
+
+      def write_postgres(instances)
+        reset_dir("postgres")
+        rows = instances.to_h do |instance|
+          adapter = Hecks::Adapters::Postgres.new(aggregate: instance.aggregate, settings: { database: SCRATCH[:postgres] })
+          adapter.save(instance)
+          db = adapter.instance_variable_get(:@db)
+          table = PG::Connection.quote_ident(instance.aggregate.storage_name)
+          entries = PG::Connection.quote_ident("#{instance.aggregate.storage_name}_entries")
+          [instance.aggregate.storage_name, {
+            "head"    => db.exec("SELECT * FROM #{table} ORDER BY id").to_a,
+            "entries" => db.exec("SELECT aggregate_id, operation, state, mirrors FROM #{entries} ORDER BY sequence").to_a
+          }]
+        end
+        write_json("postgres/rows.json", rows)
+      end
+
+      def write_postgres_era(instances)
+        reset_dir("postgres_era")
+        rows = instances.to_h { |instance| [instance.aggregate.storage_name, era_rows(instance)] }
+        write_json("postgres_era/rows.json", rows)
+      end
+
+      def era_rows(instance)
+        adapter = Hecks::Adapters::PostgresEra.new(aggregate: instance.aggregate,
+                                                   settings:  { database: SCRATCH[:postgres_era] })
+        adapter.save(instance)
+        db = adapter.instance_variable_get(:@db)
+        journal = adapter.instance_variable_get(:@lineage).quoted_journal
+        snapshot = adapter.send(:quoted_head_snapshot)
+        {
+          "journal"       => db.exec_params(
+            "SELECT ordinal, era, aggregate, aggregate_id, operation, state, mirrors FROM #{journal} " \
+            "WHERE aggregate = $1 ORDER BY ordinal", [instance.aggregate.storage_name]
+          ).to_a,
+          "head_snapshot" => db.exec("SELECT id, ordinal, operation, state FROM #{snapshot} ORDER BY id").to_a
+        }
+      end
+    end
+  end
+end

data/lib/hecks/persistence_legacy_fixture.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+require "hecks"
+require "fileutils"
+
+module Hecks
+  # The seed records of `spec/fixtures/persistence_legacy/`, over `examples/banking`, and the
+  # regeneration of those fixtures through the real adapters.
+  #
+  # Banking's IR only: no hecksagon, no boot; adapters are built straight from `aggregate:`.
+  module PersistenceLegacyFixture
+    # The gem's root directory.
+    ROOT = File.expand_path("../..", __dir__)
+    # Where the fixtures stand in a checkout.
+    DIR  = File.join(ROOT, "spec/fixtures/persistence_legacy").freeze
+
+    # Each seed: aggregate name, id and field values.
+    SEEDS = [
+      [
+        "Account", "ACC-1",
+        {
+          number:          { value: "ACC-1" },
+          customer:        "CUST-1",
+          balance:         { cents: 1250, currency: "USD" },
+          kind:            { name: "current" },
+          daily_limit:     { cents: 500 },
+          ledger:          [
+            { sequence: { value: 1 }, amount: { cents: 1000, currency: "USD" }, narrative: { text: "opening" },
+              direction: { value: "credit" }, state: "posted" },
+            { sequence: { value: 2 }, amount: { cents: 250, currency: "USD" }, narrative: { text: "top up" },
+              direction: { value: "credit" }, state: "reversed" }
+          ],
+          status:          "open",
+          customer_status: "active"
+        }
+      ],
+      [
+        "CardPayment", "AUTH-1",
+        {
+          authorisation:  { value: "AUTH-1" },
+          account:        "ACC-1",
+          amount:         { cents: 300 },
+          merchant:       { value: "Cafe" },
+          tags:           [{ value: "food" }, { value: "travel" }],
+          status:         "authorized",
+          account_status: "open"
+        }
+      ]
+    ].freeze
+
+    module_function
+
+    # @return [Hecks::Bluebook::Structure::Domain] banking's bluebook, loaded once
+    def bluebook
+      @bluebook ||= begin
+        registry = Hecks::Runtime::Registry.new
+        Hecks.with_registry(registry) do
+          Kernel.load(File.join(ROOT, "lib/hecks/ports/persistence.port"))
+          Kernel.load(File.join(ROOT, "lib/hecks/ports/extraction.port"))
+          Kernel.load(File.join(ROOT, "lib/hecks/adapters/driven/prism.adapter"))
+          folder = Hecks::Adapters::Folder.new
+          folder.load_bluebooks(folder.bluebook_directory(File.join(ROOT, "examples/banking/bluebook")))
+        end
+        registry.bluebook("Banking")
+      end
+    end
+
+    # @param name [String] an aggregate of banking
+    # @return [Object] its definition
+    def aggregate(name) = bluebook.aggregate(name)
+
+    # @return [Array<Hecks::Runtime::Instance>] one instance for each seed
+    def instances
+      SEEDS.map do |name, id, fields|
+        aggregate = aggregate(name)
+        instance = Hecks::Runtime::Instance.new(aggregate: aggregate, id: id)
+        fields.each { |field, value| instance[field] = Hecks::Runtime::Value.for(aggregate, field, value) }
+        instance
+      end
+    end
+
+    # In-memory SQLite answering `Connection`'s four methods, as `d1_spec.rb` does.
+    #
+    # @return [Object] the connection
+    def fake_d1_connection
+      require "sqlite3"
+      db = SQLite3::Database.new(":memory:")
+      db.results_as_hash = true
+      Class.new do
+        def initialize(db) = @db = db
+        def execute(sql, binds = []) = @db.execute(sql, binds)
+        def get_first_row(sql, binds = []) = execute(sql, binds).first
+        def get_first_value(sql, binds = []) = get_first_row(sql, binds)&.values&.first
+      end.new(db)
+    end
+
+    # Makes `D1::Connection.new` answer `connection` for the length of the block.
+    #
+    # @param connection [Object] the connection to answer
+    # @yield the work that builds a D1 adapter
+    # @return [Object] the block's value
+    def with_d1_connection(connection)
+      klass = Hecks::Adapters::D1::Connection
+      klass.define_singleton_method(:new) { |**| connection }
+      yield
+    ensure
+      klass.singleton_class.send(:remove_method, :new) if klass.singleton_class.method_defined?(:new, false)
+    end
+  end
+end
+
+require_relative "persistence_legacy_fixture/regenerate"

data/lib/hecks/ports/access_control.rb

@@ -2,22 +2,9 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # Who can sign in, and what role do they hold — the domain-specific
-    # half of sign-in `Ports::Authentication` deliberately stays out of
-    # (see that port's own header: it only ever talks to the external
-    # provider, never this registry's own data). Resolved the same way
-    # every other port here resolves its adapter: one adapter
-    # registry-wide answers this, since an app has no reason to want a
-    # different "who's allowed in" source per aggregate.
-    #
-    # Every domain shapes this differently — who its own "a person who
-    # can sign in" aggregate is, what admits them, what grants them
-    # access — so this port is pure delegation, same as every sibling
-    # port. The one piece of this that is generic (a live Governance
-    # grant should win over whatever an aggregate's own role field
-    # says) lives on `Ports::Authorization#live_role_for` instead —
-    # a domain's adapter here calls that directly, rather than this
-    # port re-deriving Governance-query logic another port already owns.
+    # Who can sign in and what role they hold: the domain-specific half of sign-in.
+    # Pure delegation to the one adapter bound registry-wide; adapters that need a
+    # live Governance grant call `Ports::Authorization#live_role_for`.
     module AccessControl
       NAME = "access_control".freeze
 
@@ -39,16 +26,13 @@ module Hecks
 
       # Admits a new person, in whatever way this domain's adapter defines admission.
       #
-      # The keywords carry the names of a verified sign-in (`Ports::Authentication.verify`
-      # answers `issuer`, `subject` and `email`), but nothing in this repository wires the
-      # two together, so their shapes here are adapter-defined.
+      # The keywords carry the names of a verified sign-in (`Ports::Authentication.verify`),
+      # but nothing here wires the two together, so their shapes are adapter-defined.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param email [Object] adapter-defined, forwarded unchanged; the person's email
-      # @param issuer [Object] adapter-defined, forwarded unchanged; the OIDC issuer that
-      #   authenticated the person
-      # @param subject [Object] adapter-defined, forwarded unchanged; the OIDC subject the
-      #   issuer vouches for
+      # @param issuer [Object] adapter-defined, forwarded unchanged; the OIDC issuer
+      # @param subject [Object] adapter-defined, forwarded unchanged; the OIDC subject
       # @return [Object] adapter-defined representation of the newly admitted person
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
       #   (see `adapter`)

data/lib/hecks/ports/agent/answers.rb

@@ -1,18 +1,8 @@
 module Hecks
   module Ports
     module Agent
-      # Where a raw hash becomes a struct — the one place, so every
-      # adapter (the real `claude_code` one, and any scripted double
-      # standing in for it in a spec) is held to the identical shape.
-      # An adapter's whole job ends at "here is what came back, already
-      # JSON"; whether that hash is usable is decided once, here, not
-      # re-decided per adapter.
-      #
-      # Every failure raises `ValidationError` — never lets a bare
-      # `NoMethodError` on nil, or a `KeyError`, reach a caller looking
-      # for an agent-shaped failure. `bin/interview` catches exactly one
-      # class for "the model answered badly," not a grab-bag of Ruby's
-      # own.
+      # Turns an adapter's raw reply hash into structs, so every adapter is held to
+      # one shape. Every failure raises `ValidationError`, never a bare `NoMethodError`.
       module Answers
         VERB_PATTERN = /\A[A-Za-z]+::[A-Za-z]+\.[A-Za-z]+\z/
 
@@ -77,8 +67,6 @@ module Hecks
           end
         end
 
-        # ── shared checks, each named for what it refuses ───────────────
-
         # Reads the array of rows an answer holds under one key, refusing any other shape.
         #
         # @param raw [Object] the adapter's reply; only a Hash is accepted
@@ -111,12 +99,8 @@ module Hecks
 
         # Reads a proposal row's verb, refusing one that is not fully qualified.
         #
-        # A verb the language could not even parse is an adapter fault,
-        # refused right here — the same `not_fully_qualified` shape the
-        # language's own grammar already refuses by, reused rather than
-        # reinvented. A verb naming a real category that turns out to
-        # describe the wrong fact is not this port's business: that one
-        # dispatches, and `Interview::Session#offer` is what says no.
+        # Only the shape is checked; whether the verb fits the fact is
+        # `Interview::Session#offer`'s call.
         #
         # @param row [Hash{String => Object}] one proposal row of the adapter's answer
         # @return [String] the row's `"verb"`, shaped `Chapter::Aggregate.Command`
@@ -157,9 +141,7 @@ module Hecks
 
         # Normalises a proposal row's arguments into symbol-keyed, all-String rows.
         #
-        # Rows shaped exactly as `Interview::Proposal::Argument` — a
-        # reference's `field` is legitimately blank (a reference is an
-        # id), so only `name` is required here.
+        # Only `name` is required: a reference's `field` is legitimately blank.
         #
         # @param row [Hash{String => Object}] one proposal row of the adapter's answer
         # @return [Array<Hash{Symbol => String}>] one `{name:, field:, value:}` Hash per