> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning & Compatibility

> Manifests, components, compatibility verdicts, and the engine that classifies traces against agent changes.

DecimalAI's core innovation is **version-aware data management.** This page explains how agent versions are tracked and what happens when they change.

## How Versions Are Tracked

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
graph LR
    T1["Trace arrives"] --> AD["Auto-Detect: extract tools + models"]
    AD --> H["Compute manifest hash"]
    H --> CHK{"Hash exists for this agent?"}
    CHK -->|Yes, active| SKIP["Idempotent — use existing manifest"]
    CHK -->|Yes, superseded| REV["Revert detected — reactivate old manifest"]
    CHK -->|No| NEW["Register new manifest (v1 → v2 → v3)"]

    style T1 fill:#44403c,stroke:#292524,color:#fafaf9
    style AD fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style H fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style CHK fill:#e7e5e4,stroke:#78716c,color:#1c1917
    style SKIP fill:#dcfce7,stroke:#22c55e,color:#14532d
    style REV fill:#e7e5e4,stroke:#a8a29e,color:#1c1917
    style NEW fill:#a8a29e,stroke:#57534e,color:#1c1917
```

## Manifest

A **manifest** is a snapshot of your agent's full configuration at a point in time: which tools, models, prompts, skills, and sub-agents it uses.

Manifests can be:

* **Auto-detected** — extracted from incoming traces (zero config)
* **Manually registered** — explicitly declared via the SDK or API (highest fidelity)

→ See [Manifests & Versioning](/guides/manifests) for the full guide.

<Note>
  **Manifest vs Version:** A manifest is the data (the full snapshot). A version is the label (v1, v2, v3). Each agent has many manifests over time; each manifest has a unique version label. Version labels are NOT semantic versions (major.minor.patch) — they simply auto-increment.
</Note>

## Component

A **component** is a single versioned piece within a manifest. Each component has a type, name, and content hash:

| Component Type    | What It Represents                           | Example                                     |
| ----------------- | -------------------------------------------- | ------------------------------------------- |
| `tool`            | A function the agent can call                | `search_docs(query: str) → List[Doc]`       |
| `model`           | An LLM the agent uses                        | `gpt-4o, temperature=0.7`                   |
| `prompt`          | A system prompt or instruction               | `"You are a helpful research assistant..."` |
| `skill`           | A reusable behavior module                   | `code-review` (SKILL.md file)               |
| `subagent`        | A child agent this orchestrator delegates to | `fact-checker`                              |
| `output_contract` | Expected output schema                       | `{answer: string, confidence: number}`      |

## Surface

A **surface** is one independently-versioned policy-grouping of the manifest — a slice you can write its own compatibility rules for. Components are bucketed into surfaces so that, for example, a breaking tool change can `replay` while a guardrail change merely gets flagged. There are **10 surfaces**:

| Surface           | What It Groups                                           |
| ----------------- | -------------------------------------------------------- |
| `prompt_stack`    | System prompts and instructions                          |
| `model_runtime`   | The LLM(s) and runtime params (model, temperature, etc.) |
| `tool_registry`   | The set of callable tools and their signatures           |
| `skill_registry`  | Loaded skills (SKILL.md modules)                         |
| `workflow`        | Orchestration structure and control flow                 |
| `subagents`       | Delegated child agents                                   |
| `output_contract` | Expected output schema                                   |
| `guardrails`      | Input/output safety and validation rules                 |
| `context_config`  | Context-window and retrieval configuration               |
| `environment`     | Runtime environment and external dependencies            |

Each surface carries its own `on_minor` / `on_moderate` / `on_major` action under the agent's compatibility policy — see the [matrix](#severity--policy-matrix) below.

## Component Verdict

When the engine diffs a single component across old and new manifests, it assigns one of four per-component outcomes. (This is distinct from the per-*trace* [Compatibility Verdict](#compatibility-verdict) of keep/repair/replay/drop.)

| Component Verdict | Meaning                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| **COMPATIBLE**    | The component is unchanged, or changed only cosmetically — no action needed.                   |
| **REPAIRABLE**    | The component changed in a way that can be deterministically fixed (e.g. a renamed parameter). |
| **INCOMPATIBLE**  | The component changed in a breaking way that cannot be auto-fixed.                             |
| **MISSING**       | The component was present in the old manifest but no longer exists in the new one.             |

## Manifest Hash

A SHA-256 fingerprint of the manifest's structural components (tools + models). Two manifests with the same hash for the same agent are considered identical — the second registration is idempotent. Prompt changes alone do NOT change the hash — they're tracked separately via content hashing for drift detection.

## Manifest Status

| Status       | Meaning                            |
| ------------ | ---------------------------------- |
| `active`     | The current version for this agent |
| `superseded` | Replaced by a newer version        |
| `draft`      | Registered but not yet activated   |

## Revert

When a trace arrives with a manifest hash matching a previously superseded manifest, DecimalAI detects this as a rollback. It re-activates the old manifest and supersedes the current one — no duplicate is created. Your version history stays clean.

## Compatibility Engine

When a manifest changes, the compatibility engine classifies every existing trace to determine if it's still usable. This is what makes DecimalAI's training data lifecycle possible.

### How Compatibility Works

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
graph TD
    MC["Manifest Change Detected (v2 → v3)"] --> DIFF["Diff: which components changed?"]
    DIFF --> SEV["Assess severity per component"]
    SEV --> EP["Classify every trace against new manifest"]
    EP --> V{"Per-trace verdict"}
    V -->|All compatible| KEEP["✅ Keep"]
    V -->|Fixable schema change| REPAIR["⚡ Repair"]
    V -->|Behavior changed| REPLAY["↻ Replay"]
    V -->|Component removed| DROP["✕ Drop"]

    style MC fill:#44403c,stroke:#292524,color:#fafaf9
    style DIFF fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style SEV fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style EP fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style V fill:#e7e5e4,stroke:#78716c,color:#1c1917
    style KEEP fill:#dcfce7,stroke:#22c55e,color:#14532d
    style REPAIR fill:#e7e5e4,stroke:#a8a29e,color:#1c1917
    style REPLAY fill:#a8a29e,stroke:#57534e,color:#1c1917
    style DROP fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
```

