audita/docs/integrations/subprocess.md

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 and docs/config.md.

Recommended Invocation

Use explicit output and report paths for machine workflows:

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.