apcore-js 0.19.0 → 0.21.0

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';
@@ -43,6 +44,35 @@ async function lazyScanMultiRoot(roots, maxDepth, followSymlinks) {
     const { scanMultiRoot } = await import('./scanner.js');
     return scanMultiRoot(roots, maxDepth, followSymlinks);
 }
+/**
+ * One-shot deprecation flag for the legacy 4-arg
+ * `Registry.discoverMultiClass(filePath, classes, extensionsRoot, multiClassEnabled)`
+ * call shape. Cleared per process so the warning fires at most once even
+ * across many invocations from the same caller. See apcore decision-log
+ * D-06 (apcore commit 973410b).
+ *
+ * @internal exported for tests so they can reset between cases.
+ */
+let _multiClassEnabledDeprecationWarned = false;
+/**
+ * Reset the one-shot deprecation flag for the legacy 4-arg
+ * `Registry.discoverMultiClass` overload. Test-only — production callers
+ * never need this.
+ *
+ * @internal
+ */
+export function _resetMultiClassEnabledDeprecationWarned() {
+    _multiClassEnabledDeprecationWarned = false;
+}
+function warnMultiClassEnabledDeprecated() {
+    if (_multiClassEnabledDeprecationWarned)
+        return;
+    _multiClassEnabledDeprecationWarned = true;
+    console.warn('[apcore:registry] DEPRECATION: the `multiClassEnabled` argument to ' +
+        '`Registry.discoverMultiClass()` is deprecated and ignored under apcore ' +
+        'decision-log D-06. Mark each `ClassDescriptor` with `multiClass: true` ' +
+        'instead. The 4-arg overload will be removed in v0.22.0.');
+}
 /**
  * Standard registry event names.
  */
@@ -68,6 +98,25 @@ export const MAX_MODULE_ID_LENGTH = 192;
  * 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']);
+/**
+ * Namespace prefix reserved for programmatically-registered modules
+ * synthesized at runtime (PROTOCOL_SPEC §2.5; RFC
+ * `apcore/docs/spec/rfc-ephemeral-modules.md`). IDs in this namespace MUST
+ * be registered through {@link Registry.register} only — the filesystem
+ * discoverer rejects matching IDs because the namespace has no
+ * directory-rooted source of truth, and {@link Registry.registerInternal}
+ * rejects them too so the audit-trail provenance distinction between
+ * framework-emitted (`system.*`) and caller-emitted (`ephemeral.*`)
+ * modules stays clean.
+ *
+ * The trailing dot is required so module IDs whose first segment merely
+ * *starts with* `ephemeral` (e.g. `ephemerals`) are not falsely classified.
+ */
+export const EPHEMERAL_NAMESPACE_PREFIX = 'ephemeral.';
+/** Return true when `moduleId` belongs to the reserved `ephemeral.*` namespace. */
+export function isEphemeralModuleId(moduleId) {
+    return moduleId === 'ephemeral' || moduleId.startsWith(EPHEMERAL_NAMESPACE_PREFIX);
+}
 /**
  * Validate a module ID against PROTOCOL_SPEC §2.7 in canonical order.
  *
@@ -129,6 +178,16 @@ export class Registry {
     _refCounts = new Map();
     _draining = new Set();
     _drainResolvers = new Map();
+    /**
+     * Optional EventEmitter for the ephemeral.* registry-side audit emits
+     * (RFC `apcore/docs/spec/rfc-ephemeral-modules.md` "Audit-event single-emit
+     * rule"). Set via {@link setEventEmitter}; when null, ephemeral audit
+     * events are warn-logged so they never silently disappear.
+     *
+     * Mirrors apcore-python `Registry._event_emitter` /
+     * `Registry.set_event_emitter`.
+     */
+    _eventEmitter = null;
     constructor(options) {
         const config = options?.config ?? null;
         const extensionsDir = options?.extensionsDir ?? null;
@@ -197,6 +256,27 @@ 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;
+            }
+            // RFC `apcore/docs/spec/rfc-ephemeral-modules.md`: filesystem /
+            // discoverer paths MUST reject `ephemeral.*` IDs. The custom
+            // discoverer is functionally a discovery path too, so the same
+            // contract applies — ephemeral.* must land via Registry.register().
+            if (isEphemeralModuleId(moduleId)) {
+                console.warn(`[apcore:registry] Skipping custom-discovered module '${moduleId}': ` +
+                    `'ephemeral.*' is reserved for programmatic registration via ` +
+                    `Registry.register(); see docs/spec/rfc-ephemeral-modules.md.`);
+                continue;
+            }
             try {
                 this._registerImpl(moduleId, mod);
                 count++;
@@ -207,15 +287,31 @@ 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();
         await this._applyIdMapOverrides(discovered);
+        this._rejectEphemeralDiscoveries(discovered);
         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;
@@ -230,6 +326,31 @@ export class Registry {
         }
         return lazyScanExtensions(this._extensionRoots[0]['root'], maxDepth, followSymlinks);
     }
