Simulation Suite

Scenario-driven exhaustive verification for the three-layer development model

Author
Affiliation

SSCCS Foundation

SSCCS Foundation

Published

July 13, 2026

Abstract

nexus-sim implements the same core storage traits as production backends and wraps them in edge-emulating async boundaries. It validates the three-layer development model: consumption scenarios define what must hold true, nexus-sim proves whether the orchestration layer enforces them, and capability gap reports tell the foundation what to provide. Every run produces a cryptographically signed proof artifact.

The Core Loop

nexus-sim is the infrastructure that drives this loop on a multi-modal coordinate space covering the record lifecycle domains:

Consumption Scenario (immutable domain requirement)
    ↓ expressed as
nexus-sim Test Case
    ↓ run against current stack
PASS → scenario is a permanent regression test
FAIL → gap found:
    ├── Orchestration layer insufficient → update orchestration → re-run
    └── Foundation capability missing → update foundation → re-run
    ↓
Re-run all prior scenarios → confirm no regression
    ↓
Commit. The loop tightens with every iteration.

nexus-sim’s test suite is always ahead of the implementation. Every scenario is either passing (verified) or failing (gap identified). There is no gap between what the system should guarantee and what it is tested for. The loop compresses the feedback cycle from “weeks of manual validation” to “seconds of automated verification.”

Architectural Role

nexus-sim implements the three-layer development model defined in Development. It serves two functions that are the same mechanism at different depths in the stack:

  • At the trait level: nexus-sim is the in-memory implementation of the reference storage runtime, the multi-modal coordinate space covering the record lifecycle domains, backed by KeyValueStore, BlobStore, ObjectStore, and SessionExecute. It validates the persistence contracts that production backends implement. A test written against nexus-sim runs unmodified against any real backend.
  • At the async boundary: Nexus-sim wraps its own storage inside an async IO bridge, an HTTP server that reproduces the I/O patterns, latency profiles, and failure modes of a specific deployment target (CF Workers, ROS2, blockchain, etc.).

The same trait, two depths. The inner depth tells you the logic is correct. The outer depth tells you the logic survives production conditions.

Figure 1: nexus-sim validates the three layers: trait-level tests pass everywhere; emulator-level tests discover what the orchestration layer must handle.

Scenario-Driven Reverse Development

Instead of implementing a feature and then writing tests, nexus-sim starts from the consumption scenario and works backward:

  1. Define the consumption scenario (immutable domain Fact)
  2. Express as a nexus-sim test case against the trait-level implementation
  3. Run — FAIL (orchestration does not yet implement the rule)
  4. Update orchestration until test passes at trait level
  5. Route same test through async-boundary emulator — may FAIL
  6. Update orchestration until it passes under production I/O conditions
  7. Commit. The scenario is now a permanent test at both depths.

nexus-sim’s test suite is always ahead of the implementation. Every scenario is either passing or failing. There is no gap between what the system should guarantee and what it is tested for.

Attack Scenarios

The primary consumption scenarios nexus-sim validates are the 7 attack vectors against the exchange contract. These are defined in Proof by Structure: Direct Free-Riding, Evasive Free-Riding, Falsified Contribution, Poison Injection, Intent Spam, Replay Attack, and Sybil Attack. Each scenario has a parameterized agent model, expected outcome, and test at both trait and async-boundary depths. See the Proof by Structure document for the full definition of each scenario.

Game-Theoretic Scenarios

Alongside the structural violation scenarios, nexus-sim runs a second class of scenarios that test whether the exchange contract produces the intended cooperative equilibrium when agents are free to choose their behavior. These scenarios do not attempt to breach the contract. They test its game-theoretic stability through iterated interactions over multiple turns and generations.

Each scenario executes in an isolated environment — a fresh reference storage runtime instance with a deterministic clock — so that no state leaks between scenarios. This isolation is structurally identical to a virtual machine: the scenario cannot observe outcomes of other scenarios, cannot persist state across runs, and is reset before the next scenario executes.

Scenario Agent Strategies What It Tests CI Gate
Basic Cooperation Tit-for-Tat vs Always Defect vs Always Cooperate vs Grudger Whether cooperative strategies (TFT, Grudger) outscore defectors in a round-robin tournament over 200 turns score(TFT) > score(AlwaysDefect)
Evolutionary Stability Tit-for-Tat vs Always Defect vs Random (500 generations, population-proportional selection) Whether cooperation survives evolutionary pressure without external enforcement extant_strategies contains TFT
Generous Forgiveness Generous TFT vs Always Defect vs Grudger Whether a forgiving strategy can recover from occasional defection while avoiding exploitation cooperation_rate > 0.6
FIH Intent Lifecycle Honest agents vs defectors, each submitting and resolving FIH Intents Whether honest agents (who faithfully claim, heartbeat, and conclude) outperform defectors (who drop Intents or falsify results) in a storage game honest_completion_rate > 0.7 and false_conclusion_rate < 0.1

