effectable 0.1.0

package/build/runtime/EventBus.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Lightweight event bus implementation.
+ *
+ * @module Effectable/runtime/EventBus
+ */
+import type { EventHandler, RuntimeEvent } from './types';
+/**
+ * Event bus with per-type and global subscriptions.
+ */
+export declare class EventBus<TEvent extends RuntimeEvent = RuntimeEvent> {
+    private readonly handlersByType;
+    private readonly anyHandlers;
+    /**
+     * Publishes an event to all matching subscribers.
+     *
+     * @param {TEvent} event - runtime event
+     * @returns {void}
+     */
+    publish(event: TEvent): void;
+    /**
+     * Subscribes a handler to the given event type only.
+     *
+     * @param {TEvent['type']} eventType - event type
+     * @param {EventHandler<TEvent>} handler - event handler
+     * @returns {() => void} unsubscribe function
+     */
+    subscribe(eventType: TEvent['type'], handler: EventHandler<TEvent>): () => void;
+    /**
+     * Subscribes a handler to all events on the bus.
+     *
+     * @param {EventHandler<TEvent>} handler - event handler
+     * @returns {() => void} unsubscribe function
+     */
+    subscribeAll(handler: EventHandler<TEvent>): () => void;
+    /**
+     * Unsubscribes a handler from a specific event type.
+     *
+     * @param {TEvent['type']} eventType - event type
+     * @param {EventHandler<TEvent>} handler - event handler
+     * @returns {void}
+     */
+    unsubscribe(eventType: TEvent['type'], handler: EventHandler<TEvent>): void;
+    /**
+     * Clears all subscriptions.
+     *
+     * @returns {void}
+     */
+    clear(): void;
+}
+//# sourceMappingURL=EventBus.d.ts.map

package/build/runtime/EventBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.d.ts","sourceRoot":"","sources":["../../src/runtime/EventBus.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D;;GAEG;AACH,qBAAa,QAAQ,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IAC9D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgD;IAC/E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmC;IAE/D;;;;;OAKG;IACI,OAAO,CAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAapC;;;;;;OAMG;IACI,SAAS,CACd,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EACzB,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAC5B,MAAM,IAAI;IAcb;;;;;OAKG;IACI,YAAY,CAAE,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI;IAO/D;;;;;;OAMG;IACI,WAAW,CAChB,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EACzB,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAC5B,IAAI;IAYP;;;;OAIG;IACI,KAAK,IAAK,IAAI;CAItB"}

package/build/runtime/EventBus.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Lightweight event bus implementation.
+ *
+ * @module Effectable/runtime/EventBus
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBus = void 0;
+/**
+ * Event bus with per-type and global subscriptions.
+ */
+class EventBus {
+    handlersByType = new Map();
+    anyHandlers = new Set();
+    /**
+     * Publishes an event to all matching subscribers.
+     *
+     * @param {TEvent} event - runtime event
+     * @returns {void}
+     */
+    publish(event) {
+        const typedHandlers = this.handlersByType.get(event.type);
+        if (typeof typedHandlers !== 'undefined') {
+            for (const handler of typedHandlers) {
+                handler(event);
+            }
+        }
+        for (const handler of this.anyHandlers) {
+            handler(event);
+        }
+    }
+    /**
+     * Subscribes a handler to the given event type only.
+     *
+     * @param {TEvent['type']} eventType - event type
+     * @param {EventHandler<TEvent>} handler - event handler
+     * @returns {() => void} unsubscribe function
+     */
+    subscribe(eventType, handler) {
+        const current = this.handlersByType.get(eventType);
+        const handlers = typeof current === 'undefined'
+            ? new Set()
+            : current;
+        handlers.add(handler);
+        this.handlersByType.set(eventType, handlers);
+        return () => {
+            this.unsubscribe(eventType, handler);
+        };
+    }
+    /**
+     * Subscribes a handler to all events on the bus.
+     *
+     * @param {EventHandler<TEvent>} handler - event handler
+     * @returns {() => void} unsubscribe function
+     */
+    subscribeAll(handler) {
+        this.anyHandlers.add(handler);
+        return () => {
+            this.anyHandlers.delete(handler);
+        };
+    }
+    /**
+     * Unsubscribes a handler from a specific event type.
+     *
+     * @param {TEvent['type']} eventType - event type
+     * @param {EventHandler<TEvent>} handler - event handler
+     * @returns {void}
+     */
+    unsubscribe(eventType, handler) {
+        const handlers = this.handlersByType.get(eventType);
+        if (typeof handlers === 'undefined') {
+            return;
+        }
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+            this.handlersByType.delete(eventType);
+        }
+    }
+    /**
+     * Clears all subscriptions.
+     *
+     * @returns {void}
+     */
+    clear() {
+        this.handlersByType.clear();
+        this.anyHandlers.clear();
+    }
+}
+exports.EventBus = EventBus;
+//# sourceMappingURL=EventBus.js.map

