Audit des traces

La trace d’exécution enregistre run.air_digest avant de démarrer : SHA-256 du document AIR JSON canonique complet (clés triées récursivement, ordre des tableaux conservé, UTF-8). L’audit compare cet engagement à l’AIR fourni, constantes, expressions, autorisations et références source incluses. Une modification produit TraceAirDigestMismatch et interdit l’export, même avec un nouveau manifest d’audit. Une trace sans engagement est refusée ; les preuves archivées ne sont pas requalifiées rétroactivement. Ce mécanisme n’est pas une signature contre une réécriture conjointe de la trace et de l’AIR.

Si --trace-out est demandé et que l’admission échoue, la CLI enregistre un unique événement admission_refused, avec des identifiants contrôlés stage et code, sans entrée brute, message d’exception ou secret. run.admission vaut refused et les champs d’identité AIR sont nuls. L’audit signale AdmissionRefused : il s’agit d’une preuve de non-exécution, pas d’un run réussi ni d’une correspondance AIR.

L’audit des traces relie une trace Touba aux artefacts qui l’expliquent : AIR, source et manifest. Il produit un rapport de validation et, si les checks sont satisfaits, un export borné.

Ce mécanisme sert à répondre à des questions pratiques :

• la trace correspond-elle au run attendu ;
• l’AIR et la trace parlent-ils du même module ;
• les références source sont-elles cohérentes avec le fichier fourni ;
• les artefacts ont-ils les mêmes digests que ceux déclarés ;
• la politique de redaction choisie refuse-t-elle les fuites évidentes.

L’audit des traces constitue une couche de preuve d’ingénierie. Signature, horodatage légal, stockage immuable et attestations de conformité relèvent de contrôles organisationnels séparés.

Commande minimale

Terminal

touba audit --trace trace.json

Cette commande lit la trace fournie et produit un rapport texte.

Sortie attendue en cas de trace cohérente :

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

Avec AIR, source et manifest

Terminal

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

Touba vérifie alors plus de liens :

Artefact	Ce qui est vérifié
Trace	version, run, séquence d’événements et fuites évidentes
AIR	version et cohérence module/trace
Source	références source portées par les artefacts fournis
Manifest	version et absence de champs sensibles établissables

Le runtime, les handlers et les secrets ne sont pas exécutés pendant cet audit.

Plusieurs modules et rapport JSON

Répétez --source pour fournir le module d'entrée et tous les modules référencés par l'AIR assemblé. Aucun répertoire n'est parcouru implicitement :

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 exige le suffixe .trace-audit-report.json. Chaque référence doit correspondre à un seul fichier fourni ; les sources manquantes, étrangères, répétées ou ambiguës sont refusées. Sans --source, le contrôle source_refs reste non effectué.

Le manifeste scelle la collection triée avec sources_digest ; l'export inclut artifacts.sources, liste de {source_id, text}. L'ordre des options ne change pas ce digest. L'audit vérifie les références et l'intégrité déclarée, pas une recompilation équivalente des sources. Conservez le scellé initial pour détecter une altération.

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

L’export est écrit seulement si le rapport est ok.

Il contient :

• un manifeste d’audit trace-audit-v1 ;
• un rapport trace-audit-validation-v1 ;
• les artefacts explicitement fournis ;
• des digests sha256.

Lire l’export

Terminal

touba inspect trace-audit.export.json

Ou :

Terminal

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

Sortie attendue :

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 résume l’artefact d’audit. Il ne relance pas le programme, ne lit pas de secret et ne relit pas les handlers.

Timeline de revue

Pour une interface de revue ou une lecture rapide, touba audit peut écrire une timeline compacte :

Terminal

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

Le fichier touba-trace-timeline-v1 contient les événements ordonnés, leur type, une sévérité d’affichage, une référence source et un marqueur de redaction. Il ne contient pas les prompts complets, payloads bruts, contenus mémoire ni valeurs de secrets. Quand une trace minimale n’a pas d’horodatage par événement, la timeline conserve l’ordre sous la forme sequence:n.

La timeline est produite seulement si le rapport d’audit est ok. En cas de diagnostic, le rapport TA-1 reste l’artefact à lire en premier.

Exporter vers OpenTelemetry

Pour brancher une trace Touba sur un stack d’observabilité, produire une projection OpenTelemetry depuis la trace native :

Terminal

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

La trace native reste l’artefact d’audit Touba. L’export OpenTelemetry rend les événements exploitables comme spans GenAI (invoke_workflow, invoke_agent, execute_tool) par des outils externes, sans relancer le programme, sans lire les handlers et sans exporter prompt complet, payload brut, secret, résultat de tool, observation brute ou chemin local.

Classes de rétention

Classe	Usage prévu
local_debug	essai local court
project_audit	conservation projet limitée
security_review	revue technique ciblée
regulated_export	export destiné à une revue encadrée

Ces classes sont déclaratives dans Touba. Elles structurent l’intention de rétention ; l’effacement et la politique organisationnelle restent pilotés par l’environnement.

Politiques de redaction

Politique	Rôle
no_secrets	refuse les champs de secrets évidents
no_secrets_no_raw_prompts	refuse aussi les prompts bruts évidents
no_secrets_no_raw_prompts_no_memory_content	refuse aussi les contenus mémoire bruts évidents

La redaction de l’audit des traces (TA-1) est un contrôle sur les artefacts fournis. Elle rend la frontière d’audit explicite et répétable.

Périmètre d’audit

La valeur de l’audit des traces (TA-1) est de rendre l’audit reproductible : trace, AIR, source, manifest, digests, rétention et redaction deviennent des artefacts explicites.

La conformité réglementaire, la preuve juridique, les signatures cryptographiques, l’horodatage légal, le stockage immuable, la sandbox de handlers, la lecture de backends externes et la détection complète d’empoisonnement mémoire relèvent de couches de preuve et de plateforme séparées.