@futdevpro/nts-dynamo 1.15.155 → 1.15.157

package/src/_models/control-models/endpoint-params.control-model.ts

@@ -1,14 +1,20 @@
 import { Request, Response } from 'express';
 
 import {
-  DyFM_AnyError,
-  DyFM_Array, DyFM_Endpoint_SettingsBase, DyFM_EnvironmentFlag, DyFM_Error, DyFM_getConstructionStackLocation, DyFM_HttpCallType, 
-  DyFM_Log, DyFM_Object
+  DyFM_AnyError, DyFM_Array, DyFM_Endpoint_SettingsBase, DyFM_Error, DyFM_getConstructionStackLocation,
+  DyFM_HttpCallType, DyFM_Log, DyFM_Object
 } from '@futdevpro/fsm-dynamo';
 
 import { DyNTS_global_settings } from '../../_collections/global-settings.const';
 import { DyNTS_ClientSafeError_Util } from '../../_collections/client-safe-error.util';
 import { DyNTS_RouteSecurity } from '../../_enums/route-security.enum';
+import {
+  DyNTS_SafeDiagnostic_ControlService
+} from '../../_modules/server/safe-diagnostic/safe-diagnostic.control-service';
+import {
+  DyNTS_SafeDiagnosticStage_Type
+} from '../../_modules/server/safe-diagnostic/safe-diagnostic-stage.type-enum';
+import { DyNTS_SafeDiagnostic_Interface } from '../../_modules/server/safe-diagnostic/safe-diagnostic.interface';
 import { DyNTS_GlobalService } from '../../_services/core/global.service';
 import { DyNTS_RequestHunter } from '../../_services/core/request-hunter.service';
 
@@ -167,12 +173,11 @@ export class DyNTS_Endpoint_Params<
       
       this.stackLocation = DyFM_getConstructionStackLocation();
     } catch (error) {
-      DyFM_Log.error(
-        `\nEndpoint params setup failed: name: '${set.name}' ` +
-          `(security: ${set.security}) endpoint: ${set.endpoint}` +
-        `\nERROR:` +
-        `\n`, error
-      );
+      DyNTS_SafeDiagnostic_ControlService.report({
+        code: 'DYNTS|ENDPOINT|CONSTRUCTION_FAILURE',
+        stage: DyNTS_SafeDiagnosticStage_Type.endpoint,
+        error: error,
+      });
 
       throw error;
     }
@@ -222,11 +227,14 @@ export class DyNTS_Endpoint_Params<
       // jegyzes. Reszletes indoklas: `DyNTS_RequestHunter`.
       const hunterId: number = DyNTS_RequestHunter.getInstance().begin(this.name);
       try {
-        let issuer: string;
         try {
           issuer = DyNTS_GlobalService?.getAuthService()?.getIssuerFromRequest(req);
         } catch (error) {
-          DyFM_Log.warn(DyFM_Error.getAnyMessage(error));
+          DyNTS_SafeDiagnostic_ControlService.report({
+            code: 'DYNTS|ENDPOINT|ISSUER_RESOLUTION_FAILURE',
+            stage: DyNTS_SafeDiagnosticStage_Type.endpoint,
+            error: error,
+          });
           issuer = 'unknown-issuer';
         }
         
@@ -294,7 +302,7 @@ export class DyNTS_Endpoint_Params<
           }
         }
       } catch (error) {
-        this.error(req, res, error, issuer);
+        await this.error(req, res, error, issuer);
       } finally {
         DyNTS_RequestHunter.getInstance().end(hunterId);
       }
