hecks 0.2.0 → 1.0.0

data/lib/hecks/runtime/entity_interpreter.rb

@@ -0,0 +1,299 @@
+require_relative "interpreting"
+require_relative "../naming"
+require_relative "../rendering"
+require_relative "errors"
+require_relative "identity"
+require_relative "instance"
+require_relative "value"
+require_relative "refusal_wording"
+require_relative "routing"
+require_relative "dependency_planning"
+require_relative "../ports/persistence/execution"
+require_relative "entity_element"
+require_relative "command_interpreter/argument_gate"
+
+module Hecks
+  module Runtime
+    class EntityInterpreter
+      include Interpreting
+      # THE SAME PAYLOAD GATE aggregate commands and port operations already
+      # run — bug audit H1 (docs/audits/2026-08-10-main-bug-audit.md): this
+      # class used to run NEITHER refuse_unknown_arguments NOR
+      # refuse_absent_arguments, on a comment claiming "an entity inherits
+      # its aggregate's own gate." Nothing on the entity dispatch path ever
+      # ran one — confirmed live, `LedgerEntry.Reverse` accepted an
+      # unrecognized `bogus_arg:` outright, and dispatching it with no
+      # `narrative:` silently overwrote the stored narrative with `nil`
+      # (`sets :narrative`'s bare self-referential form reads `args[:narrative]`
+      # unconditionally). See `step_refuse_unknown_arguments`/
+      # `step_refuse_absent_arguments`, below, for how the shared gate is
+      # reused rather than reimplemented.
+      include CommandInterpreter::ArgumentGate
+
+      attr_reader :registry
+
+      # THE DECLARED ORDER, HAND-TYPED — mirrors Vocabulary::EntityDispatchOrder
+      # (language/bluebook/vocabulary.bluebook:217-232), held equal to it by
+      # spec/vocabulary_conformance_spec.rb the same way CommandInterpreter's
+      # own DISPATCH_ORDER is; see that constant's doc comment for why this is
+      # hand-typed rather than read live off the meta-domain at every dispatch.
+      # `refuse_unknown_arguments`/`refuse_absent_arguments` now lead it, same
+      # position `AggregateDispatchOrder` holds them at (H1, above) — the only
+      # remaining difference from the aggregate order is no
+      # `assign_creation_attributes` (an entity is never created through this
+      # path).
+      DISPATCH_ORDER = Hecks::Vocabulary.symbols("EntityDispatchOrder")
+
+      # Same safety valve as `CommandInterpreter::MAX_STALE_WRITE_RETRIES` —
+      # see that constant's own comment.
+      MAX_STALE_WRITE_RETRIES = 5
+
+      # `instance` is the PARENT aggregate record (what gets saved and
+      # returned) ; `element`/`view` are the entity piece itself — `view`
+      # wraps `element` as it stood at `locate_element`, pre-mutation, and
+      # `enforce_ensures` builds its own settled wrapper off `element` as it
+      # stands after, the same split the original sequential code made.
+      #
+      # `chain` — S17, ADR 0026 — every entity the dotted verb passes
+      # through, root-first (`[Handler, Dispatch]` for `Handler.Dispatch.
+      # Bind`) ; `entity`/`entity_name` stay the CHAIN'S OWN LAST entry,
+      # the one a command actually belongs to and a mutation actually
+      # targets, so every step written before this ADR (enforce_givens,
+      # apply_mutations, advance_lifecycle, element_identity, ...) reads
+      # exactly as it always has. Only `locate_element` walks the chain.
+      Context = Struct.new(:domain, :aggregate, :entity, :entity_name, :command, :command_name,
+                           :args, :repository, :instance, :chain, :element, :view, :transition,
+                           :old_element, :result, :route, :plan, :persistence_outcome, :dry_run)
+
+      def initialize(registry, rules:)
+        @registry = registry
+        @rules    = rules
+      end
+
+      # `dry_run:` — CommandInterpreter#call's own twin, see that method's
+      # comment for the shared reasoning (Dispatcher#dry_run?'s own entry
+      # point). `step_save`/`step_emit` are the only two steps here that
+      # read it either.
+      # RETRIES THE WHOLE METHOD BODY on `StaleWrite` — same reasoning as
+      # `CommandInterpreter#call`'s own retry: a fresh `ctx`, a fresh
+      # `step_hydrate_parent`/`step_locate_element` re-reading current
+      # state.
+      def call(domain, aggregate, dotted, legacy_args, route: nil, with: nil, dry_run: false)
+        *entity_names, command_name = dotted.to_s.split(".")
+        if entity_names.empty?
+          raise UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
+                                                   aggregate: aggregate.hecks_name, entity: dotted.to_s.inspect)
+        end
+
+        chain  = walk_entity_chain(aggregate, entity_names)
+        entity = chain.last
+        command = entity.command(command_name) ||
+                  raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_no_command",
+                                                           entity: entity.hecks_name, command: command_name.inspect))
+
+        args = Routing.payload(command, with: with, legacy: legacy_args)
+        attempt = 0
+        begin
+          ctx = Context.new(domain, aggregate, entity, entity_names.join("."), command, command_name, args)
+          ctx.chain = chain
+          ctx.route = route
+          ctx.dry_run = dry_run
+          ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command)
+          # RESOLVED HERE, ONCE — see CommandInterpreter#call's own comment;
+          # `step_hydrate_parent` reads `ctx.repository` without re-fetching.
+          ctx.repository = @registry.repository(domain, aggregate)
+          lock_id = Identity.best_effort(aggregate, args, route)
+          run_dispatch_order_with_isolation(DISPATCH_ORDER, ctx, lock_key_id: lock_id)
+          [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome]
+        rescue StaleWrite
+          attempt += 1
+          retry if attempt < MAX_STALE_WRITE_RETRIES
+          raise
+        end
+      end
+
+      private
+
+      # ONE HOP PER DOTTED SEGMENT — `ProcessManager.Handler.Dispatch.Bind`
+      # (once the dispatcher has already stripped "Domain::Aggregate.")
+      # walks Handler off the aggregate, then Dispatch off Handler, each
+      # step reading `.entities` exactly the way the single-level case
+      # always did — a nested entity is "structurally interchangeable
+      # with an aggregate" (Entity's own header) for precisely this
+      # reason. Two levels is what Handler/Dispatch need today ; nothing
+      # here assumes it stops at two.
+      def walk_entity_chain(aggregate, entity_names)
+        owner = aggregate
+        entity_names.map do |name|
+          found = owner.entities.find { |piece| piece.hecks_name == name } ||
+                  raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
+                                                           aggregate: owner.hecks_name, entity: name.inspect))
+          owner = found
+          found
+        end
+      end
+
+      # `extra_identity_heads:` — every entity `ctx.chain` walks through, not
+      # just the root aggregate `ArgumentGate` already knows about. A
+      # two-hop dispatch (`Handler.Dispatch.Bind`) is addressed by BOTH
+      # hops' own identity, each read straight out of `args` by
+      # `EntityElement#element_of` — refusing those as unknown would refuse
+      # every legitimate nested-entity dispatch there is, the same reasoning
+      # `ArgumentGate#refuse_unknown_arguments`'s own header gives for `:id`/
+      # the root's `identity_heads`.
+      def step_refuse_unknown_arguments(ctx)
+        step(:refuse_unknown_arguments) {
+          refuse_unknown_arguments(ctx.domain, ctx.aggregate, ctx.command, ctx.args,
+                                   extra_identity_heads: ctx.chain.flat_map(&:identity_heads))
+        }
+      end
+
+      # No `aggregate:` exemption to pass — that kwarg exists only for a
+      # port operation's own self-address (`ArgumentGate#refuse_absent_
+      # arguments`'s own comment); an entity command's chain identity never
+      # reaches `command.attributes` in the first place (resolved as
+      # addressing above, not as a declared fact), so there is nothing here
+      # for the exemption to need to strip.
+      def step_refuse_absent_arguments(ctx)
+        step(:refuse_absent_arguments) { refuse_absent_arguments(ctx.command, ctx.args) }
+      end
+
+      def step_normalize_args(ctx)
+        ctx.args = step(:normalize_args) { normalize_args(ctx.aggregate, ctx.command, ctx.args) }
+      end
+
+      def step_refuse_role_mismatch(ctx)
+        step(:refuse_role_mismatch) { @rules.refuse_role_mismatch(ctx.command, ctx.domain) }
+      end
+
+      def step_resolve_references(ctx)
+        step(:resolve_references) { @rules.resolve_references(ctx.domain, ctx.command, ctx.args) }
+      end
+
+      def step_hydrate_parent(ctx)
+        # `ctx.repository` is resolved once, in `#call`, before the
+        # isolation decision — not here any more.
+        ctx.instance = step(:hydrate_parent) {
+          parent(ctx.repository, ctx.aggregate, ctx.entity_name, ctx.command_name, ctx.args, ctx.route)
+        }
+      end
+
+      def step_locate_element(ctx)
+        ctx.element = step(:locate_element) {
+          EntityElement.locate_chain(ctx.aggregate, ctx.chain, ctx.instance, ctx.args, ctx.command_name, ctx.route)
+        }
+        # `view` was hydrated ONCE, here, into its OWN state hash
+        # (Value.hydrate builds a fresh Hash — never aliased with `element`)
+        # — exactly right for enforce_givens, which must read pre-mutation.
+        ctx.view = Instance.new(aggregate: ctx.entity, id: EntityElement.element_identity(ctx.entity, ctx.element).to_s,
+                                state: ctx.element)
+      end
+
+      def step_enforce_givens(ctx)
+        step(:enforce_givens) {
+          @rules.enforce_givens(ctx.view, ctx.command, ctx.args, domain: ctx.domain, declaring: ctx.entity, parent: ctx.instance)
+        }
+      end
+
+      def step_admissible_transition(ctx)
+        ctx.transition = step(:admissible_transition) { @rules.admissible_transition(ctx.entity, ctx.command, ctx.view) }
+      end
+
+      def step_apply_mutations(ctx)
+        ctx.old_element = ctx.element.dup unless ctx.command.ensures.empty?
+        step(:apply_mutations) {
+          ctx.command.mutations.each { |mutation|
+            EntityElement.apply_to_element(@rules, ctx.aggregate, ctx.entity, ctx.element, mutation, ctx.args)
+          }
+        }
+      end
+
+      def step_advance_lifecycle(ctx)
+        return unless ctx.transition
+
+        step(:advance_lifecycle) { ctx.element[ctx.entity.lifecycle.field] = ctx.transition.target }
+      end
+
+      # An ensures reads the SETTLED record, so it needs a view hydrated from
+      # `element` as it stands now, mutations included — unlike `view` above,
+      # built once and read pre-mutation by enforce_givens.
+      def step_enforce_ensures(ctx)
+        step(:enforce_ensures) do
+          settled = Instance.new(aggregate: ctx.entity, id: ctx.view.id, state: ctx.element)
+          @rules.enforce_ensures(settled, ctx.command, ctx.args, old: ctx.old_element, domain: ctx.domain, parent: ctx.instance)
+        end
+      end
+
+      # THE PARENT AGGREGATE's own invariants — `ctx.instance` is the
+      # parent record an entity mutation writes into (this file's own
+      # `Context` comment), the SAME boundary an aggregate-level
+      # invariant guards regardless of which interpreter changed it. No
+      # separate "entity invariant" exists (S10, ADR 0025 scopes
+      # `invariant` to the aggregate only) — see `Admissibility#
+      # enforce_invariants`'s own comment.
+      def step_enforce_invariants(ctx)
+        step(:enforce_invariants) { @rules.enforce_invariants(ctx.instance, ctx.aggregate, domain: ctx.domain) }
+      end
+
+      # `dry_run:` skips this — see CommandInterpreter#step_save's own
+      # comment, same reasoning and the same precedent
+      # (`step_assign_creation_attributes`'s own conditional-skip).
+      def step_save(ctx)
+        return if ctx.dry_run
+
+        step(:save) do
+          @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state)
+          # `expected_version:` — see CommandInterpreter#step_save's own
+          # comment: nil for a repository that isn't CAS-capable, or an
+          # instance never read from storage, either of which falls
+          # through to a plain save inside `AppendOnly#save`.
+          ctx.persistence_outcome = ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
+          if ctx.persistence_outcome.status == :stale
+            # NOT a `RefusalWording.render` call — see
+            # `CommandInterpreter#step_save`'s identical branch and
+            # `Runtime::StaleWrite`'s own comment.
+            raise(StaleWrite,
+                  "#{ctx.command.hecks_name} on #{ctx.aggregate.hecks_name} " \
+                  "(#{Identity.reading(ctx.aggregate)}: #{Rendering.describe(ctx.instance.id)}) lost a race — " \
+                  "another write committed against this record after it was read")
+          end
+        end
+      end
+
+      # `dry_run:` skips this too — nothing was committed, so `ctx.result`
+      # stays nil and `Dispatcher#dry_run?` never reads it.
+      def step_emit(ctx)
+        return if ctx.dry_run
+
+        ctx.result = step(:emit) { @rules.emit(ctx.command, ctx.domain, ctx.aggregate, ctx.instance, ctx.args, ctx.repository) }
+      end
+
+      # THE PARENT AGGREGATE, addressed exactly as `CommandInterpreter#hydrate`
+      # addresses one acting on itself — derive from the declared identity first
+      # (`Identity.of`), and let a bare `id:` name an already-derived record when
+      # the identity itself is not what the caller is holding.
+      def parent(repository, aggregate, entity_name, command_name, args, route = nil)
+        parent_id = route&.aggregate ||
+                    Identity.of(aggregate, args) ||
+                    Identity.from(aggregate, args, :id) ||
+                    raise(NotFound, RefusalWording.render("NotFound", "entity_parent_no_identity",
+                                                          command: command_name, aggregate: aggregate.hecks_name,
+                                                          entity: entity_name, identity: Identity.reading(aggregate)))
+        found = repository.find(parent_id) ||
+                raise(NotFound, RefusalWording.render("NotFound", "record_missing",
+                                                      aggregate: aggregate.hecks_name,
+                                                      identity:  Identity.reading(aggregate),
+                                                      offered:   Rendering.describe(parent_id)))
+        found.dup
+      end
+
+      # `locate_chain`/`element_of`/`element_identity`/`apply_to_element` and
+      # their own helpers used to live here — moved to `Runtime::EntityElement`
+      # (see that file's own header) so `CommandInterpreter`'s own
+      # `delegate_to_entity` step can locate and mutate the same element the
+      # same way, against an aggregate record already held in memory. `call`,
+      # above, and every `step_*` method reach them through that module now;
+      # nothing about the STEPS themselves changed.
+    end
+  end
+end

