fix: Spec Agent Runtime

specs/en/SPEC-013-Versioning-and-Compatibility-Model.md

@@ -0,0 +1,175 @@
+# 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.