@tulipes/core 0.1.0

package/dist/acl/acl.d.ts

@@ -0,0 +1,49 @@
+import { BootReport } from "../errors/boot-error.js";
+/**
+ * Global ACL registry.
+ *
+ * Roles are app-global (the sys core module defines them); every other
+ * module attaches permission grants to existing roles for its own resources.
+ * Resources are namespaced strings — `users:write`, `categories:read`,
+ * `users:*` — where the prefix is, by convention, the owning module.
+ *
+ * Every mutation happens through a per-module `AclBuilder` so each role
+ * definition and grant records who made it: that is what lets a conflict
+ * crash the boot with both module names in the message.
+ */
+export declare class Acl {
+    #private;
+    forModule(moduleName: string, report: BootReport): AclBuilder;
+    /**
+     * Runtime permission check. Unknown roles simply deny — at request time
+     * the safe answer to "can this unheard-of role do X?" is always no.
+     */
+    can(role: string, permission: string): boolean;
+    hasRole(role: string): boolean;
+    roles(): string[];
+    /** Flat grant list — feeds logs, docs and the future postman generator. */
+    describe(): {
+        role: string;
+        resource: string;
+        grantedBy: string;
+    }[];
+    /** @internal AclBuilder only. */
+    defineRole_(role: string, moduleName: string): string | undefined;
+    /** @internal AclBuilder only. */
+    grant_(role: string, resource: string, moduleName: string): string | undefined;
+}
+/**
+ * The module-scoped facade handed to `module.acl.ts`. All validation issues
+ * flow into the boot report — collected, never thrown — so a module with
+ * three bad grants shows all three.
+ */
+export declare class AclBuilder {
+    #private;
+    constructor(acl: Acl, moduleName: string, report: BootReport);
+    /**
+     * Introducing a role is deliberately explicit — a typo in `allow()` must
+     * be an error, never a silently created role.
+     */
+    defineRole(role: string): this;
+    allow(role: string, ...resources: string[]): this;
+}

package/dist/acl/acl.js

@@ -0,0 +1,123 @@
+import { BootReport } from "../errors/boot-error.js";
+/**
+ * Global ACL registry.
+ *
+ * Roles are app-global (the sys core module defines them); every other
+ * module attaches permission grants to existing roles for its own resources.
+ * Resources are namespaced strings — `users:write`, `categories:read`,
+ * `users:*` — where the prefix is, by convention, the owning module.
+ *
+ * Every mutation happens through a per-module `AclBuilder` so each role
+ * definition and grant records who made it: that is what lets a conflict
+ * crash the boot with both module names in the message.
+ */
+export class Acl {
+    /** role → module that defined it */
+    #roles = new Map();
+    /** role → (resource → module that granted it) */
+    #grants = new Map();
+    forModule(moduleName, report) {
+        return new AclBuilder(this, moduleName, report);
+    }
+    /**
+     * Runtime permission check. Unknown roles simply deny — at request time
+     * the safe answer to "can this unheard-of role do X?" is always no.
+     */
+    can(role, permission) {
+        const grants = this.#grants.get(role);
+        if (!grants)
+            return false;
+        if (grants.has(permission) || grants.has("*"))
+            return true;
+        const namespace = permission.split(":")[0];
+        return grants.has(`${namespace}:*`);
+    }
+    hasRole(role) {
+        return this.#roles.has(role);
+    }
+    roles() {
+        return [...this.#roles.keys()];
+    }
+    /** Flat grant list — feeds logs, docs and the future postman generator. */
+    describe() {
+        return [...this.#grants.entries()].flatMap(([role, grants]) => [...grants.entries()].map(([resource, grantedBy]) => ({
+            role,
+            resource,
+            grantedBy,
+        })));
+    }
+    /** @internal AclBuilder only. */
+    defineRole_(role, moduleName) {
+        const existing = this.#roles.get(role);
+        if (existing)
+            return existing;
+        this.#roles.set(role, moduleName);
+        this.#grants.set(role, new Map());
+        return undefined;
+    }
+    /** @internal AclBuilder only. */
+    grant_(role, resource, moduleName) {
+        const grants = this.#grants.get(role);
+        if (!grants)
+            return undefined; // caller reports the unknown role
+        const existing = grants.get(resource);
+        if (existing)
+            return existing;
+        grants.set(resource, moduleName);
+        return undefined;
+    }
+}
+/** `name:action`, `name:*`, or the standalone `*`. */
+const RESOURCE = /^([a-z0-9-]+:[a-z0-9-]+|[a-z0-9-]+:\*|\*)$/;
+const ROLE = /^[a-z][a-z0-9-]*$/;
+/**
+ * The module-scoped facade handed to `module.acl.ts`. All validation issues
+ * flow into the boot report — collected, never thrown — so a module with
+ * three bad grants shows all three.
+ */
+export class AclBuilder {
+    #acl;
+    #module;
+    #report;
+    constructor(acl, moduleName, report) {
+        this.#acl = acl;
+        this.#module = moduleName;
+        this.#report = report;
+    }
+    /**
+     * Introducing a role is deliberately explicit — a typo in `allow()` must
+     * be an error, never a silently created role.
+     */
+    defineRole(role) {
+        if (!ROLE.test(role)) {
+            this.#issue(`role "${role}" is invalid — lowercase kebab-case required`);
+            return this;
+        }
+        const definedBy = this.#acl.defineRole_(role, this.#module);
+        if (definedBy) {
+            this.#issue(`role "${role}" is already defined by module "${definedBy}"`);
+        }
+        return this;
+    }
+    allow(role, ...resources) {
+        if (!this.#acl.hasRole(role)) {
+            this.#issue(`allow() on unknown role "${role}" — roles must be defined first (defineRole)`);
+            return this;
+        }
+        for (const resource of resources) {
+            if (!RESOURCE.test(resource)) {
+                this.#issue(`resource "${resource}" is invalid — expected "name:action", "name:*" or "*"`);
+                continue;
+            }
+            const grantedBy = this.#acl.grant_(role, resource, this.#module);
+            if (grantedBy) {
+                this.#issue(`"${role}" already granted "${resource}" by module "${grantedBy}" — duplicate grant`);
+            }
+        }
+        return this;
+    }
+    #issue(message) {
+        this.#report.add({ scope: "acl", module: this.#module, message });
+    }
+}
+//# sourceMappingURL=acl.js.map

