@moku-labs/core 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 **Micro-kernel plugin framework for TypeScript. Three layers of isolation. Built for LLM-scale development.**
 
-One runtime export. Bundle < 5KB. Zero dependencies. The type system does the heavy lifting.
+Two runtime exports. Bundle < 8KB gzipped. Zero dependencies. The type system does the heavy lifting.
 
 ```
 bun add @moku-labs/core
@@ -33,7 +33,7 @@ Moku enforces a 3-layer architecture where each layer physically constrains the
 │  Cannot: modify the kernel                              │
 ├─────────────────────────────────────────────────────────┤
 │  Layer 1: @moku-labs/core                               │
-│  One function. Zero domain knowledge. Pure machinery.   │
+│  Two functions. Zero domain knowledge. Pure machinery.  │
 └─────────────────────────────────────────────────────────┘
 ```
 
@@ -122,7 +122,7 @@ app.blog.listPosts();           // fully typed
 await app.stop();
 ```
 
-**That's the entire API.** `createCoreConfig` → `createCore` → `createApp`. Three functions, three layers.
+**That's the entire factory chain.** `createCoreConfig` → `createCore` → `createApp`. Three functions, three layers. (A second runtime export, `createCorePlugin`, builds self-contained infrastructure plugins — see the API reference below.)
 
 ---
 
@@ -171,7 +171,7 @@ Moku is designed for a world where LLMs write plugins and CI enforces quality. T
 
 - **Strict emit** — only known event names compile. Wrong payloads are type errors. No `any`, no escape hatch.
 - **Phantom types** — plugin APIs, configs, and events flow through the type system without runtime cost.
-- **Required configs** — if a plugin needs config and you don't provide it, TypeScript tells you.
+- **Typed plugin configs** — `pluginConfigs` overrides are checked against each plugin's declared config shape. Wrong keys or value types don't compile. Overrides are optional — plugin defaults fill anything you omit.
 - **Context tiers** — `createState` can't call `emit` (other plugins don't exist yet). `onStop` can't access other plugins (they may already be stopped). The type system prevents temporal bugs.
 
 ### Runtime guarantees
@@ -248,7 +248,7 @@ Every field is optional. A plugin with only `api` works. A plugin with only `hoo
 
 ```typescript
 // Runtime
-import { createCoreConfig } from '@moku-labs/core';
+import { createCoreConfig, createCorePlugin } from '@moku-labs/core';
 
 // Type utilities for plugin authors
 import type { PluginCtx, EmitFn } from '@moku-labs/core';
@@ -258,6 +258,10 @@ import type { PluginCtx, EmitFn } from '@moku-labs/core';
 
 Creates a bound factory chain for a framework. Returns `{ createPlugin, createCore }`, both locked to `Config` and `Events`.
 
+### createCorePlugin(name, spec)
+
+Creates a self-contained infrastructure plugin (logging, env, storage). Core plugins are passed to `createCoreConfig` via `plugins`, and their APIs are injected onto every regular plugin's context (`ctx.log.info(...)`). No `depends`, no `events`, no `hooks` — a minimal `{ config, state }` context only.
+
 ### createCore(coreConfig, options)
 
 Captures framework defaults: plugins, plugin configs, `onReady`, `onError`. Returns `{ createApp, createPlugin }`.

package/dist/index.cjs

@@ -156,10 +156,16 @@ function checkCorePluginConflicts(id, plugins, corePluginNames) {
 function asRecord(value) {
 	return isRecord(value) ? value : {};
 }
+/** Shared frozen API for registered plugins that declare no api(). */
+const EMPTY_API = Object.freeze({});
 /**
 * Create a require function that looks up a plugin API by instance reference.
 *
-* @param runtime - The kernel runtime containing the API map.
+* Registered plugins without an api() resolve to a frozen empty object —
+* matching the type contract (ExtractApi = Record<string, never>) and
+* agreeing with has(). Only genuinely unregistered plugins throw.
+*
+* @param runtime - The kernel runtime containing the API map and name set.
 * @param formatError - Formats the error message using the plugin instance name.
 * @returns A function that returns the API for a given plugin instance or throws.
 * @example
@@ -171,8 +177,9 @@ function asRecord(value) {
 function createRequire(runtime, formatError) {
 	return (instance) => {
 		const api = runtime.apis.get(instance.name);
-		if (!api) throw new Error(formatError(instance.name));
-		return api;
+		if (api) return api;
+		if (runtime.pluginNameSet.has(instance.name)) return EMPTY_API;
+		throw new Error(formatError(instance.name));
 	};
 }
 /**
@@ -268,7 +275,9 @@ function buildEventBus(onError) {
 		for (const handler of handlers) try {
 			await handler(payload);
 		} catch (error) {
-			if (onError) onError(error);
+			try {
+				if (onError) onError(error);
+			} catch {}
 		}
 	}
 	/**
@@ -552,7 +561,7 @@ function initCorePlugins(corePlugins, corePluginConfigs, frameworkPluginConfigs,
 * @returns The frozen app object.
 * @example
 * ```ts
