@porulle/core 0.1.0

package/dist/kernel/local-api.d.ts

@@ -0,0 +1,104 @@
+import type { Actor } from "../auth/types.js";
+import type { Kernel } from "../runtime/kernel.js";
+/**
+ * Proxy-based Local API — the Payload-style programmatic interface.
+ *
+ * Exposes services registered on `kernel.services` without hardcoding method
+ * signatures. Uses a Proxy to intercept property access and wrap each service
+ * method to auto-inject `actor` and `txCtx`.
+ *
+ * ## Usage in Next.js / TanStack Start / SvelteKit:
+ *
+ * ```typescript
+ * import { createCommerce } from "@porulle/core";
+ * import config from "./commerce.config.js";
+ *
+ * const commerce = await createCommerce(config);
+ *
+ * // Server action / loader — no HTTP round-trip
+ * const products = await commerce.api.catalog.list({ limit: 10 });
+ * const order = await commerce.api.orders.getById("order-123");
+ * ```
+ *
+ * Plugin services are NOT exposed on `commerce.api`. Plugins instantiate their
+ * own services inside `routes(ctx)` via `ctx.services`. A
+ * future enhancement (backlog B-03) will introduce plugin service registration
+ * into the typed `kernel.services` map.
+ *
+ * ## Usage from a hook:
+ *
+ * ```typescript
+ * const api = createLocalAPI(kernel, { actor, tx });
+ * const product = await api.catalog.getById("prod-123");
+ * ```
+ *
+ * ## How it works:
+ *
+ * 1. `api.catalog` → Proxy intercepts, finds `kernel.services.catalog`
+ * 2. `api.catalog.getById(id)` → Proxy intercepts method call
+ * 3. Wraps the call: `kernel.services.catalog.getById(id, actor, txCtx)`
+ * 4. Returns the result directly — no HTTP, no serialization
+ *
+ * The Proxy auto-appends `actor` and `txCtx` to every method call.
+ * Service methods that accept `(actor, ctx)` as the last two params
+ * get them injected automatically. Methods that don't accept them
+ * still work — extra args are harmlessly ignored by JavaScript.
+ */
+/** Options for creating a local API instance */
+export interface LocalAPIOptions {
+    actor?: Actor | null;
+    tx?: unknown;
+    requestId?: string;
+}
+/**
+ * Maps a service type to strip actor/txCtx params from each method.
+ * Plugin authors get clean autocomplete: `api.catalog.create(input)`
+ * instead of `api.catalog.create(input, actor, txCtx)`.
+ */
+type CleanService<T> = {
+    [K in keyof T]: T[K] extends (...args: infer _A) => infer R ? (...args: unknown[]) => R : T[K];
+};
+/** The full local API type — all kernel services with cleaned signatures */
+export type CommerceLocalAPI<TServices extends Record<string, unknown> = Kernel["services"]> = {
+    [K in keyof TServices]: TServices[K] extends Record<string, unknown> ? CleanService<TServices[K]> : TServices[K];
+};
+/**
+ * Create a proxy-based local API over kernel services.
+ * Every service method gets `actor` and `txCtx` auto-injected.
+ */
+export declare function createLocalAPI(kernel: Kernel, options?: LocalAPIOptions): CommerceLocalAPI;
+/**
+ * @deprecated Use `createLocalAPI(kernel, { actor, tx })` instead.
+ * Kept for backward compatibility with existing hook code.
+ */
+export declare class LocalAPI {
+    private _proxy;
+    constructor(ctx: {
+        actor: Actor | null;
+        tx: unknown;
+        requestId: string;
+    }, kernel: Kernel);
+    get orders(): import("../modules/orders/service.js").OrderService;
+    get catalog(): import("../modules/catalog/service.js").CatalogServiceImpl;
+    get cart(): import("../modules/cart/service.js").CartService;
+    get inventory(): import("../modules/inventory/service.js").InventoryService;
+    get customers(): import("../modules/customers/service.js").CustomerService;
+    get pricing(): import("../modules/pricing/service.js").PricingService;
+    get promotions(): import("../modules/promotions/service.js").PromotionService;
+    get media(): import("../modules/media/service.js").MediaService;
+    get shipping(): import("../modules/shipping/service.js").ShippingService;
+    get search(): import("../modules/search/service.js").SearchService;
+    get webhooks(): import("../modules/webhooks/service.js").WebhookService & {
+        enqueueDelivery(payload: import("../runtime/kernel-types.js").WebhookDeliveryPayload): Promise<void>;
+    };
+    get fulfillment(): import("../modules/fulfillment/service.js").FulfillmentService;
+    get payments(): import("../modules/payments/service.js").PaymentsService;
+    get analytics(): import("../modules/analytics/service.js").AnalyticsService;
+    get tax(): import("../modules/tax/service.js").TaxService;
+    get audit(): import("../index.js").AuditService;
+    get organization(): import("../index.js").OrganizationService;
+    /** Resolve a service by name from `kernel.services`. */
+    service(name: string): unknown;
+}
+export {};
+//# sourceMappingURL=local-api.d.ts.map

