@cldmv/slothlet 3.8.0 → 3.9.1

package/dist/lib/helpers/module-discovery.mjs

@@ -14,4 +14,4 @@
 	limitations under the License.
 */
 
-import{promises as fs}from"node:fs";import path from"node:path";import{SlothletError}from"@cldmv/slothlet/errors";import{validateModuleManifest}from"@cldmv/slothlet/helpers/module-manifest-validator";const DEFAULT_MANIFEST_FILE="slothlet.module.json";const UPWARD_WALK_CAP=20;async function discoverModules(options={}){const scanRoots=await resolveScanRoots(options.scanRoot);const manifestSource=parseManifestSource(options.manifest);const fieldSchema=options.schema??{};const filterFn=options.filter;const prefixes=normalizePrefixes(options.prefix);const candidates=[];for(const root of scanRoots){const mode=await detectScanMode(root);if(mode==="npm"){candidates.push(...await enumerateNpmPackages(root,prefixes))}else{candidates.push(...await enumerateFolderModules(root,prefixes))}}const results=[];const seenRealPaths=new Set;const realPathByNameVersion=new Map;for(const candidate of candidates){let realPath;try{realPath=await fs.realpath(candidate.path)}catch{continue}if(seenRealPaths.has(realPath))continue;seenRealPaths.add(realPath);const pkgJsonPath=path.join(realPath,"package.json");const pkg=await readJsonOrNull(pkgJsonPath);if(!pkg||typeof pkg.name!=="string"||typeof pkg.version!=="string"){continue}const manifestPath=path.join(realPath,manifestSource.file);const manifestRaw=await loadManifestRaw(manifestPath,manifestSource,pkg.name);if(manifestRaw===void 0)continue;const remapped=applySchemaRemap(manifestRaw,fieldSchema);if(manifestSource.isOverride&&remapped.schemaVersion===void 0){remapped.schemaVersion=1}const normalized=validateModuleManifest(remapped,{packageName:pkg.name,packageVersion:pkg.version,packageDescription:pkg.description,packageRoot:realPath,manifestPath});if(typeof filterFn==="function"&&!filterFn(normalized,pkg.name)){continue}const nameVersionKey=`${pkg.name}@${pkg.version}`;if(realPathByNameVersion.has(nameVersionKey)){const otherRealPath=realPathByNameVersion.get(nameVersionKey);if(otherRealPath!==realPath){throw new SlothletError("MODULE_DUPLICATE_NAME_VERSION_MISMATCH",{packageName:pkg.name,version:pkg.version,paths:[otherRealPath,realPath].join(", ")},null,{validationError:true})}}else{realPathByNameVersion.set(nameVersionKey,realPath)}const apiDirAbs=path.resolve(realPath,normalized.apiDir);results.push(Object.freeze({packageName:pkg.name,packageRoot:realPath,mountPath:Object.freeze([...normalized.mountPath]),apiDir:apiDirAbs,manifest:deepFreeze(normalized)}))}return results}async function resolveScanRoots(opt){if(opt===void 0){return[await defaultScanRoot()]}if(typeof opt==="string"){return[path.resolve(opt)]}if(Array.isArray(opt)){return opt.map(p=>path.resolve(p))}throw new SlothletError("INVALID_ARGUMENT",{argument:"scanRoot",expected:"string or string[]",received:typeof opt},null,{validationError:true})}async function defaultScanRoot(){let current=process.cwd();for(let i=0;i<UPWARD_WALK_CAP;i++){try{const stat=await fs.stat(path.join(current,"node_modules"));if(stat.isDirectory())return current}catch{}const parent=path.dirname(current);if(parent===current)break;current=parent}return process.cwd()}async function detectScanMode(root){try{const stat=await fs.stat(path.join(root,"node_modules"));if(stat.isDirectory())return"npm"}catch{}return"folder"}async function enumerateNpmPackages(root,prefixes){const nodeModules=path.join(root,"node_modules");const out=[];let entries;try{entries=await fs.readdir(nodeModules,{withFileTypes:true})}catch{return out}for(const entry of entries){if(!entry.isDirectory()&&!entry.isSymbolicLink())continue;if(entry.name.startsWith("."))continue;if(entry.name.startsWith("@")){const scopeDir=path.join(nodeModules,entry.name);let scopedEntries;try{scopedEntries=await fs.readdir(scopeDir,{withFileTypes:true})}catch{continue}for(const scoped of scopedEntries){if(!scoped.isDirectory()&&!scoped.isSymbolicLink())continue;const fullName=`${entry.name}/${scoped.name}`;if(!matchesPrefix(fullName,prefixes))continue;out.push({path:path.join(scopeDir,scoped.name),packageName:fullName})}}else{if(!matchesPrefix(entry.name,prefixes))continue;out.push({path:path.join(nodeModules,entry.name),packageName:entry.name})}}return out}async function enumerateFolderModules(root,prefixes){const out=[];let entries;try{entries=await fs.readdir(root,{withFileTypes:true})}catch{return out}for(const entry of entries){if(!entry.isDirectory()&&!entry.isSymbolicLink())continue;if(entry.name.startsWith("."))continue;if(!matchesPrefix(entry.name,prefixes))continue;out.push({path:path.join(root,entry.name),packageName:entry.name})}return out}function normalizePrefixes(opt){if(opt===void 0)return null;if(typeof opt==="string")return[opt];if(Array.isArray(opt)){if(opt.length===0)return null;return opt.slice()}throw new SlothletError("INVALID_ARGUMENT",{argument:"prefix",expected:"string or string[]",received:typeof opt},null,{validationError:true})}function matchesPrefix(name,prefixes){if(!prefixes)return true;for(const p of prefixes){if(name.startsWith(p))return true}return false}function parseManifestSource(opt){if(opt===void 0){return{file:DEFAULT_MANIFEST_FILE,subkey:null,isOverride:false}}if(typeof opt!=="string"||opt.length===0){throw new SlothletError("INVALID_ARGUMENT",{argument:"manifest",expected:"string",received:typeof opt},null,{validationError:true})}const hashIdx=opt.indexOf("#");if(hashIdx===-1){return{file:opt,subkey:null,isOverride:opt!==DEFAULT_MANIFEST_FILE}}const file=opt.slice(0,hashIdx);const subkey=opt.slice(hashIdx+1);if(file.length===0||subkey.length===0){throw new SlothletError("INVALID_ARGUMENT",{argument:"manifest",expected:"<file>#<dotted.key> with both parts non-empty",received:opt},null,{validationError:true})}return{file,subkey,isOverride:true}}async function readJsonOrNull(filePath){let content;try{content=await fs.readFile(filePath,"utf8")}catch{return null}try{return JSON.parse(content)}catch{return null}}async function loadManifestRaw(manifestPath,source,packageName){let content;try{content=await fs.readFile(manifestPath,"utf8")}catch{return void 0}let parsed;try{parsed=JSON.parse(content)}catch(err){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`JSON parse error: ${err.message}`},err,{validationError:true})}if(source.subkey===null){return parsed}const parts=source.subkey.split(".");let cur=parsed;for(const part of parts){if(cur===null||typeof cur!=="object"||!(part in cur)){return void 0}cur=cur[part]}if(cur===null||typeof cur!=="object"||Array.isArray(cur)){return void 0}return cur}function applySchemaRemap(raw,schemaMap){if(!schemaMap||Object.keys(schemaMap).length===0){return raw}const out={...raw};for(const[canonical,legacy]of Object.entries(schemaMap)){if(legacy===canonical)continue;if(out[canonical]!==void 0)continue;if(legacy in out){out[canonical]=out[legacy];delete out[legacy]}}return out}function deepFreeze(obj){if(obj===null||typeof obj!=="object"||Object.isFrozen(obj))return obj;Object.freeze(obj);for(const key of Object.keys(obj)){const value=obj[key];if(value!==null&&typeof value==="object"){deepFreeze(value)}}return obj}export{discoverModules};
+import{SlothletError}from"@cldmv/slothlet/errors";import{validateModuleManifest}from"@cldmv/slothlet/helpers/module-manifest-validator";import{fsp,path}from"@cldmv/slothlet/helpers/platform";const DEFAULT_MANIFEST_FILE="slothlet.module.json";const UPWARD_WALK_CAP=20;async function discoverModules(options={}){const scanRoots=await resolveScanRoots(options.scanRoot);const manifestSource=parseManifestSource(options.manifest);const fieldSchema=options.schema??{};const filterFn=options.filter;const prefixes=normalizePrefixes(options.prefix);const candidates=[];for(const root of scanRoots){const mode=await detectScanMode(root);if(mode==="npm"){candidates.push(...await enumerateNpmPackages(root,prefixes))}else{candidates.push(...await enumerateFolderModules(root,prefixes))}}const results=[];const seenRealPaths=new Set;const realPathByNameVersion=new Map;for(const candidate of candidates){let realPath;try{realPath=await fsp.realpath(candidate.path)}catch{continue}if(seenRealPaths.has(realPath))continue;seenRealPaths.add(realPath);const pkgJsonPath=path.join(realPath,"package.json");const pkg=await readJsonOrNull(pkgJsonPath);if(!pkg||typeof pkg.name!=="string"||typeof pkg.version!=="string"){continue}const manifestPath=path.join(realPath,manifestSource.file);const manifestRaw=await loadManifestRaw(manifestPath,manifestSource,pkg.name);if(manifestRaw===void 0)continue;const remapped=applySchemaRemap(manifestRaw,fieldSchema);if(manifestSource.isOverride&&remapped.schemaVersion===void 0){remapped.schemaVersion=1}const normalized=validateModuleManifest(remapped,{packageName:pkg.name,packageVersion:pkg.version,packageDescription:pkg.description,packageRoot:realPath,manifestPath});if(typeof filterFn==="function"&&!filterFn(normalized,pkg.name)){continue}const nameVersionKey=`${pkg.name}@${pkg.version}`;if(realPathByNameVersion.has(nameVersionKey)){const otherRealPath=realPathByNameVersion.get(nameVersionKey);if(otherRealPath!==realPath){throw new SlothletError("MODULE_DUPLICATE_NAME_VERSION_MISMATCH",{packageName:pkg.name,version:pkg.version,paths:[otherRealPath,realPath].join(", ")},null,{validationError:true})}}else{realPathByNameVersion.set(nameVersionKey,realPath)}const apiDirAbs=path.resolve(realPath,normalized.apiDir);results.push(Object.freeze({packageName:pkg.name,packageRoot:realPath,mountPath:Object.freeze([...normalized.mountPath]),apiDir:apiDirAbs,manifest:deepFreeze(normalized)}))}return results}async function resolveScanRoots(opt){if(opt===void 0){return[await defaultScanRoot()]}if(typeof opt==="string"){return[path.resolve(opt)]}if(Array.isArray(opt)){return opt.map(p=>path.resolve(p))}throw new SlothletError("INVALID_ARGUMENT",{argument:"scanRoot",expected:"string or string[]",received:typeof opt},null,{validationError:true})}async function defaultScanRoot(){let current=process.cwd();for(let i=0;i<UPWARD_WALK_CAP;i++){try{const stat=await fsp.stat(path.join(current,"node_modules"));if(stat.isDirectory())return current}catch{}const parent=path.dirname(current);if(parent===current)break;current=parent}return process.cwd()}async function detectScanMode(root){try{const stat=await fsp.stat(path.join(root,"node_modules"));if(stat.isDirectory())return"npm"}catch{}return"folder"}async function enumerateNpmPackages(root,prefixes){const nodeModules=path.join(root,"node_modules");const out=[];let entries;try{entries=await fsp.readdir(nodeModules,{withFileTypes:true})}catch{return out}for(const entry of entries){if(!entry.isDirectory()&&!entry.isSymbolicLink())continue;if(entry.name.startsWith("."))continue;if(entry.name.startsWith("@")){const scopeDir=path.join(nodeModules,entry.name);let scopedEntries;try{scopedEntries=await fsp.readdir(scopeDir,{withFileTypes:true})}catch{continue}for(const scoped of scopedEntries){if(!scoped.isDirectory()&&!scoped.isSymbolicLink())continue;const fullName=`${entry.name}/${scoped.name}`;if(!matchesPrefix(fullName,prefixes))continue;out.push({path:path.join(scopeDir,scoped.name),packageName:fullName})}}else{if(!matchesPrefix(entry.name,prefixes))continue;out.push({path:path.join(nodeModules,entry.name),packageName:entry.name})}}return out}async function enumerateFolderModules(root,prefixes){const out=[];let entries;try{entries=await fsp.readdir(root,{withFileTypes:true})}catch{return out}for(const entry of entries){if(!entry.isDirectory()&&!entry.isSymbolicLink())continue;if(entry.name.startsWith("."))continue;if(!matchesPrefix(entry.name,prefixes))continue;out.push({path:path.join(root,entry.name),packageName:entry.name})}return out}function normalizePrefixes(opt){if(opt===void 0)return null;if(typeof opt==="string")return[opt];if(Array.isArray(opt)){if(opt.length===0)return null;return opt.slice()}throw new SlothletError("INVALID_ARGUMENT",{argument:"prefix",expected:"string or string[]",received:typeof opt},null,{validationError:true})}function matchesPrefix(name,prefixes){if(!prefixes)return true;for(const p of prefixes){if(name.startsWith(p))return true}return false}function parseManifestSource(opt){if(opt===void 0){return{file:DEFAULT_MANIFEST_FILE,subkey:null,isOverride:false}}if(typeof opt!=="string"||opt.length===0){throw new SlothletError("INVALID_ARGUMENT",{argument:"manifest",expected:"string",received:typeof opt},null,{validationError:true})}const hashIdx=opt.indexOf("#");if(hashIdx===-1){return{file:opt,subkey:null,isOverride:opt!==DEFAULT_MANIFEST_FILE}}const file=opt.slice(0,hashIdx);const subkey=opt.slice(hashIdx+1);if(file.length===0||subkey.length===0){throw new SlothletError("INVALID_ARGUMENT",{argument:"manifest",expected:"<file>#<dotted.key> with both parts non-empty",received:opt},null,{validationError:true})}return{file,subkey,isOverride:true}}async function readJsonOrNull(filePath){let content;try{content=await fsp.readFile(filePath,"utf8")}catch{return null}try{return JSON.parse(content)}catch{return null}}async function loadManifestRaw(manifestPath,source,packageName){let content;try{content=await fsp.readFile(manifestPath,"utf8")}catch{return void 0}let parsed;try{parsed=JSON.parse(content)}catch(err){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`JSON parse error: ${err.message}`},err,{validationError:true})}if(source.subkey===null){return parsed}const parts=source.subkey.split(".");let cur=parsed;for(const part of parts){if(cur===null||typeof cur!=="object"||!(part in cur)){return void 0}cur=cur[part]}if(cur===null||typeof cur!=="object"||Array.isArray(cur)){return void 0}return cur}function applySchemaRemap(raw,schemaMap){if(!schemaMap||Object.keys(schemaMap).length===0){return raw}const out={...raw};for(const[canonical,legacy]of Object.entries(schemaMap)){if(legacy===canonical)continue;if(out[canonical]!==void 0)continue;if(legacy in out){out[canonical]=out[legacy];delete out[legacy]}}return out}function deepFreeze(obj){if(obj===null||typeof obj!=="object"||Object.isFrozen(obj))return obj;Object.freeze(obj);for(const key of Object.keys(obj)){const value=obj[key];if(value!==null&&typeof value==="object"){deepFreeze(value)}}return obj}export{discoverModules};

