hecks 1.4.0 → 1.5.1

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

@@ -25,6 +25,12 @@ 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)
@@ -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,13 +64,23 @@ 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
@@ -68,10 +88,21 @@ module Hecks
       # 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,22 +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
         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
@@ -105,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)
 
@@ -116,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
       # 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
@@ -159,7 +250,7 @@ module Hecks
 
       # `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
+      # 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,
       # never a Symbol one. Treated the same as no setting at all — falls

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

@@ -8,11 +8,21 @@ module Hecks
     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

@@ -16,10 +16,24 @@ module Hecks
     module InMemoryOrdering
       module_function
 
+      # 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?

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

@@ -9,6 +9,8 @@ module Hecks
       # domain-specific: neither caller needs to know an AWS SDK is
       # involved at all.
       #
+      # ## 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}"`,
@@ -19,6 +21,8 @@ module Hecks
       # reproduces the same string bin/project_deploy computes from the
       # 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
@@ -33,6 +37,8 @@ module Hecks
       # 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
@@ -40,6 +46,12 @@ module Hecks
       # is unchanged, which is every domain whose stack name was never
       # pinned.
       class Client
+        # @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 = function.to_s.empty? ? "hecks-#{domain.to_s.downcase}" : function.to_s
@@ -48,21 +60,37 @@ module Hecks
 
         # The function this client actually invokes — read by
         # `Runtime::WiringError` messages and worth asserting on
-        # directly, since "which function did we call" is precisely the
-        # thing that used to be unanswerable from outside.
+        # 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

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

@@ -29,6 +29,16 @@ module Hecks
 
       attr_reader :aggregate
 
+      # Resolves which Lambda function's Store to read from and builds the client that
+      # reads it.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose records this adapter reads
+      # @param settings [Hash{Symbol, String => Object}] world settings for the binding:
+      #   `domain` (prefixes the instances lookup; default the aggregate's own name),
+      #   `region` (default `"us-east-1"`) and `function` (the function name, when it is not
+      #   `hecks-<domain>`), each read under a Symbol or a String key
+      # @param root [String, nil] the boot's own project directory, used with `DOMAIN_NAME`
+      #   to resolve which function to call; nil falls further back to `domain`
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
         domain =
@@ -80,16 +90,40 @@ module Hecks
         @prefix = "#{domain}::#{aggregate.hecks_name}#"
       end
 
+      # Looks up the current record for one aggregate identity, reading the Lambda's own
+      # Store fresh on every call.
+      #
+      # @param id [String, Object] the aggregate identity, compared as `id.to_s`
+      # @return [Runtime::Instance, nil] the decoded record, or nil when no record has that id
       def find(id)
         instances[id.to_s]
       end
 
+      # Lists every stored record, in id order unless an ordering attribute is given.
+      #
+      # @param order_by [String, Symbol, nil] attribute (or dotted value-object path) to sort
+      #   by; nil orders by id alone
+      # @param direction [Symbol, String] `:asc` or `:desc`
+      # @return [Array<Runtime::Instance>] the decoded records, `[]` when the Store holds none
+      #   with this aggregate's own prefix
+      # @raise [Runtime::WiringError] if `order_by` names no attribute of the aggregate
       def all(order_by: nil, direction: :asc)
         InMemoryOrdering.ordered(instances.values, aggregate: @aggregate, order_by: order_by, direction: direction)
       end
 
+      # Counts the records currently held for this aggregate.
+      #
+      # @return [Integer] number of records
       def count = instances.size
 
+      # Answers a declared query by filtering, ordering and paging the held records in Ruby.
+      #
+      # @param specification [QuerySpecification::Common::Options] the declared query
+      # @param args [Hash{Symbol => Object}] values for the specification's symbolic operands
+      # @param context [Hash] execution context from `Ports::Query.execute`; accepted for the
+      #   port's call shape and not read
+      # @return [Array<Runtime::Instance>] the matching records, `[]` when none match
+      # @raise [Runtime::WiringError] if a where clause uses an operation no comparator handles
       def query(specification, args = {}, context: {})
         Ports::Query::InMemory.execute(instances.values, specification, args)
       end
@@ -103,10 +137,17 @@ module Hecks
       # 1 — there is no local write-ahead log for `recover!` to replay),
       # `append`/`project` raise rather than silently no-op.
 
+      # Reads a world setting under either a Symbol or a String key, with a fallback.
+      #
       # A `.world` block's settings arrive symbol-keyed from the DSL and
       # string-keyed from a round-tripped export, so every read has to
       # accept both — one helper rather than the same five lines per
       # key.
+      #
+      # @param settings [Hash] the world settings Hash to read from
+      # @param key [Symbol] the setting name, tried as itself and as `key.to_s`
+      # @param fallback [Object] the value to return when neither key is present
+      # @return [Object] the setting's value, or `fallback` when absent
       def setting(settings, key, fallback)
         return settings[key] if settings.key?(key)
         return settings[key.to_s] if settings.key?(key.to_s)