package/build/runtime/EventBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventBus.js","sourceRoot":"","sources":["../../src/runtime/EventBus.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAIH;;GAEG;AACH,MAAa,QAAQ;IACF,cAAc,GAAG,IAAI,GAAG,EAAqC,CAAC;IAC9D,WAAW,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE/D;;;;;OAKG;IACI,OAAO,CAAE,KAAa;QAC3B,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,OAAO,aAAa,KAAK,WAAW,EAAE,CAAC;YACzC,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;gBACpC,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;QAED,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACvC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACI,SAAS,CACd,SAAyB,EACzB,OAA6B;QAE7B,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,OAAO,OAAO,KAAK,WAAW;YAC7C,CAAC,CAAC,IAAI,GAAG,EAAwB;YACjC,CAAC,CAAC,OAAO,CAAC;QAEZ,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAE7C,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACvC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACI,YAAY,CAAE,OAA6B;QAChD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACI,WAAW,CAChB,SAAyB,EACzB,OAA6B;QAE7B,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpD,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;YACpC,OAAO;QACT,CAAC;QAED,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,KAAK;QACV,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC5B,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;CACF;AA3FD,4BA2FC"}

package/build/runtime/HandleRegistry.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Registry of imperative handle objects.
+ *
+ * `HandleRegistry` is a small runtime registry that stores and retrieves
+ * "imperative handles" (objects with methods) keyed by a string.
+ *
+ * In application code this idea is used for bridge mechanics:
+ * 1) a runtime-host/internal service creates a handle (for example with `runUname()` / `getSnapshot()`),
+ * 2) that handle is registered in `HandleRegistry` under a `handleKey`,
+ * 3) command/query handlers obtain the handle via `resolve()` and call its methods.
+ *
+ * Thanks to this, domain handlers do not depend on how the runtime-host lifecycle is structured:
+ * they only operate on `key -> handle -> method`.
+ *
+ * @module Effectable/runtime/HandleRegistry
+ *
+ * @example
+ * const handleRegistry = new HandleRegistry();
+ *
+ * // runtime-host created an imperative handle and registered it
+ * const disposer = handleRegistry.register('domain:instance1:handle', myHandle);
+ *
+ * // query-handler resolves the handle by key and returns a snapshot
+ * const handle = handleRegistry.resolve<typeof myHandle>('domain:instance1:handle');
+ * const snapshot = handle.getSnapshot();
+ *
+ * // on shutdown the runtime-host must unregister
+ * disposer();
+ */
+import 'reflect-metadata';
+export type HandleRefKeyFactory<TInstance = unknown> = string | ((instance: TInstance) => string);
+/**
+ * Decorator that sets a handle key (or key factory) for an instance.
+ *
+ * Used together with `HandleRegistry.autoRegister(instance)`:
+ * - the decorator stores key metadata
+ * - `autoRegister()` fills the ref object (on the field marked with `@UseRef()`)
+ *   with methods marked with `@UseImperativeHandle()`
+ */
+export declare function forwardRef<TInstance = unknown>(keyOrFactory: HandleRefKeyFactory<TInstance>): ClassDecorator;
+/**
+ * Method decorator that includes a method in the imperative handle.
+ *
+ * Together with `@forwardRef(...)` and the `@UseRef()` property decorator, it lets you build a handle
+ * without manually calling `handleRegistry.register(handleKey, { ... })`.
+ */
+export declare function UseImperativeHandle(): MethodDecorator;
+/**
+ * Property decorator that marks the field where the runtime host should place a ref object.
+ *
+ * That ref object is then filled with methods marked with `@UseImperativeHandle()`.
+ */
+export declare function UseRef(): PropertyDecorator;
+/**
+ * Handle registry keyed by string.
+ */
+export declare class HandleRegistry {
+    private readonly handles;
+    private buildRefHandle;
+    private resolveHandleKey;
+    /**
+     * Automatically registers an imperative handle for the given instance.
+     *
+     * `instance` must be annotated with:
+     * - `@UseRef(...)` on the class (sets the handle key)
+     * - `@UseImperativeHandle()` on methods (defines the handle surface)
+     *
+     * @param {unknown} instance - instance from which the handle is built
+     * @returns {() => void} disposer that unregisters the handle
+     */
+    autoRegister(instance: unknown): () => void;
+    /**
+     * Registers a handle and returns a disposer that unregisters it.
+     *
+     * Prefer keeping the disposer and calling it from the component's `onUnmount()`,
+     * so stale handles are not left after the runtime instance stops.
+     *
+     * @param {string} key - handle key
+     * @param {THandle} handle - imperative API object
+     * @returns {() => void} unregister function
+     */
+    register<THandle>(key: string, handle: THandle): () => void;
+    /**
+     * Removes a handle by key.
+     *
+     * Usually called either directly in "manual lifecycle" scenarios,
+     * or indirectly via the disposer returned from `register()`.
+     *
+     * @param {string} key - handle key
+     * @returns {void}
+     */
+    unregister(key: string): void;
+    /**
+     * Returns a handle by key if it is registered.
+     *
+     * If the handle is not found, returns `undefined` — without throwing.
+     *
+     * @param {string} key - handle key
+     * @returns {THandle | undefined} found handle
+     */
+    get<THandle>(key: string): THandle | undefined;
+    /**
+     * Returns a handle by key or throws.
+     *
+     * This is the strict method: suitable for command/query handlers
+     * when a missing handle means a business-logic error
+     * (for example, a request arrived for an instance that has already stopped).
+     *
+     * @param {string} key - handle key
+     * @returns {THandle} found handle
+     * @throws {Error} if the handle is not registered
+     */
+    resolve<THandle>(key: string): THandle;
+    /**
+     * Checks whether a handle exists for the key.
+     *
+     * Useful for diagnostics and "soft" scenarios
+     * when you want to avoid exceptions and take an alternate path.
+     *
+     * @param {string} key - handle key
+     * @returns {boolean} true if the handle is registered
+     */
+    has(key: string): boolean;
+    /**
+     * Returns the list of registered keys.
+     *
+     * Suitable for debugging runtime instances (for example, to see
+     * which handles are currently active).
+     *
+     * @returns {string[]} list of keys
+     */
+    keys(): string[];
+    /**
+     * Fully clears the registry.
+     *
+     * Use on full system/subsystem shutdown,
+     * when all previously registered imperative handles are considered obsolete.
+     *
+     * @returns {void}
+     */
+    clear(): void;
+}
+//# sourceMappingURL=HandleRegistry.d.ts.map

