# 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`](../agendas/01.7.%20Builder%20Integration,%20Versioning,%20and%20Trust%20Model%20Agenda.md).

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