94 lines
3.9 KiB
Markdown
94 lines
3.9 KiB
Markdown
# D&D Location Registry Artifact
|
|
|
|
This contract defines the durable, source-grounded location registry produced
|
|
by `dnd/location-registry`. 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-registry` |
|
|
| Schema ID | `notarius.dnd.location_registry` |
|
|
| Schema name | `notarius_dnd_location_registry_v1` |
|
|
| Schema version | `v1` |
|
|
| Media type | `application/json` |
|
|
| Identity policy | `dnd.location_registry.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:fb05475da0fc7debf994b517e1906ffe7209887a6a1ec306356d84de820b1a24",
|
|
"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.location_registry.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 with a
|
|
stable proper name or unique in-world designation, such as named planes,
|
|
regions, settlements, districts, buildings, rooms, landmarks, routes, and
|
|
geographic features. Generic, temporary, relative, and descriptive phrases
|
|
such as “the room,” “the bar,” “the hallway,” “outside,” and “upstairs” are not
|
|
registry locations. Capitalization alone does not establish eligibility.
|
|
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
|
|
`location_registry` reference slot. Its prompt receives contextual selectors
|
|
containing a canonical name and registry references; Notarius resolves a
|
|
selection into the unchanged exact durable ID/name pair. Registry references
|
|
must not be treated 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.
|