@cldmv/slothlet 2.11.0 → 3.0.1

package/types/dist/lib/handlers/hook-manager.d.mts

@@ -0,0 +1,199 @@
+/**
+ * Manages hooks for API function interception.
+ * Supports before/after/always/error hooks with pattern matching and priority ordering.
+ *
+ * @class HookManager
+ * @extends ComponentBase
+ */
+export class HookManager extends ComponentBase {
+    /**
+     * Property name for auto-discovery
+     * @type {string}
+     * @static
+     */
+    static slothletProperty: string;
+    enabled: any;
+    defaultPattern: any;
+    suppressErrors: any;
+    enabledPatterns: Set<any>;
+    patternFilterActive: boolean;
+    hooks: Map<any, any>;
+    registrationOrder: number;
+    reportedErrors: WeakSet<object>;
+    /**
+     * Register a hook for API functions.
+     *
+     * @param {string} typePattern - Combined type and pattern (e.g., "before:math.*")
+     * @param {function} handler - Hook handler function
+     * @param {object} [options={}] - Hook options
+     * @param {string} [options.id] - Unique identifier (auto-generated if not provided)
+     * @param {number} [options.priority=0] - Higher = earlier execution
+     * @param {string} [options.subset="primary"] - Phase: "before", "primary", or "after"
+     * @returns {string} Hook ID
+     * @public
+     *
+     * @example
+     * hookManager.on("before:math.*", ({ args }) => {
+     *   console.log("Args:", args);
+     *   return args;
+     * }, { priority: 100 });
+     */
+    public on(typePattern: string, handler: Function, options?: {
+        id?: string;
+        priority?: number;
+        subset?: string;
+    }): string;
+    /**
+     * Remove hooks matching filter criteria.
+     *
+     * @param {object} [filter={}] - Filter criteria
+     * @param {string} [filter.id] - Remove hook by ID
+     * @param {string} [filter.type] - Remove hooks by type
+     * @param {string} [filter.pattern] - Remove hooks matching pattern
+     * @returns {number} Number of hooks removed
+     * @public
+     */
+    public remove(filter?: {
+        id?: string;
+        type?: string;
+        pattern?: string;
+    }): number;
+    /**
+     * Enable hooks matching filter criteria.
+     *
+     * @param {object|string} [filter={}] - Filter criteria (empty = enable all, string = pattern)
+     * @param {string} [filter.id] - Enable hook by ID
+     * @param {string} [filter.type] - Enable hooks by type
+     * @param {string} [filter.pattern] - Enable hooks matching pattern
+     * @returns {number} Number of hooks enabled
+     * @public
+     */
+    public enable(filter?: object | string): number;
+    /**
+     * Disable hooks matching filter criteria.
+     *
+     * @param {object|string} [filter={}] - Filter criteria (empty = disable all, string = pattern)
+     * @param {string} [filter.id] - Disable hook by ID
+     * @param {string} [filter.type] - Disable hooks by type
+     * @param {string} [filter.pattern] - Disable hooks matching pattern
+     * @returns {number} Number of hooks disabled
+     * @public
+     */
+    public disable(filter?: object | string): number;
+    /**
+     * List registered hooks matching filter criteria.
+     *
+     * @param {object|string} [filter={}] - Filter criteria (empty = list all), type string, or pattern string
+     * @param {string} [filter.id] - List hook by ID
+     * @param {string} [filter.type] - List hooks by type
+     * @param {string} [filter.pattern] - List hooks matching pattern
+     * @param {boolean} [filter.enabled] - Filter by enabled state
+     * @returns {object} Object with registeredHooks array property
+     * @public
+     */
+    public list(filter?: object | string): object;
+    /**
+     * Get hooks for a specific API path and type.
+     * Used internally by UnifiedWrapper.
+     *
+     * @param {string} type - Hook type (before/after/always/error)
+     * @param {string} apiPath - API path (e.g., "math.add")
+     * @returns {Array<object>} Sorted array of matching hooks
+     * @public
+     */
+    public getHooksForPath(type: string, apiPath: string): Array<object>;
+    /**
+     * Execute before hooks for an API path.
+     *
+     * @param {string} path - API path being called
+     * @param {Array} args - Function arguments
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @returns {object} Result object: { args, shortCircuit, value }
+     * @public
+     */
+    public executeBeforeHooks(path: string, args: any[], api: object, ctx: object): object;
+    /**
+     * Execute after hooks for an API path.
+     *
+     * @param {string} path - API path being called
+     * @param {*} result - Function return value
+     * @param {Array} args - Original function arguments
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @returns {HookExecutionResult} Object indicating if result was modified and the final result
+     * @public
+     */
+    public executeAfterHooks(path: string, result: any, args: any[], api: object, ctx: object): HookExecutionResult;
+    /**
+     * Execute always hooks for an API path.
+     *
+     * @param {string} path - API path being called
+     * @param {Array} args - Function arguments
+     * @param {*} resultOrError - Function result or error
+     * @param {boolean} hasError - Whether an error occurred
+     * @param {Array<Error>} errors - Array of errors that occurred
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @public
+     */
+    public executeAlwaysHooks(path: string, args: any[], resultOrError: any, hasError: boolean, errors: Array<Error>, api: object, ctx: object): void;
+    /**
+     * Execute error hooks for an API path.
+     *
+     * @param {string} path - API path being called
+     * @param {Error} error - The error that occurred
+     * @param {object} source - Error source info with type, hookTag, hookId, timestamp, stack
+     * @param {Array} args - Function arguments
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @public
+     */
+    public executeErrorHooks(path: string, error: Error, source: object, args: any[], api: object, ctx: object): void;
+    /**
+     * Get the pattern compilation function for diagnostic purposes.
+     * Only exposed when diagnostics mode is enabled.
+     *
+     * @returns {function} The pattern compilation function
+     * @internal
+     */
+    getCompilePatternForDiagnostics(): Function;
+    /**
+     * Export all registered hooks (including handler closures) so they can be
+     * re-registered on a fresh HookManager instance after a full reload.
+     *
+     * @returns {Array<object>} Snapshot of all current hook registrations.
+     * @public
+     */
+    public exportHooks(): Array<object>;
+    /**
+     * Re-register hooks exported by {@link exportHooks} into this (new) instance.
+     * Called after a full `api.slothlet.reload()` to restore user-registered hooks.
+     *
+     * @param {Array<object>} registrations - Snapshot returned by exportHooks().
+     * @returns {void}
+     * @public
+     */
+    public importHooks(registrations: Array<object>): void;
+    /**
+     * Cleanup hook manager on shutdown.
+     * @public
+     */
+    public shutdown(): Promise<void>;
+    #private;
+}
+/**
+ * Result returned by hook execution methods.
+ */
+export type HookExecutionResult = {
+    /**
+     * - Whether any hook modified the result value.
+     */
+    modified: boolean;
+    /**
+     * - The final (possibly hook-modified) return value.
+     */
+    result?: any;
+};
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=hook-manager.d.mts.map

