WorldModel

The WorldModel primitive defines an optional predictive planning surface that an agent can use to simulate consequences, estimate risk, and compare candidate actions before acting. It is distinct from Memory: Memory preserves and retrieves past state, while WorldModel generates bounded expectations about possible future states.

URI pattern: claw://local/world-model/{name}

Schema

claw: "0.3.0"
kind: WorldModel
metadata:
  name: "environment-model"
  version: "1.0.0"
spec:
  paradigm: "hybrid"             # "implicit" | "explicit" | "simulator" | "hybrid"
  scope: "agent-wide"            # "agent-wide" | "task-scoped"

  memory_ref: "hybrid-memory"

  backend:
    type: "tool"                 # "tool" | "provider" | "custom"
    ref: "environment-simulator"

  predicts:
    state: true
    observation: true
    risk: true
    cost: true

  planning:
    horizon: "adaptive"          # "adaptive" | "bounded" | "fixed"
    uncertainty_mode: "bounded"  # "none" | "bounded" | "calibrated"
    fallback: "conservative"     # "conservative" | "retry" | "escalate"

  update:
    mode: "online"               # "online" | "batch" | "hybrid"
    evidence: "observations"     # "observations" | "observations+outcomes"

  constraints:
    policy_ref: "planning-policy"

Key Fields

Field	Required	Description
`paradigm`	Yes	Predictive style: `implicit`, `explicit`, `simulator`, or `hybrid`.
`scope`	No	Planning scope: `agent-wide` or `task-scoped`. Defaults to `agent-wide`.
`memory_ref`	No	Optional reference to a declared Memory primitive that grounds planning.
`backend`	Yes	Prediction backend and target reference. Must include `type` and `ref`.
`predicts`	No	Declares what the world model tries to estimate (`state`, `observation`, `risk`, `cost`).
`planning`	No	Policy-like planning hints: horizon, uncertainty handling, fallback behavior.
`update`	No	How the world model incorporates experience over time.
`constraints`	No	Optional policy binding for budget, safety, or simulation-side effects.

Paradigms

Paradigm	Description
`implicit`	Predicts latent future state without reconstructing full observations.
`explicit`	Predicts observations or environment snapshots directly.
`simulator`	Delegates future-state generation to an external simulator or environment tool.
`hybrid`	Combines latent prediction, simulators, rules, or model calls.

Validation Rules

The backend object is REQUIRED and MUST contain both type and ref.
If memory_ref is present, it MUST resolve to a declared Memory primitive.
If constraints.policy_ref is present, it MUST resolve to a declared Policy primitive.
scope defaults to agent-wide when omitted.
WorldModel is OPTIONAL at all conformance levels. Runtimes that do not implement predictive planning MAY ignore this primitive after validation.

Relationship to Skill and Memory

Skill may reference a world model through world_model_ref.
Memory may ground planning through memory_ref.
Policy may constrain expensive or risky simulations through constraints.policy_ref.

That separation is intentional. A world model is not a one-off skill and it is not just another memory store. It is a reusable planning surface that multiple skills can share.

Design Rationale

CKP 0.3.0 introduces WorldModel as an optional primitive instead of burying predictive planning inside prompt text or tying it to a single workflow. This keeps planning reusable, declarative, and separable from execution. It also lets runtimes expose predictive planning without introducing new JSON-RPC methods in this release.