@ciq-dev/neoiq-foundation-node 1.0.1-beta.1 → 1.0.1-beta.2

package/dist/index.mjs

@@ -1,7 +1,8 @@
+import { createRequire } from "module";
 import { z } from "zod";
 import { AsyncLocalStorage } from "async_hooks";
-import pino from "pino";
 import { SpanStatusCode, SpanStatusCode as SpanStatusCode$1, context, context as context$1, metrics, propagation, propagation as propagation$1, trace, trace as trace$1 } from "@opentelemetry/api";
+import pino from "pino";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
@@ -14,7 +15,12 @@ import { randomUUID } from "crypto";
 import axios from "axios";
 import axiosRetry from "axios-retry";
 import CircuitBreaker from "opossum";
+import { Readable } from "node:stream";
+
+//#region rolldown:runtime
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+//#endregion
 //#region src/config.ts
 const AutoInstrumentationConfigSchema = z.object({
 	http: z.boolean().default(true),
@@ -57,6 +63,11 @@ const RequestLoggingConfigSchema = z.object({
 	maxBodySize: z.number().default(10 * 1024),
 	redactHeaders: z.array(z.string()).optional()
 }).partial();
+const RedactionConfigSchema = z.object({ additionalPaths: z.array(z.string()).default([]) }).partial();
+const ShutdownConfigSchema = z.object({
+	flushOnCrash: z.boolean().default(false),
+	flushTimeoutMs: z.number().min(100).default(5e3)
+}).partial();
 const FoundationConfigSchema = z.object({
 	serviceName: z.string().min(1, "serviceName is required"),
 	serviceVersion: z.string().default(process.env.SERVICE_VERSION || "1.0.0"),
@@ -69,7 +80,9 @@ const FoundationConfigSchema = z.object({
 	features: FeaturesConfigSchema.default({}),
 	otel: OtelConfigSchema.default({}),
 	logging: LoggingConfigSchema.default({}),
-	requestLogging: RequestLoggingConfigSchema.default({})
+	requestLogging: RequestLoggingConfigSchema.default({}),
+	redaction: RedactionConfigSchema.default({}),
+	shutdown: ShutdownConfigSchema.default({})
 });
 /** Parse and validate configuration */
 function parseConfig(input) {
@@ -87,33 +100,247 @@ function getDefaultOtelEndpoint() {
 
 //#endregion
 //#region src/features/context.ts
+const BAGGAGE_CORRELATION_KEY = "correlation.id";
+function setBaggageCorrelationId(correlationId) {
+	const currentBaggage = propagation$1.getBaggage(context$1.active());
+	const baggage = (currentBaggage ?? propagation$1.createBaggage()).setEntry(BAGGAGE_CORRELATION_KEY, { value: correlationId });
+	return propagation$1.setBaggage(context$1.active(), baggage);
+}
+function getBaggageCorrelationId() {
+	const baggage = propagation$1.getBaggage(context$1.active());
+	return baggage?.getEntry(BAGGAGE_CORRELATION_KEY)?.value;
+}
 /** Create a new context manager instance */
 function createContextManager() {
 	const als = new AsyncLocalStorage();
 	return {
-		getContext: () => als.getStore(),
+		getContext() {
+			const alsCtx = als.getStore();
+			if (!alsCtx) return void 0;
+			const baggageCorrelationId = getBaggageCorrelationId();
+			if (baggageCorrelationId && baggageCorrelationId !== alsCtx.correlationId) return {
+				...alsCtx,
+				correlationId: baggageCorrelationId
+			};
+			return alsCtx;
+		},
 		run(context$2, fn) {
+			if (context$2.correlationId) {
+				const otelCtx = setBaggageCorrelationId(context$2.correlationId);
+				return context$1.with(otelCtx, () => als.run(context$2, fn));
+			}
 			return als.run(context$2, fn);
 		},
 		get(key) {
+			if (key === "correlationId") return getBaggageCorrelationId() ?? als.getStore()?.correlationId;
 			return als.getStore()?.[key];
 		},
 		update(updates) {
 			const current = als.getStore();
 			if (!current) return void 0;
+			if (updates.correlationId) setBaggageCorrelationId(updates.correlationId);
 			Object.assign(current, updates);
 			return current;
+		},
+		setContextValue(key, value) {
+			const current = als.getStore();
+			if (!current) return;
+			if (!current.contextData) current.contextData = {};
+			current.contextData[key] = value;
+		},
+		getContextValue(key) {
+			return als.getStore()?.contextData?.[key];
+		},
+		getContextData() {
+			return als.getStore()?.contextData ?? {};
+		},
+		setContextData(data) {
+			const current = als.getStore();
+			if (!current) return;
+			current.contextData = {
+				...current.contextData ?? {},
+				...data
+			};
+		},
+		clearContextData() {
+			const current = als.getStore();
+			if (!current) return;
+			current.contextData = {};
 		}
 	};
 }
 
+//#endregion
+//#region src/features/redaction.ts
+/**
+* Log Redaction & PII Sanitization
+*
+* Two-layer approach:
+* - Layer A: Pino native `redact` (fast-redact) for key-based redaction on every log call.
+*   Compiled at init, near-zero runtime cost.
+* - Layer B: Deep-traverse sanitizer for value-pattern detection (JWTs, AWS keys, etc.).
+*   Only used for request/response body logging — NOT on every log call.
+*/
+const PLACEHOLDER = "[REDACTED]";
+/**
+* Key names that Pino's fast-redact will censor automatically.
+* Supports wildcards: '*.password' matches nested keys one level deep.
+*/
+const REDACT_PATHS = [
+	"password",
+	"passwd",
+	"pass",
+	"pwd",
+	"secret",
+	"secretKey",
+	"secret_key",
+	"token",
+	"accessToken",
+	"access_token",
+	"refreshToken",
+	"refresh_token",
+	"idToken",
+	"id_token",
+	"apiKey",
+	"api_key",
+	"apiSecret",
+	"api_secret",
+	"authorization",
+	"auth",
+	"credentials",
+	"privateKey",
+	"private_key",
+	"cookie",
+	"setCookie",
+	"set_cookie",
+	"creditCard",
+	"credit_card",
+	"cardNumber",
+	"card_number",
+	"ccNumber",
+	"cc_number",
+	"cvv",
+	"cvc",
+	"securityCode",
+	"security_code",
+	"accountNumber",
+	"account_number",
+	"ssn",
+	"socialSecurity",
+	"social_security",
+	"dateOfBirth",
+	"date_of_birth",
+	"dob",
+	"*.password",
+	"*.secret",
+	"*.token",
+	"*.apiKey",
+	"*.api_key",
+	"*.authorization",
+	"*.cookie",
+	"*.credentials",
+	"*.creditCard",
+	"*.cardNumber",
+	"*.cvv",
+	"*.ssn",
+	"*.privateKey",
+	"*.private_key"
+];
+/**
+* Value patterns that indicate a secret regardless of the key name.
+* Used only for body sanitization (Layer B).
+*/
+const VALUE_PATTERNS = [
+	{
+		label: "jwt",
+		pattern: /^eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+$/
+	},
+	{
+		label: "aws_access_key",
+		pattern: /(?:^|[^A-Za-z0-9])AKIA[0-9A-Z]{16}(?:$|[^A-Za-z0-9])/
+	},
+	{
+		label: "stripe_key",
+		pattern: /^[sr]k_(live|test)_[A-Za-z0-9]{10,}$/
+	},
+	{
+		label: "openai_key",
+		pattern: /^sk-[A-Za-z0-9_-]{20,}$/
+	},
+	{
+		label: "github_token",
+		pattern: /^gh[ps]_[A-Za-z0-9]{36,}$/
+	},
+	{
+		label: "pem_private_key",
+		pattern: /-----BEGIN\s+(RSA\s+|EC\s+)?PRIVATE\s+KEY-----/
+	},
+	{
+		label: "connection_string",
+		pattern: /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^:]+:[^@]+@/
+	},
+	{
+		label: "bearer_token",
+		pattern: /^Bearer\s+\S{10,}$/i
+	}
+];
+const SENSITIVE_KEYS = new Set(REDACT_PATHS.filter((p) => !p.includes("*")).map((k) => k.toLowerCase()));
+const MAX_DEPTH = 10;
+const MAX_KEYS = 200;
+function mask(value) {
+	if (typeof value !== "string" || value.length <= 8) return PLACEHOLDER;
+	return `${value.slice(0, 4)}${"*".repeat(Math.min(value.length - 8, 20))}${value.slice(-4)}`;
+}
+function isSensitiveValue(value) {
+	return VALUE_PATTERNS.some((p) => p.pattern.test(value));
+}
+function sanitizeValue(value, depth) {
+	if (depth > MAX_DEPTH) return value;
+	if (typeof value === "string" && isSensitiveValue(value)) return mask(value);
+	if (Array.isArray(value)) return value.map((item) => sanitizeValue(item, depth + 1));
+	if (value !== null && typeof value === "object") return sanitizeObject(value, depth + 1);
+	return value;
+}
+function sanitizeObject(obj, depth) {
+	if (depth > MAX_DEPTH) return obj;
+	const keys = Object.keys(obj);
+	if (keys.length > MAX_KEYS) return obj;
+	const result = {};
+	for (const key of keys) {
+		const value = obj[key];
+		if (SENSITIVE_KEYS.has(key.toLowerCase())) result[key] = typeof value === "string" ? mask(value) : PLACEHOLDER;
+		else result[key] = sanitizeValue(value, depth);
+	}
+	return result;
+}
+/**
+* Deep-traverse sanitizer for request/response bodies.
+* Checks both key names (deny-list) and value patterns (JWT, AWS keys, etc.).
+* NOT intended for every log call — use Pino native `redact` for that.
+*/
+function sanitizeBody(body) {
+	if (body === null || body === void 0) return body;
+	if (typeof body === "string") return isSensitiveValue(body) ? mask(body) : body;
+	if (typeof body !== "object") return body;
+	if (Array.isArray(body)) return body.map((item) => sanitizeValue(item, 0));
+	return sanitizeObject(body, 0);
+}
+/** Build the Pino `redact` config object for fast-redact integration */
+function buildPinoRedactConfig(additionalPaths = []) {
+	return {
+		paths: [...REDACT_PATHS, ...additionalPaths],
+		censor: PLACEHOLDER
+	};
+}
+
 //#endregion
 //#region src/features/logging.ts
 /** Create a structured logger with automatic trace context injection */
 function createLogger(options) {
-	const { serviceName, serviceVersion, environment, level, prettyPrint, contextManager } = options;
+	const { serviceName, serviceVersion, environment, level, prettyPrint, contextManager, additionalRedactPaths = [] } = options;
 	const pinoLogger = pino({
 		level,
+		redact: buildPinoRedactConfig(additionalRedactPaths),
 		base: {
 			service: serviceName,
 			version: serviceVersion,
@@ -126,11 +353,14 @@ function createLogger(options) {
 			const traceId = spanContext?.traceId || ctx?.traceId;
 			const spanId = spanContext?.spanId || ctx?.spanId;
 			const correlationId = ctx?.correlationId;
-			return {
+			const contextData = ctx?.contextData;
+			const result = {
 				trace_id: traceId,
 				span_id: spanId,
 				correlation_id: correlationId
 			};
+			if (contextData && Object.keys(contextData).length > 0) result.context = contextData;
+			return result;
 		},
 		formatters: { level: (label) => ({ level: label }) },
 		transport: prettyPrint ? {
@@ -191,12 +421,26 @@ function getGlobalLogger() {
 //#region src/features/tracing.ts
 let sdk = null;
 let isInitialized$1 = false;
+const MONITORED_MODULES = [
+	"pg",
+	"mongodb",
+	"ioredis",
+	"mysql2",
+	"express",
+	"@grpc/grpc-js"
+];
+function warnPreloadedModules() {
+	for (const mod of MONITORED_MODULES) try {
+		if (__require.resolve(mod) in (__require.cache || {})) console.warn(`[neoiq-foundation] "${mod}" was imported before tracing init. Auto-instrumentation may not work for this module. Use node -r @ciq-dev/neoiq-foundation-node/bootstrap or call createFoundation() first.`);
+	} catch {}
+}
 /** Initialize OpenTelemetry tracing */
 function setupTracing(options) {
 	if (isInitialized$1) {
 		console.warn("[neoiq-foundation] Tracing already initialized");
 		return;
 	}
+	warnPreloadedModules();
 	const { serviceName, serviceVersion, environment, endpoint = getDefaultOtelEndpoint(), autoInstrumentation = {} } = options;
 	const resource = resourceFromAttributes({
 		[ATTR_SERVICE_NAME]: serviceName,
@@ -353,7 +597,6 @@ function createObservabilityPlugin(options) {
 		const maxBodySize = requestLogging.maxBodySize ?? 10 * 1024;
 		const headersToRedact = requestLogging.redactHeaders ?? DEFAULT_REDACT_HEADERS;
 		const runInContext = contextManager ? (ctx, fn) => contextManager.run(ctx, fn) : (_ctx, fn) => fn();
-		const tracer = tracingEnabled ? trace$1.getTracer("neoiq-foundation-node") : null;
 		let requestCounter;
 		let requestDuration;
 		let requestErrors;
@@ -370,22 +613,12 @@ function createObservabilityPlugin(options) {
 			}
 			const correlationId = request.headers["x-request-id"] || randomUUID();
 			reply.header("x-request-id", correlationId);
-			let span;
 			let traceId = "";
 			let spanId = "";
-			if (tracer) {
-				const parentContext = propagation$1.extract(context$1.active(), request.headers);
-				span = tracer.startSpan(`${request.method} ${request.routeOptions?.url || request.url}`, {
-					kind: 1,
-					attributes: {
-						"http.method": request.method,
-						"http.url": request.url,
-						"http.route": request.routeOptions?.url || request.url,
-						"http.user_agent": request.headers["user-agent"] || "",
-						"http.correlation_id": correlationId
-					}
-				}, parentContext);
-				const spanContext = span.spanContext();
+			const activeSpan = tracingEnabled ? trace$1.getActiveSpan() : void 0;
+			if (activeSpan) {
+				activeSpan.setAttribute("http.correlation_id", correlationId);
+				const spanContext = activeSpan.spanContext();
 				traceId = spanContext.traceId;
 				spanId = spanContext.spanId;
 			}
@@ -395,7 +628,6 @@ function createObservabilityPlugin(options) {
 				spanId,
 				startTime: Date.now()
 			};
-			request.__span = span;
 			request.__requestContext = requestContext;
 			runInContext(requestContext, () => {
 				const logData = {
@@ -421,7 +653,7 @@ function createObservabilityPlugin(options) {
 			runInContext(ctx, () => {
 				logger.debug({
 					correlation_id: ctx.correlationId,
-					body: truncateBody(request.body, maxBodySize)
+					body: sanitizeBody(truncateBody(request.body, maxBodySize))
 				}, "Request body");
 				done();
 			});
@@ -436,14 +668,13 @@ function createObservabilityPlugin(options) {
 				logger.debug({
 					correlation_id: ctx.correlationId,
 					statusCode: reply.statusCode,
-					body: truncateBody(payload, maxBodySize)
+					body: sanitizeBody(truncateBody(payload, maxBodySize))
 				}, "Response body");
 				done(null, payload);
 			});
 		});
 		fastify.addHook("onResponse", (request, reply, done) => {
 			const ctx = request.__requestContext;
-			const span = request.__span;
 			if (!ctx) {
 				done();
 				return;
@@ -467,18 +698,15 @@ function createObservabilityPlugin(options) {
 					requestDuration.record(durationMs, labels);
 					if (reply.statusCode >= 400) requestErrors.add(1, labels);
 				}
-				if (span) {
-					span.setStatus({ code: reply.statusCode < 400 ? SpanStatusCode$1.OK : SpanStatusCode$1.ERROR });
-					span.setAttribute("http.status_code", reply.statusCode);
-					span.setAttribute("http.response_time_ms", durationMs);
-					span.end();
+				if (tracingEnabled) {
+					const activeSpan = trace$1.getActiveSpan();
+					if (activeSpan) activeSpan.setAttribute("http.response_time_ms", durationMs);
 				}
 				done();
 			});
 		});
 		fastify.addHook("onError", (request, _reply, error, done) => {
 			const ctx = request.__requestContext;
-			const span = request.__span;
 			if (!ctx) {
 				done();
 				return;
@@ -490,12 +718,15 @@ function createObservabilityPlugin(options) {
 					url: request.url,
 					error: error.message
 				}, "Request failed");
-				if (span) {
-					span.setStatus({
-						code: SpanStatusCode$1.ERROR,
-						message: error.message
-					});
-					span.recordException(error);
+				if (tracingEnabled) {
+					const activeSpan = trace$1.getActiveSpan();
+					if (activeSpan) {
+						activeSpan.setStatus({
+							code: SpanStatusCode$1.ERROR,
+							message: error.message
+						});
+						activeSpan.recordException(error);
+					}
 				}
 				done();
 			});
@@ -625,17 +856,54 @@ function createHttpClient(options) {
 		breaker.on("open", () => logger.warn({ targetService: serviceName }, "Circuit breaker OPEN"));
 		breaker.on("halfOpen", () => logger.info({ targetService: serviceName }, "Circuit breaker HALF-OPEN"));
 		breaker.on("close", () => logger.info({ targetService: serviceName }, "Circuit breaker CLOSED"));
+		const originalRequest = client.request.bind(client);
+		client.request = (config) => breaker.fire(config);
+		client.get = (url, config) => breaker.fire({
+			...config,
+			method: "GET",
+			url
+		});
+		client.post = (url, data, config) => breaker.fire({
+			...config,
+			method: "POST",
+			url,
+			data
+		});
+		client.put = (url, data, config) => breaker.fire({
+			...config,
+			method: "PUT",
+			url,
+			data
+		});
+		client.delete = (url, config) => breaker.fire({
+			...config,
+			method: "DELETE",
+			url
+		});
+		client.patch = (url, data, config) => breaker.fire({
+			...config,
+			method: "PATCH",
+			url,
+			data
+		});
+		client.__originalRequest = originalRequest;
 	}
 	return client;
 }
 
 //#endregion
 //#region src/foundation.ts
+const deprecationWarnings = new Set();
+function warnDeprecation(oldPath, newPath) {
+	if (deprecationWarnings.has(oldPath)) return;
+	deprecationWarnings.add(oldPath);
+	console.warn(`[neoiq-foundation] DEPRECATED: foundation.${oldPath}() is deprecated. Use foundation.${newPath}() instead. This alias will be removed in the next major version.`);
+}
 /** Create a fully configured observability foundation */
 function createFoundation(input) {
 	const startTime = Date.now();
 	const config = parseConfig(input);
-	const { serviceName, serviceVersion, environment, features: featuresConfig, otel, logging: loggingConfig, requestLogging: requestLoggingConfig } = config;
+	const { serviceName, serviceVersion, environment, features: featuresConfig, otel, logging: loggingConfig, requestLogging: requestLoggingConfig, redaction: redactionConfig, shutdown: shutdownConfig } = config;
 	const features = {
 		tracing: featuresConfig.tracing ?? true,
 		metrics: featuresConfig.metrics ?? true,
@@ -651,7 +919,8 @@ function createFoundation(input) {
 			environment,
 			level: loggingConfig.level ?? "info",
 			prettyPrint: loggingConfig.prettyPrint ?? environment === "development",
-			contextManager
+			contextManager,
+			additionalRedactPaths: redactionConfig.additionalPaths
 		});
 		setGlobalLogger(logger);
 	} catch (err) {
@@ -723,17 +992,137 @@ function createFoundation(input) {
 		environment,
 		features
 	}, "Foundation initialized");
-	const foundation = {
-		config,
+	if (shutdownConfig.flushOnCrash) {
+		const flushTimeoutMs = shutdownConfig.flushTimeoutMs ?? 5e3;
+		const crashFlush = (origin, err) => {
+			const error = err instanceof Error ? err : new Error(String(err));
+			logger.error({
+				error: error.message,
+				stack: error.stack,
+				origin
+			}, "Process crash detected, flushing telemetry");
+			const flushPromises = [];
+			if (features.tracing && isTracingEnabled()) flushPromises.push(shutdownTracing());
+			if (features.metrics && isMetricsEnabled()) flushPromises.push(shutdownMetrics());
+			const timeout = new Promise((resolve) => setTimeout(resolve, flushTimeoutMs));
+			Promise.race([Promise.allSettled(flushPromises), timeout]).finally(() => {
+				process.exit(1);
+			});
+		};
+		process.on("uncaughtException", (err) => crashFlush("uncaughtException", err));
+		process.on("unhandledRejection", (reason) => crashFlush("unhandledRejection", reason));
+		logger.info({ flushTimeoutMs }, "Crash-flush handlers registered");
+	}
+	const traceInSpan = async (name, fn) => {
+		const tracer = tracerInstance || getTracer(serviceName);
+		return new Promise((resolve, reject) => {
+			tracer.startActiveSpan(name, async (span) => {
+				try {
+					const result = await fn();
+					span.setStatus({ code: SpanStatusCode.OK });
+					span.end();
+					resolve(result);
+				} catch (err) {
+					const error = err;
+					span.setStatus({
+						code: SpanStatusCode.ERROR,
+						message: error.message
+					});
+					span.recordException(error);
+					span.end();
+					logger.error({
+						span: name,
+						error: error.message
+					}, "Span failed");
+					reject(error);
+				}
+			});
+		});
+	};
+	const observability = {
 		logger,
-		context: contextManager,
 		tracer: tracerInstance,
 		meter: meterInstance,
-		features,
 		getTracer: (name) => getTracer(name || serviceName),
 		getMeter: (name, version) => getMeter(name, version),
 		getTraceContext,
 		getActiveSpan,
+		trace: traceInSpan
+	};
+	const httpModule = { createClient: (options) => createHttpClient({
+		...options,
+		foundation
+	}) };
+	const buildHealthStatus = () => {
+		const tracingUp = !features.tracing || !tracingError && isTracingEnabled();
+		const metricsUp = !features.metrics || !metricsError && isMetricsEnabled();
+		const loggingUp = !loggingError;
+		const allUp = tracingUp && metricsUp && loggingUp;
+		const anyDown = features.tracing && tracingError || features.metrics && metricsError || loggingError;
+		return {
+			status: allUp ? "healthy" : anyDown ? "degraded" : "unhealthy",
+			timestamp: new Date().toISOString(),
+			service: serviceName,
+			version: serviceVersion,
+			uptime: Math.floor((Date.now() - startTime) / 1e3),
+			components: {
+				tracing: {
+					enabled: features.tracing,
+					status: !features.tracing ? "disabled" : tracingError ? "down" : "up",
+					message: tracingError
+				},
+				metrics: {
+					enabled: features.metrics,
+					status: !features.metrics ? "disabled" : metricsError ? "down" : "up",
+					message: metricsError
+				},
+				logging: {
+					enabled: features.logging,
+					status: loggingError ? "down" : "up",
+					message: loggingError
+				}
+			}
+		};
+	};
+	const shutdownFn = async () => {
+		logger.info({}, "Shutting down foundation...");
+		const promises = [];
+		if (features.tracing && isTracingEnabled()) promises.push(shutdownTracing());
+		if (features.metrics && isMetricsEnabled()) promises.push(shutdownMetrics());
+		await Promise.all(promises);
+		logger.info({}, "Foundation shutdown complete");
+	};
+	const isReadyFn = () => {
+		if (features.tracing && !tracingError && !isTracingEnabled()) return false;
+		if (features.metrics && !metricsError && !isMetricsEnabled()) return false;
+		return true;
+	};
+	const safeRunFn = async (fn, fallback) => {
+		try {
+			return await fn();
+		} catch (err) {
+			const error = err;
+			logger.error({
+				error: error.message,
+				stack: error.stack
+			}, "safeRun caught error");
+			return fallback;
+		}
+	};
+	const lifecycle = {
+		health: buildHealthStatus,
+		isReady: isReadyFn,
+		shutdown: shutdownFn,
+		safeRun: safeRunFn
+	};
+	const foundation = {
+		config,
+		features,
+		observability,
+		http: httpModule,
+		lifecycle,
+		logger,
+		context: contextManager,
 		fastifyPlugin: createObservabilityPlugin({
 			serviceName,
 			logger,
@@ -742,91 +1131,47 @@ function createFoundation(input) {
 			metricsEnabled: features.metrics && !metricsError,
 			requestLogging: requestLoggingConfig
 		}),
-		createHttpClient: (options) => createHttpClient({
-			...options,
-			foundation
-		}),
-		shutdown: async () => {
-			logger.info({}, "Shutting down foundation...");
-			const promises = [];
-			if (features.tracing && isTracingEnabled()) promises.push(shutdownTracing());
-			if (features.metrics && isMetricsEnabled()) promises.push(shutdownMetrics());
-			await Promise.all(promises);
-			logger.info({}, "Foundation shutdown complete");
+		tracer: tracerInstance,
+		meter: meterInstance,
+		getTracer: (name) => {
+			warnDeprecation("getTracer", "observability.getTracer");
+			return observability.getTracer(name);
+		},
+		getMeter: (name, version) => {
+			warnDeprecation("getMeter", "observability.getMeter");
+			return observability.getMeter(name, version);
+		},
+		getTraceContext: () => {
+			warnDeprecation("getTraceContext", "observability.getTraceContext");
+			return observability.getTraceContext();
+		},
+		getActiveSpan: () => {
+			warnDeprecation("getActiveSpan", "observability.getActiveSpan");
+			return observability.getActiveSpan();
+		},
+		createHttpClient: (options) => {
+			warnDeprecation("createHttpClient", "http.createClient");
+			return httpModule.createClient(options);
+		},
+		shutdown: () => {
+			warnDeprecation("shutdown", "lifecycle.shutdown");
+			return lifecycle.shutdown();
 		},
 		isReady: () => {
-			if (features.tracing && !tracingError && !isTracingEnabled()) return false;
-			if (features.metrics && !metricsError && !isMetricsEnabled()) return false;
-			return true;
+			warnDeprecation("isReady", "lifecycle.isReady");
+			return lifecycle.isReady();
 		},
 		health: () => {
-			const tracingUp = !features.tracing || !tracingError && isTracingEnabled();
-			const metricsUp = !features.metrics || !metricsError && isMetricsEnabled();
-			const loggingUp = !loggingError;
-			const allUp = tracingUp && metricsUp && loggingUp;
-			const anyDown = features.tracing && tracingError || features.metrics && metricsError || loggingError;
-			return {
-				status: allUp ? "healthy" : anyDown ? "degraded" : "unhealthy",
-				timestamp: new Date().toISOString(),
-				service: serviceName,
-				version: serviceVersion,
-				uptime: Math.floor((Date.now() - startTime) / 1e3),
-				components: {
-					tracing: {
-						enabled: features.tracing,
-						status: !features.tracing ? "disabled" : tracingError ? "down" : "up",
-						message: tracingError
-					},
-					metrics: {
-						enabled: features.metrics,
-						status: !features.metrics ? "disabled" : metricsError ? "down" : "up",
-						message: metricsError
-					},
-					logging: {
-						enabled: features.logging,
-						status: loggingError ? "down" : "up",
-						message: loggingError
-					}
-				}
-			};
+			warnDeprecation("health", "lifecycle.health");
+			return lifecycle.health();
 		},
-		trace: async (name, fn) => {
-			const tracer = tracerInstance || getTracer(serviceName);
-			return new Promise((resolve, reject) => {
-				tracer.startActiveSpan(name, async (span) => {
-					try {
-						const result = await fn();
-						span.setStatus({ code: SpanStatusCode.OK });
-						span.end();
-						resolve(result);
-					} catch (err) {
-						const error = err;
-						span.setStatus({
-							code: SpanStatusCode.ERROR,
-							message: error.message
-						});
-						span.recordException(error);
-						span.end();
-						logger.error({
-							span: name,
-							error: error.message
-						}, "Span failed");
-						reject(error);
-					}
-				});
-			});
+		trace: (name, fn) => {
+			warnDeprecation("trace", "observability.trace");
+			return observability.trace(name, fn);
 		},
-		safeRun: async (fn, fallback) => {
-			try {
-				return await fn();
-			} catch (err) {
-				const error = err;
-				logger.error({
-					error: error.message,
-					stack: error.stack
-				}, "safeRun caught error");
-				return fallback;
-			}
+		safeRun: (fn, fallback) => {
+			warnDeprecation("safeRun", "lifecycle.safeRun");
+			return lifecycle.safeRun(fn, fallback);
 		}
 	};
 	return foundation;
@@ -835,5 +1180,254 @@ function createFoundation(input) {
 const setupObservability = createFoundation;
 
 //#endregion
-export { AutoInstrumentationConfigSchema, FeaturesConfigSchema, FoundationConfigSchema, LoggingConfigSchema, OtelConfigSchema, RequestLoggingConfigSchema, SpanStatusCode, context, createContextManager, createFallbackLogger, createFoundation, createHttpClient, createLogger, createObservabilityPlugin, getActiveSpan, getDefaultOtelEndpoint, getGlobalLogger, getMeter, getTraceContext, getTracer, isMetricsEnabled, isTracingEnabled, metrics, parseConfig, propagation, setGlobalLogger, setupMetrics, setupObservability, setupTracing, shutdownMetrics, shutdownTracing, trace };
+//#region src/integrations/object-store/aws-s3.ts
+async function loadAwsS3() {
+	try {
+		const clientMod = await import("@aws-sdk/client-s3");
+		const presignerMod = await import("@aws-sdk/s3-request-presigner");
+		return {
+			S3Client: clientMod.S3Client,
+			PutObjectCommand: clientMod.PutObjectCommand,
+			GetObjectCommand: clientMod.GetObjectCommand,
+			HeadObjectCommand: clientMod.HeadObjectCommand,
+			DeleteObjectCommand: clientMod.DeleteObjectCommand,
+			ListObjectsV2Command: clientMod.ListObjectsV2Command,
+			getSignedUrl: presignerMod.getSignedUrl
+		};
+	} catch (err) {
+		const e = err;
+		throw new Error(`AWS SDK not available. Install optional peer deps: @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner. Original error: ${e.message}`);
+	}
+}
+function normalizeBody(body) {
+	return body;
+}
+/**
+* AwsS3ObjectStore - wraps AWS S3 behind the provider-agnostic `ObjectStore` interface.
+*
+* This implementation uses dynamic imports so `neoiq-foundation-node` can be used without AWS SDK.
+*/
+var AwsS3ObjectStore = class {
+	provider = "aws-s3";
+	clientPromise;
+	awsPromise = loadAwsS3();
+	constructor(options = {}) {
+		if (options.client) {
+			this.clientPromise = Promise.resolve(options.client);
+			return;
+		}
+		this.clientPromise = (async () => {
+			const aws = await this.awsPromise;
+			return new aws.S3Client(options.clientOptions ?? {});
+		})();
+	}
+	async client() {
+		return this.clientPromise;
+	}
+	async putObject(ref, body, options = {}) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		const res = await s3.send(new aws.PutObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key,
+			Body: normalizeBody(body),
+			ContentType: options.contentType,
+			CacheControl: options.cacheControl,
+			Metadata: options.metadata
+		}));
+		return {
+			etag: res?.ETag,
+			versionId: res?.VersionId
+		};
+	}
+	async getObject(ref) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		const res = await s3.send(new aws.GetObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key
+		}));
+		if (!res?.Body) {
+			const err = new Error(`S3 GetObject returned empty body: ${ref.bucket}/${ref.key}`);
+			err.code = "EMPTY_BODY";
+			throw err;
+		}
+		return {
+			body: res.Body,
+			contentType: res.ContentType,
+			contentLength: res.ContentLength,
+			etag: res.ETag,
+			versionId: res.VersionId,
+			metadata: res.Metadata,
+			lastModified: res.LastModified
+		};
+	}
+	async headObject(ref) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		try {
+			const res = await s3.send(new aws.HeadObjectCommand({
+				Bucket: ref.bucket,
+				Key: ref.key
+			}));
+			return {
+				exists: true,
+				contentType: res.ContentType,
+				contentLength: res.ContentLength,
+				etag: res.ETag,
+				versionId: res.VersionId,
+				metadata: res.Metadata,
+				lastModified: res.LastModified
+			};
+		} catch (err) {
+			const e = err;
+			const name = String(e?.name || "");
+			const httpStatus = e?.$metadata?.httpStatusCode;
+			if (httpStatus === 404 || name.includes("NotFound") || name.includes("NoSuchKey")) return { exists: false };
+			throw err;
+		}
+	}
+	async deleteObject(ref) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		await s3.send(new aws.DeleteObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key
+		}));
+	}
+	async listObjects(options) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		const res = await s3.send(new aws.ListObjectsV2Command({
+			Bucket: options.bucket,
+			Prefix: options.prefix,
+			ContinuationToken: options.continuationToken,
+			MaxKeys: options.maxKeys
+		}));
+		return {
+			objects: (res?.Contents ?? []).map((o) => ({
+				key: o.Key,
+				size: o.Size,
+				etag: o.ETag,
+				lastModified: o.LastModified
+			})),
+			nextContinuationToken: res?.NextContinuationToken
+		};
+	}
+	async presignGetObject(ref, options) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		return aws.getSignedUrl(s3, new aws.GetObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key,
+			ResponseContentType: options.responseContentType
+		}), { expiresIn: options.expiresInSeconds });
+	}
+	async presignPutObject(ref, options) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		return aws.getSignedUrl(s3, new aws.PutObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key,
+			ContentType: options.contentType
+		}), { expiresIn: options.expiresInSeconds });
+	}
+};
+
+//#endregion
+//#region src/integrations/object-store/in-memory.ts
+function toBuffer(body) {
+	if (typeof body === "string") return Buffer.from(body);
+	if (Buffer.isBuffer(body)) return body;
+	if (body instanceof Uint8Array) return Buffer.from(body);
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		body.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+		body.on("end", () => resolve(Buffer.concat(chunks)));
+		body.on("error", reject);
+	});
+}
+function simpleEtag(buf) {
+	return `mem-${buf.length}-${buf.subarray(0, 8).toString("hex")}`;
+}
+/**
+* InMemoryObjectStore - useful for local dev, unit tests, and as a safe default.
+* NOTE: presign* methods are not meaningful here and will throw.
+*/
+var InMemoryObjectStore = class {
+	provider = "in-memory";
+	buckets = new Map();
+	bucketMap(bucket) {
+		let m = this.buckets.get(bucket);
+		if (!m) {
+			m = new Map();
+			this.buckets.set(bucket, m);
+		}
+		return m;
+	}
+	async putObject(ref, body, options = {}) {
+		const buf = await toBuffer(body);
+		const obj = {
+			body: buf,
+			contentType: options.contentType,
+			cacheControl: options.cacheControl,
+			metadata: options.metadata,
+			etag: simpleEtag(buf),
+			lastModified: new Date()
+		};
+		this.bucketMap(ref.bucket).set(ref.key, obj);
+		return { etag: obj.etag };
+	}
+	async getObject(ref) {
+		const obj = this.bucketMap(ref.bucket).get(ref.key);
+		if (!obj) {
+			const err = new Error(`Object not found: ${ref.bucket}/${ref.key}`);
+			err.code = "OBJECT_NOT_FOUND";
+			throw err;
+		}
+		return {
+			body: Readable.from(obj.body),
+			contentType: obj.contentType,
+			contentLength: obj.body.length,
+			etag: obj.etag,
+			metadata: obj.metadata,
+			lastModified: obj.lastModified
+		};
+	}
+	async headObject(ref) {
+		const obj = this.bucketMap(ref.bucket).get(ref.key);
+		if (!obj) return { exists: false };
+		return {
+			exists: true,
+			contentType: obj.contentType,
+			contentLength: obj.body.length,
+			etag: obj.etag,
+			metadata: obj.metadata,
+			lastModified: obj.lastModified
+		};
+	}
+	async deleteObject(ref) {
+		this.bucketMap(ref.bucket).delete(ref.key);
+	}
+	async listObjects(options) {
+		const { bucket, prefix = "" } = options;
+		const map = this.bucketMap(bucket);
+		const objects = [...map.entries()].filter(([key]) => key.startsWith(prefix)).map(([key, obj]) => ({
+			key,
+			size: obj.body.length,
+			etag: obj.etag,
+			lastModified: obj.lastModified
+		})).sort((a, b) => a.key.localeCompare(b.key));
+		return { objects };
+	}
+	async presignGetObject(_ref, _options) {
+		throw new Error("InMemoryObjectStore does not support presigned URLs");
+	}
+	async presignPutObject(_ref, _options) {
+		throw new Error("InMemoryObjectStore does not support presigned URLs");
+	}
+};
+
+//#endregion
+export { AutoInstrumentationConfigSchema, AwsS3ObjectStore, FeaturesConfigSchema, FoundationConfigSchema, InMemoryObjectStore, LoggingConfigSchema, OtelConfigSchema, REDACT_PATHS, RedactionConfigSchema, RequestLoggingConfigSchema, ShutdownConfigSchema, SpanStatusCode, buildPinoRedactConfig, context, createContextManager, createFallbackLogger, createFoundation, createHttpClient, createLogger, createObservabilityPlugin, getActiveSpan, getDefaultOtelEndpoint, getGlobalLogger, getMeter, getTraceContext, getTracer, isMetricsEnabled, isTracingEnabled, metrics, parseConfig, propagation, sanitizeBody, setGlobalLogger, setupMetrics, setupObservability, setupTracing, shutdownMetrics, shutdownTracing, trace };
 //# sourceMappingURL=index.mjs.map