Com publicar una autoritat d’execució validada

Feu servir aquesta guia quan canvieu el registre de regles fiscals de Cadrumo o les seves evidències jurídiques. La publicació converteix les regles modelo validades de l’Agencia Estatal de Administración Tributaria (AEAT) en l’autoritat que llegeix l’entorn d’execució per fer càlculs i exportar declaracions. És una operació de desenvolupament i de publicació de versions, no una ordre aeat per a contribuents.

La publicació és contingut generat. Consta d’un descriptor petit i una base de dades SQLite adreçada per contingut. El descriptor registra el nombre de bytes i el resum de la base de dades, a més de la generació lògica; el manifest de la base de dades i les files de components registren els rebuts complets de font i compilador i el tancament de dependències. El descriptor és l’única vora de commutació, de manera que un procés instal·lat pot admetre una generació exacta i conservar-la per a una operació en curs. També és l’única font distribuïda per a l’entorn d’execució: el codi instal·lat no obre l’arbre de registre d’autoria, no analitza TOML de perfils ni manté una memòria cau paral·lela de taules extretes d’ell.

Per conèixer el format de la publicació, les comprovacions en execució, les classes d’error i la interfície de programació d’aplicacions (API) de Python, consulteu Registre, fonts jurídiques i API de Python. Per a una fallada ordinària d’una ordre instal·lada, feu servir Diagnosticar i reparar.

Publica

1. Comenceu per un registre les declaracions del qual i el tancament exacte d’evidències jurídiques estiguin preparats per a la comprovació completa de conformitat del registre.

2. Des de l’arrel del repositori, executeu:

   uv run --no-sync python -m dev.registry.pipeline publish-authority
   

   L’ordre compila cada modelo, declaració de perfil, catàleg, fet, disseny d’exportació i projecció d’evidències jurídiques i d’origen en una autoritat completa, materialitza les diferències d’autoria en revisions tipades completes, executa la conformitat completa del registre contra el tancament exacte d’evidències i instal·la un candidat SQLite adreçat per contingut a .authority/authority-<database_sha256>.sqlite3. Només després que la base de dades s’hagi admès i recorregut de manera independent, reemplaça atòmicament .authority/authority.current.json. L’ordre imprimeix el camí del descriptor i la generació lògica que ha registrat. --registry-root, --source-root, --profile-schema i --destination seleccionen altres entrades o un destí aïllat per al candidat. Les arrels de registre o de fonts personalitzades han de proporcionar --profile-schema de manera explícita. Sense --destination, la publicació escriu a l’arrel d’autoritat configurada i es nega en lloc d’endevinar una ubicació quan no n’hi ha cap configurada. No hi ha cap ordre de publicació només de fets ni reutilització selectiva de components: tota publicació correcta és una generació completa i nova. --if-stale només publica quan l’artefacte existent ja no registra el registre i les evidències d’origen vigents, i imprimeix published=skipped-current quan sí que ho fa. Respondre aquesta pregunta llegeix el contingut sense compilar, de manera que costa segons on una publicació costa minuts, cosa que fa que la recepta associada sigui segura d’executar després de cada edició del registre:

   just registry-publish-authority-if-authority-stale
   

3. No confirmeu el resultat al control de versions. El descriptor i la seva base de dades adreçada per contingut són contingut generat, i el directori on es publiquen està exclòs del control de versions: el canvi del registre es confirma a part i cada còpia de treball publica la seva pròpia autoritat a partir d’ell. No reanomeneu cap base de dades ni editeu el descriptor a mà.

On viu l’autoritat

L’autoritat publicada és contingut generat, per això una còpia de treball la manté fora de l’arbre empaquetat, a .authority/ a l’arrel del repositori. Aquest directori està exclòs del control de versions: es regenera a partir del registre confirmat, és gran i canvia amb cada edició del registre.

CADRUMO_AUTHORITY_ROOT indica el directori des del qual resoldre-la. Que la definiu o no depèn de com inicieu el procés:

Com executeu	La variable
Receptes de just, python -m dev.*, pytest	Es defineix per vosaltres, apuntant a .authority/ al repositori on us trobeu.
L’ordre aeat des d’una còpia de treball	La definiu vosaltres.
L’ordre aeat des d’un Cadrumo instal·lat	No es defineix mai. La distribució porta l’autoritat.

