2.8 KiB
Subprocess Integration
This guide explains how a parent process can invoke Audita and consume its results. The CLI reference owns command syntax, streams, and exit semantics; configuration owns discovery and precedence.
Invocation
Use an argument array with the transcript path and required glossary argument,
following the process examples. For machine workflows,
select an explicit transcript file destination and a configuration path. Reports
go beside the transcript unless an explicit --report-dir selects another
directory. For stdout output, reports use the effective reporting.stdout_dir
(defaulting to the invocation working directory), including a --report-dir
override. A config-file or overlay value for reporting.stdout_dir alone does
not redirect file-output reports. --work-dir selects a debug root, while
configuration or --debug enables capture; the path flag alone does not.
Supplying a configuration path also makes file selection predictable; only
explicitly referenced credential variables are read from the environment.
Resolve the executable deliberately and set the child's working directory so relative input/output paths and reported artifact paths have a known base. Read stdout and stderr concurrently to avoid pipe blocking, and impose timeout or cancellation in the parent process when needed.
Result Handling
Interpret the exit result according to the
CLI output and exit contract.
Consume transcript/report data through the
output-file contract, and treat stderr as human-readable detail.
The three reports may be absent after early configuration or destination
failures. After initialization, failed reports can describe invalid input or
partial processing and use the same selected report directory as successful
runs. Exit 0 can include recoverable model errors and applied
corrections; inspect errors.yml and recoveries.yml for those outcomes. A
transcript may have been written before a later required report failure, so
the file alone does not prove completion.
If processing fails, preserve available evidence and follow
operations recovery.
Ordinary reports are independent of optional retained debug evidence. Parent
cancellation reaches the child through its context; Audita joins workers and
attempts failed-status report finalization before exiting. Uncatchable
termination can leave in_progress reports. Neither the existence of an output
file nor a debug directory alone establishes successful completion.