# 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.