hecks 1.2.0 → 1.4.0

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

@@ -2,17 +2,17 @@ require "time"
 
 module Hecks
   module Adapters
-    # THE `authorization` PORT, FULFILLED BY GOVERNANCE — same registry,
+    # **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
+    # 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`
+    # 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
@@ -21,7 +21,7 @@ module Hecks
     module GovernanceAuthorization
       module_function
 
-      # `as_of` and `scope` are BOTH optional, same opt-in shape
+      # `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
@@ -31,7 +31,7 @@ module Hecks
       # 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",
+          provided_verb(registry, :assignments),
           actor_id: { value: actor_id.to_s }
         )
 
@@ -43,20 +43,20 @@ module Hecks
         end
       end
 
-      # `scope` UNCHECKED WHEN NOT STATED, same as every other opt-in
+      # `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.
+      # 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
+      # `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
+      # 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)
@@ -67,21 +67,21 @@ module Hecks
         false
       end
 
-      # THE OTHER HALF — may role X act as role Y. `RoleTransition.Allowed`
+      # **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",
+          provided_verb(registry, :transitions),
           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
+      # 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
@@ -89,13 +89,31 @@ module Hecks
       # 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",
+          provided_verb(registry, :assignments),
           actor_id: { value: actor_id.to_s }
         )
 
         live = rows.find { |row| row[:ends_at].nil? }
         live && live[:role_name][:value]
       end
+
+      # The verb, read from the provider's own declaration — `provides
+      # "authorization", assignments: ..., transitions: ...` on whichever
+      # loaded chapter declares it (Governance's, in every boot today).
+      # Exactly one provider, the same "the runtime will not choose for
+      # you" rule `Ports::Authorization.adapter` applies to adapters.
+      def provided_verb(registry, key)
+        providers = registry.authorization_providers
+        unless providers.size == 1
+          raise Runtime::WiringError,
+                "#{providers.size} loaded chapters provide \"authorization\"" \
+                "#{" (#{providers.map(&:name).sort.join(', ')})" unless providers.empty?} — " \
+                "a role lookup needs exactly one (framework members declaring it: " \
+                "#{Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION).join(', ')})"
+        end
+
+        providers.first.provided_verb(Bluebook::Capabilities::AUTHORIZATION, key)
+      end
     end
   end
 end

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

@@ -11,14 +11,71 @@ module Hecks
 
           File.readlines(@journal_path, chomp: true).reject(&:empty?).map do |line|
             value = JSON.parse(line)
-            state = value["state"]&.transform_keys(&:to_sym)
+            state = Ports::Persistence::StateCodec.decode(@aggregate, value["state"])
             Ports::Persistence::Entry.new(operation: value.fetch("operation"), id: value.fetch("id"), state: state,
                                           mirrors: value["mirrors"])
           end
         end
 
+        # An explicit, opt-in maintenance operation — never run
+        # automatically after an ordinary save/delete. Heki's journal is
+        # not a disposable write-ahead log: it is this adapter's own
+        # answer to `entries`, and `entries` is a real port contract
+        # (`Ports::Persistence::AppendOnly`'s own required-methods list)
+        # read in full, forever, by `Ports::Projection::Worker#catch_up!`
+        # and `Registry#projection_current?` to catch a projection up to
+        # its authoritative source, and by `bin/history` to show "every
+        # journal entry a domain's append-only adapters hold" — the same
+        # contract Postgres/Sqlite/D1 uphold by way of a journal table
+        # that is never pruned. A real example (`examples/banking`,
+        # `persisted_by("Heki")` + `projected_by("SqliteProjection")`)
+        # depends on this today. Compacting throws that full history away
+        # for whatever happened before the call — correct only for an
+        # aggregate nothing ever projects from; callers (`bin/
+        # heki_compact`) are responsible for confirming that first.
+        #
+        # Crash-safety ordering: `write` below is the exact same
+        # temp-file, fsync, atomic-rename sequence `save`/`delete`
+        # already use — the snapshot it produces is confirmed durably on
+        # disk before this method ever touches the journal. Only once
+        # that succeeds does `truncate_journal!` run. A crash between the
+        # two leaves old (now fully redundant) journal lines in place;
+        # replaying them again over the fresh snapshot on the next boot
+        # is idempotent — the same value gets set again, never a wrong
+        # one — so nothing is lost, just a little wasted replay work
+        # once. A crash before `write` completes leaves the journal
+        # fully intact and the prior snapshot untouched, exactly today's
+        # existing crash-recovery guarantee.
+        def compact!
+          with_lock do
+            current = replay_journal(read_snapshot)
+            write(current)
+            truncate_journal!
+            @store = current
+          end
+        end
+
         private
 
+        def truncate_journal!
+          return unless File.exist?(@journal_path)
+
+          # A single `truncate(0)` syscall on an already-open file
+          # descriptor — the file's length changes atomically at the
+          # filesystem level, so there is no "half truncated" state to
+          # observe even under a crash mid-call. `fsync` below makes
+          # that change durable before this method returns; without it
+          # a crash could still leave the old (harmless-to-replay)
+          # content on disk after a normal return, which is fine per
+          # the crash-safety note above, but the durable case is the
+          # one actually worth returning success for.
+          File.open(@journal_path, "r+b") do |file|
+            file.truncate(0)
+            file.flush
+            file.fsync
+          end
+        end
+
         def replay_journal(records)
           return records unless File.exist?(@journal_path)
 
@@ -38,7 +95,8 @@ module Hecks
         end
 
         def append_entry(operation, id, state)
-          line = "#{JSON.generate(operation: operation, id: id.to_s, state: state, mirrors: @entry_mirrors)}\n"
+          encoded = Ports::Persistence::StateCodec.encode(@aggregate, state)
+          line = "#{JSON.generate(operation: operation, id: id.to_s, state: encoded, mirrors: @entry_mirrors)}\n"
 
           # One write, not JSON-then-newline as two: two concurrent
           # appends can only interleave *between* writes, never inside

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

@@ -4,8 +4,8 @@ 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
+      # 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
@@ -15,16 +15,16 @@ module Hecks
       # 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
+      # `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
+      # 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
+      # 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.

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

@@ -30,7 +30,7 @@ module Hecks
         @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.
@@ -65,7 +65,7 @@ module Hecks
       # 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.
       def query(specification, args = {}, context: {})
@@ -86,7 +86,11 @@ module Hecks
       # overwrite that write on disk rather than layer on top of it.
       def project(entry)
         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)
