@futdevpro/fsm-dynamo 1.15.12 → 1.15.14

package/_specifications/BACKLOG.md

@@ -0,0 +1,43 @@
+# BACKLOG.md
+
+> STRICT PATTERN (MUST FOLLOW EXACTLY)
+> - Entry header: "- [TYPE] (BL-YYYYMMDD-###) TITLE"
+> - Immediately followed by (exact keys, colon-space, indented 2 spaces):
+>   - "  status: <EMOJI status-key>"
+>   - "  priority: <low|medium|high|urgent>"
+>   - "  source: <user|system|assistant>"
+>   - "  area: <ui|backend|infra|docs|tests|ux|general>"
+>   - "  details: <single-line summary>"
+> - NO blank line between header and fields (parser reads i+1..i+5).
+> - One blank line between entries (readability).
+> - TYPE values: FEATURE, BUG, IMPROVEMENT, QUESTION, RESEARCH, TASK
+> - STATUS EMOJI: ❌ ⏳ 🔄 ✅ ⚠️ ❓
+> - IDs: unique, format BL-YYYYMMDD-### (increment ###).
+
+- [IMPROVEMENT] (BL-20260518-001) DyFM_StateMachine: explicit `_FailureResult` return type a `_failure()` helper-en (TS narrowing)
+  status: ⏳ pending
+  priority: low
+  source: assistant
+  area: backend
+  details: A `DyFM_StateMachine._failure()` jelenleg `DyFM_StateMachineTransition_Result<TState>` union-t ad vissza. A TS inference emiatt nem narrow-ol az `if (!r.ok) {...}` blokkban (a private helper visszatérése a union mind két ágát beilleszti, és a `_failure()` belső object literal `{ ok: false, ... }` típusa nem narrow-ódik le `false` literal-re). Konzumens kódban `as DyFM_StateMachineTransition_FailureResult<TState>` cast szükséges. Fix: `_failure()` return type-ja explicit `DyFM_StateMachineTransition_FailureResult<TState>` (NEM union). 1-line type-annotation change, 0 viselkedés-változás.
+
+- [IMPROVEMENT] (BL-20260518-002) DyFM_StateMachine: `DyFM_Error` wrapping a result.error mezőben
+  status: ⏳ pending
+  priority: low
+  source: assistant
+  area: backend
+  details: A jelenlegi `DyFM_StateMachineTransition_FailureResult.error` `DyFM_Error | Error` típusú, de a `_failure()` raw `Error`-t propagál (callback throw-jából). Konzisztencia a többi `DyFM_*` modullal: `DyFM_Error({ status: 422, errorCode: 'DyFM-SM-<subcode>', message, error: originalError, issuerService: 'DyFM_StateMachine' })` wrappingot adni a 4 throw-elhető helyen (guard/onLeave/onEnter/persist). Subcode-ok pl. 'DyFM-SM-GR' (guard-rejected throw), 'DyFM-SM-OL' (on-leave), 'DyFM-SM-OE' (on-enter), 'DyFM-SM-PE' (persist). Spec: minden 4 error-path-on `DyFM_Error.getErrorCode(f.error)` assertion.
+
+- [TASK] (BL-20260518-003) DyFM_StateMachine: guard-throw + self-loop spec coverage
+  status: ⏳ pending
+  priority: low
+  source: assistant
+  area: tests
+  details: Két explicit spec hiányzik a FR-006 (52354ba) 22-spec szettjéből: (1) guard callback throw esetén `transition()` `guard-rejected` reason-t ad-e, és a `canTransition()` `false`-t (mindkét helyen catch-eli a impl, de NEM bizonyított teszttel); (2) self-loop transition (`from === to`) explicit spec — a `_findTransition` matchel rá, de nincs lefedve. ~30 LOC spec, no impl change.
+
+- [FEATURE] (BL-20260518-004) DyFM_StateMachine: Mongoose persist adapter
+  status: ⏳ pending
+  priority: medium
+  source: assistant
+  area: backend
+  details: Az MVP-ben (FR-006 / 52354ba) a `persist` callback caller-supplied (CCAP MP1-D maga írja a Mongo updateOne logikát stateVersion optimistic-lock-kal). Egy genericikus adapter ami `DyFM_dataModel`-kötött (Mongoose ControlModel) state-document-et frissít automatikusan, kevesebb boilerplate-tel. API: `createMongoosePersistAdapter({ collection: Model<T>, docFilter: { _id: 'rag-status' } }): DyFM_StateMachineConfig['persist']`. Optimistic-lock: `findOneAndUpdate({ ...filter, stateVersion: prev }, { $set: { state, stateVersion: next, lastTransitionAt: timestamp } })` — match nélkül `'persist-failed'`. Tervek szerint a consumer real-world tapasztalat (MP1-D landolása) után írandó, hogy a tényleges minta visszahatáson alapuljon.

