Class WorldModel

Optionalaborted?: boolean

Optionalassumptions?: string[]

Optionalcitations?: { context: string; doi?: string; text: string; url: string }[]

Optionalcost?: {
    breakdown?: Record<string, number>;
    cachedReadTokens?: number;
    cacheSavingsUSD?: number;
    inputTokens?: number;
    llmCalls?: number;
    outputTokens?: number;
    totalUSD: number;
}

• Optionalbreakdown?: Record<string, number>

  Per-site / per-model breakdown: { director: 0.12, departments: 0.34 }.

• OptionalcachedReadTokens?: number

• OptionalcacheSavingsUSD?: number

• OptionalinputTokens?: number

• OptionalllmCalls?: number

• OptionaloutputTokens?: number

• totalUSD: number

Optionaldecisions?: {
    actor?: string;
    choice: string;
    outcome?:
        | "risky_success"
        | "risky_failure"
        | "conservative_success"
        | "conservative_failure";
    rationale?: string;
    reasoning?: string;
    scenarioExtensions?: Record<string, unknown>;
    time: number;
}[]

Optionaldisclaimer?: string

OptionalfinalState?: {
    capacities?: Record<string, number>;
    environment?: Record<string, string | number | boolean>;
    metrics: Record<string, number>;
    politics?: Record<string, string | number | boolean>;
    scenarioExtensions?: Record<string, unknown>;
    statuses?: Record<string, string | boolean>;
}

• Optionalcapacities?: Record<string, number>

  Capacity constraints: life support, housing, budget.

• Optionalenvironment?: Record<string, string | number | boolean>

  Environmental conditions: weather, radiation, depth, altitude.

• metrics: Record<string, number>

  Numeric gauges: food, power, population, morale, VO2max, whatever.

• Optionalpolitics?: Record<string, string | number | boolean>

  Political/social pressures. Values may be numeric or categorical.

• OptionalscenarioExtensions?: Record<string, unknown>

• Optionalstatuses?: Record<string, string | boolean>

  Categorical state: governance status, alignment, phase.

OptionalfinalSwarm?: {
    agents: {
        age?: number;
        agentId: string;
        alive: boolean;
        childrenIds?: string[];
        department: string;
        featured?: boolean;
        generation?: number;
        marsborn?: boolean;
        mood?: string;
        name: string;
        partnerId?: string;
        psychScore?: number;
        rank?: "junior" | "senior" | "lead" | "chief";
        role: string;
        shortTermMemory?: string[];
    }[];
    births?: number;
    deaths?: number;
    morale?: number;
    population: number;
    scenarioExtensions?: Record<string, unknown>;
    time: number;
    turn: number;
}

• agents: {
      age?: number;
      agentId: string;
      alive: boolean;
      childrenIds?: string[];
      department: string;
      featured?: boolean;
      generation?: number;
      marsborn?: boolean;
      mood?: string;
      name: string;
      partnerId?: string;
      psychScore?: number;
      rank?: "junior" | "senior" | "lead" | "chief";
      role: string;
      shortTermMemory?: string[];
  }[]

  Every agent in the swarm at snapshot time, alive or dead.

• Optionalbirths?: number

  Number of births this turn.

• Optionaldeaths?: number

  Number of deaths this turn.

• Optionalmorale?: number

  Aggregate morale 0..1 (population-weighted).

• population: number

  Aggregate counts derived from agents.

• OptionalscenarioExtensions?: Record<string, unknown>

• time: number

  Scenario time at snapshot (years/quarters/ticks per scenario).

• turn: number

  Turn number this snapshot was taken at (0-indexed).

Optionalfingerprint?: Record<string, string | number>

OptionalforgedTools?: {
    approved: boolean;
    confidence?: number;
    department?: string;
    description?: string;
    name: string;
}[]

Optionalintervention?: {
    adherenceProfile?: { expected: number; risks?: string[] };
    category?: string;
    description: string;
    duration?: { unit: string; value: number };
    id: string;
    mechanism?: string;
    name: string;
    scenarioExtensions?: Record<string, unknown>;
    targetBehaviors?: string[];
}

OptionalleveragePoints?: string[]

metadata: {
    completedAt?: string;
    forkedFrom?: { atTurn: number; parentRunId: string };
    mode: "turn-loop" | "batch-trajectory" | "batch-point";
    runId: string;
    scenario: { id: string; name: string; version?: string };
    scenarioExtensions?: Record<string, unknown>;
    seed?: number;
    startedAt: string;
}

• OptionalcompletedAt?: string

