axn 0.1.0.pre.alpha.6 → 0.1.0.pre.alpha.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96629802248edd18b5c1d3607b7aa3ad6775c9185a8667808f4d81ae98cfb69e
-  data.tar.gz: 66185b1f3f784c7a4c57680ed7b1fdcda1ae958904b69d53dfa003fb50c88286
+  metadata.gz: 259cd996e88bc18c257764dcdbf09b8329d9455a468508db610fdee30312bdd0
+  data.tar.gz: 5ad4e15519eb9a4d8af7b4ebff976c2455411e46b24073a43c8d054e78a88798
 SHA512:
-  metadata.gz: bc8ffc522d6226bcb15f401d42f23560cec3fd0497d30f710456d2b68f12c1238c5ca6453f151aec00baddebfe707b619a649177c62779f6db0cf44eb43e84fb
-  data.tar.gz: 8bd82a4adf9fd10a612ae70ff4abfc7b37284970dbed31a6e615c5d842b8384e51ad9ff17b1a6914738257fc2bc2d86ce374fa8d18a21019f069e19e300653dd
+  metadata.gz: 766cf539c8c8dde70ab669b8dbed304b1e2b8359910b0a187502971db9175e72bf5f8041db02fa60be5327fc1d212e89258c8140a6434b9de368705fc66d6292
+  data.tar.gz: f0d4cea99d2a124ec1f0dbe3f475a2ec900d4fd3221d3e3d5529f9b01bb3efe1e3fe4f629433c7de23e2a98dee7852402a4ec48799aa8672b3505f13abdb6a53

data/AGENTS-consuming.md

@@ -165,8 +165,17 @@ expects :user, model: true
 `user_id` always means *the record's primary key*, on every path. Passing both a record and a
 disagreeing `user_id` (default `:find` finder) raises `InboundValidationError` — contradictory
 input is a developer error. `klass:` must be a single Class/Module (no union, no `type:`-style
-pseudo-type); anything else raises `ArgumentError` at declaration. Source:
-`lib/axn/core/field_resolvers/model.rb`.
+pseudo-type); anything else raises `ArgumentError` at declaration. The `model:` bag only accepts
+`klass:`/`finder:`/`not_found_on:`/`id_type:`/`message:` (plus the shared ActiveModel options) — a
+typo'd key (`fnder:`, `class:` for `klass:`) raises `ArgumentError` too, rather than silently
+falling back to the default. Source: `lib/axn/core/field_resolvers/model.rb`.
+
+**No record found is a contract violation, not a reported exception.** A finder returning `nil` and
+one raising its not-found error (`ActiveRecord::RecordNotFound` for `:find`) are the same outcome:
+an `InboundValidationError` reading `User not found` — distinct from the `User can't be blank` an
+omitted `user_id` gets. It is NOT handed to `on_ignored_exception`, so a bad id from a tool caller
+never pages; anything else the finder raises still does. Name your own miss class with
+`model: { finder: :fetch!, not_found_on: MyApi::NotFound }` (a `StandardError` subclass or an array of them; `[]` opts out).
 
 **`on:` — subfields (the `:extract` resolver).** Declare expectations about nested data and get a
 flat reader:

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.0-alpha.6.1
+
+### Added
+
+* [FEAT] `Axn::Failure` exposes `originating_axn_class` and `originating_result`, giving failure handlers the failing axn's class and its result (including exposures made before `fail!`) without reaching through the action instance. The readers are defined on `Axn::Failure` only and are nil when the failure was not raised by an axn.
+* [FEAT] A `model:` field's generated `<field>_id` is typed in `.input_schema`. ActiveRecord models using the default `:find` finder infer Integer, String, or UUID from the model's primary key; `model: { id_type: Integer }`/`String`/`:uuid` provides an explicit override for POROs, custom finders, or unavailable database metadata.
+
+### Changed
+
+* [BREAKING] A `model:` lookup that means “not found” is now treated as an inbound validation failure, whether the finder returns `nil` or raises its configured not-found exception. This removes duplicate `best_effort`/`on_exception` noise for expected bad identifiers: required fields report one `Axn::InboundValidationError`, optional fields remain quiet, and tool-facing input errors are not reported. Other finder failures are still swallowed to `nil` and reported. `model: { finder:, not_found_on: <class or array> }` defines the not-found exception set for custom finders; an empty set opts out.
+* [BREAKING] `Axn::Result#declared_fields` is now `#__declared_fields__`; `declared_fields`, along with `context`, `action`, `action_name`, `default_error`, and `default_success`, is available for field declarations. There is no compatibility alias for the result reader.
+* [BREAKING] Unknown keys in `model:`, `type:`, `validate:`, and `shape:` option bags now raise at declaration instead of being silently ignored. The check applies consistently to top-level fields, subfields, shapes, `of:` positions, map axes, and `Axn::Factory.build`.
+* [BREAKING] Explicit subfields now conjoin with an enclosing `shape:` member during schema generation, preserving the full declared shape and requiredness instead of silently replacing the member with a bare object. Model-generated `<field>_id` keys that collide with emitted nested objects are rejected at declaration.
+* [FEAT] Validation errors rooted at `on: :ambient_context` identify that source in their rendered message, including nested and model-consistency errors, without changing structured error details.
+* [BREAKING] The ActiveModel/ActiveSupport dependency floor is now `>= 8.1`.
+
+### Fixed
+
+* [BUGFIX] `fails_on` now accepts multiple exception classes positionally, and `error`/`success`/`fails_on` reject invalid message values at declaration instead of misclassifying them or placing non-message objects in results.
+* [BUGFIX] `Axn::Factory.build` correctly splats arrays for hook declarations and preserves single handlers that happen to implement `to_a`/`to_ary`; callbacks, memo declarations, and shape-block fields also support multiple entries in one call.
+* [BUGFIX] A missing `model:` record produces one accurate validation error—“not found” when an id was supplied, “can't be blank” when it was omitted—instead of combining type and presence errors.
 ## 0.1.0-alpha.6
 
 ### Added

