Cloud Artifacts

A Cloud Artifact is a durable product output stored in a Chainabit workspace. An artifact has a stable identity and one or more immutable versions. A conversation card refers to an artifact ID and version ID, not to a temporary workspace location or a storage URL.

An artifact is created when a result needs to outlive the turn that produced it — to be downloaded, versioned, attributed, shared, or consumed by another tool. It is not how a result is displayed: a conversation renders prose, tables, code and other supported formats directly, and asking to see something does not create a file. See Cloud Artifact Runtime for the boundary between the two.

Artifact availability is capability-gated. A client should treat an unavailable operation or preview kind as an explicit fallback condition and continue to offer any authorised download that is available.

Terms

Term	Meaning
Artifact	Stable, workspace-scoped identity for a product output.
Version	Immutable set of promoted source bytes and file metadata.
File	One normalized relative path within an artifact version.
Source	The exact promoted bytes. Source bytes are never changed by preview or attribution.
Derivative	A bounded preview, thumbnail, export, or other generated representation linked to one source version.
Preview descriptor	Authorised typed instructions for rendering a preview. It is not an arbitrary file URL.
Attestation	Detached provenance data that identifies the bytes and the recorded origin of a version.

Artifact identity and provenance

Every version records its source surface and execution plane. These fields make the origin clear without claiming that an imported file was authored by Chainabit.

Field	Values	Meaning
`surface`	`web`, `cli`, `nexus_desktop`, `api`, `automation`	The product surface that requested promotion.
`executionPlane`	`cloud_sandbox`, `local_machine`, `nexus_local`, `remote_api`	Where the source was produced or selected.
`provenanceState`	`imported_unverified`, `promoted_by_chainabit`, `derived_by_chainabit`	The level and kind of recorded provenance.

These are recorded claims made by the service, not labels chosen by the caller. A direct publication states its surface; the service derives the execution plane and provenance state from it and rejects a request that states a value disagreeing with the derived one, rather than correcting the request silently.

Because of that, a direct publication can never record `cloud_sandbox`. Only a promotion of an authorised Cloud Sandbox run's output records that plane, so the field remains a meaningful statement about where the bytes were produced.

The source hash identifies exact bytes. A detached attestation associates that hash with the recorded artifact version and provenance claim. A hash by itself does not establish authorship.

Version lifecycle

An output moves through the following user-visible states:

`discovered` → `promoting` → `ready` → `preview_pending` → `preview_ready` or `preview_limited`

Policy or safety failures can place a version in `quarantined`. A later promotion creates a new version rather than modifying a ready source version. When a linked conversation is deleted, a recoverable deletion state starts the documented recovery period before final purge.

API operations

The artifact API uses the workspace selected by the authenticated request. Responses use normal Chainabit response envelopes. Mutation requests should include an idempotency key so a retry cannot create a second version.

Operation	Purpose
`GET /artifacts`	List artefacts the caller can access in the active workspace.
`GET /artifacts/:artifactId`	Read the stable identity, current version, lifecycle state, and safe metadata.
`GET /artifacts/:artifactId/versions/:versionId`	Read a specific immutable version and its file manifest.
`GET /artifacts/:artifactId/versions/:versionId/preview`	Obtain the current typed preview descriptor or an explicit limited state.
`GET /artifacts/:artifactId/versions/:versionId/download`	Obtain an authorised, short-lived download grant.
`POST /artifacts/publish`	Explicitly promote a selected cloud or local output into a workspace artifact.
`GET /artifacts/:artifactId/versions/:versionId/verify`	Read the detached attestation and verification result for an authorised version.

A successful promotion returns the artifact and immutable version IDs. It never returns a durable storage URL. Downloads and preview resources are authorised per request and expire.

Promotion request shape

The public request describes the selected output and its provenance. It does not imply background synchronisation of a local directory.

```json { "kind": "document", "surface": "cli", "executionPlane": "local_machine", "provenanceState": "promoted_by_chainabit", "idempotencyKey": "YOUR_IDEMPOTENCY_KEY", "publicationConsent": true, "files": [ { "path": "report.md", "contentBase64": "IyByZXBvcnQ=", "declaredMime": "text/markdown" } ] } ```

`surface` and `idempotencyKey` are required. `executionPlane` and `provenanceState` may be omitted; when sent they must match what the service derives. `publicationConsent` must be `true` when the surface selects bytes from a machine the person controls.

A publication may name the `runId` it belongs to, and may add `messageId` and `toolCallId` alongside it. The run must be one the active workspace owns; an unknown run is refused, and a message or tool reference without a run is refused. This keeps a publication from attaching itself to another person's conversation or live run.

The service validates normalized relative paths, file counts, byte limits, and detected content before a version becomes visible. Size limits are checked before the request body is decoded, so an oversized publication is refused with a payload-too-large result rather than being partially processed. A rejected promotion does not create a cloud artifact.

Streaming updates

Artifact progress is delivered over the existing authenticated SSE stream. The artifact family is separate from both `activity.` and eligible-session `cot.` visible reasoning events.

Event	Meaning
`artifact.created`	An artifact identity has been allocated.
`artifact.updated`	Safe lifecycle or metadata state changed.
`artifact.ready`	An immutable source version is ready.
`artifact.failed`	Promotion could not complete.
`preview.ready`	A preview descriptor is available.
`preview.limited`	The source remains downloadable but has no supported bounded preview.
`preview.failed`	Preview preparation failed without changing source bytes.

Each replayable event carries a stable event ID, an ordered sequence, timestamp, correlation IDs, and an idempotency key. On reconnect, use `Last-Event-ID` or the supported resume cursor, deduplicate by event ID, and retain the original message/run placement of an artifact card.

Preview descriptors

The API chooses a renderer after inspecting the source. The browser must render only the provided descriptor and allowed capabilities; it must not choose a renderer from a filename, MIME label, or arbitrary URL.

Initial kinds include PDF, sanitized text or Markdown, escaped code, Mermaid, read-only tabular data, and native structured artifacts. Unsupported or resource-limited content reports `preview_limited` and remains downloadable. Interactive site previews use an isolated preview context and never receive ambient account credentials from the Chainabit application.

Local-first publishing

The CLI and NEXUS keep local work local unless a person explicitly publishes selected output to a named Cloud Workspace. The publish flow displays the target, selected files, size, source surface, and execution plane before the operation. A reference to a cloud artifact does not make it a local file, and a local file is not described as cloud-promoted until promotion succeeds.

Deletion and recovery

Deleting a linked conversation starts a recoverable deletion lifecycle for its artifact references. A restore before the applicable recovery deadline restores the references and access permitted by policy. After the deadline, the final purge removes retained source and derivative content and leaves only the non-content evidence needed to record that the purge completed.