Files
prometeu-studio/docs/specs/packer/1. Domain and Artifact Boundary Specification.md
bquarkz a0a5050d5e
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 64.01% (20482/31999) * Branch Coverage: 54.22% (8240/15196) * Lines of Code: 31999 * Cyclomatic Complexity: 13164 #### Quality Gates Summary Output truncated.
Test / Build skipped: 15, passed: 715
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
complete Studio core and JavaFX boundary migration
2026-09-25 11:28:18 +01:00

3.4 KiB

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 consolidates the initial packer agenda and decision wave into normative form.

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/
  • registered 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.
  8. The packer's Java package root is p.packer; it must not be moved under p.studio or treated as a Studio subdomain.
  9. The packer must remain independently consumable by Studio, command-line tooling, build tooling, and future automation adapters.
  10. No Packer module may depend on p.studio, Studio UI, or Studio application modules.

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.

Studio Consumption Boundary

Studio is a consumer of Packer capabilities, not the owner of Packer semantics.

Rules:

  • Studio should consume a stable, neutral, use-case-oriented public Packer API directly;
  • Studio must not add a gateway that merely mirrors an already suitable public Packer API;
  • when only concrete, static, infrastructure-oriented, unstable, or excessively broad integration is available, the Studio consumer may define a narrow consumer-owned gateway;
  • implementations of Studio-owned gateways must stay outside Packer and outside the Studio Core functional contract;
  • Studio projections and orchestration must not duplicate Packer validation, packing, diagnostic, concurrency, or artifact semantics.

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.