@oktis-works/core 0.5.15 → 0.7.0

package/dist/plugin/load.d.ts

@@ -1,5 +1,70 @@
-import { type PluginBootstrapResult } from '@oktis-works/plugin-runtime';
-import type { RouteDefinition } from '@oktis-works/plugin-runtime';
+import type { RouteDefinition, PluginBootstrapResult } from '@oktis-works/plugin-runtime';
+import type { AdminExtensionsState, PluginBlockManifest, PluginPatternManifest } from '@oktis-works/types';
+import type { EnqueuedAsset, PluginHealthCheck } from '@oktis-works/plugin-sdk';
+/** Plugin job handler (dispatched by the worker). */
+export type PluginJobHandlerFn = (payload: unknown, context: {
+    tenantId: string | null;
+    plugin: string;
+    jobName: string;
+}) => void | Promise<void>;
+/**
+ * Resolves the handler registered by a plugin for a job (via api.jobs.on).
+ * Scope: platform (`tenantId` null) or tenant (loaded on demand).
+ * Never throws — null when the plugin is disabled or the handler is absent.
+ */
+export declare function getPluginJobHandler(tenantId: string | null, pluginName: string, jobName: string): Promise<PluginJobHandlerFn | null>;
+/**
+ * `api.admin` slots loaded in a scope (platform `null` or `tenant:<id>`) —
+ * feeds GET /api/v1/plugins/extensions together with `manifest.admin`.
+ * Never throws: runtime unavailability becomes an empty list.
+ */
+export declare function getPluginAdminExtensions(tenantId: string | null): Promise<Array<{
+    pluginName: string;
+    state: AdminExtensionsState;
+}>>;
+/**
+ * Blocks registered at runtime by the loaded plugins of a scope — feeds
+ * GET /api/v1/blocks together with `manifest.blocks`. Never throws: runtime
+ * unavailability becomes an empty list.
+ */
+export declare function getPluginBlocks(tenantId: string | null): Promise<Array<{
+    pluginName: string;
+    blocks: Array<PluginBlockManifest & {
+        pluginName: string;
+    }>;
+}>>;
+/**
+ * Patterns registered at runtime by the loaded plugins of a scope — feeds
+ * GET /api/v1/patterns together with `manifest.patterns`. Never throws:
+ * runtime unavailability becomes an empty list.
+ */
+export declare function getPluginPatterns(tenantId: string | null): Promise<Array<{
+    pluginName: string;
+    patterns: Array<PluginPatternManifest & {
+        pluginName: string;
+    }>;
+}>>;
+/**
+ * Assets enqueued by the loaded plugins of a scope — feeds the public
+ * renderer's theme:head pipeline (Item 8). Never throws: runtime
+ * unavailability becomes an empty list.
+ */
+export declare function getPluginAssets(tenantId: string | null): Promise<Array<{
+    pluginName: string;
+    assets: EnqueuedAsset[];
+}>>;
+/**
+ * Health checks registered by the loaded plugins of a scope — aggregated by
+ * GET /api/v1/health (Item 14). Never throws: runtime unavailability becomes
+ * an empty list.
+ */
+export declare function getPluginHealthChecks(tenantId: string | null): Promise<Array<{
+    pluginName: string;
+    checks: Array<{
+        name: string;
+        check: PluginHealthCheck;
+    }>;
+}>>;
 export interface PluginsScopeState {
     /** `platform` ou `tenant:<id>`. */
     scope: string;
@@ -21,36 +86,38 @@ export interface PluginsRuntimeState {
 export interface PluginRouteEntry {
     pluginName: string;
     routes: RouteDefinition[];
+    /** rpm do rate limit por plugin (manifest rateLimit.rpm, Item 17). */
+    rpm?: number;
 }
 /** Registra rotas de um plugin (chamado durante bootstrap). */
-export declare function registerPluginRoutes(pluginName: string, routes: RouteDefinition[]): void;
+export declare function registerPluginRoutes(pluginName: string, routes: RouteDefinition[], rpm?: number): void;
 /** Remove rotas de um plugin (quando desativado/desinstalado). */
 export declare function unregisterPluginRoutes(pluginName: string): boolean;
-/** Obtém todas as rotas registradas para montagem no router da API. */
+/** Gets every route registered for mounting on the API router. */
 export declare function getRegisteredPluginRoutes(): PluginRouteEntry[];
 /**
  * Sincroniza o registry **platform** com os plugins habilitados no banco.
- * Force implícito: é a chamada explícita de boot/ativação — reflete o banco
- * na hora. Idempotente e nunca lança.
+ * Implicit force: this is the explicit boot/activation call — reflects the
+ * database immediately. Idempotent and never throws.
  */
 export declare function syncEnabledPlugins(options?: {
     force?: boolean;
 }): Promise<PluginBootstrapResult>;
 /**
- * Garante que os plugins do tenant estão carregados no registry dele.
+ * Ensures the tenant's plugins are loaded into its own registry.
  * Chamado sob demanda (middleware/API, web, worker) — com cache de TTL para
- * não bater no banco a cada requisição. Nunca lança.
+ * avoids hitting the database on every request. Never throws.
  */
 export declare function ensureTenantPluginsLoaded(tenantId: string, options?: {
     force?: boolean;
 }): Promise<PluginBootstrapResult>;
 /**
- * Invalida o cache/registry de um tenant (após ativar/desativar vínculo,
- * desinstalar ou mudar permissões). A próxima requisição do tenant recarrega.
+ * Invalidates a tenant's cache/registry (after enabling/disabling a link,
+ * uninstalling or changing permissions). The tenant's next request reloads.
  */
-export declare function invalidateTenantPlugins(tenantId: string): void;
-/** Invalida o escopo platform (após mudanças globais). */
+export declare function invalidateTenantPlugins(tenantId: string): Promise<void>;
+/** Invalidates the platform scope (after global changes). */
 export declare function invalidatePlatformPlugins(): void;
-/** Estado de carga por escopo — superfície de observabilidade (WP2). */
+/** Per-scope load state — observability surface (WP2). */
 export declare function getPluginsRuntimeState(): PluginsRuntimeState;
 //# sourceMappingURL=load.d.ts.map

package/dist/plugin/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/plugin/load.ts"],"names":[],"mappings":"AAiBA,OAAO,EAKL,KAAK,qBAAqB,EAE3B,MAAM,6BAA6B,CAAC;AAWrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAID,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI,CAGxF;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAElE;AAED,uEAAuE;AACvE,wBAAgB,yBAAyB,IAAI,gBAAgB,EAAE,CAE9D;AAkOD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAS1G;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,qBAAqB,CAAC,CAUhC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAO9D;AAED,0DAA0D;AAC1D,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,IAAI,mBAAmB,CAa5D"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/plugin/load.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAyB,MAAM,6BAA6B,CAAC;AACjH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3G,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AA4BhF,qDAAqD;AACrD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAClE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAO1B;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAYpC;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAAC,CAAC,CAMrE;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,mBAAmB,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAAC,CAMrG;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC,qBAAqB,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAAC,CAMzG;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAAC,CAMjE;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAAC,CAMnG;AAED,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAID,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAGtG;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAElE;AAED,kEAAkE;AAClE,wBAAgB,yBAAyB,IAAI,gBAAgB,EAAE,CAE9D;AAmYD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAS1G;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,qBAAqB,CAAC,CAUhC;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7E;AAED,6DAA6D;AAC7D,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD;AAED,0DAA0D;AAC1D,wBAAgB,sBAAsB,IAAI,mBAAmB,CAa5D"}

package/dist/plugin/load.js

@@ -1,20 +1,20 @@
-// @oktis-works/core - Sincronização de plugins habilitados em runtime
+// @oktis-works/core - Enabled plugins runtime sync
 //
-// O PLUGIN.md promete que `register(registry)` é chamado quando o plugin é
-// carregado — aqui o core cumpre isso para todos os processos (API, web,
-// worker, dev). Dois escopos:
+// PLUGIN.md promises that `register(registry)` is called when the plugin is
+// loaded — the core honors it for every process (API, web, worker, dev). Two
+// scopes:
 //
-//   - **platform** (`syncEnabledPlugins`): plugins `tenant_id IS NULL`,
-//     habilitados globalmente → registry platform, carregado no boot;
-//   - **tenant** (`ensureTenantPluginsLoaded`): plugins vinculados em
-//     `plugin_tenants` (status ENABLED) → registry do tenant, carregado sob
-//     demanda na primeira requisição daquele tenant (cache com TTL + LRU).
+//   - **platform** (`syncEnabledPlugins`): plugins with `tenant_id IS NULL`,
+//     enabled globally → platform registry, loaded at boot;
+//   - **tenant** (`ensureTenantPluginsLoaded`): plugins linked in
+//     `plugin_tenants` (ENABLED status) → tenant registry, loaded on demand
+//     at that tenant's first request (TTL + LRU cache).
 //
-// Nunca lança: falha de banco, diretório ausente ou plugin quebrado são
-// reportadas no resultado (e persistidas em `plugins.error`), sem derrubar o
-// boot. Falhas ficam visíveis em `getPluginsRuntimeState()` (rota
-// `/api/v1/plugins/runtime` + badge no admin) — não são silenciadas.
-import { bootstrapPlugins, getHookRegistryStore, unloadTenant, getLoadedPluginRoutes, } from '@oktis-works/plugin-runtime';
+// Never throws: database failure, missing directory or a broken plugin are
+// reported in the result (and persisted in `plugins.error`) without breaking
+// the boot. Failures are visible in `getPluginsRuntimeState()` (the
+// `/api/v1/plugins/runtime` route + admin badge) — never silenced.
+import { createHash } from 'node:crypto';
 import { getConnection } from '@oktis-works/database';
 import { loadConfig } from '@oktis-works/config';
 import { resolvePluginPermissionPolicy } from '@oktis-works/validation';
@@ -24,23 +24,143 @@ import { getEventBus } from '../events/bus.js';
 import { tenantService } from '../tenant/service.js';
 import { userService } from '../user/service.js';
 import { fieldGroupService } from '../fields/service.js';
+import { postTypeRegistry } from '../content/post-types.js';
+import { taxonomyService } from '../taxonomies/service.js';
+import { pluginRolesService } from '../role/plugin-roles.js';
+import { mailService } from '../mail/service.js';
+import { auditService } from '../observability/audit.js';
+import { getCache } from '../cache/index.js';
+import { queueProducer } from '../queue/producer.js';
 import { getCurrentTenantIdSync, getCurrentUserIdSync, getCurrentRequestIdSync } from '../tenant/context.js';
+// Dynamic imports for the circular dependency with plugin-runtime
+// (non-literal require so TypeScript cannot resolve it at build time)
+const getPluginRuntime = async () => {
+    return require('@oktis-works/plugin-runtime');
+};
+let _pluginRuntimeCache = null;
+const getPluginRuntimeCached = async () => {
+    if (!_pluginRuntimeCache) {
+        _pluginRuntimeCache = await getPluginRuntime();
+    }
+    return _pluginRuntimeCache;
+};
+const getBootstrapPlugins = async () => (await getPluginRuntimeCached()).bootstrapPlugins;
+const getHookRegistryStore = async () => (await getPluginRuntimeCached()).getHookRegistryStore;
+const unloadTenant = async () => (await getPluginRuntimeCached()).unloadTenant;
+const getLoadedPluginRoutes = async () => (await getPluginRuntimeCached()).getLoadedPluginRoutes;
+const getLoadedPluginJobHandlers = async () => (await getPluginRuntimeCached()).getLoadedPluginJobHandlers;
+const getLoadedPluginAdminExtensions = async () => (await getPluginRuntimeCached()).getLoadedPluginAdminExtensions;
+const getLoadedPluginBlocks = async () => (await getPluginRuntimeCached()).getLoadedPluginBlocks;
+const getLoadedPluginPatterns = async () => (await getPluginRuntimeCached()).getLoadedPluginPatterns;
+const getLoadedPluginAssets = async () => (await getPluginRuntimeCached()).getLoadedPluginAssets;
+const getLoadedPluginHealthChecks = async () => (await getPluginRuntimeCached()).getLoadedPluginHealthChecks;
+/** Deterministic plugin job id (schedules are idempotent by it). */
+function pluginJobId(tenantId, pluginName, jobName) {
+    return `plugin:${tenantId ?? 'platform'}:${pluginName}:${jobName}`;
+}
+/**
+ * Resolves the handler registered by a plugin for a job (via api.jobs.on).
+ * Scope: platform (`tenantId` null) or tenant (loaded on demand).
+ * Never throws — null when the plugin is disabled or the handler is absent.
+ */
+export async function getPluginJobHandler(tenantId, pluginName, jobName) {
+    try {
+        const entries = await (await getLoadedPluginJobHandlers())(scopeKey(tenantId));
+        for (const entry of entries) {
+            if (entry.pluginName === pluginName) {
+                return entry.handlers.get(jobName) ?? null;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `api.admin` slots loaded in a scope (platform `null` or `tenant:<id>`) —
+ * feeds GET /api/v1/plugins/extensions together with `manifest.admin`.
+ * Never throws: runtime unavailability becomes an empty list.
+ */
+export async function getPluginAdminExtensions(tenantId) {
+    try {
+        return await (await getLoadedPluginAdminExtensions())(scopeKey(tenantId));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Blocks registered at runtime by the loaded plugins of a scope — feeds
+ * GET /api/v1/blocks together with `manifest.blocks`. Never throws: runtime
+ * unavailability becomes an empty list.
+ */
+export async function getPluginBlocks(tenantId) {
+    try {
+        return await (await getLoadedPluginBlocks())(scopeKey(tenantId));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Patterns registered at runtime by the loaded plugins of a scope — feeds
+ * GET /api/v1/patterns together with `manifest.patterns`. Never throws:
+ * runtime unavailability becomes an empty list.
+ */
+export async function getPluginPatterns(tenantId) {
+    try {
+        return await (await getLoadedPluginPatterns())(scopeKey(tenantId));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Assets enqueued by the loaded plugins of a scope — feeds the public
+ * renderer's theme:head pipeline (Item 8). Never throws: runtime
+ * unavailability becomes an empty list.
+ */
+export async function getPluginAssets(tenantId) {
+    try {
+        return await (await getLoadedPluginAssets())(scopeKey(tenantId));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Health checks registered by the loaded plugins of a scope — aggregated by
+ * GET /api/v1/health (Item 14). Never throws: runtime unavailability becomes
+ * an empty list.
+ */
+export async function getPluginHealthChecks(tenantId) {
+    try {
+        return await (await getLoadedPluginHealthChecks())(scopeKey(tenantId));
+    }
+    catch {
+        return [];
+    }
+}
 const pluginRoutesRegistry = new Map();
 /** Registra rotas de um plugin (chamado durante bootstrap). */
-export function registerPluginRoutes(pluginName, routes) {
+export function registerPluginRoutes(pluginName, routes, rpm) {
     if (routes.length === 0)
         return;
-    pluginRoutesRegistry.set(pluginName, { pluginName, routes });
+    pluginRoutesRegistry.set(pluginName, { pluginName, routes, ...(rpm ? { rpm } : {}) });
 }
 /** Remove rotas de um plugin (quando desativado/desinstalado). */
 export function unregisterPluginRoutes(pluginName) {
     return pluginRoutesRegistry.delete(pluginName);
 }
-/** Obtém todas as rotas registradas para montagem no router da API. */
+/** Gets every route registered for mounting on the API router. */
 export function getRegisteredPluginRoutes() {
     return [...pluginRoutesRegistry.values()];
 }
-/** Estados por escopo — ordem de iteração = LRU. */
+/** Item 21: registro das consultas preparadas por hash (teto LRU). */
+const PREPARED_CACHE_MAX = 200;
+const preparedPluginStatements = new Map();
+/** Per-scope states — iteration order = LRU. */
 const states = new Map();
 const inflight = new Map();
 const PLATFORM_KEY = 'platform';
@@ -63,9 +183,31 @@ function createApiDeps(tenantId) {
         db: {
             query: async (sql, params) => {
                 const conn = getConnection();
+                // Item 21: registro de prepared statements por hash — dedupe + LRU +
+                // contagem de uso por consulta (identidade da consulta preparada em
+                // api.query; o driver reutiliza o plano para consultas repetidas).
+                const hash = createHash('sha256').update(sql).digest('hex').slice(0, 24);
+                let entry = preparedPluginStatements.get(hash);
+                if (!entry) {
+                    entry = { sql, uses: 0 };
+                    preparedPluginStatements.set(hash, entry);
+                    if (preparedPluginStatements.size > PREPARED_CACHE_MAX) {
+                        const oldest = preparedPluginStatements.keys().next().value;
+                        if (oldest)
+                            preparedPluginStatements.delete(oldest);
+                    }
+                }
+                entry.uses += 1;
                 return conn.unsafe(sql, params ?? []);
             },
         },
+        // api.cache backend (Item 2) — lazy so contexts that never use the
+        // plugin cache don't need it at boot.
+        cache: {
+            get: (key) => getCache().get(key),
+            set: (key, value, ttlSeconds) => getCache().set(key, value, ttlSeconds),
+            del: (key) => getCache().del(key),
+        },
         getTenantId: () => tenantId ?? getCurrentTenantIdSync(),
         getUserId: () => getCurrentUserIdSync(),
         getRequestId: () => getCurrentRequestIdSync(),
@@ -78,14 +220,14 @@ function createApiDeps(tenantId) {
             return user ? { id: user.id, email: user.email, name: user.name, roles: user.roles } : null;
         },
         registerRoutes: (routes) => {
-            // As rotas registradas aqui são coletadas no bootstrap pelo próprio
-            // PluginAPI (getLoadedPluginRoutes) — neste ponto só registramos o log.
-            console.debug(`[PluginAPI] ${routes.length} rota(s) registrada(s) — será coletada no bootstrap`);
+            // Routes registered here are collected at bootstrap by the PluginAPI
+            // itself (getLoadedPluginRoutes) — this point only logs.
+            console.debug(`[PluginAPI] ${routes.length} route(s) registered — collected at bootstrap`);
         },
         registerContentFields: async (fields) => {
-            // Guard explícito: com noUncheckedIndexedAccess, fields[0] é T | undefined
-            // mesmo com o length check acima — o desctructuring com verificação
-            // deixa o narrowing para o TS e mantém a mesma semântica.
+            // Explicit guard: with noUncheckedIndexedAccess, fields[0] is
+            // T | undefined even with the length check above — checked
+            // destructuring leaves the narrowing to TS with the same semantics.
             const firstField = fields[0];
             if (!firstField)
                 return;
@@ -116,12 +258,135 @@ function createApiDeps(tenantId) {
                         fields: fieldInputs,
                     });
                 }
-                console.debug(`[PluginAPI] ${fields.length} campo(s) de conteúdo registrado(s) no field group "${groupKey}"`);
+                console.debug(`[PluginAPI] ${fields.length} content field(s) registered in field group "${groupKey}"`);
             }
             catch (error) {
-                console.error('[PluginAPI] Falha ao registrar campos de conteúdo:', error);
+                console.error('[PluginAPI] Failed to register content fields:', error);
             }
         },
+        registerFieldTypes: async (fieldTypes) => {
+            try {
+                // Same package — relative import (a self-import of '@oktis-works/core'
+                // does not resolve on a fresh checkout, where dist/ does not exist yet).
+                const { fieldTypeExtensionService } = await import('../fields/service.js');
+                for (const ft of fieldTypes) {
+                    await fieldTypeExtensionService.register(ft);
+                }
+                await fieldTypeExtensionService.syncToRegistry();
+                console.debug(`[PluginAPI] ${fieldTypes.length} tipo(s) de campo registrado(s) no registry`);
+            }
+            catch (error) {
+                console.error('[PluginAPI] Falha ao registrar tipos de campo:', error);
+            }
+        },
+        registerPostTypes: async (postTypes) => {
+            // Idempotent persistence for plugin Custom Post Types (item 1 of the
+            // plugin-parity-plan): existe com mesmo sourceId → atualiza; existe com
+            // outra origem (CORE/ADMIN/outro plugin) → warn + skip (nunca rouba).
+            try {
+                for (const type of postTypes) {
+                    const supports = ['title', 'editor'];
+                    if (type.revisions)
+                        supports.push('revisions');
+                    const existing = await postTypeRegistry.getBySlug(type.key);
+                    if (existing) {
+                        if (existing.source === 'PLUGIN' && existing.sourceId === type.pluginName) {
+                            await postTypeRegistry.update(type.key, {
+                                singularLabel: type.label,
+                                pluralLabel: type.plural ?? existing.pluralLabel,
+                                menuIcon: type.icon ?? existing.menuIcon,
+                                supports,
+                            });
+                        }
+                        else {
+                            console.warn(`[PluginAPI] Post type "${type.key}" already exists (${existing.source}) — "${type.pluginName}" cannot claim it`);
+                        }
+                        continue;
+                    }
+                    await postTypeRegistry.create({
+                        name: type.key,
+                        slug: type.key,
+                        pluralLabel: type.plural ?? `${type.label}s`,
+                        singularLabel: type.label,
+                        source: 'PLUGIN',
+                        sourceId: type.pluginName,
+                        supports,
+                        hasArchive: true,
+                        menuIcon: type.icon ?? 'box',
+                        singleton: false,
+                        public: true,
+                    });
+                }
+                console.debug(`[PluginAPI] ${postTypes.length} post type(s) de plugin persistido(s)`);
+            }
+            catch (error) {
+                console.error('[PluginAPI] Falha ao registrar post types:', error);
+            }
+        },
+        registerTaxonomies: async (taxonomies) => {
+            // Idempotent persistence for plugin Custom Taxonomies — ownership
+            // stored in meta.plugin (schema has no sourceId for taxonomies).
+            try {
+                for (const taxonomy of taxonomies) {
+                    const existing = await taxonomyService.getBySlug(taxonomy.key);
+                    if (existing) {
+                        const owner = existing.meta?.['plugin'];
+                        if (owner !== undefined && owner !== taxonomy.pluginName) {
+                            console.warn(`[PluginAPI] Taxonomy "${taxonomy.key}" belongs to plugin "${String(owner)}" — "${taxonomy.pluginName}" cannot claim it`);
+                            continue;
+                        }
+                        await taxonomyService.update(taxonomy.key, {
+                            name: taxonomy.label,
+                            hierarchical: taxonomy.hierarchical ?? false,
+                            attachTo: taxonomy.postTypes,
+                            meta: { ...(existing.meta ?? {}), plugin: taxonomy.pluginName },
+                        });
+                        continue;
+                    }
+                    await taxonomyService.create({
+                        name: taxonomy.label,
+                        slug: taxonomy.key,
+                        hierarchical: taxonomy.hierarchical ?? false,
+                        attachTo: taxonomy.postTypes,
+                        meta: { plugin: taxonomy.pluginName },
+                        source: 'PLUGIN',
+                    });
+                }
+                console.debug(`[PluginAPI] ${taxonomies.length} taxonomia(s) de plugin persistida(s)`);
+            }
+            catch (error) {
+                console.error('[PluginAPI] Falha ao registrar taxonomias:', error);
+            }
+        },
+        jobs: {
+            schedule: async (jobName, spec, ctx) => {
+                // Recurrence on the `plugins` queue — deterministic idempotent jobId
+                return queueProducer.scheduleRepeatable('plugin.job', pluginJobId(ctx.tenantId, ctx.pluginName, jobName), { plugin: ctx.pluginName, job: jobName, scheduled: true }, spec, { tenantId: ctx.tenantId ?? 'default' });
+            },
+            cancel: async (jobName, ctx) => {
+                return queueProducer.cancelRepeatable('plugin.job', pluginJobId(ctx.tenantId, ctx.pluginName, jobName));
+            },
+            enqueue: async (jobName, payload, ctx) => {
+                return queueProducer.enqueue('plugin.job', { plugin: ctx.pluginName, job: jobName, data: payload }, { tenantId: ctx.tenantId ?? 'default' });
+            },
+        },
+        roles: {
+            add: (input) => pluginRolesService.add(input),
+            remove: (input) => pluginRolesService.remove(input),
+            addPermission: (input) => pluginRolesService.addPermission(input),
+        },
+        mail: {
+            send: (input) => mailService.enqueue(input),
+        },
+        audit: {
+            record: (entry) => auditService.record({
+                tenantId: entry.tenantId ?? undefined,
+                action: entry.action,
+                resourceType: entry.resourceType,
+                resourceId: entry.resourceId,
+                changes: entry.changes,
+            }),
+        },
     };
 }
 function runtimeOptions(tenantId) {
@@ -143,7 +408,7 @@ function runtimeOptions(tenantId) {
  * Persiste o resultado da carga em `plugins.error`/`status`:
  *   - falha nova → `status = LOAD_FAILED` + mensagem;
  *   - sucesso depois de falha → `ACTIVATED` + `error = NULL`.
- * Só grava quando o estado mudou (nada de UPDATE por request). Nunca lança.
+ * Only writes when the state changed (no UPDATE per request). Never throws.
  */
 async function persistScopeResult(state) {
     const sql = getConnection();
@@ -165,7 +430,7 @@ async function persistScopeResult(state) {
         }
     }
     catch {
-        // banco indisponível não pode derrubar a carga — visibilidade fica no estado em memória
+        // an unavailable database cannot break the load — visibility stays in the in-memory state
     }
 }
 async function syncScope(tenantId, force) {
@@ -184,12 +449,12 @@ async function syncScope(tenantId, force) {
         return running;
     const promise = (async () => {
         try {
-            const result = await bootstrapPlugins(runtimeOptions(tenantId));
+            const result = await (await getBootstrapPlugins())(runtimeOptions(tenantId));
             // Coleta rotas registradas pelos plugins neste escopo
             const scopeKey = key; // 'platform' ou 'tenant:<id>'
-            const pluginRoutes = getLoadedPluginRoutes(scopeKey);
-            for (const { pluginName, routes } of pluginRoutes) {
-                registerPluginRoutes(pluginName, routes);
+            const pluginRoutes = await (await getLoadedPluginRoutes())(scopeKey);
+            for (const { pluginName, routes, rpm } of pluginRoutes) {
+                registerPluginRoutes(pluginName, routes, rpm);
             }
             // Remove rotas de plugins que foram descarregados (unloaded)
             for (const pluginName of result.unloaded) {
@@ -206,11 +471,11 @@ async function syncScope(tenantId, force) {
             states.set(key, state);
             await persistScopeResult(state);
             state.errors = new Map(result.failed.map((failure) => [failure.name, failure.error]));
-            evictOldTenants(config.plugins.maxLoadedTenants);
+            await evictOldTenants(config.plugins.maxLoadedTenants);
             return result;
         }
         catch (error) {
-            console.warn(`[plugins] sync indisponível (${key}): ${error instanceof Error ? error.message : String(error)}`);
+            console.warn(`[plugins] sync unavailable (${key}): ${error instanceof Error ? error.message : String(error)}`);
             const fallback = { enabled: [], loaded: [], unloaded: [], failed: [] };
             if (!states.has(key)) {
                 states.set(key, { key, tenantId, loadedAt: 0, result: fallback, errors: new Map() });
@@ -225,7 +490,7 @@ async function syncScope(tenantId, force) {
     return promise;
 }
 /** Evita crescer sem limite: descarta tenants com carga mais antiga. */
-function evictOldTenants(maxTenants) {
+async function evictOldTenants(maxTenants) {
     if (states.size <= maxTenants)
         return;
     for (const [key, state] of [...states.entries()]) {
@@ -234,28 +499,28 @@ function evictOldTenants(maxTenants) {
         if (state.tenantId === null)
             continue; // platform nunca sai
         states.delete(key);
-        unloadTenant(state.tenantId);
-        getHookRegistryStore().invalidateTenant(state.tenantId);
+        await (await unloadTenant())(state.tenantId);
+        (await (await getHookRegistryStore())).invalidateTenant(state.tenantId);
     }
 }
 /**
  * Sincroniza o registry **platform** com os plugins habilitados no banco.
- * Force implícito: é a chamada explícita de boot/ativação — reflete o banco
- * na hora. Idempotente e nunca lança.
+ * Implicit force: this is the explicit boot/activation call — reflects the
+ * database immediately. Idempotent and never throws.
  */
 export async function syncEnabledPlugins(options = {}) {
     try {
         return await syncScope(null, options.force ?? true);
     }
     catch (error) {
-        console.warn(`[plugins] sync indisponível: ${error instanceof Error ? error.message : String(error)}`);
+        console.warn(`[plugins] sync unavailable: ${error instanceof Error ? error.message : String(error)}`);
         return { enabled: [], loaded: [], unloaded: [], failed: [] };
     }
 }
 /**
- * Garante que os plugins do tenant estão carregados no registry dele.
+ * Ensures the tenant's plugins are loaded into its own registry.
  * Chamado sob demanda (middleware/API, web, worker) — com cache de TTL para
- * não bater no banco a cada requisição. Nunca lança.
+ * avoids hitting the database on every request. Never throws.
  */
 export async function ensureTenantPluginsLoaded(tenantId, options = {}) {
     if (!tenantId)
@@ -264,29 +529,29 @@ export async function ensureTenantPluginsLoaded(tenantId, options = {}) {
         return await syncScope(tenantId, options.force ?? false);
     }
     catch (error) {
-        console.warn(`[plugins] sync do tenant indisponível: ${error instanceof Error ? error.message : String(error)}`);
+        console.warn(`[plugins] tenant sync unavailable: ${error instanceof Error ? error.message : String(error)}`);
         return { enabled: [], loaded: [], unloaded: [], failed: [] };
     }
 }
 /**
- * Invalida o cache/registry de um tenant (após ativar/desativar vínculo,
- * desinstalar ou mudar permissões). A próxima requisição do tenant recarrega.
+ * Invalidates a tenant's cache/registry (after enabling/disabling a link,
+ * uninstalling or changing permissions). The tenant's next request reloads.
  */
-export function invalidateTenantPlugins(tenantId) {
+export async function invalidateTenantPlugins(tenantId) {
     if (!tenantId)
         return;
     const key = scopeKey(tenantId);
     states.delete(key);
     inflight.delete(key);
-    unloadTenant(tenantId);
-    getHookRegistryStore().invalidateTenant(tenantId);
+    await (await unloadTenant())(tenantId);
+    (await (await getHookRegistryStore())).invalidateTenant(tenantId);
 }
-/** Invalida o escopo platform (após mudanças globais). */
+/** Invalidates the platform scope (after global changes). */
 export function invalidatePlatformPlugins() {
     states.delete(PLATFORM_KEY);
     inflight.delete(PLATFORM_KEY);
 }
-/** Estado de carga por escopo — superfície de observabilidade (WP2). */
+/** Per-scope load state — observability surface (WP2). */
 export function getPluginsRuntimeState() {
     return {
         generatedAt: new Date().toISOString(),