@hostwebhook/platform-contracts 0.22.0 → 0.24.0

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

@@ -72,4 +72,89 @@ export interface PasoEjecutado {
      * de antes: la pantalla cae a la de la versión, avisando.
      */
     configuracion?: Record<string, unknown>;
+    /**
+     * Cómo decidió un conditional [2026-09-29]: cada rama, cada condición con
+     * lo que valió cada lado, y cuál ganó. Sólo lo llevan los pasos de un
+     * conditional; ver `EvaluacionDeRamas`.
+     */
+    evaluacion?: EvaluacionDeRamas;
+    /**
+     * En qué vuelta de qué bucle corrió [2026-09-29]: la pila de los bucles que
+     * lo contienen, del de FUERA al de DENTRO. Ausente fuera de un bucle, en las
+     * corridas de antes, y donde el motor la pierde (tras reanudar un approval).
+     * Ver `VueltaDeBucle`.
+     */
+    vueltas?: VueltaDeBucle[];
+}
+/**
+ * Una vuelta de un bucle, vista desde un paso que corre dentro de él
+ * [2026-09-29].
+ *
+ * Hace falta porque el historial sólo sabía el ORDEN de los pasos: en un
+ * bucle dentro de otro, «la tercera vez que corrió el cuerpo» no dice de qué
+ * pedido ni de qué artículo. La pila la lleva el motor en el contexto
+ * (`ContextoDeCorrida.pilaDeVueltas`) y cada paso se la queda.
+ */
+export interface VueltaDeBucle {
+    /** El id del nodo Loop. */
+    bucleId: string;
+    /** Su nombre cuando corrió, para la pantalla. */
+    nombre?: string;
+    /** La vuelta, contando desde 0. */
+    vuelta: number;
+    /** Cuántas vueltas da en esta pasada. */
+    total: number;
+}
+/**
+ * Una condición de una rama, tal como se evaluó.
+ *
+ * `actual` y `esperado` son los dos lados YA RESUELTOS —lo que salió de
+ * `{{payload.amount}}` y de lo que se escribió como valor—, recortados para
+ * que un payload grande no infle el paso. `actual` AUSENTE quiere decir que
+ * el campo no resolvió (`undefined`), que es justo lo que más se busca al
+ * mirar por qué una rama no casó; salvo cuando el payload era una lista, que
+ * entonces no hay un valor sino muchos y lo que va es `items`.
+ */
+export interface CondicionEvaluada {
+    /** El campo tal como se escribió: `{{payload.amount}}` o `amount`. */
+    campo: string;
+    operador: string;
+    /** El valor tal como se escribió, sin resolver. */
+    valor?: string;
+    /** No cuenta: desactivada, o sin campo. Ver `condicionPuesta`. */
+    ignorada?: true;
+    /** Si se cumplió. Ausente si está ignorada, si la rama no llegó a evaluarse o si el payload era una lista. */
+    paso?: boolean;
+    actual?: unknown;
+    esperado?: unknown;
+    /** Payload iterable: cuántos ítems la cumplieron, de cuántos. */
+    items?: {
+        total: number;
+        pasan: number;
+    };
+}
+/**
+ * - `casa`: se cumplió y es la que se tomó (la primera que casa gana).
+ * - `no-casa`: se evaluó y no se cumplió.
+ * - `sin-condiciones`: no tiene ninguna, y el conditional se la salta.
+ * - `no-evaluada`: una anterior ya había casado, así que ésta ni se miró.
+ */
+export type ResultadoDeRama = 'casa' | 'no-casa' | 'sin-condiciones' | 'no-evaluada';
+export interface RamaEvaluada {
+    id: string;
+    nombre: string;
+    modo: 'and' | 'or';
+    resultado: ResultadoDeRama;
+    condiciones: CondicionEvaluada[];
+    /** Payload iterable: cuántos ítems cumplieron la rama entera. */
+    items?: {
+        total: number;
+        pasan: number;
+    };
+}
+/** La decisión de un conditional, en el orden en que se evaluaron sus ramas. */
+export interface EvaluacionDeRamas {
+    ramas: RamaEvaluada[];
+    /** El id de la rama que ganó; `null` = ninguna, se fue por el `else`. */
+    ganadora: string | null;
 }

package/dist/servicios/index.d.ts

@@ -26,7 +26,7 @@
  * 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 type { FileRef, ChunkingStrategy, RunStepStatus, PasoEjecutado as PasoEjecutadoDelSdk, CondicionEvaluada, ResultadoDeRama, RamaEvaluada, EvaluacionDeRamas, VueltaDeBucle, } from './formas-compartidas';
 export * from './almacenes-vectoriales';
 export * from './aprobaciones-pendientes';
 export * from './avisos-en-vivo';

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

@@ -1,4 +1,5 @@
 import type { Types } from 'mongoose';
+import type { VueltaDeBucle } from './formas-compartidas';
 /**
  * Lo que un nodo le pide al motor de ejecución. Nada más.
  *
@@ -168,6 +169,13 @@ export interface ContextoDeCorrida {
      * detecta los ciclos de FlowLinks y aplica el `maxFlowCallDepth` del plan.
      */
     callStack?: string[];
+    /**
+     * La vuelta de cada bucle en el que se está, del de fuera al de dentro
+     * [2026-09-29]. La pone el bucle al despachar cada vuelta —a partir de su
+     * estado, no de lo que traiga el contexto—, y los pasos la guardan. Es
+     * JSON plano: cruza el cable tal cual.
+     */
+    pilaDeVueltas?: VueltaDeBucle[];
 }
 /** Una espera pendiente, de lo que el motor le lee. */
 export interface EsperaPendiente {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/platform-contracts",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Contratos compartidos entre los servicios de HostWebhook: addons del plan, identidad interna, y las formas que cruzan una frontera de red",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",