ManifestProvenance: say why build_git_sha is absent (closes #100)
Closes #100. Both riders held, and the signature stayed compatible — which was not the first shape I built.
The reason
BuildGitShaAbsenceReason — DeclinedDirty, NeverDerived, NoGitDir, plus ForwardCompatibleUnknown(String) per the #79 ruling, named so a reader sees it is the forward-compat arm and not a cause. Optional, skip_serializing_if, present only when build_git_sha is absent.
Rider 1: contradiction is unrepresentable, not rejected
The reason is derived by the helper that decides the omission, and the input makes a contradicting call impossible to write rather than an error to catch:
pub enum BuildGitShaSource<'a> {
Git { revision: &'a str, tree_state: GitTreeState },
NeverDerived,
NoGitDir,
}
NeverDerived and NoGitDir carry no revision field, so "NeverDerived with a sha" does not typecheck. DeclinedDirty is reachable only from Git { tree_state: Dirty }. Callers cannot supply a reason at all.
Rider 2: the stamp rule is pure
pub fn attestable_commit(revision: &str, tree_state: GitTreeState) -> Option<&str>
A function of its arguments, so both branches run in a test without rebuilding. This was the half you called sharper, and it is the reason the refusing branch is now reachable at all: build.rs's current rule reads env! inline, so its refusal path has never executed in a test.
The signature stayed compatible — and that was a correction
The first implementation changed build_provenance's signature in place. Before opening this I checked who calls it outside this repo: five fleet consumers do, with the three-argument form — broca, cerebellum, claustrum, insula, synapse. Sample, broca-module-serve/src/manifest.rs:65:
match subc_protocol::manifest::build_provenance(
option_env!("CK_BUILD_REV"),
All five would have failed to compile. That matters more than an ordinary break here: #83 moved this helper into subc-protocol specifically so transport-direct modules that cannot link the client SDK could still build honest provenance. Breaking its signature re-imposes the cost that move was made to remove — and it is a source break with no wire change, so no lockfile, version pin, wire-crate check or golden fixture would have caught it. It surfaces as five other repos' red builds, on their clock.
So:
build_provenance(Option<&str>, Option<&str>, Option<&str>)— unchanged semantics, emits no reason.build_provenance_from_source(BuildGitShaSource<'_>, …)— the reason-bearing path. This repo's own callers migrated to it.
The doc comment says why the legacy path names no reason: not because absence has no cause there, but because a caller that has not told us the tree state has given us no ground to name one, and guessing would be the fabrication this issue exists to prevent.
Compatibility is proved from outside the crate
An in-crate test can compile for reasons an external consumer cannot rely on, so the proof is a doc-test — doc-tests compile as a separate crate against the public API, exactly the linkage those five repos have:
let provenance = build_provenance(option_env!("CK_BUILD_REV"), None, None)
.expect("legacy build facts remain supported");
assert!(provenance.build_git_sha_absence_reason.is_none());
And the bytes, not just the field: legacy_build_provenance_keeps_master_wire_bytes_without_an_absence_reason asserts exact serde_json::to_string output against hardcoded literals (not values derived from the new implementation) for a canonical 40-hex sha, None, and the "unknown" sentinel.
I ran the discriminating mutation myself rather than take it on report — making the legacy path emit Some(NeverDerived) reds both proofs:
manifest.rs:2123: left: Some(NeverDerived)
right: None
doc-test line 790: assertion failed: provenance.build_git_sha_absence_reason.is_none()
Restored, 48/48 green, tree clean.
Versions
subc-protocol 0.19.2 — additive now that the old signature is retained; nothing a consumer must change to compile. subc-core 0.17.46, avoiding 0.17.45 which PR #101 is holding.
Gates: workspace 1357 passed / 0 failed · clippy -D warnings · fmt · check-wire-crate-versions.sh 6 crates, none unbumped · no golden fixtures changed.
CONSUMER-IMPACT: additive. Existing three-argument callers compile unchanged and their wire output is byte-identical; the absence reason is opt-in via the new entry point.
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.
Summary by cubic
Adds an optional build_git_sha_absence_reason field to ManifestProvenance so consumers can see why build_git_sha is missing, closing #100. The legacy build_provenance API keeps its three-argument signature and emits no reason; source-aware callers use the new build_provenance_from_source entry point.
New Features
BuildGitShaAbsenceReasondistinguishesDeclinedDirty,NeverDerived, andNoGitDir, and preserves unknown future reasons asForwardCompatibleUnknown(String).BuildGitShaSourceprevents assigning a SHA toNeverDerivedorNoGitDir, and the dirty-tree rule is a pureattestable_commitfunction.- Validation rejects a provenance that has both a SHA and an absence reason; the field is omitted from JSON when absent.
Migration
- Existing
build_provenance(...)callers compile unchanged and keep byte-identical wire output. - Direct
ManifestProvenanceliterals need the newbuild_git_sha_absence_reason: Nonefield;subc-protocolis bumped to 0.19.2.