# Fossil RFC Suite Brief

## Objective

Produce a four-document RFC suite that specifies the Fossil distributed version control system as implemented in the current Fossil source tree:

1. **The Fossil Distributed Version Control System: Artifact Format**
2. **The Fossil Delta Format**
3. **The Fossil Distributed Version Control System: Repository State and Check-in Resolution**
4. **The Fossil Distributed Version Control System: Sync Protocol**

The later drafting work added Repository State and Check-in Resolution as a fourth companion RFC when it became clear that derived repository-state behavior needed its own specification rather than remaining implicit inside Artifact and Sync.

The governing standard is implementability: a competent programmer who has never seen the Fossil source must be able to build a conformant, interoperable implementation from the suite alone.

## Required clean-room capabilities

Each document must let a reader carry out every operation it governs.

### Artifact Format
A clean-room implementer must be able to:

- parse every structural artifact type the document covers,
- verify artifact naming and checksum rules,
- apply card ordering and multiplicity rules correctly,
- distinguish content artifacts from structural artifacts,
- rebuild the full file set of a delta manifest.

### Delta Format
A clean-room implementer must be able to:

- parse the delta byte format,
- apply a delta to a source artifact,
- produce a valid delta from source and target content,
- validate trailer and bounds behavior.

### Repository State and Check-in Resolution
A clean-room implementer must be able to:

- build the check-in DAG from stored manifest parent references,
- crosslink structural artifacts into repository tag state,
- compute branch membership and tag propagation correctly,
- enumerate leaves and open leaves with closed-marker handling,
- resolve a symbolic branch or tag name to a single check-in,
- resolve `current-trunk` from the derived repository state and the repository-local default branch name.

### Sync Protocol
A clean-room implementer must be able to:

- open a sync session,
- authenticate,
- exchange content,
- resolve phantoms,
- complete a clone,
- converge on a common artifact set,
- terminate the session correctly.

## Cross-document structure

- **Artifact** is foundational and owns the core artifact vocabulary.
- **Delta** defines the delta encoding referenced by Artifact and Sync.
- **RepoState** defines the derived repository views computed over stored artifacts: check-in DAG construction, crosslink/tag propagation, leaves, symbolic-name resolution, and `current-trunk`.
- **Sync** depends on Artifact and Delta for transferred content and on RepoState for repository-derived state rather than redefining those rules inline.
- Cross-references should be narrow and explicit; do not duplicate foundational rules just to avoid a citation.

## Suite-wide Fossil constraints

- Preserve every construct needed to read existing repositories, including old SHA-1 artifacts.
- Preserve documented historical relaxations that a reader must tolerate, such as the technote card-order exception when confirmed by source.
- Treat the Sync document as the **current** wire protocol specification.
- Keep the current clone path (`cfile` plus `clone_seqno`); omit the older version-2 uncompressed `send_file` clone path.
- Omit login handling older than Fossil 2.27, but record the version/date boundary in the sync text after checking the implementation path.
- The version pragmas (`client-version`, `server-version`) matter because they expose the protocol generation a peer is speaking.

## Deliverable boundaries

- Public suite outputs are the Kramdown source draft and the rendered IETF text draft.
- XML is a build intermediate, not part of the public suite output.
- The suite should read as enduring protocol and format documentation, not as a process diary.
- The only permitted transformation/ratification provenance sentence is the mandated opening sentence in the Artifact abstract.

## Editorial bias

- Self-contained beats terse if the tradeoff affects interoperability.
- Artifact and Delta must stay readable for long-term repository access.
- Sync must specify the exchange algorithmically, not merely narrate what pull/push usually do.
- After drafting the suite, perform a cross-document pass for repetition, mismatched terminology, and missing capability coverage.