package/build/_collections/utils/require-env.util.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Options for `DyFM_requireEnv`. See the helper's JSDoc for usage.
+ */
+export interface DyFM_RequireEnv_Options {
+    /**
+     * Stable error code emitted on the DyFM_Error when the env-var is missing
+     * and no fallback is configured. Convention: `<PACKAGE>-ENV-MISSING-<KEY>`,
+     * e.g. `DyNM-ENV-MISSING-STORAGE-KEY`, `FDP-ENV-MISSING-AUTH-KEY`.
+     */
+    errorCode: string;
+    /**
+     * Short-code name of the package responsible for the env-var. Used as the
+     * DyFM_Error `___issuerService` for downstream filtering / dashboards.
+     */
+    issuerService: string;
+    /**
+     * Transition fallback. When set, returned if BOTH `process.env[name]` AND
+     * `DyFM_global_settings.envOverrides[name]` are missing.
+     *
+     * Use only during the additive phase of an env-var migration to keep the
+     * package backward-compatible while every deploy target rolls the new
+     * env-var out. Remove the `fallback` argument once the rollout is verified
+     * everywhere — then a missing env-var fail-fast crashes the consumer at
+     * first access with a structured DyFM_Error.
+     */
+    fallback?: string;
+    /**
+     * Admin-actionable user-facing message attached to the DyFM_Error. Defaults
+     * to a generic config-missing string referencing the env-var name.
+     */
+    userMessage?: string;
+}
+/**
+ * FR-015 Phase 2 — isomorphic env-var requirement helper.
+ *
+ * Universal source of truth for "read this configuration key from an env-var
+ * across Node and browser". Replaces per-package `requireEnv` helpers (the
+ * Phase 1 local implementation in fdp-templates-nts is being refactored to
+ * delegate here).
+ *
+ * Lookup order:
+ *   1. `process.env[envVarName]` — Node-side (server const files at module load).
+ *   2. `DyFM_global_settings.envOverrides[envVarName]` — browser-side, populated
+ *      by the consumer at app bootstrap from its `environment.ts`. See
+ *      DyFM_Global_Settings.envOverrides docs for the pattern.
+ *   3. `options.fallback` if provided — used during migration's additive phase.
+ *   4. throw a structured DyFM_Error with the full deploy-target checklist.
+ *
+ * The throw shape is rich on purpose (per the rich-error rule):
+ *   - `___status` = 500 (configuration error)
+ *   - `_errorCode` = caller-supplied stable code
+ *   - `_message` = debug-level description with the env-var name + deploy-target
+ *     checklist (host .env, docker-compose env-block, Overseer secrets-store,
+ *     client environment.ts → bootstrap envOverrides)
+ *   - `__userMessage` = admin-actionable message
+ *   - `___issuerService` = caller-supplied package short-code
+ *
+ * @example Node server const file (module load):
+ * ```ts
+ * import { DyFM_requireEnv } from '@futdevpro/fsm-dynamo';
+ *
+ * export const FDP_keysEnv_settingsBase = {
+ *   authKey: DyFM_requireEnv('FDP_AUTH_KEY', {
+ *     errorCode: 'FDP-ENV-MISSING-AUTH-KEY',
+ *     issuerService: 'fdp-templates',
+ *     fallback: '<inherit literal>',   // remove for Wave 3
+ *   }),
+ * };
+ * ```
+ *
+ * @example Browser-side lazy getter (deferred to first access, after consumer
+ * bootstrap has populated DyFM_global_settings.envOverrides):
+ * ```ts
+ * let _cached: string | undefined;
+ * function _resolveKey(): string {
+ *   if (_cached !== undefined) return _cached;
+ *   _cached = DyFM_requireEnv('DyNM_STORAGE_ENCRYPTION_KEY', { ... });
+ *   return _cached;
+ * }
+ * export const DyNM_global_settings = {
+ *   get storageEncryptionKey(): string { return _resolveKey(); },
+ * };
+ * ```
+ */
+export declare function DyFM_requireEnv(envVarName: string, options: DyFM_RequireEnv_Options): string;
+//# sourceMappingURL=require-env.util.d.ts.map

package/build/_collections/utils/require-env.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-env.util.d.ts","sourceRoot":"","sources":["../../../src/_collections/utils/require-env.util.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,uBAAuB,GAC/B,MAAM,CAyCR"}

