Cómo publicar una autoridad de ejecución validada¶

Utiliza esta guía cuando cambies el registro de reglas fiscales de Cadrumo o sus evidencias jurídicas. La publicación convierte las reglas modelo validadas de la Agencia Estatal de Administración Tributaria (AEAT) en la autoridad que lee el entorno de ejecución para realizar cálculos y exportar declaraciones. Es una operación de desarrollo y de publicación de versiones, no un comando aeat para contribuyentes.

La publicación es contenido generado. Consta de un descriptor pequeño y una base de datos SQLite direccionada por contenido. El descriptor registra el número de bytes y el resumen de la base de datos, además de la generación lógica; el manifiesto de la base de datos y las filas de componentes registran los recibos completos de fuente y compilador y el cierre de dependencias. El descriptor es el único punto de conmutación, de modo que un proceso instalado puede admitir una generación exacta y conservarla para una operación en curso. Es además la única fuente distribuida para el entorno de ejecución: el código instalado no abre el árbol de registro de autoría, no analiza TOML de perfiles ni mantiene una caché paralela de tablas extraídas de él.

Para conocer el formato de la publicación, las comprobaciones en ejecución, las clases de error y la interfaz de programación de aplicaciones (API) de Python, consulta Registro, fuentes jurídicas y API de Python. Para un fallo ordinario de un comando instalado, usa Diagnosticar y reparar.

Publicar¶

Parte de un registro cuyas declaraciones y cierre exacto de evidencias jurídicas estén listos para la comprobación completa de conformidad del registro.
Desde la raíz del repositorio, ejecuta:
```
uv run --no-sync python -m dev.registry.pipeline publish-authority
```
El comando compila cada modelo, declaración de perfil, catálogo, hecho, diseño de exportación y proyección de evidencias jurídicas y de origen en una autoridad completa, materializa las diferencias de autoría en revisiones tipadas completas, ejecuta la conformidad completa del registro contra el cierre exacto de evidencias e instala un candidato SQLite direccionado por contenido en .authority/authority-<database_sha256>.sqlite3. Solo después de que la base de datos se haya admitido y recorrido de forma independiente, reemplaza atómicamente .authority/authority.current.json. El comando imprime la ruta del descriptor y la generación lógica que ha registrado. --registry-root, --source-root, --profile-schema y --destination seleccionan otras entradas o un destino aislado para el candidato. Las raíces de registro o de fuentes personalizadas deben proporcionar --profile-schema de forma explícita. Sin --destination, la publicación escribe en la raíz de autoridad configurada y se niega en lugar de adivinar una ubicación cuando no hay ninguna configurada. No existe un comando de publicación solo de hechos ni reutilización selectiva de componentes: toda publicación correcta es una generación completa y nueva. --if-stale solo publica cuando el artefacto existente ya no registra el registro y las evidencias de origen vigentes, e imprime published=skipped-current cuando sí lo hace. Responder a esa pregunta lee el contenido sin compilar, por lo que cuesta segundos donde una publicación cuesta minutos, lo que hace que la receta asociada sea segura de ejecutar tras cada edición del registro:
```
just registry-publish-authority-if-authority-stale
```
No confirmes el resultado en el control de versiones. El descriptor y su base de datos direccionada por contenido son contenido generado, y el directorio en el que se publican está excluido del control de versiones: el cambio del registro se confirma por separado y cada copia de trabajo publica su propia autoridad a partir de él. No renombres una base de datos ni edites el descriptor a mano.

Dónde vive la autoridad¶

La autoridad publicada es contenido generado, por lo que una copia de trabajo la mantiene fuera del árbol empaquetado, en .authority/ en la raíz del repositorio. Ese directorio está excluido del control de versiones: se regenera a partir del registro confirmado, es grande y cambia con cada edición del registro.

CADRUMO_AUTHORITY_ROOT indica el directorio desde el que resolverla. Que la definas o no depende de cómo inicies el proceso:

Cómo ejecutas	La variable
Recetas de `just`, `python -m dev.*`, `pytest`	Se define por ti, apuntando a `.authority/` en el repositorio en el que estás.
El comando `aeat` desde una copia de trabajo	La defines tú.
El comando `aeat` desde un Cadrumo instalado	Nunca se define. La distribución lleva la autoridad.

