@cldmv/slothlet-types 3.15.2 → 3.16.0

package/lib/typegen/typegen.d.mts

@@ -1,4 +1,36 @@
-export function generateTypes(options?: {}): Promise<{
-    filePath: any;
+/**
+ * Generate a TypeScript declaration file (`.d.ts`) for a Slothlet API directory.
+ *
+ * Loads the API in eager + fast TypeScript mode (no type-checking pass needed —
+ * the structure walk uses the loaded API and source files), writes the `.d.ts`,
+ * and shuts the loaded instance down before returning.
+ *
+ * @param {object} options
+ * @param {string} options.dir - Path to the API directory to scan (relative or absolute).
+ * @param {string} options.output - Path to write the `.d.ts` file to (relative or absolute).
+ * @param {string} options.interfaceName - Name of the generated TypeScript interface (e.g. `"MyApi"`).
+ * @param {boolean|string|object} [options.typescript] - Override TypeScript loader config. Same union accepted by `slothlet({ typescript })`: pass `true` (default mode), `"fast"` / `"strict"`, or an object like `{ mode: "fast" }`. Defaults to `{ mode: "fast" }` when omitted.
+ * @param {boolean} [options.includeDocumentation=true] - Include JSDoc comments in the generated declaration.
+ * @returns {Promise<{filePath: string, content: string}>} Absolute path written and the declaration content.
+ * @throws {SlothletError} `INVALID_CONFIG` when `dir`, `output`, or `interfaceName` is missing or not a string.
+ * @public
+ *
+ * @example
+ * import { generateTypes } from "@cldmv/slothlet/typegen";
+ *
+ * await generateTypes({
+ *     dir: "./api",
+ *     output: "./types/api.d.ts",
+ *     interfaceName: "MyApi"
+ * });
+ */
+export function generateTypes(options?: {
+    dir: string;
+    output: string;
+    interfaceName: string;
+    typescript?: string | boolean | object | undefined;
+    includeDocumentation?: boolean | undefined;
+}): Promise<{
+    filePath: string;
     content: string;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/slothlet-types",
-	"version": "3.15.2",
+	"version": "3.16.0",
 	"description": "TypeScript declaration files (.d.mts) for @cldmv/slothlet. Install alongside @cldmv/slothlet for editor and type-checker support.",
 	"keywords": [
 		"slothlet",
@@ -41,7 +41,7 @@
 	},
 	"type": "module",
 	"engines": {
-		"node": ">=22.0.0"
+		"node": ">=22.12.0"
 	},
 	"sideEffects": false,
 	"exports": {
@@ -58,29 +58,11 @@
 		"./runtime": {
 			"types": "./lib/runtime/runtime.d.mts"
 		},
-		"./runtime/async": {
-			"types": "./lib/runtime/runtime-asynclocalstorage.d.mts"
-		},
-		"./runtime/live": {
-			"types": "./lib/runtime/runtime-livebindings.d.mts"
-		},
-		"./helpers/*": {
-			"types": "./lib/helpers/*.d.mts"
-		},
-		"./modes/*": {
-			"types": "./lib/modes/*.d.mts"
-		},
-		"./builders/*": {
-			"types": "./lib/builders/*.d.mts"
-		},
-		"./processors/*": {
-			"types": "./lib/processors/*.d.mts"
+		"./helpers/sanitize": {
+			"types": "./lib/helpers/sanitize.d.mts"
 		},
 		"./errors": {
 			"types": "./lib/errors.d.mts"
-		},
-		"./i18n": {
-			"types": "./lib/i18n/translations.d.mts"
 		}
 	},
 	"imports": {
@@ -97,7 +79,7 @@
 		"LICENSE"
 	],
 	"peerDependencies": {
-		"@cldmv/slothlet": "3.15.2"
+		"@cldmv/slothlet": "3.16.0"
 	},
 	"peerDependenciesMeta": {
 		"@cldmv/slothlet": {

package/slothlet.d.mts

@@ -1,3 +1,428 @@
-declare function stdin_default(config: any): Promise<{}>;
-export function slothlet(config: any): Promise<{}>;
-export { stdin_default as default };
+/**
+ * Create a new Slothlet instance and load an API from a directory.
+ * This is the sole public entry point for slothlet. Each call produces an independent
+ * API instance with its own component graph, context store, and lifecycle.
+ * @alias module:@cldmv/slothlet
+ * @async
+ * @param {SlothletOptions} config - Configuration options
+ * @returns {Promise<SlothletAPI>} Fully loaded, proxy-based API object
+ * @public
+ * @example
+ * // Minimal usage
+ * const api = await slothlet({ base: "./api" });
+ * const result = await api.math.add(2, 3);
+ * await api.slothlet.shutdown();
+ *
+ * @example
+ * // Lazy mode with background materialization
+ * const api = await slothlet({
+ *   base: "./api",
+ *   mode: "lazy",
+ *   backgroundMaterialize: true
+ * });
+ *
+ * @example
+ * // With hooks
+ * const api = await slothlet({ base: "./api", hook: true });
+ * api.slothlet.hook.on("before", "**", (endpoint, args) => { /* ... *\/ });
+ *
+ * @example
+ * // Hot-reload a module at runtime
+ * await api.slothlet.api.reload("./api/math.mjs");
+ *
+ * @example
+ * // Strict collision control
+ * const api = await slothlet({
+ *   base: "./api",
+ *   api: { collision: { initial: "merge", api: "error" } }
+ * });
+ */
+export function slothlet(config: SlothletOptions): Promise<SlothletAPI>;
+export namespace slothlet {
+    let defaults: Readonly<{
+        routines: ReadonlyArray<{
+            name: string;
+            mode: string;
+        }>;
+        reservedExports: ReadonlySet<string>;
+    }>;
+}
+export default slothlet;
+/**
+ * Configuration options passed to `slothlet()`.
+ */
+export type SlothletOptions = {
+    /**
+     * - Directory (node mode) or file:// URL / base URL (browser mode) to load API modules from.
+     * Required in both modes. Plain filesystem paths are automatically converted to `file://` URLs by the default browser-mode resolver.
+     */
+    base?: string | undefined;
+    /**
+     * - Deprecated alias for `base`. Still accepted; emits a `V3_CONFIG_DEPRECATED` warning unless `silent: true`. Will be removed in v4.
+     */
+    dir?: string | undefined;
+    /**
+     * - Loading strategy.
+     * - `"eager"` — all modules are loaded immediately at startup (default).
+     * - `"lazy"` — modules are loaded on first access via a Proxy.
+     * Also accepted: `"immediate"` / `"preload"` (eager aliases); `"deferred"` / `"proxy"` (lazy aliases).
+     */
+    mode?: "eager" | "lazy" | undefined;
+    /**
+     * - Context propagation runtime.
+     * - `"async"` — AsyncLocalStorage (Node.js built-in, recommended for production).
+     * - `"live"` — Experimental live bindings.
+     * Also accepted: `"asynclocalstorage"` / `"als"` / `"node"` as aliases for `"async"`.
+     */
+    runtime?: "async" | "live" | undefined;
+    /**
+     * - Directory traversal depth. `Infinity` scans all subdirectories (default). `0` scans only the root.
+     */
+    apiDepth?: number | undefined;
+    /**
+     * - Glob or array of globs hiding files and folders from the API, matched against each entry's
+     * path relative to `base` (folder-style `a/b` or dotted `a.b`; `*` one segment, `**` any depth, `?` one char, `{a,b}` alternation,
+     * `!` negation). Files match on their extension-stripped path. Applies on top of the built-in rule that `.`/`__`-prefixed names are
+     * hidden by default (`.`/`__`-prefixed folders can be restored via the deprecated `scanHiddenFolders`; files stay hidden). Also accepted per-call by `api.slothlet.api.add(path, dir, { hidden })`, where globs are relative to the added folder.
+     */
+    hidden?: string | string[] | undefined;
+    /**
+     * - Deprecated escape hatch: restore the pre-v3.11 behavior of scanning `.`/`__`-prefixed
+     * folders. Emits a `CONFIG_SCAN_HIDDEN_FOLDERS_DEPRECATED` warning when supplied (unless `silent: true`). Will be removed in v4.
+     */
+    scanHiddenFolders?: boolean | undefined;
+    /**
+     * - Object merged into the per-request context accessible inside API functions via `import { context } from "@cldmv/slothlet/runtime"`.
+     */
+    context?: object | null | undefined;
+    /**
+     * - Object whose properties are merged directly onto the root API and also available as `api.slothlet.reference`.
+     */
+    reference?: object | null | undefined;
+    /**
+     * - Controls how per-request scope data is merged. `"shallow"` merges top-level keys; `"deep"` recurses into nested objects.
+     */
+    scope?: {
+        merge: "shallow" | "deep";
+    } | undefined;
+    /**
+     * - API build and mutation settings.
+     */
+    api?: {
+        /**
+         * - Collision strategy when two modules export the same path.
+         * Modes: `"merge"` (default), `"merge-replace"`, `"replace"`, `"skip"`, `"warn"`, `"error"`.
+         * Pass an object to use different strategies for the initial build vs. runtime `api.slothlet.api.add()` calls.
+         */
+        collision?: string | {
+            initial: string;
+            api: string;
+        } | undefined;
+        /**
+         * - Enable or disable runtime mutation methods on `api.slothlet.api`.
+         * Object with boolean keys `add`, `remove`, `reload` (all default `true`).
+         */
+        mutations?: object | undefined;
+    } | undefined;
+    /**
+     * - Hook system configuration.
+     * - `false` — disabled (default).
+     * - `true` — enabled, all endpoints.
+     * - `string` — enabled with a default glob pattern.
+     * - `object` — full control: `{ enabled: boolean, pattern?: string, suppressErrors?: boolean }`.
+     */
+    hook?: string | boolean | object | undefined;
+    /**
+     * - Enable verbose internal logging. `true` enables all categories.
+     * Pass an object with sub-keys `builder`, `api`, `index`, `modes`, `wrapper`, `ownership`, `context` to target specific subsystems.
+     */
+    debug?: boolean | object | undefined;
+    /**
+     * - Suppress all console output from slothlet (warnings, deprecations). Does not affect `debug`.
+     */
+    silent?: boolean | undefined;
+    /**
+     * - Enable the `api.slothlet.diag.*` introspection namespace. Intended for testing; do not enable in production.
+     */
+    diagnostics?: boolean | undefined;
+    /**
+     * - Construction-time lifecycle subscribers, registered on the lifecycle emitter BEFORE the api builds so events emitted during cold-start `buildAPI` (init-time `impl:warning` / `impl:created` / …) are observable. Maps an event name to a handler `function(data, token)` or an array of them; any event name is accepted. Because they are ordinary subscribers, they also receive runtime events afterward — equivalent to calling `api.slothlet.lifecycle.on(event, fn)` for each, but early enough to catch initialization diagnostics. Example: `{ "impl:warning": (d) => log(d), "impl:error": [onError, audit] }`.
+     */
+    lifecycle?: {
+        [x: string]: Function | Function[];
+    } | undefined;
+    /**
+     * - DEPRECATED — will be removed in v4. Expands into two implicit `routines` entries (`{name: "^**.shutdown", mode: "shutdown", order: "depth"}` and the `destroy` equivalent) reproducing this option's original whole-tree, cross-mount, deepest-first scope for literally-named `shutdown`/`destroy` leaves, dropping any existing `shutdown`/`destroy`-mode routine (including the built-in `shutdown` default) in favor of these — and sets the effective `autoRoutines` to `true` unless `autoRoutines` is given explicitly. Nested hooks remain directly callable regardless. Emits a `V3_CONFIG_DEPRECATED` warning unless `silent: true`.
+     */
+    collectLifecycleHooks?: boolean | undefined;
+    /**
+     * - Stackable lifecycle routines (#341). Every mounted module exporting a function matching a configured routine name is composed into one callable at its exact composed api path, plus a root cascade (`self.<name>()` ≡ `api.slothlet.<name>()`) that runs every matching contribution anywhere. Entries: `"name"` (mode `"manual"`), `"name:mode"`, or `{ name, mode?, recursive?, order? }` (`recursive`/`order` only settable via the object form). `name` is mount-relative by default (a bare name matches only a mount's own top level; a dotted name matches a fixed relative sub-path, or with `recursive: true` any depth within the mount); a `^`-prefixed name is root-anchored, matched via glob (`*`, `**`, `{}`, `!`) against the full api path, crossing mount boundaries. `order` (`"mount"` | `"depth"`, mode-defaulted) controls the root cascade's grouping order. Providing `routines` at all REPLACES the built-in defaults (`slothlet.defaults.routines`: `initialize` → `startup`, `shutdown` → `shutdown`) — spread `slothlet.defaults.routines` to extend them instead, or pass `[]` to disable every routine. Every configured routine is always wrapped and directly callable regardless of `autoRoutines`. Whether two or more contributors colliding at the identical api path all run is governed by `stackRoutines` (#365), independent of `collisionMode` — by default only the single contribution that actually owns that path runs, matching ordinary collision behavior. A throwing contributor doesn't stop the chain — every contributor runs (best-effort), and one aggregate `ROUTINE_FAILED` error is thrown afterward if any failed. See [LIFECYCLE.md](docs/LIFECYCLE.md#routines).
+     */
+    routines?: (string | {
+        name: string;
+        mode?: ("manual" | "startup" | "shutdown" | "destroy");
+        recursive?: boolean;
+        order?: ("mount" | "depth");
+    })[] | undefined;
+    /**
+     * - The non-deprecated replacement for `collectLifecycleHooks`. TEMPORARY v3-compat default (#341): `false` for now, so a project upgrading sees no behavior change from a pre-existing nested leaf that happens to share a routine's name (e.g. `shutdown`) — it stays stacked and directly callable, but does not start auto-firing. When `true`, every `mode: "startup"` routine's cascade runs at the end of compose, and every `mode: "shutdown"`/`"destroy"` routine's cascade runs on the corresponding dispose call. Planned to default to `true` in v4 (`collectLifecycleHooks` removed at the same time) — see [LIFECYCLE.md](docs/LIFECYCLE.md#routines).
+     */
+    autoRoutines?: boolean | undefined;
+    /**
+     * - Whether two or more modules' contributions colliding at the exact same composed api path all run, or only the single contribution that actually owns that path (per `collisionMode`) runs (#365). `false` by default, matching ordinary (non-routine) collision behavior everywhere else in the framework. Deliberately independent of `collisionMode` — a module that loses a collision, under any mode, does not run via the routine system unless this is explicitly `true`. The root cascade runs every matching contribution across distinct api paths regardless of this flag; where two or more contributions land on the identical api path, the cascade applies the same filtering a direct call at that path would. See [LIFECYCLE.md](docs/LIFECYCLE.md#stackroutines).
+     */
+    stackRoutines?: boolean | undefined;
+    /**
+     * - Enable internal tracking. Pass `true` or `{ materialization: true }` to track lazy-mode materialization progress.
+     */
+    tracking?: boolean | object | undefined;
+    /**
+     * - When `mode: "lazy"`, immediately begins materializing all paths in the background after init.
+     */
+    backgroundMaterialize?: boolean | undefined;
+    /**
+     * - Internationalization settings (dev-facing, process-global).
+     * `{ language: string }` — selects the locale for framework messages (e.g. `"en-us"`, `"fr-fr"`, `"ja-jp"`).
+     */
+    i18n?: object | undefined;
+    /**
+     * - Execution-environment target. Controls whether filesystem-dependent code paths run. Independent of `env` (the `process.env` snapshot).
+     * - `"browser"` — browser/worker/Electron-renderer mode. Skips filesystem operations and the `process.env` snapshot. Requires `manifest`.
+     * - `"node"` — explicit Node.js mode.
+     * - Omitted — auto-detected: `"browser"` when a `manifest` is provided (or no Node `process` is present), `"node"` otherwise.
+     */
+    platform?: "browser" | "node" | undefined;
+    /**
+     * - `process.env` snapshot configuration (Node mode). Independent of `platform`.
+     * - `{ include: ["KEY"] }` — allowlist; only the listed keys are captured in `api.slothlet.env`. Non-string entries are silently ignored; an all-non-string array falls back to the full snapshot.
+     * - Omitted / `null` — the full `process.env` snapshot is captured.
+     */
+    env?: object | null | undefined;
+    /**
+     * - Allowlist of environment variable names to capture. Only string entries are used.
+     */
+    include?: string[] | undefined;
+    /**
+     * - Pre-generated directory structure for browser mode.
+     * Produced at build time by `generateManifest()` from `@cldmv/slothlet/helpers/generate-manifest`. Required when `platform: "browser"`.
+     * Presence of `manifest` auto-triggers browser mode without needing an explicit `platform: "browser"`.
+     */
+    manifest?: {
+        files: Array<{
+            path: string;
+            name: string;
+            fullName: string;
+        }>;
+        directories: any[];
+    } | undefined;
+    /**
+     * - Browser-mode module resolver: `(fileEntry: {path, name, fullName}) => string | URL`.
+     * Maps a manifest file entry to an importable URL or bare specifier. Defaults to resolving against `base` as a `file://` URL.
+     * Override to point at a CDN, bundler virtual module, or other browser-friendly source.
+     */
+    resolveModuleSpecifier?: Function | undefined;
+    /**
+     * - Injectable leaf importer: `(specifier: string) => Promise<object>`.
+     * Every leaf module load is routed through it instead of slothlet's own dynamic `import()`, so the
+     * modules land in the caller's module graph rather than slothlet's. Pass `(s) => import(s)` written
+     * inside the consumer's own (transformed) code to make a coverage run attribute leaf execution
+     * correctly; unset, slothlet imports natively exactly as before. See [`docs/TESTING.md`](../docs/TESTING.md).
+     */
+    import?: Function | undefined;
+    /**
+     * - Opt out of specific bug-fix behaviors that landed in v3 and become permanent in v4.
+     * Each entry uses the `<rule>_<PR>` form (e.g. `"C03_116"`). Each listed rule emits a `WARN_SUPPRESS_FIX_ACTIVE` deprecation warning unless `silent: true`.
+     * Temporary escape hatch — will be removed in v4 when the corrected behaviors become permanent.
+     */
+    suppressFixes?: string[] | undefined;
+    /**
+     * - TypeScript support.
+     * - `false` — disabled (default).
+     * - `true` or `"fast"` — esbuild transpilation, no type checking.
+     * - `"strict"` — tsc compilation with type checking and `.d.ts` generation.
+     * See [TYPESCRIPT.md](docs/TYPESCRIPT.md) for the full configuration reference.
+     */
+    typescript?: boolean | object | "strict" | "fast" | undefined;
+    /**
+     * - Version routing discriminator for versioned API paths.
+     * - **string** (e.g. `"version"`) — at dispatch time, reads that key from the calling module's version metadata to select a version tag.
+     * - **function** — called as `(allVersions, caller) => versionTag | null`; return a registered version tag to force routing, or `null`/`undefined` to fall through to the automatic default.
+     * - **omitted / `undefined`** — behaves identically to `"version"`.
+     * Only relevant when modules are registered via `api.slothlet.api.add()` with a `versionConfig` argument.
+     */
+    versionDispatcher?: string | Function | null | undefined;
+};
+/**
+ * Bound API object returned by `slothlet()`.
+ * The root contains all loaded module exports plus the reserved `slothlet` namespace.
+ */
+export type SlothletAPI = {
+    /**
+     * - Like `shutdown()` but additionally invokes registered destroy hooks before teardown. %%sig: (): void%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api' });|await api.destroy();%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api' });|  await api.destroy();|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api' });|  await api.destroy();|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api' });|await api.destroy();%%
+     */
+    destroy: () => void;
+    /**
+     * - Convenience alias for `slothlet.shutdown()`. Shuts down the instance and invokes any user-provided shutdown hook first. %%sig: (): void%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api' });|await api.shutdown();%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api' });|  await api.shutdown();|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api' });|  await api.shutdown();|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api' });|await api.shutdown();%%
+     */
+    shutdown: () => void;
+    /**
+     * - Built-in control namespace. All framework internals live here to avoid collisions with loaded modules.
+     */
+    slothlet: {
+        env: Readonly<Record<string, string | undefined>>;
+        api: {
+            add: Function;
+            reload: Function;
+            remove: Function;
+            leaves: Function;
+            modules: {
+                discover: Function;
+                sort: Function;
+                addModule: Function;
+                addModules: Function;
+                removeModule: Function;
+                addDiscovered: Function;
+                getDiscoveryCache: Function;
+                clearDiscoveryCache: Function;
+                getStaleMounts: Function;
+            };
+        };
+        context: {
+            get: Function;
+            inspect: () => Object;
+            run: Function;
+            scope: Function;
+            set: Function;
+        };
+        diag?: {
+            /**
+             * - Cache diagnostics sub-namespace.
+             */
+            caches?: {
+                /**
+                 * - Get full cache diagnostic data (`{ totalCaches, caches[] }`). Only available when `diagnostics: true`. %%sig: (): Object%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api', diagnostics: true });|const cacheData = api.slothlet.diag.caches.get();|// { totalCaches: 2, caches: [...] }%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api', diagnostics: true });|  const cacheData = api.slothlet.diag.caches.get();|  // { totalCaches: 2, caches: [...] }|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api', diagnostics: true });|  const cacheData = api.slothlet.diag.caches.get();|  // { totalCaches: 2, caches: [...] }|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api', diagnostics: true });|const cacheData = api.slothlet.diag.caches.get();|// { totalCaches: 2, caches: [...] }%%
+                 */
+                get?: (() => Object) | undefined;
+                /**
+                 * - Return all moduleIDs currently in cache. Only available when `diagnostics: true`. %%sig: (): string[]%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api', diagnostics: true });|const ids = api.slothlet.diag.caches.getAllModuleIDs();|// ['utils/math.mjs', 'utils/strings.mjs']%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api', diagnostics: true });|  const ids = api.slothlet.diag.caches.getAllModuleIDs();|  // ['utils/math.mjs', 'utils/strings.mjs']|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api', diagnostics: true });|  const ids = api.slothlet.diag.caches.getAllModuleIDs();|  // ['utils/math.mjs', 'utils/strings.mjs']|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api', diagnostics: true });|const ids = api.slothlet.diag.caches.getAllModuleIDs();|// ['utils/math.mjs', 'utils/strings.mjs']%%
+                 */
+                getAllModuleIDs?: (() => string[]) | undefined;
+                /**
+                 * - Check whether a cache entry exists for a given moduleID. Only available when `diagnostics: true`. %%sig: (moduleID: string): boolean%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api', diagnostics: true });|const exists = api.slothlet.diag.caches.has('utils/math.mjs'); // true or false%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api', diagnostics: true });|  const exists = api.slothlet.diag.caches.has('utils/math.mjs'); // true or false|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api', diagnostics: true });|  const exists = api.slothlet.diag.caches.has('utils/math.mjs'); // true or false|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api', diagnostics: true });|const exists = api.slothlet.diag.caches.has('utils/math.mjs'); // true or false%%
+                 */
+                has?: Function | undefined;
+            } | undefined;
+            /**
+             * - The `context` config value as passed to `slothlet()`.
+             */
+            context?: object | undefined;
+            /**
+             * - Describe API structure. Pass `true` to return the full API object; omit for top-level keys only. Only available when `diagnostics: true`. %%sig: ([showAll]: boolean): *%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api', diagnostics: true });|const keys = api.slothlet.diag.describe();|const full = api.slothlet.diag.describe(true);%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api', diagnostics: true });|  const keys = api.slothlet.diag.describe();|  const full = api.slothlet.diag.describe(true);|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api', diagnostics: true });|  const keys = api.slothlet.diag.describe();|  const full = api.slothlet.diag.describe(true);|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api', diagnostics: true });|const keys = api.slothlet.diag.describe();|const full = api.slothlet.diag.describe(true);%%
+             */
+            describe?: Function | undefined;
+            /**
+             * - Return the live bound API proxy object. Only available when `diagnostics: true`. %%sig: (): Object%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api', diagnostics: true });|const proxy = api.slothlet.diag.getAPI(); // the live bound API proxy%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api', diagnostics: true });|  const proxy = api.slothlet.diag.getAPI(); // the live bound API proxy|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api', diagnostics: true });|  const proxy = api.slothlet.diag.getAPI(); // the live bound API proxy|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api', diagnostics: true });|const proxy = api.slothlet.diag.getAPI(); // the live bound API proxy%%
+             */
+            getAPI?: (() => Object) | undefined;
+            /**
+             * - Return ownership diagnostics for all registered API paths. Only available when `diagnostics: true`. %%sig: (): Object%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api', diagnostics: true });|const ownership = api.slothlet.diag.getOwnership();%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api', diagnostics: true });|  const ownership = api.slothlet.diag.getOwnership();|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api', diagnostics: true });|  const ownership = api.slothlet.diag.getOwnership();|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api', diagnostics: true });|const ownership = api.slothlet.diag.getOwnership();%%
+             */
+            getOwnership?: (() => Object) | undefined;
+            /**
+             * - Hook system diagnostics sub-namespace (present only when hooks are enabled).
+             */
+            hook?: object | undefined;
+            /**
+             * - Return a full diagnostic snapshot of current instance state. Only available when `diagnostics: true`. %%sig: (): Object%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api', diagnostics: true });|const snapshot = api.slothlet.diag.inspect();|console.log(snapshot.modules, snapshot.hooks);%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api', diagnostics: true });|  const snapshot = api.slothlet.diag.inspect();|  console.log(snapshot.modules, snapshot.hooks);|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api', diagnostics: true });|  const snapshot = api.slothlet.diag.inspect();|  console.log(snapshot.modules, snapshot.hooks);|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api', diagnostics: true });|const snapshot = api.slothlet.diag.inspect();|console.log(snapshot.modules, snapshot.hooks);%%
+             */
+            inspect?: (() => Object) | undefined;
+            /**
+             * - Ownership sub-namespace for diagnostics.
+             */
+            owner?: {
+                /**
+                 * - Get the owning moduleIDs for a specific API path. Only available when `diagnostics: true`. %%sig: (apiPath: string): string[]%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api', diagnostics: true });|const owners = api.slothlet.diag.owner.get('math.add');|// ['utils/math.mjs']%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api', diagnostics: true });|  const owners = api.slothlet.diag.owner.get('math.add');|  // ['utils/math.mjs']|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api', diagnostics: true });|  const owners = api.slothlet.diag.owner.get('math.add');|  // ['utils/math.mjs']|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api', diagnostics: true });|const owners = api.slothlet.diag.owner.get('math.add');|// ['utils/math.mjs']%%
+                 */
+                get?: Function | undefined;
+            } | undefined;
+            /**
+             * - The `reference` config value as passed to `slothlet()`.
+             */
+            reference?: object | undefined;
+            /**
+             * - The `SlothletWarning` class — access `.captured` for warnings emitted during tests. Only available when `diagnostics: true`. %%sig: (): SlothletWarning%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ base: './api', diagnostics: true });|const SlothletWarning = api.slothlet.diag.SlothletWarning;|console.log(SlothletWarning.captured); // array of captured warnings%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ base: './api', diagnostics: true });|  const SlothletWarning = api.slothlet.diag.SlothletWarning;|  console.log(SlothletWarning.captured); // array of captured warnings|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ base: './api', diagnostics: true });|  const SlothletWarning = api.slothlet.diag.SlothletWarning;|  console.log(SlothletWarning.captured); // array of captured warnings|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ base: './api', diagnostics: true });|const SlothletWarning = api.slothlet.diag.SlothletWarning;|console.log(SlothletWarning.captured); // array of captured warnings%%
+             */
+            SlothletWarning?: (() => SlothletWarning) | undefined;
+        } | undefined;
+        hook: {
+            clear: Function;
+            disable: Function;
+            disablePattern: Function;
+            enable: Function;
+            enablePattern: Function;
+            list: Function;
+            off: Function;
+            on: Function;
+            pin: {
+                enabled: boolean;
+                enable: Function;
+                disable: Function;
+            };
+            remove: Function;
+            resetPatternFilter: Function;
+        };
+        lifecycle: {
+            off: Function;
+            on: Function;
+        };
+        materialize: {
+            get: () => Object;
+            materialized: boolean;
+            wait: () => Promise<void>;
+        };
+        metadata: {
+            caller: () => Object | null;
+            get: Function;
+            remove: Function;
+            getFor: Function;
+            removeFor: Function;
+            self: () => Object | null;
+            set: Function;
+            setFor: Function;
+            setGlobal: Function;
+        };
+        owner: {
+            get: Function;
+        };
+        ownership: {
+            get: Function;
+            unregister: Function;
+        };
+        permissions: {
+            control: {
+                enabled: boolean;
+                enable: () => void;
+                disable: () => void;
+                readGatingEnabled: boolean;
+                readGating: (arg0: boolean) => void;
+                seal: () => void;
+                sealed: boolean;
+            };
+        };
+        versioning: {
+            list: Function;
+            setDefault: Function;
+            unregister: Function;
+            getVersionMetadata: Function;
+            setVersionMetadata: Function;
+        };
+        lockCaller: Function;
+        bind: Function;
+        reference?: object | undefined;
+        reload: Function;
+        run: Function;
+        scope: Function;
+        shutdown: () => Promise<void>;
+    };
+};
+import { SlothletWarning } from "@cldmv/slothlet/errors";