package/types/dist/lib/handlers/hook-manager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-manager.d.mts","sourceRoot":"","sources":["../../../../dist/lib/handlers/hook-manager.mjs"],"names":[],"mappings":"AAkCA;;;;;;GAMG;AACH;IACC;;;;OAIG;IACH,yBAHU,MAAM,CAGwB;IAoDvC,aAAiC;IACjC,oBAAgD;IAChD,oBAAwD;IACxD,0BAAgC;IAChC,6BAAgC;IAEhC,qBAAsB;IACtB,0BAA0B;IAC1B,gCAAmC;IAGpC;;;;;;;;;;;;;;;;;OAiBG;IACH,uBAfW,MAAM,+BAGd;QAAyB,EAAE,GAAnB,MAAM;QACW,QAAQ,GAAzB,MAAM;QACW,MAAM,GAAvB,MAAM;KACd,GAAU,MAAM,CA+ElB;IAED;;;;;;;;;OASG;IACH,uBANG;QAAwB,EAAE,GAAlB,MAAM;QACU,IAAI,GAApB,MAAM;QACU,OAAO,GAAvB,MAAM;KACd,GAAU,MAAM,CA8ClB;IAED;;;;;;;;;OASG;IACH,uBAPW,MAAM,GAAC,MAAM,GAIX,MAAM,CAalB;IAED;;;;;;;;;OASG;IACH,wBAPW,MAAM,GAAC,MAAM,GAIX,MAAM,CAclB;IAED;;;;;;;;;;OAUG;IACH,qBARW,MAAM,GAAC,MAAM,GAKX,MAAM,CA8DlB;IAED;;;;;;;;OAQG;IACH,6BALW,MAAM,WACN,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAqDzB;IAED;;;;;;;;;OASG;IACH,gCAPW,MAAM,oBAEN,MAAM,OACN,MAAM,GACJ,MAAM,CA6ClB;IAED;;;;;;;;;;OAUG;IACH,+BARW,MAAM,UACN,GAAC,oBAED,MAAM,OACN,MAAM,GACJ,mBAAmB,CA+C/B;IAED;;;;;;;;;;;OAWG;IACH,gCATW,MAAM,8BAEN,GAAC,YACD,OAAO,UACP,KAAK,CAAC,KAAK,CAAC,OACZ,MAAM,OACN,MAAM,QA8BhB;IAED;;;;;;;;;;OAUG;IACH,+BARW,MAAM,SACN,KAAK,UACL,MAAM,oBAEN,MAAM,OACN,MAAM,QA4BhB;IAkLD;;;;;;OAMG;IACH,4CAEC;IA6ID;;;;;;OAMG;IACH,sBAHa,KAAK,CAAC,MAAM,CAAC,CAkBzB;IAED;;;;;;;OAOG;IACH,kCAJW,KAAK,CAAC,MAAM,CAAC,GACX,IAAI,CAWhB;IAED;;;OAGG;IACH,iCAUC;;CACD;;;;;;;;cAt9Ba,OAAO;;;;aACP,GAAC;;8BANe,0CAA0C"}