data/lib/hecks/runtime/errors.rb

@@ -0,0 +1,122 @@
+require_relative "value/invariant_violation"
+require_relative "../vocabulary"
+
+module Hecks
+  module Runtime
+    class UnknownVerb < StandardError; end
+    class EnsuresNotMet < StandardError; end
+    class GivenNotMet < StandardError; end
+    class NotFound    < StandardError; end
+    class LifecycleRefused < StandardError; end
+    class TypeMismatch < StandardError; end
+    # An argument the command does not declare. Sibling of TypeMismatch : that one
+    # is the right name carrying the wrong thing, this one is a name the command
+    # never had. Both are the payload gate refusing before any rule runs.
+    class UnknownArgument < StandardError; end
+    # The third of the trio, and the one that was missing : a name the command DOES
+    # declare, absent. TypeMismatch is the right name carrying the wrong thing,
+    # UnknownArgument a name that was never declared, AbsentArgument a declared name
+    # that never arrived. Between them they say a command takes exactly the
+    # arguments it declares — no others, and all of them.
+    class AbsentArgument < StandardError; end
+    # A creating command whose derived identity already names a record. The
+    # record it would have overwritten stands ; the dispatch that tried to
+    # mint a second one over it is what refuses.
+    class AlreadyExists < StandardError; end
+    # A declared, non-optional attribute a record predates — added since
+    # it was written, with no default: to fill it and no translation
+    # declaring what an old record should read there. `GuardState`
+    # (command_rules/admissibility.rb) is the one place this is raised: a
+    # `given`/`ensures`/`invariant` that reads the field would otherwise
+    # evaluate against a value nobody wrote, which is the same silent-
+    # wrong-answer class as an unpopulated projection reading "not
+    # active" (ADR 0025, "Added attributes and absence"). An OPTIONAL
+    # attribute in the same spot reads nil instead — that is what
+    # optional means, and this refusal is deliberately narrower than the
+    # nil-read it sits beside, not a replacement for it.
+    class AttributeAbsent < StandardError; end
+    # THE SAME SILENT-WRONG-ANSWER CLASS AS ABOVE, one line up — a
+    # `projects` field (S12, ADR 0025) this record predates, or that no
+    # rebuild sweep has populated yet, read by a `given`/`ensures`/
+    # `invariant` as though it carried a real value. `GuardState` is
+    # the one place this is raised, the same way AttributeAbsent is —
+    # a DECLARED field the record does not yet carry, distinguished
+    # from that one only in WHY: an ordinary attribute is absent
+    # because nobody backfilled it, a projected field is absent
+    # because nobody has swept it yet.
+    class ProjectionAbsent < StandardError; end
+    # A query or read model declares `authorize policy, tenant: :field` and
+    # the caller did not pass that field — the one half of `authorize` this
+    # runtime can enforce without a caller-identity system: the boundary
+    # itself, not whether the caller actually holds `policy`. See
+    # Runtime::TenantScope.
+    class Unauthorized < StandardError; end
+    # `corrects` names a past event this record must have already emitted
+    # (CommandBuilder#corrects_impl's own comment) — a fact the expression
+    # evaluator cannot check (it is not a predicate over the record's OWN
+    # fields, it is "did this exact record ever announce this"), so it is
+    # raised structurally, the same way AlreadyExists/NotFound are, rather
+    # than being expressible as an ordinary `given`. Raised by
+    # `CommandRules::Admissibility#enforce_correction_target`.
+    class NothingToCorrect < StandardError; end
+
+    # A RUNTIME FAULT, NOT A DOMAIN REFUSAL — deliberately absent from
+    # `DOMAIN_REFUSALS` below and from `vocabulary.bluebook`'s own
+    # `DomainRefusal` list. Raised when an optimistic-concurrency CAS write
+    # (`AppendOnly#save`'s `expected_version:`) finds the stored version has
+    # moved since this instance was read — someone else's write committed
+    # in between. `CommandInterpreter#call`/`EntityInterpreter#call` catch
+    # this themselves and retry the whole dispatch from a fresh hydrate, so
+    # `enforce_givens` re-evaluates against the now-current state; a caller
+    # only ever sees this escape when every retry is exhausted under
+    # sustained contention — an operational condition (many concurrent
+    # writers hammering one aggregate), not a business rule a domain author
+    # declared. See docs/decisions/ (concurrency-control ADR).
+    class StaleWrite < StandardError; end
+
+    # A Lambda-routed domain's own refusal (rust/host, `Runtime::
+    # RemoteDispatcher`), carrying Rust's own refusal text verbatim —
+    # NOT yet mapped back to the specific matching class above
+    # (GivenNotMet vs. EnsuresNotMet vs. ...), a real, known,
+    # documented gap: the WASM projector's own event/refusal-wording
+    # parity work (ADR 0021) makes the TEXT match Ruby's, but nothing
+    # yet parses that text back into a typed Ruby exception the way a
+    # local dispatch already raises one directly. Callers that only
+    # need "the domain said no" (not which specific rule) are
+    # unaffected; callers pattern-matching a SPECIFIC refusal class
+    # against a Lambda-routed domain are the ones this gap would bite.
+    class RemoteRefusal < StandardError; end
+
+    # The domain saying NO — the errors a reaction may legitimately meet and
+    # record as an undelivered outcome. A policy whose target refuses is a fact
+    # about the domain ; the originating command still stands.
+    #
+    # Everything ELSE is a defect : a NoMethodError in an interpreter, a
+    # NameError from a missing constant, a TypeError from a bad assumption. A
+    # blanket `rescue StandardError` used to fold both into one line —
+    # `delivered: false, reason: "..."` — so a crash in the runtime was
+    # indistinguishable from a rule doing its job, and read as normal operation
+    # in the log.
+    #
+    # UnknownVerb IS one of these, and deliberately : a cross-domain policy
+    # (`across "Notifications"`) fires in deployments where that domain is not
+    # loaded, and recording the undelivered reaction rather than raising is the
+    # design — spec/policy_spec states it in so many words, "records a reaction
+    # it cannot deliver rather than swallowing it".
+    # InvariantViolation belongs here and was missing. A value object refusing
+    # its own rule is the domain saying no as plainly as a given is — but the
+    # class is declared over in value.rb and never made the list, so the policy
+    # and saga interpreters, which rescue exactly these, would let it propagate
+    # as though the RUNTIME had broken. A reaction whose target violates an
+    # invariant is declined, not crashed. Found by spec/domain_refusal_spec on
+    # its first run : every corpus refusal must be a class named here, and 23
+    # of banking's were InvariantViolation.
+    # THE NAMES COME FROM THE LANGUAGE, the classes from this module.
+    # `DomainRefusal` declares WHICH refusals are the domain's own —
+    # a rule the caller broke — as against a runtime fault. Resolving
+    # each name here means a refusal declared but never defined fails
+    # at load with a NameError, rather than being quietly absent from
+    # a list nothing re-checks.
+    DOMAIN_REFUSALS = Hecks::Vocabulary.fetch("DomainRefusal").map { |name| const_get(name) }.freeze
+  end
+end

