@hostwebhook/node-sdk 0.3.0 → 0.4.0

package/dist/base-node.service.js

@@ -0,0 +1,409 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseNodeService = void 0;
+const olvidar_la_colocacion_1 = require("./olvidar-la-colocacion");
+const common_1 = require("@nestjs/common");
+const mongoose_1 = require("mongoose");
+const cascade_cleanup_1 = require("./cascade-cleanup");
+const sync_connections_1 = require("./sync-connections");
+const normalize_nodes_1 = require("./normalize-nodes");
+const unique_name_1 = require("./unique-name");
+const dto_utils_1 = require("./dto-utils");
+const workspace_payloads_1 = require("./workspace-payloads");
+const limpiar_marcador_detach_1 = require("./limpiar-marcador-detach");
+const credential_references_1 = require("./credential-references");
+const swallow_1 = require("./swallow");
+const acceso_al_workspace_1 = require("./acceso-al-workspace");
+/**
+ * File-level logger so the diagnostic line in `saveLastPayload` doesn't
+ * require declaring `protected readonly logger` on the abstract class —
+ * which would collide with the `private readonly logger` already
+ * declared on ~22 subclasses (TS2415: stricter visibility on derived).
+ */
+const BASE_NODE_SAVE_PAYLOAD_LOGGER = new common_1.Logger('BaseNodeService.saveLastPayload');
+/** Mismo motivo de visibilidad que el de arriba: a nivel de módulo. */
+const BASE_NODE_STALE_PAYLOAD_LOGGER = new common_1.Logger('BaseNodeService.staleConnection');
+/**
+ * Base service for node entities (HTTP Actions, Transform Nodes, Filter Nodes, Sheets Actions, etc.).
+ * Provides standard CRUD, saveLastPayload, findActiveByInput, and connection validation.
+ *
+ * Subclasses must define:
+ * - `entityName`: human-readable name for error messages (e.g. 'HTTP action')
+ * - `cascadeNodeType`: type key for cascadeCleanupNodeReferences (e.g. 'httpAction')
+ */
+class BaseNodeService {
+    model;
+    connection;
+    constructor(model, connection) {
+        this.model = model;
+        this.connection = connection;
+    }
+    async findAll(orgId, workspaceId, visibles) {
+        const filter = {
+            organizationId: new mongoose_1.Types.ObjectId(orgId),
+        };
+        if (workspaceId)
+            filter.workspaceId = new mongoose_1.Types.ObjectId(workspaceId);
+        /* Sin `workspaceId` esto listaba TODOS los nodos de la organizacion,
+           incluidos los de workspaces restringidos. Es el mismo agujero que tenia
+           el lienzo y se arregla igual: `null` significa «no hay nada que
+           recortar» y entonces la consulta sale identica a antes; el `null` de la
+           lista deja pasar los nodos sin workspace, que no estan en ninguno
+           restringido. */ else if (visibles)
+            filter.workspaceId = { $in: [...visibles, null] };
+        return this.model.find(filter).sort({ createdAt: -1 });
+    }
+    async findOne(id, orgId) {
+        const doc = await this.model.findOne({
+            _id: new mongoose_1.Types.ObjectId(id),
+            organizationId: new mongoose_1.Types.ObjectId(orgId),
+        });
+        if (!doc)
+            throw new common_1.NotFoundException(`${this.entityName} not found`);
+        return doc;
+    }
+    /**
+     * Devuelve el `organizationId` del nodo, que ya se busca aquí dentro.
+     *
+     * Lo necesita quien quiera avisar por socket de que el payload cambió: sin
+     * esto tendría que repetir la misma consulta justo después. Los llamantes
+     * que no lo usen no se enteran — antes devolvía `void`.
+     */
+    async saveLastPayload(id, payload, 
+    /**
+     * De dónde sale este payload.
+     *
+     * `example: true` sólo cuando el usuario promueve una PLANTILLA desde el
+     * Test push: datos inventados, con la forma exacta que el nodo va a
+     * despachar, para poder montar el flujo antes del primer evento real.
+     *
+     * ⚠️ Va FUERA del payload a propósito. Meter la marca dentro cambiaría la
+     * forma —y el sprint entero fue sobre que la plantilla sea la forma
+     * EXACTA—, así que quien copiara `{{payload.x}}` desde ahí acabaría con
+     * una ruta que no existe en la entrega de verdad.
+     */
+    meta) {
+        if (payload == null)
+            return undefined;
+        const entity = (await this.model
+            .findById(id, { organizationId: 1, workspaceId: 1, name: 1 })
+            .lean());
+        if (!entity) {
+            // Used to be silent — the upsert would proceed with `organizationId:
+            // undefined` and the schema's `required: true` validation would
+            // bounce the write, leaving the calling .catch() to log a warn that
+            // got buried among other warns. Throwing here surfaces the race
+            // explicitly so the calling trigger handler's enhanced
+            // .catch() can emit a proper telemetry event with this exact reason.
+            throw new Error(`saveLastPayload: ${this.cascadeNodeType} entity ${id} not found at write time (race? was the trigger deleted between push and persist?)`);
+        }
+        const result = await this.connection.db
+            ?.collection('nodepayloads')
+            .updateOne({ nodeId: new mongoose_1.Types.ObjectId(id) }, {
+            $set: {
+                nodeType: this.cascadeNodeType,
+                organizationId: entity.organizationId,
+                workspaceId: entity.workspaceId,
+                name: entity.name,
+                payload,
+                /**
+                 * ⚠️ SIEMPRE se escribe, aunque sea `false`.
+                 *
+                 * Si sólo se pusiera al promover un ejemplo, la marca se quedaría
+                 * pegada: el siguiente evento REAL sobreescribiría el payload y el
+                 * panel seguiría diciendo "Example data" sobre datos de verdad —
+                 * que es peor que no marcarlo nunca.
+                 */
+                example: meta?.example === true,
+                /**
+                 * ⚠️ Y por lo mismo, SIEMPRE `false`.
+                 *
+                 * Éste es el segundo escritor de payloads —el otro es
+                 * `NodePayloadsService.save()`— y si sólo limpiara aquel, el aviso
+                 * de «esta salida es de otra conexión» se quedaría pegado en todos
+                 * los nodos que pasan por aquí: la ejecución nueva sobreescribiría
+                 * el payload y el panel seguiría avisando sobre datos recién
+                 * traídos. Mismo error que documenta `example`, dos líneas arriba.
+                 */
+                staleConnection: false,
+                updatedAt: new Date(),
+            },
+            $setOnInsert: {
+                nodeId: new mongoose_1.Types.ObjectId(id),
+                createdAt: new Date(),
+            },
+        }, { upsert: true });
+        // Confirm the upsert actually landed. Diagnostic line — temporary,
+        // remove once the slack-trigger output-payload-empty bug is resolved.
+        // matched=1 → existing doc updated. upserted=yes → new doc created.
+        // matched=0 + upserted=no → write was a no-op (shouldn't happen with
+        // upsert: true, but worth catching). Local Logger so we don't collide
+        // with the `private readonly logger` declared on every subclass.
+        BASE_NODE_SAVE_PAYLOAD_LOGGER.log(`saveLastPayload — type=${this.cascadeNodeType} id=${id} matched=${result?.matchedCount ?? 0} modified=${result?.modifiedCount ?? 0} upserted=${result?.upsertedId ? 'yes' : 'no'}`);
+        // Keep Redis cache in sync so downstream $() reads get fresh data
+        if (entity.workspaceId && entity.name) {
+            (0, workspace_payloads_1.cacheNodePayload)(entity.workspaceId.toString(), entity.name, payload);
+        }
+        return { organizationId: entity.organizationId.toString() };
+    }
+    async remove(id, orgId) {
+        /* `findOneAndDelete` y no `deleteOne` porque hace falta el `workspaceId`
+           del nodo, y una vez borrado no queda de dónde sacarlo.
+    
+           Sin él esto invalidaba sólo `canvas:{org}:all`, que es una clave que el
+           dashboard no pide nunca: siempre lee `canvas:{org}:{workspace}`. El nodo
+           borrado seguía en el lienzo hasta que vencía el TTL de 30 s, y volver a
+           borrarlo respondía «not found» —el de aquí abajo— porque en Mongo ya no
+           estaba. */
+        const deleted = await this.model.findOneAndDelete({
+            _id: new mongoose_1.Types.ObjectId(id),
+            organizationId: new mongoose_1.Types.ObjectId(orgId),
+        });
+        if (!deleted)
+            throw new common_1.NotFoundException(`${this.entityName} not found`);
+        await this.onCascadeDelete(id);
+        await (0, cascade_cleanup_1.cascadeCleanupNodeReferences)(this.connection, this.cascadeNodeType, id);
+        /* Al final y no justo tras el borrado: la limpieza en cascada desconecta
+           este nodo de los demás, y esas aristas también salen en el lienzo. Tirar
+           la clave antes dejaba una ventana en la que una lectura volvía a cachear
+           el grafo con las conexiones muertas todavía puestas. */
+        /* Y su sitio en el lienzo. Sin esto la clave se queda para siempre: es de
+           donde salió el 78 % de posiciones muertas del mapa viejo, y ya estaba
+           volviendo a pasar en la colección nueva. */
+        await (0, olvidar_la_colocacion_1.olvidarLaColocacion)(this.connection, this.cascadeNodeType, id, deleted.workspaceId?.toString());
+        (0, workspace_payloads_1.invalidateCanvasCache)(orgId, deleted.workspaceId?.toString());
+    }
+    /** Override for custom cascade cleanup (e.g. router rules). Default is no-op. */
+    async onCascadeDelete(_id) { }
+    /** Sugar for the one lookup event-pipeline does often enough to name. */
+    findActiveByInputWebhook(webhookId) {
+        return this.findActiveByInput('webhook', webhookId);
+    }
+    /** Find active nodes where the given node is an input source */
+    async findActiveByInput(nodeType, nodeId) {
+        return this.model
+            .find({
+            inputNodes: {
+                $elemMatch: { nodeType, nodeId: new mongoose_1.Types.ObjectId(nodeId) },
+            },
+            isActive: true,
+        })
+            .lean();
+    }
+    /**
+     * Standard create: assertUniqueNodeName → model.create → normalizeAndValidateConnections.
+     * Pass node-specific fields via `fields` — userId, orgId, workspaceId, inputNodes,
+     * outputNodes, isActive, and name are handled automatically.
+     */
+    async createNode(dto, userId, orgId, extraFields = {}) {
+        /* `workspaceId` llega del cuerpo y se escribía tal cual. Un id de OTRA
+           organización tampoco lo frenaba el guardia: no aparece en su consulta
+           —que filtra por organización— y su regla para «no encontrado» es dejar
+           contestar al manejador, para que un id equivocado siga dando 404 en vez
+           de delatar su existencia con un 403. Sólo que el manejador tampoco
+           miraba. Ver `workspaces/acceso-al-workspace.ts`. */
+        await (0, acceso_al_workspace_1.asegurarWorkspaceDeLaOrganizacion)(this.connection, dto.workspaceId, orgId);
+        await (0, unique_name_1.assertUniqueNodeName)(this.connection, dto.workspaceId, dto.name);
+        /* ANTES del `create`, no después. La comprobación de workspace corría con
+           el nodo ya guardado y sin transacción alrededor: el 400 salía, pero la
+           arista rechazada se quedaba escrita y el motor la seguía en el siguiente
+           evento. El workspace es el del DTO —el mismo con el que va a nacer el
+           nodo— y todavía no hay `_id`, así que no cabe autoconexión. */
+        await this.normalizeAndValidateConnections(dto, dto.workspaceId);
+        const saved = await this.model.create({
+            name: dto.name,
+            isActive: dto.isActive ?? true,
+            inputNodes: (0, normalize_nodes_1.normalizeNodes)(dto.inputNodes),
+            outputNodes: (0, normalize_nodes_1.normalizeNodes)(dto.outputNodes),
+            userId: new mongoose_1.Types.ObjectId(userId),
+            organizationId: new mongoose_1.Types.ObjectId(orgId),
+            workspaceId: dto.workspaceId ? new mongoose_1.Types.ObjectId(dto.workspaceId) : null,
+            ...extraFields,
+        });
+        (0, workspace_payloads_1.invalidateCanvasCache)(orgId, saved.workspaceId?.toString());
+        return saved;
+    }
+    /**
+     * Normalize inputNodes/outputNodes and validate the structural rules.
+     *
+     * Tres reglas. Dos son sobre la forma del grafo y necesitan ids —no se puede
+     * cruzar de workspace, y un nodo no se conecta a sí mismo—, y por eso viven
+     * aquí y no en el registro.
+     *
+     * La tercera sí es de tipos. Aquí ponía que la compatibilidad «es cosa del
+     * registro y se comprueba en el lienzo», y eso sólo vale si el lienzo es el
+     * único que escribe. No lo es: `/agent-context` le explica a un agente que
+     * meta las referencias a mano, y cualquier cliente con la clave puede. Lo
+     * que entra por ahí no falla, desaparece — ver `assertConnectableTypes`.
+     */
+    async normalizeAndValidateConnections(dto, workspaceId, selfId) {
+        if (dto.inputNodes === undefined && dto.outputNodes === undefined)
+            return;
+        const nodes = [...(dto.inputNodes ?? []), ...(dto.outputNodes ?? [])];
+        (0, sync_connections_1.assertConnectableTypes)(this.cascadeNodeType, dto);
+        if (selfId)
+            (0, sync_connections_1.assertNoSelfConnection)(this.cascadeNodeType, selfId, nodes);
+        await (0, sync_connections_1.validateConnectionWorkspaces)(this.connection, workspaceId, nodes);
+    }
+    /** Build update payload with normalized nodes */
+    buildUpdatePayload(dto) {
+        const update = (0, dto_utils_1.definedProps)({ ...dto });
+        if (dto.inputNodes !== undefined)
+            update.inputNodes = (0, normalize_nodes_1.normalizeNodes)(dto.inputNodes);
+        if (dto.outputNodes !== undefined)
+            update.outputNodes = (0, normalize_nodes_1.normalizeNodes)(dto.outputNodes);
+        this.castSchemaObjectIdFields(update);
+        return update;
+    }
+    /**
+     * Walk the entity's schema and convert any field declared as
+     * `Types.ObjectId` (or `[Types.ObjectId]`) from a string back to a
+     * proper ObjectId before the value enters a `findOneAndUpdate` $set.
+     *
+     * **Why this exists:** Mongoose does NOT auto-cast nested $set paths to
+     * the schema's declared types — the cast only fires for full-document
+     * `save()` and `Document.set()`. So a dashboard PATCH that lands a
+     * `credentialId: "69fe70…"` string in the dto would persist a String
+     * even though the schema says `Types.ObjectId`. That's invisible to
+     * `_id`-keyed lookups (Mongoose casts query filters), but breaks any
+     * downstream query using `field: { $in: [ObjectId(…)] }` because
+     * MongoDB is strict-typed: String !== ObjectId.
+     *
+     * The Slack-trigger `processSlackCommand` was the canary: it routes
+     * inbound pushes by `team_id → credentials → triggers $in [ObjectId]`
+     * and silently dropped every `/joke` invocation as `no-trigger-opted-in`
+     * even though the toggle was correctly true on the entity. Fix landed
+     * 2026-05-09 — see `feedback_basenode_objectid_cast.md` for the full
+     * forensics. Lifting the cast here means every node service inherits
+     * the protection without repeating per-subclass logic.
+     *
+     * Schema-driven so adding a new ObjectId field on any entity
+     * (including Array<ObjectId> like `[{type: ObjectId, ref: 'Foo'}]`)
+     * gets covered automatically — no maintenance needed.
+     *
+     * Skips `_id` (Mongoose handles it explicitly in query casting),
+     * skips `null`/`undefined` (preserves "clear the relationship"
+     * semantics), skips non-hex strings (throwing here would mask
+     * real validation errors).
+     */
+    castSchemaObjectIdFields(payload) {
+        const schema = this.model.schema;
+        if (!schema?.eachPath)
+            return;
+        schema.eachPath((path, schemaType) => {
+            if (path === '_id')
+                return;
+            if (!(path in payload))
+                return;
+            const value = payload[path];
+            if (value == null)
+                return;
+            // Plain `field: ObjectId`
+            //
+            // 'ObjectId', not 'ObjectID'. Mongoose reported the capitalised form up
+            // to v6; this comparison was written against that and silently stopped
+            // matching on the upgrade — half of why this helper was a no-op for so
+            // long. The other half was that every path compiled to Mixed until the
+            // declarations were corrected, so there was nothing to match anyway.
+            if (schemaType?.instance === 'ObjectId' && typeof value === 'string') {
+                if (mongoose_1.Types.ObjectId.isValid(value)) {
+                    payload[path] = new mongoose_1.Types.ObjectId(value);
+                }
+                return;
+            }
+            // `field: [ObjectId]`
+            if (schemaType?.instance === 'Array' &&
+                schemaType.caster?.instance === 'ObjectId' &&
+                Array.isArray(value)) {
+                payload[path] = value.map((v) => typeof v === 'string' && mongoose_1.Types.ObjectId.isValid(v)
+                    ? new mongoose_1.Types.ObjectId(v)
+                    : v);
+                return;
+            }
+        });
+    }
+    /** Standard update with node normalization and workspace validation */
+    async update(id, dto, orgId) {
+        let previousName;
+        /* La credencial de ANTES, para saber si el nodo cambió de servidor. Se lee
+           aquí porque `findOneAndUpdate` de abajo devuelve el documento ya
+           actualizado, y para comparar hace falta el de antes. */
+        let previousCredentialId = null;
+        const tocaConexiones = dto.inputNodes !== undefined || dto.outputNodes !== undefined;
+        if (dto.name !== undefined ||
+            dto.credentialId !== undefined ||
+            tocaConexiones) {
+            /* Filtrado por organización, igual que el `findOneAndUpdate` de abajo:
+               este documento ya no sirve sólo para comparar nombres, ahora decide si
+               la petición sigue. Leerlo sin el filtro dejaba que un nodo de otra
+               organización pusiera el workspace con el que se toma esa decisión. */
+            const existing = await this.model.findOne({
+                _id: new mongoose_1.Types.ObjectId(id),
+                organizationId: new mongoose_1.Types.ObjectId(orgId),
+            });
+            if (!existing)
+                throw new common_1.NotFoundException(`${this.entityName} not found`);
+            previousName = existing.name;
+            previousCredentialId = existing.credentialId?.toString() ?? null;
+            if (dto.name !== undefined) {
+                await (0, unique_name_1.assertUniqueNodeName)(this.connection, existing.workspaceId, dto.name, id);
+            }
+            /* ANTES del `findOneAndUpdate`. Corría después y sin transacción, así
+               que el 400 era cosmético: la arista rechazada ya estaba guardada y el
+               motor la recorría igual. El workspace no se puede cambiar por PATCH,
+               así que el de antes de escribir es el mismo que el de después. */
+            if (tocaConexiones) {
+                await this.normalizeAndValidateConnections(dto, existing.workspaceId, id);
+            }
+        }
+        const update = this.buildUpdatePayload(dto);
+        const updated = await this.model.findOneAndUpdate({
+            _id: new mongoose_1.Types.ObjectId(id),
+            organizationId: new mongoose_1.Types.ObjectId(orgId),
+        }, { $set: update }, { returnDocument: 'after' });
+        if (!updated)
+            throw new common_1.NotFoundException(`${this.entityName} not found`);
+        if (dto.name !== undefined) {
+            await (0, workspace_payloads_1.propagateNodeRename)(this.connection, id, previousName, dto.name, updated.workspaceId?.toString());
+        }
+        /* Cambiar de credencial es cambiar de servidor, y la última salida
+           guardada se queda enseñando lo que devolvió el anterior. Se marca para
+           que la UI pueda decir de dónde viene, en vez de pintarla como si fuera
+           de la conexión de ahora. No se borra: esa salida sigue siendo útil para
+           mapear campos aguas abajo — lo que sobra es el silencio, no el dato.
+    
+           Vive aquí, en la base, y no en los dos nodos de base de datos: cualquier
+           nodo con credencial tiene el mismo problema en cuanto la cambia. */
+        if (dto.credentialId !== undefined) {
+            const nuevaCredencial = dto.credentialId
+                ? String(dto.credentialId)
+                : null;
+            if (nuevaCredencial !== previousCredentialId) {
+                await this.connection
+                    .collection('nodepayloads')
+                    .updateOne({ nodeId: new mongoose_1.Types.ObjectId(id) }, { $set: { staleConnection: true } })
+                    .catch((0, swallow_1.onFailure)(BASE_NODE_STALE_PAYLOAD_LOGGER, `marcar la salida de ${id} como de otra conexión`));
+            }
+        }
+        /* El aviso «se borró tu credencial» se apaga cuando vuelve a haber una.
+    
+           El marcador lo escribe `credentials.service.remove` y hasta ahora no lo
+           borraba NADIE: un solo `$set` en toda la api y ningún `$unset`. El
+           dashboard se limitaba a ocultarlo mientras el nodo tuviera credencial,
+           así que seguía vivo debajo — y resucitaba en cuanto el nodo se quedaba
+           sin ella otra vez, aunque fuera por pulsar «Disconnect», que sólo pone
+           el campo a null y no borra nada. El usuario leía «fue eliminada el 20 de
+           agosto» tres días después de desconectar a mano.
+    
+           Va aquí y no en el `$set` de arriba porque la condición no es «el dto
+           trae credencial» sino «el nodo TIENE credencial»: así también se limpia
+           el fósil de un nodo que sólo cambió de nombre. En el caso normal no hay
+           marcador y la función vuelve sin tocar la base. */
+        await (0, limpiar_marcador_detach_1.limpiarMarcadorDetachSiEsFosil)(this.model, updated, {
+            tocoCredencial: (0, credential_references_1.dtoTocaCredencial)(dto),
+        });
+        (0, workspace_payloads_1.invalidateCanvasCache)(orgId, updated.workspaceId?.toString());
+        return updated;
+    }
+}
+exports.BaseNodeService = BaseNodeService;