package/types/dist/lib/handlers/lifecycle-token.d.mts

@@ -0,0 +1,49 @@
+/**
+ * Registers a Slothlet instance and creates its per-instance lifecycle capability token.
+ *
+ * Safe to call multiple times on the same instance (idempotent) — subsequent calls are
+ * silently ignored, preserving the original token. This handles the reload code path where
+ * `load()` is called again on the same Slothlet object.
+ *
+ * @param {object} slothlet - The Slothlet instance to register.
+ * @returns {void}
+ * @package
+ *
+ * @example
+ * // Called once (or on reload) in Slothlet.load():
+ * registerInstance(this);
+ */
+export function registerInstance(slothlet: object): void;
+/**
+ * Returns the per-instance capability token for the given Slothlet instance.
+ *
+ * Used internally by `lifecycle.mjs` (emit dispatch) and `modes-processor.mjs`
+ * (direct tagSystemMetadata call for folder wrappers). Requires a live registered
+ * Slothlet instance — cannot be exploited without one.
+ *
+ * @param {object} slothlet - A registered Slothlet instance.
+ * @returns {symbol|undefined} The instance token, or undefined if not registered.
+ * @package
+ *
+ * @example
+ * handler(data, getInstanceToken(this.slothlet));
+ */
+export function getInstanceToken(slothlet: object): symbol | undefined;
+/**
+ * Verifies that `token` is the registered capability token for the given Slothlet instance.
+ *
+ * Used by `metadata.mjs` inside `tagSystemMetadata()` to reject calls that did not
+ * originate from the internal lifecycle dispatch path.
+ *
+ * @param {object} slothlet - A registered Slothlet instance.
+ * @param {*} token - The token value to verify.
+ * @returns {boolean} `true` only if `token` is the exact Symbol registered for `slothlet`.
+ * @package
+ *
+ * @example
+ * if (!verifyToken(this.slothlet, token)) {
+ *   throw new this.SlothletError("METADATA_LIFECYCLE_BYPASS", ...);
+ * }
+ */
+export function verifyToken(slothlet: object, token: any): boolean;
+//# sourceMappingURL=lifecycle-token.d.mts.map

package/types/dist/lib/handlers/lifecycle-token.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-token.d.mts","sourceRoot":"","sources":["../../../../dist/lib/handlers/lifecycle-token.mjs"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;GAcG;AACH,2CARW,MAAM,GACJ,IAAI,CAchB;AAED;;;;;;;;;;;;;GAaG;AACH,2CAPW,MAAM,GACJ,MAAM,GAAC,SAAS,CAQ5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,sCAVW,MAAM,SACN,GAAC,GACC,OAAO,CAUnB"}

package/types/dist/lib/handlers/lifecycle.d.mts

