apcore-js 0.21.1 → 0.23.0

package/dist/registry/registry.js

@@ -2,7 +2,8 @@
  * Central module registry for discovering, registering, and querying modules.
  */
 import { getDefault } from '../config-defaults.js';
-import { InvalidInputError, ModuleNotFoundError } from '../errors.js';
+import { DuplicateModuleIdError, ErrorCodes, InvalidInputError, ModuleNotFoundError, StreamingInterfaceError, } from '../errors.js';
+import { isStreamingModule } from '../streaming.js';
 import { detectIdConflicts } from './conflicts.js';
 import { resolveDependencies } from './dependencies.js';
 import { resolveEntryPoint } from './entry-point.js';
@@ -137,22 +138,22 @@ export function isEphemeralModuleId(moduleId) {
 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');
+        throw new InvalidInputError('module_id must be a non-empty string', undefined, ErrorCodes.INVALID_MODULE_ID);
     }
     // 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)`);
+        throw new InvalidInputError(`Invalid module ID: '${moduleId}'. Must match pattern: ${MODULE_ID_PATTERN.source} (lowercase, digits, underscores, dots only; no hyphens)`, undefined, ErrorCodes.INVALID_MODULE_ID);
     }
     // 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}`);
+        throw new InvalidInputError(`Module ID exceeds maximum length of ${MAX_MODULE_ID_LENGTH}: ${moduleId.length}`, undefined, ErrorCodes.INVALID_MODULE_ID);
     }
     // 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}'`);
+            throw new InvalidInputError(`Module ID contains reserved word: '${firstSegment}'`, undefined, ErrorCodes.INVALID_MODULE_ID);
         }
     }
 }
