# Fossil Corpus Brief

## Purpose

This brief defines the Fossil-specific source corpus for the RFC suite. It names the authoritative and informative source surfaces, the observed-byte corpus, and the section-to-source routing that the original pack required.

Neutral workflow mechanics belong in `core/`. This file names the Fossil materials those mechanics operate on.

## Authoritative sources

### Fossil implementation and observed bytes

Treat the following as primary authority for suite content:

- `src/manifest.c` — structural artifact parser, card validation, card ordering, delta-manifest file-set reconstruction, and the stored-artifact inputs consumed by RepoState.
- `src/tag.c` — repository crosslink processing, tag-state updates, branch propagation, and leaf/open-leaf maintenance for stored structural artifacts.
- `src/name.c` — symbolic-name resolution and repository-derived check-in selection such as `current-trunk`.
- `src/delta.c`, `src/deltacmd.c`, `src/deltafunc.c` — delta encoding, apply logic, and related behavior.
- `src/xfer.c` — sync card handling, clone behavior, content transfer, authentication, pragma handling, and the protocol boundary where peers admit artifacts before deriving repository state locally.
- `src/http.c` — transport/request-target behavior for sync POST handling.
- `src/sha1.c`, `src/sha3.c`, `src/md5.c` — hash and checksum computation.
- `fossil.fossil` — the supplied repository, treated as observed byte ground truth.

### libfossil

Treat libfossil as an additional authoritative source for artifact/card understanding and validation tooling, with one boundary:

- its `src/` and associated documentation are authoritative for parsing and artifact understanding,
- it is less complete than Fossil for networking behavior,
- it may corroborate the stored-artifact shapes that feed RepoState, but it does not override Fossil's own repository-state derivation,
- use it to corroborate artifact and validation behavior, not to override Fossil sync behavior.

## Informative sources

These sources help orientation and terminology but can lag the code:

- `www/fileformat.wiki`
- `www/sync.wiki`
- `www/delta_format.wiki`
- `www/delta_encoder_algorithm.wiki`
- `www/hashes.md`
- `www/hashpolicy.wiki`
- `www/blockchain.md`

When implementation and documentation disagree, the suite states implemented behavior and records the divergence as a Fossil-specific anomaly or reviewer note.

## Claim basis

For this project, every normative claim should resolve to one of these Fossil-specific evidence forms:

- a named implementation file and function,
- the observed byte content of an artifact in `fossil.fossil`, confirmed by direct inspection or tool output.

Training knowledge, prior prose, and lagging wiki text may help locate source, but they are not claim bases.

## Observed-byte and tool surfaces

The original pack relied on these Fossil/libfossil inspection surfaces:

- `fossil artifact` for raw artifact inspection by hash or symbolic name,
- `fossil sql` for mapping rowid to UUID before artifact lookup,
- `f-aparse` for single-artifact parsing and R-card confirmation,
- `f-parseparty -R REPO -q` for repository-wide libfossil parsing,
- `f-acat` for raw artifact byte extraction.

Project-specific cautions:

- Whole-repository parsers are chatty; redirect or use quiet modes when gathering evidence.
- Fossil/libfossil tools that can read stdin should be given explicit input so they do not block waiting for data.
- Do not reimplement parser, delta, or hashing logic when the Fossil or libfossil entry points already expose the behavior.

## Section-to-source routing

| Suite topic | Read here first |
| --- | --- |
| Artifact naming | `src/sha1.c`, `src/sha3.c`, plus hashed-byte handling in `src/manifest.c` |
| Artifact card syntax | card lexer and W-card framing in `src/manifest.c` |
| Structural artifact types | per-type card validation and ordering in `src/manifest.c` |
| Z-card and R-card checksums | checksum handling in `src/manifest.c` and `src/md5.c` |
| Hash policy | `src/sha1.c`, `src/sha3.c`, and hash-policy selection in `src/manifest.c` |
| Check-in DAG inputs | manifest parent-card parsing in `src/manifest.c`, then repository-state linkage/crosslink handling in `src/tag.c` |
| Crosslink and tag propagation | repository crosslink procedure and propagated tag-state maintenance in `src/tag.c` |
| Branch membership, leaves, and closed markers | derived branch/leaf state maintenance in `src/tag.c` |
| Symbolic-name resolution and `current-trunk` | repository name-resolution and branch-selection logic in `src/name.c`, corroborated by tag-state inputs from `src/tag.c` |
| Delta segments | copy/literal encoding in `src/delta.c` |
| Delta application | apply logic and absent-source behavior in `src/delta.c`, `src/deltacmd.c`, `src/deltafunc.c` |
| Sync transport | HTTP transport and sync dispatch in `src/http.c` and `src/xfer.c` |
| Sync cards/auth/clone/round logic | card vocabulary and protocol flow in `src/xfer.c` |
| Derived repository views after sync | artifact admission in `src/xfer.c`, then local repository-state derivation in `src/tag.c` and `src/name.c` |
| Artifact anomaly audit | `manifest_parse` and `manifest_is_well_formed` in `src/manifest.c` |

## Fossil-specific evidence shape

For this project, the smallest useful citation units are:

- `file:function` for implementation behavior,
- artifact hash or repository rowid/UUID for observed bytes,
- a concrete tool invocation plus verdict when behavior must be demonstrated,
- a specific wiki/document path when a lagging informative source is being contrasted with code.

## Exclusions

This pack intentionally does **not** carry:

- environment bootstrap commands,
- machine-specific build recipes,
- neutral validation-stage policy,
- harness-specific command wrappers.

Those belong in repo-wide core or toolchain materials.