effectable 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Nick Nask, also known as Nikita Neskuchaev (iamnikas)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# Effectable
+
+Reactive layer library: explicit bootstrap-path, Redux-RxJS store, base class with lifecycle, class-based HOC `connect`, and GraphRuntime with a declarative component tree (`h`, `compose`).
+
+## Installation
+
+Requires **Node.js 18.18+** and **npm 9+**.
+
+```bash
+npm install effectable
+```
+
+```typescript
+import { bootstrap, connect, createStore, Component, h } from 'effectable';
+```
+
+Subpackages: `effectable/bootstrap`, `effectable/store`, `effectable/component`, `effectable/connect`, `effectable/runtime`.
+
+## Structure
+
+```text
+Effectable/
+├── src/
+│   ├── index.ts         # Re-exports bootstrap, store, component, connect, runtime
+│   ├── bootstrap/       # Explicit root bootstrap, runtime handle, and default runtime primitives
+│   ├── store/           # Redux-RxJS store (createStore, select, state$)
+│   ├── component/       # Lifecycle, Component (state, setState, onMount, onUpdate, onUnmount), GraphRuntime, refs, context
+│   ├── connect/         # connect(store, mapStateToProps)(MyClass) -> ConnectedClass (class-based HOC)
+│   └── runtime/         # EventBus, CommandBus, QueryBus, HandleRegistry, BusDecorators
+├── tests/               # Unit and integration Jest tests
+├── benchmarks/          # Performance suites (`npm run bench`)
+├── docs/                # Architecture notes (`docs/ARCHITECTURE.md`)
+└── examples/            # Usage examples outside production build
+```
+
+Architecture overview: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+
+## Bootstrap
+
+`bootstrap(...)` — explicit root runtime entry contract.
+
+- Creates `EventBus`, `CommandBus`, `QueryBus`, and `HandleRegistry` when the caller does not pass them explicitly.
+- Mounts the root component via `GraphRuntime` (including ones wrapped with `connect`).
+- Returns a handle with `shutdown()` for graceful teardown: calls `onUnmount` in reverse order.
+- On startup failure, automatically cleans up already created runtime primitives.
+
+### Bootstrap-path example
+
+```typescript
+import { bootstrap, connect } from 'effectable';
+import { AppRoot, mapStateToProps } from './app';
+import { store } from './store';
+
+const ConnectedAppRoot = connect(store, mapStateToProps)(AppRoot);
+
+const handle = await bootstrap(
+  ConnectedAppRoot,
+  { /* refs, handles — BUT NOT store */ },
+  { name: 'app.root' },
+);
+
+await handle.shutdown(); // graceful teardown via onUnmount
+```
+
+## Host application roles
+
+In a consuming app, keep process concerns outside Effectable:
+
+1. **Process entry** — env/config, signal handlers, infrastructure adapters, then `bootstrap(...)`.
+2. **Root component** — extends `Component`, implements `compose()`, optional `onMount`/`onUnmount`; wrap with `connect(store, map)(Root)` so the store is injected by the HOC, not via props.
+3. On shutdown call `handle.shutdown()`.
+
+## Control plane / data plane boundary
+
+- **Control plane**: `bootstrap`, lifecycle orchestration (`onMount`/`onUnmount`), reconcile, context resolution, HOC `connect`.
+- **Data plane**: latency-sensitive work on an already-mounted graph.
+
+Rules:
+
+- `compose()`, reconcile, and context resolution must not sit on the hot execution path.
+- Data-plane components use direct refs and pre-resolved handles for the fast path.
+- `GraphRuntime` manages lifecycle; it is not meant to run on every high-frequency tick.
+
+## Store
+
+See [src/store/README.md](src/store/README.md): creating a store, selectors, middleware, `state$`, `select()`.
+
+## Component and connect
+
+Pattern for wiring a class to the store without manual subscriptions: reactive `state`, lifecycle hooks, automatic unsubscribe on unmount.
+
+### Lifecycle
+
+- **onMount** — once when the node mounts (start subscriptions, timers, background work).
+- **onUpdate(prev, next)** — on every state update (from `setState`; in a connected class also on every store emit).
+- **onUnmount** — once when the node unmounts (tear down subscriptions, stop effects).
+
+A connected class with `mapStateToProps` receives **one deferred** `onUpdate` after mount
+(post-mount kick-off) — see the migration note in [src/connect/README.md](src/connect/README.md).
+`setState` inside `onMount` in GraphRuntime buffers subtree reconcile and applies it after
+startup (same idea as deferring an update until after the mount pass completes).
+
+### Example: class and connect
+
+```typescript
+import { createStore } from 'effectable/store';
+import { Component } from 'effectable/component';
+import { connect } from 'effectable/connect';
+
+interface AppState { status: string }
+interface Props { id: string; status?: string }
+
+class MyServiceRaw extends Component<never, Props> {
+  public override onMount (): void {
+    console.log('Mounting, status:', this.props.status);
+  }
+
+  public override onUpdate (_prev: never, _next: never): void {
+    console.log('status updated:', this.props.status);
+  }
+
+  public override onUnmount (): void {
+    console.log('Unmounting, tear down subscriptions');
+  }
+}
+
+const store = createStore(reducer, initialState);
+const mapStateToProps = (state: AppState) => ({ status: state.status });
+
+export const MyService = connect(store, mapStateToProps)(MyServiceRaw);
+
+// in the parent's compose():
+//   h(MyService, { id: '1' })
+```
+
+`store` is passed into the HOC `connect` (closure) and MUST NOT appear in the component `props`.
+
+## Entry points
+
+- `effectable` — canonical public entrypoint (`bootstrap`, store, component, connect, runtime)
+- `effectable/bootstrap` — explicit root bootstrap-path
+- `effectable/store` — store
+- `effectable/component` — Component, Lifecycle, GraphRuntime, h, refs, context
+- `effectable/connect` — connect, MapStateToProps, ConnectOptions
+- `effectable/runtime` — EventBus, CommandBus, QueryBus, HandleRegistry, BusDecorators (`wireRuntimeBuses`, **`wireRuntimeBusesAll`** — wire several handlers to the same bus set; process code usually reuses the same `commandBus` / `queryBus` / `eventBus` as `bootstrap(...).runtime`, without a second `createRuntimeBuses` / `HandleRegistry`)
+
+## Publishing
+
+- **Canary** (`develop`): `npm install effectable@canary`
+- **Stable** (`main` / tags `vX.Y.Z`): `npm install effectable`
+
+Details: [docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+## License
+
+MIT © 2025–2026 Nick Nask, also known as Nikita Neskuchaev ([iamnikas](https://github.com/iamnikas)). See [LICENSE](./LICENSE).

package/build/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Nick Nask, also known as Nikita Neskuchaev (iamnikas)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/build/bootstrap/bootstrap.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Component-based bootstrap path for the Effectable root runtime.
+ *
+ * Mounts the root component via GraphRuntime (hidden in the implementation) and returns
+ * a handle with the root component instance and runtime buses. GraphRuntime / h / getRootInstance
+ * are not exposed — all mounting details are encapsulated here.
+ *
+ * @module Effectable/bootstrap/bootstrap
+ */
+import { Component } from '../component';
+import type { ComponentConstructor } from '../component';
+import type { RuntimeCommand, RuntimeEvent, RuntimeQuery } from '../runtime';
+import type { BootstrapHandle, BootstrapOptions } from './types';
+/**
+ * Mounts the root component via a hidden GraphRuntime and returns a handle
+ * with a ready instance, runtime buses, and an idempotent `shutdown()`.
+ *
+ * Example:
+ * ```ts
+ * const handle = await bootstrap(AppRoot, { logger }, { name: 'app.root' });
+ * const root = handle.rootInstance;
+ * await handle.shutdown();
+ * ```
+ *
+ * @param {ComponentConstructor<TProps>} type - root component class
+ * @param {TProps} props - root component props
+ * @param {BootstrapOptions<TCommand, TQuery, TEvent>} [options] - root runtime name and external runtime primitives
+ * @returns {Promise<BootstrapHandle<TComponent, TProps, TCommand, TQuery, TEvent>>} handle of the running root runtime
+ * @throws {Error} rethrown when mounting the root component fails
+ */
+export declare function bootstrap<TProps, TComponent extends Component<unknown, TProps> = Component<unknown, TProps>, TCommand extends RuntimeCommand = RuntimeCommand, TQuery extends RuntimeQuery = RuntimeQuery, TEvent extends RuntimeEvent = RuntimeEvent>(type: ComponentConstructor<TProps>, props: TProps, options?: BootstrapOptions<TCommand, TQuery, TEvent>): Promise<BootstrapHandle<TComponent, TProps, TCommand, TQuery, TEvent>>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/build/bootstrap/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/bootstrap/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAwC,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAOzD,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AAgIjB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EACN,UAAU,SAAS,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,EAC1E,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY,EAE1C,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAClC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,GACnD,OAAO,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CA0ExE"}

package/build/bootstrap/bootstrap.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Component-based bootstrap path for the Effectable root runtime.
+ *
+ * Mounts the root component via GraphRuntime (hidden in the implementation) and returns
+ * a handle with the root component instance and runtime buses. GraphRuntime / h / getRootInstance
+ * are not exposed — all mounting details are encapsulated here.
+ *
+ * @module Effectable/bootstrap/bootstrap
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bootstrap = bootstrap;
+const component_1 = require("../component");
+const runtime_1 = require("../runtime");
+const types_1 = require("./types");
+const DEFAULT_BOOTSTRAP_NAME = 'effectable.root';
+/**
+ * Creates runtime primitives for the bootstrap path and marks which of them belong to the current handle.
+ *
+ * @param {Partial<BootstrapRuntimePrimitives<TCommand, TQuery, TEvent>> | undefined} providedRuntime - external runtime primitives
+ * @returns {{ runtime: BootstrapRuntimePrimitives<TCommand, TQuery, TEvent>; owned: OwnedRuntimePrimitives }} set of runtime primitives and ownership map
+ */
+function createRuntimePrimitives(providedRuntime) {
+    const providedCommandBus = typeof providedRuntime === 'undefined'
+        ? undefined
+        : providedRuntime.commandBus;
+    const providedQueryBus = typeof providedRuntime === 'undefined'
+        ? undefined
+        : providedRuntime.queryBus;
+    const providedEventBus = typeof providedRuntime === 'undefined'
+        ? undefined
+        : providedRuntime.eventBus;
+    const providedHandleRegistry = typeof providedRuntime === 'undefined'
+        ? undefined
+        : providedRuntime.handleRegistry;
+    const commandBus = typeof providedCommandBus === 'undefined'
+        ? new runtime_1.CommandBus()
+        : providedCommandBus;
+    const queryBus = typeof providedQueryBus === 'undefined'
+        ? new runtime_1.QueryBus()
+        : providedQueryBus;
+    const eventBus = typeof providedEventBus === 'undefined'
+        ? new runtime_1.EventBus()
+        : providedEventBus;
+    const handleRegistry = typeof providedHandleRegistry === 'undefined'
+        ? new runtime_1.HandleRegistry()
+        : providedHandleRegistry;
+    return {
+        runtime: {
+            commandBus,
+            queryBus,
+            eventBus,
+            handleRegistry,
+        },
+        owned: {
+            commandBus: typeof providedCommandBus === 'undefined',
+            queryBus: typeof providedQueryBus === 'undefined',
+            eventBus: typeof providedEventBus === 'undefined',
+            handleRegistry: typeof providedHandleRegistry === 'undefined',
+        },
+    };
+}
+/**
+ * Clears only those runtime primitives owned by the current bootstrap handle.
+ *
+ * @param {BootstrapRuntimePrimitives<TCommand, TQuery, TEvent>} runtime - handle runtime primitives
+ * @param {OwnedRuntimePrimitives} owned - ownership map for the primitives
+ * @returns {void}
+ */
+function clearOwnedRuntimePrimitives(runtime, owned) {
+    if (owned.commandBus) {
+        runtime.commandBus.clear();
+    }
+    if (owned.queryBus) {
+        runtime.queryBus.clear();
+    }
+    if (owned.eventBus) {
+        runtime.eventBus.clear();
+    }
+    if (owned.handleRegistry) {
+        runtime.handleRegistry.clear();
+    }
+}
+/**
+ * Creates an observability identity for the bootstrap-path root runtime.
+ *
+ * @param {string} name - bootstrap root name
+ * @returns {BootstrapRuntimeNodeIdentity} root runtime identity
+ */
+function createBootstrapRootIdentity(name) {
+    return {
+        rootId: name,
+        nodeId: name,
+        displayName: name,
+        kind: types_1.BOOTSTRAP_RUNTIME_NODE_KIND.ROOT,
+        ownership: types_1.BOOTSTRAP_RUNTIME_NODE_OWNERSHIP.RUNTIME_OWNED,
+    };
+}
+/**
+ * Mounts the root component via a hidden GraphRuntime and returns a handle
+ * with a ready instance, runtime buses, and an idempotent `shutdown()`.
+ *
+ * Example:
+ * ```ts
+ * const handle = await bootstrap(AppRoot, { logger }, { name: 'app.root' });
+ * const root = handle.rootInstance;
+ * await handle.shutdown();
+ * ```
+ *
+ * @param {ComponentConstructor<TProps>} type - root component class
+ * @param {TProps} props - root component props
+ * @param {BootstrapOptions<TCommand, TQuery, TEvent>} [options] - root runtime name and external runtime primitives
+ * @returns {Promise<BootstrapHandle<TComponent, TProps, TCommand, TQuery, TEvent>>} handle of the running root runtime
+ * @throws {Error} rethrown when mounting the root component fails
+ */
+async function bootstrap(type, props, options) {
+    const name = typeof options !== 'undefined' && typeof options.name === 'string' && options.name !== ''
+        ? options.name
+        : DEFAULT_BOOTSTRAP_NAME;
+    const providedRuntime = typeof options === 'undefined' ? undefined : options.runtime;
+    const onAutoReconcileError = typeof options !== 'undefined' ? options.onAutoReconcileError : undefined;
+    const { runtime, owned } = createRuntimePrimitives(providedRuntime);
+    const rootIdentity = createBootstrapRootIdentity(name); // TODO: remove; let this be configured automatically
+    let graphRuntime = null;
+    let rootInstance = null;
+    let running = false;
+    try {
+        graphRuntime = await component_1.GraphRuntime.mount((0, component_1.h)(type, props), component_1.EMPTY_CONTEXT_SCOPE, {
+            commandBus: runtime.commandBus,
+            queryBus: runtime.queryBus,
+            eventBus: runtime.eventBus,
+        }, onAutoReconcileError);
+        const resolved = graphRuntime.getRootInstance();
+        if (resolved === null) {
+            throw new Error('bootstrap: root instance is null after GraphRuntime.mount');
+        }
+        rootInstance = resolved;
+        running = true;
+    }
+    catch (error) {
+        if (graphRuntime !== null) {
+            await graphRuntime.unmount();
+        }
+        clearOwnedRuntimePrimitives(runtime, owned);
+        throw error;
+    }
+    // graphRuntime and rootInstance are guaranteed non-null at this point (running === true).
+    const activeGraphRuntime = graphRuntime;
+    const activeRootInstance = rootInstance;
+    return {
+        name,
+        rootInstance: activeRootInstance,
+        props,
+        runtime,
+        identity: rootIdentity,
+        isRunning() {
+            return running;
+        },
+        async reconcile() {
+            if (!running) {
+                return;
+            }
+            await activeGraphRuntime.reconcile((0, component_1.h)(type, props));
+        },
+        async shutdown() {
+            if (!running) {
+                return;
+            }
+            running = false;
+            try {
+                await activeGraphRuntime.unmount();
+            }
+            finally {
+                clearOwnedRuntimePrimitives(runtime, owned);
+            }
+        },
+    };
+}
+//# sourceMappingURL=bootstrap.js.map

package/build/bootstrap/bootstrap.js.map

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

package/build/bootstrap/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public entry point of the Effectable bootstrap subsystem.
+ *
+ * @module Effectable/bootstrap
+ */
+export { bootstrap } from './bootstrap';
+export { BOOTSTRAP_RUNTIME_NODE_KIND, BOOTSTRAP_RUNTIME_NODE_OWNERSHIP, } from './types';
+export type { BootstrapHandle, BootstrapOptions, BootstrapRuntimeNodeIdentity, BootstrapRuntimeNodeKind, BootstrapRuntimeNodeOwnership, BootstrapRuntimePrimitives, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/build/bootstrap/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bootstrap/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EACL,2BAA2B,EAC3B,gCAAgC,GACjC,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,4BAA4B,EAC5B,wBAAwB,EACxB,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,SAAS,CAAC"}

package/build/bootstrap/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Public entry point of the Effectable bootstrap subsystem.
+ *
+ * @module Effectable/bootstrap
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOOTSTRAP_RUNTIME_NODE_OWNERSHIP = exports.BOOTSTRAP_RUNTIME_NODE_KIND = exports.bootstrap = void 0;
+var bootstrap_1 = require("./bootstrap");
+Object.defineProperty(exports, "bootstrap", { enumerable: true, get: function () { return bootstrap_1.bootstrap; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "BOOTSTRAP_RUNTIME_NODE_KIND", { enumerable: true, get: function () { return types_1.BOOTSTRAP_RUNTIME_NODE_KIND; } });
+Object.defineProperty(exports, "BOOTSTRAP_RUNTIME_NODE_OWNERSHIP", { enumerable: true, get: function () { return types_1.BOOTSTRAP_RUNTIME_NODE_OWNERSHIP; } });
+//# sourceMappingURL=index.js.map

package/build/bootstrap/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bootstrap/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAClB,iCAGiB;AAFf,oHAAA,2BAA2B,OAAA;AAC3B,yHAAA,gCAAgC,OAAA"}

package/build/bootstrap/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Types of the Effectable bootstrap subsystem.
+ *
+ * bootstrap mounts the root component via GraphRuntime (hidden in the implementation)
+ * and returns a handle with the root component instance and runtime buses.
+ *
+ * @module Effectable/bootstrap/types
+ */
+import type { Component } from '../component';
+import type { CommandBus, EventBus, HandleRegistry, QueryBus, RuntimeCommand, RuntimeEvent, RuntimeQuery } from '../runtime';
+/**
+ * Categories of runtime nodes in the bootstrap path.
+ */
+export declare const BOOTSTRAP_RUNTIME_NODE_KIND: {
+    readonly ROOT: "ROOT";
+    readonly MOLECULE: "MOLECULE";
+};
+export type BootstrapRuntimeNodeKind = (typeof BOOTSTRAP_RUNTIME_NODE_KIND)[keyof typeof BOOTSTRAP_RUNTIME_NODE_KIND];
+/**
+ * Ownership modes for a runtime node in the bootstrap path.
+ */
+export declare const BOOTSTRAP_RUNTIME_NODE_OWNERSHIP: {
+    readonly RUNTIME_OWNED: "RUNTIME_OWNED";
+    readonly COMPATIBILITY_BRIDGE: "COMPATIBILITY_BRIDGE";
+};
+export type BootstrapRuntimeNodeOwnership = (typeof BOOTSTRAP_RUNTIME_NODE_OWNERSHIP)[keyof typeof BOOTSTRAP_RUNTIME_NODE_OWNERSHIP];
+/**
+ * Observability identity of the root node in the bootstrap path.
+ */
+export interface BootstrapRuntimeNodeIdentity {
+    rootId: string;
+    nodeId: string;
+    displayName: string;
+    kind: BootstrapRuntimeNodeKind;
+    ownership: BootstrapRuntimeNodeOwnership;
+}
+/**
+ * Full set of runtime primitives raised by the bootstrap path by default.
+ * Includes four buses: command / query / event and HandleRegistry.
+ */
+export interface BootstrapRuntimePrimitives<TCommand extends RuntimeCommand = RuntimeCommand, TQuery extends RuntimeQuery = RuntimeQuery, TEvent extends RuntimeEvent = RuntimeEvent> {
+    commandBus: CommandBus<TCommand>;
+    queryBus: QueryBus<TQuery>;
+    eventBus: EventBus<TEvent>;
+    handleRegistry: HandleRegistry;
+}
+/**
+ * Optional parameters for a bootstrap call.
+ *
+ * @template TCommand - command family type
+ * @template TQuery - query family type
+ * @template TEvent - event family type
+ */
+export interface BootstrapOptions<TCommand extends RuntimeCommand = RuntimeCommand, TQuery extends RuntimeQuery = RuntimeQuery, TEvent extends RuntimeEvent = RuntimeEvent> {
+    /** Root runtime name; defaults to `effectable.root`. */
+    name?: string;
+    /** Partially or fully external runtime primitives; missing ones are created internally. */
+    runtime?: Partial<BootstrapRuntimePrimitives<TCommand, TQuery, TEvent>>;
+    /**
+     * Hook invoked on automatic reconcile failure (triggered by `setState()`).
+     * Allows logging or handling errors that would otherwise be ignored.
+     */
+    onAutoReconcileError?: (err: unknown) => void;
+}
+/**
+ * Handle of a running root runtime.
+ *
+ * @template TComponent - root component class
+ * @template TProps - root component props
+ * @template TCommand - command family type
+ * @template TQuery - query family type
+ * @template TEvent - event family type
+ */
+export interface BootstrapHandle<TComponent extends Component<unknown, TProps>, TProps, TCommand extends RuntimeCommand = RuntimeCommand, TQuery extends RuntimeQuery = RuntimeQuery, TEvent extends RuntimeEvent = RuntimeEvent> {
+    /** Root runtime name. */
+    name: string;
+    /** Root component instance that has already completed full startup. */
+    rootInstance: TComponent;
+    /** Props passed to the root component at bootstrap. */
+    props: TProps;
+    /** Runtime primitives (buses and registry) of the current handle. */
+    runtime: BootstrapRuntimePrimitives<TCommand, TQuery, TEvent>;
+    /** Observability identity of the root runtime. */
+    identity: BootstrapRuntimeNodeIdentity;
+    /**
+     * Checks whether the handle is still active (before shutdown).
+     *
+     * @returns {boolean} true if the handle has not been shut down yet
+     */
+    isRunning(): boolean;
+    /**
+     * Rebuilds the root runtime tree with the original props.
+     * Needed by external reactive sources because `Component.setState()` does not reconcile the subtree.
+     *
+     * @returns {Promise<void>} completion of the reconcile pass
+     */
+    reconcile(): Promise<void>;
+    /**
+     * Idempotently shuts down the root runtime: unmounts the tree and clears owned buses.
+     *
+     * @returns {Promise<void>}
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/bootstrap/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bootstrap/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;CAG9B,CAAC;AACX,MAAM,MAAM,wBAAwB,GAClC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,gCAAgC;;;CAGnC,CAAC;AACX,MAAM,MAAM,6BAA6B,GACvC,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,OAAO,gCAAgC,CAAC,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,wBAAwB,CAAC;IAC/B,SAAS,EAAE,6BAA6B,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B,CACzC,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY;IAE1C,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IACjC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,cAAc,EAAE,cAAc,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAC/B,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY;IAE1C,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,OAAO,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxE;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe,CAC9B,UAAU,SAAS,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,EAC7C,MAAM,EACN,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,MAAM,SAAS,YAAY,GAAG,YAAY;IAE1C,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,YAAY,EAAE,UAAU,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,EAAE,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9D,kDAAkD;IAClD,QAAQ,EAAE,4BAA4B,CAAC;IACvC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC;IACrB;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/build/bootstrap/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Types of the Effectable bootstrap subsystem.
+ *
+ * bootstrap mounts the root component via GraphRuntime (hidden in the implementation)
+ * and returns a handle with the root component instance and runtime buses.
+ *
+ * @module Effectable/bootstrap/types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOOTSTRAP_RUNTIME_NODE_OWNERSHIP = exports.BOOTSTRAP_RUNTIME_NODE_KIND = void 0;
+/**
+ * Categories of runtime nodes in the bootstrap path.
+ */
+exports.BOOTSTRAP_RUNTIME_NODE_KIND = {
+    ROOT: 'ROOT',
+    MOLECULE: 'MOLECULE',
+};
+/**
+ * Ownership modes for a runtime node in the bootstrap path.
+ */
+exports.BOOTSTRAP_RUNTIME_NODE_OWNERSHIP = {
+    RUNTIME_OWNED: 'RUNTIME_OWNED',
+    COMPATIBILITY_BRIDGE: 'COMPATIBILITY_BRIDGE',
+};
+//# sourceMappingURL=types.js.map

package/build/bootstrap/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/bootstrap/types.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAaH;;GAEG;AACU,QAAA,2BAA2B,GAAG;IACzC,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;CACZ,CAAC;AAIX;;GAEG;AACU,QAAA,gCAAgC,GAAG;IAC9C,aAAa,EAAE,eAAe;IAC9B,oBAAoB,EAAE,sBAAsB;CACpC,CAAC"}