Foundation: simulation and state primitives #70

Goal

Shared building blocks for recipes that keep state or run a loop, so thirteen advanced recipes do not each invent a queue and a simulator.

Scope

• A deterministic, seeded simulator base: reset, observe, enumerate legal actions, step, and a trajectory log that can be replayed.
• A simulated review queue and action log, used wherever a recipe says an item goes to review or an action is simulated.
• A versioned key-value store that keeps provenance and never deletes, with history and rollback.
• A transactional wrapper: validate, apply, roll back on failure, with a replayable log.
• A budget helper for retry limits, call budgets, and stop conditions, raising when exceeded.
• Guidance on using ScriptedBackend to run a closed loop offline.

Acceptance criteria

• Each primitive has tests, including property-style tests for the invariants (no deletion, budget never exceeded, replay reproduces state)
• Same seed gives the same trajectory on Linux and Windows
• A short example shows a loop running offline end to end
• 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: decision backends with typed answers, replay, and scripted modes #63 (decision backends with typed answers, replay, and scripted modes)
• Unblocks the recipes labelled needs: simulator
• 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