La sembra és deliberada, no accidental: les eines de desenvolupament saben on hi ha un repositori i el producte no. L’entorn d’execució de Cadrumo no importa mai les seves eines de desenvolupament ni cerca cap amunt l’arrel d’un repositori, de manera que res del codi instal·lat no pot descobrir pel seu compte el .authority/ d’una còpia de treball. Per executar l’ordre aeat contra l’autoritat pròpia d’una còpia de treball, indiqueu-la a l’entorn:

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

Un valor explícit sempre guanya, de manera que una verificació de versió apuntada a un altre arbre d’autoritat no queda mai substituïda per la pròpia de la còpia de treball.

Un Cadrumo instal·lat no necessita cap variable. La distribució porta el descriptor i la base de dades exacta que aquest anomena a cadrumo/_data/registry/authority/, i un CADRUMO_AUTHORITY_ROOT sense definir resol allà.

El directori de candidats no és la ubicació de l’entorn d’execució

Per a una comprovació aïllada de paquet o de cohort instal·lada, definiu CADRUMO_AUTHORITY_CANDIDATE_DIR amb el directori que conté un candidat acceptat però encara no promogut: el seu descriptor i la base de dades que aquest descriptor selecciona. Les comprovacions d’empaquetatge copien només aquests dos fitxers en una instantània de fonts privada; no modifiquen mai la còpia de treball i no recorren mai a un parell promogut quan la variable està definida.

És una variable de desenvolupament i de verificació de versions. Un operador del producte no la defineix mai i, de manera deliberada, no forma part de la configuració de l’aplicació, per això no apareix a la referència d’entorn.

No és una grafia alternativa de CADRUMO_AUTHORITY_ROOT, i totes dues no han d’apuntar al mateix directori. CADRUMO_AUTHORITY_ROOT indica on resol el producte l’autoritat que pot llegir; CADRUMO_AUTHORITY_CANDIDATE_DIR indica bytes que l’entorn d’execució no ha de resoldre fins que es promoguin. Apuntar l’arrel de l’entorn d’execució a un candidat sense promoure durant una compilació de versió és exactament la confusió que la segona variable existeix per evitar.

La publicació manté el blocatge del destí mentre captura el rebut d’entrada, valida i serialitza el conjunt complet de components, prepara i bolca els bytes SQLite, verifica el resum complet de la base de dades, comprova el tancament del manifest i global, obre un candidat nou en mode només de lectura i torna a comprovar el rebut immediatament abans de reemplaçar el descriptor. Si es rebutja la validació o l’admissió, es troba una col·lisió d’adreçament per contingut o canvia qualsevol entrada de registre, evidència, compilador o dependència, l’ordre falla i deixa el descriptor anterior intacte byte a byte. Corregiu l’entrada i torneu a publicar.

La publicació també projecta l’envolupant de compatibilitat compartida floor, horizon i hard_ceiling opcional, així com els catàlegs tipats de temps d’execució per a les regles d’IVA, el lloc de prestació, els països i territoris, les bandes de recàrrec i els àmbits d’apoderament. Tots els catàlegs requerits han d’estar emplenats. Els identificadors de modelo i de domini fiscal accepten la sintaxi estable en el codi, però la pertinença correspon a aquesta autoritat validada; un identificador absent del seu vocabulari publicat no s’hi admet silenciosament.

Verifiqueu una versió candidata

Verifiqueu directament la generació SQLite seleccionada pel descriptor. La publicació ha d’admetre cada component a través del lector indexat, coincidir amb el rebut actual del compilador i superar les comprovacions del límit d’empaquetatge. No hi ha cap dorsal JSON de càrrega total per a l’entorn d’execució ni cap via alternativa en execució.

Les comprovacions d’empaquetatge preparen únicament el descriptor i la base de dades que selecciona a la seva cohort privada. Els fitxers adreçats per contingut superats que conservi una còpia de treball no són membres del paquet candidat.

