@omnitron-dev/omnitron 0.1.3 → 0.3.0

package/dist/orchestrator/bootstrap-process.js

@@ -25,12 +25,33 @@ import 'reflect-metadata';
 import path from 'node:path';
 import { Application } from '@omnitron-dev/titan';
 import { createToken } from '@omnitron-dev/titan/nexus';
+import { Errors } from '@omnitron-dev/titan/errors';
 import { HttpTransport } from '@omnitron-dev/titan/netron/transport/http';
 import { WebSocketTransport } from '@omnitron-dev/titan/netron/transport/websocket';
 import { loadBootstrapConfig } from './bootstrap-loader.js';
+import { pathToFileURL } from 'node:url';
+import { queryTopologyService } from './topology-query.js';
+/**
+ * Convert an absolute filesystem path to a file:// URL string suitable as
+ * the anchor argument for `createRequire(...)`. Trailing slash on `p` is
+ * preserved so directory-anchored resolution behaves like `cd <p> && require`.
+ */
+function pathToFileUrl(p) {
+    return pathToFileURL(p).href;
+}
 // Inline PM decorator metadata — avoids importing the full PM module which
 // deadlocks when loaded from source (.ts) alongside the dist-loaded worker-runtime.
 const PROCESS_METADATA_KEY = Symbol.for('process:metadata');
