# Artifacts

> Files one attempt wrote and other attempts read: the hand-offs between agents.

An artifact is a file, or another addressable output, that one attempt wrote and other attempts read. Artifacts are the hand-offs between agents. The run records who wrote and who read an artifact, never its content.

- `id` (string, required): Unique within the document. Producers may use the path itself or a hash of it.

  At most 200 characters.

- `path` (string, required): The path the writers and readers used, as the producer knew it (absolute or workspace-relative). A locator, never content.

  At most 1000 characters.

- `kind` (object, required): *properties*

  - `value` (string | null, required): Open set. Recommended vocabulary: plan, review, spec, report, code, test, config, doc, data, log, commit, merge, issue, repo, diff, verdict, test_record, other (commit and merge from v0.3: a late event is matched to its run by its commit; issue, repo, diff, verdict and test_record from v0.3: the artifact kinds of workflow pieces). null when the kind is unknown; the key is always present and the tier stays required beside it.

    At most 100 characters.

  - `tier` ([EvidenceTier](https://orchestrationcontextprotocol.io/specification/0.3/schema#evidencetier), required)

  - `evidence` ([ShortText](https://orchestrationcontextprotocol.io/specification/0.3/schema#shorttext)): What the kind was inferred from, e.g. `path pattern` or `heredoc first line`.

  - `ext` ([Ext](https://orchestrationcontextprotocol.io/specification/0.3/schema#ext))

- `producer` (string, required): Attempt id of the first writer. Must name an existing attempt and must equal writers[0]; anything else is a conformance error.

  At most 200 characters.

- `writers` (string[], required): Attempt ids that wrote the artifact, in first-write order, each listed once. Never empty: an artifact exists because something wrote it, and writers[0] is the producer.

- `consumers` (string[], required): Attempt ids that read the artifact after a write by another attempt, in first-read order, each listed once. May be empty (written, never read by another attempt).

- `first_write_at` ([Timestamp](https://orchestrationcontextprotocol.io/specification/0.3/schema#timestamp) | null, required): Timestamp of the first write event; null when the producer cannot compute it. The key is always present: unknown is an explicit null, never an absent key.

- `n_writes` (integer | null, required): Number of write events across all writers; null when the producer cannot count them. A known count must be at least the number of writers; a smaller count undercounts and is a conformance error. A null count is unknown: it neither satisfies nor fails that check.

- `n_reads` (integer | null, required): Number of read events across all consumers; null when the producer cannot count them. A known count must be at least the number of consumers; a smaller count undercounts and is a conformance error. A null count is unknown: it neither satisfies nor fails that check.

- `labels` ([Labels](https://orchestrationcontextprotocol.io/specification/0.3/schema#labels))

- `ext` ([Ext](https://orchestrationcontextprotocol.io/specification/0.3/schema#ext))

- `vertex` (string): The workflow artifact id this artifact instantiates.

  At most 200 characters.

- `version` (integer): Version of the artifact, from 1.

- `supersedes` (string): The artifact id this version replaces.

  At most 200 characters.

- `transfer_tokens` (map of object): Attempt id to the tokens that attempt spent reading this artifact, when known.

  *properties*

  - `input` (integer)

  - `cache_read` (integer)

## Requirements

- `producer` MUST name an existing attempt ([E118](https://orchestrationcontextprotocol.io/specification/0.3/conformance#e118)) and MUST equal `writers[0]`: the producer is the first writer ([E162](https://orchestrationcontextprotocol.io/specification/0.3/conformance#e162)).
- `writers` and `consumers` MUST be arrays of existing attempt ids ([E167](https://orchestrationcontextprotocol.io/specification/0.3/conformance#e167)), each attempt listed once ([E166](https://orchestrationcontextprotocol.io/specification/0.3/conformance#e166)). `writers` is never empty; `consumers` MAY be.
- A known `n_writes` MUST be at least the number of writers, and a known `n_reads` at least the number of consumers ([E163](https://orchestrationcontextprotocol.io/specification/0.3/conformance#e163)). A `null` count is unknown and is not checked.
- `first_write_at` is always present, and `null` when the producer cannot compute it.
- `path` is a locator (absolute or relative to the workspace), never content.
- An `artifact` edge records one hand-off of an artifact between two attempts; see [Edges](https://orchestrationcontextprotocol.io/specification/0.3/run-graph#edges).

## Versions (0.3)

From 0.3 an artifact can name the workflow artifact it instantiates (`vertex`), its `version` from 1, and the artifact it `supersedes`, so a revised diff after a review is a new version of the same workflow artifact rather than an unrelated file. `transfer_tokens` records, per consuming attempt, the tokens spent reading the artifact, when known.