narratio/docs/internal/stage-render.md

Stage: render

Purpose

Render Markdown transcript artifacts from normalized JSON transcripts via Seriatim.

Inputs

• narratio.transcript.final (transcripts/final.json)
• narratio.transcript.final_trimmed (transcripts/final.trimmed.json)

Outputs

• narratio.transcript.final_markdown -> transcripts/final.md
• narratio.transcript.final_trimmed_markdown -> transcripts/final.trimmed.md

Key Behavior

• uses pipeline.render settings (enabled/format/title/booleans).
• resolves inputs manifest-first, then canonical fallback.
• writes run-local outputs first, then materializes canonical session outputs.
• records input provenance, output paths, adapter metadata, logs, and generated config refs.
• when pipeline.render.enabled=false, completes successfully with no outputs and records explanatory metadata. This is not an explicit self-skip: both manifests record success, and enabling render later requires a forced run.

Failure Semantics

• missing normalized input fails with normalize rerun guidance.
• missing trimmed input fails with trim rerun guidance.
• adapter/subprocess failure fails stage.
• empty render output files fail validation.

Invariants

• only format: markdown is supported.
• render stage owns production of built-in Markdown transcript sources.

Related Contracts And Tests

• Seriatim owns render subprocess behavior.
• Configuration owns render fields and defaults.
• Implementation and tests: internal/stage/render.go, internal/stage/render_test.go