Immutability and Forking

Immutability and Content Addressing

At the core of ctx is the Context Pack: an immutable, content-addressed snapshot of an AI agent's execution. Unlike standard logging, where data can be truncated or overwritten, Context Substrate treats every agent run as a permanent cryptographic record.

The Content Hash

When you run ctx pack, the system generates a unique hash (e.g., ctx://a1b2c3...) based on the canonical manifest of the execution. This manifest includes:

• System and User Prompts: The exact instructions provided to the model.
• Input Blobs: The content and state of files provided to the agent.
• Step Sequence: The order, tool choices, and parameters of every action.
• Outputs: The final artifacts produced.

Because the hash is derived from the content itself (using canonical JSON serialization), any change—no matter how small—results in a different hash. This ensures strict provenance: if an artifact's hash matches the record in the store, it is guaranteed to be the exact result of the recorded execution steps.

The Forking Workflow

While Context Packs are immutable, development is iterative. To experiment with an existing execution—such as testing a different system prompt or adjusting model parameters—you use the forking mechanism.

Creating a Draft

Forking allows you to create a mutable copy of an existing pack. This transitions the data from the "Object Store" (immutable) back into a "Draft" (mutable) state.

# Create a mutable draft from an existing pack
ctx fork <hash>

When you fork a pack, ctx extracts the manifest into a local directory. This draft represents a branch in your agent's history, allowing you to modify the environment, prompts, or tool definitions without losing the original record.

Finalizing an Iteration

Once you have modified the draft (e.g., editing the system prompt in the draft directory), you can "seal" the changes to create a new immutable pack.

# Seal the draft into a new Context Pack
ctx pack <path-to-draft/execution.json>

This creates a new node in the execution graph. The new pack will maintain a Parent reference to the original hash, allowing for lineage tracking across multiple iterations of agent tuning.

Detecting Drift

The primary benefit of immutability and forking is the ability to perform high-fidelity Drift Analysis. Because the substrate understands the structure of an agent's run, it can compare a fork against its parent to identify exactly why an agent's behavior changed.

Using ctx diff <hash-a> <hash-b>, the substrate generates a structured report identifying specific types of divergence:

| Drift Type | Description | | :--- | :--- | | prompt_drift | Changes in the system prompt or user instructions. | | tool_drift | The agent called a different tool at the same execution step. | | param_drift | The same tool was called, but with different arguments (e.g., temperature, file paths). | | reasoning_drift | The tool and parameters were the same, but the model produced a different output or chain-of-thought. | | output_drift | Differences in the final artifacts produced by the agent. |

Example: Comparing a Fork

If you fork a pack to test a "concise" system prompt, you can verify the impact of that change:

$ ctx diff ctx://original_hash ctx://new_hash --human

Comparing a1b2c3d4e5f6 vs b2c3d4e5f6g7

1 difference(s) found:

  1. [prompt_drift] System prompts differ
  2. [reasoning_drift] Step 2: read_file produced different output

This workflow transforms AI debugging from a "guessing game" into a git-like experience, where every change is tracked, hashed, and contestable.