@futdevpro/fsm-dynamo 1.15.13 → 1.15.15

package/src/_collections/utils/extract-error-message.util.spec.ts

@@ -0,0 +1,204 @@
+import { DyFM_Error } from '../../_models/control-models/error.control-model';
+import {
+  DyFM_extractErrorMessage,
+  DyFM_formatError,
+  DyFM_registerMalformedErrorSink,
+  DyFM_reportMalformedError,
+} from './extract-error-message.util';
+
+
+/**
+ * FR-015-P0-fix — DyFM_extractErrorMessage specs.
+ *
+ * Coverage:
+ *   - DyFM_Error with __userMessage / _message / both
+ *   - HttpErrorResponse-shaped (status + statusText + error body)
+ *   - Plain Error.message
+ *   - String input
+ *   - null / undefined → fallback (never 'undefined undefined')
+ *   - Empty object → 'Malformed error: {}' OR fallback (depending on json)
+ *   - Circular reference handled (no infinite loop / no crash)
+ *   - prefix option
+ *   - includeHttpStatus toggle
+ *   - DyFM_formatError convenience wrapper
+ *   - DyFM_reportMalformedError sink registration
+ *
+ * MUST never emit:
+ *   - literal 'undefined' anywhere in the returned string
+ *   - '[object Object]'
+ *   - bare empty string
+ */
+describe('| DyFM_extractErrorMessage', (): void => {
+
+  describe('| DyFM_Error inputs', (): void => {
+    it('| uses __userMessage when present', (): void => {
+      const err: DyFM_Error = new DyFM_Error({
+        status: 401,
+        message: 'Internal debug',
+        userMessage: 'Bad credentials',
+        errorCode: 'AUTH-001',
+      });
+      // userMessage from settings maps to __userMessage on the DyFM_Error instance
+      // (deprecated but still copied).
+      const result: string = DyFM_extractErrorMessage(err);
+      expect(result).toContain('Bad credentials');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| falls back to _message when no __userMessage', (): void => {
+      const err: DyFM_Error = new DyFM_Error({
+        status: 500,
+        message: 'Database connection lost',
+        errorCode: 'DB-001',
+      });
+      const result: string = DyFM_extractErrorMessage(err);
+      expect(result).toContain('Database connection lost');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| appends HTTP status when present', (): void => {
+      const err: DyFM_Error = new DyFM_Error({
+        status: 401,
+        message: 'Token expired',
+        errorCode: 'AUTH-002',
+      });
+      const result: string = DyFM_extractErrorMessage(err);
+      expect(result).toContain('Token expired');
+      expect(result).toContain('401');
+    });
+  });
+
+  describe('| HttpErrorResponse-shaped inputs', (): void => {
+    it('| extracts from nested .error.__userMessage', (): void => {
+      const httpErr: object = {
+        status: 401,
+        statusText: 'Unauthorized',
+        error: {
+          __userMessage: 'Invalid username or password',
+          _errorCode: 'FAS-ACS-LOG1',
+        },
+      };
+      const result: string = DyFM_extractErrorMessage(httpErr);
+      expect(result).toContain('Invalid username or password');
+      expect(result).toContain('401');
+      expect(result).toContain('Unauthorized');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| extracts from nested .error.message (no DyFM extras)', (): void => {
+      const httpErr: object = {
+        status: 500,
+        statusText: 'Internal Server Error',
+        error: { message: 'ECONNREFUSED' },
+      };
+      const result: string = DyFM_extractErrorMessage(httpErr);
+      expect(result).toContain('ECONNREFUSED');
+      expect(result).toContain('500');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| status without statusText still rendered cleanly', (): void => {
+      const httpErr: object = {
+        status: 502,
+        error: { __userMessage: 'Upstream down' },
+      };
+      const result: string = DyFM_extractErrorMessage(httpErr);
+      expect(result).toContain('Upstream down');
+      expect(result).toContain('502');
+      expect(result).not.toContain('undefined');
+    });
+  });
+
+  describe('| primitive + edge inputs (the "undefined undefined" guard)', (): void => {
+    it('| null → fallback, never literal "undefined"', (): void => {
+      const result: string = DyFM_extractErrorMessage(null);
+      expect(result).not.toContain('undefined');
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('| undefined → fallback', (): void => {
+      const result: string = DyFM_extractErrorMessage(undefined);
+      expect(result).not.toContain('undefined');
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('| string input returned as-is', (): void => {
+      const result: string = DyFM_extractErrorMessage('Network unreachable');
+      expect(result).toBe('Network unreachable');
+    });
+
+    it('| plain Error.message', (): void => {
+      const result: string = DyFM_extractErrorMessage(new Error('boom'));
+      expect(result).toContain('boom');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| empty object → "Malformed error: {}" or fallback, NEVER bare undefined', (): void => {
+      const result: string = DyFM_extractErrorMessage({});
+      expect(result.length).toBeGreaterThan(0);
+      expect(result).not.toContain('undefined undefined');
+      // Either Malformed-error report or fallback — both are acceptable.
+    });
+
+    it('| HttpErrorResponse with ALL undefined fields → fallback, never literal "undefined undefined"', (): void => {
+      // This is the EXACT shape that produced the bug today:
+      // errorRes?.status, errorRes?.error?.status, errorRes?.statusText,
+      // errorRes?.error?.statusText all undefined.
+      const httpErr: object = { error: {} };
+      const result: string = DyFM_extractErrorMessage(httpErr, { prefix: 'Login' });
+      expect(result.startsWith('Login:')).toBeTrue();
+      expect(result).not.toContain('undefined');
+      expect(result).not.toContain('[object Object]');
+    });
+  });
+
+  describe('| circular reference safety', (): void => {
+    it('| does not crash + does not loop', (): void => {
+      const a: { name: string; self?: object } = { name: 'a' };
+      a.self = a;
+      const result: string = DyFM_extractErrorMessage(a);
+      expect(result.length).toBeGreaterThan(0);
+      expect(result).not.toContain('undefined');
+    });
+  });
+
+  describe('| prefix + includeHttpStatus options', (): void => {
+    it('| prefix prepends with ": "', (): void => {
+      const result: string = DyFM_extractErrorMessage('boom', { prefix: 'Login' });
+      expect(result).toBe('Login: boom');
+    });
+
+    it('| includeHttpStatus=false skips the (HTTP …) suffix', (): void => {
+      const httpErr: object = { status: 500, statusText: 'X', error: { message: 'm' } };
+      const result: string = DyFM_extractErrorMessage(httpErr, { includeHttpStatus: false });
+      expect(result).toContain('m');
+      expect(result).not.toContain('HTTP');
+    });
+
+    it('| custom fallback honored', (): void => {
+      const result: string = DyFM_extractErrorMessage(null, { fallback: 'Custom retry message' });
+      expect(result).toContain('Custom retry message');
+    });
+  });
+
+  describe('| DyFM_formatError convenience wrapper', (): void => {
+    it('| applies prefix', (): void => {
+      const result: string = DyFM_formatError('boom', 'Register');
+      expect(result).toBe('Register: boom');
+    });
+  });
+
+  describe('| DyFM_reportMalformedError sink', (): void => {
+    it('| calls registered sink with err + context', (): void => {
+      const calls: Array<{ err: unknown; context?: string }> = [];
+      DyFM_registerMalformedErrorSink((err: unknown, context?: string): void => {
+        calls.push({ err: err, context: context });
+      });
+      DyFM_reportMalformedError({ weirdShape: true }, 'login-flow');
+      expect(calls.length).toBe(1);
+      expect(calls[0].context).toBe('login-flow');
+      // Reset sink (no public unregister; pass an explicit no-op for cleanup).
+      DyFM_registerMalformedErrorSink((): void => { /* no-op */ });
+    });
+  });
+});

package/src/_collections/utils/extract-error-message.util.ts

@@ -0,0 +1,223 @@
+import { DyFM_AnyError, DyFM_Error } from '../../_models/control-models/error.control-model';
+
+
+/**
+ * Options for `DyFM_extractErrorMessage`.
+ */
+export interface DyFM_ExtractErrorMessage_Options {
+  /**
+   * Optional prefix prepended to the result with ': '. e.g. `prefix: 'Login'`
+   * → `'Login: <message>'`. Useful for distinguishing the UI surface.
+   */
+  prefix?: string;
+
+  /**
+   * Fallback string when no usable message can be extracted. Defaults to
+   * a human-readable diagnostic that mentions checking server logs.
+   */
+  fallback?: string;
+
+  /**
+   * When `true`, the returned string includes HTTP status + statusText after
+   * the main message (in parens) for HTTP errors. Default: `true`.
+   */
+  includeHttpStatus?: boolean;
+}
+
+
+/**
+ * Universal error → human-readable string extractor. **Never** returns the
+ * literal string `'undefined'` (or `'undefined undefined'`), `'[object Object]'`,
+ * or any other JS-rendering artifact. Walks the full DyFM_Error pipeline plus
+ * common Angular HttpErrorResponse + plain Error shapes, falling back to a
+ * meaningful diagnostic string when the input is malformed.
+ *
+ * Order of attempts (first non-empty wins):
+ *   1. `err.__userMessage` (DyFM_Error admin-actionable user message)
+ *   2. `err._message` (DyFM_Error aggregated debug message)
+ *   3. `err.message` (plain Error.message)
+ *   4. `err.userMessage` (deprecated DyFM_Error_Settings field, still seen
+ *      on some payloads)
+ *   5. `err.error.__userMessage` (HttpErrorResponse wrapping a DyFM_Error in
+ *      its body)
+ *   6. `err.error._message`
+ *   7. `err.error.message`
+ *   8. `err.error.userMessage`
+ *   9. If `err` itself is a string, use as-is
+ *  10. JSON-stringified payload (circular-safe; first 200 chars) as a last
+ *      resort, prefixed with 'Malformed error: '
+ *  11. `options.fallback` (or its default)
+ *
+ * When `includeHttpStatus` is true (default) and the input looks like a
+ * HttpErrorResponse, the status + statusText are appended in parens: e.g.
+ * `'Bad credentials (HTTP 401 Unauthorized)'`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await auth_CS.login(account);
+ * } catch (err) {
+ *   this.formError = DyFM_extractErrorMessage(err, { prefix: 'Login' });
+ *   // → 'Login: Bad credentials (HTTP 401 Unauthorized)'
+ *   //   OR
+ *   // → 'Login: Network unreachable — check connection. Server logs may have detail.'
+ *   //   never 'Login: undefined undefined'
+ * }
+ * ```
+ */
+export function DyFM_extractErrorMessage(
+  err: DyFM_AnyError | unknown,
+  options?: DyFM_ExtractErrorMessage_Options,
+): string {
+  const includeHttpStatus: boolean = options?.includeHttpStatus !== false;
+  const fallback: string = options?.fallback
+    ?? 'Unexpected error (no detail in payload — check server logs).';
+  const prefix: string = options?.prefix ? `${options.prefix}: ` : '';
+
+  // Null/undefined/empty
+  if (err === null || err === undefined) {
+    return `${prefix}${fallback}`;
+  }
+
+  // String → use as-is
+  if (typeof err === 'string') {
+    return `${prefix}${err}`;
+  }
+
+  // Walk the candidate fields in order. Cast to any to access optional
+  // properties without forcing each branch into a separate type guard.
+  const e: any = err as any;
+  const innerError: any = e?.error;
+
+  const candidate: string | undefined =
+       _nonEmptyString(e?.__userMessage)
+    ?? _nonEmptyString(e?._message)
+    ?? _nonEmptyString(e?.message)
+    ?? _nonEmptyString(e?.userMessage)
+    ?? _nonEmptyString(innerError?.__userMessage)
+    ?? _nonEmptyString(innerError?._message)
+    ?? _nonEmptyString(innerError?.message)
+    ?? _nonEmptyString(innerError?.userMessage);
+
+  // HTTP status suffix (always-on by default)
+  const status: number | string | undefined =
+       e?.___status
+    ?? e?.status
+    ?? innerError?.___status
+    ?? innerError?.status;
+  const statusText: string | undefined =
+       _nonEmptyString(e?.statusText)
+    ?? _nonEmptyString(innerError?.statusText);
+  const httpSuffix: string = (includeHttpStatus && (status !== undefined || statusText !== undefined))
+    ? ` (HTTP ${status ?? '?'}${statusText ? ' ' + statusText : ''})`
+    : '';
+
+  if (candidate !== undefined) {
+    return `${prefix}${candidate}${httpSuffix}`;
+  }
+
+  // No usable text field. Try a JSON-stringify of the raw payload (circular-safe).
+  const jsonAttempt: string | undefined = _safeJsonStringify(err);
+  if (jsonAttempt !== undefined && jsonAttempt !== '{}' && jsonAttempt !== '[]') {
+    const trimmed: string = jsonAttempt.length > 200
+      ? jsonAttempt.slice(0, 200) + '…'
+      : jsonAttempt;
+    return `${prefix}Malformed error: ${trimmed}${httpSuffix}`;
+  }
+
+  // Total fallback.
+  return `${prefix}${fallback}${httpSuffix}`;
+}
+
+
+/**
+ * Returns the value if it's a non-empty string, else undefined.
+ * Trims and treats whitespace-only as empty. Internal helper.
+ */
+function _nonEmptyString(v: unknown): string | undefined {
+  if (typeof v !== 'string') { return undefined; }
+  const trimmed: string = v.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+
+/**
+ * JSON.stringify wrapper that survives circular references + non-serializable
+ * values. Returns undefined if even the safe fallback fails (e.g. a Proxy
+ * whose getter throws).
+ */
+function _safeJsonStringify(v: unknown): string | undefined {
+  try {
+    const seen: WeakSet<object> = new WeakSet<object>();
+    return JSON.stringify(v, (_key: string, value: unknown): unknown => {
+      if (typeof value === 'object' && value !== null) {
+        if (seen.has(value as object)) { return '[Circular]'; }
+        seen.add(value as object);
+      }
+      if (typeof value === 'function') { return '[Function]'; }
+      if (typeof value === 'undefined') { return '[undefined]'; }
+      return value;
+    });
+  } catch {
+    try { return String(v); } catch { return undefined; }
+  }
+}
+
+
+/**
+ * Convenience: same as DyFM_extractErrorMessage but always includes a default
+ * prefix derived from the calling context, useful for adding diagnostic
+ * breadcrumbs without per-call boilerplate.
+ */
+export function DyFM_formatError(
+  err: DyFM_AnyError | unknown,
+  prefix: string,
+): string {
+  return DyFM_extractErrorMessage(err, { prefix: prefix });
+}
+
+
+/**
+ * Reports a raw error payload via the universal client-error capture system
+ * (FR-029-style). Implementation is delegated to a consumer-registered
+ * handler so dynamo-fsm stays Angular-agnostic; if no handler is registered
+ * the error is logged via `DyFM_Log.error` (which is the default no-op-safe
+ * sink). Consumers (e.g. A_ErrorHandler_ControlService) call
+ * `DyFM_registerMalformedErrorSink(fn)` once at bootstrap.
+ *
+ * The intent: when DyFM_extractErrorMessage falls back to 'Malformed error:'
+ * or the generic fallback, the raw payload should also be captured for
+ * post-mortem analysis (server error-log via FR-029 pipeline).
+ */
+let _malformedErrorSink: ((err: unknown, context?: string) => void) | undefined;
+
+export function DyFM_registerMalformedErrorSink(
+  fn: (err: unknown, context?: string) => void,
+): void {
+  _malformedErrorSink = fn;
+}
+
+export function DyFM_reportMalformedError(
+  err: unknown,
+  context?: string,
+): void {
+  if (_malformedErrorSink !== undefined) {
+    try {
+      _malformedErrorSink(err, context);
+      return;
+    } catch {
+      /* sink threw — fall through to default */
+    }
+  }
+  // Default: best-effort console.error wrapped in DyFM_Error for stack capture.
+  try {
+    // Lazy require to avoid a hard cycle through error.control-model -> log.util.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { DyFM_Log }: { DyFM_Log: { error(msg: string, ...args: unknown[]): void } } =
+      require('./log.util');
+    DyFM_Log.error(`[DyFM_reportMalformedError] ${context ?? 'unknown context'}`, err);
+  } catch {
+    // Last-ditch — should never happen since log.util has no further deps.
+    /* swallow */
+  }
+}

package/src/_collections/utils/object.util.spec.ts

@@ -114,7 +114,7 @@ describe('| DyFM_Object', () => {
       expect(result).toEqual(expected);
     });
 
-    xit('should resolve circular references in data', () => {
+    xit('should resolve self-circular root reference', () => {
       const obj: any = {};
       obj.self = obj;
       const expected = { self: 'CIRCULATION:ROOT;Object.self' };

package/src/_collections/utils/require-env.util.spec.ts

@@ -0,0 +1,231 @@
+import { DyFM_global_settings } from '../constants/global-settings.const';
+import { DyFM_Error } from '../../_models/control-models/error.control-model';
+import { DyFM_requireEnv } from './require-env.util';
+
+
+/**
+ * FR-015 Phase 2 Wave 0 — DyFM_requireEnv specs.
+ *
+ * Coverage:
+ *   - Node path: returns process.env value when set
+ *   - Browser path: returns DyFM_global_settings.envOverrides value when
+ *     process.env is unset
+ *   - Fallback path: returns options.fallback when both above unset
+ *   - Throw path: structured DyFM_Error when nothing resolves and no
+ *     fallback. Verifies errorCode, message contains the env-var name +
+ *     deploy-target checklist, userMessage is admin-actionable,
+ *     issuerService matches.
+ *   - Override priority: process.env wins over envOverrides; envOverrides
+ *     wins over fallback.
+ */
+
+
+/**
+ * Cleans the test fixture between specs so leak-state from one test doesn't
+ * pollute another. We touch the live `DyFM_global_settings.envOverrides`
+ * because the spec exercises the same surface the production code reads.
+ */
+function clearOverrides(): void {
+  DyFM_global_settings.envOverrides = undefined;
+}
+
+
+describe('| DyFM_requireEnv', (): void => {
+
+  afterEach((): void => {
+    clearOverrides();
+    delete process.env['DyFM_TEST_REQUIRE_ENV_KEY'];
+    delete process.env['DyFM_TEST_REQUIRE_ENV_OTHER'];
+  });
+
+
+  describe('| Node path (process.env)', (): void => {
+    it('| returns process.env value when set', (): void => {
+      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = 'node-value';
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-001',
+        issuerService: 'spec',
+      });
+      expect(value).toBe('node-value');
+    });
+
+    it('| empty-string process.env value is treated as unset', (): void => {
+      // Truthy guard — empty string means "not configured".
+      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = '';
+      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'browser-value' };
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-002',
+        issuerService: 'spec',
+      });
+      expect(value).toBe('browser-value');
+    });
+  });
+
+
+  describe('| browser path (envOverrides)', (): void => {
+    it('| returns envOverrides value when process.env unset', (): void => {
+      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'browser-value' };
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-003',
+        issuerService: 'spec',
+      });
+      expect(value).toBe('browser-value');
+    });
+
+    it('| handles other entries in the same map without interference', (): void => {
+      DyFM_global_settings.envOverrides = {
+        'DyFM_TEST_REQUIRE_ENV_KEY':   'value-a',
+        'DyFM_TEST_REQUIRE_ENV_OTHER': 'value-b',
+      };
+      expect(DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', { errorCode: 'X', issuerService: 's' }))
+        .toBe('value-a');
+      expect(DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_OTHER', { errorCode: 'X', issuerService: 's' }))
+        .toBe('value-b');
+    });
+  });
+
+
+  describe('| fallback path', (): void => {
+    it('| returns fallback when neither process.env nor envOverrides resolves', (): void => {
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-004',
+        issuerService: 'spec',
+        fallback: 'fallback-value',
+      });
+      expect(value).toBe('fallback-value');
+    });
+
+    it('| empty-string fallback is honored (explicit empty intent)', (): void => {
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-005',
+        issuerService: 'spec',
+        fallback: '',
+      });
+      expect(value).toBe('');
+    });
+  });
+
+
+  describe('| throw path — rich DyFM_Error', (): void => {
+    it('| throws DyFM_Error when nothing resolves and no fallback', (): void => {
+      let caught: unknown = null;
+      try {
+        DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+          errorCode: 'TEST-MISSING-001',
+          issuerService: 'dynamo-fsm-spec',
+        });
+      } catch (error: unknown) {
+        caught = error;
+      }
+      expect(caught).toBeInstanceOf(DyFM_Error);
+    });
+
+    it('| error has the caller-supplied errorCode', (): void => {
+      try {
+        DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+          errorCode: 'CUSTOM-CODE-XYZ',
+          issuerService: 's',
+        });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err._errorCode).toBe('CUSTOM-CODE-XYZ');
+        // Also present in the aggregated _errorCodes list.
+        expect(err._errorCodes).toContain('CUSTOM-CODE-XYZ');
+      }
+    });
+
+    it('| error has status 500 (config error)', (): void => {
+      try {
+        DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+          errorCode: 'C', issuerService: 's',
+        });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err.___status).toBe(500);
+      }
+    });
+
+    it('| error message names the env-var + lists deploy targets', (): void => {
+      try {
+        DyFM_requireEnv('SOME_SPECIFIC_VAR_NAME', {
+          errorCode: 'C', issuerService: 's',
+        });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        const msg: string = err._message || '';
+        // Names the specific var
+        expect(msg).toContain('SOME_SPECIFIC_VAR_NAME');
+        // Lists each deploy target so an operator knows where to look
+        expect(msg).toContain('host .env');
+        expect(msg).toContain('docker-compose');
+        expect(msg).toContain('Overseer');
+        expect(msg).toContain('environment.ts');
+      }
+    });
+
+    it('| error has admin-actionable userMessage (custom or default)', (): void => {
+      // Default userMessage
+      try {
+        DyFM_requireEnv('DEFAULT_MSG_VAR', { errorCode: 'C', issuerService: 's' });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err.__userMessage).toContain('DEFAULT_MSG_VAR');
+        expect(err.__userMessage).toContain('operator');
+      }
+      // Custom userMessage
+      try {
+        DyFM_requireEnv('CUSTOM_MSG_VAR', {
+          errorCode: 'C',
+          issuerService: 's',
+          userMessage: 'My custom admin instruction',
+        });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err.__userMessage).toBe('My custom admin instruction');
+      }
+    });
+
+    it('| error has issuerService set', (): void => {
+      try {
+        DyFM_requireEnv('V', { errorCode: 'C', issuerService: 'my-package' });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err.___issuerService).toBe('my-package');
+      }
+    });
+  });
+
+
+  describe('| lookup priority', (): void => {
+    it('| process.env wins over envOverrides', (): void => {
+      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = 'from-process';
+      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'from-overrides' };
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'C', issuerService: 's',
+      });
+      expect(value).toBe('from-process');
+    });
+
+    it('| envOverrides wins over fallback', (): void => {
+      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'from-overrides' };
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'C', issuerService: 's', fallback: 'from-fallback',
+      });
+      expect(value).toBe('from-overrides');
+    });
+
+    it('| process.env wins over fallback', (): void => {
+      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = 'from-process';
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'C', issuerService: 's', fallback: 'from-fallback',
+      });
+      expect(value).toBe('from-process');
+    });
+  });
+});