axn 0.1.0.pre.alpha.4.3 → 0.1.0.pre.alpha.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a911da94d085860df8fc6aed9bbe869edae27c2ff0e5821b2c07a043644c4fb5
-  data.tar.gz: 0d56247c256cc52efc8258a1716b0c4274114411948b084fe872fc63285907c3
+  metadata.gz: c7c950f2b3d95c1f76aa0d963531b635e08c57058a2c3e2c8d07ccd40355faa5
+  data.tar.gz: 459ab003e2d8802c4c547ff6b89f6de3cc673e7e50072a66928d6a1b78444db7
 SHA512:
-  metadata.gz: d39402f76d8df64e831007e046f0d5c8ac7fcd009246bbee9e7296db789b3afa270f5e63987eb23c88821f3f0ee2fecf3e7ec576b5dc9ce0f9e0972ba1811f93
-  data.tar.gz: 2347b225abbab7c3e705ca071b661e104c18c4d6333d5eb8563eadf26559035485f79682f4e4a23f3c6e3dabf30209475570fd07ab511a9b75f9d5537d320f41
+  metadata.gz: b8917cfa50c90daf33a41ebc40c90e5bec9bafe926da10a70ac4b73c34d5883185569af921d8f7693dd4f0b38074d07d675ecc8d3f7b4808be4b69ef8e52c6b9
+  data.tar.gz: 96a0838272f6f800206d2c85beae9c82f1e1ef954db7d940d856c431719870639bc4e63f1ad1883621665ac67eaa676bbc270c1072c0bf517d458e268d6790ef

data/.rubocop.yml

@@ -0,0 +1,109 @@
+# RuboCop cops are not loaded by default in this repo
+# Downstream consumers can enable them by adding:
+# require:
+#   - axn/rubocop
+
+# Merge with (rather than replace) RuboCop's built-in AllCops/Exclude — 'node_modules/**/*',
+# 'tmp/**/*', 'vendor/**/*', '.git/**/*'. Declaring an Exclude array replaces those built-ins, and
+# every glob resolves relative to the config file that declares it, so without this a gem doing
+# `inherit_gem: axn` ends up with nothing excluding its OWN tree: it inherits globs pointing into the
+# axn gem dir, having lost the built-ins that pointed at itself. CI then lints the bundle that
+# ruby/setup-ruby's bundler-cache installs into an in-repo vendor/bundle, reading each vendored gem's
+# own .rubocop.yml and dying on the plugins those `require:` but the consuming gem doesn't bundle.
+# `inherit_mode` declared HERE governs the merge for every consumer, so they inherit the built-in
+# excludes whether or not their own config remembers to re-declare them.
+inherit_mode:
+  merge:
+    - Exclude
+
+AllCops:
+  TargetRubyVersion: 3.2
+  SuggestExtensions: false
+  NewCops: enable
+  # Deltas only — vendor/node_modules/tmp/.git arrive via the merge above. The built-in globs are
+  # top-level-anchored, so a nested bundle (a locally-vendored dummy app) still needs naming.
+  Exclude:
+    - 'benchmark/**/*'
+    - 'bin/benchmark'
+    - 'spec_rails/dummy_app/vendor/**/*'
+    - 'spec_rails/dummy_app/tmp/**/*'
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/SingleLineMethods:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: always
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 250
+  Exclude:
+    - 'spec_rails/dummy_app/lib/integration/**/*'
+
+Metrics/MethodLength:
+  Max: 70
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Lint/EmptyBlock:
+  Enabled: false
+
+Naming/MethodParameterName:
+  AllowedNames: e, on, id, if, as
+
+Metrics/ParameterLists:
+  Max: 11
+
+Layout/LineLength:
+  Max: 160
+
+Naming/VariableNumber:
+  Exclude:
+    - 'spec/**/*'
+
+# Sidekiq::RetrySet doesn't have empty? method
+Style/ZeroLengthPredicate:
+  Exclude:
+    - 'spec_rails/dummy_app/lib/integration/**/*'
+
+

data/AGENTS-consuming.md

