@geekmidas/services 1.0.2 → 1.0.4

package/dist/{context-BVeZOvOd.d.cts → context-D5pIUGkm.d.cts}

@@ -1,4 +1,4 @@
-import { ServiceContext } from "./types-D7d_yeU5.cjs";
+import { ServiceContext } from "./types-BY9yrY6Y.cjs";
 import { Logger } from "@geekmidas/logger";
 
 //#region src/context.d.ts
@@ -39,7 +39,26 @@ declare const serviceContext: ServiceContext;
  * ```
  */
 declare function runWithRequestContext<T>(data: RequestContextData, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Mutate the current async task's store so that subsequent code in this task
+ * (and any descendants) sees the supplied request context.
+ *
+ * Unlike `runWithRequestContext`, this does not scope the context to a
+ * callback — useful when the caller can't wrap a function, for example in a
+ * Vitest fixture that suspends on `use()` and yields control to the test
+ * runner before the test body executes.
+ *
+ * **Test setup only.** In production handlers, prefer `runWithRequestContext`
+ * so the frame is automatically cleaned up.
+ */
+declare function enterRequestContext(data: RequestContextData): void;
+/**
+ * Clear the request context for the current async task. Pairs with
+ * `enterRequestContext`. After calling, `serviceContext.hasContext()` returns
+ * false for the remainder of the current async resource.
+ */
+declare function exitRequestContext(): void;
 //# sourceMappingURL=context.d.ts.map
 //#endregion
-export { RequestContextData, runWithRequestContext, serviceContext };
-//# sourceMappingURL=context-BVeZOvOd.d.cts.map
+export { RequestContextData, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext };
+//# sourceMappingURL=context-D5pIUGkm.d.cts.map

package/dist/context-D5pIUGkm.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-D5pIUGkm.d.cts","names":[],"sources":["../src/context.ts"],"sourcesContent":[],"mappings":";;;;;;;AAQA;AAiHA;AA0DgB,UA3KC,kBAAA,CA2KoB;EAAA,MAAA,EA1K5B,MA0K4B;EAAA,SAC9B,EAAA,MAAA;EAAkB,SACd,EAAA,MAAA;;;;;;AACG;AAgBE,cA7EH,cA6EsB,EA7EN,cA6Ea;AAS1C;;;;;;;;;;;;;;;;;;;;iBA5BgB,+BACT,8BACI,IAAI,QAAQ,KACpB,IAAI,QAAQ;;;;;;;;;;;;;iBAgBC,mBAAA,OAA0B;;;;;;iBAS1B,kBAAA,CAAA"}

package/dist/{context-DMExgNzl.d.mts → context-OmKid3Mr.d.mts}

@@ -1,4 +1,4 @@
-import { ServiceContext } from "./types-CcHmCx_U.mjs";
+import { ServiceContext } from "./types-B99KrvXR.mjs";
 import { Logger } from "@geekmidas/logger";
 
 //#region src/context.d.ts
@@ -39,7 +39,26 @@ declare const serviceContext: ServiceContext;
  * ```
  */
 declare function runWithRequestContext<T>(data: RequestContextData, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Mutate the current async task's store so that subsequent code in this task
+ * (and any descendants) sees the supplied request context.
+ *
+ * Unlike `runWithRequestContext`, this does not scope the context to a
+ * callback — useful when the caller can't wrap a function, for example in a
+ * Vitest fixture that suspends on `use()` and yields control to the test
+ * runner before the test body executes.
+ *
+ * **Test setup only.** In production handlers, prefer `runWithRequestContext`
+ * so the frame is automatically cleaned up.
+ */
+declare function enterRequestContext(data: RequestContextData): void;
+/**
+ * Clear the request context for the current async task. Pairs with
+ * `enterRequestContext`. After calling, `serviceContext.hasContext()` returns
+ * false for the remainder of the current async resource.
+ */
+declare function exitRequestContext(): void;
 //# sourceMappingURL=context.d.ts.map
 //#endregion
-export { RequestContextData, runWithRequestContext, serviceContext };
-//# sourceMappingURL=context-DMExgNzl.d.mts.map
+export { RequestContextData, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext };
+//# sourceMappingURL=context-OmKid3Mr.d.mts.map

package/dist/context-OmKid3Mr.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-OmKid3Mr.d.mts","names":[],"sources":["../src/context.ts"],"sourcesContent":[],"mappings":";;;;;;;AAQA;AAiHA;AA0DgB,UA3KC,kBAAA,CA2KoB;EAAA,MAAA,EA1K5B,MA0K4B;EAAA,SAC9B,EAAA,MAAA;EAAkB,SACd,EAAA,MAAA;;;;;;AACG;AAgBE,cA7EH,cA6EsB,EA7EN,cA6Ea;AAS1C;;;;;;;;;;;;;;;;;;;;iBA5BgB,+BACT,8BACI,IAAI,QAAQ,KACpB,IAAI,QAAQ;;;;;;;;;;;;;iBAgBC,mBAAA,OAA0B;;;;;;iBAS1B,kBAAA,CAAA"}

package/dist/context.cjs

@@ -1,4 +1,6 @@
-const require_context = require('./context-DUTDtYd2.cjs');
+const require_context = require('./context-CkCPt2Fe.cjs');
 
+exports.enterRequestContext = require_context.enterRequestContext;
+exports.exitRequestContext = require_context.exitRequestContext;
 exports.runWithRequestContext = require_context.runWithRequestContext;
 exports.serviceContext = require_context.serviceContext;

package/dist/context.d.cts

@@ -1,3 +1,3 @@
-import "./types-D7d_yeU5.cjs";
-import { RequestContextData, runWithRequestContext, serviceContext } from "./context-BVeZOvOd.cjs";
-export { RequestContextData, runWithRequestContext, serviceContext };
+import "./types-BY9yrY6Y.cjs";
+import { RequestContextData, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext } from "./context-D5pIUGkm.cjs";
+export { RequestContextData, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext };

package/dist/context.d.mts

@@ -1,3 +1,3 @@
-import "./types-CcHmCx_U.mjs";
-import { RequestContextData, runWithRequestContext, serviceContext } from "./context-DMExgNzl.mjs";
-export { RequestContextData, runWithRequestContext, serviceContext };
+import "./types-B99KrvXR.mjs";
+import { RequestContextData, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext } from "./context-OmKid3Mr.mjs";
+export { RequestContextData, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext };

package/dist/context.mjs

@@ -1,3 +1,3 @@
-import { runWithRequestContext, serviceContext } from "./context-B5YTspJR.mjs";
+import { enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext } from "./context-BojeLlxs.mjs";
 
-export { runWithRequestContext, serviceContext };
+export { enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext };

package/dist/index.cjs

@@ -1,6 +1,8 @@
-const require_context = require('./context-DUTDtYd2.cjs');
-const require_ServiceDiscovery = require('./ServiceDiscovery-YeM2FZsl.cjs');
+const require_context = require('./context-CkCPt2Fe.cjs');
+const require_ServiceDiscovery = require('./ServiceDiscovery-Cxus7ber.cjs');
 
 exports.ServiceDiscovery = require_ServiceDiscovery.ServiceDiscovery;
+exports.enterRequestContext = require_context.enterRequestContext;
+exports.exitRequestContext = require_context.exitRequestContext;
 exports.runWithRequestContext = require_context.runWithRequestContext;
 exports.serviceContext = require_context.serviceContext;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Service, ServiceContext, ServiceRegisterOptions } from "./types-D7d_yeU5.cjs";
