Manifestes de version d’application

Une définition d’application identifie son propriétaire, son organisation, son espace de travail, son environnement, son audience et son statut (publiée ou retirée). Sa version enregistre un condensat immuable de la source, un condensat de l’artefact de dépendances, un condensat de l’image d’exécution, un condensat du widget et les révisions exactes du schéma d’ontologie. L’identifiant de version de l’application est distinct de l’identifiant de révision d’une ontologie.

Les nouvelles versions lient aussi runtime.dependencyDigest : l’intention d’environnement vérifiée sous l’image épinglée. Il diffère de dependencies.sha256, qui identifie l’archive de paquets résolue. Le démarrage de l’exécution a besoin des deux ; il restaure l’archive sans résoudre à nouveau les paquets ni consulter la session de préparation de l’auteur. Les anciens manifestes restent lisibles avec leurs hachages d’origine, mais une version dépourvue de cette liaison nécessite une nouvelle validation et une nouvelle publication avant de pouvoir s’exécuter ou devenir une cible de retour arrière. La réconciliation d’une publication déjà validée fonctionne toujours.

Les schémas sûrs pour le navigateur sont exportés par @scrydon/ontology-sdk/client et @scrydon/sdk-authoring/ontologies/manifest :

import {
  AppPayloadSchema,
  AppReleaseSchema,
  AppPermitSchema,
} from "@scrydon/ontology-sdk/client";

const definition = AppPayloadSchema.parse(receivedDefinition);
const release = AppReleaseSchema.parse(definition.release);
const permit = AppPermitSchema.parse(release.permit);

L’analyse valide le contrat. Elle ne publie pas l’application, ne valide pas les octets de l’artefact stocké et n’autorise pas un lecteur. Les définitions d’application exigent le workflow de cycle de vie des applications ; les déclarations de schéma génériques, les modifications de branche et les propositions de schéma ne peuvent ni les publier ni les retirer.

Les entrées du cycle de vie sont validées avec AppPublishInputSchema, AppRollbackInputSchema et AppWithdrawInputSchema. La publication prend un candidat enregistré, des notes de version, des preuves de validation issues du plan de contrôle de confiance et expectedStateId (null uniquement pour la première publication). Le serveur déduit le propriétaire, l’éditeur, l’identifiant de version, l’horodatage et le tenant. Un candidat analysé ou un condensat généré par le client ne peut pas remplacer les preuves de validation.

expectedStateId identifie le fait de cycle de vie courant, et pas seulement sa version : un retour arrière vers une version antérieure crée tout de même un nouvel état. Un état périmé renvoie un conflit. Réessayer la même action avec sa clé d’idempotence d’origine renvoie son résultat d’origine ; modifier cette requête exige une nouvelle clé.

Le retour arrière exige une nouvelle validation d’une version conservée. Il préserve l’audience, la propriété et les métadonnées actuelles de l’application. Le retrait conserve les artefacts immuables et incrémente revocationEpoch ; une republication préserve ce compteur afin que les sessions précédemment révoquées ne puissent pas redevenir valides.

Le permis contient ces déclarations explicites :

Pour une application créée avec marimo, écrivez l’accès demandé dans le notebook enregistré avec apps.declare(...) du SDK Python et les assistants apps.ontology, apps.query, apps.link, apps.allow_action et apps.allow_watch. L’éditeur compile statiquement les appels littéraux, résout les épingles d’ontologie publiées accessibles et affiche le permis obtenu pour relecture. Les valeurs d’exécution et les expressions Python arbitraires ne sont pas des déclarations de publication. Les assistants eux-mêmes n’effectuent aucune lecture de données, aucune attribution, aucune soumission d’action et aucune installation de surveillance. Consultez le guide de création marimo pour un exemple.

Les jokers de propriété et les alias d’ontologie non déclarés sont rejetés. Les filtres de base sont des contraintes obligatoires ; les filtres supplémentaires du lecteur ne peuvent que les restreindre. Les opérations d’exécution doivent faire l’intersection de ce permis avec les autorisations actuelles du lecteur et la politique actuelle de la source. Les épingles de schéma ne figent pas les données en direct et ne préservent pas les autorisations révoquées.

Les identifiants d’autorité, les références de ressource et les valeurs des filtres de base doivent être en Unicode NFC. Les valeurs non canoniques sont rejetées afin que le scellement du manifeste ne puisse pas sélectionner silencieusement un autre utilisateur, tenant, ressource ou valeur de source.

Les déclarations d’action renvoient à des actions d’ontologie créées et exécutables, et non à des opérations de gestion du noyau. Les entrées sont limitées aux noms déclarés, au contrat de champs typés de l’action et à maxInputBytes (16 Kio au plus). Les exigences existantes d’approbation humaine s’appliquent toujours. Déclarer une action ne l’exécute pas et ne l’autorise pas.

Les chaînes d’action doivent être du texte UTF-8 PostgreSQL valide : NUL et les substituts Unicode non appariés sont rejetés avant la soumission ou le stockage de l’intention. Les intégrateurs du SDK peuvent réutiliser l’assistant postgresTextIssue, sûr pour le navigateur, depuis @scrydon/common/postgres-text ; il renvoie null pour un texte accepté et une description du problème dans le cas contraire. Il ne normalise ni ne modifie le texte fourni.

AppActionInputSchema et AppActionResultSchema décrivent le contrat privé du plan de contrôle. KernelClient.apps.submitAction et actionResult sont réservés à Analytics lorsqu’il transmet un lecteur authentifié ; ce ne sont pas des API de notebook ni de navigateur. Le résultat ne contient que unknown, committed avec un identifiant d’action, ou rejected avec un code du noyau. La réconciliation est en lecture seule : un délai dépassé ou un résultat unknown ne doit jamais déclencher de nouvelle soumission automatique. Les commandes privées de session de lecteur conservent chaque requête avant une tentative de soumission ; répéter cette requête ne fait que réconcilier son résultat. Au plus 256 requêtes d’action sont conservées par session de lecteur, et atteindre cette limite renvoie 429 sans effacer les requêtes précédentes. Les contrôles apps.action et apps.alerts du notebook utilisent le parcours de confirmation de confiance d’Horizon. Pour les détections de surveillance, utilisez le comportement d’accusé de réception afin d’enregistrer l’opérateur authentifié et l’heure sans remplacer les preuves de détection.

Les sélecteurs d’audience sont workspace ou users avec une liste explicite d’identifiants d’utilisateur. Des sélecteurs discover et run distincts décrivent l’accès prévu au sein du tenant de l’application. Aucun des deux n’accorde d’autorisations sur les données ou actions sous-jacentes.

Les références d’artefact contiennent sha256 et sizeBytes. Les emplacements de stockage sont déduits par la plateforme plutôt que fournis sous forme d’URL arbitraires. Les artefacts de source sont limités à 1 Mio ; les artefacts de dépendances à 512 Mio. Chaque permis prend en charge jusqu’à 32 dépendances d’ontologie et 64 déclarations par catégorie de requête, lien, action ou surveillance. Les requêtes ont des limites de résultats explicites d’au plus 10 000 objets.

Les manifestes de révision d’ontologie transportent les définitions d’application dans le compartiment facultatif apps et les surveillances dans watches. Les anciens manifestes omettent ces champs ; les appelants doivent lire un compartiment omis comme une liste vide, sans ajouter de champs au document stocké ni recalculer son hachage.