package/build/runtime/HandleRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandleRegistry.d.ts","sourceRoot":"","sources":["../../src/runtime/HandleRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,kBAAkB,CAAC;AAM1B,MAAM,MAAM,mBAAmB,CAAC,SAAS,GAAG,OAAO,IAC/C,MAAM,GACN,CAAC,CAAC,QAAQ,EAAE,SAAS,KAAK,MAAM,CAAC,CAAC;AAEtC;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,SAAS,GAAG,OAAO,EAC5C,YAAY,EAAE,mBAAmB,CAAC,SAAS,CAAC,GAC3C,cAAc,CAIhB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAK,eAAe,CAmBtD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,IAAK,iBAAiB,CAS3C;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IAEtD,OAAO,CAAC,cAAc;IA2CtB,OAAO,CAAC,gBAAgB;IAwBxB;;;;;;;;;OASG;IACI,YAAY,CAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,IAAI;IAMnD;;;;;;;;;OASG;IACI,QAAQ,CAAC,OAAO,EAAG,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI;IAOnE;;;;;;;;OAQG;IACI,UAAU,CAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAIrC;;;;;;;OAOG;IACI,GAAG,CAAC,OAAO,EAAG,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAItD;;;;;;;;;;OAUG;IACI,OAAO,CAAC,OAAO,EAAG,GAAG,EAAE,MAAM,GAAG,OAAO;IAQ9C;;;;;;;;OAQG;IACI,GAAG,CAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;;;;OAOG;IACI,IAAI,IAAK,MAAM,EAAE;IAIxB;;;;;;;OAOG;IACI,KAAK,IAAK,IAAI;CAGtB"}

