light-heart-labs--dreamserver/ods/docs/COMPOSE_RESOLVER_CONTRACTS.md

Compose Resolver Contracts

ODS assembles its runtime from a base compose file, hardware overlays, mode overlays, and extension compose fragments. This document defines the expected contract so maintainers and forks can add services or backends without breaking unrelated install paths.

Compose Layer Model

The resolved stack is built from these layers:

1. Base stack: common networks, volumes, and core services.
2. Hardware overlays: NVIDIA, AMD/Lemonade, Apple Silicon, Intel Arc, CPU, or other backend-specific runtime settings.
3. Mode overlays: local, cloud, hybrid, external Lemonade, or other routing modes.
4. Extension fragments: enabled service compose.yaml files and optional GPU overlays.
5. Operator overrides: local environment variables and supported flags.

The resolver, installer, CLI, dashboard, and validation tests should agree on the same file set for a given mode and hardware class.

Resolver Rules

• Do not require users to hand-compose files for supported install modes.
• Do not make a compose fragment valid only by accident of local state.
• A service referenced by depends_on must exist in every resolved file set that includes that dependency.
• Optional services should be gated by install/profile state, not by relying on missing files.
• Host ports must be declared through the port contract where applicable.
• Internal container ports should stay stable unless every dependent service and generated config writer is updated.
• Hardware overlays should change runtime flags, devices, images, or build targets only for the relevant backend.

Adding A Service

Use the extension path unless the service is a core boot dependency.

Required files:

extensions/services/<service-id>/manifest.yaml
extensions/services/<service-id>/compose.yaml

Recommended validation:

python scripts/audit-extensions.py --project-dir . <service-id>
python scripts/audit-extensions.py --project-dir .
docker compose -f docker-compose.base.yml -f extensions/services/<service-id>/compose.yaml config

If the service needs GPU-specific runtime flags, add backend overlays in the service directory instead of modifying unrelated global overlays.

Adding A Backend Or Mode

When adding a backend or mode:

1. Define the backend contract or mode behavior.
2. Add the compose overlay.
3. Update installer detection and compose selection.
4. Update generated config writers.
5. Update dashboard-api service/status assumptions if needed.
6. Add resolver validation for the exact file set.
7. Add support matrix and validation docs.

Backends commonly touch more than compose. Model selection, service URLs, health checks, and dashboard diagnostics often need matching updates.

Dependency Placeholders

Sometimes a mode uses an external or native process where another compose layer expects a service name. If a placeholder is needed:

• document why it exists;
• avoid host port bindings when the placeholder never runs;
• keep health semantics honest;
• validate restart and reinstall behavior;
• prefer a ready-sidecar only when it checks a real external endpoint.

Placeholders should satisfy the compose dependency graph without claiming a container is doing work that actually happens elsewhere.

Port And Network Policy

• Default user-facing services should bind to localhost unless a LAN path is explicitly enabled.
• LAN and owner-card routes should use the documented proxy path.
• Internal service-to-service traffic should use container DNS and internal ports.
• Host-facing port defaults belong in config/ports.json and service manifests.
• Dashboard/API docs should match the actual auth and binding behavior.

Run the network exposure contract tests when changing host bindings or proxy routes.

Validation Commands

Use focused checks while developing:

python scripts/validate-golden-paths.py
python scripts/validate-generated-configs.py
python scripts/audit-extensions.py --project-dir .

Then validate representative compose sets for changed modes. For operational changes, use the release-grade gate described in RELEASE_VALIDATION.md.

Manual Compose Use

Manual compose commands are useful for debugging, but supported users should not need to know the full file set. If a doc shows a manual compose command, include all required base, mode, hardware, and extension files or point to the resolver.