prometeu-studio/docs/packer/pull-requests/PR-19-api-surface-audit-model-separation-and-public-read-dtos.md

PR-19 API Surface Audit, Model Separation, and Public Read DTOs

Domain Owner: docs/packer Cross-Domain Impact: docs/studio

Briefing

The current packer API still exposes some read payload types that are simultaneously acting as public transport objects and internal implementation models.

This is acceptable during early convergence, but it weakens the boundary between prometeu-packer-api and prometeu-packer-v1.

The next cleanup step is to make the API explicit about three different categories:

• domain contracts,
• request/response messages,
• public read DTOs.

At the same time, the internal implementation models used by prometeu-packer-v1 should stop leaking through the API as if they were stable public models.

Objective

Separate internal v1 read models from public API read DTOs while preserving:

• request/response messages as immutable messages,
• domain contracts as domain contracts,
• exceptions as part of the public API,
• and Studio compatibility through explicit mapper-based conversion inside prometeu-packer-v1.

Dependencies

• ./PR-15-snapshot-backed-asset-query-services.md
• ./PR-16-write-lane-command-completion-and-used-write-services.md
• ./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md
• ./PR-18-legacy-service-retirement-and-regression-hardening.md

Scope

• audit the current public packer API against real external consumption
• preserve public exceptions in the API even when only v1 currently throws them
• preserve request/response records as request/response messages rather than renaming them as generic DTOs
• move the current mixed model/transport read types out of the API and into prometeu-packer-v1
• introduce public read DTOs in the API for the information Studio actually consumes
• add explicit mapper classes in prometeu-packer-v1 to convert internal models into API DTOs
• keep the active service wave limited to initWorkspace, listAssets, getAssetDetails, and createAsset

Non-Goals

• no new packer capabilities
• no write API redesign
• no doctor or build/pack reintroduction
• no reconcile observer work
• no semantic change to asset identity, registry ownership, or snapshot authority

Execution Method

1. Classify the current API surface into:
   • public domain contracts,
   • public request/response messages,
   • public read DTOs,
   • internal implementation models.
2. Keep domain contracts in prometeu-packer-api without DTO suffixes.
3. Keep request/response types in prometeu-packer-api as immutable message records with Request and Response naming.
4. Move the current mixed read shapes now exposed as PackerAssetSummary, PackerAssetDetails, and PackerAssetIdentity into prometeu-packer-v1 as internal models.
5. Introduce explicit public DTOs in the API for runtime-backed read payloads, such as:
   • PackerAssetSummaryDTO
   • PackerAssetDetailsDTO
   • PackerAssetIdentityDTO
   • PackerCodecConfigurationFieldDTO
   • and PackerDiagnosticDTO if diagnostics remain part of public responses.
6. Add explicit mapper classes in prometeu-packer-v1 to convert internal models into API DTOs before responses cross the module boundary.
7. Update response messages to carry the new DTO types instead of leaking v1 models through the API.
8. Update Studio consumers to read from the new DTO types while preserving the same user-facing behavior.

Acceptance Criteria

• the API surface is explicitly partitioned between domain contracts, request/response messages, and read DTOs
• request/response messages remain immutable message records and are not renamed as generic DTOs
• public exceptions remain in the API
• internal v1 models are no longer exposed as if they were public API models
• Studio depends only on API contracts and DTOs, not on v1 model semantics
• conversion from v1 internal models to public API DTOs happens through explicit mapper code
• no behavior regression is introduced in initWorkspace, listAssets, getAssetDetails, or createAsset

Validation

• compile-time audit proving prometeu-studio and prometeu-app consume only API contracts
• packer regression tests for read and write flows
• Studio regression tests for asset list, asset details, and add asset flows
• targeted tests for mapper coverage between internal models and public API DTOs

Affected Artifacts

• prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**
• prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**
• prometeu-studio/src/main/java/p/studio/**
• prometeu-studio/src/test/java/p/studio/**