@cldmv/slothlet 2.9.0 → 2.10.0

package/dist/lib/helpers/metadata-api.mjs

@@ -0,0 +1,201 @@
+/*
+	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 { getStack, toFsPath } from "@cldmv/slothlet/helpers/resolve-from-caller";
+
+
+let runtimeModule = null;
+let runtimeImportPromise = null;
+
+
+async function ensureRuntime() {
+	if (runtimeModule) {
+		return runtimeModule;
+	}
+
+	if (!runtimeImportPromise) {
+		runtimeImportPromise = import("@cldmv/slothlet/runtime")
+			.then((module) => {
+				runtimeModule = module;
+				return module;
+			})
+			.catch((err) => {
+				console.error("[slothlet] Failed to import runtime for metadata API:", err.message);
+				runtimeModule = {}; 
+				return {};
+			});
+	}
+
+	return runtimeImportPromise;
+}
+
+
+function getApiRoot() {
+	
+	return runtimeModule?.self || null;
+}
+
+
+function findFunctionByStack(apiRoot, targetFile, targetLine, visited = new WeakSet()) {
+	if (!apiRoot || visited.has(apiRoot)) return null;
+	visited.add(apiRoot);
+
+	
+	if (typeof apiRoot === "function" && apiRoot.__sourceFile && apiRoot.__sourceLine) {
+		if (apiRoot.__sourceFile === targetFile && apiRoot.__sourceLine === targetLine) {
+			return apiRoot;
+		}
+	}
+
+	
+	if (typeof apiRoot === "object" || typeof apiRoot === "function") {
+		const keys = Object.keys(apiRoot);
+		for (const key of keys) {
+			
+			if (key.startsWith("_") || ["hooks", "shutdown", "addApi", "describe", "run"].includes(key)) {
+				continue;
+			}
+
+			const result = findFunctionByStack(apiRoot[key], targetFile, targetLine, visited);
+			if (result) return result;
+		}
+	}
+
+	return null;
+}
+
+
+function findFunctionByPath(apiRoot, path) {
+	if (!path || typeof path !== "string") return null;
+
+	const parts = path.split(".");
+	let current = apiRoot;
+
+	for (const part of parts) {
+		if (!current || (typeof current !== "object" && typeof current !== "function")) {
+			if (process.env.SLOTHLET_DEBUG) {
+				console.log("[findFunctionByPath] Failed: current is", typeof current);
+			}
+			return null;
+		}
+		current = current[part];
+	}
+
+	const result = typeof current === "function" ? current : null;
+	if (process.env.SLOTHLET_DEBUG) {
+		console.log("[findFunctionByPath] Result:", result ? "function found" : "null");
+	}
+	return result;
+}
+
+
+function parseCallSite(cs) {
+	if (!cs) return null;
+
+	const fileName = cs.getFileName?.();
+	if (!fileName) return null;
+
+	
+	const filePath = toFsPath(fileName);
+	if (!filePath) return null;
+
+	
+	if (filePath.startsWith?.("node:internal")) return null;
+
+	const lineNum = cs.getLineNumber?.();
+	if (typeof lineNum !== "number") return null;
+
+	return { file: filePath, line: lineNum };
+}
+
+
+export const metadataAPI = {
+	
+	async caller() {
+		
+		await ensureRuntime();
+
+		
+		const apiRoot = getApiRoot();
+		if (!apiRoot || typeof apiRoot !== "object") return null;
+
+		
+		const stack = getStack(metadataAPI.caller);
+
+		
+		
+		
+		if (stack.length < 1) return null;
+
+		const parsed = parseCallSite(stack[0]);
+		if (!parsed) return null;
+
+		
+		const func = findFunctionByStack(apiRoot, parsed.file, parsed.line);
+		if (!func) return null;
+
+		
+		return func.__metadata || null;
+	},
+
+	
+	async self() {
+		
+		await ensureRuntime();
+
+		
+		const apiRoot = getApiRoot();
+		if (!apiRoot || typeof apiRoot !== "object") return null;
+
+		
+		const stack = getStack(metadataAPI.self);
+
+		
+		if (stack.length < 1) return null;
+
+		const parsed = parseCallSite(stack[0]);
+		if (!parsed) return null;
+
+		
+		const func = findFunctionByStack(apiRoot, parsed.file, parsed.line);
+		if (!func) return null;
+
+		
+		return func.__metadata || null;
+	},
+
+	
+	async get(path, apiRoot) {
+		
+		await ensureRuntime();
+
+		
+		const root = apiRoot || getApiRoot();
+		if (!root || (typeof root !== "object" && typeof root !== "function")) {
+			return null;
+		}
+
+		const func = findFunctionByPath(root, path);
+		if (!func) return null;
+
+		
+		return func.__metadata || null;
+	}
+};

package/dist/lib/helpers/multidefault.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.
@@ -39,10 +39,19 @@ async function multidefault_analyzeModules(moduleFiles, baseDir, options = {}) {
 		const moduleFilePath = path.resolve(baseDir, file.name);
 
 		
+		
 		let importUrl = `file://${moduleFilePath.replace(/\\/g, "/")}`;
+		const separator = importUrl.includes("?") ? "&" : "?";
+
+		
+		importUrl = `${importUrl}${separator}_t=${Date.now()}_${Math.random().toString(36).slice(2)}`;
+
+		
 		if (instance && instance.instanceId) {
-			const separator = importUrl.includes("?") ? "&" : "?";
-			importUrl = `${importUrl}${separator}slothlet_instance=${instance.instanceId}`;
+			const runtimeType = instance.config?.runtime || "async";
+			if (runtimeType === "live") {
+				importUrl = `${importUrl}&slothlet_instance=${instance.instanceId}`;
+			}
 		}
 
 		

package/dist/lib/helpers/resolve-from-caller.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/sanitize.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/utilities.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/modes/slothlet_eager.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/modes/slothlet_lazy.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.
@@ -345,6 +345,11 @@ function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth,
 				return pathParts.length > 0 ? pathParts.join(".") : undefined;
 			}
 			
+			if (prop === "__metadata" || prop === "__sourceFolder") {
+				
+				return Reflect.get(_t, prop);
+			}
+			
 			if (materialized) {
 				if (materialized && (typeof materialized === "object" || typeof materialized === "function")) return materialized[prop];
 				return undefined;
@@ -485,6 +490,10 @@ function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth,
 			if (prop === "__materialized") {
 				return { configurable: true, enumerable: false, writable: true, value: materialized };
 			}
+			
+			if (prop === "__metadata" || prop === "__sourceFolder") {
+				return Reflect.getOwnPropertyDescriptor(lazy_lazyTarget, prop);
+			}
 			if (prop === "prototype") {
 				
 				return Object.getOwnPropertyDescriptor(lazy_lazyTarget, "prototype");

package/dist/lib/runtime/runtime-asynclocalstorage.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,6 +21,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import util from "node:util";
 import { enableAlsForEventEmitters } from "@cldmv/slothlet/helpers/als-eventemitter";
+import { metadataAPI } from "@cldmv/slothlet/helpers/metadata-api";
 
 const als = new AsyncLocalStorage();
 
@@ -565,3 +566,6 @@ export const context = runtime_createLiveBinding("context");
 export const reference = runtime_createLiveBinding("reference");
 
 
+export { metadataAPI };
+
+

package/dist/lib/runtime/runtime-livebindings.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.
@@ -25,6 +25,7 @@ import {
 	setActiveInstance,
 	getCurrentActiveInstanceId
 } from "@cldmv/slothlet/helpers/instance-manager";
+import { metadataAPI } from "@cldmv/slothlet/helpers/metadata-api";
 
 
 export const requestALS = new AsyncLocalStorage();
@@ -433,3 +434,6 @@ export const contextManager = {
 	set: setContext,
 	runWithCtx
 };
+
+
+export { metadataAPI };

package/dist/lib/runtime/runtime.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.
@@ -225,3 +225,14 @@ export const instanceId = (() => {
 })();
 
 export const sharedALS = getCurrentRuntime().sharedALS;
+
+
+export const metadataAPI = new Proxy(
+	{},
+	{
+		get(_, prop) {
+			const runtime = getCurrentRuntime();
+			return runtime.metadataAPI[prop];
+		}
+	}
+);

package/dist/slothlet.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.
@@ -75,6 +75,11 @@ let DEBUG = process.argv.includes("--slothletdebug")
 		: false;
 
 
+if (DEBUG && !process.env.SLOTHLET_DEBUG) {
+	process.env.SLOTHLET_DEBUG = "1";
+}
+
+
 export const self = {};
 
 
@@ -636,6 +641,17 @@ const slothletObject = {
 		}
 
 		
+		const instanceIdDesc = Object.getOwnPropertyDescriptor(boundApi, "instanceId");
+		if (!instanceIdDesc || instanceIdDesc.configurable) {
+			Object.defineProperty(boundApi, "instanceId", {
+				value: this.instanceId,
+				writable: false,
+				configurable: true,
+				enumerable: false
+			});
+		}
+
+		
 		const scopeDesc = Object.getOwnPropertyDescriptor(boundApi, "scope");
 		if (!scopeDesc || scopeDesc.configurable) {
 			Object.defineProperty(boundApi, "scope", {
@@ -678,8 +694,8 @@ const slothletObject = {
 	},
 
 	
-	async addApi(apiPath, folderPath) {
-		return addApiFromFolder({ apiPath, folderPath, instance: this });
+	async addApi(apiPath, folderPath, metadata = {}) {
+		return addApiFromFolder({ apiPath, folderPath, instance: this, metadata });
 	},
 
 	

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/slothlet",
-	"version": "2.9.0",
+	"version": "2.10.0",
 	"moduleVersions": {
 		"lazy": "1.3.1",
 		"eager": "1.3.1",

package/types/dist/lib/helpers/api_builder/add_api.d.mts

@@ -7,6 +7,7 @@
  * @param {string} options.apiPath - Dot-notation path where modules will be added
  * @param {string} options.folderPath - Path to folder containing modules to load
  * @param {object} options.instance - Slothlet instance with api, boundapi, config, modes, etc.
+ * @param {object} [options.metadata={}] - Metadata to attach to all loaded functions
  * @returns {Promise<void>}
  * @throws {Error} If API not loaded, invalid parameters, folder does not exist, or merge conflicts
  * @package
@@ -51,10 +52,25 @@
  *   folderPath: "./services/stripe",
  *   instance: slothletInstance
  * });
+ *
+ * @example
+ * // Add modules with metadata
+ * await addApiFromFolder({
+ *   apiPath: "plugins",
+ *   folderPath: "./untrusted-plugins",
+ *   instance: slothletInstance,
+ *   metadata: {
+ *     trusted: false,
+ *     permissions: ["read"],
+ *     version: "1.0.0",
+ *     author: "external"
+ *   }
+ * });
  */
