85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
# D&D Location-Occurrence Artifact
|
|
|
|
This contract defines the durable occurrence list produced by
|
|
`dnd/location-occurrences`. It records source-grounded ways the party relates
|
|
to locations in a required normalized location registry; it does not extend
|
|
that registry or infer a place absent from it.
|
|
|
|
## Identity and compatibility
|
|
|
|
| Property | Value |
|
|
| --- | --- |
|
|
| Artifact kind | `dnd/location-occurrence-list` |
|
|
| Schema ID | `notarius.dnd.location_occurrences` |
|
|
| Schema name | `notarius_dnd_location_occurrences_v1` |
|
|
| Schema version | `v1` |
|
|
| Media type | `application/json` |
|
|
|
|
`v1` accepts one strict JSON object with required `occurrences`; the array may
|
|
be empty. Occurrence and source-reference objects reject unknown fields. An
|
|
incompatible shape change requires a new schema version.
|
|
|
|
## Wire shape
|
|
|
|
Each occurrence has these required fields:
|
|
|
|
| Field | Contract |
|
|
| --- | --- |
|
|
| `location_id` | Exact ID from the required normalized [location registry](dnd-location-registry-artifacts.md). |
|
|
| `name` | Exact canonical display name for `location_id` in that registry. |
|
|
| `kind` | One of `visited`, `planned`, `recalled`, or `mentioned`. |
|
|
| `source_refs` | One or more current-transcript evidence ranges for this occurrence. |
|
|
|
|
A source reference has exactly `source_id`, `start_unit_id`, and `end_unit_id`.
|
|
It identifies an inclusive range in the current transcript; unit IDs are
|
|
positive and the start may not follow the end.
|
|
|
|
```json
|
|
{
|
|
"occurrences": [
|
|
{
|
|
"location_id": "location:sha256:fb05475da0fc7debf994b517e1906ffe7209887a6a1ec306356d84de820b1a24",
|
|
"name": "Moon Gate",
|
|
"kind": "visited",
|
|
"source_refs": [
|
|
{"source_id": "session-7", "start_unit_id": 12, "end_unit_id": 13}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Occurrence categories
|
|
|
|
| Kind | Meaning |
|
|
| --- | --- |
|
|
| `visited` | The transcript establishes physical party presence, including arrival, continuing presence, or departure. |
|
|
| `planned` | The party explicitly proposes, intends, or agrees to future travel; speculation alone is not enough. |
|
|
| `recalled` | The transcript explicitly recounts prior party presence before the current live events. |
|
|
| `mentioned` | The location is explicit but no stronger category applies, including lore, directions, third-party activity, non-actionable speculation, a mere hypothetical reference, or out-of-character discussion. |
|
|
|
|
For overlapping evidence, precedence is `visited`, then `planned`, then
|
|
`recalled`, then `mentioned`. For example, “What if we went to Moon Gate?” is
|
|
eligible as `mentioned` when its narrow evidence explicitly references that
|
|
registry location, but it is not `planned` without an actual proposal,
|
|
intention, or agreement to travel. Inferred, unstated, uncertain, and
|
|
unsupported places or occurrences are omitted. Normalization
|
|
canonicalizes the registry name, orders and deduplicates source references, and
|
|
orders occurrences by source chronology, location ID, name, kind, and reference
|
|
sequence. It collapses only exact duplicates with the same ID, kind, and
|
|
complete canonical evidence sequence.
|
|
|
|
## Required grounding and evidence
|
|
|
|
Both extraction and normalization require exactly one `location_registry` reference of
|
|
kind `dnd/location-registry`, media type `application/json`, and at most 1 MiB. The
|
|
registry provides identity grounding only: unknown IDs and mismatched ID/name
|
|
pairs are rejected rather than guessed or reassigned. The current transcript is
|
|
the only evidence source for an occurrence; registry evidence and provenance
|
|
never become occurrence evidence.
|
|
|
|
See [Configuration](../config.md#d-d-reference-slots) for the selectable slot
|
|
and generated-handoff compatibility, [D&D module internals](../internal/dnd.md)
|
|
for implementation behavior, and the [JSON output contract](json-output.md)
|
|
for publication.
|