Add pipeline stage contracts

internal/framework/contracts/contracts.go

@@ -46,10 +46,35 @@ type InputAdapter interface {
 	Parse(ctx context.Context, req ParseRequest) (*source.SourceDocument, error)
 }
 
+type SourceChunk struct {
+	ID       string              `json:"id"`
+	SourceID string              `json:"source_id"`
+	Index    int                 `json:"index"`
+	Units    []source.SourceUnit `json:"units"`
+	Metadata map[string]any      `json:"metadata,omitempty"`
+}
+
+type ChunkRequest struct {
+	Source   *source.SourceDocument `json:"-"`
+	Metadata map[string]any         `json:"metadata,omitempty"`
+}
+
+type ChunkResult struct {
+	Chunks   []SourceChunk `json:"chunks"`
+	Warnings []Warning     `json:"warnings,omitempty"`
+}
+
+type Chunker interface {
+	Key() string
+	Chunk(ctx context.Context, req ChunkRequest) (ChunkResult, error)
+}
+
 type ExtractionRequest struct {
-	Source    *source.SourceDocument `json:"-"`
-	LLMClient StructuredLLMClient    `json:"-"`
-	Metadata  map[string]any         `json:"metadata,omitempty"`
+	Source         *source.SourceDocument `json:"-"`
+	Chunk          *SourceChunk           `json:"chunk,omitempty"`
+	AmbientContext map[string]any         `json:"ambient_context,omitempty"`
+	LLMClient      StructuredLLMClient    `json:"-"`
+	Metadata       map[string]any         `json:"metadata,omitempty"`
 }
 
 type ExtractionResult struct {
@@ -65,6 +90,45 @@ type Extractor interface {
 	Extract(ctx context.Context, req ExtractionRequest) (ExtractionResult, error)
 }
 
+type ChunkArtifacts struct {
+	Chunk      SourceChunk                   `json:"chunk"`
+	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
+}
+
+type MergeRequest struct {
+	Source         *source.SourceDocument `json:"-"`
+	LaneID         string                 `json:"lane_id"`
+	ChunkArtifacts []ChunkArtifacts       `json:"chunk_artifacts"`
+	Metadata       map[string]any         `json:"metadata,omitempty"`
+}
+
+type MergeResult struct {
+	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
+	Warnings   []Warning                     `json:"warnings,omitempty"`
+}
+
+type Merger interface {
+	Key() string
+	Merge(ctx context.Context, req MergeRequest) (MergeResult, error)
+}
+
+type NormalizeRequest struct {
+	Source     *source.SourceDocument        `json:"-"`
+	LaneID     string                        `json:"lane_id"`
+	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
+	Metadata   map[string]any                `json:"metadata,omitempty"`
+}
+
+type NormalizeResult struct {
+	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
+	Warnings   []Warning                     `json:"warnings,omitempty"`
+}
+
+type Normalizer interface {
+	Key() string
+	Normalize(ctx context.Context, req NormalizeRequest) (NormalizeResult, error)
+}
+
 type ValidationRequest struct {
 	Source     *source.SourceDocument        `json:"-"`
 	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
@@ -95,3 +159,22 @@ type Warning struct {
 	ReasonCode string `json:"reason_code"`
 	Message    string `json:"message"`
 }
+
+type OutputRequest struct {
+	Manifest artifacts.RunManifest        `json:"manifest"`
+	Approved []artifacts.Artifact         `json:"approved,omitempty"`
+	Rejected []artifacts.RejectedArtifact `json:"rejected,omitempty"`
+	Warnings []Warning                    `json:"warnings,omitempty"`
+	Metadata map[string]any               `json:"metadata,omitempty"`
+}
+
+type OutputResult struct {
+	Bytes       []byte    `json:"-"`
+	ContentType string    `json:"content_type,omitempty"`
+	Warnings    []Warning `json:"warnings,omitempty"`
+}
+
+type OutputEncoder interface {
+	Key() string
+	Encode(ctx context.Context, req OutputRequest) (OutputResult, error)
+}