@hostwebhook/platform-contracts 0.1.0 → 0.3.0

package/dist/servicios/ficheros-del-gateway.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALMACEN_DE_OBJETOS = exports.REGISTRO_DE_FICHEROS = void 0;
+/**
+ * ⚠️ Cadenas y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+exports.REGISTRO_DE_FICHEROS = 'REGISTRO_DE_FICHEROS';
+exports.ALMACEN_DE_OBJETOS = 'ALMACEN_DE_OBJETOS';

package/dist/servicios/formas-compartidas.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Las formas que varios contratos de esta carpeta necesitan, y que antes
+ * vivían fuera de ella.
+ *
+ * ## Por qué están aquí y no donde estaban
+ *
+ * Al sacar los contratos del monolito, tres de ellos apuntaban a tipos que se
+ * quedaban en la api o en el SDK. Un contrato que describe una frontera no
+ * puede depender de un lado de esa frontera: si `RegistroDeFicheros` habla de
+ * un `FileRef`, entonces `FileRef` **es parte del contrato**, no un detalle
+ * del gateway.
+ *
+ * Los tres eran `import type`, así que no había ciclo en tiempo de ejecución —
+ * pero sí en el de compilación, y sobre todo una mentira sobre quién define
+ * qué.
+ *
+ * ⚠️ Los originales pasan a re-exportar desde aquí. Copiarlos habría dejado dos
+ * definiciones que un día se escriben distinto, que es exactamente lo que este
+ * paquete existe para impedir.
+ */
+/** Un fichero ya registrado: lo que un nodo recibe para poder leerlo. */
+export interface FileRef {
+    id: string;
+    key: string;
+    originalName: string;
+    mimeType: string;
+    size: number;
+    downloadUrl: string;
+}
+export type ChunkingStrategy = 'recursive' | 'fixed' | 'semantic';
+/**
+ * `skipped` es un estado de primera y no un `failed` descafeinado: un paso que
+ * no llegó a correr porque el anterior falló no es lo mismo que uno que sí
+ * corrió y salió mal, y la pantalla necesita distinguirlos para enseñar dónde
+ * se cortó el flujo.
+ */
+export type RunStepStatus = 'success' | 'failed' | 'skipped';
+export interface PasoEjecutado {
+    organizationId: string;
+    correlationId: string;
+    nodeId: string;
+    nodeName?: string;
+    nodeType?: string;
+    status: RunStepStatus;
+    startedAt: Date;
+    durationMs: number;
+    error?: string;
+    /** El origen de la corrida, para poder abrirla en la primera fila. */
+    sourceId?: string;
+    sourceName?: string;
+    workspaceId?: string;
+    entrada?: unknown;
+    salida?: unknown;
+    metadata?: Record<string, unknown>;
+    /** Cómo se disparó la corrida. Ausente = producción. */
+    modo?: 'pipeline';
+}

package/dist/servicios/formas-compartidas.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Las formas que varios contratos de esta carpeta necesitan, y que antes
+ * vivían fuera de ella.
+ *
+ * ## Por qué están aquí y no donde estaban
+ *
+ * Al sacar los contratos del monolito, tres de ellos apuntaban a tipos que se
+ * quedaban en la api o en el SDK. Un contrato que describe una frontera no
+ * puede depender de un lado de esa frontera: si `RegistroDeFicheros` habla de
+ * un `FileRef`, entonces `FileRef` **es parte del contrato**, no un detalle
+ * del gateway.
+ *
+ * Los tres eran `import type`, así que no había ciclo en tiempo de ejecución —
+ * pero sí en el de compilación, y sobre todo una mentira sobre quién define
+ * qué.
+ *
+ * ⚠️ Los originales pasan a re-exportar desde aquí. Copiarlos habría dejado dos
+ * definiciones que un día se escriben distinto, que es exactamente lo que este
+ * paquete existe para impedir.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/servicios/historial-de-corridas.d.ts