package/build/runtime/HandleRegistry.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Registry of imperative handle objects.
+ *
+ * `HandleRegistry` is a small runtime registry that stores and retrieves
+ * "imperative handles" (objects with methods) keyed by a string.
+ *
+ * In application code this idea is used for bridge mechanics:
+ * 1) a runtime-host/internal service creates a handle (for example with `runUname()` / `getSnapshot()`),
+ * 2) that handle is registered in `HandleRegistry` under a `handleKey`,
+ * 3) command/query handlers obtain the handle via `resolve()` and call its methods.
+ *
+ * Thanks to this, domain handlers do not depend on how the runtime-host lifecycle is structured:
+ * they only operate on `key -> handle -> method`.
+ *
+ * @module Effectable/runtime/HandleRegistry
+ *
+ * @example
+ * const handleRegistry = new HandleRegistry();
+ *
+ * // runtime-host created an imperative handle and registered it
+ * const disposer = handleRegistry.register('domain:instance1:handle', myHandle);
+ *
+ * // query-handler resolves the handle by key and returns a snapshot
+ * const handle = handleRegistry.resolve<typeof myHandle>('domain:instance1:handle');
+ * const snapshot = handle.getSnapshot();
+ *
+ * // on shutdown the runtime-host must unregister
+ * disposer();
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandleRegistry = void 0;
+exports.forwardRef = forwardRef;
+exports.UseImperativeHandle = UseImperativeHandle;
+exports.UseRef = UseRef;
+require("reflect-metadata");
+const USE_REF_METADATA_KEY = 'effectable:HandleRegistry:UseRef';
+const USE_REF_PROPERTY_METADATA_KEY = 'effectable:HandleRegistry:UseRefProperty';
+const USE_IMPERATIVE_HANDLE_METADATA_KEY = 'effectable:HandleRegistry:UseImperativeHandle';
+/**
+ * Decorator that sets a handle key (or key factory) for an instance.
+ *
+ * Used together with `HandleRegistry.autoRegister(instance)`:
+ * - the decorator stores key metadata
+ * - `autoRegister()` fills the ref object (on the field marked with `@UseRef()`)
+ *   with methods marked with `@UseImperativeHandle()`
+ */
+function forwardRef(keyOrFactory) {
+    return (target) => {
+        Reflect.defineMetadata(USE_REF_METADATA_KEY, keyOrFactory, target);
+    };
+}
+/**
+ * Method decorator that includes a method in the imperative handle.
+ *
+ * Together with `@forwardRef(...)` and the `@UseRef()` property decorator, it lets you build a handle
+ * without manually calling `handleRegistry.register(handleKey, { ... })`.
+ */
+function UseImperativeHandle() {
+    return (target, propertyKey) => {
+        if (typeof propertyKey === 'undefined') {
+            return;
+        }
+        const ctor = target.constructor;
+        const current = Reflect.getMetadata(USE_IMPERATIVE_HANDLE_METADATA_KEY, ctor);
+        const next = typeof current === 'undefined'
+            ? new Set()
+            : new Set(current);
+        next.add(String(propertyKey));
+        Reflect.defineMetadata(USE_IMPERATIVE_HANDLE_METADATA_KEY, next, ctor);
+    };
+}
+/**
+ * Property decorator that marks the field where the runtime host should place a ref object.
+ *
+ * That ref object is then filled with methods marked with `@UseImperativeHandle()`.
+ */
+function UseRef() {
+    return (target, propertyKey) => {
+        if (typeof propertyKey === 'undefined') {
+            return;
+        }
+        const ctor = target.constructor;
+        Reflect.defineMetadata(USE_REF_PROPERTY_METADATA_KEY, propertyKey, ctor);
+    };
+}
+/**
+ * Handle registry keyed by string.
+ */
+class HandleRegistry {
+    handles = new Map();
+    buildRefHandle(instance) {
+        const ctor = instance !== null && typeof instance === 'object'
+            ? instance.constructor
+            : null;
+        if (typeof ctor !== 'function') {
+            throw new Error('HandleRegistry.autoRegister: invalid instance');
+        }
+        const refPropertyKey = Reflect.getMetadata(USE_REF_PROPERTY_METADATA_KEY, ctor);
+        if (typeof refPropertyKey === 'undefined') {
+            throw new Error('HandleRegistry.autoRegister: missing ref property metadata (@UseRef)');
+        }
+        const ref = instance[refPropertyKey];
+        if (typeof ref !== 'object' || ref === null) {
+            throw new Error('HandleRegistry.autoRegister: ref property is not an object');
+        }
+        const methodNames = Reflect.getMetadata(USE_IMPERATIVE_HANDLE_METADATA_KEY, ctor);
+        if (typeof methodNames === 'undefined' || methodNames.size === 0) {
+            throw new Error('HandleRegistry.autoRegister: no @UseImperativeHandle methods');
+        }
+        for (const methodName of methodNames) {
+            const fn = instance[methodName];
+            if (typeof fn !== 'function') {
+                throw new Error(`HandleRegistry.autoRegister: method is not a function: ${methodName}`);
+            }
+            ref[methodName] = fn.bind(instance);
+        }
+        return ref;
+    }
+    resolveHandleKey(instance) {
+        const ctor = instance !== null && typeof instance === 'object'
+            ? instance.constructor
+            : null;
+        if (typeof ctor !== 'function') {
+            throw new Error('HandleRegistry.autoRegister: invalid instance');
+        }
+        const keyOrFactory = Reflect.getMetadata(USE_REF_METADATA_KEY, ctor);
+        if (typeof keyOrFactory === 'undefined') {
+            throw new Error('HandleRegistry.autoRegister: missing @UseRef metadata');
+        }
+        if (typeof keyOrFactory === 'string') {
+            return keyOrFactory;
+        }
+        return keyOrFactory(instance);
+    }
+    /**
+     * Automatically registers an imperative handle for the given instance.
+     *
+     * `instance` must be annotated with:
+     * - `@UseRef(...)` on the class (sets the handle key)
+     * - `@UseImperativeHandle()` on methods (defines the handle surface)
+     *
+     * @param {unknown} instance - instance from which the handle is built
+     * @returns {() => void} disposer that unregisters the handle
+     */
+    autoRegister(instance) {
+        const key = this.resolveHandleKey(instance);
+        const handle = this.buildRefHandle(instance);
+        return this.register(key, handle);
+    }
+    /**
+     * Registers a handle and returns a disposer that unregisters it.
+     *
+     * Prefer keeping the disposer and calling it from the component's `onUnmount()`,
+     * so stale handles are not left after the runtime instance stops.
+     *
+     * @param {string} key - handle key
+     * @param {THandle} handle - imperative API object
+     * @returns {() => void} unregister function
+     */
+    register(key, handle) {
+        this.handles.set(key, handle);
+        return () => {
+            this.unregister(key);
+        };
+    }
+    /**
+     * Removes a handle by key.
+     *
+     * Usually called either directly in "manual lifecycle" scenarios,
+     * or indirectly via the disposer returned from `register()`.
+     *
+     * @param {string} key - handle key
+     * @returns {void}
+     */
+    unregister(key) {
+        this.handles.delete(key);
+    }
+    /**
+     * Returns a handle by key if it is registered.
+     *
+     * If the handle is not found, returns `undefined` — without throwing.
+     *
+     * @param {string} key - handle key
+     * @returns {THandle | undefined} found handle
+     */
+    get(key) {
+        return this.handles.get(key);
+    }
+    /**
+     * Returns a handle by key or throws.
+     *
+     * This is the strict method: suitable for command/query handlers
+     * when a missing handle means a business-logic error
+     * (for example, a request arrived for an instance that has already stopped).
+     *
+     * @param {string} key - handle key
+     * @returns {THandle} found handle
+     * @throws {Error} if the handle is not registered
+     */
+    resolve(key) {
+        const handle = this.get(key);
+        if (typeof handle === 'undefined') {
+            throw new Error(`Handle is not registered: ${key}`);
+        }
+        return handle;
+    }
+    /**
+     * Checks whether a handle exists for the key.
+     *
+     * Useful for diagnostics and "soft" scenarios
+     * when you want to avoid exceptions and take an alternate path.
+     *
+     * @param {string} key - handle key
+     * @returns {boolean} true if the handle is registered
+     */
+    has(key) {
+        return this.handles.has(key);
+    }
+    /**
+     * Returns the list of registered keys.
+     *
+     * Suitable for debugging runtime instances (for example, to see
+     * which handles are currently active).
+     *
+     * @returns {string[]} list of keys
+     */
+    keys() {
+        return Array.from(this.handles.keys());
+    }
+    /**
+     * Fully clears the registry.
+     *
+     * Use on full system/subsystem shutdown,
+     * when all previously registered imperative handles are considered obsolete.
+     *
+     * @returns {void}
+     */
+    clear() {
+        this.handles.clear();
+    }
+}
+exports.HandleRegistry = HandleRegistry;
+//# sourceMappingURL=HandleRegistry.js.map

