apcore-js 0.17.1 → 0.19.0

package/dist/registry/registry.d.ts

@@ -17,10 +17,15 @@ export declare const REGISTRY_EVENTS: Readonly<{
 export declare const MODULE_ID_PATTERN: RegExp;
 /**
  * Maximum allowed length for a module ID.
+ *
+ * Per PROTOCOL_SPEC §2.7 EBNF constraint #1. 192 is filesystem-safe
+ * (192 + ".binding.yaml".length = 205 < 255-byte filename limit on
+ * ext4/xfs/NTFS/APFS/btrfs) and accommodates Java/.NET deep-namespace
+ * FQN-derived IDs. Bumped from 128 in spec 1.6.0-draft (2026-04-08).
  */
-export declare const MAX_MODULE_ID_LENGTH = 128;
+export declare const MAX_MODULE_ID_LENGTH = 192;
 /**
- * Reserved words that cannot appear as any segment of a module ID.
+ * Reserved words that cannot appear as the first segment of a module ID.
  */
 export declare const RESERVED_WORDS: Set<string>;
 /**
@@ -48,6 +53,7 @@ export declare class Registry {
     private _moduleMeta;
     private _callbacks;
     private _idMap;
+    private _lowercaseMap;
     private _schemaCache;
     private _config;
     private _watchers?;
@@ -79,7 +85,16 @@ export declare class Registry {
     private _validateAll;
     private _resolveLoadOrder;
     private _registerInOrder;
+    /**
+     * Register a module.
+     *
+     * Validation order (PROTOCOL_SPEC §2.7, aligned with apcore-python and
+     * apcore-rust): empty → pattern → length → reserved (per-segment) →
+     * duplicate.
+     */
     register(moduleId: string, module: unknown): void;
+    /** Inner registration — no validator, no ID validation. Used by discover() paths that run their own checks. */
+    private _registerImpl;
     unregister(moduleId: string): boolean;
     get(moduleId: string): unknown | null;
     has(moduleId: string): boolean;
@@ -93,6 +108,8 @@ export declare class Registry {
     getDefinition(moduleId: string): ModuleDescriptor | null;
     describe(moduleId: string): string;
     on(event: string, callback: EventCallback): void;
+    off(event: string, callback: EventCallback): boolean;
+    reload(): Promise<number>;
     private _triggerEvent;
     watch(): Promise<void>;
     unwatch(): void;
@@ -100,10 +117,25 @@ export declare class Registry {
     private _handleFileDeletion;
     private _pathToModuleId;
     /**
-     * Register a module bypassing reserved-word checks.
-     * Used exclusively by the sys-modules subsystem for system.* IDs.
+     * Register a sys/internal module that bypasses **only** the reserved word
+     * check. All other PROTOCOL_SPEC §2.7 validations (empty, EBNF pattern,
+     * length, duplicate) still apply.
+     *
+     * Used exclusively by the sys-modules subsystem for `system.*` IDs.
+     * Aligned with apcore-python `Registry.register_internal` and apcore-rust
+     * `Registry::register_internal`.
      */
     registerInternal(moduleId: string, module: unknown): void;
+    /**
+     * Export the JSON Schema for a registered module.
+     *
+     * Returns the schema as a plain object (`Record<string, unknown> | null`),
+     * matching Python's `dict | None` and Rust's `Option<Value>` return types.
+     * Returns `null` if the module is not registered.
+     * Use the standalone `exportSchema` function from `schema-export.ts` for
+     * serialized (JSON/YAML) output.
+     */
+    exportSchema(moduleId: string, strict?: boolean): Record<string, unknown> | null;
     clearCache(): void;
     /**
      * Number of in-flight executions per module.
@@ -133,6 +165,10 @@ export declare class Registry {
     beginDrain(moduleId: string): void;
     /**
      * Remove the draining mark and clean up drain state.
+     *
+     * If any waitDrained waiters are still pending (e.g., refCount briefly
+     * hit zero and then a new acquire bumped it back up), resolve them first
+     * so they do not wait for their individual timeouts before returning.
      */
     endDrain(moduleId: string): void;
     /**

package/dist/registry/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry/registry.ts"],"names":[],"mappings":"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"}

package/dist/registry/registry.js

@@ -1,10 +1,15 @@
 /**
  * Central module registry for discovering, registering, and querying modules.
  */
+import { getDefault } from '../config.js';
 import { InvalidInputError, ModuleNotFoundError } from '../errors.js';
+import { detectIdConflicts } from './conflicts.js';
 import { resolveDependencies } from './dependencies.js';
 import { resolveEntryPoint } from './entry-point.js';
 import { mergeModuleMetadata, parseDependencies } from './metadata.js';
+import { getSchema } from './schema-export.js';
+import { toStrictSchema } from '../schema/strict.js';
+import { deepCopy } from '../utils/index.js';
 import { validateModule } from './validation.js';
 // ── Lazy-loaded Node.js modules ────────────────────────────────────
 // These are loaded on first use so that importing Registry in a browser
@@ -52,12 +57,56 @@ export const REGISTRY_EVENTS = Object.freeze({
 export const MODULE_ID_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
 /**
  * Maximum allowed length for a module ID.
+ *
+ * Per PROTOCOL_SPEC §2.7 EBNF constraint #1. 192 is filesystem-safe
+ * (192 + ".binding.yaml".length = 205 < 255-byte filename limit on
+ * ext4/xfs/NTFS/APFS/btrfs) and accommodates Java/.NET deep-namespace
+ * FQN-derived IDs. Bumped from 128 in spec 1.6.0-draft (2026-04-08).
  */
-export const MAX_MODULE_ID_LENGTH = 128;
+export const MAX_MODULE_ID_LENGTH = 192;
 /**
- * Reserved words that cannot appear as any segment of a module ID.
+ * Reserved words that cannot appear as the first segment of a module ID.
  */
 export const RESERVED_WORDS = new Set(['system', 'internal', 'core', 'apcore', 'plugin', 'schema', 'acl']);
+/**
+ * Validate a module ID against PROTOCOL_SPEC §2.7 in canonical order.
+ *
+ * Order: empty → pattern → length → reserved (first-segment).
+ * Duplicate detection is the caller's responsibility (it requires registry
+ * state).
+ *
+ * When `allowReserved` is true the first-segment reserved word check is
+ * skipped — used by `Registry.registerInternal` so sys modules can use the
+ * `system.*` prefix. All other validations (empty, pattern, length) still
+ * apply.
+ *
+ * Aligned with `apcore-python._validate_module_id` and
+ * `apcore::registry::registry::validate_module_id`.
+ *
+ * @internal
+ */
+function validateModuleId(moduleId, allowReserved) {
+    // 1. empty check (message byte-aligned with apcore-python and apcore-rust)
+    if (!moduleId || typeof moduleId !== 'string') {
+        throw new InvalidInputError('module_id must be a non-empty string');
+    }
+    // 2. EBNF pattern check (message byte-aligned with apcore-python and apcore-rust:
+    // single quotes around the offending ID; bare regex source without /…/ delimiters)
+    if (!MODULE_ID_PATTERN.test(moduleId)) {
+        throw new InvalidInputError(`Invalid module ID: '${moduleId}'. Must match pattern: ${MODULE_ID_PATTERN.source} (lowercase, digits, underscores, dots only; no hyphens)`);
+    }
+    // 3. length check
+    if (moduleId.length > MAX_MODULE_ID_LENGTH) {
+        throw new InvalidInputError(`Module ID exceeds maximum length of ${MAX_MODULE_ID_LENGTH}: ${moduleId.length}`);
+    }
+    // 4. reserved word first-segment check (skipped for registerInternal)
+    if (!allowReserved) {
+        const firstSegment = moduleId.split('.')[0];
+        if (RESERVED_WORDS.has(firstSegment)) {
+            throw new InvalidInputError(`Module ID contains reserved word: '${firstSegment}'`);
+        }
+    }
+}
 export class Registry {
     _extensionRoots;
     _modules = new Map();
@@ -67,6 +116,7 @@ export class Registry {
         [REGISTRY_EVENTS.UNREGISTER, []],
     ]);
     _idMap = {};
+    _lowercaseMap = new Map();
     _schemaCache = new Map();
     _config;
     _watchers;
@@ -94,10 +144,10 @@ export class Registry {
         }
         else if (config !== null) {
             const extRoot = config.get('extensions.root');
-            this._extensionRoots = [{ root: extRoot ?? './extensions' }];
+            this._extensionRoots = [{ root: extRoot ?? getDefault('extensions.root') }];
         }
         else {
-            this._extensionRoots = [{ root: './extensions' }];
+            this._extensionRoots = [{ root: getDefault('extensions.root') }];
         }
         this._config = config;
         this._idMapPath = options?.idMapPath ?? null;
@@ -124,9 +174,21 @@ export class Registry {
     async _discoverCustom() {
         const rootPaths = this._extensionRoots.map((r) => r['root']);
         const customModules = await this._customDiscoverer.discover(rootPaths);
+        if (!Array.isArray(customModules)) {
+            console.warn(`[apcore:registry] Custom discoverer returned non-array (${typeof customModules}); expected Array<{moduleId, module}>. Ignoring.`);
+            return 0;
+        }
         let count = 0;
         for (const entry of customModules) {
+            if (entry === null || typeof entry !== 'object') {
+                console.warn(`[apcore:registry] Malformed entry from custom discoverer (expected object, got ${entry === null ? 'null' : typeof entry}); skipping.`);
+                continue;
+            }
             const { moduleId, module: mod } = entry;
+            if (typeof moduleId !== 'string' || mod === undefined) {
+                console.warn(`[apcore:registry] Malformed entry from custom discoverer (missing 'moduleId' string or 'module'); skipping.`);
+                continue;
+            }
             // Apply custom validator if set
             if (this._customValidator !== null) {
                 const errors = await this._customValidator.validate(mod);
@@ -136,7 +198,7 @@ export class Registry {
                 }
             }
             try {
-                this.register(moduleId, mod);
+                this._registerImpl(moduleId, mod);
                 count++;
             }
             catch (e) {
@@ -180,7 +242,13 @@ export class Registry {
                         ? dm.filePath.slice(root.length + 1)
                         : null;
                     if (relPath && relPath in this._idMap) {
-                        dm.canonicalId = this._idMap[relPath]['id'];
+                        const rawId = this._idMap[relPath]['id'];
+                        if (typeof rawId === 'string' && rawId.length > 0) {
+                            dm.canonicalId = rawId;
+                        }
+                        else {
+                            console.warn(`[apcore:registry] ID map entry for '${relPath}' has invalid 'id' field (got ${typeof rawId}), skipping override`);
+                        }
                         break;
                     }
                 }
@@ -229,13 +297,33 @@ export class Registry {
     }
     _resolveLoadOrder(validModules, rawMetadata) {
         const modulesWithDeps = [];
-        for (const modId of validModules.keys()) {
+        const moduleVersions = new Map();
+        for (const [modId, cls] of validModules.entries()) {
             const meta = rawMetadata.get(modId) ?? {};
             const depsRaw = meta['dependencies'] ?? [];
             modulesWithDeps.push([modId, depsRaw.length > 0 ? parseDependencies(depsRaw) : []]);
+            const yamlVersion = meta['version'];
+            const codeVersion = cls?.version;
+            const resolvedVersion = (typeof yamlVersion === 'string' && yamlVersion) ||
+                (typeof codeVersion === 'string' && codeVersion) ||
+                '1.0.0';
+            moduleVersions.set(modId, resolvedVersion);
+        }
+        // Include already-registered modules so inter-batch version constraints
+        // resolve against the live registry too.
+        for (const [existingId, existingMod] of this._modules.entries()) {
+            if (!moduleVersions.has(existingId)) {
+                const existingVersion = existingMod?.version;
+                if (typeof existingVersion === 'string') {
+                    moduleVersions.set(existingId, existingVersion);
+                }
+            }
         }
-        const knownIds = new Set(modulesWithDeps.map(([id]) => id));
-        return resolveDependencies(modulesWithDeps, knownIds);
+        const knownIds = new Set([
+            ...modulesWithDeps.map(([id]) => id),
+            ...this._modules.keys(),
+        ]);
+        return resolveDependencies(modulesWithDeps, knownIds, moduleVersions);
     }
     _registerInOrder(loadOrder, validModules, rawMetadata) {
         let count = 0;
@@ -245,6 +333,7 @@ export class Registry {
             const mergedMeta = mergeModuleMetadata(modObj, rawMetadata.get(modId) ?? {});
             this._modules.set(modId, mod);
             this._moduleMeta.set(modId, mergedMeta);
+            this._lowercaseMap.set(modId.toLowerCase(), modId);
             if (typeof modObj['onLoad'] === 'function') {
                 try {
                     modObj['onLoad']();
@@ -253,6 +342,7 @@ export class Registry {
                     console.warn(`[apcore:registry] onLoad failed for ${modId}, skipping:`, e);
                     this._modules.delete(modId);
                     this._moduleMeta.delete(modId);
+                    this._lowercaseMap.delete(modId.toLowerCase());
                     continue;
                 }
             }
@@ -261,26 +351,40 @@ export class Registry {
         }
         return count;
     }
+    /**
+     * Register a module.
+     *
+     * Validation order (PROTOCOL_SPEC §2.7, aligned with apcore-python and
+     * apcore-rust): empty → pattern → length → reserved (per-segment) →
+     * duplicate.
+     */
     register(moduleId, module) {
-        if (!moduleId || typeof moduleId !== "string") {
-            throw new InvalidInputError("Module ID must be a non-empty string");
-        }
-        if (!MODULE_ID_PATTERN.test(moduleId)) {
-            throw new InvalidInputError(`Invalid module ID: "${moduleId}". Must match pattern: ${MODULE_ID_PATTERN} (lowercase, digits, underscores, dots only; no hyphens)`);
-        }
-        const parts = moduleId.split('.');
-        for (const part of parts) {
-            if (RESERVED_WORDS.has(part)) {
-                throw new InvalidInputError(`Module ID contains reserved word: '${part}'`);
+        validateModuleId(moduleId, false);
+        if (this._customValidator !== null) {
+            const result = this._customValidator.validate(module);
+            if (result instanceof Promise) {
+                throw new InvalidInputError(`Custom validator for '${moduleId}' is async — use discover() which awaits the validator, or register after awaiting validation manually.`);
+            }
+            if (result.length > 0) {
+                throw new InvalidInputError(`Custom validator rejected module '${moduleId}': ${result.join('; ')}`);
             }
         }
-        if (moduleId.length > MAX_MODULE_ID_LENGTH) {
-            throw new InvalidInputError(`Module ID exceeds maximum length of ${MAX_MODULE_ID_LENGTH}: ${moduleId.length}`);
-        }
-        if (this._modules.has(moduleId)) {
-            throw new InvalidInputError(`Module already exists: ${moduleId}`);
+        this._registerImpl(moduleId, module);
+    }
+    /** Inner registration — no validator, no ID validation. Used by discover() paths that run their own checks. */
+    _registerImpl(moduleId, module) {
+        // Algorithm A03: detect ID conflicts (exact duplicate, reserved word, case collision)
+        const conflict = detectIdConflicts(moduleId, new Set(this._modules.keys()), RESERVED_WORDS, this._lowercaseMap);
+        if (conflict !== null) {
+            if (conflict.severity === 'error') {
+                throw new InvalidInputError(conflict.message);
+            }
+            else {
+                console.warn(`[apcore:registry] ID conflict: ${conflict.message}`);
+            }
         }
         this._modules.set(moduleId, module);
+        this._lowercaseMap.set(moduleId.toLowerCase(), moduleId);
         // Populate metadata from the module object
         const modObj = module;
         this._moduleMeta.set(moduleId, mergeModuleMetadata(modObj, {}));
@@ -292,6 +396,7 @@ export class Registry {
             catch (e) {
                 this._modules.delete(moduleId);
                 this._moduleMeta.delete(moduleId);
+                this._lowercaseMap.delete(moduleId.toLowerCase());
                 throw e;
             }
         }
@@ -304,6 +409,7 @@ export class Registry {
         this._modules.delete(moduleId);
         this._moduleMeta.delete(moduleId);
         this._schemaCache.delete(moduleId);
+        this._lowercaseMap.delete(moduleId.toLowerCase());
         // Call onUnload if available
         const modObj = module;
         if (typeof modObj['onUnload'] === 'function') {
@@ -363,21 +469,27 @@ export class Registry {
         const module = this._modules.get(moduleId);
         if (module == null)
             return null;
+        // INVARIANT: every registration site (`register`, `registerInternal`,
+        // `_discoverDefault`) populates `_moduleMeta` via `mergeModuleMetadata`,
+        // so `meta` always contains the full set of canonical keys including
+        // an `annotations` slot. Read fields directly from it. The schemas
+        // come straight from the module instance because they are not part
+        // of the merged metadata payload.
         const meta = this._moduleMeta.get(moduleId) ?? {};
         const mod = module;
         return {
             moduleId,
-            name: (meta['name'] ?? mod['name']) ?? null,
-            description: (meta['description'] ?? mod['description']) ?? '',
-            documentation: (meta['documentation'] ?? mod['documentation']) ?? null,
+            name: meta['name'] ?? null,
+            description: meta['description'] ?? '',
+            documentation: meta['documentation'] ?? null,
             inputSchema: mod['inputSchema'] ?? {},
             outputSchema: mod['outputSchema'] ?? {},
-            version: (meta['version'] ?? mod['version']) ?? '1.0.0',
-            tags: meta['tags'] ?? mod['tags'] ?? [],
-            annotations: mod['annotations'] ?? null,
-            examples: mod['examples'] ?? [],
+            version: meta['version'] ?? '1.0.0',
+            tags: meta['tags'] ?? [],
+            annotations: meta['annotations'] ?? null,
+            examples: meta['examples'] ?? [],
             metadata: meta['metadata'] ?? {},
-            sunsetDate: (meta['sunsetDate'] ?? mod['sunsetDate']) ?? null,
+            sunsetDate: meta['sunsetDate'] ?? null,
         };
     }
     describe(moduleId) {
@@ -426,6 +538,21 @@ export class Registry {
         }
         this._callbacks.get(event).push(callback);
     }
+    off(event, callback) {
+        const validEvents = Object.values(REGISTRY_EVENTS);
+        if (!validEvents.includes(event)) {
+            throw new InvalidInputError(`Invalid event: ${event}. Must be one of: ${validEvents.map((e) => `'${e}'`).join(', ')}`);
+        }
+        const callbacks = this._callbacks.get(event);
+        const idx = callbacks.indexOf(callback);
+        if (idx === -1)
+            return false;
+        callbacks.splice(idx, 1);
+        return true;
+    }
+    async reload() {
+        return this.discover();
+    }
     _triggerEvent(event, moduleId, module) {
         const callbacks = this._callbacks.get(event) ?? [];
         for (const cb of callbacks) {
@@ -461,24 +588,32 @@ export class Registry {
                     if (now - last < 300)
                         return;
                     this._debounceTimers?.set(fullPath, now);
+                    const handle = (p) => {
+                        p.catch((e) => {
+                            console.warn(`[apcore:registry] Watch handler failed for ${fullPath}:`, e);
+                        });
+                    };
                     if (eventType === "rename") {
                         // Could be create or delete
                         try {
                             fs.accessSync(fullPath);
-                            this._handleFileChange(fullPath);
+                            handle(this._handleFileChange(fullPath));
                         }
                         catch {
-                            this._handleFileDeletion(fullPath);
+                            handle(this._handleFileDeletion(fullPath));
                         }
                     }
                     else {
-                        this._handleFileChange(fullPath);
+                        handle(this._handleFileChange(fullPath));
                     }
                 });
                 this._watchers.push(watcher);
             }
-            catch {
-                // Skip directories that don't exist
+            catch (e) {
+                // Surface real failures (EMFILE, EACCES, Linux kernels < 4.7 without
+                // recursive support, etc.). A silently non-functional watch misleads
+                // users who expect hot-reload to be active.
+                console.warn(`[apcore:registry] fs.watch failed for '${rootPath}' — hot-reload disabled for this root:`, e);
             }
         }
     }
@@ -501,12 +636,17 @@ export class Registry {
                 try {
                     oldModule.onUnload();
                 }
-                catch { /* ignore */ }
+                catch (e) {
+                    console.warn(`[apcore:registry] onUnload failed for '${moduleId}':`, e);
+                }
             }
             this.unregister(moduleId);
         }
-        // Re-import is complex in ES modules - emit event for user to handle
-        this._triggerEvent("register", moduleId ?? basename(filePath, extname(filePath)), null);
+        // Re-import is complex in ES modules — tell consumers that a watched file
+        // changed so they can re-import and re-register. The earlier design
+        // emitted a 'register' event with a null module, which crashed any
+        // consumer that accessed fields on the module argument.
+        this._triggerEvent("file_changed", moduleId ?? basename(filePath, extname(filePath)), { filePath });
     }
     async _handleFileDeletion(path) {
         const moduleId = this._pathToModuleId(path);
@@ -516,7 +656,9 @@ export class Registry {
                 try {
                     module.onUnload();
                 }
-                catch { /* ignore */ }
+                catch (e) {
+                    console.warn(`[apcore:registry] onUnload failed for '${moduleId}':`, e);
+                }
             }
             this.unregister(moduleId);
         }
@@ -533,21 +675,18 @@ export class Registry {
         return null;
     }
     /**
-     * Register a module bypassing reserved-word checks.
-     * Used exclusively by the sys-modules subsystem for system.* IDs.
+     * Register a sys/internal module that bypasses **only** the reserved word
+     * check. All other PROTOCOL_SPEC §2.7 validations (empty, EBNF pattern,
+     * length, duplicate) still apply.
+     *
+     * Used exclusively by the sys-modules subsystem for `system.*` IDs.
+     * Aligned with apcore-python `Registry.register_internal` and apcore-rust
+     * `Registry::register_internal`.
      */
     registerInternal(moduleId, module) {
-        if (!moduleId || typeof moduleId !== "string") {
-            throw new InvalidInputError("Module ID must be a non-empty string");
-        }
-        if (!MODULE_ID_PATTERN.test(moduleId)) {
-            throw new InvalidInputError(`Invalid module ID: "${moduleId}". Must match pattern: ${MODULE_ID_PATTERN}`);
-        }
-        if (moduleId.length > MAX_MODULE_ID_LENGTH) {
-            throw new InvalidInputError(`Module ID exceeds maximum length of ${MAX_MODULE_ID_LENGTH}: ${moduleId.length}`);
-        }
+        validateModuleId(moduleId, true);
         if (this._modules.has(moduleId)) {
-            throw new InvalidInputError(`Module already exists: ${moduleId}`);
+            throw new InvalidInputError(`Module ID '${moduleId}' is already registered`);
         }
         this._modules.set(moduleId, module);
         const modObj = module;
@@ -564,6 +703,27 @@ export class Registry {
         }
         this._triggerEvent(REGISTRY_EVENTS.REGISTER, moduleId, module);
     }
+    /**
+     * Export the JSON Schema for a registered module.
+     *
+     * Returns the schema as a plain object (`Record<string, unknown> | null`),
+     * matching Python's `dict | None` and Rust's `Option<Value>` return types.
+     * Returns `null` if the module is not registered.
+     * Use the standalone `exportSchema` function from `schema-export.ts` for
+     * serialized (JSON/YAML) output.
+     */
+    exportSchema(moduleId, strict = false) {
+        const schema = getSchema(this, moduleId);
+        if (schema === null)
+            return null;
+        if (strict) {
+            const result = deepCopy(schema);
+            result['input_schema'] = toStrictSchema(result['input_schema']);
+            result['output_schema'] = toStrictSchema(result['output_schema']);
+            return result;
+        }
+        return schema;
+    }
     clearCache() {
         this._schemaCache.clear();
     }
@@ -629,9 +789,18 @@ export class Registry {
     }
     /**
      * Remove the draining mark and clean up drain state.
+     *
+     * If any waitDrained waiters are still pending (e.g., refCount briefly
+     * hit zero and then a new acquire bumped it back up), resolve them first
+     * so they do not wait for their individual timeouts before returning.
      */
     endDrain(moduleId) {
         this._draining.delete(moduleId);
+        const resolvers = this._drainResolvers.get(moduleId);
+        if (resolvers) {
+            for (const resolve of resolvers)
+                resolve();
+        }
         this._drainResolvers.delete(moduleId);
         this._refCounts.delete(moduleId);
     }