axn 0.1.0.pre.alpha.5 → 0.1.0.pre.alpha.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7c950f2b3d95c1f76aa0d963531b635e08c57058a2c3e2c8d07ccd40355faa5
-  data.tar.gz: 459ab003e2d8802c4c547ff6b89f6de3cc673e7e50072a66928d6a1b78444db7
+  metadata.gz: 96629802248edd18b5c1d3607b7aa3ad6775c9185a8667808f4d81ae98cfb69e
+  data.tar.gz: 66185b1f3f784c7a4c57680ed7b1fdcda1ae958904b69d53dfa003fb50c88286
 SHA512:
-  metadata.gz: b8917cfa50c90daf33a41ebc40c90e5bec9bafe926da10a70ac4b73c34d5883185569af921d8f7693dd4f0b38074d07d675ecc8d3f7b4808be4b69ef8e52c6b9
-  data.tar.gz: 96a0838272f6f800206d2c85beae9c82f1e1ef954db7d940d856c431719870639bc4e63f1ad1883621665ac67eaa676bbc270c1072c0bf517d458e268d6790ef
+  metadata.gz: bc8ffc522d6226bcb15f401d42f23560cec3fd0497d30f710456d2b68f12c1238c5ca6453f151aec00baddebfe707b619a649177c62779f6db0cf44eb43e84fb
+  data.tar.gz: 8bd82a4adf9fd10a612ae70ff4abfc7b37284970dbed31a6e615c5d842b8384e51ad9ff17b1a6914738257fc2bc2d86ce374fa8d18a21019f069e19e300653dd

data/AGENTS-consuming.md

@@ -60,13 +60,13 @@ Common options (same for `expects` and `exposes`):
 
 | Option | Meaning |
 | --- | --- |
-| `type:` | `is_a?` check. `type: :boolean` (no Ruby Boolean class; also defines a `field?` predicate), `type: :uuid`, `type: :params` (a Hash or any `ActionController::Parameters`). Union: `type: [String, Symbol]`. |
+| `type:` | `is_a?` check. `type: :boolean` (no Ruby Boolean class; also defines a `field?` predicate), `type: :uuid`, `type: :params` (a Hash or any `ActionController::Parameters`). Union: `type: [String, Symbol]`. A token outside that grammar (`type: false`, `type: [String, nil]`) raises `ArgumentError` at declaration. |
 | `optional: true` | Don't fail when the field is missing or nil (≡ `allow_blank: true`); removes the auto presence check. **Preferred** spelling. Caveat: a *typed* field still type-checks a non-nil blank — `type: Hash, optional: true` still rejects `""` (a `type: String` field accepts it, since `"".is_a?(String)`). |
 | `allow_empty: true` | Accept an empty collection or string but **not** `nil` — the field stays required. Needs a `type:` whose values can be empty — `Array`/`Hash`/`Set`/`String`/`:params`, or any class or module defining `empty?`; raises otherwise, as does any value other than `true`/`false`/`nil`. Pair with a tolerance flag inverted (`optional: true, allow_empty: false`) for "may be omitted, but not empty". Don't also declare `presence:` — the two answer the same question, and a disagreement raises. |
 | `allow_nil:` / `allow_blank:` | Finer-grained than `optional:`. |
 | `default:` | Used when the field is missing or explicitly `nil` (**not** for blank values). |
 | `sensitive: true` | Filter the value in logs / error reports / `inspect`. Accepts a proc/symbol for runtime decisions. |
-| `of:` | For `type: Array` **only** — validates each element's class (`of: String`, `of: [String, Numeric]`). Errors report the failing index. |
+| `of:` | Names what is INSIDE a container. `type: Array`: each element's class (`of: String`, `of: [String, Numeric]`), errors reporting the failing index. `type: Hash`: a map (`of: { keys: Symbol, values: Integer }`) — either axis may be omitted to leave it unconstrained, and a failing entry is reported by its ordinal, never its key. Refused on any other type, a union `type: [Array, Hash]` included. It **nests**: an element or an axis may take an inner-contract bag carrying `klass:`/`of:`/`shape:`/`message:` — `of: { klass: Array, of: Integer }` (an array of arrays), `of: { values: { klass: Hash, shape: … } }` (a map of shaped records; members at an axis must be objects answering `field`/`validations`, e.g. a `Struct.new(:field, :validations)`, since no block form reaches an axis). On a Hash, `of:` may sit beside a `shape:` or a block, which names specific keys: those keys are **exempt** from the map contract, exactly as JSON Schema's `additionalProperties` applies only to keys `properties` does not match. |
 | `validate:` | Custom: `validate: ->(v) { "must be > 10" unless v > 10 }` — return a string (or raise) to fail. |
 | any ActiveModel validation | e.g. `length:`, `format:`, `numericality:` — passed through as if to `validates`. |
 
