@unifiedcommerce/core 0.0.1

package/dist/kernel/local-api.js

@@ -0,0 +1,87 @@
+// ─── Implementation ─────────────────────────────────────────────────────────
+const SERVICE_METHOD_CACHE = new WeakMap();
+/**
+ * Create a proxy-based local API over kernel services.
+ * Every service method gets `actor` and `txCtx` auto-injected.
+ */
+export function createLocalAPI(kernel, options = {}) {
+    const actor = options.actor ?? null;
+    const txCtx = options.tx != null
+        ? {
+            tx: options.tx,
+            actor,
+            requestId: options.requestId ?? crypto.randomUUID(),
+        }
+        : undefined;
+    // Top-level proxy: intercept service access (e.g., api.catalog, api.giftCards)
+    return new Proxy(kernel.services, {
+        get(target, serviceName) {
+            const service = target[serviceName];
+            // Non-object services (e.g., email config) — return as-is
+            if (service == null || typeof service !== "object") {
+                return service;
+            }
+            // Method-level proxy: intercept method calls on the service
+            return new Proxy(service, {
+                get(svcTarget, methodName) {
+                    const method = svcTarget[methodName];
+                    if (typeof method !== "function") {
+                        return method;
+                    }
+                    // Check cache to avoid re-creating wrapper functions
+                    let methodCache = SERVICE_METHOD_CACHE.get(svcTarget);
+                    if (!methodCache) {
+                        methodCache = new Map();
+                        SERVICE_METHOD_CACHE.set(svcTarget, methodCache);
+                    }
+                    const cacheKey = `${methodName}:${actor?.userId ?? "null"}`;
+                    let cached = methodCache.get(cacheKey);
+                    if (cached)
+                        return cached;
+                    // Create wrapped method that auto-injects actor + txCtx
+                    cached = (...args) => {
+                        return method.call(svcTarget, ...args, actor, txCtx);
+                    };
+                    methodCache.set(cacheKey, cached);
+                    return cached;
+                },
+            });
+        },
+    });
+}
+// ─── Legacy Class API (backward compat) ─────────────────────────────────────
+/**
+ * @deprecated Use `createLocalAPI(kernel, { actor, tx })` instead.
+ * Kept for backward compatibility with existing hook code.
+ */
+export class LocalAPI {
+    _proxy;
+    constructor(ctx, kernel) {
+        this._proxy = createLocalAPI(kernel, {
+            actor: ctx.actor,
+            tx: ctx.tx,
+            requestId: ctx.requestId,
+        });
+    }
+    get orders() { return this._proxy.orders; }
+    get catalog() { return this._proxy.catalog; }
+    get cart() { return this._proxy.cart; }
+    get inventory() { return this._proxy.inventory; }
+    get customers() { return this._proxy.customers; }
+    get pricing() { return this._proxy.pricing; }
+    get promotions() { return this._proxy.promotions; }
+    get media() { return this._proxy.media; }
+    get shipping() { return this._proxy.shipping; }
+    get search() { return this._proxy.search; }
+    get webhooks() { return this._proxy.webhooks; }
+    get fulfillment() { return this._proxy.fulfillment; }
+    get payments() { return this._proxy.payments; }
+    get analytics() { return this._proxy.analytics; }
+    get tax() { return this._proxy.tax; }
+    get audit() { return this._proxy.audit; }
+    get organization() { return this._proxy.organization; }
+    /** Access any service (including plugins) by name */
+    service(name) {
+        return this._proxy[name];
+    }
+}

package/dist/kernel/plugin/capability-registry.d.ts

@@ -0,0 +1,9 @@
+import type { CommercePluginManifest } from "./manifest";
+export type CapabilityHandler = unknown;
+export declare class PluginCapabilityRegistry {
+    private registry;
+    register(manifest: CommercePluginManifest, capabilities: Record<string, CapabilityHandler>): void;
+    get<TCapability = unknown>(key: string): TCapability | undefined;
+    list(): string[];
+}
+//# sourceMappingURL=capability-registry.d.ts.map

