@cldmv/slothlet-types 3.15.2 → 3.16.0

package/lib/handlers/unified-wrapper.d.mts

@@ -1,39 +1,300 @@
+/**
+ * Whether a property name belongs to the framework rather than to a module's exports.
+ *
+ * @param {string|symbol} key - Property name to classify.
+ * @returns {boolean} True when the name is reserved by the framework.
+ * @public
+ *
+ * @description
+ * Matched against the framework's own reserved names — `INTERNAL_KEYS` (wrapper state and control
+ * props) plus {@link IMPL_METADATA_KEYS} — never by underscore prefix. The documented hidden-entry
+ * rule (docs/MODULE-STRUCTURE.md) hides `.`/`__`-prefixed FILES and FOLDERS; it says nothing about
+ * export names, and a module that writes `export const __priv` has deliberately put that member on
+ * its surface. Treating the prefix as internal silently dropped such exports from the composed api
+ * in lazy mode while eager served them.
+ *
+ * @example
+ * isFrameworkReservedKey("__childFilePaths"); // true
+ * isFrameworkReservedKey("__priv"); // false — a module's own export
+ */
+export function isFrameworkReservedKey(key: string | symbol): boolean;
+/**
+ * Resolves a value to its backing UnifiedWrapper instance.
+ * Accepts a proxy registered via createProxy() or a raw UnifiedWrapper instance.
+ * Returns null for any other value.
+ *
+ * @param {unknown} value - Value to resolve
+ * @returns {UnifiedWrapper|null} The backing wrapper, or null
+ *
+ * @example
+ * const wrapper = resolveWrapper(someProxy);
+ * if (wrapper) wrapper.____slothletInternal.impl = newImpl;
+ */
+export function resolveWrapper(value: unknown): UnifiedWrapper | null;
+/**
+ * Framework metadata that rides on a module implementation but is not an api member.
+ *
+ * Matched by EXACT name rather than an `__` prefix: a user module may legitimately export an
+ * underscore-prefixed member, and dropping those would make the composed surface lie. Shared so
+ * enumeration and the collision-merge paths filter exactly the same set.
+ * @type {Set<string>}
+ * @public
+ */
 export const IMPL_METADATA_KEYS: Set<string>;
 export namespace TYPE_STATES {
     let UNMATERIALIZED: symbol;
     let IN_FLIGHT: symbol;
 }
