# SPEC-013 — Versioning and Compatibility Model

## Agent Platform OCI

Version: 1.0.0


---

## Reading guide

each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.

The document structure is:

1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.

---


# 1. Concept

Versionamento Defines como The platform evolui without quebrar projetos existing. compatibility Defines quais versions of framework, runtime, gateways, contracts, templates, prompts, tools and evaluator can operar juntas.

# 2. Problem addressed

without Model of versionamento:

- a change em GatewayRequest quebra canais;
- a change em MCP tool quebra Agents;
- a prompt alterado muda comportamento without rastreabilidade;
- evaluator muda score without History;
- templates ficam incompatíveis with runtime;
- Production Uses imagem `latest` without control.

# 3. Semantic Versioning

Formato:

```text
MAJOR.MINOR.PATCH
```

Rules:

| Parte | Significado |
| --- | --- |
| MAJOR | change incompatível. |
| MINOR | new Capacity compatível. |
| PATCH | Correction without change of Contract. |


# 4. artifacts versionados

| Artefato | Model |
| --- | --- |
| agent_framework | SemVer |
| agent_runtime | SemVer alinhado ao framework |
| agent_gateway | SemVer + Docker tag |
| channel_gateway | SemVer + Docker tag |
| ai_gateway | SemVer + Docker tag |
| mcp_gateway | SemVer + Docker tag |
| templates | Version of the plataforma |
| contracts | contract-name-vN |
| prompts | SemVer |
| datasets | SemVer |
| guardrails | SemVer por código |
| judges | SemVer por judge |
| mcp_tools | SemVer por tool |
| evaluator | SemVer |
| certification_suite | SemVer + ruleset version |


# 5. Contract versioning

Examples:

```text
gateway-request-v1
business-context-v1
tool-invocation-v1
llm-request-v1
```

allowed na mesma Version major:

- adicionar fields optional;
- adicionar metadata;
- adicionar enum documentado.

No allowed:

- remover field Required;
- mudar tipo;
- mudar significado;
- alterar regra obrigatória.

# 6. Compatibility Matrix

```yaml
compatibility:
  - framework: "1.4.x"
    runtime: "1.4.x"
    agent_gateway: "1.4.x"
    supported: true
  - framework: "1.4.x"
    runtime: "2.0.x"
    supported: false
```

# 7. Policy of depreciação

Ciclo:

```text
Active → Deprecated → Retired
```

Período recommended:

```text
12 meses
```

# 8. Policy of migração

changes major exigem:

- migration guide;
- compatibility matrix;
- rollback strategy;
- certification;
- evaluator;
- release notes.

# 9. Estratégia of rollback

Rollback must considerar:

- imagem Docker;
- Version of the pacote;
- Version of the YAMLs;
- Version of the Contract;
- migration of banco;
- dataset;
- prompts.

# 10. Common errors

| Error | Impact | Correction |
| --- | --- | --- |
| use latest em Production | Deploy No reprodutível. | use tag explícita. |
| Mudar prompt without Version | without rastreabilidade. | Versionar prompt. |
| Adicionar field Required em Contract v1 | Quebra clientes. | create v2. |
| Atualizar evaluator without baseline | Scores No comparáveis. | Registrar Version and metodologia. |


# 11. Acceptance criteria

- [ ] all os Components têm Version.
- [ ] contracts têm Version independente.
- [ ] Matriz of compatibility publicada.
- [ ] Release notes publicadas.
- [ ] Migrações major possuem guide.
- [ ] Rollback definido.
- [ ] Prompts and datasets versionados.
- [ ] Evaluator and certification registram Version.