Schéma du fichier de verrouillage par Release d’Aggrega
Référence générée. Ne pas modifier à la main — régénérer à partir du JSON Schema publié.
Identifiant du schéma : https://aggrega.ai/schemas/lockfile-v1beta1.schema.json
Fichier de verrouillage généré automatiquement qui épingle chaque URI résolu à partir d’une Release pour des builds futurs déterministes. Il se trouve à <release-stem>.lock à côté de <release-stem>.yaml ; produit par aggrega pull --release <release> ; consommé par aggrega build --release <release>. Deux formes de provenance enregistrent deux relations distinctes dans le graphe des dépendances : referenced_from (liste de chaînes) apparaît sur entities, sous forme de chemins pointés de sites d’écriture qui enregistrent à quel endroit de la Release / de l’Aggregate / du Manifest / de .aggrega-config.yaml chaque URI a été introduit, et sur plugins, comme la référence de chaque entité Plugin par laquelle un artefact a été atteint ; consumers (liste d’enregistrements {consumer_uri, fragments}) apparaît sur schema_libraries, mapping_libraries, workload_libraries et artifact_libraries pour enregistrer quelle entité du catalogue référence quels fragments <entry-name> d’une bibliothèque — la forme structurée rend traçables les diffs des consommateurs affectés par une montée de version de bibliothèque sans résoudre de nouveau la Release. Discipline d’évolution du schéma : ajouter une nouvelle section de premier niveau est SemVer-MINOR (additif) ; ajouter un nouveau champ dans une section existante est SemVer-MINOR ; supprimer une clé ou resserrer une contrainte est SemVer-MAJOR.
Type de premier niveau : object
Propriétés
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
entities | object[] | non | Entités du catalogue atteignables depuis cette Release : Component, Feature, Recipe, FeatureRecipe, Plugin, Aggregate, l’Aggregate et le Manifest propres à la Release, ainsi que le Manifest que ce Manifest étend. Chaque entrée est identifiée par son kind conjointement à son URI canonique, de sorte que deux entités de types différents qui partagent un nom — un Aggregate et un Manifest tous deux nommés imported/flow, par exemple — constituent deux entrées, chacune vérifiée par rapport à son propre digest. Chacune enregistre la version résolue, le digest de ce que porte l’entité et les origines sur les sites d’écriture (referenced_from) qui ont introduit l’URI dans la fermeture des dépendances de la Release. Un lockfile dont les entrées ne portent aucun kind est obsolète : aggrega pull --release <release> le réécrit. Par défaut : [] |
external_inputs | ExternalInput[] | non | Entrées distantes épinglées dans le magasin d’entrées adressé par contenu au moment de l’acquisition — du contenu que le rendu d’un plugin de fournisseur consomme depuis l’extérieur de l’espace de travail, comme des documents de schéma distants ou des dépendances de chart non vendorisées. Chaque entrée épingle une URL au digest qui nomme ses octets dans le magasin. Le build sert les entrées épinglées depuis le magasin et lit cette section sans accès réseau. Par défaut : [] |
generated_at | string | oui | Horodatage RFC 3339 du pull qui a produit ce fichier de verrouillage ; le motif contraint la valeur à cette forme lorsque le fichier de verrouillage est chargé. Provenance de diagnostic — enregistre l’instant de la résolution selon l’horloge système. Change intentionnellement d’un pull à l’autre ; ne fait pas partie de la garantie d’identité octet pour octet du fichier de verrouillage. Motif : ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$. |
mapping_libraries | LibraryEntry[] | non | Entrées de MappingLibrary que la fermeture des dépendances de la Release atteint par les sites valuesMapping: { $import: ... } de Recipe / FeatureRecipe. La liste consumers de chaque entrée enregistre quelle entité du catalogue référence quels fragments <entry-name> de la bibliothèque — un enregistrement structuré qui rend traçables les diffs d’impact d’une montée de version de la bibliothèque sans résoudre de nouveau la Release. Par défaut : [] |
mutators | object[] | non | Rattachements de gouvernance à rôle de transformation résolus, dans l’ordre rédigé. Un plugin à rôle de transformation (label-transform, qui réécrit les labels des nœuds ; ou annotation-transform, qui injecte des annotations avant l’expansion) façonne les octets de la sortie rendue, de sorte que l’ensemble des rattachements — la liste ordonnée, plus pour chaque rattachement le rôle, la coordonnée du plugin et la fonction exportée — est une entrée déterminante pour les octets, épinglée ici. Le build lit cette section — jamais .aggrega-config.yaml — pour reconstruire l’ensemble, l’ordre, le rôle et la fonction exportée, de sorte que la sortie du build est invariante vis-à-vis d’une modification de plugins.governance faite après le pull (adoptée seulement au pull suivant). L’ordre est SÉMANTIQUE : chaque exécuteur de transformation applique les rattachements de son rôle dans l’ordre de la liste, de sorte que, contrairement aux sections plugins / providers triées par URI, cette liste n’est jamais réordonnée. Le digest du contenu du plugin n’est PAS dupliqué ici : il a une source unique dans les sections plugins et entities, vers lesquelles cet enregistrement pointe par identité. Par défaut : [] |
plugins | object[] | non | Les plugins Wasm dont les octets façonnent la sortie rendue, chacun épinglé par le digest du contenu de son .wasm : un plugin de gouvernance rattaché dans un rôle de transformation (label-transform, annotation-transform) sous .aggrega-config.yaml plugins.governance, plus tous les URI de plugins intégrés provenant des Recipes / FeatureRecipes / Providers référencés. Un plugin de gouvernance rattaché dans un rôle de verdict (ir-verdict, render-verdict) et un rattachement plugins.linter renvoient un verdict et ne façonnent aucun octet de sortie, de sorte qu’aucun des deux n’est épinglé : aucun n’apparaît ici ni sous entities, et les fichiers de règles que lit un rattachement de verdict sont enregistrés sous verdict_inputs. Par défaut : [] |
providers | object[] | non | Sélections de fournisseur par capacité résolues. Chaque entrée épingle une capacité (par ex. helm) à l’identité OCI sans digest du plugin de rendu de fournisseur qui en effectue le rendu, résolue au pull à partir de la liste plugins.providers de .aggrega-config.yaml (lorsque la capacité est servie de manière ambiguë) ou à partir de l’unique plugin qui la sert (lorsqu’il n’y a pas d’ambiguïté). Le build lit cette section — jamais .aggrega-config.yaml — pour sélectionner le fournisseur, de sorte que la sortie du build est invariante vis-à-vis des modifications de la configuration de l’espace de travail faites après le pull. Le digest du contenu du plugin n’est PAS dupliqué ici : il a une source unique dans les sections plugins et entities, vers lesquelles cet enregistrement pointe par identité. La coexistence des versions est préservée : cet enregistrement sélectionne le dépôt du plugin par capacité ; les versions concrètes se trouvent dans entities (une entrée par version de plugin résolue), et l’épinglage de version spec.capability de chaque Recipe choisit parmi elles au rendu. Par défaut : [] |
release | string | oui | Chemin vers la Release à laquelle correspond ce fichier de verrouillage, résolu par rapport au répertoire propre du fichier de verrouillage (par ex. ./release-prod.yaml). La convention de nommage par Release place <release-stem>.lock à côté de <release-stem>.yaml ; le chemin relatif rend le fichier de verrouillage autodescriptif sans chemins absolus propres à une machine. Ceci nomme la Release ; ce que contenait la Release lorsqu’elle a été résolue est enregistré sous release_documents. |
release_documents | object[] | non | Les fichiers de Release que la résolution a lus, chacun enregistré par le digest du contenu de ses octets : d’abord la Release à laquelle appartient ce fichier de verrouillage, puis chaque Release qu’elle étend, dans l’ordre dans lequel la chaîne extends est parcourue. Tout ce qu’une Release demande est résolu à partir de ce qu’elle contient, de sorte qu’une Release modifiée après le pull ne correspond plus à son digest enregistré, et qu’un build — ou aggrega pull --verify — s’interrompt en nommant le fichier, avec aggrega pull --release <release> comme remède, avant que quoi que ce soit ne soit rendu. Le digest couvre les octets tels quels, sans rien normaliser, selon la même règle que suivent les épinglages de l’Aggregate et du Manifest : une modification d’un commentaire ou d’espaces compte comme un changement. Un fichier de verrouillage sans cette section n’enregistre aucun fichier de Release, et un build qui dispose d’un tel fichier de verrouillage signale la Release comme non enregistrée. Un fichier que la Release importe via parameters n’est pas enregistré ici. |
schema_libraries | LibraryEntry[] | non | Entrées de SchemaLibrary que la fermeture des dépendances de la Release atteint par les sites $ref et $import: dans le contenu schema: / usesSchema: / featuresSchema: des entités. La liste consumers de chaque entrée enregistre quelle entité du catalogue référence quels fragments <entry-name> de la bibliothèque — un enregistrement structuré qui rend traçables les diffs d’impact d’une montée de version de la bibliothèque sans résoudre de nouveau la Release. Par défaut : [] |
source_artifacts | SourceArtifactEntry[] | non | Artefacts source récupérés depuis les champs spec.source de Recipe / FeatureRecipe au moment du pull. Chaque entrée identifie une identité {kind, url, chart, pinned_version} unique avec le digest du contenu, le type de média et les pointeurs de retour structurés referenced_by: nommant chaque entité du catalogue qui s’est résolue vers cet artefact. url est l’URL d’identité rédigée ; l’emplacement résolu de l’artefact pour une source helm à racine de dépôt est enregistré séparément sous resolved_url: comme provenance. Plusieurs Recipes épinglant le même chart à la même version sont dédupliquées en une seule entrée avec plusieurs enregistrements referenced_by:. L’énumération des types couvre les quatre types de source qui se résolvent, et terraform-module-oci, qu’aucun adaptateur de source ne sert : une Recipe ou une FeatureRecipe qui le nomme est refusée dès sa lecture, de sorte qu’aucun pull n’enregistre d’entrée de ce type. Par défaut : [] |
toolchain | object | non | Versions de la chaîne d’outils qui a produit ce fichier de verrouillage : la version propre du compilateur, et la version de chaque plugin core que le compilateur embarque. Enregistrées pour qu’un fichier de verrouillage indique après coup quel compilateur et quels plugins core ont résolu et rendu un build — une question à laquelle les sections épinglées ne peuvent pas toujours répondre, car un plugin de fournisseur core servi depuis l’intérieur du binaire du compilateur reste non épinglé et ne porte donc aucune version enregistrée qui lui soit propre. Uniquement des versions : le tampon n’enregistre jamais d’où proviennent les octets d’un plugin, de sorte que deux machines qui ont épinglé la même fermeture des dépendances avec le même compilateur écrivent le même tampon. Rien ne compare cette section, n’avertit à son sujet ni ne refuse un build à cause d’elle, et son absence d’un fichier de verrouillage est silencieuse : la chaîne d’outils ne fait pas partie de la fermeture des dépendances qu’épingle le fichier de verrouillage. Pour la même raison, la section est exemptée de la comparaison d’identité octet pour octet entre deux pulls des mêmes entrées, au même titre que generated_at. |
verdict_inputs | object[] | non | Entrées de règles externes qu’un rattachement de gouvernance à rôle de verdict (ir-verdict / render-verdict) lit à la compilation — un fichier de règles Kyverno / Rego fourni via le with.sources du rattachement. Enregistrées sous forme d’un digest du contenu par source, à des fins d’audit et de visibilité de la dérive d’un pull à l’autre : le digest qui a façonné un verdict peut être comparé d’un pull à l’autre, de sorte qu’un fichier de règles modifié apparaît comme un diff du fichier de verrouillage. Cette section est de la PROVENANCE, pas une entrée du build : contrairement à mutators.sources, elle ne porte aucun content, et le build ne la lit PAS — un plugin de verdict est mis en cache plutôt qu’épinglé et lit ses entrées de règles en direct (le verdict ne façonne aucun octet de sortie, de sorte que rien de ce que le fichier de verrouillage épingle pour une sortie déterministe ne l’inclut). Comme un plugin de verdict n’est pas épinglé, il est absent des sections entities / plugins ; cet enregistrement identifie donc le rattachement par son URI rédigé, de manière autonome plutôt qu’en pointant vers ces sections. Enregistrer le digest rend les entrées qui ont déterminé une décision d’acceptation ou de rejet auditables et reproductibles sans les épingler dans le build. Par défaut : [] |
version | const 1 | oui | Version du schéma du fichier de verrouillage : 1. Une modification SemVer-MAJOR du schéma l’incrémente. Constante : 1 |
workload_libraries | LibraryEntry[] | non | Entrées de WorkloadLibrary que la fermeture des dépendances de la Release atteint par les sites workload: { $import: ... } de Recipe. La liste consumers de chaque entrée enregistre quelle entité du catalogue référence quels fragments <entry-name> de la bibliothèque — un enregistrement structuré qui rend traçables les diffs d’impact d’une montée de version de la bibliothèque sans résoudre de nouveau la Release. Par défaut : [] |
artifact_libraries | LibraryEntry[] | non | Entrées d’ArtifactLibrary que la fermeture des dépendances de la Release atteint par les sites artifacts.<name>: { $import: ... } de Recipe / FeatureRecipe. La liste consumers de chaque entrée enregistre quelle entité du catalogue référence quels bundles <entry-name> de la bibliothèque — un enregistrement structuré qui rend traçables les diffs d’impact d’une montée de version de la bibliothèque sans résoudre de nouveau la Release. Par défaut : [] |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.entities[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
kind | string (enum) | oui | Type de l’entité du catalogue, lu là où la Release, son Aggregate ou son Manifest la nomme : component et feature pour un type de Component ou de Feature que nomme l’Aggregate, la Release ou un mapping de Manifest, recipe et feature_recipe pour une réalisation que lie un mapping de Manifest, plugin pour une entité Plugin, aggregate pour l’Aggregate propre à la Release et chaque Aggregate qu’il inclut, et manifest pour le Manifest propre à la Release et le Manifest qu’il étend. Avec uri, il identifie l’entrée : un build compare chaque entrée à l’entité de même type et de même URI, de sorte qu’une modification de l’une ou l’autre de deux entités homonymes de types différents est remarquée. Valeurs autorisées : "aggregate", "component", "feature", "feature_recipe", "manifest", "plugin", "recipe" |
uri | string | oui | URI canonique de l’entité du catalogue (par ex. hub.aggrega.ai/component/core/compute/api-server). |
resolved_version | string | oui | Version concrète que le résolveur a sélectionnée au moment du pull — la version propre d’une entité du catalogue (par ex. 1.2.3), ou vide pour une entité de premier niveau résolue par chemin plutôt que par version. Enregistrée sous la forme d’un seul segment de chemin, car elle en nomme un, de sorte qu’elle ne contient ni /, ni \, ni .. : la valeur construit l’emplacement du cache à partir duquel le build relit cette entité, et une valeur qui sortirait du répertoire du cache nommerait un emplacement situé en dehors de celui-ci. Motif : ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | oui | Digest de ce que porte une publication de l’entité, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules : le SHA-256 calculé sur le document de l’entité et sur chaque fichier qu’elle déclare à côté de lui, triés par chemin, chacun apportant son chemin et le SHA-256 de ses octets. Une entité qui ne déclare aucun fichier compte comme son unique document. Rien d’autre n’y entre — ni la façon dont une archive a été compressée, ni un horodatage, ni aucun bit de permission, le bit d’exécution compris — de sorte que l’entité enregistre le même digest qu’elle soit lue depuis un répertoire de catalogue ou récupérée depuis un registre, et sur tout checkout des mêmes fichiers, sur tout système. Motif : ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | non | Digest du manifeste OCI de l’artefact résolu, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. La signature engage ce digest, et le manifeste nomme le digest des octets publiés, par rapport auquel une récupération et une lecture en cache sont vérifiées avant que l’entité soit confrontée à son digest ci-dessus. Présent uniquement pour une entité résolue depuis un registre. Motif : ^sha256:[a-f0-9]{64}$. |
referenced_from | string[] | non | Origines sur les sites d’écriture — chemins pointés dans le YAML de Release / Aggregate / Manifest (par ex. aggregate.spec.components.api.type) qui enregistrent pourquoi cet URI se trouve dans la fermeture des dépendances de la Release. Par défaut : [] |
signature | VerifiedSignature | non | Fait de signature vérifiée enregistré lorsque la signature de cette entité a été vérifiée au moment du pull, par rapport à la politique de confiance du registre qui l’a résolue. |
deprecation | DeprecationRecord | non | Marqueur de dépréciation rétroactif vérifié, enregistré lorsqu’un marqueur de dépréciation signé et de confiance a été découvert sur cet artefact au moment du pull. Un marqueur est un referrer OCI signé de l’artefact qu’il déprécie, attaché après la publication sans republier l’artefact. Enregistre la sévérité et le message du marqueur ainsi que le signataire vérifié qui l’a rédigé. Le build lit ce fait et applique la politique de dépréciation à partir du seul fichier de verrouillage ; il ne redécouvre ni ne revérifie jamais le marqueur. |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.mutators[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
plugin | string | oui | Coordonnée de plugin résolue du plugin à rôle de transformation — l’identité <pluginType>/<name> d’une entité Plugin (par ex. governance/tag-injector). Se joint par identité aux sections plugins et entities pour le digest épinglé et l’ensemble des versions. |
role | string (enum) | oui | Le rôle de transformation auquel ce rattachement est lié, enregistré tel quel à partir de l’entrée plugins.governance rédigée, de sorte qu’un build exécute le rattachement exactement dans ce rôle plutôt que d’en déduire un : label-transform réécrit les labels des nœuds lors de la construction de la topologie ; annotation-transform injecte des annotations avant l’expansion, pendant la résolution. Valeurs autorisées : "label-transform", "annotation-transform" |
function | string | non | Surcharge de l’export que nomme le rattachement. En son absence, l’export par défaut du rôle est sélectionné (mutate pour label-transform, transform_annotations pour annotation-transform). |
settings | object | non | Objet de réglages de forme libre que le rattachement a déclaré, épinglé tel que rédigé et transmis tel quel au plugin. Le build lit les réglages ici — jamais dans la configuration en vigueur — de sorte qu’une modification des réglages postérieure au pull ne déplace pas la sortie du build. Absent lorsque le rattachement n’en déclare aucun. |
sources | object[] | non | Épinglages adressés par contenu des fichiers sources déclarés par le rattachement, dans l’ordre des noms de base. Le build reconstruit la source que lit le plugin à partir du contenu enregistré de chaque épinglage plutôt que d’une lecture en direct sur l’hôte, de sorte que la sortie du build reste invariante à une modification du fichier source postérieure au pull. Absent lorsque le rattachement n’en déclare aucun. |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.mutators[].sources[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
content | string | oui | Le contenu du fichier source, porté tel quel afin que le build reconstruise l’entrée source du plugin à partir du fichier de verrouillage. |
digest | string | oui | L’adresse de contenu du contenu enregistré, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. Un nouveau pull compare le fichier sous-jacent à ce digest pour détecter une dérive. Motif : ^sha256:[a-f0-9]{64}$. |
path | string | oui | Le nom de base du fichier source — jamais un chemin absolu de l’hôte, de sorte que l’épinglage est portable et déterministe. |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.plugins[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
uri | string | oui | Identité nue de l’artefact .wasm du plugin Wasm — le chemin <pluginType>/<name> (par ex. governance/aggrega-security-baseline). Le premier segment est le type du plugin (provider, linter, pipeline-step, governance, cli, parser, importer) ; le segment suivant est le nom du plugin. Le type et le nom forment ensemble l’identité du plugin — le même nom sous deux types correspond à deux plugins. L’emplacement physique de récupération est dérivé de cette identité et du registre configuré, et n’est jamais porté dans le fichier de verrouillage. |
resolved_version | string | oui | Le digest du contenu vers lequel l’artefact Wasm s’est résolu, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. Un artefact de plugin est adressé par contenu plutôt que nommé par version — un .wasm voyage inline dans le manifeste de son plugin et est épinglé par le digest de ses octets — de sorte que ce champ enregistre ce digest, qui est aussi le digest ci-dessous. Il construit l’emplacement du cache à partir duquel le build relit l’artefact, de sorte qu’il ne contient ni /, ni \, ni .., ce que la forme sha256: exclut déjà. Motif : ^sha256:[a-f0-9]{64}$. |
digest | string | oui | Digest du contenu de l’artefact Wasm résolu, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules — la forme sous laquelle l’adresse de contenu est écrite partout où elle est comparée. Motif : ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | non | Digest du manifeste OCI de l’artefact Wasm résolu, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. La signature engage ce digest ; le digest du contenu ci-dessus est l’identité portable utilisée pour l’épinglage dans le cache et le contrôle d’intégrité. Présent uniquement pour un artefact résolu depuis un registre. Motif : ^sha256:[a-f0-9]{64}$. |
referenced_from | string[] | non | Pourquoi cet artefact se trouve dans la fermeture des dépendances de la Release : la référence de chaque entité Plugin par laquelle il a été atteint, telle que la section entities enregistre cette entité (par ex. governance/label-injector:1.0.0). Par défaut : [] |
signature | VerifiedSignature | non | Fait de signature vérifiée enregistré lorsque la signature de ce plugin a été vérifiée au moment du pull, par rapport à la même politique de confiance par registre que pour les entités du catalogue. |
deprecation | DeprecationRecord | non | Marqueur de dépréciation rétroactif vérifié, enregistré lorsqu’un marqueur de dépréciation signé et de confiance a été découvert sur cet artefact au moment du pull. Un marqueur est un referrer OCI signé de l’artefact qu’il déprécie, attaché après la publication sans republier l’artefact. Enregistre la sévérité et le message du marqueur ainsi que le signataire vérifié qui l’a rédigé. Le build lit ce fait et applique la politique de dépréciation à partir du seul fichier de verrouillage ; il ne redécouvre ni ne revérifie jamais le marqueur. |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.providers[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
capability | string | oui | La capacité pour laquelle cette liaison sélectionne un fournisseur — le nom nu de la capacité qu’une Recipe lie via spec.capability (par ex. helm, compose). |
plugin | string | oui | Identité nue du plugin de rendu du fournisseur résolu (l’identité de l’entité Plugin, son metadata.pluginType et son metadata.name joints par une barre oblique, par ex. provider/helm). Se joint par identité aux sections plugins et entities pour le digest épinglé et l’ensemble des versions. |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.release_documents[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
digest | string | oui | Le digest du contenu des octets du fichier de Release au moment où la résolution les a lus, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. Motif : ^sha256:[a-f0-9]{64}$. |
path | string | oui | Le chemin du fichier de Release relatif au répertoire qui contient la Release à laquelle appartient ce fichier de verrouillage, avec des barres obliques (par ex. release-prod.yaml, ../shared/base-release.yaml) — jamais un chemin absolu de l’hôte, de sorte que l’entrée est portable et déterministe. |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.toolchain
Versions de la chaîne d’outils qui a produit ce fichier de verrouillage : la version propre du compilateur, et la version de chaque plugin core que le compilateur embarque. Enregistrées pour qu’un fichier de verrouillage indique après coup quel compilateur et quels plugins core ont résolu et rendu un build — une question à laquelle les sections épinglées ne peuvent pas toujours répondre, car un plugin de fournisseur core servi depuis l’intérieur du binaire du compilateur reste non épinglé et ne porte donc aucune version enregistrée qui lui soit propre. Uniquement des versions : le tampon n’enregistre jamais d’où proviennent les octets d’un plugin, de sorte que deux machines qui ont épinglé la même fermeture des dépendances avec le même compilateur écrivent le même tampon. Rien ne compare cette section, n’avertit à son sujet ni ne refuse un build à cause d’elle, et son absence d’un fichier de verrouillage est silencieuse : la chaîne d’outils ne fait pas partie de la fermeture des dépendances qu’épingle le fichier de verrouillage. Pour la même raison, la section est exemptée de la comparaison d’identité octet pour octet entre deux pulls des mêmes entrées, au même titre que generated_at.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
compiler_version | string | oui | Version du compilateur qui a écrit ce fichier de verrouillage, sous la forme sans v que signale chaque surface d’Aggrega (1.2.0, et non v1.2.0). Un build portant le tampon d’une version enregistre cette version — un build de release taggé, son tag — et un build sans tampon de version enregistre le marqueur (devel), de sorte qu’un fichier de verrouillage produit par un compilateur sans tampon ne soit pas pris pour une sortie de release. Enregistrée sous la forme d’un seul segment de chemin, de sorte qu’elle ne contient ni /, ni \, ni ... Motif : ^([^/\\.]|\.[^/\\.])*\.?$. |
core_plugins | object[] | oui | Version de chaque plugin core que porte le compilateur, une entrée par plugin, triées par coordonnée de plugin. Un plugin core est publié sur le tag propre du compilateur à la même version, de sorte que ces versions se lisent de la même façon, que le compilateur ait servi un plugin depuis son propre intérieur ou l’ait récupéré depuis un registre — c’est ce qui garde le tampon exempt de détails propres à la machine. Vide pour un build qui ne porte aucun plugin core. Par défaut : [] |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.toolchain.core_plugins[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
plugin | string | oui | Coordonnée du plugin core — l’identité <pluginType>/<name> d’une entité Plugin (par ex. provider/helm), la même identité par laquelle les sections providers et mutators nomment un plugin. |
version | string | oui | Version de ce plugin core, sous la forme sans v que signale chaque surface d’Aggrega. Enregistrée sous la forme d’un seul segment de chemin, de sorte qu’elle ne contient ni /, ni \, ni ... Motif : ^([^/\\.]|\.[^/\\.])*\.?$. |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.verdict_inputs[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
plugin | string | oui | L’URI de plugin rédigé du rattachement de verdict, tel qu’écrit dans .aggrega-config.yaml plugins.governance (par ex. governance/aggrega-security-baseline:1.0.0). Identifie le rattachement auquel appartiennent les entrées de règles enregistrées ; un plugin de verdict est mis en cache plutôt qu’épinglé, de sorte qu’il n’a aucune entrée dans les sections plugins / entities à laquelle se joindre. |
role | string (enum) | oui | Le rôle de verdict auquel ce rattachement est lié — ir-verdict (lors de l’analyse statique, sur le graphe IR) ou render-verdict (lors du rendu, sur les artefacts rendus). Distingue le même plugin rattaché aux deux étapes de verdict, chacune pouvant avoir ses propres entrées de règles. Valeurs autorisées : "ir-verdict", "render-verdict" |
sources | object[] | non | Digests du contenu des fichiers d’entrée de règles déclarés par le rattachement, dans l’ordre des noms de base. Absent lorsque le rattachement ne déclare aucune source. |
Les propriétés supplémentaires ne sont pas autorisées.
lockfile.verdict_inputs[].sources[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
digest | string | oui | L’adresse de contenu des octets du fichier d’entrée de règles au moment du pull, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. Un nouveau pull la recalcule, de sorte qu’un fichier de règles modifié apparaît comme un diff du fichier de verrouillage. Motif : ^sha256:[a-f0-9]{64}$. |
path | string | oui | Le nom de base du fichier d’entrée de règles — jamais un chemin absolu de l’hôte, de sorte que l’entrée est portable et déterministe. |
Les propriétés supplémentaires ne sont pas autorisées.
Définitions
DeprecationRecord
Marqueur de dépréciation rétroactif vérifié, enregistré lorsqu’un marqueur de dépréciation signé et de confiance a été découvert sur cet artefact au moment du pull. Un marqueur est un referrer OCI signé de l’artefact qu’il déprécie, attaché après la publication sans republier l’artefact. Enregistre la sévérité et le message du marqueur ainsi que le signataire vérifié qui l’a rédigé. Le build lit ce fait et applique la politique de dépréciation à partir du seul fichier de verrouillage ; il ne redécouvre ni ne revérifie jamais le marqueur.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
message | string | oui | Message de dépréciation lisible par un humain porté par le marqueur — généralement une indication de migration. |
severity | string (enum) | oui | Sévérité du marqueur, ordonnée warning < error < retracted. Le build s’interrompt lorsque cette sévérité atteint ou dépasse le seuil d’interruption configuré, et émet un avis sinon. Valeurs autorisées : "warning", "error", "retracted" |
signer | VerifiedSignature | non | Signataire vérifié du marqueur, enregistré de la même façon que le signataire de la signature d’un artefact : le sujet/émetteur du certificat pour la signature keyless, ou l’empreinte de la clé épinglée pour la signature avec clé. Un marqueur est un artefact signé à part entière, de sorte que son signataire a la même forme que la signature d’un artefact — et le bundle_digest ici nomme le bundle de signature propre au marqueur plutôt que celui de l’artefact déprécié. |
Les propriétés supplémentaires ne sont pas autorisées.
ExternalInput
Une entrée externe épinglée unique : l’URL qu’un rendu a demandée, l’épinglage SHA-256 qui nomme ses octets dans le magasin d’entrées adressé par contenu (sha256/<digest>), la taille de la charge utile et la provenance des consommateurs qui l’ont requise. L’épinglage fait autorité — une URL épinglée est toujours servie depuis le magasin, et un nouveau remplissage du magasin est vérifié par rapport à ce digest avant que les octets n’atteignent un rendu.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
required_by | string[] | oui | Provenance — les sites de rendu qui ont demandé cette entrée. Triés et dédupliqués par le rédacteur du fichier de verrouillage. |
sha256 | string | oui | Épinglage SHA-256 en hexadécimal minuscule. Pour une entrée https, le digest des octets de la charge utile ; pour une entrée oci, le digest du manifeste vers lequel la référence s’est résolue. Nomme le blob du magasin à sha256/<digest>. Motif : ^[0-9a-f]{64}$. |
size | integer | oui | Taille en octets de la charge utile épinglée. Un nombre d’octets n’est jamais négatif. Minimum : 0. |
url | string | oui | L’URL de l’entrée telle que rédigée au site de rendu — la clé de recherche qui fait correspondre une requête au moment du rendu à son épinglage. |
Les propriétés supplémentaires ne sont pas autorisées.
LibraryEntry
Forme commune partagée par les entrées de schema_libraries, mapping_libraries, workload_libraries et artifact_libraries. La liste consumers capture la relation dans le graphe du catalogue — quelle entité du catalogue référence quels fragments <entry-name> de cette bibliothèque — et prend en charge des diffs d’impact structurés lorsque le digest de la bibliothèque change. Une bibliothèque est un artefact OCI comme un autre, de sorte qu’elle enregistre les mêmes faits vérifiés qu’une entité du catalogue : le digest du manifeste qu’engage sa signature, la signature vérifiée elle-même et tout marqueur de dépréciation rétroactif vérifié découvert au moment du pull.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
uri | string | oui | URI canonique de l’entité de bibliothèque. |
resolved_version | string | oui | Version concrète résolue au moment du pull (sélection de version minimale sur le graphe des dépendances entre bibliothèques) — la version propre de la bibliothèque. Enregistrée sous la forme d’un seul segment de chemin, car elle construit l’emplacement du cache à partir duquel le build relit la bibliothèque, de sorte qu’elle ne contient ni /, ni \, ni .. : une valeur qui sortirait du répertoire du cache nommerait un emplacement situé en dehors de celui-ci. Motif : ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | oui | Digest du contenu de l’artefact de bibliothèque résolu, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules — la forme sous laquelle l’adresse de contenu est écrite partout où elle est comparée. Motif : ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | non | Digest du manifeste OCI de l’artefact de bibliothèque résolu, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. La signature engage ce digest ; le digest du contenu ci-dessus est l’identité portable utilisée pour l’épinglage dans le cache et le contrôle d’intégrité. Présent uniquement pour une bibliothèque résolue depuis un registre. Motif : ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | non | Fait de signature vérifiée enregistré lorsque la signature de cette bibliothèque a été vérifiée au moment du pull, par rapport à la même politique de confiance par registre que pour les entités du catalogue. |
deprecation | DeprecationRecord | non | Marqueur de dépréciation rétroactif vérifié découvert sur cette bibliothèque au moment du pull. Le build le signale et, là où l’espace de travail a configuré un seuil d’interruption que la sévérité enregistrée atteint, s’interrompt — de sorte qu’une bibliothèque retirée après l’épinglage de la version est annoncée à chaque build plutôt qu’uniquement lors de la sélection de version, que contourne une version épinglée explicitement. |
consumers | object[] | non | Enregistrements indiquant quelle entité du catalogue référence cette bibliothèque et à quels fragments <entry-name>. Capture le fan-in : de nombreux consommateurs par bibliothèque, chacun pouvant référencer de nombreux fragments. Chaque enregistrement porte l’URI du consommateur ainsi que l’ensemble des fragments que ce consommateur intègre. Par défaut : [] |
Les propriétés supplémentaires ne sont pas autorisées.
LibraryEntry.consumers[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
consumer_uri | string | oui | URI canonique de l’entité du catalogue qui référence cette bibliothèque : un Component ou une Feature pour une bibliothèque de schémas, une Recipe ou une FeatureRecipe pour une bibliothèque de mappings, de workloads ou d’artefacts, ou une autre bibliothèque du même type dont les entrées référencent celle-ci. |
fragments | string[] | oui | Ensemble des fragments <entry-name> que ce consommateur référence au sein de la bibliothèque (par ex. ["#/schemas/PortSpec", "#/schemas/EndpointSpec"]). L’ordre est canonisé lexicographiquement par le rédacteur. |
Les propriétés supplémentaires ne sont pas autorisées.
SourceArtifactEntry
Un épinglage unique d’artefact source : l’identité {kind, url, chart, module_subdir, pinned_version}, le digest du contenu qui vérifie le pull, le type de média canonique et les pointeurs de retour structurés vers chaque entité du catalogue qui s’est résolue vers cet artefact. chart et module_subdir sont les deux termes sélecteurs — chacun nomme ce que l’URL seule ne nomme pas, pour les types qui en ont besoin.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
kind | enum | oui | Le type de source. Détermine quel adaptateur a résolu l’artefact et quel type de média est attendu. terraform-module-oci appartient à l’ensemble, et aucun adaptateur de source ne le sert : une Recipe ou une FeatureRecipe qui le nomme est refusée dès sa lecture. Valeurs autorisées : "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci" |
url | string | oui | L’URL rédigée — l’URL d’identité telle qu’écrite dans spec.source.url de la Recipe. Pour helm-https-chart, il s’agit de la racine du dépôt (forme racine de dépôt) ou du .tgz direct (forme directe), exactement tel que rédigé ; le build reconstruit cette même URL hors ligne, c’est donc l’identité stable sur laquelle l’épinglage est indexé. Pour git-repository, l’URL du dépôt clonable. Pour helm-oci-chart, la référence de registre. Pour compose-https-fragment, l’URL HTTPS du fragment. L’emplacement résolu de l’artefact pour une source helm à racine de dépôt est enregistré séparément sous resolved_url: comme provenance. |
chart | string | non | Le nom du chart pour une source helm à racine de dépôt (spec.source.chart de la Recipe), qui fait partie de l’identité {kind, url, chart, module_subdir, pinned_version}, de sorte que deux charts servis depuis une même racine de dépôt à la même version s’épinglent sur des entrées distinctes. Absent pour une source .tgz directe, OCI, compose ou git, dont aucune ne sélectionne un chart au sein de l’URL. |
module_subdir | string | non | Le répertoire, au sein d’un dépôt issu de git, qui constitue l’artefact (spec.source.module_subdir de la Recipe), qui fait partie de l’identité {kind, url, chart, module_subdir, pinned_version}, de sorte que deux répertoires d’un même dépôt au même commit s’épinglent sur des entrées distinctes. Absent lorsque le dépôt entier est l’artefact, ainsi que pour tout type qui atteint son artefact par URL plutôt qu’en descendant dans un clone. |
pinned_version | string | oui | La version concrète épinglée au moment du pull. Pour les types helm-*, la version du chart. Pour git-repository, le commit vers lequel la référence rédigée s’est résolue (PAS la référence de tag/branche d’origine — celle-ci est enregistrée sous requested_ref: sur chaque entrée referenced_by:, chaque fois que la Recipe a rédigé un spec.source.ref:). Un build trouve cette entrée d’après ce que la Recipe a écrit : le ref: rédigé s’il y en a un, mis en correspondance avec le requested_ref: enregistré, et cette valeur épinglée sinon — de sorte qu’une Recipe qui nomme un tag se résout vers le commit auquel ce tag a été épinglé, sans que le commit apparaisse jamais dans la Recipe. Enregistrée sous la forme d’un seul segment de chemin, car elle construit l’emplacement du cache à partir duquel le build relit l’artefact, de sorte qu’elle ne contient ni /, ni \, ni ... Motif : ^([^/\\.]|\.[^/\\.])*\.?$. |
resolved_url | string | non | Provenance uniquement : l’emplacement concret de l’artefact vers lequel l’URL rédigée s’est résolue au moment du pull. Pour une source helm à racine de dépôt, il s’agit de l’URL du .tgz direct vers laquelle l’index du dépôt a résolu chart+version ; elle est enregistrée à des fins de diagnostic et ne fait PAS partie de l’identité de l’artefact. Absent lorsque l’emplacement résolu est égal à l’URL rédigée (une source .tgz directe, OCI, compose ou git). |
digest | string | oui | Digest du contenu de l’archive .tar.gz résolue, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. La vérification au moment du build lit les octets de l’emplacement du cache, recalcule le digest et le compare à ce champ ; une discordance interrompt le build en signalant une discordance du digest du contenu. Motif : ^sha256:[a-f0-9]{64}$. |
manifest_digest | string | non | Digest du manifeste OCI de l’artefact résolu, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. Le manifeste est la racine de confiance indépendante par rapport à laquelle l’archive en cache est vérifiée ; le digest du contenu ci-dessus est l’identité portable utilisée pour l’épinglage dans le cache et le contrôle d’intégrité. Présent uniquement pour une source distribuée via OCI (un helm-oci-chart). Motif : ^sha256:[a-f0-9]{64}$. |
mediatype | string | oui | Type de média canonique annoncé par le registre (ou la valeur par défaut du type pour les types sans métadonnées de registre). Enregistré à titre de provenance diagnostique. |
referenced_by | SourceArtifactReference[] | oui | Entités du catalogue qui se sont résolues vers cet artefact, triées par (uri, field) pour une sortie déterministe. Une entrée n’existe que parce qu’une Recipe ou une FeatureRecipe l’a récupérée par un pull, de sorte que la liste n’est jamais vide. Au moins 1 entrée. |
Les propriétés supplémentaires ne sont pas autorisées.
SourceArtifactReference
Un pointeur de retour unique entité du catalogue → artefact source. entity + uri identifient ensemble l’entité du catalogue ; field nomme le chemin côté source dans la spec de l’entité où l’artefact a été déclaré. Le requested_ref: facultatif conserve le spec.source.ref: rédigé de la Recipe, et il est écrit chaque fois que la Recipe en a rédigé un (tags/branches git-repository → SHA du commit).
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
entity | enum | oui | Le type d’entité du catalogue qui porte ce pointeur de retour. Valeurs autorisées : "recipe", "feature_recipe" |
uri | string | oui | URI canonique de la Recipe ou de la FeatureRecipe (par ex. hub.aggrega.ai/recipe/helm/mariadb-bitnami:1.0.0). |
field | string | oui | Chemin côté source dans la spec de l’entité où l’artefact a été déclaré. La valeur est spec.source. |
requested_ref | string | non | Facultatif — le spec.source.ref: rédigé de la Recipe, écrit chaque fois que la Recipe en a rédigé un. Pour une Recipe git-repository qui rédige ref: v1.0.0, ceci conserve "v1.0.0" tandis que pinned_version: contient le commit vers lequel cette référence s’est résolue. Absent lorsque la Recipe ne rédige aucun ref:, ce qui est le cas de tout type dont le résolveur épingle tel quel la version rédigée (helm-, compose-). Il remplit deux rôles à la fois, et c’est son enregistrement inconditionnel qui les empêche de s’exclure mutuellement. Un build s’en sert comme clé de jointure pour trouver cette entrée à partir d’une Recipe qui nomme la référence plutôt que le commit. Et un pull qui n’est pas une mise à niveau maintient chaque référence enregistrée à sa version épinglée : une référence qui s’est déplacée sur son dépôt distant interrompt l’exécution au lieu d’être adoptée. |
Les propriétés supplémentaires ne sont pas autorisées.
VerifiedSignature
Fait de signature vérifiée enregistré lorsque la signature d’un artefact a été vérifiée au moment du pull, par rapport à la politique de confiance du registre qui l’a résolu. Tout artefact signable l’enregistre de la même façon — une entité du catalogue, une bibliothèque, un plugin Wasm — car tous sont vérifiés par un seul chemin plutôt que par un chemin par type. Enregistre le mode de vérification, l’identité/l’émetteur keyless qui a correspondu (en mode keyless) et le digest adressé par contenu du bundle de signature dans le cache de contenu. Le build ne relance pas la vérification. Avant tout rendu, il lit ce fait sur chaque entrée à partir de laquelle il construit, dans chaque section : il recalcule le hachage du bundle en cache et compare le résultat à bundle_digest, en s’interrompant là où le blob est manquant ou diffère ; et pour une entrée que le cache de contenu a servie, il lit dans ce bundle pour quel artefact la signature a été établie, et s’interrompt là où elle a été établie pour un artefact différent de celui que le build a lu pour l’entrée — de sorte qu’une signature copiée d’une entrée sur une autre est refusée, quoi que dise l’exigence de signature. Un build ne vérifie aucune signature, de sorte qu’un bundle écrit à la main dans le cache, établi pour l’artefact propre de l’entrée, ne se distingue pas d’un bundle qu’un pull a vérifié. Et là où la configuration de confiance de l’espace de travail exige une signature pour une entrée que le cache de contenu a servie — l’exigence que pull applique lorsqu’il récupère l’artefact, de sorte que les exemptions et un registre advisory qui permettent à un pull d’admettre un artefact sans signature permettent aussi au build d’admettre son entrée — une entrée qui ne porte aucun fait interrompt le build. Une entrée lue depuis un répertoire de catalogue, depuis la copie intégrée au binaire du compilateur ou depuis l’emplacement situé à côté de la Release n’est jamais soumise à cette exigence.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
bundle_digest | string | oui | Digest SHA-256 du blob du bundle de signature en cache, sous la forme sha256: suivi de 64 caractères hexadécimaux en minuscules. Il nomme le blob du cache, de sorte qu’il construit un chemin et ne contient ni /, ni \, ni .. — ce que la forme sha256: exclut déjà — et, sur une entrée de n’importe quelle section, c’est ce par rapport à quoi un build recalcule le hachage de ce blob. Motif : ^sha256:[a-f0-9]{64}$. |
identity | string | non | Signataire vérifié de la signature : le sujet du certificat de signature pour une signature keyless, ou keyed:sha256: suivi du SHA-256 du texte PEM de la clé publique épinglée pour une signature avec clé. |
issuer | string | non | Émetteur OIDC vérifié pour une signature keyless. Vide pour une signature avec clé. |
mode | string (enum) | oui | Mode de vérification qui a admis la signature. Valeurs autorisées : "keyless", "keyed" |
Les propriétés supplémentaires ne sont pas autorisées.