data/lib/axn/async/batch_enqueue.rb

@@ -124,7 +124,7 @@ module Axn
         # @example Count-only heartbeat via a class method
         #   on_enqueue_all :log_summary
         #   def self.log_summary(count:) = info "Found #{count} events"
-        def on_enqueue_all(handler = nil, **, &block) = _add_callback(:enqueue_all, handler:, **, block:)
+        def on_enqueue_all(*handlers, **, &block) = _add_callback(:enqueue_all, handlers, **, block:)
       end
     end
   end

data/lib/axn/core/context/facade.rb

@@ -26,7 +26,7 @@ module Axn
         (@declared_fields + Array(implicitly_allowed_fields)).each do |field|
           # Never define over a name the facade ITSELF answers to — its own ancestry up to Object,
           # private methods included, since those are the ones it dispatches on itself
-          # (`default_error`, `_msg_resolver`). Declarations that would land such a name are refused up
+          # (`_default_error`, `_msg_resolver`). Declarations that would land such a name are refused up
           # front (Contract::ClassMethods#_reject_shadowed_exposure_name! and its inbound twin); this is
           # the definition-site half of that rule, so a config reaching a facade without passing through
           # the DSL cannot silently take a method away. Object/Kernel are deliberately NOT asked: an
@@ -38,9 +38,12 @@ module Axn
         end
       end
 
-      attr_reader :declared_fields
+      # Namespaced like `Axn::Result`'s `__action__`/`__exposed_keys__` rather than left as
+      # `declared_fields`: every name this class owns is one an `expects`/`exposes` declaration may not
+      # take, so the facade's own surface stays out of the namespace an author writes field names in.
+      def __declared_fields__ = @declared_fields
 
