@sdux-vault/engine 0.25.0 → 0.26.0

package/fesm2022/sdux-vault-engine.mjs

@@ -4,14 +4,10 @@ import { __decorate } from 'tslib';
 import { filter } from 'rxjs/operators';
 import { EventBus, initDevtoolsWidget } from '@sdux-vault/devtools';
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: projects > engine > src > lib > utils > version > version.register.ts
-// Updated: 2026-03-03 08:09
-//	 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/engine';
-const SDUX_VERSION = '0.25.0';
+/** Current package version registered with the Vault runtime. */
+const SDUX_VERSION = '0.26.0';
 registerVersion(SDUX_PACKAGE, SDUX_VERSION);
 
 /**
@@ -24,11 +20,6 @@ var withCoreAbstainController_1;
  * Core abstain controller responsible for participating in controller vote resolution.
  * This controller observes incoming controller messages and emits a neutral vote without modifying pipeline flow.
  *
- * --RelatedStart--
- * ControllerMessageShape
- * ControllerVote
- * ControllerVotes
- * --RelatedEnd--
  */
 let withCoreAbstainController = class withCoreAbstainController {
     static { withCoreAbstainController_1 = this; }
@@ -57,7 +48,9 @@ let withCoreAbstainController = class withCoreAbstainController {
      * Unique controller key identifying this instance.
      */
     key;
+    /** Whether the FeatureCell has completed its initial pipeline cycle. */
     #isInitialized = false;
+    /** Whether the initialization pipeline cycle failed. */
     #initializationFailed = false;
     /**
      * Creates a new core conductor controller instance.
@@ -129,6 +122,11 @@ withCoreAbstainController = withCoreAbstainController_1 = __decorate([
 ], withCoreAbstainController);
 
 var withCoreErrorController_1;
+/**
+ * Core error controller responsible for handling failure messages in the
+ * controller vote resolution pipeline. This controller requests an abort
+ * on failure and abstains from all other message types.
+ */
 let withCoreErrorController = class withCoreErrorController {
     static { withCoreErrorController_1 = this; }
     controllerCtx;
@@ -156,6 +154,7 @@ let withCoreErrorController = class withCoreErrorController {
      * Unique controller key identifying this instance.
      */
     key;
+    /** Controller class context providing execution metadata. */
     ctx;
     /**
      * Creates a new core conductor controller instance.
@@ -208,6 +207,7 @@ withCoreErrorController = withCoreErrorController_1 = __decorate([
     })
 ], withCoreErrorController);
 
+/** Enumeration of license lifecycle event identifiers. */
 const LicenseEventTypes = {
     RequireLicense: 'requireLicense',
     ValidateLicense: 'validateLicense',
@@ -217,38 +217,79 @@ const LicenseEventTypes = {
     DescribeControllers: 'describe-controllers'
 };
 
+/** Cached singleton instance of the licensing service. */
 //eslint-disable-next-line
 let singleton = null;
+/**
+ * Initializes the global licensing service singleton.
+ *
+ * @param events$ - Subject used to emit licensing events.
+ * @param validation$ - Observable providing license validation results.
+ */
 function InitializeLicensingService(events$, validation$) {
     if (singleton)
         return;
     singleton = new LicensingServiceInstance(events$, validation$);
 }
+/**
+ * Returns the global licensing service singleton.
+ *
+ * @returns The initialized licensing service contract.
+ */
 function LicensingService() {
     if (!singleton) {
         throw new Error('[vault] LicensingService not initialized.');
     }
     return singleton;
 }
+/** Internal implementation of the licensing service contract. */
 class LicensingServiceInstance {
     events$;
     validation$;
+    /**
+     * Creates a new licensing service backed by the supplied event streams.
+     *
+     * @param events$ - Subject used to emit licensing events.
+     * @param validation$ - Observable providing license validation results.
+     */
     constructor(events$, validation$) {
         this.events$ = events$;
         this.validation$ = validation$;
     }
+    /**
+     * Emits a feature description event for licensing inspection.
+     *
+     * @param event - Feature description event to emit.
+     */
     describeFeature(event) {
         event.type = LicenseEventTypes.DescribeFeature;
         this.events$.next(event);
     }
+    /**
+     * Emits a behavior description event for licensing inspection.
+     *
+     * @param event - Behavior description event to emit.
+     */
     describeBehaviors(event) {
         event.type = LicenseEventTypes.DescribeBehaviors;
         this.events$.next(event);
     }
+    /**
+     * Emits a controller description event for licensing inspection.
+     *
+     * @param event - Controller description event to emit.
+     */
     describeControllers(event) {
         event.type = LicenseEventTypes.DescribeControllers;
         this.events$.next(event);
     }
+    /**
+     * Requests a license token for a behavior or controller.
+     *
+     * @param featureCellKey - Key of the FeatureCell requesting the license.
+     * @param key - Key of the behavior or controller requiring a license.
+     * @returns The generated license token.
+     */
     requestLicense(featureCellKey, key) {
         if (!key) {
             throw new Error('[vault] Cannot register controller license without a key.');
@@ -262,6 +303,14 @@ class LicensingServiceInstance {
         });
         return licenseToken;
     }
+    /**
+     * Validates a previously requested license token.
+     *
+     * @param featureCellKey - Key of the FeatureCell owning the license.
+     * @param key - Key of the behavior or controller being validated.
+     * @param licenseToken - License token to validate.
+     * @param valid - Whether the license is approved.
+     */
     validateLicense(featureCellKey, key, licenseToken, valid) {
         this.events$.next({
             featureCellKey,
@@ -271,15 +320,22 @@ class LicensingServiceInstance {
             valid
         });
     }
+    /** Generates a random alphanumeric license token. */
     #generateLicenseToken() {
         const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
         const randomPart = (length) => Array.from({ length }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
         return `${randomPart(5)}-${randomPart(5)}`;
     }
+    /**
+     * Returns an observable of license validation results.
+     *
+     * @returns Observable emitting validation outcomes.
+     */
     getLicenseValidation$() {
         return this.validation$;
     }
 }
+/** Resets the licensing service singleton for test isolation. */
 const resetLicensingServiceForTests = () => {
     if (!DevMode.active)
         return;
@@ -287,17 +343,37 @@ const resetLicensingServiceForTests = () => {
 };
 
 var withCoreLicenseController_1;
+/**
+ * Core license controller that gates pipeline execution based on the
+ * licensing service validation result. The controller subscribes to
+ * the license validation stream on construction and votes Deny until
+ * a license decision arrives, Abstain on approval, or Abort on denial.
+ */
 let withCoreLicenseController = class withCoreLicenseController {
     static { withCoreLicenseController_1 = this; }
     controllerCtx;
+    /** Static controller type assigned by the VaultController decorator. */
     static type;
+    /** Static controller key assigned by the VaultController decorator. */
     static key;
+    /** Static critical flag assigned by the VaultController decorator. */
     static critical;
+    /** Instance controller type mirrored from the static declaration. */
     type = withCoreLicenseController_1.type;
+    /** Instance critical flag mirrored from the static declaration. */
     critical = withCoreLicenseController_1.critical;
+    /** Unique key identifying this controller instance. */
     key;
+    /** Resolved license approval state: true, false, or null if pending. */
     #licenseApproved = null;
+    /** Subscription to the licensing validation stream. */
     #sub;
+    /**
+     * Subscribes to the licensing validation stream and signals approval or denial.
+     *
+     * @param key - Unique key for this controller instance.
+     * @param controllerCtx - Controller class context providing lifecycle hooks.
+     */
     constructor(key, controllerCtx) {
         this.controllerCtx = controllerCtx;
         this.key = key;
@@ -317,6 +393,12 @@ let withCoreLicenseController = class withCoreLicenseController {
             }
         });
     }
+    /**
+     * Evaluates a controller message and returns a license-based vote.
+     *
+     * @param msg - The incoming controller message.
+     * @returns An observable emitting the controller vote.
+     */
     handleMessage(msg) {
         vaultDebug(`${this.key} received "${msg.type}" for trace "${msg.traceId}".`);
         switch (msg.type) {
@@ -334,10 +416,12 @@ let withCoreLicenseController = class withCoreLicenseController {
                 return of();
         }
     }
+    /** Unsubscribes from the licensing validation stream. */
     destroy() {
         this.#sub?.unsubscribe();
         vaultWarn(`${this.key} - destroy unsubscribe`);
     }
+    /** No-op reset handler for this controller. */
     reset() {
         vaultWarn(`${this.key} - reset noop`);
     }
@@ -437,28 +521,21 @@ class Arbitrator {
     }
 }
 
-// --- AI Model File Path ---
-// projects > engine > src > lib > types > monitor > vault-monitor-event-category.type.ts
+/** Enumeration of monitor event category classifications. */
 const VaultMonitorEventCategoryType = {
     Boundary: 'boundary',
     State: 'state',
     Error: 'error'
 };
 
-// --- AI Model File Path ---
-// projects > engine > src > lib > types > monitor > vault-monitor-field-rule.type.ts
+/** Enumeration of field emission rules for monitor event policies. */
 const FieldRuleTypes = {
     Never: 'never',
     Optional: 'optional',
     Required: 'required'
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: projects > engine > src > lib > monitor > event-policy > vault-monitor-category-field-policy.constant.ts
-// Updated: 2026-03-06 16:29
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Field emission rules indexed by monitor event category. */
 const CATEGORY_FIELD_POLICY_CONSTANT = {
     [VaultMonitorEventCategoryType.Boundary]: {
         state: FieldRuleTypes.Never,
@@ -477,12 +554,7 @@ const CATEGORY_FIELD_POLICY_CONSTANT = {
     }
 };
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: projects > engine > src > lib > monitor > event-policy > vault-monitor-event-policy.constant.ts
-// Updated: 2026-03-06 16:30
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Maps normalized event names to their monitor event category classification. */
 const EVENT_POLICY_CONSTANT = {
     // ─────────────────────────────────────────────
     // STATE
@@ -564,11 +636,6 @@ const EVENT_POLICY_CONSTANT = {
 let instance$2 = null;
 /**
  * Returns the global VaultMonitorSharedState singleton instance.
- * This function ensures a single shared state instance is created and reused across the runtime.
- *
- * --RelatedStart--
- * VaultMonitorSharedStateInstance
- * --RelatedEnd--
  *
  * @returns The global VaultMonitorSharedState instance.
  */
@@ -578,6 +645,13 @@ function VaultMonitorSharedState() {
     }
     return instance$2;
 }
+/**
+ * Mutable shared state consumed by all VaultMonitor instances.
+ *
+ * This class holds the global insight override and the per-cell
+ * insight registry so that every monitor operates on the same
+ * canonical state.
+ */
 class VaultMonitorSharedStateInstance {
     /**
      * Optional global insight definition that overrides per-cell insight
@@ -589,18 +663,11 @@ class VaultMonitorSharedStateInstance {
      * Registry of FeatureCell insight configurations keyed by cell ID.
      *
      * Each entry indicates whether insight is enabled and contains the
-     * resolved list of {@link InsightConfig} values associated with
-     * that FeatureCell.
+     * resolved list of InsightConfig values associated with that FeatureCell.
      */
     cellRegistry = new Map();
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: projects > engine > src > lib > monitor > vault-monitor.helper.ts
-// Updated: 2026-03-06 16:27
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /**
  * Abstract helper base class used by both `VaultMonitor` and
  * `VaultQueueMonitor`.
@@ -679,9 +746,22 @@ class VaultMonitorHelper {
     activateGlobalInsights(definition) {
         this.globalInsightOverride = definition;
     }
+    /**
+     * Determines whether the given cell key belongs to a Chrome DevTools channel.
+     *
+     * @param cell - The FeatureCell key to check.
+     * @returns True when the cell is a DevTools-internal channel.
+     */
     isChromeDevTools(cell) {
         return cell === DEVTOOLS_LOGGING_KEY_CONSTANT || cell === DEVTOOLS_AGGREGATE_KEY_CONSTANT;
     }
+    /**
+     * Applies field-level emission policy to a pipeline event.
+     *
+     * @param event - The raw event to filter.
+     * @param insight - Optional insight configuration controlling field visibility.
+     * @returns The policy-filtered event.
+     */
     applyPolicy(event, insight) {
         const category = EVENT_POLICY_CONSTANT[event.name]?.category ?? VaultMonitorEventCategoryType.Boundary;
         const policy = CATEGORY_FIELD_POLICY_CONSTANT[category];
@@ -715,12 +795,6 @@ class VaultMonitorHelper {
     }
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: projects > engine > src > lib > monitor > vault-monitor.service.ts
-// Updated: 2026-03-03 09:10
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /**
  * Holds the singleton VaultMonitor instance.
  */
@@ -729,9 +803,6 @@ let instance$1 = null;
  * Returns the global VaultMonitor singleton instance.
  * This function ensures a single monitor instance is created and reused across the runtime.
  *
- * --RelatedStart--
- * VaultMonitorContract
- * --RelatedEnd--
  *
  * @returns The global VaultMonitor instance.
  */
@@ -745,9 +816,6 @@ function VaultMonitor() {
  * Implements the VaultMonitorContract using shared helper functionality.
  * This class provides the concrete singleton implementation backing the VaultMonitor entry point.
  *
- * --RelatedStart--
- * VaultMonitorContract
- * --RelatedEnd--
  */
 class VaultMonitorInstance extends VaultMonitorHelper {
     /**
@@ -769,10 +837,7 @@ class VaultMonitorInstance extends VaultMonitorHelper {
     }
     /**
      * Maps a BehaviorContext into a StateSnapshot suitable for DevTools.
-     * This ensures each pipeline event includes a normalized representation
-     * of loading, value, error, and hasValue.
      *
-     * @typeParam T - State value type.
      * @param ctx - Immutable behavior context provided by the orchestrator.
      * @returns A standardized StateSnapshot.
      */
@@ -1193,50 +1258,60 @@ class VaultMonitorInstance extends VaultMonitorHelper {
         const name = 'warn';
         this.#emitEventV2LifecycleNotification({ cell, behaviorKey, name, ctx, error: errorMessage });
     }
+    /** Prepends event type and boundary to the event name. */
     #buildEventName(eventInput) {
         eventInput.name = `${eventInput.type}:${eventInput.boundary}:${eventInput.name}`;
         return eventInput;
     }
+    /** Emits a stage-start monitoring event. */
     #emitEventV2StageStart(eventInput) {
         eventInput.type = EventTypes.Stage;
         eventInput.boundary = EventBoundaryTypes.Start;
         this.#emitEventV2(this.#buildEventName(eventInput));
     }
+    /** Emits a stage-end monitoring event. */
     #emitEventV2StageEnd(eventInput) {
         eventInput.type = EventTypes.Stage;
         eventInput.boundary = EventBoundaryTypes.End;
         this.#emitEventV2(this.#buildEventName(eventInput));
     }
+    /** Emits a lifecycle-start monitoring event. */
     #emitEventV2LifecycleStart(eventInput) {
         eventInput.type = EventTypes.Lifecycle;
         eventInput.boundary = EventBoundaryTypes.Start;
         this.#emitEventV2(this.#buildEventName(eventInput));
     }
+    /** Emits a lifecycle-end monitoring event. */
     #emitEventV2LifecycleEnd(eventInput) {
         eventInput.type = EventTypes.Lifecycle;
         eventInput.boundary = EventBoundaryTypes.End;
         this.#emitEventV2(this.#buildEventName(eventInput));
     }
+    /** Emits a lifecycle-notification monitoring event. */
     #emitEventV2LifecycleNotification(eventInput) {
         eventInput.type = EventTypes.Lifecycle;
         eventInput.boundary = EventBoundaryTypes.Notification;
         this.#emitEventV2(this.#buildEventName(eventInput));
     }
+    /** Emits a conductor-notification monitoring event. */
     #emitEventV2ConductorNotification(eventInput) {
         eventInput.type = EventTypes.Conductor;
         eventInput.boundary = EventBoundaryTypes.Notification;
         this.#emitEventV2(this.#buildEventName(eventInput));
     }
+    /** Emits a controller-start monitoring event. */
     #emitEventV2ControllerStart(eventInput) {
         eventInput.type = EventTypes.Controller;
         eventInput.boundary = EventBoundaryTypes.Start;
         this.#emitEventV2(this.#buildEventName(eventInput));
     }
+    /** Emits a controller-end monitoring event. */
     #emitEventV2ControllerEnd(eventInput) {
         eventInput.type = EventTypes.Controller;
         eventInput.boundary = EventBoundaryTypes.End;
         this.#emitEventV2(this.#buildEventName(eventInput));
     }
+    /** Emits a controller-notification monitoring event. */
     #emitEventV2ControllerNotification(eventInput) {
         eventInput.type = EventTypes.Controller;
         eventInput.boundary = EventBoundaryTypes.Notification;
@@ -1327,7 +1402,9 @@ const ControllerEventTypes = {
 class DecisionEngine {
     controllers;
     events$;
+    /** Arbitrator responsible for aggregating controller votes. */
     #arbitrator = new Arbitrator();
+    /** Vault monitor instance used to emit controller lifecycle events. */
     #vaultMonitor = VaultMonitor();
     /**
      * Creates a new decision engine instance.
@@ -1472,12 +1549,7 @@ const PROTECTED_FEATURE_CELL_KEYS = new Set([
     'hydrate'
 ]);
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: projects > engine > src > lib > types > vault-registration-license-status.type.ts
-// Updated: 2026-03-03 10:09
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Enumeration of FeatureCell registration license validation statuses. */
 const VaultRegistrationLicenseStatusTypes = {
     NotRequired: 'not-required',
     Pending: 'pending',
@@ -1572,34 +1644,58 @@ const KNOWN_VAULT_KEYS = new Set([
  */
 const VAULT_LICENSE_ID = 'sdux-vault';
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: projects > engine > src > lib > factories > vault > vault-core.function.ts
-// Updated: 2026-03-02 19:52
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/** Behavior key used to identify the core license behavior during validation. */
 const CORE_LICENSE_BEHAVIOR_KEY = 'SDUX::Behavior::Core::License';
+/** Cached singleton instance of the VaultCore runtime. */
 let instance = null;
+/**
+ * Initializes the global Vault runtime singleton with the supplied configuration.
+ *
+ * @param config - Optional Vault configuration overriding defaults.
+ */
 function VaultCore(config = {}) {
     if (!instance) {
         instance = new VaultCoreInstance(config);
     }
 }
+/**
+ * Internal singleton managing Vault configuration, licensing, and the
+ * FeatureCell registry. All mutable state is held in private fields and
+ * exposed only through controlled public methods.
+ */
 class VaultCoreInstance {
+    /** Subscription to the licensing event bus. */
     #licensingSub;
+    /** Subscription to the validation result bus. */
     #validaionSub;
+    /** Map of license IDs to their decoded payloads. */
     #licenseMap = new Map();
+    /** Tracks FeatureCells that have reached a terminal license status. */
     #terminalStatus = new Map();
+    /** Whether AI-assist capabilities have been enabled. */
     #aiAssistEnabled = false;
+    /** Whether licensing checks are bypassed in dev mode. */
     #bypassLicensing = false;
+    /** Timeout duration in milliseconds for pending license evaluations. */
     #licenseTimeoutMs;
+    /** Active timeout handles for pending license evaluations keyed by FeatureCell. */
     // eslint-disable-next-line
     #licenseTimers = new Map();
+    /** Subject emitting licensing events to the licensing service. */
     #licensingBus$ = new Subject();
+    /** ReplaySubject emitting license validation results. */
     #validationBus$ = new ReplaySubject();
+    /** Last published license status per FeatureCell key. */
     #lastStatus = new Map();
+    /** Frozen global Vault configuration. */
     #vaultConfig;
+    /** Registry of FeatureCell registration records keyed by cell key. */
     #registry = new Map();
+    /**
+     * Creates the VaultCore singleton and initializes licensing infrastructure.
+     *
+     * @param config - Raw Vault configuration.
+     */
     constructor(config) {
         InitializeLicensingService(this.#licensingBus$, this.#validationBus$.asObservable());
         this.setVaultConfig(config);
@@ -1634,6 +1730,7 @@ class VaultCoreInstance {
         this.#licenseTimeoutMs = config.licenseTimeoutMs ?? 15_000;
         this.#warnIfAccidentalDevMode();
     }
+    /** Resets all internal state for test isolation. */
     resetForTesting() {
         this.#licensingSub?.unsubscribe();
         this.#licensingSub = undefined;
@@ -1644,40 +1741,87 @@ class VaultCoreInstance {
         this.#lastStatus.clear();
         this.#licenseMap.clear();
     }
+    /** Clears the FeatureCell registration registry. */
     resetFeatureCellRegistry() {
         this.#registry.clear();
     }
+    /**
+     * Registers a FeatureCell key in the runtime registry.
+     *
+     * @param key - Unique FeatureCell identifier.
+     */
     registerCellRuntime(key) {
         this.#ensureRecord(key);
     }
+    /**
+     * Registers behavior entities for a FeatureCell.
+     *
+     * @param key - FeatureCell key.
+     * @param behaviors - Array of behavior entity descriptors.
+     */
     registerBehaviors(key, behaviors) {
         const record = this.#ensureRecord(key);
         record.behaviors = this.#registerEntities(behaviors);
         record.behaviorsRegistered = true;
     }
+    /**
+     * Registers controller entities for a FeatureCell.
+     *
+     * @param key - FeatureCell key.
+     * @param controllers - Array of controller entity descriptors.
+     */
     registerControllers(key, controllers) {
         const record = this.#ensureRecord(key);
         record.controllers = this.#registerEntities(controllers);
         record.controllersRegistered = true;
     }
+    /**
+     * Registers fluent API callback counts for a FeatureCell.
+     *
+     * @param key - FeatureCell key.
+     * @param summary - Object summarizing the count of each fluent API callback type.
+     */
     registerFluentApis(key, summary) {
         const record = this.#ensureRecord(key);
         record.fluentApis = Object.freeze(summary);
     }
+    /**
+     * Retrieves the decoded license payload for a given license ID.
+     *
+     * @param licenseId - License identifier to look up.
+     * @returns The decoded payload, or undefined if not found.
+     */
     getLicensePayload(licenseId) {
         return this.#licenseMap.get(licenseId);
     }
+    /**
+     * Returns whether licensing checks are bypassed.
+     *
+     * @returns True when bypass licensing is active.
+     */
     isBypassLicensing() {
         return this.#bypassLicensing;
     }
+    /**
+     * Checks whether a key belongs to the set of known Vault-internal keys.
+     *
+     * @param key - The key to check.
+     * @returns True when the key is a recognized Vault key.
+     */
     isAuthorizedKey(key) {
         return KNOWN_VAULT_KEYS.has(key);
     }
+    /**
+     * Returns whether a Vault-level license has been registered.
+     *
+     * @returns True when a Vault license exists.
+     */
     hasVaultLicense() {
         return this.#licenseMap.has(VAULT_LICENSE_ID);
     }
     //#endregion
     //#region  private Methods
+    /** Populates the license map from the supplied license configurations. */
     #initializeLicenses(licenses) {
         if (!licenses?.length)
             return;
@@ -1687,6 +1831,7 @@ class VaultCoreInstance {
             this.#licenseMap.set(license.licenseId, license.payload);
         }
     }
+    /** Freezes and registers an array of entity descriptors into a keyed map. */
     #registerEntities(entities) {
         return new Map(entities.map((entity) => {
             let needsLicense;
@@ -1708,6 +1853,7 @@ class VaultCoreInstance {
             return [entity.key, Object.freeze(frozen)];
         }));
     }
+    /** Subscribes to the licensing bus and routes events to the appropriate handlers. */
     #subscribeToLicensingEvents() {
         this.#licensingSub = this.#licensingBus$.subscribe((event) => {
             switch (event.type) {
@@ -1741,6 +1887,7 @@ class VaultCoreInstance {
             }
         });
     }
+    /** Starts a timeout timer for pending licenses on a FeatureCell. */
     #startLicenseTimeout(featureCellKey) {
         if (!this.#licenseTimeoutMs)
             return;
@@ -1752,6 +1899,7 @@ class VaultCoreInstance {
         }, this.#licenseTimeoutMs);
         this.#licenseTimers.set(featureCellKey, timer);
     }
+    /** Expires all pending licenses for a FeatureCell and publishes a denial. */
     #expirePendingLicenses(featureCellKey) {
         const record = this.#registry.get(featureCellKey);
         if (!record)
@@ -1775,6 +1923,7 @@ class VaultCoreInstance {
         this.#clearLicenseTimer(featureCellKey);
     }
     // Do not evaluate until both sides registered
+    /** Evaluates and emits the aggregate license status for a FeatureCell. */
     #emitLicenseStatus(featureCellKey) {
         const record = this.#registry.get(featureCellKey);
         if (!record)
@@ -1804,6 +1953,7 @@ class VaultCoreInstance {
         // All valid
         this.#publishStatus(featureCellKey, true);
     }
+    /** Clears the license timeout timer for a FeatureCell. */
     #clearLicenseTimer(featureCellKey) {
         const timer = this.#licenseTimers.get(featureCellKey);
         if (timer) {
@@ -1811,6 +1961,7 @@ class VaultCoreInstance {
             this.#licenseTimers.delete(featureCellKey);
         }
     }
+    /** Publishes a terminal license validation result for a FeatureCell. */
     #publishStatus(featureCellKey, approved) {
         if (this.#terminalStatus.has(featureCellKey))
             return;
@@ -1822,6 +1973,7 @@ class VaultCoreInstance {
             approved
         });
     }
+    /** Routes a license validation event to the appropriate entity maps. */
     #handleLicenseValidation(event) {
         const { featureCellKey, key, licenseToken, valid } = event;
         if (this.#terminalStatus.has(event.featureCellKey))
@@ -1839,6 +1991,7 @@ class VaultCoreInstance {
             this.#enableAiAssist();
         }
     }
+    /** Applies a license validation result to a single entity within a map. */
     #applyLicenseValidation(entities, key, licenseId, valid) {
         if (!entities?.has(key))
             return;
@@ -1861,6 +2014,7 @@ class VaultCoreInstance {
             validLicense: valid ? VaultRegistrationLicenseStatusTypes.Valid : VaultRegistrationLicenseStatusTypes.Revoked
         }));
     }
+    /** Records a license token against the matching entity in the registry. */
     #recordLicenses(event) {
         const { featureCellKey, key, licenseToken } = event;
         const record = this.#registry.get(featureCellKey);
@@ -1873,6 +2027,7 @@ class VaultCoreInstance {
         this.#recordLicense(record.behaviors, key, licenseToken);
         this.#recordLicense(record.controllers, key, licenseToken);
     }
+    /** Writes a license ID to a single entity if it requires a license. */
     #recordLicense(entities, key, licenseId) {
         if (!entities?.has(key))
             return;
@@ -1890,6 +2045,7 @@ class VaultCoreInstance {
             licenseId
         }));
     }
+    /** Emits a console warning when dev mode is active outside a test environment. */
     #warnIfAccidentalDevMode() {
         if (DevMode.active && !isTestEnv.active) {
             // eslint-disable-next-line
@@ -1899,6 +2055,7 @@ class VaultCoreInstance {
                 `If this is intentional, you can safely ignore this message.`);
         }
     }
+    /** Summarizes fluent API callback counts from a feature description event. */
     #summarizeFluent(event) {
         const fluent = event?.fluentApis ?? {};
         return {
@@ -1910,12 +2067,14 @@ class VaultCoreInstance {
             errorCallbacks: Array.isArray(fluent?.errorCallbacks) ? fluent.errorCallbacks.length : 0
         };
     }
+    /** Returns or creates the registry record for a FeatureCell key. */
     #ensureRecord(key) {
         if (!this.#registry.has(key)) {
             this.#registry.set(key, { key, behaviorsRegistered: false, controllersRegistered: false });
         }
         return this.#registry.get(key);
     }
+    /** Enables AI-assist capabilities when a core license is validated. */
     #enableAiAssist() {
         if (this.#aiAssistEnabled)
             return;
@@ -1930,6 +2089,7 @@ class VaultCoreInstance {
         globalThis.sdux.debugWidget.aiAssistEnabled = true;
         document.dispatchEvent(new CustomEvent('sdux-license-resolved'));
     }
+    /** Injects the DevTools debug widget into the global scope. */
     #injectDebugWidget() {
         if (!DevMode.active)
             return;
@@ -1945,10 +2105,21 @@ class VaultCoreInstance {
     }
     //#endregion
     //#region  Public Testing Method
+    /**
+     * Registers a settled callback for a FeatureCell.
+     *
+     * @param key - FeatureCell key.
+     * @param fn - Async function invoked when the cell settles.
+     */
     registerVaultSettled(key, fn) {
         const record = this.#ensureRecord(key);
         record.vaultSettled = fn;
     }
+    /**
+     * Awaits the settled callback for a specific FeatureCell.
+     *
+     * @param key - FeatureCell key to await.
+     */
     async awaitFeatureCellSettled(key) {
         const record = this.#registry.get(key);
         if (!record) {
@@ -1959,6 +2130,7 @@ class VaultCoreInstance {
             await Promise.resolve(); // flush microtasks
         }
     }
+    /** Awaits settled callbacks for all registered FeatureCells. */
     async awaitAllSettled() {
         for (const record of this.#registry.values()) {
             if (typeof record.vaultSettled === 'function') {
@@ -1968,11 +2140,21 @@ class VaultCoreInstance {
         await Promise.resolve();
     }
     // TESTING ONLY — do not use in production code
+    /**
+     * Returns a shallow clone of the internal registry for test inspection.
+     *
+     * @returns A read-only copy of the FeatureCell registry.
+     */
     getRegistrySnapshot() {
         // Return a shallow cloned map so tests cannot mutate internal state
         return new Map(this.#registry);
     }
 }
+/**
+ * Registers a FeatureCell entry in the global Vault registry.
+ *
+ * @param entry - Registration descriptor containing the FeatureCell key.
+ */
 function registerFeatureCell(entry) {
     if (!instance) {
         throw new Error('[vault] Vault not initialized.');
@@ -1985,6 +2167,12 @@ function registerFeatureCell(entry) {
     }
     instance.registerCellRuntime(entry.key);
 }
+/**
+ * Retrieves the decoded license payload for a given license ID.
+ *
+ * @param licenseId - License identifier to look up.
+ * @returns The decoded payload.
+ */
 function getLicensePayload(licenseId) {
     if (!instance) {
         throw new Error('[vault] Vault not initialized.');
@@ -1994,17 +2182,29 @@ function getLicensePayload(licenseId) {
     }
     return instance.getLicensePayload(licenseId);
 }
+/** Awaits settled callbacks for all registered FeatureCells. */
 async function vaultAllSettled() {
     if (!instance)
         return;
     await instance.awaitAllSettled();
 }
+/**
+ * Awaits the settled callback for a specific FeatureCell.
+ *
+ * @param key - FeatureCell key to await.
+ */
 async function vaultSettled(key) {
     if (!instance) {
         throw new Error('[vault] Vault not initialized.');
     }
     await instance.awaitFeatureCellSettled(key);
 }
+/**
+ * Registers a settled callback for a FeatureCell in the global Vault.
+ *
+ * @param key - FeatureCell key.
+ * @param vaultSettled - Async function invoked when the cell settles.
+ */
 function registerVaultSettled(key, vaultSettled) {
     if (!instance) {
         throw new Error('[vault] Vault not initialized.');
@@ -2028,15 +2228,27 @@ function resetVaultForTests() {
     instance?.resetForTesting();
     instance = null;
 }
+/** Clears the FeatureCell registration registry. */
 function resetFeatureCellRegistry() {
     instance?.resetFeatureCellRegistry();
 }
+/**
+ * Returns a read-only snapshot of the FeatureCell registry for test inspection.
+ *
+ * @returns A read-only copy of the registry.
+ */
 function getVaultRegistryForTests() {
     if (!instance) {
         throw new Error('[vault] Vault not initialized.');
     }
     return instance.getRegistrySnapshot();
 }
+/**
+ * Checks whether a key is authorized by the Vault runtime.
+ *
+ * @param key - The key to check.
+ * @returns True when the key is authorized or licensing is bypassed.
+ */
 function isAuthorizedKey(key) {
     if (!instance)
         return false;
@@ -2044,11 +2256,21 @@ function isAuthorizedKey(key) {
         return true;
     return instance.isAuthorizedKey(key);
 }
+/**
+ * Returns whether licensing checks are currently bypassed.
+ *
+ * @returns True when bypass licensing is active.
+ */
 function isBypassLicensing() {
     if (!instance)
         return false;
     return instance.isBypassLicensing();
 }
+/**
+ * Returns whether a Vault-level license has been registered.
+ *
+ * @returns True when a Vault license exists.
+ */
 function hasVaultLicense() {
     if (!instance)
         return false;
@@ -2366,27 +2588,19 @@ MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAuXto+eRaFm9pObys/IEI ASwV1wgGvNGJsiy
 `
 };
 
-/**
- * Static license verification utility used to validate signed license tokens
- * against tier-specific public keys. Tokens use a dot-separated format:
- * `base64(payload).base64(signature)`.
- *
- * The verification process:
- *  - Splits the token on `.` to extract the encoded payload and signature
- *  - Decodes the payload from base64 to determine the license tier
- *  - Rejects tokens with missing or unrecognized tier
- *  - Loads the appropriate PEM-encoded public key for the tier
- *  - Uses `crypto.subtle.verify()` (RSA-SHA256) to validate the signature
- *    against the raw base64-encoded payload string
- *
- * Verification failures return `false` rather than throwing.
- */
+/** Whether license details have already been logged to the console. */
 let hasLoggedLicenseDetails = false;
+/** Resets the license details log flag for test isolation. */
 function resetLicenseDetailsLog() {
     if (!DevMode.active)
         return;
     hasLoggedLicenseDetails = false;
 }
+/**
+ * Static license verification utility that validates signed license tokens
+ * against tier-specific RSA public keys. Tokens use a dot-separated
+ * base64(payload).base64(signature) format verified via crypto.subtle.
+ */
 const VerifyLicenseToken = {
     /**
      * Verifies the supplied signed license token using the public key associated
@@ -2524,6 +2738,12 @@ function formatLicenseDate(value) {
     }).format(new Date(value));
 }
 
+/**
+ * Verifies a signed license payload string.
+ *
+ * @param licensePayload - The signed license token to verify.
+ * @returns A promise resolving to true if the license is valid.
+ */
 async function verifyLicensePayload(licensePayload) {
     try {
         if (!licensePayload) {
@@ -2536,13 +2756,29 @@ async function verifyLicensePayload(licensePayload) {
     }
 }
 
+/**
+ * Abstract base class providing license lifecycle management for behaviors
+ * and controllers. Subclasses automatically request a license token during
+ * construction when the static `needsLicense` flag is set.
+ */
 class LicensingAbstract {
+    /** Whether this class requires a valid license to operate. */
     static needsLicense;
+    /** Static key assigned by the VaultBehavior or VaultController decorator. */
     static key;
+    /** License token received from the licensing service. */
     #licenseToken;
+    /** Key of the FeatureCell this instance belongs to. */
     #featureCellKey;
+    /** Key identifying this behavior or controller. */
     #key;
+    /** Licensing service used to request and validate licenses. */
     #licenseService;
+    /**
+     * Creates a new licensing-aware instance and requests a license if required.
+     *
+     * @param ctx - Context providing the FeatureCell key and optional license payload.
+     */
     constructor(ctx) {
         const ctor = this.constructor;
         if (typeof ctor.key !== 'string' || !ctor.key.trim()) {
@@ -2555,9 +2791,15 @@ class LicensingAbstract {
             this.#requestLicense();
         }
     }
+    /** Requests a license token from the licensing service. */
     #requestLicense() {
         this.#licenseToken = this.#licenseService.requestLicense(this.#featureCellKey, this.#key);
     }
+    /**
+     * Validates the previously requested license token.
+     *
+     * @param valid - Whether the license should be marked as approved.
+     */
     validateLicense(valid) {
         if (!this.#licenseToken) {
             throw new VaultLicenseError(`validateLicense() called but no license was requested for "${this.#featureCellKey}" and "${this.#key}".`);
@@ -2566,24 +2808,45 @@ class LicensingAbstract {
     }
 }
 
+/**
+ * Core license behavior that validates the vault license payload on
+ * construction. The behavior extends LicensingAbstract to integrate
+ * with the licensing service and gates pipeline execution based on
+ * the asynchronous verification result.
+ */
 let withCoreLicenseBehavior = class withCoreLicenseBehavior extends LicensingAbstract {
     behaviorCtx;
+    /** Static behavior type assigned by the VaultBehavior decorator. */
     static type;
+    /** Static behavior key assigned by the VaultBehavior decorator. */
     static key;
+    /** Static critical flag assigned by the VaultBehavior decorator. */
     static critical;
+    /** Static license requirement flag assigned by the VaultBehavior decorator. */
     static needsLicense;
+    /** Instance behavior type for core license evaluation. */
     type = BehaviorTypes.CoreLicense;
+    /** Instance critical flag indicating this behavior is required. */
     critical = true;
+    /** Unique key identifying this behavior instance. */
     key;
+    /**
+     * Verifies the license payload asynchronously and reports the result.
+     *
+     * @param key - Unique key for this behavior instance.
+     * @param behaviorCtx - Behavior class context providing the license payload.
+     */
     constructor(key, behaviorCtx) {
         super(behaviorCtx);
         this.behaviorCtx = behaviorCtx;
         this.key = key;
         verifyLicensePayload(this.behaviorCtx.licensePayload).then((valid) => this.validateLicense(valid));
     }
+    /** No-op destroy handler for this behavior. */
     destroy() {
         vaultWarn(`${this.key} - destroy noop`);
     }
+    /** No-op reset handler for this behavior. */
     reset() {
         vaultWarn(`${this.key} - reset noop`);
     }
@@ -2598,32 +2861,56 @@ withCoreLicenseBehavior = __decorate([
     })
 ], withCoreLicenseBehavior);
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: lib > src > orchestrator > orchestrator.ts
-// Updated: 2026-04-07 16:30
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/**
+ * Abstract base class that executes the FeatureCell behavior pipeline in
+ * a deterministic stage order. The Orchestrator resolves incoming state,
+ * runs operators, filters, reducers, tap callbacks, and persistence
+ * stages before committing the final state snapshot.
+ */
 class Orchestrator {
+    /** Registered after-tap callback functions executed post-reduce. */
     #afterTapCallbacks;
+    /** Registered before-tap callback functions executed pre-reduce. */
     #beforeTapCallbacks;
+    /** Full set of instantiated behavior instances for this FeatureCell. */
     #behaviors;
+    /** Subset of behaviors eligible for stage-based pipeline execution. */
     #stageBehaviors;
+    /** Unique key identifying the FeatureCell that owns this orchestrator. */
     cellKey;
+    /** Decision engine used for controller vote evaluation. */
     decisionEngine;
+    /** Core error behavior responsible for normalizing pipeline errors. */
     #coreErrorBehavior;
+    /** Error callback behavior for dispatching errors to user callbacks. */
     #coreErrorCallbackBehavior;
+    /** Emit-state callback behavior for notifying state change listeners. */
     #emitStateCallbackBehavior;
+    /** User-provided emit-state callback functions. */
     #emitStateCallbacks;
+    /** Core state behavior managing snapshot commits and signal emission. */
     #coreStateBehavior;
+    /** Error transform behaviors for custom error shaping. */
     #errorTransformBehaviors;
+    /** User-provided error callback functions. */
     #errorCallbacks;
+    /** Global error service for broadcasting errors across FeatureCells. */
     privateErrorService = VaultPrivateErrorService();
+    /** User-provided filter functions applied during the filter stage. */
     #filterFunctions = [];
+    /** Initial state value or deferred factory for this FeatureCell. */
     #initialState;
+    /** Merge behavior responsible for combining partial and current state. */
     #mergeBehavior;
+    /** User-provided reducer functions applied during the reduce stage. */
     #reducerFunctions;
+    /** Vault monitor instance for tracing pipeline lifecycle events. */
     vaultMonitor = VaultMonitor();
+    /**
+     * Initializes the orchestrator with configuration callbacks and initial state.
+     *
+     * @param config - Orchestrator configuration containing behaviors and callbacks.
+     */
     constructor(config) {
         this.#afterTapCallbacks = config.afterTapCallbacks ?? [];
         this.#beforeTapCallbacks = config.beforeTapCallbacks ?? [];
@@ -2634,20 +2921,25 @@ class Orchestrator {
         this.#initialState = config.initialState;
         this.#reducerFunctions = config.reducerCallbacks ?? [];
     }
+    /** Registers all behaviors from the orchestrator configuration. */
     initializeOrchestrator(config) {
         config.behaviors = config.behaviors ?? [];
         this.#registerBehaviors(config);
     }
     //#region  Protected Methods
+    /** Loads the initial state and runs the first pipeline cycle. */
     async initializeFeatureCell(ctx) {
         await this.#loadInitialState(ctx);
     }
+    /** Invokes destroy on all registered behaviors. */
     destroyBehaviors(ctx) {
         this.#destroyBehaviors(ctx);
     }
+    /** Invokes reset on all registered behaviors. */
     resetBehaviors(ctx) {
         this.#resetBehaviors(ctx);
     }
+    /** Routes the pipeline context to the appropriate replace or merge orchestration flow. */
     async orchestrate(ctx, options) {
         // no controllers → pipeline behaves exactly as before
         if (ctx.operation === OperationTypes.Replace) {
@@ -2658,6 +2950,11 @@ class Orchestrator {
         }
         return;
     }
+    /**
+     * Builds a controller context from the current behavior context.
+     *
+     * @returns The controller context snapshot.
+     */
     buildControllerCtx(ctx) {
         return {
             traceId: ctx.traceId,
@@ -2667,6 +2964,11 @@ class Orchestrator {
             operation: ctx.operation
         };
     }
+    /**
+     * Normalizes an incoming state input into a consistent shape.
+     *
+     * @returns The normalized state input value.
+     */
     normalizeIncoming(incoming) {
         if (!incoming)
             return null;
@@ -2680,6 +2982,7 @@ class Orchestrator {
             value: incoming
         };
     }
+    /** Notifies the core state behavior of a controller abort or deny outcome. */
     controllerOutcomeNotification(type, ctx) {
         switch (type) {
             case DecisionOutcomeTypes.Abort: {
@@ -2692,6 +2995,11 @@ class Orchestrator {
             }
         }
     }
+    /**
+     * Prepares the incoming value and handles noop and clear-state short-circuits.
+     *
+     * @returns The normalized incoming value or undefined for short-circuit paths.
+     */
     prepareIncoming(ctx, incoming, operation) {
         ctx = this.#prepIncomingForOrchestration(ctx, incoming, operation);
         const normalizedIncoming = this.#coreStateBehavior.preparePipelineIncoming(ctx);
@@ -2711,12 +3019,14 @@ class Orchestrator {
     }
     //#endregion
     //#region Private Methods
+    /** Attaches incoming, resolve type, and operation to the behavior context. */
     #prepIncomingForOrchestration(ctx, incoming, operation) {
         ctx.incoming = this.normalizeIncoming(incoming);
         ctx.resolveType = this.#getResolveType(incoming);
         ctx.operation = operation;
         return ctx;
     }
+    /** Ensures at most one merge behavior is registered and adds it to the list. */
     #addDefaultMergeBehavior(behaviors, config) {
         const mergeBehaviors = config.behaviors.filter((behaviorClass) => {
             return behaviorClass.type === BehaviorTypes.Merge;
@@ -2734,6 +3044,7 @@ class Orchestrator {
     // ---------------------------------------------------------------------------
     // NORMALIZATION
     // ---------------------------------------------------------------------------
+    /** Assembles the default behavior set from configuration and internal overrides. */
     #defineDefaultBehaviors(config) {
         let defaultBehaviors = config.defaultBehaviors ?? [];
         defaultBehaviors = this.#determineCoreCallbackErrorBehavior(defaultBehaviors, config);
@@ -2742,18 +3053,21 @@ class Orchestrator {
         defaultBehaviors = this.#addCoreLicenseBehavior(defaultBehaviors);
         return defaultBehaviors;
     }
+    /** Removes the error callback behavior when no error callbacks are configured. */
     #determineCoreCallbackErrorBehavior(behaviors, config) {
         if (config?.errorCallbacks?.length === 0) {
             return behaviors.filter((behavior) => behavior.type !== BehaviorTypes.CoreErrorCallback);
         }
         return behaviors;
     }
+    /** Removes the emit-state callback behavior when no emit-state callbacks are configured. */
     #addCoreEmitStateCallbackBehavior(behaviors, config) {
         if (config?.emitStateCallbacks?.length === 0) {
             return behaviors.filter((behavior) => behavior.type !== BehaviorTypes.CoreEmitState);
         }
         return behaviors;
     }
+    /** Conditionally adds the core license behavior when a vault license is active. */
     #addCoreLicenseBehavior(behaviors) {
         behaviors = behaviors?.filter((behavior) => behavior.type !== BehaviorTypes.CoreLicense);
         if (hasVaultLicense()) {
@@ -2761,6 +3075,7 @@ class Orchestrator {
         }
         return behaviors;
     }
+    /** Reports behavior metadata to the licensing service for license validation. */
     #registerBehaviorsWithVault(behaviors) {
         // eslint-disable-next-line
         const behaviorMetadata = behaviors.map((behavior) => {
@@ -2777,6 +3092,7 @@ class Orchestrator {
             behaviors: behaviorMetadata
         });
     }
+    /** Initializes, filters, and registers all behaviors for this FeatureCell. */
     #registerBehaviors(config) {
         const defaultBehaviors = this.#defineDefaultBehaviors(config);
         // Strip out any user-provided reducers; they are passed separately via `reducers`
@@ -2816,6 +3132,7 @@ class Orchestrator {
         this.#registerStateBehavior();
         behaviorInit.applyBehaviorExtensions(this.#behaviors, config.cell, this.vaultMonitor);
     }
+    /** Filters behaviors to only those eligible for stage-based pipeline execution. */
     #registerStageBehaviors() {
         // Remove merge behavior from the pipeline list
         this.#stageBehaviors = this.#behaviors.filter((behavior) => !(behavior.type === BehaviorTypes.CoreState ||
@@ -2826,6 +3143,7 @@ class Orchestrator {
             behavior.type === BehaviorTypes.CoreErrorCallback ||
             behavior.type === BehaviorTypes.Merge));
     }
+    /** Extracts and registers the core state and emit-state callback behaviors. */
     #registerStateBehavior() {
         const tabSyncState = this.#behaviors.filter((behavior) => behavior.type === BehaviorTypes.TabSyncState);
         const coreState = this.#behaviors.filter((behavior) => behavior.type === BehaviorTypes.CoreState);
@@ -2836,6 +3154,7 @@ class Orchestrator {
         this.#coreStateBehavior = stateBehaviors[0] ?? null;
         this.#emitStateCallbackBehavior = this.#behaviors.filter((behavior) => isCoreEmitStateCallbackBehavior(behavior))[0];
     }
+    /** Extracts and registers the core error, error callback, and error transform behaviors. */
     #registerErrorBehavior() {
         // Extract and remove error behavior
         const coreErrors = this.#behaviors.filter((behavior) => behavior.type === BehaviorTypes.CoreError);
@@ -2846,11 +3165,17 @@ class Orchestrator {
         this.#coreErrorCallbackBehavior = this.#behaviors.filter((behavior) => isCoreErrorCallbackBehavior(behavior))[0];
         this.#errorTransformBehaviors = this.#behaviors.filter((behavior) => isErrorTransformBehavior(behavior));
     }
+    /** Extracts and registers the merge behavior from the behavior list. */
     #registerMergeBehavior() {
         // Extract and remove merge behavior
         const merges = this.#behaviors.filter((behavior) => behavior.type === BehaviorTypes.Merge);
         this.#mergeBehavior = merges[0] ?? null;
     }
+    /**
+     * Runs a stepwise behavior and returns its pipeline signal.
+     *
+     * @returns A noop, clear-state, or continue signal.
+     */
     async #runStepwise(behaviorType, ctx, current) {
         const stepwise = await this.#runUpstreamStage(behaviorType, ctx, current);
         if (isVaultClearState(stepwise)) {
@@ -2861,6 +3186,11 @@ class Orchestrator {
         }
         return VAULT_CONTINUE;
     }
+    /**
+     * Runs the post-resolve pipeline stages and returns the final state data.
+     *
+     * @returns The pipeline data flow result or a sentinel signal.
+     */
     async #finishPipeline(ctx, resolved) {
         // Stage: operators
         let pipelineDataFlow;
@@ -2901,6 +3231,7 @@ class Orchestrator {
         // Commit the *cloned* pre-encrypted snapshot to signals
         return stateData;
     }
+    /** Orchestrates a full replace pipeline cycle for the current attempt. */
     async #orchestrateReplace(ctx) {
         this.vaultMonitor.startReplace(this.cellKey, VAULT_ORCHESTRATOR, ctx);
         await this.#safeAsync(async () => {
@@ -2918,6 +3249,7 @@ class Orchestrator {
             return this.#handleFinalState(finalState, ctx);
         }, ctx);
     }
+    /** Orchestrates a full merge pipeline cycle for the current attempt. */
     async #orchestrateMerge(ctx, options) {
         this.vaultMonitor.startMerge(this.cellKey, VAULT_ORCHESTRATOR, ctx);
         await this.#safeAsync(async () => {
@@ -2942,6 +3274,11 @@ class Orchestrator {
             return await this.#handleFinalState(finalState, ctx);
         }, ctx);
     }
+    /**
+     * Emits monitor events for the final pipeline state and returns the result.
+     *
+     * @returns The final state value passed through.
+     */
     async #handleFinalState(finalState, ctx) {
         let payload;
         if (isSignalStop(finalState)) {
@@ -2961,6 +3298,7 @@ class Orchestrator {
         }
         return finalState;
     }
+    /** Wraps an async pipeline function with error handling and state finalization. */
     async #safeAsync(fn, ctx) {
         try {
             const result = await fn();
@@ -2980,6 +3318,11 @@ class Orchestrator {
             await this.decisionEngine?.notifyFailure(this.buildControllerCtx(ctx), pipelineError);
         }
     }
+    /**
+     * Iterates through behaviors matching the given stage and applies each one.
+     *
+     * @returns The accumulated pipeline value after all stage behaviors execute.
+     */
     async #runUpstreamStage(stage, ctx, current) {
         let stageBehaviors;
         if (stage === BehaviorTypes.Resolve) {
@@ -3076,6 +3419,11 @@ class Orchestrator {
         }
         return current;
     }
+    /**
+     * Runs interceptor behaviors and returns a stop signal if any interceptor halts the pipeline.
+     *
+     * @returns Undefined to continue or VAULT_STOP to halt.
+     */
     async #runInterceptorStage(ctx) {
         const interceptorBehaviors = this.#stageBehaviors.filter((behavior) => behavior.type === BehaviorTypes.Interceptor);
         for (const behavior of interceptorBehaviors) {
@@ -3096,10 +3444,16 @@ class Orchestrator {
         }
         return;
     }
+    /** Returns whether any operator behaviors are registered in the pipeline. */
     #containsOperators() {
         const operatorBehaviors = this.#stageBehaviors.filter((behavior) => behavior.type === BehaviorTypes.Operator);
         return operatorBehaviors.length > 0;
     }
+    /**
+     * Runs operator behaviors in sequence and returns the transformed value.
+     *
+     * @returns The pipeline value after all operators execute or undefined on noop.
+     */
     async #runOperatorStage(ctx, current) {
         const operatorBehaviors = this.#stageBehaviors.filter((behavior) => behavior.type === BehaviorTypes.Operator);
         for (const behavior of operatorBehaviors) {
@@ -3122,6 +3476,11 @@ class Orchestrator {
         }
         return current;
     }
+    /**
+     * Runs encrypt and persist behaviors in sequence for state persistence.
+     *
+     * @returns The pipeline persist value after all stage behaviors execute.
+     */
     async #runPersistStage(stage, ctx, current) {
         let stageBehaviors;
         stageBehaviors = this.#stageBehaviors.filter((behavior) => behavior.type === stage);
@@ -3156,6 +3515,7 @@ class Orchestrator {
         }
         return current;
     }
+    /** Invokes destroy on each registered behavior with monitor tracing. */
     #destroyBehaviors(ctx) {
         for (const behavior of this.#behaviors) {
             this.vaultMonitor.startDestroy(this.cellKey, behavior.key, ctx);
@@ -3169,6 +3529,7 @@ class Orchestrator {
             }
         }
     }
+    /** Invokes reset on each registered behavior with monitor tracing. */
     #resetBehaviors(ctx) {
         for (const behavior of this.#behaviors) {
             this.vaultMonitor.startReset(this.cellKey, behavior.key, ctx);
@@ -3182,6 +3543,7 @@ class Orchestrator {
             }
         }
     }
+    /** Runs emit-state callbacks with an isolated snapshot clone. */
     async #runStateBehaviors(ctx) {
         if (this.#emitStateCallbacks?.length > 0) {
             const lastSnapshotClone = isolateValue(ctx.lastSnapshot);
@@ -3193,15 +3555,9 @@ class Orchestrator {
         }
     }
     /**
-     * Runs the error behaviors in sequence.
-     *
-     * - Starts from a normalized ResourceError produced by resourceError().
-     * - Each behavior gets (rawError, currentResourceError, ctx).
-     * - If a behavior returns:
-     *    • ResourceError → becomes the next currentResourceError
-     *    • VAULT_NOOP    → previous ResourceError is kept
+     * Runs error normalization, transforms, state commit, and callbacks in sequence.
      *
-     * Returns void
+     * @returns The final normalized vault error shape.
      */
     async #runErrorBehaviors(rawError, ctx) {
         let current;
@@ -3282,6 +3638,11 @@ class Orchestrator {
         vaultDebug(`${this.cellKey} #runErrorBehaviors completed with final ResourceError: ${JSON.stringify(current)}`);
         return current;
     }
+    /**
+     * Determines the resolve type for the incoming state input.
+     *
+     * @returns The resolve type matching the incoming value shape.
+     */
     #getResolveType(incoming) {
         if (isHttpResourceRef(incoming)) {
             return ResolveTypes.HttpResource;
@@ -3299,6 +3660,7 @@ class Orchestrator {
             return ResolveTypes.Value;
         }
     }
+    /** Loads the initial state from persistence, configuration, or a deferred factory. */
     async #loadInitialState(ctx) {
         const incoming = {
             value: undefined,
@@ -3333,9 +3695,19 @@ class Orchestrator {
             this.decisionEngine?.notifySuccess(this.buildControllerCtx(ctx));
         }
     }
+    /**
+     * Returns persist behaviors registered for this FeatureCell.
+     *
+     * @returns Array of persist behavior instances.
+     */
     #getPersistedBehaviors() {
         return this.#stageBehaviors.filter((behavior) => behavior.type === BehaviorTypes.Persist);
     }
+    /**
+     * Loads persisted state and decrypts it if encryption behaviors are registered.
+     *
+     * @returns The loaded and optionally decrypted state or undefined on failure.
+     */
     async #loadInitialPersistedState(ctx, persistBehaviors) {
         let loaded = undefined;
         for (const behavior of persistBehaviors) {
@@ -3384,6 +3756,7 @@ class Orchestrator {
     }
 }
 
+/** Enumeration of conductor license evaluation statuses. */
 const ConductorLicenseStatusTypes = {
     Pending: 'pending',
     Approved: 'approved',
@@ -3540,20 +3913,32 @@ class ControllerInitializationClass {
     }
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: lib > src > conductor > conductor.ts
-// Updated: 2026-04-07 16:29
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/**
+ * Coordinates pipeline execution, controller arbitration, and license
+ * gating for a single FeatureCell. The Conductor serializes pipeline
+ * attempts through a FIFO queue and delegates vote resolution to the
+ * DecisionEngine.
+ */
 class Conductor extends Orchestrator {
+    /** FIFO queue of pending pipeline attempts awaiting controller evaluation. */
     #attemptQueue = [];
+    /** Instantiated controller instances for this FeatureCell. */
     #controllers = [];
+    /** Subject emitting controller lifecycle events to the decision engine. */
     #events$ = new Subject();
+    /** Whether the conductor is currently processing an attempt. */
     #processing = false;
+    /** Whether the conductor is in a deny state for test flushing. */
     #isDenyStateForTesting = false;
+    /** Current license evaluation status for this conductor. */
     #conductorLicenseStatus = ConductorLicenseStatusTypes.Pending;
+    /** Subject signaling when the conductor has settled for DevMode testing. */
     #settled$ = new Subject();
+    /**
+     * Creates a new Conductor and initializes controllers and licensing.
+     *
+     * @param config - Configuration describing behaviors, controllers, and callbacks.
+     */
     constructor(config) {
         super(config);
         LicensingService().describeFeature({
@@ -3575,6 +3960,11 @@ class Conductor extends Orchestrator {
         this.vaultMonitor.conductorLicenseAttempt(this.cellKey, `${this.cellKey}::license`);
         this.initializeOrchestrator(config);
     }
+    /**
+     * Enqueues an initialization attempt for the FeatureCell pipeline.
+     *
+     * @param ctx - Behavior context for the initialization cycle.
+     */
     initialize(ctx) {
         const initCtx = this.#buildPipelineCtx(ctx, OperationTypes.Initialize, undefined);
         this.#enqueueAttempt({
@@ -3584,6 +3974,14 @@ class Conductor extends Orchestrator {
         });
     }
     //#region public method
+    /**
+     * Enqueues a pipeline attempt for a merge or replace operation.
+     *
+     * @param ctx - Behavior context for the current pipeline cycle.
+     * @param incoming - Incoming state input value.
+     * @param operation - Pipeline operation type.
+     * @param options - Optional merge or replace options.
+     */
     conduct(ctx, incoming, operation, options) {
         const behaviorCtx = this.#buildPipelineCtx(ctx, operation, options);
         const preparedIncoming = this.prepareIncoming(behaviorCtx, incoming, operation);
@@ -3626,6 +4024,7 @@ class Conductor extends Orchestrator {
     }
     //#endregion
     //#region Private Methods
+    /** Routes a pipeline attempt to the appropriate orchestrator method. */
     async #processEvent(ctx, options) {
         if (ctx.operation === OperationTypes.Initialize) {
             await this.initializeFeatureCell(ctx);
@@ -3638,6 +4037,7 @@ class Conductor extends Orchestrator {
         this.vaultMonitor.runtimeError(this.cellKey, VAULT_CONDUCTOR, ctx, new Error(`Unknown operation type: "${ctx.operation}"`));
         this.#completeCurrentAttempt(ctx);
     }
+    /** Schedules a microtask to signal a deny-state completion. */
     #enqueueMicrotask() {
         queueMicrotask(() => {
             this.#denyAttemptCompleted();
@@ -3669,6 +4069,7 @@ class Conductor extends Orchestrator {
             this.#enqueueMicrotask();
         }
     }
+    /** Finalizes the current attempt and advances the queue in a microtask. */
     #completeCurrentAttempt(ctx) {
         const head = this.#attemptQueue[0];
         /* istanbul ignore next */
@@ -3723,6 +4124,7 @@ class Conductor extends Orchestrator {
             this.#processQueue();
         });
     }
+    /** Resets the processing flag and emits a restart-attempt monitor event. */
     #resetProcessingState(ctx, outcome) {
         this.vaultMonitor.restartControllerAttempt(this.cellKey, ctx.traceId, ctx, outcome);
         this.#processing = false;
@@ -3819,6 +4221,7 @@ class Conductor extends Orchestrator {
             this.#processQueue();
         }
     }
+    /** Registers the decision engine and subscribes to controller lifecycle events. */
     #registerDecisionEngine() {
         this.decisionEngine = new DecisionEngine(this.#controllers, this.#events$);
         this.#events$.subscribe({
@@ -3886,6 +4289,7 @@ class Conductor extends Orchestrator {
             }
         });
     }
+    /** Builds an isolated pipeline context for a single attempt. */
     #buildPipelineCtx(ctx, operation, options) {
         const traceId = assignTraceId();
         return {
@@ -3904,10 +4308,12 @@ class Conductor extends Orchestrator {
             incoming: undefined
         };
     }
+    /** Clears the attempt queue and resets the processing flag. */
     #resetConductor() {
         this.#attemptQueue.length = 0;
         this.#processing = false;
     }
+    /** Invokes destroy on all registered controllers. */
     #destroyControllers(ctx) {
         for (const controller of this.#controllers) {
             this.vaultMonitor.startDestroy(this.cellKey, controller.key, ctx);
@@ -3921,6 +4327,7 @@ class Conductor extends Orchestrator {
             }
         }
     }
+    /** Invokes reset on all registered controllers. */
     #resetControllers(ctx) {
         for (const controller of this.#controllers) {
             this.vaultMonitor.startReset(this.cellKey, controller.key, ctx);
@@ -3934,6 +4341,7 @@ class Conductor extends Orchestrator {
             }
         }
     }
+    /** Adds the default or user-supplied error controller to the controller list. */
     #addDefaultErrorController(controllers, config) {
         const errorControllers = config.controllers.filter((controllerClass) => {
             return controllerClass.type === ControllerTypes.Error;
@@ -3949,6 +4357,7 @@ class Conductor extends Orchestrator {
             controllers.unshift(withCoreErrorController);
         }
     }
+    /** Removes reserved controller types from the user-supplied list. */
     #filterRestrictedControllers(controllers) {
         return controllers.filter((controller) => {
             if (controller.type === ControllerTypes.License || controller.type === ControllerTypes.CoreAbstain) {
@@ -3961,6 +4370,7 @@ class Conductor extends Orchestrator {
     // ---------------------------------------------------------------------------
     // INTERNAL SCHEDULING
     // ---------------------------------------------------------------------------
+    /** Initializes all controllers and registers the decision engine. */
     #registerControllers(config) {
         config.controllers = config.controllers ?? [];
         const allControllers = this.#filterRestrictedControllers(config.controllers);
@@ -4001,12 +4411,14 @@ class Conductor extends Orchestrator {
             this.vaultMonitor.endControllerVote(this.cellKey, pending.controllerCtx.traceId, pending.controllerCtx, decision);
         }), map((decision) => decision.outcome));
     }
+    /** Signals a deny-state settlement for DevMode testing. */
     #denyAttemptCompleted() {
         if (!DevMode.active)
             return;
         this.#settled$.next();
     }
     // ADD
+    /** Signals queue settlement when all attempts have been processed. */
     #attemptCompleted() {
         if (!DevMode.active || this.#attemptQueue.length > 0)
             return;
@@ -4014,6 +4426,7 @@ class Conductor extends Orchestrator {
             this.#settled$.next();
         });
     }
+    /** Returns a promise that resolves when the conductor has settled. */
     #conductorSettled() {
         return firstValueFrom(this.#settled$);
     }
@@ -4065,27 +4478,46 @@ function featureCellValidation(descriptor, behaviors = []) {
     }
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: projects > engine > src > lib > factories > feature-cell > feature-cell.builder.ts
-// Updated: 2026-03-02 19:52
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/**
+ * Abstract builder that assembles the fluent configuration API and
+ * lifecycle wiring for a FeatureCell. Subclasses call setup() to obtain
+ * a CellBuilderContract, then build the final FeatureCellShape from it.
+ * The builder manages conductor creation, initialization guards, and
+ * state operation dispatch.
+ */
 class FeatureCellBuilder {
     featureCellConfiguration;
     defaultBehaviors;
     behaviors;
     controllers;
+    /** Whether the cell encountered a critical failure and is permanently unusable. */
     #cellCorrupt = false;
+    /** Conductor instance managing pipeline execution for this cell. */
     #conductor;
+    /** Whether the cell has been initialized via the builder. */
     #initialized = false;
+    /** Vault monitor instance for tracing lifecycle events. */
     #vaultMonitor = VaultMonitor();
+    /** Reference to the constructed FeatureCellBaseShape. */
     cell;
+    /** Unique key identifying this FeatureCell. */
     cellKey;
+    /** Shared behavior context for pipeline execution. */
     ctx;
+    /** Subject signaling cell destruction. */
     destroyed$ = new Subject();
+    /** Subject signaling cell reset. */
     reset$ = new Subject();
+    /** Subject emitting state snapshots to subscribers. */
     state$ = new Subject();
+    /**
+     * Creates the builder and initializes the shared behavior context.
+     *
+     * @param featureCellConfiguration - FeatureCell descriptor configuration.
+     * @param defaultBehaviors - Default behavior classes provided by the framework.
+     * @param behaviors - User-supplied behavior classes.
+     * @param controllers - User-supplied controller classes.
+     */
     constructor(
     // kept for parity with original API, even if not used directly
     featureCellConfiguration, defaultBehaviors, behaviors, controllers) {
@@ -4096,6 +4528,11 @@ class FeatureCellBuilder {
         this.cellKey = this.featureCellConfiguration.key;
         this.ctx = this.#buildCtx();
     }
+    /**
+     * Builds the initial behavior context with locked snapshot reference.
+     *
+     * @returns The constructed behavior context.
+     */
     #buildCtx() {
         const destroyed$ = this.destroyed$.asObservable();
         const state$ = this.state$;
@@ -4133,6 +4570,7 @@ class FeatureCellBuilder {
     // ---------------------------------------------------------------------------
     // INTERNAL LIFECYCLE
     // ---------------------------------------------------------------------------
+    /** Resets the conductor and emits a reset signal. */
     reset() {
         this.#vaultMonitor.startReset(this.cellKey, VAULT_FEATURE_CELL, this.ctx);
         vaultWarn(`${VAULT_FEATURE_CELL}: reset`);
@@ -4141,6 +4579,7 @@ class FeatureCellBuilder {
         this.#conductor?.reset(this.ctx);
         this.#vaultMonitor.endReset(this.cellKey, VAULT_FEATURE_CELL, this.ctx);
     }
+    /** Destroys the conductor, completes all subjects, and emits destruction signals. */
     destroy() {
         this.#vaultMonitor.startDestroy(this.cellKey, VAULT_FEATURE_CELL, this.ctx);
         vaultWarn(`${VAULT_FEATURE_CELL}: destroy`);
@@ -4152,6 +4591,7 @@ class FeatureCellBuilder {
         this.state$.complete();
         this.#vaultMonitor.endDestroy(this.cellKey, VAULT_FEATURE_CELL, this.ctx);
     }
+    /** Throws if the cell is corrupt or has not been initialized. */
     #ensureInitialized() {
         if (this.#cellCorrupt) {
             const errorMessage = `[vault] FeatureCell "${this.featureCellConfiguration.key}" encountered a critical initialization failure and is now in a corrupted state. Further use is blocked.`;
@@ -4164,6 +4604,7 @@ class FeatureCellBuilder {
             throw new Error(errorMessage);
         }
     }
+    /** Creates the conductor, validates the cell, and starts the initialization lifecycle. */
     #initialize(ctx) {
         if (this.#initialized) {
             const errorMessage = `[vault] FeatureCell "${this.featureCellConfiguration.key}" already initialized.`;
@@ -4216,11 +4657,17 @@ class FeatureCellBuilder {
             throw err;
         }
     }
+    /** Marks the cell as corrupt, logs a runtime error, and throws. */
     #handleCorruptionError(message) {
         this.#cellCorrupt = true;
         this.#vaultMonitor.runtimeError(this.cellKey, VAULT_FEATURE_CELL, this.ctx, message);
         throw new Error(message);
     }
+    /**
+     * Constructs the fluent CellBuilderContract with pre-initialization guards.
+     *
+     * @returns The builder contract exposing configuration and initialize methods.
+     */
     setup() {
         const afterTapCallbacks = [];
         const beforeTapCallbacks = [];
@@ -4333,26 +4780,41 @@ class FeatureCellBuilder {
     // ---------------------------------------------------------------------------
     // STATE OPERATIONS
     // ---------------------------------------------------------------------------
+    /** Dispatches a merge operation through the conductor pipeline. */
     mergeState(incoming, options) {
         this.#ensureInitialized();
         return this.#conductor.conduct(this.ctx, incoming, OperationTypes.Merge, options);
     }
+    /** Dispatches a replace operation through the conductor pipeline. */
     replaceState(incoming, options) {
         this.#ensureInitialized();
         return this.#conductor.conduct(this.ctx, incoming, OperationTypes.Replace, options);
     }
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: projects > engine > src > lib > factories > feature-cell > feature-cell.class.ts
-// Updated: 2026-03-02 19:52
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
+/**
+ * Concrete FeatureCell factory that extends the builder to produce a
+ * fully configured FeatureCellShape instance. The class wires fluent
+ * API extensions from behaviors and controllers onto the resulting
+ * cell and attaches non-enumerable context and key properties.
+ */
 class FeatureCellClass extends FeatureCellBuilder {
+    /**
+     * Creates a new FeatureCellClass with the provided descriptor and behavior/controller lists.
+     *
+     * @param descriptor - FeatureCell configuration descriptor.
+     * @param defaultBehaviors - Default behavior classes provided by the framework.
+     * @param behaviors - User-supplied behavior classes.
+     * @param controllers - User-supplied controller classes.
+     */
     constructor(descriptor, defaultBehaviors, behaviors, controllers) {
         super(descriptor, defaultBehaviors, behaviors, controllers);
     }
+    /**
+     * Assembles and returns a fully configured FeatureCellShape with fluent API extensions.
+     *
+     * @returns The constructed FeatureCellShape instance.
+     */
     build() {
         const builder = this.setup();
         const ctx = this.ctx;
@@ -4483,12 +4945,6 @@ function resetFeatureCellToken() {
     featureCellTokenRequested.clear();
 }
 
-// --- AI Model File Path (DO NOT DELETE) ---
-// FilePath: lib > public-api.ts
-// Updated: 2026-03-30 15:42
-//	 Generated by pathcomment [tab] (see .vscode/typescript.code-snippets) or
-//	 cmd+alt+j (see .vscode/keybindings.json)
-// --- END AI MODEL FILE PATH ---
 /*
  * This is for version support in dev mode and tracking in the devtools
  */