-import { ExtractServiceNames, ServiceDiscovery, ServiceRecord } from "./ServiceDiscovery-Dvqa-Q1_.cjs";
-import { RequestContextData, runWithRequestContext, serviceContext } from "./context-BVeZOvOd.cjs";
-export { ExtractServiceNames, RequestContextData, Service, ServiceContext, ServiceDiscovery, ServiceRecord, ServiceRegisterOptions, runWithRequestContext, serviceContext };
+import { Service, ServiceContext, ServiceRegisterOptions } from "./types-BY9yrY6Y.cjs";
+import { ExtractServiceNames, ServiceDiscovery, ServiceRecord } from "./ServiceDiscovery-DF4OKEZp.cjs";
+import { RequestContextData, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext } from "./context-D5pIUGkm.cjs";
+export { ExtractServiceNames, RequestContextData, Service, ServiceContext, ServiceDiscovery, ServiceRecord, ServiceRegisterOptions, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Service, ServiceContext, ServiceRegisterOptions } from "./types-CcHmCx_U.mjs";
-import { ExtractServiceNames, ServiceDiscovery, ServiceRecord } from "./ServiceDiscovery-ykolgkIj.mjs";
-import { RequestContextData, runWithRequestContext, serviceContext } from "./context-DMExgNzl.mjs";
-export { ExtractServiceNames, RequestContextData, Service, ServiceContext, ServiceDiscovery, ServiceRecord, ServiceRegisterOptions, runWithRequestContext, serviceContext };
+import { Service, ServiceContext, ServiceRegisterOptions } from "./types-B99KrvXR.mjs";
+import { ExtractServiceNames, ServiceDiscovery, ServiceRecord } from "./ServiceDiscovery-CadEgTKz.mjs";
+import { RequestContextData, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext } from "./context-OmKid3Mr.mjs";
+export { ExtractServiceNames, RequestContextData, Service, ServiceContext, ServiceDiscovery, ServiceRecord, ServiceRegisterOptions, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { runWithRequestContext, serviceContext } from "./context-B5YTspJR.mjs";
-import { ServiceDiscovery } from "./ServiceDiscovery-BQ45ZFgI.mjs";
+import { enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext } from "./context-BojeLlxs.mjs";
+import { ServiceDiscovery } from "./ServiceDiscovery-SujDuYHr.mjs";
 
-export { ServiceDiscovery, runWithRequestContext, serviceContext };
+export { ServiceDiscovery, enterRequestContext, exitRequestContext, runWithRequestContext, serviceContext };

package/dist/{types-CcHmCx_U.d.mts → types-B99KrvXR.d.mts}

@@ -11,6 +11,13 @@ import { Logger } from "@geekmidas/logger";
 interface ServiceContext {
   /**
    * Get the current request's logger.
+   *
+   * Returns a **request-scoped proxy** that re-resolves the underlying logger
+   * from AsyncLocalStorage on every call. This makes it safe for a singleton
+   * service to capture the logger once (e.g. during `register()`) and reuse it
+   * across requests — each log call routes to the current request's logger
+   * instead of freezing the first request's logger.
+   *
    * @throws Error if called outside a request context
    */
   getLogger(): Logger;
@@ -83,4 +90,4 @@ interface Service<TName extends string = string, TInstance = unknown> {
 //# sourceMappingURL=types.d.ts.map
 //#endregion
 export { Service, ServiceContext, ServiceRegisterOptions };
-//# sourceMappingURL=types-CcHmCx_U.d.mts.map
+//# sourceMappingURL=types-B99KrvXR.d.mts.map

package/dist/types-B99KrvXR.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-B99KrvXR.d.mts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAQA;AAqCA;;AAEY,UAvCK,cAAA,CAuCL;EAAiB;AAEL;AA8BxB;;;;;;;AAW+D;;eAtEjD;;;;;;;;;;;;;;;;;;;;;UAyBG,sBAAA;;aAEL;;WAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA8BO;;;;eAIH;;;;;;;oBAOK,yBAAyB,YAAY,QAAQ"}

package/dist/{types-D7d_yeU5.d.cts → types-BY9yrY6Y.d.cts}

@@ -11,6 +11,13 @@ import { Logger } from "@geekmidas/logger";
 interface ServiceContext {
   /**
    * Get the current request's logger.
+   *
+   * Returns a **request-scoped proxy** that re-resolves the underlying logger
+   * from AsyncLocalStorage on every call. This makes it safe for a singleton
+   * service to capture the logger once (e.g. during `register()`) and reuse it
+   * across requests — each log call routes to the current request's logger
+   * instead of freezing the first request's logger.
+   *
    * @throws Error if called outside a request context
    */
   getLogger(): Logger;
@@ -83,4 +90,4 @@ interface Service<TName extends string = string, TInstance = unknown> {
 //# sourceMappingURL=types.d.ts.map
 //#endregion
 export { Service, ServiceContext, ServiceRegisterOptions };
-//# sourceMappingURL=types-D7d_yeU5.d.cts.map
+//# sourceMappingURL=types-BY9yrY6Y.d.cts.map

package/dist/types-BY9yrY6Y.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-BY9yrY6Y.d.cts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAQA;AAqCA;;AAEY,UAvCK,cAAA,CAuCL;EAAiB;AAEL;AA8BxB;;;;;;;AAW+D;;eAtEjD;;;;;;;;;;;;;;;;;;;;;UAyBG,sBAAA;;aAEL;;WAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA8BO;;;;eAIH;;;;;;;oBAOK,yBAAyB,YAAY,QAAQ"}

package/dist/types.d.cts

@@ -1,2 +1,2 @@
-import { Service, ServiceContext, ServiceRegisterOptions } from "./types-D7d_yeU5.cjs";
+import { Service, ServiceContext, ServiceRegisterOptions } from "./types-BY9yrY6Y.cjs";
 export { Service, ServiceContext, ServiceRegisterOptions };

package/dist/types.d.mts

@@ -1,2 +1,2 @@
-import { Service, ServiceContext, ServiceRegisterOptions } from "./types-CcHmCx_U.mjs";
+import { Service, ServiceContext, ServiceRegisterOptions } from "./types-B99KrvXR.mjs";
 export { Service, ServiceContext, ServiceRegisterOptions };

package/docs/request-scoped-logging.md

@@ -0,0 +1,153 @@
+# Request-Scoped Logging in Singleton Services
+
+## Problem
+
+Services in `@geekmidas/services` are **singletons**. `ServiceDiscovery.register()`
+(and `get()`) instantiates a service **once**, caches the instance in an internal
+`Map`, and returns that same instance for every subsequent request:
+
+```ts
+// ServiceDiscovery.register()
+if (this.instances.has(name)) {
+  return this.instances.get(name); // cached — register() does NOT run again
+}
+const instance = await service.register({ envParser, context: serviceContext });
+this.instances.set(name, instance);
+```
+
+The per-request logger, on the other hand, is **not** a singleton. On every request
+an adaptor builds a fresh child logger with request-specific bindings and stores it
+in `AsyncLocalStorage` via `runWithRequestContext`:
+
+```ts
+// e.g. HonoEndpointAdaptor
+const logger = endpoint.logger.child({
+  requestId,          // unique per request
+  endpoint, route, host, method, path,
+});
+
+return runWithRequestContext({ logger, requestId, startTime }, async () => {
+  const services = await serviceDiscovery.register(endpoint.services);
+  // ...handle request...
+});
+```
+
+### The bug
+
+`service.register()` runs **inside the first request's context**. If a service reads
+the logger **at registration time** and stores the concrete reference:
+
+```ts
+const databaseService = {
+  serviceName: 'database' as const,
+  register({ context }) {
+    const logger = context.getLogger(); // ❌ resolved ONCE, during request #1
+
+    return {
+      async query(sql: string) {
+        logger.debug({ sql }, 'Executing query'); // always request #1's logger
+      },
+    };
+  },
+} satisfies Service<'database', Database>;
+```
+
+…then `logger` is frozen to the **first** request's logger forever, because
+`register()` never runs again. Every later request reuses the cached service
+instance, so its logs carry the **first** request's `requestId` (and any user/session
+bindings).
+
+**Symptom:** logs make it look like the user who made the *first* request after a
+cold start is responsible for actions actually performed by *other* users on later
+requests. Request correlation, per-user log filtering, and audit trails are all
+silently wrong.
+
+This is an easy mistake to make because `register()` is handed a `context` object,
+and "grab the logger once and reuse it" looks reasonable — but it is incompatible
+with the singleton lifecycle.
+
+## Solution
+
+`serviceContext.getLogger()` returns a **stable, request-scoped proxy logger**
+instead of the raw logger. The proxy holds no logger of its own — on **every** log
+call it re-resolves the current request's logger from `AsyncLocalStorage`:
+
+```
+proxy.info('x')  →  asyncLocalStorage.getStore().logger.info('x')   // resolved at call time
+```
+
+Because resolution happens per call (not at capture time), capturing the logger once
+during `register()` is now **safe**: the single captured reference routes each call
+to whichever request is currently executing.
+
+```ts
+register({ context }) {
+  const logger = context.getLogger(); // ✅ now safe to capture — it's a live proxy
+
+  return {
+    async query(sql: string) {
+      logger.debug({ sql }, 'Executing query'); // logs to the CURRENT request
+    },
+  };
+}
+```
+
+### Child loggers compose correctly too
+
+`proxy.child(bindings)` returns **another** proxy carrying the bindings, applied lazily
+on top of the current request's logger at call time:
+
+```ts
+register({ context }) {
+  // Captured once. `{ svc: 'db' }` is the static part; the per-request bindings
+  // (requestId, user, ...) come from whichever base logger is current.
+  const logger = context.getLogger().child({ svc: 'db' });
+
+  return {
+    async query(sql: string) {
+      // request A → loggerA.child({ svc: 'db' }).debug(...)
+      // request B → loggerB.child({ svc: 'db' }).debug(...)
+      logger.debug({ sql }, 'Executing query');
+    },
+  };
+}
+```
+
+### Implementation
+
+See `createRequestScopedLogger` in
+[`src/context.ts`](../src/context.ts):
+
+- `getLogger()` still **throws eagerly** if called with no active request context,
+  preserving the "catch bugs early" contract.
+- The returned object is a shared, process-wide proxy. It carries no request state,
+  so sharing it across requests is safe — `AsyncLocalStorage` provides correct
+  per-async-context isolation, and each resolve/log call is synchronous (no `await`
+  between resolving and using the logger), so it is concurrency-safe.
+- Each `child()` call returns a new proxy that remembers its bindings and rebuilds
+  the child chain off the current base logger, memoised per underlying logger to
+  avoid rebuilding the chain on every log line.
+
+## Guidance for service authors
+
+- ✅ You **may** capture `context.getLogger()` (or a `.child()` of it) once in
+  `register()` and reuse it — it stays correct per request.
+- ✅ You **may** also call `context.getLogger()` inside each method; behaviour is
+  identical.
+- ⚠️ Do **not** wrap the proxy in something that snapshots a concrete logger, e.g.
+  `const real = someConcreteLogger; ...` outside the proxy. Resolution only stays
+  live while you go through the proxy returned by `getLogger()`/`.child()`.
+- ⚠️ Calling a log method outside any request context throws
+  (`called outside request context`). Guard background work with
+  `serviceContext.hasContext()` if it may run detached from a request.
+
+## Tests
+
+Regression coverage lives in
+[`src/__tests__/context.spec.ts`](../src/__tests__/context.spec.ts):
+
+- `captured-once logger follows each request (singleton service fix)` — a logger
+  captured during the first request still logs to the second request's logger.
+- `child loggers also follow the current request` — the same guarantee for
+  `.child()` proxies.
+- `should delegate to the current request logger` — basic delegation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/services",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "private": false,
   "type": "module",
   "exports": {

package/src/__tests__/context.spec.ts

@@ -1,7 +1,40 @@
+import type { Logger } from '@geekmidas/logger';
 import { ConsoleLogger } from '@geekmidas/logger/console';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { runWithRequestContext, serviceContext } from '../context';
 
+/** Minimal spy logger whose `child()` returns itself for easy assertions. */
+function makeSpyLogger(): Logger {
+	const logger: Logger = {
+		trace: vi.fn(),
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		fatal: vi.fn(),
+		child: vi.fn(() => logger),
+	};
+	return logger;
+}
+
+/**
+ * A logger that carries MORE than the base `Logger` interface: an extra method
+ * (`flush`) and a data property (`level`). Models a richer real-world logger
+ * (e.g. pino) so we can assert the request-scoped proxy forwards the full
+ * surface, not just the known log methods.
+ */
+type ExtendedLogger = Logger & {
+	flush: ReturnType<typeof vi.fn>;
+	level: string;
+};
+
+function makeExtendedSpyLogger(level = 'info'): ExtendedLogger {
+	const logger = makeSpyLogger() as ExtendedLogger;
+	logger.flush = vi.fn();
+	logger.level = level;
+	return logger;
+}
+
 describe('Request Context', () => {
 	const logger = new ConsoleLogger({ app: 'test' });
 
@@ -28,13 +61,156 @@ describe('Request Context', () => {
 				);
 			});
 
-			it('should return logger inside request context', async () => {
+			it('should delegate to the current request logger', async () => {
+				const requestLogger = makeSpyLogger();
 				await runWithRequestContext(
-					{ logger, requestId: 'test-id', startTime: Date.now() },
+					{
+						logger: requestLogger,
+						requestId: 'test-id',
+						startTime: Date.now(),
+					},
 					async () => {
-						expect(serviceContext.getLogger()).toBe(logger);
+						serviceContext.getLogger().info('hello');
 					},
 				);
+				expect(requestLogger.info).toHaveBeenCalledWith('hello');
+			});
+
+			it('captured-once logger follows each request (singleton service fix)', async () => {
+				// Mimic a singleton service that grabs the logger ONCE (during its
+				// one-time register) and reuses that reference for every request.
+				let captured: Logger | undefined;
+				const handle = (requestLogger: Logger) =>
+					runWithRequestContext(
+						{ logger: requestLogger, requestId: 'r', startTime: Date.now() },
+						async () => {
+							captured ??= serviceContext.getLogger();
+							captured.info('handled');
+						},
+					);
+
+				const first = makeSpyLogger();
+				const second = makeSpyLogger();
+				await handle(first);
+				await handle(second);
+
+				// Before the fix, the captured logger stayed bound to `first`, so
+				// `second` never saw the call.
+				expect(first.info).toHaveBeenCalledTimes(1);
+				expect(second.info).toHaveBeenCalledTimes(1);
+			});
+
+			it('child loggers also follow the current request', async () => {
+				let capturedChild: Logger | undefined;
+				const handle = (requestLogger: Logger) =>
+					runWithRequestContext(
+						{ logger: requestLogger, requestId: 'r', startTime: Date.now() },
+						async () => {
+							capturedChild ??= serviceContext
+								.getLogger()
+								.child({ scope: 'svc' });
+							capturedChild.info('scoped');
+						},
+					);
+
+				const first = makeSpyLogger();
+				const second = makeSpyLogger();
+				await handle(first);
+				await handle(second);
+
+				expect(first.child).toHaveBeenCalledWith({ scope: 'svc' });
+				expect(second.child).toHaveBeenCalledWith({ scope: 'svc' });
+				expect(first.info).toHaveBeenCalledWith('scoped');
+				expect(second.info).toHaveBeenCalledWith('scoped');
+			});
+
+			describe('forwards the full logger surface (logger with more)', () => {
+				it('forwards an extra method beyond the Logger interface', async () => {
+					const requestLogger = makeExtendedSpyLogger();
+					await runWithRequestContext(
+						{ logger: requestLogger, requestId: 'r', startTime: Date.now() },
+						async () => {
+							(serviceContext.getLogger() as ExtendedLogger).flush();
+						},
+					);
+					expect(requestLogger.flush).toHaveBeenCalledTimes(1);
+				});
+
+				it('re-resolves an extra method per request when captured once', async () => {
+					let captured: ExtendedLogger | undefined;
+					const handle = (requestLogger: Logger) =>
+						runWithRequestContext(
+							{ logger: requestLogger, requestId: 'r', startTime: Date.now() },
+							async () => {
+								captured ??= serviceContext.getLogger() as ExtendedLogger;
+								captured.flush();
+							},
+						);
+
+					const first = makeExtendedSpyLogger();
+					const second = makeExtendedSpyLogger();
+					await handle(first);
+					await handle(second);
+
+					expect(first.flush).toHaveBeenCalledTimes(1);
+					expect(second.flush).toHaveBeenCalledTimes(1);
+				});
+
+				it('forwards a data property as the current request logger value', async () => {
+					const captureLevel = (requestLogger: Logger) =>
+						runWithRequestContext(
+							{ logger: requestLogger, requestId: 'r', startTime: Date.now() },
+							async () => (serviceContext.getLogger() as ExtendedLogger).level,
+						);
+
+					const debugLogger = makeExtendedSpyLogger('debug');
+					const warnLogger = makeExtendedSpyLogger('warn');
+
+					expect(await captureLevel(debugLogger)).toBe('debug');
+					expect(await captureLevel(warnLogger)).toBe('warn');
+				});
+
+				it('detached method reference still targets the current request', async () => {
+					const requestLogger = makeExtendedSpyLogger();
+					await runWithRequestContext(
+						{ logger: requestLogger, requestId: 'r', startTime: Date.now() },
+						async () => {
+							const { info } = serviceContext.getLogger();
+							info('detached');
+						},
+					);
+					expect(requestLogger.info).toHaveBeenCalledWith('detached');
+				});
+
+				it('reflects underlying membership via the `in` operator', async () => {
+					const requestLogger = makeExtendedSpyLogger();
+					await runWithRequestContext(
+						{ logger: requestLogger, requestId: 'r', startTime: Date.now() },
+						async () => {
+							const proxy = serviceContext.getLogger();
+							expect('flush' in proxy).toBe(true);
+							expect('child' in proxy).toBe(true);
+							expect('nope' in proxy).toBe(false);
+						},
+					);
+				});
+
+				it('is not thenable (safe to return from async / await)', async () => {
+					await runWithRequestContext(
+						{
+							logger: makeExtendedSpyLogger(),
+							requestId: 'r',
+							startTime: Date.now(),
+						},
+						async () => {
+							const proxy = serviceContext.getLogger();
+							expect((proxy as { then?: unknown }).then).toBeUndefined();
+							// Awaiting a non-thenable yields the value itself rather than
+							// hanging or invoking a spurious `then`.
+							expect(await proxy).toBe(proxy);
+						},
+					);
+				});
 			});
 		});