narratio/docs/internal/stage-polish.md

# Stage: polish

## Purpose

Run Audita polishing on base transcript and produce polished transcript.

## Inputs

- `transcripts/base.json`
- `inputs/glossary.yml`

## Outputs

- `transcripts/polished.json`

The transcript is the only canonical output. Available `errors.yml`,
`recoveries.yml`, and `report.md` remain beside the run-local transcript and
are recorded as diagnostics, not artifact outputs.

## Key Behavior

- resolves base transcript only from verified merge manifest output evidence.
- invokes an Audita v2 runner with external configuration selectors and
  explicitly forwarded provider credentials; the invocation supplies paths.
- validates processed transcript structure (`segments` array required).
- validates reported diagnostic paths against the three fixed adjacent names.
- materializes only the canonical transcript; records available reports with
  stdout/stderr logs, generated invocation, and safe adapter metadata.

## Invariants

- polished transcript schema validation is mandatory.
- reports are optional diagnostics; Audita's external configuration may disable
  them. A failed invocation never promotes an incidental transcript.

## Resume Semantics

The versioned semantic fingerprint covers the Audita service endpoint, model,
validation model, module set, transcript description, output schema, selected
external configuration path, and canonical polished-transcript identity. Module
ordering is normalized because the configured modules form a set. Audita's
executable, timeouts, concurrency, report and debug behavior, work retention,
and resolved credential value are operational and do not invalidate a
successful result. The public credential reference name may participate in
configuration provenance but never exposes its resolved value.

Narratio can fingerprint a selected model, module, or configuration identifier,
but it cannot inspect content that Audita privately resolves behind that stable
identifier. Force `polish` after changing such private content without changing
its identifier.

## Related Contracts And Tests

- [Audita](../integrations/audita.md) owns subprocess, validation, and failure
  semantics.
- [Configuration](../config.md#pipeline) owns operator-selected Audita values.
- Implementation and tests: `internal/stage/polish.go`,
  `internal/stage/polish_test.go`,
  `internal/stage/semantic_contracts_refinement.go`