@@ -0,0 +1,282 @@
+# Axn — agent guide
+
+For an LLM writing code that **calls** or **declares** Axn actions (not modifying Axn internals).
+Covers the contract, result/failure behavior, idioms, and gotchas; points out to the docs and source
+for depth. On an edge case, read the source — paths below, via `bundle show axn`.
+Docs: <https://teamshares.github.io/axn/>.
+
+## Mental model
+
+An Axn (Action) is a callable service object with a declared contract: inbound fields (`expects`),
+outbound fields (`exposes`), and a `call` body. `Foo.call(...)` **always** returns an `Axn::Result`
+— it never raises for ordinary failures (exceptions are swallowed and reported). You branch on
+`result.ok?`. Business logic aborts with `fail!`; unexpected errors raise and are caught for you.
+
+```ruby
+class CreateWidget
+  include Axn
+
+  expects :name, type: String
+  expects :category, type: String, optional: true
+  exposes :widget
+
+  # Idiom: set meaningful messages — the generic fallbacks ("Action completed successfully" /
+  # "Something went wrong") are almost never what a caller should see. Do this by default.
+  success "Widget created"
+  error "Couldn't create widget"
+
+  def call
+    fail!("Name is taken") if Widget.exists?(name:)
+    expose widget: Widget.create!(name:, category:)
+  end
+end
+
+result = CreateWidget.call(name: "Sprocket")
+result.ok?      # => true
+result.widget   # => #<Widget ...>                            (reader for the exposed field)
+result.success  # => "Widget created"
+
+result = CreateWidget.call(name: "Existing")  # name taken → fail!
+result.ok?      # => false
+result.error    # => "Couldn't create widget: Name is taken"  (base headline prefixes the reason)
+```
+
+Each declared field gets a reader **inside** the action (`name`, `category`) and each exposed field
+gets a reader **on the result** (`result.widget`). Inside `call` you never touch a raw params hash —
+you read the named fields.
+
+## Declaring the contract
+
+`expects` declares inbound fields; `exposes` declares outbound. Both take one or more field names
+plus shared options. Validation runs automatically (inbound before `call`, outbound after).
+
+```ruby
+expects :email, type: String
+expects :role, inclusion: { in: %w[admin member] }, optional: true
+exposes :user
+```
+
+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]`. |
+| `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. |
+| `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`. |
+
+`expects`-only extras: `model:` (auto-hydrate a record, below), `on:` (subfields, below),
+`as:`/`prefix:` (rename the reader), `preprocess:` (coerce before validation/defaults),
+`user_facing:` (blame the caller, see Failure semantics).
+
+These validations are the **developer contract** (how the action is called) — not pretty
+user-facing copy. For user-facing input validation reach for `use :form`. Full option detail:
+<https://teamshares.github.io/axn/reference/class>.
+
+If this action runs as a tool (via `Axn::Tools::Invoker`, an adapter's runtime for model-supplied
+args), declare a `type:` on every field rather than a defensive per-field `coerce: true` — tool
+calls always coerce, and coercion plus schema reflection (`input_schema`) both key off `type:`.
+See <https://teamshares.github.io/axn/reference/tool-invoker>.
+
+## Inside `call`
+
+| Helper | Effect |
+| --- | --- |
+| `expose key: val` / `expose :key, val` | Set an exposed field on the result. Only declared `exposes` keys are allowed. |
+| `fail!("msg", **kw)` | Abort now as a **failure**; `result.error` = msg; optional kwargs exposed first. |
+| `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`). |
+
+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?`.
+<https://teamshares.github.io/axn/usage/writing>.
+
+## Using a result
+
+`Axn::Result` is uniform across every action:
+
+| Member | Meaning |
+| --- | --- |
+| `ok?` | Succeeded? |
+| `error` | User-facing error string when `!ok?` (else nil). |
+| `success` / `message` | Success string when `ok?`; `message` is always set (success or error). |
+| `outcome` | String inquirer: `outcome.success?` / `failure?` / `exception?`. |
+| `exception` | The swallowed exception, if any (mostly for tests/diagnostics). |
+| `<exposed field>` | Reader for each declared exposure. |
+
+```ruby
+result = Actions::Slack::Post.call(channel: "#eng", message: text)
+if result.ok?
+  @thread_id = result.thread_id
+else
+  flash[:alert] = result.error
+end
+```
+
+Invocation variants:
+
+- `Foo.call(**kw)` → always returns a `Result`; exceptions swallowed. **Default.**
+- `Foo.call!(**kw)` → returns a `Result` on success; a `fail!` raises `Axn::Failure`, any other
+  error re-raises as-is. Use in scripts / when you want failures to bubble.
+- `Foo.call_async(**kw)` → enqueue as a background job (configure with `async :sidekiq` /
+  `async :active_job`). See <https://teamshares.github.io/axn/reference/async>.
+
+`Result` supports pattern matching (`in ok: true, user: User => u`).
+
+## Field resolvers (`model:` and `on:`)
+
+**`model:` — hydrate a record from an id.** `expects :user, model: true` adds expectations that
+`user_id` is supplied (derived from the field name) and `User.find(user_id)` returns a record, and
+defines both a `user` reader (the record) and a `user_id` reader. Variants: `model: User`,
+`model: { klass: User, finder: :find_by_slug }`.
+
+```ruby
+expects :user, model: true
+# called with user_id: 5   → user_id == 5,      user resolves the record
+# called with user: <rec>  → user_id == rec.id, user is that record
+```
+
+`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`.
+
+**`on:` — subfields (the `:extract` resolver).** Declare expectations about nested data and get a
+flat reader:
+
+```ruby
+expects :event, type: Hash
+expects :data, type: Hash, on: :event
+expects :id, :type, on: :data            # readers: id, type (extract event[:data][:id], ...)
+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:
+`lib/axn/core/field_resolvers/extract.rb`. Reference:
+<https://teamshares.github.io/axn/reference/class>.
+
+## Failure semantics (read this — most subtle bugs live here)
+
+Every non-success outcome lands in exactly one bucket:
+
+| How it ends | `outcome` | `on_failure` | `on_exception` + **global report** | `result.exception` |
+| --- | --- | --- | --- | --- |
+| `fail!("…")` | `failure` | fires | **no** | `Axn::Failure` |
+| `fails_on`-matched raise | `failure` | fires | **no** | the original exception |
+| any other raised error | `exception` | — | **yes** (e.g. Honeybadger) | the original exception |
+
+So `fail!` is for **expected, user-facing** outcomes; an unhandled raise is treated as a **bug** and
+reported to `Axn.config.on_exception`. Key consequences:
+
+- **`fails_on ExceptionClass`** reclassifies a raised exception from *bug* to *expected failure*
+  (fires `on_failure`, skips the global report, keeps the original on `result.exception`). Put it on
+  the action that **raises** the exception — it doesn't suppress a report from a deeper action. Only
+  reclassify deterministic/non-transient errors (e.g. `ActiveRecord::RecordInvalid`), never a
+  transient one you'd want retried. In async, a `fails_on` failure is terminal (no retry).
+  `result.error` never defaults to the exception's own (technical) `#message`; opt a specific class
+  in with `fails_on ExceptionClass, &:message` when that message is genuinely user-facing. This is
+  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).
+- **`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
+  failure bucket with a meaningful `result.error`. The field stays required. In a mixed failure
+  (a `user_facing:` field *and* a plain one), dev-facing wins and it still pages.
+- **A nested bug is reported once**, from the innermost action that treats it as a bug, however deep
+  the `call!` chain.
+
+**Messages — declare `success` and `error` by default.** The fallbacks are the generic
+`"Action completed successfully"` / `"Something went wrong"`; declare a meaningful `success "…"` and
+`error "…"` on every action whose result a caller surfaces. Both accept a string, a symbol (action
+method), or a block (evaluated in instance context: `error { "Failed for #{name}" }`).
+
+**Base/reason model.** An *unconditional* `error "Headline"` is the **base**: it's the fallback and it
+auto-prefixes every failure reason as `"Headline: reason"` (a conditional `error … if:`, a
+`prefixed: true` entry, and `fail!` strings). A *conditional* `error "…", if: SomeError` is a reason.
+Most-recently-declared matching reason wins. `success`/`done!` work the same. A literal and a block
+behave identically — conditionality (not string-vs-block) sets the role.
+
+```ruby
+error "Couldn't sync user"                       # base / fallback + prefix
+error "email already taken", if: ArgumentError   # reason → "Couldn't sync user: email already taken"
+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}")`.
+
+⚠️ **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
+sensitive values in `sensitive:` fields. Detail:
+<https://teamshares.github.io/axn/usage/writing#prefixing-failure-reasons>. Source:
+`lib/axn/core/flow/messages.rb`, `lib/axn/core/flow/fails_on.rb`.
+
+## Gotchas
+
+- **Indifferent access is top-level only.** Declared keys, call-arg keys, and `expose` keys are all
+  symbolized, so `expects :note` matches `.call("note" => x)` (the `.call(**params)` case). But field
+  **values** — including nested hashes — are untouched: reach into a nested value with the key type
+  it actually has (or declare an `on:` subfield, which *is* indifferent).
+- **Auto-copy of `expects` + `exposes` fields.** A field declared with *both* is copied from input to
+  result automatically on **all** paths — success, `done!`, `fail!`, and exception. Lets a caller
+  read `result.user.errors` after a failed save without a manual `expose`. Don't redundantly
+  `expose` it.
+- **`done!` rolls back a manual `ActiveRecord::Base.transaction`** (it's implemented via an
+  exception). Use `use :transaction` for transaction-safe early completion.
+- **Default `call`.** Omit `call` entirely and Axn synthesizes one that exposes each declared
+  `exposes` by calling a same-named method. A method returning `nil` (no default) counts as missing.
+- **`call` vs `call!`.** With `call!`, a `fail!` raises `Axn::Failure`; any *other* error re-raises
+  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.
+
+## Strategies (DRYed configuration via `use`)
+
+- **`use :form do … end`** — validate user input via an `Axn::FormObject` (full ActiveModel
+  validations) before `call`; exposes `form`. For genuinely user-facing input.
+  <https://teamshares.github.io/axn/strategies/form>.
+- **`use :transaction`** — wrap the action in a DB transaction that `done!` won't roll back.
+- **`use :client`** (Faraday) for HTTP APIs.
+
+## Composition (steps)
+
+`step :name, expects: […], exposes: […] do … end` defines inline sequential steps; `steps(A, B, C)`
+chains existing action classes. Data flows via the shared context; a step failure fails the parent
+with the step name prefixed (`"validate: Email is invalid"`).
+<https://teamshares.github.io/axn/usage/steps>.
+
+## 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`).
+
+Source entry points (resolve with `bundle show axn`):
+- `lib/axn.rb` — `include Axn` wiring.
+- `lib/axn/core/contract.rb` — `expects`/`exposes` declaration.
+- `lib/axn/core/field_resolvers/` — `model.rb` (`model:`), `extract.rb` (`on:` subfields).
+- `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`.