+    /**
+     * Reject filesystem-derived IDs that fall in the reserved `ephemeral.*`
+     * namespace.
+     *
+     * Per the apcore ephemeral-modules RFC pilot (`apcore/docs/spec/
+     * rfc-ephemeral-modules.md`), `ephemeral.*` is reserved for
+     * programmatically-registered modules synthesized at runtime. Any
+     * filesystem layout that produces such an ID is a configuration error —
+     * either the directory is misnamed or the namespace prefix is being
+     * misused. We surface this as an `InvalidInputError` so callers cannot
+     * accidentally pollute the registry with filesystem-rooted ephemerals.
+     *
+     * Mirrors apcore-python `Registry._reject_ephemeral_discoveries`.
+     */
+    _rejectEphemeralDiscoveries(discovered) {
+        const offenders = discovered.filter((dm) => isEphemeralModuleId(dm.canonicalId));
+        if (offenders.length === 0)
+            return;
+        const ids = [...new Set(offenders.map((dm) => dm.canonicalId))].sort();
+        throw new InvalidInputError(`Filesystem discovery produced module ID(s) in the reserved ` +
+            `'ephemeral.*' namespace: ${JSON.stringify(ids)}. The ephemeral.* ` +
+            `namespace is reserved for programmatically-registered modules and ` +
+            `may only be used via Registry.register(). Rename the offending ` +
+            `directory or extension namespace.`);
+    }
     async _applyIdMapOverrides(discovered) {
         if (Object.keys(this._idMap).length === 0)
             return;
@@ -295,6 +416,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 +497,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,9 +532,25 @@ 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, options) {
         validateModuleId(moduleId, false);
+        // ephemeral.* registrations only land via this programmatic path —
+        // the filesystem discoverer rejects matching IDs upstream (see
+        // `_rejectEphemeralDiscoveries`). When invoked here the RFC pilot
+        // recommends `requires_approval=true` so a human gates execution of
+        // agent-synthesized code; we soft-warn but never refuse.
+        const ephemeral = isEphemeralModuleId(moduleId);
+        if (ephemeral) {
+            this._warnIfMissingApproval(moduleId, module);
+        }
         if (this._customValidator !== null) {
             const result = this._customValidator.validate(module);
             if (result instanceof Promise) {
@@ -369,10 +560,17 @@ 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);
+        if (ephemeral) {
+            this._emitEphemeralAudit('apcore.registry.module_registered', moduleId, options?.context ?? null);
+        }
     }
     /** 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 +583,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 {
@@ -402,7 +601,7 @@ export class Registry {
         }
         this._triggerEvent(REGISTRY_EVENTS.REGISTER, moduleId, module);
     }
-    unregister(moduleId) {
+    unregister(moduleId, options) {
         if (!this._modules.has(moduleId))
             return false;
         const module = this._modules.get(moduleId);
@@ -421,9 +620,24 @@ export class Registry {
             }
         }
         this._triggerEvent(REGISTRY_EVENTS.UNREGISTER, moduleId, module);
+        if (isEphemeralModuleId(moduleId)) {
+            this._emitEphemeralAudit('apcore.registry.module_unregistered', moduleId, options?.context ?? null);
+        }
         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('');
         }
@@ -432,8 +646,21 @@ export class Registry {
     has(moduleId) {
         return this._modules.has(moduleId);
     }
+    /**
+     * Return sorted list of registered module IDs, optionally filtered by
+     * `prefix` / `tags`.
+     *
+     * Modules whose `ModuleAnnotations.discoverable === false` are excluded
+     * by default per PROTOCOL_SPEC §4.4 (RFC
+     * `apcore/docs/spec/rfc-ephemeral-modules.md`). Pass
+     * `includeHidden: true` to enumerate every registered module — useful
+     * for introspection tools, debug consoles, and tests.
+     */
     list(options) {
         let ids = [...this._modules.keys()];
+        if (options?.includeHidden !== true) {
+            ids = ids.filter((id) => this._isDiscoverable(id));
+        }
         if (options?.prefix != null) {
             ids = ids.filter((id) => id.startsWith(options.prefix));
         }
@@ -456,16 +683,92 @@ export class Registry {
         }
         return ids.sort();
     }
-    iter() {
-        return this._modules.entries();
+    /**
+     * Iterate `[moduleId, module]` pairs. Hides modules annotated
+     * `discoverable: false` by default; pass `includeHidden: true` to walk
+     * every registered module.
+     */
+    iter(options) {
+        if (options?.includeHidden === true) {
+            return this._modules.entries();
+        }
+        const visible = [];
+        for (const [id, mod] of this._modules.entries()) {
+            if (this._isDiscoverable(id))
+                visible.push([id, mod]);
+        }
+        return visible[Symbol.iterator]();
     }
+    /** Total number of registered modules (includes `discoverable: false`). */
     get count() {
         return this._modules.size;
     }
+    /**
+     * Sorted list of registered module IDs (excludes
+     * `ModuleAnnotations.discoverable === false` modules). Use
+     * {@link list} with `includeHidden: true` when the full set is required.
+     */
     get moduleIds() {
-        return [...this._modules.keys()].sort();
+        return [...this._modules.keys()]
+            .filter((id) => this._isDiscoverable(id))
+            .sort();
+    }
+    /**
+     * Return false when the module's annotations declare
+     * `discoverable: false`. Anything else (including missing annotations)
+     * keeps the module visible — the default `true` preserves backward
+     * compatibility.
+     *
+     * Resolution order matches `mergeModuleMetadata`:
+     * 1. The merged `annotations` slot in `_moduleMeta` (which already
+     *    accounts for YAML > code precedence).
+     * 2. The module instance's `annotations` attribute (covers paths that
+     *    bypassed the merge, e.g. `registerInternal`).
+     */
+    _isDiscoverable(moduleId) {
+        const meta = this._moduleMeta.get(moduleId);
+        if (meta != null) {
+            const ann = meta['annotations'];
+            if (ann != null) {
+                const dv = this._readDiscoverable(ann);
+                if (dv === false)
+                    return false;
+                if (dv === true)
+                    return true;
+            }
+        }
+        const mod = this._modules.get(moduleId);
+        if (mod == null)
+            return true;
+        const ann = mod['annotations'];
+        if (ann == null)
+            return true;
+        return this._readDiscoverable(ann) !== false;
+    }
+    _readDiscoverable(ann) {
+        if (ann == null)
+            return undefined;
+        if (typeof ann === 'object') {
+            // Accept both ModuleAnnotations instances and YAML-style dicts.
+            const rec = ann;
+            const v = rec['discoverable'];
+            if (v === true || v === false)
+                return v;
+        }
+        return undefined;
     }
-    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 +867,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
@@ -684,13 +1010,42 @@ export class Registry {
      * `Registry::register_internal`.
      */
     registerInternal(moduleId, module) {
+        // RFC `apcore/docs/spec/rfc-ephemeral-modules.md` "register_internal()
+        // interaction": ephemeral.* IDs MUST be rejected here. Namespace →
+        // registration-mechanism is a 1:1 mapping; mixing blurs the audit-trail
+        // distinction between framework-emitted (`system.*`) and caller-emitted
+        // (`ephemeral.*`) modules.
+        if (isEphemeralModuleId(moduleId)) {
+            throw new InvalidInputError(`ephemeral.* module IDs must be registered via Registry.register(), ` +
+                `not registerInternal() (got: '${moduleId}'). See apcore ` +
+                `docs/spec/rfc-ephemeral-modules.md "register_internal() ` +
+                `interaction" for rationale.`);
+        }
         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 +1053,7 @@ export class Registry {
             catch (e) {
                 this._modules.delete(moduleId);
                 this._moduleMeta.delete(moduleId);
+                this._lowercaseMap.delete(moduleId.toLowerCase());
                 throw e;
             }
         }
@@ -727,7 +1083,16 @@ export class Registry {
     clearCache() {
         this._schemaCache.clear();
     }
-    // ── Safe Hot-Reload (F09 / Algorithm A21) ───────────────────────
+    discoverMultiClass(filePath, classes, extensionsRoot = 'extensions', multiClassEnabled) {
+        if (multiClassEnabled !== undefined) {
+            warnMultiClassEnabledDeprecated();
+            // The argument is functionally inert under D-06: the per-class
+            // `multiClass` field is the source of truth. We intentionally ignore
+            // `multiClassEnabled` and recompute from the descriptors below.
+        }
+        const enabled = classes.some((c) => c.implementsModule && c.multiClass === true);
+        return _discoverMultiClass(filePath, classes, extensionsRoot, enabled);
+    }
     /**
      * Number of in-flight executions per module.
      */
@@ -841,6 +1206,110 @@ export class Registry {
      *
      * Returns true if drained cleanly, false if force-unloaded after timeout.
      */
+    // ── Ephemeral namespace pilot (RFC: rfc-ephemeral-modules) ──────
+    /**
+     * Wire an EventEmitter for registry-side audit emits.
+     *
+     * Per the apcore RFC `apcore/docs/spec/rfc-ephemeral-modules.md`
+     * "Audit-event single-emit rule", `ephemeral.*` registrations and
+     * unregistrations emit a single `apcore.registry.module_registered` /
+     * `apcore.registry.module_unregistered` event with the D-35 contextual
+     * payload. When no emitter is wired, the event is logged at INFO so it
+     * never silently disappears — useful for the v1 pilot where most
+     * callers will not have an emitter attached.
+     *
+     * Pilot scope: only `ephemeral.*` registrations trigger registry-side
+     * emits. The pre-existing bridge in
+     * `sys-modules/registration.ts` continues to emit empty-payload events
+     * for non-ephemeral modules and short-circuits for ephemerals so the
+     * single-emit rule holds.
+     */
+    setEventEmitter(emitter) {
+        this._eventEmitter = emitter;
+    }
+    /**
+     * Soft-warn when an `ephemeral.*` module is registered without
+     * `requiresApproval: true`. Per the ephemeral-modules RFC pilot,
+     * agent-synthesized modules SHOULD declare `requiresApproval` so a
+     * human gates execution. The registry only warns; it does not refuse
+     * the registration.
+     */
+    _warnIfMissingApproval(moduleId, module) {
+        const ann = module?.annotations;
+        let requiresApproval = false;
+        if (ann != null && typeof ann === 'object') {
+            const rec = ann;
+            requiresApproval = rec['requiresApproval'] === true || rec['requires_approval'] === true;
+        }
+        if (!requiresApproval) {
+            console.warn(`[apcore:registry] ephemeral.* module '${moduleId}' registered without ` +
+                `requiresApproval=true. The apcore RFC docs/spec/rfc-ephemeral-modules.md ` +
+                `recommends setting ModuleAnnotations.requiresApproval=true so ` +
+                `agent-synthesized code does not run unattended.`);
+        }
+    }
+    /**
+     * Build the D-35 audit payload (`caller_id` plus optional `identity`
+     * snapshot) for an ephemeral.* register/unregister. Mirrors the shape
+     * `extractAuditIdentity` produces for `system.control.*` events so
+     * subscribers can apply identical redaction rules.
+     */
+    _buildEphemeralAuditPayload(context) {
+        const callerIdRaw = context?.callerId;
+        const callerId = callerIdRaw == null || callerIdRaw === '' ? '@external' : callerIdRaw;
+        const ident = context?.identity ?? null;
+        if (!ident) {
+            return { caller_id: callerId, identity: null, namespace_class: 'ephemeral' };
+        }
+        const snapshot = {
+            id: ident.id,
+            type: ident.type,
+            roles: [...ident.roles],
+        };
+        const displayName = ident.attrs['display_name'];
+        if (typeof displayName === 'string' && displayName.length > 0) {
+            snapshot['display_name'] = displayName;
+        }
+        return { caller_id: callerId, identity: snapshot, namespace_class: 'ephemeral' };
+    }
+    /**
+     * Emit the canonical ephemeral.* audit event to the wired EventEmitter
+     * (or warn-log if none is wired). The bridge in
+     * `sys-modules/registration.ts` short-circuits on ephemeral.* IDs so
+     * exactly one event lands per registration / unregistration.
+     */
+    _emitEphemeralAudit(eventType, moduleId, context) {
+        let payload;
+        try {
+            payload = this._buildEphemeralAuditPayload(context);
+        }
+        catch (e) {
+            console.warn(`[apcore:registry] Failed to extract audit payload for ephemeral '${moduleId}': ${e.message}. ` +
+                `Falling back to caller_id='@external'.`);
+            payload = { caller_id: '@external', identity: null, namespace_class: 'ephemeral' };
+        }
+        const emitter = this._eventEmitter;
+        if (emitter === null) {
+            console.info(`[apcore:registry] ephemeral audit event ${eventType} module_id=${moduleId} ` +
+                `payload=${JSON.stringify(payload)} (no EventEmitter wired; call ` +
+                `Registry.setEventEmitter to capture)`);
+            return;
+        }
+        const event = {
+            eventType,
+            moduleId,
+            timestamp: new Date().toISOString(),
+            severity: 'info',
+            data: payload,
+        };
+        try {
+            emitter.emit(event);
+        }
+        catch (e) {
+            console.error(`[apcore:registry] EventEmitter.emit failed for ephemeral audit event ` +
+                `${eventType} on '${moduleId}':`, e);
+        }
+    }
     async safeUnregister(moduleId, timeoutMs = 5000) {
         if (!this._modules.has(moduleId))
             return false;