# Subprocess Integration

## Scope

This document describes how a parent process should invoke Audita as a subprocess.

It covers:
- invocation shape;
- stdout/stderr behavior;
- output/report file behavior;
- diagnostics and exit behavior.

For full CLI and config references, see [`docs/cli.md`](../cli.md) and [`docs/config.md`](../config.md).

## Recommended Invocation

Use explicit output and report paths for machine workflows:

```sh
audita process <transcript.json> \
  --glossary <glossary.yaml> \
  --output <output-transcript.json> \
  --report-json <report.json>
```

Optional commonly used flags:
- `--config <path>`
- `--output-schema <bare-segments|audita-v1>`
- `--work-dir <dir>`
- `--work-dir-retention <always|auto|never>`
- `--transcript-description <text>`

## Stdout Contract

On success:
- with `--output`: stdout is expected to be empty;
- without `--output`: stdout contains transcript JSON only.

`--report-json` output is never written to stdout.

## Stderr Contract

Stderr is human-readable status/error output.

On failures:
- stderr includes a concise top-level error;
- when diagnostics are initialized, stderr includes diagnostics directory path.

Do not treat stderr as a machine-stable JSON channel.

## Output and Report File Contract

Transcript output:
- `--output` writes corrected transcript JSON to the provided path;
- output write failures return nonzero.

Report output:
- `--report-json` writes machine-readable process report JSON to the provided path;
- run diagnostics also attempt to write their own `report.json`;
- report write failures return nonzero;
- on failure paths, report writing is best-effort and does not mask the primary run error.

## Diagnostics Contract

When run-directory initialization succeeds, per-run diagnostics artifacts are written under the configured work directory.

Typical artifacts include:
- `source-transcript.json`
- `source-transcript-parsed.json`
- `normalized-transcript.json`
- `normalization-summary.json`
- `chunking-summary.json`
- `invocation.json`
- `effective-config.json`
- `utilization-diagnostics.json`
- `correction-ledger.json`
- `report.json`
- `error.log` (failure)

Retention behavior is controlled by `--work-dir-retention` / config.

## Exit Behavior

Exit codes:
- `0`: success;
- `1`: runtime processing/output/report failure;
- `2`: CLI usage or configuration input error.

Treat any nonzero as subprocess failure.

## Parent-Process Guidance

For reliable orchestration:
- read stdout and stderr concurrently to avoid pipe blocking;
- prefer `--output` and `--report-json` for machine parsing;
- use timeout/cancellation in the parent process;
- inspect diagnostics path and `report.json`/`error.log` on failure.

For input file contracts, see [`docs/integrations/transcript-glossary-files.md`](transcript-glossary-files.md).