package/build/_collections/utils/require-env.util.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyFM_requireEnv = DyFM_requireEnv;
+const error_control_model_1 = require("../../_models/control-models/error.control-model");
+const global_settings_const_1 = require("../constants/global-settings.const");
+/**
+ * FR-015 Phase 2 — isomorphic env-var requirement helper.
+ *
+ * Universal source of truth for "read this configuration key from an env-var
+ * across Node and browser". Replaces per-package `requireEnv` helpers (the
+ * Phase 1 local implementation in fdp-templates-nts is being refactored to
+ * delegate here).
+ *
+ * Lookup order:
+ *   1. `process.env[envVarName]` — Node-side (server const files at module load).
+ *   2. `DyFM_global_settings.envOverrides[envVarName]` — browser-side, populated
+ *      by the consumer at app bootstrap from its `environment.ts`. See
+ *      DyFM_Global_Settings.envOverrides docs for the pattern.
+ *   3. `options.fallback` if provided — used during migration's additive phase.
+ *   4. throw a structured DyFM_Error with the full deploy-target checklist.
+ *
+ * The throw shape is rich on purpose (per the rich-error rule):
+ *   - `___status` = 500 (configuration error)
+ *   - `_errorCode` = caller-supplied stable code
+ *   - `_message` = debug-level description with the env-var name + deploy-target
+ *     checklist (host .env, docker-compose env-block, Overseer secrets-store,
+ *     client environment.ts → bootstrap envOverrides)
+ *   - `__userMessage` = admin-actionable message
+ *   - `___issuerService` = caller-supplied package short-code
+ *
+ * @example Node server const file (module load):
+ * ```ts
+ * import { DyFM_requireEnv } from '@futdevpro/fsm-dynamo';
+ *
+ * export const FDP_keysEnv_settingsBase = {
+ *   authKey: DyFM_requireEnv('FDP_AUTH_KEY', {
+ *     errorCode: 'FDP-ENV-MISSING-AUTH-KEY',
+ *     issuerService: 'fdp-templates',
+ *     fallback: '<inherit literal>',   // remove for Wave 3
+ *   }),
+ * };
+ * ```
+ *
+ * @example Browser-side lazy getter (deferred to first access, after consumer
+ * bootstrap has populated DyFM_global_settings.envOverrides):
+ * ```ts
+ * let _cached: string | undefined;
+ * function _resolveKey(): string {
+ *   if (_cached !== undefined) return _cached;
+ *   _cached = DyFM_requireEnv('DyNM_STORAGE_ENCRYPTION_KEY', { ... });
+ *   return _cached;
+ * }
+ * export const DyNM_global_settings = {
+ *   get storageEncryptionKey(): string { return _resolveKey(); },
+ * };
+ * ```
+ */
+function DyFM_requireEnv(envVarName, options) {
+    // Node path: process.env at module-load time. Guarded for browser bundles
+    // where `process` may be undefined or shimmed without runtime values.
+    if (typeof process !== 'undefined' && process.env && process.env[envVarName]) {
+        return process.env[envVarName];
+    }
+    // Browser path: consumer-populated envOverrides map. Populated at app
+    // bootstrap from environment.ts — see DyFM_Global_Settings.envOverrides.
+    const override = global_settings_const_1.DyFM_global_settings.envOverrides?.[envVarName];
+    if (override) {
+        return override;
+    }
+    // Transition fallback (Wave 1 of an FR-015-style migration).
+    if (options.fallback !== undefined) {
+        return options.fallback;
+    }
+    // Missing — fail fast with a rich, debug-friendly DyFM_Error.
+    throw new error_control_model_1.DyFM_Error({
+        status: 500,
+        errorCode: options.errorCode,
+        message: `Environment variable '${envVarName}' is required but was not found. ` +
+            `Checked: process.env.${envVarName} (Node) and ` +
+            `DyFM_global_settings.envOverrides['${envVarName}'] (browser). ` +
+            `Both unset, and no transition fallback configured. ` +
+            `Set '${envVarName}' on every deploy target before deploying this ` +
+            `package version: (1) host .env on every host running a backend, ` +
+            `(2) docker-compose env-block on every consumer service, ` +
+            `(3) Overseer secrets-store entry for CI builds, ` +
+            `(4) client environment.ts plus app-bootstrap copy into ` +
+            `DyFM_global_settings.envOverrides for any browser consumer.`,
+        userMessage: options.userMessage
+            ?? `Configuration error — environment variable '${envVarName}' is missing. `
+                + `Contact the responsible operator to set it on this deploy target.`,
+        issuerService: options.issuerService,
+    });
+}
+//# sourceMappingURL=require-env.util.js.map

package/build/_collections/utils/require-env.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-env.util.js","sourceRoot":"","sources":["../../../src/_collections/utils/require-env.util.ts"],"names":[],"mappings":";;AA6FA,0CA4CC;AAzID,0FAA8E;AAC9E,8EAA0E;AAwC1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,SAAgB,eAAe,CAC7B,UAAkB,EAClB,OAAgC;IAEhC,0EAA0E;IAC1E,sEAAsE;IACtE,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7E,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,CAAW,CAAC;IAC3C,CAAC;IAED,sEAAsE;IACtE,yEAAyE;IACzE,MAAM,QAAQ,GACZ,4CAAoB,CAAC,YAAY,EAAE,CAAC,UAAU,CAAC,CAAC;IAClD,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,6DAA6D;IAC7D,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,OAAO,CAAC,QAAQ,CAAC;IAC1B,CAAC;IAED,8DAA8D;IAC9D,MAAM,IAAI,gCAAU,CAAC;QACnB,MAAM,EAAE,GAAG;QACX,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,OAAO,EACL,yBAAyB,UAAU,mCAAmC;YACtE,wBAAwB,UAAU,cAAc;YAChD,sCAAsC,UAAU,gBAAgB;YAChE,qDAAqD;YACrD,QAAQ,UAAU,iDAAiD;YACnE,kEAAkE;YAClE,0DAA0D;YAC1D,kDAAkD;YAClD,yDAAyD;YACzD,6DAA6D;QAC/D,WAAW,EACT,OAAO,CAAC,WAAW;eAChB,+CAA+C,UAAU,gBAAgB;kBACvE,mEAAmE;QAC1E,aAAa,EAAE,OAAO,CAAC,aAAa;KACrC,CAAC,CAAC;AACL,CAAC"}

