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 handles artifact-level projection and does not execute merge pipeline modules.

Run layer (run.go):

1. Parse selector from validated config.
2. Read and parse input artifact JSON.
3. Apply trim projection through schema-aware artifact handling.
4. Resolve output schema (preserve input schema unless overridden).
5. Validate output artifact.
6. Write output JSON.
7. Optionally write report JSON with trim-audit.

Apply layer (apply.go):

• one shared projection policy for selector mode, input ID validation, selected ID existence checks, keep/remove filtering, removed IDs, and old-to-new ID mappings
• schema-specific segment reconstruction for full/intermediate/minimal outputs
• overlap-group recomputation only for full-schema outputs

Artifact layer (artifact.go):

• schema detection for full/intermediate/minimal artifacts
• schema-preserving trim application
• supported schema conversions:
  • full -> intermediate/minimal
  • intermediate -> minimal
  • minimal -> intermediate
• rejected conversion:
  • intermediate/minimal -> full

Trim invariants:

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

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.