audita/docs/internal/pipeline.md

Audita Internal Pipeline

Scope

This document describes processing collaborators and state transitions. External input definitions belong to the input-file contract, settings to configuration, and serialized results to the output-file contract.

Inputs

Pipeline inputs are:

• effective config (internal/core/config);
• transcript JSON (internal/core/schema);
• glossary YAML (internal/core/schema).

Pipeline Phases

1. Input loading: CLI filesystem adapters read inputs; schema parsing produces source transcript and glossary objects. Source segments are converted to the canonical transcript shape before normalization.
2. Normalization: the normalizer sorts and merges segments using its configured time/token rules, reassigns IDs, and produces summary counters.
3. Chunking: the chunker partitions the normalized transcript and returns sections and token estimates, or fails when constraints are impossible.
4. Proposal generation: the runner executes configured module instances in sequence. Sections can generate proposals concurrently; results are collected for deterministic indexing.
5. Validation: deterministic validators run before LLM-backed validators. LLM validation is batched by prompt budget; candidate decisions feed application.
6. Application: internal/framework/proposals clones transcript state and applies approved proposals in index order through replacement-policy checks.
7. Serialization and reporting: the CLI encodes the final transcript, maps runner output into reports, writes artifacts, and delegates retention to diagnostics. See report assembly.

Runner Outputs

runner.Run returns:

• final transcript;
• per-module results.

CLI/reporting then map these results into process reports and diagnostics artifacts. PromptKit execution observations are collected at the role-client boundary for the new report summary.

Failure Behavior

CLI orchestration labels failures at the phase boundary. Runner execution failures can return completed or partial module results, which report assembly preserves. Report fields define how consumers see these outcomes; CLI semantics define streams and exits. Diagnostic write failures do not always abort processing.

Ordering and State

The runner mutates its working transcript between module instances, after collecting section results and validating proposals. Proposal indexes follow section order; reports are derived from actual run results. Global requirements are owned by the architecture policy.

Key Tests

• internal/framework/runner/runner_test.go
• internal/framework/proposal_generation/*_test.go
• cmd/audita/main_integration_test.go