hecks 1.3.0 → 1.5.0

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

@@ -6,8 +6,8 @@ require_relative "../../runtime/instance"
 
 module Hecks
   module Adapters
-    # THE READ-SIDE HALF OF LAMBDA ROUTING — `persisted_by("Lambda")`'s
-    # own adapter, resolved through the SAME `Ports::Persistence`
+    # **The read-side half of lambda routing** — `persisted_by("Lambda")`'s
+    # own adapter, resolved through the same `Ports::Persistence`
     # machinery `persisted_by("Postgres")`/`persisted_by("Memory")`
     # already use (`Runtime::Registry#repository`, `RepositoryFactory
     # .build`) — no new framework plumbing, just a new adapter class at
@@ -16,7 +16,7 @@ module Hecks
     # compose through one shared `Client` per domain rather than each
     # inventing its own AWS wiring.
     #
-    # READ-ONLY, DELIBERATELY — `append`/`project` raise rather than
+    # **Read-only, deliberately** — `append`/`project` raise rather than
     # silently no-op. A write reaching this class would mean
     # `Runtime::CommandInterpreter` ran locally against a Lambda-routed
     # domain, which is exactly the bypass `Runtime::RemoteDispatcher`
@@ -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 =
@@ -39,59 +49,81 @@ module Hecks
           else
             aggregate.name
           end
-        region =
-          if settings.key?(:region)
-            settings[:region]
-          elsif settings.key?("region")
-            settings["region"]
-          else
-            "us-east-1"
-          end
-        # TWO DIFFERENT "domain"s, deliberately not conflated: `domain`
-        # (this aggregate's OWN bluebook name — "Identity", "Governance")
+        region = setting(settings, :region, "us-east-1")
+        # Named, when this deployment's function isn't `hecks-<domain>`
+        # — `Client`'s own comment has the real case that needs it.
+        # Absent (every domain whose stack name was never pinned), the
+        # computation below is exactly as it was.
+        function = setting(settings, :function, nil)
+        # Two different "domain"s, deliberately not conflated: `domain`
+        # (this aggregate's own bluebook name — "Identity", "Governance")
         # only ever prefixes the instances lookup, since that's how
         # rust/host's own `Store::instances()` keys every record
         # (`registry.rb`'s own `"#{a[:domain_name]}::#{a[:name]}#"`
         # dump format, unchanged by which chapter attached it). The
-        # FUNCTION to actually call is a different question: Governance
-        # and Identity aggregates are compiled into the ATTACHING
+        # function to actually call is a different question: Governance
+        # and Identity aggregates are compiled into the attaching
         # domain's own Lambda (one merged `Store` per target — Phase 0's
         # framework-bluebook work), never a function of their own, so
         # `settings[:domain]` is the wrong signal for `Client.new`.
         # `root` is the boot's own directory (`Registry#root`, shared by
-        # EVERY bluebook in one registry regardless of which one
+        # every bluebook in one registry regardless of which one
         # attached it) — `File.basename(root)` reproduces the exact
         # same string `bin/project_deploy`'s own `stack_name` computes
-        # from the domain PATH, so the two can never name two
-        # different functions for the same deploy... on a LOCAL boot,
+        # from the domain path, so the two can never name two
+        # different functions for the same deploy... on a local boot,
         # where `root` is a real project directory. Inside the deployed
-        # Lambda itself `root` is ALWAYS `/var/task` (every Lambda's own
+        # Lambda itself `root` is always `/var/task` (every Lambda's own
         # fixed code root, regardless of domain) — `File.basename` gives
         # "task", not the domain name, and invokes the wrong function
         # entirely. A real, live AccessDeniedException on
         # "hecks-task" caught this: invisible through every earlier
         # phase's own verify step, all run from a local boot, until
-        # WebFunction became the first Ruby process to EVER make this
+        # WebFunction became the first Ruby process to ever make this
         # exact call from inside a deployed Lambda. `DOMAIN_NAME` (set
         # by bin/project_deploy's own WebFunction Environment) is the
         # real, unambiguous signal in that specific context; the
         # root-basename heuristic stays as the local-boot fallback,
         # unchanged.
         function_domain = ENV["DOMAIN_NAME"] || (root ? File.basename(root) : domain)
-        @client = Client.new(domain: function_domain, region: region)
+        @client = Client.new(domain: function_domain, region: region, function: function)
         @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
@@ -105,18 +137,36 @@ 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)
+
+        fallback
+      end
+
       private
 
-      # RE-FETCHED EVERY CALL, deliberately NOT memoized across them —
+      # Re-fetched every call, deliberately not memoized across them —
       # this adapter itself is long-lived (one instance per aggregate,
