SDK du noyau d'ontologie

Utilisez createKernelClient depuis @scrydon/ontology-sdk/client dans les appelants côté serveur. Le client est limité à la requête : fournissez le transport admis de l'appelant ainsi que les en-têtes exacts de l'organisation, de l'espace de travail et de son environnement. Ne mettez jamais en cache les en-têtes d'un utilisateur, n'exposez pas les identifiants de service au navigateur et ne remplacez pas le tuple complet par une portée limitée à l'organisation.

import { createKernelClient } from "@scrydon/ontology-sdk/client";

const ontology = createKernelClient({
  baseUrl: `${ontologyServiceUrl}/api/ontology`,
  headers: () => ({
    ...admittedCallerHeaders(),
    "x-organization-id": organizationId,
    "x-workspace-id": workspaceId,
    "x-workspace-environment-id": workspaceEnvironmentId,
  }),
});

const result = await ontology.objects.query({
  ontology: "crm",
  objectTypes: ["Customer"],
  limit: 50,
});

Les lectures publiées résolvent la révision courante, sauf si vous fournissez un revisionId immuable ; les lectures de branche utilisent un apiName de branche. Les écritures passent par actions.submit avec un type d'action final tel que schema.declare, schema.publish, branch.submit ou proposal.approve. schema.declare et schema.publish modifient main directement et sont réservés aux administrateurs de l'organisation ; les autres appelants créent une branche (branch.create), la modifient (branch.declare) et la soumettent à révision (branch.submit) — voir Branches et propositions. Les erreurs sont des valeurs OntologyApiError avec un code stable généré, un httpStatus et des détails bornés. Une réponse non-2xx dépourvue d'enveloppe d'erreur du noyau — un 502 HTML renvoyé par un proxy, un 401 vide provenant du maillage — est elle aussi une OntologyApiError : son code est MALFORMED_ERROR_RESPONSE, httpStatus reprend le statut retourné et details contient le type de contenu de la réponse ainsi qu'un aperçu borné du corps.

Chaque ensemble renvoyé par objects.query indique matched, le nombre d'objets qu'il renvoie, et scanned, le nombre de lignes que le service a lues pour les trouver. Une source liée illisible fait échouer la requête avec SOURCE_READ_UNAVAILABLE ; le service ne répond jamais à partir du registre de l'ontologie à la place. Le résultat porte toujours sourceFallbackToLedger, que les serveurs actuels renvoient toujours à false : traitez true (venant d'un serveur plus ancien) comme des données du registre, jamais comme une preuve issue de la source. Un ensemble n'indique pas si le parcours d'une source liée s'est arrêté avant la fin de cette source. Ce signal reste interne au service, où l'évaluation des veilles s'en sert pour refuser de noter une veille sur une lecture partielle : le résultat de cette veille dans watches.evaluate porte alors une reason telle que incomplete-read au lieu d'une détection. Un ensemble court ou vide ne prouve donc pas que la source ne contient rien de plus ; affinez la requête avec filter ou objectTypes avant de le tenir pour définitif.

Découverte des applications

ontology.apps.list({ view: "for-me", search: "north sea", limit: 24 }) lit le catalogue actuel des applications publiées. Les vues for-me, all, extensions et mine appliquent toutes le public de découverte, l’habilitation et le périmètre du locataire. Passez nextName comme afterName pour continuer. La recherche est littérale et insensible à la casse ; la limite maximale est 50.

ontology.apps.get({ name: "north-sea" }) renvoie les mêmes métadonnées sûres pour une application visible. Ces méthodes ne renvoient ni source notebook, ni artefacts, permis, listes de publics ou anciennes versions. canRequestRun décrit le public d’exécution actuel et ne constitue aucune autorisation d’exécution ou d’accès aux données. Ces lectures exigent un utilisateur humain direct, éventuellement transmis par un service vérifié. Elles ne démarrent aucun calcul notebook.

ontology.apps.runRelease est réservé au plan de contrôle Analytics. Il résout les éléments immuables d’exécution selon l’accès actuel de l’opérateur à l’application ; son résultat privé reste côté serveur. Les clients SDK ordinaires et Horizon ne peuvent pas obtenir les artefacts notebook par cette méthode. Une référence de version n’accorde aucun accès au calcul ou aux données.

