Trace Audit

An execution trace records run.air_digest before execution: SHA-256 of the complete canonical AIR JSON (recursively sorted object keys, original array order, UTF-8). Audit compares this commitment with the supplied AIR, including constants, expressions, authority and source references. Changes produce TraceAirDigestMismatch and prevent export, even with a new audit manifest. A trace without the commitment is refused; archived evidence is not retroactively qualified. This is not a signature against joint rewriting of the trace and AIR.

When --trace-out is requested and admission fails, the CLI records a single admission_refused event with controlled stage and code identifiers, without raw input, exception text or secrets. run.admission is refused, and AIR identity fields are null. Audit reports AdmissionRefused: this proves non-execution, not a successful run or an AIR match.

Trace audit connects a Touba trace to the artifacts that explain it: AIR, source, and manifest. It produces a validation report and, when checks pass, a bounded export.

This mechanism answers practical questions:

• does the trace correspond to the expected run;
• do AIR and trace describe the same module;
• are source references coherent with the supplied file;
• do artifacts have the same digests as the declared values;
• does the selected redaction policy reject obvious leaks.

Trace audit is an engineering evidence layer. Legal timestamping, cryptographic signatures, immutable storage, and compliance attestations are separate organizational controls.

Minimal Command

Terminal

touba audit --trace trace.json

This command reads the supplied trace and produces a textual report.

Expected output for a coherent trace:

Touba Trace Audit trace-audit-validation-v1
Status ok
Run run-...
Retention local_debug
Redaction no_secrets_no_raw_prompts_no_memory_content
Diagnostics ok

With AIR, Source, and Manifest

Terminal

touba audit \
  --trace trace.json \
  --air program.air.json \
  --source source.tb \
  --manifest touba.manifest.json

Touba then verifies more links:

Artifact	What is verified
Trace	version, run, event sequence, and obvious leaks
AIR	version and module/trace coherence
Source	source references carried by supplied artifacts
Manifest	version and absence of identifiable sensitive fields

The runtime, handlers, and secrets are not executed during this audit.

Multiple modules and JSON reports

Repeat --source for the entry module and every module referenced by the assembled AIR. No directory is scanned implicitly:

touba audit --trace run.trace.json --air support.air.json \
  --source src/app/support.tb --source src/app/mail.tb \
  --report-out run.trace-audit-report.json

--report-out requires the .trace-audit-report.json suffix. Each reference must match exactly one supplied file; missing, unrelated, duplicate or ambiguous sources are refused. Without --source, source_refs remains unchecked.

The manifest seals the sorted collection with sources_digest; the export includes artifacts.sources, a list of {source_id, text}. Option order does not change this digest. Audit checks references and declared integrity, not equivalent recompilation of sources. Keep the initial seal to detect tampering.

Export

Terminal

touba audit \
  --trace trace.json \
  --air program.air.json \
  --source source.tb \
  --manifest touba.manifest.json \
  --retention-class project_audit \
  --redaction-policy no_secrets_no_raw_prompts_no_memory_content \
  --export trace-audit.export.json

The export is written only when the report is ok.

It contains:

• a trace-audit-v1 audit manifest;
• a trace-audit-validation-v1 report;
• the explicitly supplied artifacts;
• sha256 digests.

Read the Export

Terminal

touba inspect trace-audit.export.json

Or:

Terminal

touba inspect --trace-audit trace-audit.export.json

Expected output:

Trace audit trace-audit-export-v1-local
- kind=trace_audit_export run=run-... status=ok
- retention=project_audit redaction=no_secrets_no_raw_prompts_no_memory_content

inspect summarizes the audit artifact. It does not rerun the program, read secrets, or re-read handlers.

Export to OpenTelemetry

To connect a Touba trace to an observability stack, produce an OpenTelemetry projection from the native trace:

Terminal

touba inspect trace.json --otel-out trace.otel.json

The native trace remains the Touba audit artifact. The OpenTelemetry export makes events usable as GenAI spans (invoke_workflow, invoke_agent, execute_tool) by external tools, without rerunning the program, reading handlers, or exporting full prompts, raw payloads, secrets, tool results, raw observations, or local paths.

Retention Classes

Class	Intended use
local_debug	short local test
project_audit	limited project retention
security_review	focused technical review
regulated_export	export intended for a governed review

These classes are declarative in Touba. They do not delete files automatically and do not replace an organizational retention policy.

Redaction Policies

Policy	Role
no_secrets	rejects obvious secret fields
no_secrets_no_raw_prompts	also rejects obvious raw prompts
no_secrets_no_raw_prompts_no_memory_content	also rejects obvious raw memory content

Trace audit redaction (TA-1) is a control over the supplied artifacts. It makes the audit boundary explicit and repeatable.

Audit Scope

The value of trace audit (TA-1) is reproducibility: trace, AIR, source, manifest, digests, retention, and redaction become explicit artifacts.

Regulatory compliance, legal proof, cryptographic signatures, legal timestamping, immutable storage, handler sandboxing, external backend reading, and complete memory-poisoning detection are separate evidence and platform layers.