# V1 / V2 Compatibility

URL: https://docs.nexart.io/docs/v1-v2-compatibility

A compatibility matrix for AI Execution V1 and V2: which SDK, CLI, Agent Kit, and node surfaces accept which schema, and what deliberately has no V2 counterpart.

## Overview

AI Execution has two record schemas in active use: V1 (`ai.execution.v1`) and V2 (`ai.execution.v2`). V1 is fully supported and unchanged. V2, described in AI Execution V2, is the current recommended schema for new integrations. Neither schema deprecates the other; they coexist. To move an existing integration to V2, see Migrating from V1 to V2.

V1 is not going away
V1 is fully supported and unchanged. Historical V1 records verify byte-for-byte exactly as they always have. Adopting V2 for new integrations does not require touching existing V1 records.

## Surface Compatibility Matrix

| Surface | V1 | V2 |
| --- | --- | --- |
| createSnapshot / createSnapshotV2 | Yes | Yes (separate function) |
| sealCer / sealCerV2 | Yes | Yes (separate function) |
| certifyDecision / certifyDecisionV2 | Yes | Yes (separate function) |
| verifyCer(Async) / verifyCerV2(Async) | Yes | Yes (separate function) |
| Provider wrappers (openai/anthropic) | Yes (V1 helpers) | Yes (openaiV2 / anthropicV2) |
| createLangChainCer(V2) | Yes | Yes (createLangChainCerV2) |
| sealConfidential / sealConfidentialV2 | Yes | Yes (separate commitment domains) |
| Agent Kit certifyDecision / certifyAiExecutionV2 | Yes | Yes (certifyAiExecutionV2) |
| Agent Kit wrapTool | Yes | No, no V2 counterpart |
| Agent Kit startWorkflow step bookkeeping | Yes | No, no V2 counterpart |
| Node /api/attest | Yes | Yes, dispatches by bundleType |
| Node /v1/cer/ai/certify | Yes (producer flow) | No, V2 must not be created here |
| CLI nexart ai verify / --aief | Yes | Yes |
| verifyAief | Yes | Yes, accepts V1 \| V2 |
| Project Bundle steps | Yes | Yes, may be mixed in one bundle |

## Surfaces With No V2 Counterpart

The following surfaces are intentionally V1-only and stay that way. They are not AI executions and MUST NOT produce synthetic V2 records:

- `wrapTool` (Agent Kit): tool-call bookkeeping. It is not an AI execution and has no V2 counterpart.
- `startWorkflow` step bookkeeping (Agent Kit): workflow step registry entries are structural, not AI executions, and have no V2 counterpart.
- `/v1/cer/ai/certify` (node route): the V1 producer certify flow. V2 bundles MUST NOT be created through this endpoint.

## Project Bundles Stay a Single Container

There is no Project Bundle V2. The container type (`cer.project.bundle.v1`, container version `"0.1"`, `protocolVersion "1.2.0"`) is unchanged. A bundle's ordered step registry MAY contain a mix of V1 and V2 CERs in the same project (`AiExecutionCer = V1 | V2 bundle`). `projectHash` binds the ordered step registry; this semantic is unchanged by mixing schemas. See Project Bundles.

Mixed V1/V2 step registry (conceptual)

```
// A single Project Bundle can contain V1 and V2 CERs side by side.
const steps = [
  { stepId: "s1", certificateHash: v1Bundle.certificateHash, /* ... */ },
  { stepId: "s2", certificateHash: v2Bundle.certificateHash, /* ... */ },
];
// projectHash binds the ordered step registry regardless of per-step schema.
```

## Package Version to Schema Support

| Package | Version | Schema support |
| --- | --- | --- |
| @nexart/ai-execution | 1.4.0 | V1 and V2 APIs, in one package |
| @nexart/agent-kit | 0.6.0 | V1 (all existing surfaces) plus certifyAiExecutionV2 |
| @nexart/cli | 1.3.0 | Verifies both cer.ai.execution.v1 and cer.ai.execution.v2 |
| @nexart/codemode-sdk | 1.13.1 | Not schema-specific; see its own reference |
| @nexart/policy | 0.1.0 | Producer-side, schema-agnostic evaluation output |
| NexArt Node | 0.25.0 | /api/attest accepts v1 and v2 by bundleType |
| AIEF | v0.2.5 | verifyAief accepts V1 or V2 bundles |

## Next

- AI Execution V2: the full V2 schema reference.
- AI Execution CER (V1): the unchanged V1 schema.
- Migrating from V1 to V2: a practical, optional migration path.
- Verification Semantics: hash scope for both schemas.
- Attestation Node: how /api/attest dispatches by bundleType.
- Trust Model: what either schema does and does not prove.