Documents and artifacts
The two kinds of thing worth keeping — durable knowledge, and the evidence a particular run produced
Not built yet. There is no Document table and no Artifact table, and no blob storage is wired to
either. The Prisma schema still ships the template's stub model. This page describes the intended
shape, taken from spec/01-domain-model.md.
Both records exist to stop knowledge dying with a session. They divide by lifetime: an Artifact is evidence from one attempt, a Document is knowledge that outlives every attempt.
Artifact
Any output worth keeping: a diff, a screenshot, a log, a file, a URL.
| Field | Notes |
|---|---|
kind | What sort of output it is. |
mime, bytes | How to read it and how big it is. |
sha256 | Content hash. |
storageKey | Where the bytes live in blob storage. |
runId, taskId | The attempt and the intent it belongs to. |
Artifacts are content-addressed, so re-uploading the same bytes deduplicates rather than storing a second copy. An Artifact is immutable once written: a new version is a new row, never an edit.
Why logs are artifacts and not columns
A Run references its log through logArtifactId rather than carrying the log
inline. Context window is the scarcest resource in this system, and a run log is the single largest
thing a run produces. Returning a reference costs an agent a few tokens; returning the log costs it
the rest of its budget.
The same rule governs prose generally: fields have documented length budgets, and a long body is returned as an artifact reference rather than inlined.
What a runner is expected to attach
The write-back contract asks for the diff, the pull request link, and any screenshot proving the work. A claim that something was verified, with no artifact showing the verification, is the shape of a green lie.
Document
The centralizing half of the product: durable knowledge not tied to one task. Decisions, ADRs, runbooks, links, snippets, and credential references.
| Field | Notes |
|---|---|
body | Markdown. |
tags[] | Retrieval by hand. |
embedding | Retrieval by meaning. |
supersededById | Points at the document that replaced this one. |
Superseding rather than overwriting
A decision that changed is two documents, not one edited document. supersededById keeps the old
one readable and marks it as no longer current. An agent reading history needs to know both what is
true now and what was true when a past run made a choice; an overwrite destroys the second.
Credential references, never credentials
A Document may record where a credential lives. It never records the credential. No table in this
model stores a secret value, only secretRef pointers to the real store, and an agent that needs
one resolves it on its own machine.
Choosing between them
| Ask | Answer |
|---|---|
| Would the next agent working a different task need this? | Document |
| Is this evidence of what one run did? | Artifact |
| Is it large, binary, or a log? | Artifact |
| Would rewriting it destroy history someone might need? | Document, superseded rather than edited |
The write-back contract closes with documents_upsert for anything the next agent would otherwise
have to rediscover. Rediscovery is the cost this record exists to remove.