ARCADIA-Studio/harness/release-port-migration.md

Typed port migration, source and API handoff

Implemented in codex/typed-port-contracts, isolated worktree D:/CodexWorktrees/Capella2-typed-ports, against the frozen port contract.

• Private V2 DTO, source reader and validation snapshot captured from c20a207. V1 normalizes to that DTO, then follows the same V2-to-3 adapter.
• Existing port identity/prose/ownership/placement and interface associations survive as Legacy. Missing FE endpoints receive deterministic item-bearing typed ports; old boundary exchanges explicitly retain oriented = true.
• Generated identities are collision checked across all object categories; aliases use the existing deterministic convention. Original admission limits remain intact, with generated records and references charged before creation.
• persistence::{decode_with_report, decode_with_report_limited, load_with_report} and language::{parse_with_report, parse_with_report_limited} return DecodeResult { project, migration }. Existing Project-only wrappers remain. Desktop integration should use the report-returning calls to display the migration findings. Merely loading never writes or advances a revision.
• Source 3 requires a port contract and both explicit FE port aliases. Item declarations and nested legacy.interface use normal source references. Canonical output is schema 3 / arcadia 3; source 1/2 remain importable.
• REST import, replacement, candidate validation and project snapshots surface reports. Reopened V2 envelopes retain resource/revision/bytes until a real edit. Reports are transient response metadata, excluded from persisted envelopes. Raw model JSON is preserved through request/envelope parsing so duplicate-map detection cannot be bypassed. Invalid typed transactions retain disk and ETag.
• Language/OpenAPI documents include typed contracts, PortAllocation, explicit endpoint IDs, independent orientation, Legacy and strict Standard/Flow kind mismatch rejection. Original V2 goldens and worked-example files are untouched.

Validation: 16 language, 8 migration, 3 typed source and 4 existing admission tests pass. The HTTP suite has 19 passing tests, including migration/restart and rejected typed transaction coverage. Core+server Clippy with all targets and -D warnings passes. Server unit/doc checks are included in final verification.

Native GUI acceptance and report presentation remain root integration work; this handoff makes no native-UI or broad R3 completion claim.