Deterministic, scripted adapter for typed-classification testing. Implements ALLM.ClassificationAdapter.

Layer B — runtime. FakeClassification is the canonical testing classification adapter; it ships in lib/ (not test/support/) because users need it for their own application tests, like ALLM.Providers.Fake and ALLM.Providers.FakeModeration.

What FakeClassification is (and isn't)

FakeClassification never looks at :state. It reads :questions to answer each question id with an answer of the right type and shape, :model and :metadata to round-trip them onto the response, and nothing else. It does not re-validate the request: a question that ALLM.Validate.classification_request/1 would reject may still be answered, or may raise.

Its confidence convention is its own and is NOT any provider's formula. A default or scripted choice answer reports confidence: 1.0; a scripted fractional score reports the larger of its two level probabilities. A real adapter reports whatever its provider returns and never computes confidence.

Default answers (no script)

With no script — adapter_opts[:classification_script] absent or [] — every question gets a deterministic default:

iex> q = ALLM.ClassificationQuestion.choice("Which team?", ["technical", "billing"])
iex> req = ALLM.ClassificationRequest.new(state: "My card was charged twice.", questions: %{"team" => q})
iex> {:ok, resp} = ALLM.Providers.FakeClassification.classify(req, [])
iex> ALLM.ClassificationResponse.answer(resp, "team").choice
"billing"

Spent script

A non-empty script whose cursor has run off the end does NOT fall back to the defaults — it returns

{:error, %ALLM.Error.ClassificationAdapterError{
   reason: :unknown,
   metadata: %{cause: :classification_script_exhausted}}}

"I didn't script anything, give me a default" is a convenience; "my script ran out" is almost always an off-by-one in the caller's expectation of how many times classify/2 gets invoked, and answering it with defaults would make that bug pass green.

Script shapes

opts[:adapter_opts][:classification_script] accepts a list of entries. See script/1 for the grammar.

adapter_opts: [
  classification_script: [
    {:answers, %{"team" => "billing", "frustration" => 1.25, "refund" => 0.9}},
    {:error, %ALLM.Error.ClassificationAdapterError{reason: :rate_limited}},
    {:retry_until_call, 3}
  ]
]

{:answers, map} overrides the answer for each listed question id; every id not listed gets its default. A value is read according to the question's type:

A fractional score x puts probability ceil(x) - x on level floor(x) and x - floor(x) on level ceil(x); a whole-number score puts 1.0 on that level. Every "raises" cell, an out-of-range number, and an id that is not one of the request's questions raise ArgumentError naming the question id: those are test-author mistakes and should not pass green.

{:retry_until_call, n} returns a synthetic %ALLM.Error.ClassificationAdapterError{reason: :rate_limited, retry_after_ms: 0} for the first n - 1 calls against this entry, then advances to the next entry on call n. Consecutive {:retry_until_call, _} entries chain into a layered budget.

Cursor behaviour

Multi-call scripts advance a per-process cursor on every call. The cursor lives in the process dictionary at {:allm_fake_classification_cursor, key_id}, isolated per ExUnit test process (async: true), GC'd on pid-down, zero-setup for the common case. The key_id is chosen by this precedence:

1. adapter_opts[:script_cursor] — an explicit Agent pid (handled separately; see start_script_cursor/0).
2. adapter_opts[:cursor_key] — the engine's stable :id, injected by the façade dispatch chokepoint via ALLM.Engine.put_cursor_key/2.
3. :erlang.phash2(script) — the content-hash fallback for direct adapter calls with no engine.

The {:retry_until_call, n} budget keys on the same identity, so two engines built with content-equal scripts each get their own cursor and their own retry budget. The content-hash footgun remains only for DIRECT adapter calls — ALLM.Providers.FakeClassification.classify(req, opts) invoked without an engine receives no :cursor_key. Workaround for that path: pass distinct adapter_opts[:script_cursor] Agent pids from start_script_cursor/0, or distinct :cursor_key values.

Test-only capture seam

Pass adapter_opts[:capture_pid] with a pid to receive a side-channel message every time classify/2 is invoked, BEFORE the empty-questions gate runs and before the script is consulted:

{ALLM.Providers.FakeClassification, :call, %{request: request, opts: opts}}

It does not affect the response.