Modularize Contained packages and backend architecture

[tdeverx]

Goal

Track the package, backend, database, and design-system architecture work needed to make Contained easier to maintain, reuse, test, and extend without losing the native macOS app experience.

Current status (July 18, 2026)

PR #48 is scope-complete and automated-review-ready at 99537804. The rebased PR and CodeQL workflows are green.

The current foundation is:

• ContainedCore owns backend orchestration under Core.*, including runtime descriptors/capabilities, canonical container/image/network/volume/metrics models, command previews, command execution, Compose import/export semantics, typed errors, semantic Core localization, migration planning/execution surfaces, and non-shipping fixture data.
• Shared runtime contracts and the built-in module registry live in Core Runtime/; concrete runtime behavior lives under Runtimes/AppleContainer and Runtimes/Docker.
• Apple container is the only default registered runtime for the app today. Docker adapter code, fixtures, and tests remain in place as dormant groundwork until Contained chooses an independent Docker provider/daemon model.
• ContainedApp owns SwiftUI screens, stores, routing, SwiftData app metadata persistence, product localization, Sparkle/update presentation, settings, personalization, Core-to-UI presentation mapping, and feature policy.
• App metadata is reset around the new SwiftData database; old live UserDefaults/SwiftData app metadata is ignored rather than migrated.
• Containers, images/tags, volumes, and networks carry runtime identity. Actions route through the owning runtime, and no stored/global active runtime remains.
• ContainedUI owns reusable visuals under UI.*, with package-internal Shared helpers for repeated implementation anatomy and colocated previews on element declarations.
• ContainedUX owns reusable interaction infrastructure under UX.*, including morphing, safe areas, source-frame measurement, panel placement, and single-surface behavior, with colocated previews.
• Sources/Contained is only the executable launcher.
• Repo automation now lives under Scripts/, maintained docs under Documentation/, and release deltas under Changes/.

ContainedRuntime, AppleContainerRuntime, ContainedDesignSystem, ContainedNavigation, and ContainedPreviewSupport are no longer standalone packages. ContainedCoreFixtures now lives as a Core fixture target/product for tests and previews only, and normal app/debug/release bundles do not link fixture modules.

Keep this parent open until PR #48 merges. Manual app/UI polish is deferred follow-up work and is not a merge gate.

Child issues

• Migrate Contained to an Xcode project/workspace #33
• Extract a reusable design system package #34
• Extract navigation, toolbar, panel, and morph infrastructure #35
• Design runtime backend abstraction and dormant Docker adapter #36

Research / design checklist

• Define the intended package/target boundaries before implementation begins.
• Decide which shared UI and navigation concepts are stable enough to extract.
• Decide how backend abstractions should represent Apple container, Docker-compatible behavior, and future runtimes.
• Sequence child issues so package extraction does not break the current SwiftPM release workflow or native Xcode development workflow.
• Decide how app-owned metadata resets into the runtime-first SwiftData database.

Implementation checklist

• Keep ContainedCore pure and testable.
• Extract shared UI and navigation concepts when the package boundary makes reuse clearer.
• Keep Apple container behavior stable while backend abstractions are introduced.
• Add native Xcode app/test/previews support without replacing SwiftPM release tooling.
• Keep docs/wiki and issue checklists aligned as package boundaries settle.
• Add runtime-first app metadata persistence and runtime-scoped resources.
• Add Docker adapter groundwork inside Core without enabling Docker as a default app runtime.
• Remove global active/default runtime behavior from app workflows.
• Colocate design-system/UX previews and factor repeated implementation anatomy into package-internal Shared helpers.
• Consolidate Scripts/Documentation/Changes so repo automation and docs match the package layout.

Acceptance criteria

• Package boundaries are documented before implementation begins.
• Each child issue has its own research/design checklist, implementation checklist, and acceptance criteria.
• Shared abstractions do not force SwiftUI into pure runtime packages.
• Existing app behavior remains covered by the appropriate verification loop.
• Xcode can build/run the app for functional SwiftUI development while SwiftPM remains the release path.
• Runtime adapters are implemented through Core modules rather than app-side switches.
• Runtime-scoped database records support same-name resources across runtimes.

Remaining follow-up

• Review and merge PR Runtime-first Core, persistence, and package boundary cleanup #48 when ready.
• Keep the deferred manual app/UI polish separate from this completed architecture scope.
• Keep optional app-owned OCI image caching tracked separately in Add optional app-owned OCI image cache #50.
• Track any future Contained-owned Docker provider/daemon work separately from this foundation issue.