audita/docs/internal/pipeline.md

# Audita Internal Pipeline

The [input contract](../integrations/transcript-glossary-files.md) owns input
formats; [configuration](../config.md) owns settings; the
[output contract](../integrations/output-files.md) owns serialized results.

1. CLI loads resolved configuration and transcript input. Preflight checks all
   selected glossary views and roles before the output session prepares resources.
   Transcript segments then enter canonical normalization.
2. Normalization sorts and merges segments using configured time and token
   limits, reassigning IDs where needed.
3. The runner partitions the normalized transcript exactly once before its
   module loop. Initial section identity, segment membership, and token
   estimates stay fixed while text evolves.
4. Module instances execute in configured order. Sections may propose
   concurrently, but proposal indices follow section order and response order.
5. Deterministic validators precede LLM-backed validators. Every submitted
   candidate receives one decision per validator on a normal return. Fatal returns
   may preserve a checked subset of completed decisions as diagnostic evidence.
   Recoverable failed batches mark their candidates unavailable; successful
   survivors continue through all required validators.
6. Actionable rejections can enter independent section-local repair branches.
   Each revision is mapped to the original section and revalidated from the
   start. Withdrawal, exhaustion, and recoverable failures finish the branch
   without affecting independent approvals.
7. Only fully approved proposals reach application. Corrections apply in
   proposal-index order within their owning section. Existing replacement
   policies and apply-time safety checks resolve stale conflicts.
8. CLI encodes the final transcript and publishes active files through the
   output session. `framework/processreport` builds one snapshot for YAML,
   Markdown, and CLI totals. Debug evidence is captured separately when enabled.

`runner.Run` returns the final working transcript, initial section inventory,
explicit `not_started`/`interrupted`/`completed` work units, compact model
operation outcomes, and per-module results. Candidate payloads are retained
in the returned output only when debug capture is requested. A work unit can
complete with model errors and applied corrections. Recoverable model failures
never trigger shared cancellation. Fatal setup, internal, application, or
parent-cancellation errors cancel peers, join workers, and preserve earlier
committed module text for partial reports; no completed transcript is published.

Required transcript/report write failures are fatal. Optional debug writes
report safely to stderr without changing decisions or exit status. See
[operations](../operations.md) for file placement and failure handling, and
[architecture policy](../policy/architecture.md#correction-and-concurrency-invariants)
for invariants.

Key tests: `internal/framework/runner/*_test.go`,
`internal/framework/validators/*_test.go`, and
`cmd/audita/main_integration_test.go`.