# Packer Scope, Boundaries, and Golden Pipeline Agenda

## Status

Open

## Purpose

Define the architectural boundary of the `packer` domain before the draft is decomposed into normative specs.

## Context

`Prometeu Packer.md` already establishes a strong direction:

- packer owns asset management,
- packer produces `build/assets.pa`,
- packer produces `build/asset_table.json`,
- packer must produce artifacts that can be consumed by `../runtime`,
- packer operations must be available as Studio-integrated services,
- packer does not build the cartridge,
- cartridge builder consumes packer outputs later.

This is a good draft direction, but it still needs to be closed as an explicit domain contract.
The interface between packer outputs and `../runtime` should be documented first, before it is treated as implementation detail.

The runtime already exposes normative constraints that the packer must treat as upstream contract, not as optional design space.

## Source Sections

- `1. Goals and Non-Goals`
- `2. Repository / Project Layout (Golden Pipeline)`
- `3. Crate Topology`
- `15. Integration with Cartridge Builder`

## Runtime Normative Inputs

From `../runtime/docs/runtime/specs/13-cartridge.md`:

- `assets.pa` is the runtime-facing asset artifact consumed by the current runtime;
- cartridges that declare `Asset` capability must provide valid `assets.pa`;
- runtime bootstrap must fail early when the asset capability is declared but `assets.pa` is missing or invalid;
- `assets.pa` v1 is autocontained and contains:
  - fixed binary prelude,
  - JSON header,
  - binary payload region.

From `../runtime/docs/runtime/specs/15-asset-management.md`:

- the runtime consumes `assets.pa` as the primary cartridge asset artifact;
- the runtime-facing contract is bank-centric;
- `asset_table` and `preload` are loaded from inside `assets.pa`;
- payload slices are resolved relative to `payload_offset`;
- the runtime must not require the full `assets.pa` payload to remain resident in RAM as its baseline operating mode.

These points are already normative on the runtime side and should be treated as hard inputs for packer-side discussion.

## Key Questions

1. What is the exact ownership boundary between `packer` and `cartridge builder`?
2. Should `packer` be defined purely as offline asset tooling, or as a Studio-integrated service surface with optional CLI adapters?
3. Which project directories are normative for packer behavior, and which are merely conventional?
4. Should packer be allowed to read `src/` or compiler outputs at all, or only operate on `assets/` plus project metadata?
5. Is `build/asset_table.json` a packer-owned artifact contract or a shared cross-domain contract?
6. Which packer-produced artifact is the runtime-facing contract, and what must be documented before code depends on it?
7. Which parts of the runtime-facing `assets.pa` contract are already closed by runtime specs and therefore outside packer-side redesign scope?

## Options

### Option A

Keep packer strictly scoped to `assets/` workspace management and production of packer outputs only.

### Option B

Allow packer to absorb more cartridge preparation responsibilities over time.

## Tradeoffs

- Option A keeps the architecture cleaner and reduces domain leakage.
- Option A makes builder integration more explicit and easier to spec.
- Option B may feel convenient short-term, but it risks collapsing packer and builder concerns into one blurred tool boundary.

## Recommendation

Adopt Option A and make the packer/builder boundary explicit as a first-class architectural invariant.

Also adopt this operational direction:

- packer capabilities should be modeled as services first;
- any CLI surface should be treated as an adapter over those services, not as the architectural center of the domain.

## Expected Decisions to Produce

1. Packer domain boundary.
2. Ownership of `assets.pa` and `asset_table.json`.
3. Relationship between CLI, core library, and future integrations.
3. Relationship between services, CLI adapters, and future integrations.
4. Normative project layout expectations.
5. Runtime-facing artifact ownership and documentation responsibility.
6. Explicit statement that runtime specs 13 and 15 are upstream constraints for `assets.pa`.

## Expected Spec Follow-up

- Packer domain charter or overview spec.
- Builder integration spec.
- Artifact ownership and responsibility spec.
- Runtime artifact interface spec.

## Non-Goals

- Defining the detailed schema of `asset_table.json`.
- Defining individual asset formats.
- Designing cartridge builder internals.