The source is what can be rebuilt

Teams often discover what their source of truth is only after they need it. A public site is running. Its repository contains part of the content. A server contains another part. A release archive has assets that neither location has. The organization can point to several plausible originals, yet none can reproduce the thing people actually see. The phrase “canonical source” then stops sounding like documentation hygiene and starts sounding like a question of institutional memory.

The usual response is to choose a folder and declare it authoritative. That declaration helps only if the folder is complete, governed, and capable of producing the public result. A label cannot restore a missing essay, explain an unexplained image, or prove which revision reached readers. Canonicality is earned through reconstruction. The controlling source is the material from which an authorized operator can build the same publication, account for its differences, and repeat the release without scavenging from production.

This standard changes recovery work. The live system is not automatically the truth, because it may include accidents, abandoned files, or edits made outside the normal process. The repository is not automatically the truth either, because a repository can lag behind a successful release. Recovery must compare them. It treats each surface as evidence, identifies what was intentionally public, and then creates a governed source set that can explain the result.

Recovery is an act of authorship

Recovering a public system is not the same as copying it. A blind copy preserves every ambiguity. It may import generated artifacts beside their templates, private notes beside public pages, and old assets beside current ones. The recovered tree looks complete because it contains more, but no one knows which files matter. Useful recovery classifies what it finds: authored content, generated output, public assets, internal evidence, obsolete material, and unexplained residue.

That classification requires judgment. A page that exists only in production may be a legitimate release that never made it back to source, or it may be an accidental exposure. A file in version control may be a planned publication, or it may have been deliberately withheld. Dates, links, release records, build rules, and surrounding artifacts all help. No single signal is enough. The aim is not to crown one location after a superficial comparison; it is to construct a history that makes the differences intelligible.

The canonical source is the smallest governed set of material that can reproduce the public truth without reproducing its accidents.

Isolation makes this work safer. Git’s official worktree documentation describes multiple working trees with separate indexes and branch state attached to one repository. That mechanism is useful beyond convenience. A recovery can proceed in a clean working tree while unrelated work remains untouched. The operator can see which changes belong to recovery, test the reconstructed build, and compare it with the live service without mixing two histories.

Isolation is not permission to ignore the shared repository. Worktrees share objects and references, and eventually the recovered source must return through ordinary review. But the separate index creates a clean boundary around the act of reconstruction. It reduces the chance that unrelated edits become part of a release merely because they were present on the same machine.

A source must carry its own proof

A trustworthy source tree should answer four questions. What material is authored? What material is generated? What is allowed to become public? And how can a reviewer verify the resulting publication? Those answers belong in scripts, manifests, validation rules, and version history, not in the memory of the person who performed the rescue.

The build should be deterministic enough to reveal unexpected differences. Generated indexes should come from the same inventory as the pages they describe. Public artifacts should be assembled from an explicit set of file classes. Validation should compare counts across surfaces, inspect links, reject forbidden material, and fail when an essay cannot be represented consistently. These controls turn a recovered snapshot into an operable source.

The source also needs provenance. The W3C PROV-O recommendation offers a general vocabulary for entities, activities, and agents. A small publication need not adopt its entire model to learn from its discipline: record what input produced an artifact, which process transformed it, and who or what performed the release. That chain makes later reconstruction less dependent on folklore.

This is why production should be treated as evidence but not as an editing environment. If an emergency change must occur there, the change should immediately create a reconciliation obligation. Otherwise the running service becomes a second authoring system, and the next release may erase the fix or preserve it without explanation.

Canonical source is therefore a capability, not a location. It is the capability to reproduce, inspect, change, and release the public system from governed material. A directory becomes canonical when those operations work and their history is legible. Until then, the label is a hope.

The recovery should end with a comparison that anyone on the team can repeat. Build from the recovered source, enumerate the artifact, and compare representative pages, metadata, assets, and discovery files with the current service. Differences should be either corrected or documented as intentional. This repeatable comparison is more valuable than a one-time declaration that the rescue “looks right,” because it becomes the baseline for every later release.

Recovery is complete only when the organization no longer needs the accident that forced it. The next operator should be able to rebuild from source, understand what will be public, and explain why the result differs from yesterday. That is the point at which a rescued publication becomes an institutionally owned one.

— Dispatches · Summit Cognitive