+/**
+ * Unified wrapper class that handles all proxy concerns in one place:
+ * - __impl pattern for reload support
+ * - Lazy/eager mode materialization
+ * - Recursive waiting proxy for deep lazy loading
+ * - Context binding through contextManager
+ *
+ * @class
+ * @extends ComponentBase
+ * @public
+ */
 export class UnifiedWrapper extends ComponentBase {
-    static _cloneImpl(value: any): any;
-    static _extractFullImpl(wrapper: any): any;
-    constructor(slothlet: any, { mode, apiPath, initialImpl, materializeFunc, isCallable, materializeOnCreate, filePath, moduleID, sourceFolder, __adoptVisited, deferChildAdopt }: {
-        mode: any;
-        apiPath: any;
-        initialImpl?: null | undefined;
-        materializeFunc?: null | undefined;
-        isCallable: any;
+    /**
+     * Shallow-clone a non-Proxy object implementation to prevent ___adoptImplChildren
+     * from mutating shared module export references via its `delete this.____slothletInternal.impl[key]`
+     * operations. When concurrent materializations (e.g., old + new wrapper during reload)
+     * both load the same cached module, the first ___adoptImplChildren would destroy the
+     * shared export, causing subsequent wrappers to receive empty objects.
+     *
+     * Returns the value unchanged if it is not a plain object, or if it IS a Proxy
+     * (cloning a Proxy destroys its trap behavior - e.g., LG TV controllers using
+     * numeric-index access through custom get traps).
+     *
+     * @param {*} value - The implementation value to (maybe) clone.
+     * @returns {*} A shallow clone of `value` when it is a non-Proxy plain object,
+     *              otherwise the original `value`.
+     * @static
+     * @private
+     */
+    private static _cloneImpl;
+    /**
+     * Reconstruct a full implementation object from a wrapper whose _impl may have
+     * been depleted by ___adoptImplChildren.
+     *
+     * @description
+     * After ___adoptImplChildren runs, children are moved from _impl onto the wrapper as
+     * own properties and deleted from _impl. This helper reconstructs the original
+     * impl by merging the remaining _impl keys with the adopted children extracted
+     * from the wrapper.
+     *
+     * Recursively walks the wrapper tree so nested objects whose _impl was also
+     * depleted are properly reconstructed. For callable (function) impls, returns
+     * the function directly since keepImplProperties prevents depletion.
+     *
+     * @param {Object} wrapper - The UnifiedWrapper instance to extract from
+     * @returns {*} The reconstructed implementation mirroring original module exports
+     * @static
+     * @private
+     */
+    private static _extractFullImpl;
+    /**
+     * @param {Object} slothlet - Slothlet instance (provides contextManager, instanceID, ownership)
+     * @param {Object} options - Configuration options
+     * @param {string} options.mode - "lazy" or "eager"
+     * @param {string} options.apiPath - API path for this wrapper (e.g., "math.advanced.calc")
+     * @param {Function|Object|null} [options.initialImpl=null] - Initial implementation (null for lazy mode)
+     * @param {Function} [options.materializeFunc=null] - Async function to materialize lazy modules
+     * @param {boolean} [options.isCallable=false] - Whether the wrapper should be callable
+     * @param {boolean} [options.materializeOnCreate=false] - Whether to materialize on creation
+     * @param {string} [options.filePath=null] - File path of the module source
+     * @param {string} [options.moduleID=null] - Module identifier
+     * @param {string} [options.sourceFolder=null] - Source folder for metadata
+     * @param {WeakSet<object>|null} [options.__adoptVisited=null] - Internal: one-shot cycle-guard set
+     *   threaded through the eager child-adoption recursion so a self-referential value cannot recurse
+     *   forever (#330). Set only on nested wrappers built during a single adopt traversal; null for a
+     *   normal (root / reload) construction.
+     * @param {boolean} [options.deferChildAdopt=false] - Internal: defer eager child adoption to first
+     *   getTrap access (and propagate the deferral to descendants). Used for wrap-on-set of a
+     *   user-assigned object so an arbitrarily deep runtime-grafted chain is wrapped one level per
+     *   access instead of recursing synchronously through every level at assignment and overflowing
+     *   the stack (#329 / #247 unbounded depth).
+     *
+     * @description
+     * Creates a unified wrapper instance for a specific API path. Extends ComponentBase
+     * to access slothlet.contextManager, slothlet.instanceID, and slothlet.handlers.ownership.
+     *
+     * @example
+     * const wrapper = new UnifiedWrapper(this.slothlet, {
+     * 	mode: "lazy",
+     * 	apiPath: "math",
+     * 	initialImpl: null,
+     * 	materializeFunc: async () => import("./math.mjs")
+     * });
+     */
+    constructor(slothlet: Object, { mode, apiPath, initialImpl, materializeFunc, isCallable, materializeOnCreate, filePath, moduleID, sourceFolder, __adoptVisited, deferChildAdopt }: {
+        mode: string;
+        apiPath: string;
+        initialImpl?: Object | Function | null | undefined;
+        materializeFunc?: Function | undefined;
+        isCallable?: boolean | undefined;
         materializeOnCreate?: boolean | undefined;
-        filePath?: null | undefined;
-        moduleID?: null | undefined;
-        sourceFolder?: null | undefined;
-        __adoptVisited?: null | undefined;
+        filePath?: string | undefined;
+        moduleID?: string | undefined;
+        sourceFolder?: string | undefined;
+        __adoptVisited?: WeakSet<object> | null | undefined;
         deferChildAdopt?: boolean | undefined;
     });
-    get ____slothletInternal(): null | undefined;
+    /**
+     * Internal state accessor used by framework-internal code only.
+     * Backed by the private `#internal` field - prototype property, not an own property,
+     * so proxy invariants never apply and getTrap can legally return undefined for it.
+     *
+     * Uses a private-field brand check (`#internal in this`) so the getter is safe to
+     * invoke with any receiver - including `UnifiedWrapper.prototype` itself during a
+     * prototype chain walk via `Object.getPrototypeOf` - without throwing a TypeError.
+     * Without the brand check, `Object.getPrototypeOf(proxy).____slothletInternal` would
+     * throw because the prototype object was never constructed and has no `#internal` field.
+     * @returns {Record<string, any>|undefined} Internal state container, or undefined for non-instances
+     */
+    get ____slothletInternal(): Record<string, any> | undefined;
+    /**
+     * Custom inspect output for Node.js `util.inspect`.
+     *
+     * Defined as an ordinary named method and wired to the `util.inspect.custom`
+     * symbol via a prototype assignment after the class. A computed
+     * `[util.inspect.custom]` member in the class body makes tsc emit a spurious
+     * numeric index signature (`[x: number]`) into the generated `.d.mts`; an
+     * ordinary named method emits cleanly instead.
+     * @returns {*} The actual implementation for inspection.
+     * @internal
+     */
     ____inspectCustom(____depth: any, ____options: any, ____inspect: any): any;
-    get __impl(): any;
-    _applyNewImpl(newImpl: any, forceReuseChildren?: boolean): void;
-    ___setImpl(newImpl: any, moduleID?: null, forceReuseChildren?: boolean): void;
-    ___resetLazy(newMaterializeFunc: any): void;
-    ___materialize(): Promise<any>;
-    _materialize(): Promise<any>;
-    ___invalidate(): void;
-    ___adoptImplChildren(forceReuseChildren?: boolean): void;
-    ___createChildWrapper(key: any, value: any, visited?: null, deferChildAdopt?: boolean): any;
-    ___createWaitingProxy(propChain?: any[]): any;
-    createProxy(): any;
+    /**
+     * Get current implementation
+     * @returns {Function|Object|null} Current __impl value
+     * @public
+     */
+    public get __impl(): Function | Object | null;
+    /**
+     * Core implementation-application logic shared by ___setImpl and lazy materialization.
+     * Clones the implementation (protecting the API cache from ___adoptImplChildren's
+     * delete operations), clears the invalid flag, upgrades __isCallable when a
+     * callable impl arrives on a configurable wrapper, updates __filePath for lazy
+     * folder wrappers, and adopts children.
+     *
+     * @param {*} newImpl - The new implementation value.
+     * @param {boolean} [forceReuseChildren=false] - When true, always reuse existing child
+     *   wrappers regardless of mode (used by ___setImpl to preserve live references).
+     * @private
+     */
+    private _applyNewImpl;
+    /**
+     * Set new implementation and adopt children.
+     * Delegates core impl work to _applyNewImpl, then emits lifecycle events
+     * and updates materialization state.
+     *
+     * @param {*} newImpl - New implementation
+     * @param {string} [moduleID] - Optional moduleID for lifecycle event (for replacements)
+     * @param {boolean} [forceReuseChildren=false] - When true, always reuse existing child
+     *   wrappers and bypass collision-merged key guards. Use this for direct/explicit
+     *   ___setImpl calls where reference preservation is the intent. Do NOT set for
+     *   hot-reload paths (syncWrapper) where lazy refs should intentionally break.
+     * @private
+     */
+    private ___setImpl;
+    /**
+     * Reset wrapper to un-materialized lazy state with a fresh materialization function.
+     * Used during reload to restore lazy wrappers to their shell state instead of
+     * eagerly loading all implementations. Preserves proxy identity so existing
+     * references continue to work - next property access triggers materialization
+     * from the fresh materializeFunc (which reads updated source files from disk).
+     * @param {Function} newMaterializeFunc - Fresh materialization function from rebuild
+     * @returns {void}
+     * @private
+     */
+    private ___resetLazy;
+    /**
+     * Trigger materialization (lazy mode only)
+     * @returns {Promise<void>}
+     * @private
+     */
+    private ___materialize;
+    /**
+     * @private
+     * @returns {Promise<void>}
+     *
+     * @description
+     * Exposes lazy materialization for waiting proxies and nested wrappers.
+     *
+     * @example
+     * await wrapper._materialize();
+     */
+    private _materialize;
+    /**
+     * @private
+     * @returns {void}
+     *
+     * @description
+     * Invalidates this wrapper when its parent removes the API path.
+     *
+     * @example
+     * wrapper.___invalidate();
+     */
+    private ___invalidate;
+    /**
+     * @private
+     * @returns {void}
+     *
+     * @description
+     * Moves child properties off the impl and attaches them to wrapper as properties
+     * so this wrapper only represents the current API path.
+     *
+     * @example
+     * wrapper.___adoptImplChildren();
+     */
+    private ___adoptImplChildren;
+    /**
+     * @private
+     * @param {string|symbol} key - Child property name
+     * @param {unknown} value - Child value
+     * @param {WeakSet<object>|null} [visited=null] - Cycle-guard set threaded through an eager adopt
+     *   traversal so a self-referential value cannot recurse forever (#330); null outside a traversal.
+     * @param {boolean} [deferChildAdopt=false] - Defer the child's own eager adoption to first getTrap
+     *   access, so a deep wrap-on-set graft is wrapped one level per access instead of recursively (#329).
+     * @returns {Object|Function|null|undefined} Wrapped child proxy, or null/undefined when the value is
+     *   stored unwrapped (opaque built-ins, null, cycle bail-out) or is undefined.
+     *
+     * @description
+     * Creates a child wrapper for impl values, including primitives.
+     *
+     * @example
+     * const child = wrapper.___createChildWrapper("add", fn);
+     */
+    private ___createChildWrapper;
+    /**
+     * Create recursive waiting proxy for deep lazy loading
+     * Builds property chain (e.g., ["advanced", "calc", "power"]) and waits for all parent
+     * wrappers to materialize before accessing the final property.
+     *
+     * Waiting proxies are ONLY created when not materialized or in-flight.
+     * Once materialized, we return actual cached values, not waiting proxies.
+     * Therefore, waiting proxies always represent in-flight/unmaterialized state.
+     *
+     * CRITICAL: Caches waiting proxies by propChain key to ensure subsequent accesses
+     * return the SAME proxy object, which can then delegate once materialization completes.
+     * This matches v2's propertyProxyCache behavior.
+     *
+     * @private
+     * @param {Array<string|symbol>} [propChain=[]] - Property chain to resolve.
+     * @returns {Proxy} Proxy that waits for materialization before applying calls.
+     */
+    private ___createWaitingProxy;
+    /**
+     * Create main proxy for this wrapper
+     * Handles lazy/eager mode logic, property access, and context binding
+     *
+     * @returns {Proxy} Main proxy for API
+     * @public
+     */
+    public createProxy(): ProxyConstructor;
     #private;
 }
-export function isFrameworkReservedKey(key: any): boolean;
-export function resolveWrapper(value: any): any;
 import { ComponentBase } from "#factories/component-base";

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

@@ -1,36 +1,243 @@
+/**
+ * Manages versioned API paths and their dispatcher proxies.
+ *
+ * Allows the same logical API path (e.g. `auth`) to be registered under multiple
+ * version tags (e.g. `v1`, `v2`). A dispatcher proxy lives at the logical path and
+ * routes property accesses to the correct versioned namespace at call time.
+ *
+ * @class VersionManager
+ * @extends ComponentBase
+ * @package
+ */
 export class VersionManager extends ComponentBase {
     static slothletProperty: string;
-    registerVersion(logicalPath: any, versionTag: any, moduleID: any, versionMeta: any, isDefault: any): void;
-    unregisterVersion(logicalPath: any, versionTag: any): boolean;
-    getVersionKeyForModule(moduleID: any): any;
-    hasDispatcher(logicalPath: any): boolean;
-    getVersionMetadata(moduleID: any): any;
-    getVersionMetadataByPath(logicalPath: any, versionTag: any): any;
-    setVersionMetadataByPath(logicalPath: any, versionTag: any, patch: any): void;
-    findLogicalPathFor(path: any): any;
-    list(logicalPath: any): {
-        versions: {};
-        default: any;
+    /**
+     * Register a new version for a logical path and rebuild the dispatcher.
+     *
+     * @param {string} logicalPath - Logical API path (e.g. `"auth"`).
+     * @param {string} versionTag - Version tag (e.g. `"v1"`).
+     * @param {string} moduleID - Module ID of the mounted versioned module.
+     * @param {object} versionMeta - User-supplied version metadata (stored in VersionManager only).
+     * @param {boolean} isDefault - Whether this version should be the explicit default.
+     * @returns {void}
+     * @example
+     * versionManager.registerVersion("auth", "v1", "auth_abc", { stable: true }, true);
+     */
+    registerVersion(logicalPath: string, versionTag: string, moduleID: string, versionMeta: object, isDefault: boolean): void;
+    /**
+     * Unregister a version for a logical path.
+     * Rebuilds or tears down the dispatcher accordingly.
+     *
+     * @param {string} logicalPath - Logical API path.
+     * @param {string} versionTag - Version tag to remove.
+     * @returns {boolean} `true` when the version was found and removed.
+     * @example
+     * versionManager.unregisterVersion("auth", "v2");
+     */
+    unregisterVersion(logicalPath: string, versionTag: string): boolean;
+    /**
+     * Get the version key (logicalPath + versionTag) for a given module ID.
+     * Used as a reverse lookup during remove operations.
+     *
+     * @param {string} moduleID - Module ID.
+     * @returns {{ logicalPath: string, versionTag: string } | undefined}
+     * @example
+     * versionManager.getVersionKeyForModule("auth_abc123"); // { logicalPath: "auth", versionTag: "v1" }
+     */
+    getVersionKeyForModule(moduleID: string): {
+        logicalPath: string;
+        versionTag: string;
     } | undefined;
-    setDefault(logicalPath: any, versionTag: any): void;
-    getDefaultVersion(logicalPath: any): any;
-    resolveForPath(logicalPath: any, allVersions: any, caller: any): any;
-    buildAllVersionsArg(logicalPath: any): {};
-    buildCallerArg(callerWrapper: any): {
-        version: null;
-        default: null;
-        metadata: any;
-        versionMetadata: null;
-    } | {
-        version: any;
-        default: boolean;
-        metadata: any;
-        versionMetadata: any;
+    /**
+     * Returns `true` when a live dispatcher proxy is tracked for the given logical path.
+     * Used by ApiManager to detect whether a removed path was a logical dispatcher.
+     *
+     * @param {string} logicalPath - Logical API path (e.g. `"auth"`).
+     * @returns {boolean}
+     * @example
+     * versionManager.hasDispatcher("auth"); // true
+     */
+    hasDispatcher(logicalPath: string): boolean;
+    /**
+     * Retrieve the VersionManager-only metadata object stored for a module ID.
+     * Used internally by `buildAllVersionsArg` and `buildCallerArg`.
+     *
+     * @param {string} moduleID - Opaque module ID.
+     * @returns {object | undefined} Stored version metadata or `undefined`.
+     * @example
+     * versionManager.getVersionMetadata("auth_abc123"); // { version: "v1", logicalPath: "auth", stable: true }
+     */
+    getVersionMetadata(moduleID: string): object | undefined;
+    /**
+     * Retrieve the VersionManager-only metadata for a logical path and version tag.
+     *
+     * @param {string} logicalPath - Logical API path (e.g. `"auth"`).
+     * @param {string} versionTag - Version tag (e.g. `"v1"`, `"2.3.0"`).
+     * @returns {object | undefined} Stored version metadata or `undefined` if not registered.
+     * @example
+     * versionManager.getVersionMetadataByPath("auth", "v1"); // { version: "v1", logicalPath: "auth", stable: true }
+     */
+    getVersionMetadataByPath(logicalPath: string, versionTag: string): object | undefined;
+    /**
+     * Patch (merge) the VersionManager-only metadata for a registered logical path and version tag at runtime.
+     * The injected `version` and `logicalPath` keys always win over any user-supplied fields in `patch`.
+     *
+     * @param {string} logicalPath - Logical API path (e.g. `"auth"`).
+     * @param {string} versionTag - Version tag (e.g. `"v1"`, `"2.3.0"`).
+     * @param {object} patch - Plain object of keys to merge into the stored version metadata.
+     * @returns {void}
+     * @throws {SlothletError} When the logical path or version tag is not registered.
+     * @example
+     * versionManager.setVersionMetadataByPath("auth", "v1", { stable: true });
+     */
+    setVersionMetadataByPath(logicalPath: string, versionTag: string, patch: object): void;
+    /**
+     * Find the registered logical path that covers a dotted api pattern.
+     *
+     * @param {string} path - Dotted api path or hook pattern (e.g. "auth.login").
+     * @returns {string | null} The longest registered logical path that is a segment-prefix of
+     *   `path`, or `null` when no registered version covers it.
+     * @public
+     * @example
+     * versionManager.findLogicalPathFor("auth.login"); // "auth"
+     */
+    public findLogicalPathFor(path: string): string | null;
+    /**
+     * Return a snapshot of all registered versions and the default tag for a logical path.
+     *
+     * @param {string} logicalPath - Logical API path.
+     * @returns {{ versions: object, default: string | null } | undefined} Snapshot object, or `undefined` if the path is not registered.
+     * @example
+     * versionManager.list("auth"); // { versions: { v1: {...}, v2: {...} }, default: "v2" }
+     * versionManager.list("unknown"); // undefined
+     */
+    list(logicalPath: string): {
+        versions: object;
+        default: string | null;
+    } | undefined;
+    /**
+     * Explicitly override the default version for a logical path at runtime.
+     * Clears any previous explicit defaults and marks only the specified tag.
+     *
+     * @param {string} logicalPath - Logical API path.
+     * @param {string} versionTag - Version tag to set as default.
+     * @returns {void}
+     * @throws {SlothletError} When the version tag is not registered for the path.
+     * @example
+     * versionManager.setDefault("auth", "v1");
+     */
+    setDefault(logicalPath: string, versionTag: string): void;
+    /**
+     * Determine the default version tag for a logical path.
+     *
+     * Algorithm:
+     * 1. Return the first version entry with `isDefault === true`.
+     * 2. Otherwise, normalise all tags, sort descending, return highest.
+     * 3. Return `null` when no versions are registered.
+     *
+     * @param {string} logicalPath - Logical API path.
+     * @returns {string | null} The default version tag, or `null`.
+     * @example
+     * // Given: ["v1", "v3", "v8", "v2"]
+     * versionManager.getDefaultVersion("auth"); // "v8"
+     */
+    getDefaultVersion(logicalPath: string): string | null;
+    /**
+     * Run the configured discriminator and return the winning version tag.
+     *
+     * When the configured `versionDispatcher` is a string, reads that key from
+     * `caller.versionMetadata`. When it is a function, calls it with `(allVersions, caller)`.
+     *
+     * @param {string} logicalPath - Logical API path.
+     * @param {object} allVersions - Pre-built allVersions arg (see `buildAllVersionsArg`).
+     * @param {object} caller - Pre-built caller arg (see `buildCallerArg`).
+     * @returns {string | null} Resolved version tag, or `null` to fall through to default.
+     * @example
+     * const tag = versionManager.resolveForPath("auth", allVersions, caller); // "v2"
+     */
+    resolveForPath(logicalPath: string, allVersions: object, caller: object): string | null;
+    /**
+     * Build the `allVersions` argument passed to function discriminators.
+     *
+     * Each key is a version tag; each value contains `version`, `default`, `metadata`
+     * (regular Metadata system data), and `versionMetadata` (VersionManager-only store).
+     *
+     * @param {string} logicalPath - Logical API path.
+     * @returns {object} Map-like object keyed by version tag.
+     * @example
+     * versionManager.buildAllVersionsArg("auth");
+     * // { v1: { version: "v1", default: true, metadata: {...}, versionMetadata: {...} } }
+     */
+    buildAllVersionsArg(logicalPath: string): object;
+    /**
+     * Build the `caller` argument passed to function discriminators.
+     *
+     * Returns `null` for version-specific fields when the caller is not a registered
+     * versioned module.
+     *
+     * @param {object | null | undefined} callerWrapper - The caller's UnifiedWrapper proxy.
+     * @returns {{ version: string|null, default: boolean|null, metadata: object, versionMetadata: object|null }}
+     * @example
+     * versionManager.buildCallerArg(callerWrapper);
+     * // { version: "v2", default: false, metadata: {...}, versionMetadata: {...} }
+     */
+    buildCallerArg(callerWrapper: object | null | undefined): {
+        version: string | null;
+        default: boolean | null;
+        metadata: object;
+        versionMetadata: object | null;
     };
-    createDispatcher(logicalPath: any): any;
-    updateDispatcher(logicalPath: any): void;
-    teardownDispatcher(logicalPath: any): void;
-    onVersionedModuleReload(moduleID: any): void;
+    /**
+     * Create a native Proxy that dispatches property accesses to the correct versioned path.
+     *
+     * The dispatcher handles all property categories defined in the spec (framework
+     * internal keys, stable framework accessors, `then`, symbols, routing, etc.).
+     *
+     * @param {string} logicalPath - Logical API path this dispatcher covers.
+     * @returns {object} A Proxy instance for version-dispatched property access. The returned
+     *   value is a Proxy wrapping a frozen plain-object target; it is NOT the Proxy constructor.
+     * @example
+     * const proxy = versionManager.createDispatcher("auth");
+     * proxy.login; // resolves version then returns api.v2.auth.login
+     */
+    createDispatcher(logicalPath: string): object;
+    /**
+     * Rebuild (or create) the dispatcher proxy for a logical path and mount it
+     * on both `api` and `boundApi`.
+     *
+     * @param {string} logicalPath - Logical API path.
+     * @returns {void}
+     * @example
+     * versionManager.updateDispatcher("auth");
+     */
+    updateDispatcher(logicalPath: string): void;
+    /**
+     * Tear down the dispatcher for a logical path, removing it from the API tree.
+     *
+     * @param {string} logicalPath - Logical API path.
+     * @returns {void}
+     * @example
+     * versionManager.teardownDispatcher("auth");
+     */
+    teardownDispatcher(logicalPath: string): void;
+    /**
+     * Called after a versioned module is reloaded.
+     * Refreshes internal metadata and rebuilds the dispatcher for the affected path.
+     *
+     * @param {string} moduleID - Module ID that was reloaded.
+     * @returns {void}
+     * @example
+     * versionManager.onVersionedModuleReload("auth_abc");
+     */
+    onVersionedModuleReload(moduleID: string): void;
+    /**
+     * Clear all internal state.
+     * Called automatically by the shutdown sequence.
+     *
+     * @returns {void}
+     * @example
+     * versionManager.shutdown();
+     */
     shutdown(): void;
     #private;
 }

package/lib/helpers/caller-pinning.d.mts

@@ -1,2 +1,21 @@
-export function pinToCurrentCaller(callback: any): any;
-export function setApiCallerPinner(strategy: any): void;
+/**
+ * Register the strategy for binding a callback to whoever scheduled it.
+ *
+ * @param {Function|null} strategy - Takes a callback and returns a replacement that re-enters the
+ *   registering module's context when it runs. `null` clears the registration.
+ * @returns {void}
+ * @internal
+ */
+export function setApiCallerPinner(strategy: Function | null): void;
+/**
+ * Bind a callback to the caller active right now, if the runtime supplies a way to.
+ *
+ * Called by each scheduling boundary at registration time. Returns the callback unchanged when no
+ * pinner is registered (the async runtime) or when there is no caller to pin (the host scheduling
+ * its own work), so the boundary pays nothing outside a module call.
+ *
+ * @param {Function} callback - Callback about to be deferred.
+ * @returns {Function} The callback, bound to the current caller where one exists.
+ * @internal
+ */
+export function pinToCurrentCaller(callback: Function): Function;