Refine anchor-first universe migration docs

docs/UNIVERSE-MODEL.md

@@ -8,7 +8,7 @@ It is the canonical reference for:
 - solar systems
 - celestials
 - anchors
-- localspaces
+- localspaces as the tactical space around anchors
 - ship and station placement
 - intra-system travel
 - inter-system travel
@@ -27,14 +27,13 @@ The structure can be understood as a tree:
 - the galaxy contains solar systems
 - each solar system contains celestials and other derived locations
 - each meaningful location is an anchor
-- each anchor owns one localspace
+- each anchor has a localspace around it
 
 The intended structure is:
 
 1. `galaxy`
 2. `solar system`
 3. `anchor`
-4. `localspace`
 
 Ships and stations do not live in arbitrary free-floating "system local space".
 
@@ -99,7 +98,7 @@ Systems remain important for:
 
 ## Anchors
 
-An anchor is a meaningful object in a system that owns a localspace.
+An anchor is a meaningful object in a system.
 
 Anchors are first-class world entities.
 
@@ -120,7 +119,7 @@ Each anchor should have:
 - an anchor type
 - a position in system space
 - optional orbital metadata
-- an associated localspace definition
+- a localspace around it
 - optional parent/child relationships
 
 Examples:
@@ -131,7 +130,7 @@ Examples:
 - a resource node is an anchor but not a celestial
 - a Lagrange point can be the child of a moon, which is the child of a planet, which is the child of a star
 
-Every anchor has exactly one localspace.
+Every anchor has exactly one localspace around it.
 
 ## Celestials
 
@@ -147,9 +146,9 @@ Celestials exist for three reasons:
 
 1. they structure the solar system visually and strategically
 2. they define orbital relationships
-3. they provide valid anchors for localspaces and derived locations such as Lagrange points
+3. they provide valid anchors and derived locations such as Lagrange points
 
-Every star, planet, and moon gets a localspace.
+Every star, planet, and moon has a localspace around it.
 
 Not all anchors are celestials, but all celestials are anchors.
 
@@ -165,7 +164,7 @@ Initial assumptions:
 
 - major orbitals can expose `L1` through `L5`
 - each exposed Lagrange point is its own anchor
-- each exposed Lagrange point has its own localspace
+- each exposed Lagrange point has its own localspace around it
 - Lagrange points are valid construction sites
 
 For now, all five may exist for supported orbitals, but the intended direction is that only major planets should necessarily expose all five.
@@ -186,7 +185,7 @@ That means a resource node can have:
 
 - a stable identity
 - a place in a solar system
-- its own localspace
+- its own localspace around it
 
 This is desirable because it allows resources to exist anywhere meaningful in a system while still fitting the anchored localspace model.
 
@@ -212,7 +211,7 @@ Use:
 
 - `localspace`
 
-Each localspace belongs to exactly one anchor.
+Each localspace is the tactical space around exactly one anchor.
 
 Examples:
 
@@ -237,12 +236,12 @@ Ships and constructions do not exist directly in system space. They exist in one
 
 ## Ship Placement
 
-A ship always belongs to exactly one localspace unless it is actively transitioning between anchors.
+A ship always belongs to exactly one anchor unless it is actively transitioning between anchors.
 
 Normal ship state should be one of:
 
-- in a localspace
-- traveling between localspaces in the same system
+- at an anchor
+- traveling between anchors in the same system
 - traveling between systems
 
 Inside a localspace, ships use tactical movement with thrusters.
@@ -444,6 +443,82 @@ Localspace view should show:
 
 The viewer should not imply that the full solar system is one continuous local battlefield.
 
+Viewer zoom transitions are a client-side presentation effect.
+
+That means:
+
+- zooming from galaxy to system does not imply one shared coordinate space
+- zooming from system to localspace does not imply one shared coordinate space
+- the client may animate or blend between views for readability
+- those effects do not define simulation truth
+
+## Scales And Units
+
+Each spatial layer owns its own units.
+
+Those units should be native to that layer, not projections of one universal master coordinate system.
+
+### Galaxy
+
+The galaxy layer uses:
+
+- `light-years`
+
+This is the scale for:
+
+- system positions
+- inter-system distances
+- strategic map layout
+
+### System
+
+The system layer uses:
+
+- `AU`
+
+This is the scale for:
+
+- anchor positions inside a system
+- orbital relationships
+- intra-system routing and warp travel
+
+Variation at localspace scale is intentionally insignificant at this layer.
+
+### Localspace
+
+The localspace layer uses:
+
+- `meters`
+- `m/s`
+
+This is the scale for:
+
+- tactical movement
+- combat
+- docking
+- mining
+- construction
+
+Variation at system scale is intentionally insignificant at this layer.
+
+## Cross-Layer Rule
+
+The simulation should not try to preserve one continuous coordinate frame across galaxy, system, and localspace.
+
+Cross-layer relationships should be modeled through:
+
+- containment
+- references
+- travel state
+
+Not through:
+
+- universal coordinate conversion
+- raw projection of localspace offsets into system space
+- raw projection of system offsets into galaxy space
+
+The viewer may animate transitions between layers, but that is presentation only. It does not mean the simulation uses one continuous spatial frame.
+
 ## Ownership And Sovereignty
 
 Ownership and sovereignty should primarily be tracked at system level.
@@ -451,7 +526,7 @@ Ownership and sovereignty should primarily be tracked at system level.
 This is not fully defined yet, but the current design direction is:
 
 - systems are the main sovereignty unit
-- localspaces and constructions exist inside systems
+- anchors and constructions exist inside systems
 - local conflicts and control still matter tactically
 
 ## Simulation Implications
@@ -466,7 +541,7 @@ This model supports:
 
 It also gives a cleaner authority boundary for later scaling:
 
-- one localspace can become one simulation partition
+- one anchor can become one tactical simulation partition
 - one system can remain a higher-level strategic container
 
 This supports:
@@ -493,8 +568,8 @@ Until the implementation is updated, the following terms should be used consiste
 - `galaxy`: the top-level strategic star map
 - `system`: the solar system container
 - `celestial`: star, planet, or moon
-- `anchor`: anything that owns a localspace
-- `localspace`: the tactical simulation bubble attached to one anchor
+- `anchor`: a meaningful location in a system and the primary tactical simulation container
+- `localspace`: the tactical simulation space around an anchor, not a separately identified entity
 - `intra-system warp`: movement between anchors in the same system
 - `inter-system FTL`: movement between systems