package/dist/kernel/plugin/capability-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../../src/kernel/plugin/capability-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAUxC,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAwC;IAExD,QAAQ,CACN,QAAQ,EAAE,sBAAsB,EAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAC9C,IAAI;IAeP,GAAG,CAAC,WAAW,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIhE,IAAI,IAAI,MAAM,EAAE;CAGjB"}

package/dist/kernel/plugin/capability-registry.js

@@ -0,0 +1,28 @@
+function majorVersion(version) {
+    const parsed = Number.parseInt(version.split(".")[0] ?? "1", 10);
+    if (Number.isNaN(parsed) || parsed < 0) {
+        return "1";
+    }
+    return String(parsed);
+}
+export class PluginCapabilityRegistry {
+    registry = new Map();
+    register(manifest, capabilities) {
+        const major = majorVersion(manifest.version);
+        for (const [name, handler] of Object.entries(capabilities)) {
+            const normalized = name.includes("/")
+                ? name
+                : `${manifest.id}/${name}@${major}`;
+            if (this.registry.has(normalized)) {
+                throw new Error(`Capability key collision: \"${normalized}\".`);
+            }
+            this.registry.set(normalized, handler);
+        }
+    }
+    get(key) {
+        return this.registry.get(key);
+    }
+    list() {
+        return [...this.registry.keys()].sort();
+    }
+}

package/dist/kernel/plugin/dependency-graph.d.ts

@@ -0,0 +1,6 @@
+import type { CommercePluginManifest } from "./manifest";
+export declare class PluginDependencyError extends Error {
+    constructor(message: string);
+}
+export declare function resolvePluginInitializationOrder(manifests: CommercePluginManifest[]): CommercePluginManifest[];
+//# sourceMappingURL=dependency-graph.d.ts.map

package/dist/kernel/plugin/dependency-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../../../src/kernel/plugin/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,gCAAgC,CAC9C,SAAS,EAAE,sBAAsB,EAAE,GAClC,sBAAsB,EAAE,CA6D1B"}

package/dist/kernel/plugin/dependency-graph.js

@@ -0,0 +1,55 @@
+export class PluginDependencyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PluginDependencyError";
+    }
+}
+export function resolvePluginInitializationOrder(manifests) {
+    const byId = new Map();
+    for (const manifest of manifests) {
+        if (byId.has(manifest.id)) {
+            throw new PluginDependencyError(`Duplicate plugin id \"${manifest.id}\".`);
+        }
+        byId.set(manifest.id, manifest);
+    }
+    const indegree = new Map();
+    const edges = new Map();
+    for (const manifest of manifests) {
+        indegree.set(manifest.id, 0);
+        edges.set(manifest.id, []);
+    }
+    for (const manifest of manifests) {
+        for (const dependency of manifest.dependsOn ?? []) {
+            if (!byId.has(dependency)) {
+                throw new PluginDependencyError(`Plugin \"${manifest.id}\" depends on missing plugin \"${dependency}\".`);
+            }
+            edges.get(dependency).push(manifest.id);
+            indegree.set(manifest.id, (indegree.get(manifest.id) ?? 0) + 1);
+        }
+    }
+    const queue = [...indegree.entries()]
+        .filter(([, degree]) => degree === 0)
+        .map(([pluginId]) => pluginId)
+        .sort();
+    const ordered = [];
+    while (queue.length > 0) {
+        const pluginId = queue.shift();
+        ordered.push(byId.get(pluginId));
+        for (const child of edges.get(pluginId) ?? []) {
+            const next = (indegree.get(child) ?? 0) - 1;
+            indegree.set(child, next);
+            if (next === 0) {
+                queue.push(child);
+                queue.sort();
+            }
+        }
+    }
+    if (ordered.length !== manifests.length) {
+        const stuck = [...indegree.entries()]
+            .filter(([, degree]) => degree > 0)
+            .map(([id]) => id)
+            .sort();
+        throw new PluginDependencyError(`Plugin dependency cycle detected among: ${stuck.join(", ")}.`);
+    }
+    return ordered;
+}

package/dist/kernel/plugin/manifest.d.ts

