@justscale/core 0.1.0

package/dist/core/hmr.js

@@ -0,0 +1,211 @@
+/**
+ * Hot Module Replacement (HMR) Runtime
+ *
+ * Provides runtime functions for the compiler-generated HMR code.
+ * These functions are prefixed with __ to indicate they're compiler-internal.
+ *
+ * @module @justscale/core/hmr
+ */
+// ============================================================================
+// Global Container Reference
+// ============================================================================
+/**
+ * Global container reference for HMR runtime.
+ * Set by setHmrContainer() during app initialization.
+ */
+let hmrContainer = null;
+/**
+ * Set the container for HMR runtime.
+ * Called by the app builder during initialization in dev mode.
+ *
+ * @param container - The app's container instance
+ */
+export function setHmrContainer(container) {
+    hmrContainer = container;
+}
+/**
+ * Get the current HMR container.
+ * Throws if not initialized.
+ */
+function getContainer() {
+    if (!hmrContainer) {
+        throw new Error('[HMR] Container not initialized. Are you running in dev mode with `just dev`?');
+    }
+    return hmrContainer;
+}
+// ============================================================================
+// Type Hash Registry
+// ============================================================================
+/**
+ * Stores the current type hash schema for each service.
+ * Updated each time __validateHmrState is called during factory execution.
+ * Used by __wrapHmrStateForSave to bundle hashes with saved state.
+ */
+const typeHashRegistry = new Map();
+/**
+ * Wrap user-provided hotReload state with type hashes for later validation.
+ * Called by the container when saving HMR state during full reload.
+ *
+ * @param serviceId - The stable service ID
+ * @param state - The raw state from the user's hotReload callback
+ * @returns Wrapped state with __values and __typeHashes, or the raw state if no hashes registered
+ */
+export function __wrapHmrStateForSave(serviceId, state) {
+    if (state == null || typeof state !== 'object') {
+        return state;
+    }
+    const schema = typeHashRegistry.get(serviceId);
+    if (!schema) {
+        return state;
+    }
+    return {
+        __values: state,
+        __typeHashes: { ...schema },
+    };
+}
+// ============================================================================
+// Compiler-Generated Functions
+// ============================================================================
+/**
+ * Get HMR state for a service during factory execution.
+ * Called by compiler-generated factory wrapper:
+ *
+ * ```typescript
+ * factory: ((__hmr) =>
+ *   ({ lifecycle }) => {
+ *     const cache = __hmr?.cache ?? new Map()
+ *     // ...
+ *   }
+ * )(__getHmrState('src/services/cache.ts#CacheService'))
+ * ```
+ *
+ * @param serviceId - The stable service ID
+ * @returns The saved HMR state, or undefined if none
+ */
+export function __getHmrState(serviceId) {
+    if (!hmrContainer) {
+        // Not in dev mode or container not initialized yet
+        return undefined;
+    }
+    return hmrContainer.getHmrState(serviceId);
+}
+/**
+ * Patch methods on a service instance.
+ * Called by compiler-generated HMR update code when only method bodies changed.
+ *
+ * @param serviceId - The stable service ID
+ * @param changedMethods - List of method names that changed
+ */
+export async function __hmrPatchMethods(serviceId, changedMethods) {
+    const container = getContainer();
+    await container.hotReload(serviceId, 'method-patch', changedMethods);
+}
+/**
+ * Trigger a full reload of a service.
+ * Called by compiler-generated HMR update code when structure changed.
+ *
+ * @param serviceId - The stable service ID
+ */
+export async function __hmrFullReload(serviceId) {
+    const container = getContainer();
+    await container.hotReload(serviceId, 'full-reload');
+}
+/**
+ * Validate HMR state before injection.
+ *
+ * Performs per-variable type-aware validation. The state is stored as:
+ *   { __values: { cache: ..., counter: ... }, __typeHashes: { cache: 'abc', counter: 'def' } }
+ *
+ * For each expected variable, compares the stored type hash against the current
+ * expected hash. Variables whose types haven't changed are preserved; variables
+ * whose types changed are discarded (returning undefined for that key, so the
+ * ?? fallback in the factory kicks in).
+ *
+ * Also supports legacy format (plain object without __values/__typeHashes) for
+ * backward compatibility - in that case, all keys are preserved if they match
+ * by name (no type validation possible).
+ *
+ * @param state - The raw state from __getHmrState
+ * @param expectedSchema - Map of variable name to type hash (or string[] for legacy)
+ * @param serviceId - The service ID (for warning messages)
+ * @returns The validated state (partial object with only type-compatible keys), or undefined
+ */
+export function __validateHmrState(state, expectedSchema, serviceId) {
+    // Register current schema for future saves (only for Record format)
+    if (!Array.isArray(expectedSchema)) {
+        typeHashRegistry.set(serviceId, expectedSchema);
+    }
+    if (state == null) {
+        return undefined;
+    }
+    if (typeof state !== 'object') {
+        console.warn(`[HMR] ${serviceId}: discarding state - expected object, got ${typeof state}`);
+        return undefined;
+    }
+    if (Array.isArray(expectedSchema)) {
+        const stateKeys = Object.keys(state);
+        const expectedSet = new Set(expectedSchema);
+        const stateSet = new Set(stateKeys);
+        const missing = expectedSchema.filter(k => !stateSet.has(k));
+        const extra = stateKeys.filter(k => !expectedSet.has(k));
+        if (missing.length > 0 || extra.length > 0) {
+            const parts = [];
+            if (missing.length > 0)
+                parts.push(`missing: ${missing.join(', ')}`);
+            if (extra.length > 0)
+                parts.push(`extra: ${extra.join(', ')}`);
+            console.warn(`[HMR] ${serviceId}: discarding state - shape mismatch (${parts.join('; ')})`);
+            return undefined;
+        }
+        return state;
+    }
+    const stateObj = state;
+    const storedValues = stateObj.__values;
+    const storedHashes = stateObj.__typeHashes;
+    if (!storedValues) {
+        const stateKeys = Object.keys(state);
+        const expectedKeys = Object.keys(expectedSchema);
+        const expectedSet = new Set(expectedKeys);
+        const stateSet = new Set(stateKeys);
+        const missing = expectedKeys.filter(k => !stateSet.has(k));
+        const extra = stateKeys.filter(k => !expectedSet.has(k));
+        if (missing.length > 0 || extra.length > 0) {
+            console.warn(`[HMR] ${serviceId}: discarding state - shape mismatch`);
+            return undefined;
+        }
+        return state;
+    }
+    // Per-key type-aware validation
+    const result = {};
+    const discarded = [];
+    for (const [key, expectedHash] of Object.entries(expectedSchema)) {
+        const storedHash = storedHashes?.[key];
+        const hasValue = key in storedValues;
+        if (!hasValue) {
+            // New variable added - will use ?? fallback
+            continue;
+        }
+        // Empty hash means no type info (no checker was available) - always accept
+        if (expectedHash === '' || storedHash === '' || storedHash === undefined) {
+            result[key] = storedValues[key];
+            continue;
+        }
+        if (storedHash === expectedHash) {
+            result[key] = storedValues[key];
+        }
+        else {
+            discarded.push(key);
+        }
+    }
+    if (discarded.length > 0) {
+        console.warn(`[HMR] ${serviceId}: type changed for ${discarded.join(', ')} - using fresh defaults`);
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Check if HMR is available (dev mode with container initialized).
+ */
+export function __hmrAvailable() {
+    return hmrContainer !== null;
+}
+//# sourceMappingURL=hmr.js.map

package/dist/core/hmr.js.map

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

package/dist/core/index.d.ts

@@ -0,0 +1,17 @@
+export * from './service.js';
+export * from './contribution.js';
+export * from './disposable.js';
+export * from './container-reflection.js';
+export * from './scope-bridge.js';
+export * from './context.js';
+export { Lifecycle, isLifecycleToken, LIFECYCLE_TOKEN } from './lifecycle.js';
+export type { LifecycleHooks } from './lifecycle.js';
+export { LifecycleImpl } from './lifecycle-impl.js';
+export * from './logger.js';
+export * from './controller.js';
+export * from './controller.contextual.js';
+export * from './controller.procedure.js';
+export * from './middleware.js';
+export * from './plugin.js';
+export * from './hmr.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAGA,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAGlC,cAAc,cAAc,CAAC;AAG7B,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,cAAc,aAAa,CAAC;AAG5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAG1C,cAAc,iBAAiB,CAAC;AAGhC,cAAc,aAAa,CAAC;AAG5B,cAAc,UAAU,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,25 @@
+// Core - Foundation: DI + routing + observability
+// DI Container & Services
+export * from './service.js';
+export * from './contribution.js';
+export * from './disposable.js';
+export * from './container-reflection.js';
+export * from './scope-bridge.js';
+// Request Context
+export * from './context.js';
+// Lifecycle
+export { Lifecycle, isLifecycleToken, LIFECYCLE_TOKEN } from './lifecycle.js';
+export { LifecycleImpl } from './lifecycle-impl.js';
+// Logger
+export * from './logger.js';
+// Controller
+export * from './controller.js';
+export * from './controller.contextual.js';
+export * from './controller.procedure.js';
+// Middleware & Guards
+export * from './middleware.js';
+// Plugin System
+export * from './plugin.js';
+// HMR
+export * from './hmr.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAElD,0BAA0B;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAElC,kBAAkB;AAClB,cAAc,cAAc,CAAC;AAE7B,YAAY;AACZ,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAE9E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,SAAS;AACT,cAAc,aAAa,CAAC;AAE5B,aAAa;AACb,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAE1C,sBAAsB;AACtB,cAAc,iBAAiB,CAAC;AAEhC,gBAAgB;AAChB,cAAc,aAAa,CAAC;AAE5B,MAAM;AACN,cAAc,UAAU,CAAC"}

package/dist/core/internal/routes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Internal Route Utilities
+ *
+ * Helper functions for route compilation and matching.
+ * Not part of the public API.
+ */
+/**
+ * Join controller prefix and route path cleanly.
+ * Returns both the full path string and an array of segments.
+ *
+ * Examples:
+ * - /players + / = { path: '/players', segments: ['players'] }
+ * - /players + /:id = { path: '/players/:id', segments: ['players', ':id'] }
+ * - auth + create-user = { path: 'auth/create-user', segments: ['auth', 'create-user'] }
+ * - '' + shell = { path: 'shell', segments: ['shell'] }
+ */
+export declare function joinPaths(prefix: string, path: string): {
+    path: string;
+    segments: string[];
+};
+/** Compile a path pattern to regex */
+export declare function compilePath(path: string): {
+    pattern: RegExp;
+    paramNames: string[];
+};
+//# sourceMappingURL=routes.d.ts.map

package/dist/core/internal/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/core/internal/routes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAoB5F;AAED,sCAAsC;AACtC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAcnF"}

package/dist/core/internal/routes.js

@@ -0,0 +1,48 @@
+/**
+ * Internal Route Utilities
+ *
+ * Helper functions for route compilation and matching.
+ * Not part of the public API.
+ */
+/**
+ * Join controller prefix and route path cleanly.
+ * Returns both the full path string and an array of segments.
+ *
+ * Examples:
+ * - /players + / = { path: '/players', segments: ['players'] }
+ * - /players + /:id = { path: '/players/:id', segments: ['players', ':id'] }
+ * - auth + create-user = { path: 'auth/create-user', segments: ['auth', 'create-user'] }
+ * - '' + shell = { path: 'shell', segments: ['shell'] }
+ */
+export function joinPaths(prefix, path) {
+    // Parse prefix into segments (filter empty strings from leading/trailing slashes)
+    const prefixSegments = prefix.split('/').filter(s => s !== '');
+    // Parse path into segments
+    const pathSegments = (path === '/' || path === '')
+        ? []
+        : path.split('/').filter(s => s !== '');
+    // Combine segments
+    const segments = [...prefixSegments, ...pathSegments];
+    // Build path string - HTTP routes need leading slash, CLI routes don't
+    // We check both prefix and path to determine this (prefix takes priority, then path)
+    const needsLeadingSlash = prefix.startsWith('/') || (prefix === '' && path.startsWith('/'));
+    const fullPath = segments.length === 0
+        ? '/'
+        : (needsLeadingSlash ? '/' : '') + segments.join('/');
+    return { path: fullPath, segments };
+}
+/** Compile a path pattern to regex */
+export function compilePath(path) {
+    const paramNames = [];
+    let pattern = path.replace(/:(\w+)/g, (_, name) => {
+        paramNames.push(name);
+        return '([^/]+)';
+    });
+    // Make trailing slash optional: /players matches both /players and /players/
+    pattern = pattern + '/?';
+    return {
+        pattern: new RegExp(`^${pattern}$`),
+        paramNames,
+    };
+}
+//# sourceMappingURL=routes.js.map

package/dist/core/internal/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../../src/core/internal/routes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,IAAY;IACpD,kFAAkF;IAClF,MAAM,cAAc,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAE/D,2BAA2B;IAC3B,MAAM,YAAY,GAAG,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC;QAChD,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAE1C,mBAAmB;IACnB,MAAM,QAAQ,GAAG,CAAC,GAAG,cAAc,EAAE,GAAG,YAAY,CAAC,CAAC;IAEtD,uEAAuE;IACvE,qFAAqF;IACrF,MAAM,iBAAiB,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5F,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,KAAK,CAAC;QACpC,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAExD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE;QAChD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAC7E,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;IAEzB,OAAO;QACL,OAAO,EAAE,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,CAAC;QACnC,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/core/lifecycle-impl.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Lifecycle Implementation
+ *
+ * Concrete implementation of the Lifecycle abstract class.
+ * Manages handler registration and execution with proper ordering.
+ */
+import { Lifecycle, type LifecycleHooks } from './lifecycle.js';
+/** @internal Concrete Lifecycle implementation used by the kernel. */
+export declare class LifecycleImpl extends Lifecycle {
+    private handlers;
+    private currentPhase;
+    private hotReloadHandlers;
+    private currentServiceId;
+    /**
+     * Register a lifecycle hook handler.
+     *
+     * @throws Error if attempting to register during the same hook's execution
+     */
+    register<K extends keyof LifecycleHooks>(hook: K, handler: LifecycleHooks[K]): void;
+    /**
+     * Check if a specific lifecycle phase is currently running.
+     */
+    isInPhase(hook: keyof LifecycleHooks): boolean;
+    /**
+     * Run all handlers for a hook.
+     *
+     * Execution order:
+     * - 'stop': LIFO (reverse order) for proper dependency cleanup
+     * - All others: FIFO (registration order)
+     *
+     * Error handling:
+     * - Errors are caught and logged
+     * - Execution continues with remaining handlers
+     * - All handlers are guaranteed to be called
+     *
+     * @param hook - The hook to execute handlers for
+     */
+    runHook(hook: keyof LifecycleHooks): Promise<void>;
+    setServiceContext(serviceId: string | null): void;
+    getServiceContext(): string | null;
+    runHotReload(serviceId: string): Promise<unknown>;
+    hasHotReloadHandler(serviceId: string): boolean;
+    clearHotReloadHandler(serviceId: string): void;
+}
+//# sourceMappingURL=lifecycle-impl.d.ts.map

package/dist/core/lifecycle-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-impl.d.ts","sourceRoot":"","sources":["../../src/core/lifecycle-impl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAahE,sEAAsE;AACtE,qBAAa,aAAc,SAAQ,SAAS;IAC1C,OAAO,CAAC,QAAQ,CAAkD;IAClE,OAAO,CAAC,YAAY,CAAqC;IAEzD,OAAO,CAAC,iBAAiB,CAAuC;IAChE,OAAO,CAAC,gBAAgB,CAAuB;IAE/C;;;;OAIG;IACH,QAAQ,CAAC,CAAC,SAAS,MAAM,cAAc,EACrC,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,IAAI;IAqBP;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,cAAc,GAAG,OAAO;IAI9C;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBxD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIjD,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAI5B,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAcvD,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI/C,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAG/C"}

package/dist/core/lifecycle-impl.js

@@ -0,0 +1,102 @@
+/**
+ * Lifecycle Implementation
+ *
+ * Concrete implementation of the Lifecycle abstract class.
+ * Manages handler registration and execution with proper ordering.
+ */
+import { Lifecycle } from './lifecycle.js';
+// ============================================================================
+// Lifecycle Implementation
+// ============================================================================
+/** @internal Concrete Lifecycle implementation used by the kernel. */
+export class LifecycleImpl extends Lifecycle {
+    handlers = new Map();
+    currentPhase = null;
+    hotReloadHandlers = new Map();
+    currentServiceId = null;
+    /**
+     * Register a lifecycle hook handler.
+     *
+     * @throws Error if attempting to register during the same hook's execution
+     */
+    register(hook, handler) {
+        if (this.currentPhase === hook) {
+            throw new Error(`Cannot register '${hook}' handler while '${hook}' phase is running`);
+        }
+        if (hook === 'hotReload') {
+            if (!this.currentServiceId) {
+                console.warn('[Lifecycle] hotReload handler registered without service context - will be ignored');
+                return;
+            }
+            this.hotReloadHandlers.set(this.currentServiceId, handler);
+            return;
+        }
+        const handlers = this.handlers.get(hook) ?? [];
+        handlers.push(handler);
+        this.handlers.set(hook, handlers);
+    }
+    /**
+     * Check if a specific lifecycle phase is currently running.
+     */
+    isInPhase(hook) {
+        return this.currentPhase === hook;
+    }
+    /**
+     * Run all handlers for a hook.
+     *
+     * Execution order:
+     * - 'stop': LIFO (reverse order) for proper dependency cleanup
+     * - All others: FIFO (registration order)
+     *
+     * Error handling:
+     * - Errors are caught and logged
+     * - Execution continues with remaining handlers
+     * - All handlers are guaranteed to be called
+     *
+     * @param hook - The hook to execute handlers for
+     */
+    async runHook(hook) {
+        this.currentPhase = hook;
+        try {
+            const handlers = this.handlers.get(hook) ?? [];
+            const ordered = hook === 'stop' ? [...handlers].reverse() : handlers;
+            for (const handler of ordered) {
+                try {
+                    await handler();
+                }
+                catch (error) {
+                    console.error(`[Lifecycle] ${hook} handler threw:`, error);
+                }
+            }
+        }
+        finally {
+            this.currentPhase = null;
+        }
+    }
+    setServiceContext(serviceId) {
+        this.currentServiceId = serviceId;
+    }
+    getServiceContext() {
+        return this.currentServiceId;
+    }
+    async runHotReload(serviceId) {
+        const handler = this.hotReloadHandlers.get(serviceId);
+        if (!handler) {
+            return undefined;
+        }
+        try {
+            return await handler();
+        }
+        catch (error) {
+            console.error(`[Lifecycle] hotReload handler for ${serviceId} threw:`, error);
+            return undefined;
+        }
+    }
+    hasHotReloadHandler(serviceId) {
+        return this.hotReloadHandlers.has(serviceId);
+    }
+    clearHotReloadHandler(serviceId) {
+        this.hotReloadHandlers.delete(serviceId);
+    }
+}
+//# sourceMappingURL=lifecycle-impl.js.map

package/dist/core/lifecycle-impl.js.map

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

package/dist/core/lifecycle.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Lifecycle hook registration for graceful shutdown and extensible events.
+ */
+/**
+ * Symbol to identify Lifecycle as a built-in service.
+ * Used by Container to detect and special-case Lifecycle resolution.
+ */
+export declare const LIFECYCLE_TOKEN: unique symbol;
+/**
+ * Extensible lifecycle hooks interface.
+ * Transports and features extend this via module augmentation.
+ *
+ * @example Adding HTTP serving hook (in @justscale/http)
+ * ```typescript
+ * declare module '@justscale/core' {
+ *   interface LifecycleHooks {
+ *     httpServing(): Promise<void> | void
+ *   }
+ * }
+ * ```
+ *
+ * @example Adding WebSocket ready hook (in @justscale/websocket)
+ * ```typescript
+ * declare module '@justscale/core' {
+ *   interface LifecycleHooks {
+ *     wsReady(): Promise<void> | void
+ *   }
+ * }
+ * ```
+ */
+export interface LifecycleHooks {
+    /** Called when cluster.stop() is invoked. LIFO order. */
+    stop(): Promise<void> | void;
+    /**
+     * Called when this service is about to be hot-reloaded (dev mode only).
+     * Return state to preserve across the reload.
+     *
+     * The compiler automatically injects the returned state into variable
+     * initializers, so you don't need manual restoration logic.
+     *
+     * @example
+     * ```typescript
+     * class CacheService extends defineService({
+     *   inject: { lifecycle: Lifecycle },
+     *   factory: ({ lifecycle }) => {
+     *     const cache = new Map<string, User>()
+     *
+     *     // Declare what to preserve - compiler handles the rest
+     *     lifecycle.register('hotReload', () => ({ cache }))
+     *
+     *     return { get: (id) => cache.get(id) }
+     *   }
+     * }) {}
+     * ```
+     */
+    hotReload(): Promise<unknown> | unknown;
+}
+/**
+ * Lifecycle service for registering hooks.
+ *
+ * @example
+ * ```typescript
+ * class DatabaseService extends defineService({
+ *   inject: { lifecycle: Lifecycle },
+ *   factory: async ({ lifecycle }) => {
+ *     const pool = await createPool()
+ *     lifecycle.register('stop', async () => { await pool.end() })
+ *     return { pool }
+ *   }
+ * }) {}
+ * ```
+ */
+export declare abstract class Lifecycle {
+    /**
+     * Register a lifecycle hook handler.
+     * 'stop' runs LIFO; all other hooks run FIFO.
+     *
+     * @throws Error if registering during the same hook's execution.
+     */
+    abstract register<K extends keyof LifecycleHooks>(hook: K, handler: LifecycleHooks[K]): void;
+    /** Returns true if the given hook phase is currently executing. */
+    abstract isInPhase(hook: keyof LifecycleHooks): boolean;
+}
+/** @internal */
+export declare function isLifecycleToken(token: unknown): token is typeof Lifecycle;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/core/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/core/lifecycle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;;GAGG;AACH,eAAO,MAAM,eAAe,eAAgC,CAAC;AAM7D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAE5B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;CACxC;AAMD;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,SAAS;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,CAAC,SAAS,MAAM,cAAc,EAC9C,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,IAAI;IAEP,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,cAAc,GAAG,OAAO;CACxD;AAID,gBAAgB;AAChB,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,SAAS,CAE1E"}

package/dist/core/lifecycle.js

@@ -0,0 +1,38 @@
+/**
+ * Lifecycle hook registration for graceful shutdown and extensible events.
+ */
+// ============================================================================
+// Lifecycle Token
+// ============================================================================
+/**
+ * Symbol to identify Lifecycle as a built-in service.
+ * Used by Container to detect and special-case Lifecycle resolution.
+ */
+export const LIFECYCLE_TOKEN = Symbol('justscale:Lifecycle');
+// ============================================================================
+// Lifecycle Abstract Class
+// ============================================================================
+/**
+ * Lifecycle service for registering hooks.
+ *
+ * @example
+ * ```typescript
+ * class DatabaseService extends defineService({
+ *   inject: { lifecycle: Lifecycle },
+ *   factory: async ({ lifecycle }) => {
+ *     const pool = await createPool()
+ *     lifecycle.register('stop', async () => { await pool.end() })
+ *     return { pool }
+ *   }
+ * }) {}
+ * ```
+ */
+export class Lifecycle {
+}
+;
+Lifecycle[LIFECYCLE_TOKEN] = true;
+/** @internal */
+export function isLifecycleToken(token) {
+    return token === Lifecycle || token?.[LIFECYCLE_TOKEN] === true;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/core/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/core/lifecycle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAyD7D,+EAA+E;AAC/E,2BAA2B;AAC3B,+EAA+E;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAgB,SAAS;CAc9B;AAED,CAAC;AAAC,SAAiB,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC;AAE5C,gBAAgB;AAChB,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,KAAK,KAAK,SAAS,IAAK,KAAa,EAAE,CAAC,eAAe,CAAC,KAAK,IAAI,CAAC;AAC3E,CAAC"}