Interface contracts
The surface area of a Counterworld world.
These boundaries separate what agents can do from how runners control, inspect and evaluate a world.
Five surfaces, separate responsibilities
For callable methods and TypeScript examples, use the SDK reference. This page defines the boundaries every implementation must preserve.
| Surface | Primary consumer | Capabilities |
|---|---|---|
| Agent | Agent or harness | Production-shaped APIs, SDK behavior, MCP tools and scoped credentials. |
| Control | Runner or operator | Create, start, pause, checkpoint, restore, fork and advance time. |
| Inspection | Evaluator or debugger | Query privileged state, event history, pending schedules and diffs. |
| Simulation | Environment builder | Configure buyers, customers, admins, employees or operators, plus history, clock and event policies. |
| Evaluation | Evaluation system | Define scenarios, invariants, delayed checks, metrics and run exports. |
Every running world exposes the same control contract
- Identity
- World ID, definition version, seed, current checkpoint and clock.
- Interfaces
- Available services, interface schemas, endpoints and scoped credentials.
- Lifecycle
- Instance status, pause/resume, checkpoint, restore and teardown.
- Time
- Current simulated time, pending events and controlled advancement.
- State
- Privileged queries, event log, state diff and invariant inspection.
- Lineage
- Parent checkpoint, fork relationship and complete run configuration.
Data contracts remain explicit
World definitions and run artifacts should be machine-readable, versioned and independently validatable.
world definition
├── systems schemas, relations, mutations, permissions
├── interfaces API, SDK and MCP-compatible surfaces
├── actors buyers, admins, employees, approvers, operators
├── history generators, seeds and calibration inputs
├── clock schedules and event ordering
└── evaluators invariants, predicates and outcome metrics
Use established standards at external boundaries
| Standard | Role in Counterworld |
|---|---|
| OpenAPI | Describe HTTP interfaces and import internal service surfaces. |
| JSON Schema | Validate entities, events, configuration and exported artifacts. |
| MCP | Expose tool-oriented interfaces where agents already use MCP. |
| OpenTelemetry | Export request, tool, mutation and evaluation traces. |
| OCI | Package deployable world services and isolated runtime dependencies. |
Framework adapters remain optional. OpenEnv, Verifiers or NeMo Gym compatibility can wrap these contracts without becoming dependencies of the Counterworld core.
Version the definition and the interfaces independently
A world definition may improve its history or actor model without changing an API. An API may add an endpoint without changing existing checkpoint data. Recording both versions keeps comparisons interpretable.