audita/docs/subprocess-operations.md

Audita Subprocess Operations

This document describes how parent processes should invoke audita process safely in production orchestration.

Recommended command form

Use explicit file outputs for orchestrated runs:

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

Recommended additions:

• --config <path> to select an explicit versioned config file.
• --output-schema <bare-segments|audita-v1> to select transcript output shape.
• --work-dir <dir> to control diagnostics location.
• --work-dir-retention <always|auto|never> to control retained run directories.
• --total-llm-concurrency, --proposal-llm-concurrency, and --validation-llm-concurrency when orchestration needs explicit LLM throughput controls.
• --modules ... only when intentionally overriding the default full sequence.

Stdout behavior

• With --output: stdout is expected to be empty on success.
• Without --output: stdout contains transcript JSON only on success.
• Report JSON is never written to stdout.

Stderr behavior

• Success path should be quiet or minimal human-readable logs.
• Failure path writes concise human-readable errors.
• When a diagnostics run directory exists, failure stderr includes its path.
• Prompt/response diagnostic payloads are not streamed to stderr.

Output file behavior

• --output writes transcript JSON in the selected output schema to the provided path.
• Output write failures return nonzero and surface actionable errors.
• The command does not silently ignore output write errors.

Report JSON behavior

• --report-json writes a machine-readable process report to the requested path.
• Run-directory report.json is written independently under diagnostics.
• Best-effort failure reports are emitted when possible without masking the primary failure.
• Report write failures return nonzero with clear stderr messaging.

Diagnostics directory behavior

• Each run creates (when possible) a per-run diagnostics directory.
• Typical artifacts include transcript, normalization, chunking, invocation, effective config, LLM diagnostics, report.json, and error.log on failure.
• Failed runs retain diagnostics.
• Under auto retention, successful runs with skipped/rejected corrections are retained; clean successful runs may be removed.

Exit codes

• 0: success.
• Nonzero: failure (input/schema/config/module/LLM/runtime/output/report/diagnostics errors).

Treat any nonzero as a failed subprocess invocation.

Timeout and cancellation

• Runtime operations propagate context cancellation and request timeouts through LLM/scheduler paths.
• On cancellation or timeout, the process exits nonzero and should not hang.
• If diagnostics were initialized before failure, failure artifacts remain available for debugging.

Secret redaction expectations

API keys and configured secret values are redacted from:

• reports (--report-json and run-dir report.json);
• diagnostics artifacts (including effective config and LLM interaction artifacts);
• surfaced adapter/runtime errors;
• test fixtures and regression outputs.

Parent-process logs should still avoid printing raw environment variables.

Parent-process pipe guidance

To avoid deadlocks in orchestrators:

• always read both stdout and stderr concurrently when invoking as a subprocess;
• prefer file outputs (--output, --report-json) for machine workflows;
• treat stderr as human-readable diagnostics, not structured data;
• parse structured results from output/report files.

For Go callers, prefer exec.CommandContext with explicit timeout/cancellation and buffered/streamed readers for both pipes.