@constructive-io/graphql-server 5.0.4 → 5.1.0

package/esm/middleware/api.js

@@ -1,13 +1,12 @@
-import { getNodeEnv } from '@pgpmjs/env';
+import './types';
+import { createDefaultRegistry } from '@constructive-io/express-context';
+import { parseUrl } from '@constructive-io/url-domains';
 import { Logger } from '@pgpmjs/logger';
 import { svcCache } from '@pgpmjs/server-utils';
-import { parseUrl } from '@constructive-io/url-domains';
-import { createDefaultRegistry, } from '@constructive-io/express-context';
 import { getPgPool } from 'pg-cache';
 import errorPage50x from '../errors/50x';
 import errorPage404Message from '../errors/404-message';
 import { resolveRoute, routeToApiStructure } from './routing';
-import './types';
 const log = new Logger('api');
 // =============================================================================
 // Module Loader Registry (replaces inline SQL queries for per-db config)
@@ -16,87 +15,49 @@ const defaultRegistry = createDefaultRegistry();
 // =============================================================================
 // SQL Queries (API resolution only — module queries now live in loaders)
 // =============================================================================
-const DOMAIN_LOOKUP_SQL = `
-  SELECT 
-    a.id as api_id,
-    a.database_id,
-    a.dbname,
-    a.role_name,
-    a.anon_role,
-    a.is_public,
-    COALESCE(array_agg(s.schema_name) FILTER (WHERE s.schema_name IS NOT NULL), '{}') as schemas
-  FROM services_public.domains d
-  JOIN services_public.apis a ON d.api_id = a.id
-  LEFT JOIN services_public.api_schemas aps ON a.id = aps.api_id
-  LEFT JOIN metaschema_public.schema s ON aps.schema_id = s.id
-  WHERE d.domain = $1 
-    AND (($2::text IS NULL AND d.subdomain IS NULL) OR d.subdomain = $2)
-    AND a.is_public = $3
-  GROUP BY a.id, a.database_id, a.dbname, a.role_name, a.anon_role, a.is_public
-  LIMIT 1
-`;
-const API_NAME_LOOKUP_SQL = `
+// Private-header X-Api-Name lookup against the scoped routing plane.
+// `is_published` is the routing-plane analog of the legacy `is_public` column.
+const SCOPED_API_NAME_LOOKUP_SQL = `
   SELECT 
     a.id as api_id,
     a.database_id,
     a.dbname,
     a.role_name,
     a.anon_role,
-    a.is_public,
+    a.is_published as is_public,
     COALESCE(array_agg(s.schema_name) FILTER (WHERE s.schema_name IS NOT NULL), '{}') as schemas
-  FROM services_public.apis a
-  LEFT JOIN services_public.api_schemas aps ON a.id = aps.api_id
+  FROM constructive_routing_public.apis a
+  LEFT JOIN constructive_routing_public.api_schemas aps ON a.id = aps.api_id
   LEFT JOIN metaschema_public.schema s ON aps.schema_id = s.id
   WHERE a.database_id = $1 
     AND a.name = $2
