@cldmv/slothlet 3.3.0 → 3.3.2

package/README.md

@@ -55,18 +55,17 @@ Every feature has been hardened with a comprehensive test suite - over **5,300 t
 
 ## ✨ What's New
 
-### Latest: v3.3.0 (April 2026)
+### Latest: v3.3.2 (April 2026)
 
-- **Permission System** — path-based access control for inter-module calls with glob pattern rules, most-specific-wins evaluation, audit events, and runtime `api.slothlet.permissions.*` management API
-- **Shared pattern matcher** — extracted hook system's glob compilation into a shared utility for reuse across hooks and permissions
-- [View full v3.3.0 Changelog](./docs/changelog/v3/v3.3.0.md)
+- **Workflow maintenance** — `release.yml` and `publish.yml` now match `ci.yml`: minimum Node.js raised to `20.19.0` and `lts_only_matrix` input added (default `true`) to keep matrix tests on LTS-only Node releases.
+- [View full v3.3.2 Changelog](./docs/changelog/v3/v3.3.2.md)
 
 ### Recent Releases
 
+- **v3.3.1** (April 2026) — `construct` trap for proxied classes; Node.js engine requirement raised to ≥ 20.19.0; type declaration fixes ([Changelog](./docs/changelog/v3/v3.3.1.md))
+- **v3.3.0** (April 2026) — Permission System: path-based access control for inter-module calls with glob rules, audit events, and `api.slothlet.permissions.*` runtime API ([Changelog](./docs/changelog/v3/v3.3.0.md))
 - **v3.2.3** (April 2026) — publish workflow fix ([Changelog](./docs/changelog/v3/v3.2.3.md))
 - **v3.2.2** (April 2026) — missing `set` trap on version dispatchers; `util.inspect(api.auth)` now shows resolved versioned namespace ([Changelog](./docs/changelog/v3/v3.2.2.md))
-- **v3.2.1** (April 2026) — version-dispatcher `defineProperty` trap fix; pre-commit validation cleanup ([Changelog](./docs/changelog/v3/v3.2.1.md))
-- **v3.2.0** (April 2026) — API Path Versioning (`versionDispatcher`, `api.slothlet.versioning.*`, version metadata, dispatcher proxy); lazy-mode shutdown race fix ([Changelog](./docs/changelog/v3/v3.2.0.md))
 
 
 📚 **For complete version history and detailed release notes, see [docs/changelog/](./docs/changelog/) folder.**
@@ -176,8 +175,7 @@ Automatic context preservation across all asynchronous boundaries:
 
 ### Requirements
 
