World API / v0.1 — the behaviour surface of a World-Sim instance

This is the reference for what your code can do inside a World-Sim world: the w object a behaviour receives, the names in scope, the per-template differences, and the counterfactual oracle that scores it. The product guide is specs/world-sim/v0.1 (buying, endpoints, credentials, templates). This spec is the engine contract underneath it.

The simulator engine itself is private. Everything listed here is supported surface: it is kept stable within v0.x (additions only). Anything else you can reach on w is internal state — it works today, but it can change or disappear without a version bump, and the oracle will not treat your reliance on it as a contract.

---

A behaviour is Python source that defines one function:

You submit it in two places, and it runs the same way in both:

Execution model.

simulated staff have done the day's baseline work. w.day is still the day that just ran.

configuration; keep state in the world instead (w.after/w.due, or records you created).

compile error: the oracle answers 400 {"error": "behavior failed to compile", "detail": …}.

200 characters). The world keeps ticking. A day that runs cleanly clears it, so the oracle's behavior_run_error shows only the last day's error — test on a day that has matching records.

Names in scope. Only these are visible to run without an import:

Put imports inside run. Module-level names in your source are not visible to run (import re at the top → NameError at run time). This is the most common first failure.

1. Where your code runs

2. The core surface (every template)

3. Surface that only some templates have

4. Per template: purchase orders, master data, KPIs

5. The oracle: POST {eval_oracle}/counterfactual

6. Versioning