docs(plan,adr): slice 6 migration distinguishes Region from Plane

ADR 0004: a Region is geographic (inside a plane); a Plane is a
mode of existence (Material, Shadow, Voldramir). The v1.1 codex
conflates them under 'type: region'; the slice 6 migration fixes
this.

Migration rules:
  - Entries with plane: true in frontmatter -> Plane node
  - Entries under Campaign Codex - Planes/ -> Plane node
  - All others -> Region node
  - Migration is idempotent
  - Default plane for an entity with no plane: -> Material Plane

Voldramir becomes a Plane node; its body-text [[Underdark]]
reference becomes a LAYER_OF edge. Added criteria 6.8-6.11.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-06-17 18:58:13 -04:00
parent f24b638a33
commit b8dcc13585
2 changed files with 42 additions and 5 deletions

View File

@@ -0,0 +1,26 @@
# Region and Plane are different node labels
**Status:** accepted.
A `Region` is a *geographic* concept — a continent, kingdom,
forest, dungeon, anything that exists *inside* a plane. The
`PART_OF` edge between two `Region` nodes means "geographically
contains" (a kingdom is `PART_OF` a continent).
A `Plane` is a *mode of existence* — the Material Plane, a
Shadow Plane, a demiplane, Voldramir, the Feywild. The plane-
relation edge types (`REFLECTS`, `LAYER_OF`, `ADJACENT_TO`,
`ACCESSIBLE_VIA`) are between `Plane` nodes.
The codex migration in slice 6 distinguishes the two by reading
frontmatter (`plane: true`) or path (`Campaign Codex - Planes/`)
and emitting the correct node label. Entries that don't say
either become `Region` nodes, not `Plane` nodes. The migration
is idempotent.
The v1.2 model fixes a real bug in the v1.1 codex where
"Voldramir" was a `Region` with body text saying "a vast
darkness pit plane beneath the Underdark" — that conflates
geography and ontology. After the slice 6 migration, Voldramir
is a `Plane` node and its relationship to Underdark is a
`LAYER_OF` edge, not a body-text `[[Underdark]]` wikilink.

View File

@@ -21,12 +21,19 @@ types. Multi-setting queries, planar relationships, and the
- `LAYER_OF` — Plane A is a layer of Plane B
- `ADJACENT_TO` — Plane A is adjacent to Plane B
- `ACCESSIBLE_VIA` — Plane A is reachable via (Route/Portal)
5. Backfill migration: every existing `Person`, `Faction`, `Location`,
`Region` node gains `setting_id` and `plane_id` (default to a
single setting if `world_id` is the v1.1 legacy column).
6. Query path: `Setting` filter on every read tool; `EXISTS_IN`
5. **Migration script** that reads the codex frontmatter and
distinguishes `Region` from `Plane` correctly. Entries with
`plane: true` in frontmatter (or whose path is under
`Campaign Codex - Planes/`) become `Plane` nodes, not
`Region`. The migration is idempotent.
6. **Backfill of `EXISTS_IN` edges.** Every entity that is *in*
a plane (Person, Faction, Location, Region) gets one
`EXISTS_IN` edge to the appropriate `Plane` node. The default
plane is the Material Plane of the default `Setting` if no
`plane:` is specified in frontmatter.
7. Query path: `Setting` filter on every read tool; `EXISTS_IN`
traversal for plane-scoped queries.
7. Documentation updates in `docs/11-extensibility.md` and
8. Documentation updates in `docs/11-extensibility.md` and
`docs/14-examples.md` to use `setting_id` instead of `world_id`.
## Acceptance criteria
@@ -40,6 +47,10 @@ types. Multi-setting queries, planar relationships, and the
| 6.5 | `was_true_at` queries can be filtered by `setting` |
| 6.6 | Cross-setting queries work via `Setting` filter |
| 6.7 | `docs/` no longer references `world_id` outside the migration section |
| 6.8 | Migration distinguishes `Region` (geographic, inside a plane) from `Plane` (mode of existence); entries with `plane: true` or path under `Campaign Codex - Planes/` become `Plane` nodes, not `Region` |
| 6.9 | Migration is idempotent: running twice produces the same graph (no duplicate `Setting`, `Plane`, or `EXISTS_IN` nodes/edges) |
| 6.10 | Default plane for an entity with no explicit `plane:` is the Material Plane of the default `Setting` |
| 6.11 | Voldramir (currently `type: region` in the codex) becomes a `Plane` node in the v1.2 graph; its body-text `[[Underdark]]` reference becomes a `LAYER_OF` edge |
## Test plan