@@ -0,0 +1,90 @@
+/**
+ * Lifecycle event manager for impl changes
+ * @extends ComponentBase
+ * @public
+ */
+export class Lifecycle extends ComponentBase {
+    /**
+     * Where this component should be mounted on the Slothlet instance
+     * @type {string}
+     */
+    static slothletProperty: string;
+    subscribers: Map<any, any>;
+    eventLog: any[];
+    maxLogSize: number;
+    /**
+     * Subscribe to lifecycle event
+     * @param {string} event - Event name (impl:created, impl:changed, impl:removed, materialized:complete, path:collision)
+     * @param {Function} handler - Event handler function(eventData)
+     * @returns {Function} Unsubscribe function
+     * @public
+     *
+     * @description
+     * Subscribe to lifecycle events to react to impl changes.
+     *
+     * @example
+     * const unsubscribe = lifecycle.subscribe("impl:changed", (data) => {
+     *   console.log("Impl changed:", data.apiPath, data.source);
+     * });
+     */
+    public subscribe(event: string, handler: Function): Function;
+    /**
+     * Alias for subscribe() - standard EventEmitter pattern
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler function
+     * @returns {Function} Unsubscribe function
+     * @public
+     *
+     * @example
+     * lifecycle.on('materialized:complete', (data) => {
+     *   console.log(`${data.total} modules materialized`);
+     * });
+     */
+    public on(event: string, handler: Function): Function;
+    /**
+     * Unsubscribe from lifecycle event - standard EventEmitter pattern
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler function to remove
+     * @public
+     *
+     * @example
+     * const handler = (data) => console.log(data);
+     * lifecycle.on('impl:changed', handler);
+     * lifecycle.off('impl:changed', handler);
+     */
+    public off(event: string, handler: Function): void;
+    /**
+     * Alias for off() - standard EventEmitter pattern
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler function to remove
+     * @public
+     */
+    public unsubscribe(event: string, handler: Function): void;
+    /**
+     * Emit lifecycle event
+     * @param {string} event - Event name
+     * @param {object} data - Event data
+     * @private
+     *
+     * @description
+     * Emit event to all subscribers. Event data should include:
+     * - apiPath: API path where impl exists
+     * - impl: The implementation object
+     * - source: Source of event (initial, hot-reload, materialization, etc)
+     * - moduleID: Module identifier (if applicable)
+     * - filePath: File path (if applicable)
+     * - metadata: Additional metadata
+     *
+     * @example
+     * lifecycle.emit("impl:created", {
+     *   apiPath: "math.add",
+     *   impl: addFunction,
+     *   source: "initial",
+     *   moduleID: "base_abc123",
+     *   filePath: "/path/to/math.mjs"
+     * });
+     */
+    private emit;
+}
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=lifecycle.d.mts.map

package/types/dist/lib/handlers/lifecycle.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.mts","sourceRoot":"","sources":["../../../../dist/lib/handlers/lifecycle.mjs"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH;IACC;;;OAGG;IACH,yBAFU,MAAM,CAEsB;IAOrC,2BAA4B;IAC5B,gBAAkB;IAClB,mBAAsB;IAGvB;;;;;;;;;;;;;;OAcG;IACH,wBAbW,MAAM,+BA0BhB;IAED;;;;;;;;;;;OAWG;IACH,iBAVW,MAAM,+BAYhB;IAED;;;;;;;;;;OAUG;IACH,kBATW,MAAM,2BAchB;IAED;;;;;OAKG;IACH,0BAJW,MAAM,2BAMhB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,aAyDC;CAED;8BAtL6B,0CAA0C"}

package/types/dist/lib/handlers/materialize-manager.d.mts

@@ -0,0 +1,75 @@
+/**
+ * Manager for tracking lazy folder materialization state
+ * @class MaterializeManager
+ * @extends ComponentBase
+ * @package
+ *
+ * @description
+ * Provides access to lazy materialization state via `api.slothlet.materialize`.
+ * Tracks count of unmaterialized lazy folders and provides boolean state, statistics,
+ * and wait functionality for synchronization.
+ *
+ * @example
+ * const api = await slothlet({ dir: "./api", mode: "lazy" });
+ *
+ * // Check if fully materialized
+ * if (api.slothlet.materialize.materialized) {
+ *   console.log("All lazy folders loaded!");
+ * }
+ *
+ * // Get statistics
+ * const stats = api.slothlet.materialize.get();
+ * console.log(`${stats.percentage}% loaded (${stats.remaining}/${stats.total} remaining)`);
+ *
+ * // Wait for full materialization
+ * await api.slothlet.materialize.wait();
+ */
+export class MaterializeManager extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Get materialization state as a boolean
+     * Returns true when all lazy wrappers have been materialized
+     * @returns {boolean} True if fully materialized, false if any lazy folders remain
+     * @public
+     *
+     * @example
+     * if (api.slothlet.materialize.materialized) {
+     *   console.log("API is fully loaded");
+     * }
+     */
+    public get materialized(): boolean;
+    /**
+     * Get detailed materialization statistics
+     * @returns {Object} Statistics object with total, materialized, remaining, percentage
+     * @public
+     *
+     * @example
+     * const stats = api.slothlet.materialize.get();
+     * // { total: 5, materialized: 3, remaining: 2, percentage: 60 }
+     */
+    public get(): any;
+    /**
+     * Wait for full materialization (all lazy folders loaded)
+     * Returns immediately if already fully materialized
+     * @returns {Promise<void>} Resolves when all lazy wrappers have materialized
+     * @public
+     *
+     * @example
+     * // Wait for API to fully load
+     * await api.slothlet.materialize.wait();
+     * console.log("All modules loaded!");
+     *
+     * @example
+     * // Wait with timeout
+     * const timeoutPromise = new Promise((_, reject) =>
+     *   setTimeout(() => reject(new Error("Timeout")), 5000)
+     * );
+     * await Promise.race([
+     *   api.slothlet.materialize.wait(),
+     *   timeoutPromise
+     * ]);
+     */
+    public wait(): Promise<void>;
+}
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=materialize-manager.d.mts.map

