@fulmenhq/tsfulmen 0.2.2 → 0.2.4

package/dist/signals/index.d.ts

@@ -1,5 +1,6 @@
-import { a as BehaviorInfo, m as SignalInfo, k as SignalCatalog, S as SignalManager, l as SignalHandler, H as HandlerOptions, F as FallbackLogger, T as TelemetryEmitter } from '../manager-CH3fX7zO.js';
+import { a as BehaviorInfo, m as SignalInfo, k as SignalCatalog, S as SignalManager, F as FallbackLogger, T as TelemetryEmitter, l as SignalHandler, H as HandlerOptions } from '../manager-CH3fX7zO.js';
 export { B as Behavior, b as BehaviorPhase, E as ExitCodes, L as LogLevel, O as OsMappings, P as PlatformOverrides, e as PlatformSupport, f as PlatformSupportLevel, i as Signal, j as SignalBehavior, n as SignalManagerOptions, o as TimeoutBehavior, W as WindowsFallback, p as WindowsFallbackBehavior, q as WindowsFallbackOptions, s as WindowsFallbackResult, c as createSignalManager, g as getFallbackMetadata, d as getHttpFallbackGuidance, h as handleWindowsFallback, r as requiresFallback } from '../manager-CH3fX7zO.js';
+import { I as Identity } from '../types-Dv5TERCM.js';
 
 /**
  * Signal Capability Detection
@@ -116,560 +117,647 @@ declare function getBehavior(id: string): Promise<BehaviorInfo | null>;
 declare function getSignalCatalog(): Promise<SignalCatalog>;
 
 /**
- * Signal Handler Convenience Wrappers
+ * HTTP Signal Endpoint Helper
  *
- * Common signal handling patterns for shutdown, reload, and custom behaviors.
+ * Framework-agnostic scaffold for POST /admin/signal endpoint.
+ * Applications provide auth/rate-limiting; helper handles validation and execution.
  */
 
 /**
- * Register a graceful shutdown handler
- *
- * Convenience wrapper for SIGTERM and SIGINT handlers.
- * Automatically registers both signals to the same handler.
+ * Signal request payload
+ */
+interface SignalRequest {
+    signal: string;
+    reason?: string;
+    correlation_id?: string;
+}
+/**
+ * Signal response (success)
+ */
+interface SignalResponse {
+    status: "accepted";
+    signal: string;
+    correlation_id: string;
+    message: string;
+}
+/**
+ * Signal error response
+ */
+interface SignalErrorResponse {
+    status: "error";
+    error: string;
+    message: string;
+    valid_signals?: string[];
+}
+/**
+ * Authentication result
+ */
+interface AuthResult {
+    authenticated: boolean;
+    identity?: string;
+    reason?: string;
+}
+/**
+ * Rate limit result
+ */
+interface RateLimitResult {
+    allowed: boolean;
+    remaining?: number;
+    reset_at?: number;
+}
+/**
+ * Authentication hook function
  *
- * @param manager - Signal manager instance
- * @param handler - Shutdown handler function
- * @param options - Handler options
+ * Applications must provide this to validate requests.
+ * Returns authentication result with optional identity.
+ */
+type AuthHook = (req: unknown) => Promise<AuthResult> | AuthResult;
+/**
+ * Rate limiting hook function
  *
- * @example
- * ```typescript
- * await onShutdown(manager, async () => {
- *   await closeDatabase();
- *   await flushLogs();
- * });
- * ```
+ * Applications may provide this to enforce rate limits.
+ * Returns whether request is allowed and quota info.
  */
