apcore-js 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-02-20
+
+### Added
+
+- **Error classes and constants**
+  - `ModuleExecuteError` — New error class for module execution failures
+  - `InternalError` — New error class for general internal errors
+  - `ErrorCodes` — Frozen object with all 26 error code strings for consistent error code usage
+  - `ErrorCode` — Type definition for all error codes
+- **Registry constants**
+  - `REGISTRY_EVENTS` — Frozen object with standard event names (`register`, `unregister`)
+  - `MODULE_ID_PATTERN` — Regex pattern enforcing lowercase/digits/underscores/dots for module IDs (no hyphens allowed to ensure bijective MCP tool name normalization)
+- **Executor methods**
+  - `Executor.callAsync()` — Alias for `call()` for compatibility with MCP bridge packages
+
+### Changed
+
+- **Module ID validation** — Registry now validates module IDs against `MODULE_ID_PATTERN` on registration, rejecting IDs with hyphens or invalid characters
+- **Event handling** — Registry event validation now uses `REGISTRY_EVENTS` constants instead of hardcoded strings
+- **Test updates** — Updated tests to use underscore-separated module IDs instead of hyphens (e.g., `math.add_ten` instead of `math.addTen`, `ctx_test` instead of `ctx-test`)
+
+### Fixed
+
+- **String literals in Registry** — Replaced hardcoded `'register'` and `'unregister'` strings with `REGISTRY_EVENTS.REGISTER` and `REGISTRY_EVENTS.UNREGISTER` constants in event triggers for consistency
+
 ## [0.1.2] - 2026-02-18
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "AI-Perceivable Core — schema-driven module development framework",
   "type": "module",
   "main": "./dist/index.js",

package/planning/overview.md

@@ -3,7 +3,7 @@
 ## Overall Progress
 
 ```
-[████████████████████████████████████████] 42/42 tasks (100%)
+[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] 42/42 tasks (100%)
 ```
 
 | Status | Count |

package/src/errors.ts

@@ -367,3 +367,58 @@ export class ModuleLoadError extends ModuleError {
     this.name = 'ModuleLoadError';
   }
 }
+
+export class ModuleExecuteError extends ModuleError {
+  constructor(moduleId: string, reason: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'MODULE_EXECUTE_ERROR',
+      `Failed to execute module '${moduleId}': ${reason}`,
+      { moduleId, reason },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'ModuleExecuteError';
+  }
+}
+
+export class InternalError extends ModuleError {
+  constructor(message: string = 'Internal error', options?: { cause?: Error; traceId?: string }) {
+    super('GENERAL_INTERNAL_ERROR', message, {}, options?.cause, options?.traceId);
+    this.name = 'InternalError';
+  }
+}
+
+/**
+ * All framework error codes as constants.
+ * Use these instead of hardcoding error code strings.
+ */
+export const ErrorCodes = Object.freeze({
+  CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+  CONFIG_INVALID: "CONFIG_INVALID",
+  ACL_RULE_ERROR: "ACL_RULE_ERROR",
+  ACL_DENIED: "ACL_DENIED",
+  MODULE_NOT_FOUND: "MODULE_NOT_FOUND",
+  MODULE_TIMEOUT: "MODULE_TIMEOUT",
+  MODULE_LOAD_ERROR: "MODULE_LOAD_ERROR",
+  MODULE_EXECUTE_ERROR: "MODULE_EXECUTE_ERROR",
+  SCHEMA_VALIDATION_ERROR: "SCHEMA_VALIDATION_ERROR",
+  SCHEMA_NOT_FOUND: "SCHEMA_NOT_FOUND",
+  SCHEMA_PARSE_ERROR: "SCHEMA_PARSE_ERROR",
+  SCHEMA_CIRCULAR_REF: "SCHEMA_CIRCULAR_REF",
+  CALL_DEPTH_EXCEEDED: "CALL_DEPTH_EXCEEDED",
+  CIRCULAR_CALL: "CIRCULAR_CALL",
+  CALL_FREQUENCY_EXCEEDED: "CALL_FREQUENCY_EXCEEDED",
+  GENERAL_INVALID_INPUT: "GENERAL_INVALID_INPUT",
+  GENERAL_INTERNAL_ERROR: "GENERAL_INTERNAL_ERROR",
+  FUNC_MISSING_TYPE_HINT: "FUNC_MISSING_TYPE_HINT",
+  FUNC_MISSING_RETURN_TYPE: "FUNC_MISSING_RETURN_TYPE",
+  BINDING_INVALID_TARGET: "BINDING_INVALID_TARGET",
+  BINDING_MODULE_NOT_FOUND: "BINDING_MODULE_NOT_FOUND",
+  BINDING_CALLABLE_NOT_FOUND: "BINDING_CALLABLE_NOT_FOUND",
+  BINDING_NOT_CALLABLE: "BINDING_NOT_CALLABLE",
+  BINDING_SCHEMA_MISSING: "BINDING_SCHEMA_MISSING",
+  BINDING_FILE_INVALID: "BINDING_FILE_INVALID",
+  CIRCULAR_DEPENDENCY: "CIRCULAR_DEPENDENCY",
+} as const);
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];

