narratio/internal/contracts/bounds.go

package contracts

import (
	"encoding/json"
	"fmt"
	"math"
	"os"
	"strconv"
	"strings"
)

const (
	// BoundsTrimActionTrim keeps only a selected segment range.
	BoundsTrimActionTrim = "trim"
	// BoundsTrimActionNone indicates no trimming should be applied.
	BoundsTrimActionNone = "none"
	// BoundsTrimActionCopy indicates the transcript should be copied unchanged.
	BoundsTrimActionCopy = "copy"
)

// SessionBounds is the expected bounds-output contract from Scriptorium.
// Unknown JSON fields are tolerated to align with existing transcript/output parsing policy.
type SessionBounds struct {
	Confidence            string `json:"confidence"`
	TrimAction            string `json:"trim_action"`
	StartSegmentID        *int   `json:"start_segment_id"`
	EndSegmentID          *int   `json:"end_segment_id"`
	StartBoundaryReason   string `json:"start_boundary_reason"`
	EndBoundaryReason     string `json:"end_boundary_reason"`
	ExcludedPrefixSummary string `json:"excluded_prefix_summary"`
	ExcludedSuffixSummary string `json:"excluded_suffix_summary"`
	Warnings              []any  `json:"warnings"`
	StartEvidence         any    `json:"start_evidence"`
	EndEvidence           any    `json:"end_evidence"`
}

// ParseSessionBoundsFile reads and parses one Scriptorium bounds output JSON file.
func ParseSessionBoundsFile(path string) (SessionBounds, error) {
	data, err := os.ReadFile(path)
	if err != nil {
		return SessionBounds{}, fmt.Errorf("read bounds file: %w", err)
	}
	var bounds SessionBounds
	if err := json.Unmarshal(data, &bounds); err != nil {
		return SessionBounds{}, fmt.Errorf("parse bounds json: %w", err)
	}
	return bounds, nil
}

// ValidateSessionBoundsAgainstTranscript validates bounds against transcript segment ID space.
func ValidateSessionBoundsAgainstTranscript(bounds SessionBounds, transcriptPath string) error {
	action, err := normalizeBoundsTrimAction(bounds.TrimAction)
	if err != nil {
		return err
	}

	segmentIDs, err := loadTranscriptSegmentIDs(transcriptPath)
	if err != nil {
		return err
	}

	if action == BoundsTrimActionTrim {
		if bounds.StartSegmentID == nil {
			return fmt.Errorf("bounds.start_segment_id is required for trim action")
		}
		if bounds.EndSegmentID == nil {
			return fmt.Errorf("bounds.end_segment_id is required for trim action")
		}
		if *bounds.StartSegmentID > *bounds.EndSegmentID {
			return fmt.Errorf("bounds.start_segment_id must be <= bounds.end_segment_id")
		}
		if _, ok := segmentIDs[*bounds.StartSegmentID]; !ok {
			return fmt.Errorf("bounds.start_segment_id %d does not exist in transcript segments", *bounds.StartSegmentID)
		}
		if _, ok := segmentIDs[*bounds.EndSegmentID]; !ok {
			return fmt.Errorf("bounds.end_segment_id %d does not exist in transcript segments", *bounds.EndSegmentID)
		}
	}

	return nil
}

// BuildSeriatimKeepSelector converts validated bounds into Seriatim keep selector semantics.
// It returns selector="", copyUnchanged=true for no-trim actions.
func BuildSeriatimKeepSelector(bounds SessionBounds) (selector string, copyUnchanged bool, err error) {
	action, err := normalizeBoundsTrimAction(bounds.TrimAction)
	if err != nil {
		return "", false, err
	}

	if action == BoundsTrimActionTrim {
		if bounds.StartSegmentID == nil {
			return "", false, fmt.Errorf("bounds.start_segment_id is required for trim action")
		}
		if bounds.EndSegmentID == nil {
			return "", false, fmt.Errorf("bounds.end_segment_id is required for trim action")
		}
		if *bounds.StartSegmentID > *bounds.EndSegmentID {
			return "", false, fmt.Errorf("bounds.start_segment_id must be <= bounds.end_segment_id")
		}
		return strconv.Itoa(*bounds.StartSegmentID) + "-" + strconv.Itoa(*bounds.EndSegmentID), false, nil
	}

	return "", true, nil
}

func normalizeBoundsTrimAction(raw string) (string, error) {
	action := strings.ToLower(strings.TrimSpace(raw))
	switch action {
	case "", BoundsTrimActionTrim:
		return BoundsTrimActionTrim, nil
	case BoundsTrimActionNone:
		return BoundsTrimActionNone, nil
	case BoundsTrimActionCopy:
		return BoundsTrimActionCopy, nil
	default:
		return "", fmt.Errorf("unsupported bounds.trim_action %q", raw)
	}
}

func loadTranscriptSegmentIDs(path string) (map[int]struct{}, error) {
	data, err := os.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("read transcript file: %w", err)
	}

	var payload map[string]any
	if err := json.Unmarshal(data, &payload); err != nil {
		return nil, fmt.Errorf("transcript json parse failed: %w", err)
	}

	segmentsAny, ok := payload["segments"]
	if !ok {
		return nil, fmt.Errorf("transcript top-level segments array is required")
	}
	segments, ok := segmentsAny.([]any)
	if !ok {
		return nil, fmt.Errorf("transcript top-level segments must be an array")
	}

	ids := make(map[int]struct{}, len(segments))
	for i, segmentAny := range segments {
		segment, ok := segmentAny.(map[string]any)
		if !ok {
			return nil, fmt.Errorf("transcript segments[%d] must be an object", i)
		}
		idAny, exists := segment["id"]
		if !exists {
			continue
		}
		id, err := parseJSONSegmentID(idAny)
		if err != nil {
			return nil, fmt.Errorf("transcript segments[%d].id invalid: %w", i, err)
		}
		ids[id] = struct{}{}
	}

	return ids, nil
}

func parseJSONSegmentID(v any) (int, error) {
	n, ok := v.(float64)
	if !ok {
		return 0, fmt.Errorf("must be numeric")
	}
	if math.Trunc(n) != n {
		return 0, fmt.Errorf("must be an integer")
	}
	return int(n), nil
}