@@ -92,14 +92,29 @@ See <https://teamshares.github.io/axn/reference/tool-invoker>.
 | `done!("msg", **kw)` | Abort now as **success** (early return); skips remaining `call` + `after` hooks. |
 | `log("msg", level: :info)` | Log via `Axn.config.logger`, prefixed with the class name. |
 | field readers | Read any `expects` field by name; `result.<field>` reads exposures (rare inside `call`). |
+| `Axn::Extensions::Tracing.annotate_span(**attrs)` | Write vendor-namespaced OTel attributes onto axn's own `axn.call` span — for a gem, not an app (apps use `tag`/`dimension`); never `OpenTelemetry::Trace.current_span`. |
 
 If you declare `exposes :x` you must `expose x: …` on every success path — **unless** `x` is also an
 `expects` field, in which case Axn auto-copies it (see Gotchas). Outbound validation still runs on
 `done!`, so a required exposure that's unset makes the action fail with `OutboundValidationError`.
 
 Hooks: `before`, `after`, `around` (block or symbol method). A `fail!`/raise in a hook fails the
-action. `done!` skips `after` hooks but lets `around` finish. Callbacks (`on_success`, `on_error`,
-`on_failure`, `on_exception`) run *after* `call` and do **not** flip `ok?`.
+action. `done!` skips `after` hooks — and because it unwinds via an exception, statements *after*
+`chain.call` in an `around` hook are skipped too (`fail!` and an unhandled raise unwind the same
+way). Put such teardown in an `ensure` inside the `around`, or use `use :transaction`, which rescues
+the signal so the transaction still commits. Note the `around` hook (and its `ensure`) covers only
+halts raised **after the hook chain is entered** — an inbound `expects` failure, or an *inbound*
+`preprocess:`/`default:` callable that raises, settles before the hooks run, so neither fires. The
+`exposes` side is bounded too: outbound resolution (an `exposes` `default:`, outbound validation)
+runs *after* the hook body returns, so the hooks complete **normally** and never observe a raise from
+it — an `around` that rescues to record failures misses them. Use the callbacks for per-call
+observability that must not miss either end. Callbacks
+(`on_success`, `on_error`, `on_failure`, `on_exception`) fire once the action **settles** — which is
+not the same as "after `call`": they fire even when `call` never ran, as on an inbound validation
+failure. That is what makes them the seam that sees every call. `on_error` is a superset, co-firing
+with whichever of `on_failure`/`on_exception` applies. A raise in a callback does **not** flip `ok?` —
+it is swallowed, logged, and reported to `Axn.config.on_ignored_exception` (which defaults to your
+`on_exception` handler) carrying `context[:axn_ignored]`.
 <https://teamshares.github.io/axn/usage/writing>.
 
 ## Using a result
@@ -149,7 +164,9 @@ 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. Source: `lib/axn/core/field_resolvers/model.rb`.
+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`.
 
 **`on:` — subfields (the `:extract` resolver).** Declare expectations about nested data and get a
 flat reader:
@@ -162,8 +179,12 @@ expects :zip, on: "address.billing"      # dotted path; reader: zip
 ```
 
 Subfields support all the normal options and `default:`; `readers: false` skips reader creation;
-`as:`/`prefix:` rename. `default:`/`preprocess:`/`sensitive:` are **not** allowed on a *nested
-parent*. Subfield hashes accept string **or** symbol keys (indifferent). Source:
+`as:`/`prefix:` rename. `default:`/`preprocess:`/`sensitive:` work on a *nested parent* too (whether
+reached by dotted path or by pointing `on:` at another subfield). `default:`/`preprocess:` resolve on
+the **read path**, when the subfield is read; `sensitive:` is not part of that read — it resolves
+only when something requests redaction (see Gotchas). Either way the parent is never mutated and
+intermediates are never materialized; on an ambient parent (`on: :ambient_context`) only
+`user_facing:` is unsupported. Subfield hashes accept string **or** symbol keys (indifferent). Source:
 `lib/axn/core/field_resolvers/extract.rb`. Reference:
 <https://teamshares.github.io/axn/reference/class>.
 
