Definir Actions

Una Action es una operación ejecutable, atómica y auditada sobre los objetos. Es lo que un operador “hace” en Mentat. Se definen en /actions (UI, editor híbrido form + JSON) o por el template.

Anatomía de un ActionType

{
  "id": "cerrarTicket",
  "displayName": "Cerrar ticket",
  "affectedTypes": ["Ticket"],
  "parameters": [
    { "name": "ticket", "type": "reference", "referenceType": "Ticket", "required": true }
  ],
  "rules": [
    { "type": "modify", "targetType": "Ticket",
      "target": { "from": "parameter", "parameter": "ticket" },
      "changes": { "estado": { "from": "literal", "value": "cerrado" } } }
  ],
  "validations": [
    { "type": "permission", "roles": ["admin", "editor", "operator"] },
    { "type": "stateCheck", "config": {
        "target": { "from": "parameter", "parameter": "ticket" },
        "property": "estado", "operator": "neq", "value": "cerrado" } }
  ],
  "sideEffects": [],
  "permissions": { "roles": ["admin", "editor", "operator"] }
}

Parameters

Lo que el operador completa al ejecutar. Tipos: string, text, number, boolean, enum (con enumValues) y reference (con referenceType). El parámetro reference es como el operador elige el objeto target.

Rules — qué cambia

`type`	Qué hace	Campos
`modify`	cambia properties de un objeto	`target`, `changes`
`create`	crea un objeto nuevo	`values`
`delete`	soft-delete de un objeto	`target`

El valor de cada cambio es un ChangeSpec:

{ "from": "literal", "value": "cerrado" } — un valor fijo.
{ "from": "parameter", "parameter": "agente" } — lo que aportó el operador.

⚠️

Dos límites a tener presentes:

El target de un modify/delete sale siempre de un parámetro reference ({ "from": "parameter", … }). No hay target por query: una Action opera sobre el objeto que el operador elige, no sobre “todos los que cumplan X”.
Las changes aplican a properties, no a links. Para mutar una relación, modelala como property reference en la Ontología.

Validations — precondiciones

permission — qué roles pueden ejecutar (admin/editor/operator/viewer).
stateCheck — una condición sobre una property del target, evaluada dentro de la transacción (atómica). Operadores: eq, neq, in, notIn, gt, gte, lt, lte, exists, notExists.

Si una validation falla, la Action se rechaza y se persiste una ejecución failed auditada (no queda nada a medias).

Side effects — efectos best-effort

Corren después de aplicar el cambio (post-commit). Si fallan, el modelo ya se aplicó y la ejecución queda en estado partial:

notification — email vía Resend (to, subject, body con placeholders {{parametro}}). Ver Notificaciones.
webhook — POST/PUT a una URL con el payload de la ejecución.

Cómo se ejecuta (el motor)

Cuando un operador ejecuta una Action, el backend:

Carga el ActionType y verifica el rol del ejecutor.
Valida los parámetros contra las definiciones.
Abre una transacción atómica: evalúa los stateCheck, aplica las rules (con version++ y validación de schema), todo o nada.
Post-commit corre los side effects (best-effort).
Escribe el ActionExecution inmutable + el AuditEvent (domain: 'action') con el resultado final (success / partial / failed).

El resultado y el historial de ejecuciones se ven en el detalle de la Action y en el Dashboard. Cada ejecución es inmutable: es el audit log central de Mentat.

Forward-compat

Los tipos functionCall (validation) y audit (side effect) existen en el modelo pero no se aceptan todavía en el MVP — no se puede crear un ActionType con un comportamiento que el motor no ejecuta.

Modelar la Ontología Configurar DataSources