list_versions #

View this page as Markdown

On this page

Generated automatically from the published contract sources.

A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/list_versions, with a bearer credential and the action's payload as the JSON body. It also accepts GET. An MCP connection lists this action as the tool tzcloud_list_versions.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts (Sign-in, sessions, and tokens).

Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

Contract description #

This call lists your app's version history, newest first. These are the version numbers promote and roll_back take. Kinds are deploy, promote, or restart. A restart re-creates the serving version under current settings, made by restart_application, a rename, or the platform. Each row says whether it serves and is promotable. promotable marks a kept image, without advice to promote. Once retention deletes its image, promotable is false. Each environment's serving row gives kept, recorded { path, sha256 } pairs or null, for reuse in deploy_files. Version numbers form one sequence per application, shared by development and production. Each deploy takes the next number. A promote, rollback, or restart row has the number of the version it applies.

More about this action #

Each row also gives harness_hash, the hash of the runtime harness its image contains, and harness_current, whether that harness is the platform's current one. A promote keeps the harness of the version it promotes, and a new deploy takes the current harness. Each row also records its step timings. A failed build's outcome includes the last lines of the build's own output. The serving row also gives fixes: critical or high, the highest severity fixed by the platform's base image updates since its version's base, or null. It is the same value as read_status's base.fixes.

Each environment's serving row also gives kept: its recorded files as { path, sha256 } pairs sorted by path, or null where none were recorded. Each listed hash can replace content for that file in deploy_files while the version serves. Null covers versions deployed before the platform recorded these entries, those deployed through the command, upload or artifact route, and promotes, rollbacks or restarts carrying their null. Where kept is null, a later chat sends every file with content or stored. Other rows carry no kept.

Each row gives its environment, number, kind, state, artifact hash, times, and outcome. An ended row's result in outcome says how it ended. Read a failed row's outcome for its error and detail and, where the health check failed, its gate evidence.

Access and action metadata #

