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.