@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/lib/builders/modes-processor.mjs

@@ -0,0 +1,1816 @@
+/*
+	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 { t } from "@cldmv/slothlet/i18n";
+import { UnifiedWrapper, resolveWrapper } from "@cldmv/slothlet/handlers/unified-wrapper";
+import { getInstanceToken } from "@cldmv/slothlet/handlers/lifecycle-token";
+
+export class ModesProcessor extends ComponentBase {
+	static slothletProperty = "modesProcessor";
+	
+	constructor(slothlet) {
+		super(slothlet);
+	}
+	async processFiles(
+		api,
+		files,
+		directory,
+		currentDepth,
+		mode,
+		isRoot,
+		recursive,
+		populateDirectly = false,
+		apiPathPrefix = "",
+		collisionContext = "initial",
+		moduleID = null,
+		sourceFolder = null,
+		cacheBust = null,
+		collisionModeOverride = null
+	) {
+		
+		const buildApiPath = (path) => {
+			if (!apiPathPrefix) return path;
+			
+			
+			
+			if (path.startsWith(`${apiPathPrefix}.`)) {
+				return path; 
+			}
+			
+			return `${apiPathPrefix}.${path}`;
+		};
+		let rootDefaultFunction = null;
+		const rootContributors = []; 
+		const categoryName = isRoot && !populateDirectly ? null : this.slothlet.helpers.sanitize.sanitizePropertyName(directory.name);
+		let targetApi = isRoot && !populateDirectly ? api : populateDirectly ? api : (api[categoryName] = api[categoryName] || {});
+
+		
+		
+		const isRootFile = currentDepth === 0 && !populateDirectly;
+		const effectiveMode = mode === "lazy" && isRootFile ? "eager" : mode;
+		const shouldWrap = !(effectiveMode === "lazy" && populateDirectly);
+
+		if (!isRoot && shouldWrap && !populateDirectly) {
+			const existingTarget = api[categoryName];
+			
+			
+			if (existingTarget && resolveWrapper(existingTarget)) {
+				if (this.slothlet.config.debug?.modes) {
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_CATEGORY_REUSE_EXISTING_WRAPPER",
+						categoryName,
+						apiPath: resolveWrapper(existingTarget)?.apiPath
+					});
+				}
+				targetApi = existingTarget;
+			} else if (existingTarget === undefined || (typeof existingTarget === "object" && existingTarget !== null)) {
+				
+				
+				
+				
+				const initialImpl = resolveWrapper(existingTarget)
+					? {}
+					: 
+						
+						this.slothlet.helpers.modesUtils.cloneWrapperImpl(existingTarget || {}, mode);
+				if (this.slothlet.config.debug?.modes) {
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_CATEGORY_WRAPPER_CREATED",
+						categoryName,
+						apiPath: buildApiPath(categoryName)
+					});
+				}
+				const wrapper = new UnifiedWrapper(this.slothlet, {
+					mode: effectiveMode,
+					apiPath: buildApiPath(categoryName),
+					initialImpl,
+					filePath: directory.path,
+					
+					
+					moduleID: moduleID || categoryName,
+					sourceFolder
+				});
+				api[categoryName] = wrapper.createProxy();
+
+				
+				
+				
+				if (this.slothlet.handlers?.metadata) {
+					this.slothlet.handlers.metadata.tagSystemMetadata(
+						wrapper,
+						{
+							filePath: directory.path,
+							apiPath: buildApiPath(categoryName),
+							
+							
+							moduleID: moduleID || "base",
+							
+							
+							sourceFolder: sourceFolder || directory.path
+						},
+						getInstanceToken(this.slothlet)
+					);
+				}
+
+				if (this.slothlet.config.debug?.modes) {
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_CATEGORY_WRAPPER_ASSIGNED",
+						categoryName
+					});
+				}
+				targetApi = api[categoryName];
+				if (this.slothlet.config.debug?.modes) {
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_CATEGORY_CREATED",
+						categoryName,
+						apiPath: wrapper.apiPath
+					});
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_CATEGORY_TARGET_API_STATUS",
+						isWrapper: !!resolveWrapper(targetApi),
+						targetApiKeys: Object.keys(targetApi)
+					});
+				}
+			}
+		}
+		
+		if (!isRoot && this.slothlet.config.debug?.modes) {
+			this.slothlet.debug("modes", {
+				message: await t("DEBUG_MODE_PROCESSING_DIRECTORY", { mode, categoryName, currentDepth })
+			});
+		}
+		
+		const loadedModules = [];
+		for (const file of files) {
+			if (this.slothlet.config.debug?.modes && categoryName === "string") {
+				this.slothlet.debug("modes", {
+					key: "DEBUG_MODE_PROCESSING_FILE",
+					categoryName,
+					file: file.name,
+					isRoot,
+					populateDirectly,
+					mode
+				});
+			}
+			try {
+				const mod = await this.slothlet.processors.loader.loadModule(file.path, this.slothlet.instanceID, moduleID, cacheBust);
+				const exports = this.slothlet.processors.loader.extractExports(mod);
+				const moduleName = this.slothlet.helpers.sanitize.sanitizePropertyName(file.name);
+				const moduleKeys = Object.keys(exports).filter((k) => k !== "default");
+				const analysis = {
+					hasDefault: exports.default !== undefined,
+					hasNamed: moduleKeys.length > 0,
+					defaultExportType: exports.default ? typeof exports.default : null
+				};
+				loadedModules.push({ file, mod: exports, moduleName, moduleKeys, analysis });
+			} catch (error) {
+				
+				
+				if (error.name === "SlothletError") throw error;
+				
+				
+				
+				
+				throw new this.SlothletError("MODULE_LOAD_FAILED", { modulePath: file.path, moduleID: moduleID || file.moduleID }, error);
+			}
+		}
+		
+		const hasMultipleDefaults = loadedModules.filter((m) => m.analysis.hasDefault).length > 1;
+		
+		for (const { file, mod, moduleName, moduleKeys, analysis } of loadedModules) {
+			if (this.slothlet.config.debug?.modes && categoryName === "logger") {
+				this.slothlet.debug("modes", {
+					key: "DEBUG_MODE_PROCESSING_MODULE",
+					categoryName,
+					moduleName,
+					hasDefault: analysis.hasDefault,
+					moduleKeys,
+					targetApiType: typeof targetApi,
+					targetApiCallable: typeof targetApi === "function"
+				});
+			}
+			
+			
+			
+			
+			const isAddapiFile =
+				moduleName === "addapi" ||
+				file.name === "addapi" ||
+				(file.fullName && ["addapi.mjs", "addapi.cjs", "addapi.js", "addapi.ts"].includes(file.fullName.toLowerCase()));
+			const isAddapiObjectDefault = isAddapiFile && analysis.hasDefault && typeof mod.default !== "function";
+			const isRootContributor = isRoot && analysis.hasDefault && typeof mod.default === "function" && !isAddapiObjectDefault;
+			if (moduleName === "config" || moduleKeys.some((k) => k.includes("Config") || k.includes("config"))) {
+				if (this.slothlet.config.debug?.modes) {
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_FILE_PROCESSING",
+						module: moduleName,
+						category: categoryName || "(none)",
+						isRoot,
+						hasDefault: analysis.hasDefault,
+						moduleKeys
+					});
+				}
+			}
+			if (isRootContributor) {
+				
+				const defaultFunc = this.slothlet.helpers.modesUtils.ensureNamedExportFunction(mod.default, moduleName);
+				for (const key of moduleKeys) {
+					if (!this.slothlet.processors.flatten.shouldAttachNamedExport(key, mod[key], defaultFunc, mod.default)) {
+						continue;
+					}
+					defaultFunc[key] = mod[key];
+				}
+				
+				rootContributors.push({ moduleName, file, defaultFunc });
+				continue; 
+			} else {
+				
+				const decision = await this.slothlet.processors.flatten.getFlatteningDecision({
+					mod,
+					moduleName,
+					categoryName: categoryName || moduleName,
+					analysis,
+					hasMultipleDefaults,
+					moduleKeys,
+					t
+				});
+				if (this.slothlet.config.debug?.modes) {
+					this.slothlet.debug("modes", {
+						message: await t("DEBUG_MODE_MODULE_DECISION", { mode, moduleName, reason: decision.reason })
+					});
+				}
+				
+				const propertyName = decision.preferredName || moduleName;
+
+				
+				
+				const effectiveCategoryName = categoryName || moduleName;
+
+				
+				let { moduleContent } = this.slothlet.processors.flatten.processModuleForAPI({
+					mod,
+					decision,
+					moduleName,
+					propertyName,
+					moduleKeys,
+					analysis,
+					file,
+					collisionContext,
+					apiPathPrefix: apiPathPrefix || ""
+				});
+				
+				
+				if (!isRoot && !apiPathPrefix && moduleName === categoryName) {
+					
+					
+					if (moduleKeys.length === 1 && moduleKeys[0] === moduleName && !analysis.hasDefault) {
+						
+						
+						const exportedValue = mod[moduleName];
+						
+						
+						if (typeof exportedValue === "object" && exportedValue !== null) {
+							if (this.slothlet.config.debug?.modes && categoryName === "string") {
+								this.slothlet.debug("modes", {
+									key: "DEBUG_MODE_SINGLE_FILE_FOLDER_DETECTED",
+									categoryName,
+									populateDirectly,
+									isRoot,
+									mode,
+									exportKeys: Object.keys(exportedValue)
+								});
+							}
+							
+							
+							
+							if (shouldWrap) {
+								const wrapper = new UnifiedWrapper(this.slothlet, {
+									mode: effectiveMode,
+									apiPath: buildApiPath(categoryName),
+									initialImpl: exportedValue,
+									materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+									filePath: file.path,
+									
+									
+									moduleID: moduleID || file.moduleID,
+									sourceFolder
+								});
+								
+								api[categoryName] = wrapper.createProxy();
+								targetApi = api[categoryName];
+							} else {
+								this.slothlet.debug("modes", {
+									key: "DEBUG_MODE_SINGLE_FILE_FOLDER_WRAPPED",
+									categoryName,
+									implKeys: Object.keys(exportedValue)
+								});
+							}
+							
+							for (const key of Object.keys(exportedValue)) {
+								
+								
+								if (this.slothlet.handlers.ownership) {
+									this.slothlet.handlers.ownership.register({
+										
+										
+										moduleID: moduleID || file.moduleID,
+										apiPath: `${categoryName}.${key}`,
+										source: "core",
+										collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+										filePath: file.path
+									});
+								}
+							}
+							continue;
+						}
+						
+						
+					} else if (analysis.hasDefault) {
+						
+						
+						
+						
+						
+						
+						
+						
+						const namedKeys = moduleKeys.length > 0 ? moduleKeys : Object.keys(mod).filter((key) => key !== "default");
+						
+						
+						const callableModule =
+							typeof mod.default === "function"
+								? this.slothlet.helpers.modesUtils.ensureNamedExportFunction(mod.default, categoryName)
+								: moduleContent;
+						
+						
+						if (namedKeys.length > 0) {
+							for (const key of namedKeys) {
+								
+								
+								
+								if (key in callableModule) {
+									continue;
+								}
+								
+								
+								if (!this.slothlet.processors.flatten.shouldAttachNamedExport(key, mod[key], callableModule, mod.default)) {
+									continue;
+								}
+								
+								
+								
+								
+								
+								
+								callableModule[key] = mod[key];
+							}
+						}
+						moduleContent = callableModule;
+						
+						
+						if (shouldWrap) {
+							const wrapper = new UnifiedWrapper(this.slothlet, {
+								mode: effectiveMode,
+								apiPath: buildApiPath(categoryName),
+								initialImpl: this.slothlet.helpers.modesUtils.cloneWrapperImpl(callableModule, mode),
+								materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+								filePath: file.path,
+								
+								
+								moduleID: moduleID || file.moduleID,
+								sourceFolder
+							});
+							
+							api[categoryName] = wrapper.createProxy();
+							
+							targetApi = api[categoryName];
+						} else {
+							
+							
+							
+							
+							
+							
+							
+							api[categoryName] = moduleContent;
+							targetApi = api[categoryName];
+							
+						}
+						
+						
+						const needsSeparateNamedExports = typeof mod.default === "function";
+						if (needsSeparateNamedExports && namedKeys.length > 0) {
+							for (const key of namedKeys) {
+								
+								
+								if (shouldWrap) {
+									const namedWrapper = new UnifiedWrapper(this.slothlet, {
+										mode: effectiveMode,
+										apiPath: buildApiPath(`${categoryName}.${key}`),
+										initialImpl: mod[key],
+										materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+										filePath: file.path,
+										
+										
+										moduleID: moduleID || file.moduleID,
+										sourceFolder
+									});
+									this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, key, namedWrapper.createProxy(), {
+										useCollisionDetection: true,
+										config: this.slothlet.config,
+										collisionContext
+									});
+								} else {
+									
+									
+									
+									
+									this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, key, mod[key], {
+										useCollisionDetection: true,
+										config: this.slothlet.config,
+										collisionContext
+									});
+									
+								}
+								
+								
+								if (this.slothlet.handlers.ownership) {
+									this.slothlet.handlers.ownership.register({
+										
+										
+										moduleID: moduleID || file.moduleID,
+										apiPath: `${categoryName}.${key}`,
+										source: "core",
+										collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+										filePath: file.path
+									});
+								}
+							}
+						}
+						
+						
+						if (this.slothlet.handlers.ownership) {
+							this.slothlet.handlers.ownership.register({
+								
+								
+								moduleID: moduleID || file.moduleID,
+								apiPath: categoryName,
+								source: "core",
+								collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+								filePath: file.path
+							});
+						}
+						
+						continue;
+						
+						
+					} else if (moduleKeys.length > 0) {
+						
+						
+						
+						
+						const hasMatchingObject = moduleKeys.some(
+							(key) => key === moduleName && typeof mod[key] === "object" && mod[key] !== null && !Array.isArray(mod[key])
+						);
+						if (hasMatchingObject) {
+							
+							
+							const matchingObj = mod[moduleName];
+							
+							for (const [propKey, propValue] of Object.entries(matchingObj)) {
+								
+								
+								if (shouldWrap) {
+									const wrapper = new UnifiedWrapper(this.slothlet, {
+										mode: effectiveMode,
+										apiPath: buildApiPath(`${categoryName}.${propKey}`),
+										initialImpl: this.slothlet.helpers.modesUtils.cloneWrapperImpl(propValue, mode),
+										materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+										filePath: file.path,
+										
+										
+										moduleID: moduleID || file.moduleID,
+										sourceFolder
+									});
+									this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, propKey, wrapper.createProxy(), {
+										useCollisionDetection: true,
+										config: this.slothlet.config,
+										collisionContext
+									});
+								} else {
+									this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, propKey, propValue, {
+										useCollisionDetection: true,
+										config: this.slothlet.config,
+										collisionContext
+									});
+								}
+								
+								
+								if (this.slothlet.handlers.ownership) {
+									this.slothlet.handlers.ownership.register({
+										
+										
+										moduleID: moduleID || file.moduleID,
+										apiPath: `${categoryName}.${propKey}`,
+										source: "core",
+										collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+										filePath: file.path
+									});
+								}
+							}
+							
+							for (const key of moduleKeys) {
+								if (key !== moduleName) {
+									
+									
+									if (shouldWrap) {
+										const wrapper = new UnifiedWrapper(this.slothlet, {
+											mode: effectiveMode,
+											apiPath: buildApiPath(`${categoryName}.${key}`),
+											initialImpl: this.slothlet.helpers.modesUtils.cloneWrapperImpl(mod[key], mode),
+											materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+											filePath: file.path,
+											
+											
+											moduleID: moduleID || file.moduleID,
+											sourceFolder
+										});
+										this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, key, wrapper.createProxy(), {
+											useCollisionDetection: true,
+											config: this.slothlet.config,
+											collisionContext
+										});
+									} else {
+										this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, key, mod[key], {
+											useCollisionDetection: true,
+											config: this.slothlet.config,
+											collisionContext
+										});
+									}
+									
+									
+									if (this.slothlet.handlers.ownership) {
+										this.slothlet.handlers.ownership.register({
+											
+											
+											moduleID: moduleID || file.moduleID,
+											apiPath: `${categoryName}.${key}`,
+											source: "core",
+											collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+											filePath: file.path
+										});
+									}
+								}
+							}
+						} else {
+							
+							if (this.slothlet.config.debug?.modes) {
+								this.slothlet.debug("modes", {
+									key: "DEBUG_MODE_FLATTEN_MULTI_EXPORT_FILE",
+									moduleName,
+									categoryName,
+									exportCount: moduleKeys.length
+								});
+								this.slothlet.debug("modes", {
+									key: "DEBUG_MODE_FLATTEN_MULTI_EXPORT_TARGET_STATUS",
+									isWrapper: !!resolveWrapper(targetApi),
+									keysBefore: Object.keys(targetApi)
+								});
+							}
+							for (const key of moduleKeys) {
+								if (this.slothlet.config.debug?.modes) {
+									this.slothlet.debug("modes", {
+										key: "DEBUG_MODE_FLATTEN_MULTI_EXPORT_ASSIGNING",
+										propKey: key
+									});
+								}
+								
+								
+								if (shouldWrap) {
+									const wrapper = new UnifiedWrapper(this.slothlet, {
+										mode: effectiveMode,
+										apiPath: buildApiPath(`${categoryName}.${key}`),
+										initialImpl: this.slothlet.helpers.modesUtils.cloneWrapperImpl(mod[key], mode),
+										materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+										filePath: file.path,
+										
+										
+										moduleID: moduleID || file.moduleID,
+										sourceFolder
+									});
+									const assigned = this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, key, wrapper.createProxy(), {
+										useCollisionDetection: true,
+										config: this.slothlet.config,
+										collisionContext
+									});
+									if (assigned) {
+										this.slothlet.debug("modes", {
+											key: "DEBUG_MODE_FLATTEN_MULTI_EXPORT_ASSIGNED",
+											propKey: key,
+											keysAfter: Object.keys(targetApi)
+										});
+									} else {
+										this.slothlet.debug("modes", {
+											key: "DEBUG_MODE_FLATTEN_MULTI_EXPORT_BLOCKED",
+											propKey: key
+										});
+									}
+								} else {
+									this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, key, mod[key], {
+										useCollisionDetection: true,
+										config: this.slothlet.config,
+										collisionContext
+									});
+								}
+								
+								
+								if (this.slothlet.handlers.ownership) {
+									this.slothlet.handlers.ownership.register({
+										
+										
+										moduleID: moduleID || file.moduleID,
+										apiPath: `${categoryName}.${key}`,
+										source: "core",
+										collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+										filePath: file.path
+									});
+								}
+							}
+						}
+						continue;
+					}
+					
+				}
+				
+				
+				
+				
+				
+				if (!analysis.hasDefault && moduleKeys.length === 1 && !isRoot) {
+					const key = moduleKeys[0];
+					const keyValue = mod[key];
+					const isMatchingObject = key === moduleName && typeof keyValue === "object" && keyValue !== null && !Array.isArray(keyValue);
+					
+					if (!isMatchingObject) {
+						
+						const normalizedKey = key.toLowerCase().replace(/[-_]/g, "");
+						const normalizedModuleName = moduleName.toLowerCase().replace(/[-_]/g, "");
+						if (normalizedKey === normalizedModuleName) {
+							
+							const preferredName = key;
+							
+							
+							if (shouldWrap) {
+								const wrapper = new UnifiedWrapper(this.slothlet, {
+									mode: effectiveMode,
+									apiPath: buildApiPath(`${categoryName}.${preferredName}`),
+									initialImpl: this.slothlet.helpers.modesUtils.cloneWrapperImpl(mod[key], mode),
+									materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+									filePath: file.path,
+									
+									
+									moduleID: moduleID || file.moduleID,
+									sourceFolder
+								});
+								this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, preferredName, wrapper.createProxy(), {
+									useCollisionDetection: true,
+									config: this.slothlet.config,
+									collisionContext
+								});
+							} else {
+								this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, preferredName, mod[key], {
+									useCollisionDetection: true,
+									config: this.slothlet.config,
+									collisionContext
+								});
+							}
+							
+							
+							if (this.slothlet.handlers.ownership) {
+								this.slothlet.handlers.ownership.register({
+									
+									
+									moduleID: moduleID || file.moduleID,
+									apiPath: `${categoryName}.${preferredName}`,
+									source: "core",
+									collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+									filePath: file.path
+								});
+							}
+							continue;
+						}
+					}
+				}
+
+				
+				
+				if (decision.flattenToCategory && moduleContent && effectiveCategoryName) {
+					
+					const isAddapiFile = decision.flattenType === "addapi-metadata-default" || decision.flattenType === "addapi-special-file";
+
+					if (isAddapiFile && typeof moduleContent === "object" && !Array.isArray(moduleContent) && typeof moduleContent !== "function") {
+						
+						
+						for (const key of Object.keys(moduleContent)) {
+							const value = moduleContent[key];
+							
+							
+							const keyPath = isRoot ? key : `${apiPathPrefix ? apiPathPrefix + "." : ""}${key}`;
+
+							if (shouldWrap && typeof value === "function") {
+								const wrapper = new UnifiedWrapper(this.slothlet, {
+									mode: effectiveMode,
+									apiPath: buildApiPath(keyPath),
+									initialImpl: value,
+									materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+									filePath: file.path,
+									
+									
+									moduleID: moduleID || file.moduleID,
+									sourceFolder
+								});
+								this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, key, wrapper.createProxy(), {
+									useCollisionDetection: true,
+									config: this.slothlet.config,
+									collisionContext
+								});
+							} else {
+								this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, key, value, {
+									useCollisionDetection: true,
+									config: this.slothlet.config,
+									collisionContext
+								});
+							}
+						}
+
+						
+						
+						
+						if (this.slothlet.handlers.ownership) {
+							for (const key of Object.keys(moduleContent)) {
+								
+								
+								const apiPath = isRoot ? key : apiPathPrefix ? `${apiPathPrefix}.${key}` : key;
+								this.slothlet.handlers.ownership.register({
+									
+									
+									moduleID: moduleID || file.moduleID,
+									apiPath,
+									source: "core",
+									collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+									config: this.slothlet.config
+								});
+							}
+						}
+					} else {
+						
+						
+						
+						const localPath = isRoot ? effectiveCategoryName : `${apiPathPrefix ? apiPathPrefix + "." : ""}${effectiveCategoryName}`;
+
+						
+						
+						if (shouldWrap) {
+							const wrapper = new UnifiedWrapper(this.slothlet, {
+								mode: effectiveMode,
+								apiPath: buildApiPath(localPath),
+								initialImpl: moduleContent,
+								materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+								filePath: file.path,
+								
+								
+								moduleID: moduleID || file.moduleID,
+								sourceFolder,
+								isCallable: typeof moduleContent === "function"
+							});
+							this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, effectiveCategoryName, wrapper.createProxy(), {
+								useCollisionDetection: true,
+								config: this.slothlet.config,
+								collisionContext
+							});
+						} else {
+							this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, effectiveCategoryName, moduleContent, {
+								useCollisionDetection: true,
+								config: this.slothlet.config,
+								collisionContext
+							});
+						}
+
+						
+						
+						
+						if (this.slothlet.handlers.ownership) {
+							const apiPath = isRoot
+								? effectiveCategoryName
+								: apiPathPrefix
+									? `${apiPathPrefix}.${effectiveCategoryName}`
+									: effectiveCategoryName;
+							this.slothlet.handlers.ownership.register({
+								
+								
+								moduleID: moduleID || file.moduleID,
+								apiPath,
+								source: "core",
+								collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+								config: this.slothlet.config
+							});
+						}
+					}
+					
+					continue;
+				}
+
+				
+				
+				
+				if (shouldWrap) {
+					const localPath = isRoot ? propertyName : `${categoryName}.${propertyName}`;
+					const wrapper = new UnifiedWrapper(this.slothlet, {
+						mode: effectiveMode,
+						apiPath: buildApiPath(localPath),
+						initialImpl: moduleContent, 
+						materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+						filePath: file.path,
+						
+						
+						moduleID: moduleID || file.moduleID,
+						sourceFolder
+					});
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_FILE_WRAPPER_ASSIGNMENT",
+						propertyName,
+						apiPath: buildApiPath(localPath),
+						
+						
+						overwriting: propertyName in targetApi ? (resolveWrapper(targetApi[propertyName]) ? "wrapper" : "value") : "nothing"
+					});
+					this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, propertyName, wrapper.createProxy(), {
+						useCollisionDetection: true,
+						config: this.slothlet.config,
+						collisionContext
+					});
+				} else {
+					this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, propertyName, moduleContent, {
+						useCollisionDetection: true,
+						config: this.slothlet.config,
+						collisionContext
+					});
+				}
+				if (this.slothlet.config.debug?.modes && categoryName === "logger") {
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_AFTER_ASSIGNMENT_STATUS",
+						targetApiType: typeof targetApi,
+						propertyName,
+						hasProperty: propertyName in targetApi,
+						implType: typeof resolveWrapper(targetApi)?.____slothletInternal.impl,
+						implHasProperty: !!resolveWrapper(targetApi)?.____slothletInternal.impl?.utils
+					});
+				}
+				
+				
+				if (this.slothlet.handlers.ownership) {
+					const apiPath = isRoot ? propertyName : `${categoryName}.${propertyName}`;
+					this.slothlet.handlers.ownership.register({
+						
+						
+						moduleID: moduleID || file.moduleID,
+						apiPath,
+						source: "core",
+						collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+						config: this.slothlet.config
+					});
+				}
+			}
+		}
+		
+		if (this.slothlet.config.debug?.modes) {
+			this.slothlet.debug("modes", {
+				key: "DEBUG_MODE_SUBDIRECTORY_CHECK",
+				isRoot,
+				categoryName,
+				hasDirectory: !!directory,
+				hasChildren: !!directory?.children,
+				directoryCount: directory?.children?.directories?.length || 0
+			});
+		}
+		this.slothlet.debug("modes", {
+			key: "DEBUG_MODE_DIRECTORY_CHECK",
+			hasChildren: !!directory?.children,
+			hasDirectories: !!directory?.children?.directories,
+			length: directory?.children?.directories?.length || 0
+		});
+		if (directory?.children?.directories) {
+			this.slothlet.debug("modes", {
+				key: "DEBUG_MODE_DIRECTORY_CHECK_PASSED",
+				recursive
+			});
+			if (this.slothlet.config.debug?.modes) {
+				this.slothlet.debug("modes", {
+					key: "DEBUG_MODE_SUBDIRECTORIES_FOUND",
+					subdirectoryCount: directory.children.directories.length,
+					recursive
+				});
+			}
+			if (recursive) {
+				
+				this.slothlet.debug("modes", {
+					key: "DEBUG_MODE_SUBDIRECTORY_LOOP_START",
+					count: directory.children.directories.length
+				});
+				for (const subDir of directory.children.directories) {
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_PROCESSING_SUBDIRECTORY",
+						name: subDir.name,
+						fileCount: subDir.children.files.length,
+						subdirCount: subDir.children.directories.length
+					});
+					const subDirName = this.slothlet.helpers.sanitize.sanitizePropertyName(subDir.name);
+					
+					if (subDir.children.files.length === 1 && subDir.children.directories.length === 0) {
+						const file = subDir.children.files[0];
+						const moduleName = this.slothlet.helpers.sanitize.sanitizePropertyName(file.name);
+						const genericFilenames = ["singlefile", "index", "main", "default"];
+						const isGeneric = genericFilenames.includes(moduleName.toLowerCase());
+						const filenameMatchesFolder = moduleName === subDirName;
+						
+						
+						
+						
+						if (isGeneric || filenameMatchesFolder) {
+							this.slothlet.debug("modes", {
+								key: "DEBUG_MODE_FOLDER_LEVEL_FLATTEN_CHECK",
+								subDir: subDirName,
+								file: moduleName,
+								isGeneric,
+								filenameMatches: filenameMatchesFolder
+							});
+							const mod = await this.slothlet.processors.loader.loadModule(file.path, this.slothlet.instanceID, moduleID, cacheBust);
+							const exports = this.slothlet.processors.loader.extractExports(mod);
+							const moduleKeys = Object.keys(exports).filter((k) => k !== "default");
+							const analysis = {
+								hasDefault: exports.default !== undefined,
+								hasNamed: moduleKeys.length > 0,
+								defaultExportType: exports.default ? typeof exports.default : null
+							};
+							const modContent = exports.default !== undefined ? exports.default : exports;
+							const categoryDecision = await this.slothlet.processors.flatten.buildCategoryDecisions({
+								categoryName: subDirName,
+								mod: modContent,
+								moduleName,
+								fileBaseName: file.name,
+								analysis,
+								moduleKeys,
+								currentDepth: currentDepth + 1,
+								moduleFiles: subDir.children.files,
+								t
+							});
+							
+							
+							
+							if (categoryDecision.shouldFlatten) {
+								this.slothlet.debug("modes", {
+									key: "DEBUG_MODE_FOLDER_LEVEL_FLATTEN_SKIP_RECURSION",
+									subDir: subDirName
+								});
+								
+								
+								let implToWrap;
+
+								
+								
+								
+								if (categoryDecision.flattenType === "addapi-metadata-default") {
+									
+									implToWrap = {};
+									for (const key of moduleKeys) {
+										
+										
+										if (key !== "default") {
+											implToWrap[key] = exports[key];
+										}
+									}
+								} else if (moduleName === subDirName && moduleKeys.includes(subDirName)) {
+									
+									implToWrap = exports[subDirName];
+								} else if (exports.default !== undefined) {
+									
+									implToWrap = exports.default;
+									if (moduleKeys.length > 0) {
+										
+										
+										
+										if (typeof implToWrap === "function") {
+											
+											
+											
+											const collisionConfig = this.slothlet.config.api?.collision || this.slothlet.config.collision;
+											
+											
+											const collisionMode = (collisionContext === "initial" ? collisionConfig?.initial : collisionConfig?.api) || "merge";
+											for (const key of moduleKeys) {
+												
+												
+												if (key !== "default") {
+													const hasExisting = implToWrap[key] !== undefined;
+													if (hasExisting) {
+														if (collisionMode === "merge" || collisionMode === "skip") {
+															
+															continue;
+														} else if (collisionMode === "error") {
+															throw new this.slothlet.SlothletError(
+																"COLLISION_DEFAULT_EXPORT_ERROR",
+																{
+																	key,
+																	apiPath: `${apiPathPrefix}.${subDirName}`
+																},
+																null,
+																{ validationError: true }
+															);
+														} else if (collisionMode === "warn") {
+															new this.slothlet.SlothletWarning("WARNING_COLLISION_DEFAULT_EXPORT_OVERWRITE", {
+																key,
+																apiPath: `${apiPathPrefix}.${subDirName}`
+															});
+														}
+														
+													}
+													implToWrap[key] = exports[key];
+												}
+											}
+										} else if (typeof implToWrap === "object" && implToWrap !== null) {
+											
+											for (const key of moduleKeys) {
+												if (key !== "default" && !(key in implToWrap)) {
+													implToWrap[key] = exports[key];
+												}
+											}
+										}
+										
+									}
+								} else {
+									
+									implToWrap = modContent;
+								}
+
+								
+								
+								
+								
+								
+								
+								
+								
+								
+								
+								
+								
+								
+								const modes_eagerCollisionConfig = this.slothlet.config.api?.collision || this.slothlet.config.collision;
+								
+								
+								const modes_eagerCollisionMode =
+									(collisionContext === "initial" ? modes_eagerCollisionConfig?.initial : modes_eagerCollisionConfig?.api) || "merge";
+								const modes_existingAtKey = targetApi[subDirName];
+								if (modes_existingAtKey !== undefined && modes_eagerCollisionMode !== "replace" && modes_eagerCollisionMode !== "skip") {
+									const modes_existingWrapper = resolveWrapper(modes_existingAtKey);
+									
+									
+									if (modes_existingWrapper) {
+										
+										
+										
+										
+										
+										if (
+											modes_existingWrapper.____slothletInternal?.materializeFunc &&
+											!modes_existingWrapper.____slothletInternal?.state?.materialized
+										) {
+											await modes_existingWrapper._materialize();
+										}
+										
+										
+										
+										
+										if (
+											modes_existingWrapper.____slothletInternal?.impl &&
+											!modes_existingWrapper.____slothletInternal?.state?.childrenAdopted
+										) {
+											modes_existingWrapper.___adoptImplChildren();
+										}
+										const modes_existingImpl = modes_existingWrapper.__impl;
+										
+										
+										if (modes_existingImpl && typeof modes_existingImpl === "object" && !Array.isArray(modes_existingImpl)) {
+											if (typeof implToWrap === "object" && implToWrap !== null) {
+												for (const [k, v] of Object.entries(modes_existingImpl)) {
+													
+													
+													
+													
+													if (!(k in implToWrap)) {
+														implToWrap[k] = v;
+													}
+												}
+												
+												
+												
+												
+											} else if (typeof implToWrap === "function") {
+												for (const [k, v] of Object.entries(modes_existingImpl)) {
+													if (implToWrap[k] === undefined) {
+														implToWrap[k] = v;
+													}
+												}
+											}
+											
+										}
+										
+										const modes_existingChildKeys = Object.keys(modes_existingWrapper).filter(
+											(k) => !k.startsWith("_") && !k.startsWith("__")
+										);
+										for (const ck of modes_existingChildKeys) {
+											if (typeof implToWrap === "object" && implToWrap !== null && !(ck in implToWrap)) {
+												implToWrap[ck] = modes_existingWrapper[ck];
+											} else if (typeof implToWrap === "function" && implToWrap[ck] === undefined) {
+												implToWrap[ck] = modes_existingWrapper[ck];
+											}
+										}
+										this.slothlet.debug("modes", {
+											key: "DEBUG_MODE_FILE_FOLDER_COLLISION_MERGED",
+											subDir: subDirName,
+											mergedKeys: Object.keys(implToWrap)
+										});
+									}
+								}
+
+								
+								const wrapper = new UnifiedWrapper(this.slothlet, {
+									mode: effectiveMode,
+									
+									
+									apiPath: buildApiPath(categoryName ? `${categoryName}.${subDirName}` : subDirName),
+									initialImpl: implToWrap, 
+									materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+									filePath: file.path,
+									
+									
+									moduleID: moduleID || file.moduleID,
+									sourceFolder
+								});
+								this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, subDirName, wrapper.createProxy(), {
+									useCollisionDetection: true,
+									config: this.slothlet.config,
+									collisionContext
+								});
+								
+								
+								if (this.slothlet.handlers.ownership) {
+									
+									
+									const apiPath = buildApiPath(categoryName ? `${categoryName}.${subDirName}` : subDirName);
+									this.slothlet.handlers.ownership.register({
+										
+										
+										moduleID: moduleID || file.moduleID,
+										apiPath,
+										source: "core",
+										collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+										config: this.slothlet.config
+									});
+								}
+								continue;
+							}
+						}
+					}
+
+					
+					
+					
+					
+					
+					
+					
+					const currentCategoryName = apiPathPrefix ? apiPathPrefix.split(".").pop() : categoryName;
+					if (subDirName === currentCategoryName && currentCategoryName !== null) {
+						
+						await this.processFiles(
+							targetApi, 
+							subDir.children.files,
+							subDir, 
+							currentDepth + 1,
+							mode,
+							false, 
+							recursive,
+							true, 
+							apiPathPrefix,
+							collisionContext,
+							moduleID,
+							sourceFolder,
+							cacheBust
+						);
+						continue;
+					}
+
+					
+					await this.processFiles(
+						targetApi,
+						subDir.children.files,
+						{ name: subDirName, path: subDir.path, children: subDir.children }, 
+						currentDepth + 1,
+						mode,
+						false, 
+						recursive, 
+						false, 
+						apiPathPrefix, 
+						collisionContext,
+						moduleID, 
+						sourceFolder,
+						cacheBust
+					);
+				}
+			} else {
+				
+				for (const subDir of directory.children.directories) {
+					const subDirName = this.slothlet.helpers.sanitize.sanitizePropertyName(subDir.name);
+
+					
+					
+					
+					
+					
+					
+					
+					
+					
+					
+					const lazy_currentCategoryName = apiPathPrefix ? apiPathPrefix.split(".").pop() : categoryName;
+					if (subDirName === lazy_currentCategoryName && lazy_currentCategoryName !== null && !populateDirectly) {
+						await this.processFiles(
+							targetApi,
+							subDir.children.files,
+							subDir,
+							currentDepth + 1,
+							"eager",
+							false,
+							true, 
+							true, 
+							apiPathPrefix,
+							collisionContext,
+							moduleID,
+							sourceFolder,
+							cacheBust
+						);
+						continue;
+					}
+
+					const apiPath = categoryName ? `${categoryName}.${subDirName}` : apiPathPrefix ? `${apiPathPrefix}.${subDirName}` : subDirName;
+					if (this.slothlet.config.debug?.modes) {
+						this.slothlet.debug("modes", {
+							key: "DEBUG_MODE_CREATING_LAZY_SUBDIRECTORY",
+							apiPath,
+							fileCount: subDir.children.files.length
+						});
+					}
+
+					
+					
+					
+					
+					
+					
+					
+					const collisionConfig = this.slothlet.config.api?.collision;
+					
+					
+					const modes_initialCollisionMode =
+						collisionModeOverride || (collisionContext === "initial" ? collisionConfig?.initial : collisionConfig?.api) || "replace";
+					
+					let modes_fileFolderImpl = null;
+					const modes_lazyExisting = targetApi[subDirName];
+					if (modes_initialCollisionMode !== "replace" && resolveWrapper(modes_lazyExisting)) {
+						const modes_lazyExistingW = resolveWrapper(modes_lazyExisting);
+						
+						const existImpl = modes_lazyExistingW.__impl;
+						
+						
+						if (existImpl && typeof existImpl === "object" && !Array.isArray(existImpl)) {
+							modes_fileFolderImpl = { ...existImpl };
+						}
+						
+						const existChildKeys = Object.keys(modes_lazyExistingW).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
+						for (const ck of existChildKeys) {
+							
+							
+							
+							
+							
+							
+							if (!modes_fileFolderImpl) modes_fileFolderImpl = {};
+							
+							
+							if (!(ck in modes_fileFolderImpl)) {
+								modes_fileFolderImpl[ck] = modes_lazyExistingW[ck];
+							}
+						}
+					}
+
+					this.slothlet.builders.apiAssignment.assignToApiPath(
+						targetApi,
+						subDirName,
+						this.createLazySubdirectoryWrapper(
+							subDir,
+							apiPath,
+							moduleID,
+							sourceFolder,
+							cacheBust,
+							modes_fileFolderImpl,
+							modes_initialCollisionMode
+						),
+						{
+							useCollisionDetection: true,
+							config: this.slothlet.config,
+							collisionContext
+						}
+					);
+				}
+			}
+		}
+		
+		if (isRoot && rootContributors.length > 0) {
+			if (rootContributors.length === 1) {
+				
+				const { moduleName, file, defaultFunc } = rootContributors[0];
+				rootDefaultFunction = defaultFunc;
+				if (this.slothlet.config.debug?.modes) {
+					this.slothlet.debug("modes", {
+						
+						
+						message: await t("DEBUG_MODE_ROOT_CONTRIBUTOR", { mode, functionName: defaultFunc.name || "anonymous" })
+					});
+				}
+				
+				
+				if (this.slothlet.handlers.ownership) {
+					this.slothlet.handlers.ownership.register({
+						
+						
+						moduleID: moduleID || file.moduleID,
+						apiPath: moduleName,
+						source: "core",
+						collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+						filePath: file.path
+					});
+				}
+			} else {
+				
+				new this.SlothletWarning("WARNING_MULTIPLE_ROOT_CONTRIBUTORS", {
+					rootContributors: rootContributors.map((rc) => rc.moduleName).join(", "),
+					firstContributor: rootContributors[0].moduleName
+				});
+				for (const { moduleName, file, defaultFunc } of rootContributors) {
+					
+					
+					
+					if (shouldWrap) {
+						const wrapper = new UnifiedWrapper(this.slothlet, {
+							mode: effectiveMode,
+							apiPath: buildApiPath(moduleName),
+							initialImpl: this.slothlet.helpers.modesUtils.cloneWrapperImpl(defaultFunc, mode),
+							materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+							filePath: file.path,
+							
+							
+							moduleID: moduleID || file.moduleID,
+							sourceFolder
+						});
+						this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, moduleName, wrapper.createProxy(), {
+							useCollisionDetection: true,
+							config: this.slothlet.config,
+							collisionContext
+						});
+						
+						
+						
+						
+						
+					} else {
+						this.slothlet.builders.apiAssignment.assignToApiPath(targetApi, moduleName, defaultFunc, {
+							useCollisionDetection: true,
+							config: this.slothlet.config,
+							collisionContext
+						});
+					}
+					
+					
+					
+					if (this.slothlet.handlers.ownership) {
+						this.slothlet.handlers.ownership.register({
+							
+							
+							moduleID: moduleID || file.moduleID,
+							apiPath: moduleName,
+							source: "core",
+							collisionMode: this.slothlet.helpers.modesUtils.getOwnershipCollisionMode(this.slothlet.config, collisionContext),
+							filePath: file.path
+						});
+					}
+				}
+			}
+		}
+		return rootDefaultFunction;
+	}
+	
+	createLazySubdirectoryWrapper(
+		dir,
+		apiPath,
+		moduleID = null,
+		sourceFolder = null,
+		cacheBust = null,
+		fileFolderCollisionImpl = null,
+		collisionMode = "merge"
+	) {
+		
+		
+		const lazy_materializeFunc = this.slothlet.modes.lazy.createNamedMaterializeFunc(apiPath, async () => {
+			if (this.slothlet.config.debug?.modes) {
+				this.slothlet.debug("modes", {
+					key: "DEBUG_MODE_MATERIALIZE_FUNCTION_STARTING",
+					dir: dir.name,
+					
+					
+					fileCount: dir.children.files?.length || 0
+				});
+			}
+			const categoryName = this.slothlet.helpers.sanitize.sanitizePropertyName(dir.name);
+			const materialized = {};
+
+			
+			
+			
+			
+			
+			const actualSourceFolder = sourceFolder
+				? `${sourceFolder}/${dir.name}`.replace(/\\/g, "/")
+				: `${this.slothlet.config?.dir}/${dir.name}`.replace(/\\/g, "/");
+			
+
+			
+			
+			
+			
+			const parentPrefix = apiPath.includes(".") ? apiPath.split(".").slice(0, -1).join(".") : "";
+			
+			
+			const subDirs = dir.children.directories || [];
+			if (dir.children.files.length === 1 && subDirs.length === 0) {
+				const file = dir.children.files[0];
+				const moduleName = this.slothlet.helpers.sanitize.sanitizePropertyName(file.name);
+				const genericFilenames = ["singlefile", "index", "main", "default"];
+				const isGeneric = genericFilenames.includes(moduleName.toLowerCase());
+				const filenameMatchesFolder = moduleName === categoryName;
+				if (isGeneric || filenameMatchesFolder) {
+					const mod = await this.slothlet.processors.loader.loadModule(file.path, this.slothlet.instanceID, moduleID, cacheBust);
+					const exports = this.slothlet.processors.loader.extractExports(mod);
+					const moduleKeys = Object.keys(exports).filter((k) => k !== "default");
+					const analysis = {
+						hasDefault: exports.default !== undefined,
+						hasNamed: moduleKeys.length > 0,
+						defaultExportType: exports.default ? typeof exports.default : null
+					};
+					const modContent = exports.default !== undefined ? exports.default : exports;
+					const categoryDecision = await this.slothlet.processors.flatten.buildCategoryDecisions({
+						categoryName,
+						mod: modContent,
+						moduleName,
+						fileBaseName: file.name,
+						analysis,
+						moduleKeys,
+						currentDepth: apiPath.split(".").length,
+						moduleFiles: dir.children.files,
+						t
+					});
+					if (categoryDecision.shouldFlatten) {
+						let implToWrap;
+
+						
+						
+						
+						if (categoryDecision.flattenType === "addapi-metadata-default") {
+							
+							implToWrap = exports.default;
+							for (const key of moduleKeys) {
+								
+								
+								if (key !== "default") {
+									implToWrap[key] = exports[key];
+								}
+							}
+						} else if (moduleName === categoryName && moduleKeys.includes(categoryName)) {
+							implToWrap = exports[categoryName];
+						} else if (exports.default !== undefined) {
+							implToWrap = exports.default;
+
+							
+							
+							
+							
+							if (moduleKeys.length > 0 && (typeof implToWrap === "function" || (typeof implToWrap === "object" && implToWrap !== null))) {
+								const collisionMode = this.slothlet.config?.collision?.initial || "merge";
+								for (const key of moduleKeys) {
+									
+									
+									
+									
+									
+									if (!this.slothlet.processors.flatten.shouldAttachNamedExport(key, exports[key], implToWrap, exports.default)) {
+										continue;
+									}
+									
+									const hasExisting = Object.prototype.hasOwnProperty.call(implToWrap, key);
+									if (hasExisting) {
+										if (collisionMode === "merge" || collisionMode === "skip") {
+											
+											continue;
+										} else if (collisionMode === "error") {
+											throw new this.slothlet.SlothletError(
+												"COLLISION_DEFAULT_EXPORT_ERROR",
+												{
+													key,
+													apiPath
+												},
+												null,
+												{ validationError: true }
+											);
+										} else if (collisionMode === "warn") {
+											new this.slothlet.SlothletWarning("WARNING_COLLISION_DEFAULT_EXPORT_OVERWRITE", {
+												key,
+												apiPath
+											});
+										}
+										
+									}
+									implToWrap[key] = exports[key];
+								}
+							}
+							
+						} else {
+							implToWrap = modContent;
+						}
+						
+						
+						
+						
+						
+						
+						
+
+						
+						if (implToWrap && typeof implToWrap === "object" && this.slothlet.handlers?.lifecycle) {
+							for (const key of Object.keys(implToWrap)) {
+								const value = implToWrap[key];
+								if (typeof value === "function") {
+									this.slothlet.handlers.lifecycle.emit("impl:created", {
+										apiPath: `${apiPath}.${key}`,
+										impl: value,
+										source: "lazy-materialization",
+										moduleID: moduleID,
+										filePath: file.path,
+										
+										
+										sourceFolder: sourceFolder || this.slothlet.config?.dir
+									});
+								}
+							}
+						}
+
+						
+						
+						if (implToWrap && typeof implToWrap === "object") {
+							
+							const childPaths = {};
+							for (const key of Object.keys(implToWrap)) {
+								if (typeof key !== "symbol" && key !== "__childFilePaths" && key !== "__filePath") {
+									childPaths[key] = file.path;
+								}
+							}
+
+							
+							
+							
+							
+							
+
+							implToWrap.__childFilePaths = childPaths;
+						}
+
+						
+						if (fileFolderCollisionImpl && typeof implToWrap === "object" && implToWrap !== null) {
+							for (const [k, v] of Object.entries(fileFolderCollisionImpl)) {
+								if (!(k in implToWrap)) {
+									implToWrap[k] = v;
+								}
+							}
+						} else if (fileFolderCollisionImpl && typeof implToWrap === "function") {
+							for (const [k, v] of Object.entries(fileFolderCollisionImpl)) {
+								
+								
+								if (implToWrap[k] === undefined) {
+									implToWrap[k] = v;
+								}
+							}
+						}
+
+						return implToWrap;
+					}
+				}
+			}
+			
+			
+			
+			await this.processFiles(
+				materialized,
+				dir.children.files,
+				{ name: dir.name, children: dir.children },
+				0,
+				"eager",
+				false, 
+				false, 
+				true, 
+				parentPrefix, 
+				"initial",
+				moduleID, 
+				actualSourceFolder, 
+				cacheBust,
+				collisionMode 
+			);
+			if (this.slothlet.config.debug?.modes) {
+				this.slothlet.debug("modes", {
+					key: "DEBUG_MODE_MATERIALIZE_FUNCTION_RETURNING_IMPL",
+					dir: dir.name,
+					keys: Object.keys(materialized)
+				});
+			}
+
+			
+			
+			if (fileFolderCollisionImpl) {
+				for (const [k, v] of Object.entries(fileFolderCollisionImpl)) {
+					
+					
+					if (!(k in materialized)) {
+						materialized[k] = v;
+					}
+				}
+			}
+
+			const materializedKeys = Object.keys(materialized);
+			
+			
+			
+			
+			
+			
+			const _hasCategoryFile = dir.children.files.some((f) => this.slothlet.helpers.sanitize.sanitizePropertyName(f.name) === categoryName);
+			if (_hasCategoryFile && materializedKeys.includes(categoryName) && materializedKeys.length > 1) {
+				if (this.slothlet.config.debug?.modes) {
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_FOLDER_PATTERN_MATCH",
+						dir: dir.name,
+						categoryName,
+						keys: materializedKeys
+					});
+				}
+				const mainValue = materialized[categoryName];
+				
+				for (const key of materializedKeys) {
+					if (key !== categoryName) {
+						if (this.slothlet.config.debug?.modes) {
+							this.slothlet.debug("modes", {
+								key: "DEBUG_MODE_FOLDER_PATTERN_ATTACH_PROPERTY",
+								categoryName,
+								propKey: key,
+								valueType: typeof materialized[key]
+							});
+						}
+						mainValue[key] = materialized[key];
+					}
+				}
+				if (this.slothlet.config.debug?.modes) {
+					this.slothlet.debug("modes", {
+						key: "DEBUG_MODE_FOLDER_PATTERN_RETURN",
+						categoryName,
+						keys: Object.keys(mainValue).filter((k) => !k.startsWith("__"))
+					});
+				}
+				return mainValue;
+			}
+			if (materializedKeys.length === 1 && materializedKeys[0] === categoryName) {
+				const nestedValue = materialized[categoryName];
+				
+				
+				
+				
+				
+				if (nestedValue && resolveWrapper(nestedValue) !== null) {
+					const attachedKeys = Object.keys(nestedValue).filter((key) => key !== "____slothletInternal");
+					
+					
+					if (attachedKeys.length > 0) {
+						return nestedValue;
+					}
+					
+					return nestedValue.__impl ?? nestedValue;
+					
+					
+					
+				} else {
+					return nestedValue;
+				}
+				
+			}
+			
+			return materialized;
+		});
+		
+		const wrapper = new UnifiedWrapper(this.slothlet, {
+			mode: "lazy",
+			apiPath,
+			materializeFunc: lazy_materializeFunc,
+			materializeOnCreate: this.slothlet.config.backgroundMaterialize,
+			filePath: dir.path, 
+			moduleID: moduleID, 
+			sourceFolder
+		});
+
+		
+		
+		
+		
+		if (collisionMode) {
+			wrapper.____slothletInternal.state.collisionMode = collisionMode;
+		}
+
+		
+		
+		
+		
+		
+		
+		
+		
+		
+		const shouldPrePopulate = collisionMode === "merge" || collisionMode === "warn";
+		if (fileFolderCollisionImpl && shouldPrePopulate) {
+			for (const [k, v] of Object.entries(fileFolderCollisionImpl)) {
+				
+				
+				if (typeof k === "string" && !k.startsWith("_") && !k.startsWith("__")) {
+					Object.defineProperty(wrapper, k, {
+						value: v,
+						writable: false,
+						enumerable: true,
+						configurable: true
+					});
+				}
+			}
+		}
+
+		return wrapper.createProxy();
+	}
+	
+	async applyRootContributor(api, rootFunction, mode) {
+		if (rootFunction) {
+			
+			
+			
+			
+			
+			
+			Object.assign(rootFunction, api);
+			if (this.slothlet.config.debug?.modes) {
+				this.slothlet.debug("modes", {
+					message: await t("DEBUG_MODE_ROOT_CONTRIBUTOR_APPLIED", { mode, properties: Object.keys(api).length })
+				});
+			}
+			return rootFunction;
+		}
+		return api;
+	}
+}