# 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-15-snapshot-backed-asset-query-services.md)
- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md)
- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md)
- [`./PR-18-legacy-service-retirement-and-regression-hardening.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/**`