Each scenario checks a quantitative bound (cooperation rate, score ratio, completion rate). If the bound is violated, the scenario produces a failing Fact and the CI gate rejects the build.

Architecture

nexus-sim is neither a helper layer nor a consumer abstraction. It implements the same trait interfaces as every production storage backend, modeled as a tiered state model:

  • Fact (X axis) — immutable committed data, the canonical record
  • Intent (Y axis) — pending claims awaiting resolution
  • Hint (Z axis) — derived governance rules from simulation patterns
  • Temporal coordinator (T axis) — temporal ordering, delta rollups, cold storage epochs

The core storage is the reference storage runtime, which materializes this tiered state model in memory. It implements KeyValueStore, BlobStore, ObjectStore, and SessionExecute — the same trait contracts that all production backends satisfy. A test that passes against the reference storage runtime passes against any real backend without modification, because both speak the same trait contract. There is no adapter layer.

DualStorage and PetgraphStorage remain available as optional or legacy implementations but are no longer the primary storage. The reference storage runtime is the reference implementation that all new scenarios target.

On top of the reference storage runtime, the async IO bridge wraps the same storage behind an async HTTP boundary. The HTTP layer faithfully reproduces the exact I/O patterns, latency distributions, failure modes, and concurrency semantics of the target deployment. The same trait, the same test, now exercised under production-like conditions. Delta rollup is the delta accumulation mechanism: each session accumulates state-space deltas and flushes them as a single atomic commit, mimicking the write path of cold storage rollups.

Agent Model

Each simulated agent is parameterized with two axes: an outer role and an inner game-theoretic strategy. The role defines what FIH operations the agent is permitted to perform. The strategy defines how the agent decides, on each turn, whether to cooperate or defect.

Parameter Values Description
Role honest, free-rider, poisoner, spammer, Sybil Behavioral profile defining permitted FIH operations
Game strategy Tit-for-Tat, Always Defect, Always Cooperate, Grudger, Pavlov, Random Moment-to-moment decision function: (history, context) -> Action mapped to Cooperate / Defect
API surface trait-level (direct), overlay (exchange_fact), async-boundary (HTTP) Which depth of the stack the agent targets
Signature key valid, forged, missing Cryptographic identity
Data payload valid, empty, structurally invalid, replayed What the agent commits

Test Harness (Two Depths)

Depth 1 — Trait level (sync, in-process, no I/O):
  nexus-sim implements the reference storage runtime (tiered state model)
  → Consumer calls trait methods directly
  → Deterministic, sub-millisecond

Depth 2 — Async boundary (HTTP, with emulated production I/O):
  nexus-sim storage → async IO bridge HTTP server
  → Consumer sends HTTP request
  → Server injects target-specific latency, contention, failure

The same test suite runs at both depths. Depth 1 proves logical correctness. Depth two proves the orchestration survives production I/O.

Scenario Runner

Figure 2: Each scenario run at each depth produces a signed Fact; the aggregate forms a verifiable proof.

Implementation

Repository Location

Within the nexus monorepo. Planned to graduate to a dedicated nexus-sim workspace when the suite covers multiple domains.

Phase 0: Core Trait Implementation (Complete)

The reference storage runtime as the in-memory core, backed by KeyValueStore, BlobStore, ObjectStore, and SessionExecute. This is the foundation that every emulator wraps.

  • Phase 0: Core traits (Blackboard, FactCapable, IntentCapable, HintCapable) implemented
  • Phase 0.5: VECompositeStorage HTTP server — superseded by the reference storage runtime
  • Phase 1: Exchange contract scenarios — reference test scenarios validated
  • Phase 2: Three-layer validation loop — comprehensive validation suite, automated verification passes
  • Phase 3: Persistence contracts + Time Machine tests

Deliverable: All phases 0-3 complete. Reference storage runtime passes foundation tests, persistence contract satisfaction, WASM build, and Time Machine compatibility.

Phase 0.5: VECompositeStorage HTTP Server

The trait implementations wrapped behind an async HTTP boundary, with production I/O emulation for CF Workers.

Component Priority Depends On
KV endpoint (GET/PUT/DELETE) Immediate Phase 0
R2 blob endpoint (PUT/GET/DELETE) Immediate Phase 0
DO CAS endpoint (POST with compare-and-swap) Immediate Phase 0
Failure injection (latency, timeout, CAS conflict) Phase 0.5 Phase 0
Multi-worker contention (two clients, same CAS key) Phase 0.5 Phase 0

Deliverable: HTTP server. Existing tests pass through it. Failure injection operational.

Phase 1: Exchange Contract Scenarios

Component Priority Depends On
Agent model with parameterized roles and game strategies Phase 1 Phase 0
7 attack scenarios as automated tests Phase 1 Agent model
4 game-theoretic scenarios as automated tests Phase 1 Agent model
exchange_fact() mock overlay Phase 1 —
Violation matrix output Phase 1 All scenarios
Both depths (trait-level + HTTP) for all scenarios Phase 1 Phase 0.5

Deliverable: All 7 structural + 4 game-theoretic scenarios executable at both depths. Violation matrix and cooperation statistics generated per run.

