pub struct PinnedRef {
pub name: String,
pub component_type: ComponentType,
pub version: Version,
pub digest: ManifestDigest,
pub resolved_from: Option<VersionReq>,
}Expand description
An exact, digest-verified component pin. version and digest are both
mandatory (non-Option) — a pin always carries both.
Fields§
§name: String§component_type: ComponentType§version: Version§digest: ManifestDigest§resolved_from: Option<VersionReq>The semver range this pin was RESOLVED FROM, when it was resolved from
one. Same type as ComponentRef::Range’s range field, because a
resolution records the same kind of thing the range declared.
§Why a pin keeps the range it resolved (D-10)
Cargo’s model, adopted deliberately because that logic is proven and
will pass the same security reviews. Cargo keeps TWO artifacts:
Cargo.toml holds the range (author intent — what enables reuse and
upgrade), Cargo.lock holds the resolution (the exact version plus its
checksum). Pinning never destroys the range.
Before this field, ComponentRef was strictly either/or, so pinning
DISCARDED the declared range — losing the one fact the dev-to-prod case
turns on. A target environment could not distinguish “dev declared
^1.2 and resolved 1.3.0” from “dev declared =1.2.0”. In the first
case prod’s already-deployed 1.2.0 still satisfies ^1.2, so it is
silently kept — the wrong reference, with nothing in the package able to
say so.
§What None means — decided, not left implicit (D-10)
None means “no declared range is recorded on this pin”. It is NOT
distinguishable from “this package was packed before this field
existed”: the additive serde attributes below make an old pin
deserialize to exactly the value a direct pin produces. The crate
ACCEPTS that ambiguity rather than carrying a schema-version
discriminator — pmcp-package is 0.x, and the standing position for the
package tree is to break freely rather than ship compatibility shims.
Two obligations follow, and both are load-bearing:
- Consumer side. Anything building skew reporting on this field —
Phase 123’s dev-to-prod import check is the named one — MUST treat
Noneas “cannot report” and NEVER as “no skew”. Reading an absent fact as a positive claim is precisely the failure this field exists to prevent. - Producer side. A producer that resolved a range MUST record it. A
Nonewritten by a range-resolving producer is indistinguishable from an old package, and destroys the signal for every consumer downstream.
§Compatibility — both halves, because only stating one under-scopes the next change
-
Serde/wire: ADDITIVE.
#[serde(default)]means pin JSON written before this field existed still deserializes (yieldingNone), andskip_serializing_ifmeans nothing new is emitted for aNone. No checked-in fixture byte and no pinned digest constant moves — measured, not assumed: all fourtests/golden_fixtures/canonical/*.jsonfiles and all five pinned constants intests/digest_stability.rsare byte-identical across this addition, and their tests pass unedited.skip_serializing_ifis load-bearing here, not cosmetic: without it every pin would emit"resolved_from": null, and bothworkflow.canonical.jsonandEXPECTED_WORKFLOW_DIGESTwould move.A
Some(range)DOES change the canonical bytes and therefore the manifest digest — seerecording_the_range_a_pin_resolved_changes_the_manifest_digestintests/digest_stability.rs. The field participates in package identity; it is not cosmetic metadata that could be stripped or forged without changing what the package IS. -
Rust source: BREAKING.
PinnedRefhad four public fields before this, all non-Option, all set by struct literal — a fifth field breaks every literal in the language, everywhere. The MEASURED inventory is EIGHT construction sites (grep -rn 'PinnedRef {' --include="*.rs" crates cargo-pmcpreturns nine hits; the ninth is this struct’s ownpub struct PinnedRef {definition, which is not a construction site):crates/pmcp-package/src/reference.rs— 4 (all inside#[cfg(test)] mod tests)crates/pmcp-package/src/oci/unpack.rs— 2 (both in a#[cfg(test)]fixture helper)crates/pmcp-package/src/package/workflow.rs— 1 (#[cfg(test)]helper)crates/pmcp-team-servers/src/team/identity.rs— 1 (#[cfg(test)]helper)
A reader who takes “additive” at face value will under-scope the next field addition exactly as this one would have been.