104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# Shipper Integration, Versioning, and Trust Model Agenda
|
|
|
|
## Status
|
|
|
|
Closed
|
|
|
|
Resolved by [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md).
|
|
|
|
## Purpose
|
|
|
|
Close the cross-domain contracts around shipper integration, schema versioning, migrations, and the packer trust model.
|
|
|
|
## Context
|
|
|
|
The tail of the draft contains several cross-cutting commitments:
|
|
|
|
- shipper consumes packer outputs,
|
|
- `../runtime` must be able to read the packer-produced artifact contract,
|
|
- multiple JSON artifacts carry `schema_version`,
|
|
- packer must migrate older schemas or emit actionable diagnostics,
|
|
- packer is offline tooling and must not execute untrusted scripts.
|
|
|
|
These topics are cross-domain and should be discussed together before hardening the specs.
|
|
The first step should be to document the runtime-facing interface explicitly instead of leaving it implicit in tooling behavior.
|
|
|
|
## Source Sections
|
|
|
|
- `15. Integration with Cartridge Shipper`
|
|
- `16. Compatibility and Versioning`
|
|
- `17. Security and Trust Model`
|
|
|
|
## Runtime Normative Inputs
|
|
|
|
From `../runtime/docs/runtime/specs/13-cartridge.md`:
|
|
|
|
- cartridges may contain optional `assets.pa`;
|
|
- when `Asset` capability is declared, valid `assets.pa` is required before asset bootstrap;
|
|
- runtime validation failure must happen before preload execution;
|
|
- `assets.pa` is the runtime-facing asset artifact for the current runtime.
|
|
|
|
From `../runtime/docs/runtime/specs/15-asset-management.md`:
|
|
|
|
- the runtime-facing asset model is bank-centric;
|
|
- `preload` is boot-time input only;
|
|
- runtime residency and bank ownership are independent from VM heap ownership;
|
|
- asset loading uses slice-based access over `assets.pa`;
|
|
- schema-bearing runtime-facing structures already exist and must be versioned carefully.
|
|
|
|
These runtime specs already constrain packer evolution. The packer discussion should focus on how to honor and document this contract on the tooling side.
|
|
|
|
## Key Questions
|
|
|
|
1. Which integration points with shipper are packer-owned versus shared contracts?
|
|
2. Which artifacts need explicit migration policy?
|
|
3. Is backward compatibility required for all schema versions or only within a support window?
|
|
4. What counts as trusted configuration versus untrusted input data?
|
|
5. Can packer ever execute plugin-like transformations, or is that forbidden by architecture?
|
|
6. How should migration failures be surfaced to users and CI?
|
|
7. How should the runtime reader contract be versioned and documented?
|
|
8. Which compatibility guarantees apply specifically to `../runtime` consumption?
|
|
9. Which parts of the runtime-facing contract are owned by runtime specs versus packer-owned companion specs?
|
|
|
|
## Options
|
|
|
|
### Option A
|
|
|
|
Keep shipper integration narrow, schema versioning explicit, and trust model conservative.
|
|
|
|
### Option B
|
|
|
|
Allow broader extensibility and looser compatibility commitments.
|
|
|
|
## Tradeoffs
|
|
|
|
- Option A is easier to secure and specify.
|
|
- Option A supports reliable CI and migration diagnostics.
|
|
- Option B may feel more flexible, but it introduces major review and safety burden early.
|
|
|
|
## Recommendation
|
|
|
|
Adopt Option A and treat schema evolution plus trust boundaries as first-class contracts.
|
|
|
|
## Expected Decisions to Produce
|
|
|
|
1. Shipper integration boundary.
|
|
2. Schema versioning and migration policy.
|
|
3. Compatibility guarantees.
|
|
4. Security and trust invariants.
|
|
5. Runtime consumption contract and versioning boundary.
|
|
6. Ownership split between runtime normative specs and packer-side companion documentation.
|
|
|
|
## Expected Spec Follow-up
|
|
|
|
- Shipper integration spec.
|
|
- Schema versioning and migration spec.
|
|
- Security and trust model spec.
|
|
- Runtime reader and compatibility interface spec.
|
|
|
|
## Non-Goals
|
|
|
|
- CLI ergonomics for all commands.
|
|
- Detailed asset format transformation pipelines.
|
|
- Workspace hygiene behavior.
|