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:
26
docs/adr/0004-region-vs-plane.md
Normal file
26
docs/adr/0004-region-vs-plane.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user