seriatim/docs/internal/artifacts.md

Artifact Internals

Purpose

Describes public artifact conversion and validation internals for merge output, trim, and normalize.

Artifact contracts

Public contracts live in schema/:

• full: schema.Transcript
• intermediate: schema.IntermediateTranscript
• minimal: schema.MinimalTranscript

Machine-readable schemas:

• schema/full-output.schema.json
• schema/intermediate-output.schema.json
• schema/minimal-output.schema.json

Schema selection

Merge pipeline conversion uses internal/artifact.SelectedFromMerged:

• seriatim-full -> artifact.FromMerged
• seriatim-intermediate -> artifact.IntermediateFromMerged
• seriatim-minimal -> artifact.MinimalFromMerged

Unknown/empty selection falls back to intermediate conversion.

Merge conversion behavior

internal/artifact converts model.MergedTranscript to public contracts:

• full schema preserves source/provenance, overlap groups, and metadata module lists.
• intermediate schema emits segment timing/text/speaker with optional categories and compact metadata.
• minimal schema emits compact segment timing/text/speaker and compact metadata.

Validation behavior

schema/output.go validates both structure and semantics:

• embedded JSON Schema validation via jsonschema/v6
• semantic checks for sequential segment IDs starting at 1
• semantic checks for non-inverted segment timing (end >= start)
• full schema overlap-group timing checks (group.end >= group.start)

Trim internals

internal/trim is artifact-level projection, not merge reprocessing.

Core flow:

1. Parse selector (internal/trim/selector.go).
2. Parse input artifact and detect schema (ParseArtifactJSON).
3. Apply keep/remove projection with sequential ID renumbering.
4. Recompute overlap groups only for full-schema artifacts.
5. Optionally convert output schema when supported.
6. Validate output artifact before write.

Schema-conversion limits:

• full -> intermediate/minimal supported.
• intermediate -> minimal supported.
• minimal -> intermediate supported.
• intermediate/minimal -> full is rejected.

Trim invariants:

• selected IDs must exist in input.
• input IDs must be positive, unique, sequential.
• retained order follows input transcript order.
• output IDs are reassigned to 1..N.

Run layer (run.go):

• executes end-to-end trim orchestration from validated config
• writes output JSON
• optionally writes report JSON with trim-audit

Normalize internals

internal/normalize canonicalizes transcript-like JSON input into a selected public schema.

Parse layer (parse.go):

• accepts object-with-segments or bare segment array
• repairs missing timing deterministically
• swaps inverted timing
• fills missing/blank speaker with Unknown_Speaker
• drops missing/blank text segments

Build layer (build.go):

• sorts deterministically by (start, end, input_index, speaker)
• reassigns output IDs sequentially
• builds minimal/intermediate/full output shape
• validates selected output schema before write

Run layer (normalize.go):

• writes output JSON
• optionally writes report with normalize-audit

Normalize invariant:

• report events do not embed transcript text.

Boundaries

• CLI flag semantics belong to docs/cli.md.
• Runtime config/env surfaces belong to docs/config.md.
• This doc describes internal conversion/validation behavior only.

Failure behavior

Representative failure classes:

• malformed or unsupported input JSON shape
• schema validation failure for parsed artifact or built output
• unsupported schema conversion path (trim)
• selector or input-ID consistency errors (trim)
• output/report file write failures from command paths

Tests to inspect before changes

• schema/output_test.go
• internal/artifact/transcript_test.go
• internal/trim/selector_test.go
• internal/trim/artifact_test.go
• internal/trim/apply_test.go
• internal/normalize/parse_test.go
• internal/cli/trim_test.go
• internal/cli/normalize_test.go

Invariants

• Public artifacts are validated through schema before acceptance.
• Segment IDs in emitted artifacts are sequential and deterministic.
• Internal-only fields are not emitted in minimal/intermediate contracts.
• Trim and normalize stay artifact-level and do not execute merge modules.