Generate and materialize canonical chunk plans

internal/framework/pipeline/debug.go

@@ -111,6 +111,18 @@ type debugSourceChunk struct {
 	PlanAnnotations source.ChunkAnnotations `json:"plan_annotations,omitempty"`
 }
 
+type debugChunkPlan struct {
+	SourceDigest string            `json:"source_digest,omitempty"`
+	Ranges       []debugChunkRange `json:"ranges,omitempty"`
+	Annotations  map[string]any    `json:"annotations,omitempty"`
+}
+
+type debugChunkRange struct {
+	StartUnitID int            `json:"start_unit_id"`
+	EndUnitID   int            `json:"end_unit_id"`
+	Annotations map[string]any `json:"annotations,omitempty"`
+}
+
 type debugSerializedOutput struct {
 	LaneID        string                   `json:"lane_id"`
 	NormalizerKey string                   `json:"normalizer_key"`
@@ -489,6 +501,37 @@ func debugSourceChunkEnvelopes(chunks []source.Chunk) []debugSourceChunk {
 	return out
 }
 
+func debugChunkPlanEnvelope(plan source.ChunkPlan) debugChunkPlan {
+	envelope := debugChunkPlan{
+		SourceDigest: plan.SourceDigest,
+		Ranges:       make([]debugChunkRange, len(plan.Ranges)),
+		Annotations:  debugChunkAnnotations(plan.Annotations),
+	}
+	for i, chunkRange := range plan.Ranges {
+		envelope.Ranges[i] = debugChunkRange{
+			StartUnitID: chunkRange.StartUnitID,
+			EndUnitID:   chunkRange.EndUnitID,
+			Annotations: debugChunkAnnotations(chunkRange.Annotations),
+		}
+	}
+	return envelope
+}
+
+func debugChunkAnnotations(annotations source.ChunkAnnotations) map[string]any {
+	if len(annotations) == 0 {
+		return nil
+	}
+	out := make(map[string]any, len(annotations))
+	for namespace, raw := range annotations {
+		if json.Valid(raw) {
+			out[namespace] = append(json.RawMessage(nil), raw...)
+		} else {
+			out[namespace] = string(raw)
+		}
+	}
+	return out
+}
+
 func debugSerializedOutputEnvelope(output contracts.SerializedOutput) debugSerializedOutput {
 	schema := contracts.CloneArtifactSchema(output.Artifact.Schema)
 	digest := contracts.DigestArtifactSchema(schema)