-* const app = await kernel({ id: "my-app", configDefaults: {}, ... });
+* const app = kernel({ id: "my-app", configDefaults: {}, ... });
 * ```
 */
 function kernel(parameters) {
@@ -566,7 +575,9 @@ function kernel(parameters) {
 	const resolvedConfigs = resolvePluginConfigs(flatPlugins, frameworkPluginConfigs, consumerPluginConfigs);
 	const states = createPluginStates(flatPlugins, globalConfig, resolvedConfigs);
 	const { emit, registerHook } = buildEventBus(onError || consumer?.onError ? (error) => {
-		if (onError) onError(error);
+		try {
+			if (onError) onError(error);
+		} catch {}
 		if (consumer?.onError) consumer.onError(error, buildCallbackContext(runtime));
 	} : void 0);
 	const runtime = {

package/dist/index.d.cts

@@ -953,14 +953,14 @@ type BoundCreatePluginFunction<GlobalConfig extends FrameworkConfig, GlobalEvent
 */
 interface CreateCoreOptions<Config> {
   /** Framework default plugins. */
-  readonly plugins: AnyPluginInstance[];
+  readonly plugins: readonly AnyPluginInstance[];
   /** Framework-level plugin config overrides keyed by plugin name. */
   readonly pluginConfigs?: Record<string, unknown>;
   /** Called after all plugins are initialized. */
   readonly onReady?: (context: {
     config: Readonly<Config>;
   }) => void;
-  /** Error handler for hook dispatch and teardown failures. */
+  /** Error handler for hook dispatch failures. Lifecycle errors from start()/stop() propagate to the caller instead. */
   readonly onError?: (error: Error) => void;
 }
 /**
@@ -996,7 +996,7 @@ interface CreateCoreResult<Config extends Record<string, unknown>, Events extend
 type BoundCreateCoreFunction<Config extends Record<string, unknown>, Events extends Record<string, unknown>, CorePlugins extends readonly AnyCorePluginInstance[] = readonly []> = <const Plugins extends readonly AnyPluginInstance[]>(coreConfig: {
   readonly createPlugin: BoundCreatePluginFunction<Config, Events, CoreApisFromTuple<CorePlugins>>;
 }, options: CreateCoreOptions<Config> & {
-  readonly plugins: [...Plugins];
+  readonly plugins: readonly [...Plugins];
 }) => CreateCoreResult<Config, Events, Plugins, CorePlugins>;
 /**
 * Creates a bound `createCore` function that captures framework context.
@@ -1055,7 +1055,7 @@ interface CoreConfigResult<Config extends Record<string, unknown>, Events extend
 * const { createPlugin, createCore } = coreConfig;
 * ```
 */
-declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = Record<string, never>, const CorePlugins extends readonly AnyCorePluginInstance[] = readonly []>(id: string, options: {
+declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = EmptyPluginEventMap, const CorePlugins extends readonly AnyCorePluginInstance[] = readonly []>(id: string, options: {
   config: Config;
   plugins?: [...CorePlugins];
   pluginConfigs?: { [K in CorePlugins[number] as ExtractCoreConfig<K> extends Record<string, never> ? never : IsLiteralString<ExtractCoreName<K>> extends true ? ExtractCoreName<K> : never]?: Partial<ExtractCoreConfig<K>> };

package/dist/index.d.mts

@@ -953,14 +953,14 @@ type BoundCreatePluginFunction<GlobalConfig extends FrameworkConfig, GlobalEvent
 */
 interface CreateCoreOptions<Config> {
   /** Framework default plugins. */
-  readonly plugins: AnyPluginInstance[];
+  readonly plugins: readonly AnyPluginInstance[];
   /** Framework-level plugin config overrides keyed by plugin name. */
   readonly pluginConfigs?: Record<string, unknown>;
   /** Called after all plugins are initialized. */
   readonly onReady?: (context: {
     config: Readonly<Config>;
   }) => void;
-  /** Error handler for hook dispatch and teardown failures. */
+  /** Error handler for hook dispatch failures. Lifecycle errors from start()/stop() propagate to the caller instead. */
   readonly onError?: (error: Error) => void;
 }
 /**
@@ -996,7 +996,7 @@ interface CreateCoreResult<Config extends Record<string, unknown>, Events extend
 type BoundCreateCoreFunction<Config extends Record<string, unknown>, Events extends Record<string, unknown>, CorePlugins extends readonly AnyCorePluginInstance[] = readonly []> = <const Plugins extends readonly AnyPluginInstance[]>(coreConfig: {
   readonly createPlugin: BoundCreatePluginFunction<Config, Events, CoreApisFromTuple<CorePlugins>>;
 }, options: CreateCoreOptions<Config> & {
-  readonly plugins: [...Plugins];
+  readonly plugins: readonly [...Plugins];
 }) => CreateCoreResult<Config, Events, Plugins, CorePlugins>;
 /**
 * Creates a bound `createCore` function that captures framework context.
@@ -1055,7 +1055,7 @@ interface CoreConfigResult<Config extends Record<string, unknown>, Events extend
 * const { createPlugin, createCore } = coreConfig;
 * ```
 */
-declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = Record<string, never>, const CorePlugins extends readonly AnyCorePluginInstance[] = readonly []>(id: string, options: {
+declare function createCoreConfig<Config extends Record<string, unknown>, Events extends Record<string, unknown> = EmptyPluginEventMap, const CorePlugins extends readonly AnyCorePluginInstance[] = readonly []>(id: string, options: {
   config: Config;
   plugins?: [...CorePlugins];
   pluginConfigs?: { [K in CorePlugins[number] as ExtractCoreConfig<K> extends Record<string, never> ? never : IsLiteralString<ExtractCoreName<K>> extends true ? ExtractCoreName<K> : never]?: Partial<ExtractCoreConfig<K>> };

package/dist/index.mjs

@@ -155,10 +155,16 @@ function checkCorePluginConflicts(id, plugins, corePluginNames) {
 function asRecord(value) {
 	return isRecord(value) ? value : {};
 }
+/** Shared frozen API for registered plugins that declare no api(). */
+const EMPTY_API = Object.freeze({});
 /**
 * Create a require function that looks up a plugin API by instance reference.
 *
-* @param runtime - The kernel runtime containing the API map.
+* Registered plugins without an api() resolve to a frozen empty object —
+* matching the type contract (ExtractApi = Record<string, never>) and
+* agreeing with has(). Only genuinely unregistered plugins throw.
+*
+* @param runtime - The kernel runtime containing the API map and name set.
 * @param formatError - Formats the error message using the plugin instance name.
 * @returns A function that returns the API for a given plugin instance or throws.
 * @example
@@ -170,8 +176,9 @@ function asRecord(value) {
 function createRequire(runtime, formatError) {
 	return (instance) => {
 		const api = runtime.apis.get(instance.name);
-		if (!api) throw new Error(formatError(instance.name));
-		return api;
+		if (api) return api;
+		if (runtime.pluginNameSet.has(instance.name)) return EMPTY_API;
+		throw new Error(formatError(instance.name));
 	};
 }
 /**
@@ -267,7 +274,9 @@ function buildEventBus(onError) {
 		for (const handler of handlers) try {
 			await handler(payload);
 		} catch (error) {
-			if (onError) onError(error);
+			try {
+				if (onError) onError(error);
+			} catch {}
 		}
 	}
 	/**
@@ -551,7 +560,7 @@ function initCorePlugins(corePlugins, corePluginConfigs, frameworkPluginConfigs,
 * @returns The frozen app object.
 * @example
 * ```ts
-* const app = await kernel({ id: "my-app", configDefaults: {}, ... });
+* const app = kernel({ id: "my-app", configDefaults: {}, ... });
 * ```
 */
 function kernel(parameters) {
@@ -565,7 +574,9 @@ function kernel(parameters) {
 	const resolvedConfigs = resolvePluginConfigs(flatPlugins, frameworkPluginConfigs, consumerPluginConfigs);
 	const states = createPluginStates(flatPlugins, globalConfig, resolvedConfigs);
 	const { emit, registerHook } = buildEventBus(onError || consumer?.onError ? (error) => {
-		if (onError) onError(error);
+		try {
+			if (onError) onError(error);
+		} catch {}
 		if (consumer?.onError) consumer.onError(error, buildCallbackContext(runtime));
 	} : void 0);
 	const runtime = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "author": "Alex Kucherenko",
   "repository": {
     "type": "git",
@@ -46,7 +46,7 @@
   },
   "description": "Micro-kernel plugin framework for LLMs (TypeScript)",
   "engines": {
-    "node": ">=22.0.0",
+    "node": ">=24.0.0",
     "bun": ">=1.3.8"
   },
   "files": [