Plans et Actions

En bref

Toute mutation significative dans Ontologie passe par un plan signe. Un plan est un descripteur d'intention : il declare ce qui va changer, qui l'a demande, et expire apres un delai lie au risque. Ce mecanisme garantit la tracabilite, la reversibilite et le controle humain.

Cycle de vie d'un plan

1. Dry-run — Simule l'action, retourne un plan signe avec les changements prevus
2. Verification — L'appelant (humain ou agent) inspecte le plan
3. Apply — Execute la mutation si le plan est valide et non expire
4. Audit — Chaque execution est tracee dans le journal d'audit

Dry-run (creer un plan)

SDK

const plan = await client.actions.dryRun('Contract.approve', {
  targetId: 'uuid-du-contrat',
  input: { approverNote: 'Valide par le directeur' },
});

console.log(plan.planId);       // Identifiant unique
console.log(plan.expiresAt);    // Date d'expiration
console.log(plan.risk);         // low | medium | high
console.log(plan.changes);      // Changements prevus

CLI

npx ontologie actions dry-run Contract.approve \
  --target uuid-du-contrat \
  --input '{"approverNote": "Valide"}'

Apply (executer le plan)

SDK

const result = await client.actions.apply(plan.planId, {
  confirmed: true,
  riskAcknowledged: true,
});

CLI

npx ontologie actions apply --plan-id plan_xxxxx --confirm

Securite des plans

Propriete	Description
Signature	Chaque plan est signe cryptographiquement (HMAC)
Expiration	TTL base sur le risque (low: 7j, medium: 24h, high: 1h)
Idempotence	Un plan ne peut etre applique qu'une seule fois
Actor binding	Seul le principal qui a cree le plan peut l'appliquer
Schema check	Le plan est invalide si le schema a change depuis le dry-run

Lister les actions disponibles

// Decouvrir les actions executables sur une entite
const actions = await client.actions.describe('Contract', {
  targetId: 'uuid-du-contrat',
});

// Retourne les actions disponibles avec leurs preconditions
for (const action of actions) {
  console.log(action.name, action.available, action.risk);
}

npx ontologie actions describe Contract --target uuid-du-contrat

Preconditions

Les actions declarent des conditions d'execution. Si une precondition n'est pas satisfaite, le dry-run retourne une erreur ACTION_PRECONDITION_FAILED :

{
  "ok": false,
  "error": {
    "code": "ACTION_PRECONDITION_FAILED",
    "message": "Precondition failed: status must equal 'draft'",
    "details": {
      "field": "status",
      "operator": "eq",
      "expected": "draft",
      "actual": "active"
    }
  }
}

Modes d'execution

Mode	Comportement
descriptive	Aucune mutation — retourne uniquement une description
plan_only	Genere un plan, necessite apply explicite
twin_apply	Execute sur le digital twin (reversible via undo)
human_handoff	Cree une tache pour validation humaine
workflow_handoff	Declenche un workflow automatise
external_commit	Commit vers un systeme externe (webhook)

Erreurs courantes

Code	Cause	Remediation
PLAN_EXPIRED	Plan expire (TTL depasse)	Refaire un dry-run
PLAN_ALREADY_APPLIED	Plan deja execute	Aucune — idempotent
PLAN_SCHEMA_MISMATCH	Schema modifie depuis le dry-run	Refaire un dry-run
PLAN_ACTOR_MISMATCH	Principal different du createur	Utiliser le meme principal
ACTION_PRECONDITION_FAILED	Condition non satisfaite	Verifier l'etat de l'entite

Voir aussi

• Schema DSL — Declarer les actions dans le schema
• Requetes — Interroger vos entites
• Erreurs — Reference complete des codes d'erreur
• Gouvernance — Controle d'acces et approbations