Move compile-time evaluation to DSPy's TypeSafe adapter without losing budget, identity and consent guarantees #91

Blocked by: #90

Problem and outcome

We maintain our own native TypeSafe adapter (TypeSafeBackend over typesafe-sdk). DSPy 3.4 now ships dspy.experimental.TypeSafe, an upstream Jev client behind the normal lm= interface with request translation, probability-evidence decoding, shared cache, usage tracking, callbacks and async. Keeping a parallel adapter duplicates upstream work and risks drift from the native contract.

The decision is to move compile-time evaluation to DSPy's adapter, while keeping the guarantees this project exists to provide. Upstream's PR #10463 leaves several of those guarantees unaddressed or not described, so the move is a wrapper plus a gap analysis, not a drop-in swap:

Also from that PR: nested decision outputs warn, generative optimizers are unsupported with the TypeSafe client (so teacher traffic must stay on a generative LM, as today), and the API is explicitly experimental and may change without warning.

Decision required, not assumed: AGENTS.md and the README state that the frozen runtime must not import DSPy. Either the runtime keeps a direct SDK backend (two paths, tested equivalent) or that invariant is changed deliberately with a documented rationale. Do not weaken it silently.

Implementation tasks

• Complete Verify compatibility with DSPy 3.4 and decide the supported version range #90 first and pin the verified DSPy version.
• Write the gap analysis above against the actual 3.4.x code, replacing "not described" with what the code does.
• Prototype a backend implementing our existing backend protocol on top of dspy.experimental.TypeSafe, still enforcing: versioned model pin and returned-model equality, ManagedBackend budget before dispatch, no automatic retries, allow_paid consent, our cache policy, and null-cost reporting.
• Offline equivalence tests with labeled test doubles: for the same projected state and questions, the native request and the normalized Response match the current adapter. Check that DSPy's decision-type mapping does not alter our question dictionaries (instructions, criteria, Score levels).
• Hierarchy: confirm per-leaf requests, attempt reservation and settlement, the evidence ledger, resume and replay behave identically.
• Decide the runtime boundary (see above) and record the decision in AGENTS.md, README.md and docs/ARCHITECTURE.md.
• Remove or deprecate the old adapter only after equivalence passes and the decision is recorded. Update docs/INTEGRATIONS.md (TypeSafe contract) and docs/SECURITY.md.

Acceptance criteria

• All existing tests pass; budget, identity and consent behavior is preserved, or changed explicitly with updated docs and tests.
• No live calls without explicit consent; offline tests are labeled as test doubles, not Jev results.
• The experimental status and the pinned upstream version are documented.

Source anchors

• DSPy PR #10463: decision types and System One clients
• DSPy Jev decision tutorial
• src/typewright/backends.py, src/typewright/runtime.py, src/typewright/hierarchy_runtime.py, src/typewright/hierarchy_evidence.py, docs/INTEGRATIONS.md, AGENTS.md. Paths use the typewright layout from PR Rename the project to Typewright #89.