package/dist/acl/acl.js.map

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

package/dist/acl/index.d.ts

@@ -0,0 +1,2 @@
+export { Acl, AclBuilder } from "./acl.js";
+export { loadAcl, type AclFn } from "./load-acl.js";

package/dist/acl/index.js

@@ -0,0 +1,3 @@
+export { Acl, AclBuilder } from "./acl.js";
+export { loadAcl } from "./load-acl.js";
+//# sourceMappingURL=index.js.map

package/dist/acl/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/acl/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAc,MAAM,eAAe,CAAC"}

package/dist/acl/load-acl.d.ts

@@ -0,0 +1,11 @@
+import { BootReport } from "../errors/boot-error.js";
+import type { ModuleFiles } from "../modules/explorer.js";
+import { Acl, type AclBuilder } from "./acl.js";
+/** Default export of `module.acl.ts`. */
+export type AclFn = (acl: AclBuilder) => void | Promise<void>;
+/**
+ * Boot phase 7: run every `module.acl.ts` in load order against the shared
+ * registry. Load order is what makes "define roles in the sys core module,
+ * grant everywhere else" work without further ceremony: sys runs first.
+ */
+export declare function loadAcl(explored: readonly ModuleFiles[], report: BootReport): Promise<Acl>;

package/dist/acl/load-acl.js

@@ -0,0 +1,38 @@
+import { BootReport } from "../errors/boot-error.js";
+import { importFile } from "../boot/import-file.js";
+import { Acl } from "./acl.js";
+/**
+ * Boot phase 7: run every `module.acl.ts` in load order against the shared
+ * registry. Load order is what makes "define roles in the sys core module,
+ * grant everywhere else" work without further ceremony: sys runs first.
+ */
+export async function loadAcl(explored, report) {
+    const acl = new Acl();
+    for (const { module, aclFile } of explored) {
+        if (!aclFile)
+            continue;
+        const exported = await importFile(aclFile, "acl", module.name, report);
+        if (!exported)
+            continue;
+        if (typeof exported.default !== "function") {
+            report.add({
+                scope: "acl",
+                module: module.name,
+                message: "module.acl must default-export a function (acl) => void",
+            });
+            continue;
+        }
+        try {
+            await exported.default(acl.forModule(module.name, report));
+        }
+        catch (error) {
+            report.add({
+                scope: "acl",
+                module: module.name,
+                message: `acl function threw: ${error.message}`,
+            });
+        }
+    }
+    return acl;
+}
+//# sourceMappingURL=load-acl.js.map

