@cldmv/slothlet 3.1.0 → 3.2.1

package/AGENT-USAGE.md

@@ -409,6 +409,34 @@ export const secureOperation = {
 
 ---
 
+## 🌍 Environment Snapshot (v3.1+)
+
+Slothlet captures a **frozen snapshot of `process.env` at init time** and exposes it at `api.slothlet.env`. The snapshot is deeply read-only — mutating `process.env` after init does not affect `api.slothlet.env`.
+
+```js
+const api = await slothlet({
+	dir: "./api",
+	env: true,
+	// env: { include: ["NODE_ENV", "DATABASE_URL", "PORT"] }  // allowlist
+});
+
+// Access inside any module:
+import { self } from "@cldmv/slothlet/runtime";
+
+export const getConfig = () => ({
+	mode: self.slothlet.env.NODE_ENV,
+	dbUrl: self.slothlet.env.DATABASE_URL
+});
+```
+
+**Key behaviors:**
+- `env: true` → all `process.env` variables are captured
+- `env: { include: [...] }` → only the listed keys are captured (recommended for security)
+- `api.slothlet.env` is a frozen object — writes throw in strict mode
+- Snapshot is taken at init time — late `process.env` mutations are NOT reflected
+
+---
+
 ## 🔁 Hot Reload / Dynamic API Management
 
 ```js
@@ -457,6 +485,69 @@ api.slothlet.lifecycle.off("materialized:complete", handler);
 
 ---
 
+## 🔀 API Path Versioning (v3.2+)
+
+Mount multiple versions of the same logical path and dispatch to the correct version automatically based on the caller's version metadata.
+
+### Setup
+
+```js
+const api = await slothlet({
+	dir: "./api",
+	versionDispatcher: "version"  // use caller's versionMetadata.version field
+	// versionDispatcher: (allVersions, caller) => { ... }  // custom function
+});
+
+// Register versioned modules — 4th argument is versionConfig
+await api.slothlet.api.add("auth", "./api/v1", {}, { version: "v1", default: true });
+await api.slothlet.api.add("auth", "./api/v2", {}, { version: "v2" });
+```
+
+### Access Patterns
+
+```js
+// Dispatcher — routes via discriminator (use this in most cases)
+api.auth.login(user, pass)        // → routes to v1 or v2 based on caller metadata
+
+// Direct versioned access — bypasses dispatcher entirely
+api.v1.auth.login(user, pass)     // → always v1
+api.v2.auth.login(user, pass)     // → always v2
+```
+
+### Attaching Version Metadata to a Caller
+
+```js
+// Register a module WITH a version tag so the discriminator can use it
+await api.slothlet.api.add("services/payments", "./payments", {}, {
+	version: "v2",
+	metadata: { stable: true }    // versionConfig.metadata — stored in VersionManager only
+});
+
+// options.metadata (3rd arg)     → regular Metadata system (metadata.caller() etc.)
+// versionConfig.metadata (4th arg) → version-system only, used by the discriminator
+```
+
+### Runtime Version Management
+
+```js
+// List registered versions for a path
+api.slothlet.versioning.list("auth");
+// → { versions: { v1: { ... }, v2: { ... } }, default: "v2" }
+
+// Change the default dispatcher fallback
+api.slothlet.versioning.setDefault("auth", "v1");
+
+// Unregister a version (removes api.v1.auth; dispatcher updates automatically)
+await api.slothlet.versioning.unregister("auth", "v1");
+
+// Read version metadata stored at registration
+api.slothlet.versioning.getVersionMetadata(moduleID);
+```
+
+> 📖 See [`docs/VERSIONING.md`](docs/VERSIONING.md) for full documentation.
+
+---
+
 ## 📁 File Organization Best Practices
 
 ### ✅ Clean Folder Structure
@@ -550,6 +641,41 @@ api.slothlet.lifecycle.on("materialized:complete", handler);
 api.slothlet.lifecycle.off("materialized:complete", handler);
 ```
 
+### ❌ Mistake 6: Assuming `api.v1.auth` Goes Through the Dispatcher
+
+```js
+// ❌ WRONG — direct versioned path bypasses the discriminator entirely
+api.v1.auth.login(user, pass);   // always v1, no routing logic
+
+// ✅ CORRECT — use the logical dispatcher path for dynamic routing
+api.auth.login(user, pass);      // routes based on caller version metadata
+```
+
+### ❌ Mistake 7: Wrong Config Key for Versioning
+
+```js
+// ❌ WRONG
+const api = await slothlet({ dir: "./api", versionResolver: "version" });
+
+// ✅ CORRECT
+const api = await slothlet({ dir: "./api", versionDispatcher: "version" });
+```
+
+### ❌ Mistake 8: Conflating versionConfig.metadata with options.metadata
+
+```js
+// ❌ WRONG — puts version tag in the regular Metadata system instead of VersionManager
+await api.slothlet.api.add("auth", "./v2", { metadata: { version: "v2" } });
+
+// ✅ CORRECT
+// options.metadata (3rd arg)       → regular Metadata system (metadata.caller() etc.)
+// versionConfig.metadata (4th arg) → VersionManager only, used by the discriminator
+await api.slothlet.api.add("auth", "./v2",
+	{ metadata: { role: "core" } },
+	{ version: "v2", metadata: { stable: true } }
+);
+```
+
 ---
 
 ## ✅ AI Agent Checklist
@@ -563,6 +689,9 @@ api.slothlet.lifecycle.off("materialized:complete", handler);
 - [ ] **Lifecycle** uses `api.slothlet.lifecycle.on/off()` only
 - [ ] **Lazy mode**: if using background materialization, use `api.slothlet.materialize.wait()` before accessing the API
 - [ ] **Hook subsets**: auth/security → `subset: "before"`, main logic → `"primary"`, audit → `"after"`
+- [ ] **Versioning config key is `versionDispatcher:`**, not `versionResolver:` or `versionDiscriminator:`
+- [ ] **Use `api.auth` (dispatcher path) for dynamic routing**, not `api.v1.auth` (direct path bypasses discriminator)
+- [ ] **`versionConfig.metadata` (4th arg)** and **`options.metadata` (3rd arg)** are separate systems — don't conflate them
 - [ ] **Double quotes everywhere** - follow Slothlet coding standards
 
 ---

package/README.md

@@ -16,7 +16,7 @@ The name might suggest we're taking it easy, but don't be fooled. **Slothlet del
 
 > _Where sophisticated architecture meets blazing performance - slothlet is anything but slow._
 
-[![npm version]][npm_version_url] [![npm downloads]][npm_downloads_url] <!-- [![GitHub release]][github_release_url] -->[![GitHub downloads]][github_downloads_url] [![Last commit]][last_commit_url] <!-- [![Release date]][release_date_url] -->[![npm last update]][npm_last_update_url]
+[![npm version]][npm_version_url] [![npm downloads]][npm_downloads_url] <!-- [![GitHub release]][github_release_url] -->[![GitHub downloads]][github_downloads_url] [![Last commit]][last_commit_url] <!-- [![Release date]][release_date_url] -->[![npm last update]][npm_last_update_url] [![coverage]][coverage_url]
 
 > [!NOTE]
 > **🚀 Production Ready Modes:**
@@ -55,20 +55,19 @@ Every feature has been hardened with a comprehensive test suite - over **5,300 t
 
 ## ✨ What's New
 
-### Latest: v3.1.0 (March 2026)
+### Latest: v3.2.1 (April 2026)
 
-- **Environment Snapshot** — `api.slothlet.env` exposes a frozen copy of `process.env` captured at initialization time; every module accesses it via `self.slothlet.env`
-- **`env.include` Allowlist** — restrict the snapshot to specific keys with `env: { include: ["NODE_ENV", "PORT"] }`; empty array falls back to full snapshot
-- **Reload Immunity** — snapshot is captured once on first `load()` and never replaced on subsequent `api.slothlet.reload()` calls (including partial `api.slothlet.api.reload()` calls)
-- [View full v3.1.0 Changelog](./docs/changelog/v3/v3.1.0.md)
+- **Missing `defineProperty` trap** — the version dispatcher proxy introduced in v3.2.0 had no `defineProperty` trap; calls fell through to the raw target, bypassing version routing, and non-configurable writes could trigger V8 proxy invariant `TypeError` on subsequent reads
+- **Pre-commit tooling** — removed duplicate `build:cleanup` step from `precommit-validation.mjs`; sequence is now `build:dev → debug → test:node → vitest`
+- [View full v3.2.1 Changelog](./docs/changelog/v3/v3.2.1.md)
 
 ### Recent Releases
 
+- **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))
+- **v3.1.0** (March 2026) — Frozen `api.slothlet.env` snapshot; `env.include` allowlist; reload immunity ([Changelog](./docs/changelog/v3/v3.1.0.md))
 - **v3.0.1** (March 2026) — Resolver fix for user `index.mjs` mis-classified as internal; CI `slothlet-dev` stripping hardening; respawn race fix; resilient `build:dist` script ([Changelog](./docs/changelog/v3/v3.0.1.md))
 - **v3.0.0** (February 2026) — Unified Wrapper architecture, redesigned hook system, full i18n, background materialization, lifecycle events, collision modes, mutation controls ([Changelog](./docs/changelog/v3.0.md))
