eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Retire annotated D&D scene plans

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-24 00:40:53 +00:00
parent cacf3f24e7
commit f5ed30e455
8 changed files with 39 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/internal/modules.md
View File

@@ -177,17 +177,16 @@ window settings used by `Plan`.
The scene chunker prepares a structured Scriptorium request from the full
transcript, session, and optional D&D reference inputs. It validates the model's
scene boundaries against source-unit IDs and converts them into deterministic
plan ranges with optional scene annotations. Preparation injects the shared
structured LLM client into the chunker; `Plan`
supplies only the run-specific profile, session, source, references, and
metadata.
inclusive source-unit endpoints against document position and converts them
into deterministic plan ranges. Preparation injects the shared structured LLM
client into the chunker; `Plan` supplies only the run-specific profile, session,
source, references, and metadata.
Scene validation requires sequential, contiguous, non-overlapping coverage from
the first source unit through the last. Scene descriptions, boundaries,
confidence, and participants are module-owned annotations. Boundary caveats
become warnings. Malformed
structured output is returned as an error; there is no fallback chunker.
the first source unit through the last. Its private response contains only the
boundary endpoints; the accepted plan has no D&D-specific annotations and
produces no boundary warnings. Malformed structured output is returned as an
error; there is no fallback chunker.
The package embeds its prompt and response schema and reports their non-secret
identity and hashes through singleton module metadata. Shared D&D assets supply

6
docs/roadmap/future.md
View File

@@ -16,12 +16,8 @@ not as committed release dates.
validator, and normalizer development. Treat model-quality review as an
iterative human evaluation aid, not a deterministic correctness gate.
### Minimize And Use D&D Scene Chunking
### Use D&D Scene Chunking
- Reduce the D&D scene chunker toward its narrow responsibility: identifying
coherent scene boundaries. Retain boundary confidence or caveats only when a
demonstrated validator or operator workflow consumes them; move title,
summary, scene kind, and participant duties to dedicated artifacts.
- Allow the combat extractor to no-op for chunks classified as non-combat only
after the scene-description artifact can be supplied through an explicit
ordered dependency. Do not make generic chunk materialization depend on a D&D

2
docs/roadmap/minimal-dnd-scene-chunking.md
View File

@@ -1,6 +1,6 @@
# Minimal D&D Scene Chunking
Status: Proposed
Status: Implemented
## Purpose

23
internal/cli/production_contract_test.go
View File

