hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,199 @@
+require_relative "../../vocabulary"
+
+module Hecks
+  module Adapters
+    class Folder
+      DOMAIN_ORDER = Hecks::Vocabulary.fetch("LoadOrder")
+      PORTS        = "ports"
+      ADAPTERS     = "adapters"
+
+      def initialize(settings: {}, root: nil)
+        @settings = settings
+        @root     = root
+      end
+
+      def load_library
+        load_each(library(PORTS),    %w[*.port])
+        load_each(library(ADAPTERS), %w[*/*.adapter */*/*.adapter])
+      end
+
+      def load_project(root)
+        return unless root
+
+        load_each(File.join(root, PORTS),    %w[*.port */*.port])
+        load_each(File.join(root, ADAPTERS), %w[*.adapter */*.adapter */*/*.adapter])
+      end
+
+      # CHAPTERS FIRST, JUDGED ONCE, THEN EVERYTHING THAT READS THEM.
+      # A chapter may be split across files (the language's own grammar is
+      # nine), and judging file one before files two-through-nine exist
+      # refuses references that are perfectly well declared a file later —
+      # see MetaValidator.defer for the whole reasoning. DOMAIN_ORDER
+      # already places every `*.bluebook` ahead of hecksagons and worlds,
+      # so the window ends at the last chapter pattern rather than at a
+      # hand-written list this would otherwise have to keep in step.
+      # `environment:` — ONE MORE PAIR OF FILES, LOADED LAST, NOT A GLOB.
+      # RECOVERED, not new — see Runtime::Loader.boot's own comment for
+      # the provenance. A caller passing `Hecks.boot(path, environment:
+      # "production")` gets exactly `environments/production.hecksagon`
+      # and `environments/production.world` loaded, whichever exist (a
+      # missing one is a silent no-op — not every environment overrides
+      # both; see docs/implemented/guides/wiring.md's "Swapping wiring per
+      # environment" for the motivating case: swapping a driven adapter
+      # — e.g. a real payment gateway for a mock one, or a hosting
+      # layer's tenancy settings — without an `if`/`else` anywhere in
+      # the domain's own wiring). Never matched by `DOMAIN_ORDER`'s own
+      # globs (all non-recursive, none named `environments/*`), so this
+      # is the only thing that ever reaches them. Loaded as genuine
+      # `Hecks.hecksagon "SameDomain" do ... end` / `Hecks.world
+      # "SameDomain" do ... end` blocks — MERGED into the base file's
+      # own hecksagon/world (Registry#add_hecksagon / #add_world,
+      # concatenate/override rather than replace), so an overlay can
+      # rebind or add settings for anything the base file declared
+      # without needing to know what else the base file said.
+      def load_domain(directory, environment: nil)
+        boundary = DOMAIN_ORDER.rindex { |pattern| pattern.end_with?(".bluebook") }
+        if boundary
+          load_bluebooks(directory, DOMAIN_ORDER[0..boundary])
+          load_each(directory, DOMAIN_ORDER[(boundary + 1)..])
+        else
+          load_each(directory, DOMAIN_ORDER)
+        end
+
+        return unless environment
+
+        load_each(directory, [File.join("environments", "#{environment}.hecksagon")])
+        load_each(directory, [File.join("environments", "#{environment}.world")])
+      end
+
+      # EVERY BLUEBOOK IN A FOLDER IS ONE DECLARATION SET. Individual files
+      # remain organized in the domain expert's language; the folder is the
+      # unit callers load. Builders group declarations by the chapter name in
+      # each file, so a folder may hold more than one chapter without a catalog.
+      # Sorting makes source order deterministic while the deferred window keeps
+      # cross-file references from being judged against a partial chapter.
+      def load_bluebooks(directory, patterns = ["*.bluebook"])
+        Bluebook::MetaValidator.defer { load_each(directory, patterns) }
+        Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
+      end
+
+      # THE EXPLICIT-FILE SIBLING OF `load_domain` — for a caller that names
+      # its own exact files rather than a directory to glob (`Loader.boot_files`,
+      # behind `Hecks.boot_files`). No `Dir.glob`, no copying: every path here
+      # is a real file on disk, wherever it actually lives, loaded in place —
+      # a `.behaviors` file's `loads` scopes a boot this way specifically so a
+      # per-test boot never has to fake isolation by staging bluebooks into a
+      # tmpdir (see Loader.boot_files's own header for why that pattern is a
+      # hazard, not a convenience).
+      #
+      # ORDERED BY CATEGORY, NOT BY THE CALLER'S OWN LIST ORDER — same four
+      # groups `Vocabulary.fetch("LoadOrder")` walks a directory in
+      # (bluebook chapters, translations, hecksagons, worlds), because a
+      # hecksagon can reference a bluebook's own constants and must not load
+      # first regardless of which order a caller happened to write `loads
+      # "x.hecksagon", "x.bluebook"` in. Bluebook chapters are judged as one
+      # deferred group exactly like `load_domain` does, for the identical
+      # forward-reference reason (MetaValidator.defer's own header).
+      def load_selected(files, environment: nil)
+        bluebooks, rest = files.partition { |f| f.end_with?(".bluebook") }
+
+        if bluebooks.any?
+          Bluebook::MetaValidator.defer { bluebooks.sort.each { |f| Kernel.load(f) } }
+          Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
+        end
+
+        %w[.hecksagon .world].each do |ext|
+          rest.select { |f| f.end_with?(ext) }.sort.each { |f| Kernel.load(f) }
+        end
+
+        return unless environment
+
+        directory = File.dirname(files.first)
+        load_each(directory, [File.join("environments", "#{environment}.hecksagon")])
+        load_each(directory, [File.join("environments", "#{environment}.world")])
+      end
+
+      def load_each(directory, patterns)
+        return unless File.directory?(directory)
+
+        patterns.each do |pattern|
+          Dir[File.join(directory, pattern)].sort.each { |file| Kernel.load(file) }
+        end
+      end
+
+      def bluebook_directory(path)
+        expanded = File.expand_path(path)
+        nested   = File.join(expanded, "bluebook")
+
+        return nested   if File.directory?(nested)
+        return expanded if File.directory?(expanded)
+
+        raise Errno::ENOENT, "no such domain directory: #{path}"
+      end
+
+      # THE DOMAIN YOU ARE STANDING IN. Walks up from `from` — the way git
+      # finds `.git` — and answers the nearest directory a boot would accept,
+      # or nil if there is not one above you.
+      #
+      # MARKED BY A `.hecksagon`, NOT BY A `.bluebook`. Chapters are
+      # everywhere: era translations, the language's own self-hosted grammar,
+      # and `spec/fixtures`, which holds a dozen unrelated ones in a single
+      # directory. A `.hecksagon` is the file that says "this is a domain, and
+      # here is how its aggregates are stored", which is exactly the claim a
+      # caller is relying on when they omit the path.
+      #
+      # Both layouts, because `bluebook_directory` above accepts both: a
+      # domain directory holding a `bluebook/` subdirectory (every example in
+      # this corpus), or one holding the files directly.
+      # NORMALISED TO THE OUTER DIRECTORY. Standing in `examples/banking/bluebook`,
+      # the `.hecksagon` is right there, so a plain walk stops on the
+      # `bluebook/` directory itself. Both boot identically — `bluebook_directory`
+      # accepts either and `Loader.boot` takes `File.dirname` of what it gets,
+      # so the registry root comes out the same — but `examples/banking` is the
+      # directory a person names, and the one a `.world`'s `dir "data"` reads
+      # as relative to.
+      def domain_root(from = Dir.pwd)
+        found = nearest_domain(File.expand_path(from))
+        return nil unless found
+
+        parent = File.dirname(found)
+        File.basename(found) == "bluebook" && domain?(parent) ? parent : found
+      end
+
+      def nearest_domain(current)
+        loop do
+          return current if domain?(current)
+
+          parent = File.dirname(current)
+          return nil if parent == current
+
+          current = parent
+        end
+      end
+
+      def domain?(directory)
+        !Dir[File.join(directory, "*.hecksagon")].empty? ||
+          !Dir[File.join(directory, "bluebook", "*.hecksagon")].empty?
+      end
+
+      def shared_root(given, directory)
+        return File.expand_path(given) if given
+
+        current = directory
+        loop do
+          return current if File.directory?(File.join(current, PORTS)) ||
+                            File.directory?(File.join(current, ADAPTERS))
+
+          parent = File.dirname(current)
+          return nil if parent == current
+
+          current = parent
+        end
+      end
+
+      def library(folder)
+        File.expand_path("../../#{folder}", __dir__)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+Hecks.adapter "GoogleAuthentication" do
+  port "authentication"
+end

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

@@ -0,0 +1,100 @@
+require "securerandom"
+
+require_relative "../../ports/authentication"
+
+module Hecks
+  module Adapters
+    # GOOGLE'S OWN OIDC HANDSHAKE — the `authentication` port's one real
+    # implementation today, moved here from being hand-rolled per-app
+    # (an embryonaut_console `google_auth.rb` used to do exactly this;
+    # any hecks-based app gets Google sign-in for free now, the
+    # same "one adapter, reusable everywhere" value every other adapter
+    # in this directory already has).
+    #
+    # `oauth2` does ONLY the authorization-code exchange (no Rack
+    # middleware, no Omniauth strategy indirection) ; `google-id-token`
+    # does ONLY ID-token verification (signature checked against
+    # Google's real, rotating JWKS — real, maintained code, never
+    # hand-rolled here). Neither library decides what a verified
+    # (issuer, subject) MEANS — that's `Ports::IdentityResolution`'s
+    # job, called by whoever consumes this port's `verify`.
+    #
+    # LAZY REQUIRES, same reasoning `Postgres.connect_for` already
+    # holds itself to for `pg`: a domain that never binds
+    # `authentication` to this adapter should never need these gems
+    # installed. This FILE loads in every boot (driven.rb's own
+    # unconditional require_relative list) ; the GEMS load only where
+    # a real handshake actually happens.
+    #
+    # `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`/`GOOGLE_REDIRECT_URI` —
+    # no defaults, on purpose: a login mechanism silently
+    # half-configured is worse than one that refuses to boot at all.
+    module GoogleAuthentication
+      ISSUER = "https://accounts.google.com"
+
+      module_function
+
+      def client
+        require "oauth2"
+        OAuth2::Client.new(
+          ENV.fetch("GOOGLE_CLIENT_ID"), ENV.fetch("GOOGLE_CLIENT_SECRET"),
+          site:          "https://oauth2.googleapis.com",
+          authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
+          token_url:     "/token"
+        )
+      end
+
+      # The URL to send a browser to, carrying a fresh CSRF `state` the
+      # caller is responsible for stashing (a session, typically) and
+      # checking again in `verify`.
+      def authorization_url
+        state = SecureRandom.hex(24)
+        url = client.auth_code.authorize_url(
+          redirect_uri: ENV.fetch("GOOGLE_REDIRECT_URI"),
+          scope:        "openid email profile",
+          state:        state
+        )
+        [url, state]
+      end
+
+      # Exchanges `code` for tokens, verifies the returned ID token's
+      # signature and claims against Google's own JWKS, and confirms
+      # `state` matches what `authorization_url` handed out — a
+      # mismatch (or any failure in the exchange/verification itself)
+      # is a Ports::Authentication::ValidationError, never a
+      # silently-empty result. Returns
+      # {issuer:, subject:, email:, email_verified:} on success — never
+      # the raw token, never anything a caller would need to re-verify
+      # itself. `email_verified` rides along because a caller granting
+      # access off this email needs to know Google actually checked it.
+      def verify(code:, state:, expected_state:)
+        # BOTH GEMS, BEFORE ANYTHING ELSE — not staggered further down
+        # this method: the rescue clause below names GoogleIDToken
+        # ::ValidationError, and Ruby resolves that constant reference
+        # at the moment an exception is being matched, not at parse
+        # time. An OAuth2::Error raised before a later `require
+        # "google-id-token"` line ran would make the rescue clause
+        # itself blow up on an undefined constant, masking the real
+        # error. Requiring both up front means whichever one raises
+        # first, the constant is already there to catch it.
+        require "oauth2"
+        require "google-id-token"
+
+        unless state && expected_state && state == expected_state
+          raise Ports::Authentication::ValidationError, "state mismatch"
+        end
+
+        token = client.auth_code.get_token(code, redirect_uri: ENV.fetch("GOOGLE_REDIRECT_URI"))
+        id_token = token.params["id_token"] or raise Ports::Authentication::ValidationError, "no id_token in the response"
+
+        payload = GoogleIDToken::Validator.new.check(id_token, ENV.fetch("GOOGLE_CLIENT_ID"))
+        {
+          issuer: payload.fetch("iss"), subject: payload.fetch("sub"),
+          email: payload["email"], email_verified: [true, "true"].include?(payload["email_verified"])
+        }
+      rescue OAuth2::Error, GoogleIDToken::ValidationError => e
+        raise Ports::Authentication::ValidationError, e.message
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+Hecks.adapter "GovernanceAuthorization" do
+  port "authorization"
+end

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

@@ -0,0 +1,101 @@
+require "time"
+
+module Hecks
+  module Adapters
+    # THE `authorization` PORT, FULFILLED BY GOVERNANCE — same registry,
+    # same boot, so "ask Governance" is a dispatch against records
+    # already sitting in the store this adapter is handed, not a bridge
+    # to a second runtime. `Runtime::Dispatcher.new(registry)` is cheap
+    # to build fresh per call (`Registry#capability_graph`'s own
+    # neighbor, `#repository`, does the same kind of on-demand build) —
+    # nothing here holds one across calls, so there is no boot-order
+    # dependency on WHEN Governance's bluebook loads relative to this
+    # adapter, only that it has by the time `holds_role?` is called.
+    #
+    # AN ACTIVE ASSIGNMENT, not merely a historical one : `RoleAssignment`
+    # answers with every assignment an actor has ever held
+    # (`AssignmentsForActor`'s own description — "currently or
+    # historically") and leaves `ends_at` for the caller to read, the
+    # same deferral `Governance::RoleTransition.Allowed` makes for the
+    # same reason. This is that caller.
+    module GovernanceAuthorization
+      module_function
+
+      # `as_of` and `scope` are BOTH optional, same opt-in shape
+      # `refuse_role_mismatch` already gives `actor_id` itself — an
+      # unbound `as_of` skips the `starts_at` check and an unbound
+      # `scope` skips the `scope` check, exactly the behavior before
+      # either existed. Neither is fetched here: `as_of` arrives already
+      # resolved from `Ports::Clock.now`, called by the caller at the
+      # door, never by this adapter — see `Ports::Clock`'s own header
+      # for why the dispatch path must not consult the clock itself.
+      def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
+        rows = Runtime::Dispatcher.new(registry).query(
+          "Governance::RoleAssignment.AssignmentsForActor",
+          actor_id: { value: actor_id.to_s }
+        )
+
+        rows.any? do |row|
+          row[:role_name][:value] == role.to_s &&
+            row[:ends_at].nil? &&
+            in_scope?(row, scope) &&
+            started?(row, as_of)
+        end
+      end
+
+      # `scope` UNCHECKED WHEN NOT STATED, same as every other opt-in
+      # field here — a caller that never says which scope it is acting
+      # in gets the pre-scope behavior: any live assignment for the role
+      # authorizes, everywhere. A caller that does state one only
+      # authorizes against an assignment granted for THAT scope.
+      def in_scope?(row, scope)
+        scope.nil? || row[:scope][:value] == scope.to_s
+      end
+
+      # `starts_at` IS A FREE-TEXT STRING in the bluebook (`Timestamp`'s
+      # only invariant is "present", not any particular format) — parsed
+      # here with `Time.parse` rather than compared lexically, since
+      # nothing guarantees every caller writes it zero-padded ISO 8601.
+      # FAILS CLOSED : a `starts_at` that does not parse is treated as
+      # not-yet-started rather than silently ignored, the same direction
+      # every other check in this method already fails.
+      def started?(row, as_of)
+        return true if as_of.nil?
+
+        Time.parse(row[:starts_at][:value].to_s).to_i <= as_of
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      # THE OTHER HALF — may role X act as role Y. `RoleTransition.Allowed`
+      # is identified by the exact pair, so at most one row ever comes
+      # back ; still read as `.any?` rather than trusting that structurally,
+      # the same defensiveness `holds_role?` already has to have anyway
+      # since `AssignmentsForActor` can return several.
+      def authorized_as?(registry, from_role:, to_role:)
+        rows = Runtime::Dispatcher.new(registry).query(
+          "Governance::RoleTransition.Allowed",
+          from_role: { value: from_role.to_s }, to_role: { value: to_role.to_s }
+        )
+
+        rows.any? { |row| row[:ends_at].nil? }
+      end
+
+      # THE ROLE ITSELF, not just a yes/no about one — the same
+      # `AssignmentsForActor` query `holds_role?` runs, just returning
+      # the live (non-revoked) row's `role_name` instead of comparing it
+      # against a caller-supplied guess. `nil` for no live assignment at
+      # all — the caller's own fallback (an aggregate's own role field,
+      # a default) is domain-specific and does not belong here.
+      def live_role_for(registry, actor_id:)
+        rows = Runtime::Dispatcher.new(registry).query(
+          "Governance::RoleAssignment.AssignmentsForActor",
+          actor_id: { value: actor_id.to_s }
+        )
+
+        live = rows.find { |row| row[:ends_at].nil? }
+        live && live[:role_name][:value]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+require_relative "../../../ports/persistence/append_only"
+
+module Hecks
+  module Adapters
+    class Heki
+      # The append-only journal beside the snapshot: one JSON line per
+      # entry, fsynced on append, replayed over the snapshot on read.
+      module Journal
+        def entries
+          return [] unless File.exist?(@journal_path)
+
+          File.readlines(@journal_path, chomp: true).reject(&:empty?).map do |line|
+            value = JSON.parse(line)
+            state = value["state"]&.transform_keys(&:to_sym)
+            Ports::Persistence::Entry.new(operation: value.fetch("operation"), id: value.fetch("id"), state: state,
+                                          mirrors: value["mirrors"])
+          end
+        end
+
+        private
+
+        def replay_journal(records)
+          return records unless File.exist?(@journal_path)
+
+          File.foreach(@journal_path) do |line|
+            entry = JSON.parse(line)
+            id    = entry.fetch("id")
+
+            case entry.fetch("operation")
+            when "save"   then records[id] = entry.fetch("state")
+            when "delete" then records.delete(id)
+            else raise Malformed, "#{@journal_path}: unknown journal operation #{entry.fetch("operation").inspect}"
+            end
+          end
+          records
+        rescue JSON::ParserError => e
+          raise Malformed, "#{@journal_path}: json error: #{e.message}"
+        end
+
+        def append_entry(operation, id, state)
+          line = "#{JSON.generate(operation: operation, id: id.to_s, state: state, mirrors: @entry_mirrors)}\n"
+
+          # One write, not JSON-then-newline as two: two concurrent
+          # appends can only interleave *between* writes, never inside
+          # one, so this line can't come out split by another process's
+          # line landing in the middle of it.
+          File.open(@journal_path, "ab") do |journal|
+            journal.write(line)
+            journal.flush
+            journal.fsync
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+require_relative "snapshot"
+require_relative "journal"
+
+module Hecks
+  module Adapters
+    class Heki
+      # THE OPTIONAL saga-persistence capability (§2), Heki's own shape —
+      # a SIBLING snapshot+journal file pair, built the exact same way an
+      # aggregate's own persistence already is: `Snapshot`/`Journal`
+      # (heki/snapshot.rb, heki/journal.rb) operate generically on
+      # `@path`/`@journal_path`/`@entry_mirrors` and never touch
+      # `@aggregate`, so this reuses them unchanged rather than
+      # re-deriving the same binary framing and crash-recovery replay.
+      #
+      # Reserved file name (`hecks_saga_instances.heki`, matching the
+      # `hecks_`-prefix convention every other new saga table in this
+      # work uses) avoids colliding with any real aggregate's own
+      # `storage_name`. Lives in the SAME directory an aggregate's own
+      # `.heki` file would (`File.dirname(@path)`, `Heki`'s own call
+      # below) — which, since Heki's `resolve_path` has no per-domain
+      # component at all, is typically shared across EVERY domain
+      # booted from the same `root`. `domain` is therefore carried
+      # inside each record and filtered on read, the same reason
+      # Postgres's own `hecks_saga_instances` keeps an explicit `domain`
+      # column under schema isolation (§3).
+      #
+      # ONE flat records hash, keyed by a composite string (Heki's own
+      # snapshot format is id-keyed, not tuple-keyed) — never exposed
+      # outside this class; `each_saga` yields the five real fields a
+      # caller actually wants, not the internal key shape.
+      #
+      # Locked the same way an aggregate's own store is: `with_lock`
+      # (`Snapshot`, shared) serializes each save/delete's read-modify-
+      # write against `@path`'s own lock file — a saga gets exactly the
+      # durability and concurrency-safety this adapter already gives its
+      # aggregates, no better, no worse.
+      class SagaStore
+        include Snapshot
+        include Journal
+
+        def initialize(dir)
+          @path         = File.join(dir, "hecks_saga_instances.heki")
+          @journal_path = "#{@path}.journal"
+          @entry_mirrors = nil
+        end
+
+        def save_saga(domain, process_manager, correlation, state, memory, completed_compensations = [])
+          key    = key_for(domain, process_manager, correlation)
+          record = { "domain" => domain, "process_manager" => process_manager,
+                     "correlation" => correlation, "state" => state, "memory" => memory,
+                     "completed_compensations" => completed_compensations }
+
+          with_lock do
+            append_entry("save", key, record)
+            current = replay_journal(read_snapshot)
+            current[key] = record
+            write(current)
+            @store = current
+          end
+        end
+
+        def delete_saga(domain, process_manager, correlation)
+          key = key_for(domain, process_manager, correlation)
+
+          with_lock do
+            append_entry("delete", key, nil)
+            current = replay_journal(read_snapshot)
+            current.delete(key)
+            write(current)
+            @store = current
+          end
+        end
+
+        def each_saga(domain)
+          return enum_for(:each_saga, domain) unless block_given?
+
+          store.each_value do |record|
+            next unless record["domain"] == domain
+
+            yield record["process_manager"], record["correlation"], record["state"],
+                  (record["memory"] || {}).transform_keys(&:to_sym),
+                  record["completed_compensations"] || []
+          end
+        end
+
+        private
+
+        def store
+          @store ||= replay_journal(read_snapshot)
+        end
+
+        # A plain space-joined key, not anything fancier — a correlation value is real
+        # business data (an order id, a customer reference) and nothing
+        # here should assume it never contains a space.
+        def key_for(domain, process_manager, correlation) = [domain, process_manager, correlation].join(" ")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+require "zlib"
+
+module Hecks
+  module Adapters
+    class Heki
+      # The binary snapshot codec: magic-header framing around
+      # deflate-compressed, id-sorted JSON. Reading refuses loudly on a
+      # short file, a bad magic, or a body neither zlib nor JSON will own.
+      module Snapshot
+        private
+
+        def read_snapshot
+          return {} unless File.exist?(@path)
+
+          data = File.binread(@path)
+          raise Malformed, "#{@path}: too short" if data.bytesize < HEADER_BYTES
+          raise Malformed, "#{@path}: bad magic" unless data[0, 4] == MAGIC
+
+          JSON.parse(Zlib::Inflate.inflate(data[HEADER_BYTES..]))
+        rescue Zlib::DataError => e
+          raise Malformed, "#{@path}: zlib error: #{e.message}"
+        rescue JSON::ParserError => e
+          raise Malformed, "#{@path}: json error: #{e.message}"
+        end
+
+        # Temp-file-plus-rename, fsynced before the rename: a reader can
+        # only ever see the last complete snapshot or the one before it,
+        # never a truncated or partial one — `File.binwrite`'s old
+        # truncate-then-write left a window, proportional to the whole
+        # dataset, where the file on disk was neither.
+        def write(records)
+          sorted = records.sort_by { |id, _| id }.to_h
+          json   = JSON.generate(sorted)
+          body   = MAGIC + [sorted.size].pack("N") + Zlib::Deflate.deflate(json, Zlib::BEST_COMPRESSION)
+          tmp    = "#{@path}.tmp.#{Process.pid}.#{object_id}"
+
+          File.open(tmp, "wb") do |file|
+            file.write(body)
+            file.flush
+            file.fsync
+          end
+          File.rename(tmp, @path)
+        end
+
+        # Serializes the read-modify-write each save/delete does against
+        # the snapshot (and the journal append that precedes it) across
+        # processes — `flock` is per-process advisory, so every writer
+        # has to go through this to matter, which `with_lock`'s only two
+        # callers (`Heki#save`/`#delete`, `SagaStore#save_saga`/
+        # `#delete_saga`) both do. The lock file is separate from
+        # `@path` so a held lock never blocks `write`'s own rename.
+        def with_lock
+          File.open(lock_path, File::CREAT | File::RDWR, 0o644) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          ensure
+            lock.flock(File::LOCK_UN)
+          end
+        end
+
+        def lock_path = "#{@path}.lock"
+      end
+    end
+  end
+end

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

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