Summary
Replace the transparent type aliases in types.go:32-59 (Snapshot, AgentConfig, PhaseResult, Phase, and the phase constants) with facade-owned structs and translate at the boundary — same pattern ValidateOption already uses in options.go:24.
Motivation
docs/integrator/public-api.md advertises github.com/NVIDIA/aicr as Public (stable) and marks pkg/snapshotter as Internal ("may change without notice"). But types.go:32 is type Snapshot = snapshotter.Snapshot — a transparent type alias. Consumers using aicr.Snapshot are identity-pinned to snapshotter.Snapshot; any field rename/removal in the "Internal" package breaks them.
Same shape for AgentConfig (types.go:40, ← snapshotter), PhaseResult (line 46), Phase (line 51), and the phase constants (lines 55-59). pkg/validator is "Public (evolving)" not "Internal" but it still can't supply identity for a "stable" surface — "evolving" by definition admits minor-bump breakage.
The PR description (#1072) acknowledges this: "promoting them to facade-owned wrappers is worth scoping separately."
Acceptance
Notes on translation cost
Most of these types carry transitively-referenced types of their own (e.g., validator.PhaseResult embeds a CTRF report; snapshotter.Snapshot embeds a measurement.Measurement slice). The fix has to either:
- Wrap the immediate type and re-expose only the fields the facade guarantees (lossy but stable), or
- Wrap recursively (high effort, mirrors more types).
Pick (1) unless a consumer concretely needs a field that (1) drops.
Related
Summary
Replace the transparent type aliases in
types.go:32-59(Snapshot,AgentConfig,PhaseResult,Phase, and the phase constants) with facade-owned structs and translate at the boundary — same patternValidateOptionalready uses inoptions.go:24.Motivation
docs/integrator/public-api.mdadvertisesgithub.com/NVIDIA/aicras Public (stable) and markspkg/snapshotteras Internal ("may change without notice"). Buttypes.go:32istype Snapshot = snapshotter.Snapshot— a transparent type alias. Consumers usingaicr.Snapshotare identity-pinned tosnapshotter.Snapshot; any field rename/removal in the "Internal" package breaks them.Same shape for
AgentConfig(types.go:40, ←snapshotter),PhaseResult(line 46),Phase(line 51), and the phase constants (lines 55-59).pkg/validatoris "Public (evolving)" not "Internal" but it still can't supply identity for a "stable" surface — "evolving" by definition admits minor-bump breakage.The PR description (#1072) acknowledges this: "promoting them to facade-owned wrappers is worth scoping separately."
Acceptance
aicr.Snapshot,aicr.AgentConfig,aicr.PhaseResult,aicr.Phase, and the phase constants are facade-owned types with no transparent alias to internal packages.pkg/snapshotter/pkg/validatortypes is done inside the facade (analogous toapplyValidateOptionsinoptions.go).docs/integrator/public-api.mdis consistent: every type reachable from the Public (stable) facade is either facade-owned or comes from a package the matrix lists as Public (stable).Notes on translation cost
Most of these types carry transitively-referenced types of their own (e.g.,
validator.PhaseResultembeds a CTRF report;snapshotter.Snapshotembeds ameasurement.Measurementslice). The fix has to either:Pick (1) unless a consumer concretely needs a field that (1) drops.
Related