prometeu-studio/docs/packer/specs/1. Domain and Artifact Boundary Specification.md

Domain and Artifact Boundary Specification

Status: Draft Scope: Packer domain core boundary Purpose: Define what the packer owns, what it emits, and where its responsibility stops.

Authority and Precedence

This specification is grounded in:

• 001-asset-workspace-registry-and-stable-identity-decision.md
• 003-build-artifacts-and-deterministic-packing-decision.md
• 007-shipper-integration-versioning-and-trust-model-decision.md

Runtime-side reading semantics for assets.pa are defined upstream in ../runtime/docs/runtime/specs/13-cartridge.md and ../runtime/docs/runtime/specs/15-asset-management.md.

Normative Inputs

• project workspace with assets/
• packer registry and control data under assets/.prometeu/
• managed asset roots anchored by asset.json

Core Rules

1. The packer owns asset workspace management and artifact production.
2. The packer emits the runtime-facing asset artifact assets.pa.
3. The packer may emit companion build artifacts for Studio and tooling.
4. The packer does not own cartridge shipping/publication.
5. A future shipper is a consumer of packer artifacts, not a co-author of the asset contract.
6. Runtime reading semantics are not redefined by the packer.
7. The packer must stop at artifact publication, not cartridge assembly.

Packer-Owned Artifacts

The packer owns production of at least:

• assets.pa
• build/asset_table.json
• build/preload.json
• build/asset_table_metadata.json
• asset.json
• assets/.prometeu/index.json

Runtime-Facing Boundary

assets.pa is the authoritative runtime-facing artifact.

Rules:

• the internal header of assets.pa is the runtime-facing source of truth for asset table and preload data;
• companion JSON outputs must not replace the internal header as the runtime contract;
• offsets and preload semantics must remain aligned with runtime specs.

Future Shipper Boundary

The future shipper may consume packer artifacts to assemble cartridges.

Rules:

• the packer must not depend on a concrete shipper implementation now;
• shipper-specific workflow detail is deferred;
• published artifact names and meanings must remain documented and stable enough for later consumption.

Non-Goals

• cartridge assembly flow
• package distribution format design
• runtime asset loading implementation detail

Exit Criteria

This specification is complete enough when:

• packer ownership is unambiguous;
• runtime-facing artifact authority is explicit;
• future shipper integration is bounded without overdesign.