package/build/_models/interfaces/environment/global-settings.interface.d.ts

@@ -17,5 +17,27 @@ export interface DyFM_Global_Settings {
      * this setting will set which logs will be shown
      */
     log_settings: DyFM_GlobalLog_Settings;
+    /**
+     * FR-015 Phase 2 — isomorphic env-var overrides surface.
+     *
+     * On Node, `DyFM_requireEnv(name, ...)` reads `process.env[name]` directly.
+     * On browser there is no `process.env` at runtime, so consumers populate
+     * this map at app bootstrap from `environment.ts`:
+     *
+     * ```ts
+     * import { DyFM_global_settings } from '@futdevpro/fsm-dynamo';
+     * import { environment } from './environments/environment';
+     *
+     * DyFM_global_settings.envOverrides = {
+     *   FDP_AUTH_KEY: environment.authKey,
+     *   FDP_EXTRA_AUTH_STORAGE_KEY: environment.extraAuthStorageKey,
+     *   DyNM_STORAGE_ENCRYPTION_KEY: environment.storageEncryptionKey,
+     * };
+     * ```
+     *
+     * `DyFM_requireEnv` checks `process.env` first, then this map, then
+     * the caller's optional `fallback`, then throws a structured DyFM_Error.
+     */
+    envOverrides?: Record<string, string>;
 }
 //# sourceMappingURL=global-settings.interface.d.ts.map

