224 lines
7.0 KiB
Markdown
224 lines
7.0 KiB
Markdown
# 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
|