Add stable checkpoint decision diagnostics

2026-07-22 02:13:50 +00:00
parent 5bdd56cfb1
commit 9de399432e
10 changed files with 391 additions and 155 deletions
--- a/internal/framework/pipeline/checkpoint.go
+++ b/internal/framework/pipeline/checkpoint.go
@@ -57,26 +57,96 @@ type StepCheckpointRecorder interface {
 	NormalizeFailedForStep(stepID, laneID string, moduleKey string, dependencies []CheckpointFingerprint, err error) error
 }

+type CheckpointDecisionCategory string
+
+const (
+	CheckpointDecisionExecuted              CheckpointDecisionCategory = "executed"
+	CheckpointDecisionReused                CheckpointDecisionCategory = "reused"
+	CheckpointDecisionForcedRecompute       CheckpointDecisionCategory = "forced_recompute"
+	CheckpointDecisionDependencyInvalidated CheckpointDecisionCategory = "dependency_invalidated"
+)
+
+type CheckpointReasonCode string
+
+const (
+	CheckpointReasonLoadingDisabled             CheckpointReasonCode = "loading_disabled"
+	CheckpointReasonMissing                     CheckpointReasonCode = "checkpoint_missing"
+	CheckpointReasonPathInvalid                 CheckpointReasonCode = "checkpoint_path_invalid"
+	CheckpointReasonReadFailed                  CheckpointReasonCode = "checkpoint_read_failed"
+	CheckpointReasonDecodeFailed                CheckpointReasonCode = "checkpoint_decode_failed"
+	CheckpointReasonWorkspaceSchemaIncompatible CheckpointReasonCode = "workspace_schema_incompatible"
+	CheckpointReasonIdentityMismatch            CheckpointReasonCode = "identity_mismatch"
+	CheckpointReasonStageMismatch               CheckpointReasonCode = "stage_mismatch"
+	CheckpointReasonStepMismatch                CheckpointReasonCode = "step_mismatch"
+	CheckpointReasonLaneMismatch                CheckpointReasonCode = "lane_mismatch"
+	CheckpointReasonModuleMismatch              CheckpointReasonCode = "module_mismatch"
+	CheckpointReasonStatusNotReusable           CheckpointReasonCode = "status_not_reusable"
+	CheckpointReasonDependencyMismatch          CheckpointReasonCode = "dependency_mismatch"
+	CheckpointReasonArtifactPayloadInvalid      CheckpointReasonCode = "artifact_payload_invalid"
+	CheckpointReasonArtifactDigestMismatch      CheckpointReasonCode = "artifact_digest_mismatch"
+	CheckpointReasonArtifactCodecIncompatible   CheckpointReasonCode = "artifact_codec_incompatible"
+	CheckpointReasonArtifactNotCanonical        CheckpointReasonCode = "artifact_not_canonical"
+	CheckpointReasonReused                      CheckpointReasonCode = "checkpoint_reused"
+	CheckpointReasonAcceptedArtifactReused      CheckpointReasonCode = "accepted_artifact_reused"
+	CheckpointReasonRecomputeStep               CheckpointReasonCode = "recompute_step"
+)
+
 type CheckpointDecision struct {
-	Reused     bool   `json:"reused"`
-	Category   string `json:"category,omitempty"`
-	ReasonCode string `json:"reason_code,omitempty"`
-	Detail     string `json:"detail,omitempty"`
+	Reused     bool                       `json:"reused"`
+	Category   CheckpointDecisionCategory `json:"category,omitempty"`
+	ReasonCode CheckpointReasonCode       `json:"reason_code,omitempty"`
+	Detail     string                     `json:"detail,omitempty"`
 	// Reason is retained as a compatibility/debug field for existing callers.
 	// New checkpoint stores should put bounded, non-sensitive text in Detail.
 	Reason string `json:"reason,omitempty"`
 }