package/build/_models/interfaces/environment/global-settings.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global-settings.interface.d.ts","sourceRoot":"","sources":["../../../../src/_models/interfaces/environment/global-settings.interface.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,YAAY,EAAE,uBAAuB,CAAC;CACvC"}
+{"version":3,"file":"global-settings.interface.d.ts","sourceRoot":"","sources":["../../../../src/_models/interfaces/environment/global-settings.interface.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,YAAY,EAAE,uBAAuB,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC"}

package/build/index.d.ts

@@ -10,6 +10,7 @@ export * from './_collections/utils/json-error-helper.util';
 export * from './_collections/utils/log.util';
 export * from './_collections/utils/round-list.util';
 export * from './_collections/utils/object.util';
+export * from './_collections/utils/require-env.util';
 export * from './_collections/utils/stack.util';
 export * from './_collections/utils/string.util';
 export * from './_collections/utils/string-case.util';

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,wCAAwC,CAAC;AACvD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iDAAiD,CAAC;AAChE,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAG/C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,uCAAuC,CAAC;AACtD,cAAc,gDAAgD,CAAC;AAI/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AAGvD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,uCAAuC,CAAC;AAGtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AAKjD,cAAc,0DAA0D,CAAC;AACzE,cAAc,6DAA6D,CAAC;AAC5E,cAAc,8CAA8C,CAAC;AAC7D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oDAAoD,CAAC;AACnE,cAAc,sDAAsD,CAAC;AACrE,cAAc,uEAAuE,CAAC;AAGtF,cAAc,iEAAiE,CAAC;AAChF,cAAc,0DAA0D,CAAC;AACzE,cAAc,wDAAwD,CAAC;AAGvE,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC;AAG1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,sCAAsC,CAAC;AACrD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,8CAA8C,CAAC;AAC7D,cAAc,wDAAwD,CAAC;AACvE,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gEAAgE,CAAC;AAC/E,cAAc,4DAA4D,CAAC;AAG3E,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,wCAAwC,CAAC;AACvD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iDAAiD,CAAC;AAChE,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAG/C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,uCAAuC,CAAC;AACtD,cAAc,gDAAgD,CAAC;AAI/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AAGvD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,uCAAuC,CAAC;AAGtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AAKjD,cAAc,0DAA0D,CAAC;AACzE,cAAc,6DAA6D,CAAC;AAC5E,cAAc,8CAA8C,CAAC;AAC7D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oDAAoD,CAAC;AACnE,cAAc,sDAAsD,CAAC;AACrE,cAAc,uEAAuE,CAAC;AAGtF,cAAc,iEAAiE,CAAC;AAChF,cAAc,0DAA0D,CAAC;AACzE,cAAc,wDAAwD,CAAC;AAGvE,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC;AAG1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,sCAAsC,CAAC;AACrD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,8CAA8C,CAAC;AAC7D,cAAc,wDAAwD,CAAC;AACvE,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gEAAgE,CAAC;AAC/E,cAAc,4DAA4D,CAAC;AAG3E,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC"}

package/build/index.js

@@ -16,6 +16,7 @@ tslib_1.__exportStar(require("./_collections/utils/json-error-helper.util"), exp
 tslib_1.__exportStar(require("./_collections/utils/log.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/round-list.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/object.util"), exports);
+tslib_1.__exportStar(require("./_collections/utils/require-env.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/stack.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/string.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/string-case.util"), exports);

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,cAAc;AACd,wBAAwB;AACxB,oFAA0D;AAC1D,wFAA8D;AAC9D,yFAA+D;AAC/D,iFAAuD;AACvD,+EAAqD;AAErD,oBAAoB;AACpB,0EAAgD;AAChD,0EAAgD;AAChD,yEAA+C;AAC/C,sFAA4D;AAC5D,wEAA8C;AAC9C,+EAAqD;AACrD,2EAAiD;AACjD,0EAAgD;AAChD,2EAAiD;AACjD,gFAAsD;AACtD,yEAA+C;AAC/C,0FAAgE;AAChE,8EAAoD;AACpD,yEAA+C;AAE/C,yBAAyB;AACzB,oFAA0D;AAC1D,8EAAoD;AACpD,gFAAsD;AACtD,sFAA4D;AAC5D,iFAAuD;AAEvD,2BAA2B;AAC3B,yFAA+D;AAC/D,gFAAsD;AACtD,yFAA+D;AAG/D,QAAQ;AACR,4EAAkD;AAClD,wEAA8C;AAC9C,yEAA+C;AAC/C,oEAA0C;AAC1C,kEAAwC;AACxC,iFAAuD;AAEvD,aAAa;AACb,4EAAkD;AAClD,6EAAmD;AACnD,gFAAsD;AAEtD,aAAa;AACb,yEAA+C;AAC/C,mEAAyC;AACzC,2EAAiD;AAGjD,SAAS;AACT,wBAAwB;AACxB,mGAAyE;AACzE,sGAA4E;AAC5E,uFAA6D;AAC7D,sFAA4D;AAC5D,6FAAmE;AACnE,+FAAqE;AACrE,gHAAsF;AAEtF,6BAA6B;AAC7B,0GAAgF;AAChF,mGAAyE;AACzE,iGAAuE;AAEvE,qBAAqB;AACrB,kFAAwD;AACxD,oFAA0D;AAE1D,oBAAoB;AACpB,oFAA0D;AAC1D,wFAA8D;AAC9D,+EAAqD;AACrD,uFAA6D;AAC7D,wFAA8D;AAC9D,sFAA4D;AAC5D,uFAA6D;AAC7D,iGAAuE;AACvE,iFAAuD;AAEvD,gCAAgC;AAChC,yGAA+E;AAC/E,qGAA2E;AAE3E,eAAe;AACf,yEAA+C;AAC/C,uEAA6C;AAC7C,yEAA+C;AAC/C,uEAA6C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,cAAc;AACd,wBAAwB;AACxB,oFAA0D;AAC1D,wFAA8D;AAC9D,yFAA+D;AAC/D,iFAAuD;AACvD,+EAAqD;AAErD,oBAAoB;AACpB,0EAAgD;AAChD,0EAAgD;AAChD,yEAA+C;AAC/C,sFAA4D;AAC5D,wEAA8C;AAC9C,+EAAqD;AACrD,2EAAiD;AACjD,gFAAsD;AACtD,0EAAgD;AAChD,2EAAiD;AACjD,gFAAsD;AACtD,yEAA+C;AAC/C,0FAAgE;AAChE,8EAAoD;AACpD,yEAA+C;AAE/C,yBAAyB;AACzB,oFAA0D;AAC1D,8EAAoD;AACpD,gFAAsD;AACtD,sFAA4D;AAC5D,iFAAuD;AAEvD,2BAA2B;AAC3B,yFAA+D;AAC/D,gFAAsD;AACtD,yFAA+D;AAG/D,QAAQ;AACR,4EAAkD;AAClD,wEAA8C;AAC9C,yEAA+C;AAC/C,oEAA0C;AAC1C,kEAAwC;AACxC,iFAAuD;AAEvD,aAAa;AACb,4EAAkD;AAClD,6EAAmD;AACnD,gFAAsD;AAEtD,aAAa;AACb,yEAA+C;AAC/C,mEAAyC;AACzC,2EAAiD;AAGjD,SAAS;AACT,wBAAwB;AACxB,mGAAyE;AACzE,sGAA4E;AAC5E,uFAA6D;AAC7D,sFAA4D;AAC5D,6FAAmE;AACnE,+FAAqE;AACrE,gHAAsF;AAEtF,6BAA6B;AAC7B,0GAAgF;AAChF,mGAAyE;AACzE,iGAAuE;AAEvE,qBAAqB;AACrB,kFAAwD;AACxD,oFAA0D;AAE1D,oBAAoB;AACpB,oFAA0D;AAC1D,wFAA8D;AAC9D,+EAAqD;AACrD,uFAA6D;AAC7D,wFAA8D;AAC9D,sFAA4D;AAC5D,uFAA6D;AAC7D,iGAAuE;AACvE,iFAAuD;AAEvD,gCAAgC;AAChC,yGAA+E;AAC/E,qGAA2E;AAE3E,eAAe;AACf,yEAA+C;AAC/C,uEAA6C;AAC7C,yEAA+C;AAC/C,uEAA6C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fsm-dynamo",
-  "version": "01.15.12",
+  "version": "01.15.14",
   "description": "Full Stack Model Collection for Dynamic (NodeJS-Typescript) Framework called Dynamo, by Future Development Ltd.",
   "DyBu_settings": {
     "packageType": "full-stack-package",
@@ -256,7 +256,7 @@
     "uuid": "11.1.0"
   },
   "devDependencies": {
-    "@futdevpro/dynamo-eslint": "1.15.9",
+    "@futdevpro/dynamo-eslint": "1.15.10",
     "@types/jasmine": "~4.3.5",
     "@typescript-eslint/eslint-plugin": "^8.41.0",
     "@typescript-eslint/parser": "^8.41.0",

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');
+    });
+  });
+});

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

