@edge-base/server 0.2.1 → 0.2.2

package/src/lib/functions.ts

@@ -25,19 +25,22 @@ import type {
   ScheduleTrigger,
   HttpTrigger,
 } from '@edge-base/shared';
-import { getDbDoName, getD1BindingName, callDO, shouldRouteToD1 } from './do-router.js';
+import { getD1BindingName, shouldRouteToD1 } from './do-router.js';
 import { executeDoSql } from './do-sql.js';
 import { D1AuthDb, type AuthDb } from './auth-db-adapter.js';
-import { handleD1Request } from './d1-handler.js';
-import { handlePgRequest } from './postgres-handler.js';
-import { buildInternalHandlerContext } from './internal-request.js';
+import { ensureAuthSchema } from './auth-d1.js';
 import type { Env } from '../types.js';
 import { createSignedToken } from '../routes/storage.js';
 import {
+  createManagedAdminUser,
   deleteManagedAdminUser,
   normalizeAdminUserUpdates,
   updateManagedAdminUser,
 } from './admin-user-management.js';
+import { hashPassword } from './password.js';
+import { generateId } from './uuid.js';
+import { DbRef, TableRef, DefaultDbApi, HttpClient, ContextManager } from '@edge-base/core';
+import { InternalHttpTransport } from './internal-transport.js';
 
 // ─── Function Context Types ───
 
@@ -48,21 +51,6 @@ export interface AuthContext {
   custom?: Record<string, unknown>;
 }
 