-      def inspect = ContextFacadeInspector.new(facade: self, action:, context:).call
+      def inspect = ContextFacadeInspector.new(facade: self, action: _action, context: _context).call
 
       def fail!(...)
         raise Axn::ContractViolation::MethodNotAllowed, "Call fail! directly rather than on the context"
@@ -48,7 +51,14 @@ module Axn
 
       private
 
-      attr_reader :action, :context
+      # Underscored, like everything else this class owns. The facade's method table IS the set of
+      # field names a declaration is refused (Contract::ClassMethods#_reject_shadowed_wire_key! and
+      # its exposure twin ask it by ownership), so a helper named `action` or `context` would take two
+      # ordinary domain words away from every author while offering them nothing — neither name is
+      # reachable from an action or documented anywhere. Keep new helpers here underscored;
+      # spec/axn/core/context/facade_name_surface_spec.rb enforces it.
+      def _action = @action
+      def _context = @context
 
       # Define one field's reader. The base (outbound Result) facade reads the data source directly;
       # InternalContext overrides this to resolve declared inbound fields through the read path.
@@ -62,9 +72,9 @@ module Axn
         end
       end
 
-      def _model_fields = action.class._model_fields
+      def _model_fields = _action.class._model_fields
 
-      def action_name = @action.class.name.presence || "The action"
+      def _action_name = @action.class.name.presence || "The action"
 
       def _define_model_field_method(field, options)
         Axn::Internal::Memoization.define_memoized_reader_method(@__singleton, field) do
@@ -81,9 +91,9 @@ module Axn
 
       def _msg_resolver(event_type, exception:)
         Axn::Core::Flow::Handlers::Resolvers::MessageResolver.new(
-          action.class._messages_registry,
+          _action.class._messages_registry,
           event_type,
-          action:,
+          action: _action,
           exception:,
         )
       end

data/lib/axn/core/context/facade_inspector.rb

@@ -115,7 +115,7 @@ module Axn
       def rendered_field_name(field) = Axn::Internal::Reflection::PropertyNames.renderable_label(field)
 
       def class_name = facade.class.name
-      def declared_fields = facade.send(:declared_fields)
+      def declared_fields = facade.__declared_fields__
 
       def format_for_inspect(field, value)
         return value.inspect if value.nil?

data/lib/axn/core/context/internal.rb

@@ -6,8 +6,13 @@ module Axn
   module Core
     # Inbound / Internal ContextFacade
     class InternalContext < ContextFacade
-      def default_error = _msg_resolver(:error, exception: Axn::Failure.new).resolve_default_message
-      def default_success = _msg_resolver(:success, exception: nil).resolve_default_message
+      # Underscored for the same reason as everything else on the facade (see ContextFacade's private
+      # section): the method table is the set of field names a declaration is refused. Public despite the
+      # underscore — the action-side `default_error`/`default_success` sugar dispatches these by name,
+      # and that pair stays unprefixed because Contract::InstanceMethods is surrenderable, so a field
+      # may take it and lose nothing but the helper.
+      def _default_error = _msg_resolver(:error, exception: Axn::Failure.new).resolve_default_message
+      def _default_success = _msg_resolver(:success, exception: nil).resolve_default_message
 
       private
 
@@ -17,16 +22,16 @@ module Axn
       # provided_data never mutated). A field with no config (implicitly-allowed) keeps the raw source
       # read. Model fields resolve through the shared resolve_model_value (record + sibling-id + default).
       def _define_reader_for(field)
-        config = action.class.internal_field_configs.find { |c| c.field == field }
+        config = _action.class.internal_field_configs.find { |c| c.field == field }
         return super if config.nil?
 
         if config.validations.key?(:model)
           Axn::Internal::Memoization.define_memoized_reader_method(@__singleton, field) do
-            Axn::Core::ContractForSubfields.resolve_model_value(action, config, config.validations[:model])
+            Axn::Core::ContractForSubfields.resolve_model_value(_action, config, config.validations[:model])
           end
         else
           @__singleton.define_method(field) do
