deploy #

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/deploy, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_deploy.

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 #

Deploy a stored ZIP or start a prepared upload.

artifact deploys a storage ZIP. upload only retries a prepared start. A tool with no shell uses deploy_files. With a shell and the app's whole folder, use deploy_command where it works. A script passes artifact to deploy a stored zip.

A gateway error, closed connection or non-platform response leaves the outcome unknown. A read_status row of kind deploy, started after your call, confirms a start. A retry is allowed only when status shows no start, using pending_upload.retry where supplied.

Details: read_documentation /cloud/getting-started/ways-to-deploy/.

More about this action #

A deploy goes to production until create_environment adds development, and to development after that; promote then moves a version to production. A deploy past the size's 24-hour cap, the deploys-per-day row of read_plan_quotas, is refused deploys_per_day_exceeded. Both sizes have the same cap.

The request has an artifact form and an upload form. Pass artifact for a stored ZIP. The turnzero command's preparing call passes zip_sha256 on the HTTP route, and its start passes upload. Pass upload yourself only to retry that start, as read_status's pending_upload.retry gives it. commit is optional on a start with upload or artifact; wait_seconds is optional on every start.

For a folder on your computer, call deploy_command and run its returned line. It writes and starts nothing; the line zips, uploads, and deploys the folder when run. Choose the route with read_documentation, page /cloud/getting-started/ways-to-deploy/.

While a deploy of the environment is in flight, a call that passes the same artifact hash, or the upload that deploy read, returns that deploy. Any other call is refused deploy_in_flight, even an upload of identical bytes.

Where the upload arrived and no deploy read it, read_status lists it as pending_upload on the environment the deploy goes to. Once the cause of the refusal is cleared, make the call in its retry. Where retry is null, call deploy_command and run its line; fix the folder first where its zip was refused. A call that passes upload reads the zip the command wrote and deploys it as the artifact form does. An upload with no such file is refused upload_not_found: it was not uploaded yet, it expired unused, a later preparing call replaced it, or a deploy that has ended already read it.

For a script, use the artifact form. Upload the zip to a declared storage area under a single-use grant from mint_upload_grant, then pass its area, file name, and SHA-256 in artifact. The environment member of artifact says where the file is stored, never where it deploys.

The command's start passes commit where the folder has a Git repository, and an artifact start may pass it. The version keeps the commit, and so do its promote, its rollback, and the build record in the application's issue-tracking space. The command's preparing call records rotate_database_credential on the upload's grant where its line carries the flag. A start of that upload that passes no such member still applies it, and a refused start's retry includes it.

The platform then builds the artifact's image with its declared runtime dependencies, starts it, and checks its health. Development of either size, and production of a shared-0.5gb application, run as a pod where the platform has a shared group of that kind open. Where the cell has no such group, the environment runs as a container app. Where every such group is full, the deploy is refused group_full. Production of a shared-1gb application runs as its own container app. A deploy to a halted production is refused target_environment_halted. A deploy to a halted development environment ends the halt once it has passed its refusals.

A deploy typically takes up to about two and a half minutes on a development pod and three and a half on its own container app. Most of that is the image build: up to about two and a quarter minutes for a first version, and a minute and a half for a later one. Where the artifact installs nothing and ships no native module, the platform usually assembles the image without running a build. Such a deploy takes about 15 seconds on a pod and about 45 on its own container app, up to about 80 for its first. The health check's own limit is 180 seconds. Each version-history row records its step timings, and a failed build's outcome contains its last lines.

An answer that did not settle gives the next call, read_status, whose environment's deploy member gives the step. After an answer that is not this platform's own, make that read first. Call deploy again only where that member shows no row of kind deploy with a started_at later than your call. An upload still listed in pending_upload was not started. Each server holds one wait per application. This call's wait takes that place. A concurrent held read_status for that application on the same server returns at once, from its own read.

