#250 child: Reconcile Atlas design with current contracts and avoid aesthetic backend expansion

[Joncallim]

Parent: #250. Architecture finding from repo review.

Current ContainerRecord exposes id/name/role/image/status/ports/networks/mounts/dependsOn but does not expose Compose project identity. The Atlas must not pretend project grouping is currently available or add backend contract scope merely to satisfy a preferred picture.

Before #251 closes, inventory exactly which grouping/relationship/exposure/storage/runtime facts are available from SystemModel, DockerSnapshot, RuntimeMap, /api/graph, and Compose surfaces. For each proposed Atlas object, record the authoritative source and whether it has explicit evidence refs or needs a bounded source-reference form.

Mandatory authority questions

Project/group identity

V1 must degrade cleanly to provider/layer/ungrouped subjects when project identity is absent. Any future project grouping requires a separately justified truthful contract change, not name/image inference.

Semantic containment vs presentation lanes

A box/region visually containing a subject is itself a semantic claim unless the grammar explicitly marks it as presentation-only. Freeze two distinct concepts:

• semantic group/containment — allowed only where a source proves membership/containment;
• presentation lane/region — deterministic organisational scaffolding with no containment/ownership meaning.

They must have different model types and visibly different treatment. A renderer may never turn a presentation lane into an AtlasGroup merely because it looks cleaner.

Inspection scope / host boundary

Do not assume every runtime node belongs inside the inspected host. Runtime contracts can represent external APIs, tailnet/network entities, DNS/provider context and other off-host subjects. A host/scope boundary may contain only subjects whose source establishes that placement. Unresolved/off-host/context subjects remain outside or in a clearly non-containment context region. Never infer runs on host from the fact DockerMap discovered a node while inspecting that host.

Host-published exposure

ContainerRecord.ports is currently only string[]. Do not promote a display string into stronger Atlas semantics such as host-published, external, bind-address scope, or protocol unless the authority audit proves a structured canonical source and a closed parser/adapter contract. If only opaque strings are available, expose them as observed port text/context and omit stronger boundary/exposure claims.

Cross-source entity correlation

Docker/service records and runtime-map nodes may describe the same underlying container/service/listener from different providers/surfaces. The Atlas must not double-render one thing as two primary subjects merely because two sources expose it, and must not merge two records merely because names look similar.

Freeze an explicit correlation rule:

• merge/unify only with a canonical collision-safe identity or explicit backend correlation that proves equivalence;
• otherwise retain separate source-scoped subjects/context with visible provenance;
• never correlate by fuzzy label/name/image matching;
• relation/membership deduplication across sources requires proven semantic equivalence, not matching endpoints alone.

Source precedence and disagreement

If two authoritative surfaces disagree about the same correlated fact, do not silently choose whichever arrives last. Define source ownership/precedence per field or preserve the disagreement as a diagnostic. The Atlas is a projection, not a reconciliation engine that invents truth.

Projection input boundary

Decide the Atlas projection input boundary: SystemModel is convenient but includes heuristic service classification and loses some raw provenance shape; raw canonical contracts carry stronger evidence but need web adaptation. Freeze the narrowest input that preserves truth/provenance without duplicating backend semantics.

useSystemModel already gates DockerSnapshot and RuntimeMap on generation, provenance, and the same non-empty modelRevision; Atlas must consume one coherent published model/envelope and must not add independent screen-level fetches that can reintroduce split-revision topology.

Closure requires an authority/correlation matrix with explicit supported, context-only, unsupported, and requires-contract-change outcomes for every planned Atlas semantic.