90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# D&D Location Artifact
|
|
|
|
This contract defines the durable, source-grounded location registry produced
|
|
by `dnd/locations`. It records transcript-established physical places for one
|
|
source document; it is not a map, location hierarchy, campaign-wide world
|
|
registry, or location description.
|
|
|
|
## Identity and compatibility
|
|
|
|
| Property | Value |
|
|
| --- | --- |
|
|
| Artifact kind | `dnd/location-list` |
|
|
| Schema ID | `notarius.dnd.locations` |
|
|
| Schema name | `notarius_dnd_locations_v1` |
|
|
| Schema version | `v1` |
|
|
| Media type | `application/json` |
|
|
| Identity policy | `dnd.locations.identity.v1` |
|
|
|
|
`v1` accepts one strict JSON object with required `locations`; the array may be
|
|
empty. Location and source-reference objects reject unknown fields. An
|
|
incompatible artifact shape or identity-policy change uses a new version or
|
|
policy.
|
|
|
|
## Wire shape and identity
|
|
|
|
Each location has these required fields:
|
|
|
|
| Field | Contract |
|
|
| --- | --- |
|
|
| `id` | `location:sha256:` followed by 64 lowercase hexadecimal characters. |
|
|
| `name` | Non-empty transcript-established display name. |
|
|
| `source_refs` | One or more transcript evidence ranges that identify the place. |
|
|
|
|
A source reference has exactly `source_id`, `start_unit_id`, and `end_unit_id`.
|
|
The source ID identifies the transcript, unit IDs are positive inclusive unit
|
|
identifiers, and the start may not follow the end.
|
|
|
|
```json
|
|
{
|
|
"locations": [
|
|
{
|
|
"id": "location:sha256:5c1a91f15729df0b8c257093865fdf2452b43c215375e8cf2341aa9c37bb99aa",
|
|
"name": "Moon Gate",
|
|
"source_refs": [
|
|
{"source_id": "session-7", "start_unit_id": 4, "end_unit_id": 5}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
The ID is deterministic and scoped to the source document. Notarius normalizes
|
|
the display name for comparison with Unicode NFKC, supported apostrophe
|
|
normalization, collapsed whitespace, and case folding. It hashes compact JSON
|
|
for this array, using the earliest canonical source reference as the anchor:
|
|
|
|
```text
|
|
["dnd.locations.identity.v1", comparison_name, source_id, start_unit_id, end_unit_id]
|
|
```
|
|
|
|
The canonical ID is the lowercase SHA-256 digest of those bytes with the
|
|
`location:sha256:` prefix. Equal display names are allowed when their evidence
|
|
anchors differ, so a generic name does not force distinct places to collapse.
|
|
|
|
## Scope, reconciliation, and evidence
|
|
|
|
Locations are physical or spatial places established by the transcript, such
|
|
as planes, regions, settlements, districts, buildings, rooms, landmarks,
|
|
routes, and geographic features. A generic label is permitted only when it
|
|
identifies a specific place in the transcript. Notarius does not infer an
|
|
unstated place or add hierarchy, coordinates, descriptions, participants, or
|
|
ownership.
|
|
|
|
Normalization first applies deterministic display, evidence, and ID rules. It
|
|
then may use a bounded LLM-assisted proposal to reconcile semantically duplicate
|
|
records. The proposal is validated and applied conservatively; invalid or
|
|
unusable proposals retain the deterministic result with retry or fallback
|
|
diagnostics. The registry's source references establish registry provenance,
|
|
not evidence for later artifacts.
|
|
|
|
## Consumers and publication
|
|
|
|
`dnd/location-occurrences` requires one approved location registry through its
|
|
`locations` reference slot. Its prompt receives an ordered source-free `{id,
|
|
name}` projection and must not treat registry references as occurrence
|
|
evidence. See the [location-occurrence artifact](dnd-location-occurrence-artifacts.md)
|
|
for that contract, [Configuration](../config.md#references-and-ordered-handoffs)
|
|
for binding rules, and the [JSON output contract](json-output.md) for
|
|
publication.
|