publish_public_files
Generated automatically from the published contract sources.
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.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/publish_public_files, with a bearer credential and the action's payload as the JSON body.
Contract description
Publish one set of public files into its container on the public files origin, in three phases. Platform operator or its publisher (the `publication` grant or `super_admin`) only. The set is the `plugins` release set or the `packages` folder from its committed folder, or the rendered website as a version of the `site` container, which the control plane reads and no browser does.
For a folder container, `begin` with the container and the folder's manifest, `put` for each versioned file with its bytes and SHA-256, then `commit` with the manifest and the one stable file that no versioned file duplicates. The server refuses a publish that would move the served version backward (`publish_not_forward`), a versioned name whose stored bytes differ (`published_bytes_differ`), and a `commit` with a versioned file missing (`publish_incomplete`).
For `site`, every file is written under `v/<source commit>/`, and `begin` with no manifest answers the served version, its sequence, and the pointer's history. The `commit` phase carries the source commit, the sequence the client read plus one, the manifest, and the entry's properties. It is refused `publish_not_forward` where the sequence has moved, `published_bytes_differ` where a path's stored bytes differ from the manifest's digest, and `publish_incomplete` where a file is missing. The publisher scripts that drive it run from the pushed trunk head with the inputs clean. The rest is on the page /cloud/reference/actions/publish-public-files/, which `read_documentation` reads as `page` and the platform's origin serves.
More about this action
The `site` container's published versions are read by the control plane's management and accounts services and by no browser. The two folder containers share one rule set, and `site` has its own, stated per member.
For a folder container, at `begin` the server compares the manifest's rows with the container. For `packages` it judges the served version per package, as `newest` states, under the script's version comparison. It answers the versioned names the container lacks. At `commit` the server verifies every versioned name from its blob metadata. A plain file name is its blob name in the container. The `newest` member is not carried for `plugins` or `site`.
A stable name is one of `blueprint-release.json`, `blueprint.zip`, `blueprint-codex-install.mjs`, and `marketplace.json` in `plugins`, and `packages.json` in `packages`. A versioned name is never rewritten once published. For `plugins` the server writes the `stable` file last, after the stable manifest's conditional write and the copies of `blueprint.zip` and `blueprint-codex-install.mjs`, because `marketplace.json` names the stable archive's digest. For `packages` it is the stable manifest itself, written first by the conditional write.
At `put` a mismatch between the bytes and the `sha256` writes nothing. The write is create-only with the sha256 as blob metadata: an existing blob of the same digest is a no-op.
For `site`, a `begin` with a manifest and `source_commit` also answers the paths the version lacks, and a `commit` verifies every path under the version's prefix. The first segments a site path may not open with are a set that `route_table.ts` derives. A site file's blob name is `v/<source_commit>/<name>`. Every file of the version is that blob, written create-only and never rewritten, so a second publish of the same commit writes nothing per file. No site name is stable, and every file is written under its version.
The `stable` member is not carried for `site`, which has no stable file: `commit` writes the pointer `site.json` first by the conditional write. Where the served sequence has moved, of two overlapping publishers one commits and the other writes nothing. The refused publisher runs `begin` again and commits with the new sequence.
Access and action metadata
{
"name": "publish_public_files",
"resource": "public_files",
"tier": "reversible",
"grant": "publication",
"phases": [
"begin",
"put",
"commit"
],
"summary": "Publish one set of public files into its container on the public files origin, one file per call because the action routes admit 4 MB per call: the plugin release set or the packages folder from its committed folder, or the rendered website as a version of the `site` container, which the control plane reads and no browser does. For the two folder containers, `begin` takes the container's name and the folder's manifest, refuses a publish that would move the served version backward or a versioned name whose stored bytes differ, and answers the served version and the versioned names the container lacks; `put` writes one versioned file create-only, with its sha256 as blob metadata; `commit` verifies that every versioned name is present, writes the stable names with the container's stable manifest first by a conditional write against the version it read, deletes every blob the manifest does not name, and answers the served version, the stable manifest's digest, the deleted names, and the container's listing, which then equals the committed folder. For `site`, every file is written under `v/<source commit>/`, `begin` with no manifest answers the served sequence, the served source commit, and the pointer's history of at most three entries, `commit` takes the source commit, the sequence the client read plus one, the manifest, and the entry's properties, refuses `publish_not_forward` where the sequence has moved, writes the pointer `site.json` first by the conditional write, deletes every version prefix the new history does not name except one any of whose blobs was written within the last fifteen minutes, a publish in flight, and answers the version, the sequence, the pointer's digest, every file's digest as read from blob metadata, the history, the deleted names, and the spared versions; `begin` with a manifest and `commit` refuse `published_bytes_differ` naming a path whose stored bytes differ from the manifest's digest, and a `commit` with a file missing refuses `publish_incomplete`; a rollback is a commit naming a retained entry's source commit with that entry's file list and properties.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false
}
}
MCP catalog entry
{
"name": "publish_public_files",
"tier": "reversible",
"summary": "Publish one set of public files into its container on the public files origin, in three phases. Platform operator or its publisher (the `publication` grant or `super_admin`) only. The set is the `plugins` release set or the `packages` folder from its committed folder, or the rendered website as a version of the `site` container, which the control plane reads and no browser does.\n\nFor a folder container, `begin` with the container and the folder's manifest, `put` for each versioned file with its bytes and SHA-256, then `commit` with the manifest and the one stable file that no versioned file duplicates. The server refuses a publish that would move the served version backward (`publish_not_forward`), a versioned name whose stored bytes differ (`published_bytes_differ`), and a `commit` with a versioned file missing (`publish_incomplete`).\n\nFor `site`, every file is written under `v/<source commit>/`, and `begin` with no manifest answers the served version, its sequence, and the pointer's history. The `commit` phase carries the source commit, the sequence the client read plus one, the manifest, and the entry's properties. It is refused `publish_not_forward` where the sequence has moved, `published_bytes_differ` where a path's stored bytes differ from the manifest's digest, and `publish_incomplete` where a file is missing. The publisher scripts that drive it run from the pushed trunk head with the inputs clean. The rest is on the page /cloud/reference/actions/publish-public-files/, which `read_documentation` reads as `page` and the platform's origin serves.",
"owners": [
"PLD-L0-68",
"PLD-L0-71",
"PLD-L0-75"
],
"scenario": "PLD-L0-68"
}
request
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["phase","container"] Additional properties: false |
| / |
`begin`, `put`, or `commit`. The client drives the three in order and sends one file per call, because the action routes admit 4 MB per call. Allowed values: ["begin","put","commit"] |
| / |
The container the call addresses: `plugins`, the plugin release set served at `/plugins/`; `packages`, the packages folder served at `/packages/`; or `site`, the website's published versions. Allowed values: ["plugins","packages","site"] |
| / |
With `begin` and `commit`: every file of the set, one row per file. For `plugins` and `packages`, the rows are the committed folder's files; for `site`, the rendered site's files, each row's name the path relative to the version. A `begin` refuses `publish_not_forward` where a folder container's served version is newer than the committed one, and `published_bytes_differ` naming a versioned name or a site path that stands with a different sha256. A `commit` refuses `publish_incomplete` naming the missing ones and, for `site`, `published_bytes_differ` naming a differing path; for a folder container it deletes every blob the rows do not name. Type: array |
| / |
Type: object Required fields: ["name","size","sha256"] Additional properties: false |
| / |
The file's name. For `plugins` and `packages`, a plain file name. For `site`, the file's path relative to the version, one to eight plain segments joined by `/`, whose first segment is none of the first segments a control plane service or the edge answers. Type: string |
| / |
The file's size as a byte count. Type: integer |
| / |
The file's SHA-256, hex. Type: string |
| / |
For `plugins` and `packages`, carried on every row, which the server refuses without it: true for a stable name, one that carries no version and is rewritten at every publish, and false for a versioned name. For `site`, absent or false. Type: boolean |
| / |
With `begin` and `commit`, where `container` is `packages`: each package's newest published version as a string, keyed by package name, as the incoming `packages.json` states it. The server refuses `publish_not_forward` where a served package's newest version is greater than the incoming one, or where a served package is absent here. Type: object |
| / |
With `put`: the file's name, as the manifest row spells it. For `plugins` and `packages` a versioned file's name; a stable name is never written at `put`. For `site` the path relative to the version. Type: string |
| / |
With `put`: the file's content, base64. Type: string |
| / |
With `put`: the file's SHA-256, hex. The server hashes the bytes and refuses `invalid_request` on a mismatch. An existing blob of a different digest refuses `published_bytes_differ`. Type: string |
| / |
With `commit`, for `plugins` and `packages`: the one stable file that no versioned file duplicates, `marketplace.json` for `plugins` and `packages.json` for `packages`. Type: object Required fields: ["name","bytes"] Additional properties: false |
| / |
Type: string |
| / |
The file's content, base64. Type: string |
| / |
For `site`, with `begin` where a manifest is carried, with `put`, and with `commit`: the version's source commit, forty lowercase hex digits, the commit of the trunk the site was rendered from. At `commit` a source commit that a retained history entry names, with that entry's file list and `properties`, is a rollback, which needs no `put`. Type: string |
| / |
For `site`, with `commit`: the publish sequence the version takes, the served sequence `begin` answered plus one. The server refuses `publish_not_forward` where the served sequence has moved. Type: integer |
| / |
For `site`, with `commit`: the entry's properties, an object the server stores in the pointer's history entry unread and answers back in `history`, at most 64 KiB serialized; absent, an empty object. A rollback carries the retained entry's `properties` as `begin` answered them. Type: object |
response
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version"] Additional properties: false |
| / |
Required value: 1 |
| / |
With `begin`: the version the container serves, or null where nothing is served yet: for `plugins` and `packages` the version the stable manifest states, for `site` the served version's source commit. With `commit`: the version served after the write. Type: ["string","null"] |
| / |
With `begin`: the names the container lacks, each owed a `put` before `commit`: for `plugins` and `packages` the versioned names, for `site` the paths the version lacks. Not answered by a `site` `begin` that carries no manifest. Type: array |
| / |
Type: string |
| / |
With `put`: the name the call addressed. Type: string |
| / |
With `put`: true where the call wrote the blob, false where a blob of the same name and digest already stood and nothing was written. Type: boolean |
| / |
With `commit`: the SHA-256, hex, of the stable manifest as served after the write; for `site`, of the pointer `site.json` as written. Type: string |
| / |
With `commit`: the names of the blobs deleted. For `plugins` and `packages`, every blob the manifest did not name. For `site`, every blob outside the pointer and the `v/<commit>/` prefixes the new history names; no blob under a retained version is deleted, and none under a version prefix the commit spared (`spared`). Type: array |
| / |
Type: string |
| / |
With `commit`, for `site`: the source commits of the version prefixes the commit spared as a publish in flight, empty where none. A prefix outside the new history is spared whole while any of its blobs was written within the last fifteen minutes, and the next commit past that bound deletes it. Type: array |
| / |
Type: string |
| / |
With `commit`, for `plugins` and `packages`: the container's blob names after the deletions, which then equal the committed folder's file names. Not answered for `site`. Type: array |
| / |
Type: string |
| / |
For `site`: with `begin`, the served publish sequence, 0 where nothing is served yet; with `commit`, the sequence the version took. Type: integer |
| / |
For `site`: with `begin`, the served version's source commit, or null where nothing is served yet; with `commit`, the version's source commit. Type: ["string","null"] |
| / |
For `site`, with `begin` and `commit`: the pointer's history after the read or the write, newest first, at most three entries, the first the served version. A rollback names one of the older entries' source commits and carries that entry's file list and `properties`. Type: array |
| / |
Type: object Required fields: ["sequence","source_commit","published_at","files","properties"] Additional properties: false |
| / |
The entry's publish sequence. Type: integer |
| / |
The entry's source commit. Type: string |
| / |
The instant the entry was committed, ISO 8601 UTC. Type: string |
| / |
The entry's file list: every file of the version, its path relative to the version, its byte count, and its sha256. Type: array |
| / |
Type: object Required fields: ["name","size","sha256"] Additional properties: false |
| / |
The path relative to the version. Type: string |
| / |
The file's size as a byte count. Type: integer |
| / |
The file's SHA-256, hex. Type: string |
| / |
The entry's properties as the publish carried them. Type: object |
| / |
For `site`, with `commit`: every file of the version with the sha256 the server verified from its blob metadata, in the manifest's order, which the client compares with its own manifest. Type: array |
| / |
Type: object Required fields: ["name","sha256"] Additional properties: false |
| / |
The path relative to the version. Type: string |
| / |
The file's SHA-256, hex, as the blob's metadata records it. Type: string |
Complete payload contract
{
"request": {
"type": "object",
"required": [
"phase",
"container"
],
"properties": {
"phase": {
"enum": [
"begin",
"put",
"commit"
],
"description": "`begin`, `put`, or `commit`. The client drives the three in order and sends one file per call, because the action routes admit 4 MB per call."
},
"container": {
"enum": [
"plugins",
"packages",
"site"
],
"description": "The container the call addresses: `plugins`, the plugin release set served at `/plugins/`; `packages`, the packages folder served at `/packages/`; or `site`, the website's published versions."
},
"manifest": {
"type": "array",
"description": "With `begin` and `commit`: every file of the set, one row per file. For `plugins` and `packages`, the rows are the committed folder's files; for `site`, the rendered site's files, each row's name the path relative to the version. A `begin` refuses `publish_not_forward` where a folder container's served version is newer than the committed one, and `published_bytes_differ` naming a versioned name or a site path that stands with a different sha256. A `commit` refuses `publish_incomplete` naming the missing ones and, for `site`, `published_bytes_differ` naming a differing path; for a folder container it deletes every blob the rows do not name.",
"items": {
"type": "object",
"required": [
"name",
"size",
"sha256"
],
"properties": {
"name": {
"type": "string",
"description": "The file's name. For `plugins` and `packages`, a plain file name. For `site`, the file's path relative to the version, one to eight plain segments joined by `/`, whose first segment is none of the first segments a control plane service or the edge answers."
},
"size": {
"type": "integer",
"description": "The file's size as a byte count."
},
"sha256": {
"type": "string",
"description": "The file's SHA-256, hex."
},
"stable": {
"type": "boolean",
"description": "For `plugins` and `packages`, carried on every row, which the server refuses without it: true for a stable name, one that carries no version and is rewritten at every publish, and false for a versioned name. For `site`, absent or false."
}
},
"additionalProperties": false
}
},
"newest": {
"type": "object",
"description": "With `begin` and `commit`, where `container` is `packages`: each package's newest published version as a string, keyed by package name, as the incoming `packages.json` states it. The server refuses `publish_not_forward` where a served package's newest version is greater than the incoming one, or where a served package is absent here."
},
"name": {
"type": "string",
"description": "With `put`: the file's name, as the manifest row spells it. For `plugins` and `packages` a versioned file's name; a stable name is never written at `put`. For `site` the path relative to the version."
},
"bytes": {
"type": "string",
"description": "With `put`: the file's content, base64."
},
"sha256": {
"type": "string",
"description": "With `put`: the file's SHA-256, hex. The server hashes the bytes and refuses `invalid_request` on a mismatch. An existing blob of a different digest refuses `published_bytes_differ`."
},
"stable": {
"type": "object",
"description": "With `commit`, for `plugins` and `packages`: the one stable file that no versioned file duplicates, `marketplace.json` for `plugins` and `packages.json` for `packages`.",
"required": [
"name",
"bytes"
],
"properties": {
"name": {
"type": "string"
},
"bytes": {
"type": "string",
"description": "The file's content, base64."
}
},
"additionalProperties": false
},
"source_commit": {
"type": "string",
"description": "For `site`, with `begin` where a manifest is carried, with `put`, and with `commit`: the version's source commit, forty lowercase hex digits, the commit of the trunk the site was rendered from. At `commit` a source commit that a retained history entry names, with that entry's file list and `properties`, is a rollback, which needs no `put`."
},
"sequence": {
"type": "integer",
"description": "For `site`, with `commit`: the publish sequence the version takes, the served sequence `begin` answered plus one. The server refuses `publish_not_forward` where the served sequence has moved."
},
"properties": {
"type": "object",
"description": "For `site`, with `commit`: the entry's properties, an object the server stores in the pointer's history entry unread and answers back in `history`, at most 64 KiB serialized; absent, an empty object. A rollback carries the retained entry's `properties` as `begin` answered them."
}
},
"additionalProperties": false
},
"response": {
"type": "object",
"required": [
"contract_version"
],
"properties": {
"contract_version": {
"const": 1
},
"version": {
"type": [
"string",
"null"
],
"description": "With `begin`: the version the container serves, or null where nothing is served yet: for `plugins` and `packages` the version the stable manifest states, for `site` the served version's source commit. With `commit`: the version served after the write."
},
"missing": {
"type": "array",
"items": {
"type": "string"
},
"description": "With `begin`: the names the container lacks, each owed a `put` before `commit`: for `plugins` and `packages` the versioned names, for `site` the paths the version lacks. Not answered by a `site` `begin` that carries no manifest."
},
"name": {
"type": "string",
"description": "With `put`: the name the call addressed."
},
"written": {
"type": "boolean",
"description": "With `put`: true where the call wrote the blob, false where a blob of the same name and digest already stood and nothing was written."
},
"manifest_digest": {
"type": "string",
"description": "With `commit`: the SHA-256, hex, of the stable manifest as served after the write; for `site`, of the pointer `site.json` as written."
},
"deleted": {
"type": "array",
"items": {
"type": "string"
},
"description": "With `commit`: the names of the blobs deleted. For `plugins` and `packages`, every blob the manifest did not name. For `site`, every blob outside the pointer and the `v/<commit>/` prefixes the new history names; no blob under a retained version is deleted, and none under a version prefix the commit spared (`spared`)."
},
"spared": {
"type": "array",
"items": {
"type": "string"
},
"description": "With `commit`, for `site`: the source commits of the version prefixes the commit spared as a publish in flight, empty where none. A prefix outside the new history is spared whole while any of its blobs was written within the last fifteen minutes, and the next commit past that bound deletes it."
},
"listing": {
"type": "array",
"items": {
"type": "string"
},
"description": "With `commit`, for `plugins` and `packages`: the container's blob names after the deletions, which then equal the committed folder's file names. Not answered for `site`."
},
"sequence": {
"type": "integer",
"description": "For `site`: with `begin`, the served publish sequence, 0 where nothing is served yet; with `commit`, the sequence the version took."
},
"source_commit": {
"type": [
"string",
"null"
],
"description": "For `site`: with `begin`, the served version's source commit, or null where nothing is served yet; with `commit`, the version's source commit."
},
"history": {
"type": "array",
"description": "For `site`, with `begin` and `commit`: the pointer's history after the read or the write, newest first, at most three entries, the first the served version. A rollback names one of the older entries' source commits and carries that entry's file list and `properties`.",
"items": {
"type": "object",
"required": [
"sequence",
"source_commit",
"published_at",
"files",
"properties"
],
"properties": {
"sequence": {
"type": "integer",
"description": "The entry's publish sequence."
},
"source_commit": {
"type": "string",
"description": "The entry's source commit."
},
"published_at": {
"type": "string",
"description": "The instant the entry was committed, ISO 8601 UTC."
},
"files": {
"type": "array",
"description": "The entry's file list: every file of the version, its path relative to the version, its byte count, and its sha256.",
"items": {
"type": "object",
"required": [
"name",
"size",
"sha256"
],
"properties": {
"name": {
"type": "string",
"description": "The path relative to the version."
},
"size": {
"type": "integer",
"description": "The file's size as a byte count."
},
"sha256": {
"type": "string",
"description": "The file's SHA-256, hex."
}
},
"additionalProperties": false
}
},
"properties": {
"type": "object",
"description": "The entry's properties as the publish carried them."
}
},
"additionalProperties": false
}
},
"files": {
"type": "array",
"description": "For `site`, with `commit`: every file of the version with the sha256 the server verified from its blob metadata, in the manifest's order, which the client compares with its own manifest.",
"items": {
"type": "object",
"required": [
"name",
"sha256"
],
"properties": {
"name": {
"type": "string",
"description": "The path relative to the version."
},
"sha256": {
"type": "string",
"description": "The file's SHA-256, hex, as the blob's metadata records it."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
Shared contracts
- Refusals: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md