package/dist/kernel/local-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-api.d.ts","sourceRoot":"","sources":["../../src/kernel/local-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,KAAK,YAAY,CAAC,CAAC,IAAI;KACpB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC,GACvD,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GACzB,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,CAC1B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,IAC5D;KACD,CAAC,IAAI,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChE,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAC1B,SAAS,CAAC,CAAC,CAAC;CACjB,CAAC;AAMF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC5B,gBAAgB,CAsDlB;AAID;;;GAGG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAmB;gBAG/B,GAAG,EAAE;QAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAC5D,MAAM,EAAE,MAAM;IAShB,IAAI,MAAM,wDAAiC;IAC3C,IAAI,OAAO,+DAAkC;IAC7C,IAAI,IAAI,qDAA+B;IACvC,IAAI,SAAS,+DAAoC;IACjD,IAAI,SAAS,8DAAoC;IACjD,IAAI,OAAO,2DAAkC;IAC7C,IAAI,UAAU,gEAAqC;IACnD,IAAI,KAAK,uDAAgC;IACzC,IAAI,QAAQ,6DAAmC;IAC/C,IAAI,MAAM,yDAAiC;IAC3C,IAAI,QAAQ;;MAAmC;IAC/C,IAAI,WAAW,mEAAsC;IACrD,IAAI,QAAQ,6DAAmC;IAC/C,IAAI,SAAS,+DAAoC;IACjD,IAAI,GAAG,mDAA8B;IACrC,IAAI,KAAK,uCAAgC;IACzC,IAAI,YAAY,8CAAuC;IAEvD,wDAAwD;IACxD,OAAO,CAAC,IAAI,EAAE,MAAM;CAGrB"}

package/dist/kernel/local-api.js

@@ -0,0 +1,89 @@
+// ─── 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)
+    // The Proxy transforms method signatures at runtime (auto-injecting actor/txCtx),
+    // so the cast from Kernel["services"] to CommerceLocalAPI is safe.
+    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; }
+    /** Resolve a service by name from `kernel.services`. */
+    service(name) {
+        return this._proxy[name];
+    }
+}

package/dist/kernel/module/define.d.ts

@@ -0,0 +1,21 @@
+import type { DatabaseAdapter } from "../database/adapter.js";
+import type { HookRegistry } from "../hooks/registry.js";
+import type { Logger } from "../hooks/types.js";
+export interface ModuleDeps<TDeps extends Record<string, unknown> = Record<string, unknown>> {
+    db: DatabaseAdapter;
+    hooks: HookRegistry;
+    services: TDeps;
+    config: unknown;
+    logger: Logger;
+}
+export interface AppModule<TSchema = unknown, TService = unknown, TDeps extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    schema: () => TSchema;
+    dependencies?: ReadonlyArray<keyof TDeps & string>;
+    service: (deps: ModuleDeps<TDeps>) => TService;
+}
+export type ServiceMap<TModules extends Record<string, AppModule>> = {
+    [K in keyof TModules]: TModules[K] extends AppModule<infer _TSchema, infer TService, infer _TDeps> ? TService : never;
+};
+export declare function defineModule<TSchema, TService, TDeps extends Record<string, unknown> = Record<string, unknown>>(manifest: AppModule<TSchema, TService, TDeps>): AppModule<TSchema, TService, TDeps>;
+//# sourceMappingURL=define.d.ts.map

package/dist/kernel/module/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/kernel/module/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,UAAU,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzF,EAAE,EAAE,eAAe,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS,CACxB,OAAO,GAAG,OAAO,EACjB,QAAQ,GAAG,OAAO,EAClB,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE/D,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC;IACnD,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC;CAChD;AAED,MAAM,MAAM,UAAU,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI;KAClE,CAAC,IAAI,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,QAAQ,EAAE,MAAM,QAAQ,EAAE,MAAM,MAAM,CAAC,GAC9F,QAAQ,GACR,KAAK;CACV,CAAC;AAEF,wBAAgB,YAAY,CAC1B,OAAO,EACP,QAAQ,EACR,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,QAAQ,EAAE,SAAS,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAEpF"}

package/dist/kernel/module/define.js

@@ -0,0 +1,3 @@
+export function defineModule(manifest) {
+    return manifest;
+}

package/dist/kernel/module/index.d.ts

@@ -0,0 +1,4 @@
+export type { AppModule, ModuleDeps, ServiceMap } from "./define.js";
+export { defineModule } from "./define.js";
+export { ModuleCycleError, topoSortModules } from "./topo-sort.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/kernel/module/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/kernel/module/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/kernel/module/index.js

