Bind runner assessment and propagate fallback reuse eligibility

This commit is contained in:
2026-11-21 23:48:51 +00:00
parent 44e4fb92c2
commit 923cbe594f
19 changed files with 852 additions and 902 deletions

View File

@@ -221,3 +221,13 @@ func TestChunkAssessmentIsolatesTypedAndSerializedViewsAfterRejection(t *testing
t.Fatalf("assessment = %#v %v, calls %d, chunks %#v", assessment, err, calls, chunks)
}
}
type serializedValidationFunc func(context.Context, contracts.SerializedValidationRequest) (contracts.ValidationResult, error)
func (serializedValidationFunc) Name() string { return "candidate-serialized" }
func (serializedValidationFunc) ExecutionClass() contracts.ExecutionClass {
return contracts.ExecutionClassDeterministic
}
func (validate serializedValidationFunc) Validate(ctx context.Context, request contracts.SerializedValidationRequest) (contracts.ValidationResult, error) {
return validate(ctx, request)
}

View File

@@ -153,30 +153,6 @@ type debugLLMCallReference struct {
Execution *contracts.LLMExecutionSummary `json:"execution,omitempty"`
}
type debugValidationOutcome struct {
ValidatorName string `json:"validator_name"`
Outcome string `json:"outcome"`
AttemptCount int `json:"attempt_count"`
ReasonCode string `json:"reason_code,omitempty"`
}
type debugProducerAttempt struct {
Number int `json:"number"`
Kind string `json:"kind"`
Outcome string `json:"outcome"`
Validation []debugValidationOutcome `json:"validation,omitempty"`
}
type debugProducerTerminal struct {
ProducerAttemptCount int `json:"producer_attempt_count"`
Attempts []debugProducerAttempt `json:"attempts,omitempty"`
AggregateReasonCodes []string `json:"aggregate_reason_codes,omitempty"`
ValidationComplete bool `json:"validation_complete"`
EffectivePolicy ValidationPolicy `json:"effective_policy"`
TerminalAction string `json:"terminal_action"`
Summary artifacts.ValidationSummary `json:"validation_summary"`
}
type debugValidationCall struct {
ValidatorName string `json:"validator_name"`
Request any `json:"request"`
@@ -443,50 +419,6 @@ func (r attemptTerminalRecorder) record(payload any, terminalErr error) error {
return terminalErr
}
func debugValidationOutcomes(report validationReport) []debugValidationOutcome {
if len(report.records) == 0 {
return nil
}
outcomes := make([]debugValidationOutcome, 0, len(report.records))
for _, record := range report.records {
outcomes = append(outcomes, debugValidationOutcome{
ValidatorName: record.validatorName,
Outcome: string(record.outcome),
AttemptCount: record.attemptCount,
ReasonCode: record.reasonCode,
})
}
return outcomes
}
func writeProducerTerminalDebug(recorder DebugRecorder, name string, terminal producerAttemptTerminal, policy ValidationPolicy, summary artifacts.ValidationSummary) error {
attempts := make([]debugProducerAttempt, 0, len(terminal.Provenance))
for _, item := range terminal.Provenance {
attempts = append(attempts, debugProducerAttempt{
Number: item.Number,
Kind: string(item.Kind),
Outcome: string(item.Outcome),
Validation: debugValidationOutcomes(item.Validation),
})
}
return writeDebugTimed(recorder, name, debugTimedEnvelope{
Stage: summary.Stage,
StepID: summary.StepID,
LaneID: summary.LaneID,
ModuleKey: summary.ModuleKey,
StartedAt: time.Now().UTC(),
Payload: debugProducerTerminal{
ProducerAttemptCount: summary.ProducerAttemptCount,
Attempts: attempts,
AggregateReasonCodes: append([]string(nil), summary.ReasonCodes...),
ValidationComplete: summary.Status == "complete",
EffectivePolicy: policy,
TerminalAction: string(terminal.Action),
Summary: artifacts.CloneValidationSummary(summary),
},
})
}
func debugContentEnvelope(content []byte, mediaType string, metadata map[string]any, _ any) debugBinaryEnvelope {
content = redactSecretBytes(content)
return debugBinaryEnvelope{

View File

@@ -8,26 +8,6 @@ import (
frameworkdiagnostics "gitea.maximumdirect.net/eric/notarius/internal/framework/diagnostics"
)
func terminalDiagnosticGroups(terminal producerAttemptTerminal, origin contracts.DiagnosticOrigin, chunk *source.Chunk) ([]contracts.DiagnosticGroup, error) {
return promoteCheckpointDiagnostics(terminalCheckpointDiagnostics(terminal), origin, chunk)
}
func terminalCheckpointDiagnostics(terminal producerAttemptTerminal) []CheckpointDiagnostic {
diagnostics := make([]CheckpointDiagnostic, 0, len(terminal.Diagnostics))
for _, diagnostic := range terminal.Diagnostics {
diagnostics = append(diagnostics, CheckpointDiagnostic{Diagnostic: diagnostic})
}
for _, record := range terminal.Validation.Diagnostics() {
diagnostics = append(diagnostics, CheckpointDiagnostic{Diagnostic: record.diagnostic, ValidatorKey: record.validatorName})
}
if terminal.Action == producerTerminalIncompleteAccepted {
for _, record := range incompleteValidationDiagnostics(terminal.Validation) {
diagnostics = append(diagnostics, CheckpointDiagnostic{Diagnostic: record.diagnostic, ValidatorKey: record.validatorName})
}
}
return cloneCheckpointDiagnostics(diagnostics)
}
func promoteCheckpointDiagnostics(diagnostics []CheckpointDiagnostic, origin contracts.DiagnosticOrigin, chunk *source.Chunk) ([]contracts.DiagnosticGroup, error) {
groups := make([]contracts.DiagnosticGroup, 0, len(diagnostics))
for _, record := range diagnostics {

View File

@@ -66,7 +66,7 @@ func RegisterExtractorBuilder[T any](registry *ExtractorRegistry, spec ModuleSpe
if err != nil {
return erasedTypedResult{}, err
}
return erasedTypedResult{Value: result.Value, Diagnostics: contracts.CloneProducerDiagnostics(result.Diagnostics), Outcome: result.Outcome}, nil
return erasedTypedResult{Value: result.Value, Diagnostics: contracts.CloneProducerDiagnostics(result.Diagnostics), Outcome: result.Outcome, Fallback: eraseProducerFallback(result.Fallback)}, nil
}}
if registry.typedEntries == nil {
registry.typedEntries = map[string]typedExtractorEntry{}

View File

@@ -41,8 +41,8 @@ func operationReferenceSet(input RunInput, target ResolvedReferenceTarget) contr
return CloneReferenceSet(target.ReferenceSet)
}
// referenceTargetReuseEligible reports whether every generated artifact in a
// stage's reference set descends exclusively from fully validated work. Static
// referenceTargetReuseEligible reports whether every generated artifact in an
// operation's reference set descends exclusively from ordinary acceptance. Static
// references and callers that do not supply lineage metadata are reusable.
func referenceTargetReuseEligible(input RunInput, target ResolvedReferenceTarget) bool {
if input.referenceReuseEligibility == nil {
@@ -58,7 +58,7 @@ func laneReferencesReuseEligible(input RunInput, lane ResolvedArtifactLane) bool
referenceTargetReuseEligible(input, lane.NormalizeReferences)
}
// buildStepReferenceReuseEligibility carries validation completeness alongside
// buildStepReferenceReuseEligibility carries reuse eligibility alongside
// generated references without exposing the internal lineage flag in artifact
// payloads. A target becomes ineligible when any generated input is ineligible.
func buildStepReferenceReuseEligibility(step PreparedPipelineStep, outputs map[generatedOutputKey]bool) map[referenceTargetKey]bool {

View File

@@ -92,7 +92,7 @@ func RegisterMergerBuilder[T any](registry *MergerRegistry, spec ModuleSpec, val
if err != nil {
return erasedTypedResult{}, err
}
return erasedTypedResult{Value: result.Value, Diagnostics: contracts.CloneProducerDiagnostics(result.Diagnostics), Outcome: result.Outcome}, nil
return erasedTypedResult{Value: result.Value, Diagnostics: contracts.CloneProducerDiagnostics(result.Diagnostics), Outcome: result.Outcome, Fallback: eraseProducerFallback(result.Fallback)}, nil
},
}
return nil

View File

@@ -1,43 +0,0 @@
package pipeline
import (
"errors"
"strings"
"unicode/utf8"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
)
func validateNormalizeRetry(retry *contracts.NormalizeRetry) error {
if retry == nil {
return errors.New("normalize retry directive is missing")
}
if !utf8.ValidString(retry.ReasonCode) {
return errors.New("normalize retry directive reason code has invalid UTF-8")
}
if strings.TrimSpace(retry.ReasonCode) == "" {
return errors.New("normalize retry directive reason code is blank")
}
if len(retry.ReasonCode) > contracts.MaxNormalizeRetryReasonCodeBytes {
return errors.New("normalize retry directive reason code exceeds maximum length")
}
if !utf8.ValidString(retry.Message) {
return errors.New("normalize retry directive message has invalid UTF-8")
}
if strings.TrimSpace(retry.Message) == "" {
return errors.New("normalize retry directive message is blank")
}
if len(retry.Message) > contracts.MaxNormalizeRetryMessageBytes {
return errors.New("normalize retry directive message exceeds maximum length")
}
if !utf8.ValidString(retry.CorrectionGuidance) {
return errors.New("normalize retry directive correction guidance has invalid UTF-8")
}
if retry.CorrectionGuidance != "" && strings.TrimSpace(retry.CorrectionGuidance) == "" {
return errors.New("normalize retry directive correction guidance is blank")
}
if len(retry.CorrectionGuidance) > contracts.MaxNormalizeRetryCorrectionGuidanceBytes {
return errors.New("normalize retry directive correction guidance exceeds maximum length")
}
return nil
}

View File

@@ -83,7 +83,7 @@ func RegisterNormalizerBuilder[T any](registry *NormalizerRegistry, spec ModuleS
if err != nil {
return erasedTypedResult{}, err
}
return erasedTypedResult{Value: result.Value, Diagnostics: contracts.CloneProducerDiagnostics(result.Diagnostics), Outcome: result.Outcome}, nil
return erasedTypedResult{Value: result.Value, Diagnostics: contracts.CloneProducerDiagnostics(result.Diagnostics), Outcome: result.Outcome, Fallback: eraseProducerFallback(result.Fallback)}, nil
},
}
return nil

View File

@@ -4,8 +4,6 @@ import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"mime"
"path"
@@ -15,7 +13,6 @@ import (
"time"
"gitea.maximumdirect.net/eric/notarius/internal/core/artifacts"
"gitea.maximumdirect.net/eric/notarius/internal/core/fileio"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/chunkmap"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
@@ -41,6 +38,7 @@ func New() *Runner {
}
type RunInput struct {
Execution contracts.ExecutionOptions
Prepared *PreparedPipeline
SourceID string
Path string
@@ -61,14 +59,16 @@ type RunInput struct {
// single worker so direct framework callers retain deterministic behavior.
ExtractWorkers int
pipeline ResolvedPipeline
llmClient contracts.StructuredLLMClient
pipeline ResolvedPipeline
// reuseIneligible carries chunk ancestry; reference eligibility stays scoped.
reuseIneligible bool
stepID string
references map[referenceTargetKey]contracts.ReferenceSet
referenceReuseEligibility map[referenceTargetKey]bool
}
type RunOutput struct {
FallbackCount int `json:"fallback_count,omitempty"`
Manifest artifacts.RunManifest `json:"manifest"`
ChunkPlan *artifacts.ChunkPlanSummary `json:"chunk_plan,omitempty"`
NormalizeOutputs []contracts.SerializedOutput `json:"normalize_outputs,omitempty"`
@@ -97,7 +97,6 @@ func (r *Runner) Run(ctx context.Context, input RunInput) (output RunOutput, err
return output, fmt.Errorf("clone run metadata: %w", err)
}
input.pipeline = input.Prepared.resolved
input.llmClient = input.Prepared.dependencies.LLM
output.Manifest = manifestFromPipeline(input)
sessionID := strings.TrimSpace(input.SessionID)
@@ -126,10 +125,6 @@ func (r *Runner) Run(ctx context.Context, input RunInput) (output RunOutput, err
checkpointLoader = synchronizedCheckpointLoader(checkpointLoader)
debugRecorder = synchronizedDebugRecorder(debugRecorder)
input.Debug = debugRecorder
input.llmClient = wrapDebugLLMClient(input.llmClient, debugRecorder)
defer func() {
output.Manifest.LLMProfiles = mergeLLMProfileManifests(input.LLMProfiles, llmProfileManifests(input.llmClient))
}()
inputDiagnostics, diagnosticErr := promoteProducerDiagnostics(input.Diagnostics, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageReferences}, nil)
if diagnosticErr != nil {
return failOutput(output), fmt.Errorf("promote input diagnostics: %w", diagnosticErr)
@@ -182,12 +177,11 @@ func (r *Runner) Run(ctx context.Context, input RunInput) (output RunOutput, err
return failOutput(output), err
}
doc, err = adapter.Parse(ctx, contracts.ParseRequest{
SourceID: input.SourceID,
Path: input.Path,
Raw: input.RawInput,
LLMProfile: input.pipeline.Input.LLMProfile,
StructuredOutputRepairAttempts: cloneStructuredOutputRepairAttempts(input.pipeline.Input.StructuredOutputRepairAttempts),
Metadata: requestMetadata,
SourceID: input.SourceID,
Path: input.Path,
Raw: input.RawInput,
LLMProfile: input.pipeline.Input.LLMProfile,
Metadata: requestMetadata,
})
if ctxErr := ctx.Err(); ctxErr != nil {
_ = checkpoints.SourceFailed(adapter.Key(), ctxErr)
@@ -298,6 +292,10 @@ func (r *Runner) Run(ctx context.Context, input RunInput) (output RunOutput, err
}
if chunkResult.accepted {
input.reuseIneligible = !chunkResult.outcome.ReuseEligible
if chunkResult.outcome.Disposition == contracts.ProducerFallback {
output.FallbackCount++
}
if err := r.runPreparedSteps(ctx, input, checkpoints, checkpointLoader, doc, sourceInput, sessionID, chunkResult.chunks, &output); err != nil {
return failOutput(output), err
}
@@ -308,7 +306,7 @@ func (r *Runner) Run(ctx context.Context, input RunInput) (output RunOutput, err
if len(output.Rejected) > 0 {
output.Manifest.ValidationStatus = "rejected"
} else if hasIncompleteValidation(output.ValidationSummaries) {
} else if output.FallbackCount > 0 || hasIncompleteValidation(output.ValidationSummaries) {
output.Manifest.ValidationStatus = "incomplete"
} else {
output.Manifest.ValidationStatus = "approved"
@@ -376,15 +374,14 @@ func (r *Runner) Run(ctx context.Context, input RunInput) (output RunOutput, err
return failOutput(output), err
}
encoded, err := encoder.Encode(ctx, contracts.OutputRequest{
Manifest: output.Manifest,
NormalizeOutputs: cloneSerializedOutputs(output.NormalizeOutputs),
Rejected: cloneRejectedOutputs(output.Rejected),
Diagnostics: contracts.CloneDiagnosticCollection(output.Diagnostics),
LLMProfile: input.pipeline.Output.LLMProfile,
StructuredOutputRepairAttempts: cloneStructuredOutputRepairAttempts(input.pipeline.Output.StructuredOutputRepairAttempts),
Metadata: outputMetadata,
ChunkMap: contracts.CloneSerializedArtifactPointer(acceptedChunkMap),
EvidenceContext: contracts.CloneSerializedArtifactPointer(evidenceArtifact),
Manifest: output.Manifest,
NormalizeOutputs: cloneSerializedOutputs(output.NormalizeOutputs),
Rejected: cloneRejectedOutputs(output.Rejected),
Diagnostics: contracts.CloneDiagnosticCollection(output.Diagnostics),
LLMProfile: input.pipeline.Output.LLMProfile,
Metadata: outputMetadata,
ChunkMap: contracts.CloneSerializedArtifactPointer(acceptedChunkMap),
EvidenceContext: contracts.CloneSerializedArtifactPointer(evidenceArtifact),
})
if ctxErr := ctx.Err(); ctxErr != nil {
return failOutput(output), ctxErr
@@ -445,53 +442,6 @@ func (r *Runner) runPreparedSteps(ctx context.Context, input RunInput, checkpoin
return nil
}
type retryAttemptResult struct {
accepted bool
rejection *contracts.RejectedOutput
}
func runSimpleRetry(ctx context.Context, retries int, run func(attempt int) (retryAttemptResult, error)) (retryAttemptResult, error) {
attempts := retries + 1
var last retryAttemptResult
for attempt := 1; attempt <= attempts; attempt++ {
if err := ctx.Err(); err != nil {
return retryAttemptResult{}, err
}
result, err := run(attempt)
if err != nil {
var debugErr *attemptDebugPersistenceError
if errors.As(err, &debugErr) {
return retryAttemptResult{}, fmt.Errorf("failed after %d attempt(s): %w", attempt, err)
}
if attempt == attempts {
return retryAttemptResult{}, fmt.Errorf("failed after %d attempt(s): %w", attempt, err)
}
if ctxErr := ctx.Err(); ctxErr != nil {
return retryAttemptResult{}, ctxErr
}
continue
}
if result.accepted {
return result, nil
}
if result.rejection != nil {
rejection := *result.rejection
rejection.AttemptCount = attempt
last = retryAttemptResult{rejection: &rejection}
}
if ctxErr := ctx.Err(); ctxErr != nil {
return retryAttemptResult{}, ctxErr
}
if attempt == attempts {
if last.rejection == nil {
last.rejection = &contracts.RejectedOutput{ReasonCode: "output_rejected", Message: "output rejected", AttemptCount: attempt}
}
return last, nil
}
}
return last, nil
}
func resolvedValidatorChain(stage ModuleStage, laneID string, moduleKey string, chains []ResolvedValidatorChain) ResolvedValidatorChain {
for _, chain := range chains {
if chain.Stage != stage {

View File

@@ -173,16 +173,6 @@ func setCandidateValidator(prepared *PreparedPipeline, target ModuleStage, appro
}
}
type serializedValidationFunc func(context.Context, contracts.SerializedValidationRequest) (contracts.ValidationResult, error)
func (serializedValidationFunc) Name() string { return "candidate-serialized" }
func (serializedValidationFunc) ExecutionClass() contracts.ExecutionClass {
return contracts.ExecutionClassDeterministic
}
func (validate serializedValidationFunc) Validate(ctx context.Context, request contracts.SerializedValidationRequest) (contracts.ValidationResult, error) {
return validate(ctx, request)
}
func TestRunnerIsolatesTypedValidatorCandidates(t *testing.T) {
for _, target := range []ModuleStage{StageExtract, StageMerge, StageNormalize} {
t.Run(string(target), func(t *testing.T) {

View File

@@ -3,7 +3,6 @@ package pipeline
import (
"context"
"fmt"
"path"
"time"
"gitea.maximumdirect.net/eric/notarius/internal/core/artifacts"
@@ -12,6 +11,7 @@ import (
)
type chunkPlanExecution struct {
outcome contracts.ProducerOutcome
accepted bool
chunks []source.Chunk
plan *source.ChunkPlan
@@ -24,14 +24,6 @@ type chunkPlanExecution struct {
validation *artifacts.ValidationSummary
}
type generatedChunkPlanCandidate struct {
plan source.ChunkPlan
chunks []source.Chunk
record ChunkPlanRecord
producerDiagnostics []contracts.ProducerDiagnostic
terminal *attemptTerminalRecorder
}
func effectiveChunkCacheMode(mode ChunkCacheMode) ChunkCacheMode {
if mode == "" {
return ChunkCacheBypass
@@ -45,218 +37,120 @@ func effectiveChunkCacheMode(mode ChunkCacheMode) ChunkCacheMode {
func (r *Runner) runChunkPlan(ctx context.Context, input RunInput, doc *source.SourceDocument, sourceInput contracts.LLMInputMaterial, sessionID string) (chunkPlanExecution, error) {
mode := effectiveChunkCacheMode(input.ChunkCacheMode)
chunker := input.Prepared.chunker
result := chunkPlanExecution{
lookup: ChunkPlanDecision{Reason: "chunk plan lookup skipped"},
summary: artifacts.ChunkPlanSummary{
Mode: string(mode), SourceDigest: doc.Digest, RequestedModule: chunker.Key(), LookupStatus: "skipped",
LookupReason: "chunk plan lookup skipped", ValidationStatus: "not_run", PublicationStatus: "not_requested",
result := chunkPlanExecution{lookup: ChunkPlanDecision{Reason: "chunk plan lookup skipped"}, summary: artifacts.ChunkPlanSummary{Mode: string(mode), SourceDigest: doc.Digest, RequestedModule: chunker.Key(), LookupStatus: "skipped", LookupReason: "chunk plan lookup skipped", ValidationStatus: "not_run", PublicationStatus: "not_requested"}}
target := typedValidationTarget{stage: StageChunk, moduleKey: chunker.Key(), source: doc, sourceID: doc.ID, sourceInput: sourceInput.Clone(), sessionID: sessionID, references: input.pipeline.ChunkReferences.ReferenceSet, metadata: input.Metadata, execution: input.Execution}
assessChunks := chunkCandidateAssessor(target, input.Prepared.chunkValidators)
var assessment contracts.CandidateAssessment
operation := contracts.ProducerOperation[source.ChunkPlan]{Controls: input.pipeline.ChunkControls, Execution: input.Execution, ReuseEligible: true,
Assess: func(ctx context.Context, plan source.ChunkPlan) (contracts.CandidateAssessment, error) {
_, chunks, err := validateAndMaterializeChunkPlan(doc, plan)
if err != nil {
if input.pipeline.ChunkExecutionClass == contracts.ExecutionClassDeterministic {
return contracts.CandidateAssessment{}, err
}
assessment = contracts.CandidateAssessment{Validators: []contracts.ValidatorAssessment{{ValidatorName: "chunk materialization", Decision: contracts.AssessmentFailed, Failure: err}}}
return assessment, nil
}
assessment, err = assessChunks(ctx, chunks)
return assessment, err
},
}
if mode == ChunkCacheAuto {
record, decision, err := input.ChunkPlans.Load(doc.Digest)
result.lookup = decision
result.summary.LookupStatus = chunkPlanLookupStatus(decision.Status)
result.summary.LookupReason = chunkPlanLookupReason(decision.Status)
if err != nil {
result.summary.LookupStatus = "skipped"
result.summary.LookupReason = chunkPlanLookupReason("")
return result, fmt.Errorf("load chunk plan: %w", err)
}
switch decision.Status {
case ChunkPlanHit:
plan, chunks, validationErr := validateAndMaterializeChunkPlan(doc, record.Plan)
if validationErr == nil {
report, err := r.validateChunkReport(ctx, doc, chunker.Key(), chunks, sourceInput, sessionID, input.pipeline.ChunkReferences.ReferenceSet, input.Metadata, input.Prepared.chunkValidators, 1, input.Debug)
result.lookup = decision
result.summary.LookupStatus, result.summary.LookupReason = chunkPlanLookupStatus(decision.Status), chunkPlanLookupReason(decision.Status)
if decision.Status == ChunkPlanHit {
plan, chunks, err := validateAndMaterializeChunkPlan(doc, record.Plan)
if err == nil {
cachedAssessment, err := assessChunks(ctx, chunks)
if err != nil {
return result, err
}
if cachedAssessment.Accepted() {
if err := result.setCandidate(record, "reused"); err != nil {
return result, err
}
result.plan, result.chunks, result.accepted = &plan, chunks, true
result.outcome = contracts.ProducerOutcome{Disposition: contracts.ProducerAccepted, ReuseEligible: true}
result.diagnostics, err = operationDiagnosticGroups(record.Diagnostics, cachedAssessment, result.outcome, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageChunk, ModuleKey: chunker.Key()}, nil)
result.setValidation(nil, err)
return result, err
}
rejection := report.FirstRejection()
incomplete := firstIncompleteValidation(report)
if rejection == nil && incomplete == nil {
if err := result.setCandidate(record, "reused"); err != nil {
return result, fmt.Errorf("clone reused chunk plan record: %w", err)
}
result.plan = &plan
result.chunks = chunks
result.accepted = true
result.setValidation(nil, nil)
cachedTerminal := producerAttemptTerminal{Action: producerTerminalAccepted, Diagnostics: contracts.CloneProducerDiagnostics(record.Diagnostics), Validation: report}
diagnostics, diagnosticErr := terminalDiagnosticGroups(cachedTerminal, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageChunk, ModuleKey: chunker.Key()}, nil)
if diagnosticErr != nil {
return result, fmt.Errorf("promote reused chunk diagnostics: %w", diagnosticErr)
}
result.diagnostics = diagnostics
summary := validationSummary(cachedTerminal, StageChunk, "", "", chunker.Key(), "", 0)
result.validation = &summary
return result, nil
}
if incomplete != nil && input.pipeline.ChunkValidationPolicy.ValidatorFailure == ValidatorFailureFailRun {
failure := validatorFailureError(*incomplete)
result.setValidation(nil, failure)
failedTerminal := producerAttemptTerminal{Action: producerTerminalFailed, Validation: report, ValidationIncomplete: true}
summary := validationSummary(failedTerminal, StageChunk, "", "", chunker.Key(), "", 0)
result.validation = &summary
return result, failure
}
// A cache hit is not model material. Its rejection is discarded and
// generation begins with the ordinary initial request below. Diagnostics
// from this discarded candidate are intentionally not promoted.
}
result.lookup = ChunkPlanDecision{Status: ChunkPlanInvalid, Reason: chunkPlanLookupReason(ChunkPlanInvalid)}
result.summary.LookupStatus = "invalid"
result.summary.LookupReason = chunkPlanLookupReason(ChunkPlanInvalid)
case ChunkPlanMissing, ChunkPlanInvalid:
// Generate below.
default:
result.summary.LookupStatus, result.summary.LookupReason = "invalid", chunkPlanLookupReason(ChunkPlanInvalid)
} else if decision.Status != ChunkPlanMissing && decision.Status != ChunkPlanInvalid {
return result, fmt.Errorf("load chunk plan returned unsupported decision status")
}
}
if mode == ChunkCacheAuto || mode == ChunkCacheRefresh {
result.summary.PublicationStatus = "not_published"
}
terminal, err := runProducerAttempts(ctx, producerAttemptConfig{
Retries: input.pipeline.Chunk.Retries,
Policy: input.pipeline.ChunkValidationPolicy,
AllowStructuralRetry: input.pipeline.ChunkExecutionClass == contracts.ExecutionClassLLMBacked,
}, func(attemptCtx context.Context, request producerAttemptRequest) (producerAttemptOutput, error) {
attempt := request.Number
attemptStarted := time.Now().UTC()
attemptPath := path.Join("chunk", fmt.Sprintf("attempt-%02d", attempt))
attemptCtx, llmScope := withDebugLLMScope(attemptCtx, attemptPath)
attemptTerminal := newAttemptTerminalRecorder(input.Debug, attemptPath, "chunk", llmScope, debugTimedEnvelope{Stage: string(StageChunk), ModuleKey: chunker.Key(), Attempt: attempt, AttemptKind: string(request.Kind), StartedAt: attemptStarted})
requestMetadata, metadataErr := cloneMetadata(input.Metadata)
if metadataErr != nil {
return producerAttemptOutput{}, attemptTerminal.record(nil, fmt.Errorf("clone chunk request metadata: %w", metadataErr))
}
chunkResult, callErr := chunker.Plan(attemptCtx, contracts.ChunkRequest{
Source: doc, SourceInput: sourceInput.Clone(), SessionID: sessionID,
References: CloneReferenceSet(input.pipeline.ChunkReferences.ReferenceSet),
LLMProfile: input.pipeline.Chunk.LLMProfile, StructuredOutputRepairAttempts: cloneStructuredOutputRepairAttempts(input.pipeline.Chunk.StructuredOutputRepairAttempts), Correction: request.Correction, Metadata: requestMetadata,
})
if callErr != nil {
return producerAttemptOutput{}, attemptTerminal.record(nil, fmt.Errorf("chunk source with chunker %q: %w", chunker.Key(), callErr))
}
plan, chunks, validationErr := validateAndMaterializeChunkPlan(doc, chunkResult.Plan)
if validationErr != nil {
attemptErr := fmt.Errorf("validate chunk plan from chunker %q: %w", chunker.Key(), validationErr)
payload := map[string]any{"plan": debugChunkPlanEnvelope(chunkResult.Plan)}
return producerAttemptOutput{}, attemptTerminal.record(payload, fmt.Errorf("%w: %v", contracts.ErrInvalidStructuredOutput, attemptErr))
}
planDigest, digestErr := source.DigestChunkPlan(plan)
if digestErr != nil {
return producerAttemptOutput{}, attemptTerminal.record(nil, fmt.Errorf("digest generated chunk plan: %w", digestErr))
}
producerMetadata, _, metadataErr := moduleManifestMetadata(chunker)
if metadataErr != nil {
return producerAttemptOutput{}, attemptTerminal.record(nil, fmt.Errorf("clone chunker manifest metadata: %w", metadataErr))
}
profile := ""
if input.pipeline.ChunkExecutionClass == contracts.ExecutionClassLLMBacked {
profile = input.pipeline.Chunk.LLMProfile
}
candidate := ChunkPlanRecord{
SchemaVersion: ChunkPlanSchemaVersion, SourceDigest: doc.Digest, PlanDigest: planDigest,
Plan: source.CloneChunkPlan(plan),
Producer: ChunkPlanProducer{
InputModule: input.Prepared.input.Key(), ChunkModule: chunker.Key(), LLMProfile: profile,
References: append([]artifacts.ReferenceProvenance(nil), referenceTargetProvenance(input.pipeline.ChunkReferences)...),
Metadata: producerMetadata,
},
CreatedAt: time.Now().UTC(),
}
return producerAttemptOutput{Value: generatedChunkPlanCandidate{plan: plan, chunks: chunks, record: candidate, producerDiagnostics: contracts.CloneProducerDiagnostics(chunkResult.Diagnostics), terminal: &attemptTerminal}, Candidate: chunkResult.ModelCandidate, Diagnostics: contracts.CloneProducerDiagnostics(chunkResult.Diagnostics)}, nil
}, func(validationCtx context.Context, output producerAttemptOutput) (validationReport, error) {
candidate, ok := output.Value.(generatedChunkPlanCandidate)
if !ok {
return validationReport{}, fmt.Errorf("chunk attempt candidate has incompatible type")
}
report, validationErr := r.validateChunkReport(validationCtx, doc, chunker.Key(), candidate.chunks, sourceInput, sessionID, input.pipeline.ChunkReferences.ReferenceSet, input.Metadata, input.Prepared.chunkValidators, candidate.terminal.envelope.Attempt, input.Debug)
payload := map[string]any{
"plan": debugChunkPlanEnvelope(candidate.plan), "materialized_chunks": debugSourceChunkEnvelopes(candidate.chunks),
"rejection": debugRejectedOutputPtr(chunkRejection(report, candidate.terminal.envelope.Attempt, chunker.Key())),
}
if validationErr != nil {
return report, candidate.terminal.record(payload, validationErr)
}
return report, candidate.terminal.record(payload, nil)
})
terminalSummary := validationSummary(terminal, StageChunk, "", "", chunker.Key(), "", 0)
if debugErr := writeProducerTerminalDebug(input.Debug, "chunk/terminal.json", terminal, input.pipeline.ChunkValidationPolicy, terminalSummary); debugErr != nil {
return result, debugErr
}
metadata, err := cloneMetadata(input.Metadata)
if err != nil {
if result.summary.ValidationStatus == "not_run" {
result.summary.ValidationStatus = "error"
}
return result, err
}
diagnostics, diagnosticErr := terminalDiagnosticGroups(terminal, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageChunk, ModuleKey: chunker.Key()}, nil)
if diagnosticErr != nil {
return result, fmt.Errorf("promote chunk diagnostics: %w", diagnosticErr)
if err := ctx.Err(); err != nil {
return result, err
}
result.diagnostics = diagnostics
if terminal.Action == producerTerminalRejected {
result.rejection = terminal.Rejection
if result.rejection != nil {
result.rejection.Stage = string(StageChunk)
result.rejection.ModuleKey = chunker.Key()
}
result.validation = &terminalSummary
if result.rejection != nil {
result.rejection.Validation = cloneValidationSummaryPtr(result.validation)
}
result.setValidation(result.rejection, nil)
return result, nil
produced, err := chunker.Plan(ctx, contracts.ChunkRequest{Operation: operation, Source: doc, SourceInput: sourceInput.Clone(), SessionID: sessionID, References: CloneReferenceSet(target.references), LLMProfile: input.pipeline.Chunk.LLMProfile, Metadata: metadata})
if err != nil {
return result, fmt.Errorf("chunk source with %q: %w", chunker.Key(), err)
}
candidate, ok := terminal.Value.(generatedChunkPlanCandidate)
if !ok {
return result, fmt.Errorf("chunk attempt terminal has incompatible value")
plan, outcome, err := completeProducerOperation(ctx, input.pipeline.ChunkExecutionClass, operation, produced.Plan, produced.Outcome, produced.Fallback)
if err != nil {
return result, fmt.Errorf("accept chunk plan with %q: %w", chunker.Key(), err)
}
if err := result.setCandidate(candidate.record, "generated"); err != nil {
return result, fmt.Errorf("clone generated chunk plan record: %w", err)
plan, chunks, err := validateAndMaterializeChunkPlan(doc, plan)
if err != nil {
return result, fmt.Errorf("materialize final chunk plan: %w", err)
}
digest, err := source.DigestChunkPlan(plan)
if err != nil {
return result, err
}
producerMetadata, _, err := moduleManifestMetadata(chunker)
if err != nil {
return result, err
}
profile := ""
if input.pipeline.ChunkExecutionClass == contracts.ExecutionClassLLMBacked {
profile = input.pipeline.Chunk.LLMProfile
}
record := ChunkPlanRecord{SchemaVersion: ChunkPlanSchemaVersion, SourceDigest: doc.Digest, PlanDigest: digest, Plan: source.CloneChunkPlan(plan), CreatedAt: time.Now().UTC(),
Producer: ChunkPlanProducer{InputModule: input.Prepared.input.Key(), ChunkModule: chunker.Key(), LLMProfile: profile, References: append([]artifacts.ReferenceProvenance(nil), referenceTargetProvenance(input.pipeline.ChunkReferences)...), Metadata: producerMetadata},
}
if err := result.setCandidate(record, "generated"); err != nil {
return result, err
}
if mode == ChunkCacheRefresh {
result.action = "refreshed"
result.summary.Action = "refreshed"
result.action, result.summary.Action = "refreshed", "refreshed"
}
if mode == ChunkCacheBypass {
result.action = "bypassed"
result.summary.Action = "bypassed"
result.action, result.summary.Action = "bypassed", "bypassed"
}
result.accepted = true
result.plan = &candidate.plan
result.chunks = candidate.chunks
result.validation = &terminalSummary
result.plan, result.chunks, result.accepted, result.outcome = &plan, chunks, true, outcome
result.setValidation(nil, nil)
if terminal.ValidationIncomplete {
if outcome.Disposition == contracts.ProducerFallback {
result.summary.ValidationStatus = "incomplete"
}
if (mode == ChunkCacheAuto || mode == ChunkCacheRefresh) && !terminal.ValidationIncomplete {
record, cloneErr := cloneChunkPlanRecord(*result.record)
if cloneErr != nil {
return result, fmt.Errorf("clone chunk plan record for publication: %w", cloneErr)
result.diagnostics, err = operationDiagnosticGroups(produced.Diagnostics, assessment, outcome, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageChunk, ModuleKey: chunker.Key()}, nil)
if err != nil {
return result, err
}
if mode == ChunkCacheAuto || mode == ChunkCacheRefresh {
result.summary.PublicationStatus = "not_published"
if outcome.ReuseEligible {
record.Diagnostics = contracts.CloneProducerDiagnostics(produced.Diagnostics)
if err := input.ChunkPlans.Save(record); err != nil {
return result, fmt.Errorf("save chunk plan: %w", err)
}
result.summary.PublicationStatus = "published"
}
record.Diagnostics = contracts.CloneProducerDiagnostics(candidate.producerDiagnostics)
if err := input.ChunkPlans.Save(record); err != nil {
return result, fmt.Errorf("save chunk plan: %w", err)
}
result.summary.PublicationStatus = "published"
}
return result, nil
}
func chunkRejection(report validationReport, attempt int, moduleKey string) *contracts.RejectedOutput {
rejection := report.FirstRejection()
if rejection == nil {
return nil
}
return &contracts.RejectedOutput{Stage: string(StageChunk), ModuleKey: moduleKey, ValidatorName: rejection.validatorName, ReasonCode: rejection.reasonCode, Message: rejection.message, AttemptCount: attempt, DiagnosticArtifactPath: rejection.diagnosticPath}
}
func chunkPlanLookupStatus(status ChunkPlanStatus) string {
switch status {
case ChunkPlanHit:

View File

@@ -10,40 +10,36 @@ import (
"sync"
"time"
"gitea.maximumdirect.net/eric/notarius/internal/core/artifacts"
"gitea.maximumdirect.net/eric/notarius/internal/core/fileio"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
)
type laneExtractState struct {
index int
prepared preparedLaneExecutor
deps []CheckpointFingerprint
decision CheckpointDecision
reuseEligible bool
values []erasedExtractArtifact
serialized []CheckpointArtifact
diagnostics []contracts.DiagnosticGroup
rejected []contracts.RejectedOutput
incomplete []int
validationSummaries []artifacts.ValidationSummary
results map[int]extractJobResult
remaining int
failed bool
terminal bool
output RunOutput
fallbackCount int
index int
prepared preparedLaneExecutor
deps []CheckpointFingerprint
decision CheckpointDecision
reuseEligible bool
values []erasedExtractArtifact
serialized []CheckpointArtifact
diagnostics []contracts.DiagnosticGroup
rejected []contracts.RejectedOutput
results map[int]extractJobResult
remaining int
failed bool
terminal bool
output RunOutput
}
type finalizedExtractResults struct {
accepted []erasedExtractArtifact
serialized []CheckpointArtifact
diagnostics []contracts.DiagnosticGroup
rejected []contracts.RejectedOutput
incomplete []int
validationSummaries []artifacts.ValidationSummary
decision CheckpointDecision
reuseEligible bool
accepted []erasedExtractArtifact
serialized []CheckpointArtifact
diagnostics []contracts.DiagnosticGroup
rejected []contracts.RejectedOutput
decision CheckpointDecision
reuseEligible bool
}
func loadExtract(loader CheckpointLoader, stepID, laneID, moduleKey string, deps []CheckpointFingerprint) (ExtractCheckpoint, CheckpointDecision) {
@@ -63,21 +59,14 @@ type extractJob struct {
}
type extractJobResult struct {
laneIndex int
chunkIndex int
value erasedExtractArtifact
serialized CheckpointArtifact
diagnostics []contracts.DiagnosticGroup
rejected *contracts.RejectedOutput
validationIncomplete bool
validationSummary *artifacts.ValidationSummary
err error
}
type extractAttemptValue struct {
artifact erasedExtractArtifact
serialized CheckpointArtifact
terminal *attemptTerminalRecorder
laneIndex int
chunkIndex int
value erasedExtractArtifact
serialized CheckpointArtifact
diagnostics []contracts.DiagnosticGroup
rejected *contracts.RejectedOutput
outcome contracts.ProducerOutcome
err error
}
type laneCompletion struct {
@@ -125,7 +114,7 @@ func initializeLaneStates(input RunInput, step PreparedPipelineStep, checkpoints
return states, err
}
if input.CheckpointPolicy.requiresReusable(input.stepID, prepared.resolved.ID) && !input.CheckpointPolicy.forced(input.stepID, prepared.resolved.ID) {
if !laneReferencesReuseEligible(input, prepared.resolved) {
if input.reuseIneligible || !laneReferencesReuseEligible(input, prepared.resolved) {
return states, fmt.Errorf("required reusable checkpoint unavailable for step %q lane %q: generated input lineage is validation-incomplete", input.stepID, prepared.resolved.ID)
}
state, err := hydrateRequiredLane(input, loader, doc, i, prepared)
@@ -399,7 +388,7 @@ func prepareLaneExtract(input RunInput, loader CheckpointLoader, doc *source.Sou
}
extractReferences := operationReferenceSet(input, lane.ExtractReferences)
deps := append(digestFingerprints("chunks", digest), generatedReferenceDependencies(extractReferences)...)
state := &laneExtractState{index: index, prepared: prepared, deps: normalizeCheckpointFingerprints(deps), reuseEligible: referenceTargetReuseEligible(input, lane.ExtractReferences), remaining: len(chunks), results: make(map[int]extractJobResult, len(chunks))}
state := &laneExtractState{index: index, prepared: prepared, deps: normalizeCheckpointFingerprints(deps), reuseEligible: !input.reuseIneligible && referenceTargetReuseEligible(input, lane.ExtractReferences), remaining: len(chunks), results: make(map[int]extractJobResult, len(chunks))}
if !state.reuseEligible {
state.decision = checkpointDecision(CheckpointDecisionExecuted, CheckpointReasonValidationIncompleteLineage)
recordCheckpointEvent(output, loader, string(StageExtract), input.stepID, lane.ID, lane.Extract.Module, state.decision)
@@ -436,99 +425,56 @@ func prepareLaneExtract(input RunInput, loader CheckpointLoader, doc *source.Sou
func (r *Runner) runExtractJob(ctx context.Context, input RunInput, doc *source.SourceDocument, sourceInput contracts.LLMInputMaterial, sessionID string, job extractJob) extractJobResult {
state := job.lane
chunk, cloneErr := cloneSourceChunk(job.chunk)
lane, typed := state.prepared.resolved, state.prepared.typed
result := extractJobResult{laneIndex: state.index, chunkIndex: job.chunk.Index}
if cloneErr != nil {
result.err = fmt.Errorf("clone chunk %q for extraction: %w", job.chunk.ID, cloneErr)
if err := ctx.Err(); err != nil {
result.err = err
return result
}
terminalResult, err := runProducerAttempts(ctx, producerAttemptConfig{Retries: lane.Extract.Retries, Policy: lane.ExtractValidationPolicy, AllowStructuralRetry: lane.ExtractExecutionClass == contracts.ExecutionClassLLMBacked}, func(attemptCtx context.Context, request producerAttemptRequest) (producerAttemptOutput, error) {
attempt := request.Number
started := time.Now().UTC()
attemptPath := path.Join("extract", fileio.EncodePathComponent(lane.ID), fmt.Sprintf("chunk-%06d", chunk.Index+1), fmt.Sprintf("attempt-%02d", attempt))
attemptCtx, llmScope := withDebugLLMScope(attemptCtx, attemptPath)
terminal := newAttemptTerminalRecorder(input.Debug, attemptPath, "extract", llmScope, debugTimedEnvelope{Stage: string(StageExtract), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Extract.Module, Attempt: attempt, AttemptKind: string(request.Kind), StartedAt: started})
requestMetadata, metadataErr := cloneMetadata(input.Metadata)
if metadataErr != nil {
return producerAttemptOutput{}, terminal.record(nil, fmt.Errorf("clone extract request metadata: %w", metadataErr))
}
extractReferences := operationReferenceSet(input, lane.ExtractReferences)
extracted, callErr := typed.extract(attemptCtx, typed.extractor, contracts.TypedExtractionRequest{Source: doc, Chunk: &chunk, SourceInput: chunkInputMaterial(sourceInput, chunk), SessionID: sessionID, References: CloneReferenceSet(extractReferences), LLMProfile: lane.Extract.LLMProfile, StructuredOutputRepairAttempts: cloneStructuredOutputRepairAttempts(lane.Extract.StructuredOutputRepairAttempts), Correction: request.Correction, Metadata: requestMetadata})
if callErr != nil {
attemptErr := fmt.Errorf("extract lane %q chunk %q with extractor %q: %w", lane.ID, chunk.ID, lane.Extract.Module, callErr)
return producerAttemptOutput{}, terminal.record(nil, attemptErr)
}
artifact := erasedExtractArtifact{LaneID: lane.ID, ExtractorKey: lane.Extract.Module, SourceID: doc.ID, ChunkID: chunk.ID, ChunkIndex: chunk.Index, ChunkRef: chunk.Ref, Value: extracted.Value}
serializedCandidate, encodeErr := serializeCandidateArtifact(typed.codec, artifact.LaneID, artifact.ExtractorKey, artifact.SourceID, artifact.Value)
if encodeErr != nil {
attemptErr := fmt.Errorf("serialize extract candidate for lane %q chunk %q: %w", lane.ID, chunk.ID, encodeErr)
payload := map[string]any{}
return producerAttemptOutput{}, terminal.record(payload, attemptErr)
}
serializedCandidate.ChunkID, serializedCandidate.ChunkIndex, serializedCandidate.ChunkRef = artifact.ChunkID, artifact.ChunkIndex, artifact.ChunkRef
return producerAttemptOutput{Value: extractAttemptValue{artifact: artifact, serialized: serializedCandidate, terminal: &terminal}, Candidate: extracted.ModelCandidate, Diagnostics: contracts.CloneProducerDiagnostics(extracted.Diagnostics)}, nil
}, func(validationCtx context.Context, output producerAttemptOutput) (validationReport, error) {
candidate, ok := output.Value.(extractAttemptValue)
if !ok {
return validationReport{}, fmt.Errorf("extract attempt has incompatible value")
}
report, validationErr := r.validateTypedReport(validationCtx, typed.codec, typedValidationTarget{stage: StageExtract, stepID: input.stepID, laneID: lane.ID, moduleKey: lane.Extract.Module, source: doc, sourceID: doc.ID, sourceInput: chunkInputMaterial(sourceInput, chunk), sessionID: sessionID, references: operationReferenceSet(input, lane.ExtractReferences), metadata: input.Metadata, chunk: &chunk, ref: chunk.Ref, value: candidate.artifact.Value, candidate: &candidate.serialized}, state.prepared.extractValidators, candidate.terminal.envelope.Attempt, input.Debug)
payload := map[string]any{
"output": debugCheckpointArtifact(candidate.serialized),
"rejection": debugRejectedOutputPtr(typedRejection(report, typedValidationTarget{stage: StageExtract, stepID: input.stepID, laneID: lane.ID, moduleKey: lane.Extract.Module, chunk: &chunk}, candidate.terminal.envelope.Attempt)),
}
if validationErr != nil {
return report, candidate.terminal.record(payload, validationErr)
}
return report, candidate.terminal.record(payload, nil)
})
result.err = err
summary := validationSummary(terminalResult, StageExtract, input.stepID, lane.ID, lane.Extract.Module, chunk.ID, chunk.Index)
if debugErr := writeProducerTerminalDebug(input.Debug, path.Join("extract", fileio.EncodePathComponent(lane.ID), fmt.Sprintf("chunk-%06d", chunk.Index+1), "terminal.json"), terminalResult, lane.ExtractValidationPolicy, summary); debugErr != nil {
result.err = errors.Join(result.err, debugErr)
chunk, err := cloneSourceChunk(job.chunk)
if err != nil {
result.err = err
return result
}
if err == nil {
diagnostics, diagnosticErr := terminalDiagnosticGroups(terminalResult, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageExtract, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Extract.Module}, &chunk)
if diagnosticErr != nil {
result.err = fmt.Errorf("promote extract diagnostics: %w", diagnosticErr)
return result
}
result.diagnostics = diagnostics
}
if err == nil && terminalResult.Action == producerTerminalRejected {
result.rejected = terminalResult.Rejection
if result.rejected != nil {
result.rejected.Stage, result.rejected.StepID, result.rejected.LaneID, result.rejected.ModuleKey, result.rejected.ChunkID, result.rejected.ChunkIndex = string(StageExtract), input.stepID, lane.ID, lane.Extract.Module, chunk.ID, chunk.Index
result.validationSummary = &summary
result.rejected.Validation = cloneValidationSummaryPtr(result.validationSummary)
}
metadata, err := cloneMetadata(input.Metadata)
if err != nil {
result.err = err
return result
}
if err == nil {
candidate, ok := terminalResult.Value.(extractAttemptValue)
if !ok {
result.err = fmt.Errorf("extract attempt terminal has incompatible value")
return result
}
stored, encodeErr := checkpointArtifact(typed.codec, candidate.artifact.LaneID, candidate.artifact.ExtractorKey, candidate.artifact.SourceID, candidate.artifact.Value)
payload := map[string]any{"output": debugCheckpointArtifact(candidate.serialized), "rejection": debugRejectedOutputPtr(nil)}
if encodeErr != nil {
attemptErr := fmt.Errorf("serialize accepted extract output for lane %q chunk %q: %w", lane.ID, chunk.ID, encodeErr)
result.err = candidate.terminal.record(payload, attemptErr)
return result
}
stored.ChunkID, stored.ChunkIndex, stored.ChunkRef = candidate.artifact.ChunkID, candidate.artifact.ChunkIndex, candidate.artifact.ChunkRef
stored.Diagnostics = terminalCheckpointDiagnostics(terminalResult)
if debugErr := candidate.terminal.record(payload, nil); debugErr != nil {
result.err = debugErr
return result
}
result.value, result.serialized = candidate.artifact, stored
result.validationIncomplete = terminalResult.ValidationIncomplete
result.validationSummary = &summary
references := operationReferenceSet(input, lane.ExtractReferences)
target := typedValidationTarget{stage: StageExtract, stepID: input.stepID, laneID: lane.ID, moduleKey: lane.Extract.Module, source: doc, sourceID: doc.ID, sourceInput: chunkInputMaterial(sourceInput, chunk), sessionID: sessionID, references: references, metadata: input.Metadata, execution: input.Execution, chunk: &chunk, ref: chunk.Ref}
var assessment contracts.CandidateAssessment
assess := typedCandidateAssessor[any](typed.codec, target, state.prepared.extractValidators)
operation := contracts.ProducerOperation[any]{Controls: lane.ExtractControls, Execution: input.Execution, ReuseEligible: !input.reuseIneligible && referenceTargetReuseEligible(input, lane.ExtractReferences),
Assess: func(ctx context.Context, value any) (contracts.CandidateAssessment, error) {
var err error
assessment, err = assess(ctx, value)
return assessment, err
},
}
extracted, err := typed.extract(ctx, typed.extractor, contracts.TypedExtractionRequest[any]{Operation: operation, Source: doc, Chunk: &chunk, SourceInput: target.sourceInput.Clone(), SessionID: sessionID, References: CloneReferenceSet(references), LLMProfile: lane.Extract.LLMProfile, Metadata: metadata})
if err != nil {
result.err = fmt.Errorf("extract lane %q chunk %q: %w", lane.ID, chunk.ID, err)
return result
}
value, outcome, err := completeProducerOperation(ctx, lane.ExtractExecutionClass, operation, extracted.Value, extracted.Outcome, extracted.Fallback)
if err != nil {
result.err = fmt.Errorf("accept extract lane %q chunk %q: %w", lane.ID, chunk.ID, err)
return result
}
stored, err := checkpointArtifact(typed.codec, lane.ID, lane.Extract.Module, doc.ID, value)
if err != nil {
result.err = fmt.Errorf("encode extract lane %q chunk %q: %w", lane.ID, chunk.ID, err)
return result
}
stored.ChunkID, stored.ChunkIndex, stored.ChunkRef = chunk.ID, chunk.Index, chunk.Ref
result.diagnostics, err = operationDiagnosticGroups(extracted.Diagnostics, assessment, outcome, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageExtract, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Extract.Module}, &chunk)
if err != nil {
result.err = err
return result
}
result.value = erasedExtractArtifact{LaneID: lane.ID, ExtractorKey: lane.Extract.Module, SourceID: doc.ID, ChunkID: chunk.ID, ChunkIndex: chunk.Index, ChunkRef: chunk.Ref, Value: value}
result.serialized, result.outcome = stored, outcome
return result
}
@@ -541,9 +487,6 @@ func finalizeLaneExtract(checkpoints CheckpointRecorder, stepID string, state *l
sort.Ints(indexes)
for _, index := range indexes {
result := state.results[index]
if result.validationSummary != nil {
state.validationSummaries = append(state.validationSummaries, artifacts.CloneValidationSummary(*result.validationSummary))
}
if result.rejected != nil {
state.rejected = append(state.rejected, *result.rejected)
state.diagnostics = append(state.diagnostics, result.diagnostics...)
@@ -552,17 +495,16 @@ func finalizeLaneExtract(checkpoints CheckpointRecorder, stepID string, state *l
state.values = append(state.values, result.value)
state.serialized = append(state.serialized, result.serialized)
state.diagnostics = append(state.diagnostics, result.diagnostics...)
if result.validationIncomplete {
state.incomplete = append(state.incomplete, result.chunkIndex)
if !result.outcome.ReuseEligible {
state.reuseEligible = false
}
if result.outcome.Disposition == contracts.ProducerFallback {
state.fallbackCount++
}
}
sort.SliceStable(state.values, func(i, j int) bool { return state.values[i].ChunkIndex < state.values[j].ChunkIndex })
sort.SliceStable(state.serialized, func(i, j int) bool { return state.serialized[i].ChunkIndex < state.serialized[j].ChunkIndex })
sort.SliceStable(state.rejected, func(i, j int) bool { return state.rejected[i].ChunkIndex < state.rejected[j].ChunkIndex })
sort.Ints(state.incomplete)
if len(state.incomplete) > 0 {
state.reuseEligible = false
}
if !state.decision.Reused && state.reuseEligible {
if err := recordExtract(checkpoints, stepID, lane.ID, lane.Extract.Module, state.deps, state.serialized, state.rejected); err != nil {
return fmt.Errorf("write extract checkpoint for lane %q: %w", lane.ID, err)
@@ -573,24 +515,21 @@ func finalizeLaneExtract(checkpoints CheckpointRecorder, stepID string, state *l
func (r *Runner) continueLane(ctx context.Context, input RunInput, checkpoints CheckpointRecorder, loader CheckpointLoader, doc *source.SourceDocument, sourceInput contracts.LLMInputMaterial, sessionID string, chunks []source.Chunk, state *laneExtractState) (RunOutput, error) {
lane := state.prepared.resolved
local := RunOutput{Manifest: manifestFromPipeline(input)}
local := RunOutput{Manifest: manifestFromPipeline(input), FallbackCount: state.fallbackCount}
results := finalizedExtractResults{
accepted: state.values,
serialized: state.serialized,
diagnostics: state.diagnostics,
rejected: state.rejected,
incomplete: state.incomplete,
validationSummaries: state.validationSummaries,
decision: state.decision,
reuseEligible: state.reuseEligible,
accepted: state.values,
serialized: state.serialized,
diagnostics: state.diagnostics,
rejected: state.rejected,
decision: state.decision,
reuseEligible: state.reuseEligible,
}
local.diagnosticGroups = append(local.diagnosticGroups, contracts.CloneDiagnosticCollection(contracts.DiagnosticCollection{Groups: results.diagnostics}).Groups...)
local.Rejected = append(local.Rejected, cloneRejectedOutputs(results.rejected)...)
local.ValidationSummaries = append(local.ValidationSummaries, cloneValidationSummaries(results.validationSummaries)...)
if err := writeDebugTimed(input.Debug, path.Join("extract", fileio.EncodePathComponent(lane.ID), "input.json"), debugTimedEnvelope{Stage: string(StageExtract), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Extract.Module, StartedAt: time.Now().UTC(), Payload: map[string]any{"reused": results.decision.Reused, "decision": results.decision, "source": debugSourceDocumentEnvelope(doc), "chunks": debugSourceChunkEnvelopes(chunks), "options": redactSensitiveMap(lane.Extract.Options), "metadata": redactSensitiveMap(input.Metadata)}}); err != nil {
return local, &laneRunError{stage: StageExtract, err: err}
}
if err := writeDebugTimed(input.Debug, path.Join("extract", fileio.EncodePathComponent(lane.ID), "output.json"), debugTimedEnvelope{Stage: string(StageExtract), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Extract.Module, StartedAt: time.Now().UTC(), Payload: map[string]any{"reused": results.decision.Reused, "outputs": debugCheckpointArtifacts(results.serialized), "rejected": debugRejectedOutputEnvelopes(results.rejected), "validation_incomplete_chunks": append([]int(nil), results.incomplete...)}}); err != nil {
if err := writeDebugTimed(input.Debug, path.Join("extract", fileio.EncodePathComponent(lane.ID), "output.json"), debugTimedEnvelope{Stage: string(StageExtract), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Extract.Module, StartedAt: time.Now().UTC(), Payload: map[string]any{"reused": results.decision.Reused, "outputs": debugCheckpointArtifacts(results.serialized), "rejected": debugRejectedOutputEnvelopes(results.rejected)}}); err != nil {
return local, &laneRunError{stage: StageExtract, err: err}
}
if len(results.accepted) == 0 {
@@ -653,6 +592,7 @@ func mergeLaneOutput(dst *RunOutput, src RunOutput) error {
if dst == nil {
return nil
}
dst.FallbackCount += src.FallbackCount
dst.NormalizeOutputs = append(dst.NormalizeOutputs, cloneSerializedOutputs(src.NormalizeOutputs)...)
dst.Rejected = append(dst.Rejected, cloneRejectedOutputs(src.Rejected)...)
appendDiagnosticGroups(dst, src.diagnosticGroups)

View File

@@ -0,0 +1,78 @@
package pipeline
import (
"context"
"fmt"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
)
// completeProducerOperation assesses deterministic work once. LLM modules have
// already used their operation's assessor through RunProducer and must return
// its disposition; the runner never assesses those results a second time.
func completeProducerOperation[T any](ctx context.Context, class contracts.ExecutionClass, operation contracts.ProducerOperation[T], value T, outcome contracts.ProducerOutcome, fallback func(context.Context) (T, error)) (T, contracts.ProducerOutcome, error) {
var zero T
if err := ctx.Err(); err != nil {
return zero, contracts.ProducerOutcome{}, err
}
if class == contracts.ExecutionClassDeterministic {
assessment, err := operation.Assess(ctx, value)
if err != nil {
return zero, contracts.ProducerOutcome{}, err
}
if err := ctx.Err(); err != nil {
return zero, contracts.ProducerOutcome{}, err
}
if !assessment.Accepted() {
return finishProducerFailure(ctx, operation.Controls.Mode, assessment.Err(), fallback)
}
outcome = contracts.ProducerOutcome{Disposition: contracts.ProducerAccepted, ReuseEligible: operation.ReuseEligible}
} else if class != contracts.ExecutionClassLLMBacked {
return zero, contracts.ProducerOutcome{}, fmt.Errorf("unsupported producer execution class %q", class)
}
switch outcome.Disposition {
case contracts.ProducerAccepted:
outcome.ReuseEligible = operation.ReuseEligible && outcome.ReuseEligible
case contracts.ProducerFallback:
if operation.Controls.Mode != contracts.ModePermissive {
return zero, contracts.ProducerOutcome{}, fmt.Errorf("producer returned fallback without permissive mode")
}
if outcome.FallbackReason == "" {
return zero, contracts.ProducerOutcome{}, fmt.Errorf("producer fallback has no reason")
}
outcome.ReuseEligible = false
default:
return zero, contracts.ProducerOutcome{}, fmt.Errorf("producer did not return an acceptance or fallback outcome")
}
return value, outcome, nil
}
func operationDiagnosticGroups(diagnostics []contracts.ProducerDiagnostic, assessment contracts.CandidateAssessment, outcome contracts.ProducerOutcome, origin contracts.DiagnosticOrigin, chunk *source.Chunk) ([]contracts.DiagnosticGroup, error) {
groups, err := promoteProducerDiagnostics(diagnostics, origin, chunk)
if err != nil {
return nil, err
}
if outcome.Disposition == contracts.ProducerFallback {
warning := contracts.ProducerDiagnostic{
Disposition: contracts.DiagnosticDispositionWarning, Category: contracts.DiagnosticCategoryFallback,
ReasonCode: "producer_fallback", OccurrenceCount: 1,
Samples: []contracts.DiagnosticSample{{Scope: origin.ModuleKey, Message: outcome.FallbackReason}},
}
fallbackGroups, err := promoteProducerDiagnostics([]contracts.ProducerDiagnostic{warning}, origin, chunk)
return append(groups, fallbackGroups...), err
}
for _, finding := range assessment.Validators {
if finding.Decision != contracts.AssessmentApproved {
continue
}
validatorOrigin := origin
validatorOrigin.ValidatorKey = finding.ValidatorName
validatorGroups, err := promoteProducerDiagnostics(finding.Result.Diagnostics, validatorOrigin, chunk)
if err != nil {
return nil, err
}
groups = append(groups, validatorGroups...)
}
return groups, nil
}

View File

@@ -0,0 +1,378 @@
package pipeline
import (
"context"
"errors"
"fmt"
"reflect"
"sync"
"testing"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
"go.maximumdirect.net/promptkit"
)
type runnerProbe struct {
mu sync.Mutex
calls map[string]int
eligible map[string][]bool
}
func newRunnerProbe() *runnerProbe {
return &runnerProbe{calls: map[string]int{}, eligible: map[string][]bool{}}
}
func (p *runnerProbe) record(key string, eligible bool) {
p.mu.Lock()
defer p.mu.Unlock()
p.calls[key]++
p.eligible[key] = append(p.eligible[key], eligible)
}
type runnerNotesProducer struct {
name string
probe *runnerProbe
engine *promptkit.Engine
native bool
references bool
failure error
cancel context.CancelFunc
}
func (p *runnerNotesProducer) Key() string { return p.name }
func (p *runnerNotesProducer) ReferenceSlots() []contracts.ReferenceSlot {
if !p.references {
return nil
}
return []contracts.ReferenceSlot{{Name: "context", AcceptedArtifactKinds: []contracts.ArtifactKind{"test/notes"}, AcceptedMediaTypes: []string{"application/json"}}}
}
func (p *runnerNotesProducer) fallback(ctx context.Context, role string) (codecNotes, error) {
p.probe.record(p.name+"/"+role+"/fallback", false)
return codecNotes{Items: []string{}}, ctx.Err()
}
func (p *runnerNotesProducer) Extract(ctx context.Context, request contracts.TypedExtractionRequest[codecNotes]) (contracts.TypedExtractionResult[codecNotes], error) {
p.probe.record(p.name+"/extract", request.Operation.ReuseEligible)
if p.cancel != nil {
p.cancel()
}
if p.failure != nil {
return contracts.TypedExtractionResult[codecNotes]{}, p.failure
}
if p.native {
initial := nativeProducerInitial()
initial.ProfileID, initial.SessionID = request.LLMProfile, request.SessionID
value, outcome, err := RunProducer(ctx, p.engine, request.Operation, initial,
func(ctx context.Context, result *promptkit.RunResult) (*codecNotes, []string, error) {
number, _, err := interpretProducerNumber(ctx, result)
if err != nil {
return nil, nil, err
}
return &codecNotes{Items: []string{fmt.Sprint(*number)}}, nil, nil
}, producerCorrection, func(ctx context.Context, _ *codecNotes) (codecNotes, error) { return p.fallback(ctx, "extract") })
return contracts.TypedExtractionResult[codecNotes]{Value: value, Outcome: outcome}, err
}
return contracts.TypedExtractionResult[codecNotes]{Value: codecNotes{Items: []string{p.name}}, Fallback: func(ctx context.Context) (codecNotes, error) { return p.fallback(ctx, "extract") }}, nil
}
func (p *runnerNotesProducer) Merge(ctx context.Context, request contracts.TypedMergeRequest[codecNotes]) (contracts.TypedMergeResult[codecNotes], error) {
p.probe.record(p.name+"/merge", request.Operation.ReuseEligible)
if p.references {
if slot, ok := request.References.Slots["context"]; ok && len(slot.Items) > 0 {
p.probe.record(p.name+"/reference", request.Operation.ReuseEligible)
}
}
value := codecNotes{Items: []string{}}
for _, output := range request.ExtractOutputs {
value.Items = append(value.Items, output.Value.Items...)
}
return contracts.TypedMergeResult[codecNotes]{Value: value, Fallback: func(ctx context.Context) (codecNotes, error) { return p.fallback(ctx, "merge") }}, nil
}
func (p *runnerNotesProducer) Normalize(ctx context.Context, request contracts.TypedNormalizeRequest[codecNotes]) (contracts.TypedNormalizeResult[codecNotes], error) {
p.probe.record(p.name+"/normalize", request.Operation.ReuseEligible)
return contracts.TypedNormalizeResult[codecNotes]{Value: request.MergeOutput.Value, Fallback: func(ctx context.Context) (codecNotes, error) { return p.fallback(ctx, "normalize") }}, nil
}
func registerRunnerNotes(t *testing.T, catalog ModuleCatalog, producer runnerNotesProducer) ArtifactLaneProfile {
t.Helper()
class := contracts.ExecutionClassDeterministic
if producer.native {
class = contracts.ExecutionClassLLMBacked
}
spec := func(stage ModuleStage) ModuleSpec {
return ModuleSpec{Key: producer.name, Stage: stage, ExecutionClass: contracts.ExecutionClassDeterministic, ArtifactKind: "test/notes", ReferenceSlots: producer.ReferenceSlots()}
}
extractSpec := spec(StageExtract)
extractSpec.ExecutionClass = class
if err := RegisterExtractorBuilder(catalog.Extractors, extractSpec, rejectUnconfiguredOptions, func(request BuildRequest) (contracts.Extractor[codecNotes], error) {
copy := producer
copy.engine = request.Dependencies.Engine
return &copy, nil
}); err != nil {
t.Fatal(err)
}
if err := RegisterMerger(catalog.Mergers, spec(StageMerge), func() (contracts.Merger[codecNotes], error) { copy := producer; return &copy, nil }); err != nil {
t.Fatal(err)
}
if err := RegisterNormalizer(catalog.Normalizers, spec(StageNormalize), func() (contracts.Normalizer[codecNotes], error) { copy := producer; return &copy, nil }); err != nil {
t.Fatal(err)
}
return ArtifactLaneProfile{Extract: Binding(producer.name), Merge: Binding(producer.name), Normalize: Binding(producer.name)}
}
func prepareRunnerProfile(t *testing.T, catalog ModuleCatalog, profile PipelineProfile, engine *promptkit.Engine) *PreparedPipeline {
t.Helper()
resolved, err := ResolvePipeline(profile, ResolveOptions{}, catalog)
if err != nil {
t.Fatal(err)
}
resolved, _, err = MaterializeReferences(resolved, catalog, ReferenceMaterializationOptions{})
if err != nil {
t.Fatal(err)
}
prepared, err := Prepare(resolved, registriesFromModuleCatalog(catalog), ModuleDependencies{Engine: engine})
if err != nil {
t.Fatal(err)
}
return prepared
}
type namedRunnerValidator struct {
name string
notesAssessmentValidator
}
func (v namedRunnerValidator) Name() string { return v.name }
func registerRunnerRejection(t *testing.T, catalog ModuleCatalog, probe *runnerProbe) ValidatorOverride {
t.Helper()
if err := RegisterTypedValidator(catalog.Validators, "test/notes", ValidatorSpec{Key: "reject", ExecutionClass: contracts.ExecutionClassDeterministic}, func() (contracts.TypedValidator[codecNotes], error) {
return namedRunnerValidator{"reject", notesAssessmentValidator(func(_ context.Context, request contracts.TypedValidationRequest[codecNotes]) (contracts.ValidationResult, error) {
probe.record(request.ModuleKey+"/"+request.Stage+"/validator", false)
return contracts.ValidationResult{ReasonCode: "domain_rejection", CorrectionGuidance: "Return a supported value."}, nil
})}, nil
}); err != nil {
t.Fatal(err)
}
return ValidatorOverride{Set: true, Validators: []ModuleBinding{Binding("reject")}}
}
func TestRunnerPropagatesLaneFallbackWithoutCountingDependents(t *testing.T) {
for _, stage := range []ModuleStage{StageExtract, StageMerge, StageNormalize} {
t.Run(string(stage), func(t *testing.T) {
probe := newRunnerProbe()
catalog := typedResolutionCatalog(t, completeTypedCatalogOptions())
affected := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "affected", probe: probe})
unrelated := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "unrelated", probe: probe})
reject := registerRunnerRejection(t, catalog, probe)
permissive := contracts.ModePermissive
switch stage {
case StageExtract:
affected.Extract.Validators, affected.Extract.Mode = reject, &permissive
case StageMerge:
affected.Merge.Validators, affected.Merge.Mode = reject, &permissive
case StageNormalize:
affected.Normalize.Validators, affected.Normalize.Mode = reject, &permissive
}
profile := typedResolutionProfile()
profile.Artifacts = map[string]ArtifactLaneProfile{"affected": affected, "unrelated": unrelated}
output, err := New().Run(context.Background(), RunInput{Prepared: prepareRunnerProfile(t, catalog, profile, nil), RawInput: []byte("input"), ExtractWorkers: 1})
if err != nil {
t.Fatal(err)
}
if output.FallbackCount != 1 || len(output.NormalizeOutputs) != 2 {
t.Fatalf("fallback count=%d, outputs=%d", output.FallbackCount, len(output.NormalizeOutputs))
}
after := false
for _, role := range []ModuleStage{StageExtract, StageMerge, StageNormalize} {
for _, name := range []string{"affected", "unrelated"} {
key := name + "/" + string(role)
want := name != "affected" || !after
if probe.calls[key] != 1 || !reflect.DeepEqual(probe.eligible[key], []bool{want}) {
t.Fatalf("%s calls=%d eligibility=%#v, want %t", key, probe.calls[key], probe.eligible[key], want)
}
}
if role == stage {
after = true
}
}
if probe.calls["affected/"+string(stage)+"/validator"] != 1 || probe.calls["affected/"+string(stage)+"/fallback"] != 1 {
t.Fatalf("deterministic work was retried or fallback revalidated: %#v", probe.calls)
}
lanes := output.normalizeReuseEligibility
for key, eligible := range lanes {
if eligible != (key.laneID == "unrelated") {
t.Fatalf("normalized eligibility = %#v", lanes)
}
}
})
}
}
func TestRunnerAssessesNativeRevisionsWithoutOuterRevalidation(t *testing.T) {
probe := newRunnerProbe()
providerCalls := 0
engine := nativeProducerEngine(t, producerClientFunc(func(_ context.Context, request promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) {
if request.Target.Model != "runner-model" || request.Prompt.SessionID != "runner-session" {
t.Fatalf("run-wide override missing: %#v", request)
}
value := providerCalls
providerCalls++
return &promptkit.GenerateResponse{Content: fmt.Sprintf(`{"value":%d}`, value)}, nil
}))
catalog := typedResolutionCatalog(t, completeTypedCatalogOptions())
lane := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "native", probe: probe, native: true})
for _, name := range []string{"first", "second"} {
if err := RegisterTypedValidator(catalog.Validators, "test/notes", ValidatorSpec{Key: name, ExecutionClass: contracts.ExecutionClassDeterministic}, func() (contracts.TypedValidator[codecNotes], error) {
return namedRunnerValidator{name, notesAssessmentValidator(func(_ context.Context, request contracts.TypedValidationRequest[codecNotes]) (contracts.ValidationResult, error) {
probe.record(name+"/"+request.Value.Items[0], true)
if name == "second" && request.Value.Items[0] == "0" {
return contracts.ValidationResult{ReasonCode: "not_one", CorrectionGuidance: "Return value one."}, nil
}
return contracts.ValidationResult{Approved: true}, nil
})}, nil
}); err != nil {
t.Fatal(err)
}
}
lane.Extract.Validators = ValidatorOverride{Set: true, Validators: []ModuleBinding{Binding("first"), Binding("second")}}
profile := typedResolutionProfile()
profile.Artifacts = map[string]ArtifactLaneProfile{"native": lane}
profile.LLMProfile = "chosen"
turns := 1
profile.MaxAdditionalTurns = &turns
output, err := New().Run(context.Background(), RunInput{
Prepared: prepareRunnerProfile(t, catalog, profile, engine), RawInput: []byte("input"), SessionID: "runner-session",
Execution: contracts.ExecutionOptions{Execution: &promptkit.ExecutionTargetOverride{Model: "runner-model"}},
})
if err != nil {
t.Fatal(err)
}
if providerCalls != 2 || output.FallbackCount != 0 || len(output.NormalizeOutputs) != 1 {
t.Fatalf("native calls=%d, output=%#v", providerCalls, output)
}
for _, key := range []string{"first/0", "second/0", "first/1", "second/1", "native/extract", "native/merge", "native/normalize"} {
if probe.calls[key] != 1 {
t.Fatalf("%s called %d times", key, probe.calls[key])
}
}
}
func TestRunnerGeneratedFallbackReferencesTaintOnlyActualConsumers(t *testing.T) {
probe := newRunnerProbe()
catalog := typedResolutionCatalog(t, completeTypedCatalogOptions())
producer := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "producer", probe: probe})
earlier := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "earlier", probe: probe})
consumer := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "consumer", probe: probe, references: true})
unrelated := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "later", probe: probe})
producer.Normalize.Validators = registerRunnerRejection(t, catalog, probe)
permissive := contracts.ModePermissive
producer.Normalize.Mode = &permissive
consumer.Merge.References = map[string]ReferenceSource{"context": GeneratedReference("build", "producer")}
profile := typedResolutionProfile()
profile.Artifacts = nil
profile.Steps = []PipelineStepProfile{
{ID: "build", Artifacts: map[string]ArtifactLaneProfile{"producer": producer, "earlier": earlier}},
{ID: "consume", Artifacts: map[string]ArtifactLaneProfile{"consumer": consumer, "later": unrelated}},
}
output, err := New().Run(context.Background(), RunInput{Prepared: prepareRunnerProfile(t, catalog, profile, nil), RawInput: []byte("input"), ExtractWorkers: 1})
if err != nil {
t.Fatal(err)
}
if output.FallbackCount != 1 || len(output.NormalizeOutputs) != 4 || probe.calls["consumer/reference"] != 1 {
t.Fatalf("handoff failed: count=%d outputs=%d observations=%#v", output.FallbackCount, len(output.NormalizeOutputs), probe.calls)
}
for _, key := range []string{"earlier/extract", "earlier/merge", "earlier/normalize", "later/extract", "later/merge", "later/normalize", "consumer/extract"} {
if !reflect.DeepEqual(probe.eligible[key], []bool{true}) {
t.Fatalf("unaffected work %s tainted: %#v", key, probe.eligible[key])
}
}
for _, key := range []string{"consumer/merge", "consumer/normalize"} {
if !reflect.DeepEqual(probe.eligible[key], []bool{false}) {
t.Fatalf("dependent %s remained reusable: %#v", key, probe.eligible[key])
}
}
if output.normalizeReuseEligibility[generatedOutputKeyFor("consume", "consumer")] || !output.normalizeReuseEligibility[generatedOutputKeyFor("consume", "later")] {
t.Fatalf("generated lineage = %#v", output.normalizeReuseEligibility)
}
}
type runnerFallbackChunker struct{}
func (runnerFallbackChunker) Key() string { return "fallback-chunk" }
func (runnerFallbackChunker) ReferenceSlots() []contracts.ReferenceSlot { return nil }
func (runnerFallbackChunker) Plan(_ context.Context, request contracts.ChunkRequest) (contracts.ChunkPlanResult, error) {
return contracts.ChunkPlanResult{Plan: typedTestPlan(request.Source), Outcome: contracts.ProducerOutcome{Disposition: contracts.ProducerFallback, FallbackReason: "selected test fallback", ReuseEligible: false}}, nil
}
func TestRunnerChunkFallbackTaintsEveryDerivedOperation(t *testing.T) {
probe := newRunnerProbe()
catalog := typedResolutionCatalog(t, completeTypedCatalogOptions())
if err := catalog.Chunkers.RegisterWithSpec(ModuleSpec{Key: "fallback-chunk", Stage: StageChunk, ExecutionClass: contracts.ExecutionClassLLMBacked}, func() (contracts.Chunker, error) { return runnerFallbackChunker{}, nil }); err != nil {
t.Fatal(err)
}
lane := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "notes", probe: probe})
profile := typedResolutionProfile()
profile.Chunk = Binding("fallback-chunk")
permissive := contracts.ModePermissive
profile.Chunk.Mode = &permissive
profile.Artifacts = map[string]ArtifactLaneProfile{"notes": lane}
output, err := New().Run(context.Background(), RunInput{Prepared: prepareRunnerProfile(t, catalog, profile, nil), RawInput: []byte("input")})
if err != nil {
t.Fatal(err)
}
if output.FallbackCount != 1 || len(output.NormalizeOutputs) != 1 {
t.Fatalf("chunk fallback = %#v", output)
}
for _, role := range []string{"extract", "merge", "normalize"} {
if !reflect.DeepEqual(probe.eligible["notes/"+role], []bool{false}) {
t.Fatalf("chunk fallback did not taint %s: %#v", role, probe.eligible)
}
}
}
func TestRunnerDoesNotRetryOrFallbackDeterministicOperationErrors(t *testing.T) {
probe := newRunnerProbe()
failure := errors.New("deterministic operation failed")
catalog := typedResolutionCatalog(t, completeTypedCatalogOptions())
lane := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "notes", probe: probe, failure: failure})
permissive := contracts.ModePermissive
profile := typedResolutionProfile()
profile.Mode = &permissive
profile.Artifacts = map[string]ArtifactLaneProfile{"notes": lane}
_, err := New().Run(context.Background(), RunInput{Prepared: prepareRunnerProfile(t, catalog, profile, nil), RawInput: []byte("input")})
if !errors.Is(err, failure) || probe.calls["notes/extract"] != 1 || probe.calls["notes/extract/fallback"] != 0 || probe.calls["notes/merge"] != 0 {
t.Fatalf("operation failure = %v, calls %#v", err, probe.calls)
}
}
func TestRunnerDoesNotAcceptModuleFallbackUnderStrictControls(t *testing.T) {
probe := newRunnerProbe()
catalog := typedResolutionCatalog(t, completeTypedCatalogOptions())
if err := catalog.Chunkers.RegisterWithSpec(ModuleSpec{Key: "fallback-chunk", Stage: StageChunk, ExecutionClass: contracts.ExecutionClassLLMBacked}, func() (contracts.Chunker, error) { return runnerFallbackChunker{}, nil }); err != nil {
t.Fatal(err)
}
profile := typedResolutionProfile()
profile.Chunk = Binding("fallback-chunk")
profile.Artifacts = map[string]ArtifactLaneProfile{"notes": registerRunnerNotes(t, catalog, runnerNotesProducer{name: "notes", probe: probe})}
output, err := New().Run(context.Background(), RunInput{Prepared: prepareRunnerProfile(t, catalog, profile, nil), RawInput: []byte("input")})
if err == nil || output.FallbackCount != 0 || len(output.NormalizeOutputs) != 0 || probe.calls["notes/extract"] != 0 {
t.Fatalf("strict controls accepted module fallback: %#v %v", output, err)
}
}
func TestRunnerDiscardsDeterministicOutputReturnedAfterCancellation(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
probe := newRunnerProbe()
catalog := typedResolutionCatalog(t, completeTypedCatalogOptions())
lane := registerRunnerNotes(t, catalog, runnerNotesProducer{name: "notes", probe: probe, cancel: cancel})
profile := typedResolutionProfile()
profile.Artifacts = map[string]ArtifactLaneProfile{"notes": lane}
output, err := New().Run(ctx, RunInput{Prepared: prepareRunnerProfile(t, catalog, profile, nil), RawInput: []byte("input")})
if !errors.Is(err, context.Canceled) || output.FallbackCount != 0 || len(output.NormalizeOutputs) != 0 || probe.calls["notes/merge"] != 0 || probe.calls["notes/extract/fallback"] != 0 {
t.Fatalf("cancellation = %#v %v, calls %#v", output, err, probe.calls)
}
}
var _ contracts.Chunker = runnerFallbackChunker{}
var _ contracts.Extractor[codecNotes] = (*runnerNotesProducer)(nil)
var _ contracts.Merger[codecNotes] = (*runnerNotesProducer)(nil)
var _ contracts.Normalizer[codecNotes] = (*runnerNotesProducer)(nil)

View File

@@ -8,10 +8,8 @@ import (
"errors"
"fmt"
"path"
"reflect"
"time"
"gitea.maximumdirect.net/eric/notarius/internal/core/artifacts"
"gitea.maximumdirect.net/eric/notarius/internal/core/fileio"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
@@ -190,41 +188,29 @@ func (e *laneRunError) Error() string { return e.err.Error() }
func (e *laneRunError) Unwrap() error { return e.err }
type mergeStageResult struct {
artifact erasedMergeArtifact
serialized CheckpointArtifact
terminal bool
validationIncomplete bool
reuseEligible bool
artifact erasedMergeArtifact
serialized CheckpointArtifact
reuseEligible bool
}
type mergeAttemptValue struct {
artifact erasedMergeArtifact
candidate CheckpointArtifact
terminal *attemptTerminalRecorder
}
type normalizeAttemptValue struct {
value any
candidate CheckpointArtifact
terminal *attemptTerminalRecorder
retry map[string]any
type normalizeStageResult struct {
serialized CheckpointArtifact
accepted bool
reuseEligible bool
}
func (r *Runner) continueTypedLane(ctx context.Context, input RunInput, checkpoints CheckpointRecorder, loader CheckpointLoader, doc *source.SourceDocument, sourceInput contracts.LLMInputMaterial, sessionID string, prepared preparedLaneExecutor, extracts finalizedExtractResults, output *RunOutput) error {
lane, typed := prepared.resolved, prepared.typed
if typed == nil {
lane := prepared.resolved
if prepared.typed == nil {
return fmt.Errorf("typed lane %q executor is not prepared", lane.ID)
}
if err := setTypedLaneManifestMetadata(output, lane.ID, typed.extractor, typed.merger, typed.normalizer); err != nil {
if err := setTypedLaneManifestMetadata(output, lane.ID, prepared.typed.extractor, prepared.typed.merger, prepared.typed.normalizer); err != nil {
return err
}
merged, err := r.runMergeStage(ctx, input, checkpoints, loader, doc, sourceInput, sessionID, prepared, extracts, output)
if err != nil {
return &laneRunError{stage: StageMerge, err: err}
}
if merged.terminal {
return nil
}
normalized, err := r.runNormalizeStage(ctx, input, checkpoints, loader, doc, sourceInput, sessionID, prepared, merged.artifact, merged.serialized, merged.reuseEligible, output)
if err != nil {
return &laneRunError{stage: StageNormalize, err: err}
@@ -240,318 +226,176 @@ func (r *Runner) continueTypedLane(ctx context.Context, input RunInput, checkpoi
}
func (r *Runner) runMergeStage(ctx context.Context, input RunInput, checkpoints CheckpointRecorder, loader CheckpointLoader, doc *source.SourceDocument, sourceInput contracts.LLMInputMaterial, sessionID string, prepared preparedLaneExecutor, extracts finalizedExtractResults, output *RunOutput) (mergeStageResult, error) {
var stageResult mergeStageResult
state := mergeStageResult{}
lane, typed := prepared.resolved, prepared.typed
mergeInputs := make([]contracts.ExtractArtifact[any], len(extracts.accepted))
for i, value := range extracts.accepted {
mergeInputs[i] = contracts.ExtractArtifact[any]{LaneID: value.LaneID, ExtractorKey: value.ExtractorKey, SourceID: value.SourceID, ChunkID: value.ChunkID, ChunkIndex: value.ChunkIndex, ChunkRef: value.ChunkRef, Value: value.Value}
references := operationReferenceSet(input, lane.MergeReferences)
state.reuseEligible = extracts.reuseEligible && !input.reuseIneligible && referenceTargetReuseEligible(input, lane.MergeReferences)
deps := normalizeCheckpointFingerprints(append(artifactCheckpointDigests(extracts.serialized), generatedReferenceDependencies(references)...))
var checkpoint MergeCheckpoint
decision := checkpointDecision(CheckpointDecisionExecuted, CheckpointReasonValidationIncompleteLineage)
if state.reuseEligible {
checkpoint, decision = loadMerge(loader, input.stepID, lane.ID, lane.Merge.Module, deps)
}
mergeReferences := operationReferenceSet(input, lane.MergeReferences)
stageResult.reuseEligible = extracts.reuseEligible && referenceTargetReuseEligible(input, lane.MergeReferences)
mergeDeps := append(artifactCheckpointDigests(extracts.serialized), generatedReferenceDependencies(mergeReferences)...)
mergeDeps = normalizeCheckpointFingerprints(mergeDeps)
var mergeCP MergeCheckpoint
mergeDecision := checkpointDecision(CheckpointDecisionExecuted, CheckpointReasonValidationIncompleteLineage)
if stageResult.reuseEligible {
mergeCP, mergeDecision = loadMerge(loader, input.stepID, lane.ID, lane.Merge.Module, mergeDeps)
}
mergeResolution, err := resolveCheckpointDecision(output, loader, input.CheckpointPolicy, StageMerge, input.stepID, lane.ID, lane.Merge.Module, mergeDecision, typed.codec, []CheckpointArtifact{mergeCP.Output})
resolution, err := resolveCheckpointDecision(output, loader, input.CheckpointPolicy, StageMerge, input.stepID, lane.ID, lane.Merge.Module, decision, typed.codec, []CheckpointArtifact{checkpoint.Output})
if err != nil {
return stageResult, err
return state, err
}
mergeDecision = mergeResolution.decision
if err := writeDebugTimed(input.Debug, path.Join("merge", fileio.EncodePathComponent(lane.ID), "input.json"), debugTimedEnvelope{Stage: string(StageMerge), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Merge.Module, StartedAt: time.Now().UTC(), Payload: map[string]any{"reused": mergeDecision.Reused, "decision": mergeDecision, "source": debugSourceDocumentEnvelope(doc), "extract_outputs": debugCheckpointArtifacts(extracts.serialized), "options": redactSensitiveMap(lane.Merge.Options), "metadata": redactSensitiveMap(input.Metadata)}}); err != nil {
return stageResult, err
}
var merged erasedMergeArtifact
var serializedMerge CheckpointArtifact
if mergeDecision.Reused {
merged = erasedMergeArtifact{LaneID: lane.ID, MergerKey: lane.Merge.Module, SourceID: doc.ID, Value: mergeResolution.values[0]}
serializedMerge = mergeResolution.artifacts[0]
diagnostics, diagnosticErr := promoteCheckpointDiagnostics(serializedMerge.Diagnostics, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageMerge, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Merge.Module}, nil)
if diagnosticErr != nil {
return stageResult, fmt.Errorf("promote reused merge diagnostics: %w", diagnosticErr)
if resolution.decision.Reused {
state.serialized = resolution.artifacts[0]
state.artifact = erasedMergeArtifact{LaneID: lane.ID, MergerKey: lane.Merge.Module, SourceID: doc.ID, Value: resolution.values[0]}
diagnostics, err := promoteCheckpointDiagnostics(state.serialized.Diagnostics, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageMerge, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Merge.Module}, nil)
if err != nil {
return state, err
}
appendDiagnosticGroups(output, diagnostics)
} else {
if stageResult.reuseEligible {
if err := checkpointMergeRunning(checkpoints, input.stepID, lane.ID, lane.Merge.Module, mergeDeps); err != nil {
return stageResult, err
}
}
terminalResult, runErr := runProducerAttempts(ctx, producerAttemptConfig{Retries: lane.Merge.Retries, Policy: lane.MergeValidationPolicy, AllowStructuralRetry: lane.MergeExecutionClass == contracts.ExecutionClassLLMBacked}, func(attemptCtx context.Context, request producerAttemptRequest) (producerAttemptOutput, error) {
started := time.Now().UTC()
attemptPath := path.Join("merge", fileio.EncodePathComponent(lane.ID), fmt.Sprintf("attempt-%02d", request.Number))
attemptCtx, llmScope := withDebugLLMScope(attemptCtx, attemptPath)
terminal := newAttemptTerminalRecorder(input.Debug, attemptPath, "merge", llmScope, debugTimedEnvelope{Stage: string(StageMerge), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Merge.Module, Attempt: request.Number, AttemptKind: string(request.Kind), StartedAt: started})
requestMetadata, metadataErr := cloneMetadata(input.Metadata)
if metadataErr != nil {
return producerAttemptOutput{}, terminal.record(nil, fmt.Errorf("clone merge request metadata: %w", metadataErr))
}
result, callErr := typed.merge(attemptCtx, typed.merger, contracts.TypedMergeRequest[any]{Source: doc, LaneID: lane.ID, ExtractOutputs: mergeInputs, SourceInput: sourceInput.Clone(), SessionID: sessionID, References: CloneReferenceSet(mergeReferences), LLMProfile: lane.Merge.LLMProfile, StructuredOutputRepairAttempts: cloneStructuredOutputRepairAttempts(lane.Merge.StructuredOutputRepairAttempts), Correction: request.Correction, Metadata: requestMetadata})
if callErr != nil {
return producerAttemptOutput{}, terminal.record(nil, fmt.Errorf("merge lane %q with merger %q: %w", lane.ID, lane.Merge.Module, callErr))
}
candidate := erasedMergeArtifact{LaneID: lane.ID, MergerKey: lane.Merge.Module, SourceID: doc.ID, Value: result.Value}
serializedCandidate, encodeErr := serializeCandidateArtifact(typed.codec, candidate.LaneID, candidate.MergerKey, candidate.SourceID, candidate.Value)
if encodeErr != nil {
return producerAttemptOutput{}, terminal.record(nil, fmt.Errorf("serialize merge candidate for lane %q: %w", lane.ID, encodeErr))
}
return producerAttemptOutput{Value: mergeAttemptValue{artifact: candidate, candidate: serializedCandidate, terminal: &terminal}, Candidate: result.ModelCandidate, Diagnostics: contracts.CloneProducerDiagnostics(result.Diagnostics)}, nil
}, func(validationCtx context.Context, output producerAttemptOutput) (validationReport, error) {
candidate, ok := output.Value.(mergeAttemptValue)
if !ok {
return validationReport{}, fmt.Errorf("merge attempt has incompatible value")
}
target := typedValidationTarget{stage: StageMerge, stepID: input.stepID, laneID: lane.ID, moduleKey: lane.Merge.Module, source: doc, sourceID: doc.ID, sourceInput: sourceInput.Clone(), sessionID: sessionID, references: mergeReferences, metadata: input.Metadata, value: candidate.artifact.Value, candidate: &candidate.candidate}
report, validationErr := r.validateTypedReport(validationCtx, typed.codec, target, prepared.mergeValidators, candidate.terminal.envelope.Attempt, input.Debug)
payload := map[string]any{"output": debugCheckpointArtifact(candidate.candidate), "rejection": debugRejectedOutputPtr(typedRejection(report, target, candidate.terminal.envelope.Attempt))}
if validationErr != nil {
return report, candidate.terminal.record(payload, validationErr)
}
return report, candidate.terminal.record(payload, nil)
})
terminalSummary := validationSummary(terminalResult, StageMerge, input.stepID, lane.ID, lane.Merge.Module, "", 0)
if debugErr := writeProducerTerminalDebug(input.Debug, path.Join("merge", fileio.EncodePathComponent(lane.ID), "terminal.json"), terminalResult, lane.MergeValidationPolicy, terminalSummary); debugErr != nil {
if stageResult.reuseEligible {
_ = checkpointMergeFailed(checkpoints, input.stepID, lane.ID, lane.Merge.Module, mergeDeps, debugErr)
}
return stageResult, debugErr
}
if runErr != nil {
if stageResult.reuseEligible {
_ = checkpointMergeFailed(checkpoints, input.stepID, lane.ID, lane.Merge.Module, mergeDeps, runErr)
}
return stageResult, runErr
}
terminalDiagnostics, diagnosticErr := terminalDiagnosticGroups(terminalResult, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageMerge, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Merge.Module}, nil)
if diagnosticErr != nil {
return stageResult, fmt.Errorf("promote merge diagnostics: %w", diagnosticErr)
}
if terminalResult.Action == producerTerminalRejected {
rejected := terminalResult.Rejection
if rejected == nil {
return stageResult, fmt.Errorf("merge attempt terminal is missing rejection")
}
rejected.Stage, rejected.StepID, rejected.LaneID, rejected.ModuleKey = string(StageMerge), input.stepID, lane.ID, lane.Merge.Module
rejected.Validation = &terminalSummary
output.ValidationSummaries = append(output.ValidationSummaries, artifacts.CloneValidationSummary(terminalSummary))
appendDiagnosticGroups(output, terminalDiagnostics)
output.Rejected = append(output.Rejected, *rejected)
if stageResult.reuseEligible {
if err := checkpointMergeRejected(checkpoints, input.stepID, lane.ID, lane.Merge.Module, mergeDeps, *rejected); err != nil {
return stageResult, err
}
}
stageResult.terminal = true
return stageResult, nil
}
candidate, ok := terminalResult.Value.(mergeAttemptValue)
if !ok {
return stageResult, fmt.Errorf("merge attempt terminal has incompatible value")
}
stored, encodeErr := checkpointArtifact(typed.codec, candidate.artifact.LaneID, candidate.artifact.MergerKey, candidate.artifact.SourceID, candidate.artifact.Value)
payload := map[string]any{"output": debugCheckpointArtifact(candidate.candidate), "rejection": debugRejectedOutputPtr(nil)}
if encodeErr != nil {
attemptErr := fmt.Errorf("serialize accepted merge output for lane %q: %w", lane.ID, encodeErr)
if stageResult.reuseEligible {
_ = checkpointMergeFailed(checkpoints, input.stepID, lane.ID, lane.Merge.Module, mergeDeps, attemptErr)
}
return stageResult, candidate.terminal.record(payload, attemptErr)
}
stored.Diagnostics = terminalCheckpointDiagnostics(terminalResult)
if debugErr := candidate.terminal.record(payload, nil); debugErr != nil {
if stageResult.reuseEligible {
_ = checkpointMergeFailed(checkpoints, input.stepID, lane.ID, lane.Merge.Module, mergeDeps, debugErr)
}
return stageResult, debugErr
}
merged, serializedMerge = candidate.artifact, stored
output.ValidationSummaries = append(output.ValidationSummaries, terminalSummary)
stageResult.validationIncomplete = terminalResult.ValidationIncomplete
if stageResult.validationIncomplete {
stageResult.reuseEligible = false
}
appendDiagnosticGroups(output, terminalDiagnostics)
if stageResult.reuseEligible {
if err := recordMerge(checkpoints, input.stepID, lane.ID, lane.Merge.Module, mergeDeps, serializedMerge); err != nil {
return stageResult, err
}
return state, nil
}
if err := ctx.Err(); err != nil {
return state, err
}
if state.reuseEligible {
if err := checkpointMergeRunning(checkpoints, input.stepID, lane.ID, lane.Merge.Module, deps); err != nil {
return state, err
}
}
if err := writeDebugTimed(input.Debug, path.Join("merge", fileio.EncodePathComponent(lane.ID), "output.json"), debugTimedEnvelope{Stage: string(StageMerge), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Merge.Module, StartedAt: time.Now().UTC(), Payload: map[string]any{"reused": mergeDecision.Reused, "accepted": true, "output": debugCheckpointArtifact(serializedMerge)}}); err != nil {
return stageResult, err
}
stageResult.artifact = merged
stageResult.serialized = serializedMerge
return stageResult, nil
}
type normalizeStageResult struct {
serialized CheckpointArtifact
accepted bool
reuseEligible bool
inputs := make([]contracts.ExtractArtifact[any], len(extracts.accepted))
for i, value := range extracts.accepted {
inputs[i] = contracts.ExtractArtifact[any]{LaneID: value.LaneID, ExtractorKey: value.ExtractorKey, SourceID: value.SourceID, ChunkID: value.ChunkID, ChunkIndex: value.ChunkIndex, ChunkRef: value.ChunkRef, Value: value.Value}
}
metadata, err := cloneMetadata(input.Metadata)
if err != nil {
return state, err
}
target := typedValidationTarget{stage: StageMerge, stepID: input.stepID, laneID: lane.ID, moduleKey: lane.Merge.Module, source: doc, sourceID: doc.ID, sourceInput: sourceInput.Clone(), sessionID: sessionID, references: references, metadata: input.Metadata, execution: input.Execution}
var assessment contracts.CandidateAssessment
assess := typedCandidateAssessor[any](typed.codec, target, prepared.mergeValidators)
operation := contracts.ProducerOperation[any]{Controls: lane.MergeControls, Execution: input.Execution, ReuseEligible: state.reuseEligible,
Assess: func(ctx context.Context, value any) (contracts.CandidateAssessment, error) {
var err error
assessment, err = assess(ctx, value)
return assessment, err
},
}
produced, err := typed.merge(ctx, typed.merger, contracts.TypedMergeRequest[any]{Operation: operation, Source: doc, LaneID: lane.ID, ExtractOutputs: inputs, SourceInput: sourceInput.Clone(), SessionID: sessionID, References: CloneReferenceSet(references), LLMProfile: lane.Merge.LLMProfile, Metadata: metadata})
if err != nil {
if state.reuseEligible {
_ = checkpointMergeFailed(checkpoints, input.stepID, lane.ID, lane.Merge.Module, deps, err)
}
return state, fmt.Errorf("merge lane %q: %w", lane.ID, err)
}
value, outcome, err := completeProducerOperation(ctx, lane.MergeExecutionClass, operation, produced.Value, produced.Outcome, produced.Fallback)
if err != nil {
return state, fmt.Errorf("accept merge lane %q: %w", lane.ID, err)
}
state.serialized, err = checkpointArtifact(typed.codec, lane.ID, lane.Merge.Module, doc.ID, value)
if err != nil {
return state, fmt.Errorf("encode merge lane %q: %w", lane.ID, err)
}
diagnostics, err := operationDiagnosticGroups(produced.Diagnostics, assessment, outcome, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageMerge, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Merge.Module}, nil)
if err != nil {
return state, err
}
appendDiagnosticGroups(output, diagnostics)
if outcome.Disposition == contracts.ProducerFallback {
output.FallbackCount++
}
state.reuseEligible = outcome.ReuseEligible
state.artifact = erasedMergeArtifact{LaneID: lane.ID, MergerKey: lane.Merge.Module, SourceID: doc.ID, Value: value}
if state.reuseEligible {
if err := recordMerge(checkpoints, input.stepID, lane.ID, lane.Merge.Module, deps, state.serialized); err != nil {
return state, err
}
}
if err := writeDebugTimed(input.Debug, path.Join("merge", fileio.EncodePathComponent(lane.ID), "output.json"), debugTimedEnvelope{Stage: string(StageMerge), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Merge.Module, StartedAt: time.Now().UTC(), Payload: map[string]any{"outcome": outcome, "output": debugCheckpointArtifact(state.serialized)}}); err != nil {
return state, err
}
return state, nil
}
func (r *Runner) runNormalizeStage(ctx context.Context, input RunInput, checkpoints CheckpointRecorder, loader CheckpointLoader, doc *source.SourceDocument, sourceInput contracts.LLMInputMaterial, sessionID string, prepared preparedLaneExecutor, merged erasedMergeArtifact, serializedMerge CheckpointArtifact, upstreamReuseEligible bool, output *RunOutput) (normalizeStageResult, error) {
var stageResult normalizeStageResult
state := normalizeStageResult{}
lane, typed := prepared.resolved, prepared.typed
normalizeReferences := operationReferenceSet(input, lane.NormalizeReferences)
stageResult.reuseEligible = upstreamReuseEligible && referenceTargetReuseEligible(input, lane.NormalizeReferences)
normalizeDeps := append(artifactCheckpointDigests([]CheckpointArtifact{serializedMerge}), generatedReferenceDependencies(normalizeReferences)...)
normalizeDeps = normalizeCheckpointFingerprints(normalizeDeps)
var normalizeCP NormalizeCheckpoint
normalizeDecision := checkpointDecision(CheckpointDecisionExecuted, CheckpointReasonValidationIncompleteLineage)
if stageResult.reuseEligible {
normalizeCP, normalizeDecision = loadNormalize(loader, input.stepID, lane.ID, lane.Normalize.Module, normalizeDeps)
references := operationReferenceSet(input, lane.NormalizeReferences)
state.reuseEligible = upstreamReuseEligible && !input.reuseIneligible && referenceTargetReuseEligible(input, lane.NormalizeReferences)
deps := normalizeCheckpointFingerprints(append(artifactCheckpointDigests([]CheckpointArtifact{serializedMerge}), generatedReferenceDependencies(references)...))
var checkpoint NormalizeCheckpoint
decision := checkpointDecision(CheckpointDecisionExecuted, CheckpointReasonValidationIncompleteLineage)
if state.reuseEligible {
checkpoint, decision = loadNormalize(loader, input.stepID, lane.ID, lane.Normalize.Module, deps)
}
normalizeResolution, err := resolveCheckpointDecision(output, loader, input.CheckpointPolicy, StageNormalize, input.stepID, lane.ID, lane.Normalize.Module, normalizeDecision, typed.codec, []CheckpointArtifact{normalizeCP.Output})
resolution, err := resolveCheckpointDecision(output, loader, input.CheckpointPolicy, StageNormalize, input.stepID, lane.ID, lane.Normalize.Module, decision, typed.codec, []CheckpointArtifact{checkpoint.Output})
if err != nil {
return stageResult, err
return state, err
}
normalizeDecision = normalizeResolution.decision
if err := writeDebugTimed(input.Debug, path.Join("normalize", fileio.EncodePathComponent(lane.ID), "input.json"), debugTimedEnvelope{Stage: string(StageNormalize), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Normalize.Module, StartedAt: time.Now().UTC(), Payload: map[string]any{"reused": normalizeDecision.Reused, "decision": normalizeDecision, "source": debugSourceDocumentEnvelope(doc), "merge_output": debugCheckpointArtifact(serializedMerge), "options": redactSensitiveMap(lane.Normalize.Options), "metadata": redactSensitiveMap(input.Metadata)}}); err != nil {
return stageResult, err
}
var serializedNormalize CheckpointArtifact
if normalizeDecision.Reused {
serializedNormalize = normalizeResolution.artifacts[0]
diagnostics, diagnosticErr := promoteCheckpointDiagnostics(serializedNormalize.Diagnostics, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageNormalize, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Normalize.Module}, nil)
if diagnosticErr != nil {
return stageResult, fmt.Errorf("promote reused normalize diagnostics: %w", diagnosticErr)
if resolution.decision.Reused {
state.serialized = resolution.artifacts[0]
state.accepted = true
diagnostics, err := promoteCheckpointDiagnostics(state.serialized.Diagnostics, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageNormalize, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Normalize.Module}, nil)
if err != nil {
return state, err
}
appendDiagnosticGroups(output, diagnostics)
} else {
if stageResult.reuseEligible {
if err := checkpointNormalizeRunning(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, normalizeDeps); err != nil {
return stageResult, err
}
}
terminalResult, runErr := runProducerAttempts(ctx, producerAttemptConfig{Retries: lane.Normalize.Retries, Policy: lane.NormalizeValidationPolicy, AllowStructuralRetry: lane.NormalizeExecutionClass == contracts.ExecutionClassLLMBacked}, func(attemptCtx context.Context, request producerAttemptRequest) (producerAttemptOutput, error) {
started := time.Now().UTC()
attemptPath := path.Join("normalize", fileio.EncodePathComponent(lane.ID), fmt.Sprintf("attempt-%02d", request.Number))
attemptCtx, llmScope := withDebugLLMScope(attemptCtx, attemptPath)
terminal := newAttemptTerminalRecorder(input.Debug, attemptPath, "normalize", llmScope, debugTimedEnvelope{Stage: string(StageNormalize), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Normalize.Module, Attempt: request.Number, AttemptKind: string(request.Kind), StartedAt: started})
requestMetadata, metadataErr := cloneMetadata(input.Metadata)
if metadataErr != nil {
return producerAttemptOutput{}, terminal.record(nil, fmt.Errorf("clone normalize request metadata: %w", metadataErr))
}
result, callErr := typed.normalize(attemptCtx, typed.normalizer, contracts.TypedNormalizeRequest[any]{Source: doc, LaneID: lane.ID, MergeOutput: contracts.MergeArtifact[any]{LaneID: lane.ID, MergerKey: lane.Merge.Module, SourceID: doc.ID, Value: merged.Value}, SourceInput: sourceInput.Clone(), SessionID: sessionID, References: CloneReferenceSet(normalizeReferences), LLMProfile: lane.Normalize.LLMProfile, StructuredOutputRepairAttempts: cloneStructuredOutputRepairAttempts(lane.Normalize.StructuredOutputRepairAttempts), Correction: request.Correction, Metadata: requestMetadata})
if callErr != nil {
return producerAttemptOutput{}, terminal.record(nil, fmt.Errorf("normalize lane %q with normalizer %q: %w", lane.ID, lane.Normalize.Module, callErr))
}
serializedCandidate, encodeErr := serializeCandidateArtifact(typed.codec, lane.ID, lane.Normalize.Module, doc.ID, result.Value)
if encodeErr != nil {
return producerAttemptOutput{}, terminal.record(nil, fmt.Errorf("serialize normalize candidate for lane %q: %w", lane.ID, encodeErr))
}
attemptValue := normalizeAttemptValue{value: result.Value, candidate: serializedCandidate, terminal: &terminal}
var directive *producerRetryDirective
if result.Retry != nil {
if err := validateNormalizeRetry(result.Retry); err != nil {
return producerAttemptOutput{}, terminal.record(map[string]any{"output": debugCheckpointArtifact(serializedCandidate)}, fmt.Errorf("normalize lane %q returned invalid retry directive: %w", lane.ID, err))
}
anotherAttempt := request.Number <= lane.Normalize.Retries
attemptValue.retry = map[string]any{"reason_code": result.Retry.ReasonCode, "message": result.Retry.Message, "correction_available": result.Retry.CorrectionGuidance != "", "another_attempt": anotherAttempt, "fallback_accepted": !anotherAttempt}
directive = &producerRetryDirective{CorrectionGuidance: result.Retry.CorrectionGuidance, FallbackDiagnostics: contracts.CloneProducerDiagnostics(result.Retry.FallbackDiagnostics)}
if anotherAttempt {
payload := map[string]any{"output": debugCheckpointArtifact(serializedCandidate), "retry": attemptValue.retry}
if debugErr := terminal.record(payload, nil); debugErr != nil {
return producerAttemptOutput{}, debugErr
}
}
}
return producerAttemptOutput{Value: attemptValue, Candidate: result.ModelCandidate, Diagnostics: contracts.CloneProducerDiagnostics(result.Diagnostics), Retry: directive}, nil
}, func(validationCtx context.Context, output producerAttemptOutput) (validationReport, error) {
candidate, ok := output.Value.(normalizeAttemptValue)
if !ok {
return validationReport{}, fmt.Errorf("normalize attempt has incompatible value")
}
target := typedValidationTarget{stage: StageNormalize, stepID: input.stepID, laneID: lane.ID, moduleKey: lane.Normalize.Module, source: doc, sourceID: doc.ID, sourceInput: sourceInput.Clone(), sessionID: sessionID, references: normalizeReferences, metadata: input.Metadata, value: candidate.value, candidate: &candidate.candidate}
report, validationErr := r.validateTypedReport(validationCtx, typed.codec, target, prepared.normalizeValidators, candidate.terminal.envelope.Attempt, input.Debug)
payload := map[string]any{"output": debugCheckpointArtifact(candidate.candidate), "rejection": debugRejectedOutputPtr(typedRejection(report, target, candidate.terminal.envelope.Attempt))}
if candidate.retry != nil {
payload["retry"] = candidate.retry
}
if validationErr != nil {
return report, candidate.terminal.record(payload, validationErr)
}
return report, candidate.terminal.record(payload, nil)
})
terminalSummary := validationSummary(terminalResult, StageNormalize, input.stepID, lane.ID, lane.Normalize.Module, "", 0)
if debugErr := writeProducerTerminalDebug(input.Debug, path.Join("normalize", fileio.EncodePathComponent(lane.ID), "terminal.json"), terminalResult, lane.NormalizeValidationPolicy, terminalSummary); debugErr != nil {
if stageResult.reuseEligible {
_ = checkpointNormalizeFailed(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, normalizeDeps, debugErr)
}
return stageResult, debugErr
}
if runErr != nil {
if stageResult.reuseEligible {
_ = checkpointNormalizeFailed(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, normalizeDeps, runErr)
}
return stageResult, runErr
}
terminalDiagnostics, diagnosticErr := terminalDiagnosticGroups(terminalResult, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageNormalize, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Normalize.Module}, nil)
if diagnosticErr != nil {
return stageResult, fmt.Errorf("promote normalize diagnostics: %w", diagnosticErr)
}
if terminalResult.Action == producerTerminalRejected {
rejected := terminalResult.Rejection
if rejected == nil {
return stageResult, fmt.Errorf("normalize attempt terminal is missing rejection")
}
rejected.Stage, rejected.StepID, rejected.LaneID, rejected.ModuleKey = string(StageNormalize), input.stepID, lane.ID, lane.Normalize.Module
rejected.Validation = &terminalSummary
output.ValidationSummaries = append(output.ValidationSummaries, artifacts.CloneValidationSummary(terminalSummary))
appendDiagnosticGroups(output, terminalDiagnostics)
output.Rejected = append(output.Rejected, *rejected)
if stageResult.reuseEligible {
if err := checkpointNormalizeRejected(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, normalizeDeps, *rejected); err != nil {
return stageResult, err
}
}
return stageResult, nil
}
candidate, ok := terminalResult.Value.(normalizeAttemptValue)
if !ok {
return stageResult, fmt.Errorf("normalize attempt terminal has incompatible value")
}
stored, encodeErr := checkpointArtifact(typed.codec, lane.ID, lane.Normalize.Module, doc.ID, candidate.value)
payload := map[string]any{"output": debugCheckpointArtifact(candidate.candidate), "rejection": debugRejectedOutputPtr(nil)}
if candidate.retry != nil {
payload["retry"] = candidate.retry
}
if encodeErr != nil {
attemptErr := fmt.Errorf("serialize accepted normalize output for lane %q: %w", lane.ID, encodeErr)
if stageResult.reuseEligible {
_ = checkpointNormalizeFailed(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, normalizeDeps, attemptErr)
}
return stageResult, candidate.terminal.record(payload, attemptErr)
}
stored.Diagnostics = terminalCheckpointDiagnostics(terminalResult)
if debugErr := candidate.terminal.record(payload, nil); debugErr != nil {
if stageResult.reuseEligible {
_ = checkpointNormalizeFailed(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, normalizeDeps, debugErr)
}
return stageResult, debugErr
}
serializedNormalize = stored
output.ValidationSummaries = append(output.ValidationSummaries, terminalSummary)
appendDiagnosticGroups(output, terminalDiagnostics)
if terminalResult.ValidationIncomplete {
stageResult.reuseEligible = false
}
if stageResult.reuseEligible {
if err := recordNormalize(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, normalizeDeps, serializedNormalize); err != nil {
return stageResult, err
}
return state, nil
}
if err := ctx.Err(); err != nil {
return state, err
}
if state.reuseEligible {
if err := checkpointNormalizeRunning(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, deps); err != nil {
return state, err
}
}
if err := writeDebugTimed(input.Debug, path.Join("normalize", fileio.EncodePathComponent(lane.ID), "output.json"), debugTimedEnvelope{Stage: string(StageNormalize), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Normalize.Module, StartedAt: time.Now().UTC(), Payload: map[string]any{"reused": normalizeDecision.Reused, "accepted": true, "output": debugCheckpointArtifact(serializedNormalize)}}); err != nil {
return stageResult, err
metadata, err := cloneMetadata(input.Metadata)
if err != nil {
return state, err
}
stageResult.serialized = serializedNormalize
stageResult.accepted = true
return stageResult, nil
target := typedValidationTarget{stage: StageNormalize, stepID: input.stepID, laneID: lane.ID, moduleKey: lane.Normalize.Module, source: doc, sourceID: doc.ID, sourceInput: sourceInput.Clone(), sessionID: sessionID, references: references, metadata: input.Metadata, execution: input.Execution}
var assessment contracts.CandidateAssessment
assess := typedCandidateAssessor[any](typed.codec, target, prepared.normalizeValidators)
operation := contracts.ProducerOperation[any]{Controls: lane.NormalizeControls, Execution: input.Execution, ReuseEligible: state.reuseEligible,
Assess: func(ctx context.Context, value any) (contracts.CandidateAssessment, error) {
var err error
assessment, err = assess(ctx, value)
return assessment, err
},
}
produced, err := typed.normalize(ctx, typed.normalizer, contracts.TypedNormalizeRequest[any]{Operation: operation, Source: doc, LaneID: lane.ID, MergeOutput: contracts.MergeArtifact[any]{LaneID: merged.LaneID, MergerKey: merged.MergerKey, SourceID: merged.SourceID, Value: merged.Value}, SourceInput: sourceInput.Clone(), SessionID: sessionID, References: CloneReferenceSet(references), LLMProfile: lane.Normalize.LLMProfile, Metadata: metadata})
if err != nil {
if state.reuseEligible {
_ = checkpointNormalizeFailed(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, deps, err)
}
return state, fmt.Errorf("normalize lane %q: %w", lane.ID, err)
}
value, outcome, err := completeProducerOperation(ctx, lane.NormalizeExecutionClass, operation, produced.Value, produced.Outcome, produced.Fallback)
if err != nil {
return state, fmt.Errorf("accept normalize lane %q: %w", lane.ID, err)
}
state.serialized, err = checkpointArtifact(typed.codec, lane.ID, lane.Normalize.Module, doc.ID, value)
if err != nil {
return state, fmt.Errorf("encode normalize lane %q: %w", lane.ID, err)
}
diagnostics, err := operationDiagnosticGroups(produced.Diagnostics, assessment, outcome, contracts.DiagnosticOrigin{Stage: contracts.DiagnosticOriginStageNormalize, StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Normalize.Module}, nil)
if err != nil {
return state, err
}
appendDiagnosticGroups(output, diagnostics)
if outcome.Disposition == contracts.ProducerFallback {
output.FallbackCount++
}
state.reuseEligible = outcome.ReuseEligible
state.accepted = true
if state.reuseEligible {
if err := recordNormalize(checkpoints, input.stepID, lane.ID, lane.Normalize.Module, deps, state.serialized); err != nil {
return state, err
}
}
if err := writeDebugTimed(input.Debug, path.Join("normalize", fileio.EncodePathComponent(lane.ID), "output.json"), debugTimedEnvelope{Stage: string(StageNormalize), StepID: input.stepID, LaneID: lane.ID, ModuleKey: lane.Normalize.Module, StartedAt: time.Now().UTC(), Payload: map[string]any{"outcome": outcome, "output": debugCheckpointArtifact(state.serialized)}}); err != nil {
return state, err
}
return state, nil
}
func setTypedLaneManifestMetadata(output *RunOutput, laneID string, extractor, merger, normalizer any) error {
@@ -582,34 +426,3 @@ func setTypedLaneManifestMetadata(output *RunOutput, laneID string, extractor, m
}
return nil
}
func typedRejection(report validationReport, target typedValidationTarget, attempt int) *contracts.RejectedOutput {
rejection := report.FirstRejection()
if rejection == nil {
return nil
}
chunkID, chunkIndex := "", 0
if target.chunk != nil {
chunkID, chunkIndex = target.chunk.ID, target.chunk.Index
}
return &contracts.RejectedOutput{Stage: string(target.stage), StepID: target.stepID, LaneID: target.laneID, ModuleKey: target.moduleKey, ChunkID: chunkID, ChunkIndex: chunkIndex, ValidatorName: rejection.validatorName, ReasonCode: rejection.reasonCode, Message: rejection.message, AttemptCount: attempt, DiagnosticArtifactPath: rejection.diagnosticPath}
}
func validationCandidateArtifact(codec artifactCodecEntry, target typedValidationTarget) (CheckpointArtifact, error) {
if target.candidate != nil {
return cloneCheckpointArtifact(*target.candidate), nil
}
return serializeCandidateArtifact(codec, target.laneID, target.moduleKey, target.sourceID, target.value)
}
func decodeTypedValidationCandidate(codec artifactCodecEntry, candidate CheckpointArtifact) (any, error) {
value, err := codec.decodeCandidate(candidate.Artifact.Content)
if err != nil {
return nil, err
}
actualType := reflect.TypeOf(value)
if actualType != codec.valueType {
return nil, newArtifactCodecTypeError("decode candidate", codec.spec.Kind, codec.valueType, actualType)
}
return value, nil
}

View File

@@ -22,6 +22,7 @@ type erasedMergeArtifact struct {
}
type erasedTypedResult struct {
Fallback func(context.Context) (any, error)
Value any
Diagnostics []contracts.ProducerDiagnostic
Outcome contracts.ProducerOutcome
@@ -44,7 +45,13 @@ type typedValidationTarget struct {
chunks []source.Chunk
ref source.SourceRef
value any
candidate *CheckpointArtifact
}
func eraseProducerFallback[T any](fallback func(context.Context) (T, error)) func(context.Context) (any, error) {
if fallback == nil {
return nil
}
return func(ctx context.Context) (any, error) { return fallback(ctx) }
}
func exactTypedValue[T any](operation string, value any) (T, error) {