prometeu-studio/docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md

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.
4. Relationship between services, CLI adapters, and future integrations.
5. Normative project layout expectations.
6. Runtime-facing artifact ownership and documentation responsibility.
7. 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.