-      # held by the registry `RUNTIME = Hecks.boot(...)` builds ONCE
+      # 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,
+      # Lambda fresh) and the very next `.all` on the same warm
+      # container kept returning the state from before that mutation,
       # forever, until the container cold-started — memoizing here
       # made every write invisible to every read on a warm container.
       # Keyed by bare id (the part after "Domain::Aggregate#"), not the
@@ -130,15 +180,12 @@ module Hecks
         end.to_h
       end
 
-      # Lambda's own JSON response is already Ruby-decoded with STRING
-      # keys (plain `JSON.parse`, no `symbolize_names:`) — every other
-      # adapter's own `instance(row)` builder (Postgres, Sqlite) hands
-      # `Runtime::Instance.new` a SYMBOL-keyed state hash instead. A
-      # round trip through `JSON.generate`/`JSON.parse` is simpler and
-      # safer than a hand-rolled deep-symbolize helper for what is not
-      # a hot path.
+      # Lambda's own JSON response is already Ruby-decoded with string
+      # keys (plain `JSON.parse`, no `symbolize_names:`) — decoded through
+      # the state codec (PR A3), the same IR-driven spelling every other
+      # adapter's read produces.
       def build_instance(id, state)
-        Runtime::Instance.new(aggregate: @aggregate, id: id, state: JSON.parse(JSON.generate(state), symbolize_names: true))
+        Runtime::Instance.new(aggregate: @aggregate, id: id, state: Ports::Persistence::StateCodec.decode(@aggregate, state))
       end
     end
   end

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

@@ -5,13 +5,13 @@ require_relative "../../runtime/instance"
 
 module Hecks
   module Adapters
-    # A BROWSER-HOSTED DOMAIN'S OWN DECLARED INTENT — not a second Memory
+    # **A browser-hosted domain's own declared intent** — not a second Memory
     # wearing a different name. Ruby has no way to reach a real browser's
     # `window.localStorage` at all (it is per-tab, per-origin, JS-only,
     # unreachable over any network the way D1's own REST API is) — so
     # this Ruby-side adapter is honestly a stand-in: in-process, ephemeral,
     # mechanically identical to Memory. What earns it a name of its own
-    # is what it DECLARES, not what it happens to do in Ruby: `persisted_by
+    # is what it declares, not what it happens to do in Ruby: `persisted_by
     # "LocalStorage"` says "this domain expects real, durable, single-
     # device storage the moment it's actually running where it's meant to
     # run" — the same distinction Heki (real local durability) already
@@ -20,26 +20,35 @@ module Hecks
     # model_check` all get a domain that boots and behaves correctly
     # against this adapter; only a real browser gets the real durability.
     #
-    # THE REAL BROWSER HALF lives outside this file entirely: `rust/web`'s
+    # The real browser half lives outside this file entirely: `rust/web`'s
     # `dispatch(json)` (docs/implemented/decisions/0015) takes an optional
     # `"seed"` (the exact `"instances"` shape it also answers with) plus
     # `"steps"` — a host rehydrates from a prior snapshot and replays only
     # the new command(s), rather than the whole history every call. A
     # page bound to this adapter is expected to hold that snapshot in
     # `window.localStorage` itself (get on load, set after every
-    # `dispatch`) — the seed/instances round trip IS the adapter, once
+    # `dispatch`) — the seed/instances round trip is the adapter, once
     # you're in the one runtime that can actually reach the storage this
     # name promises.
     class LocalStorage
-      # TENANT-CAPABLE TRIVIALLY, same reasoning as Memory's own — a
+      # Tenant-capable trivially, same reasoning as Memory's own — a
       # 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,40 +56,86 @@ 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
 
-      # THE DECISION THE GUIDE ASKS FOR, MADE EXPLICITLY: no compiled
+      # 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
 
+      # 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)
-        @entries << entry
+        copied = Ports::Persistence::Entry.new(operation: entry.operation, id: entry.id,
+                                               state: copy(entry.state), mirrors: entry.mirrors)
+        @entries << copied
         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: entry.state.dup)
+          @records[entry.id] = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: copy(entry.state))
         else
           @records.delete(entry.id)
         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: instance.state.dup)
+        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
@@ -91,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  = []
@@ -108,7 +177,11 @@ module Hecks
         self
       end
 
-      # NOT lineage_capable? — deliberately absent, the same trade Heki
+      private
+
+      def copy(state) = Ports::Persistence::StateCodec.copy(@aggregate, state)
+
+      # Not lineage_capable? — deliberately absent, the same trade Heki
       # makes and states plainly (writing-an-adapter.md's own section on
       # it): a domain bound here has no edge for its own shape to travel
       # across if it ever changes; that must be hand-migrated, or the