@@ -190,6 +211,9 @@ reported to `Axn.config.on_exception`. Key consequences:
   the idiom for the "save an ActiveRecord model" case — a plain action plus
   `fails_on ActiveRecord::RecordInvalid, &:message` surfaces the record's validation errors as the
   failure message (and, e.g., `fails_on Stripe::CardError, &:message` for a card-declined message).
+  `if:`/`unless:` (evaluated against the action at settlement, same mechanism as `error`/callbacks)
+  gate the reclassification itself, not just the message — a condition living *inside* the message
+  block never did that, which is the footgun `if:`/`unless:` exist to close.
 - **`expects` violations are dev-facing by default** → exception bucket, pages, generic
   `"Something went wrong"`. A missing required input is your bug. Mark a genuinely caller-supplied
   field `user_facing: true` (or a String/Symbol/Proc message) to move *its* violations to the
@@ -215,12 +239,28 @@ error "email already taken", if: ArgumentError   # reason → "Couldn't sync use
 fail! "missing field"                            # reason → "Couldn't sync user: missing field"
 ```
 
-Composing actions: a base `error` on the parent auto-prefixes a child failure surfaced via `call!`
-**only when the child failed via `fail!`** (re-raised as `Axn::Failure`). A child `fails_on`-matched
-exception — or any raised exception — bubbles as the *original* exception, so the parent settles as a
-failure but `result.error` shows just the parent headline; the child's message is **not** woven in.
-To carry the child's message (e.g. a `RecordInvalid`/model-strategy child), or to add per-call
-context, use non-bang `call` + `fail!("context: #{child.error}")`.
+Composing actions: a base `error` on the parent auto-prefixes the child's **resolved `result.error`**
+surfaced via `call!`, and this is **bucket-independent** — it applies whether the child failed via
+`fail!`, a `fails_on`-classified exception, or an unexpected exception. What differs by bucket is the
+*exception object*, not the message: `fail!` re-raises as `Axn::Failure`, while a `fails_on`-matched
+or unhandled exception bubbles as the **original** exception. Either way the child's message is woven
+in (`"Onboarding failed: Charge failed: card declined"`) — **unless the parent itself declares a
+matching conditional reason**, which *replaces* the child's presentation rather than prefixing it
+(`error "Record not found", if: NotFoundErr` on the parent yields `"Onboarding failed: Record not
+found"`, and `standalone: true` drops the parent's base too, leaving `"Record not found"`). So a
+parent that authors its own reason for an exception class opts out of carrying the child's context.
+An *unexpected* exception still picks up a
+leaf if a conditional `error "…", if: SomeError` matches it — reason matching is independent of
+`fails_on` — giving `"Onboarding failed: Charge failed: retry later"` while the outcome stays
+`exception`. Only with **no matching reason** is there no leaf, and then just the declared base
+headers chain (`"Onboarding failed: Charge failed"`). The raw exception message never enters
+`result.error` **by default** — it stays the technical `#message` on `result.exception` — but you can
+opt a class in explicitly with `error(if: SomeError, &:message)` or `fails_on SomeError, &:message`,
+and once opted in it aggregates like any other reason (`"Onboarding failed: Charge failed: <raw
+message>"`). Only do that where the message is genuinely user-facing. A level declaring no base
+contributes nothing. Reach for non-bang `call` +
+`fail!("context: #{child.error}")` when you want to author a *different* message than this automatic
+aggregation, or to add per-call context — not to carry the child's message through.
 
 ⚠️ **Message bodies are NOT redacted** and propagate outward to every ancestor's `result.error`,
 logs, and error trackers. Never interpolate secrets/PII into `error`/`success`/`fail!` text — put
@@ -246,8 +286,17 @@ sensitive values in `sensitive:` fields. Detail:
   unchanged (not wrapped). `fails_on` reclassification is sticky across `call!` boundaries.
 - **Hooks vs callbacks.** A raise/`fail!` in a `before`/`after`/`around` hook flips `ok?` to false; a
   raise in a callback (`on_success` etc.) is reported but does **not** change `ok?`.
