notarius/docs/integrations/dnd-scene-description-artifacts.md

D&D Scene-Description Artifact

This contract defines the durable output of dnd/scene-descriptions. Each record classifies one accepted transcript chunk and gives it a minimal source-grounded title and summary.

Identity and compatibility

Property	Value
Artifact kind	dnd/scene-description-list
Schema ID	notarius.dnd.scene_descriptions
Schema name	notarius_dnd_scene_descriptions_v1
Schema version	v1
Media type	application/json

v1 is a strict JSON object with required non-empty scenes. Scene and source-reference objects reject unknown fields. An incompatible shape change requires a new schema version.

Wire shape

Each scene has exactly these required fields:

Field	Contract
id	Non-empty accepted chunk ID, assigned by Notarius.
source_ref	The assigned inclusive source range for that chunk.
kind	combat, narrative, recap, or meta.
title	Non-empty, trimmed, source-grounded title.
summary	Non-empty, trimmed, source-grounded summary.

source_ref has exactly source_id, start_unit_id, and end_unit_id. Its source ID identifies the input transcript; its positive unit IDs identify the chunk's inclusive range, with the start no later than the end.

{
  "scenes": [
    {
      "id": "chunk-000001",
      "source_ref": {"source_id": "session-7", "start_unit_id": 1, "end_unit_id": 3},
      "kind": "narrative",
      "title": "Arrival at the watchtower",
      "summary": "The party reaches the ruined watchtower and begins to investigate it."
    }
  ]
}

Meaning and normalized form

combat identifies a chunk where active combat is the central activity. narrative is current in-world play that is not principally combat, recap, or meta discussion. recap is primarily a recounting of an earlier session, and meta is primarily out-of-character discussion. The artifact does not add participants, confidence, events, or information absent from the chunk.

Normalization trims title and summary, orders scenes by source position and then ID, and removes exact duplicate records. A reused ID with different durable fields, or the same source range with different kind, title, or summary, is invalid. It does not merge adjacent ranges, alter prose, or infer missing scenes.

The combat-turn artifact and enemy-event artifact use an exact matching combat scene only as eligibility control; scene title, summary, and source reference never become their evidence. Publication is defined by the JSON output contract; implementation details live in D&D module internals.