@@ -121,8 +162,8 @@ module Hecks
       # held by the registry `RUNTIME = Hecks.boot(...)` builds once
       # per Lambda web process — WebFunction's own top-level constant,
       # reused warm across every HTTP request that process serves, not
-      # rebuilt per request the way a memoize-for-one-request comment
-      # here used to assume). A real, live bug caught this: a mutation
+      # rebuilt per request the way memoizing here would wrongly assume).
+      # A real, live bug caught this: a mutation
       # dispatched fine (RemoteDispatcher always calls the dispatch
       # Lambda fresh) and the very next `.all` on the same warm
       # container kept returning the state from before that mutation,

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

@@ -35,11 +35,20 @@ module Hecks
       # browser tab is exactly one origin, exactly one user; there is no
       # second tenant this in-process Hash could ever confuse a first
       # one with.
+      #
+      # @return [Boolean] true, always
       def self.tenant_capable? = true
+
+      # Lists the optional persistence behaviours this adapter advertises.
+      #
+      # @return [Array<Symbol>] `[:atomic_put]`
       def persistence_capabilities = [:atomic_put]
 
       attr_reader :aggregate, :events
 
+      # @param aggregate [Bluebook::Aggregate] the aggregate this store persists
+      # @param settings [Hash] accepted but not read by this class
+      # @param root [String, nil] accepted but not read by this class
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
         @records   = {}
@@ -47,22 +56,48 @@ module Hecks
         @entries   = []
       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) = @records[id.to_s]
+
+      # Counts the records currently projected.
+      #
+      # @return [Integer] number of stored records
       def count    = @records.size
 
+      # Lists every record currently projected.
+      #
+      # @param order_by [String, Symbol, nil] an attribute name to sort by; nil keeps
+      #   insertion 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)
         InMemoryOrdering.ordered(@records.values, aggregate: @aggregate, order_by: order_by, direction: direction)
       end
 
+      # Answers a declared query specification against the projected records.
+      #
       # The decision the guide asks for, made explicitly: no compiled
       # dialect of its own, same as Heki/Memory — a personal-scale local
       # store answering by walking `all` is correct on day one, and
       # nothing about a browser tab's own data volume asks for pushdown.
+      #
+      # @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
 
-      # Through the state codec, the same as Memory (see its `append`).
+      # Records one journal entry, holding a codec copy of its state, the same as `Memory#append`.
+      #
+      # @param entry [Ports::Persistence::Entry] the save or delete to journal
+      # @return [Ports::Persistence::Entry] the caller's own `entry`, not the journalled copy
       def append(entry)
         copied = Ports::Persistence::Entry.new(operation: entry.operation, id: entry.id,
                                                state: copy(entry.state), mirrors: entry.mirrors)
@@ -70,6 +105,11 @@ module Hecks
         entry
       end
 
+      # Applies one journaled entry to the current-state store.
+      #
+      # @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)
         if entry.save?
           @records[entry.id] = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: copy(entry.state))
@@ -78,12 +118,24 @@ module Hecks
         end
       end
 
+      # Journals and projects an instance's state.
+      #
+      # @param instance [Runtime::Instance] the record to persist
+      # @return [Runtime::Instance] the newly stored record (a copy of `instance`'s state)
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: copy(instance.state))
         append(entry)
         project(entry)
       end
 
+      # Writes an entry through an existence check, refusing to replace an existing record
+      # when asked.
+      #
+      # @param entry [Persistence::Entry] the entry to persist (its `id` checked for an
+      #   existing record)
+      # @param insert_only [Boolean] true to refuse replacing a record that already exists
+      # @return [Symbol] `:conflicted` when `insert_only` met an existing record and nothing
+      #   was written; `:inserted` or `:replaced` otherwise
       def atomic_put(entry, insert_only: false)
         exists = @records.key?(entry.id.to_s)
         return :conflicted if insert_only && exists
@@ -94,16 +146,30 @@ module Hecks
         status
       end
 
+      # Journals and projects the removal of one record.
+      #
+      # @param id [String, Object] the record's identity, compared as `id.to_s`
+      # @return [Runtime::Instance, nil] the removed record, or nil when no record had that id
       def delete(id)
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
         append(entry)
         project(entry)
       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
 
+      # Reads the whole journal, oldest entry first.
+      #
+      # @return [Array<Persistence::Entry>] a shallow copy of every appended entry
       def entries = @entries.dup
 
+      # Clears the stored records, events and journal so a kept runtime starts clean.
+      #
+      # @return [LocalStorage] self, so a caller can chain after resetting
       def reset!
         @records = {}
         @events  = []