Document D&D location tracking contracts

docs/integrations/dnd-location-artifacts.md

@@ -0,0 +1,89 @@
+# 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.