3.8 KiB
G-026 Enforceable clean-checkout provenance policy for vendor and bootsupport pulls
Status: proposed Scope: src/make.tcl (vendorupdate and bootsupport steps), src/vendormodules/include_modules.config, src/bootsupport/modules*/include_modules.config Acceptance: as in root GOALS.md index (canonical).
Context
make.tcl vendorupdate pulls the latest release-stamped module files from each
source project's built modules/ folder (paths declared in
include_modules.config). Nothing verified the source project's checkout state,
so artifacts built from uncommitted source could be vendored with no committed
provenance anywhere. This actually happened: tomlish 1.1.7/1.1.8 were vendored
into punkshell from a tomlish working tree whose fossil history ended at 1.1.6
- the released content existed only as uncommitted edits (recorded and remedied 2026-07-06, tomlish checkin 37b71e82).
A warn-only check was added in project 0.2.5 (fix-now/goal-later review,
2026-07-06): vendor_source_dirty_warnings in make.tcl walks up from each
vendor source path to the nearest fossil and/or git root, runs
fossil changes / git status --porcelain, and warns once per VCS root when
dirty. The first real run flagged 8 dirty source projects, confirming the
problem is endemic, and equally that abort-by-default would have made
vendorupdate unusable on this machine today - which is why enforcement is a
goal (requiring cleanup and a policy/override design) rather than part of the
quick fix.
Approach
- Promote the warning to a policy: refuse to pull from dirty source projects unless an explicit override is given (flag such as -allow-dirty-sources, or per-project allowance); warn-only remains selectable as a configured mode. Where the mode is configured (command flag vs punk::config once G-014 lands) is an implementation decision to record.
- Share one check implementation between vendor_localupdate and bootsupport_localupdate (make.tcl already carries a "todo - sync alg with bootsupport_localupdate!" note; do not grow a second divergent copy).
- Per-root reporting and unversioned-location silence are established behaviour from the 0.2.5 check - keep them.
The residual staleness gap
A clean checkout is necessary but not sufficient: the built modules/ files
are produced from the working tree at build time, so they can predate the
latest commits (stale) or - the reverse of the tomlish case - have been built
from dirt that was subsequently committed. Candidate mechanisms, decision to
be recorded here:
- Rebuild-on-demand: vendorupdate triggers the source project's module build before pulling (correct, but couples projects' build systems).
- Provenance stamp: source projects stamp checkout id (fossil checkin / git hash) into built modules at build time; vendorupdate compares stamp to the source project's current checkout id (ties into the G-025 stamping machinery pattern).
- Accepted risk: document that clean-checkout checking is the enforced bar and staleness remains a manual concern.
Alternatives considered
- Abort-by-default immediately (no goal, just flip the fix) - rejected for now: the first run showed 8 dirty source projects; enforcement without a cleanup pass and an override design would block routine work.
- Checking only the specific pulled files' dirtiness rather than the whole source checkout - rejected: the built module is generated from many source files; per-file dirt attribution against a build product is not tractable.
Notes
- include_modules.config files carry their own "#todo - change to include_modules.toml" - a natural companion change under the G-024 toml-conversion pattern, but deliberately not part of this goal's acceptance.
- Related: G-014 (tomlish provenance incident motivated this), G-024 (toml config direction), G-025 (build stamping machinery a provenance stamp could ride on).