@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/scheduler/console.js

@@ -30,7 +30,7 @@ export async function runSchedulerConsole(options, argv = process.argv.slice(2))
         case 'scheduler:list':
             await runWithApp(options, app => {
                 for (const definition of app.scheduler.definitions()) {
-                    console.log(`${definition.name}\t${definition.kind}\tdaily at ${definition.frequency.time}\t${definition.timezone}${definition.jobName ? `\t${definition.jobName}` : ''}`);
+                    console.log(`${definition.name}\t${definition.kind}\t${definition.frequency.type === 'minute' ? 'every minute' : definition.frequency.type === 'hourly' ? 'hourly (UTC)' : `daily at ${definition.frequency.time}`}\t${definition.timezone}${definition.jobName ? `\t${definition.jobName}` : ''}`);
                 }
             });
             return;
@@ -112,6 +112,8 @@ async function workScheduler(options) {
     const app = options.app();
     app.scheduler.definitions();
     const worker = new SchedulerWorker(app.scheduler, {
+        onTick: options.onTick,
+        checkpoint: options.checkpoint,
         logger: app.log ? schedulerLogger(app.log) : undefined,
     });
     let shuttingDown = false;

package/dist/scheduler/contracts/Schedule.d.ts

@@ -0,0 +1,19 @@
+import type { ScheduledJob } from '../ScheduledJob.js';
+import type { ScheduledCall } from '../ScheduledCall.js';
+import type { ScheduledJobSource, ScheduledCallHandler, ScheduledTaskDefinition } from './Scheduler.js';
+/** Fluent declaration surface shared by the host scheduler and app-owned schedule.ts files. */
+export interface Schedule {
+    /** Declares queued work; workers execute the expensive operation. */
+    job(source: ScheduledJobSource): ScheduledJob;
+    /** Declares a short inline operation executed by the scheduler. */
+    call(handler: ScheduledCallHandler): ScheduledCall;
+}
+/** Ownership handle for one group's registrations. Closing removes only that group. */
+export interface ScheduleRegistration {
+    /** Browser-safe definitions, including the owning app identifier. */
+    definitions: ScheduledTaskDefinition[];
+    /** Idempotently removes the group's runtime definitions. Durable history remains. */
+    close(): void;
+}
+/** Wraps one complete occurrence, including claiming and dispatch, in the owner's lifecycle gate. */
+export type ScheduleRunner = (operation: () => Promise<void>) => Promise<void>;

package/dist/scheduler/contracts/Schedule.js

@@ -0,0 +1 @@
+export {};

package/dist/scheduler/contracts/Scheduler.d.ts

@@ -1,4 +1,4 @@
-import type { QueueableJob } from '../../queue/index.js';
+import type { QueueableJobContract as QueueableJob } from '../../queue/index.js';
 /**
  * Supported scheduled task kinds.
  */
@@ -8,24 +8,36 @@ export type ScheduledTaskKind = 'job' | 'call';
  */
 export type ScheduledOccurrenceStatus = 'claimed' | 'queued' | 'running' | 'retrying' | 'deferred' | 'succeeded' | 'failed';
 /**
- * Daily frequency supported by the initial scheduler implementation.
+ * Daily frequency interpreted in the configured timezone.
  */
 export interface DailyScheduleFrequency {
-    /** Frequency discriminator reserved for future schedule types. */
+    /** Frequency discriminator. */
     type: 'daily';
     /** Local wall-clock time in 24-hour HH:mm format. */
     time: string;
 }
+/** Runs once for each evaluated UTC minute, including catch-up after downtime. */
+export interface MinuteScheduleFrequency {
+    type: 'minute';
+}
+/** Supported calendar frequencies; durable claims remain scoped to UTC minutes. */
+export type ScheduleFrequency = DailyScheduleFrequency | MinuteScheduleFrequency | HourlyScheduleFrequency;
+/** Runs at minute zero of each UTC hour, including catch-up; independent of local daylight-saving changes. */
+export interface HourlyScheduleFrequency {
+    type: 'hourly';
+}
 /**
  * Normalized public description of one registered schedule.
  */
 export interface ScheduledTaskDefinition {
+    /** App or other runtime group that owns this registration; absent for host declarations. */
+    owner?: string;
     /** Stable task name used for deduplication and history. */
     name: string;
     /** Whether the task dispatches a job or executes an inline callback. */
     kind: ScheduledTaskKind;
-    /** Daily frequency and local wall-clock time. */
-    frequency: DailyScheduleFrequency;
+    /** Minute/hour cadence or daily local wall-clock time. */
+    frequency: ScheduleFrequency;
     /** IANA timezone used to interpret the frequency. */
     timezone: string;
     /** Durable queue job name when known without invoking a factory. */
@@ -49,7 +61,7 @@ export interface ScheduledJobClass {
      * @param data - JSON-safe queue payload.
      * @returns Rehydrated job instance.
      */
-    fromJSON(data: Record<string, unknown>): QueueableJob;
+    fromJSON(data: Record<string, unknown>): QueueableJob | Promise<QueueableJob>;
 }
 /**
  * Zero-argument class or fresh-job factory accepted by Scheduler.job().

package/dist/scheduler/contracts/SchedulerCheckpoint.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Application-owned durable progress for one registered scheduler.
+ * Share this checkpoint between replacement processes using the same definitions.
+ */
+export interface SchedulerCheckpoint {
+    /**
+     * Loads the last fully evaluated UTC minute. On first use, atomically persist
+     * and return the minute immediately before firstMinute, establishing the start
+     * of coverage before any scheduled work is attempted.
+     *
+     * @param firstMinute - Current UTC minute at the worker's first startup.
+     * @returns Last evaluated minute, or the newly established starting boundary.
+     */
+    load(firstMinute: Date): Promise<Date>;
+    /**
+     * Advances progress after all events in a minute have been considered.
+     * Concurrent saves must never move the stored minute backwards. A rejected
+     * save causes the worker to reconsider that minute using occurrence deduplication.
+     *
+     * @param evaluatedFor - UTC minute whose complete evaluation was recorded.
+     */
+    save(evaluatedFor: Date): Promise<void>;
+}

package/dist/scheduler/contracts/SchedulerCheckpoint.js

@@ -0,0 +1 @@
+export {};

package/dist/scheduler/contracts/SchedulerConsole.d.ts

@@ -1,5 +1,6 @@
 import type { Scheduler } from '../Scheduler.js';
 import type { Logger } from '../../logging/index.js';
+import type { SchedulerWorkerOptions } from './SchedulerWorker.js';
 /**
  * Parsed scheduler command name, positional arguments, and long options.
  */
@@ -26,6 +27,10 @@ export interface SchedulerConsoleApp {
  * Application hooks and help customisation for scheduler console commands.
  */
 export interface SchedulerConsoleOptions {
+    /** Called after a successful scheduler worker tick for application-owned health reporting. */
+    onTick?: SchedulerWorkerOptions['onTick'];
+    /** Durable worker progress, initialized only by scheduler:work. One-off commands leave it alone. */
+    checkpoint?: SchedulerWorkerOptions['checkpoint'];
     /** Resolves the active application instance after bootstrap. */
     app: () => SchedulerConsoleApp;
     /** Prepares schema, queue jobs, and schedule definitions. */

package/dist/scheduler/contracts/SchedulerWorker.d.ts

@@ -1,4 +1,5 @@
-import type { SchedulerLogger } from './Scheduler.js';
+import type { SchedulerLogger, SchedulerRunResult } from './Scheduler.js';
+import type { SchedulerCheckpoint } from './SchedulerCheckpoint.js';
 /**
  * Abort-aware sleep function used by the long-running scheduler worker.
  */
@@ -7,6 +8,10 @@ export type SchedulerSleep = (delayMs: number, signal: AbortSignal) => Promise<v
  * Runtime dependencies and logging overrides for SchedulerWorker.
  */
 export interface SchedulerWorkerOptions {
+    /** Durable coverage across process restarts; without it, coverage starts in the current process. */
+    checkpoint?: SchedulerCheckpoint;
+    /** Records a successful evaluation and its actual minute; hook failures retry that minute. */
+    onTick?: (result: SchedulerRunResult) => Promise<void>;
     /** Clock used to align and evaluate scheduler ticks. */
     now?: () => Date;
     /** Abort-aware sleeper used between minute boundaries. */

package/dist/scheduler/contracts/index.d.ts

@@ -1,3 +1,5 @@
 export * from './Scheduler.js';
 export * from './SchedulerConsole.js';
 export * from './SchedulerWorker.js';
+export * from './SchedulerCheckpoint.js';
+export * from './Schedule.js';

package/dist/scheduler/contracts/index.js

@@ -1,3 +1,5 @@
 export * from './Scheduler.js';
 export * from './SchedulerConsole.js';
 export * from './SchedulerWorker.js';
+export * from './SchedulerCheckpoint.js';
+export * from './Schedule.js';

package/dist/scheduler/index.d.ts

@@ -7,3 +7,4 @@ export * from './ScheduledJob.js';
 export * from './ScheduledOccurrence.js';
 export * from './ScheduledOccurrenceRecorder.js';
 export * from './SchedulerWorker.js';
+export * from './SchedulerCheckpointRecord.js';

package/dist/scheduler/index.js

@@ -7,3 +7,4 @@ export * from './ScheduledJob.js';
 export * from './ScheduledOccurrence.js';
 export * from './ScheduledOccurrenceRecorder.js';
 export * from './SchedulerWorker.js';
+export * from './SchedulerCheckpointRecord.js';

package/dist/server/App.d.ts

@@ -1,9 +1,16 @@
+import type { WebSocketServiceOptions } from '../websocket/index.js';
 import type { Knex } from 'knex';
 import { Ai, type AIOptions } from '../ai/index.js';
+import { Apps, type AppDefinitions, type AppServices, type InstalledApps } from '../apps/index.js';
 import { Auth, type AuthOptions } from '../auth/index.js';
 import { Cache } from '../cache/index.js';
 import { Config, type ConfigValues } from '../config/index.js';
 import { Database, type DatabaseOptions } from '../db/index.js';
+import { InApp, type InAppOptions } from '../in-app/index.js';
+import { Health, type HealthOptions } from '../health/index.js';
+import { Mail, type MailOptions } from '../mail/index.js';
+import { Notifications } from '../notifications/index.js';
+import { WebSockets } from '../websocket/index.js';
 import { Events } from '../events/index.js';
 import { UrlGenerator, type UrlGeneratorOptions } from '../url/index.js';
 import { Queue, type QueueOptions } from '../queue/index.js';
@@ -15,7 +22,9 @@ import { Serializer, type SerializerOptions } from '../serialization/index.js';
 import { MediaManager } from '../media/index.js';
 import { RequestContext } from './RequestContext.js';
 /** Application root, service configuration and optional dependencies supplied at bootstrap. */
-export interface AppOptions {
+export interface AppOptions<TApps extends AppDefinitions = {}> {
+    /** Optional explicit composition. Omit to discover local apps and marked npm dependencies. */
+    apps?: TApps;
     /** App root as a path or file URL; defaults to the working directory at construction. */
     directory?: string | URL;
     /** Provider adapters and extensible ActiveRecord models for app().ai. */
@@ -29,6 +38,14 @@ export interface AppOptions {
     /** Canonical application URL configuration used across all runtimes. */
     url?: UrlGeneratorOptions;
     queue?: QueueOptions;
+    /** Authorization policy for application-scoped in-app inboxes. */
+    inApp?: InAppOptions;
+    /** Optional shared transport for channel events from API and worker processes. */
+    webSockets?: WebSocketServiceOptions;
+    /** Application health identity and initial component checks. */
+    health?: HealthOptions;
+    /** Provider-neutral mail delivery used directly and by app().notifications. */
+    mail?: MailOptions;
     /** Serializable classes and ActiveRecord models registered with app().serializer. */
     serializer?: SerializerOptions;
     storage?: StorageOptions;
@@ -39,8 +56,8 @@ export interface AppOptions {
  * Keep this as the place where top-level framework capabilities are discovered
  * and wired, not where domain logic itself accumulates.
  */
-export declare class App {
-    protected readonly options: AppOptions;
+export declare class App<TApps extends AppDefinitions = {}> {
+    protected readonly options: AppOptions<TApps>;
     private readonly services;
     /** Absolute app root used for conventional server paths, independent of later working-directory changes. */
     readonly directory: string;
@@ -49,9 +66,21 @@ export declare class App {
      *
      * @param options - Framework services and application configuration.
      */
-    constructor(options?: AppOptions);
+    constructor(options?: AppOptions<TApps>);
+    /** Returns the app composition registry with optional, inferred public service accessors. */
+    get apps(): Apps<TApps> & AppServices<TApps>;
     /** Returns the lazy database service with this app's connection, model registry and root directory. */
     get db(): Database;
+    /** Returns the durable inbox service using the configured Auth identity model. */
+    get inApp(): InApp;
+    /** Returns the extensible application health registry. */
+    get health(): Health;
+    /** Returns the provider-neutral mail service configured for this application. */
+    get mail(): Mail;
+    /** Returns the notification coordinator for application-owned channel renderers. */
+    get notifications(): Notifications<any>;
+    /** Returns authenticated WebSocket endpoints owned by this application's lifecycle. */
+    get webSockets(): WebSockets;
     get auth(): Auth<any>;
     get requestContext(): RequestContext;
     /** Returns the application AI service with durable request and conversation history. */
@@ -139,3 +168,6 @@ export declare class App {
     private resolveDbConnection;
     private resolveDatabaseOptions;
 }
+/** Optional discovered app services, generated from root App.ts classes by DB3 tooling. */
+export interface App<TApps extends AppDefinitions = {}> extends InstalledApps {
+}

package/dist/server/App.js

@@ -1,11 +1,18 @@
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Ai } from '../ai/index.js';
+import { Apps } from '../apps/index.js';
 import { Auth, } from '../auth/index.js';
 import { Cache, } from '../cache/index.js';
 import { Config, } from '../config/index.js';
 import { db as defaultDb, destroyDatabase, } from '../db/connection.js';
 import { Database, } from '../db/index.js';
+import { InApp } from '../in-app/index.js';
+import { Health } from '../health/index.js';
+import { Mail } from '../mail/index.js';
+import { Notifications } from '../notifications/index.js';
+import { WebSockets } from '../websocket/index.js';
+import { UserIdentity } from '../auth/index.js';
 import { Events } from '../events/index.js';
 import { UrlGenerator } from '../url/index.js';
 import { Queue, } from '../queue/index.js';
@@ -36,16 +43,42 @@ export class App {
     constructor(options = {}) {
         this.options = options;
         this.directory = resolve(options.directory instanceof URL ? fileURLToPath(options.directory) : options.directory ?? process.cwd());
+        if (options.apps)
+            void this.apps;
         setActiveApp(this);
         if (this.config.has('security'))
             void this.security;
     }
+    /** Returns the app composition registry with optional, inferred public service accessors. */
+    get apps() {
+        return this.service('apps', () => new Apps(this, this.options.apps));
+    }
     /** Returns the lazy database service with this app's connection, model registry and root directory. */
     get db() {
         return this.service('db', () => {
             return new Database(this.resolveDbConnection(), this.resolveDatabaseOptions(), this.directory);
         });
     }
+    /** Returns the durable inbox service using the configured Auth identity model. */
+    get inApp() {
+        return this.service('inApp', () => new InApp(this.options.inApp, this.options.auth?.identityModel ?? UserIdentity));
+    }
+    /** Returns the extensible application health registry. */
+    get health() {
+        return this.service('health', () => new Health(this.options.health));
+    }
+    /** Returns the provider-neutral mail service configured for this application. */
+    get mail() {
+        return this.service('mail', () => new Mail(this.options.mail));
+    }
+    /** Returns the notification coordinator for application-owned channel renderers. */
+    get notifications() {
+        return this.service('notifications', () => new Notifications(this.inApp, this.mail, this.options.auth?.identityModel ?? UserIdentity));
+    }
+    /** Returns authenticated WebSocket endpoints owned by this application's lifecycle. */
+    get webSockets() {
+        return this.service('webSockets', () => new WebSockets(this, this.options.webSockets));
+    }
     get auth() {
         return this.service('auth', () => new Auth({
             ...this.options.auth,
@@ -86,7 +119,7 @@ export class App {
      * @returns Pino-backed logging service with app lifecycle ownership.
      */
     get log() {
-        return this.service('log', () => new Log(this.options.log));
+        return this.service('log', () => new Log(this.options.log, () => this.mail));
     }
     /**
      * Returns the canonical application URL generator.
@@ -111,7 +144,10 @@ export class App {
         });
     }
     get queue() {
-        return this.service('queue', () => new Queue(this.db, this.options.queue));
+        return this.service('queue', () => new Queue(this.db, {
+            onLifecycleError: failure => this.log.error({ err: failure.error, component: 'queue', source: failure.source, hook: failure.hook, jobId: failure.event.jobId, jobName: failure.event.jobName, action: failure.event.action }, 'Queue lifecycle handler failed'),
+            ...this.options.queue,
+        }));
     }
     /**
      * Returns the application scheduler and attaches queue lifecycle recording.
@@ -179,15 +215,29 @@ export class App {
      * Closes shared resources owned by the default app.
      */
     async close() {
+        const errors = [];
+        /** Continues releasing host resources when an app or transport disposer fails. */
+        const release = async (cleanup) => {
+            try {
+                await cleanup();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        };
+        await release(() => this.services.get('apps')?.close());
+        await release(() => this.services.get('webSockets')?.close());
         clearActiveApp(this);
-        this.services.get('scheduler')?.close();
-        this.services.get('events')?.clear();
-        await this.services.get('cache')?.close();
-        await this.services.get('log')?.close();
+        await release(() => this.services.get('scheduler')?.close());
+        await release(() => this.services.get('events')?.clear());
+        await release(() => this.services.get('cache')?.close());
+        await release(() => this.services.get('log')?.close());
         if (!this.options.db) {
-            await destroyDatabase();
+            await release(() => destroyDatabase());
         }
         this.services.clear();
+        if (errors.length)
+            throw new AggregateError(errors, 'Application shutdown failed.');
     }
     resolveDbConnection() {
         if (!this.options.db) {

package/dist/server/contracts/HttpErrorHandlerOptions.d.ts

@@ -0,0 +1,29 @@
+import type { FastifyRequest } from 'fastify';
+/** Application-owned mapping for deliberate HTTP failures, never arbitrary provider errors. */
+export interface HttpErrorResponse {
+    /** HTTP failure status between 400 and 599. */
+    statusCode: number;
+    /** Public client-error copy. Production 5xx bodies are always replaced. */
+    body: {
+        error: string;
+        message: string;
+    };
+}
+/** Server-only diagnostics passed to an application's support-record store. */
+export interface HttpServerErrorContext {
+    /** Request whose logger and ID correlate the failure. */
+    request: FastifyRequest;
+    /** Actual HTTP response status. */
+    statusCode: number;
+    /** Framework-generated reference shared by logs and the public response. */
+    reference: string;
+    /** Explicitly returned error body, if no exception reached the handler. Never public in production. */
+    responseBody?: string;
+}
+/** Application integration points for the framework's HTTP error boundary. */
+export interface HttpErrorHandlerOptions {
+    /** Map only known application errors; returning undefined uses framework classification. */
+    mapError?: (error: unknown) => HttpErrorResponse | undefined;
+    /** Retain extra support records after framework logging. Failures here cannot leak diagnostics. */
+    onServerError?: (error: unknown, context: HttpServerErrorContext) => void;
+}

package/dist/server/contracts/HttpErrorHandlerOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/server/contracts/index.d.ts

@@ -0,0 +1 @@
+export type { HttpErrorHandlerOptions, HttpErrorResponse, HttpServerErrorContext } from './HttpErrorHandlerOptions.js';

package/dist/server/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/server/index.d.ts

@@ -1,3 +1,7 @@
+export * from './contracts/index.js';
+export { publicServerErrorMessage } from './publicServerErrorMessage.js';
+export { registerBrowserJsonFormatting } from './registerBrowserJsonFormatting.js';
+export { registerHttpErrorHandler } from './registerHttpErrorHandler.js';
 export { App, type AppOptions, } from './App.js';
 export { app, activeAppDatabase, activeAppRequestContext, clearActiveApp, setActiveApp, type AppDatabaseProvider, } from './appContext.js';
 export { RequestContext, type RequestContextValues, } from './RequestContext.js';

package/dist/server/index.js

@@ -1,3 +1,7 @@
+export * from './contracts/index.js';
+export { publicServerErrorMessage } from './publicServerErrorMessage.js';
+export { registerBrowserJsonFormatting } from './registerBrowserJsonFormatting.js';
+export { registerHttpErrorHandler } from './registerHttpErrorHandler.js';
 export { App, } from './App.js';
 export { app, activeAppDatabase, activeAppRequestContext, clearActiveApp, setActiveApp, } from './appContext.js';
 export { RequestContext, } from './RequestContext.js';

package/dist/server/publicServerErrorMessage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns internal diagnostics only for explicitly named development environments.
+ *
+ * Production, staging, unknown and unset environments fail closed. This policy
+ * applies to every exception, without relying on database-specific signatures.
+ *
+ * @param error - Original server-side failure; never modified by this function.
+ * @param environment - Runtime environment, defaulting to NODE_ENV.
+ * @returns Detailed development message or the generic public failure message.
+ */
+export declare function publicServerErrorMessage(error: unknown, environment?: string | undefined): string;

package/dist/server/publicServerErrorMessage.js

@@ -0,0 +1,16 @@
+import { isDevelopmentEnvironment, unknownErrorMessage } from '@db3.ai/pure';
+/**
+ * Returns internal diagnostics only for explicitly named development environments.
+ *
+ * Production, staging, unknown and unset environments fail closed. This policy
+ * applies to every exception, without relying on database-specific signatures.
+ *
+ * @param error - Original server-side failure; never modified by this function.
+ * @param environment - Runtime environment, defaulting to NODE_ENV.
+ * @returns Detailed development message or the generic public failure message.
+ */
+export function publicServerErrorMessage(error, environment = process.env.NODE_ENV) {
+    return isDevelopmentEnvironment(environment)
+        ? unknownErrorMessage(error) || 'Unexpected server error'
+        : 'Unexpected server error';
+}

package/dist/server/registerBrowserJsonFormatting.d.ts

@@ -0,0 +1,16 @@
+import type { FastifyInstance } from 'fastify';
+/**
+ * Formats small JSON responses for browser page navigations across a Fastify server.
+ *
+ * Register before routes and plugins so their replies inherit the send hook. The
+ * hook runs after Fastify response-schema serialization and only reformats GET
+ * requests with `Sec-Fetch-Mode: navigate`. Browser fetches, other methods,
+ * streams, encoded bodies, and responses with integrity headers retain their
+ * original bytes. Large JSON bodies remain compact to bound browser-only work.
+ *
+ * @param server - Fastify server that owns the response lifecycle.
+ * @example
+ * const server = Fastify();
+ * registerBrowserJsonFormatting(server);
+ */
+export declare function registerBrowserJsonFormatting(server: FastifyInstance): void;

package/dist/server/registerBrowserJsonFormatting.js

@@ -0,0 +1,100 @@
+const MAX_PRETTY_JSON_CHARS = 1_000_000;
+const MAX_PRETTY_JSON_DEPTH = 64;
+const MAX_FORMATTED_JSON_CHARS = 4_000_000;
+const JSON_CONTENT_TYPE = /^application\/json(?:\s*;|$)/i;
+const JSON_TOKENS = /"(?:\\.|[^"\\])*"|[{}\[\],:]|[^\s{}\[\],:"]+/g;
+const BODY_PRESERVING_HEADERS = ['content-encoding', 'content-disposition', 'etag', 'content-digest', 'digest', 'content-md5'];
+/**
+ * Formats small JSON responses for browser page navigations across a Fastify server.
+ *
+ * Register before routes and plugins so their replies inherit the send hook. The
+ * hook runs after Fastify response-schema serialization and only reformats GET
+ * requests with `Sec-Fetch-Mode: navigate`. Browser fetches, other methods,
+ * streams, encoded bodies, and responses with integrity headers retain their
+ * original bytes. Large JSON bodies remain compact to bound browser-only work.
+ *
+ * @param server - Fastify server that owns the response lifecycle.
+ * @example
+ * const server = Fastify();
+ * registerBrowserJsonFormatting(server);
+ */
+export function registerBrowserJsonFormatting(server) {
+    server.addHook('onSend', (request, reply, payload, done) => {
+        if (request.method !== 'GET' || typeof payload !== 'string' || payload.length > MAX_PRETTY_JSON_CHARS)
+            return done(null, payload);
+        const contentType = reply.getHeader('content-type');
+        if (typeof contentType !== 'string' || !JSON_CONTENT_TYPE.test(contentType))
+            return done(null, payload);
+        if (BODY_PRESERVING_HEADERS.some(header => reply.hasHeader(header)))
+            return done(null, payload);
+        varyByFetchMode(reply);
+        if (request.headers['sec-fetch-mode'] !== 'navigate')
+            return done(null, payload);
+        try {
+            JSON.parse(payload);
+            const formatted = formatJsonTokens(payload);
+            if (formatted === payload)
+                return done(null, payload);
+            reply.removeHeader('content-length');
+            return done(null, formatted);
+        }
+        catch {
+            return done(null, payload);
+        }
+    });
+}
+/**
+ * Inserts spacing around validated JSON tokens without changing numeric or string literals.
+ *
+ * @param source - Valid serialized JSON whose original value tokens must be retained.
+ * @returns Indented JSON, or the original body when depth or output limits are reached.
+ */
+function formatJsonTokens(source) {
+    const tokens = source.match(JSON_TOKENS);
+    if (!tokens)
+        return source;
+    let depth = 0;
+    let formatted = '';
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (token === '{' || token === '[') {
+            const next = tokens[index + 1];
+            if (next === (token === '{' ? '}' : ']')) {
+                formatted += token + next;
+                index++;
+            }
+            else {
+                if (depth >= MAX_PRETTY_JSON_DEPTH)
+                    return source;
+                formatted += token + '\n' + '  '.repeat(++depth);
+            }
+        }
+        else if (token === '}' || token === ']') {
+            formatted += '\n' + '  '.repeat(--depth) + token;
+        }
+        else if (token === ',') {
+            formatted += ',\n' + '  '.repeat(depth);
+        }
+        else if (token === ':') {
+            formatted += ': ';
+        }
+        else {
+            formatted += token;
+        }
+        if (formatted.length > MAX_FORMATTED_JSON_CHARS)
+            return source;
+    }
+    return formatted;
+}
+/**
+ * Keeps cached compact and browser-readable JSON variants separate.
+ *
+ * @param reply - Response whose existing Vary fields must be preserved.
+ */
+function varyByFetchMode(reply) {
+    const existing = reply.getHeader('vary');
+    const values = existing === undefined ? '' : String(existing);
+    if (values === '*' || values.split(',').some(value => value.trim().toLowerCase() === 'sec-fetch-mode'))
+        return;
+    reply.header('vary', values ? `${values}, Sec-Fetch-Mode` : 'Sec-Fetch-Mode');
+}

package/dist/server/registerHttpErrorHandler.d.ts

@@ -0,0 +1,20 @@
+import type { FastifyInstance } from 'fastify';
+import type * as server from './contracts/index.js';
+/**
+ * Installs framework error logging and production-safe HTTP responses.
+ *
+ * Call immediately after constructing Fastify, before registering any routes or
+ * plugins. The inherited send hook also sanitizes explicit 5xx responses and
+ * child-plugin error handlers. Only deliberate mapped client errors and Fastify
+ * request errors retain public messages. Browser JSON formatting is installed
+ * after this boundary so it only sees the safe serialized response. Never send
+ * internal errors as 2xx data.
+ *
+ * @param fastify - HTTP host, still owned and closed by the caller.
+ * @param options - Application error classification and support-record observer.
+ * @example
+ * const server = Fastify({ logger: true });
+ * registerHttpErrorHandler(server);
+ * server.get('/example', async () => loadExample());
+ */
+export declare function registerHttpErrorHandler(fastify: FastifyInstance, options?: server.HttpErrorHandlerOptions): void;