La siembra es deliberada, no accidental: las herramientas de desarrollo saben dónde hay un repositorio y el producto no. El entorno de ejecución de Cadrumo nunca importa sus herramientas de desarrollo ni busca hacia arriba la raíz de un repositorio, de modo que nada del código instalado puede descubrir por su cuenta el .authority/ de una copia de trabajo. Para ejecutar el comando aeat contra la autoridad propia de una copia de trabajo, indícala en el entorno:

$env:CADRUMO_AUTHORITY_ROOT = "$PWD\.authority"

Un valor explícito siempre gana, de modo que una verificación de versión apuntada a otro árbol de autoridad nunca queda sustituida por la propia de la copia de trabajo.

Un Cadrumo instalado no necesita ninguna variable. La distribución lleva el descriptor y la base de datos exacta que este nombra en cadrumo/_data/registry/authority/, y un CADRUMO_AUTHORITY_ROOT sin definir resuelve ahí.

El directorio de candidatos no es la ubicación del entorno de ejecución¶

Para una comprobación aislada de paquete o de cohorte instalada, define CADRUMO_AUTHORITY_CANDIDATE_DIR con el directorio que contiene un candidato aceptado pero aún no promovido: su descriptor y la base de datos que ese descriptor selecciona. Las comprobaciones de empaquetado copian solo esos dos archivos en una instantánea de fuentes privada; nunca modifican la copia de trabajo y nunca recurren a un par promovido cuando la variable está definida.

Es una variable de desarrollo y de verificación de versiones. Un operador del producto nunca la define y, de forma deliberada, no forma parte de la configuración de la aplicación, por lo que no aparece en la referencia de entorno.

No es una grafía alternativa de CADRUMO_AUTHORITY_ROOT, y ambas no deben apuntar al mismo directorio. CADRUMO_AUTHORITY_ROOT indica dónde resuelve el producto la autoridad que puede leer; CADRUMO_AUTHORITY_CANDIDATE_DIR indica bytes que el entorno de ejecución no debe resolver hasta que se promuevan. Apuntar la raíz del entorno de ejecución a un candidato sin promover durante una compilación de versión es exactamente la confusión que la segunda variable existe para evitar.

La publicación mantiene el bloqueo del destino mientras captura el recibo de entrada, valida y serializa el conjunto completo de componentes, prepara y vuelca los bytes SQLite, verifica el resumen completo de la base de datos, comprueba el cierre del manifiesto y global, abre un candidato nuevo en modo solo lectura y vuelve a comprobar el recibo inmediatamente antes de reemplazar el descriptor. Si se rechaza la validación o la admisión, se encuentra una colisión de direccionamiento por contenido o cambia cualquier entrada de registro, evidencia, compilador o dependencia, el comando falla y deja el descriptor anterior intacto byte a byte. Corrige la entrada y vuelve a publicar.

La publicación también proyecta el sobre de compatibilidad compartido floor, horizon y el hard_ceiling opcional, además de los catálogos tipados de reglas de IVA, lugar de realización, países y territorios, bandas de recargo y ámbitos de apoderamiento. Todos los catálogos obligatorios deben estar completos. Los identificadores de modelo y del dominio fiscal aceptan su sintaxis estable en el código, pero su pertenencia corresponde a esta autoridad validada; un identificador ausente de su vocabulario publicado no se admite de forma silenciosa.

Verifica una versión candidata¶

Verifica directamente la generación SQLite seleccionada por el descriptor. La publicación debe admitir cada componente a través del lector indexado, coincidir con el recibo actual del compilador y superar las comprobaciones del límite de empaquetado. No existe un backend JSON de carga total para el entorno de ejecución ni una vía alternativa en ejecución.

Las comprobaciones de empaquetado preparan únicamente el descriptor y la base de datos que selecciona en su cohorte privada. Los archivos direccionados por contenido superados que conserve una copia de trabajo no son miembros del paquete candidato.

La medición comparada, solo de desarrollo, acepta ese mismo descriptor aislado y una línea base JSON explícita producida a partir del mismo AuthorityArtifact validado que produjo la base de datos candidata. El ayudante de línea base de desarrollo es dev.registry.eager_authority_baseline.write_eager_authority_baseline; invócalo desde el controlador del punto de control con ese artefacto exacto y mantén el archivo resultante fuera de los recursos del paquete distribuido. Ejecuta la medición comparada con:

