threadforge 0.1.1 → 0.2.1

package/dist/services/worker-bootstrap.js

@@ -0,0 +1,744 @@
+/**
+ * Worker Bootstrap v3
+ *
+ * Loads services, builds proxy clients, and injects them.
+ *
+ * After bootstrap, a service can call:
+ *   await this.users.getUser('123')
+ *
+ * Which transparently routes through:
+ *   - Direct function call (colocated services, same process)
+ *   - UDS (different process, same machine)
+ *   - Supervisor IPC fallback (startup race)
+ */
+import { createHmac } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { EndpointResolver } from "../core/EndpointResolver.js";
+import { ForgeContext, NOT_HANDLED } from "../core/ForgeContext.js";
+import { RequestContext } from "../core/RequestContext.js";
+import { buildServiceProxies, createServiceProxy } from "../decorators/ServiceProxy.js";
+import { applyStaticContractWrappers, getContract } from "../decorators/index.js";
+import { resolveRpcOptionsForTarget } from "../core/RpcConfig.js";
+import { IPC_PROTOCOL_VERSION } from "../core/ipc-errors.js";
+import { resolveStaticMountsForService } from "../frontend/SiteResolver.js";
+import { REGISTRY_MODES, RegistryMode, ServiceMode, SERVICE_TYPES, ServiceType, } from "../core/config-enums.js";
+// ─── Configuration ──────────────────────────────────────────
+// A6: Consolidate all env var reads into a single structured config object
+function parseWorkerConfig() {
+    const mode = process.env.FORGE_MODE;
+    return {
+        groupName: process.env.FORGE_GROUP_NAME,
+        serviceEntries: process.env.FORGE_SERVICE_ENTRIES,
+        serviceNames: process.env.FORGE_SERVICE_NAMES,
+        port: process.env.FORGE_PORT,
+        workerId: process.env.FORGE_WORKER_ID,
+        threadCount: process.env.FORGE_THREAD_COUNT,
+        mode: mode === ServiceMode.CLUSTER ? ServiceMode.CLUSTER : ServiceMode.CLUSTER,
+        serviceTypes: process.env.FORGE_SERVICE_TYPES,
+        channels: process.env.FORGE_CHANNELS,
+        hostMeta: process.env.FORGE_HOST_META,
+        registryMode: process.env.FORGE_REGISTRY_MODE ?? RegistryMode.EMBEDDED,
+        registryHost: process.env.FORGE_HOST,
+        servicePorts: process.env.FORGE_SERVICE_PORTS,
+        plugins: process.env.FORGE_PLUGINS,
+        servicePlugins: process.env.FORGE_SERVICE_PLUGINS,
+        configPath: process.env.FORGE_CONFIG_PATH,
+        serviceEndpoints: process.env.FORGE_SERVICE_ENDPOINTS,
+        sites: process.env.FORGE_SITES,
+        sitesFile: process.env.FORGE_SITES_FILE,
+        ingress: process.env.FORGE_INGRESS,
+        serviceRpc: process.env.FORGE_SERVICE_RPC,
+    };
+}
+const workerConfig = parseWorkerConfig();
+const hostMeta = workerConfig.hostMeta ? JSON.parse(workerConfig.hostMeta) : null;
+let ingressConfig = {};
+if (workerConfig.ingress) {
+    try {
+        ingressConfig = JSON.parse(workerConfig.ingress);
+    }
+    catch (err) {
+        console.warn(`[ThreadForge] Invalid FORGE_INGRESS payload, using defaults: ${err.message}`);
+    }
+}
+let sites = null;
+let sitesPayload = workerConfig.sites;
+if (!sitesPayload && workerConfig.sitesFile) {
+    try {
+        sitesPayload = fs.readFileSync(workerConfig.sitesFile, "utf8");
+    }
+    catch (err) {
+        console.warn(`[ThreadForge] Could not read FORGE_SITES_FILE, static mounts disabled: ${err.message}`);
+    }
+}
+if (sitesPayload) {
+    try {
+        sites = JSON.parse(sitesPayload);
+    }
+    catch (err) {
+        console.warn(`[ThreadForge] Invalid FORGE_SITES payload, static mounts disabled: ${err.message}`);
+    }
+}
+async function _deliverRemoteEvent(url, body, headers, serviceName, maxRetries = 3) {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            const resp = await fetch(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(5000),
+            });
+            if (resp.ok)
+                return;
+            // Non-retryable status codes
+            if (resp.status >= 400 && resp.status < 500)
+                return;
+        }
+        catch (err) {
+            if (attempt === maxRetries - 1) {
+                console.error(`[ThreadForge] Remote event delivery to ${serviceName} failed after ${maxRetries} attempts: ${err.message}`);
+                return;
+            }
+        }
+        // Exponential backoff: 100ms, 200ms, 400ms
+        await new Promise((resolve) => setTimeout(resolve, 100 * 2 ** attempt));
+    }
+}
+/**
+ * Look up which project owns a given service name.
+ * Returns { projectId, schema, keyPrefix } or null.
+ */
+function resolveProjectForService(serviceName) {
+    if (!hostMeta)
+        return null;
+    for (const [projectId, meta] of Object.entries(hostMeta)) {
+        if (meta.services.includes(serviceName)) {
+            return { projectId, schema: meta.schema, keyPrefix: meta.keyPrefix };
+        }
+    }
+    return null;
+}
+// Hoisted reference so emergency shutdown handlers can access it
+let _localServices = null;
+let emergencyShutdownPromise = null;
+// M-CORE-4: Module-level flag so emergencyShutdown can check if normal shutdown is running
+let shutdownInProgress = false;
+// Track unhandled rejections — exit only if 5+ within 60 seconds
+let _rejectionCount = 0;
+let _rejectionWindowStart = Date.now();
+const REJECTION_THRESHOLD = 5;
+const REJECTION_WINDOW_MS = 60_000;
+async function emergencyShutdown(reason, err) {
+    if (emergencyShutdownPromise) {
+        await emergencyShutdownPromise.catch(() => { });
+        process.exit(1);
+        return;
+    }
+    // M-CORE-4: Skip service._stop() if normal shutdown is already running
+    // to prevent double-cleanup of services
+    const skipServiceStop = shutdownInProgress;
+    emergencyShutdownPromise = (async () => {
+        console.error(`[ThreadForge] ${reason}:`, err);
+        try {
+            if (_localServices && !skipServiceStop) {
+                for (const [, { service }] of _localServices) {
+                    try {
+                        await Promise.race([
+                            service._stop?.(),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error("Stop timed out")), 5000)),
+                        ]);
+                    }
+                    catch {
+                        // Swallow errors during emergency shutdown
+                    }
+                }
+            }
+        }
+        catch {
+            // Swallow errors during emergency shutdown
+        }
+        process.exit(1);
+    })();
+    await emergencyShutdownPromise;
+}
+function handleUnhandledRejection(err) {
+    const now = Date.now();
+    // Reset window if it has elapsed
+    if (now - _rejectionWindowStart > REJECTION_WINDOW_MS) {
+        _rejectionCount = 0;
+        _rejectionWindowStart = now;
+    }
+    _rejectionCount++;
+    console.error(`[ThreadForge] SEVERE: Unhandled rejection (${_rejectionCount}/${REJECTION_THRESHOLD} in window):`, err);
+    if (err?.stack)
+        console.error(err.stack);
+    if (_rejectionCount >= REJECTION_THRESHOLD) {
+        console.error(`[ThreadForge] ${REJECTION_THRESHOLD}+ unhandled rejections within ${REJECTION_WINDOW_MS / 1000}s — exiting`);
+        emergencyShutdown("Repeated unhandled rejections", err);
+    }
+}
+async function bootstrap() {
+    // RT-H2: Register emergency handlers early so exceptions during any phase get cleanup
+    process.on("uncaughtException", (err) => emergencyShutdown("Uncaught exception", err));
+    process.on("unhandledRejection", (err) => handleUnhandledRejection(err));
+    // RT-C2: Re-entrancy guard for graceful shutdown (uses module-level `shutdownInProgress`)
+    // H-RT-4: Register signal handlers early so SIGTERM/SIGINT during any phase triggers cleanup
+    process.once("SIGTERM", () => shutdown("SIGTERM"));
+    process.once("SIGINT", () => shutdown("SIGINT"));
+    const entries = workerConfig
+        .serviceEntries.split(",")
+        .filter((e) => e.trim())
+        .map((e) => {
+        const eqIdx = e.indexOf("=");
+        if (eqIdx === -1) {
+            throw new Error(`Invalid FORGE_SERVICE_ENTRIES format: "${e}". Expected "name=path".`);
+        }
+        const name = e.slice(0, eqIdx).trim();
+        const entryPath = e.slice(eqIdx + 1).trim();
+        if (!name || !entryPath) {
+            throw new Error(`Invalid FORGE_SERVICE_ENTRIES entry: "${e}". Name and path are both required.`);
+        }
+        return { name, entry: entryPath };
+    });
+    if (entries.length === 0) {
+        throw new Error("FORGE_SERVICE_ENTRIES is empty or contains no valid entries");
+    }
+    const typeMap = {};
+    if (workerConfig.serviceTypes) {
+        for (const pair of workerConfig.serviceTypes.split(",")) {
+            const [name, type] = pair.split("=");
+            if (SERVICE_TYPES.includes(type)) {
+                typeMap[name] = type;
+            }
+            else {
+                typeMap[name] = ServiceType.INTERNAL;
+            }
+        }
+    }
+    // Parse declared channels to know which services we might talk to
+    let declaredChannels = [];
+    try {
+        declaredChannels = JSON.parse(workerConfig.channels || "[]");
+    }
+    catch {
+        // Swallow parse errors — use empty channels
+    }
+    const port = parseInt(workerConfig.port, 10);
+    const workerId = parseInt(workerConfig.workerId, 10);
+    const threadCount = parseInt(workerConfig.threadCount, 10);
+    // Phase 1: Load all service modules (P13: parallel imports)
+    const loaded = new Map();
+    /** service name → class (for proxy building) */
+    const serviceClasses = new Map();
+    const resolvedEntries = entries.map(({ name, entry }) => ({
+        name,
+        entry,
+        url: pathToFileURL(path.resolve(process.cwd(), entry)).href,
+    }));
+    const importResults = await Promise.all(resolvedEntries.map(async ({ name, entry, url }) => {
+        try {
+            const mod = (await import(url));
+            return { name, entry, mod, error: null };
+        }
+        catch (err) {
+            return { name, entry, mod: null, error: err };
+        }
+    }));
+    for (const { name, entry, mod, error } of importResults) {
+        if (error) {
+            console.error(`[ThreadForge] Failed to load service "${name}" from ${entry}: ${error.message}`);
+            if (error.stack)
+                console.error(error.stack);
+            throw new Error(`Service "${name}" failed to load from "${entry}": ${error.message}`);
+        }
+        const ServiceClass = (mod.default ?? mod);
+        if (typeof ServiceClass !== "function") {
+            throw new Error(`Service "${entry}" must export a class. Got: ${typeof ServiceClass}`);
+        }
+        const instance = new ServiceClass();
+        loaded.set(name, { ServiceClass, instance });
+        serviceClasses.set(name, ServiceClass);
+    }
+    // Also register remote service classes if we know about them
+    // (from channels config). For remote services we don't have the
+    // class, so proxies will use dynamic dispatch.
+    const allConnectedServices = new Set();
+    for (const ch of declaredChannels) {
+        allConnectedServices.add(ch.from);
+        allConnectedServices.add(ch.to);
+    }
+    // Phase 2: Create contexts and local service registry
+    const localServices = new Map();
+    _localServices = localServices;
+    function localSend(fromName, target, payload) {
+        const local = localServices.get(target);
+        if (!local)
+            return false;
+        Promise.resolve(local.service.onMessage(fromName, payload)).catch((err) => {
+            local.ctx?.logger?.error?.("onMessage error", { from: fromName, error: err.message });
+            local.ctx?.metrics?.increment?.("forge_local_send_errors_total", { target });
+        });
+        return true;
+    }
+    async function localRequest(fromName, target, payload) {
+        const local = localServices.get(target);
+        if (local) {
+            return local.service.onRequest(fromName, payload);
+        }
+        return NOT_HANDLED;
+    }
+    // Create EndpointResolver from env — shared by all contexts in this worker
+    const endpointResolver = EndpointResolver.fromEnv();
+    for (const [name, { instance }] of loaded) {
+        const serviceType = typeMap[name] ?? ServiceType.INTERNAL;
+        const isEdge = serviceType === ServiceType.EDGE;
+        const ctx = new ForgeContext({
+            serviceName: name,
+            port: isEdge ? port : 0,
+            workerId,
+            threadCount,
+            mode: workerConfig.mode,
+            serviceType,
+            ingress: ingressConfig,
+            sendIPC: (msg) => {
+                if (process.send)
+                    process.send(msg);
+            },
+            localSend: (target, payload) => localSend(name, target, payload),
+            localRequest: (target, payload) => localRequest(name, target, payload),
+            staticMounts: resolveStaticMountsForService(name, sites),
+        });
+        ctx._endpointResolver = endpointResolver;
+        const projectInfo = resolveProjectForService(name);
+        if (projectInfo) {
+            ctx._projectId = projectInfo.projectId;
+            ctx._projectSchema = projectInfo.schema;
+            ctx._projectKeyPrefix = projectInfo.keyPrefix;
+        }
+        ctx._emitEvent = (eventName, data) => {
+            const eventPayload = { __forge_event: eventName, __forge_data: data };
+            for (const ch of declaredChannels) {
+                let target;
+                if (ch.from === name)
+                    target = ch.to;
+                else if (ch.to === name)
+                    target = ch.from;
+                else
+                    continue;
+                if (localSend(name, target, eventPayload))
+                    continue;
+                const endpoint = endpointResolver.resolve(target);
+                if (endpoint?.remote) {
+                    // Propagate RequestContext so events can be traced back to originating requests
+                    const rctx = RequestContext.current();
+                    const headers = { "Content-Type": "application/json" };
+                    if (rctx)
+                        Object.assign(headers, rctx.toHeaders());
+                    // Sign event delivery with HMAC when FORGE_INTERNAL_SECRET is set
+                    const internalSecret = process.env.FORGE_INTERNAL_SECRET;
+                    if (internalSecret) {
+                        const ts = String(Date.now());
+                        const sig = createHmac("sha256", internalSecret).update(`POST:/__forge/event:${ts}`).digest("hex");
+                        headers["x-forge-internal-sig"] = sig;
+                        headers["x-forge-internal-ts"] = ts;
+                    }
+                    _deliverRemoteEvent(`http://${endpoint.host}:${endpoint.port}/__forge/event`, { from: name, event: eventName, data }, headers, target);
+                }
+                else {
+                    ctx.send(target, eventPayload);
+                }
+            }
+        };
+        await instance._init(ctx);
+        ctx._serviceInstance = instance; // for /__forge/invoke endpoint
+        localServices.set(name, { service: instance, ctx });
+    }
+    // Phase 2b: Dynamic registry discovery
+    if (workerConfig.registryMode !== RegistryMode.EMBEDDED) {
+        try {
+            const registryModule = await import("../registry/ServiceRegistry.js");
+            const ServiceRegistry = registryModule.ServiceRegistry;
+            const workerRegistry = new ServiceRegistry({
+                mode: REGISTRY_MODES.includes(workerConfig.registryMode)
+                    ? workerConfig.registryMode
+                    : RegistryMode.EMBEDDED,
+                host: workerConfig.registryHost || undefined,
+            });
+            workerRegistry.on("discovered", (reg) => {
+                if (reg.ports?.http) {
+                    endpointResolver.set(reg.name, {
+                        host: reg.host,
+                        port: reg.ports.http,
+                        remote: true,
+                    });
+                }
+            });
+            workerRegistry.on("removed", (reg) => {
+                if (reg.ports?.http) {
+                    endpointResolver.remove(reg.name, reg.host, reg.ports.http);
+                }
+            });
+            await workerRegistry.start();
+        }
+        catch (err) {
+            // Don't crash on registry errors — static endpoints still work
+            console.error(`[ThreadForge] Worker registry init failed: ${err.message}`);
+        }
+    }
+    // Phase 3: Build and inject proxy clients
+    // A2: Delegate all proxy creation to ServiceProxy — no inline retry/circuit-breaker reimplementation
+    const _servicePorts = JSON.parse(workerConfig.servicePorts || "{}");
+    const serviceRpcMap = JSON.parse(workerConfig.serviceRpc || "{}");
+    for (const [name, { service }] of localServices) {
+        const ctx = localServices.get(name).ctx;
+        const rpcConfig = serviceRpcMap[name] ?? {};
+        const proxies = buildServiceProxies(ctx, serviceClasses, localServices, { rpcConfig });
+        for (const svcName of allConnectedServices) {
+            if (svcName === name)
+                continue;
+            if (proxies[svcName])
+                continue;
+            // Service not in serviceClasses (remote/external) — resolve per-target RPC options
+            const targetOpts = resolveRpcOptionsForTarget(rpcConfig, svcName);
+            proxies[svcName] = createServiceProxy(ctx, svcName, null, null, targetOpts);
+        }
+        service._setProxies(proxies);
+    }
+    // Phase 3b: Validate that contract references match declared connections (DX-M2)
+    // Detect when a service's contract references other services not in its connects array
+    // Build a map of all emitted events: eventName -> emitting service name
+    const emittedEvents = new Map();
+    for (const [name, { ServiceClass }] of loaded) {
+        const contract = getContract(ServiceClass);
+        if (!contract)
+            continue;
+        for (const [, eventName] of contract.events) {
+            emittedEvents.set(eventName, name);
+        }
+    }
+    for (const [name, { ServiceClass }] of loaded) {
+        const contract = getContract(ServiceClass);
+        if (!contract)
+            continue;
+        // Build the set of services this service is connected to via channels
+        const connectedTo = new Set();
+        for (const ch of declaredChannels) {
+            if (ch.from === name)
+                connectedTo.add(ch.to);
+            if (ch.to === name)
+                connectedTo.add(ch.from);
+        }
+        // Check @On / static contract.on subscriptions reference connected services
+        if (contract.subscriptions) {
+            for (const sub of contract.subscriptions) {
+                if (!connectedTo.has(sub.service)) {
+                    throw new Error(`Service "${name}" subscribes to event "${sub.event}" from "${sub.service}" ` +
+                        `(handler: ${sub.handlerName}), but "${sub.service}" is not in its connects array. ` +
+                        `Add connects: ['${sub.service}'] to the "${name}" service config.`);
+                }
+            }
+        }
+        // Check that subscription targets reference services that actually emit the subscribed event
+        if (contract.subscriptions) {
+            for (const sub of contract.subscriptions) {
+                const emitter = emittedEvents.get(sub.event);
+                if (emitter && emitter !== sub.service) {
+                    console.warn(`[ThreadForge] Warning: Service "${name}" subscribes to event "${sub.event}" from "${sub.service}", ` +
+                        `but that event is emitted by "${emitter}". Check the service name in your @On decorator.`);
+                }
+            }
+        }
+    }
+    // Phase 4: Connect plugins and inject into services
+    let pluginManager = null;
+    try {
+        const pluginNames = JSON.parse(workerConfig.plugins || "[]");
+        const servicePluginMap = JSON.parse(workerConfig.servicePlugins || "{}");
+        if (pluginNames.length > 0) {
+            const { PluginManager } = (await import("../plugins/PluginManager.js"));
+            pluginManager = new PluginManager();
+            if (workerConfig.configPath) {
+                const configMod = (await import(workerConfig.configPath));
+                const config = (configMod.default ?? configMod);
+                if (config.plugins) {
+                    let plugins = config.plugins;
+                    if (hostMeta) {
+                        const scopedPostgresModule = await import("../plugins/ScopedPostgres.js");
+                        const scopedPostgres = scopedPostgresModule.scopedPostgres;
+                        const scopedRedisModule = await import("../plugins/ScopedRedis.js");
+                        const scopedRedis = scopedRedisModule.scopedRedis;
+                        plugins = plugins.map((p) => {
+                            if (p.name === "postgres")
+                                return scopedPostgres(p._options ?? {});
+                            if (p.name === "redis")
+                                return scopedRedis(p._options ?? {});
+                            return p;
+                        });
+                    }
+                    pluginManager.register(plugins);
+                }
+            }
+            // P14: Connect plugins for all services in parallel
+            const pluginEntries = [...localServices.entries()];
+            const pluginResults = await Promise.all(pluginEntries.map(async ([svcName, { service, ctx }]) => {
+                const svcPlugins = servicePluginMap[svcName];
+                const clients = await pluginManager.connectForService(svcPlugins, ctx);
+                return { svcName, service, ctx, clients, svcPlugins };
+            }));
+            for (const { service, ctx, clients, svcPlugins } of pluginResults) {
+                // Inject clients as properties on the service
+                for (const [injectName, client] of clients) {
+                    if (injectName.startsWith("_"))
+                        continue; // skip internal plugins (cors, etc.)
+                    service[injectName] = client;
+                }
+                // Apply plugin middleware
+                const middleware = pluginManager.getMiddleware(svcPlugins);
+                for (const mw of middleware) {
+                    ctx.router.use(mw);
+                }
+                // Attach websocket lifecycle hooks for this service
+                ctx._wsPluginHooks = pluginManager.getWebSocketHooks(svcPlugins);
+            }
+        }
+    }
+    catch (err) {
+        // Don't crash on plugin errors — log and continue
+        console.error(`[ThreadForge] Plugin init failed for ${workerConfig.groupName}: ${err.message}`);
+        if (err.stack)
+            console.error(err.stack);
+        for (const [, { ctx }] of localServices) {
+            try {
+                ctx?.logger?.error(`Plugin init failed: ${err.message}`);
+            }
+            catch {
+                // Swallow logging errors
+            }
+        }
+    }
+    // O4: Correct shutdown order — stop accepting connections first, then drain, then stop services, then disconnect plugins
+    // RT-C1: shutdown is a function declaration (hoisted) to avoid TDZ when called from IPC handler
+    // RT-C2: re-entrancy guard prevents double shutdown from SIGTERM + IPC race
+    async function shutdown(signal) {
+        if (shutdownInProgress)
+            return;
+        shutdownInProgress = true;
+        for (const [name, { ctx }] of localServices) {
+            ctx.logger.info(`Received ${signal}, shutting down ${name}...`);
+        }
+        // Step 1: Stop accepting new connections (server.close())
+        const serverClosePromises = [];
+        for (const [, { ctx }] of localServices) {
+            if (ctx._server) {
+                serverClosePromises.push(new Promise((resolve) => {
+                    ctx._server.close(() => resolve());
+                }));
+            }
+        }
+        // Step 2: Wait for in-flight requests to drain (up to 5s)
+        if (serverClosePromises.length > 0) {
+            await Promise.race([Promise.all(serverClosePromises), new Promise((resolve) => setTimeout(resolve, 5000))]);
+        }
+        // Step 3: Stop services (onStop hooks, with 5s timeout per service)
+        for (const [name, { service, ctx }] of localServices) {
+            try {
+                await Promise.race([
+                    service._stop(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`Service "${name}" stop timed out after 5s`)), 5000)),
+                ]);
+            }
+            catch (err) {
+                ctx.logger.error("Shutdown error", { error: err.message });
+            }
+        }
+        // Step 4: Disconnect all plugins
+        if (pluginManager) {
+            try {
+                const errors = await pluginManager.disconnectAll(localServices.values().next().value?.ctx?.logger);
+                if (errors.length > 0) {
+                    console.warn(`[ThreadForge] ${errors.length} plugins failed to disconnect cleanly`);
+                }
+            }
+            catch (err) {
+                console.warn(`[ThreadForge] Plugin disconnect error: ${err.message}`);
+            }
+        }
+        // SUP-H4: Remove IPC message handler during shutdown to prevent
+        // messages from reaching partially torn-down contexts.
+        process.removeListener("message", ipcMessageHandler);
+        // F-3: Allow event loop to drain naturally instead of process.exit(0)
+        // so plugin disconnect and I/O flushes complete. The supervisor manages
+        // worker lifecycle via cluster 'exit' events.
+        if (process.connected && process.disconnect)
+            process.disconnect();
+    }
+    // Wire IPC before starting so no messages are lost during startup
+    // SUP-H4: Store handler reference for removal during shutdown
+    const ipcMessageHandler = (msg, _handle) => {
+        if (typeof msg !== "object" || msg === null || !msg.type)
+            return;
+        const ipcMsg = msg;
+        if (ipcMsg.type === "forge:shutdown") {
+            // Stop accepting new requests, let in-flight complete
+            shutdown("forge:shutdown");
+            return;
+        }
+        // IPC-C3: Socket messages handled only by WorkerChannelManager — skip here to avoid duplicates
+        if (ipcMsg.type === "forge:init-socket" || ipcMsg.type === "forge:socket-registry")
+            return;
+        // REG-H1: Apply topology updates pushed from Supervisor
+        if (ipcMsg.type === "forge:endpoint-update") {
+            const endpoints = ipcMsg.endpoints;
+            if (endpoints && typeof endpoints === "object") {
+                endpointResolver.applyEndpointUpdate(endpoints);
+            }
+            return;
+        }
+        // REG-H2: Apply health status updates pushed from Supervisor
+        if (ipcMsg.type === "forge:health-update") {
+            const { host, port, status } = ipcMsg;
+            if (typeof host === "string" && typeof port === "number" && typeof status === "string") {
+                endpointResolver.setHealthStatus(host, port, status);
+            }
+            return;
+        }
+        if (ipcMsg.type === "forge:health-check") {
+            for (const [, { ctx }] of localServices) {
+                ctx._handleIPCMessage(ipcMsg);
+            }
+            return;
+        }
+        if (ipcMsg.type === "forge:metrics-snapshot") {
+            if (!process.send)
+                return;
+            try {
+                const chunks = [];
+                for (const [, { ctx }] of localServices) {
+                    if (ctx?.metrics?.expose) {
+                        chunks.push(ctx.metrics.expose());
+                    }
+                }
+                process.send({
+                    type: "forge:metrics-snapshot-response",
+                    requestId: ipcMsg.requestId,
+                    metrics: chunks.join("\n"),
+                });
+            }
+            catch (err) {
+                process.send({
+                    type: "forge:metrics-snapshot-response",
+                    requestId: ipcMsg.requestId,
+                    error: err.message,
+                });
+            }
+            return;
+        }
+        if (ipcMsg.type === "forge:message" || ipcMsg.type === "forge:request" || ipcMsg.type === "forge:response") {
+            for (const [, { ctx }] of localServices) {
+                ctx._handleIPCMessage(ipcMsg);
+            }
+        }
+    };
+    process.on("message", ipcMessageHandler);
+    // Request socket setup (supervisor may have sent init-socket before we were listening)
+    if (process.send) {
+        process.send({ type: "forge:worker-ready", group: workerConfig.groupName });
+    }
+    // Phase 5: Start all services — track started services for cleanup on failure (RT-H1)
+    const startedServices = [];
+    try {
+        for (const [name, { service, ctx }] of localServices) {
+            // DEC-M2: Apply deferred validation wrappers at startup, not during contract inspection
+            const entry = loaded.get(name);
+            if (entry)
+                applyStaticContractWrappers(entry.ServiceClass);
+            await service._start();
+            startedServices.push({ name, service, ctx });
+            const proxyNames = Object.keys(Object.fromEntries(Object.entries(service).filter(([_k, v]) => v?.$name ||
+                v?.$isLocal !== undefined)));
+            // Reduce startup noise: emit framework startup metadata once per group.
+            if (workerId === 0) {
+                ctx.logger.info("Service started", {
+                    group: workerConfig.groupName,
+                    service: name,
+                    type: typeMap[name] ?? ServiceType.INTERNAL,
+                    port: ctx.port || null,
+                    worker: workerId,
+                    pid: process.pid,
+                    colocated: entries.length > 1 ? entries.map((e) => e.name) : undefined,
+                    proxies: proxyNames.length > 0 ? proxyNames : undefined,
+                });
+            }
+        }
+    }
+    catch (startErr) {
+        const typedStartErr = startErr;
+        // Check if this is a fatal bind error (EPERM, EACCES, EADDRNOTAVAIL, EADDRINUSE)
+        if (typedStartErr.fatalBindError) {
+            // Log clear error message and exit without triggering restart loop
+            console.error(`\n[ThreadForge] FATAL: ${typedStartErr.userMessage || typedStartErr.message}`);
+            console.error(`[ThreadForge] Service group "${workerConfig.groupName}" cannot start. Worker will not restart.\n`);
+            // Notify supervisor this is a fatal error (already sent via IPC from ForgeContext)
+            // Exit with code 100 to signal fatal configuration error (supervisor checks this)
+            process.exit(100);
+        }
+        // RT-H1: Stop already-started services in reverse order before re-throwing
+        for (let i = startedServices.length - 1; i >= 0; i--) {
+            const { name, service, ctx } = startedServices[i];
+            try {
+                ctx.logger.warn(`Rolling back service start for ${name} due to Phase 5 failure`);
+                await service._stop();
+            }
+            catch (stopErr) {
+                ctx.logger.error(`Rollback stop failed for ${name}`, { error: stopErr.message });
+            }
+            try {
+                if (ctx._server) {
+                    await new Promise((resolve) => ctx._server.close(() => resolve()));
+                }
+            }
+            catch {
+                // Swallow server close errors during rollback
+            }
+        }
+        throw typedStartErr;
+    }
+    // Phase 6: Auto-register health check (always, not just with plugins)
+    for (const [, { ctx }] of localServices) {
+        const existingHealthRoute = [...ctx.router.routes.values()].some((bucket) => bucket.some((r) => r.pattern === "/health"));
+        if (!existingHealthRoute) {
+            ctx.router.get("/health", (async (_req, res) => {
+                const health = {
+                    status: "ok",
+                    service: ctx.serviceName,
+                    pid: process.pid,
+                };
+                if (pluginManager) {
+                    health.plugins = await pluginManager.healthCheck();
+                }
+                res.json(health);
+            }));
+        }
+    }
+    // Notify supervisor that this worker finished startup for readiness aggregation.
+    if (process.send) {
+        process.send({
+            type: "forge:group-ready",
+            group: workerConfig.groupName,
+            workerId,
+            pid: process.pid,
+            services: entries.map((e) => e.name),
+            port: Number.isFinite(port) && port > 0 ? port : null,
+            ipcVersion: IPC_PROTOCOL_VERSION,
+        });
+    }
+    // Signal handlers moved to early in bootstrap() — see below uncaughtException handler
+}
+bootstrap().catch((err) => {
+    const services = workerConfig.serviceNames || "unknown";
+    console.error(`[ThreadForge] Worker bootstrap failed for group "${workerConfig.groupName}" (services: ${services}):`, err);
+    process.exit(1);
+});
+//# sourceMappingURL=worker-bootstrap.js.map