@hostwebhook/node-sdk 0.1.0

package/dist/node-lifecycle.js

@@ -0,0 +1,782 @@
+"use strict";
+/**
+ * Unified Node Lifecycle — single dispatch function for all 3 execution paths.
+ *
+ * Each node type registers a NodeHandler. dispatchSingleNode() runs the
+ * standard lifecycle: fetch → validate → filter → execute → save → delivery → telemetry → downstream.
+ * Only the execute step is node-specific.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerNodeHandler = registerNodeHandler;
+exports.getNodeHandler = getNodeHandler;
+exports.getTelemetrySource = getTelemetrySource;
+exports.mensajeDeFallo = mensajeDeFallo;
+exports.veredictoDelDespacho = veredictoDelDespacho;
+exports.veredictoDeResultado = veredictoDeResultado;
+exports.conPasoRegistrado = conPasoRegistrado;
+exports.dispatchSingleNode = dispatchSingleNode;
+const mongoose_1 = require("mongoose");
+const common_1 = require("@nestjs/common");
+const filter_utils_1 = require("./filter-utils");
+const workspace_payloads_1 = require("./workspace-payloads");
+const pipeline_constants_1 = require("./pipeline.constants");
+const log_metadata_1 = require("./log-metadata");
+const node_dispatch_registry_1 = require("./node-dispatch.registry");
+const node_executors_1 = require("./node-executors");
+const output_webhook_scope_1 = require("./output-webhook-scope");
+const node_types_1 = require("@hostwebhook/node-types");
+const swallow_1 = require("./swallow");
+const logger = new common_1.Logger('NodeLifecycle');
+// ─── Handler registry ────────────────────────────────────────────
+const handlers = new Map();
+/**
+ * La clave del registro. Sin versión es el tipo pelado, que es como se ha
+ * llamado siempre; con versión lleva sufijo.
+ *
+ * Que la clave sea una cadena es lo que hace barato el versionado: no hubo
+ * que cambiar la estructura, sólo cómo se nombra lo que va dentro.
+ */
+const claveDeHandler = (nodeType, version) => version == null ? nodeType : `${nodeType}@${version}`;
+function registerNodeHandler(handler) {
+    handlers.set(claveDeHandler(handler.nodeType, handler.version), handler);
+    /* El handler de la versión vigente responde TAMBIÉN a la clave pelada.
+       Sin esto, versionar un tipo dejaría ciegos de golpe a los llamantes
+       que preguntan sin versión —los de MCP, sobre todo— y el síntoma sería
+       un toolkit que desaparece, no un error. */
+    if (handler.version == null ||
+        handler.version === (0, node_types_1.currentVersion)(handler.nodeType))
+        handlers.set(handler.nodeType, handler);
+}
+/**
+ * El handler de un tipo, opcionalmente el de una versión concreta.
+ *
+ * Sin `version` devuelve el de la versión vigente, que es exactamente lo
+ * que hacía antes de que existieran las versiones. Con una versión que
+ * nadie registró cae al vigente en vez de devolver nada: un nodo apuntando
+ * a una versión que ya se retiró debe seguir corriendo, no dejar de
+ * dispararse en silencio.
+ */
+function getNodeHandler(nodeType, version) {
+    return (handlers.get(claveDeHandler(nodeType, version)) ?? handlers.get(nodeType));
+}
+/**
+ * Telemetry log source for a node type.
+ *
+ * This used to be a 33-entry `NODE_TYPE_TO_SOURCE` map maintained by hand in
+ * pipeline-run.service.ts — a fourth place to remember when adding a node,
+ * and one that had already grown duplicate aliases (`approval` /
+ * `approvalNode`, `delay` / `delayNode`, `merge` / `mergeNode`,
+ * `conditional` / `conditionalNode`) because nobody could tell which key the
+ * callers passed. Every handler already declares `telemetrySource`, so the
+ * map was a copy of information the registry owned.
+ *
+ * Types with no handler declare their source next to the reason they have no
+ * handler, in HANDLERLESS_NODE_TYPES. Anything else — the non-node sources
+ * the pipeline logs under, like 'delivery', 'replay' and 'chain' — passes
+ * through as-is, which is what the old map's `?? nodeType` fallback did.
+ */
+function getTelemetrySource(nodeType) {
+    const registered = handlers.get(nodeType)?.telemetrySource;
+    if (registered)
+        return registered;
+    if ((0, node_executors_1.isHandlerless)(nodeType))
+        return node_executors_1.HANDLERLESS_NODE_TYPES[nodeType].telemetrySource;
+    return nodeType;
+}
+// ─── Default implementations ─────────────────────────────────────
+function defaultPreFilter(entity, payload, wsPayloads) {
+    const filters = entity.filters ?? [];
+    const opts = wsPayloads ? { workspacePayloads: wsPayloads } : undefined;
+    if (filters.length > 0 && !(0, filter_utils_1.evaluateFilters)(filters, payload, 'and', opts)) {
+        return 'filtered out';
+    }
+    return null;
+}
+function defaultBuildLastPayload(_entity, _result, outputPayload) {
+    if (outputPayload._meta)
+        return outputPayload;
+    return { _meta: { iterable: false, count: 1 }, ...outputPayload };
+}
+/**
+ * Cuánto del mensaje de error cabe en un paso.
+ *
+ * Se enseña bajo el nombre del nodo en la línea de tiempo, así que tiene que
+ * caber en una o dos líneas. El cuerpo entero ya está en `run_payloads`, que
+ * es donde se va a mirar de verdad; esto es el titular.
+ */
+const TOPE_DEL_ERROR = 500;
+/**
+ * Saca del resultado la frase que explica el fallo.
+ *
+ * Los handlers devuelven el cuerpo como texto, y casi siempre es un JSON con
+ * `error` dentro — una frase ya escrita para leerse. Enseñar el JSON crudo en
+ * la línea de tiempo es enseñar llaves y comillas donde cabía la explicación.
+ * Si no es JSON, o no trae `error`, se enseña el cuerpo recortado; y si no hay
+ * cuerpo, el código HTTP, que al menos dice algo.
+ */
+function mensajeDeFallo(result) {
+    if (!result)
+        return 'el nodo falló sin devolver resultado';
+    const cuerpo = result.responseBody?.trim();
+    if (!cuerpo)
+        return `HTTP ${result.statusCode}`;
+    let frase;
+    try {
+        const json = JSON.parse(cuerpo);
+        const candidata = json?.error ?? json?.message;
+        frase = typeof candidata === 'string' ? candidata : undefined;
+    }
+    catch {
+        /* No era JSON. Se enseña el cuerpo tal cual, que para eso está abajo. */
+        frase = undefined;
+    }
+    return (frase && frase.length > 0 ? frase : cuerpo).slice(0, TOPE_DEL_ERROR);
+}
+/**
+ * Cómo le fue al paso, a partir de lo que devolvió el despacho.
+ *
+ * ⚠️ El veredicto sale del `statusCode`, NO de si el nodo llegó a correr. Eso
+ * era el bug: `anotar(r.executed ? 'success' : 'skipped')` daba `success` a
+ * todo nodo que corriera, devolviese lo que devolviese. Un Email Action que
+ * lleva cinco días contestando 500 tenía cinco corridas en verde, con el
+ * `{"statusCode":500}` guardado dentro de su propio payload. La telemetría de
+ * este mismo fichero ya lo miraba bien (`result.statusCode < 400`): eran dos
+ * criterios distintos sobre el mismo resultado.
+ *
+ * Los tres estados, y por qué son tres y no dos:
+ *
+ * - `failed`  — corrió y salió mal, o reventó. Es lo que cuenta `failures` y
+ *               lo que hace que la corrida entera sea `failed` o `partial`.
+ * - `skipped` — no llegó a correr: inactivo, filtrado, sin handler. Un paso
+ *               que no existe y uno que se saltó no se leen igual.
+ * - `success` — corrió y salió bien.
+ */
+function veredictoDelDespacho(r) {
+    /* El fallo explícito manda sobre todo lo demás: `ejecutarNodo` devuelve
+       `executed: false` tanto cuando el nodo explotó como cuando nadie lo
+       llamó, y sólo este campo los separa. */
+    if (r.error !== undefined) {
+        return { status: 'failed', salida: r.result, error: r.error };
+    }
+    if (!r.executed)
+        return { status: 'skipped', salida: r.result };
+    return veredictoDeResultado(r.result);
+}
+/**
+ * El veredicto de un nodo que SÍ corrió, sacado de lo que devolvió.
+ *
+ * Aparte de `veredictoDelDespacho` porque las rutas que no pasan por el
+ * pipeline —el Chat Trigger, los tools del nodo AI, los de MCP— no tienen un
+ * `DispatchResult`: tienen el `NodeExecutionResult` a secas. El criterio de
+ * qué es un fallo tiene que ser UNO, o vuelven a ser dos.
+ *
+ * Sin `statusCode` numérico se da por bueno a propósito: un handler que no lo
+ * declara no está diciendo que falló, y pintar de rojo lo que no se sabe es
+ * peor que dejarlo verde — el rojo se mira.
+ */
+function veredictoDeResultado(result) {
+    const statusCode = result?.statusCode;
+    if (typeof statusCode === 'number' && statusCode >= 400) {
+        return { status: 'failed', salida: result, error: mensajeDeFallo(result) };
+    }
+    return { status: 'success', salida: result };
+}
+/**
+ * Corre algo y lo deja escrito en el historial como un paso.
+ *
+ * Es una envoltura, y no un puñado de llamadas repartidas por dentro, a
+ * propósito: `ejecutarNodo` tiene seis salidas —no hay handler, no se pudo
+ * traer la entidad, está inactiva, la filtró el pre-filtro, reventó, salió
+ * bien— y anotar el paso en cada una es la clase de lista que se olvida en la
+ * séptima. Desde fuera se ven todas a la vez, con su duración de verdad.
+ *
+ * Vive fuera de `dispatchSingleNode` porque el pipeline de producción NO es la
+ * única forma de ejecutar un nodo. El Chat Trigger, los tools del nodo AI, los
+ * de MCP, Run Pipeline y Run Test llegan al nodo por su cuenta, y sin una
+ * función a la que llamar cada uno tendría que copiar este bloque — que es
+ * como se llega a seis copias que se desincronizan.
+ *
+ * `ficha` se lee DESPUÉS de correr, no antes: `correr` puede rellenarle el
+ * `nodeName` y el `workspaceId` en cuanto cargue la entidad. Son opcionales en
+ * `PasoEjecutado`, así que olvidarlos no rompe nada y sólo se nota en pantalla
+ * —sin `nodeName` la línea de tiempo enseña el tipo dos veces; sin
+ * `workspaceId` la corrida sale sin foto y diciendo que es anterior al sellado
+ * de versiones—.
+ *
+ * Nunca estorba: si no hay `historial` en el contexto —tests, modos que no lo
+ * montan— esto es una llamada directa y ya está.
+ */
+async function conPasoRegistrado(ctx, ficha, correr, veredicto) {
+    if (!ctx.historial)
+        return correr();
+    const empezado = new Date();
+    const anotar = (v) => ctx.historial?.registrarPaso({
+        organizationId: ctx.orgId,
+        correlationId: ctx.event.correlationId ?? ctx.event.id,
+        nodeId: ficha.nodeId,
+        nodeName: ficha.nodeName,
+        workspaceId: ficha.workspaceId,
+        nodeType: ficha.nodeType,
+        status: v.status,
+        startedAt: empezado,
+        durationMs: Date.now() - empezado.getTime(),
+        error: v.error,
+        sourceId: ctx.webhook.id,
+        sourceName: ctx.webhook.name,
+        entrada: ficha.entrada,
+        salida: v.salida,
+        modo: ctx.modoDeCorrida,
+    });
+    try {
+        const r = await correr();
+        anotar(veredicto(r));
+        return r;
+    }
+    catch (err) {
+        /* Que `correr` lance es la vía rara —`ejecutarNodo` captura lo suyo y
+           devuelve `error`—, pero los llamadores de fuera del pipeline sí lanzan,
+           y un paso que se pierde por reventar es justo el que hacía falta ver. */
+        anotar({
+            status: 'failed',
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+/**
+ * Ejecuta un nodo y, de paso, lo deja escrito en el historial.
+ *
+ * El payload de entrada es un argumento, así que entra gratis. El de salida y
+ * el veredicto salen del resultado, en `veredictoDelDespacho`.
+ */
+async function dispatchSingleNode(nodeType, id, payload, ctx) {
+    if (!ctx.historial)
+        return ejecutarNodo(nodeType, id, payload, ctx);
+    /* La misma ficha viaja a `ejecutarNodo`, que le pone el nombre y el
+       workspace en cuanto carga la entidad, y a la envoltura, que los lee al
+       anotar. Un solo objeto: si se copiara, lo rellenado se perdería. */
+    const ficha = { nodeType, nodeId: id, entrada: payload };
+    return conPasoRegistrado(ctx, ficha, () => ejecutarNodo(nodeType, id, payload, ctx, ficha), veredictoDelDespacho);
+}
+async function ejecutarNodo(nodeType, id, payload, ctx, 
+/** Se rellena en cuanto la entidad está cargada. Ver `FichaDelNodo`. */
+ficha) {
+    const handler = handlers.get(nodeType);
+    if (!handler)
+        return { executed: false };
+    // 1. FETCH
+    let entity;
+    try {
+        entity = await handler.fetchEntity(id, ctx.orgId);
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        ctx.telemetry?.emit({
+            organizationId: ctx.orgId,
+            level: 'error',
+            source: handler.telemetrySource,
+            message: `Failed to fetch ${nodeType} ${id}: ${errorMsg}`,
+            eventId: ctx.event.id,
+            /* La corrida a la que pertenece la fila, con el mismo bautizo que usa
+               el pipeline en todas partes: la del evento raíz. Va en LAS SIETE
+               emisiones de este fichero, no sólo en la del final — una corrida a
+               la que le faltan sus filas de error es peor que no tenerla.
+               `architecture.spec.ts` exige que la próxima también lo lleve. */
+            correlationId: ctx.event.correlationId ?? ctx.event.id,
+            webhookId: ctx.webhook.id,
+            webhookName: ctx.webhook.name,
+            nodeId: id,
+        });
+        /* No poder traer la entidad es un FALLO, no un salto: la base no
+           contestó, o contestó mal. Sin el `error` el historial lo guardaba como
+           `skipped`, indistinguible de un nodo apagado a propósito. */
+        return { executed: false, error: `no se pudo traer el nodo: ${errorMsg}` };
+    }
+    /* Antes de validar, no después: un nodo inactivo también se graba —como
+       `skipped`— y sin esto ese paso salía sin nombre ni workspace. Y es un paso
+       que se mira precisamente para entender por qué NO pasó nada. */
+    if (ficha && entity) {
+        ficha.nodeName = entity.name ?? id;
+        ficha.workspaceId = entity.workspaceId?.toString();
+    }
+    // 2. VALIDATE
+    if (!entity || !entity.isActive) {
+        ctx.telemetry?.emit({
+            organizationId: ctx.orgId,
+            level: 'warn',
+            source: handler.telemetrySource,
+            message: `${nodeType} ${id} ${!entity ? 'not found' : 'not active'} — skipped`,
+            eventId: ctx.event.id,
+            correlationId: ctx.event.correlationId ?? ctx.event.id,
+            webhookId: ctx.webhook.id,
+            webhookName: ctx.webhook.name,
+            nodeId: id,
+            metadata: { nodeId: id },
+        });
+        return { executed: false };
+    }
+    const nodeName = entity.name ?? id;
+    // 2b. LOAD WORKSPACE PAYLOADS — only for nodes that use $() cross-node refs
+    (0, workspace_payloads_1.initPayloadRedis)();
+    const crossNodeRefs = (0, workspace_payloads_1.extractCrossNodeRefs)(entity);
+    if (entity.workspaceId && crossNodeRefs.size > 0) {
+        try {
+            // Always load fresh for nodes with $() refs — don't reuse from ctx
+            const db = ctx.eventModel?.db?.db;
+            if (db) {
+                const wsPayloads = await (0, workspace_payloads_1.loadWorkspacePayloads)(db, entity.workspaceId.toString(), ctx.orgId, crossNodeRefs);
+                // In-memory overrides take priority (e.g. loop iteration payload)
+                if (ctx.wsPayloadOverrides)
+                    Object.assign(wsPayloads, ctx.wsPayloadOverrides);
+                ctx.executorContext = {
+                    ...ctx.executorContext,
+                    workspacePayloads: wsPayloads,
+                };
+            }
+        }
+        catch (err) {
+            logger.warn(`Failed to load workspace payloads for ${nodeType} ${id}: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    else if (ctx.wsPayloadOverrides &&
+        Object.keys(ctx.wsPayloadOverrides).length > 0) {
+        // No $() refs in entity but overrides exist — still inject them
+        ctx.executorContext = {
+            ...ctx.executorContext,
+            workspacePayloads: {
+                ...(ctx.executorContext?.workspacePayloads ?? {}),
+                ...ctx.wsPayloadOverrides,
+            },
+        };
+    }
+    // 3. PRE-FILTER
+    const filterFn = handler.preFilter ?? defaultPreFilter;
+    const filterReason = filterFn(entity, payload, ctx.executorContext?.workspacePayloads);
+    if (filterReason) {
+        ctx.telemetry?.emit({
+            organizationId: ctx.orgId,
+            level: 'info',
+            source: handler.telemetrySource,
+            message: `${nodeType} "${nodeName}" ${filterReason} — skipped`,
+            eventId: ctx.event.id,
+            correlationId: ctx.event.correlationId ?? ctx.event.id,
+            webhookId: ctx.webhook.id,
+            webhookName: ctx.webhook.name,
+            nodeId: id,
+            nodeName,
+        });
+        return { executed: false };
+    }
+    // 3.5 CHECKPOINT — save BEFORE execute so crash during execute can resume this node
+    if (ctx.loopStateId && ctx.updateLoopCheckpoint) {
+        ctx
+            .updateLoopCheckpoint(ctx.loopStateId, {
+            nodeType,
+            nodeId: id,
+            outputPayload: payload,
+        })
+            .catch((err) => logger.warn(`[LoopCheckpoint] Pre-exec failed: ${err?.message ?? err}`));
+    }
+    else if (ctx.eventModel && ctx.event?.id) {
+        ctx.eventModel
+            .updateOne({ _id: ctx.event.id }, {
+            $set: {
+                pipelineCheckpoint: {
+                    nodeType,
+                    nodeId: id,
+                    outputPayload: payload,
+                    depth: ctx.depth,
+                    updatedAt: new Date(),
+                },
+            },
+        })
+            .catch((err) => logger.warn(`[PipelineCheckpoint] Pre-exec failed: ${err?.message ?? err}`));
+    }
+    // 4. EXECUTE (with per-node timeout — AWS Step Functions pattern)
+    const timeoutSec = entity.timeoutSeconds ??
+        pipeline_constants_1.NODE_TIMEOUT_DEFAULTS[nodeType] ??
+        pipeline_constants_1.DEFAULT_NODE_TIMEOUT_SEC;
+    let result;
+    /* El temporizador se guarda para poder APAGARLO en el `finally`. Antes no se
+       limpiaba: la carrera la gana el nodo —el caso normal, en milisegundos— y
+       el `setTimeout` seguía vivo hasta cumplir su plazo, que por defecto son
+       decenas de segundos. O sea un temporizador colgando por CADA nodo
+       ejecutado, con su closure dentro, y bajo carga miles a la vez. Lo delató
+       un test: el worker de jest se negaba a cerrar. */
+    let reloj;
+    try {
+        result = await Promise.race([
+            handler.execute(entity, payload, ctx),
+            new Promise((_, reject) => {
+                reloj = setTimeout(() => reject(new Error(`Node timeout after ${timeoutSec}s`)), timeoutSec * 1000);
+            }),
+        ]);
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        const errorStack = err instanceof Error ? err.stack : undefined;
+        logger.error(`[Lifecycle] ${nodeType} "${nodeName}" FAILED: ${errorMsg}${errorStack ? `\n${errorStack}` : ''}`);
+        ctx.telemetry?.emit({
+            organizationId: ctx.orgId,
+            level: 'error',
+            source: handler.telemetrySource,
+            message: `${nodeType} "${nodeName}" FAILED: ${errorMsg}`,
+            eventId: ctx.event.id,
+            correlationId: ctx.event.correlationId ?? ctx.event.id,
+            webhookId: ctx.webhook.id,
+            webhookName: ctx.webhook.name,
+            nodeId: id,
+            nodeName,
+            metadata: { error: errorMsg },
+        });
+        // Notify loop handler if inside a loop iteration
+        if (ctx.loopStateId && ctx.onLoopIterationError) {
+            await ctx
+                .onLoopIterationError(ctx.loopStateId, errorMsg, false)
+                .catch((e) => logger.warn(`[Lifecycle] onLoopIterationError failed: ${e?.message ?? e}`));
+        }
+        /* El nodo reventó o se le acabó el tiempo. Este `catch` se traga la
+           excepción y devuelve `executed: false`, así que el `try/catch` de la
+           envoltura NO se entera: el fallo tiene que viajar en el resultado o el
+           historial lo guarda como `skipped`. */
+        return { executed: false, error: errorMsg };
+    }
+    finally {
+        /* Gane quien gane la carrera. También en el camino del error: un nodo que
+           revienta a los 20 ms no tiene por qué dejar su reloj andando. */
+        if (reloj)
+            clearTimeout(reloj);
+    }
+    const success = result.statusCode < 400;
+    // ── Node Circuit Breaker — auto-pause after consecutive failures ──
+    if (ctx.mode === 'prod') {
+        const redis = (0, workspace_payloads_1.getPayloadRedis)();
+        if (redis) {
+            const cbKey = `node:cb:${nodeType}:${id}`;
+            const MAX_CONSECUTIVE_FAILURES = 5;
+            const CB_TTL_SEC = 300; // 5 minutes — resets if node succeeds within window
+            if (success) {
+                redis
+                    .del(cbKey)
+                    .catch((0, swallow_1.onFailure)(logger, `circuit-breaker reset ${cbKey}`));
+            }
+            else {
+                redis
+                    .incr(cbKey)
+                    .then(async (count) => {
+                    if (count === 1)
+                        await redis.expire(cbKey, CB_TTL_SEC);
+                    if (count >= MAX_CONSECUTIVE_FAILURES) {
+                        logger.error(`[CircuitBreaker] ${nodeType} "${nodeName}" failed ${count} times in ${CB_TTL_SEC}s — auto-pausing`);
+                        ctx.telemetry?.emit({
+                            organizationId: ctx.orgId,
+                            level: 'error',
+                            source: handler.telemetrySource,
+                            message: `${nodeType} "${nodeName}" auto-paused after ${count} consecutive failures`,
+                            eventId: ctx.event.id,
+                            correlationId: ctx.event.correlationId ?? ctx.event.id,
+                            webhookId: ctx.webhook.id,
+                            webhookName: ctx.webhook.name,
+                            nodeId: id,
+                            nodeName,
+                            metadata: {
+                                consecutiveFailures: count,
+                                lastStatusCode: result.statusCode,
+                                lastError: result.responseBody?.slice(0, 200),
+                            },
+                        });
+                        // Auto-pause the node
+                        try {
+                            await handler
+                                .fetchEntity(id, ctx.orgId)
+                                .then(async (e) => {
+                                if (e?.save) {
+                                    e.isActive = false;
+                                    await e.save();
+                                }
+                            });
+                        }
+                        catch (err) {
+                            logger.warn(`[CircuitBreaker] Failed to auto-pause ${nodeType} ${id}: ${err.message}`);
+                        }
+                        await redis
+                            .del(cbKey)
+                            .catch((0, swallow_1.onFailure)(logger, `circuit-breaker clear ${cbKey}`));
+                    }
+                })
+                    .catch((0, swallow_1.onFailure)(logger, `circuit-breaker bookkeeping ${cbKey}`));
+            }
+        }
+    }
+    // If execution failed inside a loop, notify loop handler (skip/retry/stop)
+    if (!success && ctx.loopStateId && ctx.onLoopIterationError) {
+        const errorMsg = result.responseBody?.slice(0, 200) ?? `HTTP ${result.statusCode}`;
+        const retriedTransient = !!result?._retriedTransient;
+        await ctx
+            .onLoopIterationError(ctx.loopStateId, errorMsg, retriedTransient)
+            .catch((e) => logger.warn(`[Lifecycle] onLoopIterationError failed: ${e?.message ?? e}`));
+        /* Falló DENTRO de un loop. El `executed: false` es para que el pipeline no
+           siga aguas abajo —de eso se encarga la política del loop—, pero para el
+           historial es un fallo con todas las letras. Y el resultado viaja: es lo
+           que se mira para saber qué contestó. */
+        return { executed: false, result, error: mensajeDeFallo(result) };
+    }
+    // 5. GET OUTPUT PAYLOAD
+    const getOutput = handler.getOutputPayload ?? ((_e, r, inp) => r.outputPayload ?? inp);
+    const outputPayload = getOutput(entity, result, payload);
+    // 6. SAVE LAST PAYLOAD + EMIT REAL-TIME UPDATE
+    const buildLP = handler.buildLastPayload ?? defaultBuildLastPayload;
+    const lastPayload = buildLP(entity, result, outputPayload ?? {});
+    // Don't persist error responses as lastPayload — keeps last successful output on reload
+    // Schema validator always returns 200 (validity is in responseBody.valid), so this is safe
+    if (success) {
+        await handler
+            .saveLastPayload(id, lastPayload)
+            .catch((err) => logger.warn(`Failed to save lastPayload for ${nodeType} ${id}: ${err?.message ?? err}`));
+        // Warm Redis cache for $() cross-node lookups
+        if (entity.workspaceId && entity.name) {
+            (0, workspace_payloads_1.cacheNodePayload)(entity.workspaceId.toString(), entity.name, lastPayload);
+        }
+    }
+    if (ctx.gateway) {
+        // For schema validator: include specific valid/invalid payload fields for live updates
+        const extraPayloadFields = {};
+        if (handler.nodeType === 'schemaValidator' && lastPayload) {
+            const isInvalid = lastPayload?.error === 'Schema Validation Failed';
+            if (isInvalid) {
+                extraPayloadFields.lastInvalidPayload = lastPayload;
+            }
+            else {
+                extraPayloadFields.lastValidPayload = lastPayload;
+            }
+        }
+        ctx.gateway.emitPipelineStep(ctx.orgId, {
+            eventId: ctx.event?.id,
+            nodeType: handler.nodeType,
+            nodeId: id,
+            nodeName,
+            status: success ? 'success' : 'error',
+            statusCode: result.statusCode,
+            durationMs: result.latencyMs,
+            ...(success ? { lastPayload } : { error: result.responseBody }),
+            ...extraPayloadFields,
+        });
+        // Aviso aparte para la sección OUTPUT de la página de detalle. No sirve
+        // `pipeline:step` para esto: lo escucha quien sigue una corrida concreta,
+        // mientras que esto le interesa a cualquiera que tenga el nodo abierto,
+        // venga la ejecución de donde venga.
+        if (success && lastPayload != null) {
+            ctx.gateway.emitNodePayload(ctx.orgId, {
+                nodeType: handler.nodeType,
+                nodeId: id,
+                lastPayload,
+            });
+        }
+    }
+    // 7. DELIVERY (prod only)
+    if (ctx.mode === 'prod' && handler.buildDeliveryRecord && ctx.deliveryModel) {
+        const deliveryData = handler.buildDeliveryRecord(entity, result, success, ctx);
+        if (deliveryData) {
+            ctx.deliveryModel
+                .create(deliveryData)
+                .catch((err) => logger.warn(`Failed to create delivery record for ${nodeType} ${id}: ${err?.message ?? err}`));
+        }
+    }
+    // 8. TELEMETRY — handler override or unified format
+    if (handler.emitTelemetry) {
+        // Await the handler's emitter — when it returns a promise (e.g. it
+        // internally calls telemetry.emitAndWait for recovery safety), we
+        // need to actually wait for the Mongo write to land before
+        // declaring the node done. Sync handlers that return undefined
+        // resolve immediately and add no overhead.
+        await handler.emitTelemetry(entity, result, success, outputPayload, ctx, payload);
+    }
+    else {
+        const handlerMeta = handler.getTelemetryMetadata?.(entity, result) ?? {};
+        const entry = {
+            organizationId: ctx.orgId,
+            level: (success ? 'info' : 'error'),
+            source: handler.telemetrySource,
+            message: success
+                ? `${nodeType} "${nodeName}" executed (${result.latencyMs}ms)`
+                : `${nodeType} "${nodeName}" FAILED (${result.statusCode})`,
+            eventId: ctx.event.id,
+            correlationId: ctx.event.correlationId ?? ctx.event.id,
+            webhookId: ctx.webhook.id,
+            webhookName: ctx.webhook.name,
+            nodeId: id,
+            nodeName,
+            statusCode: result.statusCode,
+            durationMs: result.latencyMs,
+            success,
+            /* `payload` es lo que ENTRÓ a este nodo, y hasta hoy no se guardaba en
+               producción: un nodo que fallaba dejaba un log que decía qué salió
+               mal pero no con qué datos. Ver `log-metadata.ts`. */
+            metadata: (0, log_metadata_1.construirMetadatosDeLog)({
+                nodeType,
+                nodeName,
+                payload,
+                responseBody: result.responseBody,
+                statusCode: result.statusCode,
+                success,
+                extra: handlerMeta,
+            }),
+        };
+        // Expensive/non-idempotent nodes (AI / LLM) opt in to await the
+        // telemetry write — guarantees `hasRecentSuccess` will see the
+        // success on recovery, preventing a re-run that would double-charge
+        // the provider.
+        if (handler.awaitTelemetry && success && ctx.telemetry?.emitAndWait) {
+            await ctx.telemetry.emitAndWait(entry);
+        }
+        else {
+            ctx.telemetry?.emit(entry);
+        }
+    }
+    // 8.5 SYNC MODE — resolve ingress waiter if handler provides a sync result
+    if (handler.getSyncResult && ctx.gateway?.resolveSyncWaiter) {
+        const syncResult = handler.getSyncResult(entity, result, outputPayload, ctx);
+        if (syncResult) {
+            ctx.gateway.resolveSyncWaiter(ctx.event.id, syncResult);
+        }
+    }
+    // 8.55 — checkpoint was moved to step 3.5 (pre-execute) so crashes during execute are recoverable
+    // 8.6 LOOP-BACK SIGNAL (success or failure)
+    // If this node is a loop-back target, signal the loop immediately to advance.
+    // On failure: skip downstream, advance to next item.
+    // On success: after downstream dispatch completes, advance to next item.
+    // Read loopBackTargetId via raw DB query since Mongoose strict mode may not include it.
+    logger.debug(`[LoopBack] Check: nodeType=${nodeType} id=${id} hasHandleLoop=${!!ctx.handleLoopIteration} hasRawEvent=${!!ctx.rawEvent} hasRawWebhook=${!!ctx.rawWebhook}`);
+    if (ctx.handleLoopIteration && ctx.rawEvent && ctx.rawWebhook) {
+        try {
+            const dispatchConfig = (0, node_dispatch_registry_1.getNodeDispatchConfig)(nodeType);
+            logger.debug(`[LoopBack] dispatchConfig=${dispatchConfig?.collection ?? 'null'} hasEventModel=${!!ctx.eventModel} hasDb=${!!ctx.eventModel?.db?.db}`);
+            if (dispatchConfig) {
+                const db = ctx.eventModel?.db?.db;
+                if (db) {
+                    const rawDoc = await db
+                        .collection(dispatchConfig.collection)
+                        .findOne({ _id: new mongoose_1.Types.ObjectId(id) }, { projection: { loopBackTargetId: 1 } });
+                    logger.debug(`[LoopBack] rawDoc loopBackTargetId=${rawDoc?.loopBackTargetId ?? 'null'} for ${nodeType}:${id}`);
+                    if (rawDoc?.loopBackTargetId) {
+                        const loopDoc = await db
+                            .collection('loopnodes')
+                            .findOne({ _id: rawDoc.loopBackTargetId, isActive: true });
+                        if (loopDoc) {
+                            if (!success) {
+                                // Failed — send loop-back immediately (before downstream return)
+                                logger.log(`[LoopBack] Node "${nodeName}" failed — sending immediate loop-back to loop "${loopDoc.name}"`);
+                                await ctx.handleLoopIteration(ctx.rawEvent, ctx.rawWebhook, loopDoc, {}, ctx.rawCtx ?? { orgId: ctx.orgId }, ctx.depth);
+                            }
+                            else {
+                                // Success — defer loop-back until AFTER downstream dispatch (step 9)
+                                ctx._pendingLoopBack = {
+                                    loopDoc,
+                                    nodeName,
+                                    payload: outputPayload ?? payload,
+                                };
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(`[LoopBack] Failed to check loop-back: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // 9. DOWNSTREAM DISPATCH
+    if (!success && handler.propagateDownstream !== false) {
+        await sendPendingLoopBack(ctx, logger);
+        return { executed: true, result };
+    }
+    if (outputPayload === null) {
+        await sendPendingLoopBack(ctx, logger);
+        return { executed: true, result };
+    }
+    if (handler.propagateDownstream === false) {
+        await sendPendingLoopBack(ctx, logger);
+        return { executed: true, result };
+    }
+    const downstreamPayload = handler.downstreamPayload === 'original'
+        ? payload
+        : (outputPayload ?? payload);
+    const allOutputs = handler.getOutputNodes
+        ? handler.getOutputNodes(entity, result)
+        : (0, node_dispatch_registry_1.getAllOutputs)(entity);
+    logger.debug(`[Downstream] ${nodeType} "${nodeName}" → ${allOutputs.length} targets: ${JSON.stringify(allOutputs)}`);
+    if (allOutputs.length === 0) {
+        await sendPendingLoopBack(ctx, logger);
+        return { executed: true, result };
+    }
+    await dispatchDownstream(allOutputs, downstreamPayload, ctx);
+    // Cross-workspace dispatch — fires AFTER local downstream so the
+    // call-graph stays predictable: in-canvas children first, then any
+    // FlowLinks pointing out of this node. callStack lives on rawCtx so
+    // sync-mode chains propagate it; absence means "starting fresh".
+    if (ctx.dispatchFlowLinksFor) {
+        try {
+            await ctx.dispatchFlowLinksFor(nodeType, id, downstreamPayload, ctx.rawCtx?.callStack ?? []);
+        }
+        catch (err) {
+            logger.warn(`[FlowLink] dispatchFlowLinksFor ${nodeType}:${id} failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    await sendPendingLoopBack(ctx, logger);
+    return { executed: true, result };
+}
+/** Execute deferred loop-back signal if pending */
+async function sendPendingLoopBack(ctx, logger) {
+    const pendingLoopBack = ctx._pendingLoopBack;
+    if (!pendingLoopBack)
+        return;
+    try {
+        logger.log(`[LoopBack] Node "${pendingLoopBack.nodeName}" succeeded — sending loop-back to loop "${pendingLoopBack.loopDoc.name}"`);
+        await ctx.handleLoopIteration(ctx.rawEvent, ctx.rawWebhook, pendingLoopBack.loopDoc, pendingLoopBack.payload ?? {}, ctx.rawCtx ?? { orgId: ctx.orgId }, ctx.depth);
+    }
+    catch (err) {
+        logger.warn(`[LoopBack] Failed to send success loop-back: ${err instanceof Error ? err.message : err}`);
+    }
+}
+// ─── Downstream dispatch helper ──────────────────────────────────
+async function dispatchDownstream(outputs, payload, ctx) {
+    const webhookOutputs = outputs.filter((o) => o.nodeType === 'webhook');
+    const transformOutputs = outputs.filter((o) => o.nodeType === 'transform');
+    const pipelineOutputs = outputs.filter((o) => o.nodeType !== 'webhook' && o.nodeType !== 'transform');
+    // Webhook outputs: create child events
+    if (ctx.eventModel && ctx.webhookModel && ctx.onEventCreated) {
+        for (const out of webhookOutputs) {
+            const outEp = await ctx.webhookModel.findById(out.nodeId);
+            if (!outEp || !outEp.isActive || !(0, output_webhook_scope_1.belongsToOrg)(outEp, ctx.orgId))
+                continue;
+            const childEvent = await ctx.eventModel.create({
+                webhookId: out.nodeId,
+                payload,
+                rawBody: JSON.stringify(payload),
+                headers: ctx.event.headers ?? {},
+                sourceIp: ctx.event.sourceIp ?? '0.0.0.0',
+                status: 'pending',
+                eventType: ctx.event.eventType || 'pipeline',
+                correlationId: ctx.event.correlationId ?? ctx.event.id,
+            });
+            await ctx.onEventCreated(childEvent, outEp, {
+                ...ctx.rawCtx,
+                propagationDepth: ctx.depth + 1,
+            });
+        }
+    }
+    // Transform outputs — dispatch through unified lifecycle (same as all other nodes)
+    for (const out of transformOutputs) {
+        await dispatchSingleNode('transform', out.nodeId, payload, {
+            ...ctx,
+            depth: ctx.depth + 1,
+        });
+    }
+    // Pipeline outputs (other node types)
+    if (pipelineOutputs.length > 0 && ctx.dispatchOutputNodes) {
+        await ctx.dispatchOutputNodes(pipelineOutputs.map((o) => ({
+            nodeType: o.nodeType,
+            nodeId: new mongoose_1.Types.ObjectId(o.nodeId),
+        })), payload, ctx.rawEvent, ctx.rawWebhook, ctx.rawCtx, ctx.depth + 1);
+    }
+}