seriatim/docs/internal/artifacts.md

Artifact Internals

Purpose

Describes implemented artifact parsing, conversion, validation, and render-model normalization internals.

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

Shared output-artifact parser

internal/artifact/output_artifact.go provides schema-aware parsing for existing seriatim output artifacts.

Behavior:

• accepts only valid full, intermediate, or minimal seriatim output artifacts
• validates through schema semantic + JSON schema checks
• rejects malformed JSON
• rejects raw WhisperX-style JSON and other non-seriatim shapes

Consumers:

• internal/trim artifact-level trim flow
• internal/render artifact-level render flow

Merge conversion behavior

internal/artifact/transcript.go 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

Schema selection uses internal/artifact.SelectedFromMerged:

• seriatim-full -> artifact.FromMerged
• seriatim-intermediate -> artifact.IntermediateFromMerged
• seriatim-minimal -> artifact.MinimalFromMerged
• unknown/empty -> intermediate fallback

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 conversion layer (artifact.go):

• 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

Render internals

internal/render is an artifact-level, downstream-only renderer.

Model normalization (normalize.go):

• converts full/intermediate/minimal artifacts into a common render model
• preserves segment order and segment IDs
• normalizes per-segment fields to ID, start, end, speaker, text, categories
• emits empty categories slice when categories are absent in input

Renderer registry (registry.go):

• resolves renderers by public format name
• currently registers markdown

Markdown renderer (markdown.go):

• writes title header # {title}
• renders optional [HH:MM:SS–HH:MM:SS] timestamps
• renders optional [#id] segment references
• renders **speaker:** text
• italicizes text when categories include background, backchannel, or filler
• ignores unknown categories
• optionally includes metadata summary block

Run layer (run.go):

1. Read input artifact JSON.
2. Parse via shared output-artifact parser.
3. Normalize to render model.
4. Resolve renderer by --format.
5. Render text output.
6. Write output file.

Render invariants:

• does not run merge/trim/normalize modules
• does not expose report output
• deterministic for identical input artifact and render flags

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)

Boundaries

• CLI flag semantics belong to docs/cli.md.
• Runtime config/env surfaces belong to docs/config.md.
• This document 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)
• unsupported renderer format (render)
• output/report file write failures from command paths

Tests to inspect before changes

• schema/output_test.go
• internal/artifact/transcript_test.go
• internal/artifact/output_artifact_test.go
• internal/trim/selector_test.go
• internal/trim/artifact_test.go
• internal/trim/apply_test.go
• internal/normalize/parse_test.go
• internal/render/normalize_test.go
• internal/render/markdown_test.go
• internal/render/registry_test.go
• internal/cli/trim_test.go
• internal/cli/normalize_test.go
• internal/cli/render_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, normalize, and render stay artifact-level and do not execute merge modules.