apcore-js 0.18.0 → 0.20.0

package/dist/registry/registry.js

@@ -3,9 +3,11 @@
  */
 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 { _discoverMultiClass } from './multi-class.js';
 import { getSchema } from './schema-export.js';
 import { toStrictSchema } from '../schema/strict.js';
 import { deepCopy } from '../utils/index.js';
@@ -64,17 +66,17 @@ export const MODULE_ID_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
  */
 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 (per-segment).
+ * Order: empty → pattern → length → reserved (first-segment).
  * Duplicate detection is the caller's responsibility (it requires registry
  * state).
  *
- * When `allowReserved` is true the per-segment reserved word check is
+ * 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.
@@ -98,12 +100,11 @@ function validateModuleId(moduleId, allowReserved) {
     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 per-segment check (skipped for registerInternal)
+    // 4. reserved word first-segment check (skipped for registerInternal)
     if (!allowReserved) {
-        for (const segment of moduleId.split('.')) {
-            if (RESERVED_WORDS.has(segment)) {
-                throw new InvalidInputError(`Module ID contains reserved word: '${segment}'`);
-            }
+        const firstSegment = moduleId.split('.')[0];
+        if (RESERVED_WORDS.has(firstSegment)) {
+            throw new InvalidInputError(`Module ID contains reserved word: '${firstSegment}'`);
         }
     }
 }
@@ -116,6 +117,7 @@ export class Registry {
         [REGISTRY_EVENTS.UNREGISTER, []],
     ]);
     _idMap = {};
+    _lowercaseMap = new Map();
     _schemaCache = new Map();
     _config;
     _watchers;
@@ -173,9 +175,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);
@@ -184,8 +198,19 @@ export class Registry {
                     continue;
                 }
             }
+            // PROTOCOL_SPEC §2.7 ID validation — sync finding A-D-102.
+            // Mirrors apcore-python `Registry._discover_custom` which calls
+            // `_validate_module_id` before registration. Invalid IDs are skipped
+            // with a warning rather than aborting the whole discover run.
             try {
-                this.register(moduleId, mod);
+                validateModuleId(moduleId, false);
+            }
+            catch (e) {
+                console.warn(`[apcore:registry] Skipping custom-discovered module with invalid ID '${moduleId}': ${e.message}`);
+                continue;
+            }
+            try {
+                this._registerImpl(moduleId, mod);
                 count++;
             }
             catch (e) {
@@ -194,6 +219,20 @@ export class Registry {
         }
         return count;
     }
+    /**
+     * Default discovery pipeline (D-32 — 8 canonical stages, mirroring
+     * apcore-rust `default_discoverer.rs`):
+     *
+     *   1. _ensureIdMap            — lazy-load the optional id_map.json
+     *   2. _scanRoots              — walk extension roots
+     *   3. _applyIdMapOverrides    — rewrite canonical IDs from the map
+     *   4. _loadAllMetadata        — load each module's `module.yaml`
+     *   5. _resolveAllEntryPoints  — import the JS/TS entry point
+     *   6. _validateAll            — run module/custom validators
+     *   7. _filterIdConflicts      — batch-drop conflicting / invalid IDs
+     *   8. _resolveLoadOrder + _registerInOrder
+     *                              — topological sort then register.
+     */
     async _discoverDefault() {
         await this._ensureIdMap();
         const discovered = await this._scanRoots();
@@ -201,8 +240,9 @@ export class Registry {
         const rawMetadata = await this._loadAllMetadata(discovered);
         const resolvedModules = await this._resolveAllEntryPoints(discovered, rawMetadata);
         const validModules = await this._validateAll(resolvedModules);
-        const loadOrder = this._resolveLoadOrder(validModules, rawMetadata);
-        return this._registerInOrder(loadOrder, validModules, rawMetadata);
+        const filteredModules = this._filterIdConflicts(validModules, rawMetadata);
+        const loadOrder = this._resolveLoadOrder(filteredModules, rawMetadata);
+        return this._registerInOrder(loadOrder, filteredModules, rawMetadata);
     }
     async _scanRoots() {
         let maxDepth = 8;
@@ -229,7 +269,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;
                     }
                 }
