@kosdev-code/kos-ui-sdk 0.1.0-dev.5072 → 0.1.0-dev.5092

package/core/core/companion-instantiator.d.ts

@@ -0,0 +1,71 @@
+import { IKosRegistry } from './types';
+import { KosModelCacheHandler } from './model-cache';
+import { IKosModel } from './kosModel';
+import { DependencyLifecycle } from '../types';
+
+/**
+ * Handles creation and lifecycle management of companion models.
+ * Companions are models that extend or enhance parent models and can be
+ * created at specific lifecycle phases based on decorator configuration.
+ */
+export declare class KosCompanionInstantiator {
+    private registry;
+    private cache;
+    private createModel;
+    constructor(registry: IKosRegistry, cache: KosModelCacheHandler, createModel: (typeId: string, id: string, options: Record<string, any>) => any);
+    /**
+     * Creates companion models for a parent model, optionally filtered by lifecycle phase.
+     * Called automatically during instantiation for companions without lifecycle specified.
+     * Can be called from lifecycle hooks to create lifecycle-deferred companions.
+     *
+     * @param model The parent model
+     * @param options Options to pass to companion constructors
+     * @param lifecycle Optional lifecycle filter - only create companions matching this phase
+     */
+    createCompanionModels(model: IKosModel, options: Record<string, any>, lifecycle?: DependencyLifecycle): void;
+    /**
+     * Get companion definitions for a parent model type
+     */
+    private getCompanionDefinitions;
+    /**
+     * Resolve companion type from definition and extract lifecycle metadata
+     */
+    private resolveCompanionType;
+    /**
+     * Resolve factory companion by calling factory and extracting lifecycle
+     */
+    private resolveFactoryCompanion;
+    /**
+     * Resolve string companion using pre-extracted lifecycle from registration
+     */
+    private resolveStringCompanion;
+    /**
+     * Extract lifecycle metadata from companion model decorator
+     */
+    private extractLifecycleFromType;
+    /**
+     * Determine if companion should be created based on lifecycle filtering
+     */
+    private shouldCreateCompanion;
+    /**
+     * Instantiate and attach companion to parent model
+     */
+    private instantiateCompanion;
+    /**
+     * Generate unique companion ID
+     */
+    private generateCompanionId;
+    /**
+     * Check if companion already exists in cache
+     */
+    private companionAlreadyExists;
+    /**
+     * Create companion model instance with parent context
+     */
+    private createCompanionInstance;
+    /**
+     * Attach companion to parent model
+     */
+    private attachCompanionToParent;
+}
+//# sourceMappingURL=companion-instantiator.d.ts.map

package/core/core/companion-instantiator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-instantiator.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/core/companion-instantiator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAA6B,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAIvE;;;;GAIG;AACH,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,WAAW;gBAFX,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,oBAAoB,EAC3B,WAAW,EAAE,CACnB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KACzB,GAAG;IAGV;;;;;;;;OAQG;IACH,qBAAqB,CACnB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,SAAS,CAAC,EAAE,mBAAmB;IAyBjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAI/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAqB/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAU9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAWhC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAa7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAsC5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAc9B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAe/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAOhC"}

package/core/core/decorators/fsm-injection-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Main coordinator for injecting FSM support into a model instance.
+ * Delegates to Zone 3 functions for actual implementation.
+ *
+ * @param modelInstance The model instance to inject FSM support into
+ */
+export declare function injectStateMachineSupport(modelInstance: any): void;
+/**
+ * Initialize the state machine at a specific lifecycle phase.
+ * Called from KosModel lifecycle hooks.
+ *
+ * @param modelInstance The model instance
+ * @param lifecycle The current lifecycle phase
+ */
+export declare function initializeStateMachine(modelInstance: any, lifecycle: string): void;
+//# sourceMappingURL=fsm-injection-utils.d.ts.map

package/core/core/decorators/fsm-injection-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsm-injection-utils.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/fsm-injection-utils.ts"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,GAAG,QAoB3D;AAmZD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,QA0B3E"}