package/build/runtime/HandleRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandleRegistry.js","sourceRoot":"","sources":["../../src/runtime/HandleRegistry.ts"],"names":[],"mappings":"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"}

package/build/runtime/QueryBus.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Lightweight query bus implementation.
+ *
+ * @module Effectable/runtime/QueryBus
+ */
+import type { QueryHandler, RuntimeQuery } from './types';
+/**
+ * Query bus with a single handler per query type.
+ */
+export declare class QueryBus<TQuery extends RuntimeQuery = RuntimeQuery> {
+    private readonly handlers;
+    /**
+     * Registers a query handler.
+     *
+     * @param {TQuery['type']} queryType - query type
+     * @param {QueryHandler<TQuery, TResult>} handler - query handler
+     * @returns {() => void} unregister function
+     * @throws {Error} if a handler is already registered
+     */
+    register<TResult>(queryType: TQuery['type'], handler: QueryHandler<TQuery, TResult>): () => void;
+    /**
+     * Executes a query through the registered handler.
+     *
+     * @param {TQuery} query - query
+     * @returns {Promise<TResult>} query execution result
+     * @throws {Error} if no handler is found
+     */
+    execute<TResult>(query: TQuery): Promise<TResult>;
+    /**
+     * Unregisters a query handler.
+     *
+     * @param {TQuery['type']} queryType - query type
+     * @returns {void}
+     */
+    unregister(queryType: TQuery['type']): void;
+    /**
+     * Clears all registered handlers.
+     *
+     * @returns {void}
+     */
+    clear(): void;
+}
+//# sourceMappingURL=QueryBus.d.ts.map

