apcore-js 0.19.0 → 0.20.0

package/dist/registry/multi-class.js

@@ -0,0 +1,120 @@
+/**
+ * Multi-class module discovery: opt-in scanner, snake_case ID derivation, conflict detection.
+ *
+ * Implements PROTOCOL_SPEC §2.1.1 (Multi-Module Discovery).
+ */
+import { IdTooLongError, InvalidSegmentError, ModuleIdConflictError } from '../errors.js';
+const SEGMENT_RE = /^[a-z][a-z0-9_]*$/;
+const CANONICAL_ID_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+const MAX_MODULE_ID_LEN = 192;
+/**
+ * Convert a class name to a snake_case segment per PROTOCOL_SPEC §2.1.1.
+ *
+ * Algorithm:
+ * 1. Insert boundary at ALLCAPS→CamelCase transitions (HTTPSender → HTTP_Sender).
+ * 2. Insert boundary at lowercase/digit→uppercase transitions (MathOps → Math_Ops).
+ * 3. Replace every non-alphanumeric character with `_`.
+ * 4. Lowercase.
+ * 5. Collapse consecutive `_` to a single `_`.
+ * 6. Strip leading and trailing `_`.
+ */
+export function classNameToSegment(className) {
+    let s = className.replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2');
+    s = s.replace(/([a-z\d])([A-Z])/g, '$1_$2');
+    s = s.replace(/[^a-zA-Z0-9]/g, '_');
+    s = s.toLowerCase();
+    s = s.replace(/_+/g, '_');
+    return s.replace(/^_+|_+$/g, '');
+}
+function computeBaseId(filePath, extensionsRoot) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    const rootIdx = parts.findIndex(p => p === extensionsRoot);
+    const relParts = rootIdx === -1 ? [parts[parts.length - 1]] : parts.slice(rootIdx + 1);
+    // Strip file extension from the last segment
+    relParts[relParts.length - 1] = relParts[relParts.length - 1].replace(/\.[^.]+$/, '');
+    return relParts.join('.');
+}
+/**
+ * Discover module IDs for classes in a single file under multi-class mode.
+ *
+ * Implements the Registry.discover_multi_class contract from PROTOCOL_SPEC §2.1.1.
+ *
+ * When multiClassEnabled is false (the default — multi-class mode is opt-in),
+ * only the first qualifying class is used and the bare base_id is returned.
+ *
+ * When multiClassEnabled is true and exactly one class qualifies:
+ * - If the class segment matches the file's last path segment (class named after
+ *   the file), the bare base_id is returned to preserve existing module IDs.
+ * - Otherwise the class segment is appended: base_id.class_segment.
+ *
+ * @internal Prefer `Registry.discoverMultiClass` (D-15) for the canonical
+ * cross-language API surface; this free function is retained for backwards
+ * compatibility and direct use by the scanner.
+ *
+ * @throws ModuleIdConflictError — two classes produce the same class_segment
+ * @throws InvalidSegmentError   — a segment does not match ^[a-z][a-z0-9_]*$
+ * @throws IdTooLongError        — a derived module_id exceeds 192 characters
+ */
+export function discoverMultiClass(filePath, classes, extensionsRoot = 'extensions', multiClassEnabled = false) {
+    const qualifying = classes.filter(c => c.implementsModule);
+    if (qualifying.length === 0)
+        return [];
+    const baseId = computeBaseId(filePath, extensionsRoot);
+    if (!multiClassEnabled) {
+        return [{ moduleId: baseId, className: qualifying[0].name }];
+    }
+    if (qualifying.length === 1) {
+        const segment = classNameToSegment(qualifying[0].name);
+        const lastBaseSegment = baseId.split('.').pop();
+        // Identity guarantee: when the class segment matches the file's last segment
+        // (class named after the file), preserve the bare base_id so existing IDs
+        // are not broken when multi-class mode is enabled.
+        if (segment === lastBaseSegment) {
+            return [{ moduleId: baseId, className: qualifying[0].name }];
+        }
+        // Class has a distinct name from the file — append the class segment.
+        if (!SEGMENT_RE.test(segment))
+            throw new InvalidSegmentError(filePath, qualifying[0].name, segment);
+        const moduleId = `${baseId}.${segment}`;
+        if (!CANONICAL_ID_RE.test(moduleId))
+            throw new InvalidSegmentError(filePath, qualifying[0].name, segment);
+        if (moduleId.length > MAX_MODULE_ID_LEN)
+            throw new IdTooLongError(filePath, moduleId);
+        return [{ moduleId, className: qualifying[0].name }];
+    }
+    // Multi-class path: derive IDs, detect conflicts, validate
+    const seenSegments = new Map(); // segment → className
+    const results = [];
+    for (const cls of qualifying) {
+        const segment = classNameToSegment(cls.name);
+        if (!SEGMENT_RE.test(segment)) {
+            throw new InvalidSegmentError(filePath, cls.name, segment);
+        }
+        if (seenSegments.has(segment)) {
+            console.warn(`[apcore:multi-class] MODULE_ID_CONFLICT in '${filePath}': ` +
+                `classes '${seenSegments.get(segment)}' and '${cls.name}' both produce segment '${segment}'`);
+            throw new ModuleIdConflictError(filePath, [seenSegments.get(segment), cls.name], segment);
+        }
+        seenSegments.set(segment, cls.name);
+        const moduleId = `${baseId}.${segment}`;
+        if (!CANONICAL_ID_RE.test(moduleId)) {
+            throw new InvalidSegmentError(filePath, cls.name, segment);
+        }
+        if (moduleId.length > MAX_MODULE_ID_LEN) {
+            throw new IdTooLongError(filePath, moduleId);
+        }
+        results.push({ moduleId, className: cls.name });
+    }
+    return results;
+}
+/**
+ * Internal alias of {@link discoverMultiClass}. Use {@link Registry.discoverMultiClass}
+ * instead — this name is preserved so the scanner and other internal callers
+ * have a stable reference that signals the surface is not part of the public
+ * API.
+ *
+ * @internal
+ */
+export const _discoverMultiClass = discoverMultiClass;
+//# sourceMappingURL=multi-class.js.map

