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.