Bugfixes and documentation cleanup for v1.0 release.

schema/full-output.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://gitea.maximumdirect.net/eric/seriatim/schema/output.schema.json",
+  "$id": "https://gitea.maximumdirect.net/eric/seriatim/schema/full-output.schema.json",
   "title": "seriatim full output transcript",
   "type": "object",
   "additionalProperties": false,

schema/intermediate-output.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://gitea.maximumdirect.net/eric/seriatim/schema/default-output.schema.json",
-  "title": "seriatim default output transcript",
+  "$id": "https://gitea.maximumdirect.net/eric/seriatim/schema/intermediate-output.schema.json",
+  "title": "seriatim intermediate output transcript",
   "type": "object",
   "additionalProperties": false,
   "required": ["metadata", "segments"],
@@ -13,7 +13,7 @@
       "properties": {
         "application": { "type": "string" },
         "version": { "type": "string" },
-        "output_schema": { "type": "string", "const": "default" }
+        "output_schema": { "type": "string", "const": "seriatim-intermediate" }
       }
     },
     "segments": {

schema/minimal-output.schema.json

@@ -13,7 +13,7 @@
       "properties": {
         "application": { "type": "string" },
         "version": { "type": "string" },
-        "output_schema": { "type": "string", "const": "minimal" }
+        "output_schema": { "type": "string", "const": "seriatim-minimal" }
       }
     },
     "segments": {

schema/output.go

@@ -14,9 +14,9 @@ import (
 var schemaFS embed.FS
 
 const (
-	outputSchemaPath        = "output.schema.json"
-	defaultOutputSchemaPath = "default-output.schema.json"
-	minimalOutputSchemaPath = "minimal-output.schema.json"
+	fullOutputSchemaPath         = "full-output.schema.json"
+	intermediateOutputSchemaPath = "intermediate-output.schema.json"
+	minimalOutputSchemaPath      = "minimal-output.schema.json"
 )
 
 var (
@@ -32,10 +32,10 @@ type Transcript struct {
 	OverlapGroups []OverlapGroup `json:"overlap_groups"`
 }
 
-// DefaultTranscript is seriatim's default public JSON output contract.
-type DefaultTranscript struct {
-	Metadata DefaultMetadata  `json:"metadata"`
-	Segments []DefaultSegment `json:"segments"`
+// IntermediateTranscript is seriatim's intermediate public JSON output contract.
+type IntermediateTranscript struct {
+	Metadata IntermediateMetadata  `json:"metadata"`
+	Segments []IntermediateSegment `json:"segments"`
 }
 
 // MinimalTranscript is seriatim's compact public JSON output contract.
@@ -55,8 +55,8 @@ type Metadata struct {
 	OutputModules         []string `json:"output_modules"`
 }
 
-// DefaultMetadata records default artifact identity.
-type DefaultMetadata struct {
+// IntermediateMetadata records intermediate artifact identity.
+type IntermediateMetadata struct {
 	Application  string `json:"application"`
 	Version      string `json:"version"`
 	OutputSchema string `json:"output_schema"`
@@ -84,9 +84,9 @@ type Segment struct {
 	OverlapGroupID     int      `json:"overlap_group_id,omitempty"`
 }
 
-// DefaultSegment is the compact public transcript segment shape with
+// IntermediateSegment is the compact public transcript segment shape with
 // categories.
-type DefaultSegment struct {
+type IntermediateSegment struct {
 	ID         int      `json:"id"`
 	Start      float64  `json:"start"`
 	End        float64  `json:"end"`
@@ -115,7 +115,7 @@ type OverlapGroup struct {
 	Resolution string   `json:"resolution"`
 }
 
-// ValidateTranscript validates a typed transcript against the public JSON
+// ValidateTranscript validates a full transcript against the public JSON
 // schema and seriatim-specific semantic rules.
 func ValidateTranscript(transcript Transcript) error {
 	if err := validateSemantics(transcript); err != nil {
@@ -129,18 +129,18 @@ func ValidateTranscript(transcript Transcript) error {
 	return ValidateJSON(data)
 }
 
-// ValidateDefaultTranscript validates the default transcript against the
-// default JSON schema and seriatim-specific semantic rules.
-func ValidateDefaultTranscript(transcript DefaultTranscript) error {
-	if err := validateDefaultSemantics(transcript); err != nil {
+// ValidateIntermediateTranscript validates the intermediate transcript against
+// the intermediate JSON schema and seriatim-specific semantic rules.
+func ValidateIntermediateTranscript(transcript IntermediateTranscript) error {
+	if err := validateIntermediateSemantics(transcript); err != nil {
 		return err
 	}
 
 	data, err := json.Marshal(transcript)
 	if err != nil {
-		return fmt.Errorf("marshal default transcript for schema validation: %w", err)
+		return fmt.Errorf("marshal intermediate transcript for schema validation: %w", err)
 	}
-	return ValidateDefaultJSON(data)
+	return ValidateIntermediateJSON(data)
 }
 
 // ValidateMinimalTranscript validates a minimal transcript against the minimal
@@ -159,13 +159,13 @@ func ValidateMinimalTranscript(transcript MinimalTranscript) error {
 
 // ValidateJSON validates serialized output JSON against the public schema.
 func ValidateJSON(data []byte) error {
-	return validateJSONWithSchema(data, outputSchemaPath)
+	return validateJSONWithSchema(data, fullOutputSchemaPath)
 }
 
-// ValidateDefaultJSON validates serialized default output JSON against the
-// default public schema.
-func ValidateDefaultJSON(data []byte) error {
-	return validateJSONWithSchema(data, defaultOutputSchemaPath)
+// ValidateIntermediateJSON validates serialized intermediate output JSON
+// against the intermediate public schema.
+func ValidateIntermediateJSON(data []byte) error {
+	return validateJSONWithSchema(data, intermediateOutputSchemaPath)
 }
 
 // ValidateMinimalJSON validates serialized minimal output JSON against the
@@ -245,7 +245,7 @@ func validateSemantics(transcript Transcript) error {
 	return nil
 }
 
-func validateDefaultSemantics(transcript DefaultTranscript) error {
+func validateIntermediateSemantics(transcript IntermediateTranscript) error {
 	for index, segment := range transcript.Segments {
 		wantID := index + 1
 		if segment.ID != wantID {

schema/output_test.go

@@ -21,11 +21,11 @@ func TestValidateMinimalTranscriptAcceptsValidTranscript(t *testing.T) {
 	}
 }
 
-func TestValidateDefaultTranscriptAcceptsValidTranscript(t *testing.T) {
-	transcript := validDefaultTranscript()
+func TestValidateIntermediateTranscriptAcceptsValidTranscript(t *testing.T) {
+	transcript := validIntermediateTranscript()
 
-	if err := ValidateDefaultTranscript(transcript); err != nil {
-		t.Fatalf("validate default transcript: %v", err)
+	if err := ValidateIntermediateTranscript(transcript); err != nil {
+		t.Fatalf("validate intermediate transcript: %v", err)
 	}
 }
 
@@ -34,7 +34,7 @@ func TestValidateMinimalJSONRejectsMissingRequiredField(t *testing.T) {
 		"metadata": {
 			"application": "seriatim",
 			"version": "dev",
-			"output_schema": "minimal"
+				"output_schema": "seriatim-minimal"
 		}
 	}`))
 	assertErrorContains(t, err, "segments")
@@ -45,7 +45,7 @@ func TestValidateMinimalJSONRejectsWrongFieldType(t *testing.T) {
 		"metadata": {
 			"application": "seriatim",
 			"version": "dev",
-			"output_schema": "minimal"
+				"output_schema": "seriatim-minimal"
 		},
 		"segments": [
 			{
@@ -68,7 +68,7 @@ func TestValidateMinimalJSONRejectsUnexpectedFields(t *testing.T) {
 		{
 			name: "top-level overlap groups",
 			json: `{
-				"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
+					"metadata": {"application": "seriatim", "version": "dev", "output_schema": "seriatim-minimal"},
 				"segments": [],
 				"overlap_groups": []
 			}`,
@@ -76,28 +76,28 @@ func TestValidateMinimalJSONRejectsUnexpectedFields(t *testing.T) {
 		{
 			name: "segment source",
 			json: `{
-				"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
+					"metadata": {"application": "seriatim", "version": "dev", "output_schema": "seriatim-minimal"},
 				"segments": [{"id": 1, "source": "input.json", "start": 1, "end": 2, "speaker": "Alice", "text": "hello"}]
 			}`,
 		},
 		{
 			name: "segment categories",
 			json: `{
-				"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
+					"metadata": {"application": "seriatim", "version": "dev", "output_schema": "seriatim-minimal"},
 				"segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "categories": ["backchannel"]}]
 			}`,
 		},
 		{
 			name: "segment derived from",
 			json: `{
-				"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
+					"metadata": {"application": "seriatim", "version": "dev", "output_schema": "seriatim-minimal"},
 				"segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "derived_from": ["input.json#0"]}]
 			}`,
 		},
 		{
 			name: "segment words",
 			json: `{
-				"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
+					"metadata": {"application": "seriatim", "version": "dev", "output_schema": "seriatim-minimal"},
 				"segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "words": []}]
 			}`,
 		},
@@ -111,24 +111,24 @@ func TestValidateMinimalJSONRejectsUnexpectedFields(t *testing.T) {
 	}
 }
 
-func TestValidateDefaultJSONRejectsMissingRequiredField(t *testing.T) {
-	err := ValidateDefaultJSON([]byte(`{
-		"metadata": {
-			"application": "seriatim",
-			"version": "dev",
-			"output_schema": "default"
-		}
-	}`))
+func TestValidateIntermediateJSONRejectsMissingRequiredField(t *testing.T) {
+	err := ValidateIntermediateJSON([]byte(`{
+			"metadata": {
+				"application": "seriatim",
+				"version": "dev",
+				"output_schema": "seriatim-intermediate"
+			}
+		}`))
 	assertErrorContains(t, err, "segments")
 }
 
-func TestValidateDefaultJSONRejectsWrongFieldType(t *testing.T) {
-	err := ValidateDefaultJSON([]byte(`{
-		"metadata": {
-			"application": "seriatim",
-			"version": "dev",
-			"output_schema": "default"
-		},
+func TestValidateIntermediateJSONRejectsWrongFieldType(t *testing.T) {
+	err := ValidateIntermediateJSON([]byte(`{
+			"metadata": {
+				"application": "seriatim",
+				"version": "dev",
+				"output_schema": "seriatim-intermediate"
+			},
 		"segments": [
 			{
 				"id": "1",
@@ -142,7 +142,7 @@ func TestValidateDefaultJSONRejectsWrongFieldType(t *testing.T) {
 	assertErrorContains(t, err, "id")
 }
 
-func TestValidateDefaultJSONRejectsUnexpectedFields(t *testing.T) {
+func TestValidateIntermediateJSONRejectsUnexpectedFields(t *testing.T) {
 	tests := []struct {
 		name string
 		json string
@@ -150,7 +150,7 @@ func TestValidateDefaultJSONRejectsUnexpectedFields(t *testing.T) {
 		{
 			name: "top-level overlap groups",
 			json: `{
-				"metadata": {"application": "seriatim", "version": "dev", "output_schema": "default"},
+					"metadata": {"application": "seriatim", "version": "dev", "output_schema": "seriatim-intermediate"},
 				"segments": [],
 				"overlap_groups": []
 			}`,
@@ -158,21 +158,21 @@ func TestValidateDefaultJSONRejectsUnexpectedFields(t *testing.T) {
 		{
 			name: "segment source",
 			json: `{
-				"metadata": {"application": "seriatim", "version": "dev", "output_schema": "default"},
+					"metadata": {"application": "seriatim", "version": "dev", "output_schema": "seriatim-intermediate"},
 				"segments": [{"id": 1, "source": "input.json", "start": 1, "end": 2, "speaker": "Alice", "text": "hello"}]
 			}`,
 		},
 		{
 			name: "segment derived from",
 			json: `{
-				"metadata": {"application": "seriatim", "version": "dev", "output_schema": "default"},
+					"metadata": {"application": "seriatim", "version": "dev", "output_schema": "seriatim-intermediate"},
 				"segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "derived_from": ["input.json#0"]}]
 			}`,
 		},
 		{
 			name: "segment words",
 			json: `{
-				"metadata": {"application": "seriatim", "version": "dev", "output_schema": "default"},
+					"metadata": {"application": "seriatim", "version": "dev", "output_schema": "seriatim-intermediate"},
 				"segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "words": []}]
 			}`,
 		},
@@ -180,7 +180,7 @@ func TestValidateDefaultJSONRejectsUnexpectedFields(t *testing.T) {
 
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
-			err := ValidateDefaultJSON([]byte(test.json))
+			err := ValidateIntermediateJSON([]byte(test.json))
 			assertErrorContains(t, err, "additional properties")
 		})
 	}
@@ -267,7 +267,7 @@ func TestValidateJSONRejectsUnexpectedInternalFields(t *testing.T) {
 	}
 }
 
-func TestValidateDefaultTranscriptRejectsMissingOrNonSequentialIDs(t *testing.T) {
+func TestValidateIntermediateTranscriptRejectsMissingOrNonSequentialIDs(t *testing.T) {
 	tests := []struct {
 		name string
 		ids  []int
@@ -280,10 +280,10 @@ func TestValidateDefaultTranscriptRejectsMissingOrNonSequentialIDs(t *testing.T)
 
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
-			transcript := validDefaultTranscript()
+			transcript := validIntermediateTranscript()
 			transcript.Segments = transcript.Segments[:0]
 			for index, id := range test.ids {
-				transcript.Segments = append(transcript.Segments, DefaultSegment{
+				transcript.Segments = append(transcript.Segments, IntermediateSegment{
 					ID:      id,
 					Start:   float64(index),
 					End:     float64(index) + 1,
@@ -292,18 +292,18 @@ func TestValidateDefaultTranscriptRejectsMissingOrNonSequentialIDs(t *testing.T)
 				})
 			}
 
-			err := ValidateDefaultTranscript(transcript)
+			err := ValidateIntermediateTranscript(transcript)
 			assertErrorContains(t, err, test.want)
 		})
 	}
 }
 
-func TestValidateDefaultTranscriptRejectsInvalidTiming(t *testing.T) {
-	transcript := validDefaultTranscript()
+func TestValidateIntermediateTranscriptRejectsInvalidTiming(t *testing.T) {
+	transcript := validIntermediateTranscript()
 	transcript.Segments[0].Start = 2
 	transcript.Segments[0].End = 1
 
-	err := ValidateDefaultTranscript(transcript)
+	err := ValidateIntermediateTranscript(transcript)
 	assertErrorContains(t, err, "segment 0 has end")
 }
 
@@ -411,7 +411,7 @@ func validMinimalTranscript() MinimalTranscript {
 		Metadata: MinimalMetadata{
 			Application:  "seriatim",
 			Version:      "dev",
-			OutputSchema: "minimal",
+			OutputSchema: "seriatim-minimal",
 		},
 		Segments: []MinimalSegment{
 			{
@@ -425,14 +425,14 @@ func validMinimalTranscript() MinimalTranscript {
 	}
 }
 
-func validDefaultTranscript() DefaultTranscript {
-	return DefaultTranscript{
-		Metadata: DefaultMetadata{
+func validIntermediateTranscript() IntermediateTranscript {
+	return IntermediateTranscript{
+		Metadata: IntermediateMetadata{
 			Application:  "seriatim",
 			Version:      "dev",
-			OutputSchema: "default",
+			OutputSchema: "seriatim-intermediate",
 		},
-		Segments: []DefaultSegment{
+		Segments: []IntermediateSegment{
 			{
 				ID:         1,
 				Start:      1,