World State API

Endpoint:

• GET /api/world-state

Cache policy:

• Cache-Control: public, s-maxage=60, stale-while-revalidate=300

Response Contract

{
  "schemaVersion": "2026-02-16.world-state.v1",
  "generatedAt": "2026-02-16T00:00:00.000Z",
  "installCount": 133,
  "tier": {
    "level": 2,
    "key": "tier_2_office_detail",
    "minInstallCount": 100,
    "nextInstallCount": 250
  },
  "unlocks": {
    "agentsAndDesks": true,
    "officeDetail": true,
    "exteriorPark": false,
    "blueSky": false,
    "worldRichness": false
  },
  "caps": {
    "maxAgents": 10,
    "maxDesks": 10,
    "maxOfficeProps": 12,
    "maxOfficePlants": 16,
    "maxExteriorProps": 0
  },
  "installSource": {
    "kind": "prototype",
    "name": "github_release_assets",
    "detail": "github_release_assets"
  },
  "versions": {
    "worldState": "2026-02-16.world-state.v1",
    "tierConfig": "tiers-v1"
  }
}

Install Source Modes

• Prototype mode (default): install count is derived from GitHub release .dmg download counts.
• Production mode: install count is read from backend beacon aggregate values when available.

Environment toggles used by server code:

• AGENT_OBSERVER_WORLD_INSTALL_SOURCE: prototype or production
• AGENT_OBSERVER_WORLD_INSTALL_COUNT: numeric production aggregate count
• AGENT_OBSERVER_INSTALL_BEACON_STORE_FILE: optional persistent JSON store path for install beacon dedupe/aggregate state

If production is selected, world state first uses the install-beacon aggregate count; if unavailable, it falls back to AGENT_OBSERVER_WORLD_INSTALL_COUNT, then to prototype if still unavailable.

Install Beacon Ingest API

Endpoint:

• POST /api/install-beacon

Request body contract:

{
  "installation_id_hash": "sha256_hex_64_chars",
  "app_version": "1.2.0",
  "first_seen_at": "2026-02-16T00:00:00.000Z"
}

Response:

• 202 accepted with dedupe result and uniqueInstallCount
• 400 invalid payload
• 429 rate limited (includes Retry-After)

Abuse controls:

• strict payload schema validation
• per-source IP rate limit window
• per-installation hash rate limit window
• idempotent dedupe keyed by installation_id_hash

Aggregation latency and consistency:

• aggregate updates synchronously on accepted beacon ingest (single request latency)
• aggregate reads are strongly consistent within one server process
• cross-instance consistency depends on shared persistence path (AGENT_OBSERVER_INSTALL_BEACON_STORE_FILE)

Tier thresholds, unlock flags, and per-tier entity caps are defined in one source-of-truth module:

• web/src/lib/world-tier-config.ts

Tier 1 desk/agent density layout uses deterministic desk slots from:

• web/src/lib/office-layout.ts
• web/src/lib/office-detail.ts (Tier 2 interior detail visibility)
• web/src/lib/exterior-detail.ts (Tier 3+ park + sky progression)

Performance safeguards for world growth are centralized in:

• web/src/lib/world-performance.ts (hard cap clamps + FPS/frame-time budgets)
• web/src/lib/scene-culling.ts (distance culling for non-critical props)

Performance Budgets

• targetFps: 60
• minFps: 45
• maxFrameTimeMs: 22
• p95FrameTimeMs: 18

All incoming scene cap values are clamped to configured hard caps before rendering, and non-critical plants/exterior props are distance-culled from the office focal point.

Experimental interior decorations can be toggled at runtime from the demo HUD:

• View -> Enable/Disable Experimental Decor
• Cmd/Ctrl+Shift+D