Add transcript bounds validation helpers

2026-05-08 17:01:18 +00:00
parent 79a8bcf37b
commit 79eb5cd9b1
2 changed files with 369 additions and 0 deletions
--- a/internal/contracts/bounds.go
+++ b/internal/contracts/bounds.go
@@ -0,0 +1,170 @@
+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
+}