Référence traces

Choisir le détail des fonctions pures

--trace-pure-functions full conserve le détail complet, actif par défaut. Avec calls, les branches, boucles, bindings et scopes réussis internes aux fonctions pures sont omis. Les appels, retours, erreurs, budgets et événements de gouvernance restent enregistrés. Le scope de la fonction d'entrée est conservé.

touba run --project . --trace-pure-functions calls --trace-out trace.json

La trace indique run.pure_function_detail: "calls". Le filtrage précède la numérotation, les observateurs et la persistance : tous reçoivent la même trace. La CLI serve et les deux SDK exposent aussi ce réglage.

Conserver les traces

touba run program.air.json --trace-store .touba/traces.sqlite --trace-out trace.json

SQLite conserve les traces par défaut dans .touba/traces.sqlite du projet. Sans touba.project.json parent, la CLI utilise le dossier de l’AIR ou du plan fourni. --trace-store choisit un autre journal privé. Les événements sont conservés progressivement ; les détails purs sont regroupés en petits lots, enregistrés avant les appels et checkpoints. Une panne de stockage interrompt la progression avant le prochain effet. Chaque exécution ou reprise crée un segment distinct.

--trace-out exporte le document touba-trace-v1. Les modes --output trace, json et all lisent le journal progressivement et attendent la disponibilité de la sortie. Le fichier exporté est remplacé seulement une fois complet.

Le résumé --output run-summary et les preuves --evidence-out parcourent aussi le journal progressivement. Les collections du résumé sont limitées à 16 Mio ; en cas de dépassement, exportez la trace complète avec --trace-out.

Le journal autorise par défaut 512 Mio de données sérialisées et 1 Mio par événement. Il reste conservé jusqu'à son archivage par l'hôte ; aucune purge automatique n'est activée. Placez-le dans un dossier privé et sauvegardé.

Archiver un journal

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

La première commande affiche le volume récupérable. La commande avec --apply crée une archive vérifiée, puis libère les runs réussis de la source. Les pauses, échecs et exécutions interrompues restent conservés. L'archive se lit avec les mêmes références, en passant son chemin à --store. Sa destination doit être nouvelle ; aucun fichier existant n'est remplacé.

Pour un serveur projet, archivez l'état complet, serveur arrêté : traces, checkpoints et effets restent associés. Les aperçus serveur affichent les 200 derniers événements et le nombre total. L'index GET /runs/{run_id}/trace?index=true et les pages /runs/{run_id}/trace/segments/0?limit=100 donnent accès au journal complet avec l'autorisation du projet. Sans index, la route exporte toute la trace.

Lire une trace par pages

--output json-reference renvoie le résultat métier et une trace_reference. Le journal par défaut suffit ; --trace-store permet de choisir un autre chemin. Les événements se lisent séparément, par pages. Pour lire une page, transmettez la référence JSON complète à :

touba trace read --store .touba/traces.sqlite --reference-json '<référence JSON>' --limit 100

La réponse contient header, events, next et done. Passez next à --after pour la page suivante, jusqu'à done: true. La première lecture sans curseur vérifie aussi l'empreinte du segment complet, en mémoire bornée. Les pages suivantes vérifient les événements lus et leur ordre. Une lecture n'exécute aucun programme et ne modifie pas le journal.

Une page contient au plus 1 000 événements et 1 Mio de contenu d'événements ; la référence et l'en-tête s'ajoutent à cette taille. Les exemples des SDK JavaScript et Python montrent la boucle complète. La référence désigne un segment terminé, y compris en cas de pause ou d'échec. Un refus d'admission conserve sa petite trace dans le résultat d'erreur.

Provenance et décisions

Les nouveaux AIR produits par la CLI utilisent des identités de source relatives à une racine commune aux fichiers compilés, sans enregistrer le chemin absolu de cette racine dans l’AIR. Les traces héritent de ces identités. Le résultat technique de compilation --json fournit séparément source_root à l’éditeur ; les diagnostics locaux gardent leurs chemins pour ouvrir le fichier. Avant de partager un artefact, vérifiez aussi les données et métadonnées applicatives : ce changement n’est pas un anonymiseur général.

L’éditeur résout une source relative depuis le dossier de travail, ou demande la racine du projet. Un déplacement conserve l’identité AIR si les sources et leurs chemins relatifs restent identiques. Les anciens AIR et traces ne sont pas réécrits : recompilez et faites revoir les locks si vous migrez leur provenance.

Une répétition autorisée reste exécutable. Les observations et la chronologie exposent repeated_from_step et identical_invocation_number, sans créer de permission à usage unique. Une sélection native peut ne fournir aucun reason : cette absence n’est ni un raisonnement caché disponible ni une erreur ; aucun motif n’est inventé. Les métadonnées inchangées d’un skill pack ne sont tracées qu’une fois par invocation d’agent ; contrôles d’autorité et de budget restent évalués à chaque requête.

