A File That Says Where It Came From
The single most important property of a vendored copy is that a reader who opens it — six months later, in a repository they have never worked in, hunting a bug — immediately knows three things: this file is not authored here, here is where it is authored, and here is what to run to change it.
So every deployed file gets a first line. It names the kit source path, the kit commit the body came from, and the instruction:
GENERATED FROM the-kit/kit/python/kit_pippa.py @ <kit-sha> — DO NOT EDIT HERE. Edit the kit and run the sync script.
The comment syntax is chosen per file extension, which is a small detail with a large consequence: the header is a comment in Python, TypeScript, JavaScript, CSS and Swift alike, so one deploy mechanism can serve every language in the family without any of them needing a preamble stripped at build time. A few sources cannot take a prepended line at all — a shell script whose first line must be the interpreter, a property list whose first line must be the XML declaration. Those carry the origin note inside their own body and are marked so the deploy will not invent a line 1. The comparison still wants an exact body; only the insertion rule changed.
Why the Header Must Not Be Compared
The header names the kit commit that was current when the file was deployed. The file on disk does not churn — a re-deploy only rewrites a copy whose body actually changed. But the expected header is built from the kit's HEAD right now, so the moment the kit commits anything at all, every already-deployed file carries a SHA older than the one a comparison would compute. Include the header in that comparison and every consumer reports drift after every kit commit, forever, for files nobody touched.
A check that fires constantly is a check that gets disabled. So the comparison strips the first line if it carries the marker, and compares only what follows. Drift then means exactly one thing: the body differs. That precision is what lets the check be wired into test suites without anybody resenting it.
The Awkward Case: Refreshing Only the Certificate
There is one wrinkle worth knowing, because it is the kind of thing that looks like a bug in the tool. A header names the kit commit that was current when its body was deployed. Later the kit commits something that leaves that body byte-identical — a regenerated binding, an edit to a neighbouring file — and the copies should now name the newer commit. The body is right; the certificate is old.
The tool handles that with a narrow, explicit mode: re-run the deploy with an instruction to refresh provenance for the named sources only. It rewrites those headers and leaves every other body-identical copy alone — so unrelated vendored files keep the commit that actually deployed their body, which is the honest record. It is still a deploy run, though: a copy whose body differs from the kit, or one that is missing, is deployed in the same pass exactly as it would be without the flag. The flag narrows which headers get refreshed, not which bodies get shipped, so run it from a kit tree whose other changes you mean to ship. It is a narrow feature on purpose, and it exists because the alternative (blanket header rewrites) would quietly destroy the one piece of information the header is for.