ontology.apps.previewQuery est une lecture privée du plan de contrôle Analytics pour un candidat non publié. Elle applique les permissions actuelles de l’auteur sur l’ontologie ainsi que les requêtes et liens déclarés du candidat. Elle ne publie rien et n’exécute aucune action ; fournir un candidat ne donne aucun droit d’accès aux données. Sa preuve privée de source doit rester côté serveur. Cette méthode seule ne démarre ni n’autorise un aperçu visuel ; les auteurs de notebooks ne doivent pas l’appeler directement. ontology.apps.previewWaitQueries fournit l’attente privée et bornée des changements de source. Une modification déclenche une nouvelle lecture sous la politique actuelle ; une preuve de source ou de politique différente exige un nouvel instantané. Les preuves physiques restent côté serveur ; Analytics remet au navigateur des curseurs opaques liés au cadre.

Les sous-chemins navigateur apps/session-controller, apps/session-frame et apps/widget-queries partagent l’expiration, le retrait du cadre opaque et l’ordonnancement des lectures entre l’aperçu Analytics et Horizon. Le transport doit vérifier l’autorisation courante côté serveur ; ces utilitaires n’accordent aucun droit. Les auteurs utilisent les composants Python et la commande d’aperçu.

ontology.apps.readResponse est également réservé à Analytics. Il reçoit la référence de version enregistrée, les identifiants déclarés de requête et de surveillance, ainsi qu’une référence qualifiée de détection. Il renvoie une association privée uniquement si la détection reste visible et son assertion de surveillance valide et lisible. Une association absente ou ambiguë donne response: null. Ce résultat n’autorise pas l’accès au processus : Horizon doit vérifier séparément le processus réel auprès d’Agentic avant de révéler son identifiant. Les auteurs de notebooks ne peuvent ni fournir une URL de réponse, ni appeler directement cette méthode du plan de contrôle.

Historique de publication et récupération

Les éditeurs autorisés peuvent consulter les résumés des versions avec ontology.apps.history({ name: "north-sea", limit: 25 }). La réponse distingue l’état courant current des versions conservées distinctes releases. Passez nextReleaseId comme beforeReleaseId pour obtenir la page suivante. Ces lectures exigent le droit de publication ; elles ne constituent pas le catalogue Horizon et ne révèlent ni emplacement des artefacts ni permis d’accès.

Si la réponse à une publication est perdue, le service de création Analytics peut appeler ontology.apps.publicationResult avec les UUID de préparation et de requête d’origine, l’empreinte du candidat, l’assertion de cycle de vie attendue et les notes de version. Le résultat committed prouve que cette requête a été validée, même si une version ultérieure ou un retrait est désormais courant. rejected ne contient qu’un code d’erreur sûr. unknown ne prouve pas un échec : la requête peut encore être en cours. La vérification n’effectue aucune écriture et ne renouvelle pas la preuve de validation. Conservez l’identité de la requête d’origine ; ne remplacez jamais une tentative au résultat incertain par une nouvelle publication.

Soumettez une action intégrée du noyau par sa constante plutôt que par une chaîne littérale : une faute de frappe échoue alors à la vérification de types plutôt qu'à la requête. KERNEL_ACTION_TYPE_NAMES (avec son type union KernelActionTypeName et le garde isKernelActionTypeName) est exporté par @scrydon/ontology-sdk/client ; le registre d'actions du noyau est indexé par ce même objet, et la liste générée ci-dessous en est extraite. Une SCHEMA_ACTION publiée ne peut pas réutiliser un nom intégré.

import { KERNEL_ACTION_TYPE_NAMES } from "@scrydon/ontology-sdk/client";

await ontology.actions.submit({
  actionType: KERNEL_ACTION_TYPE_NAMES.OBJECT_ASSERT,
  idempotencyKey,
  input: { objects: [/* ... */] },
});

Client namespaces

Built-in action types