-- **v2.11.0** — AddApi Special File Pattern (Rule 11), smart flattening enhancements ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.11.md))
-- **v2.10.0** — Function metadata tagging and introspection capabilities ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.10.md))
-- **v2.9** — Per-Request Context Isolation ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.9.md))
+
 
 📚 **For complete version history and detailed release notes, see [docs/changelog/](./docs/changelog/) folder.**
 
@@ -327,6 +326,7 @@ await api.slothlet.api.reload("database.*");
 | `backgroundMaterialize`   | `boolean` | `false`       | In lazy mode: start background pre-loading of all modules immediately after init; automatically enables materialization tracking and the `materialized:complete` lifecycle event                              |
 | `api.collision`           | `mixed`   | `"merge"`     | Collision mode for API namespace conflicts: `"merge"`, `"skip"`, `"overwrite"`, `"throw"` - or `{ initial: "merge", api: "skip" }` to set independently for load vs runtime `add()`                          |
 | `api.mutations`           | `object`  | all `true`    | Per-operation mutation controls: `{ add: true, remove: true, reload: true }` - set any to `false` to disable                                                                                                 |
+| `versionDispatcher`       | `mixed`   | `undefined`   | Version routing discriminator: `"version"` (or any string key) looks up that key in the caller's version metadata; a function receives `(allVersions, caller)` and returns a tag or `null`; `undefined` behaves like `"version"` |
 | `i18n`                    | `object`  | `{}`          | Internationalization settings: `{ language: "en" }` - supported: `en`, `es`, `fr`, `de`, `pt`, `it`, `ja`, `zh`, `ko`                                                                                       |
 
 ---
