@agent-play/sdk 3.3.8 → 3.4.0

package/dist/browser-DhKo5Hv7.d.ts

@@ -0,0 +1,2237 @@
+import { z } from 'zod';
+
+type GameId = "hidden-gems" | "map-recall" | "price-check" | "signal-hunt" | "delivery-dash" | "lease-locker" | "talk-timer" | "daily-rotator";
+type GameCabinetEntry = {
+    readonly id: string;
+    readonly gameId: GameId;
+    readonly name: string;
+};
+declare const GAME_CABINET_CATALOG: readonly GameCabinetEntry[];
+declare const PLAYABLE_GAME_IDS: readonly GameId[];
+declare const getGameCabinetById: (id: string) => GameCabinetEntry | undefined;
+declare const getGameCabinetByGameId: (gameId: GameId) => GameCabinetEntry | undefined;
+declare const featuredGameIdForUtcDate: (date: Date) => GameId;
+declare const isGameId: (value: string) => value is GameId;
+
+/**
+ * Domain types for sessions, journeys, agents, and the shared world map exposed by the SDK and server.
+ */
+/** Role for a single line in the interaction log / chat stream. */
+type WorldInteractionRole = "user" | "assistant" | "tool";
+/**
+ * Payload for {@link RemotePlayWorld.recordInteraction}.
+ *
+ * @property playerId - Player id returned from `addAgent` / `addPlayer`.
+ * @property role - Who "spoke" the line.
+ * @property text - Plain text; may be truncated for display server-side.
+ */
+type RecordInteractionInput = {
+    playerId: string;
+    role: WorldInteractionRole;
+    text: string;
+};
+/** How the watch UI should render and coerce a single assist tool argument. */
+type AssistToolFieldType = "string" | "number" | "boolean";
+/**
+ * Per-parameter metadata for assist tools. Legacy snapshots may omit `fieldType`; the UI treats that as `"string"`.
+ */
+type AssistToolParameterSpec = {
+    fieldType: AssistToolFieldType;
+    field?: string;
+};
+/**
+ * Metadata for a tool whose name starts with `assist_`, shown as assist actions on the watch UI.
+ *
+ * @property parameters - Derived from Zod object `schema` when present: each key maps to
+ *   {@link AssistToolParameterSpec} with `fieldType` from schema introspection. May include `_note` when no schema shape exists.
+ */
+type AssistToolSpec = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+};
+/**
+ * Serializable shape returned by {@link langchainRegistration} for agent registration.
+ *
+ * @property type - Always `"langchain"` for this adapter.
+ * @property toolNames - All tool names from the agent (must include `chat_tool`). Used for assist/chat UI only; **does not** spawn map structures (see world map v3).
+ * @property assistTools - Subset of tools with `assist_` prefix, for UI buttons.
+ */
+type LangChainAgentRegistration = {
+    type: "langchain";
+    toolNames: string[];
+    assistTools?: AssistToolSpec[];
+};
+/** Minimal player identity in the SDK (without preview URL). */
+type PlayAgentInformation = {
+    id: string;
+    name: string;
+    sid: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
+/** Input fields for {@link AddAgentInput} / {@link AddPlayerInput} before `agent` is attached. */
+type PlatformAgentInformation = {
+    name: string;
+    type: string;
+    version?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+};
+/**
+ * Register an automation agent in the world, tied to **agent node identity**.
+ *
+ * Use **`langchainRegistration(agent)`** for `agent` (requires a **`chat_tool`** tool; `assist_*`
+ * tools are indexed for the watch UI).
+ *
+ * **`nodeId`** is the **agent node id** (from **`agent-play create`** when the server uses a repository).
+ * It is sent on the wire as `agentId` for server compatibility; treating it as a node id makes the
+ * contract explicit for billing, validation, and event attribution.
+ */
+type P2aEnableFlag = "on" | "off";
+type RealtimeWebrtcClientSecret = {
+    clientSecret: string;
+    expiresAt?: string;
+    model: string;
+    voice?: string;
+};
+/** OpenAI Realtime minting options used by {@link RemotePlayWorld.initAudio}. */
+type RemotePlayWorldOpenAiAudioOptions = {
+    /** Server-side OpenAI key used to mint ephemeral browser client secrets. */
+    apiKey?: string;
+    /** Realtime model id, defaults to `gpt-realtime`. */
+    model?: string;
+    /** Realtime voice id, defaults to `marin`. */
+    voice?: string;
+    /** Explicit system instructions for the realtime session. */
+    instructions?: string;
+    /** Template fallback for instructions; `{{agentName}}` placeholder is supported. */
+    instructionsTemplate?: string;
+};
+/** Configuration payload for enabling SDK-managed realtime audio initialization. */
+type RemotePlayWorldInitAudioOptions = {
+    openai: RemotePlayWorldOpenAiAudioOptions;
+};
+type AddAgentInput = PlatformAgentInformation & {
+    /** Registration from {@link langchainRegistration}. */
+    agent: LangChainAgentRegistration;
+    /** Main node id that owns the agent (required on repository-backed servers). */
+    mainNodeId?: string;
+    /** Agent node id — same value the server stores as registered `agentId`. */
+    nodeId: string;
+    /**
+     * Human passphrase for this agent node (from **`agent-play create-agent-node`** or
+     * **`AGENT_PLAY_AGENT_NODE_ID_*_*_PASSW`**). When omitted, the main node passphrase from
+     * {@link RemotePlayWorld} construction is used (local dev only).
+     */
+    agentPassphrase?: string;
+    /**
+     * When **`"on"`**, registration enables OpenAI Realtime provisioning for this agent.
+     * Omitted or **`"off"`** disables realtime voice for this registration.
+     */
+    enableP2a?: P2aEnableFlag;
+    /**
+     * Per-agent instructions for OpenAI Realtime when **`enableP2a`** is **`"on"`** (e.g. from
+     * **`personality.txt`**). Ignored when **`initAudio`** was given explicit **`openai.instructions`**,
+     * which still wins as a global override.
+     */
+    realtimeInstructions?: string;
+};
+/**
+ * Register a player (agent) in the world.
+ *
+ * @deprecated Prefer {@link AddAgentInput} and `RemotePlayWorld.prototype.addAgent` for SDK and automation; use `nodeId` there instead of `agentId`.
+ *
+ * Use **`langchainRegistration(agent)`** for `agent` (requires a **`chat_tool`** tool; `assist_*`
+ * tools are indexed for the watch UI).
+ *
+ * **`agentId`** is required: use an id from **`agent-play create`** when the server uses a repository
+ * (with account **`passwHash`** from **`RemotePlayWorld`**), or any stable string for local dev without Redis.
+ */
+type AddPlayerInput = PlatformAgentInformation & {
+    /** Registration from {@link langchainRegistration}. */
+    agent: LangChainAgentRegistration;
+    /** Main node id that owns the agent (required on repository-backed servers). */
+    mainNodeId?: string;
+    /** Registered agent id (or session-local id without Redis). */
+    agentId: string;
+    /**
+     * When **`"on"`**, registration enables OpenAI Realtime provisioning for this agent.
+     * Omitted or **`"off"`** disables realtime voice for this registration.
+     *
+     * Same semantics as {@link AddAgentInput} **`enableP2a`**.
+     */
+    enableP2a?: P2aEnableFlag;
+    /**
+     * Same semantics as {@link AddAgentInput} **`realtimeInstructions`**.
+     */
+    realtimeInstructions?: string;
+};
+/** Zone counter event surfaced on snapshots and signals. */
+type ZoneEventInfo = {
+    zoneCount: number;
+    flagged?: boolean;
+    at: string;
+};
+/** Yield counter event surfaced on snapshots and signals. */
+type YieldEventInfo = {
+    yieldCount: number;
+    at: string;
+};
+/** Repository-backed summary returned with `addAgent` when the agent is (or maps to) a stored registration. */
+type RegisteredAgentSummary = {
+    agentId: string;
+    name: string;
+    toolNames: string[];
+    zoneCount: number;
+    yieldCount: number;
+    flagged: boolean;
+};
+/** Result of `addAgent` / `addPlayer` including watch URL and registered-agent metadata from the server. */
+type RegisteredPlayer = PlayAgentInformation & {
+    previewUrl: string;
+    registeredAgent: RegisteredAgentSummary;
+    /** Echo of registration-time P2A flag (defaults to **`"off"`**). */
+    enableP2a: P2aEnableFlag;
+    /** Optional OpenAI Realtime WebRTC client-secret payload for browser-side direct voice. */
+    realtimeWebrtc?: RealtimeWebrtcClientSecret;
+    connectionId?: string;
+    leaseTtlSeconds?: number;
+};
+/** First step of a journey: user message origin. */
+type OriginJourneyStep = {
+    type: "origin";
+    content: string;
+    messageId: string;
+};
+/** Middle step: tool invocation on the map. */
+type StructureJourneyStep = {
+    type: "structure";
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+    result?: string;
+};
+/** Final step: assistant reply. */
+type DestinationJourneyStep = {
+    type: "destination";
+    content: string;
+    messageId: string;
+};
+/** Union of journey step shapes. */
+type JourneyStep = OriginJourneyStep | StructureJourneyStep | DestinationJourneyStep;
+/**
+ * Ordered journey with timestamps; sent to the server via `recordJourney`.
+ *
+ * @property steps - Ordered path from origin through tool steps to destination.
+ * @property startedAt, completedAt - Wall times for the run (client or server).
+ */
+type Journey = {
+    steps: JourneyStep[];
+    startedAt: Date;
+    completedAt: Date;
+};
+/** Journey step after server assigns coordinates (and optional structure id). */
+type PositionedStep = JourneyStep & {
+    x?: number;
+    y?: number;
+    structureId?: string;
+};
+type AgentPlayWorldMapBounds = {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+/**
+ * One agent on the world map. Prefer `streetId` with layout-driven placement; `x`/`y` are optional on wire before normalization and act as a denormalized cache after materialize.
+ */
+type AgentPlayWorldMapAgentOccupant = {
+    kind: "agent";
+    nodeId?: string;
+    agentId: string;
+    name: string;
+    streetId?: string;
+    x?: number;
+    y?: number;
+    /**
+     * Integration label from addPlayer `type` (e.g. `langchain`). Populated from the snapshot field `platform`. The legacy wire field `agentType` is deprecated and accepted only for backward compatibility when parsing JSON.
+     */
+    platform?: string;
+    toolNames?: string[];
+    assistToolNames?: string[];
+    assistTools?: AssistToolSpec[];
+    hasChatTool?: boolean;
+    enableP2a?: P2aEnableFlag;
+    realtimeInstructions?: string;
+    realtimeWebrtc?: RealtimeWebrtcClientSecret;
+    stationary?: boolean;
+    lastUpdate?: unknown;
+    recentInteractions?: Array<{
+        role: WorldInteractionRole;
+        text: string;
+        at: string;
+        seq: number;
+    }>;
+    zoneCount?: number;
+    yieldCount?: number;
+    flagged?: boolean;
+    onZone?: ZoneEventInfo;
+    onYield?: YieldEventInfo;
+};
+/** MCP server shown as a separate map occupant (distinct from LangChain agents). */
+type AgentPlayWorldMapHumanOccupant = {
+    kind: "human";
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    interactive?: boolean;
+};
+/** MCP server shown as a separate map occupant (distinct from LangChain agents). */
+type AgentPlayWorldMapMcpOccupant = {
+    kind: "mcp";
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    url?: string;
+};
+type AgentPlaySpaceAmenityKind = "supermarket" | "shop" | "car_wash";
+type AgentPlaySpaceOwner = {
+    displayName: string;
+    playerId?: string;
+    nodeId?: string;
+};
+type AgentPlaySpaceCatalogEntry = {
+    id: string;
+    name: string;
+    description: string;
+    designKey: string;
+    owner: AgentPlaySpaceOwner;
+    amenities: AgentPlaySpaceAmenityKind[];
+    activityObjectIds?: string[];
+};
+
+/** Map anchor linking one or more authored spaces or an arcade game cabinet. */
+type AgentPlayWorldMapStructureOccupant = {
+    kind: "structure";
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    worldId: string;
+    spaceIds: string[];
+    /** When set, this structure is an arcade cabinet door on Maple Ave. */
+    gameId?: GameId;
+    /** When true, the anchor is fixed map furniture (e.g. authored spaces). */
+    stationary?: boolean;
+    primaryAmenity?: AgentPlaySpaceAmenityKind;
+    amenities?: AgentPlaySpaceAmenityKind[];
+};
+/** Spatial index: axis-aligned bounds plus every agent and MCP registration placed on the grid. */
+type AgentPlayWorldMap = {
+    bounds: AgentPlayWorldMapBounds;
+    occupants: (AgentPlayWorldMapHumanOccupant | AgentPlayWorldMapAgentOccupant | AgentPlayWorldMapMcpOccupant | AgentPlayWorldMapStructureOccupant)[];
+};
+/** Wire shape for seeded world zones (matches server snapshot `worldLayout`). */
+type AgentPlayWorldLayoutZone = {
+    id: string;
+    streetId: string;
+    streetLabel: string;
+    rect: AgentPlayWorldMapBounds;
+    primaryGroup: "agent" | "space" | "arcade";
+    allowedGroups: readonly ("agent" | "space" | "arcade")[];
+};
+type AgentPlayWorldLayout = {
+    rev: number;
+    bounds: AgentPlayWorldMapBounds;
+    zones: AgentPlayWorldLayoutZone[];
+    streets: readonly {
+        id: string;
+        label: string;
+    }[];
+};
+/**
+ * Session snapshot from {@link RemotePlayWorld.getWorldSnapshot}.
+ * Agents and MCP servers appear only under **`worldMap.occupants`** (no separate `players` list).
+ */
+type AgentPlaySnapshot = {
+    sid: string;
+    worldMap: AgentPlayWorldMap;
+    worldLayout?: AgentPlayWorldLayout;
+    spaces?: AgentPlaySpaceCatalogEntry[];
+    mcpServers?: Array<{
+        id: string;
+        name: string;
+        url?: string;
+    }>;
+};
+type PlayerChainNotifyNodeRef = {
+    stableKey: string;
+    leafIndex: number;
+    removed?: boolean;
+    updatedAt?: string;
+};
+type PlayerChainFanoutNotify = {
+    updatedAt: string;
+    nodes: PlayerChainNotifyNodeRef[];
+};
+type PlayerChainGenesisStableKey = "__genesis__";
+type PlayerChainHeaderStableKey = "__header__";
+type PlayerChainGenesisNode = {
+    kind: "genesis";
+    stableKey: PlayerChainGenesisStableKey;
+    text: string;
+};
+type PlayerChainHeaderNode = {
+    kind: "header";
+    stableKey: PlayerChainHeaderStableKey;
+    sid: string;
+    bounds: AgentPlayWorldMapBounds;
+};
+type PlayerChainOccupantRemovedNode = {
+    kind: "occupant";
+    stableKey: string;
+    removed: true;
+};
+type PlayerChainOccupantPresentNode = {
+    kind: "occupant";
+    stableKey: string;
+    removed: false;
+    occupant: AgentPlayWorldMapHumanOccupant | AgentPlayWorldMapAgentOccupant | AgentPlayWorldMapMcpOccupant | AgentPlayWorldMapStructureOccupant;
+};
+type PlayerChainSpaceRemovedNode = {
+    kind: "space";
+    stableKey: string;
+    removed: true;
+};
+type PlayerChainSpacePresentNode = {
+    kind: "space";
+    stableKey: string;
+    removed: false;
+    space: AgentPlaySpaceCatalogEntry;
+};
+type PlayerChainNodeResponse = PlayerChainGenesisNode | PlayerChainHeaderNode | PlayerChainOccupantRemovedNode | PlayerChainOccupantPresentNode | PlayerChainSpaceRemovedNode | PlayerChainSpacePresentNode;
+/** Full journey + path update (SSE `world:journey`); coordinates are embedded in `path` steps. */
+type WorldJourneyUpdate = {
+    playerId: string;
+    journey: Journey;
+    path: PositionedStep[];
+};
+
+/**
+ * Axis-aligned rectangle in world coordinates (grid units). Used by the server to clamp paths
+ * and by the watch UI to clamp joystick-driven movement.
+ *
+ * @remarks **Consumers:** {@link clampWorldPosition}, {@link boundsContain}; server `PlayWorld` and
+ * play-ui canvas both import these helpers from `@agent-play/sdk`.
+ */
+type WorldBounds = {
+    /** Inclusive minimum X. */
+    minX: number;
+    /** Inclusive minimum Y. */
+    minY: number;
+    /** Inclusive maximum X. */
+    maxX: number;
+    /** Inclusive maximum Y. */
+    maxY: number;
+};
+/** Minimum playable span aligned with the watch canvas scrolling world (~20×20 cells). */
+declare const MINIMUM_PLAY_WORLD_BOUNDS: WorldBounds;
+/**
+ * Default bounds for {@link createVerticalStripSeedLayout} (street / zone map).
+ * Shorter on Y than {@link MINIMUM_PLAY_WORLD_BOUNDS}: three vertical strips across span X = 20, height 3.
+ */
+declare const MINIMUM_STREET_LAYOUT_BOUNDS: WorldBounds;
+declare function expandBoundsToMinimumPlayArea(bounds: WorldBounds): WorldBounds;
+/**
+ * Clamps a point to lie inside `bounds` along both axes.
+ *
+ * @param p - Position with `x` and `y` in world units.
+ * @param bounds - Valid rectangle (`min` ≤ `max` per axis).
+ * @returns Same point if inside, otherwise clamped to the nearest edge.
+ *
+ * @remarks **Callers:** server `PlayWorld` path enrichment; play-ui joystick and preview. **Callees:** `Math.min/Math.max`.
+ */
+declare function clampWorldPosition(p: {
+    x: number;
+    y: number;
+}, bounds: WorldBounds): {
+    x: number;
+    y: number;
+};
+/**
+ * @returns Whether `p` lies inside or on the border of `bounds`.
+ *
+ * @remarks **Callers:** optional UI checks. **Callees:** none.
+ */
+declare function boundsContain(bounds: WorldBounds, p: {
+    x: number;
+    y: number;
+}): boolean;
+
+type OccupancyGridPoint = {
+    x: number;
+    y: number;
+};
+declare const OCCUPANCY_POINT_MULTIPLIER = 5;
+declare const CONTINUOUS_RENDER_OFFSET = 0.2;
+declare const DEFAULT_AGENT_SPAWN_MIN_DISTANCE = 0.9;
+declare const SPACE_STRUCTURE_ANCHOR_MIN_DISTANCE = 2.1;
+/** @deprecated Prefer {@link WorldLayout} zones from snapshot; quartile geometry is legacy. */
+declare const SPATIAL_ZONE_INDEX_AGENTS = 0;
+/** @deprecated Prefer {@link WorldLayout} zones from snapshot; quartile geometry is legacy. */
+declare const SPATIAL_ZONE_INDEX_SPACES = 2;
+/** @deprecated Prefer layout zone rects; quartile geometry is legacy. */
+declare function spatialZoneBounds(quartileIndex: number): WorldBounds;
+/** @deprecated Prefer {@link centerOfZone} with a layout zone. */
+declare function spatialZoneCenter(quartileIndex: number): OccupancyGridPoint;
+declare function pointCellInRect(wx: number, wy: number, bounds: WorldBounds): boolean;
+declare function listOccupancyPointsInRect(bounds: WorldBounds): readonly OccupancyGridPoint[];
+declare function buildRankedOccupancyPointsInRect(bounds: WorldBounds): OccupancyGridPoint[];
+/** @deprecated Prefer {@link pointCellInZone} with a layout zone. */
+declare function pointCellInSpatialZone(wx: number, wy: number, zoneIndex: number): boolean;
+/** @deprecated Prefer {@link listOccupancyPointsForZone}. */
+declare function listOccupancyPointsForSpatialZone(zoneIndex: number): readonly OccupancyGridPoint[];
+/** @deprecated Prefer {@link occupancyPointsGroupedByZones}. */
+declare function occupancyPointsGroupedBySpatialZone(): readonly (readonly OccupancyGridPoint[])[];
+/** @deprecated Prefer points from the agent primary zone in {@link WorldLayout}. */
+declare function listAllowedOccupancyPoints(): readonly OccupancyGridPoint[];
+declare function occupancyKeyForPosition(x: number, y: number): string;
+/** @deprecated Prefer {@link buildRankedOccupancyPointsForZone}. */
+declare function buildRankedOccupancyPointsForSpatialZone(zoneIndex: number): OccupancyGridPoint[];
+/** Back-compat: agent-zone ranking only. */
+declare function buildRankedOccupancyPoints(): OccupancyGridPoint[];
+declare function boundingWorldRectForOccupancyPoints(points: readonly OccupancyGridPoint[]): {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+} | null;
+declare function isAgentSpawnOccupancyPointAvailableInRect(input: {
+    rect: WorldBounds;
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance?: number;
+}): boolean;
+declare function isSpaceAnchorOccupancyPointAvailableInRect(input: {
+    rect: WorldBounds;
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    structureAnchors: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance: number;
+    structureMinDistance: number;
+}): boolean;
+declare function isAgentSpawnOccupancyPointAvailable(input: {
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance?: number;
+}): boolean;
+declare function isSpaceAnchorOccupancyPointAvailable(input: {
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    structureAnchors: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance: number;
+    structureMinDistance: number;
+}): boolean;
+
+type StreetPoolEntry = {
+    id: string;
+    label: string;
+};
+declare const STREET_NAME_POOL: readonly StreetPoolEntry[];
+declare function getStreetPoolEntryById(id: string): StreetPoolEntry | undefined;
+
+type OccupantGroup = "agent" | "space" | "arcade";
+type Street = {
+    id: string;
+    label: string;
+};
+type Zone = {
+    id: string;
+    streetId: string;
+    streetLabel: string;
+    rect: WorldBounds;
+    primaryGroup: OccupantGroup;
+    allowedGroups: readonly OccupantGroup[];
+};
+type WorldLayout = {
+    rev: number;
+    bounds: WorldBounds;
+    zones: readonly Zone[];
+    streets: readonly Street[];
+};
+declare function streetFromPoolEntry(entry: StreetPoolEntry): Street;
+declare function zonesForGroup(layout: WorldLayout, group: OccupantGroup): readonly Zone[];
+declare function primaryZoneForGroup(layout: WorldLayout, group: OccupantGroup): Zone | undefined;
+declare function enumerateIntegerCellsInRect(rect: WorldBounds): OccupancyGridPoint[];
+declare function cellsForZone(zone: Zone): readonly OccupancyGridPoint[];
+declare function centerOfZone(zone: Zone): OccupancyGridPoint;
+declare function pointCellInZone(wx: number, wy: number, zone: Zone): boolean;
+declare function listOccupancyPointsForZone(zone: Zone): readonly OccupancyGridPoint[];
+declare function buildRankedOccupancyPointsForZone(zone: Zone): OccupancyGridPoint[];
+declare function occupancyPointsGroupedByZones(layout: WorldLayout): readonly (readonly OccupancyGridPoint[])[];
+declare function nextStreetFromPool(usedStreetIds: ReadonlySet<string>): StreetPoolEntry | undefined;
+declare function pickZoneForGroup(layout: WorldLayout, group: OccupantGroup): Zone;
+declare function availableCellsForZone(zone: Zone, occupiedCellKeys: ReadonlySet<string>): OccupancyGridPoint[];
+declare function isAgentSpawnOccupancyPointAvailableInZone(input: {
+    zone: Zone;
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance?: number;
+}): boolean;
+declare function isSpaceAnchorOccupancyPointAvailableInZone(input: {
+    zone: Zone;
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    structureAnchors: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance: number;
+    structureMinDistance: number;
+}): boolean;
+type WorldLayoutBoundsField = "minX" | "minY" | "maxX" | "maxY";
+declare function migrateWorldLayoutBounds(input: {
+    layout: WorldLayout;
+    bounds: WorldBounds;
+}): WorldLayout;
+declare function applyBoundsFieldUpdateToLayout(input: {
+    layout: WorldLayout;
+    field: WorldLayoutBoundsField;
+    value: number;
+}): WorldLayout;
+declare function createVerticalStripSeedLayout(input: {
+    bounds: WorldBounds;
+    streets: readonly [StreetPoolEntry, StreetPoolEntry, StreetPoolEntry];
+}): WorldLayout;
+
+/**
+ * @packageDocumentation
+ * @module @agent-play/sdk/space-content-model
+ *
+ * Zod schemas and helpers for the **server-authoritative content** a space owns
+ * inside each amenity kind, plus the **per-player wallet** that funds purchases.
+ *
+ * **Scope**
+ * - {@link SaleStateSchema}: shared sub-record describing whether an item is
+ *   still available for purchase or has already been sold (and to whom).
+ * - {@link ShopItemSchema}, {@link SupermarketItemSchema}, {@link CarWashCarSchema}:
+ *   the three amenity-content kinds. Each carries a `sale` block.
+ * - {@link PlayerWalletSchema} + {@link createInitialPlayerWallet}: every player
+ *   starts with **`$10`** ({@link DEFAULT_PLAYER_WALLET_BALANCE_USD}); the wallet
+ *   is seeded lazily on first read by the server.
+ * - {@link PurchaseRecordSchema}: append-only audit row stored per player.
+ * - {@link isItemAvailableForPurchase}: pure helper consumed by the `purchase`
+ *   RPC (server) and the item-tooltip / sprite renderers (client).
+ *
+ * @see ../../packages/web-ui/src/server/agent-play/session-store.ts for the
+ *      session-store interface that persists these records.
+ * @see ../../packages/web-ui/src/app/api/agent-play/sdk/rpc/route.ts for the
+ *      RPC handlers that write them.
+ */
+
+/**
+ * Sale state attached to every amenity content record.
+ *
+ * @remarks
+ * Records start as `{ status: "available" }`. The `purchase` RPC flips them
+ * to `{ status: "sold", soldToPlayerId, soldAt }` inside a `WATCH`/`MULTI`
+ * transaction so concurrent buyers cannot both succeed.
+ *
+ * @example
+ * ```ts
+ * SaleStateSchema.parse({ status: "available" });
+ * SaleStateSchema.parse({
+ *   status: "sold",
+ *   soldToPlayerId: "player-42",
+ *   soldAt: new Date().toISOString(),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const SaleStateSchema: z.ZodObject<{
+    status: z.ZodEnum<["available", "sold"]>;
+    soldToPlayerId: z.ZodOptional<z.ZodString>;
+    soldAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "available" | "sold";
+    soldToPlayerId?: string | undefined;
+    soldAt?: string | undefined;
+}, {
+    status: "available" | "sold";
+    soldToPlayerId?: string | undefined;
+    soldAt?: string | undefined;
+}>;
+/** Runtime type derived from {@link SaleStateSchema}. @public */
+type SaleState = z.infer<typeof SaleStateSchema>;
+/**
+ * Shop amenity item — books, music, coffee.
+ *
+ * @remarks
+ * Inserted by `addShopItem` AQL / RPC. Always starts with
+ * `sale.status === "available"`. Client renders this via
+ * `sprite-shop-item.ts` and the bookstore amenity stage.
+ *
+ * @example
+ * ```ts
+ * ShopItemSchema.parse({
+ *   id: "shop-1",
+ *   spaceId: "space-42",
+ *   type: "book",
+ *   name: "Hitchhiker's Guide",
+ *   description: "Don't panic.",
+ *   priceUsd: 12.5,
+ *   createdAt: new Date().toISOString(),
+ *   sale: { status: "available" },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const ShopItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    spaceId: z.ZodString;
+    type: z.ZodEnum<["book", "music", "coffee"]>;
+    name: z.ZodString;
+    description: z.ZodString;
+    priceUsd: z.ZodNumber;
+    createdAt: z.ZodString;
+    sale: z.ZodObject<{
+        status: z.ZodEnum<["available", "sold"]>;
+        soldToPlayerId: z.ZodOptional<z.ZodString>;
+        soldAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "book" | "music" | "coffee";
+    id: string;
+    spaceId: string;
+    name: string;
+    description: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+}, {
+    type: "book" | "music" | "coffee";
+    id: string;
+    spaceId: string;
+    name: string;
+    description: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+}>;
+/** Runtime type for {@link ShopItemSchema}. @public */
+type ShopItem = z.infer<typeof ShopItemSchema>;
+/**
+ * Supermarket amenity item — laid out on a 4×5 grid of slots.
+ *
+ * @remarks
+ * `row` selects the section (1=Fruits, 2=Mens, 3=Womens, 4=Kids in the
+ * client-side stage); `column` is 1..5. If the AQL caller omits `column` the
+ * server picks the next free slot in that row.
+ *
+ * @example
+ * ```ts
+ * SupermarketItemSchema.parse({
+ *   id: "sm-1",
+ *   spaceId: "space-42",
+ *   row: 1,
+ *   column: 3,
+ *   name: "Apple",
+ *   description: "fresh",
+ *   priceUsd: 1.25,
+ *   createdAt: new Date().toISOString(),
+ *   sale: { status: "available" },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const SupermarketItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    spaceId: z.ZodString;
+    row: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+    column: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>]>;
+    name: z.ZodString;
+    description: z.ZodString;
+    priceUsd: z.ZodNumber;
+    createdAt: z.ZodString;
+    sale: z.ZodObject<{
+        status: z.ZodEnum<["available", "sold"]>;
+        soldToPlayerId: z.ZodOptional<z.ZodString>;
+        soldAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    spaceId: string;
+    name: string;
+    description: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+    row: 1 | 2 | 3 | 4;
+    column: 1 | 2 | 5 | 3 | 4;
+}, {
+    id: string;
+    spaceId: string;
+    name: string;
+    description: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+    row: 1 | 2 | 3 | 4;
+    column: 1 | 2 | 5 | 3 | 4;
+}>;
+/** Runtime type for {@link SupermarketItemSchema}. @public */
+type SupermarketItem = z.infer<typeof SupermarketItemSchema>;
+/**
+ * Car-wash amenity car parked in one of nine slots.
+ *
+ * @remarks
+ * Client renders the car via `sprite-car.ts`, parameterised by `colorHex`.
+ * Sold cars flip to a desaturated palette plus a `SOLD` banner overlay.
+ *
+ * @example
+ * ```ts
+ * CarWashCarSchema.parse({
+ *   id: "car-1",
+ *   spaceId: "space-42",
+ *   slot: 5,
+ *   name: "Mustang",
+ *   model: "GT",
+ *   year: 2023,
+ *   priceUsd: 45000,
+ *   colorHex: "#ff3344",
+ *   createdAt: new Date().toISOString(),
+ *   sale: { status: "available" },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const CarWashCarSchema: z.ZodObject<{
+    id: z.ZodString;
+    spaceId: z.ZodString;
+    slot: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>, z.ZodLiteral<7>, z.ZodLiteral<8>, z.ZodLiteral<9>]>;
+    name: z.ZodString;
+    model: z.ZodString;
+    year: z.ZodNumber;
+    priceUsd: z.ZodNumber;
+    colorHex: z.ZodString;
+    createdAt: z.ZodString;
+    sale: z.ZodObject<{
+        status: z.ZodEnum<["available", "sold"]>;
+        soldToPlayerId: z.ZodOptional<z.ZodString>;
+        soldAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    spaceId: string;
+    name: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+    slot: 8 | 7 | 1 | 6 | 2 | 5 | 3 | 4 | 9;
+    model: string;
+    year: number;
+    colorHex: string;
+}, {
+    id: string;
+    spaceId: string;
+    name: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+    slot: 8 | 7 | 1 | 6 | 2 | 5 | 3 | 4 | 9;
+    model: string;
+    year: number;
+    colorHex: string;
+}>;
+/** Runtime type for {@link CarWashCarSchema}. @public */
+type CarWashCar = z.infer<typeof CarWashCarSchema>;
+/**
+ * Default starting balance, in USD, seeded into every new player wallet.
+ *
+ * @remarks
+ * The session store seeds the wallet lazily on first read via
+ * {@link createInitialPlayerWallet} inside an atomic `MULTI`, so two
+ * simultaneous first reads still leave the balance at exactly `$10`.
+ *
+ * @defaultValue 10
+ * @public
+ */
+declare const DEFAULT_PLAYER_WALLET_BALANCE_USD = 10;
+/**
+ * Per-player wallet.
+ *
+ * @remarks
+ * Stored at `agent-play:${hostId}:player:${playerId}:wallet`. Mutated atomically
+ * by the `purchase` RPC (decrement) and by the optional AQL `SET WALLET`
+ * statement.
+ *
+ * @public
+ */
+declare const PlayerWalletSchema: z.ZodObject<{
+    playerId: z.ZodString;
+    balanceUsd: z.ZodNumber;
+    currency: z.ZodLiteral<"USD">;
+    updatedAt: z.ZodString;
+    powerUps: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    playerId: string;
+    balanceUsd: number;
+    currency: "USD";
+    updatedAt: string;
+    powerUps: number;
+}, {
+    playerId: string;
+    balanceUsd: number;
+    currency: "USD";
+    updatedAt: string;
+    powerUps?: number | undefined;
+}>;
+/** Runtime type for {@link PlayerWalletSchema}. @public */
+type PlayerWallet = z.infer<typeof PlayerWalletSchema>;
+/**
+ * Build a fresh wallet seeded with the {@link DEFAULT_PLAYER_WALLET_BALANCE_USD}
+ * balance for an unseen player.
+ *
+ * @example
+ * ```ts
+ * const wallet = createInitialPlayerWallet({
+ *   playerId: "player-42",
+ *   now: new Date().toISOString(),
+ * });
+ * // → { playerId: "player-42", balanceUsd: 10, currency: "USD", updatedAt: ... }
+ * ```
+ *
+ * @public
+ */
+declare function createInitialPlayerWallet(input: {
+    playerId: string;
+    now: string;
+}): PlayerWallet;
+declare function createInitialAgentRewardWallet(input: {
+    playerId: string;
+    now: string;
+}): PlayerWallet;
+/**
+ * Audit record appended each time a player completes a purchase.
+ *
+ * @remarks
+ * Stored as a Redis list at `agent-play:${hostId}:player:${playerId}:purchases`
+ * with `LPUSH` so the newest entry is at index 0.
+ *
+ * @public
+ */
+declare const PurchaseRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    playerId: z.ZodString;
+    spaceId: z.ZodString;
+    amenityKind: z.ZodEnum<["shop", "supermarket", "car_wash", "talk_time", "wallet_bundle", "apu_credit", "apu_debit"]>;
+    itemRef: z.ZodObject<{
+        kind: z.ZodEnum<["shop", "supermarket", "carwash", "game", "apu", "talk", "bundle"]>;
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+    }, {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+    }>;
+    priceUsd: z.ZodOptional<z.ZodNumber>;
+    at: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    powerUpsSpent: z.ZodOptional<z.ZodNumber>;
+    powerUpsEarned: z.ZodOptional<z.ZodNumber>;
+    powerUpsDelta: z.ZodOptional<z.ZodNumber>;
+    debitSource: z.ZodOptional<z.ZodString>;
+    creditSource: z.ZodOptional<z.ZodString>;
+    counterpartyNodeId: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodLiteral<"APU">>;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    id: string;
+    spaceId: string;
+    playerId: string;
+    amenityKind: "supermarket" | "shop" | "car_wash" | "talk_time" | "wallet_bundle" | "apu_credit" | "apu_debit";
+    itemRef: {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+    };
+    priceUsd?: number | undefined;
+    detail?: string | undefined;
+    powerUpsSpent?: number | undefined;
+    powerUpsEarned?: number | undefined;
+    powerUpsDelta?: number | undefined;
+    debitSource?: string | undefined;
+    creditSource?: string | undefined;
+    counterpartyNodeId?: string | undefined;
+    token?: "APU" | undefined;
+}, {
+    at: string;
+    id: string;
+    spaceId: string;
+    playerId: string;
+    amenityKind: "supermarket" | "shop" | "car_wash" | "talk_time" | "wallet_bundle" | "apu_credit" | "apu_debit";
+    itemRef: {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+    };
+    priceUsd?: number | undefined;
+    detail?: string | undefined;
+    powerUpsSpent?: number | undefined;
+    powerUpsEarned?: number | undefined;
+    powerUpsDelta?: number | undefined;
+    debitSource?: string | undefined;
+    creditSource?: string | undefined;
+    counterpartyNodeId?: string | undefined;
+    token?: "APU" | undefined;
+}>;
+/** Runtime type for {@link PurchaseRecordSchema}. @public */
+type PurchaseRecord = z.infer<typeof PurchaseRecordSchema>;
+/**
+ * Returns whether an amenity content record can still be purchased.
+ *
+ * @remarks
+ * Server-side, the `purchase` RPC calls this **after** re-reading the item
+ * inside the `WATCH`/`MULTI` block to make the check atomic. Client-side, the
+ * tooltip and sprite renderers call it to decide between the `Buy` button and
+ * the disabled `SOLD` pill.
+ *
+ * @example
+ * ```ts
+ * if (!isItemAvailableForPurchase(item)) {
+ *   // render the sold view
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function isItemAvailableForPurchase(item: {
+    sale: SaleState;
+}): boolean;
+/**
+ * Union of all three content kinds, useful for places where the carrier
+ * doesn't need to know the specific amenity.
+ *
+ * @public
+ */
+type SpaceContentItem = ShopItem | SupermarketItem | CarWashCar;
+/**
+ * Convert any 24-bit RGB color to its perceptual grey equivalent using the
+ * standard luminance coefficients (`Y = 0.299·R + 0.587·G + 0.114·B`).
+ *
+ * @remarks
+ * Used by every amenity sprite (shop card, grocery item, car) when the
+ * item's `sale.status === 'sold'`. Replacing original fills with the
+ * desaturated grey is the first step of the sold visual treatment;
+ * `drawSoldBadge` then paints the red `SOLD` banner on top.
+ *
+ * The function is bit-pure: it accepts a `0xRRGGBB` integer and returns a
+ * `0xGGGGGG` integer, so it composes cleanly with `pixi.js` color params.
+ *
+ * @example
+ * ```ts
+ * const grey = desaturateColor(0xff3344);
+ * // grey = 0x6e6e6e (approximate)
+ * ```
+ *
+ * @public
+ */
+declare function desaturateColor(hex: number): number;
+
+/**
+ * Token name for redeemable power-up units (Agent Play Units).
+ *
+ * @public
+ */
+declare const APU_TOKEN: "APU";
+type ApuItemRef = PurchaseRecord["itemRef"];
+/**
+ * Build a wallet transaction row for an APU credit or debit.
+ *
+ * @public
+ */
+declare const buildApuWalletTransaction: (input: {
+    id: string;
+    playerId: string;
+    spaceId: string;
+    delta: number;
+    at: string;
+    creditSource?: string;
+    debitSource?: string;
+    counterpartyNodeId?: string;
+    detail?: string;
+    itemRef: ApuItemRef;
+}) => PurchaseRecord;
+/**
+ * APU fields appended to amenity purchase audit rows when USD is spent
+ * and power-ups are minted.
+ *
+ * @public
+ */
+declare const buildAmenityPurchaseApuFields: (input: {
+    amenityKind: "shop" | "supermarket" | "car_wash";
+    spaceId: string;
+    earnedPowerUps: number;
+}) => Pick<PurchaseRecord, "powerUpsEarned" | "powerUpsDelta" | "creditSource" | "debitSource" | "token">;
+/**
+ * APU fields for wallet bundle redemption rows.
+ *
+ * @public
+ */
+declare const buildWalletBundleApuFields: (input: {
+    bundleId: string;
+    powerUpsCost: number;
+}) => Pick<PurchaseRecord, "powerUpsSpent" | "powerUpsDelta" | "creditSource" | "debitSource" | "token">;
+
+declare const TALK_PRICE_PER_60S_USD = 1.5;
+declare const TALK_PRICE_PER_SECOND_USD = 0.025;
+declare const TALK_TICK_SECONDS = 10;
+declare const costForSeconds: (seconds: number) => number;
+
+declare const TALK_AGENT_PU_BILLED_SECONDS_PER_UNIT = 10;
+declare const TALK_AGENT_PU_MAX_PER_LEG = 5;
+type ComputeTalkAgentPowerUpsEarnedInput = {
+    billedWholeSeconds: number;
+    costUsd: number;
+};
+declare const computeTalkAgentPowerUpsEarned: (input: ComputeTalkAgentPowerUpsEarnedInput) => number;
+
+type WalletBundleId = "bundle-10" | "bundle-20" | "bundle-50" | "bundle-100";
+type WalletBundleOffer = {
+    readonly id: WalletBundleId;
+    readonly powerUpsCost: number;
+    readonly creditUsd: number;
+};
+declare const WALLET_BUNDLE_OFFERS: readonly WalletBundleOffer[];
+declare const getWalletBundleById: (id: string) => WalletBundleOffer | undefined;
+
+declare const DAILY_GAME_PU_CAP = 100;
+declare const STREAK_BONUS_PU = 5;
+declare const STREAK_BONUS_THRESHOLD_DAYS = 5;
+declare const GameEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"chest_open">;
+    correct: z.ZodBoolean;
+    tutorial: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "chest_open";
+    correct: boolean;
+    tutorial?: boolean | undefined;
+}, {
+    type: "chest_open";
+    correct: boolean;
+    tutorial?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"sequence_step">;
+    correct: z.ZodBoolean;
+    tutorial: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "sequence_step";
+    correct: boolean;
+    tutorial?: boolean | undefined;
+}, {
+    type: "sequence_step";
+    correct: boolean;
+    tutorial?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"price_guess">;
+    correct: z.ZodBoolean;
+    round: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "price_guess";
+    correct: boolean;
+    round: number;
+}, {
+    type: "price_guess";
+    correct: boolean;
+    round: number;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"signal_pick">;
+    correct: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    type: "signal_pick";
+    correct: boolean;
+}, {
+    type: "signal_pick";
+    correct: boolean;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"delivery_finish">;
+    band: z.ZodEnum<["fast", "ok", "slow"]>;
+    hits: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "delivery_finish";
+    band: "fast" | "ok" | "slow";
+    hits: number;
+}, {
+    type: "delivery_finish";
+    band: "fast" | "ok" | "slow";
+    hits: number;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"door_pick">;
+    correct: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    type: "door_pick";
+    correct: boolean;
+}, {
+    type: "door_pick";
+    correct: boolean;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"talk_release">;
+    success: z.ZodBoolean;
+    round: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "talk_release";
+    round: number;
+    success: boolean;
+}, {
+    type: "talk_release";
+    round: number;
+    success: boolean;
+}>]>;
+type GameEvent = z.infer<typeof GameEventSchema>;
+declare const ApplyGameOutcomeInputSchema: z.ZodObject<{
+    gameId: z.ZodEffects<z.ZodString, GameId, string>;
+    roundId: z.ZodString;
+    events: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"chest_open">;
+        correct: z.ZodBoolean;
+        tutorial: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        type: "chest_open";
+        correct: boolean;
+        tutorial?: boolean | undefined;
+    }, {
+        type: "chest_open";
+        correct: boolean;
+        tutorial?: boolean | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"sequence_step">;
+        correct: z.ZodBoolean;
+        tutorial: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        type: "sequence_step";
+        correct: boolean;
+        tutorial?: boolean | undefined;
+    }, {
+        type: "sequence_step";
+        correct: boolean;
+        tutorial?: boolean | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"price_guess">;
+        correct: z.ZodBoolean;
+        round: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "price_guess";
+        correct: boolean;
+        round: number;
+    }, {
+        type: "price_guess";
+        correct: boolean;
+        round: number;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"signal_pick">;
+        correct: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        type: "signal_pick";
+        correct: boolean;
+    }, {
+        type: "signal_pick";
+        correct: boolean;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"delivery_finish">;
+        band: z.ZodEnum<["fast", "ok", "slow"]>;
+        hits: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "delivery_finish";
+        band: "fast" | "ok" | "slow";
+        hits: number;
+    }, {
+        type: "delivery_finish";
+        band: "fast" | "ok" | "slow";
+        hits: number;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"door_pick">;
+        correct: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        type: "door_pick";
+        correct: boolean;
+    }, {
+        type: "door_pick";
+        correct: boolean;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"talk_release">;
+        success: z.ZodBoolean;
+        round: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "talk_release";
+        round: number;
+        success: boolean;
+    }, {
+        type: "talk_release";
+        round: number;
+        success: boolean;
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    gameId: GameId;
+    roundId: string;
+    events: ({
+        type: "chest_open";
+        correct: boolean;
+        tutorial?: boolean | undefined;
+    } | {
+        type: "sequence_step";
+        correct: boolean;
+        tutorial?: boolean | undefined;
+    } | {
+        type: "price_guess";
+        correct: boolean;
+        round: number;
+    } | {
+        type: "signal_pick";
+        correct: boolean;
+    } | {
+        type: "delivery_finish";
+        band: "fast" | "ok" | "slow";
+        hits: number;
+    } | {
+        type: "door_pick";
+        correct: boolean;
+    } | {
+        type: "talk_release";
+        round: number;
+        success: boolean;
+    })[];
+}, {
+    gameId: string;
+    roundId: string;
+    events: ({
+        type: "chest_open";
+        correct: boolean;
+        tutorial?: boolean | undefined;
+    } | {
+        type: "sequence_step";
+        correct: boolean;
+        tutorial?: boolean | undefined;
+    } | {
+        type: "price_guess";
+        correct: boolean;
+        round: number;
+    } | {
+        type: "signal_pick";
+        correct: boolean;
+    } | {
+        type: "delivery_finish";
+        band: "fast" | "ok" | "slow";
+        hits: number;
+    } | {
+        type: "door_pick";
+        correct: boolean;
+    } | {
+        type: "talk_release";
+        round: number;
+        success: boolean;
+    })[];
+}>;
+type ApplyGameOutcomeInput = z.infer<typeof ApplyGameOutcomeInputSchema>;
+declare const GamePerTitleStatsSchema: z.ZodObject<{
+    plays: z.ZodNumber;
+    bestNetPu: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    plays: number;
+    bestNetPu: number;
+}, {
+    plays: number;
+    bestNetPu: number;
+}>;
+type GamePerTitleStats = z.infer<typeof GamePerTitleStatsSchema>;
+declare const GameStatsSchema: z.ZodObject<{
+    dayStreak: z.ZodNumber;
+    bestStreak: z.ZodNumber;
+    puEarnedToday: z.ZodNumber;
+    puCapRemaining: z.ZodNumber;
+    gamesPlayedToday: z.ZodNumber;
+    featuredGameId: z.ZodString;
+    firstGamePlayed: z.ZodBoolean;
+    perGame: z.ZodRecord<z.ZodString, z.ZodObject<{
+        plays: z.ZodNumber;
+        bestNetPu: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        plays: number;
+        bestNetPu: number;
+    }, {
+        plays: number;
+        bestNetPu: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    dayStreak: number;
+    bestStreak: number;
+    puEarnedToday: number;
+    puCapRemaining: number;
+    gamesPlayedToday: number;
+    featuredGameId: string;
+    firstGamePlayed: boolean;
+    perGame: Record<string, {
+        plays: number;
+        bestNetPu: number;
+    }>;
+}, {
+    dayStreak: number;
+    bestStreak: number;
+    puEarnedToday: number;
+    puCapRemaining: number;
+    gamesPlayedToday: number;
+    featuredGameId: string;
+    firstGamePlayed: boolean;
+    perGame: Record<string, {
+        plays: number;
+        bestNetPu: number;
+    }>;
+}>;
+type GameStats = z.infer<typeof GameStatsSchema>;
+declare const computeEventPuDelta: (event: GameEvent) => number;
+declare const computeRoundPuDelta: (events: readonly GameEvent[]) => number;
+declare const utcDateKey: (date: Date) => string;
+declare const createEmptyGameStats: (date: Date) => GameStats;
+
+declare const ScannerTxOpSchema: z.ZodEnum<["purchase", "redeemWalletBundle", "applyGameOutcome", "talkTick", "talkStop", "talkStart", "walletSeeded"]>;
+type ScannerTxOp = z.infer<typeof ScannerTxOpSchema>;
+/**
+ * Explorer row for a wallet / APU transaction indexed globally.
+ *
+ * @public
+ */
+declare const ScannerTxRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    playerId: z.ZodString;
+    spaceId: z.ZodString;
+    amenityKind: z.ZodEnum<["shop", "supermarket", "car_wash", "talk_time", "wallet_bundle", "apu_credit", "apu_debit"]>;
+    itemRef: z.ZodObject<{
+        kind: z.ZodEnum<["shop", "supermarket", "carwash", "game", "apu", "talk", "bundle"]>;
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+    }, {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+    }>;
+    priceUsd: z.ZodOptional<z.ZodNumber>;
+    at: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    powerUpsSpent: z.ZodOptional<z.ZodNumber>;
+    powerUpsEarned: z.ZodOptional<z.ZodNumber>;
+    powerUpsDelta: z.ZodOptional<z.ZodNumber>;
+    debitSource: z.ZodOptional<z.ZodString>;
+    creditSource: z.ZodOptional<z.ZodString>;
+    counterpartyNodeId: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodLiteral<"APU">>;
+} & {
+    hostId: z.ZodString;
+    indexedAt: z.ZodString;
+    op: z.ZodEnum<["purchase", "redeemWalletBundle", "applyGameOutcome", "talkTick", "talkStop", "talkStart", "walletSeeded"]>;
+    blockRev: z.ZodOptional<z.ZodNumber>;
+    merkleRootHex: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    id: string;
+    spaceId: string;
+    playerId: string;
+    amenityKind: "supermarket" | "shop" | "car_wash" | "talk_time" | "wallet_bundle" | "apu_credit" | "apu_debit";
+    itemRef: {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+    };
+    hostId: string;
+    indexedAt: string;
+    op: "purchase" | "redeemWalletBundle" | "applyGameOutcome" | "talkTick" | "talkStop" | "talkStart" | "walletSeeded";
+    priceUsd?: number | undefined;
+    detail?: string | undefined;
+    powerUpsSpent?: number | undefined;
+    powerUpsEarned?: number | undefined;
+    powerUpsDelta?: number | undefined;
+    debitSource?: string | undefined;
+    creditSource?: string | undefined;
+    counterpartyNodeId?: string | undefined;
+    token?: "APU" | undefined;
+    blockRev?: number | undefined;
+    merkleRootHex?: string | undefined;
+}, {
+    at: string;
+    id: string;
+    spaceId: string;
+    playerId: string;
+    amenityKind: "supermarket" | "shop" | "car_wash" | "talk_time" | "wallet_bundle" | "apu_credit" | "apu_debit";
+    itemRef: {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+    };
+    hostId: string;
+    indexedAt: string;
+    op: "purchase" | "redeemWalletBundle" | "applyGameOutcome" | "talkTick" | "talkStop" | "talkStart" | "walletSeeded";
+    priceUsd?: number | undefined;
+    detail?: string | undefined;
+    powerUpsSpent?: number | undefined;
+    powerUpsEarned?: number | undefined;
+    powerUpsDelta?: number | undefined;
+    debitSource?: string | undefined;
+    creditSource?: string | undefined;
+    counterpartyNodeId?: string | undefined;
+    token?: "APU" | undefined;
+    blockRev?: number | undefined;
+    merkleRootHex?: string | undefined;
+}>;
+type ScannerTxRecord = z.infer<typeof ScannerTxRecordSchema>;
+/**
+ * Snapshot revision block indexed by the scanner.
+ *
+ * @public
+ */
+declare const ScannerBlockRecordSchema: z.ZodObject<{
+    rev: z.ZodNumber;
+    merkleRootHex: z.ZodString;
+    merkleLeafCount: z.ZodNumber;
+    at: z.ZodString;
+    occupantCount: z.ZodOptional<z.ZodNumber>;
+    leafDeltaCount: z.ZodOptional<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    merkleRootHex: string;
+    rev: number;
+    merkleLeafCount: number;
+    occupantCount?: number | undefined;
+    leafDeltaCount?: number | undefined;
+    label?: string | undefined;
+}, {
+    at: string;
+    merkleRootHex: string;
+    rev: number;
+    merkleLeafCount: number;
+    occupantCount?: number | undefined;
+    leafDeltaCount?: number | undefined;
+    label?: string | undefined;
+}>;
+type ScannerBlockRecord = z.infer<typeof ScannerBlockRecordSchema>;
+declare const ScannerMigrationStatusSchema: z.ZodEnum<["pending", "running", "completed", "failed"]>;
+type ScannerMigrationStatus = z.infer<typeof ScannerMigrationStatusSchema>;
+/**
+ * Backfill progress for scanner indexes.
+ *
+ * @public
+ */
+declare const ScannerMigrationStateSchema: z.ZodObject<{
+    status: z.ZodEnum<["pending", "running", "completed", "failed"]>;
+    cursor: z.ZodString;
+    totalIndexed: z.ZodNumber;
+    startedAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "running" | "completed" | "failed";
+    cursor: string;
+    totalIndexed: number;
+    startedAt: string;
+    completedAt?: string | undefined;
+    error?: string | undefined;
+}, {
+    status: "pending" | "running" | "completed" | "failed";
+    cursor: string;
+    totalIndexed: number;
+    startedAt: string;
+    completedAt?: string | undefined;
+    error?: string | undefined;
+}>;
+type ScannerMigrationState = z.infer<typeof ScannerMigrationStateSchema>;
+/**
+ * Cached wallet snapshot for scanner supply metrics.
+ *
+ * @public
+ */
+declare const ScannerWalletSnapshotSchema: z.ZodObject<{
+    playerId: z.ZodString;
+    balanceUsd: z.ZodNumber;
+    powerUps: z.ZodNumber;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    playerId: string;
+    balanceUsd: number;
+    updatedAt: string;
+    powerUps: number;
+}, {
+    playerId: string;
+    balanceUsd: number;
+    updatedAt: string;
+    powerUps: number;
+}>;
+type ScannerWalletSnapshot = z.infer<typeof ScannerWalletSnapshotSchema>;
+/**
+ * Chain head + KPI strip for the scanner dashboard.
+ *
+ * @public
+ */
+declare const ScannerHeadSchema: z.ZodObject<{
+    generatedAt: z.ZodString;
+    hostId: z.ZodString;
+    snapshotRev: z.ZodNumber;
+    merkleRootHex: z.ZodNullable<z.ZodString>;
+    merkleLeafCount: z.ZodNullable<z.ZodNumber>;
+    sid: z.ZodNullable<z.ZodString>;
+    txsLast24h: z.ZodNumber;
+    apuMintedLast24h: z.ZodNumber;
+    apuBurnedLast24h: z.ZodNumber;
+    migrationStatus: z.ZodEnum<["pending", "running", "completed", "failed"]>;
+}, "strip", z.ZodTypeAny, {
+    hostId: string;
+    merkleRootHex: string | null;
+    merkleLeafCount: number | null;
+    generatedAt: string;
+    snapshotRev: number;
+    sid: string | null;
+    txsLast24h: number;
+    apuMintedLast24h: number;
+    apuBurnedLast24h: number;
+    migrationStatus: "pending" | "running" | "completed" | "failed";
+}, {
+    hostId: string;
+    merkleRootHex: string | null;
+    merkleLeafCount: number | null;
+    generatedAt: string;
+    snapshotRev: number;
+    sid: string | null;
+    txsLast24h: number;
+    apuMintedLast24h: number;
+    apuBurnedLast24h: number;
+    migrationStatus: "pending" | "running" | "completed" | "failed";
+}>;
+type ScannerHead = z.infer<typeof ScannerHeadSchema>;
+declare const ScannerNodeProfileSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    kind: z.ZodEnum<["main", "agent", "unknown"]>;
+    generatedAt: z.ZodString;
+    wallet: z.ZodNullable<z.ZodObject<{
+        balanceUsd: z.ZodNumber;
+        powerUps: z.ZodNumber;
+        currency: z.ZodLiteral<"USD">;
+        updatedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        balanceUsd: number;
+        currency: "USD";
+        updatedAt: string;
+        powerUps: number;
+    }, {
+        balanceUsd: number;
+        currency: "USD";
+        updatedAt: string;
+        powerUps: number;
+    }>>;
+    ledger: z.ZodObject<{
+        txCount: z.ZodNumber;
+        usdSpent: z.ZodNumber;
+        apuMinted: z.ZodNumber;
+        apuBurned: z.ZodNumber;
+        lastTxAt: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        txCount: number;
+        usdSpent: number;
+        apuMinted: number;
+        apuBurned: number;
+        lastTxAt: string | null;
+    }, {
+        txCount: number;
+        usdSpent: number;
+        apuMinted: number;
+        apuBurned: number;
+        lastTxAt: string | null;
+    }>;
+    breakdown: z.ZodObject<{
+        byAmenityKind: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        bySpaceId: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        byToken: z.ZodObject<{
+            usd: z.ZodNumber;
+            apu: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            apu: number;
+            usd: number;
+        }, {
+            apu: number;
+            usd: number;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        byAmenityKind: Record<string, number>;
+        bySpaceId: Record<string, number>;
+        byToken: {
+            apu: number;
+            usd: number;
+        };
+    }, {
+        byAmenityKind: Record<string, number>;
+        bySpaceId: Record<string, number>;
+        byToken: {
+            apu: number;
+            usd: number;
+        };
+    }>;
+    txs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        playerId: z.ZodString;
+        spaceId: z.ZodString;
+        amenityKind: z.ZodEnum<["shop", "supermarket", "car_wash", "talk_time", "wallet_bundle", "apu_credit", "apu_debit"]>;
+        itemRef: z.ZodObject<{
+            kind: z.ZodEnum<["shop", "supermarket", "carwash", "game", "apu", "talk", "bundle"]>;
+            id: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+        }, {
+            id: string;
+            kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+        }>;
+        priceUsd: z.ZodOptional<z.ZodNumber>;
+        at: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        powerUpsSpent: z.ZodOptional<z.ZodNumber>;
+        powerUpsEarned: z.ZodOptional<z.ZodNumber>;
+        powerUpsDelta: z.ZodOptional<z.ZodNumber>;
+        debitSource: z.ZodOptional<z.ZodString>;
+        creditSource: z.ZodOptional<z.ZodString>;
+        counterpartyNodeId: z.ZodOptional<z.ZodString>;
+        token: z.ZodOptional<z.ZodLiteral<"APU">>;
+    } & {
+        hostId: z.ZodString;
+        indexedAt: z.ZodString;
+        op: z.ZodEnum<["purchase", "redeemWalletBundle", "applyGameOutcome", "talkTick", "talkStop", "talkStart", "walletSeeded"]>;
+        blockRev: z.ZodOptional<z.ZodNumber>;
+        merkleRootHex: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        id: string;
+        spaceId: string;
+        playerId: string;
+        amenityKind: "supermarket" | "shop" | "car_wash" | "talk_time" | "wallet_bundle" | "apu_credit" | "apu_debit";
+        itemRef: {
+            id: string;
+            kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+        };
+        hostId: string;
+        indexedAt: string;
+        op: "purchase" | "redeemWalletBundle" | "applyGameOutcome" | "talkTick" | "talkStop" | "talkStart" | "walletSeeded";
+        priceUsd?: number | undefined;
+        detail?: string | undefined;
+        powerUpsSpent?: number | undefined;
+        powerUpsEarned?: number | undefined;
+        powerUpsDelta?: number | undefined;
+        debitSource?: string | undefined;
+        creditSource?: string | undefined;
+        counterpartyNodeId?: string | undefined;
+        token?: "APU" | undefined;
+        blockRev?: number | undefined;
+        merkleRootHex?: string | undefined;
+    }, {
+        at: string;
+        id: string;
+        spaceId: string;
+        playerId: string;
+        amenityKind: "supermarket" | "shop" | "car_wash" | "talk_time" | "wallet_bundle" | "apu_credit" | "apu_debit";
+        itemRef: {
+            id: string;
+            kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+        };
+        hostId: string;
+        indexedAt: string;
+        op: "purchase" | "redeemWalletBundle" | "applyGameOutcome" | "talkTick" | "talkStop" | "talkStart" | "walletSeeded";
+        priceUsd?: number | undefined;
+        detail?: string | undefined;
+        powerUpsSpent?: number | undefined;
+        powerUpsEarned?: number | undefined;
+        powerUpsDelta?: number | undefined;
+        debitSource?: string | undefined;
+        creditSource?: string | undefined;
+        counterpartyNodeId?: string | undefined;
+        token?: "APU" | undefined;
+        blockRev?: number | undefined;
+        merkleRootHex?: string | undefined;
+    }>, "many">;
+    txsNextCursor: z.ZodNullable<z.ZodString>;
+    gameStats: z.ZodNullable<z.ZodObject<{
+        dayStreak: z.ZodNumber;
+        bestStreak: z.ZodNumber;
+        puEarnedToday: z.ZodNumber;
+        puCapRemaining: z.ZodNumber;
+        gamesPlayedToday: z.ZodNumber;
+        featuredGameId: z.ZodString;
+        firstGamePlayed: z.ZodBoolean;
+        perGame: z.ZodRecord<z.ZodString, z.ZodObject<{
+            plays: z.ZodNumber;
+            bestNetPu: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            plays: number;
+            bestNetPu: number;
+        }, {
+            plays: number;
+            bestNetPu: number;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        dayStreak: number;
+        bestStreak: number;
+        puEarnedToday: number;
+        puCapRemaining: number;
+        gamesPlayedToday: number;
+        featuredGameId: string;
+        firstGamePlayed: boolean;
+        perGame: Record<string, {
+            plays: number;
+            bestNetPu: number;
+        }>;
+    }, {
+        dayStreak: number;
+        bestStreak: number;
+        puEarnedToday: number;
+        puCapRemaining: number;
+        gamesPlayedToday: number;
+        featuredGameId: string;
+        firstGamePlayed: boolean;
+        perGame: Record<string, {
+            plays: number;
+            bestNetPu: number;
+        }>;
+    }>>;
+    analyticsEvents: z.ZodArray<z.ZodObject<{
+        messageId: z.ZodString;
+        event: z.ZodString;
+        distinctId: z.ZodString;
+        timestamp: z.ZodString;
+        properties: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, "strip", z.ZodTypeAny, {
+        event: string;
+        messageId: string;
+        distinctId: string;
+        timestamp: string;
+        properties: Record<string, string | number | boolean | null>;
+    }, {
+        event: string;
+        messageId: string;
+        distinctId: string;
+        timestamp: string;
+        properties: Record<string, string | number | boolean | null>;
+    }>, "many">;
+    analyticsEventsNextCursor: z.ZodNullable<z.ZodString>;
+    analytics: z.ZodObject<{
+        eventsLast24h: z.ZodNumber;
+        topEvents: z.ZodArray<z.ZodObject<{
+            event: z.ZodString;
+            count: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            event: string;
+            count: number;
+        }, {
+            event: string;
+            count: number;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        eventsLast24h: number;
+        topEvents: {
+            event: string;
+            count: number;
+        }[];
+    }, {
+        eventsLast24h: number;
+        topEvents: {
+            event: string;
+            count: number;
+        }[];
+    }>;
+    traits: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, "strip", z.ZodTypeAny, {
+    kind: "agent" | "unknown" | "main";
+    generatedAt: string;
+    nodeId: string;
+    wallet: {
+        balanceUsd: number;
+        currency: "USD";
+        updatedAt: string;
+        powerUps: number;
+    } | null;
+    ledger: {
+        txCount: number;
+        usdSpent: number;
+        apuMinted: number;
+        apuBurned: number;
+        lastTxAt: string | null;
+    };
+    breakdown: {
+        byAmenityKind: Record<string, number>;
+        bySpaceId: Record<string, number>;
+        byToken: {
+            apu: number;
+            usd: number;
+        };
+    };
+    txs: {
+        at: string;
+        id: string;
+        spaceId: string;
+        playerId: string;
+        amenityKind: "supermarket" | "shop" | "car_wash" | "talk_time" | "wallet_bundle" | "apu_credit" | "apu_debit";
+        itemRef: {
+            id: string;
+            kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+        };
+        hostId: string;
+        indexedAt: string;
+        op: "purchase" | "redeemWalletBundle" | "applyGameOutcome" | "talkTick" | "talkStop" | "talkStart" | "walletSeeded";
+        priceUsd?: number | undefined;
+        detail?: string | undefined;
+        powerUpsSpent?: number | undefined;
+        powerUpsEarned?: number | undefined;
+        powerUpsDelta?: number | undefined;
+        debitSource?: string | undefined;
+        creditSource?: string | undefined;
+        counterpartyNodeId?: string | undefined;
+        token?: "APU" | undefined;
+        blockRev?: number | undefined;
+        merkleRootHex?: string | undefined;
+    }[];
+    txsNextCursor: string | null;
+    gameStats: {
+        dayStreak: number;
+        bestStreak: number;
+        puEarnedToday: number;
+        puCapRemaining: number;
+        gamesPlayedToday: number;
+        featuredGameId: string;
+        firstGamePlayed: boolean;
+        perGame: Record<string, {
+            plays: number;
+            bestNetPu: number;
+        }>;
+    } | null;
+    analyticsEvents: {
+        event: string;
+        messageId: string;
+        distinctId: string;
+        timestamp: string;
+        properties: Record<string, string | number | boolean | null>;
+    }[];
+    analyticsEventsNextCursor: string | null;
+    analytics: {
+        eventsLast24h: number;
+        topEvents: {
+            event: string;
+            count: number;
+        }[];
+    };
+    traits: Record<string, string | number | boolean | null>;
+}, {
+    kind: "agent" | "unknown" | "main";
+    generatedAt: string;
+    nodeId: string;
+    wallet: {
+        balanceUsd: number;
+        currency: "USD";
+        updatedAt: string;
+        powerUps: number;
+    } | null;
+    ledger: {
+        txCount: number;
+        usdSpent: number;
+        apuMinted: number;
+        apuBurned: number;
+        lastTxAt: string | null;
+    };
+    breakdown: {
+        byAmenityKind: Record<string, number>;
+        bySpaceId: Record<string, number>;
+        byToken: {
+            apu: number;
+            usd: number;
+        };
+    };
+    txs: {
+        at: string;
+        id: string;
+        spaceId: string;
+        playerId: string;
+        amenityKind: "supermarket" | "shop" | "car_wash" | "talk_time" | "wallet_bundle" | "apu_credit" | "apu_debit";
+        itemRef: {
+            id: string;
+            kind: "supermarket" | "shop" | "carwash" | "game" | "apu" | "talk" | "bundle";
+        };
+        hostId: string;
+        indexedAt: string;
+        op: "purchase" | "redeemWalletBundle" | "applyGameOutcome" | "talkTick" | "talkStop" | "talkStart" | "walletSeeded";
+        priceUsd?: number | undefined;
+        detail?: string | undefined;
+        powerUpsSpent?: number | undefined;
+        powerUpsEarned?: number | undefined;
+        powerUpsDelta?: number | undefined;
+        debitSource?: string | undefined;
+        creditSource?: string | undefined;
+        counterpartyNodeId?: string | undefined;
+        token?: "APU" | undefined;
+        blockRev?: number | undefined;
+        merkleRootHex?: string | undefined;
+    }[];
+    txsNextCursor: string | null;
+    gameStats: {
+        dayStreak: number;
+        bestStreak: number;
+        puEarnedToday: number;
+        puCapRemaining: number;
+        gamesPlayedToday: number;
+        featuredGameId: string;
+        firstGamePlayed: boolean;
+        perGame: Record<string, {
+            plays: number;
+            bestNetPu: number;
+        }>;
+    } | null;
+    analyticsEvents: {
+        event: string;
+        messageId: string;
+        distinctId: string;
+        timestamp: string;
+        properties: Record<string, string | number | boolean | null>;
+    }[];
+    analyticsEventsNextCursor: string | null;
+    analytics: {
+        eventsLast24h: number;
+        topEvents: {
+            event: string;
+            count: number;
+        }[];
+    };
+    traits: Record<string, string | number | boolean | null>;
+}>;
+type ScannerNodeProfile = z.infer<typeof ScannerNodeProfileSchema>;
+
+declare const AnalyticsPropertyValueSchema: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+type AnalyticsPropertyValue = z.infer<typeof AnalyticsPropertyValueSchema>;
+declare const AnalyticsContextSchema: z.ZodObject<{
+    hostId: z.ZodString;
+    sid: z.ZodOptional<z.ZodString>;
+    snapshotRev: z.ZodOptional<z.ZodNumber>;
+    library: z.ZodEnum<["agent-play-server", "agent-play-client"]>;
+}, "strip", z.ZodTypeAny, {
+    hostId: string;
+    library: "agent-play-server" | "agent-play-client";
+    snapshotRev?: number | undefined;
+    sid?: string | undefined;
+}, {
+    hostId: string;
+    library: "agent-play-server" | "agent-play-client";
+    snapshotRev?: number | undefined;
+    sid?: string | undefined;
+}>;
+type AnalyticsContext = z.infer<typeof AnalyticsContextSchema>;
+/**
+ * Segment-style track envelope for in-platform analytics.
+ *
+ * @public
+ */
+declare const AnalyticsEventSchema: z.ZodObject<{
+    messageId: z.ZodString;
+    event: z.ZodString;
+    distinctId: z.ZodString;
+    timestamp: z.ZodString;
+    properties: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    context: z.ZodOptional<z.ZodObject<{
+        hostId: z.ZodString;
+        sid: z.ZodOptional<z.ZodString>;
+        snapshotRev: z.ZodOptional<z.ZodNumber>;
+        library: z.ZodEnum<["agent-play-server", "agent-play-client"]>;
+    }, "strip", z.ZodTypeAny, {
+        hostId: string;
+        library: "agent-play-server" | "agent-play-client";
+        snapshotRev?: number | undefined;
+        sid?: string | undefined;
+    }, {
+        hostId: string;
+        library: "agent-play-server" | "agent-play-client";
+        snapshotRev?: number | undefined;
+        sid?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    event: string;
+    messageId: string;
+    distinctId: string;
+    timestamp: string;
+    properties: Record<string, string | number | boolean | null>;
+    context?: {
+        hostId: string;
+        library: "agent-play-server" | "agent-play-client";
+        snapshotRev?: number | undefined;
+        sid?: string | undefined;
+    } | undefined;
+}, {
+    event: string;
+    messageId: string;
+    distinctId: string;
+    timestamp: string;
+    properties: Record<string, string | number | boolean | null>;
+    context?: {
+        hostId: string;
+        library: "agent-play-server" | "agent-play-client";
+        snapshotRev?: number | undefined;
+        sid?: string | undefined;
+    } | undefined;
+}>;
+type AnalyticsEvent = z.infer<typeof AnalyticsEventSchema>;
+/**
+ * Segment-style identify envelope for node traits.
+ *
+ * @public
+ */
+declare const AnalyticsTraitsSchema: z.ZodObject<{
+    distinctId: z.ZodString;
+    traits: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    distinctId: string;
+    timestamp: string;
+    traits: Record<string, string | number | boolean | null>;
+}, {
+    distinctId: string;
+    timestamp: string;
+    traits: Record<string, string | number | boolean | null>;
+}>;
+type AnalyticsTraits = z.infer<typeof AnalyticsTraitsSchema>;
+declare const AnalyticsMigrationStateSchema: z.ZodObject<{
+    status: z.ZodEnum<["pending", "running", "completed", "failed"]>;
+    cursor: z.ZodString;
+    totalIndexed: z.ZodNumber;
+    startedAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "running" | "completed" | "failed";
+    cursor: string;
+    totalIndexed: number;
+    startedAt: string;
+    completedAt?: string | undefined;
+    error?: string | undefined;
+}, {
+    status: "pending" | "running" | "completed" | "failed";
+    cursor: string;
+    totalIndexed: number;
+    startedAt: string;
+    completedAt?: string | undefined;
+    error?: string | undefined;
+}>;
+type AnalyticsMigrationState = z.infer<typeof AnalyticsMigrationStateSchema>;
+declare const ANALYTICS_EVENT_NAMES: {
+    readonly purchaseCompleted: "Purchase Completed";
+    readonly walletBundleRedeemed: "Wallet Bundle Redeemed";
+    readonly gameRoundCompleted: "Game Round Completed";
+    readonly talkSessionStarted: "Talk Session Started";
+    readonly talkSessionBilled: "Talk Session Billed";
+    readonly talkSessionEnded: "Talk Session Ended";
+    readonly walletSeeded: "Wallet Seeded";
+    readonly spaceEntered: "Space Entered";
+    readonly amenityEntered: "Amenity Entered";
+    readonly worldJourneyRecorded: "World Journey Recorded";
+    readonly worldInteractionRecorded: "World Interaction Recorded";
+    readonly playerAdded: "Player Added";
+    readonly chainRevisionPublished: "Chain Revision Published";
+    readonly uiPresentationAction: "UI Presentation Action";
+    readonly gameStageActivated: "Game Stage Activated";
+    readonly scannerViewOpened: "Scanner View Opened";
+};
+type AnalyticsEventName = (typeof ANALYTICS_EVENT_NAMES)[keyof typeof ANALYTICS_EVENT_NAMES];
+
+/**
+ * Parses **`playerChainNotify`** envelopes and merges {@link PlayerChainNodeResponse} slices into {@link AgentPlaySnapshot} (pure functions + fetch ordering for serialized RPC).
+ */
+
+declare function sortNodeRefsForSerializedFetch(nodes: ReadonlyArray<PlayerChainNotifyNodeRef>): PlayerChainNotifyNodeRef[];
+declare function parsePlayerChainFanoutNotify(raw: unknown): PlayerChainFanoutNotify | undefined;
+declare function parsePlayerChainFanoutNotifyFromSsePayload(sseData: unknown): PlayerChainFanoutNotify | undefined;
+declare function parsePlayerChainNodeRpcBody(json: unknown): PlayerChainNodeResponse;
+declare function mergeSnapshotWithPlayerChainNode(snapshot: AgentPlaySnapshot, node: PlayerChainNodeResponse): AgentPlaySnapshot;
+
+declare const PLAYER_CHAIN_GENESIS_STABLE_KEY: "__genesis__";
+declare const PLAYER_CHAIN_HEADER_STABLE_KEY: "__header__";
+
+export { MINIMUM_STREET_LAYOUT_BOUNDS as $, type AgentPlaySnapshot as A, type AssistToolParameterSpec as B, type AssistToolSpec as C, CONTINUOUS_RENDER_OFFSET as D, type CarWashCar as E, CarWashCarSchema as F, type ComputeTalkAgentPowerUpsEarnedInput as G, DAILY_GAME_PU_CAP as H, DEFAULT_AGENT_SPAWN_MIN_DISTANCE as I, type Journey as J, DEFAULT_PLAYER_WALLET_BALANCE_USD as K, type LangChainAgentRegistration as L, type DestinationJourneyStep as M, GAME_CABINET_CATALOG as N, type GameCabinetEntry as O, type PlayerChainNodeResponse as P, type GameEvent as Q, type RemotePlayWorldInitAudioOptions as R, GameEventSchema as S, type GameId as T, type GamePerTitleStats as U, GamePerTitleStatsSchema as V, type WorldInteractionRole as W, type GameStats as X, GameStatsSchema as Y, type JourneyStep as Z, MINIMUM_PLAY_WORLD_BOUNDS as _, type AddAgentInput as a, type WalletBundleOffer as a$, OCCUPANCY_POINT_MULTIPLIER as a0, type OccupancyGridPoint as a1, type OccupantGroup as a2, type OriginJourneyStep as a3, type P2aEnableFlag as a4, PLAYABLE_GAME_IDS as a5, PLAYER_CHAIN_GENESIS_STABLE_KEY as a6, PLAYER_CHAIN_HEADER_STABLE_KEY as a7, type PlatformAgentInformation as a8, type PlayAgentInformation as a9, type ScannerMigrationState as aA, ScannerMigrationStateSchema as aB, type ScannerMigrationStatus as aC, ScannerMigrationStatusSchema as aD, type ScannerNodeProfile as aE, ScannerNodeProfileSchema as aF, type ScannerTxOp as aG, ScannerTxOpSchema as aH, type ScannerTxRecord as aI, ScannerTxRecordSchema as aJ, type ScannerWalletSnapshot as aK, ScannerWalletSnapshotSchema as aL, type ShopItem as aM, ShopItemSchema as aN, type SpaceContentItem as aO, type Street as aP, type StreetPoolEntry as aQ, type StructureJourneyStep as aR, type SupermarketItem as aS, SupermarketItemSchema as aT, TALK_AGENT_PU_BILLED_SECONDS_PER_UNIT as aU, TALK_AGENT_PU_MAX_PER_LEG as aV, TALK_PRICE_PER_60S_USD as aW, TALK_PRICE_PER_SECOND_USD as aX, TALK_TICK_SECONDS as aY, WALLET_BUNDLE_OFFERS as aZ, type WalletBundleId as a_, type PlayerChainFanoutNotify as aa, type PlayerChainGenesisNode as ab, type PlayerChainHeaderNode as ac, type PlayerChainNotifyNodeRef as ad, type PlayerChainOccupantPresentNode as ae, type PlayerChainOccupantRemovedNode as af, type PlayerWallet as ag, PlayerWalletSchema as ah, type PositionedStep as ai, type PurchaseRecord as aj, PurchaseRecordSchema as ak, type RealtimeWebrtcClientSecret as al, type RegisteredAgentSummary as am, type RemotePlayWorldOpenAiAudioOptions as an, SPACE_STRUCTURE_ANCHOR_MIN_DISTANCE as ao, SPATIAL_ZONE_INDEX_AGENTS as ap, SPATIAL_ZONE_INDEX_SPACES as aq, STREAK_BONUS_PU as ar, STREAK_BONUS_THRESHOLD_DAYS as as, STREET_NAME_POOL as at, type SaleState as au, SaleStateSchema as av, type ScannerBlockRecord as aw, ScannerBlockRecordSchema as ax, type ScannerHead as ay, ScannerHeadSchema as az, type RegisteredPlayer as b, sortNodeRefsForSerializedFetch as b$, type WorldBounds as b0, type WorldJourneyUpdate as b1, type WorldLayout as b2, type WorldLayoutBoundsField as b3, type YieldEventInfo as b4, type Zone as b5, type ZoneEventInfo as b6, applyBoundsFieldUpdateToLayout as b7, availableCellsForZone as b8, boundingWorldRectForOccupancyPoints as b9, getWalletBundleById as bA, isAgentSpawnOccupancyPointAvailable as bB, isAgentSpawnOccupancyPointAvailableInRect as bC, isAgentSpawnOccupancyPointAvailableInZone as bD, isGameId as bE, isItemAvailableForPurchase as bF, isSpaceAnchorOccupancyPointAvailable as bG, isSpaceAnchorOccupancyPointAvailableInRect as bH, isSpaceAnchorOccupancyPointAvailableInZone as bI, listAllowedOccupancyPoints as bJ, listOccupancyPointsForSpatialZone as bK, listOccupancyPointsForZone as bL, listOccupancyPointsInRect as bM, mergeSnapshotWithPlayerChainNode as bN, migrateWorldLayoutBounds as bO, nextStreetFromPool as bP, occupancyKeyForPosition as bQ, occupancyPointsGroupedBySpatialZone as bR, occupancyPointsGroupedByZones as bS, parsePlayerChainFanoutNotify as bT, parsePlayerChainFanoutNotifyFromSsePayload as bU, parsePlayerChainNodeRpcBody as bV, pickZoneForGroup as bW, pointCellInRect as bX, pointCellInSpatialZone as bY, pointCellInZone as bZ, primaryZoneForGroup as b_, boundsContain as ba, buildAmenityPurchaseApuFields as bb, buildApuWalletTransaction as bc, buildRankedOccupancyPoints as bd, buildRankedOccupancyPointsForSpatialZone as be, buildRankedOccupancyPointsForZone as bf, buildRankedOccupancyPointsInRect as bg, buildWalletBundleApuFields as bh, cellsForZone as bi, centerOfZone as bj, clampWorldPosition as bk, computeEventPuDelta as bl, computeRoundPuDelta as bm, computeTalkAgentPowerUpsEarned as bn, costForSeconds as bo, createEmptyGameStats as bp, createInitialAgentRewardWallet as bq, createInitialPlayerWallet as br, createVerticalStripSeedLayout as bs, desaturateColor as bt, enumerateIntegerCellsInRect as bu, expandBoundsToMinimumPlayArea as bv, featuredGameIdForUtcDate as bw, getGameCabinetByGameId as bx, getGameCabinetById as by, getStreetPoolEntryById as bz, type AddPlayerInput as c, spatialZoneBounds as c0, spatialZoneCenter as c1, streetFromPoolEntry as c2, utcDateKey as c3, zonesForGroup as c4, type RecordInteractionInput as d, ANALYTICS_EVENT_NAMES as e, APU_TOKEN as f, type AgentPlayWorldLayout as g, type AgentPlayWorldLayoutZone as h, type AgentPlayWorldMap as i, type AgentPlayWorldMapAgentOccupant as j, type AgentPlayWorldMapBounds as k, type AgentPlayWorldMapMcpOccupant as l, type AnalyticsContext as m, AnalyticsContextSchema as n, type AnalyticsEvent as o, type AnalyticsEventName as p, AnalyticsEventSchema as q, type AnalyticsMigrationState as r, AnalyticsMigrationStateSchema as s, type AnalyticsPropertyValue as t, AnalyticsPropertyValueSchema as u, type AnalyticsTraits as v, AnalyticsTraitsSchema as w, type ApplyGameOutcomeInput as x, ApplyGameOutcomeInputSchema as y, type AssistToolFieldType as z };