> Esta traducción se ofrece por comodidad. El texto normativo es el original en inglés. # Migración semántica **Especificación del Meta-Universo** **ID del documento:** MU-V2-ARCH-010 **Título:** Estándar de migración semántica (SMS) **Clase de documento:** normativo **Versión:** 2.0 (borrador) **Estado:** borrador de trabajo **Referencias normativas:** [MMAS-Core](../02-architecture/MMAS-Core.md), [Versioning](../02-architecture/Versioning.md), [MMAS-Interchange](../02-architecture/MMAS-Interchange.md), [Event](../04-core-concepts/Event.md), [Traceability](../02-architecture/Traceability.md), RFC 2119 **Referencias informativas:** [Migration from v1](../07-guides/Migration-from-v1.md), [Naming-Conventions](../02-architecture/Naming-Conventions.md) **Copyright:** © Orkestron.AI **Licencia:** Apache-2.0 --- # 1. Propósito Este documento define el **Estándar de migración semántica (SMS)**: las reglas normativas bajo las cuales un Meta-Modelo pasa de una versión, estructura o vocabulario a otro *sin perder ni cambiar el significado en silencio*. La guía [Migration from v1](../07-guides/Migration-from-v1.md) presenta la migración como una actividad evolutiva en tres niveles y menciona SMS como su formalización futura. Este documento materializa el concepto: especifica los niveles de migración, registra toda migración como [Evento](../04-core-concepts/Event.md) trazable, define un **manifiesto de migración** y fija el invariante de que *el significado NO DEBERÁ cambiar sin un evento de migración explícito*. --- # 2. Alcance Esta especificación se aplica a: - la migración de Meta-Modelos, Bundles, Capas, Objetos, Propiedades, Relaciones, Eventos, Contratos y Proyecciones entre versiones; - el renombrado, la división, la fusión y la reclasificación de conceptos; - la reorganización estructural de repositorios y documentos; - la revinculación federativa de un modelo migrado. No define la tecnología de almacenamiento usada para persistir los registros de migración, ni el proceso de revisión humana (véase [Migration from v1](../07-guides/Migration-from-v1.md)). La huella semántica y la canonicalización en que se apoya se definen en [MMAS-Interchange](../02-architecture/MMAS-Interchange.md). --- # 3. Los tres niveles de migración Una migración DEBERÁ razonarse en tres niveles distintos, que PUEDEN avanzar de forma independiente y a distinto ritmo: - **Migración estructural** - la *estructura de repositorio y documentos*: disposición de carpetas, organización de archivos, identificadores y cabeceras de documento. El cambio estructural PUEDE ser silencioso: por sí solo no cambia el significado. - **Migración semántica** - la *terminología, los conceptos, las relaciones y las reglas*: cómo un concepto se renombra, divide, fusiona, reclasifica o redefine. El cambio semántico NO DEBERÁ ser silencioso (véase la Sección 5). - **Migración de federación** - *cómo interactúa el modelo migrado con otros Universos*: revincular confianza, identidad, correspondencias semánticas, contratos y sincronización de proyecciones para que el modelo pueda reincorporarse al ecosistema. Una migración completa DEBERÁ abordar los tres niveles. La migración estructural mueve los archivos; la migración semántica preserva el significado dentro de ellos; la migración de federación restaura cómo se relaciona el modelo con los demás. --- # 4. La migración como operación trazable y explicable en reverso Una migración DEBERÁ registrarse como uno o más [Eventos](../04-core-concepts/Event.md) inmutables de categoría *evento semántico* (y, cuando corresponda, *evento de ciclo de vida*). Cada evento de migración DEBERÁ declarar: - su sujeto: el artefacto que se migra; - la **versión de origen** y la **versión de destino**; - una referencia al **manifiesto de migración** que la gobierna (Sección 6); - su [procedencia](../02-architecture/Traceability.md): quién realizó la migración y con qué autoridad. Una migración DEBERÁ ser: - **trazable** - todo cambio DEBERÁ poder seguirse desde su origen hasta su resultado a través del evento de migración y su manifiesto; - **explicable en reverso** - el estado previo, la justificación y la correspondencia DEBERÁN registrarse para que el cambio pueda entenderse y, cuando la correspondencia sea invertible, revertirse. SMS no exige que toda migración sea *ejecutable* en sentido inverso; exige que toda migración sea *explicable* en sentido inverso. Las correcciones de una migración DEBERÁN expresarse a su vez como nuevos eventos de migración que referencien al evento corregido. Un evento de migración NO DEBERÁ editarse ni eliminarse una vez registrado. --- # 5. La regla de ningún cambio de significado silencioso El significado NO DEBERÁ cambiar sin un evento de migración explícito. En concreto: - Un cambio que altere la [huella semántica](../02-architecture/MMAS-Interchange.md) de cualquier concepto DEBERÁ ir acompañado de un evento de migración y de una entrada en el manifiesto de migración que lo clasifique. - Renombrar un concepto DEBERÁ producir un nuevo [nombre semántico canónico (CSN)](../02-architecture/Naming-Conventions.md); el CSN antiguo NO DEBERÁ reescribirse en silencio, y la correspondencia antiguo → nuevo DEBERÁ registrarse en el manifiesto. - Un cambio que solo afecte a contenido no semántico (nombres visibles, descripciones, documentación, ubicación de archivos) NO DEBERÁ cambiar la huella y PUEDE realizarse como migración estructural sin evento de migración semántica. La asimetría es deliberada: **al cambio estructural se le permite ser silencioso; al cambio semántico, no.** --- # 6. El manifiesto de migración Toda migración semántica DEBERÁ estar gobernada por un **manifiesto de migración** legible por máquina que describa, de forma declarativa, cómo se traslada el significado de una versión a la siguiente. Un manifiesto DEBERÁ contener: | Campo | Significado | |-------|---------| | `fromVersion` | La versión de origen del Meta-Modelo. | | `toVersion` | La versión de destino del Meta-Modelo. | | `fromFingerprint` | La [huella semántica](../02-architecture/MMAS-Interchange.md) del modelo de origen. | | `toFingerprint` | La huella semántica del modelo de destino. | | `conceptMappings` | El conjunto ordenado de conceptos cambiados; cada uno asocia un CSN de origen a su CSN o CSN de destino y a un tipo de cambio. | | `compatibility` | La clasificación global de compatibilidad (Sección 7). | | `events` | Referencias al evento o eventos de migración que aplican este manifiesto. | | `provenance` | Autor, autoridad y hora de creación del manifiesto. | Cada entrada de `conceptMappings` DEBERÁ declarar un **tipo de cambio**: `renamed`, `split`, `merged`, `reclassified`, `redefined`, `added`, `deprecated` o `removed`, junto con los CSN de origen y destino que relaciona. Un concepto sin cambios no necesita aparecer; su ausencia de `conceptMappings` DEBERÁ significar *significado preservado sin cambios*. Un manifiesto de migración DEBERÁ poder expresarse él mismo como [MUIF](../02-architecture/MMAS-Interchange.md), de modo que pueda intercambiarse, obtener huella y validarse como cualquier otro artefacto. --- # 7. Clasificación de compatibilidad Toda migración DEBERÁ declarar una clasificación de compatibilidad, alineada con la clasificación de cambios semánticos de [Versioning](../02-architecture/Versioning.md): - **Compatible** - ningún concepto cambia de significado; los consumidores del modelo de origen pueden consumir el de destino sin adaptación. La huella del modelo PUEDE cambiar solo por conceptos aditivos y no rupturistas. - **Condicionalmente compatible** - el significado se preserva pero cambia la representación (por ejemplo, un renombrado con su correspondencia de CSN registrada); los consumidores PUEDEN seguir usando el origen a través de las correspondencias del manifiesto. - **Rupturista** - al menos un concepto cambia de significado, se elimina o se fusiona de un modo que pierde distinciones; los consumidores DEBERÁN adaptarse, guiados por los `conceptMappings` del manifiesto. La clasificación DEBERÁ poder derivarse de los `conceptMappings` y DEBERÁ ser coherente con el cambio en las huellas semánticas. --- # 8. Preservación de la identidad canónica La migración NO DEBERÁ romper la **identidad canónica**. - La identidad estable de un Objeto, Relación, Evento o Contrato DEBERÁ sobrevivir sin cambios a una migración, incluso cuando cambien su CSN o su nombre visible. - Cuando un concepto se divide, cada concepto resultante DEBERÁ declarar su derivación de la identidad original; cuando se fusionan conceptos, el concepto resultante DEBERÁ referenciar cada identidad de origen que absorbe. - Los [Eventos](../04-core-concepts/Event.md) históricos y las versiones anteriores DEBERÁN seguir disponibles y NO DEBERÁN ser reescritos por la migración. La continuidad de la identidad es lo que permite rastrear el [linaje semántico](../02-architecture/Traceability.md) a través de una frontera de versión. --- # 9. Ejemplo resuelto: Galaxia de v1 → Espacio de nombres de v2 La evolución canónica de v1 a v2 renombra el concepto organizador de v1 *Galaxia* al [Espacio de nombres](../02-architecture/Naming-Conventions.md) de v2. El significado, *cómo se organizan y publican los conceptos*, se preserva; solo cambian el nombre y su estatus de gobernanza. Es una migración semántica **condicionalmente compatible**. Esquema del manifiesto de migración: ```text fromVersion : 1.4 toVersion : 2.0 fromFingerprint : sha256: toFingerprint : sha256: compatibility : Conditionally Compatible conceptMappings : - source: galaxy. target: namespace. kind: renamed - source: object. target: metaObject. kind: renamed - source: identity. target: canonicalIdentity. kind: renamed - source: projection. (unchanged — omitted) events : [ evt:migration/1.4→2.0/namespace ] provenance : { author: , authority: , at: