@cldmv/slothlet 2.11.0 → 3.0.0

package/dist/lib/handlers/api-manager.mjs

@@ -0,0 +1,2364 @@
+/*
+	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 fs from "node:fs/promises";
+import path from "node:path";
+import { translate } from "@cldmv/slothlet/i18n";
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+import { UnifiedWrapper, resolveWrapper } from "@cldmv/slothlet/handlers/unified-wrapper";
+
+
+export class ApiManager extends ComponentBase {
+	static slothletProperty = "apiManager";
+
+	
+	constructor(slothlet) {
+		super(slothlet);
+		this.state = {
+			addHistory: [],
+			
+			
+			initialConfig: slothlet?.config || null,
+			operationHistory: [] 
+		};
+	}
+
+	
+	normalizeApiPath(apiPath) {
+		
+		if (apiPath === "" || apiPath === null || apiPath === undefined) {
+			return { apiPath: "", parts: [] };
+		}
+
+		
+		if (Array.isArray(apiPath)) {
+			
+			if (apiPath.length === 0) {
+				return { apiPath: "", parts: [] };
+			}
+
+			for (let i = 0; i < apiPath.length; i++) {
+				if (typeof apiPath[i] !== "string") {
+					throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+						apiPath,
+						segment: apiPath[i],
+						index: i,
+						reason: translate("API_PATH_REASON_ARRAY_ELEMENTS"),
+						validationError: true
+					});
+				}
+				if (apiPath[i].trim() === "") {
+					throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+						apiPath,
+						segment: apiPath[i],
+						index: i,
+						reason: translate("API_PATH_REASON_ARRAY_EMPTY_SEGMENTS"),
+						validationError: true
+					});
+				}
+			}
+
+			
+			if (apiPath[0] === "slothlet" || (apiPath.length === 1 && (apiPath[0] === "shutdown" || apiPath[0] === "destroy"))) {
+				throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+					apiPath,
+					reason: translate("API_PATH_REASON_RESERVED_NAME"),
+					index: undefined,
+					segment: undefined,
+					validationError: true
+				});
+			}
+
+			return { apiPath: apiPath.join("."), parts: apiPath };
+		}
+
+		if (typeof apiPath !== "string") {
+			throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+				apiPath,
+				reason: translate("API_PATH_REASON_INVALID_TYPE"),
+				index: undefined,
+				segment: undefined,
+				validationError: true
+			});
+		}
+
+		const normalized = apiPath.trim();
+
+		
+		if (normalized === "") {
+			return { apiPath: "", parts: [] };
+		}
+
+		const parts = normalized.split(".");
+		if (parts.length === 0 || parts.some((part) => part.trim() === "")) {
+			throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+				apiPath: normalized,
+				reason: translate("API_PATH_REASON_EMPTY_SEGMENTS"),
+				index: undefined,
+				segment: undefined,
+				validationError: true
+			});
+		}
+
+		if (parts[0] === "slothlet" || normalized === "shutdown" || normalized === "destroy") {
+			throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+				apiPath: normalized,
+				reason: translate("API_PATH_REASON_RESERVED_NAME"),
+				index: undefined,
+				segment: undefined,
+				validationError: true
+			});
+		}
+
+		return { apiPath: normalized, parts };
+	}
+
+	
+	async resolvePath(inputPath) {
+		if (!inputPath || typeof inputPath !== "string") {
+			throw new this.SlothletError("INVALID_CONFIG_DIR_INVALID", {
+				dir: inputPath,
+				validationError: true
+			});
+		}
+
+		const resolvedPath = this.slothlet.helpers.resolver.resolvePathFromCaller(inputPath);
+		try {
+			const stats = await fs.stat(resolvedPath);
+			return {
+				resolvedPath,
+				isDirectory: stats.isDirectory(),
+				isFile: stats.isFile()
+			};
+		} catch (error) {
+			
+			
+			
+			
+			if (error instanceof this.SlothletError) {
+				throw error;
+			}
+			
+			
+			throw new this.SlothletError("INVALID_CONFIG_DIR_INVALID", {
+				dir: resolvedPath,
+				validationError: true
+			});
+		}
+	}
+
+	
+	async resolveFolderPath(folderPath) {
+		if (!folderPath || typeof folderPath !== "string") {
+			throw new this.SlothletError("INVALID_CONFIG_DIR_INVALID", {
+				dir: folderPath,
+				validationError: true
+			});
+		}
+
+		const resolvedPath = this.slothlet.helpers.resolver.resolvePathFromCaller(folderPath);
+		try {
+			const stats = await fs.stat(resolvedPath);
+			if (!stats.isDirectory()) {
+				throw new this.SlothletError("INVALID_CONFIG_DIR_INVALID", {
+					dir: resolvedPath,
+					validationError: true
+				});
+			}
+		} catch (error) {
+			if (error instanceof this.SlothletError) {
+				throw error;
+			}
+			throw new this.SlothletError("INVALID_CONFIG_DIR_INVALID", {
+				dir: resolvedPath,
+				validationError: true
+			});
+		}
+
+		return resolvedPath;
+	}
+
+	
+	buildDefaultModuleId(apiPath, ____resolvedFolderPath) {
+		const randomSuffix = Math.random().toString(36).substring(2, 8);
+		const prefix = apiPath || "auto";
+		return `${prefix}_${randomSuffix}`;
+	}
+
+	
+	getValueAtPath(root, parts) {
+		let current = root;
+		for (const part of parts) {
+			if (!current || (typeof current !== "object" && typeof current !== "function")) {
+				return undefined;
+			}
+			current = current[part];
+		}
+		return current;
+	}
+
+	
+	ensureParentPath(root, parts, options = {}) {
+		const { moduleID, sourceFolder } = options;
+		let current = root;
+		for (let i = 0; i < parts.length - 1; i += 1) {
+			const part = parts[i];
+			const next = current[part];
+			if (next === undefined) {
+				
+				const containerPath = parts.slice(0, i + 1).join(".");
+				const containerWrapper = new UnifiedWrapper(this.slothlet, {
+					mode: this.____config.mode,
+					apiPath: containerPath,
+					moduleID: moduleID,
+					sourceFolder: sourceFolder
+				});
+				
+				containerWrapper.___setImpl({}, moduleID);
+				current[part] = containerWrapper.createProxy();
+				current = current[part];
+				continue;
+			}
+			if (next && (typeof next === "object" || typeof next === "function")) {
+				current = next;
+				continue;
+			}
+			throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+				apiPath: parts.slice(0, i + 1).join("."),
+				reason: translate("API_PATH_REASON_NOT_TRAVERSABLE"),
+				index: undefined,
+				segment: undefined,
+				validationError: true
+			});
+		}
+		return current;
+	}
+
+	
+	isWrapperProxy(value) {
+		return !!(value && (typeof value === "object" || typeof value === "function") && resolveWrapper(value) !== null);
+	}
+
+	
+	async syncWrapper(existingProxy, nextProxy, config, collisionMode = "replace", moduleID = null) {
+		if (config?.debug?.api) {
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_SYNC_WRAPPER_ENTRY_EXISTING",
+				apiPath: resolveWrapper(existingProxy)?.apiPath
+			});
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_SYNC_WRAPPER_ENTRY_NEXT",
+				apiPath: resolveWrapper(nextProxy)?.apiPath
+			});
+		}
+
+		
+		
+		if (!this.isWrapperProxy(existingProxy) || !this.isWrapperProxy(nextProxy)) {
+			return false;
+		}
+
+		
+		
+		const existingWrapper = resolveWrapper(existingProxy) ?? existingProxy;
+		
+		
+		const nextWrapper = resolveWrapper(nextProxy) ?? nextProxy;
+
+		if (config?.debug?.api) {
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_SYNC_WRAPPER_EXISTING",
+				apiPath: existingWrapper.apiPath
+			});
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_SYNC_WRAPPER_NEXT",
+				apiPath: nextWrapper.apiPath
+			});
+		}
+
+		
+		
+		
+		
+		if (nextWrapper.____slothletInternal.materializeFunc && collisionMode !== "merge") {
+			existingWrapper.____slothletInternal.materializeFunc = nextWrapper.____slothletInternal.materializeFunc;
+		}
+
+		
+		
+		
+		
+		const existingChildKeys = Object.keys(existingWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+		const nextChildKeys = Object.keys(nextWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+
+		if (config?.debug?.api) {
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_SYNC_WRAPPER_BEFORE_MERGE",
+				existingCacheSize: existingChildKeys.length,
+				nextCacheSize: nextChildKeys.length
+			});
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_SYNC_WRAPPER_NEXT_IMPL_KEYS",
+				
+				
+				implKeys: Object.keys(nextWrapper.____slothletInternal.impl || {})
+			});
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_SYNC_WRAPPER_NEXT_CHILDCACHE_KEYS",
+				childCacheKeys: nextChildKeys
+			});
+		}
+
+		
+		
+		
+		
+		if (collisionMode === "replace") {
+			
+			
+			
+			
+			if (existingWrapper.___setImpl && nextWrapper.____slothletInternal.impl !== undefined) {
+				
+				existingWrapper.___setImpl(nextWrapper.____slothletInternal.impl, moduleID);
+				
+				
+				
+				
+				
+			} else if (nextWrapper.____slothletInternal.impl === undefined) {
+				
+				
+				existingWrapper.____slothletInternal.impl = null;
+			} else {
+				
+				
+				
+				
+				if (nextWrapper.____slothletInternal.impl !== undefined) {
+					existingWrapper.____slothletInternal.impl = nextWrapper.____slothletInternal.impl;
+					
+					if (
+						typeof nextWrapper.____slothletInternal.impl === "function" ||
+						(nextWrapper.____slothletInternal.impl && typeof nextWrapper.____slothletInternal.impl.default === "function")
+					) {
+						existingWrapper.isCallable = true;
+					}
+				}
+				
+			}
+
+			
+			for (const key of existingChildKeys) {
+				delete existingWrapper[key];
+			}
+			existingWrapper.___adoptImplChildren();
+
+			
+			
+			for (const key of nextChildKeys) {
+				const childValue = nextWrapper[key];
+				Object.defineProperty(existingWrapper, key, {
+					value: childValue,
+					writable: false,
+					enumerable: true,
+					configurable: true
+				});
+			}
+		} else if (collisionMode === "merge") {
+			
+			
+			
+			
+			for (const key of nextChildKeys) {
+				const isInternal = typeof key === "string" && (key.startsWith("_") || key.startsWith("__"));
+				
+				
+				if (!isInternal && !Object.prototype.hasOwnProperty.call(existingWrapper, key)) {
+					const childValue = nextWrapper[key];
+					Object.defineProperty(existingWrapper, key, {
+						value: childValue,
+						writable: false,
+						enumerable: true,
+						configurable: true
+					});
+				} else if (!isInternal) {
+					
+					
+					const existingChild = existingWrapper[key];
+					const nextChild = nextWrapper[key];
+					if (this.isWrapperProxy(existingChild) && this.isWrapperProxy(nextChild)) {
+						
+						
+						const syncWrapper_nextChildWrapper = resolveWrapper(nextChild) ?? nextChild;
+						const syncWrapper_hasGrandChildren = Object.keys(syncWrapper_nextChildWrapper).some(
+							(k) => !k.startsWith("_") && !k.startsWith("__")
+						);
+						if (syncWrapper_hasGrandChildren) {
+							await this.syncWrapper(existingChild, nextChild, config, collisionMode, moduleID);
+						}
+					}
+				}
+				
+			}
+			
+			
+		} else if (collisionMode === "merge-replace") {
+			
+			for (const key of nextChildKeys) {
+				const childValue = nextWrapper[key];
+				const isInternal = typeof key === "string" && (key.startsWith("_") || key.startsWith("__"));
+				
+				if (!isInternal && Object.prototype.hasOwnProperty.call(existingWrapper, key)) {
+					
+					const existingChild = existingWrapper[key];
+					if (this.isWrapperProxy(existingChild) && this.isWrapperProxy(childValue)) {
+						await this.syncWrapper(existingChild, childValue, config, collisionMode, moduleID);
+					} else {
+						
+						delete existingWrapper[key];
+						Object.defineProperty(existingWrapper, key, {
+							value: childValue,
+							writable: false,
+							enumerable: true,
+							configurable: true
+						});
+					}
+					
+					
+				} else if (!isInternal) {
+					
+					Object.defineProperty(existingWrapper, key, {
+						value: childValue,
+						writable: false,
+						enumerable: true,
+						configurable: true
+					});
+				}
+			}
+		}
+		
+
+		
+		
+		
+		if (existingWrapper.____slothletInternal.state) {
+			
+			const isActuallyMaterialized =
+				existingWrapper.____slothletInternal.impl && typeof existingWrapper.____slothletInternal.impl !== "function";
+			existingWrapper.____slothletInternal.state.materialized = isActuallyMaterialized;
+			existingWrapper.____slothletInternal.state.inFlight = false;
+		}
+
+		return true;
+	}
+
+	
+	async mutateApiValue(existingValue, nextValue, options, config) {
+		if (config?.debug?.api) {
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_MUTATE_API_VALUE_CALLED",
+				existingType: typeof existingValue,
+				nextType: typeof nextValue
+			});
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_MUTATE_API_VALUE_WRAPPER_STATUS",
+				existingIsWrapper: this.isWrapperProxy(existingValue),
+				nextIsWrapper: this.isWrapperProxy(nextValue)
+			});
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_MUTATE_API_VALUE_NEXT_VALUE",
+				nextValue
+			});
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_MUTATE_API_VALUE_NEXT_VALUE_KEYS",
+				
+				
+				nextValueKeys: nextValue ? Object.keys(nextValue) : []
+			});
+		}
+
+		if (existingValue === nextValue) {
+			return;
+		}
+
+		
+		if (this.isWrapperProxy(existingValue) && this.isWrapperProxy(nextValue)) {
+			if (config?.debug?.api) {
+				this.slothlet.debug("api", {
+					key: "DEBUG_MODE_MUTATE_API_VALUE_SYNC_WRAPPERS"
+				});
+			}
+			await this.syncWrapper(existingValue, nextValue, config, options.collisionMode, options.moduleID);
+			return;
+		}
+
+		
+		
+		if (this.isWrapperProxy(existingValue) && !this.isWrapperProxy(nextValue)) {
+			
+			const nextIsObjectLike = nextValue && (typeof nextValue === "object" || typeof nextValue === "function");
+			const nextHasKeys = nextIsObjectLike && Object.keys(nextValue).length > 0;
+
+			if (nextHasKeys) {
+				if (config?.debug?.api) {
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_MUTATE_API_VALUE_MERGE_INTO_WRAPPER"
+					});
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_MUTATE_API_VALUE_MERGE_KEYS",
+						keys: Object.keys(nextValue)
+					});
+				}
+				
+				await this.slothlet.builders.apiAssignment.mergeApiObjects(existingValue, nextValue, {
+					removeMissing: options.removeMissing,
+					mutateExisting: true,
+					allowOverwrite: true,
+					syncWrapper: this.syncWrapper.bind(this),
+					collisionMode: options.collisionMode,
+					moduleID: options.moduleID
+				});
+				return;
+			}
+
+			
+			const existingValueRaw = resolveWrapper(existingValue);
+			
+			
+			if (existingValueRaw !== null) {
+				if (config?.debug?.api) {
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_MUTATE_API_VALUE_SETIMPL_FALLBACK"
+					});
+				}
+				existingValueRaw.___setImpl(resolveWrapper(nextValue)?.__impl ?? nextValue);
+				return;
+			}
+		}
+
+		
+		if (existingValue && typeof existingValue === "object" && nextValue && typeof nextValue === "object") {
+			await this.slothlet.builders.apiAssignment.mergeApiObjects(existingValue, nextValue, {
+				removeMissing: options.removeMissing,
+				mutateExisting: true,
+				allowOverwrite: true,
+				syncWrapper: this.syncWrapper.bind(this),
+				collisionMode: options.collisionMode,
+				moduleID: options.moduleID
+			});
+			return existingValue;
+		}
+
+		
+		return nextValue;
+	}
+
+	
+	async setValueAtPath(root, parts, value, options) {
+		const parent = this.ensureParentPath(root, parts, {
+			moduleID: options.moduleID,
+			sourceFolder: options.sourceFolder
+		});
+		const finalKey = parts[parts.length - 1];
+		
+		
+		const existing = parent ? parent[finalKey] : undefined;
+		
+		
+		const collisionMode = options.collisionMode || "merge";
+		const moduleID = options.moduleID; 
+
+		this.slothlet.debug("api", {
+			key: "DEBUG_MODE_SET_VALUE_AT_PATH",
+			finalKey,
+			existingType: typeof existing,
+			valueType: typeof value,
+			collisionMode,
+			options
+		});
+
+		
+		if (existing !== undefined) {
+			if (collisionMode === "error") {
+				throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+					apiPath: parts.join("."),
+					reason: translate("API_PATH_REASON_COLLISION_ERROR"),
+					index: undefined,
+					segment: undefined,
+					validationError: true
+				});
+			}
+
+			if (collisionMode === "skip") {
+				this.slothlet.debug("api", {
+					key: "DEBUG_MODE_SET_VALUE_AT_PATH_SKIP_COLLISION",
+					path: parts.join("."),
+					mode: "skip"
+				});
+				return false;
+			}
+
+			if (collisionMode === "warn") {
+				if (this.slothlet && !this.____config?.silent) {
+					new this.SlothletWarning("WARNING_HOT_RELOAD_PATH_COLLISION", {
+						apiPath: parts.join(".")
+					});
+				}
+				return false;
+			}
+
+			if (collisionMode === "replace") {
+				const existingIsObject = typeof existing === "object" || typeof existing === "function";
+				const valueIsObject = typeof value === "object" || typeof value === "function";
+
+				if (existingIsObject && valueIsObject) {
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_SET_VALUE_AT_PATH_REPLACE_MERGE",
+						path: parts.join("."),
+						mode: "replace"
+					});
+					
+					await this.mutateApiValue(
+						existing,
+						value,
+						{ removeMissing: false, allowOverwrite: true, collisionMode: "replace", moduleID },
+						this.____config
+					);
+					return true;
+				} else {
+					
+					parent[finalKey] = value;
+					return true;
+				}
+			}
+
+			
+			
+			if (collisionMode === "merge" || collisionMode === "merge-replace") {
+				const existingIsObject = typeof existing === "object" || typeof existing === "function";
+				const valueIsObject = typeof value === "object" || typeof value === "function";
+
+				if (existingIsObject && valueIsObject) {
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_SET_VALUE_AT_PATH_MERGE_PROPS",
+						mode: collisionMode
+					});
+					await this.mutateApiValue(existing, value, { removeMissing: false, allowOverwrite: true, collisionMode }, this.____config);
+					return true;
+				} else {
+					
+					if (this.slothlet && !this.____config?.silent) {
+						new this.SlothletWarning("WARNING_HOT_RELOAD_MERGE_PRIMITIVES", {
+							apiPath: parts.join(".")
+						});
+					}
+					return false;
+				}
+			}
+		}
+
+		
+		this.slothlet.debug("api", {
+			key: "DEBUG_MODE_SET_VALUE_AT_PATH_ASSIGN",
+			finalKey
+		});
+		parent[finalKey] = value;
+		return true;
+	}
+
+	
+	async deletePath(root, parts) {
+		let current = root;
+		const stack = [];
+		for (const part of parts.slice(0, -1)) {
+			if (!current || (typeof current !== "object" && typeof current !== "function")) {
+				return false;
+			}
+			stack.push({ parent: current, key: part });
+			current = current[part];
+		}
+
+		const finalKey = parts[parts.length - 1];
+		if (!current || (typeof current !== "object" && typeof current !== "function")) {
+			return false;
+		}
+		if (!Object.prototype.hasOwnProperty.call(current, finalKey)) {
+			return false;
+		}
+
+		
+		const removedImpl = current[finalKey];
+		const apiPath = parts.join(".");
+
+		
+		if (removedImpl && this.slothlet.handlers?.lifecycle) {
+			const metadata = this.slothlet.handlers.metadata?.getMetadata?.(removedImpl);
+			await this.slothlet.handlers.lifecycle.emit("impl:removed", {
+				apiPath,
+				impl: removedImpl,
+				source: "removal",
+				moduleID: metadata?.moduleID,
+				filePath: metadata?.filePath,
+				sourceFolder: metadata?.sourceFolder
+			});
+		}
+
+		
+		
+		if (resolveWrapper(current)) {
+			const wrapper = resolveWrapper(current);
+			
+			const isInternal = typeof finalKey === "string" && (finalKey.startsWith("_") || finalKey.startsWith("__"));
+			if (!isInternal && finalKey in wrapper) {
+				delete wrapper[finalKey];
+			}
+			
+			if (wrapper.____slothletInternal.impl && typeof wrapper.____slothletInternal.impl === "object") {
+				delete wrapper.____slothletInternal.impl[finalKey];
+			}
+		}
+
+		
+		delete current[finalKey];
+
+		
+		
+		
+		if (removedImpl && (typeof removedImpl === "object" || typeof removedImpl === "function")) {
+			
+			
+			
+			if (resolveWrapper(removedImpl)) {
+				const wrapper = resolveWrapper(removedImpl);
+				
+				if (wrapper.____slothletInternal.impl !== undefined) {
+					wrapper.____slothletInternal.impl = null;
+				}
+				
+				const childKeys = Object.keys(wrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+				for (const key of childKeys) {
+					delete wrapper[key];
+				}
+				
+				
+				
+				if (wrapper.____slothletInternal.state) {
+					wrapper.____slothletInternal.state.materialized = false;
+					wrapper.____slothletInternal.state.inFlight = false;
+				}
+			}
+		}
+
+		
+		
+		
+		if (this.slothlet.handlers?.metadata) {
+			const rootSegment = apiPath.split(".")[0];
+			this.slothlet.handlers.metadata.removeUserMetadataByApiPath(rootSegment);
+		}
+
+		for (let i = stack.length - 1; i >= 0; i -= 1) {
+			const { parent, key } = stack[i];
+			const value = parent[key];
+			if (value && (typeof value === "object" || typeof value === "function") && Object.keys(value).length === 0) {
+				delete parent[key];
+			}
+		}
+
+		return true;
+	}
+	
+	async restoreApiPath(apiPath, moduleID) {
+		
+		
+		const normalizedModuleId = moduleID || null;
+		const historyEntry = this.state.addHistory
+			.slice()
+			.reverse()
+			
+			
+			.find((entry) => entry.apiPath === apiPath && (normalizedModuleId ? entry.moduleID === normalizedModuleId : true));
+		
+
+		
+		
+		if (historyEntry) {
+			await this.addApiComponent({
+				apiPath: historyEntry.apiPath,
+				folderPath: historyEntry.folderPath,
+				options: {
+					...historyEntry.options,
+					metadata: historyEntry.metadata,
+					mutateExisting: true,
+					forceOverwrite: true,
+					collisionMode: "replace", 
+					recordHistory: false
+				}
+			});
+			return;
+		}
+		
+
+		
+		
+		if (normalizedModuleId === "base" || normalizedModuleId === "core") {
+			const baseApi = await this.slothlet.builders.builder.buildAPI({
+				dir: this.____config.dir,
+				mode: this.____config.mode,
+				moduleID: "base" 
+			});
+
+			const { parts } = this.normalizeApiPath(apiPath);
+			let baseValue = this.getValueAtPath(baseApi, parts);
+			if (baseValue === undefined) {
+				await this.deletePath(this.slothlet.api, parts);
+				await this.deletePath(this.slothlet.boundApi, parts);
+				return;
+			}
+
+			
+			
+			
+			
+			const baseValueRaw = resolveWrapper(baseValue);
+			
+			
+			if (baseValue && baseValueRaw !== null) {
+				baseValue = baseValueRaw.__impl;
+			}
+
+			await this.setValueAtPath(this.slothlet.api, parts, baseValue, {
+				mutateExisting: true,
+				allowOverwrite: true,
+				collisionMode: "replace", 
+				moduleID: normalizedModuleId
+			});
+			await this.setValueAtPath(this.slothlet.boundApi, parts, baseValue, {
+				mutateExisting: true,
+				allowOverwrite: true,
+				collisionMode: "replace", 
+				moduleID: normalizedModuleId
+			});
+		}
+	}
+
+	
+	async addApiComponent(params) {
+		
+		
+		const { apiPath, folderPath, options = {} } = params || {};
+
+		
+		if (Array.isArray(folderPath)) {
+			const moduleIDs = [];
+			for (const singlePath of folderPath) {
+				const moduleID = await this.addApiComponent({
+					apiPath,
+					folderPath: singlePath,
+					options
+				});
+				moduleIDs.push(moduleID);
+			}
+			return moduleIDs;
+		}
+
+		const { metadata = {}, ...restOptions } = options;
+		if (!this.slothlet || !this.slothlet.isLoaded) {
+			throw new this.SlothletError("INVALID_CONFIG_NOT_LOADED", {
+				operation: "addApi",
+				validationError: true
+			});
+		}
+
+		const { apiPath: normalizedPath, parts } = this.normalizeApiPath(apiPath);
+
+		
+		const { resolvedPath, isDirectory, isFile } = await this.resolvePath(folderPath);
+
+		
+		if (!isDirectory && !isFile) {
+			throw new this.SlothletError("INVALID_CONFIG_PATH_TYPE", {
+				path: resolvedPath,
+				validationError: true
+			});
+		}
+
+		if (isFile) {
+			
+			const ext = path.extname(resolvedPath);
+			if (![".mjs", ".cjs", ".js"].includes(ext)) {
+				throw new this.SlothletError("INVALID_CONFIG_FILE_TYPE", {
+					path: resolvedPath,
+					extension: ext,
+					validationError: true
+				});
+			}
+		}
+
+		
+		const resolvedFolderPath = resolvedPath;
+
+		
+		
+		
+		let collisionMode;
+		if (restOptions.forceOverwrite) {
+			collisionMode = "replace";
+		} else {
+			
+			
+			collisionMode = restOptions.collisionMode || this.____config.api?.collision?.api || "error";
+		}
+
+		const mutateExisting = !!(restOptions.mutateExisting || collisionMode === "merge");
+
+		const moduleID = restOptions.moduleID ? String(restOptions.moduleID) : this.buildDefaultModuleId(normalizedPath, resolvedFolderPath);
+		
+		
+		
+		
+		if (restOptions.forceOverwrite && !moduleID) {
+			throw new this.SlothletError("INVALID_CONFIG_FORCE_OVERWRITE_REQUIRES_MODULE_ID", {
+				apiPath: normalizedPath,
+				validationError: true
+			});
+		}
+		
+
+		
+		
+		let dirForBuild = resolvedFolderPath;
+		let fileFilter = null;
+
+		if (isFile) {
+			dirForBuild = path.dirname(resolvedFolderPath);
+			const fileName = path.basename(resolvedFolderPath);
+			fileFilter = (file) => file === fileName;
+		}
+
+		const newApi = await this.slothlet.builders.builder.buildAPI({
+			dir: dirForBuild,
+			mode: this.____config.mode,
+			
+			
+			
+			apiPathPrefix: normalizedPath,
+			collisionContext: "addApi",
+			moduleID: moduleID,
+			
+			collisionMode: collisionMode,
+			
+			fileFilter: fileFilter
+		});
+
+		
+		
+		
+		if (this.slothlet.handlers.apiCacheManager) {
+			this.slothlet.handlers.apiCacheManager.set(moduleID, {
+				endpoint: normalizedPath,
+				moduleID: moduleID,
+				api: newApi,
+				folderPath: resolvedFolderPath,
+				mode: this.____config.mode,
+				sanitizeOptions: this.____config.sanitize || {},
+				collisionMode: collisionMode,
+				config: { ...this.____config },
+				timestamp: Date.now()
+			});
+		}
+
+		this.slothlet.debug("api", {
+			key: "DEBUG_MODE_ADD_API_COMPONENT_BUILD_RETURN",
+			topLevelKeys: Object.keys(newApi),
+			dottedKeys: Object.keys(newApi).filter((k) => k.includes(".")),
+			wrappers: Object.keys(newApi)
+				.filter((k) => resolveWrapper(newApi[k]) !== null)
+				.map((k) => {
+					const _w = resolveWrapper(newApi[k]);
+					return {
+						key: k,
+						apiPath: _w.apiPath,
+						implKeys: Object.keys(_w.____slothletInternal.impl || {}),
+						childCacheSize: Object.keys(_w).filter((k) => !k.startsWith("_") && !k.startsWith("__")).length,
+						childCacheKeys: Object.keys(_w).filter((k) => !k.startsWith("_") && !k.startsWith("__"))
+					};
+				}),
+			nonWrappers: Object.keys(newApi)
+				.filter((k) => resolveWrapper(newApi[k]) === null)
+				.map((k) => ({ key: k, type: typeof newApi[k] }))
+		});
+
+		
+		
+		
+		
+		let apiToMerge = newApi;
+
+		
+		
+		
+		if (isFile && Object.keys(newApi).length === 1) {
+			const fileName = Object.keys(newApi)[0];
+			apiToMerge = newApi[fileName];
+		}
+
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		if (!isFile && normalizedPath) {
+			const lastPart = normalizedPath.includes(".") ? normalizedPath.split(".").pop() : normalizedPath;
+			if (lastPart && Object.prototype.hasOwnProperty.call(apiToMerge, lastPart)) {
+				const dupValue = apiToMerge[lastPart];
+				const dupType = typeof dupValue;
+				
+				
+				if (dupValue !== null && (dupType === "object" || dupType === "function")) {
+					
+					
+					
+					
+					const dupWrapper = resolveWrapper(dupValue);
+					const dupFilePath = dupWrapper?.____slothletInternal?.filePath;
+					
+					
+					const dupFileDir = dupFilePath ? dupFilePath.replace(/\\/g, "/").split("/").slice(0, -1).join("/") : null;
+					const normalizedFolderPath = resolvedFolderPath.replace(/\\/g, "/").replace(/\/$/, "");
+					const expectedDir = normalizedFolderPath + "/" + lastPart;
+					
+					
+					
+					
+					
+					
+					
+					const isDirectChild = dupFileDir === expectedDir || dupFileDir === normalizedFolderPath;
+
+					if (isDirectChild) {
+						
+						const hoisted = {};
+						for (const k of Object.keys(apiToMerge)) {
+							if (k !== lastPart) hoisted[k] = apiToMerge[k];
+						}
+						
+						
+						
+						if (dupWrapper) {
+							
+							for (const k of Object.keys(dupWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"))) {
+								hoisted[k] = dupWrapper[k];
+							}
+						} else {
+							
+							
+							
+							
+							for (const k of Object.keys(dupValue)) {
+								hoisted[k] = dupValue[k];
+							}
+							
+						}
+						apiToMerge = hoisted;
+						this.slothlet.debug("api", {
+							key: "DEBUG_MODE_RULE_13_DEDUP_HOISTED_KEY",
+							lastPart,
+							newKeys: Object.keys(apiToMerge)
+						});
+					}
+				}
+			}
+		}
+
+		if (this.____config.debug?.api) {
+			this.slothlet.debug("api", {
+				key: "DEBUG_MODE_ADD_API_COMPONENT_MERGE_KEYS",
+				keys: Object.keys(apiToMerge),
+				isRootLevel: parts.length === 0
+			});
+		}
+
+		
+		
+		
+		let anyAssignmentSucceeded = false;
+
+		if (parts.length === 0) {
+			
+			for (const key of Object.keys(newApi)) {
+				const result1 = await this.setValueAtPath(this.slothlet.api, [key], newApi[key], {
+					mutateExisting,
+					collisionMode,
+					moduleID,
+					sourceFolder: resolvedFolderPath
+				});
+
+				const result2 = await this.setValueAtPath(this.slothlet.boundApi, [key], newApi[key], {
+					mutateExisting,
+					collisionMode,
+					moduleID,
+					sourceFolder: resolvedFolderPath
+				});
+
+				
+				if (result1 || result2) {
+					anyAssignmentSucceeded = true;
+				}
+			}
+		} else {
+			
+			
+			
+			if (resolveWrapper(apiToMerge) === null) {
+				
+				
+				
+				const isCallableNamespace = typeof apiToMerge === "function";
+
+				const containerWrapper = new UnifiedWrapper(this.slothlet, {
+					apiPath: normalizedPath,
+					mode: this.____config.mode,
+					isCallable: isCallableNamespace, 
+					moduleID: moduleID,
+					filePath: resolvedFolderPath,
+					sourceFolder: resolvedFolderPath
+				});
+				
+				containerWrapper.___setImpl(apiToMerge, moduleID);
+				
+				apiToMerge = containerWrapper.createProxy();
+			}
+
+			const result1 = await this.setValueAtPath(this.slothlet.api, parts, apiToMerge, {
+				mutateExisting,
+				collisionMode,
+				moduleID, 
+				sourceFolder: resolvedFolderPath 
+			});
+
+			const result2 = await this.setValueAtPath(this.slothlet.boundApi, parts, apiToMerge, {
+				mutateExisting,
+				collisionMode,
+				moduleID, 
+				sourceFolder: resolvedFolderPath 
+			});
+
+			
+			if (result1 || result2) {
+				anyAssignmentSucceeded = true;
+			}
+		}
+
+		
+		
+		
+		
+		
+		
+		if (anyAssignmentSucceeded) {
+			const pendingMaterializations = [];
+			const seenWrappers = new Set();
+
+			
+			const collectPendingMaterializations = (obj, depth = 0) => {
+				if (!obj || typeof obj !== "object" || depth > 10) return;
+
+				const wrapper = resolveWrapper(obj);
+				if (wrapper) {
+					
+					if (seenWrappers.has(wrapper)) return;
+					seenWrappers.add(wrapper);
+
+					
+					
+					
+					if (wrapper.____slothletInternal.materializationPromise) {
+						pendingMaterializations.push(wrapper.____slothletInternal.materializationPromise);
+					}
+
+					
+					const childKeys = Object.keys(wrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+					for (const key of childKeys) {
+						collectPendingMaterializations(wrapper[key], depth + 1);
+					}
+				}
+
+				
+				for (const key of Object.keys(obj)) {
+					
+					
+					if (key !== "____slothletInternal") {
+						collectPendingMaterializations(obj[key], depth + 1);
+					}
+				}
+			};
+
+			
+			
+			if (parts.length === 0) {
+				
+				for (const key of Object.keys(newApi)) {
+					
+					
+					if (this.slothlet.api[key]) {
+						collectPendingMaterializations(this.slothlet.api[key]);
+					}
+				}
+			} else {
+				
+				let current = this.slothlet.api;
+				for (const part of parts) {
+					
+					
+					if (current && current[part]) {
+						current = current[part];
+					} else {
+						break;
+					}
+					
+				}
+				
+				
+				if (current) {
+					collectPendingMaterializations(current);
+				}
+			}
+
+			
+			
+			
+			if (pendingMaterializations.length > 0) {
+				if (this.____config.debug?.api) {
+					this.slothlet.debug("api", {
+						key: "DEBUG_MODE_AWAITING_PENDING_MATERIALIZATIONS",
+						count: pendingMaterializations.length,
+						apiPath: normalizedPath
+					});
+				}
+				await Promise.all(pendingMaterializations);
+			}
+			
+		}
+
+		
+		
+		
+		
+		
+		if (anyAssignmentSucceeded && metadata && Object.keys(metadata).length > 0 && this.slothlet.handlers.metadata) {
+			if (parts.length === 0) {
+				
+				for (const key of Object.keys(newApi)) {
+					this.slothlet.handlers.metadata.registerUserMetadata(key, metadata);
+				}
+			} else {
+				const rootSegment = normalizedPath.split(".")[0];
+				this.slothlet.handlers.metadata.registerUserMetadata(rootSegment, metadata);
+			}
+		}
+
+		
+		
+		
+		if (this.slothlet.handlers.ownership && moduleID) {
+			this.slothlet.handlers.ownership.registerSubtree(apiToMerge, moduleID, normalizedPath);
+		}
+
+		
+		
+		if (this.slothlet.handlers.ownership) {
+			if (restOptions.recordHistory !== false) {
+				this.state.addHistory.push({
+					apiPath: normalizedPath,
+					folderPath: resolvedFolderPath,
+					options: { ...restOptions, metadata, moduleID },
+					moduleID
+				});
+
+				
+				this.state.operationHistory.push({
+					type: "add",
+					apiPath: normalizedPath,
+					folderPath: resolvedFolderPath,
+					options: { ...restOptions, metadata, moduleID },
+					moduleID
+				});
+			}
+		}
+
+		return moduleID;
+	}
+
+	
+	async removeApiComponent(pathOrModuleId, options = {}) {
+		const recordHistory = options.recordHistory !== false;
+		if (typeof pathOrModuleId !== "string" || !pathOrModuleId) {
+			throw new this.SlothletError("INVALID_ARGUMENT", {
+				argument: "pathOrModuleId",
+				expected: "non-empty string",
+				received: typeof pathOrModuleId,
+				validationError: true
+			});
+		}
+
+		
+		
+		let apiPath = null;
+		let moduleID = null;
+
+		if (this.slothlet.handlers.ownership) {
+			
+			const candidateModuleID = pathOrModuleId.split(":")[0];
+
+			
+			
+			
+			
+			const registeredModules = Array.from(this.slothlet.handlers.ownership.moduleToPath.keys());
+			const matchingModule = registeredModules.findLast((m) => m === candidateModuleID || m.startsWith(`${candidateModuleID}_`));
+
+			if (matchingModule) {
+				
+				moduleID = matchingModule;
+			} else {
+				
+				const owner = this.slothlet.handlers.ownership.getCurrentOwner(pathOrModuleId);
+				if (owner) {
+					
+					apiPath = pathOrModuleId;
+					moduleID = owner.moduleID;
+				} else {
+					
+					return false;
+				}
+			}
+		} else {
+			
+			const isModuleId = !pathOrModuleId.includes(".");
+			apiPath = isModuleId ? null : pathOrModuleId;
+			moduleID = isModuleId ? pathOrModuleId.split(":")[0] : null;
+		}
+		if (!this.slothlet || !this.slothlet.isLoaded) {
+			throw new this.SlothletError("INVALID_CONFIG_NOT_LOADED", {
+				operation: "removeApi",
+				validationError: true
+			});
+		}
+
+		if (apiPath && moduleID) {
+			const normalizedPath = this.normalizeApiPath(apiPath).apiPath;
+			const moduleIDKey = String(moduleID);
+			
+			
+			const history = this.slothlet.handlers.ownership?.getPathHistory?.(normalizedPath) || [];
+			
+			
+			const ownershipResult = this.slothlet.handlers.ownership?.removePath?.(normalizedPath, moduleIDKey) || {
+				action: "none",
+				removedModuleId: null,
+				restoreModuleId: null
+			};
+			const pathParts = this.normalizeApiPath(apiPath).parts;
+			if (ownershipResult.action === "delete") {
+				await this.deletePath(this.slothlet.api, pathParts);
+				await this.deletePath(this.slothlet.boundApi, pathParts);
+				
+				
+				
+				if (this.slothlet.handlers.metadata) {
+					const rootSegment = normalizedPath.split(".")[0];
+					this.slothlet.handlers.metadata.removeUserMetadataByApiPath(rootSegment);
+				}
+				
+				this.state.operationHistory.push({
+					type: "remove",
+					apiPath: normalizedPath
+				});
+				return true;
+			}
+			
+			
+			
+			if (ownershipResult.action === "restore") {
+				const restoredValue = this.slothlet.handlers.ownership?.getCurrentValue?.(normalizedPath);
+				const restoredModuleId = this.slothlet.handlers.ownership?.getCurrentOwner?.(normalizedPath)?.moduleID;
+				if (restoredValue !== undefined && restoredModuleId) {
+					await this.setValueAtPath(this.slothlet.api, pathParts, restoredValue, {
+						mutateExisting: true,
+						allowOverwrite: true,
+						collisionMode: "replace", 
+						moduleID: restoredModuleId 
+					});
+					await this.setValueAtPath(this.slothlet.boundApi, pathParts, restoredValue, {
+						mutateExisting: true,
+						allowOverwrite: true,
+						collisionMode: "replace", 
+						moduleID: restoredModuleId 
+					});
+					
+					this.state.operationHistory.push({
+						type: "remove",
+						apiPath: normalizedPath
+					});
+					return true;
+				}
+				await this.restoreApiPath(normalizedPath, ownershipResult.restoreModuleId);
+				
+				this.state.operationHistory.push({
+					type: "remove",
+					apiPath: normalizedPath
+				});
+				return true;
+			}
+			if (ownershipResult.action === "none" && history.length === 0) {
+				await this.deletePath(this.slothlet.api, pathParts);
+				await this.deletePath(this.slothlet.boundApi, pathParts);
+				return true;
+			}
+			return false;
+			
+		}
+
+		if (moduleID) {
+			const moduleIDKey = String(moduleID);
+			
+			
+			const result = this.slothlet.handlers.ownership?.unregister?.(moduleIDKey) || { removed: [], rolledBack: [] };
+
+			
+			const allPaths = [...result.removed, ...result.rolledBack.map((r) => r.apiPath)];
+
+			
+			const uniquePaths = [...new Set(allPaths)];
+
+			
+			const pathsToDelete = [];
+			const pathsToRollback = [];
+
+			for (const path of uniquePaths) {
+				const currentOwner = this.slothlet.handlers.ownership?.getCurrentOwner?.(path);
+
+				
+				
+				const hasChildrenWithOtherOwners = uniquePaths.some((p) => {
+					if (p === path || !p.startsWith(path + ".")) return false;
+					const childOwner = this.slothlet.handlers.ownership?.getCurrentOwner?.(p);
+					return childOwner && childOwner.moduleID !== moduleIDKey;
+				});
+
+				
+				if (currentOwner && currentOwner.moduleID !== moduleIDKey) {
+					
+					pathsToRollback.push({ apiPath: path, restoredTo: currentOwner.moduleID });
+				} else if (!hasChildrenWithOtherOwners) {
+					
+					pathsToDelete.push(path);
+				}
+				
+			}
+
+			
+			
+			pathsToDelete.sort((a, b) => {
+				const depthA = (a.match(/\./g) || []).length;
+				const depthB = (b.match(/\./g) || []).length;
+				return depthB - depthA; 
+			});
+
+			
+			for (const removedPath of pathsToDelete) {
+				const { parts } = this.normalizeApiPath(removedPath);
+				await this.deletePath(this.slothlet.api, parts);
+				await this.deletePath(this.slothlet.boundApi, parts);
+				
+				
+				
+				if (this.slothlet.handlers.metadata) {
+					const rootSegment = removedPath.split(".")[0];
+					this.slothlet.handlers.metadata.removeUserMetadataByApiPath(rootSegment);
+				}
+			}
+
+			
+			
+			
+			
+			if (pathsToDelete.length > 0) {
+				const rootSegment = pathsToDelete[0].split(".")[0];
+
+				
+				
+				
+				if (rootSegment in this.slothlet.api) {
+					delete this.slothlet.api[rootSegment];
+				}
+				
+				
+				
+				if (rootSegment in this.slothlet.boundApi) {
+					delete this.slothlet.boundApi[rootSegment];
+				}
+			}
+
+			
+			for (const rollback of pathsToRollback) {
+				
+				const { parts } = this.normalizeApiPath(rollback.apiPath);
+				const previousImpl = this.slothlet.handlers.ownership?.getCurrentValue?.(rollback.apiPath);
+
+				if (previousImpl !== undefined) {
+					
+					const existingWrapper = this.getValueAtPath(this.slothlet.api, parts);
+					const existingWrapperRaw = resolveWrapper(existingWrapper);
+					if (existingWrapperRaw) {
+						
+						existingWrapperRaw.___setImpl(previousImpl, rollback.restoredTo);
+					}
+					
+					const existingBoundWrapper = this.getValueAtPath(this.slothlet.boundApi, parts);
+					const existingBoundWrapperRaw = resolveWrapper(existingBoundWrapper);
+					if (existingBoundWrapperRaw) {
+						existingBoundWrapperRaw.___setImpl(previousImpl, rollback.restoredTo);
+					}
+				}
+			}
+
+			this.state.addHistory = this.state.addHistory.filter((entry) => String(entry.moduleID) !== moduleIDKey);
+
+			
+			
+			
+			if (this.slothlet.handlers.apiCacheManager) {
+				const deleted = this.slothlet.handlers.apiCacheManager.delete(moduleIDKey);
+				
+				
+				if (deleted) {
+					this.slothlet.debug("cache", {
+						key: "DEBUG_MODE_CACHE_DELETED_MODULE_REMOVED",
+						moduleID: moduleIDKey
+					});
+				}
+			}
+
+			
+			
+			
+			if (recordHistory && pathsToDelete.length > 0) {
+				const rootSegment = pathsToDelete[0].split(".")[0];
+				this.state.operationHistory.push({
+					type: "remove",
+					apiPath: rootSegment
+				});
+			}
+			
+			return pathsToDelete.length > 0 || pathsToRollback.length > 0;
+		}
+
+		
+		
+		if (!apiPath) {
+			throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+				apiPath,
+				reason: translate("API_PATH_REASON_REQUIRED"),
+				index: undefined,
+				segment: undefined,
+				validationError: true
+			});
+		}
+
+		const { apiPath: normalizedPath, parts } = this.normalizeApiPath(apiPath);
+		const ownershipResult = this.slothlet.handlers.ownership?.removePath?.(normalizedPath, null) || {
+			action: "none",
+			removedModuleId: null,
+			restoreModuleId: null
+		};
+
+		
+		const pathExists = this.getValueAtPath(this.slothlet.api, parts) !== undefined;
+
+		if (ownershipResult.action === "none") {
+			if (pathExists) {
+				await this.deletePath(this.slothlet.api, parts);
+				await this.deletePath(this.slothlet.boundApi, parts);
+				
+				
+				
+				if (this.slothlet.handlers.metadata) {
+					this.slothlet.handlers.metadata.removeUserMetadataByApiPath(normalizedPath);
+				}
+				
+				
+				
+				if (recordHistory) {
+					this.state.operationHistory.push({
+						type: "remove",
+						apiPath: normalizedPath
+					});
+				}
+				return true;
+			}
+			
+			return false;
+		}
+		
+		
+		if (ownershipResult.action === "delete") {
+			await this.deletePath(this.slothlet.api, parts);
+			await this.deletePath(this.slothlet.boundApi, parts);
+			
+			if (this.slothlet.handlers.metadata) {
+				this.slothlet.handlers.metadata.removeUserMetadataByApiPath(normalizedPath);
+			}
+			
+			if (recordHistory) {
+				this.state.operationHistory.push({
+					type: "remove",
+					apiPath: normalizedPath
+				});
+			}
+			return true;
+		}
+		if (ownershipResult.action === "restore") {
+			const restoredValue = this.slothlet.handlers.ownership?.getCurrentValue?.(normalizedPath);
+			const restoredModuleId = this.slothlet.handlers.ownership?.getCurrentOwner?.(normalizedPath)?.moduleID;
+			if (restoredValue !== undefined && restoredModuleId) {
+				await this.setValueAtPath(this.slothlet.api, parts, restoredValue, {
+					mutateExisting: true,
+					allowOverwrite: true,
+					collisionMode: "replace", 
+					moduleID: restoredModuleId 
+				});
+				await this.setValueAtPath(this.slothlet.boundApi, parts, restoredValue, {
+					mutateExisting: true,
+					allowOverwrite: true,
+					collisionMode: "replace", 
+					moduleID: restoredModuleId 
+				});
+				
+				if (recordHistory) {
+					this.state.operationHistory.push({
+						type: "remove",
+						apiPath: normalizedPath
+					});
+				}
+				return true;
+			}
+			await this.restoreApiPath(normalizedPath, ownershipResult.restoreModuleId);
+			
+			if (recordHistory) {
+				this.state.operationHistory.push({
+					type: "remove",
+					apiPath: normalizedPath
+				});
+			}
+			return true;
+		}
+		
+		
+		
+		return false;
+	}
+
+	
+	async reloadApiComponent(params) {
+		const { apiPath, moduleID, options } = params || {};
+		if (!this.slothlet || !this.slothlet.isLoaded) {
+			throw new this.SlothletError("INVALID_CONFIG_NOT_LOADED", {
+				operation: "reloadApi",
+				validationError: true
+			});
+		}
+
+		
+		if (moduleID) {
+			await this._reloadByModuleID(moduleID);
+			return;
+		}
+
+		
+		if (apiPath) {
+			await this._reloadByApiPath(apiPath, options);
+			return;
+		}
+
+		throw new this.SlothletError("INVALID_ARGUMENT", {
+			argument: "params",
+			expected: "{ moduleID } or { apiPath }",
+			received: params,
+			validationError: true
+		});
+	}
+
+	
+	async _reloadByModuleID(moduleID, { forceReplace = true } = {}) {
+		const cacheManager = this.slothlet.handlers.apiCacheManager;
+		if (!cacheManager) {
+			throw new this.SlothletError("CACHE_MANAGER_NOT_AVAILABLE", {
+				operation: "reload",
+				validationError: true
+			});
+		}
+
+		
+		if (!cacheManager.has(moduleID)) {
+			throw new this.SlothletError("CACHE_NOT_FOUND", {
+				moduleID,
+				operation: "reload",
+				validationError: true
+			});
+		}
+
+		
+		const oldEntry = cacheManager.get(moduleID);
+
+		this.slothlet.debug("reload", {
+			key: "DEBUG_MODE_RELOADING_MODULE_BY_ID",
+			moduleID,
+			endpoint: oldEntry.endpoint,
+			folderPath: oldEntry.folderPath
+		});
+
+		
+		const freshApi = await cacheManager.rebuildCache(moduleID);
+
+		
+		cacheManager.set(moduleID, {
+			...oldEntry,
+			api: freshApi,
+			timestamp: Date.now()
+		});
+
+		
+		this.slothlet.debug("reload", {
+			key: "DEBUG_MODE_FRESH_API_KEYS_BEFORE_RESTORE",
+			moduleID,
+			endpoint: oldEntry.endpoint,
+			
+			
+			freshApiKeys: Object.keys(freshApi || {})
+		});
+
+		
+		await this._restoreApiTree(freshApi, oldEntry.endpoint, moduleID, oldEntry.collisionMode, forceReplace);
+
+		
+		this.slothlet.debug("reload", {
+			key: "DEBUG_MODE_FRESH_API_KEYS_AFTER_RESTORE",
+			moduleID,
+			endpoint: oldEntry.endpoint,
+			
+			
+			freshApiKeys: Object.keys(freshApi || {})
+		});
+
+		this.slothlet.debug("reload", {
+			key: "DEBUG_MODE_MODULE_RELOAD_COMPLETE",
+			moduleID
+		});
+	}
+
+	
+	async _reloadByApiPath(apiPath, options = {}) {
+		this.slothlet.debug("reload", {
+			key: "DEBUG_MODE_RELOADING_BY_API_PATH",
+			apiPath
+		});
+
+		
+		const moduleIDsToReload = this._findAffectedCaches(apiPath);
+
+		
+		
+		
+		if (moduleIDsToReload.length === 0) {
+			this.slothlet.debug("reload", {
+				key: "DEBUG_MODE_NO_CACHES_ATTEMPTING_RESTORE",
+				apiPath
+			});
+			
+			if (apiPath !== "." && apiPath !== "") {
+				await this.restoreApiPath(apiPath, "base");
+			}
+			return;
+		}
+		
+
+		
+		
+		
+		const cacheManager = this.slothlet.handlers.apiCacheManager;
+		moduleIDsToReload.sort((a, b) => {
+			const entryA = cacheManager.get(a);
+			const entryB = cacheManager.get(b);
+
+			
+			
+			
+			if (entryA?.endpoint === "." && entryB?.endpoint !== ".") return -1;
+			if (entryB?.endpoint === "." && entryA?.endpoint !== ".") return 1;
+			
+			
+			const indexA = this.state.addHistory.findIndex((h) => h.moduleID === a);
+			const indexB = this.state.addHistory.findIndex((h) => h.moduleID === b);
+			return indexA - indexB;
+		});
+
+		
+		
+		
+		
+		const endpointOrder = new Map();
+		for (const moduleID of moduleIDsToReload) {
+			const entry = cacheManager.get(moduleID);
+			
+			
+			const ep = entry?.endpoint ?? ".";
+			if (!endpointOrder.has(ep)) endpointOrder.set(ep, []);
+			endpointOrder.get(ep).push(moduleID);
+		}
+
+		for (const [, moduleIDs] of endpointOrder) {
+			for (let i = 0; i < moduleIDs.length; i++) {
+				await this._reloadByModuleID(moduleIDs[i], { forceReplace: i === 0 });
+			}
+		}
+
+		
+		
+		
+		const reloadMetadata = options?.metadata;
+		if (reloadMetadata && typeof reloadMetadata === "object" && Object.keys(reloadMetadata).length > 0) {
+			
+			
+			if (this.slothlet.handlers.metadata) {
+				const targetPath = apiPath === "." ? null : apiPath.split(".")[0];
+				if (targetPath) {
+					this.slothlet.handlers.metadata.registerUserMetadata(targetPath, reloadMetadata);
+				}
+			}
+		}
+
+		this.slothlet.debug("reload", {
+			key: "DEBUG_MODE_API_PATH_RELOAD_COMPLETE",
+			apiPath,
+			reloadedModules: moduleIDsToReload.length,
+			loadOrder: moduleIDsToReload
+		});
+	}
+
+	
+	_findAffectedCaches(apiPath) {
+		const cacheManager = this.slothlet.handlers.apiCacheManager;
+		
+		
+		if (!cacheManager) return [];
+
+		const allModuleIDs = cacheManager.getAllModuleIDs();
+
+		
+		if (apiPath === "." || apiPath === "" || apiPath == null) {
+			const baseModules = [];
+			for (const moduleID of allModuleIDs) {
+				const entry = cacheManager.get(moduleID);
+				if (entry && entry.endpoint === ".") {
+					baseModules.push(moduleID);
+				}
+			}
+			return baseModules;
+		}
+
+		
+		const exactMatches = [];
+		for (const moduleID of allModuleIDs) {
+			const entry = cacheManager.get(moduleID);
+			if (entry && entry.endpoint === apiPath) {
+				exactMatches.push(moduleID);
+			}
+		}
+		if (exactMatches.length > 0) return exactMatches;
+
+		
+		const children = [];
+		const pathPrefix = apiPath + ".";
+		for (const moduleID of allModuleIDs) {
+			const entry = cacheManager.get(moduleID);
+			if (entry?.endpoint?.startsWith(pathPrefix)) {
+				children.push(moduleID);
+			}
+		}
+		if (children.length > 0) return children;
+
+		
+		const ownership = this.slothlet.handlers.ownership;
+		const history = ownership?.getPathHistory?.(apiPath);
+		if (history && history.length > 0) {
+			const owned = [];
+			for (const { moduleID } of history) {
+				
+				
+				if (cacheManager.has(moduleID)) {
+					owned.push(moduleID);
+				}
+			}
+			
+			
+			if (owned.length > 0) return owned;
+		}
+
+		
+		
+		
+		let bestMatch = null;
+		let bestLength = -1;
+		for (const moduleID of allModuleIDs) {
+			const entry = cacheManager.get(moduleID);
+			
+			
+			if (!entry?.endpoint) continue;
+
+			const ep = entry.endpoint;
+			
+			
+			
+			
+			if (ep === "." || apiPath.startsWith(ep + ".")) {
+				
+				
+				if (ep.length > bestLength) {
+					bestLength = ep.length;
+					bestMatch = moduleID;
+				}
+			}
+		}
+		
+		
+		if (bestMatch) return [bestMatch];
+
+		
+		
+		return [];
+	}
+
+	
+	_collectCustomProperties(existingProxy, freshApi) {
+		const customProps = {};
+		
+		
+		
+		if (!existingProxy || (typeof existingProxy !== "object" && typeof existingProxy !== "function")) {
+			return customProps;
+		}
+		
+
+		const wrapper = resolveWrapper(existingProxy);
+		
+		
+		if (!wrapper) {
+			return customProps;
+		}
+		
+
+		
+		
+		
+		const freshKeys = new Set(freshApi ? Object.keys(freshApi) : []);
+
+		
+		
+		
+		const ownKeys = Object.keys(wrapper).filter((k) => !ComponentBase.INTERNAL_KEYS.has(k));
+
+		for (const key of ownKeys) {
+			try {
+				
+				const val = wrapper[key];
+
+				
+				
+				if (val && (typeof val === "object" || typeof val === "function") && resolveWrapper(val)) {
+					continue;
+				}
+
+				
+				
+				if (!freshKeys.has(key)) {
+					
+					customProps[key] = val;
+				} else {
+					
+					
+					customProps[key] = val;
+				}
+			} catch {
+				
+			}
+		}
+
+		return customProps;
+	}
+
+	
+	_restoreCustomProperties(proxy, customProps) {
+		
+		
+		
+		if (!proxy || !customProps || typeof customProps !== "object") {
+			return;
+		}
+
+		for (const [key, value] of Object.entries(customProps)) {
+			try {
+				proxy[key] = value;
+			} catch {
+				
+			}
+		}
+	}
+
+	
+	async _restoreApiTree(freshApi, endpoint, moduleID, collisionMode, forceReplace = true) {
+		
+		
+		
+		if (!freshApi || (typeof freshApi !== "object" && typeof freshApi !== "function")) {
+			return;
+		}
+
+		
+		const parts = endpoint === "." ? [] : endpoint.split(".");
+
+		if (parts.length === 0) {
+			
+			
+			
+			for (const key of Object.keys(freshApi)) {
+				
+				
+				
+				if (typeof key === "string" && (key.startsWith("_") || key.startsWith("__"))) continue;
+				
+				
+				
+				if (key === "slothlet" || key === "shutdown" || key === "destroy") continue;
+
+				const existingAtKey = this.slothlet.api[key];
+				const freshValue = freshApi[key];
+
+				if (existingAtKey && resolveWrapper(existingAtKey) !== null) {
+					
+					const customProps = this._collectCustomProperties(existingAtKey, freshValue);
+
+					
+					
+					const freshWrapper = resolveWrapper(freshValue);
+					const isLazyFresh =
+						freshWrapper &&
+						freshWrapper.____slothletInternal.mode === "lazy" &&
+						!freshWrapper.____slothletInternal.state.materialized &&
+						typeof freshWrapper.____slothletInternal.materializeFunc === "function";
+
+					
+					this.slothlet.debug("reload", {
+						key: "DEBUG_MODE_RESTORE_ROOT_KEY_INSPECT",
+						rootKey: key,
+						hasFreshWrapper: !!freshWrapper,
+						freshMode: freshWrapper?.____slothletInternal.mode,
+						freshMaterialized: freshWrapper?.____slothletInternal.state?.materialized,
+						hasMaterializeFunc: typeof freshWrapper?.____slothletInternal.materializeFunc === "function",
+						isLazyFresh,
+						existingMaterialized: resolveWrapper(existingAtKey)?.____slothletInternal?.state?.materialized
+					});
+
+					if (isLazyFresh) {
+						
+						
+						
+						
+						resolveWrapper(existingAtKey).___resetLazy(freshWrapper.____slothletInternal.materializeFunc);
+
+						
+						this._restoreCustomProperties(existingAtKey, customProps);
+
+						this.slothlet.debug("reload", {
+							key: "DEBUG_MODE_ROOT_KEY_RESET_LAZY",
+							rootKey: key,
+							restoredCustomProps: Object.keys(customProps)
+						});
+					} else {
+						
+						
+
+						
+						
+						
+						
+						
+						let implForReload;
+						
+						
+						
+						if (freshValue && resolveWrapper(freshValue) !== null) {
+							implForReload = freshWrapper ? UnifiedWrapper._extractFullImpl(freshWrapper) : freshValue;
+						} else {
+							
+							
+							
+							
+							implForReload = freshValue;
+						}
+
+						
+						if (typeof implForReload === "function") {
+							const extracted = {};
+							for (const k of Object.keys(implForReload)) {
+								extracted[k] = implForReload[k];
+							}
+							implForReload = extracted;
+						}
+
+						
+						
+						
+						const wrapper = resolveWrapper(existingAtKey);
+						
+						
+						const originalCollisionMode = wrapper ? wrapper.____slothletInternal.state.collisionMode : null;
+						if (forceReplace && wrapper) {
+							wrapper.____slothletInternal.state.collisionMode = "replace";
+						}
+						
+						
+						
+						
+						if (wrapper && originalCollisionMode !== null) {
+							wrapper.____slothletInternal.state.collisionMode = originalCollisionMode;
+						}
+
+						
+						this._restoreCustomProperties(existingAtKey, customProps);
+
+						this.slothlet.debug("reload", {
+							key: "DEBUG_MODE_ROOT_KEY_UPDATED_SETIMPL",
+							rootKey: key,
+							restoredCustomProps: Object.keys(customProps)
+						});
+					}
+				} else if (existingAtKey === undefined) {
+					
+					const cacheManager = this.slothlet.handlers.apiCacheManager;
+					const cacheEntry = cacheManager.get(moduleID);
+					
+					
+					const resolvedFolderPath = cacheEntry?.folderPath || "";
+
+					await this.setValueAtPath(this.slothlet.api, [key], freshValue, {
+						mutateExisting: true,
+						collisionMode,
+						moduleID,
+						sourceFolder: resolvedFolderPath
+					});
+
+					
+					
+					if (this.slothlet.boundApi) {
+						await this.setValueAtPath(this.slothlet.boundApi, [key], freshValue, {
+							mutateExisting: true,
+							collisionMode,
+							moduleID,
+							sourceFolder: resolvedFolderPath
+						});
+					}
+				}
+				
+			}
+		} else {
+			
+			
+			const existing = this.getValueAtPath(this.slothlet.api, parts);
+
+			this.slothlet.debug("reload", {
+				key: "DEBUG_MODE_RESTORE_NESTED_PATH",
+				endpoint,
+				moduleID,
+				partsPath: parts.join("."),
+				existingFound: !!existing,
+				
+				
+				
+				hasSetImpl: existing ? resolveWrapper(existing) !== null : false,
+				freshApiKeys: Object.keys(freshApi || {})
+				
+			});
+
+			if (existing && resolveWrapper(existing) !== null) {
+				
+				const customProps = this._collectCustomProperties(existing, freshApi);
+
+				
+				
+				
+				const wrapper = resolveWrapper(existing);
+				
+				
+				const originalCollisionMode = wrapper ? wrapper.____slothletInternal.state.collisionMode : null;
+
+				if (forceReplace && wrapper) {
+					wrapper.____slothletInternal.state.collisionMode = "replace";
+					this.slothlet.debug("reload", {
+						key: "DEBUG_MODE_RESTORE_FORCING_REPLACE",
+						endpoint,
+						originalCollisionMode,
+						wrapperApiPath: wrapper.____slothletInternal.apiPath
+					});
+				}
+
+				
+				
+				
+				
+				
+				let implForReload;
+				
+				
+				
+				
+				
+				
+				if (resolveWrapper(freshApi) !== null) {
+					const freshWrapper = resolveWrapper(freshApi);
+					implForReload = freshWrapper ? UnifiedWrapper._extractFullImpl(freshWrapper) : freshApi;
+				} else if (typeof freshApi === "function") {
+					implForReload = {};
+					for (const key of Object.keys(freshApi)) {
+						implForReload[key] = freshApi[key];
+					}
+				} else {
+					implForReload = freshApi;
+				}
+
+				
+				
+				
+				
+				
+				
+				
+				
+				if (implForReload && typeof implForReload === "object") {
+					for (const key of Object.keys(implForReload)) {
+						const val = implForReload[key];
+						if (resolveWrapper(val) !== null) {
+							const childWrapper = resolveWrapper(val);
+							if (childWrapper.____slothletInternal.state.materialized) {
+								implForReload[key] = UnifiedWrapper._extractFullImpl(childWrapper);
+							}
+						}
+					}
+				}
+
+				resolveWrapper(existing).___setImpl(implForReload, moduleID);
+
+				
+				
+				
+				
+				if (wrapper && originalCollisionMode !== null) {
+					wrapper.____slothletInternal.state.collisionMode = originalCollisionMode;
+				}
+
+				
+				this._restoreCustomProperties(existing, customProps);
+
+				this.slothlet.debug("reload", {
+					key: "DEBUG_MODE_UPDATED_WRAPPER_IMPL",
+					endpoint,
+					moduleID,
+					forcedReplaceMode: true,
+					restoredCustomProps: Object.keys(customProps)
+				});
+			} else {
+				
+				
+				const cacheManager = this.slothlet.handlers.apiCacheManager;
+				const cacheEntry = cacheManager.get(moduleID);
+				
+				
+				const resolvedFolderPath = cacheEntry?.folderPath || "";
+
+				
+				let implForContainer = freshApi;
+				
+				
+				
+				
+				
+				
+				if (typeof freshApi === "function") {
+					implForContainer = {};
+					for (const key of Object.keys(freshApi)) {
+						implForContainer[key] = freshApi[key];
+					}
+				}
+				const containerWrapper = new UnifiedWrapper(this.slothlet, {
+					apiPath: endpoint,
+					mode: this.____config.mode,
+					moduleID: moduleID,
+					filePath: resolvedFolderPath,
+					sourceFolder: resolvedFolderPath
+				});
+				containerWrapper.___setImpl(implForContainer, moduleID);
+				const apiToSet = containerWrapper.createProxy();
+
+				
+				await this.setValueAtPath(this.slothlet.api, parts, apiToSet, {
+					mutateExisting: true,
+					collisionMode,
+					moduleID,
+					sourceFolder: resolvedFolderPath
+				});
+
+				
+				
+				if (this.slothlet.boundApi) {
+					await this.setValueAtPath(this.slothlet.boundApi, parts, apiToSet, {
+						mutateExisting: true,
+						collisionMode,
+						moduleID,
+						sourceFolder: resolvedFolderPath
+					});
+				}
+
+				this.slothlet.debug("reload", {
+					key: "DEBUG_MODE_CREATED_NEW_WRAPPER_UNEXPECTED",
+					endpoint,
+					moduleID
+				});
+			}
+		}
+	}
+}