data/lib/hecks/runtime/event.rb

@@ -0,0 +1,51 @@
+require "time"
+
+module Hecks
+  module Runtime
+    # `correlation` is NOT on the wire — `to_h` below deliberately omits it,
+    # the same as `bin/run`'s own event projection does. It is runtime
+    # bookkeeping stamped by `Dispatcher#dispatch` when a saga leg's own
+    # dispatch causes this event (see `SagaInterpreter#deliver_saga_dispatch`
+    # and `#saga_correlation`) : a Hash of `correlation_head` -> correlation
+    # value, so an event caused by one saga cannot be misread by an unrelated
+    # one correlating on a different field. Absent for any event no saga
+    # dispatch caused, which is most of them.
+    Event = Struct.new(:name, :aggregate, :id, :payload, :occurred_at, :correlation, keyword_init: true) do
+      # AN EMITTED EVENT IS A RECORD OF SOMETHING THAT HAPPENED, and a
+      # mutable audit trail is not one. The PAYLOAD — the domain fact the
+      # event carries — is frozen THROUGH on emission: freezing the Hash
+      # alone would leave every value in it editable in place, which is
+      # the shape all four previous freezing bugs had.
+      #
+      # THE WHOLE EVENT, not just its payload. Correlation used to be
+      # merged onto already-emitted events by `Dispatcher#dispatch`, which
+      # is what kept an event writable after it had happened; it is set at
+      # construction now, because it is part of the transaction and known
+      # from `dispatch`'s own argument before anything is emitted.
+      #
+      # The LOG stays appendable: new events are still recorded. It is
+      # each event that stops changing once it exists.
+      def emit!
+        Freezer.deep(payload)
+        Freezer.deep(correlation)
+        freeze
+      end
+
+      def to_h
+        {
+          name:        name,
+          aggregate:   aggregate,
+          id:          id,
+          payload:     payload,
+          occurred_at: occurred_at
+        }
+      end
+
+      def to_s
+        "#{name}(#{aggregate}##{id}) #{payload.inspect}"
+      end
+
+      def inspect = "#<Event #{self}>"
+    end
+  end
+end

