Revisions & versioning

An artifact isn't overwritten when it changes — it gains a revision. The artifact itself is a stable handle with a version history; each revision is immutable. That split is what lets "the report" be one durable thing whose contents can still evolve.

Immutable revisions, a mutable head

There are two halves. A revision is written once and never changes after creation — it records its sequence number, a change description, and the durable reference to its rendered bytes. The artifact head is the stable identity: it tracks how many revisions exist and which one is current. Revise an artifact and you add a new immutable revision and advance the head — you never mutate the bytes anyone already saw.

Revising in place

Because the head is stable, a link to an artifact keeps working as it's revised: it resolves to the newest revision. So an agent can publish a report, then improve it, and everyone following it sees the update in place — while an exact earlier revision remains addressable if you need the version someone actually approved.

The durable handle

Each revision carries the reference to its bytes in the artifact store. That reference is the one durable handle to the output once the transient render is cleaned up — it's what makes an artifact outlive the session that made it.

oap artifact versions            # list an artifact's revision history
oap artifact revisions <id>      # the revisions of one artifact
oap artifact get <id>            # fetch a specific version