An external API's stored key goes through declare_outbound_api, whose sdk_settings let an unchanged SDK reach the API. A value your code reads itself is bound in the manifest's settings.

The environment argument: left out, the deploy goes to the application's deploy target: production with one environment, development with two.

The artifact argument: an absent file or a hash mismatch is refused by name. So is the platform's deploy area, which only the upload form reads.

The upload argument: the upload's id, which the turnzero command's prepared: line prints and its start passes. Pass it yourself only to start that upload again, where its start was refused or never made, as the retry of pending_upload in read_status shows.

The wait_seconds argument: the seconds, 1 to 45, counted from the call's arrival, that the call waits for the version-history row it started. It replies when that row ends or the seconds pass. A value outside that range is refused invalid_request, and its detail gives 45 as the bound.

The commit argument: on a start you make yourself, one that passes upload or artifact, the commit the code was built from. It is 7 to 64 lower-case hexadecimal characters, as git rev-parse HEAD prints. On the upload path, leave it out: the turnzero command reads the folder's commit, where it has a Git repository, and passes it on its start.

The rotate_database_credential argument: on production, true rotates the database credential. The preparing call records it on the upload's grant, and its start applies it.

Access and action metadata #

{
  "name": "deploy",
  "resource": "environment",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "Deploy a built artifact to the environment the application's deploys go to: production on an application with one environment, and development on one with two, where production receives a version through `promote`. The command alone passes `zip_sha256`, on the HTTP action route, and over this connection a call that passes it is refused `local_route_required`. Called with that `upload`, by the command's start or by a retry of a start refused or never made, it starts the deploy. So does a call with an `artifact` in a storage area bound to the application. It returns 202 `deploying`, or, with `wait_seconds` up to 45, holds its answer until the deploy ends. The compute grain is chosen before any compute act: a development environment of either size, and the production environment of a `shared-0.5gb` application, run as a pod in the hosting cell's admitting group of its kind with headroom, and as a container app where the cell has none. The production environment of a `shared-1gb` or unlimited application runs as its own container app. A full group is refused `group_full` and a row in a group of another kind `group_kind_mismatch`. A grain that differs from the existing compute's is the grain migration, the previous compute deleted after its hold. The hosts a manifest's `egress` member declares are reached in the tunnel mode with no key applied; a host called on a stored key is a declared upstream (`declare_outbound_api`), its key applied at the gateway's edge, and the container holding at most the upstream's egress key. The start may pass `commit`, the commit the code was built from. The version keeps it, its promote and rollback carry it, and so does the build row the platform writes into the application's own issue-tracking space. On a deploy to production, `rotate_database_credential` true also sets a new production database password, as a promote does; the command's preparing call records it for the upload's start. Its answer leads with a `summary`; unsettled, it gives the `next` call, a `read_status` that shows the `step`.\n\nAn answer that is not this platform's own, such as a gateway's error page or a closed connection, says nothing about whether the deploy started. Read `read_status` with `wait_seconds` first: the deploy started only where the environment's deploy member shows the kind deploy with a `started_at` later than your call. Where `pending_upload` still lists the upload, its start was not made: make the call its `retry` carries. Call again only where that read shows no start.\n\nChoose the route with read_documentation, page /cloud/getting-started/ways-to-deploy/.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}

MCP catalog entry #

{
  "name": "deploy",
  "title": "Deploy application",
  "tier": "reversible",
  "scenario": "CHI-L0-07",
  "summary": "Deploy a stored ZIP or start a prepared upload.\n\n`artifact` deploys a storage ZIP. `upload` only retries a prepared start. A tool with no shell uses `deploy_files`. With a shell and the app's whole folder, use `deploy_command` where it works. A script passes `artifact` to deploy a stored zip.\n\nA gateway error, closed connection or non-platform response leaves the outcome unknown. A `read_status` row of kind deploy, started after your call, confirms a start. A retry is allowed only when status shows no start, using `pending_upload.retry` where supplied.\n\nDetails: read_documentation /cloud/getting-started/ways-to-deploy/.",
  "owners": [
    "PLD-L0-43",
    "PLD-L0-127",
    "PLD-L0-136",
    "MAN-09",
    "EGW-L0-01",
    "EGW-L0-11",
    "PLD-L0-63",
    "PLD-L0-40",
    "PLD-L0-41",
    "PRC-L0-16",
    "OST-L0-01",
    "MAPI-04",
    "OST-L0-08",
    "PLD-L0-86",
    "PLD-L0-89",
    "PLD-L0-90",
    "MAN-14",
    "SEC-L0-18",
    "ITS-L0-02"
  ]
}

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 With one environment, default production. Development needs create_environment, else environment_not_created. With two, default development, and production is refused environment_unavailable; production changes use promote.

Type: string
Allowed values: ["development","production"]
/properties/artifact Stored ZIP. Missing file, hash mismatch or the platform deploy area is refused by name. Excludes upload, else invalid_request.

Type: object
Required fields: ["area","name","hash"]
/properties/artifact/properties/area Type: string
/properties/artifact/properties/name Type: string
/properties/artifact/properties/hash SHA-256 of ZIP bytes, hexadecimal.

Type: string
Pattern: ^[a-f0-9]{64}$
/properties/artifact/properties/environment Storage partition, not deploy target. Default the deployment's environment.

Type: string
Pattern: ^(development|production)$
/properties/upload Prepared upload id from the command's prepared: line, only for retrying its start. No file gives upload_not_found. Changed SHA-256 gives upload_hash_mismatch, which retries cannot start.

Type: string
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
/properties/zip_sha256 Taken on the HTTP action route alone, from the turnzero command's preparing call: the SHA-256 of the zip the command made and will upload, 64 lower-case hexadecimal characters. The MCP tool has no zip_sha256 member, and a call that passes it there is refused local_route_required. From a tool, call deploy_command and run the line it returns. A value of another form, or one passed with artifact or upload, is refused invalid_request.

Type: string
HTTP action route only, never an MCP tool argument: true
/properties/wait_seconds Seconds to wait for the deploy to end. Out of range gives invalid_request.

Type: integer
Minimum: 1
Maximum: 45
/properties/commit Build commit from git rev-parse HEAD, on a self-made start only. Malformed or supplied during preparation gives invalid_request. Omitted records no commit.

Type: string
Pattern: ^[0-9a-f]{7,64}$
/properties/rotate_database_credential True also changes the production database-role password. Other values, or development, give invalid_request.

Type: boolean

response #

JSON pointer Description and constraints
"" (root) With artifact or upload, 202 at once with next, before the build starts: the environment's version-history row was inserted deploying, and the build, the apply, the publish, and the health gate continue after the answer. With wait_seconds, the answer is held until the row ends: settled, it is 200 with the state deployed or failed and the row's outcome; unsettled, it is 202 with next. While a deploy of the environment is in flight, a second deploy with artifact returns it for the same artifact hash and is refused deploy_in_flight for a different one. A call passing upload returns it only where that deploy read the same upload, and any other upload is refused deploy_in_flight, identical bytes included. On the HTTP action route alone, the command's preparing call passes zip_sha256 and returns 200 with the state awaiting_upload and upload.

Type: object
Required fields: ["contract_version","application","environment","state"]
/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/summary The answer's first member: one sentence giving the environment's state and serving version and, for the row this call started, its version, kind, step, and seconds since it started, or how it ended. Absent with awaiting_upload.

Where this call's held answer ends deployed on production, the summary may close with an invitation warning. This applies to an invited audience whose production realm is absent, or holds no end user other than test end users and no standing invitation. The warning says no invited user can sign in to production yet and tells the caller to use invite_end_user. It is added last, only if the whole summary fits its budget. A failed realm read adds no warning.

Type: string
/properties/application Type: string
/properties/environment Type: string
/properties/version The version number the deploy's history row carries: returned with deploying, deployed, and failed, and absent with the other states.

Type: integer
/properties/state deploying on the 202 answer, which precedes the row's end. The state is deployed or failed on the 200 answer, where the request's wait_seconds saw the row end. The state is awaiting_upload on the 200 answer to the turnzero command's preparing call on the HTTP action route, which passes zip_sha256; it inserts no version row and starts nothing.

Type: string
Pattern: ^(deploying|deployed|failed|awaiting_upload)$
/properties/hostname The hostname of the environment the deploy goes to: returned with deploying, deployed, and failed, and absent with the other states.

Type: string
/properties/health_path The recorded manifest's health path, which the health gate that follows this act will probe, cut at 256 characters as the gate's record keeps it. It is returned where this call starts the deploy. It is absent with awaiting_upload, which starts no deploy, the preparing answer carrying recorded_health_path instead, and on an answer that joins a deploy already in flight.

Type: string
/properties/recorded_health_path With the state awaiting_upload: the recorded manifest's health path, whole and never cut. It is absent for a serverless application. It is absent too where no manifest exists, a case the preparing call refuses. The turnzero command reads it before its upload, refusing where the start's health check would.

Type: string
/properties/served_version Present with the state awaiting_upload: the environment's serving version as read_status shows it, null where none serves. With recorded_health_path it tells the turnzero command whether the start's health check would read the zip.

Type: ["integer","null"]
/properties/settled Present where the request carried wait_seconds. True where the one read after the wait found the row this call started ended, whatever ended the wait. False means that read found the row still deploying, or could not read it, and not that it failed: next gives the call that waits on it.

Type: boolean
/properties/waited_ms Present where the request carried wait_seconds: the milliseconds the answer was held after the row started.

Type: integer
Minimum: 0
/properties/outcome Present where the wait settled: the row's outcome as list_versions returns it. Its result is succeeded on a deployed row and failed, interrupted, or superseded on a failed one.

Type: object
/properties/server_errors_since Present where the wait saw the row end deployed: the router's 5xx responses since the version began serving, as check_deploy's last_release counts them. count runs from since, the later of the row's end and seven days before the read. It is capped at 500, and capped is true where the cap was met, the count then a floor. It covers only the routes requested in that time, so a route nobody requested counts nothing. A route listed in the manifest's smoke_paths is checked before each deploy and promote switches, and that check is not in this count. Where the read failed, unread carries its reason. Absent on every other response.

/properties/server_errors_since/oneOf/0 Type: object
Required fields: ["count","since","capped"]
/properties/server_errors_since/oneOf/0/properties/count Type: integer
Minimum: 0
Maximum: 500
/properties/server_errors_since/oneOf/0/properties/since Type: string
/properties/server_errors_since/oneOf/0/properties/capped Type: boolean
/properties/server_errors_since/oneOf/1 Type: object
Required fields: ["unread"]
Additional properties: false
/properties/server_errors_since/oneOf/1/properties/unread Why the count was not read: failed, timed_out, or read_status's own word for its server_errors member, such as unavailable.

Type: string
/properties/upload Present with the state awaiting_upload alone, the answer to the turnzero command's preparing call on the HTTP action route: one pending upload of the zip whose SHA-256 the call passed, under a short-lived grant for that one zip, returned in grant. Its one write puts the zip, and its one start deploys it. After that start, the same grant serves the command's own progress reads of that deploy, until five minutes after it ends and never past fifteen minutes after the start. The same zip sent again under the grant before expires_at, once its write landed and while no later call replaced the upload, receives 200 with the file's name, area, size, and SHA-256 and writes nothing; other bytes under the spent grant are refused transfer_grant_spent. A later preparing call for the application replaces an upload no deploy has read.

Type: object
Required fields: ["id","expires_at","max_bytes","grant"]
Additional properties: false
/properties/upload/properties/id The upload's id, which the turnzero command's prepared: line prints and its start passes as upload.

Type: string
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
/properties/upload/properties/expires_at When the upload's grant stops serving, as an ISO 8601 instant. A write or a start under the grant after it is refused transfer_grant_expired, and a deploy_command call returns a new line.

Type: string
/properties/upload/properties/max_bytes The most bytes the zip may carry, the configured bound.

Type: integer
/properties/upload/properties/grant The upload's grant, its value alone. The deploy command from 0.8.0 reads it here and presents it as the bearer of the upload, the start, and the progress read. It is returned on the HTTP action route alone, in the answer to the preparing call.

Type: string
/properties/next The exact read_status call that reads the deploy to its end. With the state awaiting_upload it is made where the command returned before the outcome, or to read the whole record. It carries the request's wait_seconds, which that answer did not wait on; where the command ended 3, nothing started, and its printed refusal is the way on. With deploying, it is present at once without wait_seconds, and where the wait did not settle.

Type: object
Required fields: ["action","arguments"]
Additional properties: false
/properties/next/properties/action Required value: read_status
/properties/next/properties/arguments Type: object
Required fields: ["application","environment","wait_seconds"]
Additional properties: false
/properties/next/properties/arguments/properties/application Type: string
/properties/next/properties/arguments/properties/environment Type: string
Pattern: ^(development|production)$
/properties/next/properties/arguments/properties/wait_seconds The read's wait: 45, or the preparing call's own wait_seconds, 45 where it gave none.

Type: integer
Minimum: 1
Maximum: 45
/properties/detail With the state deploying, says how the deploy's step and end are read: the next call, read_status with wait_seconds 45, or a read every ten seconds.

With deployed or failed, says how the row ended. For a deployed run that entered health_gate, it says the check requested the health path and any smoke paths the manifest lists. It says to request the other routes, read read_status's server_errors, and read read_logs for errors. It closes that form by saying the health path returned status 200 three times in a row, so that path needs no further request.

With deployed and a run that entered no health_gate, it says no health check or smoke check ran and to request its pages or routes and read read_logs for errors. A row with no step list uses the health-check form.

With awaiting_upload, identifies the upload's grant, which deploys to the answer's environment only the zip whose SHA-256 the call passed, and gives no line to run.

Type: string
/properties/manifest_notice present where the zip's manifest.json, less its application member, differs or does not parse, or a lib/ copy is unread, uncompared, or unpaired.

Type: string
/properties/artifact_notice present where the build will not run an install script or rebuild a binding.gyp of the root or a workspace member, listing each and each member package.json left unread.

Type: string
/properties/client_notice present where the zip's client/ folder holds a file beyond the shell or a name the publish skips: counts the files the router serves at their own paths, listing twenty beyond the shell and twenty skipped, then counting the rest.

Type: string
/properties/database_notice present where the target environment declares or holds a database and the deploy serves APP_DATABASE_URL on the pooler's port. The fixed notice describes transaction pooling's limits and APP_DATABASE_DIRECT_URL for work requiring one held server connection. It rides an at-once answer and a held answer, and deploy_files with check_only, but no preparing answer. It refuses nothing.

Type: string
/properties/usage_notice Present while the application's usage state is over, absent otherwise. For a size, the daily check found stored data at or past its served quantity. It lists the over measures and what each refuses. A size has no backend-actions or data-transfer quantity. It lists file puts on bound storage areas for stored data until the next successful daily pass or a raised quantity. It also says that the deploy proceeded. The deploy itself is never refused for usage.

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",
        "enum": [
          "development",
          "production"
        ],
        "description": "With one environment, default production. Development needs `create_environment`, else `environment_not_created`. With two, default development, and production is refused `environment_unavailable`; production changes use `promote`."
      },
      "artifact": {
        "type": "object",
        "required": [
          "area",
          "name",
          "hash"
        ],
        "properties": {
          "area": {
            "type": "string",
            "description": ""
          },
          "name": {
            "type": "string",
            "description": ""
          },
          "hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "SHA-256 of ZIP bytes, hexadecimal."
          },
          "environment": {
            "type": "string",
            "pattern": "^(development|production)$",
            "description": "Storage partition, not deploy target. Default the deployment's environment."
          }
        },
        "description": "Stored ZIP. Missing file, hash mismatch or the platform deploy area is refused by name. Excludes `upload`, else `invalid_request`."
      },
      "upload": {
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
        "description": "Prepared upload id from the command's `prepared:` line, only for retrying its start. No file gives `upload_not_found`. Changed SHA-256 gives `upload_hash_mismatch`, which retries cannot start."
      },
      "zip_sha256": {
        "type": "string",
        "x-wire-only": true,
        "description": "Taken on the HTTP action route alone, from the turnzero command's preparing call: the SHA-256 of the zip the command made and will upload, 64 lower-case hexadecimal characters. The MCP tool has no `zip_sha256` member, and a call that passes it there is refused `local_route_required`. From a tool, call `deploy_command` and run the line it returns. A value of another form, or one passed with `artifact` or `upload`, is refused `invalid_request`."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "Seconds to wait for the deploy to end. Out of range gives `invalid_request`."
      },
      "commit": {
        "type": "string",
        "pattern": "^[0-9a-f]{7,64}$",
        "description": "Build commit from `git rev-parse HEAD`, on a self-made start only. Malformed or supplied during preparation gives `invalid_request`. Omitted records no commit."
      },
      "rotate_database_credential": {
        "type": "boolean",
        "description": "True also changes the production database-role password. Other values, or development, give `invalid_request`."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "environment",
      "state"
    ],
    "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."
      },
      "summary": {
        "type": "string",
        "description": "The answer's first member: one sentence giving the environment's state and serving version and, for the row this call started, its version, kind, step, and seconds since it started, or how it ended (PLD-L0-63). Absent with `awaiting_upload`.\n\nWhere this call's held answer ends `deployed` on production, the summary may close with an invitation warning. This applies to an `invited` audience whose production realm is absent, or holds no end user other than test end users and no standing invitation. The warning says no invited user can sign in to production yet and tells the caller to use `invite_end_user`. It is added last, only if the whole summary fits its budget. A failed realm read adds no warning."
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "type": "string"
      },
      "version": {
        "type": "integer",
        "description": "The version number the deploy's history row carries: returned with `deploying`, `deployed`, and `failed`, and absent with the other states."
      },
      "state": {
        "type": "string",
        "pattern": "^(deploying|deployed|failed|awaiting_upload)$",
        "description": "`deploying` on the 202 answer, which precedes the row's end. The state is `deployed` or `failed` on the 200 answer, where the request's `wait_seconds` saw the row end. The state is `awaiting_upload` on the 200 answer to the turnzero command's preparing call on the HTTP action route, which passes `zip_sha256`; it inserts no version row and starts nothing."
      },
      "hostname": {
        "type": "string",
        "description": "The hostname of the environment the deploy goes to: returned with `deploying`, `deployed`, and `failed`, and absent with the other states."
      },
      "health_path": {
        "type": "string",
        "description": "The recorded manifest's health path, which the health gate that follows this act will probe, cut at 256 characters as the gate's record keeps it. It is returned where this call starts the deploy. It is absent with `awaiting_upload`, which starts no deploy, the preparing answer carrying `recorded_health_path` instead, and on an answer that joins a deploy already in flight (PLD-L0-63)."
      },
      "recorded_health_path": {
        "type": "string",
        "description": "With the state `awaiting_upload`: the recorded manifest's health path, whole and never cut. It is absent for a serverless application. It is absent too where no manifest exists, a case the preparing call refuses. The turnzero command reads it before its upload, refusing where the start's health check would (PLD-L0-86; PLD-L0-94)."
      },
      "served_version": {
        "type": [
          "integer",
          "null"
        ],
        "description": "Present with the state `awaiting_upload`: the environment's serving version as `read_status` shows it, null where none serves. With `recorded_health_path` it tells the turnzero command whether the start's health check would read the zip (PLD-L0-86)."
      },
      "settled": {
        "type": "boolean",
        "description": "Present where the request carried `wait_seconds`. True where the one read after the wait found the row this call started ended, whatever ended the wait. False means that read found the row still deploying, or could not read it, and not that it failed: `next` gives the call that waits on it (MAPI-04; PLD-L0-63)."
      },
      "waited_ms": {
        "type": "integer",
        "minimum": 0,
        "description": "Present where the request carried `wait_seconds`: the milliseconds the answer was held after the row started."
      },
      "outcome": {
        "type": "object",
        "description": "Present where the wait settled: the row's `outcome` as `list_versions` returns it. Its `result` is `succeeded` on a deployed row and `failed`, `interrupted`, or `superseded` on a failed one (PLD-L0-63)."
      },
      "server_errors_since": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "count",
              "since",
              "capped"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 500
              },
              "since": {
                "type": "string"
              },
              "capped": {
                "type": "boolean"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "unread"
            ],
            "properties": {
              "unread": {
                "type": "string",
                "description": "Why the count was not read: `failed`, `timed_out`, or `read_status`'s own word for its `server_errors` member, such as `unavailable`."
              }
            },
            "additionalProperties": false
          }
        ],
        "description": "Present where the wait saw the row end `deployed`: the router's 5xx responses since the version began serving, as `check_deploy`'s `last_release` counts them. `count` runs from `since`, the later of the row's end and seven days before the read. It is capped at 500, and `capped` is true where the cap was met, the count then a floor. It covers only the routes requested in that time, so a route nobody requested counts nothing. A route listed in the manifest's `smoke_paths` is checked before each deploy and promote switches, and that check is not in this count. Where the read failed, `unread` carries its reason. Absent on every other response."
      },
      "upload": {
        "type": "object",
        "required": [
          "id",
          "expires_at",
          "max_bytes",
          "grant"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
            "description": "The upload's id, which the turnzero command's `prepared:` line prints and its start passes as `upload`."
          },
          "expires_at": {
            "type": "string",
            "description": "When the upload's grant stops serving, as an ISO 8601 instant. A write or a start under the grant after it is refused `transfer_grant_expired`, and a `deploy_command` call returns a new line."
          },
          "max_bytes": {
            "type": "integer",
            "description": "The most bytes the zip may carry, the configured bound."
          },
          "grant": {
            "type": "string",
            "description": "The upload's grant, its value alone. The deploy command from 0.8.0 reads it here and presents it as the bearer of the upload, the start, and the progress read. It is returned on the HTTP action route alone, in the answer to the preparing call."
          }
        },
        "additionalProperties": false,
        "description": "Present with the state `awaiting_upload` alone, the answer to the turnzero command's preparing call on the HTTP action route: one pending upload of the zip whose SHA-256 the call passed, under a short-lived grant for that one zip, returned in `grant`. Its one write puts the zip, and its one start deploys it. After that start, the same grant serves the command's own progress reads of that deploy, until five minutes after it ends and never past fifteen minutes after the start. The same zip sent again under the grant before `expires_at`, once its write landed and while no later call replaced the upload, receives 200 with the file's name, area, size, and SHA-256 and writes nothing; other bytes under the spent grant are refused `transfer_grant_spent`. A later preparing call for the application replaces an upload no deploy has read."
      },
      "next": {
        "type": "object",
        "required": [
          "action",
          "arguments"
        ],
        "properties": {
          "action": {
            "const": "read_status"
          },
          "arguments": {
            "type": "object",
            "required": [
              "application",
              "environment",
              "wait_seconds"
            ],
            "properties": {
              "application": {
                "type": "string"
              },
              "environment": {
                "type": "string",
                "pattern": "^(development|production)$"
              },
              "wait_seconds": {
                "type": "integer",
                "minimum": 1,
                "maximum": 45,
                "description": "The read's wait: 45, or the preparing call's own `wait_seconds`, 45 where it gave none."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false,
        "description": "The exact `read_status` call that reads the deploy to its end. With the state `awaiting_upload` it is made where the command returned before the outcome, or to read the whole record. It carries the request's `wait_seconds`, which that answer did not wait on; where the command ended 3, nothing started, and its printed refusal is the way on. With `deploying`, it is present at once without `wait_seconds`, and where the wait did not settle."
      },
      "detail": {
        "type": "string",
        "description": "With the state `deploying`, says how the deploy's step and end are read: the `next` call, `read_status` with `wait_seconds` 45, or a read every ten seconds (MAPI-04).\n\nWith `deployed` or `failed`, says how the row ended. For a deployed run that entered `health_gate`, it says the check requested the health path and any smoke paths the manifest lists. It says to request the other routes, read `read_status`'s `server_errors`, and read `read_logs` for errors. It closes that form by saying the health path returned status 200 three times in a row, so that path needs no further request.\n\nWith `deployed` and a run that entered no `health_gate`, it says no health check or smoke check ran and to request its pages or routes and read `read_logs` for errors. A row with no step list uses the health-check form.\n\nWith `awaiting_upload`, identifies the upload's grant, which deploys to the answer's `environment` only the zip whose SHA-256 the call passed, and gives no line to run."
      },
      "manifest_notice": {
        "type": "string",
        "description": "present where the zip's manifest.json, less its application member, differs or does not parse, or a lib/ copy is unread, uncompared, or unpaired (PLD-L0-63)."
      },
      "artifact_notice": {
        "type": "string",
        "description": "present where the build will not run an install script or rebuild a binding.gyp of the root or a workspace member, listing each and each member package.json left unread (PLD-L0-60)."
      },
      "client_notice": {
        "type": "string",
        "description": "present where the zip's client/ folder holds a file beyond the shell or a name the publish skips: counts the files the router serves at their own paths, listing twenty beyond the shell and twenty skipped, then counting the rest (SVC-L0-26)."
      },
      "database_notice": {
        "type": "string",
        "description": "present where the target environment declares or holds a database and the deploy serves APP_DATABASE_URL on the pooler's port (PLD-L0-63; DBS-L0-02). The fixed notice describes transaction pooling's limits and APP_DATABASE_DIRECT_URL for work requiring one held server connection. It rides an at-once answer and a held answer, and deploy_files with check_only, but no preparing answer. It refuses nothing."
      },
      "usage_notice": {
        "type": "string",
        "description": "Present while the application's usage state is over, absent otherwise. For a size, the daily check found stored data at or past its served quantity (ACB-L0-26). It lists the over measures and what each refuses. A size has no backend-actions or data-transfer quantity. It lists file puts on bound storage areas for stored data until the next successful daily pass or a raised quantity. It also says that the deploy proceeded. The deploy itself is never refused for usage."
      }
    },
    "description": "With `artifact` or `upload`, 202 at once with `next`, before the build starts: the environment's version-history row was inserted `deploying`, and the build, the apply, the publish, and the health gate continue after the answer. With `wait_seconds`, the answer is held until the row ends: settled, it is 200 with the state `deployed` or `failed` and the row's `outcome`; unsettled, it is 202 with `next` (MAPI-04; PLD-L0-63). While a deploy of the environment is in flight, a second deploy with `artifact` returns it for the same artifact hash and is refused `deploy_in_flight` for a different one (PLD-L0-63; MAPI-04). A call passing `upload` returns it only where that deploy read the same upload, and any other upload is refused `deploy_in_flight`, identical bytes included (PLD-L0-86). On the HTTP action route alone, the command's preparing call passes `zip_sha256` and returns 200 with the state `awaiting_upload` and `upload`."
  }
}

Shared contracts #