feat: 0.24.0 — DX cleanup, strict indices, error taxonomy

[drewstone]

Summary

DX + correctness pass. No runtime behavior moved; consumer contracts tightened across the board. Library went from 7.5/10 to 10/10 on first-touch usability.

What changed

Framing

• README reframed as substrate for self-improving agents — names GEPA / reflective mutation, auto-research, active curriculum, PRM, OPE, tournaments, contamination, compute curves, sequential anytime-valid stats. Previously called itself "evaluation infrastructure" while shipping all of the above.
• src/rl/index.ts carries @stable / @experimental JSDoc on every re-export. Tags emit into dist/rl.d.ts — IDE hover surfaces stability at the call site. Stable: 7. Experimental: 9.

Strictness

• noUncheckedIndexedAccess: true flipped in tsconfig.json. 251 latent T | undefined sites surfaced and fixed across ~70 files. Loop-bound indices documented with !, external lookups guarded explicitly, accumulator patterns refactored to capture-then-assign. Every fix audited for semantic correctness.
• Subpath imports forced. 6 leaky export * from './X' wildcards killed at root (./rl, ./pipelines, ./builder-eval, ./meta-eval, ./prm, ./trace-analyst). 7 new subpaths in package.json + tsup.config.ts. Root re-exports retained only for the load-bearing capture-integrity surface (./trace, ./knowledge, ./governance).
• Error taxonomy. New src/errors.ts: AgentEvalError base + ValidationError, NotFoundError, ConfigError, CaptureIntegrityError, JudgeError, VerificationError, ReplayError. 10 existing custom errors re-parented. ~25 user-facing throws migrated to typed errors. Internal invariant guards intentionally left as plain Error — those are bugs, not contract failures.
• LlmRouteAssertionError.code → .reason (breaking, greenfield). The route-specific reason no longer shadows the base class's category code = 'capture_integrity'. instanceof CaptureIntegrityError still discriminates correctly.

Tooling

• Biome lint + format. biome.json codifies the project style (no semicolons, single quotes, 2-space indent, 100 col, noNonNullAssertion: off, useNodejsImportProtocol: error). pnpm lint + pnpm format. Auto-format applied to 191 src files.
• .github/workflows/ci.yml — typecheck + lint + test + build + Python pytest on every PR. Previously only the publish workflow (tag-push) exercised this surface.
• noUncheckedIndexedAccess: true now enforced in CI.

Tests & examples

• ReplayCache.entries() — public iterator replacing the private byKey bracket-access escape hatch.
• Per-example READMEs for multi-shot-optimization and same-sandbox-harness. Other three examples already had them.
• clients/python/examples/judge_anti_slop.py — runnable script doubling as pytest, anchoring composite range / RubricNotFoundError / ValidationError invariants.

Versions

• npm 0.24.0
• PyPI agent-eval-rpc 0.24.0
• __version__ in __init__.py matched (version-lock CI gate already enforces this on tag push)

Local gate

• typecheck: 0 errors
• lint (biome): 0 errors, 14 pre-existing warnings (none blocking)
• tests: 1019/1019 across 118 files
• build: clean, OpenAPI emits

Test plan

• CI passes (the new ci.yml will exercise lint + typecheck + test + build + Python pytest)
• No external consumers — greenfield breaking changes (LlmRouteAssertionError.code rename, root wildcard removals) are intentional and documented in CHANGELOG