data/AGENTS-tool-adapters.md

@@ -0,0 +1,250 @@
+# Axn — tool-adapter author guide
+
+For an LLM writing an **axn tool-adapter gem**: a gem that exposes plain Axn actions over a tool/agent
+transport (`axn-mcp` → MCP, `axn-ruby_llm` → RubyLLM function-calling, a hypothetical `axn-http_api` →
+OpenAPI). Not for action authors — for *those* (declaring/calling Axns) read `AGENTS-consuming.md`, the
+sibling in this gem. On an edge case, read the core source — paths below, via `bundle show axn`.
+Docs: <https://teamshares.github.io/axn/recipes/authoring-tool-adapters>.
+
+## Mental model
+
+**Author-once.** A tool is a plain Axn (`include Axn` + `expects`/`exposes`/`call`) with nothing
+transport-specific. The SAME class is wrapped by every adapter, called directly, or enqueued async. Your
+adapter *projects* that class into the transport's native tool object, reading everything from Axn's public
+reflection surface. Two hard rules:
+
+- **Never require the author to write against your adapter.** No marker mixin, no adapter base class they
+  must subclass. They write a normal Axn; you wrap it.
+- **Never mutate the shared class in a way that breaks a different adapter.** The class is wrapped by
+  others. Overriding `input_schema` to a non-Hash is the canonical bug that retired `Axn::MCP::Tool` — do
+  transport shaping inside `wrap`, not by redefining reflection on the class.
+
+Core owns the shared machinery (membership, naming, reflection, config store, extension registry,
+invocation contract); you consume its public API. Expose exactly two public methods so every adapter has
+the same shape:
+
+```ruby
+GemName.tools                    # zero-arg: Axn::Tools.for(:key).map { |a| wrap(a) }
+GemName.wrap(axn_class, **opts)  # one Axn -> the transport's native tool object
+```
+
+`.tools` MUST be zero-arg — so every `wrap` option must default (name/description from the class).
+
+## Registration & discovery
+
+- **Register at gem load, from the entry file:** `Axn::Tools.register_adapter(:key)`. Pass a config source
+  second arg (`Axn::Tools.register_adapter(:key, self)`) ONLY if you offer directory discovery; else omit.
+  Re-registering with no source is idempotent.
+- **Enumerate with `Axn::Tools.for(:key)`** — returns the latest version per `tool_name`, sorted by
+  `tool_name` (a duplicate `(tool_name, tool_version)` raises), tool-root dirs eager-loaded first. Pass
+  `all_versions: true` for every version, or use `Axn::Tools.versions(:key, tool_name)` for one tool's group.
+- **Only currently-loaded classes are enumerated.** A `tool :key` class outside a tool-root dir must be
+  `require`d first. Enumerate from `config.after_initialize` / `to_prepare` — **never** a
+  `config/initializers` file (runs before autoload paths are wired; `Axn::Tools.for` warns).
+- **Membership** = `(directory grant ∪ declaration grant) − except`, computed by the registry. You don't
+  parse it — you call `Axn::Tools.for`. The author declares it: `tool` (all adapters), `tool :mcp` (add),
+  `tool mcp: { … }` / `configure(:mcp)` (implies `:mcp`), residency under a tool root, `tool false` (opt
+  out), `tool except: :x` (narrow).
+- **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.
+
+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`).
+
+## Naming & description
+
+- **Name = `axn_class.tool_name(:your_key)` — pass your adapter key.** Don't roll your own — the same Axn
+  must yield the same name across adapters. It's provider-safe, never blank, honors `tool name:` and prefix
+  stripping. `Axn::Tools.for` sorts on `tool_name(:your_key)` and collapses to the latest per name (uniqueness is
+  on `(tool_name, tool_version)`); a per-adapter `tool your_key: { name: }` override is only returned when
+  you pass the key — the zero-arg form ignores per-adapter overrides, so reading it would publish a name
+  the registry didn't collapse on.
+- **Description = `axn_class.description`.** `wrap`'s `description:` defaults to it (keeps `.tools` zero-arg).
+
+## Schema reflection
+
+- Use public `axn_class.input_schema` / `axn_class.output_schema` — plain JSON Schema **Hashes**. Wrap them
+  into your transport's schema object inside `wrap`.
+- **Don't** reach into `Axn::Internal::Reflection::Schema` internals. **Don't** override `input_schema` to a non-Hash
+  (breaks other adapters on the shared class).
+- `on: :ambient_context` fields are **auto-excluded** from `input_schema` — you get a clean model-facing
+  schema; don't re-add them.
+- Reflection is best-effort, biased **stricter** than runtime (a schema-following call won't be rejected),
+  with one documented **looser** case (an invalid literal `default:`). Surface the caveat; don't fight it.
+  A deep subfield under a `model:`/non-object parent is omitted with a `logger.warn` — pass it through.
+
+Source: `lib/axn/core/schema_reflection.rb`, `lib/axn/internal/reflection/schema.rb`.
+
+## Value serialization
+
+- Render a success result's exposures with `Axn::Extensions::Serialization.render(result)` → JSON-safe Hash.
+  Don't hand-roll (it handles Symbol/BigDecimal/Time/`as_json`-vs-`to_h` so output matches `output_schema`).
+- **You pass no config list** — `render` derives the declared `exposes` from the result itself. Rendering a
+  subset is deliberately unsupported: it would emit a body contradicting `output_schema`.
+- **Don't reach into `Axn::Internal::Reflection::Values`.** `render` is the surface; the renderer's helpers are private, and
+  what stays public is there for core's own cross-module callers, not for you.
+- No **value** in the result is one `JSON.generate` refuses (no non-finite number, no non-UTF-8 bytes, no
+  cycle, no collapsed property). That is a promise about values, NOT about your encoder's config: a structure
+  deeper than `max_nesting` (100 default) still raises `JSON::NestingError`. Drop your pre-*pass* over the
+  value graph; **keep** your encode `rescue`.
+- Raises `Axn::Extensions::Serialization::UnserializableValue` (an `ArgumentError`), naming the path, on five
+  unconditional defects: a cycle; two exposed field NAMES that render as the same JSON property (compared the same
+  canonicalized way as a Hash key, since a declared field is itself a property name); two Hash keys that
+  render as one JSON property (compared as the PROPERTY each produces, not as the Ruby String its `to_s`
+  returned — keys are transcoded to UTF-8 first, so one property name in two encodings collides); a
+  non-finite Float (incl. a `BigDecimal`/`Rational` coercing to one); and a
+  String — or a key's String form — whose bytes have no UTF-8 rendering (stricter than `valid_encoding?`:
+  `"\xFF"` in `BINARY` is valid BINARY and unencodable; a valid ISO-8859-1/Shift_JIS value transcodes and
+  passes untouched, a key comes back as UTF-8). Add `reject_opaque: true` to also reject a
+  value or key that declares no rendering of its own — `to_s` inherited from `Object`, or (in Rails)
+  ActiveSupport's generic `Object#as_json` ivar dump as its only projection. A meaningful
+  `to_s`/`as_json`/`to_h` defined anywhere else passes, address-looking or not. Never write your own
+  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).
+
+## Per-adapter configuration
+
+- `extend Axn::Configurable` + `config_namespace :key` (declare it before any overridable setting); declare
+  `setting :x, …, overridable: true`. See <https://teamshares.github.io/axn/recipes/gem-configuration>.
+- **Resolve a per-class value with `Axn::<Mod>.resolve_override_for(axn_class, :x)` — NOT
+  `axn_class.public_send(:x)`.** A wrapped plain Axn never included your `overrides` module, so it has no
+  such accessor; but the app may have set the value via `configure(:key)` / `tool key: { … }`.
+  `resolve_override_for` is the shadow-proof reader over the override store.
+- 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).
+
+Source: `lib/axn/configurable.rb` (`config_namespace`, `resolve_override_for`, `overrides`).
+
+## Extension registry
+
+- Add transport-only vocabulary without a core change: `Axn::Extensions.config.register_semantic_hint(:open_world,
+  :closed_world)` at load. Read `axn_class._semantic_hints` in `wrap` to map declared hints to your
+  annotations; let an explicit adapter override win. Hints are advisory (nothing enforces them).
+
+Source: `lib/axn/extensions/config.rb`, `lib/axn/core/semantic_hints.rb`.
+
+## Invocation & result → response
+
+- **`axn_class.call(**kwargs)` returns an `Axn::Result` and never raises for a business failure** (`call!`
+  raises; `call` doesn't). Prefer calling through **`Axn::Tools::Invoker`** — it applies the tool contract
+  (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>.
+- 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).
+- **`Axn::Extensions.owned_failure?(exception)`** — true for an axn-owned failure (`Axn::Failure` or a
+  user-facing validation error, whose `#message` is client-safe), false for a foreign exception
+  reclassified via `fails_on` (technical cause — don't leak). Check it before reading `#message` off an
+  exception.
+- **Impose no gem-wide error headline.** Surface `result.error`; let each tool declare its own base
+  `error "…"`. A base `error` prefixes `fail!("reason")` as `"Headline: reason"` unless
+  `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`.
+
+## Error boundary
+
+- **Root your gem's errors at `Axn::Error`.** Give the gem a base class that `include`s the module, and
+  subclass every specific error from it: `class Axn::Webhooks::Error < StandardError; include Axn::Error;
+  end`. Two sibling gems already have such a base and need only the `include`.
+- **It's a module, not a base class, on purpose.** `rescue` matches a module via `is_a?`, so including it
+  costs a class no ancestry — the adapter keeps whatever superclass its ecosystem needs (`< Faraday::Error`,
+  `< Timeout::Error`) and is still `rescue Axn::Error`-catchable. A base class would force a choice.
+- **Including it is a promise, not decoration**: the class becomes public, documented, rescuable, and
+  breaking to remove.
+- **The tag is inherited** — a tagged class cannot have an untagged subclass, so a public error family
+  can't grow a secretly-internal member.
+- **Two things stay outside the boundary on purpose.** `Axn::Failure` is a control-flow signal from
+  `call!`, not a fault, so it is deliberately untagged — `rescue Axn::Error` around a `call!` should mean
+  "axn objected," not "axn objected or the action intentionally failed"; a caller wanting both writes
+  `rescue StandardError`. Generic `ArgumentError`s raised for DSL misuse (a malformed `on:`, an
+  unregistered tool adapter) also stay plain — that's this repo's convention for a declaration mistake, not
+  a runtime fault, and it isn't specific to what your adapter raises.
+- **Why bother:** a consuming app's `rescue Axn::Error` catches core's errors AND every participating
+  adapter's, which is the payoff for following the convention instead of inventing a per-gem base with no
+  shared catch.
+
+Source: `lib/axn/error.rb`.
+
+## ambient_context
+
+Server/session data (`current_user`, `company`) an author declares via `expects :user_id, on: :ambient_context`.
+
+- **Spread it AS `ambient_context:`** — pass the injected context as the `ambient_context:` keyword, NOT
+  nested under an adapter key. Nesting couples the Axn to one adapter; spreading keeps it portable (the
+  same class resolves from an MCP server context, from `Current` on a direct call, or from ruby_llm). On a
+  direct `.call`, strip any model-supplied `ambient_context` from the args before splatting them (`**`) or
+  the model could override your trusted value — or just use the Invoker, which strips it for you.
+- It's **filtered to declared keys**; the injected value must be a `Hash` / hash-like (responds to
+  `key?`/`[]`, e.g. `HashWithIndifferentAccess`) — axn keys into it and drops any source it can't key into,
+  so a bare opaque object resolves every ambient field as absent. Wrap a transport context object in a Hash
+  of the injected fields (keys string or symbol, indifferent).
+- **Always pass an explicit `ambient_context:` (even `{}`)** — it *replaces* the `Current`-derived default
+  (no merge), preventing server-side state leaking into the call. The Invoker also strips any
+  `ambient_context` smuggled through model args before merging yours.
+
+Source: `lib/axn/core/ambient_context.rb`, `lib/axn/tools/invoker.rb`.
+
+## Live transport capabilities
+
+- Progress/cancellation are **objects/operations, not ambient data** — they don't survive ambient_context
+  filtering. Expose them via an adapter handle scoped with `ActiveSupport::IsolatedExecutionState`
+  (thread-/fiber-scoped per the configured isolation level), matching how axn scopes its own per-execution
+  state. A raw `Thread.current[...]` local is wrong under a Fiber scheduler. See `Axn::MCP.server_context` /
+  `with_server_context` in axn-mcp.
+
+## Inline / one-off tools
+
+- **Don't ship a per-gem `define`.** Wrap a core `Axn::Factory.build`:
+  `GemName.wrap(Axn::Factory.build(expects:, exposes:, axn_name: "…", description: "…") { … })`. The block is
+  the `#call` body (keyword-only args; not available for `exposes`/`shape:` coercion). A factory-built
+  class is **not** auto-discovered by `Axn::Tools.for` (synthetic name) — the constructor holds the reference
+  and wraps it directly. See <https://teamshares.github.io/axn/reference/factory>.
+
+## Deprecations
+
+- Own a dedicated `ActiveSupport::Deprecation.new("1.0", "gem-name")` as `GemName.deprecator`, so a
+  consuming Rails app can register it (`Rails.application.deprecators[:gem] = GemName.deprecator`) and
+  govern its behavior. `axn-mcp` does this; `axn-ruby_llm` currently uses raw `warn` — follow axn-mcp.
+
+## Testing
+
+- Reuse `Axn::Testing::SpecHelpers` (`build_axn { … }`, `with_ambient_context`) to construct the wrapped
+  Axns. Verify adapter output against **real** transport objects (a real `MCP::Tool::Response`/`InputSchema`,
+  a real `RubyLLM::Tool`), not hand-built hashes. **Pin the exact user-facing failure/success strings.** An
+  end-to-end spec driving a real `MCP::Server.new(tools:, server_context:)` catches wiring a unit test can't.
+
+## Reference gems
+
+- **axn-mcp** — adapter key `:mcp`; `wrap` → `::MCP::Tool` subclass → `MCP::Tool::Response`. Full worked
+  example of every convention above (registration, `server_context`, `semantic_hints` → annotations,
+  dedicated deprecator, real-object specs).
+- **axn-ruby_llm** — adapter key `:ruby_llm`; `wrap` → `::RubyLLM::Tool`. No output schema, no
+  transport-capability handle, no semantic_hints (RubyLLM has no annotations) — a simpler adapter surface.
+
+## Pointers
+
+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).
+
+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/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.
+- `lib/axn/core/ambient_context.rb` — ambient filtering/resolution.
+- `lib/axn/factory.rb` — `Axn::Factory.build`.
+- `lib/axn/error.rb` — `Axn::Error`, the public-error boundary tag.