@cldmv/slothlet 2.10.0 → 3.0.0

package/dist/lib/handlers/ownership.mjs

@@ -0,0 +1,338 @@
+/*
+	Copyright 2026 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+import { resolveWrapper } from "@cldmv/slothlet/handlers/unified-wrapper";
+
+
+
+
+export class OwnershipManager extends ComponentBase {
+	static slothletProperty = "ownership";
+
+	constructor(slothlet) {
+		super(slothlet);
+		this.moduleToPath = new Map(); 
+		this.pathToModule = new Map(); 
+		this._unregisteredModules = new Set(); 
+	}
+
+	
+	register({ moduleID, apiPath, value, source = "core", collisionMode = "error", config = null, filePath = null }) {
+		
+		if (!moduleID || typeof moduleID !== "string") {
+			throw new this.SlothletError("OWNERSHIP_INVALID_MODULE_ID", { moduleID }, null, { validationError: true });
+		}
+		
+		if (apiPath !== "" && (!apiPath || typeof apiPath !== "string")) {
+			throw new this.SlothletError("OWNERSHIP_INVALID_API_PATH", { apiPath }, null, { validationError: true });
+		}
+
+		
+		
+		
+		if (this._unregisteredModules.has(moduleID)) {
+			return null;
+		}
+
+		
+		const currentOwner = this.getCurrentOwner(apiPath);
+		if (currentOwner && currentOwner.moduleID !== moduleID) {
+			
+			if (collisionMode === "merge" || collisionMode === "replace" || collisionMode === "merge-replace") {
+				
+			} else if (collisionMode === "skip") {
+				
+				return null;
+			} else if (collisionMode === "warn") {
+				
+				if (!config?.silent) {
+					new this.SlothletWarning("WARNING_OWNERSHIP_CONFLICT", {
+						apiPath,
+						existingModuleId: currentOwner.moduleID,
+						newModuleId: moduleID
+					});
+				}
+				return null;
+			} else {
+				
+				throw new this.SlothletError("OWNERSHIP_CONFLICT", {
+					apiPath,
+					existingModuleId: currentOwner.moduleID,
+					newModuleId: moduleID,
+					validationError: true
+				});
+			}
+		}
+
+		
+		if (!this.moduleToPath.has(moduleID)) {
+			this.moduleToPath.set(moduleID, new Set());
+		}
+		this.moduleToPath.get(moduleID).add(apiPath);
+
+		
+		if (!this.pathToModule.has(apiPath)) {
+			this.pathToModule.set(apiPath, []);
+		}
+
+		
+		const stack = this.pathToModule.get(apiPath);
+		const existingEntry = stack.find((entry) => entry.moduleID === moduleID);
+		if (existingEntry) {
+			
+			existingEntry.source = source;
+			existingEntry.timestamp = Date.now();
+			existingEntry.value = value;
+			if (filePath !== null) {
+				existingEntry.filePath = filePath;
+			}
+			return existingEntry;
+		}
+
+		const entry = {
+			moduleID,
+			source,
+			timestamp: Date.now(),
+			value,
+			filePath
+		};
+
+		this.pathToModule.get(apiPath).push(entry);
+
+		return entry;
+	}
+
+	
+	unregister(moduleID) {
+		const paths = this.moduleToPath.get(moduleID);
+		if (!paths) {
+			return { removed: [], rolledBack: [] };
+		}
+
+		
+		
+		this._unregisteredModules.add(moduleID);
+
+		const removed = [];
+		const rolledBack = [];
+
+		for (const apiPath of paths) {
+			const result = this.removePath(apiPath, moduleID);
+
+			if (result.action === "delete") {
+				removed.push(apiPath);
+			} else if (result.action === "restore") {
+				rolledBack.push({
+					apiPath,
+					restoredTo: result.restoreModuleId
+				});
+			}
+		}
+
+		this.moduleToPath.delete(moduleID);
+
+		return { removed, rolledBack };
+	}
+
+	
+	removePath(apiPath, moduleID = null) {
+		const stack = this.pathToModule.get(apiPath);
+		if (!stack) {
+			return { action: "none", removedModuleId: null, restoreModuleId: null };
+		}
+
+		
+		const index = moduleID ? stack.findIndex((entry) => entry.moduleID === moduleID) : stack.length - 1;
+		if (index === -1) {
+			return { action: "none", removedModuleId: null, restoreModuleId: null };
+		}
+		const [removed] = stack.splice(index, 1);
+		const removedModuleId = removed.moduleID;
+		if (removedModuleId && this.moduleToPath.has(removedModuleId)) {
+			const pathSet = this.moduleToPath.get(removedModuleId);
+			pathSet.delete(apiPath);
+			if (pathSet.size === 0) {
+				this.moduleToPath.delete(removedModuleId);
+			}
+		}
+
+		
+		if (stack.length === 0) {
+			this.pathToModule.delete(apiPath);
+			return { action: "delete", removedModuleId, restoreModuleId: null };
+		}
+
+		
+		const previous = stack[stack.length - 1];
+		return {
+			action: "restore",
+			removedModuleId,
+			restoreModuleId: previous.moduleID
+		};
+	}
+
+	
+	getCurrentOwner(apiPath) {
+		const stack = this.pathToModule.get(apiPath);
+		if (!stack || stack.length === 0) return null;
+		return stack[stack.length - 1];
+	}
+
+	
+	getCurrentValue(apiPath) {
+		const owner = this.getCurrentOwner(apiPath);
+		if (!owner) return undefined;
+
+		const value = owner.value;
+
+		
+		
+		
+		const rawWrapper = resolveWrapper(value);
+		if (rawWrapper) {
+			return rawWrapper.__impl;
+		}
+
+		return value;
+	}
+
+	
+	getModulePaths(moduleID) {
+		return Array.from(this.moduleToPath.get(moduleID) || []);
+	}
+
+	
+	getPathHistory(apiPath) {
+		return this.pathToModule.get(apiPath) || [];
+	}
+
+	
+	ownsPath(moduleID, apiPath) {
+		const owner = this.getCurrentOwner(apiPath);
+		return owner && owner.moduleID === moduleID;
+	}
+
+	
+	getDiagnostics() {
+		return {
+			totalModules: this.moduleToPath.size,
+			totalPaths: this.pathToModule.size,
+			modules: Array.from(this.moduleToPath.entries()).map(([id, paths]) => ({
+				moduleID: id,
+				pathCount: paths.size
+			})),
+			conflictedPaths: Array.from(this.pathToModule.entries())
+				.filter(([_, stack]) => stack.length > 1)
+				.map(([path, stack]) => ({
+					apiPath: path,
+					ownerStack: stack.map((e) => e.moduleID)
+				}))
+		};
+	}
+
+	
+	getPathOwnership(apiPath) {
+		const stack = this.pathToModule.get(apiPath);
+		if (!stack || stack.length === 0) {
+			return null;
+		}
+		return new Set(stack.map((entry) => entry.moduleID));
+	}
+
+	
+	registerSubtree(api, moduleID, path, visited = new WeakSet()) {
+		if (!api || typeof api !== "object") return;
+
+		
+		if (visited.has(api)) {
+			return;
+		}
+		visited.add(api);
+
+		
+		if (path) {
+			this.register({
+				moduleID,
+				apiPath: path,
+				value: api,
+				source: "core",
+				collisionMode: "merge",
+				filePath: null
+			});
+		}
+
+		
+		for (const [key, value] of Object.entries(api)) {
+			
+			const skipProps = ["__metadata", "__type", "_materialize", "_impl", "____slothletInternal"];
+			if (skipProps.includes(key)) {
+				continue;
+			}
+
+			const childPath = path ? `${path}.${key}` : key;
+			if (typeof value === "function" || (value && typeof value === "object")) {
+				this.register({
+					moduleID,
+					apiPath: childPath,
+					value,
+					source: "core",
+					collisionMode: "merge",
+					filePath: null
+				});
+
+				
+				if (typeof value === "object" && !Array.isArray(value)) {
+					this.registerSubtree(value, moduleID, childPath, visited);
+				}
+			}
+		}
+	}
+
+	
+	clear() {
+		this.moduleToPath.clear();
+		this.pathToModule.clear();
+		this._unregisteredModules.clear();
+	}
+
+	
+	exportState() {
+		return {
+			moduleToPath: Array.from(this.moduleToPath.entries()).map(([id, paths]) => [id, Array.from(paths)]),
+			pathToModule: Array.from(this.pathToModule.entries())
+		};
+	}
+
+	
+	importState(state) {
+		
+		this.clear();
+
+		
+		for (const [id, paths] of state.moduleToPath) {
+			this.moduleToPath.set(id, new Set(paths));
+		}
+
+		
+		for (const [path, stack] of state.pathToModule) {
+			this.pathToModule.set(path, stack);
+		}
+	}
+}