@fastrack/core 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,48 @@
+# @fastrack/core
+
+Application bootstrap, starter loading, config aggregation and validation, standard error model, request context and correlation IDs, graceful shutdown and readiness toggle.
+
+See [docs/architecture.md](../../docs/architecture.md) and the design document for the full platform vision.
+
+## Install
+
+```bash
+pnpm add @fastrack/core
+```
+
+## Usage
+
+```ts
+import { createApp } from "@fastrack/core";
+import { webStarter } from "@fastrack/starter-web";
+import { actuatorStarter } from "@fastrack/starter-actuator";
+
+const app = await createApp({
+  starters: [webStarter, actuatorStarter],
+});
+
+await app.listen({ port: 3000 });
+```
+
+## Env config (dotenv)
+
+By default, `createApp` loads a `.env` file from the current working directory (via [dotenv](https://www.npmjs.com/package/dotenv)), so `process.env` is populated before config is built. You can then pass config from env or use it in starters:
+
+```ts
+const app = await createApp({
+  envPath: ".env",        // default; set to false to disable
+  config: {
+    web: { port: Number(process.env.PORT) ?? 3000 },
+  },
+});
+```
+
+Set `envPath: false` to disable loading a .env file.
+
+## API
+
+- `createApp(options)` — Bootstrap Fastify with starters and config.
+- `FastrackStarter<TConfig>` — Starter interface (name, configSchema, register).
+- `FastrackContext` — Bootstrap context passed to starters.
+- Problem-details error schema and `replyError` helper.
+- Readiness getter/setter for actuator integration.

package/dist/create-app.d.ts

@@ -0,0 +1,19 @@
+import type { FastifyInstance } from "fastify";
+import type { FastrackContext, CreateAppOptions } from "./types.js";
+/**
+ * Create a Fastrack app: load env (.env via dotenv), validate starter configs, register starters, set up shutdown.
+ */
+export declare function createApp(options?: CreateAppOptions): Promise<FastifyInstance>;
+/**
+ * Get the Fastrack context from an app (for actuator / other starters).
+ */
+export declare function getFastrackContext(app: FastifyInstance): FastrackContext | undefined;
+/**
+ * Get health contributors map from app (for actuator).
+ */
+export declare function getHealthContributors(app: FastifyInstance): Map<string, () => Promise<{
+    ok: boolean;
+    status?: "up" | "down";
+    details?: Record<string, unknown>;
+}>> | undefined;
+//# sourceMappingURL=create-app.d.ts.map

package/dist/create-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-app.d.ts","sourceRoot":"","sources":["../src/create-app.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAIpE;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CA0ExF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,GAAG,SAAS,CAEpF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,eAAe,GACnB,GAAG,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC,GAAG,SAAS,CAEpH"}

package/dist/create-app.js

@@ -0,0 +1,83 @@
+import { config as dotenvConfig } from "dotenv";
+import { Value } from "@sinclair/typebox/value";
+import Fastify from "fastify";
+const DEFAULT_SHUTDOWN_MS = 30_000;
+/**
+ * Create a Fastrack app: load env (.env via dotenv), validate starter configs, register starters, set up shutdown.
+ */
+export async function createApp(options = {}) {
+    const { starters = [], config: configOverride = {}, envPath = ".env", shutdownTimeoutMs = DEFAULT_SHUTDOWN_MS, } = options;
+    if (envPath !== false) {
+        dotenvConfig({ path: envPath });
+    }
+    const app = Fastify({ logger: true });
+    let readiness = true;
+    const shutdownHooks = [];
+    const healthContributors = new Map();
+    const ctx = {
+        app,
+        config: { ...configOverride },
+        get logger() {
+            return app.log;
+        },
+        getReadiness: () => readiness,
+        setReadiness: (ready) => {
+            readiness = ready;
+        },
+        onShutdown: (fn) => {
+            shutdownHooks.push(fn);
+        },
+        registerHealthContributor: (name, check) => {
+            healthContributors.set(name, check);
+        },
+    };
+    for (const starter of starters) {
+        const defaults = starter.defaults ?? {};
+        const raw = ctx.config[starter.name] ?? {};
+        const merged = { ...defaults, ...raw };
+        const errors = [...Value.Errors(starter.configSchema, merged)];
+        if (errors.length > 0) {
+            const msg = errors.map((e) => `${e.path}: ${e.message}`).join("; ");
+            throw new Error(`Config validation failed for starter "${starter.name}": ${msg}`);
+        }
+        const result = Value.Decode(starter.configSchema, merged);
+        await Promise.resolve(starter.register(app, ctx, result));
+    }
+    const shutdown = async (signal) => {
+        readiness = false;
+        app.log?.info?.({ signal }, "Shutdown: readiness=false");
+        const timeout = setTimeout(() => {
+            app.log?.error?.("Shutdown timeout; exiting");
+            process.exit(1);
+        }, shutdownTimeoutMs);
+        try {
+            for (let i = shutdownHooks.length - 1; i >= 0; i--) {
+                const fn = shutdownHooks[i];
+                if (fn)
+                    await Promise.resolve(fn());
+            }
+            await app.close();
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    };
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    app._fastrackContext = ctx;
+    app._healthContributors = healthContributors;
+    return app;
+}
+/**
+ * Get the Fastrack context from an app (for actuator / other starters).
+ */
+export function getFastrackContext(app) {
+    return app._fastrackContext;
+}
+/**
+ * Get health contributors map from app (for actuator).
+ */
+export function getHealthContributors(app) {
+    return app._healthContributors;
+}
+//# sourceMappingURL=create-app.js.map

package/dist/create-app.js.map

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

package/dist/error.d.ts

@@ -0,0 +1,20 @@
+import type { FastifyReply } from "fastify";
+/**
+ * Problem-details error schema (design §5).
+ * Stack traces are logged server-side only; never exposed in response.
+ */
+export declare const ProblemDetailsSchema: import("@sinclair/typebox").TObject<{
+    status: import("@sinclair/typebox").TNumber;
+    code: import("@sinclair/typebox").TString;
+    message: import("@sinclair/typebox").TString;
+    correlationId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type ProblemDetails = typeof ProblemDetailsSchema.static;
+/**
+ * Reply with problem-details body. Logs stack server-side only.
+ */
+export declare function replyError(reply: FastifyReply, err: unknown, options?: {
+    status?: number;
+    correlationId?: string;
+}): void;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,OAAO,oBAAoB,CAAC,MAAM,CAAC;AAEhE;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,IAAI,CAgBN"}

package/dist/error.js

@@ -0,0 +1,30 @@
+import { Type } from "@sinclair/typebox";
+/**
+ * Problem-details error schema (design §5).
+ * Stack traces are logged server-side only; never exposed in response.
+ */
+export const ProblemDetailsSchema = Type.Object({
+    status: Type.Number({ description: "HTTP status" }),
+    code: Type.String({ description: "Error code" }),
+    message: Type.String({ description: "Human-readable message" }),
+    correlationId: Type.Optional(Type.String({ description: "Request correlation ID" })),
+});
+/**
+ * Reply with problem-details body. Logs stack server-side only.
+ */
+export function replyError(reply, err, options) {
+    const status = options?.status ?? err.statusCode ?? 500;
+    const correlationId = options?.correlationId ?? reply.request.correlationId;
+    const message = err instanceof Error ? err.message : String(err);
+    const code = err.code ?? "INTERNAL_ERROR";
+    if (err instanceof Error && err.stack) {
+        reply.log?.error?.({ err, correlationId }, "Error (stack server-side only)");
+    }
+    reply.status(status).send({
+        status,
+        code,
+        message,
+        ...(correlationId ? { correlationId } : {}),
+    });
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAGzC;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC;IACnD,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;IAChD,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,wBAAwB,EAAE,CAAC;IAC/D,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,wBAAwB,EAAE,CAAC,CAAC;CACrF,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,KAAmB,EACnB,GAAY,EACZ,OAAqD;IAErD,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAK,GAA+B,CAAC,UAAU,IAAI,GAAG,CAAC;IACrF,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAK,KAAK,CAAC,OAAsC,CAAC,aAAa,CAAC;IAC5G,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,IAAI,GAAI,GAAyB,CAAC,IAAI,IAAI,gBAAgB,CAAC;IAEjE,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QACtC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,gCAAgC,CAAC,CAAC;IAC/E,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;QACxB,MAAM;QACN,IAAI;QACJ,OAAO;QACP,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fastrack/core — Application bootstrap, starter loading, config, shutdown.
+ * @see https://github.com/fastrack-platform-js/fastrack
+ */
+export * from "./create-app.js";
+export * from "./types.js";
+export * from "./error.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @fastrack/core — Application bootstrap, starter loading, config, shutdown.
+ * @see https://github.com/fastrack-platform-js/fastrack
+ */
+export * from "./create-app.js";
+export * from "./types.js";
+export * from "./error.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+import type { TSchema } from "@sinclair/typebox";
+import type { FastifyInstance } from "fastify";
+/**
+ * Bootstrap context passed to starters.
+ */
+export interface FastrackContext {
+    /** Fastify app instance */
+    app: FastifyInstance;
+    /** Root config (env + file, merged with starter defaults) */
+    config: Record<string, unknown>;
+    /** Logger (optional; app.log if not set) */
+    logger?: {
+        info: (o: unknown) => void;
+        error: (o: unknown) => void;
+        child: (bindings: Record<string, unknown>) => unknown;
+    };
+    /** Readiness getter (core sets this) */
+    getReadiness?: () => boolean;
+    /** Set readiness (core sets this; actuator /ready uses it) */
+    setReadiness?: (ready: boolean) => void;
+    /** Register shutdown hook (called in reverse order on SIGTERM) */
+    onShutdown?: (fn: () => Promise<void> | void) => void;
+    /** Register health contributor (actuator uses this) */
+    registerHealthContributor?: (name: string, check: () => Promise<HealthResult>) => void;
+}
+/**
+ * Health contributor result (design §9).
+ */
+export interface HealthResult {
+    ok: boolean;
+    status?: "up" | "down";
+    details?: Record<string, unknown>;
+}
+/**
+ * Health contributor interface (for actuator and starters that register).
+ */
+export interface HealthContributor {
+    name: string;
+    check(): Promise<HealthResult>;
+}
+/**
+ * Starter interface (design §4).
+ * Each starter provides: TypeBox config schema, Fastify plugin registration, optional health/shutdown.
+ */
+export interface FastrackStarter<TConfig = unknown> {
+    name: string;
+    configSchema: TSchema;
+    defaults?: Partial<TConfig>;
+    register(app: FastifyInstance, ctx: FastrackContext, config: TConfig): Promise<void> | void;
+}
+/**
+ * Options for createApp.
+ */
+export interface CreateAppOptions {
+    /** Starters to load (order is deterministic) */
+    starters?: FastrackStarter<unknown>[];
+    /** Override config (merged with env; starters get namespaced slice by starter name) */
+    config?: Record<string, unknown>;
+    /** Load .env file: path string (default ".env"), or false to disable. Uses dotenv. */
+    envPath?: string | false;
+    /** Shutdown timeout in ms (default 30_000) */
+    shutdownTimeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,GAAG,EAAE,eAAe,CAAC;IACrB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,4CAA4C;IAC5C,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAA;KAAE,CAAC;IAC5H,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;IAC7B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC,kEAAkE;IAClE,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IACtD,uDAAuD;IACvD,yBAAyB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;CACxF;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,GAAG,OAAO;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7F;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;IACtC,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@fastrack/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "fastify": "^5.1.0",
+    "@sinclair/typebox": "^0.34.34"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "lint": "echo ok",
+    "test": "echo ok"
+  }
+}

package/src/create-app.ts

@@ -0,0 +1,102 @@
+import { config as dotenvConfig } from "dotenv";
+import { Value } from "@sinclair/typebox/value";
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+import type { FastrackContext, CreateAppOptions } from "./types.js";
+
+const DEFAULT_SHUTDOWN_MS = 30_000;
+
+/**
+ * Create a Fastrack app: load env (.env via dotenv), validate starter configs, register starters, set up shutdown.
+ */
+export async function createApp(options: CreateAppOptions = {}): Promise<FastifyInstance> {
+  const {
+    starters = [],
+    config: configOverride = {},
+    envPath = ".env",
+    shutdownTimeoutMs = DEFAULT_SHUTDOWN_MS,
+  } = options;
+
+  if (envPath !== false) {
+    dotenvConfig({ path: envPath });
+  }
+
+  const app = Fastify({ logger: true });
+
+  let readiness = true;
+  const shutdownHooks: Array<() => Promise<void> | void> = [];
+  const healthContributors: Map<string, () => Promise<{ ok: boolean; status?: "up" | "down"; details?: Record<string, unknown> }>> = new Map();
+
+  const ctx: FastrackContext = {
+    app,
+    config: { ...configOverride },
+    get logger() {
+      return app.log as FastrackContext["logger"];
+    },
+    getReadiness: () => readiness,
+    setReadiness: (ready: boolean) => {
+      readiness = ready;
+    },
+    onShutdown: (fn) => {
+      shutdownHooks.push(fn);
+    },
+    registerHealthContributor: (name: string, check: () => Promise<{ ok: boolean; status?: "up" | "down"; details?: Record<string, unknown> }>) => {
+      healthContributors.set(name, check);
+    },
+  };
+
+  for (const starter of starters) {
+    const defaults = starter.defaults ?? {};
+    const raw = (ctx.config[starter.name] as Record<string, unknown>) ?? {};
+    const merged = { ...defaults, ...raw };
+    const errors = [...Value.Errors(starter.configSchema, merged)];
+    if (errors.length > 0) {
+      const msg = errors.map((e) => `${e.path}: ${e.message}`).join("; ");
+      throw new Error(`Config validation failed for starter "${starter.name}": ${msg}`);
+    }
+    const result = Value.Decode(starter.configSchema, merged) as unknown;
+    await Promise.resolve(starter.register(app, ctx, result));
+  }
+
+  const shutdown = async (signal: string) => {
+    readiness = false;
+    app.log?.info?.({ signal }, "Shutdown: readiness=false");
+    const timeout = setTimeout(() => {
+      app.log?.error?.("Shutdown timeout; exiting");
+      process.exit(1);
+    }, shutdownTimeoutMs);
+    try {
+      for (let i = shutdownHooks.length - 1; i >= 0; i--) {
+        const fn = shutdownHooks[i];
+        if (fn) await Promise.resolve(fn());
+      }
+      await app.close();
+    } finally {
+      clearTimeout(timeout);
+    }
+  };
+
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+
+  (app as unknown as { _fastrackContext: FastrackContext })._fastrackContext = ctx;
+  (app as unknown as { _healthContributors: Map<string, () => Promise<{ ok: boolean; status?: "up" | "down"; details?: Record<string, unknown> }>> })._healthContributors = healthContributors;
+
+  return app;
+}
+
+/**
+ * Get the Fastrack context from an app (for actuator / other starters).
+ */
+export function getFastrackContext(app: FastifyInstance): FastrackContext | undefined {
+  return (app as FastifyInstance & { _fastrackContext?: FastrackContext })._fastrackContext;
+}
+
+/**
+ * Get health contributors map from app (for actuator).
+ */
+export function getHealthContributors(
+  app: FastifyInstance
+): Map<string, () => Promise<{ ok: boolean; status?: "up" | "down"; details?: Record<string, unknown> }>> | undefined {
+  return (app as unknown as { _healthContributors?: Map<string, () => Promise<{ ok: boolean; status?: "up" | "down"; details?: Record<string, unknown> }>> })._healthContributors;
+}

package/src/error.ts

@@ -0,0 +1,40 @@
+import { Type } from "@sinclair/typebox";
+import type { FastifyReply } from "fastify";
+
+/**
+ * Problem-details error schema (design §5).
+ * Stack traces are logged server-side only; never exposed in response.
+ */
+export const ProblemDetailsSchema = Type.Object({
+  status: Type.Number({ description: "HTTP status" }),
+  code: Type.String({ description: "Error code" }),
+  message: Type.String({ description: "Human-readable message" }),
+  correlationId: Type.Optional(Type.String({ description: "Request correlation ID" })),
+});
+
+export type ProblemDetails = typeof ProblemDetailsSchema.static;
+
+/**
+ * Reply with problem-details body. Logs stack server-side only.
+ */
+export function replyError(
+  reply: FastifyReply,
+  err: unknown,
+  options?: { status?: number; correlationId?: string }
+): void {
+  const status = options?.status ?? (err as { statusCode?: number }).statusCode ?? 500;
+  const correlationId = options?.correlationId ?? (reply.request as { correlationId?: string }).correlationId;
+  const message = err instanceof Error ? err.message : String(err);
+  const code = (err as { code?: string }).code ?? "INTERNAL_ERROR";
+
+  if (err instanceof Error && err.stack) {
+    reply.log?.error?.({ err, correlationId }, "Error (stack server-side only)");
+  }
+
+  reply.status(status).send({
+    status,
+    code,
+    message,
+    ...(correlationId ? { correlationId } : {}),
+  });
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fastrack/core — Application bootstrap, starter loading, config, shutdown.
+ * @see https://github.com/fastrack-platform-js/fastrack
+ */
+export * from "./create-app.js";
+export * from "./types.js";
+export * from "./error.js";

package/src/types.ts

@@ -0,0 +1,64 @@
+import type { TSchema } from "@sinclair/typebox";
+import type { FastifyInstance } from "fastify";
+
+/**
+ * Bootstrap context passed to starters.
+ */
+export interface FastrackContext {
+  /** Fastify app instance */
+  app: FastifyInstance;
+  /** Root config (env + file, merged with starter defaults) */
+  config: Record<string, unknown>;
+  /** Logger (optional; app.log if not set) */
+  logger?: { info: (o: unknown) => void; error: (o: unknown) => void; child: (bindings: Record<string, unknown>) => unknown };
+  /** Readiness getter (core sets this) */
+  getReadiness?: () => boolean;
+  /** Set readiness (core sets this; actuator /ready uses it) */
+  setReadiness?: (ready: boolean) => void;
+  /** Register shutdown hook (called in reverse order on SIGTERM) */
+  onShutdown?: (fn: () => Promise<void> | void) => void;
+  /** Register health contributor (actuator uses this) */
+  registerHealthContributor?: (name: string, check: () => Promise<HealthResult>) => void;
+}
+
+/**
+ * Health contributor result (design §9).
+ */
+export interface HealthResult {
+  ok: boolean;
+  status?: "up" | "down";
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Health contributor interface (for actuator and starters that register).
+ */
+export interface HealthContributor {
+  name: string;
+  check(): Promise<HealthResult>;
+}
+
+/**
+ * Starter interface (design §4).
+ * Each starter provides: TypeBox config schema, Fastify plugin registration, optional health/shutdown.
+ */
+export interface FastrackStarter<TConfig = unknown> {
+  name: string;
+  configSchema: TSchema;
+  defaults?: Partial<TConfig>;
+  register(app: FastifyInstance, ctx: FastrackContext, config: TConfig): Promise<void> | void;
+}
+
+/**
+ * Options for createApp.
+ */
+export interface CreateAppOptions {
+  /** Starters to load (order is deterministic) */
+  starters?: FastrackStarter<unknown>[];
+  /** Override config (merged with env; starters get namespaced slice by starter name) */
+  config?: Record<string, unknown>;
+  /** Load .env file: path string (default ".env"), or false to disable. Uses dotenv. */
+  envPath?: string | false;
+  /** Shutdown timeout in ms (default 30_000) */
+  shutdownTimeoutMs?: number;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}