Manifest & Blob Schema

ContextSubstrate utilizes a content-addressed storage (CAS) model to ensure AI agent executions are immutable and verifiable. Every execution is represented by a Manifest (the structural metadata) and a collection of Blobs (the raw data).

The Manifest Schema

The manifest is a canonical JSON file that describes the entire execution state. When a manifest is "packed," it is stored in the object store, and its own SHA-256 hash becomes the unique identifier for the Context Pack (prefixed with ctx://).

Manifest Fields

| Field | Type | Description | | :--- | :--- | :--- | | version | string | The schema version (e.g., "0.1"). | | hash | string | The self-referential content hash of the manifest. | | created | string | RFC3339 UTC timestamp of pack creation. | | model | Object | Details of the LLM used (see Model Object). | | system_prompt | string | Hash reference to the system prompt blob. | | prompts | Array | List of user/assistant prompt references. | | inputs | Array | Files or data provided to the agent. | | steps | Array | The sequential execution log (see Step Object). | | outputs | Array | Final artifacts produced by the agent. | | environment | Object | Metadata about the execution host. | | parent | string | (Optional) Hash of the pack this was forked from. |

Model Object

Captures the configuration of the generative model.

{
  "identifier": "gpt-4-turbo",
  "parameters": {
    "temperature": 0.7,
    "top_p": 1.0,
    "max_tokens": 4096
  }
}

Step Object

Represents a single atomic action, such as a tool call or a reasoning step.

{
  "index": 0,
  "type": "tool_call",
  "tool": "read_file",
  "parameters": {
    "path": "config.yaml"
  },
  "output_ref": "sha256:8af3...",
  "deterministic": true,
  "timestamp": "2023-10-27T10:00:01Z"
}

Content Addressing & Blobs

Instead of storing large text blocks or binary files directly inside the manifest, ContextSubstrate uses Content References. Any field ending in _ref or designated as a content field (like system_prompt) contains a SHA-256 hash.

The Object Store

Blobs are stored in the .ctx/objects/ directory. The storage path is derived from the hash (e.g., sha256:abc123... might be stored at .ctx/objects/ab/c123...).

• De-duplication: If multiple execution packs use the same system prompt or input file, only one blob is stored.
• Integrity: The ctx verify command re-hashes blobs on disk to ensure they haven't been tampered with.

Canonicalization

To ensure that two identical executions produce the exact same Pack Hash, the manifest undergoes Canonical JSON serialization before hashing:

1. Key Sorting: All JSON keys are sorted alphabetically.
2. Whitespace: All unnecessary whitespace is removed.
3. Hash Omission: During the initial hashing process, the hash field itself is empty, as the hash cannot contain itself. Once calculated, the manifest is stored with the hash field populated.

Usage Example: Inspecting a Manifest

You can view the raw structure of any pack using the show command:

ctx show <hash>

To extract a specific blob (like an input file) from the schema, you can use the hash reference found in the manifest:

# Example: Finding a blob in the local store
cat .ctx/objects/ad/3f21... 

Environment Metadata

The environment block ensures that "drift" can be debugged by identifying changes in the underlying infrastructure:

{
  "os": "linux",
  "runtime": "go1.22",
  "tool_versions": {
    "python": "3.11.4",
    "search_api": "v2.1"
  }
}