http-dispatcher.ts

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

import {
    ObjectKernel, getEnv, resolveLocale, evaluateAuthGate, isAuthGateAllowlisted,
    shouldDenyAnonymous, ANONYMOUS_DENY_STATUS, ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_MESSAGE,
} from '@objectstack/core';
import { isMcpServerEnabled } from '@objectstack/types';
import { measureServerTiming, allowPerfDisclosure, isPerfDisclosurePrincipal } from '@objectstack/observability';
import { CoreServiceName } from '@objectstack/spec/system';
import { readServiceSelfInfo } from '@objectstack/spec/api';
import { MCP_OAUTH_SCOPES } from '@objectstack/spec/ai';
import { pluralToSingular, PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
import type { ExecutionContext } from '@objectstack/spec/kernel';
import { setPackageDisabled } from './package-state-store.js';
import { checkApiExposure } from './api-exposure.js';

/** Minimal local interface — full EnvironmentScopeManager was removed in Phase R. */
interface EnvironmentScopeManager {
    touch(environmentId: string): void;
}
import {
    resolveExecutionContext,
    isPermissionDeniedError,
} from './security/resolve-execution-context.js';
import { generateApiKey } from './security/api-key.js';

/** Browser-safe UUID generator — prefers Web Crypto, falls back to RFC 4122 v4 */
function randomUUID(): string {
    if (globalThis.crypto && typeof globalThis.crypto.randomUUID === 'function') {
        return globalThis.crypto.randomUUID();
    }
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
        const r = (Math.random() * 16) | 0;
        const v = c === 'x' ? r : (r & 0x3) | 0x8;
        return v.toString(16);
    });
}

/** A `sys_`-prefixed object is a system table — off-limits to external MCP agents. */
function isSystemObjectName(name: string): boolean {
    return /^sys_/i.test(name);
}

// The per-request `Server-Timing` disclosure predicate (#2408) now lives in
// `@objectstack/observability` — the ONE definition shared by every HTTP entry
// point that resolves a principal (this dispatcher, the REST server, the
// standalone Hono CRUD surface), so an admin-serving path can never drift into
// under- or over-disclosing (#3361). Re-exported here for back-compat with the
// dispatcher's existing consumers/tests.
export { isPerfDisclosurePrincipal } from '@objectstack/observability';

export interface HttpProtocolContext {
    request: any;
    response?: any;
    environmentId?: string;   // Resolved environment ID (set by the host's KernelResolver)
    dataDriver?: any; // IDataDriver - Resolved environment-scoped driver (set by the host's KernelResolver)
    /**
     * Dispatcher-provided hint for the host's {@link KernelResolver}: the
     * cleaned route path (API prefix stripped). Lets the resolver apply its
     * own path policy (e.g. skip env resolution for control-plane routes)
     * without re-deriving the dispatcher's URL handling.
     */
    routePath?: string;
    /**
     * Dispatcher-provided hint for the host's {@link KernelResolver}: the
     * UNVALIDATED environment-id candidate parsed from the scoped URL form
     * (`/environments/:id/...`) or the router's `params.environmentId`.
     * URL parsing is the dispatcher's routing convention, so it stays here;
     * validation (registry lookup) is the resolver's job.
     */
    urlEnvironmentId?: string;
    /**
     * Identity envelope resolved by `resolveExecutionContext` and threaded
     * into every ObjectQL call so the SecurityPlugin middleware can apply
     * RBAC/RLS/FLS. Optional — anonymous requests carry an empty context.
     */
    executionContext?: ExecutionContext;
}

export interface HttpDispatcherResult {
    handled: boolean;
    response?: {
        status: number;
        body?: any;
        headers?: Record<string, string>;
    };
    result?: any; // For flexible return types or direct response objects (Response/NextResponse)
}

/**
 * ADR-0006 generic kernel-resolution seam.
 *
 * A host (e.g. ObjectStack Cloud) injects a resolver to own per-request
 * kernel selection. The framework ships NO multi-tenant implementation — all
 * hostname→env strategy, the per-env kernel cache, and the control plane live
 * in the host distribution (`@objectstack/objectos-runtime`). When no resolver
 * is injected the dispatcher serves every request from its single
 * `defaultKernel` (single-environment mode).
 *
 * Returning `undefined` routes the request to `defaultKernel` — resolvers use
 * this for control-plane / unscoped / single-environment requests.
 *
 * As of ADR-0006 Phase 5 the resolver owns the ENTIRE per-request environment
 * resolution, not just kernel selection: the dispatcher no longer performs any
 * hostname / header / session → environment lookup of its own. The dispatcher
 * provides parsing hints on the context (`routePath`, `urlEnvironmentId`) and
 * expects the resolver to SET `context.environmentId` (and optionally
 * `context.dataDriver`) for scoped requests — downstream dispatcher stages
 * (project-membership enforcement, scope TTL touch, scoped service resolution)
 * key off `context.environmentId`.
 */
export interface KernelResolver {
    resolveKernel(
        context: HttpProtocolContext,
        defaultKernel: ObjectKernel,
    ): Promise<ObjectKernel | undefined> | ObjectKernel | undefined;
}

/**
 * Optional configuration passed to the dispatcher constructor. Supports the
 * legacy `enforceProjectMembership` toggle plus the new multi-kernel
 * scheduling hook required by ADR-0003's cloud runtime mode.
 */
export interface HttpDispatcherOptions {
    enforceProjectMembership?: boolean;
    /**
     * Optional generic kernel-resolution seam (ADR-0006). The SOLE
     * multi-tenant hook: the host's resolver owns env resolution + kernel
     * selection per request (see {@link KernelResolver}). Falls back to
     * `resolveService('kernel-resolver')`. Hosts that register none run
     * single-environment on `defaultKernel`. (The legacy `kernelManager`
     * option and the dispatcher's built-in hostname/header/session
     * resolution were removed in ADR-0006 Phase 5 — that strategy lives in
     * the cloud distribution's resolver now.)
     */
    kernelResolver?: KernelResolver;
    /**
     * Optional {@link EnvironmentScopeManager}. When present, `touch(environmentId)` is
     * called on every scoped request so idle projects are evicted after TTL.
     */
    scopeManager?: EnvironmentScopeManager;
    /**
     * Reject anonymous requests to `auth: true` service routes (AI) and to the
     * metadata catch-all with HTTP 401, mirroring the REST API's `requireAuth`
     * gate. Matches {@link DispatcherPluginConfig.requireAuth}; the dispatcher
     * plugin threads the host's `api.requireAuth` here. Defaults to `false`
     * (backward-compatible — nothing enforced `RouteDefinition.auth` before).
     */
    requireAuth?: boolean;
}

/**
 * The HTTP dispatch engine — translates an inbound (method, path, body, ctx)
 * request into a kernel response. Used directly by the framework's HTTP adapters
 * (express / fastify / nextjs / nestjs / nuxt / sveltekit / hono) and plugin-msw,
 * which need a *callable* dispatcher.
 *
 * NOTE: `createDispatcherPlugin()` is a different thing — a kernel plugin that
 * registers routes on a kernel-hosted HTTP server. It is NOT a drop-in for
 * adapters. Retiring this public class behind a `createHttpDispatcher()` factory
 * is tracked in #2380 (a deliberate adapter-API change, not yet done) — so this
 * is intentionally NOT marked `@deprecated` while no working replacement exists.
 */
export class HttpDispatcher {
    private kernel: any; // Casting to any to access dynamic props like services, graphql
    private defaultKernel: ObjectKernel;
    private defaultProject?: { environmentId: string; orgId?: string };
    private kernelResolver?: KernelResolver;
    private scopeManager?: EnvironmentScopeManager;
    /**
     * When `true`, scoped data-plane routes enforce a
     * `sys_environment_member` lookup and return 403 for non-members.
     * Defaults to `true` when a environmentId is resolvable — legacy callers
     * can opt out via the third constructor argument (see
     * `DispatcherConfig.enforceProjectMembership`).
     */
    private enforceMembership: boolean;
    /**
     * When `true`, `auth: true` AI routes and the metadata catch-all reject
     * anonymous callers with 401 (mirrors the REST `requireAuth` gate). Set
     * from {@link HttpDispatcherOptions.requireAuth}. Defaults to `false`.
     */
    private requireAuth: boolean;
    /**
     * In-memory cache of positive membership checks, keyed by
     * `${environmentId}:${userId}`. Entries expire 60 seconds after insertion
     * — a short TTL is acceptable because a user whose access was just
     * revoked sees stale access for at most one minute.
     */
    private membershipCache: Map<string, number> = new Map();
    private static readonly MEMBERSHIP_CACHE_TTL_MS = 60_000;
    /** Well-known system project id — bypassed for any authenticated user. */
    private static readonly SYSTEM_ENVIRONMENT_ID = '00000000-0000-0000-0000-000000000001';
    /** Well-known platform org id — members bypass project membership. */
    private static readonly PLATFORM_ORG_ID = '00000000-0000-0000-0000-000000000000';

    /**
     * @param _envRegistryIgnored — RETIRED (ADR-0006 Phase 5). Environment
     * resolution moved behind the host's {@link KernelResolver}; the
     * positional parameter is kept so existing 3-arg callers keep compiling,
     * but its value is ignored.
     */
    constructor(kernel: ObjectKernel, _envRegistryIgnored?: unknown, options?: HttpDispatcherOptions) {
        this.kernel = kernel;
        this.defaultKernel = kernel;
        const resolveService = (name: string): any => {
            try { return (kernel as any).getService?.(name); } catch { return undefined; }
        };
        this.enforceMembership = options?.enforceProjectMembership ?? true;
        this.requireAuth = options?.requireAuth ?? false;
        // ADR-0006 kernel-resolution seam — the host's resolver owns env
        // resolution + kernel selection. Optional service so single-environment
        // hosts that register none are unchanged.
        this.kernelResolver = options?.kernelResolver ?? resolveService('kernel-resolver');
        this.scopeManager = options?.scopeManager ?? resolveService('scope-manager');
        // Single-project default is resolved lazily on first request — the
        // plugin that registers it (`createSingleEnvironmentPlugin`) may run
        // its `init()` after the HttpDispatcher is constructed.
    }

    private resolveDefaultProject(): { environmentId: string; orgId?: string } | undefined {
        if (this.defaultProject) return this.defaultProject;
        try {
            const v = (this.kernel as any).getService?.('default-project');
            if (v?.environmentId) {
                this.defaultProject = v;
                return v;
            }
        } catch {
            // service not registered — single-environment plugin not in stack
        }
        return undefined;
    }

    /**
     * Resolve the per-request identity/session, timed as the `auth`
     * `Server-Timing` span — the prime suspect for unexplained data-API
     * overhead (session lookup, org-scope resolution). A no-op wrapper when
     * perf-tuning is off, so it costs nothing on the normal path.
     */
    private async timedResolveExecutionContext(
        opts: Parameters<typeof resolveExecutionContext>[0],
    ): Promise<ExecutionContext> {
        const ec = await measureServerTiming('auth', () => resolveExecutionContext(opts), 'Identity/session');
        // Perf-tuning disclosure gate (#2408): when timing was opened
        // per-request via `X-OS-Debug-Timing`, the `Server-Timing` header stays
        // withheld until the request proves an admin/service identity — never
        // leak phase timings to an ordinary caller. A no-op when perf-tuning is
        // off or already global (no gate, or gate already open).
        if (isPerfDisclosurePrincipal(ec)) allowPerfDisclosure();
        return ec;
    }

    private success(data: any, meta?: any) {
        return {
            status: 200,
            body: { success: true, data, meta }
        };
    }

    private error(message: string, code: number = 500, details?: any) {
        return {
            status: code,
            body: { success: false, error: { message, code, details } }
        };
    }

    /**
     * Build an error response from a THROWN service/protocol error, preserving
     * the error's own HTTP `status` and — critically — any structured `issues`
     * array (e.g. spec-validation `{ path, message, code }[]` from
     * `protocol.saveMetaItem`). The plain `error(msg, code)` path collapses a
     * validation failure to a single message, so the UI can only show a generic
     * banner; carrying `issues` (and the semantic `code`) in `details` lets it
     * map each error back to the offending field. Falls back to `fallbackStatus`
     * and behaves exactly like `error()` for errors that carry neither.
     */
    private errorFromThrown(e: any, fallbackStatus = 500) {
        const status =
            typeof e?.status === 'number' ? e.status
            : typeof e?.statusCode === 'number' ? e.statusCode
            : fallbackStatus;
        const issues = Array.isArray(e?.issues) ? e.issues : undefined;
        const details =
            issues || e?.code
                ? { ...(e?.code ? { code: e.code } : {}), ...(issues ? { issues } : {}) }
                : undefined;
        return this.error(e?.message ?? String(e), status, details);
    }

    /**
     * ADR-0046: `doc` list responses omit `content` by default — manuals
     * are the one metadata payload that grows unbounded, and the list
     * surface only needs `name` + `label`. `?include=content` opts back in
     * (single-item GET /metadata/doc/:name always returns the full body).
     */
    private slimDocList(type: string, data: any, query?: Record<string, string>): any {
        if (type !== 'doc' || query?.include === 'content') return data;
        const strip = (items: any[]) =>
            items.map((i) => {
                if (!i || typeof i !== 'object') return i;
                const { content: _content, ...rest } = i as Record<string, unknown>;
                return rest;
            });
        if (Array.isArray(data)) return strip(data);
        if (data && Array.isArray(data.items)) return { ...data, items: strip(data.items) };
        return data;
    }

    /**
     * 404 Route Not Found — no route is registered for this path.
     */
    private routeNotFound(route: string) {
        return {
            status: 404,
            body: {
                success: false,
                error: {
                    code: 404,
                    message: `Route Not Found: ${route}`,
                    type: 'ROUTE_NOT_FOUND' as const,
                    route,
                    hint: 'No route is registered for this path. Check the API discovery endpoint for available routes.',
                },
            },
        };
    }

    /**
     * Direct data service dispatch — replaces broker.call('data.*').
     * Tries protocol service first (supports expand/populate), falls back to ObjectQL.
     *
     * @param dataDriver - Optional environment-scoped driver to use instead of kernel default
     * @param scopeId - Optional project ID for scoped service resolution (SharedProjectPlugin mode)
     */
    private async callData(
        action: string,
        params: any,
        dataDriver?: any,
        scopeId?: string,
        executionContext?: ExecutionContext,
    ): Promise<any> {
        // ── Object-level API exposure gate (ADR-0049, #1889) ─────
        // Honour the object's `apiEnabled` / `apiMethods` declarations for
        // external traffic. System/internal contexts bypass — these flags
        // govern API *exposure*, not internal engine self-writes.
        if (!executionContext?.isSystem && params?.object) {
            let def: any;
            try {
                const meta = await this.resolveService('metadata', scopeId);
                def = await (meta as any)?.getObject?.(params.object);
            } catch {
                def = undefined; // fall open to schema defaults (apiEnabled=true)
            }
            const gate = checkApiExposure(def, action);
            if (!gate.allowed) {
                throw { statusCode: gate.status ?? 403, message: gate.reason ?? 'API access denied' };
            }
        }

        const protocol = await this.resolveService('protocol', scopeId);
        const qlService = dataDriver ?? await this.getObjectQLService(scopeId);
        const ql = qlService ?? await this.resolveService('objectql', scopeId);
        const qlOpts = executionContext ? { context: executionContext } : undefined;
        const findOpts = (extra?: any) => {
            const base = qlOpts ? { ...qlOpts } : {};
            return extra ? { ...base, ...extra } : (qlOpts ? base : undefined);
        };

        if (action === 'create') {
            // Prefer the protocol service (validations + RLS + audit), mirroring
            // the read paths below. The MCP bridge passes `context.dataDriver` as
            // `ql`, which in the multi-env runtime is a RAW db driver with no ORM
            // `insert` — so going straight to `ql.insert` broke MCP create_record
            // ("ql.insert is not a function") while REST (which uses `createData`)
            // worked. Routing writes through the protocol keeps them aligned.
            if (protocol && typeof protocol.createData === 'function') {
                return await protocol.createData({ object: params.object, data: params.data, ...(scopeId ? { environmentId: scopeId } : {}), context: executionContext });
            }
            if (ql && typeof ql.insert === 'function') {
                const res = await ql.insert(params.object, params.data, qlOpts);
                const record = { ...params.data, ...res };
                return { object: params.object, id: record.id, record };
            }
            throw { statusCode: 503, message: 'Data service not available' };
        }

        if (action === 'get') {
            if (protocol && typeof protocol.getData === 'function') {
                return await protocol.getData({ object: params.object, id: params.id, expand: params.expand, select: params.select, context: executionContext });
            }
            if (ql) {
                let all = await ql.find(params.object, findOpts({ where: { id: params.id }, limit: 1 }));
                if (all && (all as any).value) all = (all as any).value;
                if (!all) all = [];
                const match = (all as any[]).find((i: any) => i.id === params.id);
                return match ? { object: params.object, id: params.id, record: match } : null;
            }
            throw { statusCode: 503, message: 'Data service not available' };
        }

        if (action === 'update') {
            if (protocol && typeof protocol.updateData === 'function') {
                return await protocol.updateData({ object: params.object, id: params.id, data: params.data, ...(scopeId ? { environmentId: scopeId } : {}), context: executionContext });
            }
            if (ql && params.id && typeof ql.update === 'function') {
                let all = await ql.find(params.object, findOpts({ where: { id: params.id }, limit: 1 }));
                if (all && (all as any).value) all = (all as any).value;
                if (!all) all = [];
                const existing = (all as any[]).find((i: any) => i.id === params.id);
                if (!existing) throw new Error('[ObjectStack] Not Found');
                await ql.update(params.object, params.data, findOpts({ where: { id: params.id } }));
                return { object: params.object, id: params.id, record: { ...existing, ...params.data } };
            }
            throw { statusCode: 503, message: 'Data service not available' };
        }

        if (action === 'delete') {
            if (protocol && typeof protocol.deleteData === 'function') {
                return await protocol.deleteData({ object: params.object, id: params.id, ...(scopeId ? { environmentId: scopeId } : {}), context: executionContext });
            }
            if (ql && typeof ql.delete === 'function') {
                await ql.delete(params.object, findOpts({ where: { id: params.id } }));
                return { object: params.object, id: params.id, deleted: true };
            }
            throw { statusCode: 503, message: 'Data service not available' };
        }

        if (action === 'query' || action === 'find') {
            if (protocol && typeof protocol.findData === 'function') {
                // Build query: use explicit params.query if provided, otherwise extract query fields from params
                const query = params.query || (() => {
                    const { object, ...rest } = params;
                    return rest;
                })();
                return await protocol.findData({ object: params.object, query, context: executionContext });
            }
            if (ql) {
                let all = await ql.find(params.object, qlOpts);
                if (!Array.isArray(all) && all && (all as any).value) all = (all as any).value;
                if (!all) all = [];
                return { object: params.object, records: all, total: all.length };
            }
            throw { statusCode: 503, message: 'Data service not available' };
        }

        if (action === 'aggregate') {
            // Aggregate MUST run through the ObjectQL ENGINE (never the raw
            // `dataDriver` the MCP bridge threads through for the other verbs):
            // only the engine's middleware chain injects RLS/tenant scoping and
            // the FLS aggregate-input gate. A raw driver.aggregate() would
            // evaluate the query verbatim over every row.
            //
            // At least one aggregation is REQUIRED: with neither aggregations
            // nor groupBy the engine's in-memory path degrades to raw rows,
            // and the FLS result masker does not cover the `aggregate` op —
            // grouped/aggregated output must stay the only thing this action
            // can ever return.
            if (!Array.isArray(params.aggregations) || params.aggregations.length === 0) {
                throw { statusCode: 400, message: 'aggregate requires at least one aggregation' };
            }
            const engine = (await this.getObjectQLService(scopeId))
                ?? await this.resolveService('objectql', scopeId).catch(() => null);
            if (engine && typeof engine.aggregate === 'function') {
                const rows = await engine.aggregate(
                    params.object,
                    {
                        ...(params.where ? { where: params.where } : {}),
                        ...(params.groupBy ? { groupBy: params.groupBy } : {}),
                        ...(params.aggregations ? { aggregations: params.aggregations } : {}),
                        ...(params.timezone ? { timezone: params.timezone } : {}),
                        ...(executionContext ? { context: executionContext } : {}),
                    },
                );
                return { object: params.object, rows: rows ?? [] };
            }
            throw { statusCode: 503, message: 'Data service not available' };
        }

        if (action === 'batch') {
            // Batch operations — not yet supported via direct service dispatch
            return { object: params.object, results: [] };
        }

        throw { statusCode: 400, message: `Unknown data action: ${action}` };
    }

    /**
     * Handle an MCP request over the Streamable HTTP transport (`/mcp`).
     *
     * Gating + auth (fail-closed):
     *  - **default-on**: served unless `OS_MCP_SERVER_ENABLED=false` (single-env
     *    runtime; MCP is a core platform capability). Multi-tenant cloud
     *    overrides this gate per env. When opted out we return 404 so the
     *    surface isn't advertised.
     *  - **auth**: requires a principal already resolved by
     *    `resolveExecutionContext` (the `sys_api_key` Bearer/header path or a
     *    session). Anonymous → 401.
     *
     * Execution: the MCP runtime builds a stateless per-request server whose
     * object-CRUD tools run through {@link callData} bound to THIS request's
     * ExecutionContext — i.e. the exact permission + RLS path the REST API
     * uses. An external agent can never exceed the key's authority.
     */
    async handleMcp(body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        if (!HttpDispatcher.isMcpEnabled()) {
            return { handled: true, response: this.error('MCP server is not enabled for this environment', 404) };
        }

        const mcp: any = await this.resolveService('mcp', context.environmentId);
        if (!mcp || typeof mcp.handleHttpRequest !== 'function') {
            return { handled: true, response: this.error('MCP server is not available', 501) };
        }

        const ec = context.executionContext;
        if (!ec || (!ec.userId && !ec.isSystem)) {
            // Per the MCP authorization spec (RFC 9728 §5.1), a 401 from the
            // protected resource advertises where its metadata lives so an
            // OAuth-capable client can bootstrap discovery → DCR → PKCE.
            // Only advertised when the OAuth track is actually live (AS on +
            // TLS rule satisfied); API-key-only deployments return a plain 401.
            const resourceMetadataUrl = await this.getMcpResourceMetadataUrl(context);
            const response = this.error(
                resourceMetadataUrl
                    ? 'Unauthorized: a valid OAuth access token or API key is required'
                    : 'Unauthorized: a valid API key is required',
                401,
            ) as { status: number; body: any; headers?: Record<string, string> };
            if (resourceMetadataUrl) {
                response.headers = {
                    'WWW-Authenticate':
                        `Bearer realm="ObjectStack MCP", resource_metadata="${resourceMetadataUrl}"`,
                };
            }
            return { handled: true, response };
        }

        // ── OAuth scope → tool-family enforcement (fail-closed, #2698) ──
        // `oauthScopes` is set ONLY for OAuth-token provenance. A token that
        // grants none of the MCP tool families gets 403 insufficient_scope
        // up front; a partial grant narrows the tool set at registration
        // time inside the MCP runtime. API-key / session principals
        // (`oauthScopes` undefined) keep the full principal-bound surface.
        const grantedScopes = Array.isArray((ec as any).oauthScopes)
            ? ((ec as any).oauthScopes as string[])
            : undefined;
        if (grantedScopes && !grantedScopes.some((s) => (MCP_OAUTH_SCOPES as readonly string[]).includes(s))) {
            const resourceMetadataUrl = await this.getMcpResourceMetadataUrl(context);
            const response = this.error(
                `Forbidden: the access token grants none of the MCP scopes (${MCP_OAUTH_SCOPES.join(', ')})`,
                403,
            ) as { status: number; body: any; headers?: Record<string, string> };
            response.headers = {
                'WWW-Authenticate':
                    'Bearer error="insufficient_scope"' +
                    `, scope="${MCP_OAUTH_SCOPES.join(' ')}"` +
                    (resourceMetadataUrl ? `, resource_metadata="${resourceMetadataUrl}"` : ''),
            };
            return { handled: true, response };
        }

        // The MCP transport needs a Web-standard Request. The runtime HTTP
        // adapter may hand us a node/Hono-style req (plain `headers` object,
        // path-only `url`), so normalise it.
        const webRequest = this.toMcpWebRequest(context.request, body);
        if (!webRequest) {
            return { handled: true, response: this.error('MCP transport requires a standard HTTP request', 400) };
        }

        const bridge = this.buildMcpBridge(context);
        let webRes: Response;
        try {
            webRes = await mcp.handleHttpRequest(webRequest, {
                bridge,
                parsedBody: body,
                // undefined = not scope-limited (API key / session); an array
                // narrows the registered tool families inside the MCP runtime.
                ...(grantedScopes ? { toolOptions: { grantedScopes } } : {}),
            });
        } catch (err: any) {
            return { handled: true, response: this.error(err?.message ?? 'MCP request failed', 500) };
        }

        // Convert the transport's buffered Web Response into the dispatcher's
        // `{ status, headers, body }` shape (JSON-response mode → fully buffered).
        const headers: Record<string, string> = {};
        try { webRes.headers.forEach((v, k) => { headers[k] = v; }); } catch { /* no headers */ }
        const text = await webRes.text().catch(() => '');
        let responseBody: any = null;
        if (text) {
            const ct = headers['content-type'] ?? '';
            if (ct.includes('application/json')) {
                try { responseBody = JSON.parse(text); } catch { responseBody = text; }
            } else {
                responseBody = text;
            }
        }
        return { handled: true, response: { status: webRes.status, headers, body: responseBody } };
    }