package/dist/lib/helpers/module-manifest-validator.mjs

@@ -14,4 +14,4 @@
 	limitations under the License.
 */
 
-import path from"node:path";import{SlothletError}from"@cldmv/slothlet/errors";const RESERVED_MOUNTPATH_ROOTS=Object.freeze(new Set(["slothlet","shutdown","destroy"]));const ALLOWED_TOP_LEVEL_FIELDS=Object.freeze(new Set(["schemaVersion","name","version","description","mountPath","apiDir","kind","priority","dependencies","permissions","metadata"]));const PERMISSION_EFFECT_VALUES=Object.freeze(new Set(["allow","deny"]));function validateModuleManifest(manifest,packageContext){if(!manifest||typeof manifest!=="object"||Array.isArray(manifest)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName:packageContext?.packageName??"<unknown>",manifestPath:packageContext?.manifestPath??"<unknown>",reason:"manifest must be a JSON object"},null,{validationError:true})}const{packageName,packageVersion,packageDescription,packageRoot,manifestPath}=packageContext;for(const key of Object.keys(manifest)){if(!ALLOWED_TOP_LEVEL_FIELDS.has(key)){throw new SlothletError("MODULE_MANIFEST_UNKNOWN_FIELD",{packageName,manifestPath,field:key},null,{validationError:true})}}if(manifest.schemaVersion===void 0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"missing required field 'schemaVersion'"},null,{validationError:true})}if(manifest.schemaVersion!==1){throw new SlothletError("MODULE_VERSION_UNSUPPORTED",{packageName,schemaVersion:String(manifest.schemaVersion)},null,{validationError:true})}if(manifest.mountPath===void 0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"missing required field 'mountPath'"},null,{validationError:true})}const mountPathSegments=normalizeMountPath(manifest.mountPath,packageName,manifestPath);if(RESERVED_MOUNTPATH_ROOTS.has(mountPathSegments[0])){throw new SlothletError("MODULE_RESERVED_MOUNTPATH",{packageName,mountPathRoot:mountPathSegments[0],mountPath:mountPathSegments.join(".")},null,{validationError:true})}if(manifest.apiDir===void 0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"missing required field 'apiDir'"},null,{validationError:true})}if(typeof manifest.apiDir!=="string"||manifest.apiDir.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'apiDir' must be a non-empty string"},null,{validationError:true})}validateApiDirContainment(manifest.apiDir,packageRoot,packageName);if(manifest.name!==void 0){if(typeof manifest.name!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'name' must be a string"},null,{validationError:true})}if(manifest.name!==packageName){throw new SlothletError("MODULE_MANIFEST_NAME_MISMATCH",{packageName,manifestName:manifest.name},null,{validationError:true})}}if(manifest.version!==void 0){if(typeof manifest.version!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'version' must be a string"},null,{validationError:true})}if(manifest.version!==packageVersion){throw new SlothletError("MODULE_MANIFEST_VERSION_MISMATCH",{packageName,manifestVersion:manifest.version,packageVersion},null,{validationError:true})}}if(manifest.description!==void 0&&typeof manifest.description!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'description' must be a string"},null,{validationError:true})}if(manifest.kind!==void 0&&typeof manifest.kind!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'kind' must be a string"},null,{validationError:true})}if(manifest.priority!==void 0&&(typeof manifest.priority!=="number"||!Number.isFinite(manifest.priority))){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'priority' must be a finite number"},null,{validationError:true})}if(manifest.dependencies!==void 0){if(typeof manifest.dependencies!=="object"||manifest.dependencies===null||Array.isArray(manifest.dependencies)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'dependencies' must be a plain object"},null,{validationError:true})}for(const[depName,depValue]of Object.entries(manifest.dependencies)){if(typeof depValue!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`dependency '${depName}' must be a string version range`},null,{validationError:true})}}}if(manifest.permissions!==void 0){validatePermissions(manifest.permissions,packageName,manifestPath)}if(manifest.metadata!==void 0){if(typeof manifest.metadata!=="object"||manifest.metadata===null||Array.isArray(manifest.metadata)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'metadata' must be a plain object"},null,{validationError:true})}}return{schemaVersion:1,name:packageName,version:packageVersion,description:manifest.description??packageDescription,mountPath:mountPathSegments,apiDir:manifest.apiDir,kind:manifest.kind,priority:manifest.priority??0,dependencies:manifest.dependencies,permissions:manifest.permissions,metadata:manifest.metadata}}function normalizeMountPath(mountPath,packageName,manifestPath){if(typeof mountPath==="string"){if(mountPath.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'mountPath' must be a non-empty string or non-empty array of non-empty strings"},null,{validationError:true})}return mountPath.split(".")}if(Array.isArray(mountPath)){if(mountPath.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'mountPath' must be a non-empty string or non-empty array of non-empty strings"},null,{validationError:true})}for(const segment of mountPath){if(typeof segment!=="string"||segment.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'mountPath' array entries must all be non-empty strings"},null,{validationError:true})}}return mountPath.slice()}throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'mountPath' must be a non-empty string or non-empty array of non-empty strings"},null,{validationError:true})}function validateApiDirContainment(apiDir,packageRoot,packageName){const resolved=path.resolve(packageRoot,apiDir);const rootWithSep=packageRoot.endsWith(path.sep)?packageRoot:packageRoot+path.sep;if(resolved!==packageRoot&&!resolved.startsWith(rootWithSep)){throw new SlothletError("MODULE_PATH_TRAVERSAL",{packageName,apiDir,resolvedPath:resolved,packageRoot},null,{validationError:true})}}function validatePermissions(permissions,packageName,manifestPath){if(!Array.isArray(permissions)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'permissions' must be an array of rule objects"},null,{validationError:true})}for(let i=0;i<permissions.length;i++){const rule=permissions[i];if(!rule||typeof rule!=="object"||Array.isArray(rule)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`permissions[${i}] must be a rule object`},null,{validationError:true})}if(typeof rule.caller!=="string"||rule.caller.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`permissions[${i}].caller must be a non-empty string`},null,{validationError:true})}if(typeof rule.target!=="string"||rule.target.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`permissions[${i}].target must be a non-empty string`},null,{validationError:true})}if(!PERMISSION_EFFECT_VALUES.has(rule.effect)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`permissions[${i}].effect must be "allow" or "deny"`},null,{validationError:true})}}}export{validateModuleManifest};
+import{SlothletError}from"@cldmv/slothlet/errors";import{path}from"@cldmv/slothlet/helpers/platform";const RESERVED_MOUNTPATH_ROOTS=Object.freeze(new Set(["slothlet","shutdown","destroy"]));const ALLOWED_TOP_LEVEL_FIELDS=Object.freeze(new Set(["schemaVersion","name","version","description","mountPath","apiDir","kind","priority","dependencies","permissions","metadata"]));const PERMISSION_EFFECT_VALUES=Object.freeze(new Set(["allow","deny"]));function validateModuleManifest(manifest,packageContext){if(!manifest||typeof manifest!=="object"||Array.isArray(manifest)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName:packageContext?.packageName??"<unknown>",manifestPath:packageContext?.manifestPath??"<unknown>",reason:"manifest must be a JSON object"},null,{validationError:true})}const{packageName,packageVersion,packageDescription,packageRoot,manifestPath}=packageContext;for(const key of Object.keys(manifest)){if(!ALLOWED_TOP_LEVEL_FIELDS.has(key)){throw new SlothletError("MODULE_MANIFEST_UNKNOWN_FIELD",{packageName,manifestPath,field:key},null,{validationError:true})}}if(manifest.schemaVersion===void 0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"missing required field 'schemaVersion'"},null,{validationError:true})}if(manifest.schemaVersion!==1){throw new SlothletError("MODULE_VERSION_UNSUPPORTED",{packageName,schemaVersion:String(manifest.schemaVersion)},null,{validationError:true})}if(manifest.mountPath===void 0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"missing required field 'mountPath'"},null,{validationError:true})}const mountPathSegments=normalizeMountPath(manifest.mountPath,packageName,manifestPath);if(RESERVED_MOUNTPATH_ROOTS.has(mountPathSegments[0])){throw new SlothletError("MODULE_RESERVED_MOUNTPATH",{packageName,mountPathRoot:mountPathSegments[0],mountPath:mountPathSegments.join(".")},null,{validationError:true})}if(manifest.apiDir===void 0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"missing required field 'apiDir'"},null,{validationError:true})}if(typeof manifest.apiDir!=="string"||manifest.apiDir.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'apiDir' must be a non-empty string"},null,{validationError:true})}validateApiDirContainment(manifest.apiDir,packageRoot,packageName);if(manifest.name!==void 0){if(typeof manifest.name!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'name' must be a string"},null,{validationError:true})}if(manifest.name!==packageName){throw new SlothletError("MODULE_MANIFEST_NAME_MISMATCH",{packageName,manifestName:manifest.name},null,{validationError:true})}}if(manifest.version!==void 0){if(typeof manifest.version!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'version' must be a string"},null,{validationError:true})}if(manifest.version!==packageVersion){throw new SlothletError("MODULE_MANIFEST_VERSION_MISMATCH",{packageName,manifestVersion:manifest.version,packageVersion},null,{validationError:true})}}if(manifest.description!==void 0&&typeof manifest.description!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'description' must be a string"},null,{validationError:true})}if(manifest.kind!==void 0&&typeof manifest.kind!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'kind' must be a string"},null,{validationError:true})}if(manifest.priority!==void 0&&(typeof manifest.priority!=="number"||!Number.isFinite(manifest.priority))){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'priority' must be a finite number"},null,{validationError:true})}if(manifest.dependencies!==void 0){if(typeof manifest.dependencies!=="object"||manifest.dependencies===null||Array.isArray(manifest.dependencies)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'dependencies' must be a plain object"},null,{validationError:true})}for(const[depName,depValue]of Object.entries(manifest.dependencies)){if(typeof depValue!=="string"){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`dependency '${depName}' must be a string version range`},null,{validationError:true})}}}if(manifest.permissions!==void 0){validatePermissions(manifest.permissions,packageName,manifestPath)}if(manifest.metadata!==void 0){if(typeof manifest.metadata!=="object"||manifest.metadata===null||Array.isArray(manifest.metadata)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'metadata' must be a plain object"},null,{validationError:true})}}return{schemaVersion:1,name:packageName,version:packageVersion,description:manifest.description??packageDescription,mountPath:mountPathSegments,apiDir:manifest.apiDir,kind:manifest.kind,priority:manifest.priority??0,dependencies:manifest.dependencies,permissions:manifest.permissions,metadata:manifest.metadata}}function normalizeMountPath(mountPath,packageName,manifestPath){if(typeof mountPath==="string"){if(mountPath.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'mountPath' must be a non-empty string or non-empty array of non-empty strings"},null,{validationError:true})}return mountPath.split(".")}if(Array.isArray(mountPath)){if(mountPath.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'mountPath' must be a non-empty string or non-empty array of non-empty strings"},null,{validationError:true})}for(const segment of mountPath){if(typeof segment!=="string"||segment.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'mountPath' array entries must all be non-empty strings"},null,{validationError:true})}}return mountPath.slice()}throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'mountPath' must be a non-empty string or non-empty array of non-empty strings"},null,{validationError:true})}function validateApiDirContainment(apiDir,packageRoot,packageName){const resolved=path.resolve(packageRoot,apiDir);const rootWithSep=packageRoot.endsWith(path.sep)?packageRoot:packageRoot+path.sep;if(resolved!==packageRoot&&!resolved.startsWith(rootWithSep)){throw new SlothletError("MODULE_PATH_TRAVERSAL",{packageName,apiDir,resolvedPath:resolved,packageRoot},null,{validationError:true})}}function validatePermissions(permissions,packageName,manifestPath){if(!Array.isArray(permissions)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:"field 'permissions' must be an array of rule objects"},null,{validationError:true})}for(let i=0;i<permissions.length;i++){const rule=permissions[i];if(!rule||typeof rule!=="object"||Array.isArray(rule)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`permissions[${i}] must be a rule object`},null,{validationError:true})}if(typeof rule.caller!=="string"||rule.caller.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`permissions[${i}].caller must be a non-empty string`},null,{validationError:true})}if(typeof rule.target!=="string"||rule.target.length===0){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`permissions[${i}].target must be a non-empty string`},null,{validationError:true})}if(!PERMISSION_EFFECT_VALUES.has(rule.effect)){throw new SlothletError("MODULE_MANIFEST_INVALID",{packageName,manifestPath,reason:`permissions[${i}].effect must be "allow" or "deny"`},null,{validationError:true})}}}export{validateModuleManifest};