-            Axn::Core::ContractForSubfields.resolve_value(action, config)
+            Axn::Core::ContractForSubfields.resolve_value(_action, config)
           end
         end
       end
@@ -36,7 +41,7 @@ module Axn
           msg = <<~MSG
             Method ##{method_name} is not available on Axn::Core::InternalContext!
 
-            #{action_name} may be missing a line like:
+            #{_action_name} may be missing a line like:
               expects :#{method_name}
           MSG
 

data/lib/axn/core/contract/shape_declaration.rb

@@ -117,6 +117,7 @@ module Axn
         # declared no `shape:` must not gain the key here.
         def _snapshot_declared_shape!(validations, allowance, fields)
           _reject_unshaped_shape!(validations, "`shape:` on #{_declared_fields_label(fields)}")
+          _reject_unknown_shape_keys!(validations, "`shape:` on #{_declared_fields_label(fields)}")
           shape = Internal::ShapeGraph.hash_or_nil(validations[:shape])
           return if nil.equal?(shape)
 
@@ -169,6 +170,48 @@ module Axn
                 "`ArgumentError: must supply :members`. Supply `shape: { members: [...] }`, or drop shape:."
         end
 
+        # THE key-set refusal for a `shape:` node (PRO-3387), at the same four positions
+        # `_reject_unshaped_shape!` reaches: a field's own, a shape MEMBER's, an `of:` element bag's, and either
+        # axis of a map (the last two share one call site, `_snapshot_inner_shape!`). `members:`/`container:`
+        # are the only two keys `ShapeValidator` reads (`ClassMethods::SHAPE_OPTION_KEYS`) — everything else
+        # declared cleanly and constrained nothing, the same hole `_reject_unknown_bag_keys!` already closes for
+        # `of:`/`model:`/`type:`/`validate:`. `where` is the same label its `_reject_unshaped_shape!` sibling
+        # takes at every call site — passed rather than recomputed, so the two guards read the position
+        # identically and neither can name it differently from the other.
+        #
+        # Stands down on a non-Hash `shape:` — that is `_reject_unshaped_shape!`'s defect one line up, and
+        # firing here too would report a bare `ArgumentError: must supply :members` graph as also missing keys
+        # it never had a chance to name.
+        #
+        # Raises ITSELF, rather than deferring, for a shape that ANSWERS a missing key from a Hash default
+        # (`Hash.new(…)` or a `default_proc`) — `copy_entries` below is entry-wise, so a `members:`/`container:`
+        # the shape only ANSWERS is invisible to it, and every REAL entry beside it (however few) reads as
+        # unknown. This used to defer to `_walk_shape_graph!`'s own `reject_defaulting_option_container!` call,
+        # on the assumption that it always runs after this one — true when there is no block, but this guard
+        # ALSO runs ahead of a block/subblock overwrite (PRO-3387, Codex round 2, PR #275), and that overwrite
+        # replaces `validations[:shape]` before `_walk_shape_graph!` ever reaches the ORIGINAL defaulting Hash
+        # — so deferring there let a defaulting raw shape beside a block skip this check entirely, real
+        # entries included. Raising here closes that: the SAME shared helper, so the underlying defect is
+        # named identically wherever it is caught, and `_walk_shape_graph!`'s own call stays as a backstop for
+        # the one position this method is never asked about (a shape reached via `internal_field_configs=`,
+        # which skips the whole declaration walk).
+        #
+        # `:shape` is the one entry `ShapeGraph.detach_option_containers!` deliberately skips — the field's own
+        # validations bag is detached there, but the shape graph beneath it is walked and copied by this
+        # module's own machinery instead — so the Hash handed here is still the CALLER's own object. Read
+        # through `ShapeGraph.copy_entries` (the bound `each` seam) rather than a direct `.keys`, which a
+        # caller-defined Hash subclass could answer with anything: the same discipline `_symbol_keyed_bag`
+        # already reads a caller-supplied bag by.
+        def _reject_unknown_shape_keys!(carrier, where)
+          return unless Internal::ShapeGraph.carries_key?(carrier, :shape)
+
+          shape = Internal::ShapeGraph.hash_or_nil(carrier[:shape])
+          return if nil.equal?(shape)
+
+          Internal::ShapeGraph.reject_defaulting_option_container!(shape) { where }
+          _reject_unknown_bag_keys!(Internal::ShapeGraph.copy_entries(shape), ClassMethods::SHAPE_OPTION_KEYS, option: "shape:")
+        end
+
         # THE refusal for a raw `shape:` kwarg asking to distribute — the reading PRO-3191 retires. Checked at
         # every position a raw kwarg can occupy, ahead of the block form's own write to the same slot (a block
         # legitimately builds a distributing shape; a raw kwarg no longer may), so `carrier` is passed rather