@@ -0,0 +1,2 @@
+export { defineModule } from "./define.js";
+export { ModuleCycleError, topoSortModules } from "./topo-sort.js";

package/dist/kernel/module/topo-sort.d.ts

@@ -0,0 +1,7 @@
+import type { AppModule } from "./define.js";
+export declare class ModuleCycleError extends Error {
+    readonly cycle: string[];
+    constructor(cycle: string[]);
+}
+export declare function topoSortModules(modules: Record<string, AppModule>): string[];
+//# sourceMappingURL=topo-sort.d.ts.map

package/dist/kernel/module/topo-sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo-sort.d.ts","sourceRoot":"","sources":["../../../src/kernel/module/topo-sort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;gBAEb,KAAK,EAAE,MAAM,EAAE;CAM5B;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,MAAM,EAAE,CAiD5E"}

package/dist/kernel/module/topo-sort.js

@@ -0,0 +1,89 @@
+export class ModuleCycleError extends Error {
+    cycle;
+    constructor(cycle) {
+        const label = cycle.join(" → ");
+        super(`Module dependency cycle: ${label}`);
+        this.name = "ModuleCycleError";
+        this.cycle = cycle;
+    }
+}
+export function topoSortModules(modules) {
+    const keys = Object.keys(modules);
+    const keySet = new Set(keys);
+    for (const [id, mod] of Object.entries(modules)) {
+        for (const dep of mod.dependencies ?? []) {
+            const depKey = dep;
+            if (!keySet.has(depKey)) {
+                throw new Error(`Module "${id}" declares unknown dependency "${depKey}"`);
+            }
+        }
+    }
+    const remaining = new Map();
+    for (const k of keys) {
+        const mod = modules[k];
+        remaining.set(k, new Set((mod.dependencies ?? [])));
+    }
+    const waitingOn = new Map();
+    for (const m of keys) {
+        const mod = modules[m];
+        for (const d of (mod.dependencies ?? [])) {
+            const list = waitingOn.get(d);
+            if (list)
+                list.push(m);
+            else
+                waitingOn.set(d, [m]);
+        }
+    }
+    const order = [];
+    const queue = keys.filter((k) => remaining.get(k).size === 0);
+    while (queue.length > 0) {
+        const n = queue.shift();
+        order.push(n);
+        for (const m of waitingOn.get(n) ?? []) {
+            const set = remaining.get(m);
+            if (set.delete(n) && set.size === 0) {
+                queue.push(m);
+            }
+        }
+    }
+    if (order.length !== keys.length) {
+        const cycle = findCycleKeys(modules, keys);
+        throw new ModuleCycleError(cycle);
+    }
+    return order;
+}
+function findCycleKeys(modules, keys) {
+    const WHITE = 0;
+    const GRAY = 1;
+    const BLACK = 2;
+    const mark = new Map();
+    const stack = [];
+    function dfs(u) {
+        mark.set(u, GRAY);
+        stack.push(u);
+        const mod = modules[u];
+        for (const v of (mod.dependencies ?? [])) {
+            const mv = mark.get(v) ?? WHITE;
+            if (mv === WHITE) {
+                const found = dfs(v);
+                if (found)
+                    return found;
+            }
+            else if (mv === GRAY) {
+                const idx = stack.indexOf(v);
+                return [...stack.slice(idx), v];
+            }
+        }
+        stack.pop();
+        mark.set(u, BLACK);
+        return null;
+    }
+    for (const k of keys) {
+        if ((mark.get(k) ?? WHITE) === WHITE) {
+            const found = dfs(k);
+            if (found)
+                return found;
+        }
+    }
+    throw new Error("topoSortModules: expected a cycle but DFS did not find one");
+}

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

