neXus Simulation Suite

The Core Loop

nexus-sim is the infrastructure that drives this loop:

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 Architecture. 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 KeyValueStore, BlobStore, ObjectStore, and SessionExecute — the exact same trait interfaces that CompositeColdStorage depends on. A test written against nexus-sim runs unmodified against any real backend.
At the async boundary: Nexus-sim wraps its own trait implementations inside VECompositeStorage, 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:

Define the consumption scenario (immutable domain Fact)
Express as a nexus-sim test case against the trait-level implementation
Run — FAIL (orchestration does not yet implement the rule)
Update orchestration until test passes at trait level
Route same test through async-boundary emulator — may FAIL
Update orchestration until it passes under production I/O conditions
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.

Architecture

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

KeyValueStore — key-value read/write/delete
BlobStore — blob put/get/delete
ObjectStore — object put/get/list
SessionExecute — session lifecycle (hydration, execution, flush)

The trait implementations are in-memory. A test that passes against them passes against any real backend without modification, because both speak the same trait contract. There is no adapter layer.

On top of these trait implementations, VECompositeStorage wraps the same traits 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.

Agent Model

Each simulated agent is parameterized with:

Parameter	Values	Description
Strategy	honest, free-rider, poisoner, spammer, Sybil	Behavioral profile
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 KeyValueStore / BlobStore / ObjectStore
  → Consumer calls trait methods directly
  → Deterministic, sub-millisecond

Depth 2 — Async boundary (HTTP, with emulated production I/O):
  nexus-sim trait impl → VECompositeStorage 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 2 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

ext/ve-composite/ in the nexus monorepo. Planned to graduate to a dedicated nexus-sim workspace when the suite covers multiple domains.

Phase 0: Core Trait Implementation (In Progress)

The in-memory implementations of KeyValueStore, BlobStore, ObjectStore, and SessionExecute. These are the foundation that every emulator wraps.

Component	Priority	Depends On
KeyValueStore (HashMap-backed)	Immediate	—
BlobStore (HashMap-backed)	Immediate	—
ObjectStore (HashMap-backed)	Immediate	—
SessionExecute (hydration + flush)	Immediate	#66 (IoBufferSession)
Existing 21+ foundation tests pass	Immediate	—

Deliverable: Trait-level implementations complete. All foundation tests pass against them.

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 strategies	Phase 1	Phase 0
7 attack scenarios as automated tests	Phase 1	Agent model
`exchange_fact()` mock overlay	Phase 1	—
Violation matrix output	Phase 1	7 scenarios
Both depths (trait-level + HTTP) for all scenarios	Phase 1	Phase 0.5

Deliverable: All 7 scenarios executable at both depths. Violation matrix 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: Cryptographic Proof Aggregation

Component	Priority	Depends On
Each scenario run produces a C2PA-signed Fact	Phase 3	#71
Aggregate proof artifact (all scenarios, both depths)	Phase 3	Phase 2
Proof embedded in release artifact	Phase 3	—
External verifier confirms proof without re-running	Phase 3	—

Deliverable: Release artifacts include signed proof of exhaustive scenario coverage at both depths.

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, 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	XIF constraint specification
Agent model	free-rider, poisoner, spammer, Sybil	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