@hostwebhook/platform-contracts 0.13.0 → 0.14.0

package/dist/servicios/telemetria.d.ts

@@ -36,9 +36,16 @@
  * ## Los campos son los que se usan
  *
  * El esquema `TelemetryLog` tiene ~20 campos. Se contaron los que aparecen de
- * verdad en las 67 llamadas de `nodes/` y las 53 de `common/`: son quince.
- * Fuera quedan `timestamp` —lo pone el gateway si falta—, `correlationId` y
- * los dos de voz, que nadie de este lado escribe.
+ * verdad en las 67 llamadas de `nodes/` y las 53 de `common/`: eran quince.
+ * Fuera quedaron `timestamp` —lo ponía el gateway si faltaba—, `correlationId`
+ * y los dos de voz, porque **nadie de este lado los escribía**.
+ *
+ * ⚠️ Eso era una MEDIDA, no un principio, y caducó. Hoy el split sella su
+ * propia hora —su fila se escribe cuando termina todo su abanico, así que con
+ * la hora de escritura la corrida se lee al revés— y el merge, el split y los
+ * triggers necesitan decir a qué corrida pertenecen. Así que `timestamp` y
+ * `correlationId` entran, y suben la cuenta a diecisiete. Los dos de voz
+ * siguen fuera: eso no ha cambiado.
  *
  * ## Cómo viaja
  *
@@ -56,9 +63,21 @@ export type NivelDeRegistro = 'info' | 'warn' | 'error' | 'debug';
 /**
  * Una fila del registro.
  *
- * ⚠️ Los quince campos MEDIDOS, ni uno más. Si hace falta otro, se añade
+ * ⚠️ Los diecisiete campos MEDIDOS, ni uno más. Si hace falta otro, se añade
  * aquí: tsc rechaza una clave desconocida en un literal, así que no se puede
  * colar por accidente.
+ *
+ * 🔥 Y esa promesa tenía una fuga. `correlationId` y `timestamp` ya viajaban
+ * SIN declarar, colados por un *spread* —`...(cond ? { timestamp } : {})`—,
+ * que TypeScript no somete al chequeo de propiedades excedentes. O sea que el
+ * tipo ni los prohibía ni los garantizaba, y quien leyera este contrato no
+ * podía saber que existían.
+ *
+ * El daño se midió en producción: `TelemetryService.runs()` agrupa una corrida
+ * por `correlationId`, y de las catorce filas de una corrida real SEIS no lo
+ * llevaban. No salían en su detalle ni se podían filtrar por ella. La causa no
+ * era el olvido de quien emite: era que **el tipo lo impedía**, así que al
+ * añadirlo en un literal el build se caía con TS2353.
  */
 export interface EntradaDeTelemetria {
     organizationId: string;
@@ -78,6 +97,27 @@ export interface EntradaDeTelemetria {
     statusCode?: number;
     success?: boolean;
     metadata?: Record<string, unknown>;
+    /**
+     * La corrida a la que pertenece esta fila.
+     *
+     * Es lo que agrupa un flujo entero: `TelemetryService.runs()` DESCARTA las
+     * filas que no lo traen, así que una emisión sin él no cuenta como paso de
+     * su corrida por muy correcta que sea.
+     *
+     * ⚠️ Va aquí y no dentro de `metadata`. El campo de primer nivel es el que
+     * está indexado y el que mira la consulta; guardarlo en la metadata es
+     * tenerlo y no tenerlo — pasó, y por eso está dicho.
+     */
+    correlationId?: string;
+    /**
+     * Cuándo ocurrió lo que esta fila cuenta.
+     *
+     * Sin él, quien escribe pone la hora de la ESCRITURA. Casi siempre da igual
+     * —se escribe al instante— pero no cuando un nodo reparte trabajo y su fila
+     * se escribe al terminar todo lo que colgaba de él: entonces aparece la
+     * última, después de sus propios hijos, y la corrida se lee al revés.
+     */
+    timestamp?: Date;
 }
 /** Apuntar en el registro, y preguntarle a la recuperación de caídas. */
 export interface Telemetria {

package/dist/servicios/telemetria.js

@@ -37,9 +37,16 @@
  * ## Los campos son los que se usan
  *
  * El esquema `TelemetryLog` tiene ~20 campos. Se contaron los que aparecen de
- * verdad en las 67 llamadas de `nodes/` y las 53 de `common/`: son quince.
- * Fuera quedan `timestamp` —lo pone el gateway si falta—, `correlationId` y
- * los dos de voz, que nadie de este lado escribe.
+ * verdad en las 67 llamadas de `nodes/` y las 53 de `common/`: eran quince.
+ * Fuera quedaron `timestamp` —lo ponía el gateway si faltaba—, `correlationId`
+ * y los dos de voz, porque **nadie de este lado los escribía**.
+ *
+ * ⚠️ Eso era una MEDIDA, no un principio, y caducó. Hoy el split sella su
+ * propia hora —su fila se escribe cuando termina todo su abanico, así que con
+ * la hora de escritura la corrida se lee al revés— y el merge, el split y los
+ * triggers necesitan decir a qué corrida pertenecen. Así que `timestamp` y
+ * `correlationId` entran, y suben la cuenta a diecisiete. Los dos de voz
+ * siguen fuera: eso no ha cambiado.
  *
  * ## Cómo viaja
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/platform-contracts",
-  "version": "0.13.0",
+  "version": "0.14.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",