@kosdev-code/kos-ui-sdk 2.0.44 → 2.0.45

package/core/core/types/registration.d.ts

@@ -1,5 +1,6 @@
 import { IKosDataModel, IKosDataModelBuilder, IKosDataModelCreator, IKosModel } from '../kosModel';
 import { DataLoader, DataMapper, PropertyMapper } from '../extension';
+import { DependencyLifecycle } from '../../types';
 
 export interface IKosSubscriptionSpecification {
     webSocket: boolean;
@@ -37,6 +38,12 @@ export type KosCompanionModelType<T extends IKosDataModel = IKosDataModel> = str
 export declare const isKosCompanionTypeFactory: (obj: any) => obj is KosCompanionTypeFactory<IKosDataModel>;
 export interface IKosCompanionRegistration {
     type: KosCompanionModelType<any>;
+    /**
+     * Lifecycle phase at which this companion should be created.
+     * Extracted from the @kosCompanion decorator metadata.
+     * Defaults to undefined (treated as INIT - immediate creation).
+     */
+    lifecycle?: DependencyLifecycle;
 }
 export type Preloaded = string | {
     modelType: string;

package/core/core/types/registration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/types/registration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AACD,MAAM,WAAW,cAAe,SAAQ,qBAAqB;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,CAAC,EAAE,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,OAAA,KAAK,aAAa,CAAC;IAEvC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC,CAAC;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC5C;AAED,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAAI,CAC7E,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,GAAG,KACT,MAAM,GAAG,SAAS,CAAC;AACxB,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IACrE,MAAM,GACN,uBAAuB,CAAC,CAAC,CAAC,CAAC;AAE/B,eAAO,MAAM,yBAAyB,QAC/B,GAAG,kDACoD,CAAC;AAC/D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,qBAAqB,CAAC,GAAG,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,SAAS,GACjB,MAAM,GACN;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,GAAG,CAAA;CAAE,CAAC;AAC1D,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAGjD,aAAa,EAAE,SAAS,EAAE,CAAC;IAE3B,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC"}
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/types/registration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AACD,MAAM,WAAW,cAAe,SAAQ,qBAAqB;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,CAAC,EAAE,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,OAAA,KAAK,aAAa,CAAC;IAEvC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC,CAAC;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC5C;AAED,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAAI,CAC7E,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,GAAG,KACT,MAAM,GAAG,SAAS,CAAC;AACxB,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IACrE,MAAM,GACN,uBAAuB,CAAC,CAAC,CAAC,CAAC;AAE/B,eAAO,MAAM,yBAAyB,QAC/B,GAAG,kDACoD,CAAC;AAC/D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,qBAAqB,CAAC,GAAG,CAAC,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAED,MAAM,MAAM,SAAS,GACjB,MAAM,GACN;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,GAAG,CAAA;CAAE,CAAC;AAC1D,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAGjD,aAAa,EAAE,SAAS,EAAE,CAAC;IAE3B,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC"}

package/core/index.d.ts

@@ -15,9 +15,10 @@ export * from './core/kosModel';
 export * from './core/kosModelManager';
 export { KosModelEvents, KosModelState } from './core/lifecycle';
 export * from './core/log';
+export { KosLoggerFactory } from './core/model/kos-logger-factory';
 export * from './core/models';
 export { default as KosToken } from './core/models/kos-token';
-export { KosModelRegistrationFactory, preloadKosModel, registerCompanionModel, registerKosModel, registerLegacyModel, RegistrationManager, SingletonKosModelRegistrationFactory, type RegistrationResult, } from './core/registration';
+export { KosModelRegistrationFactory, preloadKosModel, registerCompanionModel, registerKosModel, registerLegacyModel, RegistrationManager, SingletonKosModelRegistrationFactory, type KosModelRegistrationType, type RegistrationResult, } from './core/registration';
 export * from './core/services';
 export * from './core/transport';
 export * from './core/types';

package/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/sdk/kos-ui-sdk/src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAEP,kBAAkB,EAClB,cAAc,EAEd,QAAQ,EACR,WAAW,EACX,IAAI,EACL,MAAM,MAAM,CAAC;AACd,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjE,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,oCAAoC,EACpC,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,OAAO,EACL,SAAS,EACT,aAAa,EACb,WAAW,EACX,SAAS,EACT,aAAa,EACb,OAAO,EACP,kBAAkB,EAClB,cAAc,GACf,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,OAAO,aAAO,CAAC;AAErB;;;GAGG;AACH,QAAA,MAAM,WAAW,iCAAW,CAAC;AAC7B;;;GAGG;AACH,QAAA,MAAM,SAAS,oBAAc,CAAC;AAE9B;;;;;;;GAOG;AACH,QAAA,MAAM,aAAa,gBAAU,CAAC;AAE9B;;;GAGG;AACH,QAAA,MAAM,SAAS,iBAAW,CAAC;AAE3B;;;GAGG;AACH,QAAA,MAAM,aAAa,mCAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/sdk/kos-ui-sdk/src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAEP,kBAAkB,EAClB,cAAc,EAEd,QAAQ,EACR,WAAW,EACX,IAAI,EACL,MAAM,MAAM,CAAC;AACd,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjE,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,oCAAoC,EACpC,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,OAAO,EACL,SAAS,EACT,aAAa,EACb,WAAW,EACX,SAAS,EACT,aAAa,EACb,OAAO,EACP,kBAAkB,EAClB,cAAc,GACf,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,OAAO,aAAO,CAAC;AAErB;;;GAGG;AACH,QAAA,MAAM,WAAW,iCAAW,CAAC;AAC7B;;;GAGG;AACH,QAAA,MAAM,SAAS,oBAAc,CAAC;AAE9B;;;;;;;GAOG;AACH,QAAA,MAAM,aAAa,gBAAU,CAAC;AAE9B;;;GAGG;AACH,QAAA,MAAM,SAAS,iBAAW,CAAC;AAE3B;;;GAGG;AACH,QAAA,MAAM,aAAa,mCAAa,CAAC"}

package/core/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from './model';
 export * from './utils/kos-fetch';
 export * from './kos-dependency';
+export * from './service-response-store';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC"}

package/core/types/kos-dependency.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @kosService core.dependency
+ */
 export declare enum DependencyLifecycle {
     INIT = "init",
     LOAD = "load",
@@ -5,9 +8,41 @@ export declare enum DependencyLifecycle {
     ACTIVATE = "activate",
     ONLINE = "online"
 }
+/**
+ * Policy for handling dependency resolution failures.
+ *
+ * @kosService core.dependency
+ *
+ * All policies follow a lookup-first approach: The framework first checks if a model
+ * with the specified ID already exists. If found and the type matches, it returns the
+ * existing instance. Only if no existing model is found does the framework apply the
+ * resolution policy below.
+ */
+export declare enum DependencyResolutionPolicy {
+    /**
+     * CREATE (default) - After lookup fails, attempt to create a new instance of the model.
+     * If the model requires options (via optionsRequired flag) and none are provided,
+     * it will fail with an exception.
+     */
+    CREATE = "create",
+    /**
+     * CONTINUE - After lookup fails, do not attempt to create a new instance.
+     * The property will be set to undefined. Log the failure but allow execution to continue.
+     * Use for optional dependencies that can degrade gracefully.
+     */
+    CONTINUE = "continue",
+    /**
+     * FAIL - After lookup fails, throw an exception with detailed diagnostic logging.
+     * Use for critical dependencies where failure should halt execution.
+     */
+    FAIL = "fail"
+}
 /**
  * The parameters for the kosDependency decorator.
- * */
+ *
+ * @kosService core.dependency
+ * @kosApiLevel 2
+ */
 export interface KosDependencyParams<Options = unknown> {
     /** The type of the model to be injected. */
     modelType: string;
@@ -17,5 +52,17 @@ export interface KosDependencyParams<Options = unknown> {
     options?: Options;
     /** The lifecycle at which the dependency should be injected. */
     lifecycle?: DependencyLifecycle;
+    /**
+     * Policy for handling dependency resolution failures.
+     *
+     * All policies first attempt to look up an existing model instance. If found and the type
+     * matches, the existing instance is returned. Only if lookup fails does the policy apply:
+     *
+     * - CREATE (default): Attempts to create model instance after lookup fails
+     * - CONTINUE: Returns undefined after lookup fails, allows graceful degradation
+     * - FAIL: Throws exception with detailed logging after lookup fails
+     * @kosApiLevel 16
+     */
+    resolutionPolicy?: DependencyResolutionPolicy;
 }
 //# sourceMappingURL=kos-dependency.d.ts.map

package/core/types/kos-dependency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-dependency.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/types/kos-dependency.ts"],"names":[],"mappings":"AAAA,oBAAY,mBAAmB;IAC7B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,KAAK,UAAU;IACf,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED;;KAEK;AACL,MAAM,WAAW,mBAAmB,CAAC,OAAO,GAAG,OAAO;IACpD,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC"}
+{"version":3,"file":"kos-dependency.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/types/kos-dependency.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,mBAAmB;IAC7B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,KAAK,UAAU;IACf,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED;;;;;;;;;GASG;AACH,oBAAY,0BAA0B;IACpC;;;;OAIG;IACH,MAAM,WAAW;IACjB;;;;OAIG;IACH,QAAQ,aAAa;IACrB;;;OAGG;IACH,IAAI,SAAS;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO,GAAG,OAAO;IACpD,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,0BAA0B,CAAC;CAC/C"}

package/core/types/service-response-store.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Response retention policies for ServiceResponseStore
+ * Controls how long service responses are cached and when they're cleaned up
+ *
+ * @kosService core.service-request
+ */
+export declare enum ResponseRetention {
+    /**
+     * Clear immediately after handler completes
+     * Use for one-time operations with no caching needs
+     *
+     * Note: Response remains available during handler execution (including async handlers).
+     * Cleanup happens AFTER the handler returns/resolves via ServiceRequestManager.
+     */
+    IMMEDIATE = "immediate",
+    /**
+     * Keep until next response for same path
+     * Default behavior - previous response replaced on new request
+     */
+    SINGLE = "single",
+    /**
+     * Keep for specified duration (ms)
+     * Automatic cleanup after TTL expires
+     */
+    TTL = "ttl",
+    /**
+     * Keep until model is destroyed
+     * Use for data needed throughout model lifetime
+     */
+    PERMANENT = "permanent",
+    /**
+     * Keep until explicitly cleared
+     * Manual cleanup required via clearServiceResponse()
+     */
+    MANUAL = "manual"
+}
+/**
+ * Configuration for response caching behavior
+ *
+ * @kosService core.service-request
+ * @kosApiLevel 15
+ */
+export interface ResponseCacheConfig {
+    /**
+     * Retention policy determining when response is cleaned up
+     */
+    retention: ResponseRetention;
+    /**
+     * Time-to-live in milliseconds (required for TTL retention)
+     */
+    ttl?: number;
+    /**
+     * For TTL retention: extend TTL instead of replacing data on new request
+     *
+     * When false (default): New request clears old data and stores new data with fresh TTL
+     * When true: If cached data exists and hasn't expired, extend TTL without replacing data
+     *
+     * Use extendOnRefresh=true to avoid re-running expensive operations when cached data is still valid.
+     *
+     * @default false
+     *
+     * @example
+     * // Replace on each request (default)
+     * cache: { retention: ResponseRetention.TTL, ttl: 5 * 60 * 1000 }
+     *
+     * @example
+     * // Extend TTL on refresh - avoid re-fetching if cache valid
+     * cache: { retention: ResponseRetention.TTL, ttl: 5 * 60 * 1000, extendOnRefresh: true }
+     */
+    extendOnRefresh?: boolean;
+    /**
+     * Maximum number of responses to cache per path (future use)
+     */
+    maxSize?: number;
+}
+/**
+ * Replay strategy for baseline-delta race condition handling
+ * Determines which queued events to replay after baseline loads
+ *
+ * @kosService core.topic-handler
+ */
+export declare enum ReplayStrategy {
+    /**
+     * Replay all queued events
+     * Use for: State machines, audit trails requiring complete event history
+     */
+    ALL = "all",
+    /**
+     * Replay events received at or after baseline request was sent
+     * Use for: High-frequency idempotent updates (quantities, sensor readings, status)
+     */
+    AFTER_REQUEST = "after-request",
+    /**
+     * Replay events received at or after baseline response was received
+     * Use for: Low-frequency config where baseline likely includes recent changes
+     */
+    AFTER_RESPONSE = "after-response",
+    /**
+     * Discard all queued events
+     * Use for: Baseline is always complete source of truth
+     */
+    NONE = "none"
+}
+/**
+ * Baseline dependency configuration for topic handlers
+ *
+ * @kosService core.topic-handler
+ * @kosApiLevel 15
+ */
+export interface BaselineDependency {
+    /**
+     * API path of the baseline request this handler depends on
+     */
+    path: string;
+    /**
+     * HTTP method of the baseline request
+     * @default 'get'
+     */
+    method?: string;
+    /**
+     * Strategy for replaying queued events after baseline loads
+     * @default ReplayStrategy.AFTER_REQUEST
+     */
+    replayStrategy?: ReplayStrategy;
+}
+/**
+ * Cached response with metadata
+ */
+export interface CachedResponse<T = unknown> {
+    /**
+     * The response data
+     */
+    data: T;
+    /**
+     * When the response was cached (timestamp)
+     * @deprecated Use requestedAt or receivedAt for temporal comparisons
+     */
+    timestamp: number;
+    /**
+     * When the HTTP request was sent (timestamp)
+     * Used for baseline-delta temporal filtering
+     */
+    requestedAt: number;
+    /**
+     * When the HTTP response was received (timestamp)
+     * Used for baseline-delta temporal filtering
+     */
+    receivedAt: number;
+    /**
+     * The API path this response came from
+     */
+    path: string;
+    /**
+     * The HTTP method used
+     */
+    method: string;
+    /**
+     * When this response expires (for TTL retention)
+     */
+    expiresAt?: number;
+}
+//# sourceMappingURL=service-response-store.d.ts.map

package/core/types/service-response-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-response-store.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/types/service-response-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAY,iBAAiB;IAC3B;;;;;;OAMG;IACH,SAAS,cAAc;IAEvB;;;OAGG;IACH,MAAM,WAAW;IAEjB;;;OAGG;IACH,GAAG,QAAQ;IAEX;;;OAGG;IACH,SAAS,cAAc;IAEvB;;;OAGG;IACH,MAAM,WAAW;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,SAAS,EAAE,iBAAiB,CAAC;IAE7B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;;;;;;;;OAiBG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,oBAAY,cAAc;IACxB;;;OAGG;IACH,GAAG,QAAQ;IAEX;;;OAGG;IACH,aAAa,kBAAkB;IAE/B;;;OAGG;IACH,cAAc,mBAAmB;IAEjC;;;OAGG;IACH,IAAI,SAAS;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC;;OAEG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/core/types/utils/kos-fetch.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 1
+ */
 export declare enum KosFetchMethods {
     GET = "GET",
     PUT = "PUT",
@@ -5,6 +9,10 @@ export declare enum KosFetchMethods {
     DELETE = "DELETE"
 }
 type FetchMethodStrings = keyof typeof KosFetchMethods;
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface Headers {
     append(name: string, value: string): void;
     delete(name: string): void;
@@ -22,6 +30,10 @@ interface Body {
     json<T = any>(): Promise<T | null>;
     text(): Promise<string>;
 }
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface Response extends Body {
     readonly headers: Headers;
     readonly ok: boolean;
@@ -32,8 +44,65 @@ export interface Response extends Body {
     readonly url: string;
     clone(): Response;
 }
+/**
+ * Configuration for automatic retry with exponential backoff.
+ *
+ * @kosService core.fetch
+ *
+ * When `retry` is set to `true` on {@link KosFetchOptions}, these defaults apply.
+ * When set to a partial `RetryConfig`, unspecified fields use these defaults:
+ * - `maxAttempts`: 3
+ * - `baseDelayMs`: 350
+ * - `backoffFactor`: 2
+ * - `retryMutations`: false (POST, PUT, DELETE, PATCH are NOT retried)
+ * - `retryOn`: retries on any error (return `true` to retry, `false` to stop)
+ *
+ * @example
+ * ```typescript
+ * // Use all defaults
+ * retry: true
+ *
+ * // Custom config
+ * retry: {
+ *   maxAttempts: 5,
+ *   retryOn: (response) => response.status === 503 || response.status === 429,
+ * }
+ * ```
+ *
+ * @category Service Request
+ * @kosApiLevel 22
+ */
+export interface RetryConfig {
+    /** Maximum number of attempts (including the initial request). @default 3 */
+    maxAttempts?: number;
+    /** Base delay in milliseconds before the first retry. @default 350 */
+    baseDelayMs?: number;
+    /** Multiplier applied to the delay after each attempt. @default 2 */
+    backoffFactor?: number;
+    /**
+     * Whether to retry mutating methods (POST, PUT, DELETE, PATCH).
+     * Set to `true` only if the endpoint is idempotent.
+     * @default false
+     */
+    retryMutations?: boolean;
+    /**
+     * Predicate called with the {@link Response} to decide if a failed request
+     * should be retried. Return `true` to retry, `false` to stop immediately.
+     *
+     * If not provided, all errors are retried (up to `maxAttempts`).
+     *
+     * @example
+     * ```typescript
+     * retryOn: (response) => response.status >= 500
+     * ```
+     */
+    retryOn?: (response: Response) => boolean;
+}
 /**
  * Represents the configuration options for performing a Kos WebSocket fetch operation.
+ *
+ * @kosService core.fetch
+ * @kosApiLevel 2
  */
 export interface KosFetchOptions {
     /**
@@ -73,16 +142,37 @@ export interface KosFetchOptions {
      */
     bridge?: boolean;
     timeout?: number;
+    /**
+     * @kosApiLevel 5
+     */
     headers?: Record<string, string>;
     /**
      * Enable streaming mode for large responses
+     * @kosApiLevel 11
      */
     stream?: boolean;
     /**
      * Response type hint for binary data handling
+     * @kosApiLevel 11
      */
     responseType?: "text" | "json" | "arraybuffer" | "blob";
+    /**
+     * Retry configuration for transient failures.
+     *
+     * - `true`: enable retry with all defaults
+     * - `RetryConfig`: partial overrides (unspecified fields use defaults)
+     * - `undefined` / omitted: no retry (current behavior)
+     *
+     * Mutating methods (POST, PUT, DELETE, PATCH) are NOT retried by default.
+     * Set `retryMutations: true` to opt in.
+     * @kosApiLevel 22
+     */
+    retry?: boolean | RetryConfig;
 }
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface KosFetchResponse {
     headers: Headers;
     status: string | number | boolean;
@@ -90,6 +180,10 @@ export interface KosFetchResponse {
     json: <T = Record<string | number | symbol, string | number | symbol>>() => Promise<T>;
     body: ReadableStream<Uint8Array> | null;
 }
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface KosFetchReqeust {
     path: string;
     requestId: string;
@@ -98,21 +192,40 @@ export interface KosFetchReqeust {
     ordered?: boolean;
     tracker?: string;
     bridge?: boolean;
+    /**
+     * @kosApiLevel 5
+     */
     headers?: Record<string, string | number | boolean>;
 }
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface KosMessageRequest extends Omit<KosFetchReqeust, "method" | "path" | "requestId"> {
     requestType: string;
     requestId?: string;
     headers?: Record<string, string>;
 }
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface KosBroadcastRequest {
     topic: string;
 }
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface KosMessageOptions extends KosBroadcastRequest {
     destinationAddress?: string;
     responseId?: string;
     type?: string;
 }
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface KosHttpMessageOptions {
     destinationAddress: string;
     sourceAddress: string;
@@ -121,12 +234,20 @@ export interface KosHttpMessageOptions {
     type: string;
     contentType?: string;
 }
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface KosFetchResponseParams {
     path: string;
     responseId?: string;
     destinationAddress: string;
     status: string | number | boolean;
 }
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export interface KosFetchPostReqeust extends KosFetchReqeust {
     body?: string;
 }

package/core/types/utils/kos-fetch.d.ts.map

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

package/core/util/ancestor-path-visitor.d.ts

@@ -0,0 +1,60 @@
+import { KosModelVisitor } from './kos-model-visitor';
+import { IKosDataModel, IKosModel } from '../core/kosModel';
+
+/**
+ * Generic visitor that finds the ancestor path to a target item.
+ * Works with any KOS model hierarchy that implements the visitor pattern.
+ *
+ * Uses depth-first traversal, tracking the path as it goes.
+ * When the target is found, the accumulated path IS the ancestor list.
+ *
+ * Backtracking logic is entirely self-contained - no model changes needed.
+ * Works well for Studio's typical model sizes (dozens to ~100 items).
+ *
+ * @example
+ * ```typescript
+ * const visitor = new AncestorPathVisitor('target-item-id');
+ * visitor.start(rootContainerModel);
+ * const ancestors = visitor.getAncestorPath(); // ['root', 'parent', 'grandparent']
+ * ```
+ *
+ * @category Core
+ * @kosService core.utils
+ * @kosApiLevel 20
+ */
+export declare class AncestorPathVisitor extends KosModelVisitor {
+    private targetId;
+    private currentPath;
+    private foundPath;
+    constructor(targetId: string);
+    /**
+     * Override visit() to wrap the entire visit lifecycle with path tracking.
+     *
+     * Flow:
+     * 1. Check cycle detection (skip if already visited)
+     * 2. Push model to path
+     * 3. Call visitModel() to check if this is target
+     * 4. If not target, visit children
+     * 5. Pop from path if target not found in this subtree (backtrack)
+     *
+     * Note: We inline the base class logic rather than calling super.visit()
+     * because we need to control exactly when push/pop happens relative to
+     * the cycle detection and child traversal.
+     */
+    visit(model: IKosModel): void;
+    /**
+     * Called for each model during traversal.
+     * Returns true to stop traversal when target is found.
+     */
+    visitModel<T extends IKosDataModel>(model: T): boolean | void;
+    /**
+     * Get the ancestor path (IDs from root to parent, not including target).
+     * Returns empty array if target not found or target is at root level.
+     */
+    getAncestorPath(): string[];
+    /**
+     * Check if target was found during traversal.
+     */
+    wasFound(): boolean;
+}
+//# sourceMappingURL=ancestor-path-visitor.d.ts.map

package/core/util/ancestor-path-visitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ancestor-path-visitor.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/util/ancestor-path-visitor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,SAAS,CAAyB;gBAE9B,QAAQ,EAAE,MAAM;IAK5B;;;;;;;;;;;;;OAaG;IACM,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAgCtC;;;OAGG;IACH,UAAU,CAAC,CAAC,SAAS,aAAa,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,GAAG,IAAI;IAY7D;;;OAGG;IACH,eAAe,IAAI,MAAM,EAAE;IAI3B;;OAEG;IACH,QAAQ,IAAI,OAAO;CAGpB"}

package/core/util/api-request-id.d.ts

@@ -1,2 +1,6 @@
+/**
+ * @kosService core.fetch
+ * @kosApiLevel 2
+ */
 export declare function uuid(): string;
 //# sourceMappingURL=api-request-id.d.ts.map

package/core/util/api-request-id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-request-id.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/util/api-request-id.ts"],"names":[],"mappings":"AAAA,wBAAgB,IAAI,WAMnB"}
+{"version":3,"file":"api-request-id.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/util/api-request-id.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,IAAI,WAMnB"}

package/core/util/apply-mixins.d.ts

@@ -1,2 +1,6 @@
+/**
+ * @kosService core.kos-model
+ * @kosApiLevel 2
+ */
 export declare function applyMixins(derivedCtor: any, baseCtors: any[]): void;
 //# sourceMappingURL=apply-mixins.d.ts.map

package/core/util/apply-mixins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply-mixins.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/util/apply-mixins.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,QAc7D"}
+{"version":3,"file":"apply-mixins.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/util/apply-mixins.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,QAc7D"}

package/core/util/array-utils.d.ts

@@ -1,2 +1,6 @@
+/**
+ * @kosService core.utils
+ * @kosApiLevel 5
+ */
 export declare function arraysEqual(_a?: any[], _b?: any[]): boolean;
 //# sourceMappingURL=array-utils.d.ts.map

package/core/util/array-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array-utils.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/util/array-utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAK3D"}
+{"version":3,"file":"array-utils.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/core/util/array-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAK3D"}