{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/immix/json-schema/immix-algo-instance-row-schema.json",
  "title": "AlgoInstanceRow",
  "description": "An algo instance as the API serves it: its identity, where it stands and the record of who moved it — `createdByUserId` and `lastUpdatedByUserId` (null when the engine or the platform's own rule moved it; `lastCause` says which) — with the row extras (`globalSequence`). The `ETag` is `configSeq`: the latest staged document's sequence number, what `If-Match` takes on a config write.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/immix-algos-api-openapi.yml#/components/schemas/AlgoInstanceRow",
  "type": "object",
  "properties": {
    "globalSequence": {
      "$ref": "#/$defs/GlobalSequenceValue"
    },
    "unscaled": {
      "type": "boolean",
      "description": "Never present since 0.3.3: every money value on this API states its own scale on the wire — a policy amount or cap since 0.3.3, an order's and an execution's since 0.3.2, a balance's since 0.3.1 — so a row is never served raw, whether or not this member holds the asset or instrument it references. Kept, deprecated, so a client generated from 0.3.2 still compiles; it goes at the next major.",
      "deprecated": true
    },
    "instanceId": {
      "type": "integer",
      "description": "The instance's id — the value its orders carry as `algoInstanceId`."
    },
    "orgId": {
      "type": "integer",
      "description": "The organisation that owns the instance."
    },
    "algoVersionId": {
      "type": "integer",
      "description": "The catalog version the instance runs (`GET /algos/versions`)."
    },
    "pool": {
      "type": "string",
      "description": "The engine pool the instance runs on, fixed at creation."
    },
    "displayName": {
      "type": "string",
      "description": "The instance's display name, as created."
    },
    "status": {
      "$ref": "#/$defs/AlgoInstanceRowStatus",
      "description": "Where the instance stands: `CREATED` until its first document is applied, `STOPPED` or `STARTED` under the desk, `ERROR` after the engine's fault trip (left only by a stop), `DELETED` terminal. `PENDING_APPROVAL` and `DISABLED` are reserved and never served today. The value set is append-only: read an unknown name as `UNKNOWN`."
    },
    "transitionSeq": {
      "type": "integer",
      "description": "The instance's transition number: 1 at creation, one more on every move."
    },
    "configSeq": {
      "type": "integer",
      "description": "The latest staged document's sequence number — the `ETag`, and what `If-Match` takes on a config write."
    },
    "appliedConfigSeq": {
      "type": "integer",
      "description": "The document in force; 0 while none has been applied."
    },
    "createdByUserId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The user who created the instance."
    },
    "createdAtNs": {
      "type": "string",
      "pattern": "^-?[0-9]+$",
      "description": "When it was created — epoch nanoseconds as a decimal string."
    },
    "lastUpdatedByUserId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The user whose command last moved the instance; null when the engine or the platform's own rule did — `lastCause` says which."
    },
    "lastUpdatedAtNs": {
      "type": "string",
      "pattern": "^-?[0-9]+$",
      "description": "When it last moved — epoch nanoseconds as a decimal string."
    },
    "lastCause": {
      "$ref": "#/$defs/AlgoInstanceRowLastCause",
      "description": "Why it last moved: a command, the organisation's halt, its first document applied, the engine's fault trip, or the engine's divergence check. The value set is append-only: read an unknown name as `UNKNOWN`."
    },
    "lastCommandKind": {
      "$ref": "#/$defs/AlgoInstanceRowLastCommandKind",
      "description": "The command behind the last move — a desk's, or the engine's report that moved it. The value set is append-only: read an unknown name as `UNKNOWN`."
    },
    "pendingByUserId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Reserved; always null."
    }
  },
  "required": [
    "globalSequence",
    "instanceId",
    "orgId",
    "algoVersionId",
    "pool",
    "displayName",
    "status",
    "transitionSeq",
    "configSeq",
    "appliedConfigSeq",
    "createdAtNs",
    "lastUpdatedAtNs",
    "lastCause",
    "lastCommandKind"
  ],
  "$defs": {
    "AlgoInstanceRowLastCause": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "COMMAND",
        "HALT",
        "CONFIG_APPLIED",
        "ENGINE_FAULT",
        "DIVERGED"
      ],
      "description": "Why it last moved: a command, the organisation's halt, its first document applied, the engine's fault trip, or the engine's divergence check. The value set is append-only: read an unknown name as `UNKNOWN`.",
      "title": "AlgoInstanceRowLastCause"
    },
    "AlgoInstanceRowLastCommandKind": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "CREATE_ALGO_INSTANCE",
        "SUBMIT_ALGO_CONFIG",
        "START_ALGO_INSTANCE",
        "STOP_ALGO_INSTANCE",
        "DELETE_ALGO_INSTANCE",
        "HALT_ALGOS",
        "REPORT_ALGO_VERSIONS",
        "REPORT_ALGO_CONFIG_OUTCOME",
        "REPORT_ALGO_INSTANCE_FAULT"
      ],
      "description": "The command behind the last move — a desk's, or the engine's report that moved it. The value set is append-only: read an unknown name as `UNKNOWN`.",
      "title": "AlgoInstanceRowLastCommandKind"
    },
    "AlgoInstanceRowStatus": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "CREATED",
        "STOPPED",
        "STARTED",
        "ERROR",
        "DELETED",
        "PENDING_APPROVAL",
        "DISABLED"
      ],
      "description": "Where the instance stands: `CREATED` until its first document is applied, `STOPPED` or `STARTED` under the desk, `ERROR` after the engine's fault trip (left only by a stop), `DELETED` terminal. `PENDING_APPROVAL` and `DISABLED` are reserved and never served today. The value set is append-only: read an unknown name as `UNKNOWN`.",
      "title": "AlgoInstanceRowStatus"
    },
    "GlobalSequenceValue": {
      "type": "string",
      "pattern": "^[0-9]+$",
      "description": "The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.",
      "title": "GlobalSequenceValue"
    }
  }
}