{
  "name": "list_versions",
  "resource": "version",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "An application's version history, newest first: each row's environment, number, kind (deploy, promote, or restart, the last the re-creation of a serving revision under current settings by `restart_application`, a rename, or the platform), state, artifact hash, instants, and outcome. The outcome carries `result`, and the `gate` evidence of a failed health gate or a failed build's last lines. Each row says whether it is serving and whether it is promotable, false once the platform's retention has deleted its image. It carries its step `timings`, and its harness hash with whether that harness is the platform's current one, which a promote keeps and a new deploy takes; the rows are those promotion and rollback name.\n\nEach environment's serving row alone also gives `kept`: its recorded file paths and SHA-256 hashes sorted by path, or null where none were recorded. Each listed hash can replace `content` for that file in `deploy_files` while the version serves.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}

MCP catalog entry #

{
  "name": "list_versions",
  "title": "List deployed versions",
  "tier": "observe",
  "scenario": "CHI-L0-09",
  "summary": "This call lists your app's version history, newest first. These are the version numbers `promote` and `roll_back` take. Kinds are deploy, promote, or restart. A restart re-creates the serving version under current settings, made by `restart_application`, a rename, or the platform. Each row says whether it serves and is promotable. `promotable` marks a kept image, without advice to promote. Once retention deletes its image, promotable is false. Each environment's serving row gives `kept`, recorded `{ path, sha256 }` pairs or null, for reuse in `deploy_files`. Version numbers form one sequence per application, shared by development and production. Each deploy takes the next number. A promote, rollback, or restart row has the number of the version it applies.",
  "owners": [
    "PLD-L0-84",
    "PLD-L0-63",
    "PLD-L0-89",
    "PLD-L0-90",
    "PLD-L0-82"
  ]
}

request #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["application"]
/properties/application Your account's application id from list_applications, not its name or label.

Type: string
/properties/environment Optional. Narrows the answer to one environment's rows, development or production; leave it out and you get both environments' rows.

Type: string
Pattern: ^(development|production)$
/properties/limit Optional. The most rows you get, 1 to 200; 50 by default.

Type: integer
Minimum: 1
Maximum: 200
/properties/cursor Optional. The next_cursor of a previous answer.

Type: string

response #

JSON pointer Description and constraints
"" (root) The application's version history, newest first by start instant. The serving member is true on each environment's serving row, the deployed row that is not retired and has the latest end instant. The promotable member is true on a deployed row whose image the platform's retention has kept. A row retired by its environment's deletion is not returned. The harness_hash and harness_current members state the harness the row's image carries and whether it is the platform's current one — a promote keeps the deploy's harness, a new deploy takes the current one.

Each environment's serving row alone also carries kept: its recorded file paths and SHA-256 hashes sorted by path, or null where none were recorded.

Type: object
Required fields: ["contract_version","application","versions","next_cursor"]
/properties/contract_version Required value: 1
/properties/reference The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call.

Type: string
Pattern: ^[0-9a-f]{10}$
/properties/application Type: string
/properties/versions Type: array
/properties/versions/items Type: object
Required fields: ["id","environment","version","kind","state","artifact_hash","started_at","ended_at","outcome","serving","promotable","harness_hash","harness_current","rolled_back_from"]
/properties/versions/items/properties/id Type: string
/properties/versions/items/properties/environment Type: string
Allowed values: ["development","production"]
/properties/versions/items/properties/version Type: integer
/properties/versions/items/properties/kind A deploy writes a row of kind deploy. A promote or rollback writes a row of kind promote. A restart writes a row of kind restart, carrying the serving row's number. A restart is the re-creation of the environment's serving compute under current settings by restart_application, a rename, or the platform.

Type: string
Allowed values: ["deploy","promote","restart"]
/properties/versions/items/properties/state Type: string
Allowed values: ["deploying","deployed","failed"]
/properties/versions/items/properties/artifact_hash Type: ["string","null"]
/properties/versions/items/properties/started_at Type: string
/properties/versions/items/properties/ended_at Type: ["string","null"]
/properties/versions/items/properties/outcome Null while the row is deploying. On a failed row an object of error, the refusal's name, and detail, its sentence — or the outcome interrupted or superseded — with step, the step the run had reached where the process that ran it ended the row. On a row failed at the health gate (health_gate_failed) it also carries gate: probed (private_ingress or group_route, never the address), timeout_ms, polls, and probe_sequence. The probe_sequence is a run-length ledger of at most sixteen {answer, count} runs, answer an HTTP status or one of the transport words connection_refused, name_not_resolved, connection_reset, timed_out, tls_failed, and transport_error. The gate also carries last (the last non-200 answer's status and content_type, and its body's first 512 bytes with body_truncated only where answered_by is application), null where no HTTP answer was read. The gate also carries answered_by (application, intermediary, nothing, or unknown, the reading at the deadline or at an early end) and control_probe (its outcome and status, refusal, or cause). The gate also carries ended_early: true for an early end on an own-process client error or stopping instance. It is false at the bound and absent on rows written before the member. The gate's polls_200 counts the probes whose response was 200; an older row lacks it. The gate also carries compute: state, and with detail revision {provisioning, running, health}, instance {phase, state, restarts, exit_code, last_state}, and ready, a member {unavailable: cause} where its read failed. The cause is an HTTP status word, a platform error code, or error. The whole member is {outcome: unavailable, cause} where its read failed or overran and {state: unavailable, reason} where the seam caught the failure. The gate also carries console (outcome as lines, empty, or unavailable; lines, at most forty of at most 512 bytes and 4,096 in all; truncated; since; and cause). read_status returns the same outcome whole. No member includes an address, a header value, or the provider. On a row failed smoke_path_failed it carries smoke in place of gate: path, answer, last, compute, and console.

Type: ["object","null"]
/properties/versions/items/properties/outcome/properties/result How the row ended, on every ended row: succeeded on a deployed row, interrupted where the platform's process stopped or lost the run, superseded where a deletion ended it, and failed otherwise.

On a succeeded server run, the declared health path returned 200 three times in a row within the check's bound. Where it replaced a serving version, the routers' short resolve interval after the switch has passed. On a server deploy or a promote that is not a rollback and passes a version production does not serve, the check also requested the manifest's smoke paths after the gate passed. No other path is probed: a failing route shows in read_status' server_errors once a request reaches it.

A serverless run made no health check or smoke check.

Type: string
Allowed values: ["succeeded","failed","interrupted","superseded"]
/properties/versions/items/properties/outcome/properties/step On a failed row, the step the run had reached when the process that ran it failed or stopped it, a platform word. The word switching is a live step alone, the one a replacing act is at between its switch and its mark: a row that reached it ends deployed, so no failed row carries it. The step is absent on a row the stale sweep ended, a superseded row, and a row written before the member.

Type: string
Allowed values: ["pending_candidates","image_build","slot_guard","database_pair","issue_space","platform_credential","database_credential","declarations","realm_keys","pull_identity","compute_apply","shell_assets","migrations","health_gate","smoke_check","function_settings","finish","switching","after_finish"]
/properties/versions/items/properties/outcome/properties/build On a row failed image_build_failed or failed by the function build's tree check with function_tree_link, function_native_module, function_tree_too_large or function_count_exceeded. The build steps' own last lines, at most forty of at most 512 bytes and 4,096 in all, truncated where a bound cut them. Framing lines, registry addresses, header values, and the provider's name are left out; another address reads [address] and a token [token]. cause says why the log was not read.

Type: object
Required fields: ["outcome","output_tail","truncated"]
Additional properties: false
/properties/versions/items/properties/outcome/properties/build/properties/outcome Type: string
Allowed values: ["lines","empty","unavailable"]
/properties/versions/items/properties/outcome/properties/build/properties/output_tail Type: array
/properties/versions/items/properties/outcome/properties/build/properties/output_tail/items Type: string
/properties/versions/items/properties/outcome/properties/build/properties/truncated Type: boolean
/properties/versions/items/properties/outcome/properties/build/properties/cause Type: string
Allowed values: ["log_unavailable","log_timeout"]
/properties/versions/items/properties/outcome/properties/credentials_missing On a row that ended deployed, present where the environment reads no stored key for an upstream of the application: each such upstream and its key's stored name. The act served, and the gateway refuses that upstream's calls credential_not_in_custody until store_secret stores the key at that environment's scope of the application or at the account scope.

Type: array
/properties/versions/items/properties/outcome/properties/credentials_missing/items Type: object
Required fields: ["upstream","credential_name"]
/properties/versions/items/properties/outcome/properties/credentials_missing/items/properties/upstream The upstream's name.

Type: string
/properties/versions/items/properties/outcome/properties/credentials_missing/items/properties/credential_name The stored name of the upstream's key.

Type: string
/properties/versions/items/properties/outcome/properties/provider_credentials_missing On a row that ended deployed, present where a credential the manifest's realm member or push entry refers to is one the environment's provider cannot read: each such credential and its provider. The act served. Until store_secret stores the credential at that environment's scope of the application, the sign-in method's sign-ins fail and the push provider's deliveries end credential_unreadable. A sign-in credential then moves into place at the manifest's next submission.

Type: array
/properties/versions/items/properties/outcome/properties/provider_credentials_missing/items Type: object
Required fields: ["provider","credential_name"]
/properties/versions/items/properties/outcome/properties/provider_credentials_missing/items/properties/provider The provider the credential serves: a sign-in method, entra or apple, or a push provider, apns or fcm.

Type: string
Allowed values: ["entra","apple","apns","fcm"]
/properties/versions/items/properties/outcome/properties/provider_credentials_missing/items/properties/credential_name The credential's stored name.

Type: string
/properties/versions/items/properties/outcome/properties/error Type: string
/properties/versions/items/properties/outcome/properties/detail Type: string
/properties/versions/items/properties/outcome/properties/gate Type: object
/properties/versions/items/properties/outcome/properties/smoke Type: object
/properties/versions/items/properties/serving Type: boolean
/properties/versions/items/properties/fixes On a serving row alone: the highest severity, critical or high, fixed by the platform's moves of its running-stage base image since this version's base. It is null where none, where the version runs on the current base, or where its base is not recorded. It is read_status's base.fixes for that environment, whose base_apply says which acts take the current base.

Type: ["string","null"]
Allowed values: ["critical","high",null]
/properties/versions/items/properties/kept On each environment's serving row alone: the recorded files as { path, sha256 } pairs sorted by path, or null where none were recorded. These are the files the deploy_files list carried, excluding left-out entries and library copies the platform filled. Each hash can replace content for that file in deploy_files while the version serves. Null covers versions deployed before the platform recorded these entries, those deployed through the command, upload or artifact route, and promotes, rollbacks or restarts carrying their null. Other rows carry no kept.

Type: ["array","null"]
Maximum items: 200
/properties/versions/items/properties/kept/items Type: object
Required fields: ["path","sha256"]
Additional properties: false
/properties/versions/items/properties/kept/items/properties/path Type: string
/properties/versions/items/properties/kept/items/properties/sha256 Type: string
Pattern: ^[0-9a-f]{64}$
/properties/versions/items/properties/promotable True where the row is deployed and its image still exists in the cell registry, so promote and roll_back can take its version. It says the image exists, not that promoting it is advised; serving marks the version the environment runs. It is false on a deploying or failed row and on a deployed row whose image the platform's retention deleted, when a promote of that version is refused 409 version_image_pruned. The retention keeps the images of each environment's serving version and its twenty most recent deployed versions.

Type: boolean
/properties/versions/items/properties/harness_hash The SHA-256 of the runtime harness bundle the row's image carries, read by the platform from its own bundle at the deploy's first write and copied from the source row by a promote or rollback. It is null where the platform did not record the harness: every row written before the platform kept it, and a promote or rollback of such a row.

Type: ["string","null"]
/properties/versions/items/properties/harness_current True where harness_hash is non-null and equals the harness the platform you called bakes into new images; false where it differs or is null. A promote carries the deploy's image and its harness, so a version whose harness is not current stays so in production; a new deploy takes the current harness.

Type: boolean
/properties/versions/items/properties/timings The steps the row entered, in order, each with its start and end instants, a step a word of outcome.step's list. The last step's ended_at is null while the row is deploying and where the platform's sweep or a deletion ended the row. Null on a row written before the platform kept it.

Type: ["array","null"]
/properties/versions/items/properties/timings/items Type: object
Required fields: ["step","started_at","ended_at"]
Additional properties: false
/properties/versions/items/properties/timings/items/properties/step Type: string
/properties/versions/items/properties/timings/items/properties/started_at Type: string
/properties/versions/items/properties/timings/items/properties/ended_at Type: ["string","null"]
/properties/versions/items/properties/rolled_back_from The version production served when this rollback was accepted. Null on other rows, when production served none, and on rows written before this member. A rollback's kind remains promote.

Type: ["integer","null"]
/properties/next_cursor The cursor of the next page, or null on the last page.

Type: ["string","null"]
/properties/serving Each environment the application has, mapped to the number of the version it serves, or null where it serves none. It is read from the whole version history, whatever page you request.

Type: object
Additional properties: false
/properties/serving/properties/development Type: ["integer","null"]
/properties/serving/properties/production Type: ["integer","null"]
/properties/page $ref: #/shapes/page
/properties/detail Type: string

Complete payload contract #

{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "Optional. Narrows the answer to one environment's rows, `development` or `production`; leave it out and you get both environments' rows."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "description": "Optional. The most rows you get, 1 to 200; 50 by default."
      },
      "cursor": {
        "type": "string",
        "description": "Optional. The `next_cursor` of a previous answer."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "versions",
      "next_cursor"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "application": {
        "type": "string"
      },
      "versions": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "environment",
            "version",
            "kind",
            "state",
            "artifact_hash",
            "started_at",
            "ended_at",
            "outcome",
            "serving",
            "promotable",
            "harness_hash",
            "harness_current",
            "rolled_back_from"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "environment": {
              "type": "string",
              "enum": [
                "development",
                "production"
              ]
            },
            "version": {
              "type": "integer"
            },
            "kind": {
              "type": "string",
              "enum": [
                "deploy",
                "promote",
                "restart"
              ],
              "description": "A deploy writes a row of kind deploy. A promote or rollback writes a row of kind promote. A restart writes a row of kind restart, carrying the serving row's number (PLD-L0-63). A restart is the re-creation of the environment's serving compute under current settings by `restart_application`, a rename, or the platform (PLD-L0-84)."
            },
            "state": {
              "type": "string",
              "enum": [
                "deploying",
                "deployed",
                "failed"
              ]
            },
            "artifact_hash": {
              "type": [
                "string",
                "null"
              ]
            },
            "started_at": {
              "type": "string"
            },
            "ended_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "outcome": {
              "type": [
                "object",
                "null"
              ],
              "description": "Null while the row is deploying. On a failed row an object of error, the refusal's name, and detail, its sentence — or the outcome interrupted or superseded — with step, the step the run had reached where the process that ran it ended the row (PLD-L0-63). On a row failed at the health gate (health_gate_failed) it also carries gate: probed (private_ingress or group_route, never the address), timeout_ms, polls, and probe_sequence. The probe_sequence is a run-length ledger of at most sixteen {answer, count} runs, answer an HTTP status or one of the transport words connection_refused, name_not_resolved, connection_reset, timed_out, tls_failed, and transport_error. The gate also carries last (the last non-200 answer's status and content_type, and its body's first 512 bytes with body_truncated only where answered_by is application), null where no HTTP answer was read. The gate also carries answered_by (application, intermediary, nothing, or unknown, the reading at the deadline or at an early end) and control_probe (its outcome and status, refusal, or cause). The gate also carries ended_early: true for an early end on an own-process client error or stopping instance. It is false at the bound and absent on rows written before the member. The gate's polls_200 counts the probes whose response was 200; an older row lacks it. The gate also carries compute: state, and with detail revision {provisioning, running, health}, instance {phase, state, restarts, exit_code, last_state}, and ready, a member {unavailable: cause} where its read failed. The cause is an HTTP status word, a platform error code, or error. The whole member is {outcome: unavailable, cause} where its read failed or overran and {state: unavailable, reason} where the seam caught the failure. The gate also carries console (outcome as lines, empty, or unavailable; lines, at most forty of at most 512 bytes and 4,096 in all; truncated; since; and cause). read_status returns the same outcome whole. No member includes an address, a header value, or the provider (PLD-L0-59; PLD-L0-63). On a row failed `smoke_path_failed` it carries `smoke` in place of `gate`: path, answer, last, compute, and console (PLD-L0-59).",
              "properties": {
                "result": {
                  "type": "string",
                  "enum": [
                    "succeeded",
                    "failed",
                    "interrupted",
                    "superseded"
                  ],
                  "description": "How the row ended, on every ended row: `succeeded` on a deployed row, `interrupted` where the platform's process stopped or lost the run, `superseded` where a deletion ended it, and `failed` otherwise (PLD-L0-63).\n\nOn a `succeeded` server run, the declared health path returned 200 three times in a row within the check's bound. Where it replaced a serving version, the routers' short resolve interval after the switch has passed. On a server deploy or a promote that is not a rollback and passes a version production does not serve, the check also requested the manifest's smoke paths after the gate passed (MAN-18). No other path is probed: a failing route shows in `read_status`' `server_errors` once a request reaches it.\n\nA serverless run made no health check or smoke check."
                },
                "step": {
                  "type": "string",
                  "enum": [
                    "pending_candidates",
                    "image_build",
                    "slot_guard",
                    "database_pair",
                    "issue_space",
                    "platform_credential",
                    "database_credential",
                    "declarations",
                    "realm_keys",
                    "pull_identity",
                    "compute_apply",
                    "shell_assets",
                    "migrations",
                    "health_gate",
                    "smoke_check",
                    "function_settings",
                    "finish",
                    "switching",
                    "after_finish"
                  ],
                  "description": "On a failed row, the step the run had reached when the process that ran it failed or stopped it, a platform word. The word `switching` is a live step alone, the one a replacing act is at between its switch and its mark: a row that reached it ends `deployed`, so no failed row carries it. The step is absent on a row the stale sweep ended, a superseded row, and a row written before the member (PLD-L0-63)."
                },
                "build": {
                  "type": "object",
                  "required": [
                    "outcome",
                    "output_tail",
                    "truncated"
                  ],
                  "properties": {
                    "outcome": {
                      "type": "string",
                      "enum": [
                        "lines",
                        "empty",
                        "unavailable"
                      ]
                    },
                    "output_tail": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "truncated": {
                      "type": "boolean"
                    },
                    "cause": {
                      "type": "string",
                      "enum": [
                        "log_unavailable",
                        "log_timeout"
                      ]
                    }
                  },
                  "additionalProperties": false,
                  "description": "On a row failed `image_build_failed` or failed by the function build's tree check with `function_tree_link`, `function_native_module`, `function_tree_too_large` or `function_count_exceeded`. The build steps' own last lines, at most forty of at most 512 bytes and 4,096 in all, `truncated` where a bound cut them. Framing lines, registry addresses, header values, and the provider's name are left out; another address reads `[address]` and a token `[token]`. `cause` says why the log was not read (PLD-L0-90; PLD-L0-59)."
                },
                "credentials_missing": {
                  "type": "array",
                  "description": "On a row that ended deployed, present where the environment reads no stored key for an upstream of the application: each such upstream and its key's stored name (EGW-L0-02). The act served, and the gateway refuses that upstream's calls `credential_not_in_custody` until `store_secret` stores the key at that environment's scope of the application or at the account scope.",
                  "items": {
                    "type": "object",
                    "required": [
                      "upstream",
                      "credential_name"
                    ],
                    "properties": {
                      "upstream": {
                        "type": "string",
                        "description": "The upstream's name."
                      },
                      "credential_name": {
                        "type": "string",
                        "description": "The stored name of the upstream's key."
                      }
                    }
                  }
                },
                "provider_credentials_missing": {
                  "type": "array",
                  "description": "On a row that ended deployed, present where a credential the manifest's `realm` member or push entry refers to is one the environment's provider cannot read: each such credential and its provider (ACS-L0-09; PSH-L0-01). The act served. Until `store_secret` stores the credential at that environment's scope of the application, the sign-in method's sign-ins fail and the push provider's deliveries end `credential_unreadable`. A sign-in credential then moves into place at the manifest's next submission.",
                  "items": {
                    "type": "object",
                    "required": [
                      "provider",
                      "credential_name"
                    ],
                    "properties": {
                      "provider": {
                        "type": "string",
                        "enum": [
                          "entra",
                          "apple",
                          "apns",
                          "fcm"
                        ],
                        "description": "The provider the credential serves: a sign-in method, `entra` or `apple`, or a push provider, `apns` or `fcm`."
                      },
                      "credential_name": {
                        "type": "string",
                        "description": "The credential's stored name."
                      }
                    }
                  }
                },
                "error": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                },
                "gate": {
                  "type": "object"
                },
                "smoke": {
                  "type": "object"
                }
              }
            },
            "serving": {
              "type": "boolean"
            },
            "fixes": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "critical",
                "high",
                null
              ],
              "description": "On a serving row alone: the highest severity, `critical` or `high`, fixed by the platform's moves of its running-stage base image since this version's base. It is null where none, where the version runs on the current base, or where its base is not recorded. It is read_status's `base.fixes` for that environment, whose `base_apply` says which acts take the current base (PLD-L0-82)."
            },
            "kept": {
              "type": [
                "array",
                "null"
              ],
              "maxItems": 200,
              "items": {
                "type": "object",
                "required": [
                  "path",
                  "sha256"
                ],
                "properties": {
                  "path": {
                    "type": "string"
                  },
                  "sha256": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{64}$"
                  }
                },
                "additionalProperties": false
              },
              "description": "On each environment's serving row alone: the recorded files as `{ path, sha256 }` pairs sorted by path, or null where none were recorded. These are the files the `deploy_files` list carried, excluding left-out entries and library copies the platform filled. Each hash can replace `content` for that file in `deploy_files` while the version serves. Null covers versions deployed before the platform recorded these entries, those deployed through the command, upload or artifact route, and promotes, rollbacks or restarts carrying their null. Other rows carry no `kept` (PLD-L0-63)."
            },
            "promotable": {
              "type": "boolean",
              "description": "True where the row is `deployed` and its image still exists in the cell registry, so `promote` and `roll_back` can take its version. It says the image exists, not that promoting it is advised; `serving` marks the version the environment runs. It is false on a `deploying` or `failed` row and on a deployed row whose image the platform's retention deleted, when a promote of that version is refused 409 `version_image_pruned`. The retention keeps the images of each environment's serving version and its twenty most recent deployed versions (PLD-L0-63)."
            },
            "harness_hash": {
              "type": [
                "string",
                "null"
              ],
              "description": "The SHA-256 of the runtime harness bundle the row's image carries, read by the platform from its own bundle at the deploy's first write and copied from the source row by a promote or rollback. It is null where the platform did not record the harness: every row written before the platform kept it, and a promote or rollback of such a row (PLD-L0-63)."
            },
            "harness_current": {
              "type": "boolean",
              "description": "True where `harness_hash` is non-null and equals the harness the platform you called bakes into new images; false where it differs or is null. A promote carries the deploy's image and its harness, so a version whose harness is not current stays so in production; a new deploy takes the current harness (PLD-L0-63)."
            },
            "timings": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "object",
                "required": [
                  "step",
                  "started_at",
                  "ended_at"
                ],
                "properties": {
                  "step": {
                    "type": "string"
                  },
                  "started_at": {
                    "type": "string"
                  },
                  "ended_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "additionalProperties": false
              },
              "description": "The steps the row entered, in order, each with its start and end instants, a step a word of `outcome.step`'s list. The last step's `ended_at` is null while the row is deploying and where the platform's sweep or a deletion ended the row. Null on a row written before the platform kept it (PLD-L0-89)."
            },
            "rolled_back_from": {
              "type": [
                "integer",
                "null"
              ],
              "description": "The version production served when this rollback was accepted. Null on other rows, when production served none, and on rows written before this member. A rollback's `kind` remains `promote`."
            }
          }
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ],
        "description": "The cursor of the next page, or null on the last page."
      },
      "serving": {
        "type": "object",
        "properties": {
          "development": {
            "type": [
              "integer",
              "null"
            ]
          },
          "production": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "additionalProperties": false,
        "description": "Each environment the application has, mapped to the number of the version it serves, or null where it serves none. It is read from the whole version history, whatever page you request (PLD-L0-63)."
      },
      "page": {
        "$ref": "#/shapes/page"
      },
      "detail": {
        "type": "string"
      }
    },
    "description": "The application's version history, newest first by start instant. The `serving` member is true on each environment's serving row, the deployed row that is not retired and has the latest end instant. The `promotable` member is true on a deployed row whose image the platform's retention has kept. A row retired by its environment's deletion is not returned. The `harness_hash` and `harness_current` members state the harness the row's image carries and whether it is the platform's current one — a promote keeps the deploy's harness, a new deploy takes the current one (PLD-L0-63).\n\nEach environment's serving row alone also carries `kept`: its recorded file paths and SHA-256 hashes sorted by path, or null where none were recorded (PLD-L0-63)."
  }
}

Shared contracts #