• action.approval.approve
• action.approval.deny
• action.catalog.disable
• action.catalog.enable
• action.outbound.reconcile
• action.tasking.dispatch
• app.publish
• app.revalidate
• app.rollback
• app.withdraw
• branch.archive
• branch.create
• branch.declare
• branch.publish
• branch.rebase
• branch.submit
• object.assert
• object.retract
• operational.decision
• pack.record-install
• proposal.approve
• proposal.reject
• risk.assess
• schema.declare
• schema.publish
• watch.detect

Error contract

Décisions qui citent une détection

Toute décision opérationnelle prise dans un dossier ouvert par une détection de veille (verdict sur une carte, approbation, rejet) cite cette détection comme preuve dans le registre des décisions. La décision prend le marquage de la détection : une décision prise sur une détection restreinte est elle-même restreinte, et un lecteur habilité en dessous ne reçoit pas la ligne.

La citation est faite à la livraison de la décision, au nom de la personne qui a décidé. Les limites suivantes en découlent :

• Si cette personne ne peut pas lire la détection, la décision est tout de même enregistrée, sans la citation, donc au marquage de ce qu'elle cite par ailleurs.
• Si la détection n'a pas pu être lue parce que la lecture a échoué, la livraison est retentée au lieu d'être enregistrée sans citation. Un échec que réessayer ne corrige pas (jeton expiré, réponse illisible) est retenté un nombre borné de fois, puis mis en rebut avec une raison.
• Une décision citée à un marquage restreint ne peut être révisée que par quelqu'un d'habilité au moins à ce niveau. Un réviseur moins habilité est refusé (FORBIDDEN) et la décision d'origine reste en vigueur.
• Une décision qui cite déjà le nombre maximal d'objets ne peut pas citer en plus la détection. Elle est refusée et mise en rebut avec une raison, jamais enregistrée à un marquage inférieur.
• La détection est recherchée dans le dossier vivant au moment de la livraison. Si le dossier a été supprimé avant, la décision est enregistrée sans la citation.

Un dossier qu'aucune détection n'a ouvert reste inchangé.

decisions.citing répond à « quelles décisions ont été prises sur cette alerte ? » :

const page = await kernel.decisions.citing({
  objectType: "MaritimeDetection",
  objectId: detectionId,
  limit: 20,
});
// page.items : décision, justification, acteur, decidedAt, supersedes, marquage.
// Du plus récent au plus ancien. Suivez page.nextCursor tant que page.hasMore est vrai.

limit vaut 20 par défaut et au plus 100. Une décision qui en révise une autre nomme celle-ci dans son propre supersedes. Les décisions enregistrées avant ce changement ne citent aucune détection et ne sont pas renvoyées.

Règlement des réponses aux détections

Pour un worker autorisé, watches.dispatches.settle transmet l’eventId, l’attemptCount et le leaseOwner du lot réclamé. Un résultat delivered exige désormais l’instanceId réellement renvoyé par le moteur de flux : au maximum 256 caractères, sans NUL ni substitut Unicode isolé. Les résultats retry et dead_letter peuvent fournir une erreur bornée et doivent omettre instanceId. Une preuve de livraison absente ou invalide est refusée.

Le noyau enregistre l’association au flux dans la même transaction que la livraison. Un bail expiré, un compteur périmé ou un autre périmètre locataire ne peut pas régler l’obligation. L’association survit au nettoyage de la file mais n’accorde aucun accès au flux. Coordonnez les mises à jour du SDK, du dispatcher et du récepteur ; ne déclarez pas une livraison si un ancien composant refuse le nouveau contrat.

Agentic enregistre une seule réponse par locataire, ontologie et identité de détection. Les nouvelles tentatives renvoient la même instance après sa fin, son annulation ou sa suppression ; elles ne lancent pas une autre réponse. Changer la veille ou le modèle de réponse pour une identité déjà enregistrée est refusé. Un nouvel épisode exige une nouvelle identité de détection. L’identifiant renvoyé prouve le déclenchement, pas l’accès actuel au flux ni l’existence actuelle de l’instance.