El mesurament comparat, només de desenvolupament, accepta aquest mateix descriptor aïllat i una línia base JSON explícita produïda a partir del mateix AuthorityArtifact validat que va produir la base de dades candidata. L’ajudant de línia base de desenvolupament és dev.registry.eager_authority_baseline.write_eager_authority_baseline; invoqueu-lo des del controlador del punt de control amb aquest artefacte exacte i mantingueu el fitxer resultant fora dels recursos del paquet distribuït. Executeu el mesurament comparat amb:

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ínia base és evidència de desenvolupament únicament: es genera a partir de l’autoritat exacta validada en memòria, descodifica amb càrrega total el graf complet i porta la identitat lògica del candidat. L’executor verifica els bytes exactes de la base de dades del descriptor abans de mesurar qualsevol dels dos costats; no llegeix el paquet distribuït, no descobreix cap fitxer JSON predeterminat ni es converteix en una via alternativa de l’entorn d’execució. Cada càrrega de treball M100, M200 i M303 s’informa de manera independent; els llindars d’admissió, de memòria incremental i de context calent continuen pendents fins que el punt de control C s’executi sobre una cohort de candidats estable.

Comproveu que la publicació està actualitzada

Executeu el control del registre:

just check-registry

El seu pas d’autoritat admet el descriptor i la base de dades que anomena en mode només de lectura. Acaba amb el codi 1 i mostra una negativa a la sortida d’error estàndard quan el selector o la base de dades estan obsolets, són illegibles, estan mal formats, han estat manipulats o ja no coincideixen amb el candidat actiu. La negativa identifica els resums d’identitat registrat i esperat i l’ordre que torna a publicar l’autoritat.

El rebut de fonts depèn del contingut dels fitxers i dels camins relatius a les arrels de registre i de fonts, incloses les evidències complementàries mantingudes manualment. El rebut del compilador cobreix el compilador i el codi relevant de Cadrumo, pyproject.toml, uv.lock, la versió major/menor de Python i les versions instal·lades de pydantic i pydantic-core. Una còpia nova del repositori en el mateix entorn declarat és estable; un intèrpret, conjunt de dependències, manifest o compilador incompatibles deixen la publicació obsoleta i obliguen a tornar a publicar. El rebut de components vincula aquests rebuts de fonts i de compilador a la generació d’autoritat completa. El resum de la base de dades protegeix de manera independent tots els bytes de components emmagatzemats, mentre que cada càrrega de component sota demanda comprova el seu propi resum de càrrega útil i el seu tancament de dependències.

Recupereu-vos d’una autoritat no vàlida

Quan un flux de treball instal·lat rebutja una autoritat no disponible, mal formada, alterada o illegible, atureu el flux de treball. La via IndexedRegistryAuthority.operation() és només d’artefacte: no compila fonts d’autoria, no analitza TOML sense processar, no repara cap base de dades ni recorre al marc JSON retirat. L’entorn d’execució carrega components tipats sota demanda a través de l’operació fixada a una generació i conserva només valors limitats a l’àmbit d’aquesta generació; el reemplaçament d’un descriptor inicia una generació d’autoritat nova mentre les operacions existents conserven el seu lector admès.

A Windows, la publicació elimina una base de dades adreçada per contingut anterior només després de poder adquirir un manipulador exclusiu, de manera que un lector en curs ajorna la neteja fins a una publicació posterior. A sistemes POSIX la publicació conserva els fitxers de base de dades superats: allà desenllaçar un fitxer obert funciona i no aporta cap senyal segur d’arrendament entre processos. El nom de fitxer immutable impedeix que aquests bytes conservats siguin seleccionats pel descriptor actual.

1. Conserveu el parell descriptor/base de dades fallit quan hi sigui, juntament amb la versió del paquet, els resums lògic i físic, la classe d’error i els registres anonimitzats.

2. Torneu a publicar des d’un registre validat i confirmeu que just check-registry passa.

3. Reconstruïu el paquet perquè contingui el descriptor de reemplaçament i la base de dades exacta que aquest anomena. El paquet no ha de contenir el registre d’autoria, el TOML de l’esquema de perfils ni el marc JSON retirat.

Eleveu el cas mitjançant el sistema d’incidències del projecte amb la versió de la publicació, els resums de l’autoritat, la classe d’error i el context de registre anonimitzat. No incloeu mai dades de contribuents.