notarius/docs/integrations/dnd-location-occurrence-artifacts.md

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.
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.

{
  "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 for the selectable slot and generated-handoff compatibility, D&D module internals for implementation behavior, and the JSON output contract for publication.