-export function addApiFromFolder({ apiPath, folderPath, instance }: {
+export function addApiFromFolder({ apiPath, folderPath, instance, metadata }: {
     apiPath: string;
     folderPath: string;
     instance: object;
+    metadata?: object;
 }): Promise<void>;
 //# sourceMappingURL=add_api.d.mts.map

package/types/dist/lib/helpers/api_builder/add_api.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"add_api.d.mts","sourceRoot":"","sources":["../../../../../dist/lib/helpers/api_builder/add_api.mjs"],"names":[],"mappings":"AAiDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,oEAhDG;IAAwB,OAAO,EAAvB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,QAAQ,EAAxB,MAAM;CACd,GAAU,OAAO,CAAC,IAAI,CAAC,CAgQzB"}
+{"version":3,"file":"add_api.d.mts","sourceRoot":"","sources":["../../../../../dist/lib/helpers/api_builder/add_api.mjs"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,8EA/DG;IAAwB,OAAO,EAAvB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,QAAQ,EAAxB,MAAM;IACW,QAAQ,GAAzB,MAAM;CACd,GAAU,OAAO,CAAC,IAAI,CAAC,CAoUzB"}

package/types/dist/lib/helpers/api_builder/analysis.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis.d.mts","sourceRoot":"","sources":["../../../../../dist/lib/helpers/api_builder/analysis.mjs"],"names":[],"mappings":"AA0CA;;;;;;;;GAQG;AACH,0CAHW,GAAC,GACC,OAAO,CAcnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,0CAvBW,MAAM,YAEd;IAA0B,KAAK,GAAvB,OAAO;IACU,QAAQ,GAAzB,MAAM;CACd,GAAU,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9B,iBAAiB,EAAE,UAAU,GAAC,QAAQ,GAAC,IAAI,CAAC;IAC5C,oBAAoB,EAAE,OAAO,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAC,CAkGJ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,oDAZW,MAAM,YAEd;IAAyB,QAAQ,GAAzB,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU,MAAM,CA4NlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wDA1BW,MAAM,YAEd;IAAwB,QAAQ,EAAxB,MAAM;IACW,YAAY,GAA7B,MAAM;IACW,QAAQ,GAAzB,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,aAAa,GAAC,YAAY,GAAC,OAAO,CAAC;IACvD,eAAe,EAAE,MAAM,CAAA;CACxB,CAAC,CAkEJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,2DA1BW,MAAM,YAEd;IAAwB,QAAQ,EAAxB,MAAM;IACW,YAAY,GAA7B,MAAM;IACW,QAAQ,GAAzB,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU,OAAO,CAAC;IAChB,kBAAkB,EAAE,aAAa,GAAC,YAAY,GAAC,OAAO,CAAC;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gBAAgB,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,OAAO,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,GAAG,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACnH,cAAc,EAAE,KAAK,CAAC;QAAC,QAAQ,EAAE,OAAO,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAC3E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yBAAyB,EAAE;QAAC,aAAa,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAA;CACxE,CAAC,CAmHJ"}
+{"version":3,"file":"analysis.d.mts","sourceRoot":"","sources":["../../../../../dist/lib/helpers/api_builder/analysis.mjs"],"names":[],"mappings":"AA0CA;;;;;;;;GAQG;AACH,0CAHW,GAAC,GACC,OAAO,CAcnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,0CAvBW,MAAM,YAEd;IAA0B,KAAK,GAAvB,OAAO;IACU,QAAQ,GAAzB,MAAM;CACd,GAAU,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9B,iBAAiB,EAAE,UAAU,GAAC,QAAQ,GAAC,IAAI,CAAC;IAC5C,oBAAoB,EAAE,OAAO,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAC,CA4GJ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,oDAZW,MAAM,YAEd;IAAyB,QAAQ,GAAzB,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU,MAAM,CA4NlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wDA1BW,MAAM,YAEd;IAAwB,QAAQ,EAAxB,MAAM;IACW,YAAY,GAA7B,MAAM;IACW,QAAQ,GAAzB,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,aAAa,GAAC,YAAY,GAAC,OAAO,CAAC;IACvD,eAAe,EAAE,MAAM,CAAA;CACxB,CAAC,CAkEJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,2DA1BW,MAAM,YAEd;IAAwB,QAAQ,EAAxB,MAAM;IACW,YAAY,GAA7B,MAAM;IACW,QAAQ,GAAzB,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU,OAAO,CAAC;IAChB,kBAAkB,EAAE,aAAa,GAAC,YAAY,GAAC,OAAO,CAAC;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gBAAgB,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,OAAO,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,GAAG,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACnH,cAAc,EAAE,KAAK,CAAC;QAAC,QAAQ,EAAE,OAAO,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAC3E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yBAAyB,EAAE;QAAC,aAAa,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAA;CACxE,CAAC,CAmHJ"}

package/types/dist/lib/helpers/api_builder/metadata.d.mts

@@ -0,0 +1,99 @@
+/**
+ *	@Project: @cldmv/slothlet
+ *	@Filename: /src/lib/helpers/api_builder/metadata.mjs
+ *	@Date: 2025-12-31 00:00:00 -08:00
+ *	@Author: Nate Hyson <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Nate Hyson <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2025-12-31 22:30:16 -08:00 (1767249016)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2025 Catalyzed Motivation Inc. All rights reserved.
+ */
+/**
+ * @fileoverview Metadata management utilities for API functions.
+ * @module @cldmv/slothlet/lib/helpers/api_builder/metadata
+ * @memberof module:@cldmv/slothlet.lib.helpers.api_builder
+ * @internal
+ * @private
+ *
+ * @description
+ * Provides utilities for tagging functions with immutable metadata, cleaning stale metadata
+ * from cached modules, and creating immutable metadata objects with deep freezing.
+ *
+ * Key Features:
+ * - Immutable metadata with Proxy-based enforcement
+ * - Deep freezing of nested objects and arrays
+ * - Recursive traversal for tagging/cleaning object trees
+ * - CommonJS cache-aware metadata cleanup
+ */
+/**
+ * Creates an immutable-but-extensible metadata proxy object.
+ *
+ * @function createImmutableMetadata
+ * @param {object} initial - Initial metadata properties
+ * @returns {object} Object with immutable existing properties but allows adding new ones
+ *
+ * @description
+ * Creates an object that enforces immutability of existing properties while allowing
+ * new properties to be added. This prevents tampering with security-critical metadata
+ * while allowing runtime extension of metadata for additional context.
+ *
+ * Security features:
+ * - Existing properties cannot be modified (non-writable, non-configurable after first set)
+ * - Properties cannot be deleted
+ * - New properties can be added, which then become immutable
+ *
+ * @example
+ * const meta = createImmutableMetadata({ trusted: true, version: "1.0" });
+ * meta.author = "Alice"; // OK - new property
+ * meta.author = "Bob"; // FAIL - cannot modify after setting
+ * meta.trusted = false;  // FAIL - cannot modify existing property
+ * delete meta.version;   // FAIL - cannot delete properties
+ */
+export function createImmutableMetadata(initial?: object): object;
+/**
+ * Removes metadata from all functions in an object tree.
+ *
+ * @function cleanMetadata
+ * @param {object|Function} obj - Object or function to clean
+ * @param {WeakSet} [visited] - Visited objects tracker to prevent infinite recursion
+ * @returns {void}
+ *
+ * @description
+ * Traverses an object/function tree and removes __metadata and __sourceFolder properties.
+ * This is needed when reloading CommonJS modules that cache function object references.
+ */
+export function cleanMetadata(obj: object | Function, visited?: WeakSet<any>): void;
+/**
+ * Recursively tags all functions in an object tree with metadata.
+ *
+ * @function tagLoadedFunctions
+ * @param {object|Function} obj - Object or function to tag
+ * @param {object} metadata - Metadata object to attach
+ * @param {string} baseDir - Base directory path for relative file tracking
+ * @param {WeakSet} [visited] - Visited objects tracker to prevent infinite recursion
+ * @returns {void}
+ *
+ * @description
+ * Traverses an object/function tree and attaches immutable metadata to all functions.
+ * Also tracks source file information (__sourceFile, __sourceLine) for stack trace
+ * matching. Only tags functions that don't already have metadata (non-overwriting).
+ *
+ * Attached properties:
+ * - __metadata: Immutable metadata proxy with all user-provided metadata
+ * - __sourceFolder: Absolute path to the folder the module was loaded from
+ * - __sourceFile: Absolute file path (for stack trace matching)
+ * - __sourceLine: Line number where function is defined (for stack trace matching)
+ *
+ * @example
+ * const modules = { math: { add: (a, b) => a + b } };
+ * tagLoadedFunctions(modules, {
+ *     trusted: true,
+ *     version: "1.0.0",
+ *     author: "Alice"
+ * }, "/path/to/plugins");
+ * // Now modules.math.add.__metadata.trusted === true
+ */
+export function tagLoadedFunctions(obj: object | Function, metadata: object, baseDir: string, visited?: WeakSet<any>): void;
+//# sourceMappingURL=metadata.d.mts.map

package/types/dist/lib/helpers/api_builder/metadata.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.mts","sourceRoot":"","sources":["../../../../../dist/lib/helpers/api_builder/metadata.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,kDApBW,MAAM,GACJ,MAAM,CAmJlB;AAED;;;;;;;;;;;GAWG;AACH,mCARW,MAAM,WAAS,2BAEb,IAAI,CAyChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wCA1BW,MAAM,WAAS,YACf,MAAM,WACN,MAAM,2BAEJ,IAAI,CA+EhB"}