hecks 0.2.0 → 0.3.0

data/lib/hecks/runtime/era_guard.rb

@@ -0,0 +1,193 @@
+require "fileutils"
+require_relative "era_guard/shape_diff"
+require_relative "../bluebook/dsl/malformed"
+require_relative "../bluebook/meta_validator"
+require_relative "../naming"
+require_relative "../ports/loading"
+require_relative "../ports/persistence/lineage"
+require_relative "era_check"
+require_relative "registry"
+
+module Hecks
+  module Runtime
+    # Detects when a bluebook's storage shape has drifted from what its data
+    # was written under — a rename or restructure with nothing to explain
+    # it. Refuses at boot, before a command can run into the gap and raise
+    # something that only makes sense once you already suspect a rename.
+    #
+    # The held source is a snapshot of the bluebook text as it stood the
+    # last time its shape was accepted. It updates only when a drift is
+    # seen AND covered by a translation — never on every boot, and never
+    # silently when a rename has nothing to explain it.
+    module EraGuard
+      extend ShapeDiff
+
+      module_function
+
+      def check!(registry, directory)
+        registry.bluebooks.each_value { |bluebook| check_bluebook!(registry, bluebook, directory) }
+      end
+
+      def check_bluebook!(registry, bluebook, directory)
+        current_text = EraCheck.source_text_for(bluebook, directory)
+        return unless current_text
+
+        era_dir   = File.join(registry.root, "data", "eras")
+        held_path = File.join(era_dir, "#{Naming.snake(bluebook.name)}.bluebook")
+
+        FileUtils.mkdir_p(era_dir)
+        unless File.exist?(held_path)
+          File.write(held_path, current_text)
+          return
+        end
+
+        held_bluebook = shadow_parse(File.read(held_path, encoding: "UTF-8"), held_path)
+        drifted = false
+
+        bluebook.aggregates.each do |aggregate|
+          lineage = Ports::Persistence::Lineage.for(registry, bluebook.name, aggregate)
+          held_aggregate = held_bluebook.aggregate(lineage&.ancestor_name || aggregate.name)
+          next unless held_aggregate
+          next if shape(aggregate) == shape(held_aggregate)
+
+          drifted = true
+          uncovered = uncovered_attributes(aggregate, held_aggregate, lineage)
+          refuse_uncovered!(bluebook, aggregate, uncovered) unless uncovered.empty?
+
+          unsafe = unsafe_additions(aggregate, held_aggregate, lineage)
+          refuse_unsafe_addition!(bluebook, aggregate, unsafe) unless unsafe.empty?
+        end
+
+        check_vanished_aggregates!(registry, bluebook, held_bluebook)
+        File.write(held_path, current_text) if drifted
+      end
+
+      # An aggregate that existed in the held text and answers to no
+      # current name — renamed silently, with nothing declaring `was:` to
+      # explain where its data went — is exactly the disease this guards
+      # against, and a plain per-aggregate diff would never see it: the
+      # current aggregate simply has no held counterpart to compare to.
+      def check_vanished_aggregates!(registry, bluebook, held_bluebook)
+        held_bluebook.aggregates.each do |held_aggregate|
+          claimed = bluebook.aggregates.any? do |aggregate|
+            aggregate.name == held_aggregate.name ||
+              registry.translations.any? do |translation|
+                translation.domain == bluebook.name &&
+                  translation.for_aggregate(aggregate.name)&.was == held_aggregate.name
+              end
+          end
+          claimed ||= registry.translations.any? do |translation|
+            translation.domain == bluebook.name && translation.retired.include?(held_aggregate.name)
+          end
+          next if claimed
+
+          raise WiringError,
+                "cannot boot #{bluebook.name}: #{held_aggregate.name} existed and now doesn't, " \
+                "and nothing declares was: #{held_aggregate.name.inspect} to explain where its data went."
+        end
+      end
+
+      # The Layer-1 coverage refusal — one wording, whoever detects the
+      # gap (the file-store boot check here, or Postgres's mint path).
+      def refuse_uncovered!(bluebook, aggregate, uncovered)
+        raise WiringError,
+              "cannot boot #{bluebook.name}::#{aggregate.name}: its shape changed and " \
+              "#{uncovered.map { |path| render_path(path) }.join(', ')} #{uncovered.size == 1 ? 'is' : 'are'} not " \
+              "explained by any rename, move, convert, retype, or drop. Update bluebook/translations/*.bluebook, e.g. " \
+              "#{suggestion(uncovered.first)}."
+      end
+
+      # The addition-side sibling of refuse_uncovered! above — same
+      # wording shape, different cause: nothing vanished or changed type,
+      # something new arrived that an existing record has no way to hold.
+      def refuse_unsafe_addition!(bluebook, aggregate, unsafe)
+        raise WiringError,
+              "cannot boot #{bluebook.name}::#{aggregate.name}: #{unsafe.map { |name| ":#{name}" }.join(', ')} " \
+              "#{unsafe.size == 1 ? 'is new and required' : 'are new and required'}, with no default: to fill " \
+              "an existing record and no translation explaining what one should read there. Give it a " \
+              "default:, make it optional: true or list_of, or declare bluebook/translations/*.bluebook, e.g. " \
+              "`backfill :#{unsafe.first}, default: ...`."
+      end
+
+      def render_path(path) = path.include?(".") ? path.inspect : ":#{path}"
+
+      def suggestion(path)
+        if path.include?(".")
+          "`move #{path.inspect}, to: #{path.inspect}` or `drop #{path.inspect}`"
+        else
+          "`rename :#{path}, to: :new_name` or `drop :#{path}`"
+        end
+      end
+
+      # Parses held source into its own IR, in a scratch registry so a past
+      # era's text never touches the one actually booting.
+      #
+      # NORMAL PARSE FIRST, shadow only as a FALLBACK — not shadow-parsing
+      # unconditionally, which is what this used to do. A handful of DSL
+      # defaults fork on `MetaValidator.shadow_parsing?` for a reason
+      # that has NOTHING to do with syntax the live grammar can no longer
+      # read at all (`identified_by { }`, `belongs_to`, `has_one`,
+      # `has_many` — genuinely removed spellings, exactly what shadow-
+      # parsing exists to keep readable): `reference_to`'s own default
+      # mint name (`default_reference_name`, attribute_collector.rb)
+      # changed from `_id`-suffixed to bare under ADR 0025, and THAT fork
+      # applies even to text using nothing but current, live syntax.
+      # Held text minted under the CURRENT grammar — every real era in
+      # this corpus today, since nothing has ever minted a second one —
+      # parses fine normally; only the reference-naming DEFAULT differed
+      # once shadow mode engaged unconditionally, so it silently
+      # reconstructed a DIFFERENT shape (and hash) than a fresh parse of
+      # the identical text — the same text hashing two different ways
+      # depending on which code path read it, breaking `ensure_named!`'s
+      # own from/to edge lookup with a spurious "no translation edge
+      # covers it" refusal that has nothing to do with any real
+      # translation gap.
+      #
+      # A normal parse can only ever SUCCEED on text the live grammar
+      # fully understands — there is no way for it to silently produce a
+      # wrong-but-plausible answer for genuinely legacy text, since every
+      # removed spelling refuses loudly (`Malformed`) rather than
+      # degrading. So: try normal first — if the ordinary grammar reads
+      # this text without complaint, that IS the canonical, unambiguous
+      # interpretation, the same one `label_of`/`mint_hash` on the same
+      # source text always computes, whoever's asking. Only on a
+      # `Malformed` refusal — the one signal that actually means "this
+      # spelling doesn't exist anymore" — fall back to the legacy
+      # grammar, exactly as before this change. Any OTHER exception (a
+      # genuine syntax error, an unrelated validation refusal) propagates
+      # unchanged; swallowing it here to retry under shadow mode would
+      # risk masking a real defect in the held text behind a confusing
+      # second failure instead of the original, more specific one.
+      #
+      # `MetaValidator.while_shadow_parsing` (ADR 0025, docs/dsl-work-
+      # slices.md's S0a) is what makes the fallback a LEGACY grammar
+      # rather than just a second copy of today's: it stops
+      # `BluebookBuilder.build` from judging this text against the
+      # grammar as it stands NOW, which is the one thing that would make
+      # a removed spelling refuse HISTORY the day it is removed from
+      # live source. The scratch registry is throwaway either way —
+      # nothing here is dispatched against or exposed to the real one —
+      # so skipping the judge/assemble round-trip changes nothing this
+      # method reads: `shape`, `uncovered_attributes`, and friends only
+      # ever ask the built IR for its own structure.
+      def shadow_parse(source, path)
+        parse_bluebook(source, path, shadow: false)
+      rescue Hecks::Bluebook::DSL::Malformed
+        parse_bluebook(source, path, shadow: true)
+      end
+
+      def parse_bluebook(source, path, shadow:)
+        scratch = Registry.new
+        loading = Ports::Loading.bootstrap
+        run = lambda do
+          Hecks.with_registry(scratch) do
+            loading.load_library
+            Kernel.eval(source, TOPLEVEL_BINDING, path, 1)
+          end
+        end
+        shadow ? Hecks::Bluebook::MetaValidator.while_shadow_parsing(&run) : run.call
+        scratch.bluebooks.values.first
+      end
+    end
+  end
+end