-- **`sensitive:` proc timing.** For `expects`, the `sensitive:` callable runs *before* defaults are
-  applied — guard against `nil` if it depends on another field.
+- **Callable-option timing.** A `sensitive:` Proc is `instance_exec`'d with **no arguments** (write
+  `sensitive: -> { !include_pii }`, reading other fields by name — a lambda declaring a parameter
+  raises), and it resolves lazily, only when something actually redacts. By then `default:`s are
+  applied, so it reads another field's *defaulted* value. `preprocess:` is the opposite: it runs
+  *before* defaults, seeing `nil` for an omitted top-level field. Only a **non-nil** result bypasses
+  the `default:` — return `nil` and the default still applies, so an intentional nil does not survive
+  (`false` does, matching `default:`'s missing-or-nil rule). On a **subfield** the preprocessor runs
+  only when the leaf's immediate parent is present: `parent: {}` still invokes it with `nil`, but an
+  absent or `nil` parent skips it entirely. The subfield's own `default:` still resolves in that case
+  — the reader returns the default, and is `nil` only when there is none. So don't rely on a nested
+  `preprocess:` to manufacture a value when the parent is missing; declare a `default:` for that.
 
 ## Strategies (DRYed configuration via `use`)
 
@@ -264,13 +313,25 @@ chains existing action classes. Data flows via the shared context; a step failur
 with the step name prefixed (`"validate: Email is invalid"`).
 <https://teamshares.github.io/axn/usage/steps>.
 
+## Declaring your entry point
+
+If you're building a gem that dispatches Axns on behalf of an external trigger (an inbound webhook, a
+scheduled job runner, a queue consumer) rather than calling them straight from app code, wrap your
+dispatch in `Axn::Extensions::InvokedVia.with(:your_gem) { handler.call!(**args) }`. The value becomes
+the `invoked_via` dimension on the whole call tree — every nested sub-Axn, span, log line, metric, and
+exception report — so an app can tell "traffic that came in through your gem" apart from ordinary
+direct calls without touching the classes it dispatches. A tool-adapter gem gets this automatically
+through `Axn::Tools::Invoker`'s `adapter:` kwarg; everyone else calls `InvokedVia.with` once, at the
+outermost point they control. `dimension :invoked_via` / `tag :invoked_via` are reserved — declaring
+either raises. See `docs/recipes/declaring-entry-points.md` for the full recipe.
+
 ## Pointers
 
 Human docs — <https://teamshares.github.io/axn/>:
 build (`/usage/writing`), use (`/usage/using`), class DSL (`/reference/class`), instance helpers
 (`/reference/instance`), result (`/reference/axn-result`), strategies (`/strategies/`), steps
 (`/usage/steps`), async (`/reference/async`), config (`/reference/configuration`), tool invoker
-(`/reference/tool-invoker`).
+(`/reference/tool-invoker`), entry points (`/recipes/declaring-entry-points`).
 
 Source entry points (resolve with `bundle show axn`):
 - `lib/axn.rb` — `include Axn` wiring.
@@ -279,4 +340,4 @@ Source entry points (resolve with `bundle show axn`):
 - `lib/axn/core/validation/validators/` — `type`, `of`, `model`, `validate`, `shape` validators.
 - `lib/axn/core/flow/` — `messages.rb`, `fails_on.rb`, `handlers/` (failure/message/callback resolution).
 - `lib/axn/result.rb`, `lib/axn/core/context/facade.rb` — the `Result` surface.
-- `lib/axn/strategies/` — `model.rb`, `form.rb`, `transaction.rb`.
+- `lib/axn/strategies/` — `form.rb`, `transaction.rb`; `lib/axn/extras/strategies/client.rb` (`use :client`).

data/AGENTS-tool-adapters.md

@@ -48,6 +48,11 @@ GemName.wrap(axn_class, **opts)  # one Axn -> the transport's native tool object
 - **Directory membership is optional.** `extend Axn::Tools::AdapterRoots` → a validated `tool_roots`
   setting the registry reads. Its `validate!` reuses core's broad-path guard (rejects `app`/`actions`/`.`/`..`).
   The reference gems don't adopt it (they use explicit `tool`/`configure`); add it only if it fits.
+- **Shipping a non-empty default root? Call `tool_roots_default %w[agent_tools]`** — don't re-declare
+  `setting :tool_roots` by hand, which means hand-copying `AdapterRoots.validate!`'s lambda too.
+  `tool_roots_default` validates EAGERLY at the call site (fails at gem load, not at the registry's first
+  read) and re-declares through the normal `setting` path, so an app's own assignment still wins and
+  `config.reset!(:tool_roots)` returns to the adapter's default, not core's `[]`.
 
 Source: `lib/axn/tools.rb` (`.register_adapter`, `.for`, `.versions`), `lib/axn/tools/registry.rb` (membership,
 eager-load), `lib/axn/tools/adapter_roots.rb`, `lib/axn/core/tool_declaration.rb` (`tool` DSL, `tool_name`).
