cambria

This document explains how Fossil’s repository schema underpins the version control core, with emphasis on document/version artifacts and their relationships. It maps key tables and indexes in schema.sql to the responsibilities in (source paths under src/):

• src/checkin.c — commit operations
• src/checkout.c — checkout/update operations
• src/merge.c — three-way merge logic
• src/delta.c — delta compression algorithm
• src/manifest.c — manifest parsing and generation
• src/rebuild.c — repository rebuild operations
• src/sync.c — push/pull/sync operations
• src/xfer.c — network transfer protocol

Core Data Model

• blob(rid, rcvid, size, uuid, content)

  • Stores all artifacts: manifests, file contents, wiki/forum posts, tickets, etc.
  • uuid is the immutable artifact hash; rid is the internal row id.
  • rcvid ties the artifact to a received bundle (remote sync session).

• delta(rid, srcid)

  • Records that artifact rid is stored as a delta against base srcid.
  • Used for storage optimization; logical content still addressed by blob.uuid.

• filename(fnid, name)

  • Interns path names; referenced by mlink to avoid duplication.

• mlink(mid, fid, pmid, pid, fnid, pfnid, mperm, isaux)

  • Per-file linkage within a manifest (mid).
  • Maps file artifact (fid) and its parent (pid) under a filename (fnid).
  • Encodes file-level perms and aux flags and parent filename (pfnid) for renames.

• plink(pid, cid, isprim, mtime, baseid)

  • Parent/child relationships between check-in manifests (pid → cid).
  • isprim marks primary parent (for merges, cherry-picks); baseid can reference a baseline.

• leaf(rid)

  • Tracks leaf check-ins for branch growth and tip resolution.

• tag(tagid, tagname) and tagxref(tagid, tagtype, srcid, origid, value, mtime, rid)

  • Branch names, closes, propagating tags, user-defined tags. rid usually refers to a check-in.

• event(type, mtime, objid, tagid, uid, ...)

  • Timeline events: check-ins, wiki edits, ticket changes.

• artifact view (rid, rcvid, size, atype, srcid, hash, content)

  • Joins blob with delta to present artifacts with delta ancestry.

• Support tables

  • rcvfrom (received bundles for sync)
  • private (private artifacts)
  • phantom, orphan, unclustered, unsent (stateful maintenance during sync/rebuild)
  • cherrypick(parentid, childid, isExclude) (cherry-pick inclusion/exclusion)
  • attachment, backlink (cross-object references)

Module Linkage

checkin.c (Commit Operations)

Cross-refs: src/checkin.c, src/manifest.c, src/tag.c, src/event.c.

• Inserts a new manifest into blob (content is manifest text; uuid is its hash).
• Updates plink to connect the new check-in (cid) to its parent(s) (pid).
• Populates mlink rows per file entry:
  • mid = manifest rid, fid = file content rid, fnid = path from filename.
  • pid/pfnid capture parent file linkage for diffs/renames.
• Marks leaf for the new tip and updates tags via tagxref (e.g., branch, closed).
• Emits event(type='ci', objid=rid, mtime, ...) for timeline.

checkout.c (Checkout/Update Operations)

Cross-refs: src/checkout.c, src/vfile.c, src/content.c.

• Resolves target rid via branch/tag selectors using tag/tagxref and plink ancestry.
• Enumerates mlink for the target manifest to materialize the working tree:
  • For each fid, retrieves blob.content (following delta.srcid if needed).
  • Applies renames via pfnid and permissions mperm.
• Computes update plans by diffing mlink of current vs target manifests.

merge.c (Three-Way Merge Logic)

Cross-refs: src/merge.c, src/diff.c, src/plink.c (logical graph via plink), src/filename.c (path intern).

• Determines merge bases using plink graph (common ancestor selection).
• Per file path (fnid), uses mlink triplets (base, ours, theirs) to locate fid artifacts.
• Obtains file contents from blob (resolves deltas via delta lineage when fetching).
• Writes merged results as new blob entries (for committing) and updates mlink on commit.
• Records merge parents in plink (isprim may indicate primary parent) and optionally cherrypick for selective inclusion/exclusion.

delta.c (Delta Compression Algorithm)

Cross-refs: src/delta.c, src/blob.c, src/content.c.

• Storage layer uses deltas for blob.content:
  • When saving content as a delta against srcid, inserts row in delta and stores patch in blob.content.
  • Retrieval reconstructs fulltext using artifact view to locate base srcid.
• The VC core modules call delta routines indirectly via blob I/O helpers.

manifest.c (Manifest Parsing and Generation)

Cross-refs: src/manifest.c, src/mlink.c (derived linkage), src/tag.c.

• Produces and parses manifest artifacts in blob.content (M-records, F-lines, etc.).
• F lines map to mlink rows: file hash → fid, filename → fnid, perms → mperm.
• P lines establish parents → plink(pid, cid).
• R rename directives can be represented via pfnid linkage in mlink.
• Tags (T lines) become tag/tagxref entries, including branch name.