package/dist/acl/load-acl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-acl.js","sourceRoot":"","sources":["../../src/acl/load-acl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAE,GAAG,EAAmB,MAAM,UAAU,CAAC;AAKhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,QAAgC,EAChC,MAAkB;IAElB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;IAEtB,KAAK,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC3C,IAAI,CAAC,OAAO;YAAE,SAAS;QAEvB,MAAM,QAAQ,GAAG,MAAM,UAAU,CAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CACpC,CAAC;QACF,IAAI,CAAC,QAAQ;YAAE,SAAS;QAExB,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YAC3C,MAAM,CAAC,GAAG,CAAC;gBACT,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,MAAM,CAAC,IAAI;gBACnB,OAAO,EAAE,yDAAyD;aACnE,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,IAAI,CAAC;YACH,MAAO,QAAQ,CAAC,OAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,GAAG,CAAC;gBACT,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,MAAM,CAAC,IAAI;gBACnB,OAAO,EAAE,uBAAwB,KAAe,CAAC,OAAO,EAAE;aAC3D,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/boot/app-files.d.ts

@@ -0,0 +1,17 @@
+import { BootReport } from "../errors/boot-error.js";
+import type { Ctx } from "./contracts.js";
+/**
+ * The one app-level (non-module) convention file. Optional — an app that
+ * doesn't need it simply doesn't create it.
+ *
+ *   config/app.config.ts   default-exports (Environment) => object; the
+ *                          result seeds the global config BEFORE any module
+ *                          factory runs. The place for app-wide values that
+ *                          belong to no single module.
+ *
+ * There is deliberately no app-level middleware file: global middleware is
+ * a sys module's job — sys modules load before everything, so their routes
+ * files mounting on ctx.app IS the "before all routes" slot.
+ */
+export type AppConfigFn = (environment: Ctx["Environment"]) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
+export declare function loadAppConfigSeed(rootDir: string, ctx: Ctx, report: BootReport): Promise<void>;

package/dist/boot/app-files.js

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { BootReport } from "../errors/boot-error.js";
+import { detectSourceExtension } from "../modules/explorer.js";
+import { importFile } from "./import-file.js";
+export async function loadAppConfigSeed(rootDir, ctx, report) {
+    const file = join(rootDir, "config", `app.config${detectSourceExtension()}`);
+    if (!existsSync(file))
+        return;
+    const exported = await importFile(file, "config", "app", report);
+    if (!exported)
+        return;
+    if (typeof exported.default !== "function") {
+        report.add({
+            scope: "config",
+            message: "config/app.config must default-export a function (Environment) => object",
+        });
+        return;
+    }
+    try {
+        const seed = await exported.default(ctx.Environment);
+        Object.assign(ctx.config, seed ?? {});
+    }
+    catch (error) {
+        report.add({
+            scope: "config",
+            message: `app.config threw: ${error.message}`,
+        });
+    }
+}
+//# sourceMappingURL=app-files.js.map

package/dist/boot/app-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-files.js","sourceRoot":"","sources":["../../src/boot/app-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAqB9C,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAe,EACf,GAAQ,EACR,MAAkB;IAElB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,qBAAqB,EAAE,EAAE,CAAC,CAAC;IAC7E,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAE9B,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAwB,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACxF,IAAI,CAAC,QAAQ;QAAE,OAAO;IAEtB,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,CAAC;YACT,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,0EAA0E;SACpF,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAO,QAAQ,CAAC,OAAuB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACtE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,GAAG,CAAC;YACT,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,qBAAsB,KAAe,CAAC,OAAO,EAAE;SACzD,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/boot/banner.d.ts

@@ -0,0 +1,9 @@
+import type { BootHandle } from "./boot.js";
+import type { ModuleManifest } from "../modules/manifest.js";
+/**
+ * The end-of-boot banner: one glance answers every "is it actually up?"
+ * question — where the server listens, database state, queues, sockets,
+ * modules, roles, runtime. Colorette strips ANSI when stdout isn't a TTY,
+ * so piped/production logs stay clean text.
+ */
+export declare function printStartupBanner(handle: BootHandle, modules: readonly ModuleManifest[], bootMs: number): void;

package/dist/boot/banner.js