package/core/core/decorators/index.d.ts

@@ -1,3 +1,4 @@
+export * from './fsm-injection-utils';
 export * from './kos-child';
 export * from './kos-companion';
 export * from './kos-container-aware';
@@ -12,6 +13,7 @@ export * from './kos-model-effect';
 export * from './kos-parent';
 export * from './kos-reference';
 export * from './kos-service-request';
+export * from './kos-state-machine';
 export * from './kos-trouble-aware';
 export * from './kosDependency';
 export * from './kosModel';

package/core/core/decorators/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/core/core/decorators/kos-companion.d.ts

@@ -1,4 +1,5 @@
 import { IKosDataModel } from '../kosModel';
+import { DependencyLifecycle } from '../../types';
 
 export interface KosCompanionOptions {
     /**
@@ -11,6 +12,20 @@ export interface KosCompanionOptions {
     excludeProperties?: string[];
     /** Custom parent property name. Default: 'companionParent' */
     parentProperty?: string;
+    /**
+     * Lifecycle phase at which this companion should be created.
+     * Defaults to INIT (created immediately during parent instantiation).
+     * Use LOAD to create after parent's load() completes, READY for after ready(), etc.
+     *
+     * @example
+     * ```typescript
+     * @kosCompanion({ lifecycle: DependencyLifecycle.LOAD })
+     * class CarbAgitatorModel implements IKosDataModel {
+     *   // Created after assembly.load() completes
+     * }
+     * ```
+     */
+    lifecycle?: DependencyLifecycle;
 }
 /**
  * Base interface for all companion models.
@@ -119,6 +134,10 @@ export interface KosCompanionDecorator<TParent extends IKosDataModel = IKosDataM
  * // Decorator mode with exclusions
  * @kosCompanion({ mode: 'decorator', excludeProperties: ['internalState'] })
  * class MyCompanion { }
+ *
+ * // Lifecycle-deferred companion creation
+ * @kosCompanion({ lifecycle: DependencyLifecycle.LOAD })
+ * class DataDrivenCompanion { }
  * ```
  *
  * @category KOS Model Decorator

package/core/core/decorators/kos-companion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-companion.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-companion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IACnC,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAChC,OAAO,SAAS,aAAa,GAAG,aAAa;IAE7C;;;;;;OAMG;IACH,kBAAkB,IAAI,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,uBAAuB,CACtC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAAG;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,qBAAqB,CACpC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAGnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAmB1E"}
+{"version":3,"file":"kos-companion.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-companion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IACnC,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAChC,OAAO,SAAS,aAAa,GAAG,aAAa;IAE7C;;;;;;OAMG;IACH,kBAAkB,IAAI,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,uBAAuB,CACtC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAAG;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,qBAAqB,CACpC,OAAO,SAAS,aAAa,GAAG,aAAa,CAC7C,SAAQ,iBAAiB,CAAC,OAAO,CAAC;CAGnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAqB1E"}

package/core/core/decorators/kos-state-machine.d.ts

@@ -0,0 +1,466 @@
+import { DependencyLifecycle } from '../../types';
+
+/**
+ * Configuration for a KOS state machine.
+ *
+ * @template TState Union type of valid state strings
+ * @template TEvent Union type of valid event strings
+ *
+ * @example
+ * ```typescript
+ * const config: KosStateMachineConfig<'idle' | 'active', 'START' | 'STOP'> = {
+ *   initial: 'idle',
+ *   initializeAt: DependencyLifecycle.READY,
+ *   states: {
+ *     idle: { on: { START: 'active' } },
+ *     active: { on: { STOP: 'idle' } }
+ *   }
+ * };
+ * ```
+ */
+export interface KosStateMachineConfig<TState extends string, TEvent extends string> {
+    /**
+     * The initial state when the state machine is initialized.
+     * This state will be set when the FSM reaches its configured lifecycle phase.
+     */
+    initial: TState;
+    /**
+     * The lifecycle phase at which the state machine should be initialized.
+     * Before this phase, currentState will be undefined and isFsmInitialized will be false.
+     *
+     * @default DependencyLifecycle.READY
+     *
+     * @example
+     * ```typescript
+     * // FSM initializes when model is ready (most common)
+     * initializeAt: DependencyLifecycle.READY
+     *
+     * // FSM initializes only when UI activates the model
+     * initializeAt: DependencyLifecycle.ACTIVATE
+     *
+     * // FSM initializes during model initialization (rare)
+     * initializeAt: DependencyLifecycle.INIT
+     * ```
+     */
+    initializeAt?: DependencyLifecycle;
+    /**
+     * State machine definition mapping states to their allowed transitions.
+     *
+     * @example
+     * ```typescript
+     * states: {
+     *   idle: { on: { PREPARE: 'preparing' } },
+     *   preparing: { on: { READY: 'ready', ERROR: 'error' } },
+     *   ready: { on: { POUR: 'pouring' } },
+     *   pouring: { on: { COMPLETE: 'idle', ERROR: 'error' } },
+     *   error: { on: { RESET: 'idle' } }
+     * }
+     * ```
+     */
+    states: Record<TState, {
+        /**
+         * Mapping of events to target states.
+         * When an event occurs in this state, transition to the target state.
+         */
+        on?: Partial<Record<TEvent, TState>>;
+    }>;
+}
+/**
+ * Options for configuring state machine behavior.
+ */
+export interface KosStateMachineOptions {
+    /**
+     * Property name for storing the current state.
+     *
+     * @default "currentState"
+     */
+    stateProperty?: string;
+    /**
+     * Whether to track state history.
+     * When enabled, a stateHistory array is maintained with timestamps and events.
+     *
+     * @default false
+     */
+    trackHistory?: boolean;
+    /**
+     * Whether to throw errors on invalid transitions.
+     * When false, invalid transitions are logged as warnings instead.
+     *
+     * @default true
+     */
+    throwOnInvalid?: boolean;
+}
+/**
+ * Interface for models using the @kosStateMachine decorator.
+ *
+ * **IMPORTANT**: Use TypeScript interface merging to add FSM properties to your model class.
+ * This provides full type safety and IntelliSense support for all injected FSM functionality.
+ *
+ * ## Interface Merging Pattern
+ *
+ * ```typescript
+ * // 1. Define state and event types
+ * type PourState = 'idle' | 'preparing' | 'ready' | 'pouring' | 'error';
+ * type PourEvent = 'PREPARE' | 'READY' | 'POUR' | 'COMPLETE' | 'ERROR';
+ *
+ * // 2. Declare interface merging BEFORE the class
+ * interface DispenserModelImpl extends KosStateMachineAware<PourState, PourEvent> {}
+ *
+ * // 3. Apply decorators and implement the class
+ * @kosModel({ modelTypeId: "dispenser-model" })
+ * @kosStateMachine<PourState, PourEvent>({
+ *   initial: 'idle',
+ *   initializeAt: DependencyLifecycle.READY,
+ *   states: {
+ *     idle: { on: { PREPARE: 'preparing' } },
+ *     preparing: { on: { READY: 'ready', ERROR: 'error' } },
+ *     ready: { on: { POUR: 'pouring' } },
+ *     pouring: { on: { COMPLETE: 'idle', ERROR: 'error' } },
+ *     error: {}
+ *   }
+ * })
+ * export class DispenserModelImpl implements IKosDataModel {
+ *   // All FSM properties are now available with full type safety
+ * }
+ * ```
+ *
+ * ## Lifecycle-Aware Initialization
+ *
+ * The FSM is uninitialized until the configured lifecycle phase:
+ * - Before initialization: `currentState === undefined`, `isFsmInitialized === false`
+ * - After initialization: `currentState === initial`, `isFsmInitialized === true`
+ *
+ * ```typescript
+ * @kosStateMachine({
+ *   initial: 'idle',
+ *   initializeAt: DependencyLifecycle.READY, // FSM starts when model is ready
+ *   states: { ... }
+ * })
+ * class MyModel {
+ *   async ready(): Promise<void> {
+ *     // Before this completes: this.currentState === undefined
+ *     // After this completes: this.currentState === 'idle'
+ *   }
+ * }
+ * ```
+ *
+ * ## Injected Properties and Methods
+ *
+ * The decorator automatically injects the following members:
+ *
+ * - **`currentState`**: Current state (undefined until FSM initialized, observable)
+ * - **`isFsmInitialized`**: Boolean indicating if FSM has been initialized
+ * - **`isTransitioning`**: Boolean indicating if a transition is in progress
+ * - **`allowedTransitions`**: Computed array of valid events for current state
+ * - **`transition(event)`**: Method to trigger state transitions
+ * - **`canTransition(event)`**: Check if a transition is valid from current state
+ * - **`isInState(state)`**: Check if currently in a specific state
+ * - **`stateHistory`**: Array of historical states (if trackHistory enabled)
+ *
+ * All properties are reactive and will automatically update UI components when state changes.
+ *
+ * @template TState Union type of valid state strings
+ * @template TEvent Union type of valid event strings
+ *
+ * @see {@link kosStateMachine} - The decorator function
+ * @see {@link KosStateMachineConfig} - Configuration interface
+ * @see {@link KosStateMachineOptions} - Options interface
+ */
+export interface KosStateMachineAware<TState extends string, TEvent extends string> {
+    /**
+     * Current state of the state machine.
+     * Observable property that updates automatically via @kosModel.
+     * Always initialized to the initial state immediately.
+     */
+    currentState: TState;
+    /**
+     * Indicates whether the state machine has been initialized.
+     * FSM initializes at the configured lifecycle phase (READY, ACTIVATE, etc.).
+     *
+     * - Before initialization: `false`, `currentState === undefined`
+     * - After initialization: `true`, `currentState === initial`
+     */
+    readonly isFsmInitialized: boolean;
+    /**
+     * Indicates whether a state transition is currently in progress.
+     * Observable property that updates during transitions.
+     */
+    isTransitioning: boolean;
+    /**
+     * Computed array of valid events that can be triggered from the current state.
+     * Updates automatically when state changes.
+     * Returns empty array if FSM is not initialized.
+     */
+    readonly allowedTransitions: TEvent[];
+    /**
+     * Trigger a state transition by event.
+     *
+     * @param event The event to trigger
+     * @throws Error if FSM not initialized (unless `throwOnInvalid` is false)
+     * @throws Error if transition is invalid (unless `throwOnInvalid` is false)
+     *
+     * @example
+     * ```typescript
+     * this.transition('START'); // idle -> active
+     * this.transition('STOP');  // active -> idle
+     * ```
+     */
+    transition(event: TEvent): void;
+    /**
+     * Check if a transition is valid from the current state.
+     * Returns false if FSM is not initialized.
+     *
+     * @param event The event to check
+     * @returns true if the transition is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (this.canTransition('START')) {
+     *   this.transition('START');
+     * }
+     * ```
+     */
+    canTransition(event: TEvent): boolean;
+    /**
+     * Check if the state machine is currently in a specific state.
+     * Returns false if FSM is not initialized.
+     *
+     * @param state The state to check
+     * @returns true if currently in the specified state, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (this.isInState('idle')) {
+     *   console.log('System is idle');
+     * }
+     * ```
+     */
+    isInState(state: TState): boolean;
+    /**
+     * History of state transitions (if trackHistory is enabled).
+     * Each entry contains the state, timestamp, and optional event that caused the transition.
+     *
+     * Only available when `trackHistory: true` is set in options.
+     */
+    stateHistory?: Array<{
+        state: TState;
+        timestamp: Date;
+        event?: TEvent;
+    }>;
+}
+/**
+ * Class decorator that adds finite state machine capabilities to a KOS model.
+ *
+ * This decorator eliminates manual state management boilerplate by:
+ * - **Adding lifecycle-aware FSM initialization** at configured phase (READY, ACTIVATE, etc.)
+ * - **Managing state transitions** automatically with validation
+ * - **Providing observable state** that integrates with @kosModel reactive system
+ * - **Supporting entry/exit handlers** via @kosStateEntry and @kosStateExit decorators
+ * - **Enabling state guards** via @kosStateGuard decorator
+ *
+ * ## Two-Level State System
+ *
+ * **Framework Lifecycle (Universal, Not Customizable):**
+ * - CREATED → INIT → LOAD → READY → ACTIVATE → UNLOAD → DESTROY
+ * - Managed by KOS framework
+ * - Same for all models
+ *
+ * **Application FSM (This Decorator):**
+ * - Runs WITHIN an active model
+ * - Application-specific business logic
+ * - Different for each model type
+ * - Examples: Pour states, connection states, workflow states
+ *
+ * ## Lifecycle Integration
+ *
+ * The FSM initializes at the configured lifecycle phase:
+ *
+ * ```typescript
+ * @kosStateMachine({
+ *   initial: 'idle',
+ *   initializeAt: DependencyLifecycle.READY, // Default
+ *   states: { ... }
+ * })
+ * ```
+ *
+ * - **INIT**: FSM needs to be active during model initialization (rare)
+ * - **READY**: FSM operational as soon as data loaded (most common)
+ * - **ACTIVATE**: FSM only relevant when UI is active (UI-bound models)
+ *
+ * ## TypeScript Usage
+ *
+ * **IMPORTANT**: Use TypeScript interface merging to get proper type information:
+ *
+ * ```typescript
+ * type MyState = 'idle' | 'active';
+ * type MyEvent = 'START' | 'STOP';
+ *
+ * interface MyModelImpl extends KosStateMachineAware<MyState, MyEvent> {}
+ *
+ * @kosStateMachine<MyState, MyEvent>({ ... })
+ * class MyModelImpl implements IKosDataModel {
+ *   // All FSM properties are now available with full type safety
+ * }
+ * ```
+ *
+ * @param config State machine configuration
+ * @param options Optional configuration for FSM behavior
+ * @returns A class decorator that modifies the target class prototype
+ *
+ * @see {@link KosStateMachineAware} - Interface for TypeScript merging
+ * @see {@link KosStateMachineConfig} - Configuration interface
+ * @see {@link KosStateMachineOptions} - Options interface
+ *
+ * @example
+ * ```typescript
+ * // Basic FSM with default READY initialization
+ * type PourState = 'idle' | 'pouring' | 'complete';
+ * type PourEvent = 'START' | 'FINISH';
+ *
+ * interface PourModelImpl extends KosStateMachineAware<PourState, PourEvent> {}
+ *
+ * @kosModel({ modelTypeId: "pour-model" })
+ * @kosStateMachine<PourState, PourEvent>({
+ *   initial: 'idle',
+ *   states: {
+ *     idle: { on: { START: 'pouring' } },
+ *     pouring: { on: { FINISH: 'complete' } },
+ *     complete: {}
+ *   }
+ * })
+ * class PourModelImpl implements IKosDataModel {
+ *   async ready(): Promise<void> {
+ *     // After this completes, FSM is initialized to 'idle'
+ *   }
+ *
+ *   startPour(): void {
+ *     this.transition('START'); // idle -> pouring
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // UI-bound FSM with ACTIVATE initialization
+ * type WorkflowState = 'draft' | 'review' | 'approved';
+ * type WorkflowEvent = 'SUBMIT' | 'APPROVE' | 'REJECT';
+ *
+ * interface DocumentModelImpl extends KosStateMachineAware<WorkflowState, WorkflowEvent> {}
+ *
+ * @kosModel({ modelTypeId: "document-model" })
+ * @kosStateMachine<WorkflowState, WorkflowEvent>({
+ *   initial: 'draft',
+ *   initializeAt: DependencyLifecycle.ACTIVATE, // UI-bound
+ *   states: {
+ *     draft: { on: { SUBMIT: 'review' } },
+ *     review: { on: { APPROVE: 'approved', REJECT: 'draft' } },
+ *     approved: {}
+ *   }
+ * })
+ * class DocumentModelImpl implements IKosDataModel {
+ *   // FSM only initializes when UI activates this model
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // FSM with history tracking
+ * interface HistoryModelImpl extends KosStateMachineAware<'idle' | 'active', 'TOGGLE'> {}
+ *
+ * @kosStateMachine<'idle' | 'active', 'TOGGLE'>(
+ *   {
+ *     initial: 'idle',
+ *     states: {
+ *       idle: { on: { TOGGLE: 'active' } },
+ *       active: { on: { TOGGLE: 'idle' } }
+ *     }
+ *   },
+ *   {
+ *     trackHistory: true,
+ *     stateProperty: 'status'
+ *   }
+ * )
+ * class HistoryModelImpl implements IKosDataModel {
+ *   // Access via this.stateHistory
+ * }
+ * ```
+ *
+ * @category KOS Model Decorator
+ * @since 2.1.0
+ */
+export declare function kosStateMachine<TState extends string, TEvent extends string>(config: KosStateMachineConfig<TState, TEvent>, options?: KosStateMachineOptions): ClassDecorator;
+/**
+ * Method decorator that marks a method as a state entry handler.
+ * The decorated method will be called when the state machine enters the specified state.
+ *
+ * @param state The state to handle entry for
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * @kosStateEntry('pouring')
+ * handlePouringStart(): void {
+ *   this.logger.info('Pour started');
+ *   EventBus.publish(TOPIC_POUR_STARTED, { id: this.id });
+ * }
+ * ```
+ */
+export declare function kosStateEntry<TState extends string>(state: TState): MethodDecorator;
+/**
+ * Method decorator that marks a method as a state exit handler.
+ * The decorated method will be called when the state machine exits the specified state.
+ *
+ * @param state The state to handle exit for
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * @kosStateExit('pouring')
+ * handlePouringEnd(): void {
+ *   this.logger.info('Pour ended');
+ *   EventBus.publish(TOPIC_POUR_ENDED, { id: this.id });
+ * }
+ * ```
+ */
+export declare function kosStateExit<TState extends string>(state: TState): MethodDecorator;
+/**
+ * Options for @kosStateGuard decorator.
+ */
+export interface KosStateGuardOptions<TState extends string> {
+    /**
+     * Array of states in which the decorated method can be called.
+     * The method will throw an error (or log a warning) if called from any other state.
+     */
+    allowedStates: TState[];
+    /**
+     * Whether to throw an error on invalid state.
+     * When false, logs a warning instead.
+     *
+     * @default true (uses the FSM's throwOnInvalid setting)
+     */
+    throwOnInvalid?: boolean;
+}
+/**
+ * Method decorator that guards a method with state validation.
+ * The decorated method can only be called when the state machine is in one of the allowed states.
+ *
+ * **IMPORTANT**: This decorator gracefully handles uninitialized FSM:
+ * - If FSM is not yet initialized, the guard allows the method to proceed
+ * - Once FSM is initialized, the guard enforces state validation
+ *
+ * @param options Guard configuration
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * @kosStateGuard({ allowedStates: ['ready'] })
+ * async pourBeverage(bevId: string): Promise<void> {
+ *   // This method can only be called when currentState === 'ready'
+ *   this.transition('POUR');
+ *   await this.deviceService.dispense(bevId);
+ *   this.transition('COMPLETE');
+ * }
+ * ```
+ */
+export declare function kosStateGuard<TState extends string>(options: KosStateGuardOptions<TState>): MethodDecorator;
+//# sourceMappingURL=kos-state-machine.d.ts.map

