@sdux-vault/engine 0.13.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdux-vault/engine",
-  "version": "0.13.0",
+  "version": "0.26.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -9,10 +9,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "private": false,
   "homepage": "https://www.sdux-vault.com",
   "dependencies": {
-    "@sdux-vault/devtools": "0.6.0",
-    "@sdux-vault/shared": "0.5.0",
+    "@sdux-vault/devtools": "0.8.0",
+    "@sdux-vault/shared": "0.7.0",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {
@@ -44,5 +45,6 @@
       "types": "./types/sdux-vault-engine.d.ts",
       "default": "./fesm2022/sdux-vault-engine.mjs"
     }
-  }
+  },
+  "type": "module"
 }

package/types/sdux-vault-engine.d.ts

@@ -1,5 +1,5 @@
 import * as _sdux_vault_shared from '@sdux-vault/shared';
-import { TapCallback, BehaviorClassContract, FeatureCellBaseShape, CoreEmitStateCallback, VaultErrorCallback, FilterFunction, DeferredType, ReducerFunction, InterceptorBehaviorClassContract, OperatorsBehaviorClassContract, ControllerClassContract, ControllerContract, ControllerContext, VaultErrorShape, BehaviorContext, VaultPrivateErrorServiceContract, StateInputType, DecisionOutcomeType, OperationType, VAULT_NOOP, VAULT_CLEAR_STATE, InsightConfig, PipelineValue, StateEmitSnapshotShape, CellBuilderContract, VaultConfig, VaultRegistrationShape, BehaviorClassContext, FinalState } from '@sdux-vault/shared';
+import { TapCallback, BehaviorClassContract, FeatureCellBaseShape, CoreEmitStateCallback, VaultErrorCallback, FilterFunction, DeferredType, StateSnapshotShape, ReducerFunction, StateEmitSnapshotShape, InterceptorBehaviorClassContract, OperatorsBehaviorClassContract, ControllerClassContract, ControllerContract, ControllerContext, VaultErrorShape, BehaviorContext, VaultPrivateErrorServiceContract, StateInputType, DecisionOutcomeType, OperationType, VAULT_NOOP, VAULT_CLEAR_STATE, InsightConfig, PipelineValue, CellBuilderContract, VaultConfig, VaultRegistrationShape, FinalState } from '@sdux-vault/shared';
 import * as rxjs from 'rxjs';
 import { Subject } from 'rxjs';
 