    /**
     * Whether the MCP HTTP surface is on for this single-env runtime.
     * Default-on core capability; `OS_MCP_SERVER_ENABLED=false` opts out
     * (single decision point: `isMcpServerEnabled` in `@objectstack/types`).
     */
    private static isMcpEnabled(): boolean {
        return isMcpServerEnabled();
    }

    /**
     * Absolute URL of the RFC 9728 protected-resource metadata for the MCP
     * endpoint, advertised via `WWW-Authenticate` (#2698). `null` when the
     * OAuth track is off — the auth service owns the decision (AS enabled +
     * OAuth 2.1 TLS rule), the dispatcher only relays it. Never throws.
     */
    private async getMcpResourceMetadataUrl(context: HttpProtocolContext): Promise<string | null> {
        try {
            const authService: any = await this.resolveService('auth', context.environmentId);
            const url = authService?.getMcpResourceMetadataUrl?.();
            return typeof url === 'string' && url ? url : null;
        } catch {
            return null;
        }
    }

    /**
     * `GET /mcp/skill` — the environment-customized portable Agent Skill
     * (`SKILL.md`), rendered by the MCP service (ADR-0036 Amendment C: ONE
     * generic skill; only the connection URL is environment-specific).
     *
     * Served PUBLIC like `/discovery`: the content is generic agent
     * instructions plus a URL the caller already knows — no schema, no
     * tenant data. Gated on the same default-on switch as the `/mcp` route
     * (404 when opted out, so the surface isn't advertised) and 501 when the
     * MCP plugin isn't loaded, mirroring `handleMcp`.
     */
    async handleMcpSkill(method: string, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        if (!HttpDispatcher.isMcpEnabled()) {
            return { handled: true, response: this.error('MCP server is not enabled for this environment', 404) };
        }
        if (method !== 'GET') {
            return {
                handled: true,
                response: {
                    status: 405,
                    headers: { Allow: 'GET' },
                    body: { success: false, error: { message: 'Method not allowed — use GET', code: 405 } },
                },
            };
        }

        const mcp: any = await this.resolveService('mcp', context.environmentId);
        if (!mcp || typeof mcp.renderSkill !== 'function') {
            return { handled: true, response: this.error('MCP server is not available', 501) };
        }

        // Resolve this environment's MCP URL for the skill's Connect section:
        // the auth service owns the canonical value (base URL config); fall
        // back to deriving from the request host so the endpoint still works
        // when the auth plugin isn't loaded.
        let mcpUrl: string | undefined;
        try {
            const authService: any = await this.resolveService('auth', context.environmentId);
            const url = authService?.getMcpResourceUrl?.();
            if (typeof url === 'string' && url) mcpUrl = url;
        } catch { /* fall through to host derivation */ }
        if (!mcpUrl) {
            try {
                const webReq = this.toMcpWebRequest(context.request, undefined);
                const host = webReq?.headers.get('host');
                if (host) {
                    const proto = webReq?.headers.get('x-forwarded-proto') || 'http';
                    mcpUrl = `${proto}://${host}/api/v1/mcp`;
                }
            } catch { /* leave the documented placeholder in place */ }
        }

        const markdown: string = mcp.renderSkill({ mcpUrl });
        // Raw text must NOT ride the `response` channel — `sendResult` JSON-
        // encodes those bodies unconditionally. The `result` stream channel is
        // the one raw pipe through every adapter (string events are written
        // verbatim, custom headers honored), so serve the markdown as a
        // single-chunk "stream".
        return {
            handled: true,
            result: {
                type: 'stream',
                status: 200,
                contentType: 'text/markdown; charset=utf-8',
                headers: {
                    'content-type': 'text/markdown; charset=utf-8',
                    'content-disposition': 'inline; filename="SKILL.md"',
                    // Same reasoning as /discovery (cloud#152): reflects mutable
                    // runtime config (base URL), must never be edge-cached stale.
                    'cache-control': 'no-store',
                },
                events: (async function* () {
                    yield markdown;
                })(),
            },
        } as any;
    }

    /**
     * Normalise the inbound request into a Web-standard `Request` for the MCP
     * transport. Accepts an already-Web `Request`, or a node/Hono-style req
     * (plain `headers` object, path-only `url`). Returns undefined only if the
     * shape is unusable. The body is carried separately via `parsedBody`, so a
     * GET/DELETE (no body) and a POST (JSON-RPC) both normalise cleanly.
     */
    private toMcpWebRequest(raw: any, parsedBody: any): Request | undefined {
        if (!raw) return undefined;
        // Already a Web Request.
        if (typeof raw.headers?.get === 'function' && typeof raw.url === 'string' && typeof raw.method === 'string') {
            return raw as Request;
        }
        try {
            const method = String(raw.method ?? 'POST').toUpperCase();

            // Normalise headers (plain object or Headers-like).
            const headers = new Headers();
            const h = raw.headers;
            if (h) {
                if (typeof h.forEach === 'function') {
                    h.forEach((v: any, k: any) => { if (v != null) headers.set(String(k), String(v)); });
                } else {
                    for (const k of Object.keys(h)) {
                        const v = (h as any)[k];
                        if (v != null) headers.set(k, Array.isArray(v) ? v.join(',') : String(v));
                    }
                }
            }

            // Build an absolute URL (node req.url is path-only).
            let url: string;
            try {
                url = new URL(String(raw.url)).toString();
            } catch {
                const host = headers.get('host') || 'mcp.local';
                const path = typeof raw.url === 'string' && raw.url ? raw.url : '/api/v1/mcp';
                url = `https://${host}${path.startsWith('/') ? path : `/${path}`}`;
            }

            const init: { method: string; headers: Headers; body?: string } = { method, headers };
            if (method !== 'GET' && method !== 'HEAD' && method !== 'DELETE') {
                init.body = typeof parsedBody === 'string' ? parsedBody : JSON.stringify(parsedBody ?? {});
            }
            return new Request(url, init);
        } catch {
            return undefined;
        }
    }

    /**
     * Build a principal-bound {@link McpDataBridge}: every method runs AS the
     * request's ExecutionContext through {@link callData} (RLS/permissions) and
     * the per-env metadata service. Keeps the MCP tool layer free of any direct
     * engine access.
     */
    private buildMcpBridge(context: HttpProtocolContext): any {
        const ec = context.executionContext;
        const envId = context.environmentId;
        const driver = (context as any).dataDriver;
        const callData = this.callData.bind(this);
        const getMeta = () => this.resolveService('metadata', envId);

        return {
            listObjects: async () => {
                const meta: any = await getMeta();
                const objs: any[] = (await meta?.listObjects?.()) ?? [];
                return objs.map((o) => ({
                    name: o.name,
                    label: o.label ?? o.name,
                    fieldCount: o.fields ? Object.keys(o.fields).length : undefined,
                }));
            },
            describeObject: async (name: string) => {
                const meta: any = await getMeta();
                const def: any = await meta?.getObject?.(name);
                if (!def) return null;
                const fields = def.fields ?? {};
                return {
                    name: def.name,
                    label: def.label ?? def.name,
                    fields: Object.entries(fields).map(([k, f]: [string, any]) => ({
                        name: k,
                        type: f?.type,
                        label: f?.label ?? k,
                        required: f?.required ?? false,
                    })),
                    enableFeatures: def.enable ?? {},
                };
            },
            query: async (object: string, o: any) => {
                const query: any = {};
                if (o?.where) query.where = o.where;
                if (o?.fields) query.fields = o.fields;
                if (typeof o?.limit === 'number') query.limit = o.limit;
                if (typeof o?.offset === 'number') query.offset = o.offset;
                if (o?.orderBy) query.orderBy = o.orderBy;
                return await callData('query', { object, query }, driver, envId, ec);
            },
            get: async (object: string, id: string) => {
                const res: any = await callData('get', { object, id }, driver, envId, ec);
                return res?.record ?? res ?? null;
            },
            aggregate: async (object: string, o: any) => {
                // NOTE: `driver` (the raw per-env db driver) is deliberately NOT
                // passed — callData's aggregate branch resolves the ObjectQL
                // engine itself so the security middleware (RLS + FLS aggregate
                // gate) always runs. See the branch comment in callData.
                const res: any = await callData(
                    'aggregate',
                    {
                        object,
                        where: o?.where,
                        groupBy: o?.groupBy,
                        aggregations: o?.aggregations,
                        timezone: o?.timezone,
                    },
                    undefined,
                    envId,
                    ec,
                );
                return res?.rows ?? [];
            },
            create: async (object: string, data: any) =>
                await callData('create', { object, data }, driver, envId, ec),
            update: async (object: string, id: string, data: any) =>
                await callData('update', { object, id, data }, driver, envId, ec),
            remove: async (object: string, id: string) =>
                await callData('delete', { object, id }, driver, envId, ec),

            // ── Business-action surface (McpActionBridge) ──────────────
            // Resolution + dispatch flow through the framework's own action
            // mechanism (engine.executeAction / automation flow runner). All
            // gating is at INVOKE time — `ai.exposed` (author opt-in, #2849) +
            // the ADR-0066 D4 capability gate + record load under the caller's
            // RLS. Script/body handlers then run TRUSTED (see
            // buildActionEngineFacade); flows honour `runAs` with the caller's
            // identity forwarded. No `@objectstack/service-ai`.
            listActions: async () => {
                const meta: any = await getMeta();
                const hasAutomation = Boolean(
                    await this.resolveService('automation', envId).catch(() => null),
                );
                const out: any[] = [];
                for (const { action, objectName, obj } of await this.collectActionDeclarations(meta)) {
                    if (!objectName || isSystemObjectName(objectName)) continue; // fail-closed on sys_*
                    if (!this.isHeadlessInvokableAction(action, hasAutomation)) continue;
                    // [#2849 / ADR-0011] MCP is an AI surface: only actions the
                    // author explicitly opted in via `ai.exposed` are listed.
                    // Fail-closed — bodies run as trusted code (see
                    // buildActionEngineFacade), so author opt-in is the boundary.
                    if (this.actionAiExposureError(action)) continue;
                    // Hide actions the caller is not permitted to run.
                    if (this.actionPermissionError(action, ec)) continue;
                    out.push(this.summarizeAction(action, obj, objectName));
                }
                return out;
            },
            runAction: async (
                name: string,
                input: { objectName?: string; recordId?: string; params?: Record<string, unknown> },
            ) => this.invokeBusinessAction(name, input ?? {}, { driver, envId, ec, getMeta, callData }),
        };
    }

    // ── MCP action bridge helpers ──────────────────────────────────────

    /**
     * [ADR-0066 D4] Shared capability gate for an action invocation. Returns a
     * human-readable error string when the caller's `systemPermissions` don't
     * cover the action's declared `requiredPermissions`, or `null` when allowed.
     * System/engine self-invocation (`isSystem`) bypasses; an action without
     * `requiredPermissions` is ungated. Single-sourced so the REST `/actions/...`
     * route and the MCP `run_action` bridge enforce the SAME declaration.
     */
    private actionPermissionError(actionDef: any, ec: any, objectName?: string): string | null {
        const required: string[] = Array.isArray(actionDef?.requiredPermissions)
            ? actionDef.requiredPermissions
            : [];
        if (required.length === 0) return null;
        if (ec?.isSystem) return null;
        const held = new Set<string>(ec?.systemPermissions ?? []);
        const missing = required.filter((perm) => !held.has(perm));
        if (missing.length === 0) return null;
        const on = objectName ? ` on '${objectName}'` : '';
        return (
            `Action '${actionDef?.name ?? 'unknown'}'${on} requires capability ` +
            `[${required.join(', ')}] — caller is missing [${missing.join(', ')}]`
        );
    }

    /**
     * [#2849 / ADR-0011] AI-exposure gate for the MCP action surface. Returns a
     * human-readable error string unless the action's author explicitly opted it
     * into the AI surface with `ai.exposed: true`, or `null` when exposed.
     *
     * This gate is the REAL agent-facing boundary for actions: script/body
     * handlers execute as TRUSTED application code (the engine facade carries no
     * ExecutionContext — see {@link buildActionEngineFacade}), so once invoked, a
     * body's reads/writes are NOT bounded by the caller's RLS/FLS or an agent's
     * data ceiling (ADR-0090 D10). The author's explicit opt-in — not a data-layer
     * backstop — therefore decides what AI may trigger. Fail-closed by default.
     */
    private actionAiExposureError(actionDef: any, objectName?: string): string | null {
        if (actionDef?.ai?.exposed === true) return null;
        const on = objectName ? ` on '${objectName}'` : '';
        return (
            `Action '${actionDef?.name ?? 'unknown'}'${on} is not exposed to AI — ` +
            `the app author must opt it in with \`ai: { exposed: true, description: … }\``
        );
    }

    /**
     * Whether an action has a headless invocation path (so MCP can run it).
     * Mirrors the supported-type set of the (now cloud-side) action-tools
     * bridge: `script` needs a handler binding (`target`) or an inline `body`;
     * `flow` needs a `target` and an automation service. UI-only types
     * (`url`, `modal`, `form`) and `api` have no server dispatch here.
     */
    private isHeadlessInvokableAction(action: any, hasAutomation: boolean): boolean {
        const type: string = action?.type ?? 'script';
        if (type === 'script') return Boolean(action?.target || action?.body);
        if (type === 'flow') return Boolean(action?.target) && hasAutomation;
        return false;
    }

    /** True when an action is destructive by author signal/heuristic (HITL hint). */
    private actionLooksDestructive(action: any): boolean {
        if (action?.ai?.requiresConfirmation !== undefined) return Boolean(action.ai.requiresConfirmation);
        return Boolean(action?.confirmText || action?.mode === 'delete' || action?.variant === 'danger');
    }

    /** Project an action's declarative metadata into a lean MCP summary. */
    private summarizeAction(action: any, obj: any, objectName: string): any {
        const requiresRecord =
            Array.isArray(action?.locations) &&
            action.locations.some(
                (l: string) =>
                    l === 'list_item' || l === 'record_header' || l === 'record_more' || l === 'record_related',
            );
        const description =
            (typeof action?.ai?.description === 'string' ? action.ai.description : undefined) ??
            (typeof action?.label === 'string' ? action.label : undefined);
        const params = this.summarizeActionParams(action, obj);
        return {
            name: action.name,
            objectName,
            ...(typeof action?.label === 'string' ? { label: action.label } : {}),
            ...(description ? { description } : {}),
            type: action?.type ?? 'script',
            requiresRecord: Boolean(requiresRecord),
            requiresConfirmation: this.actionLooksDestructive(action),
            ...(params.length > 0 ? { params } : {}),
        };
    }

    /** Map an ObjectStack field type to a JSON-Schema primitive (conservative). */
    private jsonTypeOf(t: string | undefined): 'string' | 'number' | 'boolean' | 'array' {
        switch (t) {
            case 'number': case 'currency': case 'percent': case 'rating': case 'slider': case 'autonumber':
                return 'number';
            case 'boolean': case 'toggle':
                return 'boolean';
            case 'multiselect': case 'checkboxes': case 'tags':
                return 'array';
            default:
                return 'string';
        }
    }

    /** Resolve an action's params into LLM-facing summaries (field-backed types resolved). */
    private summarizeActionParams(action: any, obj: any): any[] {
        const fields: Record<string, any> = obj?.fields ?? {};
        const out: any[] = [];
        for (const p of (Array.isArray(action?.params) ? action.params : [])) {
            const fieldRef: string | undefined = p?.field;
            const field = fieldRef ? fields[fieldRef] : undefined;
            const name: string | undefined = p?.name ?? fieldRef;
            if (!name) continue;
            const type = this.jsonTypeOf(p?.type ?? field?.type);
            const label = typeof p?.label === 'string' ? p.label : field?.label;
            const help = p?.helpText ?? field?.description;
            const description = [label, help].filter(Boolean).join(' — ') || undefined;
            const optionSource = p?.options ?? field?.options;
            const enumVals = Array.isArray(optionSource)
                ? optionSource
                      .map((o: any) => (typeof o === 'string' ? o : o?.value))
                      .filter((v: any): v is string => typeof v === 'string')
                : [];
            out.push({
                name,
                type,
                required: Boolean(p?.required ?? field?.required ?? false),
                ...(description ? { description } : {}),
                ...(enumVals.length > 0 ? { enum: enumVals } : {}),
            });
        }
        return out;
    }

    /**
     * Slim engine facade matching the ActionContext.engine shape handlers expect.
     *
     * ⚠️ TRUSTED (SECURITY-DEFINER-like) BY DESIGN (#2849): these calls carry NO
     * ExecutionContext, so the data engine's security middleware skips RLS / FLS /
     * CRUD / tenant scoping entirely. Action bodies are the app author's own code
     * and legitimately perform cross-object writes the invoking user could not
     * (convert-lead, cascade-close). The boundary is therefore enforced at INVOKE
     * time (`ai.exposed` + ADR-0066 D4 capability gate), and every dispatch is
     * audit-logged. Longer-term direction: an action-level `runAs: 'user'|'system'`
     * mirroring flows (ADR-0049) — tracked in #2849.
     */
    /**
     * Build the action-body `ctx.session` from the request ExecutionContext,
     * mirroring the hook `ctx.session` shape (#3280) so an action author reads
     * the caller's active org under the SAME blessed name as a hook author.
     *
     * `organizationId` is the blessed name for the caller's active org — the
     * same value as the `organization_id` column and `current_user.organizationId`
     * (RLS). The deprecated `session.tenantId` alias (#3280) was removed in v11
     * (#3290); the driver-layer `ExecutionContext.tenantId` it is sourced from is
     * a distinct, configurable axis and stays. Returns undefined for a genuinely
     * context-less / self-invoked call so a body can distinguish "no session" the
     * same way hooks do.
     */
    private buildActionSession(ec: any): any | undefined {
        if (!ec || (ec.userId == null && ec.tenantId == null)) return undefined;
        return {
            ...(ec.userId != null ? { userId: String(ec.userId) } : {}),
            ...(ec.tenantId != null ? { organizationId: String(ec.tenantId) } : {}),
            ...(Array.isArray(ec.positions) && ec.positions.length ? { roles: ec.positions } : {}),
        };
    }

    private buildActionEngineFacade(ql: any): any {
        return {
            async insert(object: string, data: Record<string, unknown>): Promise<{ id: string }> {
                const res = await ql.insert(object, data);
                const id = (res && (res as any).id) ?? (data as any).id;
                return { id };
            },
            async update(object: string, id: string, data: Record<string, unknown>): Promise<void> {
                await ql.update(object, data, { where: { id } });
            },
            // Tolerant of both the single-id and array conventions handler suites
            // use (CRM handlers pass one id; todo handlers pass an id array).
            async delete(object: string, idOrIds: string | string[]): Promise<void> {
                const ids = Array.isArray(idOrIds) ? idOrIds : [idOrIds];
                for (const id of ids) {
                    if (id != null) await ql.delete(object, { where: { id } });
                }
            },
            async find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>> {
                const opts = query && Object.keys(query).length ? { where: query } : undefined;
                const rows = await ql.find(object, opts as any);
                return Array.isArray(rows) ? rows : ((rows as any)?.value ?? []);
            },
        };
    }

    /**
     * Resolve + invoke a business action by its declarative name for the MCP
     * `run_action` tool. Enforces the AI-exposure gate (`ai.exposed`, #2849), the
     * ADR-0066 D4 capability gate, loads the subject record under the caller's
     * RLS for row-context actions, and dispatches through the framework's
     * `engine.executeAction` (script/body) or automation flow runner (flow).
     * Throws on denial / not-found / handler failure so the tool surfaces a
     * clean tool-error. No service-ai dependency.
     *
     * SECURITY MODEL (#2849): all gating happens at INVOKE time. A script/body
     * handler then runs as trusted code — its engine facade performs
     * context-less reads/writes that bypass RLS/FLS (SECURITY-DEFINER-like), so
     * the caller's permissions and an agent's ADR-0090 D10 data ceiling do NOT
     * bound what the body does internally. Flow actions differ: the flow engine
     * receives the caller's identity below and honours `runAs` (ADR-0049).
     */
    private async invokeBusinessAction(
        name: string,
        input: { objectName?: string; recordId?: string; params?: Record<string, unknown> },
        wiring: {
            driver: any;
            envId?: string;
            ec: any;
            getMeta: () => any;
            callData: (action: string, params: any, dataDriver?: any, scopeId?: string, ec?: ExecutionContext) => Promise<any>;
        },
    ): Promise<any> {
        const { driver, envId, ec, getMeta, callData } = wiring;
        const meta: any = await getMeta();
        const params = input?.params && typeof input.params === 'object' ? input.params : {};
        const recordId = typeof input?.recordId === 'string' && input.recordId.length > 0 ? input.recordId : undefined;

        // Resolve the action def by declarative name (optionally scoped).
        const resolved = await this.resolveActionByName(meta, name, input?.objectName);
        if (!resolved) {
            throw new Error(
                input?.objectName
                    ? `Action '${name}' not found on object '${input.objectName}'`
                    : `Action '${name}' not found`,
            );
        }
        const { action, objectName } = resolved;

        // Fail-closed on system-object actions (mirrors the object-tool guard).
        if (isSystemObjectName(objectName)) {
            throw new Error(`Action '${name}' is on a system object and is not exposed via MCP`);
        }
        const hasAutomation = Boolean(await this.resolveService('automation', envId).catch(() => null));
        if (!this.isHeadlessInvokableAction(action, hasAutomation)) {
            throw new Error(
                `Action '${name}' (type='${action?.type ?? 'script'}') cannot be invoked via MCP`,
            );
        }

        // [#2849 / ADR-0011] AI-exposure gate — fail-closed. Bodies run trusted
        // (unbounded by the caller's RLS or an agent's data ceiling), so only
        // actions the author explicitly exposed to AI may be invoked here.
        const exposureError = this.actionAiExposureError(action, objectName);
        if (exposureError) throw new Error(exposureError);

        // ADR-0066 D4 capability gate — same declaration the REST route enforces.
        const gateError = this.actionPermissionError(action, ec, objectName);
        if (gateError) throw new Error(gateError);

        // Load the subject record under RLS when row-context (engages the same
        // permission path as get_record — an unseen record reads as not-found).
        let record: Record<string, unknown> = {};
        if (recordId && objectName !== 'global') {
            try {
                const got: any = await callData('get', { object: objectName, id: recordId }, driver, envId, ec);
                if (got?.record) record = got.record;
            } catch {
                /* new-record / record-less actions pass an empty record */
            }
        }
        if (record && (record as any).id == null && recordId) (record as any).id = recordId;

        const user = ec?.userId
            ? {
                id: ec.userId,
                name: ec.userName ?? ec.userDisplayName ?? ec.userId,
                // `organizationId` is the blessed name for the caller's active
                // org (matches columns + `current_user.organizationId`); the
                // action body executes TRUSTED (RLS-bypassing), so a body that
                // wants to scope by org must read it here (#3280).
                ...(ec.tenantId != null ? { organizationId: String(ec.tenantId) } : {}),
              }
            : { id: 'system', name: 'system' };

        // ── flow dispatch ──
        if (action.type === 'flow') {
            const automation: any = await this.resolveService('automation', envId).catch(() => null);
            if (!automation || typeof automation.execute !== 'function') {
                throw new Error(`Action '${name}' is a flow but no automation service is available`);
            }
            // Pass a proper AutomationContext (the engine never read the former
            // `triggerData` envelope). Forwarding the caller's identity is what
            // lets a `runAs:'user'` flow enforce RLS as the invoker instead of
            // falling into the user-less UNSCOPED path (#2849, ADR-0049 / #1888;
            // mirrors the record-change trigger's context shape).
            const result: any = await automation.execute(action.target, {
                record,
                ...(objectName !== 'global' ? { object: objectName } : {}),
                userId: ec?.userId,
                ...(Array.isArray(ec?.positions) && ec.positions.length ? { positions: ec.positions } : {}),
                ...(Array.isArray(ec?.permissions) && ec.permissions.length ? { permissions: ec.permissions } : {}),
                ...(ec?.tenantId ? { tenantId: ec.tenantId } : {}),
                // Record fields seed flows' named `isInput` variables (like the
                // record-change trigger); explicit action params win on clash.
                params: { ...record, ...params },
            });
            if (result && typeof result === 'object' && 'success' in result && result.success === false) {
                throw new Error(`Flow '${action.target}' failed: ${result.error ?? 'unknown error'}`);
            }
            return { ok: true, action: action.name, objectName, ...(recordId ? { recordId } : {}), result: result ?? null };
        }

        // ── script/body dispatch via the engine's executeAction ──
        const ql: any = await this.getObjectQLService(envId);
        if (!ql || typeof ql.executeAction !== 'function') {
            throw new Error('Data engine not available for action dispatch');
        }
        // [#2849] Trusted-mode elevation must be AUDIBLE: the body's engine
        // facade bypasses RLS/FLS, so record who triggered which action.
        console.info(
            `[action-audit] MCP run_action '${action.name}' on '${objectName}' — body executes TRUSTED ` +
            `(context-less engine, RLS/FLS-bypassing) for user '${ec?.userId ?? 'anonymous'}'` +
            (ec?.principalKind === 'agent' ? ` (AGENT on behalf of '${ec?.onBehalfOf?.userId ?? 'unknown'}')` : ''),
        );
        const actionContext: any = {
            record,
            user,
            session: this.buildActionSession(ec),
            engine: this.buildActionEngineFacade(ql),
            params: { ...params, recordId, objectName },
        };
        // Handler key: body-based actions register under `name` (AppPlugin);
        // target-bound script actions register under `target` (user code).
        // Probe both, then the wildcard object, distinguishing the engine's
        // "action not registered" miss from a genuine handler error.
        const primary = action.body ? action.name : (action.target || action.name);
        const candidates = [primary, action.target, action.name].filter(
            (k: unknown, i: number, a: unknown[]): k is string => typeof k === 'string' && a.indexOf(k) === i,
        );
        const notRegistered = (err: any) => /Action '.+' on object '.+' not found/i.test(String(err?.message ?? err));
        for (const obj of [objectName, '*']) {
            for (const key of candidates) {
                try {
                    const result = await ql.executeAction(obj, key, actionContext);
                    return { ok: true, action: action.name, objectName, ...(recordId ? { recordId } : {}), result: result ?? null };
                } catch (err: any) {
                    if (!notRegistered(err)) throw err; // real handler failure → surface
                }
            }
        }
        throw new Error(`No handler registered for action '${name}' on '${objectName}'`);
    }

