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`
- optional `artifacts/audita.report.json`

## Key Behavior

- resolves base transcript only from verified merge manifest output evidence.
- invokes an Audita runner configured with static model/runtime options; the
  invocation supplies paths and modules.
- validates processed transcript structure (`segments` array required).
- validates optional report JSON.
- materializes canonical outputs; records logs/generated config and adapter metadata.

## Invariants

- polished transcript schema validation is mandatory.
- report output is config-gated.

## 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 credential environment name are operational and do not invalidate a
successful result.

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`