114 lines
4.5 KiB
Markdown
114 lines
4.5 KiB
Markdown
# 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.
|