narratio/docs/internal/stage-trim.md

# Stage: trim

## Purpose

Produce a final-trimmed transcript. By default, the stage generates bounds and
applies a bounds-driven trim.

## Inputs

- `transcripts/final.json`

## Outputs

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

## Key Behavior

When `trim.enabled=true`:
- runs Scriptorium bounds artifact generation;
- optionally runs render-debug output generation;
- validates bounds payload against transcript;
- derives keep selector;
- either copies unchanged transcript or runs Seriatim trim;
- validates trimmed transcript and materializes bounds output.

When `trim.enabled=false`:
- copies normalized transcript to trimmed output.

## Invariants

- normalized transcript is required input.
- bounds output exists only in enabled trim path.
- render-debug output is diagnostic and not a declared stage output.

## Resume Semantics

The versioned semantic fingerprint covers enablement, the bounds prompt and
profile identifiers, the Scriptorium configuration identity, transcript input
name, sticky session variable, bounds and trimmed output identities, and the
Seriatim trim operation. Diagnostic bounds rendering, diagnostic output paths,
timeouts, executable paths, and optional reports are operational and do not
invalidate the canonical trimmed transcript.

Narratio cannot inspect prompt, profile, or configuration content that
Scriptorium or Seriatim privately resolves behind a stable identifier. Force
`trim` after changing such private content without changing its identifier.

## Related Contracts And Tests

- [Scriptorium](../integrations/scriptorium.md) owns bounds generation and
  debug-render subprocess behavior.
- [Seriatim](../integrations/seriatim.md) owns transcript trimming behavior.
- [Configuration](../config.md#pipeline) owns trim fields and defaults.
- Implementation and tests: `internal/stage/trim.go`,
  `internal/stage/trim_test.go`,
  `internal/stage/semantic_contracts_refinement.go`