Le contrat machine courant est touba-trace-v1, avec le profil touba-trace-capabilities-v1. Une trace d’exécution exige run.air_digest, l’empreinte canonique SHA-256 de l’AIR calculée avant exécution. Une ancienne trace sans cet engagement n’est pas une preuve V1 et n’est pas réparée à la lecture.

Les traces rendent l'exécution observable. Elles constituent une preuve d’ingénierie, distincte des garanties de sandbox, de permission forte ou de vérification scientifique.

Enveloppe

Une trace contient :

• trace_protocol_version
• trace_capability_profile
• run
• events

Chaque événement porte un kind et un payload, un identifiant unique et une séquence continue. Les références de run et de module doivent rester cohérentes. Une trace terminée contient exactement un événement terminal ; un ordre cassé, un profil inconnu ou un payload sensible interdit sont refusés avant rendu.

Événements principaux

Événement	Signification
admission_refused	Refus avant exécution, seul événement ; run.admission vaut refused et les identités AIR sont nulles
call_started	Entrée dans un appel AIR
call_completed	Sortie d'un appel AIR
binding_created	Valeur locale bind créée sans exposition de sa valeur
tool_binding_authorized	Tool autorisé avant dispatch handler
secret_handle_authorized	Handle de secret autorisé avant dispatch handler
secret_handle_refused	Handle de secret refusé avant dispatch handler
memory_access_authorized	Accès mémoire logique autorisé
memory_provenance_observed	Metadata de provenance mémoire observée
memory_integrity_observed	Evidence d’intégrité mémoire observée
memory_metadata_refused	Metadata mémoire refusée
memory_integrity_refused	Evidence d’intégrité mémoire refusée
agent_invocation_authorized	Entrée agent autorisée
agent_invocation_refused	Entrée agent refusée
agent_capabilities_listed	Capacités déclarées dans uses pour l'agent actif
agent_capability_descriptions_diagnosed	Qualité des descriptions de capacités exposées au decision provider
agent_decision_requested	Demande structurée envoyée au decision provider, avec request_digest et mode d'entrée modèle sans payload brut
agent_decision_provider_call_attempted	Appel au decision provider tenté avec tentative, timeout et metadata non secrètes
agent_decision_catalog_requested	Catalogue complet demandé par le provider
agent_decision_provider_retry_scheduled	Retry borné planifié après échec provider éligible
agent_decision_provider_returned	Réponse structurée du provider
provider_cost_recorded	Réservation ou règlement du coût hôte, corrélé à l'invocation d'agent ; un usage inconnu conserve sa borne
agent_decision_recorded	Décision d'agent reçue par le runtime
agent_direct_answer_returned	Réponse directe retournée sans présentation du catalogue
skill_pack_discovery_listed	Skill packs disponibles listés comme hints courts, sans contenu brut
skill_pack_activated	Skill pack explicitement activé comme contexte borné
skill_pack_activation_refused	Activation ou entrée modèle refusée par budget
skill_pack_resource_loaded	Ressource déclarée chargée comme contexte, sans contenu dans la trace
skill_pack_resource_refused	Ressource ou lien d’exécution de skill pack refusé
agent_capability_selected	Capacité autorisée sélectionnée
agent_capability_result_returned	Résultat de capacité rendu disponible comme observation pour la décision suivante
agent_capability_refused	Capacité refusée car hors périmètre déclaré
agent_human_review_requested	Review humain demandé par l’agent en mode catalogue
agent_step_limit_exceeded	Limite de pas agentiques dépassée
trigger_event_received	Événement trigger normalisé reçu
trigger_event_accepted	Trigger accepté avant exécution cible
trigger_event_refused	Trigger refusé avant exécution cible
trigger_rate_limited	Limite de run trigger atteinte
trigger_execution_started	Exécution cible déclenchée
trigger_execution_completed	Exécution cible terminée
trigger_execution_failed	Exécution cible échouée
run_cancel_requested	Annulation demandée par l’hôte, le timeout ou le kill switch
run_cancelled	Annulation coopérative terminée
run_timeout_exceeded	Timeout global de run observé
kill_switch_enabled	Kill switch activé par l’hôte
kill_switch_disabled	Kill switch désactivé par l’hôte
dispatch_refused_cancelled	Nouveau dispatch refusé après une demande de cancel
budget_limit_checked	Budget d’autonomie effectif établi
budget_consumed	Compteur de budget d’autonomie consommé
budget_limit_exceeded	Budget d’autonomie dépassé ou configuration refusée
dispatch_refused_budget_exceeded	Nouveau dispatch refusé par budget d’autonomie
human_approval_requested	Demande de validation humaine
human_approval_paused	Exécution suspendue
human_approval_pause_refused	Pause humaine refusée car une reprise durable serait nécessaire après effet externe
human_approval_decided	Décision humaine fournie
user_interaction_shown	show exécuté
user_interaction_paused	Exécution suspendue faute d'entrée
user_interaction_answered	Entrée fournie par l'hôte
failure_detected	Échec runtime observable
fallback_selected	Branche de récupération correspondant à la famille d’échec
run_completed	Fin de run