@@ -0,0 +1,82 @@
+import { bold, cyan, cyanBright, dim, gray, green, greenBright, magenta, red, } from "colorette";
+/**
+ * The end-of-boot banner: one glance answers every "is it actually up?"
+ * question — where the server listens, database state, queues, sockets,
+ * modules, roles, runtime. Colorette strips ANSI when stdout isn't a TTY,
+ * so piped/production logs stay clean text.
+ */
+export function printStartupBanner(handle, modules, bootMs) {
+    const { env, ctx, mode } = handle;
+    const ec = envColor(env.appEnv);
+    const appName = String(ctx.config.app?.name ?? "tulipes");
+    const rows = [];
+    if (handle.server) {
+        const address = handle.server.address();
+        const port = typeof address === "object" && address ? address.port : "?";
+        rows.push([
+            "Server",
+            `${cyan(`http://localhost:${port}`)}  ${dot(true)} ${green("listening")}`,
+        ]);
+    }
+    else {
+        const workers = ctx.queues?.workerCount ?? 0;
+        rows.push([
+            "Worker",
+            `${dot(workers > 0)} ${green(`consuming ${workers} queue(s)`)}`,
+        ]);
+    }
+    if (handle.connection) {
+        const { host, port, name, readyState } = handle.connection;
+        const connected = readyState === 1;
+        rows.push([
+            "Database",
+            `${cyan(`mongodb://${host}:${port}/${name}`)}  ${dot(connected)} ${connected ? green("connected") : red("disconnected")}`,
+        ]);
+    }
+    else {
+        rows.push(["Database", gray("not configured")]);
+    }
+    if (ctx.queues) {
+        const names = ctx.queues.names();
+        rows.push([
+            "Queues",
+            `${bold(String(names.length))} ${gray(`(${names.join(", ")})`)}  ${dim("·")}  ${gray(`${ctx.queues.processorCount} processor(s) registered`)}`,
+        ]);
+    }
+    if (ctx.sockets) {
+        rows.push(["Sockets", cyan(ctx.sockets.namespaces().join(", ") || "—")]);
+    }
+    rows.push([
+        "Modules",
+        `${bold(String(modules.length))} ${gray(`(${modules.map((m) => (m.tier === "sys" ? `${m.name}*` : m.name)).join(", ")})`)}  ${dim("·")}  ${gray("* sys tier")}`,
+    ]);
+    if (ctx.acl) {
+        const roles = ctx.acl.roles();
+        rows.push(["Roles", `${bold(String(roles.length))} ${gray(`(${roles.join(", ")})`)}`]);
+    }
+    rows.push([
+        "Runtime",
+        `${gray(`Node ${process.version}`)}  ${dim("·")}  ${gray(`PID ${process.pid}`)}  ${dim("·")}  ${gray(`ready in ${bootMs}ms`)}`,
+    ]);
+    const labelWidth = Math.max(...rows.map(([label]) => label.length));
+    const arrow = green("➜");
+    const lines = [
+        "",
+        `  ${bold(cyan(`▲ ${appName}`))}  ${ec(bold(env.appEnv))} ${dim("·")} ${dim(`${mode} mode`)}`,
+        "",
+        ...rows.map(([label, value]) => `  ${arrow}  ${bold(label.padEnd(labelWidth))}   ${value}`),
+        "",
+    ];
+    console.log(lines.join("\n"));
+}
+function envColor(env) {
+    if (env === "production")
+        return greenBright;
+    if (env === "test")
+        return magenta;
+    return cyanBright;
+}
+function dot(ok) {
+    return ok ? green("●") : red("●");
+}
+//# sourceMappingURL=banner.js.map

package/dist/boot/banner.js.map

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

package/dist/boot/boot.d.ts

@@ -0,0 +1,32 @@
+import { type Server } from "node:http";
+import type { Connection } from "mongoose";
+import { type Express } from "express";
+import { Environment, type AppEnv } from "../env/environment.js";
+import type { Ctx } from "./contracts.js";
+export declare const processModes: readonly ["web", "worker"];
+export type ProcessMode = (typeof processModes)[number];
+export interface BootOptions {
+    /** App root — the directory containing `modules/` and `.envs/`. */
+    rootDir: string;
+    /** Defaults to process.env.PROCESS_MODE, then "web". */
+    mode?: ProcessMode;
+    appEnv?: AppEnv;
+    /** Skip SIGTERM/SIGINT wiring — for tests that manage shutdown themselves. */
+    handleSignals?: boolean;
+}
+export interface BootHandle {
+    mode: ProcessMode;
+    env: Environment;
+    ctx: Ctx;
+    connection?: Connection;
+    app?: Express;
+    server?: Server;
+    shutdown: () => Promise<void>;
+}
+/**
+ * The whole run workflow, in the order the POC pins down:
+ * environment → module graph → exploration → global config → (acl, db —
+ * future steps) → mode fork (web | worker) → onReady. Each phase crashes
+ * with its aggregate report before the next begins.
+ */
+export declare function boot(options: BootOptions): Promise<BootHandle>;