@@ -0,0 +1,138 @@
+import { DyFM_Error } from '../../_models/control-models/error.control-model';
+import { DyFM_global_settings } from '../constants/global-settings.const';
+
+
+/**
+ * Options for `DyFM_requireEnv`. See the helper's JSDoc for usage.
+ */
+export interface DyFM_RequireEnv_Options {
+  /**
+   * Stable error code emitted on the DyFM_Error when the env-var is missing
+   * and no fallback is configured. Convention: `<PACKAGE>-ENV-MISSING-<KEY>`,
+   * e.g. `DyNM-ENV-MISSING-STORAGE-KEY`, `FDP-ENV-MISSING-AUTH-KEY`.
+   */
+  errorCode: string;
+
+  /**
+   * Short-code name of the package responsible for the env-var. Used as the
+   * DyFM_Error `___issuerService` for downstream filtering / dashboards.
+   */
+  issuerService: string;
+
+  /**
+   * Transition fallback. When set, returned if BOTH `process.env[name]` AND
+   * `DyFM_global_settings.envOverrides[name]` are missing.
+   *
+   * Use only during the additive phase of an env-var migration to keep the
+   * package backward-compatible while every deploy target rolls the new
+   * env-var out. Remove the `fallback` argument once the rollout is verified
+   * everywhere — then a missing env-var fail-fast crashes the consumer at
+   * first access with a structured DyFM_Error.
+   */
+  fallback?: string;
+
+  /**
+   * Admin-actionable user-facing message attached to the DyFM_Error. Defaults
+   * to a generic config-missing string referencing the env-var name.
+   */
+  userMessage?: string;
+}
+
+
+/**
+ * FR-015 Phase 2 — isomorphic env-var requirement helper.
+ *
+ * Universal source of truth for "read this configuration key from an env-var
+ * across Node and browser". Replaces per-package `requireEnv` helpers (the
+ * Phase 1 local implementation in fdp-templates-nts is being refactored to
+ * delegate here).
+ *
+ * Lookup order:
+ *   1. `process.env[envVarName]` — Node-side (server const files at module load).
+ *   2. `DyFM_global_settings.envOverrides[envVarName]` — browser-side, populated
+ *      by the consumer at app bootstrap from its `environment.ts`. See
+ *      DyFM_Global_Settings.envOverrides docs for the pattern.
+ *   3. `options.fallback` if provided — used during migration's additive phase.
+ *   4. throw a structured DyFM_Error with the full deploy-target checklist.
+ *
+ * The throw shape is rich on purpose (per the rich-error rule):
+ *   - `___status` = 500 (configuration error)
+ *   - `_errorCode` = caller-supplied stable code
+ *   - `_message` = debug-level description with the env-var name + deploy-target
+ *     checklist (host .env, docker-compose env-block, Overseer secrets-store,
+ *     client environment.ts → bootstrap envOverrides)
+ *   - `__userMessage` = admin-actionable message
+ *   - `___issuerService` = caller-supplied package short-code
+ *
+ * @example Node server const file (module load):
+ * ```ts
+ * import { DyFM_requireEnv } from '@futdevpro/fsm-dynamo';
+ *
+ * export const FDP_keysEnv_settingsBase = {
+ *   authKey: DyFM_requireEnv('FDP_AUTH_KEY', {
+ *     errorCode: 'FDP-ENV-MISSING-AUTH-KEY',
+ *     issuerService: 'fdp-templates',
+ *     fallback: '<inherit literal>',   // remove for Wave 3
+ *   }),
+ * };
+ * ```
+ *
+ * @example Browser-side lazy getter (deferred to first access, after consumer
+ * bootstrap has populated DyFM_global_settings.envOverrides):
+ * ```ts
+ * let _cached: string | undefined;
+ * function _resolveKey(): string {
+ *   if (_cached !== undefined) return _cached;
+ *   _cached = DyFM_requireEnv('DyNM_STORAGE_ENCRYPTION_KEY', { ... });
+ *   return _cached;
+ * }
+ * export const DyNM_global_settings = {
+ *   get storageEncryptionKey(): string { return _resolveKey(); },
+ * };
+ * ```
+ */
+export function DyFM_requireEnv(
+  envVarName: string,
+  options: DyFM_RequireEnv_Options,
+): string {
+  // Node path: process.env at module-load time. Guarded for browser bundles
+  // where `process` may be undefined or shimmed without runtime values.
+  if (typeof process !== 'undefined' && process.env && process.env[envVarName]) {
+    return process.env[envVarName] as string;
+  }
+
+  // Browser path: consumer-populated envOverrides map. Populated at app
+  // bootstrap from environment.ts — see DyFM_Global_Settings.envOverrides.
+  const override: string | undefined =
+    DyFM_global_settings.envOverrides?.[envVarName];
+  if (override) {
+    return override;
+  }
+
+  // Transition fallback (Wave 1 of an FR-015-style migration).
+  if (options.fallback !== undefined) {
+    return options.fallback;
+  }
+
+  // Missing — fail fast with a rich, debug-friendly DyFM_Error.
+  throw new DyFM_Error({
+    status: 500,
+    errorCode: options.errorCode,
+    message:
+      `Environment variable '${envVarName}' is required but was not found. ` +
+      `Checked: process.env.${envVarName} (Node) and ` +
+      `DyFM_global_settings.envOverrides['${envVarName}'] (browser). ` +
+      `Both unset, and no transition fallback configured. ` +
+      `Set '${envVarName}' on every deploy target before deploying this ` +
+      `package version: (1) host .env on every host running a backend, ` +
+      `(2) docker-compose env-block on every consumer service, ` +
+      `(3) Overseer secrets-store entry for CI builds, ` +
+      `(4) client environment.ts plus app-bootstrap copy into ` +
+      `DyFM_global_settings.envOverrides for any browser consumer.`,
+    userMessage:
+      options.userMessage
+      ?? `Configuration error — environment variable '${envVarName}' is missing. `
+         + `Contact the responsible operator to set it on this deploy target.`,
+    issuerService: options.issuerService,
+  });
+}

