v0.1.0-alpha.24 — Catalog architectural redesign + onValidationRetry emission + Cerebras pricing

The headline

The static catalog is now FROZEN. New reasoning models are caught by:

1. Runtime detection (alpha.22+; universal correctness path; no maintenance)
2. Behavioral fingerprint cache (NEW in alpha.24; opt-in optimization)

The KNOWN_REASONING_MODELS catalog stays for the stable well-known cases (OpenAI o-series, gpt-5-nano, gpt-oss family, Qwen3.6, MiniMax-M2.7, MiMo-V) but stops growing. See the three-tier architecture doc.

This answers Babak's architectural pushback across the alpha.22 → alpha.23 transition that maintaining per-(model × provider) regex patterns is unsustainable. The empirical survey at docs/research/reasoning-models-survey-2026-06.md identified 30+ reasoning models across 5 providers — none of them need catalog entries from alpha.24 onward.

What's in this release

Behavioral fingerprinting (adapter-openai)

Opt-in cross-process cache that eliminates the first-call discovery penalty:

```ts
import { createOpenAIAdapter, FileFingerprintCache } from "@llm-ports/adapter-openai";

const adapter = createOpenAIAdapter({
apiKey: process.env.DEEPINFRA_API_KEY!,
baseURL: "https://api.deepinfra.com/v1/openai\",
fingerprintCache: new FileFingerprintCache("~/.llm-ports/fingerprints.json"),
});
```

Bundled backends: `InMemoryFingerprintCache`, `FileFingerprintCache`. Bring-your-own backend (Redis, S3, KV) via the `FingerprintCacheBackend` interface. Standalone helper `fingerprintModel()` for CI warm-starts.

The fingerprint analyzer detects all four CoT field conventions in the OpenAI-compat ecosystem:

• `usage.completion_tokens_details.reasoning_tokens` (OpenAI native)
• `message.reasoning` (Cerebras, Groq, SambaNova)
• `message.reasoning_content` (DeepInfra, Parasail)
• inline `...` (legacy R1 distills)

Every successful response is inspected for free — no extra probe call needed.

`onValidationRetry` Registry-level emission (core)

Closes the alpha.21-deferred Registry-level emission:

```ts
import { deriveValidationRetryFromAdapterRetry } from "@llm-ports/core";

const adapter = createOpenAIAdapter({
apiKey: process.env.OPENAI_API_KEY!,
onRetry: deriveValidationRetryFromAdapterRetry(registry),
});
```

Filters adapter retry events for `reason === "validation-feedback"` and forwards to the Registry's `observability.onValidationRetry` hook. Optionally chains with a user-supplied adapter-level callback.

Cerebras pricing entries

Two production models added to `OPENAI_PRICING`:

Model	Input $/1M	Output $/1M	Confidence
`gpt-oss-120b`	$0.35	$0.75	HIGH (primary docs)
`zai-glm-4.7`	$2.25	$2.75	MEDIUM (third-party only)

Research artifact

docs/research/reasoning-models-survey-2026-06.md — empirical catalog across DeepInfra, Parasail, SambaNova, Cerebras, Groq. 30+ reasoning models documented with response shapes, pricing, finish_reason behavior, and round-trip incompatibility caveats.

Tests

• 25 fingerprinting tests (analyzer + 2 backends + adapter integration + error swallowing)
• 11 validation-retry derivation tests
• 2 Cerebras pricing tests
• 828 total (was 792 in alpha.23; +36 new, 0 regressions across the other 6 packages)

Backwards compatibility

All changes additive. When `fingerprintCache` is undefined (default), the adapter behaves identically to alpha.23. Existing onRetry filters keep working unchanged. The Registry's observability.onValidationRetry hook (type-only since alpha.21) now optionally fires via the helper.

Empirical sources

• Babak's architectural pushback across the alpha.22 → alpha.23 transition that the static catalog is unsustainable
• 2026-06-24 research survey (10 parallel agents) covering DeepInfra, Parasail, SambaNova, Cerebras, Groq
• ADW's 2026-06-19 production diagnostic confirming the failure mode (silent first-call penalty on unrecognized reasoning models)

Install

`pnpm add @llm-ports/core@alpha @llm-ports/adapter-openai@alpha`

All 7 publishable packages bumped to 0.1.0-alpha.24.

What's NOT in this release (deferred)

• Streamed cost surfacing for `onCost` / `onTokenUsage` — complex semantics (when does a stream complete?); deserves its own release
• LP-REQ-01 resilient fallback preset — no production blocker
• `llm-ports` meta-package (unscoped npm landing page) — belongs in v0.1.0 GA prep