-    AND a.is_public = $3
-  GROUP BY a.id, a.database_id, a.dbname, a.role_name, a.anon_role, a.is_public
+    AND a.is_published = $3
+  GROUP BY a.id, a.database_id, a.dbname, a.role_name, a.anon_role, a.is_published
   LIMIT 1
 `;
-const API_LIST_SQL = `
-  SELECT 
-    a.id,
-    a.database_id,
-    a.name,
-    a.dbname,
-    a.role_name,
-    a.anon_role,
-    a.is_public,
-    COALESCE(
-      json_agg(
-        json_build_object('domain', d.domain, 'subdomain', d.subdomain)
-      ) FILTER (WHERE d.domain IS NOT NULL),
-      '[]'
-    ) as domains
-  FROM services_public.apis a
-  LEFT JOIN services_public.domains d ON a.id = d.api_id
-  WHERE a.is_public = $1
-  GROUP BY a.id, a.database_id, a.name, a.dbname, a.role_name, a.anon_role, a.is_public
-  LIMIT 100
-`;
 /**
  * Build a LoaderContext from the API row and options.
  * This is used to resolve per-database module settings via the loader registry.
  */
-const buildLoaderContext = (servicesPool, opts, row) => ({
-    servicesPool,
+const buildLoaderContext = (routingPool, opts, row) => ({
+    routingPool,
     tenantPool: getPgPool({ ...opts.pg, database: row.dbname }),
     databaseId: row.database_id,
     apiId: row.api_id,
-    dbname: row.dbname,
+    dbname: row.dbname
 });
 /**
  * Resolve all per-database module settings in parallel via the loader registry.
  * Each loader independently caches by databaseId — repeated calls are cheap.
  */
 const resolveModuleSettings = async (registry, ctx) => {
-    const [rlsModule, authSettings, corsOrigins, databaseSettings, pubkeyChallengeSettings, webauthnSettings,] = await Promise.all([
+    const [rlsModule, authSettings, corsOrigins, databaseSettings, pubkeyChallengeSettings, webauthnSettings] = await Promise.all([
         registry.resolve('rlsModule', ctx),
         registry.resolve('authSettings', ctx),
         registry.resolve('corsOrigins', ctx),
         registry.resolve('databaseSettings', ctx),
         registry.resolve('pubkeyChallengeSettings', ctx),
-        registry.resolve('webauthnSettings', ctx),
+        registry.resolve('webauthnSettings', ctx)
     ]);
     return {
         rlsModule,
@@ -104,7 +65,7 @@ const resolveModuleSettings = async (registry, ctx) => {
         corsOrigins,
         databaseSettings,
         pubkeyChallengeSettings,
-        webauthnSettings,
+        webauthnSettings
     };
 };
 // =============================================================================
@@ -125,14 +86,14 @@ const getRoutingHeaders = (req) => ({
     schemata: req.get('X-Schemata'),
     apiName: req.get('X-Api-Name'),
     metaSchema: req.get('X-Meta-Schema'),
-    databaseId: req.get('X-Database-Id'),
+    databaseId: req.get('X-Database-Id')
 });
 const getUrlDomains = (req) => {
     const fullUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
     const parsed = parseUrl(fullUrl);
     return {
         domain: parsed.domain ?? '',
-        subdomains: parsed.subdomains ?? [],
+        subdomains: parsed.subdomains ?? []
     };
 };
 export const getSubdomain = (subdomains) => {
@@ -172,7 +133,7 @@ const toApiStructure = (row, opts, settings = {}) => ({
     corsOrigins: settings.corsOrigins,
     databaseSettings: settings.databaseSettings,
     pubkeyChallengeSettings: settings.pubkeyChallengeSettings,
-    webauthnSettings: settings.webauthnSettings,
+    webauthnSettings: settings.webauthnSettings
 });
 const createAdminStructure = (opts, schemas, databaseId) => ({
     dbname: opts.pg?.database ?? '',
@@ -182,7 +143,7 @@ const createAdminStructure = (opts, schemas, databaseId) => ({
     apiModules: [],
     domains: [],
     databaseId,
-    isPublic: false,
+    isPublic: false
 });
 // =============================================================================
 // Database Queries (API resolution only)
@@ -191,31 +152,25 @@ const validateSchemata = async (pool, schemas) => {
     const result = await pool.query(`SELECT schema_name FROM information_schema.schemata WHERE schema_name = ANY($1::text[])`, [schemas]);
     return result.rows.map((row) => row.schema_name);
 };
-const queryByDomain = async (pool, domain, subdomain, isPublic) => {
-    const result = await pool.query(DOMAIN_LOOKUP_SQL, [domain, subdomain, isPublic]);
-    return result.rows[0] ?? null;
-};
 const queryByApiName = async (pool, databaseId, name, isPublic) => {
-    const result = await pool.query(API_NAME_LOOKUP_SQL, [databaseId, name, isPublic]);
+    const result = await pool.query(SCOPED_API_NAME_LOOKUP_SQL, [databaseId, name, isPublic]);
     return result.rows[0] ?? null;
 };
-const queryApiList = async (pool, isPublic) => {
-    const result = await pool.query(API_LIST_SQL, [isPublic]);
-    return result.rows;
-};
 // =============================================================================
 // Resolution Logic
 // =============================================================================
 const determineMode = (ctx) => {
     const { opts, headers } = ctx;
-    if (opts.api?.enableServicesApi === false)
-        return 'services-disabled';
+    // Static single-tenant mode: scoped routing off — expose configured schemas
+    // directly with no route resolution.
+    if (!opts.api?.enableScopedRouting)
+        return 'static';
     if (opts.api?.isPublic === false) {
-        return getPrivateHeaderMode(headers) ?? 'domain-lookup';
+        return getPrivateHeaderMode(headers) ?? 'scoped-route';
     }
-    return 'domain-lookup';
+    return 'scoped-route';
 };
-const resolveServicesDisabled = (ctx) => {
+const resolveStatic = (ctx) => {
     const { opts } = ctx;
     return {
         dbname: opts.pg?.database ?? '',
@@ -225,7 +180,7 @@ const resolveServicesDisabled = (ctx) => {
         apiModules: [],
         domains: [],
         databaseId: opts.api?.defaultDatabaseId,
-        isPublic: false,
+        isPublic: false
     };
 };
 const resolveSchemataHeader = async (ctx, validatedSchemas) => {
@@ -257,12 +212,12 @@ const resolveMetaSchemaHeader = (ctx, validatedSchemas) => {
     return createAdminStructure(ctx.opts, validatedSchemas, ctx.headers.databaseId);
 };
 /**
- * Scoped routing plane resolution (additive, host-only): one indexed
- * resolve_route() call against the compiled hostname/route bindings.
- * Path/method routing belongs to Traefik/Ingress — the server only maps
- * host → tenant/api/db/role. Returns null (fall back to the legacy
- * services_public lookup) when disabled, unmatched, resolver not installed,
- * or the target is not an api surface.
+ * Scoped routing plane resolution (host-only): one indexed resolve_route()
+ * call against the compiled hostname/route bindings. Path/method routing
+ * belongs to Traefik/Ingress — the server only maps host → tenant/api/db/role.
+ * This is the sole host resolver. Returns null (→ 404) when disabled,
+ * unmatched, the resolver is not installed, or the target is not an api
+ * surface. There is no legacy fallback.
  */
 const resolveScopedRoute = async (ctx) => {
     const { opts, pool, host } = ctx;
@@ -285,7 +240,7 @@ const resolveScopedRoute = async (ctx) => {
         role_name: structure.roleName,
         anon_role: structure.anonRole,
         is_public: structure.isPublic ?? false,
-        schemas: structure.schema,
+        schemas: structure.schema
     });
     const settings = await resolveModuleSettings(defaultRegistry, loaderCtx);
     return {
@@ -295,63 +250,7 @@ const resolveScopedRoute = async (ctx) => {
         corsOrigins: settings.corsOrigins,
         databaseSettings: settings.databaseSettings,
         pubkeyChallengeSettings: settings.pubkeyChallengeSettings,
-        webauthnSettings: settings.webauthnSettings,
-    };
-};
-const resolveDomainLookup = async (ctx) => {
-    const { opts, pool, domain, subdomain } = ctx;
-    const isPublic = opts.api?.isPublic ?? false;
-    log.debug(`[domain-lookup] domain=${domain} subdomain=${subdomain} isPublic=${isPublic}`);
-    const row = await queryByDomain(pool, domain, subdomain, isPublic);
-    if (!row) {
-        log.debug(`[domain-lookup] No API found for domain=${domain} subdomain=${subdomain}`);
-        return null;
-    }
-    const loaderCtx = buildLoaderContext(pool, opts, row);
-    const settings = await resolveModuleSettings(defaultRegistry, loaderCtx);
-    log.debug(`[domain-lookup] resolved schemas: [${row.schemas?.join(', ')}], rlsModule: ${settings.rlsModule ? 'found' : 'none'}, authSettings: ${settings.authSettings ? 'found' : 'none'}`);
-    return toApiStructure(row, opts, settings);
-};
-const buildDevFallbackError = async (ctx, req) => {
-    if (getNodeEnv() !== 'development')
-        return null;
-    const isPublic = ctx.opts.api?.isPublic ?? false;
-    const apis = await queryApiList(ctx.pool, isPublic);
-    if (!apis.length)
-        return null;
-    const host = req.get('host') || '';
-    const portMatch = host.match(/:(\d+)$/);
-    const port = portMatch ? portMatch[1] : '';
-    const apiCards = apis.map((api) => {
-        const domains = api.domains.length
-            ? api.domains.map((d) => {
-                const hostname = d.subdomain ? `${d.subdomain}.${d.domain}` : d.domain;
-                const url = port ? `http://${hostname}:${port}/graphiql` : `http://${hostname}/graphiql`;
-                return `<a href="${url}" style="color:#01A1FF;text-decoration:none;font-weight:500" onmouseover="this.style.textDecoration='underline'" onmouseout="this.style.textDecoration='none'">${hostname}</a>`;
-            }).join('<span style="color:#D4DCEA;margin:0 4px">·</span>')
-            : '<span style="color:#8E9398;font-style:italic;font-size:11px">no domains</span>';
-        const badge = api.is_public
-            ? '<span style="color:#01A1FF;font-size:10px;font-weight:500">public</span>'
-            : '<span style="color:#8E9398;font-size:10px">private</span>';
-        return `
-      <div style="background:#fff;border-radius:8px;padding:10px 14px;margin-bottom:6px;box-shadow:0 1px 3px rgba(0,0,0,0.04);border:1px solid #E8ECF0;display:flex;align-items:center;gap:12px;transition:background 0.15s" onmouseover="this.style.background='#FAFBFC'" onmouseout="this.style.background='#fff'">
-        <div style="flex:1;min-width:0;display:flex;align-items:center;gap:8px;font-size:13px">
-          <span style="font-weight:600;color:#232323;white-space:nowrap">${api.name}</span>
-          <span style="color:#D4DCEA">→</span>
-          ${domains}
-        </div>
-        <div style="display:flex;align-items:center;gap:8px;flex-shrink:0">
-          <span style="color:#8E9398;font-size:11px;font-family:'SF Mono',Monaco,monospace">${api.dbname}</span>
-          ${badge}
-        </div>
-      </div>`;
-    }).join('');
-    return {
-        errorHtml: `
-      <div style="text-align:left;max-width:600px;margin:0 auto">
-        <p style="color:#8E9398;font-size:11px;margin-bottom:10px;font-weight:500;text-transform:uppercase;letter-spacing:0.5px">Available APIs</p>
-        ${apiCards}
-      </div>`,
+        webauthnSettings: settings.webauthnSettings
     };
 };
 // =============================================================================
