Make command line references pipeline scoped

internal/cli/run.go

@@ -177,7 +177,7 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i
 	fs.Var(&llmProfile, "llm-profile", "LLM profile override")
 	fs.Var(&reasoningEffort, "reasoning-effort", "reasoning effort override")
 	fs.Var(&chunkCache, "chunk_cache", "chunk plan cache mode: auto, bypass, or refresh")
-	fs.Var(&referenceFlags, "reference", "reference binding, as slot=path, chunk.slot=path, merge.slot=path, lane.slot=path, lane.extract.slot=path, lane.merge.slot=path, or lane.normalize.slot=path")
+	fs.Var(&referenceFlags, "reference", "reference binding, as slot=path, chunk.slot=path, lane.slot=path, lane.extract.slot=path, lane.merge.slot=path, or lane.normalize.slot=path")
 	fs.Var(&withoutReferenceFlags, "without-reference", "unbind a reference, using the same selector forms as --reference")
 	fs.Var(&recomputeStep, "recompute-step", "recompute one ordered pipeline step and dependent lanes")
 	if err := validateRunFlagValues(args); err != nil {
@@ -1287,11 +1287,21 @@ type cliReferenceUnbindRequest struct {
 }
 
 type cliReferenceSelector struct {
+	Scope    cliReferenceSelectorScope
 	LaneID   string
 	Stage    pipeline.ModuleStage
 	SlotName string
 }
 
+type cliReferenceSelectorScope uint8
+
+const (
+	cliReferenceScopePipeline cliReferenceSelectorScope = iota
+	cliReferenceScopeLane
+	cliReferenceScopeChunk
+	cliReferenceScopeBinding
+)
+
 func parseReferenceFlags(values []string) ([]cliReferenceRequest, error) {
 	if len(values) == 0 {
 		return nil, nil
@@ -1300,7 +1310,7 @@ func parseReferenceFlags(values []string) ([]cliReferenceRequest, error) {
 	for _, raw := range values {
 		name, source, ok := strings.Cut(raw, "=")
 		if !ok {
-			return nil, fmt.Errorf("--reference must use slot=path or lane.slot=path")
+			return nil, fmt.Errorf("--reference must use slot=path, lane.slot=path, or lane.stage.slot=path")
 		}
 		if strings.TrimSpace(source) == "" {
 			return nil, fmt.Errorf("--reference path must not be empty; use --without-reference to unbind")
@@ -1350,17 +1360,14 @@ func parseReferenceSelector(raw string, flagName string) (cliReferenceSelector,
 	}
 	switch len(parts) {
 	case 1:
-		return cliReferenceSelector{SlotName: strings.TrimSpace(parts[0])}, nil
+		return cliReferenceSelector{Scope: cliReferenceScopePipeline, SlotName: strings.TrimSpace(parts[0])}, nil
 	case 2:
 		first := strings.TrimSpace(parts[0])
 		slotName := strings.TrimSpace(parts[1])
 		if first == string(pipeline.StageChunk) {
-			return cliReferenceSelector{Stage: pipeline.StageChunk, SlotName: slotName}, nil
+			return cliReferenceSelector{Scope: cliReferenceScopeChunk, Stage: pipeline.StageChunk, SlotName: slotName}, nil
 		}
-		if first == string(pipeline.StageMerge) {
-			return cliReferenceSelector{Stage: pipeline.StageMerge, SlotName: slotName}, nil
-		}
-		return cliReferenceSelector{LaneID: first, SlotName: slotName}, nil
+		return cliReferenceSelector{Scope: cliReferenceScopeLane, LaneID: first, SlotName: slotName}, nil
 	case 3:
 		laneID := strings.TrimSpace(parts[0])
 		stage := pipeline.ModuleStage(strings.TrimSpace(parts[1]))
@@ -1368,9 +1375,9 @@ func parseReferenceSelector(raw string, flagName string) (cliReferenceSelector,
 		if stage != pipeline.StageExtract && stage != pipeline.StageMerge && stage != pipeline.StageNormalize {
 			return cliReferenceSelector{}, fmt.Errorf("%s lane-qualified selector must use lane.extract.slot, lane.merge.slot, or lane.normalize.slot", flagName)
 		}
-		return cliReferenceSelector{LaneID: laneID, Stage: stage, SlotName: slotName}, nil
+		return cliReferenceSelector{Scope: cliReferenceScopeBinding, LaneID: laneID, Stage: stage, SlotName: slotName}, nil
 	default:
-		return cliReferenceSelector{}, fmt.Errorf("%s must use slot, chunk.slot, merge.slot, lane.slot, lane.extract.slot, lane.merge.slot, or lane.normalize.slot", flagName)
+		return cliReferenceSelector{}, fmt.Errorf("%s must use slot, chunk.slot, lane.slot, lane.extract.slot, lane.merge.slot, or lane.normalize.slot", flagName)
 	}
 }
 
@@ -1391,37 +1398,153 @@ func resolveCLIReferenceRequests(
 		return nil, nil, err
 	}
 
-	overrides := make([]pipeline.ReferenceBinding, 0, len(referenceRequests))
+	// Broad CLI selectors are only presentation syntax. Collapse them into one
+	// highest-specificity action per concrete framework target before pipeline
+	// resolution so the generic reference contract stays stage-and-lane exact.
+	actions := make(map[cliReferenceTargetKey]resolvedCLIReferenceAction)
 	for _, request := range referenceRequests {
-		target, err := resolveCLIReferenceTarget(targets, request.Selector)
+		matches, err := resolveCLIReferenceTargets(targets, request.Selector)
 		if err != nil {
 			return nil, nil, err
 		}
-		overrides = append(overrides, pipeline.ReferenceBinding{
-			Stage:         target.stage,
-			LaneID:        target.laneID,
-			SlotName:      request.Selector.SlotName,
-			Source:        request.Source,
-			BindingSource: contracts.ReferenceBindingSourceCLI,
-		})
+		for _, target := range matches {
+			candidate := resolvedCLIReferenceAction{
+				kind:        cliReferenceActionBind,
+				selector:    request.Selector,
+				target:      target,
+				slotName:    request.Selector.SlotName,
+				source:      request.Source,
+				specificity: request.Selector.specificity(),
+			}
+			if err := mergeCLIReferenceAction(actions, candidate); err != nil {
+				return nil, nil, err
+			}
+		}
 	}
-
-	unbinds := make([]pipeline.ReferenceUnbind, 0, len(unbindRequests))
 	for _, request := range unbindRequests {
-		target, err := resolveCLIReferenceTarget(targets, request.Selector)
+		matches, err := resolveCLIReferenceTargets(targets, request.Selector)
 		if err != nil {
 			return nil, nil, err
 		}
-		unbinds = append(unbinds, pipeline.ReferenceUnbind{
-			Stage:    target.stage,
-			LaneID:   target.laneID,
-			SlotName: request.Selector.SlotName,
-		})
+		for _, target := range matches {
+			candidate := resolvedCLIReferenceAction{
+				kind:        cliReferenceActionUnbind,
+				selector:    request.Selector,
+				target:      target,
+				slotName:    request.Selector.SlotName,
+				specificity: request.Selector.specificity(),
+			}
+			if err := mergeCLIReferenceAction(actions, candidate); err != nil {
+				return nil, nil, err
+			}
+		}
 	}
 
+	resolved := make([]resolvedCLIReferenceAction, 0, len(actions))
+	for _, action := range actions {
+		resolved = append(resolved, action)
+	}
+	sort.Slice(resolved, func(i, j int) bool {
+		left, right := resolved[i], resolved[j]
+		if left.target.laneID != right.target.laneID {
+			return left.target.laneID < right.target.laneID
+		}
+		if left.target.stage != right.target.stage {
+			return referenceStageOrder(left.target.stage) < referenceStageOrder(right.target.stage)
+		}
+		return left.slotName < right.slotName
+	})
+
+	overrides := make([]pipeline.ReferenceBinding, 0, len(resolved))
+	unbinds := make([]pipeline.ReferenceUnbind, 0, len(resolved))
+	for _, action := range resolved {
+		switch action.kind {
+		case cliReferenceActionBind:
+			overrides = append(overrides, pipeline.ReferenceBinding{
+				Stage:         action.target.stage,
+				LaneID:        action.target.laneID,
+				SlotName:      action.slotName,
+				Source:        action.source,
+				BindingSource: contracts.ReferenceBindingSourceCLI,
+			})
+		case cliReferenceActionUnbind:
+			unbinds = append(unbinds, pipeline.ReferenceUnbind{
+				Stage:    action.target.stage,
+				LaneID:   action.target.laneID,
+				SlotName: action.slotName,
+			})
+		}
+	}
 	return overrides, unbinds, nil
 }
 
+type cliReferenceActionKind uint8
+
+const (
+	cliReferenceActionBind cliReferenceActionKind = iota
+	cliReferenceActionUnbind
+)
+
+type cliReferenceTargetKey struct {
+	stage    pipeline.ModuleStage
+	laneID   string
+	slotName string
+}
+
+type resolvedCLIReferenceAction struct {
+	kind        cliReferenceActionKind
+	selector    cliReferenceSelector
+	target      selectedReferenceTarget
+	slotName    string
+	source      string
+	specificity int
+}
+
+func mergeCLIReferenceAction(actions map[cliReferenceTargetKey]resolvedCLIReferenceAction, candidate resolvedCLIReferenceAction) error {
+	key := cliReferenceTargetKey{stage: candidate.target.stage, laneID: candidate.target.laneID, slotName: candidate.slotName}
+	current, ok := actions[key]
+	if !ok || candidate.specificity > current.specificity {
+		actions[key] = candidate
+		return nil
+	}
+	if candidate.specificity < current.specificity {
+		return nil
+	}
+	if candidate.kind != current.kind {
+		return fmt.Errorf("reference target %q slot %q is both bound by %q and unbound by %q at the same specificity", targetLabel(candidate.target), candidate.slotName, current.selector.String(), candidate.selector.String())
+	}
+	actions[key] = candidate
+	return nil
+}
+
+func (selector cliReferenceSelector) specificity() int {
+	switch selector.Scope {
+	case cliReferenceScopePipeline:
+		return 0
+	case cliReferenceScopeLane:
+		return 1
+	case cliReferenceScopeChunk, cliReferenceScopeBinding:
+		return 2
+	default:
+		return -1
+	}
+}
+
+func (selector cliReferenceSelector) String() string {
+	switch selector.Scope {
+	case cliReferenceScopePipeline:
+		return selector.SlotName
+	case cliReferenceScopeLane:
+		return selector.LaneID + "." + selector.SlotName
+	case cliReferenceScopeChunk:
+		return "chunk." + selector.SlotName
+	case cliReferenceScopeBinding:
+		return selector.LaneID + "." + string(selector.Stage) + "." + selector.SlotName
+	default:
+		return selector.SlotName
+	}
+}
+
 type selectedReferenceTarget struct {
 	laneID string
 	stage  pipeline.ModuleStage
@@ -1638,114 +1761,77 @@ func referenceSlotSet(slots []contracts.ReferenceSlot) map[string]struct{} {
 	return slotSet
 }
 
-func resolveCLIReferenceTarget(targets []selectedReferenceTarget, selector cliReferenceSelector) (selectedReferenceTarget, error) {
+func resolveCLIReferenceTargets(targets []selectedReferenceTarget, selector cliReferenceSelector) ([]selectedReferenceTarget, error) {
 	slotName := strings.TrimSpace(selector.SlotName)
 	if slotName == "" {
-		return selectedReferenceTarget{}, fmt.Errorf("reference slot must not be empty")
+		return nil, fmt.Errorf("reference slot must not be empty")
 	}
-	if selector.Stage == pipeline.StageChunk {
+	switch selector.Scope {
+	case cliReferenceScopePipeline:
+		matches := make([]selectedReferenceTarget, 0, len(targets))
+		for _, target := range targets {
+			if _, ok := target.slots[slotName]; ok {
+				matches = append(matches, target)
+			}
+		}
+		if len(matches) == 0 {
+			return nil, fmt.Errorf("reference slot %q is not declared by any selected target", slotName)
+		}
+		return matches, nil
+	case cliReferenceScopeChunk:
 		for _, target := range targets {
 			if target.stage != pipeline.StageChunk {
 				continue
 			}
 			if _, ok := target.slots[slotName]; !ok {
-				return selectedReferenceTarget{}, fmt.Errorf("reference slot %q is not declared by chunk module %q", slotName, target.module)
+				return nil, fmt.Errorf("reference slot %q is not declared by chunk module %q", slotName, target.module)
 			}
-			return target, nil
-		}
-		return selectedReferenceTarget{}, fmt.Errorf("reference chunk target is not selected")
-	}
-	if selector.Stage == pipeline.StageExtract || selector.Stage == pipeline.StageMerge || selector.Stage == pipeline.StageNormalize {
-		if selector.LaneID == "" && selector.Stage == pipeline.StageMerge {
-			return resolveCLIReferenceStageTarget(targets, selector.Stage, slotName)
+			return []selectedReferenceTarget{target}, nil
 		}
+		return nil, fmt.Errorf("reference chunk target is not selected")
+	case cliReferenceScopeLane:
+		laneSelected := false
+		matches := make([]selectedReferenceTarget, 0, 3)
 		for _, target := range targets {
-			if target.laneID == selector.LaneID && target.stage == selector.Stage {
-				if _, ok := target.slots[slotName]; !ok {
-					return selectedReferenceTarget{}, fmt.Errorf("reference slot %q is not declared by selected %s target %q", slotName, selector.Stage, targetLabel(target))
-				}
-				return target, nil
+			if target.laneID != selector.LaneID {
+				continue
+			}
+			laneSelected = true
+			if _, ok := target.slots[slotName]; ok {
+				matches = append(matches, target)
 			}
 		}
-		return selectedReferenceTarget{}, fmt.Errorf("reference lane %q is not selected", selector.LaneID)
-	}
-	if strings.TrimSpace(selector.LaneID) != "" {
-		return resolveCLIReferenceLaneTarget(targets, strings.TrimSpace(selector.LaneID), slotName)
-	}
-	return resolveCLIReferenceFlatTarget(targets, slotName)
-}
-
-func resolveCLIReferenceStageTarget(targets []selectedReferenceTarget, stage pipeline.ModuleStage, slotName string) (selectedReferenceTarget, error) {
-	matches := make([]selectedReferenceTarget, 0, 2)
-	for _, target := range targets {
-		if target.stage != stage {
-			continue
+		if !laneSelected {
+			return nil, fmt.Errorf("reference lane %q is not selected", selector.LaneID)
 		}
-		if _, ok := target.slots[slotName]; ok {
-			matches = append(matches, target)
+		if len(matches) == 0 {
+			return nil, fmt.Errorf("reference slot %q is not declared by selected lane %q", slotName, selector.LaneID)
 		}
-	}
-	switch len(matches) {
-	case 0:
-		return selectedReferenceTarget{}, fmt.Errorf("reference slot %q is not declared by any selected %s target", slotName, stage)
-	case 1:
-		return matches[0], nil
+		return matches, nil
+	case cliReferenceScopeBinding:
+		laneSelected := false
+		for _, target := range targets {
+			if target.laneID != selector.LaneID {
+				continue
+			}
+			laneSelected = true
+			if target.stage != selector.Stage {
+				continue
+			}
+			if _, ok := target.slots[slotName]; !ok {
+				return nil, fmt.Errorf("reference slot %q is not declared by selected %s target %q", slotName, selector.Stage, targetLabel(target))
+			}
+			return []selectedReferenceTarget{target}, nil
+		}
+		if !laneSelected {
+			return nil, fmt.Errorf("reference lane %q is not selected", selector.LaneID)
+		}
+		return nil, fmt.Errorf("reference %s target is not selected for lane %q", selector.Stage, selector.LaneID)
 	default:
-		return selectedReferenceTarget{}, fmt.Errorf("reference slot %q is declared by multiple selected %s targets (%s); use a more specific selector such as %s", slotName, stage, targetList(matches), selectorSuggestions(matches, slotName))
+		return nil, fmt.Errorf("reference selector has unknown scope")
 	}
 }
 
-func resolveCLIReferenceLaneTarget(targets []selectedReferenceTarget, laneID string, slotName string) (selectedReferenceTarget, error) {
-	laneSelected := false
-	matches := make([]selectedReferenceTarget, 0, 2)
-	for _, target := range targets {
-		if target.laneID != laneID {
-			continue
-		}
-		laneSelected = true
-		if _, ok := target.slots[slotName]; ok {
-			matches = append(matches, target)
-		}
-	}
-	if !laneSelected {
-		return selectedReferenceTarget{}, fmt.Errorf("reference lane %q is not selected", laneID)
-	}
-	switch len(matches) {
-	case 0:
-		return selectedReferenceTarget{}, fmt.Errorf("reference slot %q is not declared by selected lane %q", slotName, laneID)
-	case 1:
-		return matches[0], nil
-	default:
-		return selectedReferenceTarget{}, fmt.Errorf("reference slot %q is declared by multiple selected targets in lane %q (%s); use a more specific selector such as %s", slotName, laneID, targetList(matches), selectorSuggestions(matches, slotName))
-	}
-}
-
-func resolveCLIReferenceFlatTarget(targets []selectedReferenceTarget, slotName string) (selectedReferenceTarget, error) {
-	matches := make([]selectedReferenceTarget, 0, 2)
-	for _, target := range targets {
-		if _, ok := target.slots[slotName]; ok {
-			matches = append(matches, target)
-		}
-	}
-	switch len(matches) {
-	case 0:
-		return selectedReferenceTarget{}, fmt.Errorf("reference slot %q is not declared by any selected reference target", slotName)
-	case 1:
-		return matches[0], nil
-	default:
-		return selectedReferenceTarget{}, fmt.Errorf("reference slot %q is declared by multiple selected targets (%s); use a more specific selector such as %s", slotName, targetList(matches), selectorSuggestions(matches, slotName))
-	}
-}
-
-func targetList(targets []selectedReferenceTarget) string {
-	labels := make([]string, 0, len(targets))
-	for _, target := range targets {
-		labels = append(labels, targetLabel(target))
-	}
-	sort.Strings(labels)
-	return strings.Join(labels, ", ")
-}
-
 func targetLabel(target selectedReferenceTarget) string {
 	if target.stage == pipeline.StageChunk {
 		return "chunk"
@@ -1753,17 +1839,19 @@ func targetLabel(target selectedReferenceTarget) string {
 	return target.laneID + "." + string(target.stage)
 }
 
-func selectorSuggestions(targets []selectedReferenceTarget, slotName string) string {
-	suggestions := make([]string, 0, len(targets))
-	for _, target := range targets {
-		if target.stage == pipeline.StageChunk {
-			suggestions = append(suggestions, "chunk."+slotName)
-			continue
-		}
-		suggestions = append(suggestions, target.laneID+"."+string(target.stage)+"."+slotName)
+func referenceStageOrder(stage pipeline.ModuleStage) int {
+	switch stage {
+	case pipeline.StageChunk:
+		return 0
+	case pipeline.StageExtract:
+		return 1
+	case pipeline.StageMerge:
+		return 2
+	case pipeline.StageNormalize:
+		return 3
+	default:
+		return 4
 	}
-	sort.Strings(suggestions)
-	return strings.Join(suggestions, " or ")
 }
 
 func sortedPipelineIDs(cfg config.Config) []string {