La Agencia Estatal de Administración Tributaria (AEAT) es la titular de la estructura oficial de los modelos. API significa interfaz de programación de aplicaciones.
Publicación de la autoridad de ejecución
La autoridad de ejecución es la publicación con resumen verificado del registro validado de la AEAT, destinada a los cálculos instalados y a las exportaciones de declaraciones. Es contenido generado con dos archivos: authority.current.json es un descriptor canónico pequeño, y su miembro database nombra la carga útil exacta authority-<database_sha256>.sqlite3 que hay junto a él. El descriptor y la base de datos se admiten juntos; la base de datos se abre en modo solo lectura y no se hidrata en un único grafo de modelo para todo el proceso.
El par se resuelve desde un directorio, y cuál sea ese directorio depende de cómo se haya instalado Cadrumo. Una distribución instalada lo lleva en cadrumo/_data/registry/authority/ y lo resuelve ahí sin configuración. Una copia de trabajo publica la suya en .authority/ en la raíz del repositorio, que está excluido del control de versiones, y la nombra con la variable de entorno CADRUMO_AUTHORITY_ROOT. Cuando esa variable está definida, es la respuesta completa: la resolución lee el directorio indicado y no recurre a la ubicación empaquetada, de modo que una copia de trabajo no puede responder en silencio con bytes empaquetados que creía haber reemplazado. Un directorio que no contiene descriptor es una negativa que nombra el comando de publicación, no una autoridad vacía. Consulta Publicar una autoridad de ejecución validada.
Término |
Significado |
|---|
Candidato validado |
Las entradas del registro y de las evidencias de origen aceptadas por el compilador de desarrollo. |
Recibo de fuentes |
Contenido del registro y de las evidencias de origen relativo a la raíz, incluidas las evidencias complementarias mantenidas manualmente. |
Recibo del compilador |
Código relevante de Cadrumo y del compilador, manifiestos de dependencias, versión mayor/menor de Python y versiones de Pydantic. |
Recibo de componentes |
Los recibos de fuentes y de compilador vinculados a una única generación de autoridad completa y nueva. |
Resumen de identidad |
La combinación direccionada por contenido de esos recibos, registrada para poder detectar un artefacto obsoleto. |
Descriptor de autoridad |
El selector reemplazado atómicamente que contiene el nombre base de la base de datos, el número de bytes, el SHA-256 físico y la generación lógica. |
Base de datos de autoridad |
La publicación SQLite direccionada por contenido que contiene los componentes tipados, las filas de dependencias y el manifiesto completo. |
El formato del descriptor es cadrumo-authority-descriptor-v1; sus miembros exactos son format, database, database_size, database_sha256 y logical_generation. El formato de la base de datos es cadrumo-authority-sqlite-v1. Su manifiesto vincula la generación lógica y el directorio completo de componentes. El resumen físico de la base de datos es a la vez la comprobación de admisión del descriptor y el nombre de archivo direccionado por contenido, de modo que una carga útil modificada o en colisión se rechaza antes de que empiece el trabajo del entorno de ejecución.
El comando de publicación de desarrollo es python -m dev.registry.pipeline publish-authority. Escribe en la raíz de autoridad configurada y se niega en lugar de elegir una ubicación cuando no hay ninguna configurada; su opción --destination selecciona en su lugar un directorio de autoridad aislado. Los valores personalizados de --registry-root o --source-root deben acompañarse de un --profile-schema explícito. El paquete del producto que lleva los comandos no tiene ningún comando que compile o repare esta publicación.
El recibo de fuentes pliega la ruta relativa a la raíz y el resumen de contenido de cada archivo de registro y de evidencia de origen. Los archivos de registro convierten CRLF en LF; la evidencia de origen es exacta byte a byte. El recibo del compilador también cambia con el código fuente relevante, pyproject.toml, uv.lock, la versión mayor/menor de Python o las versiones instaladas de pydantic y pydantic-core. Una copia nueva del repositorio en el mismo entorno declarado es estable, sin prometer identidad entre entornos de compilación incompatibles.
Cada carga útil de componente es una proyección canónica compacta de un valor de autoridad tipado. Los campos obligatorios siempre se escriben; un campo solo se omite cuando su valor tipado coincide con el valor predeterminado declarado por su esquema. La rehidratación estricta restaura esos valores predeterminados. Los discriminadores y las grafías de las uniones definidas por la autoría permanecen en la representación transmitida, por lo que la compactación nunca adivina qué variante tipada debe construir. Los decimales y las fechas son cadenas JSON cuando el esquema tipa un campo como decimal o fecha. Un valor de hecho gobernado puede ser texto, un entero, un decimal, un booleano o una fecha, y JSON no puede distinguirlos solo por su valor. Por tanto, todo valor de hecho no textual se escribe como un objeto con una etiqueta que identifica su tipo:
Valor del hecho |
Se escribe como |
|---|
Decimal |
{"$decimal": "0.40"}
|
Fecha |
{"$date": "2025-01-01"}
|
Entero |
{"$int": 5}
|
Booleano |
{"$bool": true}
|
Texto |
La cadena JSON sin etiqueta, por ejemplo "0.40" |
El entorno de ejecución descodifica la carga útil conforme al mismo esquema estricto que utiliza el compilador de desarrollo. Rechaza una etiqueta desconocida, un valor etiquetado malformado o no canónico y un valor de hecho no textual sin etiqueta; nunca infiere un tipo a partir de la forma de una cadena.
El compilador, y no el entorno de ejecución del producto, expande las diferencias de autoría en revisiones canónicas completas. La base de datos también lleva catálogos tipados del entorno de ejecución para la normativa del IVA, las reglas del lugar de realización, los alias de países, los territorios postales españoles, las exclusiones territoriales, las bandas de recargo y los ámbitos de apoderamiento. Son registros congelados del esquema, no bytes TOML incrustados ni un contenedor JSON sin tipo. Una escritura o lectura rechaza una autoridad cuando cualquier catálogo obligatorio del entorno de ejecución está vacío.
Los tipos de Modelo y del dominio fiscal validan la sintaxis estable de los identificadores sin cargar el árbol de autoría. La autoridad compilada es la fuente de pertenencia y valida esos identificadores frente a sus vocabularios publicados. La misma autoridad proyecta el sobre temporal de soporte compartido —floor, horizon y el hard_ceiling opcional— que se utiliza para admitir coordenadas compatibles.
La vía IndexedRegistryAuthority.operation() no compila fuentes, no carga el árbol de autoría sin procesar, no ofrece una ruta de reparación, ni un backend JSON de carga total para el entorno de ejecución, ni una vía alternativa JSON. Un descriptor o una base de datos que falten producen un error de disponibilidad. Un descriptor malformado, un miembro inesperado de la base de datos, un manifiesto incompleto o un componente no válido producen un error de formato. Una discrepancia de resumen del descriptor, de la base de datos o de un componente produce un error de integridad. Estos fallos ocurren antes de que continúen los cálculos o las declaraciones que dependen de la autoridad. Los componentes se cargan solo cuando una operación fijada los solicita; los valores correctos permanecen en una caché acotada al ámbito de la generación.
El punto de control C de desarrollo puede comparar el lector indexado con una línea base JSON explícita de dev.registry.indexed_authority_benchmark. La línea base se escribe a partir del mismo AuthorityArtifact validado en memoria que el candidato exacto, conserva su identidad de generación lógica y decodifica con carga total la misma semántica pública completa de la autoridad. La medición verifica los bytes físicos de la base de datos del descriptor antes de medir. La línea base es un accesorio de medición, no un módulo del producto ni una vía alternativa distribuida. Los resultados numéricos de latencia y memoria siguen pendientes hasta que el punto de control C se ejecute sobre un candidato estable; esta descripción de la API no implica ninguna ganancia medida.
El contrato del entorno de ejecución es para ruedas instaladas en un sistema de archivos ordinario, donde el descriptor y la base de datos SQLite tienen rutas físicas estables. No se admite la ejecución directa por importación desde un zip: SQLite no puede abrir un miembro de archivo comprimido como su base de datos de solo lectura.
python -m dev.registry.conformance integrity rechaza una publicación descriptor/base de datos cuyo resumen de identidad registrado difiere de la identidad del registro activo y de su entorno de compilación. Consulta Publicar una autoridad de ejecución validada para conocer el comando canónico, las garantías de publicación, las comprobaciones de actualidad y la ruta de recuperación.