-declare function onShutdown(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+type RateLimitHook = (identity: string, signal: string) => Promise<RateLimitResult> | RateLimitResult;
 /**
- * Register a config reload handler
+ * Signal endpoint options
+ */
+interface SignalEndpointOptions {
+    /**
+     * Signal manager instance
+     */
+    manager: SignalManager;
+    /**
+     * Authentication hook (required)
+     */
+    auth: AuthHook;
+    /**
+     * Rate limiting hook (optional)
+     */
+    rateLimit?: RateLimitHook;
+    /**
+     * Logger for endpoint events
+     */
+    logger?: FallbackLogger;
+    /**
+     * Telemetry emitter
+     */
+    telemetry?: TelemetryEmitter;
+    /**
+     * Allowed signals (default: all catalog signals)
+     */
+    allowedSignals?: string[];
+}
+/**
+ * Create a framework-agnostic signal endpoint handler
  *
- * Convenience wrapper for SIGHUP handler.
- * Only registers on POSIX platforms (SIGHUP not supported on Windows).
+ * Returns an async function that processes signal requests.
+ * Applications wire this to their HTTP framework (Express, Fastify, etc.)
  *
- * @param manager - Signal manager instance
- * @param handler - Reload handler function
- * @param options - Handler options
+ * @param options - Endpoint configuration
  *
- * @example
+ * @example Express
  * ```typescript
- * await onReload(manager, async () => {
- *   const newConfig = await loadConfig();
- *   await validateConfig(newConfig);
- *   process.exit(129); // Exit for restart
+ * const handler = createSignalEndpoint({
+ *   manager,
+ *   auth: async (req) => {
+ *     const token = req.headers.authorization?.split(' ')[1];
+ *     return { authenticated: token === process.env.ADMIN_TOKEN };
+ *   },
  * });
- * ```
- */
-declare function onReload(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
-/**
- * Register a custom handler for SIGUSR1
  *
- * Common use cases: toggle debug logging, reopen log files, dump statistics.
- *
- * @param manager - Signal manager instance
- * @param handler - Custom handler function
- * @param options - Handler options
+ * app.post('/admin/signal', async (req, res) => {
+ *   const result = await handler(req.body, req);
+ *   res.status(result.status === 'accepted' ? 202 : result.statusCode || 400)
+ *      .json(result);
+ * });
+ * ```
  *
- * @example
+ * @example Fastify
  * ```typescript
- * await onUSR1(manager, async () => {
- *   logger.info('SIGUSR1 received - reopening log files');
- *   await reopenLogFiles();
+ * const handler = createSignalEndpoint({ manager, auth });
+ *
+ * fastify.post('/admin/signal', async (request, reply) => {
+ *   const result = await handler(request.body, request);
+ *   reply.status(result.status === 'accepted' ? 202 : 400).send(result);
  * });
  * ```
  */
-declare function onUSR1(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+declare function createSignalEndpoint(options: SignalEndpointOptions): (payload: SignalRequest, req: unknown) => Promise<(SignalResponse | SignalErrorResponse) & {
+    statusCode?: number;
+}>;
 /**
- * Register a custom handler for SIGUSR2
+ * Create a simple bearer token auth hook
  *
- * Common use cases: trigger profiling, rotate credentials, toggle verbose mode.
+ * Validates requests against a static token.
+ * For production, use mTLS or more robust auth.
  *
- * @param manager - Signal manager instance
- * @param handler - Custom handler function
- * @param options - Handler options
+ * @param expectedToken - Expected bearer token
  *
  * @example
  * ```typescript
- * await onUSR2(manager, async () => {
- *   logger.info('SIGUSR2 received - toggling debug mode');
- *   toggleDebugMode();
- * });
+ * const auth = createBearerTokenAuth(process.env.ADMIN_TOKEN);
+ * const handler = createSignalEndpoint({ manager, auth });
  * ```
  */
-declare function onUSR2(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+declare function createBearerTokenAuth(expectedToken: string): AuthHook;
 /**
- * Register an emergency quit handler
+ * Create a simple in-memory rate limiter
  *
- * Convenience wrapper for SIGQUIT (immediate exit, no cleanup).
+ * Tracks requests per identity with sliding window.
+ * For production, use Redis or distributed rate limiting.
  *
- * @param manager - Signal manager instance
- * @param handler - Emergency quit handler
- * @param options - Handler options
+ * @param requestsPerMinute - Max requests per minute per identity
  *
  * @example
  * ```typescript
- * await onEmergencyQuit(manager, async () => {
- *   logger.error('SIGQUIT received - emergency exit');
- *   process.exit(131);
- * });
+ * const rateLimit = createSimpleRateLimiter(10); // 10 req/min
+ * const handler = createSignalEndpoint({ manager, auth, rateLimit });
  * ```
  */
-declare function onEmergencyQuit(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+declare function createSimpleRateLimiter(requestsPerMinute: number): RateLimitHook;
+
 /**
- * Register handlers for all common shutdown signals
- *
- * Registers the same handler for SIGTERM, SIGINT, and SIGQUIT.
- * Useful for applications that want consistent shutdown behavior.
+ * Configuration Reload Helpers
  *
- * @param manager - Signal manager instance
- * @param handler - Shutdown handler function
- * @param options - Handler options
+ * Implements restart-based config reload pattern with mandatory schema validation.
+ * Per Crucible standard: validate before restart, reject invalid configs without disruption.
  */
-declare function onAnyShutdown(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
 
 /**
- * Double-Tap Signal Handling
+ * Configuration validator function type
  *
- * Implements Ctrl+C double-tap pattern for graceful shutdown with force-quit option.
- * Per Crucible standard: 2-second window, immediate exit on second signal.
+ * Applications provide this function to validate new config against schema.
+ * Should return validation result with errors if invalid.
  */
-
+type ConfigValidator<T = unknown> = (config: T) => Promise<ConfigValidationResult> | ConfigValidationResult;
 /**
- * Double-tap configuration
+ * Configuration validation result
  */
-interface DoubleTapConfig {
+interface ConfigValidationResult {
+    valid: boolean;
+    errors?: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+/**
+ * Configuration loader function type
+ *
+ * Applications provide this function to load new config from disk/environment.
+ */
+type ConfigLoader<T = unknown> = () => Promise<T> | T;
+/**
+ * Config reload options
+ */
+interface ConfigReloadOptions<T = unknown> {
     /**
-     * Debounce window in milliseconds (default: 2000ms per Crucible standard)
+     * Config loader function
      */
-    windowMs?: number;
+    loader: ConfigLoader<T>;
     /**
-     * Exit code for forced double-tap exit (default: 130 for SIGINT)
+     * Schema validator function
      */
-    exitCode?: number;
+    validator: ConfigValidator<T>;
     /**
-     * Message to display on first signal (default: from catalog)
+     * Callback invoked after successful validation, before exit
+     * Use for cleanup, logging, etc.
      */
-    hintMessage?: string;
+    onValidated?: (config: T) => void | Promise<void>;
     /**
-     * Logger for double-tap events
+     * Exit code for successful reload (default: 129 for SIGHUP)
+     */
+    exitCode?: number;
+    /**
+     * Logger for reload events
      */
     logger?: FallbackLogger;
     /**
-     * Enable test mode (prevents process.exit calls)
+     * Telemetry emitter
+     */
+    telemetry?: TelemetryEmitter;
+    /**
+     * Test mode (prevents process.exit)
      */
     testMode?: boolean;
 }
 /**
- * Double-tap state tracker
+ * Config reload result (for testing)
  */
-interface DoubleTapState {
-    firstTapTime: number | null;
-    windowMs: number;
-    exitCode: number;
-    hintMessage: string;
-    logger?: FallbackLogger;
-    testMode: boolean;
-}
-/**
- * Create double-tap state tracker for a signal
- *
- * @param signalName - Signal name (typically "SIGINT")
- * @param config - Double-tap configuration
- */
-declare function createDoubleTapTracker(signalName: string, config?: DoubleTapConfig): Promise<DoubleTapState>;
-/**
- * Handle double-tap signal logic
- *
- * Returns true if this is the second tap (force-quit), false if first tap.
- * Updates state to track timing between taps.
- *
- * @param state - Double-tap state tracker
- * @returns true if force-quit should proceed, false if graceful shutdown
- */
-declare function handleDoubleTap(state: DoubleTapState): boolean;
-/**
- * Reset double-tap state
- *
- * Called when graceful shutdown completes before second tap.
- */
-declare function resetDoubleTap(state: DoubleTapState): void;
-/**
- * Check if currently within double-tap window
- *
- * Useful for testing and debugging.
- */
-declare function isWithinWindow(state: DoubleTapState): boolean;
-/**
- * Get time remaining in double-tap window (milliseconds)
- *
- * Returns null if not in a window, otherwise milliseconds remaining.
- */
-declare function getWindowTimeRemaining(state: DoubleTapState): number | null;
-
-/**
- * Signal Support Guards
- *
- * Validation functions that throw actionable errors when signals are unsupported.
- * Used to fail-fast with clear operational guidance.
- */
-/**
- * Guard options
- */
-interface GuardOptions {
-    /**
-     * Include platform-specific operational guidance in error message
-     */
-    includeGuidance?: boolean;
+interface ConfigReloadResult {
+    reloaded: boolean;
+    validationErrors?: Array<{
+        path: string;
+        message: string;
+    }>;
+    error?: Error;
 }
 /**
- * Ensure a signal is supported on the current platform
+ * Create a config reload handler with schema validation
  *
- * Throws an error with actionable guidance if the signal is not supported.
- * Use this as a guard at the start of signal registration functions.
+ * Returns a signal handler function that implements restart-based reload:
+ * 1. Load new config
+ * 2. Validate against schema (mandatory)
+ * 3. If invalid: log errors, continue with current config
+ * 4. If valid: invoke callback, exit for restart
  *
- * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
- * @param options - Guard configuration
- * @throws {FoundryCatalogError} If signal is not found or not supported
+ * @param options - Reload configuration
  *
  * @example
  * ```typescript
- * await ensureSupported("SIGHUP");
- * // On Windows: throws with HTTP fallback guidance
- * // On POSIX: passes through
- * ```
- */
-declare function ensureSupported(signalName: string, options?: GuardOptions): Promise<void>;
-/**
- * Ensure platform supports signal-based exit codes
- *
- * Throws an error if the platform doesn't support the POSIX 128+N exit code pattern.
- * Use this when exit code semantics are critical to application logic.
- *
- * @throws {FoundryCatalogError} If platform doesn't support signal exit codes
+ * const reloadHandler = createConfigReloadHandler({
+ *   loader: () => loadConfig('./config.yaml'),
+ *   validator: (config) => validateConfigSchema(config),
+ *   onValidated: async (config) => {
+ *     logger.info('Config validated, restarting...');
+ *   },
+ *   logger: myLogger,
+ * });
  *
- * @example
- * ```typescript
- * ensureSignalExitCodesSupported();
- * // On Windows: throws with guidance
- * // On POSIX: passes through
+ * await manager.register('SIGHUP', reloadHandler);
  * ```
  */
-declare function ensureSignalExitCodesSupported(): void;
-/**
- * Ensure platform is POSIX
- *
- * Throws an error if the platform is not POSIX-compliant.
- * Use this for functionality that strictly requires POSIX signal semantics.
- *
- * @throws {FoundryCatalogError} If platform is not POSIX
- */
-declare function ensurePOSIX(): void;
+declare function createConfigReloadHandler<T = unknown>(options: ConfigReloadOptions<T>): () => Promise<void>;
 /**
- * Ensure platform is Windows
- *
- * Throws an error if the platform is not Windows.
- * Use this for Windows-specific fallback testing or functionality.
+ * Three-strikes failure tracker
  *
- * @throws {FoundryCatalogError} If platform is not Windows
+ * Tracks consecutive config reload failures and triggers alerts.
+ * Useful for detecting persistent config source issues.
  */
-declare function ensureWindows(): void;
+declare class ConfigReloadTracker {
+    private failures;
+    private lastFailureTime;
+    private readonly maxFailures;
+    private readonly logger?;
+    private readonly telemetry?;
+    constructor(options: {
+        maxFailures?: number;
+        logger?: FallbackLogger;
+        telemetry?: TelemetryEmitter;
+    });
+    /**
+     * Record a reload failure
+     *
+     * @returns true if threshold exceeded, false otherwise
+     */
+    recordFailure(): boolean;
+    /**
+     * Record a successful reload (resets counter)
+     */
+    recordSuccess(): void;
+    /**
+     * Get current failure count
+     */
+    getFailureCount(): number;
+    /**
+     * Get last failure timestamp
+     */
+    getLastFailureTime(): number | null;
+}
 
 /**
- * HTTP Signal Endpoint Helper
+ * HTTP Config Reload Endpoint Helper
  *
- * Framework-agnostic scaffold for POST /admin/signal endpoint.
- * Applications provide auth/rate-limiting; helper handles validation and execution.
+ * Framework-agnostic scaffold for POST /admin/config/reload.
+ *
+ * Unlike the signal-based reload handler, this helper is synchronous from the
+ * perspective of the caller (it returns a response object). Applications can
+ * choose whether to apply config live or initiate a restart.
  */
 
-/**
- * Signal request payload
- */
-interface SignalRequest {
-    signal: string;
+interface ConfigReloadRequest {
     reason?: string;
     correlation_id?: string;
 }
-/**
- * Signal response (success)
- */
-interface SignalResponse {
-    status: "accepted";
-    signal: string;
+interface ConfigReloadResponse {
+    status: "reloaded";
     correlation_id: string;
     message: string;
 }
-/**
- * Signal error response
- */
-interface SignalErrorResponse {
+interface ConfigReloadErrorResponse {
     status: "error";
     error: string;
     message: string;
-    valid_signals?: string[];
+    validation_errors?: Array<{
+        path: string;
+        message: string;
+    }>;
 }
-/**
- * Authentication result
- */
-interface AuthResult {
-    authenticated: boolean;
-    identity?: string;
-    reason?: string;
+type ConfigReloadRateLimitHook = (identity: string) => Promise<RateLimitResult> | RateLimitResult;
+interface ConfigReloadEndpointOptions<T = unknown> {
+    loader: ConfigLoader<T>;
+    validator?: ConfigValidator<T>;
+    onReload?: (config: T) => Promise<void> | void;
+    auth: AuthHook;
+    rateLimit?: ConfigReloadRateLimitHook;
+    logger?: FallbackLogger;
+    telemetry?: TelemetryEmitter;
 }
+declare function createConfigReloadEndpoint<T = unknown>(options: ConfigReloadEndpointOptions<T>): (payload: ConfigReloadRequest, req: unknown) => Promise<(ConfigReloadResponse | ConfigReloadErrorResponse) & {
+    statusCode?: number;
+}>;
+
 /**
- * Rate limit result
+ * HTTP Control Discovery Endpoint Helper
+ *
+ * Framework-agnostic scaffold for a control-plane discovery endpoint.
  */
-interface RateLimitResult {
-    allowed: boolean;
-    remaining?: number;
-    reset_at?: number;
+
+interface ControlEndpointDescriptor {
+    method: string;
+    path: string;
+    summary?: string;
+}
+interface ControlDiscoveryResponse {
+    status: "ok";
+    service: {
+        name: string;
+        vendor: string;
+        version: string;
+    };
+    runtime: {
+        name: string;
+        version?: string;
+        platform: string;
+        arch: string;
+    };
+    auth_summary?: string;
+    endpoints: ControlEndpointDescriptor[];
 }
+interface ControlDiscoveryErrorResponse {
+    status: "error";
+    error: string;
+    message: string;
+}
+interface ControlDiscoveryEndpointOptions {
+    identity: Identity;
+    version: string;
+    endpoints: ControlEndpointDescriptor[];
+    auth?: AuthHook;
+    authSummary?: string;
+    logger?: FallbackLogger;
+    telemetry?: TelemetryEmitter;
+}
+declare function createControlDiscoveryEndpoint(options: ControlDiscoveryEndpointOptions): (req: unknown) => Promise<(ControlDiscoveryResponse | ControlDiscoveryErrorResponse) & {
+    statusCode?: number;
+}>;
+
 /**
- * Authentication hook function
+ * Signal Handler Convenience Wrappers
  *
- * Applications must provide this to validate requests.
- * Returns authentication result with optional identity.
+ * Common signal handling patterns for shutdown, reload, and custom behaviors.
  */
-type AuthHook = (req: unknown) => Promise<AuthResult> | AuthResult;
+
 /**
- * Rate limiting hook function
+ * Register a graceful shutdown handler
  *
- * Applications may provide this to enforce rate limits.
- * Returns whether request is allowed and quota info.
- */
-type RateLimitHook = (identity: string, signal: string) => Promise<RateLimitResult> | RateLimitResult;
-/**
- * Signal endpoint options
+ * Convenience wrapper for SIGTERM and SIGINT handlers.
+ * Automatically registers both signals to the same handler.
+ *
+ * @param manager - Signal manager instance
+ * @param handler - Shutdown handler function
+ * @param options - Handler options
+ *
+ * @example
+ * ```typescript
+ * await onShutdown(manager, async () => {
+ *   await closeDatabase();
+ *   await flushLogs();
+ * });
+ * ```
  */
-interface SignalEndpointOptions {
-    /**
-     * Signal manager instance
-     */
-    manager: SignalManager;
-    /**
-     * Authentication hook (required)
-     */
-    auth: AuthHook;
-    /**
-     * Rate limiting hook (optional)
-     */
-    rateLimit?: RateLimitHook;
-    /**
-     * Logger for endpoint events
-     */
-    logger?: FallbackLogger;
-    /**
-     * Telemetry emitter
-     */
-    telemetry?: TelemetryEmitter;
-    /**
-     * Allowed signals (default: all catalog signals)
-     */
-    allowedSignals?: string[];
-}
+declare function onShutdown(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
 /**
- * Create a framework-agnostic signal endpoint handler
+ * Register a config reload handler
  *
- * Returns an async function that processes signal requests.
- * Applications wire this to their HTTP framework (Express, Fastify, etc.)
+ * Convenience wrapper for SIGHUP handler.
+ * Only registers on POSIX platforms (SIGHUP not supported on Windows).
  *
- * @param options - Endpoint configuration
+ * @param manager - Signal manager instance
+ * @param handler - Reload handler function
+ * @param options - Handler options
  *
- * @example Express
+ * @example
  * ```typescript
- * const handler = createSignalEndpoint({
- *   manager,
- *   auth: async (req) => {
- *     const token = req.headers.authorization?.split(' ')[1];
- *     return { authenticated: token === process.env.ADMIN_TOKEN };
- *   },
- * });
- *
- * app.post('/admin/signal', async (req, res) => {
- *   const result = await handler(req.body, req);
- *   res.status(result.status === 'accepted' ? 202 : result.statusCode || 400)
- *      .json(result);
+ * await onReload(manager, async () => {
+ *   const newConfig = await loadConfig();
+ *   await validateConfig(newConfig);
+ *   process.exit(129); // Exit for restart
  * });
  * ```
+ */
+declare function onReload(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+/**
+ * Register a custom handler for SIGUSR1
  *
- * @example Fastify
- * ```typescript
- * const handler = createSignalEndpoint({ manager, auth });
+ * Common use cases: toggle debug logging, reopen log files, dump statistics.
  *
- * fastify.post('/admin/signal', async (request, reply) => {
- *   const result = await handler(request.body, request);
- *   reply.status(result.status === 'accepted' ? 202 : 400).send(result);
+ * @param manager - Signal manager instance
+ * @param handler - Custom handler function
+ * @param options - Handler options
+ *
+ * @example
+ * ```typescript
+ * await onUSR1(manager, async () => {
+ *   logger.info('SIGUSR1 received - reopening log files');
+ *   await reopenLogFiles();
  * });
  * ```
  */
-declare function createSignalEndpoint(options: SignalEndpointOptions): (payload: SignalRequest, req: unknown) => Promise<(SignalResponse | SignalErrorResponse) & {
-    statusCode?: number;
-}>;
+declare function onUSR1(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
 /**
- * Create a simple bearer token auth hook
+ * Register a custom handler for SIGUSR2
  *
- * Validates requests against a static token.
- * For production, use mTLS or more robust auth.
+ * Common use cases: trigger profiling, rotate credentials, toggle verbose mode.
  *
- * @param expectedToken - Expected bearer token
+ * @param manager - Signal manager instance
+ * @param handler - Custom handler function
+ * @param options - Handler options
  *
  * @example
  * ```typescript
- * const auth = createBearerTokenAuth(process.env.ADMIN_TOKEN);
- * const handler = createSignalEndpoint({ manager, auth });
+ * await onUSR2(manager, async () => {
+ *   logger.info('SIGUSR2 received - toggling debug mode');
+ *   toggleDebugMode();
+ * });
  * ```
  */
-declare function createBearerTokenAuth(expectedToken: string): AuthHook;
+declare function onUSR2(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
 /**
- * Create a simple in-memory rate limiter
+ * Register an emergency quit handler
  *
- * Tracks requests per identity with sliding window.
- * For production, use Redis or distributed rate limiting.
+ * Convenience wrapper for SIGQUIT (immediate exit, no cleanup).
  *
- * @param requestsPerMinute - Max requests per minute per identity
+ * @param manager - Signal manager instance
+ * @param handler - Emergency quit handler
+ * @param options - Handler options
  *
  * @example
  * ```typescript
- * const rateLimit = createSimpleRateLimiter(10); // 10 req/min
- * const handler = createSignalEndpoint({ manager, auth, rateLimit });
+ * await onEmergencyQuit(manager, async () => {
+ *   logger.error('SIGQUIT received - emergency exit');
+ *   process.exit(131);
+ * });
  * ```
  */
-declare function createSimpleRateLimiter(requestsPerMinute: number): RateLimitHook;
-
+declare function onEmergencyQuit(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
 /**
- * Configuration Reload Helpers
+ * Register handlers for all common shutdown signals
  *
- * Implements restart-based config reload pattern with mandatory schema validation.
- * Per Crucible standard: validate before restart, reject invalid configs without disruption.
- */
-
-/**
- * Configuration validator function type
+ * Registers the same handler for SIGTERM, SIGINT, and SIGQUIT.
+ * Useful for applications that want consistent shutdown behavior.
  *
- * Applications provide this function to validate new config against schema.
- * Should return validation result with errors if invalid.
- */
-type ConfigValidator<T = unknown> = (config: T) => Promise<ConfigValidationResult> | ConfigValidationResult;
-/**
- * Configuration validation result
+ * @param manager - Signal manager instance
+ * @param handler - Shutdown handler function
+ * @param options - Handler options
  */
-interface ConfigValidationResult {
-    valid: boolean;
-    errors?: Array<{
-        path: string;
-        message: string;
-    }>;
-}
+declare function onAnyShutdown(manager: SignalManager, handler: SignalHandler, options?: HandlerOptions): Promise<void>;
+
 /**
- * Configuration loader function type
+ * Double-Tap Signal Handling
  *
- * Applications provide this function to load new config from disk/environment.
+ * Implements Ctrl+C double-tap pattern for graceful shutdown with force-quit option.
+ * Per Crucible standard: 2-second window, immediate exit on second signal.
  */
-type ConfigLoader<T = unknown> = () => Promise<T> | T;
+
 /**
- * Config reload options
+ * Double-tap configuration
  */
-interface ConfigReloadOptions<T = unknown> {
-    /**
-     * Config loader function
-     */
-    loader: ConfigLoader<T>;
-    /**
-     * Schema validator function
-     */
-    validator: ConfigValidator<T>;
+interface DoubleTapConfig {
     /**
-     * Callback invoked after successful validation, before exit
-     * Use for cleanup, logging, etc.
+     * Debounce window in milliseconds (default: 2000ms per Crucible standard)
      */
-    onValidated?: (config: T) => void | Promise<void>;
+    windowMs?: number;
     /**
-     * Exit code for successful reload (default: 129 for SIGHUP)
+     * Exit code for forced double-tap exit (default: 130 for SIGINT)
      */
     exitCode?: number;
     /**
-     * Logger for reload events
+     * Message to display on first signal (default: from catalog)
      */
-    logger?: FallbackLogger;
+    hintMessage?: string;
     /**
-     * Telemetry emitter
+     * Logger for double-tap events
      */
-    telemetry?: TelemetryEmitter;
+    logger?: FallbackLogger;
     /**
-     * Test mode (prevents process.exit)
+     * Enable test mode (prevents process.exit calls)
      */
     testMode?: boolean;
 }
 /**
- * Config reload result (for testing)
+ * Double-tap state tracker
  */
-interface ConfigReloadResult {
-    reloaded: boolean;
-    validationErrors?: Array<{
-        path: string;
-        message: string;
-    }>;
-    error?: Error;
+interface DoubleTapState {
+    firstTapTime: number | null;
+    windowMs: number;
+    exitCode: number;
+    hintMessage: string;
+    logger?: FallbackLogger;
+    testMode: boolean;
 }
 /**
- * Create a config reload handler with schema validation
+ * Create double-tap state tracker for a signal
  *
- * Returns a signal handler function that implements restart-based reload:
- * 1. Load new config
- * 2. Validate against schema (mandatory)
- * 3. If invalid: log errors, continue with current config
- * 4. If valid: invoke callback, exit for restart
+ * @param signalName - Signal name (typically "SIGINT")
+ * @param config - Double-tap configuration
+ */
+declare function createDoubleTapTracker(signalName: string, config?: DoubleTapConfig): Promise<DoubleTapState>;
+/**
+ * Handle double-tap signal logic
  *
- * @param options - Reload configuration
+ * Returns true if this is the second tap (force-quit), false if first tap.
+ * Updates state to track timing between taps.
  *
- * @example
- * ```typescript
- * const reloadHandler = createConfigReloadHandler({
- *   loader: () => loadConfig('./config.yaml'),
- *   validator: (config) => validateConfigSchema(config),
- *   onValidated: async (config) => {
- *     logger.info('Config validated, restarting...');
- *   },
- *   logger: myLogger,
- * });
+ * @param state - Double-tap state tracker
+ * @returns true if force-quit should proceed, false if graceful shutdown
+ */
+declare function handleDoubleTap(state: DoubleTapState): boolean;
+/**
+ * Reset double-tap state
  *
- * await manager.register('SIGHUP', reloadHandler);
- * ```
+ * Called when graceful shutdown completes before second tap.
  */
-declare function createConfigReloadHandler<T = unknown>(options: ConfigReloadOptions<T>): () => Promise<void>;
+declare function resetDoubleTap(state: DoubleTapState): void;
 /**
- * Three-strikes failure tracker
+ * Check if currently within double-tap window
  *
- * Tracks consecutive config reload failures and triggers alerts.
- * Useful for detecting persistent config source issues.
+ * Useful for testing and debugging.
  */
-declare class ConfigReloadTracker {
-    private failures;
-    private lastFailureTime;
-    private readonly maxFailures;
-    private readonly logger?;
-    private readonly telemetry?;
-    constructor(options: {
-        maxFailures?: number;
-        logger?: FallbackLogger;
-        telemetry?: TelemetryEmitter;
-    });
-    /**
-     * Record a reload failure
-     *
-     * @returns true if threshold exceeded, false otherwise
-     */
-    recordFailure(): boolean;
-    /**
-     * Record a successful reload (resets counter)
-     */
-    recordSuccess(): void;
-    /**
-     * Get current failure count
-     */
-    getFailureCount(): number;
+declare function isWithinWindow(state: DoubleTapState): boolean;
+/**
+ * Get time remaining in double-tap window (milliseconds)
+ *
+ * Returns null if not in a window, otherwise milliseconds remaining.
+ */
+declare function getWindowTimeRemaining(state: DoubleTapState): number | null;
+
+/**
+ * Signal Support Guards
+ *
+ * Validation functions that throw actionable errors when signals are unsupported.
+ * Used to fail-fast with clear operational guidance.
+ */
+/**
+ * Guard options
+ */
+interface GuardOptions {
     /**
-     * Get last failure timestamp
+     * Include platform-specific operational guidance in error message
      */
-    getLastFailureTime(): number | null;
+    includeGuidance?: boolean;
 }
+/**
+ * Ensure a signal is supported on the current platform
+ *
+ * Throws an error with actionable guidance if the signal is not supported.
+ * Use this as a guard at the start of signal registration functions.
+ *
+ * @param signalName - Signal name (e.g., "SIGTERM") or id (e.g., "term")
+ * @param options - Guard configuration
+ * @throws {FoundryCatalogError} If signal is not found or not supported
+ *
+ * @example
+ * ```typescript
+ * await ensureSupported("SIGHUP");
+ * // On Windows: throws with HTTP fallback guidance
+ * // On POSIX: passes through
+ * ```
+ */
+declare function ensureSupported(signalName: string, options?: GuardOptions): Promise<void>;
+/**
+ * Ensure platform supports signal-based exit codes
+ *
+ * Throws an error if the platform doesn't support the POSIX 128+N exit code pattern.
+ * Use this when exit code semantics are critical to application logic.
+ *
+ * @throws {FoundryCatalogError} If platform doesn't support signal exit codes
+ *
+ * @example
+ * ```typescript
+ * ensureSignalExitCodesSupported();
+ * // On Windows: throws with guidance
+ * // On POSIX: passes through
+ * ```
+ */
+declare function ensureSignalExitCodesSupported(): void;
+/**
+ * Ensure platform is POSIX
+ *
+ * Throws an error if the platform is not POSIX-compliant.
+ * Use this for functionality that strictly requires POSIX signal semantics.
+ *
+ * @throws {FoundryCatalogError} If platform is not POSIX
+ */
+declare function ensurePOSIX(): void;
+/**
+ * Ensure platform is Windows
+ *
+ * Throws an error if the platform is not Windows.
+ * Use this for Windows-specific fallback testing or functionality.
+ *
+ * @throws {FoundryCatalogError} If platform is not Windows
+ */
+declare function ensureWindows(): void;
 
-export { type AuthHook, type AuthResult, BehaviorInfo, type ConfigLoader, type ConfigReloadOptions, type ConfigReloadResult, ConfigReloadTracker, type ConfigValidationResult, type ConfigValidator, type DoubleTapConfig, type DoubleTapState, FallbackLogger, type GuardOptions, HandlerOptions, type Platform, type PlatformCapabilities, type RateLimitHook, type RateLimitResult, SignalCatalog, type SignalEndpointOptions, type SignalErrorResponse, SignalHandler, SignalInfo, SignalManager, type SignalRequest, type SignalResponse, TelemetryEmitter, createBearerTokenAuth, createConfigReloadHandler, createDoubleTapTracker, createSignalEndpoint, createSimpleRateLimiter, ensurePOSIX, ensureSignalExitCodesSupported, ensureSupported, ensureWindows, getBehavior, getPlatform, getPlatformCapabilities, getSignal, getSignalCatalog, getSignalNumber, getSignalsVersion, getWindowTimeRemaining, getWindowsEvent, handleDoubleTap, isPOSIX, isWindows, isWithinWindow, listBehaviors, listSignals, onAnyShutdown, onEmergencyQuit, onReload, onShutdown, onUSR1, onUSR2, resetDoubleTap, supportsSignal, supportsSignalExitCodes };
+export { type AuthHook, type AuthResult, BehaviorInfo, type ConfigLoader, type ConfigReloadEndpointOptions, type ConfigReloadErrorResponse, type ConfigReloadOptions, type ConfigReloadRateLimitHook, type ConfigReloadRequest, type ConfigReloadResponse, type ConfigReloadResult, ConfigReloadTracker, type ConfigValidationResult, type ConfigValidator, type ControlDiscoveryEndpointOptions, type ControlDiscoveryErrorResponse, type ControlDiscoveryResponse, type ControlEndpointDescriptor, type DoubleTapConfig, type DoubleTapState, FallbackLogger, type GuardOptions, HandlerOptions, type Platform, type PlatformCapabilities, type RateLimitHook, type RateLimitResult, SignalCatalog, type SignalEndpointOptions, type SignalErrorResponse, SignalHandler, SignalInfo, SignalManager, type SignalRequest, type SignalResponse, TelemetryEmitter, createBearerTokenAuth, createConfigReloadEndpoint, createConfigReloadHandler, createControlDiscoveryEndpoint, createDoubleTapTracker, createSignalEndpoint, createSimpleRateLimiter, ensurePOSIX, ensureSignalExitCodesSupported, ensureSupported, ensureWindows, getBehavior, getPlatform, getPlatformCapabilities, getSignal, getSignalCatalog, getSignalNumber, getSignalsVersion, getWindowTimeRemaining, getWindowsEvent, handleDoubleTap, isPOSIX, isWindows, isWithinWindow, listBehaviors, listSignals, onAnyShutdown, onEmergencyQuit, onReload, onShutdown, onUSR1, onUSR2, resetDoubleTap, supportsSignal, supportsSignalExitCodes };