# Migration Guide

## Purpose

This document describes how existing repos (DPE, MCO, and any repo using abi-template schemas) migrate to consuming contracts from `abi-control-core` as the single source of truth.

## Strategy: Dual-Write

During the transition period, use a **dual-write** strategy:

1. **Phase 1 — Shadow mode**: Both the original schema locations and `abi-control-core` exist. Validation uses the original schemas. CI also validates against `abi-control-core` schemas as a non-blocking check.

2. **Phase 2 — Flip**: Switch primary validation to `abi-control-core`. Keep original schema files as read-only copies. CI blocks on `abi-control-core` validation.

3. **Phase 3 — Cleanup**: Remove original schema copies. All validation flows through `abi-control-core`.

## Mapping: Template Repo to abi-control-core

| Template Location | abi-control-core Contract | Import Path |
|---|---|---|
| `.abi/evidence.schema.json` | `evidence.schema.json` | `abi_control_core.contracts.schema_path("evidence.schema.json")` |
| `agents/schemas/role_assignments.schema.json` | `role_assignments.schema.json` | `abi_control_core.contracts.schema_path("role_assignments.schema.json")` |
| `docs/ai/contracts/a2a-handoff.schema.json` | `a2a_handoff.schema.json` | `abi_control_core.contracts.schema_path("a2a_handoff.schema.json")` |
| `docs/ai/contracts/dlif-envelope.schema.json` | `dlif_envelope.schema.json` | `abi_control_core.contracts.schema_path("dlif_envelope.schema.json")` |
| `docs/ai/contracts/genai-telemetry.schema.json` | `genai_telemetry.schema.json` | `abi_control_core.contracts.schema_path("genai_telemetry.schema.json")` |
| `intent/schemas/aics.manifest.schema.json` | `aics_manifest.schema.json` | `abi_control_core.contracts.schema_path("aics_manifest.schema.json")` |
| `intent/schemas/aics.receipt.schema.json` | `aics_receipt.schema.json` | `abi_control_core.contracts.schema_path("aics_receipt.schema.json")` |
| `policies/schema/policy_registry.schema.json` | `policy_registry.schema.json` | `abi_control_core.contracts.schema_path("policy_registry.schema.json")` |
| `schemas/budget_receipt.schema.json` | `budget_receipt.schema.json` | `abi_control_core.contracts.schema_path("budget_receipt.schema.json")` |
| `schemas/context_manifest.schema.json` | `context_manifest.schema.json` | `abi_control_core.contracts.schema_path("context_manifest.schema.json")` |
| `schemas/crp.schema.json` | `crp.schema.json` | `abi_control_core.contracts.schema_path("crp.schema.json")` |
| `schemas/mrp.schema.json` | `mrp.schema.json` | `abi_control_core.contracts.schema_path("mrp.schema.json")` |
| `schemas/run_manifest.schema.json` | `run_manifest.schema.json` | `abi_control_core.contracts.schema_path("run_manifest.schema.json")` |
| `schemas/span.schema.json` | `span.schema.json` | `abi_control_core.contracts.schema_path("span.schema.json")` |
| `schemas/trace_event.schema.json` | `trace_event.schema.json` | `abi_control_core.contracts.schema_path("trace_event.schema.json")` |

## For DPE (abi-prd)

1. Add `abi-control-core` as a dependency.
2. Replace any inline schema validation with `validate_json()` from the SDK.
3. Use `canonical_hash_jcs_sha256()` for all manifest hashing.
4. Use `EvidencePackBuilder` for evidence pack creation.

## For MCO (abi-orchestrator)

1. Add `abi-control-core` as a dependency.
2. Replace local schema copies with imports from `abi_control_core.contracts`.
3. Pin the version of `abi-control-core` and verify `contracts.lock.json` in CI.

## Concept Mapping

| DPE/MCO Concept | abi-control-core Equivalent |
|---|---|
| Local schema files | `abi_control_core.contracts.schema_path(name)` |
| Custom JSON validation | `abi_control_core.sdk.validate.validate_json()` |
| Manual SHA-256 hashing | `abi_control_core.sdk.canonical_hash.canonical_hash_jcs_sha256()` |
| Ad-hoc evidence dirs | `abi_control_core.sdk.evidence_pack.EvidencePackBuilder` |
| Local eval scripts | `abi_control_core.sdk.evals.load_eval_suite()` / `write_eval_result()` |

## Version Pinning

```toml
# In consumer's pyproject.toml
dependencies = [
    "abi-control-core==0.1.0",
]
```

Consumers should pin to exact versions. Schema changes require version bumps in `abi-control-core` and coordinated updates across consumers.