@@ -336,100 +344,28 @@ export class DyNTS_Endpoint_Params<
     autoSecondTry?: boolean
   ): Promise<void> {
     try {
-      let msg: string = `Endpoint caught an error. '${this.name}' (${this.endpoint})`;
-
-      msg += this.getPathParamsLogContent(req);
-      if (error instanceof DyFM_Error) {
-        msg += `\n  ErrorCode: ${error._errorCode}`;
-      }
-      msg += `\n  error: "${(error as DyFM_Error)?._message ?? (error as Error)?.message}"`;
-      msg += '\n  at ' + this.stackLocation;
-
-      DyFM_Log.testError(msg);
-
-      if (
-        DyNTS_global_settings.log_settings.highDetailedLogs ||
-        !(error instanceof DyFM_Error)
-      ) {
-        DyFM_Log.H_error(
-          `Endpoint "${this.endpoint}" caught an error. (${this.name})`,
-          '\n    ERROR:', error
-        );
-      } else if (DyNTS_global_settings.log_settings.api_errors) {
-        error.logSimple(`Endpoint "${this.endpoint}" caught an error. (${this.name})`);
-      }
-
-      if ((error as DyFM_Error)?.flag?.includes('DYNAMO')) {
-        if (!(error as DyFM_Error).additionalContent) {
-          (error as DyFM_Error).additionalContent = {};
-        }
-        (error as DyFM_Error).additionalContent.endpointInfo = msg;
-      }
+      const status: number = DyNTS_Endpoint_Params.resolveErrorStatus(error);
+      const diagnostic: DyNTS_SafeDiagnostic_Interface = DyNTS_SafeDiagnostic_ControlService.report({
+        code: 'DYNTS|ENDPOINT|FAILURE',
+        stage: DyNTS_SafeDiagnosticStage_Type.endpoint,
+        error: error,
+        status: status,
+      });
 
-      // FR-071 (2026-06-06) — rich debug-descriptive request-context.
-      // Per memory [[feedback_rich_error_handling]] minden errornak debug-level
-      // descriptive-nek kell lennie + persisted to errors table. Az endpoint-
-      // params catch-blokkjaban minden errorhoz csatoljuk a request snapshot-ot
-      // (URL, method, headers KULCSAI ertek nelkul, query, params, origin,
-      // user-agent), igy a TEST environment-en a kliens-oldali fejleszto a
-      // response-bol latja MI hianyzott a request-bol, NEM csak az error-code-ot.
-      // Header-VALUEK nem szivarognak ki — csak a kulcs-listat es az auth-header
-      // alakjat (length + first 7 chars hogy lassek "Bearer "-rel kezd-e).
       try {
-        const headerKeys: string[] = Object.keys(req?.headers ?? {});
-        const authHeader: unknown = req?.headers?.['authorization'];
-        const authHeaderShape: string = typeof authHeader === 'string'
-          ? `present (len=${authHeader.length}, startsWith="${authHeader.substring(0, 7)}")`
-          : 'MISSING';
-        const requestSnapshot: Record<string, unknown> = {
-          url: req?.originalUrl ?? req?.url,
-          method: req?.method,
-          origin: req?.headers?.origin ?? null,
-          referer: req?.headers?.referer ?? null,
-          userAgent: req?.headers?.['user-agent'] ?? null,
-          hostHeader: req?.headers?.host ?? null,
-          headerKeyCount: headerKeys.length,
-          headerKeys: headerKeys.sort(),
-          hasAuthorizationKey: headerKeys.includes('authorization'),
-          authHeaderShape: authHeaderShape,
-          hasSecretKeyKey: headerKeys.includes('secret-key'),
-          hasAdminKeyKey: headerKeys.includes('x-admin-key'),
-          hasContentTypeKey: headerKeys.includes('content-type'),
-          params: req?.params,
-          query: req?.query,
-          remoteAddress: req?.ip ?? null,
-        };
-        if (error instanceof DyFM_Error) {
-          if (!(error as DyFM_Error).additionalContent) {
-            (error as DyFM_Error).additionalContent = {};
-          }
-          (error as DyFM_Error).additionalContent.requestDebug = requestSnapshot;
-        }
-        // Plusz: 1-soros debug log a server-side log-buffer-ben.
-        DyFM_Log.warn(
-          `[FR-071 req-debug] ${req?.method ?? '?'} ${req?.originalUrl ?? req?.url ?? '?'} ` +
-          `(endpoint=${this.name}, origin=${req?.headers?.origin ?? 'none'}, ` +
-          `auth=${headerKeys.includes('authorization') ? 'yes' : 'NO'}, ` +
-          `secretKey=${headerKeys.includes('secret-key') ? 'yes' : 'no'}, ` +
-          `adminKey=${headerKeys.includes('x-admin-key') ? 'yes' : 'no'}, ` +
-          `errorCode=${(error as DyFM_Error)?._errorCode ?? '(raw)'})`
+        await DyNTS_GlobalService.globalErrorHandler?.(
+          error,
+          req,
+          res,
+          issuer
         );
-      } catch /* (snapshotErr) */ {
-        // ha a snapshot kepzese maga is bukik, ne maszek bele az error-flow-ba.
+      } catch (handlerError) {
+        DyNTS_SafeDiagnostic_ControlService.report({
+          code: 'DYNTS|ENDPOINT|GLOBAL_HANDLER_FAILURE',
+          stage: DyNTS_SafeDiagnosticStage_Type.endpoint,
+          error: handlerError,
+        });
       }
-
-      await DyNTS_GlobalService.globalErrorHandler?.(
-        error, 
-        req, 
-        res, 
-        issuer
-      ).catch((err): void => {
-        DyFM_Log.warn(
-          'DyNTS_GlobalService.globalErrorHandler failed to handle error: ', 
-          err
-        );
-        DyFM_Log.warn('It will proceed as normal.');
-      });
       
       // FR-067 (2026-06-06): non-DyFM_Error wrap.
       // Korabban a plain Error / axios HTTP error nyersen ment kifele
@@ -442,25 +378,12 @@ export class DyNTS_Endpoint_Params<
       // betesszuk a DyFM_Error `___status` mezojebe, igy a kovetkezo blokk
       // mar konzekvensen olvasni tudja.
       if (!(error instanceof DyFM_Error)) {
-        const errAny: { statusCode?: unknown; status?: unknown; message?: string } =
-          error as { statusCode?: unknown; status?: unknown; message?: string };
-        const downstreamRaw: unknown = errAny?.statusCode ?? errAny?.status;
-        const downstreamStatus: number | undefined = typeof downstreamRaw === 'number'
-          ? downstreamRaw
-          : (typeof downstreamRaw === 'string' && downstreamRaw !== '' && !isNaN(Number(downstreamRaw)))
-            ? Number(downstreamRaw)
-            : undefined;
-        const wrapStatus: number = (
-          downstreamStatus !== undefined &&
-          downstreamStatus >= 100 &&
-          downstreamStatus <= 599
-        ) ? downstreamStatus : 500;
         error = new DyFM_Error({
-          error: error as Error,
-          message: errAny?.message ?? `Unhandled error in endpoint "${this.name}"`,
-          errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-EPP-${this.name ?? 'UNKNOWN'}`,
+          message: 'Unhandled endpoint failure.',
+          errorCode: this.getClientErrorCode(),
           userMessage: 'An internal error occurred.\nPlease contact the responsible development team.',
-          status: wrapStatus,
+          additionalContent: { diagnostic: diagnostic },
+          status: status,
         });
       }
 
@@ -513,20 +436,7 @@ export class DyNTS_Endpoint_Params<
       // `___status`-en kívül a `statusCode` (Express convention) es `status`
       // (axios / general HTTP) mezőket is. Igy a downstream HTTP-hivasok
       // (pl. axios-bol jovo error) helyes HTTP-status-szal továbbítódnak.
-      const errorAny: { statusCode?: unknown; status?: unknown } = error as { statusCode?: unknown; status?: unknown };
-      const resolvedStatusRaw: unknown = (error as DyFM_Error)?.___status
-        ?? errorAny?.statusCode
-        ?? errorAny?.status;
-      const resolvedStatus: number | null = typeof resolvedStatusRaw === 'number'
-        ? resolvedStatusRaw
-        : (typeof resolvedStatusRaw === 'string' && !isNaN(Number(resolvedStatusRaw)))
-          ? Number(resolvedStatusRaw)
-          : null;
-      if (resolvedStatus !== null && resolvedStatus >= 100 && resolvedStatus <= 599) {
-        res.status(resolvedStatus);
-      } else {
-        res.status(500);
-      }
+      res.status(DyNTS_Endpoint_Params.resolveErrorStatus(error));
 
       // Kliens-safe strip ENV-FÜGGETLENÜL (BFR-FDPAUTHSERVICE-002): a korábbi prod-only blokk a
       // test/dev környezetben TELJES DyFM-leaket hagyott (__localStack + ___systemVersion + issuer).
@@ -537,15 +447,8 @@ export class DyNTS_Endpoint_Params<
       res.send(clientSafeError);
 
       if (this.logRequest) {
-        DyFM_Log.error(
-          `  <<<=====   '${this.name}' error sent: ${(error as DyFM_Error)?._message ?? ''}`
-        );
-        if (this.logResponseContent) {
-          DyFM_Log.error(`              error response: ${DyNTS_Endpoint_Params.previewBody(clientSafeError)}`);
-        }
+        DyFM_Log.error('[DyNTS endpoint error response sent]', diagnostic);
       }
-
-      DyFM_Log.error('');
           
     } catch (errorLvl2) {
       this.multiLevelError(
@@ -571,33 +474,11 @@ export class DyNTS_Endpoint_Params<
       autoSecondTry: boolean
     }
   ): void {
-    if (DyNTS_global_settings.log_settings.highDetailedLogs) {
-      const msg = 
-        `\n\nDYNAMO MULTILEVEL ERROR:DyNTS_Endpoint_Params: error: ` +
-          `(${this.name}, ${this.endpoint})` +
-        `\n(DYNAMO MULTILEVEL ERROR means, that the ERROR HANDLING is ALSO FAILED, ` +
-          `and the error message was not sent.)` + 
-        `\nthisEndpointStackLocation: ${this.stackLocation}`;
-
-      if (errorLvl2 instanceof DyFM_Error) {
-        errorLvl2.logSimple(msg);
-      } else {
-        DyFM_Log.H_error(msg, '\nERROR:', errorLvl2, '\n');
-      }
-    } else {
-      const msg = 
-        `\n\nDYNAMO MULTILEVEL ERROR:DyNTS_Endpoint_Params: error: ` +
-          `(${this.name}, ${this.endpoint})` +
-        `\nthisEndpointStackLocation: ${this.stackLocation}` +
-        `\n(DYNAMO MULTILEVEL ERROR means, that the ERROR HANDLING is ALSO FAILED, ` +
-          `and the error message was not sent.)`;
-
-      if (errorLvl2 instanceof DyFM_Error) {
-        errorLvl2.logSimple(msg);
-      } else {
-        DyFM_Log.H_error(msg, '\nERROR:', errorLvl2, '\n');
-      }
-    }
+    DyNTS_SafeDiagnostic_ControlService.report({
+      code: 'DYNTS|ENDPOINT|ERROR_HANDLER_FAILURE',
+      stage: DyNTS_SafeDiagnosticStage_Type.endpoint,
+      error: errorLvl2,
+    });
 
     try {
       JSON.stringify(errorInputs.error);
@@ -608,8 +489,11 @@ export class DyNTS_Endpoint_Params<
       try {
         resolvedError = DyFM_Object.resolveCirculation(errorInputs.error);
       } catch (errorLvl3) {
-        DyFM_Log.error('  ...response object is not resolvable!');
-        DyFM_Log.error('  ...', errorLvl3);
+        DyNTS_SafeDiagnostic_ControlService.report({
+          code: 'DYNTS|ENDPOINT|CIRCULATION_RESOLUTION_FAILURE',
+          stage: DyNTS_SafeDiagnosticStage_Type.endpoint,
+          error: errorLvl3,
+        });
       }
       
       if (resolvedError) {
@@ -633,19 +517,46 @@ export class DyNTS_Endpoint_Params<
       }
     }
 
-    if (
-      DyNTS_global_settings.log_settings.highDetailedLogs ||
-      !(errorLvl2 instanceof DyFM_Error)
-    ) {
-      DyFM_Log.H_error(
-        `Endpoint "${this.endpoint}" caught an error and FAILED TO RESOLVE. (${this.name})`,
-        '\n    ERROR:', errorLvl2
-      );
-    } else {
-      errorLvl2.logSimple(
-        `Endpoint "${this.endpoint}" caught an error and FAILED TO RESOLVE. (${this.name})`
-      );
+  }
+
+  /** Resolves conventional HTTP status fields without inspecting raw error content. */
+  private static resolveErrorStatus(error: unknown): number {
+    try {
+      if (error === null || (typeof error !== 'object' && typeof error !== 'function')) {
+        return 500;
+      }
+
+      const statusRaw: unknown = Reflect.get(error, '___status')
+        ?? Reflect.get(error, 'statusCode')
+        ?? Reflect.get(error, 'status');
+      const status: number = typeof statusRaw === 'number' ? statusRaw : Number(statusRaw);
+
+      return Number.isInteger(status) && status >= 100 && status <= 599 ? status : 500;
+    } catch {
+      return 500;
+    }
+  }
+
+  /** Preserves the public error-code shape while excluding arbitrary endpoint-name characters. */
+  private getClientErrorCode(): string {
+    const systemCode: string = DyNTS_Endpoint_Params.sanitizeCodePart(
+      DyNTS_global_settings.systemShortCodeName,
+      'DYNTS'
+    );
+    const endpointCode: string = DyNTS_Endpoint_Params.sanitizeCodePart(this.name, 'UNKNOWN');
+
+    return `${systemCode}|DyNTS-EPP-${endpointCode}`;
+  }
+
+  /** Bounds developer-owned identifiers to the established error-code alphabet. */
+  private static sanitizeCodePart(value: unknown, fallback: string): string {
+    if (typeof value !== 'string') {
+      return fallback;
     }
+
+    const sanitized: string = value.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64);
+
+    return sanitized || fallback;
   }
 
   private getPathParamsLogContent(req: Request): string {

package/src/_models/interfaces/request-telemetry-settings.interface.ts

@@ -0,0 +1,9 @@
+/** Opt-in, content-free request telemetry settings for one Dynamo application. */
+export interface DyNTS_RequestTelemetry_Settings {
+  /** Enables correlation headers and event-driven aggregate metrics. Default: false. */
+  enabled?: boolean;
+  /** Maximum distinct declared route templates retained before overflow aggregation. Default: 128. */
+  maxRouteCardinality?: number;
+  /** Inclusive duration bucket upper bounds in milliseconds. Default: 25, 100, 250, 1000, 5000. */
+  durationBucketUpperBoundsMs?: number[];
+}

package/src/_models/interfaces/request-telemetry-snapshot.interface.ts

@@ -0,0 +1,30 @@
+/** One bounded duration bucket in the content-free request telemetry snapshot. */
+export interface DyNTS_RequestDurationBucket_Interface {
+  upperBoundMs: number | null;
+  count: number;
+}
+
+/** One declared route-template aggregate. No concrete URL or request value is retained. */
+export interface DyNTS_RequestRouteMetric_Interface {
+  method: string;
+  routeTemplate: string;
+  count: number;
+  abortedCount: number;
+  serverErrorCount: number;
+  totalDurationMs: number;
+  maxDurationMs: number;
+}
+
+/** Synchronous, immutable-by-copy snapshot of the event-driven request counters. */
+export interface DyNTS_RequestTelemetrySnapshot_Interface {
+  contractVersion: 'dynts-request-telemetry/1';
+  correlationHeader: 'X-Correlation-Id';
+  requestsStarted: number;
+  requestsCompleted: number;
+  requestsAborted: number;
+  inFlight: number;
+  droppedRouteTemplates: number;
+  statusClasses: Record<string, number>;
+  durationBuckets: DyNTS_RequestDurationBucket_Interface[];
+  routes: DyNTS_RequestRouteMetric_Interface[];
+}

package/src/_modules/server/safe-diagnostic/safe-diagnostic-stage.type-enum.ts

@@ -5,6 +5,7 @@ export enum DyNTS_SafeDiagnosticStage_Type {
   databaseConnect = 'database-connect',
   databaseRuntime = 'database-runtime',
   eventLoopDiagnostic = 'event-loop-diagnostic',
+  endpoint = 'endpoint',
   expressFallback = 'express-fallback',
   globalErrorHandler = 'global-error-handler',
   httpServer = 'http-server',

package/src/_services/core/request-telemetry.control-service.spec.ts

@@ -0,0 +1,217 @@
+import { EventEmitter } from 'events';
+import { NextFunction, Request, Response } from 'express';
+
+import {
+  DyNTS_RequestRouteMetric_Interface,
+  DyNTS_RequestTelemetrySnapshot_Interface
+} from '../../_models/interfaces/request-telemetry-snapshot.interface';
+import { DyNTS_RequestTelemetry_ControlService } from './request-telemetry.control-service';
+
+class ResponseStub extends EventEmitter {
+  public readonly headers: Record<string, string> = {};
+  private responseStatusCode: number = 200;
+
+  /** Returns the response status used by completion aggregation. */
+  public get statusCode(): number {
+    return this.responseStatusCode;
+  }
+
+  /** Updates the response status used by completion aggregation. */
+  public set statusCode(value: number) {
+    this.responseStatusCode = value;
+  }
+
+  /** Stores one response header for middleware assertions. */
+  public setHeader(name: string, value: string): void {
+    this.headers[name] = value;
+  }
+
+  /** Reads one stored response header for middleware composition. */
+  public getHeader(name: string): string | undefined {
+    return this.headers[name];
+  }
+}
+
+class ThrowingHeaderResponseStub extends ResponseStub {
+  /** Simulates a response implementation rejecting header mutation. */
+  public override setHeader(_name: string, _value: string): void {
+    void _name;
+    void _value;
+
+    throw new Error('simulated header failure');
+  }
+}
+
+class ThrowingStatusResponseStub extends ResponseStub {
+  /** Simulates a late response implementation failure after listener installation. */
+  public override get statusCode(): number { // eslint-disable-line @futdevpro/dynamo/no-getter-logic
+    throw new Error('simulated status failure');
+  }
+
+  /** Accepts setup writes while the read side remains deliberately unavailable. */
+  public override set statusCode(_value: number) {}
+}
+
+describe('| BFR-CTM-020 content-free request telemetry', (): void => {
+  const service: DyNTS_RequestTelemetry_ControlService = DyNTS_RequestTelemetry_ControlService.getInstance();
+
+  beforeEach((): void => service._resetForTesting());
+
+  it('| replaces caller correlation and counts finish exactly once', (): void => {
+    service.configure({ enabled: true, durationBucketUpperBoundsMs: [ 50 ], maxRouteCardinality: 4 });
+    const req: Request = createRequest('GET');
+    const res: ResponseStub = new ResponseStub();
+    const next: NextFunction = createNext();
+
+    service.createMiddleware()(req, response(res), next);
+    service.identifyRoute('/pipeline/:pipelineId')(req, response(res), next);
+    res.statusCode = 503;
+    res.emit('finish');
+    res.emit('close');
+
+    const snapshot: DyNTS_RequestTelemetrySnapshot_Interface = service.snapshot();
+
+    expect(res.headers['X-Correlation-Id']).toMatch(/^[0-9a-f-]{36}$/u);
+    expect(res.headers['X-Correlation-Id']).not.toBe('caller-value');
+    expect(res.headers['Access-Control-Expose-Headers']).toContain('X-Correlation-Id');
+    expect(snapshot.requestsStarted).toBe(1);
+    expect(snapshot.requestsCompleted).toBe(1);
+    expect(snapshot.requestsAborted).toBe(0);
+    expect(snapshot.inFlight).toBe(0);
+    expect(snapshot.statusClasses['5xx']).toBe(1);
+    expect(snapshot.routes).toEqual([ jasmine.objectContaining({
+      method: 'GET',
+      routeTemplate: '/pipeline/:pipelineId',
+      count: 1,
+      abortedCount: 0,
+      serverErrorCount: 1,
+    }) ]);
+    expect(service.getCorrelationId(req)).toBeUndefined();
+  });
+
+  it('| records close without finish as an abort and removes both listeners', (): void => {
+    service.configure({ enabled: true });
+    const req: Request = createRequest('POST');
+    const res: ResponseStub = new ResponseStub();
+
+    service.createMiddleware()(req, response(res), createNext());
+    expect(res.listenerCount('finish')).toBe(1);
+    expect(res.listenerCount('close')).toBe(1);
+    res.emit('close');
+
+    const snapshot: DyNTS_RequestTelemetrySnapshot_Interface = service.snapshot();
+
+    expect(snapshot.requestsAborted).toBe(1);
+    expect(snapshot.requestsCompleted).toBe(0);
+    expect(snapshot.inFlight).toBe(0);
+    expect(res.listenerCount('finish')).toBe(0);
+    expect(res.listenerCount('close')).toBe(0);
+  });
+
+  it('| caps declared route cardinality and never retains invalid route content', (): void => {
+    service.configure({ enabled: true, maxRouteCardinality: 1 });
+    completeRequest(service, '/first/:id');
+    completeRequest(service, '/second/:id');
+    completeRequest(service, '/unsafe?secret=:value');
+
+    const snapshot: DyNTS_RequestTelemetrySnapshot_Interface = service.snapshot();
+
+    expect(snapshot.droppedRouteTemplates).toBe(2);
+    expect(snapshot.routes.map(
+      (route: DyNTS_RequestRouteMetric_Interface): string => route.routeTemplate
+    )).toEqual([ '__other__', '/first/:id' ]);
+    expect(JSON.stringify(snapshot)).not.toContain('secret');
+    expect(snapshot.routes.length).toBe(2);
+  });
+
+  it('| caps distinct templates without collapsing allowed methods on one retained template', (): void => {
+    service.configure({ enabled: true, maxRouteCardinality: 1 });
+    completeRequest(service, '/pipeline/:id', 'GET');
+    completeRequest(service, '/pipeline/:id', 'POST');
+    completeRequest(service, '/another/:id', 'GET');
+
+    const snapshot: DyNTS_RequestTelemetrySnapshot_Interface = service.snapshot();
+
+    expect(snapshot.droppedRouteTemplates).toBe(1);
+    expect(snapshot.routes.map(
+      (route: DyNTS_RequestRouteMetric_Interface): string => `${route.method}:${route.routeTemplate}`
+    )).toEqual([ 'GET:__other__', 'GET:/pipeline/:id', 'POST:/pipeline/:id' ]);
+  });
+
+  it('| is a no-op while disabled', (): void => {
+    service.configure({ enabled: false });
+    const req: Request = createRequest('GET');
+    const res: ResponseStub = new ResponseStub();
+
+    service.createMiddleware()(req, response(res), createNext());
+
+    expect(res.headers['X-Correlation-Id']).toBeUndefined();
+    expect(res.listenerCount('finish')).toBe(0);
+    expect(service.snapshot().requestsStarted).toBe(0);
+  });
+
+  it('| cannot leak header setup failures or create phantom in-flight requests', (): void => {
+    service.configure({ enabled: true });
+    const req: Request = createRequest('GET');
+    const res: ThrowingHeaderResponseStub = new ThrowingHeaderResponseStub();
+
+    expect((): void => service.createMiddleware()(req, response(res), createNext())).not.toThrow();
+    expect(service.snapshot().requestsStarted).toBe(0);
+    expect(service.snapshot().inFlight).toBe(0);
+  });
+
+  it('| contains late telemetry failures without changing response lifecycle semantics', (): void => {
+    service.configure({ enabled: true });
+    const req: Request = createRequest('GET');
+    const res: ThrowingStatusResponseStub = new ThrowingStatusResponseStub();
+
+    service.createMiddleware()(req, response(res), createNext());
+
+    expect((): boolean => res.emit('finish')).not.toThrow();
+    expect(service.snapshot().inFlight).toBe(0);
+  });
+
+  it('| rejects conflicting or unbounded configuration with stable codes', (): void => {
+    expect((): void => service.configure({ enabled: true, maxRouteCardinality: 0 }))
+      .toThrowError('DYNTS|REQUEST_TELEMETRY|MAX_ROUTE_CARDINALITY_INVALID');
+    expect((): void => service.configure({ enabled: true, durationBucketUpperBoundsMs: [ 100, 50 ] }))
+      .toThrowError('DYNTS|REQUEST_TELEMETRY|DURATION_BUCKETS_INVALID');
+
+    service.configure({ enabled: true });
+    expect((): void => service.configure({ enabled: true, maxRouteCardinality: 5 }))
+      .toThrowError('DYNTS|REQUEST_TELEMETRY|CONFIGURATION_CONFLICT');
+  });
+});
+
+function completeRequest(
+  service: DyNTS_RequestTelemetry_ControlService,
+  routeTemplate: string,
+  method: string = 'GET'
+): void {
+  const req: Request = createRequest(method);
+  const res: ResponseStub = new ResponseStub();
+  const next: NextFunction = createNext();
+
+  service.createMiddleware()(req, response(res), next);
+  service.identifyRoute(routeTemplate)(req, response(res), next);
+  res.emit('finish');
+}
+
+function createRequest(method: string): Request {
+  // Express's runtime object is intentionally narrowed to fields the middleware is allowed to read.
+  // eslint-disable-next-line @futdevpro/dynamo/no-as-cast
+  return { method: method, headers: { 'x-correlation-id': 'caller-value' } } as unknown as Request;
+}
+
+function response(res: ResponseStub): Response {
+  // The stub implements the exact response lifecycle/header surface used by this middleware.
+  // eslint-disable-next-line @futdevpro/dynamo/no-as-cast
+  return res as unknown as Response;
+}
+
+function createNext(): NextFunction {
+  /** Deliberately empty Express continuation used by the isolated middleware tests. */
+  const next: NextFunction = (): void => undefined;
+
+  return next;
+}