125 lines
3.6 KiB
Markdown
125 lines
3.6 KiB
Markdown
# Versioning, Migration, and Trust Model Specification
|
|
|
|
Status: Draft
|
|
Scope: Artifact/schema versioning, migration ownership, and conservative trust boundaries
|
|
Purpose: Define how the packer evolves safely over time and what trust assumptions it makes.
|
|
|
|
## Authority and Precedence
|
|
|
|
This specification consolidates the initial packer agenda and decision wave into normative form.
|
|
|
|
## Core Rules
|
|
|
|
1. Versioning is explicit and per artifact/schema.
|
|
2. Migration applies only to artifacts the packer owns.
|
|
3. Compatibility is governed by a support window, not indefinite backward guarantees.
|
|
4. Inputs are untrusted until validated.
|
|
5. Baseline packer architecture does not execute arbitrary plugins or scripts.
|
|
|
|
## Explicit Versioning Surfaces
|
|
|
|
The packer versioning model applies to at least:
|
|
|
|
- `asset.json`
|
|
- `index.json`
|
|
- `assets.pa`
|
|
- the `assets.pa` header contract
|
|
- companion build artifacts where a stable reader exists
|
|
- packer-owned cache/control schemas where migration is supported
|
|
|
|
## Migration Ownership
|
|
|
|
The packer owns migration of artifacts it controls.
|
|
|
|
This includes:
|
|
|
|
- `asset.json`
|
|
- `index.json`
|
|
- packer-owned caches and control files
|
|
|
|
Rules:
|
|
|
|
- migration may be automatic within the supported window;
|
|
- unsupported versions fail clearly and early;
|
|
- migration failures must be diagnosable in Studio and CI.
|
|
- migration may need to preserve or repair identity-bearing fields such as `asset_uuid` without fabricating a different asset identity silently.
|
|
|
|
## Runtime Compatibility Boundary
|
|
|
|
Runtime reading semantics for `assets.pa` belong upstream to runtime specs.
|
|
|
|
Rules:
|
|
|
|
- the packer implements the corresponding writer-side production contract;
|
|
- the packer must not redefine runtime reader semantics;
|
|
- companion artifacts do not redefine the runtime-facing contract.
|
|
|
|
## Future Shipper Boundary
|
|
|
|
The future shipper is a consumer of packer artifacts.
|
|
|
|
Rules:
|
|
|
|
- the shipper is not a current packer dependency;
|
|
- the shipper must not become a silent repair layer for invalid packer artifacts;
|
|
- shipper workflow detail is deferred until the shipper exists.
|
|
|
|
## Trust Model
|
|
|
|
The trust posture is conservative.
|
|
|
|
Untrusted until validated:
|
|
|
|
- source asset files;
|
|
- hand-edited or legacy declarations;
|
|
- imported external project content;
|
|
- legacy packer artifacts and control data.
|
|
- runtime snapshot observations that have not yet been reconciled against changed workspace files.
|
|
|
|
Trusted only after:
|
|
|
|
- strict parse;
|
|
- structural validation;
|
|
- semantic validation;
|
|
- version compatibility check.
|
|
- reconcile or refresh when divergence between snapshot and filesystem has been detected.
|
|
|
|
## Plugin and Script Execution
|
|
|
|
The baseline packer contract forbids arbitrary external execution as part of normal asset processing.
|
|
|
|
Rules:
|
|
|
|
- no untrusted plugins;
|
|
- no ad hoc script execution;
|
|
- no implicit foreign-code extension hooks.
|
|
|
|
Any future extensibility model requires a separate decision.
|
|
|
|
## Failure Surfacing
|
|
|
|
Version and migration failures must be actionable.
|
|
|
|
At minimum, diagnostics should make clear:
|
|
|
|
- the version found;
|
|
- the supported range or expectation;
|
|
- whether migration was attempted;
|
|
- whether identity-bearing fields or registry/catalog alignment were implicated;
|
|
- whether manual action is required;
|
|
- whether the failure blocks build or Studio workflow.
|
|
|
|
## Non-Goals
|
|
|
|
- artifact signing strategy
|
|
- distribution security beyond current tooling trust posture
|
|
- remote/shared artifact registry behavior
|
|
|
|
## Exit Criteria
|
|
|
|
This specification is complete enough when:
|
|
|
|
- artifact versioning boundaries are explicit;
|
|
- migration ownership is unambiguous;
|
|
- trust assumptions are conservative and enforceable.
|