hecks 1.3.0 → 1.5.0

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

@@ -23,7 +23,7 @@ module Hecks
           raise Malformed, "#{@path}: json error: #{e.message}"
         end
 
-        # Temp-file-plus-rename, fsynced before the rename: a reader can
+        # Temp-file-plus-rename, fsynced ahead of the `File.rename` call: 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

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

@@ -25,12 +25,18 @@ module Hecks
 
       attr_reader :aggregate, :path, :events
 
+      # @param aggregate [Bluebook::Aggregate] the aggregate this store persists
+      # @param settings [Hash] adapter settings; `dir:`/`"dir"` (a storage directory, `"data"`
+      #   by default) and `domain:`/`"domain"` (the saga-persistence scope, defaulting to
+      #   `aggregate.name`) are read
+      # @param root [String, nil] the directory `settings[:dir]` resolves relative to when it
+      #   is not absolute; defaults to the process's current working directory
       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)
+        # 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.
@@ -47,6 +53,10 @@ module Hecks
         FileUtils.mkdir_p(File.dirname(@path))
       end
 
+      # Reads one record's current projected state.
+      #
+      # @param id [String, Object] the record's identity, compared as `id.to_s`
+      # @return [Runtime::Instance, nil] the stored record, or nil when no record has that id
       def find(id)
         record = store[id.to_s]
         return nil unless record
@@ -54,24 +64,45 @@ module Hecks
         instance(id.to_s, record)
       end
 
+      # Lists every record currently projected, sorted by id then reordered as requested.
+      #
+      # @param order_by [String, Symbol, nil] an attribute name to sort by; nil keeps id order
+      # @param direction [Symbol] `:asc` or `:desc`
+      # @return [Array<Runtime::Instance>] the stored records; `[]` when there are none
       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
 
+      # Counts the records currently projected.
+      #
+      # @return [Integer] number of stored records, not of journal entries
       def count = store.size
 
+      # Answers a declared query specification against the projected records.
+      #
       # `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
+      # 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.
+      #
+      # @param specification [QuerySpecification::Common::Options,
+      #   Bluebook::Behaviour::ReadModel::FilteredOptions] the declared query specification
+      # @param args [Hash{Symbol => Object}] bound values for the specification's placeholders
+      # @param context [Hash{Symbol => Object}] call context; `:registry` is read and passed
+      #   through for registry-aware comparisons
+      # @return [Array<Runtime::Instance>] the matching records, ordered and paged
       def query(specification, args = {}, context: {})
         Ports::Query::InMemory.execute(all, specification, args, registry: context[:registry])
       end
 
+      # Writes one entry to the durable journal, before any projection of it.
+      #
+      # @param entry [Persistence::Entry] the save or delete to journal
+      # @return [Persistence::Entry] `entry`, unchanged
       def append(entry)
         @entry_mirrors = entry.mirrors
         append_entry(entry.operation, entry.id, entry.state)
@@ -80,18 +111,42 @@ module Hecks
         @entry_mirrors = nil
       end
 
+      # Applies one journaled entry to the current-state snapshot.
+      #
       # 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.
+      #
+      # On a delete, though, the record `current.delete` finds is already
+      # gone: every caller (`#delete` above, `AppendOnly#delete`) appends
+      # before it projects, so the fresh read above has already replayed
+      # this very entry off the journal. What the memoized `store` last
+      # held — from before this call — is read up front, for the return
+      # value only; it plays no part in what gets written.
+      #
+      # @param entry [Persistence::Entry] the save or delete to materialize
+      # @return [Runtime::Instance, nil] on a save, the newly stored record; on a delete, the
+      #   removed record, or nil when no record had that id
       def project(entry)
+        removed = entry.delete? ? store[entry.id] : nil
         current = read
-        entry.save? ? current[entry.id] = entry.state.dup : current.delete(entry.id)
+        if entry.save?
+          current[entry.id] = Ports::Persistence::StateCodec.encode(@aggregate, entry.state)
+          projected = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
+        else
+          current.delete(entry.id)
+          projected = removed && instance(entry.id, removed)
+        end
         write(current)
         @store = current
-        entry
+        projected
       end
 
+      # Journals and projects an instance's state under the file lock.
+      #
+      # @param instance [Runtime::Instance] the record to persist
+      # @return [Runtime::Instance] `instance`, unchanged
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
         with_lock do
@@ -101,6 +156,11 @@ module Hecks
         instance
       end
 
