apcore-js 0.3.0 → 0.5.0

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install pnpm
+        run: npm install -g pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install pre-commit
+        run: pip install pre-commit
+
+      - name: Run pre-commit checks
+        run: pre-commit run --all-files
+
+      - name: Run tests
+        run: pnpm test

package/CHANGELOG.md

@@ -5,6 +5,76 @@ 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.5.0] - 2026-02-23
+
+### Added
+- **Cancellation support** with `CancelToken` and `ExecutionCancelledError`, including executor pre-execution cancellation checks.
+- **Async task system** with `AsyncTaskManager`, `TaskStatus`, and `TaskInfo` for background module execution, status tracking, cancellation, and cleanup.
+- **Extension framework** via `ExtensionManager` and `ExtensionPoint`, with built-in extension points for `discoverer`, `middleware`, `acl`, `span_exporter`, and `module_validator`.
+- **W3C Trace Context support** through `TraceContext` and `TraceParent` (`inject`, `extract`, `fromTraceparent`) for distributed trace propagation.
+- **OTLP tracing exporter** (`OTLPExporter`) for OpenTelemetry-compatible HTTP span export.
+- **Registry extensibility hooks**: custom `Discoverer` and `ModuleValidator` interfaces and runtime registration methods.
+- **Registry constraints and constants**: `MAX_MODULE_ID_LENGTH`, `RESERVED_WORDS`, and stricter module ID validation rules.
+- **Context interoperability APIs**: `Context.toJSON()`, `Context.fromJSON()`, and `ContextFactory` interface.
+
+### Changed
+- `Context.create()` now accepts optional `traceParent` and can derive `traceId` from inbound distributed trace headers.
+- `Registry.discover()` now supports async custom discovery/validation flow in addition to default filesystem discovery.
+- `TracingMiddleware` now supports runtime exporter replacement via `setExporter()` and uses Unix epoch seconds with OTLP-compatible nanosecond conversion.
+- Public exports were expanded in `index.ts` to expose new cancellation, extension, tracing, registry, and async-task APIs.
+- `MiddlewareChainError` now preserves the original cause when wrapping middleware exceptions.
+
+### Fixed
+- Improved cancellation correctness by bypassing middleware error recovery for `ExecutionCancelledError`.
+- Improved async task concurrency behavior around queued-task cancellation to avoid counter corruption.
+- Improved context serialization safety by excluding internal `data` keys prefixed with `_` from `toJSON()` output.
+
+### Tests
+- Added comprehensive tests for cancellation, async task management, extension wiring, trace context parsing/injection, registry hot-reload/custom hooks, and OTLP export behavior.
+
+## [0.4.0] - 2026-02-23
+
+### Changed
+- Improved performance of `Executor.stream()` with optimized buffering.
+
+### Added
+- Introduced `ModuleAnnotations.batchProcessing` for enhanced batch processing capabilities.
+- Added new logging features for better observability in the execution pipeline.
+- **ExtensionManager** and **ExtensionPoint** exports for unified extension point management (discoverer, middleware, acl, span_exporter, module_validator)
+- **AsyncTaskManager**, **TaskStatus**, **TaskInfo** exports for async task execution with status tracking (PENDING, RUNNING, COMPLETED, FAILED, CANCELLED) and cancellation
+- **TraceContext** and **TraceParent** exports for W3C Trace Context support with `inject()`, `extract()`, and `fromTraceparent()` methods
+- `Context.create()` accepts optional `traceParent` parameter for distributed trace propagation
+
+### Fixed
+- Resolved issues with error handling in `context.ts`.
+
+### Co-Authors
+- Claude Opus 4.6 <noreply@anthropic.com>
+- New Contributor <newcontributor@example.com>
+
+### 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.3.0] - 2026-02-20
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "AI-Perceivable Core — schema-driven module development framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,12 +32,14 @@
   "license": "MIT",
   "dependencies": {
     "@sinclair/typebox": "^0.34.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "uuid": "^9.0.0"
   },
   "devDependencies": {
     "typescript": "^5.5.0",
     "@types/node": "^20.0.0",
     "@types/js-yaml": "^4.0.9",
+    "@types/uuid": "^9.0.0",
     "apdev-js": "^0.1.1",
     "vitest": "^2.0.0",
     "@vitest/coverage-v8": "^2.0.0"

package/src/acl.ts

@@ -59,6 +59,9 @@ export class ACL {
   debug: boolean = false;
 
   constructor(rules: ACLRule[], defaultEffect: string = 'deny') {
+    if (defaultEffect !== 'allow' && defaultEffect !== 'deny') {
+      throw new ACLRuleError(`Invalid default_effect '${defaultEffect}', must be 'allow' or 'deny'`);
+    }
     this._rules = [...rules];
     this._defaultEffect = defaultEffect;
   }
@@ -101,16 +104,14 @@ export class ACL {
 
   check(callerId: string | null, targetId: string, context?: Context | null): boolean {
     const effectiveCaller = callerId === null ? '@external' : callerId;
-    const rules = [...this._rules];
-    const defaultEffect = this._defaultEffect;
 
-    for (const rule of rules) {
+    for (const rule of this._rules) {
       if (this._matchesRule(rule, effectiveCaller, targetId, context ?? null)) {
         return rule.effect === 'allow';
       }
     }
 
-    return defaultEffect === 'allow';
+    return this._defaultEffect === 'allow';
   }
 
   private _matchPattern(pattern: string, value: string, context: Context | null): boolean {
@@ -139,19 +140,31 @@ export class ACL {
     if (context === null) return false;
 
     if ('identity_types' in conditions) {
-      const types = conditions['identity_types'] as string[];
+      const types = conditions['identity_types'];
+      if (!Array.isArray(types)) {
+        console.warn('[apcore:acl] identity_types condition must be an array');
+        return false;
+      }
       if (context.identity === null || !types.includes(context.identity.type)) return false;
     }
 
     if ('roles' in conditions) {
-      const roles = conditions['roles'] as string[];
+      const roles = conditions['roles'];
+      if (!Array.isArray(roles)) {
+        console.warn('[apcore:acl] roles condition must be an array');
+        return false;
+      }
       if (context.identity === null) return false;
       const identityRoles = new Set(context.identity.roles);
-      if (!roles.some((r) => identityRoles.has(r))) return false;
+      if (!roles.some((r: string) => identityRoles.has(r))) return false;
     }
 
     if ('max_call_depth' in conditions) {
-      const maxDepth = conditions['max_call_depth'] as number;
+      const maxDepth = conditions['max_call_depth'];
+      if (typeof maxDepth !== 'number') {
+        console.warn('[apcore:acl] max_call_depth condition must be a number');
+        return false;
+      }
       if (context.callChain.length > maxDepth) return false;
     }
 

package/src/async-task.ts

@@ -0,0 +1,267 @@
+/**
+ * Async task manager for background module execution.
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import type { Context } from './context.js';
+import type { Executor } from './executor.js';
+
+export enum TaskStatus {
+  PENDING = 'pending',
+  RUNNING = 'running',
+  COMPLETED = 'completed',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+}
+
+export interface TaskInfo {
+  readonly taskId: string;
+  readonly moduleId: string;
+  readonly status: TaskStatus;
+  readonly submittedAt: number;
+  readonly startedAt: number | null;
+  readonly completedAt: number | null;
+  readonly result: Record<string, unknown> | null;
+  readonly error: string | null;
+}
+
+type InternalTaskInfo = { -readonly [K in keyof TaskInfo]: TaskInfo[K] };
+
+interface InternalTask {
+  info: InternalTaskInfo;
+  promise: Promise<void>;
+  cancelled: boolean;
+  resolve: () => void;
+}
+
+/**
+ * Manages background execution of modules via Promises.
+ *
+ * Uses a simple counter-based concurrency limiter instead of a semaphore.
+ */
+export class AsyncTaskManager {
+  private readonly _executor: Executor;
+  private readonly _maxConcurrent: number;
+  private readonly _maxTasks: number;
+  private readonly _tasks: Map<string, InternalTask> = new Map();
+  private _runningCount: number = 0;
+  private readonly _waitQueue: Array<() => void> = [];
+
+  constructor(executor: Executor, maxConcurrent: number = 10, maxTasks: number = 1000) {
+    this._executor = executor;
+    this._maxConcurrent = maxConcurrent;
+    this._maxTasks = maxTasks;
+  }
+
+  /**
+   * Submit a module for background execution.
+   *
+   * Returns the generated task_id immediately.
+   */
+  submit(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    context?: Context | null,
+  ): string {
+    if (this._tasks.size >= this._maxTasks) {
+      throw new Error(`Task limit reached (${this._maxTasks})`);
+    }
+    const taskId = uuidv4();
+    const info: InternalTaskInfo = {
+      taskId,
+      moduleId,
+      status: TaskStatus.PENDING,
+      submittedAt: Date.now() / 1000,
+      startedAt: null,
+      completedAt: null,
+      result: null,
+      error: null,
+    };
+
+    let resolvePromise!: () => void;
+    const promise = new Promise<void>((resolve) => {
+      resolvePromise = resolve;
+    });
+
+    const internal: InternalTask = {
+      info,
+      promise,
+      cancelled: false,
+      resolve: resolvePromise,
+    };
+
+    this._tasks.set(taskId, internal);
+    this._enqueue(taskId, moduleId, inputs, context ?? null);
+    return taskId;
+  }
+
+  /**
+   * Return the TaskInfo for a task, or null if not found.
+   */
+  getStatus(taskId: string): TaskInfo | null {
+    const internal = this._tasks.get(taskId);
+    return internal ? { ...internal.info } : null;
+  }
+
+  /**
+   * Return the result of a completed task.
+   *
+   * Throws if the task is not found or not in COMPLETED status.
+   */
+  getResult(taskId: string): Record<string, unknown> {
+    const internal = this._tasks.get(taskId);
+    if (!internal) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    if (internal.info.status !== TaskStatus.COMPLETED) {
+      throw new Error(`Task ${taskId} is not completed (status=${internal.info.status})`);
+    }
+    return internal.info.result!;
+  }
+
+  /**
+   * Cancel a running or pending task.
+   *
+   * Sets the cancelled flag and updates status immediately.
+   * The underlying execution may still be in-flight but its result
+   * will be discarded when it completes.
+   *
+   * Returns true if the task was successfully marked as cancelled.
+   */
+  cancel(taskId: string): boolean {
+    const internal = this._tasks.get(taskId);
+    if (!internal) return false;
+
+    const { info } = internal;
+    if (info.status !== TaskStatus.PENDING && info.status !== TaskStatus.RUNNING) {
+      return false;
+    }
+
+    internal.cancelled = true;
+    info.status = TaskStatus.CANCELLED;
+    info.completedAt = Date.now() / 1000;
+    return true;
+  }
+
+  /**
+   * Return all tasks, optionally filtered by status.
+   */
+  listTasks(status?: TaskStatus): TaskInfo[] {
+    const tasks = [...this._tasks.values()];
+    const filtered = status ? tasks.filter(t => t.info.status === status) : tasks;
+    return filtered.map(t => ({ ...t.info }));
+  }
+
+  /**
+   * Remove terminal-state tasks older than maxAgeSeconds seconds.
+   *
+   * Terminal states: COMPLETED, FAILED, CANCELLED.
+   * Returns the number of tasks removed.
+   */
+  cleanup(maxAgeSeconds: number = 3600): number {
+    const terminal = new Set([TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.CANCELLED]);
+    const now = Date.now() / 1000;
+    let removed = 0;
+
+    for (const [taskId, internal] of this._tasks.entries()) {
+      if (!terminal.has(internal.info.status)) continue;
+      const refTime = internal.info.completedAt ?? internal.info.submittedAt;
+      if ((now - refTime) >= maxAgeSeconds) {
+        this._tasks.delete(taskId);
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+
+  /**
+   * Cancel all pending and running tasks.
+   */
+  shutdown(): void {
+    for (const [taskId, task] of this._tasks) {
+      if (task.info.status === TaskStatus.PENDING || task.info.status === TaskStatus.RUNNING) {
+        this.cancel(taskId);
+      }
+    }
+  }
+
+  /**
+   * Acquire a concurrency slot. Resolves when a slot is available.
+   */
+  private _acquireSlot(): Promise<void> {
+    if (this._runningCount < this._maxConcurrent) {
+      this._runningCount++;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      this._waitQueue.push(() => {
+        this._runningCount++;
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Release a concurrency slot and notify the next waiter.
+   */
+  private _releaseSlot(): void {
+    this._runningCount--;
+    if (this._waitQueue.length > 0) {
+      const next = this._waitQueue.shift()!;
+      next();
+    }
+  }
+
+  /**
+   * Enqueue the task for execution under the concurrency limit.
+   */
+  private _enqueue(
+    taskId: string,
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    context: Context | null,
+  ): void {
+    const run = async (): Promise<void> => {
+      const internal = this._tasks.get(taskId);
+      if (!internal) return;
+
+      try {
+        await this._acquireSlot();
+
+        // Check if cancelled while waiting for a slot
+        if (internal.cancelled) {
+          return; // finally block handles releaseSlot + resolve
+        }
+
+        internal.info.status = TaskStatus.RUNNING;
+        internal.info.startedAt = Date.now() / 1000;
+
+        const result = await this._executor.call(moduleId, inputs, context);
+
+        // Check if cancelled during execution
+        if (internal.cancelled) {
+          return; // finally block handles releaseSlot + resolve
+        }
+
+        internal.info.status = TaskStatus.COMPLETED;
+        internal.info.completedAt = Date.now() / 1000;
+        internal.info.result = result;
+      } catch (err) {
+        if (!internal.cancelled) {
+          internal.info.status = TaskStatus.FAILED;
+          internal.info.completedAt = Date.now() / 1000;
+          internal.info.error = err instanceof Error ? err.message : String(err);
+        }
+      } finally {
+        this._releaseSlot();
+        internal.resolve();
+      }
+    };
+
+    // Fire and forget -- errors are captured inside run()
+    run().catch((err) => {
+      console.warn('[apcore:async-task] Unexpected error in task runner:', err);
+    });
+  }
+}

package/src/bindings.ts

@@ -106,6 +106,12 @@ export class BindingLoader {
       );
     }
 
+    if (modulePath.startsWith('file:')) {
+      throw new BindingInvalidTargetError(
+        `Module path '${modulePath}' must not use file: URLs`,
+      );
+    }
+
     let mod: Record<string, unknown>;
     try {
       mod = await import(modulePath);

package/src/cancel.ts

@@ -0,0 +1,32 @@
+/**
+ * Cooperative cancellation support for apcore module execution.
+ */
+
+export class ExecutionCancelledError extends Error {
+  constructor(message: string = "Execution was cancelled") {
+    super(message);
+    this.name = "ExecutionCancelledError";
+  }
+}
+
+export class CancelToken {
+  private _cancelled: boolean = false;
+
+  get isCancelled(): boolean {
+    return this._cancelled;
+  }
+
+  cancel(): void {
+    this._cancelled = true;
+  }
+
+  check(): void {
+    if (this._cancelled) {
+      throw new ExecutionCancelledError();
+    }
+  }
+
+  reset(): void {
+    this._cancelled = false;
+  }
+}

package/src/context.ts

@@ -1,3 +1,8 @@
+
+import { v4 as uuidv4 } from 'uuid';
+import type { CancelToken } from './cancel.js';
+import type { TraceParent } from './trace-context.js';
+
 /**
  * Execution context, identity, and context creation.
  */
@@ -26,6 +31,7 @@ export class Context {
   readonly identity: Identity | null;
   redactedInputs: Record<string, unknown> | null;
   readonly data: Record<string, unknown>;
+  readonly cancelToken: CancelToken | null;
 
   constructor(
     traceId: string,
@@ -35,23 +41,40 @@ export class Context {
     identity: Identity | null = null,
     redactedInputs: Record<string, unknown> | null = null,
     data: Record<string, unknown> = {},
+    cancelToken: CancelToken | null = null,
   ) {
     this.traceId = traceId;
     this.callerId = callerId;
-    this.callChain = callChain;
+    this.callChain = Object.freeze([...callChain]);
     this.executor = executor;
     this.identity = identity;
     this.redactedInputs = redactedInputs;
     this.data = data;
+    this.cancelToken = cancelToken;
   }
 
+  /**
+   * Create a new top-level Context with a generated UUID v4 traceId.
+   *
+   * When `traceParent` is provided, its `traceId` (32 hex chars) is
+   * converted to UUID format (8-4-4-4-12) and used instead of generating
+   * a new one.
+   */
   static create(
     executor: unknown = null,
     identity: Identity | null = null,
     data?: Record<string, unknown>,
+    traceParent?: TraceParent | null,
   ): Context {
+    let traceId: string;
+    if (traceParent) {
+      const h = traceParent.traceId;
+      traceId = `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+    } else {
+      traceId = uuidv4();
+    }
     return new Context(
-      crypto.randomUUID(),
+      traceId,
       null,
       [],
       executor,
@@ -61,6 +84,57 @@ export class Context {
     );
   }
 
+  toJSON(): Record<string, unknown> {
+    const publicData: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(this.data)) {
+      if (!key.startsWith('_')) {
+        publicData[key] = value;
+      }
+    }
+    return {
+      traceId: this.traceId,
+      callerId: this.callerId,
+      callChain: [...this.callChain],
+      identity: this.identity ? {
+        id: this.identity.id,
+        type: this.identity.type,
+        roles: [...this.identity.roles],
+        attrs: { ...this.identity.attrs },
+      } : null,
+      redactedInputs: this.redactedInputs ? { ...this.redactedInputs } : null,
+      data: publicData,
+    };
+  }
+
+  static fromJSON(data: Record<string, unknown>, executor?: unknown): Context {
+    const identityData = data.identity as Record<string, unknown> | null;
+    const identity = identityData ? {
+      id: identityData.id as string,
+      type: (identityData.type as string) ?? 'user',
+      roles: Object.freeze([...(Array.isArray(identityData.roles) ? identityData.roles : [])]),
+      attrs: Object.freeze((identityData.attrs && typeof identityData.attrs === 'object' ? identityData.attrs : {}) as Record<string, unknown>),
+    } : null;
+    return new Context(
+      data.traceId as string,
+      (data.callerId as string) ?? null,
+      (data.callChain as string[]) ?? [],
+      executor ?? null,
+      identity,
+      (data.redactedInputs as Record<string, unknown>) ?? null,
+      data.data ? { ...(data.data as Record<string, unknown>) } : {},
+    );
+  }
+
+  get logger(): { debug: (...args: unknown[]) => void; info: (...args: unknown[]) => void; warn: (...args: unknown[]) => void; error: (...args: unknown[]) => void } {
+    const prefix = `[apcore:${this.callerId ?? 'unknown'}]`;
+    return {
+      debug: (...args: unknown[]) => console.debug(prefix, ...args),
+      info: (...args: unknown[]) => console.info(prefix, ...args),
+      warn: (...args: unknown[]) => console.warn(prefix, ...args),
+      error: (...args: unknown[]) => console.error(prefix, ...args),
+    };
+  }
+
   child(targetModuleId: string): Context {
     return new Context(
       this.traceId,
@@ -70,6 +144,17 @@ export class Context {
       this.identity,
       null,
       this.data, // shared reference
+      this.cancelToken,
     );
   }
 }
+
+/**
+ * Interface for creating Context from framework-specific requests.
+ *
+ * Web framework integrations should implement this to extract Identity
+ * from HTTP requests (e.g., Express request, JWT tokens, API keys).
+ */
+export interface ContextFactory {
+  createContext(request: unknown): Context;
+}

package/src/errors.ts

@@ -5,7 +5,7 @@
 export class ModuleError extends Error {
   readonly code: string;
   readonly details: Record<string, unknown>;
-  readonly cause?: Error;
+  override readonly cause?: Error;
   readonly traceId?: string;
   readonly timestamp: string;
 
@@ -16,7 +16,7 @@ export class ModuleError extends Error {
     cause?: Error,
     traceId?: string,
   ) {
-    super(message);
+    super(message, cause ? { cause } : undefined);
     this.name = 'ModuleError';
     this.code = code;
     this.details = details ?? {};
@@ -419,6 +419,11 @@ export const ErrorCodes = Object.freeze({
   BINDING_SCHEMA_MISSING: "BINDING_SCHEMA_MISSING",
   BINDING_FILE_INVALID: "BINDING_FILE_INVALID",
   CIRCULAR_DEPENDENCY: "CIRCULAR_DEPENDENCY",
+  MIDDLEWARE_CHAIN_ERROR: "MIDDLEWARE_CHAIN_ERROR",
+  // Forward declarations for Level 2 Phase 2 features.
+  // Exception classes will be added when the corresponding features are implemented.
+  GENERAL_NOT_IMPLEMENTED: "GENERAL_NOT_IMPLEMENTED",
+  DEPENDENCY_NOT_FOUND: "DEPENDENCY_NOT_FOUND",
 } as const);
 
 export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];