    /**
     * Find an action's declarative definition by name across object metadata,
     * optionally scoped to a single object. Returns the action plus its owning
     * object name, or `null`. Throws when the name is ambiguous across objects
     * and no `objectName` was supplied (so `run_action` can ask for one).
     */
    private async resolveActionByName(
        meta: any,
        name: string,
        objectName?: string,
    ): Promise<{ action: any; objectName: string } | null> {
        const decls = await this.collectActionDeclarations(meta);
        if (objectName) {
            const hit = decls.find((d) => d.objectName === objectName && d.action?.name === name);
            return hit ? { action: hit.action, objectName } : null;
        }
        const matches = decls.filter((d) => d.action?.name === name);
        if (matches.length === 0) return null;
        if (matches.length > 1) {
            const where = matches.map((m) => m.objectName).join(', ');
            throw new Error(`Action '${name}' exists on multiple objects (${where}); pass objectName to disambiguate`);
        }
        return { action: matches[0].action, objectName: matches[0].objectName };
    }

    /**
     * The MCP surface's single declaration source: every action declaration the
     * bridge may list or invoke, as `{ action, objectName, obj }` rows.
     *
     * Two shapes feed it (#3010):
     *  1. `object.actions` — bundle/artifact objects and authored object rows.
     *  2. Standalone `action` metadata items — Studio-authored rows that the
     *     engine executes since #2608 (`resyncAuthoredActions`) but that never
     *     appear inside any object definition. Their owning object follows the
     *     same convention as the engine registration key (`objectName` field,
     *     legacy `object` field, else the `'global'` wildcard).
     *
     * On a key clash (`objectName:name`) the object-embedded declaration wins,
     * mirroring the execution layer's artifact-wins rule — `resyncAuthoredActions`
     * refuses to clobber an artifact-registered handler, so the embedded
     * declaration is the one that matches what actually runs. All MCP gating
     * (`ai.exposed`, ADR-0066 D4, headless-invokability) applies downstream of
     * this collection, unchanged.
     */
    private async collectActionDeclarations(
        meta: any,
    ): Promise<Array<{ action: any; objectName: string; obj: any }>> {
        const objs: any[] = (await meta?.listObjects?.()) ?? [];
        const objByName = new Map<string, any>();
        for (const obj of objs) {
            if (typeof obj?.name === 'string') objByName.set(obj.name, obj);
        }
        const out: Array<{ action: any; objectName: string; obj: any }> = [];
        const seen = new Set<string>();
        for (const obj of objs) {
            const objectName: string | undefined = obj?.name;
            if (!objectName) continue;
            for (const action of Array.isArray(obj?.actions) ? obj.actions : []) {
                if (!action || typeof action.name !== 'string') continue;
                seen.add(`${objectName}:${action.name}`);
                out.push({ action, objectName, obj });
            }
        }
        let standalone: any[] = [];
        try {
            standalone = (await meta?.loadMany?.('action')) ?? [];
        } catch {
            standalone = []; // no standalone-item source on this metadata service
        }
        for (const action of standalone) {
            if (!action || typeof action.name !== 'string') continue;
            const objectName = this.standaloneActionObjectName(action);
            const key = `${objectName}:${action.name}`;
            if (seen.has(key)) continue; // object-embedded declaration wins
            seen.add(key);
            out.push({ action, objectName, obj: objByName.get(objectName) });
        }
        return out;
    }

    /**
     * Owning object of a standalone `action` item — must stay in lockstep with
     * the ObjectQL plugin's `actionObjectKey` (the engine registration key), so
     * the declaration the MCP surface resolves is the one whose handler
     * `executeAction` will find: spec `objectName`, bundle-collector `object`,
     * else the `'global'` wildcard.
     */
    private standaloneActionObjectName(action: any): string {
        if (typeof action?.objectName === 'string' && action.objectName.length > 0) return action.objectName;
        if (typeof action?.object === 'string' && action.object.length > 0) return action.object;
        return 'global';
    }

    /**
     * Generate a `sys_api_key` and return the raw secret EXACTLY ONCE
     * (`POST /keys`). This is the only mint path — the raw key is never stored
     * (only its sha256 hash) and never re-displayable.
     *
     * Security (zero-tolerance):
     *  - Requires an authenticated principal; `user_id` is PINNED to that
     *    caller and is NEVER read from the request body (no impersonation).
     *  - Body is whitelisted to `name` (+ optional `expires_at`); any
     *    `key` / `id` / `user_id` / `revoked` in the body is ignored, so a
     *    caller cannot forge a known-secret or escalate.
     *  - `scopes` are intentionally NOT accepted from the body in v1: the
     *    verify path ADDS scopes to the principal's permissions, so honouring
     *    arbitrary body scopes would be an escalation vector. A generated key
     *    therefore acts exactly AS the caller (via `user_id` resolution).
     *    Narrowing/scoped keys need subset-enforcement — deferred.
     *  - The raw key and its hash never enter logs or error messages.
     *  - The row is written with an elevated `{ isSystem: true }` context
     *    because `sys_api_key` is protection-locked; safe because the row's
     *    contents are fully server-controlled (user_id pinned to caller).
     */
    async handleKeys(method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        if (method !== 'POST') {
            return { handled: true, response: this.error('Method not allowed', 405) };
        }

        const ec = context.executionContext;
        if (!ec || !ec.userId) {
            return { handled: true, response: this.error('Unauthorized: sign in to generate an API key', 401) };
        }

        // ── Whitelist the body. Only `name` and optional `expires_at`. ──
        const rawName = typeof body?.name === 'string' ? body.name.trim() : '';
        const name = rawName || 'API Key';

        let expiresAt: string | undefined;
        if (body?.expires_at != null && body.expires_at !== '') {
            const ms = typeof body.expires_at === 'number'
                ? (body.expires_at < 1e12 ? body.expires_at * 1000 : body.expires_at)
                : Date.parse(String(body.expires_at));
            if (Number.isNaN(ms)) {
                return { handled: true, response: this.error('Invalid expires_at: must be a parseable date', 400) };
            }
            if (ms <= Date.now()) {
                return { handled: true, response: this.error('Invalid expires_at: must be in the future', 400) };
            }
            expiresAt = new Date(ms).toISOString();
        }

        const ql = (await this.getObjectQLService(context.environmentId))
            ?? (await this.resolveService('objectql', context.environmentId));
        if (!ql || typeof ql.insert !== 'function') {
            return { handled: true, response: this.error('Data service not available', 503) };
        }

        // Generate AFTER validation so we never mint on a rejected request.
        const generated = generateApiKey();

        // Server-controlled row. user_id is pinned to the caller; only the hash
        // is persisted. NOTHING from the body can set key/id/user_id/revoked.
        const row: Record<string, unknown> = {
            name,
            key: generated.hash,
            prefix: generated.prefix,
            user_id: ec.userId,
            revoked: false,
        };
        if (expiresAt) row.expires_at = expiresAt;

        let inserted: any;
        try {
            inserted = await ql.insert('sys_api_key', row, { context: { isSystem: true } });
        } catch {
            // Never surface the underlying error (could echo row contents).
            return { handled: true, response: this.error('Failed to create API key', 500) };
        }
        const id = inserted?.id ?? (Array.isArray(inserted) ? inserted[0]?.id : undefined);

        // Raw key returned ONCE. Do not log it.
        return {
            handled: true,
            response: {
                status: 201,
                body: {
                    success: true,
                    data: {
                        id,
                        name,
                        prefix: generated.prefix,
                        key: generated.raw,
                        ...(expiresAt ? { expires_at: expiresAt } : {}),
                    },
                },
            },
        };
    }

