Tutoriel - Auditer une trace

Objectif : produire une trace, la relier à l’AIR et au source, puis générer un rapport d’audit.

L’audit des traces (TA-1) sert à vérifier la cohérence d’un run. Ce n’est pas une preuve juridique, une signature cryptographique ou une conformité automatique.

Ce que vous allez tester

Étape	Résultat attendu
Compiler	un AIR explicite
Exécuter	une trace
Auditer	un rapport ok ou des diagnostics
Exporter	un export borné si le rapport est ok
Inspecter	un résumé lisible sans relancer le programme

1. Créer un programme simple

Terminal

mkdir -p audit-demo
cd audit-demo

audit-demo.tb

module examples.audit_demo

strategy RunAuditDemo
    gives Text
    do
        show
            with message as "audit demo"
        give "done"

2. Compiler vers AIR

Terminal

touba compile audit-demo.tb --out audit-demo.air.json

La compilation ne lance rien. Elle produit l’artefact que le runtime consomme.

3. Exécuter avec trace séparée

Terminal

touba run audit-demo.air.json \
  --trace-out audit-demo.trace.json \
  --output all

Sortie attendue :

Sortie

audit demo

Le fichier audit-demo.trace.json contient les événements runtime.

4. Auditer trace, AIR et source

Terminal

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

Sortie attendue, en substance :

Résumé

Touba Trace Audit trace-audit-validation-v1
Status ok
Diagnostics ok

Si la trace et l’AIR ne parlent pas du même module, le rapport doit refuser.

5. Produire un export borné

Terminal

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

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

6. Inspecter l’export

Terminal

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

Touba doit afficher :

• le type d’export ;
• le run concerné ;
• le statut ;
• la classe de rétention ;
• la politique de redaction ;
• les diagnostics.

inspect ne relance pas le programme, ne lit pas de secret et ne prouve pas que le système est conforme à un cadre réglementaire.

Refuser un AIR différent

Conservez la trace et le source initiaux. Compilez un second programme avec le même module mais un résultat différent, puis auditez la trace initiale avec cet AIR. Le nom du module ne suffit pas : le digest de l’AIR complet doit correspondre.

changed.tb

module examples.audit_demo

strategy RunAuditDemo
    gives Text
    do
        show
            with message as "audit demo"
        give "changed"

check-refusal.mjs

import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";
const original = readFileSync("audit-demo.trace.json", "utf8");
const child = spawnSync("touba", ["audit", "--trace", "audit-demo.trace.json", "--air", "changed.air.json",
  "--source", "changed.tb", "--export", "refused.export.json", "--output", "json"], { encoding: "utf8" });
assert.equal(child.status, 1, child.stderr);
const audit = JSON.parse(child.stdout);
assert.equal(audit.validationReport.status, "failed");
assert.ok(audit.validationReport.diagnostics.some(item => item.code === "TraceAirDigestMismatch"));
assert.equal(existsSync("refused.export.json"), false);
assert.equal(readFileSync("audit-demo.trace.json", "utf8"), original);
console.log("AIR_MISMATCH_REFUSED_ORIGINAL_TRACE_PRESERVED");

Terminal

touba compile changed.tb --out changed.air.json
node check-refusal.mjs

Contrat Validé

L’audit des traces rend le lien entre trace, AIR, source, redaction et export observable et répétable. Le rapport produit un artefact d’ingénierie exploitable pour relire, comparer et conserver une exécution.

Conserver et archiver le journal

L’exécution conserve aussi ses événements dans .touba/traces.sqlite. Pour obtenir une référence légère et lire les événements par pages :

Terminal

touba run audit-demo.air.json --output json-reference > run.json

Dans VS Code, ouvrez run.json, lancez Touba: Render Trace, puis sélectionnez .touba/traces.sqlite. Le bouton Next page poursuit la lecture.

Après vos vérifications, prévisualisez puis archivez les runs réussis :

Terminal

touba trace archive --store .touba/traces.sqlite
mkdir -m 700 archives
touba trace archive --store .touba/traces.sqlite --destination archives/audit.sqlite --apply

Conservez l’archive : les mêmes références s’y lisent avec --store archives/audit.sqlite. Les pauses, échecs et interruptions restent dans le journal actif. Pour un serveur projet, archivez son état complet, serveur arrêté, afin de garder ensemble traces et continuations.