@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/slothlet.mjs

@@ -17,924 +17,705 @@
 
 
 
-import fs from "node:fs/promises";
-import path from "node:path";
+import { readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-
-import { resolvePathFromCaller } from "@cldmv/slothlet/helpers/resolve-from-caller";
+import { getContextManager } from "@cldmv/slothlet/factories/context";
+import { SlothletError, SlothletWarning, SlothletDebug } from "@cldmv/slothlet/errors";
+import { registerInstance } from "@cldmv/slothlet/handlers/lifecycle-token";
+import { initI18n } from "@cldmv/slothlet/i18n";
 import {
-	analyzeModule,
-	processModuleFromAnalysis,
-	buildCategoryStructure,
-	toapiPathKey,
-	shouldIncludeFile,
-	safeDefine,
-	deepMerge,
-	mutateLiveBindingFunction,
-	addApiFromFolder
-} from "@cldmv/slothlet/helpers/api_builder";
-import { updateInstanceData, cleanupInstance } from "@cldmv/slothlet/helpers/instance-manager";
-import { disableAlsForEventEmitters, cleanupAllSlothletListeners } from "@cldmv/slothlet/helpers/als-eventemitter";
-import { HookManager } from "@cldmv/slothlet/helpers/hooks";
-
-
-
-
-function normalizeRuntimeType(runtime) {
-	if (!runtime || typeof runtime !== "string") {
-		return "async"; 
-	}
+	enableEventEmitterPatching,
+	disableEventEmitterPatching,
+	cleanupEventEmitterResources,
+	setApiContextChecker
+} from "@cldmv/slothlet/helpers/eventemitter-context";
 
-	const normalized = runtime.toLowerCase().trim();
 
+class Slothlet {
 	
-	if (normalized === "async" || normalized === "asynclocal" || normalized === "asynclocalstorage") {
-		return "async";
-	}
-
 	
-	if (normalized === "live" || normalized === "livebindings" || normalized === "experimental") {
-		return "live";
-	}
+	static RESERVED_ROOT_KEYS = ["slothlet", "shutdown", "destroy"];
 
 	
-	return "async";
-}
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-
-
-
-
-let DEBUG = process.argv.includes("--slothletdebug")
-	? true
-	: process.env.SLOTHLET_DEBUG === "1" || process.env.SLOTHLET_DEBUG === "true"
-		? true
-		: false;
-
+	static SKIP_PROPS = ["__metadata", "__type", "_materialize", "_impl", "____slothletInternal"];
 
-if (DEBUG && !process.env.SLOTHLET_DEBUG) {
-	process.env.SLOTHLET_DEBUG = "1";
-}
-
-
-export const self = {};
-
-
-export const context = {};
-
-
-export const reference = {};
-
-
-async function slothlet(options = {}) {
-	
-	const instance = createFreshInstance();
-
-	
-	for (const key of Object.keys(slothlet)) {
-		if (key.startsWith("_")) continue; 
+	constructor() {
 		
-		if (key === "name" || key === "length") continue;
-		try {
-			delete slothlet[key];
-		} catch {
-			
-		}
-	}
+		this.SlothletError = SlothletError;
+		this.SlothletWarning = SlothletWarning;
+		
+		this.debugLogger = null;
 
-	
-	for (const [k, v] of Object.entries(instance)) {
-		if (typeof v === "function") {
-			
-			Object.defineProperty(slothlet, k, { value: v.bind(instance), writable: false, enumerable: true, configurable: true });
-		} else {
-			
-			Object.defineProperty(slothlet, k, { value: instance[k], writable: true, enumerable: true, configurable: true });
-		}
-	}
-	Object.defineProperty(slothlet, "_instance", { value: instance, writable: false, enumerable: false, configurable: true });
+		
+		this.instanceID = null;
+		this.config = null;
+		this.api = null;
+		this.boundApi = null; 
+		this.contextManager = null;
+		this.isLoaded = false;
+		this.reference = null;
+		this.context = null;
 
-	
-	return await instance.create(options);
-}
+		
+		this._totalLazyCount = 0; 
+		this._unmaterializedLazyCount = 0; 
+		this._materializationComplete = false; 
+		this._materializationWaiters = []; 
+		this._materializationCompleteEmitted = false; 
 
+		
+		this.componentCategories = ["helpers", "handlers", "builders", "processors", "modes"];
 
-function createFreshInstance() {
-	const instance = {};
-	for (const [k, v] of Object.entries(slothletObject)) {
-		if (typeof v === "function") {
-			
-			instance[k] = v;
-			continue;
-		}
 		
-		if (k === "config") instance[k] = { ...v };
-		else if (k === "boundapi" || k === "context" || k === "reference") instance[k] = {};
-		else instance[k] = v;
+		for (const category of this.componentCategories) {
+			this[category] = {};
+		}
 	}
-	return instance;
-}
-
-
-const slothletObject = {
-	
-	api: null,
-	self: {},
-	boundapi: {},
-	context: {},
-	reference: {},
-	mode: "singleton",
-	loaded: false,
-	config: {
-		lazy: false,
-		apiDepth: Infinity,
-		debug: DEBUG,
-		dir: null,
-		sanitize: null,
-		allowApiOverwrite: true,
-		enableModuleOwnership: false
-	},
-	
-	_moduleOwnership: new Map(), 
-	_dispose: null,
-	_boundAPIShutdown: null,
-	instanceId: null, 
 
 	
-	async create(options = {}) {
-		if (this.loaded) {
-			console.warn("[slothlet] create: API already loaded, returning existing instance.");
-			return this.boundapi;
-		}
-
+	async _initializeComponents() {
 		
 		
 		
-		const { entry = import.meta.url, engine = "singleton", mode, api_mode = "auto" } = options ?? {};
-
 		
-		const executionEngine = mode && ["singleton", "vm", "worker", "fork"].includes(mode) ? mode : engine;
-
 		
-		let isLazyMode;
-		if (mode && ["lazy", "eager"].includes(mode)) {
-			isLazyMode = mode === "lazy";
-		} else {
-			isLazyMode = options.lazy !== undefined ? options.lazy : this.config.lazy;
-		}
 
-		
-		const runtimeType = normalizeRuntimeType(options.runtime || "async");
-		const loadingModeStr = isLazyMode ? "lazy" : "eager";
-		this.instanceId = `slothlet_${runtimeType}_${loadingModeStr}_${Date.now()}_${Math.random().toString(36).slice(2, 11).padEnd(9, "0")}`;
+		const baseDir = join(dirname(fileURLToPath(import.meta.url)), "lib");
 
-		
-		if (!this.modes) {
-			this.modes = {};
-			const modesDir = path.join(__dirname, "lib", "modes");
+		for (const category of this.componentCategories) {
+			const categoryDir = join(baseDir, category);
+			const files = readdirSync(categoryDir).filter((f) => f.endsWith(".mjs"));
 
-			const dirents = await fs.readdir(modesDir, { withFileTypes: true });
-			const modeFiles = dirents.filter((d) => d.isFile()).map((d) => path.join(modesDir, d.name));
+			for (const file of files) {
+				const filePath = join(categoryDir, file);
 
-			for (const file of modeFiles) {
-				const modePath = file;
-
-				const modeName = path.parse(file).name.replace(/^slothlet_/, "");
-				if (!modeName || modeName.includes(" ")) continue;
 				try {
+					const module = await import(pathToFileURL(filePath).href);
+
 					
-					const modeUrl = pathToFileURL(modePath).href;
+					const classExports = Object.values(module).filter((exp) => typeof exp === "function" && exp.slothletProperty);
 
-					const imported = await import(modeUrl);
-					if (imported && typeof imported === "object") {
-						this.modes[modeName] = imported.default || imported;
+					for (const ClassExport of classExports) {
+						const propName = ClassExport.slothletProperty;
+						
+						this[category][propName] = new ClassExport(this);
+
+						if (this.config?.debug?.initialization) {
+							this.debug("initialization", {
+								key: "DEBUG_MODE_COMPONENT_INITIALIZED",
+								component: ClassExport.name,
+								category,
+								propertyName: propName
+							});
+						}
 					}
-				} catch (err) {
-					console.error(`[slothlet] Could not import mode '${modeName}':`, err);
+				} catch (error) {
+					
+					
+					
+					
+					throw new this.SlothletError(
+						"MODULE_IMPORT_FAILED",
+						{
+							modulePath: filePath
+						},
+						error
+					);
 				}
 			}
 		}
+	}
 
-		this.mode = executionEngine;
-		this.api_mode = api_mode;
-		let api;
-		let dispose;
-		if (executionEngine === "singleton") {
-			
-			
-			const { context = null, reference = null, sanitize = null, hooks = false, scope, engine, mode, ...loadConfig } = options;
-			this.context = context;
-			this.reference = reference;
+	
+	_setupLifecycleSubscribers() {
+		
+		
+		if (!this.handlers.lifecycle) {
+			return; 
+		}
+		
 
-			
-			let hooksEnabled = false;
-			let hooksPattern = null;
-			let hooksSuppressErrors = false;
+		
+		
+		
+		if (this.handlers.metadata) {
+			this.handlers.lifecycle.subscribe("impl:created", (data, token) => {
+				this.handlers.metadata.tagSystemMetadata(
+					data.impl,
+					{
+						filePath: data.filePath,
+						apiPath: data.apiPath,
+						moduleID: data.moduleID,
+						sourceFolder: data.sourceFolder
+					},
+					token
+				);
+			});
+
+			this.handlers.lifecycle.subscribe("impl:changed", (data, token) => {
+				this.handlers.metadata.tagSystemMetadata(
+					data.impl,
+					{
+						filePath: data.filePath,
+						apiPath: data.apiPath,
+						moduleID: data.moduleID,
+						sourceFolder: data.sourceFolder
+					},
+					token
+				);
+			});
 
-			if (hooks === true || hooks === false) {
+			this.handlers.lifecycle.subscribe("impl:removed", (data) => {
 				
-				hooksEnabled = hooks;
-				hooksPattern = hooks ? "**" : null;
-			} else if (typeof hooks === "string") {
 				
-				hooksEnabled = true;
-				hooksPattern = hooks;
-			} else if (hooks && typeof hooks === "object") {
 				
-				hooksEnabled = hooks.enabled !== false; 
-				hooksPattern = hooks.pattern || "**";
-				hooksSuppressErrors = hooks.suppressErrors || false;
-			}
-
-			
-			this.hookManager = new HookManager(hooksEnabled, hooksPattern, { suppressErrors: hooksSuppressErrors });
-
-			
-			if (scope && typeof scope === "object") {
-				const mergeStrategy = scope.merge || "shallow";
-				if (mergeStrategy !== "shallow" && mergeStrategy !== "deep") {
-					throw new TypeError(`Invalid scope.merge value: "${mergeStrategy}". Must be "shallow" or "deep".`);
+				if (data.apiPath) {
+					const rootSegment = data.apiPath.split(".")[0];
+					this.handlers.metadata.removeUserMetadataByApiPath(rootSegment);
 				}
-				this.config.scope = { merge: mergeStrategy };
-			} else if (scope === false) {
-				this.config.scope = { enabled: false };
-			} else {
-				
-				this.config.scope = { merge: "shallow" };
-			}
+			});
+		}
 
+		
+		
+		
+		if (this.handlers.ownership) {
 			
-			if (sanitize !== null) {
-				this.config.sanitize = sanitize;
-			}
-
 			
-			loadConfig.lazy = isLazyMode;
+			this.handlers.lifecycle.subscribe("impl:created", (data) => {
+				
+				
+				
+				const collisionMode = this.config?.collision?.api || "merge";
+				
+				const implValue = data.wrapper?.__impl ?? data.impl;
+				this.handlers.ownership.register({
+					moduleID: data.moduleID,
+					apiPath: data.apiPath,
+					value: implValue,
+					source: data.source,
+					filePath: data.filePath,
+					collisionMode: collisionMode
+				});
+			});
 
 			
 			
-			if (this.api_mode === "function") {
-				this.boundapi = function (...args) {
-					if (typeof this.boundapi._impl === "function") {
-						return this.boundapi._impl(...args);
-					}
-				}.bind(this);
-				this.boundapi._impl = () => {};
-			} else if (this.api_mode === "auto") {
+			this.handlers.lifecycle.subscribe("impl:changed", (data) => {
 				
-				this.boundapi = {};
-			} else {
-				this.boundapi = {};
-			}
-
-			await this.load(loadConfig, { context, reference });
+				
+				
+				const collisionMode = this.config?.collision?.api || "merge";
+				
+				
+				
+				const implValue = data.wrapper?.__impl ?? data.impl;
 
-			
-			return this.boundapi;
-		} else {
-			const { createEngine } = await import("./lib/engine/slothlet_engine.mjs");
-			
-			({ api, dispose } = await createEngine({ entry, mode: executionEngine, ...options }));
-			
-			
-			if (typeof dispose === "function") {
-				Object.defineProperty(api, "__dispose__", {
-					value: dispose,
-					writable: false,
-					enumerable: false,
-					configurable: false
-				});
-			}
-			this._dispose = dispose;
-			this.loaded = true;
-			return api;
+				
+				
+				const currentOwner = this.handlers.ownership.getCurrentOwner(data.apiPath);
+				if (currentOwner?.moduleID !== data.moduleID) {
+					this.handlers.ownership.register({
+						moduleID: data.moduleID,
+						apiPath: data.apiPath,
+						value: implValue,
+						source: data.source,
+						filePath: data.filePath,
+						collisionMode: collisionMode
+					});
+				}
+			});
 		}
-	},
+	}
 
 	
-	async load(config = {}, ctxRef = { context: null, reference: null }) {
-		this.config = { ...this.config, ...config };
+	_registerLazyWrapper() {
+		this._totalLazyCount++;
+		this._unmaterializedLazyCount++;
+
+		if (this.config?.debug?.materialize) {
+			this.debug("materialize", {
+				key: "DEBUG_MODE_LAZY_WRAPPER_REGISTERED",
+				total: this._totalLazyCount,
+				unmaterialized: this._unmaterializedLazyCount
+			});
+		}
+	}
 
-		
-		this.config.runtime = normalizeRuntimeType(this.config.runtime);
-		
-		if (!this.runtime) {
-			if (this.config.runtime === "live") {
-				this.runtime = await import("@cldmv/slothlet/runtime/live");
-			} else {
+	
+	_onWrapperMaterialized() {
+		this._unmaterializedLazyCount--;
+
+		if (this.config?.debug?.materialize) {
+			this.debug("materialize", {
+				key: "DEBUG_MODE_LAZY_WRAPPER_MATERIALIZED",
+				total: this._totalLazyCount,
+				unmaterialized: this._unmaterializedLazyCount,
 				
-				this.runtime = await import("@cldmv/slothlet/runtime/async");
-			}
+				
+				percentage: this._totalLazyCount > 0 ? ((this._totalLazyCount - this._unmaterializedLazyCount) / this._totalLazyCount) * 100 : 100
+			});
 		}
 
-		let apiDir = this.config.dir || "api";
 		
-		if (apiDir && !path.isAbsolute(apiDir)) {
-			apiDir = resolvePathFromCaller(apiDir);
-		}
-
-		if (this.loaded) return this.api;
-		if (this.config.lazy) {
-			this.api = await this.modes.lazy.create.call(this, apiDir, this.config.apiDepth || Infinity, 0);
-		} else {
-			this.api = await this.modes.eager.create.call(this, apiDir, this.config.apiDepth || Infinity, 0);
-		}
+		if (this._unmaterializedLazyCount === 0 && !this._materializationComplete) {
+			this._materializationComplete = true;
 
-		
-		if (this.hookManager) {
-			const hooksApi = {
-				on: (name, type, handler, options) => this.hookManager.on(name, type, handler, options),
-				off: (idOrPattern) => this.hookManager.off(idOrPattern),
-				enable: (pattern) => this.hookManager.enable(pattern),
-				disable: () => this.hookManager.disable(),
-				clear: (type) => this.hookManager.clear(type),
-				list: (type) => this.hookManager.list(type)
-			};
+			if (this.config?.debug?.materialize) {
+				this.debug("materialize", {
+					key: "DEBUG_MODE_ALL_LAZY_WRAPPERS_MATERIALIZED",
+					total: this._totalLazyCount
+				});
+			}
 
 			
-			Object.defineProperty(this.api, "hooks", {
-				value: hooksApi,
-				writable: false,
-				enumerable: true,
-				configurable: true
-			});
-		}
-
-		if (this.config.debug) console.log(this.api);
-
-		
-		if (this.api_mode === "auto") {
-			this.api_mode = typeof this.api === "function" ? "function" : "object";
-			if (this.config.debug) {
-				console.log(`[DEBUG] Auto-detected api_mode: ${this.api_mode} (API is ${typeof this.api})`);
+			const waiters = this._materializationWaiters.splice(0);
+			for (const resolve of waiters) {
+				resolve();
 			}
 
 			
-			if (this.api_mode === "function" && typeof this.boundapi !== "function") {
-				this.boundapi = function (...args) {
-					
-					if (typeof this.boundapi._impl === "function") {
-						return this.boundapi._impl(...args);
-					}
-				}.bind(this);
-				this.boundapi._impl = () => {};
-			} else if (this.api_mode === "object" && typeof this.boundapi === "function") {
-				this.boundapi = {};
+			if (this.config?.tracking?.materialization && !this._materializationCompleteEmitted) {
+				this._materializationCompleteEmitted = true;
+				
+				
+				if (this.handlers?.lifecycle) {
+					this.handlers.lifecycle.emit("materialized:complete", {
+						total: this._totalLazyCount,
+						timestamp: Date.now()
+					});
+				}
 			}
 		}
-
-		const l_ctxRef = { ...{ context: null, reference: null }, ...ctxRef };
-
-		const _boundapi = this.createBoundApi(l_ctxRef.reference);
-
-		mutateLiveBindingFunction(this.boundapi, _boundapi);
-
-		this.updateBindings(this.context, this.reference, this.boundapi);
-
-		this.loaded = true;
-
-		return this.boundapi;
-	},
+	}
 
 	
-	_toapiPathKey(name) {
-		return toapiPathKey(name, this.config.sanitize || {});
-	},
+	async load(config = {}, preservedInstanceID = null) {
+		
+		this.config = config;
 
-	
-	async _buildCategory(categoryPath, options = {}) {
-		const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler, existingApi } = options;
+		
+		
+		
+		this.debugLogger = new SlothletDebug(config);
 
 		
-		return buildCategoryStructure(categoryPath, {
-			currentDepth,
-			maxDepth,
-			mode,
-			subdirHandler,
-			instance: this,
-			existingApi
-		});
-	},
+		
+		await this._initializeComponents();
 
-	
-	async _loadCategory(categoryPath, currentDepth = 0, maxDepth = Infinity) {
-		return this._buildCategory(categoryPath, { currentDepth, maxDepth, mode: "eager" });
-	},
+		
+		registerInstance(this);
 
-	
-	async _loadSingleModule(modulePath, returnAnalysis = false) {
 		
-		const analysis = await analyzeModule(modulePath, {
-			debug: this.config.debug,
-			instance: this
-		});
-		const processedModule = processModuleFromAnalysis(analysis, {
-			debug: this.config.debug,
-			instance: this
-		});
+		this._setupLifecycleSubscribers();
+
+		
+		this.config = this.helpers.config.transformConfig(config);
 
 		
-		if (returnAnalysis) {
-			return { mod: processedModule, analysis };
+		if (this.config?.i18n?.language) {
+			initI18n({ language: this.config.i18n.language });
 		}
 
 		
-		return processedModule;
-	},
+		
+		this.debugLogger = new SlothletDebug(this.config);
 
-	
-	_shouldIncludeFile(entry) {
-		return shouldIncludeFile(entry);
-	},
+		
+		this.instanceID = preservedInstanceID || this.helpers.utilities.generateId();
 
-	
-	updateBoundApiProperty(key, materializedValue) {
-		if (this.boundapi && key) {
-			try {
-				
-				Object.defineProperty(this.boundapi, key, {
-					value: materializedValue,
-					writable: true,
-					enumerable: true,
-					configurable: true
-				});
+		
+		this.reference = this.config.reference;
+		this.context = this.config.context;
 
-				
-				if (self && typeof self === "object") {
-					Object.defineProperty(self, key, {
-						value: materializedValue,
-						writable: true,
-						enumerable: true,
-						configurable: true
-					});
-				}
+		
+		this.contextManager = getContextManager(this.config.runtime);
 
-				
-				
-				const currentApi = this.api;
-				if (currentApi && currentApi[key] === materializedValue) {
-					mutateLiveBindingFunction(this.boundapi, currentApi);
-				}
+		
+		
+		
+		
+		
+		
+		
+		
+		setApiContextChecker(() => {
+			
+			const ctx = this.contextManager.tryGetContext();
+			return !!(ctx && ctx.self);
+			
+		});
+		
 
-				if (this.config.debug) {
-					console.log(`[DEBUG] Updated boundapi.${key} with materialized value`);
-					console.log(`[DEBUG] boundapi.${key} is now:`, typeof this.boundapi[key]);
-					console.log(`[DEBUG] boundapi.${key} keys:`, Object.keys(this.boundapi[key] || {}));
-				}
-			} catch (error) {
-				console.warn(`[slothlet] Failed to update boundapi.${key}:`, error.message);
-			}
+		
+		let store;
+		if (preservedInstanceID && this.contextManager.instances.has(preservedInstanceID)) {
+			
+			this.contextManager.cleanup(preservedInstanceID);
+			store = this.contextManager.initialize(this.instanceID, this.config);
+		} else {
+			
+			store = this.contextManager.initialize(this.instanceID, this.config);
 		}
-	},
 
-	
-	updateBindings(newContext = null, newReference = null, newSelf = null) {
-		if (newContext === null || (typeof newContext === "object" && Object.keys(newContext).length === 0)) newContext = { ...context };
-		if (newReference === null || (typeof newReference === "object" && Object.keys(newReference).length === 0))
-			newReference = { ...reference };
-		if (newSelf === null || (typeof newSelf === "object" && Object.keys(newSelf).length === 0)) newSelf = this.boundapi;
-		
 		
 		
+		enableEventEmitterPatching();
 
-		mutateLiveBindingFunction(self, newSelf);
+		
+		
+		
+		if (typeof this.contextManager.registerEventEmitterContextChecker === "function") {
+			this.contextManager.registerEventEmitterContextChecker();
+		}
 
 		
-		const contextWithRuntime = {
-			...newContext,
-			runtimeType: this.config.runtime 
-		};
-		Object.assign(context, contextWithRuntime || {});
-		Object.assign(reference, newReference || {});
 
 		
-		if (this.instanceId) {
-			updateInstanceData(this.instanceId, "self", newSelf);
-			updateInstanceData(this.instanceId, "context", contextWithRuntime);
-			updateInstanceData(this.instanceId, "reference", newReference);
-			updateInstanceData(this.instanceId, "config", this.config);
-		}
+		const baseModuleId = `base_${this.helpers.utilities.generateId().substring(0, 8)}`;
 
-		this.safeDefine(this.boundapi, "__ctx", {
-			self: this.boundapi,
-			context: this.context,
-			reference: this.reference,
-			hookManager: this.hookManager
+		
+		
+		const baseApi = await this.builders.builder.buildAPI({
+			dir: this.config.dir,
+			mode: this.config.mode,
+			moduleID: baseModuleId
 		});
-	},
 
-	
-	createBoundApi(ref = null) {
-		if (!this.api) throw new Error("BindleApi modules not loaded. Call load() first.");
-
-		let boundApi;
+		
+		
+		this.api = baseApi;
 
-		boundApi = this.api;
+		
+		const apiWithBuiltins = await this.buildFinalAPI(this.api);
 
 		
-		if (ref && typeof ref === "object") {
-			for (const [key, value] of Object.entries(ref)) {
-				if (!(key in boundApi)) {
-					try {
-						boundApi[key] = value;
-					} catch {
-						
-					}
-				}
-			}
+		
+		
+		
+		if (this.handlers.apiCacheManager) {
+			this.handlers.apiCacheManager.set(baseModuleId, {
+				endpoint: ".",
+				moduleID: baseModuleId,
+				api: this.api, 
+				folderPath: this.config.dir,
+				mode: this.config.mode,
+				sanitizeOptions: this.config.sanitize || {},
+				
+				
+				collisionMode: this.config.collision?.api || "merge",
+				config: { ...this.config },
+				timestamp: Date.now()
+			});
 		}
 
 		
-		const instance = this;
-		this.safeDefine(boundApi, "describe", function (showAll = false) {
+		this.injectRuntimeMetadataFunctions(apiWithBuiltins);
+
+		
+		if (this.config.metadata && typeof this.config.metadata === "object") {
 			
-			if (instance.config && instance.config.lazy) {
-				if (!showAll) {
-					return Reflect.ownKeys(boundApi);
-				}
-				
-				async function resolveAll(obj) {
-					const keys = Reflect.ownKeys(obj);
-					const entries = await Promise.all(
-						keys.map(async (key) => {
-							const value = obj[key];
-							
-							if (typeof value === "function" && value.constructor.name === "Proxy") {
-								let resolved;
-								try {
-									resolved = await value();
-								} catch {
-									resolved = value;
-								}
-								
-								if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
-									return [key, await resolveAll(resolved)];
-								}
-								return [key, resolved];
-							} else if (value && typeof value === "object" && !Array.isArray(value)) {
-								
-								return [key, await resolveAll(value)];
-							} else {
-								return [key, value];
-							}
-						})
-					);
-					const apiObj = {};
-					for (const [key, val] of entries) {
-						apiObj[key] = val;
-					}
-					return apiObj;
-				}
-				return resolveAll(boundApi);
+			for (const [key, value] of Object.entries(this.config.metadata)) {
+				this.handlers.metadata.setGlobalMetadata(key, value);
 			}
+
 			
-			return { ...boundApi };
-		});
+			this.handlers.metadata.registerUserMetadata(baseModuleId, this.config.metadata);
+		}
 
 		
-		if (
-			typeof boundApi.shutdown === "function" &&
-			boundApi.shutdown !== this.shutdown &&
-			boundApi.shutdown.name !== "bound get" &&
-			boundApi.shutdown.name !== "bound shutdown" &&
-			boundApi.shutdown.toString().indexOf("[native code]") === -1 &&
-			boundApi.shutdown.toString() !== this.shutdown.bind(this).toString()
-		) {
-			this._boundAPIShutdown = boundApi.shutdown; 
-		} else {
-			this._boundAPIShutdown = null;
+		
+		
+		
+		if (this.handlers.ownership) {
+			this.handlers.ownership.registerSubtree(apiWithBuiltins, baseModuleId, "");
 		}
 
 		
 		
-		
-		const hasUserDefinedShutdown = this._boundAPIShutdown !== null;
 
-		const shutdownDesc = Object.getOwnPropertyDescriptor(boundApi, "shutdown");
-		if (!shutdownDesc || shutdownDesc.configurable) {
-			Object.defineProperty(boundApi, "shutdown", {
-				value: this.shutdown.bind(this),
-				writable: true,
-				configurable: true,
-				enumerable: hasUserDefinedShutdown 
+		
+		if (!this.boundApi) {
+			
+			
+			
+			const isCallable = typeof this.api === "function" || (this.api && typeof this.api.default === "function");
+			const proxyTarget = isCallable ? function () {} : {};
+
+			this.boundApi = new Proxy(proxyTarget, {
+				get: (target, prop) => (this.api ? this.api[prop] : undefined),
+				set: (target, prop, value) => {
+					if (this.api) {
+						this.api[prop] = value;
+					}
+					return true;
+				},
+				has: (target, prop) => (this.api ? prop in this.api : false),
+				ownKeys: (____target) => (this.api ? Reflect.ownKeys(this.api) : []),
+				deleteProperty: (target, prop) => (this.api ? delete this.api[prop] : true),
+				apply: (target, thisArg, args) => (this.api ? Reflect.apply(this.api, thisArg, args) : undefined),
+				construct: (target, args) => (this.api ? Reflect.construct(this.api, args) : {}),
+				getOwnPropertyDescriptor: (target, prop) => {
+					
+					if (isCallable && prop === "prototype") {
+						return Object.getOwnPropertyDescriptor(target, prop);
+					}
+					if (this.api && prop in this.api) {
+						const desc = Object.getOwnPropertyDescriptor(this.api, prop);
+						if (desc) {
+							return { ...desc, configurable: true };
+						}
+					}
+					return undefined;
+				}
 			});
-		} else if (this.config && this.config.debug) {
-			console.warn("Could not redefine boundApi.shutdown: not configurable");
+			
 		}
 
 		
-		const addApiDesc = Object.getOwnPropertyDescriptor(boundApi, "addApi");
-		if (!addApiDesc || addApiDesc.configurable) {
-			Object.defineProperty(boundApi, "addApi", {
-				value: this.addApi.bind(this),
-				writable: true,
-				configurable: true,
-				enumerable: false 
-			});
-		} else if (this.config && this.config.debug) {
-			console.warn("Could not redefine boundApi.addApi: not configurable");
-		}
+		store.self = this.boundApi;
+		store.context = this.context || {}; 
 
 		
-		const runDesc = Object.getOwnPropertyDescriptor(boundApi, "run");
-		if (!runDesc || runDesc.configurable) {
-			Object.defineProperty(boundApi, "run", {
-				value: this.run.bind(this),
-				writable: true,
-				configurable: true,
-				enumerable: false
-			});
-		} else if (this.config && this.config.debug) {
-			console.warn("Could not redefine boundApi.run: not configurable");
+		
+		if (this.reference && typeof this.reference === "object") {
+			Object.assign(this.boundApi, this.reference);
 		}
 
+		this.isLoaded = true;
+
+		return this.boundApi;
+	}
+
+	
+	async reload(options = {}) {
+		const { keepInstanceID = false } = options;
+
+		
 		
-		const instanceIdDesc = Object.getOwnPropertyDescriptor(boundApi, "instanceId");
-		if (!instanceIdDesc || instanceIdDesc.configurable) {
-			Object.defineProperty(boundApi, "instanceId", {
-				value: this.instanceId,
-				writable: false,
-				configurable: true,
-				enumerable: false
+		if (!this.config?.dir) {
+			throw new SlothletError("INVALID_CONFIG_NOT_LOADED", {
+				operation: "reload",
+				validationError: true
 			});
 		}
 
 		
-		const scopeDesc = Object.getOwnPropertyDescriptor(boundApi, "scope");
-		if (!scopeDesc || scopeDesc.configurable) {
-			Object.defineProperty(boundApi, "scope", {
-				value: this.scope.bind(this),
-				writable: true,
-				configurable: true,
-				enumerable: false
-			});
-		} else if (this.config && this.config.debug) {
-			console.warn("Could not redefine boundApi.scope: not configurable");
-		}
 		
+		
+		const operationHistory = this.handlers.apiManager?.state?.operationHistory ? [...this.handlers.apiManager.state.operationHistory] : [];
 
 		
+		await this._clearModuleCaches();
 
 		
 		
+		
+		
+		const oldInstanceID = this.instanceID;
+		if (!keepInstanceID) {
+			this.instanceID = `${oldInstanceID}_reload_${Date.now()}`;
+		}
 
-		return boundApi;
-	},
-
-	
-	safeDefine(obj, key, value, enumerable = false) {
-		return safeDefine(obj, key, value, enumerable, this.config);
-	},
-
-	
-	isLoaded() {
-		return this.loaded;
-	},
+		
+		
+		const savedMetadataState = this.handlers.metadata?.exportUserState?.();
 
-	
-	getApi() {
-		return this.api;
-	},
+		
+		
+		const savedHooks = this.handlers.hookManager?.exportHooks?.();
 
-	
-	getBoundApi() {
-		return this.boundapi;
-	},
+		
+		await this.load(this.config, this.instanceID);
 
-	
-	_registerApiOwnership(apiPath, moduleId) {
-		if (!this.config.enableModuleOwnership) return;
-		this._moduleOwnership.set(apiPath, moduleId);
-		if (this.config.debug) {
-			console.log(`[DEBUG] Registered ownership: ${apiPath} -> ${moduleId}`);
+		
+		
+		
+		
+		if (savedMetadataState && this.handlers.metadata) {
+			this.handlers.metadata.importUserState(savedMetadataState);
 		}
-	},
-
-	
-	_getApiOwnership(apiPath) {
-		if (!this.config.enableModuleOwnership) return null;
-		return this._moduleOwnership.get(apiPath) || null;
-	},
-
-	
-	_validateModuleOwnership(apiPath, moduleId, forceOverwrite) {
-		if (!this.config.enableModuleOwnership || !forceOverwrite) return false;
 
-		const existingOwner = this._getApiOwnership(apiPath);
-		if (!existingOwner) {
-			
-			return true;
+		
+		
+		
+		if (savedHooks?.length && this.handlers.hookManager) {
+			this.handlers.hookManager.importHooks(savedHooks);
 		}
 
 		
-		if (existingOwner === moduleId) {
-			return true;
+		
+		
+		for (const [, store] of this.contextManager.instances) {
+			if (store.parentInstanceID === oldInstanceID) {
+				store.parentInstanceID = this.instanceID;
+			}
 		}
 
 		
-		if (this.config.debug) {
-			console.log(`[DEBUG] Ownership conflict: ${apiPath} owned by ${existingOwner}, attempted by ${moduleId}`);
+		
+		if (oldInstanceID && oldInstanceID !== this.instanceID && this.contextManager.instances?.has(oldInstanceID)) {
+			this.contextManager.cleanup(oldInstanceID);
 		}
-		return false;
-	},
 
-	
-	async addApi(apiPath, folderPath, metadata = {}, options = {}) {
-		return addApiFromFolder({ apiPath, folderPath, instance: this, metadata, options });
-	},
+		
+		for (const operation of operationHistory) {
+			if (operation.type === "add") {
+				await this.handlers.apiManager.addApiComponent({
+					apiPath: operation.apiPath,
+					folderPath: operation.folderPath,
+					
+					
+					options: { ...(operation.options || {}), recordHistory: false },
+					moduleID: `replay_${this.helpers.utilities.generateId().substring(0, 8)}` 
+				});
+				
+				
+			} else if (operation.type === "remove") {
+				
+				
+				const { parts } = this.handlers.apiManager.normalizeApiPath(operation.apiPath);
+				this.handlers.apiManager.deletePath(this.api, parts);
+				
+				
+				
+				if (this.handlers.metadata) {
+					const rootSegment = operation.apiPath.split(".")[0];
+					this.handlers.metadata.removeUserMetadataByApiPath(rootSegment);
+				}
+			}
+		}
 
-	
+		return this.boundApi;
+	}
 
 	
-	run(contextData, callback, ...args) {
-		if (this.config.scope?.enabled === false) {
-			throw new Error("Per-request context (scope) is disabled for this instance.");
-		}
+	async _clearModuleCaches() {
+		
+		
+		const targetDir = this.config.dir;
+		const { resolve } = await import("node:path");
+		const { createRequire } = await import("node:module");
+		const require = createRequire(import.meta.url);
+		const absoluteTargetDir = resolve(targetDir);
 
-		if (typeof callback !== "function") {
-			throw new TypeError("Callback must be a function.");
+		
+		for (const key of Object.keys(require.cache)) {
+			if (key.startsWith(absoluteTargetDir)) {
+				delete require.cache[key];
+			}
 		}
 
-		const runtimeType = this.config.runtime || "async";
-		let requestALS;
-		if (runtimeType === "async") {
-			return import("@cldmv/slothlet/runtime/async").then((asyncRuntime) => {
-				requestALS = asyncRuntime.requestALS;
-				const parentContext = requestALS.getStore() || {};
-
-				let mergedContext;
-				if (this.config.scope?.merge === "deep") {
-					const instanceContext = this.context || {};
-					let temp = this._deepMerge({}, instanceContext);
-					temp = this._deepMerge(temp, parentContext);
-					mergedContext = this._deepMerge(temp, contextData);
-				} else {
-					mergedContext = { ...parentContext, ...contextData };
-				}
-
-				return requestALS.run(mergedContext, () => callback(...args));
-			});
-		} else {
-			return import("@cldmv/slothlet/runtime/live").then((liveRuntime) => {
-				requestALS = liveRuntime.requestALS;
-				const parentContext = requestALS.getStore() || {};
-
-				let mergedContext;
-				if (this.config.scope?.merge === "deep") {
-					const instanceContext = this.context || {};
-					let temp = this._deepMerge({}, instanceContext);
-					temp = this._deepMerge(temp, parentContext);
-					mergedContext = this._deepMerge(temp, contextData);
-				} else {
-					mergedContext = { ...parentContext, ...contextData };
-				}
-
-				return requestALS.run(mergedContext, () => callback(...args));
-			});
-		}
-	},
+		
+		
+	}
 
 	
-	scope({ context, fn, args }) {
-		if (this.config.scope?.enabled === false) {
-			throw new Error("Per-request context (scope) is disabled for this instance.");
+	injectRuntimeMetadataFunctions(api) {
+		if (!api.slothlet?.metadata) {
+			return;
 		}
 
-		if (!context || typeof context !== "object") {
-			throw new TypeError("context must be an object.");
-		}
+		const metadataHandler = this.handlers.metadata;
 
-		if (typeof fn !== "function") {
-			throw new TypeError("fn must be a function.");
-		}
+		
+		api.slothlet.metadata.get = async function slothlet_metadata_get_runtime(path) {
+			return metadataHandler.get(path);
+		};
 
-		const runtimeType = this.config.runtime || "async";
-		let requestALS;
-		if (runtimeType === "async") {
-			return import("./lib/runtime/runtime-asynclocalstorage.mjs").then((asyncRuntime) => {
-				requestALS = asyncRuntime.requestALS;
-				const parentContext = requestALS.getStore() || {};
-
-				let mergedContext;
-				if (this.config.scope?.merge === "deep") {
-					const instanceContext = this.context || {};
-					let temp = this._deepMerge({}, instanceContext);
-					temp = this._deepMerge(temp, parentContext);
-					mergedContext = this._deepMerge(temp, context);
-				} else {
-					mergedContext = { ...parentContext, ...context };
-				}
+		api.slothlet.metadata.self = function slothlet_metadata_self_runtime() {
+			return metadataHandler.self();
+		};
 
-				const argsArray = args || [];
-				return requestALS.run(mergedContext, () => fn(...argsArray));
-			});
-		} else {
-			return import("./lib/runtime/runtime-livebindings.mjs").then((liveRuntime) => {
-				requestALS = liveRuntime.requestALS;
-				const parentContext = requestALS.getStore() || {};
-
-				let mergedContext;
-				if (this.config.scope?.merge === "deep") {
-					const instanceContext = this.context || {};
-					let temp = this._deepMerge({}, instanceContext);
-					temp = this._deepMerge(temp, parentContext);
-					mergedContext = this._deepMerge(temp, context);
-				} else {
-					mergedContext = { ...parentContext, ...context };
-				}
+		api.slothlet.metadata.caller = function slothlet_metadata_caller_runtime() {
+			return metadataHandler.caller();
+		};
+	}
 
-				const argsArray = args || [];
-				return requestALS.run(mergedContext, () => fn(...argsArray));
-			});
+	
+	async shutdown() {
+		if (!this.isLoaded) {
+			return;
 		}
-	},
 
-	
-	_deepMerge(target, source) {
-		return deepMerge(target, source);
-	},
+		
+		disableEventEmitterPatching();
+		cleanupEventEmitterResources();
+
+		
+		if (this.instanceID && this.contextManager) {
+			this.contextManager.cleanup(this.instanceID);
+		}
 
-	async shutdown() {
 		
 		
-		if (this._shutdownInProgress) {
-			if (!this.loaded) return; 
-			console.warn("[slothlet] shutdown already in progress – ignoring nested call.");
-			return; 
+		
+		if (this.handlers.ownership) {
+			this.handlers.ownership.clear();
 		}
-		this._shutdownInProgress = true;
-		try {
-			
-			if (this.loaded) {
-				const TIMEOUT_MS = 5000;
-				let apiError, internalError;
-				if (typeof this._boundAPIShutdown === "function") {
-					try {
-						await Promise.race([
-							this._boundAPIShutdown.call(this.boundapi),
-							new Promise((_, reject) => setTimeout(() => reject(new Error("API shutdown timeout")), TIMEOUT_MS))
-						]);
-					} catch (err) {
-						apiError = err;
-					}
-				}
-				
-				const disposeFn = this.boundapi && typeof this.boundapi.__dispose__ === "function" ? this.boundapi.__dispose__ : this._dispose;
-				if (typeof disposeFn === "function") {
-					try {
-						await disposeFn();
-					} catch (err) {
-						internalError = err;
-					}
-				}
-				this.loaded = false;
-				this.api = null;
-				this.boundapi = {};
-				this.context = {};
-				this.reference = {};
-				this._dispose = null;
-				this._boundAPIShutdown = null;
 
-				
-				if (this.hookManager) {
-					this.hookManager.cleanup();
-					this.hookManager = null;
-				}
+		
+		
+		this.isLoaded = false;
+	}
 
-				
+	
+	debug(code, context = {}) {
+		if (this.debugLogger) {
+			this.debugLogger.log(code, context);
+		}
+	}
 
-				
-				if (this.instanceId) {
-					await cleanupInstance(this.instanceId);
-				}
+	
+	getAPI() {
+		if (!this.isLoaded) {
+			throw new SlothletError(
+				"INVALID_CONFIG_NOT_LOADED",
+				{
+					operation: "getAPI"
+				},
+				null,
+				{ validationError: true }
+			);
+		}
+		return this.boundApi;
+	}
 
-				
-				
-				try {
-					
-					cleanupAllSlothletListeners();
-					
-					disableAlsForEventEmitters();
-				} catch (cleanupError) {
-					
-					console.warn("[slothlet] Warning: EventEmitter cleanup failed:", cleanupError.message);
-				}
+	
+	getDiagnostics() {
+		return {
+			instanceID: this.instanceID,
+			isLoaded: this.isLoaded,
+			config: this.config,
+			context: this.contextManager?.getDiagnostics() || null,
+			ownership: this.handlers.ownership?.getDiagnostics() || null
+		};
+	}
 
-				if (apiError || internalError) throw apiError || internalError;
-			}
-		} finally {
-			
-			this._shutdownInProgress = false;
+	
+	getOwnership() {
+		if (!this.handlers.ownership) {
+			return null;
 		}
+		return this.handlers.ownership.getDiagnostics();
+	}
+
+	
+	buildFinalAPI(userApi) {
+		return this.builders.apiBuilder.buildFinalAPI(userApi);
 	}
-};
+}
 
 
+export async function slothlet(config) {
+	const instance = new Slothlet();
+	const api = await instance.load(config);
+
+	
+	return api;
+}
 
-export { slothlet };
 export default slothlet;