Add transcript bounds validation helpers
This commit is contained in:
170
internal/contracts/bounds.go
Normal file
170
internal/contracts/bounds.go
Normal file
@@ -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
|
||||
}
|
||||
199
internal/contracts/bounds_test.go
Normal file
199
internal/contracts/bounds_test.go
Normal file
@@ -0,0 +1,199 @@
|
||||
package contracts
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strconv"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestValidBoundsOutputProducesKeepSelector(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
boundsPath := filepath.Join(dir, "bounds.json")
|
||||
transcriptPath := filepath.Join(dir, "processed.json")
|
||||
|
||||
writeBoundsTestFile(t, boundsPath, `{
|
||||
"confidence":"high",
|
||||
"trim_action":"trim",
|
||||
"start_segment_id":10,
|
||||
"end_segment_id":868,
|
||||
"warnings":[]
|
||||
}`)
|
||||
writeBoundsTestFile(t, transcriptPath, `{
|
||||
"segments":[
|
||||
{"id":10,"text":"start"},
|
||||
{"id":868,"text":"end"}
|
||||
]
|
||||
}`)
|
||||
|
||||
bounds, err := ParseSessionBoundsFile(boundsPath)
|
||||
if err != nil {
|
||||
t.Fatalf("ParseSessionBoundsFile() error = %v", err)
|
||||
}
|
||||
if err := ValidateSessionBoundsAgainstTranscript(bounds, transcriptPath); err != nil {
|
||||
t.Fatalf("ValidateSessionBoundsAgainstTranscript() error = %v", err)
|
||||
}
|
||||
selector, copyUnchanged, err := BuildSeriatimKeepSelector(bounds)
|
||||
if err != nil {
|
||||
t.Fatalf("BuildSeriatimKeepSelector() error = %v", err)
|
||||
}
|
||||
if copyUnchanged {
|
||||
t.Fatal("copyUnchanged = true, want false for trim action")
|
||||
}
|
||||
if selector != "10-868" {
|
||||
t.Fatalf("selector = %q, want %q", selector, "10-868")
|
||||
}
|
||||
}
|
||||
|
||||
func TestBoundsMissingStartSegmentIDFails(t *testing.T) {
|
||||
bounds := SessionBounds{TrimAction: "trim", EndSegmentID: intPtr(5)}
|
||||
err := ValidateSessionBoundsAgainstTranscript(bounds, writeTranscriptWithIDs(t, 1, 5))
|
||||
if err == nil {
|
||||
t.Fatal("expected error, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "start_segment_id") {
|
||||
t.Fatalf("error = %q, want start_segment_id context", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestBoundsMissingEndSegmentIDFails(t *testing.T) {
|
||||
bounds := SessionBounds{TrimAction: "trim", StartSegmentID: intPtr(1)}
|
||||
err := ValidateSessionBoundsAgainstTranscript(bounds, writeTranscriptWithIDs(t, 1, 5))
|
||||
if err == nil {
|
||||
t.Fatal("expected error, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "end_segment_id") {
|
||||
t.Fatalf("error = %q, want end_segment_id context", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestBoundsDescendingRangeFails(t *testing.T) {
|
||||
bounds := SessionBounds{TrimAction: "trim", StartSegmentID: intPtr(9), EndSegmentID: intPtr(5)}
|
||||
err := ValidateSessionBoundsAgainstTranscript(bounds, writeTranscriptWithIDs(t, 5, 9))
|
||||
if err == nil {
|
||||
t.Fatal("expected error, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "<=") {
|
||||
t.Fatalf("error = %q, want range ordering context", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestBoundsNonExistentStartIDFails(t *testing.T) {
|
||||
bounds := SessionBounds{TrimAction: "trim", StartSegmentID: intPtr(3), EndSegmentID: intPtr(9)}
|
||||
err := ValidateSessionBoundsAgainstTranscript(bounds, writeTranscriptWithIDs(t, 4, 9))
|
||||
if err == nil {
|
||||
t.Fatal("expected error, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "start_segment_id 3 does not exist") {
|
||||
t.Fatalf("error = %q, want missing start id context", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestBoundsNonExistentEndIDFails(t *testing.T) {
|
||||
bounds := SessionBounds{TrimAction: "trim", StartSegmentID: intPtr(3), EndSegmentID: intPtr(9)}
|
||||
err := ValidateSessionBoundsAgainstTranscript(bounds, writeTranscriptWithIDs(t, 3, 8))
|
||||
if err == nil {
|
||||
t.Fatal("expected error, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "end_segment_id 9 does not exist") {
|
||||
t.Fatalf("error = %q, want missing end id context", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestInvalidTranscriptJSONFails(t *testing.T) {
|
||||
bounds := SessionBounds{TrimAction: "trim", StartSegmentID: intPtr(1), EndSegmentID: intPtr(2)}
|
||||
path := filepath.Join(t.TempDir(), "processed.json")
|
||||
writeBoundsTestFile(t, path, "not-json")
|
||||
|
||||
err := ValidateSessionBoundsAgainstTranscript(bounds, path)
|
||||
if err == nil {
|
||||
t.Fatal("expected error, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "transcript json parse failed") {
|
||||
t.Fatalf("error = %q, want transcript json parse context", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestTranscriptWithoutSegmentsFails(t *testing.T) {
|
||||
bounds := SessionBounds{TrimAction: "trim", StartSegmentID: intPtr(1), EndSegmentID: intPtr(2)}
|
||||
path := filepath.Join(t.TempDir(), "processed.json")
|
||||
writeBoundsTestFile(t, path, `{"schema":"audita.processed.v1"}`)
|
||||
|
||||
err := ValidateSessionBoundsAgainstTranscript(bounds, path)
|
||||
if err == nil {
|
||||
t.Fatal("expected error, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "segments array is required") {
|
||||
t.Fatalf("error = %q, want segments required context", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestWarningsArePreservedInParsedOutput(t *testing.T) {
|
||||
path := filepath.Join(t.TempDir(), "bounds.json")
|
||||
writeBoundsTestFile(t, path, `{
|
||||
"confidence":"medium",
|
||||
"trim_action":"trim",
|
||||
"start_segment_id":10,
|
||||
"end_segment_id":12,
|
||||
"warnings":["weak opening marker","possible flashback"]
|
||||
}`)
|
||||
|
||||
bounds, err := ParseSessionBoundsFile(path)
|
||||
if err != nil {
|
||||
t.Fatalf("ParseSessionBoundsFile() error = %v", err)
|
||||
}
|
||||
if len(bounds.Warnings) != 2 {
|
||||
t.Fatalf("warnings len = %d, want 2", len(bounds.Warnings))
|
||||
}
|
||||
if bounds.Warnings[0] != "weak opening marker" || bounds.Warnings[1] != "possible flashback" {
|
||||
t.Fatalf("warnings = %#v, want preserved warnings", bounds.Warnings)
|
||||
}
|
||||
}
|
||||
|
||||
func TestNoTrimActionCopyIsSupported(t *testing.T) {
|
||||
bounds := SessionBounds{TrimAction: "copy"}
|
||||
if err := ValidateSessionBoundsAgainstTranscript(bounds, writeTranscriptWithIDs(t, 1)); err != nil {
|
||||
t.Fatalf("ValidateSessionBoundsAgainstTranscript() error = %v", err)
|
||||
}
|
||||
selector, copyUnchanged, err := BuildSeriatimKeepSelector(bounds)
|
||||
if err != nil {
|
||||
t.Fatalf("BuildSeriatimKeepSelector() error = %v", err)
|
||||
}
|
||||
if selector != "" {
|
||||
t.Fatalf("selector = %q, want empty for copy action", selector)
|
||||
}
|
||||
if !copyUnchanged {
|
||||
t.Fatal("copyUnchanged = false, want true for copy action")
|
||||
}
|
||||
}
|
||||
|
||||
func writeTranscriptWithIDs(t *testing.T, ids ...int) string {
|
||||
t.Helper()
|
||||
path := filepath.Join(t.TempDir(), "processed.json")
|
||||
if len(ids) == 0 {
|
||||
writeBoundsTestFile(t, path, `{"segments":[]}`)
|
||||
return path
|
||||
}
|
||||
parts := make([]string, 0, len(ids))
|
||||
for _, id := range ids {
|
||||
parts = append(parts, `{"id":`+strconv.Itoa(id)+`}`)
|
||||
}
|
||||
writeBoundsTestFile(t, path, `{"segments":[`+strings.Join(parts, ",")+`]}`)
|
||||
return path
|
||||
}
|
||||
|
||||
func writeBoundsTestFile(t *testing.T, path, contents string) {
|
||||
t.Helper()
|
||||
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
|
||||
t.Fatalf("MkdirAll(%q): %v", path, err)
|
||||
}
|
||||
if err := os.WriteFile(path, []byte(contents), 0o644); err != nil {
|
||||
t.Fatalf("WriteFile(%q): %v", path, err)
|
||||
}
|
||||
}
|
||||
|
||||
func intPtr(v int) *int {
|
||||
value := v
|
||||
return &value
|
||||
}
|
||||
Reference in New Issue
Block a user