@@ -178,6 +179,13 @@ export class Registry {
     _refCounts = new Map();
     _draining = new Set();
     _drainResolvers = new Map();
+    /**
+     * In-flight async registrations: modules whose async onLoad has not yet
+     * resolved. Keys in this map are NOT visible via get()/has() until the
+     * promise resolves and the module is committed to _modules.
+     * This enforces deferred-publish for async onLoad (issue #65).
+     */
+    _inFlight = new Map();
     /**
      * Optional EventEmitter for the ephemeral.* registry-side audit emits
      * (RFC `apcore/docs/spec/rfc-ephemeral-modules.md` "Audit-event single-emit
@@ -349,7 +357,7 @@ export class Registry {
             `'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.`);
+            `directory or extension namespace.`, undefined, ErrorCodes.INVALID_MODULE_ID);
     }
     async _applyIdMapOverrides(discovered) {
         if (Object.keys(this._idMap).length === 0)
@@ -496,31 +504,45 @@ export class Registry {
         ]);
         return resolveDependencies(modulesWithDeps, knownIds, moduleVersions);
     }
-    _registerInOrder(loadOrder, validModules, rawMetadata) {
+    async _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.
+        //
+        // Deferred-publish contract (issue #65, audit D11-001 / D10-005): a module
+        // is NEVER published to `_modules`/`_moduleMeta`/`_lowercaseMap` until its
+        // `onLoad` (sync or async) has succeeded. This mirrors the public
+        // `_registerWithOnLoad` path: the caller observes either a fully-published
+        // module OR an `apcore.registry.module_load_failed` event — never a module
+        // that is visible mid-load. On `onLoad` failure we emit the event, skip
+        // publishing, and move to the next module (skip-on-failure, never abort).
         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);
+            // Run onLoad BEFORE publishing. Handle both sync and async onLoad: call
+            // it, and if it returns a Promise, await it.
             if (typeof modObj['onLoad'] === 'function') {
                 try {
-                    modObj['onLoad']();
+                    const onLoadResult = modObj['onLoad']();
+                    if (onLoadResult instanceof Promise) {
+                        await onLoadResult;
+                    }
                 }
                 catch (e) {
+                    // Sync throw or async rejection: emit module_load_failed, do NOT
+                    // publish, warn, and skip to the next module.
+                    this._emitModuleLoadFailed(modId, e);
                     console.warn(`[apcore:registry] onLoad failed for ${modId}, skipping:`, e);
-                    this._modules.delete(modId);
-                    this._moduleMeta.delete(modId);
-                    this._lowercaseMap.delete(modId.toLowerCase());
                     continue;
                 }
             }
+            // Success (including empty / no-onLoad modules): publish all state.
+            const mergedMeta = mergeModuleMetadata(modObj, rawMetadata.get(modId) ?? {});
+            this._modules.set(modId, mod);
+            this._moduleMeta.set(modId, mergedMeta);
+            this._lowercaseMap.set(modId.toLowerCase(), modId);
             this._triggerEvent(REGISTRY_EVENTS.REGISTER, modId, mod);
             count++;
         }
@@ -539,8 +561,18 @@ export class Registry {
      * 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.
+     *
+     * Returns a Promise that resolves once `onLoad` (if any) completes and the
+     * module is fully visible. For modules without `onLoad` or with a sync
+     * `onLoad`, the module is visible immediately (before the promise resolves)
+     * so existing sync callers that do not `await` continue to work.
+     *
+     * All sync validation errors (invalid ID, duplicate, streaming mismatch,
+     * sync onLoad failure) are thrown synchronously for backward compatibility
+     * with callers that use `expect(() => register(...)).toThrow(...)` patterns.
      */
     register(moduleId, module, version, metadata, options) {
+        // 1. ID validation (always sync — throws synchronously for backward compat)
         validateModuleId(moduleId, false);
         // ephemeral.* registrations only land via this programmatic path —
         // the filesystem discoverer rejects matching IDs upstream (see
@@ -551,54 +583,201 @@ export class Registry {
         if (ephemeral) {
             this._warnIfMissingApproval(moduleId, module);
         }
+        // 2. Duplicate detection (sync — preserves backward compat with `.toThrow()` tests)
+        const conflict = detectIdConflicts(moduleId, new Set([...this._modules.keys(), ...this._inFlight.keys()]), RESERVED_WORDS, this._lowercaseMap);
+        if (conflict !== null) {
+            if (conflict.severity === 'error') {
+                if (conflict.type === 'duplicate_id') {
+                    throw new DuplicateModuleIdError(moduleId);
+                }
+                throw new InvalidInputError(conflict.message);
+            }
+            console.warn(`[apcore:registry] ID conflict: ${conflict.message}`);
+        }
+        // 3. Streaming annotation validation (sync — preserves .toThrow() compat)
+        const modForStreaming = module;
+        const annForStreaming = modForStreaming['annotations'];
+        if (annForStreaming != null && typeof annForStreaming === 'object') {
+            const streamingFlag = annForStreaming['streaming'];
+            if (streamingFlag === true) {
+                const hasStreamMethod = typeof modForStreaming['stream'] === 'function';
+                const hasMarker = modForStreaming[Symbol.for('apcore.streaming')] === true;
+                if (!isStreamingModule(module)) {
+                    throw new StreamingInterfaceError(moduleId, true, hasStreamMethod, hasMarker);
+                }
+            }
+        }
+        // 4. Custom validator (may be async)
         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.`);
+                return result.then((errors) => {
+                    if (errors.length > 0) {
+                        throw new InvalidInputError(`Custom validator rejected module '${moduleId}': ${errors.join('; ')}`);
+                    }
+                    return this._registerWithOnLoad(moduleId, module, version, metadata, options, ephemeral);
+                });
             }
             if (result.length > 0) {
                 throw new InvalidInputError(`Custom validator rejected module '${moduleId}': ${result.join('; ')}`);
             }
         }
+        return this._registerWithOnLoad(moduleId, module, version, metadata, options, ephemeral);
+    }
+    /**
+     * Core registration logic after all sync validation has passed.
+     * Handles both sync and async onLoad with deferred-publish for async.
+     *
+     * For sync or absent onLoad: module becomes visible immediately, returns
+     * a resolved Promise (backward-compatible sync usage continues to work).
+     * For async onLoad: module is tracked in _inFlight and hidden from get()/has()
+     * until onLoad resolves; then committed to _modules and made visible.
+     */
+    _registerWithOnLoad(moduleId, module, version, metadata, options, ephemeral) {
         const overrides = { ...(metadata ?? {}) };
         if (version !== undefined && version !== null) {
             overrides['version'] = version;
         }
-        this._registerImpl(moduleId, module, overrides);
+        // Detect async onLoad
+        const modObj = module;
+        if (typeof modObj['onLoad'] === 'function') {
+            // Call onLoad and check if it returns a Promise.
+            // Sync onLoad must emit module_load_failed on throw (Issue #65 gap;
+            // mirror the async-Promise rejection branch below). The strong-guarantee
+            // invariant — caller observes either fully-published or
+            // module_load_failed — applies to every registration path including
+            // this entry point.
+            // A-D-013: reserve the in-flight slot BEFORE invoking onLoad, for both
+            // sync and async onLoad. The module MUST NOT be observable via get()/has()
+            // while onLoad runs (strong-guarantee invariant #65). Reserving uniformly
+            // — not only for the async branch — makes the in-flight gate effective
+            // for a sync onLoad that re-entrantly inspects the registry, matching
+            // apcore-python (_in_flight.add before on_load) and apcore-rust.
+            // A resolved placeholder Promise is used as the sync sentinel; the
+            // async branch overwrites it with the real loadPromise below.
+            this._inFlight.set(moduleId, Promise.resolve());
+            let onLoadResult;
+            try {
+                onLoadResult = modObj['onLoad']();
+            }
+            catch (e) {
+                // Surface sync onLoad failures as a rejected Promise so the
+                // strong-guarantee invariant — `register()` always returns a Promise
+                // — holds for sync and async onLoad alike. Without this, callers
+                // doing `await registry.register(...)` would see sync throws and the
+                // module_load_failed event would arrive before the await target.
+                this._inFlight.delete(moduleId);
+                this._emitModuleLoadFailed(moduleId, e);
+                return Promise.reject(e);
+            }
+            if (onLoadResult instanceof Promise) {
+                // Async onLoad: deferred-publish
+                // Register metadata and lowercase index (but NOT _modules) so conflict
+                // detection works for concurrent registrations of the same ID.
+                const modObjFull = module;
+                this._moduleMeta.set(moduleId, mergeModuleMetadata(modObjFull, overrides));
+                this._lowercaseMap.set(moduleId.toLowerCase(), moduleId);
+                const loadPromise = onLoadResult.then(() => {
+                    // Commit module to visible state
+                    this._modules.set(moduleId, module);
+                    this._inFlight.delete(moduleId);
+                    this._triggerEvent(REGISTRY_EVENTS.REGISTER, moduleId, module);
+                    if (ephemeral) {
+                        this._emitEphemeralAudit('apcore.registry.module_registered', moduleId, options?.context ?? null);
+                    }
+                }, (err) => {
+                    // onLoad failed: rollback all state
+                    this._inFlight.delete(moduleId);
+                    this._moduleMeta.delete(moduleId);
+                    this._lowercaseMap.delete(moduleId.toLowerCase());
+                    // Emit module_load_failed event (spec #65)
+                    this._emitModuleLoadFailed(moduleId, err);
+                    throw err;
+                });
+                // Guard against unhandled rejection if caller fire-and-forgets (no await)
+                loadPromise.catch(() => { });
+                this._inFlight.set(moduleId, loadPromise);
+                return loadPromise;
+            }
+            // Sync onLoad returned (possibly undefined) — fall through to normal
+            // registration. Release the in-flight reservation now that onLoad has
+            // succeeded; the module becomes visible on the publish below (A-D-013).
+            this._inFlight.delete(moduleId);
+        }
+        // Sync path: no onLoad, or sync onLoad already called above
+        this._modules.set(moduleId, module);
+        this._lowercaseMap.set(moduleId.toLowerCase(), moduleId);
+        const modObjFull = module;
+        this._moduleMeta.set(moduleId, mergeModuleMetadata(modObjFull, overrides));
+        this._triggerEvent(REGISTRY_EVENTS.REGISTER, moduleId, module);
         if (ephemeral) {
             this._emitEphemeralAudit('apcore.registry.module_registered', moduleId, options?.context ?? null);
         }
+        return Promise.resolve();
     }
-    /** Inner registration — no validator, no ID validation. Used by discover() paths that run their own checks. */
+    /**
+     * Inner registration — no validator, no ID validation. Used by discover() paths that run
+     * their own checks. Validates streaming annotation, runs sync onLoad, commits to _modules.
+     */
     _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);
+        const conflict = detectIdConflicts(moduleId, new Set([...this._modules.keys(), ...this._inFlight.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}`);
+            console.warn(`[apcore:registry] ID conflict: ${conflict.message}`);
+        }
+        // Streaming annotation validation: if module declares streaming=true it must
+        // implement the StreamingModule interface (has stream() + STREAMING_MARKER).
+        const modForStreaming = module;
+        const annForStreaming = modForStreaming['annotations'];
+        if (annForStreaming != null && typeof annForStreaming === 'object') {
+            const streamingFlag = annForStreaming['streaming'];
+            if (streamingFlag === true) {
+                const hasStreamMethod = typeof modForStreaming['stream'] === 'function';
+                const hasMarker = modForStreaming[Symbol.for('apcore.streaming')] === true;
+                if (!isStreamingModule(module)) {
+                    throw new StreamingInterfaceError(moduleId, true, hasStreamMethod, hasMarker);
+                }
             }
         }
-        this._modules.set(moduleId, module);
-        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.
+        // A-D-REG-003 / spec REG-003: deferred-publish for the discover path.
+        // Reserve the slot in metadata + lowercase index (for conflict detection)
+        // but do NOT insert into `_modules` until onLoad has completed. The
+        // strong-guarantee invariant (#65) applies uniformly to every registration
+        // path including discover/hot-reload — observers must never see a module
+        // that subsequently fails its onLoad.
         const modObj = module;
         this._moduleMeta.set(moduleId, mergeModuleMetadata(modObj, metadataOverrides));
-        // Call onLoad if available
+        this._lowercaseMap.set(moduleId.toLowerCase(), moduleId);
+        // Call onLoad if available (sync only in this discover() path)
         if (typeof modObj['onLoad'] === 'function') {
+            let onLoadResult;
             try {
-                modObj['onLoad']();
+                onLoadResult = modObj['onLoad']();
             }
             catch (e) {
-                this._modules.delete(moduleId);
+                // Rollback the reservation: nothing was published, so observers
+                // never saw the module.
                 this._moduleMeta.delete(moduleId);
                 this._lowercaseMap.delete(moduleId.toLowerCase());
+                this._emitModuleLoadFailed(moduleId, e);
                 throw e;
             }
+            if (onLoadResult instanceof Promise) {
+                // Async onLoad in discover() path: warn and skip — deferred-publish
+                // with async onLoad is only available via the public register() API.
+                console.warn(`[apcore:registry] Module '${moduleId}' has async onLoad in discover() path ` +
+                    `— async onLoad is not supported here; use Registry.register() instead. Module skipped.`);
+                this._moduleMeta.delete(moduleId);
+                this._lowercaseMap.delete(moduleId.toLowerCase());
+                onLoadResult.catch(() => { }); // prevent unhandled rejection
+                return;
+            }
         }
+        // onLoad succeeded — now commit the module to the visible map.
+        this._modules.set(moduleId, module);
         this._triggerEvent(REGISTRY_EVENTS.REGISTER, moduleId, module);
     }
     unregister(moduleId, options) {
@@ -641,9 +820,20 @@ export class Registry {
         if (moduleId === '') {
             throw new ModuleNotFoundError('');
         }
+        // In-flight modules are not yet visible — spec #65: module MUST NOT be
+        // observable via get() until onLoad completes. Cross-SDK canonical
+        // behaviour (Python/Rust, A-D-002) is to return null for an in-flight id,
+        // matching this SDK's own well-formed-unregistered → null contract and
+        // getDefinition()'s null return for the same case (asymmetry removed).
+        if (this._inFlight.has(moduleId)) {
+            return null;
+        }
         return this._modules.get(moduleId) ?? null;
     }
     has(moduleId) {
+        // In-flight modules are not visible (same invariant as get())
+        if (this._inFlight.has(moduleId))
+            return false;
         return this._modules.has(moduleId);
     }
     /**
@@ -656,11 +846,25 @@ export class Registry {
      * `includeHidden: true` to enumerate every registered module — useful
      * for introspection tools, debug consoles, and tests.
      */
+    /**
+     * Return sorted list of unique registered module IDs, optionally filtered.
+     *
+     * @param options.tags When supplied, only modules carrying *all* of the given tags are returned.
+     * @param options.prefix When supplied, only IDs starting with the prefix are returned.
+     * @param options.visibility Filter by module visibility. Supported: `['public', 'hidden']`.
+     *                           Defaults to `['public']`. Aligned with apcore D-24.
+     * @param options.includeHidden Deprecated. Use `visibility: ['public', 'hidden']` instead.
+     */
     list(options) {
         let ids = [...this._modules.keys()];
-        if (options?.includeHidden !== true) {
-            ids = ids.filter((id) => this._isDiscoverable(id));
-        }
+        // D-24 alignment: visibility list takes precedence over legacy includeHidden bool.
+        const vis = options?.visibility ?? (options?.includeHidden === true ? ['public', 'hidden'] : ['public']);
+        const showPublic = vis.includes('public');
+        const showHidden = vis.includes('hidden');
+        ids = ids.filter((id) => {
+            const isDisc = this._isDiscoverable(id);
+            return (isDisc && showPublic) || (!isDisc && showHidden);
+        });
         if (options?.prefix != null) {
             ids = ids.filter((id) => id.startsWith(options.prefix));
         }
@@ -1033,11 +1237,13 @@ export class Registry {
             if (conflict.severity === 'error') {
                 throw new InvalidInputError(conflict.message);
             }
-            else {
-                console.warn(`[apcore:registry] ID conflict: ${conflict.message}`);
-            }
+            console.warn(`[apcore:registry] ID conflict: ${conflict.message}`);
         }
-        this._modules.set(moduleId, module);
+        // A-D-REG-004 / spec REG-003: deferred-publish for registerInternal.
+        // Reserve metadata + lowercase index but defer the visible _modules
+        // insert until onLoad succeeds so the strong-guarantee invariant (#65)
+        // holds uniformly across `register()`, `registerInternal`, and
+        // discover/hot-reload paths.
         const modObj = module;
         this._moduleMeta.set(moduleId, mergeModuleMetadata(modObj, {}));
         // Mirror apcore-python register_internal and apcore-rust register_core:
@@ -1051,12 +1257,13 @@ export class Registry {
                 modObj['onLoad']();
             }
             catch (e) {
-                this._modules.delete(moduleId);
                 this._moduleMeta.delete(moduleId);
                 this._lowercaseMap.delete(moduleId.toLowerCase());
+                this._emitModuleLoadFailed(moduleId, e);
                 throw e;
             }
         }
+        this._modules.set(moduleId, module);
         this._triggerEvent(REGISTRY_EVENTS.REGISTER, moduleId, module);
     }
     /**
@@ -1272,6 +1479,39 @@ export class Registry {
         }
         return { caller_id: callerId, identity: snapshot, namespace_class: 'ephemeral' };
     }
+    /**
+     * Emit `apcore.registry.module_load_failed` when onLoad raises (spec #65).
+     * Delivered synchronously if the emitter is wired; logged as warn otherwise.
+     */
+    _emitModuleLoadFailed(moduleId, err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const payload = {
+            module_id: moduleId,
+            callback_name: 'module.onLoad',
+            error_type: error.constructor?.name ?? 'Error',
+            error_message: error.message,
+            timestamp: new Date().toISOString(),
+        };
+        const emitter = this._eventEmitter;
+        if (emitter === null) {
+            console.warn(`[apcore:registry] module_load_failed module_id=${moduleId} ` +
+                `error_type=${payload['error_type']} message=${error.message}`);
+            return;
+        }
+        const event = {
+            eventType: 'apcore.registry.module_load_failed',
+            moduleId,
+            timestamp: new Date().toISOString(),
+            severity: 'error',
+            data: payload,
+        };
+        try {
+            emitter.emit(event);
+        }
+        catch (emitErr) {
+            console.error('[apcore:registry] Failed to emit module_load_failed:', emitErr);
+        }
+    }
     /**
      * Emit the canonical ephemeral.* audit event to the wired EventEmitter
      * (or warn-log if none is wired). The bridge in