@cldmv/slothlet 2.9.0 → 2.11.0

package/AGENT-USAGE.md

@@ -144,6 +144,47 @@ export function rootFunctionShout(message) {
 
 > 📖 **See**: [API-RULES.md Rule 4](./API-RULES.md#rule-4-default-export-container-pattern) for root-level default export handling
 
+### Pattern 5: AddApi Special File Pattern (Rule 11)
+
+**File**: `addapi.mjs` loaded via `addApi()` → **API**: Always flattened for API extensions
+
+```js
+// File: plugins/addapi.mjs
+/**
+ * Special addapi.mjs file for runtime API extensions.
+ * Always flattens regardless of autoFlatten setting.
+ */
+export function initializePlugin() {
+	return "Plugin initialized";
+}
+
+export function cleanup() {
+	return "Plugin cleaned up";
+}
+
+export function configure(options) {
+	return `Configured with ${options}`;
+}
+
+// Usage:
+await api.addApi("plugins", "./plugins-folder");
+
+// Result: Always flattened (no .addapi. level)
+api.plugins.initializePlugin(); // ✅ Direct extension
+api.plugins.cleanup(); // ✅ No intermediate namespace
+api.plugins.configure(opts); // ✅ Seamless integration
+```
+
+**Result**: `addapi.mjs` always flattens → Perfect for plugin systems and runtime extensions
+
+**Use Cases**:
+
+- 🔌 **Plugin Systems**: Runtime plugin loading
+- 🔄 **Hot Reloading**: Dynamic API updates during development
+- 📦 **Modular Extensions**: Clean extension of existing API surfaces
+
+> 📖 **See**: [API-RULES.md Rule 11](./API-RULES.md#rule-11-addapi-special-file-pattern) for technical implementation details
+
 ## 🔄 Cross-Module Communication Patterns
 
 ### ✅ Using Live Bindings

package/README.md

@@ -35,14 +35,19 @@ The name might suggest we're taking it easy, but don't be fooled. **Slothlet del
 
 ## ✨ What's New
 
-### Latest: v2.9 (December 30, 2025)
+### Latest: v2.11.0 (January 2025)
 
-- **Per-Request Context Isolation** - New `api.run()` and `api.scope()` methods for isolated context execution ([Documentation](https://github.com/CLDMV/slothlet/blob/master/docs/CONTEXT-PROPAGATION.md#per-request-context-isolation))
-- API Builder Modularization - Improved maintainability and code organization
-- [View Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.9.md)
+- **AddApi Special File Pattern (Rule 11)** - Files named `addapi.mjs` now always flatten for seamless API namespace extensions
+- **Filename-Matches-Container in addApi (Rule 1 Extension)** - Auto-flattening now works in runtime `addApi()` contexts
+- **Enhanced addApi Content Preservation** - Fixed critical issue where multiple addApi calls were overwriting previous content instead of merging
+- **Rule 12 Smart Flattening Enhancements** - Comprehensive smart flattening improvements with 168-scenario test coverage
+- **API Documentation Suite Overhaul** - Enhanced 3-tier navigation system with verified examples and cross-references
+- [View Changelog](./docs/changelog/v2.11.md)
 
 ### Recent Releases
 
+- **v2.10.0** - Function metadata tagging and introspection capabilities ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.10.md))
+- **v2.9** - Per-Request Context Isolation with `api.run()` and `api.scope()` methods ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.9.md))
 - **v2.8** - NPM security fixes and package workflow updates ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.8.md))
 - **v2.7** - Security updates ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.7.md))
 - **v2.6** - Hook System with 4 interceptor types ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.6.md))
@@ -130,7 +135,8 @@ Automatic context preservation across all asynchronous boundaries:
 
 ### Requirements
 
