Module: Axn::Extensions::Serialization

Defined in:
lib/axn/extensions/serialization.rb,
lib/axn/exceptions.rb

Overview

The declared entry point for rendering a successful Result — the one serialization call an adapter gem makes. Everything behind it is core's own: Axn::Internal::Reflection::Values holds the rendering decisions, and a caller depending on one of them constrains core's routing.

Defined Under Namespace

Classes: UnserializableValue

Class Method Summary collapse

Class Method Details

.render(result, reject_opaque: false) ⇒ Object

A successful Result's exposures as a JSON-safe Hash keyed by wire key (a String), over the action's declared exposes.

The configs are DERIVED from the result rather than passed in. Rendering a subset is the only thing an explicit list would allow, and a subset silently produces a body that no longer matches the action's reflected output_schema — which is the promise this rendering keeps.

reject_opaque: additionally rejects a value (or Hash key) that declares no rendering of its own. Off by default, because such output is honest and complete, just not a shape its author chose: whether that is a failure belongs to the transport, since an HTTP contract should not ship it while an LLM tool result is better off ugly than failed. Everything unconditional — a cycle, two names collapsing to one property, a non-finite Float, bytes with no UTF-8 rendering — raises either way.

Raises Axn::Extensions::Serialization::UnserializableValue (an ArgumentError) naming the path to the offending value, so an adapter's existing rescue StandardError maps it to an error response.



33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/axn/extensions/serialization.rb', line 33

def render(result, reject_opaque: false)
  action_class = result.__action__.class
  # The outbound property-name rules run before the first render of a class, not only before a schema:
  # a render-only adapter would otherwise learn about a collision from serialize_exposed's runtime
  # defense on a live call, which is a last line rather than a substitute for telling the author. Costs
  # one output-schema build on the first render and nothing after.
  Axn::Internal::Reflection::PropertyNames.validate_outbound!(action_class)

  configs = action_class.external_field_configs

  # `send` because serialize_exposed is private: this facade is its only caller, and that is
  # what makes `render` the rendering path rather than one of two.
  Axn::Internal::Reflection::Values.send(:serialize_exposed, result, configs, reject_opaque:)
end