seal

Vue d’ensemble

seal est l’outil universel pour les artefacts git : commit, PR mergée, tag, release, snapshot complet du repo, ou ticket Jira. Idempotent — re-sceller le même artefact ne crée pas de doublon.

Le flux : récupération de l’artefact depuis la forge (GitHub / GitLab / Forgejo) → calcul SHA-512 sur le contenu canonique → insertion ledger → scellement IP Secure (si configuré).

Note

Pour sceller du texte brut, utilisez seal_content. Pour un fichier sur disque, seal_file.

Paramètres

project string requis

ID du projet configuré dans SESHAT.

type string requis

Type d’artefact à sceller.

Type	Description	Cas d’usage
commit	Commit git spécifique	Rare en standalone — préférer pr
pr	Pull request mergée	Le plus courant pour le flux dev
tag	Tag git (version)	Releases formelles
release	Release GitHub / GitLab	Avec notes de release
repo	Snapshot complet du repo à un ref	Dépôt légal d’un état complet
jira_issue	Ticket Jira (avec worklogs)	Effort R&D par issue

ref string requis

Référence à l’artefact.

Type	Format du ref	Exemple
commit	SHA	abc1234
pr	Numéro de PR	42
tag	Nom du tag	v1.0.0
release	Tag de release	v1.0.0
repo	Ref git (tag, branche, SHA)	v1.0.0
jira_issue	Issue key	SES-42

asset_types string[]

Type(s) d’actif IP. Plusieurs valeurs possibles.

Type	Description
logiciel	Code source (défaut pour PR/commit/tag)
base_donnees	Base de données
programme_rnd	Programme R&D
savoir_faire	Secret industriel
brevet	Invention brevetée
dessin_modele	Design industriel

Astuce

Si le projet a default_asset_types configuré, il est utilisé automatiquement quand asset_types n’est pas fourni.

objective string

Objectif R&D pour la traçabilité CIR. Exemple : "Optimisation latence inférence LLM sous 50ms".

Un bon objectif identifie une incertitude technique et un avancement visé — ce sont les deux critères CIR.

dry_run boolean

Mode preview. Défaut : true quand IP Secure est lié au projet, false sinon.

Quand true, retourne un preview avec le fingerprint prévu, sans rien persister ni signer.

Attention

Sceller un certificat eIDAS est irréversible. Le certificat fige title/description/asset_types au moment où dry_run: false est exécuté. Le ledger SESHAT reste éditable (via annotate), mais pas le certificat. Toujours présenter le preview à l’utilisateur et attendre une confirmation explicite.

Réponse

{
  "type": "pr",
  "reference": "pr:42",
  "description": "PR #42: Add MCP transport",
  "fingerprint": "sha512:def456...",
  "timestamp": "2026-05-27T10:30:00Z",
  "asset_types": ["logiciel"],
  "objective": null,
  "dry_run": false,
  "ipsecure_contribution_id": "mwMWTpjmu3",
  "ipsecure_certificate_url": null,
  "ipsecure_setup_hint": null
}

reference string

Préfixée par le type : commit:, pr:, tag:, release:, jira:, etc. Permet de filtrer le ledger : /odata/ledger?$filter=startswith(reference, 'pr:').

ipsecure_certificate_url string | null

Souvent null à la réponse immédiate — Jinnove génère le certificat de manière asynchrone. Récupérer plus tard avec fetch_certificate.

Types détaillés

Pull Request (le plus courant)

Scelle la PR 42 pour mon projet

Inclut :

• SHA du commit de merge
• Tree hash au point de merge
• Titre et description de la PR
• Auteurs (author + merger)
• Timestamp du merge

Attention

La PR doit être mergée. Tenter de sceller une PR ouverte échoue avec pr_not_merged.

Astuce

Auto-seal webhook : si le projet utilise une GitHub App SESHAT, les PRs mergées sont scellées automatiquement à la réception du webhook pull_request.closed+merged. Vérifier avec status si une PR est déjà scellée avant un appel manuel.

Tag

Scelle le tag v1.4.2 pour mon projet

Idéal pour marquer un point stable de la base de code. Le sceau prouve :

• L’état exact du code à ce tag
• Le timestamp du tag
• Le contenu complet (via tree hash)

Release

Comme tag, mais inclut en plus :

• Les notes de release
• Les assets attachés (binaires, sources)
• Le timestamp de publication

Repo (snapshot complet)

Scelle un snapshot complet du repo à v1.4.2

Génère un hash de l’arbre git complet à un ref donné. Utile pour les dépôts légaux APP / INPI : on prouve l’état exact de TOUT le repo à un instant.

Jira issue

Scelle l'issue SES-42 (qui a 12h de worklogs)

Sceau d’une issue avec son contenu canonique (summary, status, reporter, worklogs triés). L’effort en heures provient des worklogs Jira.

Note

La re-vérifiabilité des seals jira:* est limitée — si l’issue change côté Jira après le seal, on ne peut plus recalculer le hash. Le snapshot canonique côté SESHAT est suivi dans #420.

Workflow recommandés

Après merge d’une PR

1. Vérifier l’état auto-seal

   status verbose

   Si la PR a été auto-scellée via webhook, inutile de la sceller à nouveau.

2. Sceller manuellement si besoin

   Scelle la PR 42

3. Tisser les liens du faisceau d’indices

   Cette PR implémente l'issue Jira SES-42 — lie-les

   Voir link_proofs.

Préparer une release

1. Créer le tag git

   git tag v1.4.2
   git push origin v1.4.2
   git push bunker v1.4.2

2. Sceller le tag

   Scelle le tag v1.4.2

3. Générer le bundle légal

   Génère le bundle légal pour le tag v1.4.2

   Voir bundle_release.

Gestion d’erreurs

Erreur	Cause	Solution
pr_not_merged	Tentative de sceller une PR ouverte	Attendre le merge
already_sealed	Sceau dupliqué (fingerprint identique)	Safe — la fonction est idempotente, c’est juste un no-op informatif
git_host_not_configured	Credentials forge manquants	Voir Configuration
ref_not_found	Référence invalide	Vérifier l’existence du commit/tag/PR
project_not_configured	Champs projet manquants	L’outil renvoie un guide structuré pour configure(action:"update_project")

Recommandations agent

L’agent doit proactivement proposer un sceau quand :

L’utilisateur dit…	L’agent doit…
”Je viens de merger une PR”	Vérifier auto-seal, sinon seal(type:"pr")
”Feature terminée”	Proposer seal(type:"pr") puis éventuellement un tag
”Time pour une release”	Proposer tag → seal → bundle_release
”On a atteint la milestone X”	Proposer création + sceau d’un tag

Astuce

Bonne pratique : sceller chaque PR mergée pour une chaîne de preuves continue et vérifiable. C’est le bloc de base du faisceau d’indices.

Voir aussi

• seal_content — sceller du texte
• seal_file — sceller un fichier
• bundle_release — package légal d’une release
• fetch_certificate — récupérer l’URL eIDAS async
• link_proofs — tisser les relations entre preuves
• Concepts → Chaîne de preuves — modèle du faisceau d’indices