A world defines what can exist and change.

The world contract

Different creation paths produce the same runtime contract. Agents should not need to know whether a world began from the catalog, an OpenAPI document or custom code.

Systems

Entities, relationships, permissions and state transitions.

Interfaces

The APIs, SDK behavior or MCP tools exposed to agents.

Mutations

Accepted inputs, rejected inputs, side effects and invariants.

Population

Buyers, customers, admins, employees or operators grounded in state.

History

How coherent records and prior events are generated.

Evaluators

Rules and metrics used to judge resulting world state.

Three creation paths

The path changes how much definition work is required, not what the resulting world can do.

Create definitions with the SDK

Start from catalog systems

import {
  catalog,
  buyers,
  storeAdmins,
  warehouseOperators,
} from "@counterworld/sdk";

const draft = await counterworld.definitions.create({
  name: "retail-operations",
  systems: [catalog.shopify(), catalog.stripe()],
  population: [
    buyers({ count: 12_000 }),
    storeAdmins({ count: 24 }),
    warehouseOperators({ count: 80 }),
  ],
  history: { years: 2 },
});

const version = await draft.publish();

Infer an internal world from service contracts

const draft = await counterworld.definitions.fromOpenAPI({
  name: "fulfillment-operations",
  specs: ["./orders.yaml", "./warehouse.yaml"],
});

draft.relations.add("order.fulfilledBy", "shipment.id");
draft.invariants.add("allocated_stock_lte_available_stock");

const report = await draft.validate();
if (!report.valid) throw new Error(report.summary);

const version = await draft.publish();

Publishing freezes the schemas, mutation behavior, actor configuration and evaluators into one reproducible version.

Shape, definition and instance

A shape can support many definitions. A definition can create many independent instances. Each instance receives its own state, identities, credentials, clock and event queue.

Definitions are versioned; instances are traceable

A run should identify the exact definition, seed, starting checkpoint and configuration that produced it. This makes failures reproducible even after the world definition evolves.

• Definition version identifies schemas, mutations, actor logic and evaluators.
• Seed identifies generated identities, history and stochastic choices.
• Checkpoint identifies the exact starting state and clock.
• Run export identifies every agent, actor and scheduled event applied afterward.

Fidelity is behavioral, not only structural

Matching endpoint names and response schemas is insufficient. A faithful world must accept, reject and propagate mutations like the represented system.