{
 "openapi": "3.1.0",
 "info": {
  "title": "pDigger Factory API",
  "version": "2.1.0",
  "summary": "Interpreted stone work from a factory camera: events, stones and hands, as streams and as final draw lists.",
  "description": "The pDigger Factory API interprets stone work from a camera on the line: who handles which stone, when it is lifted,\ncarried, put down or pushed, and where every stone is, as a persistent 3-D world. It runs on a Jetson Orin NX next to\nthe camera and serves one **shared session** that every client follows.\n\n**Shipping default: the live camera.** The product ships with one live camera stream, selected by default and listed\nwith the recordings in `GET /api/v2/videos` (`kind: camera`, `live: true`). Parts marked *shipping* are not enabled on\nthe 20.20 test unit (build int17), where the session plays four recordings; everything else is the API that unit\nserves today. The demo server of this page answers from real 20.20 recordings, in your browser.\n\n**Three levels, one resource.** A grid frame `g` (5 per media second) has five layers; ask for any subset.\n\n| Level | Use it for | Where |\n|---|---|---|\n| High: Interpreter | events, stones, hands, a stone's path, the shared highlight | `world` layer, `/session/world*`, SDK `interpreter()` |\n| Mid: Streams and render-ready | live delivery; final 2-D/3-D draw lists | `/frames/stream`, `/frames`, `/render/*` |\n| Low: Frames and codec | the model's own packet, maps, rasters, tensors | `raw`, `overlay`, `scene`, `cards` layers, `/raw/*`, `/frames/{g}` |\n\n**Async first.** Follow the session with `GET /api/v2/session/frames/stream` (server-sent events): each `frame`\nevent's id is `<boot>-<cursor>`; reconnect with `Last-Event-ID` and nothing is lost inside the retained window (512\nframes, about 100 s); `limit` and `max_s` end a stream and clients reconnect (the unit closes a finished stream about\n10 s later: count them yourself and close it, as the SDKs do); `gap` tells a slow consumer how many items it lost;\n`reset` means the server restarted. `clock` events carry the shared state (`media_time`, `rate`, `playing`, `session`), `worker`\nevents the interpreter's status. The worker reads up to 0.6 s of media ahead of the shared playhead, and frames arrive\n0.2 to 0.35 s of media ahead of it (on the 20.20 unit). A frame is released at most 300 ms after its packet; a layer not ready by then is listed in `missing` and is\nnever pushed again (read it with `GET /frames/{g}`); the SDKs do that for you. While the session is paused, the\npaused frame's world is refined and released again with a higher `world.rev`.\n\n**SDKs** (same features, same output): Go `pdigger-factory-sdk-go`, Python `pdigger-factory-sdk`, Rust\n`pdigger-factory-sdk`, TypeScript `pdigger-factory-sdk`. Each operation below names its method.\n\n**Coordinates.** Native px: pixels of the model crop, centres at integers (`px = u·W − 0.5`). Content units `u, v` in\n[0, 1]. Scene world: z up, board top at z = 0, template gauge (not metric). three.js: `(x, y, z) → (x, z, −y)`.\n\n**Errors.** `{\"error\": \"<message>\", \"code\": \"<stable code>\", \"retry_ms\"?, \"field\"?, \"retained\"?}`; key on `code`. Rate\nlimits are checked before anything is applied, so a 429 is always safe to retry after `retry_ms`.\n\n**Access.** Today the API is LAN-only, without authentication or CORS, and controls must be same-origin. The SDKs can\nsend a bearer token for deployments that require one.\n\n**Demo data.** The demo answers from public recordings: face keypoints, appearance masks and depth textures are\nremoved from them, so those fields are absent there; the unit on the LAN sends them.\n",
  "contact": {
   "name": "eprojac",
   "url": "https://factory.pdigger.com/"
  },
  "license": {
   "name": "Proprietary",
   "identifier": "LicenseRef-Proprietary"
  },
  "x-served-by": {
   "unit": "20.20 (Jetson Orin NX)",
   "build": "claude-20261114-int17",
   "api": "2.0.0",
   "source": "interp-api/openapi/openapi.yaml"
  }
 },
 "servers": [
  {
   "url": "/developers/api/demo",
   "description": "Demo: real 20.20 recordings, answered in your browser (nothing is sent anywhere)"
  },
  {
   "url": "{scheme}://{host}:{port}",
   "description": "Your unit on the factory LAN",
   "variables": {
    "scheme": {
     "default": "http",
     "enum": [
      "http",
      "https"
     ]
    },
    "host": {
     "default": "factory-orin.local"
    },
    "port": {
     "default": "8120"
    }
   }
  }
 ],
 "tags": [
  {
   "name": "Interpreter",
   "x-level": "high",
   "description": "What happened, in the words of the interpreter: the persistent world of stones and hands, its event log (lift, carry, place, push, new, delete, split, ...), a stone's path, and the stone highlighted for everyone. The SDKs turn these into typed events, activities (a move from lift to put-down, a burst of pushes) and plain sentences such as `21:17.8 Right hand lifts stone 2534`."
  },
  {
   "name": "Sources",
   "x-level": "high",
   "description": "What the shared session can show: the live camera (shipping: one camera, selected by default) and the recordings. The proxy video of a source, with byte ranges (the live camera: a live fragmented MP4)."
  },
  {
   "name": "Session",
   "x-level": "high",
   "description": "The one shared session. Every viewer follows it; `select` and `seek` start a new interpretation run for everyone. Every control takes `dry_run=1` to validate without moving anything."
  },
  {
   "name": "Streams",
   "x-level": "mid",
   "description": "Async delivery. `frames/stream` pushes frames as server-sent events (or NDJSON) with resume by `Last-Event-ID`; `frames` is the long-poll for clients that cannot stream; `raw/stream` is the model codec. A stream counts as a viewer and keeps the interpreter running unless `observe=1`."
  },
  {
   "name": "Render-ready",
   "x-level": "mid",
   "description": "Final 2-D and 3-D draw lists at any retained time: no interpolation, no joints to resolve, styles resolved with `draw=primitives`."
  },
  {
   "name": "Frames and codec",
   "x-level": "low",
   "description": "Random access to retained frames and their layers, the raw model packet (`sip1`), map rasters and debug tensors. Maps are base64 of u8 row-major (sip1: of zlib), bitsets LSB-first; the SDK codecs decode them."
  },
  {
   "name": "Meta",
   "x-level": "meta",
   "description": "Entry point, this document, the running model and the skeleton topology."
  },
  {
   "name": "Ops",
   "x-level": "ops",
   "description": "Liveness, readiness, status and Prometheus metrics."
  }
 ],
 "paths": {
  "/api/v2/session/world": {
   "get": {
    "operationId": "getWorld",
    "tags": [
     "Interpreter"
    ],
    "summary": "The newest world.",
    "description": "The world of the newest retained frame that has one, at its newest revision (`rev`).\n\n**SDK** · Go `c.API().GetWorld(ctx, …)` · Python `await factory.api.get_world(…)` · Rust `factory.api().get_world(…).await` · TypeScript `await factory.api.getWorld(…)`",
    "parameters": [
     {
      "$ref": "#/components/parameters/Precision"
     }
    ],
    "responses": {
     "200": {
      "description": "The world of the newest frame that has one.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/WorldLayer"
        },
        "examples": {
         "ok_newest": {
          "summary": "Stones, hands, events and stats",
          "value": {
           "schema": "stw1",
           "session": 1794353523,
           "video": "aug28",
           "g": 6389,
           "t": 1277.8,
           "motion": "static",
           "logF": -0.08459,
           "stones": [
            {
             "id": 72,
             "mode": "carry",
             "family": "dogbone",
             "shape": "model",
             "detected": false,
             "uncertain": false,
             "side": "right",
             "outline": [
              [
               372.05,
               474.42
              ],
              [
               372.11,
               497.61
              ],
              [
               362.88,
               511.3
              ]
             ],
             "solid": {
              "pos": [
               -1.2055,
               -0.2421,
               0.2159
              ],
              "q": [
               -0.40383,
               0.40732,
               -0.58172,
               0.57673
              ],
              "dims": [
               0.3084,
               0.235,
               0.093
              ]
             }
            },
            {
             "id": 39,
             "mode": "kept",
             "family": "dogbone",
             "shape": "model",
             "detected": false,
             "uncertain": true,
             "side": null,
             "outline": [
              [
               217.48,
               248.44
              ],
              [
               217.58,
               270.08
              ],
              [
               208.88,
               281.77
              ]
             ],
             "solid": {
              "pos": [
               -1.6785,
               0.334,
               0.0465
              ],
              "q": [
               0,
               0,
               -0.71353,
               0.70062
              ],
              "dims": [
               0.297,
               0.2192,
               0.093
              ]
             }
            }
           ],
           "hands": {
            "left": {
             "state": "touch",
             "stone": null,
             "rayK": 0.998055
            },
            "right": {
             "state": "carry",
             "stone": 72,
             "rayK": 0.983232
            }
           },
           "events": [
            {
             "type": "lift",
             "id": 72,
             "side": "right"
            },
            {
             "type": "carry",
             "id": 72,
             "side": "right"
            },
            {
             "type": "push",
             "id": 63,
             "side": "left"
            }
           ],
           "stats": {
            "stones": 33,
            "confirmed": 33,
            "frozen": 0,
            "fitted": 3,
            "held": 1,
            "stepMs": 4.2
           },
           "draw": {
            "board": {
             "cx": -1.1755,
             "cy": -0.4326,
             "theta": 1.4556,
             "hw": 0.9168,
             "hh": 0.6683
            },
            "skeleton": {
             "logF": -0.084593,
             "k": {
              "left": 0.998055,
              "right": 0.983232
             },
             "elbow": {
              "left": [
               0.00153,
               -0.0016,
               -0.00223
              ],
              "right": [
               0.02213,
               -0.02741,
               0.00364
              ]
             }
            }
           },
           "focus": {
            "id": 72,
            "path2d": [
             [
              335.1,
              540.2
             ]
            ],
            "path3d": [
             [
              -1.21,
              -0.24,
              0.26
             ]
            ]
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_precision": {
          "summary": "rounded or full",
          "value": {
           "error": "precision must be rounded or full",
           "code": "invalid_param",
           "field": "precision"
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "No world yet.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_world_off": {
          "summary": "Stable sim off or restarting",
          "value": {
           "error": "the Stable sim is not running",
           "code": "world_unavailable",
           "retry_ms": 1000
          }
         }
        }
       }
      }
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().GetWorld(ctx, …)",
     "python": "await factory.api.get_world(…)",
     "rust": "factory.api().get_world(…).await",
     "typescript": "await factory.api.getWorld(…)"
    }
   }
  },
  "/api/v2/session/world/events": {
   "get": {
    "operationId": "getWorldEvents",
    "tags": [
     "Interpreter"
    ],
    "summary": "The event log of this session (lift, carry, place, push, new, delete, split, ...).",
    "description": "A frame's events are those of its newest world revision; a revised frame's events replace its earlier ones and are never listed twice. So a reader that follows `next_after` past a frame that is revised later (a paused frame and the few after it, fixer thin-v1) does not see the events the revision adds: after a revision of frame g (the world long-poll, or `stable.hold`), read again from `after` = g - 1, or take the events from the world layer itself.\n\n**SDK** · Go `c.API().GetWorldEvents(ctx, …)` · Python `await factory.api.get_world_events(…)` · Rust `factory.api().get_world_events(…).await` · TypeScript `await factory.api.getWorldEvents(…)`\n\n**High level** · Python `async for ev in factory.interpreter().events()` · TypeScript `for await (const ev of factory.interpreter().events())`",
    "parameters": [
     {
      "name": "after",
      "in": "query",
      "description": "Only events with a larger `g`.",
      "schema": {
       "type": "integer",
       "minimum": -1,
       "default": -1
      },
      "examples": {
       "ok_after": {
        "value": 6380,
        "summary": "Since g 6380"
       },
       "bad_after": {
        "value": "abc",
        "summary": "Not an integer"
       }
      }
     },
     {
      "name": "limit",
      "in": "query",
      "description": "At most this many events, by whole frames: the events of one frame are never split, so a frame that alone has more comes whole, and a next request with `after` = `next_after` loses nothing while those frames are retained (see `oldest_g`).",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 1024,
       "default": 256
      },
      "examples": {
       "ok_limit": {
        "value": 100,
        "summary": "At most 100"
       },
       "bad_limit": {
        "value": 0,
        "summary": "Below 1"
       }
      }
     },
     {
      "name": "type",
      "in": "query",
      "description": "Comma-separated event types.",
      "schema": {
       "type": "string"
      },
      "examples": {
       "ok_lifts": {
        "value": "lift,place",
        "summary": "Only lifts and put-downs"
       },
       "ok_splits": {
        "value": "split,new",
        "summary": "Splits and new stones"
       },
       "bad_type": {
        "value": "nonsense",
        "summary": "Not an event type"
       }
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Events, oldest first.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EventLog"
        },
        "examples": {
         "ok_lifts": {
          "summary": "Lifts and put-downs",
          "value": {
           "session": 1794353523,
           "video": "aug28",
           "events": [
            {
             "g": 6389,
             "t": 1277.8,
             "type": "lift",
             "id": 72,
             "side": "right"
            },
            {
             "g": 6409,
             "t": 1281.8,
             "type": "place",
             "id": 72,
             "side": "right",
             "why": "slot-t-release"
            }
           ],
           "next_after": 6409,
           "oldest_g": 6386
          }
         },
         "ok_one_frame": {
          "summary": "One whole frame, though it has more events than limit",
          "description": "With `limit=1` every reply is one frame's events, however many there are: here the first frame of the world at the carry, where its stones are new. Follow `next_after` to read the log frame by frame.",
          "value": {
           "session": 1794353523,
           "video": "aug28",
           "events": [
            {
             "g": 6386,
             "t": 1277.2,
             "type": "new",
             "id": 1
            },
            {
             "g": 6386,
             "t": 1277.2,
             "type": "new",
             "id": 2
            },
            {
             "g": 6386,
             "t": 1277.2,
             "type": "new",
             "id": 3
            }
           ],
           "next_after": 6386,
           "oldest_g": 6386
          }
         },
         "ok_fills": {
          "summary": "Stones the model never boxed, and splits",
          "description": "Fixer thin-v1, paused on dry2 at 9:49: rest refinement of the paused frame added two stones the model never boxed, each a `new` with `source: image`. A split (none here) keeps the old id on the larger part and names the new part in `into`. A revision replaces its frame's events in this log, which lists them once: a reader that had passed the frame reads it again from `after` = g - 1 (or takes the events from the world long-poll).",
          "value": {
           "session": 1794446896,
           "video": "dry2",
           "events": [
            {
             "g": 2953,
             "t": 588.956667,
             "type": "new",
             "id": 41,
             "source": "image"
            },
            {
             "g": 2953,
             "t": 588.956667,
             "type": "new",
             "id": 42,
             "source": "image"
            }
           ],
           "next_after": 2956,
           "oldest_g": 2950
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_after": {
          "summary": "after is an integer",
          "value": {
           "error": "after must be an integer",
           "code": "invalid_param",
           "field": "after"
          }
         },
         "bad_type": {
          "summary": "Not an event type",
          "value": {
           "error": "unknown event type 'nonsense'",
           "code": "invalid_param",
           "field": "type"
          }
         },
         "bad_type_plural": {
          "summary": "Event types are singular",
          "value": {
           "error": "unknown event type 'splits'",
           "code": "invalid_param",
           "field": "type"
          }
         },
         "bad_limit": {
          "summary": "limit is 1..1024",
          "value": {
           "error": "limit must be within 1..1024",
           "code": "invalid_param",
           "field": "limit"
          }
         }
        }
       }
      }
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().GetWorldEvents(ctx, …)",
     "python": "await factory.api.get_world_events(…)",
     "rust": "factory.api().get_world_events(…).await",
     "typescript": "await factory.api.getWorldEvents(…)",
     "high": {
      "go": "for ev, err := range c.Interpreter().Events(ctx)",
      "python": "async for ev in factory.interpreter().events()",
      "rust": "factory.interpreter().events().await?",
      "typescript": "for await (const ev of factory.interpreter().events())"
     }
    }
   }
  },
  "/api/v2/session/world/stones/{id}": {
   "get": {
    "operationId": "getStone",
    "tags": [
     "Interpreter"
    ],
    "summary": "One stone, with its path since the session began.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "The world's stone id.",
      "schema": {
       "type": "integer",
       "minimum": 0
      },
      "examples": {
       "ok_carried": {
        "value": 72,
        "summary": "The carried stone"
       },
       "bad_float": {
        "value": "7.5",
        "summary": "Not an integer"
       },
       "bad_unknown": {
        "value": 999999,
        "summary": "Not in the world"
       }
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The track.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/StoneTrack"
        },
        "examples": {
         "ok_carried": {
          "summary": "Where stone 72 has been",
          "value": {
           "schema": "sts1",
           "session": 1794353523,
           "video": "aug28",
           "id": 72,
           "g": 6389,
           "t": 1277.8,
           "stone": {
            "id": 72,
            "mode": "carry",
            "family": "dogbone",
            "shape": "model",
            "detected": false,
            "uncertain": false,
            "side": "right",
            "outline": [
             [
              372.05,
              474.42
             ]
            ],
            "solid": {
             "pos": [
              -1.2055,
              -0.2421,
              0.2159
             ],
             "q": [
              -0.40383,
              0.40732,
              -0.58172,
              0.57673
             ],
             "dims": [
              0.3084,
              0.235,
              0.093
             ]
            }
           },
           "first_g": 6368,
           "last_g": 6389,
           "path2d": [
            [
             335.1,
             540.2
            ]
           ],
           "path3d": [
            [
             -1.21,
             -0.24,
             0.26
            ]
           ]
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_float": {
          "summary": "id is an integer",
          "value": {
           "error": "id must be an integer",
           "code": "invalid_param",
           "field": "id"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not in this session's world.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_unknown": {
          "summary": "Not in the world",
          "value": {
           "error": "no stone 999999 in the world",
           "code": "unknown_stone",
           "field": "id"
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "The Stable sim is not running.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_world_off": {
          "summary": "Stable sim off or restarting",
          "value": {
           "error": "the Stable sim is not running",
           "code": "world_unavailable",
           "retry_ms": 1000
          }
         }
        }
       }
      }
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().GetStone(ctx, …)",
     "python": "await factory.api.get_stone(…)",
     "rust": "factory.api().get_stone(…).await",
     "typescript": "await factory.api.getStone(…)"
    },
    "description": "One stone, with its path since the session began.\n\n**SDK** · Go `c.API().GetStone(ctx, …)` · Python `await factory.api.get_stone(…)` · Rust `factory.api().get_stone(…).await` · TypeScript `await factory.api.getStone(…)`"
   }
  },
  "/api/v2/session/focus": {
   "get": {
    "operationId": "getFocus",
    "tags": [
     "Interpreter"
    ],
    "summary": "The stone highlighted for every viewer, and its path.",
    "responses": {
     "200": {
      "description": "The focus, or nulls.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/FocusReply"
        },
        "examples": {
         "ok_none": {
          "summary": "Nothing highlighted",
          "value": {
           "focus": null,
           "resolved": null
          }
         },
         "ok_carried": {
          "summary": "A carried stone, with its path",
          "value": {
           "focus": {
            "n": 421,
            "session": 1794353523,
            "video": "aug28",
            "id": 72,
            "g": 6389,
            "t": 1277.8,
            "x": -1.2055,
            "y": -0.2421,
            "z": 0.2159,
            "L": 0.3084,
            "W": 0.235,
            "yaw": -1.5602
           },
           "resolved": {
            "id": 72,
            "path2d": [
             [
              335.1,
              540.2
             ]
            ],
            "path3d": [
             [
              -1.21,
              -0.24,
              0.26
             ]
            ]
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().GetFocus(ctx, …)",
     "python": "await factory.api.get_focus(…)",
     "rust": "factory.api().get_focus(…).await",
     "typescript": "await factory.api.getFocus(…)"
    },
    "description": "The stone highlighted for every viewer, and its path.\n\n**SDK** · Go `c.API().GetFocus(ctx, …)` · Python `await factory.api.get_focus(…)` · Rust `factory.api().get_focus(…).await` · TypeScript `await factory.api.getFocus(…)`"
   },
   "put": {
    "operationId": "putFocus",
    "tags": [
     "Interpreter"
    ],
    "summary": "Highlight a stone of the world for every viewer.",
    "x-mutates-session": true,
    "parameters": [
     {
      "$ref": "#/components/parameters/DryRun"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/FocusRequest"
       },
       "examples": {
        "ok_carried_stone": {
         "summary": "The stone being carried",
         "value": {
          "stone_id": 72
         }
        },
        "ok_pinned": {
         "summary": "As drawn at g 6389 of this session",
         "value": {
          "stone_id": 72,
          "g": 6389,
          "session": 1794353523
         }
        },
        "bad_unknown_stone": {
         "summary": "Not in the world",
         "value": {
          "stone_id": 999999
         }
        },
        "bad_float_id": {
         "summary": "An id is an integer",
         "value": {
          "stone_id": 7.5
         }
        },
        "bad_old_session": {
         "summary": "Clicked just before a seek",
         "value": {
          "stone_id": 72,
          "session": 1794353000
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The focus is set (or, with dry_run, validated).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ControlReply"
        },
        "examples": {
         "ok_carried_stone": {
          "summary": "The highlight is shared",
          "value": {
           "state": {
            "session": 1794353523,
            "revision": 421,
            "video": "aug28",
            "playing": false,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353610.1,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": {
             "n": 421,
             "session": 1794353523,
             "video": "aug28",
             "id": 72,
             "g": 6389,
             "t": 1277.8,
             "x": -1.2055,
             "y": -0.2421,
             "z": 0.2159,
             "L": 0.3084,
             "W": 0.235,
             "yaw": -1.5602
            },
            "media_time": 1277.8
           },
           "server_now": 1794353620.4,
           "server_recv": 1794353620.399,
           "dry_run": true
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad body.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_float_id": {
          "summary": "An id is an integer",
          "value": {
           "error": "stone_id must be an integer within 0..1000000000",
           "code": "invalid_type",
           "field": "stone_id"
          }
         },
         "bad_no_id": {
          "summary": "stone_id is required",
          "value": {
           "error": "stone_id must be an integer within 0..1000000000",
           "code": "missing_field",
           "field": "stone_id"
          }
         },
         "bad_malformed_json": {
          "$ref": "#/components/examples/bad_malformed_json"
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/ForeignOrigin"
     },
     "404": {
      "description": "The stone is not in the world.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_unknown_stone": {
          "summary": "Not in the world",
          "value": {
           "error": "no stone 999999 in the world",
           "code": "unknown_stone",
           "field": "stone_id"
          }
         }
        }
       }
      }
     },
     "409": {
      "description": "The focus was made for another session.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_old_session": {
          "summary": "Clicked just before a seek",
          "value": {
           "error": "that stone belongs to an earlier session",
           "code": "stale_session",
           "field": "session"
          }
         }
        }
       }
      }
     },
     "413": {
      "$ref": "#/components/responses/TooLarge"
     },
     "415": {
      "$ref": "#/components/responses/NotJson"
     },
     "429": {
      "$ref": "#/components/responses/TooSoonFocus"
     },
     "503": {
      "description": "The Stable sim is not running.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_world_off": {
          "summary": "Stable sim off or restarting",
          "value": {
           "error": "the Stable sim is not running",
           "code": "world_unavailable",
           "retry_ms": 1000
          }
         }
        }
       }
      }
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().PutFocus(ctx, …)",
     "python": "await factory.api.put_focus(…)",
     "rust": "factory.api().put_focus(…).await",
     "typescript": "await factory.api.putFocus(…)"
    },
    "description": "Highlight a stone of the world for every viewer.\n\n**SDK** · Go `c.API().PutFocus(ctx, …)` · Python `await factory.api.put_focus(…)` · Rust `factory.api().put_focus(…).await` · TypeScript `await factory.api.putFocus(…)`"
   },
   "delete": {
    "operationId": "deleteFocus",
    "tags": [
     "Interpreter"
    ],
    "summary": "Clear the highlight.",
    "x-mutates-session": true,
    "parameters": [
     {
      "$ref": "#/components/parameters/DryRun"
     }
    ],
    "responses": {
     "200": {
      "description": "Cleared. A repeat returns 200 and does not bump the revision.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ControlReply"
        },
        "examples": {
         "ok_clear": {
          "summary": "Nothing highlighted any more",
          "value": {
           "state": {
            "session": 1794353523,
            "revision": 419,
            "video": "aug28",
            "playing": false,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353610.1,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1277.8
           },
           "server_now": 1794353622.4,
           "server_recv": 1794353622.399,
           "dry_run": true
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/ForeignOriginNoBody"
     },
     "429": {
      "$ref": "#/components/responses/TooSoonFocusNoBody"
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().DeleteFocus(ctx, …)",
     "python": "await factory.api.delete_focus(…)",
     "rust": "factory.api().delete_focus(…).await",
     "typescript": "await factory.api.deleteFocus(…)"
    },
    "description": "Clear the highlight.\n\n**SDK** · Go `c.API().DeleteFocus(ctx, …)` · Python `await factory.api.delete_focus(…)` · Rust `factory.api().delete_focus(…).await` · TypeScript `await factory.api.deleteFocus(…)`"
   }
  },
  "/api/v2/videos": {
   "get": {
    "operationId": "listVideos",
    "tags": [
     "Sources"
    ],
    "summary": "The public catalog.",
    "parameters": [
     {
      "$ref": "#/components/parameters/IfNoneMatch"
     }
    ],
    "responses": {
     "200": {
      "description": "All videos, with cameras and stone models.",
      "headers": {
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VideoList"
        },
        "examples": {
         "ok_catalog": {
          "summary": "The 20.20 unit today: four recordings",
          "value": {
           "schema": "stone-interpreter-catalog-v1",
           "title": "Stone-work interpreter",
           "default_video": "aug28",
           "model": {
            "checkpoint": "db1b35410858",
            "name": "hand-3D cascade v2 (R regions, H hands & bodies, S stones, T temporal)",
            "grid_fps": 5,
            "playback_rate": 0.8
           },
           "videos": [
            {
             "id": "aug28",
             "title": "Line A · 28 Aug",
             "duration": 3711.816667,
             "fps": 60.0,
             "frames": 222709,
             "grid_step": 12,
             "default_start": 1243.5,
             "hold": 1.4,
             "proxy": "/api/v2/videos/aug28/media",
             "proxy_wh": [
              816,
              770
             ],
             "native_wh": [
              1088,
              1026
             ],
             "source_wh": [
              1920,
              1080
             ],
             "crop": [
              72,
              54,
              1088,
              1026
             ],
             "profile": "1088",
             "held_out": [
              [
               877,
               899
              ]
             ],
             "camera": {
              "K": [
               [
                1104.506,
                0,
                544.047
               ],
               [
                0,
                1094.323,
                512.985
               ],
               [
                0,
                0,
                1
               ]
              ],
              "R_c2w": [
               [
                0.936803,
                0.025786,
                -0.348905
               ],
               [
                0.002448,
                -0.997739,
                -0.067166
               ],
               [
                -0.349848,
                0.062068,
                -0.934748
               ]
              ],
              "t_c2w": [
               0.16251,
               -0.00974,
               2.42157
              ],
              "gauge": "template (MHR adult), not metric",
              "calibrated": false
             },
             "stone_model": {
              "family": "dogbone",
              "h": 0.093
             }
            }
           ]
          }
         },
         "ok_shipping_catalog": {
          "summary": "The shipped catalog: the live camera first, selected by default (shipping)",
          "value": {
           "schema": "stone-interpreter-catalog-v1",
           "title": "Stone-work interpreter",
           "default_video": "live",
           "model": {
            "checkpoint": "db1b35410858",
            "name": "hand-3D cascade v2 (R regions, H hands & bodies, S stones, T temporal)",
            "grid_fps": 5,
            "playback_rate": 0.8
           },
           "videos": [
            {
             "id": "live",
             "kind": "camera",
             "live": true,
             "seekable": false,
             "title": "Line A · live camera",
             "subtitle": "Overhead, 21° tilt · cascade crop",
             "duration": null,
             "fps": 20.0,
             "frames": null,
             "grid_step": 4,
             "default_start": null,
             "hold": 1.4,
             "proxy": "/api/v2/videos/live/media",
             "proxy_wh": [
              816,
              770
             ],
             "native_wh": [
              1088,
              1026
             ],
             "source_wh": [
              1920,
              1080
             ],
             "crop": [
              72,
              54,
              1088,
              1026
             ],
             "profile": "1088",
             "held_out": []
            },
            {
             "id": "aug28",
             "title": "Line A · 28 Aug",
             "duration": 3711.816667,
             "fps": 60.0,
             "frames": 222709,
             "grid_step": 12,
             "default_start": 1243.5,
             "hold": 1.4,
             "proxy": "/api/v2/videos/aug28/media",
             "proxy_wh": [
              816,
              770
             ],
             "native_wh": [
              1088,
              1026
             ],
             "source_wh": [
              1920,
              1080
             ],
             "crop": [
              72,
              54,
              1088,
              1026
             ],
             "profile": "1088",
             "held_out": [
              [
               877,
               899
              ]
             ],
             "camera": {
              "K": [
               [
                1104.506,
                0,
                544.047
               ],
               [
                0,
                1094.323,
                512.985
               ],
               [
                0,
                0,
                1
               ]
              ],
              "R_c2w": [
               [
                0.936803,
                0.025786,
                -0.348905
               ],
               [
                0.002448,
                -0.997739,
                -0.067166
               ],
               [
                -0.349848,
                0.062068,
                -0.934748
               ]
              ],
              "t_c2w": [
               0.16251,
               -0.00974,
               2.42157
              ],
              "gauge": "template (MHR adult), not metric",
              "calibrated": false
             },
             "stone_model": {
              "family": "dogbone",
              "h": 0.093
             }
            }
           ]
          },
          "x-availability": "shipping"
         }
        }
       }
      }
     },
     "304": {
      "description": "Unchanged since the given ETag."
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().ListVideos(ctx, …)",
     "python": "await factory.api.list_videos(…)",
     "rust": "factory.api().list_videos(…).await",
     "typescript": "await factory.api.listVideos(…)",
     "high": {
      "go": "c.Sources(ctx)",
      "python": "await factory.sources()",
      "rust": "factory.sources().await?",
      "typescript": "await factory.sources()"
     }
    },
    "description": "The public catalog.\n\n**SDK** · Go `c.API().ListVideos(ctx, …)` · Python `await factory.api.list_videos(…)` · Rust `factory.api().list_videos(…).await` · TypeScript `await factory.api.listVideos(…)`\n\n**High level** · Python `await factory.sources()` · TypeScript `await factory.sources()`"
   }
  },
  "/api/v2/videos/{id}": {
   "get": {
    "operationId": "getVideo",
    "tags": [
     "Sources"
    ],
    "summary": "One catalog entry.",
    "parameters": [
     {
      "$ref": "#/components/parameters/VideoId"
     }
    ],
    "responses": {
     "200": {
      "description": "The entry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/VideoEntry"
        },
        "examples": {
         "ok_dry1": {
          "summary": "A 10 fps full-frame video",
          "value": {
           "id": "dry1",
           "duration": 1807.157567,
           "fps": 10.027903,
           "frames": 18122,
           "grid_step": 2,
           "default_start": 139.0,
           "hold": 2.2,
           "proxy": "/api/v2/videos/dry1/media",
           "proxy_wh": [
            960,
            540
           ],
           "native_wh": [
            1920,
            1080
           ],
           "crop": [
            0,
            0,
            1920,
            1080
           ],
           "profile": "1920",
           "held_out": [
            [
             139,
             161
            ]
           ]
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not in the catalog.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_unknown_video": {
          "summary": "An id that is not in the catalog",
          "value": {
           "error": "Unknown video 'nope'",
           "code": "unknown_video",
           "field": "id"
          }
         },
         "bad_traversal": {
          "summary": "A path instead of an id",
          "value": {
           "error": "Unknown video '..%2Fcatalog'",
           "code": "unknown_video",
           "field": "id"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().GetVideo(ctx, …)",
     "python": "await factory.api.get_video(…)",
     "rust": "factory.api().get_video(…).await",
     "typescript": "await factory.api.getVideo(…)"
    },
    "description": "One catalog entry.\n\n**SDK** · Go `c.API().GetVideo(ctx, …)` · Python `await factory.api.get_video(…)` · Rust `factory.api().get_video(…).await` · TypeScript `await factory.api.getVideo(…)`"
   }
  },
  "/api/v2/videos/{id}/media": {
   "get": {
    "operationId": "getVideoMedia",
    "tags": [
     "Sources"
    ],
    "summary": "The browser proxy video, with a single byte range.",
    "description": "HEAD returns the same headers with no body. Only one range is accepted (`bytes=a-b`, `a-`, `-n`).\nSame semantics as `/videos/{id}.mp4`. `If-Range` and `If-None-Match` use the ETag.\n\n**SDK** · Go `c.API().GetVideoMedia(ctx, …)` · Python `await factory.api.get_video_media(…)` · Rust `factory.api().get_video_media(…).await` · TypeScript `await factory.api.getVideoMedia(…)`\n\nThe live camera (shipping, `id` = `live`) answers a live fragmented MP4 and accepts no `Range` (416).",
    "parameters": [
     {
      "$ref": "#/components/parameters/VideoId"
     },
     {
      "$ref": "#/components/parameters/Range"
     },
     {
      "$ref": "#/components/parameters/IfRange"
     },
     {
      "$ref": "#/components/parameters/IfNoneMatch"
     }
    ],
    "responses": {
     "200": {
      "description": "The whole file.",
      "headers": {
       "ETag": {
        "$ref": "#/components/headers/ETag"
       },
       "Accept-Ranges": {
        "schema": {
         "type": "string",
         "const": "bytes"
        }
       }
      },
      "content": {
       "video/mp4": {
        "schema": {
         "type": "string",
         "format": "binary"
        },
        "examples": {
         "ok_whole_file": {
          "summary": "No Range header",
          "value": "<binary mp4>"
         }
        }
       }
      }
     },
     "206": {
      "description": "The requested range.",
      "headers": {
       "Content-Range": {
        "schema": {
         "type": "string"
        }
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "video/mp4": {
        "schema": {
         "type": "string",
         "format": "binary"
        },
        "examples": {
         "ok_first_kilobyte": {
          "summary": "The first 1024 bytes",
          "value": "<1024 bytes>"
         },
         "ok_suffix": {
          "summary": "The last 10 bytes",
          "value": "<10 bytes>"
         }
        }
       }
      }
     },
     "304": {
      "description": "Unchanged since the given ETag."
     },
     "404": {
      "description": "Not in the catalog.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_unknown_video": {
          "summary": "An id that is not in the catalog",
          "value": {
           "error": "Unknown video 'nope'",
           "code": "unknown_video",
           "field": "id"
          }
         }
        }
       }
      }
     },
     "416": {
      "description": "Range not satisfiable. Empty body, `Content-Range` gives the size.",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        },
        "examples": {
         "bad_past_end": {
          "summary": "Starts after the end",
          "value": ""
         },
         "bad_two_ranges": {
          "summary": "Multiple ranges are not supported",
          "value": ""
         },
         "bad_reversed": {
          "summary": "End before start",
          "value": ""
         }
        }
       }
      }
     }
    },
    "x-level": "low",
    "x-sdk": {
     "go": "c.API().GetVideoMedia(ctx, …)",
     "python": "await factory.api.get_video_media(…)",
     "rust": "factory.api().get_video_media(…).await",
     "typescript": "await factory.api.getVideoMedia(…)"
    }
   }
  },
  "/api/v2/session": {
   "get": {
    "operationId": "getSession",
    "tags": [
     "Session"
    ],
    "summary": "The shared clock, the worker and the Stable sim.",
    "responses": {
     "200": {
      "description": "The session now.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SessionReply"
        },
        "examples": {
         "ok_playing": {
          "summary": "Playing at 0.8x",
          "value": {
           "server_now": 1794353607.482,
           "server_recv": 1794353607.481,
           "state": {
            "session": 1794353523,
            "revision": 418,
            "video": "aug28",
            "playing": true,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353601.482,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1281.48
           },
           "worker": {
            "state": "running",
            "reason": "",
            "fps": 4.0,
            "frame_ms": 57.8,
            "cycle_ms": 59.3,
            "session": 1794353523,
            "g": 6410,
            "gpu": 918,
            "errors": 0,
            "stage_ms": {
             "decode": 0.9,
             "encoder": 34.4,
             "regions": 3.4,
             "hands": 9.6,
             "stones": 7.1,
             "temporal": 0.7,
             "total": 57.8
            },
            "engines": {
             "encoder-1088": "eefcff080c55",
             "encoder-1920": "f07cc6c711d1",
             "regions": "e4f249df07e3",
             "hands": "8cfefa5248d6",
             "stones": "1070e3c22bda",
             "temporal": "768e16042a09"
            },
            "model": "db1b35410858",
            "video": "aug28"
           },
           "viewers": 3,
           "stable": {
            "state": "running",
            "fits": 3,
            "evidence": true
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().GetSession(ctx, …)",
     "python": "await factory.api.get_session(…)",
     "rust": "factory.api().get_session(…).await",
     "typescript": "await factory.api.getSession(…)",
     "high": {
      "go": "c.Session().Clock(ctx)",
      "python": "await factory.session.clock()",
      "rust": "factory.session().clock().await?",
      "typescript": "await factory.session.clock()"
     }
    },
    "description": "The shared clock, the worker and the Stable sim.\n\n**SDK** · Go `c.API().GetSession(ctx, …)` · Python `await factory.api.get_session(…)` · Rust `factory.api().get_session(…).await` · TypeScript `await factory.api.getSession(…)`\n\n**High level** · Python `await factory.session.clock()` · TypeScript `await factory.session.clock()`"
   }
  },
  "/api/v2/session/select": {
   "post": {
    "operationId": "sessionSelect",
    "tags": [
     "Session"
    ],
    "summary": "Switch the shared session to another video.",
    "x-mutates-session": true,
    "parameters": [
     {
      "$ref": "#/components/parameters/DryRun"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SelectRequest"
       },
       "examples": {
        "ok_switch_to_dry1": {
         "summary": "Start dry1 at its default start",
         "value": {
          "video": "dry1"
         }
        },
        "ok_jul30_hinge": {
         "summary": "jul30 at the hinge, g 8180",
         "value": {
          "video": "jul30",
          "time": 1636.0
         }
        },
        "bad_unknown_video": {
         "summary": "Not in the catalog",
         "value": {
          "video": "nope"
         }
        },
        "bad_no_video": {
         "summary": "video is required",
         "value": {}
        },
        "ok_live": {
         "summary": "The live camera (shipping)",
         "value": {
          "video": "live"
         }
        },
        "bad_live_time": {
         "summary": "A time on the live camera (shipping)",
         "value": {
          "video": "live",
          "time": 12.0
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Applied (or, with dry_run, validated).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ControlReply"
        },
        "examples": {
         "ok_switch_to_dry1": {
          "summary": "A new session starts on dry1",
          "value": {
           "state": {
            "session": 1794353524,
            "revision": 420,
            "video": "dry1",
            "playing": true,
            "rate": 0.8,
            "anchor_media": 139.0,
            "anchor_wall": 1794353612.2,
            "hold_until": 1794353614.4,
            "duration": 1807.157567,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 139.0
           },
           "server_now": 1794353612.2,
           "server_recv": 1794353612.199,
           "dry_run": true
          }
         },
         "ok_live": {
          "summary": "A live session starts at the live edge (shipping)",
          "x-availability": "shipping",
          "value": {
           "state": {
            "session": 1794958000,
            "revision": 12,
            "video": "live",
            "playing": true,
            "rate": 1.0,
            "anchor_media": 0.0,
            "anchor_wall": 1794958000.2,
            "hold_until": 1794958001.6,
            "duration": null,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 0.0
           },
           "server_now": 1794958000.2,
           "server_recv": 1794958000.199,
           "dry_run": true
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Validation failed.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_unknown_video": {
          "summary": "Not in the catalog",
          "value": {
           "error": "Unknown video 'nope'",
           "code": "unknown_video",
           "field": "video"
          }
         },
         "bad_no_video": {
          "summary": "video is required",
          "value": {
           "error": "Unknown video None",
           "code": "missing_field",
           "field": "video"
          }
         },
         "bad_time_past_end": {
          "summary": "Time beyond the video",
          "value": {
           "error": "time must be within 0..3711.817 s",
           "code": "time_out_of_range",
           "field": "time"
          }
         },
         "bad_malformed_json": {
          "$ref": "#/components/examples/bad_malformed_json"
         },
         "bad_live_time": {
          "summary": "The live camera has no time (shipping)",
          "x-availability": "shipping",
          "value": {
           "error": "the live camera has no time; leave time out",
           "code": "not_seekable",
           "field": "time"
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/ForeignOrigin"
     },
     "413": {
      "$ref": "#/components/responses/TooLarge"
     },
     "415": {
      "$ref": "#/components/responses/NotJson"
     },
     "429": {
      "$ref": "#/components/responses/TooSoonSession"
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().SessionSelect(ctx, …)",
     "python": "await factory.api.session_select(…)",
     "rust": "factory.api().session_select(…).await",
     "typescript": "await factory.api.sessionSelect(…)",
     "high": {
      "go": "c.Session().Watch(ctx, \"live\", nil)",
      "python": "await factory.session.watch(\"live\")",
      "rust": "factory.session().watch(\"live\", None).await?",
      "typescript": "await factory.session.watch(\"live\")"
     }
    },
    "description": "Switch the shared session to another video.\n\n**SDK** · Go `c.API().SessionSelect(ctx, …)` · Python `await factory.api.session_select(…)` · Rust `factory.api().session_select(…).await` · TypeScript `await factory.api.sessionSelect(…)`\n\n**High level** · Python `await factory.session.watch(\"live\")` · TypeScript `await factory.session.watch(\"live\")`"
   }
  },
  "/api/v2/session/seek": {
   "post": {
    "operationId": "sessionSeek",
    "tags": [
     "Session"
    ],
    "summary": "Move the shared playhead. Starts a new interpretation run for every viewer.",
    "x-mutates-session": true,
    "parameters": [
     {
      "$ref": "#/components/parameters/DryRun"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/SeekRequest"
       },
       "examples": {
        "ok_jump_to_carry": {
         "summary": "aug28, the carry at g 6389",
         "value": {
          "time": 1277.8
         }
        },
        "ok_with_video": {
         "summary": "Seek in a named video",
         "value": {
          "video": "aug28",
          "time": 1277.8
         }
        },
        "bad_past_end": {
         "summary": "Past the end of the video",
         "value": {
          "time": 99999
         }
        },
        "bad_boolean_time": {
         "summary": "A boolean is not a number",
         "value": {
          "time": true
         }
        },
        "bad_no_time": {
         "summary": "time is required",
         "value": {
          "video": "aug28"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Applied (or, with dry_run, validated).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ControlReply"
        },
        "examples": {
         "ok_jump_to_carry": {
          "summary": "A new session, playing resumes after the hold",
          "value": {
           "state": {
            "session": 1794353523,
            "revision": 418,
            "video": "aug28",
            "playing": true,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353601.482,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1281.48
           },
           "server_now": 1794353601.482,
           "server_recv": 1794353601.481,
           "dry_run": true
          }
         },
         "ok_with_video": {
          "summary": "The video may be named",
          "value": {
           "state": {
            "session": 1794353523,
            "revision": 418,
            "video": "aug28",
            "playing": true,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353601.482,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1281.48
           },
           "server_now": 1794353601.482,
           "server_recv": 1794353601.481,
           "dry_run": true
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Validation failed.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_past_end": {
          "summary": "Past the end of the video",
          "value": {
           "error": "time must be within 0..3711.817 s",
           "code": "time_out_of_range",
           "field": "time"
          }
         },
         "bad_boolean_time": {
          "summary": "A boolean is not a number",
          "value": {
           "error": "time must be within 0..3711.817 s",
           "code": "invalid_type",
           "field": "time"
          }
         },
         "bad_no_time": {
          "summary": "time is required",
          "value": {
           "error": "time must be within 0..3711.817 s",
           "code": "missing_field",
           "field": "time"
          }
         },
         "bad_malformed_json": {
          "$ref": "#/components/examples/bad_malformed_json"
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/ForeignOrigin"
     },
     "413": {
      "$ref": "#/components/responses/TooLarge"
     },
     "415": {
      "$ref": "#/components/responses/NotJson"
     },
     "429": {
      "$ref": "#/components/responses/TooSoonSession"
     },
     "409": {
      "description": "The session shows the live camera, which cannot be seeked (shipping).",
      "x-availability": "shipping",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_live": {
          "summary": "A seek on the live camera",
          "value": {
           "error": "the live camera cannot be seeked",
           "code": "not_seekable",
           "field": "time"
          }
         }
        }
       }
      }
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().SessionSeek(ctx, …)",
     "python": "await factory.api.session_seek(…)",
     "rust": "factory.api().session_seek(…).await",
     "typescript": "await factory.api.sessionSeek(…)"
    },
    "description": "Move the shared playhead. Starts a new interpretation run for every viewer.\n\n**SDK** · Go `c.API().SessionSeek(ctx, …)` · Python `await factory.api.session_seek(…)` · Rust `factory.api().session_seek(…).await` · TypeScript `await factory.api.sessionSeek(…)`\n\nOn the live camera a seek is refused with 409 `not_seekable` (shipping); pause and play instead."
   }
  },
  "/api/v2/session/play": {
   "post": {
    "operationId": "sessionPlay",
    "tags": [
     "Session"
    ],
    "summary": "Resume the shared playhead. Idempotent.",
    "x-mutates-session": true,
    "parameters": [
     {
      "$ref": "#/components/parameters/DryRun"
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EmptyRequest"
       },
       "examples": {
        "ok_resume": {
         "summary": "No fields",
         "value": {}
        },
        "ok_fields_ignored": {
         "summary": "Fields are ignored",
         "value": {
          "video": "dry1",
          "time": 5
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Applied. A repeat returns 200 and does not bump the revision.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ControlReply"
        },
        "examples": {
         "ok_resume": {
          "summary": "Playing",
          "value": {
           "state": {
            "session": 1794353523,
            "revision": 418,
            "video": "aug28",
            "playing": true,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353601.482,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1281.48
           },
           "server_now": 1794353611.0,
           "server_recv": 1794353610.999,
           "dry_run": true
          }
         },
         "ok_fields_ignored": {
          "summary": "Playing from where it was paused; video and time are ignored",
          "value": {
           "state": {
            "session": 1794353523,
            "revision": 418,
            "video": "aug28",
            "playing": true,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353601.482,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1281.48
           },
           "server_now": 1794353611.0,
           "server_recv": 1794353610.999,
           "dry_run": true
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad body.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_malformed_json": {
          "$ref": "#/components/examples/bad_malformed_json"
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/ForeignOrigin"
     },
     "413": {
      "$ref": "#/components/responses/TooLarge"
     },
     "415": {
      "$ref": "#/components/responses/NotJson"
     },
     "429": {
      "$ref": "#/components/responses/TooSoonPlay"
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().SessionPlay(ctx, …)",
     "python": "await factory.api.session_play(…)",
     "rust": "factory.api().session_play(…).await",
     "typescript": "await factory.api.sessionPlay(…)"
    },
    "description": "Resume the shared playhead. Idempotent.\n\n**SDK** · Go `c.API().SessionPlay(ctx, …)` · Python `await factory.api.session_play(…)` · Rust `factory.api().session_play(…).await` · TypeScript `await factory.api.sessionPlay(…)`"
   }
  },
  "/api/v2/session/pause": {
   "post": {
    "operationId": "sessionPause",
    "tags": [
     "Session"
    ],
    "summary": "Pause the shared playhead. Idempotent.",
    "x-mutates-session": true,
    "parameters": [
     {
      "$ref": "#/components/parameters/DryRun"
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EmptyRequest"
       },
       "examples": {
        "ok_pause": {
         "summary": "No fields",
         "value": {}
        },
        "ok_fields_ignored": {
         "summary": "Fields are ignored",
         "value": {
          "video": "dry1",
          "time": 5
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Applied. A repeat returns 200 and does not bump the revision.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ControlReply"
        },
        "examples": {
         "ok_pause": {
          "summary": "Paused",
          "value": {
           "state": {
            "session": 1794353523,
            "revision": 419,
            "video": "aug28",
            "playing": false,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353610.1,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1277.8
           },
           "server_now": 1794353610.1,
           "server_recv": 1794353610.099,
           "dry_run": true
          }
         },
         "ok_fields_ignored": {
          "summary": "Still paused where it was; video and time are ignored",
          "value": {
           "state": {
            "session": 1794353523,
            "revision": 419,
            "video": "aug28",
            "playing": false,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353610.1,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1277.8
           },
           "server_now": 1794353610.1,
           "server_recv": 1794353610.099,
           "dry_run": true
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad body.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_malformed_json": {
          "$ref": "#/components/examples/bad_malformed_json"
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/ForeignOrigin"
     },
     "413": {
      "$ref": "#/components/responses/TooLarge"
     },
     "415": {
      "$ref": "#/components/responses/NotJson"
     },
     "429": {
      "$ref": "#/components/responses/TooSoonPlay"
     }
    },
    "x-level": "high",
    "x-sdk": {
     "go": "c.API().SessionPause(ctx, …)",
     "python": "await factory.api.session_pause(…)",
     "rust": "factory.api().session_pause(…).await",
     "typescript": "await factory.api.sessionPause(…)"
    },
    "description": "Pause the shared playhead. Idempotent.\n\n**SDK** · Go `c.API().SessionPause(ctx, …)` · Python `await factory.api.session_pause(…)` · Rust `factory.api().session_pause(…).await` · TypeScript `await factory.api.sessionPause(…)`\n\nOn the live camera (shipping) pause freezes the shared view: the world of the paused frame is refined as for a recording; play continues at the live edge in the same session, so `g` jumps by the paused time."
   }
  },
  "/api/v2/session/frames/stream": {
   "get": {
    "operationId": "streamFrames",
    "tags": [
     "Streams"
    ],
    "summary": "The same frames pushed, as SSE or NDJSON.",
    "description": "SSE events: `frame` (data = Frame, id = `<boot>-<cursor>`), `clock`, `worker`, `reset`, `gap`, with the data of `raw/stream`'s.\n`Last-Event-ID` resumes inside the retained window; an id of another boot gets `reset` and continues from the newest.\nWith the `world` layer, a frame whose world was revised (a paused frame refined, `world.rev` higher) is sent again as a\n`frame` event with the newest world; its id is the revision's cursor, its data the frame with its own `cursor`. A stream\ngets each revision once: one that reads the frame at its packet after the revision already has it, and is not sent it\nagain.\n\n**SDK** · Go `c.API().StreamFrames(ctx, …)` · Python `await factory.api.stream_frames(…)` · Rust `factory.api().stream_frames(…).await` · TypeScript `await factory.api.streamFrames(…)`\n\n**High level** · Python `async for update in factory.interpreter().updates()` · TypeScript `for await (const update of factory.interpreter().updates())`",
    "parameters": [
     {
      "$ref": "#/components/parameters/Layers"
     },
     {
      "$ref": "#/components/parameters/StreamFormat"
     },
     {
      "$ref": "#/components/parameters/After"
     },
     {
      "$ref": "#/components/parameters/StreamLimit"
     },
     {
      "$ref": "#/components/parameters/StreamMaxS"
     },
     {
      "$ref": "#/components/parameters/Observe"
     },
     {
      "$ref": "#/components/parameters/Precision"
     },
     {
      "$ref": "#/components/parameters/LastEventId"
     }
    ],
    "responses": {
     "200": {
      "description": "The stream. Ends after `limit` frames or `max_s` seconds.",
      "content": {
       "text/event-stream": {
        "schema": {
         "type": "string"
        },
        "x-item-schema": "Frame",
        "x-event-schemas": {
         "clock": "ClockEvent",
         "worker": "WorkerStatus",
         "reset": "ResetEvent",
         "gap": "GapEvent"
        },
        "examples": {
         "ok_sse_world": {
          "summary": "World snapshots as events",
          "value": "id: b7f3a2c1-918\nevent: frame\ndata: {\"cursor\":918,\"session\":1794353523,\"video\":\"aug28\",\"g\":6389,\"world\":{...}}\n\n"
         }
        }
       },
       "application/x-ndjson": {
        "schema": {
         "type": "string",
         "description": "One Frame per line."
        },
        "x-item-schema": "Frame",
        "examples": {
         "ok_ndjson_cards": {
          "summary": "Cards as NDJSON",
          "value": "{\"cursor\":918,\"g\":6389,\"cards\":{...}}\n"
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_unknown_layer": {
          "summary": "Not a layer",
          "value": {
           "error": "unknown layer 'foo'",
           "code": "unknown_layer",
           "field": "layers"
          }
         },
         "bad_max_s": {
          "summary": "max_s is 1..3600",
          "value": {
           "error": "max_s must be within 1..3600",
           "code": "invalid_param",
           "field": "max_s"
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "Too many streams.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_too_many_streams": {
          "summary": "32 streams are open",
          "value": {
           "error": "too many streams right now",
           "code": "too_many_streams",
           "retry_ms": 2000
          }
         }
        }
       }
      }
     }
    },
    "x-level": "mid",
    "x-sdk": {
     "go": "c.API().StreamFrames(ctx, …)",
     "python": "await factory.api.stream_frames(…)",
     "rust": "factory.api().stream_frames(…).await",
     "typescript": "await factory.api.streamFrames(…)",
     "high": {
      "go": "interp := c.Interpreter(); for u, err := range interp.Updates(ctx)",
      "python": "async for update in factory.interpreter().updates()",
      "rust": "factory.interpreter().updates().await?",
      "typescript": "for await (const update of factory.interpreter().updates())"
     }
    }
   }
  },
  "/api/v2/session/frames": {
   "get": {
    "operationId": "pollFrames",
    "tags": [
     "Streams"
    ],
    "summary": "Long-poll for new frames. This is what the portal uses.",
    "description": "Returns as soon as a frame newer than `cursor` is released for the requested layers or the state revision differs from `rev`,\nelse after `wait` ms. A `cursor` or `rev` ahead of the server is clamped. At most `limit` newest frames.\nWith the `world` layer, a frame whose world was revised since (a paused frame refined, `world.rev` higher) comes again,\nwith the newest world: its `cursor` is its packet's, the reply's `cursor` moves past the revision. Keep the frame of the\nnewest `world.rev` per `g`; continue from the reply's `cursor`, never from a frame's.\n\n**SDK** · Go `c.API().PollFrames(ctx, …)` · Python `await factory.api.poll_frames(…)` · Rust `factory.api().poll_frames(…).await` · TypeScript `await factory.api.pollFrames(…)`",
    "parameters": [
     {
      "$ref": "#/components/parameters/Cursor"
     },
     {
      "$ref": "#/components/parameters/Rev"
     },
     {
      "$ref": "#/components/parameters/Cid"
     },
     {
      "$ref": "#/components/parameters/Layers"
     },
     {
      "$ref": "#/components/parameters/Limit"
     },
     {
      "$ref": "#/components/parameters/WaitMs"
     },
     {
      "$ref": "#/components/parameters/Precision"
     }
    ],
    "responses": {
     "200": {
      "description": "The state and the new frames.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LiveReply"
        },
        "examples": {
         "ok_portal_bundle": {
          "summary": "What the portal asks for",
          "value": {
           "server_now": 1794353607.482,
           "server_recv": 1794353607.21,
           "state": {
            "session": 1794353523,
            "revision": 418,
            "video": "aug28",
            "playing": true,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353601.482,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1281.48
           },
           "worker": {
            "state": "running",
            "reason": "",
            "fps": 4.0,
            "frame_ms": 57.8,
            "cycle_ms": 59.3,
            "session": 1794353523,
            "g": 6410,
            "gpu": 918,
            "errors": 0,
            "stage_ms": {
             "decode": 0.9,
             "encoder": 34.4,
             "regions": 3.4,
             "hands": 9.6,
             "stones": 7.1,
             "temporal": 0.7,
             "total": 57.8
            },
            "engines": {
             "encoder-1088": "eefcff080c55",
             "encoder-1920": "f07cc6c711d1",
             "regions": "e4f249df07e3",
             "hands": "8cfefa5248d6",
             "stones": "1070e3c22bda",
             "temporal": "768e16042a09"
            },
            "model": "db1b35410858",
            "video": "aug28"
           },
           "viewers": 3,
           "stable": {
            "state": "running",
            "fits": 3,
            "evidence": true
           },
           "cursor": 918,
           "frames": [
            {
             "cursor": 918,
             "session": 1794353523,
             "video": "aug28",
             "g": 6389,
             "i": 76668,
             "t": 1277.8,
             "past_valid": true,
             "dt_past": 0.6,
             "overlay": {
              "schema": "ovl1",
              "native_wh": [
               1088,
               1026
              ],
              "regions": {
               "rows": 40,
               "cols": 64,
               "human": "AAAAAAEBAgID...",
               "tray": "AAAAAAAAAAEB...",
               "stone": "AAECAgMDBAUF..."
              },
              "mask": {
               "rows": 40,
               "cols": 64,
               "label": "AAEBAQICAgMD...",
               "alpha": "AB9kf5CYoaqz...",
               "box": [
                0.0,
                0.0,
                0.9412,
                0.6238
               ],
               "rot": false,
               "present": true
              },
              "boxes": {
               "person": [
                0.0,
                0.0,
                0.9412,
                0.6238,
                false,
                0.999
               ],
               "stone": [
                0.1014,
                0.0848,
                0.6408,
                1.0,
                true,
                0.999
               ]
              },
              "joints": [
               [
                0.2191,
                0.3371,
                1.0,
                -0.568,
                -0.314,
                2.049
               ],
               [
                0.2159,
                0.3363,
                1.0,
                -0.555,
                -0.304,
                1.978
               ],
               null
              ],
              "scale": 0.029,
              "wrists": {
               "left": {
                "uv": [
                 0.4936,
                 0.3798
                ],
                "visible": true,
                "filled": true,
                "ring": true,
                "stone": -1
               },
               "right": {
                "uv": [
                 0.2178,
                 0.4737
                ],
                "visible": true,
                "filled": true,
                "ring": true,
                "stone": -1
               }
              },
              "prev_g": 6388,
              "items": [
               {
                "t": [
                 0.1501,
                 0.6254,
                 0.045,
                 0.0886,
                 0.557,
                 -1.036,
                 0.352,
                 3.002,
                 0.133,
                 0.249,
                 1.505
                ],
                "prev": 0,
                "side": null,
                "outline": [
                 [
                  181.49,
                  595.71
                 ],
                 [
                  187.29,
                  683.77
                 ],
                 [
                  144.13,
                  686.61
                 ],
                 [
                  138.33,
                  598.55
                 ]
                ]
               }
              ]
             },
             "scene": {
              "schema": "scn1",
              "plane": {
               "n": [
                -0.3498,
                0.0621,
                -0.9347
               ],
               "d": -2.4216,
               "floor": -0.8458,
               "anchor": "prior",
               "floor_anchor": "ankles"
              },
              "board": {
               "raw": {
                "cx": -1.1755,
                "cy": -0.4326,
                "theta": 1.4556,
                "hw": 0.9168,
                "hh": 0.6683
               }
              },
              "surface": {
               "rows": 40,
               "cols": 64,
               "q": "Nk5TV1tcXmBh...",
               "lo": -3.1111,
               "hi": 2.7123,
               "a": 0.0233,
               "b": 1.0063,
               "flat": "AAAAgP8P/w8A...",
               "quads": {
                "raw": "//////8f/P8H...",
                "stable": "//////8//f8P..."
               },
               "lift": 0.002
              },
              "skeleton": {
               "world": [
                [
                 -1.093,
                 0.165,
                 0.686
                ],
                null
               ]
              },
              "rings": [
               {
                "side": "left",
                "pos": [
                 -0.725,
                 0.035,
                 -0.046
                ]
               },
               {
                "side": "right",
                "pos": [
                 -1.478,
                 -0.206,
                 0.077
                ]
               }
              ],
              "items": [
               {
                "x": -1.8465,
                "y": -0.5647,
                "yaw": -1.5168,
                "L": 0.2435,
                "S": 0.1452,
                "h": 0.0653,
                "side": null
               }
              ]
             },
             "cards": {
              "schema": "crd1",
              "left": {
               "title": "Hand on a stone",
               "tone": "interact",
               "visible": true,
               "pInteraction": 0.988,
               "contact": 0.997,
               "contactOn": true,
               "held": "empty",
               "pHeld": 0.929,
               "action": "hold_stone",
               "fine": [
                {
                 "key": "not_interacting",
                 "label": "not interacting",
                 "p": 0.012,
                 "reliable": true
                },
                {
                 "key": "hold_stone",
                 "label": "hold stone",
                 "p": 0.922,
                 "reliable": true
                }
               ],
               "hint": null,
               "stone": -1,
               "pWrist": 1.0
              },
              "right": {
               "title": "Holding a stone",
               "tone": "hold",
               "visible": true,
               "pInteraction": 0.991,
               "contact": 0.996,
               "contactOn": true,
               "held": "stone",
               "pHeld": 0.9,
               "action": "hold_stone",
               "fine": [
                {
                 "key": "not_interacting",
                 "label": "not interacting",
                 "p": 0.009,
                 "reliable": true
                },
                {
                 "key": "hold_stone",
                 "label": "hold stone",
                 "p": 0.801,
                 "reliable": true
                }
               ],
               "hint": null,
               "stone": -1,
               "pWrist": 1.0
              },
              "stage": {
               "parts": [
                {
                 "key": "decode",
                 "label": "decode",
                 "fam": "I",
                 "ms": 0.9
                },
                {
                 "key": "encoder",
                 "label": "encoder",
                 "fam": "E",
                 "ms": 34.4
                },
                {
                 "key": "regions",
                 "label": "R regions",
                 "fam": "R",
                 "ms": 3.4
                },
                {
                 "key": "hands",
                 "label": "H hands",
                 "fam": "H",
                 "ms": 9.6
                },
                {
                 "key": "stones",
                 "label": "S stones",
                 "fam": "S",
                 "ms": 7.1
                },
                {
                 "key": "temporal",
                 "label": "T temporal",
                 "fam": "T",
                 "ms": 0.7
                }
               ],
               "total": 57.8,
               "fps": 17.3
              },
              "numbers": {
               "stones": 23,
               "past_valid": true,
               "dt_past": 0.6,
               "tray_anchor": "prior",
               "floor_anchor": "ankles",
               "depth_anchor": "board",
               "g": 6389,
               "t": 1277.8,
               "session": 1794353523
              }
             },
             "world": {
              "schema": "stw1",
              "session": 1794353523,
              "video": "aug28",
              "g": 6389,
              "t": 1277.8,
              "motion": "static",
              "logF": -0.08459,
              "stones": [
               {
                "id": 72,
                "mode": "carry",
                "family": "dogbone",
                "shape": "model",
                "detected": false,
                "uncertain": false,
                "side": "right",
                "outline": [
                 [
                  372.05,
                  474.42
                 ],
                 [
                  372.11,
                  497.61
                 ],
                 [
                  362.88,
                  511.3
                 ]
                ],
                "solid": {
                 "pos": [
                  -1.2055,
                  -0.2421,
                  0.2159
                 ],
                 "q": [
                  -0.40383,
                  0.40732,
                  -0.58172,
                  0.57673
                 ],
                 "dims": [
                  0.3084,
                  0.235,
                  0.093
                 ]
                }
               },
               {
                "id": 39,
                "mode": "kept",
                "family": "dogbone",
                "shape": "model",
                "detected": false,
                "uncertain": true,
                "side": null,
                "outline": [
                 [
                  217.48,
                  248.44
                 ],
                 [
                  217.58,
                  270.08
                 ],
                 [
                  208.88,
                  281.77
                 ]
                ],
                "solid": {
                 "pos": [
                  -1.6785,
                  0.334,
                  0.0465
                 ],
                 "q": [
                  0,
                  0,
                  -0.71353,
                  0.70062
                 ],
                 "dims": [
                  0.297,
                  0.2192,
                  0.093
                 ]
                }
               }
              ],
              "hands": {
               "left": {
                "state": "touch",
                "stone": null,
                "rayK": 0.998055
               },
               "right": {
                "state": "carry",
                "stone": 72,
                "rayK": 0.983232
               }
              },
              "events": [
               {
                "type": "lift",
                "id": 72,
                "side": "right"
               },
               {
                "type": "carry",
                "id": 72,
                "side": "right"
               },
               {
                "type": "push",
                "id": 63,
                "side": "left"
               }
              ],
              "stats": {
               "stones": 33,
               "confirmed": 33,
               "frozen": 0,
               "fitted": 3,
               "held": 1,
               "stepMs": 4.2
              },
              "draw": {
               "board": {
                "cx": -1.1755,
                "cy": -0.4326,
                "theta": 1.4556,
                "hw": 0.9168,
                "hh": 0.6683
               },
               "skeleton": {
                "logF": -0.084593,
                "k": {
                 "left": 0.998055,
                 "right": 0.983232
                },
                "elbow": {
                 "left": [
                  0.00153,
                  -0.0016,
                  -0.00223
                 ],
                 "right": [
                  0.02213,
                  -0.02741,
                  0.00364
                 ]
                }
               }
              },
              "focus": {
               "id": 72,
               "path2d": [
                [
                 335.1,
                 540.2
                ]
               ],
               "path3d": [
                [
                 -1.21,
                 -0.24,
                 0.26
                ]
               ]
              }
             }
            }
           ]
          }
         },
         "ok_world_only": {
          "summary": "Only the cleaned-up world",
          "value": {
           "server_now": 1794353607.482,
           "server_recv": 1794353607.481,
           "state": {
            "session": 1794353523,
            "revision": 418,
            "video": "aug28",
            "playing": true,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353601.482,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1281.48
           },
           "worker": {
            "state": "running",
            "reason": "",
            "fps": 4.0,
            "frame_ms": 57.8,
            "cycle_ms": 59.3,
            "session": 1794353523,
            "g": 6410,
            "gpu": 918,
            "errors": 0,
            "stage_ms": {
             "decode": 0.9,
             "encoder": 34.4,
             "regions": 3.4,
             "hands": 9.6,
             "stones": 7.1,
             "temporal": 0.7,
             "total": 57.8
            },
            "engines": {
             "encoder-1088": "eefcff080c55",
             "encoder-1920": "f07cc6c711d1",
             "regions": "e4f249df07e3",
             "hands": "8cfefa5248d6",
             "stones": "1070e3c22bda",
             "temporal": "768e16042a09"
            },
            "model": "db1b35410858",
            "video": "aug28"
           },
           "viewers": 3,
           "stable": {
            "state": "running",
            "fits": 3,
            "evidence": true
           },
           "cursor": 918,
           "frames": [
            {
             "cursor": 918,
             "session": 1794353523,
             "video": "aug28",
             "g": 6389,
             "i": 76668,
             "t": 1277.8,
             "past_valid": true,
             "dt_past": 0.6,
             "world": {
              "schema": "stw1",
              "session": 1794353523,
              "video": "aug28",
              "g": 6389,
              "t": 1277.8,
              "motion": "static",
              "logF": -0.08459,
              "stones": [
               {
                "id": 72,
                "mode": "carry",
                "family": "dogbone",
                "shape": "model",
                "detected": false,
                "uncertain": false,
                "side": "right",
                "outline": [
                 [
                  372.05,
                  474.42
                 ],
                 [
                  372.11,
                  497.61
                 ],
                 [
                  362.88,
                  511.3
                 ]
                ],
                "solid": {
                 "pos": [
                  -1.2055,
                  -0.2421,
                  0.2159
                 ],
                 "q": [
                  -0.40383,
                  0.40732,
                  -0.58172,
                  0.57673
                 ],
                 "dims": [
                  0.3084,
                  0.235,
                  0.093
                 ]
                }
               },
               {
                "id": 39,
                "mode": "kept",
                "family": "dogbone",
                "shape": "model",
                "detected": false,
                "uncertain": true,
                "side": null,
                "outline": [
                 [
                  217.48,
                  248.44
                 ],
                 [
                  217.58,
                  270.08
                 ],
                 [
                  208.88,
                  281.77
                 ]
                ],
                "solid": {
                 "pos": [
                  -1.6785,
                  0.334,
                  0.0465
                 ],
                 "q": [
                  0,
                  0,
                  -0.71353,
                  0.70062
                 ],
                 "dims": [
                  0.297,
                  0.2192,
                  0.093
                 ]
                }
               }
              ],
              "hands": {
               "left": {
                "state": "touch",
                "stone": null,
                "rayK": 0.998055
               },
               "right": {
                "state": "carry",
                "stone": 72,
                "rayK": 0.983232
               }
              },
              "events": [
               {
                "type": "lift",
                "id": 72,
                "side": "right"
               },
               {
                "type": "carry",
                "id": 72,
                "side": "right"
               },
               {
                "type": "push",
                "id": 63,
                "side": "left"
               }
              ],
              "stats": {
               "stones": 33,
               "confirmed": 33,
               "frozen": 0,
               "fitted": 3,
               "held": 1,
               "stepMs": 4.2
              },
              "draw": {
               "board": {
                "cx": -1.1755,
                "cy": -0.4326,
                "theta": 1.4556,
                "hw": 0.9168,
                "hh": 0.6683
               },
               "skeleton": {
                "logF": -0.084593,
                "k": {
                 "left": 0.998055,
                 "right": 0.983232
                },
                "elbow": {
                 "left": [
                  0.00153,
                  -0.0016,
                  -0.00223
                 ],
                 "right": [
                  0.02213,
                  -0.02741,
                  0.00364
                 ]
                }
               }
              },
              "focus": {
               "id": 72,
               "path2d": [
                [
                 335.1,
                 540.2
                ]
               ],
               "path3d": [
                [
                 -1.21,
                 -0.24,
                 0.26
                ]
               ]
              }
             }
            }
           ]
          }
         },
         "ok_world_late": {
          "summary": "A frame released without its world (300 ms deadline)",
          "value": {
           "server_now": 1794353607.482,
           "server_recv": 1794353607.481,
           "state": {
            "session": 1794353523,
            "revision": 418,
            "video": "aug28",
            "playing": true,
            "rate": 0.8,
            "anchor_media": 1277.8,
            "anchor_wall": 1794353601.482,
            "hold_until": 1794353602.882,
            "duration": 3711.816667,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 1281.48
           },
           "worker": {
            "state": "running",
            "reason": "",
            "fps": 4.0,
            "frame_ms": 57.8,
            "cycle_ms": 59.3,
            "session": 1794353523,
            "g": 6410,
            "gpu": 918,
            "errors": 0,
            "stage_ms": {
             "decode": 0.9,
             "encoder": 34.4,
             "regions": 3.4,
             "hands": 9.6,
             "stones": 7.1,
             "temporal": 0.7,
             "total": 57.8
            },
            "engines": {
             "encoder-1088": "eefcff080c55",
             "encoder-1920": "f07cc6c711d1",
             "regions": "e4f249df07e3",
             "hands": "8cfefa5248d6",
             "stones": "1070e3c22bda",
             "temporal": "768e16042a09"
            },
            "model": "db1b35410858",
            "video": "aug28"
           },
           "viewers": 3,
           "stable": {
            "state": "failed",
            "fits": 3,
            "evidence": true,
            "message": "restarting"
           },
           "cursor": 918,
           "frames": [
            {
             "cursor": 918,
             "session": 1794353523,
             "video": "aug28",
             "g": 6389,
             "i": 76668,
             "t": 1277.8,
             "past_valid": true,
             "dt_past": 0.6,
             "missing": [
              "world"
             ],
             "overlay": {
              "schema": "ovl1",
              "native_wh": [
               1088,
               1026
              ],
              "regions": {
               "rows": 40,
               "cols": 64,
               "human": "AAAAAAEBAgID...",
               "tray": "AAAAAAAAAAEB...",
               "stone": "AAECAgMDBAUF..."
              },
              "mask": {
               "rows": 40,
               "cols": 64,
               "label": "AAEBAQICAgMD...",
               "alpha": "AB9kf5CYoaqz...",
               "box": [
                0.0,
                0.0,
                0.9412,
                0.6238
               ],
               "rot": false,
               "present": true
              },
              "boxes": {
               "person": [
                0.0,
                0.0,
                0.9412,
                0.6238,
                false,
                0.999
               ],
               "stone": [
                0.1014,
                0.0848,
                0.6408,
                1.0,
                true,
                0.999
               ]
              },
              "joints": [
               [
                0.2191,
                0.3371,
                1.0,
                -0.568,
                -0.314,
                2.049
               ],
               [
                0.2159,
                0.3363,
                1.0,
                -0.555,
                -0.304,
                1.978
               ],
               null
              ],
              "scale": 0.029,
              "wrists": {
               "left": {
                "uv": [
                 0.4936,
                 0.3798
                ],
                "visible": true,
                "filled": true,
                "ring": true,
                "stone": -1
               },
               "right": {
                "uv": [
                 0.2178,
                 0.4737
                ],
                "visible": true,
                "filled": true,
                "ring": true,
                "stone": -1
               }
              },
              "prev_g": 6388,
              "items": [
               {
                "t": [
                 0.1501,
                 0.6254,
                 0.045,
                 0.0886,
                 0.557,
                 -1.036,
                 0.352,
                 3.002,
                 0.133,
                 0.249,
                 1.505
                ],
                "prev": 0,
                "side": null,
                "outline": [
                 [
                  181.49,
                  595.71
                 ],
                 [
                  187.29,
                  683.77
                 ],
                 [
                  144.13,
                  686.61
                 ],
                 [
                  138.33,
                  598.55
                 ]
                ]
               }
              ]
             }
            }
           ]
          }
         },
         "ok_world_revised": {
          "summary": "A paused frame's world released again, revised",
          "description": "Fixer thin-v1, paused on dry2 at 9:49 by a seek: the frame on screen, g 2953, came first with 16 of its 40 stones shaped. Five rounds of rest refinement shaped them all and added two the model never boxed (`source: image`), and each round that changed the world released the frame again. A poll of the world layer from the frame's own cursor gets it once more, at its newest revision (here rev 5): the frame's `cursor` stays its packet's, the reply's `cursor` is past the revision. Readers of other layers get nothing from a revision.",
          "value": {
           "server_now": 1794446913.347661,
           "server_recv": 1794446913.347649,
           "state": {
            "session": 1794446896,
            "revision": 3,
            "video": "dry2",
            "playing": false,
            "rate": 0.8,
            "anchor_media": 589.0,
            "anchor_wall": 1794446912.444618,
            "hold_until": 1794446914.644618,
            "duration": 1792.199311,
            "changed_by": "viewer",
            "focus": null,
            "media_time": 589.0
           },
           "worker": {
            "state": "running",
            "reason": "",
            "fps": 4.6,
            "frame_ms": 310.8,
            "cycle_ms": 1.2,
            "session": 1794446896,
            "g": 2956,
            "errors": 0,
            "stage_ms": {
             "decode": 0.2,
             "encoder": 84.5,
             "regions": 42.9,
             "hands": 154,
             "stones": 86.5,
             "temporal": 4.4,
             "total": 372.5
            },
            "engines": {
             "encoder-1088": "eefcff080c55",
             "encoder-1920": "f07cc6c711d1",
             "regions": "e4f249df07e3",
             "hands": "8cfefa5248d6",
             "stones": "1070e3c22bda",
             "temporal": "768e16042a09"
            },
            "model": "db1b35410858",
            "video": "dry2"
           },
           "viewers": 1,
           "stable": {
            "state": "running",
            "fits": 4,
            "evidence": true,
            "fixer": "thin-v1",
            "hold": {
             "session": 1794446896,
             "g": 2953,
             "state": "converged",
             "rounds": 5,
             "rev": 5,
             "ms": 111.6,
             "resteps": 3
            }
           },
           "cursor": 83,
           "frames": [
            {
             "cursor": 72,
             "session": 1794446896,
             "video": "dry2",
             "g": 2953,
             "i": 5906,
             "t": 588.956667,
             "past_valid": true,
             "dt_past": 0.598333,
             "world": {
              "schema": "stw1",
              "session": 1794446896,
              "video": "dry2",
              "g": 2953,
              "t": 588.956667,
              "motion": "static",
              "logF": 0.0191,
              "stones": [
               {
                "id": 1,
                "mode": "seen",
                "family": "rect",
                "shape": "provisional",
                "detected": true,
                "uncertain": false,
                "side": null,
                "outline": [
                 [
                  1021.71,
                  389.7
                 ],
                 [
                  1022.57,
                  498.31
                 ],
                 [
                  951.32,
                  498.88
                 ],
                 [
                  950.46,
                  390.26
                 ]
                ],
                "solid": {
                 "pos": [
                  -0.2274,
                  -0.1582,
                  0.046
                 ],
                 "q": [
                  0,
                  0,
                  -0.702,
                  0.71218
                 ],
                 "dims": [
                  0.219,
                  0.1469,
                  0.092
                 ]
                }
               },
               {
                "id": 41,
                "mode": "kept",
                "family": "rect",
                "shape": "provisional",
                "detected": false,
                "uncertain": false,
                "side": null,
                "outline": [
                 [
                  1845.38,
                  504.43
                 ],
                 [
                  1845.38,
                  616.65
                 ],
                 [
                  1736.55,
                  616.65
                 ],
                 [
                  1736.55,
                  504.43
                 ]
                ],
                "solid": {
                 "pos": [
                  1.2476,
                  -0.3594,
                  0.046
                 ],
                 "q": [
                  0,
                  0,
                  -0.68198,
                  0.73138
                 ],
                 "dims": [
                  0.2152,
                  0.1936,
                  0.092
                 ]
                },
                "source": "image"
               }
              ],
              "hands": {
               "left": {
                "state": "free",
                "stone": null
               },
               "right": {
                "state": "free",
                "stone": null
               }
              },
              "events": [
               {
                "type": "new",
                "id": 41,
                "source": "image"
               },
               {
                "type": "confirm",
                "id": 41
               },
               {
                "type": "new",
                "id": 42,
                "source": "image"
               },
               {
                "type": "confirm",
                "id": 42
               }
              ],
              "stats": {
               "stones": 42,
               "confirmed": 42,
               "frozen": 0,
               "fitted": 42,
               "held": 0,
               "stepMs": 2.5
              },
              "draw": {
               "board": {
                "cx": 0.5277,
                "cy": -0.7033,
                "theta": -0.0313,
                "hw": 0.8341,
                "hh": 0.7407
               },
               "skeleton": {
                "logF": 0.0191,
                "k": {
                 "left": 1,
                 "right": 1
                },
                "elbow": {
                 "left": [
                  0,
                  0,
                  0
                 ],
                 "right": [
                  0,
                  0,
                  0
                 ]
                }
               }
              },
              "focus": null,
              "rev": 5
             }
            }
           ]
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_unknown_layer": {
          "summary": "Not a layer",
          "value": {
           "error": "unknown layer 'foo'",
           "code": "unknown_layer",
           "field": "layers"
          }
         },
         "bad_cursor": {
          "summary": "cursor must be digits",
          "value": {
           "error": "cursor must be an integer",
           "code": "invalid_param",
           "field": "cursor"
          }
         },
         "bad_limit": {
          "summary": "limit is at most 16",
          "value": {
           "error": "limit must be within 1..16",
           "code": "invalid_param",
           "field": "limit"
          }
         },
         "bad_wait": {
          "summary": "wait is at most 1000 ms",
          "value": {
           "error": "wait must be within 0..1000 ms",
           "code": "invalid_param",
           "field": "wait"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Too many replies that did not wait.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_polling_too_fast": {
          "summary": "rev=0 in a tight loop drains the per-IP bucket",
          "description": "seq 180 | xargs -P 16 -I{} curl -s -o /dev/null -w '%{http_code}\\n' 'http://HOST:8120/api/v2/session/frames?rev=0' | sort | uniq -c",
          "value": {
           "error": "too many requests",
           "code": "too_many_requests",
           "retry_ms": 500
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "Too many long-polls.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_too_many_viewers": {
          "summary": "256 polls are waiting",
          "value": {
           "error": "too many viewers right now",
           "code": "too_many_viewers",
           "retry_ms": 2000
          }
         }
        }
       }
      }
     }
    },
    "x-level": "mid",
    "x-sdk": {
     "go": "c.API().PollFrames(ctx, …)",
     "python": "await factory.api.poll_frames(…)",
     "rust": "factory.api().poll_frames(…).await",
     "typescript": "await factory.api.pollFrames(…)"
    }
   }
  },
  "/api/v2/raw/stream": {
   "get": {
    "operationId": "rawStream",
    "tags": [
     "Streams"
    ],
    "summary": "The raw model codec stream.",
    "description": "One `sip1` packet per line, with no envelope (NDJSON), or SSE with `Accept: text/event-stream` or `format=sse`.\nSSE events: `frame` (data = the packet, id = `<boot>-<cursor>`), `clock`, `worker`, `reset`, `gap`.\nTheir data: `clock` the shared state with `server_now` (ClockEvent), `worker` a WorkerStatus, `reset` `{boot, cursor}`, `gap` `{gap}`.\nA slow consumer skips the oldest and gets `gap` (NDJSON: a line `{\"gap\":n}`).\nA consumer counts as a viewer and keeps the GPU working unless `observe=1`.\n\n**SDK** · Go `c.API().RawStream(ctx, …)` · Python `await factory.api.raw_stream(…)` · Rust `factory.api().raw_stream(…).await` · TypeScript `await factory.api.rawStream(…)`",
    "parameters": [
     {
      "$ref": "#/components/parameters/StreamFormat"
     },
     {
      "$ref": "#/components/parameters/After"
     },
     {
      "$ref": "#/components/parameters/StreamLimit"
     },
     {
      "$ref": "#/components/parameters/StreamMaxS"
     },
     {
      "$ref": "#/components/parameters/Observe"
     },
     {
      "$ref": "#/components/parameters/LastEventId"
     }
    ],
    "responses": {
     "200": {
      "description": "The stream. Ends after `limit` packets or `max_s` seconds.",
      "content": {
       "application/x-ndjson": {
        "schema": {
         "type": "string",
         "description": "One Sip1Packet per line."
        },
        "x-item-schema": "Sip1Packet",
        "examples": {
         "ok_four_packets": {
          "summary": "Four packets and stop",
          "value": "{\"schema\":\"sip1\",\"maps\":{...},\"session\":1794353523,\"video\":\"aug28\",\"g\":6389,\"i\":76668,\"t\":1277.8,\"past_valid\":true,\"dt_past\":0.6,\"ms\":{...},\"cursor\":918}\n{\"schema\":\"sip1\",\"maps\":{...},\"session\":1794353523,\"video\":\"aug28\",\"g\":6390,\"i\":76680,\"t\":1278.0,\"past_valid\":true,\"dt_past\":0.6,\"ms\":{...},\"cursor\":919}\n"
         }
        }
       },
       "text/event-stream": {
        "schema": {
         "type": "string"
        },
        "x-item-schema": "Sip1Packet",
        "x-event-schemas": {
         "clock": "ClockEvent",
         "worker": "WorkerStatus",
         "reset": "ResetEvent",
         "gap": "GapEvent"
        },
        "examples": {
         "ok_sse": {
          "summary": "Server-sent events",
          "value": "id: b7f3a2c1-918\nevent: frame\ndata: {\"schema\":\"sip1\",\"g\":6389,...}\n\nevent: clock\ndata: {\"revision\":418,\"media_time\":1278.1}\n\n"
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_limit_zero": {
          "summary": "limit must be 1..4096",
          "value": {
           "error": "limit must be within 1..4096",
           "code": "invalid_param",
           "field": "limit"
          }
         },
         "bad_format": {
          "summary": "Only ndjson and sse",
          "value": {
           "error": "format must be ndjson or sse",
           "code": "invalid_param",
           "field": "format"
          }
         },
         "bad_after": {
          "summary": "after is a cursor",
          "value": {
           "error": "after must be an integer",
           "code": "invalid_param",
           "field": "after"
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "Too many streams.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_too_many_streams": {
          "summary": "32 streams are open",
          "value": {
           "error": "too many streams right now",
           "code": "too_many_streams",
           "retry_ms": 2000
          }
         }
        }
       }
      }
     }
    },
    "x-level": "low",
    "x-sdk": {
     "go": "c.API().RawStream(ctx, …)",
     "python": "await factory.api.raw_stream(…)",
     "rust": "factory.api().raw_stream(…).await",
     "typescript": "await factory.api.rawStream(…)"
    }
   }
  },
  "/api/v2/session/render/overlay2d": {
   "get": {
    "operationId": "renderOverlay2d",
    "tags": [
     "Render-ready"
    ],
    "summary": "Everything the 2-D overlay draws, final, at a grid frame or any retained time.",
    "description": "Skeleton, hands and stones are already interpolated, with hide and freeze applied. Give exactly one of `g` and `t`.\n\n**SDK** · Go `c.API().RenderOverlay2D(ctx, …)` · Python `await factory.api.render_overlay2d(…)` · Rust `factory.api().render_overlay2d(…).await` · TypeScript `await factory.api.renderOverlay2d(…)`",
    "parameters": [
     {
      "$ref": "#/components/parameters/RenderG"
     },
     {
      "$ref": "#/components/parameters/RenderT"
     },
     {
      "$ref": "#/components/parameters/RenderMode"
     },
     {
      "$ref": "#/components/parameters/RenderDraw"
     },
     {
      "$ref": "#/components/parameters/SessionGuard"
     }
    ],
    "responses": {
     "200": {
      "description": "The draw list, in native px.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Overlay2D"
        },
        "examples": {
         "ok_on_grid": {
          "summary": "At the lift, on a grid frame",
          "value": {
           "schema": "r2d1",
           "session": 1794353523,
           "video": "aug28",
           "g": 6389,
           "bg": 6390,
           "f": 0,
           "t": 1277.8,
           "mode": "stable",
           "native_wh": [
            1088,
            1026
           ],
           "regions": {
            "url": "/api/v2/session/frames/6389/regions.png",
            "rows": 40,
            "cols": 64
           },
           "mask": {
            "url": "/api/v2/session/frames/6389/mask.png",
            "box": [
             0.0,
             0.0,
             0.9412,
             0.6238
            ],
            "rot": false
           },
           "boxes": [
            {
             "kind": "person",
             "x0": -0.5,
             "y0": -0.5,
             "x1": 1023.5,
             "y1": 639.5,
             "rot": false,
             "presence": 0.999,
             "label": "person 1.00"
            }
           ],
           "stones": [
            {
             "id": 72,
             "outline": [
              [
               372.05,
               474.42
              ],
              [
               372.11,
               497.61
              ],
              [
               362.88,
               511.3
              ]
             ],
             "style": "held",
             "side": "right",
             "alpha": 1,
             "detected": false,
             "uncertain": false,
             "shape": "model",
             "mode": "carry"
            }
           ],
           "skeleton": {
            "bones": [
             {
              "a": 13,
              "b": 11,
              "from": [
               495.41,
               175.46
              ],
              "to": [
               469.52,
               198.95
              ],
              "side": "body",
              "alpha": 1,
              "hand": false
             }
            ],
            "joints": [
             {
              "j": 0,
              "at": [
               237.89,
               345.56
              ],
              "side": "body",
              "alpha": 1,
              "hand": false
             }
            ]
           },
           "wrists": [
            {
             "side": "right",
             "at": [
              236.47,
              485.5
             ],
             "filled": true,
             "ring": true,
             "label": "R"
            }
           ],
           "focus": null
          }
         },
         "ok_between_packets": {
          "summary": "Half way between two packets, stone 72 on its lift path",
          "value": {
           "schema": "r2d1",
           "session": 1794353523,
           "video": "aug28",
           "g": 6389,
           "bg": 6390,
           "f": 0.5,
           "t": 1277.9,
           "mode": "stable",
           "native_wh": [
            1088,
            1026
           ],
           "regions": {
            "url": "/api/v2/session/frames/6389/regions.png",
            "rows": 40,
            "cols": 64
           },
           "mask": {
            "url": "/api/v2/session/frames/6389/mask.png",
            "box": [
             0.0,
             0.0,
             0.9412,
             0.6238
            ],
            "rot": false
           },
           "boxes": [],
           "stones": [
            {
             "id": 72,
             "outline": [
              [
               354.53,
               447.25
              ],
              [
               354.55,
               470.58
              ],
              [
               345.11,
               484.12
              ]
             ],
             "style": "held",
             "side": "right",
             "alpha": 1,
             "detected": false,
             "uncertain": false,
             "shape": "model",
             "mode": "carry"
            }
           ],
           "skeleton": {
            "bones": [],
            "joints": []
           },
           "wrists": [],
           "focus": null
          }
         },
         "ok_primitives": {
          "summary": "Flat shapes for a renderer with no domain knowledge",
          "description": "Widths and radii are in the line unit `lw` of a canvas of the native width, as the page draws them: a detected stone, a body bone, and the right wrist (filled at alpha .85, stroked, and its contact ring).",
          "value": {
           "schema": "r2d1",
           "session": 1794353523,
           "video": "aug28",
           "g": 6389,
           "bg": 6390,
           "f": 0,
           "t": 1277.8,
           "mode": "stable",
           "native_wh": [
            1088,
            1026
           ],
           "primitives": {
            "lw": 2.5905,
            "images": [
             {
              "url": "/api/v2/session/frames/6389/regions.png",
              "x": -0.5,
              "y": -0.5,
              "w": 1088,
              "h": 1026,
              "alpha": 1
             }
            ],
            "polygons": [
             {
              "points": [
               [
                134.25,
                685.05
               ],
               [
                136.25,
                664.68
               ],
               [
                145.74,
                654.53
               ]
              ],
              "stroke": "#ffd60a",
              "fill": "#ffd60a",
              "fill_alpha": 0.1,
              "width": 2.5905,
              "dash": null,
              "alpha": 0.95
             }
            ],
            "segments": [
             {
              "from": [
               495.41,
               175.46
              ],
              "to": [
               469.52,
               198.95
              ],
              "color": "#a4f1be",
              "width": 2.979,
              "alpha": 1
             }
            ],
            "circles": [
             {
              "at": [
               236.47,
               485.52
              ],
              "r": 8.2895,
              "stroke": null,
              "fill": "#00b5ff",
              "alpha": 0.85
             },
             {
              "at": [
               236.47,
               485.52
              ],
              "r": 8.2895,
              "stroke": "#00b5ff",
              "fill": null,
              "alpha": 1,
              "width": 2.5905
             },
             {
              "at": [
               236.47,
               485.52
              ],
              "r": 15.0248,
              "stroke": "#00b5ff",
              "fill": null,
              "alpha": 1,
              "width": 3.6267
             }
            ],
            "labels": [
             {
              "at": [
               6.09,
               4.09
              ],
              "text": "person 1.00",
              "color": "#ed50e9",
              "background": "rgba(0,0,0,.6)",
              "baseline": "top"
             },
             {
              "at": [
               253.57,
               485.52
              ],
              "text": "R",
              "color": "#00b5ff",
              "baseline": "middle"
             }
            ]
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_both_t_and_g": {
          "summary": "Exactly one of g and t",
          "value": {
           "error": "give exactly one of g and t",
           "code": "invalid_param",
           "field": "t"
          }
         },
         "bad_neither": {
          "summary": "Exactly one of g and t",
          "value": {
           "error": "give exactly one of g and t",
           "code": "invalid_param",
           "field": "t"
          }
         },
         "bad_draw": {
          "summary": "shapes or primitives",
          "value": {
           "error": "draw must be shapes or primitives",
           "code": "invalid_param",
           "field": "draw"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Outside the retained window.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_outside_window": {
          "summary": "A time with no retained frame",
          "value": {
           "error": "time 5.000 is not retained",
           "code": "not_retained",
           "field": "t",
           "retained": {
            "session": 1794353523,
            "g0": 6386,
            "g1": 6410,
            "t0": 1277.2,
            "t1": 1282.0,
            "n": 25
           }
          }
         }
        }
       }
      }
     },
     "410": {
      "description": "The session asked for has ended.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_session_gone": {
          "summary": "Protects a reader from another viewer's seek",
          "value": {
           "error": "session 1794353000 has ended",
           "code": "session_gone",
           "field": "session"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Per-IP render budget (60 per second).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_too_fast": {
          "summary": "A tight loop drains the bucket",
          "description": "seq 180 | xargs -P 16 -I{} curl -s -o /dev/null -w '%{http_code}\\n' 'http://HOST:8120/api/v2/session/render/overlay2d?g=6389' | sort | uniq -c",
          "value": {
           "error": "too many requests",
           "code": "too_many_requests",
           "retry_ms": 500
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "The render queue is full. Renders share it with `/render/scene3d` and the frame rasters. While the render host restarts, the answer is `not_ready`.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_busy": {
          "summary": "More than 32 renders queued",
          "value": {
           "error": "the render queue is full",
           "code": "busy",
           "retry_ms": 200
          }
         }
        }
       }
      }
     }
    },
    "x-level": "mid",
    "x-sdk": {
     "go": "c.API().RenderOverlay2D(ctx, …)",
     "python": "await factory.api.render_overlay2d(…)",
     "rust": "factory.api().render_overlay2d(…).await",
     "typescript": "await factory.api.renderOverlay2d(…)"
    }
   }
  },
  "/api/v2/session/render/scene3d": {
   "get": {
    "operationId": "renderScene3d",
    "tags": [
     "Render-ready"
    ],
    "summary": "Everything the 3-D view draws, final, at a grid frame or any retained time.",
    "description": "Final world coordinates; the observed surface as an explicit mesh by default. Give exactly one of `g` and `t`.\n\n**SDK** · Go `c.API().RenderScene3D(ctx, …)` · Python `await factory.api.render_scene3d(…)` · Rust `factory.api().render_scene3d(…).await` · TypeScript `await factory.api.renderScene3d(…)`",
    "parameters": [
     {
      "$ref": "#/components/parameters/RenderG"
     },
     {
      "$ref": "#/components/parameters/RenderT"
     },
     {
      "$ref": "#/components/parameters/RenderMode"
     },
     {
      "$ref": "#/components/parameters/RenderDraw"
     },
     {
      "$ref": "#/components/parameters/RenderSurface"
     },
     {
      "$ref": "#/components/parameters/SessionGuard"
     }
    ],
    "responses": {
     "200": {
      "description": "The scene, in world coordinates.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Scene3D"
        },
        "examples": {
         "ok_mesh": {
          "summary": "With the surface as vertices and indices",
          "value": {
           "schema": "r3d1",
           "session": 1794353523,
           "video": "aug28",
           "g": 6389,
           "bg": 6390,
           "f": 0,
           "t": 1277.8,
           "mode": "stable",
           "camera": {
            "K": [
             [
              1104.506,
              0,
              544.047
             ],
             [
              0,
              1094.323,
              512.985
             ],
             [
              0,
              0,
              1
             ]
            ],
            "R_c2w": [
             [
              0.936803,
              0.025786,
              -0.348905
             ],
             [
              0.002448,
              -0.997739,
              -0.067166
             ],
             [
              -0.349848,
              0.062068,
              -0.934748
             ]
            ],
            "t_c2w": [
             0.16251,
             -0.00974,
             2.42157
            ],
            "native_wh": [
             1088,
             1026
            ],
            "centre": [
             0.16251,
             -0.00974,
             2.4216
            ]
           },
           "plane": {
            "n": [
             -0.3498,
             0.0621,
             -0.9347
            ],
            "d": -2.4216,
            "floor": -0.8458
           },
           "board": {
            "cx": -1.1755,
            "cy": -0.4326,
            "theta": 1.4556,
            "hw": 0.9168,
            "hh": 0.6683
           },
           "stones": [
            {
             "id": 72,
             "family": "dogbone",
             "pos": [
              -1.2055,
              -0.2421,
              0.2159
             ],
             "q": [
              -0.40383,
              0.40732,
              -0.58172,
              0.57673
             ],
             "dims": [
              0.3084,
              0.235,
              0.093
             ],
             "side": "right",
             "alpha": 1,
             "uncertain": false
            }
           ],
           "skeleton": {
            "joints": [
             [
              -1.093,
              0.165,
              0.686
             ],
             null
            ],
            "bones": [
             {
              "a": 13,
              "b": 11,
              "side": "body",
              "hand": false
             }
            ],
            "rings": [
             {
              "side": "left",
              "pos": [
               -0.651,
               0.031,
               0.158
              ]
             },
             {
              "side": "right",
              "pos": [
               -1.319,
               -0.187,
               0.303
              ]
             }
            ]
           },
           "surface": {
            "form": "vertices",
            "rows": 40,
            "cols": 64,
            "positions": "6GgEwDe0hj8g...",
            "indices": "AABAAEEAQQBA...",
            "opacity": 0.5
           },
           "focus": null
          }
         },
         "ok_no_surface": {
          "summary": "Stones and skeleton only",
          "value": {
           "schema": "r3d1",
           "session": 1794353523,
           "video": "aug28",
           "g": 6389,
           "bg": 6390,
           "f": 0.5,
           "t": 1277.9,
           "mode": "stable",
           "camera": {
            "native_wh": [
             1088,
             1026
            ]
           },
           "plane": {
            "n": [
             -0.3498,
             0.0621,
             -0.9347
            ],
            "d": -2.4216,
            "floor": -0.8458
           },
           "board": {
            "cx": -1.1755,
            "cy": -0.4326,
            "theta": 1.4556,
            "hw": 0.9168,
            "hh": 0.6683
           },
           "stones": [
            {
             "id": 72,
             "family": "dogbone",
             "pos": [
              -1.2403,
              -0.1779,
              0.2361
             ],
             "q": [
              -0.40316,
              0.40798,
              -0.58266,
              0.57578
             ],
             "dims": [
              0.3084,
              0.235,
              0.093
             ],
             "side": "right",
             "alpha": 1,
             "uncertain": false
            }
           ],
           "skeleton": {
            "joints": [],
            "bones": [],
            "rings": []
           },
           "surface": null,
           "focus": null
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_surface": {
          "summary": "vertices, compact or none",
          "value": {
           "error": "surface must be vertices, compact or none",
           "code": "invalid_param",
           "field": "surface"
          }
         },
         "bad_mode": {
          "summary": "stable or raw",
          "value": {
           "error": "mode must be stable or raw",
           "code": "invalid_param",
           "field": "mode"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Outside the retained window.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_outside_window": {
          "summary": "A frame that is not retained",
          "value": {
           "error": "frame 1 is not retained",
           "code": "not_retained",
           "field": "g",
           "retained": {
            "session": 1794353523,
            "g0": 6386,
            "g1": 6410,
            "t0": 1277.2,
            "t1": 1282.0,
            "n": 25
           }
          }
         }
        }
       }
      }
     },
     "410": {
      "description": "The session asked for has ended.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_session_gone": {
          "summary": "Protects a reader from another viewer's seek",
          "value": {
           "error": "session 1794353000 has ended",
           "code": "session_gone",
           "field": "session"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Per-IP render budget (60 per second).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_too_fast": {
          "summary": "A tight loop drains the bucket",
          "description": "seq 180 | xargs -P 16 -I{} curl -s -o /dev/null -w '%{http_code}\\n' 'http://HOST:8120/api/v2/session/render/scene3d?g=6389&surface=none' | sort | uniq -c",
          "value": {
           "error": "too many requests",
           "code": "too_many_requests",
           "retry_ms": 500
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "The render queue is full. Renders share it with `/render/overlay2d` and the frame rasters. While the render host restarts, the answer is `not_ready`.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_busy": {
          "summary": "More than 32 renders queued",
          "value": {
           "error": "the render queue is full",
           "code": "busy",
           "retry_ms": 200
          }
         }
        }
       }
      }
     }
    },
    "x-level": "mid",
    "x-sdk": {
     "go": "c.API().RenderScene3D(ctx, …)",
     "python": "await factory.api.render_scene3d(…)",
     "rust": "factory.api().render_scene3d(…).await",
     "typescript": "await factory.api.renderScene3d(…)"
    }
   }
  },
  "/api/v2/session/frames/{g}": {
   "get": {
    "operationId": "getFrame",
    "tags": [
     "Frames and codec"
    ],
    "summary": "Random access to a retained frame.",
    "parameters": [
     {
      "$ref": "#/components/parameters/GridFrameOrLatest"
     },
     {
      "$ref": "#/components/parameters/Layers"
     },
     {
      "$ref": "#/components/parameters/SessionGuard"
     },
     {
      "$ref": "#/components/parameters/Precision"
     }
    ],
    "responses": {
     "200": {
      "description": "The frame.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Frame"
        },
        "examples": {
         "ok_carry_world": {
          "summary": "The cleaned-up world at the lift",
          "value": {
           "cursor": 918,
           "session": 1794353523,
           "video": "aug28",
           "g": 6389,
           "i": 76668,
           "t": 1277.8,
           "past_valid": true,
           "dt_past": 0.6,
           "world": {
            "schema": "stw1",
            "session": 1794353523,
            "video": "aug28",
            "g": 6389,
            "t": 1277.8,
            "motion": "static",
            "logF": -0.08459,
            "stones": [
             {
              "id": 72,
              "mode": "carry",
              "family": "dogbone",
              "shape": "model",
              "detected": false,
              "uncertain": false,
              "side": "right",
              "outline": [
               [
                372.05,
                474.42
               ],
               [
                372.11,
                497.61
               ],
               [
                362.88,
                511.3
               ]
              ],
              "solid": {
               "pos": [
                -1.2055,
                -0.2421,
                0.2159
               ],
               "q": [
                -0.40383,
                0.40732,
                -0.58172,
                0.57673
               ],
               "dims": [
                0.3084,
                0.235,
                0.093
               ]
              }
             },
             {
              "id": 39,
              "mode": "kept",
              "family": "dogbone",
              "shape": "model",
              "detected": false,
              "uncertain": true,
              "side": null,
              "outline": [
               [
                217.48,
                248.44
               ],
               [
                217.58,
                270.08
               ],
               [
                208.88,
                281.77
               ]
              ],
              "solid": {
               "pos": [
                -1.6785,
                0.334,
                0.0465
               ],
               "q": [
                0,
                0,
                -0.71353,
                0.70062
               ],
               "dims": [
                0.297,
                0.2192,
                0.093
               ]
              }
             }
            ],
            "hands": {
             "left": {
              "state": "touch",
              "stone": null,
              "rayK": 0.998055
             },
             "right": {
              "state": "carry",
              "stone": 72,
              "rayK": 0.983232
             }
            },
            "events": [
             {
              "type": "lift",
              "id": 72,
              "side": "right"
             },
             {
              "type": "carry",
              "id": 72,
              "side": "right"
             },
             {
              "type": "push",
              "id": 63,
              "side": "left"
             }
            ],
            "stats": {
             "stones": 33,
             "confirmed": 33,
             "frozen": 0,
             "fitted": 3,
             "held": 1,
             "stepMs": 4.2
            },
            "draw": {
             "board": {
              "cx": -1.1755,
              "cy": -0.4326,
              "theta": 1.4556,
              "hw": 0.9168,
              "hh": 0.6683
             },
             "skeleton": {
              "logF": -0.084593,
              "k": {
               "left": 0.998055,
               "right": 0.983232
              },
              "elbow": {
               "left": [
                0.00153,
                -0.0016,
                -0.00223
               ],
               "right": [
                0.02213,
                -0.02741,
                0.00364
               ]
              }
             }
            },
            "focus": {
             "id": 72,
             "path2d": [
              [
               335.1,
               540.2
              ]
             ],
             "path3d": [
              [
               -1.21,
               -0.24,
               0.26
              ]
             ]
            }
           }
          }
         },
         "ok_revised": {
          "summary": "Random access answers with the newest world revision",
          "description": "A paused frame refined by the Stable sim (fixer thin-v1): `world.rev` is the revision, its events those of that revision. Here dry2 g 2953 at rev 5, with two stones the model never boxed (`source: image`).",
          "value": {
           "cursor": 72,
           "session": 1794446896,
           "video": "dry2",
           "g": 2953,
           "i": 5906,
           "t": 588.956667,
           "past_valid": true,
           "dt_past": 0.598333,
           "world": {
            "schema": "stw1",
            "session": 1794446896,
            "video": "dry2",
            "g": 2953,
            "t": 588.956667,
            "motion": "static",
            "logF": 0.0191,
            "stones": [
             {
              "id": 1,
              "mode": "seen",
              "family": "rect",
              "shape": "provisional",
              "detected": true,
              "uncertain": false,
              "side": null,
              "outline": [
               [
                1021.71,
                389.7
               ],
               [
                1022.57,
                498.31
               ],
               [
                951.32,
                498.88
               ],
               [
                950.46,
                390.26
               ]
              ],
              "solid": {
               "pos": [
                -0.2274,
                -0.1582,
                0.046
               ],
               "q": [
                0,
                0,
                -0.702,
                0.71218
               ],
               "dims": [
                0.219,
                0.1469,
                0.092
               ]
              }
             },
             {
              "id": 41,
              "mode": "kept",
              "family": "rect",
              "shape": "provisional",
              "detected": false,
              "uncertain": false,
              "side": null,
              "outline": [
               [
                1845.38,
                504.43
               ],
               [
                1845.38,
                616.65
               ],
               [
                1736.55,
                616.65
               ],
               [
                1736.55,
                504.43
               ]
              ],
              "solid": {
               "pos": [
                1.2476,
                -0.3594,
                0.046
               ],
               "q": [
                0,
                0,
                -0.68198,
                0.73138
               ],
               "dims": [
                0.2152,
                0.1936,
                0.092
               ]
              },
              "source": "image"
             }
            ],
            "hands": {
             "left": {
              "state": "free",
              "stone": null
             },
             "right": {
              "state": "free",
              "stone": null
             }
            },
            "events": [
             {
              "type": "new",
              "id": 41,
              "source": "image"
             },
             {
              "type": "confirm",
              "id": 41
             },
             {
              "type": "new",
              "id": 42,
              "source": "image"
             },
             {
              "type": "confirm",
              "id": 42
             }
            ],
            "stats": {
             "stones": 42,
             "confirmed": 42,
             "frozen": 0,
             "fitted": 42,
             "held": 0,
             "stepMs": 2.5
            },
            "draw": {
             "board": {
              "cx": 0.5277,
              "cy": -0.7033,
              "theta": -0.0313,
              "hw": 0.8341,
              "hh": 0.7407
             },
             "skeleton": {
              "logF": 0.0191,
              "k": {
               "left": 1,
               "right": 1
              },
              "elbow": {
               "left": [
                0,
                0,
                0
               ],
               "right": [
                0,
                0,
                0
               ]
              }
             }
            },
            "focus": null,
            "rev": 5
           }
          }
         },
         "ok_latest": {
          "summary": "The newest frame",
          "value": {
           "cursor": 941,
           "session": 1794353523,
           "video": "aug28",
           "g": 6410,
           "i": 76920,
           "t": 1282.0,
           "past_valid": true,
           "dt_past": 0.6,
           "cards": {
            "schema": "crd1",
            "left": {
             "title": "Hand on a stone",
             "tone": "interact",
             "visible": true,
             "pInteraction": 0.988,
             "contact": 0.997,
             "contactOn": true,
             "held": "empty",
             "pHeld": 0.929,
             "action": "hold_stone",
             "fine": [
              {
               "key": "not_interacting",
               "label": "not interacting",
               "p": 0.012,
               "reliable": true
              },
              {
               "key": "hold_stone",
               "label": "hold stone",
               "p": 0.922,
               "reliable": true
              }
             ],
             "hint": null,
             "stone": -1,
             "pWrist": 1.0
            },
            "right": {
             "title": "Holding a stone",
             "tone": "hold",
             "visible": true,
             "pInteraction": 0.991,
             "contact": 0.996,
             "contactOn": true,
             "held": "stone",
             "pHeld": 0.9,
             "action": "hold_stone",
             "fine": [
              {
               "key": "not_interacting",
               "label": "not interacting",
               "p": 0.009,
               "reliable": true
              },
              {
               "key": "hold_stone",
               "label": "hold stone",
               "p": 0.801,
               "reliable": true
              }
             ],
             "hint": null,
             "stone": -1,
             "pWrist": 1.0
            },
            "stage": {
             "parts": [
              {
               "key": "decode",
               "label": "decode",
               "fam": "I",
               "ms": 0.9
              },
              {
               "key": "encoder",
               "label": "encoder",
               "fam": "E",
               "ms": 34.4
              },
              {
               "key": "regions",
               "label": "R regions",
               "fam": "R",
               "ms": 3.4
              },
              {
               "key": "hands",
               "label": "H hands",
               "fam": "H",
               "ms": 9.6
              },
              {
               "key": "stones",
               "label": "S stones",
               "fam": "S",
               "ms": 7.1
              },
              {
               "key": "temporal",
               "label": "T temporal",
               "fam": "T",
               "ms": 0.7
              }
             ],
             "total": 57.8,
             "fps": 17.3
            },
            "numbers": {
             "stones": 23,
             "past_valid": true,
             "dt_past": 0.6,
             "tray_anchor": "prior",
             "floor_anchor": "ankles",
             "depth_anchor": "board",
             "g": 6389,
             "t": 1277.8,
             "session": 1794353523
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_unknown_layer": {
          "summary": "Not a layer",
          "value": {
           "error": "unknown layer 'foo'",
           "code": "unknown_layer",
           "field": "layers"
          }
         },
         "bad_precision": {
          "summary": "rounded or full",
          "value": {
           "error": "precision must be rounded or full",
           "code": "invalid_param",
           "field": "precision"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not retained.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_not_retained": {
          "summary": "Outside the retained window",
          "value": {
           "error": "frame 0 is not retained",
           "code": "not_retained",
           "field": "g",
           "retained": {
            "session": 1794353523,
            "g0": 6386,
            "g1": 6410,
            "t0": 1277.2,
            "t1": 1282.0,
            "n": 25
           }
          }
         }
        }
       }
      }
     },
     "410": {
      "description": "The session asked for has ended.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_session_gone": {
          "summary": "Protects a reader from another viewer's seek",
          "value": {
           "error": "session 1794353000 has ended",
           "code": "session_gone",
           "field": "session"
          }
         }
        }
       }
      }
     }
    },
    "x-level": "low",
    "x-sdk": {
     "go": "c.API().GetFrame(ctx, …)",
     "python": "await factory.api.get_frame(…)",
     "rust": "factory.api().get_frame(…).await",
     "typescript": "await factory.api.getFrame(…)"
    },
    "description": "Random access to a retained frame.\n\n**SDK** · Go `c.API().GetFrame(ctx, …)` · Python `await factory.api.get_frame(…)` · Rust `factory.api().get_frame(…).await` · TypeScript `await factory.api.getFrame(…)`"
   }
  },
  "/api/v2/session/frames/{g}/{raster}.png": {
   "get": {
    "operationId": "getFrameRaster",
    "tags": [
     "Frames and codec"
    ],
    "summary": "A retained frame's map as a PNG, coloured with the portal's own ramps.",
    "description": "`regions`: tray, stones and human composited. `mask`: the person-crop label map. `depth`: the depth map as grey.\n\n**SDK** · Go `c.API().GetFrameRaster(ctx, …)` · Python `await factory.api.get_frame_raster(…)` · Rust `factory.api().get_frame_raster(…).await` · TypeScript `await factory.api.getFrameRaster(…)`",
    "parameters": [
     {
      "$ref": "#/components/parameters/GridFrame"
     },
     {
      "name": "raster",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "regions",
        "mask",
        "depth"
       ]
      },
      "examples": {
       "ok_regions": {
        "value": "regions",
        "summary": "The region overlay"
       },
       "bad_unknown_raster": {
        "value": "heat",
        "summary": "Not a raster"
       }
      }
     },
     {
      "name": "scale",
      "in": "query",
      "description": "Nearest-neighbour upscale.",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 8,
       "default": 1
      },
      "examples": {
       "ok_scale_8": {
        "value": 8,
        "summary": "512 x 320 px"
       },
       "bad_scale": {
        "value": 99,
        "summary": "Too large"
       }
      }
     }
    ],
    "responses": {
     "200": {
      "description": "A PNG (64 x 40 times scale).",
      "content": {
       "image/png": {
        "schema": {
         "type": "string",
         "format": "binary"
        },
        "examples": {
         "ok_regions": {
          "summary": "Regions at 8x",
          "value": "<PNG>"
         },
         "ok_mask": {
          "summary": "The person mask",
          "value": "<PNG>"
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_scale": {
          "summary": "scale is 1..8",
          "value": {
           "error": "scale must be within 1..8",
           "code": "invalid_param",
           "field": "scale"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Unknown raster, or not retained.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_unknown_raster": {
          "summary": "Not a raster",
          "value": {
           "error": "unknown raster 'heat'",
           "code": "not_found",
           "field": "raster"
          }
         },
         "bad_not_retained": {
          "summary": "Outside the retained window",
          "value": {
           "error": "frame 0 is not retained",
           "code": "not_retained",
           "field": "g",
           "retained": {
            "session": 1794353523,
            "g0": 6386,
            "g1": 6410,
            "t0": 1277.2,
            "t1": 1282.0,
            "n": 25
           }
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "The render queue is full. Rasters share it with the renders of `/render/overlay2d` and `/render/scene3d`. While the render host restarts, the answer is `not_ready`.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_busy": {
          "summary": "More than 32 renders and rasters queued",
          "value": {
           "error": "the render queue is full",
           "code": "busy",
           "retry_ms": 200
          }
         }
        }
       }
      }
     }
    },
    "x-level": "low",
    "x-sdk": {
     "go": "c.API().GetFrameRaster(ctx, …)",
     "python": "await factory.api.get_frame_raster(…)",
     "rust": "factory.api().get_frame_raster(…).await",
     "typescript": "await factory.api.getFrameRaster(…)"
    }
   }
  },
  "/api/v2/raw/packets/{g}": {
   "get": {
    "operationId": "rawPacket",
    "tags": [
     "Frames and codec"
    ],
    "summary": "One raw packet of the retained window.",
    "parameters": [
     {
      "$ref": "#/components/parameters/GridFrameOrLatest"
     },
     {
      "$ref": "#/components/parameters/SessionGuard"
     }
    ],
    "responses": {
     "200": {
      "description": "The packet.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Sip1Packet"
        },
        "examples": {
         "ok_carry": {
          "summary": "aug28 g 6389, a stone being lifted",
          "value": {
           "schema": "sip1",
           "maps": {
            "grid": [
             40,
             64
            ],
            "human": "eJztlF9IU1Ecx3fPuefce3ev...",
            "tray": "eJyVln1MW1UUwLn33XdfaQvC...",
            "stone": "eJyNVmlMVUcUvrPd5e3vwVt8...",
            "conf": "eJyNVnlsFFUY33fNmzc7M3vM..."
           },
           "depth": {
            "q": "eJwlVnlU2lcW7pm2Z+a002am...",
            "lo": -3.1111,
            "hi": 2.7123,
            "a": 0.0233,
            "b": 1.0063,
            "anchor": "board"
           },
           "boxes": {
            "stone": [
             0.1014,
             0.0848,
             0.6408,
             1.0,
             true,
             0.999
            ],
            "person": [
             0.0,
             0.0,
             0.9412,
             0.6238,
             false,
             0.999
            ],
            "hand_left": [
             0.5232,
             0.4347,
             0.735
            ],
            "hand_right": [
             0.2374,
             0.5126,
             0.871
            ]
           },
           "person": {
            "present": true,
            "box": [
             0.0,
             0.0,
             0.9412,
             0.6238
            ],
            "rot": false,
            "grid": [
             40,
             64
            ],
            "mask": "eJzl1dEKgDAIhWGn7//OUVdr...",
            "alpha": "eJyllctr1EAYwOex2TRbl0Ur...",
            "joints": [
             [
              0.2191,
              0.3371,
              1.0,
              -0.568,
              -0.314,
              2.049
             ],
             [
              0.2159,
              0.3363,
              1.0,
              -0.555,
              -0.304,
              1.978
             ],
             null
            ],
            "scale": 0.029,
            "bones_used": 48,
            "person_scale": 1.3087,
            "scale_anchor": "contact-now"
           },
           "stones": {
            "present": true,
            "count": 23,
            "box": [
             0.1014,
             0.0848,
             0.6408,
             1.0
            ],
            "rot": true,
            "grid": [
             40,
             64
            ],
            "fg": "eJyVVmtsFFUUnvuYOzM7s6/u...",
            "tray_grid": [
             20,
             32
            ],
            "tray": "eJxjYEAARkYgZmAQ5mBjZePg...",
            "items": [
             [
              0.1501,
              0.6254,
              0.045,
              0.0886,
              0.557,
              -1.036,
              0.352,
              3.002,
              0.133,
              0.249,
              1.505
             ]
            ]
           },
           "tray": {
            "valid": true,
            "normal": [
             -0.3498,
             0.0621,
             -0.9347
            ],
            "d": -2.4216,
            "anchor": "prior",
            "floor": -0.8458,
            "floor_anchor": "ankles"
           },
           "hands": {
            "left": {
             "visible": true,
             "p_interaction": 0.988,
             "action": "hold_stone",
             "p_action": [
              0.012,
              0.017,
              0.015,
              0.019,
              0.922,
              0.015
             ],
             "contact": 0.997,
             "held": "empty",
             "p_held": [
              0.929,
              0.024,
              0.023,
              0.024
             ],
             "p_hold": 0.922,
             "stone": -1,
             "wrist": [
              0.4936,
              0.3798
             ],
             "p_wrist": 1.0
            },
            "right": {
             "visible": true,
             "p_interaction": 0.991,
             "action": "hold_stone",
             "p_action": [
              0.009,
              0.087,
              0.013,
              0.077,
              0.801,
              0.012
             ],
             "contact": 0.996,
             "held": "stone",
             "p_held": [
              0.049,
              0.9,
              0.024,
              0.027
             ],
             "p_hold": 0.801,
             "stone": -1,
             "wrist": [
              0.2178,
              0.4737
             ],
             "p_wrist": 1.0
            }
           },
           "both": 0.297,
           "session": 1794353523,
           "video": "aug28",
           "g": 6389,
           "i": 76668,
           "t": 1277.8,
           "past_valid": true,
           "dt_past": 0.6,
           "ms": {
            "decode": 0.9,
            "encoder": 34.4,
            "regions": 3.4,
            "hands": 9.6,
            "stones": 7.1,
            "temporal": 0.7,
            "total": 57.8
           },
           "cursor": 918
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_g_not_a_number": {
          "summary": "g is an integer or latest",
          "value": {
           "error": "g must be an integer or latest",
           "code": "invalid_param",
           "field": "g"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not retained.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_not_retained": {
          "summary": "Outside the retained window",
          "value": {
           "error": "frame 0 is not retained",
           "code": "not_retained",
           "field": "g",
           "retained": {
            "session": 1794353523,
            "g0": 6386,
            "g1": 6410,
            "t0": 1277.2,
            "t1": 1282.0,
            "n": 25
           }
          }
         }
        }
       }
      }
     },
     "410": {
      "description": "The session asked for has ended.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_session_gone": {
          "summary": "Another viewer seeked since",
          "value": {
           "error": "session 1794353000 has ended",
           "code": "session_gone",
           "field": "session"
          }
         }
        }
       }
      }
     }
    },
    "x-level": "low",
    "x-sdk": {
     "go": "c.API().RawPacket(ctx, …)",
     "python": "await factory.api.raw_packet(…)",
     "rust": "factory.api().raw_packet(…).await",
     "typescript": "await factory.api.rawPacket(…)"
    },
    "description": "One raw packet of the retained window.\n\n**SDK** · Go `c.API().RawPacket(ctx, …)` · Python `await factory.api.raw_packet(…)` · Rust `factory.api().raw_packet(…).await` · TypeScript `await factory.api.rawPacket(…)`"
   }
  },
  "/api/v2/raw/tensors/{g}": {
   "get": {
    "operationId": "rawTensors",
    "tags": [
     "Frames and codec"
    ],
    "summary": "The 20 model output tensors and the encoder's RGB input for one frame.",
    "description": "Debug only. An `.npz` of `PACKET_OUTPUTS` plus `rgb`. Available when the worker runs with `--debug-tensors N`; the newest N frames are kept.\n\n**SDK** · Go `c.API().RawTensors(ctx, …)` · Python `await factory.api.raw_tensors(…)` · Rust `factory.api().raw_tensors(…).await` · TypeScript `await factory.api.rawTensors(…)`",
    "parameters": [
     {
      "$ref": "#/components/parameters/GridFrame"
     }
    ],
    "responses": {
     "200": {
      "description": "An npz archive (190,884 B of tensors plus RGB).",
      "content": {
       "application/octet-stream": {
        "schema": {
         "type": "string",
         "format": "binary"
        },
        "examples": {
         "ok_npz": {
          "summary": "Asset C2 for backend-parity tests",
          "value": "<npz archive>"
         }
        }
       }
      }
     },
     "400": {
      "description": "Bad parameter.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_g_not_a_number": {
          "summary": "g is an integer",
          "value": {
           "error": "g must be an integer",
           "code": "invalid_param",
           "field": "g"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Off, or not kept.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_debug_disabled": {
          "summary": "The worker keeps no tensors",
          "value": {
           "error": "tensor capture is not enabled",
           "code": "debug_disabled"
          }
         }
        }
       }
      }
     }
    },
    "x-level": "low",
    "x-sdk": {
     "go": "c.API().RawTensors(ctx, …)",
     "python": "await factory.api.raw_tensors(…)",
     "rust": "factory.api().raw_tensors(…).await",
     "typescript": "await factory.api.rawTensors(…)"
    }
   }
  },
  "/api/v2": {
   "get": {
    "operationId": "getApiRoot",
    "tags": [
     "Meta"
    ],
    "summary": "Entry point with links, layer schema ids, limits and the build.",
    "responses": {
     "200": {
      "description": "The entry point.",
      "headers": {
       "X-Interp-Build": {
        "$ref": "#/components/headers/XInterpBuild"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ApiRoot"
        },
        "examples": {
         "ok_entry_point": {
          "summary": "Links, schema ids and limits",
          "value": {
           "api": "2.0.0",
           "build": "2026.11.11-7c1ad02",
           "boot": "b7f3a2c1",
           "backend": "trt",
           "spec": "/api/v2/openapi.yaml",
           "docs": "/api/docs/",
           "layers": {
            "raw": "sip1",
            "overlay": "ovl1",
            "scene": "scn1",
            "cards": "crd1",
            "world": "stw1"
           },
           "render": {
            "overlay2d": "r2d1",
            "scene3d": "r3d1"
           },
           "limits": {
            "retained_frames": 512,
            "reply_frames": 8,
            "max_reply_frames": 16,
            "max_streams": 32,
            "long_poll_ms": 1000,
            "control_body_bytes": 512
           },
           "docs_policy": {
            "force_dry_run": true
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "meta",
    "x-sdk": {
     "go": "c.API().GetAPIRoot(ctx, …)",
     "python": "await factory.api.get_api_root(…)",
     "rust": "factory.api().get_api_root(…).await",
     "typescript": "await factory.api.getApiRoot(…)"
    },
    "description": "Entry point with links, layer schema ids, limits and the build.\n\n**SDK** · Go `c.API().GetAPIRoot(ctx, …)` · Python `await factory.api.get_api_root(…)` · Rust `factory.api().get_api_root(…).await` · TypeScript `await factory.api.getApiRoot(…)`"
   }
  },
  "/api/v2/openapi.yaml": {
   "get": {
    "operationId": "getOpenApi",
    "tags": [
     "Meta"
    ],
    "summary": "This specification.",
    "responses": {
     "200": {
      "description": "The OpenAPI 3.1 document.",
      "content": {
       "application/yaml": {
        "schema": {
         "type": "string"
        },
        "examples": {
         "ok_spec": {
          "summary": "The first lines",
          "value": "openapi: 3.1.0\ninfo:\n  title: Stone-work interpreter API\n"
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "meta",
    "x-sdk": {
     "go": "c.API().GetOpenAPI(ctx, …)",
     "python": "await factory.api.get_openapi(…)",
     "rust": "factory.api().get_openapi(…).await",
     "typescript": "await factory.api.getOpenApi(…)"
    },
    "description": "This specification.\n\n**SDK** · Go `c.API().GetOpenAPI(ctx, …)` · Python `await factory.api.get_openapi(…)` · Rust `factory.api().get_openapi(…).await` · TypeScript `await factory.api.getOpenApi(…)`"
   }
  },
  "/api/v2/model": {
   "get": {
    "operationId": "getModel",
    "tags": [
     "Meta"
    ],
    "summary": "The model that is running, with engine hashes and INT4 receipts.",
    "responses": {
     "200": {
      "description": "Model identity.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ModelInfo"
        },
        "examples": {
         "ok_orin_engines": {
          "summary": "The Orin's TensorRT engines",
          "value": {
           "schema": "mdl1",
           "checkpoint": "db1b35410858",
           "name": "hand-3D cascade v2 (R regions, H hands & bodies, S stones, T temporal)",
           "stage": "stage 5 best, update 1100",
           "backend": "trt",
           "profile": null,
           "tensorrt": "10.16.2.10",
           "engines": [
            {
             "stage": "encoder-1088",
             "sha256": "eefcff080c55216022a23624f32755e980e597dc45bfb5c01f195b1dafc0f35c",
             "bytes": 124639164,
             "onnx_sha256": "bbac2c41e347bbcf5a715e545ea2ee8f5c95f23922a490219d6bdacf2933be8f",
             "int4_weights": 0,
             "int4_exceptions": 0
            },
            {
             "stage": "hands-w4",
             "sha256": "8cfefa5248d6a4086a8020be547842c16615530500d49b82226feb230e5f87ec",
             "bytes": 9841772,
             "onnx_sha256": "bdcede7a113120ef1a745721c185a4ef39418313f7411578fc5b702195a1eff8",
             "int4_weights": 52,
             "int4_exceptions": 1
            }
           ]
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "meta",
    "x-sdk": {
     "go": "c.API().GetModel(ctx, …)",
     "python": "await factory.api.get_model(…)",
     "rust": "factory.api().get_model(…).await",
     "typescript": "await factory.api.getModel(…)"
    },
    "description": "The model that is running, with engine hashes and INT4 receipts.\n\n**SDK** · Go `c.API().GetModel(ctx, …)` · Python `await factory.api.get_model(…)` · Rust `factory.api().get_model(…).await` · TypeScript `await factory.api.getModel(…)`"
   }
  },
  "/api/v2/topology": {
   "get": {
    "operationId": "getTopology",
    "tags": [
     "Meta"
    ],
    "summary": "Skeleton topology, class names, palette and coordinate constants.",
    "responses": {
     "200": {
      "description": "Constants a renderer needs once.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Topology"
        },
        "examples": {
         "ok_topology": {
          "summary": "MHR70 joints, bones and colours",
          "value": {
           "schema": "top1",
           "joints": 70,
           "never": [
            15,
            16,
            17,
            18,
            19,
            20,
            63,
            64,
            65,
            66,
            67,
            68
           ],
           "wrist": {
            "left": 62,
            "right": 41
           },
           "tips": {
            "left": [
             42,
             46,
             50,
             54,
             58
            ],
            "right": [
             21,
             25,
             29,
             33,
             37
            ]
           },
           "bones": [
            [
             13,
             11
            ],
            [
             11,
             9
            ],
            [
             14,
             12
            ]
           ],
           "actions": [
            "not_interacting",
            "move_stone",
            "push_stones",
            "pull_out_stone",
            "hold_stone",
            "place_stone"
           ],
           "held": [
            "empty",
            "stone",
            "tool",
            "tray"
           ],
           "colors": {
            "human": "#00e15a",
            "left": "#f68c36",
            "right": "#00b5ff",
            "stones": "#ffd60a",
            "tray": "#00dcff",
            "focus": "#ff4fc8"
           },
           "grid": [
            40,
            64
           ]
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "meta",
    "x-sdk": {
     "go": "c.API().GetTopology(ctx, …)",
     "python": "await factory.api.get_topology(…)",
     "rust": "factory.api().get_topology(…).await",
     "typescript": "await factory.api.getTopology(…)"
    },
    "description": "Skeleton topology, class names, palette and coordinate constants.\n\n**SDK** · Go `c.API().GetTopology(ctx, …)` · Python `await factory.api.get_topology(…)` · Rust `factory.api().get_topology(…).await` · TypeScript `await factory.api.getTopology(…)`"
   }
  },
  "/api/v2/health": {
   "get": {
    "operationId": "getHealth",
    "tags": [
     "Ops"
    ],
    "summary": "Liveness only.",
    "responses": {
     "200": {
      "description": "The process answers.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Health"
        },
        "examples": {
         "ok_alive": {
          "summary": "Up, the worker running",
          "value": {
           "ok": true,
           "worker": "running",
           "viewers": 3
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "ops",
    "x-sdk": {
     "go": "c.API().GetHealth(ctx, …)",
     "python": "await factory.api.get_health(…)",
     "rust": "factory.api().get_health(…).await",
     "typescript": "await factory.api.getHealth(…)"
    },
    "description": "Liveness only.\n\n**SDK** · Go `c.API().GetHealth(ctx, …)` · Python `await factory.api.get_health(…)` · Rust `factory.api().get_health(…).await` · TypeScript `await factory.api.getHealth(…)`"
   }
  },
  "/api/v2/ready": {
   "get": {
    "operationId": "getReady",
    "tags": [
     "Ops"
    ],
    "summary": "Readiness. 503 until the catalog, proxies and hosts are up.",
    "responses": {
     "200": {
      "description": "Ready.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Ready"
        },
        "examples": {
         "ok_ready": {
          "summary": "Everything is up",
          "value": {
           "ready": true,
           "waiting": []
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     },
     "503": {
      "description": "Not ready yet.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "examples": {
         "bad_not_ready": {
          "summary": "During start-up",
          "value": {
           "error": "still starting",
           "code": "not_ready",
           "retry_ms": 500,
           "waiting": [
            "derive"
           ]
          }
         }
        }
       }
      }
     }
    },
    "x-level": "ops",
    "x-sdk": {
     "go": "c.API().GetReady(ctx, …)",
     "python": "await factory.api.get_ready(…)",
     "rust": "factory.api().get_ready(…).await",
     "typescript": "await factory.api.getReady(…)"
    },
    "description": "Readiness. 503 until the catalog, proxies and hosts are up.\n\n**SDK** · Go `c.API().GetReady(ctx, …)` · Python `await factory.api.get_ready(…)` · Rust `factory.api().get_ready(…).await` · TypeScript `await factory.api.getReady(…)`"
   }
  },
  "/api/v2/status": {
   "get": {
    "operationId": "getStatus",
    "tags": [
     "Ops"
    ],
    "summary": "Everything an operator wants on one page.",
    "responses": {
     "200": {
      "description": "Status.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Status"
        },
        "examples": {
         "ok_status": {
          "summary": "Running with one stream open",
          "value": {
           "build": "2026.11.11-7c1ad02",
           "boot": "b7f3a2c1",
           "uptime_s": 3612.4,
           "page": "next",
           "worker": {
            "state": "running",
            "reason": "",
            "fps": 4.0,
            "frame_ms": 57.8,
            "cycle_ms": 59.3,
            "session": 1794353523,
            "g": 6410,
            "gpu": 918,
            "errors": 0,
            "stage_ms": {
             "decode": 0.9,
             "encoder": 34.4,
             "regions": 3.4,
             "hands": 9.6,
             "stones": 7.1,
             "temporal": 0.7,
             "total": 57.8
            },
            "engines": {
             "encoder-1088": "eefcff080c55",
             "encoder-1920": "f07cc6c711d1",
             "regions": "e4f249df07e3",
             "hands": "8cfefa5248d6",
             "stones": "1070e3c22bda",
             "temporal": "768e16042a09"
            },
            "model": "db1b35410858",
            "video": "aug28"
           },
           "retained": {
            "session": 1794353523,
            "g0": 6386,
            "g1": 6410,
            "t0": 1277.2,
            "t1": 1282.0,
            "n": 25
           },
           "stable": {
            "state": "running",
            "fits": 3,
            "evidence": true
           },
           "hosts": {
            "derive": {
             "state": "running",
             "restarts": 0,
             "rss_mb": 96,
             "queue": 0
            },
            "world": {
             "state": "running",
             "restarts": 0,
             "rss_mb": 214,
             "queue": 0
            }
           },
           "memory": {
            "rss_mb": 61
           },
           "viewers": 3,
           "long_polls": 2,
           "streams": 1
          }
         },
         "ok_held": {
          "summary": "Paused, the world host held on the paused frame",
          "description": "Fixer thin-v1, paused on dry2 at 9:49: five rounds of rest refinement shaped the frame on screen (rev 5), then the three packets the worker had interpreted ahead were stepped again from it. With fixer legacy a hold reads `state: off` and nothing is revised.",
          "value": {
           "build": "0.1.0",
           "boot": "5f34a1cd5ea8a4",
           "uptime_s": 18.08,
           "page": "legacy",
           "worker": {
            "state": "running",
            "reason": "",
            "fps": 4.6,
            "frame_ms": 310.8,
            "cycle_ms": 1.2,
            "session": 1794446896,
            "g": 2956,
            "errors": 0,
            "stage_ms": {
             "decode": 0.2,
             "encoder": 84.5,
             "regions": 42.9,
             "hands": 154,
             "stones": 86.5,
             "temporal": 4.4,
             "total": 372.5
            },
            "engines": {
             "encoder-1088": "eefcff080c55",
             "encoder-1920": "f07cc6c711d1",
             "regions": "e4f249df07e3",
             "hands": "8cfefa5248d6",
             "stones": "1070e3c22bda",
             "temporal": "768e16042a09"
            },
            "model": "db1b35410858",
            "video": "dry2"
           },
           "retained": {
            "session": 1794446896,
            "g0": 2950,
            "g1": 2956,
            "t0": 588.358333,
            "t1": 589.555,
            "n": 7
           },
           "stable": {
            "state": "running",
            "fits": 4,
            "evidence": true,
            "fixer": "thin-v1",
            "hold": {
             "session": 1794446896,
             "g": 2953,
             "state": "converged",
             "rounds": 5,
             "rev": 5,
             "ms": 111.6,
             "resteps": 3
            }
           },
           "hosts": {
            "derive": {
             "state": "running",
             "restarts": 0,
             "rss_mb": 92.6,
             "queue": 0
            },
            "world": {
             "state": "running",
             "restarts": 0,
             "rss_mb": 109.9,
             "queue": 0
            }
           },
           "memory": {
            "rss_mb": 17.8
           },
           "viewers": 1,
           "long_polls": 0,
           "streams": 0
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "ops",
    "x-sdk": {
     "go": "c.API().GetStatus(ctx, …)",
     "python": "await factory.api.get_status(…)",
     "rust": "factory.api().get_status(…).await",
     "typescript": "await factory.api.getStatus(…)"
    },
    "description": "Everything an operator wants on one page.\n\n**SDK** · Go `c.API().GetStatus(ctx, …)` · Python `await factory.api.get_status(…)` · Rust `factory.api().get_status(…).await` · TypeScript `await factory.api.getStatus(…)`"
   }
  },
  "/metrics": {
   "get": {
    "operationId": "getMetrics",
    "tags": [
     "Ops"
    ],
    "summary": "Prometheus text exposition.",
    "responses": {
     "200": {
      "description": "Metrics.",
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        },
        "examples": {
         "ok_metrics": {
          "summary": "A few lines",
          "value": "interp_frames_total{video=\"aug28\"} 918\ninterp_cycle_ms 59.3\ninterp_world_ms{phase=\"total\",quantile=\"0.95\"} 62.1\ninterp_viewers 3\n"
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BodyOnGet"
     },
     "405": {
      "$ref": "#/components/responses/MethodNotAllowed"
     }
    },
    "x-level": "ops",
    "x-sdk": {
     "go": "c.API().GetMetrics(ctx, …)",
     "python": "await factory.api.get_metrics(…)",
     "rust": "factory.api().get_metrics(…).await",
     "typescript": "await factory.api.getMetrics(…)"
    },
    "description": "Prometheus text exposition.\n\n**SDK** · Go `c.API().GetMetrics(ctx, …)` · Python `await factory.api.get_metrics(…)` · Rust `factory.api().get_metrics(…).await` · TypeScript `await factory.api.getMetrics(…)`"
   }
  }
 },
 "components": {
  "headers": {
   "XInterpBuild": {
    "description": "The build that answered.",
    "schema": {
     "type": "string"
    }
   },
   "ETag": {
    "description": "Entity tag.",
    "schema": {
     "type": "string"
    }
   },
   "RetryAfter": {
    "description": "Seconds to wait, at least 1.",
    "schema": {
     "type": "integer"
    }
   }
  },
  "parameters": {
   "DryRun": {
    "name": "dry_run",
    "in": "query",
    "description": "1 validates and answers without moving the session. Charged only to the per-IP rate limit.",
    "schema": {
     "type": "integer",
     "enum": [
      0,
      1
     ],
     "default": 0
    },
    "examples": {
     "ok_validate_only": {
      "value": 1,
      "summary": "Validate and answer"
     },
     "ok_apply": {
      "value": 0,
      "summary": "Apply for every viewer"
     }
    }
   },
   "VideoId": {
    "name": "id",
    "in": "path",
    "required": true,
    "description": "Catalog id.",
    "schema": {
     "type": "string"
    },
    "examples": {
     "ok_aug28": {
      "value": "aug28",
      "summary": "Line A 28 Aug"
     },
     "bad_unknown": {
      "value": "nope",
      "summary": "Not in the catalog"
     }
    }
   },
   "Range": {
    "name": "Range",
    "in": "header",
    "description": "A single byte range.",
    "schema": {
     "type": "string"
    },
    "examples": {
     "ok_first_kilobyte": {
      "value": "bytes=0-1023",
      "summary": "The first KiB"
     },
     "bad_past_end": {
      "value": "bytes=99999999999-",
      "summary": "Starts after the end"
     },
     "bad_two_ranges": {
      "value": "bytes=0-1,5-6",
      "summary": "Multiple ranges are not supported"
     }
    }
   },
   "IfRange": {
    "name": "If-Range",
    "in": "header",
    "description": "ETag or Last-Modified of the previous reply.",
    "schema": {
     "type": "string"
    }
   },
   "IfNoneMatch": {
    "name": "If-None-Match",
    "in": "header",
    "description": "ETag of a cached copy.",
    "schema": {
     "type": "string"
    }
   },
   "Cursor": {
    "name": "cursor",
    "in": "query",
    "description": "The last cursor this client has. A value ahead of the server is clamped.",
    "schema": {
     "type": "integer",
     "minimum": 0,
     "default": 0
    },
    "examples": {
     "ok_from_start": {
      "value": 0,
      "summary": "From the newest frames"
     },
     "bad_cursor": {
      "value": "12a",
      "summary": "Not an integer"
     }
    }
   },
   "Rev": {
    "name": "rev",
    "in": "query",
    "description": "The last state revision this client has. 0 returns at once.",
    "schema": {
     "type": "integer",
     "minimum": 0,
     "default": 0
    }
   },
   "Cid": {
    "name": "cid",
    "in": "query",
    "description": "A per-tab id (`^[A-Za-z0-9_-]{8,40}$`). Counts this client as a viewer.",
    "schema": {
     "type": "string",
     "pattern": "^[A-Za-z0-9_-]{8,40}$"
    },
    "examples": {
     "ok_tab_id": {
      "value": "Yz3kPq7LwR2sT9vB",
      "summary": "One id per tab"
     }
    }
   },
   "Layers": {
    "name": "layers",
    "in": "query",
    "description": "Comma-separated subset of `raw`, `overlay`, `scene`, `cards`, `world`. Default `overlay,scene,cards,world`.",
    "schema": {
     "type": "string",
     "default": "overlay,scene,cards,world"
    },
    "examples": {
     "ok_portal_bundle": {
      "value": "overlay,scene,cards,world",
      "summary": "What the portal uses"
     },
     "ok_world": {
      "value": "world",
      "summary": "Only the cleaned-up world"
     },
     "ok_raw": {
      "value": "raw",
      "summary": "The codec packet"
     },
     "bad_unknown_layer": {
      "value": "foo",
      "summary": "Not a layer"
     }
    }
   },
   "Limit": {
    "name": "limit",
    "in": "query",
    "description": "At most this many newest frames per reply.",
    "schema": {
     "type": "integer",
     "minimum": 1,
     "maximum": 16,
     "default": 8
    },
    "examples": {
     "ok_eight": {
      "value": 8,
      "summary": "Same as the legacy long-poll"
     },
     "bad_limit": {
      "value": 99,
      "summary": "Above 16"
     }
    }
   },
   "WaitMs": {
    "name": "wait",
    "in": "query",
    "description": "Longest wait in ms.",
    "schema": {
     "type": "integer",
     "minimum": 0,
     "maximum": 1000,
     "default": 1000
    },
    "examples": {
     "ok_no_wait": {
      "value": 0,
      "summary": "Return at once"
     },
     "bad_wait": {
      "value": 5000,
      "summary": "Above 1000"
     }
    }
   },
   "Precision": {
    "name": "precision",
    "in": "query",
    "description": "`rounded` (default): outline .01 px, solid 1e-4, q 1e-5. `full`: unrounded, for parity runs.",
    "schema": {
     "type": "string",
     "enum": [
      "rounded",
      "full"
     ],
     "default": "rounded"
    },
    "examples": {
     "ok_full": {
      "value": "full",
      "summary": "Unrounded"
     },
     "bad_precision": {
      "value": "exact",
      "summary": "Not a mode"
     }
    }
   },
   "SessionGuard": {
    "name": "session",
    "in": "query",
    "description": "Answer 410 if this is not the current session. Protects a reader from another viewer's seek.",
    "schema": {
     "type": "integer"
    },
    "examples": {
     "ok_current": {
      "value": 1794353523,
      "summary": "The current session"
     },
     "bad_old": {
      "value": 1794353000,
      "summary": "An earlier session"
     }
    }
   },
   "GridFrame": {
    "name": "g",
    "in": "path",
    "required": true,
    "description": "Grid frame index.",
    "schema": {
     "type": "integer",
     "minimum": 0
    },
    "examples": {
     "ok_carry": {
      "value": 6389,
      "summary": "The lift on aug28"
     },
     "bad_not_a_number": {
      "value": "abc",
      "summary": "Not an integer"
     }
    }
   },
   "GridFrameOrLatest": {
    "name": "g",
    "in": "path",
    "required": true,
    "description": "Grid frame index, or `latest`.",
    "schema": {
     "type": "string",
     "pattern": "^(latest|[0-9]{1,10})$"
    },
    "examples": {
     "ok_carry": {
      "value": "6389",
      "summary": "The lift on aug28"
     },
     "ok_latest": {
      "value": "latest",
      "summary": "The newest frame"
     },
     "bad_not_retained": {
      "value": "0",
      "summary": "Outside the retained window"
     },
     "bad_not_a_number": {
      "value": "abc",
      "summary": "Not an integer"
     }
    }
   },
   "After": {
    "name": "after",
    "in": "query",
    "description": "Start after this cursor. Default the newest.",
    "schema": {
     "type": "integer",
     "minimum": 0
    }
   },
   "StreamFormat": {
    "name": "format",
    "in": "query",
    "description": "Overrides the `Accept` header.",
    "schema": {
     "type": "string",
     "enum": [
      "ndjson",
      "sse"
     ]
    },
    "examples": {
     "ok_ndjson": {
      "value": "ndjson",
      "summary": "One JSON document per line"
     },
     "ok_sse": {
      "value": "sse",
      "summary": "Server-sent events"
     },
     "bad_format": {
      "value": "xml",
      "summary": "Not a format"
     }
    }
   },
   "StreamLimit": {
    "name": "limit",
    "in": "query",
    "description": "End the stream after this many frames.",
    "schema": {
     "type": "integer",
     "minimum": 1,
     "maximum": 4096
    },
    "examples": {
     "ok_four": {
      "value": 4,
      "summary": "Four frames and stop"
     },
     "bad_zero": {
      "value": 0,
      "summary": "Below 1"
     }
    }
   },
   "StreamMaxS": {
    "name": "max_s",
    "in": "query",
    "description": "End the stream after this many seconds.",
    "schema": {
     "type": "integer",
     "minimum": 1,
     "maximum": 3600
    },
    "examples": {
     "ok_five": {
      "value": 5,
      "summary": "Five seconds and stop"
     },
     "bad_zero": {
      "value": 0,
      "summary": "Below 1"
     }
    }
   },
   "Observe": {
    "name": "observe",
    "in": "query",
    "description": "1 does not count this consumer as a viewer, so an idle system stays idle.",
    "schema": {
     "type": "integer",
     "enum": [
      0,
      1
     ],
     "default": 0
    }
   },
   "LastEventId": {
    "name": "Last-Event-ID",
    "in": "header",
    "description": "`<boot>-<cursor>` of the last event. An id from another boot gets `reset`.",
    "schema": {
     "type": "string"
    }
   },
   "RenderG": {
    "name": "g",
    "in": "query",
    "description": "A grid frame (exactly one of `g` and `t`).",
    "schema": {
     "type": "integer",
     "minimum": 0
    },
    "examples": {
     "ok_carry": {
      "value": 6389,
      "summary": "The lift on aug28"
     }
    }
   },
   "RenderT": {
    "name": "t",
    "in": "query",
    "description": "A media time in seconds (exactly one of `g` and `t`).",
    "schema": {
     "type": "number",
     "minimum": 0
    },
    "examples": {
     "ok_between_packets": {
      "value": 1277.9,
      "summary": "Half way between two packets"
     },
     "bad_outside_window": {
      "value": 5.0,
      "summary": "No retained frame there"
     }
    }
   },
   "RenderMode": {
    "name": "mode",
    "in": "query",
    "description": "`stable`: the persistent world. `raw`: per-packet detections.",
    "schema": {
     "type": "string",
     "enum": [
      "stable",
      "raw"
     ],
     "default": "stable"
    },
    "examples": {
     "ok_stable": {
      "value": "stable",
      "summary": "The cleaned-up world"
     },
     "ok_raw": {
      "value": "raw",
      "summary": "Raw detections"
     },
     "bad_mode": {
      "value": "best",
      "summary": "Not a mode"
     }
    }
   },
   "RenderDraw": {
    "name": "draw",
    "in": "query",
    "description": "`shapes`: semantic objects. `primitives`: flat lists with resolved styles.",
    "schema": {
     "type": "string",
     "enum": [
      "shapes",
      "primitives"
     ],
     "default": "shapes"
    },
    "examples": {
     "ok_shapes": {
      "value": "shapes",
      "summary": "Stones, skeleton, wrists"
     },
     "ok_primitives": {
      "value": "primitives",
      "summary": "Polygons, segments, circles"
     },
     "bad_draw": {
      "value": "svg",
      "summary": "Not a form"
     }
    }
   },
   "RenderSurface": {
    "name": "surface",
    "in": "query",
    "description": "`vertices`: explicit f32 positions and u16 indices. `compact`: quantised log depth plus masks. `none`: omit.",
    "schema": {
     "type": "string",
     "enum": [
      "vertices",
      "compact",
      "none"
     ],
     "default": "vertices"
    },
    "examples": {
     "ok_vertices": {
      "value": "vertices",
      "summary": "An explicit mesh"
     },
     "ok_none": {
      "value": "none",
      "summary": "Omit the surface"
     },
     "bad_surface": {
      "value": "mesh",
      "summary": "Not a form"
     }
    }
   }
  },
  "examples": {
   "bad_malformed_json": {
    "summary": "Not JSON",
    "value": {
     "error": "invalid JSON",
     "code": "invalid_json"
    }
   },
   "bad_get_with_body": {
    "summary": "A body on GET is refused and the connection closed",
    "description": "curl -X GET --data x http://HOST:8120/api/v2/health",
    "value": {
     "error": "a GET request cannot carry a body",
     "code": "body_not_allowed"
    }
   },
   "bad_method_not_allowed": {
    "summary": "A method the path does not have",
    "value": {
     "error": "method not allowed",
     "code": "method_not_allowed"
    }
   },
   "bad_foreign_origin": {
    "summary": "A cross-origin request",
    "description": "curl -X POST -H 'Origin: http://evil.example' -H 'Content-Type: application/json' -d '{}' http://HOST:8120/api/v2/session/pause",
    "value": {
     "error": "cross-origin control refused",
     "code": "cross_origin"
    }
   },
   "bad_foreign_origin_no_body": {
    "summary": "A cross-origin DELETE",
    "description": "curl -X DELETE -H 'Origin: http://evil.example' http://HOST:8120/api/v2/session/focus",
    "value": {
     "error": "cross-origin control refused",
     "code": "cross_origin"
    }
   },
   "bad_too_large": {
    "summary": "600 bytes",
    "value": {
     "error": "body must be 1..512 bytes",
     "code": "body_too_large"
    }
   },
   "bad_text_plain": {
    "summary": "text/plain",
    "value": {
     "error": "JSON only",
     "code": "json_only"
    }
   },
   "bad_too_soon_session": {
    "summary": "Twice within a second",
    "value": {
     "error": "too many controls; wait a moment",
     "code": "too_many_controls",
     "retry_ms": 800
    }
   },
   "bad_too_soon_play": {
    "summary": "Twice within 0.3 s",
    "value": {
     "error": "too many controls; wait a moment",
     "code": "too_many_controls",
     "retry_ms": 300
    }
   },
   "bad_too_soon_focus": {
    "summary": "Twice within 0.15 s",
    "value": {
     "error": "too many controls; wait a moment",
     "code": "too_many_controls",
     "retry_ms": 150
    }
   },
   "bad_too_soon_focus_no_body": {
    "summary": "Twice within 0.15 s",
    "value": {
     "error": "too many controls; wait a moment",
     "code": "too_many_controls",
     "retry_ms": 150
    }
   }
  },
  "responses": {
   "BodyOnGet": {
    "description": "A GET with a body is refused and the connection closed.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_get_with_body": {
        "$ref": "#/components/examples/bad_get_with_body"
       }
      }
     }
    }
   },
   "MethodNotAllowed": {
    "description": "A method this path does not have.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_method_not_allowed": {
        "$ref": "#/components/examples/bad_method_not_allowed"
       }
      }
     }
    }
   },
   "ForeignOrigin": {
    "description": "A foreign `Origin`.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_foreign_origin": {
        "$ref": "#/components/examples/bad_foreign_origin"
       }
      }
     }
    }
   },
   "ForeignOriginNoBody": {
    "description": "A foreign `Origin`.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_foreign_origin": {
        "$ref": "#/components/examples/bad_foreign_origin_no_body"
       }
      }
     }
    }
   },
   "TooLarge": {
    "description": "Body over 512 bytes.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_too_large": {
        "$ref": "#/components/examples/bad_too_large"
       }
      }
     }
    }
   },
   "NotJson": {
    "description": "Not `application/json`.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_text_plain": {
        "$ref": "#/components/examples/bad_text_plain"
       }
      }
     }
    }
   },
   "TooSoonSession": {
    "description": "select and seek are limited to one per second from anyone, one per 0.8 s per IP.",
    "headers": {
     "Retry-After": {
      "$ref": "#/components/headers/RetryAfter"
     }
    },
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_too_soon": {
        "$ref": "#/components/examples/bad_too_soon_session"
       }
      }
     }
    }
   },
   "TooSoonPlay": {
    "description": "play and pause are limited to one per 0.2 s from anyone, one per 0.3 s per IP.",
    "headers": {
     "Retry-After": {
      "$ref": "#/components/headers/RetryAfter"
     }
    },
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_too_soon": {
        "$ref": "#/components/examples/bad_too_soon_play"
       }
      }
     }
    }
   },
   "TooSoonFocus": {
    "description": "Focus changes are limited to one per 0.1 s from anyone, one per 0.15 s per IP.",
    "headers": {
     "Retry-After": {
      "$ref": "#/components/headers/RetryAfter"
     }
    },
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_too_soon": {
        "$ref": "#/components/examples/bad_too_soon_focus"
       }
      }
     }
    }
   },
   "TooSoonFocusNoBody": {
    "description": "Focus changes are limited to one per 0.1 s from anyone, one per 0.15 s per IP.",
    "headers": {
     "Retry-After": {
      "$ref": "#/components/headers/RetryAfter"
     }
    },
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      },
      "examples": {
       "bad_too_soon": {
        "$ref": "#/components/examples/bad_too_soon_focus_no_body"
       }
      }
     }
    }
   }
  },
  "schemas": {
   "ErrorCode": {
    "type": "string",
    "description": "Stable machine-readable error code.",
    "enum": [
     "invalid_json",
     "not_an_object",
     "chunked_refused",
     "length_required",
     "body_too_large",
     "body_not_allowed",
     "cross_origin",
     "json_only",
     "too_many_controls",
     "too_many_requests",
     "too_many_viewers",
     "too_many_streams",
     "unknown_video",
     "time_out_of_range",
     "invalid_type",
     "missing_field",
     "invalid_param",
     "unknown_layer",
     "not_retained",
     "session_gone",
     "stale_session",
     "unknown_stone",
     "world_unavailable",
     "debug_disabled",
     "busy",
     "not_ready",
     "not_found",
     "method_not_allowed",
     "internal",
     "not_seekable"
    ]
   },
   "Retained": {
    "type": "object",
    "description": "The retained frame window of the current session.",
    "required": [
     "session",
     "n"
    ],
    "properties": {
     "session": {
      "type": "integer"
     },
     "g0": {
      "type": [
       "integer",
       "null"
      ]
     },
     "g1": {
      "type": [
       "integer",
       "null"
      ]
     },
     "t0": {
      "type": [
       "number",
       "null"
      ]
     },
     "t1": {
      "type": [
       "number",
       "null"
      ]
     },
     "n": {
      "type": "integer",
      "minimum": 0,
      "maximum": 512
     }
    }
   },
   "Error": {
    "type": "object",
    "required": [
     "error",
     "code"
    ],
    "properties": {
     "error": {
      "type": "string",
      "description": "Human-readable."
     },
     "code": {
      "$ref": "#/components/schemas/ErrorCode"
     },
     "retry_ms": {
      "type": "integer",
      "minimum": 0
     },
     "field": {
      "type": "string",
      "description": "The parameter or body field at fault."
     },
     "retained": {
      "$ref": "#/components/schemas/Retained"
     },
     "waiting": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "ApiRoot": {
    "type": "object",
    "required": [
     "api",
     "build",
     "boot",
     "layers",
     "render",
     "spec",
     "docs"
    ],
    "properties": {
     "api": {
      "type": "string"
     },
     "build": {
      "type": "string"
     },
     "boot": {
      "type": "string",
      "description": "Changes with every process start."
     },
     "backend": {
      "type": "string",
      "enum": [
       "trt",
       "ort",
       "replay",
       "none"
      ]
     },
     "spec": {
      "type": "string"
     },
     "docs": {
      "type": "string"
     },
     "layers": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "render": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "limits": {
      "type": "object",
      "additionalProperties": true
     },
     "docs_policy": {
      "type": "object",
      "properties": {
       "force_dry_run": {
        "type": "boolean"
       }
      }
     }
    }
   },
   "ModelEngine": {
    "type": "object",
    "required": [
     "stage",
     "sha256"
    ],
    "properties": {
     "stage": {
      "type": "string"
     },
     "sha256": {
      "type": "string"
     },
     "bytes": {
      "type": "integer"
     },
     "onnx_sha256": {
      "type": "string"
     },
     "int4_weights": {
      "type": "integer"
     },
     "int4_exceptions": {
      "type": "integer"
     }
    }
   },
   "ModelInfo": {
    "type": "object",
    "required": [
     "schema",
     "checkpoint",
     "backend",
     "engines"
    ],
    "properties": {
     "schema": {
      "const": "mdl1"
     },
     "checkpoint": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "stage": {
      "type": "string"
     },
     "backend": {
      "type": "string",
      "enum": [
       "trt",
       "ort",
       "replay",
       "none"
      ]
     },
     "profile": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "a",
       "b",
       "c",
       null
      ]
     },
     "tensorrt": {
      "type": [
       "string",
       "null"
      ]
     },
     "engines": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ModelEngine"
      }
     }
    }
   },
   "Topology": {
    "type": "object",
    "required": [
     "schema",
     "joints",
     "never",
     "bones",
     "wrist",
     "tips",
     "actions",
     "held",
     "colors",
     "grid"
    ],
    "properties": {
     "schema": {
      "const": "top1"
     },
     "joints": {
      "type": "integer",
      "const": 70
     },
     "never": {
      "type": "array",
      "items": {
       "type": "integer"
      }
     },
     "wrist": {
      "type": "object",
      "properties": {
       "left": {
        "type": "integer"
       },
       "right": {
        "type": "integer"
       }
      }
     },
     "tips": {
      "type": "object",
      "additionalProperties": {
       "type": "array",
       "items": {
        "type": "integer"
       }
      }
     },
     "bones": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "type": "integer"
       },
       "minItems": 2,
       "maxItems": 2
      }
     },
     "actions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "held": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "colors": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "grid": {
      "type": "array",
      "items": {
       "type": "integer"
      },
      "minItems": 2,
      "maxItems": 2
     }
    }
   },
   "Camera": {
    "type": "object",
    "properties": {
     "K": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "type": "number"
       }
      }
     },
     "R_c2w": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "type": "number"
       }
      }
     },
     "t_c2w": {
      "type": "array",
      "items": {
       "type": "number"
      }
     },
     "gauge": {
      "type": "string"
     },
     "calibrated": {
      "type": "boolean"
     }
    }
   },
   "VideoEntry": {
    "type": "object",
    "required": [
     "id",
     "duration",
     "fps",
     "frames",
     "grid_step",
     "proxy",
     "proxy_wh",
     "native_wh"
    ],
    "properties": {
     "id": {
      "type": "string"
     },
     "title": {
      "type": "string"
     },
     "subtitle": {
      "type": "string"
     },
     "duration": {
      "type": [
       "number",
       "null"
      ],
      "description": "Null for the live camera."
     },
     "fps": {
      "type": "number"
     },
     "frames": {
      "type": [
       "integer",
       "null"
      ],
      "description": "Null for the live camera."
     },
     "grid_step": {
      "type": "integer"
     },
     "default_start": {
      "type": [
       "number",
       "null"
      ],
      "description": "Null for the live camera."
     },
     "hold": {
      "type": "number"
     },
     "proxy": {
      "type": "string",
      "description": "URL of the proxy video."
     },
     "proxy_wh": {
      "type": "array",
      "items": {
       "type": "integer"
      }
     },
     "native_wh": {
      "type": "array",
      "items": {
       "type": "integer"
      }
     },
     "source_wh": {
      "type": "array",
      "items": {
       "type": "integer"
      }
     },
     "crop": {
      "type": "array",
      "items": {
       "type": "integer"
      }
     },
     "profile": {
      "type": "string"
     },
     "camera": {
      "$ref": "#/components/schemas/Camera"
     },
     "held_out": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "type": "number"
       }
      }
     },
     "stone_model": {
      "type": "object",
      "additionalProperties": true
     },
     "kind": {
      "type": "string",
      "enum": [
       "recording",
       "camera"
      ],
      "default": "recording",
      "x-availability": "shipping",
      "description": "`camera`: the live camera. Absent: a recording."
     },
     "live": {
      "type": "boolean",
      "default": false,
      "x-availability": "shipping",
      "description": "True for the live camera: no duration, no seek, rate 1.0."
     },
     "seekable": {
      "type": "boolean",
      "default": true,
      "x-availability": "shipping"
     }
    },
    "description": "A source of the shared session: a recording, or the live camera (shipping). A server that does not send `kind`, `live` or `seekable` (the 20.20 unit today) means a seekable recording."
   },
   "VideoList": {
    "type": "object",
    "required": [
     "schema",
     "videos"
    ],
    "properties": {
     "schema": {
      "type": "string"
     },
     "title": {
      "type": "string"
     },
     "default_video": {
      "type": "string",
      "description": "The source a new session starts on: `live` on the shipped product, `aug28` on the 20.20 unit today."
     },
     "model": {
      "type": "object",
      "additionalProperties": true
     },
     "videos": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/VideoEntry"
      }
     }
    }
   },
   "Focus": {
    "type": "object",
    "description": "The shared stone focus, in the shape every viewer since v1 understands.",
    "required": [
     "n",
     "session",
     "video",
     "id",
     "g",
     "t",
     "x",
     "y",
     "z",
     "L",
     "W",
     "yaw"
    ],
    "properties": {
     "n": {
      "type": "integer"
     },
     "session": {
      "type": "integer"
     },
     "video": {
      "type": "string"
     },
     "id": {
      "type": "integer"
     },
     "g": {
      "type": "integer"
     },
     "t": {
      "type": "number"
     },
     "x": {
      "type": "number"
     },
     "y": {
      "type": "number"
     },
     "z": {
      "type": "number"
     },
     "L": {
      "type": "number"
     },
     "W": {
      "type": "number"
     },
     "yaw": {
      "type": "number"
     }
    }
   },
   "State": {
    "type": "object",
    "required": [
     "session",
     "revision",
     "video",
     "playing",
     "rate",
     "anchor_media",
     "anchor_wall",
     "hold_until",
     "duration",
     "changed_by",
     "focus",
     "media_time"
    ],
    "properties": {
     "session": {
      "type": "integer"
     },
     "revision": {
      "type": "integer"
     },
     "video": {
      "type": "string"
     },
     "playing": {
      "type": "boolean"
     },
     "rate": {
      "type": "number",
      "minimum": 0.3,
      "maximum": 1.0,
      "description": "Media seconds per wall second. Recordings play at 0.8 and auto-rate lowers it when the interpreter falls behind; the live camera is always 1.0 (frames are dropped instead, so `g` jumps)."
     },
     "anchor_media": {
      "type": "number"
     },
     "anchor_wall": {
      "type": "number",
      "description": "Epoch seconds on the server's wall clock."
     },
     "hold_until": {
      "type": "number"
     },
     "duration": {
      "type": [
       "number",
       "null"
      ],
      "description": "Null on the live camera."
     },
     "changed_by": {
      "type": "string",
      "enum": [
       "start",
       "viewer",
       "auto-rate",
       "end-of-video"
      ]
     },
     "focus": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/Focus"
       },
       {
        "type": "null"
       }
      ]
     },
     "media_time": {
      "type": "number",
      "description": "Seconds into the source; on the live camera, seconds since the live session started."
     }
    }
   },
   "WorkerStatus": {
    "type": "object",
    "required": [
     "state",
     "reason"
    ],
    "properties": {
     "state": {
      "type": "string",
      "enum": [
       "running",
       "idle",
       "waiting",
       "starting",
       "offline",
       "error",
       "paused"
      ]
     },
     "reason": {
      "type": "string"
     },
     "fps": {
      "type": "number"
     },
     "frame_ms": {
      "type": [
       "number",
       "null"
      ]
     },
     "cycle_ms": {
      "type": [
       "number",
       "null"
      ]
     },
     "session": {
      "type": [
       "integer",
       "null"
      ]
     },
     "g": {
      "type": [
       "integer",
       "null"
      ]
     },
     "gpu": {
      "type": [
       "number",
       "null"
      ]
     },
     "errors": {
      "type": "integer"
     },
     "stage_ms": {
      "type": "object",
      "additionalProperties": {
       "type": "number"
      }
     },
     "engines": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "model": {
      "type": "string"
     },
     "video": {
      "type": "string"
     }
    }
   },
   "StableStatus": {
    "type": "object",
    "required": [
     "state"
    ],
    "properties": {
     "state": {
      "type": "string",
      "enum": [
       "running",
       "starting",
       "failed",
       "off",
       "unusable"
      ]
     },
     "fits": {
      "type": "integer"
     },
     "evidence": {
      "type": "boolean",
      "description": "False: grey frames are missing, shapes come from the detections only."
     },
     "message": {
      "type": "string"
     },
     "fixer": {
      "type": "string",
      "enum": [
       "legacy",
       "thin-v1"
      ],
      "description": "The Stable engine's fixer (`--world-fixer`): `legacy` is the engine of the page before the API, `thin-v1` adds the thin-stone rules and the rest refinement of a paused frame."
     },
     "hold": {
      "$ref": "#/components/schemas/HoldStatus"
     }
    }
   },
   "HoldStatus": {
    "type": "object",
    "description": "While the shared session is paused, the world host is held on the paused grid frame and refines it on its own image\n(fixer thin-v1). Each round that changes that frame's world releases it again with `world.rev` one higher. The hold\nends at play, select, a seek while playing, or a new session.\n",
    "required": [
     "session",
     "g",
     "state",
     "rounds",
     "rev",
     "ms",
     "resteps"
    ],
    "properties": {
     "session": {
      "type": "integer"
     },
     "g": {
      "type": "integer",
      "description": "The held grid frame: the grid frame of the paused media time. A page whose video is presented within 20 ms of the paused time does not seek again, and when that crosses a grid frame's start it shows the frame next to this one, which gets this frame's refined world stepped again but no rounds of its own."
     },
     "at": {
      "type": "integer",
      "description": "The frame refined, when it is not `g`: the worker skipped `g` (a frame dropped under load), and a page shows the newest frame before it in its place."
     },
     "state": {
      "type": "string",
      "enum": [
       "waiting",
       "running",
       "converged",
       "nothing",
       "limit",
       "time",
       "off",
       "stale",
       "nogray",
       "failed",
       "moved",
       "released"
      ],
      "description": "`waiting` for the frame's packet, `running`, or over: `converged` (nothing left to refine), `nothing` (nothing to refine there), `limit` and `time` (the round and time bounds), `off` (fixer legacy refines nothing), `stale` (the frame and every frame before it are gone from the engine), `nogray` (no grey frame), `failed`, `moved` (another hold came), `released`."
     },
     "rounds": {
      "type": "integer",
      "description": "Refine rounds run."
     },
     "rev": {
      "type": "integer",
      "minimum": 0,
      "description": "The newest world revision of the frame."
     },
     "ms": {
      "type": "number",
      "description": "Wall time of the rounds."
     },
     "resteps": {
      "type": "integer",
      "description": "Packets after the held frame (the worker runs up to 0.6 s of media ahead of a paused playhead) stepped again from its refined world."
     }
    }
   },
   "SessionReply": {
    "type": "object",
    "required": [
     "server_now",
     "server_recv",
     "state",
     "worker",
     "viewers",
     "stable"
    ],
    "properties": {
     "server_now": {
      "type": "number"
     },
     "server_recv": {
      "type": "number"
     },
     "state": {
      "$ref": "#/components/schemas/State"
     },
     "worker": {
      "$ref": "#/components/schemas/WorkerStatus"
     },
     "viewers": {
      "type": "integer"
     },
     "stable": {
      "$ref": "#/components/schemas/StableStatus"
     }
    }
   },
   "SelectRequest": {
    "type": "object",
    "required": [
     "video"
    ],
    "properties": {
     "video": {
      "type": "string"
     },
     "time": {
      "type": "number",
      "minimum": 0
     }
    },
    "description": "`video` is a source id. For the live camera (`live`) leave `time` out: the session starts at the live edge (shipping)."
   },
   "SeekRequest": {
    "type": "object",
    "required": [
     "time"
    ],
    "properties": {
     "video": {
      "type": "string"
     },
     "time": {
      "type": "number",
      "minimum": 0
     }
    }
   },
   "EmptyRequest": {
    "type": "object",
    "description": "Any JSON object, or no body at all. Its fields are ignored, as the legacy `POST /api/control` ignores the fields an action does not read."
   },
   "FocusRequest": {
    "type": "object",
    "required": [
     "stone_id"
    ],
    "properties": {
     "stone_id": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000
     },
     "g": {
      "type": "integer",
      "description": "The frame the stone was picked on."
     },
     "session": {
      "type": "integer",
      "description": "Refused with 409 if not the current session."
     }
    }
   },
   "ControlReply": {
    "type": "object",
    "required": [
     "state",
     "server_now",
     "server_recv"
    ],
    "properties": {
     "state": {
      "$ref": "#/components/schemas/State"
     },
     "server_now": {
      "type": "number"
     },
     "server_recv": {
      "type": "number"
     },
     "dry_run": {
      "type": "boolean"
     }
    }
   },
   "ResolvedFocus": {
    "type": "object",
    "required": [
     "id",
     "path2d",
     "path3d"
    ],
    "properties": {
     "id": {
      "type": "integer"
     },
     "path2d": {
      "type": "array",
      "description": "Native px, oldest first, at most 512 points.",
      "items": {
       "type": "array",
       "items": {
        "type": "number"
       }
      }
     },
     "path3d": {
      "type": "array",
      "description": "Scene world, oldest first, at most 512 points.",
      "items": {
       "type": "array",
       "items": {
        "type": "number"
       }
      }
     }
    }
   },
   "FocusReply": {
    "type": "object",
    "required": [
     "focus",
     "resolved"
    ],
    "properties": {
     "focus": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/Focus"
       },
       {
        "type": "null"
       }
      ]
     },
     "resolved": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/ResolvedFocus"
       },
       {
        "type": "null"
       }
      ]
     }
    }
   },
   "Sip1Hand": {
    "type": "object",
    "properties": {
     "visible": {
      "type": "boolean"
     },
     "p_action": {
      "type": "array",
      "items": {
       "type": "number"
      },
      "minItems": 6,
      "maxItems": 6
     },
     "action": {
      "type": "string"
     },
     "p_interaction": {
      "type": "number"
     },
     "p_hold": {
      "type": "number"
     },
     "contact": {
      "type": "number"
     },
     "held": {
      "type": "string",
      "enum": [
       "empty",
       "stone",
       "tool",
       "tray"
      ]
     },
     "p_held": {
      "type": "array",
      "items": {
       "type": "number"
      },
      "minItems": 4,
      "maxItems": 4
     },
     "stone": {
      "type": "integer",
      "description": "Index into this packet's stones, or -1."
     },
     "wrist": {
      "type": "array",
      "items": {
       "type": "number"
      },
      "minItems": 2,
      "maxItems": 2
     },
     "p_wrist": {
      "type": "number"
     }
    }
   },
   "Sip1Packet": {
    "type": "object",
    "description": "The model codec packet (`schema` = `sip1`), the worker's bytes with `cursor` spliced in. Maps are base64 of zlib of u8 row-major.\n`person.joints[j]` = `[u, v, vis, x, y, z]` or null, 70 entries, `x,y,z` camera-frame template metres.\n`stones.items[k]` = `[u, v, w, h, score, X, Y, Z, w_m, h_m, yaw]`.\n",
    "required": [
     "schema",
     "maps",
     "depth",
     "boxes",
     "person",
     "stones",
     "tray",
     "hands",
     "both",
     "session",
     "video",
     "g",
     "i",
     "t",
     "past_valid",
     "dt_past",
     "ms"
    ],
    "properties": {
     "schema": {
      "const": "sip1"
     },
     "maps": {
      "type": "object",
      "required": [
       "grid",
       "human",
       "tray",
       "stone",
       "conf"
      ],
      "properties": {
       "grid": {
        "type": "array",
        "items": {
         "type": "integer"
        }
       },
       "human": {
        "type": "string"
       },
       "tray": {
        "type": "string"
       },
       "stone": {
        "type": "string"
       },
       "conf": {
        "type": "string"
       }
      }
     },
     "depth": {
      "type": "object",
      "required": [
       "q",
       "lo",
       "hi",
       "a",
       "b",
       "anchor"
      ],
      "properties": {
       "q": {
        "type": "string"
       },
       "lo": {
        "type": "number"
       },
       "hi": {
        "type": "number"
       },
       "a": {
        "type": "number"
       },
       "b": {
        "type": "number"
       },
       "anchor": {
        "type": "string"
       }
      }
     },
     "boxes": {
      "type": "object",
      "properties": {
       "stone": {
        "type": "array",
        "description": "x0,y0,x1,y1,rot,presence"
       },
       "person": {
        "type": "array",
        "description": "x0,y0,x1,y1,rot,presence"
       },
       "hand_left": {
        "type": "array",
        "description": "u,v,p"
       },
       "hand_right": {
        "type": "array",
        "description": "u,v,p"
       }
      }
     },
     "person": {
      "type": "object",
      "properties": {
       "present": {
        "type": "boolean"
       },
       "box": {
        "type": "array",
        "items": {
         "type": "number"
        }
       },
       "rot": {
        "type": "boolean"
       },
       "grid": {
        "type": "array",
        "items": {
         "type": "integer"
        }
       },
       "mask": {
        "type": "string"
       },
       "alpha": {
        "type": "string"
       },
       "joints": {
        "type": "array",
        "maxItems": 70,
        "items": {
         "oneOf": [
          {
           "type": "array",
           "items": {
            "type": "number"
           },
           "minItems": 6,
           "maxItems": 6
          },
          {
           "type": "null"
          }
         ]
        }
       },
       "scale": {
        "type": "number"
       },
       "bones_used": {
        "type": "integer"
       },
       "person_scale": {
        "type": "number"
       },
       "scale_anchor": {
        "type": "string",
        "enum": [
         "template",
         "contact",
         "contact-now"
        ]
       }
      }
     },
     "stones": {
      "type": "object",
      "properties": {
       "present": {
        "type": "boolean"
       },
       "count": {
        "type": "integer"
       },
       "box": {
        "type": "array",
        "items": {
         "type": "number"
        }
       },
       "rot": {
        "type": "boolean"
       },
       "grid": {
        "type": "array",
        "items": {
         "type": "integer"
        }
       },
       "fg": {
        "type": "string"
       },
       "tray_grid": {
        "type": "array",
        "items": {
         "type": "integer"
        }
       },
       "tray": {
        "type": "string"
       },
       "items": {
        "type": "array",
        "items": {
         "type": "array",
         "items": {
          "type": "number"
         },
         "minItems": 11,
         "maxItems": 11
        }
       }
      }
     },
     "tray": {
      "type": "object",
      "properties": {
       "valid": {
        "type": "boolean"
       },
       "normal": {
        "type": "array",
        "items": {
         "type": "number"
        }
       },
       "d": {
        "type": "number"
       },
       "anchor": {
        "type": "string"
       },
       "floor": {
        "type": "number"
       },
       "floor_anchor": {
        "type": "string"
       }
      }
     },
     "hands": {
      "type": "object",
      "properties": {
       "left": {
        "$ref": "#/components/schemas/Sip1Hand"
       },
       "right": {
        "$ref": "#/components/schemas/Sip1Hand"
       }
      }
     },
     "both": {
      "type": "number"
     },
     "session": {
      "type": "integer"
     },
     "video": {
      "type": "string"
     },
     "g": {
      "type": "integer"
     },
     "i": {
      "type": "integer"
     },
     "t": {
      "type": "number"
     },
     "past_valid": {
      "type": "boolean"
     },
     "dt_past": {
      "type": "number"
     },
     "ms": {
      "type": "object",
      "additionalProperties": {
       "type": "number"
      }
     },
     "cursor": {
      "type": "integer"
     }
    }
   },
   "Rect": {
    "type": "object",
    "description": "Board rectangle in the scene world.",
    "required": [
     "cx",
     "cy",
     "theta",
     "hw",
     "hh"
    ],
    "properties": {
     "cx": {
      "type": "number"
     },
     "cy": {
      "type": "number"
     },
     "theta": {
      "type": "number"
     },
     "hw": {
      "type": "number"
     },
     "hh": {
      "type": "number"
     }
    }
   },
   "Wrist": {
    "type": "object",
    "required": [
     "visible",
     "filled",
     "ring"
    ],
    "properties": {
     "uv": {
      "oneOf": [
       {
        "type": "array",
        "items": {
         "type": "number"
        },
        "minItems": 2,
        "maxItems": 2
       },
       {
        "type": "null"
       }
      ]
     },
     "visible": {
      "type": "boolean"
     },
     "filled": {
      "type": "boolean",
      "description": "P(interaction) >= .5"
     },
     "ring": {
      "type": "boolean",
      "description": "contact >= .5"
     },
     "stone": {
      "type": "integer",
      "description": "Index into this frame's items, or -1."
     }
    }
   },
   "OverlayLayer": {
    "type": "object",
    "description": "2-D per packet, raw-derived. Never waits for the Stable sim.",
    "required": [
     "schema",
     "native_wh",
     "regions",
     "mask",
     "boxes",
     "joints",
     "wrists",
     "items"
    ],
    "properties": {
     "schema": {
      "const": "ovl1"
     },
     "native_wh": {
      "type": "array",
      "items": {
       "type": "integer"
      },
      "minItems": 2,
      "maxItems": 2
     },
     "regions": {
      "type": "object",
      "required": [
       "rows",
       "cols"
      ],
      "properties": {
       "rows": {
        "type": "integer"
       },
       "cols": {
        "type": "integer"
       },
       "human": {
        "type": "string",
        "description": "base64 u8 rows*cols"
       },
       "tray": {
        "type": "string"
       },
       "stone": {
        "type": "string"
       }
      }
     },
     "mask": {
      "type": "object",
      "required": [
       "rows",
       "cols",
       "present"
      ],
      "properties": {
       "rows": {
        "type": "integer"
       },
       "cols": {
        "type": "integer"
       },
       "label": {
        "type": "string",
        "description": "0 none, 1 human, 2 left, 3 right"
       },
       "alpha": {
        "type": "string"
       },
       "box": {
        "type": "array",
        "items": {
         "type": "number"
        }
       },
       "rot": {
        "type": "boolean"
       },
       "present": {
        "type": "boolean"
       }
      }
     },
     "boxes": {
      "type": "object",
      "properties": {
       "person": {
        "type": "array",
        "description": "x0,y0,x1,y1,rot,presence"
       },
       "stone": {
        "type": "array",
        "description": "x0,y0,x1,y1,rot,presence"
       }
      }
     },
     "joints": {
      "type": "array",
      "description": "The sip1 joints, 70 entries `[u, v, vis, x, y, z]` or null.",
      "items": {
       "oneOf": [
        {
         "type": "array",
         "items": {
          "type": "number"
         },
         "minItems": 6,
         "maxItems": 6
        },
        {
         "type": "null"
        }
       ]
      }
     },
     "scale": {
      "type": [
       "number",
       "null"
      ],
      "description": "person.scale, for the blend when a world is late."
     },
     "wrists": {
      "type": "object",
      "properties": {
       "left": {
        "$ref": "#/components/schemas/Wrist"
       },
       "right": {
        "$ref": "#/components/schemas/Wrist"
       }
      }
     },
     "prev_g": {
      "type": [
       "integer",
       "null"
      ],
      "description": "The previous packet received in this session."
     },
     "items": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "t",
        "prev",
        "outline"
       ],
       "properties": {
        "t": {
         "type": "array",
         "description": "[u, v, w, h, score, X, Y, Z, w_m, h_m, yaw]",
         "items": {
          "type": "number"
         },
         "minItems": 11,
         "maxItems": 11
        },
        "prev": {
         "type": "integer",
         "description": "Mutual-nearest index into the previous packet's items, or -1. Valid only against the frame with g = prev_g."
        },
        "side": {
         "type": [
          "string",
          "null"
         ],
         "enum": [
          "left",
          "right",
          null
         ]
        },
        "outline": {
         "type": "array",
         "description": "Four corners, native px.",
         "items": {
          "type": "array",
          "items": {
           "type": "number"
          },
          "minItems": 2,
          "maxItems": 2
         }
        }
       }
      }
     }
    }
   },
   "SceneLayer": {
    "type": "object",
    "description": "3-D per packet, raw-derived.",
    "required": [
     "schema",
     "plane",
     "board",
     "surface",
     "skeleton"
    ],
    "properties": {
     "schema": {
      "const": "scn1"
     },
     "plane": {
      "type": "object",
      "required": [
       "n",
       "d",
       "floor"
      ],
      "properties": {
       "n": {
        "type": "array",
        "items": {
         "type": "number"
        },
        "minItems": 3,
        "maxItems": 3
       },
       "d": {
        "type": "number"
       },
       "floor": {
        "type": "number"
       },
       "anchor": {
        "type": "string"
       },
       "floor_anchor": {
        "type": "string"
       }
      }
     },
     "board": {
      "type": "object",
      "properties": {
       "raw": {
        "oneOf": [
         {
          "$ref": "#/components/schemas/Rect"
         },
         {
          "type": "null"
         }
        ]
       }
      }
     },
     "surface": {
      "type": "object",
      "required": [
       "rows",
       "cols",
       "q",
       "lo",
       "hi",
       "a",
       "b",
       "flat",
       "quads",
       "lift"
      ],
      "properties": {
       "rows": {
        "type": "integer"
       },
       "cols": {
        "type": "integer"
       },
       "q": {
        "type": "string",
        "description": "base64 u8 rows*cols. logZ = a*(lo + q/255*(hi-lo)) + b; X = ray*exp(logZ)."
       },
       "lo": {
        "type": "number"
       },
       "hi": {
        "type": "number"
       },
       "a": {
        "type": "number"
       },
       "b": {
        "type": "number"
       },
       "flat": {
        "type": "string",
        "description": "Bitset rows*cols: cells the Stable view puts on the board."
       },
       "quads": {
        "type": "object",
        "required": [
         "raw",
         "stable"
        ],
        "properties": {
         "raw": {
          "type": "string",
          "description": "Bitset (rows-1)*(cols-1), row-major: quads kept."
         },
         "stable": {
          "type": "string"
         }
        }
       },
       "lift": {
        "type": "number"
       }
      }
     },
     "skeleton": {
      "type": "object",
      "required": [
       "world"
      ],
      "properties": {
       "world": {
        "type": "array",
        "description": "70 entries, scene world, raw path.",
        "items": {
         "oneOf": [
          {
           "type": "array",
           "items": {
            "type": "number"
           },
           "minItems": 3,
           "maxItems": 3
          },
          {
           "type": "null"
          }
         ]
        }
       }
      }
     },
     "rings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Ring"
      }
     },
     "items": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "x": {
         "type": "number"
        },
        "y": {
         "type": "number"
        },
        "yaw": {
         "type": "number"
        },
        "L": {
         "type": "number"
        },
        "S": {
         "type": "number"
        },
        "h": {
         "type": "number"
        },
        "side": {
         "type": [
          "string",
          "null"
         ],
         "enum": [
          "left",
          "right",
          null
         ]
        }
       }
      }
     }
    }
   },
   "Ring": {
    "type": "object",
    "required": [
     "side",
     "pos"
    ],
    "properties": {
     "side": {
      "type": "string",
      "enum": [
       "left",
       "right"
      ]
     },
     "pos": {
      "type": "array",
      "items": {
       "type": "number"
      },
      "minItems": 3,
      "maxItems": 3
     }
    }
   },
   "HandCard": {
    "type": "object",
    "required": [
     "title",
     "tone",
     "visible",
     "fine"
    ],
    "properties": {
     "title": {
      "type": "string"
     },
     "tone": {
      "type": "string",
      "enum": [
       "hold",
       "interact",
       "idle",
       "hidden",
       "none"
      ]
     },
     "visible": {
      "type": "boolean"
     },
     "pInteraction": {
      "type": [
       "number",
       "null"
      ]
     },
     "contact": {
      "type": [
       "number",
       "null"
      ]
     },
     "contactOn": {
      "type": "boolean"
     },
     "held": {
      "type": [
       "string",
       "null"
      ]
     },
     "pHeld": {
      "type": [
       "number",
       "null"
      ]
     },
     "action": {
      "type": [
       "string",
       "null"
      ]
     },
     "fine": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "key": {
         "type": "string"
        },
        "label": {
         "type": "string"
        },
        "p": {
         "type": [
          "number",
          "null"
         ]
        },
        "reliable": {
         "type": "boolean"
        }
       }
      }
     },
     "hint": {
      "type": [
       "string",
       "null"
      ]
     },
     "stone": {
      "type": "integer"
     },
     "pWrist": {
      "type": [
       "number",
       "null"
      ]
     }
    }
   },
   "CardsLayer": {
    "type": "object",
    "required": [
     "schema",
     "left",
     "right",
     "numbers"
    ],
    "properties": {
     "schema": {
      "const": "crd1"
     },
     "left": {
      "$ref": "#/components/schemas/HandCard"
     },
     "right": {
      "$ref": "#/components/schemas/HandCard"
     },
     "stage": {
      "oneOf": [
       {
        "type": "object",
        "properties": {
         "parts": {
          "type": "array",
          "items": {
           "type": "object",
           "properties": {
            "key": {
             "type": "string"
            },
            "label": {
             "type": "string"
            },
            "fam": {
             "type": "string"
            },
            "ms": {
             "type": "number"
            }
           }
          }
         },
         "total": {
          "type": "number"
         },
         "fps": {
          "type": "number"
         }
        }
       },
       {
        "type": "null"
       }
      ]
     },
     "numbers": {
      "type": "object",
      "properties": {
       "stones": {
        "type": "integer"
       },
       "past_valid": {
        "type": "boolean"
       },
       "dt_past": {
        "type": "number"
       },
       "tray_anchor": {
        "type": "string"
       },
       "floor_anchor": {
        "type": "string"
       },
       "depth_anchor": {
        "type": "string"
       },
       "g": {
        "type": "integer"
       },
       "t": {
        "type": "number"
       },
       "session": {
        "type": "integer"
       }
      }
     }
    }
   },
   "Solid": {
    "type": "object",
    "required": [
     "pos",
     "q",
     "dims"
    ],
    "properties": {
     "pos": {
      "type": "array",
      "items": {
       "type": "number"
      },
      "minItems": 3,
      "maxItems": 3
     },
     "q": {
      "type": "array",
      "description": "x, y, z, w",
      "items": {
       "type": "number"
      },
      "minItems": 4,
      "maxItems": 4
     },
     "dims": {
      "type": "array",
      "description": "L, W, h",
      "items": {
       "type": "number"
      },
      "minItems": 3,
      "maxItems": 3
     }
    }
   },
   "StoneView": {
    "type": "object",
    "required": [
     "id",
     "mode",
     "family",
     "shape",
     "detected",
     "uncertain",
     "side",
     "outline",
     "solid"
    ],
    "properties": {
     "id": {
      "type": "integer",
      "description": "Persistent over the session, the same for every viewer."
     },
     "mode": {
      "type": "string",
      "enum": [
       "seen",
       "kept",
       "pushed",
       "hinge",
       "carry",
       "placed",
       "transit"
      ]
     },
     "family": {
      "type": "string",
      "enum": [
       "rect",
       "dogbone"
      ]
     },
     "shape": {
      "type": "string",
      "enum": [
       "model",
       "provisional",
       "frozen"
      ]
     },
     "detected": {
      "type": "boolean"
     },
     "uncertain": {
      "type": "boolean"
     },
     "side": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "left",
       "right",
       "both",
       null
      ]
     },
     "outline": {
      "type": "array",
      "description": "Native px, 4 or 12 vertices.",
      "items": {
       "type": "array",
       "items": {
        "type": "number"
       },
       "minItems": 2,
       "maxItems": 2
      }
     },
     "solid": {
      "$ref": "#/components/schemas/Solid"
     },
     "placed": {
      "type": "integer",
      "description": "Packets since a put-down."
     },
     "source": {
      "type": "string",
      "enum": [
       "model",
       "image"
      ],
      "description": "Absent or `model`: a stone the model boxed. `image`: one it never boxed, made from the image (a filled hole, or the new part of a split; fixer thin-v1)."
     }
    }
   },
   "HandState": {
    "type": "object",
    "required": [
     "state",
     "stone"
    ],
    "properties": {
     "state": {
      "type": "string",
      "enum": [
       "free",
       "touch",
       "grasp",
       "hinge",
       "carry"
      ]
     },
     "stone": {
      "type": [
       "integer",
       "null"
      ]
     },
     "rayK": {
      "type": "number"
     },
     "untrusted": {
      "type": "boolean"
     }
    }
   },
   "WorldEvent": {
    "type": "object",
    "required": [
     "type"
    ],
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "new",
       "confirm",
       "freeze",
       "push",
       "lift",
       "hinge",
       "carry",
       "place",
       "drop",
       "gone",
       "delete",
       "split"
      ]
     },
     "id": {
      "type": "integer"
     },
     "side": {
      "type": "string"
     },
     "why": {
      "type": "string"
     },
     "into": {
      "type": "array",
      "description": "`split`: the stone's own id, which keeps the larger part, then the new part's (which has no `new` of its own).",
      "items": {
       "type": "integer"
      },
      "minItems": 2,
      "maxItems": 2
     },
     "source": {
      "type": "string",
      "enum": [
       "model",
       "image"
      ],
      "description": "`new` of a stone the model never boxed: `image` (fixer thin-v1)."
     }
    },
    "examples": [
     {
      "type": "new",
      "id": 41,
      "source": "image"
     },
     {
      "type": "split",
      "id": 57,
      "into": [
       57,
       61
      ]
     }
    ]
   },
   "WorldDraw": {
    "type": "object",
    "description": "Per-packet draw terms resolved on the server.",
    "properties": {
     "board": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/Rect"
       },
       {
        "type": "null"
       }
      ]
     },
     "skeleton": {
      "type": "object",
      "required": [
       "logF",
       "k",
       "elbow"
      ],
      "properties": {
       "logF": {
        "type": "number"
       },
       "k": {
        "type": "object",
        "description": "Per-hand effective ray scale.",
        "additionalProperties": {
         "type": "number"
        }
       },
       "elbow": {
        "type": "object",
        "description": "Per-side elbow offset, camera frame.",
        "additionalProperties": {
         "type": "array",
         "items": {
          "type": "number"
         },
         "minItems": 3,
         "maxItems": 3
        }
       }
      }
     }
    }
   },
   "WorldLayer": {
    "type": "object",
    "description": "The Stable sim's persistent world at one grid frame. Field names are the engine's. While the session is paused the world of the paused frame may be released again, revised (`rev`); every read answers with the newest revision.",
    "required": [
     "schema",
     "session",
     "video",
     "g",
     "t",
     "motion",
     "logF",
     "stones",
     "hands",
     "events",
     "stats"
    ],
    "properties": {
     "schema": {
      "const": "stw1"
     },
     "session": {
      "type": "integer"
     },
     "video": {
      "type": "string"
     },
     "g": {
      "type": "integer"
     },
     "t": {
      "type": "number"
     },
     "motion": {
      "type": "string",
      "enum": [
       "static",
       "moving",
       "settling"
      ]
     },
     "logF": {
      "type": "number"
     },
     "stones": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/StoneView"
      }
     },
     "hands": {
      "type": "object",
      "properties": {
       "left": {
        "$ref": "#/components/schemas/HandState"
       },
       "right": {
        "$ref": "#/components/schemas/HandState"
       }
      }
     },
     "events": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/WorldEvent"
      }
     },
     "stats": {
      "type": "object",
      "properties": {
       "stones": {
        "type": "integer"
       },
       "confirmed": {
        "type": "integer"
       },
       "frozen": {
        "type": "integer"
       },
       "fitted": {
        "type": "integer"
       },
       "held": {
        "type": "integer"
       },
       "stepMs": {
        "type": "number"
       }
      }
     },
     "draw": {
      "$ref": "#/components/schemas/WorldDraw"
     },
     "focus": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/ResolvedFocus"
       },
       {
        "type": "null"
       }
      ]
     },
     "rev": {
      "type": "integer",
      "minimum": 0,
      "description": "The world's revision for this frame: absent (0) as first released; 1, 2, ... after the rest refinement of a paused frame, or a frame stepped again after one, changed it."
     }
    }
   },
   "Frame": {
    "type": "object",
    "required": [
     "cursor",
     "session",
     "video",
     "g",
     "i",
     "t",
     "past_valid",
     "dt_past"
    ],
    "properties": {
     "cursor": {
      "type": "integer"
     },
     "session": {
      "type": "integer"
     },
     "video": {
      "type": "string"
     },
     "g": {
      "type": "integer"
     },
     "i": {
      "type": "integer"
     },
     "t": {
      "type": "number"
     },
     "past_valid": {
      "type": "boolean"
     },
     "dt_past": {
      "type": "number"
     },
     "missing": {
      "type": "array",
      "description": "Layers requested but not ready at the release deadline.",
      "items": {
       "type": "string",
       "enum": [
        "overlay",
        "scene",
        "cards",
        "world"
       ]
      }
     },
     "raw": {
      "$ref": "#/components/schemas/Sip1Packet"
     },
     "overlay": {
      "$ref": "#/components/schemas/OverlayLayer"
     },
     "scene": {
      "$ref": "#/components/schemas/SceneLayer"
     },
     "cards": {
      "$ref": "#/components/schemas/CardsLayer"
     },
     "world": {
      "$ref": "#/components/schemas/WorldLayer"
     }
    }
   },
   "LiveReply": {
    "type": "object",
    "required": [
     "server_now",
     "server_recv",
     "state",
     "worker",
     "viewers",
     "stable",
     "cursor",
     "frames"
    ],
    "properties": {
     "server_now": {
      "type": "number"
     },
     "server_recv": {
      "type": "number"
     },
     "state": {
      "$ref": "#/components/schemas/State"
     },
     "worker": {
      "$ref": "#/components/schemas/WorkerStatus"
     },
     "viewers": {
      "type": "integer"
     },
     "stable": {
      "$ref": "#/components/schemas/StableStatus"
     },
     "cursor": {
      "type": "integer"
     },
     "frames": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Frame"
      }
     }
    }
   },
   "StoneTrack": {
    "type": "object",
    "required": [
     "schema",
     "session",
     "video",
     "id",
     "g",
     "t",
     "stone",
     "first_g",
     "last_g",
     "path2d",
     "path3d"
    ],
    "properties": {
     "schema": {
      "const": "sts1"
     },
     "session": {
      "type": "integer"
     },
     "video": {
      "type": "string"
     },
     "id": {
      "type": "integer"
     },
     "g": {
      "type": "integer"
     },
     "t": {
      "type": "number"
     },
     "stone": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/StoneView"
       },
       {
        "type": "null"
       }
      ]
     },
     "first_g": {
      "type": "integer"
     },
     "last_g": {
      "type": "integer"
     },
     "path2d": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "type": "number"
       }
      }
     },
     "path3d": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "type": "number"
       }
      }
     }
    }
   },
   "EventLog": {
    "type": "object",
    "required": [
     "session",
     "video",
     "events",
     "next_after"
    ],
    "properties": {
     "session": {
      "type": "integer"
     },
     "video": {
      "type": "string"
     },
     "events": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "g",
        "t",
        "type"
       ],
       "properties": {
        "g": {
         "type": "integer"
        },
        "t": {
         "type": "number"
        },
        "type": {
         "type": "string"
        },
        "id": {
         "type": "integer"
        },
        "side": {
         "type": "string"
        },
        "why": {
         "type": "string"
        },
        "into": {
         "type": "array",
         "items": {
          "type": "integer"
         }
        },
        "source": {
         "type": "string"
        }
       }
      }
     },
     "next_after": {
      "type": "integer",
      "description": "The `after` that continues this log without loss or repeats, while its frames are retained (see `oldest_g`): never before `after` or before a frame of these events."
     },
     "oldest_g": {
      "type": "integer"
     }
    }
   },
   "DrawStone2D": {
    "type": "object",
    "required": [
     "outline",
     "style",
     "alpha"
    ],
    "properties": {
     "id": {
      "type": [
       "integer",
       "null"
      ]
     },
     "outline": {
      "type": "array",
      "items": {
       "type": "array",
       "items": {
        "type": "number"
       },
       "minItems": 2,
       "maxItems": 2
      }
     },
     "style": {
      "type": "string",
      "enum": [
       "held",
       "placed",
       "model",
       "detected",
       "kept",
       "raw"
      ]
     },
     "side": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "left",
       "right",
       "both",
       null
      ]
     },
     "alpha": {
      "type": "number"
     },
     "detected": {
      "type": "boolean"
     },
     "uncertain": {
      "type": "boolean"
     },
     "shape": {
      "type": [
       "string",
       "null"
      ]
     },
     "mode": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "Primitives2D": {
    "type": "object",
    "description": "Flat draw lists in native px. Widths and radii are in overlay.js's line unit for a canvas of the native width, `lw`, so they are what the page draws at native size; scale them with the canvas.",
    "properties": {
     "lw": {
      "type": "number",
      "description": "The line unit the sizes are in: clamp(native width / 420, 1.2, 3)."
     },
     "images": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "polygons": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "segments": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "circles": {
      "type": "array",
      "description": "A filled wrist is a filled circle at alpha .85 and a stroked one at alpha 1.",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "labels": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true,
       "properties": {
        "baseline": {
         "type": "string",
         "description": "The canvas textBaseline that `at` is given for (top, middle)."
        }
       }
      }
     }
    }
   },
   "Overlay2D": {
    "type": "object",
    "description": "The 2-D draw list, final, native px.",
    "required": [
     "schema",
     "session",
     "video",
     "g",
     "f",
     "t",
     "mode",
     "native_wh"
    ],
    "properties": {
     "schema": {
      "const": "r2d1"
     },
     "session": {
      "type": "integer"
     },
     "video": {
      "type": "string"
     },
     "g": {
      "type": "integer",
      "description": "Packet a."
     },
     "bg": {
      "type": [
       "integer",
       "null"
      ],
      "description": "Packet b, or null."
     },
     "f": {
      "type": "number",
      "description": "Fraction from a to b."
     },
     "t": {
      "type": "number"
     },
     "mode": {
      "type": "string",
      "enum": [
       "stable",
       "raw"
      ]
     },
     "missing": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "native_wh": {
      "type": "array",
      "items": {
       "type": "integer"
      }
     },
     "regions": {
      "type": "object",
      "additionalProperties": true
     },
     "mask": {
      "type": "object",
      "additionalProperties": true
     },
     "boxes": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "stones": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DrawStone2D"
      }
     },
     "skeleton": {
      "type": "object",
      "properties": {
       "bones": {
        "type": "array",
        "items": {
         "type": "object",
         "additionalProperties": true
        }
       },
       "joints": {
        "type": "array",
        "items": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "wrists": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "focus": {
      "type": [
       "object",
       "null"
      ],
      "additionalProperties": true
     },
     "primitives": {
      "$ref": "#/components/schemas/Primitives2D"
     }
    }
   },
   "DrawStone3D": {
    "type": "object",
    "required": [
     "family",
     "pos",
     "q",
     "dims",
     "alpha"
    ],
    "properties": {
     "id": {
      "type": [
       "integer",
       "null"
      ]
     },
     "family": {
      "type": "string",
      "enum": [
       "rect",
       "dogbone",
       "box"
      ]
     },
     "pos": {
      "type": "array",
      "items": {
       "type": "number"
      }
     },
     "q": {
      "type": "array",
      "items": {
       "type": "number"
      }
     },
     "dims": {
      "type": "array",
      "items": {
       "type": "number"
      }
     },
     "side": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "left",
       "right",
       "both",
       null
      ]
     },
     "alpha": {
      "type": "number"
     },
     "uncertain": {
      "type": "boolean"
     }
    }
   },
   "SurfaceMesh": {
    "type": "object",
    "description": "The observed surface. `vertices` is an explicit mesh; `compact` is the `scene.surface` form.",
    "required": [
     "form",
     "rows",
     "cols"
    ],
    "properties": {
     "form": {
      "type": "string",
      "enum": [
       "vertices",
       "compact"
      ]
     },
     "rows": {
      "type": "integer"
     },
     "cols": {
      "type": "integer"
     },
     "positions": {
      "type": "string",
      "description": "base64 f32le x,y,z rows*cols (world)."
     },
     "indices": {
      "type": "string",
      "description": "base64 u16le triangle list."
     },
     "opacity": {
      "type": "number"
     }
    }
   },
   "Primitives3D": {
    "type": "object",
    "properties": {
     "boxes": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "segments": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "spheres": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": true
      }
     },
     "mesh": {
      "type": "object",
      "additionalProperties": true
     }
    }
   },
   "Scene3D": {
    "type": "object",
    "description": "The 3-D scene, final, scene world.",
    "required": [
     "schema",
     "session",
     "video",
     "g",
     "f",
     "t",
     "mode",
     "plane",
     "board",
     "stones",
     "skeleton"
    ],
    "properties": {
     "schema": {
      "const": "r3d1"
     },
     "session": {
      "type": "integer"
     },
     "video": {
      "type": "string"
     },
     "g": {
      "type": "integer"
     },
     "bg": {
      "type": [
       "integer",
       "null"
      ]
     },
     "f": {
      "type": "number"
     },
     "t": {
      "type": "number"
     },
     "mode": {
      "type": "string",
      "enum": [
       "stable",
       "raw"
      ]
     },
     "missing": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "camera": {
      "type": "object",
      "additionalProperties": true
     },
     "plane": {
      "type": "object",
      "additionalProperties": true
     },
     "board": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/Rect"
       },
       {
        "type": "null"
       }
      ]
     },
     "stones": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/DrawStone3D"
      }
     },
     "skeleton": {
      "type": "object",
      "properties": {
       "joints": {
        "type": "array",
        "items": {
         "oneOf": [
          {
           "type": "array",
           "items": {
            "type": "number"
           },
           "minItems": 3,
           "maxItems": 3
          },
          {
           "type": "null"
          }
         ]
        }
       },
       "bones": {
        "type": "array",
        "items": {
         "type": "object",
         "additionalProperties": true
        }
       },
       "rings": {
        "type": "array",
        "items": {
         "$ref": "#/components/schemas/Ring"
        }
       }
      }
     },
     "surface": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/SurfaceMesh"
       },
       {
        "type": "null"
       }
      ]
     },
     "focus": {
      "type": [
       "object",
       "null"
      ],
      "additionalProperties": true
     },
     "primitives": {
      "$ref": "#/components/schemas/Primitives3D"
     }
    }
   },
   "Health": {
    "type": "object",
    "required": [
     "ok",
     "worker",
     "viewers"
    ],
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "worker": {
      "type": "string"
     },
     "viewers": {
      "type": "integer"
     }
    }
   },
   "Ready": {
    "type": "object",
    "required": [
     "ready",
     "waiting"
    ],
    "properties": {
     "ready": {
      "type": "boolean"
     },
     "waiting": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "HostStatus": {
    "type": "object",
    "required": [
     "state",
     "restarts"
    ],
    "properties": {
     "state": {
      "type": "string",
      "enum": [
       "running",
       "starting",
       "failed",
       "off"
      ]
     },
     "restarts": {
      "type": "integer"
     },
     "rss_mb": {
      "type": "number"
     },
     "queue": {
      "type": "integer"
     }
    }
   },
   "Status": {
    "type": "object",
    "required": [
     "build",
     "boot",
     "uptime_s",
     "page",
     "worker",
     "stable",
     "hosts",
     "viewers"
    ],
    "properties": {
     "build": {
      "type": "string"
     },
     "boot": {
      "type": "string"
     },
     "uptime_s": {
      "type": "number"
     },
     "page": {
      "type": "string",
      "enum": [
       "legacy",
       "next"
      ]
     },
     "worker": {
      "$ref": "#/components/schemas/WorkerStatus"
     },
     "retained": {
      "$ref": "#/components/schemas/Retained"
     },
     "stable": {
      "$ref": "#/components/schemas/StableStatus"
     },
     "hosts": {
      "type": "object",
      "additionalProperties": {
       "$ref": "#/components/schemas/HostStatus"
      }
     },
     "memory": {
      "type": "object",
      "additionalProperties": true
     },
     "viewers": {
      "type": "integer"
     },
     "long_polls": {
      "type": "integer"
     },
     "streams": {
      "type": "integer"
     }
    }
   },
   "ClockEvent": {
    "description": "The data of an SSE `clock` event, sent when the shared state changes: its fields, and the server's wall clock.",
    "allOf": [
     {
      "$ref": "#/components/schemas/State"
     },
     {
      "type": "object",
      "required": [
       "server_now"
      ],
      "properties": {
       "server_now": {
        "type": "number"
       }
      }
     }
    ]
   },
   "ResetEvent": {
    "type": "object",
    "description": "The data of an SSE `reset` event, for a `Last-Event-ID` of another boot; the stream goes on from the newest.",
    "required": [
     "boot",
     "cursor"
    ],
    "properties": {
     "boot": {
      "type": "string"
     },
     "cursor": {
      "type": "integer"
     }
    }
   },
   "GapEvent": {
    "type": "object",
    "description": "The data of an SSE `gap` event (and an NDJSON line of its own): that many items were skipped for a slow consumer.",
    "required": [
     "gap"
    ],
    "properties": {
     "gap": {
      "type": "integer",
      "minimum": 1
     }
    }
   }
  },
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "Optional. The 20.20 unit has no authentication and ignores it; a deployment may require it."
   }
  }
 },
 "x-tagGroups": [
  {
   "name": "High level",
   "tags": [
    "Interpreter",
    "Sources",
    "Session"
   ]
  },
  {
   "name": "Mid level",
   "tags": [
    "Streams",
    "Render-ready"
   ]
  },
  {
   "name": "Low level",
   "tags": [
    "Frames and codec"
   ]
  },
  {
   "name": "Service",
   "tags": [
    "Meta",
    "Ops"
   ]
  }
 ],
 "security": [
  {},
  {
   "bearerAuth": []
  }
 ]
}