/**
 * Ephemeral, in-memory debug-logging contract — shared across server and
 * browser code, and by any package/project that wants to emit developer-
 * facing debug output (see docs/LOGGING.md). Deliberately unrelated to
 * `$lib/server/core/analytics.ts`: that module is a permanent record of
 * business data (sessions/messages/tool-calls/events); this is a disposable
 * debugging aid, never persisted to disk.
 *
 * `category` is an intentionally open string, not a closed union — packages
 * like `humanoid` (and its `eye` sub-package) own their own namespace (e.g.
 * `"humanoid.eye"`) without core needing to know about them ahead of time,
 * the same "no registration step" rule as the package system itself (see
 * docs/ARCHITECTURE.md's "Optional packages" section).
 */

export type LogLevel = 'debug' | 'info' | 'warn' | 'error';

export interface LogEntry {
	level: LogLevel;
	category: string;
	message: string;
	data?: unknown;
	timestamp: number; // epoch ms
}

export interface Logger {
	debug(category: string, message: string, data?: unknown): void;
	info(category: string, message: string, data?: unknown): void;
	warn(category: string, message: string, data?: unknown): void;
	error(category: string, message: string, data?: unknown): void;
}

/** Discards every call. Useful as a default so callers never need to null-check a `Logger`. */
export const NOOP_LOGGER: Logger = {
	debug() {},
	info() {},
	warn() {},
	error() {}
};