package/build/runtime/QueryBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryBus.d.ts","sourceRoot":"","sources":["../../src/runtime/QueryBus.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D;;GAEG;AACH,qBAAa,QAAQ,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoD;IAE7E;;;;;;;OAOG;IACI,QAAQ,CAAC,OAAO,EACrB,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EACzB,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,MAAM,IAAI;IAWb;;;;;;OAMG;IACU,OAAO,CAAC,OAAO,EAAG,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU/D;;;;;OAKG;IACI,UAAU,CAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI;IAInD;;;;OAIG;IACI,KAAK,IAAK,IAAI;CAGtB"}

package/build/runtime/QueryBus.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Lightweight query bus implementation.
+ *
+ * @module Effectable/runtime/QueryBus
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBus = void 0;
+/**
+ * Query bus with a single handler per query type.
+ */
+class QueryBus {
+    handlers = new Map();
+    /**
+     * Registers a query handler.
+     *
+     * @param {TQuery['type']} queryType - query type
+     * @param {QueryHandler<TQuery, TResult>} handler - query handler
+     * @returns {() => void} unregister function
+     * @throws {Error} if a handler is already registered
+     */
+    register(queryType, handler) {
+        if (this.handlers.has(queryType)) {
+            throw new Error(`Query handler is already registered: ${queryType}`);
+        }
+        this.handlers.set(queryType, handler);
+        return () => {
+            this.unregister(queryType);
+        };
+    }
+    /**
+     * Executes a query through the registered handler.
+     *
+     * @param {TQuery} query - query
+     * @returns {Promise<TResult>} query execution result
+     * @throws {Error} if no handler is found
+     */
+    async execute(query) {
+        const handler = this.handlers.get(query.type);
+        if (typeof handler === 'undefined') {
+            throw new Error(`Query handler is not registered: ${query.type}`);
+        }
+        const result = await handler(query);
+        return result;
+    }
+    /**
+     * Unregisters a query handler.
+     *
+     * @param {TQuery['type']} queryType - query type
+     * @returns {void}
+     */
+    unregister(queryType) {
+        this.handlers.delete(queryType);
+    }
+    /**
+     * Clears all registered handlers.
+     *
+     * @returns {void}
+     */
+    clear() {
+        this.handlers.clear();
+    }
+}
+exports.QueryBus = QueryBus;
+//# sourceMappingURL=QueryBus.js.map

package/build/runtime/QueryBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryBus.js","sourceRoot":"","sources":["../../src/runtime/QueryBus.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAIH;;GAEG;AACH,MAAa,QAAQ;IACF,QAAQ,GAAG,IAAI,GAAG,EAAyC,CAAC;IAE7E;;;;;;;OAOG;IACI,QAAQ,CACb,SAAyB,EACzB,OAAsC;QAEtC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,wCAAwC,SAAS,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,OAAwC,CAAC,CAAC;QACvE,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,OAAO,CAAW,KAAa;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,oCAAoC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;QACpC,OAAO,MAAiB,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACI,UAAU,CAAE,SAAyB;QAC1C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACI,KAAK;QACV,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF;AA5DD,4BA4DC"}