@@ -369,6 +412,7 @@ module Axn
         # what a member's nested shape contributes to its node's height.
         def _snapshot_inner_shape!(bag, walk, allowance, fields:, position:, via:, via_name:)
           _reject_unshaped_shape!(bag, _inner_shape_position_label(position, via, via_name, fields))
+          _reject_unknown_shape_keys!(bag, _inner_shape_position_label(position, via, via_name, fields))
           shape = Internal::ShapeGraph.hash_or_nil(bag[:shape])
           return NO_INNER_CONTRACTS if nil.equal?(shape)
 
@@ -601,6 +645,7 @@ module Axn
           # pre-pass, leaving no top-level `shape:` for this read to find.
           _reject_distributing_shape!(validations, "`shape:` on shape member #{_describe_shape_member(member, name)}")
           _reject_unshaped_shape!(validations, "`shape:` on shape member #{_describe_shape_member(member, name)}")
+          _reject_unknown_shape_keys!(validations, "`shape:` on shape member #{_describe_shape_member(member, name)}")
           nested = Internal::ShapeGraph.hash_or_nil(validations[:shape])
           return NO_INNER_CONTRACTS if nil.equal?(nested)
 
@@ -966,7 +1011,7 @@ module Axn
                 :_raise_member_confirmation_unsupported!,
                 :_snapshot_declared_shape!, :_validate_and_snapshot_shape!, :_walk_shape_graph!,
                 :_distributing_shape_depth,
-                :_reject_unshaped_shape!, :_reject_distributing_shape!,
+                :_reject_unshaped_shape!, :_reject_unknown_shape_keys!, :_reject_distributing_shape!,
                 :_distributing_shape_message, :_distributing_container_message,
                 :_inner_shape_position_label,
                 :_walk_inner_contracts!, :_walk_declared_inner_contracts!, :_new_path_allowance,

data/lib/axn/core/contract/subfield_contradictions.rb

@@ -33,9 +33,218 @@ module Axn
           check_unanswerable_segments!(tree) # first: an unreachable path moots any ambiguity on it
           check_subfields_under_map!(tree)
           check_ambiguous_crossings!(tree) if crossings
+          check_model_id_object_claim!(tree, field_configs)
           check_dead_nil_tolerance!(tree, field_configs)
         end
 
