Require explicit module execution classes

2026-08-03 17:00:08 +00:00
parent ce857966f1
commit 58815aaf33
23 changed files with 246 additions and 182 deletions
--- a/internal/framework/pipeline/profile_test.go
+++ b/internal/framework/pipeline/profile_test.go
@@ -15,11 +15,11 @@ import (
 func TestResolvePipelineWithExplicitModules(t *testing.T) {
 	catalog := newProfileCatalog(t)
 	registerProfileSpecs(t, catalog,
-		ModuleSpec{Key: "window", Stage: StageChunk, Requires: []string{"source"}, Provides: []string{"chunk"}},
-		ModuleSpec{Key: "record-extractor", Stage: StageExtract, Requires: []string{"chunk"}, Provides: []string{"candidate"}},
-		ModuleSpec{Key: "dedupe", Stage: StageMerge, Requires: []string{"candidate"}, Provides: []string{"merged"}},
-		ModuleSpec{Key: "canonical", Stage: StageNormalize, Requires: []string{"merged"}, Provides: []string{"normalized"}},
-		ModuleSpec{Key: "ndjson", Stage: StageOutput, Requires: []string{"normalized"}, Provides: []string{"encoded"}},
+		ModuleSpec{Key: "window", Stage: StageChunk, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"source"}, Provides: []string{"chunk"}},
+		ModuleSpec{Key: "record-extractor", Stage: StageExtract, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"chunk"}, Provides: []string{"candidate"}},
+		ModuleSpec{Key: "dedupe", Stage: StageMerge, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"candidate"}, Provides: []string{"merged"}},
+		ModuleSpec{Key: "canonical", Stage: StageNormalize, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"merged"}, Provides: []string{"normalized"}},
+		ModuleSpec{Key: "ndjson", Stage: StageOutput, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"normalized"}, Provides: []string{"encoded"}},
 	)

 	resolved, err := ResolvePipeline(PipelineProfile{
@@ -386,7 +386,8 @@ func TestResolvePipelinePreservesOrderedStepsAndExpandsGeneratedBindings(t *test
 	catalog := newProfileCatalogWithOverrides(t,
 		ModuleSpec{
 			Key: "note-extractor", Stage: StageExtract, ArtifactKind: "test/notes",
-			Requires: []string{"chunk"}, Provides: []string{"candidate"},
+			ExecutionClass: contracts.ExecutionClassDeterministic,
+			Requires:       []string{"chunk"}, Provides: []string{"candidate"},
 			ReferenceSlots: []contracts.ReferenceSlot{{Name: "npcs", AcceptedArtifactKinds: []contracts.ArtifactKind{"test/notes"}, AcceptedMediaTypes: []string{"application/json"}}},
 		})
 	resolved, err := ResolvePipeline(PipelineProfile{
@@ -414,7 +415,7 @@ func TestResolvePipelinePreservesOrderedStepsAndExpandsGeneratedBindings(t *test

 func TestResolvePipelineRejectsGeneratedBindingOrderingAndKind(t *testing.T) {
 	catalog := newProfileCatalogWithOverrides(t,
-		ModuleSpec{Key: "note-extractor", Stage: StageExtract, ArtifactKind: "test/notes", Requires: []string{"chunk"}, Provides: []string{"candidate"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "npcs", AcceptedArtifactKinds: []contracts.ArtifactKind{"test/other"}}}},
+		ModuleSpec{Key: "note-extractor", Stage: StageExtract, ExecutionClass: contracts.ExecutionClassDeterministic, ArtifactKind: "test/notes", Requires: []string{"chunk"}, Provides: []string{"candidate"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "npcs", AcceptedArtifactKinds: []contracts.ArtifactKind{"test/other"}}}},
 	)
 	_, err := ResolvePipeline(PipelineProfile{
 		ID: "invalid-order", Input: Binding("text"), Steps: []PipelineStepProfile{
@@ -449,10 +450,11 @@ func TestResolvePipelineAppliesReferenceBindings(t *testing.T) {
 	profile.Artifacts["events"] = lane

 	catalog := newProfileCatalogWithOverride(t, ModuleSpec{
-		Key:      "event-extractor",
-		Stage:    StageExtract,
-		Requires: []string{"chunk"},
-		Provides: []string{"candidate"},
+		Key:            "event-extractor",
+		Stage:          StageExtract,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+		Requires:       []string{"chunk"},
+		Provides:       []string{"candidate"},
 		ReferenceSlots: []contracts.ReferenceSlot{
 			{Name: "roster", Required: true},
 			{Name: "lore"},
@@ -495,6 +497,7 @@ func TestResolvePipelineAppliesPipelineReferenceDefaultToChunkTarget(t *testing.
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
 		Key:            "generic",
 		Stage:          StageChunk,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
 		Requires:       []string{"source"},
 		Provides:       []string{"chunk"},
 		ReferenceSlots: []contracts.ReferenceSlot{{Name: "scene_guide"}},
@@ -523,6 +526,7 @@ func TestResolvePipelineAppliesPipelineReferenceDefaultToExtractorTarget(t *test
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
 		Key:            "event-extractor",
 		Stage:          StageExtract,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
 		Requires:       []string{"chunk"},
 		Provides:       []string{"candidate"},
 		ReferenceSlots: []contracts.ReferenceSlot{{Name: "roster"}},
@@ -551,6 +555,7 @@ func TestResolvePipelineAppliesPipelineReferenceDefaultToNormalizerTarget(t *tes
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
 		Key:            "noop",
 		Stage:          StageNormalize,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
 		Requires:       []string{"merged"},
 		Provides:       []string{"normalized"},
 		ReferenceSlots: []contracts.ReferenceSlot{{Name: "normalization_notes"}},
@@ -579,6 +584,7 @@ func TestResolvePipelineAppliesPipelineReferenceDefaultToMergeTarget(t *testing.
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
 		Key:            "appendorder",
 		Stage:          StageMerge,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
 		Requires:       []string{"candidate"},
 		Provides:       []string{"merged"},
 		ReferenceSlots: []contracts.ReferenceSlot{{Name: "merge_notes"}},
@@ -608,10 +614,10 @@ func TestResolvePipelineAppliesOnePipelineReferenceDefaultToMultipleTargets(t *t
 	profile := baselineProfile()
 	profile.References = ExternalReferenceMap(map[string]string{"context": "./context.md"})
 	catalog := newProfileCatalogWithOverrides(t,
-		ModuleSpec{Key: "generic", Stage: StageChunk, Requires: []string{"source"}, Provides: []string{"chunk"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
-		ModuleSpec{Key: "event-extractor", Stage: StageExtract, Requires: []string{"chunk"}, Provides: []string{"candidate"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
-		ModuleSpec{Key: "appendorder", Stage: StageMerge, Requires: []string{"candidate"}, Provides: []string{"merged"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
-		ModuleSpec{Key: "noop", Stage: StageNormalize, Requires: []string{"merged"}, Provides: []string{"normalized"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
+		ModuleSpec{Key: "generic", Stage: StageChunk, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"source"}, Provides: []string{"chunk"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
+		ModuleSpec{Key: "event-extractor", Stage: StageExtract, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"chunk"}, Provides: []string{"candidate"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
+		ModuleSpec{Key: "appendorder", Stage: StageMerge, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"candidate"}, Provides: []string{"merged"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
+		ModuleSpec{Key: "noop", Stage: StageNormalize, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"merged"}, Provides: []string{"normalized"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
 	)

 	resolved, err := ResolvePipeline(profile, ResolveOptions{}, catalog)
@@ -629,10 +635,11 @@ func TestResolvePipelineAllowsPipelineReferenceDeclaredOnlyByUnselectedLane(t *t
 	profile := multiLaneProfile()
 	profile.References = ExternalReferenceMap(map[string]string{"notes_context": "./notes.md"})
 	catalog := newProfileCatalogWithOverride(t, ModuleSpec{
-		Key:      "note-extractor",
-		Stage:    StageExtract,
-		Requires: []string{"chunk"},
-		Provides: []string{"candidate"},
+		Key:            "note-extractor",
+		Stage:          StageExtract,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+		Requires:       []string{"chunk"},
+		Provides:       []string{"candidate"},
 		ReferenceSlots: []contracts.ReferenceSlot{
 			{Name: "notes_context"},
 		},
@@ -654,10 +661,11 @@ func TestResolvePipelineAllowsPipelineReferenceDeclaredOnlyByUnselectedNormalize
 	lane.Normalize = Binding("note-normalizer")
 	profile.Artifacts["notes"] = lane
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
-		Key:      "note-normalizer",
-		Stage:    StageNormalize,
-		Requires: []string{"merged"},
-		Provides: []string{"normalized"},
+		Key:            "note-normalizer",
+		Stage:          StageNormalize,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+		Requires:       []string{"merged"},
+		Provides:       []string{"normalized"},
 		ReferenceSlots: []contracts.ReferenceSlot{
 			{Name: "notes_context"},
 		},
@@ -707,6 +715,7 @@ func TestResolvePipelineRejectsExtractLocalReferenceDeclaredOnlyByNormalizer(t *
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
 		Key:            "noop",
 		Stage:          StageNormalize,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
 		Requires:       []string{"merged"},
 		Provides:       []string{"normalized"},
 		ReferenceSlots: []contracts.ReferenceSlot{{Name: "normalization_notes"}},
@@ -725,10 +734,11 @@ func TestResolvePipelineRejectsMergeLocalReferenceDeclaredOnlyByNormalizer(t *te
 	lane.Merge.References = ExternalReferenceMap(map[string]string{"normalization_notes": "./normalize.md"})
 	profile.Artifacts["events"] = lane
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
-		Key:      "noop",
-		Stage:    StageNormalize,
-		Requires: []string{"merged"},
-		Provides: []string{"normalized"},
+		Key:            "noop",
+		Stage:          StageNormalize,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+		Requires:       []string{"merged"},
+		Provides:       []string{"normalized"},
 		ReferenceSlots: []contracts.ReferenceSlot{
 			{Name: "normalization_notes"},
 		},
@@ -749,6 +759,7 @@ func TestResolvePipelineRejectsNormalizeLocalReferenceDeclaredOnlyByExtractor(t
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
 		Key:            "event-extractor",
 		Stage:          StageExtract,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
 		Requires:       []string{"chunk"},
 		Provides:       []string{"candidate"},
 		ReferenceSlots: []contracts.ReferenceSlot{{Name: "roster"}},
@@ -765,6 +776,7 @@ func TestResolvePipelineRequiresBoundChunkReference(t *testing.T) {
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
 		Key:            "generic",
 		Stage:          StageChunk,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
 		Requires:       []string{"source"},
 		Provides:       []string{"chunk"},
 		ReferenceSlots: []contracts.ReferenceSlot{{Name: "scene_guide", Required: true}},
@@ -781,6 +793,7 @@ func TestResolvePipelineRequiresBoundNormalizeReference(t *testing.T) {
 	catalog := newProfileCatalogWithOverrides(t, ModuleSpec{
 		Key:            "noop",
 		Stage:          StageNormalize,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
 		Requires:       []string{"merged"},
 		Provides:       []string{"normalized"},
 		ReferenceSlots: []contracts.ReferenceSlot{{Name: "normalization_notes", Required: true}},
@@ -806,9 +819,9 @@ func TestResolvePipelineLocalReferencesOverridePipelineDefaultsForEligibleTarget
 	lane.Normalize.References = ExternalReferenceMap(map[string]string{"normalization_notes": "./local-normalize.md"})
 	profile.Artifacts["events"] = lane
 	catalog := newProfileCatalogWithOverrides(t,
-		ModuleSpec{Key: "generic", Stage: StageChunk, Requires: []string{"source"}, Provides: []string{"chunk"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
-		ModuleSpec{Key: "event-extractor", Stage: StageExtract, Requires: []string{"chunk"}, Provides: []string{"candidate"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "roster"}}},
-		ModuleSpec{Key: "noop", Stage: StageNormalize, Requires: []string{"merged"}, Provides: []string{"normalized"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "normalization_notes"}}},
+		ModuleSpec{Key: "generic", Stage: StageChunk, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"source"}, Provides: []string{"chunk"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "context"}}},
+		ModuleSpec{Key: "event-extractor", Stage: StageExtract, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"chunk"}, Provides: []string{"candidate"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "roster"}}},
+		ModuleSpec{Key: "noop", Stage: StageNormalize, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"merged"}, Provides: []string{"normalized"}, ReferenceSlots: []contracts.ReferenceSlot{{Name: "normalization_notes"}}},
 	)

 	resolved, err := ResolvePipeline(profile, ResolveOptions{}, catalog)
@@ -823,10 +836,11 @@ func TestResolvePipelineLocalReferencesOverridePipelineDefaultsForEligibleTarget

 func TestResolvePipelineRequiresBoundReferenceSlotsForSelectedLanes(t *testing.T) {
 	catalog := newProfileCatalogWithOverride(t, ModuleSpec{
-		Key:      "event-extractor",
-		Stage:    StageExtract,
-		Requires: []string{"chunk"},
-		Provides: []string{"candidate"},
+		Key:            "event-extractor",
+		Stage:          StageExtract,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+		Requires:       []string{"chunk"},
+		Provides:       []string{"candidate"},
 		ReferenceSlots: []contracts.ReferenceSlot{
 			{Name: "roster", Required: true},
 		},
@@ -847,10 +861,11 @@ func TestResolvePipelineReferenceUnbindCanLeaveRequiredSlotMissing(t *testing.T)
 	profile := baselineProfile()
 	profile.References = ExternalReferenceMap(map[string]string{"roster": "./roster.yml"})
 	catalog := newProfileCatalogWithOverride(t, ModuleSpec{
-		Key:      "event-extractor",
-		Stage:    StageExtract,
-		Requires: []string{"chunk"},
-		Provides: []string{"candidate"},
+		Key:            "event-extractor",
+		Stage:          StageExtract,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+		Requires:       []string{"chunk"},
+		Provides:       []string{"candidate"},
 		ReferenceSlots: []contracts.ReferenceSlot{
 			{Name: "roster", Required: true},
 		},
@@ -876,11 +891,12 @@ func TestResolvePipelineUsesReferenceSlotsFromSpecWithoutConstructingExtractor(t
 		}
 	}
 	if err := RegisterExtractor[codecNotes](catalog.Extractors, ModuleSpec{
-		Key:          "event-extractor",
-		Stage:        StageExtract,
-		ArtifactKind: "test/notes",
-		Requires:     []string{"chunk"},
-		Provides:     []string{"candidate"},
+		Key:            "event-extractor",
+		Stage:          StageExtract,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+		ArtifactKind:   "test/notes",
+		Requires:       []string{"chunk"},
+		Provides:       []string{"candidate"},
 		ReferenceSlots: []contracts.ReferenceSlot{
 			{Name: "roster", Required: true},
 		},
@@ -1038,32 +1054,32 @@ func TestResolvePipelineRejectsMissingCapabilities(t *testing.T) {
 	}{
 		{
 			name: "input",
-			spec: ModuleSpec{Key: "text", Stage: StageInput, Requires: []string{"raw"}},
+			spec: ModuleSpec{Key: "text", Stage: StageInput, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"raw"}},
 			want: []string{"baseline", "input", "text", "raw"},
 		},
 		{
 			name: "chunk",
-			spec: ModuleSpec{Key: "generic", Stage: StageChunk, Requires: []string{"missing"}},
+			spec: ModuleSpec{Key: "generic", Stage: StageChunk, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"missing"}},
 			want: []string{"baseline", "chunk", "generic", "missing"},
 		},
 		{
 			name: "extract",
-			spec: ModuleSpec{Key: "event-extractor", Stage: StageExtract, Requires: []string{"missing"}},
+			spec: ModuleSpec{Key: "event-extractor", Stage: StageExtract, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"missing"}},
 			want: []string{"baseline", "events", "extract", "event-extractor", "missing"},
 		},
 		{
 			name: "merge",
-			spec: ModuleSpec{Key: "appendorder", Stage: StageMerge, Requires: []string{"missing"}},
+			spec: ModuleSpec{Key: "appendorder", Stage: StageMerge, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"missing"}},
 			want: []string{"baseline", "events", "merge", "appendorder", "missing"},
 		},
 		{
 			name: "normalize",
-			spec: ModuleSpec{Key: "noop", Stage: StageNormalize, Requires: []string{"missing"}},
+			spec: ModuleSpec{Key: "noop", Stage: StageNormalize, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"missing"}},
 			want: []string{"baseline", "events", "normalize", "noop", "missing"},
 		},
 		{
 			name: "output",
-			spec: ModuleSpec{Key: "json", Stage: StageOutput, Requires: []string{"missing"}},
+			spec: ModuleSpec{Key: "json", Stage: StageOutput, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"missing"}},
 			want: []string{"baseline", "output", "json", "missing"},
 		},
 	}
@@ -1149,7 +1165,7 @@ func TestResolvePipelineDigestChangesWhenBindingChanges(t *testing.T) {
 	right := baselineProfile()
 	right.Chunk = Binding("window")
 	catalog := newProfileCatalog(t)
-	registerProfileSpecs(t, catalog, ModuleSpec{Key: "window", Stage: StageChunk, Requires: []string{"source"}, Provides: []string{"chunk"}})
+	registerProfileSpecs(t, catalog, ModuleSpec{Key: "window", Stage: StageChunk, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"source"}, Provides: []string{"chunk"}})

 	leftResolved, err := ResolvePipeline(left, ResolveOptions{}, catalog)
 	if err != nil {
@@ -1516,14 +1532,14 @@ func emptyProfileCatalog() ModuleCatalog {

 func defaultProfileSpecs() []ModuleSpec {
 	return []ModuleSpec{
-		ModuleSpec{Key: "text", Stage: StageInput, Provides: []string{"source"}},
-		ModuleSpec{Key: "generic", Stage: StageChunk, Requires: []string{"source"}, Provides: []string{"chunk"}},
-		ModuleSpec{Key: "event-extractor", Stage: StageExtract, ArtifactKind: "test/notes", Requires: []string{"chunk"}, Provides: []string{"candidate"}},
-		ModuleSpec{Key: "note-extractor", Stage: StageExtract, ArtifactKind: "test/notes", Requires: []string{"chunk"}, Provides: []string{"candidate"}},
-		ModuleSpec{Key: "appendorder", Stage: StageMerge, ArtifactKind: "test/notes", Requires: []string{"candidate"}, Provides: []string{"merged"}},
-		ModuleSpec{Key: "noop", Stage: StageNormalize, ArtifactKind: "test/notes", Requires: []string{"merged"}, Provides: []string{"normalized"}},
-		ModuleSpec{Key: "grounded", Stage: StageValidate, Requires: []string{"normalized"}, Provides: []string{"validated"}},
-		ModuleSpec{Key: "json", Stage: StageOutput, Requires: []string{"normalized"}, Provides: []string{"encoded"}},
+		ModuleSpec{Key: "text", Stage: StageInput, ExecutionClass: contracts.ExecutionClassDeterministic, Provides: []string{"source"}},
+		ModuleSpec{Key: "generic", Stage: StageChunk, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"source"}, Provides: []string{"chunk"}},
+		ModuleSpec{Key: "event-extractor", Stage: StageExtract, ExecutionClass: contracts.ExecutionClassDeterministic, ArtifactKind: "test/notes", Requires: []string{"chunk"}, Provides: []string{"candidate"}},
+		ModuleSpec{Key: "note-extractor", Stage: StageExtract, ExecutionClass: contracts.ExecutionClassDeterministic, ArtifactKind: "test/notes", Requires: []string{"chunk"}, Provides: []string{"candidate"}},
+		ModuleSpec{Key: "appendorder", Stage: StageMerge, ExecutionClass: contracts.ExecutionClassDeterministic, ArtifactKind: "test/notes", Requires: []string{"candidate"}, Provides: []string{"merged"}},
+		ModuleSpec{Key: "noop", Stage: StageNormalize, ExecutionClass: contracts.ExecutionClassDeterministic, ArtifactKind: "test/notes", Requires: []string{"merged"}, Provides: []string{"normalized"}},
+		ModuleSpec{Key: "grounded", Stage: StageValidate, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"normalized"}, Provides: []string{"validated"}},
+		ModuleSpec{Key: "json", Stage: StageOutput, ExecutionClass: contracts.ExecutionClassDeterministic, Requires: []string{"normalized"}, Provides: []string{"encoded"}},
 	}
 }