### Compatibility Verdict

The per-trace outcome of a compatibility analysis:

| Verdict    | Meaning                                            | Automated Action                     |
| ---------- | -------------------------------------------------- | ------------------------------------ |
| **Keep**   | Trace is fully compatible with the new version     | Use as-is for training               |
| **Repair** | Trace has fixable issues (e.g., renamed parameter) | Auto-fix at zero LLM cost            |
| **Replay** | Too much changed — trace must be re-run            | Re-execute against the current agent |
| **Drop**   | Incompatible and unfixable                         | Exclude from datasets                |

### Severity

When comparing a component between old and new manifests, the engine assigns a severity:

| Severity   | Meaning                          | Example                                                |
| ---------- | -------------------------------- | ------------------------------------------------------ |
| `none`     | No change                        | Same content hash                                      |
| `minor`    | Cosmetic                         | Typo fix in prompt, temperature 0.70 → 0.71            |
| `moderate` | Significant, possibly repairable | Tool parameter renamed, prompt moderately changed      |
| `major`    | Breaking                         | Tool removed, model provider changed, prompt rewritten |

Severity is then mapped to a verdict through the agent's **compatibility policy** (strict / default / permissive).

### Severity × Policy Matrix

Each surface has its own rules, but the shape is the same across presets. Here is the `tool_registry` surface — for each component severity, the action each preset takes:

| Severity   | `strict` | `default` | `permissive` |
| ---------- | -------- | --------- | ------------ |
| `none`     | keep     | keep      | keep         |
| `minor`    | keep     | keep      | keep         |
| `moderate` | drop     | repair    | keep         |
| `major`    | drop     | replay    | flag         |

The five possible actions are `keep`, `repair`, `flag`, `replay`, and `drop`. A severity of `none` always maps to `keep` (nothing changed). Other surfaces shift the actions — `guardrails`, `context_config`, and `environment` are softer (a `major` change only flags under `default`), while `prompt_stack` and `model_runtime` are stricter.

→ See [Compatibility Policies](/guides/compatibility-policies) for policy configuration.

<Tip>
  The manifest, the diff, and the compatibility-decision format are all defined by **agentversion** — the open spec the platform is built on. You can produce the same manifests and verdicts outside DecimalAI with the [`agentversion` package on PyPI](https://pypi.org/project/agentversion/).
</Tip>

## Next

<CardGroup cols={2}>
  <Card title="Evaluation" icon="circle-check" href="/concepts/evaluation">
    The decision engine combines quality + compatibility into one verdict.
  </Card>

  <Card title="Manifests Guide" icon="layer-group" href="/guides/manifests">
    Hands-on guide to manifest detection and the impact report.
  </Card>
</CardGroup>