uv run --no-sync python -m dev.registry.indexed_authority_benchmark `
  --descriptor <candidate>\authority.current.json `
  --json-baseline <work>\authority-eager-baseline.json `
  --backend both --runs 10

La línea base es evidencia de desarrollo únicamente: se genera a partir de la autoridad exacta validada en memoria, decodifica con carga total el grafo completo y lleva la identidad lógica del candidato. El ejecutor verifica los bytes exactos de la base de datos del descriptor antes de medir cualquiera de los dos lados; no lee el paquete distribuido, no descubre un archivo JSON predeterminado ni se convierte en una vía alternativa del entorno de ejecución. Cada carga de trabajo M100, M200 y M303 se informa de forma independiente; los umbrales de admisión, de memoria incremental y de contexto caliente siguen pendientes hasta que el punto de control C se ejecute sobre una cohorte de candidatos estable.

Comprueba que la publicación está actualizada¶

Ejecuta el control del registro:

just check-registry

Su paso de autoridad admite el descriptor y la base de datos que nombra en modo solo lectura. Termina con el código 1 y muestra una negativa en la salida de error estándar cuando el selector o la base de datos están obsoletos, son ilegibles, están malformados, han sido manipulados o ya no coinciden con el candidato activo. La negativa identifica los resúmenes de identidad registrado y esperado y el comando que vuelve a publicar la autoridad.

El recibo de fuentes depende del contenido de los archivos y de las rutas relativas a las raíces de registro y de fuentes, incluidas las evidencias complementarias mantenidas manualmente. El recibo del compilador cubre el compilador y el código relevante de Cadrumo, pyproject.toml, uv.lock, la versión mayor/menor de Python y las versiones instaladas de pydantic y pydantic-core. Una copia nueva del repositorio en el mismo entorno declarado es estable; un intérprete, conjunto de dependencias, manifiesto o compilador incompatibles dejan la publicación obsoleta y obligan a volver a publicar. El recibo de componentes vincula esos recibos de fuentes y de compilador a la generación de autoridad completa. El resumen de la base de datos protege de forma independiente todos los bytes de componentes almacenados, mientras que cada carga de componente bajo demanda comprueba su propio resumen de carga útil y su cierre de dependencias.

Recuperación ante una autoridad no válida¶

Cuando un flujo de trabajo instalado rechaza una autoridad no disponible, malformada, alterada o ilegible, detén el flujo de trabajo. La vía IndexedRegistryAuthority.operation() es solo de artefacto: no compila fuentes de autoría, no analiza TOML sin procesar, no repara una base de datos ni recurre al marco JSON retirado. El entorno de ejecución carga componentes tipados bajo demanda a través de la operación fijada a una generación y conserva solo valores acotados al ámbito de esa generación; el reemplazo de un descriptor inicia una nueva generación de autoridad mientras las operaciones existentes conservan su lector admitido.

En Windows, la publicación elimina una base de datos direccionada por contenido anterior solo después de poder adquirir un manejador exclusivo, de modo que un lector en curso aplaza la limpieza hasta una publicación posterior. En sistemas POSIX la publicación conserva los archivos de base de datos superados: allí desenlazar un archivo abierto funciona y no aporta una señal segura de arrendamiento entre procesos. El nombre de archivo inmutable impide que esos bytes conservados sean seleccionados por el descriptor actual.

Conserva el par descriptor/base de datos fallido cuando esté presente, junto con la versión del paquete, los resúmenes lógico y físico, la clase de error y los registros anonimizados.
Vuelve a publicar desde un registro validado y confirma que just check-registry pasa.
Reconstruye el paquete para que contenga el descriptor de reemplazo y la base de datos exacta que este nombra. El paquete no debe contener el registro de autoría, el TOML del esquema de perfiles ni el marco JSON retirado.

Eleva el caso mediante el sistema de incidencias del proyecto con la versión de la publicación, los resúmenes de la autoridad, la clase de error y el contexto de registro anonimizado. No incluyas nunca datos de contribuyentes.