Documentation

The lineage protocol

A semantic layer above Git. Git keeps every commit; this records what a capability is, where it came from, and why you should believe it.

How this specification is compiled

These pages are not a frozen Markdown dump. They import the same TypeScript vocabularies, Zod schemas and KEYLIT fixtures the registry uses. If an evidence code, an accession prefix or a mutation state changes, the specification changes with it.

That is the documentation pipeline: live modules, rendered as the protocol. Diagrams are Mermaid; schemas are JSON Schema Draft 2020-12 emitted by z.toJSONSchema.

What this is not

It is not a code host, a replacement for Git, or another SBOM. CycloneDX already models component pedigree — ancestors, descendants, variants, commits, patches. Recording that software has ancestry is not, on its own, a contribution.

What sits above that layer is the contribution: semantic capability genes, alleles, a genotype/phenotype separation, evidence-backed annotations, agent lineage, and controlled inheritance between living descendants.

Architecture

Every screen reads through the query layer. Fixtures feed it today; api.codeancestry.com can replace the bodies later without touching a component.

Drawing diagram…

Fixtures validate through Zod, then the query layer feeds every surface.

Diagram source

flowchart LR
  Fixtures["KEYLIT fixtures"]
  Zod["Zod schemas"]
  Query["Query layer"]
  Fixtures --> Zod --> Query
  Query --> Hero["Helix hero"]
  Query --> Tree["Family CodeTree"]
  Query --> Browser["Genome browser"]
  Query --> Records["Accession records"]
  Query -.->|"same signature, later"| API["api.codeancestry.com"]

The core objects

A gene is a stable semantic capability — MIDI input handling, adaptive lesson scoring. It is deliberately not a file or a function: one capability may span many files, and one utility file may serve ten capabilities.

An allele is one implementation of that capability. Two distant descendants can carry functionally equivalent alleles even though their source, language and version numbers differ — which is why allele is a better concept than version.

A mutation is one capability changing, carrying the measurement that justified it. A genome is the versioned composition of a project at a point in its history.

Accessions, edges, evidence — live counts

The protocol currently names 9 accession prefixes, 7 typed edge kinds, and a 7-step propagation sequence that a mutation cannot skip. The pages below expand each of those from the modules that define them.

CAPROJ · CAGENOME · CAGENE · CAALLELE · CAMUT · CAAGENT · CAEV · CAPHENO · CAMEM
DERIVED_FROM · RECOMBINED_FROM · MUTATED_FROM · TRANSFERRED_FROM · ADOPTED_FROM · REJECTED_FROM · PROPOSED_TO
Discover → Describe → Attest → Sandbox → Test → Evaluate → Decide

Nothing propagates on its own

A descendant can offer an improvement to its ancestors. It can never install one. Every arrow that carries a change ends at a decision made by the receiving project, under rules that project wrote.

Connected does not mean synchronised. That single rule is what stops a lineage network from becoming a worm.