@@ -276,24 +322,99 @@ export class Registry {
         }
         return validModules;
     }
+    /**
+     * Stage 7 (D-32) — batch-drop modules with invalid or conflicting IDs.
+     *
+     * Mirrors apcore-python `_filter_id_conflicts` and apcore-rust
+     * `default_discoverer::filter_id_conflicts`. Two failure modes drop a
+     * module here (warn + skip) rather than aborting the whole batch:
+     *   - PROTOCOL_SPEC §2.7 ID validation (empty / pattern / length /
+     *     reserved-word first segment), and
+     *   - Algorithm A03 conflict detection (duplicate against an existing
+     *     registration, lowercase collision, reserved-word collision).
+     *
+     * Soft-severity conflicts (e.g. case-insensitive match against an
+     * already-registered ID at `warn` level) are NOT dropped here — the
+     * warning is logged and the module flows through to registration so
+     * existing behaviour is preserved. Only `error`-severity conflicts and
+     * invalid IDs are filtered out.
+     *
+     * `rawMetadata` is accepted for cross-language signature parity with
+     * the Rust/Python helpers (which may inspect metadata for additional
+     * checks); the TS implementation reads only the module ID.
+     */
+    _filterIdConflicts(validModules, _rawMetadata) {
+        const filtered = new Map();
+        // Track within-batch IDs (case-insensitive) so two newly-discovered
+        // modules whose IDs collide on lowercase don't both slip through.
+        const batchLowercase = new Map(this._lowercaseMap);
+        const batchIds = new Set(this._modules.keys());
+        for (const [modId, mod] of validModules.entries()) {
+            try {
+                validateModuleId(modId, false);
+            }
+            catch (e) {
+                console.warn(`[apcore:registry] Skipping discovered module with invalid ID '${modId}': ${e.message}`);
+                continue;
+            }
+            const conflict = detectIdConflicts(modId, batchIds, RESERVED_WORDS, batchLowercase);
+            if (conflict !== null) {
+                if (conflict.severity === 'error') {
+                    console.warn(`[apcore:registry] Skipping discovered module '${modId}' due to ID conflict: ${conflict.message}`);
+                    continue;
+                }
+                // Soft severity — log but keep the module.
+                console.warn(`[apcore:registry] ID conflict: ${conflict.message}`);
+            }
+            filtered.set(modId, mod);
+            batchIds.add(modId);
+            batchLowercase.set(modId.toLowerCase(), modId);
+        }
+        return filtered;
+    }
     _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) {
+        // Stage 8 (D-32). Conflict detection / ID validation already happened in
+        // `_filterIdConflicts` (stage 7), so this loop is purely a register pass.
         let count = 0;
         for (const modId of loadOrder) {
             const mod = validModules.get(modId);
+            if (mod === undefined)
+                continue;
             const modObj = mod;
             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']();
@@ -302,6 +423,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;
                 }
             }
