package runner import ( "context" "errors" "fmt" "slices" "sort" "sync" "gitea.maximumdirect.net/eric/audita/v3/internal/core/chunking" "gitea.maximumdirect.net/eric/audita/v3/internal/core/config" "gitea.maximumdirect.net/eric/audita/v3/internal/core/glossary" "gitea.maximumdirect.net/eric/audita/v3/internal/core/modulecatalog" "gitea.maximumdirect.net/eric/audita/v3/internal/core/schema" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/contracts" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/outcomes" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/promptcontext" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/proposals" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/structuredoutput" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/validators" validatormetadata "gitea.maximumdirect.net/eric/audita/v3/internal/validators/metadata" ) const ( ModuleStatusSuccess = "success" ModuleStatusFailed = "failed" ) // ModuleFactory resolves one module instance for one run spec. type ModuleFactory interface { ModuleForSpec(spec contracts.ModuleRunSpec) (contracts.TranscriptModule, error) } // Runner executes module instances sequentially against a working transcript. type Runner struct { factory ModuleFactory } // ModuleResult captures deterministic per-module execution output. type ModuleResult struct { StageIndex int `json:"stage_index"` StageID *string `json:"stage_id,omitempty"` ModuleKey string `json:"module_key"` ModuleInstance string `json:"module_instance"` ReplacementPolicy proposals.ReplacementPolicy `json:"replacement_policy"` Status string `json:"status"` ValidatorDecisions []ValidatorDecisionRecord `json:"validator_decisions,omitempty"` ValidatorRejected []ValidatorRejectedChange `json:"validator_rejected,omitempty"` AppliedChanges []proposals.AppliedChange `json:"applied_changes,omitempty"` SkippedChanges []proposals.SkippedChange `json:"skipped_changes,omitempty"` ErrorMessage string `json:"error_message,omitempty"` } // WorkUnitOutcome keeps initial section identity while text evolves between // module instances. Detailed candidate and decision records are debug evidence. type WorkUnitOutcome struct { ProposalIndexOffset int `json:"-"` StageIndex int `json:"stage_index"` StageID *string `json:"stage_id,omitempty"` ModuleIndex int `json:"module_index"` ModuleKey string `json:"module_key"` ModuleInstance string `json:"module_instance"` Section contracts.SectionMetadata `json:"section"` State outcomes.WorkState `json:"state"` Failure *ExecutionFailure `json:"-"` CorrectionsApplied int `json:"corrections_applied"` Repairs []RepairOutcome `json:"-"` Operations []outcomes.Operation `json:"operations,omitempty"` } type ValidatorDecisionRecord struct { ExecutionClass validatormetadata.ExecutionClass `json:"-"` ValidatorName string `json:"validator_name"` ProposalIndex int `json:"proposal_index"` Approved bool `json:"approved"` Disposition validators.DecisionDisposition `json:"disposition"` ReasonCode string `json:"reason_code"` Message string `json:"message"` DiagnosticArtifactPath string `json:"diagnostic_artifact_path,omitempty"` } type ValidatorRejectedChange struct { ValidatorName string `json:"validator_name"` ProposalIndex int `json:"proposal_index"` ModuleKey string `json:"module_key"` ModuleInstance string `json:"module_instance"` TargetSegmentID int `json:"target_segment_id"` OriginalText string `json:"original_text"` CorrectedText string `json:"corrected_text"` Disposition validators.DecisionDisposition `json:"disposition"` ReasonCode string `json:"reason_code"` Message string `json:"message"` } // EvidenceSelection selects the detailed views consumed by the invocation. type EvidenceSelection struct { Reports bool Debug bool } type evidenceNeeds struct { reports bool decisions bool candidates bool } func selectEvidence(selection *EvidenceSelection) evidenceNeeds { if selection == nil { return evidenceNeeds{reports: true, decisions: true} } return evidenceNeeds{reports: selection.Reports, decisions: selection.Debug, candidates: selection.Debug} } // RunInput is the deterministic runner input. type RunInput struct { Config *config.Config Transcript *schema.Transcript ModuleSpecs []contracts.ModuleRunSpec Interactions structuredoutput.InteractionSink Evidence *EvidenceSelection Progress func(Progress) } // RunOutput is the deterministic runner output. type RunOutput struct { FinalTranscript *schema.Transcript `json:"-"` ModuleResults []ModuleResult `json:"module_results"` Sections []contracts.SectionMetadata `json:"sections"` Totals *outcomes.WorkTotals `json:"-"` InventoryAvailable bool `json:"-"` WorkUnits []WorkUnitOutcome `json:"work_units"` Candidates []proposals.EnrichedCorrectionProposal `json:"-"` } func New(factory ModuleFactory) *Runner { return &Runner{factory: factory} } func (r *Runner) Run(ctx context.Context, input RunInput) (RunOutput, error) { if err := ctx.Err(); err != nil { return RunOutput{FinalTranscript: input.Transcript.Clone()}, &ExecutionFailure{Phase: "processing", Cause: err} } if r == nil || r.factory == nil { return RunOutput{}, &ExecutionFailure{Phase: "setup", Cause: errors.New("runner module factory is required")} } working := input.Transcript.Clone() results := make([]ModuleResult, 0, len(input.ModuleSpecs)) sections, err := chunkWorkingTranscript(input.Config, working) if err != nil { return RunOutput{FinalTranscript: working}, &ExecutionFailure{Phase: "chunking", Cause: fmt.Errorf("chunk normalized transcript: %w", err)} } evidence := selectEvidence(input.Evidence) totals := outcomes.WorkTotals{Total: len(input.ModuleSpecs) * len(sections)} var inventory []contracts.SectionMetadata var workUnits []WorkUnitOutcome var candidates []proposals.EnrichedCorrectionProposal if evidence.reports { inventory = make([]contracts.SectionMetadata, len(sections)) for i, section := range sections { inventory[i] = contracts.SectionMetadataFromSection(section) } workUnits = make([]WorkUnitOutcome, 0, totals.Total) for moduleIndex, spec := range input.ModuleSpecs { for _, section := range inventory { workUnits = append(workUnits, newWorkUnit(spec, section, moduleIndex)) } } } snapshot := func() RunOutput { return RunOutput{ FinalTranscript: transcriptFromSections(sections), ModuleResults: results, Sections: inventory, InventoryAvailable: true, Totals: &totals, WorkUnits: workUnits, Candidates: candidates, } } for moduleIndex, spec := range input.ModuleSpecs { progress := Progress{ModuleIndex: spec.Index, ModuleKey: spec.ModuleKey, ModuleID: spec.ID} sectionCount := len(sections) progress.emit(input.Progress, "started", nil, §ionCount) var reportUnits []WorkUnitOutcome if evidence.reports { reportUnits = workUnits[moduleIndex*len(sections) : (moduleIndex+1)*len(sections)] } execution, err := r.executeModule(ctx, spec, sections, input.Interactions, evidence, reportUnits, input.Progress) units := execution.pipeline.WorkUnits if err == nil { filters := findApplyFiltering(sections, execution.pipeline.Approved, execution.skipped, execution.policy) if canceled := ctx.Err(); canceled != nil { err = locateFailure(canceled, "application", failureReference(spec, nil, ""), false, nil) } else { execution.pipeline.recordApplyFiltering(filters, evidence.reports) sections = execution.updated execution.pipeline.Totals.Started = len(sections) execution.pipeline.Totals.Completed = len(sections) execution.pipeline.Totals.Corrections = len(execution.applied) } } var failure *ExecutionFailure applicationInterrupted := errors.As(err, &failure) && failure.Phase == "application" if applicationInterrupted { execution.pipeline.Totals.Completed = 0 } totals.Add(execution.pipeline.Totals) appliedIndices := make(map[int]struct{}) if evidence.reports || evidence.candidates { for _, change := range execution.applied { appliedIndices[change.ProposalIndex] = struct{}{} } } for i := range units { unit := &units[i] unit.ModuleIndex = moduleIndex unit.Operations = reportOperations(unit.Operations) if err == nil { unit.State = outcomes.WorkCompleted if evidence.reports { unit.CorrectionsApplied = execution.appliedBySection[unit.Section.Index] } } else if applicationInterrupted && unit.State != outcomes.WorkNotStarted { unit.State = outcomes.WorkInterrupted } for j := range unit.Repairs { branch := &unit.Repairs[j] if branch.Outcome != "approved" { continue } if err != nil { branch.Outcome = "interrupted" } else if _, ok := appliedIndices[branch.ProposalIndex]; ok { branch.Outcome = "applied" } else { branch.Outcome = "approved_skipped" } } } if !evidence.reports && evidence.candidates { workUnits = append(workUnits, units...) } candidates = append(candidates, execution.pipeline.Candidates...) result := ModuleResult{ StageIndex: spec.Index, StageID: spec.ID, ModuleKey: spec.ModuleKey, ModuleInstance: spec.InstanceName, ReplacementPolicy: execution.policy, ValidatorDecisions: execution.pipeline.ValidatorDecisions, ValidatorRejected: execution.pipeline.ValidatorRejected, } if err != nil { result.Status = ModuleStatusFailed result.ErrorMessage = err.Error() } else { result.Status = ModuleStatusSuccess if evidence.decisions { result.AppliedChanges = execution.applied result.SkippedChanges = execution.skipped } } results = append(results, result) if err != nil { progress.emit(input.Progress, "failed", nil, nil) return snapshot(), fmt.Errorf("module %q failed: %w", spec.InstanceName, err) } corrections := len(execution.applied) progress.emit(input.Progress, "completed", nil, &corrections) } if err := ctx.Err(); err != nil { return snapshot(), &ExecutionFailure{Phase: "processing", Cause: err} } return snapshot(), nil } type moduleExecution struct { policy proposals.ReplacementPolicy pipeline modulePipelineResult updated []chunking.Section applied []proposals.AppliedChange skipped []proposals.SkippedChange appliedBySection []int } func (r *Runner) executeModule(ctx context.Context, spec contracts.ModuleRunSpec, sections []chunking.Section, interactions structuredoutput.InteractionSink, evidence evidenceNeeds, reportUnits []WorkUnitOutcome, progress func(Progress)) (moduleExecution, error) { var execution moduleExecution origin := failureReference(spec, nil, "") if err := ctx.Err(); err != nil { return execution, locateFailure(err, "processing", origin, false, nil) } module, err := r.factory.ModuleForSpec(spec) if err != nil { return execution, locateFailure(fmt.Errorf("setup failed: %w", err), "setup", origin, false, nil) } execution.policy = module.ReplacementPolicy() if err := spec.PrepareGlossary(); err != nil { return execution, locateFailure(fmt.Errorf("glossary preparation failed: %w", err), "setup", origin, false, nil) } execution.pipeline, err = runModulePipeline(ctx, collectSectionProposalsInput{ Module: module, Evidence: &evidence, ReportUnits: reportUnits, Progress: progress, Spec: spec, Policy: execution.policy, Sections: sections, ProposalClient: spec.ProposalClient, Interactions: interactions, ValidationClient: spec.ValidationClient, GlossaryVariables: spec.GlossaryVariables, GlossaryView: spec.GlossaryView, }) if err != nil { return execution, err } if err := ctx.Err(); err != nil { return execution, locateFailure(err, "application", origin, false, nil) } execution.updated, execution.applied, execution.skipped, execution.appliedBySection, err = applyWithinSections(sections, execution.pipeline.Approved, execution.policy, spec.GlossaryView.Protection, spec.ModuleKey == modulecatalog.KeySpokenWord) if err != nil { return execution, locateFailure(fmt.Errorf("application failed: %w", err), "application", origin, false, nil) } return execution, nil } func transcriptFromSections(sections []chunking.Section) *schema.Transcript { segments := make([]schema.Segment, 0) for _, section := range sections { segments = append(segments, section.Segments...) } return &schema.Transcript{Segments: segments} } // applyWithinSections leaves section membership and initial metadata unchanged. // Approved proposals are applied only to their identified section. func applyWithinSections(sections []chunking.Section, approved []proposals.EnrichedCorrectionProposal, policy proposals.ReplacementPolicy, vocabulary glossary.ProtectedVocabulary, allowRepetitionCleanup bool) ([]chunking.Section, []proposals.AppliedChange, []proposals.SkippedChange, []int, error) { applied := make([]proposals.AppliedChange, 0) skipped := make([]proposals.SkippedChange, 0) appliedBySection := make([]int, len(sections)) if len(approved) == 0 { return sections, applied, skipped, appliedBySection, nil } bySection := make(map[int][]proposals.EnrichedCorrectionProposal, len(sections)) known := make(map[int]struct{}, len(sections)) for _, section := range sections { known[section.Index] = struct{}{} } for _, candidate := range approved { if candidate.SectionIndex == nil { return nil, nil, nil, nil, fmt.Errorf("approved proposal %d has no section identity", candidate.ProposalIndex) } if _, ok := known[*candidate.SectionIndex]; !ok { return nil, nil, nil, nil, fmt.Errorf("approved proposal %d has unknown section identity", candidate.ProposalIndex) } bySection[*candidate.SectionIndex] = append(bySection[*candidate.SectionIndex], candidate) } updated := make([]chunking.Section, len(sections)) copy(updated, sections) for i, section := range sections { candidates := bySection[section.Index] if len(candidates) == 0 { continue } result := proposals.ApplyProposals(transcriptFromSection(section), candidates, policy, func(before, after string) bool { return vocabulary.AllowsChange(before, after, allowRepetitionCleanup) }) updated[i].Segments = result.Transcript.Segments applied = append(applied, result.Applied...) skipped = append(skipped, result.Skipped...) appliedBySection[i] = len(result.Applied) } return updated, applied, skipped, appliedBySection, nil } type collectSectionProposalsInput struct { Progress func(Progress) Evidence *evidenceNeeds ReportUnits []WorkUnitOutcome Interactions structuredoutput.InteractionSink Module contracts.TranscriptModule Spec contracts.ModuleRunSpec Policy proposals.ReplacementPolicy Sections []chunking.Section ProposalClient contracts.StructuredLLMClient ValidationClient contracts.StructuredLLMClient GlossaryVariables *promptcontext.GlossaryVariables GlossaryView *validators.GlossaryView } type sectionProposalResult struct { sectionPos int section chunking.Section proposal contracts.ProposalResult started bool failure *ExecutionFailure } type sectionValidationResult struct { interactions *sectionInteractions repairs []RepairOutcome sectionPos int approved []proposals.EnrichedCorrectionProposal decisions []ValidatorDecisionRecord rejected []ValidatorRejectedChange operations []outcomes.Operation filtered []outcomes.FilteredProposal failure *ExecutionFailure } type sectionWork struct { unit WorkUnitOutcome candidates []proposals.EnrichedCorrectionProposal validation *sectionValidationResult finished bool } type modulePipelineResult struct { Totals outcomes.WorkTotals proposalFacts map[int]proposalRecovery revised map[int]struct{} Candidates []proposals.EnrichedCorrectionProposal Approved []proposals.EnrichedCorrectionProposal WorkUnits []WorkUnitOutcome ValidatorDecisions []ValidatorDecisionRecord ValidatorRejected []ValidatorRejectedChange } // moduleWorkWindow bounds active and downstream work across all roles in // one module. PromptKit still owns admission to each provider backend. const moduleWorkWindow = 8 func proposeSection(ctx context.Context, input collectSectionProposalsInput, sectionPos int) sectionProposalResult { section := input.Sections[sectionPos] result := sectionProposalResult{sectionPos: sectionPos, section: section} if ctx.Err() != nil { return result } progress := Progress{ModuleIndex: input.Spec.Index, ModuleKey: input.Spec.ModuleKey, ModuleID: input.Spec.ID} progress.emit(input.Progress, "started", §ion.Index, nil) meta := contracts.SectionMetadataFromSection(section) proposalResult, err := input.Module.Propose(ctx, contracts.ProposalRequest{ ExecutionContext: contracts.ExecutionContext{ StageIndex: &input.Spec.Index, StageID: input.Spec.ID, Settings: input.Spec.Settings, WorkingTranscript: transcriptFromSection(section), Glossary: input.Spec.Glossary, ProtectedTerms: input.Spec.ProtectedTerms, GlossaryVariables: input.GlossaryVariables, Section: &meta, Interactions: input.Interactions, }, RunSpec: contracts.ModuleRunSpec{ ModuleKey: input.Spec.ModuleKey, InstanceName: input.Spec.InstanceName, ReplacementPolicy: input.Policy, CaptureProposalExchange: input.Spec.CaptureProposalExchange, }, LLMClient: input.ProposalClient, }) result.started = true result.proposal = proposalResult if err != nil { result.failure = locateFailure(err, "proposal", failureReference(input.Spec, &meta.Index, outcomes.OperationProposal), true, proposalResult.Operations) } return result } func runModulePipeline(ctx context.Context, input collectSectionProposalsInput) (modulePipelineResult, error) { var out modulePipelineResult evidence := selectEvidence(nil) if input.Evidence != nil { evidence = *input.Evidence } out.WorkUnits = input.ReportUnits if evidence.reports && out.WorkUnits == nil { out.WorkUnits = make([]WorkUnitOutcome, len(input.Sections)) for i, section := range input.Sections { out.WorkUnits[i] = newWorkUnit(input.Spec, contracts.SectionMetadataFromSection(section), 0) } } if len(input.Sections) == 0 { return out, nil } repairPromptID := "" if input.Spec.Settings.LLM.CorrectionRepairAttempts > 0 { provider, ok := input.Module.(interface{ RepairPromptID() string }) if !ok || input.Spec.RepairCoordinator == nil { cause := &structuredoutput.Failure{Class: outcomes.FailureFatal, Reason: outcomes.ReasonSetupFailure, Message: "correction repair coordinator or prompt provider is unavailable"} return out, locateFailure(cause, "setup", failureReference(input.Spec, nil, ""), false, nil) } repairPromptID = provider.RepairPromptID() if repairPromptID == "" { cause := &structuredoutput.Failure{Class: outcomes.FailureFatal, Reason: outcomes.ReasonSetupFailure, Message: "correction repair prompt is unavailable"} return out, locateFailure(cause, "setup", failureReference(input.Spec, nil, ""), false, nil) } input.Spec.CaptureProposalExchange = true } pending := make(map[int]*sectionWork, moduleWorkWindow) proposalResults := make(chan sectionProposalResult) validationResults := make(chan sectionValidationResult) validatorsOrdered, validatorOrder := reorderValidatorsForPipeline(input.Module.Validators()) nextSectionToRecord := 0 nextProposalIndex := 0 var ( firstFailure *ExecutionFailure errMu sync.Mutex workers sync.WaitGroup ) runCtx, cancel := context.WithCancel(ctx) defer cancel() setFailure := func(failure *ExecutionFailure) { if failure == nil { return } errMu.Lock() defer errMu.Unlock() if firstFailure == nil { firstFailure = failure cancel() } } makeCandidates := func(sectionResult sectionProposalResult) []proposals.EnrichedCorrectionProposal { sectionEnriched := make([]proposals.EnrichedCorrectionProposal, 0, len(sectionResult.proposal.Proposals)) for i, corrected := range sectionResult.proposal.Proposals { sectionIndex := sectionResult.section.Index sectionEnriched = append(sectionEnriched, proposals.EnrichedCorrectionProposal{ CorrectionProposal: corrected, ProposalMetadata: proposals.ProposalMetadata{ ProposalIndex: i, ModuleKey: input.Spec.ModuleKey, ModuleInstance: input.Spec.InstanceName, SectionIndex: §ionIndex, }, }) } return sectionEnriched } recordCandidates := func(unit *WorkUnitOutcome, enriched []proposals.EnrichedCorrectionProposal) { unit.ProposalIndexOffset = nextProposalIndex if evidence.candidates { for _, candidate := range enriched { candidate.ProposalIndex += nextProposalIndex out.Candidates = append(out.Candidates, candidate) } } nextProposalIndex += len(enriched) } validate := func(sectionResult sectionProposalResult, enriched []proposals.EnrichedCorrectionProposal) sectionValidationResult { sectionPos := sectionResult.sectionPos sectionMetadata := contracts.SectionMetadataFromSection(sectionResult.section) var interactions structuredoutput.InteractionSink var capture *sectionInteractions if input.Interactions != nil { capture = §ionInteractions{InteractionSink: input.Interactions} interactions = capture } validationInput := validateSectionCandidatesInput{ Spec: input.Spec, SuppressDecisionHistory: !evidence.decisions, Policy: input.Policy, WorkingTranscript: transcriptFromSection(sectionResult.section), SectionIndex: §ionMetadata.Index, Validators: validatorsOrdered, SectionEnriched: enriched, Exchange: sectionResult.proposal.Exchange, ValidationLLMClient: input.ValidationClient, GlossaryView: input.GlossaryView, Interactions: interactions, } if input.Spec.Settings.LLM.CorrectionRepairAttempts > 0 && len(enriched) > 0 { validationInput.Section = validators.NewSectionLookup(validationInput.WorkingTranscript) } validated, err := validateSectionCandidates(runCtx, validationInput) var repairs []RepairOutcome phase, kind := "validation", outcomes.OperationValidation if err == nil && repairPromptID != "" { phase, kind = "correction_repair", outcomes.OperationCorrectionRepair validated, repairs, err = repairCandidates(runCtx, validationInput, sectionResult.proposal.SegmentReferences, validated, repairPromptID) } var failure *ExecutionFailure if err != nil { if !errors.As(err, &failure) { failure = locateFailure(err, phase, failureReference(input.Spec, §ionMetadata.Index, kind), true, validated.operations) } } return sectionValidationResult{ interactions: capture, repairs: repairs, sectionPos: sectionPos, approved: validated.approved, decisions: validated.decisions, rejected: validated.rejected, operations: validated.operations, filtered: validated.filtered, failure: failure, } } recordValidation := func(unit *WorkUnitOutcome, res sectionValidationResult) { unit.Operations = append(unit.Operations, res.operations...) unit.Repairs = res.repairs mergeFilteredProposals(unit, res.filtered) unit.Failure = res.failure if res.failure == nil { unit.State = outcomes.WorkCompleted } else { unit.State = outcomes.WorkInterrupted } out.Approved = append(out.Approved, res.approved...) if evidence.decisions { out.ValidatorDecisions = append(out.ValidatorDecisions, res.decisions...) out.ValidatorRejected = append(out.ValidatorRejected, res.rejected...) } if len(res.approved) > 0 { out.rememberProposalRecovery(unit) } } progress := Progress{ModuleIndex: input.Spec.Index, ModuleKey: input.Spec.ModuleKey, ModuleID: input.Spec.ID} nextAdmission, active := 0, 0 for { for work := pending[nextSectionToRecord]; work != nil && work.finished; work = pending[nextSectionToRecord] { offset := nextProposalIndex recordCandidates(&work.unit, work.candidates) if work.validation != nil { work.validation.assignProposalIndices(offset) recordValidation(&work.unit, *work.validation) } out.Totals.Record(work.unit.State, work.unit.Operations) if evidence.reports { out.WorkUnits[nextSectionToRecord] = work.unit } else if evidence.candidates && len(work.unit.Repairs) > 0 { work.unit.Operations = nil out.WorkUnits = append(out.WorkUnits, work.unit) } delete(pending, nextSectionToRecord) nextSectionToRecord++ } for len(pending) < moduleWorkWindow && nextAdmission < len(input.Sections) && runCtx.Err() == nil { sectionPos := nextAdmission nextAdmission++ pending[sectionPos] = §ionWork{unit: newWorkUnit(input.Spec, contracts.SectionMetadataFromSection(input.Sections[sectionPos]), 0)} active++ workers.Go(func() { proposed := proposeSection(runCtx, input, sectionPos) setFailure(proposed.failure) proposalResults <- proposed }) } if active == 0 { break } select { case result := <-proposalResults: active-- work := pending[result.sectionPos] unit := &work.unit unit.Operations = append(unit.Operations, result.proposal.Operations...) if result.started { unit.State = outcomes.WorkInterrupted } unit.Failure = result.failure if result.started && result.failure == nil { work.candidates = makeCandidates(result) if runCtx.Err() == nil { enriched := work.candidates active++ workers.Go(func() { validated := validate(result, enriched) setFailure(validated.failure) validationResults <- validated }) continue } } work.finished = true if result.started { progress.emit(input.Progress, "interrupted", &work.unit.Section.Index, nil) } case validated := <-validationResults: active-- work := pending[validated.sectionPos] work.validation = &validated work.finished = true state := "completed" if validated.failure != nil { state = "interrupted" } proposals := len(work.candidates) progress.emit(input.Progress, state, &work.unit.Section.Index, &proposals) } } workers.Wait() sort.SliceStable(out.Approved, func(i, j int) bool { return out.Approved[i].ProposalIndex < out.Approved[j].ProposalIndex }) sort.SliceStable(out.ValidatorDecisions, func(i, j int) bool { if out.ValidatorDecisions[i].ProposalIndex != out.ValidatorDecisions[j].ProposalIndex { return out.ValidatorDecisions[i].ProposalIndex < out.ValidatorDecisions[j].ProposalIndex } return validatorOrder[out.ValidatorDecisions[i].ValidatorName] < validatorOrder[out.ValidatorDecisions[j].ValidatorName] }) sort.SliceStable(out.ValidatorRejected, func(i, j int) bool { if out.ValidatorRejected[i].ProposalIndex != out.ValidatorRejected[j].ProposalIndex { return out.ValidatorRejected[i].ProposalIndex < out.ValidatorRejected[j].ProposalIndex } return validatorOrder[out.ValidatorRejected[i].ValidatorName] < validatorOrder[out.ValidatorRejected[j].ValidatorName] }) if err := ctx.Err(); err != nil { setFailure(locateFailure(err, "processing", failureReference(input.Spec, nil, ""), false, nil)) } if firstFailure != nil { for i := range out.WorkUnits { for j := range out.WorkUnits[i].Repairs { if out.WorkUnits[i].Repairs[j].Outcome == "approved" { out.WorkUnits[i].Repairs[j].Outcome = "interrupted" } } } return out, firstFailure } return out, nil } type validateSectionCandidatesInput struct { SuppressDecisionHistory bool Section *validators.SectionLookup RepairProposalIndex *int RepairAttempt *int Exchange *structuredoutput.Exchange Spec contracts.ModuleRunSpec Policy proposals.ReplacementPolicy WorkingTranscript *schema.Transcript SectionIndex *int Validators []validators.Validator SectionEnriched []proposals.EnrichedCorrectionProposal ValidationLLMClient contracts.StructuredLLMClient Interactions structuredoutput.InteractionSink GlossaryView *validators.GlossaryView } type validateSectionCandidatesResult struct { approved []proposals.EnrichedCorrectionProposal decisions []ValidatorDecisionRecord rejected []ValidatorRejectedChange operations []outcomes.Operation filtered []outcomes.FilteredProposal } func validateSectionCandidates(ctx context.Context, input validateSectionCandidatesInput) (validateSectionCandidatesResult, error) { decisions := make([]ValidatorDecisionRecord, 0) rejected := make([]ValidatorRejectedChange, 0) operations := make([]outcomes.Operation, 0) filtered := make([]outcomes.FilteredProposal, 0) eligible := append([]proposals.EnrichedCorrectionProposal(nil), input.SectionEnriched...) feedback := input.Spec.Settings.LLM.CorrectionRepairAttempts > 0 var blocked, noEffect map[int]bool evidence := validators.Request{WorkingTranscript: input.WorkingTranscript, Section: input.Section, ReplacementPolicy: input.Policy, IndependentEvidence: feedback} if len(input.SectionEnriched) > 0 && len(input.Validators) > 0 { if feedback { evidence.Previews = make(map[int]proposals.SegmentPreviewResult) } else { evidence.PreviewApplicability = make(map[int]bool) } if evidence.Section == nil { evidence.Section = validators.NewSectionLookup(input.WorkingTranscript) } } if feedback { blocked, noEffect = make(map[int]bool), make(map[int]bool) } for validatorOrder, validator := range input.Validators { if err := ctx.Err(); err != nil { return validateSectionCandidatesResult{decisions: decisions, rejected: rejected, operations: operations, filtered: filtered}, err } class := validatormetadata.ClassOf(validator) submitted := eligible if feedback { submitted = feedbackCandidates(input, validator.Name(), class == validatormetadata.ExecutionClassLLMBacked, noEffect, evidence) } vResult, err := validator.Validate(ctx, validators.Request{ StageIndex: &input.Spec.Index, StageID: input.Spec.ID, WorkingTranscript: input.WorkingTranscript, Section: evidence.Section, Previews: evidence.Previews, PreviewApplicability: evidence.PreviewApplicability, CandidateProposal: submitted, ModuleKey: input.Spec.ModuleKey, ModuleInstance: input.Spec.InstanceName, SectionIndex: input.SectionIndex, IndependentEvidence: feedback, RepairProposalIndex: input.RepairProposalIndex, RepairAttempt: input.RepairAttempt, ValidatorOrder: &validatorOrder, ReplacementPolicy: input.Policy, Glossary: input.Spec.Glossary, ProtectedTerms: input.Spec.ProtectedTerms, GlossaryView: input.GlossaryView, Settings: input.Spec.Settings, LLMClient: input.ValidationLLMClient, Interactions: input.Interactions, }) operations = append(operations, vResult.Operations...) locate := func(cause error) *ExecutionFailure { ref := failureReference(input.Spec, input.SectionIndex, outcomes.OperationValidation) ref.ValidatorName, ref.ValidatorOrder = validator.Name(), &validatorOrder ref.ProposalIndex, ref.RepairAttempt = input.RepairProposalIndex, input.RepairAttempt return locateFailure(cause, "validation", ref, input.SectionIndex != nil, vResult.Operations) } var decisionErr error if err != nil { decisionErr = validators.EnforcePartialDecisionCardinality(submitted, vResult.Decisions) } else { decisionErr = validators.EnforceDecisionCardinality(submitted, vResult.Decisions) } if decisionErr != nil { return validateSectionCandidatesResult{ decisions: decisions, rejected: rejected, operations: operations, filtered: filtered, }, locate(fmt.Errorf("validator %q cardinality failed: %w", validator.Name(), errors.Join(err, decisionErr))) } nextEligible := make([]proposals.EnrichedCorrectionProposal, 0, len(submitted)) byIndex := make(map[int]proposals.EnrichedCorrectionProposal, len(submitted)) for _, p := range submitted { byIndex[p.ProposalIndex] = p } dispositions := make([]validators.DecisionDisposition, len(vResult.Decisions)) for i, decision := range vResult.Decisions { disposition, contractErr := decision.EffectiveDisposition() if contractErr != nil { return validateSectionCandidatesResult{ decisions: decisions, rejected: rejected, operations: operations, filtered: filtered, }, locate(fmt.Errorf("validator %q returned inconsistent decisions: %w", validator.Name(), errors.Join(err, contractErr))) } dispositions[i] = disposition } for i, d := range vResult.Decisions { disposition := dispositions[i] approved := disposition == validators.DispositionApproved if feedback && !approved { blocked[d.ProposalIndex] = true if d.ReasonCode == validators.ReasonNoEffect { noEffect[d.ProposalIndex] = true } } if !input.SuppressDecisionHistory { decisions = append(decisions, ValidatorDecisionRecord{ ValidatorName: validator.Name(), ExecutionClass: class, ProposalIndex: d.ProposalIndex, Approved: approved, Disposition: disposition, ReasonCode: d.ReasonCode, Message: d.Message, DiagnosticArtifactPath: d.DiagnosticArtifactPath, }) } if approved { nextEligible = append(nextEligible, byIndex[d.ProposalIndex]) continue } if disposition != validators.DispositionUnavailable { if reason, ok := validators.DefectiveProposalReason(d.ReasonCode); ok { filtered = append(filtered, outcomes.FilteredProposal{ProposalIndex: d.ProposalIndex, Reason: reason, Count: 1}) } } if feedback || !input.SuppressDecisionHistory { p := byIndex[d.ProposalIndex] rejected = append(rejected, ValidatorRejectedChange{ ValidatorName: validator.Name(), ProposalIndex: p.ProposalIndex, ModuleKey: p.ModuleKey, ModuleInstance: p.ModuleInstance, TargetSegmentID: p.TargetSegmentID, OriginalText: p.OriginalText, CorrectedText: p.CorrectedText, Disposition: disposition, ReasonCode: d.ReasonCode, Message: d.Message, }) } } if err != nil { // Completed decisions are evidence only. A fatal return never grants // approval to candidates that have not finished the full chain. return validateSectionCandidatesResult{ decisions: decisions, rejected: rejected, operations: operations, filtered: filtered, }, locate(fmt.Errorf("validator %q failed: %w", validator.Name(), err)) } eligible = nextEligible } if feedback { eligible = eligible[:0] for _, candidate := range input.SectionEnriched { if !blocked[candidate.ProposalIndex] { eligible = append(eligible, candidate) } } } for i := range eligible { index := eligible[i].ProposalIndex applicable, checked := evidence.PreviewApplicability[index] if preview, ok := evidence.Previews[index]; ok { applicable, checked = preview.Applicable, true } if checked { eligible[i].OriginalApplicability = proposals.Inapplicable if applicable { eligible[i].OriginalApplicability = proposals.Applicable } } } return validateSectionCandidatesResult{ approved: eligible, decisions: decisions, rejected: rejected, operations: operations, filtered: filtered, }, nil } // mergeFilteredProposals attributes defective candidates to their originating // proposal response. Each response has at most one filtering recovery reason. func mergeFilteredProposals(unit *WorkUnitOutcome, filtered []outcomes.FilteredProposal) { if len(filtered) == 0 { return } for i := range unit.Operations { operation := &unit.Operations[i] if operation.Reference.Kind == outcomes.OperationProposal && operation.Succeeded { mergeOperationFiltering(operation, filtered) return } } } func mergeOperationFiltering(operation *outcomes.Operation, filtered []outcomes.FilteredProposal) { seen := make(map[int]struct{}, len(operation.Filtered)+len(filtered)) for _, existing := range operation.Filtered { seen[existing.ProposalIndex] = struct{}{} } for _, item := range filtered { if _, ok := seen[item.ProposalIndex]; ok { continue } seen[item.ProposalIndex] = struct{}{} operation.Filtered = append(operation.Filtered, item) } sort.Slice(operation.Filtered, func(a, b int) bool { return operation.Filtered[a].ProposalIndex < operation.Filtered[b].ProposalIndex }) if !slices.Contains(operation.RecoveryReasons, outcomes.RecoveryProposalsFiltered) { operation.RecoveryReasons = append(operation.RecoveryReasons, outcomes.RecoveryProposalsFiltered) } } func findApplyFiltering(sections []chunking.Section, approved []proposals.EnrichedCorrectionProposal, skipped []proposals.SkippedChange, policy proposals.ReplacementPolicy) map[int][]outcomes.FilteredProposal { if len(skipped) == 0 { return nil } byIndex := make(map[int]proposals.EnrichedCorrectionProposal) for _, proposal := range approved { if proposal.OriginalApplicability != proposals.Applicable { byIndex[proposal.ProposalIndex] = proposal } } if len(byIndex) == 0 { return nil } sectionPosition := make(map[int]int, len(sections)) for pos, section := range sections { sectionPosition[section.Index] = pos } lookups := make(map[int]*validators.SectionLookup) filtered := make(map[int][]outcomes.FilteredProposal) for _, skip := range skipped { reason, defective := validators.DefectiveProposalReason(string(skip.SkipReason)) proposal, ok := byIndex[skip.ProposalIndex] if !defective || !ok || proposal.SectionIndex == nil { continue } pos, ok := sectionPosition[*proposal.SectionIndex] if !ok { continue } if proposal.OriginalApplicability == proposals.ApplicabilityUnknown { lookup := lookups[pos] if lookup == nil { lookup = validators.NewSectionLookup(&schema.Transcript{Segments: sections[pos].Segments}) lookups[pos] = lookup } var segment *schema.Segment if i, found := lookup.Position(proposal.TargetSegmentID); found { segment = §ions[pos].Segments[i] } // A previously applicable proposal can become stale during application. if proposals.PreviewProposalForSegment(segment, proposal.CorrectionProposal, policy).Applicable { continue } } filtered[pos] = append(filtered[pos], outcomes.FilteredProposal{ProposalIndex: skip.ProposalIndex, Reason: reason, Count: 1}) } return filtered } func reorderValidatorsForPipeline(in []validators.Validator) ([]validators.Validator, map[string]int) { deterministic := make([]validators.Validator, 0, len(in)) llmBacked := make([]validators.Validator, 0, len(in)) for _, validator := range in { class := validatormetadata.ClassOf(validator) validator = validatormetadata.Wrap(validator, class) if class == validatormetadata.ExecutionClassLLMBacked { llmBacked = append(llmBacked, validator) continue } deterministic = append(deterministic, validator) } ordered := append(deterministic, llmBacked...) order := make(map[string]int, len(ordered)) for idx, validator := range ordered { order[validator.Name()] = idx } return ordered, order } func chunkWorkingTranscript(cfg *config.Config, transcript *schema.Transcript) ([]chunking.Section, error) { if cfg == nil { if transcript == nil || len(transcript.Segments) == 0 { return []chunking.Section{}, nil } return []chunking.Section{ { Index: 0, EstimatedTokens: estimateTranscriptTokens(transcript), Segments: append([]schema.Segment(nil), transcript.Segments...), StartSegmentID: transcript.Segments[0].ID, EndSegmentID: transcript.Segments[len(transcript.Segments)-1].ID, }, }, nil } chunker := chunking.NewChunker(chunking.ChunkingConfig{ MaxSectionTokens: cfg.Chunking.MaxSectionTokens, MinSectionTokens: cfg.Chunking.MinSectionTokens, TargetSections: cfg.Chunking.TargetSections, }) return chunker.ChunkTranscript(transcript) } func estimateTranscriptTokens(transcript *schema.Transcript) int { if transcript == nil || len(transcript.Segments) == 0 { return 0 } estimator := chunking.NewSimpleTokenEstimator() total := 0 for _, segment := range transcript.Segments { total += estimator.EstimateTokens(segment.Text) } return total } func transcriptFromSection(section chunking.Section) *schema.Transcript { segments := make([]schema.Segment, len(section.Segments)) copy(segments, section.Segments) return &schema.Transcript{Segments: segments} }