package/src/_models/interfaces/environment/global-settings.interface.ts

@@ -21,4 +21,27 @@ export interface DyFM_Global_Settings {
    * this setting will set which logs will be shown
    */
   log_settings: DyFM_GlobalLog_Settings;
+
+  /**
+   * FR-015 Phase 2 — isomorphic env-var overrides surface.
+   *
+   * On Node, `DyFM_requireEnv(name, ...)` reads `process.env[name]` directly.
+   * On browser there is no `process.env` at runtime, so consumers populate
+   * this map at app bootstrap from `environment.ts`:
+   *
+   * ```ts
+   * import { DyFM_global_settings } from '@futdevpro/fsm-dynamo';
+   * import { environment } from './environments/environment';
+   *
+   * DyFM_global_settings.envOverrides = {
+   *   FDP_AUTH_KEY: environment.authKey,
+   *   FDP_EXTRA_AUTH_STORAGE_KEY: environment.extraAuthStorageKey,
+   *   DyNM_STORAGE_ENCRYPTION_KEY: environment.storageEncryptionKey,
+   * };
+   * ```
+   *
+   * `DyFM_requireEnv` checks `process.env` first, then this map, then
+   * the caller's optional `fallback`, then throws a structured DyFM_Error.
+   */
+  envOverrides?: Record<string, string>;
 }

package/src/index.ts

@@ -15,6 +15,7 @@ export * from './_collections/utils/json-error-helper.util';
 export * from './_collections/utils/log.util';
 export * from './_collections/utils/round-list.util';
 export * from './_collections/utils/object.util';
+export * from './_collections/utils/require-env.util';
 export * from './_collections/utils/stack.util';
 export * from './_collections/utils/string.util';
 export * from './_collections/utils/string-case.util';

package/src/_collections/utils/math/box-bounds.util.spec.ts

