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

package/src/index.ts

@@ -9,6 +9,7 @@ export {
 export * from './cache';
 export * from './config';
 export * from './events';
+export * from './health';
 export * from './logging';
 export * from './media';
 export * from './security';
@@ -16,25 +17,4 @@ export * from './serialization';
 export * from './url';
 export * from './validation';
 
-export interface AppManifest {
-	id: string;
-	name: string;
-	version: string;
-	description?: string;
-	icon?: string;
-	entry?: string;
-	adminPath?: string;
-	capabilities?: string[];
-}
-
-export interface AppDefinition<TManifest extends AppManifest = AppManifest> {
-	manifest: TManifest;
-}
-
-export function defineApp<TManifest extends AppManifest>(
-	manifest: TManifest,
-): AppDefinition<TManifest> {
-	return {
-		manifest,
-	};
-}
+export * from './apps';

package/src/logging/DevelopmentConsole.ts

@@ -0,0 +1,154 @@
+import { StringDecoder } from 'node:string_decoder';
+import { Writable } from 'node:stream';
+import { stripVTControlCharacters } from 'node:util';
+import { PrettyLogFormatter } from './PrettyLogFormatter';
+import type * as logging from './contracts';
+
+/**
+ * Owns grouped log output and a bounded live pending area in one terminal.
+ * Multi-process launchers must pipe every child's output through this owner;
+ * unrelated processes writing directly to the same TTY cannot be coordinated.
+ */
+export class DevelopmentConsole {
+	readonly #output: NonNullable<logging.DevelopmentConsoleOptions['output']>;
+	readonly #write: Writable['write'];
+	readonly #formatter: PrettyLogFormatter;
+	readonly #interactive: boolean;
+	readonly #restore: Array<() => void> = [];
+	#lines: string[] = [];
+	#timer?: ReturnType<typeof setInterval>;
+	#closed = false;
+
+	/**
+	 * Creates a console owner without starting an HTTP server or taking stream ownership.
+	 * @param options - Destination, terminal capability and stdio coordination.
+	 */
+	constructor(options: logging.DevelopmentConsoleOptions = {}) {
+		this.#output = options.output ?? process.stdout;
+		this.#write = this.#output.write.bind(this.#output);
+		this.#interactive = options.interactive ?? Boolean(this.#output.isTTY && process.env.TERM !== 'dumb');
+		this.#formatter = new PrettyLogFormatter(options.color ?? consoleColor(Boolean(this.#output.isTTY), process.env));
+		if (this.#interactive) {
+			if (options.coordinateStdio !== false && this.#output === process.stdout) {
+				this.#coordinate(process.stdout);
+				this.#coordinate(process.stderr);
+			}
+			this.#timer = setInterval(() => {
+				if (this.#lines.length && !this.#output.writableNeedDrain) this.#render('');
+			}, 250);
+			this.#timer.unref();
+			const resize = (): void => { this.#render(''); };
+			this.#output.on('resize', resize);
+			this.#restore.push(() => { this.#output.off('resize', resize); });
+		}
+		const exit = (): void => { this.close(); };
+		process.once('exit', exit);
+		this.#restore.push(() => { process.off('exit', exit); });
+	}
+
+	/** Accepts a complete Pino JSON line, retaining ordinary non-log text verbatim. */
+	write(line: string): void {
+		if (this.#closed) return;
+		try {
+			const record = JSON.parse(line);
+			if (record && typeof record === 'object' && typeof record.level === 'number') {
+				this.#render(this.#formatter.format(record));
+				return;
+			}
+		} catch { /* Non-JSON output from tools is ordinary terminal text. */ }
+		this.writeText(line);
+	}
+
+	/** Writes tool output above pending rows, removing controls that clear terminal history. */
+	writeText(text: string): void {
+		if (this.#closed || !text) return;
+		const safe = stripVTControlCharacters(text).replace(/\r/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+		this.#render(safe.endsWith('\n') ? safe : `${safe}\n`);
+	}
+
+	/**
+	 * Creates a separately buffered child stdout/stderr sink, handling split UTF-8
+	 * and final unterminated lines. Long non-JSON lines are forwarded in bounded chunks.
+	 * @returns A writable input; end it when its child stream closes.
+	 */
+	createInput(): Writable {
+		const decoder = new StringDecoder('utf8');
+		let pending = '';
+		const consume = (text: string): void => {
+			pending += text;
+			let newline: number;
+			while ((newline = pending.indexOf('\n')) !== -1) {
+				this.write(pending.slice(0, newline));
+				pending = pending.slice(newline + 1);
+			}
+			if (pending.length > 256 * 1024) { this.writeText(pending); pending = ''; }
+		};
+		return new Writable({
+			write: (chunk, _encoding, callback) => { consume(decoder.write(chunk)); callback(); },
+			final: callback => { consume(decoder.end()); if (pending) this.write(pending); callback(); },
+		});
+	}
+
+	/** Finalizes pending work from an exited child without disturbing other children. */
+	endSource(pid: number): void { this.#render(this.#formatter.finish(pid)); }
+
+	/** Waits for previously rendered output to reach the caller-owned destination. */
+	async flush(): Promise<void> {
+		await new Promise<void>((resolve, reject) => { this.#write('', error => error ? reject(error) : resolve()); });
+	}
+
+	/** Clears only owned rows, releases timers/listeners and restores patched stdio. */
+	close(): void {
+		if (this.#closed) return;
+		clearInterval(this.#timer);
+		this.#render(this.#formatter.finish());
+		this.#closed = true;
+		for (const restore of this.#restore.reverse()) restore();
+	}
+
+	/** Replaces only the live footer and appends immutable completed output above it. */
+	#render(text: string): void {
+		if (this.#closed) return;
+		if (!this.#interactive) { if (text) this.#write(text); return; }
+		const columns = Math.max(1, this.#output.columns ?? 80);
+		const occupied = this.#lines.reduce((rows, line) => rows + Math.max(1, Math.ceil(line.length / columns)), 0);
+		const clear = occupied ? `\u001b[${occupied}A\r\u001b[J` : '';
+		const pending = this.#formatter.pending();
+		const maximum = Math.max(1, Math.min(5, (this.#output.rows ?? 24) - 3));
+		const visible = pending.slice(0, maximum);
+		if (pending.length > maximum) visible[maximum - 1] = `[http] … ${pending.length - maximum + 1} more requests waiting`;
+		// ASCII in mutable rows gives exact terminal-cell counts across resizes.
+		this.#lines = columns < 20 ? [] : visible.map(line => line.replace(/→/g, '->').replace(/[^\x20-\x7e]/g, ' ').slice(0, columns - 1));
+		const footer = this.#lines.length ? this.#lines.join('\n') + '\n' : '';
+		if (clear || text || footer) this.#write(clear + text + footer);
+	}
+
+	/** Serializes same-process writes with redraws while preserving write callbacks. */
+	#coordinate(stream: NodeJS.WriteStream): void {
+		const original = stream.write;
+		const write: typeof stream.write = (chunk: string | Uint8Array, encoding?: BufferEncoding | ((error?: Error | null) => void), callback?: (error?: Error | null) => void): boolean => {
+			this.writeText(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString(typeof encoding === 'string' ? encoding : 'utf8'));
+			const done = typeof encoding === 'function' ? encoding : callback;
+			return this.#write('', done);
+		};
+		stream.write = write;
+		this.#restore.push(() => { if (stream.write === write) stream.write = original; });
+	}
+}
+
+/**
+ * Whether the pretty console uses colour. `NO_COLOR` turns it off; a set
+ * `FORCE_COLOR` (other than `0` or `false`) turns it on even without a TTY, as
+ * when a process manager pipes output into its own terminal view; otherwise a
+ * TTY decides.
+ *
+ * @param isTTY - Whether the output stream is a terminal.
+ * @param env - Process environment.
+ * @returns Whether to emit ANSI colours.
+ */
+export function consoleColor(isTTY: boolean, env: NodeJS.ProcessEnv): boolean {
+	if (env.NO_COLOR !== undefined) return false;
+	const force = env.FORCE_COLOR;
+	if (force === '0' || force === 'false') return false;
+	return force !== undefined || isTTY;
+}

package/src/logging/Log.ts

@@ -1,4 +1,5 @@
 import type { ChildLoggerOptions } from 'pino';
+import type { Mail } from '../mail';
 
 import { PinoLoggerDriver } from './drivers/PinoLoggerDriver';
 import type * as logging from './contracts';
@@ -19,9 +20,11 @@ export class Log implements logging.Logger {
 	 * Creates the application logger from explicit options or the Pino driver.
 	 *
 	 * @param options - Logging level, destinations, context, and driver overrides.
+	 * @param mail - Lazy application Mail resolver, required when email is configured.
 	 */
-	constructor(options: logging.LoggingOptions = {}) {
-		this.#driver = options.driver ?? new PinoLoggerDriver(options);
+	constructor(options: logging.LoggingOptions = {}, mail?: () => Mail) {
+		if (options.driver && options.transports !== undefined) throw new Error('Configured logging transports require the default Pino driver.');
+		this.#driver = options.driver ?? new PinoLoggerDriver(options, undefined, mail);
 	}
 
 	/** Returns the current trace function, respecting runtime level changes. */

package/src/logging/PrettyLogFormatter.ts

@@ -0,0 +1,165 @@
+import { STATUS_CODES } from 'node:http';
+import { highlightQueueMessage } from './highlightQueueMessage';
+
+/** Minimal retained HTTP context, bounded independently of the original log sinks. */
+interface PendingRequest {
+	record: Record<string, unknown>;
+	route: string;
+	started: number;
+	exchange?: Record<string, unknown>;
+}
+
+/** Groups redacted HTTP lifecycle records while preserving ordinary diagnostic logs. */
+export class PrettyLogFormatter {
+	readonly #requests = new Map<string, PendingRequest>();
+	readonly #ended = new Set<string>();
+	readonly #color: boolean;
+
+	/** Creates a formatter; terminal capability is resolved by the console owner. */
+	constructor(color = false) { this.#color = color; }
+
+	/**
+	 * Accepts one redacted Pino record and returns any completed output.
+	 * Request context is bounded to 1,000 entries. Eviction is explicitly reported;
+	 * later completions still print even when their earlier context is unavailable.
+	 */
+	format(record: Record<string, unknown>, now = Date.now()): string {
+		const message = record.msg;
+		const key = requestKey(record);
+		const request = object(record.req);
+		const exchange = object(record.httpExchange);
+		const route = requestRoute(request);
+		if (message === 'incoming request' && record.reqId != null && route) {
+			this.#ended.delete(key);
+			let evicted = '';
+			if (this.#requests.size >= 1000) {
+				const oldest = this.#requests.keys().next().value!;
+				const pending = this.#requests.get(oldest)!;
+				evicted = this.#http(pending.record, pending, 'tracking limit reached; response still pending');
+				this.#requests.delete(oldest);
+			}
+			this.#requests.set(key, { record, route, started: now });
+			return evicted;
+		}
+		if (message === 'request exchange' && exchange && Number(record.level ?? 30) <= 30) {
+			if (record.reqId != null && this.#ended.has(key)) return '';
+			const pending = this.#requests.get(key);
+			if (pending) {
+				pending.exchange = exchange;
+				return '';
+			}
+			// A missing arrival (e.g. a filtered log level) must not lose the payload.
+			return this.#http(record, { record, route: requestRoute(object(exchange.request)) || 'Request', started: now, exchange });
+		}
+		if (['request completed', 'request errored', 'request aborted', 'request timed out'].includes(String(message))) {
+			if (record.reqId != null) {
+				if (this.#ended.has(key)) return '';
+				if (this.#ended.size >= 1000) this.#ended.delete(this.#ended.values().next().value!);
+				this.#ended.add(key);
+			}
+			const pending = this.#requests.get(key);
+			this.#requests.delete(key);
+			const outcome = message === 'request completed' ? undefined : message === 'request errored' ? 'failed' : message === 'request aborted' ? 'cancelled' : 'timed out';
+			return this.#http(record, pending ?? { record, route: route || 'Request', started: now }, outcome);
+		}
+		const severity = Number(record.level ?? 30);
+		const category = severity >= 50 ? 'error' : severity >= 40 ? 'warn' : typeof record.component === 'string' ? record.component : severity <= 20 ? 'debug' : 'app';
+		const context = Object.entries(record).filter(([key, value]) => !hiddenFields.has(key) && value != null).slice(0, 8).map(([key, value]) => `${compact(key, 40)}=${compact(value, 100)}`).join('  ');
+		const details = errorDetails(record.err ?? record.error);
+		return `${this.#paint(timestamp(record.time), 90)} ${this.#paint(`[${compact(category, 30)}]`, severity >= 50 ? 31 : severity >= 40 ? 33 : 36)} ${this.#message(compact(record.msg ?? '', 500))}${context ? `  ${this.#paint(context, 90)}` : ''}\n${details ? indent(details) + '\n' : ''}`;
+	}
+
+	/** Returns waiting rows without mutating completed output or request order. */
+	pending(now = Date.now()): string[] {
+		return [...this.#requests.values()].map(request => {
+			const elapsed = Math.max(0, now - request.started);
+			return `[http] ${request.route}  ${elapsed >= 5000 ? 'slow · ' : ''}waiting · ${(elapsed / 1000).toFixed(1)} s  #${request.record.reqId}`;
+		});
+	}
+
+	/** Finalizes requests whose transport ended before a completion record arrived. */
+	finish(sourcePid?: number): string {
+		let output = '';
+		for (const [key, pending] of this.#requests) {
+			if (sourcePid !== undefined && pending.record.pid !== sourcePid) continue;
+			output += this.#http(pending.record, pending, 'interrupted · process stopped before response');
+			this.#requests.delete(key);
+		}
+		return output;
+	}
+
+	/** Renders a single immutable HTTP block, including readable payload previews. */
+	#http(record: Record<string, unknown>, pending: PendingRequest, outcome?: string): string {
+		const status = object(record.res)?.statusCode ?? object(pending.exchange?.response)?.statusCode;
+		const statusText = typeof status === 'number' ? `${status} ${STATUS_CODES[status] ?? ''}`.trim() : '';
+		const elapsed = typeof record.responseTime === 'number' && Number.isFinite(record.responseTime) ? ` · ${Math.round(record.responseTime)} ms` : '';
+		const tone = outcome || Number(status) >= 500 ? 31 : Number(status) >= 400 ? 33 : 32;
+		const reference = record.reqId == null ? '' : `  #${compact(record.reqId, 60)}`;
+		const bodies = bodyPreview(object(object(pending.exchange?.request)?.body), '> request') + bodyPreview(object(object(pending.exchange?.response)?.body), '< response');
+		const details = errorDetails(record.err ?? record.error);
+		return `${this.#paint(timestamp(pending.record.time), 90)} ${this.#paint('[http]', 36)} ${compact(pending.route, 240)}  ${this.#paint(outcome ?? (statusText || 'response'), tone)}${elapsed}${this.#paint(reference, 90)}\n${bodies}${details ? indent(details) + '\n' : ''}\n`;
+	}
+
+	/** Colours structural labels only, never application-controlled terminal escapes. */
+	#paint(text: string, code: number | string): string { return this.#color ? `\u001b[${code}m${text}\u001b[0m` : text; }
+
+	/** Highlights queue states and job labels when colouring. */
+	#message(text: string): string { return this.#color ? highlightQueueMessage(text, (part, code) => this.#paint(part, code)) : text; }
+}
+
+const hiddenFields = new Set(['level', 'time', 'pid', 'hostname', 'source', 'environment', 'release', 'component', 'msg', 'req', 'res', 'httpExchange', 'responseTime', 'err', 'error']);
+
+/** Separates processes and sources that independently allocate Fastify request IDs. */
+function requestKey(record: Record<string, unknown>): string { return JSON.stringify([record.pid, record.source, record.reqId]); }
+
+/** Narrows optional parsed context without trusting arbitrary application values. */
+function object(value: unknown): Record<string, unknown> | undefined { return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined; }
+
+/** Extracts the method and URL without headers or payload duplication. */
+function requestRoute(request: Record<string, unknown> | undefined): string { return typeof request?.method === 'string' && typeof request.url === 'string' ? `${request.method} → ${request.url}` : ''; }
+
+/** Formats local wall time with a stable fallback for non-Pino input. */
+function timestamp(value: unknown): string {
+	const date = new Date(typeof value === 'number' || typeof value === 'string' ? value : NaN);
+	return Number.isNaN(date.getTime()) ? '--:--:--' : [date.getHours(), date.getMinutes(), date.getSeconds()].map(part => String(part).padStart(2, '0')).join(':');
+}
+
+/** Prevents control injection and bounds single-line summaries. */
+function compact(value: unknown, limit: number): string {
+	const text = clean(typeof value === 'string' ? value : JSON.stringify(value) ?? String(value)).replace(/\s+/g, ' ');
+	return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+/** Strips terminal controls while retaining readable line breaks. */
+function clean(text: string): string { return text.replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/g, ''); }
+
+/** Indents diagnostic text consistently beneath its owning request or message. */
+function indent(text: string): string { return text.split('\n').map(line => `    ${line}`).join('\n'); }
+
+/** Shows small JSON inline and larger JSON as a bounded, explicitly shortened preview. */
+function bodyPreview(body: Record<string, unknown> | undefined, label: string): string {
+	if (!body || body.kind === 'empty') return '';
+	let text: string;
+	if (body.value === undefined) text = String(body.note ?? `${body.kind} body omitted`);
+	else if (body.kind === 'json' && !body.truncated) {
+		const expanded = JSON.stringify(body.value, null, 2);
+		const inline = expanded.replace(/\n\s*/g, ' ');
+		text = inline.length <= 90 ? inline : expanded;
+	} else text = String(body.value);
+	const lines = clean(text).split('\n');
+	const visible = lines.slice(0, 20).map(line => line.length > 160 ? `${line.slice(0, 159)}… [line shortened]` : line);
+	if (lines.length > 20) visible.push(`… ${lines.length - 20} more lines (full captured body in JSON logs/devtools)`);
+	if (body.truncated) visible.push(`… capture truncated (${body.sizeBytes ?? 'unknown'} bytes before limit)`);
+	return `  ${label}\n${indent(visible.join('\n'))}\n`;
+}
+
+/** Preserves bounded error stacks and nested causes without terminal control sequences. */
+function errorDetails(value: unknown, depth = 0): string {
+	if (value == null || depth > 4) return '';
+	const error = object(value);
+	if (!error) return compact(value, 2000);
+	const stack = typeof error.stack === 'string' ? clean(error.stack) : compact(`${error.type ?? 'Error'}: ${error.message ?? JSON.stringify(error)}`, 2000);
+	const detail = stack.length > 16000 ? stack.slice(0, 16000) + '\n… stack shortened' : stack;
+	const cause = errorDetails(error.cause, depth + 1);
+	return `${detail}${cause ? `\nCaused by: ${cause}` : ''}`;
+}

package/src/logging/README.md

@@ -1,139 +1,82 @@
 # Logging
 
-`@db3.ai/app/logging` provides the application logger exposed through
-`app().log`. Pino is the default driver, while the framework owns service discovery,
-configuration, redaction, transport selection, and shutdown.
+`app().log` uses Pino; the framework owns configuration, redaction, transports and shutdown.
 
-## Run a structured logging lab
+## Writing logs
 
-From your independent app after [Installation](https://db3.ai/docs/installation):
-
-```sh
-mkdir -p examples
-cp -R node_modules/@db3.ai/app/src/logging/examples/. examples/
-npx tsx examples/runNoteLogs.ts
-```
-
-This captures the real Pino driver's output in a writable stream, with devtools HTTP delivery disabled. Expect three records: `Note saved`, `Summary failed`, and `Diagnostics enabled`. The first debug message is filtered, then changing `log.level` enables debug output. Changing it to silent suppresses later errors. The output omits unstable metadata and stack text only for readability.
-
-The [Logging guide](https://db3.ai/docs/logging#testing) contains the exact consumer test. Save it as `tests/logging/runNoteLogs.test.ts` and run:
-
-```sh
-npx vitest run tests/logging/runNoteLogs.test.ts
-npx tsc --noEmit --target ES2022 --module ESNext --moduleResolution Bundler --types node --skipLibCheck examples/*.ts
-```
-
-The test asserts structured context, error serialization, level changes and the absence of synthetic password/token/provider-key values. It uses the real logger, not a framework mock. This does not prove remote log ingestion or retention.
-
-## Writing Logs
-
-Prefer a short message plus structured fields:
-
-```ts
-app().log.info({
-	websiteId,
-	pageCount,
-}, 'Website crawl completed');
-```
-
-Pass errors under `err` so Pino retains their name, message, stack, and cause:
+Use structured context and put exceptions under `err` to retain name, message, stack and cause:
 
 ```ts
-app().log.error({
-	err: error,
-	websiteId,
-}, 'Website crawl failed');
-```
-
-Use child loggers for context shared by several records:
-
-```ts
-const log = app().log.child({
-	component: 'crawler',
-	websiteId,
-});
-
+app().log.error({ err: error, websiteId }, 'Website crawl failed');
+const log = app().log.child({ component: 'crawler', websiteId });
 log.info('Crawl started');
-log.debug({ url }, 'Page discovered');
 ```
 
-The standard levels are `trace`, `debug`, `info`, `warn`, `error`, `fatal`,
-and `silent`. The default level is `info`; tests default to `silent`.
+Levels are `trace`, `debug`, `info`, `warn`, `error`, `fatal` and `silent`.
+The default is `info`, or `silent` in tests. Application boundaries must log exceptions explicitly.
 
-## Application Configuration
-
-Configure logging through `AppOptions.log`:
+## Configuration
 
 ```ts
 const app = new App({
 	log: {
-		level: 'debug',
+		level: 'info',
 		source: 'example-api',
-		bindings: {
-			release: process.env.RELEASE_SHA,
-		},
-		devtools: true,
+		bindings: { release: process.env.RELEASE_SHA },
+		transports: [
+			{ type: 'console' },
+			{ type: 'file', destination: '/storage/logs/app.jsonl' },
+			{ type: 'email', level: 'error', to: 'operator@example.com' },
+		],
 	},
 });
 ```
 
-Supported environment values:
-
-- `PLATFORM_LOG_LEVEL`: minimum standard log level.
-- `PLATFORM_LOG_SOURCE`: source name copied to every record.
-- `PLATFORM_LOG_DEVTOOLS`: explicitly enables or disables devtools delivery.
-- `PLATFORM_DEVTOOLS_EVENTS_URL`: complete development ingestion endpoint.
-- `PLATFORM_DEVTOOLS_HOST`: development service host when no URL is supplied.
-- `PLATFORM_DEVTOOLS_API_PORT`: development service port, defaulting to `9998`.
-
-Newline-delimited JSON is written to standard output by default. Interactive
-development also enables the framework devtools transport automatically. Tests
-do not enable network delivery unless explicitly configured.
+`transports` replaces defaults; `[]` disables output. Omit it for legacy/environment
+defaults. Route thresholds combine with the logger minimum; email defaults to `error`,
+others inherit it. `silent` disables a route. Pino permits one console and devtools via
+`{ type: 'devtools', options: { url } }`.
 
-## Development Log Stream
-
-The Pino transport runs in a worker thread and sends bounded, best-effort HTTP
-batches to the same generic event endpoint used by database and queue
-instrumentation:
-
-```text
-app().log
-	-> Pino worker transport
-	-> POST /api/events
-	-> development event store
-	-> WebSocket
-	-> Logs panel
-```
+Environment defaults: `PLATFORM_LOG_LEVEL`, `PLATFORM_LOG_SOURCE`, `PLATFORM_LOG_FORMAT`
+(`auto`, `pretty`, `json`), `PLATFORM_LOG_FILE`, `PLATFORM_LOG_DEVTOOLS`,
+`PLATFORM_DEVTOOLS_EVENTS_URL`, `PLATFORM_DEVTOOLS_HOST`, `PLATFORM_DEVTOOLS_API_PORT` (9998).
+Legacy `log.file` adds a file alongside stdout unless `console: false`.
 
-The default batch contains at most 25 records and a partial batch waits at most
-100 milliseconds. At most 1,000 unsent events are retained; the oldest event is
-discarded when that bound is exceeded. A failed batch is discarded and later
-delivery pauses for one second. Logging therefore remains observability rather
-than an application dependency.
+Terminals show pending requests and grouped exchanges; production/tests/pipes use JSON.
+`consoleFormat` overrides presentation. Files/devtools stay structured; test devtools
+requires opt-in. See [development logging](development/README.md).
 
-`App.close()` flushes the logger and closes its worker transport. Application
-entrypoints should always use the framework shutdown lifecycle rather than
-calling `process.exit()` directly after writing a log.
+## Email
 
-## Security
+Every matching record, including repeats, gets a separate submission through `app.mail`.
+Logging formats redacted primitive context and exception message/stack/cause as text and
+escaped HTML, excluding arbitrary nested payloads. Common credentials are masked.
+There is no grouping, deduplication, cooldown, retry or database dependency.
+Operation backoff remains the caller's responsibility.
 
-The default Pino driver removes common password, secret, token, authorization,
-and cookie paths before records reach stdout or devtools. Applications can add
-more redaction paths through `AppOptions.log.redact`.
+Sends are asynchronous and ordered; flush/close drains them. Abrupt exits lose pending
+mail. Refusals go to stderr without recursive emails; later sends continue. Keep raw logs:
+acceptance is not inbox delivery. App supplies the lazy Mail resolver accepted by `Log`.
+Database, PostHog and OpenTelemetry transports are not included.
 
-Redaction is a safeguard, not permission to log request bodies, credentials,
-payment details, or personal data. Prefer explicit safe fields over logging
-large application objects.
+## Delivery and shutdown
 
-Redaction removes configured paths, not arbitrary secret substrings. Error messages, URL query strings and unfamiliar nested properties may still contain sensitive data. Test your application paths and never embed a credential in the log message itself. `redact: false` disables the protection.
+Devtools sends worker-thread HTTP batches to `/api/events`: at most 25 records per batch,
+100ms partial-batch wait, 1,000 pending events. Overflow drops oldest events; failed batches
+are discarded and delivery pauses one second. Its event store feeds the Logs panel.
 
-`Log.level` changes take effect on subsequent method lookups; avoid capturing a log function and then expecting it to be replaced when the level changes. `App.close()` owns its logger; a manually supplied output stream remains the creator's resource to end. The [full API](https://db3.ai/docs/logging-api) includes all current logger, driver, options and HTTP exchange contracts.
+`App.close()` flushes logging and closes owned workers; use it instead of immediate
+`process.exit()`. Caller-supplied streams remain caller-owned. File transports create parent
+directories; mount files persistently and manage rotation, retention, permissions and capacity.
+`Log.level` changes affect subsequent method lookups, not previously captured functions.
 
-## Framework Boundaries
+## Security and boundaries
 
-Logs describe operations for people and observability tools. They are not a
-framework event bus and must not trigger application behavior.
+Pino removes common credential, authorization and cookie paths. Add paths with `log.redact`;
+`false` disables protection. Path redaction cannot remove arbitrary secret substrings,
+private prose or unfamiliar nested fields. Avoid sensitive messages, URL queries and bodies;
+log explicit safe fields and test application-specific redaction.
 
-Database query events, queue lifecycle events, and durable flow events retain
-their own typed contracts. They can be correlated with logs through fields such
-as `requestId`, `jobId`, `websiteId`, `flowId`, and `component`.
+Logs must not trigger application behavior. Database, queue and flow events keep their
+own typed contracts; correlate them using request/job/website/flow IDs and component fields.
+See the [API](https://db3.ai/docs/logging-api) for contracts.

package/src/logging/acquireDevelopmentConsole.ts

@@ -0,0 +1,19 @@
+import { DevelopmentConsole } from './DevelopmentConsole';
+
+let active: DevelopmentConsole | undefined;
+let leases = 0;
+
+/** Shares one terminal owner across application loggers in the same process. */
+export function acquireDevelopmentConsole(): { console: DevelopmentConsole; release: () => void } {
+	active ??= new DevelopmentConsole();
+	leases++;
+	let released = false;
+	return {
+		console: active,
+		release: () => {
+			if (released) return;
+			released = true;
+			if (--leases === 0) { active?.close(); active = undefined; }
+		},
+	};
+}

package/src/logging/contracts/DevelopmentConsoleOptions.ts

@@ -0,0 +1,13 @@
+import type { Writable } from 'node:stream';
+
+/** Terminal capabilities for the one renderer that owns a development output stream. */
+export interface DevelopmentConsoleOptions {
+	/** Output destination; defaults to process.stdout. The caller retains stream ownership. */
+	output?: Writable & { isTTY?: boolean; columns?: number; rows?: number };
+	/** Enable pending-row redraws. Defaults to the output's terminal capability. */
+	interactive?: boolean;
+	/** Enable structural ANSI colours. Defaults to terminal support, respecting NO_COLOR. */
+	color?: boolean;
+	/** Coordinate console.log/warn and direct stdout/stderr writes in this process. Defaults to true for interactive stdout. */
+	coordinateStdio?: boolean;
+}

package/src/logging/contracts/EmailLogOptions.ts

@@ -0,0 +1,9 @@
+import type { MailAddress } from '../../mail';
+
+/** Sends each error or fatal record to the configured operator through the application's Mail service. */
+export interface EmailLogOptions {
+	/** Explicit operator destination; disabled unless configured. */
+	to: MailAddress | MailAddress[];
+	/** Optional subject prefix identifying the application. Defaults to Application error. */
+	subjectPrefix?: string;
+}

package/src/logging/contracts/HttpExchangeMonitorOptions.ts

@@ -0,0 +1,13 @@
+import type { FastifyRequest } from 'fastify';
+
+/** Development HTTP payload capture policy, owned by the host application. */
+export interface HttpExchangeMonitorOptions {
+	/** Defaults to NODE_ENV; production and test never capture payloads. */
+	environment?: string;
+	/** Explicitly disables body capture independently of console presentation. */
+	enabled?: boolean;
+	/** Maximum bytes retained per body; defaults to 16 KiB, capped at 64 KiB. */
+	maxBodyBytes?: number;
+	/** Excludes sensitive routes from payload capture. Request summaries remain governed by route logging. */
+	exclude?: (request: FastifyRequest) => boolean;
+}

package/src/logging/contracts/LogTransportOptions.ts

@@ -0,0 +1,10 @@
+import type { EmailLogOptions } from './EmailLogOptions';
+import type { LogLevel } from './Logger';
+import type { DevtoolsLogOptions } from './LoggingOptions';
+
+/** A configured destination receiving records at its minimum severity or above. */
+export type LogTransportOptions =
+	| { type: 'console'; level?: LogLevel }
+	| { type: 'file'; level?: LogLevel; destination: string }
+	| ({ type: 'email'; level?: LogLevel } & EmailLogOptions)
+	| { type: 'devtools'; level?: LogLevel; options?: DevtoolsLogOptions };