> Esta traducción se ofrece por comodidad. El texto normativo es el original en inglés. # Recorrido del modelo y ubicaciones reservadas **Especificación del Meta-Universo** **ID del documento:** MU-V2-ARCH-017 **Título:** Estándar de arquitectura de meta-modelos - recorrido sin pérdidas y ubicaciones reservadas **Clase de documento:** normativo **Versión:** 2.0 (borrador) **Estado:** borrador de trabajo **Referencias normativas:** MMAS-Core, MMAS-Package, Versioning, Validation, Data-Mastership **Referencias informativas:** Traceability, AI-Agent-Guide, Repository-Structure **Copyright:** © Orkestron.AI **Licencia:** Apache-2.0 --- # 1. Propósito [MMAS-Package](MMAS-Package.md) define *dónde vive cada cosa* en el repositorio de un Meta-Modelo. Este documento define las dos garantías que la disposición por sí sola no puede dar: 1. **Recorrido sin pérdidas.** Un lector (persona o agente de IA) DEBERÁ poder recorrer el modelo entero bundle a bundle, capa a capa, visitando **cada archivo exactamente una vez**, sabiendo **qué significa cada archivo** y **demostrando que no se omitió nada**. 2. **Ubicaciones reservadas.** El contenido que no es una definición semántica (datos de origen en bruto, textos canónicos de origen, artefactos generados, instrucciones de operación) DEBERÁ residir en ubicaciones reservadas con significado predefinido, de modo que un lector nunca tenga que adivinar qué es un archivo. Junto con [Data-Mastership](Data-Mastership.md), que declara *quién posee la verdad* de cada conjunto de datos, esto hace que un Meta-Modelo sea plenamente legible por máquina: nada perdido, nada ambiguo, nada de autoridad desconocida. --- # 2. Alcance Esta especificación se aplica a: - repositorios de Meta-Modelos y Paquetes de distribución semántica; - manifiestos a nivel de repositorio, bundle y capa; - todos los archivos contenidos en un repositorio de modelo, sin excepción; - recorredores: cualquier herramienta o agente que enumere el contenido del modelo. No redefine la semántica de Objetos, Relaciones, Eventos, Contratos o Proyecciones; rige cómo se localizan, ordenan y clasifican los archivos que los transportan. --- # 3. Principios de diseño - **Un único punto de entrada.** Todo recorrido empieza en el mismo sitio; no hay conocimiento tribal sobre por dónde comenzar. - **Orden declarado.** El orden de lectura son datos, no convención: los manifiestos lo declaran, los recorredores lo siguen. - **Clasificación total.** Todo archivo queda clasificado. Un archivo cuyo significado no pueda determinarse a partir de los manifiestos y de esta especificación es un defecto, no una curiosidad. - **El significado viaja con la estructura.** Cada unidad enumerada lleva un significado declarado; un lector nunca debería necesitar abrir un archivo para descubrir qué clase de cosa es. - **Lo escrito, lo recolectado y lo generado nunca se mezclan.** Sus reglas de ciclo de vida difieren, así que difieren sus ubicaciones. --- # 4. El punto de entrada Un repositorio conforme DEBERÁ poder leerse partiendo de exactamente dos archivos en su raíz: 1. **`BOOTSTRAP.md`** - las instrucciones de operación: cómo leer este modelo, en qué orden, con qué herramientas, y qué se espera que un agente haga y no haga aquí. Un recorredor DEBERÍA leerlo primero. `BOOTSTRAP.md` PUEDE delegar en un directorio `bootstrap/` para instrucciones ampliadas (prompts de agentes, incorporación, listas de comprobación). El contenido de bootstrap NO DEBERÁ definir semántica; explica, nunca declara. 2. **`manifest.yaml`** - el punto de entrada para máquinas definido en [MMAS-Package](MMAS-Package.md) §5, ampliado por este documento con la declaración del recorrido (§5) y la lista de exclusiones (§7). Si `BOOTSTRAP.md` no existe, el recorredor procede solo con el manifiesto; la ausencia del manifiesto hace no conforme al repositorio. Los repositorios que ya usan un archivo de entrada propio de su ecosistema (por ejemplo `README.md`, `AGENTS.md` o `CLAUDE.md`) DEBERÍAN convertirlo en un puntero fino a `BOOTSTRAP.md` y `manifest.yaml` en lugar de en una segunda fuente de verdad. --- # 5. La declaración del recorrido El orden de recorrido se declara de arriba abajo: - El **manifiesto del repositorio** DEBERÁ declarar la lista ordenada de bundles (`bundles:` en orden de lectura). - Cada **manifiesto de bundle** (`bundle.yaml`) DEBERÁ declarar la responsabilidad semántica única del bundle y la lista ordenada de sus capas. - Cada **manifiesto de capa** (`layer.yaml`) DEBERÁ enumerar el contenido de la capa: archivos o patrones glob, cada uno con un **kind** (§8) y un **significado** de una línea. La enumeración PUEDE ser **centralizada en lugar de por capa**: un repositorio cuyos nombres de archivo llevan el kind por convención (por ejemplo `{kind}-{id}-{memo}.md`) PUEDE declarar la clasificación una sola vez, como lista ordenada de reglas de coincidencia en el manifiesto del repositorio (`kind_rules`): cada regla asocia un patrón glob a un kind y a un origen (§9); gana la primera regla que coincida. En esas reglas, el marcador `{prefix}` denota el segmento del nombre de archivo anterior al primer delimitador, de modo que una sola regla como `kind: "object/{prefix}"` clasifica toda una convención de nombres. Las reglas centralizadas equivalen a la enumeración por capa a efectos de la comprobación de cobertura (§7); un archivo que no coincida con ninguna regla es un huérfano en cualquier caso. Reglas de ordenación: - Los bundles DEBERÁN ordenarse de modo que un bundle aparezca **después** de todo bundle del que dependa (primero los cimientos). Las dependencias cíclicas entre bundles no son conformes. - Las capas dentro de un bundle DEBERÁN ordenarse del mismo modo. - Se permiten las referencias hacia delante (un archivo que menciona un concepto definido más adelante en el recorrido), pero el orden de *declaración* DEBERÁ seguir siendo el de dependencias primero, para que una única pasada secuencial lea las definiciones antes de su uso intensivo. Un recorredor que visita bundles, luego capas, luego archivos enumerados, cada cosa en el orden declarado, realiza el **recorrido canónico**. Dos recorredores que realicen el recorrido canónico sobre la misma versión del repositorio DEBERÁN visitar los mismos archivos en el mismo orden. --- # 6. Ubicaciones reservadas Más allá de los directorios estructurales de [MMAS-Package](MMAS-Package.md) §4 (`bundles/`, `imports/`, `mappings/`, `schemas/`, `examples/`, `diagrams/`, `docs/`, `tools/`), este documento reserva las siguientes ubicaciones. Cada una tiene un significado por defecto fijo; un recorredor PUEDE apoyarse en él sin más declaraciones. | Ubicación | Significado | Ciclo de vida | |----------|---------|-----------| | `BOOTSTRAP.md`, `bootstrap/` | Instrucciones de operación para lectores y agentes: cómo leer, actualizar y validar este modelo | Escrito | | `canon/` | Textos canónicos de origen que este modelo trata como verdad de base: doctrina, decisiones adoptadas, entradas normativas, especificaciones fuente | Escrito o adoptado; versionado; nunca generado | | `raw/` | Capturas sin procesar de sistemas externos: exportaciones, volcados, transcripciones, resultados de rastreo | Recolectado; NUNCA editado a mano | | `artifacts/` | Salidas derivadas y regenerables: vistas compiladas, documentos renderizados, índices computados, informes | Generado; NUNCA escrito a mano | | `sources.yaml` | El Registro de maestría de datos: el sistema de registro de cada conjunto de datos (véase [Data-Mastership](Data-Mastership.md)) | Escrito | Reglas: - **`canon/`** contiene los textos de los que el modelo *trata* o por los que está *obligado*, cuando esos textos deben viajar con el modelo. Las capas DEBERÁN referenciar los archivos del canon en lugar de parafrasearlos; si una afirmación de capa y un texto del canon entran en conflicto, dentro de ese modelo gana el texto del canon. - **`raw/`** DEBERÁ organizarse como `raw///...`. Cada directorio de conjunto de datos DEBERÁ llevar un archivo lateral de procedencia (`_provenance.yaml`: sistema origen, alcance, hora de extracción, herramienta de extracción, número de registros). El contenido en bruto es evidencia; corregirlo a mano destruye su valor probatorio y no es conforme. Las correcciones se hacen en el sistema origen (y luego se vuelve a recolectar) o en la capa semántica (como desviación anotada). - Las entradas de **`artifacts/`** DEBERÁN declarar su generador y sus entradas (basta un archivo lateral o una línea de cabecera). Un repositorio conforme puede borrar `artifacts/` por completo y reconstruirlo; si no puede, algo está mal archivado. - Un repositorio NO DEBERÍA inventar ubicaciones paralelas para estos fines (`_raw/`, `generated/`, `sources/` y similares). Donde existan disposiciones heredadas, el manifiesto DEBERÁ asociarlas a los significados reservados. --- # 7. La regla de completitud (ningún archivo se queda atrás) Todo archivo del repositorio DEBERÁ caer exactamente en una de tres clases: 1. **Enumerado** - coincide con la declaración de contenido de un manifiesto de capa (§5), o es un directorio estructural de MMAS-Package §4 con su papel definido; 2. **Reservado** - situado bajo una ubicación reservada de §6, heredando su significado por defecto; 3. **Excluido** - coincide con la lista de exclusiones del manifiesto (`exclude:`), que nombra archivos de infraestructura sin contenido semántico (interioridades del control de versiones, configuración de CI, ajustes del editor, cachés de compilación). La **comprobación de cobertura**: un recorredor DEBERÁ poder comparar el listado recursivo completo de archivos del repositorio con la unión de las tres clases. Los archivos sin clase («huérfanos») y los archivos en más de una clase («ambiguos») son fallos de validación. La comprobación de cobertura forma parte de la **validación estructural (V1)** de [Validation](Validation.md). La lista de exclusiones es una declaración, no un vertedero: excluir un archivo afirma que **no lleva significado de modelo**. Excluir contenido semántico para superar la comprobación de cobertura no es conforme. --- # 8. Tipos de archivo Todo archivo enumerado DEBERÁ llevar un kind. El vocabulario base: `object` · `relationship` · `event` · `contract` · `projection` · `canon` · `raw` · `artifact` · `mapping` · `import` · `schema` · `example` · `diagram` · `doc` · `tool` · `bootstrap` · `manifest` Los kinds responden a «qué es este archivo *en el modelo*», no a «de qué formato es». Un CSV puede ser `raw` (una exportación), `artifact` (un índice computado) u `object` (una tabla de definiciones); lo que decide cómo lo trata un lector es el kind, no la extensión. Los ecosistemas PUEDEN refinar el vocabulario con subtipos (`object/policy`, `doc/adr`) pero DEBERÁN conservar el kind base como prefijo. Los subtipos PUEDEN derivarse mecánicamente de convenciones de nombres declaradas mediante el marcador `{prefix}` de §5. --- # 9. Escrito, recolectado, generado Ortogonal al kind, todo archivo tiene exactamente un **origen**: - **Escrito** - redactado por una persona o por un agente que actúa como autor; se edita in situ; se revisa como código. - **Recolectado** - capturado de un sistema externo por una tubería; se reemplaza volviendo a recolectar; nunca se edita in situ. - **Generado** - computado a partir de otros archivos de este repositorio; se reemplaza regenerándolo; nunca se edita in situ. El origen queda implícito por la ubicación en los directorios reservados (§6) y DEBERÁ declararse en el manifiesto de capa en los demás casos. Editar in situ archivos recolectados o generados no es conforme: la corrección pertenece al sistema origen o al generador. Esta distinción es lo que hace exigible en la práctica la maestría (véase [Data-Mastership](Data-Mastership.md)): el origen de un archivo dice de inmediato al lector si *esta* copia puede llegar a ser la verdad. --- # 10. El recorrido canónico (informativo) Un recorredor conforme: 1. Lee `BOOTSTRAP.md` (contexto, restricciones, convenciones locales). 2. Lee `manifest.yaml`: identidad, versiones, orden de bundles, lista de exclusiones. 3. Lee `sources.yaml`: qué conjuntos de datos se dominan aquí y cuáles son espejos (con su frescura). 4. Visita `canon/` según se declare o referencie, de modo que la verdad de base quede cargada antes de interpretar. 5. Recorre los bundles en el orden declarado; dentro de cada uno, las capas en el orden declarado; dentro de cada una, los archivos enumerados, leyendo kind y significado antes que el contenido. 6. Resuelve `imports/` y `mappings/` cuando una capa los referencia. 7. Trata `raw/` como evidencia (se consulta, no se recita) y `artifacts/` como vistas desechables. 8. Ejecuta la comprobación de cobertura (§7) e informa de huérfanos, ambigüedades y espejos obsoletos. El recorrido está completo cuando todo archivo queda contabilizado y se conoce la autoridad de cada conjunto de datos. --- # 11. Requisitos nativos de IA Un repositorio conforme DEBERÁ permitir que un agente de IA, sin conocimiento fuera de banda: - encuentre el punto de entrada y las instrucciones de operación; - enumere todo el contenido en un orden determinista; - indique, para cualquier archivo, su kind, su origen y su significado de una línea; - demuestre cobertura: nombre todo archivo que no leyó y por qué (excluido, generado, evidencia en bruto); - distinga lo que puede editar (escrito, bajo la maestría del modelo) de lo que no debe (recolectado, generado, dominado externamente). Un agente que no pueda satisfacer el último punto DEBERÍA rechazar las operaciones de escritura sobre el modelo. --- # 12. Invariantes arquitectónicos El recorrido y la disposición DEBERÁN preservar: - la identidad y la propiedad semánticas; - la procedencia del contenido recolectado y generado; - la propiedad de punto de entrada único; - el determinismo del recorrido canónico; - el cumplimiento constitucional. La disposición y el recorrido NUNCA DEBERÁN redefinir el significado semántico; solo lo hacen alcanzable. --- # 13. Direcciones futuras Un recorredor de referencia (`mu-walk`) es el compañero natural de las herramientas existentes: realizaría el recorrido canónico, emitiría un informe de recorrido legible por máquina (archivos, kinds, orígenes, resultado de cobertura, frescura de espejos) y serviría como definición ejecutable de este documento. Un informe de recorrido podría pasar a formar parte del Paquete de distribución semántica, permitiendo a los consumidores verificar la completitud antes de confiar en un paquete. --- # Declaración final Un Meta-Modelo solo es tan fiable como lo sea la capacidad de un lector de saber que lo ha visto entero y de haber entendido qué es cada parte. Este estándar convierte esa capacidad de diligencia en contrato: un punto de entrada, un orden declarado, una clasificación total de los archivos, lugares reservados para instrucciones, canon, evidencia en bruto y artefactos derivados, y una comprobación de cobertura que hace imposible la pérdida silenciosa.