narratio/docs/internal/stage-trim.md

Stage: trim

Purpose

Optionally trim the final transcript to session bounds; always produce a durable final-trimmed transcript.

Inputs and Outputs

Inputs:

• transcripts/final.json

Outputs:

• transcripts/final.trimmed.json (or configured trim output path)
• when trim enabled: artifacts/session_bounds.json

Boundaries

Owns:

• Trim-enabled switch behavior
• Bounds generation via Scriptorium artifact run
• Bounds validation against final transcript
• Keep-selector derivation and Seriatim trim invocation
• Copy-through behavior when disabled or bounds indicate unchanged transcript

Does not own:

• Upstream normalization
• Downstream artifact analysis

Config Fields Used

• session.session_id
• session.campaign
• pipeline.workspace.root
• pipeline.trim.enabled
• pipeline.trim.output_path
• pipeline.trim.bounds.prompt_id
• pipeline.trim.bounds.profile_id
• pipeline.trim.bounds.timeout
• pipeline.trim.bounds.output_path
• pipeline.trim.bounds.transcript_input_name
• pipeline.trim.bounds.render_debug
• pipeline.trim.bounds.render_output_path
• pipeline.seriatim.binary
• pipeline.seriatim.timeout
• pipeline.scriptorium.binary
• pipeline.scriptorium.config_path
• pipeline.scriptorium.timeout

External Adapters Used

• Scriptorium adapter:
  • optional RenderArtifact for bounds debug render
  • RunArtifact for bounds output
• Seriatim adapter:
  • Trim when bounds indicate trimming is required

State and Manifest Behavior

• Reads final transcript from normalize manifest outputs when available; falls back to canonical path.
• Uses run-local outputs/logs/reports/config/scratch paths when run layout is enabled.
• Materializes canonical final-trimmed transcript and session bounds when trim is enabled.
• Records bounds diagnostics, trim action, keep selector, and adapter metadata.

Skip and Resume Behavior

• Runner-level skip applies when already succeeded and not forced.
• Forced reruns can stale downstream succeeded stages.
• When trim.enabled=false, stage still succeeds by copying final to final-trimmed output.

Failure Behavior

• Fails on missing/invalid final transcript.
• With trim enabled, fails on missing adapters/config, bounds generation/validation errors, invalid bounds JSON, invalid range/segment ids, trim adapter failures, or invalid final-trimmed output.

Tests to Inspect Before Changing

• internal/stage/trim_test.go
• internal/adapters/scriptorium/subprocess_test.go
• internal/adapters/seriatim/subprocess_test.go

Architectural Invariants

• Trim never falls back to polished transcript; final transcript is required input.
• session_bounds output exists only for enabled trim path.
• Render-debug artifacts are diagnostics and not declared stage outputs.