Foundation: decision backends with typed answers, replay, and scripted modes #63

Goal

One small interface that every notebook calls, so a recipe runs offline from fixtures and live against Jev with the same question definitions.

Scope

• Question definitions for Choice, Noul, and Score that mirror the TypeSafe request shape: instructions, and criteria as a mapping for Choice or an ordered list for Score. Read S02 and the SDK reference before designing these.
• Typed answer objects that mirror the response shape: Choice has choice, probabilities, confidence; Score has score, probabilities, confidence, legend; Noul has noul only.
• A Backend protocol with one call taking state and a mapping of named questions, returning named answers plus model and usage.
• ReplayBackend: answers from recorded fixtures keyed by a stable hash of state and questions. A miss raises an error that names the missing key. It never fabricates an answer.
• ScriptedBackend: a deterministic, seeded stand-in driven by a function, for closed-loop recipes where the next request depends on earlier answers. Its answers are always marked synthetic.
• get_backend() that returns the replay or scripted backend by default and the live backend only when JEV_COOKBOOK_LIVE=1.
• Every answer carries provenance: synthetic or recorded, and for recorded answers the model string and date.

Acceptance criteria

• Unit tests cover hashing stability, replay hits and misses, scripted determinism under a seed, and provenance on every answer
• A request mixing all three question types round-trips through ReplayBackend
• Importing the package and using the offline backends works with typesafe-sdk not installed
• Public API is documented with docstrings and one short usage example
• Lint and tests pass in CI, or locally with the output pasted in the pull request if CI does not exist yet

Dependencies

• Blocked by Foundation: project scaffolding and Python package skeleton #61 (project scaffolding and Python package skeleton)
• Unblocks Foundation: opt-in live Jev backend and response recorder #64, Foundation: fixture specification and validator #65, Foundation: recipe template and scaffolder #68, Foundation: simulation and state primitives #70
• Tracked in Epic: Foundation #74

References

• Recipe contract
• Catalog
• TypeSafe documentation index for tools: https://docs.typesafe.ai/llms.txt
• Python SDK: https://docs.typesafe.ai/sdk/python