package/src/executor.ts

@@ -168,6 +168,18 @@ export class Executor {
     return this._executeWithMiddleware(mod, moduleId, effectiveInputs, ctx);
   }
 
+  /**
+   * Alias for call(). Provided for compatibility with MCP bridge packages
+   * that may call callAsync() by convention.
+   */
+  async callAsync(
+    moduleId: string,
+    inputs?: Record<string, unknown> | null,
+    context?: Context | null,
+  ): Promise<Record<string, unknown>> {
+    return this.call(moduleId, inputs, context);
+  }
+
   private _createContext(moduleId: string, context?: Context | null): Context {
     if (context == null) {
       return Context.create(this).child(moduleId);

package/src/index.ts

@@ -5,7 +5,7 @@
 // Core
 export { Context, createIdentity } from './context.js';
 export type { Identity } from './context.js';
-export { Registry } from './registry/registry.js';
+export { Registry, REGISTRY_EVENTS, MODULE_ID_PATTERN } from './registry/registry.js';
 export { Executor, redactSensitive, REDACTED_VALUE } from './executor.js';
 
 // Module types
@@ -42,7 +42,11 @@ export {
   BindingFileInvalidError,
   CircularDependencyError,
   ModuleLoadError,
+  ModuleExecuteError,
+  InternalError,
+  ErrorCodes,
 } from './errors.js';
+export type { ErrorCode } from './errors.js';
 
 // ACL
 export { ACL } from './acl.js';

package/src/registry/registry.ts

@@ -13,6 +13,20 @@ import { scanExtensions, scanMultiRoot } from './scanner.js';
 import type { DependencyInfo, ModuleDescriptor } from './types.js';
 import { validateModule } from './validation.js';
 
+/**
+ * Standard registry event names.
+ */
+export const REGISTRY_EVENTS = Object.freeze({
+  REGISTER: "register",
+  UNREGISTER: "unregister",
+} as const);
+
+/**
+ * Valid module ID pattern. Only lowercase letters, digits, underscores, and dots.
+ * Hyphens are prohibited to ensure bijective MCP/OpenAI tool name normalization.
+ */
+export const MODULE_ID_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+
 type EventCallback = (moduleId: string, module: unknown) => void;
 
 export class Registry {
@@ -20,8 +34,8 @@ export class Registry {
   private _modules: Map<string, unknown> = new Map();
   private _moduleMeta: Map<string, Record<string, unknown>> = new Map();
   private _callbacks: Map<string, EventCallback[]> = new Map([
-    ['register', []],
-    ['unregister', []],
+    [REGISTRY_EVENTS.REGISTER, []],
+    [REGISTRY_EVENTS.UNREGISTER, []],
   ]);
   private _idMap: Record<string, Record<string, unknown>> = {};
   private _schemaCache: Map<string, Record<string, unknown>> = new Map();
@@ -187,15 +201,20 @@ export class Registry {
         }
       }
 
-      this._triggerEvent('register', modId, mod);
+      this._triggerEvent(REGISTRY_EVENTS.REGISTER, modId, mod);
       count++;
     }
     return count;
   }
 
   register(moduleId: string, module: unknown): void {
-    if (!moduleId) {
-      throw new InvalidInputError('module_id must be a non-empty string');
+    if (!moduleId || typeof moduleId !== "string") {
+      throw new InvalidInputError("Module ID must be a non-empty string");
+    }
+    if (!MODULE_ID_PATTERN.test(moduleId)) {
+      throw new InvalidInputError(
+        `Invalid module ID: "${moduleId}". Must match pattern: ${MODULE_ID_PATTERN} (lowercase, digits, underscores, dots only; no hyphens)`,
+      );
     }
 
     if (this._modules.has(moduleId)) {
@@ -215,7 +234,7 @@ export class Registry {
       }
     }
 
-    this._triggerEvent('register', moduleId, module);
+    this._triggerEvent(REGISTRY_EVENTS.REGISTER, moduleId, module);
   }
 
   unregister(moduleId: string): boolean {
@@ -236,7 +255,7 @@ export class Registry {
       }
     }
 
-    this._triggerEvent('unregister', moduleId, module);
+    this._triggerEvent(REGISTRY_EVENTS.UNREGISTER, moduleId, module);
     return true;
   }
 
@@ -311,8 +330,11 @@ export class Registry {
   }
 
   on(event: string, callback: EventCallback): void {
-    if (!this._callbacks.has(event)) {
-      throw new InvalidInputError(`Invalid event: ${event}. Must be 'register' or 'unregister'`);
+    const validEvents = Object.values(REGISTRY_EVENTS) as string[];
+    if (!validEvents.includes(event)) {
+      throw new InvalidInputError(
+        `Invalid event: ${event}. Must be one of: ${validEvents.map((e) => `'${e}'`).join(', ')}`,
+      );
     }
     this._callbacks.get(event)!.push(callback);
   }

package/tests/integration/test-e2e-flow.test.ts

@@ -72,21 +72,21 @@ describe('E2E Flow', () => {
     });
     const modB = new FunctionModule({
       execute: (inputs) => ({ value: (inputs['x'] as number) + 10 }),
-      moduleId: 'math.addTen',
+      moduleId: 'math.add_ten',
       inputSchema: Type.Object({ x: Type.Number() }),
       outputSchema: Type.Object({ value: Type.Number() }),
       description: 'Add ten',
     });
     registry.register('math.double', modA);
-    registry.register('math.addTen', modB);
+    registry.register('math.add_ten', modB);
 
     const executor = new Executor({ registry });
-    const ctx = Context.create(executor, createIdentity('test-user'));
+    const ctx = Context.create(executor, createIdentity('test_user'));
 
     const r1 = await executor.call('math.double', { x: 5 }, ctx);
     expect(r1['value']).toBe(10);
 
-    const r2 = await executor.call('math.addTen', { x: r1['value'] as number }, ctx);
+    const r2 = await executor.call('math.add_ten', { x: r1['value'] as number }, ctx);
     expect(r2['value']).toBe(20);
   });
 

package/tests/test-executor.test.ts

@@ -221,16 +221,16 @@ describe('Executor', () => {
     let capturedCtx: Context | null = null;
     const mod = new FunctionModule({
       execute: (_inputs, ctx) => { capturedCtx = ctx; return { ok: true }; },
-      moduleId: 'ctx-test',
+      moduleId: 'ctx_test',
       inputSchema: Type.Object({}),
       outputSchema: Type.Object({ ok: Type.Boolean() }),
       description: 'Context capture',
     });
-    registry.register('ctx-test', mod);
+    registry.register('ctx_test', mod);
 
     const executor = new Executor({ registry });
     const ctx = Context.create(executor, createIdentity('user1'));
-    await executor.call('ctx-test', {}, ctx);
+    await executor.call('ctx_test', {}, ctx);
 
     expect(capturedCtx).not.toBeNull();
     expect(capturedCtx!.traceId).toBe(ctx.traceId);