package/core/core/decorators/kos-state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-state-machine.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-state-machine.ts"],"names":[],"mappings":"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"}

package/core/core/decorators/kosModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kosModel.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kosModel.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAykB5C,UAAU,cAAc;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACtC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,cAAc,CAqDjD"}
+{"version":3,"file":"kosModel.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kosModel.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAilB5C,UAAU,cAAc;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACtC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,cAAc,CAqDjD"}

package/core/core/decorators/propKeys.d.ts

@@ -17,4 +17,8 @@ export declare const FutureAliases: unique symbol;
 export declare const TroubleAwareSetup: unique symbol;
 export declare const LoggerSetup: unique symbol;
 export declare const ContainerAwareSetup: unique symbol;
+export declare const StateMachineSetup: unique symbol;
+export declare const StateEntryHandlers: unique symbol;
+export declare const StateExitHandlers: unique symbol;
+export declare const StateActionHandlers: unique symbol;
 //# sourceMappingURL=propKeys.d.ts.map

package/core/core/decorators/propKeys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"propKeys.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/propKeys.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAC3D,eAAO,MAAM,aAAa,eAA0B,CAAC;AACrD,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,SAAS,eAAsB,CAAC;AAC7C,eAAO,MAAM,eAAe,eAA4B,CAAC;AACzD,eAAO,MAAM,cAAc,eAA2B,CAAC;AACvD,eAAO,MAAM,YAAY,eAAyB,CAAC;AACnD,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,4BAA4B,eAExC,CAAC;AACF,eAAO,MAAM,aAAa,eAA0B,CAAC;AACrD,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAC7D,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,mBAAmB,eAAgC,CAAC"}
+{"version":3,"file":"propKeys.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/propKeys.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAC3D,eAAO,MAAM,aAAa,eAA0B,CAAC;AACrD,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,SAAS,eAAsB,CAAC;AAC7C,eAAO,MAAM,eAAe,eAA4B,CAAC;AACzD,eAAO,MAAM,cAAc,eAA2B,CAAC;AACvD,eAAO,MAAM,YAAY,eAAyB,CAAC;AACnD,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AACnE,eAAO,MAAM,4BAA4B,eAExC,CAAC;AACF,eAAO,MAAM,aAAa,eAA0B,CAAC;AACrD,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAC7D,eAAO,MAAM,WAAW,eAAwB,CAAC;AACjD,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AACjE,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAC7D,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAC/D,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,eAAgC,CAAC"}

