@cldmv/slothlet-types 3.15.3 → 3.16.0

package/lib/handlers/api-manager.d.mts

@@ -1,49 +1,550 @@
+/**
+ * Manages runtime API component lifecycle (add/remove/reload).
+ * @class ApiManager
+ * @extends ComponentBase
+ * @package
+ *
+ * @description
+ * Class-based handler for managing API components at runtime. Tracks add history,
+ * removed module IDs, and initial configuration per instance. Extends ComponentBase
+ * for common Slothlet property access (config, debug, api, error classes, etc.).
+ *
+ * @example
+ * const manager = new ApiManager(slothlet);
+ * await manager.addApiComponent({ apiPath: "plugins", folderPath: "./plugins" });
+ */
 export class ApiManager extends ComponentBase {
     static slothletProperty: string;
+    /**
+     * Create an ApiManager instance.
+     * @param {object} slothlet - Slothlet class instance.
+     * @package
+     *
+     * @description
+     * Initializes manager state with empty add history, removed module tracking,
+     * and stores the initial configuration.
+     *
+     * @example
+     * const manager = new ApiManager(slothlet);
+     */
+    constructor(slothlet: object);
+    /** @type {{ addHistory: object[], initialConfig: object|null, operationHistory: object[], replaceShadows: Map<string, object[]> }} */
     state: {
-        addHistory: never[];
-        initialConfig: any;
-        operationHistory: never[];
-        replaceShadows: Map<any, any>;
+        addHistory: object[];
+        initialConfig: object | null;
+        operationHistory: object[];
+        replaceShadows: Map<string, object[]>;
     };
-    normalizeApiPath(apiPath: any): {
+    /**
+     * Normalize and validate an API path.
+     * @param {string|string[]} apiPath - Dot-delimited API path, array of path segments, or empty/null for root.
+     * @returns {{ apiPath: string, parts: string[] }} Normalized path data.
+     * @throws {SlothletError} When apiPath is invalid.
+     * @private
+     *
+     * @description
+     * Ensures the API path is valid. Accepts:
+     * - String: "some.path" → parts: ["some", "path"]
+     * - Array: ["some", "path"] → parts: ["some", "path"]
+     * - Empty string, null, or undefined → root level (parts: [])
+     * Non-empty paths must contain no empty segments.
+     *
+     * @example
+     * const { apiPath, parts } = this.normalizeApiPath("plugins.tools");
+     * const { apiPath, parts } = this.normalizeApiPath(["plugins", "tools"]);
+     * const { apiPath, parts } = this.normalizeApiPath(""); // Root level: parts = []
+     */
+    private normalizeApiPath;
+    /**
+     * Resolve and validate a path (file or directory) from caller context.
+     * @param {string} inputPath - File or folder path provided by caller.
+     * @returns {Promise<{resolvedPath: string, isDirectory: boolean, isFile: boolean}>} Path info.
+     * @throws {SlothletError} When the path does not exist.
+     * @private
+     *
+     * @description
+     * Resolves relative paths from the caller and verifies the path exists.
+     * Supports both files (.mjs, .cjs, .js) and directories.
+     *
+     * @example
+     * const { resolvedPath, isDirectory, isFile } = await this.resolvePath("./plugins");
+     * const { resolvedPath, isDirectory, isFile } = await this.resolvePath("./module.mjs");
+     */
+    private resolvePath;
+    /**
+     * Resolve and validate a folder path from caller context.
+     * @param {string} folderPath - Folder path provided by caller.
+     * @returns {Promise<string>} Absolute folder path.
+     * @throws {SlothletError} When the folder does not exist or is not a directory.
+     * @private
+     *
+     * @description
+     * Resolves relative paths from the caller and verifies the folder exists.
+     *
+     * @deprecated Use resolvePath() instead for file/directory support.
+     *
+     * @example
+     * const resolved = await this.resolveFolderPath("./plugins");
+     */
+    private resolveFolderPath;
+    /**
+     * Build a default moduleID when none is provided.
+     * @param {string} apiPath - API path for this module.
+     * @param {string} resolvedFolderPath - Absolute folder path.
+     * @returns {string} Stable module identifier.
+     * @private
+     *
+     * @description
+     * Generates a stable moduleID using the apiPath and resolved folder path.
+     *
+     * @example
+     * const moduleID = this.buildDefaultModuleId("plugins", "/abs/path/plugins");
+     */
+    private buildDefaultModuleId;
+    /**
+     * Read the current value at an API path.
+     * @param {function|object} root - API root object.
+     * @param {string[]} parts - Path segments.
+     * @returns {unknown} Current value or undefined.
+     * @private
+     *
+     * @description
+     * Traverses the API graph by path segments and returns the value if found.
+     *
+     * @example
+     * const value = this.getValueAtPath(api, ["plugins", "tools"]);
+     */
+    private getValueAtPath;
+    /**
+     * Ensure parent path exists and return the parent object.
+     * @param {function|object} root - API root object.
+     * @param {string[]} parts - Path segments.
+     * @returns {function|object} Parent container for the final segment.
+     * @throws {SlothletError} When a non-object path segment blocks creation.
+     * @private
+     *
+     * @description
+     * Walks through the path segments, creating missing objects as needed.
+     *
+     * @example
+     * const parent = this.ensureParentPath(api, ["plugins", "tools"]);
+     */
+    private ensureParentPath;
+    /**
+     * Persist a value at `apiPath` on the live API tree, validating that the
+     * caller owns (or is otherwise allowed to write to) the requested path.
+     *
+     * Called from the runtime `self` set traps when a module does
+     * `self.X = value` (TOP-LEVEL assignments only — deep-path writes like
+     * `self.X.Y = …` flow through the wrapper at `self.X` instead, not this
+     * method). Ownership rule: a caller whose own apiPath is `P` may only
+     * write under `P.*` (e.g. caller `lib.config` may write
+     * `self.lib.config.foo` or `self.lib.config.deep.nested.thing`, but NOT
+     * `self.lib.ssh.foo` or `self.lib.foo`). Callers with no apiPath
+     * (external user code outside any module) may write anywhere.
+     *
+     * Callable (`typeof value === "function"`) and object-shaped values are
+     * wrapped through `UnifiedWrapper` so they receive the same hook /
+     * permission / lifecycle treatment as `api.add()`-loaded modules.
+     * Primitives are stored verbatim. The write is applied to the live tree for
+     * the lifetime of the instance but is NOT recorded for reload replay — a
+     * reload rebuilds from disk + operation history, and a runtime write is not
+     * part of that history.
+     *
+     * @param {string} apiPath - Dotted path to write to (e.g. `"lib.config.foo"`).
+     * @param {unknown} value - Value to write. Functions/objects are wrapped via UnifiedWrapper; primitives stored as-is.
+     * @param {object|null} callerWrapper - Caller's wrapper from ALS (may be null for external code).
+     * @returns {void}
+     * @throws {SlothletError} `LOOSE_SET_NOT_OWNED` when a module-bound caller
+     *   writes outside its own namespace.
+     * @throws {SlothletError} `LOOSE_SET_RESERVED_KEY` when any path segment is
+     *   a prototype-pollution key (`__proto__`, `prototype`, `constructor`).
+     * @throws {SlothletError} `INVALID_CONFIG_API_PATH_INVALID` when the path is empty,
+     *   contains empty segments (e.g. `"a..b"`), or targets a reserved root name
+     *   (`slothlet`, `shutdown`, `destroy`).
+     * @public
+     */
+    public setOwnedProperty(apiPath: string, value: unknown, callerWrapper: object | null): void;
+    /**
+     * Determine whether a value is a UnifiedWrapper proxy.
+     * @param {unknown} value - Value to inspect.
+     * @returns {boolean} True when value looks like a wrapper proxy.
+     * @private
+     *
+     * @description
+     * Checks for wrapper markers that are exposed on UnifiedWrapper proxies.
+     *
+     * @example
+     * if (this.isWrapperProxy(api.plugins)) {
+     * 	// Update wrapper implementation
+     * }
+     */
+    private isWrapperProxy;
+    /**
+     * Synchronize an existing wrapper proxy with a new wrapper.
+     * @param {function|object} existingProxy - Existing wrapper proxy.
+     * @param {function|object} nextProxy - New wrapper proxy.
+     * @param {object} config - Configuration object for debug logging.
+     * @returns {Promise<boolean>} True when a wrapper update occurred.
+     * @private
+     *
+     * @description
+     * Copies materialization behavior and implementation from the new proxy into the existing
+     * proxy to preserve references during reload operations.
+     *
+     * @example
+     * await this.syncWrapper(existingProxy, nextProxy, this.____config);
+     */
+    private syncWrapper;
+    /**
+     * Record the first module's exclusive members that a cross-module `replace` shadows off the live
+     * surface, so a later remove of the overriding module can restore the first module's FULL mount. (#3)
+     * @param {object} existingWrapper - Raw container wrapper being overwritten (still holds the first module's children).
+     * @param {string[]} existingChildKeys - The container's current child keys.
+     * @param {string[]} nextChildKeys - The overriding module's child keys.
+     * @param {string|null} moduleID - The overriding module's id.
+     * @returns {void}
+     * @private
+     *
+     * @description
+     * `replace` wholesale-swaps the visible surface: the overriding module's keys win and the first
+     * module's EXCLUSIVE members (present on the existing container, absent from the incoming one) are
+     * deleted from the surface. Ownership still records the first module as their owner, but the live
+     * child wrappers are detached — and a namespace cannot be faithfully rebuilt from the ownership
+     * value alone (its impl is depleted once its children are adopted). So capture the actual detached
+     * child wrappers, keyed by the overriding module, and re-attach them on its removal.
+     *
+     * Only members owned by a DIFFERENT module are shadowed: a module replacing itself (an explicit
+     * same-moduleID re-add / reload) genuinely drops the export and must not resurrect it. Runs once
+     * per API tree (api + boundApi both flow through syncWrapper), capturing each tree's own container
+     * + child so the re-attach restores both.
+     */
+    private _recordReplaceShadows;
+    /**
+     * Invalidate every UnifiedWrapper found in a rejected candidate's subtree, so a still-in-flight
+     * `backgroundMaterialize: true` materialization cannot re-apply the rejected content later.
+     * @param {unknown} api - Candidate subtree (or leaf) to walk.
+     * @param {WeakSet} [visited] - Cycle guard for the recursive walk.
+     * @returns {void}
+     * @private
+     *
+     * @description
+     * `createProxy()` can kick off a wrapper's `_materialize()` in the background before
+     * `setValueAtPath()`'s collision decision is even known. When that decision rejects the
+     * candidate, `revertSpeculativeSubtree()` correctly undoes ownership/raw-capture state
+     * immediately — but the in-flight materialization is a separate, already-running async
+     * operation with no way to know it was rejected. Left alone, its eventual completion calls
+     * `___setImpl()`, which re-emits `impl:changed` and re-captures the never-mounted module,
+     * undoing the revert that already ran. `___invalidate()` (its own `invalid` flag) is checked by
+     * `___materialize()` both before starting and again after its async work resolves, so
+     * invalidating here — even after materialization has already begun — stops it from applying its
+     * result at all (#372 review, suppressed finding).
+     *
+     * @example
+     * this.invalidateSpeculativeWrappers(rootSource[key]);
+     */
+    private invalidateSpeculativeWrappers;
+    /**
+     * Recursively mutate an existing API value to match a new value.
+     * @param {function|object} existingValue - Existing value to mutate.
+     * @param {unknown} nextValue - New value to apply.
+     * @param {object} options - Mutation options.
+     * @param {boolean} options.removeMissing - Remove properties not present in nextValue.
+     * @param {object} config - Configuration object for debug logging.
+     * @returns {Promise<void>}
+     * @private
+     *
+     * @description
+     * Uses unified mergeApiObjects logic from api_assignment.mjs to ensure consistent
+     * merge behavior between initial build and hot reload.
+     *
+     * @example
+     * await this.mutateApiValue(existing, next, { removeMissing: true }, this.____config);
+     */
+    private mutateApiValue;
+    /**
+     * Set a value at a path within an API root.
+     * @param {function|object} root - API root object.
+     * @param {string[]} parts - Path segments.
+     * @param {unknown} value - New value to assign.
+     * @param {object} options - Assignment options.
+     * @param {boolean} options.mutateExisting - Mutate existing values in place.
+     * @param {boolean} options.allowOverwrite - Allow overwriting existing values.
+     * @param {string} [options.collisionMode] - Collision handling mode (skip/warn/replace/merge/error).
+     * @returns {Promise<boolean>} True if value was set, false if skipped due to collision.
+     * @throws {SlothletError} When overwrite is not allowed or collision mode is "error".
+     * @private
+     *
+     * @description
+     * Writes a new value at the requested path with configurable collision handling.
+     * Supports five collision modes:
+     * - skip: Silently ignore collision, keep existing
+     * - warn: Warn about collision, keep existing
+     * - replace: Replace existing value completely
+     * - merge: Merge properties (preserve original + add new)
+     * - error: Throw error on collision
+     *
+     * @example
+     * await this.setValueAtPath(api, ["plugins"], newApi, {
+     *   mutateExisting: true,
+     *   allowOverwrite: true,
+     *   collisionMode: "merge"
+     * });
+     */
+    private setValueAtPath;
+    /**
+     * Delete a value at a path and prune empty parents.
+     * @param {function|object} root - API root object.
+     * @param {string[]} parts - Path segments.
+     * @returns {Promise<boolean>} True when a value was deleted.
+     * @private
+     *
+     * @description
+     * Removes the property at the provided path and cleans up any empty parent objects.
+     *
+     * @example
+     * const deleted = await await this.deletePath(api, ["plugins", "tools"]);
+     */
+    private deletePath;
+    /**
+     * Restore a path from api.slothlet.api.add history or core load.
+     * @param {string} apiPath - API path to restore.
+     * @param {?string} moduleID - ModuleId to restore.
+     * @returns {Promise<void>}
+     * @private
+     *
+     * @description
+     * Attempts to reapply a previous api.slothlet.api.add entry or rebuild the core API for the path.
+     *
+     * @example
+     * await this.restoreApiPath("plugins", "plugins-core");
+     */
+    private restoreApiPath;
+    /**
+     * Add new API modules at runtime.
+     * @param {object} params - Add parameters.
+     * @param {string} params.apiPath - API path to attach.
+     * @param {string|string[]|Function|Record<string, unknown>} params.folderPath - A path (file/folder), an array of paths, OR inline content for a synthetic / in-memory leaf (#117): a bare function (a single `default` leaf), a plain object (its keys mount as leaves — option-named keys are content, never options), or a `{ exports, ...options }` object (`exports` is the content; sibling keys are call options).
+     * @param {Record<string, unknown>} [params.options={}] - Add options (including optional metadata).
+     * @returns {Promise<string|string[]>} Module ID or array of module IDs.
+     * @throws {SlothletError} When the instance is not loaded or inputs are invalid.
+     * @package
+     *
+     * @description
+     * Loads modules from a folder, file, or array of files/folders using the instance configuration
+     * and merges the resulting API under the specified apiPath.
+     *
+     * Supports filesystem paths and inline (synthetic / in-memory, #117) content:
+     * 1. Single directory path (original behavior)
+     * 2. Single file path (.mjs, .cjs, .js)
+     * 3. Array of file and/or directory paths
+     * 4. A bare function — mounted as a single `default` leaf (no filesystem touched)
+     * 5. A plain object export map — its own keys mount as leaves, including keys that share an
+     *    option name (options are never auto-extracted from this argument)
+     * 6. A `{ exports, ...options }` object — `exports` is the content (a `{ default?, ...named }`
+     *    map); the sibling keys are applied as call options (an explicit 3rd-arg option wins)
+     *
+     * When an array is provided, each path is processed sequentially,
+     * honoring collision settings, metadata, and ownership for each.
+     *
+     * @example
+     * // Directory
+     * await manager.addApiComponent({
+     * 	apiPath: "plugins",
+     * 	folderPath: "./plugins",
+     * 	options: { moduleID: "plugins-core", metadata: { version: "1.0.0" } }
+     * });
+     *
+     * @example
+     * // Single file
+     * await manager.addApiComponent({
+     * 	apiPath: "utils",
+     * 	folderPath: "./helpers/string-utils.mjs",
+     * 	options: { metadata: { author: "team" } }
+     * });
+     *
+     * @example
+     * // Array of files and folders
+     * await manager.addApiComponent({
+     * 	apiPath: "extensions",
+     * 	folderPath: ["./ext/plugin1.mjs", "./ext/plugin2.mjs", "./ext/utils"],
+     * 	options: { collisionMode: "merge" }
+     * });
+     */
+    addApiComponent(params: {
         apiPath: string;
-        parts: any[];
-    };
-    resolvePath(inputPath: any): Promise<{
-        resolvedPath: any;
-        isDirectory: any;
-        isFile: any;
-    }>;
-    resolveFolderPath(folderPath: any): Promise<any>;
-    buildDefaultModuleId(apiPath: any, ____resolvedFolderPath: any): string;
-    getValueAtPath(root: any, parts: any): any;
-    ensureParentPath(root: any, parts: any, options?: {}): any;
-    setOwnedProperty(apiPath: any, value: any, callerWrapper: any): void;
-    isWrapperProxy(value: any): boolean;
-    syncWrapper(existingProxy: any, nextProxy: any, config: any, collisionMode?: string, moduleID?: null): Promise<boolean>;
-    _recordReplaceShadows(existingWrapper: any, existingChildKeys: any, nextChildKeys: any, moduleID: any): void;
-    mutateApiValue(existingValue: any, nextValue: any, options: any, config: any): Promise<any>;
-    setValueAtPath(root: any, parts: any, value: any, options: any): Promise<boolean>;
-    deletePath(root: any, parts: any): Promise<boolean>;
-    restoreApiPath(apiPath: any, moduleID: any): Promise<void>;
-    addApiComponent(params: any): any;
+        folderPath: string | string[] | Function | Record<string, unknown>;
+        options?: Record<string, unknown> | undefined;
+    }): Promise<string | string[]>;
+    /**
+     * Roll back a failed versioned add.
+     *
+     * @description
+     * Called when `versionManager.registerVersion()` throws after the API tree, cache,
+     * ownership, and history have already been mutated by `addApiComponent()`. Scrubs
+     * the orphaned "add" entry from `operationHistory`, then delegates tree/cache/ownership
+     * and `addHistory` cleanup to `removeApiComponent({ recordHistory: false })` so that
+     * no spurious "remove" entry is pushed into `operationHistory`.
+     *
+     * The rollback is best-effort: if `removeApiComponent` itself throws the error is
+     * swallowed and the caller re-throws the original registration error.
+     *
+     * @param {object} opts - Rollback context.
+     * @param {string} opts.moduleID - The moduleID of the just-added component.
+     * @param {string} opts.effectivePath - The effective (versioned) mount path, e.g. "v1.auth".
+     * @param {string} opts.normalizedPath - The logical path, e.g. "auth".
+     * @returns {Promise<void>}
+     * @package
+     *
+     * @example
+     * await this._rollbackFailedVersionedAdd({ moduleID, effectivePath, normalizedPath });
+     */
     _rollbackFailedVersionedAdd({ moduleID, effectivePath, normalizedPath }: {
-        moduleID: any;
-        effectivePath: any;
-        normalizedPath: any;
+        moduleID: string;
+        effectivePath: string;
+        normalizedPath: string;
     }): Promise<void>;
-    _hasForeignOwnedDescendant(apiPath: any, moduleIDKey: any): boolean;
-    removeApiComponent(pathOrModuleId: any, options?: {}): Promise<boolean>;
-    reloadApiComponent(params: any): Promise<void>;
-    _reloadByModuleID(moduleID: any, { forceReplace }?: {
-        forceReplace?: boolean | undefined;
+    /**
+     * Does `apiPath` have any descendant currently owned by a module other than `moduleIDKey`?
+     * Scans the full ownership registry (every registered path). Used only for ROOT-mount removals, so a
+     * container created by a root mount isn't deleted out from under a sibling another module added beneath
+     * it (e.g. `api.add("x.b", …)` after another module created `x`). Not used for normal component removals
+     * — those own their whole subtree, and the registry can hold stale post-reload entries. Returns false
+     * for an empty/root apiPath.
+     * @param {string} apiPath - Container path to test.
+     * @param {string} moduleIDKey - The module being removed.
+     * @returns {boolean} True if a descendant is owned by another module.
+     * @private
+     */
+    private _hasForeignOwnedDescendant;
+    /**
+     * Remove API modules at runtime.
+     * @param {string} pathOrModuleId - An apiPath (dotted), a moduleID, or the composite `__metadata.moduleID`.
+     * @param {object} [options={}] - Options.
+     * @param {string} [options.scopedApiPath] - When set, `pathOrModuleId` is resolved strictly as a
+     *   moduleID and only that module's single node at `scopedApiPath` is removed (drives the public
+     *   two-argument `api.remove(moduleID, apiPath)`); sibling modules and the module's other mounts stay.
+     * @param {boolean} [options.recordHistory=true] - Whether to record the removal in the add/operation history.
+     * @returns {Promise<boolean>} True if something was removed, false if nothing matched.
+     * @throws {SlothletError} When inputs are invalid.
+     * @package
+     *
+     * @description
+     * Removes an API subtree by apiPath, or every path owned by a moduleID. The argument is resolved by
+     * splitting on the reserved composite separator ({@link MODULE_ID_SEPARATOR}): a plain id (which can
+     * never contain the separator) passes through whole, while a composite `__metadata.moduleID` strips to
+     * its base. It matches a registered module verbatim or by its auto-generated `<base>_<hash>` form, and
+     * otherwise falls back to treating the argument as an apiPath.
+     *
+     * @example
+     * await manager.removeApiComponent("plugins.tools"); // Remove by API path
+     *
+     * @example
+     * await manager.removeApiComponent("plugins-core"); // Remove all paths owned by a module ID
+     *
+     * @example
+     * await manager.removeApiComponent("plugins-core", { scopedApiPath: "plugins.tools" }); // just that node
+     */
+    removeApiComponent(pathOrModuleId: string, options?: {
+        scopedApiPath?: string | undefined;
+        recordHistory?: boolean | undefined;
+    }): Promise<boolean>;
+    /**
+     * Reload API modules using cache system.
+     * @param {object} params - Reload parameters.
+     * @param {?string} params.apiPath - API path to reload.
+     * @param {?string} params.moduleID - ModuleId to reload.
+     * @returns {Promise<void>}
+     * @package
+     *
+     * @description
+     * Reloads modules from disk using cached parameters. For moduleID reload, rebuilds
+     * entire cache and restores all paths. For apiPath reload, rebuilds all contributing
+     * moduleID caches and merges implementations.
+     *
+     * @example
+     * await manager.reloadApiComponent({ moduleID: "plugins_abc123" });
+     * await manager.reloadApiComponent({ apiPath: "plugins" });
+     */
+    reloadApiComponent(params: {
+        apiPath: string | null;
+        moduleID: string | null;
     }): Promise<void>;
-    _reloadByApiPath(apiPath: any, options?: {}): Promise<void>;
-    _findAffectedCaches(apiPath: any): any[];
-    _collectCustomProperties(existingProxy: any, freshApi: any): {};
-    _restoreCustomProperties(proxy: any, customProps: any): void;
-    _restoreApiTree(freshApi: any, endpoint: any, moduleID: any, collisionMode: any, forceReplace?: boolean): Promise<void>;
+    /**
+     * Reload by moduleID - rebuild cache and restore all paths
+     * @param {string} moduleID - Module identifier
+     * @param {Object} [options] - Reload options
+     * @param {boolean} [options.forceReplace=true] - Force replace mode on existing wrappers.
+     *   When true, temporarily overrides collision mode to "replace" so the fresh impl
+     *   fully replaces the old one. When false, the wrapper's original collision mode is
+     *   preserved, allowing merge behavior for multi-cache rebuilds.
+     * @returns {Promise<void>}
+     * @private
+     */
+    private _reloadByModuleID;
+    /**
+     * Reload by API path - find affected caches, rebuild them, update impls.
+     *
+     * Accepts "." for base module. For other paths, the resolution order is:
+     * 1. Exact cache endpoint match
+     * 2. Child caches (endpoints under the path)
+     * 3. Ownership history (modules that registered the exact path)
+     * 4. Parent cache (most specific cache whose scope covers the path)
+     *
+     * @param {string} apiPath - API path or "." for base module
+     * @param {Object} [options] - Optional reload options
+     * @param {Object} [options.metadata] - Metadata to merge for the reloaded path after rebuild
+     * @returns {Promise<void>}
+     * @private
+     */
+    private _reloadByApiPath;
+    /**
+     * Find all cache entries that need to be rebuilt for a given API path.
+     *
+     * Resolution order:
+     * 1. "." or "" or null → base module cache(s) (endpoint ".")
+     * 2. Exact endpoint match → that specific cache
+     * 3. Child caches → caches whose endpoint is under the given path
+     * 4. Ownership history → modules that registered the exact path
+     * 5. Parent cache → most specific cache whose scope covers the path
+     *
+     * @param {string} apiPath - The API path to find caches for
+     * @returns {string[]} Array of moduleIDs to reload
+     * @private
+     */
+    private _findAffectedCaches;
+    /**
+     * Collect user-set custom properties from a proxy/wrapper that are NOT in the fresh API.
+     * Custom properties are those set by the user at runtime (e.g., api.custom.testFlag = true)
+     * that should survive a selective reload.
+     * @param {Object} existingProxy - The existing proxy/wrapper to collect from
+     * @param {Object} freshApi - The fresh API from rebuild (keys to exclude)
+     * @returns {Object} Map of custom property names to their values
+     * @private
+     */
+    private _collectCustomProperties;
+    /**
+     * Restore previously collected custom properties onto a proxy/wrapper after reload.
+     * @param {Object} proxy - The proxy to restore properties onto
+     * @param {Object} customProps - Map of property names to values from _collectCustomProperties
+     * @private
+     */
+    private _restoreCustomProperties;
+    /**
+     * Restore API from fresh rebuild by updating existing wrapper.
+     * For non-root endpoints, updates the wrapper's implementation without replacing structure.
+     * For root endpoints, merges keys directly as addApiComponent does.
+     * @param {object} freshApi - Fresh API from rebuild
+     * @param {string} endpoint - Original endpoint path
+     * @param {string} moduleID - Module identifier
+     * @param {string} collisionMode - Collision handling mode
+     * @param {boolean} [forceReplace=true] - When true, temporarily overrides wrapper collision
+     *   mode to "replace" so fresh impl fully replaces old. When false, preserves original
+     *   collision mode for proper merge behavior in multi-cache rebuilds.
+     * @returns {Promise<void>}
+     * @private
+     */
+    private _restoreApiTree;
     #private;
 }
 import { ComponentBase } from "#factories/component-base";