Reuse valid workspace checkpoints on request

internal/framework/pipeline/checkpoint.go

@@ -37,9 +37,58 @@ type CheckpointRecorder interface {
 	NormalizeFailed(laneID string, moduleKey string, dependencies []CheckpointFingerprint, err error) error
 }
 
+type CheckpointDecision struct {
+	Reused bool   `json:"reused"`
+	Reason string `json:"reason,omitempty"`
+}
+
+type CheckpointEvent struct {
+	Stage     string `json:"stage"`
+	LaneID    string `json:"lane_id,omitempty"`
+	ModuleKey string `json:"module_key,omitempty"`
+	Action    string `json:"action"`
+	Reason    string `json:"reason,omitempty"`
+}
+
+type SourceCheckpoint struct {
+	Document *source.SourceDocument
+}
+
+type ChunkCheckpoint struct {
+	Chunks   []contracts.SourceChunk
+	Warnings []contracts.Warning
+}
+
+type ExtractCheckpoint struct {
+	Outputs  []contracts.ExtractOutput
+	Rejected []contracts.RejectedOutput
+	Warnings []contracts.Warning
+}
+
+type MergeCheckpoint struct {
+	Output   contracts.MergeOutput
+	Warnings []contracts.Warning
+}
+
+type NormalizeCheckpoint struct {
+	Output   contracts.NormalizeOutput
+	Warnings []contracts.Warning
+}
+
+type CheckpointLoader interface {
+	Enabled() bool
+	Source(moduleKey string) (SourceCheckpoint, CheckpointDecision)
+	Chunk(moduleKey string, sourceDigest string) (ChunkCheckpoint, CheckpointDecision)
+	Extract(laneID string, moduleKey string, dependencies []CheckpointFingerprint) (ExtractCheckpoint, CheckpointDecision)
+	Merge(laneID string, moduleKey string, dependencies []CheckpointFingerprint) (MergeCheckpoint, CheckpointDecision)
+	Normalize(laneID string, moduleKey string, dependencies []CheckpointFingerprint) (NormalizeCheckpoint, CheckpointDecision)
+}
+
 type noopCheckpointRecorder struct{}
+type noopCheckpointLoader struct{}
 
 func NoopCheckpointRecorder() CheckpointRecorder { return noopCheckpointRecorder{} }
+func NoopCheckpointLoader() CheckpointLoader     { return noopCheckpointLoader{} }
 
 func (noopCheckpointRecorder) SourceRunning(string) error                           { return nil }
 func (noopCheckpointRecorder) SourceSucceeded(string, *source.SourceDocument) error { return nil }
@@ -84,6 +133,23 @@ func (noopCheckpointRecorder) NormalizeFailed(string, string, []CheckpointFinger
 	return nil
 }
 
+func (noopCheckpointLoader) Enabled() bool { return false }
+func (noopCheckpointLoader) Source(string) (SourceCheckpoint, CheckpointDecision) {
+	return SourceCheckpoint{}, CheckpointDecision{Reason: "checkpoint loading disabled"}
+}
+func (noopCheckpointLoader) Chunk(string, string) (ChunkCheckpoint, CheckpointDecision) {
+	return ChunkCheckpoint{}, CheckpointDecision{Reason: "checkpoint loading disabled"}
+}
+func (noopCheckpointLoader) Extract(string, string, []CheckpointFingerprint) (ExtractCheckpoint, CheckpointDecision) {
+	return ExtractCheckpoint{}, CheckpointDecision{Reason: "checkpoint loading disabled"}
+}
+func (noopCheckpointLoader) Merge(string, string, []CheckpointFingerprint) (MergeCheckpoint, CheckpointDecision) {
+	return MergeCheckpoint{}, CheckpointDecision{Reason: "checkpoint loading disabled"}
+}
+func (noopCheckpointLoader) Normalize(string, string, []CheckpointFingerprint) (NormalizeCheckpoint, CheckpointDecision) {
+	return NormalizeCheckpoint{}, CheckpointDecision{Reason: "checkpoint loading disabled"}
+}
+
 func rawOutputDigests(payloads []contracts.RawPayload) []CheckpointFingerprint {
 	values := make([]CheckpointFingerprint, 0, len(payloads))
 	for i, payload := range payloads {