# Artifact RFC Brief
## Mission
Draft the foundational Fossil artifact document:
**The Fossil Distributed Version Control System: Artifact Format**
This document owns the artifact model and the core terminology the other suite documents depend on.
## Front matter
- Use the title above.
- Intended status is Proposed Standard.
- The abstract must begin with the mandated transformation/ratification sentence captured in `../draft-metadata.md`.
- After that sentence, the abstract should state that Fossil stores global state as a content-addressed set of artifacts and that this document specifies artifact naming, card syntax, structural artifact types, and checksum computations.
## Required sections
### 1. Introduction
Cover:
- global state as an unordered set of artifacts,
- local repository state as outside the artifact model,
- content addressing by SHA-1 or SHA3-256,
- grow-only-set / convergence framing.
### 2. Terminology
Own these terms for the suite:
- artifact
- content artifact
- structural artifact
- card
- manifest
- baseline manifest
- delta manifest
- cluster
- control artifact
- phantom
- projectcode
### 3. Naming
Specify:
- hash of raw artifact content with no prefix or suffix,
- SHA-1 as 40 lowercase hexadecimal characters,
- SHA3-256 as 64 lowercase hexadecimal characters,
- the hashed byte sequence as the artifact exactly as stored, including any PGP or SSH clearsign wrapper.
### 4. Card syntax
Specify:
- UTF-8 line-oriented text,
- one `0x0a` newline between cards,
- card structure as a type character plus space-separated arguments,
- no surplus whitespace,
- lexicographic card ordering, including the documented technote relaxation when confirmed by source,
- no duplicate cards,
- argument escaping for space, tab, newline, carriage return, formfeed, vertical tab, NUL, and backslash,
- W-card body framing by decimal byte count, with the body following the card newline and a further newline preceding the next card.
### 5. Structural artifact types
Provide one subsection per type, with ABNF, card multiplicities, and constraints for:
- manifest
- cluster
- control
- wiki
- ticket
- attachment
- technote
- forum
Include the card summary table and its footnotes.
### 6. Checksums
Specify both checksum surfaces:
- **Z card:** MD5 over all prior bytes up to and including the newline before `Z`, excluding any clearsign prefix.
- **R card:** MD5 over each file as sorted path, space, decimal size, newline, and content.
Include examples for both.
### 7. Hash policy
Specify:
- SHA-1 and SHA3-256 selection,
- hash-policy configuration,
- exact hashed byte sequence,
- the continued readability of existing SHA-1 artifacts.
### 8. Delta manifest reconstruction
This section is mandatory and must be procedural. It must tell a reader how to rebuild the full file set of a delta manifest from a baseline manifest and a set of sorted `F` cards.
State each merge case explicitly:
- baseline file sorts before next delta file → keep baseline file,
- delta file sorts before next baseline file → add delta file,
- same name and delta `F` card has a hash → replace baseline file,
- same name and delta `F` card has no hash → delete the file; output nothing for that name.
Also state:
- an `F` card with no hash means delete, not empty content,
- the rebuilt file set is the merge output in filename order,
- the `B` card must name a baseline manifest, not another delta manifest.
Include one worked example captured from the implementation.
## Required appendices
- **A. Examples** — artifact-name computation, Z card, and R card examples.
- **B. ABNF** — collected artifact-format grammar.
- **C. Anomalous artifacts and behaviours** — only for cases that remain true after re-checking source and observed bytes.
## Artifact-specific boundaries
- Keep local repository configuration out of scope except where the artifact model must state that it is outside the model.
- Do not re-specify delta byte encoding; cite Delta as needed.
- Do not pull sync wire behavior into this document except for narrow terminology or dependency statements.
## High-risk Fossil specifics to preserve
- old SHA-1 artifacts remain valid and readable,
- the card-order relaxation is historical reader behavior, not a license to reorder arbitrarily,
- W-card bodies are byte-counted opaque content and may contain newlines,
- delta-manifest deletes are represented by `F` cards with no hash,
- anomaly handling must prefer the reader rule over accidental writer quirks.