# AGENTS.md

Overview
- This repository implements a production-oriented MVP for a verifiable algebraic DSL to model cross-server game economies.
- Architecture emphasizes modular adapters, a canonical IR, and a governance ledger with delta-sync semantics.

Tech Stack
- Python 3.8+ for core modeling and adapters
- Minimal in-repo DSL primitives (LocalEconomy, SharedSignal, PlanDelta)
- Adapters: server economy engine adapter and marketplace adapter
- Registry: GraphOfContractsRegistry for versioned contracts and adapters mapping

Testing and Commands
- Tests run with pytest (unit tests and a small integration test)
- test.sh orchestrates pytest and python -m build for packaging verification

How to contribute
- Implement a new adapter under adapters/ to plug a new backend
- Extend the DSL primitives in dsl.py and wire through core.py for simulations
- Update tests to cover new behavior
- Update README and add any necessary documentation in the package

Code Organization (high-level)
- src/idea76_gameeconomy_studio_verifiable/dsl.py: DSL primitives (LocalEconomy, SharedSignal, PlanDelta, GraphContract)
- src/idea76_gameeconomy_studio_verifiable/core.py: EconomyEngine that runs deterministic simulations
- src/idea76_gameeconomy_studio_verifiable/adapters/: starter adapters for server engine and marketplace
- src/idea76_gameeconomy_studio_verifiable/registry.py: GraphOfContracts registry
- tests/: basic unit and integration tests
- README.md, AGENTS.md, test.sh, READY_TO_PUBLISH: publish scaffolding

Roadmap reference
- Phase 0: DSL prototype, two adapters, toy cross-server scenario, deterministic backtesting
- Phase 1: Global constraints and governance ledger skeleton, secure aggregation for cross-server signals
- Phase 2: Cross-server demo with basic contract example and adapter blueprint
- Phase 3: End-to-end pilot in testbed with delta-sync and auditability