@@ -103,8 +108,17 @@ Source: `lib/axn/core/schema_reflection.rb`, `lib/axn/internal/reflection/schema
   pre-pass — it drifts from the renderer.
 - Keep the two guarantees apart: encodability is unconditional, declared-shape is what the flag buys.
   `reject_opaque: false` never means "might not be JSON" — that is why it isn't named `strict:`.
-
-Source: `lib/axn/extensions/serialization.rb` (the renderer itself is `lib/axn/internal/reflection/values.rb`, core-internal).
+- This is call-time by construction, not a boot check: the verdict is about the exposed VALUE's own class
+  (does it define its own `to_h`/`as_json`), and a field's declared `type:` is only a lower bound on what
+  could show up there — a subclass or a singleton method can make an otherwise-opaque declared type render
+  cleanly. A check keyed on the declared class alone would refuse programs that run correctly.
+- **If `reject_opaque:` is per-tool (usually is), call `YourAdapter.serialize_exposed(result)` instead of
+  `render` directly.** `Axn::Tools::AdapterSerialization` bundles the declaration and the
+  resolve-then-render chain — see Per-adapter configuration below. `render(result, reject_opaque:
+  config.reject_opaque)` reading the flag off the gem-wide `config` is the mistake this exists to
+  prevent: it ignores any per-tool `configure(:key)` / `tool key: { … }` override.
+
+Source: `lib/axn/extensions/serialization.rb` (the renderer itself is `lib/axn/internal/reflection/values.rb`, core-internal), `lib/axn/tools/adapter_serialization.rb`.
 
 ## Per-adapter configuration
 
@@ -117,8 +131,15 @@ Source: `lib/axn/extensions/serialization.rb` (the renderer itself is `lib/axn/i
 - A **render toggle** (structured serialized `exposes` vs. the Axn's message) is a common per-adapter
   setting. `axn-mcp` and `axn-ruby_llm` both name it `present_as` (`:structured` / `:message`) — reuse the
   name/values if you have the concept. It's adapter-specific, not core (an `axn-http_api` has no such toggle).
+- **`reject_opaque_exposed_values` is shared — declare it with `extend Axn::Tools::AdapterSerialization` +
+  `declare_reject_opaque_exposed_values! default: <bool>`**, not a hand-written `setting`. `default:` is a
+  REQUIRED kwarg with no core-picked value: an HTTP adapter with a published `output_schema` wants `true`
+  (axn-openapi); an LLM-facing adapter usually wants `false` — ugly-but-honest beats a failed call
+  (axn-mcp, axn-ruby_llm). Never fix the default in a shared declaration; parameterize it.
+- **The transport-mapping step needs its own never-raises guard — use `guard_tool_response`,** from the
+  same mixin. See Invocation & result → response below.
 
-Source: `lib/axn/configurable.rb` (`config_namespace`, `resolve_override_for`, `overrides`).
+Source: `lib/axn/configurable.rb` (`config_namespace`, `resolve_override_for`, `overrides`), `lib/axn/tools/adapter_serialization.rb`.
 
 ## Extension registry
 
@@ -135,6 +156,9 @@ Source: `lib/axn/extensions/config.rb`, `lib/axn/core/semantic_hints.rb`.
   (always-on wire coercion, opt-in user-facing input-error surfacing, undeclared-key rejection, the
   ambient guard) that a trusted in-process `.call` deliberately omits. See
   <https://teamshares.github.io/axn/reference/tool-invoker>.
+- Pass `adapter: :your_key` to `Invoker.new` and every call it makes is stamped with the `invoked_via`
+  dimension across its whole call tree — the seam that lets an app's dashboard separate tool-driven
+  traffic from ordinary direct calls. See <https://teamshares.github.io/axn/recipes/declaring-entry-points>.
 - Map from: `result.ok?`; `result.error` (**user-facing** — show to the LLM/client); `result.success` /
   `result.message` (success string); `result.exception` (**dev-facing** detail, e.g. the
   `Axn::InboundValidationError` — do **NOT** surface it).
@@ -147,8 +171,17 @@ Source: `lib/axn/extensions/config.rb`, `lib/axn/core/semantic_hints.rb`.
   `fail!("…", standalone: true)`.
 - For per-field inbound detail: `Axn::Tools::Invoker.input_invalid?(result)` and
   `result.exception.field_errors`.
-
-Source: `lib/axn/extensions.rb` (`owned_failure?`), `lib/axn/tools/invoker.rb`, `lib/axn/result.rb`.
+- **Never let the mapping step escape.** `axn_class.call` (via the Invoker) never raises, but the
+  result→response mapping AFTER it — `serialize_exposed`/render, your own response-building code — runs
+  outside core's executor and CAN raise. Wrap just that step:
+  `YourAdapter.guard_tool_response(axn_class, on_error: ->(e) { your_error_response }) { map_result_to_response }`.
+  It reports through `Axn.config.on_exception`, re-raises when `Axn::Extensions.raises_in_dev?`, and
+  otherwise calls `on_error` with the exception so you build the transport-native error response (this
+  method never constructs one). **Scope it to the mapping only — never to `axn_class.call`** (already
+  reports its own exceptions; wrapping both double-reports).
+
+Source: `lib/axn/extensions.rb` (`owned_failure?`), `lib/axn/tools/invoker.rb`, `lib/axn/result.rb`,
+`lib/axn/tools/adapter_serialization.rb` (`guard_tool_response`).
 
 ## Error boundary
 
@@ -174,6 +207,20 @@ Source: `lib/axn/extensions.rb` (`owned_failure?`), `lib/axn/tools/invoker.rb`,
 
 Source: `lib/axn/error.rb`.
 
+## Span annotation
+
+If your gem needs to write vendor-namespaced OTel attributes it can't know at declaration time
+(`gen_ai.*`, `db.*`, …), use `Axn::Extensions::Tracing.annotate_span(**attrs)` — never
+`OpenTelemetry::Trace.current_span`. That resolves through `OpenTelemetry::Context.current`, ambient
+process-wide state anything else running mid-chain can move (verified against the Datadog OTel bridge in
+production, PRO-3278); `annotate_span` is the span axn's own tracer opened for the action currently
+running, direct, no guessing. It no-ops (no raise) when there is no span, skips a `nil` value, and
+converts a Symbol key to a String. `axn-ruby_llm`'s `record_otel_attributes!` is the reference use.
+`Axn::Extensions::Tracing.current_span` is the raw accessor for anything beyond attributes — valid only
+for the duration of the action's own body; don't hold it past the call.
+
+Source: `lib/axn/extensions/tracing.rb`, `docs/reference/configuration.md#annotating-the-span-from-your-own-code`.
+
 ## ambient_context
 
 Server/session data (`current_user`, `company`) an author declares via `expects :user_id, on: :ambient_context`.
@@ -234,14 +281,17 @@ Source: `lib/axn/core/ambient_context.rb`, `lib/axn/tools/invoker.rb`.
 
 Docs — <https://teamshares.github.io/axn/>: authoring a tool-adapter gem
 (`/recipes/authoring-tool-adapters`), tool invoker (`/reference/tool-invoker`), gem configuration
-(`/recipes/gem-configuration`), factory (`/reference/factory`), class DSL (`/reference/class`), result
-(`/reference/axn-result`). Action-authoring: `AGENTS-consuming.md` (this gem).
+(`/recipes/gem-configuration`), declaring an entry point (`/recipes/declaring-entry-points`), factory
+(`/reference/factory`), class DSL (`/reference/class`), result (`/reference/axn-result`).
+Action-authoring: `AGENTS-consuming.md` (this gem).
 
 Core source entry points (resolve with `bundle show axn`):
 - `lib/axn/tools.rb` — `Axn::Tools.register_adapter`, `.adapters`, `.for`, `.versions`, `.validate_contracts!`.
 - `lib/axn/extensions.rb` — `Axn::Extensions.best_effort`, `.config`, `.owned_failure?` (extension-author surface).
 - `lib/axn/tools/registry.rb`, `lib/axn/tools/adapter_roots.rb`, `lib/axn/core/tool_declaration.rb` —
   membership, `tool_name`.
+- `lib/axn/tools/adapter_serialization.rb` — `declare_reject_opaque_exposed_values!`,
+  `serialize_exposed`, `guard_tool_response`.
 - `lib/axn/core/schema_reflection.rb`, `lib/axn/internal/reflection/schema.rb`, `lib/axn/internal/reflection/values.rb` — reflection.
 - `lib/axn/configurable.rb` — `config_namespace`, `resolve_override_for`, `overrides`.
 - `lib/axn/tools/invoker.rb` — the tool call path.