Document accepted chunk map export

internal/cli/production_contract_test.go

@@ -18,6 +18,7 @@ import (
 
 	"gitea.maximumdirect.net/eric/notarius/internal/core/artifacts"
 	"gitea.maximumdirect.net/eric/notarius/internal/core/config"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/chunkmap"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
 	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
@@ -481,6 +482,42 @@ func TestProductionSceneRunRecordsChunkerWarningsAndProvenance(t *testing.T) {
 	if got := manifest.ChunkPlan.ProducerMetadata["response_schema_id"]; got != scenes.ResponseSchemaID {
 		t.Fatalf("chunk producer schema metadata = %#v, want %q", got, scenes.ResponseSchemaID)
 	}
+	index := readProductionJSON[productionChunkMapIndex](t, filepath.Join(outputRoot, productionRunID, "index.json"))
+	if index.ChunkMap == nil || index.ChunkMap.ArtifactKind != chunkmap.ArtifactKind || index.ChunkMap.File != "chunk-map.json" || index.ChunkMap.MediaType != chunkmap.MediaType || index.ChunkMap.SchemaID != chunkmap.SchemaID || index.ChunkMap.SchemaName != chunkmap.SchemaName || index.ChunkMap.SchemaVersion != chunkmap.SchemaVersion {
+		t.Fatalf("chunk map index = %#v, want fixed chunk map descriptor", index.ChunkMap)
+	}
+	for _, output := range index.OutputFiles {
+		if output.File == index.ChunkMap.File {
+			t.Fatalf("lane output files = %#v, want no chunk map", index.OutputFiles)
+		}
+	}
+	content, err := os.ReadFile(filepath.Join(outputRoot, productionRunID, index.ChunkMap.File))
+	if err != nil {
+		t.Fatal(err)
+	}
+	chunkMap, err := chunkmap.New().Decode(content)
+	if err != nil {
+		t.Fatalf("Decode(chunk map) error = %v", err)
+	}
+	if chunkMap.SourceID != "session-alpha" || chunkMap.SourceDigest != manifest.ChunkPlan.SourceDigest || chunkMap.PlanDigest != manifest.ChunkPlan.PlanDigest || chunkMap.RequestedChunker != scenes.Key || chunkMap.Producer.InputModule != "seriatim" || chunkMap.Producer.ChunkModule != scenes.Key || chunkMap.Producer.LLMProfile != manifest.ChunkPlan.ProducerLLMProfile {
+		t.Fatalf("chunk map identity and producer = %#v, want accepted scene plan provenance", chunkMap)
+	}
+	if len(chunkMap.Chunks) != 1 || chunkMap.Chunks[0].ID != "chunk-000001" || chunkMap.Chunks[0].Index != 0 || chunkMap.Chunks[0].SourceRef.SourceID != "session-alpha" || chunkMap.Chunks[0].SourceRef.StartUnitID != 1 || chunkMap.Chunks[0].SourceRef.EndUnitID != 2 || chunkMap.Chunks[0].UnitCount != 2 {
+		t.Fatalf("chunk map chunks = %#v, want one stable accepted scene range", chunkMap.Chunks)
+	}
+	var planAnnotation struct {
+		BoundaryCaveats []string `json:"boundary_caveats"`
+	}
+	if err := json.Unmarshal(chunkMap.PlanAnnotations["dnd/scenes"], &planAnnotation); err != nil || len(planAnnotation.BoundaryCaveats) != 1 {
+		t.Fatalf("chunk map plan annotation = %s, %v; want scene caveat", chunkMap.PlanAnnotations["dnd/scenes"], err)
+	}
+	var rangeAnnotation struct {
+		ShortTitle  string `json:"short_title"`
+		PrimaryMode string `json:"primary_mode"`
+	}
+	if err := json.Unmarshal(chunkMap.Chunks[0].Annotations["dnd/scenes"], &rangeAnnotation); err != nil || rangeAnnotation.ShortTitle != "Opening scene" || rangeAnnotation.PrimaryMode != "Narrative" {
+		t.Fatalf("chunk map range annotation = %s, %v; want surviving scene annotation", chunkMap.Chunks[0].Annotations["dnd/scenes"], err)
+	}
 	warnings := readProductionJSON[struct {
 		Warnings []contracts.Warning `json:"warnings"`
 	}](t, filepath.Join(outputRoot, productionRunID, "warnings.json"))
@@ -507,6 +544,7 @@ func maintainedExampleFiles(t *testing.T) []maintainedExample {
 		{name: "combat", path: repositoryPath("examples", "dnd-combat-turns.config.yml"), pipelineIDs: []string{"dnd-combat"}},
 		{name: "npc-grounded", path: repositoryPath("examples", "dnd-npc-grounded.config.yml"), pipelineIDs: []string{"dnd-npc-grounded"}},
 		{name: "npc-interactions", path: repositoryPath("examples", "dnd-npc-interactions.config.yml"), pipelineIDs: []string{"dnd-npc-interactions"}},
+		{name: "scene-chunk-map", path: repositoryPath("examples", "dnd-scene-chunk-map.config.yml"), pipelineIDs: []string{"dnd-scene-chunk-map"}},
 	}
 }
 
@@ -588,12 +626,30 @@ pipelines:
   dnd-session:
     input: seriatim
     chunk: %s
+    output:
+      module: json
+      options:
+        include_chunk_map: true
     artifacts:
       spells:
         extract: dnd/spells
 `, outputRoot, filepath.Join(filepath.Dir(outputRoot), "debug"), chunkModule)
 }
 
+type productionChunkMapIndex struct {
+	OutputFiles []struct {
+		File string `json:"file"`
+	} `json:"output_files"`
+	ChunkMap *struct {
+		ArtifactKind  contracts.ArtifactKind `json:"artifact_kind"`
+		File          string                 `json:"file"`
+		MediaType     string                 `json:"media_type"`
+		SchemaID      string                 `json:"schema_id"`
+		SchemaName    string                 `json:"schema_name"`
+		SchemaVersion string                 `json:"schema_version"`
+	} `json:"chunk_map"`
+}
+
 func writeProductionContractConfig(t *testing.T, content string) string {
 	t.Helper()
 	path := filepath.Join(t.TempDir(), "config.yml")