feat(worldgraph): add atlas graph metadata skeleton

[100yenadmin]

Summary

Adds the first clean-room WorldGraph skeleton for issue #175.

This PR is intentionally a small draft slice: it creates additive engine-owned graph metadata and projects it through the Atlas read model. It does not import Azgaar, does not add a map generator, and does not make graph edges a second travel authority.

Refs #175, #60, #117.

What Changed

• Added additive engine models:
  • WorldGraph
  • WorldGraphNode
  • WorldGraphEdge
• Added optional Campaign.world_graph metadata.
• seed_world() now loads optional world_graph metadata and skips malformed or unauthorized refs.
• Graph edges are accepted only when they describe an already-canonical Location.connections route.
• /atlas-surface now projects route kind, difficulty, danger, biome, terrain, graph tags, and graph-provided travel minutes when available.
• Added focused engine and viewer tests for safe seeding, hidden-route suppression, and Atlas projection.

Architecture Boundary

Campaign.locations and Location.connections remain canonical. WorldGraph cannot create locations and cannot authorize travel. Viewer/OpenWorlds may render the graph and post player intent through /move, but it must not write graph nodes, graph edges, discovery, travel state, or strategic clocks.

External Research

Azgaar/Fantasy-Map-Generator is reference-only. Useful concepts are route classes, graph metadata, terrain/biome tags, and travel-cost thinking. This PR does not vendor Azgaar UI, save format, map assets, generated geometry, or runtime dependencies.

Validation

Run from /Volumes/LEXAR/repos/ClawDnD-worldgraph-skeleton:

uv run --directory servers/engine --group dev pytest -q tests/test_content.py::test_seed_world_seeds_world_graph_metadata_without_authorizing_travel
python3 -m unittest viewer.tests.test_atlas_surface -q
python3 -m py_compile viewer/server.py
uv run --directory servers/engine python -m py_compile models.py content.py
git diff --check

Draft Notes

This is visible early by design. Follow-up review should decide whether the next slice belongs in travel return payloads, wander/danger weighting, OpenWorlds map rendering, or content schema docs.

Rollback Plan

Revert this PR to remove the optional metadata and Atlas fields. Existing campaigns without world_graph are unaffected because every field is additive.

Summary by CodeRabbit

• New Features

  • Added world graph metadata for map and travel displays, including biome, terrain, danger levels, and route information.
  • World graph data is validated against existing locations and does not unlock hidden content.

• Tests

  • Added regression tests to verify world graph metadata validation and projection.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 15cb0e27-e515-4102-85e9-1daf4b77dfa2

📥 Commits

Reviewing files that changed from the base of the PR and between 10b0541 and 12019b3.

📒 Files selected for processing (5)

• servers/engine/content.py
• servers/engine/models.py
• servers/engine/tests/test_content.py
• viewer/server.py
• viewer/tests/test_atlas_surface.py

Cache: Disabled due to Reviews > Disable Cache setting

---

📝 Walkthrough

Walkthrough

This PR adds a world-graph metadata layer: new Pydantic node/edge/container models stored on Campaign, seeding that validates and attaches optional world_graph from world.json (filtering non-canonical entries), and viewer projection helpers that merge node/edge metadata into atlas locations, edges, and travel options without enabling new movement.

Changes

World Graph Metadata Enrichment

Layer / File(s)	Summary
World Graph Data Models servers/engine/models.py	WorldGraphNode, WorldGraphEdge, and WorldGraph Pydantic models define atlas/travel metadata tied to existing locations/connections. Campaign.world_graph persisted field added with default_factory=WorldGraph.
World Graph Seeding and Validation servers/engine/content.py, servers/engine/tests/test_content.py	Adds imports and _seed_world_graph() which validates/constructs a WorldGraph from world['world_graph'] if present, filters nodes to existing Campaign.locations and edges to canonical Location.connections, logs skipped malformed/non-canonical entries, and wires the hook into seed_world(). Regression test verifies filtering and absence of unauthorized travel wiring.
Atlas Surface Projection and Enrichment viewer/server.py, viewer/tests/test_atlas_surface.py	Viewer helpers read snapshot["world_graph"], _atlas_known_locations merges node fields (biome, terrain, danger, atlas_layer, graph_tags), _atlas_edges now accepts snapshot and attaches edge payloads, and _atlas_travel_options uses edge metadata (route_kind, difficulty, danger, tags) with minutes fallback. Integration test ensures hidden locations/routes remain excluded from output.

Sequence Diagram(s)

sequenceDiagram
  participant World as world.json
  participant Seed as seed_world()
  participant Validate as _seed_world_graph()
  participant Campaign as Campaign

  World->>Seed: world dict
  Seed->>Validate: (campaign, world)
  Validate->>Validate: validate/construct WorldGraph, filter nodes
  Validate->>Validate: validate/construct edges, filter non-canonical
  Validate->>Campaign: attach validated WorldGraph to campaign.world_graph

Loading

sequenceDiagram
  participant Snapshot as snapshot
  participant Build as build_atlas_surface()
  participant Locations as _atlas_known_locations()
  participant Edges as _atlas_edges()
  participant Travel as _atlas_travel_options()
  participant Surface as atlas output

  Snapshot->>Build: snapshot dict
  Build->>Locations: enrich each visible location with node metadata
  Locations->>Surface: known_locations with biome/terrain/danger/atlas_layer/tags
  Build->>Edges: provide snapshot to _atlas_edges
  Edges->>Surface: edges with attached edge payload (route_kind,difficulty,danger,tags,minutes)
  Build->>Travel: _atlas_travel_options uses edge payload
  Travel->>Surface: travel_options with minutes fallback and route attributes

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly Related Issues

• #175: Directly related — implements/requests the WorldGraph models, seeding, and viewer projection that this PR adds.

Possibly Related PRs

• 100yenadmin/ClawDnD#130: Modifies viewer atlas-surface projection; likely related to the viewer-side integration of world-graph metadata.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}