Lire une trace

Terminal

touba inspect trace.json

L'inspecteur affiche les événements existants. Il ne relit pas les handlers, secrets ou backends.

Export OpenTelemetry

Touba garde touba-trace-v1 comme trace native lisible par les commandes Touba. Pour l’observabilité externe, touba inspect peut produire une projection JSON compatible avec les modèles de spans OpenTelemetry :

Terminal

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

Cet export sert de pont vers les stacks d’observabilité. Il ne remplace pas la trace native, ne signe pas les événements et ne prouve pas une conformité. Les événements Touba deviennent des spans GenAI quand le mapping est établi : invoke_workflow, invoke_agent ou execute_tool. L’export conserve les références AIR, le run_id, la séquence, les codes de refus et des compteurs non sensibles.

L’export OpenTelemetry n’écrit pas les prompts complets, messages bruts, réponses utilisateur, résultats de tools, observations brutes, valeurs secrètes ou chemins locaux. La trace Touba reste l’artefact d’audit local.

Pour la provenance et l’intégrité mémoire (PI-1), les traces peuvent contenir des références de provenance mémoire, un digest et une integrity_evidence. Ces champs décrivent l’évidence disponible ; ils ne prouvent pas que le contenu est vrai, sûr ou vérifié de bout en bout.

Pour les skill packs, les traces exposent les refs, compteurs, raisons d'activation, budgets et codes de refus. Elles ne contiennent pas le contenu complet du pack, le contenu d'un script, un payload brut, un prompt complet ou une valeur de secret.

Auditer une trace

Terminal

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

L’audit des traces (TA-1) produit un rapport de validation et peut écrire un export trace-audit-export-v1-local.

Il vérifie seulement les artefacts fournis explicitement : trace, AIR, source, manifest runtime ou manifest d’audit. Il calcule des digests sha256, contrôle des cohérences structurelles et refuse des fuites évidentes selon la politique de redaction choisie.

Pour les interfaces de revue, le même 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

Cette projection touba-trace-timeline-v1 garde l’ordre des événements, les types, les sévérités, les références sources et les marqueurs de redaction. Elle ne copie pas les payloads bruts, prompts complets, contenus mémoire ou valeurs de secrets.

Les signatures, l’horodatage légal, le stockage immuable et les garanties de conformité relèvent de couches de preuve séparées.

Données sensibles

Ce que les traces contiennent

• Références AIR
• Noms de handles de secrets
• Autorisations ou refus de handles de secrets
• Capabilities
• Chemins de schéma
• Types attendus ou observés

Ce que les traces ne doivent pas contenir

• Valeurs de secrets
• Valeurs brutes envoyées au decision provider
• Prompt complet ou entrée modèle complète
• Observations runtime brutes retournées au decision provider
• Payload externe brut d’un trigger
• Valeurs exactes des bindings locaux
• Réponses exactes de ask dans user_interaction_answered
• Signal système de hard kill
• État d’un control plane distribué
• Quota distribué
• Payloads sensibles complets
• Contenu brut de mémoire
• Score de confiance mémoire
• Statut Verified ou Unverified

Causalité parallèle

Le runtime émet parallel_group_admitted, parallel_group_refused, parallel_branch_started, parallel_branch_completed, parallel_branch_suspended, parallel_join_completed, parallel_join_failed et parallel_group_resumed. Les événements descendants portent group_id, branch_id et parent_branch_id. Ces identités restent stables à la reprise ; l'ordre local des événements ne constitue pas un ordre total des systèmes externes. Les résultats et journaux de continuation privés ne sont pas des payloads publics de trace. Les messages show sont restitués dans l'ordre d'entrée.

Temps d’observation

Chaque nouvel événement natif contient observed_at, au format UTC YYYY-MM-DDTHH:mm:ss.sssZ. L’horodatage fait partie du contenu couvert par les empreintes de trace et de checkpoint. Une reprise conserve les événements déjà enregistrés et horodate les nouveaux à leur exécution. L’ordre causal reste donné par sequence_index ; l’heure provient de l’hôte.

L’export OpenTelemetry reprend ces instants. Pour une trace antérieure sans horodatage, l’export indique explicitement sa projection temporelle synthétique.