prometeu-studio/docs/packer/decisions/007-shipper-integration-versioning-and-trust-model-decision.md

Shipper Integration, Versioning, and Trust Model Decision

Status

Accepted

Date

2026-03-11

Context

This decision closes the architectural questions raised in 01.7. Builder Integration, Versioning, and Trust Model Agenda.

The packer must define:

• how its artifacts are versioned;
• what migration obligations it owns;
• what trust boundaries apply to asset tooling;
• how a future shipper will consume packer outputs without becoming part of the packer architecture now.

The important clarification is:

• the shipper does not exist yet as part of the current packer work;
• shipper integration is therefore a future consumer boundary, not a present operational dependency.

Decision

The packer adopts a future-shipper-consumer, explicit-versioning, conservative-trust model.

1. Current shipper boundary

The shipper is not part of the current packer architecture.

Rules:

• the packer must not depend on a concrete shipper implementation;
• the packer should emit stable, documented artifacts that a future shipper can consume;
• current packer design must stop at artifact publication, not at cartridge shipping orchestration.

2. Ownership boundary

Current ownership is split as follows:

• packer owns artifact production;
• runtime owns runtime-side artifact reading semantics;
• future shipper will own cartridge shipping/publication concerns.

This means:

• runtime-facing reading contract for assets.pa belongs to runtime specs;
• writer-side production contract for assets.pa belongs to packer specs;
• a future shipper consumes these artifacts but does not redefine the asset contract.

3. Packer-owned artifacts

The packer is responsible for emitting and versioning at least:

• assets.pa
• build/asset_table.json
• build/preload.json
• build/asset_table_metadata.json
• asset.json
• index.json
• packer-owned cache and control data

These are the boundaries a future shipper may consume, but they remain packer-owned artifacts.

4. Minimal future shipper contract

The future shipper contract should remain minimal for now.

Baseline contract:

• which packer artifacts are published;
• where they are expected to exist;
• which artifacts are runtime-facing versus tooling-only;
• which artifacts are authoritative versus derived.

Detailed shipping workflow is deferred until the shipper exists.

5. Versioning policy

Versioning is explicit and per-artifact/per-schema.

Rules:

• asset.json has explicit schema versioning;
• index.json has explicit schema versioning;
• assets.pa has explicit runtime-facing envelope versioning;
• companion artifacts may have their own schema versioning where needed;
• version evolution is tracked per concern, not by one global version number for the whole domain.

6. Migration policy

The packer migrates only artifacts it owns.

This includes, at minimum:

• asset.json
• index.json
• packer-owned caches and control files

Rules:

• migration may be automatic within a supported window;
• outside the supported window, the packer fails with actionable diagnostics;
• the packer does not assume a cooperative migration workflow with a shipper that does not yet exist.

7. Compatibility window

Backward compatibility is provided through an explicit support window, not an open-ended forever policy.

Rules:

• the packer must define which previous versions it can read or migrate;
• unsupported versions fail clearly and early;
• CI and Studio should be able to surface unsupported-version failures deterministically.

8. Runtime compatibility guarantees

The packer must preserve compatibility guarantees relevant to ../runtime.

These include:

• assets.pa emitted according to the runtime-facing reader contract;
• offsets relative to payload region;
• canonical header semantics where required by packer-side production rules;
• stable asset_id continuity end-to-end;
• preload emitted according to the current runtime-facing contract.

The runtime must not depend on companion JSON artifacts for correctness.

9. Trusted versus untrusted inputs

The packer uses a conservative trust model.

Untrusted until validated:

• source asset files;
• manually edited or legacy asset.json;
• legacy registry/control data;
• imported artifacts and external project content.

Trusted only after:

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

10. No plugin/script execution baseline

The packer must not execute arbitrary external plugins or scripts in the baseline architecture.

Rules:

• no script execution as part of normal asset transformation contract;
• no untrusted extension hooks;
• no implicit foreign code execution during build.

Any future extensibility model requires a separate decision.

11. Shipper as consumer, not co-author

A future shipper consumes packer outputs but must not silently reinterpret or repair the asset contract.

Rules:

• shipper does not redefine assets.pa;
• shipper does not become the source of truth for asset_table or preload semantics;
• if an asset artifact is invalid, the issue belongs back to packer production, not to shipper-side correction.

Invariants and Constraints

The following invariants now apply:

1. The shipper is a future consumer, not a current packer dependency.
2. Packer stops at artifact production.
3. Runtime owns reader semantics of the runtime-facing artifact.
4. Packer owns writer semantics and companion artifacts on the production side.
5. Versioning is explicit per artifact/schema.
6. Migration applies only to artifacts the packer owns.
7. Compatibility is governed by a support window, not indefinite backward promises.
8. Inputs are untrusted until validated.
9. Baseline packer architecture does not execute arbitrary plugins or scripts.
10. A future shipper is a consumer, not a co-author of the asset contract.

Explicit Non-Decisions

This decision does not yet define:

• the concrete shipper implementation;
• cartridge shipping workflow details;
• packaging formats beyond the currently documented runtime forms;
• artifact signing or distribution security policy;
• remote/shared artifact registry behavior.

Those belong to later decisions and future shipper work.

Propagation Targets

This decision must propagate to:

• packer versioning and migration specs;
• packer trust/security model spec;
• future shipper integration spec;
• Studio diagnostics for unsupported versions and migration failures;
• future implementation of schema migration boundaries and compatibility checks.

Validation Notes

Example: unsupported registry version

• index.json version is outside the supported migration window
• packer reports explicit version mismatch and migration failure
• build does not continue

Example: future shipper consumption

• packer emits assets.pa and companion build artifacts
• future shipper consumes those artifacts to assemble a cartridge
• shipper does not reinterpret asset semantics or rewrite packer-owned artifact meaning