apcore-js 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,7 +5,34 @@ 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.4.0] - 2026-02-22
+## [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.
@@ -13,6 +40,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 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`.

package/package.json

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

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/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,5 +1,7 @@
 
 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.
@@ -29,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,
@@ -38,6 +41,7 @@ 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;
@@ -46,15 +50,31 @@ export class Context {
     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(
-      uuidv4(),
+      traceId,
       null,
       [],
       executor,
@@ -64,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,
@@ -73,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

@@ -420,6 +420,10 @@ export const ErrorCodes = Object.freeze({
   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];

package/src/executor.ts

@@ -10,6 +10,7 @@ import { Value } from '@sinclair/typebox/value';
 import type { ACL } from './acl.js';
 import type { Config } from './config.js';
 import { Context } from './context.js';
+import { ExecutionCancelledError } from './cancel.js';
 import {
   ACLDeniedError,
   CallDepthExceededError,
@@ -132,6 +133,11 @@ export class Executor {
     return this._middlewareManager.snapshot();
   }
 
+  /** Set the access control provider. */
+  setAcl(acl: ACL): void {
+    this._acl = acl;
+  }
+
   use(middleware: Middleware): Executor {
     this._middlewareManager.add(middleware);
     return this;
@@ -236,6 +242,11 @@ export class Executor {
         throw e;
       }
 
+      // Cancel check before execution
+      if (ctx.cancelToken !== null) {
+        ctx.cancelToken.check();
+      }
+
       const streamFn = mod['stream'] as
         | ((inputs: Record<string, unknown>, context: Context) => AsyncGenerator<Record<string, unknown>>)
         | undefined;
@@ -261,6 +272,7 @@ export class Executor {
         yield output;
       }
     } catch (exc) {
+      if (exc instanceof ExecutionCancelledError) throw exc;
       if (executedMiddlewares.length > 0) {
         const recovery = this._middlewareManager.executeOnError(
           moduleId, effectiveInputs, exc as Error, ctx, executedMiddlewares,
@@ -357,6 +369,11 @@ export class Executor {
         throw e;
       }
 
+      // Cancel check before execution
+      if (ctx.cancelToken !== null) {
+        ctx.cancelToken.check();
+      }
+
       let output = await this._executeWithTimeout(mod, moduleId, effectiveInputs, ctx);
 
       this._validateOutput(mod, output);
@@ -364,6 +381,7 @@ export class Executor {
       output = this._middlewareManager.executeAfter(moduleId, effectiveInputs, output, ctx);
       return output;
     } catch (exc) {
+      if (exc instanceof ExecutionCancelledError) throw exc;
       if (executedMiddlewares.length > 0) {
         const recovery = this._middlewareManager.executeOnError(
           moduleId, effectiveInputs, exc as Error, ctx, executedMiddlewares,