+// These decorators are declared locally rather than imported from
+// `@omnitron-dev/titan-pm` on purpose: this file is a worker ENTRY POINT, and
+// pulling the package in would load it into every child process. They
+// interoperate through `Symbol.for`, which is realm-wide, so the metadata they
+// write is the same metadata `titan-pm`'s `worker-runtime` scans for.
+//
+// That agreement is the whole contract, and it is not enforced by the type
+// system — `a-local-decorator-still-agrees-with-the-runtime.test.ts` pins it.
+// Note the direction of the last divergence: titan-pm's exported `@OnShutdown`
+// wrote a prototype key nothing reads, and THESE copies were the correct ones.
 const PROCESS_METHOD_METADATA_KEY = Symbol.for('process:method:metadata');
 function Process(options = {}) {
     return (target) => {
@@ -75,6 +96,203 @@ function OnShutdown() {
 }
 // Topology DI token prefix — apps use createToken('topology:{processName}')
 const TOPOLOGY_TOKEN_PREFIX = 'topology:';
+/**
+ * Deadline for a topology RPC.
+ *
+ * A topology call is a worker-pool JOB — aggregate five minutes of candles,
+ * transform an upload — not a wire request, and netron's 5 s default is a
+ * deadline for the latter. `connect()` reads `requestTimeout` back out of the
+ * transport registry, and this path registered the unix transport without
+ * options, so every topology call inherited the 5 s.
+ *
+ * Measured on the stand over two days: 97 `OHLCV … aggregation failed` lines,
+ * 70 of them `RPC request timed out after 5000ms` — and scattered THROUGH
+ * healthy runs, minutes after `topology proxy became available`, between ticks
+ * that succeeded. Not a dead peer: a job that occasionally takes longer than
+ * five seconds. The timeout abandons the caller's wait without stopping the
+ * work, so the aggregation ran on and the operator got an error for it.
+ *
+ * 60 s is what `DaemonClient` already uses over this same socket, and it is
+ * still well inside the 5-minute aggregation interval, so a genuine hang
+ * surfaces within one tick rather than being hidden.
+ *
+ * MEASURED AFTER, because "it is fixed" is a different claim from "it is
+ * better": 2.39 failures/hour before, 0.55 after — a 4.3x reduction, not an
+ * elimination. The survivors still say `after 5000ms`, which means their
+ * `RemotePeer` was built with `requestTimeout` undefined, so some path reaches
+ * the daemon without the options set two lines below. The obvious candidates
+ * are ruled out by reading: `getTransportForAddress` resolves `unix://` to the
+ * transport named `unix`, `getOptions` is keyed by that same name, the
+ * reconnect path uses this same Netron, and the pool leg is 120 s. Finding the
+ * rest needs instrumentation on a live process, not more reading.
+ */
+const TOPOLOGY_REQUEST_TIMEOUT = 60_000;
+/**
+ * Announce which stage of start-up we reached.
+ *
+ * Start-up runs config load → module import → `Application.create` →
+ * hooks → transports → `start()`, and until now it reported nothing until it
+ * was finished. When an app hung — `acme/dev/main` did, repeatedly — the only
+ * artefact was `Worker startup timed out after 30000ms` with
+ * `stderrBytes: 0`: the supervisor knew the child never answered and nothing
+ * knew how far it had got.
+ *
+ * Each stage is written to stderr as a single line. stderr specifically,
+ * because the spawner already captures the last 64 KiB of it into the crash
+ * record — so a timeout now carries a trail ending at the stage that hung,
+ * with no new plumbing between the child and the daemon.
+ *
+ * The prefix is machine-greppable on purpose; `omnitron doctor` reads the
+ * last one to name the stalled stage.
+ */
+function reportStage(stage, detail) {
+    const suffix = detail ? ` ${detail}` : '';
+    process.stderr.write(`[omnitron:boot] ${stage}${suffix}\n`);
+}
+/**
+ * A topology proxy for a service that was not there yet.
+ *
+ * When the first `queryInterface` fails, this process used to register a
+ * proxy that THROWS on every call for the life of the process — so a service
+ * that appeared a second later was never seen. For a pool that is rare: pools
+ * register in step 1, before any consumer starts. For a sibling child it is
+ * the normal case, because provider and consumer are children of one
+ * supervisor and the provider can only be asked for its services after they
+ * have all started.
+ *
+ * Measured on priceverse: `CollectorWorker` registered on the daemon 7
+ * seconds after the server process asked for it, and the server's health
+ * check answered
+ *
+ *     Topology service 'CollectorWorker' unavailable: Service 'CollectorWorker' not found
+ *
+ * to every call for the rest of that process's life — while the same service,
+ * queried from a fresh client, answered `6 exchanges, 6 connected`.
+ *
+ * So: ask again on use. Once the query succeeds, hand over to the
+ * reconnecting proxy, which is what keeps it alive afterwards. A call made
+ * while it is still absent raises the same sentence as before, naming the
+ * service and the reason it could not be had THIS time — not the one from
+ * start-up.
+ *
+ * @internal exported for tests
+ */
+export function createDeferredTopologyProxy(netron, serviceName, daemonSocketUrl) {
+    let live = null;
+    let resolving = null;
+    const resolve = async () => {
+        resolving ??= (async () => {
+            try {
+                const peer = await netron.connect(daemonSocketUrl);
+                const handle = await peer.queryInterface(serviceName);
+                live = createReconnectingTopologyProxy(netron, serviceName, daemonSocketUrl, handle);
+            }
+            finally {
+                resolving = null;
+            }
+        })();
+        return resolving;
+    };
+    return new Proxy({}, {
+        get: (_target, prop) => {
+            if (typeof prop === 'symbol' || prop === 'then')
+                return undefined;
+            return async (...args) => {
+                if (!live) {
+                    try {
+                        await resolve();
+                    }
+                    catch (err) {
+                        throw new Error(`Topology service '${serviceName}' unavailable: ${err.message}`, { cause: err });
+                    }
+                }
+                return live[prop](...args);
+            };
+        },
+    });
+}
+/**
+ * A topology proxy that survives losing its connection.
+ *
+ * The interface `queryInterface` returns is bound to one socket. When that
+ * socket goes — a daemon restart, a transport hiccup, anything — every later
+ * call rejects with "Socket closed during RPC", forever, because nothing
+ * reconnects and the consumer is holding the same dead object. Consumers
+ * resolve this token once at construction, so the feature stays broken until
+ * the process is restarted.
+ *
+ * Observed exactly that way: pricing's OHLCV aggregation failed on every
+ * five-minute tick with that message while the service on the daemon was
+ * healthy and answering a freshly connected client immediately, and the app
+ * process held zero open connections to the daemon socket.
+ *
+ * So: on a call that fails because the connection is gone, reconnect, ask for
+ * the interface again, and retry once. One reconnect at a time, and a failure
+ * to reconnect surfaces the ORIGINAL error rather than a second one about the
+ * reconnect — the caller asked about their call.
+ *
+ * @internal exported for tests
+ */
+export function createReconnectingTopologyProxy(netron, serviceName, daemonSocketUrl, initial) {
+    let current = initial;
+    let reconnecting = null;
+    /**
+     * Errors that mean "this handle is no longer the service", i.e. re-query and
+     * try once more.
+     *
+     * The socket patterns are the obvious half. The other half is `Unknown
+     * member: 'x' is not defined in the service interface`, which is what a
+     * reconnect leaves behind when it lands while the worker's service is not
+     * yet registered on the daemon: `queryInterface` returns a definition
+     * without the methods, `current` is replaced by it, and every later call
+     * fails on a NAME rather than on a socket. That error matched nothing here,
+     * so the proxy stayed wrong until the app restarted — two of them on the
+     * stand, and no path back.
+     *
+     * Retrying a genuinely absent method costs one re-query and then raises the
+     * same error, so widening this cannot turn a real mistake into silence.
+     */
+    const needsFreshHandle = (error) => {
+        const message = String(error?.message ?? '');
+        return (/socket closed|connection closed|transport lost|not connected|socket is not open/i.test(message) ||
+            /unknown member|not defined in the service interface/i.test(message));
+    };
+    const reconnect = async () => {
+        reconnecting ??= (async () => {
+            try {
+                const peer = await netron.connect(daemonSocketUrl);
+                current = (await peer.queryInterface(serviceName));
+            }
+            finally {
+                reconnecting = null;
+            }
+        })();
+        return reconnecting;
+    };
+    const invoke = (prop, args) => current[prop](...args);
+    return new Proxy({}, {
+        get: (_target, prop) => {
+            if (typeof prop === 'symbol' || prop === 'then')
+                return undefined;
+            return async (...args) => {
+                try {
+                    return await invoke(prop, args);
+                }
+                catch (error) {
+                    if (!needsFreshHandle(error))
+                        throw error;
+                    try {
+                        await reconnect();
+                    }
+                    catch {
+                        throw error;
+                    }
+                    return await invoke(prop, args);
+                }
+            };
+        },
+    });
+}
 let BootstrapProcess = class BootstrapProcess {
     definition = null;
     entry = null;
@@ -91,7 +309,9 @@ let BootstrapProcess = class BootstrapProcess {
         const { bootstrapPath, processName: resolvedProcessName, portOffset: resolvedPortOffset, bundledModulePath, __daemonSocketUrl: daemonSocketUrl, __topologyConnects: topologyAccess, } = deps;
         // Prefer bundled module path (esbuild pre-built) over tsx runtime
         const hasTsx = !bundledModulePath && (process.execArgv ?? []).some((a) => a.includes('tsx'));
+        reportStage('config:loading', bootstrapPath);
         this.definition = await loadBootstrapConfig(bootstrapPath, { devMode: hasTsx || !!bundledModulePath });
+        reportStage('config:loaded', this.definition.name);
         // Find this process's entry in the topology.
         if (resolvedProcessName) {
             this.entry = this.definition.processes.find((p) => p.name === resolvedProcessName) ?? null;
@@ -109,12 +329,33 @@ let BootstrapProcess = class BootstrapProcess {
         const hooks = this.entry.hooks ?? this.definition.hooks;
         // beforeCreate hook
         if (hooks?.beforeCreate) {
+            reportStage('hook:beforeCreate');
             await hooks.beforeCreate();
         }
         // Import the module — prefer pre-bundled .mjs from BuildService,
         // fall back to resolving from bootstrap directory (tsx or dist/)
         const modulePath = bundledModulePath ?? path.resolve(path.dirname(bootstrapPath), this.entry.module);
+        reportStage('module:importing', modulePath);
         const moduleFile = await import(modulePath);
+        reportStage('module:imported');
+        // ────────────────────────────────────────────────────────────────────
+        // Container identity guard.
+        //
+        // Daemon imports `@omnitron-dev/titan` from its own pnpm peer-dep tree.
+        // App's bundled module imports `@omnitron-dev/titan-scheduler` etc. that
+        // transitively import `@omnitron-dev/titan/nexus` from the **app's**
+        // pnpm tree. If those resolve to different physical files (e.g. demon
+        // running from local omni source while app uses npm-published 0.1.3),
+        // the `Container` class identity differs → `Inject(Container)` cannot
+        // find the auto-registered token and module init fails with the cryptic
+        // "Dependency 'Container' not found".
+        //
+        // Detect this BEFORE Application.create() to surface a clear, actionable
+        // error instead of letting Application.start() blow up on every module
+        // that injects Container.
+        // ────────────────────────────────────────────────────────────────────
+        const moduleResolveDir = path.dirname(modulePath);
+        await this.assertContainerIdentity(moduleResolveDir);
         // Resolve module class: prefer default export, then first named export (class),
         // then the module namespace itself (for compatibility with non-standard modules).
         let ModuleClass = moduleFile.default;
@@ -131,13 +372,17 @@ let BootstrapProcess = class BootstrapProcess {
             ModuleClass = moduleFile;
         }
         // Create Titan Application
+        reportStage('application:creating');
         this.app = await Application.create(ModuleClass, {
             name: this.definition.name,
             version: this.definition.version,
         });
+        reportStage('application:created');
         // afterCreate hook
         if (hooks?.afterCreate) {
+            reportStage('hook:afterCreate');
             await hooks.afterCreate(this.app);
+            reportStage('hook:afterCreate:done');
         }
         // Inject topology proxies via Netron-native connection to daemon.
         // topology.access contains Netron service names (e.g., 'OhlcvAggregatorWorker')
@@ -190,7 +435,11 @@ let BootstrapProcess = class BootstrapProcess {
                 ...(wsConfig.path && { pathPrefix: wsConfig.path }),
                 ...(wsConfig.keepAlive && { keepAlive: { enabled: true, ...wsConfig.keepAlive } }),
             };
-            // Wire auth invocationWrapper for WebSocket too
+            // Applied per invocation by `remote-peer.ts`, so an app that
+            // establishes its RLS scope in this wrapper gets that scope on
+            // WebSocket calls too. It did not until recently: only the HTTP server
+            // read the option, and a WS call ran with no scope at all — kysera
+            // fails closed, so the symptom was empty results, not leaked rows.
             if (auth?.invocationWrapper) {
                 wsOptions['invocationWrapper'] = auth.invocationWrapper;
             }
@@ -201,26 +450,39 @@ let BootstrapProcess = class BootstrapProcess {
         }
         // beforeStart hook
         if (hooks?.beforeStart) {
+            reportStage('hook:beforeStart');
             await hooks.beforeStart(this.app);
+            reportStage('hook:beforeStart:done');
         }
         // Start the application
+        reportStage('application:starting');
         await this.app.start();
+        reportStage('application:started');
         // afterStart hook
         if (hooks?.afterStart) {
+            reportStage('hook:afterStart');
             await hooks.afterStart(this.app);
+            reportStage('hook:afterStart:done');
         }
+        reportStage('ready');
     }
     /**
-     * Health check — delegates to definition hook if present.
+     * Health check — the app's own hook, handed the running Application so it
+     * has something to ask. Without an Application there is nothing to be
+     * healthy: the hook is not called, and the answer says why.
      */
     async checkHealth() {
+        if (!this.app) {
+            return {
+                status: 'unhealthy',
+                checks: [{ name: 'application', status: 'fail', message: 'the application has not started in this process' }],
+            };
+        }
         const hooks = this.entry?.hooks ?? this.definition?.hooks;
         if (hooks?.onHealthCheck) {
-            return hooks.onHealthCheck();
+            return hooks.onHealthCheck(this.app);
         }
-        return {
-            status: this.app ? 'healthy' : 'unhealthy',
-        };
+        return { status: 'healthy' };
     }
     /**
      * Graceful shutdown — runs lifecycle hooks and stops the Application.
@@ -252,6 +514,44 @@ let BootstrapProcess = class BootstrapProcess {
             }
         }
     }
+    /**
+     * What this process's own transports answered — the app's traffic.
+     *
+     * The process manager asks this inside `__getProcessMetrics`
+     * (`IProcessTrafficReporter`). Before, it reported the call counters of
+     * THIS wrapper's methods, which the supervisor calls for health and
+     * metrics: `omnitron metrics` counted its own questions as the app's
+     * requests and never saw one real one.
+     *
+     * HTTP servers answer a traffic snapshot; a process with several sums the
+     * counts and reports the latency of its busiest server. A process with no
+     * HTTP server (a queue worker) has no traffic to report: `null`, which the
+     * daemon shows as «not reported», not as zero.
+     */
+    reportTraffic() {
+        const servers = this.app?.netron?.transportServers;
+        if (!servers)
+            return null;
+        let traffic = null;
+        for (const server of servers.values()) {
+            const snapshot = server.getTrafficSnapshot?.();
+            if (!snapshot)
+                continue;
+            if (!traffic) {
+                traffic = { ...snapshot };
+                continue;
+            }
+            traffic.requests += snapshot.requests;
+            traffic.serverErrors += snapshot.serverErrors;
+            traffic.clientErrors += snapshot.clientErrors;
+            traffic.probes += snapshot.probes;
+            traffic.held = (traffic.held ?? 0) + (snapshot.held ?? 0);
+            traffic.active += snapshot.active;
+            if ((snapshot.latency?.count ?? 0) > (traffic.latency?.count ?? 0))
+                traffic.latency = snapshot.latency;
+        }
+        return traffic;
+    }
     /**
      * Returns the resolved HTTP port (useful for pool instances on offset ports).
      */
@@ -273,6 +573,56 @@ let BootstrapProcess = class BootstrapProcess {
             return [];
         return this.app.netron.getServiceMetadata();
     }
+    /**
+     * Invoke a method on one of the Application's own Netron services.
+     *
+     * The pool's PM service is THIS class — `BootstrapApp` — so `pool.execute(m)`
+     * can only reach the methods listed on it. `topology.expose` builds a daemon
+     * proxy out of the method names an app service reports through
+     * `getExposedServices()` above and used to route them straight into
+     * `pool.execute(name)`, which meant every such call asked `BootstrapApp` for
+     * a method it has never had. The daemon exposed the service, the consumer's
+     * `queryInterface` succeeded, and the first call came back "Unknown member" —
+     * from inside the pool, about a different service than the one the caller
+     * named. Nothing in the chain connects the two names, which is why the whole
+     * feature could be wired end to end and still never work.
+     *
+     * This is the hop that was missing: name the service, and the call lands on
+     * the Application's own stub for it.
+     */
+    async callExposedService(serviceName, method, args = []) {
+        if (!this.app?.netron) {
+            throw Errors.internal(`Cannot call ${serviceName}.${method}: the application has no Netron`);
+        }
+        const iface = (await this.app.netron.peer.queryInterface(serviceName));
+        const fn = iface[method];
+        if (typeof fn !== 'function') {
+            throw Errors.badRequest(`Service '${serviceName}' has no method '${method}'. Methods reachable over the topology ` +
+                'proxy are those marked @Public — an undecorated method is absent from the service metadata.');
+        }
+        return fn.call(iface, ...args);
+    }
+    /**
+     * Returns the DI dependency graph of the running Application's
+     * container — nodes per registered token, edges per declared
+     * dependency. Used by `omnitron inspect <app> --graph`.
+     *
+     * The graph is computed lazily from the live container state so it
+     * reflects whatever was actually wired up (post-`@Module`-imports,
+     * post-`registerProviders`). It does NOT include the parent
+     * container's registrations by default — the local module surface
+     * is what triage cares about.
+     */
+    getDependencyGraph(options = {}) {
+        if (!this.app) {
+            return { nodes: [], edges: [] };
+        }
+        const container = this.app.container;
+        if (typeof container.exportGraph !== 'function') {
+            return { nodes: [], edges: [] };
+        }
+        return container.exportGraph(options);
+    }
     /**
      * Connect to daemon's Netron and queryInterface() for sibling services.
      *
@@ -286,6 +636,7 @@ let BootstrapProcess = class BootstrapProcess {
         const { UnixSocketTransport } = await import('@omnitron-dev/titan/netron/transport/unix');
         // Register Unix transport on the app's Netron for outgoing client connections
         this.app.netron.registerTransport('unix', () => new UnixSocketTransport());
+        this.app.netron.setTransportOptions('unix', { requestTimeout: TOPOLOGY_REQUEST_TIMEOUT });
         // Connect with timeout — fail fast if daemon socket is unavailable
         const connectTimeout = 10_000;
         const daemonPeer = await Promise.race([
@@ -293,12 +644,23 @@ let BootstrapProcess = class BootstrapProcess {
             new Promise((_, reject) => setTimeout(() => reject(new Error(`Daemon socket connection timeout (${connectTimeout}ms): ${daemonSocketUrl}`)), connectTimeout)),
         ]);
         for (const serviceName of serviceNames) {
+            // Asking once turned a half-second of startup order into a logged
+            // failure: this process connects as soon as it is up, and the pool
+            // that provides the service registers a beat later. Six such lines a
+            // day on the stand, none of them an outcome. `queryTopologyService`
+            // covers the window; a service that is genuinely absent still lands in
+            // the catch below, where the warning means what it says.
+            const queried = await queryTopologyService(daemonPeer, serviceName);
             try {
-                const proxy = await daemonPeer.queryInterface(serviceName);
+                if (!queried.ok)
+                    throw queried.error;
+                const proxy = queried.proxy;
                 // Register under topology:{ServiceName} — consumers inject via
                 // createToken('topology:OhlcvAggregatorWorker')
                 const token = createToken(`${TOPOLOGY_TOKEN_PREFIX}${serviceName}`);
-                this.app.container.register(token, { useValue: proxy });
+                this.app.container.register(token, {
+                    useValue: createReconnectingTopologyProxy(this.app.netron, serviceName, daemonSocketUrl, proxy),
+                });
             }
             catch (err) {
                 const entry = JSON.stringify({
@@ -308,20 +670,136 @@ let BootstrapProcess = class BootstrapProcess {
                     msg: `[topology] Failed to query service '${serviceName}' from daemon: ${err.message}`,
                 });
                 process.stderr.write(entry + '\n');
-                // Register an error-throwing proxy so callers get a clear error at call-time
-                // instead of a cryptic "token not found" DI error.
-                const errorProxy = new Proxy({}, {
-                    get: (_target, prop) => {
-                        if (typeof prop === 'symbol' || prop === 'then')
-                            return undefined;
-                        return () => { throw new Error(`Topology service '${serviceName}' unavailable: ${err.message}`); };
-                    },
-                });
+                // Register a proxy that asks AGAIN on use, rather than one that
+                // throws for the life of the process. A sibling child registers its
+                // services only after every child has started, so "not found" here is
+                // the ordinary case, not a verdict — see
+                // `createDeferredTopologyProxy`.
                 const token = createToken(`${TOPOLOGY_TOKEN_PREFIX}${serviceName}`);
-                this.app.container.register(token, { useValue: errorProxy });
+                this.app.container.register(token, {
+                    useValue: createDeferredTopologyProxy(this.app.netron, serviceName, daemonSocketUrl),
+                });
             }
         }
     }
+    /**
+     * Verify that `Container` class imported by Titan modules in the app's
+     * dependency tree (titan-scheduler, titan-events, etc.) has the same
+     * physical identity as the daemon's `Container` class.
+     *
+     * The daemon resolves `@omnitron-dev/titan` from its own pnpm tree and
+     * uses that to construct `Application` (which auto-registers itself as
+     * the `Container` token). The app's bundled module imports titan-scheduler
+     * (etc.), which transitively imports `@omnitron-dev/titan/nexus`. If those
+     * two paths resolve to different physical files (e.g. monorepo dev vs
+     * published version), `Container` becomes two distinct classes —
+     * `Inject(Container)` then cannot find the auto-registered token and
+     * every consumer fails with the misleading "Dependency 'Container' not
+     * found" during module initialization.
+     *
+     * We detect this **before** Application.create() by resolving titan from
+     * both contexts (daemon-side via static import, app-side via dynamic
+     * import using the module's directory as the resolution base) and
+     * comparing the realpath. On mismatch we throw a self-explanatory error.
+     *
+     * Resolution is best-effort: if the app does not depend on titan
+     * transitively (rare for a Titan @Module bundle), we skip silently.
+     */
+    async assertContainerIdentity(moduleResolveDir) {
+        const { realpathSync, existsSync, readFileSync } = await import('node:fs');
+        const { createRequire } = await import('node:module');
+        /**
+         * Resolve the **package root directory** of `pkgName` from `fromUrl`.
+         *
+         * `require.resolve('foo/package.json')` does NOT work universally because
+         * `package.json` may be hidden behind a strict `"exports"` field
+         * (titan does this) and triggers ERR_PACKAGE_PATH_NOT_EXPORTED. Instead
+         * we resolve the package's MAIN entry — which IS guaranteed to be in
+         * "exports" — and walk up to the nearest directory containing a
+         * `package.json` whose `name` matches.
+         */
+        const resolvePackageRoot = (fromUrl, pkgName) => {
+            try {
+                const req = createRequire(fromUrl);
+                // Resolve any subpath that's guaranteed to exist — the bare specifier
+                // returns the package's main entry per Node's exports algorithm.
+                const entry = req.resolve(pkgName);
+                let dir = path.dirname(realpathSync(entry));
+                const root = path.parse(dir).root;
+                while (dir !== root) {
+                    const pkgPath = path.join(dir, 'package.json');
+                    if (existsSync(pkgPath)) {
+                        try {
+                            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                            if (pkg.name === pkgName)
+                                return realpathSync(dir);
+                        }
+                        catch {
+                            // Malformed package.json — keep walking up.
+                        }
+                    }
+                    const parent = path.dirname(dir);
+                    if (parent === dir)
+                        break;
+                    dir = parent;
+                }
+            }
+            catch {
+                // package not resolvable → caller decides what to do
+            }
+            return null;
+        };
+        // Daemon-side titan root — anchored to bootstrap-process's own URL so
+        // we always probe omnitron's *own* dependency tree.
+        const daemonTitanRoot = resolvePackageRoot(import.meta.url, '@omnitron-dev/titan');
+        if (!daemonTitanRoot) {
+            // Daemon's own titan is unreachable — guard cannot meaningfully
+            // compare identities. This should not happen in practice.
+            return;
+        }
+        // App-side titan root — anchored to the app module's directory so Node's
+        // resolution algorithm walks the **app's** node_modules tree.
+        const moduleAnchor = pathToFileUrl(`${moduleResolveDir}/`);
+        let appTitanRoot = resolvePackageRoot(moduleAnchor, '@omnitron-dev/titan');
+        if (!appTitanRoot) {
+            // App may declare titan only transitively (via titan-scheduler,
+            // titan-events, …). Hop through the transitive package that's most
+            // likely present.
+            const transitive = resolvePackageRoot(moduleAnchor, '@omnitron-dev/titan-scheduler')
+                ?? resolvePackageRoot(moduleAnchor, '@omnitron-dev/titan-events');
+            if (!transitive) {
+                // App genuinely has no titan in its closure — nothing to compare.
+                return;
+            }
+            appTitanRoot = resolvePackageRoot(pathToFileUrl(`${transitive}/`), '@omnitron-dev/titan');
+            if (!appTitanRoot)
+                return;
+        }
+        if (appTitanRoot === daemonTitanRoot) {
+            return; // identities match — happy path
+        }
+        // Mismatch — produce a high-signal error.
+        const msg = `Titan package identity mismatch detected between omnitron daemon and app '${this.definition?.name ?? '<unknown>'}'.\n\n` +
+            `  Daemon resolves @omnitron-dev/titan from:\n    ${daemonTitanRoot}\n\n` +
+            `  App   resolves @omnitron-dev/titan from:\n    ${appTitanRoot}\n\n` +
+            `These are different physical installations, so the 'Container' class identity differs.\n` +
+            `Provider injections like @Inject(Container) (used internally by titan-scheduler, titan-events,\n` +
+            `etc.) will fail with the cryptic message "Dependency 'Container' not found".\n\n` +
+            `How to fix:\n` +
+            `  1. Ensure the daemon and the app are using the SAME @omnitron-dev/titan installation.\n` +
+            `  2. If you are running omnitron from a local monorepo while the app installs published\n` +
+            `     versions, add pnpm overrides in the app project's package.json:\n\n` +
+            `       "pnpm": {\n` +
+            `         "overrides": {\n` +
+            `           "@omnitron-dev/titan": "link:<path-to-omni>/packages/titan",\n` +
+            `           "@omnitron-dev/omnitron": "link:<path-to-omni>/apps/omnitron",\n` +
+            `           "@omnitron-dev/titan-scheduler": "link:<path-to-omni>/packages/titan-scheduler",\n` +
+            `           ...other @omnitron-dev/* packages used by the app\n` +
+            `         }\n` +
+            `       }\n\n` +
+            `  3. After updating overrides run 'pnpm install' in the app project.`;
+        throw new Error(msg);
+    }
 };
 __decorate([
     HealthCheck(),