Esquema del archivo de bloqueo por Release de Aggrega
Referencia generada. No la edites a mano — regenérala a partir del JSON Schema publicado.
ID del esquema: https://aggrega.ai/schemas/lockfile-v1beta1.schema.json
Archivo de bloqueo generado automáticamente que fija cada URI resuelto a partir de una Release para compilaciones futuras deterministas. Se encuentra en <release-stem>.lock junto a <release-stem>.yaml; lo produce aggrega pull --release <release>; lo consume aggrega build --release <release>. Dos formas de procedencia registran dos relaciones distintas en el grafo de dependencias: referenced_from (lista de cadenas) aparece en entities, como rutas con puntos de los sitios de autoría que registran desde qué lugar de la Release / Aggregate / Manifest / .aggrega-config.yaml se incorporó cada URI, y en plugins, como la referencia de cada entidad Plugin a través de la cual se llegó a un artefacto; consumers (lista de registros {consumer_uri, fragments}) aparece en schema_libraries, mapping_libraries, workload_libraries y artifact_libraries para registrar qué entidad del catálogo hace referencia a qué fragmentos <entry-name> de una biblioteca — la forma estructurada hace rastreables los diffs de los consumidores afectados por un cambio de versión de una biblioteca sin volver a resolver la Release. Disciplina de evolución del esquema: añadir una nueva sección de nivel superior es SemVer-MINOR (aditivo); añadir un nuevo campo dentro de una sección existente es SemVer-MINOR; eliminar una clave o endurecer una restricción es SemVer-MAJOR.
Tipo de nivel superior: object
Propiedades
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
entities | object[] | no | Entidades del catálogo alcanzables desde esta Release: Component, Feature, Recipe, FeatureRecipe, Plugin, Aggregate, el Aggregate y el Manifest propios de la Release, y el Manifest que ese Manifest extiende. Cada entrada se identifica por su kind junto con su URI canónico, de modo que dos entidades de tipos distintos que comparten un nombre — por ejemplo, un Aggregate y un Manifest llamados ambos imported/flow — son dos entradas, cada una contrastada con su propio digest. Cada una registra la versión resuelta, el digest de lo que lleva la entidad y los orígenes en los sitios de autoría (referenced_from) que incorporaron el URI al cierre de dependencias de la Release. Un lockfile cuyas entradas no llevan ningún kind está desactualizado: aggrega pull --release <release> lo vuelve a escribir. Valor predeterminado: [] |
external_inputs | ExternalInput[] | no | Entradas remotas fijadas en el almacén de entradas direccionado por contenido en el momento de la adquisición — contenido que el renderizado de un plugin de proveedor consume desde fuera del espacio de trabajo, como documentos de esquema remotos o dependencias de chart no vendorizadas. Cada entrada fija una URL al digest que nombra sus bytes en el almacén. La compilación sirve las entradas fijadas desde el almacén y lee esta sección sin acceso a la red. Valor predeterminado: [] |
generated_at | string | sí | Marca de tiempo RFC 3339 del pull que produjo este archivo de bloqueo; el patrón ajusta el valor a esa forma cuando se carga el archivo de bloqueo. Procedencia de diagnóstico — registra el momento de la resolución según el reloj del sistema. Cambia intencionadamente entre pulls; no forma parte de la garantía de identidad byte a byte del archivo de bloqueo. Patrón: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$. |
mapping_libraries | LibraryEntry[] | no | Entradas de MappingLibrary a las que llega el cierre de dependencias de la Release a través de los sitios valuesMapping: { $import: ... } de Recipe / FeatureRecipe. La lista consumers de cada entrada registra qué entidad del catálogo hace referencia a qué fragmentos <entry-name> de la biblioteca — un registro estructurado que hace rastreables los diffs del impacto de un cambio de versión de la biblioteca sin volver a resolver la Release. Valor predeterminado: [] |
mutators | object[] | no | Vinculaciones de gobernanza con rol de transformación resueltas, en el orden en que se escribieron. Un plugin con rol de transformación (label-transform, que reescribe las etiquetas de los nodos; o annotation-transform, que inyecta anotaciones antes de la expansión) da forma a los bytes de la salida renderizada, así que el conjunto de vinculaciones — la lista ordenada, más, por cada vinculación, el rol, la coordenada del plugin y la función exportada — es una entrada que determina los bytes, fijada aquí. La compilación lee esta sección — nunca .aggrega-config.yaml — para reconstruir el conjunto, el orden, el rol y la función exportada, de modo que la salida de la compilación es invariante ante un cambio en plugins.governance hecho después del pull (que solo se adopta en el pull siguiente). El orden es SEMÁNTICO: cada ejecutor de transformación aplica las vinculaciones de su rol en el orden de la lista, así que, a diferencia de las secciones plugins / providers ordenadas por URI, esta lista nunca se reordena. El digest de contenido del plugin NO se duplica aquí: tiene una única fuente en las secciones plugins y entities, a las que este registro apunta por identidad. Valor predeterminado: [] |
plugins | object[] | no | Los plugins de Wasm cuyos bytes dan forma a la salida renderizada, cada uno fijado por el digest de contenido de su .wasm: un plugin de gobernanza vinculado en un rol de transformación (label-transform, annotation-transform) bajo .aggrega-config.yaml plugins.governance, más cualquier URI de plugin incrustado procedente de Recipes / FeatureRecipes / Providers referenciados. Un plugin de gobernanza vinculado en un rol de veredicto (ir-verdict, render-verdict) y una vinculación plugins.linter devuelven un veredicto y no dan forma a ningún byte de salida, así que ninguno de los dos se fija: ninguno aparece aquí ni bajo entities, y los archivos de reglas que lee una vinculación de veredicto se registran bajo verdict_inputs. Valor predeterminado: [] |
providers | object[] | no | Selecciones de proveedor por capacidad resueltas. Cada entrada fija una capacidad (p. ej. helm) a la identidad OCI sin digest del plugin de renderizado del proveedor que la renderiza, resuelta en el pull a partir de la lista plugins.providers de .aggrega-config.yaml (cuando la capacidad se sirve de forma ambigua) o a partir del único plugin que la sirve (cuando no hay ambigüedad). La compilación lee esta sección — nunca .aggrega-config.yaml — para seleccionar el proveedor, de modo que la salida de la compilación es invariante ante cambios en la configuración del espacio de trabajo hechos después del pull. El digest de contenido del plugin NO se duplica aquí: tiene una única fuente en las secciones plugins y entities, a las que este registro apunta por identidad. Se preserva la coexistencia de versiones: este registro selecciona el repositorio del plugin por capacidad; las versiones concretas están en entities (una entrada por cada versión de plugin resuelta), y la fijación de versión spec.capability de cada Recipe elige entre ellas en el renderizado. Valor predeterminado: [] |
release | string | sí | Ruta a la Release a la que corresponde este archivo de bloqueo, resuelta en relación con el propio directorio del archivo de bloqueo (p. ej. ./release-prod.yaml). La convención de nombres por Release coloca <release-stem>.lock junto a <release-stem>.yaml; la ruta relativa hace que el archivo de bloqueo se describa a sí mismo sin rutas absolutas específicas de la máquina. Esto nombra la Release; lo que contenía la Release cuando se resolvió se registra en release_documents. |
release_documents | object[] | no | Los archivos de la Release que leyó la resolución, cada uno registrado por el digest de contenido de sus bytes: primero la Release a la que pertenece este archivo de bloqueo, luego cada Release que extiende, en el orden en que se recorre la cadena extends. Todo lo que pide una Release se resuelve a partir de lo que contiene, de modo que una Release editada después del pull ya no coincide con su digest registrado, y una compilación — o aggrega pull --verify — se detiene nombrando el archivo, con aggrega pull --release <release> como remedio, antes de que se renderice nada. El digest cubre los bytes tal como son, sin normalizar nada, la misma regla que siguen las fijaciones del Aggregate y del Manifest: una edición de un comentario o de espacios en blanco cuenta como un cambio. Un archivo de bloqueo sin esta sección no registra ningún archivo de la Release, y una compilación que tenga un archivo de bloqueo así informa de que la Release no está registrada. Un archivo que la Release importa mediante parameters no se registra aquí. |
schema_libraries | LibraryEntry[] | no | Entradas de SchemaLibrary a las que llega el cierre de dependencias de la Release a través de los sitios $ref y $import: en el contenido schema: / usesSchema: / featuresSchema: de las entidades. La lista consumers de cada entrada registra qué entidad del catálogo hace referencia a qué fragmentos <entry-name> de la biblioteca — un registro estructurado que hace rastreables los diffs del impacto de un cambio de versión de la biblioteca sin volver a resolver la Release. Valor predeterminado: [] |
source_artifacts | SourceArtifactEntry[] | no | Artefactos fuente obtenidos de los campos spec.source de Recipe / FeatureRecipe en el momento del pull. Cada entrada identifica una identidad {kind, url, chart, pinned_version} única con el digest de contenido, el tipo de medio y los punteros de retorno estructurados referenced_by: que nombran cada entidad del catálogo que se resolvió en este artefacto. url es la URL de identidad escrita por el autor; la ubicación resuelta del artefacto para una fuente helm de raíz del repositorio se registra por separado en resolved_url: como procedencia. Varias Recipes que fijan el mismo chart en la misma versión se deduplican en una sola entrada con varios registros referenced_by:. El enum de tipos cubre los cuatro tipos de fuente que se resuelven, y terraform-module-oci, que ningún adaptador de fuente sirve: una Recipe o una FeatureRecipe que lo nombre se rechaza en cuanto se lee, así que ningún pull registra una entrada de ese tipo. Valor predeterminado: [] |
toolchain | object | no | Versiones de la cadena de herramientas que produjo este archivo de bloqueo: la versión propia del compilador y la versión de cada plugin core que el compilador incluye. Se registran para que un archivo de bloqueo responda a posteriori qué compilador y qué plugins core resolvieron y renderizaron una compilación — una pregunta que las secciones fijadas no siempre pueden responder, porque un plugin de proveedor core servido desde dentro del binario del compilador queda sin fijar y, por tanto, no lleva ninguna versión registrada propia. Solo versiones: el sello nunca registra de dónde proceden los bytes de un plugin, así que dos máquinas que fijaron el mismo cierre de dependencias con el mismo compilador escriben el mismo sello. Nada compara esta sección, avisa sobre ella ni rechaza una compilación por ella, y su ausencia en un archivo de bloqueo es silenciosa: la cadena de herramientas no forma parte del cierre de dependencias que fija el archivo de bloqueo. Por la misma razón, la sección queda exenta de la comparación de identidad byte a byte entre dos pulls de las mismas entradas, al mismo nivel que generated_at. |
verdict_inputs | object[] | no | Entradas de reglas externas que una vinculación de gobernanza con rol de veredicto (ir-verdict / render-verdict) lee en tiempo de compilación — un archivo de reglas Kyverno / Rego proporcionado mediante el with.sources de la vinculación. Se registran como un digest de contenido por fuente, para auditoría y para la visibilidad de la deriva entre un pull y otro: el digest que determinó un veredicto puede compararse entre pulls, de modo que un archivo de reglas modificado aparece como un diff del archivo de bloqueo. Esta sección es PROCEDENCIA, no una entrada de la compilación: a diferencia de mutators.sources no lleva ningún content, y la compilación NO la lee — un plugin de veredicto se almacena en caché en lugar de fijarse y lee sus entradas de reglas en vivo (el veredicto no determina ningún byte de la salida, así que nada de lo que el archivo de bloqueo fija para una salida determinista lo incluye). Como un plugin de veredicto no está fijado, está ausente de las secciones entities / plugins; por eso este registro identifica la vinculación por su URI escrito por el autor, de forma autónoma en lugar de apuntar a esas secciones. Registrar el digest hace que las entradas que determinaron una decisión de aceptación o rechazo sean auditables y reproducibles sin fijarlas en la compilación. Valor predeterminado: [] |
version | const 1 | sí | Versión del esquema del archivo de bloqueo: 1. Un cambio SemVer-MAJOR en el esquema la incrementa. Constante: 1 |
workload_libraries | LibraryEntry[] | no | Entradas de WorkloadLibrary a las que llega el cierre de dependencias de la Release a través de los sitios workload: { $import: ... } de Recipe. La lista consumers de cada entrada registra qué entidad del catálogo hace referencia a qué fragmentos <entry-name> de la biblioteca — un registro estructurado que hace rastreables los diffs del impacto de un cambio de versión de la biblioteca sin volver a resolver la Release. Valor predeterminado: [] |
artifact_libraries | LibraryEntry[] | no | Entradas de ArtifactLibrary a las que llega el cierre de dependencias de la Release a través de los sitios artifacts.<name>: { $import: ... } de Recipe / FeatureRecipe. La lista consumers de cada entrada registra qué entidad del catálogo hace referencia a qué paquetes <entry-name> de la biblioteca — un registro estructurado que hace rastreables los diffs del impacto de un cambio de versión de la biblioteca sin volver a resolver la Release. Valor predeterminado: [] |
No se permiten propiedades adicionales.
lockfile.entities[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
kind | string (enum) | sí | Tipo de la entidad del catálogo, leído de donde la Release, su Aggregate o su Manifest la nombra: component y feature para un tipo de Component o de Feature que nombra el Aggregate, la Release o una asignación del Manifest, recipe y feature_recipe para una realización que vincula una asignación del Manifest, plugin para una entidad Plugin, aggregate para el Aggregate propio de la Release y cada Aggregate que este incluye, y manifest para el Manifest propio de la Release y el Manifest que este extiende. Junto con uri identifica la entrada: una compilación compara cada entrada con la entidad del mismo tipo y URI, de modo que se detecta una modificación de cualquiera de dos entidades homónimas de tipos distintos. Valores permitidos: "aggregate", "component", "feature", "feature_recipe", "manifest", "plugin", "recipe" |
uri | string | sí | URI canónico de la entidad del catálogo (p. ej. hub.aggrega.ai/component/core/compute/api-server). |
resolved_version | string | sí | Versión concreta que el resolver seleccionó en el momento del pull — la versión propia de una entidad del catálogo (p. ej. 1.2.3), o vacía para una entidad de nivel superior resuelta por ruta en lugar de por versión. Se registra como un único segmento de ruta, porque nombra uno, así que no lleva /, ni \, ni ..: el valor construye la ranura de la caché desde la que la compilación vuelve a leer esta entidad, y un valor que saliera del directorio de la caché nombraría una ubicación fuera de él. Patrón: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | sí | Digest de lo que lleva una publicación de la entidad, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas: el SHA-256 calculado sobre el documento de la entidad y sobre cada archivo que declara junto a él, ordenados por ruta, cada uno de los cuales aporta su ruta y el SHA-256 de sus bytes. Una entidad que no declara ningún archivo cuenta como su único documento. Nada más entra en él — ni cómo se comprimió un archivo comprimido, ni una marca de tiempo, ni ningún bit de permiso, incluido el bit de ejecución — de modo que la entidad registra el mismo digest tanto si se lee desde un directorio de catálogo como si se obtiene de un registro, y en cualquier checkout de los mismos archivos, en cualquier sistema. Patrón: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | no | Digest del manifiesto OCI del artefacto resuelto, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. La firma avala este digest, y el manifiesto nombra el digest de los bytes publicados, contra el cual se comprueban una obtención y una lectura desde la caché antes de que la entidad se contraste con su digest de arriba. Presente solo para una entidad resuelta desde un registro. Patrón: ^sha256:[a-f0-9]{64}$. |
referenced_from | string[] | no | Orígenes en los sitios de autoría — rutas con puntos en el YAML de Release / Aggregate / Manifest (p. ej. aggregate.spec.components.api.type) que registran por qué este URI está en el cierre de dependencias de la Release. Valor predeterminado: [] |
signature | VerifiedSignature | no | Hecho de firma verificada que se registra cuando la firma de esta entidad se verificó en el momento del pull, frente a la política de confianza del registro que la resolvió. |
deprecation | DeprecationRecord | no | Marcador de obsolescencia retroactivo verificado, que se registra cuando en el momento del pull se descubrió en este artefacto un marcador de obsolescencia firmado y de confianza. Un marcador es un referrer OCI firmado del artefacto que declara obsoleto, adjuntado después de la publicación sin volver a publicar el artefacto. Registra la severidad y el mensaje del marcador, además del firmante verificado que lo creó. La compilación lee este hecho y aplica la política de obsolescencia a partir del archivo de bloqueo únicamente; nunca vuelve a descubrir ni a verificar el marcador. |
No se permiten propiedades adicionales.
lockfile.mutators[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
plugin | string | sí | Coordenada resuelta del plugin con rol de transformación — la identidad <pluginType>/<name> de una entidad Plugin (p. ej. governance/tag-injector). Se une por identidad con las secciones plugins y entities para el digest fijado y el conjunto de versiones. |
role | string (enum) | sí | El rol de transformación al que está ligada esta vinculación, registrado tal cual a partir de la entrada plugins.governance escrita por el autor, de modo que una compilación ejecuta la vinculación exactamente en ese rol en lugar de deducir uno: label-transform reescribe las etiquetas de los nodos durante la construcción de la topología; annotation-transform inyecta anotaciones antes de la expansión, durante la resolución. Valores permitidos: "label-transform", "annotation-transform" |
function | string | no | Anulación de la exportación que nombra la vinculación. Si está ausente, se selecciona la exportación predeterminada del rol (mutate para label-transform, transform_annotations para annotation-transform). |
settings | object | no | Objeto de ajustes de forma libre que declaró la vinculación, fijado tal como se escribió y entregado al plugin tal cual. La compilación lee los ajustes desde aquí — nunca desde la configuración en vigor — de modo que un cambio de ajustes posterior al pull no mueve la salida de la compilación. Ausente cuando la vinculación no declara ninguno. |
sources | object[] | no | Fijaciones direccionadas por contenido de los archivos fuente declarados por la vinculación, en orden de nombre base. La compilación reconstruye la fuente que lee el plugin a partir del contenido registrado de cada fijación en lugar de una lectura en vivo en el host, de modo que la salida de la compilación permanece invariante ante un cambio del archivo fuente posterior al pull. Ausente cuando la vinculación no declara ninguno. |
No se permiten propiedades adicionales.
lockfile.mutators[].sources[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
content | string | sí | El contenido del archivo fuente, llevado tal cual para que la compilación reconstruya la entrada fuente del plugin a partir del archivo de bloqueo. |
digest | string | sí | La dirección de contenido del contenido registrado, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. Un nuevo pull compara el archivo subyacente con este digest para detectar la deriva. Patrón: ^sha256:[a-f0-9]{64}$. |
path | string | sí | El nombre base del archivo fuente — nunca una ruta absoluta del host, de modo que la fijación es portable y determinista. |
No se permiten propiedades adicionales.
lockfile.plugins[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
uri | string | sí | Identidad simple del artefacto .wasm del plugin Wasm — la ruta <pluginType>/<name> (p. ej. governance/aggrega-security-baseline). El primer segmento es el tipo del plugin (provider, linter, pipeline-step, governance, cli, parser, importer); el segmento siguiente es el nombre del plugin. El tipo y el nombre juntos forman la identidad del plugin — el mismo nombre bajo dos tipos son dos plugins. La ubicación física de obtención se deriva de esta identidad más el registro configurado, y nunca se lleva en el archivo de bloqueo. |
resolved_version | string | sí | El digest de contenido al que se resolvió el artefacto Wasm, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. Un artefacto de plugin está direccionado por contenido en lugar de nombrado por versión — un .wasm viaja en línea en el manifiesto de su plugin y se fija por el digest de sus bytes — así que este campo registra ese digest, que es también el digest de abajo. Construye la ranura de la caché desde la que la compilación vuelve a leer el artefacto, así que no lleva /, ni \, ni .., cosa que la forma sha256: ya excluye. Patrón: ^sha256:[a-f0-9]{64}$. |
digest | string | sí | Digest de contenido del artefacto Wasm resuelto, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas — la forma en que se escribe la dirección de contenido en todos los lugares donde se compara. Patrón: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | no | Digest del manifiesto OCI del artefacto Wasm resuelto, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. La firma avala este digest; el digest de contenido de arriba es la identidad portable que se usa para la fijación en la caché y la comprobación de integridad. Presente solo para un artefacto resuelto desde un registro. Patrón: ^sha256:[a-f0-9]{64}$. |
referenced_from | string[] | no | Por qué este artefacto está en el cierre de dependencias de la Release: la referencia de cada entidad Plugin a través de la cual se alcanzó, tal como la sección entities registra esa entidad (p. ej. governance/label-injector:1.0.0). Valor predeterminado: [] |
signature | VerifiedSignature | no | Hecho de firma verificada que se registra cuando la firma de este plugin se verificó en el momento del pull, frente a la misma política de confianza por registro que se aplica a las entidades del catálogo. |
deprecation | DeprecationRecord | no | Marcador de obsolescencia retroactivo verificado, que se registra cuando en el momento del pull se descubrió en este artefacto un marcador de obsolescencia firmado y de confianza. Un marcador es un referrer OCI firmado del artefacto que declara obsoleto, adjuntado después de la publicación sin volver a publicar el artefacto. Registra la severidad y el mensaje del marcador, además del firmante verificado que lo creó. La compilación lee este hecho y aplica la política de obsolescencia a partir del archivo de bloqueo únicamente; nunca vuelve a descubrir ni a verificar el marcador. |
No se permiten propiedades adicionales.
lockfile.providers[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
capability | string | sí | La capacidad para la que este enlace selecciona un proveedor — el nombre simple de la capacidad que una Recipe enlaza mediante spec.capability (p. ej. helm, compose). |
plugin | string | sí | Identidad simple del plugin de renderizado del proveedor resuelto (la identidad de la entidad Plugin, su metadata.pluginType y su metadata.name unidos por una barra, p. ej. provider/helm). Se une por identidad con las secciones plugins y entities para el digest fijado y el conjunto de versiones. |
No se permiten propiedades adicionales.
lockfile.release_documents[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
digest | string | sí | El digest de contenido de los bytes del archivo de Release en el momento en que la resolución los leyó, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. Patrón: ^sha256:[a-f0-9]{64}$. |
path | string | sí | La ruta del archivo de Release relativa al directorio que contiene la Release a la que pertenece este archivo de bloqueo, con barras normales (p. ej. release-prod.yaml, ../shared/base-release.yaml) — nunca una ruta absoluta del host, de modo que la entrada es portable y determinista. |
No se permiten propiedades adicionales.
lockfile.toolchain
Versiones de la cadena de herramientas que produjo este archivo de bloqueo: la versión propia del compilador y la versión de cada plugin core que el compilador incluye. Se registran para que un archivo de bloqueo responda a posteriori qué compilador y qué plugins core resolvieron y renderizaron una compilación — una pregunta que las secciones fijadas no siempre pueden responder, porque un plugin de proveedor core servido desde dentro del binario del compilador queda sin fijar y, por tanto, no lleva ninguna versión registrada propia. Solo versiones: el sello nunca registra de dónde proceden los bytes de un plugin, así que dos máquinas que fijaron el mismo cierre de dependencias con el mismo compilador escriben el mismo sello. Nada compara esta sección, avisa sobre ella ni rechaza una compilación por ella, y su ausencia en un archivo de bloqueo es silenciosa: la cadena de herramientas no forma parte del cierre de dependencias que fija el archivo de bloqueo. Por la misma razón, la sección queda exenta de la comparación de identidad byte a byte entre dos pulls de las mismas entradas, al mismo nivel que generated_at.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
compiler_version | string | sí | Versión del compilador que escribió este archivo de bloqueo, en la forma sin v que indica toda superficie de Aggrega (1.2.0, no v1.2.0). Una compilación sellada con una versión registra esa versión — una compilación de release etiquetada, su etiqueta — y una compilación sin sello de versión registra el marcador (devel), de modo que un archivo de bloqueo producido por un compilador sin sello no se confunda con una salida de release. Se registra como un único segmento de ruta, así que no lleva /, ni \, ni ... Patrón: ^([^/\\.]|\.[^/\\.])*\.?$. |
core_plugins | object[] | sí | Versión de cada plugin core que lleva el compilador, una entrada por plugin, ordenadas por coordenada de plugin. Un plugin core se publica en la etiqueta propia del compilador con la misma versión, así que estas versiones se leen igual tanto si el compilador sirvió un plugin desde su propio interior como si lo obtuvo de un registro — que es lo que mantiene el sello libre de detalles propios de la máquina. Vacío para una compilación que no lleva plugins core. Valor predeterminado: [] |
No se permiten propiedades adicionales.
lockfile.toolchain.core_plugins[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
plugin | string | sí | Coordenada del plugin core — la identidad <pluginType>/<name> de una entidad Plugin (p. ej. provider/helm), la misma identidad con la que las secciones providers y mutators nombran un plugin. |
version | string | sí | Versión de este plugin core, en la forma sin v que indica toda superficie de Aggrega. Se registra como un único segmento de ruta, así que no lleva /, ni \, ni ... Patrón: ^([^/\\.]|\.[^/\\.])*\.?$. |
No se permiten propiedades adicionales.
lockfile.verdict_inputs[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
plugin | string | sí | El URI del plugin escrito por el autor para la vinculación de veredicto, tal como está escrito en .aggrega-config.yaml plugins.governance (p. ej. governance/aggrega-security-baseline:1.0.0). Identifica a qué vinculación pertenecen las entradas de reglas registradas; un plugin de veredicto se almacena en caché en lugar de fijarse, así que no tiene ninguna entrada en las secciones plugins / entities con la que unirse. |
role | string (enum) | sí | El rol de veredicto al que está ligada esta vinculación — ir-verdict (durante el análisis estático, sobre el grafo IR) o render-verdict (durante el renderizado, sobre los artefactos renderizados). Distingue el mismo plugin vinculado en ambas etapas de veredicto, cada una potencialmente con sus propias entradas de reglas. Valores permitidos: "ir-verdict", "render-verdict" |
sources | object[] | no | Digests de contenido de los archivos de entrada de reglas declarados por la vinculación, en orden de nombre base. Ausente cuando la vinculación no declara fuentes. |
No se permiten propiedades adicionales.
lockfile.verdict_inputs[].sources[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
digest | string | sí | La dirección de contenido de los bytes del archivo de entrada de reglas en el momento del pull, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. Un nuevo pull la vuelve a calcular, de modo que un archivo de reglas modificado aparece como un diff del archivo de bloqueo. Patrón: ^sha256:[a-f0-9]{64}$. |
path | string | sí | El nombre base del archivo de entrada de reglas — nunca una ruta absoluta del host, de modo que la entrada es portable y determinista. |
No se permiten propiedades adicionales.
Definiciones
DeprecationRecord
Marcador de obsolescencia retroactivo verificado, que se registra cuando en el momento del pull se descubrió en este artefacto un marcador de obsolescencia firmado y de confianza. Un marcador es un referrer OCI firmado del artefacto que declara obsoleto, adjuntado después de la publicación sin volver a publicar el artefacto. Registra la severidad y el mensaje del marcador, además del firmante verificado que lo creó. La compilación lee este hecho y aplica la política de obsolescencia a partir del archivo de bloqueo únicamente; nunca vuelve a descubrir ni a verificar el marcador.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
message | string | sí | Mensaje de obsolescencia legible por personas que lleva el marcador — normalmente una indicación para la migración. |
severity | string (enum) | sí | Severidad del marcador, ordenada warning < error < retracted. La compilación se detiene cuando esta severidad alcanza o supera el umbral de detención configurado, y en caso contrario emite un aviso. Valores permitidos: "warning", "error", "retracted" |
signer | VerifiedSignature | no | Firmante verificado del marcador, registrado de la misma manera que el firmante de la firma de un artefacto: el sujeto/emisor del certificado para la firma keyless, o la huella de la clave fijada para la firma con clave. Un marcador es un artefacto firmado por derecho propio, así que su firmante tiene la misma forma que la firma de un artefacto — y el bundle_digest aquí nombra el bundle de firma propio del marcador en lugar del del artefacto declarado obsoleto. |
No se permiten propiedades adicionales.
ExternalInput
Una única entrada externa fijada: la URL que solicitó un renderizado, la fijación SHA-256 que nombra sus bytes en el almacén de entradas direccionado por contenido (sha256/<digest>), el tamaño de la carga útil y la procedencia de los consumidores que la requirieron. La fijación es autoritativa — una URL fijada siempre se sirve desde el almacén, y un nuevo llenado del almacén se verifica contra este digest antes de que los bytes lleguen a un renderizado.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
required_by | string[] | sí | Procedencia — los sitios de renderizado que solicitaron esta entrada. Ordenados y deduplicados por el escritor del archivo de bloqueo. |
sha256 | string | sí | Fijación SHA-256 en hexadecimal en minúsculas. Para una entrada https, el digest de los bytes de la carga útil; para una entrada oci, el digest del manifiesto al que se resolvió la referencia. Nombra el blob del almacén en sha256/<digest>. Patrón: ^[0-9a-f]{64}$. |
size | integer | sí | Tamaño en bytes de la carga útil fijada. Un recuento de bytes nunca es negativo. Mínimo: 0. |
url | string | sí | La URL de la entrada tal como está escrita en el sitio de renderizado — la clave de búsqueda que asocia una solicitud en tiempo de renderizado con su fijación. |
No se permiten propiedades adicionales.
LibraryEntry
Forma común compartida por las entradas de schema_libraries, mapping_libraries, workload_libraries y artifact_libraries. La lista consumers recoge la relación en el grafo del catálogo — qué entidad del catálogo hace referencia a qué fragmentos <entry-name> de esta biblioteca — y admite diffs estructurados del impacto cuando cambia el digest de la biblioteca. Una biblioteca es un artefacto OCI como cualquier otro, así que registra los mismos hechos verificados que una entidad del catálogo: el digest del manifiesto que avala su firma, la propia firma verificada y cualquier marcador de obsolescencia retroactivo verificado descubierto en el momento del pull.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
uri | string | sí | URI canónico de la entidad de biblioteca. |
resolved_version | string | sí | Versión concreta resuelta en el momento del pull (selección de versión mínima sobre el grafo de dependencias entre bibliotecas) — la versión propia de la biblioteca. Se registra como un único segmento de ruta, porque construye la ranura de la caché desde la que la compilación vuelve a leer la biblioteca, así que no lleva /, ni \, ni ..: un valor que saliera del directorio de la caché nombraría una ubicación fuera de él. Patrón: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | sí | Digest de contenido del artefacto de biblioteca resuelto, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas — la forma en que se escribe la dirección de contenido en todos los lugares donde se compara. Patrón: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | no | Digest del manifiesto OCI del artefacto de biblioteca resuelto, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. La firma avala este digest; el digest de contenido de arriba es la identidad portable que se usa para la fijación en la caché y la comprobación de integridad. Presente solo para una biblioteca resuelta desde un registro. Patrón: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | no | Hecho de firma verificada que se registra cuando la firma de esta biblioteca se verificó en el momento del pull, frente a la misma política de confianza por registro que se aplica a las entidades del catálogo. |
deprecation | DeprecationRecord | no | Marcador de obsolescencia retroactivo verificado descubierto en esta biblioteca en el momento del pull. La compilación lo informa y, donde el espacio de trabajo configuró un umbral de detención que la severidad registrada alcanza, se detiene — de modo que una biblioteca retirada después de fijarse la versión se anuncia en cada compilación en lugar de solo en la selección de versión, que una versión fijada explícitamente omite. |
consumers | object[] | no | Registros de qué entidad del catálogo hace referencia a esta biblioteca y a qué fragmentos <entry-name>. Recoge el fan-in: muchos consumidores por biblioteca, cada uno potencialmente con referencias a muchos fragmentos. Cada registro lleva el URI del consumidor más el conjunto de fragmentos que ese consumidor incorpora. Valor predeterminado: [] |
No se permiten propiedades adicionales.
LibraryEntry.consumers[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
consumer_uri | string | sí | URI canónico de la entidad del catálogo que hace referencia a esta biblioteca: un Component o una Feature para una biblioteca de esquemas, una Recipe o una FeatureRecipe para una biblioteca de mappings, de workloads o de artefactos, u otra biblioteca del mismo tipo cuyas entradas hacen referencia a esta. |
fragments | string[] | sí | Conjunto de fragmentos <entry-name> a los que este consumidor hace referencia dentro de la biblioteca (p. ej. ["#/schemas/PortSpec", "#/schemas/EndpointSpec"]). El escritor canoniza el orden lexicográficamente. |
No se permiten propiedades adicionales.
SourceArtifactEntry
Una única fijación de artefacto fuente: la identidad {kind, url, chart, module_subdir, pinned_version}, el digest de contenido que verifica el pull, el tipo de medio canónico y los punteros de retorno estructurados a cada entidad del catálogo que se resolvió en este artefacto. chart y module_subdir son los dos términos selectores — cada uno nombra lo que la URL por sí sola no nombra, para los tipos que lo necesitan.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
kind | enum | sí | El tipo de fuente. Determina qué adaptador resolvió el artefacto y qué tipo de medio se espera. terraform-module-oci pertenece al conjunto, y ningún adaptador de fuente lo sirve: una Recipe o una FeatureRecipe que lo nombre se rechaza en cuanto se lee. Valores permitidos: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci" |
url | string | sí | La URL escrita por el autor — la URL de identidad tal como está escrita en spec.source.url de la Recipe. Para helm-https-chart es la raíz del repositorio (forma de raíz del repositorio) o el .tgz directo (forma directa), exactamente como se escribió; la compilación reconstruye esta misma URL sin conexión, así que es la identidad estable por la que se indexa la fijación. Para git-repository, la URL del repositorio clonable. Para helm-oci-chart, la referencia del registro. Para compose-https-fragment, la URL HTTPS del fragmento. La ubicación resuelta del artefacto para una fuente helm de raíz del repositorio se registra por separado en resolved_url: como procedencia. |
chart | string | no | El nombre del chart para una fuente helm de raíz del repositorio (spec.source.chart de la Recipe), parte de la identidad {kind, url, chart, module_subdir, pinned_version}, de modo que dos charts servidos desde una misma raíz del repositorio en la misma versión se fijan en entradas distintas. Ausente para una fuente .tgz directa, OCI, compose o git, ninguna de las cuales selecciona un chart dentro de la URL. |
module_subdir | string | no | El directorio, dentro de un repositorio de origen git, que constituye el artefacto (spec.source.module_subdir de la Recipe), parte de la identidad {kind, url, chart, module_subdir, pinned_version}, de modo que dos directorios de un mismo repositorio en el mismo commit se fijan en entradas distintas. Ausente cuando el repositorio entero es el artefacto, y para todo tipo que llega a su artefacto por URL en lugar de descender a un clon. |
pinned_version | string | sí | La versión concreta fijada en el momento del pull. Para los tipos helm-*, la versión del chart. Para git-repository, el commit al que se resolvió la referencia escrita por el autor (NO la referencia de tag/rama original — esa se registra en requested_ref: en cada entrada referenced_by:, siempre que la Recipe haya escrito un spec.source.ref:). Una compilación encuentra esta entrada por lo que escribió la Recipe: el ref: escrito por el autor, donde lo hay, contrastado con el requested_ref: registrado, y en caso contrario este valor fijado — de modo que una Recipe que nombra un tag se resuelve en el commit en el que ese tag se fijó, sin que el commit aparezca nunca en la Recipe. Se registra como un único segmento de ruta, porque construye la ranura de la caché desde la que la compilación vuelve a leer el artefacto, así que no lleva /, ni \, ni ... Patrón: ^([^/\\.]|\.[^/\\.])*\.?$. |
resolved_url | string | no | Solo procedencia: la ubicación concreta del artefacto en la que se resolvió la URL escrita por el autor en el momento del pull. Para una fuente helm de raíz del repositorio es la URL del .tgz directo en la que el índice del repositorio resolvió chart+versión; se registra para diagnóstico y NO forma parte de la identidad del artefacto. Ausente cuando la ubicación resuelta es igual a la URL escrita por el autor (una fuente .tgz directa, OCI, compose o git). |
digest | string | sí | Digest de contenido del archivo comprimido .tar.gz resuelto, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. La verificación en tiempo de compilación lee los bytes de la ranura de la caché, vuelve a calcular el digest y lo compara con este campo; una discrepancia detiene la compilación e informa de una discrepancia del digest de contenido. Patrón: ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | no | Digest del manifiesto OCI del artefacto resuelto, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. El manifiesto es la raíz de confianza independiente contra la que se verifica el archivo comprimido en caché; el digest de contenido de arriba es la identidad portable que se usa para la fijación en la caché y la comprobación de integridad. Presente solo para una fuente distribuida mediante OCI (un helm-oci-chart). Patrón: ^sha256:[a-f0-9]{64}$. |
mediatype | string | sí | Tipo de medio canónico que anunció el registro (o el valor predeterminado del tipo para los tipos sin metadatos de registro). Se registra como procedencia de diagnóstico. |
referenced_by | SourceArtifactReference[] | sí | Entidades del catálogo que se resolvieron en este artefacto, ordenadas por (uri, field) para una salida determinista. Una entrada existe solo porque una Recipe o una FeatureRecipe la obtuvo mediante un pull, así que la lista nunca está vacía. Al menos 1 entrada. |
No se permiten propiedades adicionales.
SourceArtifactReference
Un único puntero de retorno entidad del catálogo → artefacto fuente. entity + uri identifican juntos la entidad del catálogo; field nombra la ruta del lado de la fuente dentro de la spec de la entidad donde se declaró el artefacto. El requested_ref: opcional conserva el spec.source.ref: escrito por el autor de la Recipe, y se escribe siempre que la Recipe haya escrito uno (tags/ramas de git-repository → SHA del commit).
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
entity | enum | sí | El tipo de entidad del catálogo que contiene este puntero de retorno. Valores permitidos: "recipe", "feature_recipe" |
uri | string | sí | URI canónico de la Recipe o de la FeatureRecipe (p. ej. hub.aggrega.ai/recipe/helm/mariadb-bitnami:1.0.0). |
field | string | sí | Ruta del lado de la fuente dentro de la spec de la entidad donde se declaró el artefacto. El valor es spec.source. |
requested_ref | string | no | Opcional — el spec.source.ref: escrito por el autor de la Recipe, que se escribe siempre que la Recipe haya escrito uno. Para una Recipe git-repository que escribe ref: v1.0.0, conserva "v1.0.0" mientras pinned_version: contiene el commit en el que se resolvió esa referencia. Ausente cuando la Recipe no escribe ningún ref:, que es el caso de todo tipo cuyo resolver fija tal cual la versión escrita por el autor (helm-, compose-). Cumple dos funciones a la vez, y registrarlo incondicionalmente es lo que evita que se excluyan entre sí. Una compilación lo usa como clave de unión para encontrar esta entrada a partir de una Recipe que nombra la referencia en lugar del commit. Y un pull que no es una actualización mantiene cada referencia registrada en su versión fijada: una referencia que se ha movido en su remoto detiene la ejecución en lugar de ser adoptada. |
No se permiten propiedades adicionales.
VerifiedSignature
Hecho de firma verificada que se registra cuando la firma de un artefacto se verificó en el momento del pull, frente a la política de confianza del registro que lo resolvió. Todo artefacto firmable lo registra de la misma manera — una entidad del catálogo, una biblioteca, un plugin de Wasm — porque todos se verifican por una única ruta en lugar de una por tipo. Registra el modo de verificación, la identidad/el emisor keyless que coincidió (si es keyless) y el digest direccionado por contenido del bundle de firma en la caché de contenido. La compilación no vuelve a ejecutar la verificación. Antes de que se renderice nada, lee este hecho en cada entrada a partir de la cual compila, en cada sección: vuelve a calcular el hash del bundle en caché y compara el resultado con bundle_digest, deteniéndose donde el blob falta o difiere; y para una entrada que sirvió la caché de contenido, lee de ese bundle para qué artefacto se hizo la firma, y se detiene donde se hizo para un artefacto distinto del que la compilación leyó para la entrada — de modo que una signature copiada de una entrada a otra se rechaza, diga lo que diga el requisito de firma. Una compilación no verifica ninguna firma, así que un bundle escrito a mano en la caché, emitido para el propio artefacto de la entrada, no se distingue de uno que verificó un pull. Y donde la configuración de confianza del espacio de trabajo exige una firma para una entrada que sirvió la caché de contenido — el requisito que pull aplica cuando obtiene el artefacto, de modo que las exenciones y un registro advisory que permiten que un pull admita un artefacto sin firma permiten también que la compilación admita su entrada — una entrada que no lleva ningún hecho detiene la compilación. Una entrada leída desde un directorio de catálogo, desde la copia dentro del binario del compilador o desde junto a la Release nunca está sujeta a ese requisito.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
bundle_digest | string | sí | Digest SHA-256 del blob del bundle de firma en caché, en la forma sha256: seguido de 64 caracteres hexadecimales en minúsculas. Nombra el blob de la caché, así que construye una ruta y no lleva /, ni \, ni .. — cosa que la forma sha256: ya excluye — y, en una entrada de cualquier sección, es aquello contra lo que una compilación vuelve a calcular el hash de ese blob. Patrón: ^sha256:[a-f0-9]{64}$. |
identity | string | no | Firmante verificado de la firma: el sujeto del certificado de firma para una firma keyless, o keyed:sha256: seguido del SHA-256 del texto PEM de la clave pública fijada para una firma con clave. |
issuer | string | no | Emisor OIDC verificado para una firma keyless. Vacío para una firma con clave. |
mode | string (enum) | sí | Modo de verificación que admitió la firma. Valores permitidos: "keyless", "keyed" |
No se permiten propiedades adicionales.