-- **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`
+- **Node.js v20.19.0 or higher**
 
 ### Install
 

package/REFERENCE.md

@@ -0,0 +1,23 @@
+# Slothlet Reference
+
+Full documentation lives in the GitHub repository.
+
+## Documentation
+
+| Topic | Link |
+|---|---|
+| README / overview | [README.md](https://github.com/CLDMV/slothlet/blob/master/README.md) |
+| All docs | [docs/](https://github.com/CLDMV/slothlet/tree/master/docs) |
+| Configuration | [docs/CONFIGURATION.md](https://github.com/CLDMV/slothlet/blob/master/docs/CONFIGURATION.md) |
+| API transformation rules | [docs/API-RULES.md](https://github.com/CLDMV/slothlet/blob/master/docs/API-RULES.md) |
+| Hooks | [docs/HOOKS.md](https://github.com/CLDMV/slothlet/blob/master/docs/HOOKS.md) |
+| Context propagation | [docs/CONTEXT-PROPAGATION.md](https://github.com/CLDMV/slothlet/blob/master/docs/CONTEXT-PROPAGATION.md) |
+| Metadata | [docs/METADATA.md](https://github.com/CLDMV/slothlet/blob/master/docs/METADATA.md) |
+| Permissions | [docs/PERMISSIONS.md](https://github.com/CLDMV/slothlet/blob/master/docs/PERMISSIONS.md) |
+| API versioning | [docs/VERSIONING.md](https://github.com/CLDMV/slothlet/blob/master/docs/VERSIONING.md) |
+| TypeScript | [docs/TYPESCRIPT.md](https://github.com/CLDMV/slothlet/blob/master/docs/TYPESCRIPT.md) |
+| Lifecycle | [docs/LIFECYCLE.md](https://github.com/CLDMV/slothlet/blob/master/docs/LIFECYCLE.md) |
+| Hot reload | [docs/RELOAD.md](https://github.com/CLDMV/slothlet/blob/master/docs/RELOAD.md) |
+| Performance | [docs/PERFORMANCE.md](https://github.com/CLDMV/slothlet/blob/master/docs/PERFORMANCE.md) |
+| Changelog | [docs/changelog/](https://github.com/CLDMV/slothlet/tree/master/docs/changelog) |
+| Agent/AI usage guide | [AGENT-USAGE.md](https://github.com/CLDMV/slothlet/blob/master/AGENT-USAGE.md) |

package/dist/lib/builders/api-assignment.mjs

@@ -14,592 +14,4 @@
 	limitations under the License.
 */
 
-
-
-
-import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
-import { resolveWrapper } from "@cldmv/slothlet/handlers/unified-wrapper";
-
-
-export class ApiAssignment extends ComponentBase {
-	static slothletProperty = "apiAssignment";
-
-	
-	constructor(slothlet) {
-		super(slothlet);
-	}
-
-	
-	isWrapperProxy(value) {
-		return !!(value && resolveWrapper(value));
-	}
-
-	
-	assignToApiPath(targetApi, key, value, options = {}) {
-		const valueIsWrapper = this.isWrapperProxy(value);
-		
-		
-		const valueId = valueIsWrapper ? (resolveWrapper(value)?.____slothletInternal?.id ?? "no-id") : "not-wrapper";
-		this.slothlet.debug("api", {
-			key: "DEBUG_MODE_ASSIGN_TO_API",
-			propKey: key,
-			valueId,
-			typeOf: typeof value
-		});
-
-		const {
-			allowOverwrite = false,
-			mutateExisting = false,
-			useCollisionDetection = false,
-			config = null,
-			collisionContext = "initial",
-			syncWrapper = null,
-			collisionMode = "merge", 
-			moduleID = null
-		} = options;
-
-		
-		const existing = targetApi[key];
-
-		
-		if (existing !== undefined && this.isWrapperProxy(existing) && this.isWrapperProxy(value)) {
-			if (mutateExisting && syncWrapper) {
-				syncWrapper(existing, value, config, collisionMode, moduleID);
-				return true;
-			}
-			
-		}
-
-		
-		this.slothlet.debug("api", {
-			key: "DEBUG_MODE_COLLISION_CHECK",
-			propKey: key,
-			useCollisionDetection,
-			hasConfig: !!config,
-			hasExisting: existing !== undefined,
-			existingType: typeof existing
-		});
-		if (useCollisionDetection && config && existing !== undefined) {
-			this.slothlet.debug("api", {
-				key: "DEBUG_MODE_COLLISION_DETECT",
-				propKey: key,
-				context: collisionContext,
-				existingType: typeof existing,
-				valueType: typeof value
-			});
-			
-			const collisionMode = config.collision?.[collisionContext] || "merge";
-
-			if (collisionMode === "error") {
-				
-				
-				const SlothletError = this.slothlet?.SlothletError || Error;
-				throw new SlothletError("COLLISION_ERROR", {
-					key: String(key),
-					collisionMode,
-					collisionContext
-				});
-			}
-
-			if (collisionMode === "skip") {
-				
-				return false;
-			}
-
-			
-			let effectiveMode = collisionMode;
-			if (collisionMode === "warn") {
-				new this.slothlet.SlothletWarning("WARNING_COLLISION_FILE_FOLDER_MERGE", {
-					key: String(key)
-				});
-				
-				effectiveMode = "merge";
-			}
-
-			
-			
-			const existingIsWrapper = this.isWrapperProxy(existing);
-			const valueIsWrapper = this.isWrapperProxy(value);
-
-			this.slothlet.debug("api", {
-				key: "DEBUG_MODE_COLLISION_WRAPPER_DETECTION",
-				propKey: key,
-				existingIsWrapper,
-				valueIsWrapper,
-				hasExistingWrapper: resolveWrapper(existing) ? "yes" : "no",
-				hasValueWrapper: resolveWrapper(value) ? "yes" : "no"
-			});
-
-			if (existingIsWrapper && valueIsWrapper) {
-				const existingWrapper = resolveWrapper(existing);
-				const valueWrapper = resolveWrapper(value);
-				const existingIsLazyUnmaterialized =
-					existingWrapper.____slothletInternal.mode === "lazy" && !existingWrapper.____slothletInternal.state.materialized;
-				const valueIsLazyUnmaterialized =
-					valueWrapper.____slothletInternal.mode === "lazy" && !valueWrapper.____slothletInternal.state.materialized;
-
-				this.slothlet.debug("api", {
-					key: "DEBUG_MODE_COLLISION_LAZY_DETECTION",
-					propKey: key,
-					effectiveMode,
-					existingLazy: existingIsLazyUnmaterialized,
-					valueLazy: valueIsLazyUnmaterialized
-				});
-
-				
-				
-				
-				if (existingIsLazyUnmaterialized) {
-					this.slothlet.debug("api", {
-						key: "DEBUG_MODE_COLLISION_SET_MODE_EXISTING_WRAPPER",
-						effectiveMode,
-						apiPath: existingWrapper.____slothletInternal.apiPath
-					});
-					existingWrapper.____slothletInternal.state.collisionMode = effectiveMode;
-					this.slothlet.debug("api", {
-						key: "DEBUG_MODE_COLLISION_VERIFIED_EXISTING_WRAPPER_MODE",
-						collisionMode: existingWrapper.____slothletInternal.state.collisionMode
-					});
-				}
-				if (valueIsLazyUnmaterialized) {
-					this.slothlet.debug("api", {
-						key: "DEBUG_MODE_COLLISION_SET_MODE_VALUE_WRAPPER",
-						effectiveMode,
-						apiPath: valueWrapper.____slothletInternal.apiPath
-					});
-					valueWrapper.____slothletInternal.state.collisionMode = effectiveMode;
-					this.slothlet.debug("api", {
-						key: "DEBUG_MODE_COLLISION_VERIFIED_VALUE_WRAPPER_MODE",
-						collisionMode: valueWrapper.____slothletInternal.state.collisionMode
-					});
-
-					
-					
-					if (effectiveMode === "replace") {
-						this.slothlet.debug("api", {
-							key: "DEBUG_MODE_COLLISION_REPLACE_MATERIALIZE",
-							apiPath: valueWrapper.____slothletInternal.apiPath
-						});
-						valueWrapper._materialize(); 
-					}
-				}
-			}
-
-			
-			if (effectiveMode === "replace") {
-				
-				
-				
-				if (existingIsWrapper && valueIsWrapper) {
-					const existingWrapper = resolveWrapper(existing);
-					const valueWrapper = resolveWrapper(value);
-					
-					
-					
-					
-					const existingIsLazyUnmaterialized =
-						existingWrapper.____slothletInternal.mode === "lazy" && !existingWrapper.____slothletInternal.state.materialized;
-					const valueIsLazyUnmaterialized =
-						valueWrapper.____slothletInternal.mode === "lazy" && !valueWrapper.____slothletInternal.state.materialized;
-
-					
-					if (valueIsLazyUnmaterialized && !existingIsLazyUnmaterialized) {
-						this.slothlet.debug("api", {
-							key: "DEBUG_MODE_COLLISION_REPLACE_NO_COPY"
-						});
-						this.slothlet.debug("api", {
-							key: "DEBUG_MODE_COLLISION_REPLACE_BEFORE",
-							propKey: key,
-							currentWrapperId: resolveWrapper(existing)?.____slothletInternal.id
-						});
-						this.slothlet.debug("api", {
-							key: "DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY",
-							propKey: key,
-							collisionMode: valueWrapper.____slothletInternal.state.collisionMode
-						});
-						targetApi[key] = value;
-						this.slothlet.debug("api", {
-							key: "DEBUG_MODE_COLLISION_REPLACE_AFTER",
-							propKey: key,
-							newWrapperId: resolveWrapper(targetApi[key])?.____slothletInternal.id
-						});
-						this.slothlet.debug("api", {
-							key: "DEBUG_MODE_COLLISION_REPLACE_VERIFY",
-							expectedId: valueWrapper.____slothletInternal.id,
-							actualId: resolveWrapper(targetApi[key])?.____slothletInternal.id
-						});
-						return true; 
-					}
-					
-				}
-				
-				targetApi[key] = value;
-				return true;
-			}
-
-			
-			
-			
-			if (effectiveMode === "merge" || effectiveMode === "merge-replace") {
-				const isMergeReplace = effectiveMode === "merge-replace";
-				
-
-				if (existingIsWrapper && valueIsWrapper) {
-					
-					const existingWrapper = resolveWrapper(existing);
-					const valueWrapper = resolveWrapper(value);
-
-					
-					
-					const existingIsLazyUnmaterialized =
-						existingWrapper.____slothletInternal.mode === "lazy" && !existingWrapper.____slothletInternal.state.materialized;
-					const valueIsLazyUnmaterialized =
-						valueWrapper.____slothletInternal.mode === "lazy" && !valueWrapper.____slothletInternal.state.materialized;
-
-					if (existingIsLazyUnmaterialized && !valueIsLazyUnmaterialized) {
-						
-						
-
-						
-						const valueMetadata = this.slothlet.handlers?.metadata?.getMetadata(value);
-						const valueFilePath = valueMetadata?.filePath;
-
-						
-						
-						
-						
-						
-						if (!existingWrapper.____slothletInternal.childFilePathsPreMaterialize) {
-							existingWrapper.____slothletInternal.childFilePathsPreMaterialize = {};
-						}
-
-						const valueChildKeys = Object.keys(valueWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
-						for (const key of valueChildKeys) {
-							
-							Object.defineProperty(existingWrapper, key, {
-								configurable: true
-							});
-							
-							if (valueFilePath) {
-								existingWrapper.____slothletInternal.childFilePathsPreMaterialize[key] = valueFilePath;
-							}
-						}
-
-						return true; 
-					} else if (valueIsLazyUnmaterialized && !existingIsLazyUnmaterialized) {
-						
-						
-						
-						
-						
-						
-
-						
-						
-						if (!isMergeReplace) {
-							
-							
-
-							
-							const existingMetadata = this.slothlet.handlers?.metadata?.getMetadata(existing);
-							const existingFilePath = existingMetadata?.filePath;
-
-							
-							if (!valueWrapper.____slothletInternal.childFilePathsPreMaterialize) {
-								valueWrapper.____slothletInternal.childFilePathsPreMaterialize = {};
-							}
-
-							const existingChildKeys = Object.keys(existingWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
-							
-							
-							
-							this.slothlet.debug("api", {
-								key: "DEBUG_MODE_COLLISION_COPY_CHILD_KEYS",
-								existingChildKeys: existingChildKeys.join(","),
-								fromApiPath: existingWrapper.____slothletInternal.apiPath,
-								toApiPath: valueWrapper.____slothletInternal.apiPath,
-								valueWrapperId: valueWrapper.____slothletInternal.id || "no-id"
-							});
-
-							
-							if (!valueWrapper.____slothletInternal.collisionMergedKeys) {
-								valueWrapper.____slothletInternal.collisionMergedKeys = new Set();
-							}
-
-							for (const key of existingChildKeys) {
-								const child = existingWrapper[key];
-								this.slothlet.debug("api", {
-									key: "DEBUG_MODE_COLLISION_COPY_INDIVIDUAL_KEY",
-									propKey: key,
-									childName: child?.name,
-									typeOf: typeof child,
-									valueWrapperId: valueWrapper.____slothletInternal.id || "no-id"
-								});
-								Object.defineProperty(valueWrapper, key, {
-									value: child,
-									writable: false,
-									enumerable: true,
-									configurable: true
-								});
-								
-								valueWrapper.____slothletInternal.collisionMergedKeys.add(key);
-								
-								if (existingFilePath) {
-									valueWrapper.____slothletInternal.childFilePathsPreMaterialize[key] = existingFilePath;
-								}
-							}
-
-							
-							
-							
-							
-							this.slothlet.debug("api", {
-								key: "DEBUG_MODE_COLLISION_TRIGGER_EARLY_MAT",
-								apiPath: valueWrapper.____slothletInternal.apiPath
-							});
-							valueWrapper.____slothletInternal.needsImmediateChildAdoption = true;
-							if (
-								valueWrapper.____slothletInternal.materializeFunc &&
-								!valueWrapper.____slothletInternal.state?.materialized &&
-								!valueWrapper.____slothletInternal.state?.inFlight
-							) {
-								valueWrapper._materialize().catch((err) => {
-									new this.slothlet.SlothletWarning(
-										"WARNING_COLLISION_TRIGGER_MATERIALIZE_ERROR",
-										{
-											apiPath: valueWrapper.____slothletInternal.apiPath
-										},
-										err
-									);
-								});
-							}
-							
-						} else {
-							
-							
-							
-							
-							valueWrapper._mergeAfterMaterialize = {
-								existingWrapper,
-								isMergeReplace: true
-							};
-						}
-
-						
-						this.slothlet.debug("api", {
-							key: "DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY",
-							propKey: key,
-							collisionMode: valueWrapper.____slothletInternal.state.collisionMode
-						});
-						targetApi[key] = value;
-						return true; 
-					}
-
-					
-					
-					const existingChildCount = Object.keys(existingWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__")).length;
-					const valueChildCount = Object.keys(valueWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__")).length;
-					if (existingWrapper.____slothletInternal.impl && existingChildCount === 0) {
-						existingWrapper.___adoptImplChildren();
-					}
-					if (valueWrapper.____slothletInternal.impl && valueChildCount === 0) {
-						valueWrapper.___adoptImplChildren();
-					}
-
-					
-					
-					
-					
-					
-					
-					const valueChildKeys2 = Object.keys(valueWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
-					for (const key of valueChildKeys2) {
-						const child = valueWrapper[key];
-						const isInternal = typeof key === "string" && (key.startsWith("_") || key.startsWith("__"));
-						
-						const keyExists = !isInternal && Object.prototype.hasOwnProperty.call(existingWrapper, key);
-
-						if (!keyExists) {
-							Object.defineProperty(existingWrapper, key, {
-								value: child,
-								writable: false,
-								enumerable: true,
-								configurable: true
-							});
-						} else if (isMergeReplace) {
-							const descriptor = Object.getOwnPropertyDescriptor(existingWrapper, key);
-							
-							
-							
-							
-							if (descriptor?.configurable) {
-								delete existingWrapper[key];
-							}
-							Object.defineProperty(existingWrapper, key, {
-								value: child,
-								writable: false,
-								enumerable: true,
-								configurable: true
-							});
-						} else {
-							
-							
-							
-							const existingChild = existingWrapper[key];
-							const existingChildWrapper = resolveWrapper(existingChild);
-							const newChildWrapper = resolveWrapper(child);
-							
-							
-							if (existingChildWrapper && newChildWrapper) {
-								
-								const newChildChildCount = Object.keys(newChildWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__")).length;
-								if (newChildWrapper.____slothletInternal.impl && newChildChildCount === 0) {
-									newChildWrapper.___adoptImplChildren();
-								}
-								const newChildKeys = Object.keys(newChildWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
-								const ____existingChildKeys = Object.keys(existingChildWrapper).filter((k) => !k.startsWith("_") && !k.startsWith("__"));
-								for (const childKey of newChildKeys) {
-									const childKeyExists = Object.prototype.hasOwnProperty.call(existingChildWrapper, childKey);
-									
-									
-									if (!childKeyExists) {
-										Object.defineProperty(existingChildWrapper, childKey, {
-											value: newChildWrapper[childKey],
-											writable: false,
-											enumerable: true,
-											configurable: true
-										});
-									}
-								}
-							}
-						}
-					}
-					
-					if (
-						valueWrapper.____slothletInternal.mode === "lazy" &&
-						!valueWrapper.____slothletInternal.state.materialized &&
-						valueWrapper.____slothletInternal.materializeFunc
-					) {
-						
-						
-						return false; 
-					}
-
-					return true;
-				} else if (existingIsWrapper && !valueIsWrapper) {
-					
-					const existingWrapper = resolveWrapper(existing);
-					const existingImpl = existingWrapper.__impl;
-					
-					
-					const mergedImpl = { ...(existingImpl || {}), ...value };
-					existingWrapper.___setImpl(mergedImpl);
-					return true;
-				} else if (!existingIsWrapper && valueIsWrapper) {
-					
-					
-				} else {
-					
-					
-					
-					if (typeof existing === "object" && existing !== null && typeof value === "object" && value !== null) {
-						Object.assign(existing, value);
-						return true;
-					}
-				}
-				
-			}
-
-			
-		}
-
-		
-		if (existing !== undefined && !allowOverwrite && !mutateExisting && !useCollisionDetection) {
-			return false; 
-		}
-
-		
-		targetApi[key] = value;
-		return true;
-	}
-
-	
-	async mergeApiObjects(targetApi, sourceApi, options = {}) {
-		const config = options.config;
-		if (config?.debug?.api) {
-			this.slothlet.debug("api", {
-				key: "DEBUG_MODE_MERGE_API_OBJECTS_ENTRY",
-				targetApiType: typeof targetApi,
-				sourceApiType: typeof sourceApi
-			});
-			this.slothlet.debug("api", {
-				key: "DEBUG_MODE_MERGE_API_OBJECTS_SOURCE_KEYS",
-				sourceApiKeys: sourceApi ? Object.keys(sourceApi) : []
-			});
-		}
-
-		
-		if (!sourceApi || (typeof sourceApi !== "object" && typeof sourceApi !== "function")) {
-			if (config?.debug?.api) {
-				this.slothlet.debug("api", {
-					key: "DEBUG_MODE_MERGE_API_OBJECTS_EXIT_INVALID_SOURCE"
-				});
-			}
-			return;
-		}
-
-		const { removeMissing = false, moduleID = null, ...assignOptions } = options;
-
-		
-		const sourceKeys = new Set(Object.keys(sourceApi));
-		for (const key of sourceKeys) {
-			const sourceValue = sourceApi[key];
-			const targetValue = targetApi[key];
-
-			if (config?.debug?.api) {
-				this.slothlet.debug("api", {
-					key: "DEBUG_MODE_MERGE_API_OBJECTS_PROCESSING_KEY",
-					propKey: key,
-					targetValueType: typeof targetValue,
-					sourceValueType: typeof sourceValue
-				});
-			}
-
-			
-			if (
-				targetValue &&
-				typeof targetValue === "object" &&
-				!this.isWrapperProxy(targetValue) &&
-				sourceValue &&
-				typeof sourceValue === "object" &&
-				!this.isWrapperProxy(sourceValue)
-			) {
-				if (config?.debug?.api) {
-					this.slothlet.debug("api", {
-						key: "DEBUG_MODE_MERGE_API_OBJECTS_RECURSING",
-						propKey: key
-					});
-				}
-				await this.mergeApiObjects(targetValue, sourceValue, options);
-			} else {
-				
-				if (config?.debug?.api) {
-					this.slothlet.debug("api", {
-						key: "DEBUG_MODE_MERGE_API_OBJECTS_CALLING_ASSIGN",
-						propKey: key
-					});
-				}
-				this.assignToApiPath(targetApi, key, sourceValue, { ...assignOptions, moduleID });
-			}
-		}
-
-		
-		if (removeMissing) {
-			for (const key of Object.keys(targetApi)) {
-				if (!sourceKeys.has(key)) {
-					delete targetApi[key];
-				}
-			}
-		}
-	}
-}
+import{ComponentBase}from"@cldmv/slothlet/factories/component-base";import{resolveWrapper}from"@cldmv/slothlet/handlers/unified-wrapper";class ApiAssignment extends ComponentBase{static slothletProperty="apiAssignment";constructor(slothlet){super(slothlet)}isWrapperProxy(value){return!!(value&&resolveWrapper(value))}assignToApiPath(targetApi,key,value,options={}){const valueIsWrapper=this.isWrapperProxy(value);const valueId=valueIsWrapper?resolveWrapper(value)?.____slothletInternal?.id??"no-id":"not-wrapper";this.slothlet.debug("api",{key:"DEBUG_MODE_ASSIGN_TO_API",propKey:key,valueId,typeOf:typeof value});const{allowOverwrite=false,mutateExisting=false,useCollisionDetection=false,config=null,collisionContext="initial",syncWrapper=null,collisionMode="merge",moduleID=null}=options;const existing=targetApi[key];if(existing!==void 0&&this.isWrapperProxy(existing)&&this.isWrapperProxy(value)){if(mutateExisting&&syncWrapper){syncWrapper(existing,value,config,collisionMode,moduleID);return true}}this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_CHECK",propKey:key,useCollisionDetection,hasConfig:!!config,hasExisting:existing!==void 0,existingType:typeof existing});if(useCollisionDetection&&config&&existing!==void 0){this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_DETECT",propKey:key,context:collisionContext,existingType:typeof existing,valueType:typeof value});const collisionMode2=config.collision?.[collisionContext]||"merge";if(collisionMode2==="error"){const SlothletError=this.slothlet?.SlothletError||Error;throw new SlothletError("COLLISION_ERROR",{key:String(key),collisionMode:collisionMode2,collisionContext})}if(collisionMode2==="skip"){return false}let effectiveMode=collisionMode2;if(collisionMode2==="warn"){new this.slothlet.SlothletWarning("WARNING_COLLISION_FILE_FOLDER_MERGE",{key:String(key)});effectiveMode="merge"}const existingIsWrapper=this.isWrapperProxy(existing);const valueIsWrapper2=this.isWrapperProxy(value);this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_WRAPPER_DETECTION",propKey:key,existingIsWrapper,valueIsWrapper:valueIsWrapper2,hasExistingWrapper:resolveWrapper(existing)?"yes":"no",hasValueWrapper:resolveWrapper(value)?"yes":"no"});if(existingIsWrapper&&valueIsWrapper2){const existingWrapper=resolveWrapper(existing);const valueWrapper=resolveWrapper(value);const existingIsLazyUnmaterialized=existingWrapper.____slothletInternal.mode==="lazy"&&!existingWrapper.____slothletInternal.state.materialized;const valueIsLazyUnmaterialized=valueWrapper.____slothletInternal.mode==="lazy"&&!valueWrapper.____slothletInternal.state.materialized;this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_LAZY_DETECTION",propKey:key,effectiveMode,existingLazy:existingIsLazyUnmaterialized,valueLazy:valueIsLazyUnmaterialized});if(existingIsLazyUnmaterialized){this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_SET_MODE_EXISTING_WRAPPER",effectiveMode,apiPath:existingWrapper.____slothletInternal.apiPath});existingWrapper.____slothletInternal.state.collisionMode=effectiveMode;this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_VERIFIED_EXISTING_WRAPPER_MODE",collisionMode:existingWrapper.____slothletInternal.state.collisionMode})}if(valueIsLazyUnmaterialized){this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_SET_MODE_VALUE_WRAPPER",effectiveMode,apiPath:valueWrapper.____slothletInternal.apiPath});valueWrapper.____slothletInternal.state.collisionMode=effectiveMode;this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_VERIFIED_VALUE_WRAPPER_MODE",collisionMode:valueWrapper.____slothletInternal.state.collisionMode});if(effectiveMode==="replace"){this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_REPLACE_MATERIALIZE",apiPath:valueWrapper.____slothletInternal.apiPath});valueWrapper._materialize()}}}if(effectiveMode==="replace"){if(existingIsWrapper&&valueIsWrapper2){const existingWrapper=resolveWrapper(existing);const valueWrapper=resolveWrapper(value);const existingIsLazyUnmaterialized=existingWrapper.____slothletInternal.mode==="lazy"&&!existingWrapper.____slothletInternal.state.materialized;const valueIsLazyUnmaterialized=valueWrapper.____slothletInternal.mode==="lazy"&&!valueWrapper.____slothletInternal.state.materialized;if(valueIsLazyUnmaterialized&&!existingIsLazyUnmaterialized){this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_REPLACE_NO_COPY"});this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_REPLACE_BEFORE",propKey:key,currentWrapperId:resolveWrapper(existing)?.____slothletInternal.id});this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY",propKey:key,collisionMode:valueWrapper.____slothletInternal.state.collisionMode});targetApi[key]=value;this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_REPLACE_AFTER",propKey:key,newWrapperId:resolveWrapper(targetApi[key])?.____slothletInternal.id});this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_REPLACE_VERIFY",expectedId:valueWrapper.____slothletInternal.id,actualId:resolveWrapper(targetApi[key])?.____slothletInternal.id});return true}}targetApi[key]=value;return true}if(effectiveMode==="merge"||effectiveMode==="merge-replace"){const isMergeReplace=effectiveMode==="merge-replace";if(existingIsWrapper&&valueIsWrapper2){const existingWrapper=resolveWrapper(existing);const valueWrapper=resolveWrapper(value);const existingIsLazyUnmaterialized=existingWrapper.____slothletInternal.mode==="lazy"&&!existingWrapper.____slothletInternal.state.materialized;const valueIsLazyUnmaterialized=valueWrapper.____slothletInternal.mode==="lazy"&&!valueWrapper.____slothletInternal.state.materialized;if(existingIsLazyUnmaterialized&&!valueIsLazyUnmaterialized){const valueMetadata=this.slothlet.handlers?.metadata?.getMetadata(value);const valueFilePath=valueMetadata?.filePath;if(!existingWrapper.____slothletInternal.childFilePathsPreMaterialize){existingWrapper.____slothletInternal.childFilePathsPreMaterialize={}}const valueChildKeys=Object.keys(valueWrapper).filter(k=>!k.startsWith("_")&&!k.startsWith("__"));for(const key2 of valueChildKeys){Object.defineProperty(existingWrapper,key2,{configurable:true});if(valueFilePath){existingWrapper.____slothletInternal.childFilePathsPreMaterialize[key2]=valueFilePath}}return true}else if(valueIsLazyUnmaterialized&&!existingIsLazyUnmaterialized){if(!isMergeReplace){const existingMetadata=this.slothlet.handlers?.metadata?.getMetadata(existing);const existingFilePath=existingMetadata?.filePath;if(!valueWrapper.____slothletInternal.childFilePathsPreMaterialize){valueWrapper.____slothletInternal.childFilePathsPreMaterialize={}}const existingChildKeys=Object.keys(existingWrapper).filter(k=>!k.startsWith("_")&&!k.startsWith("__"));this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_COPY_CHILD_KEYS",existingChildKeys:existingChildKeys.join(","),fromApiPath:existingWrapper.____slothletInternal.apiPath,toApiPath:valueWrapper.____slothletInternal.apiPath,valueWrapperId:valueWrapper.____slothletInternal.id||"no-id"});if(!valueWrapper.____slothletInternal.collisionMergedKeys){valueWrapper.____slothletInternal.collisionMergedKeys=new Set}for(const key2 of existingChildKeys){const child=existingWrapper[key2];this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_COPY_INDIVIDUAL_KEY",propKey:key2,childName:child?.name,typeOf:typeof child,valueWrapperId:valueWrapper.____slothletInternal.id||"no-id"});Object.defineProperty(valueWrapper,key2,{value:child,writable:false,enumerable:true,configurable:true});valueWrapper.____slothletInternal.collisionMergedKeys.add(key2);if(existingFilePath){valueWrapper.____slothletInternal.childFilePathsPreMaterialize[key2]=existingFilePath}}this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_TRIGGER_EARLY_MAT",apiPath:valueWrapper.____slothletInternal.apiPath});valueWrapper.____slothletInternal.needsImmediateChildAdoption=true;if(valueWrapper.____slothletInternal.materializeFunc&&!valueWrapper.____slothletInternal.state?.materialized&&!valueWrapper.____slothletInternal.state?.inFlight){valueWrapper._materialize().catch(err=>{new this.slothlet.SlothletWarning("WARNING_COLLISION_TRIGGER_MATERIALIZE_ERROR",{apiPath:valueWrapper.____slothletInternal.apiPath},err)})}}else{valueWrapper._mergeAfterMaterialize={existingWrapper,isMergeReplace:true}}this.slothlet.debug("api",{key:"DEBUG_MODE_COLLISION_ASSIGN_REPLACING_WITH_LAZY",propKey:key,collisionMode:valueWrapper.____slothletInternal.state.collisionMode});targetApi[key]=value;return true}const existingChildCount=Object.keys(existingWrapper).filter(k=>!k.startsWith("_")&&!k.startsWith("__")).length;const valueChildCount=Object.keys(valueWrapper).filter(k=>!k.startsWith("_")&&!k.startsWith("__")).length;if(existingWrapper.____slothletInternal.impl&&existingChildCount===0){existingWrapper.___adoptImplChildren()}if(valueWrapper.____slothletInternal.impl&&valueChildCount===0){valueWrapper.___adoptImplChildren()}const valueChildKeys2=Object.keys(valueWrapper).filter(k=>!k.startsWith("_")&&!k.startsWith("__"));for(const key2 of valueChildKeys2){const child=valueWrapper[key2];const isInternal=typeof key2==="string"&&(key2.startsWith("_")||key2.startsWith("__"));const keyExists=!isInternal&&Object.prototype.hasOwnProperty.call(existingWrapper,key2);if(!keyExists){Object.defineProperty(existingWrapper,key2,{value:child,writable:false,enumerable:true,configurable:true})}else if(isMergeReplace){const descriptor=Object.getOwnPropertyDescriptor(existingWrapper,key2);if(descriptor?.configurable){delete existingWrapper[key2]}Object.defineProperty(existingWrapper,key2,{value:child,writable:false,enumerable:true,configurable:true})}else{const existingChild=existingWrapper[key2];const existingChildWrapper=resolveWrapper(existingChild);const newChildWrapper=resolveWrapper(child);if(existingChildWrapper&&newChildWrapper){const newChildChildCount=Object.keys(newChildWrapper).filter(k=>!k.startsWith("_")&&!k.startsWith("__")).length;if(newChildWrapper.____slothletInternal.impl&&newChildChildCount===0){newChildWrapper.___adoptImplChildren()}const newChildKeys=Object.keys(newChildWrapper).filter(k=>!k.startsWith("_")&&!k.startsWith("__"));const ____existingChildKeys=Object.keys(existingChildWrapper).filter(k=>!k.startsWith("_")&&!k.startsWith("__"));for(const childKey of newChildKeys){const childKeyExists=Object.prototype.hasOwnProperty.call(existingChildWrapper,childKey);if(!childKeyExists){Object.defineProperty(existingChildWrapper,childKey,{value:newChildWrapper[childKey],writable:false,enumerable:true,configurable:true})}}}}}if(valueWrapper.____slothletInternal.mode==="lazy"&&!valueWrapper.____slothletInternal.state.materialized&&valueWrapper.____slothletInternal.materializeFunc){return false}return true}else if(existingIsWrapper&&!valueIsWrapper2){const existingWrapper=resolveWrapper(existing);const existingImpl=existingWrapper.__impl;const mergedImpl={...existingImpl||{},...value};existingWrapper.___setImpl(mergedImpl);return true}else if(!existingIsWrapper&&valueIsWrapper2){}else{if(typeof existing==="object"&&existing!==null&&typeof value==="object"&&value!==null){Object.assign(existing,value);return true}}}}if(existing!==void 0&&!allowOverwrite&&!mutateExisting&&!useCollisionDetection){return false}targetApi[key]=value;return true}async mergeApiObjects(targetApi,sourceApi,options={}){const config=options.config;if(config?.debug?.api){this.slothlet.debug("api",{key:"DEBUG_MODE_MERGE_API_OBJECTS_ENTRY",targetApiType:typeof targetApi,sourceApiType:typeof sourceApi});this.slothlet.debug("api",{key:"DEBUG_MODE_MERGE_API_OBJECTS_SOURCE_KEYS",sourceApiKeys:sourceApi?Object.keys(sourceApi):[]})}if(!sourceApi||typeof sourceApi!=="object"&&typeof sourceApi!=="function"){if(config?.debug?.api){this.slothlet.debug("api",{key:"DEBUG_MODE_MERGE_API_OBJECTS_EXIT_INVALID_SOURCE"})}return}const{removeMissing=false,moduleID=null,...assignOptions}=options;const sourceKeys=new Set(Object.keys(sourceApi));for(const key of sourceKeys){const sourceValue=sourceApi[key];const targetValue=targetApi[key];if(config?.debug?.api){this.slothlet.debug("api",{key:"DEBUG_MODE_MERGE_API_OBJECTS_PROCESSING_KEY",propKey:key,targetValueType:typeof targetValue,sourceValueType:typeof sourceValue})}if(targetValue&&typeof targetValue==="object"&&!this.isWrapperProxy(targetValue)&&sourceValue&&typeof sourceValue==="object"&&!this.isWrapperProxy(sourceValue)){if(config?.debug?.api){this.slothlet.debug("api",{key:"DEBUG_MODE_MERGE_API_OBJECTS_RECURSING",propKey:key})}await this.mergeApiObjects(targetValue,sourceValue,options)}else{if(config?.debug?.api){this.slothlet.debug("api",{key:"DEBUG_MODE_MERGE_API_OBJECTS_CALLING_ASSIGN",propKey:key})}this.assignToApiPath(targetApi,key,sourceValue,{...assignOptions,moduleID})}}if(removeMissing){for(const key of Object.keys(targetApi)){if(!sourceKeys.has(key)){delete targetApi[key]}}}}}export{ApiAssignment};