prometeu-studio/docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md

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 is grounded in:

• 007-shipper-integration-versioning-and-trust-model-decision.md

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.

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.

Trusted only after:

• strict parse;
• structural validation;
• semantic validation;
• version compatibility check.

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