    /**
     * Parse a project UUID out of a scoped URL path such as
     * `/api/v1/environments/abc-123/data/task` or `/projects/abc-123/meta`.
     * Returns `undefined` when the path does not match the scoped pattern.
     */
    /**
     * Parse an environment UUID out of a scoped URL path such as
     * `/api/v1/environments/abc-123/data/task` or `/environments/abc-123/meta`.
     * Returns `undefined` when the path does not match the scoped pattern.
     */
    private extractEnvironmentIdFromPath(path: string): string | undefined {
        if (!path) return undefined;
        const m = path.match(/\/environments\/([^/?#]+)/);
        if (!m) return undefined;
        const candidate = m[1];
        // Guard against matching control-plane routes like /cloud/environments.
        // `/environments/<id>` directly nested under the API prefix wins;
        // `/cloud/environments/<id>` is a CRUD endpoint on the control plane.
        if (path.includes('/cloud/environments/')) return undefined;
        return candidate;
    }

    /**
     * Attach the dispatcher's parsing hints for the host's
     * {@link KernelResolver} (ADR-0006 Phase 5).
     *
     * Environment RESOLUTION (hostname / x-environment-id / session /
     * org-default / single-env-default → environment + driver) is owned by
     * the host's resolver — the dispatcher no longer touches an environment
     * registry. What stays here is pure URL parsing (the dispatcher's own
     * routing convention): the scoped-path environment-id candidate and the
     * cleaned route path, both UNVALIDATED.
     */
    private prepareResolverHints(context: HttpProtocolContext, path: string): void {
        context.routePath = path;
        const urlEnvironmentId = this.extractEnvironmentIdFromPath(path)
            ?? context.request?.params?.environmentId;
        if (urlEnvironmentId) context.urlEnvironmentId = String(urlEnvironmentId);
    }

    /**
     * Check whether the authenticated user is a member of
     * `context.environmentId`. Runs after {@link resolveEnvironmentContext}
     * and is a no-op when:
     *
     *   - Membership enforcement is disabled via the constructor.
     *   - The route is control-plane (`/auth/*`, `/cloud/*`, `/health`,
     *     `/discovery`) — already skipped upstream.
     *   - No `environmentId` was resolved (e.g. unscoped legacy routes).
     *   - The project is the well-known system project (bypassed so any
     *     authenticated user can read platform metadata).
     *   - The user's active organization is the platform org (staff).
     *
     * Positive results are cached for 60 seconds to avoid hitting the
     * control-plane on every request. A failed check returns a 403
     * response object that callers should surface directly — no further
     * dispatch happens.
     */
    /**
     * ADR-0069 — returns a 403 response when the resolved session is blocked by
     * an auth-policy gate (expired password / required MFA) on a non-allow-listed
     * path, else null. Mirrors the REST `enforceAuth` seam so REST + dispatcher
     * (MCP, GraphQL) enforce consistently. Fails open on any lookup error.
     */
    private async enforceAuthGate(context: any, cleanPath: string): Promise<any | null> {
        try {
            if (isAuthGateAllowlisted(cleanPath)) return null;
            const authService: any = await this.resolveService('auth', context.environmentId);
            if (!authService || typeof authService.isAuthGateActive !== 'function' || !authService.isAuthGateActive()) {
                return null;
            }
            let api: any = authService.api;
            if (!api && typeof authService.getApi === 'function') api = await authService.getApi();
            if (!api?.getSession) return null;
            // Normalize headers to a Web Headers instance for getSession.
            const raw: any = context?.request?.headers;
            let headers: any;
            if (raw && typeof raw.get === 'function') {
                headers = raw;
            } else if (raw && typeof raw === 'object') {
                headers = new (globalThis as any).Headers();
                for (const k of Object.keys(raw)) {
                    const v = raw[k];
                    if (v != null) headers.set(String(k), Array.isArray(v) ? v.join(',') : String(v));
                }
            } else {
                return null;
            }
            const session: any = await api.getSession({ headers }).catch(() => undefined);
            const gate = evaluateAuthGate(session?.user, cleanPath);
            if (!gate) return null;
            return this.error(gate.message, 403, { code: gate.code });
        } catch {
            return null; // fail-open — never break dispatch on a gate hiccup
        }
    }

    private async enforceProjectMembership(
        context: HttpProtocolContext,
        path: string,
    ): Promise<{ status: number; body: any } | null> {
        if (!this.enforceMembership) return null;

        // Control-plane paths — never gated by project membership.
        const skipPaths = ['/auth', '/cloud', '/health', '/ready', '/discovery'];
        if (skipPaths.some(p => path.startsWith(p))) return null;

        // Public share-link resolve/messages — the token IS the authorisation,
        // so never gate them on project membership (a signed-in non-member
        // opening a public link must not be 403'd before the token handler runs).
        if (/(^|\/)share-links\/[^/]+\/(resolve|messages)$/.test(path)) return null;

        const environmentId = context.environmentId;
        if (!environmentId) return null; // Unscoped legacy routes fall through.

        // System project is always reachable by any authenticated user.
        if (environmentId === HttpDispatcher.SYSTEM_ENVIRONMENT_ID) return null;

        // Read the session. If auth is not wired up, fail open — tests
        // and single-tenant setups run without auth.
        let userId: string | undefined;
        let activeOrganizationId: string | undefined;
        try {
            const authService: any = await this.resolveService(CoreServiceName.enum.auth);
            const sessionData = await authService?.api?.getSession?.({
                headers: context.request?.headers,
            });
            userId = sessionData?.user?.id ?? sessionData?.session?.userId;
            activeOrganizationId = sessionData?.session?.activeOrganizationId;
        } catch {
            // Auth resolution failed — do not block the request on RBAC.
            return null;
        }

        if (!userId) return null; // Anonymous requests — upstream auth will decide.

        // Platform-org members bypass project membership.
        if (activeOrganizationId === HttpDispatcher.PLATFORM_ORG_ID) return null;

        // Check cache.
        const cacheKey = `${environmentId}:${userId}`;
        const cached = this.membershipCache.get(cacheKey);
        const now = Date.now();
        if (cached && now - cached < HttpDispatcher.MEMBERSHIP_CACHE_TTL_MS) {
            return null; // Recently verified as a member.
        }
        if (cached) {
            this.membershipCache.delete(cacheKey); // expired
        }

        // Query sys_environment_member (control plane).
        try {
            const qlService = await this.getObjectQLService();
            const ql = qlService ?? await this.resolveService('objectql');
            if (!ql) return null; // No QL — cannot enforce; fail open.

            let rows = await ql.find('sys_environment_member', {
                where: { environment_id: environmentId, user_id: userId },
                limit: 1,
            } as any);
            if (rows && (rows as any).value) rows = (rows as any).value;
            const isMember = Array.isArray(rows) && rows.length > 0;

            if (isMember) {
                this.membershipCache.set(cacheKey, now);
                return null;
            }

            return this.error(
                `Forbidden: user ${userId} is not a member of project ${environmentId}`,
                403,
                { environmentId, userId, type: 'PROJECT_MEMBERSHIP_REQUIRED' },
            );
        } catch (err) {
            // Control-plane lookup failure — log and fail open rather than
            // break the request. Tightening this is deferred to Phase 4.
            console.debug('[HttpDispatcher] Membership check failed:', err);
            return null;
        }
    }

    /**
     * Generates the discovery JSON response for the API root.
     *
     * Uses the same async `resolveService()` fallback chain that request
     * handlers use, so the reported service status is always consistent
     * with the actual runtime availability.
     */
    async getDiscoveryInfo(prefix: string) {
        // Resolve all services through the same async fallback chain
        // that request handlers (handleI18n, handleAuth, …) use.
        const [
            authSvc, graphqlSvc, searchSvc, realtimeSvc, filesSvc,
            analyticsSvc, workflowSvc, aiSvc, notificationSvc, i18nSvc,
            uiSvc, automationSvc, cacheSvc, queueSvc, jobSvc,
        ] = await Promise.all([
            this.resolveService(CoreServiceName.enum.auth),
            this.resolveService(CoreServiceName.enum.graphql),
            this.resolveService(CoreServiceName.enum.search),
            this.resolveService(CoreServiceName.enum.realtime),
            this.resolveService(CoreServiceName.enum['file-storage']),
            this.resolveService(CoreServiceName.enum.analytics),
            this.resolveService(CoreServiceName.enum.workflow),
            this.resolveService(CoreServiceName.enum.ai),
            this.resolveService(CoreServiceName.enum.notification),
            this.resolveService(CoreServiceName.enum.i18n),
            this.resolveService(CoreServiceName.enum.ui),
            this.resolveService(CoreServiceName.enum.automation),
            this.resolveService(CoreServiceName.enum.cache),
            this.resolveService(CoreServiceName.enum.queue),
            this.resolveService(CoreServiceName.enum.job),
        ]);

        const hasAuth         = !!authSvc;
        const hasGraphQL      = !!(graphqlSvc || this.kernel.graphql);
        const hasSearch       = !!searchSvc;
        const hasFiles        = !!filesSvc;
        const hasAnalytics    = !!analyticsSvc;
        const hasWorkflow     = !!workflowSvc;
        const hasAi           = !!aiSvc;
        const hasNotification = !!notificationSvc;
        const hasI18n         = !!i18nSvc;
        const hasUi           = !!uiSvc;
        const hasAutomation   = !!automationSvc;
        const hasCache        = !!cacheSvc;
        const hasQueue        = !!queueSvc;
        const hasJob          = !!jobSvc;

        // Routes are only exposed when a plugin provides the service
        const routes = {
                data:          `${prefix}/data`,
                metadata:      `${prefix}/meta`,
                packages:      `${prefix}/packages`,
                auth:          hasAuth ? `${prefix}/auth` : undefined,
                ui:            hasUi ? `${prefix}/ui` : undefined,
                graphql:       hasGraphQL ? `${prefix}/graphql` : undefined,
                storage:       hasFiles ? `${prefix}/storage` : undefined,
                analytics:     hasAnalytics ? `${prefix}/analytics` : undefined,
                automation:    hasAutomation ? `${prefix}/automation` : undefined,
                workflow:      hasWorkflow ? `${prefix}/workflow` : undefined,
                // Never advertised (ADR-0076 D12, #2462): service-realtime is an
                // in-process pub/sub bus — the dispatcher has no /realtime branch
                // and no plugin mounts one, so an advertised route would 404.
                // Re-add only when a real HTTP/WS surface exists (and then it must
                // pass through the shouldDenyAnonymous gate, #2567).
                realtime:      undefined,
                notifications: hasNotification ? `${prefix}/notifications` : undefined,
                ai:            hasAi ? `${prefix}/ai` : undefined,
                i18n:          hasI18n ? `${prefix}/i18n` : undefined,
                // MCP (Streamable HTTP) is a default-on core capability —
                // advertised unless OS_MCP_SERVER_ENABLED=false opts the env
                // out. The objectui Integrations page reads this.
                //
                // `declared === enforced` here is guaranteed by a LOCKSTEP, not
                // by service-presence gating like the routes above (#3369 /
                // #2698): `os serve` auto-loads plugin-mcp from the SAME
                // `isMcpServerEnabled()` flag that gates this advertisement, so
                // whenever `/mcp` is advertised the handler is mounted (a key /
                // token yields 401, never a 404/501). Kept flag-based on purpose
                // — `@objectstack/rest` advertises `mcp` from the identical
                // single source (rest-server.ts), so the two discovery producers
                // stay symmetric. The route-parity gate asserts the lockstep
                // holds (advertised ⇒ reachable, never 501).
                mcp:           HttpDispatcher.isMcpEnabled() ? `${prefix}/mcp` : undefined,
        };

        // Build per-service status map
        // handlerReady: true means the dispatcher has a real, bound handler for this route.
        // handlerReady: false means the route is present in the discovery table but may not
        // yet have a concrete implementation or may be served by a stub.
        //
        // Honest capabilities (ADR-0076 D12, #2462): a registered service that
        // self-identifies as a stub / dev fake / degraded fallback (via the
        // `__serviceInfo` marker or plugin-dev's legacy `_dev: true`) is
        // reported with its declared status — never as `available` — so
        // consumers (AI agents, the console) don't mistake a fake capability
        // for a real one.
        const svcAvailable = (route?: string, provider?: string, svc?: unknown) => {
            const self = svc ? readServiceSelfInfo(svc) : undefined;
            if (self) {
                return {
                    enabled: true, status: self.status, handlerReady: self.handlerReady ?? false,
                    route, provider, message: self.message,
                };
            }
            return { enabled: true, status: 'available' as const, handlerReady: true, route, provider };
        };
        const svcUnavailable = (name: string) => ({
            enabled: false, status: 'unavailable' as const, handlerReady: false,
            message: `Install a ${name} plugin to enable`,
        });

        // Self-description of the registered realtime service, if any (D12).
        const realtimeSelf = realtimeSvc ? readServiceSelfInfo(realtimeSvc) : undefined;

        // Derive locale info from actual i18n service when available
        let locale = { default: 'en', supported: ['en'], timezone: 'UTC' };
        if (hasI18n && i18nSvc) {
            const defaultLocale = typeof i18nSvc.getDefaultLocale === 'function'
                ? i18nSvc.getDefaultLocale() : 'en';
            const locales = typeof i18nSvc.getLocales === 'function'
                ? i18nSvc.getLocales() : [];
            locale = {
                default: defaultLocale,
                supported: locales.length > 0 ? locales : [defaultLocale],
                timezone: 'UTC',
            };
        }

        return {
            name: 'ObjectOS',
            version: '1.0.0',
            environment: getEnv('NODE_ENV', 'development'),
            routes,
            endpoints: routes, // Alias for backward compatibility with some clients
            features: {
                graphql: hasGraphQL,
                search: hasSearch,
                // No WS/HTTP realtime surface is mounted anywhere — a mere
                // in-process realtime service must not advertise websockets
                // (ADR-0076 D12, #2462).
                websockets: false,
                files: hasFiles,
                analytics: hasAnalytics,
                ai: hasAi,
                workflow: hasWorkflow,
                notifications: hasNotification,
                i18n: hasI18n,
            },
            services: {
                // Kernel-provided (always available via protocol implementation)
                metadata:       { enabled: true, status: 'degraded' as const, handlerReady: true, route: routes.metadata, provider: 'kernel', message: 'In-memory registry; DB persistence pending' },
                data:           svcAvailable(routes.data, 'kernel'),
                // Plugin-provided — only available when a plugin registers the service
                auth:           hasAuth ? svcAvailable(routes.auth, undefined, authSvc) : svcUnavailable('auth'),
                automation:     hasAutomation ? svcAvailable(routes.automation, undefined, automationSvc) : svcUnavailable('automation'),
                analytics:      hasAnalytics ? svcAvailable(routes.analytics, undefined, analyticsSvc) : svcUnavailable('analytics'),
                cache:          hasCache ? svcAvailable(undefined, undefined, cacheSvc) : svcUnavailable('cache'),
                queue:          hasQueue ? svcAvailable(undefined, undefined, queueSvc) : svcUnavailable('queue'),
                job:            hasJob ? svcAvailable(undefined, undefined, jobSvc) : svcUnavailable('job'),
                ui:             hasUi ? svcAvailable(routes.ui, undefined, uiSvc) : svcUnavailable('ui'),
                workflow:       hasWorkflow ? svcAvailable(routes.workflow, undefined, workflowSvc) : svcUnavailable('workflow'),
                // Honest entry (ADR-0076 D12, #2462): the registered realtime
                // service is an in-process event bus with NO mounted HTTP/WS
                // surface — report it degraded with handlerReady:false (or as
                // the stub it declares itself to be), never as an available
                // HTTP capability with a route that would 404.
                realtime:       realtimeSvc ? {
                                    enabled: true,
                                    status: realtimeSelf?.status ?? ('degraded' as const),
                                    handlerReady: false,
                                    message: realtimeSelf?.message
                                        ?? 'In-process event bus only — no HTTP/WS realtime surface is mounted',
                                } : svcUnavailable('realtime'),
                notification:   hasNotification ? svcAvailable(routes.notifications, undefined, notificationSvc) : svcUnavailable('notification'),
                ai:             hasAi ? svcAvailable(routes.ai, undefined, aiSvc) : svcUnavailable('ai'),
                i18n:           hasI18n ? svcAvailable(routes.i18n, undefined, i18nSvc) : svcUnavailable('i18n'),
                graphql:        hasGraphQL ? svcAvailable(routes.graphql, undefined, graphqlSvc) : svcUnavailable('graphql'),
                'file-storage': hasFiles ? svcAvailable(routes.storage, undefined, filesSvc) : svcUnavailable('file-storage'),
                search:         hasSearch ? svcAvailable(undefined, undefined, searchSvc) : svcUnavailable('search'),
            },
            locale,
        };
    }

    /**
     * Handles GraphQL requests
     */
    async handleGraphQL(body: { query: string; variables?: any }, context: HttpProtocolContext) {
        if (!body || !body.query) {
             throw { statusCode: 400, message: 'Missing query in request body' };
        }

        // Anonymous-deny gate — the same `requireAuth` posture the REST `/data`
        // and `/meta` surfaces enforce. GraphQL reaches ObjectQL through
        // `kernel.graphql`, whose security middleware falls OPEN for an
        // anonymous context (no userId/roles → next()), so without this gate an
        // anonymous query could read exactly the object data the sibling
        // `/data/*` 401 denies (#2567). Mirrors {@link handleMetadata}: no-op
        // when `requireAuth` is off (demo / single-tenant), an authenticated or
        // system caller passes exactly as on `/data`.
        //
        // The dispatcher-plugin's direct `/graphql` route calls us WITHOUT
        // resolving identity first (unlike `dispatch()`, which populates
        // `context.executionContext`), so resolve it here when absent —
        // REGARDLESS of `requireAuth`: the resolved identity is also what we
        // thread to the engine below (#2992), and an authenticated caller on a
        // `requireAuth: false` deployment must still run under their own
        // authority, not context-less.
        let ec: any = context.executionContext;
        if (!ec) {
            ec = await this.resolveRequestExecutionContext(context);
            if (ec) context.executionContext = ec;
        }
        // Body-routed seam: no meaningful request path, so pass none — the
        // shared decision then denies anonymous unconditionally (see the
        // `undefined`-path trap guard in `shouldDenyAnonymous`).
        if (shouldDenyAnonymous({ requireAuth: this.requireAuth, userId: ec?.userId, isSystem: ec?.isSystem })) {
            throw {
                statusCode: ANONYMOUS_DENY_STATUS,
                message: ANONYMOUS_DENY_MESSAGE,
                code: ANONYMOUS_DENY_CODE,
            };
        }

        if (typeof this.kernel.graphql !== 'function') {
            throw { statusCode: 501, message: 'GraphQL service not available' };
        }

        // ADR-0096 D1 / #2992 — thread the caller's identity to the engine.
        // `kernel.graphql` is still unassigned everywhere (this call 501s
        // above), but the moment a real engine lands it resolves objects
        // through ObjectQL, whose security middleware falls OPEN on a missing
        // principal — so the entry point must already carry the caller as
        // `options.context` (the same key the REST `callData` path threads).
        // An implementation MUST forward it to every data-engine call.
        return this.kernel.graphql(body.query, body.variables, {
            request: context.request,
            context: ec,
        });
    }

    /**
     * Resolve the RBAC/RLS execution context for a request that did NOT flow
     * through {@link dispatch} (which resolves and caches it on
     * `context.executionContext`). The dispatcher-plugin's direct `/graphql`
     * route is the current caller. Mirrors the identity resolution `dispatch()`
     * performs so an anonymous-deny gate can tell an authenticated caller from
     * an anonymous one, and so the caller's identity can be THREADED to the
     * engine (#2992 / ADR-0096 D1) instead of dropped. Best-effort: returns
     * `undefined` on failure (treated as anonymous, i.e. denied under
     * `requireAuth`).
     */
    private async resolveRequestExecutionContext(
        context: HttpProtocolContext,
    ): Promise<ExecutionContext | undefined> {
        try {
            return await this.timedResolveExecutionContext({
                getService: (n: string) => this.resolveService(n, context.environmentId),
                getQl: async () => {
                    const k: any = this.kernel;
                    if (k && typeof k.getServiceAsync === 'function') {
                        const ql = await k.getServiceAsync('objectql').catch(() => undefined);
                        if (ql && (ql.registry || typeof ql.find === 'function')) return ql;
                    }
                    return this.getObjectQLService(context.environmentId);
                },
                request: context.request,
                // OAuth access tokens are honoured only on the MCP surface
                // (#2698); GraphQL enforces no per-scope tool gating.
                acceptOAuthAccessToken: false,
            });
        } catch {
            return undefined;
        }
    }

    /**
     * Handles Auth requests
     * path: sub-path after /auth/
     */
    async handleAuth(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        // 1. Try generic Auth Service
        const authService = await this.getService(CoreServiceName.enum.auth);
        if (authService && typeof authService.handler === 'function') {
            const response = await authService.handler(context.request, context.response);
            return { handled: true, result: response };
        }

        // 2. Mock fallback for MSW/test environments when no auth service is registered
        const normalizedPath = path.replace(/^\/+/, '');
        return this.mockAuthFallback(normalizedPath, method, body);
    }

    /**
     * Provides mock auth responses for core better-auth endpoints when
     * AuthPlugin is not loaded (e.g. MSW/browser-only environments).
     * This ensures registration/sign-in flows do not 404 in mock mode.
     */
    private mockAuthFallback(path: string, method: string, body: any): HttpDispatcherResult {
        const m = method.toUpperCase();
        const MOCK_SESSION_EXPIRY_MS = 86_400_000; // 24 hours

        // POST sign-up/email
        if ((path === 'sign-up/email' || path === 'register') && m === 'POST') {
            const id = `mock_${randomUUID()}`;
            return {
                handled: true,
                response: {
                    status: 200,
                    body: {
                        user: { id, name: body?.name || 'Mock User', email: body?.email || 'mock@test.local', emailVerified: false, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() },
                        session: { id: `session_${id}`, userId: id, token: `mock_token_${id}`, expiresAt: new Date(Date.now() + MOCK_SESSION_EXPIRY_MS).toISOString() },
                    },
                },
            };
        }

        // POST sign-in/email or login
        if ((path === 'sign-in/email' || path === 'login') && m === 'POST') {
            const id = `mock_${randomUUID()}`;
            return {
                handled: true,
                response: {
                    status: 200,
                    body: {
                        user: { id, name: 'Mock User', email: body?.email || 'mock@test.local', emailVerified: true, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() },
                        session: { id: `session_${id}`, userId: id, token: `mock_token_${id}`, expiresAt: new Date(Date.now() + MOCK_SESSION_EXPIRY_MS).toISOString() },
                    },
                },
            };
        }

        // GET get-session
        if (path === 'get-session' && m === 'GET') {
            return {
                handled: true,
                response: { status: 200, body: { session: null, user: null } },
            };
        }

        // POST sign-out
        if (path === 'sign-out' && m === 'POST') {
            return {
                handled: true,
                response: { status: 200, body: { success: true } },
            };
        }

        return { handled: false };
    }

    /**
     * Handles Metadata requests
     * Standard: /metadata/:type/:name
     * Fallback for backward compat: /metadata (all objects), /metadata/:objectName (get object)
     */
    async handleMetadata(path: string, _context: HttpProtocolContext, method?: string, body?: any, query?: any): Promise<HttpDispatcherResult> {
        // Defense-in-depth: the metadata catch-all must honour the same
        // `requireAuth` gate as the REST `/meta` routes (which serve `/meta` on
        // the cloud runtime). Object/field schemas — SYSTEM-object schemas on a
        // tenant-less host — must not be readable by anonymous callers when the
        // deployment requires auth. No-op when `requireAuth` is off.
        {
            const ec: any = _context.executionContext;
            if (shouldDenyAnonymous({ requireAuth: this.requireAuth, userId: ec?.userId, isSystem: ec?.isSystem })) {
                return {
                    handled: true,
                    response: this.error(ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, { code: ANONYMOUS_DENY_CODE }),
                };
            }
        }
        const parts = path.replace(/^\/+/, '').split('/').filter(Boolean);

        // GET /metadata/types
        if (parts[0] === 'types') {
            // PRIORITY 1: Try protocol service — it returns BOTH legacy
            // `types: string[]` AND the richer `entries` array (with
            // JSON Schemas, allowOrgOverride flags, domain, etc) needed by
            // the metadata admin UI. It internally also merges
            // MetadataService runtime types, so this path is strictly richer.
            const protocol = await this.resolveService('protocol');
            if (protocol && typeof protocol.getMetaTypes === 'function') {
                try {
                    const result = await protocol.getMetaTypes({});
                    return { handled: true, response: this.success(result) };
                } catch (e: any) {
                    console.warn('[HttpDispatcher] protocol.getMetaTypes() failed:', e?.message);
                }
            }
            // PRIORITY 2: MetadataService fallback (types only, no entries)
            const metadataService = await this.resolveService('metadata', _context.environmentId);
            if (metadataService && typeof (metadataService as any).getRegisteredTypes === 'function') {
                try {
                    const types = await (metadataService as any).getRegisteredTypes();
                    return { handled: true, response: this.success({ types }) };
                } catch (e: any) {
                    console.warn('[HttpDispatcher] MetadataService.getRegisteredTypes() failed:', e.message);
                }
            }
            // Last resort: hardcoded defaults
            return { handled: true, response: this.success({ types: ['object', 'app', 'plugin'] }) };
        }

        // GET /metadata/objects/:name/state/:field?from=:state
        // ADR-0020 D3.3 introspection: the legal next states declared by the
        // object's `state_machine` validation rule for `:field`. Lets UIs /
        // AI authors ask "from here, where can this record go?" instead of
        // hard-coding the transition table. Returns `next: null` when no FSM
        // governs the field, `next: []` for a declared dead-end state.
        if (parts.length === 4 && (parts[0] === 'objects' || parts[0] === 'object') && parts[2] === 'state' && (!method || method === 'GET')) {
            const name = parts[1];
            const field = parts[3];
            const from = query?.from !== undefined ? String(query.from) : undefined;
            const qlService = await this.getObjectQLService();
            const schema = qlService?.registry?.getObject(name);
            if (!schema) return { handled: true, response: this.error('Object not found', 404) };
            // Dynamic import (matches the runtime convention for @objectstack/objectql)
            // so the dispatcher module graph doesn't statically pull in the objectql barrel.
            const { legalNextStates } = await import('@objectstack/objectql');
            const next = from === undefined ? null : legalNextStates(schema, field, from);
            return { handled: true, response: this.success({ object: name, field, from: from ?? null, next }) };
        }

        // GET /metadata/:type/:name(/:subname...)/published → get published version
        // Supports compound names like `lead/views/all_leads/published`.
        if (parts.length >= 3 && parts[parts.length - 1] === 'published' && (!method || method === 'GET')) {
            const type = parts[0];
            const name = parts.slice(1, -1).join('/');
            const metadataService = await this.getService(CoreServiceName.enum.metadata);
            if (metadataService && typeof (metadataService as any).getPublished === 'function') {
                const data = await (metadataService as any).getPublished(type, name);
                if (data === undefined) return { handled: true, response: this.error('Not found', 404) };
                return { handled: true, response: this.success(data) };
            }
            // Fallback — try MetadataService via resolveService
            const metaSvc = await this.resolveService('metadata', _context.environmentId);
            if (metaSvc && typeof (metaSvc as any).getPublished === 'function') {
                try {
                    const fallbackData = await (metaSvc as any).getPublished(type, name);
                    if (fallbackData !== undefined) return { handled: true, response: this.success(fallbackData) };
                } catch { /* fall through */ }
            }
            return { handled: true, response: this.error('Not found', 404) };
        }

        // /metadata/:type/:name where :name may itself contain slashes
        // (e.g. /metadata/lead/views/all_leads → type='lead', name='views/all_leads').
        // Compound names are how the client expresses sub-resources of a type
        // (a view of an object, a flow under an automation, etc.) and the
        // metadata service treats the full string as the lookup key.
        if (parts.length >= 2) {
            const type = parts[0];
            const name = parts.slice(1).join('/');
            // Extract optional package filter from query string
            const packageId = query?.package || undefined;

            // PUT /metadata/:type/:name (Save)
            if (method === 'PUT' && body) {
                // Try to get the protocol service directly
                const protocol = await this.resolveService('protocol');

                if (protocol && typeof protocol.saveMetaItem === 'function') {
                    try {
                        const organizationId = await this.resolveActiveOrganizationId(_context);
                        const result = await protocol.saveMetaItem({ type, name, item: body, organizationId, ...(packageId ? { packageId } : {}) });
                        return { handled: true, response: this.success(result) };
                    } catch (e: any) {
                        // Preserve the 422 + structured spec-validation `issues` so
                        // the Studio can point at the offending field, not just a
                        // generic banner (the old path hardcoded 400 + dropped them).
                        return { handled: true, response: this.errorFromThrown(e, 400) };
                    }
                }

                // Fallback: try MetadataService directly
                const metaSvc = await this.resolveService('metadata', _context.environmentId);
                if (metaSvc && typeof (metaSvc as any).saveItem === 'function') {
                    try {
                        const data = await (metaSvc as any).saveItem(type, name, body);
                        return { handled: true, response: this.success(data) };
                    } catch (e: any) {
                        return { handled: true, response: this.error(e.message || 'Save not supported', 501) };
                    }
                }
                return { handled: true, response: this.error('Save not supported', 501) };
            }

            try {
                // Try specific calls based on type
                if (type === 'objects' || type === 'object') {
                    // Check whether the kernel is project-scoped. When it is,
                    // the process-wide SchemaRegistry is unsafe to query
                    // directly — it would return objects that other projects
                    // wrote in this same process. Route through the Protocol
                    // service (which filters sys_metadata by environment_id) in that
                    // case, and fall back to the registry only for the
                    // unscoped (single-kernel / control-plane) path.
                    const protocol = await this.resolveService('protocol') as any;
                    const scopedEnv = typeof protocol?.getProjectId === 'function'
                        ? protocol.getProjectId()
                        : protocol?.environmentId;
                    const scoped = scopedEnv !== undefined;

                    if (scoped && typeof protocol.getMetaItem === 'function') {
                        try {
                            const organizationId = await this.resolveActiveOrganizationId(_context);
                            const data = await protocol.getMetaItem({ type: 'object', name, organizationId });
                            // Protocol returns `{ type, name, item }` — only
                            // treat the lookup as a hit when item is present.
                            if (data && (data.item ?? data)) {
                                return { handled: true, response: this.success(data) };
                            }
                        } catch { /* fall through to registry / 404 */ }
                    }

                    const qlService = await this.getObjectQLService();
                    if (qlService?.registry) {
                        const data = qlService.registry.getObject(name);
                        if (data) return { handled: true, response: this.success(data) };
                    }

                    // Last-ditch protocol attempt for unscoped kernels whose
                    // registry missed (e.g. object persisted to DB but not
                    // yet hydrated). Skip when we already tried above.
                    if (!scoped && protocol && typeof protocol.getMetaItem === 'function') {
                        try {
                            const organizationId = await this.resolveActiveOrganizationId(_context);
                            const data = await protocol.getMetaItem({ type: 'object', name, organizationId });
                            if (data && (data.item ?? data)) {
                                return { handled: true, response: this.success(data) };
                            }
                        } catch { /* fall through to 404 */ }
                    }
                    return { handled: true, response: this.error('Not found', 404) };
                }

                // Normalize plural URL paths to singular registry type names
                const singularType = pluralToSingular(type);

                // Try Protocol Service First (Preferred)
                const protocol = await this.resolveService('protocol');
                if (protocol && typeof protocol.getMetaItem === 'function') {
                     try {
                        const organizationId = await this.resolveActiveOrganizationId(_context);
                        // ADR-0033 draft-overlay preview: `?preview=draft` makes the
                        // detail read prefer a pending draft (falling back to active).
                        // Admin gating is layered on top in a follow-up (step 2).
                        const previewDrafts = query?.preview === 'draft';
                        const data = await protocol.getMetaItem({ type: singularType, name, packageId, organizationId, previewDrafts });
                        return { handled: true, response: this.success(data) };
                     } catch (e: any) {
                        // Protocol might throw if not found or not supported
                     }
                }

                // Try MetadataService for runtime-registered types
                const metaSvc = await this.resolveService('metadata', _context.environmentId);
                if (metaSvc && typeof (metaSvc as any).getItem === 'function') {
                    try {
                        // ADR-0048 — thread `?package=` so single-item resolution is
                        // package-scoped (prefer-local), matching list resolution.
                        const data = await (metaSvc as any).getItem(singularType, name, packageId);
                        if (data) return { handled: true, response: this.success(data) };
                    } catch { /* not found */ }
                }
                return { handled: true, response: this.error('Not found', 404) };
            } catch (e: any) {
                // Fallback: treat first part as object name if only 1 part (handled below)
                // But here we are deep in 2 parts. Must be an error.
                return { handled: true, response: this.error(e.message, 404) };
            }
        }
        
        // GET /metadata/_drafts?packageId=&type=  (ADR-0033 pending-changes list)
        // Surfaces draft-state metadata the active-only `getMetaItems` list hides,
        // so the console can show what an AI authored but nobody published yet.
        // `_drafts` is intercepted before the generic `:type` handler below so it
        // is never mistaken for a metadata type name.
        if (parts.length === 1 && parts[0] === '_drafts' && (!method || method.toUpperCase() === 'GET')) {
            const protocol = await this.resolveService('protocol');
            if (protocol && typeof protocol.listDrafts === 'function') {
                try {
                    const organizationId = await this.resolveActiveOrganizationId(_context);
                    const data = await protocol.listDrafts({
                        packageId: query?.packageId || undefined,
                        type: query?.type || undefined,
                        organizationId,
                    });
                    return { handled: true, response: this.success(data) };
                } catch (e: any) {
                    return { handled: true, response: this.error(e.message, 500) };
                }
            }
            return { handled: true, response: this.error('Draft listing not supported', 501) };
        }

        // GET /metadata/:type (List items of type) OR /metadata/:objectName (Legacy)
        if (parts.length === 1) {
            const typeOrName = parts[0];
            // Extract optional package filter from query string
            const packageId = query?.package || undefined;

            // Try protocol service first for any type
            const protocol = await this.resolveService('protocol');
            if (protocol && typeof protocol.getMetaItems === 'function') {
                try {
                    const organizationId = await this.resolveActiveOrganizationId(_context);
                    // ADR-0033 draft-overlay preview: `?preview=draft` overlays
                    // pending drafts on the active list so an (admin) reviewer can
                    // render the console off drafts before publishing.
                    const previewDrafts = query?.preview === 'draft';
                    const data = await protocol.getMetaItems({ type: typeOrName, packageId, organizationId, previewDrafts });
                    // Return any valid response from protocol (including empty items arrays)
                    if (data && (data.items !== undefined || Array.isArray(data))) {
                        return { handled: true, response: this.success(this.slimDocList(typeOrName, data, query)) };
                    }
                } catch {
                    // Protocol doesn't know this type, fall through
                }
            }

            // Try MetadataService directly for runtime-registered metadata (agents, tools, etc.)
            const metadataService = await this.getService(CoreServiceName.enum.metadata);
            if (metadataService && typeof (metadataService as any).list === 'function') {
                try {
                    let items = await (metadataService as any).list(typeOrName);
                    // Respect package filter: MetadataService.list() returns ALL items,
                    // so filter by _packageId when a specific package is requested.
                    if (packageId && items && items.length > 0) {
                        items = items.filter((item: any) => item?._packageId === packageId);
                    }
                    if (items && items.length > 0) {
                        return { handled: true, response: this.success({ type: typeOrName, items: this.slimDocList(typeOrName, items, query) }) };
                    }
                } catch (e: any) {
                    // MetadataService doesn't know this type or failed, continue to other fallbacks
                    // Sanitize typeOrName to prevent log injection (CodeQL warning)
                    const sanitizedType = String(typeOrName).replace(/[\r\n\t]/g, '');
                    console.debug(`[HttpDispatcher] MetadataService.list() failed for type:`, sanitizedType, 'error:', e.message);
                }
            }

            // Try ObjectQL registry directly for object/type lookups
            const qlService = await this.getObjectQLService();
            if (qlService?.registry) {
                if (typeOrName === 'objects') {
                    const objs = qlService.registry.getAllObjects(packageId);
                    return { handled: true, response: this.success({ type: 'object', items: objs }) };
                }
                // Try listing items of the given type
                const items = qlService.registry.listItems?.(typeOrName, packageId);
                if (items && items.length > 0) {
                    return { handled: true, response: this.success({ type: typeOrName, items }) };
                }
                // Legacy: treat as object name
                const obj = qlService.registry.getObject(typeOrName);
                if (obj) return { handled: true, response: this.success(obj) };
            }
            return { handled: true, response: this.error('Not found', 404) };
        }

        // GET /metadata — return available metadata types
        if (parts.length === 0) {
            // Prefer protocol service for the rich `entries` array (with
            // JSON Schemas etc); fall back to MetadataService types-only.
            const protocol = await this.resolveService('protocol');
            if (protocol && typeof protocol.getMetaTypes === 'function') {
                try {
                    const result = await protocol.getMetaTypes({});
                    return { handled: true, response: this.success(result) };
                } catch { /* fall through */ }
            }
            const metadataService = await this.resolveService('metadata', _context.environmentId);
            if (metadataService && typeof (metadataService as any).getRegisteredTypes === 'function') {
                try {
                    const types = await (metadataService as any).getRegisteredTypes();
                    return { handled: true, response: this.success({ types }) };
                } catch { /* fall through */ }
            }
            return { handled: true, response: this.success({ types: ['object', 'app', 'plugin'] }) };
        }
        
        return { handled: false };
    }

    /**
     * Handles Data requests
     * path: sub-path after /data/ (e.g. "contacts", "contacts/123", "contacts/query")
     */
    async handleData(path: string, method: string, body: any, query: any, _context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        const parts = path.replace(/^\/+/, '').split('/');
        const objectName = parts[0];

        if (!objectName) {
            return { handled: true, response: this.error('Object name required', 400) };
        }

        // Check if environment is resolved for data-plane requests. A
        // registered KernelResolver marks this host as multi-tenant (ADR-0006
        // Phase 5 — previously signalled by the env-registry service): a
        // data-plane request that the resolver did not attach to an
        // environment must not silently fall through to the host kernel.
        if (!_context.dataDriver && this.kernelResolver) {
            return {
                handled: true,
                response: this.error('Project not resolved. Please specify X-Environment-Id header or ensure hostname maps to a project.', 428)
            };
        }

        const m = method.toUpperCase();

        // 1. Custom Actions (query, batch)
        if (parts.length > 1) {
            const action = parts[1];

            // POST /data/:object/query
            if (action === 'query' && m === 'POST') {
                // Spec: returns FindDataResponse = { object, records, total?, hasMore? }
                const result = await this.callData('query', { object: objectName, ...body }, _context.dataDriver, _context.environmentId, _context.executionContext);
                return { handled: true, response: this.success(result) };
            }

            // GET /data/:object/:id
            if (parts.length === 2 && m === 'GET') {
                const id = parts[1];
                // Spec: Only select/expand are allowlisted query params for GET by ID.
                // All other query parameters are discarded to prevent parameter pollution.
                const { select, expand } = query || {};
                const allowedParams: Record<string, unknown> = {};
                if (select != null) allowedParams.select = select;
                if (expand != null) allowedParams.expand = expand;
                // Spec: returns GetDataResponse = { object, id, record }
                const result = await this.callData('get', { object: objectName, id, ...allowedParams }, _context.dataDriver, _context.environmentId, _context.executionContext);
                return { handled: true, response: this.success(result) };
            }

            // PATCH /data/:object/:id
            if (parts.length === 2 && m === 'PATCH') {
                const id = parts[1];
                // Spec: returns UpdateDataResponse = { object, id, record }
                const result = await this.callData('update', { object: objectName, id, data: body }, _context.dataDriver, _context.environmentId, _context.executionContext);
                return { handled: true, response: this.success(result) };
            }

            // DELETE /data/:object/:id
            if (parts.length === 2 && m === 'DELETE') {
                const id = parts[1];
                // Spec: returns DeleteDataResponse = { object, id, deleted }
                const result = await this.callData('delete', { object: objectName, id }, _context.dataDriver, _context.environmentId, _context.executionContext);
                return { handled: true, response: this.success(result) };
            }
        } else {
            // GET /data/:object (List)
            if (m === 'GET') {
                // ── Normalize HTTP transport params → Spec canonical (QueryAST) ──
                // HTTP GET query params use transport-level names (filter, sort, top,
                // skip, select, expand) which are normalized here to canonical
                // QueryAST field names (where, orderBy, limit, offset, fields,
                // expand) before forwarding to the data service layer.
                // The protocol.ts findData() method performs a deeper normalization
                // pass, but pre-normalizing here ensures the data service always receives
                // Spec-canonical keys.
                const normalized: Record<string, unknown> = { ...query };

                // filter/filters → where
                // Note: `filter` is the canonical HTTP *transport* parameter name
                // (see HttpFindQueryParamsSchema). It is normalized here to the
                // canonical *QueryAST* field name `where` before data dispatch.
                // `filters` (plural) is a deprecated alias for `filter`.
                if (normalized.filter != null || normalized.filters != null) {
                    normalized.where = normalized.where ?? normalized.filter ?? normalized.filters;
                    delete normalized.filter;
                    delete normalized.filters;
                }
                // select → fields
                if (normalized.select != null && normalized.fields == null) {
                    normalized.fields = normalized.select;
                    delete normalized.select;
                }
                // sort → orderBy
                if (normalized.sort != null && normalized.orderBy == null) {
                    normalized.orderBy = normalized.sort;
                    delete normalized.sort;
                }
                // top → limit
                if (normalized.top != null && normalized.limit == null) {
                    normalized.limit = normalized.top;
                    delete normalized.top;
                }
                // skip → offset
                if (normalized.skip != null && normalized.offset == null) {
                    normalized.offset = normalized.skip;
                    delete normalized.skip;
                }

                // Spec: returns FindDataResponse = { object, records, total?, hasMore? }
                const result = await this.callData('query', { object: objectName, query: normalized }, _context.dataDriver, _context.environmentId, _context.executionContext);
                return { handled: true, response: this.success(result) };
            }

            // POST /data/:object (Create)
            if (m === 'POST') {
                // Spec: returns CreateDataResponse = { object, id, record }
                const result = await this.callData('create', { object: objectName, data: body }, _context.dataDriver, _context.environmentId, _context.executionContext);
                const res = this.success(result);
                res.status = 201;
                return { handled: true, response: res };
            }
        }

        return { handled: false };
    }

    /**
     * Handles Analytics requests
     * path: sub-path after /analytics/
     */
    async handleAnalytics(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        const analyticsService = await this.getService(CoreServiceName.enum.analytics);
        if (!analyticsService) return { handled: false }; // 404 handled by caller if unhandled

        const m = method.toUpperCase();
        const subPath = path.replace(/^\/+/, '');

        // POST /analytics/query
        if (subPath === 'query' && m === 'POST') {
            // [#2852] Pass the request's execution context so the analytics
            // service scopes each object by its per-object read filter (tenant +
            // RLS). Without it, `getReadScope(object, undefined)` returned no
            // filter and the query ran UNSCOPED — an authenticated caller saw
            // rows RLS would otherwise hide.
            const result = await analyticsService.query(body, context?.executionContext);
            return { handled: true, response: this.success(result) };
        }

        // GET /analytics/meta
        if (subPath === 'meta' && m === 'GET') {
            const result = await analyticsService.getMeta();
             return { handled: true, response: this.success(result) };
        }

        // POST /analytics/sql (Dry-run or debug)
        if (subPath === 'sql' && m === 'POST') {
             // [#2852] Scope the generated SQL to the caller too, so a preview
             // reflects the same per-object read filter the real query applies.
             const result = await analyticsService.generateSql(body, context?.executionContext);
             return { handled: true, response: this.success(result) };
        }

        return { handled: false };
    }

    /**
     * Handles in-app notification requests (ADR-0030) — the
     * `/api/v1/notifications` surface backed by the messaging service's inbox
     * read API. Reads the L5 `sys_inbox_message` + `sys_notification_receipt`
     * join; mark-read upserts the receipt keyed `(notification_id, user_id,
     * channel:'inbox')`. The routes are `auth: true`, so an authenticated user
     * is required.
     *
     * Routes (path is the sub-path after `/notifications`):
     *   GET  ''          → listInbox    (query: read, type, limit)
     *   POST /read       → markRead     (body: { ids: string[] })
     *   POST /read/all   → markAllRead
     */
    async handleNotification(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        const service = await this.resolveService(CoreServiceName.enum.notification, context.environmentId) as any;
        if (!service || typeof service.listInbox !== 'function') return { handled: false };

        const userId: string | undefined = context.executionContext?.userId;
        if (!userId) {
            return { handled: true, response: this.error('Authentication required', 401) };
        }

        const m = method.toUpperCase();
        const subPath = path.replace(/^\/+/, '').replace(/\/+$/, '');

        // GET /notifications — list the user's inbox joined with read-state.
        if (subPath === '' && m === 'GET') {
            const read = query?.read === undefined ? undefined : String(query.read) === 'true';
            const limit = query?.limit ? Number(query.limit) : undefined;
            const type = query?.type ? String(query.type) : undefined;
            const result = await service.listInbox(userId, { read, type, limit });
            return { handled: true, response: this.success(result) };
        }

        // POST /notifications/read — mark specific notifications read.
        if (subPath === 'read' && m === 'POST') {
            const ids: string[] = Array.isArray(body?.ids) ? body.ids.map((x: unknown) => String(x)) : [];
            const result = await service.markRead(userId, ids);
            return { handled: true, response: this.success(result) };
        }

        // POST /notifications/read/all — mark all of the user's inbox read.
        if (subPath === 'read/all' && m === 'POST') {
            const result = await service.markAllRead(userId);
            return { handled: true, response: this.success(result) };
        }

        return { handled: false };
    }

    /**
     * Handle the security admin surface (`/security/...`) — ADR-0090 D5/D9
     * suggested audience bindings. A package's `isDefault: true` permission
     * set is an install-time SUGGESTION to bind it to the `everyone` position;
     * these routes let an admin see and resolve those suggestions. The
     * `security` service does the real gating (tenant-admin pre-check, and the
     * confirm write runs under the audience-anchor + delegated-admin gates
     * with the caller's execution context — never auto-bound, never system).
     *
     * Routes:
     *   GET  /security/suggested-bindings?status=&packageId=   → list (reconciles first)
     *   POST /security/suggested-bindings/:id/confirm          → create the anchor binding
     *   POST /security/suggested-bindings/:id/dismiss          → decline the suggestion
     */
    async handleSecurity(path: string, method: string, _body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        const service = await this.resolveService('security', context.environmentId) as any;
        if (!service || typeof service.listAudienceBindingSuggestions !== 'function') {
            return { handled: true, response: this.error('Security service not available', 503) };
        }

        const ec = context.executionContext;
        // Admin surface — anonymous is denied UNCONDITIONALLY (`requireAuth:
        // true` hardcoded), independent of the deployment posture: even a
        // `requireAuth: false` demo must not let anonymous callers list or
        // confirm audience bindings. Shares the decision + body with every
        // other HTTP seam (#2567).
        if (shouldDenyAnonymous({ requireAuth: true, userId: ec?.userId, isSystem: ec?.isSystem })) {
            return {
                handled: true,
                response: this.error(ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, { code: ANONYMOUS_DENY_CODE }),
            };
        }

        const m = method.toUpperCase();
        // split+filter drops leading/trailing/duplicate slashes without a
        // regex over request-controlled input (CodeQL js/polynomial-redos).
        const parts = path.split('/').filter(Boolean);
        if (parts[0] !== 'suggested-bindings') return { handled: false };

        try {
            // GET /security/suggested-bindings
            if (parts.length === 1 && m === 'GET') {
                const status = query?.status ? String(query.status) : undefined;
                const packageId = query?.packageId ? String(query.packageId) : undefined;
                const result = await service.listAudienceBindingSuggestions(ec, { status, packageId });
                return { handled: true, response: this.success(result) };
            }

            // POST /security/suggested-bindings/:id/confirm|dismiss
            if (parts.length === 3 && m === 'POST') {
                const id = decodeURIComponent(parts[1]);
                if (parts[2] === 'confirm') {
                    const result = await service.confirmAudienceBindingSuggestion(ec, id);
                    return { handled: true, response: this.success(result) };
                }
                if (parts[2] === 'dismiss') {
                    const result = await service.dismissAudienceBindingSuggestion(ec, id);
                    return { handled: true, response: this.success(result) };
                }
            }

            return { handled: false };
        } catch (err: any) {
            // The service throws typed errors carrying their HTTP status:
            // PermissionDeniedError → 403, SuggestionNotFoundError → 404,
            // SuggestionStateError → 409.
            const status = typeof err?.statusCode === 'number' ? err.statusCode : 500;
            return { handled: true, response: this.error(err?.message ?? 'Security operation failed', status) };
        }
    }

    /**
     * Handles i18n requests
     * path: sub-path after /i18n/
     *
     * Routes:
     *   GET /locales                    → getLocales
     *   GET /translations/:locale       → getTranslations (locale from path)
     *   GET /translations?locale=xx     → getTranslations (locale from query)
     *   GET /labels/:object/:locale     → getFieldLabels  (both from path)
     *   GET /labels/:object?locale=xx   → getFieldLabels  (locale from query)
     */
    async handleI18n(path: string, method: string, query: any, _context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        const i18nService = await this.getService(CoreServiceName.enum.i18n);
        if (!i18nService) return { handled: true, response: this.error('i18n service not available', 501) };

        const m = method.toUpperCase();
        const parts = path.replace(/^\/+/, '').split('/').filter(Boolean);

        if (m !== 'GET') return { handled: false };

        // GET /i18n/locales
        if (parts[0] === 'locales' && parts.length === 1) {
            const locales = i18nService.getLocales();
            return { handled: true, response: this.success({ locales }) };
        }

        // GET /i18n/translations/:locale  OR  /i18n/translations?locale=xx
        if (parts[0] === 'translations') {
            const locale = parts[1] ? decodeURIComponent(parts[1]) : query?.locale;
            if (!locale) return { handled: true, response: this.error('Missing locale parameter', 400) };

            let translations = i18nService.getTranslations(locale);

            // Locale fallback: try resolving to an available locale when
            // the exact code yields empty translations (e.g. zh → zh-CN).
            if (Object.keys(translations).length === 0) {
                const availableLocales = typeof i18nService.getLocales === 'function'
                    ? i18nService.getLocales() : [];
                const resolved = resolveLocale(locale, availableLocales);
                if (resolved && resolved !== locale) {
                    translations = i18nService.getTranslations(resolved);
                    return { handled: true, response: this.success({ locale: resolved, requestedLocale: locale, translations }) };
                }
            }

            return { handled: true, response: this.success({ locale, translations }) };
        }

        // GET /i18n/labels/:object/:locale  OR  /i18n/labels/:object?locale=xx
        if (parts[0] === 'labels' && parts.length >= 2) {
            const objectName = decodeURIComponent(parts[1]);
            let locale = parts[2] ? decodeURIComponent(parts[2]) : query?.locale;
            if (!locale) return { handled: true, response: this.error('Missing locale parameter', 400) };

            // Locale fallback for labels endpoint
            const availableLocales = typeof i18nService.getLocales === 'function'
                ? i18nService.getLocales() : [];
            const resolved = resolveLocale(locale, availableLocales);
            if (resolved) locale = resolved;

            if (typeof i18nService.getFieldLabels === 'function') {
                const labels = i18nService.getFieldLabels(objectName, locale);
                return { handled: true, response: this.success({ object: objectName, locale, labels }) };
            }
            // Fallback: derive field labels from full translation bundle
            const translations = i18nService.getTranslations(locale);
            const prefix = `o.${objectName}.fields.`;
            const labels: Record<string, string> = {};
            for (const [key, value] of Object.entries(translations)) {
                if (key.startsWith(prefix)) {
                    labels[key.substring(prefix.length)] = value as string;
                }
            }
            return { handled: true, response: this.success({ object: objectName, locale, labels }) };
        }

        return { handled: false };
    }

    /**
     * Handles Package Management requests
     * 
     * REST Endpoints:
     * - GET    /packages          → list all installed packages
     * - GET    /packages/:id      → get a specific package
     * - POST   /packages          → install a new package
     * - DELETE  /packages/:id      → uninstall a package
     * - PATCH  /packages/:id/enable  → enable a package
     * - PATCH  /packages/:id/disable → disable a package
     * - POST   /packages/:id/publish → publish a package (metadata snapshot)
     * - POST   /packages/:id/revert  → revert a package to last published state
     * 
     * Uses ObjectQL SchemaRegistry directly (via the 'objectql' service).
     */
    async handlePackages(path: string, method: string, body: any, query: any, _context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        const m = method.toUpperCase();
        const parts = path.replace(/^\/+/, '').split('/').filter(Boolean);

        // Try to get SchemaRegistry from the ObjectQL service
        const qlService = await this.getObjectQLService();
        const registry = qlService?.registry;

        // If no registry available, return 503
        if (!registry) {
            return { handled: true, response: this.error('Package service not available', 503) };
        }

        try {
            // GET /packages → list packages
            if (parts.length === 0 && m === 'GET') {
                let packages = registry.getAllPackages();
                // Apply optional filters
                if (query?.status) {
                    packages = packages.filter((p: any) => p.status === query.status);
                }
                if (query?.type) {
                    packages = packages.filter((p: any) => p.manifest?.type === query.type);
                }
                return { handled: true, response: this.success({ packages, total: packages.length }) };
            }

            // POST /packages → install package.
            // Route through the canonical `protocol.installPackage` primitive so
            // the install lands in BOTH the in-memory registry (what this list/detail
            // reads) AND the durable `sys_packages` table. Fall back to the bare
            // registry write only when the protocol service/method is unavailable.
            if (parts.length === 0 && m === 'POST') {
                const manifest = body.manifest || body;
                const pkgId = typeof manifest?.id === 'string' ? manifest.id.trim() : '';
                // A package id is mandatory — without one the install cannot be keyed.
                if (!pkgId) {
                    return { handled: true, response: this.error('Package id is required', 400) };
                }
                // Duplicate-detection: POST /packages CREATES a package. If one with
                // this id already exists, silently overwriting it destroys the existing
                // manifest (name/version/…) with no warning — a data-loss footgun
                // surfaced in Studio package-create dogfooding. Reject with 409 Conflict
                // instead. Intentional upgrade / re-install flows opt back in with
                // `overwrite: true` (body) or `?overwrite=true`.
                const overwrite =
                    body?.overwrite === true || query?.overwrite === 'true' || query?.overwrite === true;
                if (!overwrite && registry.getPackage(pkgId)) {
                    return {
                        handled: true,
                        response: this.error(`Package '${pkgId}' already exists`, 409),
                    };
                }
                let pkg: any;
                const protocolSvc: any = await this.resolveService('protocol').catch(() => null);
                if (protocolSvc && typeof protocolSvc.installPackage === 'function') {
                    const out = await protocolSvc.installPackage({ manifest, settings: body.settings });
                    pkg = out?.package ?? out;
                } else {
                    pkg = registry.installPackage(manifest, body.settings);
                }
                const res = this.success(pkg);
                res.status = 201;
                return { handled: true, response: res };
            }

            // PATCH /packages/:id/enable
            if (parts.length === 2 && parts[1] === 'enable' && m === 'PATCH') {
                const id = decodeURIComponent(parts[0]);
                const pkg = registry.enablePackage(id);
                if (!pkg) return { handled: true, response: this.error(`Package '${id}' not found`, 404) };
                try {
                    setPackageDisabled(_context?.environmentId, id, false);
                } catch (err) {
                    console.warn('[handlePackages] failed to persist enable state', { id, error: (err as Error)?.message });
                }
                return { handled: true, response: this.success(pkg) };
            }

            // PATCH /packages/:id/disable
            if (parts.length === 2 && parts[1] === 'disable' && m === 'PATCH') {
                const id = decodeURIComponent(parts[0]);
                const pkg = registry.disablePackage(id);
                if (!pkg) return { handled: true, response: this.error(`Package '${id}' not found`, 404) };
                try {
                    setPackageDisabled(_context?.environmentId, id, true);
                } catch (err) {
                    console.warn('[handlePackages] failed to persist disable state', { id, error: (err as Error)?.message });
                }
                return { handled: true, response: this.success(pkg) };
            }

            // POST /packages/:id/publish → publish package metadata
            if (parts.length === 2 && parts[1] === 'publish' && m === 'POST') {
                const id = decodeURIComponent(parts[0]);
                const metadataService = await this.getService(CoreServiceName.enum.metadata);
                if (metadataService && typeof (metadataService as any).publishPackage === 'function') {
                    const result = await (metadataService as any).publishPackage(id, body || {});
                    return { handled: true, response: this.success(result) };
                }
                return { handled: true, response: this.error('Metadata service not available', 503) };
            }

            // POST /packages/:id/publish-drafts → promote every pending DRAFT
            // bound to the package to active in one shot ("publish whole app",
            // ADR-0033). Routes through protocol.publishPackageDrafts (which
            // reuses the per-item publish primitive) — no metadata service
            // dependency, unlike /publish above.
            if (parts.length === 2 && parts[1] === 'publish-drafts' && m === 'POST') {
                const id = decodeURIComponent(parts[0]);
                const protocol = await this.resolveService('protocol');
                if (protocol && typeof (protocol as any).publishPackageDrafts === 'function') {
                    try {
                        const organizationId = await this.resolveActiveOrganizationId(_context);
                        const result = await (protocol as any).publishPackageDrafts({
                            packageId: id,
                            ...(organizationId ? { organizationId } : {}),
                            ...(body?.actor ? { actor: body.actor } : {}),
                        });
                        // Publishing a `seed` draft is what actually loads its
                        // rows. The objectql protocol now batch-applies seeds
                        // inside `publishPackageDrafts` itself (so EVERY publish
                        // path — incl. the per-ref REST publish — materializes
                        // data) and reports under `seedApplied`. Only fall back
                        // to the route-level apply for custom protocols that
                        // don't self-apply — never run both, or an externalId-less
                        // seed would double-insert.
                        if ((result as any)?.seedApplied === undefined) {
                            try {
                                const seedNames = ((result as any)?.published ?? [])
                                    .filter((p: any) => p?.type === 'seed')
                                    .map((p: any) => p.name as string);
                                if (seedNames.length > 0) {
                                    (result as any).seedApplied = await this.applyPublishedSeeds(
                                        seedNames,
                                        organizationId,
                                        _context,
                                    );
                                }
                            } catch (e: any) {
                                (result as any).seedApplied = { success: false, error: e?.message ?? 'seed apply failed' };
                            }
                        }
                        // ADR-0045: "Publish" makes the package live AND visible.
                        // A materialized (additive) build has no drafts left to
                        // promote — its app sits at `hidden: true` awaiting the
                        // visibility flip. Unhide every hidden app bound to this
                        // package so ONE publish verb serves both regimes (the
                        // caller never needs to know how the package was built).
                        // Best-effort: a custom protocol without the meta
                        // primitives keeps plain draft-publish semantics.
                        try {
                            if (
                                typeof (protocol as any).getMetaItems === 'function' &&
                                typeof (protocol as any).saveMetaItem === 'function'
                            ) {
                                const appsRes = await (protocol as any).getMetaItems({
                                    type: 'app',
                                    packageId: id,
                                    ...(organizationId ? { organizationId } : {}),
                                });
                                const apps: any[] = Array.isArray(appsRes)
                                    ? appsRes
                                    : Array.isArray((appsRes as any)?.items) ? (appsRes as any).items : [];
                                const unhidden: string[] = [];
                                for (const app of apps) {
                                    if (app && typeof app === 'object' && app.hidden === true && typeof app.name === 'string') {
                                        await (protocol as any).saveMetaItem({
                                            type: 'app',
                                            name: app.name,
                                            item: { ...app, hidden: false },
                                            packageId: id,
                                            ...(organizationId ? { organizationId } : {}),
                                            ...(body?.actor ? { actor: body.actor } : {}),
                                        });
                                        unhidden.push(app.name);
                                    }
                                }
                                if (unhidden.length > 0) (result as any).unhiddenApps = unhidden;
                            }
                        } catch (e: any) {
                            (result as any).unhideError = e?.message ?? 'visibility flip failed';
                        }
                        // A publish promoted drafts to active (or unhid an additive
                        // app) at RUNTIME — but boot-cached consumers still hold the
                        // pre-publish view. The load-bearing one is the automation
                        // engine: a record-triggered flow authored + published in the
                        // Studio does NOT bind its trigger (record-change automations
                        // never fire) until the next restart. Announce
                        // 'metadata:reloaded' — the same signal a dev artifact reload
                        // fires (MetadataPlugin._reloadAndAnnounce) — so subscribers
                        // re-sync WITHOUT a restart. #2560 covers the cold-boot bind;
                        // this covers publish-while-running. `this.kernel.context` is
                        // the same handle the service resolver uses above. Best-effort:
                        // a subscriber failure must never fail the publish (the drafts
                        // are already live), so it rides the response instead.
                        try {
                            const changed = [
                                ...(((result as any)?.published ?? []) as Array<{ type: string; name: string }>)
                                    .map((p) => `${p.type}/${p.name}`),
                                ...(((result as any)?.unhiddenApps ?? []) as string[]).map((n) => `app/${n}`),
                            ];
                            if (changed.length > 0 && this.kernel?.context?.trigger) {
                                await this.kernel.context.trigger('metadata:reloaded', { changed });
                            }
                        } catch (e: any) {
                            (result as any).rebindError = e?.message ?? 'metadata:reloaded announce failed';
                        }
                        return { handled: true, response: this.success(result) };
                    } catch (e: any) {
                        // Carry spec-validation `issues` (and the real 422 status —
                        // the protocol sets `.status`, not `.statusCode`) through to
                        // the publish surface so failures are field-anchored.
                        return { handled: true, response: this.errorFromThrown(e, 500) };
                    }
                }
                return { handled: true, response: this.error('Draft publishing not supported', 501) };
            }

            // POST /packages/:id/discard-drafts → drop every pending DRAFT bound
            // to the package, reverting it to its last published baseline
            // ("abandon all my changes"). NON-destructive: active metadata and
            // physical tables are untouched. Routes through the sys_metadata
            // path (no metadata-service dependency, unlike /revert below).
            if (parts.length === 2 && parts[1] === 'discard-drafts' && m === 'POST') {
                const id = decodeURIComponent(parts[0]);
                const protocol = await this.resolveService('protocol');
                if (protocol && typeof (protocol as any).discardPackageDrafts === 'function') {
                    try {
                        const organizationId = await this.resolveActiveOrganizationId(_context);
                        const result = await (protocol as any).discardPackageDrafts({
                            packageId: id,
                            ...(organizationId ? { organizationId } : {}),
                            ...(body?.actor ? { actor: body.actor } : {}),
                        });
                        return { handled: true, response: this.success(result) };
                    } catch (e: any) {
                        return { handled: true, response: this.error(e.message, e.statusCode || 500) };
                    }
                }
                return { handled: true, response: this.error('Draft discarding not supported', 501) };
            }

            // ── ADR-0067: package-scoped commit history & rollback ──────────

            // GET /packages/:id/commits → the commit timeline (newest-first).
            if (parts.length === 2 && parts[1] === 'commits' && m === 'GET') {
                const id = decodeURIComponent(parts[0]);
                const protocol = await this.resolveService('protocol');
                if (protocol && typeof (protocol as any).listCommits === 'function') {
                    try {
                        const organizationId = await this.resolveActiveOrganizationId(_context);
                        const commits = await (protocol as any).listCommits({
                            packageId: id,
                            ...(organizationId ? { organizationId } : {}),
                        });
                        return { handled: true, response: this.success({ commits }) };
                    } catch (e: any) {
                        return { handled: true, response: this.error(e.message, e.statusCode || 500) };
                    }
                }
                return { handled: true, response: this.error('Commit history not supported', 501) };
            }

            // POST /packages/:id/commits/:commitId/revert → revert ONE commit
            // (ADR-0067). Created artifacts are soft-removed, edited ones are
            // restored to their pre-commit version; the revert is itself a commit.
            if (parts.length === 4 && parts[1] === 'commits' && parts[3] === 'revert' && m === 'POST') {
                const commitId = decodeURIComponent(parts[2]);
                const protocol = await this.resolveService('protocol');
                if (protocol && typeof (protocol as any).revertCommit === 'function') {
                    try {
                        const organizationId = await this.resolveActiveOrganizationId(_context);
                        const result = await (protocol as any).revertCommit({
                            commitId,
                            ...(organizationId ? { organizationId } : {}),
                            ...(body?.actor ? { actor: body.actor } : {}),
                        });
                        return { handled: true, response: this.success(result) };
                    } catch (e: any) {
                        return { handled: true, response: this.error(e.message, e.statusCode || 500) };
                    }
                }
                return { handled: true, response: this.error('Commit revert not supported', 501) };
            }

            // POST /packages/:id/rollback  body { commitId } → roll the package
            // back THROUGH every commit newer than `commitId` (ADR-0067).
            if (parts.length === 2 && parts[1] === 'rollback' && m === 'POST') {
                const protocol = await this.resolveService('protocol');
                if (protocol && typeof (protocol as any).rollbackToPackageCommit === 'function') {
                    if (!body?.commitId) {
                        return { handled: true, response: this.error('Body { commitId } is required', 400) };
                    }
                    try {
                        const organizationId = await this.resolveActiveOrganizationId(_context);
                        const result = await (protocol as any).rollbackToPackageCommit({
                            commitId: String(body.commitId),
                            ...(organizationId ? { organizationId } : {}),
                            ...(body?.actor ? { actor: body.actor } : {}),
                        });
                        return { handled: true, response: this.success(result) };
                    } catch (e: any) {
                        return { handled: true, response: this.error(e.message, e.statusCode || 500) };
                    }
                }
                return { handled: true, response: this.error('Commit rollback not supported', 501) };
            }

            // POST /packages/:id/revert → revert package to last published state
            if (parts.length === 2 && parts[1] === 'revert' && m === 'POST') {
                const id = decodeURIComponent(parts[0]);
                const metadataService = await this.getService(CoreServiceName.enum.metadata);
                if (metadataService && typeof (metadataService as any).revertPackage === 'function') {
                    await (metadataService as any).revertPackage(id);
                    return { handled: true, response: this.success({ success: true }) };
                }
                return { handled: true, response: this.error('Metadata service not available', 503) };
            }

            // GET /packages/:id/export → assemble a portable manifest from
            // sys_metadata overlay rows bound to this package (offline export).
            if (parts.length === 2 && parts[1] === 'export' && m === 'GET') {
                const id = decodeURIComponent(parts[0]);
                const manifest = await this.assemblePackageManifest(id, registry, _context);
                if (!manifest) {
                    return { handled: true, response: this.error(`Package '${id}' not found`, 404) };
                }
                return { handled: true, response: this.success(manifest) };
            }

            // POST /packages/:id/adopt-orphans → bulk-rebind package-less (legacy
            // null / 'sys_metadata') metadata INTO this base (ADR-0070 D5 migration;
            // lets the env retire the "Local / Custom" scope once it has no orphans).
            if (parts.length === 2 && parts[1] === 'adopt-orphans' && m === 'POST') {
                const id = decodeURIComponent(parts[0]);
                const protocol = await this.resolveService('protocol');
                if (!protocol || typeof (protocol as any).reassignOrphanedMetadata !== 'function') {
                    return { handled: true, response: this.error('Orphan adoption not supported', 501) };
                }
                try {
                    const organizationId = await this.resolveActiveOrganizationId(_context);
                    const result = await (protocol as any).reassignOrphanedMetadata({
                        targetPackageId: id,
                        ...(organizationId ? { organizationId } : {}),
                        ...(body?.actor ? { actor: body.actor } : {}),
                    });
                    return { handled: true, response: this.success(result) };
                } catch (e: any) {
                    return { handled: true, response: this.error(e.message, e.statusCode || 500) };
                }
            }

            // POST /packages/:id/duplicate → clone this base into a NEW writable
            // package, re-namespacing objects + rewriting references (ADR-0070 D4
            // "duplicate base"). Body { targetPackageId, targetName?, targetNamespace? }.
            if (parts.length === 2 && parts[1] === 'duplicate' && m === 'POST') {
                const id = decodeURIComponent(parts[0]);
                const protocol = await this.resolveService('protocol');
                if (!protocol || typeof (protocol as any).duplicatePackage !== 'function') {
                    return { handled: true, response: this.error('Package duplication not supported', 501) };
                }
                const targetPackageId = typeof body?.targetPackageId === 'string' ? body.targetPackageId.trim() : '';
                if (!targetPackageId) {
                    return { handled: true, response: this.error('Body { targetPackageId } is required', 400) };
                }
                try {
                    const organizationId = await this.resolveActiveOrganizationId(_context);
                    const result = await (protocol as any).duplicatePackage({
                        sourcePackageId: id,
                        targetPackageId,
                        ...(typeof body?.targetName === 'string' ? { targetName: body.targetName } : {}),
                        ...(typeof body?.targetNamespace === 'string' ? { targetNamespace: body.targetNamespace } : {}),
                        ...(organizationId ? { organizationId } : {}),
                        ...(body?.actor ? { actor: body.actor } : {}),
                    });
                    return { handled: true, response: this.success(result) };
                } catch (e: any) {
                    return { handled: true, response: this.error(e.message, e.statusCode || 500) };
                }
            }

            // GET /packages/:id → get package
            if (parts.length === 1 && m === 'GET') {
                const id = decodeURIComponent(parts[0]);
                const pkg = registry.getPackage(id);
                if (!pkg) return { handled: true, response: this.error(`Package '${id}' not found`, 404) };
                return { handled: true, response: this.success(pkg) };
            }

            // PATCH /packages/:id → edit the manifest (name / description /
            // version). A partial patch: only the fields present are changed;
            // lifecycle state (enabled / status / installedAt) is preserved.
            // `id` / `scope` / `type` are identity/structure and are NOT editable
            // here. Body accepts the fields flat or under a `manifest` wrapper.
            if (parts.length === 1 && m === 'PATCH') {
                const id = decodeURIComponent(parts[0]);
                const src = (body?.manifest && typeof body.manifest === 'object' ? body.manifest : body) ?? {};
                const patch: { name?: string; description?: string; version?: string } = {};
                if (typeof src.name === 'string') patch.name = src.name.trim();
                if (typeof src.description === 'string') patch.description = src.description;
                if (typeof src.version === 'string') patch.version = src.version.trim();

                if (patch.name !== undefined && patch.name === '') {
                    return { handled: true, response: this.error('name must not be empty', 400) };
                }
                if (patch.version !== undefined && !/^\d+\.\d+\.\d+$/.test(patch.version)) {
                    return { handled: true, response: this.error('version must be semantic (e.g. 1.0.0)', 400) };
                }
                if (patch.name === undefined && patch.description === undefined && patch.version === undefined) {
                    return { handled: true, response: this.error('Body { name?, description?, version? } — nothing to update', 400) };
                }

                const protocol = await this.resolveService('protocol');
                if (protocol && typeof (protocol as any).updatePackage === 'function') {
                    try {
                        const updated = await (protocol as any).updatePackage({ packageId: id, patch });
                        return { handled: true, response: this.success((updated as any)?.package ?? updated) };
                    } catch (e: any) {
                        return { handled: true, response: this.error(e.message, e.statusCode || 500) };
                    }
                }
                // Fallback: no protocol service — in-memory registry only.
                const pkg = registry.updatePackageManifest(id, patch);
                if (!pkg) return { handled: true, response: this.error(`Package '${id}' not found`, 404) };
                return { handled: true, response: this.success(pkg) };
            }

            // DELETE /packages/:id → delete the package. Unregisters it from the
            // in-memory registry AND removes its persisted sys_metadata rows
            // (active + draft), tearing down each object's physical table by
            // default. `?keepData=true` preserves object tables (metadata-only
            // delete). Use case: "I don't want this package anymore."
            if (parts.length === 1 && m === 'DELETE') {
                const id = decodeURIComponent(parts[0]);
                const registryRemoved = registry.uninstallPackage(id);

                // Persisted removal (AI/runtime packages live in sys_metadata, not
                // just the in-memory registry — the registry uninstall alone would
                // leave the rows and tables behind).
                let persisted: unknown = undefined;
                const protocol = await this.resolveService('protocol');
                if (protocol && typeof (protocol as any).deletePackage === 'function') {
                    try {
                        const organizationId = await this.resolveActiveOrganizationId(_context);
                        const keepData = query?.keepData === 'true' || query?.keepData === '1';
                        persisted = await (protocol as any).deletePackage({
                            packageId: id,
                            ...(organizationId ? { organizationId } : {}),
                            ...(keepData ? { keepData: true } : {}),
                        });
                    } catch (e: any) {
                        return { handled: true, response: this.error(e.message, e.statusCode || 500) };
                    }
                }

                const deletedCount = (persisted as any)?.deletedCount ?? 0;
                if (!registryRemoved && deletedCount === 0) {
                    return { handled: true, response: this.error(`Package '${id}' not found`, 404) };
                }
                return { handled: true, response: this.success({ success: true, registryRemoved, persisted }) };
            }
        } catch (e: any) {
            return { handled: true, response: this.error(e.message, e.statusCode || 500) };
        }

        return { handled: false };
    }

    /**
     * Assemble a portable, offline-installable package manifest from the
     * `sys_metadata` overlay rows bound to `packageId`.
     *
     * The resulting shape mirrors what `marketplace-install-local` →
     * `manifestService.register()` → `engine.registerApp()` consumes:
     *   `{ id, name, version, objects:[…], views:[…], flows:[…], … }`
     * where each category key is the PLURAL manifest name and its value is
     * an array of clean metadata bodies (provenance decorations stripped).
     *
     * Only the metadata categories that `registerApp` can actually consume
     * are exported. `datasources` and `emailTemplates` are intentionally
     * excluded (not registered by the import path). `tools` / `skills` ARE
     * round-tripped: they are registered by `registerApp` on import and
     * surfaced by `getMetaItems('tool' | 'skill')` on export.
     *
     * @returns the manifest object, or `null` if the package id is unknown
     *          AND has no overlay-authored metadata.
     */
    private async assemblePackageManifest(
        packageId: string,
        registry: any,
        context: HttpProtocolContext,
    ): Promise<Record<string, any> | null> {
        const protocol = await this.resolveService('protocol');
        if (!protocol || typeof protocol.getMetaItems !== 'function') return null;

        const organizationId = await this.resolveActiveOrganizationId(context);

        // Provenance / overlay-bookkeeping keys that must never leak into a
        // portable manifest. Stripped at top level only — nested field bodies
        // are left untouched.
        const PROVENANCE_KEYS = new Set([
            '_packageId', '_packageVersionId', '_provenance', '_state',
            '_version', '_organizationId', '_source', '_id', '_rowId',
        ]);
        const clean = (item: any) => {
            if (!item || typeof item !== 'object') return item;
            const out: Record<string, any> = {};
            for (const [k, v] of Object.entries(item)) {
                if (k.startsWith('_') || PROVENANCE_KEYS.has(k)) continue;
                out[k] = v;
            }
            return out;
        };

        // Categories the local-install register path understands. Excludes
        // datasources / emailTemplates (not consumed by registerApp).
        const exportPluralKeys = Object.keys(PLURAL_TO_SINGULAR).filter(
            (k) => k !== 'datasources' && k !== 'emailTemplates',
        );

        const manifest: Record<string, any> = {};
        let total = 0;
        for (const plural of exportPluralKeys) {
            const singular = PLURAL_TO_SINGULAR[plural];
            let items: any[] = [];
            try {
                // getMetaItems applies the packageId filter at the
                // registry/overlay query level, so the returned items are
                // already scoped to this package — no client-side re-filter.
                const res = await protocol.getMetaItems({ type: singular, packageId, organizationId });
                items = Array.isArray(res?.items) ? res.items : [];
            } catch {
                // Unknown/unsupported type for this runtime — skip.
                continue;
            }
            if (items.length === 0) continue;
            manifest[plural] = items.map(clean);
            total += items.length;
        }

        const pkg = (() => {
            try { return registry?.getPackage?.(packageId); } catch { return undefined; }
        })();

        if (total === 0 && !pkg) return null;

        manifest.id = packageId;
        manifest.name = pkg?.manifest?.name ?? pkg?.name ?? packageId;
        manifest.version = pkg?.manifest?.version ?? pkg?.version ?? '1.0.0';
        if (pkg?.manifest?.label ?? pkg?.label) {
            manifest.label = pkg?.manifest?.label ?? pkg?.label;
        }
        return manifest;
    }

    /**
     * Cloud / Environment Control-Plane routes.
     *
     *  - GET    /cloud/drivers                                 → list registered ObjectQL drivers (for env provisioning)
     *  - GET    /cloud/environments                            → list
     *  - POST   /cloud/environments                            → provision (driver: memory | turso | <any registered driver>)
     *  - GET    /cloud/environments/:id                        → detail (+ db, credential, membership)
     *  - PATCH  /cloud/environments/:id                        → update displayName / plan / status / isDefault / metadata
     *  - DELETE /cloud/environments/:id[?force=1]              → cascade-delete the project (cred/member/package install rows + physical DB)
     *  - DELETE /cloud/organizations/:id                   → cascade-delete every project (and its DB) for the org, then drop the org
     *  - POST   /cloud/environments/:id/retry                  → re-run provisioning for a failed environment
     *  - POST   /cloud/environments/:id/activate               → mark as active for session (stub)
     *  - POST   /cloud/environments/:id/credentials/rotate     → rotate credential
     *  - GET    /cloud/environments/:id/members                → list members
     *  - GET    /cloud/environments/:id/packages               → list installed packages
     *  - POST   /cloud/environments/:id/packages               → install package into env
     *  - GET    /cloud/environments/:id/packages/:pkgId        → get installation detail
     *  - PATCH  /cloud/environments/:id/packages/:pkgId/enable  → enable package
     *  - PATCH  /cloud/environments/:id/packages/:pkgId/disable → disable package
     *  - DELETE /cloud/environments/:id/packages/:pkgId        → uninstall (scope=platform forbidden)
     *  - POST   /cloud/environments/:id/packages/:pkgId/upgrade → upgrade to newer version
     *
     * Driver binding
     * --------------
     * Environments are not tied to any specific driver. At provisioning time the
     * caller passes `driver` (a short name such as `memory`, `turso`, or any
     * future `sql` / `postgres` driver). The dispatcher validates the name
     * against the kernel's registered driver services (`driver.<name>`) and
     * derives an appropriate placeholder `database_url` for the chosen driver.
     * If `driver` is omitted, the dispatcher auto-selects the first available
     * in preference order: turso → memory → any other registered driver.
     *
     * Backed by ObjectQL sys_environment / sys_environment_credential /
     * sys_environment_member tables (registered by
     * `@objectstack/service-tenant`'s `createTenantPlugin`).
     * Physical database addressing (database_url, database_driver, etc.)
     * is stored directly on the sys_environment row.
     */
    /**
     * Apply just-published `seed` metadata: load each seed's rows into its
     * target object so publishing a seed draft makes the data live (the runtime
     * counterpart to staging it). Reads each seed body via the protocol, then
     * runs the {@link SeedLoaderService} for the active org. Best-effort and
     * idempotent (upsert) — callers must never let this fail the publish.
     *
     * Lives at the runtime layer (not in the objectql publish primitive)
     * because the seed loader needs the data engine + metadata service, which
     * objectql cannot depend on without a layering cycle.
     */
    private async applyPublishedSeeds(
        names: string[],
        organizationId: string | undefined,
        _context: HttpProtocolContext,
    ): Promise<{ success: boolean; inserted?: number; updated?: number; errors?: unknown[]; error?: string }> {
        const protocol: any = await this.resolveService('protocol');
        const metadata: any = await this.getService(CoreServiceName.enum.metadata);
        const ql: any = await this.resolveService('objectql');
        if (!protocol || typeof protocol.getMetaItem !== 'function' || !ql || !metadata) {
            return { success: false, error: 'seed apply: required services unavailable' };
        }
        const datasets: any[] = [];
        const readErrors: string[] = [];
        for (const name of names) {
            // Read the just-published seed body. Try the active org first, then
            // fall back to an env-wide read — a workspace seed is often stored
            // org-wide (organization_id IS NULL), and resolving the wrong scope
            // here is what silently produced "0 rows loaded".
            const attempts = organizationId
                ? [{ type: 'seed', name, organizationId }, { type: 'seed', name }]
                : [{ type: 'seed', name }];
            let item: any;
            for (const args of attempts) {
                try {
                    item = await protocol.getMetaItem(args);
                    if (item) break;
                } catch (e) {
                    readErrors.push(`read ${name}: ${(e as Error)?.message ?? String(e)}`);
                }
            }
            // protocol.getMetaItem (called directly, unlike the HTTP endpoint
            // which unwraps) returns a WRAPPER: `{ type, name, item, lock,
            // editable, … }` — the seed body (object/records) lives under
            // `.item`. Tolerate the wrapper (`.item`) plus the body-direct and
            // `.metadata`/`.body` shapes other protocols may return.
            const seed = item?.object && Array.isArray(item?.records)
                ? item
                : (item?.item ?? item?.metadata ?? item?.body);
            if (seed?.object && Array.isArray(seed?.records)) {
                datasets.push(seed);
            } else {
                readErrors.push(`seed "${name}" body unreadable (keys: ${item ? Object.keys(item).join(',') : 'none'})`);
            }
        }
        // Seeds were published but none could be read back → surface it (do NOT
        // report success with 0 rows, which hides the failure).
        if (datasets.length === 0) {
            return { success: false, inserted: 0, updated: 0, error: 'seed apply: no readable seed bodies', errors: readErrors };
        }

        const { SeedLoaderService } = await import('./seed-loader.js');
        const { SeedLoaderRequestSchema } = await import('@objectstack/spec/data');
        const loader = new SeedLoaderService(ql, metadata, (this as any).logger ?? console);
        const request = SeedLoaderRequestSchema.parse({
            seeds: datasets,
            config: {
                defaultMode: 'upsert',
                multiPass: true,
                ...(organizationId ? { organizationId } : {}),
            },
        });
        const r = await loader.load(request);
        return {
            success: r.success,
            inserted: r.summary.totalInserted,
            updated: r.summary.totalUpdated,
            errors: [...readErrors, ...(r.errors ?? [])],
        };
    }

    /**
     * Resolve the calling user id from the request session, if any.
     * Returns `undefined` for anonymous calls or when auth is not wired up.
     */
    private async resolveActiveOrganizationId(context: HttpProtocolContext): Promise<string | undefined> {
        try {
            const authService: any = await this.resolveService(CoreServiceName.enum.auth);
            const rawHeaders = context.request?.headers;
            let headers: any = rawHeaders;
            if (rawHeaders && typeof rawHeaders === 'object' && typeof (rawHeaders as any).get !== 'function') {
                try {
                    const h = new Headers();
                    for (const [k, v] of Object.entries(rawHeaders as Record<string, any>)) {
                        if (v == null) continue;
                        h.set(k, Array.isArray(v) ? v.join(', ') : String(v));
                    }
                    headers = h;
                } catch {
                    headers = rawHeaders;
                }
            }
            const apiObj = authService?.auth?.api ?? authService?.api;
            const sessionData = await apiObj?.getSession?.call(apiObj, { headers });
            const oid = sessionData?.session?.activeOrganizationId;
            return typeof oid === 'string' && oid.length > 0 ? oid : undefined;
        } catch {
            return undefined;
        }
    }

    /**
     * Handles Storage requests
     * path: sub-path after /storage/
     */
    async handleStorage(path: string, method: string, file: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        const storageService = await this.getService(CoreServiceName.enum['file-storage']) || this.kernel.services?.['file-storage'];
        if (!storageService) {
             return { handled: true, response: this.error('File storage not configured', 501) };
        }
        
        const m = method.toUpperCase();
        const parts = path.replace(/^\/+/, '').split('/');
        
        // POST /storage/upload
        if (parts[0] === 'upload' && m === 'POST') {
            if (!file) {
                 return { handled: true, response: this.error('No file provided', 400) };
            }
            const result = await storageService.upload(file, { request: context.request });
            return { handled: true, response: this.success(result) };
        }
        
        // GET /storage/file/:id
        if (parts[0] === 'file' && parts[1] && m === 'GET') {
            const id = parts[1];
            const result = await storageService.download(id, { request: context.request });
            
            // Result can be URL (redirect), Stream/Blob, or metadata
            if (result.url && result.redirect) {
                // Must be handled by adapter to do actual redirect
                return { handled: true, result: { type: 'redirect', url: result.url } };
            }
            
            if (result.stream) {
                 // Must be handled by adapter to pipe stream
                 return { 
                     handled: true, 
                     result: { 
                         type: 'stream', 
                         stream: result.stream, 
                         headers: {
                             'Content-Type': result.mimeType || 'application/octet-stream',
                             'Content-Length': result.size
                         }
                     } 
                 };
            }
            
            return { handled: true, response: this.success(result) };
        }
        
        return { handled: false };
    }

    /**
     * Handles UI requests
     * path: sub-path after /ui/
     */
    async handleUi(path: string, query: any, _context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        const parts = path.replace(/^\/+/, '').split('/').filter(Boolean);
        
        // GET /ui/view/:object (with optional type param)
        if (parts[0] === 'view' && parts[1]) {
            const objectName = parts[1];
            // Support both path param /view/obj/list AND query param /view/obj?type=list
            const type = parts[2] || query?.type || 'list';

            const protocol = await this.resolveService('protocol');
            
            if (protocol && typeof protocol.getUiView === 'function') {
                try {
                    const result = await protocol.getUiView({ object: objectName, type });
                    return { handled: true, response: this.success(result) };
                } catch (e: any) {
                    return { handled: true, response: this.error(e.message, 500) };
                }
            } else {
                 return { handled: true, response: this.error('Protocol service not available', 503) };
            }
        }

        return { handled: false };
    }

    /**
     * Handles Automation requests
     * path: sub-path after /automation/
     *
     * Routes:
     *   GET    /                     → listFlows
     *   GET    /actions              → getActionDescriptors (ADR-0018; ?paradigm/?source/?category filters)
     *   GET    /connectors           → getConnectorDescriptors (ADR-0022; ?type filter)
     *   GET    /:name                → getFlow
     *   POST   /                     → createFlow (registerFlow)
     *   PUT    /:name                → updateFlow
     *   DELETE /:name                → deleteFlow (unregisterFlow)
     *   POST   /:name/trigger        → execute (legacy: trigger/:name also supported)
     *   POST   /:name/toggle         → toggleFlow
     *   GET    /:name/runs           → listRuns
     *   GET    /:name/runs/:runId    → getRun
     *   POST   /:name/runs/:runId/resume → resume a paused run (screen input / ADR-0019)
     *   GET    /:name/runs/:runId/screen → the screen a paused run awaits
     */
    async handleAutomation(path: string, method: string, body: any, context: HttpProtocolContext, query?: any): Promise<HttpDispatcherResult> {
        const automationService = await this.getService(CoreServiceName.enum.automation);
        if (!automationService) return { handled: false };

        const m = method.toUpperCase();
        const parts = path.replace(/^\/+/, '').split('/').filter(Boolean);

        // Legacy: POST /automation/trigger/:name
        if (parts[0] === 'trigger' && parts[1] && m === 'POST') {
             const triggerName = parts[1];
             if (typeof automationService.trigger === 'function') {
                 const result = await automationService.trigger(triggerName, body, { request: context.request });
                 return { handled: true, response: this.success(result) };
             }
             // Fallback to execute
             if (typeof automationService.execute === 'function') {
                 const result = await automationService.execute(triggerName, body);
                 return { handled: true, response: this.success(result) };
             }
        }

        // GET / → listFlows
        if (parts.length === 0 && m === 'GET') {
            if (typeof automationService.listFlows === 'function') {
                const names = await automationService.listFlows();
                return { handled: true, response: this.success({ flows: names, total: names.length, hasMore: false }) };
            }
        }

        // POST / → createFlow
        if (parts.length === 0 && m === 'POST') {
            if (typeof automationService.registerFlow === 'function') {
                automationService.registerFlow(body?.name, body);
                return { handled: true, response: this.success(body) };
            }
        }

        // GET /actions → list registered action descriptors (ADR-0018).
        // MUST precede the `/:name → getFlow` catch-all below, otherwise a
        // flow lookup for a flow literally named "actions" would shadow it.
        // Backs the designer palette + flow validation; the registry is open
        // and marketplace-extensible (built-in + plugin-contributed actions).
        if (parts[0] === 'actions' && parts.length === 1 && m === 'GET') {
            if (typeof automationService.getActionDescriptors === 'function') {
                let actions = automationService.getActionDescriptors() ?? [];
                // Optional filters mirror descriptor fields.
                if (query?.paradigm) {
                    actions = actions.filter((a: any) => Array.isArray(a?.paradigms) && a.paradigms.includes(query.paradigm));
                }
                if (query?.source) {
                    actions = actions.filter((a: any) => a?.source === query.source);
                }
                if (query?.category) {
                    actions = actions.filter((a: any) => a?.category === query.category);
                }
                return { handled: true, response: this.success({ actions, total: actions.length }) };
            }
            // Service present but does not implement the optional method:
            // report an empty (but valid) registry rather than a 404.
            return { handled: true, response: this.success({ actions: [], total: 0 }) };
        }

        // GET /connectors → list registered connector descriptors (ADR-0022).
        // Like /actions, MUST precede the `/:name → getFlow` catch-all so a flow
        // named "connectors" cannot shadow it. Backs the designer's
        // `connector_action` connector/action/input pickers; the registry is
        // empty in baseline and populated by connector plugins (e.g.
        // @objectstack/connector-rest, @objectstack/connector-slack).
        if (parts[0] === 'connectors' && parts.length === 1 && m === 'GET') {
            if (typeof automationService.getConnectorDescriptors === 'function') {
                let connectors = automationService.getConnectorDescriptors() ?? [];
                // Optional filter mirrors the descriptor's connector type.
                if (query?.type) {
                    connectors = connectors.filter((c: any) => c?.type === query.type);
                }
                return { handled: true, response: this.success({ connectors, total: connectors.length }) };
            }
            // Service present but does not implement the optional method:
            // report an empty (but valid) registry rather than a 404.
            return { handled: true, response: this.success({ connectors: [], total: 0 }) };
        }

        // GET /_status → runtime enable/bound state for every flow (backs the
        // Studio's Automations status badges: persisted `status` is metadata, but
        // whether a flow is actually enabled + bound to its trigger is engine
        // state). Underscore-prefixed so no flow name can shadow it; MUST precede
        // the `/:name → getFlow` catch-all.
        if (parts[0] === '_status' && parts.length === 1 && m === 'GET') {
            const svc = automationService as { getFlowRuntimeStates?: () => Array<{ name: string; enabled: boolean; bound: boolean }> };
            if (typeof svc.getFlowRuntimeStates === 'function') {
                const flows = svc.getFlowRuntimeStates();
                return { handled: true, response: this.success({ flows, total: flows.length }) };
            }
            // Service present but older / does not implement the method.
            return { handled: true, response: this.success({ flows: [], total: 0 }) };
        }

        // Routes with :name
        if (parts.length >= 1) {
            const name = parts[0];

            // POST /:name/trigger → execute
            if (parts[1] === 'trigger' && m === 'POST') {
                if (typeof automationService.execute === 'function') {
                    const ctxBody = body && typeof body === 'object' ? body : {};
                    // Translate UI/SDK request shape `{recordId, objectName, params}`
                    // into the canonical AutomationContext shape expected by the engine.
                    // Key transformations:
                    //  - `recordId` is exposed in `params.recordId` AND aliased to
                    //    `<objectName>Id` (camelCase) so flow variables like `leadId`,
                    //    `caseId`, `opportunityId` resolve from a single REST contract.
                    //  - `objectName` is mapped to the canonical `object` field.
                    //  - The user identity from the auth context (if any) is forwarded
                    //    as `userId` so node executors / template interpolation can
                    //    expand `{$User.Id}`.
                    const recordId = ctxBody.recordId;
                    const objectName = ctxBody.objectName ?? ctxBody.object;
                    const baseParams = (ctxBody.params && typeof ctxBody.params === 'object') ? { ...ctxBody.params } : {};
                    // Back-compat: when callers POST a flat body (no `params` wrapper),
                    // forward unknown top-level keys as flow params so the original
                    // `{ foo: 'bar' }` payload is not silently dropped.
                    if (!ctxBody.params) {
                        const reserved = new Set(['recordId', 'objectName', 'object', 'event', 'params']);
                        for (const [k, v] of Object.entries(ctxBody)) {
                            if (reserved.has(k)) continue;
                            if (baseParams[k] === undefined) baseParams[k] = v;
                        }
                    }
                    if (recordId !== undefined && baseParams.recordId === undefined) {
                        baseParams.recordId = recordId;
                    }
                    if (recordId !== undefined && objectName) {
                        const alias = `${String(objectName).replace(/_([a-z])/g, (_: string, c: string) => c.toUpperCase())}Id`;
                        if (baseParams[alias] === undefined) baseParams[alias] = recordId;
                    }
                    const automationContext: any = {
                        params: baseParams,
                        object: objectName,
                        event: ctxBody.event ?? 'manual',
                    };
                    // Forward the FULLY-RESOLVED caller identity (not just the
                    // user id) so a `runAs:'user'` flow enforces RLS exactly as the
                    // triggering user — their roles/tenant, not a member fallback
                    // (#1888). The engine elevates to a system principal only when
                    // the flow itself declares `runAs:'system'`.
                    const ec = (context as any)?.executionContext;
                    const userIdFromAuth = (context as any)?.user?.id ?? (context as any)?.userId ?? ec?.userId;
                    if (userIdFromAuth) automationContext.userId = userIdFromAuth;
                    if (Array.isArray(ec?.positions) && ec.positions.length) automationContext.positions = ec.positions;
                    if (Array.isArray(ec?.permissions) && ec.permissions.length) automationContext.permissions = ec.permissions;
                    if (ec?.tenantId) automationContext.tenantId = ec.tenantId;
                    const result = await automationService.execute(name, automationContext);
                    return { handled: true, response: this.success(result) };
                }
            }

            // POST /:name/toggle → toggleFlow
            if (parts[1] === 'toggle' && m === 'POST') {
                if (typeof automationService.toggleFlow === 'function') {
                    await automationService.toggleFlow(name, body?.enabled ?? true);
                    return { handled: true, response: this.success({ name, enabled: body?.enabled ?? true }) };
                }
            }

            // POST /:name/runs/:runId/resume → resume a paused run (screen-flow
            // runtime / ADR-0019). Body `{ inputs }` = a screen node's collected
            // values, applied as bare flow variables; `output`/`branchLabel` also
            // forwarded for approval-style resumes. Returns the next paused
            // `{ screen }` (multi-screen) or the completed result.
            if (parts[1] === 'runs' && parts[2] && parts[3] === 'resume' && m === 'POST') {
                if (typeof automationService.resume === 'function') {
                    const b = (body && typeof body === 'object') ? body : {};
                    const inputs = (b.inputs ?? b.variables);
                    const signal: any = {};
                    if (inputs && typeof inputs === 'object') signal.variables = inputs;
                    if (b.output && typeof b.output === 'object') signal.output = b.output;
                    if (typeof b.branchLabel === 'string') signal.branchLabel = b.branchLabel;
                    const result = await automationService.resume(parts[2], signal);
                    return { handled: true, response: this.success(result) };
                }
                return { handled: true, response: this.error('Resume not supported', 501) };
            }

            // GET /:name/runs/:runId/screen → the screen a paused run awaits
            // (refresh-safe re-fetch for the UI flow-runner).
            if (parts[1] === 'runs' && parts[2] && parts[3] === 'screen' && m === 'GET') {
                if (typeof automationService.getSuspendedScreen === 'function') {
                    const screen = automationService.getSuspendedScreen(parts[2]);
                    if (!screen) return { handled: true, response: this.error('No pending screen for run', 404) };
                    return { handled: true, response: this.success({ runId: parts[2], screen }) };
                }
                return { handled: true, response: this.error('Screen lookup not supported', 501) };
            }

            // GET /:name/runs/:runId → getRun
            if (parts[1] === 'runs' && parts[2] && !parts[3] && m === 'GET') {
                if (typeof automationService.getRun === 'function') {
                    const run = await automationService.getRun(parts[2]);
                    if (!run) return { handled: true, response: this.error('Execution not found', 404) };
                    return { handled: true, response: this.success(run) };
                }
            }

            // GET /:name/runs → listRuns
            if (parts[1] === 'runs' && !parts[2] && m === 'GET') {
                if (typeof automationService.listRuns === 'function') {
                    const options = query ? { limit: query.limit ? Number(query.limit) : undefined, cursor: query.cursor } : undefined;
                    const runs = await automationService.listRuns(name, options);
                    return { handled: true, response: this.success({ runs, hasMore: false }) };
                }
            }

            // GET /:name → getFlow (no sub-path)
            if (parts.length === 1 && m === 'GET') {
                if (typeof automationService.getFlow === 'function') {
                    const flow = await automationService.getFlow(name);
                    if (!flow) return { handled: true, response: this.error('Flow not found', 404) };
                    return { handled: true, response: this.success(flow) };
                }
            }

            // PUT /:name → updateFlow
            if (parts.length === 1 && m === 'PUT') {
                if (typeof automationService.registerFlow === 'function') {
                    automationService.registerFlow(name, body?.definition ?? body);
                    return { handled: true, response: this.success(body?.definition ?? body) };
                }
            }

            // DELETE /:name → deleteFlow
            if (parts.length === 1 && m === 'DELETE') {
                if (typeof automationService.unregisterFlow === 'function') {
                    automationService.unregisterFlow(name);
                    return { handled: true, response: this.success({ name, deleted: true }) };
                }
            }
        }
        
        return { handled: false };
    }

    private getServicesMap(): Record<string, any> {
        if (this.kernel.services instanceof Map) {
            return Object.fromEntries(this.kernel.services);
        }
        return this.kernel.services || {};
    }

    private async getService(name: CoreServiceName) {
        return this.resolveService(name);
    }

    /**
     * Resolve any service by name, supporting async factories.
     * Fallback chain: getServiceAsync(scopeId) → getServiceAsync → getService (sync) → context.getService → services map.
     * Only returns when a non-null service is found; otherwise falls through to the next step.
     *
     * When `scopeId` is provided, tries the SCOPED factory on `defaultKernel` first (SharedProjectPlugin
     * mode). Falls back to the current `kernel` for singleton / legacy services.
     */
    private async resolveService(name: string, scopeId?: string) {
        // Prefer scoped lookup on defaultKernel when scopeId is given (shared-kernel / multi-environment mode)
        if (scopeId && typeof this.defaultKernel.getServiceAsync === 'function') {
            try {
                const svc = await this.defaultKernel.getServiceAsync(name, scopeId);
                if (svc != null) return svc;
            } catch {
                // Not a scoped service — fall through to singleton resolution
            }
        }
        // Prefer async resolution to support factory-based services (e.g. auth, analytics, protocol)
        if (typeof this.kernel.getServiceAsync === 'function') {
            try {
                const svc = await this.kernel.getServiceAsync(name);
                if (svc != null) return svc;
            } catch {
                // Service not registered or async resolution failed — fall through
            }
        }
        if (typeof this.kernel.getService === 'function') {
            try {
                const svc = await this.kernel.getService(name);
                if (svc != null) return svc;
            } catch {
                // Service not registered or sync resolution threw "is async" — fall through
            }
        }
        if (this.kernel?.context?.getService) {
            try {
                const svc = await this.kernel.context.getService(name);
                if (svc != null) return svc;
            } catch {
                // Service not registered — fall through
            }
        }
        const services = this.getServicesMap();
        return services[name];
    }

    /**
     * Get the ObjectQL service which provides access to SchemaRegistry.
     * Tries multiple access patterns since kernel structure varies.
     */
    private async getObjectQLService(scopeId?: string): Promise<any> {
        // 1. Try via resolveService (handles scoped, async factories, sync, context, and map)
        try {
            const svc = await this.resolveService('objectql', scopeId);
            if (svc?.registry) return svc;
        } catch { /* service not available */ }
        return null;
    }

    /**
     * Handle action invocation routes (`/actions/...`).
     *
     * Dispatches a named, server-registered action handler (registered via
     * `engine.registerAction(objectName, actionName, handler)`) over HTTP.
     * Three URL shapes are accepted to keep the client contract flexible:
     *
     *  - `POST /actions/:object/:action`              — record-scoped action
     *  - `POST /actions/:object/:action/:recordId`    — record-scoped action with id in URL
     *  - `POST /actions/global/:action`               — wildcard ("*") action
     *
     * Body shape: `{ recordId?: string, params?: Record<string, unknown> }`.
     * The handler is invoked with an `ActionContext` of:
     *   `{ record, user, engine, params }`
     * where `engine` exposes the slimmed CRUD surface used by CRM handlers
     * (`insert`, `update`, `delete`, `find`).
     */
    async handleActions(path: string, method: string, body: any, _context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        if (method.toUpperCase() !== 'POST') {
            return { handled: true, response: this.error('Method not allowed', 405) };
        }
        const parts = path.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
        if (parts.length < 2) {
            return { handled: true, response: this.error('Path must be /actions/:object/:action', 400) };
        }
        const objectName = parts[0];
        const actionName = parts[1];
        const recordIdFromPath = parts[2];

        // Resolve project scope so the right project kernel's ObjectQL is
        // used. For bare URLs the URL prefix already stripped any `/projects/:id`
        // segment, so fall back to the single-environment default if unset.
        if (!_context.environmentId) {
            const def = this.resolveDefaultProject();
            if (def?.environmentId) _context.environmentId = def.environmentId;
        }

        // Kernel-resolution fallback for the per-project kernel. HTTP action
        // routes now flow through `dispatcher.dispatch()` (like data/meta/
        // automation), which already swapped to the project kernel and resolved
        // `executionContext` before reaching here — so on that path this block
        // re-resolves idempotently (a no-op in single-kernel mode). Kept for
        // DIRECT `handleActions` callers (unit tests / internal dispatch) so the
        // call still lands on the kernel where the bundle's actions are
        // registered, not the control-plane kernel (ADR-0006 Phase 5).
        let projectQl: any = null;
        if (this.kernelResolver && _context.environmentId && _context.environmentId !== 'platform') {
            try {
                const projectKernel: any = await this.kernelResolver.resolveKernel(_context, this.defaultKernel);
                if (projectKernel) {
                    this.kernel = projectKernel;
                    // Resolve the project kernel's own ObjectQL DIRECTLY so we
                    // bypass the control-plane's scoped factory (which would
                    // hand back a different instance with no registered
                    // actions/hooks for this project's bundle).
                    if (typeof projectKernel.getServiceAsync === 'function') {
                        projectQl = await projectKernel.getServiceAsync('objectql').catch(() => null);
                    }
                }
            } catch {
                // fall back to defaultKernel — getObjectQLService will report
                // "Data engine not available" if no engine is reachable.
            }
        }

        const ql: any = projectQl ?? await this.getObjectQLService(_context?.environmentId);
        if (!ql || typeof ql.executeAction !== 'function') {
            return { handled: true, response: this.error('Data engine not available', 503) };
        }

        // [ADR-0066 D4] Dual-surface action gate — the server is the source of
        // truth. Resolve the action's declared `requiredPermissions` from the
        // object schema and reject (403) when the caller's systemPermissions
        // don't cover them. The objectui ActionRunner hides/disables the same
        // action from the identical declaration, so a UI-hidden action is also
        // server-closed (and the inverse footgun is removed). System/engine
        // self-invocation (isSystem) bypasses; an unauthenticated caller holds
        // no capabilities and is therefore denied for a gated action.
        try {
            const actionSchema: any =
                (typeof ql.getSchema === 'function' ? ql.getSchema(objectName) : undefined) ??
                ql.registry?.getObject?.(objectName);
            const actionDef: any = Array.isArray(actionSchema?.actions)
                ? actionSchema.actions.find((a: any) => a?.name === actionName)
                : undefined;
            const gateError = this.actionPermissionError(actionDef, _context?.executionContext, objectName);
            if (gateError) {
                return { handled: true, response: this.error(gateError, 403) };
            }
        } catch {
            /* schema unresolved → no declared gate to enforce (handler-only action) */
        }

        // Resolve the handler — fall back to wildcard '*' if the object-specific key is missing.
        // Since engine.executeAction throws when the key is unknown, we probe via the internal
        // map by attempting the call inside a try/catch and rotating to '*'.
        const tryExecute = async (obj: string) => {
            return ql.executeAction(obj, actionName, actionContext);
        };

        const reqBody = body && typeof body === 'object' ? body : {};
        const recordId = recordIdFromPath ?? reqBody.recordId;
        const reqParams = (reqBody.params && typeof reqBody.params === 'object') ? reqBody.params : {};

        // Load the record (best-effort) so handlers can rely on `ctx.record`.
        let record: Record<string, unknown> = {};
        if (recordId && objectName !== 'global') {
            try {
                const got = await this.callData('get', { object: objectName, id: recordId }, _context.dataDriver, _context.environmentId, _context.executionContext);
                if (got?.record) record = got.record;
            } catch { /* record may not exist for new-record actions; pass empty */ }
        }
        if (record && (record as any).id == null && recordId) (record as any).id = recordId;

        // Slim engine facade matching the ActionContext.engine shape used by CRM
        // handlers. ⚠️ TRUSTED — context-less, RLS/FLS-bypassing by design; see
        // buildActionEngineFacade for the full security-model rationale (#2849).
        const engineFacade = {
            async insert(object: string, data: Record<string, unknown>): Promise<{ id: string }> {
                const res = await ql.insert(object, data);
                const id = (res && (res as any).id) ?? (data as any).id;
                return { id };
            },
            async update(object: string, id: string, data: Record<string, unknown>): Promise<void> {
                await ql.update(object, data, { where: { id } });
            },
            async delete(object: string, id: string): Promise<void> {
                await ql.delete(object, { where: { id } });
            },
            async find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>> {
                const opts = query && Object.keys(query).length ? { where: query } : undefined;
                const rows = await ql.find(object, opts as any);
                return Array.isArray(rows) ? rows : ((rows as any)?.value ?? []);
            },
        };

        // Resolve the caller identity from the request's ExecutionContext — the
        // single source `dispatch()` populates via `resolveExecutionContext`,
        // the same envelope the MCP `runAction` and record-change trigger paths
        // read. The action body sandbox receives the operator's id and business
        // roles (ADR-0090 `positions`, formerly `roles`) so a handler can branch
        // on identity and enforce ownership. Falls back to a `system` principal
        // only for a genuinely anonymous / self-invoked call (#2701).
        const ec: any = _context?.executionContext;
        const userFromAuth = ec?.userId
            ? {
                id: ec.userId,
                name: ec.userId,
                email: ec.email,
                roles: Array.isArray(ec.positions) ? ec.positions : [],
                positions: Array.isArray(ec.positions) ? ec.positions : [],
                permissions: Array.isArray(ec.permissions) ? ec.permissions : [],
                // `organizationId` is the blessed developer-facing name for the
                // caller's active org (matches columns + `current_user.organizationId`).
                // The deprecated `tenantId` alias (#3280) was removed in v11 (#3290).
                organizationId: ec.tenantId,
              }
            : { id: 'system', name: 'system', roles: [], positions: [], permissions: [] };

        const actionContext: any = {
            record,
            user: userFromAuth,
            session: this.buildActionSession(ec),
            engine: engineFacade,
            params: { ...reqParams, recordId, objectName },
        };

        // [#2849] Same trusted-mode elevation as the MCP path — keep it audible.
        console.info(
            `[action-audit] REST action '${objectName}/${actionName}' — body executes TRUSTED ` +
            `(context-less engine, RLS/FLS-bypassing) for user '${userFromAuth.id}'`,
        );

        try {
            // Try object-specific first; on "not found" error, fall back to wildcard.
            let result: any;
            try {
                result = await tryExecute(objectName);
            } catch (err: any) {
                const msg = String(err?.message ?? err ?? '');
                if (/not found/i.test(msg) && objectName !== '*') {
                    result = await tryExecute('*');
                } else {
                    throw err;
                }
            }
            return { handled: true, response: this.success({ success: true, data: result }) };
        } catch (err: any) {
            const full = err?.message ?? String(err);
            // The sandbox wraps a user throw as `<kind> '<name>' threw: <msg>` for
            // server logs; surface only the business `<msg>` (SandboxError.innerMessage)
            // to the client so an action's error toast reads as plain text instead of
            // leaking the debug prefix. Keep the full wrapper in the log for debugging.
            const inner: unknown = err?.innerMessage;
            const clientMsg = (typeof inner === 'string' && inner) ? inner : full;
            if (clientMsg !== full) console.error(`[action ${objectName}/${actionName}] ${full}`);
            return { handled: true, response: this.success({ success: false, error: clientMsg }) };
        }
    }

    /**
     * Handle AI service routes (/ai/chat, /ai/models, /ai/conversations, etc.)
     * Resolves the AI service and its built-in route handlers, then dispatches.
     */
    async handleAI(subPath: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        let aiService: any;
        try {
            aiService = await this.resolveService('ai');
        } catch {
            // AI service not registered
        }

        if (!aiService) {
            // The console polls `GET /ai/agents` on every navigation to decide
            // whether to show AI affordances. Reporting that as a 404 turns the
            // normal "no AI service configured" state (the open-source default —
            // service-ai is a Cloud/Enterprise package) into console error-log
            // spam on every page. An empty list conveys the same information
            // without looking like a fault. Every other /ai/* route still 404s.
            if (method === 'GET' && subPath === '/ai/agents') {
                return { handled: true, response: { status: 200, body: { agents: [] } } };
            }
            return {
                handled: true,
                response: {
                    status: 404,
                    body: { success: false, error: { message: 'AI service is not configured', code: 404 } },
                },
            };
        }

        // The AI service exposes route definitions via buildAIRoutes.
        // We match the request path against known AI route patterns.
        const fullPath = `/api/v1${subPath}`;

        // Build a simple param-extracting matcher for route patterns like /api/v1/ai/conversations/:id
        const matchRoute = (pattern: string, path: string): Record<string, string> | null => {
            const patternParts = pattern.split('/');
            const pathParts = path.split('/');
            if (patternParts.length !== pathParts.length) return null;
            const params: Record<string, string> = {};
            for (let i = 0; i < patternParts.length; i++) {
                if (patternParts[i].startsWith(':')) {
                    params[patternParts[i].substring(1)] = pathParts[i];
                } else if (patternParts[i] !== pathParts[i]) {
                    return null;
                }
            }
            return params;
        };

        // Try to get route definitions from the AI service's cached routes
        const routes = (this.kernel as any).__aiRoutes as Array<{
            method: string; path: string; handler: (req: any) => Promise<any>; auth?: boolean;
        }> | undefined;

        if (!routes) {
            return {
                handled: true,
                response: {
                    status: 503,
                    body: { success: false, error: { message: 'AI service routes not yet initialized', code: 503 } },
                },
            };
        }

        for (const route of routes) {
            if (route.method !== method) continue;
            const params = matchRoute(route.path, fullPath);
            if (params === null) continue;

            // Enforce the route's declared `auth` contract. Nothing upstream
            // does: `enforceAuthGate` only covers ADR-0069 password/MFA gates
            // and `enforceProjectMembership` bails when the request is
            // anonymous or unscoped — so without this an anonymous caller
            // reached `auth: true` handlers (e.g. GET /ai/status) and got the
            // adapter/model config back. Gate when the deployment requires
            // auth; an authenticated user (or an internal system context)
            // passes, matching the REST `enforceAuth` seam. Off → unchanged.
            if (route.auth !== false) {
                const gec: any = context.executionContext;
                // `requireAuth && route.auth !== false` is the AI-route contract;
                // the shared function owns the anonymous decision itself.
                if (shouldDenyAnonymous({ requireAuth: this.requireAuth, userId: gec?.userId, isSystem: gec?.isSystem })) {
                    return {
                        handled: true,
                        response: this.error(ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, { code: ANONYMOUS_DENY_CODE }),
                    };
                }
            }

            // Resolve `req.user` from the already-resolved ExecutionContext so
            // AI route handlers can attribute the call to the authenticated
            // actor (drives auto-titled conversations, permission-aware
            // tools, HITL conversation linkage, …). Falls back to undefined
            // for anonymous requests (only reachable when the deployment does
            // NOT require auth — the gate above rejects them otherwise).
            const ec: any = context.executionContext;
            // `ai_seat` is synthesized into ec.permissions by resolveExecutionContext
            // (the single, scope-correct source — security/resolve-execution-context.ts),
            // so it flows through here with no extra per-request lookup.
            const user = ec?.userId
                ? {
                    userId: ec.userId,
                    id: ec.userId,
                    displayName: ec.userDisplayName ?? ec.userName ?? ec.userId,
                    email: ec.userEmail,
                    roles: Array.isArray(ec.positions) ? ec.positions : [],
                    permissions: Array.isArray(ec.permissions) ? ec.permissions : [],
                    organizationId: ec.tenantId,
                }
                : undefined;

            const result = await route.handler({
                body,
                params,
                query,
                headers: context.request?.headers,
                user,
            });

            if (result.stream && result.events) {
                // Return a streaming result for the adapter to handle
                return {
                    handled: true,
                    result: {
                        type: 'stream',
                        contentType: result.vercelDataStream
                            ? 'text/plain; charset=utf-8'
                            : 'text/event-stream',
                        events: result.events,
                        vercelDataStream: result.vercelDataStream,
                        headers: {
                            'Content-Type': result.vercelDataStream
                                ? 'text/plain; charset=utf-8'
                                : 'text/event-stream',
                            'Cache-Control': 'no-cache',
                            'Connection': 'keep-alive',
                        },
                    },
                };
            }

            return {
                handled: true,
                response: {
                    status: result.status,
                    body: result.body,
                },
            };
        }

        return {
            handled: true,
            response: this.routeNotFound(subPath),
        };
    }

    /**
     * Share-link capability tokens — "anyone with the link" publication of a
     * single record (ADR-0047). Mirrors the per-env service-dispatch pattern
     * used by {@link handleI18n} / {@link handleAI}: the `shareLinks` service
     * is resolved from the request's environment kernel, so links live in (and
     * resolve against) the same per-environment database that owns the record.
     * This branch owns URL parsing and the auth/public split.
     *
     *   POST   /share-links                   → create a link (authenticated)
     *   GET    /share-links?object&recordId    → list the caller's links (authenticated)
     *   DELETE /share-links/:idOrToken         → revoke (authenticated)
     *   GET    /share-links/:token/resolve     → resolve token → record (PUBLIC)
     *   GET    /share-links/:token/messages    → ai_conversations messages (PUBLIC)
     *
     * The resolve / messages routes are intentionally public — the token IS
     * the authorisation. The underlying record is fetched with a SYSTEM
     * context (per-env RLS is bypassed because the token gates access), and
     * `redactFields` are stripped before the record leaves the server.
     */
    async handleShareLinks(
        subPath: string,
        method: string,
        body: any,
        query: any,
        context: HttpProtocolContext,
    ): Promise<HttpDispatcherResult> {
        const svc: any = await this.resolveService('shareLinks', context.environmentId);
        if (!svc) {
            return { handled: true, response: this.error('Sharing is not configured for this environment', 501) };
        }

        const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
        const m = method.toUpperCase();
        const parts = subPath.replace(/^\/+/, '').split('/').filter(Boolean);
        const ec: any = context.executionContext;
        const callerCtx = { userId: ec?.userId as string | undefined, tenantId: ec?.tenantId as string | undefined };

        const headerOf = (name: string): string | undefined => {
            const h = context.request?.headers;
            if (!h) return undefined;
            const v = typeof h.get === 'function' ? h.get(name) : (h[name] ?? h[name.toLowerCase()]);
            return Array.isArray(v) ? v[0] : (v ?? undefined);
        };
        const sendErr = (status: number, code: string, msg: string): HttpDispatcherResult => ({
            handled: true,
            response: this.error(msg, status, { code }),
        });
        // Engine for fetching the shared record + token probes — the same
        // per-env ObjectQL the shareLinks service is bound to.
        const getEngine = async (): Promise<any> => {
            // Read objectql from the request's RESOLVED (per-env) kernel — the
            // same engine SharingServicePlugin bound the shareLinks service to,
            // so the shared record + messages live in the SAME store as
            // sys_share_link. `resolveService('objectql', env)` can hand back a
            // different (host/scoped) engine that lacks the per-env rows.
            try {
                const k: any = this.kernel;
                const e = typeof k?.getServiceAsync === 'function'
                    ? await k.getServiceAsync('objectql')
                    : k?.getService?.('objectql');
                if (e) return e;
            } catch { /* fall through to scoped resolution */ }
            return this.resolveService('objectql', context.environmentId);
        };
        const asArray = (rows: any): any[] => (Array.isArray(rows) ? rows : Array.isArray(rows?.value) ? rows.value : []);
        const applyRedaction = (record: any, redactFields: string[]): any => {
            if (!record || typeof record !== 'object' || redactFields.length === 0) return record;
            const out: any = {};
            for (const [k, v] of Object.entries(record)) {
                if (redactFields.includes(k)) continue;
                out[k] = v;
            }
            return out;
        };

        try {
            // ── PUBLIC: resolve a token → record ──────────────────────────
            if (parts.length === 2 && parts[1] === 'resolve' && m === 'GET') {
                const token = decodeURIComponent(parts[0]);
                const signedInUserId = ec?.userId;
                const recipientEmail = typeof query?.email === 'string' ? query.email : undefined;
                const providedPassword =
                    typeof query?.password === 'string' ? (query.password as string) : headerOf('x-share-password');

                const resolved = await svc.resolveToken(token, { signedInUserId, recipientEmail, providedPassword });
                if (!resolved) {
                    // Probe the row to return a more useful status (401 vs 410 vs 404).
                    const engine = await getEngine();
                    const probe = engine
                        ? asArray(await engine.find('sys_share_link', { where: { token }, limit: 1, context: SYSTEM_CTX } as any))
                        : [];
                    const row = probe[0] ?? null;
                    const live = row && !row.revoked_at && (!row.expires_at || Date.parse(row.expires_at) > Date.now());
                    if (live && row.password_hash) {
                        return sendErr(401, providedPassword ? 'WRONG_PASSWORD' : 'NEEDS_PASSWORD',
                            providedPassword ? 'Incorrect password' : 'This link requires a password');
                    }
                    if (live && row.audience === 'signed_in' && !signedInUserId) {
                        return sendErr(401, 'SIGN_IN_REQUIRED', 'Please sign in to view this link');
                    }
                    if (row && (row.revoked_at || (row.expires_at && Date.parse(row.expires_at) <= Date.now()))) {
                        return sendErr(410, 'EXPIRED_OR_REVOKED', 'Share link has expired or been revoked');
                    }
                    return sendErr(404, 'INVALID_OR_EXPIRED', 'Share link is invalid, expired, or revoked');
                }

                const engine = await getEngine();
                const rows = engine
                    ? asArray(await engine.find(resolved.link.object_name, { where: { id: resolved.link.record_id }, limit: 1, context: SYSTEM_CTX } as any))
                    : [];
                const record = rows[0] ?? null;
                if (!record) return sendErr(410, 'RECORD_GONE', 'The shared record no longer exists');

                return {
                    handled: true,
                    response: this.success({
                        record: applyRedaction(record, resolved.redactFields),
                        link: {
                            id: resolved.link.id,
                            token: resolved.link.token,
                            object_name: resolved.link.object_name,
                            record_id: resolved.link.record_id,
                            permission: resolved.link.permission,
                            audience: resolved.link.audience,
                            expires_at: resolved.link.expires_at,
                            label: resolved.link.label,
                            created_at: resolved.link.created_at,
                        },
                        redactFields: resolved.redactFields,
                    }),
                };
            }

            // ── PUBLIC: ai_conversations messages for a resolved token ────
            if (parts.length === 2 && parts[1] === 'messages' && m === 'GET') {
                const token = decodeURIComponent(parts[0]);
                const providedPassword =
                    typeof query?.password === 'string' ? (query.password as string) : headerOf('x-share-password');
                const resolved = await svc.resolveToken(token, { signedInUserId: ec?.userId, providedPassword });
                if (!resolved) return sendErr(404, 'NOT_FOUND', 'Share link not found');
                if (resolved.link.object_name !== 'ai_conversations') {
                    return sendErr(400, 'UNSUPPORTED', 'This share link does not expose messages');
                }
                const engine = await getEngine();
                const rows = engine
                    ? asArray(await engine.find('ai_messages', {
                        where: { conversation_id: resolved.link.record_id },
                        sort: [{ field: 'created_at', order: 'asc' }],
                        limit: 500,
                        context: SYSTEM_CTX,
                    } as any))
                    : [];
                return { handled: true, response: this.success(rows) };
            }

            // ── AUTHENTICATED: create / list / revoke ─────────────────────
            if (!callerCtx.userId) return sendErr(401, 'UNAUTHENTICATED', 'Sign in to manage share links');

            // POST /share-links → create
            if (parts.length === 0 && m === 'POST') {
                const b: any = body ?? {};
                if (!b.object || !b.recordId) return sendErr(400, 'VALIDATION_FAILED', 'object and recordId are required');
                const link = await svc.createLink(
                    {
                        object: b.object,
                        recordId: b.recordId,
                        permission: b.permission,
                        audience: b.audience,
                        expiresAt: b.expiresAt ?? null,
                        emailAllowlist: b.emailAllowlist,
                        password: b.password,
                        redactFields: b.redactFields,
                        label: b.label,
                    },
                    callerCtx,
                );
                return { handled: true, response: { status: 201, body: { success: true, data: link, link } } };
            }

            // GET /share-links?object&recordId → list the caller's own links
            if (parts.length === 0 && m === 'GET') {
                const links = await svc.listLinks(
                    {
                        object: typeof query?.object === 'string' ? query.object : undefined,
                        recordId: typeof query?.recordId === 'string' ? query.recordId : undefined,
                        // Constrain to links the caller created so a guessed
                        // recordId can never enumerate another user's tokens.
                        createdBy: callerCtx.userId,
                        includeRevoked: query?.includeRevoked === 'true' || query?.includeRevoked === '1',
                    },
                    callerCtx,
                );
                return { handled: true, response: { status: 200, body: { success: true, data: links, links } } };
            }

            // DELETE /share-links/:idOrToken → revoke
            if (parts.length === 1 && m === 'DELETE') {
                await svc.revokeLink(decodeURIComponent(parts[0]), callerCtx);
                return { handled: true, response: this.success({ ok: true }) };
            }

            return { handled: true, response: this.routeNotFound(`/share-links${subPath}`) };
        } catch (err: any) {
            return sendErr(err?.status ?? 500, err?.code ?? 'INTERNAL', err?.message ?? 'Share link request failed');
        }
    }

    /**
     * Main Dispatcher Entry Point
     * Routes the request to the appropriate handler based on path and precedence
     */
    async dispatch(method: string, path: string, body: any, query: any, context: HttpProtocolContext, prefix?: string): Promise<HttpDispatcherResult> {
        let cleanPath = path.replace(/\/$/, ''); // Remove trailing slash if present, but strict on clean paths

        // ── Environment Resolution + Multi-Kernel Routing (ADR-0006 Phase 5) ──
        // The host's KernelResolver owns the whole step: it resolves the
        // request to an environment (hostname / header / session / defaults —
        // strategy lives in the cloud distribution), SETS
        // `context.environmentId` (+ `dataDriver`), and returns the kernel to
        // serve from. The dispatcher only contributes parsing hints. No
        // resolver registered → single-environment: every request serves from
        // `defaultKernel` with no environment context.
        this.prepareResolverHints(context, cleanPath);
        if (this.kernelResolver) {
            this.kernel = (await this.kernelResolver.resolveKernel(context, this.defaultKernel)) ?? this.defaultKernel;
        } else {
            this.kernel = this.defaultKernel;
        }

        // Touch scope for TTL/LRU tracking in shared-kernel mode
        if (this.scopeManager && context.environmentId && context.environmentId !== 'platform') {
            this.scopeManager.touch(context.environmentId);
        }

        // ── Identity Resolution (RBAC/RLS/FLS context) ──
        // Resolve once per request; SecurityPlugin middleware reads
        // ctx.userId/roles/permissions/tenantId via opCtx.context.
        try {
            context.executionContext = await this.timedResolveExecutionContext({
                getService: (n: string) => this.resolveService(n, context.environmentId),
                // Resolve ObjectQL from the per-request kernel DIRECTLY. The scoped
                // `resolveService('objectql', envId)` factory can return a different
                // instance that doesn't see THIS env's rows (the gotcha
                // `handleActions` works around) — which made the api-key lookup miss
                // `sys_api_key` on the MCP path and reject valid keys with 401, while
                // REST accepted them (rest-server resolves identity via
                // `kernel.getServiceAsync('objectql')`). Resolving off `this.kernel`
                // keeps REST + MCP identity resolution aligned; falls back to the
                // scoped path when the kernel can't hand back an objectql directly.
                getQl: async () => {
                    const k: any = this.kernel;
                    if (k && typeof k.getServiceAsync === 'function') {
                        const ql = await k.getServiceAsync('objectql').catch(() => undefined);
                        if (ql && (ql.registry || typeof ql.find === 'function')) return ql;
                    }
                    return this.getObjectQLService(context.environmentId);
                },
                request: context.request,
                // OAuth 2.1 access tokens are honoured ONLY on the MCP
                // surface (#2698): their coarse tool-family scopes are
                // enforced at MCP tool dispatch, which other routes don't do.
                // Matches the plain and `/projects/:id`-scoped route forms
                // (the scoped prefix is stripped only later, below).
                acceptOAuthAccessToken: /^(?:\/projects\/[^/]+)?\/mcp(?:[/?]|$)/.test(cleanPath),
            });
        } catch {
            // anonymous request — leave executionContext undefined
        }

        // ── ADR-0069 Authentication-policy gate ──
        // Block a gated session (expired password / required MFA) from
        // protected MCP/GraphQL/data routes, mirroring the REST seam. The core
        // allow-list keeps auth + remediation reachable. Skipped (no session
        // lookup) when no gate feature is active.
        const authGated = await this.enforceAuthGate(context, cleanPath);
        if (authGated) {
            return { handled: true, response: authGated };
        }

        // ── Project Membership Enforcement ──
        // Once the environmentId is known, gate scoped data/meta/AI/automation
        // routes on `sys_environment_member`. Control-plane paths, the system
        // project, and platform-org members bypass this check.
        const forbidden = await this.enforceProjectMembership(context, cleanPath);
        if (forbidden) {
            return { handled: true, response: forbidden };
        }

        // Strip the `/environments/:environmentId` prefix so the protocol dispatchers
        // below (meta, data, ui, automation, …) see the same shape whether
        // the caller used host-based routing, `X-Environment-Id`, or a scoped URL.
        const scopedMatch = cleanPath.match(/^\/projects\/[^/]+(\/.*)?$/);
        if (scopedMatch) {
            cleanPath = scopedMatch[1] ?? '';
        }

        // 0. Discovery Endpoint (GET /discovery or GET /)
        // Standard route: /discovery (protocol-compliant)
        // Legacy route: / (empty path, for backward compatibility — MSW strips base URL)
        try {
        if ((cleanPath === '/discovery' || cleanPath === '') && method === 'GET') {
             const info = await this.getDiscoveryInfo(prefix ?? '');
             return { 
                 handled: true, 
                 response: this.success(info) 
             };
        }

        // 0b. Health Endpoint (GET /health)
        if (cleanPath === '/health' && method === 'GET') {
            return {
                handled: true,
                response: this.success({
                    status: 'ok',
                    timestamp: new Date().toISOString(),
                    version: '1.0.0',
                    uptime: typeof process !== 'undefined' ? process.uptime() : undefined,
                }),
            };
        }

        // 0b2. Readiness Endpoint (GET /ready) — k8s / load-balancer readiness probe.
        // 200 only when the kernel is fully running; 503 while booting
        // (idle/initializing) or shutting down (stopping/stopped) so a load
        // balancer stops routing to this replica BEFORE in-flight requests are
        // drained and the server closes (graceful rolling restart).
        if (cleanPath === '/ready' && method === 'GET') {
            const state: string = typeof (this.kernel as any)?.getState === 'function'
                ? (this.kernel as any).getState()
                : 'running';
            return state === 'running'
                ? { handled: true, response: this.success({ status: 'ready', state }) }
                : { handled: true, response: this.error('Service not ready', 503, { state }) };
        }

        // 0c. Plan-A diagnostics removed; the seed-replay and oauth2/callback
        // probes were temporary debugging tools used during the SSO rollout.

        // 1. System Protocols (Prefix-based)
        if (cleanPath.startsWith('/auth')) {
            return this.handleAuth(cleanPath.substring(5), method, body, context);
        }
        
        if (cleanPath.startsWith('/meta')) {
             return this.handleMetadata(cleanPath.substring(5), context, method, body, query);
        }

        if (cleanPath.startsWith('/data')) {
            return this.handleData(cleanPath.substring(5), method, body, query, context);
        }

        // `/mcp/skill` is the one sub-path NOT owned by the MCP transport:
        // the public, environment-customized SKILL.md download. Matched
        // before the transport branch below, which claims everything else
        // under `/mcp`.
        if (cleanPath === '/mcp/skill' || cleanPath.startsWith('/mcp/skill?')) {
            return this.handleMcpSkill(method, context);
        }

        if (cleanPath === '/mcp' || cleanPath.startsWith('/mcp/') || cleanPath.startsWith('/mcp?')) {
            return this.handleMcp(body, context);
        }

        if (cleanPath === '/keys' || cleanPath.startsWith('/keys/') || cleanPath.startsWith('/keys?')) {
            return this.handleKeys(method, body, context);
        }

        if (cleanPath.startsWith('/graphql')) {
             if (method === 'POST') return this.handleGraphQL(body, context);
             // GraphQL usually GET for Playground is handled by middleware but we can return 405 or handle it
        }

        if (cleanPath.startsWith('/storage')) {
             return this.handleStorage(cleanPath.substring(8), method, body, context); // body here is file/stream for upload
        }
        
        if (cleanPath.startsWith('/ui')) {
             return this.handleUi(cleanPath.substring(3), query, context);
        }

        if (cleanPath.startsWith('/automation')) {
             return this.handleAutomation(cleanPath.substring(11), method, body, context, query);
        }

        if (cleanPath.startsWith('/actions')) {
             return this.handleActions(cleanPath.substring(8), method, body, context);
        }
        
        if (cleanPath.startsWith('/analytics')) {
             return this.handleAnalytics(cleanPath.substring(10), method, body, context);
        }

        // In-app notifications (ADR-0030) — inbox list + receipt mark-read,
        // backed by the messaging service registered under the `notification` slot.
        if (cleanPath.startsWith('/notifications')) {
             return this.handleNotification(cleanPath.substring(14), method, body, query, context);
        }

        // Security admin surface (ADR-0090 D5/D9) — suggested audience
        // bindings, dispatched to the `security` service (plugin-security).
        if (cleanPath === '/security' || cleanPath.startsWith('/security/')) {
             return this.handleSecurity(cleanPath.substring(9), method, body, query, context);
        }

        if (cleanPath.startsWith('/packages')) {
             return this.handlePackages(cleanPath.substring(9), method, body, query, context);
        }

        if (cleanPath.startsWith('/i18n')) {
             return this.handleI18n(cleanPath.substring(5), method, query, context);
        }

        // AI Service — delegate to the registered AI route handlers
        if (cleanPath.startsWith('/ai')) {
             return this.handleAI(cleanPath, method, body, query, context);
        }

        // Share links — capability-token record sharing, dispatched to the
        // per-env `shareLinks` service (links + record live in the same kernel).
        if (cleanPath === '/share-links' || cleanPath.startsWith('/share-links/')) {
             return this.handleShareLinks(cleanPath.substring('/share-links'.length), method, body, query, context);
        }

        // OpenAPI Specification
        if (cleanPath === '/openapi.json' && method === 'GET') {
             try {
                const metaSvc = await this.resolveService('metadata', context.environmentId);
                if (metaSvc && typeof (metaSvc as any).generateOpenApi === 'function') {
                    const result = await (metaSvc as any).generateOpenApi({});
                    return { handled: true, response: this.success(result) };
                }
             } catch (e) {
                // If not implemented, fall through or return 404
             }
        }

        // 2. Custom API Endpoints (Registry lookup)
        // Check if there is a custom endpoint defined for this path
        const result = await this.handleApiEndpoint(cleanPath, method, body, query, context);
        if (result.handled) return result;

        // 3. Fallback — return semantic 404 with diagnostic info
        return {
            handled: true,
            response: this.routeNotFound(cleanPath),
        };
        } catch (e) {
            if (isPermissionDeniedError(e)) {
                return {
                    handled: true,
                    response: this.error(e.message, 403, { code: 'PERMISSION_DENIED', ...(e.details ?? {}) }),
                };
            }
            throw e;
        }
    }

    /**
     * Handles Custom API Endpoints defined in metadata
     */
    async handleApiEndpoint(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
        try {
            // Attempt to find a matching endpoint in the registry
            const metaSvc = await this.resolveService('metadata', context.environmentId);
            if (!metaSvc || typeof (metaSvc as any).matchEndpoint !== 'function') {
                return { handled: false };
            }
            const endpoint = await (metaSvc as any).matchEndpoint({ path, method });
            
            if (endpoint) {
                // Execute the endpoint target logic
                if (endpoint.type === 'flow') {
                    const automationSvc = await this.resolveService('automation');
                    if (!automationSvc || typeof (automationSvc as any).runFlow !== 'function') {
                        return { handled: true, response: this.error('Automation service not available', 503) };
                    }
                    const result = await (automationSvc as any).runFlow({ 
                        flowId: endpoint.target, 
                        inputs: { ...query, ...body, _request: context.request } 
                    });
                     return { handled: true, response: this.success(result) };
                }
                
                if (endpoint.type === 'script') {
                    const automationSvc = await this.resolveService('automation');
                    if (!automationSvc || typeof (automationSvc as any).runScript !== 'function') {
                        return { handled: true, response: this.error('Automation service not available', 503) };
                    }
                     const result = await (automationSvc as any).runScript({ 
                        scriptName: endpoint.target, 
                        context: { ...query, ...body, request: context.request } 
                    });
                     return { handled: true, response: this.success(result) };
                }

                if (endpoint.type === 'object_operation') {
                    // e.g. Proxy to an object action
                    if (endpoint.objectParams) {
                        const { object, operation } = endpoint.objectParams;
                        // Map standard CRUD operations
                        if (operation === 'find') {
                             const result = await this.callData('query', { object, query });
                             // Spec: FindDataResponse = { object, records, total?, hasMore? }
                             return { handled: true, response: this.success(result.records, { total: result.total }) };
                        }
                        if (operation === 'get' && query.id) {
                             const result = await this.callData('get', { object, id: query.id });
                             return { handled: true, response: this.success(result) };
                        }
                         if (operation === 'create') {
                             const result = await this.callData('create', { object, data: body });
                             return { handled: true, response: this.success(result) };
                        }
                    }
                }

                if (endpoint.type === 'proxy') {
                     return { 
                         handled: true, 
                         response: { 
                             status: 200, 
                             body: { proxy: true, target: endpoint.target, note: 'Proxy execution requires http-client service' } 
                         } 
                     };
                }
            }
        } catch (e) {
            // If matchEndpoint fails (e.g. not found), we just return not handled
            // so we can fallback to 404 or other handlers
        }

        return { handled: false };
    }
}