@futdevpro/fsm-dynamo 1.16.33 → 1.16.34

package/src/_models/data-models/errors.data-model.ts

@@ -1,176 +1,201 @@
-import { DyFM_DataModel_Params } from '../control-models/data-model-params.control-model';
-import { DyFM_ErrorLevel } from '../../_enums/error-level.enum';
-import { DyFM_ErrorStatus } from '../../_enums/error-status.enum';
-import { DyFM_Error } from '../control-models/error.control-model';
-import { DyFM_Metadata } from './metadata.data-model';
-
-
-export const DyFM_errorsFlag = 'DyFM-ERRORS-OBJECT';
-
-
-/**
- * Single fix-attempt entry on an error record. Append-only — every call to the
- * `recordFixAttempt` data-service method adds a new entry to `fixAttempts[]`.
- *
- * Intended use: after diagnosing the root cause of an error and shipping a fix,
- * mark the error with the hypothesis + target version. If a NEW occurrence of
- * the same error then arrives carrying a version >= this attempt's version,
- * the dedup branch of `recordError` flips `regressedAfterFix: true` — the
- * dashboard can highlight it as a failed hypothesis worth re-investigating.
- */
-export interface DyFM_Errors_FixAttempt {
-  /** When the fix was claimed. */
-  at: Date | string;
-  /** Issuer / username who claimed the fix. */
-  by: string;
-  /** The app version that contains the claimed fix (e.g. `01.15.117`). */
-  version: string;
-  /** Plain-text root-cause hypothesis that justified the fix. */
-  hypothesis: string;
-  /** Optional free-form notes attached to this fix attempt (links, context, follow-ups). */
-  notes?: string;
-}
-
-/**
- * This obj is the saved version of the DyFM_Error object.
- * It is used to store the error in the database and its statistics.
- * 
- * @example
- * ```ts
- * const errors: DyFM_Errors<DyFM_Error> = new DyFM_Errors({
- *   message: 'Error message',
- *   error: new DyFM_Error({
- *     message: 'Error message',
- *   }),
- * });
- * ```
- */
-export class DyFM_Errors<T_Error extends DyFM_Error> extends DyFM_Metadata {
-  readonly flag?: string = DyFM_errorsFlag;
-
-  source?: string;
-  issuer?: string;
-  username?: string;
-  /** In which system versions this error occurred. */
-  versions?: string[] = [];
-  localTime?: string;
-  region?: string;
-
-  message?: string;
-  exception?: string;
-  exceptionObj?: any;
-
-  stackTrace?: string[] = [];
-  error?: any;
-
-  count?: number = 1;
-  
-  d_error?: T_Error;
-
-  additionalContent?: any;
-
-  level?: DyFM_ErrorLevel;
-  priority?: number;
-  duplications?: DyFM_Errors<T_Error>[] = [];
-
-  /**
-   * Free-form osztaly-cimke a generic-application errors mellett. Tipikus
-   * ertekek: `'application'` (default), `'system-unreachable'`, `'build-failure'`,
-   * `'auth'`, `'db'`. A UI-szuro/tab itt szur. Optional + string (NEM enum),
-   * hogy minden host-app sajat kategoriai is additive-en bovithetok legyenek
-   * a bedrock medellenelkul.
-   */
-  category?: string;
-
-  // ─── Fix tracking (append-only audit + quick-access aliases) ────────────────
-
-  /**
-   * Lifecycle status. `active` for every new record; `fixed` after a claimed
-   * fix (`recordFixAttempt` / `resolveError`, record KEPT not deleted);
-   * `regressed` when `recordError` sees a recurrence with a version >= the last
-   * claimed-fix version (auto-reactivation); `investigating` set manually.
-   * Mirrors `regressedAfterFix` (kept for back-compat): `regressed` ⇔ `regressedAfterFix=true`.
-   */
-  status?: DyFM_ErrorStatus = DyFM_ErrorStatus.active;
-
-  /** Optional free-form notes captured on a soft-resolve (`resolveError`). */
-  resolutionNotes?: string;
-
-  /**
-   * Append-only audit log of fix attempts. New entries via `recordFixAttempt`
-   * on the data-service. Never overwritten / pruned — full hypothesis history
-   * stays available even when one hypothesis turns out to be wrong and the
-   * next attempt is logged.
-   */
-  fixAttempts?: DyFM_Errors_FixAttempt[] = [];
-
-  /** Convenience alias — last entry of `fixAttempts.at`. */
-  lastFixedAt?: Date | string;
-  /** Convenience alias — last entry of `fixAttempts.by`. */
-  lastFixedBy?: string;
-  /** Convenience alias — last entry of `fixAttempts.version`. */
-  lastFixedInVersion?: string;
-  /** Convenience alias — last entry of `fixAttempts.hypothesis`. */
-  lastFixHypothesis?: string;
-
-  /**
-   * Set to `true` in the `recordError` dedup branch when a NEW occurrence
-   * arrives carrying a `versions[0]` >= `lastFixedInVersion`. Indicates the
-   * most recent fix attempt did not actually fix the root cause — surface as
-   * a flag on the dashboard so the next investigator knows to dig deeper than
-   * "already fixed in vN".
-   */
-  regressedAfterFix?: boolean;
-
-  constructor(
-    set?: DyFM_Errors<T_Error>
-  ) {
-    super(set);
-    
-    if (set) {
-      Object.assign(this, set);
-    }
-  }
-}
-
-export const DyFM_errors_dataParams: DyFM_DataModel_Params<DyFM_Errors<DyFM_Error>> = 
-  new DyFM_DataModel_Params<DyFM_Errors<DyFM_Error>>({
-    dataName: 'errors',
-    properties: {
-      flag: { type: 'string' },
-
-      issuer: { type: 'string' },
-      username: { type: 'string' },
-      versions: { type: 'string[]' },
-
-      localTime: { type: 'string' },
-      region: { type: 'string' },
-
-      message: { type: 'string' },
-      exception: { type: 'string' },
-      exceptionObj: { type: 'any' },
-
-      stackTrace: { type: 'string[]' },
-      error: { type: 'any' },
-
-      count: { type: 'number' },
-
-      d_error: { type: 'DyFM_Error' },
-
-      additionalContent: { type: 'any' },
-
-      level: { type: 'DyFM_ErrorLevel' },
-      priority: { type: 'number' },
-      duplications: { type: 'DyNTS_Error[]' },
-      category: { type: 'string' },
-
-      status: { type: 'string' },
-      resolutionNotes: { type: 'string' },
-      fixAttempts: { type: 'any' },
-      lastFixedAt: { type: 'Date' },
-      lastFixedBy: { type: 'string' },
-      lastFixedInVersion: { type: 'string' },
-      lastFixHypothesis: { type: 'string' },
-      regressedAfterFix: { type: 'boolean' },
-    },
+import { DyFM_DataModel_Params } from '../control-models/data-model-params.control-model';
+import { DyFM_ErrorLevel } from '../../_enums/error-level.enum';
+import { DyFM_ErrorStatus } from '../../_enums/error-status.enum';
+import { DyFM_Error } from '../control-models/error.control-model';
+import { DyFM_Metadata } from './metadata.data-model';
+
+
+export const DyFM_errorsFlag = 'DyFM-ERRORS-OBJECT';
+
+
+/**
+ * Single fix-attempt entry on an error record. Append-only — every call to the
+ * `recordFixAttempt` data-service method adds a new entry to `fixAttempts[]`.
+ *
+ * Intended use: after diagnosing the root cause of an error and shipping a fix,
+ * mark the error with the hypothesis + target version. If a NEW occurrence of
+ * the same error then arrives carrying a version >= this attempt's version,
+ * the dedup branch of `recordError` flips `regressedAfterFix: true` — the
+ * dashboard can highlight it as a failed hypothesis worth re-investigating.
+ */
+export interface DyFM_Errors_FixAttempt {
+  /** When the fix was claimed. */
+  at: Date | string;
+  /** Issuer / username who claimed the fix. */
+  by: string;
+  /** The app version that contains the claimed fix (e.g. `01.15.117`). */
+  version: string;
+  /** Plain-text root-cause hypothesis that justified the fix. */
+  hypothesis: string;
+  /** Optional free-form notes attached to this fix attempt (links, context, follow-ups). */
+  notes?: string;
+}
+
+/**
+ * This obj is the saved version of the DyFM_Error object.
+ * It is used to store the error in the database and its statistics.
+ * 
+ * @example
+ * ```ts
+ * const errors: DyFM_Errors<DyFM_Error> = new DyFM_Errors({
+ *   message: 'Error message',
+ *   error: new DyFM_Error({
+ *     message: 'Error message',
+ *   }),
+ * });
+ * ```
+ */
+export class DyFM_Errors<T_Error extends DyFM_Error> extends DyFM_Metadata {
+  readonly flag?: string = DyFM_errorsFlag;
+
+  source?: string;
+  issuer?: string;
+  username?: string;
+  /** In which system versions this error occurred. */
+  versions?: string[] = [];
+  localTime?: string;
+  region?: string;
+
+  message?: string;
+  exception?: string;
+  exceptionObj?: any;
+
+  stackTrace?: string[] = [];
+  error?: any;
+
+  count?: number = 1;
+  
+  d_error?: T_Error;
+
+  additionalContent?: any;
+
+  level?: DyFM_ErrorLevel;
+  priority?: number;
+  duplications?: DyFM_Errors<T_Error>[] = [];
+
+  /**
+   * Free-form osztaly-cimke a generic-application errors mellett. Tipikus
+   * ertekek: `'application'` (default), `'system-unreachable'`, `'build-failure'`,
+   * `'auth'`, `'db'`. A UI-szuro/tab itt szur. Optional + string (NEM enum),
+   * hogy minden host-app sajat kategoriai is additive-en bovithetok legyenek
+   * a bedrock medellenelkul.
+   */
+  category?: string;
+
+  // ─── Fix tracking (append-only audit + quick-access aliases) ────────────────
+
+  /**
+   * Lifecycle status. `active` for every new record; `fixed` after a claimed
+   * fix (`recordFixAttempt` / `resolveError`, record KEPT not deleted);
+   * `regressed` when `recordError` sees a recurrence with a version >= the last
+   * claimed-fix version (auto-reactivation); `investigating` set manually.
+   * Mirrors `regressedAfterFix` (kept for back-compat): `regressed` ⇔ `regressedAfterFix=true`.
+   */
+  status?: DyFM_ErrorStatus = DyFM_ErrorStatus.active;
+
+  /** Optional free-form notes captured on a soft-resolve (`resolveError`). */
+  resolutionNotes?: string;
+
+  /**
+   * Append-only audit log of fix attempts. New entries via `recordFixAttempt`
+   * on the data-service. Never overwritten / pruned — full hypothesis history
+   * stays available even when one hypothesis turns out to be wrong and the
+   * next attempt is logged.
+   */
+  fixAttempts?: DyFM_Errors_FixAttempt[] = [];
+
+  /** Convenience alias — last entry of `fixAttempts.at`. */
+  lastFixedAt?: Date | string;
+  /** Convenience alias — last entry of `fixAttempts.by`. */
+  lastFixedBy?: string;
+  /** Convenience alias — last entry of `fixAttempts.version`. */
+  lastFixedInVersion?: string;
+  /** Convenience alias — last entry of `fixAttempts.hypothesis`. */
+  lastFixHypothesis?: string;
+
+  /**
+   * Set to `true` in the `recordError` dedup branch when a NEW occurrence
+   * arrives carrying a `versions[0]` >= `lastFixedInVersion`. Indicates the
+   * most recent fix attempt did not actually fix the root cause — surface as
+   * a flag on the dashboard so the next investigator knows to dig deeper than
+   * "already fixed in vN".
+   */
+  regressedAfterFix?: boolean;
+
+  /**
+   * A LEGUTOLSO elofordulas diagnosztikai kontextusa (es annak idopontja).
+   *
+   * MIERT KELL (2026-08-07, eles eset): a `recordError` dedup-aga csak `$inc`-el, ezert az
+   * `additionalContent` AZ ELSO elofordulasnal BEFAGY. Egy hosszu eletu hibanal ez azt jelenti,
+   * hogy a diagnosztika orokre a ho-napokkal ezelotti elso esethez tartozik — a MOSTANI hivorol
+   * semmit nem tudsz meg, es a kesobb bevezetett gazdagabb kontextus (pl. origin / referer /
+   * user-agent) SOHA nem jut el a rekordba.
+   *
+   * MERT ESET: az overseer `No authentication provided` rekordja 68 587 elofordulasnal tartott,
+   * es az `additionalContent`-je csak egy regi `endpointInfo`-t tartalmazott. A hivot igy CSAK a
+   * szerver-logbol lehetett volna azonositani — az viszont ~13 percenkent forog, egy loketszeru
+   * (1/perc) esemenynel pedig ez rendszeresen elvetette. A hibarekordbol NEM lehetett megmondani,
+   * KI hivja. (Hard rule: "minden hibanak debug-szintu detail-t kell hordoznia, hogy a hiba a
+   * hiba-detailekbol ONMAGABAN debuggolhato legyen".)
+   *
+   * Ez a mezo a dedup-agon FRISSUL, igy a rekord mindig a LEGFRISSEBB kontextust is hordozza —
+   * az `additionalContent` (elso elofordulas) pedig valtozatlan marad, tehat semmi nem vesz el.
+   */
+  lastOccurrenceContent?: any;
+  /** A `lastOccurrenceContent` rogzitesenek idopontja. */
+  lastOccurrenceAt?: Date | string;
+
+  constructor(
+    set?: DyFM_Errors<T_Error>
+  ) {
+    super(set);
+    
+    if (set) {
+      Object.assign(this, set);
+    }
+  }
+}
+
+export const DyFM_errors_dataParams: DyFM_DataModel_Params<DyFM_Errors<DyFM_Error>> = 
+  new DyFM_DataModel_Params<DyFM_Errors<DyFM_Error>>({
+    dataName: 'errors',
+    properties: {
+      flag: { type: 'string' },
+
+      issuer: { type: 'string' },
+      username: { type: 'string' },
+      versions: { type: 'string[]' },
+
+      localTime: { type: 'string' },
+      region: { type: 'string' },
+
+      message: { type: 'string' },
+      exception: { type: 'string' },
+      exceptionObj: { type: 'any' },
+
+      stackTrace: { type: 'string[]' },
+      error: { type: 'any' },
+
+      count: { type: 'number' },
+
+      d_error: { type: 'DyFM_Error' },
+
+      additionalContent: { type: 'any' },
+
+      level: { type: 'DyFM_ErrorLevel' },
+      priority: { type: 'number' },
+      duplications: { type: 'DyNTS_Error[]' },
+      category: { type: 'string' },
+
+      status: { type: 'string' },
+      resolutionNotes: { type: 'string' },
+      fixAttempts: { type: 'any' },
+      lastFixedAt: { type: 'Date' },
+      lastFixedBy: { type: 'string' },
+      lastFixedInVersion: { type: 'string' },
+      lastFixHypothesis: { type: 'string' },
+      regressedAfterFix: { type: 'boolean' },
+      lastOccurrenceContent: { type: 'any' },
+      lastOccurrenceAt: { type: 'Date' },
+    },
   });