package/dist/lib/helpers/platform.mjs

@@ -0,0 +1,17 @@
+/*
+	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.
+*/
+
+const isNode=typeof process!=="undefined"&&Boolean(process?.versions?.node);let fs=null;let fsp=null;let path=null;let url=null;let util=null;let EventEmitter=null;let AsyncLocalStorage=null;let AsyncResource=null;let createRequire=null;if(isNode){const[fsMod,fspMod,pathMod,urlMod,utilMod,eventsMod,asyncHooksMod,moduleMod]=await Promise.all([import("node:fs"),import("node:fs/promises"),import("node:path"),import("node:url"),import("node:util"),import("node:events"),import("node:async_hooks"),import("node:module")]);fs=fsMod;fsp=fspMod;path=pathMod;url=urlMod;util=utilMod;({EventEmitter}=eventsMod);({AsyncLocalStorage,AsyncResource}=asyncHooksMod);({createRequire}=moduleMod)}else{util={inspect:Object.assign(value=>value,{custom:Symbol.for("nodejs.util.inspect.custom")}),types:{isProxy:()=>false}}}function loadJson(ref){if(!isNode){return import(ref,{with:{type:"json"}}).then(mod=>mod.default??null).catch(()=>null)}try{return JSON.parse(fs.readFileSync(ref,"utf-8"))}catch{return null}}export{AsyncLocalStorage,AsyncResource,EventEmitter,createRequire,fs,fsp,isNode,loadJson,path,url,util};

package/dist/lib/helpers/resolve-from-caller.mjs

@@ -14,4 +14,4 @@
 	limitations under the License.
 */
 