@@ -458,7 +458,7 @@ func TestProductionNormalizeValidatorOverrideRemainsAuthoritative(t *testing.T)
t.Fatalf("resolved validator chains = %#v, want normalize chain for %q", effective.ResolvedPipeline.ValidatorChains, spellnormalize.Key)
}
func TestProductionSceneRunRecordsChunkerWarningsAndProvenance(t *testing.T) {
func TestProductionSceneRunRecordsAnnotationFreeChunkPlanAndProvenance(t *testing.T) {
outputRoot := filepath.Join(t.TempDir(), "output")
configPath := writeProductionContractConfig(t, productionRunConfig(outputRoot, "dnd/scenes"))
fake := &productionFakeLLMClient{}
@@ -505,24 +505,17 @@ func TestProductionSceneRunRecordsChunkerWarningsAndProvenance(t *testing.T) {
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 len(chunkMap.PlanAnnotations) != 0 {
t.Fatalf("chunk map plan annotations = %#v, want none", chunkMap.PlanAnnotations)
}
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)
if len(chunkMap.Chunks[0].Annotations) != 0 {
t.Fatalf("chunk map range annotations = %#v, want none", chunkMap.Chunks[0].Annotations)
}
warnings := readProductionJSON[struct {
Warnings []contracts.Warning `json:"warnings"`
}](t, filepath.Join(outputRoot, productionRunID, "warnings.json"))
if len(warnings.Warnings) != 1 || warnings.Warnings[0].ReasonCode != "scene_boundary_caveat" {
t.Fatalf("warnings = %#v, want one scene boundary warning", warnings.Warnings)
if len(warnings.Warnings) != 0 {
t.Fatalf("warnings = %#v, want none", warnings.Warnings)
}
if len(fake.requestsFor(scenes.PromptID)) != 1 || len(fake.requestsFor(spells.PromptID)) != 1 {
t.Fatalf("fake prompt requests = %#v, want one scene and one spell request", fake.requestPrompts())
@@ -725,7 +718,7 @@ func (client *productionFakeLLMClient) CompleteStructured(ctx context.Context, r
var content []byte
switch req.PromptID {
case scenes.PromptID:
content = []byte(`{"scenes":[{"start_unit_id":1,"end_unit_id":2,"short_title":"Opening scene","primary_mode":"Narrative","main_participants":["Aria"],"summary":"The session opens.","boundary_note":"The opening covers the available transcript.","boundary_confidence":"High"}],"boundary_caveats":["The opening boundary is inferred from the short transcript."]}`)
content = []byte(`{"scenes":[{"start_unit_id":1,"end_unit_id":2}]}`)
case spells.PromptID:
if client.spellResponse != "" {
content = []byte(client.spellResponse)

36
internal/framework/chunkmap/codec_test.go
View File

@@ -61,7 +61,7 @@ func TestCodecRoundTripsValidFixture(t *testing.T) {
func TestBuildCanonicalizesAnnotationFormatting(t *testing.T) {
first := acceptedBuildRequest(t)
second := acceptedBuildRequest(t)
second.Plan.Annotations["dnd/scenes"] = json.RawMessage(" { \n \t\"title\" : \"Gate\" \n } ")
second.Plan.Annotations["test/chunker"] = json.RawMessage(" { \n \t\"label\" : \"fixture\" \n } ")
canonical, err := source.CanonicalizeChunkPlan(second.Plan)
if err != nil {
t.Fatalf("CanonicalizeChunkPlan() error = %v", err)
@@ -108,7 +108,7 @@ func TestCodecRejectsInvalidDurableBoundaries(t *testing.T) {
{name: "invalid range", mutate: func(value *ChunkMap) { value.Chunks[0].SourceRef.StartUnitID = 0 }},
{name: "invalid count", mutate: func(value *ChunkMap) { value.Chunks[0].UnitCount = 0 }},
{name: "invalid namespace", mutate: func(value *ChunkMap) { value.PlanAnnotations[" "] = json.RawMessage(`null`) }},
{name: "invalid annotation", mutate: func(value *ChunkMap) { value.Chunks[0].Annotations["dnd/scenes"] = json.RawMessage(`{`) }},
{name: "invalid annotation", mutate: func(value *ChunkMap) { value.Chunks[0].Annotations["test/chunker"] = json.RawMessage(`{`) }},
{name: "plan digest mismatch", mutate: func(value *ChunkMap) { value.PlanDigest = "sha256:" + strings.Repeat("a", 64) }},
} {
t.Run(test.name, func(t *testing.T) {
@@ -131,13 +131,13 @@ func TestCodecRejectsInvalidDurableBoundaries(t *testing.T) {
t.Fatalf("Decode(%s) error = nil, want strict JSON rejection", raw)
}
}
formatted := bytes.Replace(content, []byte(`{"title":"Gate"}`), []byte("{\n \"title\": \"Gate\"\n}"), 1)
formatted := bytes.Replace(content, []byte(`{"label":"fixture"}`), []byte("{\n \"label\": \"fixture\"\n}"), 1)
decoded, err := New().Decode(formatted)
if err != nil {
t.Fatalf("Decode(formatted annotations) error = %v", err)
}
if string(decoded.PlanAnnotations["dnd/scenes"]) != `{"title":"Gate"}` {
t.Fatalf("decoded annotation = %s, want canonical JSON", decoded.PlanAnnotations["dnd/scenes"])
if string(decoded.PlanAnnotations["test/chunker"]) != `{"label":"fixture"}` {
t.Fatalf("decoded annotation = %s, want canonical JSON", decoded.PlanAnnotations["test/chunker"])
}
}
@@ -187,7 +187,7 @@ func TestEncodeDoesNotMutateValue(t *testing.T) {
if err != nil {
t.Fatal(err)
}
value.Chunks[0].Annotations["dnd/scenes"] = json.RawMessage(" { \n \"kind\" : \"narrative\" \n } ")
value.Chunks[0].Annotations["test/chunker"] = json.RawMessage(" { \n \"category\" : \"sample\" \n } ")
before := clone(value)
if _, err := New().Encode(value); err != nil {
t.Fatalf("Encode() error = %v", err)
@@ -203,14 +203,14 @@ func TestChunkMapOwnershipIsIndependent(t *testing.T) {
if err != nil {
t.Fatal(err)
}
request.Plan.Annotations["dnd/scenes"][0] = '['
first.PlanAnnotations["dnd/scenes"][0] = '['
request.Plan.Annotations["test/chunker"][0] = '['
first.PlanAnnotations["test/chunker"][0] = '['
second, err := Build(acceptedBuildRequest(t))
if err != nil {
t.Fatal(err)
}
if string(second.PlanAnnotations["dnd/scenes"]) != `{"title":"Gate"}` {
t.Fatalf("Build() shared mutable annotations: %s", second.PlanAnnotations["dnd/scenes"])
if string(second.PlanAnnotations["test/chunker"]) != `{"label":"fixture"}` {
t.Fatalf("Build() shared mutable annotations: %s", second.PlanAnnotations["test/chunker"])
}
}
@@ -232,11 +232,11 @@ func chunkDocument(value map[string]any, index int) map[string]any {
func acceptedBuildRequest(t *testing.T) BuildRequest {
t.Helper()
document := &source.SourceDocument{
ID: "session-7", Kind: "transcript", Format: "application/json",
ID: "source-test", Kind: "transcript", Format: "application/json",
Units: []source.SourceUnit{
{ID: 10, Kind: "segment", Text: "At the gate.", Ref: source.SourceRef{SourceID: "session-7", StartUnitID: 10, EndUnitID: 10}},
{ID: 3, Kind: "segment", Text: "The guard speaks.", Ref: source.SourceRef{SourceID: "session-7", StartUnitID: 3, EndUnitID: 3}},
{ID: 20, Kind: "segment", Text: "The party enters.", Ref: source.SourceRef{SourceID: "session-7", StartUnitID: 20, EndUnitID: 20}},
{ID: 10, Kind: "segment", Text: "First unit.", Ref: source.SourceRef{SourceID: "source-test", StartUnitID: 10, EndUnitID: 10}},
{ID: 3, Kind: "segment", Text: "Second unit.", Ref: source.SourceRef{SourceID: "source-test", StartUnitID: 3, EndUnitID: 3}},
{ID: 20, Kind: "segment", Text: "Third unit.", Ref: source.SourceRef{SourceID: "source-test", StartUnitID: 20, EndUnitID: 20}},
},
}
digest, err := source.DigestDocument(document)
@@ -246,9 +246,9 @@ func acceptedBuildRequest(t *testing.T) BuildRequest {
document.Digest = digest
plan := source.ChunkPlan{
SourceDigest: digest,
Annotations: source.ChunkAnnotations{"dnd/scenes": json.RawMessage(`{"title":"Gate"}`)},
Annotations: source.ChunkAnnotations{"test/chunker": json.RawMessage(`{"label":"fixture"}`)},
Ranges: []source.ChunkRange{
{StartUnitID: 10, EndUnitID: 3, Annotations: source.ChunkAnnotations{"dnd/scenes": json.RawMessage(`{"kind":"narrative"}`)}},
{StartUnitID: 10, EndUnitID: 3, Annotations: source.ChunkAnnotations{"test/chunker": json.RawMessage(`{"category":"sample"}`)}},
{StartUnitID: 20, EndUnitID: 20},
},
}
@@ -257,7 +257,7 @@ func acceptedBuildRequest(t *testing.T) BuildRequest {
t.Fatal(err)
}
return BuildRequest{
Source: document, Plan: plan, Chunks: chunks, RequestedChunker: "dnd/scenes",
Producer: Producer{InputModule: "seriatim", ChunkModule: "dnd/scenes", LLMProfile: "dnd-scenes"},
Source: document, Plan: plan, Chunks: chunks, RequestedChunker: "chunk/requested",
Producer: Producer{InputModule: "input/producer", ChunkModule: "chunk/producer", LLMProfile: "profile/test"},
}
}

2
internal/framework/chunkmap/testdata/source_chunk_map.v1.json vendored
View File

@@ -1 +1 @@
{"source_id":"session-7","source_digest":"sha256:87d04d40537217e2adcbdec841c5873dbc1034c426d83c4578a0431a5ef855f6","plan_digest":"sha256:a6bfc33d52f1c0f4eb3287dd4a00e8672b3d3d9579f9c0366f18a5ff0dba7d14","requested_chunker":"dnd/scenes","producer":{"input_module":"seriatim","chunk_module":"dnd/scenes","llm_profile":"dnd-scenes"},"plan_annotations":{"dnd/scenes":{"title":"Gate"}},"chunks":[{"id":"chunk-000001","index":0,"source_ref":{"source_id":"session-7","start_unit_id":10,"end_unit_id":3},"unit_count":2,"annotations":{"dnd/scenes":{"kind":"narrative"}}},{"id":"chunk-000002","index":1,"source_ref":{"source_id":"session-7","start_unit_id":20,"end_unit_id":20},"unit_count":1,"annotations":{}}]}
{"source_id":"source-test","source_digest":"sha256:186b2d30029e7fda40545f88e75ade38f22bff3e5543af4dfeb86587536a01af","plan_digest":"sha256:e50cc7da9070ac8a4339d79b2c206be842846c5c22af7b0ad58f7e9a34ceaf97","requested_chunker":"chunk/requested","producer":{"input_module":"input/producer","chunk_module":"chunk/producer","llm_profile":"profile/test"},"plan_annotations":{"test/chunker":{"label":"fixture"}},"chunks":[{"id":"chunk-000001","index":0,"source_ref":{"source_id":"source-test","start_unit_id":10,"end_unit_id":3},"unit_count":2,"annotations":{"test/chunker":{"category":"sample"}}},{"id":"chunk-000002","index":1,"source_ref":{"source_id":"source-test","start_unit_id":20,"end_unit_id":20},"unit_count":1,"annotations":{}}]}

2
internal/framework/chunkplan/store_test.go
View File

@@ -281,7 +281,7 @@ func TestFilesystemStoreReportsInvalidRecordsAsRecoverable(t *testing.T) {
return bytes.Replace(data, []byte(`{"schema_version"`), []byte(`{"SENTINEL_UNKNOWN_FIELD":true,"schema_version"`), 1)
}},
{name: "truncated JSON", mutate: func(data []byte) []byte { return data[:len(data)/2] }},
{name: "schema mismatch", mutate: replaceJSON(`notarius.chunk-plan.v1`, `SENTINEL_SCHEMA_VALUE`)},
{name: "legacy v1 record", mutate: replaceJSON(`notarius.chunk-plan.v2`, `notarius.chunk-plan.v1`)},
{name: "source mismatch", mutate: replaceJSON(testSourceDigest, "sha256:"+strings.Repeat("b", 64))},
{name: "plan digest mismatch", mutate: func(data []byte) []byte {
prefix := []byte(`"plan_digest":"sha256:`)

2
internal/framework/pipeline/chunk_plan_store.go
View File

@@ -8,7 +8,7 @@ import (
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
)
const ChunkPlanSchemaVersion = "notarius.chunk-plan.v1"
const ChunkPlanSchemaVersion = "notarius.chunk-plan.v2"
type ChunkPlanProducer struct {
InputModule string `json:"input_module"`