+        # The subfield-free entry point. `check!` is skipped outright by the top-level seam when no subfield
+        # exists, on the documented grounds that with an empty tree no tolerance is unexercisable and no
+        # segment is read. That reasoning does not extend to the model-id claim, which needs no subfield at
+        # all — a top-level `<field>_id` carrying its own `shape:` block claims the key on its own — so the
+        # top-level seam routes here instead of skipping everything.
+        #
+        # Returns without building a tree when no `model:` is declared, which is what keeps the
+        # per-declaration build off the subfield-free path for every contract that cannot trip this.
+        def check_model_id_claims!(field_configs)
+          return if field_configs.none? { |c| c.validations[:model] }
+
+          tree = Axn::Internal::SubfieldTree.build(field_configs, [])
+          check_model_id_object_claim!(tree, field_configs)
+        end
+
+        # The MODEL-ID OBJECT-CLAIM check (PRO-3396): a `model:` field's generated `<field>_id` names the
+        # LOOKUP TOKEN the finder consumes — a scalar. Another declaration can claim that same wire key as an
+        # object WITH CONTENTS: a dotted `on:` whose intermediate segment is spelled `<field>_id`, an explicit
+        # `<field>_id` that a subfield then nests under, or a `shape:` member of that name carrying its own
+        # `members:`. One wire key cannot be both, and the emitter reconciled neither pair — `apply_model_id_child!`
+        # recognizes a sibling only by its `configs`, so an implicit intermediate is invisible to it, while
+        # `apply_implicit_node!` does not know a model's generated id might be underneath. Whichever ran second in
+        # the insertion-ordered walk simply overwrote the other, so the surviving property followed declaration
+        # order and the loser's contribution vanished silently.
+        #
+        # Refused rather than reconciled, because there is no coherent schema to emit: the property is either the
+        # scalar the finder reads or the object the descendant is read out of. A PLAIN scalar `<field>_id` sibling
+        # is untouched — that is the supported spelling, and the one `sibling_id_configs` exists to serve.
+        #
+        # The object claim is judged by what the emitter would actually NEST, not by the claimant's declared type:
+        # `node_configs_block_nesting?` is the same predicate emission and the drop pass consult, so a node whose
+        # children are dropped (a scalar or `model:` route at the id key) raises nothing here — an unreachable
+        # segment is `check_unanswerable_segments!`'s to report, and it runs first.
+        #
+        # THE CLAIM IS THE ONE THE EMITTER WRITES. That scope is what makes this check answerable at
+        # declaration, and it is why no `if:`/`unless:` is consulted anywhere below: input reflection is
+        # static-maximal, so a gated declaration is advertised exactly as an ungated one is and the document
+        # carries the collision either way. A member reached through an EXPLICIT intermediate is such a claim
+        # like any other: the emitter conjoins it with the node's own property rather than replacing it
+        # (PRO-3399), so nothing here has to ask whether a runtime-only claim is enforced on a given call —
+        # a question about ActiveModel's gate resolution that would have had to be re-derived here, and the
+        # reason the case was once out of scope.
+        def check_model_id_object_claim!(tree, field_configs)
+          tree.index.each do |config, path|
+            next unless config.validations[:model]
+            # A model under a `model:` (or otherwise non-nestable) ancestor is never nested by the emitter at
+            # all — `apply_nested_subfields!` stops at the blocking node — so neither this model's generated
+            # id nor anything beneath it reaches the document, and there is no emitted claim to collide with.
+            # Asked through `path_blocked?`, the drop pass's own predicate, so what this skips and what
+            # emission omits cannot drift.
+            next if Axn::Internal::Reflection::Schema.path_blocked?(path.ancestors)
+
+            id_key = Internal::FieldConfig.model_id_key(config.field)
+            claim = model_id_object_claimant(tree, path, field_configs, id_key)
+            raise_model_id_object_claim!(config, *claim, id_key) if claim
+          end
+        end
+
+        # The declaration that claims `id_key` as an object with contents, or nil. Two positions, mirroring the
+        # two the emitter reads a sibling from: at depth the id key is a CHILD of the model's own wire parent
+        # (`apply_model_id_child!` reads `children[id_field]`), at depth 0 it is another top-level config's own
+        # node (`build_input` scans `field_configs` by wire key — not `tree.roots`, which is keyed by reader name
+        # and so misses an aliased declaration of the same wire key).
+        #
+        # A model route at the id key is excluded on both sides: such a config emits its own generated id one
+        # level deeper (`<key>_id_id`) and never writes this key at all, the same exclusion `build_input` and
+        # `apply_model_id_child!` already apply when they look for an explicit sibling.
+        def model_id_object_claimant(tree, path, field_configs, id_key)
+          if path.ancestors.empty?
+            sibling_nodes = field_configs.filter_map do |c|
+              tree.index[c].node if c.field == id_key && !c.validations[:model]
+            end
+            descendant = sibling_nodes.filter_map { |node| claiming_descendant(node) }.first
+            return descendant && [descendant, :nested]
+          end
+
+          parent = path.parent_node
+          nested = parent.children[id_key]
+          descendant = nested && claiming_descendant(nested)
+          return [descendant, :nested] if descendant
+
+          member = claiming_shape_member(Axn::Internal::Reflection::Schema.emitted_shape_sources(path), id_key)
+          member && [member, :member]
+        end
+
+        # The declaration whose nesting under `node` makes the key an object. Nil when its own configs forbid
+        # nesting (a scalar or `model:` route there emits no object property, so nothing collides with the id).
+        #
+        # Two sources of contents, because a node has two. Subfield CHILDREN are the tree's own; a node's own
+        # `shape:` MEMBERS are not children at all and so were invisible to a `children`-only test — measured,
+        # `expects :company_id, on: :payload, type: Hash do … end` beside a `model:` emitted the member's
+        # object and dropped the model's id entirely, while the resolver still read that Hash as its token.
+        # The block applies to the CHILDREN only. `node_configs_block_nesting?` gates `apply_nested_subfields!`,
+        # which is what declines to nest subfield children — but the node's own property was already built by
+        # `build_property`, and `apply_structured_schema!` merged the representative's own `shape:` members
+        # into it on the way. So a merged node carrying a `model:` route beside a non-model route with its own
+        # members still emits that object, and returning early on the block missed it entirely.
+        def claiming_descendant(node)
+          nested = first_config_below(node) unless Axn::Internal::Reflection::Schema.node_configs_block_nesting?(node.configs)
+
+          nested || claiming_own_member(node)
+        end
+
+        # A member declared by the node's OWN `shape:` — the representative route's, which is the one
+        # `apply_structured_schema!` merges into the emitted property.
+        def claiming_own_member(node)
+          first_declared_member(Array(Axn::Internal::Reflection::Schema.property_representative(node.configs)))
+        end
+
+        def first_declared_member(configs)
+          configs.each do |config|
+            contents = object_contents_of(config)
+            return contents if contents
+          end
+          nil
+        end
+
+        # What `config` contributes as object CONTENTS at its own node, or nil. Two sources, because a member
+        # list is not the whole of what gets emitted:
+        #
+        #   * its DECLARED members, returned as the member config itself so the message can name the
+        #     declaration the author wrote; and
+        #   * the properties reflection INFERS, which `shape_property_plan` seeds from a structured `type:`
+        #     whenever an `of:`/`shape:` key is present at all. A `Data`-typed member with an explicitly
+        #     EMPTY `shape: { members: [] }` declares nothing and still emits its type's own members — an
+        #     object property where the lookup token belongs — so reading the raw list alone let it through.
+        #     There is no config to name for one of these, so the property NAME is returned instead.
+        #
+        # `in_items` is excluded: there the shape describes the ARRAY'S ELEMENTS rather than the node, so the
+        # node is emitted as an array and is no object parent. Declared members are asked first, so the
+        # existing answer (and the existing message) is unchanged wherever one exists.
+        def object_contents_of(config)
+          declared = Axn::Internal::Reflection::Schema.named_members(config.validations.dig(:shape, :members)).first
+          return declared.first if declared
+
+          plan = Axn::Internal::Reflection::Schema.shape_property_plan(config, for_output: false)
+          return nil unless plan.emitted && !plan.in_items
+
+          plan.base_properties.keys.first
+        end
+
+        # Descends the way the EMITTER does, not the way the tree is shaped. A child the emitter declines to
+        # nest contributes no property, so it is no part of the claim: `apply_implicit_node!` drops an
+        # implicit child that collides with a non-nestable `shape:` member (a scalar, a mixed union) along
+        # with everything beneath it, leaving the parent emitted as a bare object with empty `properties`.
+        # A raw recursive walk still found the dropped descendant and reported it as nesting under the key,
+        # which was wrong twice over — the declaration was refused, and the message named a path the schema
+        # never emits.
+        #
+        # Asked through `path_blocked?`, the drop pass's own judgment and the same one `PropertyNames`
+        # consults per hop, so what this descends into and what emission nests cannot drift. The whole hop
+        # chain is passed each time rather than a carried-member accumulator, because that predicate carries
+        # internally from the start of the chain — and it is the PUBLIC half of the pair (`blocking_ancestor?`
+        # and `merged_shape_members` are private to reflection on purpose), so mirroring it needs no widening
+        # of that module's surface.
+        #
+        # An EXPLICIT child is always emitted as a property — `apply_children!` writes it unconditionally —
+        # and `path_blocked?` reports that hop unblocked, so it still counts as contents.
+        def first_config_below(node, hops = [])
+          node.children.each do |key, child|
+            chain = hops + [[node, key]]
+            next if Axn::Internal::Reflection::Schema.path_blocked?(chain)
+
+            return child.config if child.config
+
+            deeper = first_config_below(child, chain)
+            return deeper if deeper
+          end
+          nil
+        end
+
+        # The `shape:` spelling of the same claim: a member of the model's wire parent named `id_key` that
+        # carries members of its own, so `apply_structured_schema!` merges an object property at that key before
+        # `apply_model_id_child!` ever runs.
+        #
+        # No gate is consulted, deliberately: every claim this guard reads is one the emitter WRITES, and
+        # input reflection is static-maximal — a gated member is advertised exactly as an ungated one is, so
+        # the document carries the collision either way.
+        def claiming_shape_member(parent_configs, id_key)
+          Axn::Internal::Reflection::Schema.shape_members_at(parent_configs, id_key).find do |member|
+            object_contents_of(member)
+          end
+        end
+
+        # Names are RENDERED rather than interpolated raw, for the reason `raise_dead_tolerance!` documents: a
+        # declared name may hold bytes with no UTF-8 rendering, and joining one into this message would replace
+        # the contradiction being reported with an Encoding::CompatibilityError from the reporting itself.
+        def raise_model_id_object_claim!(config, claimant, kind, id_key)
+          label = ->(name) { Axn::Internal::Reflection::PropertyNames.renderable_label(name) }
+          where = config.on ? " (on #{label.call(config.on)})" : ""
+          # A claimant is the DECLARATION where there is one, and a bare emitted property name where the
+          # contents are inferred from a structured `type:` (see `object_contents_of`).
+          named = claimant.respond_to?(:field) ? claimant.field : claimant
+          claim =
+            if kind == :member
+              "a `shape:` member :#{label.call(named)} of the same name declares members of its own"
+            else
+              via = claimant.respond_to?(:on) && claimant.on ? " (on #{label.call(claimant.on)})" : ""
+              ":#{label.call(named)}#{via} nests underneath that same key"
+            end
+          raise ArgumentError,
+                "`model:` field :#{label.call(config.field)}#{where} generates the wire key " \
+                ":#{label.call(id_key)} for its lookup token, but #{claim}. One wire key cannot be both a " \
+                "lookup token and a nested object parent — the reflected schema can emit only one of the " \
+                "two, and which one survives follows declaration order. Rename the nested key, or drop the " \
+                "`model:` on :#{label.call(config.field)}."
+        end
+
         # The MAP-PARENT check: a subfield read out of a Hash that declares `of:`. `of:` names what every key of
         # that hash maps to, and a subfield names one of those keys — so the two describe the same keys two ways,
         # and no reflected schema can state both. JSON Schema's `additionalProperties` applies only to keys