Network Working Group D. R. Hipp, Ed. Internet-Draft Fossil Intended status: Standards Track S. Beal Expires: 7 January 2027 libfossil D. Shearer 6 July 2026 The Fossil Distributed Version Control System: Sync Protocol draft-fossil-sync-protocol-00 Abstract Fossil is a distributed version-control system in which each repository holds a full copy of a project's history as a set of content-addressed artifacts. Its sync protocol replicates that artifact set between two repositories over HTTP. This document specifies the wire transport, message format, authentication, the card vocabulary, and the multi-round synchronisation algorithm: the round structure, version negotiation, phantom discovery and resolution, the clone procedure, and the termination condition. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 7 January 2027. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights Hipp, et al. Expires 7 January 2027 [Page 1] Internet-Draft Fossil Sync Protocol July 2026 and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5 3. Protocol Operation . . . . . . . . . . . . . . . . . . . . . 7 3.1. Endpoint State . . . . . . . . . . . . . . . . . . . . . 7 3.2. Round Structure . . . . . . . . . . . . . . . . . . . . . 9 3.3. Phantom Record Lifecycle . . . . . . . . . . . . . . . . 11 3.4. The Clone Loop . . . . . . . . . . . . . . . . . . . . . 13 3.5. Request and Response Pragmas . . . . . . . . . . . . . . 13 3.6. Cookie Card . . . . . . . . . . . . . . . . . . . . . . . 13 3.7. Termination . . . . . . . . . . . . . . . . . . . . . . . 13 3.8. Client Protocol State Machine . . . . . . . . . . . . . . 15 3.9. Robustness Posture . . . . . . . . . . . . . . . . . . . 18 3.10. Round Message Layout . . . . . . . . . . . . . . . . . . 19 4. Transport . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.1. Message Compression and Media Types . . . . . . . . . . . 21 4.2. Round Structure . . . . . . . . . . . . . . . . . . . . . 23 4.3. Cookie Card . . . . . . . . . . . . . . . . . . . . . . . 23 5. Card Format . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.1. Message Structure . . . . . . . . . . . . . . . . . . . . 23 5.2. Card Syntax . . . . . . . . . . . . . . . . . . . . . . . 23 5.2.1. Defined Operators . . . . . . . . . . . . . . . . . . 25 5.3. Comment Lines . . . . . . . . . . . . . . . . . . . . . . 25 6. Authentication . . . . . . . . . . . . . . . . . . . . . . . 26 6.1. Login Card . . . . . . . . . . . . . . . . . . . . . . . 26 6.2. Nonce Derivation . . . . . . . . . . . . . . . . . . . . 27 6.3. Shared Secret . . . . . . . . . . . . . . . . . . . . . . 27 6.4. Signature Computation . . . . . . . . . . . . . . . . . . 27 6.5. Cookie-Login Mode . . . . . . . . . . . . . . . . . . . . 29 6.6. Capability Model . . . . . . . . . . . . . . . . . . . . 30 7. Content Transfer . . . . . . . . . . . . . . . . . . . . . . 30 7.1. file Card . . . . . . . . . . . . . . . . . . . . . . . . 30 7.2. cfile Card . . . . . . . . . . . . . . . . . . . . . . . 31 7.3. uvfile Card . . . . . . . . . . . . . . . . . . . . . . . 31 7.4. Delta Sources and Phantom Creation . . . . . . . . . . . 33 7.5. Private Content . . . . . . . . . . . . . . . . . . . . . 33 7.6. SHA3-256 Peer-Version Gate . . . . . . . . . . . . . . . 34 7.7. Hash-Policy Admission . . . . . . . . . . . . . . . . . . 34 8. Clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 8.1. Clone Protocol Version . . . . . . . . . . . . . . . . . 35 8.2. Sequence Numbers . . . . . . . . . . . . . . . . . . . . 36 8.3. First Clone Round . . . . . . . . . . . . . . . . . . . . 37 Hipp, et al. Expires 7 January 2027 [Page 2] Internet-Draft Fossil Sync Protocol July 2026 8.4. Configuration During Clone . . . . . . . . . . . . . . . 38 9. Synchronisation Strategies . . . . . . . . . . . . . . . . . 38 9.1. Push, Pull, and Sync . . . . . . . . . . . . . . . . . . 38 9.1.1. Unversioned-File Synchronisation . . . . . . . . . . 38 9.2. Announcement and Request Cards . . . . . . . . . . . . . 41 9.2.1. Derived Branch, Tag, Leaf, Closed, and Current-Trunk Views . . . . . . . . . . . . . . . . . . . . . . . . 41 9.3. Phantom Records . . . . . . . . . . . . . . . . . . . . . 42 9.4. Gimme Eligibility Filters . . . . . . . . . . . . . . . . 42 9.5. Loop Termination . . . . . . . . . . . . . . . . . . . . 42 10. Pragmas . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 10.1. Version Negotiation . . . . . . . . . . . . . . . . . . 43 10.2. Unversioned-File Pragmas . . . . . . . . . . . . . . . . 44 10.3. Configuration Exchange . . . . . . . . . . . . . . . . . 44 10.4. Commit-Lock Pragmas . . . . . . . . . . . . . . . . . . 46 10.5. Private-Content and Discovery Pragmas . . . . . . . . . 46 11. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 47 11.1. Error Card . . . . . . . . . . . . . . . . . . . . . . . 47 11.2. Message Card . . . . . . . . . . . . . . . . . . . . . . 48 12. Security Considerations . . . . . . . . . . . . . . . . . . . 48 12.1. Credential Replay . . . . . . . . . . . . . . . . . . . 49 12.2. Private-Content Exposure and Protected Transport . . . . 49 12.3. Line-Length Bounds and Resource Exhaustion . . . . . . . 50 12.4. SHA3-256 Downgrade Prevention . . . . . . . . . . . . . 50 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 14.1. Normative References . . . . . . . . . . . . . . . . . . 53 14.2. Informative References . . . . . . . . . . . . . . . . . 54 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 55 A.1. Basic Push/Pull Convergence (Two Rounds) . . . . . . . . 55 A.2. SHA3 Version Gate (Error Card) . . . . . . . . . . . . . 57 A.3. Private Content Suppression . . . . . . . . . . . . . . . 58 A.4. Comment Lines and Clock-Skew Timestamp . . . . . . . . . 61 A.5. Authentication Example . . . . . . . . . . . . . . . . . 62 Appendix B. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 63 Appendix C. Anomalies . . . . . . . . . . . . . . . . . . . . . 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 67 1. Introduction Fossil is a distributed version-control system: each participant keeps a full copy of a project's history, so those copies must be brought back into agreement as people work in parallel. This document specifies how two Fossil repositories synchronise over HTTP — how each obtains the history the other holds, including the initial clone of a repository that starts from nothing. Hipp, et al. Expires 7 January 2027 [Page 3] Internet-Draft Fossil Sync Protocol July 2026 Two repositories of the same Fossil project hold sets of artifacts. Each artifact is named by the hash of its content [FossilArtifact], so an artifact is identical wherever it is held and the union of two repositories' artifact sets is well-defined. Synchronisation brings the two sets into agreement: each side sends to the other the artifacts the other lacks. Because the set is grow-only and order- independent, the result does not depend on direction or timing; the sets converge [GSET]. A repository names an artifact it lacks but knows to exist as a phantom: a record carrying a hash but no content. Synchronisation discovers phantoms when the remote side announces artifact hashes the local side does not hold, and resolves them by requesting the missing content, repeating until no new phantom arises and no outbound work remains. One repository acts as client and the other as server. The client drives the exchange: it builds a request, the server replies, and the client decides from that reply what to send next. The exchange is a sequence of such HTTP round trips. This document specifies what each side sends, how the client updates its state from each reply, and when the client determines the sync is complete. This document fully specifies the current wire surface for artifact transfer and unversioned-file synchronisation: connection and framing, authentication, content transfer, phantom resolution, the unversioned-file catalog and request/response loop, clone, and termination. One area is intentionally not fully specified here: the row-level byte serialization of the table-type configuration groups (/user, /reportfmt, /shun, /concealed, /subscriber) is out of scope; the config /GROUPNAME SIZE framing is defined but the payload layout is not. An implementation conforming only to this document MAY omit table-type configuration exchange; interoperating on those groups requires a companion specification. Where examples or capability descriptions touch that area, they illustrate the framing only and do not imply that the omitted serialization can be derived from this document alone. Section 1 is informative; normative wire-protocol requirements appear in Sections 3–11; Section 12 contains additional normative security and deployment requirements using BCP 14 keywords per Section 2. Hipp, et al. Expires 7 January 2027 [Page 4] Internet-Draft Fossil Sync Protocol July 2026 2. Conventions and Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. The following terms are used throughout this document. Artifact, hash, manifest, cluster: :: As defined in [FossilArtifact]. Phantom: :: A repository record for an artifact whose hash is referenced but whose content is not yet present. Phantom records and their lifecycle are specified in Section 3.3. Branch, tag, closed marker, leaf, current-trunk: :: Branch, ordinary tag, leaf, and closed-leaf repository-state views are derived from stored artifacts after artifact-format parsing and repository crosslink/tag-state processing. The Artifact Format defines the T card syntax; the derivation of those views is specified in [FossilRepoState]. Current-trunk uses those repository-state results together with the repository's local main-branch setting, also specified in [FossilRepoState]. The sync protocol does not carry a separate branch, tag, or current-trunk state channel; it discovers, transfers, stores, dephantomizes, and crosslinks the artifacts from which each peer computes those views. Unversioned file: :: Local repository state outside the content- addressed artifact set. An unversioned-file sync uses pragma uv- hash, uvigot, uvgimme, and uvfile cards; the files are not artifacts and do not participate in the artifact hash-policy or tag-state rules. Card: :: One line of a sync message body. A card begins with a single-token operator and is followed by space-separated arguments. The card line is terminated by a single LF (0x0a). See Section 5 for the full card grammar. Client: :: The repository endpoint that initiates the exchange and drives successive rounds until synchronisation is complete. Server: :: The repository endpoint that replies to the client's requests. The server is stateless across rounds; all inter-round state is maintained by the client. Hipp, et al. Expires 7 January 2027 [Page 5] Internet-Draft Fossil Sync Protocol July 2026 servercode: :: A repository instance identifier included in push and pull cards. Each repository carries its own servercode. The value is informational; the receiver does not act on it. projectcode: :: An identifier shared by all repositories of the same Fossil project. The server MUST refuse to synchronise when the projectcode in a push or pull card does not match its own stored projectcode. round: :: One HTTP request and the corresponding HTTP response. A round ends when the response body is fully consumed; there is no terminal card. pragma: :: A directive card whose operator is the literal token pragma. Pragmas carry named parameters and govern protocol features such as version exchange, commit locks, and private-content enabling. Unknown pragma names are silently ignored; this is the forward- compatibility mechanism for the pragma namespace. An unknown non- pragma card operator is a fatal protocol error. igot: :: A card by which one side announces that it holds a specific artifact. gimme: :: A card by which one side requests the content of a specific artifact. Fossil release integer: :: A decimal integer encoding the Fossil software version as MAJOR * 10000 + MINOR * 100 + PATCH. Fossil 2.0 produces the value 20000. This integer is carried in version pragmas (Section 10.1) and governs version-gated send decisions. It is distinct from the clone protocol version. Clone protocol version: :: A small literal integer argument to the clone card indicating the artifact transfer encoding the client requests. Modern clients always send version 3, which causes the server to use the compressed cfile transfer path. This integer is independent of the Fossil release integer. fossilize encoding: :: The character-escaping scheme defined in [FossilArtifact] Section 4, used to encode strings that may contain spaces or control characters as arguments in card lines. Hipp, et al. Expires 7 January 2027 [Page 6] Internet-Draft Fossil Sync Protocol July 2026 3. Protocol Operation A sync is a sequence of rounds. The client builds a request, sends it, reads the reply, updates its state, and decides whether to issue another request. This section specifies the state each side maintains, the structure of each round, the phantom discovery and resolution loop, the clone loop, the request/response pragma semantics, and the termination condition. The card formats referenced here are defined in Sections 5 through 10. The transport encoding is defined in Section 4. Authentication is defined in Section 6. 3.1. Endpoint State The client maintains the following carried state. The server is stateless across rounds; it maintains no per-session state beyond persistent repository data. +=====================+=============+=============================+ | State | Scope | Description | +=====================+=============+=============================+ | projectcode | persistent | The project identifier both | | | | sides must share | +---------------------+-------------+-----------------------------+ | peer version | per-session | The remote side's recorded | | | | Fossil release integer | +---------------------+-------------+-----------------------------+ | peer date | per-session | The remote side's recorded | | | | version timestamp | +---------------------+-------------+-----------------------------+ | phantom set | persistent | Artifact hashes known but | | | | whose content is absent | +---------------------+-------------+-----------------------------+ | clone sequence | per-session | Next blob-table RID for the | | number | | server to send during a | | | | clone | +---------------------+-------------+-----------------------------+ | sync cookie | persistent | Opaque server token | | | | returned by the client each | | | | round | +---------------------+-------------+-----------------------------+ | round number | per-session | Count of completed request/ | | | | reply rounds in this sync | | | | session | +---------------------+-------------+-----------------------------+ | unversioned catalog | per-session | Whether pragma uv-hash has | | sent flag | | already been sent in this | Hipp, et al. Expires 7 January 2027 [Page 7] Internet-Draft Fossil Sync Protocol July 2026 | | | session | +---------------------+-------------+-----------------------------+ | unversioned send | per-session | Temporary table of local | | table | | unversioned names still | | | | eligible to upload, with an | | | | mtimeOnly marker per row | +---------------------+-------------+-----------------------------+ | unversioned upload- | per-session | Set after pragma uv-push- | | enabled flag | | ok; causes queued uvfile | | | | uploads to be emitted in | | | | later rounds | +---------------------+-------------+-----------------------------+ | unversioned pull- | per-session | Set after pragma uv-pull- | | only latch | | only; suppresses client | | | | unversioned uploads for the | | | | rest of the session | +---------------------+-------------+-----------------------------+ | send queue | per-round | Artifacts the client will | | | | push this round | +---------------------+-------------+-----------------------------+ | new-phantom flag | per-round | Set when any igot card | | | | creates a new phantom entry | +---------------------+-------------+-----------------------------+ | content-received | per-round | Set when any file or cfile | | flag | | card delivers stored | | | | content | +---------------------+-------------+-----------------------------+ | peer-has table | per-round | Artifact hashes the remote | | | | peer announced or sent in | | | | this round | +---------------------+-------------+-----------------------------+ | peer-lacks table | per-round | Artifact hashes the remote | | | | peer requested with gimme | | | | in this round | +---------------------+-------------+-----------------------------+ | unversioned-request | per-round | Number of uvgimme cards | | count | | queued while processing | | | | this round's reply | +---------------------+-------------+-----------------------------+ | unversioned-content | per-round | Number of uvfile cards | | count | | received in this round's | | | | reply | +---------------------+-------------+-----------------------------+ Table 1 Hipp, et al. Expires 7 January 2027 [Page 8] Internet-Draft Fossil Sync Protocol July 2026 When unversioned sync is enabled, the client initializes the unversioned send table at session start with every local unversioned row whose hash is not null, setting mtimeOnly false for each entry. The per-round tables and counters MUST be created or reset at the start of each round and MUST be destroyed or discarded at the end of that round; they carry no state across round boundaries and MUST NOT be treated as persistent storage. 3.2. Round Structure Each request body MUST include a pragma client-version card (Section 10.1). A current client normally begins the body-card sequence with that pragma and then writes the operation card. Two transport/order exceptions apply: in body-login mode, when a body login card is used, that login card is prepended before the body bytes whose nonce it covers; and on the initial round of a private- content sync, pragma send-private is written before pragma client- version, while later private rounds write client-version first and then repeat send-private. The first round of a modern clone suppresses the HTTP/body login card entirely (Section 8.3). The server parses body cards in the order they appear and records the peer version when it processes the pragma client-version card. Because the server decides SHA3-256 content eligibility from the recorded peer version at the moment it processes each content- requesting card, a client that may receive SHA3-256-named content MUST place pragma client-version before any content-requesting card (for example clone or gimme) in the same request: a version pragma appearing only after such a card is recorded too late to govern it, and the server MAY refuse SHA3-256-named content to a peer whose version it has not yet recorded. Subject to that ordering constraint, and to the login/send-private exceptions above, no further fixed body position is required beyond the pragma's presence in every request. The client includes, each round: * pragma client-version naming the client release and, for current clients, the source timestamp (Section 10.1); * an operation card: pull SERVERCODE PROJECTCODE, push SERVERCODE PROJECTCODE, both for a bidirectional sync, or clone 3 SEQNO for a modern clone (Section 8); * gimme HASH cards for eligible phantoms it wants resolved when the operation can receive versioned artifacts; * file or cfile cards carrying content the peer requested or that the client is pushing (Section 7); Hipp, et al. Expires 7 January 2027 [Page 9] Internet-Draft Fossil Sync Protocol July 2026 * igot HASH cards announcing artifacts the client holds; * reqconfig, configuration, and unversioned-file cards as the operation requires (Sections 7, 9, and 10); * optionally, a stored cookie card returning a previously stored cookie (Section 3.6); * one or more comment lines carrying per-round randomness (Section 5.3). For a current protocol-version-3 clone, the first request body is therefore the version pragma followed by clone 3 1 and the trailing randomness comment. It contains no login card. Configuration requests and pragma uv-hash are intentionally delayed until after clone round 0 (Section 8.4). The server reads the request body and replies with any applicable combination of: * pragmas responding to client pragmas; * a push SERVERCODE PROJECTCODE card, a pull SERVERCODE PROJECTCODE card, or both, when the server advertises its own repository identifiers; * igot HASH cards for artifacts the server holds and the client has not announced; * the content of artifacts the client requested with gimme; * gimme HASH cards for artifacts the client announced with igot that the server does not hold; * unversioned-file catalog or content cards when an unversioned-file exchange is active; * clone_seqno NEXT when the operation is a modern clone; * message or error cards as needed (Section 11); * a closing comment line carrying a timestamp and error count. The client processes each card in the server's reply in order: Hipp, et al. Expires 7 January 2027 [Page 10] Internet-Draft Fossil Sync Protocol July 2026 for each card C in the server reply body: if C is "push SERVERCODE PROJECTCODE" or C is "pull SERVERCODE PROJECTCODE": record the peer's advertised SERVERCODE and PROJECTCODE use PROJECTCODE as the peer project code for later authenticated rounds continue; only a separate rule such as `message pull only *` (Section 11.2) changes the selected operation else if C is "igot HASH": apply the igot/phantom rule of Section 3.3 else if C is "file ..." or "cfile ...": store content (Section 7) set content-received flag else if C is "gimme HASH": record that the peer lacks HASH if operation includes push and HASH is held locally and policy permits: add HASH to send queue for next round else if C is "uvigot ..." or "uvfile ..." or "uvgimme ...": process under the unversioned-file algorithm of Section 9.1 else if C is "clone_seqno N": set clone sequence number to N (Section 8.2) else if C is "error MSG": if first clone round: discard silently (Section 11.1) else: abort the sync (Section 11) else if C is "cookie TEXT": store TEXT as the sync cookie for this server (Section 3.6) else if C begins with "#": process as comment line (Section 5.3); not a card dispatch # remaining card types per Sections 5 through 10 The round's per-round tracking tables are destroyed after all reply cards have been processed. The client then evaluates the termination condition (Section 3.7) before building the next request. 3.3. Phantom Record Lifecycle This section is the authoritative phantom, igot, gimme, and phantom- related termination rule surface. Later strategy sections summarize this behavior and cross-reference this section rather than restating an independent algorithm. A phantom is a blob-table entry whose hash is known but whose content is absent. Phantoms arise in two ways: Hipp, et al. Expires 7 January 2027 [Page 11] Internet-Draft Fossil Sync Protocol July 2026 1. An igot HASH card names an artifact the receiver does not hold, and the receiver is in an operation state that can obtain that artifact. This covers a pulling or cloning client receiving server igot cards and a pushing server receiving client igot cards. 2. A file or cfile card arrives whose DELTASRC argument names a source artifact the receiver does not yet hold. Each round creates two temporary tracking tables. The peer-has table records artifact hashes the remote peer announced or successfully sent in the round, so this side avoids sending the peer content it has just said it already holds. The peer-lacks table records hashes the peer requested with gimme; the request itself is the evidence that the peer lacks HASH in this round, and the table prevents this side from immediately asking that same peer for the same HASH in the same round. Both are the per-round tracking tables introduced in Section 3.1 (Endpoint State) and follow the lifecycle specified there. When an igot HASH card creates a phantom, the receiver MUST make that phantom eligible for gimme emission when constructing a pull, push- receive, or eligible clone message. A side emits gimme for eligible phantoms subject to the filters below. The eligibility filter is evaluated freshly each round and excludes: (a) hashes present in the peer-lacks table for this round; (b) shunned hashes; and (c) private hashes unless private-content synchronisation is enabled for this session. A receiver that receives gimme HASH MUST record that the peer lacks HASH for this round. If the receiver holds HASH, the current operation direction permits sending it, and hash-policy/private- content rules permit disclosure, the receiver sends the content in this or a subsequent round. If the receiver holds HASH but the current operation direction does not permit sending it, the receiver emits no content and no error card, and does not defer the send to a later round. If the receiver does not hold HASH, it MUST silently skip the request without emitting an error card. A phantom MUST be deleted when content for that artifact is successfully stored. In the normal path, the content storage operation atomically updates the blob row and removes the phantom record. In the dangling-delta path, when a file or cfile card arrives with a DELTASRC that is not yet available locally, the delta Hipp, et al. Expires 7 January 2027 [Page 12] Internet-Draft Fossil Sync Protocol July 2026 payload for HASH is stored as received, the phantom record for HASH is deleted, and a phantom record is created for DELTASRC. Full delta reconstruction is deferred until the source artifact arrives. The content-received flag is set in both paths. 3.4. The Clone Loop A modern clone is a normal sequence of sync rounds whose operation card is clone 3 SEQNO. The detailed clone algorithm, including the required opening cards, clone_seqno continuation, and first-round login suppression, is specified once in Section 8. This operation section only establishes that clone replies are processed by the same card dispatch loop and termination rule as other sync rounds. 3.5. Request and Response Pragmas Pragmas are ordinary body cards whose operator is pragma; they are parsed in round order along with all other body cards. Unknown pragma names are silently ignored and MUST NOT be treated as protocol errors, while an unknown non-pragma operator remains a fatal protocol error. The detailed, authoritative catalog of all defined pragma names, arguments, directions, duplication behavior, and operation- specific effects is Section 10. 3.6. Cookie Card The server MAY emit a cookie TEXT card in its reply, where TEXT is an opaque value. The client that receives such a card MUST store the value, replacing any previously held cookie for that server. The client MAY include cookie TEXT in a subsequent request to return the stored value. The server MUST NOT depend on receiving a cookie card. The server must tolerate cookie cards from a different server and must be prepared to receive more than one cookie card in a single request. The cookie mechanism is an optimisation only; a client that never returns a cookie is fully conformant. 3.7. Termination The client MUST issue another round if and only if at least one of the following conditions holds after processing the previous round's reply: Hipp, et al. Expires 7 January 2027 [Page 13] Internet-Draft Fossil Sync Protocol July 2026 (a) Versioned artifact progress occurred — one or more file or cfile cards delivered stored content, including the dangling-delta path, or an igot card created a new phantom — and the phantom table is non- empty after the round. This phantom-table guard applies to non-clone operations; clone continuation is governed by condition (e). (b) Versioned content is queued for outbound push: the send queue is non-empty because the peer requested artifacts or local push work remains. (c) A private-content discovery round is required: private igot information was observed in the first round of a private sync and a second round is needed to request or suppress the private artifacts under the negotiated authorization. (d) Unversioned-file work is pending. This condition is true if either: 1. the per-session unversioned send table is non-empty and the session's unversioned upload-enabled flag is set; or 2. one or more `uvgimme` cards were queued while processing this round's reply, and either one or more `uvfile` cards were received in that same reply or the session round number, after incrementing for the completed round, is less than 3. Clause (d)(2) is the current three-cycle continuation rule of the Fossil wire behavior. Before the third completed round of the session, a round that queued `uvgimme` forces one more request even if no `uvfile` has yet arrived. On later rounds, a `uvgimme`-only round does not by itself continue the exchange. Section 9.1 defines how `uvgimme`, `uvfile`, and repeated `uvigot` cards advance that state. (e) The operation is a modern clone and at least one clone-specific continuation condition holds: this is the first clone round; at least one artifact was received this round; or the received clone_seqno NEXT is positive and the total artifact count grew this round (Section 8.2). (f) Configuration exchange is pending: a reqconfig deferred during clone (Section 8.4), or otherwise required by the client, has not yet been sent and answered. The client MUST NOT issue another round solely because phantom records remain in its local database. Unresolved phantoms at termination are not a protocol error; they arise when a referenced artifact was not present on the peer or was excluded by policy. Hipp, et al. Expires 7 January 2027 [Page 14] Internet-Draft Fossil Sync Protocol July 2026 When none of conditions (a) through (f) holds, the client stops. The server signals no completion; each reply's closing comment line carries only a timestamp and an error count. Stopping means no further protocol progress is required: when a round transfers no content in either direction, creates no new phantom, and leaves no outbound versioned, unversioned, clone, or private-discovery work pending, no additional rounds are indicated. A worked example of a complete exchange appears in Appendix A. 3.8. Client Protocol State Machine The preceding subsections specify the client's behaviour round by round. This subsection consolidates that behaviour into an explicit state machine, using the named-state and carried-state discipline of TCP [RFC9293] and the request/response-oriented organizational style of IMAP [RFC9051]. It is a restatement for implementers, not a new source of requirements: where this subsection and a cited section differ, the cited section governs. Because the server is stateless across rounds (Section 3.1), only the client runs a protocol state machine; the server reacts to each request independently. The client occupies one of five states. Hipp, et al. Expires 7 January 2027 [Page 15] Internet-Draft Fossil Sync Protocol July 2026 +==============+=================================================+ | State | Meaning | +==============+=================================================+ | INIT | Operation selected and endpoint state | | | initialised; no round sent yet. | +--------------+-------------------------------------------------+ | CLONE_ROUND0 | The first round of a modern clone is in flight: | | | the login card is suppressed, configuration and | | | uv-hash are deferred, and an error reply is | | | ignored (Sections 8.3, 8.4, 11.1). | +--------------+-------------------------------------------------+ | EXCHANGE | The steady round loop: an authenticated request | | | is sent, the reply is processed by the card- | | | dispatch loop of Section 3.2, and phantom, | | | send-queue, unversioned-file, configuration, | | | and private-content work advances. | +--------------+-------------------------------------------------+ | TERMINATED | Clean stop: after the last round, none of the | | | continuation conditions of Section 3.7 held. | +--------------+-------------------------------------------------+ | ABORTED | A fatal protocol error ended the sync without | | | convergence. | +--------------+-------------------------------------------------+ Table 2 +------+ | INIT | +--+---+ clone 3 SEQNO / \ push / pull / sync v \ +--------------+ \ | CLONE_ROUND0 | \ +------+-------+ \ reply; | | errors ignored | | (11.1) v v +----------------+ ---. | EXCHANGE | | any of 3.7 (a)..(f): +----------------+ <--' send next round | | none of 3.7 | | fatal protocol error (a)..(f) | | v v +------------+ +---------+ | TERMINATED | | ABORTED | +------------+ +---------+ Hipp, et al. Expires 7 January 2027 [Page 16] Internet-Draft Fossil Sync Protocol July 2026 The transitions are: +==============+==============+=====================+==============+ | From | Event or | Action | To | | | guard | | | +==============+==============+=====================+==============+ | INIT | operation is | send the first | CLONE_ROUND0 | | | a modern | clone request: | | | | clone (clone | clone 3 1, no login | | | | 3 SEQNO) | card, configuration | | | | | and uv-hash | | | | | deferred | | | | | (Section 8.3) | | +--------------+--------------+---------------------+--------------+ | INIT | operation is | send the first | EXCHANGE | | | push, pull, | request: | | | | or sync | authentication | | | | | (login card or | | | | | cookie, Section 6), | | | | | pragma client- | | | | | version, and the | | | | | operation card | | +--------------+--------------+---------------------+--------------+ | CLONE_ROUND0 | reply | record clone_seqno | EXCHANGE | | | processed | (Section 8.2); any | | | | | error card is | | | | | discarded silently | | | | | (Section 11.1) | | +--------------+--------------+---------------------+--------------+ | CLONE_ROUND0 | transport | abort | ABORTED | | | failure or | | | | | redirect | | | | | limit | | | | | exceeded | | | +--------------+--------------+---------------------+--------------+ | EXCHANGE | at least one | build and send the | EXCHANGE | | | continuation | next request for | | | | condition of | the operation | | | | Section 3.7 | | | | | (a)-(f) | | | | | holds | | | +--------------+--------------+---------------------+--------------+ | EXCHANGE | none of | stop; the client | TERMINATED | | | Section 3.7 | sends nothing | | | | (a)-(f) | further and the | | | | holds | server signals no | | | | | completion | | +--------------+--------------+---------------------+--------------+ Hipp, et al. Expires 7 January 2027 [Page 17] Internet-Draft Fossil Sync Protocol July 2026 | EXCHANGE | a fatal | reset partial | ABORTED | | | protocol | output and abort | | | | error occurs | | | | | (below) | | | +--------------+--------------+---------------------+--------------+ Table 3 A fatal protocol error, in any state other than CLONE_ROUND0, is any of: an error card (Section 11); an unknown non-pragma card operator (Section 5); a card or comment line that exceeds the Section 5 maximum line length; a malformed file, cfile, or uvfile card (Section 7); a project-code mismatch (Section 9.1); an authentication failure (Section 6); a redirect limit exceeded (Section 4); a clone_seqno value below zero (Section 8.2); or a SHA3-256 peer- version refusal (Section 7.6). Within EXCHANGE, the per-card processing of each reply is the dispatch loop of Section 3.2, and the guard between another EXCHANGE round and TERMINATED is the condition of Section 3.7. 3.9. Robustness Posture This protocol is intentionally strict about malformed input. It does not adopt the receive-side half of the TCP robustness principle as summarized in [RFC9293] (liberal acceptance of input). A conforming client is conservative in what it sends. It emits only well-formed cards, in the order Section 3.2 requires. A receiver MUST reject, as a fatal error, an unknown non-pragma card operator (Section 5) and a malformed content card (Section 7). The reason is interoperability. A parser that guessed at malformed or unrecognised input would let two independent implementations diverge, one tolerating what the other rejects, and it would widen the input surface an attacker can probe. The protocol is liberal only where liberality cannot cause divergence, and it names each such point. Unknown pragma names are ignored (Section 10). Receivers MAY accept runs of Fossil whitespace between tokens as a compatibility extension (Section 5), but senders MUST emit the canonical single- space form and MUST NOT rely on surplus trailing tokens being preserved. A cookie card from an unexpected server is tolerated (Section 3.6). An error card in the first round of a clone is discarded (Section 11.1). At any other point, a receiver applies a defined rule or aborts. Hipp, et al. Expires 7 January 2027 [Page 18] Internet-Draft Fossil Sync Protocol July 2026 3.10. Round Message Layout This subsection consolidates, for quick reference, the cards that make up a request body and a reply body. It restates the lists of Section 3.2; where it and Section 3.2, or the owning section of a card, differ, those sections govern. Request body, in the order a client writes it: +=========================+==============================+==========+ | Card | When present | Owning | | | | section | +=========================+==============================+==========+ | pragma client-version | every request, before any | Section | | | content-requesting card | 10.1 | +-------------------------+------------------------------+----------+ | operation card (pull, | every request | Sections | | push, or clone 3 SEQNO) | | 8, 9 | +-------------------------+------------------------------+----------+ | login card | authentication, unless | Section | | | cookie mode or clone | 6 | | | round 0 | | +-------------------------+------------------------------+----------+ | gimme HASH | eligible phantoms to | Sections | | | resolve | 7, 9 | +-------------------------+------------------------------+----------+ | file / cfile | content the client pushes | Section | | | or the peer requested | 7 | +-------------------------+------------------------------+----------+ | igot HASH | artifacts the client | Section | | | holds | 9 | +-------------------------+------------------------------+----------+ | reqconfig, | as the operation requires | Sections | | configuration, | | 7, 9, 10 | | unversioned-file cards | | | +-------------------------+------------------------------+----------+ | cookie TEXT | returning a stored cookie | Section | | | | 3.6 | +-------------------------+------------------------------+----------+ | comment line (#) | every request, carrying | Section | | | per-round randomness | 5.3 | +-------------------------+------------------------------+----------+ Table 4 Reply body, any applicable combination: Hipp, et al. Expires 7 January 2027 [Page 19] Internet-Draft Fossil Sync Protocol July 2026 +==================+==================================+==========+ | Card | When present | Owning | | | | section | +==================+==================================+==========+ | pragmas | responding to client pragmas | Section | | | | 10 | +------------------+----------------------------------+----------+ | push / pull | the server advertises its own | Sections | | | identifiers; the card is | 3, 9, 11 | | | recorded, and only a separate | | | | rule such as message pull only * | | | | changes the selected operation | | +------------------+----------------------------------+----------+ | igot HASH | artifacts the server holds that | Section | | | the client did not announce | 9 | +------------------+----------------------------------+----------+ | content (file / | artifacts the client requested | Section | | cfile) | with gimme | 7 | +------------------+----------------------------------+----------+ | gimme HASH | artifacts the client announced | Section | | | that the server lacks | 9 | +------------------+----------------------------------+----------+ | unversioned-file | an unversioned-file exchange is | Section | | catalog / | active | 9.1 | | content cards | | | +------------------+----------------------------------+----------+ | clone_seqno NEXT | the operation is a modern clone | Section | | | | 8.2 | +------------------+----------------------------------+----------+ | message / error | as needed | Section | | | | 11 | +------------------+----------------------------------+----------+ | closing comment | every reply, carrying a | Section | | line | timestamp and error count | 5.3 | +------------------+----------------------------------+----------+ Table 5 4. Transport A sync message is carried in the body of an HTTP/1.1 POST request [RFC9110]. The request-target is the path of the repository URL unchanged. The client MUST NOT append any path component, including /xfer, to the request-target; a URL whose path component is empty uses /. Requests whose Content-Type is application/x-fossil or application/x-fossil-debug are dispatched to the sync handler regardless of request-target path; the bare repository URL is therefore sufficient. application/x-fossil-uncompressed is a clone- Hipp, et al. Expires 7 January 2027 [Page 20] Internet-Draft Fossil Sync Protocol July 2026 reply media type, not a request media type. The message format is identical regardless of whether it is carried over HTTP, HTTPS, or SSH. When the transport is SSH the client includes the header X-Fossil-Transport: SSH; this is the only protocol-defined non-standard header. Standard HTTP headers — Content-Type, Content-Length, User-Agent, and, when applicable, Proxy-Authorization, Authorization: Basic, and Host — are included as normal. A sync request is always an HTTP POST. A sync message is never empty, so the empty-payload case that would otherwise be sent as a GET does not arise during synchronisation. A server MUST NOT process sync cards from a request whose method is not POST; such a request is instead redirected to the repository home page. The request MUST carry a Content-Length header giving the exact byte count of the payload that follows the header block. The client reads the reply body as delimited by the reply Content- Length header, consuming exactly that many payload bytes after the blank line that terminates the reply header block. If the reply carries no Content-Length, the client instead reads until the connection closes, growing its receive buffer as needed up to a hard cap of 536,870,912 bytes (512 MiB); a reply that would exceed that cap MUST be rejected rather than buffered without bound. An HTTP transport exchange MUST NOT follow more than 19 HTTP redirects (status 301, 302, 307, or 308) for a single exchange; on encountering a twentieth redirect, the exchange MUST abort with a fatal redirect-limit error. A transport exchange MUST NOT downgrade an HTTPS connection to plaintext HTTP as the result of following a redirect, and MUST NOT follow a redirect at all when the original transport is SSH or a local file path. When following a redirect, a trailing "/xfer" path segment present in the target location MUST be stripped before the location is used as the new request base; this stripping is repeated while such a segment remains. No other path transformation is applied, and the original repository URL's path is not consulted: after stripping, the (possibly shortened) target location is parsed as the new base URL. ("/xfer" is the sync endpoint suffix a server appends when redirecting a client to its transfer endpoint; removing it recovers the base repository URL.) 4.1. Message Compression and Media Types Three Content-Type values are defined: Hipp, et al. Expires 7 January 2027 [Page 21] Internet-Draft Fossil Sync Protocol July 2026 application/x-fossil :: Normal sync. The message body is compressed with zlib [RFC1950]. This media type is used for all requests and for replies to pull, push, and sync operations. application/x-fossil-debug :: Diagnostic debugging and testing only. The message body is NOT compressed; content is otherwise identical to application/x-fossil. This variant MUST NOT be used in production sync exchanges. application/x-fossil-uncompressed :: Clone replies only. The server uses this Content-Type for its response to a clone request when the clone protocol version is 3 (Section 8). The response body is NOT zlib-compressed at the outer message level; this is because the cfile payloads it contains are already in compressed form as stored in the repository, and recompressing them would waste CPU without reducing size. These three media types are used only within the Fossil sync protocol context. Their registration is requested in Section 13. Whole-payload transport compression and stored blob content share one compression primitive and container format. The compressed container consists of a 4-byte big-endian field giving the uncompressed length of the input offered to the compressor by the sender, followed by a standard zlib [RFC1950] stream: a 2-byte zlib header, a DEFLATE- compressed body [RFC1951], and a 4-byte Adler-32 trailer. This container is neither raw headerless DEFLATE nor gzip framing. A sender MUST encode the actual length of the pre-compression input in the 4-byte length field. A receiver MUST use that field as the allocation capacity for its decompression output buffer, MUST reject the envelope when the zlib stream is malformed, when its Adler-32 trailer does not verify, or when the decoder cannot fit its output within that capacity, and MUST NOT require the actual decoded length to equal the field value when the decoder succeeds within capacity. The actual decoded length is the number of payload bytes the receiver processes. The ordinary single-input compression path, used for a normal payload or a stored blob, uses the zlib default compression level. When a login card is prepended ahead of the body in inline login mode (Section 6.1), the same container is produced over the two concatenated inputs and is compressed at DEFLATE level 9; implementations MUST NOT rely on a particular compression level, since the container is self-describing and the decompressor is level- independent. Because stored blob content is written and retransmitted verbatim, the container used for wire transport and the container used for stored content are byte-identical. Hipp, et al. Expires 7 January 2027 [Page 22] Internet-Draft Fossil Sync Protocol July 2026 4.2. Round Structure A sync session consists of one or more rounds. Each round is one HTTP POST request and its response; a round ends when the response body is exhausted. There is no terminal card (no done or end operator) in the Fossil sync protocol; a receiver MUST NOT treat body exhaustion as an error. Section 3.2 specifies the round model. That model covers the cards each side emits each round, the client's reply-processing loop, and the per-round tracking-table requirements. 4.3. Cookie Card The sync protocol defines a cookie TEXT wire card as a transport- layer optimisation. Section 3.6 defines the storage, return, and server-tolerance rules. This section records only the wire role: the card carries one opaque TEXT value, may appear in either a request or a response, and has no protocol-defined meaning beyond being returned by convention between the same peers. 5. Card Format 5.1. Message Structure A sync message body is a sequence of lines. Lines are separated by a single LF byte (0x0a); there are no other line-ending conventions. Each line is either a card or a comment line (Section 5.3). Several cards carry a byte-counted payload (Sections 7 and 10). For those cards the payload begins on the byte immediately after the card line's terminating LF; the payload MAY contain LF bytes. A receiver MUST locate the end of the payload by its declared byte count and MUST NOT scan the payload for a separator. A message parser that splits on LF without accounting for byte-counted payloads will misframe any payload containing a LF byte. 5.2. Card Syntax A card is an operator token followed by zero or more argument tokens, terminated by a single LF byte. The canonical wire form uses exactly one space character between adjacent tokens, with no leading or trailing whitespace on the line. An operator token is a sequence of lowercase US-ASCII letters and, for clone_seqno, an underscore. The character encoding scheme for argument values that contain spaces, tabs, newlines, or other special characters is the fossilize scheme defined in [FossilArtifact] Section 4; receivers MUST apply defossilize decoding to fossilize-encoded arguments before use. Hipp, et al. Expires 7 January 2027 [Page 23] Internet-Draft Fossil Sync Protocol July 2026 On receipt, the reference parser tokenizes a card line on runs of Fossil whitespace inside the line: SP, HTAB, VT, FF, or CR. LF remains the card-line terminator and is not part of any token. A receiver MUST accept the canonical single-space form. A receiver MAY additionally accept other Fossil-whitespace runs as a compatibility extension, interpreting each such run as a token separator; a sender MUST NOT rely on that extension and MUST NOT emit non-canonical separators. A receiver MUST impose a finite maximum length on each card line and comment line, measured from the first byte of the line through and including its terminating LF, and excluding any following byte- counted payload. This specification sets that maximum to 65535 bytes. If the terminating LF is not found within that bound, the receiver MUST treat the line as malformed and abort the exchange before attempting payload framing. An unknown card operator (a first token that is not one of the defined operators listed in Section 5.2.1) is a fatal protocol error; the receiver MUST reset its partial output and emit an error card. This rule is distinct from the handling of unknown pragma names, which are silently ignored (Section 10). The fatal rule applies only when the first token is not a defined operator; a _defined_ operator that carries a malformed argument count is not treated as unknown, but is handled by that card type's own arity and error rule, described below. A card carrying more tokens than the defined form for its operator is malformed. Current Fossil implementations expose at most the first six parsed tokens to the per-card handler; seventh and later tokens can therefore be discarded before card-specific validation runs. Interoperable senders MUST NOT emit surplus tokens. A receiver that detects surplus tokens SHOULD treat the line as malformed. A receiver that follows the fixed six-token parser MAY instead produce the observable failures described below when truncation leaves the handler with an arity error. Hipp, et al. Expires 7 January 2027 [Page 24] Internet-Draft Fossil Sync Protocol July 2026 When a fixed-slot parser truncates a surplus-token line to six tokens, the card type's own arity check produces the observable failure. For the content-bearing card types (file, cfile, and uvfile), a failed arity check produces an error malformed CARD line card and the exchange is aborted. For structurally simpler card types, a failed arity check causes the line to be handled as an unrecognized card, answered with an error bad command: LINE card whose payload is the offending line; this outcome is fatal to the exchange when it occurs on the client side and non-fatal when it occurs on the server side. There is no "Unknown message" wire text: the framing for an unrecognized card is exactly error bad command: followed by the offending line (Appendix C). 5.2.1. Defined Operators This section specifies the operators covered by Sections 4 through 6 of this document. The complete operator catalog is assembled across all sections; operators not listed here are defined in Sections 7 through 11. Client-to-server (this section): login (Section 6.1), push and pull (Section 3), cookie (Section 4.3). Server-to-client (this section): cookie (Section 4.3). The remaining operators — clone, file, cfile, uvfile, private, igot, uvigot, gimme, uvgimme, reqconfig, config, clone_seqno, pragma, error, and message — are defined in Sections 7 through 11. 5.3. Comment Lines Any line in a sync message body whose first byte is ASCII # (0x23) is a comment line. Comment lines are not card operators; they carry no argument tokens and are not dispatched by either parser. The server skips all #-prefixed lines silently. The client skips #-prefixed lines in its receive loop without dispatching them, with one exception: before skipping, the client tests whether the line matches the subform # timestamp DATETIME errors N where DATETIME is the 19-byte fixed-width form YYYY-MM-DDTHH:MM:SS — four-digit year, zero-padded month, day, hour, minute, and second components, an ASCII T (0x54) between the date and the time, no fractional-second field, and no time-zone designator; the server clock is presented as UTC. N is a non-negative decimal integer with no sign, no thousands separator, and no leading zeros (a single 0 Hipp, et al. Expires 7 January 2027 [Page 25] Internet-Draft Fossil Sync Protocol July 2026 represents zero). A sender MUST emit DATETIME in exactly this form; a receiver reads the first 19 bytes after the ASCII prefix # timestamp as DATETIME and MUST NOT require additional grammar within those 19 bytes. If the line matches, the client reads DATETIME to compute clock skew relative to local time; the error count N is informational only and MUST NOT be treated as a wire-level error signal. Other #-prefixed lines in the client receive loop are not semantically interpreted. Both client and server emit the informational comment lines # sending-clusters and # end-of-clusters when transmitting cluster igot cards; these are advisory and carry no normative semantics. Each client request ends with a #-prefixed comment line carrying implementation-generated random bytes. This ensures that the body bytes following the login card (from which the authentication nonce is derived; see Section 6.2) differ between rounds even when all other content is identical. 6. Authentication 6.1. Login Card When a request uses Fossil's sync login-card mechanism, it carries exactly one login card, either as a body card or in the cookie-login HTTP header (Section 6.5). The body-card form is: login USER NONCE SIGNATURE USER is the login name encoded using the fossilize scheme of [FossilArtifact] Section 4. NONCE and SIGNATURE are each exactly 40 lowercase hexadecimal characters. A request containing more than one login card is a fatal protocol error; this includes the case where one login card arrives through the cookie header and another appears in the body. The receiver MUST reset its partial output and emit an error card. A login card MUST NOT be emitted when the user is anonymous or nobody; those identities carry their configured capabilities without challenge. A login card is also not emitted when the transport is SSH; the SSH layer provides its own authentication. The first round of a current protocol-version-3 clone also omits both body-login and cookie-login cards, as specified in Section 8.3. Hipp, et al. Expires 7 January 2027 [Page 26] Internet-Draft Fossil Sync Protocol July 2026 6.2. Nonce Derivation The NONCE value is the SHA-1 [RFC3174] digest of all message body bytes that follow the login card line — that is, the bytes beginning immediately after the LF that terminates the login card, through the end of the message body. The server verifies the nonce by computing SHA-1 over the same byte range in the received (decompressed) body. In cookie-login mode (Section 6.5) the payload nonce covers only the body bytes; the HTTP header carrying the login card is not included in the nonce computation. 6.3. Shared Secret The shared secret is derived locally on each side and is never transmitted. It is computed as the SHA-1 digest of three fields concatenated with / separators: shared-secret = SHA1( project-code "/" login-name "/" plaintext-password ) where project-code is the repository project identifier, login-name is the login name exactly as carried in USER, and plaintext-password is the user's password in plaintext form. The result is 40 lowercase hexadecimal characters. A current protocol-version-3 clone does not use a plaintext-password substitute on its first round. Instead, the client sends no login card at all in that round; after it learns the project code from the server's clone reply, later authenticated rounds use the normal shared-secret derivation and login-card transport rules. 6.4. Signature Computation The SIGNATURE value is the SHA-1 digest of the NONCE hex string concatenated with the shared-secret hex string: SIGNATURE = SHA1( NONCE-hex || shared-secret-hex ) Both inputs are 40-character lowercase hexadecimal strings. The concatenation is byte-level with no separator, yielding a 80-byte input to SHA-1. The result is 40 lowercase hexadecimal characters. The server authenticates a request by independently computing the same derivation — reconstructing the shared secret from its stored credential for the named user, combining it with the received NONCE, and comparing the result to the received SIGNATURE. Hipp, et al. Expires 7 January 2027 [Page 27] Internet-Draft Fossil Sync Protocol July 2026 The plaintext password, the shared secret, and any intermediate value derived from them MUST NOT appear on the wire in any form. The NONCE is derived from the message-body bytes that follow the login card; SIGNATURE is derived from the NONCE and the shared secret. Because each request appends an implementation-generated random comment line (Section 5.3), independently generated rounds produce distinct NONCE values. The server recomputes the NONCE from the received body tail and the SIGNATURE from the received NONCE and the stored credential, but maintains no nonce cache and applies no timestamp freshness check. A byte-for-byte replay of a previously authenticated request will therefore still pass server verification; protection against such replay MUST be provided by the transport layer (Section 12.1). Before any card is parsed, the server establishes a baseline capability set using the same session, cookie, HTTP Basic authentication, and web-server remote-user machinery it uses for ordinary web pages; this is the only point at which capability state is reset from scratch. A login card, when present, is verified and applied afterward and is purely additive: a successful login card can only add capability bits on top of the baseline, never remove any. The two mechanisms are sequential contributors to one capability set, combined by union, not related by precedence. A login card that fails verification leaves the baseline untouched but MUST cause the exchange to abort. Server-side verification of a login card proceeds as follows: 1. Special-cased identities. Logins of nobody or anonymous succeed unconditionally, with no signature check; anonymous synchronisation is always permitted. A matching authenticated remote-user identity (HTTP Basic authentication), where the server is configured to accept it, is honoured next. 2. Signature check, primary form. For a named user, the server treats the stored credential bytes directly as the shared secret, regardless of their stored format, computes SHA1( NONCE-hex || stored-bytes ), and compares the result to the received SIGNATURE using a constant-time, case-sensitive comparison over the 40-character ASCII values. 3. Signature check, stored-credential fallback. Only if the primary comparison fails, and only if the stored credential is not exactly 40 bytes long (hence a cleartext stored credential by the storage convention), the server re-derives the shared secret from the stored cleartext password, the name, and its own project code (Section 6.3) and re-checks the SIGNATURE. The server does not rewrite the stored credential as a side effect. Hipp, et al. Expires 7 January 2027 [Page 28] Internet-Draft Fossil Sync Protocol July 2026 4. Tail-hash check. Independent of the signature check, the server verifies that the NONCE equals a fresh SHA-1 hash of the remainder of the request body following the login line (Section 6.2), a case-sensitive comparison over the 40-character hash values. Login MUST be rejected if either the signature check or the tail-hash check fails. On authentication failure the server MUST NOT change the HTTP status code, which remains 200; instead it discards any staged reply content, emits an error login failed card, records the failure, and breaks out of the card-processing loop, ending the exchange. A failing login card therefore terminates the exchange at the protocol layer, not the HTTP layer. 6.5. Cookie-Login Mode When both of the following conditions hold, the client transmits the login card via the standard HTTP Cookie header rather than in the message body: 1. The peer's recorded VERSION (from a prior pragma server-version card) is at least 22700 (Fossil 2.27); and 2. The peer's recorded timestamp is on or after 2025-07-27 11:05:00. The cookie header carries the full login card text URL form-encoded, with each space replaced by +: Cookie: x-f-l-c=login+USER+NONCE+SIGNATURE The header value is the text login USER NONCE SIGNATURE with each SP converted to +; URL-unsafe bytes in the fossilize-encoded USER field are additionally percent-encoded. The server URL-decodes the value and processes the resulting login card by the same code path as a body-embedded login card; the application-layer card semantics are unchanged. The login card MUST NOT appear in the message body when cookie-login mode is in effect. The standard HTTP Cookie header containing the x-f-l-c cookie-pair is the only cookie-related header used by the Fossil sync protocol; there is no X-Fossil-* header equivalent. This version gate applies only to the x-f-l-c cookie transport defined in this section. When both conditions above are met for the current peer, the client MUST use the x-f-l-c cookie transport and MUST NOT include a body-embedded login card. When either condition is not satisfied — including any round in which the peer's pragma server-version has not yet been observed — the client MUST fall back to the body-embedded login card defined in Section 6.1; the fallback Hipp, et al. Expires 7 January 2027 [Page 29] Internet-Draft Fossil Sync Protocol July 2026 is the ordinary Section 6.1 transport, unmodified by this section. A client MUST NOT emit the x-f-l-c cookie header against an ungated peer. In the absence of an x-f-l-c cookie login, a server MUST accept a body-embedded login card, irrespective of whether the peer would also be gated for the cookie transport. The one-login-per- request invariant of Section 6.1 is preserved: a request that carries both an x-f-l-c cookie login and a body-embedded login card is a protocol error under Section 11.1, independently of whether either form would otherwise be gated. 6.6. Capability Model Users are assigned capability letters by the server. Capabilities govern what operations the server will accept from the authenticated user: Read (o) permits pull; Write (i) permits push; Clone (g) permits clone; Private (x) permits private-content transfer; administrator capabilities permit configuration and user-management operations. The server checks the capability appropriate to each card it processes and emits an error card for a request that lacks the required capability. 7. Content Transfer Versioned artifact content is transferred by file and cfile cards. The uvfile card is specified in this section because it uses the same byte-counted framing model while carrying the protocol's unversioned- file synchronization state outside the artifact model. 7.1. file Card A file card has one of two forms: file HASH SIZE file HASH DELTASRC SIZE HASH is the artifact name ([FossilArtifact], Section 3). SIZE is the count of payload bytes that follow immediately after the card's newline. The payload is uncompressed and is opaque: it MAY contain the newline byte 0x0a. A receiver MUST locate the end of the payload by the byte count and MUST NOT scan the payload for a separator. After exactly SIZE payload bytes, the next message byte, if any, is the first byte of the next card line; there is no trailing separator after the payload. The three-argument form carries the full artifact content. The four- argument form carries a delta [FossilDelta] against the artifact named DELTASRC. Hipp, et al. Expires 7 January 2027 [Page 30] Internet-Draft Fossil Sync Protocol July 2026 file cards are used for push and pull transfers. A file card is never emitted by the server on the clone 3 SEQNO path; Section 8 defines that clone transfer path separately. 7.2. cfile Card A cfile card has one of two forms: cfile HASH USIZE CSIZE cfile HASH DELTASRC USIZE CSIZE HASH is the artifact name. In the four-argument form, DELTASRC is the artifact name of the delta basis. USIZE is the sender's uncompressed size for the full artifact named by HASH after any delta reconstruction; in the delta form it is therefore the reconstructed target artifact size, not a byte count for the delta payload. CSIZE is the exact count of payload bytes that follow immediately after the card's newline. A receiver MUST locate the end of the payload by CSIZE and MUST NOT use USIZE as a framing boundary. After exactly CSIZE payload bytes, the next message byte, if any, is the first byte of the next card line; no extra separator follows the payload. Current Fossil receivers parse USIZE for syntax but do not validate the received payload against it at the transfer layer. The payload is the artifact's stored repository content transmitted verbatim. It is already in Fossil's stored compressed container. For a full-content cfile, the payload is the compressed full artifact. For a delta cfile, the payload is the compressed delta stored for HASH against DELTASRC. The sender does not re-compress the payload for the card; it writes the stored bytes. When the enclosing response body uses the application/x-fossil-uncompressed media type (Section 4.1), the outer body is not zlib-compressed, so the cfile payloads inside are not double-compressed. cfile cards are emitted by the server on the clone 3 SEQNO path (Section 8). No pragma, content-size threshold, or capability negotiation governs this choice; the clone card selects it. Push and pull transfers use file cards. 7.3. uvfile Card A uvfile card carries unversioned-file synchronization state outside the artifact model [FossilArtifact] and outside the artifact hash- policy and tag-state rules. uvfile NAME MTIME HASH SIZE FLAGS Hipp, et al. Expires 7 January 2027 [Page 31] Internet-Draft Fossil Sync Protocol July 2026 NAME is the file name encoded using the fossilize character-escaping scheme ([FossilArtifact], Section 4). MTIME is the modification time expressed as a decimal count of seconds since the Unix epoch. HASH is the content hash of the file, or the literal - when the card represents a deletion. SIZE is the byte count of the payload that follows immediately after the card's newline when content is present. FLAGS is a non-negative decimal integer interpreted as a bit field. Bit 0x0001 marks deletion; bit 0x0004 marks omitted content. All other bits are reserved and have no defined semantics in this version of the protocol. A sender MUST clear every reserved bit before emitting the card and MUST NOT overload any reserved bit with an implementation signal. A receiver MUST reject a negative FLAGS value as a malformed uvfile line and MUST ignore every reserved bit in a non-negative FLAGS value: masking off the reserved bits MUST NOT change any subsequent receiver behavior. For example, 2 (only the reserved 0x0002 bit set) is treated exactly as 0, and 6 (0x0002 | 0x0004) or 20 (0x0010 | 0x0004) is treated exactly as 4. The receiver decides deletion from the HASH token, not from the 0x0001 bit: a deletion is signaled by HASH equal to - with SIZE equal to 0, and a sender emitting a deletion MUST also set the 0x0001 bit as a metadata marker. A mtime-only or size-limited transfer uses the omitted-content flag and carries no payload bytes even though HASH and SIZE describe the sender's current file state. When SIZE is greater than zero and neither the deletion flag nor the omitted-content flag is set, the payload contains exactly SIZE content bytes. After exactly SIZE payload bytes, the next message byte, if any, is the first byte of the next card line. When content is omitted, there are no payload bytes and the next card line begins immediately after this card's terminating LF. A receiver MUST verify HASH against those bytes before storing the unversioned file. When content is omitted, the receiver may use the card to update metadata only when the unversioned-file status algorithm permits that update; it does not obtain file content from the card. A companion uvigot NAME MTIME HASH SIZE card is the announcement form, carrying the same state without a payload. A deleted unversioned file is announced or transferred with HASH equal to -. A uvgimme NAME card requests a named unversioned file. Only a receiver with unversioned-file write permission may land a uvfile change; lacking that permission is a protocol error for the uvfile receiver. Accepted unversioned-file changes clear the cached unversioned catalog hash. Hipp, et al. Expires 7 January 2027 [Page 32] Internet-Draft Fossil Sync Protocol July 2026 7.4. Delta Sources and Phantom Creation When a file or cfile card carries a DELTASRC argument that names an artifact the receiver does not currently hold, the receiver retains the delta payload against the named source and defers full reconstruction until the source arrives. The receiver MUST create a phantom record for the named DELTASRC (Section 9.3) and MUST NOT reject the card. When the source artifact is subsequently stored, the deferred reconstruction is completed at that time. Completion is recursive. Completing a deferred reconstruction stores the reconstructed artifact, and that artifact may itself be the DELTASRC of another retained delta; storing it therefore completes those deltas in turn. A receiver MUST run completion to a fixpoint over newly stored artifacts. For example, if a receiver has retained delta C against source A and delta A against source B before B arrives, then storing B completes A, and the storing of A completes C; neither C nor A may be left unreconstructed. 7.5. Private Content A private card (no arguments) MUST immediately precede the file or cfile card carrying private content. A private card that is not followed immediately by a content-bearing file or cfile card is a protocol error. Private content is transferred only when the send-private pragma has been accepted by the server and the receiving user holds the Private capability. A receiver MUST NOT store a private artifact unless the authenticated user holds that capability; a private artifact arriving without it is discarded without error. A private card preceding a uvfile card is not defined; private content suppression for unversioned files is governed by the pragma exchange in Section 10. The private-content boundary also constrains delta transmission. If the on-disk delta basis for an artifact is private but the artifact being sent is not, the sender MUST NOT send a delta that references that private basis to a peer that lacks private-content authorization; it MUST instead send full, non-delta content, so that the existence or identity of the private basis artifact is not leaked through a delta reference (Section 7.4). Authorization for private content applies in both directions, but a private announcement and private content are handled differently on the receive side. A private file or cfile card pushed to a server MUST be rejected as a not-authorized error unless the pushing peer holds the Private capability on the server. A private igot HASH 1 from a peer that Hipp, et al. Expires 7 January 2027 [Page 33] Internet-Draft Fossil Sync Protocol July 2026 lacks that capability MUST NOT be treated as an error. The receiver does not create a phantom for HASH; but if it already holds HASH as a phantom, it MUST mark that phantom private, so that it stops re- requesting content it will never be sent. The receiver records that the peer holds HASH and continues processing the message. Pulling private content MUST be preceded by a successful send-private pragma, which is itself gated on the client holding that capability. 7.6. SHA3-256 Peer-Version Gate A sender MUST NOT emit a file or cfile card whose HASH names a SHA3-256 artifact, nor a uvfile card whose HASH field carries a 64-character lowercase hexadecimal content hash, to a peer whose recorded version-pragma VERSION (Section 10.1) is less than the decimal integer 20000. The value 20000 corresponds to Fossil release 2.0. When this restriction prevents a transfer, the sender MUST emit an error card (Section 11) whose decoded text is Fossil version 2.0 or later required. The sender abandons that transfer for this round. No automatic substitution of a SHA1-named artifact or alternate hash form is performed. The client that receives this error card aborts the sync without retry, except during the first round of a clone where the error card is silently discarded (Section 11.1). This gate applies at three independent send sites: the file send path, the cfile send path, and the uvfile send path. A sender MUST apply the relevant gate at each site independently. This restriction does not define new card syntax. It is a precondition on emission, enforced before the card is written. 7.7. Hash-Policy Admission Hash-policy admission and content-integrity verification are distinct mechanisms that apply at different points in the receive path. They MUST NOT be conflated. Hash-policy admission is a gate applied to the HASH name of an inbound artifact, governed by the receiving repository's configured hash policy ([FossilArtifact], Section 7). Under the shun-sha1 policy, a receiver MUST reject any inbound artifact whose HASH is a 40-character (SHA1) name before storage. This gate applies to inbound file and cfile cards, including cfile cards received on the clone 3 SEQNO path. Hipp, et al. Expires 7 January 2027 [Page 34] Internet-Draft Fossil Sync Protocol July 2026 Content-integrity verification recomputes the artifact hash over the reconstructed artifact bytes — the full content named by HASH after applying any delta source, not the received wire payload — and confirms that the result matches HASH. This check applies pre- storage on non-clone file cards and at commit time on all paths. For cfile cards, pre-storage integrity verification does not apply in the transfer layer; commit-time verification still applies. When the receiving repository operates under the auto hash policy and successfully stores a SHA3-256-named artifact, the policy is permanently promoted to sha3 as a side effect of that storage operation. This promotion is persisted to the repository configuration immediately; it applies to all subsequent operations in the same and future sessions and is not reversible within a session ([FossilArtifact], Section 7). 8. Clone A clone is the procedure by which a client obtains a copy of a server's repository from an empty local repository. A current client uses the modern protocol-version-3 algorithm: it sends pragma client- version VERSION DATE TIME, then clone 3 SEQNO, then the normal trailing randomness comment in each clone artifact-transfer request for which SEQNO is positive. The first modern clone request uses SEQNO 1 and carries no login card (Section 8.3). 8.1. Clone Protocol Version The clone card carries a protocol version argument: clone VERSION SEQNO VERSION is a small decimal integer that selects the clone transfer path. This document defines the current interoperable clone path: Version 3: :: The client sends clone 3 SEQNO for a new clone. The server emits cfile cards (Section 7.2) for each artifact, in storage- sequence order. The response body uses the media type application/x- fossil-uncompressed. This is the clone path defined by this document. Any other VERSION value is outside the interoperable surface defined here. Hipp, et al. Expires 7 January 2027 [Page 35] Internet-Draft Fossil Sync Protocol July 2026 The clone protocol VERSION is orthogonal to the Fossil software release integer carried in version pragmas (Section 10.1). A client may send clone 3 while reporting any release integer; the value 20000 in the SHA3-256 send gate (Section 7.6) refers to the release integer, not to the clone version. 8.2. Sequence Numbers The SEQNO argument to the clone card is a blob-table row identifier in the server's repository. The server iterates row identifiers sequentially from the client-supplied SEQNO to the maximum identifier present, emitting one artifact per identifier. Gaps in the blob table are skipped silently; a client MUST NOT infer artifact count or total artifact size from the SEQNO range. The server replies with a clone_seqno NEXT card at the end of each modern clone artifact-transfer round: * When NEXT is greater than zero, the server has not yet exhausted its blob table. If the client also received at least one artifact in this round, if the total artifact count grew, or if this is the first clone round, the client continues under the Section 3.7 termination rule. A following modern clone request that continues artifact transfer includes pragma client-version and clone 3 NEXT. A positive NEXT value does not by itself require another round when no clone progress or other continuation condition holds. A conforming server upholds the matching liveness invariant: whenever it returns clone_seqno NEXT with NEXT greater than zero and blob RIDs at or above NEXT remain unsent, it MUST advance the sequence in that round — a positive NEXT is accompanied by content for at least one artifact whenever content remains to be sent. A client that receives a positive NEXT together with no new artifact and no other continuation condition has therefore reached a non- advancing peer and terminates the clone rather than looping. * When NEXT equals zero, the server has sent all artifacts up to the maximum row identifier. The client MUST NOT send another clone card after receiving clone_seqno 0. It may still issue cleanup rounds for configuration, unversioned files, private discovery, or phantom resolution if Section 3.7 requires them. A cleanup round is an ordinary request that omits the clone card and carries only the pragmas and the request cards (reqconfig, gimme, and unversioned-file cards) for the remaining work; a client with no remaining work terminates without issuing a further round. * A clone_seqno value less than zero is a fatal protocol error; the receiver MUST abort. Hipp, et al. Expires 7 January 2027 [Page 36] Internet-Draft Fossil Sync Protocol July 2026 The modern clone loop is therefore: SEQNO := 1 build first request: pragma client-version VERSION DATE TIME clone 3 1 # RANDOM no login card loop: send request; read reply accept cfile cards and other reply cards in order if clone_seqno NEXT was received: if NEXT < 0: abort SEQNO := NEXT evaluate Section 3.7 if continuing and SEQNO > 0: next request includes pragma client-version and clone 3 SEQNO else if continuing: next request includes pragma client-version but no clone card else: stop 8.3. First Clone Round During the first round of a current protocol-version-3 clone exchange, the client does not yet know the repository's project code and suppresses both body-login and cookie-login transport. The first request body begins with pragma client-version, then clone 3 1, and ends with the normal random comment. It contains no login card and therefore transmits neither a shared-secret value nor a plaintext- password substitute. The server processes that request using its baseline credentials and clone permission checks. A server that refuses the unauthenticated clone may still include push SERVERCODE PROJECTCODE before an error card, giving the client the project code needed to form later authenticated requests. A client MUST read the project code from a push or pull card it receives in a reply and record it as the peer's project code (Section 6.3); a clone client obtains its project code this way in the first clone round. For this reason a client silently discards error cards received during the first clone round; subsequent clone rounds process error cards normally. After the artifact-transfer phase completes (upon receiving clone_seqno 0), the client resolves any remaining phantoms using the normal phantom-resolution procedure of Section 3.3 and the termination rule of Section 3.7. Hipp, et al. Expires 7 January 2027 [Page 37] Internet-Draft Fossil Sync Protocol July 2026 8.4. Configuration During Clone The client defers all reqconfig cards until after clone round 0. Current clients also defer pragma uv-hash until after clone round 0 when unversioned sync is requested. This delay keeps the first clone exchange limited to version announcement, clone pagination, and project-code discovery; configuration and unversioned-file exchange then proceed through the normal reqconfig/config and unversioned-file mechanisms described in Sections 10.3 and 9.1. 9. Synchronisation Strategies 9.1. Push, Pull, and Sync A push request carries a push SERVERCODE PROJECTCODE card. A pull request carries a pull SERVERCODE PROJECTCODE card. A combined sync carries both. SERVERCODE is the client's own repository instance identifier (informational). PROJECTCODE is the identifier shared by all repositories of the same project. The server MUST refuse to synchronise when its stored project code does not match the received PROJECTCODE; such a mismatch is a fatal protocol error. A pull advances by the client creating phantoms from the server's igot announcements and requesting them with gimme cards. A push advances by the server creating phantoms from the client's igot announcements and requesting them with gimme cards; the client then sends the named content. A sync performs both directions in each round. The authoritative phantom and gimme rules are Section 3.3. 9.1.1. Unversioned-File Synchronisation An unversioned-file sync runs inside the same request/reply rounds as artifact sync, but it exchanges local unversioned-file state rather than artifacts. At session start, the client initializes the per- session unversioned send table with every local unversioned row whose hash is not null and sets the session's unversioned catalog-sent flag false. When unversioned sync is enabled and the exchange is eligible, the client sends pragma uv-hash HASH exactly once per session; during a clone this pragma is not sent on round 0. The HASH in pragma uv-hash is the unversioned catalog hash. It is computed as the SHA-1 [RFC3174] digest of the concatenation, in bytewise ascending name order, of one line per unversioned row whose hash is not null. Each line has the exact byte sequence NAME SP YYYY-MM-DD SP HH:MM:SS SP HASH LF Hipp, et al. Expires 7 January 2027 [Page 38] Internet-Draft Fossil Sync Protocol July 2026 where SP is ASCII 0x20 and LF is ASCII 0x0A. NAME is the row's fossilize-encoded file name bytes ([FossilArtifact], Section 4) as stored. YYYY-MM-DD SP HH:MM:SS is the 19-byte fixed-width UTC rendering of the row's Unix-epoch mtime — four-digit year, zero- padded month, day, hour, minute, and second components, an ASCII SP (0x20) between the date and the time, no fractional-second field, and no time-zone designator. HASH is the row's stored hash bytes as recorded for the row (lowercase hexadecimal, either SHA-1 or SHA3-256 per the row's stored form). There is no CR before the LF and no trailing whitespace inside the line. Bytewise ascending name order means the rows are ordered by unsigned bytewise comparison of the NAME field bytes (equivalent to SQL ORDER BY name under the default BINARY collation), not by any locale-dependent, case-insensitive, or Unicode collation. Deleted unversioned rows are excluded from the catalog hash; deletion is represented in inventories and transfers by HASH equal to -, not by adding a deleted row to the catalog hash input. If the server's catalog hash matches the client's value, the server sends no unversioned-file catalog for that request. If the hashes differ and the client has read permission, the server sends either pragma uv-push-ok when it will accept client unversioned uploads, or pragma uv-pull-only when the client may pull but may not upload unversioned files. It then sends uvigot NAME MTIME HASH SIZE entries describing its unversioned files. A server suppresses duplicate catalog emission only within a single request; a later request may receive another catalog only if the protocol path explicitly emits it again. Upon receiving pragma uv-push-ok, the client sets the session's unversioned upload-enabled flag. Upon receiving pragma uv-pull-only, the client sets the session's unversioned pull-only latch and MUST NOT upload unversioned files for the remainder of the session; this does not prevent pull-side uvgimme/uvfile transfer from server to client. For each uvigot NAME MTIME HASH SIZE, the client computes the unversioned status code against its local row for NAME as follows: 1. If no local row exists for NAME, status is 0. 2. Otherwise, let LOCAL-HASH be the local hash value, or - when the local row has a null hash. Let MTIME-CMP be -1, 0, or +1 according to whether the local mtime is less than, equal to, or greater than the received MTIME. Let HASH-CMP be the bytewise string comparison of LOCAL-HASH against HASH. Hipp, et al. Expires 7 January 2027 [Page 39] Internet-Draft Fossil Sync Protocol July 2026 3. If HASH-CMP is 0, status is 3 + MTIME-CMP: status 2 when the local copy is older, status 3 when the two states are identical, and status 4 when the local copy is newer. 4. Otherwise, if MTIME-CMP is less than 0, or MTIME-CMP is 0 and HASH-CMP is less than 0, status is 1. 5. Otherwise, status is 5. When mtimes are equal but hashes differ, the hash string is therefore the deterministic tie-breaker. In revert mode, the client maps status 4 to status 2 and status 5 to status 1 before applying the actions below. In dry-run mode, it suppresses local changes and reply messages. The status codes drive the client action normatively: * status 0 means NAME is absent locally and the remote state wins; when HASH is not -, the client queues uvgimme NAME and removes any local row that would be replaced before the incoming uvfile lands; * status 1 means the remote state wins over an existing local row; when HASH is not -, the client queues uvgimme NAME and deletes the local row before the replacement arrives, and when HASH is -, the client records the deletion locally by storing the received mtime and clearing hash, size, encoding, and content; * status 2 means the content hash matches but the remote mtime is newer, so the client updates local mtime only; * status 3 means local and remote state are identical; * status 4 means the content hash matches but the local mtime is newer, so the client retains NAME in the unversioned send table with mtimeOnly true if uploads are permitted; * status 5 means local content or deletion overrides the remote state, so the client retains or re-inserts NAME in the unversioned send table with mtimeOnly false if uploads are permitted. After those actions, the client updates the unversioned send table: statuses 0 through 3 remove NAME from the table; status 4 sets mtimeOnly true; status 5 sets mtimeOnly false. If the session is pull-only, statuses 4 and 5 also remove NAME from the table instead of keeping it queued for upload. Hipp, et al. Expires 7 January 2027 [Page 40] Internet-Draft Fossil Sync Protocol July 2026 A uvgimme NAME requests one named unversioned file. The receiver answers with uvfile NAME MTIME HASH SIZE FLAGS, or with uvigot NAME MTIME HASH SIZE again if the send-size limit prevents including the content in that response. The uvfile receiver rechecks the same unversioned-status function before landing the change and accepts it only when its write-permission and status checks allow the update (Section 7.3). The unversioned exchange advances across rounds as follows. The first eligible round sends uv-hash and receives either no unversioned response or a uv-push-ok/uv-pull-only pragma plus uvigot catalog entries. The next round sends any queued uvgimme cards and, when uploads are permitted, any queued uvfile uploads from the unversioned send table. A later round repeats that pattern for any repeated uvigot or received uvfile result. Unversioned-file continuation is therefore not open-ended: it depends on the Section 3.7(d) termination rule, which continues the session exactly while queued uploads remain or while a round that queued uvgimme either also received uvfile or ended before the session reached round 3. 9.2. Announcement and Request Cards An igot HASH card announces that the sender holds the artifact identified by HASH. An igot HASH 1 card announces that the artifact is private. A gimme HASH card requests the artifact identified by HASH. Creation of phantoms from igot, handling of private igot, gimme eligibility, missing-content behavior, and per-round duplicate suppression are specified in Section 3.3. There is no ordering constraint between igot and gimme cards within a single round. Private-artifact igot suppression applies when the sender's recorded peer date is before 2020-04-13: for such peers, a private artifact is omitted from the igot announcements entirely, rather than announced with the 1 flag. 9.2.1. Derived Branch, Tag, Leaf, Closed, and Current-Trunk Views The artifact inputs from which branch, ordinary tag, leaf, closed- leaf, and current-trunk views are derived are synchronized by transferring the artifacts that carry the corresponding artifact- format tag cards. The sync protocol MUST NOT treat an igot, gimme, file, or cfile card as an independent branch/tag operation, and it does not define separate wire cards for those views. The Artifact Format owns T card syntax and the tag-operation vocabulary ([FossilArtifact], Section 4.7.16); the derivation of repository tag- state views (branch, ordinary tag, leaf, closed-leaf, and current- trunk) from those crosslinked artifacts is specified in [FossilRepoState]. For current-trunk specifically, the protocol Hipp, et al. Expires 7 January 2027 [Page 41] Internet-Draft Fossil Sync Protocol July 2026 transports only the artifact inputs; each peer derives current-trunk locally, using its own main-branch setting as specified in [FossilRepoState]. Current-trunk is therefore not a pure wire- synchronized value: two synchronized peers can resolve different current-trunks when their main-branch settings differ. A receiving implementation may rely on branch, tag, leaf, closed, and current-trunk answers for the synchronized scope only after the artifacts that carry the relevant structural cards have been stored, required delta bases have been resolved or retained as pending phantoms, and repository crosslink/tag-state processing has run for the stored artifacts. Before that point, the wire stream only proves that the peer announced or sent artifact hashes; it does not prove a final open-leaf, leaf, closed-marker, or current-trunk view. If sync terminates with unresolved phantoms, derived views are complete only for the artifact closure actually available in the local repository. Later receipt of missing artifacts can change branch membership, symbolic tag visibility, closed-leaf state, leaf sets, and current-trunk answers through the artifact crosslink/tag- state machinery. This is not a separate sync error; it follows from the normal phantom termination rule in Section 3.7. 9.3. Phantom Records Phantom records are specified in Section 3.3. This section intentionally does not restate the creation, deletion, private- filtering, or dangling-delta rules. A strategy that needs missing artifact content uses igot to create phantoms and gimme to request eligible phantoms under that single rule surface. 9.4. Gimme Eligibility Filters gimme eligibility filters are specified in Section 3.3. Implementations MUST apply the per-round peer-lacks, shun, and private-content filters described there, and MUST NOT persist those per-round filters across rounds. 9.5. Loop Termination Loop termination follows the normative rule in Section 3.7, including the clone-specific continuation condition in Section 3.7(e) and the requirement that the client stop when none of those conditions holds. The server holds no per-session state and does not detect termination; it processes each request independently and signals no completion, as described in Section 3.7. Hipp, et al. Expires 7 January 2027 [Page 42] Internet-Draft Fossil Sync Protocol July 2026 10. Pragmas A pragma card has the form pragma NAME [ARGUMENTS]. Pragma cards are processed within the normal sync request/response body; no out-of- band negotiation is required. A pragma name the receiver does not recognise MUST be silently ignored; this is the forward-compatibility mechanism for the pragma namespace. Unknown pragma names differ from unknown card operators: an unknown card operator is a fatal protocol error (Section 11). Fourteen pragma names are defined. Nine are client-to-server: send- private, send-catalog, client-version, uv-hash, ci-lock, ci-unlock, client-url, req-links, and req-clusters. Five are server-to-client: server-version, uv-push-ok, uv-pull-only, ci-lock-fail, and avoid- delta-manifests. No pragma is version-gated at the receiver; all pragmas are forwarded to the ignore path when not recognised. 10.1. Version Negotiation The client MUST include the client-version pragma in every request body: pragma client-version VERSION DATE TIME VERSION is the Fossil release integer, encoded as MAJOR * 10000 + MINOR * 100 + PATCH. Fossil release 2.0 produces the value 20000; any release before 2.0 produces a value less than 20000. DATE is a decimal integer in YYYYMMDD form; TIME is a decimal integer in HHMMSS form. The DATE and TIME arguments are OPTIONAL; a client MAY send pragma client-version VERSION with VERSION only. Current clients send DATE and TIME on every round, including every clone round. Each received client-version pragma updates the server's recorded peer release integer and timestamp for the current request. Before a client-version pragma is received, the server treats the peer's VERSION as 0. The server MUST reply with pragma server-version VERSION DATE TIME if and only if the received client-version pragma included DATE and TIME (that is, the pragma had at least five tokens total). If the client sent client-version with VERSION only, the server MUST NOT emit server-version. Each received server-version pragma updates the client's recorded peer release integer and timestamp for the session. Before a server- version pragma is received, the client treats the peer's VERSION as its own release integer. Recorded peer VERSION values feed the SHA3-256 send gates in Section 7.6. Hipp, et al. Expires 7 January 2027 [Page 43] Internet-Draft Fossil Sync Protocol July 2026 10.2. Unversioned-File Pragmas pragma uv-hash HASH carries the client's catalog hash over its unversioned-file set. The catalog-hash computation and the resulting announce/request/send loop are specified in Section 9.1. A client sends uv-hash at most once per client sync session and does not send it on clone round 0. When the server's own catalog hash matches HASH, the server sends no unversioned-file response for that request. When the hashes differ and the client has read permission, the server replies with pragma uv-push-ok if the client may upload unversioned files, or pragma uv- pull-only if the client may pull but not upload them, followed by uvigot catalog entries. Server-side catalog emission is deduplicated only within the current request. pragma uv-push-ok is sent server-to-client to indicate the server accepts unversioned-file push. pragma uv-pull-only is sent server- to-client to indicate the server will not accept unversioned-file push; the client MUST treat the session as pull-only for unversioned- file uploads upon receiving this pragma. Pull-side unversioned-file transfer remains permitted when otherwise authorized. 10.3. Configuration Exchange Repository configuration settings are exchanged through reqconfig and config cards. This exchange is a library component invoked from within the normal sync round loop; there is no pre-round capability advertisement or separate configuration handshake. A client sends reqconfig NAME to request a configuration group, where NAME MUST begin with /. The server silently ignores reqconfig cards when the requesting user lacks Read permission; no error card is emitted for an unauthorized request. During clone, clients defer reqconfig until after clone round 0 (Section 8.4). The server replies with config GROUPNAME SIZE cards followed by SIZE content bytes. The GROUPNAME field encodes the configuration group as follows: * Scalar repository settings travel as config /config SIZE cards regardless of which group the client requested. The /config name is an encoding marker, not a group identifier. The SIZE bytes of content have the form: MTIME SP QUOTED-NAME SP value SP QUOTED-VALUE Hipp, et al. Expires 7 January 2027 [Page 44] Internet-Draft Fossil Sync Protocol July 2026 where MTIME is the modification time as a decimal epoch-second count, QUOTED-NAME is the setting name in Fossil quote encoding, the literal token value appears verbatim, and QUOTED-VALUE is the setting value in Fossil quote encoding. Fossil quote encoding encloses the token in single-quote (') characters and doubles any single-quote it contains, using SQL-style single-quoted string- literal escaping; a reader removes the surrounding quotes and undoubles internal quotes to recover the raw name or value. A client receiving /config cards MUST track which groups it requested by its own internal state; it cannot determine the source group from the card name alone. * Table-type configuration entries (covering the shun table, user table, report-format table, concealed table, and subscriber table) travel as config /GROUPNAME SIZE cards, where GROUPNAME identifies the table. This document specifies the config /GROUPNAME SIZE card framing and the request/response flow for these groups, but the internal byte serialization of each table-type payload is *out of scope for this document*; the scalar /config payload defined above is fully specified, whereas a client that must interoperate on the specific table groups requires that additional row-encoding definition. A single newline byte follows the content payload of every config card before the next card begins; receivers MUST consume this trailing newline. Configuration also flows in the reverse direction. A client that holds the Admin capability on the server MAY push a scalar setting with a config NAME SIZE card followed by SIZE content bytes and the trailing newline, using the same /config payload form specified above. The server MUST require the Admin capability for a pushed config card: a client without it receives an error card with the text not authorized to push configuration, and the card is not applied. A pushed config card whose SIZE is negative is a fatal protocol error, and the server aborts the transaction. A well-formed config NAME SIZE card from an authorized client is applied to the server's configuration; the server consumes the SIZE payload bytes and the single trailing newline. Only the scalar /config form is pushed by this mechanism; table-type configuration groups are not. The transfer-hook configuration group covers exactly four server-side hook settings. These settings travel as scalar config /config cards. Their content is executed server-side only and is not part of the interoperability surface of this document. Hipp, et al. Expires 7 January 2027 [Page 45] Internet-Draft Fossil Sync Protocol July 2026 10.4. Commit-Lock Pragmas pragma ci-lock HASH CLIENT-ID requests an exclusive commit lock on the check-in identified by HASH. CLIENT-ID is an opaque per-checkout identifier maintained by the client. The server stores the lock; if the lock is already held by a different client, the server replies with pragma ci-lock-fail LOGIN MTIME, where LOGIN is the current lock holder and MTIME is the lock acquisition time expressed as a non- negative decimal integer count of seconds since the Unix epoch (1970-01-01T00:00:00 UTC), with no sign, no fractional-second field, no time-zone designator, no thousands separator, and no leading zeros (a single 0 represents zero). On receipt of pragma ci-lock-fail, a client MUST record the fault against the pending commit — associating LOGIN and MTIME with the check-in that pragma ci-lock requested — and MUST continue processing the remainder of the round; the pragma is not by itself a wire-layer abort of the sync exchange. A receiver MAY treat a syntactically invalid MTIME (in particular, a negative or non-integer MTIME) as a fatal protocol error under Section 11.1 and terminate the round; a non-negative MTIME MUST NOT be treated as a wire-layer error regardless of its magnitude. The recorded fault constrains the client's later commit attempt, not its handling of the current round. When the recorded fault is present, a subsequent commit against the same check-in MUST NOT be completed if it would create a fork against the locked leaf, unless the user has explicitly requested an operation that removes the fork- avoidance guard (for example, committing on a named branch, marking the commit private, forcing the commit, allowing a fork, or overriding the lock). A client that offers such user-directed overrides MUST surface the recorded fault to the user before applying the override. Nothing in this section forbids further pull-side traffic or later pragma ci-lock attempts in the same session; whether the client retries is a policy decision left to the implementation. pragma ci-unlock CLIENT-ID releases a previously acquired commit lock. Clients with a known client identifier send ci-unlock in later rounds when no commit lock is pending for the current exchange. 10.5. Private-Content and Discovery Pragmas pragma send-private signals that the client wishes to synchronise private artifacts. The server enables private-content transfer for this session only when the requesting user holds the Private (x) capability. If the user lacks that capability, the server emits an error card with the text not authorized to sync private content rather than silently ignoring the pragma; this is a non-reset error Hipp, et al. Expires 7 January 2027 [Page 46] Internet-Draft Fossil Sync Protocol July 2026 site (Section 11.1). A client performing private sync repeats send- private in each private-sync round; repeated authorized occurrences are idempotent. pragma send-catalog requests that the server emit igot cards for every artifact it holds. This is the recovery path for a full resynchronisation. pragma req-clusters requests that the server emit igot cards for its cluster artifacts. pragma req-links requests link-graph data. pragma client-url URL communicates the client's canonical URL to the server. Current clients emit client-url and req-links, when applicable, once before the round loop rather than repeating them each round. pragma avoid-delta-manifests is sent server-to-client to indicate the server prefers receiving full-content manifests rather than delta manifests. 11. Error Handling 11.1. Error Card An error card is a fatal protocol signal except for the first round of a clone: error TEXT TEXT is the error message encoded using the fossilize character- escaping scheme ([FossilArtifact], Section 4), with spaces encoded as \s. A receiver MUST apply defossilize decoding before displaying or logging the text. Upon receiving an error card outside the first clone round, the client MUST stop processing the response body and MUST terminate the sync loop. The client does not retry the failed transfer using an alternative encoding or hash algorithm. Before emitting an error card, the server's behavior depends on the error origin. At fatal protocol-error sites — wrong project, authorization failures, duplicate login card, and unknown card operator — the server discards any prior partial output before emitting the error card. Note that discarding prior output does not guarantee an error-only response body: the unauthorized-clone site, for example, emits a push card after the reset and before the error card. At the SHA3-256 peer-version gate (Section 7.6) and the unauthorized send-private and private card sites, the server appends the error card directly to the already-built response; other response Hipp, et al. Expires 7 January 2027 [Page 47] Internet-Draft Fossil Sync Protocol July 2026 cards (such as clone_seqno, push, and the closing timestamp comment) may therefore appear in the same response body alongside the error card. In all cases the HTTP response status is 200; the error is signalled entirely within the message body. The exception to immediate client termination is the first round of a clone exchange (Section 8.3): error cards received during that round are silently discarded. Current clients send no login card in that first clone round, and a server may need to return push SERVERCODE PROJECTCODE before the client can form later authenticated requests. The exact decoded text Fossil version 2.0 or later required. is the error message emitted when the SHA3-256 peer-version gate fires (Section 7.6). 11.2. Message Card A message card is a non-fatal advisory from the server: message TEXT TEXT is encoded identically to an error card. Upon receiving a message card, both the server and the client continue processing; the session is not terminated. When the decoded text of a message card matches the pattern pull only *, the client MUST silently clear any push intent and treat the session as pull-only for this round, without displaying the message to the user. In all other cases the client MAY display the message to the user. 12. Security Considerations The Fossil login and shared-secret mechanism does not transmit the user password or the shared secret in any form; the shared secret is computed locally on each side (Section 6.3) and never carried on the wire. Standard HTTP authentication headers (Authorization: Basic, Proxy-Authorization) that may appear at the transport layer are outside the scope of this mechanism (Section 4). Authentication nonces are derived from the message payload; each freshly generated request produces a distinct nonce (Section 6.2, Section 5.3). Full authentication-flow security properties and transport requirements are described in Section 12.1. Implementations MUST NOT store a shared secret or its equivalent in a cookie, URI, or any session state that is visible to intermediaries. Hipp, et al. Expires 7 January 2027 [Page 48] Internet-Draft Fossil Sync Protocol July 2026 A sender MUST NOT transmit a SHA3-256 artifact (a 64-character lowercase hexadecimal hash) to a peer whose reported release version is less than 20000. When this condition applies, the sender MUST emit an error card (Section 11); no automatic downgrade to SHA1 naming occurs. Implementations MUST NOT silently truncate a SHA3-256 artifact identifier or re-identify it as a SHA1 artifact in any protocol path. See [FossilArtifact] §7 for hash-policy state definitions. 12.1. Credential Replay The Fossil login mechanism transmits neither the user password nor the shared secret derived from it; the shared secret is derived locally from the password (Section 6.3), and neither is carried on the wire. HTTP authentication headers (Authorization: Basic, Proxy- Authorization), when present, are transport-layer credentials outside the scope of this mechanism (Section 4). The NONCE in a login card is the SHA-1 digest of all message-body bytes that follow the card (Section 6.2). Because each request appends an implementation- generated random comment line (Section 5.3), independently generated rounds produce distinct nonces. The server maintains no nonce cache and applies no timestamp freshness check, however; a complete request — body bytes and login card, or in cookie-login mode (Section 6.5) the Cookie: x-f-l-c= header together with the body — can be replayed byte-for-byte and will pass server verification. 12.2. Private-Content Exposure and Protected Transport Confidentiality, server authentication, and protection against replay of credential-bearing traffic MUST be provided by the transport layer. A deployment that carries authenticated sync traffic, private-content transfers (send-private pragma, Section 10), or cookie-login credentials (Cookie: x-f-l-c, Section 6.5) MUST use HTTPS, SSH, or an equivalent protected transport that provides confidentiality, integrity, and server authentication. Plaintext HTTP does not provide these properties and SHOULD NOT be used in production for such traffic. An intermediary that can read a private-content sync session can read the private artifact payloads it transfers. A shared secret MUST NOT be stored in a cookie, URI, or session state visible to intermediaries. Hipp, et al. Expires 7 January 2027 [Page 49] Internet-Draft Fossil Sync Protocol July 2026 12.3. Line-Length Bounds and Resource Exhaustion Card and comment lines are terminated by LF, while several card types carry byte-counted payloads after that LF. A receiver that scans for LF without a bound can therefore be forced to buffer or scan arbitrarily large attacker-made lines before it reaches the payload framing decision. To limit this exposure, conforming receivers MUST enforce the Section 5 maximum of 65535 bytes for each card line or comment line, measured through the terminating LF and excluding any following byte-counted payload. Exceeding that bound is a fatal protocol error. The receiver MUST abort the exchange before attempting to interpret the over-length line as a card or to consume any subsequent payload bytes. This bound applies only to line framing; it does not cap the SIZE or CSIZE payloads of file, cfile, uvfile, or config cards, which remain governed by their own declared byte counts and by implementation storage policy. 12.4. SHA3-256 Downgrade Prevention SHA3-256-named artifacts are refused to peers with a release integer less than 20000 via explicit error card emission; no silent downgrade of the artifact identifier to SHA1 is performed. Implementations MUST NOT silently truncate or re-identify a SHA3-256 artifact as SHA1 on any protocol path. See [FossilArtifact], Section 7 for the hash- policy definitions that govern this gate. 13. IANA Considerations This document requests registration of the following media types in the application media type registry. No port number or service-name registration is required for this protocol. application/x-fossil Type name: application Subtype name: x-fossil Required parameters: none Optional parameters: none Encoding considerations: binary; the body is a zlib-compressed Fossil sync message and can contain arbitrary octets after decompression. Security considerations: see Section 12. Fossil sync exchanges Hipp, et al. Expires 7 January 2027 [Page 50] Internet-Draft Fossil Sync Protocol July 2026 can carry authentication material, private artifacts, and repository content. Interoperability considerations: this media type is used for ordinary Fossil sync requests and for non-clone replies as specified in Section 4.1. Published specification: this document Applications that use this media type: Fossil sync clients, servers, and compatible repository replication tools Fragment identifier considerations: none Additional information: * Deprecated alias names for this type: none * Magic number(s): none * File extension(s): none * Macintosh file type code(s): none Person and email address to contact for further information: Dan Shearer, dan@shearer.org (mailto:dan@shearer.org) Intended usage: COMMON Restrictions on usage: none Author: D. Richard Hipp, Stephan Beal, Dan Shearer Change controller: IETF application/x-fossil-debug Type name: application Subtype name: x-fossil-debug Required parameters: none Optional parameters: none Encoding considerations: binary; the body is an uncompressed Fossil sync message and can contain arbitrary octets in card payloads. Security considerations: see Section 12. This diagnostic form exposes the sync message body without outer zlib compression and MUST NOT be used on an unprotected production transport. Interoperability considerations: this media type is wire- Hipp, et al. Expires 7 January 2027 [Page 51] Internet-Draft Fossil Sync Protocol July 2026 compatible with application/x-fossil after decompression, but it is intended only for diagnostic debugging and testing as described in Section 4.1. Published specification: this document Applications that use this media type: Fossil debugging, test harnesses, and compatible debugging tools Fragment identifier considerations: none Additional information: * Deprecated alias names for this type: none * Magic number(s): none * File extension(s): none * Macintosh file type code(s): none Person and email address to contact for further information: Dan Shearer, dan@shearer.org (mailto:dan@shearer.org) Intended usage: LIMITED USE Restrictions on usage: debugging and testing only Author: D. Richard Hipp, Stephan Beal, Dan Shearer Change controller: IETF application/x-fossil-uncompressed Type name: application Subtype name: x-fossil-uncompressed Required parameters: none Optional parameters: none Encoding considerations: binary; the outer message body is not zlib- compressed and clone replies can contain arbitrary octets in cfile payloads. Security considerations: see Section 12. Clone replies can carry repository content and authentication-adjacent state exactly as ordinary sync replies do. Interoperability considerations: this media type is used only for clone replies negotiating protocol version 3, as specified in Section 4.1 and Section 8. Published specification: this document Hipp, et al. Expires 7 January 2027 [Page 52] Internet-Draft Fossil Sync Protocol July 2026 Applications that use this media type: Fossil repository-bootstrap servers, clients, and compatible repository bootstrap tools Fragment identifier considerations: none Additional information: * Deprecated alias names for this type: none * Magic number(s): none * File extension(s): none * Macintosh file type code(s): none Person and email address to contact for further information: Dan Shearer, dan@shearer.org (mailto:dan@shearer.org) Intended usage: COMMON Restrictions on usage: reply media type only; not used for requests Author: D. Richard Hipp, Stephan Beal, Dan Shearer Change controller: IETF 14. References 14.1. Normative References [FossilArtifact] Hipp, D. R., Ed., Beal, S., and D. Shearer, "The Fossil Distributed Version Control System: Artifact Format", Work in Progress, Internet-Draft, draft-fossil-artifact-format- 00, 2026, . [FossilDelta] Hipp, D. R., Ed., Beal, S., and D. Shearer, "The Fossil Delta Format", Work in Progress, Internet-Draft, draft- fossil-delta-format-00, 2026, . [FossilRepoState] Hipp, D. R., Ed., Beal, S., and D. Shearer, "The Fossil Distributed Version Control System: Repository State and Check-in Resolution", Work in Progress, Internet-Draft, draft-fossil-repo-state-00, 2026, . Hipp, et al. Expires 7 January 2027 [Page 53] Internet-Draft Fossil Sync Protocol July 2026 [RFC1950] Deutsch, P. and J. Gailly, "ZLIB Compressed Data Format Specification version 3.3", RFC 1950, DOI 10.17487/RFC1950, May 1996, . [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . 14.2. Informative References [GSET] Shapiro, M., Preguica, N., Baquero, C., and M. Zawirski, "A comprehensive study of Convergent and Commutative Replicated Data Types", INRIA RR-7506, January 2011, . [RFC9051] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message Access Protocol (IMAP) - Version 4rev2", RFC 9051, DOI 10.17487/RFC9051, August 2021, . [RFC9293] Eddy, W., Ed., "Transmission Control Protocol (TCP)", STD 7, RFC 9293, DOI 10.17487/RFC9293, August 2022, . Hipp, et al. Expires 7 January 2027 [Page 54] Internet-Draft Fossil Sync Protocol July 2026 Appendix A. Examples This appendix presents concrete sync exchanges and worked protocol instances. Request Content-Type may be application/x-fossil-debug (uncompressed body); server clone replies may use application/x- fossil-uncompressed; surrounding prose identifies the applicable Content-Type where it matters. Section 4.1 defines the protocol minimum as HTTP/1.1; Appendix A preserves the concrete request lines used in these worked instances, including HTTP/1.0 where shown. Two fence types appear in this appendix. A fossil-sync fence contains the decompressed sync-message body only — card lines, comment lines, and any printable payload bytes included in the example, with no HTTP framing. An http fence contains a full HTTP message: request or response start line, headers, a blank line, and then the decompressed body; http fences are used where HTTP headers carry protocol-relevant information (for example, the Cookie: x-f-l-c= cookie-login header or the Content-Type selection). Non-printable binary payloads and any printable content deliberately omitted from a fence are described in editorial notes immediately adjacent to that fence; no placeholder appears inside a fence. Examples are illustrative; in any conflict with the protocol definition in Sections 3 through 11, the normative prose takes precedence. A.1. Basic Push/Pull Convergence (Two Rounds) Two local repositories share project-code aa87ea41b0bb05ba528f7a3bdba700d7e23d6318. Before the sync each side held one checkin the other lacked; the common ancestor was shared by clone. *Round 1 request* (client → server; Content-Type: application/x- fossil-debug, 471 bytes body): pragma client-version 22800 20260311 113146 pull da3e69ab0655a7dd2aba2520b2d3302a97c85787 aa87ea41b0bb05ba528f7a3bdba700d7e23d6318 push da3e69ab0655a7dd2aba2520b2d3302a97c85787 aa87ea41b0bb05ba528f7a3bdba700d7e23d6318 igot 8e0933ed1ef9aa0051d185c8123f0b9ac79865e4b70098b877543fca0092c259 igot b1c1b05fea4f52bd90b15fdffd13f5c91dce6505f498eeb79b4952c2ea8d4d15 igot c5b2e0ecb779a7616b32553d973bc9c4ae5a07569a2cee18001386da6bd9ae57 # F2A895EF75B47B7157664A7FEAC978EFFFDB01C4 *Round 1 reply* (server → client; Content-Type: application/x-fossil- debug, 367 bytes body): Hipp, et al. Expires 7 January 2027 [Page 55] Internet-Draft Fossil Sync Protocol July 2026 pragma server-version 22800 20260311 113146 gimme 8e0933ed1ef9aa0051d185c8123f0b9ac79865e4b70098b877543fca0092c259 gimme b1c1b05fea4f52bd90b15fdffd13f5c91dce6505f498eeb79b4952c2ea8d4d15 igot 4361252d0f450879dcd2e0b6a42b95ffe8a41d8e948130253ae8eefa7f4b79ea igot f5116517775075ea483901021282ba97eebe5a2b993a47eb78198adc10efe128 # timestamp 2026-07-02T18:31:13 errors 0 The server does not gimme c5b2e0ecb779… because it already holds that artifact. After Round 1 the client holds two new phantoms (4361252d0f… and f5116517…) created from the server's igot cards. *Round 2 request* (client → server; 1058 bytes body): pragma client-version 22800 20260311 113146 pull da3e69ab0655a7dd2aba2520b2d3302a97c85787 aa87ea41b0bb05ba528f7a3bdba700d7e23d6318 push da3e69ab0655a7dd2aba2520b2d3302a97c85787 aa87ea41b0bb05ba528f7a3bdba700d7e23d6318 file 8e0933ed1ef9aa0051d185c8123f0b9ac79865e4b70098b877543fca0092c259 272 C client:\sadd\salpha.txt D 2026-07-02T18:30:46.860 F alpha.txt b1c1b05fea4f52bd90b15fdffd13f5c91dce6505f498eeb79b4952c2ea8d4d15 P c5b2e0ecb779a7616b32553d973bc9c4ae5a07569a2cee18001386da6bd9ae57 R 6b3e7488d36fc39ea8093fdea87c3641 U drh Z ed00cdc67449c3949587aa83b3fd8a67 file b1c1b05fea4f52bd90b15fdffd13f5c91dce6505f498eeb79b4952c2ea8d4d15 26 alpha content from client gimme 4361252d0f450879dcd2e0b6a42b95ffe8a41d8e948130253ae8eefa7f4b79ea gimme f5116517775075ea483901021282ba97eebe5a2b993a47eb78198adc10efe128 igot 8e0933ed1ef9aa0051d185c8123f0b9ac79865e4b70098b877543fca0092c259 igot b1c1b05fea4f52bd90b15fdffd13f5c91dce6505f498eeb79b4952c2ea8d4d15 igot c5b2e0ecb779a7616b32553d973bc9c4ae5a07569a2cee18001386da6bd9ae57 # F155AB07186D7F394649AB08DB88BD4179159D07 The 272-byte payload of the first file card is the Fossil checkin manifest shown above (seven lines of Fossil manifest notation, totalling 272 bytes including terminating LFs). The \s sequences in the C card are the Fossil fossilize encoding for spaces. The 26-byte payload of the second file card is the text alpha content from client followed by a single LF. Both file cards use the full-content (two- argument) form file HASH SIZE. *Round 2 reply* (server → client; 533 bytes body): Hipp, et al. Expires 7 January 2027 [Page 56] Internet-Draft Fossil Sync Protocol July 2026 pragma server-version 22800 20260311 113146 file 4361252d0f450879dcd2e0b6a42b95ffe8a41d8e948130253ae8eefa7f4b79ea 270 C server:\sadd\sbeta.txt D 2026-07-02T18:30:46.907 F beta.txt f5116517775075ea483901021282ba97eebe5a2b993a47eb78198adc10efe128 P c5b2e0ecb779a7616b32553d973bc9c4ae5a07569a2cee18001386da6bd9ae57 R 5aa7ac70dd267efe64fe354554a33895 U drh Z 7330b90458172595afd5c246c62c096d file f5116517775075ea483901021282ba97eebe5a2b993a47eb78198adc10efe128 31 beta content added server-side # timestamp 2026-07-02T18:31:13 errors 0 The 270-byte payload of the first file card is the Fossil checkin manifest for the beta commit. The 31-byte payload of the second file card is the text beta content added server-side followed by a single LF. *Termination* No Round 3 is issued. Round 2 delivered content, but the server's reply contained no igot cards, so no new phantoms were created. Neither continuation condition of Section 3.7 holds prospectively; the client stops. *Notes* 1. *No login card* appears in this example because the server accepts unauthenticated push/pull. The login card form is documented in Section 6. 2. *Delta-form file cards* (file HASH DELTASRC SIZE) do not appear: the two commits are fully independent with no common file content enabling a delta. The delta form is defined in Section 7. 3. *application/x-fossil-debug* is used throughout these two rounds; the production compressed media type is application/x-fossil. 4. *Version integer 22800* encodes Fossil 2.28.00 as 2×10000 + 28×100 + 0 = 22800. A.2. SHA3 Version Gate (Error Card) This example uses pragma client-version 19999 to fall below the SHA3 support threshold of 20000. The server has one blob with a 64-character SHA3-256 hash; the gate fires when the server attempts to emit that artifact. Hipp, et al. Expires 7 January 2027 [Page 57] Internet-Draft Fossil Sync Protocol July 2026 *Request* (Content-Type: application/x-fossil-debug, Content-Length: 38): pragma client-version 19999 clone 3 1 *Response* (HTTP 200, Content-Type: application/x-fossil- uncompressed, Content-Length: 191): error Fossil\sversion\s2.0\sor\slater\srequired. clone_seqno 0 push 34302acad64fe2397bd907704dec457899e2f9a3 c85e3efddf993e86e8325d08672ea94bdba6c2c4 # timestamp 2026-07-02T18:26:49 errors 0 Decoded error text: Fossil version 2.0 or later required. The response contains three protocol cards (error, clone_seqno 0, push) plus a closing # timestamp comment line (not a protocol card). The SHA3 peer-version gate is a per-artifact abandonment site: the server does not reset the response before emitting the error, so prior partial output is preserved and the remaining cards follow. clone_seqno 0 signals that the server's blob-table RID range is exhausted; no artifact-transfer cards were emitted in this particular response. No SHA1 retry or silent downgrade occurs. A clone client receiving this response as the reply to its first clone round would silently discard the error card rather than aborting: first-round clone errors are ignored because the project code needed for correct authentication is returned in the push card in the same response (Section 11.1). This example therefore shows the server's three-card response and the absence of any SHA1 fallback; the client-side discard is a consequence of Section 11.1. A.3. Private Content Suppression Server: three public blobs (RIDs 1–3) and two private blobs (RIDs 4–5) in the private(rid) table. User anonymous has caps og (no Private/x); user privuser has caps ogx. Full 64-character SHA3-256 hashes shown. Scenarios 1–3 isolate public/private announcement and authorization behavior; Scenario 4 shows the authenticated private- pull path. *Scenario 1 — Natural pull (anonymous): private artifacts absent* Request (131-byte body): pragma client-version 20028 20260702 183000 pull cccccccccccccccccccccccccccccccccccccccc ea2e766b68008b6c3b3ca547df136ded07c7f921 Hipp, et al. Expires 7 January 2027 [Page 58] Internet-Draft Fossil Sync Protocol July 2026 Response (295-byte body): pragma server-version 22800 20260311 113146 igot 23813573dea5ec687052a067866751f481e58ef4c478939ac601587a43f50b35 igot 2c215398c6ea4e3c0994d41918f632d5208d6a24da3ac894c9d9d167a711f30b igot ed76b084599a372a5a17232f0bb67211145c0bde6b5a5ff542813d60fa07d3dc # timestamp 2026-07-02T18:33:01 errors 0 Three public igot cards; private RIDs 4–5 are completely absent from the wire. *Scenario 2 — Crafted gimme for private hash: date-gated igot HASH 1* Request (202-byte body): pragma client-version 20028 20260702 183000 pull cccccccccccccccccccccccccccccccccccccccc ea2e766b68008b6c3b3ca547df136ded07c7f921 gimme da4b6b0ea2b060ff6bf29c16a3b10be05afc9c1a75d605a45cf7267ea3e74091 Response (367-byte body): pragma server-version 22800 20260311 113146 igot da4b6b0ea2b060ff6bf29c16a3b10be05afc9c1a75d605a45cf7267ea3e74091 1 igot 23813573dea5ec687052a067866751f481e58ef4c478939ac601587a43f50b35 igot 2c215398c6ea4e3c0994d41918f632d5208d6a24da3ac894c9d9d167a711f30b igot ed76b084599a372a5a17232f0bb67211145c0bde6b5a5ff542813d60fa07d3dc # timestamp 2026-07-02T18:33:01 errors 0 igot HASH 1 — private-flag form — signals the artifact exists and is private; no file card follows because private-content sync is not enabled. The peer's recorded date (20260702) ≥ 20200413 satisfies the date gate. *Scenario 3 — Crafted server-path probe: unauthorized send-private (anonymous, no x capability)* _This scenario isolates the server's authorization check. The card ordering shown — pragma client-version before pragma send-private — is not the normative client order; Section 3.2 places pragma send- private before pragma client-version on the initial round of a private-content sync._ Request (151-byte body): pragma client-version 20028 20260702 183000 pragma send-private pull cccccccccccccccccccccccccccccccccccccccc ea2e766b68008b6c3b3ca547df136ded07c7f921 Hipp, et al. Expires 7 January 2027 [Page 59] Internet-Draft Fossil Sync Protocol July 2026 Response (345-byte body): pragma server-version 22800 20260311 113146 error not\sauthorized\sto\ssync\sprivate\scontent igot 23813573dea5ec687052a067866751f481e58ef4c478939ac601587a43f50b35 igot 2c215398c6ea4e3c0994d41918f632d5208d6a24da3ac894c9d9d167a711f30b igot ed76b084599a372a5a17232f0bb67211145c0bde6b5a5ff542813d60fa07d3dc # timestamp 2026-07-02T18:33:01 errors 0 Decoded: not authorized to sync private content. An unauthorized send-private pragma emits an explicit error card. This is a non- reset path: public igot cards follow the error card in the same response. *Scenario 4 — Authorized private pull (privuser, x capability)* Round 1 request (455 bytes total): POST / HTTP/1.0 Host: 127.0.0.1:9872 User-Agent: Fossil/2.28 (2026-03-11 11:31:46 [52445a27f1]) Content-Type: application/x-fossil-debug Content-Length: 291 login privuser ee71329ef84fb77b428c6f626ad0103a426e0652 c3ee0be781c9ebcfc6e24756cbb75e6319ca255b pragma send-private pragma client-version 22800 20260311 113146 pull 3921d47b51aad4027faac6467b4a87b4e7951c64 ea2e766b68008b6c3b3ca547df136ded07c7f921 # 7258235C6A6B727E5C0F6E2E2576D36A234E63A3 login USER NONCE SIGNATURE — body-embedded login card. Round 1 reply (content-length 439 bytes): pragma server-version 22800 20260311 113146 igot 23813573dea5ec687052a067866751f481e58ef4c478939ac601587a43f50b35 igot 2c215398c6ea4e3c0994d41918f632d5208d6a24da3ac894c9d9d167a711f30b igot ed76b084599a372a5a17232f0bb67211145c0bde6b5a5ff542813d60fa07d3dc igot 393953a9803595823fb560ddbe333767840a5ad89748a12fc2cd00f533c6df8a 1 igot da4b6b0ea2b060ff6bf29c16a3b10be05afc9c1a75d605a45cf7267ea3e74091 1 # timestamp 2026-07-02T18:34:48 errors 0 Private artifacts announced as igot HASH 1. Round 2 request (614 bytes total): Hipp, et al. Expires 7 January 2027 [Page 60] Internet-Draft Fossil Sync Protocol July 2026 POST / HTTP/1.0 Host: 127.0.0.1:9872 User-Agent: Fossil/2.28 (2026-03-11 11:31:46 [52445a27f1]) Cookie: x-f-l-c=login+privuser+653828a8fc753c1685501de457c104f0b20938c9+bec32fbc6a2589413ee6d1f47a4ae0098dafcad2 Content-Type: application/x-fossil-debug Content-Length: 336 pragma client-version 22800 20260311 113146 pragma send-private pull 3921d47b51aad4027faac6467b4a87b4e7951c64 ea2e766b68008b6c3b3ca547df136ded07c7f921 gimme 393953a9803595823fb560ddbe333767840a5ad89748a12fc2cd00f533c6df8a gimme da4b6b0ea2b060ff6bf29c16a3b10be05afc9c1a75d605a45cf7267ea3e74091 # 4D85B916A821F5198416D9F01D4F75F45714F45C Cookie: x-f-l-c=… replaces the body login card from Round 2 onward. Round 2 reply (content-length 1033 bytes): pragma server-version 22800 20260311 113146 private file 393953a9803595823fb560ddbe333767840a5ad89748a12fc2cd00f533c6df8a 49 Private content — must not reach x-less peers. The 49-byte payload ends with a single LF. In the binary stream it is immediately followed by the next private card with no separator. private file da4b6b0ea2b060ff6bf29c16a3b10be05afc9c1a75d605a45cf7267ea3e74091 ed76b084599a372a5a17232f0bb67211145c0bde6b5a5ff542813d60fa07d3dc 317 317 bytes of binary delta payload follow; payload contains embedded LF bytes and MUST be consumed by byte count, not newline scanning. igot 23813573dea5ec687052a067866751f481e58ef4c478939ac601587a43f50b35 igot 2c215398c6ea4e3c0994d41918f632d5208d6a24da3ac894c9d9d167a711f30b igot ed76b084599a372a5a17232f0bb67211145c0bde6b5a5ff542813d60fa07d3dc igot 393953a9803595823fb560ddbe333767840a5ad89748a12fc2cd00f533c6df8a 1 igot da4b6b0ea2b060ff6bf29c16a3b10be05afc9c1a75d605a45cf7267ea3e74091 1 # timestamp 2026-07-02T18:34:48 errors 0 Each private artifact is immediately preceded by a private card. The second round completes the exchange: the client requests the two announced private artifacts and receives both. A.4. Comment Lines and Clock-Skew Timestamp This example uses the same two-round push/pull exchange as A.1. The # sending-clusters / # end-of-clusters comment pair was not triggered in this exchange; no cluster transmission occurred. Hipp, et al. Expires 7 January 2027 [Page 61] Internet-Draft Fossil Sync Protocol July 2026 *Client comment lines* (random nonce): Round 1 request, final line: # F2A895EF75B47B7157664A7FEAC978EFFFDB01C4 Round 2 request, final line: # F155AB07186D7F394649AB08DB88BD4179159D07 Both lines begin with # (0x23) followed by a 40-character uppercase hex nonce; they are not dispatched as protocol cards and the server skips them silently. A different nonce appears in each round. *Server timestamp comment lines*: Round 1 reply, final line: # timestamp 2026-07-02T18:31:13 errors 0 Round 2 reply, final line: # timestamp 2026-07-02T18:31:13 errors 0 Both match the # timestamp DATETIME errors N subform. The client reads DATETIME to compute clock skew; N = 0 indicates no protocol errors were signalled in that round. A.5. Authentication Example This non-normative example reproduces a full login signature end to end. All digests are SHA-1 [RFC3174]; each value recomputes from the inputs shown, so an implementer can check an implementation against it. The authentication formulas are specified in Section 6. Inputs: Hipp, et al. Expires 7 January 2027 [Page 62] Internet-Draft Fossil Sync Protocol July 2026 +====================+==========================================+ | Field | Value | +====================+==========================================+ | login name (USER) | alice | +--------------------+------------------------------------------+ | plaintext password | secret-passphrase | +--------------------+------------------------------------------+ | project code | c1b2a3d4e5f60718293a4b5c6d7e8f9012345678 | +--------------------+------------------------------------------+ | NONCE-covered body | the 26 ASCII bytes example-request-body- | | | bytes | +--------------------+------------------------------------------+ Table 6 Derivation: NONCE = SHA1("example-request-body-bytes") = 5dfa03bd8645938b4e312a4fcdad5ebe6d4d4840 shared-secret = SHA1("c1b2a3d4e5f60718293a4b5c6d7e8f9012345678" "/alice/secret-passphrase") = d7a235115bf97d126c42140196c4fc6087312353 SIGNATURE = SHA1( NONCE-hex || shared-secret-hex ) ; 80 bytes = e3dba1c99442823b76ae64a8afca940e0327f9f8 These populate the login card's USER, NONCE, and SIGNATURE fields (Section 6); NONCE and SIGNATURE are the 40-character lowercase hexadecimal strings shown. Appendix B. ABNF This appendix gives the canonical line grammar for every sync body- card operator named in Sections 3 through 11, plus the cookie-login HTTP header. ABNF notation follows [RFC5234]. Byte-counted payload lengths and the required equality between a card's declared SIZE or CSIZE field and the following octet count are normative rules of Sections 5, 7, and 10; the productions below name where those payload octets occur, but the arithmetic constraint itself is enforced by prose rather than ABNF. ; § B.1 Core tokens LF = %x0A SP = %x20 ALPHA-LC = %x61-7A DIGIT = %x30-39 HEXDIG-LC = DIGIT / %x61-66 HEXDIG-UC = DIGIT / %x41-46 Hipp, et al. Expires 7 January 2027 [Page 63] Internet-Draft Fossil Sync Protocol July 2026 HEXDIG-CI = DIGIT / %x41-46 / %x61-66 sha1-hash = 40HEXDIG-LC sha3-hash = 64HEXDIG-LC artifact-hash = sha1-hash / sha3-hash decimal = 1*DIGIT fossil-token = 1*( ALPHA-LC / DIGIT / %x5F ) fossilized = 1*( %x21-7E ) ; printable ASCII, no SP; ; \s \t \n \r \f \v \0 \\ per ; [FossilArtifact] §4 config-name = "/" 1*( ALPHA-LC / DIGIT / "-" / "_" ) pragma-name = 1*( ALPHA-LC / DIGIT / "-" ) client-id = fossilized non-lf-byte = %x01-09 / %x0B-FF qchar = %x20-26 / %x28-7E / %x80-FF fossil-quoted = %x27 *( qchar / %x27 %x27 ) %x27 ts-token = 1*( %x21-7E / %x80-FF ) uv-hash-field = artifact-hash / "-" payload-octets = *OCTET ; § B.2 Message-body structure sync-message = *( sync-element ) sync-element = bare-card / file-transfer / cfile-transfer / uvfile-transfer / config-transfer / comment-line bare-card = cookie-card / login-card / push-card / pull-card / clone-card / private-card / igot-card / gimme-card / uvigot-card / uvgimme-card / pragma-card / reqconfig-card / clone-seqno-card / error-card / message-card file-transfer = file-card payload-octets cfile-transfer = cfile-card payload-octets uvfile-transfer = uvfile-card [ payload-octets ] config-transfer = config-card payload-octets LF ; payload-octets is consumed by the exact SIZE or CSIZE value declared ; in the immediately preceding card line. ; § B.3 Comment lines (§5.3) comment-line = timestamp-comment / sending-clusters-comment / end-of-clusters-comment / nonce-comment / generic-comment timestamp-comment = "# timestamp" SP ts-token SP "errors" SP decimal LF sending-clusters-comment = "# sending-clusters" LF end-of-clusters-comment = "# end-of-clusters" LF nonce-comment = "#" SP 40HEXDIG-UC LF Hipp, et al. Expires 7 January 2027 [Page 64] Internet-Draft Fossil Sync Protocol July 2026 generic-comment = "#" *non-lf-byte LF ; § B.4 Transport and authentication (§§4, 6) cookie-card = "cookie" SP fossilized LF login-card = "login" SP user SP nonce SP signature LF user = fossilized nonce = sha1-hash signature = sha1-hash cookie-login-header = "Cookie: x-f-l-c=" url-login-value url-login-value = "login+" pct-user "+" nonce "+" signature pct-user = 1*( unreserved / pct-encoded ) unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" pct-encoded = "%" HEXDIG-CI HEXDIG-CI ; § B.5 Operation and announcement cards (§§3, 8, 9) push-card = "push" SP servercode SP projectcode LF pull-card = "pull" SP servercode SP projectcode LF servercode = fossil-token projectcode = fossil-token clone-card = "clone" SP decimal SP decimal LF clone-seqno-card = "clone_seqno" SP decimal LF private-card = "private" LF igot-card = "igot" SP artifact-hash LF / "igot" SP artifact-hash SP "1" LF gimme-card = "gimme" SP artifact-hash LF uvigot-card = "uvigot" SP fossilized SP decimal SP uv-hash-field SP decimal LF uvgimme-card = "uvgimme" SP fossilized LF ; § B.6 Content-transfer cards (§7) file-card = "file" SP artifact-hash SP decimal LF / "file" SP artifact-hash SP artifact-hash SP decimal LF cfile-card = "cfile" SP artifact-hash SP decimal SP decimal LF / "cfile" SP artifact-hash SP artifact-hash SP decimal SP decimal LF uvfile-card = "uvfile" SP fossilized SP decimal SP uv-hash-field SP decimal SP decimal LF ; § B.7 Configuration and pragma cards (§10) reqconfig-card = "reqconfig" SP config-name LF config-card = "config" SP config-name SP decimal LF Hipp, et al. Expires 7 January 2027 [Page 65] Internet-Draft Fossil Sync Protocol July 2026 config-scalar-payload = decimal SP fossil-quoted SP "value" SP fossil-quoted ; payload form used by config /config pragma-card = client-version-pragma / server-version-pragma / uv-hash-pragma / uv-push-ok-pragma / uv-pull-only-pragma / ci-lock-pragma / ci-lock-fail-pragma / ci-unlock-pragma / send-private-pragma / send-catalog-pragma / client-url-pragma / req-links-pragma / req-clusters-pragma / avoid-delta-manifests-pragma / extension-pragma client-version-pragma = "pragma" SP "client-version" SP decimal [ SP 8DIGIT SP 6DIGIT ] LF server-version-pragma = "pragma" SP "server-version" SP decimal SP 8DIGIT SP 6DIGIT LF uv-hash-pragma = "pragma" SP "uv-hash" SP artifact-hash LF uv-push-ok-pragma = "pragma" SP "uv-push-ok" LF uv-pull-only-pragma = "pragma" SP "uv-pull-only" LF ci-lock-pragma = "pragma" SP "ci-lock" SP artifact-hash SP client-id LF ci-lock-fail-pragma = "pragma" SP "ci-lock-fail" SP fossilized SP fossilized LF ci-unlock-pragma = "pragma" SP "ci-unlock" SP client-id LF send-private-pragma = "pragma" SP "send-private" LF send-catalog-pragma = "pragma" SP "send-catalog" LF client-url-pragma = "pragma" SP "client-url" SP fossilized LF req-links-pragma = "pragma" SP "req-links" LF req-clusters-pragma = "pragma" SP "req-clusters" LF avoid-delta-manifests-pragma = "pragma" SP "avoid-delta-manifests" LF extension-pragma = "pragma" SP pragma-name *( SP fossilized ) LF ; § B.8 Error signalling (§11) error-card = "error" SP fossilized LF message-card = "message" SP fossilized LF Hipp, et al. Expires 7 January 2027 [Page 66] Internet-Draft Fossil Sync Protocol July 2026 Appendix C. Anomalies The following statements found in existing descriptions of the protocol do not match the behaviour specified in the body of this document. The body is definitive; the divergent statements are recorded here for reference. "Unknown message" response. :: Some descriptions refer to an "Unknown message" reply for an unrecognized card. No such wire text exists. An unrecognized card is answered with an error bad command: card followed by the offending line, and a malformed content card is answered with an error malformed CARD line card (Section 5.2, Section 11.1). Cumulative multi-login permissions. :: An earlier server behaviour accumulated capability grants across multiple login cards presented in a single request. That behaviour has been withdrawn: a second login card in a request is a fatal protocol error that aborts the exchange, and capability grants from a login card are additive to the baseline within a single verification only, never cumulative across multiple cards (Section 6.1, Section 6.4). Authors' Addresses D. Richard Hipp (editor) Fossil Stephan Beal libfossil Dan Shearer Email: dan@shearer.org URI: https://shearer.org Hipp, et al. Expires 7 January 2027 [Page 67]