RepoState RFC Brief

Document identity

• Title: The Fossil Distributed Version Control System: Repository State and Check-in Resolution
• Working docname: draft-fossil-repo-state-00
• Role in the suite: later-added companion RFC that specifies the derived repository-state semantics that could not remain implicit inside Artifact and Sync.

Objective

Specify how a Fossil repository derives repository views from the crosslinked set of stored structural artifacts.

The document owns the computation of:

• the check-in DAG built from manifest parent cards,
• crosslink processing from stored structural artifacts into repository tag state,
• tag propagation and blocking,
• branch membership,
• leaves and open leaves,
• symbolic-name resolution,
• and the current-trunk check-in derived from the artifact set plus the repository-local main-branch setting.

The document is a companion to Artifact, which defines the card and hash syntax whose downstream effect is computed here, and to Sync, which moves the artifacts between peers.

Clean-room capability target

A clean-room implementer must be able to:

• build the check-in DAG from stored manifests and their parent references,
• crosslink structural artifacts into repository tag state,
• compute branch membership from propagated branch tags,
• enumerate leaves and open leaves with closed-marker handling,
• resolve a symbolic branch or tag name to a single check-in,
• and resolve current-trunk from the repository default branch configuration plus the derived repository state.

Required section inventory

The document should keep this section shape:

1. Introduction
   1. Scope
2. Terminology
3. Check-in DAG Construction
   1. Linkage record shape
   2. Primary parent vs. merge parents
   3. Ancestry direction and traversal
4. Crosslink Processing
   1. T-card syntax validation
   2. Crosslink procedure
   3. Rejection conditions
   4. Comment rendering of crosslink effects
   5. Serialization of tag artifacts
5. Tag Types and Propagation
   1. Tag Type Values
   2. Storage Model
   3. Direct Application Procedure
   4. Propagation Algorithm
   5. Blocking Conditions
6. Branch Membership and Naming
   1. Branch of a check-in
   2. Branch creation
   3. Enumerating branches
   4. A note on branch current
7. Leaves
   1. Definition
   2. Normative leaf test
   3. Maintenance algorithm
   4. Open leaves and closed-marker semantics
   5. Leaf-set enumeration and ambiguity
   6. Triggers for re-evaluation
   7. Relationship to name resolution
8. Symbolic Name Resolution
   1. Scope
   2. Rule
   3. Procedure
   4. Branch-walk rule
   5. Distinguishing name resolution from open-leaf enumeration
9. Current Trunk and Forks
10. Worked Example: Fork with a Closed Leaf
11. IANA Considerations
12. Security Considerations
13. Normative References

Boundaries and dependencies

• Artifact dependency: Artifact owns the byte-level grammar of the P and T cards, artifact-hash syntax, content-type determination, and delta-manifest reconstruction. RepoState consumes that syntax and specifies the downstream repository-state effect.
• Delta dependency: Delta remains the byte-level content-delta format beneath delta-manifest/file reconstruction; RepoState does not redefine delta encoding.
• Sync dependency: Sync owns transport, admission, and artifact exchange between peers. RepoState assumes the repository already has the relevant artifacts and defines the derived views over the resulting stored set.
• File-tree boundary: RepoState determines which check-in constitutes a given repository state; materializing that check-in's file tree stays in Artifact's delta-manifest/file reconstruction procedures.

Required emphasis points

• Name resolution and open-leaf enumeration are distinct and must not be collapsed.
• Closed-ness and leaf-ness do not filter symbolic-name resolution unless the rule explicitly says so.
• current-trunk is derived from the repository-local default branch name together with the artifact set; it is not a synchronized wire value.
• Branch and tag propagation follow the primary-parent/primary-child chain and do not cross merge edges.

Known reviewer watch points

Keep these explicit so the document does not drift back into source-familiarity assumptions:

• exact-equal-mtime ties between candidate check-ins need either a deterministic stated rule or an explicit implementation-defined note; do not invent an unstated tie-breaker,
• representative branch-entry and merge-target child choice need deterministic wording if they remain part of the public behavior,
• the worked example should show the divergence between symbolic-name resolution and open-leaf enumeration when a newer closed leaf exists.