Implement ordered pipeline step resolution

internal/core/config/config.go

@@ -107,7 +107,26 @@ func clonePipelineProfile(in pipeline.PipelineProfile) pipeline.PipelineProfile
 	out.Input = cloneModuleBinding(in.Input)
 	out.Chunk = cloneModuleBinding(in.Chunk)
 	out.Output = cloneModuleBinding(in.Output)
-	out.References = cloneStringMap(in.References)
+	out.References = cloneReferenceSourceMap(in.References)
+	if len(in.Artifacts) > 0 {
+		out.Artifacts = make(map[string]pipeline.ArtifactLaneProfile, len(in.Artifacts))
+		for key, lane := range in.Artifacts {
+			out.Artifacts[key] = cloneArtifactLaneProfile(lane)
+		}
+	}
+	if in.Steps != nil {
+		out.Steps = make([]pipeline.PipelineStepProfile, len(in.Steps))
+		for i, step := range in.Steps {
+			out.Steps[i] = clonePipelineStepProfile(step)
+		}
+	}
+	return out
+}
+
+func clonePipelineStepProfile(in pipeline.PipelineStepProfile) pipeline.PipelineStepProfile {
+	out := in
+	out.ID = in.ID
+	out.References = cloneReferenceSourceMap(in.References)
 	if len(in.Artifacts) > 0 {
 		out.Artifacts = make(map[string]pipeline.ArtifactLaneProfile, len(in.Artifacts))
 		for key, lane := range in.Artifacts {
@@ -122,7 +141,7 @@ func cloneArtifactLaneProfile(in pipeline.ArtifactLaneProfile) pipeline.Artifact
 	out.Extract = cloneModuleBinding(in.Extract)
 	out.Merge = cloneModuleBinding(in.Merge)
 	out.Normalize = cloneModuleBinding(in.Normalize)
-	out.References = cloneStringMap(in.References)
+	out.References = cloneReferenceSourceMap(in.References)
 	if len(in.Validators) > 0 {
 		out.Validators = make([]pipeline.ModuleBinding, len(in.Validators))
 		for i, binding := range in.Validators {
@@ -143,12 +162,32 @@ func cloneStringMap(in map[string]string) map[string]string {
 	return out
 }
 
+func cloneReferenceSourceMap(in map[string]pipeline.ReferenceSource) map[string]pipeline.ReferenceSource {
+	if len(in) == 0 {
+		return nil
+	}
+	out := make(map[string]pipeline.ReferenceSource, len(in))
+	for key, source := range in {
+		out[key] = cloneReferenceSource(source)
+	}
+	return out
+}
+
+func cloneReferenceSource(in pipeline.ReferenceSource) pipeline.ReferenceSource {
+	out := in
+	if in.Artifact != nil {
+		artifact := *in.Artifact
+		out.Artifact = &artifact
+	}
+	return out
+}
+
 func cloneModuleBinding(in pipeline.ModuleBinding) pipeline.ModuleBinding {
 	out := in
 	if len(in.Options) > 0 {
 		out.Options = cloneOptions(in.Options)
 	}
-	out.References = cloneStringMap(in.References)
+	out.References = cloneReferenceSourceMap(in.References)
 	out.Validators = cloneValidatorOverride(in.Validators)
 	return out
 }

internal/core/config/effective_config.go

@@ -67,11 +67,17 @@ func (c Config) Resolve(input ResolveInput) (EffectiveConfig, error) {
 
 func applyLLMProfileOverride(profile *pipeline.PipelineProfile, profileID string) {
 	profile.Chunk.LLMProfile = profileID
-	for laneID, lane := range profile.Artifacts {
-		lane.Extract.LLMProfile = profileID
-		lane.Merge.LLMProfile = profileID
-		lane.Normalize.LLMProfile = profileID
-		profile.Artifacts[laneID] = lane
+	apply := func(artifacts map[string]pipeline.ArtifactLaneProfile) {
+		for laneID, lane := range artifacts {
+			lane.Extract.LLMProfile = profileID
+			lane.Merge.LLMProfile = profileID
+			lane.Normalize.LLMProfile = profileID
+			artifacts[laneID] = lane
+		}
+	}
+	apply(profile.Artifacts)
+	for index := range profile.Steps {
+		apply(profile.Steps[index].Artifacts)
 	}
 }
 

internal/core/config/effective_config_contract_test.go

@@ -53,8 +53,8 @@ func TestEffectiveConfigOnlySelectsRequestedLanesWithoutMutatingSource(t *testin
 	if err != nil {
 		t.Fatalf("Resolve() error = %v", err)
 	}
-	if len(effective.ResolvedPipeline.ArtifactLanes) != 1 || effective.ResolvedPipeline.ArtifactLanes[0].ID != "other" {
-		t.Fatalf("resolved lanes = %#v", effective.ResolvedPipeline.ArtifactLanes)
+	if len(effective.ResolvedPipeline.Steps[0].ArtifactLanes) != 1 || effective.ResolvedPipeline.Steps[0].ArtifactLanes[0].ID != "other" {
+		t.Fatalf("resolved lanes = %#v", effective.ResolvedPipeline.Steps[0].ArtifactLanes)
 	}
 	if len(cfg.Pipelines["main"].Artifacts) != 2 {
 		t.Fatalf("source lanes were mutated: %#v", cfg.Pipelines["main"].Artifacts)
@@ -79,8 +79,8 @@ func TestEffectiveConfigMaterializesDefaultBindingsThroughCatalog(t *testing.T)
 	if resolved.Chunk.Module != pipeline.DefaultChunkModule || resolved.Output.Module != pipeline.DefaultOutputModule {
 		t.Fatalf("default pipeline bindings = %#v, %#v", resolved.Chunk, resolved.Output)
 	}
-	if len(resolved.ArtifactLanes) != 1 || resolved.ArtifactLanes[0].Merge.Module != pipeline.DefaultMergeModule || resolved.ArtifactLanes[0].Normalize.Module != pipeline.DefaultNormalizeModule {
-		t.Fatalf("default lane bindings = %#v", resolved.ArtifactLanes)
+	if len(resolved.Steps[0].ArtifactLanes) != 1 || resolved.Steps[0].ArtifactLanes[0].Merge.Module != pipeline.DefaultMergeModule || resolved.Steps[0].ArtifactLanes[0].Normalize.Module != pipeline.DefaultNormalizeModule {
+		t.Fatalf("default lane bindings = %#v", resolved.Steps[0].ArtifactLanes)
 	}
 }
 
@@ -182,8 +182,8 @@ func TestEffectiveConfigLLMProfileOverrideChangesDigestWithoutOverridingValidato
 		t.Fatal("LLM profile override did not change the pipeline digest")
 	}
 	resolved := overridden.ResolvedPipeline
-	if resolved.Chunk.LLMProfile != "override-profile" || resolved.ArtifactLanes[0].Extract.LLMProfile != "override-profile" ||
-		resolved.ArtifactLanes[0].Merge.LLMProfile != "override-profile" || resolved.ArtifactLanes[0].Normalize.LLMProfile != "override-profile" {
+	if resolved.Chunk.LLMProfile != "override-profile" || resolved.Steps[0].ArtifactLanes[0].Extract.LLMProfile != "override-profile" ||
+		resolved.Steps[0].ArtifactLanes[0].Merge.LLMProfile != "override-profile" || resolved.Steps[0].ArtifactLanes[0].Normalize.LLMProfile != "override-profile" {
 		t.Fatalf("pipeline profile override was not applied: %#v", resolved)
 	}
 	validators := findEffectiveValidatorChain(resolved, pipeline.StageExtract, "lane")
@@ -249,7 +249,7 @@ func TestEffectiveConfigValidatorOverridesRemainDistinctAndOrdered(t *testing.T)
 func TestEffectiveConfigAndResolutionInputsDoNotAliasSource(t *testing.T) {
 	profile := effectiveProfile()
 	profile.Chunk.Options = map[string]any{"nested": map[string]any{"safe": "source"}}
-	profile.Chunk.References = map[string]string{"chunk-ref": "chunk.txt"}
+	profile.Chunk.References = pipeline.ExternalReferenceMap(map[string]string{"chunk-ref": "chunk.txt"})
 	lane := profile.Artifacts["lane"]
 	lane.Extract.Validators = pipeline.ValidatorOverride{
 		Set: true,
@@ -282,7 +282,7 @@ func TestEffectiveConfigAndResolutionInputsDoNotAliasSource(t *testing.T) {
 	if got := cfg.Pipelines["main"].Chunk.Options["nested"].(map[string]any)["safe"]; got != "source" {
 		t.Fatalf("source config option was aliased: %v", got)
 	}
-	if got := cfg.Pipelines["main"].Chunk.References["chunk-ref"]; got != "chunk.txt" {
+	if got := cfg.Pipelines["main"].Chunk.References["chunk-ref"].Path; got != "chunk.txt" {
 		t.Fatalf("source config references were aliased: %v", got)
 	}
 	if only[0] != "lane" || overrides[0].Source != "source.txt" {

internal/core/config/file_config.go

@@ -28,19 +28,88 @@ type FileScriptoriumConfig struct {
 }
 
 type FilePipelineProfile struct {
-	Input      fileModuleBinding                  `yaml:"input"`
-	Chunk      *fileModuleBinding                 `yaml:"chunk,omitempty"`
-	Artifacts  map[string]FileArtifactLaneProfile `yaml:"artifacts,omitempty"`
-	Output     *fileModuleBinding                 `yaml:"output,omitempty"`
-	References map[string]string                  `yaml:"references,omitempty"`
+	Input        fileModuleBinding                  `yaml:"input"`
+	Chunk        *fileModuleBinding                 `yaml:"chunk,omitempty"`
+	Artifacts    map[string]FileArtifactLaneProfile `yaml:"artifacts,omitempty"`
+	Steps        []FilePipelineStepProfile          `yaml:"steps,omitempty"`
+	Output       *fileModuleBinding                 `yaml:"output,omitempty"`
+	References   map[string]fileReferenceSource     `yaml:"references,omitempty"`
+	artifactsSet bool                               `yaml:"-"`
+	stepsSet     bool                               `yaml:"-"`
+}
+
+func (p *FilePipelineProfile) UnmarshalYAML(node *yaml.Node) error {
+	type plainFilePipelineProfile FilePipelineProfile
+	var decoded plainFilePipelineProfile
+	seen, err := decodeKnownMapping(node, &decoded, map[string]struct{}{
+		"input": {}, "chunk": {}, "artifacts": {}, "steps": {}, "output": {}, "references": {},
+	}, "pipeline profile")
+	if err != nil {
+		return err
+	}
+	*p = FilePipelineProfile(decoded)
+	_, p.artifactsSet = seen["artifacts"]
+	_, p.stepsSet = seen["steps"]
+	return nil
+}
+
+func (s *FilePipelineStepProfile) UnmarshalYAML(node *yaml.Node) error {
+	type plainFilePipelineStepProfile FilePipelineStepProfile
+	var decoded plainFilePipelineStepProfile
+	if _, err := decodeKnownMapping(node, &decoded, map[string]struct{}{
+		"id": {}, "artifacts": {}, "references": {},
+	}, "pipeline step"); err != nil {
+		return err
+	}
+	*s = FilePipelineStepProfile(decoded)
+	return nil
+}
+
+func (l *FileArtifactLaneProfile) UnmarshalYAML(node *yaml.Node) error {
+	type plainFileArtifactLaneProfile FileArtifactLaneProfile
+	var decoded plainFileArtifactLaneProfile
+	if _, err := decodeKnownMapping(node, &decoded, map[string]struct{}{
+		"extract": {}, "merge": {}, "normalize": {}, "validators": {}, "references": {},
+	}, "artifact lane"); err != nil {
+		return err
+	}
+	*l = FileArtifactLaneProfile(decoded)
+	return nil
+}
+
+func decodeKnownMapping(node *yaml.Node, target any, allowed map[string]struct{}, context string) (map[string]struct{}, error) {
+	if node.Kind != yaml.MappingNode {
+		return nil, fmt.Errorf("%s must be an object", context)
+	}
+	if err := node.Decode(target); err != nil {
+		return nil, err
+	}
+	seen := make(map[string]struct{}, len(node.Content)/2)
+	for i := 0; i < len(node.Content); i += 2 {
+		key := node.Content[i].Value
+		if _, exists := seen[key]; exists {
+			return nil, fmt.Errorf("%s field %q is duplicated", context, key)
+		}
+		if _, ok := allowed[key]; !ok {
+			return nil, fmt.Errorf("field %s not found in %s", key, context)
+		}
+		seen[key] = struct{}{}
+	}
+	return seen, nil
+}
+
+type FilePipelineStepProfile struct {
+	ID         string                             `yaml:"id"`
+	Artifacts  map[string]FileArtifactLaneProfile `yaml:"artifacts"`
+	References map[string]fileReferenceSource     `yaml:"references,omitempty"`
 }
 
 type FileArtifactLaneProfile struct {
-	Extract    fileModuleBinding   `yaml:"extract"`
-	Merge      *fileModuleBinding  `yaml:"merge,omitempty"`
-	Normalize  *fileModuleBinding  `yaml:"normalize,omitempty"`
-	Validators []fileModuleBinding `yaml:"validators,omitempty"`
-	References map[string]string   `yaml:"references,omitempty"`
+	Extract    fileModuleBinding              `yaml:"extract"`
+	Merge      *fileModuleBinding             `yaml:"merge,omitempty"`
+	Normalize  *fileModuleBinding             `yaml:"normalize,omitempty"`
+	Validators []fileModuleBinding            `yaml:"validators,omitempty"`
+	References map[string]fileReferenceSource `yaml:"references,omitempty"`
 }
 
 type FileConcurrencyConfig struct {
@@ -72,10 +141,90 @@ type fileModuleBinding struct {
 	LLMProfile string
 	Retries    int
 	Options    map[string]any
-	References map[string]string
+	References map[string]fileReferenceSource
 	Validators pipeline.ValidatorOverride
 }
 
+type fileReferenceSource struct {
+	path     string
+	artifact *pipeline.ArtifactReference
+}
+
+func (source *fileReferenceSource) UnmarshalYAML(node *yaml.Node) error {
+	if source == nil {
+		return fmt.Errorf("reference source must not be nil")
+	}
+	switch node.Kind {
+	case yaml.ScalarNode:
+		if node.Tag != "!!str" {
+			return fmt.Errorf("external reference path must be a string")
+		}
+		path := strings.TrimSpace(node.Value)
+		if path == "" {
+			return fmt.Errorf("external reference path must not be empty")
+		}
+		source.path = path
+		source.artifact = nil
+		return nil
+	case yaml.MappingNode:
+		if len(node.Content) != 2 || node.Content[0].Value != "artifact" {
+			return fmt.Errorf("reference source mapping must contain only artifact")
+		}
+		artifactNode := node.Content[1]
+		if artifactNode.Kind != yaml.MappingNode {
+			return fmt.Errorf("artifact reference must be an object")
+		}
+		var step, lane string
+		seen := map[string]bool{}
+		for i := 0; i < len(artifactNode.Content); i += 2 {
+			key := artifactNode.Content[i].Value
+			value := artifactNode.Content[i+1]
+			if seen[key] {
+				return fmt.Errorf("artifact reference field %q is duplicated", key)
+			}
+			seen[key] = true
+			if value.Tag != "!!str" {
+				return fmt.Errorf("artifact reference field %q must be a string", key)
+			}
+			switch key {
+			case "step":
+				step = strings.TrimSpace(value.Value)
+			case "lane":
+				lane = strings.TrimSpace(value.Value)
+			default:
+				return fmt.Errorf("field %s not found in artifact reference", key)
+			}
+		}
+		if step == "" || lane == "" {
+			return fmt.Errorf("artifact reference step and lane must not be empty")
+		}
+		source.path = ""
+		source.artifact = &pipeline.ArtifactReference{Step: step, Lane: lane}
+		return nil
+	default:
+		return fmt.Errorf("reference source must be a string or object")
+	}
+}
+
+func (source fileReferenceSource) toPipelineSource() pipeline.ReferenceSource {
+	if source.artifact != nil {
+		artifact := *source.artifact
+		return pipeline.ReferenceSource{Artifact: &artifact}
+	}
+	return pipeline.ExternalReference(source.path)
+}
+
+func fileReferenceSourcesToPipeline(values map[string]fileReferenceSource) map[string]pipeline.ReferenceSource {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make(map[string]pipeline.ReferenceSource, len(values))
+	for key, value := range values {
+		out[strings.TrimSpace(key)] = value.toPipelineSource()
+	}
+	return out
+}
+
 func (b *fileModuleBinding) UnmarshalYAML(node *yaml.Node) error {
 	switch node.Kind {
 	case yaml.ScalarNode:
@@ -115,7 +264,7 @@ func (b *fileModuleBinding) UnmarshalYAML(node *yaml.Node) error {
 				}
 				b.Options = normalizeOptions(options)
 			case "references":
-				var references map[string]string
+				var references map[string]fileReferenceSource
 				if err := valueNode.Decode(&references); err != nil {
 					return err
 				}
@@ -146,7 +295,7 @@ func (b fileModuleBinding) toPipelineBinding() pipeline.ModuleBinding {
 		LLMProfile: strings.TrimSpace(b.LLMProfile),
 		Retries:    b.Retries,
 		Options:    cloneOptions(b.Options),
-		References: normalizedStringMap(b.References),
+		References: fileReferenceSourcesToPipeline(b.References),
 		Validators: b.Validators,
 	}
 }
@@ -214,10 +363,49 @@ func (c *Config) applyFileConfigWithLookup(fileCfg FileConfig, lookup func(strin
 	}
 	for _, pipelineID := range pipelineIDs {
 		filePipeline := fileCfg.Pipelines[rawPipelineIDs[pipelineID]]
+		hasArtifacts := filePipeline.artifactsSet || filePipeline.Artifacts != nil
+		hasSteps := filePipeline.stepsSet || filePipeline.Steps != nil
+		if hasArtifacts && hasSteps {
+			return fmt.Errorf("pipeline %q must not declare both artifacts and steps", pipelineID)
+		}
+		if hasSteps && len(filePipeline.Steps) == 0 {
+			return fmt.Errorf("pipeline %q must declare at least one ordered step", pipelineID)
+		}
+		if hasSteps {
+			seenSteps := make(map[string]struct{}, len(filePipeline.Steps))
+			seenLanes := make(map[string]struct{})
+			for index, step := range filePipeline.Steps {
+				stepID := strings.TrimSpace(step.ID)
+				if stepID == "" {
+					return fmt.Errorf("pipeline %q step[%d] id must not be empty", pipelineID, index)
+				}
+				if _, ok := seenSteps[stepID]; ok {
+					return fmt.Errorf("pipeline %q step id %q is duplicated after trimming", pipelineID, stepID)
+				}
+				seenSteps[stepID] = struct{}{}
+				laneIDs, rawLaneIDs, err := normalizedMapKeys(step.Artifacts, fmt.Sprintf("pipeline %q step %q artifact lane id", pipelineID, stepID))
+				if err != nil {
+					return err
+				}
+				for _, laneID := range laneIDs {
+					if _, ok := seenLanes[laneID]; ok {
+						return fmt.Errorf("pipeline %q artifact lane id %q is duplicated across steps", pipelineID, laneID)
+					}
+					seenLanes[laneID] = struct{}{}
+					fileLane := step.Artifacts[rawLaneIDs[laneID]]
+					if err := validateFileLaneReferences(pipelineID, stepID, laneID, fileLane); err != nil {
+						return err
+					}
+				}
+				if err := validateFileReferenceSources(step.References, fmt.Sprintf("pipeline %q step %q reference slot", pipelineID, stepID)); err != nil {
+					return err
+				}
+			}
+		}
 		if _, _, err := normalizedMapKeys(filePipeline.Artifacts, fmt.Sprintf("pipeline %q artifact lane id", pipelineID)); err != nil {
 			return err
 		}
-		if _, _, err := normalizedMapKeys(filePipeline.References, fmt.Sprintf("pipeline %q reference slot", pipelineID)); err != nil {
+		if err := validateFileReferenceSources(filePipeline.References, fmt.Sprintf("pipeline %q reference slot", pipelineID)); err != nil {
 			return err
 		}
 		if filePipeline.Chunk != nil {
@@ -281,6 +469,7 @@ func (c *Config) applyFileConfigWithLookup(fileCfg FileConfig, lookup func(strin
 
 	for _, pipelineID := range pipelineIDs {
 		filePipeline := fileCfg.Pipelines[rawPipelineIDs[pipelineID]]
+		hasSteps := filePipeline.stepsSet || filePipeline.Steps != nil
 		laneIDs, rawLaneIDs, err := normalizedMapKeys(filePipeline.Artifacts, fmt.Sprintf("pipeline %q artifact lane id", pipelineID))
 		if err != nil {
 			return err
@@ -289,7 +478,7 @@ func (c *Config) applyFileConfigWithLookup(fileCfg FileConfig, lookup func(strin
 			ID:         pipelineID,
 			Input:      filePipeline.Input.toPipelineBinding(),
 			Artifacts:  make(map[string]pipeline.ArtifactLaneProfile, len(filePipeline.Artifacts)),
-			References: normalizedStringMap(filePipeline.References),
+			References: fileReferenceSourcesToPipeline(filePipeline.References),
 		}
 		if filePipeline.Chunk != nil {
 			profile.Chunk = filePipeline.Chunk.toPipelineBinding()
@@ -300,10 +489,10 @@ func (c *Config) applyFileConfigWithLookup(fileCfg FileConfig, lookup func(strin
 		for _, laneID := range laneIDs {
 			fileLane := filePipeline.Artifacts[rawLaneIDs[laneID]]
 			extract := fileLane.Extract.toPipelineBinding()
-			extract.References = mergeStringMaps(normalizedStringMap(fileLane.References), extract.References)
+			extract.References = mergeReferenceSources(fileReferenceSourcesToPipeline(fileLane.References), extract.References)
 			lane := pipeline.ArtifactLaneProfile{
 				Extract:    extract,
-				References: normalizedStringMap(fileLane.References),
+				References: fileReferenceSourcesToPipeline(fileLane.References),
 			}
 			if fileLane.Merge != nil {
 				lane.Merge = fileLane.Merge.toPipelineBinding()
@@ -319,6 +508,42 @@ func (c *Config) applyFileConfigWithLookup(fileCfg FileConfig, lookup func(strin
 			}
 			profile.Artifacts[laneID] = lane
 		}
+		if hasSteps {
+			profile.Artifacts = nil
+			profile.Steps = make([]pipeline.PipelineStepProfile, len(filePipeline.Steps))
+			for i, fileStep := range filePipeline.Steps {
+				stepID := strings.TrimSpace(fileStep.ID)
+				step := pipeline.PipelineStepProfile{
+					ID:         stepID,
+					Artifacts:  make(map[string]pipeline.ArtifactLaneProfile, len(fileStep.Artifacts)),
+					References: fileReferenceSourcesToPipeline(fileStep.References),
+				}
+				stepLaneIDs, stepRawLaneIDs, err := normalizedMapKeys(fileStep.Artifacts, fmt.Sprintf("pipeline %q step %q artifact lane id", pipelineID, stepID))
+				if err != nil {
+					return err
+				}
+				for _, laneID := range stepLaneIDs {
+					fileLane := fileStep.Artifacts[stepRawLaneIDs[laneID]]
+					extract := fileLane.Extract.toPipelineBinding()
+					extract.References = mergeReferenceSources(fileReferenceSourcesToPipeline(fileLane.References), extract.References)
+					lane := pipeline.ArtifactLaneProfile{Extract: extract, References: fileReferenceSourcesToPipeline(fileLane.References)}
+					if fileLane.Merge != nil {
+						lane.Merge = fileLane.Merge.toPipelineBinding()
+					}
+					if fileLane.Normalize != nil {
+						lane.Normalize = fileLane.Normalize.toPipelineBinding()
+					}
+					if len(fileLane.Validators) > 0 {
+						lane.Validators = make([]pipeline.ModuleBinding, len(fileLane.Validators))
+						for index, validator := range fileLane.Validators {
+							lane.Validators[index] = validator.toPipelineBinding()
+						}
+					}
+					step.Artifacts[laneID] = lane
+				}
+				profile.Steps[i] = step
+			}
+		}
 		c.Pipelines[pipelineID] = profile
 	}
 
@@ -430,30 +655,72 @@ func normalizedMapKeys[T any](values map[string]T, keyName string) ([]string, ma
 	return keys, rawByNormalized, nil
 }
 
-func normalizedStringMap(values map[string]string) map[string]string {
-	if len(values) == 0 {
-		return nil
+func validateFileReferenceSources(values map[string]fileReferenceSource, context string) error {
+	seen := make(map[string]struct{}, len(values))
+	for rawSlot, source := range values {
+		slot := strings.TrimSpace(rawSlot)
+		if slot == "" {
+			return fmt.Errorf("%s must not be empty", context)
+		}
+		if _, ok := seen[slot]; ok {
+			return fmt.Errorf("%s %q is duplicated after trimming", context, slot)
+		}
+		seen[slot] = struct{}{}
+		if source.artifact != nil {
+			if strings.TrimSpace(source.artifact.Step) == "" || strings.TrimSpace(source.artifact.Lane) == "" {
+				return fmt.Errorf("%s %q artifact selector step and lane must not be empty", context, slot)
+			}
+			if strings.TrimSpace(source.path) != "" {
+				return fmt.Errorf("%s %q must contain either an external path or artifact selector", context, slot)
+			}
+			continue
+		}
+		if strings.TrimSpace(source.path) == "" {
+			return fmt.Errorf("%s %q source must not be empty", context, slot)
+		}
 	}
-	out := make(map[string]string, len(values))
-	keys := make([]string, 0, len(values))
-	rawByNormalized := make(map[string]string, len(values))
-	for rawKey := range values {
-		key := strings.TrimSpace(rawKey)
-		rawByNormalized[key] = rawKey
-		keys = append(keys, key)
-	}
-	sort.Strings(keys)
-	for _, key := range keys {
-		out[key] = strings.TrimSpace(values[rawByNormalized[key]])
-	}
-	return out
+	return nil
 }
 
-func mergeStringMaps(base map[string]string, override map[string]string) map[string]string {
+func validateFileLaneReferences(pipelineID, stepID, laneID string, lane FileArtifactLaneProfile) error {
+	prefix := fmt.Sprintf("pipeline %q step %q lane %q", pipelineID, stepID, laneID)
+	references := []struct {
+		label  string
+		values map[string]fileReferenceSource
+	}{
+		{label: "reference slot", values: lane.References},
+		{label: "extract reference slot", values: lane.Extract.References},
+	}
+	if lane.Merge != nil {
+		references = append(references, struct {
+			label  string
+			values map[string]fileReferenceSource
+		}{label: "merge reference slot", values: lane.Merge.References})
+	}
+	if lane.Normalize != nil {
+		references = append(references, struct {
+			label  string
+			values map[string]fileReferenceSource
+		}{label: "normalize reference slot", values: lane.Normalize.References})
+	}
+	for _, item := range references {
+		if err := validateFileReferenceSources(item.values, prefix+" "+item.label); err != nil {
+			return err
+		}
+	}
+	for index, validator := range lane.Validators {
+		if err := validateFileReferenceSources(validator.References, fmt.Sprintf("%s validator[%d] reference slot", prefix, index)); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func mergeReferenceSources(base map[string]pipeline.ReferenceSource, override map[string]pipeline.ReferenceSource) map[string]pipeline.ReferenceSource {
 	if len(base) == 0 && len(override) == 0 {
 		return nil
 	}
-	out := make(map[string]string, len(base)+len(override))
+	out := make(map[string]pipeline.ReferenceSource, len(base)+len(override))
 	for key, value := range base {
 		out[key] = value
 	}

internal/core/config/file_config_contract_test.go

@@ -142,7 +142,7 @@ pipelines:
 	}
 	if profile.Chunk.Module != "generic" || profile.Chunk.LLMProfile != "chunk-profile" || profile.Chunk.Retries != 2 ||
 		!reflect.DeepEqual(profile.Chunk.Options, map[string]any{"max_units": 25}) ||
-		!reflect.DeepEqual(profile.Chunk.References, map[string]string{"glossary": "./glossary.md"}) {
+		!reflect.DeepEqual(profile.Chunk.References, pipeline.ExternalReferenceMap(map[string]string{"glossary": "./glossary.md"})) {
 		t.Fatalf("object binding = %#v", profile.Chunk)
 	}
 	if !profile.Chunk.Validators.Set || len(profile.Chunk.Validators.Validators) != 0 {
@@ -192,33 +192,33 @@ pipelines:
             normalize-only: ./normalize.txt
 `)
 	profile := cfg.Pipelines["main"]
-	if !reflect.DeepEqual(profile.References, map[string]string{
+	if !reflect.DeepEqual(profile.References, pipeline.ExternalReferenceMap(map[string]string{
 		"pipeline-only": "./pipeline.txt",
 		"shared":        "./pipeline-shared.txt",
-	}) {
+	})) {
 		t.Fatalf("pipeline references = %#v", profile.References)
 	}
-	if !reflect.DeepEqual(profile.Chunk.References, map[string]string{"chunk-only": "./chunk.txt"}) {
+	if !reflect.DeepEqual(profile.Chunk.References, pipeline.ExternalReferenceMap(map[string]string{"chunk-only": "./chunk.txt"})) {
 		t.Fatalf("chunk references = %#v", profile.Chunk.References)
 	}
 	lane := profile.Artifacts["spells"]
-	if !reflect.DeepEqual(lane.References, map[string]string{
+	if !reflect.DeepEqual(lane.References, pipeline.ExternalReferenceMap(map[string]string{
 		"lane-only":  "./lane.txt",
 		"shared":     "./lane-shared.txt",
 		"overridden": "./lane.txt",
-	}) {
+	})) {
 		t.Fatalf("lane compatibility references = %#v", lane.References)
 	}
-	if !reflect.DeepEqual(lane.Extract.References, map[string]string{
+	if !reflect.DeepEqual(lane.Extract.References, pipeline.ExternalReferenceMap(map[string]string{
 		"lane-only":    "./lane.txt",
 		"shared":       "./lane-shared.txt",
 		"overridden":   "./extract-overridden.txt",
 		"extract-only": "./extract.txt",
-	}) {
+	})) {
 		t.Fatalf("extract references = %#v", lane.Extract.References)
 	}
-	if !reflect.DeepEqual(lane.Merge.References, map[string]string{"merge-only": "./merge.txt"}) ||
-		!reflect.DeepEqual(lane.Normalize.References, map[string]string{"normalize-only": "./normalize.txt"}) {
+	if !reflect.DeepEqual(lane.Merge.References, pipeline.ExternalReferenceMap(map[string]string{"merge-only": "./merge.txt"})) ||
+		!reflect.DeepEqual(lane.Normalize.References, pipeline.ExternalReferenceMap(map[string]string{"normalize-only": "./normalize.txt"})) {
 		t.Fatalf("merge/normalize references = %#v, %#v", lane.Merge.References, lane.Normalize.References)
 	}
 }
@@ -357,6 +357,82 @@ func TestFileConfigRejectsTrimmedKeyCollisions(t *testing.T) {
 	}
 }
 
+func TestFileConfigParsesOrderedStepsAndReferenceSources(t *testing.T) {
+	file := parseFileConfig(t, `version: 3
+pipelines:
+  session:
+    input: seriatim
+    steps:
+      - id: identify-npcs
+        artifacts:
+          npcs:
+            extract: dnd/npcs
+      - id: grounded-events
+        references:
+          npcs:
+            artifact:
+              step: identify-npcs
+              lane: npcs
+        artifacts:
+          spells:
+            extract: dnd/spells
+`)
+	cfg := Default()
+	if err := cfg.ApplyFileConfig(file); err != nil {
+		t.Fatal(err)
+	}
+	profile := cfg.Pipelines["session"]
+	if len(profile.Steps) != 2 || profile.Steps[0].ID != "identify-npcs" || profile.Steps[1].ID != "grounded-events" {
+		t.Fatalf("steps = %#v", profile.Steps)
+	}
+	source := profile.Steps[1].References["npcs"]
+	if source.Artifact == nil || source.Artifact.Step != "identify-npcs" || source.Artifact.Lane != "npcs" {
+		t.Fatalf("generated source = %#v", source)
+	}
+}
+
+func TestFileConfigRejectsAmbiguousReferenceSourceForms(t *testing.T) {
+	for _, source := range []string{
+		"artifact: {step: a, lane: b, extra: c}",
+		"artifact: {step: 1, lane: b}",
+		"1",
+	} {
+		_, err := ParseFileConfigYAML([]byte("version: 3\npipelines:\n  p:\n    input: text\n    references:\n      slot: " + source + "\n"))
+		if err == nil {
+			t.Fatalf("ParseFileConfigYAML(%q) error = nil", source)
+		}
+	}
+}
+
+func TestFileConfigRejectsEmptyAndAmbiguousPipelineShapes(t *testing.T) {
+	tests := []struct {
+		name string
+		yaml string
+		want string
+	}{
+		{
+			name: "empty steps",
+			yaml: "version: 3\npipelines:\n  p:\n    input: text\n    steps: []\n",
+			want: "at least one ordered step",
+		},
+		{
+			name: "both forms",
+			yaml: "version: 3\npipelines:\n  p:\n    input: text\n    artifacts: {}\n    steps: []\n",
+			want: "both artifacts and steps",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			file := parseFileConfig(t, tt.yaml)
+			cfg := Default()
+			err := cfg.ApplyFileConfig(file)
+			if err == nil || !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("ApplyFileConfig() error = %v, want context %q", err, tt.want)
+			}
+		})
+	}
+}
+
 func TestLoadFileConfigReportsPathAndOperationContext(t *testing.T) {
 	dir := t.TempDir()
 	missing := filepath.Join(dir, "missing.yml")

internal/core/config/redaction.go

@@ -42,10 +42,16 @@ func cloneResolvedPipeline(in pipeline.ResolvedPipeline) pipeline.ResolvedPipeli
 			out.ValidatorChains[i] = cloneResolvedValidatorChain(chain)
 		}
 	}
-	if len(in.ArtifactLanes) > 0 {
-		out.ArtifactLanes = make([]pipeline.ResolvedArtifactLane, len(in.ArtifactLanes))
-		for i, lane := range in.ArtifactLanes {
-			out.ArtifactLanes[i] = cloneResolvedArtifactLane(lane)
+	if len(in.Steps) > 0 {
+		out.Steps = make([]pipeline.ResolvedPipelineStep, len(in.Steps))
+		for i, step := range in.Steps {
+			out.Steps[i] = pipeline.ResolvedPipelineStep{ID: step.ID}
+			if len(step.ArtifactLanes) > 0 {
+				out.Steps[i].ArtifactLanes = make([]pipeline.ResolvedArtifactLane, len(step.ArtifactLanes))
+				for j, lane := range step.ArtifactLanes {
+					out.Steps[i].ArtifactLanes[j] = cloneResolvedArtifactLane(lane)
+				}
+			}
 		}
 	}
 	return out
@@ -89,14 +95,20 @@ func redactConfig(cfg Config) Config {
 		profile.Input = redactBinding(profile.Input)
 		profile.Chunk = redactBinding(profile.Chunk)
 		profile.Output = redactBinding(profile.Output)
-		for laneID, lane := range profile.Artifacts {
-			lane.Extract = redactBinding(lane.Extract)
-			lane.Merge = redactBinding(lane.Merge)
-			lane.Normalize = redactBinding(lane.Normalize)
-			for i := range lane.Validators {
-				lane.Validators[i] = redactBinding(lane.Validators[i])
+		redactLanes := func(lanes map[string]pipeline.ArtifactLaneProfile) {
+			for laneID, lane := range lanes {
+				lane.Extract = redactBinding(lane.Extract)
+				lane.Merge = redactBinding(lane.Merge)
+				lane.Normalize = redactBinding(lane.Normalize)
+				for i := range lane.Validators {
+					lane.Validators[i] = redactBinding(lane.Validators[i])
+				}
+				lanes[laneID] = lane
 			}
-			profile.Artifacts[laneID] = lane
+		}
+		redactLanes(profile.Artifacts)
+		for i := range profile.Steps {
+			redactLanes(profile.Steps[i].Artifacts)
 		}
 		cfg.Pipelines[id] = profile
 	}

internal/core/config/redaction_test.go

@@ -24,16 +24,19 @@ func TestRedactedResolvedPipelinePayloadRedactsEveryBinding(t *testing.T) {
 		Input:           bindings["input"],
 		Chunk:           bindings["chunk"],
 		ChunkReferences: redactionTestReferenceTarget(pipeline.StageChunk, "", "chunk-reference-content"),
-		ArtifactLanes: []pipeline.ResolvedArtifactLane{{
-			ID:                  "safe-lane",
-			ArtifactKind:        "safe/artifact",
-			Extract:             bindings["extract"],
-			Merge:               bindings["merge"],
-			Normalize:           bindings["normalize"],
-			Validators:          []pipeline.ModuleBinding{bindings["lane-validator"]},
-			ExtractReferences:   redactionTestReferenceTarget(pipeline.StageExtract, "safe-lane", "extract-reference-content"),
-			MergeReferences:     redactionTestReferenceTarget(pipeline.StageMerge, "safe-lane", "merge-reference-content"),
-			NormalizeReferences: redactionTestReferenceTarget(pipeline.StageNormalize, "safe-lane", "normalize-reference-content"),
+		Steps: []pipeline.ResolvedPipelineStep{{
+			ID: "default",
+			ArtifactLanes: []pipeline.ResolvedArtifactLane{{
+				ID:                  "safe-lane",
+				ArtifactKind:        "safe/artifact",
+				Extract:             bindings["extract"],
+				Merge:               bindings["merge"],
+				Normalize:           bindings["normalize"],
+				Validators:          []pipeline.ModuleBinding{bindings["lane-validator"]},
+				ExtractReferences:   redactionTestReferenceTarget(pipeline.StageExtract, "safe-lane", "extract-reference-content"),
+				MergeReferences:     redactionTestReferenceTarget(pipeline.StageMerge, "safe-lane", "merge-reference-content"),
+				NormalizeReferences: redactionTestReferenceTarget(pipeline.StageNormalize, "safe-lane", "normalize-reference-content"),
+			}},
 		}},
 		ValidatorChains: []pipeline.ResolvedValidatorChain{{
 			Stage:     pipeline.StageExtract,
@@ -142,12 +145,15 @@ func TestRedactedSummaryPayloadsCoverEveryEffectiveConfigBinding(t *testing.T) {
 			Input:  bindings["input"],
 			Chunk:  bindings["chunk"],
 			Output: bindings["output"],
-			ArtifactLanes: []pipeline.ResolvedArtifactLane{{
-				ID:         "safe-lane",
-				Extract:    bindings["extract"],
-				Merge:      bindings["merge"],
-				Normalize:  bindings["normalize"],
-				Validators: []pipeline.ModuleBinding{bindings["lane-validator"]},
+			Steps: []pipeline.ResolvedPipelineStep{{
+				ID: "default",
+				ArtifactLanes: []pipeline.ResolvedArtifactLane{{
+					ID:         "safe-lane",
+					Extract:    bindings["extract"],
+					Merge:      bindings["merge"],
+					Normalize:  bindings["normalize"],
+					Validators: []pipeline.ModuleBinding{bindings["lane-validator"]},
+				}},
 			}},
 		},
 	}

internal/core/config/validation.go

@@ -106,30 +106,60 @@ func validatePipelineProfiles(profiles map[string]pipeline.PipelineProfile) erro
 		if err := validateReferenceMap(id, "", profile.References); err != nil {
 			return err
 		}
-		seenLanes := make(map[string]struct{}, len(profile.Artifacts))
-		for rawLaneID, lane := range profile.Artifacts {
-			laneID := strings.TrimSpace(rawLaneID)
-			if laneID == "" {
-				return fmt.Errorf("pipeline %q artifact lane id must not be empty", id)
+		explicitSteps := profile.Steps != nil
+		if len(profile.Artifacts) > 0 && explicitSteps {
+			return fmt.Errorf("pipeline %q must not declare both artifacts and steps", id)
+		}
+		steps := profile.Steps
+		if !explicitSteps {
+			steps = []pipeline.PipelineStepProfile{{ID: "default", Artifacts: profile.Artifacts}}
+		}
+		if explicitSteps && len(steps) == 0 {
+			return fmt.Errorf("pipeline %q must declare at least one ordered step", id)
+		}
+		seenSteps := make(map[string]struct{}, len(steps))
+		seenLanes := make(map[string]struct{})
+		for index, step := range steps {
+			stepID := strings.TrimSpace(step.ID)
+			if stepID == "" {
+				return fmt.Errorf("pipeline %q step[%d] id must not be empty", id, index)
 			}
-			if _, ok := seenLanes[laneID]; ok {
-				return fmt.Errorf("pipeline %q artifact lane id %q is duplicated after trimming", id, laneID)
+			if _, ok := seenSteps[stepID]; ok {
+				return fmt.Errorf("pipeline %q step id %q is duplicated after trimming", id, stepID)
 			}
-			seenLanes[laneID] = struct{}{}
-			if err := validateReferenceMap(id, laneID, lane.References); err != nil {
-				return err
+			seenSteps[stepID] = struct{}{}
+			if explicitSteps {
+				if err := validateReferenceMapForContext(id, "", "step "+stepID, step.References, true); err != nil {
+					return err
+				}
 			}
-			if err := validateBinding(id, laneID, "extract", lane.Extract, true); err != nil {
-				return err
-			}
-			if err := validateBinding(id, laneID, "merge", lane.Merge, true); err != nil {
-				return err
-			}
-			if err := validateBinding(id, laneID, "normalize", lane.Normalize, true); err != nil {
-				return err
-			}
-			if len(lane.Validators) > 0 {
-				return fmt.Errorf("pipeline %q lane %q validators are not supported at artifact lane level; use extract.validators, merge.validators, or normalize.validators", id, laneID)
+			for rawLaneID, lane := range step.Artifacts {
+				laneID := strings.TrimSpace(rawLaneID)
+				if laneID == "" {
+					return fmt.Errorf("pipeline %q artifact lane id must not be empty", id)
+				}
+				if _, ok := seenLanes[laneID]; ok {
+					if !explicitSteps {
+						return fmt.Errorf("pipeline %q artifact lane id %q is duplicated after trimming", id, laneID)
+					}
+					return fmt.Errorf("pipeline %q artifact lane id %q is duplicated across steps", id, laneID)
+				}
+				seenLanes[laneID] = struct{}{}
+				if err := validateReferenceMapForContext(id, laneID, "", lane.References, true); err != nil {
+					return err
+				}
+				if err := validateBinding(id, laneID, "extract", lane.Extract, true); err != nil {
+					return err
+				}
+				if err := validateBinding(id, laneID, "merge", lane.Merge, true); err != nil {
+					return err
+				}
+				if err := validateBinding(id, laneID, "normalize", lane.Normalize, true); err != nil {
+					return err
+				}
+				if len(lane.Validators) > 0 {
+					return fmt.Errorf("pipeline %q lane %q validators are not supported at artifact lane level; use extract.validators, merge.validators, or normalize.validators", id, laneID)
+				}
 			}
 		}
 	}
@@ -164,7 +194,7 @@ func validateBinding(
 		}
 		return fmt.Errorf("pipeline %q %s references are not supported", pipelineID, slot)
 	}
-	return validateReferenceMapForContext(pipelineID, laneID, slot, binding.References)
+	return validateReferenceMapForContext(pipelineID, laneID, slot, binding.References, true)
 }
 
 func validateValidatorOverride(pipelineID string, laneID string, slot string, override pipeline.ValidatorOverride) error {
@@ -197,13 +227,13 @@ func validateValidatorOverride(pipelineID string, laneID string, slot string, ov
 	return nil
 }
 
-func validateReferenceMap(pipelineID string, laneID string, references map[string]string) error {
-	return validateReferenceMapForContext(pipelineID, laneID, "", references)
+func validateReferenceMap(pipelineID string, laneID string, references map[string]pipeline.ReferenceSource) error {
+	return validateReferenceMapForContext(pipelineID, laneID, "", references, false)
 }
 
-func validateReferenceMapForContext(pipelineID string, laneID string, slot string, references map[string]string) error {
+func validateReferenceMapForContext(pipelineID string, laneID string, slot string, references map[string]pipeline.ReferenceSource, generatedAllowed bool) error {
 	seen := make(map[string]struct{}, len(references))
-	for rawSlotName, rawSource := range references {
+	for rawSlotName, source := range references {
 		slotName := strings.TrimSpace(rawSlotName)
 		if slotName == "" {
 			return fmt.Errorf("%s reference slot name must not be empty", referenceContext(pipelineID, laneID, slot))
@@ -212,7 +242,19 @@ func validateReferenceMapForContext(pipelineID string, laneID string, slot strin
 			return fmt.Errorf("%s reference slot %q is duplicated after trimming", referenceContext(pipelineID, laneID, slot), slotName)
 		}
 		seen[slotName] = struct{}{}
-		if strings.TrimSpace(rawSource) == "" {
+		if source.Artifact != nil {
+			if !generatedAllowed {
+				return fmt.Errorf("%s reference slot %q must use an external path", referenceContext(pipelineID, laneID, slot), slotName)
+			}
+			if strings.TrimSpace(source.Artifact.Step) == "" || strings.TrimSpace(source.Artifact.Lane) == "" {
+				return fmt.Errorf("%s reference slot %q artifact selector step and lane must not be empty", referenceContext(pipelineID, laneID, slot), slotName)
+			}
+			if strings.TrimSpace(source.Path) != "" {
+				return fmt.Errorf("%s reference slot %q must contain exactly one source form", referenceContext(pipelineID, laneID, slot), slotName)
+			}
+			continue
+		}
+		if strings.TrimSpace(source.Path) == "" {
 			return fmt.Errorf("%s reference slot %q source must not be empty", referenceContext(pipelineID, laneID, slot), slotName)
 		}
 	}

internal/core/config/validation_contract_test.go

@@ -200,7 +200,7 @@ func TestValidateIdentifiersAfterTrimming(t *testing.T) {
 			name: "empty reference slot",
 			setup: func(cfg *Config) {
 				profile := validationProfile()
-				profile.References = map[string]string{" ": "source.txt"}
+				profile.References = pipeline.ExternalReferenceMap(map[string]string{" ": "source.txt"})
 				cfg.Pipelines = map[string]pipeline.PipelineProfile{"main": profile}
 			},
 			want: "reference slot name must not be empty",
@@ -209,7 +209,7 @@ func TestValidateIdentifiersAfterTrimming(t *testing.T) {
 			name: "duplicate reference slots",
 			setup: func(cfg *Config) {
 				profile := validationProfile()
-				profile.References = map[string]string{"slot": "one.txt", " slot ": "two.txt"}
+				profile.References = pipeline.ExternalReferenceMap(map[string]string{"slot": "one.txt", " slot ": "two.txt"})
 				cfg.Pipelines = map[string]pipeline.PipelineProfile{"main": profile}
 			},
 			want: "reference slot \"slot\" is duplicated after trimming",
@@ -267,14 +267,14 @@ func TestValidateReferencesAreUnsupportedOnInputAndOutput(t *testing.T) {
 		{
 			name: "input references",
 			set: func(profile *pipeline.PipelineProfile) {
-				profile.Input.References = map[string]string{"slot": "source.txt"}
+				profile.Input.References = pipeline.ExternalReferenceMap(map[string]string{"slot": "source.txt"})
 			},
 			want: "input references are not supported",
 		},
 		{
 			name: "output references",
 			set: func(profile *pipeline.PipelineProfile) {
-				profile.Output.References = map[string]string{"slot": "source.txt"}
+				profile.Output.References = pipeline.ExternalReferenceMap(map[string]string{"slot": "source.txt"})
 			},
 			want: "output references are not supported",
 		},
@@ -326,7 +326,7 @@ func TestValidateValidatorBindingRules(t *testing.T) {
 					Set: true,
 					Validators: []pipeline.ModuleBinding{{
 						Module:     "validator",
-						References: map[string]string{"slot": "source.txt"},
+						References: pipeline.ExternalReferenceMap(map[string]string{"slot": "source.txt"}),
 					}},
 				}
 			},