+const checkpointDecisionDetailLimit = 512
+
+func NewCheckpointDecision(category CheckpointDecisionCategory, reasonCode CheckpointReasonCode, detail string) CheckpointDecision {
+	return checkpointDecision(category, reasonCode, detail)
+}
+
+func checkpointDecision(category CheckpointDecisionCategory, reasonCode CheckpointReasonCode, detail string) CheckpointDecision {
+	detail = sanitizeCheckpointDecisionDetail(detail)
+	return CheckpointDecision{
+		Reused:     category == CheckpointDecisionReused,
+		Category:   category,
+		ReasonCode: reasonCode,
+		Detail:     detail,
+		Reason:     detail,
+	}
+}
+
+func sanitizeCheckpointDecisionDetail(detail string) string {
+	detail = strings.TrimSpace(strings.ToValidUTF8(detail, "?"))
+	lower := strings.ToLower(detail)
+	if strings.ContainsAny(detail, `/\\`) || strings.Contains(lower, "secret") || strings.Contains(lower, "token") || strings.Contains(lower, "password") || strings.Contains(lower, "credential") || strings.Contains(lower, "environment") {
+		return "checkpoint decision detail redacted"
+	}
+	var b strings.Builder
+	for _, r := range detail {
+		if r < 0x20 || r == 0x7f {
+			r = ' '
+		}
+		if b.Len()+len(string(r)) > checkpointDecisionDetailLimit {
+			break
+		}
+		b.WriteRune(r)
+	}
+	return strings.Join(strings.Fields(b.String()), " ")
+}
+
 type CheckpointEvent struct {
-	Stage      string `json:"stage"`
-	StepID     string `json:"step_id,omitempty"`
-	LaneID     string `json:"lane_id,omitempty"`
-	ModuleKey  string `json:"module_key,omitempty"`
-	Action     string `json:"action"`
-	Category   string `json:"category,omitempty"`
-	ReasonCode string `json:"reason_code,omitempty"`
-	Detail     string `json:"detail,omitempty"`
-	Reason     string `json:"reason,omitempty"`
+	Stage      string                     `json:"stage"`
+	StepID     string                     `json:"step_id,omitempty"`
+	LaneID     string                     `json:"lane_id,omitempty"`
+	ModuleKey  string                     `json:"module_key,omitempty"`
+	Action     CheckpointDecisionCategory `json:"action"`
+	Category   CheckpointDecisionCategory `json:"category,omitempty"`
+	ReasonCode CheckpointReasonCode       `json:"reason_code,omitempty"`
+	Detail     string                     `json:"detail,omitempty"`
+	Reason     string                     `json:"reason,omitempty"`
 }

 type CheckpointExecutionPolicy struct {
@@ -100,14 +170,14 @@ func (policy CheckpointExecutionPolicy) requiresReusable(stepID, laneID string)

 func forceCheckpointDecision(policy CheckpointExecutionPolicy, stepID, laneID string, decision CheckpointDecision) CheckpointDecision {
 	if policy.forced(stepID, laneID) {
-		return CheckpointDecision{Category: "forced_recompute", ReasonCode: "recompute_step", Detail: "selected step requires execution"}
+		return checkpointDecision(CheckpointDecisionForcedRecompute, CheckpointReasonRecomputeStep, "selected step requires execution")
 	}
 	return decision
 }

 func requireReusableCheckpoint(policy CheckpointExecutionPolicy, stepID, laneID string, decision CheckpointDecision) error {
 	if policy.requiresReusable(stepID, laneID) && !decision.Reused {
-		return fmt.Errorf("required reusable checkpoint unavailable for step %q lane %q", strings.TrimSpace(stepID), strings.TrimSpace(laneID))
+		return fmt.Errorf("required reusable checkpoint unavailable for step %q lane %q (%s)", strings.TrimSpace(stepID), strings.TrimSpace(laneID), decision.ReasonCode)
 	}
 	return nil
 }
@@ -116,23 +186,20 @@ func requireReusableCheckpoint(policy CheckpointExecutionPolicy, stepID, laneID
 // validation at the single point where a stage's observable decision is made.
 func resolveCheckpointDecision(output *RunOutput, loader CheckpointLoader, policy CheckpointExecutionPolicy, stage ModuleStage, stepID, laneID, moduleKey string, decision CheckpointDecision, codec artifactCodecEntry, artifacts []CheckpointArtifact) (CheckpointDecision, error) {
 	decision = forceCheckpointDecision(policy, stepID, laneID, decision)
-	if err := requireReusableCheckpoint(policy, stepID, laneID, decision); err != nil {
-		return decision, err
-	}
 	if decision.Reused {
 		for _, artifact := range artifacts {
 			if _, _, err := decodeCanonicalCheckpointArtifact(codec, artifact); err != nil {
-				decision = CheckpointDecision{Category: "executed", ReasonCode: "artifact_not_canonical", Detail: "stored " + string(stage) + " artifact failed canonical codec validation", Reason: string(stage) + " artifact checkpoint is not canonical"}
+				decision = checkpointDecision(CheckpointDecisionExecuted, checkpointArtifactReasonCode(err), "stored "+string(stage)+" artifact failed canonical codec validation")
 				break
 			}
 		}
 	}
-	if err := requireReusableCheckpoint(policy, stepID, laneID, decision); err != nil {
-		return decision, err
-	}
 	if output != nil {
 		recordCheckpointEvent(output, loader, string(stage), stepID, laneID, moduleKey, decision)
 	}
+	if err := requireReusableCheckpoint(policy, stepID, laneID, decision); err != nil {
+		return decision, err
+	}
 	return decision, nil
 }

@@ -228,16 +295,16 @@ func (noopCheckpointRecorder) NormalizeFailed(string, string, []CheckpointFinger

 func (noopCheckpointLoader) Enabled() bool { return false }
 func (noopCheckpointLoader) Source(string) (SourceCheckpoint, CheckpointDecision) {
-	return SourceCheckpoint{}, CheckpointDecision{Category: "executed", ReasonCode: "loading_disabled", Reason: "checkpoint loading disabled"}
+	return SourceCheckpoint{}, checkpointDecision(CheckpointDecisionExecuted, CheckpointReasonLoadingDisabled, "checkpoint loading disabled")
 }
 func (noopCheckpointLoader) Extract(string, string, []CheckpointFingerprint) (ExtractCheckpoint, CheckpointDecision) {
-	return ExtractCheckpoint{}, CheckpointDecision{Category: "executed", ReasonCode: "loading_disabled", Reason: "checkpoint loading disabled"}
+	return ExtractCheckpoint{}, checkpointDecision(CheckpointDecisionExecuted, CheckpointReasonLoadingDisabled, "checkpoint loading disabled")
 }
 func (noopCheckpointLoader) Merge(string, string, []CheckpointFingerprint) (MergeCheckpoint, CheckpointDecision) {
-	return MergeCheckpoint{}, CheckpointDecision{Category: "executed", ReasonCode: "loading_disabled", Reason: "checkpoint loading disabled"}
+	return MergeCheckpoint{}, checkpointDecision(CheckpointDecisionExecuted, CheckpointReasonLoadingDisabled, "checkpoint loading disabled")
 }
 func (noopCheckpointLoader) Normalize(string, string, []CheckpointFingerprint) (NormalizeCheckpoint, CheckpointDecision) {
-	return NormalizeCheckpoint{}, CheckpointDecision{Category: "executed", ReasonCode: "loading_disabled", Reason: "checkpoint loading disabled"}
+	return NormalizeCheckpoint{}, checkpointDecision(CheckpointDecisionExecuted, CheckpointReasonLoadingDisabled, "checkpoint loading disabled")
 }

 func checkpointExtractRunning(recorder CheckpointRecorder, stepID, laneID, moduleKey string, deps []CheckpointFingerprint) error {
--- a/internal/framework/pipeline/runner.go
+++ b/internal/framework/pipeline/runner.go
@@ -623,14 +623,14 @@ func recordCheckpointEvent(output *RunOutput, loader CheckpointLoader, stage str
 	})
 }

-func checkpointDecisionCategory(decision CheckpointDecision) string {
+func checkpointDecisionCategory(decision CheckpointDecision) CheckpointDecisionCategory {
 	if decision.Category != "" {
 		return decision.Category
 	}
 	if decision.Reused {
-		return "reused"
+		return CheckpointDecisionReused
 	}
-	return "executed"
+	return CheckpointDecisionExecuted
 }

 func populateOutputManifest(output *RunOutput) {
@@ -642,7 +642,7 @@ func populateOutputManifest(output *RunOutput) {
 	if len(output.CheckpointEvents) > 0 {
 		decisions := make([]artifacts.CheckpointDecisionManifest, 0, len(output.CheckpointEvents))
 		for _, event := range output.CheckpointEvents {
-			decisions = append(decisions, artifacts.CheckpointDecisionManifest{Stage: event.Stage, StepID: event.StepID, LaneID: event.LaneID, ModuleKey: event.ModuleKey, Category: event.Category, ReasonCode: event.ReasonCode, Detail: event.Detail})
+			decisions = append(decisions, artifacts.CheckpointDecisionManifest{Stage: event.Stage, StepID: event.StepID, LaneID: event.LaneID, ModuleKey: event.ModuleKey, Category: string(event.Category), ReasonCode: string(event.ReasonCode), Detail: event.Detail})
 		}
 		output.Manifest.CheckpointDecisions = decisions
 	}
--- a/internal/framework/pipeline/runner_concurrent.go
+++ b/internal/framework/pipeline/runner_concurrent.go
@@ -100,7 +100,7 @@ func initializeLaneStates(input RunInput, step PreparedPipelineStep, checkpoints
 		if err := setTypedLaneManifestMetadata(output, prepared.resolved.ID, prepared.typed.extractor, prepared.typed.merger, prepared.typed.normalizer); err != nil {
 			return nil, err
 		}
-		state, err := prepareLaneExtract(input, loader, doc, chunks, i, prepared)
+		state, err := prepareLaneExtract(input, loader, doc, chunks, i, prepared, output)
 		if err != nil {
 			return nil, err
 		}
@@ -175,6 +175,13 @@ func (r *Runner) runLaneEngine(parent context.Context, input RunInput, checkpoin
 		}()
 	}

+	completedOutputs, runErrors := collectLaneResults(ctx, cancel, input, checkpoints, chunks, states, results, completions, continuations)
+	close(continuations)
+	continuationWorkers.Wait()
+	return completedOutputs, runErrors
+}
+
+func collectLaneResults(ctx context.Context, cancel context.CancelFunc, input RunInput, checkpoints CheckpointRecorder, chunks []source.Chunk, states []*laneExtractState, results <-chan extractJobResult, completions <-chan laneCompletion, continuations chan<- *laneExtractState) ([]RunOutput, []orderedRunError) {
 	completedOutputs := make([]RunOutput, len(states))
 	var runErrors []orderedRunError
 	var pendingContinuations []*laneExtractState
@@ -184,7 +191,6 @@ func (r *Runner) runLaneEngine(parent context.Context, input RunInput, checkpoin
 			pendingContinuations = append(pendingContinuations, state)
 		}
 	}
-
 	resultChannel := results
 	for resultChannel != nil || len(pendingContinuations) > 0 || completed < launched {
 		var continuationChannel chan<- *laneExtractState
@@ -232,8 +238,6 @@ func (r *Runner) runLaneEngine(parent context.Context, input RunInput, checkpoin
 			}
 		}
 	}
-	close(continuations)
-	continuationWorkers.Wait()
 	return completedOutputs, runErrors
 }

@@ -246,7 +250,7 @@ func mergeCompletedLanes(output *RunOutput, completedOutputs []RunOutput) error
 	return nil
 }

-func prepareLaneExtract(input RunInput, loader CheckpointLoader, doc *source.SourceDocument, chunks []source.Chunk, index int, prepared preparedLaneExecutor) (*laneExtractState, error) {
+func prepareLaneExtract(input RunInput, loader CheckpointLoader, doc *source.SourceDocument, chunks []source.Chunk, index int, prepared preparedLaneExecutor, output *RunOutput) (*laneExtractState, error) {
 	lane, typed := prepared.resolved, prepared.typed
 	digest, err := joinedChunkDigest(chunks)
 	if err != nil {
@@ -256,7 +260,7 @@ func prepareLaneExtract(input RunInput, loader CheckpointLoader, doc *source.Sou
 	deps := append(digestFingerprints("chunks", digest), generatedReferenceDependencies(extractReferences)...)
 	state := &laneExtractState{index: index, prepared: prepared, deps: normalizeCheckpointFingerprints(deps), remaining: len(chunks), results: make(map[int]extractJobResult, len(chunks))}
 	cp, decision := loadExtract(loader, input.stepID, lane.ID, lane.Extract.Module, state.deps)
-	decision, err = resolveCheckpointDecision(nil, loader, input.CheckpointPolicy, StageExtract, input.stepID, lane.ID, lane.Extract.Module, decision, typed.codec, cp.Outputs)
+	decision, err = resolveCheckpointDecision(output, loader, input.CheckpointPolicy, StageExtract, input.stepID, lane.ID, lane.Extract.Module, decision, typed.codec, cp.Outputs)
 	if err != nil {
 		return nil, err
 	}
@@ -385,7 +389,6 @@ func (r *Runner) continueLane(ctx context.Context, input RunInput, checkpoints C
 	}
 	local.Warnings = append(local.Warnings, cloneWarnings(results.warnings)...)
 	local.Rejected = append(local.Rejected, cloneRejectedOutputs(results.rejected)...)
-	recordCheckpointEvent(&local, loader, string(StageExtract), input.stepID, lane.ID, lane.Extract.Module, results.decision)
 	if err := writeDebugTimed(input.Debug, path.Join("extract", debugPathComponent(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}
 	}
--- a/internal/framework/pipeline/runner_extract_handoff_test.go
+++ b/internal/framework/pipeline/runner_extract_handoff_test.go
@@ -252,7 +252,7 @@ func TestRunnerPromotesOnlyAcceptedExtractRetryWarnings(t *testing.T) {
 	}
 }

-func assertExtractDecision(t *testing.T, events []CheckpointEvent, action string, reason string) {
+func assertExtractDecision(t *testing.T, events []CheckpointEvent, action CheckpointDecisionCategory, reason string) {
 	t.Helper()
 	for _, event := range events {
 		if event.Stage == string(StageExtract) {
--- a/internal/framework/pipeline/runner_typed.go
+++ b/internal/framework/pipeline/runner_typed.go
@@ -100,21 +100,45 @@ func serializeArtifact(codec artifactCodecEntry, value any, candidate bool) (con
 	return contracts.SerializedArtifact{Kind: codec.spec.Kind, Schema: contracts.CloneArtifactSchema(schema), MediaType: codec.spec.MediaType, Content: append([]byte(nil), content...), Metadata: metadata}, nil
 }

+type checkpointArtifactValidationError struct {
+	code CheckpointReasonCode
+	err  error
+}
+
+func (e *checkpointArtifactValidationError) Error() string { return e.err.Error() }
+func (e *checkpointArtifactValidationError) Unwrap() error { return e.err }
+
+func checkpointArtifactValidationFailure(code CheckpointReasonCode, format string, args ...any) error {
+	return &checkpointArtifactValidationError{code: code, err: fmt.Errorf(format, args...)}
+}
+
+func checkpointArtifactReasonCode(err error) CheckpointReasonCode {
+	var validationErr *checkpointArtifactValidationError
+	if errors.As(err, &validationErr) {
+		return validationErr.code
+	}
+	return CheckpointReasonArtifactPayloadInvalid
+}
+
 func decodeCheckpointArtifact(codec artifactCodecEntry, artifact CheckpointArtifact) (any, error) {
 	expectedDigest := contracts.DigestArtifactSchema(codec.spec.Schema)
 	if artifact.Artifact.Kind != codec.spec.Kind {
-		return nil, fmt.Errorf("artifact kind %q does not match codec %q", artifact.Artifact.Kind, codec.spec.Kind)
+		return nil, checkpointArtifactValidationFailure(CheckpointReasonArtifactCodecIncompatible, "artifact kind %q does not match codec %q", artifact.Artifact.Kind, codec.spec.Kind)
 	}
 	if artifact.Artifact.Schema.ID != codec.spec.Schema.ID || artifact.Artifact.Schema.Version != codec.spec.Schema.Version {
-		return nil, fmt.Errorf("artifact schema %q version %q does not match codec schema %q version %q", artifact.Artifact.Schema.ID, artifact.Artifact.Schema.Version, codec.spec.Schema.ID, codec.spec.Schema.Version)
+		return nil, checkpointArtifactValidationFailure(CheckpointReasonArtifactCodecIncompatible, "artifact schema %q version %q does not match codec schema %q version %q", artifact.Artifact.Schema.ID, artifact.Artifact.Schema.Version, codec.spec.Schema.ID, codec.spec.Schema.Version)
 	}
 	if artifact.SchemaDigest != expectedDigest {
-		return nil, fmt.Errorf("artifact schema digest %q does not match codec schema digest %q", artifact.SchemaDigest, expectedDigest)
+		return nil, checkpointArtifactValidationFailure(CheckpointReasonArtifactCodecIncompatible, "artifact schema digest %q does not match codec schema digest %q", artifact.SchemaDigest, expectedDigest)
 	}
 	if artifact.Artifact.MediaType != codec.spec.MediaType {
-		return nil, fmt.Errorf("artifact media type %q does not match codec media type %q", artifact.Artifact.MediaType, codec.spec.MediaType)
+		return nil, checkpointArtifactValidationFailure(CheckpointReasonArtifactCodecIncompatible, "artifact media type %q does not match codec media type %q", artifact.Artifact.MediaType, codec.spec.MediaType)
 	}
-	return codec.decode(append([]byte(nil), artifact.Artifact.Content...))
+	value, err := codec.decode(append([]byte(nil), artifact.Artifact.Content...))
+	if err != nil {
+		return nil, checkpointArtifactValidationFailure(CheckpointReasonArtifactPayloadInvalid, "decode artifact payload: %w", err)
+	}
+	return value, nil
 }

 func decodeCanonicalCheckpointArtifact(codec artifactCodecEntry, artifact CheckpointArtifact) (any, CheckpointArtifact, error) {
@@ -124,14 +148,14 @@ func decodeCanonicalCheckpointArtifact(codec artifactCodecEntry, artifact Checkp
 	}
 	canonical, err := serializeArtifact(codec, value, false)
 	if err != nil {
-		return nil, CheckpointArtifact{}, err
+		return nil, CheckpointArtifact{}, checkpointArtifactValidationFailure(CheckpointReasonArtifactPayloadInvalid, "encode canonical artifact: %w", err)
 	}
 	if canonical.Kind != artifact.Artifact.Kind || canonical.MediaType != artifact.Artifact.MediaType || checkpointContentDigest(canonical.Content) != checkpointContentDigest(artifact.Artifact.Content) {
-		return nil, CheckpointArtifact{}, fmt.Errorf("stored artifact is not canonical")
+		return nil, CheckpointArtifact{}, checkpointArtifactValidationFailure(CheckpointReasonArtifactNotCanonical, "stored artifact is not canonical")
 	}
 	hydrated, err := hydrateCheckpointArtifact(codec, cloneCheckpointArtifact(artifact), value)
 	if err != nil {
-		return nil, CheckpointArtifact{}, err
+		return nil, CheckpointArtifact{}, checkpointArtifactValidationFailure(CheckpointReasonArtifactPayloadInvalid, "hydrate checkpoint artifact: %w", err)
 	}
 	return value, hydrated, nil
 }
--- a/internal/framework/pipeline/runner_typed_checkpoint_test.go
+++ b/internal/framework/pipeline/runner_typed_checkpoint_test.go
@@ -1,12 +1,94 @@
 package pipeline

 import (
+	"context"
+	"encoding/json"
 	"strings"
 	"testing"

 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 )

+type requiredCheckpointLoader struct {
+	CheckpointLoader
+	checkpoint ExtractCheckpoint
+	decision   CheckpointDecision
+}
+
+func (l requiredCheckpointLoader) Enabled() bool { return true }
+func (l requiredCheckpointLoader) Extract(string, string, []CheckpointFingerprint) (ExtractCheckpoint, CheckpointDecision) {
+	return l.checkpoint, l.decision
+}
+
+func TestRequiredCheckpointFailureRetainsDecision(t *testing.T) {
+	const unsafeDetail = "unsafe-loader-detail-/private/checkpoint/path"
+	tests := []struct {
+		name       string
+		decision   CheckpointDecision
+		corrupt    bool
+		wantCode   CheckpointReasonCode
+		wantAction CheckpointDecisionCategory
+	}{
+		{"missing", NewCheckpointDecision(CheckpointDecisionExecuted, CheckpointReasonMissing, unsafeDetail), false, CheckpointReasonMissing, CheckpointDecisionExecuted},
+		{"corrupt", NewCheckpointDecision(CheckpointDecisionReused, CheckpointReasonReused, "checkpoint reusable"), true, CheckpointReasonArtifactNotCanonical, CheckpointDecisionExecuted},
+		{"incompatible", NewCheckpointDecision(CheckpointDecisionExecuted, CheckpointReasonArtifactCodecIncompatible, unsafeDetail), false, CheckpointReasonArtifactCodecIncompatible, CheckpointDecisionExecuted},
+		{"dependency invalidated", NewCheckpointDecision(CheckpointDecisionDependencyInvalidated, CheckpointReasonDependencyMismatch, unsafeDetail), false, CheckpointReasonDependencyMismatch, CheckpointDecisionDependencyInvalidated},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			prepared := preparedConcurrentPipeline(t, 1)
+			step := prepared.Steps[0]
+			lane := step.lanes[0]
+			checkpoint := ExtractCheckpoint{}
+			if test.corrupt {
+				stored, err := checkpointArtifact(lane.typed.codec, lane.resolved.ID, lane.resolved.Extract.Module, "source", codecNotes{Items: []string{"stored"}})
+				if err != nil {
+					t.Fatal(err)
+				}
+				stored.Artifact.Content = []byte(`{"items": ["stored"]}`)
+				checkpoint.Outputs = []CheckpointArtifact{stored}
+			}
+			loader := requiredCheckpointLoader{CheckpointLoader: NoopCheckpointLoader(), checkpoint: checkpoint, decision: test.decision}
+			policy := CheckpointExecutionPolicy{RequireReusableLanes: map[string]struct{}{CheckpointLaneKey(step.ID, lane.resolved.ID): {}}}
+			output, err := New().Run(context.Background(), RunInput{Prepared: prepared, RawInput: []byte("input"), Checkpoint: loader, CheckpointPolicy: policy})
+			if err == nil || !strings.Contains(err.Error(), step.ID) || !strings.Contains(err.Error(), lane.resolved.ID) || !strings.Contains(err.Error(), string(test.wantCode)) {
+				t.Fatalf("Run() error = %v, want step, lane, and reason code %q", err, test.wantCode)
+			}
+			if strings.Contains(err.Error(), unsafeDetail) {
+				t.Fatalf("Run() error leaked loader detail: %v", err)
+			}
+			var found bool
+			for _, event := range output.CheckpointEvents {
+				if event.Stage == string(StageExtract) && event.StepID == step.ID && event.LaneID == lane.resolved.ID {
+					found = true
+					if event.Action != test.wantAction || event.ReasonCode != test.wantCode {
+						t.Fatalf("checkpoint event = %#v, want action %q and reason %q", event, test.wantAction, test.wantCode)
+					}
+					if strings.Contains(event.Detail, unsafeDetail) {
+						t.Fatalf("checkpoint event leaked loader detail: %#v", event)
+					}
+				}
+			}
+			if !found {
+				t.Fatalf("required checkpoint decision missing from %#v", output.CheckpointEvents)
+			}
+			var manifestFound bool
+			for _, decision := range output.Manifest.CheckpointDecisions {
+				if decision.Stage == string(StageExtract) && decision.StepID == step.ID && decision.LaneID == lane.resolved.ID {
+					manifestFound = decision.Category == string(test.wantAction) && decision.ReasonCode == string(test.wantCode)
+				}
+			}
+			if !manifestFound {
+				t.Fatalf("manifest checkpoint decision missing category %q and code %q: %#v", test.wantAction, test.wantCode, output.Manifest.CheckpointDecisions)
+			}
+			encoded, marshalErr := json.Marshal(output.CheckpointEvents)
+			if marshalErr != nil || !strings.Contains(string(encoded), `"category":"`+string(test.wantAction)+`"`) || !strings.Contains(string(encoded), `"reason_code":"`+string(test.wantCode)+`"`) {
+				t.Fatalf("checkpoint event JSON = %s, error = %v", encoded, marshalErr)
+			}
+		})
+	}
+}
+
 func TestDecodeCheckpointArtifactRejectsIncompatibleCodecIdentityAndBytes(t *testing.T) {
 	registry := NewArtifactCodecRegistry()
 	if err := RegisterArtifactCodec(registry, notesCodec()); err != nil {