-import fs from"node:fs";import path from"node:path";import{fileURLToPath}from"node:url";import{ComponentBase}from"@cldmv/slothlet/factories/component-base";const __filename=fileURLToPath(import.meta.url);const __dirname=path.dirname(__filename);const SLOTHLET_LIB_ROOT=path.resolve(__dirname,"../..");const SLOTHLET_PKG_ROOT=path.normalize(path.resolve(__dirname,"../../.."));class Resolver extends ComponentBase{static slothletProperty="resolver";getStack(skipFn){const orig=Error.prepareStackTrace;try{Error.prepareStackTrace=(_,s)=>s;const e=new Error("Stack trace");if(skipFn)Error.captureStackTrace(e,skipFn);return e.stack}finally{Error.prepareStackTrace=orig}}#getStack(){const originalPrepare=Error.prepareStackTrace;Error.prepareStackTrace=(___,stack2)=>stack2;const stack=new Error().stack;Error.prepareStackTrace=originalPrepare;return stack}toFsPath(v){if(!v)return null;const str=String(v);return str.startsWith("file://")?fileURLToPath(str):str}#isSlothletInternal(filePath){const normalized=path.normalize(filePath);const normalizedLibRoot=path.normalize(SLOTHLET_LIB_ROOT);if(normalized.startsWith(normalizedLibRoot)){return true}const basename=path.basename(normalized);if(basename==="index.mjs"||basename==="index.cjs"){if(path.dirname(normalized)===SLOTHLET_PKG_ROOT)return true}return false}#findCallerBase(){const stack=this.#getStack();const files=stack.map(s=>this.toFsPath(s.getFileName())).filter(Boolean);const slothletIndex=files.findIndex(f=>path.basename(f).toLowerCase()==="slothlet.mjs");if(slothletIndex===-1){for(const file of files){if(!this.#isSlothletInternal(file)){return file}}return null}for(let i=slothletIndex+1;i<files.length;i++){const file=files[i];if(file.startsWith?.("node:"))continue;if(this.#isSlothletInternal(file))continue;return file}for(const file of files){if(!this.#isSlothletInternal(file)){return file}}return null}resolvePathFromCaller(rel){if(rel.startsWith?.("file://"))return fileURLToPath(rel);if(path.isAbsolute(rel))return rel;const callerFile=this.#findCallerBase();if(!callerFile){return path.resolve(process.cwd(),rel)}const callerDir=path.dirname(callerFile);const resolved=path.resolve(callerDir,rel);if(fs.existsSync(resolved)){return resolved}const cwdResolved=path.resolve(process.cwd(),rel);if(fs.existsSync(cwdResolved)){return cwdResolved}return resolved}}export{Resolver};
+import{ComponentBase}from"@cldmv/slothlet/factories/component-base";import{fs,path,url}from"@cldmv/slothlet/helpers/platform";let SLOTHLET_LIB_ROOT=null;let SLOTHLET_PKG_ROOT=null;try{const __filename=url.fileURLToPath(import.meta.url);const __dirname=path.dirname(__filename);SLOTHLET_LIB_ROOT=path.resolve(__dirname,"../..");SLOTHLET_PKG_ROOT=path.normalize(path.resolve(__dirname,"../../.."))}catch{}class Resolver extends ComponentBase{static slothletProperty="resolver";getStack(skipFn){const orig=Error.prepareStackTrace;try{Error.prepareStackTrace=(_,s)=>s;const e=new Error("Stack trace");if(skipFn)Error.captureStackTrace(e,skipFn);return e.stack}finally{Error.prepareStackTrace=orig}}#getStack(){const originalPrepare=Error.prepareStackTrace;Error.prepareStackTrace=(___,stack2)=>stack2;const stack=new Error().stack;Error.prepareStackTrace=originalPrepare;return stack}toFsPath(v){if(!v)return null;const str=String(v);return str.startsWith("file://")?url.fileURLToPath(str):str}#isSlothletInternal(filePath){if(!SLOTHLET_LIB_ROOT)return false;const normalized=path.normalize(filePath);const normalizedLibRoot=path.normalize(SLOTHLET_LIB_ROOT);if(normalized.startsWith(normalizedLibRoot)){return true}const basename=path.basename(normalized);if(basename==="index.mjs"||basename==="index.cjs"){if(path.dirname(normalized)===SLOTHLET_PKG_ROOT)return true}return false}#findCallerBase(){const stack=this.#getStack();const files=stack.map(s=>this.toFsPath(s.getFileName())).filter(Boolean);const slothletIndex=files.findIndex(f=>path.basename(f).toLowerCase()==="slothlet.mjs");if(slothletIndex===-1){for(const file of files){if(!this.#isSlothletInternal(file)){return file}}return null}for(let i=slothletIndex+1;i<files.length;i++){const file=files[i];if(file.startsWith?.("node:"))continue;if(this.#isSlothletInternal(file))continue;return file}for(const file of files){if(!this.#isSlothletInternal(file)){return file}}return null}resolvePathFromCaller(rel){if(this.slothlet?.envTarget==="browser"){return rel||""}if(rel.startsWith?.("file://"))return url.fileURLToPath(rel);if(path.isAbsolute(rel))return rel;const callerFile=this.#findCallerBase();if(!callerFile){return path.resolve(process.cwd(),rel)}const callerDir=path.dirname(callerFile);const resolved=path.resolve(callerDir,rel);if(fs.existsSync(resolved)){return resolved}const cwdResolved=path.resolve(process.cwd(),rel);if(fs.existsSync(cwdResolved)){return cwdResolved}return resolved}}export{Resolver};

package/dist/lib/i18n/languages/de-de.json

@@ -2,6 +2,9 @@
 	"translations": {
 		"INVALID_CONFIG": "Ungültige Konfiguration: {option} ist {value}, erwartet wurde {expected}. {hint}",
 		"INVALID_CONFIG_DIR_MISSING": "Konfigurationsfehler: Die Option 'dir' ist erforderlich. Geben Sie einen Verzeichnispfad an, aus dem die API geladen werden soll.",
+		"INVALID_CONFIG_BROWSER_REQUIRES_MANIFEST": "Konfigurationsfehler: 'manifest' ist erforderlich, wenn env auf 'browser' gesetzt ist. Stellen Sie ein vorgeneriertes Manifest-Objekt mit den Arrays 'files' und 'directories' bereit.",
+		"INVALID_CONFIG_BROWSER_MANIFEST_INVALID": "Konfigurationsfehler: 'manifest' muss ein einfaches Objekt mit den Arrays 'files' und 'directories' sein. Empfangen: {received}",
+		"INVALID_CONFIG_BROWSER_RESOLVE_SPECIFIER_INVALID": "Konfigurationsfehler: 'resolveModuleSpecifier' muss eine Funktion sein, wenn env auf 'browser' gesetzt ist. Empfangen: {received}",
 		"INVALID_CONFIG_DIR_INVALID": "Konfigurationsfehler: 'dir' muss ein nicht leerer Pfad sein. Erhalten: {dir}",
 		"INVALID_CONFIG_MODE_INVALID": "Konfigurationsfehler: 'mode' muss entweder 'eager' oder 'lazy' sein. Erhalten: {value}",
 		"INVALID_CONFIG_NOT_LOADED": "Die Operation '{operation}' kann nicht ausgeführt werden - Instanz nicht geladen. Rufen Sie zuerst load() auf.",
@@ -55,6 +58,9 @@
 		"WARNING_LIFECYCLE_HANDLER_ERROR": "Der Lifecycle-Event-Handler hat einen Fehler für das Event '{event}' verursacht. Andere Handler für dieses Event wurden weiterhin ausgeführt.",
 		"HINT_WARNING_LIFECYCLE_HANDLER_ERROR": "Ein für das Event '{event}' registrierter Lifecycle-Handler hat einen Fehler verursacht. Überprüfen Sie Ihren lifecycle.on('{event}', ...) Handler auf Fehler. Andere Handler für das gleiche Event sind nicht betroffen.",
 		"WARNING_MULTIPLE_ROOT_CONTRIBUTORS": "Mehrere Standard-Funktionsexporte auf Root-Ebene erkannt: {rootContributors}. Jeder wurde nach Dateiname in einen Namespace verschoben (z.B. api.{firstContributor}()). Erwägen Sie einen einzigen Root-Standard-Export oder das Verschieben von Dateien in Unterverzeichnisse.",
+		"WARN_SUPPRESS_FIX_ACTIVE": "Regelkorrektur '{rule}' ist über 'suppressFixes' deaktiviert. Weitere Details unter {url}. Diese temporäre Ausnahme wird in v4 entfernt. Das korrigierte Verhalten von '{rule}' wird dauerhaft erzwungen.",
+		"HINT_WARN_SUPPRESS_FIX_ACTIVE": "Entfernen Sie '{rule}' aus 'suppressFixes' und aktualisieren Sie Ihre API-Verzeichnisstruktur, um das korrigierte Verhalten vor dem Upgrade auf v4 zu übernehmen.",
+		"V3_CONFIG_DEPRECATED": "Konfigurationsoption '{option}' ist veraltet und wird in v4 entfernt. Verwenden Sie stattdessen '{replacement}'.",
 		"V2_CONFIG_UNSUPPORTED": "Konfigurationsoption '{option}' aus v2 wird in v3 nicht unterstützt. {hint} Verwenden Sie stattdessen '{replacement}'.",
 		"DEBUG_MODE_ROOT_CONTRIBUTOR": "[{mode}] Root-Contributor erkannt: {functionName}",
 		"DEBUG_MODE_ROOT_CONTRIBUTOR_APPLIED": "[{mode}] Root-Contributor-Muster angewendet - Funktions-API mit {properties} zusätzlichen Eigenschaften",
@@ -64,21 +70,21 @@
 		"DEBUG_MODE_ASSIGN_TO_API": "ZUWEISEN-AN-API",
 		"DEBUG_MODE_COLLISION_CHECK": "KOLLISIONS-PRÜFUNG",
 		"DEBUG_MODE_COLLISION_DETECT": "KOLLISION-ERKENNUNG",
-		"DEBUG_MODE_COLLISION_WRAPPER_DETECTION": "KOLLISION: Wrapper-Erkennung",
-		"DEBUG_MODE_COLLISION_LAZY_DETECTION": "KOLLISION: Lazy-Erkennung",
-		"DEBUG_MODE_COLLISION_SET_MODE_EXISTING_WRAPPER": "KOLLISION: Setze Kollisionsmodus für BESTEHENDEN Wrapper",
-		"DEBUG_MODE_COLLISION_VERIFIED_EXISTING_WRAPPER_MODE": "KOLLISION: Verifizierter Kollisionsmodus für bestehenden Wrapper",
-		"DEBUG_MODE_COLLISION_SET_MODE_VALUE_WRAPPER": "KOLLISION: Setze Kollisionsmodus für VALUE-Wrapper",
-		"DEBUG_MODE_COLLISION_VERIFIED_VALUE_WRAPPER_MODE": "KOLLISION: Verifizierter Kollisionsmodus für Value-Wrapper",
-		"DEBUG_MODE_COLLISION_REPLACE_MATERIALIZE": "KOLLISION-REPLACE-MATERIALIZE: Löse sofortige Materialisierung aus",
-		"DEBUG_MODE_COLLISION_REPLACE_NO_COPY": "KOLLISION-REPLACE: Dateieigenschaften werden nicht kopiert - replace Modus löscht alles bei der Materialisierung",
-		"DEBUG_MODE_COLLISION_REPLACE_BEFORE": "KOLLISION-REPLACE: VOR Zuweisung",
-		"DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY": "KOLLISION-ASSIGN: Ersetze Bestehendes durch Lazy-Ordner",
-		"DEBUG_MODE_COLLISION_REPLACE_AFTER": "KOLLISION-REPLACE: NACH Zuweisung",
-		"DEBUG_MODE_COLLISION_REPLACE_VERIFY": "KOLLISION-REPLACE: Verifizierung",
-		"DEBUG_MODE_COLLISION_COPY_CHILD_KEYS": "KOLLISION-COPY: Kopiere bestehende Child-Keys",
-		"DEBUG_MODE_COLLISION_COPY_INDIVIDUAL_KEY": "KOLLISION-COPY: Kopiere einzelnen Schlüssel",
-		"DEBUG_MODE_COLLISION_TRIGGER_EARLY_MAT": "KOLLISION-TRIGGER-MAT: Löse frühzeitige Materialisierung aus (Fire-and-Forget)",
+		"DEBUG_MODE_COLLISION_WRAPPER_DETECTION": "[KOLLISION]: Wrapper-Erkennung",
+		"DEBUG_MODE_COLLISION_LAZY_DETECTION": "[KOLLISION]: Lazy-Erkennung",
+		"DEBUG_MODE_COLLISION_SET_MODE_EXISTING_WRAPPER": "[KOLLISION]: Setze Kollisionsmodus für BESTEHENDEN Wrapper",
+		"DEBUG_MODE_COLLISION_VERIFIED_EXISTING_WRAPPER_MODE": "[KOLLISION]: Verifizierter Kollisionsmodus für bestehenden Wrapper",
+		"DEBUG_MODE_COLLISION_SET_MODE_VALUE_WRAPPER": "[KOLLISION]: Setze Kollisionsmodus für VALUE-Wrapper",
+		"DEBUG_MODE_COLLISION_VERIFIED_VALUE_WRAPPER_MODE": "[KOLLISION]: Verifizierter Kollisionsmodus für Value-Wrapper",
+		"DEBUG_MODE_COLLISION_REPLACE_MATERIALIZE": "[KOLLISION-REPLACE-MATERIALIZE]: Löse sofortige Materialisierung aus",
+		"DEBUG_MODE_COLLISION_REPLACE_NO_COPY": "[KOLLISION-REPLACE]: Dateieigenschaften werden nicht kopiert - replace Modus löscht alles bei der Materialisierung",
+		"DEBUG_MODE_COLLISION_REPLACE_BEFORE": "[KOLLISION-REPLACE]: VOR Zuweisung",
+		"DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY": "[KOLLISION-ASSIGN]: Ersetze Bestehendes durch Lazy-Ordner",
+		"DEBUG_MODE_COLLISION_REPLACE_AFTER": "[KOLLISION-REPLACE]: NACH Zuweisung",
+		"DEBUG_MODE_COLLISION_REPLACE_VERIFY": "[KOLLISION-REPLACE]: Verifizierung",
+		"DEBUG_MODE_COLLISION_COPY_CHILD_KEYS": "[KOLLISION-COPY]: Kopiere bestehende Child-Keys",
+		"DEBUG_MODE_COLLISION_COPY_INDIVIDUAL_KEY": "[KOLLISION-COPY]: Kopiere einzelnen Schlüssel",
+		"DEBUG_MODE_COLLISION_TRIGGER_EARLY_MAT": "[KOLLISION-TRIGGER-MAT]: Löse frühzeitige Materialisierung aus (Fire-and-Forget)",
 		"DEBUG_MODE_MERGE_API_OBJECTS_ENTRY": "mergeApiObjects Eintritt",
 		"DEBUG_MODE_MERGE_API_OBJECTS_SOURCE_KEYS": "mergeApiObjects sourceApi Schlüssel",
 		"DEBUG_MODE_MERGE_API_OBJECTS_EXIT_INVALID_SOURCE": "mergeApiObjects Austritt - sourceApi kein Objekt/Funktion",
@@ -160,64 +166,64 @@
 		"DEBUG_MODE_RESTORE_ROOT_KEY_INSPECT": "WIEDERHERSTELLEN-ROOT-SCHLÜSSEL-INSPEKT",
 		"DEBUG_MODE_ROOT_KEY_RESET_LAZY": "Root-Schlüssel wurde über ___resetLazy auf Lazy zurückgesetzt",
 		"DEBUG_MODE_ROOT_KEY_UPDATED_SETIMPL": "Root-Schlüssel wurde über ___setImpl aktualisiert",
-		"DEBUG_MODE_RESTORE_NESTED_PATH": "RESTORE: verschachtelter Pfad",
-		"DEBUG_MODE_RESTORE_FORCING_REPLACE": "RESTORE: erzwinge replace Modus",
+		"DEBUG_MODE_RESTORE_NESTED_PATH": "[RESTORE]: verschachtelter Pfad",
+		"DEBUG_MODE_RESTORE_FORCING_REPLACE": "[RESTORE]: erzwinge replace Modus",
 		"DEBUG_MODE_UPDATED_WRAPPER_IMPL": "Bestandene Wrapper-Impl wurde aktualisiert",
 		"DEBUG_MODE_CREATED_NEW_WRAPPER_UNEXPECTED": "Neuer Wrapper erstellt (unerwartet beim Reload)",
 		"DEBUG_MODE_LIFECYCLE_EVENT": "Ereignis: {event}",
 		"DEBUG_MODE_WRAPPER_CONSTRUCTOR_IMPL_KEYS": "UnifiedWrapper Constructor - Impl Schlüssel",
 		"DEBUG_MODE_WRAPPER_CONSTRUCTOR_AFTER_ADOPT": "UnifiedWrapper Constructor - nach Übernahme (adopt)",
 		"DEBUG_MODE_BACKGROUND_MATERIALIZE_ERROR": "Materialisierungsfehler im Hintergrund",
-		"DEBUG_MODE_APPLY_IMPL_UPDATE_PATH": "APPLY-IMPL-UPDATE-PATH: filePath von null aktualisiert",
+		"DEBUG_MODE_APPLY_IMPL_UPDATE_PATH": "[APPLY-IMPL-UPDATE-PATH]: filePath von null aktualisiert",
 		"DEBUG_MODE_SETIMPL_CALLED": "___setImpl aufgerufen",
 		"DEBUG_MODE_RESETLAZY_CALLED": "___resetLazy aufgerufen",
 		"DEBUG_MODE_RESETLAZY_COMPLETE": "___resetLazy abgeschlossen - Wrapper ist nun un-materialisiert",
-		"DEBUG_MODE_MATERIALIZE_AWAIT": "MATERIALIZE-AWAIT: warte auf bestehende Materialisierungspromise",
+		"DEBUG_MODE_MATERIALIZE_AWAIT": "[MATERIALIZE-AWAIT]: warte auf bestehende Materialisierungspromise",
 		"DEBUG_MODE_MATERIALIZE_START": "_materialize Beginn",
 		"DEBUG_MODE_MATERIALIZE_CALLING_FUNC": "_materialize ruft materializeFunc auf",
 		"DEBUG_MODE_MATERIALIZE_COMPLETE": "_materialize abgeschlossen",
 		"DEBUG_MODE_MATERIALIZE_ERROR": "_materialize Fehler",
 		"DEBUG_MODE_ADOPT_START": "ÜBERNAHME-BEGINN",
 		"DEBUG_MODE_ADOPT": "ÜBERNAHME",
-		"DEBUG_MODE_ADOPT_REPLACE_CLEARING": "ADOPT: REPLACE MODUS - Bestehende Eigenschaften werden gelöscht",
+		"DEBUG_MODE_ADOPT_REPLACE_CLEARING": "[ADOPT]: REPLACE MODUS - Bestehende Eigenschaften werden gelöscht",
 		"DEBUG_MODE_ADOPT_PROCESS": "ADOPT-PROZESS",
 		"DEBUG_MODE_ADOPT_CHECK": "ADOPT-PRÜFUNG",
-		"DEBUG_MODE_ADOPT_SKIP_COLLISION_MERGED": "ADOPT-SKIP: ist collision-merged, Dateiversion wird beibehalten",
-		"DEBUG_MODE_ADOPT_SKIP_NON_CONFIGURABLE": "ADOPT-SKIP: Eigenschaft ist nicht konfigurierbar (vererbt)",
-		"DEBUG_MODE_ADOPT_SKIP_SAME_WRAPPER": "ADOPT-SKIP: Eigenschaft existiert bereits mit gleichem Wrapper",
-		"DEBUG_MODE_ADOPT_ALLOW_NOT_COLLISION_MERGED": "ADOPT-ALLOW: ist NICHT collision-merged, Erlaubnis erteilt",
-		"DEBUG_MODE_ADOPT_REUSE_CHILD_WRAPPER": "ADOPT-REUSE: Bestehender Child-Wrapper wurde wiederverwendet",
+		"DEBUG_MODE_ADOPT_SKIP_COLLISION_MERGED": "[ADOPT-SKIP]: ist collision-merged, Dateiversion wird beibehalten",
+		"DEBUG_MODE_ADOPT_SKIP_NON_CONFIGURABLE": "[ADOPT-SKIP]: Eigenschaft ist nicht konfigurierbar (vererbt)",
+		"DEBUG_MODE_ADOPT_SKIP_SAME_WRAPPER": "[ADOPT-SKIP]: Eigenschaft existiert bereits mit gleichem Wrapper",
+		"DEBUG_MODE_ADOPT_ALLOW_NOT_COLLISION_MERGED": "[ADOPT-ALLOW]: ist NICHT collision-merged, Erlaubnis erteilt",
+		"DEBUG_MODE_ADOPT_REUSE_CHILD_WRAPPER": "[ADOPT-REUSE]: Bestehender Child-Wrapper wurde wiederverwendet",
 		"DEBUG_MODE_ADOPT_WRAP": "ADOPT-UMHÜLLEN",
-		"DEBUG_MODE_ADOPT_DEFINE": "ADOPT-DEFINE: definiere auf Wrapper",
-		"DEBUG_MODE_ADOPT_DEFINED": "ADOPT-DEFINED: erfolgreich auf Wrapper definiert",
-		"DEBUG_MODE_WRAP_CHILD_PATH_CHECK": "WRAP-CHILD-PATH: prüfe auf Child-Dateipfad",
-		"DEBUG_MODE_WRAP_CHILD_PATH_AVAILABLE": "WRAP-CHILD-PATH: __childFilePaths verfügbar",
-		"DEBUG_MODE_WRAP_CHILD_PATH_USING": "WRAP-CHILD-PATH: Benutze __childFilePaths",
-		"DEBUG_MODE_WRAP_CHILD_PATH_PRE_MAT": "WRAP-CHILD-PATH: Benutze __childFilePathsPreMaterialize",
-		"DEBUG_MODE_WRAP_CHILD_PATH_FALLBACK": "WRAP-CHILD-PATH: Benutze fallback parentMetadata?.filePath",
+		"DEBUG_MODE_ADOPT_DEFINE": "[ADOPT-DEFINE]: definiere auf Wrapper",
+		"DEBUG_MODE_ADOPT_DEFINED": "[ADOPT-DEFINED]: erfolgreich auf Wrapper definiert",
+		"DEBUG_MODE_WRAP_CHILD_PATH_CHECK": "[WRAP-CHILD-PATH]: prüfe auf Child-Dateipfad",
+		"DEBUG_MODE_WRAP_CHILD_PATH_AVAILABLE": "[WRAP-CHILD-PATH]: __childFilePaths verfügbar",
+		"DEBUG_MODE_WRAP_CHILD_PATH_USING": "[WRAP-CHILD-PATH]: Benutze __childFilePaths",
+		"DEBUG_MODE_WRAP_CHILD_PATH_PRE_MAT": "[WRAP-CHILD-PATH]: Benutze __childFilePathsPreMaterialize",
+		"DEBUG_MODE_WRAP_CHILD_PATH_FALLBACK": "[WRAP-CHILD-PATH]: Benutze fallback parentMetadata?.filePath",
 		"DEBUG_MODE_WAITING_TYPE": "WARTET-TYP",
-		"DEBUG_MODE_WAITING_TYPE_WALK_WRAPPER": "WAITING-TYPE-WALK: im Wrapper gefunden",
-		"DEBUG_MODE_WAITING_TYPE_WALK_IMPL": "WAITING-TYPE-WALK: in _impl gefunden",
-		"DEBUG_MODE_WAITING_TYPE_WALK_DIRECT": "WAITING-TYPE-WALK: direkter Zugriff",
+		"DEBUG_MODE_WAITING_TYPE_WALK_WRAPPER": "[WAITING-TYPE-WALK]: im Wrapper gefunden",
+		"DEBUG_MODE_WAITING_TYPE_WALK_IMPL": "[WAITING-TYPE-WALK]: in _impl gefunden",
+		"DEBUG_MODE_WAITING_TYPE_WALK_DIRECT": "[WAITING-TYPE-WALK]: direkter Zugriff",
 		"DEBUG_MODE_WAITING_TYPE_RESOLVED": "WARTET-TYP-GELOEST",
-		"DEBUG_MODE_WAITING_TYPE_INFLIGHT": "WAITING-TYPE-INFLIGHT: gebe IN_FLIGHT zurück",
-		"DEBUG_MODE_WAITING_GET_PREMATURE": "WAITING-GET-PREMATURE: vor Materialisierung im Wrapper gefunden",
-		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT": "WAITING-GET-IMMEDIATE-MAT: löse sofortige Materialisierung für collision-merged Ordner aus",
-		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT_ERROR": "WAITING-GET-IMMEDIATE-MAT-ERROR: Materialisierung fehlgeschlagen",
-		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT_SUCCESS": "WAITING-GET-IMMEDIATE-MAT-SUCCESS: jetzt im Wrapper verfügbar",
+		"DEBUG_MODE_WAITING_TYPE_INFLIGHT": "[WAITING-TYPE-INFLIGHT]: gebe IN_FLIGHT zurück",
+		"DEBUG_MODE_WAITING_GET_PREMATURE": "[WAITING-GET-PREMATURE]: vor Materialisierung im Wrapper gefunden",
+		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT": "[WAITING-GET-IMMEDIATE-MAT]: löse sofortige Materialisierung für collision-merged Ordner aus",
+		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT_ERROR": "[WAITING-GET-IMMEDIATE-MAT-ERROR]: Materialisierung fehlgeschlagen",
+		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT_SUCCESS": "[WAITING-GET-IMMEDIATE-MAT-SUCCESS]: jetzt im Wrapper verfügbar",
 		"DEBUG_MODE_WAITING_APPLY_ENTRY": "WARTET-ANWENDUNG-EINTRAG",
-		"DEBUG_MODE_WAITING_APPLY_MATERIALIZE": "WAITING-APPLY-MATERIALIZE: Löse Materialisierung aus",
-		"DEBUG_MODE_WAITING_APPLY_MATERIALIZED": "WAITING-APPLY-MATERIALIZED: Materialisierung abgeschlossen",
-		"DEBUG_MODE_WAITING_APPLY_START_WALK": "WAITING-APPLY-START-WALK: Beginn des propChain Durchlaufs",
+		"DEBUG_MODE_WAITING_APPLY_MATERIALIZE": "[WAITING-APPLY-MATERIALIZE]: Löse Materialisierung aus",
+		"DEBUG_MODE_WAITING_APPLY_MATERIALIZED": "[WAITING-APPLY-MATERIALIZED]: Materialisierung abgeschlossen",
+		"DEBUG_MODE_WAITING_APPLY_START_WALK": "[WAITING-APPLY-START-WALK]: Beginn des propChain Durchlaufs",
 		"DEBUG_MODE_WAITING_APPLY_WALK": "WARTET-ANWENDUNG-DURCHLAUF",
 		"DEBUG_MODE_WAITING_APPLY": "WARTET-ANWENDUNG",
 		"DEBUG_MODE_GET_START": "GET-BEGINN",
 		"DEBUG_MODE_INSPECT_LAZY_UNMATERIALIZED": "util.inspect.custom: Lazy unmaterialisiert",
 		"DEBUG_MODE_GET_CACHED_REPLACE": "GET-CACHED-ERSETZEN",
 		"DEBUG_MODE_GET_CACHED": "GET-GECACHED",
-		"DEBUG_MODE_GET_PROXYGET_ACCESSING": "GET-PROXYGET: Zugriff auf",
-		"DEBUG_MODE_GET_PROXYGET_FOUND": "GET-PROXYGET: Im Wrapper gefunden",
-		"DEBUG_MODE_LAZY_GET_CREATE_WAITING_PROXY": "LAZY-GET: erstelle Waiting-Proxy",
+		"DEBUG_MODE_GET_PROXYGET_ACCESSING": "[GET-PROXYGET]: Zugriff auf",
+		"DEBUG_MODE_GET_PROXYGET_FOUND": "[GET-PROXYGET]: Im Wrapper gefunden",
+		"DEBUG_MODE_LAZY_GET_CREATE_WAITING_PROXY": "[LAZY-GET]: erstelle Waiting-Proxy",
 		"DEBUG_MODE_BUILD_LAZY_API_CALLED": "buildLazyAPI aufgerufen",
 		"DEBUG_MODE_COMPONENT_INITIALIZED": "Komponente initialisiert: {component} → this.{category}.{propertyName}",
 		"DEBUG_MODE_LAZY_WRAPPER_REGISTERED": "Lazy-Wrapper registriert",
@@ -261,6 +267,7 @@
 		"HINT_WARNING_HOT_RELOAD_MERGE_PRIMITIVES": "Primitive Werte (Strings, Zahlen, Booleans) können nicht zusammengeführt werden. Um den Wert zu ersetzen, benutzen Sie den Kollisionsmodus 'replace'. Um den bestehenden zu behalten, benutzen Sie weiterhin 'warn'.",
 		"HINT_WARNING_OWNERSHIP_CONFLICT": "Der Pfad gehört bereits einem anderen Modul. Um das Überschreiben zu erzwingen, benutzen Sie forceOverwrite: true in den api.add() Optionen oder rufen Sie zuerst api.slothlet.api.remove() auf, um den Pfad zu leeren.",
 		"HINT_V2_CONFIG_UNSUPPORTED": "Diese Konfigurationsoption aus v2 wird in v3 nicht unterstützt. Aktualisieren Sie Ihre Konfiguration auf das v3-Äquivalent für bessere Kontrolle und Klarheit.",
+  "HINT_V3_CONFIG_DEPRECATED": "Dieser Konfigurationsparameter wurde zur Klarheit umbenannt. Aktualisieren Sie Ihren Code auf den neuen Optionsnamen, um Vorwärtskompatibilität mit v4 sicherzustellen.",
 		"HINT_MODULE_LOAD_FAILED": "Prüfen Sie die Moduldatei auf Fehler. Stellen Sie sicher, dass sie gültige JavaScript-Syntax und Exports besitzt.",
 		"HINT_MODULE_IMPORT_FAILED": "Stellen Sie sicher, dass die Moduldatei existiert und importiert werden kann. Prüfen Sie auf Syntaxfehler oder fehlende Abhängigkeiten.",
 		"HINT_MODULE_NO_EXPORTS": "Das Modul muss mindestens eine Funktion oder ein Objekt exportieren.",

package/dist/lib/i18n/languages/en-gb.json

@@ -3,6 +3,9 @@
 		"INVALID_CONFIG": "Invalid configuration: {option} is {value}, expected {expected}. {hint}",
 		"INVALID_CONFIG_DIR_MISSING": "Configuration error: 'dir' option is required. Provide a directory path to load API from.",
 		"INVALID_CONFIG_DIR_INVALID": "Configuration error: 'dir' must be a non-empty string path. Received: {dir}",
+		"INVALID_CONFIG_BROWSER_REQUIRES_MANIFEST": "Configuration error: 'manifest' is required when env is 'browser'. Provide a pre-generated manifest object with 'files' and 'directories' arrays.",
+		"INVALID_CONFIG_BROWSER_MANIFEST_INVALID": "Configuration error: 'manifest' must be a plain object with 'files' and 'directories' arrays. Received: {received}",
+		"INVALID_CONFIG_BROWSER_RESOLVE_SPECIFIER_INVALID": "Configuration error: 'resolveModuleSpecifier' must be a function when env is 'browser'. Received: {received}",
 		"INVALID_CONFIG_MODE_INVALID": "Configuration error: 'mode' must be either 'eager' or 'lazy'. Received: {value}",
 		"INVALID_CONFIG_NOT_LOADED": "Cannot perform operation '{operation}' - instance not loaded. Call load() first.",
 		"INVALID_CONFIG_LAZY_MATERIALIZATION_FAILED": "Failed to materialize lazy proxy for '{apiPath}'. Check that the module loads correctly.",
@@ -55,7 +58,10 @@
 		"WARNING_LIFECYCLE_HANDLER_ERROR": "Lifecycle event handler threw an error for event '{event}'. Other handlers for this event continued executing.",
 		"HINT_WARNING_LIFECYCLE_HANDLER_ERROR": "A lifecycle handler registered for the '{event}' event threw an error. Check your lifecycle.on('{event}', ...) handler for bugs. Other handlers in the same event are not affected.",
 		"WARNING_MULTIPLE_ROOT_CONTRIBUTORS": "Multiple root-level default function exports detected: {rootContributors}. Each has been namespaced by filename (e.g., api.{firstContributor}()). Consider using a single root-level default export or moving files to subdirectories.",
+		"V3_CONFIG_DEPRECATED": "Configuration option '{option}' is deprecated and will be removed in v4. Use '{replacement}' instead.",
 		"V2_CONFIG_UNSUPPORTED": "Configuration option '{option}' from v2 is not supported in v3. {hint} Use '{replacement}' instead.",
+		"WARN_SUPPRESS_FIX_ACTIVE": "Rule fix '{rule}' is suppressed via 'suppressFixes'. See {url} for details. This is a temporary override and will be removed in v4. The corrected '{rule}' behaviour will be enforced permanently.",
+		"HINT_WARN_SUPPRESS_FIX_ACTIVE": "Remove '{rule}' from 'suppressFixes' and update your API directory structure to accommodate the corrected behaviour before upgrading to v4.",
 		"DEBUG_MODE_ROOT_CONTRIBUTOR": "[{mode}] Root contributor detected: {functionName}",
 		"DEBUG_MODE_ROOT_CONTRIBUTOR_APPLIED": "[{mode}] Root contributor pattern applied - function API with {properties} additional properties",
 		"DEBUG_MODE_PROCESSING_DIRECTORY": "[{mode}] Processing directory: {categoryName} (depth {currentDepth})",
@@ -64,21 +70,21 @@
 		"DEBUG_MODE_ASSIGN_TO_API": "ASSIGN-TO-API",
 		"DEBUG_MODE_COLLISION_CHECK": "COLLISION-CHECK",
 		"DEBUG_MODE_COLLISION_DETECT": "COLLISION-DETECT",
-		"DEBUG_MODE_COLLISION_WRAPPER_DETECTION": "COLLISION: wrapper detection",
-		"DEBUG_MODE_COLLISION_LAZY_DETECTION": "COLLISION: lazy detection",
-		"DEBUG_MODE_COLLISION_SET_MODE_EXISTING_WRAPPER": "COLLISION: Setting collision mode on EXISTING wrapper",
-		"DEBUG_MODE_COLLISION_VERIFIED_EXISTING_WRAPPER_MODE": "COLLISION: Verified existing wrapper collision mode",
-		"DEBUG_MODE_COLLISION_SET_MODE_VALUE_WRAPPER": "COLLISION: Setting collision mode on VALUE wrapper",
-		"DEBUG_MODE_COLLISION_VERIFIED_VALUE_WRAPPER_MODE": "COLLISION: Verified value wrapper collision mode",
-		"DEBUG_MODE_COLLISION_REPLACE_MATERIALIZE": "COLLISION-REPLACE-MATERIALIZE: Triggering immediate materialization",
-		"DEBUG_MODE_COLLISION_REPLACE_NO_COPY": "COLLISION-REPLACE: Not copying file properties - replace mode will clear everything on materialization",
-		"DEBUG_MODE_COLLISION_REPLACE_BEFORE": "COLLISION-REPLACE: BEFORE assignment",
-		"DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY": "COLLISION-ASSIGN: Replacing existing with lazy folder",
-		"DEBUG_MODE_COLLISION_REPLACE_AFTER": "COLLISION-REPLACE: AFTER assignment",
-		"DEBUG_MODE_COLLISION_REPLACE_VERIFY": "COLLISION-REPLACE: Verification",
-		"DEBUG_MODE_COLLISION_COPY_CHILD_KEYS": "COLLISION-COPY: Copying existing child keys",
-		"DEBUG_MODE_COLLISION_COPY_INDIVIDUAL_KEY": "COLLISION-COPY: Copying individual key",
-		"DEBUG_MODE_COLLISION_TRIGGER_EARLY_MAT": "COLLISION-TRIGGER-MAT: Triggering early materialization (fire-and-forget)",
+		"DEBUG_MODE_COLLISION_WRAPPER_DETECTION": "[COLLISION]: wrapper detection",
+		"DEBUG_MODE_COLLISION_LAZY_DETECTION": "[COLLISION]: lazy detection",
+		"DEBUG_MODE_COLLISION_SET_MODE_EXISTING_WRAPPER": "[COLLISION]: Setting collision mode on EXISTING wrapper",
+		"DEBUG_MODE_COLLISION_VERIFIED_EXISTING_WRAPPER_MODE": "[COLLISION]: Verified existing wrapper collision mode",
+		"DEBUG_MODE_COLLISION_SET_MODE_VALUE_WRAPPER": "[COLLISION]: Setting collision mode on VALUE wrapper",
+		"DEBUG_MODE_COLLISION_VERIFIED_VALUE_WRAPPER_MODE": "[COLLISION]: Verified value wrapper collision mode",
+		"DEBUG_MODE_COLLISION_REPLACE_MATERIALIZE": "[COLLISION-REPLACE-MATERIALIZE]: Triggering immediate materialization",
+		"DEBUG_MODE_COLLISION_REPLACE_NO_COPY": "[COLLISION-REPLACE]: Not copying file properties - replace mode will clear everything on materialization",
+		"DEBUG_MODE_COLLISION_REPLACE_BEFORE": "[COLLISION-REPLACE]: BEFORE assignment",
+		"DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY": "[COLLISION-ASSIGN]: Replacing existing with lazy folder",
+		"DEBUG_MODE_COLLISION_REPLACE_AFTER": "[COLLISION-REPLACE]: AFTER assignment",
+		"DEBUG_MODE_COLLISION_REPLACE_VERIFY": "[COLLISION-REPLACE]: Verification",
+		"DEBUG_MODE_COLLISION_COPY_CHILD_KEYS": "[COLLISION-COPY]: Copying existing child keys",
+		"DEBUG_MODE_COLLISION_COPY_INDIVIDUAL_KEY": "[COLLISION-COPY]: Copying individual key",
+		"DEBUG_MODE_COLLISION_TRIGGER_EARLY_MAT": "[COLLISION-TRIGGER-MAT]: Triggering early materialization (fire-and-forget)",
 		"DEBUG_MODE_MERGE_API_OBJECTS_ENTRY": "mergeApiObjects entry",
 		"DEBUG_MODE_MERGE_API_OBJECTS_SOURCE_KEYS": "mergeApiObjects sourceApi keys",
 		"DEBUG_MODE_MERGE_API_OBJECTS_EXIT_INVALID_SOURCE": "mergeApiObjects exit - sourceApi not object/function",
@@ -160,64 +166,64 @@
 		"DEBUG_MODE_RESTORE_ROOT_KEY_INSPECT": "RESTORE-ROOT-KEY-INSPECT",
 		"DEBUG_MODE_ROOT_KEY_RESET_LAZY": "Root key reset to lazy via ___resetLazy",
 		"DEBUG_MODE_ROOT_KEY_UPDATED_SETIMPL": "Root key updated via ___setImpl",
-		"DEBUG_MODE_RESTORE_NESTED_PATH": "RESTORE: nested path",
-		"DEBUG_MODE_RESTORE_FORCING_REPLACE": "RESTORE: forcing replace mode",
+		"DEBUG_MODE_RESTORE_NESTED_PATH": "[RESTORE]: nested path",
+		"DEBUG_MODE_RESTORE_FORCING_REPLACE": "[RESTORE]: forcing replace mode",
 		"DEBUG_MODE_UPDATED_WRAPPER_IMPL": "Updated existing wrapper implementation",
 		"DEBUG_MODE_CREATED_NEW_WRAPPER_UNEXPECTED": "Created new wrapper (unexpected in reload)",
 		"DEBUG_MODE_LIFECYCLE_EVENT": "Event: {event}",
 		"DEBUG_MODE_WRAPPER_CONSTRUCTOR_IMPL_KEYS": "UnifiedWrapper constructor - impl keys",
 		"DEBUG_MODE_WRAPPER_CONSTRUCTOR_AFTER_ADOPT": "UnifiedWrapper constructor - after adopt",
 		"DEBUG_MODE_BACKGROUND_MATERIALIZE_ERROR": "Background materialization error",
-		"DEBUG_MODE_APPLY_IMPL_UPDATE_PATH": "APPLY-IMPL-UPDATE-PATH: updated filePath from null",
+		"DEBUG_MODE_APPLY_IMPL_UPDATE_PATH": "[APPLY-IMPL-UPDATE-PATH]: updated filePath from null",
 		"DEBUG_MODE_SETIMPL_CALLED": "___setImpl called",
 		"DEBUG_MODE_RESETLAZY_CALLED": "___resetLazy called",
 		"DEBUG_MODE_RESETLAZY_COMPLETE": "___resetLazy complete - wrapper is now un-materialized",
-		"DEBUG_MODE_MATERIALIZE_AWAIT": "MATERIALIZE-AWAIT: awaiting existing materialization promise",
+		"DEBUG_MODE_MATERIALIZE_AWAIT": "[MATERIALIZE-AWAIT]: awaiting existing materialization promise",
 		"DEBUG_MODE_MATERIALIZE_START": "_materialize start",
 		"DEBUG_MODE_MATERIALIZE_CALLING_FUNC": "_materialize calling materializeFunc",
 		"DEBUG_MODE_MATERIALIZE_COMPLETE": "_materialize complete",
 		"DEBUG_MODE_MATERIALIZE_ERROR": "_materialize error",
 		"DEBUG_MODE_ADOPT_START": "ADOPT-START",
 		"DEBUG_MODE_ADOPT": "ADOPT",
-		"DEBUG_MODE_ADOPT_REPLACE_CLEARING": "ADOPT: REPLACE MODE - Clearing existing properties",
+		"DEBUG_MODE_ADOPT_REPLACE_CLEARING": "[ADOPT]: REPLACE MODE - Clearing existing properties",
 		"DEBUG_MODE_ADOPT_PROCESS": "ADOPT-PROCESS",
 		"DEBUG_MODE_ADOPT_CHECK": "ADOPT-CHECK",
-		"DEBUG_MODE_ADOPT_SKIP_COLLISION_MERGED": "ADOPT-SKIP: is collision-merged, keeping file version",
-		"DEBUG_MODE_ADOPT_SKIP_NON_CONFIGURABLE": "ADOPT-SKIP: property is non-configurable (inherited)",
-		"DEBUG_MODE_ADOPT_SKIP_SAME_WRAPPER": "ADOPT-SKIP: property already exists with same wrapper",
-		"DEBUG_MODE_ADOPT_ALLOW_NOT_COLLISION_MERGED": "ADOPT-ALLOW: is NOT collision-merged, allowing",
-		"DEBUG_MODE_ADOPT_REUSE_CHILD_WRAPPER": "ADOPT-REUSE: Reused existing child wrapper",
+		"DEBUG_MODE_ADOPT_SKIP_COLLISION_MERGED": "[ADOPT-SKIP]: is collision-merged, keeping file version",
+		"DEBUG_MODE_ADOPT_SKIP_NON_CONFIGURABLE": "[ADOPT-SKIP]: property is non-configurable (inherited)",
+		"DEBUG_MODE_ADOPT_SKIP_SAME_WRAPPER": "[ADOPT-SKIP]: property already exists with same wrapper",
+		"DEBUG_MODE_ADOPT_ALLOW_NOT_COLLISION_MERGED": "[ADOPT-ALLOW]: is NOT collision-merged, allowing",
+		"DEBUG_MODE_ADOPT_REUSE_CHILD_WRAPPER": "[ADOPT-REUSE]: Reused existing child wrapper",
 		"DEBUG_MODE_ADOPT_WRAP": "ADOPT-WRAP",
-		"DEBUG_MODE_ADOPT_DEFINE": "ADOPT-DEFINE: defining on wrapper",
-		"DEBUG_MODE_ADOPT_DEFINED": "ADOPT-DEFINED: defined successfully on wrapper",
-		"DEBUG_MODE_WRAP_CHILD_PATH_CHECK": "WRAP-CHILD-PATH: checking for child file path",
-		"DEBUG_MODE_WRAP_CHILD_PATH_AVAILABLE": "WRAP-CHILD-PATH: __childFilePaths available",
-		"DEBUG_MODE_WRAP_CHILD_PATH_USING": "WRAP-CHILD-PATH: Using __childFilePaths",
-		"DEBUG_MODE_WRAP_CHILD_PATH_PRE_MAT": "WRAP-CHILD-PATH: Using __childFilePathsPreMaterialize",
-		"DEBUG_MODE_WRAP_CHILD_PATH_FALLBACK": "WRAP-CHILD-PATH: Using fallback parentMetadata?.filePath",
+		"DEBUG_MODE_ADOPT_DEFINE": "[ADOPT-DEFINE]: defining on wrapper",
+		"DEBUG_MODE_ADOPT_DEFINED": "[ADOPT-DEFINED]: defined successfully on wrapper",
+		"DEBUG_MODE_WRAP_CHILD_PATH_CHECK": "[WRAP-CHILD-PATH]: checking for child file path",
+		"DEBUG_MODE_WRAP_CHILD_PATH_AVAILABLE": "[WRAP-CHILD-PATH]: __childFilePaths available",
+		"DEBUG_MODE_WRAP_CHILD_PATH_USING": "[WRAP-CHILD-PATH]: Using __childFilePaths",
+		"DEBUG_MODE_WRAP_CHILD_PATH_PRE_MAT": "[WRAP-CHILD-PATH]: Using __childFilePathsPreMaterialize",
+		"DEBUG_MODE_WRAP_CHILD_PATH_FALLBACK": "[WRAP-CHILD-PATH]: Using fallback parentMetadata?.filePath",
 		"DEBUG_MODE_WAITING_TYPE": "WAITING-TYPE",
-		"DEBUG_MODE_WAITING_TYPE_WALK_WRAPPER": "WAITING-TYPE-WALK: found in wrapper",
-		"DEBUG_MODE_WAITING_TYPE_WALK_IMPL": "WAITING-TYPE-WALK: found in _impl",
-		"DEBUG_MODE_WAITING_TYPE_WALK_DIRECT": "WAITING-TYPE-WALK: accessed directly",
+		"DEBUG_MODE_WAITING_TYPE_WALK_WRAPPER": "[WAITING-TYPE-WALK]: found in wrapper",
+		"DEBUG_MODE_WAITING_TYPE_WALK_IMPL": "[WAITING-TYPE-WALK]: found in _impl",
+		"DEBUG_MODE_WAITING_TYPE_WALK_DIRECT": "[WAITING-TYPE-WALK]: accessed directly",
 		"DEBUG_MODE_WAITING_TYPE_RESOLVED": "WAITING-TYPE-RESOLVED",
-		"DEBUG_MODE_WAITING_TYPE_INFLIGHT": "WAITING-TYPE-INFLIGHT: returning IN_FLIGHT",
-		"DEBUG_MODE_WAITING_GET_PREMATURE": "WAITING-GET-PREMATURE: found in wrapper before materialization",
-		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT": "WAITING-GET-IMMEDIATE-MAT: triggering immediate materialization for collision-merged folder",
-		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT_ERROR": "WAITING-GET-IMMEDIATE-MAT-ERROR: materialization failed",
-		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT_SUCCESS": "WAITING-GET-IMMEDIATE-MAT-SUCCESS: now available in wrapper",
+		"DEBUG_MODE_WAITING_TYPE_INFLIGHT": "[WAITING-TYPE-INFLIGHT]: returning IN_FLIGHT",
+		"DEBUG_MODE_WAITING_GET_PREMATURE": "[WAITING-GET-PREMATURE]: found in wrapper before materialization",
+		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT": "[WAITING-GET-IMMEDIATE-MAT]: triggering immediate materialization for collision-merged folder",
+		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT_ERROR": "[WAITING-GET-IMMEDIATE-MAT-ERROR]: materialization failed",
+		"DEBUG_MODE_WAITING_GET_IMMEDIATE_MAT_SUCCESS": "[WAITING-GET-IMMEDIATE-MAT-SUCCESS]: now available in wrapper",
 		"DEBUG_MODE_WAITING_APPLY_ENTRY": "WAITING-APPLY-ENTRY",
-		"DEBUG_MODE_WAITING_APPLY_MATERIALIZE": "WAITING-APPLY-MATERIALIZE: Triggering materialization",
-		"DEBUG_MODE_WAITING_APPLY_MATERIALIZED": "WAITING-APPLY-MATERIALIZED: Materialization complete",
-		"DEBUG_MODE_WAITING_APPLY_START_WALK": "WAITING-APPLY-START-WALK: Starting propChain walk",
+		"DEBUG_MODE_WAITING_APPLY_MATERIALIZE": "[WAITING-APPLY-MATERIALIZE]: Triggering materialization",
+		"DEBUG_MODE_WAITING_APPLY_MATERIALIZED": "[WAITING-APPLY-MATERIALIZED]: Materialization complete",
+		"DEBUG_MODE_WAITING_APPLY_START_WALK": "[WAITING-APPLY-START-WALK]: Starting propChain walk",
 		"DEBUG_MODE_WAITING_APPLY_WALK": "WAITING-APPLY-WALK",
 		"DEBUG_MODE_WAITING_APPLY": "WAITING-APPLY",
 		"DEBUG_MODE_GET_START": "GET-START",
 		"DEBUG_MODE_INSPECT_LAZY_UNMATERIALIZED": "util.inspect.custom: Lazy unmaterialized",
 		"DEBUG_MODE_GET_CACHED_REPLACE": "GET-CACHED-REPLACE",
 		"DEBUG_MODE_GET_CACHED": "GET-CACHED",
-		"DEBUG_MODE_GET_PROXYGET_ACCESSING": "GET-PROXYGET: Accessing",
-		"DEBUG_MODE_GET_PROXYGET_FOUND": "GET-PROXYGET: Found in wrapper",
-		"DEBUG_MODE_LAZY_GET_CREATE_WAITING_PROXY": "LAZY-GET: will create waiting proxy",
+		"DEBUG_MODE_GET_PROXYGET_ACCESSING": "[GET-PROXYGET]: Accessing",
+		"DEBUG_MODE_GET_PROXYGET_FOUND": "[GET-PROXYGET]: Found in wrapper",
+		"DEBUG_MODE_LAZY_GET_CREATE_WAITING_PROXY": "[LAZY-GET]: will create waiting proxy",
 		"DEBUG_MODE_BUILD_LAZY_API_CALLED": "buildLazyAPI called",
 		"DEBUG_MODE_COMPONENT_INITIALIZED": "Component initialized: {component} → this.{category}.{propertyName}",
 		"DEBUG_MODE_LAZY_WRAPPER_REGISTERED": "Lazy wrapper registered",
@@ -261,6 +267,7 @@
 		"HINT_WARNING_HOT_RELOAD_MERGE_PRIMITIVES": "Cannot merge primitive values (strings, numbers, booleans). To replace the value, use collision mode 'replace'. To keep the existing value, continue using 'warn' mode.",
 		"HINT_WARNING_OWNERSHIP_CONFLICT": "The path is already owned by another module. To force overwrite, use forceOverwrite: true in api.add() options, or call api.slothlet.api.remove() first to clear the path.",
 		"HINT_V2_CONFIG_UNSUPPORTED": "This configuration option from v2 is not supported in v3. Update your configuration to use the v3 equivalent for better control and clarity.",
+  "HINT_V3_CONFIG_DEPRECATED": "This configuration option has been renamed for clarity. Update your code to use the new option name to ensure forward compatibility with v4.",
 		"HINT_MODULE_LOAD_FAILED": "Check the module file for errors. Ensure it has valid JavaScript syntax and exports.",
 		"HINT_MODULE_IMPORT_FAILED": "Ensure the module file exists and can be imported. Check for syntax errors or missing dependencies.",
 		"HINT_MODULE_NO_EXPORTS": "The module must export at least one function or object.",