package/dist/cascade-cleanup.d.ts

@@ -0,0 +1,13 @@
+import { Connection } from 'mongoose';
+/**
+ * Remove everything a deleted node leaves behind: the references other
+ * nodes hold to it, and the payload row it owned.
+ *
+ * Called by every node service's remove() — the 39 that inherit
+ * `BaseNodeService.remove` plus webhooks and scheduled-workflows, which
+ * call it directly. That makes this the one funnel all 42 node types pass
+ * through on delete, which is why the payload cleanup lives here instead of
+ * in `BaseNodeService` (where the two outliers would have been missed) or
+ * in a per-type `onCascadeDelete` override (42 chances to forget one).
+ */
+export declare function cascadeCleanupNodeReferences(db: Connection, deletedNodeType: string, deletedNodeId: string): Promise<void>;

package/dist/cascade-cleanup.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cascadeCleanupNodeReferences = cascadeCleanupNodeReferences;
+const common_1 = require("@nestjs/common");
+const mongoose_1 = require("mongoose");
+const node_dispatch_registry_1 = require("./node-dispatch.registry");
+const output_node_dto_1 = require("./dto/output-node.dto");
+const workspace_payloads_1 = require("./workspace-payloads");
+const logger = new common_1.Logger('CascadeCleanup');
+/**
+ * Build all known aliases for a nodeType (e.g. 'scheduledWorkflow' also matches 'scheduled-workflow').
+ */
+function getNodeTypeVariants(nodeType) {
+    const variants = new Set([nodeType]);
+    // Check reverse: find aliases that normalize to this type
+    for (const [alias, canonical] of Object.entries(output_node_dto_1.NODE_TYPE_ALIASES)) {
+        if (canonical === nodeType)
+            variants.add(alias);
+    }
+    // Check forward: if the input is an alias, add the canonical
+    if (output_node_dto_1.NODE_TYPE_ALIASES[nodeType])
+        variants.add(output_node_dto_1.NODE_TYPE_ALIASES[nodeType]);
+    return [...variants];
+}
+/**
+ * Every array on a node entity that stores {nodeType, nodeId} refs.
+ *
+ * This list used to have seven entries and was the bug's own habitat: a
+ * node that invented an eighth field name and forgot to add it here kept
+ * orphan references forever — which is exactly what happened to
+ * `loopBackInputNodes`, and to `conditional.branches[].outputNodes`, whose
+ * dead targets needed a second cleanup layer with arrayFilters.
+ *
+ * Phase 1 collapsed the outbound side into `outputNodes` + a port, so
+ * there is nothing left to forget. `loopBackInputNodes` stays because it
+ * is a genuinely different edge — inbound, with a mirror on the target.
+ */
+const TOP_LEVEL_CONNECTION_FIELDS = [
+    'inputNodes',
+    'outputNodes',
+    'loopBackInputNodes', // loop — inbound, mirrored by loopBackTargetId
+];
+/**
+ * Remove everything a deleted node leaves behind: the references other
+ * nodes hold to it, and the payload row it owned.
+ *
+ * Called by every node service's remove() — the 39 that inherit
+ * `BaseNodeService.remove` plus webhooks and scheduled-workflows, which
+ * call it directly. That makes this the one funnel all 42 node types pass
+ * through on delete, which is why the payload cleanup lives here instead of
+ * in `BaseNodeService` (where the two outliers would have been missed) or
+ * in a per-type `onCascadeDelete` override (42 chances to forget one).
+ */
+async function cascadeCleanupNodeReferences(db, deletedNodeType, deletedNodeId) {
+    const nativeDb = db.db;
+    if (!nativeDb)
+        return;
+    const collections = (0, node_dispatch_registry_1.getAllNodeCollections)();
+    const typeVariants = getNodeTypeVariants(deletedNodeType);
+    const oid = new mongoose_1.Types.ObjectId(deletedNodeId);
+    const pullConditions = typeVariants.flatMap((t) => [
+        { nodeType: t, nodeId: deletedNodeId },
+        { nodeType: t, nodeId: oid },
+    ]);
+    // Layer 1: top-level array fields. Single updateMany per collection
+    // covers every TOP_LEVEL_CONNECTION_FIELDS entry in one round-trip.
+    const topLevelPull = Object.fromEntries(TOP_LEVEL_CONNECTION_FIELDS.map((field) => [
+        field,
+        { $or: pullConditions },
+    ]));
+    const topLevelFilterOr = TOP_LEVEL_CONNECTION_FIELDS.flatMap((field) => typeVariants.flatMap((t) => [
+        { [`${field}.nodeType`]: t, [`${field}.nodeId`]: deletedNodeId },
+        { [`${field}.nodeType`]: t, [`${field}.nodeId`]: oid },
+    ]));
+    await Promise.all(collections.map((col) => nativeDb
+        .collection(col)
+        .updateMany({ $or: topLevelFilterOr }, { $pull: topLevelPull })
+        .catch((err) => {
+        logger.error(`Failed to cleanup top-level refs in ${col} for ${deletedNodeType}:${deletedNodeId}: ${err?.message ?? err}`);
+    })));
+    // The node's own payload row. Runs after the reference scrub so a failure
+    // here cannot leave dangling edges pointing at a node that is already gone.
+    await (0, workspace_payloads_1.deleteNodePayload)(db, deletedNodeId);
+    // There used to be two more layers here: an arrayFilters pull over
+    // conditional.branches[].outputNodes, and a $set nulling the router's
+    // rules[].targetNodeId / targetNodeType. Both existed only because a
+    // destination could live nested inside a container or as a loose string.
+    // Since Phase 1 every outbound edge is a `outputNodes` entry, so the
+    // single $pull above reaches all of them — including branches, split
+    // outputs, classifier categories and router rules. The rule itself
+    // survives untouched, which is what the old $set was carefully
+    // preserving by hand.
+}