+      # Journals and projects the removal of one record, if it exists, under the file lock.
+      #
+      # @param id [String, Object] the record's identity, compared as `id.to_s`
+      # @return [Boolean] true when a record was found and deleted, false when there was none
+      #   and nothing was journaled
       def delete(id)
         return false unless find(id)
 
@@ -112,20 +172,55 @@ module Hecks
         true
       end
 
+      # Records one emitted event in this adapter's in-memory event log.
+      #
+      # @param event [Runtime::Event] the event to record
+      # @return [Array<Runtime::Event>] the adapter's in-memory event log, including `event`
       def record_event(event) = @events << event
 
-      # ── the OPTIONAL saga-persistence capability (§2) — Heki's own
+      # ── 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.
+      #
+      # @param process_manager [String, Symbol] the process manager's name, compared as
+      #   `.to_s`
+      # @param correlation [String, Symbol, Object] the instance's correlation value, compared
+      #   as `.to_s`
+      # @param state [String, Symbol] the saga's current state name, compared as `.to_s`
+      # @param memory [Hash] the saga's working memory to persist
+      # @param completed_compensations [Array] the ledger of completed compensable legs;
+      #   `[]` when none
+      # @return [Hash{String => Hash}] `SagaStore`'s internal records Hash after the write;
+      #   callers ignore it
       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
 
+      # Removes a finished saga instance's checkpoint; a missing one is not an error.
+      #
+      # @param process_manager [String, Symbol] the process manager's name, compared as
+      #   `.to_s`
+      # @param correlation [String, Symbol, Object] the instance's correlation value, compared
+      #   as `.to_s`
+      # @return [Hash{String => Hash}] `SagaStore`'s internal records Hash after the delete;
+      #   callers ignore it
       def delete_saga(process_manager:, correlation:)
         saga_store.delete_saga(@domain, process_manager.to_s, correlation.to_s)
       end
 
+      # Yields every checkpointed saga instance of this domain, for `Registry
+      # #rehydrate_sagas!` to restore at boot.
+      #
+      # @yieldparam process_manager [String] the process manager's name
+      # @yieldparam correlation [String] the instance's correlation value
+      # @yieldparam state [String] the saga's state name
+      # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, Symbol keys at every
+      #   depth
+      # @yieldparam completed_compensations [Array] the completed-compensation ledger, `[]`
+      #   when none was recorded
+      # @return [Enumerator, Hash{String => Hash}] an enumerator over the same five values
+      #   when no block is given; otherwise `SagaStore`'s internal records Hash
       def each_saga(&) = saga_store.each_saga(@domain, &)
 
       private
@@ -134,11 +229,13 @@ module Hecks
         @saga_store ||= SagaStore.new(File.dirname(@path))
       end
 
+      # `record` is the snapshot/journal's own string-keyed JSON — decoded
+      # deep through the state codec, never symbolized one level by hand.
       def instance(id, record)
         Runtime::Instance.new(
           aggregate: @aggregate,
           id:        id,
-          state:     record.transform_keys(&:to_sym)
+          state:     Ports::Persistence::StateCodec.decode(@aggregate, record)
         )
       end
 
@@ -152,10 +249,10 @@ module Hecks
       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
+      # for "a declared value that resolves by convention, never a silent
+      # fallback" — would otherwise crash `File.join` outright
       # (`TypeError: no implicit conversion of Symbol into String`):
-      # `resolve_path` only ever checked for a MISSING `dir` setting,
+      # `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)

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

@@ -1,18 +1,28 @@
 module Hecks
   module Adapters
-    # THE `identity_resolution` PORT, FULFILLED BY THE Identity FRAMEWORK
-    # BLUEBOOK — same registry, same boot, so this is a dispatch against
+    # 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
 
+      # Looks up the id of the identity an authenticated (issuer, subject) pair is linked to,
+      # querying the Identity framework bluebook's own `ResolvedBy`.
+      #
       # `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.
