# 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.