package/core/core/kos-registration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-registration.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/core/kos-registration.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAIjC,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAuB/D,KAAK,GAAG,CACN,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IACpC,gCAAgC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAC3C,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACzC,CAAC;AACF,UAAU,iBAAiB,CACzB,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAEtC,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACxB;AACD,UAAU,iBAAiB,CACzB,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAEtC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,KAAK,CAAC,CAAC;IAC3E,iBAAiB,CAAC,EAAE,GAAG,CAAC;CACzB;AACD,qBAAa,eAAe,CAC1B,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAEtC,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,GAAG,CAAC;IACxB,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,KAAK,CAAC,CAAC;gBAC/D,EAAE,IAAI,EAAE,KAAK,EAAE,iBAAiB,EAAE,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC;IAMvE,IAAI,OAAO,kFAEV;IAED,IAAI,YAAY,IAAI,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAS1C;IAED,IAAI,SAAS,+BAEZ;CACF"}
+{"version":3,"file":"kos-registration.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/core/kos-registration.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAIjC,MAAM,UAAU,CAAC;AAGlB,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAuBpE,KAAK,GAAG,CACN,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IACpC,gCAAgC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAC3C,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACzC,CAAC;AACF,UAAU,iBAAiB,CACzB,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAEtC,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACxB;AACD,UAAU,iBAAiB,CACzB,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAEtC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,KAAK,CAAC,CAAC;IAC3E,iBAAiB,CAAC,EAAE,GAAG,CAAC;CACzB;AACD,qBAAa,eAAe,CAC1B,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAEtC,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,GAAG,CAAC;IACxB,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,KAAK,CAAC,CAAC;gBAC/D,EAAE,IAAI,EAAE,KAAK,EAAE,iBAAiB,EAAE,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC;IAMvE,IAAI,OAAO,kFAEV;IAED,IAAI,YAAY,IAAI,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAS1C;IAED,IAAI,SAAS,+BAEZ;CACF"}