Skip to content

docs: freeze Infrastructure Atlas architecture gate - #271

Draft
Joncallim wants to merge 3 commits into
mainfrom
docs/epic-250-atlas-architecture
Draft

docs: freeze Infrastructure Atlas architecture gate#271
Joncallim wants to merge 3 commits into
mainfrom
docs/epic-250-atlas-architecture

Conversation

@Joncallim

@Joncallim Joncallim commented Sep 5, 2026

Copy link
Copy Markdown
Owner

Documentation-only architecture proposal for #250/#251 after repeated repo-grounded orthogonal review. No production behavior changes.

Files:

  • docs/architecture/INFRASTRUCTURE_ATLAS.md — implementation contract and issue spine.
  • docs/architecture/INFRASTRUCTURE_ATLAS_REVIEW.md — hostile review ledger, now extended through a second convergence sweep.

Second-sweep hardening added:

  • port/exposure semantics may not be inferred from opaque ContainerRecord.ports: string[];
  • semantic containment and presentation-only lanes are separate model/visual concepts;
  • inspection scope is not automatically host containment for external/runtime context nodes;
  • Docker/service/runtime representations may only be correlated/merged with proven canonical identity, never label similarity;
  • conflicting correlated facts need explicit source ownership/diagnostics, never last-write-wins;
  • Atlas must consume the existing generation/provenance/modelRevision-coherent model path rather than screen-level piecemeal topology fetches;
  • camera stability is now an independent contract so auto-fit cannot defeat logical layout stability;
  • global density/theme settings cannot re-anchor/reorder the Atlas;
  • canvas, directory/text alternative and inspector share one semantic selection/order authority;
  • aggregate/count language must preserve resolved/unresolved/ambiguous populations;
  • accessibility tests require deterministic keyboard order independent of SVG paint/insertion order.

Earlier key corrections remain:

  • current ContainerRecord has no Compose project identity: V1 cannot assume/infer project grouping;
  • semantic Atlas output excludes ephemeral publication revision/time from exact deterministic goldens;
  • collided visible occurrences need canonical presentation occurrence handling, never array-index routing identity;
  • structural stability is defined by mutation class;
  • Overview is orientation-first, not all-edges-first;
  • health, freshness, Findings attention and ambiguity remain orthogonal;
  • zero graphics/layout dependency is the baseline to beat;
  • global O(n²) layout work is unacceptable at the 250-object stress gate;
  • semantic/layout goldens, geometry tests and screenshots have separate authorities.

The second hostile convergence sweep produced no additional independent P1/P2 architecture class after these refinements. Remaining choices are deliberately authority/fixture driven (#259/#262/#252/#253/#257/#268/#261/#269), not implementation taste.

Keep draft until the maintainer accepts the architecture gate; no production renderer should start before #251 closes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant