submit_manifest

{
  "name": "submit_manifest",
  "resource": "application",
  "tier": "reversible",
  "summary": "Declare or change the manifest, a deliberate act, refused with the failing path. It records the upstreams member's declarations as declare_upstream records them. A deploy runs under the recorded manifest alone, so submit again after each edit to the project's manifest.json. A submission naming `local_run` also answers `provisioning.command`, and `provisioning.command_windows` for Windows: one line that writes a local run's settings under a short-lived grant. That answer withholds the two credential values a first submission otherwise answers once, and over the HTTP API its `provisioning.next` says where they are.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}

{
  "name": "submit_manifest",
  "tier": "reversible",
  "scenario": "CHI-L0-07",
  "summary": "Declare or change an application's manifest: the services it uses (database, storage, accounts, and others), its region, and the external hosts it may reach. It also declares the application's audience and the library entries it holds, binds stored secrets to the settings (environment variables) its code reads, and names the upstreams it calls on a stored key.\n\nSubmitting provisions what the manifest declares, the production database excepted. The development database and its owner role, which local runs use, are created on the first submission naming the database. The production database and its owner role are created at production's first deploy, or at its first promote where development is turned on. The first submission naming accounts creates a realm for each environment the application has, production's alone on a new application. The first submission mints the development platform credential, and the first naming the database mints the development database credential; neither is answered here. This surface answers no platform-minted credential value: the answer states `credentials: withheld`. A resubmission mints nothing.\n\nOnly to run the application on the developer's machine, name `local_run: true`: `provisioning` then carries `command`, and `command_windows` for Windows, one line that re-mints both credentials once each and writes the environment file. A hosted deploy needs neither.\n\nA refusal names the failing path. Adding a service or a host happens only here, never as a deploy's side effect. A `realm` member and a push entry's `apns` and `fcm` members configure each environment the application has at each submission, and a field they name is the manifest's. Keep the project's `manifest.json` matching the manifest last submitted, and submit again after each edit. A deploy runs under the recorded manifest alone: the zip's copy is optional, compared with it, and never used. Where the two differ the deploy answers `manifest_notice` and refuses nothing.",
  "owners": [
    "SEC-L0-07",
    "ADM-L0-07",
    "MAN-12",
    "PLD-L0-39",
    "MAN-14",
    "SCH-L0-07",
    "PLD-L0-63"
  ]
}

{
  "request": {
    "type": "object",
    "required": [
      "application",
      "manifest"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "The application id, from `list_applications`."
      },
      "manifest": {
        "type": "object",
        "description": "The whole manifest as a JSON object, never a partial change. Its schema is the `manifest_schema` resource; a refusal names the failing path."
      },
      "local_run": {
        "type": "boolean",
        "const": true,
        "description": "Optional, on any submission, the first included: `provisioning` then carries the local run's line, and the answer withholds `credential` and `platform_credential`. Refused on a browser session's call."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "outcome"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call."
      },
      "application": {
        "type": "string"
      },
      "outcome": {
        "type": "string",
        "pattern": "^recorded$"
      },
      "database": {
        "type": "object",
        "description": "The production database's connection facts — host, database name, role name, and the setting name. They are present whenever the manifest declares the database kind and the production database stands provisioned, which the application's first production deploy or promote does (DBS-L0-01; PLD-L0-44). The production role's password is composed by the promote from custody and never answered (DBS-L0-02).",
        "required": [
          "host",
          "dbName",
          "roleName",
          "connection_setting"
        ],
        "properties": {
          "host": {
            "type": "string"
          },
          "dbName": {
            "type": "string"
          },
          "roleName": {
            "type": "string"
          },
          "connection_setting": {
            "const": "APP_DATABASE_URL"
          }
        }
      },
      "credential": {
        "type": "string",
        "description": "The development database role's password, present exactly when this call minted or ALTER-completed the development database and its owner role, ran on the wire surface, and named no `local_run`. It is never re-answered, and never answered on the MCP surface or beside the local run's line, which state `credentials: withheld` instead; `rotate_secret` on the development scope over the wire is the re-mint, and the production role's password is never answered (DBS-L0-02; SEC-L0-07)."
      },
      "detail": {
        "type": "string"
      },
      "page": {
        "$ref": "#/shapes/page"
      },
      "realm": {
        "type": "object",
        "description": "The end-user realms, present whenever the manifest declares the accounts kind: `realm` is the production realm's identifier, the application's own. The development realm, that identifier followed by `:development`, stands once development is on (the accounts service PRD's realm statement).",
        "required": [
          "realm",
          "outcome"
        ],
        "properties": {
          "realm": {
            "type": "string"
          },
          "outcome": {
            "enum": [
              "created",
              "confirmed"
            ]
          }
        }
      },
      "schedules": {
        "type": "array",
        "description": "Present when the manifest declares the schedule kind: one row per schedule for each environment the application has (PLD-L0-40), or the rows ended by a resubmission without the kind. Each row's `starts_with` says when its environment starts firing it, `next_due` is its next due time once it runs (SCH-L0-07), and `window_seconds` is the schedule kind's window in seconds (SCH-L0-05). The detail names each environment owing a deploy (SCH-L0-01).",
        "items": {
          "type": "object",
          "required": [
            "environment",
            "name",
            "next_due",
            "starts_with"
          ],
          "properties": {
            "environment": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "next_due": {
              "type": [
                "string",
                "null"
              ],
              "description": "The next due time in UTC where `starts_with` reads `already running`; null otherwise, on a row the submission ended too."
            },
            "starts_with": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "already running",
                "the next deploy to development",
                "the next deploy to production",
                "the next promote to production",
                "the environment's resume",
                null
              ],
              "description": "`already running` where the environment holds a deploy or promote made at or after the row's declaration and is not halted, and `the environment's resume` where it holds one and is halted. Otherwise the act that makes the declaration effective: the deploy, or the promote for production on two environments. Null on a row the submission ended (SCH-L0-07)."
            },
            "window_seconds": {
              "type": "integer",
              "description": "The seconds a run has before the platform ends it, the schedule kind's window (SCH-L0-05)."
            }
          }
        }
      },
      "development_database": {
        "type": "object",
        "description": "The development database's connection facts, present whenever the manifest declares the database kind and the development database stands provisioned (DBS-L0-01); its password is `credential`, answered once at the mint (DBS-L0-02). The `host` is the operated server's own name, the one provider value SVC-L0-02 excepts: an implementation detail read from the composed `APP_DATABASE_URL` alone and copied nowhere else.",
        "required": [
          "host",
          "dbName",
          "roleName",
          "connection_setting"
        ],
        "properties": {
          "host": {
            "type": "string"
          },
          "dbName": {
            "type": "string"
          },
          "roleName": {
            "type": "string"
          },
          "connection_setting": {
            "const": "APP_DATABASE_URL"
          }
        }
      },
      "connection_limit": {
        "type": "integer",
        "description": "Present whenever the manifest declares the database kind, on a first submission and a resubmission alike. It is the plan's served `database-connection-limit` quantity: the connections each process of the application holds open at once, the client pool's maximum, which the pool reads from `APP_DATABASE_CONNECTION_LIMIT`. The role's CONNECTION LIMIT admits twice it, the second half a deploy's overlap of the previous and the new container, so a pool of this size is refused nothing (DBS-L0-04). The `read_status` action answers the same number and `read_plan_quotas` every plan's."
      },
      "platform_credential": {
        "type": "string",
        "description": "The development environment's platform credential, present exactly when this call minted it, at the application's first submission, on the wire surface, to a request naming no `local_run`. Every other answer withholds it and states `credentials: withheld`, the local run's line re-minting it through `rotate_secret` on the developer's machine. A resubmission that finds the standing credential answers nothing; `rotate_secret` on the development scope is the re-mint (SEC-L0-07; PLD-L0-39)."
      },
      "credentials": {
        "type": "string",
        "enum": [
          "answered",
          "withheld"
        ],
        "description": "Present exactly when this call minted a development credential: `answered` on the wire surface for a request naming no `local_run`, where `credential` and `platform_credential` carry the values, and `withheld` otherwise. The MCP surface answers no platform-minted credential value, and a request naming `local_run` is answered its line alone (SEC-L0-07). That line then re-mints them through `rotate_secret` on the developer's machine and writes the environment file. Absent on a resubmission, which mints nothing."
      },
      "health": {
        "type": "object",
        "description": "The health gate's terms for this manifest, present on every submission (PLD-L0-63). At each deploy, promote, and restart the gate requests `path`, the manifest's `health` path, with GET, and passes on the first `passes_on` answer, 200 exactly, within `waits_seconds`. That bound in seconds is read from the platform's configuration at each answer and written in no schema. The manifest schema's `health` description states how the route answers while the application starts. Request `path` on a local run before the first deploy. `gated` is false where the audience is `public` or `path` stands under `/__account/`, which the gate never checks. Otherwise it is true, unless the kind is `invited` or `workforce` and a prefix in its `session_free_paths` covers `path`, its query cut away as a request's path is. Where it is true, a request to `path` from outside without a session is refused 401 `authentication_required`, or sent to sign-in in a browser. The deploy's check reaches the compute directly, so it still passes.",
        "required": [
          "path",
          "passes_on",
          "waits_seconds",
          "gated"
        ],
        "properties": {
          "path": {
            "type": "string",
            "pattern": "^/[^\\s]*$"
          },
          "passes_on": {
            "const": 200
          },
          "waits_seconds": {
            "type": "integer",
            "minimum": 1
          },
          "gated": {
            "type": "boolean"
          }
        }
      },
      "provisioning": {
        "type": "object",
        "description": "The local run's setup (SEC-L0-07; DBS-L0-02), its `for` always `local_run`. Where the request named `local_run`: `command`, the line `echo <grant> | npx -y <address> provision --application <id>`; `command_windows`, the same line for Windows; and `expires_at`, its grant's expiry. Run one once, as given, in the application's folder: it re-mints the development credentials and writes the environment file. Over the wire `next` stands beside the line and says where the withheld values are. Otherwise `next` alone, one sentence naming `local_run`, and no grant is minted. Absent over the wire without `local_run`, and where the line could not be prepared, which `detail` then says.",
        "required": [
          "for"
        ],
        "properties": {
          "for": {
            "const": "local_run"
          },
          "next": {
            "type": "string"
          },
          "command": {
            "type": "string"
          },
          "command_windows": {
            "type": "string"
          },
          "expires_at": {
            "type": "string"
          }
        }
      },
      "issue_tracking": {
        "type": "array",
        "description": "The issue-tracking spaces the application's calls reach, one entry per space, present whenever the manifest declares the issue_tracking kind (ITS-L0-01).",
        "items": {
          "type": "object",
          "required": [
            "space",
            "scope",
            "environments",
            "outcome",
            "level"
          ],
          "properties": {
            "space": {
              "type": "string",
              "description": "The space's identifier, a lower-case UUID the platform derives."
            },
            "scope": {
              "enum": [
                "application",
                "account",
                "development",
                "production"
              ],
              "description": "`application` for its own space, `account` for a bound space of the account, or the environment's name for a space per environment."
            },
            "environments": {
              "type": "array",
              "items": {
                "enum": [
                  "development",
                  "production"
                ]
              },
              "description": "The environments whose calls reach the space."
            },
            "outcome": {
              "enum": [
                "created",
                "confirmed",
                "bound"
              ],
              "description": "`created` where this submission created the space, `confirmed` where it stood, and `bound` for a space of the account."
            },
            "level": {
              "enum": [
                "report",
                "contribute",
                "owner"
              ],
              "description": "The calls the gateway admits: `report` files and reads, `contribute` adds the working calls, and `owner`, a space per environment's, every call."
            },
            "note": {
              "type": "string",
              "description": "Why no release line was declared: present only where a space of the account's own already held its 50 release lines."
            }
          }
        }
      },
      "settings": {
        "type": "array",
        "description": "Present when the manifest's `settings` member binds a setting: one row per setting and environment the application has, naming the stored secret and whether it is `stored` at that environment's scope of the application (MAN-14). A deploy or promote of an environment whose row reads `stored: false` is refused `setting_secret_missing` until `store_secret` stores the name there.",
        "items": {
          "type": "object",
          "required": [
            "setting",
            "secret",
            "environment",
            "stored"
          ],
          "properties": {
            "setting": {
              "type": "string",
              "description": "The setting name the process reads."
            },
            "secret": {
              "type": "string",
              "description": "The stored name whose value the setting holds."
            },
            "environment": {
              "type": "string",
              "description": "The environment, `development` or `production`."
            },
            "stored": {
              "type": "boolean",
              "description": "True where the name stands at that environment's scope of the application."
            }
          }
        }
      },
      "upstreams": {
        "type": "array",
        "description": "Present when the manifest's `upstreams` member names an upstream: one row per upstream and environment, naming the upstream's stored key and whether that environment reads a value under it, at its own scope of the application or at the account scope (EGW-L0-02). The gateway refuses the upstream's calls in an environment whose row reads `stored: false`, `credential_not_in_custody`, until `store_secret` stores the key.",
        "items": {
          "type": "object",
          "required": [
            "upstream",
            "credential_name",
            "environment",
            "stored"
          ],
          "properties": {
            "upstream": {
              "type": "string",
              "description": "The upstream's name."
            },
            "credential_name": {
              "type": "string",
              "description": "The stored name of the upstream's key."
            },
            "environment": {
              "type": "string",
              "description": "The environment, `development` or `production`."
            },
            "stored": {
              "type": "boolean",
              "description": "True where the environment reads a stored value under the name."
            }
          }
        }
      },
      "egress_keys_ended": {
        "type": "integer",
        "minimum": 0,
        "description": "Present where an `upstreams` entry left a standing upstream with no key setting: the count of the upstream egress keys the submission ended, in both environments, zero where no deployed copy held one. A copy that held one has no working key until the entry's `settings.key` is restored, the manifest submitted again, and its environment's next deploy, promote, or `restart_application`. Where the count is above zero, the detail names those environments and the route back: restore `settings.key`, submit again, then `restart_application` each."
      }
    }
  }
}