-export interface TableProxy {
-  insert(data: Record<string, unknown>): Promise<Record<string, unknown>>;
-  upsert(
-    data: Record<string, unknown>,
-    options?: { conflictTarget?: string },
-  ): Promise<Record<string, unknown>>;
-  update(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-  delete(id: string): Promise<{ deleted: boolean }>;
-  get(id: string): Promise<Record<string, unknown>>;
-  list(options?: {
-    limit?: number;
-    filter?: unknown;
-  }): Promise<{ items: Record<string, unknown>[] }>;
-}
-
 export interface AdminAuthContext {
   getUser(userId: string): Promise<Record<string, unknown>>;
   listUsers(options?: {
@@ -89,22 +77,31 @@ export interface AdminAuthContext {
  */
 export interface FunctionAdminContext {
   /** Cross-DO table access — rules bypassed, Service Key authenticated. */
-  table(name: string): TableProxy;
+  table(name: string): TableRef;
   /**
    * Access a specific DB namespace instance (§5).
-   * Replaces forTenant() — aligned with Database-first architecture (#133).
+   * Uses the same TableRef from @edge-base/core as the client SDK,
+   * ensuring API parity (getList, getOne, where, orderBy, limit, etc.).
    *
    * @example
    * // Static DB
-   * context.admin.db('shared').table('posts').list()
+   * context.admin.db('shared').table('posts').getList()
    * // Dynamic DB (tenant/user)
-   * context.admin.db('workspace', 'ws-456').table('documents').list()
+   * context.admin.db('workspace', 'ws-456').table('documents').getList()
+   * // With query builder
+   * context.admin.db('shared').table('posts').where('status', '==', 'published').limit(10).getList()
    */
-  db(namespace: string, id?: string): { table(name: string): TableProxy };
+  db(namespace: string, id?: string): DbRef;
   /** Admin user management. */
   auth: AdminAuthContext;
-  /** Raw SQL on a DB namespace DO. */
-  sql(
+  /**
+   * Execute raw SQL with direct D1/DO binding access — no HTTP round-trip.
+   * Routes directly to D1 binding or Durable Object without network overhead.
+   *
+   * @example
+   * const rows = await ctx.admin.sqlWithDirectD1Access('shared', undefined, 'SELECT * FROM posts WHERE status = ?', ['published']);
+   */
+  sqlWithDirectD1Access(
     namespace: string,
     id: string | undefined,
     query: string,
@@ -291,20 +288,21 @@ export interface FunctionContext {
    *
    * @example
    * // Static DB
-   * await context.db('shared').table('posts').list()
+   * await context.db('shared').table('posts').getList()
    * // Dynamic DB
-   * await context.db('workspace', 'ws-456').table('documents').list()
+   * await context.db('workspace', 'ws-456').table('documents').getList()
+   * // With query builder
+   * await context.db('shared').table('posts').where('status', '==', 'published').limit(10).getList()
    */
   db: FunctionAdminContext['db'];
   /**
-   * Server-side EdgeBase admin client (§5,).
+   * Server-side EdgeBase admin client (§5).
    * Use context.admin.db(namespace, id?).table(name) for all DB access.
+   * Uses the same TableRef from @edge-base/core as the client SDK.
    *
    * @example
-   * // Static DB
-   * await context.admin.db('shared').table('posts').list()
-   * // Dynamic DB
-   * await context.admin.db('workspace', 'ws-456').table('documents').list()
+   * await context.admin.db('shared').table('posts').getList()
+   * await context.admin.db('shared').table('posts').where('userId', '==', uid).getList()
    */
   admin: FunctionAdminContext;
   /**
@@ -697,314 +695,143 @@ export function wrapMethodExport(
   };
 }
 
-// ─── Table Proxy (Cross-DO) ───
+// ─── Admin DB Proxy (uses @edge-base/core TableRef via InternalHttpTransport) ───
 
-/**
- * Build a cross-DO table proxy.
- * All calls bypass access rules by using Service Key.
- */
-function buildTableProxy(
-  tableName: string,
-  namespace: DurableObjectNamespace,
-  config: EdgeBaseConfig,
-  workerUrl?: string,
-  serviceKey?: string,
-  env?: Env,
-  executionCtx?: ExecutionContext,
-  /** DB routing info (§5). If provided, overrides auto-detect. */
-  dbTarget?: { namespace: string; id?: string; doName: string },
-  routingOptions?: { preferDirectDo?: boolean },
-): TableProxy {
-  // Determine DO name: explicit DB target (§5) or auto-detect from config
-  let resolvedTarget: { namespace: string; id?: string; doName: string };
-  if (dbTarget) {
-    resolvedTarget = dbTarget;
-  } else {
-    // Auto-detect namespace for this table from config (§1)
-    let tableNamespace = 'shared';
-    for (const [ns, dbBlock] of Object.entries(config.databases ?? {})) {
-      if (dbBlock.tables?.[tableName]) {
-        tableNamespace = ns;
-        break;
-      }
-    }
-    resolvedTarget = {
-      namespace: tableNamespace,
-      doName: getDbDoName(tableNamespace),
-    };
-  }
-  const doName = resolvedTarget.doName;
-  const headers: Record<string, string> = { 'X-DO-Name': doName };
-  if (serviceKey) {
-    headers['X-EdgeBase-Service-Key'] = serviceKey;
-  }
-  // Add internal header to bypass rules
-  headers['X-EdgeBase-Internal'] = 'true';
-
-  const buildTablePath = (id?: string, query?: URLSearchParams): string => {
-    const base = resolvedTarget.id !== undefined
-      ? `/api/db/${resolvedTarget.namespace}/${resolvedTarget.id}/tables/${tableName}`
-      : `/api/db/${resolvedTarget.namespace}/tables/${tableName}`;
-    const withId = id ? `${base}/${id}` : base;
-    const search = query && Array.from(query.keys()).length > 0 ? `?${query.toString()}` : '';
-    return `${withId}${search}`;
-  };
-  const buildDirectTablePath = (id?: string, query?: URLSearchParams): string => {
-    const base = `/tables/${tableName}`;
-    const withId = id ? `${base}/${id}` : base;
-    const search = query && Array.from(query.keys()).length > 0 ? `?${query.toString()}` : '';
-    return `${withId}${search}`;
-  };
+interface BuildAdminDbProxyOptions {
+  databaseNamespace: DurableObjectNamespace;
+  config: EdgeBaseConfig;
+  workerUrl?: string;
+  serviceKey?: string;
+  env?: Env;
+  executionCtx?: ExecutionContext;
+  preferDirectDo?: boolean;
+}
 
-  const requestViaWorker = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    path: string,
-    body?: Record<string, unknown>,
-  ): Promise<Response> => {
-    return fetch(`${workerUrl}${path}`, {
-      method,
-      headers: {
-        'Content-Type': 'application/json',
-        ...headers,
-      },
-      body: body === undefined || method === 'GET' || method === 'DELETE'
-        ? undefined
-        : JSON.stringify(body),
-    });
-  };
-  const requestViaD1Handler = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    directPath: string,
-    query?: URLSearchParams,
-    body?: Record<string, unknown>,
-  ): Promise<Response> => {
-    if (!env) {
-      throw new Error('D1 table proxy requires env.');
-    }
+// ─── Shared SQL executor — D1 direct → DO direct → HTTP fallback ───
 
-    const request = new Request(
-      `http://internal/api/db/${resolvedTarget.namespace}${resolvedTarget.id ? `/${resolvedTarget.id}` : ''}${buildDirectTablePath(undefined, query).replace('/tables/' + tableName, directPath)}`,
-      {
-        method,
-        headers: {
-          'Content-Type': 'application/json',
-          ...headers,
-        },
-        body: body === undefined || method === 'GET' || method === 'DELETE'
-          ? undefined
-          : JSON.stringify(body),
-      },
-    );
+export interface SqlWithDirectD1AccessOptions {
+  env?: unknown;
+  config: EdgeBaseConfig;
+  databaseNamespace?: DurableObjectNamespace;
+  workerUrl?: string;
+  serviceKey?: string;
+}
 
-    return handleD1Request(
-      buildInternalHandlerContext({
-        env,
-        request,
-        body,
-        executionCtx,
-      }),
-      resolvedTarget.namespace,
-      tableName,
-      directPath,
-    );
-  };
-  const requestViaPgHandler = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    directPath: string,
-    query?: URLSearchParams,
-    body?: Record<string, unknown>,
-  ): Promise<Response> => {
-    if (!env) {
-      throw new Error('PostgreSQL table proxy requires env.');
+/**
+ * Execute raw SQL with the fastest available path:
+ * 1. D1 direct binding (no network hop)
+ * 2. Durable Object direct call
+ * 3. HTTP fallback via workerUrl
+ *
+ * Shared by buildFunctionContext, auth hooks, and storage hooks.
+ */
+export async function executeSqlWithDirectD1Access(
+  opts: SqlWithDirectD1AccessOptions,
+  namespace: string,
+  id: string | undefined,
+  query: string,
+  params?: unknown[],
+): Promise<unknown[]> {
+  if (opts.env) {
+    const dbBlock = opts.config.databases?.[namespace];
+    const isDynamicNamespace = !!(dbBlock?.instance || dbBlock?.access?.canCreate || dbBlock?.access?.access);
+    if (isDynamicNamespace && !id) {
+      throw new Error(`admin.sqlWithDirectD1Access() requires an id for dynamic namespace '${namespace}'.`);
     }
 
-    const request = new Request(
-      `http://internal/api/db/${resolvedTarget.namespace}${resolvedTarget.id ? `/${resolvedTarget.id}` : ''}${buildDirectTablePath(undefined, query).replace('/tables/' + tableName, directPath)}`,
-      {
-        method,
-        headers: {
-          'Content-Type': 'application/json',
-          ...headers,
-        },
-        body: body === undefined || method === 'GET' || method === 'DELETE'
-          ? undefined
-          : JSON.stringify(body),
-      },
-    );
-
-    return handlePgRequest(
-      buildInternalHandlerContext({
-        env,
-        request,
-        body,
-        executionCtx,
-      }),
-      resolvedTarget.namespace,
-      tableName,
-      directPath,
-    );
-  };
-  const requestViaDirectDo = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    directPath: string,
-    body?: Record<string, unknown>,
-  ): Promise<Response> => {
-    const res = await callDO(namespace, doName, directPath, {
-      method,
-      body,
-      headers,
-    });
-
-    if (!resolvedTarget.id || res.status !== 201) {
-      return res;
+    if (!id && shouldRouteToD1(namespace, opts.config)) {
+      const bindingName = getD1BindingName(namespace);
+      const d1 = (opts.env as Record<string, unknown>)[bindingName] as D1Database | undefined;
+      if (!d1) {
+        throw new Error(`D1 binding '${bindingName}' not found.`);
+      }
+      try {
+        const stmt = d1.prepare(query);
+        const bound = params && params.length > 0 ? stmt.bind(...params) : stmt;
+        const result = await bound.all();
+        return (result.results ?? []) as unknown[];
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'SQL execution failed';
+        throw new Error(message);
+      }
     }
 
-    const createPayload = await res.clone().json().catch(() => null) as
-      | { needsCreate?: boolean }
-      | null;
-    if (!createPayload?.needsCreate) {
-      return res;
+    if (opts.databaseNamespace) {
+      return executeDoSql({
+        databaseNamespace: opts.databaseNamespace,
+        namespace,
+        id,
+        query,
+        params: params ?? [],
+        internal: true,
+      });
     }
+  }
 
-    return callDO(namespace, doName, directPath, {
-      method,
-      body,
+  if (opts.workerUrl && opts.serviceKey) {
+    const res = await fetch(`${opts.workerUrl}/api/sql`, {
+      method: 'POST',
       headers: {
-        ...headers,
-        'X-DO-Create-Authorized': '1',
+        'Content-Type': 'application/json',
+        'X-EdgeBase-Service-Key': opts.serviceKey,
       },
+      body: JSON.stringify({ namespace, id, sql: query, params: params ?? [] }),
     });
-  };
-  const requestTable = async (
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
-    id?: string,
-    body?: Record<string, unknown>,
-    query?: URLSearchParams,
-  ): Promise<Response> => {
-    const directPath = buildDirectTablePath(id);
-    const directPathWithQuery = buildDirectTablePath(id, query);
-    const provider = config.databases?.[resolvedTarget.namespace]?.provider;
-
-    if (!routingOptions?.preferDirectDo && shouldRouteToD1(resolvedTarget.namespace, config) && env) {
-      return requestViaD1Handler(method, directPath, query, body);
-    }
-    if ((provider === 'neon' || provider === 'postgres') && env) {
-      return requestViaPgHandler(method, directPath, query, body);
-    }
-    if (env) {
-      return requestViaDirectDo(method, directPathWithQuery, body);
-    }
-    if (workerUrl) {
-      return requestViaWorker(method, buildTablePath(id, query), body);
-    }
-    return requestViaDirectDo(method, directPathWithQuery, body);
-  };
-
-  const insert = async (data: Record<string, unknown>): Promise<Record<string, unknown>> => {
-    const res = await requestTable('POST', undefined, data);
     if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO insert failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as Record<string, unknown>;
-  };
-
-  const upsert = async (
-    data: Record<string, unknown>,
-    options?: { conflictTarget?: string },
-  ): Promise<Record<string, unknown>> => {
-    const query = new URLSearchParams();
-    query.set('upsert', 'true');
-    if (options?.conflictTarget) {
-      query.set('conflictTarget', options.conflictTarget);
-    }
-
-    const res = await requestTable('POST', undefined, data, query);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO upsert failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as Record<string, unknown>;
-  };
-
-  const update = async (
-    id: string,
-    data: Record<string, unknown>,
-  ): Promise<Record<string, unknown>> => {
-    const res = await requestTable('PATCH', id, data);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO update failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as Record<string, unknown>;
-  };
-
-  const del = async (id: string): Promise<{ deleted: boolean }> => {
-    const res = await requestTable('DELETE', id);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO delete failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as { deleted: boolean };
-  };
-
-  const get = async (id: string): Promise<Record<string, unknown>> => {
-    const res = await requestTable('GET', id);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO get failed: ${err.message || res.status}`);
-    }
-    return (await res.json()) as Record<string, unknown>;
-  };
-
-  const list = async (listOptions?: {
-    limit?: number;
-    filter?: unknown;
-  }): Promise<{ items: Record<string, unknown>[] }> => {
-    const query = new URLSearchParams();
-    if (listOptions?.limit) query.set('limit', String(listOptions.limit));
-    if (listOptions?.filter) query.set('filter', JSON.stringify(listOptions.filter));
-
-    const res = await requestTable('GET', undefined, undefined, query);
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-      throw new Error(`Cross-DO list failed: ${err.message || res.status}`);
+      const err = (await res.json().catch(() => ({ message: 'SQL execution failed' }))) as { message: string };
+      throw new Error(err.message);
     }
-    return (await res.json()) as { items: Record<string, unknown>[] };
-  };
+    const data = (await res.json()) as { rows?: unknown[]; items?: unknown[]; results?: unknown[] };
+    if (Array.isArray(data.rows)) return data.rows;
+    if (Array.isArray(data.items)) return data.items;
+    if (Array.isArray(data.results)) return data.results;
+    return [];
+  }
 
-  return { insert, upsert, update, delete: del, get, list };
-}
-
-interface BuildAdminDbProxyOptions {
-  databaseNamespace: DurableObjectNamespace;
-  config: EdgeBaseConfig;
-  workerUrl?: string;
-  serviceKey?: string;
-  env?: Env;
-  executionCtx?: ExecutionContext;
-  preferDirectDo?: boolean;
+  throw new Error(
+    'admin.sqlWithDirectD1Access() requires env or workerUrl.',
+  );
 }
 
+/**
+ * Build the admin DB proxy that returns real DbRef/TableRef instances
+ * from @edge-base/core, routed through InternalHttpTransport for
+ * direct D1/PG/DO access (no HTTP round-trip).
+ */
 export function buildAdminDbProxy(options: BuildAdminDbProxyOptions): FunctionAdminContext['db'] {
-  return (namespace: string, id?: string) => {
-    const doName = getDbDoName(namespace, id);
-
-    return {
-      table(tableName: string): TableProxy {
-        return buildTableProxy(
-          tableName,
-          options.databaseNamespace,
-          options.config,
-          options.workerUrl,
-          options.serviceKey,
-          options.env,
-          options.executionCtx,
-          { namespace, id, doName },
-          { preferDirectDo: options.preferDirectDo },
-        );
-      },
-    };
+  // Create HttpClient for sql() tagged template support on TableRef.
+  // Only available when workerUrl is set (routes through /api/sql endpoint).
+  let httpClient: HttpClient | undefined;
+  if (options.workerUrl) {
+    httpClient = new HttpClient({
+      baseUrl: options.workerUrl,
+      serviceKey: options.serviceKey,
+      contextManager: new ContextManager(),
+    });
+  }
+
+  return (namespace: string, id?: string): DbRef => {
+    // Create a per-DbRef transport with explicit dbContext so that
+    // path parsing is unambiguous even when instanceId === 'tables'.
+    const transport = new InternalHttpTransport({
+      databaseNamespace: options.databaseNamespace,
+      config: options.config,
+      workerUrl: options.workerUrl,
+      serviceKey: options.serviceKey,
+      env: options.env,
+      executionCtx: options.executionCtx,
+      preferDirectDo: options.preferDirectDo,
+      dbContext: { namespace, instanceId: id },
+    });
+    const dbApi = new DefaultDbApi(transport);
+    return new DbRef(
+      dbApi,
+      namespace,
+      id,
+      undefined,   // databaseLiveClient — not available server-side
+      undefined,   // filterMatchFn
+      httpClient,  // enables table().sql`...` tagged template
+    );
   };
 }
 
@@ -1024,7 +851,7 @@ interface AdminAuthOptions {
 /**
  * Build admin auth context for App Functions.
  * Uses AUTH_DB D1 directly for all operations (D1-first architecture).
- * Cross-shard operations (listUsers, createUser) also available via Worker HTTP relay
+ * Cross-shard operations (listUsers) also available via Worker HTTP relay
  * when workerUrl is provided.
  */
 export function buildAdminAuthContext(options: AdminAuthOptions): AdminAuthContext {
@@ -1089,10 +916,49 @@ export function buildAdminAuthContext(options: AdminAuthOptions): AdminAuthConte
       displayName?: string;
       role?: string;
     }): Promise<Record<string, unknown>> {
+      // Direct D1 path — works without service key (same as updateUser/deleteUser)
+      if (d1Database) {
+        // Input validation (mirrors routes/admin-auth.ts guards)
+        if (!data.email || typeof data.email !== 'string') throw new Error('Email and password are required.');
+        if (!data.password || typeof data.password !== 'string') throw new Error('Email and password are required.');
+        const email = data.email.trim().toLowerCase();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+          throw new Error('Invalid email format.');
+        }
+        if (data.password.length < 8) throw new Error('Password must be at least 8 characters.');
+        if (data.password.length > 256) throw new Error('Password must not exceed 256 characters.');
+        if (data.displayName && data.displayName.length > 200) {
+          throw new Error('Display name must not exceed 200 characters.');
+        }
+        // Role validation (mirrors normalizeOptionalRole in routes/admin-auth.ts)
+        let role = 'user';
+        if (data.role !== undefined) {
+          if (typeof data.role !== 'string') throw new Error('Role must be a non-empty string.');
+          const trimmed = data.role.trim();
+          if (!trimmed) throw new Error('Role must be a non-empty string.');
+          if (trimmed.length > 100) throw new Error('Role must not exceed 100 characters.');
+          role = trimmed;
+        }
+
+        const db = new D1AuthDb(d1Database);
+        // Ensure auth tables exist (critical for fresh databases)
+        await ensureAuthSchema(db);
+        const user = await createManagedAdminUser(
+          db,
+          {
+            userId: generateId(),
+            email,
+            passwordHash: await hashPassword(data.password),
+            displayName: data.displayName,
+            role,
+            verified: true,
+          },
+          { kv: kvNamespace },
+        );
+        return authService.sanitizeUser(user, { includeAppMetadata: true });
+      }
       if (workerUrl && serviceKey) {
-        // HTTP relay: POST /api/auth/admin/users → Worker → D1
-        // createUser has complex side effects (email index, _users_public, etc.)
-        // so it routes through the admin route which handles the full flow.
+        // HTTP relay fallback: POST /api/auth/admin/users → Worker → D1
         const res = await fetch(`${workerUrl}/api/auth/admin/users`, {
           method: 'POST',
           headers: {
@@ -1111,7 +977,7 @@ export function buildAdminAuthContext(options: AdminAuthOptions): AdminAuthConte
         return result.user;
       }
       throw new Error(
-        'admin.auth.createUser() is not available in this context (requires workerUrl). ' +
+        'admin.auth.createUser() is not available in this context (requires D1 or workerUrl). ' +
           'Pass workerUrl to buildFunctionContext(), or use the external SDK.',
       );
     },
@@ -1223,77 +1089,18 @@ export function buildFunctionContext(options: BuildFunctionContextOptions): Func
     // ─── context.admin.db(namespace, id) — DB-first tenant access (§5) ───
     db: adminDb,
     auth: adminAuthContext,
-    async sql(
-      namespace: string,
-      id: string | undefined,
-      query: string,
-      params?: unknown[],
-    ): Promise<unknown[]> {
-      if (options.env) {
-        const dbBlock = options.config.databases?.[namespace];
-        const isDynamicNamespace = !!(dbBlock?.instance || dbBlock?.access?.canCreate || dbBlock?.access?.access);
-        if (isDynamicNamespace && !id) {
-          throw new Error(`admin.sql() requires an id for dynamic namespace '${namespace}'.`);
-        }
-
-        if (!id && shouldRouteToD1(namespace, options.config)) {
-          const bindingName = getD1BindingName(namespace);
-          const d1 = (options.env as unknown as Record<string, unknown>)[bindingName] as D1Database | undefined;
-          if (!d1) {
-            throw new Error(`D1 binding '${bindingName}' not found.`);
-          }
-          try {
-            const stmt = d1.prepare(query);
-            const bound = params && params.length > 0 ? stmt.bind(...params) : stmt;
-            const result = await bound.all();
-            const rows = (result.results ?? []) as unknown[];
-            return rows;
-          } catch (error) {
-            const message = error instanceof Error ? error.message : 'SQL execution failed';
-            throw new Error(message);
-          }
-        }
-
-        return executeDoSql({
+    // ─── Direct D1/DO SQL — delegates to shared executor ───
+    sqlWithDirectD1Access: (namespace: string, id: string | undefined, query: string, params?: unknown[]) =>
+      executeSqlWithDirectD1Access(
+        {
+          env: options.env,
+          config: options.config,
           databaseNamespace: options.databaseNamespace,
-          namespace,
-          id,
-          query,
-          params: params ?? [],
-          internal: true,
-        });
-      }
-
-      if (options.workerUrl && options.serviceKey) {
-        // HTTP route: POST /api/sql → Worker → DatabaseDO (§11)
-        const res = await fetch(`${options.workerUrl}/api/sql`, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'X-EdgeBase-Service-Key': options.serviceKey,
-          },
-          body: JSON.stringify({ namespace, id, sql: query, params: params ?? [] }),
-        });
-        if (!res.ok) {
-          const err = (await res.json().catch(() => ({ message: 'SQL execution failed' }))) as {
-            message: string;
-          };
-          throw new Error(err.message);
-        }
-        const data = (await res.json()) as {
-          rows?: unknown[];
-          items?: unknown[];
-          results?: unknown[];
-        };
-        if (Array.isArray(data.rows)) return data.rows;
-        if (Array.isArray(data.items)) return data.items;
-        if (Array.isArray(data.results)) return data.results;
-        return [];
-      }
-      throw new Error(
-        'admin.sql() requires workerUrl. Pass workerUrl to buildFunctionContext(), or use the external SDK.',
-      );
-    },
+          workerUrl: options.workerUrl,
+          serviceKey: options.serviceKey,
+        },
+        namespace, id, query, params,
+      ),
     async broadcast(
       channel: string,
       event: string,