@@ -0,0 +1,84 @@
+import type { RouteConfig } from "@hono/zod-openapi";
+import type { PluginDb } from "../database/plugin-types.js";
+import type { CommerceConfig, CommercePlugin, PluginPermission } from "../../config/types.js";
+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: {
+        /** Tenant-scoped Drizzle handle (organization from the request actor). */
+        db: PluginDb;
+        /**
+         * Raw Drizzle handle — bypasses tenant scoping. Emits a rate-limited deprecation
+         * warning on each access (MT-4 escape hatch).
+         */
+        unscoped: PluginDb;
+        transaction<T>(fn: (tx: PluginDb) => Promise<T>): Promise<T>;
+    };
+    logger: PluginLogger;
+}
+export type { PluginPermission };
+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[];
+    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)
+ * - `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,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAS5D,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAI/B,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,0EAA0E;QAC1E,EAAE,EAAE,QAAQ,CAAC;QACb;;;WAGG;QACH,QAAQ,EAAE,QAAQ,CAAC;QACnB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KAC9D,CAAC;IACF,MAAM,EAAE,YAAY,CAAC;CACtB;AAqDD,YAAY,EAAE,gBAAgB,EAAE,CAAC;AAEjC,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,eAAe,CAAC,EAAE,MAAM,OAAO,EAAE,CAAC;CACnC;AAKD,eAAO,MAAM,kBAAkB,aAAoB,CAAC;AAEpD,mEAAmE;AACnE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,sBAAsB,GAC/B,cAAc,CAkJhB"}

package/dist/kernel/plugin/manifest.js

@@ -0,0 +1,196 @@
+import { resolveOrgId } from "../../auth/org.js";
+import { createScopedDb } from "../database/scoped-db.js";
+import { getPluginDatabaseScopeOrganizationId, runWithPluginDatabaseScope, } from "../database/plugin-db-context.js";
+const UNSCOPED_WARN_COOLDOWN_MS = 60_000;
+const UNSCOPED_WARN_EVERY_N = 100;
+function createRateLimitedUnscopedAccessWarning(logger) {
+    let lastWarnAt = 0;
+    let accessCount = 0;
+    return () => {
+        accessCount += 1;
+        const now = Date.now();
+        if (accessCount % UNSCOPED_WARN_EVERY_N !== 0 && now - lastWarnAt < UNSCOPED_WARN_COOLDOWN_MS) {
+            return;
+        }
+        lastWarnAt = now;
+        logger.warn("[plugin:database] PluginContext.database.unscoped is deprecated (MT-4 escape hatch); prefer ctx.database.db for tenant-scoped access.");
+    };
+}
+function buildPluginContextDatabase(rawDb, transactionFn, commerceConfig, logger) {
+    const orgGetter = () => getPluginDatabaseScopeOrganizationId() ??
+        resolveOrgId(null, undefined, commerceConfig);
+    const scopedDb = createScopedDb(rawDb, orgGetter);
+    const warnUnscoped = createRateLimitedUnscopedAccessWarning(logger);
+    return {
+        get db() {
+            return scopedDb;
+        },
+        get unscoped() {
+            warnUnscoped();
+            return rawDb;
+        },
+        transaction: async (fn) => {
+            return transactionFn(async (tx) => {
+                const scopedTx = createScopedDb(tx, orgGetter);
+                return fn(scopedTx);
+            });
+        },
+    };
+}
+// ─── 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)
+ * - `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 };
+        if (manifest.permissions?.length) {
+            const withPlugin = manifest.permissions.map((p) => ({
+                ...p,
+                pluginId: manifest.id,
+            }));
+            result = {
+                ...result,
+                pluginPermissions: [...(result.pluginPermissions ?? []), ...withPlugin],
+            };
+        }
+        // 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;
+                    // Narrow DatabaseAdapter<unknown> → PluginContext.database once here.
+                    // All plugin code receives typed PluginDb — no casts downstream.
+                    const regs = pluginRoutes({
+                        config: k.config,
+                        services: k.services,
+                        database: buildPluginContextDatabase(k.database.db, k.database.transaction, k.config, k.logger),
+                        logger: k.logger,
+                    });
+                    for (const route of regs) {
+                        // ── Error boundary: wrap handler with plugin context ──
+                        const originalHandler = route.handler;
+                        const wrappedHandler = async (...args) => {
+                            const c = args[0];
+                            const actor = c?.get?.("actor");
+                            const orgId = resolveOrgId(actor, undefined, k.config);
+                            try {
+                                return await runWithPluginDatabaseScope(orgId, async () => {
+                                    const out = originalHandler(...args);
+                                    return await Promise.resolve(out);
+                                });
+                            }
+                            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.
+                            // Explicit dispatch avoids casting Hono to a Record.
+                            // Handler cast is a single `as any` (Hono's overloaded method
+                            // signatures can't unify with our generic handler shape).
+                            const h = wrappedHandler;
+                            switch (route.method.toLowerCase()) {
+                                case "get":
+                                    app.get(route.path, h);
+                                    break;
+                                case "post":
+                                    app.post(route.path, h);
+                                    break;
+                                case "put":
+                                    app.put(route.path, h);
+                                    break;
+                                case "patch":
+                                    app.patch(route.path, h);
+                                    break;
+                                case "delete":
+                                    app.delete(route.path, h);
+                                    break;
+                                case "options":
+                                    app.options(route.path, h);
+                                    break;
+                                default:
+                                    console.warn(`[plugin:${manifest.id}] unsupported HTTP method "${route.method}" for ${route.path}`);
+                            }
+                        }
+                    }
+                },
+            };
+        }
+        // 4. 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.js";
+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,eAAe,CAAC;AAEvB,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"}