data/lib/hecks/runtime/identity.rb

@@ -0,0 +1,156 @@
+require_relative "../naming"
+require_relative "value"
+
+module Hecks
+  module Runtime
+    # THE SCALAR AN IDENTITY PATH NAMES.
+    #
+    # An identity is DECLARED as a path — `identified_by :number` — and
+    # this is the one place that reads one. It follows the path and nothing else.
+    #
+    # What it replaced was `Value.identifier`, which opened a one-field value
+    # object and took whatever was inside : that let `identified_by :number` pass
+    # for an identity, with the runtime guessing which field had been meant. The
+    # guess is gone. A declaration that names no field is now refused when the
+    # bluebook loads (`an aggregate that is identified names a field`, `an entity
+    # is known by a field`), so by the time anything is dispatched there is
+    # always a path here to follow.
+    #
+    # Usage:
+    #
+    #   Identity.scalar("number.value", account_number_value_object)  # => "acct-1"
+    #
+    module Identity
+      module_function
+
+      # A hash read that decides which spelling of a key answers by
+      # PRESENCE, never by `||` — a bare `||` treats a genuinely-held
+      # `false` the same as an absent key and falls through to the other
+      # spelling, landing on `nil` instead of the real, stored answer.
+      def hash_lookup(hash, key)
+        sym = key.to_sym
+        hash.key?(sym) ? hash[sym] : hash[key]
+      end
+
+      # The head names the ATTRIBUTE and is consumed by whoever looked the value
+      # up; what is left is the walk down into it. A path with no fields to walk
+      # — an aggregate that declares no identity and falls back to `id` — hands
+      # back what it was given, because there is nothing declared to dig for.
+      def scalar(path, held)
+        _head, *fields = path.to_s.split(".")
+        return held if fields.empty?
+
+        fields.reduce(Value.materialize(held)) do |dug, field|
+          dug.is_a?(Hash) ? hash_lookup(dug, field) : nil
+        end
+      end
+
+      # THE IDENTITY IS THE JOIN OF ITS PARTS, in declaration order. Shared by
+      # `CommandInterpreter` (an aggregate acting on itself) and
+      # `EntityInterpreter` (a piece addressed through its aggregate) — a piece
+      # declares an identity the same shape a head does, so it derives one the
+      # same way. `construct` answers `identity_paths` / `identity_heads` /
+      # `attribute` (an Aggregate or an Entity, either one) ; `value_owner`
+      # answers for coercion (`Value.for_attribute`'s first argument), which for
+      # an entity is its OWNING aggregate — an entity's value objects resolve
+      # through the aggregate's namespace, not its own.
+      #
+      # A part the payload does not carry makes the WHOLE identity unresolvable,
+      # rather than half of one. Half an identity names nothing, and joining what
+      # did arrive would silently name a different record on every dispatch — the
+      # precise failure that minting an id caused, arrived at by another road.
+      def of(construct, args, value_owner: construct)
+        paths = construct.identity_paths
+        return nil if paths.empty?
+
+        parts = paths.map { |path| from(construct, args, path, value_owner: value_owner) }
+        # A BLANK PART NAMES NOTHING, the same as an ABSENT one — AN ID IS A
+        # SCALAR, and "" is not a fact about anything. This used to check only
+        # `nil?`, so a canonical text extracted as "" (an expression whose
+        # source did not survive extraction) resolved to a REAL, empty-string
+        # identity — a record addressable by an id no caller could have meant.
+        return nil if parts.any? { |part| part.nil? || (part.respond_to?(:empty?) && part.empty?) }
+
+        Naming.identity(parts)
+      end
+
+      # A path digs into the value object that carries the identity, so what is
+      # stored is the SCALAR inside it rather than the object serialised whole.
+      def from(construct, args, key, value_owner: construct)
+        return nil unless key
+
+        head, *rest = key.to_s.split(".")
+        head = head.to_sym
+        return nil unless args.key?(head)
+
+        unless rest.empty?
+          held = args[head]
+          held = held.to_h if held.respond_to?(:to_h)
+          # AN ID IS ALWAYS A SCALAR. The path says WHICH FIELD carries it, so a
+          # caller may hand that field's value straight over — a string or a
+          # number, never a serialised object. Only a value object that actually
+          # arrived whole has to be opened.
+          return held.to_s unless held.is_a?(Hash)
+
+          return rest.reduce(held) { |h, f| h.is_a?(Hash) ? hash_lookup(h, f) : nil }&.to_s
+        end
+
+        # Coerced against the identity ATTRIBUTE only when the caller actually
+        # named it. A saga addresses an aggregate by its correlation key, and
+        # that key carries the id ALREADY RESOLVED — coercing "w1" against a
+        # WireReference asked the caller to pass fields for a value object they
+        # never mentioned.
+        attribute = construct.identity_heads.include?(head) ? construct.attribute(head) : nil
+        raw       = args[head]
+        return raw unless attribute
+
+        # AN ID IS ALWAYS A SCALAR — same contract the dotted branch above
+        # already keeps, just reached a different way here: a BARE
+        # (undotted) identity path names one of THIS construct's own
+        # declared attributes directly, and when that attribute's type is
+        # a value object (Translation's own compound `identified_by
+        # :domain, :from, :to`, each typed `TranslationDomainName`/
+        # `TranslationEraName`), `Value.for_attribute` coerces it into a
+        # real single-field Value wrapper — never unwrapped before this,
+        # so `Naming.identity`'s own plain `Array#join` (`Naming.identity`'s
+        # own header: parts must already be scalars) fell through to
+        # Ruby's default `Object#to_s`, leaking a raw, run-to-run-random
+        # memory address (`#<Hecks::Runtime::Value:0x...>`) into
+        # every refusal quoting this identity — found live via bin/fuzz on
+        # the self-hosted "translation" domain (replay_is_deterministic:
+        # the SAME address never repeats, so two replays of the
+        # identical steps produced different histories the moment a
+        # Translation went missing). `materialize_unwrapped` is the
+        # SAME single-field-VO-recurses-to-its-bare-scalar helper
+        # `read_model_interpreter.rb` already uses for exactly this
+        # unwrap; passthrough for anything that isn't a Value at all.
+        Value.materialize_unwrapped(Value.for_attribute(value_owner, attribute, raw)).to_s
+      end
+
+      # How an identity READS when the runtime has to name it in a refusal — the
+      # paths as they were declared, so the message quotes the bluebook back.
+      def reading(construct)
+        construct.identity_paths.join(", ")
+      end
+
+      # BEST-EFFORT, FOR A LOCK KEY ONLY — `Runtime::AggregateLock`'s own
+      # per-record striping needs SOME id to key on before dispatch has run
+      # far enough to hydrate for real, so this walks the identical chain
+      # `CommandInterpreter#hydrate_existing`/`#hydrate_prior_or_initial`
+      # and `EntityInterpreter#parent` already use to locate the real
+      # record — but wrapped to never raise. Choosing which Mutex to hold
+      # must never itself become a crash. `nil` means "could not resolve
+      # from the raw, pre-normalized payload this runs against" — the
+      # caller locks by aggregate type alone in that case (coarser, still
+      # correct, just less concurrent).
+      def best_effort(construct, args, route = nil, reference_key: nil)
+        route&.aggregate ||
+          of(construct, args) ||
+          from(construct, args, :id) ||
+          (reference_key && from(construct, args, reference_key))
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end