@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/lib/builders/api_builder.mjs

@@ -0,0 +1,1073 @@
+/*
+	Copyright 2026 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+import { TYPE_STATES } from "@cldmv/slothlet/handlers/unified-wrapper";
+import { getLanguage, initI18n, setLanguage, t, translate } from "@cldmv/slothlet/i18n";
+
+
+
+
+function _resolvePathOrModuleId(slothlet, pathOrModuleId) {
+	const history = slothlet.handlers?.apiManager?.state?.addHistory;
+	
+	
+	
+	if (history) {
+		const match = history.findLast((entry) => entry.moduleID === pathOrModuleId);
+		if (match) return match.apiPath;
+	}
+	return pathOrModuleId;
+}
+
+
+export class ApiBuilder extends ComponentBase {
+	static slothletProperty = "apiBuilder";
+
+	
+	constructor(slothlet) {
+		super(slothlet);
+	}
+
+	
+	async buildFinalAPI(userApi) {
+		this.slothlet.debug("api", {
+			key: "DEBUG_MODE_BUILD_FINAL_API_CALLED",
+			diagnostics: this.____config.diagnostics,
+			userApiKeys: Object.keys(userApi)
+		});
+
+		
+		
+		
+
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		if (this.slothlet._ownBuiltins) {
+			for (const [key, ref] of Object.entries(this.slothlet._ownBuiltins)) {
+				if (ref && Object.prototype.hasOwnProperty.call(userApi, key) && userApi[key] === ref) {
+					try {
+						delete userApi[key];
+					} catch (_) {
+						
+					}
+				}
+			}
+		}
+
+		
+		
+		
+		
+		this.slothlet.userHooks = {
+			shutdown: typeof userApi.shutdown === "function" ? userApi.shutdown : null,
+			destroy: typeof userApi.destroy === "function" ? userApi.destroy : null
+		};
+		
+
+		
+		if (userApi.slothlet) {
+			new this.SlothletWarning("WARNING_RESERVED_PROPERTY_CONFLICT", { properties: "slothlet" });
+		}
+
+		
+		const slothletNamespace = await this.createSlothletNamespace(userApi);
+
+		this.slothlet.debug("api", {
+			key: "DEBUG_MODE_SLOTHLET_NAMESPACE_CREATED",
+			namespaceKeys: Object.keys(slothletNamespace),
+			hasDiag: !!slothletNamespace.diag
+		});
+
+		
+		const shutdownFn = this.createShutdownFunction();
+
+		
+		this.attachBuiltins(userApi, {
+			slothlet: slothletNamespace,
+			shutdown: shutdownFn,
+			destroy: null
+		});
+
+		this.slothlet.debug("api", {
+			key: "DEBUG_MODE_BUILT_INS_ATTACHED",
+			userApiKeys: Object.keys(userApi),
+			hasSlothlet: !!userApi.slothlet,
+			hasDiag: !!userApi.slothlet?.diag
+		});
+
+		
+		const destroyWithApi = this.createDestroyFunction(userApi);
+		Object.defineProperty(userApi, "destroy", {
+			value: destroyWithApi,
+			enumerable: true,
+			writable: false,
+			configurable: true
+		});
+
+		
+		
+		this.slothlet._ownBuiltins = {
+			shutdown: shutdownFn,
+			slothlet: slothletNamespace,
+			destroy: destroyWithApi
+		};
+
+		return userApi;
+	}
+
+	
+	async createSlothletNamespace(userApi) {
+		const slothlet = this.slothlet;
+		const config = this.____config;
+
+		
+		let version = "unknown";
+		try {
+			const pkgPath = new URL("../../../package.json", import.meta.url);
+			const { readFile } = await import("node:fs/promises");
+			const pkgContent = await readFile(pkgPath, "utf-8");
+			const pkg = JSON.parse(pkgContent);
+			
+			
+			version = pkg.version || "unknown";
+			
+			
+			
+		} catch {
+			
+		}
+
+		const namespace = {
+			
+			i18n: {
+				setLanguage,
+				getLanguage,
+				translate,
+				t,
+				initI18n
+			},
+
+			
+			version,
+
+			
+			instanceID: slothlet.instanceID,
+
+			
+			types: TYPE_STATES,
+
+			
+			api: {
+				
+				add: async function slothlet_api_add(apiPath, folderPath, options = {}) {
+					
+					if (!config.api?.mutations?.add) {
+						throw new slothlet.SlothletError("INVALID_CONFIG_MUTATIONS_DISABLED", {
+							operation: "api.add",
+							validationError: true
+						});
+					}
+					
+					
+					
+					
+					
+					const {
+						recordHistory: ____recordHistory,
+						collisionMode: ____collisionMode,
+						mutateExisting: ____mutateExisting,
+						...filteredOptions
+					} = options;
+					return slothlet.handlers.apiManager.addApiComponent({
+						apiPath,
+						folderPath,
+						options: filteredOptions
+					});
+				},
+
+				
+				remove: async function slothlet_api_remove(pathOrModuleId) {
+					
+					if (!config.api?.mutations?.remove) {
+						throw new slothlet.SlothletError("INVALID_CONFIG_MUTATIONS_DISABLED", {
+							operation: "api.remove",
+							validationError: true
+						});
+					}
+					if (typeof pathOrModuleId !== "string") {
+						throw new slothlet.SlothletError("INVALID_ARGUMENT", {
+							argument: "pathOrModuleId",
+							expected: "string",
+							received: typeof pathOrModuleId,
+							validationError: true
+						});
+					}
+					return slothlet.handlers.apiManager.removeApiComponent(pathOrModuleId);
+				},
+
+				
+				reload: async function slothlet_api_reload(pathOrModuleId, options) {
+					
+					if (!config.api?.mutations?.reload) {
+						throw new slothlet.SlothletError("INVALID_CONFIG_MUTATIONS_DISABLED", {
+							operation: "api.reload",
+							validationError: true
+						});
+					}
+
+					
+					if (pathOrModuleId == null || pathOrModuleId === "" || pathOrModuleId === ".") {
+						return slothlet.handlers.apiManager.reloadApiComponent({ apiPath: ".", options });
+					}
+
+					if (typeof pathOrModuleId !== "string") {
+						throw new slothlet.SlothletError("INVALID_ARGUMENT", {
+							argument: "pathOrModuleId",
+							expected: "string, null, undefined, or '.'",
+							received: typeof pathOrModuleId,
+							validationError: true
+						});
+					}
+
+					
+					const isModuleId = slothlet.handlers.apiManager.state.addHistory.some((entry) => entry.moduleID === pathOrModuleId);
+
+					if (isModuleId) {
+						return slothlet.handlers.apiManager.reloadApiComponent({ moduleID: pathOrModuleId, options });
+					}
+
+					
+					const normalizedPath = slothlet.handlers.apiManager.normalizeApiPath(pathOrModuleId).apiPath;
+					const pathParts = normalizedPath.split(".");
+					let current = slothlet.api;
+					for (const part of pathParts) {
+						if (!current || (typeof current !== "object" && typeof current !== "function")) {
+							throw new slothlet.SlothletError("INVALID_API_PATH", {
+								apiPath: pathOrModuleId,
+								validationError: true
+							});
+						}
+						current = current[part];
+					}
+
+					if (current === undefined) {
+						throw new slothlet.SlothletError("INVALID_API_PATH", {
+							apiPath: pathOrModuleId,
+							validationError: true
+						});
+					}
+
+					
+					return slothlet.handlers.apiManager.reloadApiComponent({ apiPath: normalizedPath, options });
+				}
+			},
+
+			
+			sanitize: function slothlet_sanitize(str) {
+				if (typeof str !== "string") {
+					throw new slothlet.SlothletError("INVALID_ARGUMENT", {
+						argument: "str",
+						expected: "string",
+						received: typeof str,
+						validationError: true
+					});
+				}
+				return slothlet.helpers.sanitize.sanitizePropertyName(str, slothlet.config.sanitize || {});
+			},
+
+			
+			context: {
+				
+				get: (key) => {
+					
+					
+
+					
+					if (slothlet.contextManager.constructor.name === "LiveContextManager") {
+						const currentID = slothlet.contextManager.currentInstanceID;
+
+						
+						
+						
+						if (currentID) {
+							const activeStore = slothlet.contextManager.instances.get(currentID);
+							const isOurInstance =
+								currentID === slothlet.instanceID ||
+								currentID?.startsWith(slothlet.instanceID + "__run_") ||
+								activeStore?.parentInstanceID === slothlet.instanceID;
+
+							if (isOurInstance && activeStore) {
+								return key ? activeStore.context[key] : { ...activeStore.context };
+							}
+						}
+
+						
+						const store = slothlet.contextManager.instances.get(slothlet.instanceID);
+						
+						
+						
+						if (!store) {
+							const baseContext = slothlet.context || {};
+							return key ? baseContext[key] : { ...baseContext };
+						}
+						
+						
+						return key ? store.context[key] : { ...store.context };
+					}
+
+					
+					if (slothlet.contextManager.constructor.name === "AsyncContextManager") {
+						let currentStore = slothlet.contextManager.tryGetContext();
+
+						
+						
+						if (!currentStore) {
+							const baseStore = slothlet.contextManager.instances.get(slothlet.instanceID);
+							
+							
+							const baseContext = baseStore?.context || {};
+							return key ? baseContext[key] : { ...baseContext };
+							
+						}
+
+						
+						const isOurInstance =
+							currentStore.instanceID === slothlet.instanceID ||
+							currentStore.parentInstanceID === slothlet.instanceID ||
+							currentStore.instanceID.startsWith(slothlet.instanceID + "__run_");
+
+						if (isOurInstance) {
+							
+							return key ? currentStore.context[key] : { ...currentStore.context };
+						}
+
+						
+						const baseStore = slothlet.contextManager.instances.get(slothlet.instanceID);
+						
+						
+						const baseContext = baseStore?.context || {};
+						return key ? baseContext[key] : { ...baseContext };
+						
+					}
+
+					
+					
+					
+					
+					const baseContext = slothlet.context || {};
+					return key ? baseContext[key] : { ...baseContext };
+					
+				},
+
+				
+				diagnostics: () => {
+					
+					
+					
+					
+					if (!slothlet.config?.diagnostics) return undefined;
+					const managerType = slothlet.contextManager.constructor.name;
+					const result = {
+						instanceID: slothlet.instanceID,
+						managerType,
+						instancesMapSize: slothlet.contextManager.instances.size,
+						instancesMapKeys: Array.from(slothlet.contextManager.instances.keys()),
+						baseContext: slothlet.context
+					};
+
+					
+					const store = slothlet.contextManager.instances.get(slothlet.instanceID);
+					
+					
+					
+					result.storeFromInstancesMap = store
+						? {
+								instanceID: store.instanceID,
+								context: store.context,
+								createdAt: store.createdAt
+							}
+						: null;
+
+					
+					if (managerType === "AsyncContextManager") {
+						try {
+							const currentCtx = slothlet.contextManager.tryGetContext();
+							result.currentALSContext = currentCtx
+								? {
+										instanceID: currentCtx.instanceID,
+										context: currentCtx.context,
+										hasParent: !!currentCtx.parentContext,
+										parentInstanceID: currentCtx.parentInstanceID
+									}
+								: null;
+							
+							
+							
+						} catch (____error) {
+							result.currentALSContext = null;
+						}
+						
+					}
+
+					
+					if (managerType === "LiveContextManager") {
+						result.currentInstanceID = slothlet.contextManager.currentInstanceID;
+					}
+
+					return result;
+				},
+
+				
+				run: this.createRunFunction(),
+
+				
+				scope: this.createScopeFunction()
+			},
+
+			
+			hook: {
+				
+				on: function slothlet_hook_on(typePattern, handler, options = {}) {
+					if (!slothlet.handlers?.hookManager) {
+						throw new slothlet.SlothletError("HOOKS_NOT_INITIALIZED", { validationError: true });
+					}
+					return slothlet.handlers.hookManager.on(typePattern, handler, options);
+				},
+
+				
+				remove: function slothlet_hook_remove(filter = {}) {
+					if (!slothlet.handlers?.hookManager) {
+						throw new slothlet.SlothletError("HOOKS_NOT_INITIALIZED", { validationError: true });
+					}
+					return slothlet.handlers.hookManager.remove(filter);
+				},
+
+				
+				clear: function slothlet_hook_clear(filter = {}) {
+					return this.remove(filter);
+				},
+
+				
+				off: function slothlet_hook_off(idOrFilter) {
+					if (!slothlet.handlers?.hookManager) {
+						throw new slothlet.SlothletError("HOOKS_NOT_INITIALIZED", { validationError: true });
+					}
+					
+					const filter = typeof idOrFilter === "string" ? { id: idOrFilter } : idOrFilter;
+					return slothlet.handlers.hookManager.remove(filter);
+				},
+
+				
+				enable: function slothlet_hook_enable(filter = {}) {
+					if (!slothlet.handlers?.hookManager) {
+						throw new slothlet.SlothletError("HOOKS_NOT_INITIALIZED", { validationError: true });
+					}
+					return slothlet.handlers.hookManager.enable(filter);
+				},
+
+				
+				disable: function slothlet_hook_disable(filter = {}) {
+					if (!slothlet.handlers?.hookManager) {
+						throw new slothlet.SlothletError("HOOKS_NOT_INITIALIZED", { validationError: true });
+					}
+					return slothlet.handlers.hookManager.disable(filter);
+				},
+
+				
+				list: function slothlet_hook_list(filter = {}) {
+					if (!slothlet.handlers?.hookManager) {
+						throw new slothlet.SlothletError("HOOKS_NOT_INITIALIZED", { validationError: true });
+					}
+					return slothlet.handlers.hookManager.list(filter);
+				}
+			},
+
+			
+			metadata: {
+				
+				setGlobal: function slothlet_metadata_setGlobal(key, value) {
+					
+					
+					
+					
+					if (!slothlet.handlers?.metadata) {
+						throw new slothlet.SlothletError("METADATA_NOT_AVAILABLE", {
+							handlersKeys: slothlet.handlers ? Object.keys(slothlet.handlers).join(", ") : "undefined",
+							validationError: true
+						});
+					}
+					
+					return slothlet.handlers.metadata.setGlobalMetadata(key, value);
+				},
+
+				
+				set: function slothlet_metadata_set(fn, key, value) {
+					if (!slothlet.handlers?.metadata) {
+						throw new slothlet.SlothletError("METADATA_NOT_AVAILABLE", {
+							handlersKeys: slothlet.handlers
+								? Object.keys(slothlet.handlers).join(", ")
+								: 
+									
+									"undefined",
+							validationError: true
+						});
+					}
+					return slothlet.handlers.metadata.setUserMetadata(fn, key, value);
+				},
+
+				
+				remove: function slothlet_metadata_remove(fn, key) {
+					return slothlet.handlers.metadata.removeUserMetadata(fn, key);
+				},
+
+				
+				setFor: function slothlet_metadata_setFor(pathOrModuleId, keyOrObj, value) {
+					if (!slothlet.handlers?.metadata) {
+						throw new slothlet.SlothletError("METADATA_NOT_AVAILABLE", {
+							handlersKeys: slothlet.handlers
+								? Object.keys(slothlet.handlers).join(", ")
+								: 
+									
+									"undefined",
+							validationError: true
+						});
+					}
+					const resolvedPath = _resolvePathOrModuleId(slothlet, pathOrModuleId);
+					return slothlet.handlers.metadata.setPathMetadata(resolvedPath, keyOrObj, value);
+				},
+
+				
+				removeFor: function slothlet_metadata_removeFor(pathOrModuleId, key) {
+					if (!slothlet.handlers?.metadata) return;
+					const resolvedPath = _resolvePathOrModuleId(slothlet, pathOrModuleId);
+					return slothlet.handlers.metadata.removePathMetadata(resolvedPath, key);
+				}
+			},
+
+			
+			scope: this.createScopeFunction(),
+
+			
+			run: this.createRunFunction(),
+
+			
+			reload: async (options = {}) => {
+				
+				if (!config.api?.mutations?.reload) {
+					throw new slothlet.SlothletError("INVALID_CONFIG_MUTATIONS_DISABLED", {
+						operation: "reload",
+						validationError: true
+					});
+				}
+				return slothlet.reload(options);
+			},
+
+			
+			shutdown: async () => {
+				return slothlet.shutdown();
+			},
+
+			
+			owner: {
+				
+				get: (apiPath) => {
+					if (slothlet.handlers?.ownership) {
+						return slothlet.handlers.ownership.getPathOwnership(apiPath);
+					}
+					return null;
+				}
+			},
+
+			
+			materialize: (() => {
+				const mgr = slothlet.handlers?.materialize;
+				
+				
+				if (!mgr) {
+					return Object.freeze({
+						materialized: false,
+						get: () => ({ total: 0, materialized: 0, remaining: 0, percentage: 100 }),
+						wait: async () => {}
+					});
+				}
+				
+				return Object.freeze({
+					get materialized() {
+						return mgr.materialized;
+					},
+					get: mgr.get.bind(mgr),
+					wait: mgr.wait.bind(mgr)
+				});
+			})(),
+
+			
+			lifecycle: (() => {
+				const handler = slothlet.handlers?.lifecycle;
+				const noop = () => {};
+				if (!handler) return { on: noop, off: noop };
+				return {
+					on: handler.on.bind(handler),
+					off: handler.off.bind(handler)
+				};
+			})()
+		};
+
+		
+		
+		if (!config.hook?.enabled && config.diagnostics !== true) {
+			delete namespace.hooks;
+		}
+
+		
+		if (config.diagnostics === true) {
+			namespace.diag = {
+				
+				describe: (showAll = false) => {
+					if (showAll) {
+						
+						return { ...userApi };
+					}
+					
+					return Reflect.ownKeys(userApi);
+				},
+
+				
+				reference: slothlet.reference || null,
+
+				
+				context: slothlet.context || {},
+
+				
+				inspect: () => {
+					return slothlet.getDiagnostics();
+				},
+
+				
+				getAPI: () => {
+					return slothlet.getAPI();
+				},
+
+				
+				getOwnership: () => {
+					return slothlet.getOwnership();
+				},
+
+				
+				owner: {
+					
+					get: (apiPath) => {
+						if (slothlet.handlers?.ownership) {
+							return slothlet.handlers.ownership.getPathOwnership(apiPath);
+						}
+						return null;
+					}
+				},
+
+				
+				caches: {
+					
+					get: () => {
+						if (slothlet.handlers?.apiCacheManager) {
+							return slothlet.handlers.apiCacheManager.getCacheDiagnostics();
+						}
+						return { totalCaches: 0, caches: [] };
+					},
+
+					
+					getAllModuleIDs: () => {
+						if (slothlet.handlers?.apiCacheManager) {
+							return slothlet.handlers.apiCacheManager.getAllModuleIDs();
+						}
+						return [];
+					},
+
+					
+					has: (moduleID) => {
+						if (slothlet.handlers?.apiCacheManager) {
+							return slothlet.handlers.apiCacheManager.has(moduleID);
+						}
+						return false;
+					}
+				},
+
+				
+				SlothletWarning: slothlet.SlothletWarning,
+
+				
+				
+				
+				hook: slothlet.handlers?.hookManager
+					? {
+							
+							get enabled() {
+								return slothlet.handlers.hookManager.enabled;
+							},
+
+							
+							compilePattern: (pattern) => {
+								return slothlet.handlers.hookManager.getCompilePatternForDiagnostics()(pattern);
+							}
+						}
+					: undefined
+				
+			};
+		}
+
+		return namespace;
+	}
+
+	
+	createShutdownFunction() {
+		const slothlet = this.slothlet;
+		const shutdownFunction = {
+			shutdown: async () => {
+				
+				if (slothlet.userHooks?.shutdown && typeof slothlet.userHooks.shutdown === "function") {
+					await slothlet.userHooks.shutdown();
+				}
+				return slothlet.shutdown();
+			}
+		}.shutdown;
+		return shutdownFunction;
+	}
+
+	
+	createRunFunction() {
+		const slothlet = this.slothlet;
+		
+		const scopeFunc = this.createScopeFunction();
+
+		const runFunction = {
+			run: async (contextData, callback, ...args) => {
+				
+				if (slothlet.config.scope === false) {
+					throw new slothlet.SlothletError("SCOPE_DISABLED", {}, null, { validationError: true });
+				}
+
+				
+				if (!contextData || typeof contextData !== "object") {
+					throw new slothlet.SlothletError("SCOPE_INVALID_CONTEXT", { received: typeof contextData }, null, { validationError: true });
+				}
+				if (typeof callback !== "function") {
+					throw new slothlet.SlothletError("SCOPE_INVALID_CALLBACK", { received: typeof callback }, null, { validationError: true });
+				}
+
+				
+				
+				return scopeFunc({
+					context: contextData,
+					fn: callback,
+					args: args,
+					merge: slothlet.config.scope?.merge || "shallow",
+					isolation: slothlet.config.scope?.isolation || "partial"
+				});
+			}
+		}.run;
+		return runFunction;
+	}
+
+	
+	createScopeFunction() {
+		const slothlet = this.slothlet;
+		const scopeFunction = {
+			scope: async (options) => {
+				
+				if (slothlet.config.scope === false) {
+					throw new slothlet.SlothletError("SCOPE_DISABLED", {}, null, { validationError: true });
+				}
+
+				
+				if (!options || typeof options !== "object") {
+					throw new slothlet.SlothletError("SCOPE_INVALID_OPTIONS", { received: typeof options }, null, { validationError: true });
+				}
+				if (!options.fn || typeof options.fn !== "function") {
+					throw new slothlet.SlothletError("SCOPE_INVALID_FN", { received: typeof options?.fn }, null, { validationError: true });
+				}
+				if (!options.context || typeof options.context !== "object") {
+					throw new slothlet.SlothletError("SCOPE_INVALID_CONTEXT_OBJECT", { received: typeof options?.context }, null, {
+						validationError: true
+					});
+				}
+
+				const { context: contextData, fn, args = [], merge = "shallow", isolation } = options;
+
+				
+				if (merge !== "shallow" && merge !== "deep") {
+					throw new slothlet.SlothletError("SCOPE_INVALID_MERGE_STRATEGY", { merge }, null, { validationError: true });
+				}
+
+				
+				const isolationMode = isolation || slothlet.config.scope?.isolation || "partial";
+
+				
+				if (isolationMode !== "partial" && isolationMode !== "full") {
+					throw new slothlet.SlothletError("SCOPE_INVALID_ISOLATION_MODE", { isolationMode }, null, { validationError: true });
+				}
+
+				
+				const contextManager = slothlet.contextManager;
+				if (!contextManager) {
+					throw new slothlet.SlothletError("NO_CONTEXT_MANAGER", { validationError: true });
+				}
+
+				const { utilities } = slothlet.helpers;
+
+				
+				if (contextManager.constructor.name === "LiveContextManager") {
+					
+					let currentStore = null;
+
+					
+					const currentID = contextManager.currentInstanceID;
+					if (currentID) {
+						const activeStore = contextManager.instances.get(currentID);
+						const isOurContext =
+							currentID === slothlet.instanceID ||
+							activeStore?.parentInstanceID === slothlet.instanceID ||
+							currentID.startsWith(slothlet.instanceID + "__run_");
+
+						if (isOurContext) {
+							currentStore = activeStore;
+						}
+					}
+
+					
+					if (!currentStore) {
+						currentStore = contextManager.instances.get(slothlet.instanceID);
+					}
+
+					if (!currentStore) {
+						throw new slothlet.SlothletError("CONTEXT_NOT_FOUND", {
+							instanceID: slothlet.instanceID,
+							availableInstances: [...contextManager.instances.keys()].join(", ") || "none",
+							validationError: true
+						});
+					}
+
+					
+					
+					let mergedContext;
+					if (merge === "deep") {
+						mergedContext = utilities.deepMerge(currentStore.context, contextData);
+						
+						mergedContext = structuredClone(mergedContext);
+					} else {
+						
+						const clonedParent = structuredClone(currentStore.context);
+						mergedContext = { ...clonedParent, ...contextData };
+					}
+
+					
+					const childInstanceID = `${slothlet.instanceID}__run_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+					const childStore = {
+						instanceID: childInstanceID,
+						context: mergedContext,
+						self: isolationMode === "full" ? utilities.deepClone(currentStore.self) : currentStore.self,
+						config: currentStore.config,
+						createdAt: currentStore.createdAt,
+						parentInstanceID: slothlet.instanceID
+					};
+
+					
+					contextManager.instances.set(childInstanceID, childStore);
+					const previousInstanceID = contextManager.currentInstanceID;
+
+					try {
+						
+						contextManager.currentInstanceID = childInstanceID;
+
+						
+						return await fn(...args);
+					} finally {
+						
+						contextManager.currentInstanceID = previousInstanceID;
+						contextManager.instances.delete(childInstanceID);
+					}
+				}
+
+				
+				if (contextManager.constructor.name === "AsyncContextManager") {
+					
+					let currentStore = null;
+
+					
+					const activeStore = contextManager.tryGetContext();
+					if (activeStore) {
+						const isOurContext =
+							activeStore.instanceID === slothlet.instanceID ||
+							activeStore.parentInstanceID === slothlet.instanceID ||
+							activeStore.instanceID.startsWith(slothlet.instanceID + "__run_");
+
+						if (isOurContext) {
+							currentStore = activeStore;
+						}
+					}
+
+					
+					if (!currentStore) {
+						const baseStore = contextManager.instances.get(slothlet.instanceID);
+						if (!baseStore) {
+							throw new slothlet.SlothletError("CONTEXT_NOT_FOUND", {
+								instanceID: slothlet.instanceID,
+								availableInstances: [...contextManager.instances.keys()].join(", ") || "none",
+								validationError: true
+							});
+						}
+						currentStore = baseStore;
+					}
+
+					
+					
+					let mergedContext;
+					if (merge === "deep") {
+						mergedContext = utilities.deepMerge(currentStore.context, contextData);
+						
+						mergedContext = structuredClone(mergedContext);
+					} else {
+						
+						const clonedParent = structuredClone(currentStore.context);
+						mergedContext = { ...clonedParent, ...contextData };
+					}
+
+					
+					const childInstanceID = `${slothlet.instanceID}__run_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+					const childStore = {
+						instanceID: childInstanceID,
+						context: mergedContext,
+						self: isolationMode === "full" ? utilities.deepClone(currentStore.self) : currentStore.self,
+						config: currentStore.config,
+						createdAt: currentStore.createdAt,
+						parentInstanceID: slothlet.instanceID
+					};
+
+					
+					contextManager.instances.set(childInstanceID, childStore);
+
+					try {
+						
+						return await contextManager.als.run(childStore, async () => {
+							return await fn(...args);
+						});
+					} finally {
+						
+						contextManager.instances.delete(childInstanceID);
+					}
+				}
+
+				throw new slothlet.SlothletError("UNSUPPORTED_CONTEXT_MANAGER", {
+					manager: contextManager.constructor.name,
+					validationError: true
+				});
+			}
+		}.scope;
+		return scopeFunction;
+	}
+
+	
+	createDestroyFunction(api) {
+		const slothlet = this.slothlet;
+		const destroyFunction = {
+			destroy: async () => {
+				
+				if (slothlet.userHooks?.destroy && typeof slothlet.userHooks.destroy === "function") {
+					await slothlet.userHooks.destroy();
+				}
+
+				
+				if (api && typeof api.shutdown === "function") {
+					await api.shutdown();
+				} else {
+					
+					await slothlet.shutdown();
+				}
+
+				
+				
+				
+				slothlet.isDestroyed = true;
+
+				
+				const objectsToClear = [api, slothlet.api].filter((obj) => obj && typeof obj === "object");
+
+				for (const obj of objectsToClear) {
+					const keys = Object.keys(obj);
+					for (const key of keys) {
+						try {
+							delete obj[key];
+						} catch (_) {
+							
+						}
+					}
+				}
+
+				
+				slothlet.api = null;
+			}
+		}.destroy;
+		return destroyFunction;
+	}
+
+	
+	attachBuiltins(userApi, builtins) {
+		
+		
+		Object.defineProperty(userApi, "slothlet", {
+			value: builtins.slothlet,
+			enumerable: true,
+			writable: false,
+			configurable: true
+		});
+
+		
+		Object.defineProperty(userApi, "shutdown", {
+			value: builtins.shutdown,
+			enumerable: true,
+			writable: false,
+			configurable: true
+		});
+
+		
+		
+		
+		
+		
+		if (builtins.destroy !== null) {
+			Object.defineProperty(userApi, "destroy", {
+				value: builtins.destroy,
+				enumerable: true,
+				writable: false,
+				configurable: true
+			});
+		}
+		
+	}
+}