Implement raw module output contracts

docs/integrations/dnd-spell-artifacts.md

@@ -1,91 +1,27 @@
-# D&D Spell-Cast Artifacts
+# D&D Spell Raw Output
 
-This document is the durable artifact contract for approved
-`dnd.spell_cast` artifacts produced by the implemented `dnd/spells` extractor.
+This document is the durable raw output contract for the implemented
+`dnd/spells` extractor.
 
-## Artifact Identity
+## Identity
 
 - Extractor key: `dnd/spells`
-- Artifact type: `dnd.spell_cast`
-- Schema version: `v1`
 - Prompt ID: `dnd.spells`
 - Response schema key: `dnd_spells`
 - Response schema ID: `notarius.dnd.spells`
 - Response schema name: `notarius_dnd_spells_v1`
+- Response schema version: `v1`
+- Media type: `application/json`
 
 The extractor requires source chunks and transcript source capability. It
-returns generic artifact candidates that are serialized by the JSON output
-module.
+returns the structured LLM response as raw JSON. The default `appendorder`
+merger passes a single chunk output through and wraps multiple chunk outputs in
+an ordered `outputs` array. The default `noop` normalizer passes the merge
+output through unchanged.
 
-The extractor accepts optional UTF-8 text references:
+## Output Shape
 
-- `roster`: campaign roster or player-character notes.
-- `glossary`: campaign glossary or spell/name notes.
-
-References are supporting disambiguation material only. They are not source
-evidence and are not addressable through `source_refs`.
-
-## Artifact Envelope
-
-Approved artifacts use the generic artifact envelope documented in
-[JSON Output](json-output.md#artifact-files):
-
-```json
-{
-  "extractor_key": "dnd/spells",
-  "artifact_type": "dnd.spell_cast",
-  "schema_version": "v1",
-  "payload": {
-    "caster": "Aria",
-    "spell": "Cure Wounds",
-    "effect": "heals an injured ally",
-    "narrative_description": "Aria raises her holy symbol and casts Cure Wounds."
-  },
-  "source_refs": [
-    {
-      "source_id": "session-alpha",
-      "start_unit_id": 1,
-      "end_unit_id": 1
-    }
-  ]
-}
-```
-
-## Payload Fields
-
-The `payload` object contains:
-
-- `caster`: in-world character or creature casting the spell;
-- `spell`: spell name;
-- `effect`: concise spell effect in the scene;
-- `narrative_description`: short description of the spell cast in context.
-
-All payload fields are strings and must be non-empty after trimming.
-
-`caster` is the in-world caster, not the transcript speaker.
-
-## Source References
-
-Source references live on the artifact envelope as `source_refs`; they are not
-duplicated inside the `payload`.
-
-Each source reference uses the generic source-reference shape:
-
-- `source_id`
-- `start_unit_id`
-- `end_unit_id`
-
-Validation requires:
-
-- at least one source reference;
-- non-empty source ID and positive unit IDs;
-- source ID matching the source document ID;
-- start and end unit IDs existing in the source document;
-- start unit appearing before or at the same position as end unit.
-
-## Structured LLM Response Shape
-
-The extractor asks the LLM for this top-level response shape:
+For a single chunk, `outputs/spells.json` has this shape:
 
 ```json
 {
@@ -109,31 +45,57 @@ The extractor asks the LLM for this top-level response shape:
 
 `spell_casts` must be present. It may be empty when no spell casts are found.
 
-The response schema asset is embedded at
-`internal/modules/extract/dnd/spells/assets/schemas/dnd_spells.v1.json`.
+For multiple chunks with the default merger, the lane output has this shape:
 
-## Validators
+```json
+{
+  "outputs": [
+    {
+      "chunk_id": "chunk-000001",
+      "chunk_index": 0,
+      "media_type": "application/json",
+      "content": {
+        "spell_casts": []
+      }
+    }
+  ]
+}
+```
 
-The extractor supplies two deterministic validators by default:
+## Spell-Cast Fields
 
-- `dnd/spells/shape`
-- `dnd/spells/source_refs`
+Each spell cast contains:
 
-Rejection reason codes:
+- `caster`: in-world character or creature casting the spell;
+- `spell`: spell name;
+- `effect`: concise spell effect in the scene;
+- `narrative_description`: short description of the spell cast in context;
+- `source_refs`: transcript source references supplied by the model.
 
-- `invalid_payload`: payload JSON cannot be decoded as a spell-cast payload.
-- `missing_required_field`: `caster`, `spell`, `effect`, or
-  `narrative_description` is blank.
-- `missing_source_ref`: candidate has no source references.
-- `invalid_source_ref`: at least one source reference fails generic source
-  reference validation.
+`caster` is the in-world caster, not the transcript speaker.
 
-Warning reason codes:
+## Source References
 
-- `spell_not_near_source`: the extracted spell name was not found in the cited
-  source text.
+Each source reference uses the generic source-reference shape:
 
-Rejected candidates are written to `rejected.json` by the JSON output module.
+- `source_id`
+- `start_unit_id`
+- `end_unit_id`
+
+The extractor prompt and schema use integer `start_unit_id` and `end_unit_id`
+values matching source-unit IDs.
+
+## References
+
+The extractor accepts optional UTF-8 text references:
+
+- `players`
+- `party`
+- `glossary`
+- `roster`, a deprecated compatibility alias for `party`
+
+References are supporting disambiguation material only. They are not source
+evidence and are not addressable through `source_refs`.
 
 ## Manifest Metadata
 
@@ -158,8 +120,3 @@ manifest metadata:
 ```
 
 Raw prompt and schema content are not included in manifest metadata.
-
-## Compatibility Limit
-
-This contract covers only `dnd.spell_cast` artifacts produced by the
-implemented spell-cast extractor.