hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,306 @@
+require "json"
+require "fileutils"
+
+require_relative "sql_query_builder"
+require_relative "sqlite/schema_builder"
+require_relative "sqlite/codec"
+require_relative "../../ports/persistence/append_only"
+require_relative "../../query_specification/common/null_policy"
+require_relative "../../query_specification/common/order_by"
+require_relative "../../runtime/errors"
+require_relative "../../runtime/event"
+require_relative "../../runtime/instance"
+
+module Hecks
+  module Adapters
+    # The SQLite store: one table per aggregate head, an append-only entry
+    # table beside it. The DDL lives in sqlite/schema_builder.rb, the
+    # column codec in sqlite/codec.rb, and the query compilation is the
+    # shared SqlQueryBuilder — this file supplies only SQLite's dialect.
+    class Sqlite
+      include SqlQueryBuilder
+      include SchemaBuilder
+      include Codec
+
+      SQL_TYPES = { "Integer" => "INTEGER", "Float" => "REAL" }.freeze
+
+      attr_reader :aggregate, :path
+
+      def persistence_capabilities = [:atomic_put]
+
+      def initialize(aggregate:, settings: {}, root: nil)
+        # LAZY, ON PURPOSE — a domain that never wires Sqlite should never
+        # need the gem installed. `require "hecks"` alone must not
+        # force a database client library nobody asked for.
+        require "sqlite3"
+
+        @aggregate = aggregate
+        @path      = resolve_path(settings, root)
+        # THE OPTIONAL saga-persistence capability's own scoping column
+        # (§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))
+        @db = SQLite3::Database.new(@path)
+        @db.results_as_hash = true
+        # The append is the recovery commit point. Keep SQLite's fsync policy
+        # explicit instead of inheriting a process-wide pragma choice.
+        @db.execute("PRAGMA synchronous = FULL")
+
+        create_aggregate_table!
+        create_entry_table!
+        ensure_entry_operation_column!
+        ensure_entry_mirrors_column!
+        create_event_table!
+        create_saga_table!
+      end
+
+      def table = @aggregate.storage_name
+
+      def find(id)
+        row = @db.get_first_row("SELECT * FROM #{quoted_table} WHERE id = ?", [id.to_s])
+        return nil unless row
+
+        Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
+      end
+
+      # order_by IS A RUNTIME VALUE — see postgres.rb's own all for the
+      # full reasoning; whitelisted the identical way before it ever
+      # reaches order_expression.
+      def all(order_by: nil, direction: :asc)
+        order_sql = "ORDER BY id"
+        if 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)
+
+          spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
+          order_sql = "ORDER BY #{order_clause(spec, nil)}"
+        end
+
+        @db.execute("SELECT * FROM #{quoted_table} #{order_sql}").map do |row|
+          Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
+        end
+      end
+
+      def count = @db.get_first_value("SELECT COUNT(*) FROM #{quoted_table}").to_i
+
+      def append(entry)
+        @db.execute(
+          "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
+          # `mirrors` (unlike `state`) is a NULLABLE column — an absent
+          # mirrors hash must bind a real SQL NULL, not the four-character
+          # JSON text `"null"` (`JSON.generate(nil)`), or a future `IS NULL`
+          # check against it would never match. Same guard `postgres_era.rb`
+          # already uses for its own journal's `mirrors` column.
+          [entry.id, entry.operation, JSON.generate(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
+        )
+        entry
+      end
+
+      def project(entry)
+        return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
+
+        instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
+        columns = (["id"] + persisted_fields.map { |field| field[:name].to_s }).map { |c| quote_ident(c) }
+        values  = [instance.id.to_s] + persisted_fields.map { |field| encode_field(field, instance[field[:name]]) }
+        slots   = Array.new(columns.size, "?").join(", ")
+
+        @db.execute(
+          "INSERT OR REPLACE INTO #{quoted_table} (#{columns.join(', ')}) VALUES (#{slots})",
+          values
+        )
+        instance
+      end
+
+      def entries
+        @db.execute("SELECT aggregate_id, operation, state, mirrors FROM #{quoted_entry_table} ORDER BY sequence").map do |row|
+          state = JSON.parse(row["state"])
+          Ports::Persistence::Entry.new(
+            operation: row["operation"] || "save",
+            id:        row["aggregate_id"],
+            state:     state&.transform_keys(&:to_sym),
+            mirrors:   row["mirrors"] && JSON.parse(row["mirrors"])
+          )
+        end
+      end
+
+      def reset!
+        @db.execute("DELETE FROM #{quoted_table}")
+        @db.execute("DELETE FROM #{quoted_entry_table}")
+        self
+      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
+
+      # The outcome lookup, journal append and snapshot replacement share one
+      # SQLite transaction. The runtime performs no preliminary find; this
+      # adapter-native operation owns both concurrency and outcome reporting.
+      def atomic_put(entry, insert_only: false)
+        status = nil
+        @db.transaction do
+          exists = !@db.get_first_value("SELECT 1 FROM #{quoted_table} WHERE id = ?", [entry.id.to_s]).nil?
+          if insert_only && exists
+            status = :conflicted
+            next
+          end
+          status = exists ? :replaced : :inserted
+          append(entry)
+          project(entry)
+        end
+        status
+      end
+
+      def delete(id)
+        entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
+        append(entry)
+        project(entry)
+        true
+      end
+
+      def record_event(event)
+        @db.execute(
+          "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES (?, ?, ?, ?, ?)",
+          [event.name, event.aggregate, event.id.to_s, JSON.generate(event.payload), event.occurred_at]
+        )
+      end
+
+      def events
+        @db.execute("SELECT * FROM events ORDER BY id").map do |row|
+          Runtime::Event.new(
+            name:        row["name"],
+            aggregate:   row["aggregate"],
+            id:          row["aggregate_id"],
+            payload:     JSON.parse(row["payload"], symbolize_names: true),
+            occurred_at: row["occurred_at"]
+          )
+        end
+      end
+
+      # ── the OPTIONAL saga-persistence capability (§2) — reuses the
+      # DDL every SQLite-backed aggregate table already lives beside
+      # (`create_saga_table!`, `Sqlite::SchemaBuilder`, shared with D1).
+      # SQLite's `resolve_path` defaults to one `.db` file PER
+      # AGGREGATE unless a domain shares one `database` setting across
+      # its aggregates — since saga persistence resolves through
+      # whichever adapter instance backs the domain's FIRST aggregate
+      # (`Registry#saga_persistence`), this table ends up living inside
+      # THAT one aggregate's own file by default. Correct and durable
+      # either way; a domain that wants an obviously-named saga store
+      # already gets one by sharing `database` across its aggregates,
+      # the recommended, common case.
+      def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
+        @db.execute(
+          "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
+          "VALUES (?, ?, ?, ?, ?, ?)",
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
+        )
+      end
+
+      def delete_saga(process_manager:, correlation:)
+        @db.execute(
+          "DELETE FROM hecks_saga_instances WHERE domain = ? AND process_manager = ? AND correlation = ?",
+          [@domain, process_manager.to_s, correlation.to_s]
+        )
+      end
+
+      def each_saga
+        return enum_for(:each_saga) unless block_given?
+
+        @db.execute(
+          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = ?",
+          [@domain]
+        ).each do |row|
+          yield row["process_manager"], row["correlation"], row["state"],
+                JSON.parse(row["memory"], symbolize_names: true),
+                JSON.parse(row["completed_compensations"] || "[]", symbolize_names: true)
+        end
+      end
+
+      private
+
+      # ── SqlQueryBuilder's dialect hooks ─────────────────────────────
+
+      def select_list = "*"
+      def from_relation = quoted_table
+      def dialect_name = "SQLite"
+      def empty_in_clause = "0"
+
+      def placeholder(binds, value)
+        binds << value
+        "?"
+      end
+
+      def contains_clause(expression, placeholder)
+        "instr(#{expression}, #{placeholder}) > 0"
+      end
+
+      def list_contains_clause(column, member, placeholder)
+        target = member.empty? ? "json_each.value" : "json_extract(json_each.value, '$.#{member}')"
+        "EXISTS (SELECT 1 FROM json_each(#{quote_ident(column)}) WHERE #{target} = #{placeholder})"
+      end
+
+      def plain_column(name) = quote_ident(name)
+
+      def nested_expression(name, path, member)
+        json_path = path.empty? ? "$.#{member || 'value'}" : "$.#{path.join('.')}"
+        "json_extract(#{quote_ident(name)}, '#{json_path}')"
+      end
+
+      # SQLite has no bare OFFSET — LIMIT -1 is its own documented
+      # unbounded spelling, exactly for this case.
+      def unbounded_limit = " LIMIT -1"
+
+      def order_clause(order_by, policy)
+        QuerySpecification::Common::NullPolicy.sql_order(query_expression(order_by.field), order_by.direction, policy)
+      end
+
+      def execute_query(sql, binds)
+        @db.execute(sql, binds).map { |row| Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row)) }
+      end
+
+      # ── the rest of the dialect ─────────────────────────────────────
+
+      def quote_ident(name)
+        %("#{name.to_s.gsub('"', '""')}")
+      end
+
+      def quoted_table = quote_ident(table)
+      def entry_table = "#{table}_entries"
+      def quoted_entry_table = quote_ident(entry_table)
+
+      def resolve_path(settings, root)
+        declared =
+          if settings.key?(:database)
+            settings[:database]
+          elsif settings.key?("database")
+            settings["database"]
+          else
+            "data/#{table}.db"
+          end
+        return declared if declared.start_with?("/")
+
+        File.join(root || Dir.pwd, declared)
+      end
+    end
+
+    # Port-specific bindings share SQLite's storage mechanics but advertise
+    # only one operational contract each.
+    class SqlitePersistence < Sqlite; end
+  end
+end
+
+require_relative "sqlite/projection"

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

@@ -0,0 +1,3 @@
+Hecks.adapter "SystemClock" do
+  port "clock"
+end

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

@@ -0,0 +1,14 @@
+module Hecks
+  module Adapters
+    # The real `clock` fulfillment — the machine's own time, in seconds.
+    #
+    # Whole seconds on purpose. The sublanguage does integer arithmetic, a
+    # staleness window is measured in minutes, and sub-second precision in a
+    # durable ledger is precision nobody reads and every diff has to ignore.
+    module SystemClock
+      module_function
+
+      def now = Time.now.to_i
+    end
+  end
+end

data/lib/hecks/adapters/driven.rb

@@ -0,0 +1,54 @@
+module Hecks
+  module Adapters
+    # The driven side — every store or reader an adapter declaration can
+    # bind. A small adapter is one file beside this one; sqlite, postgres
+    # and heki keep a directory for their supporting cast. Each `.adapter`
+    # file alongside is the DSL declaration the grammar bootstrap and the
+    # Folder adapter load as data.
+  end
+end
+
+require_relative "driven/memory"
+require_relative "driven/sqlite"
+require_relative "driven/postgres"
+# `PostgresEra` is NOT `require_relative`d here — ADR 0033 moved it, and
+# the rest of the era/lineage/translation subsystem, behind a loadable
+# persistence plugin (`hecks/ports/persistence/plugins/era`) rather than
+# requiring every app to carry it whether or not anything ever binds
+# `persisted_by "PostgresEra"`. `Module#autoload` is the one-line seam
+# that makes that genuinely load-nothing-until-asked instead of pushing
+# an explicit `require` onto every one of the ~15 generic `bin/*` tools
+# that boot an arbitrary checked-in domain (several of which — pizzas,
+# compliance, chess, roster — bind PostgresEra): the FIRST real
+# `Adapters.const_get("PostgresEra")` (`registry/verification.rb`'s own
+# adapter resolution, unchanged) transparently `require`s the plugin
+# entry point, which defines the constant AND calls `register_plugin`
+# as its own side effect (`plugins/era.rb`'s last line) — the exact
+# same effect an explicit `require "hecks/ports/persistence/plugins/
+# era"` has, just deferred to the moment something is actually asked
+# for `PostgresEra` rather than sprinkled across every caller that
+# might. A domain that never binds it never triggers the autoload, so
+# never loads a line of era code — unchanged from ADR 0033's own goal.
+Hecks::Adapters.autoload(:PostgresEra, "hecks/ports/persistence/plugins/era")
+require_relative "driven/lambda"
+require_relative "driven/heki"
+require_relative "driven/prism"
+require_relative "driven/folder"
+require_relative "driven/d1"
+require_relative "driven/mock_stripe_adapter"
+require_relative "driven/secure_random_identity"
+require_relative "driven/system_clock"
+# `SequentialIdentity` — the deterministic identity_generation test
+# double — is NOT required here on purpose. It lives at
+# spec/fixtures/sequential_identity.{adapter,rb}, loaded explicitly by
+# whichever spec wants it: this file's `require_relative` list is what
+# `Folder#load_library`'s `.adapter` glob backs, and `.adapter` DSL
+# declarations register into every registry any real `Hecks.boot` ever
+# builds. Two adapters answering `identity_generation` unconditionally
+# would make the port permanently ambiguous — `Ports::IdentityGeneration
+# .adapter` refuses to choose between more than one — for every
+# consumer, forever, not just specs that want the deterministic one.
+require_relative "driven/governance_authorization"
+require_relative "driven/identity_registry"
+require_relative "driven/google_authentication"
+require_relative "driven/claude_code"

data/lib/hecks/adapters.rb

@@ -0,0 +1,6 @@
+module Hecks
+  module Adapters
+  end
+end
+
+require_relative "adapters/driven"

data/lib/hecks/behaviors/dsl.rb

@@ -0,0 +1,125 @@
+require_relative "ir"
+
+# The authoring surface for `Hecks.behaviors "Name" do ... end` — one
+# `test "description" do ... end` block per case, `tests`/`setup`/`input`/
+# `expect` inside. `instance_eval`-based, the same shape every other
+# hecks DSL builder uses (`WorldBuilder`, `HecksagonBuilder`).
+module Hecks
+  module Behaviors
+    # Raised at `Hecks.behaviors` build time — a missing `vision` or
+    # `loads` line names the fix directly rather than failing later, deep
+    # inside a boot, over a suite that was never going to be scoped.
+    class Malformed < StandardError; end
+
+    class TestCaseBuilder
+      def initialize(description)
+        @description   = description
+        @tests_command = nil
+        @on_aggregate  = nil
+        @kind          = :command
+        @setups        = []
+        @input         = {}
+        @expect        = {}
+      end
+
+      def tests(command, on: nil, kind: :command)
+        @tests_command = command
+        @on_aggregate  = on
+        @kind          = kind
+      end
+
+      def setup(command, **kwargs)
+        @setups << TestSetup.new(command: command, args: kwargs)
+      end
+
+      def input(**kwargs)  = @input.merge!(kwargs)
+      def expect(**kwargs) = @expect.merge!(kwargs)
+
+      def build
+        unless @tests_command
+          raise Malformed, "test #{@description.inspect} never calls `tests` — " \
+                           "say which command or query this example exercises"
+        end
+
+        validate_expect!
+
+        TestCase.new(description: @description, tests_command: @tests_command,
+                     on_aggregate: @on_aggregate, kind: @kind,
+                     setups: @setups, input: @input, expect: @expect)
+      end
+
+      private
+
+      # Closes the silent-pass paths a free-form `expect(**kwargs)` merge
+      # otherwise leaves open: a test with no `expect` at all asserts
+      # nothing and passes whenever dispatch doesn't raise; `count:` on a
+      # command and `emits:` on a query are each read by neither runner
+      # (Expectations#run_command/#run_query), so they're accepted here
+      # and then silently ignored at run time. Checking both at BUILD
+      # time, not in the runners, makes them errors on the file that
+      # wrote them rather than green checks nobody questions.
+      def validate_expect!
+        if @expect.empty?
+          raise Malformed, "test #{@description.inspect} has no `expect` — say what this " \
+                           "example proves (ok:, refused:, emits:, count:, or a field name)"
+        end
+
+        if @kind == :command && @expect.key?(:count)
+          raise Malformed, "test #{@description.inspect}: `expect count:` only applies to " \
+                           "queries — a command has no row count to check"
+        end
+
+        if @kind == :query && @expect.key?(:emits)
+          raise Malformed, "test #{@description.inspect}: `expect emits:` only applies to " \
+                           "commands — a query never dispatches, so it never emits"
+        end
+      end
+    end
+
+    class BehaviorsBuilder
+      def initialize(name, source_path:)
+        @name        = name
+        @source_path = source_path
+        @source_dir  = File.dirname(source_path)
+        @vision      = nil
+        @loads       = nil
+        @tests       = []
+      end
+
+      def vision(text) = @vision = text
+
+      # Relative to THIS `.behaviors` file, never to the filesystem's cwd
+      # or a same-stem convention — scope is a fact this file declares,
+      # not one a runner infers.
+      def loads(*paths)
+        @loads = paths.map { |path| File.expand_path(path, @source_dir) }
+      end
+
+      def test(description, &block)
+        builder = TestCaseBuilder.new(description)
+        builder.instance_eval(&block) if block
+        @tests << builder.build
+      end
+
+      def build
+        unless @vision
+          raise Malformed, "#{@source_path}: no `vision \"...\"` — say in one line " \
+                           "what this suite is examples of"
+        end
+        unless @loads
+          raise Malformed, "#{@source_path}: no `loads \"...\"` — a behaviors file " \
+                           "must declare exactly which files to boot"
+        end
+
+        BehaviorsSuite.new(name: @name, vision: @vision, loads: @loads,
+                           tests: @tests, path: @source_path)
+      end
+
+      def self.build(name, source_path:, &block)
+        builder = new(name, source_path: source_path)
+        builder.instance_eval(&block) if block
+        builder.build
+      end
+    end
+  end
+end