Canonical Lineage

Definition

Canonical lineage is the governance-approved, authoritative record of the operational lineage for a specific release. It is the single source of truth that documents: what context governed the release, which checkpoints were passed, which decisions were made, and who approved each governance gate.

The canonical lineage for a release is established at the time of certification. Once certified, it becomes the permanent, append-only record of how that release was produced.

Why It Matters

Without canonical lineage, a released artifact has no auditable history of the operational context that produced it. Engineers who encounter a production issue cannot determine whether the context used during development was governed or ad-hoc. The release has provenance in source control, but not in operational intent.

Canonical lineage provides the missing layer: the governed record of why the release was built the way it was, who approved each governance gate, and what constraints were in effect at the time.

Distinction from Operational Lineage

Operational lineage is the running record of context decisions during development — it accumulates throughout the engineering session.

Canonical lineage is a specific, governance-approved subset of operational lineage that is certified as the authoritative record for a release. Not all operational lineage becomes canonical. Only lineage that has passed certification and convergence validation is promoted to canonical status.

Relationship to Promotable Lineage

Promotable lineage is a prerequisite for canonical lineage. Lineage becomes promotable when it has passed certification. It becomes canonical when it is formally approved and attached to a specific release artifact.

In Yanzi

Yanzi’s release certification process produces a canonical lineage document for each certified release. This document is stored as an append-only artifact in the corpus, linked to the release version hash.