+        else
+          current.delete(entry.id)
+        end
         write(current)
         @store = current
         entry
@@ -114,7 +118,7 @@ module Hecks
 
       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.
@@ -134,11 +138,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 +158,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
+      # for "a declared value that resolves by convention, never a silent
       # fallback" — used to 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,7 +1,7 @@
 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.

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,7 +16,7 @@ module Hecks
     module InMemoryOrdering
       module_function
 
-      # order_by IS A RUNTIME VALUE (an HTTP query param, in the
+      # 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.
@@ -46,7 +46,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/lambda/client.rb

@@ -3,31 +3,56 @@ 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}"`,
+      # 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.
+      #
+      # 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.
+      #
+      # 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:)
+        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 precisely the
+        # thing that used to be unanswerable from outside.
+        attr_reader :function_name
+
+        # **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

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`
@@ -39,46 +39,44 @@ 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
 
@@ -105,18 +103,29 @@ module Hecks
       # 1 — there is no local write-ahead log for `recover!` to replay),
       # `append`/`project` raise rather than silently no-op.
 
+      # 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.
+      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
       # 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 +139,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,18 +20,18 @@ 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.
@@ -54,7 +54,7 @@ module Hecks
         InMemoryOrdering.ordered(@records.values, aggregate: @aggregate, order_by: order_by, direction: direction)
       end
 
-      # THE DECISION THE GUIDE ASKS FOR, MADE EXPLICITLY: no compiled
+      # 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.
@@ -62,21 +62,24 @@ module Hecks
         Ports::Query::InMemory.execute(all, specification, args, registry: context[:registry])
       end
 
+      # Through the state codec, the same as Memory (see its `append`).
       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
 
       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
 
       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
@@ -108,7 +111,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