Provenance et intégrité des mémoires

La provenance et l’intégrité des mémoires (PI-1) rendent auditables les metadata associées aux accès mémoire Touba.

Elle répond à deux questions simples :

• d’où vient une information lue ou écrite dans une mémoire logique ;
• quelle évidence accompagne cette information au moment où le runtime l’observe.

Cette tranche rend les faits d’audit visibles dans les traces. L’évaluation de vérité, la persistance durable et la confiance dans le backend relèvent de contrôles séparés.

Syntaxe mémoire

Une mémoire Touba est une ressource logique. L’accès réel passe toujours par un tool, un manifest et un handler.

module examples.memory_audit

memory ProjectKnowledge

type Query
    text is Text

type KnowledgeResult
    summary is Text

tool ReadProjectKnowledge
    uses memory ProjectKnowledge read
    takes query as Query
    gives KnowledgeResult
    requires memory_read

skill UseProjectKnowledge
    description "Read knowledge through its declared memory scope."
    takes query as Query
    gives KnowledgeResult
    uses ReadProjectKnowledge
    memory ProjectKnowledge read
    do
        ReadProjectKnowledge
            with query as query
            into result
        give result

agent Researcher
    takes query as Query
    gives KnowledgeResult
    responsibility "Fulfill the declared Researcher responsibility using only authorized capabilities."
    uses UseProjectKnowledge
    memory ProjectKnowledge read
    callable_by strategy RunResearch

strategy RunResearch
    takes query as Query
    gives KnowledgeResult
    uses Researcher
    do
        Researcher
            with query as query
            into result
        give result

Ici :

• memory ProjectKnowledge déclare la mémoire logique ;
• le tool déclare uses memory ProjectKnowledge read ;
• le skill et l’agent déclarent leur scope ;
• le runtime refuse un accès si la source, l’AIR, le manifest ou l’exécution ne l’autorisent pas.

Metadata de provenance

Un handler de mémoire peut retourner une valeur métier et des metadata optionnelles.

{
  "ok": true,
  "value": {
    "summary": "Résumé utilisable par le programme."
  },
  "memory_metadata": [
    {
      "memory_ref": "memory:examples.memory_audit/ProjectKnowledge",
      "operation": "read",
      "source_kind": "backend_import",
      "source_ref": "source:project-knowledge/main",
      "writer_ref": "handler:read_project_knowledge",
      "written_at": "2026-05-17T12:00:00Z",
      "digest_kind": "sha256",
      "digest": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "schema_ref": "type:examples.memory_audit/KnowledgeResult",
      "version_ref": "memory-version:project-knowledge:1",
      "integrity_evidence": "digest_reported"
    }
  ]
}

Le runtime accepte ces metadata seulement si elles respectent le contrat de provenance et d’intégrité.

Champs importants

Champ	Rôle
memory_ref	Mémoire logique concernée
operation	read ou write
source_kind	Catégorie d’origine
source_ref	Référence opaque de source
writer_ref	Acteur ou système reporté par l’hôte
digest_kind	Type de digest
digest	Digest ou référence de digest
schema_ref	Référence de schéma logique
version_ref	Version reportée
integrity_evidence	Évidence disponible

Valeurs de integrity_evidence :

• none
• handler_reported
• digest_reported
• digest_matched
• digest_mismatch
• stale_by_policy

Ces valeurs ne signifient jamais Verified, trusted, safe ou conforme.

Inspection

Après exécution, vous pouvez inspecter une trace :

Terminal

touba inspect trace.json

Sortie attendue quand des metadata de provenance sont présentes :

Trace touba-trace-v1
- memory_metadata provenance_observed=1 integrity_observed=1 metadata_refused=0 integrity_refused=0 evidence=[digest_reported]

Le renderer trace de l’extension VS Code affiche les mêmes faits quand ils existent dans la trace.

Refus

Touba refuse des metadata de provenance quand elles sont incohérentes ou dangereuses.

Exemples de refus :

• operation = write alors que le tool n’a qu’un accès read ;
• champ brut comme content, raw, document ou prompt ;
• valeur de secret ou chaîne de connexion ;
• integrity_evidence inconnue ;
• tentative de fournir owner_ref, tool_ref, run_id ou observed_at depuis le handler.

Le runtime trace le refus sans recopier la valeur sensible.

Périmètre d’audit

La provenance et l’intégrité des mémoires constituent une base d’audit : provenance et évidence deviennent visibles sans transformer ces indices en vérité automatique.

Les backends mémoire natifs, la vérification cryptographique obligatoire, le stockage immuable, l’horodatage légal, la détection générale d’empoisonnement, les scores de confiance, les preuves de conformité et les statuts Verified / Unverified relèvent de couches d’assurance séparées.