@cldmv/slothlet-types 3.15.3 → 3.16.1

package/lib/handlers/metadata.d.mts

@@ -1,26 +1,246 @@
-export const MODULE_ID_SEPARATOR: "__slothlet_sep__";
+/**
+ * Internal delimiter joining a module's id and apiPath in the composite `moduleID` metadata key
+ * (`` `${moduleID}${MODULE_ID_SEPARATOR}${apiPath}` ``). Deliberately a readable, slothlet-branded
+ * multi-character token rather than a lone `:` — a `:` is common in real module ids (a `vine:abc`
+ * namespacing convention, the internal `versionDispatcher:<path>` id), and using it as the splitter
+ * made those ids un-round-trippable. A moduleID containing this token is refused at `add()`, so the
+ * composite is always unambiguous to split.
+ * @type {string}
+ * @internal
+ */
+export const MODULE_ID_SEPARATOR: string;
+/**
+ * Metadata handler for introspection of function metadata
+ * @class Metadata
+ * @extends ComponentBase
+ * @package
+ */
 export class Metadata extends ComponentBase {
     static slothletProperty: string;
-    _instanceId: null;
-    tagSystemMetadata(target: any, systemData: any, token: any): void;
-    getSystemMetadata(target: any): any;
-    getMetadata(target: any): any;
-    setGlobalMetadata(key: any, value: any): void;
-    setUserMetadata(target: any, key: any, value: any): void;
-    removeUserMetadata(target: any, key: any): void;
-    registerUserMetadata(identifier: any, metadata: any): void;
-    removeUserMetadataByApiPath(apiPath: any): void;
-    setPathMetadata(apiPath: any, keyOrObj: any, value: any): void;
-    getPathMetadata(apiPath: any): any;
-    removePathMetadata(apiPath: any, key: any): void;
+    /**
+     * Create Metadata instance
+     * @param {Object} slothlet - Slothlet instance
+     */
+    constructor(slothlet: Object);
+    /** @type {string | null} */
+    _instanceId: string | null;
+    /**
+     * Tag system metadata (SECURE, IMMUTABLE)
+     * Called internally during wrapper/function creation
+     *
+     * The `token` parameter must be the module-private `LIFECYCLE_TOKEN` Symbol exported
+     * from `@cldmv/slothlet/handlers/lifecycle-token`. Because a Symbol is a unique,
+     * non-forgeable value within a Node.js process, and because the token module is not
+     * listed in the package's public `exports` map, user-land code cannot construct a
+     * value that satisfies the `token === LIFECYCLE_TOKEN` check without modifying the
+     * source or importing an undocumented internal path.
+     *
+     * @param {Function|Object} target - Wrapper or function to tag
+     * @param {Object} systemData - System metadata (filePath, apiPath, moduleID, sourceFolder)
+     * @param {symbol} token - Must be `LIFECYCLE_TOKEN` — the unforgeable module-private Symbol
+     * @private
+     */
+    private tagSystemMetadata;
+    /**
+     * Get system metadata only (without user metadata)
+     * @param {Function|Object} target - Wrapper or function
+     * @returns {Object|null} System metadata or null
+     * @package
+     */
+    getSystemMetadata(target: Function | Object): Object | null;
+    /**
+     * Get metadata for a target (combines system + user)
+     * For wrappers: checks current impl to ensure metadata is current
+     * @param {Function|Object} target - Wrapper or function
+     * @returns {Object} Combined metadata (deeply frozen)
+     * @public
+     */
+    public getMetadata(target: Function | Object): Object;
+    /**
+     * Set global user metadata (applies to all functions)
+     * @param {string} key - Metadata key
+     * @param {unknown} value - Metadata value
+     * @public
+     */
+    public setGlobalMetadata(key: string, value: unknown): void;
+    /**
+     * Add/update user metadata for specific function
+     * @param {Function} target - Function to tag with metadata
+     * @param {string} key - Metadata key
+     * @param {unknown} value - Metadata value
+     * @public
+     */
+    public setUserMetadata(target: Function, key: string, value: unknown): void;
+    /**
+     * Remove user metadata from specific function
+     * @param {Function} target - Function to remove metadata from
+     * @param {string|string[]|Object<string, string[]>} [key] - Optional key(s) to remove (removes all if omitted). Can be:
+     *   - string: Remove single key
+     *   - string[]: Remove multiple keys (each element must be a string)
+     *   - {key: string[]}: Remove nested keys from object values
+     * @public
+     */
+    public removeUserMetadata(target: Function, key?: string | string[] | {
+        [x: string]: string[];
+    }): void;
+    /**
+     * Register user metadata keyed by an identifier (moduleID or API path)
+     *
+     * @description
+     * Stores user-provided metadata in `#userMetadataStore` under the given
+     * `identifier`. The identifier is treated opaquely — callers pass either a
+     * generated moduleID (e.g. `base_slothlet`) or a dot-notation API path
+     * (e.g. `math`). `getMetadata()` retrieves entries using the same key via
+     * both the moduleID lookup and `collectMetadataFromParents`, so storing
+     * under a single key is sufficient for both cases.
+     *
+     * Multiple calls to the same identifier are merged; later calls override
+     * earlier scalar values, while nested plain objects merge recursively.
+     *
+     * @param {string} identifier - Module ID or dot-notation API path
+     * @param {Object} metadata - User metadata object to merge
+     * @package
+     */
+    registerUserMetadata(identifier: string, metadata: Object): void;
+    /**
+     * Remove all user metadata for an apiPath
+     *
+     * @description
+     * Cleanup method to remove all user metadata associated with an apiPath.
+     * Used during api.remove() or cleanup operations.
+     *
+     * @param {string} apiPath - API path to remove
+     * @package
+     */
+    removeUserMetadataByApiPath(apiPath: string): void;
+    /**
+     * Set metadata for all functions reachable at an API path.
+     *
+     * @description
+     * Stores metadata keyed by `apiPath` so that every function whose system
+     * `apiPath` starts with (or equals) the given path inherits the values via
+     * `collectMetadataFromParents()` in `getMetadata()`.
+     *
+     * Accepts either a single key/value pair or a plain object to merge.
+     * Multiple calls to the same path are merged; later calls override earlier
+     * ones for conflicting keys.
+     *
+     * Priority (lowest → highest): global → setForPath → set() → system.
+     *
+     * @param {string} apiPath - Dot-notation path (e.g. `"math"`, `"math.add"`)
+     * @param {string|Object} keyOrObj - Key string (with `value`) OR metadata object to merge
+     * @param {unknown} [value] - Value when `keyOrObj` is a string key
+     * @public
+     */
+    public setPathMetadata(apiPath: string, keyOrObj: string | Object, value?: unknown): void;
+    /**
+     * Get the user metadata collected from the path store for a given API path.
+     *
+     * @description
+     * Traverses from root segment to leaf, merging parent → child metadata — the same
+     * traversal used by `collectMetadataFromParents` inside `getMetadata()`. Does not
+     * include immutable system metadata; only user-supplied path store entries are returned.
+     *
+     * @param {string} apiPath - Dot-notation API path (e.g. `"v1.auth"`, `"math"`).
+     * @returns {Object} Merged user metadata for the path (not frozen).
+     * @public
+     * @example
+     * metadata.getPathMetadata("v1.auth"); // { stable: true, category: "auth" }
+     */
+    public getPathMetadata(apiPath: string): Object;
+    /**
+     * Remove metadata keys (or all metadata) for an API path.
+     *
+     * @description
+     * Removes one specific key, multiple keys, or ALL user metadata stored under
+     * the given `apiPath` key in the path store.
+     * Only affects metadata set via `setForPath()` / `registerUserMetadata()` for
+     * this exact path segment - it does not walk descendant paths.
+     *
+     * @param {string} apiPath - Dot-notation path (e.g. `"math"`, `"math.add"`)
+     * @param {string|string[]} [key] - Key(s) to remove. Omit to remove all metadata for the path.
+     * @public
+     */
+    public removePathMetadata(apiPath: string, key?: string | string[]): void;
+    /**
+     * Export user-managed metadata state for preservation across reload.
+     *
+     * @description
+     * Captures `#globalUserMetadata` and all entries in `#userMetadataStore`
+     * so they can be restored to a fresh Metadata instance after reload.
+     * Called by `slothlet.reload()` BEFORE `load()` destroys this instance.
+     *
+     * @returns {{ globalMetadata: Object, userMetadataStore: Map }} Snapshot of user state
+     * @package
+     */
     exportUserState(): {
-        globalMetadata: any;
+        globalMetadata: Object;
         userMetadataStore: Map<any, any>;
     };
-    importUserState(state: any): void;
-    get(path: any): Promise<any>;
-    self(): any;
-    caller(): any;
+    /**
+     * Restore user-managed metadata state after a fresh load.
+     *
+     * @description
+     * Merges previously exported state into the new (empty) Metadata instance.
+     * Called by `slothlet.reload()` AFTER `load()` creates the new instance and
+     * BEFORE operation-history replay so that `registerUserMetadata()` from replay
+     * can properly merge over the restored base state.
+     *
+     * Merge priority: existing (from load) > saved state.
+     * This means replay-registered api.add metadata overrides restored values
+     * for the same key, which is the desired behaviour.
+     *
+     * @param {{ globalMetadata: Object, userMetadataStore: Map }} state - Previously exported state
+     * @package
+     */
+    importUserState(state: {
+        globalMetadata: Object;
+        userMetadataStore: Map<any, any>;
+    }): void;
+    /**
+     * Get metadata of any function by API path.
+     *
+     * Traverses `this.slothlet.api` using the dot-notation path, materializes
+     * lazy wrappers as needed, then returns the combined metadata for the
+     * resolved target via `getMetadata()`.
+     *
+     * Called by the `api.slothlet.metadata.get()` closure injected in
+     * `slothlet.injectRuntimeMetadataFunctions()`.
+     *
+     * @param {string} path - Dot-notation API path (e.g. `"math.add"`)
+     * @returns {Promise<object|null>} Combined metadata or null
+     * @public
+     */
+    public get(path: string): Promise<object | null>;
+    /**
+     * Get metadata for the currently-executing API function.
+     *
+     * Reads `currentWrapper` from the active context-manager store — the same
+     * fast synchronous path used by the unified wrapper's `apply` trap.
+     * Throws `RUNTIME_NO_ACTIVE_CONTEXT` when called outside of a slothlet
+     * execution context.
+     *
+     * Called by the `api.slothlet.metadata.self()` closure injected in
+     * `slothlet.injectRuntimeMetadataFunctions()`.
+     *
+     * @returns {object} Combined metadata for the current function
+     * @public
+     */
+    public self(): object;
+    /**
+     * Get metadata for the API function that called the current function.
+     *
+     * Reads `callerWrapper` from the active context-manager store.
+     * Returns `null` when there is no caller in context (e.g. the function
+     * was invoked directly from outside the API).
+     *
+     * Called by the `api.slothlet.metadata.caller()` closure injected in
+     * `slothlet.injectRuntimeMetadataFunctions()`.
+     *
+     * @returns {object|null} Combined metadata for the calling function, or null
+     * @public
+     */
+    public caller(): object | null;
     #private;
 }
 import { ComponentBase } from "#factories/component-base";

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

