# Builder Integration, Versioning, and Trust Model Agenda

## Status

Open

## Purpose

Close the cross-domain contracts around builder integration, schema versioning, migrations, and the packer trust model.

## Context

The tail of the draft contains several cross-cutting commitments:

- cartridge builder 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 Builder`
- `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 builder 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 builder 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. Builder 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

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