@@ -376,7 +275,7 @@ export const getApiConfig = async (opts, req) => {
         subdomain,
         cacheKey,
         headers: getRoutingHeaders(req),
-        host: req.get('host') || '',
+        host: req.get('host') || ''
     };
     // Validate schemas upfront for modes that need them
     const apiOpts = opts.api || {};
@@ -396,8 +295,8 @@ export const getApiConfig = async (opts, req) => {
     const mode = determineMode(ctx);
     let result;
     switch (mode) {
-        case 'services-disabled':
-            result = resolveServicesDisabled(ctx);
+        case 'static':
+            result = resolveStatic(ctx);
             break;
         case 'schemata-header':
             result = await resolveSchemataHeader(ctx, validatedSchemas);
@@ -408,16 +307,8 @@ export const getApiConfig = async (opts, req) => {
         case 'meta-schema-header':
             result = resolveMetaSchemaHeader(ctx, validatedSchemas);
             break;
-        case 'domain-lookup':
+        case 'scoped-route':
             result = await resolveScopedRoute(ctx);
-            if (!result) {
-                result = await resolveDomainLookup(ctx);
-            }
-            if (!result && apiOpts.isPublic) {
-                const fallback = await buildDevFallbackError(ctx, req);
-                if (fallback)
-                    return fallback;
-            }
             break;
     }
     // Cache successful results
@@ -432,19 +323,20 @@ export const getApiConfig = async (opts, req) => {
 export const createApiMiddleware = (opts) => {
     return async (req, res, next) => {
         log.debug(`[api-middleware] ${req.method} ${req.path}`);
-        // Fast path: services disabled
-        if (opts.api?.enableServicesApi === false) {
-            req.api = resolveServicesDisabled({
+        // Fast path: static single-tenant mode (scoped routing disabled) — no
+        // route resolution, expose the configured schemas directly.
+        if (!opts.api?.enableScopedRouting) {
+            req.api = resolveStatic({
                 opts,
                 pool: null,
                 domain: '',
                 subdomain: null,
-                cacheKey: 'meta-api-off',
+                cacheKey: 'static',
                 headers: {},
-                host: '',
+                host: ''
             });
             req.databaseId = req.api.databaseId;
-            req.svc_key = 'meta-api-off';
+            req.svc_key = 'static';
             return next();
         }
         try {

package/esm/middleware/flush.js

@@ -1,8 +1,8 @@
+import './types'; // for Request type
 import { Logger } from '@pgpmjs/logger';
 import { svcCache } from '@pgpmjs/server-utils';
 import { graphileCache } from 'graphile-cache';
 import { getPgPool } from 'pg-cache';
-import './types'; // for Request type
 const log = new Logger('flush');
 export const flush = async (req, res, next) => {
     if (req.url === '/flush') {
@@ -28,19 +28,13 @@ export const flushService = async (opts, databaseId) => {
             }
         });
     }
-    const svc = await pgPool.query(`SELECT *
-     FROM services_public.domains
+    const svc = await pgPool.query(`SELECT hostname
+     FROM constructive_routing_public.domains
      WHERE database_id = $1`, [databaseId]);
     if (svc.rowCount === 0)
         return;
     for (const row of svc.rows) {
-        let key;
-        if (row.domain && !row.subdomain) {
-            key = row.domain;
-        }
-        else if (row.domain && row.subdomain) {
-            key = `${row.subdomain}.${row.domain}`;
-        }
+        const key = row.hostname || undefined;
         if (key) {
             graphileCache.delete(key);
             svcCache.delete(key);

package/esm/middleware/graphile.js

@@ -1,3 +1,4 @@
+import './types'; // for Request type
 import crypto from 'node:crypto';
 import { getNodeEnv } from '@pgpmjs/env';
 import { Logger } from '@pgpmjs/logger';
@@ -6,11 +7,10 @@ import { createFunctionBindingsPlugin } from 'graphile-function-bindings';
 import { createConstructivePreset, makePgService } from 'graphile-settings';
 import { getPgPool } from 'pg-cache';
 import { getPgEnvOptions } from 'pg-env';
-import './types'; // for Request type
 import { isGraphqlObservabilityEnabled } from '../diagnostics/observability';
 import { HandlerCreationError } from '../errors/api-errors';
-import { observeGraphileBuild } from './observability/graphile-build-stats';
 import { AuthCookiePlugin } from '../plugins/auth-cookie-plugin';
+import { observeGraphileBuild } from './observability/graphile-build-stats';
 const maskErrorLog = new Logger('graphile:maskError');
 const SAFE_ERROR_CODES = new Set([
     // GraphQL standard
@@ -115,7 +115,7 @@ const SAFE_ERROR_CODES = new Set([
     '23503', // foreign_key_violation
     '23502', // not_null_violation
     '23514', // check_violation
-    '23P01', // exclusion_violation
+    '23P01' // exclusion_violation
 ]);
 /**
  * Production-aware error masking function.
@@ -142,8 +142,8 @@ const maskError = (error) => {
         message: `An unexpected error occurred. Reference: ${errorId}`,
         extensions: {
             code: 'INTERNAL_SERVER_ERROR',
-            errorId,
-        },
+            errorId
+        }
     };
 };
 // =============================================================================
@@ -204,24 +204,24 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                             definitionsTable: m.definitionsTableName,
                             invocationsSchema: m.invocationsSchemaName,
                             invocationsTable: m.invocationsTableName,
-                            invocationsEntityField: m.invocationsEntityField,
-                        })),
-                    }),
+                            invocationsEntityField: m.invocationsEntityField
+                        }))
+                    })
                 ]
-                : []),
+                : [])
         ],
         pgServices: [
             makePgService({
                 pool,
-                schemas,
-            }),
+                schemas
+            })
         ],
         grafserv: {
             graphqlPath: '/graphql',
             graphiqlPath: '/graphiql',
             graphiql: true,
             graphiqlOnGraphQLGET: false,
-            maskError,
+            maskError
         },
         grafast: {
             explain: process.env.NODE_ENV === 'development',
@@ -234,8 +234,9 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                         context['jwt.claims.database_id'] = req.databaseId;
                     }
                     // API provenance — which API surface this request arrived through.
-                    // Derived server-side from hostname -> services_public.domains -> api_id;
-                    // never taken from client-supplied headers, body, or token payload.
+                    // Derived server-side by resolving the hostname through the scoped
+                    // routing plane (resolve_route -> api_id); never taken from
+                    // client-supplied headers, body, or token payload.
                     if (req.api?.apiId) {
                         context['jwt.claims.api_id'] = req.api.apiId;
                     }
@@ -256,7 +257,7 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                             role: roleName,
                             'jwt.claims.token_id': req.token.id,
                             'jwt.claims.user_id': req.token.user_id,
-                            ...context,
+                            ...context
                         };
                         if (req.token.session_id) {
                             pgSettings['jwt.claims.session_id'] = req.token.session_id;
@@ -283,16 +284,16 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                 }
                 const anonSettings = {
                     role: anonRole,
-                    ...context,
+                    ...context
                 };
                 if (req?.requestId) {
                     anonSettings['request.id'] = req.requestId;
                 }
                 return {
-                    pgSettings: anonSettings,
+                    pgSettings: anonSettings
                 };
-            },
-        },
+            }
+        }
     };
 };
 export const graphile = (opts) => {
@@ -355,7 +356,7 @@ export const graphile = (opts) => {
             log.info(`${label} Building PostGraphile v5 handler key=${key} db=${dbname} schemas=${schemaLabel} role=${roleName} anon=${anonRole}`);
             const pgConfig = getPgEnvOptions({
                 ...opts.pg,
-                database: dbname,
+                database: dbname
             });
             // Route through pg-cache so the pool is tracked and can be cleaned up
             // properly, preventing leaked connections during database teardown.
@@ -366,11 +367,11 @@ export const graphile = (opts) => {
             const creationPromise = observeGraphileBuild({
                 cacheKey: key,
                 serviceKey: key,
-                databaseId: api.databaseId ?? null,
+                databaseId: api.databaseId ?? null
             }, () => createGraphileInstance({
                 preset,
                 cacheKey: key,
-                enableRealtime: api.databaseSettings?.enableRealtime,
+                enableRealtime: api.databaseSettings?.enableRealtime
             }), { enabled: observabilityEnabled });
             creating.set(key, creationPromise);
             try {
@@ -383,7 +384,7 @@ export const graphile = (opts) => {
                 log.error(`${label} Failed to create PostGraphile[${key}]:`, error);
                 throw new HandlerCreationError(`Failed to create handler for ${key}: ${error instanceof Error ? error.message : String(error)}`, {
                     cacheKey: key,
-                    cause: error instanceof Error ? error.message : String(error),
+                    cause: error instanceof Error ? error.message : String(error)
                 });
             }
             finally {

package/esm/middleware/routing.js

@@ -6,8 +6,8 @@ const isValidSchemaName = (name) => /^[a-z_][a-z0-9_]*$/.test(name);
  * Resolve a hostname through the compiled scoped-routing plane (host-only:
  * path/method routing belongs to Traefik/Ingress, not the server).
  * Returns null when there is no match (route_binding_id IS NULL) or when the
- * resolver is not installed in the target database — callers fall back to the
- * legacy services_public lookup in both cases.
+ * resolver is not installed in the target database — in both cases the caller
+ * treats it as a hard no-match (→ 404); there is no legacy fallback.
  */
 export const resolveRoute = async (pool, schema, host) => {
     if (!isValidSchemaName(schema)) {
@@ -26,19 +26,18 @@ export const resolveRoute = async (pool, schema, host) => {
     catch (error) {
         const err = error;
         // 42883 undefined_function / 3F000 invalid_schema_name: resolver not
-        // installed in this database — treat as no-match so the caller falls back.
+        // installed in this database — treat as a hard no-match.
         if (err.code === '42883' || err.code === '3F000') {
-            log.debug(`[resolve-route] resolver not installed (${err.code}); falling back`);
+            log.debug(`[resolve-route] resolver not installed (${err.code}); no match`);
             return null;
         }
         throw error;
     }
 };
 /**
- * Map a resolved api-target route onto the legacy ApiStructure shape consumed
- * by the rest of the middleware chain. Returns null when the route target is
- * not an api surface or its resolved_config lacks the api essentials — the
- * caller falls back to the legacy lookup.
+ * Map a resolved api-target route onto the ApiStructure shape consumed by the
+ * rest of the middleware chain. Returns null when the route target is not an
+ * api surface or its resolved_config lacks the api essentials (→ 404).
  */
 export const routeToApiStructure = (route, opts) => {
     if (route.target_module !== 'apis' && route.target_module !== 'api') {
@@ -46,7 +45,7 @@ export const routeToApiStructure = (route, opts) => {
     }
     const config = (route.resolved_config ?? {});
     if (!config.dbname || !config.schemas?.length) {
-        log.debug('[resolve-route] api target missing dbname/schemas in resolved_config; falling back');
+        log.debug('[resolve-route] api target missing dbname/schemas in resolved_config; no match');
         return null;
     }
     return {
@@ -58,6 +57,6 @@ export const routeToApiStructure = (route, opts) => {
         apiModules: [],
         domains: [],
         databaseId: config.database_id,
-        isPublic: config.is_public ?? (opts.api?.isPublic ?? false),
+        isPublic: config.is_public ?? (opts.api?.isPublic ?? false)
     };
 };