package/types/dist/lib/handlers/materialize-manager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize-manager.d.mts","sourceRoot":"","sources":["../../../../dist/lib/handlers/materialize-manager.mjs"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IACC,gCAAwC;IAWxC;;;;;;;;;;OAUG;IACH,2BARa,OAAO,CAUnB;IAED;;;;;;;;OAQG;IACH,kBAYC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAlBa,OAAO,CAAC,IAAI,CAAC,CA4BzB;CACD;8BA9G6B,0CAA0C"}

package/types/dist/lib/handlers/metadata.d.mts

@@ -0,0 +1,215 @@
+/**
+ * Metadata handler for introspection of function metadata
+ * @class Metadata
+ * @extends ComponentBase
+ * @package
+ */
+export class Metadata extends ComponentBase {
+    static slothletProperty: string;
+    _instanceId: any;
+    /**
+     * 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 | any): any | 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 | any): any;
+    /**
+     * 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 ones for conflicting keys.
+     *
+     * @param {string} identifier - Module ID or dot-notation API path
+     * @param {Object} metadata - User metadata object to merge
+     * @package
+     */
+    registerUserMetadata(identifier: string, metadata: any): 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 | any, value?: unknown): void;
+    /**
+     * 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;
+        userMetadataStore: Map<any, 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: any;
+        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 "@cldmv/slothlet/factories/component-base";
+//# sourceMappingURL=metadata.d.mts.map

package/types/dist/lib/handlers/metadata.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.mts","sourceRoot":"","sources":["../../../../dist/lib/handlers/metadata.mjs"],"names":[],"mappings":"AAwBA;;;;;GAKG;AACH;IACC,gCAAqC;IASrC,iBAAmB;IAkCnB;;;;;;;;;;;;;;;OAeG;IACH,0BAyCC;IAED;;;;;OAKG;IACH,0BAJW,cAAe,GACb,MAAO,IAAI,CAYvB;IAED;;;;;;OAMG;IACH,2BAJW,cAAe,OAoEzB;IAED;;;;;OAKG;IACH,8BAJW,MAAM,SACN,OAAO,QAKjB;IAED;;;;;;OAMG;IACH,8CAJW,MAAM,SACN,OAAO,QA+CjB;IAED;;;;;;;;OAQG;IACH,kDANW,MAAM,GAAC,MAAM,EAAE,GAAC;YAAO,MAAM,GAAE,MAAM,EAAE;KAAC,QAkFlD;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iCAJW,MAAM,uBA2BhB;IAED;;;;;;;;;OASG;IACH,qCAHW,MAAM,QAMhB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,gCALW,MAAM,YACN,MAAM,MAAO,UACb,OAAO,QAyBjB;IAED;;;;;;;;;;;;OAYG;IACH,mCAJW,MAAM,QACN,MAAM,GAAC,MAAM,EAAE,QA+BzB;IAED;;;;;;;;;;OAUG;IACH,mBAHa;QAAE,cAAc,MAAS;QAAC,iBAAiB,gBAAK;KAAE,CAe9D;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAHW;QAAE,cAAc,MAAS;QAAC,iBAAiB,gBAAK;KAAE,QAgC5D;IAED;;;;;;;;;;;;;OAaG;IACH,iBAJW,MAAM,GACJ,OAAO,CAAC,MAAM,GAAC,IAAI,CAAC,CAkChC;IAED;;;;;;;;;;;;;OAaG;IACH,eAHa,MAAM,CASlB;IAED;;;;;;;;;;;;OAYG;IACH,iBAHa,MAAM,GAAC,IAAI,CAOvB;;CACD;8BAhpB6B,0CAA0C"}