@sdux-vault/shared 0.6.0 → 0.7.0

package/fesm2022/sdux-vault-shared.mjs

@@ -1,18 +1,6 @@
 import { BehaviorSubject, Subscription, tap } from 'rxjs';
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > typings > global.d.ts
-// Updated: 2026-03-24 12:38
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
-
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > utils > dev-mode > testing-environment.util.ts
-// Updated: 2026-03-09 14:47
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Singleton accessor that detects whether code is running in a test environment. */
 const isTestEnv = {
     get active() {
         return (
@@ -27,13 +15,9 @@ const isTestEnv = {
     }
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > utils > dev-mode > dev-mode.util.ts
-// Updated: 2026-03-09 14:46
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Tracks whether Vault development mode has been enabled. */
 let devMode = null;
+/** Singleton accessor for Vault development mode state. */
 const DevMode = {
     get active() {
         return devMode === true;
@@ -46,12 +30,12 @@ const DevMode = {
     }
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > utils > version > version.register.ts
-// Updated: 2026-03-03 07:47
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/**
+ * Registers a package version on the global SDuX debug widget when dev mode is active.
+ *
+ * @param packageName - The npm package name to register.
+ * @param version - The semver version string.
+ */
 const registerVersion = (packageName, version) => {
     if (!DevMode.active || typeof globalThis === 'undefined')
         return;
@@ -63,14 +47,10 @@ const registerVersion = (packageName, version) => {
     versions[packageName] = version;
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > version > version.register.ts
-// Updated: 2026-03-03 08:12
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Package name used for version registration. */
 const SDUX_PACKAGE = '@sdux-vault/shared';
-const SDUX_VERSION = '0.6.0';
+/** Current package version string. */
+const SDUX_VERSION = '0.7.0';
 registerVersion(SDUX_PACKAGE, SDUX_VERSION);
 
 /**
@@ -111,12 +91,6 @@ const BehaviorTypes = {
     TabSyncState: 'tabSyncState'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > types > logging > console.type.ts
-// Updated: 2026-03-21 21:00
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /**
  * Defines the allowable verbosity levels for Vault logging.
  *
@@ -130,6 +104,7 @@ const BehaviorTypes = {
  * - `'log'`   — standard log events, warnings, and errors are logged
  * - `'debug'` — all debug-level information is emitted
  */
+/** Enumeration of console output severity levels. */
 const ConsoleTypes = {
     Error: 'error',
     Warn: 'warn',
@@ -137,12 +112,6 @@ const ConsoleTypes = {
     Debug: 'debug'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > types > logging > log-level.type.ts
-// Updated: 2026-03-21 21:00
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /**
  * Defines the allowable verbosity levels for Vault logging.
  *
@@ -156,6 +125,7 @@ const ConsoleTypes = {
  * - `'log'`   — standard log events, warnings, and errors are logged
  * - `'debug'` — all debug-level information is emitted
  */
+/** Enumeration of Vault log verbosity levels. */
 const LogLevelTypes = {
     Off: 'off',
     Error: 'error',
@@ -164,18 +134,19 @@ const LogLevelTypes = {
     Debug: 'debug'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > utils > logger > logger.util.ts
-// Updated: 2026-03-23 16:50
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Current log level threshold controlling which messages are emitted. */
 let _logLevel = LogLevelTypes.Off;
 /**
  * Prefix applied to all vault-related console output. Used to keep log
  * messages consistently identifiable across all log levels.
  */
 const LOG_PREFIX = '[vault]';
+/**
+ * Routes a log message to the console if the current log level permits it.
+ *
+ * @param level - The console severity level for this message.
+ * @param args - Console arguments to log.
+ */
 // eslint-disable-next-line
 function push(level, ...args) {
     const logLevel = getVaultLogLevel();
@@ -221,13 +192,27 @@ const vaultLog = (...args) => push('log', ...args);
  */
 // eslint-disable-next-line
 const vaultDebug = (...args) => push('debug', ...args);
+/**
+ * Sets the global Vault log level threshold.
+ *
+ * @param level - The log level to apply.
+ */
 function setVaultLogLevel(level) {
     _logLevel = level ?? 'off';
 }
+/**
+ * Returns the current global Vault log level.
+ *
+ * @returns The active log level threshold.
+ */
 function getVaultLogLevel() {
     return _logLevel;
 }
 
+/**
+ * Abstract base class for error callback behaviors that execute consumer-supplied
+ * error handlers during the error stage of the Vault pipeline.
+ */
 class AbstractErrorCallbackBehavior {
     behaviorCtx;
     /** Indicates that this error behavior is critical and always executed. */
@@ -247,19 +232,13 @@ class AbstractErrorCallbackBehavior {
         this.key = key;
     }
     /**
-     * Lifecycle hook invoked when the behavior instance is destroyed.
-     *
-     * Error behaviors do not allocate runtime resources and therefore require
-     * no cleanup. A diagnostic entry is logged for lifecycle visibility.
+     * Teardown hook invoked when the behavior instance is destroyed.
      */
     destroy() {
         vaultWarn(`${this.key} - destroy "noop"`);
     }
     /**
-     * Lifecycle hook invoked when the behavior instance is reset.
-     *
-     * Error behaviors hold no internal state, making this a no-operation.
-     * The hook ensures lifecycle uniformity across all behaviors.
+     * Resets the error behavior to its initial state.
      */
     reset() {
         vaultWarn(`${this.key} - reset "noop"`);
@@ -270,12 +249,6 @@ class AbstractErrorCallbackBehavior {
  * Abstract base behavior for transforming errors during pipeline execution.
  * This class defines the contract and lifecycle hooks required for error transformation behaviors.
  *
- * --RelatedStart--
- * ErrorTransformBehaviorContract
- * BehaviorClassContext
- * StateSnapshotShape
- * VaultErrorShape
- * --RelatedEnd--
  */
 class AbstractErrorTransformBehavior {
     behaviorCtx;
@@ -374,19 +347,36 @@ function jsonSafeReplacer(_key, val) {
 /** ------------------------------------------
  * INTERNAL CLASS (NOT EXPORTED)
  * ------------------------------------------ */
+/**
+ * Internal singleton error service that holds the current Vault error state.
+ * Not exported directly; consumed exclusively by the public VaultErrorService.
+ */
 class VaultPrivateErrorClass {
+    /** Subject backing the private error observable. */
     #error$ = new BehaviorSubject(null);
+    /** Initializes the private error service singleton. */
     constructor() {
         vaultDebug('[VaultPrivateErrorService] initialized (singleton instance created)');
     }
+    /**
+     * Publishes a new error or clears the current error.
+     *
+     * @param error - The error shape to publish, or null to clear.
+     */
     setError(error) {
         vaultDebug(`[VaultPrivateErrorService] setError() ${safeStringify(error)}`);
         this.#error$.next(error);
     }
+    /**
+     * Returns an observable of the current error state.
+     *
+     * @returns Observable emitting the current error or null.
+     */
     getError() {
         vaultDebug('[VaultPrivateErrorService] getError() → observable subscribed');
         return this.#error$.asObservable();
     }
+    /** Resets the error state to null. */
     clear() {
         vaultDebug('[VaultPrivateErrorService] clear() → error reset to null');
         this.#error$.next(null);
@@ -396,6 +386,11 @@ class VaultPrivateErrorClass {
  * SINGLETON FACTORY (EXPORTED)
  * ------------------------------------------ */
 let _instance$1 = null;
+/**
+ * Returns the singleton VaultPrivateErrorService instance, creating it on first call.
+ *
+ * @returns The shared private error service instance.
+ */
 function VaultPrivateErrorService() {
     if (!_instance$1) {
         vaultDebug('[VaultPrivateErrorService] creating new singleton instance');
@@ -407,14 +402,23 @@ function VaultPrivateErrorService() {
     return _instance$1;
 }
 
+/**
+ * Singleton service that aggregates and exposes the current Vault error state.
+ * Subscribes to the private error service and mirrors updates through a public
+ * observable stream for consumer consumption.
+ */
 class VaultErrorServiceClass {
+    /** Internal delegate responsible for low-level error state management. */
     #privateVaultErrorService = VaultPrivateErrorService();
+    /** Subject backing the public error observable. */
     #error$ = new BehaviorSubject(null);
+    /** Tracks whether an active error is currently held. */
     #hasErrorState = false;
-    /** Track internal subscription for cleanup */
+    /** Aggregate subscription used for cleanup on teardown. */
     #subscription = new Subscription();
-    /** Public observable error stream */
+    /** Public observable stream of the current error state. */
     error$ = this.#error$.asObservable();
+    /** Initializes the service and subscribes to the private error stream. */
     constructor() {
         vaultDebug('[VaultErrorService] Initializing service and subscribing to private error stream.');
         // Mirror the private error service into this one
@@ -427,18 +431,23 @@ class VaultErrorServiceClass {
         });
         this.#subscription.add(sub);
     }
+    /** Whether an active error is currently present. */
     get hasError() {
         return this.#hasErrorState;
     }
+    /** Clears the current error state via the private error service. */
     clear() {
         vaultDebug('[VaultErrorService] Clearing current error.');
         this.#privateVaultErrorService.clear();
     }
 }
-// --------------------------------
-// SINGLETON FACTORY (EXPORTED)
-// --------------------------------
+/** Cached singleton instance of the VaultErrorService. */
 let _instance = null;
+/**
+ * Returns the singleton VaultErrorService instance, creating it on first call.
+ *
+ * @returns The shared VaultErrorService instance.
+ */
 function VaultErrorService() {
     if (!_instance) {
         vaultDebug('[VaultErrorService] Creating new singleton instance.');
@@ -447,13 +456,28 @@ function VaultErrorService() {
     return _instance;
 }
 
+/**
+ * Abstract base class for active controllers that react to external error
+ * state changes and participate in pipeline admission voting.
+ */
 class AbstractActiveController {
     ctx;
+    /** Unique identifier for this controller instance. */
     key;
+    /** Whether errors from this controller halt the pipeline. */
     critical = false;
+    /** Tracks whether the global error service currently holds an error. */
     hasError = false;
+    /** Trace identifier from the most recent pipeline operation. */
     traceId = null;
+    /** Subscription to the global VaultErrorService stream. */
     #subscription;
+    /**
+     * Creates an active controller and subscribes to the global error stream.
+     *
+     * @param key - Unique controller identifier supplied by the factory.
+     * @param ctx - Class-level context providing revote and lifecycle access.
+     */
     constructor(key, ctx) {
         this.ctx = ctx;
         this.key = key;
@@ -475,47 +499,34 @@ class AbstractActiveController {
         }))
             .subscribe();
     }
-    /** Child classes override to react to external error toggles */
+    /**
+     * Hook invoked when the external error state changes.
+     *
+     * @param _newErrorState - The updated error state flag.
+     */
     //istanbul ignore next
     onExternalTrigger(_newErrorState) { }
+    /** Tears down the controller and unsubscribes from the error stream. */
     destroy() {
         this.#subscription.unsubscribe();
         vaultWarn(`${this.key} - destroy`);
     }
+    /** Resets the controller to its initial state. */
     reset() {
         vaultWarn(`${this.key} - reset "noop"`);
     }
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > abstracts > index.ts
-// Updated: 2026-03-23 17:27
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /* -----------------------------------------------------------
  * Abstracts
  * --------------------------------------------------------- */
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > config > index.ts
-// Updated: 2026-03-23 16:54
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
-
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > constants > behavior-meta.constant.ts
-// Updated: 2026-03-28 14:09
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Symbol key used to attach behavior metadata to a behavior class. */
 const BEHAVIOR_META = Symbol.for('BEHAVIOR_META');
 
+/** Symbol key used to attach controller metadata to a controller class. */
 const CONTROLLER_META = Symbol.for('CONTROLLER_META');
 
-// --- AI Model File Path ---
-// libs > shared > src > lib > constants > dev-tools > devtools-aggregate-key.constant.ts
 /**
  * String token used to uniquely identify the DevTools Aggregate FeatureCell.
  *
@@ -528,8 +539,6 @@ const CONTROLLER_META = Symbol.for('CONTROLLER_META');
  */
 const DEVTOOLS_AGGREGATE_KEY_CONSTANT = 'vault::devtools::aggregate:feature::cell';
 
-// --- AI Model File Path ---
-// libs > shared > src > lib > constants > dev-tools > devtools-logging-key.constant.ts
 /**
  * String token used to uniquely identify the DevTools Logging FeatureCell.
  *
@@ -542,31 +551,22 @@ const DEVTOOLS_AGGREGATE_KEY_CONSTANT = 'vault::devtools::aggregate:feature::cel
  */
 const DEVTOOLS_LOGGING_KEY_CONSTANT = 'vault::devtools::logging::feature::cell';
 
+/** Sentinel symbol that signals the pipeline to clear the current state. */
 const VAULT_CLEAR_STATE = Symbol.for('VAULT_CLEAR_STATE');
 
+/** Sentinel symbol that signals the pipeline to continue processing. */
 const VAULT_CONTINUE = Symbol.for('VAULT_CONTINUE');
 
+/** Sentinel symbol that signals the pipeline to skip the current operation. */
 const VAULT_NOOP = Symbol.for('VAULT_NOOP');
 
+/** Sentinel symbol that signals the pipeline to halt execution. */
 const VAULT_STOP = Symbol.for('VAULT_STOP');
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > constants > public-api.ts
-// Updated: 2026-03-23 18:48
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /* -----------------------------------------------------------
  * META + DECORATORS
  * --------------------------------------------------------- */
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > contexts > index.ts
-// Updated: 2026-03-23 17:31
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
-
 // vault-behavior.decorator.ts
 /**
  * Decorator that registers a class as an Vault behavior.
@@ -625,6 +625,12 @@ function VaultBehavior(meta) {
 }
 
 // vault-behavior.decorator.ts
+/**
+ * Class decorator that attaches controller metadata to the target class.
+ *
+ * @param meta - The controller metadata shape to apply.
+ * @returns A class decorator function.
+ */
 function VaultController(meta) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return function (target) {
@@ -661,27 +667,17 @@ function VaultController(meta) {
     };
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > decorators > index.ts
-// Updated: 2026-03-23 18:29
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /* -----------------------------------------------------------
  * META + DECORATORS
  * --------------------------------------------------------- */
 
+/** Enumeration of top-level Vault error kind classifications. */
 const VaultErrorKindTypes = {
     Usage: 'VaultErrorUsage',
     VaultError: 'VaultError'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > types > error > vault-error-name.type.ts
-// Updated: 2026-03-12 11:57
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Enumeration of Vault error name identifiers. */
 const VaultErrorNameTypes = {
     EncryptionIntegrity: 'VaultErrorEncryptionIntegrity',
     License: 'VaultErrorLicense',
@@ -689,14 +685,20 @@ const VaultErrorNameTypes = {
     VaultError: 'VaultError'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > errors > vault-error.ts
-// Updated: 2026-03-12 12:08
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/**
+ * Base error class for all Vault-specific errors. Extends the native Error
+ * with a typed name and kind for structured error classification.
+ */
 class VaultError extends Error {
+    /** Classification kind used to categorize this error in diagnostics. */
     kind;
+    /**
+     * Creates a new VaultError instance with prototype chain correction.
+     *
+     * @param message - Human-readable description of the error.
+     * @param name - Typed error name used for identification.
+     * @param kind - Error kind used for diagnostic classification.
+     */
     constructor(message, name = VaultErrorNameTypes.VaultError, kind = VaultErrorKindTypes.VaultError) {
         super(message);
         this.name = name;
@@ -712,25 +714,12 @@ class VaultError extends Error {
     }
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > errors > vault-error.encryption.integrity.ts
-// Updated: 2026-03-12
-// --- END AI MODEL FILE PATH ---
 /**
- * Thrown when encrypted payload integrity verification fails.
- *
- * This occurs when AES-GCM authentication fails during decryption.
- * Causes may include:
- *
- * - Tampered ciphertext
- * - Modified IV
- * - Incorrect encryption key
- * - Corrupted storage payload
- *
- * AES-GCM provides authenticated encryption, so any modification to the
- * encrypted envelope will cause the WebCrypto decrypt operation to throw.
+ * Thrown when an encrypted payload fails AES-GCM integrity verification
+ * during decryption, indicating tampered, corrupted, or mismatched key data.
  */
 class VaultEncryptionIntegrityError extends VaultError {
+    /** Creates the error with a descriptive integrity-failure message. */
     constructor() {
         const message = `Encrypted snapshot failed integrity verification.
 
@@ -748,12 +737,7 @@ Vault refuses to restore state from unauthenticated encrypted data.`;
     }
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > types > error > vault-error-usage-kind.type.ts
-// Updated: 2026-03-12 11:57
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Enumeration of usage-specific Vault error sub-kind classifications. */
 const VaultErrorUsageKindTypes = {
     Encryption: 'VaultErrorEncryption',
     License: 'VaultErrorLicense',
@@ -762,31 +746,42 @@ const VaultErrorUsageKindTypes = {
     Usage: 'VaultErrorUsage'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > errors > vault-error.license.ts
-// Updated: 2026-03-12 11:56
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/**
+ * Thrown when a behavior or controller fails license validation.
+ */
 class VaultLicenseError extends VaultError {
+    /**
+     * Creates a license validation error.
+     *
+     * @param message - Description of the license violation.
+     * @param kind - Usage-kind classification for diagnostics.
+     */
     constructor(message, kind = VaultErrorUsageKindTypes.License) {
         super(message, VaultErrorNameTypes.License, kind);
     }
 }
 
+/**
+ * Base error for Vault API usage violations detected at runtime.
+ */
 class VaultUsageError extends VaultError {
+    /**
+     * Creates a usage error with the specified message and kind.
+     *
+     * @param message - Description of the usage violation.
+     * @param kind - Usage-kind classification for diagnostics.
+     */
     constructor(message, kind = VaultErrorUsageKindTypes.Usage) {
         super(message, VaultErrorNameTypes.Usage, kind);
     }
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > errors > vault-error.usage.promise.ts
-// Updated: 2026-03-12 12:01
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/**
+ * Thrown when an eager Promise is passed directly to the state pipeline
+ * instead of a deferred factory function.
+ */
 class VaultUsagePromiseError extends VaultUsageError {
+    /** Creates the error with a descriptive usage-violation message. */
     constructor() {
         const message = `Invalid incoming value: Promise detected.
 
@@ -799,7 +794,12 @@ This guarantees the promise is created and executed inside the pipeline.`;
     }
 }
 
+/**
+ * Thrown when a Promise-based state method receives a raw value instead
+ * of a factory function that returns a Promise.
+ */
 class VaultUsagePromiseFactoryRequiredError extends VaultUsageError {
+    /** Creates the error with a descriptive usage-violation message. */
     constructor() {
         const message = `Invalid usage of Promise-based state API.
 
@@ -820,34 +820,15 @@ inside the pipeline.`;
     }
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > errors > index.ts
-// Updated: 2026-03-23 17:21
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /* -----------------------------------------------------------
  * ERRORS
  * --------------------------------------------------------- */
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > interfaces > index.ts
-// Updated: 2026-03-23 18:45
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
-
 /* -----------------------------------------------------------
  * SERVICES
  * --------------------------------------------------------- */
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > shapes > index.ts
-// Updated: 2026-03-23 18:42
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
-
+/** Enumeration of message types dispatched to controllers during pipeline orchestration. */
 const ControllerMessageTypes = {
     Attempt: 'attempt',
     Failure: 'failure',
@@ -856,12 +837,14 @@ const ControllerMessageTypes = {
     Vote: 'vote' // mostly internal
 };
 
+/** Enumeration of votes a controller may cast during pipeline admission. */
 const ControllerVotes = {
     Abstain: 'abstain',
     Abort: 'abort',
     Deny: 'deny'
 };
 
+/** Enumeration of controller category classifications. */
 const ControllerTypes = {
     CoreAbstain: 'coreAbstain',
     Error: 'error',
@@ -872,18 +855,14 @@ const ControllerTypes = {
     TabSync: 'tabSync'
 };
 
+/** Enumeration of conductor decision outcomes after controller voting. */
 const DecisionOutcomeTypes = {
     Abort: 'abort',
     Abstain: 'abstain',
     Deny: 'deny'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > types > event > event-boundary.type.ts
-// Updated: 2026-03-10 09:56
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Enumeration of event boundary positions within a lifecycle span. */
 const EventBoundaryTypes = {
     End: 'end',
     Notification: 'notification',
@@ -891,12 +870,7 @@ const EventBoundaryTypes = {
     Unknown: 'unknown'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > types > event > event.type.ts
-// Updated: 2026-03-10 09:56
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Enumeration of monitor event category classifications. */
 const EventTypes = {
     Conductor: 'conductor',
     Controller: 'controller',
@@ -905,6 +879,7 @@ const EventTypes = {
     Unknown: 'unknown'
 };
 
+/** Enumeration of pipeline operation modes. */
 const OperationTypes = {
     Merge: 'merge',
     Replace: 'replace',
@@ -928,6 +903,7 @@ const ResolveTypes = {
     Value: 'value'
 };
 
+/** Enumeration of state emission event classifications. */
 const StateEmitTypes = {
     IncomingPipeline: 'Incoming Pipeline',
     FinalizePipeline: 'Finalize Pipeline',
@@ -939,22 +915,10 @@ const StateEmitTypes = {
     TabSync: 'Tab Sync'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > types > index.ts
-// Updated: 2026-03-23 18:51
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /* -----------------------------------------------------------
  * TYPES (USER-FACING)
  * --------------------------------------------------------- */
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > utils > behavior > define-behavior-key.util.ts
-// Updated: 2026-03-28 10:46
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /**
  * Creates a normalized behavior key identifier used for behavior registration.
  *
@@ -977,6 +941,14 @@ const StateEmitTypes = {
 function defineBehaviorKey(domain, name) {
     return defineVaultKey('Behavior', domain, name);
 }
+/**
+ * Constructs a normalized Vault key for behavior or controller registration.
+ *
+ * @param kind - Whether the key is for a Behavior or Controller.
+ * @param domain - The logical domain or category.
+ * @param name - The specific name within the domain.
+ * @returns A normalized Vault key string.
+ */
 function defineVaultKey(kind, domain, name) {
     const normalize = (s) => s.charAt(0).toUpperCase() + s.slice(1).replace(/[^A-Za-z0-9]/g, '');
     return `SDUX::${kind}::${normalize(domain)}::${normalize(name)}`;
@@ -1001,19 +973,32 @@ function validateBehaviorKey(key) {
     return pattern.test(key);
 }
 
+/**
+ * Creates a normalized controller key following the Vault key format.
+ *
+ * @param domain - The logical domain or category of the controller.
+ * @param name - The specific controller name within the domain.
+ * @returns A normalized controller key string.
+ */
 function defineControllerKey(domain, name) {
     return defineVaultKey('Controller', domain, name);
 }
+/**
+ * Validates whether a string conforms to the Vault controller key format.
+ *
+ * @param key - The controller key string to validate.
+ * @returns `true` if the key matches the required pattern.
+ */
 function validateControllerKey(key) {
     return validateBehaviorKey(key);
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > utils > deferred-factory > is-deferred-factory.util.ts
-// Updated: 2026-03-21 20:36
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/**
+ * Determines whether a value conforms to the DeferredFactory contract.
+ *
+ * @param value - The value to inspect.
+ * @returns `true` if the value is an object with a callable `value` property.
+ */
 function isDeferredFactory(value) {
     return (!!value &&
         typeof value === 'object' &&
@@ -1069,12 +1054,6 @@ function createVaultError(err, featureCellKey) {
     };
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > utils > isolate-value > isolate-value.util.ts
-// Updated: 2026-04-07 15:49
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /*
 | Category                 | Type / Example        | structuredClone behavior  | deepFreeze fallback behavior          | Isolated?  | Notes                                          |
 | ------------------------ | --------------------- | ------------------------- | ------------------------------------- | ---------- | ---------------------------------------------- |
@@ -1119,6 +1098,13 @@ function createVaultError(err, featureCellKey) {
 | **Frozen Objects**       | `Object.freeze(obj)`  | Cloned (unfrozen)         | Preserved frozen OR cloned+frozen     | ✅ Yes     | Freeze state not guaranteed                    |
 | **Boxed Primitives**     | `new Number(1)`       | Cloned                    | Frozen                                | ✅ Yes     | Unboxed behavior retained                      |
 */
+/**
+ * Recursively freezes an object and all nested properties to prevent mutation.
+ *
+ * @param obj - The object to deep-freeze.
+ * @param seen - WeakSet used to track visited references and prevent cycles.
+ * @returns The frozen object.
+ */
 function deepFreeze(obj, seen = new WeakSet()) {
     if (obj === null || typeof obj !== 'object')
         return obj;
@@ -1141,6 +1127,12 @@ function deepFreeze(obj, seen = new WeakSet()) {
     }
     return obj;
 }
+/**
+ * Creates an immutable copy of a value using structuredClone with a deepFreeze fallback.
+ *
+ * @param value - The value to isolate.
+ * @returns An immutable copy of the value.
+ */
 const isolateValue = (value) => {
     if (value === null || typeof value !== 'object')
         return value;
@@ -1169,12 +1161,6 @@ const isolateValue = (value) => {
     }
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > utils > logic > logic.utils.ts
-// Updated: 2026-04-09 18:30
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /**
  * Indicates whether a final pipeline value represents a NOOP condition.
  *
@@ -1184,9 +1170,21 @@ const isolateValue = (value) => {
 const isVaultNoop = (current) => {
     return current === VAULT_NOOP;
 };
+/**
+ * Indicates whether a final pipeline value represents the clear-state sentinel.
+ *
+ * @param current - The computed pipeline result.
+ * @returns `true` if the value is the `VAULT_CLEAR_STATE` sentinel.
+ */
 const isVaultClearState = (current) => {
     return current === VAULT_CLEAR_STATE;
 };
+/**
+ * Indicates whether a final pipeline value represents the continue sentinel.
+ *
+ * @param current - The computed pipeline result.
+ * @returns `true` if the value is the `VAULT_CONTINUE` sentinel.
+ */
 const isVaultContinue = (current) => {
     return current === VAULT_CONTINUE;
 };
@@ -1219,14 +1217,38 @@ const isDefined = (current) => !isUndefined(current);
  * @returns `true` for `null` or `undefined`, otherwise `false`.
  */
 const isNullish = (current) => current == null;
+/**
+ * Determines whether a value is a function.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a function.
+ */
 const isFunction = (value) => typeof value === 'function';
+/**
+ * Determines whether a value is a non-null object.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is an object and not null.
+ */
 const isObject = (value) => typeof value === 'object' && value !== null;
+/**
+ * Determines whether a value is a plain object with no custom prototype.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a plain object.
+ */
 const isPlainObject = (value) => {
     if (value === null || typeof value !== 'object')
         return false;
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 };
+/**
+ * Determines whether a value conforms to the StateInputShape contract.
+ *
+ * @param value - The value to inspect.
+ * @returns `true` if the value is a plain object with recognized state keys or is empty.
+ */
 const isStateInputShape = (value) => {
     if (!isPlainObject(value))
         return false;
@@ -1238,6 +1260,12 @@ const isStateInputShape = (value) => {
     return hasKnownKey || isEmptyObject;
 };
 
+/**
+ * Determines whether a value is a thenable Promise-like object.
+ *
+ * @param value - The value to inspect.
+ * @returns `true` if the value has a callable `then` property.
+ */
 function isPromise(value) {
     return (!!value &&
         (typeof value === 'object' || typeof value === 'function') &&
@@ -1272,22 +1300,10 @@ function isHttpResourceRef(obj) {
         'hasValue' in obj);
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > lib > utils > index.ts
-// Updated: 2026-03-24 09:59
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /* -----------------------------------------------------------
  * UTILITY FUNCTIONS (SAFE TO WILDCARD)
  * --------------------------------------------------------- */
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: libs > shared > src > public-api.ts
-// Updated: 2026-03-23 16:55
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /*
  * Public API Surface of @sdux-vault/shared
  *