-- **Node.js v16.4.0 or higher** (required for AsyncLocalStorage support)
+- **Node.js v16.20.2 or higher** (required for stack trace API fixes used in path resolution)
+  - Node.js 16.4-16.19 has a stack trace regression. For these versions, use slothlet 2.10.0: `npm install @cldmv/slothlet@2.10.0`
 
 ### Install
 
@@ -253,25 +259,93 @@ api.hooks.on(
 const result = await api.math.add(2, 3);
 ```
 
+### Dynamic API Extension with addApi()
+
+Load additional modules at runtime and extend your API dynamically:
+
+```javascript
+import slothlet from "@cldmv/slothlet";
+
+const api = await slothlet({ dir: "./api" });
+
+// Add plugins at runtime
+await api.addApi("plugins", "./plugins-folder");
+api.plugins.myPlugin();
+
+// Create nested API structures
+await api.addApi("runtime.plugins", "./more-plugins");
+api.runtime.plugins.loader();
+
+// Add with metadata for security/authorization
+await api.addApi("plugins.trusted", "./trusted-plugins", {
+	trusted: true,
+	permissions: ["read", "write", "admin"],
+	version: "1.0.0"
+});
+
+await api.addApi("plugins.external", "./third-party", {
+	trusted: false,
+	permissions: ["read"]
+});
+
+// Access metadata on functions
+const meta = api.plugins.trusted.someFunc.__metadata;
+console.log(meta.trusted); // true
+console.log(meta.permissions); // ["read", "write", "admin"]
+```
+
+**Security & Authorization with metadataAPI:**
+
+```javascript
+// Inside your modules, use metadataAPI for runtime introspection
+import { metadataAPI } from "@cldmv/slothlet/runtime";
+
+export async function sensitiveOperation() {
+	// Check caller's metadata
+	const caller = await metadataAPI.caller();
+
+	if (!caller?.trusted) {
+		throw new Error("Unauthorized: Caller is not trusted");
+	}
+
+	if (!caller.permissions.includes("admin")) {
+		throw new Error("Unauthorized: Admin permission required");
+	}
+
+	// Proceed with secure operation
+	return "Success";
+}
+
+// Get metadata by path
+const meta = await metadataAPI.get("plugins.trusted.someFunc");
+
+// Get current function's metadata
+const self = await metadataAPI.self();
+console.log("My version:", self.version);
+```
+
+🔒 **For complete metadata system documentation, see [docs/METADATA.md](https://github.com/CLDMV/slothlet/blob/master/docs/METADATA.md)**
+
 ---
 
 ## 📚 Configuration Options
 
-| Option              | Type      | Default       | Description                                                                                                                                                                                              |
-| ------------------- | --------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dir`               | `string`  | `"api"`       | Directory to load API modules from (absolute or relative path)                                                                                                                                           |
-| `mode`              | `string`  | `"eager"`     | **New** loading mode - `"lazy"` for on-demand loading, `"eager"` for immediate loading                                                                                                                   |
-| `lazy`              | `boolean` | `false`       | **Legacy** loading strategy (use `mode` instead)                                                                                                                                                         |
-| `engine`            | `string`  | `"singleton"` | Execution environment: `"singleton"`, `"vm"`, `"worker"`, or `"fork"` (experimental modes)                                                                                                               |
-| `runtime`           | `string`  | `"async"`     | Runtime binding system: `"async"` for AsyncLocalStorage (requires Node.js v16.4.0+), `"live"` for live-bindings (works on Node.js v12.20.0+)                                                             |
-| `apiDepth`          | `number`  | `Infinity`    | Directory traversal depth - `0` for root only, `Infinity` for all levels                                                                                                                                 |
-| `debug`             | `boolean` | `false`       | Enable verbose logging (also via `--slothletdebug` flag or `SLOTHLET_DEBUG=true` env var)                                                                                                                |
-| `api_mode`          | `string`  | `"auto"`      | API structure behavior: `"auto"` (detect), `"function"` (force callable), `"object"` (force object)                                                                                                      |
-| `allowApiOverwrite` | `boolean` | `true`        | Allow `addApi()` to overwrite existing endpoints (`false` = prevent overwrites with warning)                                                                                                             |
-| `context`           | `object`  | `{}`          | Context data injected into live-binding (available via `import { context } from "@cldmv/slothlet/runtime"`)                                                                                              |
-| `reference`         | `object`  | `{}`          | Reference object merged into API root level                                                                                                                                                              |
-| `sanitize`          | `object`  | `{}`          | Advanced filename-to-API transformation control with `lowerFirst`, `preserveAllUpper`, `preserveAllLower`, and `rules` (supports exact matches, glob patterns `*json*`, and boundary patterns `**url**`) |
-| `hooks`             | `mixed`   | `false`       | Enable hook system: `true` (enable all), `"pattern"` (enable with pattern), or object with `enabled`, `pattern`, `suppressErrors` options                                                                |
+| Option                  | Type      | Default       | Description                                                                                                                                                                                              |
+| ----------------------- | --------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dir`                   | `string`  | `"api"`       | Directory to load API modules from (absolute or relative path)                                                                                                                                           |
+| `mode`                  | `string`  | `"eager"`     | **New** loading mode - `"lazy"` for on-demand loading, `"eager"` for immediate loading                                                                                                                   |
+| `lazy`                  | `boolean` | `false`       | **Legacy** loading strategy (use `mode` instead)                                                                                                                                                         |
+| `engine`                | `string`  | `"singleton"` | Execution environment: `"singleton"`, `"vm"`, `"worker"`, or `"fork"` (experimental modes)                                                                                                               |
+| `runtime`               | `string`  | `"async"`     | Runtime binding system: `"async"` for AsyncLocalStorage (requires Node.js v16.20.2+), `"live"` for live-bindings (works on Node.js v12.20.0+)                                                            |
+| `apiDepth`              | `number`  | `Infinity`    | Directory traversal depth - `0` for root only, `Infinity` for all levels                                                                                                                                 |
+| `debug`                 | `boolean` | `false`       | Enable verbose logging (also via `--slothletdebug` flag or `SLOTHLET_DEBUG=true` env var)                                                                                                                |
+| `api_mode`              | `string`  | `"auto"`      | API structure behavior: `"auto"` (detect), `"function"` (force callable), `"object"` (force object)                                                                                                      |
+| `allowApiOverwrite`     | `boolean` | `true`        | Allow `addApi()` to overwrite existing endpoints (`false` = prevent overwrites with warning)                                                                                                             |
+| `enableModuleOwnership` | `boolean` | `false`       | Enable module-based API ownership tracking (`true` = track ownership for selective overwrites, `false` = disabled for performance)                                                                       |
+| `context`               | `object`  | `{}`          | Context data injected into live-binding (available via `import { context } from "@cldmv/slothlet/runtime"`)                                                                                              |
+| `reference`             | `object`  | `{}`          | Reference object merged into API root level                                                                                                                                                              |
+| `sanitize`              | `object`  | `{}`          | Advanced filename-to-API transformation control with `lowerFirst`, `preserveAllUpper`, `preserveAllLower`, and `rules` (supports exact matches, glob patterns `*json*`, and boundary patterns `**url**`) |
+| `hooks`                 | `mixed`   | `false`       | Enable hook system: `true` (enable all), `"pattern"` (enable with pattern), or object with `enabled`, `pattern`, `suppressErrors` options                                                                |
 
 **For complete API documentation with detailed parameter descriptions and examples, see [docs/generated/API.md](https://github.com/CLDMV/slothlet/blob/master/docs/generated/API.md)**
 
@@ -481,6 +555,7 @@ Key highlights:
 
 - **[Hook System](https://github.com/CLDMV/slothlet/blob/master/docs/HOOKS.md)** - Complete hook system documentation with 4 hook types, pattern matching, and examples
 - **[Context Propagation](https://github.com/CLDMV/slothlet/blob/master/docs/CONTEXT-PROPAGATION.md)** - EventEmitter and class instance context preservation
+- **[Metadata System](https://github.com/CLDMV/slothlet/blob/master/docs/METADATA.md)** - Function metadata tagging and runtime introspection for security, authorization, and auditing
 - **[Module Structure](https://github.com/CLDMV/slothlet/blob/master/docs/MODULE-STRUCTURE.md)** - Comprehensive module organization patterns and examples
 - **[API Flattening](https://github.com/CLDMV/slothlet/blob/master/docs/API-FLATTENING.md)** - The 5 flattening rules with decision tree and benefits
 

package/dist/lib/engine/slothlet_child.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/engine/slothlet_engine.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/engine/slothlet_esm.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/engine/slothlet_helpers.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/engine/slothlet_worker.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/helpers/als-eventemitter.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.

package/dist/lib/helpers/api_builder/add_api.mjs

@@ -1,5 +1,5 @@
 /*
-	Copyright 2025 CLDMV/Shinrai
+	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.
@@ -21,9 +21,23 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolvePathFromCaller } from "@cldmv/slothlet/helpers/resolve-from-caller";
+import { cleanMetadata, tagLoadedFunctions } from "./metadata.mjs";
 
 
-export async function addApiFromFolder({ apiPath, folderPath, instance }) {
+
+
+export async function addApiFromFolder({ apiPath, folderPath, instance, metadata = {}, options = {} }) {
+	const { forceOverwrite = false, moduleId } = options;
+
+	
+	if (forceOverwrite && !moduleId) {
+		throw new Error(`[slothlet] Rule 12: forceOverwrite requires moduleId parameter for ownership tracking`);
+	}
+
+	if (forceOverwrite && !instance.config.enableModuleOwnership) {
+		throw new Error(`[slothlet] Rule 12: forceOverwrite requires enableModuleOwnership: true in slothlet configuration`);
+	}
+
 	if (!instance.loaded) {
 		throw new Error("[slothlet] Cannot add API: API not loaded. Call create() or load() first.");
 	}
@@ -47,9 +61,21 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 	}
 
 	
+	
+	
 	let resolvedFolderPath = folderPath;
-	if (!path.isAbsolute(folderPath)) {
+	const isAbsolute = path.isAbsolute(folderPath);
+
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: folderPath="${folderPath}"`);
+		console.log(`[DEBUG] addApi: isAbsolute=${isAbsolute}`);
+	}
+
+	if (!isAbsolute) {
 		resolvedFolderPath = resolvePathFromCaller(folderPath);
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Resolved relative path to: ${resolvedFolderPath}`);
+		}
 	}
 
 	
@@ -68,6 +94,74 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 	}
 
 	
+	
+	
+
+	
+	let earlyCurrentTarget = instance.api;
+	let earlyCurrentBoundTarget = instance.boundapi;
+	const earlyPathParts = normalizedApiPath.split(".");
+
+	for (let i = 0; i < earlyPathParts.length - 1; i++) {
+		const part = earlyPathParts[i];
+		const key = instance._toapiPathKey(part);
+		if (earlyCurrentTarget[key]) {
+			earlyCurrentTarget = earlyCurrentTarget[key];
+		} else {
+			earlyCurrentTarget = null;
+			break;
+		}
+		if (earlyCurrentBoundTarget[key]) {
+			earlyCurrentBoundTarget = earlyCurrentBoundTarget[key];
+		} else {
+			earlyCurrentBoundTarget = null;
+			break;
+		}
+	}
+
+	const earlyFinalKey = instance._toapiPathKey(earlyPathParts[earlyPathParts.length - 1]);
+	let superEarlyExistingTargetContent = null;
+	let superEarlyExistingBoundContent = null;
+
+	if (earlyCurrentTarget && earlyCurrentTarget[earlyFinalKey]) {
+		if (typeof earlyCurrentTarget[earlyFinalKey] === "function" && earlyCurrentTarget[earlyFinalKey].__slothletPath) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: SUPER EARLY - Target is lazy proxy - materializing to capture existing content`);
+			}
+			const _ = earlyCurrentTarget[earlyFinalKey].__trigger;
+			await earlyCurrentTarget[earlyFinalKey]();
+		}
+		if (typeof earlyCurrentTarget[earlyFinalKey] === "object") {
+			superEarlyExistingTargetContent = { ...earlyCurrentTarget[earlyFinalKey] };
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: SUPER EARLY - Captured existing target content:`, Object.keys(superEarlyExistingTargetContent));
+			}
+		}
+	}
+
+	if (earlyCurrentBoundTarget && earlyCurrentBoundTarget[earlyFinalKey]) {
+		if (instance.config.debug) {
+			console.log(
+				`[DEBUG] addApi: SUPER EARLY - currentBoundTarget[${earlyFinalKey}] exists, type:`,
+				typeof earlyCurrentBoundTarget[earlyFinalKey]
+			);
+		}
+		if (typeof earlyCurrentBoundTarget[earlyFinalKey] === "function" && earlyCurrentBoundTarget[earlyFinalKey].__slothletPath) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: SUPER EARLY - Bound target is lazy proxy - materializing to capture existing bound content`);
+			}
+			const _ = earlyCurrentBoundTarget[earlyFinalKey].__trigger;
+			await earlyCurrentBoundTarget[earlyFinalKey]();
+		}
+		if (typeof earlyCurrentBoundTarget[earlyFinalKey] === "object") {
+			superEarlyExistingBoundContent = { ...earlyCurrentBoundTarget[earlyFinalKey] };
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: SUPER EARLY - Captured existing bound content:`, Object.keys(superEarlyExistingBoundContent));
+			}
+		}
+	}
+
+	
 	let newModules;
 	if (instance.config.lazy) {
 		
@@ -77,6 +171,110 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 		newModules = await instance.modes.eager.create.call(instance, resolvedFolderPath, instance.config.apiDepth || Infinity, 0);
 	}
 
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: Loaded modules structure:`, Object.keys(newModules || {}));
+		console.log(`[DEBUG] addApi: Full newModules:`, newModules);
+	}
+
+	
+	
+	if (newModules && typeof newModules === "object" && newModules.addapi) {
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Found addapi.mjs - applying Rule 6 flattening`);
+			console.log(`[DEBUG] addApi: Original structure:`, Object.keys(newModules));
+			console.log(`[DEBUG] addApi: Addapi contents:`, Object.keys(newModules.addapi));
+		}
+
+		
+		const addapiContent = newModules.addapi;
+
+		
+		delete newModules.addapi;
+
+		
+		if (addapiContent && typeof addapiContent === "object") {
+			
+			Object.assign(newModules, addapiContent);
+
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: After addapi flattening:`, Object.keys(newModules));
+			}
+		} else if (typeof addapiContent === "function") {
+			
+			Object.assign(newModules, addapiContent);
+
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: Flattened addapi function with properties:`, Object.keys(newModules));
+			}
+		}
+	}
+
+	
+	
+	
+	const pathSegments = normalizedApiPath.split(".");
+	const lastSegment = pathSegments[pathSegments.length - 1];
+	let rootLevelFileContent = null;
+
+	if (newModules && typeof newModules === "object" && newModules[lastSegment]) {
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Found root-level file matching API path segment "${lastSegment}" - applying Rule 7 flattening`);
+		}
+
+		
+		let fileContent = newModules[lastSegment];
+		if (typeof fileContent === "function" && fileContent.name && fileContent.name.startsWith("lazyFolder_")) {
+			
+			if (fileContent.__slothletPath) {
+				const _ = fileContent.__trigger; 
+				await fileContent(); 
+				
+				fileContent = newModules[lastSegment]; 
+				if (instance.config.debug) {
+					console.log(`[DEBUG] addApi: Materialized lazy proxy for root-level file:`, Object.keys(fileContent || {}));
+				}
+			}
+		}
+
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Root-level file content:`, Object.keys(fileContent || {}));
+		}
+
+		
+		
+		rootLevelFileContent = fileContent && typeof fileContent === "object" ? { ...fileContent } : fileContent;
+
+		
+		delete newModules[lastSegment];
+
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: After removing root-level file, remaining structure:`, Object.keys(newModules));
+		}
+	}
+
+	
+	
+	
+	if (newModules && metadata && typeof metadata === "object" && Object.keys(metadata).length > 0) {
+		
+		const fullMetadata = {
+			...metadata,
+			sourceFolder: resolvedFolderPath
+		};
+
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Tagging functions with metadata:`, Object.keys(fullMetadata));
+		}
+
+		tagLoadedFunctions(newModules, fullMetadata, resolvedFolderPath);
+	} else if (newModules) {
+		
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Cleaning metadata from functions (no metadata provided)`);
+		}
+		cleanMetadata(newModules);
+	}
+
 	if (instance.config.debug) {
 		if (newModules && typeof newModules === "object") {
 			console.log(`[DEBUG] addApi: Loaded modules:`, Object.keys(newModules));
@@ -133,6 +331,14 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 	
 	const finalKey = instance._toapiPathKey(pathParts[pathParts.length - 1]);
 
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: Final assignment - newModules type:`, typeof newModules, "keys:", Object.keys(newModules || {}));
+	}
+
+	
+	
+	
+
 	
 	if (typeof newModules === "function") {
 		
@@ -141,7 +347,21 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 			const existing = currentTarget[finalKey];
 
 			
-			if (instance.config.allowApiOverwrite === false) {
+			if (instance.config.enableModuleOwnership && existing) {
+				const normalizedPath = normalizedApiPath + (normalizedApiPath ? "." : "") + finalKey;
+				const canOverwrite = instance._validateModuleOwnership(normalizedPath, moduleId, forceOverwrite);
+
+				if (forceOverwrite && !canOverwrite) {
+					const existingOwner = instance._getApiOwnership(normalizedPath);
+					throw new Error(
+						`[slothlet] Rule 12: Cannot overwrite API "${normalizedPath}" - owned by module "${existingOwner}", ` +
+							`attempted by module "${moduleId}". Modules can only overwrite APIs they own.`
+					);
+				}
+			}
+
+			
+			if (!forceOverwrite && instance.config.allowApiOverwrite === false) {
 				console.warn(
 					`[slothlet] Skipping addApi: API path "${normalizedApiPath}" final key "${finalKey}" ` +
 						`already exists (type: "${typeof existing}"). Set allowApiOverwrite: true to allow overwrites.`
@@ -170,7 +390,21 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 			const existing = currentTarget[finalKey];
 
 			
-			if (instance.config.allowApiOverwrite === false && existing !== undefined && existing !== null) {
+			if (instance.config.enableModuleOwnership && existing) {
+				const normalizedPath = normalizedApiPath + (normalizedApiPath ? "." : "") + finalKey;
+				const canOverwrite = instance._validateModuleOwnership(normalizedPath, moduleId, forceOverwrite);
+
+				if (forceOverwrite && !canOverwrite) {
+					const existingOwner = instance._getApiOwnership(normalizedPath);
+					throw new Error(
+						`[slothlet] Rule 12: Cannot overwrite API "${normalizedPath}" - owned by module "${existingOwner}", ` +
+							`attempted by module "${moduleId}". Modules can only overwrite APIs they own.`
+					);
+				}
+			}
+
+			
+			if (!forceOverwrite && instance.config.allowApiOverwrite === false && existing !== undefined && existing !== null) {
 				
 				const hasContent = typeof existing === "object" ? Object.keys(existing).length > 0 : true;
 				if (hasContent) {
@@ -200,6 +434,25 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 		}
 
 		
+		
+		
+		const targetValue = currentTarget[finalKey];
+		if (typeof targetValue === "function" && targetValue.__slothletPath) {
+			
+			
+			const _ = targetValue.__trigger; 
+			await targetValue(); 
+			
+		}
+
+		const boundTargetValue = currentBoundTarget[finalKey];
+		if (typeof boundTargetValue === "function" && boundTargetValue.__slothletPath) {
+			
+			const _ = boundTargetValue.__trigger;
+			await boundTargetValue();
+		}
+
+		
 		if (!currentTarget[finalKey]) {
 			currentTarget[finalKey] = {};
 		}
@@ -212,8 +465,54 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 		
 		
 		
+
+		
+		if (superEarlyExistingTargetContent) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: Restoring existing content - keys:`, Object.keys(superEarlyExistingTargetContent));
+			}
+			Object.assign(currentTarget[finalKey], superEarlyExistingTargetContent);
+		}
+		if (superEarlyExistingBoundContent) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: Restoring existing BOUND content - keys:`, Object.keys(superEarlyExistingBoundContent));
+			}
+			Object.assign(currentBoundTarget[finalKey], superEarlyExistingBoundContent);
+		}
+
+		
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Before merging new modules - current keys:`, Object.keys(currentTarget[finalKey] || {}));
+			console.log(`[DEBUG] addApi: New modules to merge - keys:`, Object.keys(newModules));
+		}
 		Object.assign(currentTarget[finalKey], newModules);
 		Object.assign(currentBoundTarget[finalKey], newModules);
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: After merging new modules - keys:`, Object.keys(currentTarget[finalKey] || {}));
+		}
+
+		
+		if (rootLevelFileContent !== null) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: Merging root-level file content into API path "${normalizedApiPath}"`);
+				console.log(`[DEBUG] addApi: Root-level file functions:`, Object.keys(rootLevelFileContent));
+				console.log(`[DEBUG] addApi: Target before root-level merge:`, Object.keys(currentTarget[finalKey]));
+			}
+
+			
+			if (rootLevelFileContent && typeof rootLevelFileContent === "object") {
+				Object.assign(currentTarget[finalKey], rootLevelFileContent);
+				Object.assign(currentBoundTarget[finalKey], rootLevelFileContent);
+			} else if (typeof rootLevelFileContent === "function") {
+				
+				Object.assign(currentTarget[finalKey], rootLevelFileContent);
+				Object.assign(currentBoundTarget[finalKey], rootLevelFileContent);
+			}
+
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: After merging root-level file, final API structure:`, Object.keys(currentTarget[finalKey]));
+			}
+		}
 	} else if (newModules === null || newModules === undefined) {
 		
 		const receivedType = newModules === null ? "null" : "undefined";
@@ -229,7 +528,24 @@ export async function addApiFromFolder({ apiPath, folderPath, instance }) {
 	}
 
 	
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: Before updateBindings - currentTarget[${finalKey}]:`, Object.keys(currentTarget[finalKey] || {}));
+		console.log(
+			`[DEBUG] addApi: Before updateBindings - currentBoundTarget[${finalKey}]:`,
+			Object.keys(currentBoundTarget[finalKey] || {})
+		);
+	}
+
+	
+	if (instance.config.enableModuleOwnership && moduleId) {
+		const fullApiPath = normalizedApiPath + (normalizedApiPath ? "." : "") + finalKey;
+		instance._registerApiOwnership(fullApiPath, moduleId);
+	}
+
 	instance.updateBindings(instance.context, instance.reference, instance.boundapi);
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: After updateBindings - api[${finalKey}]:`, Object.keys(instance.api[finalKey] || {}));
+	}
 
 	if (instance.config.debug) {
 		console.log(`[DEBUG] addApi: Successfully added modules at ${normalizedApiPath}`);