Artifact Provenance

Artifact provenance ensures that every file, log, or data point produced by an AI agent can be traced back to its specific execution context. By leveraging content-addressed storage and immutable manifests, ContextSubstrate allows you to verify that an artifact was generated by a specific model, using specific prompts, under specific environment conditions.

Overview

In ctx, provenance is maintained through the relationship between Artifacts (the outputs) and Context Packs (the execution record). When an agent execution is finalized via ctx pack, the system generates a content hash for every output.

Verification confirms three things:

1. Integrity: The artifact has not been tampered with since it was produced.
2. Origin: The artifact is linked to a valid, registered Context Pack.
3. Traceability: You can retrieve the exact system prompt, tool outputs, and model parameters that led to the artifact's creation.

The Verification Workflow

The ctx verify command is the primary interface for validating provenance. It checks an artifact against the local .ctx store to find a matching signature in a registered pack.

Basic Usage

To verify an artifact, pass the file path to the verify command:

ctx verify ./outputs/summary.txt

Verification States

When you run ctx verify, the substrate returns a status report based on the following criteria:

| Status | Meaning | | :--- | :--- | | Verified | The artifact's content hash matches an entry in a registered Context Pack. | | Unregistered | The artifact exists, but no corresponding hash was found in the .ctx store. | | Mismatch | An artifact with that name exists in a pack, but the current file content differs (potential tampering). | | Corrupt | The associated Context Pack manifest is missing or has an invalid signature. |

Technical Mechanism

ContextSubstrate uses Sidecar Metadata or direct content-addressing to perform lookups.

1. Content Hashing: Every output in a Context Pack is stored as a blob. The Output type in the manifest maps a filename to a ContentRef (the SHA-256 hash of the content).
2. Manifest Lookup: ctx verify computes the hash of the target file and searches the .ctx/packs/ index for any manifest containing that specific hash in its outputs array.
3. Context Retrieval: Once a match is found, the CLI returns the Pack Hash (ctx://...), allowing you to run ctx show <hash> to see the full lineage.

Example: Tracing an Artifact to its Source

If you encounter a suspicious AI-generated report, you can verify it and then inspect the prompt that generated it:

# 1. Check if the artifact is authentic
ctx verify report.md

# Output:
# Artifact:  report.md
# Status:    VERIFIED
# Pack:      ctx://a1b2c3d4e5f6
# Created:   2023-10-24 14:30:00 UTC

# 2. Inspect the prompts and model used for this specific report
ctx show a1b2c3d4e5f6

Manual Verification (Advanced)

Since ContextSubstrate uses standard JSON and content-addressing, you can manually verify provenance without the ctx binary by inspecting the .ctx/objects directory. Each object is stored at a path corresponding to its hash.

The manifest for a pack will contain an outputs section structured as follows:

{
  "outputs": [
    {
      "name": "summary.txt",
      "content_ref": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "context_pack": "sha256:f8217036..."
    }
  ]
}

By comparing the SHA-256 hash of your artifact to the content_ref in any registered manifest, you can cryptographically prove the artifact's inclusion in that execution pack.