• OptionalforkedFrom?: { atTurn: number; parentRunId: string }

  When this run was produced by forking a prior run, records the parent run-id + the turn at which the fork happened. Consumers walking a fork chain follow this link transitively through stored artifacts. Omitted for fresh (non-forked) runs.

  Added in 0.7.x with the WorldModel.fork() API. Additive + optional; no COMPILE_SCHEMA_VERSION bump required.

• mode: "turn-loop" | "batch-trajectory" | "batch-point"

• runId: string

  Unique identifier for this run. UUID, slug, or host-assigned id.

• scenario: { id: string; name: string; version?: string }

  • id: string

  • name: string

  • Optionalversion?: string

    Scenario version; not artifact version. Optional.

• OptionalscenarioExtensions?: Record<string, unknown>

• Optionalseed?: number

  Absent for non-deterministic runs (LLM-only synthesis without a seeded kernel).

• startedAt: string

Optionaloverview?: string

OptionalproviderError?:
    | {
        actionUrl?: string;
        kind: "unknown"
        | "auth"
        | "quota"
        | "rate_limit"
        | "network";
        message: string;
        provider: string;
    }
    | null

OptionalriskFlags?: {
    detail: string;
    label: string;
    scenarioExtensions?: Record<string, unknown>;
    severity: "low" | "medium" | "high";
}[]

OptionalscenarioExtensions?: Record<string, unknown>

OptionalspecialistNotes?: {
    confidence?: number;
    detail?: {
        citations?: {
            context: string;
            doi?: string;
            text: string;
            url: string;
        }[];
        openQuestions?: string[];
        opportunities?: { description: string; impact: "low"
        | "medium"
        | "high" }[];
        recommendedActions?: string[];
        risks?: {
            description: string;
            severity: "low" | "medium" | "high" | "critical";
        }[];
    };
    domain: string;
    scenarioExtensions?: Record<string, unknown>;
    summary: string;
    trajectory?: "positive" | "negative" | "neutral" | "mixed";
}[]

Optionalsubject?: {
    conditions?: string[];
    id: string;
    markers?: {
        category?: string;
        id: string;
        interpretation?: string;
        value?: string;
    }[];
    name: string;
    personality?: Record<string, number>;
    profile?: Record<string, unknown>;
    scenarioExtensions?: Record<string, unknown>;
    signals?: {
        label: string;
        recordedAt?: string;
        unit?: string;
        value: string | number;
    }[];
}

Optionaltrajectory?: {
    points?: {
        metrics: Record<string, number>;
        scenarioExtensions?: Record<string, unknown>;
        time: number;
    }[];
    timepoints?: {
        confidence?: number;
        highlightMetrics?: {
            color?: string;
            direction?: "up"
            | "down"
            | "stable";
            label: string;
            value: string;
        }[];
        label: string;
        narrative?: string;
        reasoning?: string;
        scenarioExtensions?: Record<string, unknown>;
        score?: { label: string; max: number; min: number; value: number };
        time: number;
        worldSnapshot?: {
            capacities?: Record<string, number>;
            environment?: Record<string, (...) | (...) | (...) | (...)>;
            metrics: Record<string, number>;
            politics?: Record<string, (...) | (...) | (...) | (...)>;
            scenarioExtensions?: Record<string, unknown>;
            statuses?: Record<string, (...) | (...) | (...)>;
        };
    }[];
    timeUnit: { plural: string; singular: string };
}

• Optionalpoints?: {
      metrics: Record<string, number>;
      scenarioExtensions?: Record<string, unknown>;
      time: number;
  }[]

  Lightweight per-sample metric records; good for sparklines.

• Optionaltimepoints?: {
      confidence?: number;
      highlightMetrics?: {
          color?: string;
          direction?: "up" | "down" | "stable";
          label: string;
          value: string;
      }[];
      label: string;
      narrative?: string;
      reasoning?: string;
      scenarioExtensions?: Record<string, unknown>;
      score?: { label: string; max: number; min: number; value: number };
      time: number;
      worldSnapshot?: {
          capacities?: Record<string, number>;
          environment?: Record<string, (...) | (...) | (...) | (...)>;
          metrics: Record<string, number>;
          politics?: Record<string, (...) | (...) | (...) | (...)>;
          scenarioExtensions?: Record<string, unknown>;
          statuses?: Record<string, (...) | (...) | (...)>;
      };
  }[]

  Rich labeled snapshots with narrative + score; good for timepoint cards.

• timeUnit: { plural: string; singular: string }