Skip to content
go-libfossil Artifact [ae301b23ca]
Login

Artifact [ae301b23ca]

Check-ins Using Download Hex Wiki

Artifact ae301b23caa725efd241de1f5c3863d894c0f52c8e4316fd6221e059575d2e32:

# Erratum — draft-fossil-artifact-format-00 §4.1.2

| | |
|---|---|
| **Document** | `draft-fossil-artifact-format-00` |
| **Section** | 4.1.2 — Sterilization |
| **Type** | Technical (three factual divergences from the reference implementation) |
| **Status** | Draft — not yet applied |
| **Reported** | 2026-08-08 |
| **Submitter** | Dan Mestas |
| **Found via** | zit `import-git` mirror classifier, against a 36,383-commit SQLite Git mirror |

## 1. Summary

§4.1.2 describes Fossil's sterilization marker — the comment line a writer adds
to make content deliberately unparseable as a structural artifact. Three of its
statements are wrong against the reference implementation: the marker's
**position**, the **gate that rejects** the sterilized bytes, and the marker's
**literal text**. The section is additionally self-contradictory: it says the
marker is the first line, then says the signed form places it before the
trailing signature block, which is after the cards.

The direction of the error is the dangerous one. An implementer following
§4.1.2 as written builds a sterilizer that does not match Fossil's, and the
mismatch is invisible until a sterilized artifact reaches another repository —
where it surfaces as a foreign check-in rather than as a parse failure.

## 2. Location

§4.1.2 (Sterilization), the paragraph beginning *"This subsection is
informative."* Current text:

> To render content deliberately unparseable as a structural artifact, a writer
> inserts a comment line beginning with # (of the form `# Remove this line to
> create a well-formed Fossil artifact.`) **as the first line**, which causes
> **the line-1 gate of Section 4.1 to fail**. For PGP- or SSH-signed content,
> the marker line is instead spliced in immediately before the signature block…

## 3. The defect

Verified against Fossil 2.28 (`52445a27f1`) by source reading and by running the
code.

### 3.1 Position — the marker is appended, never inserted first

`sterilize_manifest()` (`src/manifest.c:2238`) builds its output with
`blob_appendf`. The marker lands **after the final card**, not before the first.
Observed on a real checkout:

```
U tester
Z 633267631377a908d4e09def80ef9fd5
# Remove this line to create a well-formed Fossil manifest.
```

### 3.2 Failure mechanism — residue, not the line-1 gate

Because the marker is trailing, it never reaches the line-1 gate. It is rejected
by §4.1's rule that any bytes left unconsumed after the card loop MUST cause
rejection — equivalently §4.2.1's residual-bytes clause. A reader that
implemented only the stated line-1 mechanism would **accept** a sterilized
artifact, which is the precise outcome sterilization exists to prevent.

### 3.3 Literal text — the quoted string is never emitted

The format string (`src/manifest.c:2242`) is:

```c
"# Remove this line to create a well-formed Fossil %s.\n"
```

`%s` is `manifest` for `CFTYPE_MANIFEST` and `control artifact` for every other
type. The draft's `…well-formed Fossil artifact.` is emitted by no code path.

### 3.4 Internal contradiction

"as the first line" and "spliced in immediately before the signature block"
cannot both hold: the signature block is trailing, so a marker before it is
after the cards. The signed description is the accurate one, and it
generalizes — the unsigned case is the same insertion point with an empty
signature.

## 4. Impact

Two mechanisms, in opposite directions.

**A reader built to §4.1.2 under-rejects.** It looks for a line-1 marker,
finds none, and parses a sterilized artifact as a structural artifact.

**A writer built to §4.1.2 diverges byte-for-byte from Fossil**, so its output
is not the artifact any Fossil-derived name refers to.

This is not theoretical, and the consumer-side cost is measurable. zit's Git
import proves a mirror's `manifest`/`manifest.uuid` pair by stripping the
sterilizer and checking the result against the name the mirror recorded. Written
to the trailing-only reading of the implementation — which is correct for the
unsigned case — it failed for every PGP-clearsigned check-in, because there the
marker sits mid-blob, immediately before `-----BEGIN PGP SIGNATURE-----`. On a
36,383-commit SQLite mirror:

| Proof outcome | Count |
|---|---|
| Proven by trailing strip | 35,307 |
| Proven **only** once the marker is spliced from before the signature block | 1,076 |
| Unproven | 0 |

All 1,076 date from 2009–2011, when SQLite's `clearsign` setting was on. Each
had its mirror metadata retained permanently — the observable symptom of a
correct implementation built against an incorrect description of where the
marker goes.

## 5. Correction applied

Replace the first paragraph of §4.1.2 with text that states the position once,
in the general (signature-aware) form, names the correct rejection mechanism,
and quotes the two literals the implementation actually emits:

```diff
-   This subsection is informative.  To render content deliberately
-   unparseable as a structural artifact, a writer inserts a comment line
-   beginning with # (of the form # Remove this line to create a well-
-   formed Fossil artifact.) as the first line, which causes the line-1
-   gate of Section 4.1 to fail.  For PGP- or SSH-signed content, the
-   marker line is instead spliced in immediately before the signature
-   block, with the boundary recomputed by the same wrapper-detection
-   logic of Section 4.1.1, so the signature remains trailing.
+   This subsection is informative.  To render content deliberately
+   unparseable as a structural artifact, a writer appends a comment line
+   beginning with # after the final card, and before the signature block
+   when the content is PGP- or SSH-signed, so that a signature remains
+   trailing; the boundary is located by the same wrapper-detection logic
+   of Section 4.1.1.  The marker reads # Remove this line to create a
+   well-formed Fossil manifest. for a check-in and # Remove this line to
+   create a well-formed Fossil control artifact. for any other type.
+   Because the marker follows the cards, it is Section 4.1's rule that
+   unconsumed bytes after the card loop MUST cause rejection —
+   equivalently the residual-bytes clause of Section 4.2.1 — that rejects
+   the artifact, not the line-1 gate.
```

## 6. Rationale

- **One statement of position.** The contradiction exists because position is
  asserted twice. Stating it once, in the form that covers both cases, removes
  it.
- **The mechanism is load-bearing.** Naming the wrong gate produces a reader
  that fails open on exactly the input sterilization targets. This is the most
  consequential of the three defects.
- **The literals are quoted because they are compared.** Consumers match the
  marker to strip it; a consumer matching the draft's string matches nothing
  Fossil writes.
- **Informative, not normative.** §4.1.2 does not impose requirements — the
  correction changes only what the section describes, not what any reader or
  writer is required to do.

### Note on the producer side

Fossil's own use of `sterilize_manifest()` narrowed in `722c248d53` (shipped
2.18, 2022-02-23), which removed it from `tar.c` and `zip.c`, so archive exports
are no longer sterilized while checkouts and Git export still are. That is a
producer-policy change and needs no draft text; it is recorded here because it
makes §4.1.2's accuracy matter more, not less — consumers can no longer assume
content arriving from a Fossil-derived tarball has been sterilized at all.

---

*Prepared against the frozen final `draft-fossil-artifact-format-00`. The zit
reference implementation already emits and strips the marker at the position
described in §5; this erratum records the divergence so the draft can settle it.*

## 7. Resolution verification

- All three defects verified twice: by reading Fossil 2.28 source
  (`src/manifest.c:2238`, `:2242`) and by observing a live checkout's `manifest`
  file and a published SQLite mirror's blobs.
- The 1,076/35,307/0 split is reproducible: export `sqlite.fossil` with
  `fossil git export`, then for each commit compare `manifest` stripped both
  ways against `manifest.uuid`.
- Clean-room effect: an implementer no longer has to discover, from a foreign
  check-in appearing in an unrelated repository, that the marker is trailing
  rather than leading and that the text varies by artifact type.