package/dist/registry/multi-class.js.map

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

package/dist/registry/registry.d.ts

@@ -77,12 +77,48 @@ export declare class Registry {
     setValidator(validator: ModuleValidator): void;
     discover(): Promise<number>;
     private _discoverCustom;
+    /**
+     * 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.
+     */
     private _discoverDefault;
     private _scanRoots;
     private _applyIdMapOverrides;
     private _loadAllMetadata;
     private _resolveAllEntryPoints;
     private _validateAll;
+    /**
+     * 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.
+     */
+    private _filterIdConflicts;
     private _resolveLoadOrder;
     private _registerInOrder;
     /**
@@ -91,12 +127,31 @@ export declare 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: string, module: unknown): void;
+    register(moduleId: string, module: unknown, version?: string | null, metadata?: Record<string, unknown> | null): 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;
+    /**
+     * 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: string, _versionHint?: string | null): unknown | null;
     has(moduleId: string): boolean;
     list(options?: {
         tags?: string[];
@@ -105,12 +160,35 @@ export declare class Registry {
     iter(): IterableIterator<[string, unknown]>;
     get count(): number;
     get moduleIds(): string[];
-    getDefinition(moduleId: string): ModuleDescriptor | null;
+    getDefinition(moduleId: string, _versionHint?: string | null): ModuleDescriptor | null;
     describe(moduleId: string): string;
     on(event: string, callback: EventCallback): void;
     off(event: string, callback: EventCallback): boolean;
     reload(): Promise<number>;
     private _triggerEvent;
+    /**
+     * 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.
+     */
     watch(): Promise<void>;
     unwatch(): void;
     private _handleFileChange;
@@ -137,6 +215,16 @@ export declare class Registry {
      */
     exportSchema(moduleId: string, strict?: boolean): Record<string, unknown> | null;
     clearCache(): void;
+    /**
+     * 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: string, classes: readonly import('./multi-class.js').ClassDescriptor[], extensionsRoot?: string, multiClassEnabled?: boolean): import('./multi-class.js').MultiClassEntry[];
     /**
      * Number of in-flight executions per module.
      */

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

@@ -7,6 +7,7 @@ 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';
@@ -197,6 +198,17 @@ 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 {
+                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++;
@@ -207,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();
@@ -214,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;
@@ -295,6 +322,56 @@ 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 = [];
         const moduleVersions = new Map();
@@ -326,9 +403,13 @@ export class Registry {
         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);
@@ -357,8 +438,15 @@ 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._customValidator !== null) {
             const result = this._customValidator.validate(module);
@@ -369,10 +457,14 @@ export class Registry {
                 throw new InvalidInputError(`Custom validator rejected module '${moduleId}': ${result.join('; ')}`);
             }
         }
-        this._registerImpl(moduleId, module);
+        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) {
+    _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) {
@@ -385,9 +477,10 @@ export class Registry {
         }
         this._modules.set(moduleId, module);
         this._lowercaseMap.set(moduleId.toLowerCase(), moduleId);
-        // Populate metadata from the module object
+        // 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 {
@@ -423,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('');
         }
@@ -465,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;
@@ -564,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
@@ -685,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']();
@@ -698,6 +855,7 @@ export class Registry {
             catch (e) {
                 this._modules.delete(moduleId);
                 this._moduleMeta.delete(moduleId);
+                this._lowercaseMap.delete(moduleId.toLowerCase());
                 throw e;
             }
         }
@@ -728,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.
      */