data/lib/hecks/runtime/era_tamper.rb

@@ -0,0 +1,61 @@
+require "json"
+require "tempfile"
+require_relative "era_guard"
+require_relative "storage_shape"
+
+module Hecks
+  module Runtime
+    # The refusal wording for a held era whose digest no longer matches its
+    # frozen text — the digest mismatch alone is what DETECTS tampering (a
+    # plain SHA256 comparison over raw bytes, unrelated to any of this);
+    # this only supplies the wording once that's already fired.
+    #
+    # LIVES HERE, NOT UNDER `Ports::Persistence` — `project` below directly
+    # calls `Runtime::EraGuard.shadow_parse`/`Runtime::StorageShape.project`
+    # (DSL-execution machinery), the "an adapter/port reaches into the
+    # runtime instead of being handed already-computed data" shape that
+    # has caused trouble here before. A capability this dependent on the
+    # runtime is a runtime-owned one that the Postgres adapter CALLS, not
+    # a ports-level module that happens to reach sideways into it.
+    #
+    # Used to also distinguish a cosmetic edit from a real shape change
+    # here, by re-parsing the edited text — a pure quality-of-message
+    # nicety, not a safety property, since dropped: every tamper refusal
+    # reaches the same generic wording now, the one this already fell to
+    # whenever it couldn't classify an edit anyway. An operator judges
+    # "did this matter" themselves,
+    # reading the still-archived original — an anomalous recovery moment
+    # already, not a normal boot path.
+    module EraTamper
+      module_function
+
+      def refusal(domain:, ordinal:)
+        "cannot boot #{domain}: the held text of era #{ordinal} was edited after it was frozen — " \
+          "held era texts are storage facts; restore the original text, or reset the data"
+      end
+
+      # The storage-shape projection of a bluebook text, JSON-normalized
+      # for structural comparison against a stored projection; nil when
+      # the text does not load. ALWAYS parsed through a fresh tempfile,
+      # never the held file's own path: the predicate extractor caches
+      # source by path, and a held path whose content has changed (the
+      # very situation this module exists for) would hand it stale
+      # lines.
+      def project(text, _source_path = nil)
+        file = Tempfile.new(["hecks-tamper-", ".bluebook"])
+        begin
+          file.write(text)
+          file.flush
+          bluebook = EraGuard.shadow_parse(text, file.path)
+        ensure
+          file.close!
+        end
+        return nil unless bluebook
+
+        JSON.parse(JSON.generate(StorageShape.project(bluebook)))
+      rescue StandardError, SyntaxError
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/runtime/errors.rb