@@ -53,10 +53,21 @@ interface OrchestratorConfig<T> {
      * Initial state value that seeds the FeatureCell.
      */
     initialState: T | DeferredType<T>;
+    /**
+     * Live reference to the FeatureCell's mutable last-snapshot object.
+     * Passed through to behavior constructors so they can commit state
+     * outside the pipeline call stack.
+     */
+    lastSnapshot: StateSnapshotShape<T>;
     /**
      * Reducer callbacks responsible for state transformation.
      */
     reducerCallbacks: ReducerFunction<T>[];
+    /**
+     * Subject used by the FeatureCell to emit state snapshots.
+     * Passed through to behavior constructors.
+     */
+    state$: Subject<StateEmitSnapshotShape<T>>;
     /**
      * Interceptor behavior classes applied before pipeline execution.
      */
@@ -117,9 +128,6 @@ declare const ControllerEventTypes: {
  * Represents the union of all valid controller event type values.
  * This type constrains controller events to the supported identifiers defined by the event type registry.
  *
- * --RelatedStart--
- * ControllerEventTypes
- * --RelatedEnd--
  */
 type ControllerEventType = (typeof ControllerEventTypes)[keyof typeof ControllerEventTypes];
 
@@ -127,9 +135,6 @@ type ControllerEventType = (typeof ControllerEventTypes)[keyof typeof Controller
  * Describes the shape of an event emitted by a controller during execution.
  * This interface defines the minimal contract required to identify the event type, associate it with a trace, and optionally carry error information.
  *
- * --RelatedStart--
- * ControllerEventType
- * --RelatedEnd--
  */
 interface ControllerEventShape {
     /**
@@ -192,28 +197,88 @@ declare class DecisionEngine<T> {
     notifyFinalize(ctx: ControllerContext<T> | BehaviorContext<T>): void;
 }
 
+/**
+ * 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.
+ */
 declare abstract class Orchestrator<T> {
     #private;
+    /** Unique key identifying the FeatureCell that owns this orchestrator. */
     protected cellKey: string;
+    /** Decision engine used for controller vote evaluation. */
     protected decisionEngine: DecisionEngine<T>;
+    /** Global error service for broadcasting errors across FeatureCells. */
     protected privateErrorService: VaultPrivateErrorServiceContract;
+    /** Vault monitor instance for tracing pipeline lifecycle events. */
     protected vaultMonitor: _sdux_vault_shared.VaultMonitorContract;
+    /**
+     * Initializes the orchestrator with configuration callbacks and initial state.
+     *
+     * @param config - Orchestrator configuration containing behaviors and callbacks.
+     */
     constructor(config: OrchestratorConfig<T>);
+    /** Registers all behaviors from the orchestrator configuration. */
     protected initializeOrchestrator(config: OrchestratorConfig<T>): void;
+    /** Loads the initial state and runs the first pipeline cycle. */
     protected initializeFeatureCell(ctx: BehaviorContext<T>): Promise<void>;
+    /** Invokes destroy on all registered behaviors. */
     protected destroyBehaviors(ctx: BehaviorContext<T>): void;
+    /** Invokes reset on all registered behaviors. */
     protected resetBehaviors(ctx: BehaviorContext<T>): void;
+    /** Routes the pipeline context to the appropriate replace or merge orchestration flow. */
     protected orchestrate(ctx: BehaviorContext<T>, options?: unknown): Promise<void>;
+    /**
+     * Builds a controller context from the current behavior context.
+     *
+     * @returns The controller context snapshot.
+     */
     protected buildControllerCtx(ctx: BehaviorContext<T>): ControllerContext<T>;
+    /**
+     * Normalizes an incoming state input into a consistent shape.
+     *
+     * @returns The normalized state input value.
+     */
     protected normalizeIncoming<T>(incoming: StateInputType<T>): StateInputType<T>;
+    /** Notifies the core state behavior of a controller abort or deny outcome. */
     protected controllerOutcomeNotification(type: DecisionOutcomeType, ctx: BehaviorContext<T>): void;
+    /**
+     * Prepares the incoming value and handles noop and clear-state short-circuits.
+     *
+     * @returns The normalized incoming value or undefined for short-circuit paths.
+     */
     protected prepareIncoming(ctx: BehaviorContext<T>, incoming: StateInputType<T>, operation: OperationType): StateInputType<T> | typeof VAULT_NOOP | typeof VAULT_CLEAR_STATE;
 }
 
+/**
+ * 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.
+ */
 declare class Conductor<T> extends Orchestrator<T> {
     #private;
+    /**
+     * Creates a new Conductor and initializes controllers and licensing.
+     *
+     * @param config - Configuration describing behaviors, controllers, and callbacks.
+     */
     constructor(config: ConductorConfig<T>);
+    /**
+     * Enqueues an initialization attempt for the FeatureCell pipeline.
+     *
+     * @param ctx - Behavior context for the initialization cycle.
+     */
     initialize(ctx: BehaviorContext<T>): void;
+    /**
+     * 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: BehaviorContext<T>, incoming: StateInputType<T>, operation: OperationType, options?: unknown): void;
     /**
      * Resets pipeline + controller state for this FeatureCell.
@@ -288,10 +353,6 @@ interface VaultStateRef<T> {
  * Defines the public shape of a Feature Cell with an exposed resolved state reference.
  * This interface extends the base Feature Cell contract by adding access to the reactive state produced by resolution.
  *
- * --RelatedStart--
- * FeatureCellBaseShape
- * VaultStateRef
- * --RelatedEnd--
  */
 interface FeatureCellShape<T> extends FeatureCellBaseShape<T> {
     /**
@@ -300,45 +361,92 @@ interface FeatureCellShape<T> extends FeatureCellBaseShape<T> {
     state: VaultStateRef<T>;
 }
 
+/**
+ * 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.
+ */
 declare abstract class FeatureCellBuilder<T> {
     #private;
     protected readonly featureCellConfiguration: FeatureCellConfig<T>;
     private readonly defaultBehaviors;
     protected readonly behaviors: BehaviorClassContract<T>[];
     protected readonly controllers: ControllerClassContract<T>[];
+    /** Reference to the constructed FeatureCellBaseShape. */
     protected cell: FeatureCellBaseShape<T>;
+    /** Unique key identifying this FeatureCell. */
     protected readonly cellKey: string;
+    /** Shared behavior context for pipeline execution. */
     protected readonly ctx: BehaviorContext<T>;
+    /** Subject signaling cell destruction. */
     protected readonly destroyed$: Subject<void>;
+    /** Subject signaling cell reset. */
     protected readonly reset$: Subject<void>;
+    /** Subject emitting state snapshots to subscribers. */
     protected readonly state$: Subject<StateEmitSnapshotShape<T>>;
+    /**
+     * 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(featureCellConfiguration: FeatureCellConfig<T>, defaultBehaviors: BehaviorClassContract<T>[], behaviors: BehaviorClassContract<T>[], controllers: ControllerClassContract<T>[]);
+    /** Resets the conductor and emits a reset signal. */
     protected reset(): void;
+    /** Destroys the conductor, completes all subjects, and emits destruction signals. */
     protected destroy(): void;
+    /**
+     * Constructs the fluent CellBuilderContract with pre-initialization guards.
+     *
+     * @returns The builder contract exposing configuration and initialize methods.
+     */
     protected setup(): CellBuilderContract<T>;
+    /** Dispatches a merge operation through the conductor pipeline. */
     protected mergeState(incoming: StateInputType<T>, options?: unknown): void;
+    /** Dispatches a replace operation through the conductor pipeline. */
     protected replaceState(incoming: StateInputType<T>, options?: unknown): void;
 }
 
+/**
+ * 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.
+ */
 declare class FeatureCellClass<T> extends FeatureCellBuilder<T> {
+    /**
+     * 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: FeatureCellConfig<T>, defaultBehaviors: BehaviorClassContract<T>[], behaviors: BehaviorClassContract<T>[], controllers: ControllerClassContract<T>[]);
+    /**
+     * Assembles and returns a fully configured FeatureCellShape with fluent API extensions.
+     *
+     * @returns The constructed FeatureCellShape instance.
+     */
     build(): FeatureCellShape<T>;
 }
 
 /**
- * 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)`.
+ * Verifies a signed license payload string.
  *
- * 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.
+ * @param licensePayload - The signed license token to verify.
+ * @returns A promise resolving to true if the license is valid.
+ */
+declare function verifyLicensePayload(licensePayload: string): Promise<boolean>;
+
+/**
+ * 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.
  */
 declare const VerifyLicenseToken: {
     /**
@@ -353,15 +461,45 @@ declare const VerifyLicenseToken: {
     verify: (token: string) => Promise<boolean>;
 };
 
+/** Shape identifying a FeatureCell registered with the runtime. */
 interface RegisteredFeatureCellShape {
+    /** Unique key identifying the registered FeatureCell. */
     key: string;
 }
 
+/**
+ * Initializes the global Vault runtime singleton with the supplied configuration.
+ *
+ * @param config - Optional Vault configuration overriding defaults.
+ */
 declare function VaultCore(config?: VaultConfig): void;
+/**
+ * Registers a FeatureCell entry in the global Vault registry.
+ *
+ * @param entry - Registration descriptor containing the FeatureCell key.
+ */
 declare function registerFeatureCell(entry: RegisteredFeatureCellShape): void;
+/**
+ * Retrieves the decoded license payload for a given license ID.
+ *
+ * @param licenseId - License identifier to look up.
+ * @returns The decoded payload.
+ */
 declare function getLicensePayload(licenseId: string): unknown;
+/** Awaits settled callbacks for all registered FeatureCells. */
 declare function vaultAllSettled(): Promise<void>;
+/**
+ * Awaits the settled callback for a specific FeatureCell.
+ *
+ * @param key - FeatureCell key to await.
+ */
 declare function vaultSettled(key: string): Promise<void>;
+/**
+ * Registers a settled callback for a FeatureCell in the global Vault.
+ *
+ * @param key - FeatureCell key.
+ * @param vaultSettled - Async function invoked when the cell settles.
+ */
 declare function registerVaultSettled(key: string, vaultSettled?: () => Promise<void>): void;
 /**
  * Resets the global Vault configuration for isolated tests.
@@ -369,17 +507,59 @@ declare function registerVaultSettled(key: string, vaultSettled?: () => Promise<
  * This function should **never** be called in production builds.
  */
 declare function resetVaultForTests(): void;
+/** Clears the FeatureCell registration registry. */
 declare function resetFeatureCellRegistry(): void;
+/**
+ * Returns a read-only snapshot of the FeatureCell registry for test inspection.
+ *
+ * @returns A read-only copy of the registry.
+ */
 declare function getVaultRegistryForTests(): ReadonlyMap<string, VaultRegistrationShape> | undefined;
+/**
+ * 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.
+ */
 declare function isAuthorizedKey(key: string): boolean;
+/**
+ * Returns whether licensing checks are currently bypassed.
+ *
+ * @returns True when bypass licensing is active.
+ */
 declare function isBypassLicensing(): boolean;
+/**
+ * Returns whether a Vault-level license has been registered.
+ *
+ * @returns True when a Vault license exists.
+ */
 declare function hasVaultLicense(): boolean;
 
+/**
+ * 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.
+ */
 declare abstract class LicensingAbstract<T> {
     #private;
+    /** Whether this class requires a valid license to operate. */
     static readonly needsLicense: boolean;
+    /** Static key assigned by the VaultBehavior or VaultController decorator. */
     static readonly key: string;
-    constructor(ctx: BehaviorClassContext);
+    /**
+     * 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: {
+        readonly featureCellKey: string;
+        readonly licensePayload?: unknown;
+    });
+    /**
+     * Validates the previously requested license token.
+     *
+     * @param valid - Whether the license should be marked as approved.
+     */
     validateLicense(valid: boolean): void;
 }
 
@@ -415,5 +595,5 @@ declare function getFeatureCellToken(key: string): FeatureCellToken;
  */
 declare const isPipelineTerminal: <T>(current: FinalState<T>) => boolean;
 
-export { Conductor, FeatureCellClass, LicensingAbstract, VAULT_LICENSE_ID, VaultCore, VerifyLicenseToken, createFeatureCellToken, getFeatureCellToken, getLicensePayload, getVaultRegistryForTests, hasVaultLicense, isAuthorizedKey, isBypassLicensing, isPipelineTerminal, registerFeatureCell, registerVaultSettled, resetFeatureCellRegistry, resetVaultForTests, vaultAllSettled, vaultSettled };
+export { Conductor, FeatureCellClass, LicensingAbstract, VAULT_LICENSE_ID, VaultCore, VerifyLicenseToken, createFeatureCellToken, getFeatureCellToken, getLicensePayload, getVaultRegistryForTests, hasVaultLicense, isAuthorizedKey, isBypassLicensing, isPipelineTerminal, registerFeatureCell, registerVaultSettled, resetFeatureCellRegistry, resetVaultForTests, vaultAllSettled, vaultSettled, verifyLicensePayload };
 export type { ConductorConfig, FeatureCellConfig, FeatureCellShape, VaultStateRef };