@@ -0,0 +1,75 @@
+import type { PasoEjecutado as PasoDelSdk } from './formas-compartidas';
+/**
+ * Lo que un nodo apunta en el historial de corridas. Dos cosas.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `nodes/` y `common/` importaban `history-runs/` así:
+ *
+ *   6  `HistoryRecorderService`   el grabador
+ *   3  `paso-de-origen`           un ayudante PURO, que se muda con ellos
+ *   5  `history-runs.module`      cableado, desaparece con la mudanza
+ *
+ * `HistoryRecorderService` arrastra cuatro colecciones —`runs`, `run_steps`,
+ * `run_payloads`, `flow_versions`—, **su propia conexión de Mongo** a otra
+ * base, el almacén de payloads que se van a R2 y el sellado de versiones del
+ * flujo contra el lienzo. El historial es del gateway: es lo que la pantalla
+ * lee. El nodo sólo tiene que decir qué hizo.
+ *
+ * ## Dos métodos, y ya estaban medio declarados
+ *
+ * El SDK ya tiene `RegistradorDeHistorial` con `registrarPaso`, porque el
+ * ciclo de vida lo necesitaba y no podía depender de la api. Le falta
+ * `cerrar`, que es lo que usa quien ARRANCA una corrida y sabe cuándo acaba.
+ *
+ * Así que este contrato no inventa: reusa `PasoEjecutado` del SDK y le añade
+ * el único campo que la api tiene de más.
+ *
+ * ⚠️ Las dos definiciones habían divergido — la del SDK tiene `metadata` y le
+ * falta `esOrigen`; la de la api al revés. `extends` deja de multiplicar
+ * copias: los campos compartidos se declaran en un sitio.
+ *
+ * ## Cómo viaja
+ *
+ * ⚠️ Los dos métodos devuelven `void` y **no esperan ni lanzan**: por dentro
+ * hacen `void this.encolar(...).catch(...)`. Eso es deliberado y hay que
+ * conservarlo. Un nodo no puede fallar porque no se haya podido escribir una
+ * fila de historial, y menos aún quedarse esperando a que se escriba —
+ * `registrarPaso` corre en el camino caliente de CADA paso del pipeline.
+ *
+ * ⚠️ Y el orden importa: el grabador encola por `correlationId` para que los
+ * pasos de una corrida se escriban en orden y `cerrar` llegue el último. Una
+ * implementación por red que mandara los mensajes en paralelo cerraría
+ * corridas antes de tiempo, y el veredicto saldría mal.
+ */
+/**
+ * Un paso ejecutado.
+ *
+ * ⚠️ Extiende el del SDK en vez de copiarlo. `esOrigen` es lo único que la api
+ * necesita de más: marca el nodo que ARRANCÓ la corrida, que cuenta en
+ * `steps` pero no en el denominador del veredicto. Sin él, una corrida de una
+ * sola acción fallida se lee `partial` en vez de `failed`.
+ */
+export interface PasoEjecutado extends PasoDelSdk {
+    esOrigen?: boolean;
+}
+/** Quien anota lo que pasa en una corrida. */
+export interface GrabadorDeHistorial {
+    /**
+     * ⚠️ `void`, no espera y no lanza. Corre en el camino caliente de cada
+     * paso: ver la nota de arriba.
+     */
+    registrarPaso(paso: PasoEjecutado): void;
+    /**
+     * La corrida terminó.
+     *
+     * ⚠️ Tiene que llegar DESPUÉS de los pasos de esa misma `correlationId`. El
+     * grabador lo garantiza encolando por corrida; quien lo implemente por red
+     * tiene que garantizarlo también.
+     */
+    cerrar(correlationId: string): void;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+export declare const HISTORIAL_DE_CORRIDAS = "HISTORIAL_DE_CORRIDAS";

package/dist/servicios/historial-de-corridas.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HISTORIAL_DE_CORRIDAS = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+exports.HISTORIAL_DE_CORRIDAS = 'HISTORIAL_DE_CORRIDAS';

package/dist/servicios/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Los contratos entre servicios: lo que el gateway y hw-nodes se piden.
+ *
+ * Cada fichero es **un token de cadena + la interfaz que ese token promete**.
+ * Nada de implementación: quien sirve el contrato vive en un servicio y quien
+ * lo consume en el otro, y este paquete es lo único que los dos comparten.
+ *
+ * ## Por qué aquí y no en `@hostwebhook/node-sdk`
+ *
+ * El SDK está **publicado para autores de nodos**: es ciclo de vida,
+ * reintentos, filtros e iteración. Estos veintiocho son fontanería interna
+ * entre dos servicios nuestros —`TUNELES_DE_LA_ORGANIZACION`,
+ * `SECRETOS_DE_FIRMA`, `REGISTRO_DE_ENTREGAS`—, y meterlos ahí los habría
+ * convertido en API pública: cada cambio pasaría a ser una pregunta de
+ * compatibilidad hacia fuera.
+ *
+ * ## ⚠️ Lo que NO entra aquí
+ *
+ * Lo mismo que dice el `index.ts` de arriba, y con un caso que se comprobó al
+ * mudarlos: `limites-del-plan` entra porque es la PREGUNTA («¿cuáles son los
+ * topes de esta organización?»), no los topes. Los valores —`PLAN_LIMITS`, los
+ * precios, los ids de Stripe— se quedan en el gateway, donde se pueden cambiar
+ * sin publicar un paquete.
+ *
+ * Y `credenciales-del-gateway` entra porque describe la forma de la pregunta,
+ * que está diseñada justo para que los secretos NO crucen a lo bruto. Ningún
+ * secreto vive aquí.
+ */
+export type { FileRef, ChunkingStrategy, RunStepStatus, PasoEjecutado as PasoEjecutadoDelSdk, } from './formas-compartidas';
+export * from './almacenes-vectoriales';
+export * from './aprobaciones-pendientes';
+export * from './avisos-en-vivo';
+export * from './canal-de-stream';
+export * from './conversaciones-del-chat';
+export * from './corridas-programadas';
+export * from './credencial/permiso-sobre-credencial';
+export * from './credenciales-del-gateway';
+export * from './cuentas-de-atlassian';
+export * from './descarga-de-drive';
+export * from './ejecucion-de-ia';
+export * from './enlaces-de-flujo';
+export * from './ficheros-del-gateway';
+export * from './historial-de-corridas';
+export * from './limites-del-plan';
+export * from './motor-de-ejecucion';
+export * from './plantillas-de-origen';
+export * from './posts-sociales';
+export * from './registro-de-entregas';
+export * from './registro-de-eventos';
+export * from './restauracion-de-nodos';
+export * from './salud-del-webhook';
+export * from './secretos-de-firma';
+export * from './telemetria';
+export * from './trazas-de-llm';
+export * from './tuneles';
+export * from './workspace/acceso-al-recurso';
+export * from './zona-horaria-del-usuario';

package/dist/servicios/index.js

@@ -0,0 +1,44 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./almacenes-vectoriales"), exports);
+__exportStar(require("./aprobaciones-pendientes"), exports);
+__exportStar(require("./avisos-en-vivo"), exports);
+__exportStar(require("./canal-de-stream"), exports);
+__exportStar(require("./conversaciones-del-chat"), exports);
+__exportStar(require("./corridas-programadas"), exports);
+__exportStar(require("./credencial/permiso-sobre-credencial"), exports);
+__exportStar(require("./credenciales-del-gateway"), exports);
+__exportStar(require("./cuentas-de-atlassian"), exports);
+__exportStar(require("./descarga-de-drive"), exports);
+__exportStar(require("./ejecucion-de-ia"), exports);
+__exportStar(require("./enlaces-de-flujo"), exports);
+__exportStar(require("./ficheros-del-gateway"), exports);
+__exportStar(require("./historial-de-corridas"), exports);
+__exportStar(require("./limites-del-plan"), exports);
+__exportStar(require("./motor-de-ejecucion"), exports);
+__exportStar(require("./plantillas-de-origen"), exports);
+__exportStar(require("./posts-sociales"), exports);
+__exportStar(require("./registro-de-entregas"), exports);
+__exportStar(require("./registro-de-eventos"), exports);
+__exportStar(require("./restauracion-de-nodos"), exports);
+__exportStar(require("./salud-del-webhook"), exports);
+__exportStar(require("./secretos-de-firma"), exports);
+__exportStar(require("./telemetria"), exports);
+__exportStar(require("./trazas-de-llm"), exports);
+__exportStar(require("./tuneles"), exports);
+__exportStar(require("./workspace/acceso-al-recurso"), exports);
+__exportStar(require("./zona-horaria-del-usuario"), exports);

package/dist/servicios/limites-del-plan.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Los topes del plan que un nodo necesita saber. Nada más.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `src/nodes/` importaba `plans/` 64 veces, y ese
+ * número engaña como engañaban los otros:
+ *
+ *   48  `PlansModule`      cableado de DI, desaparece con la mudanza
+ *   13  `PlansService`     de los que TODOS llaman UN método
+ *    3  helpers sueltos    `managedStorageUsage`, `enMegas`, `registerManagedStore`
+ *
+ * Los trece llaman `getOrgPlanLimits` y ninguno llama nada más. `PlansService`
+ * arrastra 13 ficheros del gateway —`plan.constants`, la entidad de usuario,
+ * la de organización— y con eso esos trece servicios de nodo no se pueden
+ * mudar a `hw-nodes`.
+ *
+ * ## Lo que lee cada uno, medido
+ *
+ * Del resultado se desestructura `{ limits, tier }`, y de `limits` se leen
+ * SEIS campos. Son los que están abajo. No se copia la forma entera de
+ * `PLAN_LIMITS` —que tiene muchos más— por la misma doctrina que el resto de
+ * contratos de esta fase: la superficie USADA, no la entidad completa.
+ *
+ * ⚠️ Y aquí el compilador es el verificador. Si me dejé un campo fuera, el
+ * sitio que lo lee no compila — no hace falta creerse la medición.
+ *
+ * ## Cuando esto cruce una red
+ *
+ * Bien: son números y una cadena. A diferencia de la costura del motor —que
+ * pasaba documentos de Mongoose vivos— y de la de Drive —donde `auth` es un
+ * objeto con métodos—, esto viaja tal cual.
+ */
+/** Los topes que un nodo consulta antes de aceptar una configuración. */
+export interface TopesDelPlan {
+    /** Reintentos máximos de una entrega. */
+    maxRetries: number;
+    /** Segundos entre reintentos. */
+    maxRetryDelaySeconds: number;
+    /**
+     * El TECHO del backoff, que no es lo mismo que el de arriba.
+     *
+     * ⚠️ Octavo campo, y otra vez lo encontró el COMPILADOR y no mi medición.
+     * Se parecen tanto en el nombre que es fácil dar uno por el otro: uno es el
+     * hueco entre reintentos y éste el límite al que el backoff deja de crecer.
+     * Confundirlos hace que una organización reintente con el calendario de
+     * otra, y nada lo dice.
+     */
+    maxRetryDelayCapSeconds: number;
+    /** Techo del nodo de espera. */
+    maxDelaySeconds: number;
+    /** Minutos que puede esperar una aprobación. */
+    maxApprovalTimeoutMinutes: number;
+    /** Minutos que puede esperar un merge a sus ramas. */
+    maxMergeTimeoutMinutes: number;
+    /** Cada cuánto, como mínimo, puede dispararse un cron. */
+    minCronIntervalMinutes: number;
+    /**
+     * Cuántas veces puede pasar una corrida por el mismo nodo.
+     *
+     * ⚠️ Éste se me escapó al medir y lo encontró el COMPILADOR: se lee con
+     * encadenado opcional (`?.limits?.maxNodeCycles`) y mi barrido exigía un
+     * punto literal. Es la cuarta forma del mismo error esta tanda —dar por
+     * hecho que el código se escribe como uno lo busca— y por eso el contrato
+     * se escribe primero y se deja que tsc lo corrija, en vez de fiarse de la
+     * medición.
+     */
+    maxNodeCycles: number;
+}
+export interface LimitesDeLaOrganizacion {
+    limits: TopesDelPlan;
+    /** El plan contratado. Se usa para el mensaje de error, no para decidir. */
+    tier: string;
+}
+export interface LimitesDelPlan {
+    getOrgPlanLimits(orgId: string): Promise<LimitesDeLaOrganizacion>;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que los otros tokens de la Fase 2: un
+ * `Symbol` no sobrevive a una frontera de módulo duplicada.
+ */
+export declare const LIMITES_DEL_PLAN = "LIMITES_DEL_PLAN";

package/dist/servicios/limites-del-plan.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Los topes del plan que un nodo necesita saber. Nada más.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `src/nodes/` importaba `plans/` 64 veces, y ese
+ * número engaña como engañaban los otros:
+ *
+ *   48  `PlansModule`      cableado de DI, desaparece con la mudanza
+ *   13  `PlansService`     de los que TODOS llaman UN método
+ *    3  helpers sueltos    `managedStorageUsage`, `enMegas`, `registerManagedStore`
+ *
+ * Los trece llaman `getOrgPlanLimits` y ninguno llama nada más. `PlansService`
+ * arrastra 13 ficheros del gateway —`plan.constants`, la entidad de usuario,
+ * la de organización— y con eso esos trece servicios de nodo no se pueden
+ * mudar a `hw-nodes`.
+ *
+ * ## Lo que lee cada uno, medido
+ *
+ * Del resultado se desestructura `{ limits, tier }`, y de `limits` se leen
+ * SEIS campos. Son los que están abajo. No se copia la forma entera de
+ * `PLAN_LIMITS` —que tiene muchos más— por la misma doctrina que el resto de
+ * contratos de esta fase: la superficie USADA, no la entidad completa.
+ *
+ * ⚠️ Y aquí el compilador es el verificador. Si me dejé un campo fuera, el
+ * sitio que lo lee no compila — no hace falta creerse la medición.
+ *
+ * ## Cuando esto cruce una red
+ *
+ * Bien: son números y una cadena. A diferencia de la costura del motor —que
+ * pasaba documentos de Mongoose vivos— y de la de Drive —donde `auth` es un
+ * objeto con métodos—, esto viaja tal cual.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIMITES_DEL_PLAN = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que los otros tokens de la Fase 2: un
+ * `Symbol` no sobrevive a una frontera de módulo duplicada.
+ */
+exports.LIMITES_DEL_PLAN = 'LIMITES_DEL_PLAN';

package/dist/servicios/motor-de-ejecucion.d.ts

@@ -0,0 +1,197 @@
+import type { Types } from 'mongoose';
+/**
+ * Lo que un nodo le pide al motor de ejecución. Nada más.
+ *
+ * ## Por qué existe
+ *
+ * Es la costura de la Fase 2. Para que `src/nodes/` pueda salir a `hw-nodes`
+ * —un servicio aparte— no puede importar `EventPipelineService` ni
+ * `PipelineRunService`: son el motor, y el motor se queda en el gateway.
+ *
+ * Medido antes de escribir esto: son **14 imports en 12 ficheros**, y todo lo
+ * que se llama son **seis métodos**. Nada más. Cinco familias de nodo
+ * —approval, merge, scheduled-workflows, triggers y ai— y ninguna otra.
+ *
+ * ⚠️ El barrido que lo midió tuvo que admitir SALTOS DE LÍNEA: en
+ * `ai-nodes.service` la llamada está partida
+ * (`void this.eventPipelineService` y `.dispatchFromOriginEntity(` debajo),
+ * y una regex de una línea se dejó ese método fuera. Una interfaz a la que
+ * le falta un método es una interfaz que no sirve.
+ *
+ * ## Por qué está aquí y no en el SDK
+ *
+ * Porque todavía no hay un segundo consumidor. El propio plan lo dice para
+ * los paquetes: extraer antes de que alguien lo pida es cómo se acaba con
+ * código publicado que nadie usa. Cuando `hw-nodes` exista de verdad, este
+ * fichero se muda entero y los `import type` de abajo se convierten en las
+ * formas planas que viajen por la red.
+ *
+ * Lo que SÍ cambia hoy es lo que importa: `nodes/` deja de conocer al motor.
+ * Los tipos entran por `import type` —que se borra al compilar— y el único
+ * vínculo en ejecución es el token, que es una cadena.
+ *
+ * ## ⚠️ Lo que esta interfaz NO arregla
+ *
+ * Por aquí cruzan **documentos de Mongoose vivos**, no datos planos:
+ * `PendingApprovalDocument`, `WebhookDocument`, `PipelineContext`. El plan
+ * dice que `hw-nodes` será «sin estado: el runner le manda entidad, payload
+ * y credencial», y eso hoy no es cierto en esta costura. Aplanarlo es
+ * trabajo aparte y hay que hacerlo ANTES de que esto cruce una red — un
+ * documento de Mongoose no sobrevive a un `JSON.stringify` con sus métodos.
+ *
+ * Se declaran como formas mínimas y no como las entidades enteras, que es la
+ * misma doctrina de `contratos.ts` en el SDK: la superficie USADA, no el
+ * documento completo. Así el día que esto se serialice, lo que hay que
+ * aplanar está escrito aquí y no hay que ir a buscarlo.
+ */
+/**
+ * Medido, no adivinado: cada forma de aquí es lo que el motor LEE de ese
+ * parámetro y nada más. `webhook` son dos campos, no un documento.
+ *
+ * ## Por qué son formas y no `unknown`
+ *
+ * La primera versión los dejó opacos, y opaco no sirve para el destino: el
+ * día que esto cruce una red hay que saber QUÉ serializar. Escrito aquí, la
+ * lista de lo que hay que empaquetar está donde se necesita.
+ *
+ * ⚠️ Y NO llevan `[k: string]: unknown`. Un índice de cadena hace la forma
+ * MÁS estricta, no menos —un documento de Mongoose no lo tiene— y rechazaría
+ * justo lo que hoy se le pasa. Sin él, el tipado estructural acepta el
+ * documento vivo Y el objeto plano, que es exactamente lo que hace falta
+ * durante la transición.
+ *
+ * ## Cómo se comprobó que se puede aplanar
+ *
+ * Se midió qué hace el motor con cada uno: **sólo lecturas de propiedad**,
+ * ninguna llamada a método de Mongoose. Y de las siete funciones que reciben
+ * uno entero, seis tampoco los tocan. La única que sí —`gateApproval`, con
+ * `event.toJSON()`— se arregló para aceptar los dos.
+ */
+/** Lo que el motor lee de un evento. */
+export interface EventoDeCorrida {
+    id: unknown;
+    correlationId?: unknown;
+    eventType?: unknown;
+    headers?: unknown;
+    sourceIp?: unknown;
+    webhookId?: unknown;
+}
+/** Y de un webhook: dos campos. */
+export interface WebhookDeCorrida {
+    id: unknown;
+    name?: unknown;
+}
+/**
+ * El contexto de la corrida.
+ *
+ * ⚠️ `nodeVisitCounts` va como OBJETO y no como `Map`, y ése era el segundo
+ * bloqueo del aplanado: un `Map` se convierte en `{}` al serializar, y aquí
+ * además se MUTA al otro lado —`ctx.nodeVisitCounts.set(...)`—, así que por
+ * una red el contador de ciclos dejaría de contar en silencio. Y fallar en la
+ * detección de ciclos es un bucle infinito, no un aviso.
+ *
+ * No hay que inventar nada: el motor YA hace esta conversión para cruzar la
+ * cola de BullMQ —`Object.fromEntries` al salir, `new Map(Object.entries(…))`
+ * al entrar, ver `delivery.processor`— porque un job es JSON. La costura usa
+ * la misma forma serializada, y el motor convierte en su borde.
+ */
+export interface ContextoDeCorrida {
+    orgId: string;
+    backoffCapMs?: number;
+    maxNodeCycles?: number;
+    nodeVisitCounts?: Record<string, number>;
+}
+/** Una espera pendiente, de lo que el motor le lee. */
+export interface EsperaPendiente {
+    id?: unknown;
+    eventId?: unknown;
+    eventHeaders?: unknown;
+    organizationId?: unknown;
+    payload?: unknown;
+    pipelineContext?: unknown;
+    webhookId?: unknown;
+}
+/** Un nodo de aprobación. */
+export interface NodoDeAprobacion {
+    _id: unknown;
+    name?: unknown;
+    outputNodes?: unknown;
+    rejectionOutputNodes?: unknown;
+}
+/** El estado acumulado de un merge. */
+export interface EstadoDeMerge {
+    correlationId?: unknown;
+    expectedCount?: unknown;
+    organizationId?: unknown;
+    receivedBranches?: unknown;
+}
+/** Un nodo de merge. */
+export interface NodoDeMerge {
+    _id: unknown;
+    name?: unknown;
+}
+/** Un paso ejecutado, tal como lo devuelve `resumeFromApproval`. */
+export type PasoDeCorrida = unknown;
+/**
+ * Los seis métodos, agrupados por lo que hacen.
+ *
+ * Se separan en dos interfaces porque hoy las implementan DOS servicios
+ * distintos —`EventPipelineService` y `PipelineRunService`— y juntarlas
+ * obligaría a un adaptador que no aporta nada.
+ */
+export interface DespachoDelMotor {
+    /** Sigue el flujo hacia los nodos de salida de un webhook. */
+    dispatchOutputNodes(outputNodes: Array<{
+        nodeType: string;
+        nodeId: Types.ObjectId;
+    }>, payload: Record<string, unknown>, event: EventoDeCorrida, webhook: WebhookDeCorrida, ctx: ContextoDeCorrida, depth: number): Promise<void>;
+    /**
+     * Arranca una corrida desde un nodo cualquiera, sin webhook de por medio.
+     * Lo usa el nodo de IA cuando lo dispara un chat: `executeForEvent` se
+     * salta el paso de aguas abajo del ciclo de vida, así que hay que
+     * empujarlo a mano.
+     */
+    dispatchFromOriginEntity(params: {
+        originType: string;
+        originEntity: unknown;
+        payload: Record<string, unknown>;
+        orgId: string;
+        [k: string]: unknown;
+    }): Promise<unknown>;
+    /** Reanuda tras un visto bueno o un rechazo. */
+    resumeAfterApproval(pending: EsperaPendiente, approvalNode: NodoDeAprobacion, action: 'approve' | 'reject'): Promise<void>;
+    /** Reanuda tras una respuesta de «envía y espera». */
+    resumeAfterSendAndWait(pending: EsperaPendiente, decision: {
+        approved: boolean;
+        decidedAt: Date;
+        decidedBy?: string;
+        ipAddress?: string;
+        comment?: string;
+        [k: string]: unknown;
+    }): Promise<void>;
+    /** Reanuda cuando a un merge se le acaba el tiempo de espera. */
+    resumeAfterMergeTimeout(mergeState: EstadoDeMerge, mergeNode: NodoDeMerge): Promise<void>;
+}
+/** El otro servicio: la corrida de prueba desde el panel. */
+export interface CorridaDelMotor {
+    /**
+     * Arrancar una corrida desde un nodo de origen.
+     *
+     * ⚠️ Es «lanza y olvida»: el llamante genera el `executionId`, lo devuelve al
+     * panel de inmediato y el progreso viaja por socket. La promesa que sale de
+     * aquí NO se espera — esperarla dejaría al navegador colgado el tiempo que
+     * dure el flujo entero.
+     */
+    ejecutar(startNodeType: string, startNodeId: string, payload: Record<string, unknown> | undefined, orgId: string, userId: string, executionId: string): Promise<unknown>;
+    resumeFromApproval(approvalNode: NodoDeAprobacion, payload: Record<string, unknown>, action: 'approve' | 'reject', orgId: string): Promise<{
+        executionId: string;
+        steps: PasoDeCorrida[];
+    }>;
+}
+/**
+ * ⚠️ Son cadenas y no `Symbol` a propósito: un `Symbol` no sobrevive a un
+ * `JSON.stringify` ni a una frontera de módulo duplicada, y esto está
+ * pensado para acabar cruzando una.
+ */
+export declare const DESPACHO_DEL_MOTOR = "DESPACHO_DEL_MOTOR";
+export declare const CORRIDA_DEL_MOTOR = "CORRIDA_DEL_MOTOR";

package/dist/servicios/motor-de-ejecucion.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORRIDA_DEL_MOTOR = exports.DESPACHO_DEL_MOTOR = void 0;
+/* ── Los tokens ──────────────────────────────────────────────────── */
+/**
+ * ⚠️ Son cadenas y no `Symbol` a propósito: un `Symbol` no sobrevive a un
+ * `JSON.stringify` ni a una frontera de módulo duplicada, y esto está
+ * pensado para acabar cruzando una.
+ */
+exports.DESPACHO_DEL_MOTOR = 'DESPACHO_DEL_MOTOR';
+exports.CORRIDA_DEL_MOTOR = 'CORRIDA_DEL_MOTOR';

package/dist/servicios/plantillas-de-origen.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Las plantillas de payload de un servicio de trigger.
+ *
+ * ## Por qué es un contrato y no un import
+ *
+ * El registro son **23 ficheros y 5.800 líneas** de plantillas —una por
+ * servicio, y varias miran su config: `changeType` en Calendar, `eventTrigger`
+ * en Gmail, `enabledEvents` en Sheets—. Viven con el trigger, que es uno de los
+ * cinco nodos de origen que se quedan en el gateway.
+ *
+ * `start-node-sample.ts` las necesita para el paso 3 de «con qué payload
+ * arranca una corrida», y ese fichero viaja con el motor. Demasiado para
+ * mudarlo, y demasiado poco para copiarlo: de tener dos copias de una plantilla
+ * salió que un trigger de Google Calendar arrancara con
+ * `{ event: "new_email" }`.
+ *
+ * ⚠️ Y NO se escriben a mano en ningún lado: pasan por el MISMO formateador que
+ * la entrega real, así que no pueden desfasarse de lo que se despacha. Una copia
+ * sí se desfasa.
+ */
+export type PlantillasDeOrigen = (service: string | null | undefined, serviceConfig: Record<string, unknown> | undefined) => Array<{
+    payload: Record<string, unknown>;
+}>;
+/** ⚠️ Cadena y no `Symbol`. */
+export declare const PLANTILLAS_DE_ORIGEN = "PLANTILLAS_DE_ORIGEN";

package/dist/servicios/plantillas-de-origen.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLANTILLAS_DE_ORIGEN = void 0;
+/** ⚠️ Cadena y no `Symbol`. */
+exports.PLANTILLAS_DE_ORIGEN = 'PLANTILLAS_DE_ORIGEN';