@@ -316,16 +438,49 @@ export class Registry {
      * Validation order (PROTOCOL_SPEC §2.7, aligned with apcore-python and
      * apcore-rust): empty → pattern → length → reserved (per-segment) →
      * duplicate.
+     *
+     * The optional `version` and `metadata` parameters mirror apcore-python's
+     * `Registry.register(module_id, module, version=None, metadata=None)` for
+     * cross-language signature parity (sync finding A-001). Multi-version
+     * coexistence is not yet implemented in this SDK — when supplied, both
+     * fields are merged into the module's metadata so callers can read them
+     * back via `getDefinition()` and `list({tags})`. See PROTOCOL_SPEC §5.4.
      */
-    register(moduleId, module) {
+    register(moduleId, module, version, metadata) {
         validateModuleId(moduleId, false);
-        if (this._modules.has(moduleId)) {
-            throw new InvalidInputError(`Module ID '${moduleId}' is already registered`);
+        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('; ')}`);
+            }
+        }
+        const overrides = { ...(metadata ?? {}) };
+        if (version !== undefined && version !== null) {
+            overrides['version'] = version;
+        }
+        this._registerImpl(moduleId, module, overrides);
+    }
+    /** Inner registration — no validator, no ID validation. Used by discover() paths that run their own checks. */
+    _registerImpl(moduleId, module, metadataOverrides = {}) {
+        // 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);
-        // Populate metadata from the module object
+        this._lowercaseMap.set(moduleId.toLowerCase(), moduleId);
+        // Populate metadata from the module object, layering any explicit overrides
+        // (e.g. the `version` / `metadata` args passed to `register()`) on top.
         const modObj = module;
-        this._moduleMeta.set(moduleId, mergeModuleMetadata(modObj, {}));
+        this._moduleMeta.set(moduleId, mergeModuleMetadata(modObj, metadataOverrides));
         // Call onLoad if available
         if (typeof modObj['onLoad'] === 'function') {
             try {
@@ -334,6 +489,7 @@ export class Registry {
             catch (e) {
                 this._modules.delete(moduleId);
                 this._moduleMeta.delete(moduleId);
+                this._lowercaseMap.delete(moduleId.toLowerCase());
                 throw e;
             }
         }
@@ -346,6 +502,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') {
@@ -359,7 +516,19 @@ export class Registry {
         this._triggerEvent(REGISTRY_EVENTS.UNREGISTER, moduleId, module);
         return true;
     }
-    get(moduleId) {
+    /**
+     * Look up a registered module by ID.
+     *
+     * @param moduleId - Module identifier (must be non-empty).
+     * @param _versionHint - Optional semver range for multi-version coexistence
+     *   (PROTOCOL_SPEC §5.4). This SDK currently exposes a single-version
+     *   registry, so the hint is accepted for cross-language API parity with
+     *   apcore-python (sync finding A-002) but does NOT participate in
+     *   resolution: the latest registered module for `moduleId` is returned
+     *   regardless of the hint. When multi-version registration lands, this
+     *   parameter will gate semver-range matching.
+     */
+    get(moduleId, _versionHint) {
         if (moduleId === '') {
             throw new ModuleNotFoundError('');
         }
@@ -401,7 +570,18 @@ export class Registry {
     get moduleIds() {
         return [...this._modules.keys()].sort();
     }
-    getDefinition(moduleId) {
+    getDefinition(moduleId, _versionHint) {
+        // `_versionHint` accepted for cross-language API parity with apcore-python
+        // (sync finding A-002 / §5.4). Ignored under the single-version registry;
+        // see `get()` for the rationale.
+        //
+        // D10-011: spec registry-system.md:382 says any error that `get(module_id)`
+        // raises is propagated. The empty-string guard mirrors `get()` (line 669)
+        // so callers using getDefinition see the same ModuleNotFoundError as
+        // get(), matching apcore-python where getDefinition routes through get().
+        if (moduleId === '') {
+            throw new ModuleNotFoundError('');
+        }
         const module = this._modules.get(moduleId);
         if (module == null)
             return null;
@@ -500,6 +680,29 @@ export class Registry {
             }
         }
     }
+    /**
+     * Watch the configured extension roots for filesystem changes and
+     * unregister any module whose source file is modified or deleted.
+     *
+     * **Cross-language divergence (sync finding A-D-104):** unlike apcore-python
+     * (which re-imports the file via `importlib.reload`) and apcore-rust (which
+     * triggers full rediscovery), the TypeScript SDK is **event-only**. On a
+     * file change the registry:
+     *   1. unregisters the previously-loaded module (calling its `onUnload`),
+     *   2. emits a `'file_changed'` event with `{ filePath }` payload.
+     *
+     * Consumers are expected to subscribe and re-register the module
+     * themselves (e.g. by calling `registry.discover()` or registering a fresh
+     * import). ES module specifiers are immutable in Node — there is no
+     * portable "reload from disk" primitive — so a transparent dynamic
+     * `import()` would silently return the cached old module on every
+     * invocation. A workaround using a cache-busting query (`?v=Date.now()`)
+     * leaks the old module each reload and breaks browser bundlers, so it is
+     * intentionally **not** offered here.
+     *
+     * If your application needs Python-style hot-reload semantics, listen for
+     * `'file_changed'` and re-discover or re-import explicitly.
+     */
     async watch() {
         if (this._watchers && this._watchers.length > 0) {
             return; // Already watching
@@ -524,24 +727,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);
             }
         }
     }
@@ -564,12 +775,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);
@@ -579,7 +795,9 @@ export class Registry {
                 try {
                     module.onUnload();
                 }
-                catch { /* ignore */ }
+                catch (e) {
+                    console.warn(`[apcore:registry] onUnload failed for '${moduleId}':`, e);
+                }
             }
             this.unregister(moduleId);
         }
@@ -606,12 +824,30 @@ export class Registry {
      */
     registerInternal(moduleId, module) {
         validateModuleId(moduleId, true);
-        if (this._modules.has(moduleId)) {
-            throw new InvalidInputError(`Module ID '${moduleId}' is already registered`);
+        // D11-007: route duplicate detection through detectIdConflicts (with an
+        // empty reserved-words set so the bypass for system.* prefixes is
+        // preserved). This restores the case-collision branch present in
+        // apcore-python (registry.py:1674) and apcore-rust (registry.rs:727).
+        // The lowercase-only EBNF in validateModuleId makes case collisions
+        // unreachable today, but the contract surface stays aligned across SDKs.
+        const conflict = detectIdConflicts(moduleId, new Set(this._modules.keys()), new Set(), 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);
         const modObj = module;
         this._moduleMeta.set(moduleId, mergeModuleMetadata(modObj, {}));
+        // Mirror apcore-python register_internal and apcore-rust register_core:
+        // every registration site (including sys/internal) populates the lowercase
+        // index. The lowercase-only EBNF pattern enforced by validateModuleId makes
+        // case collisions unreachable today, but keeping _lowercaseMap consistent
+        // with _modules preserves the invariant for downstream conflict detection.
+        this._lowercaseMap.set(moduleId.toLowerCase(), moduleId);
         if (typeof modObj['onLoad'] === 'function') {
             try {
                 modObj['onLoad']();
@@ -619,6 +855,7 @@ export class Registry {
             catch (e) {
                 this._modules.delete(moduleId);
                 this._moduleMeta.delete(moduleId);
+                this._lowercaseMap.delete(moduleId.toLowerCase());
                 throw e;
             }
         }
@@ -649,6 +886,18 @@ export class Registry {
         this._schemaCache.clear();
     }
     // ── Safe Hot-Reload (F09 / Algorithm A21) ───────────────────────
+    /**
+     * Discover module IDs for the classes in a single file under multi-class
+     * mode (PROTOCOL_SPEC §2.1.1).
+     *
+     * D-15: cross-language alignment with Python `Registry.discover_multi_class`
+     * and the Rust trait method. Internally delegates to the free function
+     * {@link discoverMultiClass} (re-exported as `_discoverMultiClass` for
+     * scanner internals), so behaviour is identical.
+     */
+    discoverMultiClass(filePath, classes, extensionsRoot = 'extensions', multiClassEnabled = false) {
+        return _discoverMultiClass(filePath, classes, extensionsRoot, multiClassEnabled);
+    }
     /**
      * Number of in-flight executions per module.
      */
@@ -710,9 +959,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);
     }