@@ -0,0 +1,100 @@
+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
+
+    # 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,128 @@
+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
+
+      # 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) ? (dug[field.to_sym] || 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) ? (h[f.to_sym] || 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
+    end
+  end
+end

data/lib/hecks/runtime/instance.rb

@@ -0,0 +1,120 @@
+require_relative "value"
+
+module Hecks
+  module Runtime
+    class Instance
+      attr_reader :aggregate, :id
+      attr_accessor :state
+
+      def initialize(aggregate:, id:, state: nil)
+        @aggregate = aggregate
+        @id        = id
+        @state     = state ? self.class.hydrate_with_defaults(aggregate, state) : self.class.defaults(aggregate)
+        materialize_identity!
+      end
+
+      # Loading existing state runs the same default-fill a fresh instance
+      # gets: an attribute the record predates — a newly-required field
+      # with a declared default:, a list added since the record was
+      # written — arrives filled instead of nil. Only declared defaults
+      # fill in; an attribute with no default stays absent, exactly as
+      # stored.
+      def self.hydrate_with_defaults(aggregate, state)
+        hydrated = Value.hydrate(aggregate, state)
+        defaults(aggregate).each do |name, value|
+          hydrated[name] = value unless value.nil? || hydrated.key?(name)
+        end
+        hydrated
+      end
+
+      def self.defaults(aggregate)
+        state = aggregate.attributes.each_with_object({}) do |attr, acc|
+          # FROZEN, like a list that has had something appended to it.
+          # An untouched list is the easiest one to miss and the easiest
+          # to mutate: nothing has replaced it yet, so a caller pushing
+          # into it writes straight into the aggregate's own state.
+          acc[attr.name] = attr.list? ? Freezer.deep([]) : default_for(aggregate, attr)
+        end
+        state[aggregate.lifecycle.field.to_sym] = aggregate.lifecycle.default if aggregate.lifecycle
+        state
+      end
+
+      def self.default_for(aggregate, attribute)
+        return Value.for_attribute(aggregate, attribute, attribute.default) unless attribute.default.nil?
+        # An entity's members hydrate through the same path but an entity
+        # declares no value objects of its own — nothing to default-build.
+        return nil unless aggregate.respond_to?(:value_object)
+
+        value_object = aggregate.value_object(attribute.type)
+        return nil unless value_object && value_object.attributes.all? { |field| !field.default.nil? }
+
+        Value.build(value_object, {}, aggregate)
+      end
+
+      def [](name) = @state[name.to_sym]
+
+      def key?(name) = @state.key?(name.to_sym)
+
+      def []=(name, value)
+        @state[name.to_sym] = value
+      end
+
+      def method_missing(name, *args)
+        return @state[name] if @state.key?(name)
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @state.key?(name) || super
+      end
+
+      # `id: @id` LAST, not first — see Facade::Handle#to_h's own comment
+      # for the full story (the same fix, landed there first): an
+      # aggregate free to declare its own attribute literally named `id`
+      # (BurningManPrep's `Item`, `attribute :id, ItemId`) has that
+      # attribute's own wrapped value object sitting in `@state[:id]` —
+      # merging `@state` on top of `{ id: @id }` let it silently clobber
+      # the correct bare identity. `@id` merged last always wins.
+      def to_h = @state.merge(id: @id)
+
+      # A COPY A MUTATION MAY TOUCH. Every adapter but Memory hands `find`
+      # a freshly-decoded Instance already; Memory's holds the record it
+      # eventually saves — the SAME state Hash, aliased. Before `ensures`
+      # existed, nothing could refuse between apply_mutations and save, so
+      # that aliasing was invisible: a dispatch either ran to completion or
+      # raised before touching state at all. `ensures` is the first refusal
+      # to sit AFTER mutation, and it found the bug the moment it did — an
+      # in-memory record left half-mutated by a dispatch that then refused.
+      # `command_interpreter`/`entity_interpreter` hydrate an EXISTING
+      # record through this, never through the adapter's own return value
+      # directly, so a refused ensures leaves the stored record untouched
+      # regardless of which adapter is holding it.
+      def dup
+        copy = super
+        copy.state = @state.dup
+        copy
+      end
+
+      def inspect
+        fields = @state.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+        "#<#{@aggregate.hecks_name} #{@id} #{fields}>"
+      end
+
+      private
+
+      def materialize_identity!
+        identity  = @aggregate.identified_by || :id
+        attribute = @aggregate.attribute(identity)
+        return unless attribute && @state[identity].nil?
+        # Several paths under one head mean the identifier is a display key,
+        # not a reversible serialization of the structured value object. A
+        # creating command supplies that object explicitly; persisted state
+        # hydrates it from storage. Never guess by splitting the joined id.
+        return if @aggregate.identity_heads.one? && @aggregate.identity_paths.size > 1
+
+        @state[identity] = Value.from_identifier(@aggregate, attribute, @id)
+      end
+    end
+  end
+end