@@ -1,124 +0,0 @@
-import { DyFM_Vector2 } from '../../../_models/interfaces/vector2.interface';
-import { DyFM_BoxBounds_Util } from './box-bounds.util';
-import { DyFM_Vector2_Util } from './vector2.util';
-
-xdescribe('| DyFM_BoxBounds', () => {
-  let boxBounds: DyFM_BoxBounds_Util;
-  const mockPosition = new DyFM_Vector2_Util({ x: 0, y: 0 });
-  const mockSize = new DyFM_Vector2_Util({ x: 10, y: 10 });
-
-  beforeEach(() => {
-    boxBounds = new DyFM_BoxBounds_Util(mockPosition, mockSize);
-  });
-
-  it('| should set position correctly ()', () => {
-    const newPosition = new DyFM_Vector2_Util({ x: 5, y: 5 });
-
-    boxBounds.pos = newPosition;
-    expect(boxBounds.pos).toEqual(newPosition);
-  });
-
-  it('| should get position correctly', () => {
-    const expectedPosition = new DyFM_Vector2_Util({ x: 5, y: 5 });
-
-    expect(boxBounds.pos).toEqual(expectedPosition);
-  });
-
-  it('| should set size correctly', () => {
-    const newSize = new DyFM_Vector2_Util({ x: 20, y: 20 });
-
-    boxBounds.size = newSize;
-    expect(boxBounds.size).toEqual(newSize);
-  });
-
-  it('| should get size correctly', () => {
-    const expectedSize = new DyFM_Vector2_Util({ x: 20, y: 20 });
-
-    expect(boxBounds.size).toEqual(expectedSize);
-  });
-
-  xit('| should calculate center correctly', () => {
-    const expectedCenter = new DyFM_Vector2_Util({ x: 10, y: 10 });
-    expect(boxBounds.center).toEqual(expectedCenter);
-  });
-
-  it('| should calculate center margin correctly', () => {
-    const expectedCenterMargin = new DyFM_Vector2_Util({ x: -5, y: -5 });
-    expect(boxBounds.centerMargin).toEqual(expectedCenterMargin);
-  });
-
-  it('| should return true for constructed method', () => {
-    expect(boxBounds.constructed()).toBe(true);
-  });
-
-  it('| should throw error when newValues has undefined position', () => {
-    expect(() => {
-      boxBounds.newValues(undefined as any, { x: 10, y: 10 });
-    }).toThrow(Error);
-  });
-
-  it('| should throw error when newValues has undefined size', () => {
-    expect(() => {
-      boxBounds.newValues({ x: 0, y: 0 }, undefined as any);
-    }).toThrow(Error);
-  });
-
-  it('| should clone and return a new instance', () => {
-    const clonedBoxBounds = boxBounds.clone();
-
-    expect(clonedBoxBounds).toBeInstanceOf(DyFM_BoxBounds_Util);
-    expect(clonedBoxBounds).toEqual(boxBounds);
-  });
-  
-
-  it('| should initialize with given position and size', () => {
-    expect(boxBounds.pos.x).toBe(mockPosition.x);
-    expect(boxBounds.pos.y).toBe(mockPosition.y);
-    expect(boxBounds.size.x).toBe(mockSize.x);
-    expect(boxBounds.size.y).toBe(mockSize.y);
-  });
-
-  it('| should calculate center correctly', () => {
-    const expectedCenter = DyFM_Vector2_Util.plus(mockPosition, DyFM_Vector2_Util.divide(mockSize, 2));
-    expect(boxBounds.center.x).toBe(expectedCenter.x);
-    expect(boxBounds.center.y).toBe(expectedCenter.y);
-  });
-
-  it('| should update position and size with newValues method', () => {
-    const newPosition: DyFM_Vector2 = { x: 50, y: 60 };
-    const newSize: DyFM_Vector2 = { x: 70, y: 80 };
-    boxBounds.newValues(newPosition, newSize);
-
-    expect(boxBounds.pos.x).toBe(newPosition.x);
-    expect(boxBounds.pos.y).toBe(newPosition.y);
-    expect(boxBounds.size.x).toBe(newSize.x);
-    expect(boxBounds.size.y).toBe(newSize.y);
-  });
-
-  it('| should throw error if newValues is called with undefined position', () => {
-    expect(() => boxBounds.newValues(undefined as any, mockSize)).toThrowError('new position is undefined!');
-  });
-
-  it('| should throw error if newValues is called with undefined size', () => {
-    expect(() => boxBounds.newValues(mockPosition, undefined as any)).toThrowError('new size is undefined!');
-  });
-
-  it('| should correctly determine if a position is within bounds', () => {
-    const insidePosition: DyFM_Vector2 = { x: 20, y: 30 };
-    const outsidePosition: DyFM_Vector2 = { x: 100, y: 100 };
-
-    expect(boxBounds.bounds(insidePosition)).toBeTrue();
-    expect(boxBounds.bounds(outsidePosition)).toBeFalse();
-  });
-
-  it('| should clone itself correctly', () => {
-    const clone = boxBounds.clone();
-    expect(clone.pos.x).toBe(boxBounds.pos.x);
-    expect(clone.pos.y).toBe(boxBounds.pos.y);
-    expect(clone.size.x).toBe(boxBounds.size.x);
-    expect(clone.size.y).toBe(boxBounds.size.y);
-    expect(clone).not.toBe(boxBounds);
-  });
-  
-
-});