Phase 2: Three-Layer Validation Loop

Component Priority Depends On
Orchestration layer introduced as single test target Phase 2 Phase 1
Scenario failure at trait depth → orchestration change → pass Phase 2 Phase 1
Scenario failure at HTTP depth → orchestration change → pass Phase 2 Phase 0.5
Foundation capability gap reporter Phase 2 —
Full regression suite on every change (both depths) Phase 2 —
CI integration: PR blocked if any scenario fails Phase 2 —

Deliverable: CI enforces three-layer model. No commit can break a consumption scenario without being caught.

Phase 3: Persistence Contracts + Time Machine Tests

Component Priority Depends On
Flush lifecycle management for the reference storage runtime Phase 3 Reference storage runtime (Phase 0)
Cold storage support + scan + time range capabilities Phase 3 Flush lifecycle
Time Machine tests (retrograde query, historical freeze) Phase 3 Cold storage support
Delta rollup as accumulation over the tiered state model Phase 3 Flush lifecycle
WASM build target for the reference storage runtime Phase 3 Phase 0-2
Full validation across all phases Phase 3 All prior

Deliverable: Persistence contract satisfaction. Time Machine temporal query support. WASM build succeeds. All validation passes.

Phase 4: Cross-Domain Expansion

Domain Emulated Backend Real Binding Priority
Edge compute VECompositeStorage HTTP CF Workers KV / R2 / DO Phase 0.5
Robotics ROS2 topic pub/sub over simulated nodes Real ROS2 Humble Phase 4
Blockchain Simulated validator with SessionExecute On-chain WASM runtime Phase 4
Edge AI Fake ONNX runtime returning canned results Real NPU / GPU inference Phase 4
Distributed tx Local 2PC coordinator with injected failures Global consensus Phase 4

Each domain wraps the same trait implementations. The core never changes.

Deliverable: Dedicated nexus-sim workspace with per-domain CI pipeline.

CI Integration

Every PR:
  └── Phase 0 tests (trait-level, both depths)
  └── Phase 1 scenarios (all 7 structural + 4 game-theoretic, both depths)
  └── Phase 2 regression (all prior scenarios, both depths)
  └── Failure if any scenario fails at trait depth
  └── Warning if scenario fails at HTTP depth (orchestration gap)

Every release:
  └── Full suite at all depths
  └── C2PA-signed proof artifact generated
  └── Proof attached to release metadata

Simulation Output

After exhaustive simulation across all scenarios at both depths, nexus-sim produces:

Violation Matrix

Depth: trait-level (in-memory, no I/O)
Scenario                    | Strategy       | Result
----------------------------|----------------|--------
Direct Free-Riding          | read_fact()    | BLOCKED (no such API)
Evasive Free-Riding         | empty data     | BLOCKED (commit rejected)
...

Depth: async-boundary (HTTP, CF Workers profile)
Scenario                    | Strategy       | Result
----------------------------|----------------|--------
Direct Free-Riding          | read_fact()    | BLOCKED (no such API)
Evasive Free-Riding         | empty data     | BLOCKED (commit rejected)
...

Proof Artifact

A C2PA-signed manifest certifying that no scenario at either depth resulted in successful data extraction without valid contribution.

Hint Generation

New governance rules (Hint) derived from simulation patterns, applied to the live Blackboard. If Intent Spam reveals a degradation threshold at the HTTP depth that does not appear at the trait depth, a Hint is generated to throttle at that threshold — the discovery of a production condition the trait test could not reveal.

Domain Recurrence

The architecture nexus-sim defines — scenario-driven exhaustive verification with parameterized agent models, depth selection, violation matrices, and cryptographic proof aggregation — is domain-agnostic. It applies identically to any verification loop where a consumption scenario must be proven against an implementation.

Component nexus-sim (infrastructure) ev (silicon verification)
Scenario 7 exchange-contract attack vectors + 4 game-theoretic scenarios XIF constraint specification
Agent model roles (honest, free-rider, poisoner, spammer, Sybil) + game strategies (TFT, AlwaysDefect, Grudger, Pavlov, Random) ISA combinations, pipeline depths, cache configs
Depth trait-level / async-boundary HTTP behavioral / RTL / gate-level
Output violation matrix coverage matrix
Proof C2PA-signed scenario coverage C2PA-signed verification proof

The scenario runner, violation matrix generator, depth selection mechanism, and C2PA proof aggregator are shared infrastructure. Only the agent model and the storage backends change per domain. This is F-I-H recursion applied to verification itself — the infrastructure that verifies the system uses the same pattern the system provides to domain verifiers.

A future version of nexus-sim may directly host ev’s scenario definitions, running silicon verification scenarios through the same harness that runs exchange-contract scenarios today. The core loop is identical.

Dependencies

Issue Component Needed By
#66 IoBufferSession Phase 0
#71 Merkle chain + cryptographic signatures Phase 3
#7 StorageRead, FactCapable, IntentCapable, HintCapable traits All phases

Acceptance Criteria