package/dist/credential-references.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Dónde guarda un nodo la referencia a una credencial — TODAS las formas.
+ *
+ * ## Por qué existe
+ *
+ * `findConsumers` buscaba en dos campos, `credentialId` y `memoryCredentialId`,
+ * y con eso decidía si una credencial estaba en uso. Los nodos que pueden usar
+ * VARIAS credenciales no las guardan así:
+ *
+ *   - `socialMediaAction.credentialIds` — un mapa `plataforma → id | id[]`;
+ *   - `socialMediaAction.extraCredentialIds` — un array;
+ *   - `trigger.serviceConfig.social_media.credentialIds` — el mismo mapa,
+ *     pero anidado dentro de `serviceConfig`.
+ *
+ * Así que borrar una credencial usada SÓLO por esas vías encontraba cero
+ * consumidores: ni 409, ni desatacado, ni aviso. La credencial desaparecía y el
+ * nodo se quedaba con un id que ya no resuelve — que es como Ariel perdió la de
+ * Mastodon el 2026-08-12, y el trigger siguió mostrando `…c0fac6` sin decir
+ * nada.
+ *
+ * No es la primera vez: la cabecera de `remove()` cuenta que esta misma clase
+ * de fallo dejó «19 nodos vivos en 5 workspaces apuntando a tres credenciales
+ * que no existían». Aquel arreglo cubrió los dos campos planos y se olvidó de
+ * los múltiples, porque la lista de campos estaba escrita a mano en la consulta.
+ * Ahora está declarada aquí, y `credential-references.spec.ts` la prueba con la
+ * forma real de cada documento.
+ *
+ * ## Cómo se compara
+ *
+ * Siempre por `String(...)`. Estos campos son `Mixed` en Mongoose, así que el
+ * mismo id vive como `ObjectId` en unos documentos y como `string` en otros —
+ * ver `reference-id.ts`. Comparar por valor fallaría en la mitad.
+ */
+/** Una forma de guardar referencias. `path` admite puntos. */
+export type CredRefShape = 
+/** `credentialId: ObjectId | string | null` */
+{
+    kind: 'scalar';
+    path: string;
+}
+/** `extraCredentialIds: ObjectId[]` */
+ | {
+    kind: 'array';
+    path: string;
+}
+/** `credentialIds: { plataforma: id | id[] }` */
+ | {
+    kind: 'map';
+    path: string;
+};
+/**
+ * Las cinco formas que existen hoy.
+ *
+ * Se barren en TODAS las colecciones de nodos, no sólo en las que declaran el
+ * campo: una consulta por un campo que la colección no tiene simplemente no
+ * devuelve nada, y así añadir el campo a otro nodo no obliga a tocar esta lista.
+ */
+export declare const CREDENTIAL_REF_SHAPES: readonly CredRefShape[];
+/** Lee un camino con puntos. Devuelve `undefined` si algo del medio falta. */
+export declare function leerCamino(doc: unknown, path: string): unknown;
+/**
+ * ¿El valor de este campo referencia la credencial?
+ *
+ * Un mapa puede tener el id como string suelto o dentro de un array: las dos
+ * formas conviven en datos reales (`credentialIds` está declarado como
+ * `Record<string, string[] | string>` justamente por eso).
+ */
+export declare function valorReferencia(valor: unknown, id: string, kind: CredRefShape['kind']): boolean;
+/** Las formas por las que ESTE documento referencia la credencial. */
+export declare function formasQueReferencian(doc: Record<string, unknown>, id: string): CredRefShape[];
+/**
+ * El valor que hay que dejar en el campo al quitar la credencial.
+ *
+ * Devuelve `null` cuando el campo se queda sin nada, para que el documento no
+ * conserve un `{}` o un `[]` que se lee como «configurado, pero vacío».
+ *
+ * En el mapa, una plataforma que se queda sin cuentas **desaparece**: dejarla
+ * con `[]` haría que el trigger siguiera anunciando que vigila Mastodon sin
+ * ninguna cuenta con la que hacerlo.
+ */
+export declare function valorTrasDesatacar(valor: unknown, id: string, kind: CredRefShape['kind']): unknown;
+/**
+ * Los dos campos que `credentials.service.remove` escribe en cada nodo que se
+ * queda huérfano, para que la pantalla pueda decir QUÉ credencial era y
+ * cuándo desapareció (después de desatacar ya no queda id al que preguntar).
+ */
+export declare const CAMPOS_MARCADOR_DETACH: readonly ["credentialDetachedAt", "credentialDetachedName"];
+/** El `$unset` que los quita. */
+export declare const UNSET_MARCADOR_DETACH: Record<string, ''>;
+/** ¿Este valor trae al menos una credencial puesta? */
+export declare function valorTieneCredencial(valor: unknown, kind: CredRefShape['kind']): boolean;
+/**
+ * ¿El nodo tiene AHORA alguna credencial, por cualquiera de las cinco formas?
+ *
+ * Es la pregunta que decide si el aviso «se borró tu credencial» sigue
+ * teniendo sentido. El dashboard hace este mismo cálculo para ocultarlo
+ * (`hooks/useNodeErrors.ts`); aquí sirve para BORRAR el marcador, que es lo
+ * que faltaba: ocultarlo lo dejaba vivo, y volvía a salir en cuanto el nodo
+ * se quedaba sin credencial otra vez — aunque fuera por un «Disconnect» a
+ * mano, y enseñando la fecha de un borrado de días atrás.
+ */
+export declare function tieneAlgunaCredencial(doc: unknown): boolean;
+/**
+ * ¿Hay que quitarle el marcador a este documento?
+ *
+ * Sólo cuando el marcador está Y el nodo volvió a tener credencial. Si sigue
+ * huérfano el aviso es legítimo y se queda: alguien le borró la credencial de
+ * verdad y todavía no ha elegido otra.
+ */
+export declare function marcadorEsFosil(doc: unknown, tocoCredencial?: boolean): boolean;
+/**
+ * ¿Este dto toca el campo de la credencial, sea para poner una o para
+ * quitarla?
+ *
+ * ⚠️ Ésta es la mitad que faltaba, y se vio en cuanto llegó a producción.
+ *
+ * «Es fósil si el nodo VOLVIÓ a tener credencial» arregla el caso de elegir
+ * otra, pero deja fuera el que lo destapó: Ariel pulsó «Disconnect» y el nodo
+ * se quedó SIN credencial, así que seguía contando como huérfano legítimo y
+ * el aviso del día 20 seguía en pantalla. Su queja fue literal: «y sigue».
+ *
+ * La distinción buena no es «tiene credencial» sino «¿sigue siendo verdad que
+ * te la quitaron sin que tú hicieras nada?». En cuanto la persona toca ese
+ * campo —ponga una o la vacíe— ya vio el aviso y actuó: a partir de ahí el
+ * estado lo eligió ella, y seguir diciéndole que se lo borraron el día 20 es
+ * hablarle de otra cosa.
+ *
+ * `!== undefined` y no un truthy: `credentialId: null` es exactamente el caso
+ * de desconectar, y es el que hay que reconocer.
+ */
+export declare function dtoTocaCredencial(dto: unknown): boolean;