rebuild.c (Repository Rebuild Operations)

Cross-refs: src/rebuild.c, src/tag.c, src/event.c, src/leaf.c.

• Recomputes derived tables from canonical artifacts in blob:
  • Regenerates plink, mlink, leaf, tagxref, event, indexes.
• Clears and repopulates maintenance tables: phantom, orphan, unclustered.
• Validates delta integrity and may rebase deltas for optimal chains.

sync.c (Push/Pull/Sync Operations)

Cross-refs: src/sync.c, src/xfer.c, src/shun.c, src/clone.c.

• Tracks received bundles in rcvfrom(rcvid, uid, mtime, nonce, ipaddr).
• Inserts remote artifacts into blob and notes rcvid for provenance.
• Temporarily marks unknown references as phantom and queues unsent for outgoing.
• Updates graph (plink) and per-file links (mlink) after manifests arrive.
• Applies shun rules to ignore certain uuids and private for non-syncing artifacts.

xfer.c (Network Transfer Protocol)

Cross-refs: src/xfer.c, src/sync.c, src/http_*.c.

• Encodes/decodes artifact exchanges (content by blob.uuid).
• Handles delta transmission and application, populating delta(rid, srcid) when storing.
• Coordinates sequence numbers and bundle integrity, feeding rcvfrom and unsent.

Document Versioning Flow

Step 1: Authoring and Check-in

• New file contents stored in blob (optionally as deltas in delta).
• Manifest stored in blob and parsed into mlink (F-lines) and plink (P-lines).
• Cross-refs: src/checkin.c, src/manifest.c.

Step 2: Branching and Tags

• tag/tagxref attach branch names and metadata to the manifest rid.
• leaf marks branch tips; event records timeline entries.
• Cross-refs: src/tag.c, src/leaf.c, src/event.c.

Step 3: Checkout and Update

• Target manifest resolved via tagxref/plink; files enumerated via mlink.
• Contents materialized from blob (reconstructing via delta when needed).
• Cross-refs: src/checkout.c, src/content.c, src/delta.c.

Step 4: Merge

• Base selection via plink; file triplets via mlink per fnid.
• Merged outputs prepared for checkin.c to write as new blob/manifest, linking via mlink & plink.
• Cross-refs: src/merge.c, src/diff.c, src/checkin.c.

Step 5: Sync

• Artifacts exchanged by xfer.c; recorded via blob.rcvid, rcvfrom.
• Graph/linkage derived by sync.c; maintenance tables reconcile missing refs.
• Cross-refs: src/xfer.c, src/sync.c, src/configure.c (sync settings).

Step 6: Rebuild

• rebuild.c re-derives all secondary tables from blob contents if indexes are lost/corrupt.
• Cross-refs: src/rebuild.c.

Indexes and Performance

• delta_i1(srcid) accelerates delta chain resolution.
• mlink_i* indexes speed per-manifest and per-file lookups for checkout/merge.
• plink_i2(cid,pid) accelerates ancestry scans for merge base and history.
• event_i1(mtime) optimizes timeline queries.
• tagxref_i1(tagid, mtime) improves tag history and branch tip resolution.
  • Cross-refs: src/db.c (query helpers), src/graph.c (timeline visualization).

Special States and Maintenance

• phantom: referenced but not yet present artifacts during sync.
• orphan(baseline): artifacts lacking expected baselines or parents.
• unclustered: artifacts outside cluster boundaries, pending consolidation.
• unsent: local artifacts queued for transmission.
• private: artifacts excluded from sync.
• cherrypick: explicit include/exclude relationships between check-ins.
  • Cross-refs: src/sync.c, src/xfer.c, src/rebuild.c.

Traceability Map (Quick Reference)

• Schema → Module
  • blob → src/checkin.c, src/content.c, src/xfer.c
  • delta → src/delta.c, src/content.c
  • filename → src/checkout.c, src/merge.c
  • mlink → src/manifest.c, src/checkout.c, src/merge.c
  • plink → src/checkin.c, src/merge.c, src/rebuild.c
  • leaf → src/checkin.c, src/rebuild.c
  • tag/tagxref → src/tag.c, src/branch.c
  • event → src/event.c
  • rcvfrom, unsent, phantom → src/sync.c, src/xfer.c

Where function-level detail is needed, see module-specific comments and COMMAND:/WEBPAGE: indices generated by tools/mkindex.c.

Summary

Fossil’s VC core treats blob artifacts and manifest semantics as the single source of truth. Derived tables such as mlink, plink, leaf, and tagxref provide efficient views optimized for commit, checkout, merge, and sync operations. The schema’s indexes and maintenance tables ensure performance and robustness across local edits, merges, and distributed synchronization.