package/dist/boot/boot.js

@@ -0,0 +1,212 @@
+import { createServer } from "node:http";
+import { join } from "node:path";
+import express, {} from "express";
+import { Environment } from "../env/environment.js";
+import { BootReport } from "../errors/boot-error.js";
+import { discoverModules } from "../modules/discovery.js";
+import { sortModules } from "../modules/graph.js";
+import { exploreModules } from "../modules/explorer.js";
+import { buildGlobalConfig } from "../config/build-config.js";
+import { loadAcl } from "../acl/load-acl.js";
+import { initDatabase } from "../db/database.js";
+import { initQueues } from "../queues/load-queues.js";
+import { initSockets } from "../sockets/load-sockets.js";
+import { errorHandler, notFoundHandler } from "../http/error-handler.js";
+import { loadAppConfigSeed } from "./app-files.js";
+import { printStartupBanner } from "./banner.js";
+import { importFile } from "./import-file.js";
+export const processModes = ["web", "worker"];
+/**
+ * The whole run workflow, in the order the POC pins down:
+ * environment → module graph → exploration → global config → (acl, db —
+ * future steps) → mode fork (web | worker) → onReady. Each phase crashes
+ * with its aggregate report before the next begins.
+ */
+export async function boot(options) {
+    const bootStartedAt = Date.now();
+    const mode = resolveMode(options.mode);
+    // Phases 1–3 — Environment engine (crashes internally on bad env)
+    const env = Environment.load({
+        rootDir: options.rootDir,
+        ...(options.appEnv && { appEnv: options.appEnv }),
+    });
+    // Phase 4 — module graph
+    const graphReport = new BootReport();
+    const manifests = discoverModules(join(options.rootDir, "modules"), graphReport);
+    const order = sortModules(manifests, graphReport);
+    graphReport.throwIfAny("module graph");
+    // Phase 5 — exploration (no failure modes)
+    const explored = exploreModules(order);
+    // Phase 6 — global config: app-level seed first, then module factories
+    const ctx = { Environment: env, config: {} };
+    const configReport = new BootReport();
+    await loadAppConfigSeed(options.rootDir, ctx, configReport);
+    const lifecycles = await buildGlobalConfig(explored, ctx, configReport);
+    configReport.throwIfAny("config");
+    // Phase 7 — ACL merge
+    const aclReport = new BootReport();
+    ctx.acl = await loadAcl(explored, aclReport);
+    aclReport.throwIfAny("acl");
+    // Phase 8 — DB + models + bootstrap
+    const dbReport = new BootReport();
+    const connection = await initDatabase(explored, ctx, dbReport);
+    dbReport.throwIfAny("database");
+    // Phase 9 — mode fork
+    const handle = {
+        mode,
+        env,
+        ctx,
+        connection,
+        shutdown: () => shutdown(handle, lifecycles),
+    };
+    // Phase 9 — queues register in both modes (producers everywhere; the
+    // worker branch additionally starts consuming below).
+    const queueReport = new BootReport();
+    await initQueues(explored, ctx, queueReport);
+    queueReport.throwIfAny("queues");
+    if (mode === "web") {
+        await startWeb(handle, explored);
+    }
+    else {
+        const workerReport = new BootReport();
+        const started = ctx.queues?.startWorkers(workerReport) ?? 0;
+        workerReport.throwIfAny("workers");
+        // BullMQ workers hold the event loop open; a worker with nothing to
+        // consume is a misconfigured deployment, not a valid idle state.
+        if (started === 0) {
+            throw new Error("worker mode started with zero processors — no module registered queue work");
+        }
+    }
+    // Phase 12 — onReady, load order
+    for (const { module, onReady } of lifecycles) {
+        try {
+            await onReady?.(ctx);
+        }
+        catch (error) {
+            // Late-phase hook failures must still take the process down cleanly:
+            // a half-ready app serving traffic is worse than no app.
+            await handle.shutdown();
+            throw new Error(`onReady hook of "${module}" failed: ${error.message}`);
+        }
+    }
+    printStartupBanner(handle, order, Date.now() - bootStartedAt);
+    if (options.handleSignals !== false) {
+        for (const signal of ["SIGINT", "SIGTERM"]) {
+            process.once(signal, () => {
+                console.log(`\n[tulipes] ${signal} — shutting down`);
+                handle.shutdown().then(() => process.exit(0), (error) => {
+                    console.error("[tulipes] shutdown failed:", error);
+                    process.exit(1);
+                });
+            });
+        }
+    }
+    return handle;
+}
+function resolveMode(override) {
+    const raw = override ?? process.env.PROCESS_MODE ?? "web";
+    if (!processModes.includes(raw)) {
+        throw new Error(`PROCESS_MODE "${raw}" is invalid — expected one of: ${processModes.join(", ")}`);
+    }
+    return raw;
+}
+/**
+ * Phases 9w–11w: express, module routes, http server.
+ *
+ * The request pipeline, in order:
+ *   1. every module router      (load order — sys modules first, so their
+ *                                routes files mounting on ctx.app ARE the
+ *                                global middleware slot: request ids and
+ *                                cross-cutting glue in the core module,
+ *                                headers/logging/body parsing in security)
+ *   2. notFoundHandler          (core)
+ *   3. errorHandler             (core — terminal, catches async throws too)
+ *
+ * Core deliberately mounts NO middleware of its own: what runs on every
+ * request is the app's decision, expressed as sys modules within the
+ * developer's reach. Core only guarantees the fail-closed tail — nothing
+ * escapes unrouted or unhandled. @tulipes/core/http ships only that tail's
+ * building blocks (HttpError, notFoundHandler, errorHandler).
+ */
+async function startWeb(handle, explored) {
+    const app = express();
+    handle.app = app;
+    handle.ctx.app = app;
+    const report = new BootReport();
+    for (const { module, routeFiles } of explored) {
+        for (const file of routeFiles) {
+            const exported = await importFile(file, "boot", module.name, report);
+            if (!exported)
+                continue;
+            if (typeof exported.default !== "function") {
+                report.add({
+                    scope: "boot",
+                    module: module.name,
+                    message: `${file} must default-export a routes function`,
+                });
+                continue;
+            }
+            try {
+                const router = await exported.default(handle.ctx);
+                // Mounting the return value is optional sugar — a routes fn may
+                // have attached handlers to ctx.app directly instead. Routers are
+                // callables in express, so a function return is a mountable.
+                if (typeof router === "function")
+                    app.use(router);
+            }
+            catch (error) {
+                report.add({
+                    scope: "boot",
+                    module: module.name,
+                    message: `routes function threw: ${error.message}`,
+                });
+            }
+        }
+    }
+    app.use(notFoundHandler());
+    app.use(errorHandler(handle.env.appEnv));
+    report.throwIfAny("routes");
+    const port = handle.env.store.has("PORT")
+        ? Number(handle.env.get("PORT"))
+        : 3000;
+    const server = createServer(app);
+    handle.server = server;
+    // Phase 11w — sockets attach before listen() so no client can connect
+    // to a namespace that isn't wired yet.
+    const socketReport = new BootReport();
+    await initSockets(explored, handle.ctx, server, socketReport);
+    socketReport.throwIfAny("sockets");
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, () => resolve());
+    });
+}
+/** Reverse load order, every hook attempted even if an earlier one throws. */
+async function shutdown(handle, lifecycles) {
+    const failures = [];
+    for (const { module, onShutdown } of [...lifecycles].reverse()) {
+        try {
+            await onShutdown?.(handle.ctx);
+        }
+        catch (error) {
+            failures.push(`${module}: ${error.message}`);
+        }
+    }
+    // Kick socket clients first so the http server's close() isn't held open
+    // by long-lived websocket connections.
+    handle.ctx.sockets?.close();
+    if (handle.server?.listening) {
+        await new Promise((resolve, reject) => {
+            handle.server.close((error) => (error ? reject(error) : resolve()));
+        });
+    }
+    // Queues drain after http stops (no new producers), workers finish their
+    // in-flight jobs inside close(). DB goes down last — hooks, requests and
+    // jobs may all need it right up to this point.
+    await handle.ctx.queues?.close();
+    await handle.connection?.close();
+    if (failures.length > 0) {
+        throw new Error(`onShutdown hook(s) failed — ${failures.join("; ")}`);
+    }
+}
+//# sourceMappingURL=boot.js.map