Memory Provenance and Integrity

Memory provenance and integrity (PI-1) make metadata associated with Touba memory access auditable.

It answers two simple questions:

• where information read from or written to a logical memory comes from;
• what evidence accompanies that information when the runtime observes it.

This slice makes audit facts visible in traces. Truth assessment, durable storage, and backend trust are separate concerns.

Memory Syntax

A Touba memory is a logical resource. Real access always goes through a tool, a manifest, and a 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

Here:

• memory ProjectKnowledge declares the logical memory;
• the tool declares uses memory ProjectKnowledge read;
• the skill and agent declare their scope;
• the runtime refuses access if source, AIR, manifest, or execution does not authorize it.

Provenance Metadata

A memory handler can return a business value and optional metadata.

{
  "ok": true,
  "value": {
    "summary": "Summary usable by the program."
  },
  "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"
    }
  ]
}

The runtime accepts this metadata only if it respects the provenance and integrity contract.

Important Fields

Field	Role
memory_ref	relevant logical memory
operation	read or write
source_kind	origin category
source_ref	opaque source reference
writer_ref	actor or system reported by the host
digest_kind	digest type
digest	digest or digest reference
schema_ref	logical schema reference
version_ref	reported version
integrity_evidence	available evidence

Values for integrity_evidence:

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

These values never mean Verified, trusted, safe, or compliant.

Inspection

After execution, inspect a trace:

Terminal

touba inspect trace.json

Expected output when provenance metadata is present:

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

The VS Code trace renderer displays the same facts when they exist in the trace.

Refusals

Touba refuses provenance metadata when it is incoherent or unsafe.

Refusal examples:

• operation = write while the tool only has read access;
• raw fields such as content, raw, document, or prompt;
• secret value or connection string;
• unknown integrity_evidence;
• attempt to provide owner_ref, tool_ref, run_id, or observed_at from the handler.

The runtime traces the refusal without copying the sensitive value.

Audit Scope

Memory provenance and integrity provide an audit foundation: provenance and evidence become visible without turning those indicators into automatic truth.

Native memory backends, mandatory cryptographic verification, immutable storage, legal timestamping, general poisoning detection, trust scoring, compliance proof, and Verified / Unverified status are separate assurance layers.