@@ -1035,6 +1035,8 @@ To my wife and children - thank you for your patience, your encouragement, and t
 [github_license_url]: https://github.com/CLDMV/slothlet/blob/HEAD/LICENSE
 [npm license]: https://img.shields.io/npm/l/%40cldmv%2Fslothlet.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
 [npm_license_url]: https://www.npmjs.com/package/@cldmv/slothlet
+[coverage]: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FCLDMV%2Fslothlet%2Fbadges%2Fcoverage.json&style=for-the-badge&logo=vitest&logoColor=white
+[coverage_url]: https://github.com/CLDMV/slothlet/blob/badges/coverage.json
 [contributors]: https://img.shields.io/github/contributors/CLDMV/slothlet.svg?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
 [contributors_url]: https://github.com/CLDMV/slothlet/graphs/contributors
 [sponsor shinrai]: https://img.shields.io/github/sponsors/shinrai?style=for-the-badge&logo=githubsponsors&logoColor=white&labelColor=EA4AAA&label=Sponsor

package/dist/lib/builders/api_builder.mjs

@@ -30,7 +30,14 @@ function _resolvePathOrModuleId(slothlet, pathOrModuleId) {
 	
 	
 	if (history) {
-		const match = history.findLast((entry) => entry.moduleID === pathOrModuleId);
+		let match = null;
+		for (let i = history.length - 1; i >= 0; i--) {
+			const entry = history[i];
+			if (entry?.moduleID === pathOrModuleId) {
+				match = entry;
+				break;
+			}
+		}
 		if (match) return match.apiPath;
 	}
 	return pathOrModuleId;
@@ -186,7 +193,7 @@ export class ApiBuilder extends ComponentBase {
 			
 			api: {
 				
-				add: async function slothlet_api_add(apiPath, folderPath, options = {}) {
+				add: async function slothlet_api_add(apiPath, folderPath, options = {}, versionConfig = null) {
 					
 					if (!config.api?.mutations?.add) {
 						throw new slothlet.SlothletError("INVALID_CONFIG_MUTATIONS_DISABLED", {
@@ -208,7 +215,8 @@ export class ApiBuilder extends ComponentBase {
 					return slothlet.handlers.apiManager.addApiComponent({
 						apiPath,
 						folderPath,
-						options: filteredOptions
+						options: filteredOptions,
+						versionConfig: versionConfig || null
 					});
 				},
 
@@ -568,6 +576,39 @@ export class ApiBuilder extends ComponentBase {
 					if (!slothlet.handlers?.metadata) return;
 					const resolvedPath = _resolvePathOrModuleId(slothlet, pathOrModuleId);
 					return slothlet.handlers.metadata.removePathMetadata(resolvedPath, key);
+				},
+
+				
+				setForVersion: function slothlet_metadata_setForVersion(logicalPath, versionTag, keyOrObj, value) {
+					if (!slothlet.handlers?.metadata) {
+						throw new slothlet.SlothletError("METADATA_NOT_AVAILABLE", {
+							handlersKeys: slothlet.handlers
+								? Object.keys(slothlet.handlers).join(", ")
+								: "undefined",
+							validationError: true
+						});
+					}
+					const info = slothlet.handlers?.versionManager?.list(logicalPath);
+					if (!info || !info.versions?.[versionTag]) {
+						throw new slothlet.SlothletError("VERSION_NOT_FOUND", {
+							version: versionTag,
+							apiPath: logicalPath
+						});
+					}
+					const { moduleID } = info.versions[versionTag];
+					const resolvedPath = _resolvePathOrModuleId(slothlet, moduleID);
+					return slothlet.handlers.metadata.setPathMetadata(resolvedPath, keyOrObj, value);
+				},
+
+				
+				getForVersion: function slothlet_metadata_getForVersion(logicalPath, versionTag) {
+					
+					if (!slothlet.handlers?.metadata) return {};
+					const info = slothlet.handlers?.versionManager?.list(logicalPath);
+					if (!info || !info.versions?.[versionTag]) return {};
+					const { moduleID } = info.versions[versionTag];
+					const resolvedPath = _resolvePathOrModuleId(slothlet, moduleID);
+					return slothlet.handlers.metadata.getPathMetadata(resolvedPath);
 				}
 			},
 
@@ -639,7 +680,61 @@ export class ApiBuilder extends ComponentBase {
 			})(),
 
 			
-			env: slothlet.envSnapshot
+			env: slothlet.envSnapshot,
+
+			
+			versioning: {
+				
+				list: function slothlet_version_list(logicalPath) {
+					
+					
+					if (!slothlet.handlers?.versionManager) return undefined;
+					return slothlet.handlers.versionManager.list(logicalPath);
+				},
+
+				
+				setDefault: function slothlet_version_setDefault(logicalPath, versionTag) {
+					
+					
+					if (!slothlet.handlers?.versionManager) return;
+					return slothlet.handlers.versionManager.setDefault(logicalPath, versionTag);
+				},
+
+				
+				unregister: async function slothlet_version_unregister(logicalPath, versionTag) {
+					
+					
+					if (!slothlet.handlers?.versionManager) return false;
+					
+					const info = slothlet.handlers.versionManager.list(logicalPath);
+					if (!info || !info.versions?.[versionTag]) return false;
+					
+					
+					
+					const { moduleID: versionedModuleID } = info.versions[versionTag];
+					
+					
+					
+					await slothlet.handlers.apiManager.removeApiComponent(versionedModuleID);
+					return true;
+				},
+
+				
+				getVersionMetadata: function slothlet_version_getVersionMetadata(logicalPath, versionTag) {
+					
+					
+					if (!slothlet.handlers?.versionManager) return undefined;
+					return slothlet.handlers.versionManager.getVersionMetadataByPath(logicalPath, versionTag);
+				},
+
+				
+				setVersionMetadata: function slothlet_version_setVersionMetadata(logicalPath, versionTag, patch) {
+					
+					
+					if (!slothlet.handlers?.versionManager) return;
+					return slothlet.handlers.versionManager.setVersionMetadataByPath(logicalPath, versionTag, patch);
+				}
+			}
 		};
 
 		

package/dist/lib/handlers/api-manager.mjs

@@ -863,7 +863,7 @@ export class ApiManager extends ComponentBase {
 	async addApiComponent(params) {
 		
 		
-		const { apiPath, folderPath, options = {} } = params || {};
+		const { apiPath, folderPath, options = {}, versionConfig = null } = params || {};
 
 		
 		if (Array.isArray(folderPath)) {
@@ -872,7 +872,8 @@ export class ApiManager extends ComponentBase {
 				const moduleID = await this.addApiComponent({
 					apiPath,
 					folderPath: singlePath,
-					options
+					options,
+					versionConfig
 				});
 				moduleIDs.push(moduleID);
 			}
@@ -890,6 +891,37 @@ export class ApiManager extends ComponentBase {
 		const { apiPath: normalizedPath, parts } = this.normalizeApiPath(apiPath);
 
 		
+		let effectivePath = normalizedPath;
+		let effectiveParts = parts;
+		if (versionConfig?.version !== undefined && versionConfig?.version !== null) {
+			
+			
+			
+			if (normalizedPath === "") {
+				throw new this.SlothletError("INVALID_CONFIG_API_PATH_INVALID", {
+					apiPath,
+					reason: translate("API_PATH_REASON_VERSIONED_ROOT"),
+					index: undefined,
+					segment: undefined,
+					validationError: true
+				});
+			}
+			if (typeof versionConfig.version !== "string" || !String(versionConfig.version).trim()) {
+				throw new this.SlothletError("INVALID_CONFIG_VERSION_TAG", {
+					received: versionConfig.version,
+					validationError: true
+				});
+			}
+			const versionTag = String(versionConfig.version).trim();
+			
+			
+			
+			
+			effectiveParts = [versionTag, ...parts];
+			effectivePath = effectiveParts.join(".");
+		}
+
+		
 		const { resolvedPath, isDirectory, isFile } = await this.resolvePath(folderPath);
 
 		
@@ -959,7 +991,8 @@ export class ApiManager extends ComponentBase {
 			
 			
 			
-			apiPathPrefix: normalizedPath,
+			
+			apiPathPrefix: effectivePath,
 			collisionContext: "addApi",
 			moduleID: moduleID,
 			
@@ -973,7 +1006,7 @@ export class ApiManager extends ComponentBase {
 		
 		if (this.slothlet.handlers.apiCacheManager) {
 			this.slothlet.handlers.apiCacheManager.set(moduleID, {
-				endpoint: normalizedPath,
+				endpoint: effectivePath,
 				moduleID: moduleID,
 				api: newApi,
 				folderPath: resolvedFolderPath,
@@ -1141,7 +1174,7 @@ export class ApiManager extends ComponentBase {
 				const isCallableNamespace = typeof apiToMerge === "function";
 
 				const containerWrapper = new UnifiedWrapper(this.slothlet, {
-					apiPath: normalizedPath,
+					apiPath: effectivePath,
 					mode: this.____config.mode,
 					isCallable: isCallableNamespace, 
 					moduleID: moduleID,
@@ -1154,14 +1187,14 @@ export class ApiManager extends ComponentBase {
 				apiToMerge = containerWrapper.createProxy();
 			}
 
-			const result1 = await this.setValueAtPath(this.slothlet.api, parts, apiToMerge, {
+			const result1 = await this.setValueAtPath(this.slothlet.api, effectiveParts, apiToMerge, {
 				mutateExisting,
 				collisionMode,
 				moduleID, 
 				sourceFolder: resolvedFolderPath 
 			});
 
-			const result2 = await this.setValueAtPath(this.slothlet.boundApi, parts, apiToMerge, {
+			const result2 = await this.setValueAtPath(this.slothlet.boundApi, effectiveParts, apiToMerge, {
 				mutateExisting,
 				collisionMode,
 				moduleID, 
@@ -1187,6 +1220,11 @@ export class ApiManager extends ComponentBase {
 			
 			const collectPendingMaterializations = (obj, depth = 0) => {
 				if (!obj || typeof obj !== "object" || depth > 10) return;
+				
+				
+				
+				
+				if (obj.__isVersionDispatcher === true) return;
 
 				const wrapper = resolveWrapper(obj);
 				if (wrapper) {
@@ -1220,7 +1258,9 @@ export class ApiManager extends ComponentBase {
 
 			
 			
-			if (parts.length === 0) {
+			
+			
+			if (effectiveParts.length === 0) {
 				
 				for (const key of Object.keys(newApi)) {
 					
@@ -1232,7 +1272,7 @@ export class ApiManager extends ComponentBase {
 			} else {
 				
 				let current = this.slothlet.api;
-				for (const part of parts) {
+				for (const part of effectiveParts) {
 					
 					
 					if (current && current[part]) {
@@ -1277,7 +1317,11 @@ export class ApiManager extends ComponentBase {
 					this.slothlet.handlers.metadata.registerUserMetadata(key, metadata);
 				}
 			} else {
-				const rootSegment = normalizedPath.split(".")[0];
+				
+				
+				
+				
+				const rootSegment = effectiveParts[0];
 				this.slothlet.handlers.metadata.registerUserMetadata(rootSegment, metadata);
 			}
 		}
@@ -1285,8 +1329,10 @@ export class ApiManager extends ComponentBase {
 		
 		
 		
+		
+		
 		if (this.slothlet.handlers.ownership && moduleID) {
-			this.slothlet.handlers.ownership.registerSubtree(apiToMerge, moduleID, normalizedPath);
+			this.slothlet.handlers.ownership.registerSubtree(apiToMerge, moduleID, effectivePath);
 		}
 
 		
@@ -1297,24 +1343,83 @@ export class ApiManager extends ComponentBase {
 					apiPath: normalizedPath,
 					folderPath: resolvedFolderPath,
 					options: { ...restOptions, metadata, moduleID },
-					moduleID
+					moduleID,
+					versionConfig: versionConfig || null
 				});
 
 				
+				
 				this.state.operationHistory.push({
 					type: "add",
 					apiPath: normalizedPath,
 					folderPath: resolvedFolderPath,
 					options: { ...restOptions, metadata, moduleID },
-					moduleID
+					moduleID,
+					versionConfig: versionConfig || null
 				});
 			}
 		}
 
+		
+		
+		
+		
+		if (versionConfig?.version && this.slothlet.handlers.versionManager) {
+			const versionTag = String(versionConfig.version).trim();
+			try {
+				this.slothlet.handlers.versionManager.registerVersion(
+					normalizedPath,
+					versionTag,
+					moduleID,
+					versionConfig.metadata ?? {},
+					versionConfig.default ?? false
+				);
+			} catch (error) {
+				await this._rollbackFailedVersionedAdd({ moduleID, effectivePath, normalizedPath });
+				throw error;
+			}
+		}
+
 		return moduleID;
 	}
 
 	
+	async _rollbackFailedVersionedAdd({ moduleID, effectivePath, normalizedPath }) {
+		
+		
+		
+		
+		
+		let addIndex = -1;
+		for (let i = this.state.operationHistory.length - 1; i >= 0; i--) {
+			const entry = this.state.operationHistory[i];
+			if (entry?.type === "add" && entry?.apiPath === normalizedPath && entry?.moduleID === moduleID) {
+				addIndex = i;
+				break;
+			}
+		}
+		if (addIndex !== -1) {
+			this.state.operationHistory.splice(addIndex, 1);
+		}
+
+		
+		
+		
+		
+		this.state.addHistory = this.state.addHistory.filter((entry) => entry?.moduleID !== moduleID);
+
+		
+		
+		
+		try {
+			await this.removeApiComponent(moduleID || effectivePath, { recordHistory: false });
+		} catch {
+			
+			
+		}
+	}
+
+	
 	async removeApiComponent(pathOrModuleId, options = {}) {
 		const recordHistory = options.recordHistory !== false;
 		if (typeof pathOrModuleId !== "string" || !pathOrModuleId) {
@@ -1340,7 +1445,14 @@ export class ApiManager extends ComponentBase {
 			
 			
 			const registeredModules = Array.from(this.slothlet.handlers.ownership.moduleToPath.keys());
-			const matchingModule = registeredModules.findLast((m) => m === candidateModuleID || m.startsWith(`${candidateModuleID}_`));
+			let matchingModule = null;
+			for (let i = registeredModules.length - 1; i >= 0; i--) {
+				const candidate = registeredModules[i];
+				if (candidate === candidateModuleID || candidate.startsWith(`${candidateModuleID}_`)) {
+					matchingModule = candidate;
+					break;
+				}
+			}
 
 			if (matchingModule) {
 				
@@ -1395,6 +1507,19 @@ export class ApiManager extends ComponentBase {
 					this.slothlet.handlers.metadata.removeUserMetadataByApiPath(rootSegment);
 				}
 				
+				if (this.slothlet.handlers.versionManager) {
+					const versionKey = this.slothlet.handlers.versionManager.getVersionKeyForModule(moduleIDKey);
+					if (versionKey) {
+						this.slothlet.handlers.versionManager.unregisterVersion(versionKey.logicalPath, versionKey.versionTag);
+					}
+					
+					
+					
+					if (this.slothlet.handlers.versionManager.hasDispatcher(normalizedPath)) {
+						this.slothlet.handlers.versionManager.teardownDispatcher(normalizedPath);
+					}
+				}
+				
 				this.state.operationHistory.push({
 					type: "remove",
 					apiPath: normalizedPath
@@ -1451,6 +1576,16 @@ export class ApiManager extends ComponentBase {
 			const result = this.slothlet.handlers.ownership?.unregister?.(moduleIDKey) || { removed: [], rolledBack: [] };
 
 			
+			
+			
+			if (this.slothlet.handlers.versionManager) {
+				const versionKey = this.slothlet.handlers.versionManager.getVersionKeyForModule(moduleIDKey);
+				if (versionKey) {
+					this.slothlet.handlers.versionManager.unregisterVersion(versionKey.logicalPath, versionKey.versionTag);
+				}
+			}
+
+			
 			const allPaths = [...result.removed, ...result.rolledBack.map((r) => r.apiPath)];
 
 			
@@ -1780,6 +1915,11 @@ export class ApiManager extends ComponentBase {
 			key: "DEBUG_MODE_MODULE_RELOAD_COMPLETE",
 			moduleID
 		});
+
+		
+		if (this.slothlet.handlers.versionManager) {
+			this.slothlet.handlers.versionManager.onVersionedModuleReload(moduleID);
+		}
 	}
 
 	
@@ -2268,6 +2408,31 @@ export class ApiManager extends ComponentBase {
 				
 				
 				
+				if (parts.length > 0 && implForReload && typeof implForReload === "object") {
+					const lastEndpointPart = parts[parts.length - 1];
+					if (lastEndpointPart && Object.prototype.hasOwnProperty.call(implForReload, lastEndpointPart)) {
+						const dupValue = implForReload[lastEndpointPart];
+						const dupWrapperForDedup = resolveWrapper(dupValue);
+						if (dupWrapperForDedup) {
+							const hoisted = {};
+							for (const k of Object.keys(implForReload)) {
+								if (k !== lastEndpointPart) hoisted[k] = implForReload[k];
+							}
+							for (const k of Object.keys(dupWrapperForDedup).filter((k) => !k.startsWith("_") && !k.startsWith("__"))) {
+								hoisted[k] = dupWrapperForDedup[k];
+							}
+							implForReload = hoisted;
+						}
+					}
+				}
+
+				
+				
+				
+				
+				
+				
+				
 				
 				if (implForReload && typeof implForReload === "object") {
 					for (const key of Object.keys(implForReload)) {