Capacités absentes, pannes et le « pas encore » du noyau

Trois familles de rejets se ressemblent sur le fil et doivent être traitées différemment. Le SDK exporte un assistant par famille pour que les appelants ne redérivent jamais la règle depuis details.

Une liaison qui ne peut pas produire de lignes

bindingReadCapabilityReason(error) répond pourquoi une lecture de liaison ne peut pas renvoyer de page, ou null lorsque l'erreur est une vraie faute à présenter comme telle. Le verdict repose sur details.reasonCode — jamais sur la présence éventuelle d'un details.reason lisible par un humain :

BINDING_READ_REASON_CODES est l'objet constant exporté (KIND_NOT_GOVERNED, SOURCE_NOT_PROVISIONED) ; branchez dessus plutôt que sur le littéral, et utilisez isBindingReadReasonCode(value) pour restreindre un code arrivé en unknown. Une surface de graphe ou de liste doit se dégrader autour des deux premières lignes (afficher la liaison comme ignorée avec la raison) et ne rendre que la troisième comme une erreur.

Un 503 portant un details.reason mais aucun details.reasonCode est une panne, pas une lacune de capacité. Les versions précédentes classaient sur la présence de la phrase : tout 503 qui transportait par hasard un texte de diagnostic cessait d'être réessayé. Le code est le contrat ; la phrase n'est qu'une courtoisie pour la personne qui lit l'écran.

Attendre une projection

Le noyau est event-sourced : une écriture est acquittée quand sa ligne de registre est validée, et les lectures la voient une fois le projecteur à jour. Une lecture émise juste après une écriture peut donc répondre NOT_FOUND ou PROJECTION_LAGGING pour une ressource qui existe. isTransientProjectionError(error) est vrai exactement pour ces deux codes — l'ensemble est TRANSIENT_PROJECTION_ERROR_CODES — et c'est le seul prédicat sur lequel une attente bornée doit réessayer. REVISION_MISMATCH n'en fait délibérément pas partie : il signifie que la prémisse de l'appelant a changé, et relire avec la même prémisse est une boucle, pas une récupération.

import { isTransientProjectionError } from "@scrydon/ontology-sdk/client";

const deadline = Date.now() + 5_000;
for (;;) {
  try {
    return await ontology.branches.get({ ontology, branch });
  } catch (error) {
    if (!isTransientProjectionError(error) || Date.now() >= deadline) throw error;
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
}

Un lien dont les arêtes sont calculées, pas stockées

Dans graph.schema, un lien avec un join déclaré n'a pas de lignes d'arêtes stockées : ses arêtes sont jointes depuis les instances visibles au moment de la lecture. Un tel lien rapporte edgeCount: null avec reason: GRAPH_SCHEMA_LINK_REASONS.COMPUTED_FROM_DECLARED_JOIN, jamais edgeCount: 0 — un zéro se lirait comme « lié, mais aucune valeur de colonne ne correspond », ce qui appelle un autre remède. Le vocabulaire complet des raisons est GRAPH_SCHEMA_LINK_REASONS ; une lecture gouvernée en échec conserve SOURCE_COUNT_UNAVAILABLE.

Branchez sur les constantes publiées plutôt que sur les chaînes brutes — GRAPH_LINK_KIND pour le kind d'un lien (REFERENCE / PROXIMITY) et GRAPH_DIAGNOSTIC_STATUS pour le status d'un diagnostic de liaison (READY / NOT_READY / SKIPPED). Les deux sont exportées depuis @scrydon/ontology-sdk/client avec leurs types dérivés GraphLinkKind / GraphDiagnosticStatus, et le z.enum(...) du schéma de tranche de graphe lit lui-même dans ces constantes : un littéral retapé échoue au typage au lieu de désaccorder silencieusement une branche de votre interface.

GRAPH_LINK_KIND décrit un lien sur le fil. Utilisez LINK_TYPE_KINDS de @scrydon/sdk-authoring/ontologies quand vous discriminez un type de lien que vous avez rédigé dans un manifeste — les deux vocabulaires épellent aujourd'hui les mêmes mots et ne sont pas interchangeables.