+      #
+      # @param registry [Runtime::Registry] the booted registry, queried for the linked
+      #   identity's id
+      # @param issuer [String] the OIDC issuer that authenticated the caller, compared as a
+      #   String
+      # @param subject [String] the OIDC subject the issuer vouches for, compared as a String
+      # @return [String, nil] the linked identity's id, or nil if nothing has linked this pair
       def resolve(registry, issuer:, subject:)
         rows = Runtime::Dispatcher.new(registry).query(
           "Identity::ExternalIdentifier.ResolvedBy",

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

@@ -6,7 +6,7 @@ require_relative "../../runtime/errors"
 
 module Hecks
   module Adapters
-    # SHARED BY every adapter that holds decoded Ruby records rather than
+    # 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
@@ -16,10 +16,24 @@ module Hecks
     module InMemoryOrdering
       module_function
 
-      # order_by IS A RUNTIME VALUE (an HTTP query param, in the
+      # Orders decoded records by a declared attribute, then by id as the total-order
+      # tiebreaker.
+      #
+      # 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.
+      #
+      # @param records [Array<Runtime::Instance>] the records to order
+      # @param aggregate [Bluebook::Aggregate] the aggregate `records` belong to, checked for
+      #   `order_by`'s attribute
+      # @param order_by [String, Symbol, nil] a dotted attribute path to sort by; nil returns
+      #   `records` unchanged
+      # @param direction [Symbol] `:asc` or `:desc`
+      # @return [Array<Runtime::Instance>] `records`, ordered by `order_by` then id; unchanged
+      #   when `order_by` is nil
+      # @raise [Runtime::WiringError] if `order_by` names no attribute of `aggregate` and is
+      #   not its lifecycle field
       def ordered(records, aggregate:, order_by:, direction:)
         return records unless order_by
 
@@ -36,6 +50,14 @@ module Hecks
         end
       end
 
+      # Resolves the dotted path `FieldPath.dig` should read to compare a value object field.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate `field` belongs to
+      # @param field [String, Symbol] a dotted order_by path, such as `"price"` or
+      #   `"price.cents"`
+      # @return [String] `field` unchanged for an already-dotted path, the lifecycle field, or
+      #   an attribute with no value-object type; otherwise `"<name>.<member>"` naming the
+      #   attribute's numeric member, its sole member, or the bare `"value"` convention
       def sortable_path(aggregate, field)
         name, *path = field.to_s.split(".")
         return field.to_s unless path.empty?
@@ -46,7 +68,7 @@ module Hecks
         vo = aggregate.value_object(attribute.type)
         return field.to_s unless vo
 
-        # Numeric member first, then the SOLE attribute whatever it is
+        # Numeric member first, then the sole attribute whatever it is
         # named (single-attribute value objects strictly answer `.value`
         # — the same generalization `SqlQueryBuilder#query_expression`
         # makes for the column side, kept in lockstep so Memory and SQL

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

@@ -0,0 +1,3 @@
+Hecks.adapter "InProcessKeyVault" do
+  port "key_vault"
+end

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

@@ -0,0 +1,53 @@
+require "securerandom"
+
+module Hecks
+  module Adapters
+    # The real `key_vault` fulfillment for a single running process — a
+    # table of key material, keyed by an opaque reference never exposed to
+    # a bluebook or an event. Cryptoshredding only works if the key
+    # genuinely leaves memory when destroyed: `destroy` deletes the Hash
+    # entry outright, not merely a flag, so a `fetch` afterward has
+    # nothing left to decrypt with.
+    #
+    # **Not crash-durable** — a process restart loses every key this
+    # adapter ever issued, along with every ciphertext under it. A
+    # deployment that needs destruction to survive a restart (or to leave
+    # a physical-destruction audit trail) backs this port with a real
+    # `KMS` or `HSM` instead; this default asks for nothing external to
+    # run, the same tradeoff `SecureRandomIdentity` already makes for
+    # identity minting.
+    module InProcessKeyVault
+      module_function
+
+      # Mints and stores a fresh symmetric key, returning only an opaque handle to it.
+      #
+      # @param subject_id [String] the data subject the key is being issued for; held
+      #   alongside the key material for {#destroy}'s own bookkeeping, never returned
+      # @return [String] an opaque key reference; the key material itself never leaves this
+      #   adapter
+      def issue(subject_id:)
+        key_reference = SecureRandom.uuid
+        (@keys ||= {})[key_reference] = { subject_id: subject_id, secret: SecureRandom.hex(32) }
+        key_reference
+      end
+
+      # Looks up the live key material behind a reference, for encrypting or decrypting.
+      #
+      # @param key_reference [String] the opaque reference {#issue} returned
+      # @return [String, nil] the key's hex-encoded secret, or nil once {#destroy} has run
+      def fetch(key_reference) = (@keys ||= {})[key_reference]&.fetch(:secret)
+
+      # Irrevocably deletes a key's material, so {#fetch} can never answer for it again.
+      #
+      # @param key_reference [String] the opaque reference {#issue} returned
+      # @return [Boolean] true when a key was held and is now gone; false when this
+      #   reference was already destroyed, or never issued
+      def destroy(key_reference:) = !(@keys ||= {}).delete(key_reference).nil? # rubocop:disable Naming/PredicateMethod
+
+      # Resets the vault to empty, forgetting every key this process ever issued.
+      #
+      # @return [void]
+      def reset! = @keys = {}
+    end
+  end
+end

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

@@ -3,41 +3,94 @@ require "json"
 module Hecks
   module Adapters
     class Lambda
-      # THE THIN AWS CLIENT — shared by this adapter's own read methods
+      # **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}"`,
+      # ## Resolving the function name
+      #
+      # Function name is computed unless it is named — `"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);
+      # 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.
+      # directory.
+      #
+      # ## When the assumption breaks
+      #
+      # That assumption is not always true, and when it breaks nothing
+      # about it is recoverable from here. `bin/project_deploy` honours
+      # a `.world`'s own `stack_prefix`/`stack_name` — settings that
+      # exist precisely so a domain whose AWS identity predates a rename
+      # keeps targeting the stack that is actually live rather than
+      # standing up a second, empty one beside it. A real one:
+      # embryonautfoundersapp deploys as `hecksagain-embryonaut`, and no
+      # value of `domain` (or of `DOMAIN_NAME`, the deployed-Lambda
+      # override callers already pass) can make this computation produce
+      # a name with no dash after "hecks". Every Ruby-side read and
+      # dispatch for that app has therefore been invoking a function
+      # that does not exist — found live, and visible in the deployed
+      # journal having never received a single row.
+      #
+      # ## Naming it explicitly
+      #
+      # So the name can be named, in the one place the rest of this
+      # deployment is already described: the `.world`'s own
+      # `persisted_by("Lambda")`/`dispatched_by("Lambda")` block, beside
+      # `region`. Given, it wins outright; absent, the computation above
+      # is unchanged, which is every domain whose stack name was never
+      # pinned.
       class Client
-        def initialize(domain:, region:)
+        # @param domain [String, Symbol] the bluebook's own declared domain name; computes
+        #   the function name when `function` is not given
+        # @param region [String] the AWS region to invoke in
+        # @param function [String, Symbol, nil] an explicit Lambda function name, from a
+        #   `.world`'s `persisted_by("Lambda")`/`dispatched_by("Lambda")` block; nil computes
+        #   `"hecks-#{domain.downcase}"`
+        def initialize(domain:, region:, function: nil)
           require "aws-sdk-lambda"
-          @function_name = "hecks-#{domain.to_s.downcase}"
+          @function_name = function.to_s.empty? ? "hecks-#{domain.to_s.downcase}" : function.to_s
           @client = Aws::Lambda::Client.new(region: region)
         end
 
-        # THE WHOLE DOMAIN, EVERY TIME — matches dispatch::read's own
+        # The function this client actually invokes — read by
+        # `Runtime::WiringError` messages and worth asserting on
+        # directly, since "which function did we call" is otherwise
+        # unanswerable from outside.
+        attr_reader :function_name
+
+        # Reads the whole domain's current state and event log from the remote function.
+        #
+        # **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.
+        # caching here, deliberately: memoizing this across calls once
+        # silently served stale reads for a warm web process's whole
+        # lifetime after a write happened elsewhere — see Lambda#instances's
+        # own comment on the real, live bug that caught it.
+        #
+        # @return [Hash{String => Object}] the parsed JSON response; the deployed function's
+        #   own top-level keys (`"instances"`, `"events"`, …)
+        # @raise [Runtime::WiringError] if the function reports a `functionError` (see
+        #   `invoke`)
         def read
           invoke({ "read" => true })
         end
 
+        # Dispatches one command to the remote function and returns its parsed response.
+        #
+        # @param verb [String] the fully-qualified verb to dispatch
+        # @param args [Hash] the command's declared arguments
+        # @param role [String, Symbol, nil] the role to dispatch as; omitted from the payload
+        #   when nil
+        # @return [Hash{String => Object}] the parsed JSON response, including a `"refusals"`
+        #   array and a `"mutations"` array
+        # @raise [Runtime::WiringError] if the function reports a `functionError` (see
+        #   `invoke`)
         def dispatch(verb, args, role: nil)
           payload = { "verb" => verb, "args" => args }
           payload["role"] = role if role