discussion framework migration
This commit is contained in:
@@ -0,0 +1,124 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user