@@ -1,28 +1,176 @@
+/**
+ * @typedef {import("../helpers/module-discovery.mjs").DiscoverResult} DiscoverResult
+ * @typedef {import("../helpers/module-discovery.mjs").DiscoverOptions} DiscoverOptions
+ */
+/**
+ * @typedef {object} AddModuleOptions
+ * @property {"skip"|"warn"|"replace"|"merge"|"merge-replace"|"error"} [collisionMode="merge"] - Per-mount override; defaults to "merge" (matches `DEFAULT_MODULE_COLLISION_MODE`). Use "error" to throw on any pre-flight mountPath collision against api-manager's `addHistory`.
+ * @property {string} [version] - When the discovery cache holds multiple versions of the same `name`, mount only the entry whose package.json version matches.
+ * @property {DiscoverOptions} [discover] - Options to forward to the lazy discover() call if the cache is empty. Ignored when the cache already holds data.
+ */
+/**
+ * @typedef {object} AddModulesOptions
+ * @property {"skip"|"warn"|"replace"|"merge"|"merge-replace"|"error"} [collisionMode="merge"] - Per-call collision policy passed to every mount. Defaults to "merge" (matches `DEFAULT_MODULE_COLLISION_MODE`); use "error" to throw on any pre-flight mountPath collision.
+ * @property {"throw"|"rollback"|"best-effort"} [onFailure="throw"] - Failure policy. `throw` (default): throw on first failure, leave mounted entries in place. `rollback`: throw on first failure, remove every entry mounted in this call. `best-effort`: collect failures, return aggregate `{ mounted, failed }`.
+ * @property {number} [concurrency=1] - Mount concurrency. `1` (default) = serial. Higher values mount in parallel batches.
+ */
+/**
+ * @typedef {object} MountResult
+ * @property {string} packageName
+ * @property {string} mountPath - Dot-notation path used at the time of mount.
+ * @property {string} moduleID - moduleID returned by api.add().
+ * @property {DiscoverResult} discoverResult
+ * @property {{version: string, default: boolean}|null} versionConfig - Versioning descriptor when the module mounted under a `vMAJOR.<mountPath>` prefix (multi-version case from `#buildVersionConfigs`), otherwise `null`. `version` is the slothlet version tag (`vMAJOR`); `default` indicates whether this entry is the default for the unversioned dispatch path.
+ */
+/**
+ * @typedef {object} FailureEntry
+ * @property {DiscoverResult|string} item - The cache entry or name that failed.
+ * @property {Error} error
+ */
+/**
+ * Module discovery + mount handler.
+ * @class
+ * @extends ComponentBase
+ */
 export class ModuleManager extends ComponentBase {
+    /**
+     * Property name used by slothlet's auto-discovery initialization loop.
+     * @type {string}
+     * @static
+     */
     static slothletProperty: string;
-    discover(options?: {}): Promise<Readonly<{
-        packageName: any;
-        packageRoot: any;
-        mountPath: readonly any[];
-        apiDir: any;
-        manifest: any;
-    }>[]>;
-    sort(results: any, comparator: any): any[];
-    getDiscoveryCache(): any[];
+    /**
+     * @param {object} slothlet - Parent slothlet instance.
+     */
+    constructor(slothlet: object);
+    /**
+     * Walk the filesystem for slothlet modules, validate manifests, dedupe, and
+     * replace the discovery cache with the new results. Returns the sorted
+     * candidate list using sortModules's default comparator.
+     *
+     * Emits `modules:discover-start` before the walk and
+     * `modules:discover-complete` after the cache is populated.
+     *
+     * @param {DiscoverOptions} [options]
+     * @returns {Promise<DiscoverResult[]>} Validated discovery results in walk order (apply `sortModules()` for deterministic ordering).
+     */
+    discover(options?: DiscoverOptions): Promise<DiscoverResult[]>;
+    /**
+     * Pure sort wrapper. Forwards to `sortModules()` without touching cache state.
+     *
+     * @param {DiscoverResult[]} results
+     * @param {(a: DiscoverResult, b: DiscoverResult) => number} [comparator]
+     * @returns {DiscoverResult[]}
+     */
+    sort(results: DiscoverResult[], comparator?: (a: DiscoverResult, b: DiscoverResult) => number): DiscoverResult[];
+    /**
+     * Return the list of modules currently in the discovery cache.
+     * @returns {DiscoverResult[]}
+     */
+    getDiscoveryCache(): DiscoverResult[];
+    /**
+     * Empty the discovery cache. Does not affect already-mounted modules.
+     * @returns {void}
+     */
     clearDiscoveryCache(): void;
-    getStaleMounts(): any[];
-    addModule(nameOrResult: any, options?: {}): Promise<{
-        packageName: any;
-        mountPath: any;
-        moduleID: any;
-        discoverResult: any;
-        versionConfig: any;
+    /**
+     * Compute the stale-mount set per S3b: mounted modules that did not surface
+     * in the most recent `discover()` cache. Host calls this after re-discovery
+     * to decide what to unmount.
+     *
+     * @returns {MountResult[]} Mounts whose `${packageName}@${version}` is no longer in the cache.
+     */
+    getStaleMounts(): MountResult[];
+    /**
+     * Mount a single module — by name (cache lookup), by DiscoverResult directly,
+     * or with a lazy-trigger discover() if the name is not cached.
+     *
+     * @param {string|DiscoverResult} nameOrResult
+     * @param {AddModuleOptions} [options]
+     * @returns {Promise<MountResult>}
+     * @throws {SlothletError} `MODULE_PACKAGE_NOT_FOUND` when a name cannot be resolved.
+     * @throws {SlothletError} `MODULE_MOUNT_COLLISION` when the exact mountPath is already occupied and `collisionMode` is `"error"`.
+     */
+    addModule(nameOrResult: string | DiscoverResult, options?: AddModuleOptions): Promise<MountResult>;
+    /**
+     * Mount a list of modules.
+     *
+     * @param {Array<string|DiscoverResult>} items - Heterogeneous array; strings resolved through the discovery cache.
+     * @param {AddModulesOptions} [options]
+     * @returns {Promise<MountResult[] | {mounted: MountResult[], failed: FailureEntry[]}>} Plain array under `throw`/`rollback`; aggregate object under `best-effort`.
+     */
+    addModules(items: Array<string | DiscoverResult>, options?: AddModulesOptions): Promise<MountResult[] | {
+        mounted: MountResult[];
+        failed: FailureEntry[];
     }>;
-    addModules(items: any, options?: {}): Promise<any[] | {
-        mounted: any[];
-        failed: any[];
-    }>;
-    removeModule(name: any, opts?: {}): Promise<boolean>;
+    /**
+     * Unmount a previously-mounted module by package name (and optional version
+     * when multi-version mounts are in play).
+     *
+     * @param {string} name - Package name.
+     * @param {object} [opts]
+     * @param {string} [opts.version] - Disambiguator when more than one mounted entry shares the name.
+     * @returns {Promise<boolean>} `true` when something was unmounted, `false` when no matching mount was found.
+     */
+    removeModule(name: string, opts?: {
+        version?: string | undefined;
+    }): Promise<boolean>;
     #private;
 }
+export type DiscoverResult = import("../helpers/module-discovery.mjs").DiscoverResult;
+export type DiscoverOptions = import("../helpers/module-discovery.mjs").DiscoverOptions;
+export type AddModuleOptions = {
+    /**
+     * - Per-mount override; defaults to "merge" (matches `DEFAULT_MODULE_COLLISION_MODE`). Use "error" to throw on any pre-flight mountPath collision against api-manager's `addHistory`.
+     */
+    collisionMode?: "merge" | "replace" | "skip" | "warn" | "merge-replace" | "error" | undefined;
+    /**
+     * - When the discovery cache holds multiple versions of the same `name`, mount only the entry whose package.json version matches.
+     */
+    version?: string | undefined;
+    /**
+     * - Options to forward to the lazy discover() call if the cache is empty. Ignored when the cache already holds data.
+     */
+    discover?: import("../helpers/module-discovery.mjs").DiscoverOptions | undefined;
+};
+export type AddModulesOptions = {
+    /**
+     * - Per-call collision policy passed to every mount. Defaults to "merge" (matches `DEFAULT_MODULE_COLLISION_MODE`); use "error" to throw on any pre-flight mountPath collision.
+     */
+    collisionMode?: "merge" | "replace" | "skip" | "warn" | "merge-replace" | "error" | undefined;
+    /**
+     * - Failure policy. `throw` (default): throw on first failure, leave mounted entries in place. `rollback`: throw on first failure, remove every entry mounted in this call. `best-effort`: collect failures, return aggregate `{ mounted, failed }`.
+     */
+    onFailure?: "throw" | "rollback" | "best-effort" | undefined;
+    /**
+     * - Mount concurrency. `1` (default) = serial. Higher values mount in parallel batches.
+     */
+    concurrency?: number | undefined;
+};
+export type MountResult = {
+    packageName: string;
+    /**
+     * - Dot-notation path used at the time of mount.
+     */
+    mountPath: string;
+    /**
+     * - moduleID returned by api.add().
+     */
+    moduleID: string;
+    discoverResult: DiscoverResult;
+    /**
+     * - Versioning descriptor when the module mounted under a `vMAJOR.<mountPath>` prefix (multi-version case from `#buildVersionConfigs`), otherwise `null`. `version` is the slothlet version tag (`vMAJOR`); `default` indicates whether this entry is the default for the unversioned dispatch path.
+     */
+    versionConfig: {
+        version: string;
+        default: boolean;
+    } | null;
+};
+export type FailureEntry = {
+    /**
+     * - The cache entry or name that failed.
+     */
+    item: DiscoverResult | string;
+    error: Error;
+};
 import { ComponentBase } from "#factories/component-base";