@nextrush/adapter-edge 1.0.0-beta.0 → 1.0.0-beta.2

package/src/__tests__/boot-reuse-warning.test.ts

@@ -0,0 +1,95 @@
+/**
+ * P1-3a (report/dx-review-serverless-edge-adapters.md): warn, once per
+ * process/isolate, when a SECOND distinct `Application` instance boots
+ * through this module's request runner — the mechanical signature of the
+ * #1 documented cold-start mistake (calling `createApp()`/`createFetchHandler()`
+ * inside the exported handler instead of at module scope, which rebuilds and
+ * reboots the app on every invocation).
+ *
+ * Uses `vi.resetModules()` + dynamic re-import per test so each test gets a
+ * fresh copy of `adapter.ts`'s module-level tracking state, since the whole
+ * point of this feature is that the state persists ACROSS `createFetchHandler`
+ * calls within one module instance.
+ */
+
+import { createApp } from '@nextrush/core';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { createFetchHandler as CreateFetchHandler } from '../adapter';
+
+async function freshAdapterModule(): Promise<{ createFetchHandler: typeof CreateFetchHandler }> {
+  vi.resetModules();
+  return import('../adapter');
+}
+
+function devApp(): ReturnType<typeof createApp> {
+  const app = createApp({ env: 'development' });
+  app.use(async (ctx) => ctx.json({ ok: true }));
+  return app;
+}
+
+describe('boot-reuse warning (P1-3a)', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+  });
+
+  it('does not warn when the same Application boots once', async () => {
+    const { createFetchHandler } = await freshAdapterModule();
+    const app = devApp();
+    const handler = createFetchHandler(app);
+    await handler(new Request('http://localhost/'));
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it('does not warn when the same Application is passed to a second createFetchHandler call (rebuilding the handler, not the app, is not the mistake)', async () => {
+    const { createFetchHandler } = await freshAdapterModule();
+    const app = devApp();
+    await createFetchHandler(app)(new Request('http://localhost/'));
+    await createFetchHandler(app)(new Request('http://localhost/'));
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it('warns once when a second, distinct Application boots in the same module instance', async () => {
+    const { createFetchHandler } = await freshAdapterModule();
+    const appOne = devApp();
+    const appTwo = devApp();
+
+    await createFetchHandler(appOne)(new Request('http://localhost/'));
+    await createFetchHandler(appTwo)(new Request('http://localhost/'));
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]?.[0]).toMatch(/\[nextrush\/edge\].*module scope/i);
+    warnSpy.mockRestore();
+  });
+
+  it('does not warn in production even with two distinct Applications', async () => {
+    const { createFetchHandler } = await freshAdapterModule();
+    const appOne = createApp({ env: 'production' });
+    appOne.use(async (ctx) => ctx.json({ ok: true }));
+    const appTwo = createApp({ env: 'production' });
+    appTwo.use(async (ctx) => ctx.json({ ok: true }));
+
+    await createFetchHandler(appOne)(new Request('http://localhost/'));
+    await createFetchHandler(appTwo)(new Request('http://localhost/'));
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it('warns only once even across a third and fourth distinct Application', async () => {
+    const { createFetchHandler } = await freshAdapterModule();
+    for (let i = 0; i < 4; i++) {
+      const app = devApp();
+      // eslint-disable-next-line no-await-in-loop -- sequential boots are the point of this test
+      await createFetchHandler(app)(new Request('http://localhost/'));
+    }
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    warnSpy.mockRestore();
+  });
+});

package/src/__tests__/context-ip-warning.test.ts

@@ -0,0 +1,67 @@
+/**
+ * @nextrush/adapter-edge - ctx.ip empty-string dev-mode warning (P2-3).
+ *
+ * When `proxy` is `false` (default), `ctx.ip` is `''` on Edge (no
+ * socket to fall back to). Outside production, the first *read* of `ctx.ip`
+ * in that state warns once per context — a silent empty string is otherwise
+ * indistinguishable from "IP resolution succeeded and it's empty."
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { EdgeContext } from '../context';
+
+function mockRequest(headers: Record<string, string> = {}): Request {
+  return new Request('http://localhost/', { headers });
+}
+
+describe('EdgeContext ctx.ip dev-mode warning (P2-3)', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it('warns once, in development, on the first read of ctx.ip when proxy is false', () => {
+    const ctx = new EdgeContext(mockRequest(), undefined, false, undefined, false);
+
+    expect(ctx.ip).toBe('');
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]?.[0]).toContain('[nextrush/edge]');
+    expect(warnSpy.mock.calls[0]?.[0]).toContain('ctx.ip');
+    expect(warnSpy.mock.calls[0]?.[0]).toContain('proxy');
+
+    // Reading it again on the same context does not warn a second time.
+    expect(ctx.ip).toBe('');
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not warn in production, even though ctx.ip is still empty', () => {
+    const ctx = new EdgeContext(mockRequest(), undefined, false, undefined, true);
+
+    expect(ctx.ip).toBe('');
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not warn when proxy is a hop count, even in development', () => {
+    const ctx = new EdgeContext(
+      mockRequest({ 'cf-connecting-ip': '1.2.3.4' }),
+      undefined,
+      1,
+      undefined,
+      false
+    );
+
+    expect(ctx.ip).toBe('1.2.3.4');
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('4.3: rejects a peer-CIDR list at construction — Edge has no peer address to validate against', () => {
+    expect(() => new EdgeContext(mockRequest(), undefined, ['10.0.0.0/8'])).toThrow(
+      /no socket peer address/
+    );
+  });
+});

package/src/__tests__/context-platform.test.ts

@@ -0,0 +1,41 @@
+/**
+ * @nextrush/adapter-edge - ctx.platform Tests (RFC-026 P1)
+ */
+
+import { resetRuntimeCache } from '@nextrush/runtime';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { EdgeContext } from '../context';
+
+function createMockRequest(url = 'http://localhost/'): Request {
+  return new Request(url);
+}
+
+describe('EdgeContext ctx.platform', () => {
+  beforeEach(() => {
+    resetRuntimeCache();
+  });
+
+  afterEach(() => {
+    resetRuntimeCache();
+  });
+
+  it('defaults to undefined when no explicit platform is given and no named edge platform is detected', () => {
+    const ctx = new EdgeContext(createMockRequest());
+
+    expect(ctx.platform).toBeUndefined();
+  });
+
+  it('uses the explicitly-supplied platform over detection', () => {
+    const ctx = new EdgeContext(createMockRequest(), undefined, false, undefined, true, 'lambda');
+
+    expect(ctx.platform).toBe('lambda');
+  });
+
+  it('accepts each serverless PlatformId explicitly', () => {
+    const gcf = new EdgeContext(createMockRequest(), undefined, false, undefined, true, 'gcf');
+    const azure = new EdgeContext(createMockRequest(), undefined, false, undefined, true, 'azure');
+
+    expect(gcf.platform).toBe('gcf');
+    expect(azure.platform).toBe('azure');
+  });
+});

package/src/__tests__/context.test.ts

@@ -98,7 +98,7 @@ describe('EdgeContext', () => {
       request = createMockRequest('http://localhost/', {
         headers: { 'cf-connecting-ip': '192.168.1.100' },
       });
-      ctx = new EdgeContext(request, undefined, true);
+      ctx = new EdgeContext(request, undefined, 1);
 
       expect(ctx.ip).toBe('192.168.1.100');
     });
@@ -107,21 +107,21 @@ describe('EdgeContext', () => {
       request = createMockRequest('http://localhost/', {
         headers: { 'x-forwarded-for': '10.0.0.1, 10.0.0.2' },
       });
-      ctx = new EdgeContext(request, undefined, true);
+      ctx = new EdgeContext(request, undefined, 1);
 
-      expect(ctx.ip).toBe('10.0.0.1');
+      expect(ctx.ip).toBe('10.0.0.2');
     });
 
     it('should extract IP from x-real-ip header', () => {
       request = createMockRequest('http://localhost/', {
         headers: { 'x-real-ip': '172.16.0.1' },
       });
-      ctx = new EdgeContext(request, undefined, true);
+      ctx = new EdgeContext(request, undefined, 1);
 
       expect(ctx.ip).toBe('172.16.0.1');
     });
 
-    it('should not trust proxy headers when trustProxy is false', () => {
+    it('should not trust proxy headers when proxy is false', () => {
       request = createMockRequest('http://localhost/', {
         headers: { 'x-forwarded-for': '10.0.0.1', 'cf-connecting-ip': '192.168.1.100' },
       });
@@ -409,6 +409,41 @@ describe('EdgeContext', () => {
       expect(() => ctx.waitUntil(promise)).not.toThrow();
     });
   });
+
+  describe('waitUntil() dev-mode warning (P2-4)', () => {
+    it('warns once via console.warn when isProduction is explicitly false and no execution context is available', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      ctx = new EdgeContext(request, undefined, false, undefined, false);
+
+      ctx.waitUntil(Promise.resolve());
+      ctx.waitUntil(Promise.resolve());
+
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy.mock.calls[0]?.[0]).toMatch(/\[nextrush\/edge\].*waitUntil/i);
+      warnSpy.mockRestore();
+    });
+
+    it('does not warn when an execution context IS available, even outside production', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      const execCtx = createMockExecutionContext();
+      ctx = new EdgeContext(request, execCtx, false, undefined, false);
+
+      ctx.waitUntil(Promise.resolve());
+
+      expect(warnSpy).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+
+    it('does not warn by default (isProduction defaults to true — safe/silent unless explicitly told otherwise)', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+      ctx = new EdgeContext(request); // no isProduction arg — matches every existing direct-construction call site
+
+      ctx.waitUntil(Promise.resolve());
+
+      expect(warnSpy).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+  });
 });
 
 describe('HttpError', () => {

package/src/__tests__/default-timeout.test.ts

@@ -11,9 +11,12 @@ import { describe, expect, it } from 'vitest';
 import { createFetchHandler, DEFAULT_EDGE_TIMEOUT_MS } from '../adapter';
 
 describe('F-07: Edge default request timeout', () => {
-  it('DEFAULT_EDGE_TIMEOUT_MS is a documented constant under the tightest common edge wall limit', () => {
+  it('DEFAULT_EDGE_TIMEOUT_MS is a documented constant strictly under the tightest common edge wall limit', () => {
     // Vercel Edge Functions: 25s wall limit — the tightest common platform limit.
-    expect(DEFAULT_EDGE_TIMEOUT_MS).toBeLessThanOrEqual(25_000);
+    // Strictly below (not at) the limit (P2-2): equal to it means the framework's
+    // clean 504 races the platform's own kill with no margin, non-deterministically
+    // losing on Vercel.
+    expect(DEFAULT_EDGE_TIMEOUT_MS).toBeLessThan(25_000);
     expect(DEFAULT_EDGE_TIMEOUT_MS).toBeGreaterThan(0);
   });
 

package/src/__tests__/per-request-work-trim.test.ts

@@ -7,15 +7,15 @@
  * (characterization tests, green before and after the trims) AND proves each
  * trim actually happened (optimization-assertion tests, RED before impl):
  *
- *  - HP-1: `trustProxy: false` sets `ctx.ip` to `''` directly (Edge has no
+ *  - HP-1: `proxy: false` sets `ctx.ip` to `''` directly (Edge has no
  *          socket) without invoking the edge header-lookup policy
- *          (`getEdgeClientIp`); `trustProxy: true` still resolves via it,
+ *          (`getEdgeClientIp`); a hop-count `proxy` still resolves via it,
  *          preserving the cf-connecting-ip → x-forwarded-for → x-real-ip
  *          precedence.
  *  - HP-7: `ctx.next()` forwards the wired dispatch thunk directly (returns its
  *          exact promise) rather than wrapping it in an extra `async` frame.
  *
- * Note: HP-4 does NOT apply — the Edge context factory takes `trustProxy`
+ * Note: HP-4 does NOT apply — the Edge context factory takes `proxy`
  * positionally, so there is no per-request options object to hoist.
  */
 
@@ -52,12 +52,12 @@ afterEach(() => {
 describe('HP-1: Edge ctx.ip resolution', () => {
   // ---- parity / characterization (green before and after) -----------------
 
-  it('2.4 trustProxy false → ctx.ip is the empty string (Edge has no socket)', () => {
+  it('2.4 proxy: false → ctx.ip is the empty string (Edge has no socket)', () => {
     const ctx = new EdgeContext(makeRequest(), undefined, false);
     expect(ctx.ip).toBe('');
   });
 
-  it('2.4 trustProxy true + cf-connecting-ip wins the Cloudflare precedence', () => {
+  it('2.4 proxy: 1 (hop count) + cf-connecting-ip wins the Cloudflare precedence', () => {
     const ctx = new EdgeContext(
       makeRequest({
         'cf-connecting-ip': '198.51.100.5',
@@ -65,24 +65,24 @@ describe('HP-1: Edge ctx.ip resolution', () => {
         'x-real-ip': '8.8.8.8',
       }),
       undefined,
-      true
+      1
     );
     expect(ctx.ip).toBe('198.51.100.5');
   });
 
-  it('2.4 trustProxy true + no cf-connecting-ip → x-forwarded-for → x-real-ip precedence', () => {
+  it('2.4 proxy: 1 (hop count) + no cf-connecting-ip → x-forwarded-for → x-real-ip precedence', () => {
     const xff = new EdgeContext(
       makeRequest({ 'x-forwarded-for': '9.9.9.9', 'x-real-ip': '8.8.8.8' }),
       undefined,
-      true
+      1
     );
     expect(xff.ip).toBe('9.9.9.9');
 
-    const real = new EdgeContext(makeRequest({ 'x-real-ip': '8.8.8.8' }), undefined, true);
+    const real = new EdgeContext(makeRequest({ 'x-real-ip': '8.8.8.8' }), undefined, 1);
     expect(real.ip).toBe('8.8.8.8');
   });
 
-  it('2.5 trustProxy false ignores cf-connecting-ip / x-forwarded-for / x-real-ip', () => {
+  it('2.5 proxy: false ignores cf-connecting-ip / x-forwarded-for / x-real-ip', () => {
     const ctx = new EdgeContext(
       makeRequest({
         'cf-connecting-ip': '198.51.100.5',
@@ -97,15 +97,15 @@ describe('HP-1: Edge ctx.ip resolution', () => {
 
   // ---- optimization assertion (RED before HP-1) ----------------------------
 
-  it('2.6 [trim] trustProxy false does NOT invoke getEdgeClientIp', () => {
+  it('2.6 [trim] proxy: false does NOT invoke getEdgeClientIp', () => {
     void new EdgeContext(makeRequest(), undefined, false);
     expect(getEdgeClientIpMock).not.toHaveBeenCalled();
   });
 
-  it('2.6 [trim] trustProxy true still resolves via getEdgeClientIp', () => {
-    void new EdgeContext(makeRequest({ 'cf-connecting-ip': '198.51.100.5' }), undefined, true);
+  it('2.6 [trim] proxy: 1 (hop count) still resolves via getEdgeClientIp', () => {
+    void new EdgeContext(makeRequest({ 'cf-connecting-ip': '198.51.100.5' }), undefined, 1);
     expect(getEdgeClientIpMock).toHaveBeenCalledTimes(1);
-    expect(getEdgeClientIpMock).toHaveBeenCalledWith(expect.any(Request), true);
+    expect(getEdgeClientIpMock).toHaveBeenCalledWith(expect.any(Request), 1);
   });
 });
 

package/src/__tests__/timeout-attribution.test.ts

@@ -0,0 +1,80 @@
+/**
+ * P1-3b (report/dx-review-serverless-edge-adapters.md): when the framework's
+ * own timeout fires (a 504), the error log should name the effective timeout
+ * value AND its source (an explicit `options.timeout` vs. the
+ * `DEFAULT_EDGE_TIMEOUT_MS` fallback) — today a 504 gives no indication of
+ * which timeout fired or why, forcing a developer to go read the adapter's
+ * source to find out.
+ */
+
+import { createApp } from '@nextrush/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createFetchHandler, DEFAULT_EDGE_TIMEOUT_MS } from '../adapter';
+
+function neverSettlingApp(): ReturnType<typeof createApp> {
+  const app = createApp();
+  app.use(async (ctx) => {
+    await new Promise<void>((resolve) => {
+      ctx.signal.addEventListener('abort', () => resolve());
+    });
+  });
+  return app;
+}
+
+describe('timeout attribution on the 504 path (P1-3b)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('logs the effective value and "default" as the source when no explicit timeout was passed', async () => {
+    const app = neverSettlingApp();
+    const warnSpy = vi.spyOn(app.logger, 'warn').mockImplementation(() => undefined);
+    const handler = createFetchHandler(app, {}); // no explicit timeout -> DEFAULT_EDGE_TIMEOUT_MS
+
+    const resPromise = handler(new Request('http://localhost/'));
+    await vi.advanceTimersByTimeAsync(DEFAULT_EDGE_TIMEOUT_MS);
+    const res = await resPromise;
+
+    expect(res.status).toBe(504);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const message = warnSpy.mock.calls[0]?.[0] as string;
+    expect(message).toMatch(/\[nextrush\/edge\]/);
+    expect(message).toMatch(new RegExp(`${DEFAULT_EDGE_TIMEOUT_MS}ms`));
+    expect(message).toMatch(/default/i);
+    warnSpy.mockRestore();
+  });
+
+  it('logs the effective value and "explicit options.timeout" as the source when a timeout is passed', async () => {
+    const app = neverSettlingApp();
+    const warnSpy = vi.spyOn(app.logger, 'warn').mockImplementation(() => undefined);
+    const handler = createFetchHandler(app, { timeout: 12 });
+
+    const resPromise = handler(new Request('http://localhost/'));
+    await vi.advanceTimersByTimeAsync(12);
+    const res = await resPromise;
+
+    expect(res.status).toBe(504);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const message = warnSpy.mock.calls[0]?.[0] as string;
+    expect(message).toMatch(/\[nextrush\/edge\]/);
+    expect(message).toMatch(/12ms/);
+    expect(message).toMatch(/explicit/i);
+    warnSpy.mockRestore();
+  });
+
+  it('does not log a timeout warning when the handler completes before the timeout', async () => {
+    const app = createApp();
+    app.use((ctx) => ctx.json({ ok: true }));
+    const warnSpy = vi.spyOn(app.logger, 'warn').mockImplementation(() => undefined);
+    const handler = createFetchHandler(app, { timeout: 5000 });
+
+    await handler(new Request('http://localhost/'));
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+});

package/src/adapter.ts

@@ -18,7 +18,7 @@
 
 import type { Application } from '@nextrush/core';
 import { jsonErrorResponse } from '@nextrush/runtime';
-import type { AdapterContextFactory, FetchAdapter } from '@nextrush/types';
+import type { AdapterContextFactory, FetchAdapter, PlatformId, ProxyTrust } from '@nextrush/types';
 import { createEdgeContext, EdgeContext, type EdgeExecutionContext } from './context';
 
 /**
@@ -27,13 +27,35 @@ import { createEdgeContext, EdgeContext, type EdgeExecutionContext } from './con
  * default to a bounded timeout rather than none).
  *
  * @remarks
- * 25 000 ms — below the tightest common edge-platform wall limit (Vercel Edge
- * Functions: 25 s), comfortably above typical handler durations, so the
- * framework's clean `504` fires before the platform terminates the isolate.
+ * 24 000 ms — strictly below the tightest common edge-platform wall limit
+ * (Vercel Edge Functions: 25 s exactly), comfortably above typical handler
+ * durations, so the framework's clean `504` reliably fires before the
+ * platform terminates the isolate. A prior value of 25 000 ms sat exactly
+ * *at* that limit rather than below it, racing the platform's own kill with
+ * no margin — this constant is deliberately 1 000 ms under the tightest
+ * limit rather than per-platform-branched, since one shared constant is
+ * simpler to reason about than a platform switch inside a package whose
+ * whole point is one runner for every edge platform.
  * Pass `timeout: 0` to disable the framework timeout entirely (platform limit
  * alone applies) or a positive value to override the default.
  */
-export const DEFAULT_EDGE_TIMEOUT_MS = 25_000;
+export const DEFAULT_EDGE_TIMEOUT_MS = 24_000;
+
+/**
+ * Module-level tracking for the boot-reuse warning (P1-3a).
+ *
+ * @remarks
+ * `bootedApps` records every distinct `Application` that has completed at
+ * least one request through this module instance; `warnedBootReuse` ensures
+ * the warning fires at most once per module instance, not once per extra app.
+ * Module-level (not per-closure) is deliberate: the mistake this catches
+ * (calling `createApp()`/`createFetchHandler()` inside the exported handler)
+ * produces a NEW `createRequestRunner` closure on every invocation, so
+ * per-closure state could never observe a second app.
+ */
+const bootedApps = new WeakSet<Application>();
+let hasBootedAnyApp = false;
+let warnedBootReuse = false;
 
 /**
  * Options for the fetch handler
@@ -50,19 +72,34 @@ export interface FetchHandlerOptions {
    * first, cancelling the still-running handler via `ctx.signal`.
    *
    * @remarks
-   * Defaults to {@link DEFAULT_EDGE_TIMEOUT_MS} (25 000 ms) when omitted
-   * (F-07/ADR-0010) — below the tightest common edge-platform wall limit
-   * (Vercel Edge: 25 s), so the framework's clean `504` fires before the
-   * platform terminates the isolate. Pass `0` to disable the framework
+   * Defaults to {@link DEFAULT_EDGE_TIMEOUT_MS} (24 000 ms) when omitted
+   * (F-07/ADR-0010) — strictly below the tightest common edge-platform wall
+   * limit (Vercel Edge: 25 s), so the framework's clean `504` fires before
+   * the platform terminates the isolate. Pass `0` to disable the framework
    * timeout entirely (the platform's own limit still applies).
    *
    * Per-platform CPU/wall limits for context when overriding:
    * - Cloudflare Workers: 30 000 (30 s CPU limit)
    * - Vercel Edge:        25 000 (25 s wall limit)
    *
-   * @default DEFAULT_EDGE_TIMEOUT_MS (25000)
+   * @default DEFAULT_EDGE_TIMEOUT_MS (24000)
    */
   timeout?: number;
+
+  /**
+   * Explicit named platform, overriding detection (RFC-026).
+   *
+   * @remarks
+   * Internal — set by `@nextrush/adapter-serverless`'s Tier-1 handlers
+   * (`createLambdaHandler`, `createGoogleHandler`, `createAzureHandler`),
+   * which already know their own platform identity unambiguously and pass it
+   * through rather than relying on detection. Application code calling
+   * `createFetchHandler`/`createCloudflareHandler`/etc. directly should not
+   * normally need to set this — the three named edge platforms
+   * (Cloudflare Workers, Vercel Edge, Netlify Edge) are still auto-detected
+   * when omitted.
+   */
+  platform?: PlatformId;
 }
 
 /**
@@ -130,7 +167,8 @@ function createRequestRunner(
   // F-07/ADR-0010: default to DEFAULT_EDGE_TIMEOUT_MS when the caller specifies
   // none (`undefined`); `0` remains an explicit opt-out (no framework timeout).
   const timeout = options.timeout ?? DEFAULT_EDGE_TIMEOUT_MS;
-  const trustProxy = app.options.proxy ?? false;
+  const timeoutSource = options.timeout === undefined ? 'default' : 'explicit options.timeout';
+  const proxy = app.options.proxy ?? false;
 
   /** Sentinel value returned by the timeout racer */
   const TIMEOUT_SENTINEL = Symbol('timeout');
@@ -141,6 +179,24 @@ function createRequestRunner(
   let bootPromise: Promise<ReturnType<Application['callback']>> | null = null;
   const ensureBooted = (): Promise<ReturnType<Application['callback']>> => {
     bootPromise ??= app.ready().then(() => {
+      // P1-3a: outside production, warn once per module instance if a
+      // DIFFERENT Application already booted here — the mechanical signature
+      // of building the app inside the exported handler instead of at module
+      // scope (rebuilding the app on every invocation defeats warm reuse).
+      if (!app.isProduction && !warnedBootReuse && hasBootedAnyApp && !bootedApps.has(app)) {
+        warnedBootReuse = true;
+        console.warn(
+          '[nextrush/edge] A different Application booted in this process/isolate than the one ' +
+            'that booted first. This usually means createApp() (or createFetchHandler/createCloudflareHandler/' +
+            'createVercelHandler/createNetlifyHandler) is being called inside the exported handler ' +
+            'instead of at module scope — rebuilding the app on every invocation defeats warm-instance ' +
+            'reuse and increases cold-start-like latency on every request. Build the app once, at module ' +
+            'scope, above the export. (This message appears in development only.)'
+        );
+      }
+      bootedApps.add(app);
+      hasBootedAnyApp = true;
+
       const handler = app.callback();
       // F-14: mark the app running so `app.isRunning` is consistent with the
       // server adapters. Edge has no server lifetime, so close()/destroy() are
@@ -158,7 +214,7 @@ function createRequestRunner(
     env?: unknown
   ): Promise<Response> => {
     const handler = await ensureBooted();
-    const ctx = createEdgeContext(request, executionContext, trustProxy, env);
+    const ctx = createEdgeContext(request, executionContext, proxy, env, app.isProduction, options.platform);
 
     try {
       if (timeout > 0) {
@@ -176,6 +232,12 @@ function createRequestRunner(
           if (result === TIMEOUT_SENTINEL) {
             // F-08: cancel the still-running handler cooperatively via ctx.signal.
             ctx.triggerTimeout();
+            // P1-3b: name the effective timeout and its source so a 504 is
+            // attributable without reading this adapter's source.
+            app.logger.warn(
+              `[nextrush/edge] Request timed out after ${String(timeout)}ms (${timeoutSource}) — returning 504. ` +
+                `${ctx.method} ${ctx.path}`
+            );
             return jsonErrorResponse(504, 'Gateway Timeout');
           }
         } finally {
@@ -315,7 +377,15 @@ export function createNetlifyHandler(
   return createFetchHandler(app, options);
 }
 
-// Alias for backwards compatibility and consistency
+/**
+ * Alias of {@link createFetchHandler}.
+ *
+ * @deprecated Use {@link createFetchHandler} directly (P3-1) — two exported
+ * names for one function means autocomplete shows both with neither
+ * obviously canonical, on a package whose docs stress bundle discipline.
+ * `createFetchHandler` is the canonical name; this alias is kept for
+ * backwards compatibility and will be removed in a future major.
+ */
 export const createHandler = createFetchHandler;
 
 // F-01: compile-time conformance guard. If the exported fetch-adapter shape
@@ -327,7 +397,7 @@ void _edgeConformance;
 // AdapterContext over the shared Context contract. A drift in createEdgeContext's
 // return type stops compiling here.
 const _edgeContextFactory: AdapterContextFactory<
-  [Request, EdgeExecutionContext?, boolean?, unknown?],
+  [Request, EdgeExecutionContext?, ProxyTrust?, unknown?, boolean?, PlatformId?],
   EdgeContext
 > = createEdgeContext;
 void _edgeContextFactory;