@@ -0,0 +1,90 @@
+import type { RouteConfig } from "@hono/zod-openapi";
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import type { CommerceConfig, CommercePlugin, MCPTool } from "../../config/types";
+export interface PluginLogger {
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/**
+ * Plugin route registration. Supports two modes:
+ *
+ * 1. Legacy: { method, path, handler } — works, but invisible to OpenAPI spec.
+ * 2. OpenAPI: { openapi, handler } — validated by Zod, appears in /api/doc.
+ *
+ * Use mode 2 for any route that accepts a request body or returns structured data.
+ * Mode 1 is acceptable for simple routes (health checks, redirects, file serving).
+ */
+export type PluginRouteRegistration = {
+    method: string;
+    path: string;
+    handler: (...args: unknown[]) => unknown;
+} | {
+    openapi: RouteConfig;
+    handler: (...args: unknown[]) => unknown;
+};
+export interface PluginHookRegistration {
+    key: string;
+    handler: (...args: unknown[]) => unknown;
+}
+export interface PluginContext {
+    config: CommerceConfig;
+    services: Record<string, unknown>;
+    database: {
+        /** Drizzle database instance — use for queries, inserts, updates, deletes */
+        db: PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
+        transaction<T>(fn: (tx: PgDatabase<PgQueryResultHKT, Record<string, unknown>>) => Promise<T>): Promise<T>;
+    };
+    logger: PluginLogger;
+}
+/**
+ * Permission scope declared by a plugin.
+ * Collected at boot time and available via GET /api/admin/permissions.
+ */
+export interface PluginPermission {
+    /** Permission scope string, e.g., "wishlist:write", "marketplace:admin" */
+    scope: string;
+    /** Human-readable description for admin UIs */
+    description: string;
+}
+export interface CommercePluginManifest {
+    id: string;
+    version: string;
+    /**
+     * IDs of plugins that must be registered before this one.
+     * If any required plugin is missing at registration time,
+     * defineCommercePlugin will throw with a clear message.
+     */
+    requires?: string[];
+    /**
+     * Permission scopes this plugin introduces.
+     * Used by admin UIs to build role editors, and validated at boot time
+     * against .permission() calls in routes.
+     */
+    permissions?: PluginPermission[];
+    /**
+     * Returns Drizzle `pgTable` objects that this plugin needs.
+     * These are collected into `config.customSchemas[]` and merged with core
+     * schema by `buildSchema(config)`. Each key becomes a named export in the
+     * merged schema; names must not collide with core table exports.
+     */
+    schema?: () => Record<string, unknown>;
+    hooks?: () => PluginHookRegistration[];
+    routes?: (ctx: PluginContext) => PluginRouteRegistration[];
+    mcpTools?: (ctx: PluginContext) => MCPTool[];
+    analyticsModels?: () => unknown[];
+}
+export declare const _registeredPlugins: Set<string>;
+/** @internal — called by defineConfig() before applying plugins */
+export declare function _resetRegisteredPlugins(): void;
+/**
+ * Converts a plugin manifest into a config transform function.
+ *
+ * - `schema` → pushed into `config.customSchemas`
+ * - `hooks` → merged into `config.hooks` flat map
+ * - `routes` → chained onto `config.routes` (evaluated at boot with kernel)
+ * - `mcpTools` → chained onto `config.mcpTools` (evaluated at boot with kernel)
+ * - `analyticsModels` → pushed into `config.analytics.models`
+ */
+export declare function defineCommercePlugin(manifest: CommercePluginManifest): CommercePlugin;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/kernel/plugin/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/kernel/plugin/manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,OAAO,EACR,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;CAAE,GAC1E;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CAC1C;AAID,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,EAAE;QACR,6EAA6E;QAC7E,EAAE,EAAE,UAAU,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1D,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,UAAU,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KAC3G,CAAC;IACF,MAAM,EAAE,YAAY,CAAC;CACtB;AAID;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,sBAAsB,EAAE,CAAC;IACvC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,uBAAuB,EAAE,CAAC;IAC3D,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,EAAE,CAAC;IAC7C,eAAe,CAAC,EAAE,MAAM,OAAO,EAAE,CAAC;CACnC;AAKD,eAAO,MAAM,kBAAkB,aAAoB,CAAC;AAEpD,mEAAmE;AACnE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,sBAAsB,GAC/B,cAAc,CA4IhB"}

package/dist/kernel/plugin/manifest.js

@@ -0,0 +1,140 @@
+// ─── Plugin Dependency Tracking ──────────────────────────────────────
+// Accumulates plugin IDs as they register during defineConfig().
+// Reset at the start of each defineConfig() call.
+export const _registeredPlugins = new Set();
+/** @internal — called by defineConfig() before applying plugins */
+export function _resetRegisteredPlugins() {
+    _registeredPlugins.clear();
+}
+/**
+ * Converts a plugin manifest into a config transform function.
+ *
+ * - `schema` → pushed into `config.customSchemas`
+ * - `hooks` → merged into `config.hooks` flat map
+ * - `routes` → chained onto `config.routes` (evaluated at boot with kernel)
+ * - `mcpTools` → chained onto `config.mcpTools` (evaluated at boot with kernel)
+ * - `analyticsModels` → pushed into `config.analytics.models`
+ */
+export function defineCommercePlugin(manifest) {
+    return (config) => {
+        // ── Dependency check ───────────────────────────────────────────
+        // In test/development, warn instead of throwing so plugins can be
+        // tested in isolation via createPluginTestApp() without installing
+        // all dependencies. In production, this is a hard error.
+        if (manifest.requires) {
+            for (const dep of manifest.requires) {
+                if (!_registeredPlugins.has(dep)) {
+                    const msg = `Plugin "${manifest.id}" requires "${dep}" to be installed before it. Add ${dep}Plugin() before ${manifest.id}Plugin() in your config.plugins array.`;
+                    if (process.env.NODE_ENV === "production") {
+                        throw new Error(msg);
+                    }
+                    // Non-production: log warning but continue (allows isolated testing)
+                    console.warn(`[plugin:${manifest.id}] WARNING: ${msg}`);
+                }
+            }
+        }
+        _registeredPlugins.add(manifest.id);
+        let result = { ...config };
+        // 1. Schema — push into customSchemas for kernel to register
+        if (manifest.schema) {
+            const schemas = manifest.schema();
+            result = {
+                ...result,
+                customSchemas: [...(result.customSchemas ?? []), schemas],
+            };
+        }
+        // 2. Hooks — merge into flat hooks map (kernel registers at boot)
+        if (manifest.hooks) {
+            const registrations = manifest.hooks();
+            const hookMap = {
+                ...(result.hooks ?? {}),
+            };
+            for (const reg of registrations) {
+                hookMap[reg.key] = [...(hookMap[reg.key] ?? []), reg.handler];
+            }
+            result = { ...result, hooks: hookMap };
+        }
+        // 3. Routes — chain onto config.routes (deferred: needs kernel at boot)
+        if (manifest.routes) {
+            const existingRoutes = result.routes;
+            const pluginRoutes = manifest.routes;
+            result = {
+                ...result,
+                routes: (app, kernel) => {
+                    existingRoutes?.(app, kernel);
+                    const k = kernel;
+                    const regs = pluginRoutes({
+                        config: k.config,
+                        services: k.services,
+                        database: k.database,
+                        logger: k.logger,
+                    });
+                    for (const route of regs) {
+                        // ── Error boundary: wrap handler with plugin context ──
+                        const originalHandler = route.handler;
+                        const wrappedHandler = async (...args) => {
+                            try {
+                                return await originalHandler(...args);
+                            }
+                            catch (err) {
+                                // Try to extract logger from Hono context
+                                const c = args[0];
+                                const logger = c?.get?.("logger");
+                                logger?.error?.({ err, plugin: manifest.id }, `[plugin:${manifest.id}] route handler error`);
+                                throw err; // re-throw so global handler still catches
+                            }
+                        };
+                        if ("openapi" in route) {
+                            // OpenAPI route: validated by Zod, appears in /api/doc
+                            // Hono type interop — OpenAPIHono.openapi() expects strict RouteConfig+Handler
+                            // generics that can't be statically resolved for dynamic plugin routes.
+                            // @ts-expect-error -- dynamic plugin routes cannot satisfy Hono's strict handler generics
+                            app.openapi(route.openapi, wrappedHandler);
+                        }
+                        else {
+                            // Legacy route: raw handler, invisible to OpenAPI spec
+                            const method = route.method.toLowerCase();
+                            const router = app;
+                            if (method in router) {
+                                router[method](route.path, wrappedHandler);
+                            }
+                        }
+                    }
+                },
+            };
+        }
+        // 4. MCP Tools — chain onto config.mcpTools (deferred: needs kernel)
+        if (manifest.mcpTools) {
+            const existingMcpTools = result.mcpTools;
+            const pluginMcpTools = manifest.mcpTools;
+            result = {
+                ...result,
+                mcpTools: (kernel) => {
+                    const existing = existingMcpTools?.(kernel) ?? [];
+                    const k = kernel;
+                    return [
+                        ...existing,
+                        ...pluginMcpTools({
+                            config: k.config,
+                            services: k.services,
+                            database: k.database,
+                            logger: k.logger,
+                        }),
+                    ];
+                },
+            };
+        }
+        // 5. Analytics models — push into config.analytics.models
+        if (manifest.analyticsModels) {
+            const models = manifest.analyticsModels();
+            result = {
+                ...result,
+                analytics: {
+                    ...result.analytics,
+                    models: [...(result.analytics?.models ?? []), ...models],
+                },
+            };
+        }
+        return result;
+    };
+}

package/dist/kernel/query/executor.d.ts

@@ -0,0 +1,21 @@
+import type { QueryRegistry } from "./registry";
+export interface QueryInput {
+    entity: string;
+    id?: string;
+    filters?: Record<string, unknown>;
+    include?: string[];
+    pagination?: {
+        limit?: number;
+        offset?: number;
+    };
+}
+export interface QueryResult<T = Record<string, unknown>> {
+    data: T[];
+    total?: number | undefined;
+}
+/**
+ * Executes a query against the registry, resolving includes via
+ * batched dataloader-style fetches (one WHERE IN per relation).
+ */
+export declare function executeQuery<T = Record<string, unknown>>(registry: QueryRegistry, services: Record<string, unknown>, input: QueryInput): Promise<QueryResult<T>>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/kernel/query/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/kernel/query/executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EAGd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAgDzB"}

package/dist/kernel/query/executor.js

@@ -0,0 +1,128 @@
+import { CommerceNotFoundError } from "../errors";
+/**
+ * Executes a query against the registry, resolving includes via
+ * batched dataloader-style fetches (one WHERE IN per relation).
+ */
+export async function executeQuery(registry, services, input) {
+    const definition = registry.get(input.entity);
+    if (!definition) {
+        throw new CommerceNotFoundError(`No entity registered with name "${input.entity}".`);
+    }
+    const service = services[definition.service];
+    // 1. Fetch primary records
+    let rows;
+    let total;
+    if (input.id) {
+        const result = (await service[definition.getByIdMethod](input.id));
+        const value = result?.value ?? result;
+        rows = value != null ? [value] : [];
+    }
+    else {
+        const result = (await service[definition.listMethod](input.filters ?? {}, input.pagination));
+        const resolved = result?.value ?? result;
+        if (resolved && typeof resolved === "object" && "items" in resolved) {
+            rows = (resolved.items ?? []);
+            total = resolved.total;
+        }
+        else if (Array.isArray(resolved)) {
+            rows = resolved;
+        }
+        else {
+            rows = [];
+        }
+    }
+    // 2. Resolve includes
+    if (input.include?.length) {
+        await resolveIncludes(rows, input.include, definition, services, registry);
+    }
+    return { data: rows, total };
+}
+async function resolveIncludes(rows, includes, definition, services, registry) {
+    // Group includes by top-level segment
+    const topLevel = new Map();
+    for (const path of includes) {
+        const dot = path.indexOf(".");
+        if (dot === -1) {
+            if (!topLevel.has(path))
+                topLevel.set(path, []);
+        }
+        else {
+            const parent = path.substring(0, dot);
+            const child = path.substring(dot + 1);
+            const existing = topLevel.get(parent) ?? [];
+            existing.push(child);
+            topLevel.set(parent, existing);
+        }
+    }
+    for (const [relationName, nestedIncludes] of topLevel) {
+        const relation = definition.relations[relationName];
+        if (!relation)
+            continue;
+        const targetService = services[relation.targetService];
+        if (!targetService)
+            continue;
+        // Collect foreign key values (deduplicated)
+        const ids = [
+            ...new Set(rows
+                .map((r) => r[relation.foreignKey])
+                .filter((v) => v != null && typeof v === "string")),
+        ];
+        if (ids.length === 0)
+            continue;
+        // One batched query
+        const batchFn = targetService[relation.batchMethod];
+        if (!batchFn)
+            continue;
+        const relatedResult = await batchFn(ids);
+        const relatedRows = extractRows(relatedResult);
+        // Build lookup
+        const map = new Map();
+        for (const related of relatedRows) {
+            const rec = related;
+            if (relation.isList) {
+                const key = rec[relation.foreignKey];
+                if (!map.has(key))
+                    map.set(key, []);
+                map.get(key).push(rec);
+            }
+            else {
+                map.set(rec["id"], rec);
+            }
+        }
+        // Attach to parent rows
+        for (const row of rows) {
+            const fkValue = row[relation.foreignKey];
+            if (!fkValue)
+                continue;
+            row[relation.attachAs] =
+                map.get(fkValue) ?? (relation.isList ? [] : null);
+        }
+        // Resolve nested includes
+        if (nestedIncludes.length > 0) {
+            const targetDef = registry.get(relation.targetService);
+            if (targetDef) {
+                const nestedRows = relation.isList
+                    ? rows.flatMap((r) => r[relation.attachAs] ?? [])
+                    : rows
+                        .map((r) => r[relation.attachAs])
+                        .filter(Boolean);
+                await resolveIncludes(nestedRows, nestedIncludes, targetDef, services, registry);
+            }
+        }
+    }
+}
+function extractRows(result) {
+    if (Array.isArray(result))
+        return result;
+    if (result && typeof result === "object") {
+        const r = result;
+        if (r.value != null) {
+            if (Array.isArray(r.value))
+                return r.value;
+            if (typeof r.value === "object" && "items" in r.value) {
+                return r.value.items;
+            }
+        }
+    }
+    return [];
+}

package/dist/kernel/query/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Defines a relation from a parent entity to a related entity.
+ * Used by the query executor to batch-load related records.
+ */
+export interface RelationDefinition {
+    foreignKey: string;
+    targetService: string;
+    batchMethod: string;
+    attachAs: string;
+    isList?: boolean;
+}
+/**
+ * Defines an entity that can be queried via kernel.query().
+ */
+export interface EntityDefinition {
+    service: string;
+    getByIdMethod: string;
+    listMethod: string;
+    relations: Record<string, RelationDefinition>;
+}
+/**
+ * Registry of queryable entities and their relations.
+ * Modules register their entities at kernel boot.
+ * Plugins can register additional entities.
+ */
+export declare class QueryRegistry {
+    private entities;
+    register(name: string, definition: EntityDefinition): void;
+    get(name: string): EntityDefinition | undefined;
+    has(name: string): boolean;
+    listEntities(): string[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/kernel/query/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/kernel/query/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC/C;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAuC;IAEvD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAI1D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAI/C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,YAAY,IAAI,MAAM,EAAE;CAGzB"}

package/dist/kernel/query/registry.js

@@ -0,0 +1,20 @@
+/**
+ * Registry of queryable entities and their relations.
+ * Modules register their entities at kernel boot.
+ * Plugins can register additional entities.
+ */
+export class QueryRegistry {
+    entities = new Map();
+    register(name, definition) {
+        this.entities.set(name, definition);
+    }
+    get(name) {
+        return this.entities.get(name);
+    }
+    has(name) {
+        return this.entities.has(name);
+    }
+    listEntities() {
+        return [...this.entities.keys()];
+    }
+}