feat: Bump to v0.12.0 — add Module.preflight()/describe(), ExecutionCancelledError extends ModuleError

- Add optional preflight() and describe() methods to Module interface (spec §5.6)
- Add ModuleDescription interface and export from package index
- ExecutionCancelledError now extends ModuleError with code EXECUTION_CANCELLED (was bare Error)
- Add EXECUTION_CANCELLED to ErrorCodes constants
- Remove phantom batchProcessing CHANGELOG entry (never implemented)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: tercel

CHANGELOG.md

@@ -5,6 +5,22 @@ 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.12.0] - 2026-03-10
+
+### Added
+- **`Module.preflight()`** — Optional method for domain-specific pre-execution warnings (spec §5.6)
+- **`Module.describe()`** — Optional method returning `ModuleDescription` for LLM/AI tool discovery (spec §5.6)
+- **`ModuleDescription`** interface — Typed return type for `Module.describe()`, exported from package index
+
+### Changed
+- **`ExecutionCancelledError`** now extends `ModuleError` (was bare `Error`) with error code `EXECUTION_CANCELLED`, aligning with PROTOCOL_SPEC §8.7 error hierarchy
+- **`ErrorCodes`** — Added `EXECUTION_CANCELLED` constant
+
+### Fixed
+- **Removed phantom CHANGELOG entry** — `ModuleAnnotations.batchProcessing` (v0.4.0) was never implemented
+
+---
+
 ## [0.11.0] - 2026-03-08
 
 ### Added
@@ -235,7 +251,6 @@ Built-in `system.*` modules that allow AI agents to query, monitor
 - 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

package.json

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

src/cancel.ts

@@ -2,9 +2,11 @@
  * Cooperative cancellation support for apcore module execution.
  */
 
-export class ExecutionCancelledError extends Error {
+import { ModuleError } from './errors.js';
+
+export class ExecutionCancelledError extends ModuleError {
   constructor(message: string = "Execution was cancelled") {
-    super(message);
+    super("EXECUTION_CANCELLED", message);
     this.name = "ExecutionCancelledError";
   }
 }

src/errors.ts

@@ -131,7 +131,7 @@ export class ACLDeniedError extends ModuleError {
       options?.cause,
       options?.traceId,
       options?.retryable,
-      options?.aiGuidance,
+      options?.aiGuidance ?? `Access denied for '${callerId}' calling '${targetId}'. Verify the caller has the required role or permission, or try an alternative module with similar functionality.`,
       options?.userFixable,
       options?.suggestion,
     );
@@ -158,7 +158,7 @@ export class ModuleNotFoundError extends ModuleError {
       options?.cause,
       options?.traceId,
       options?.retryable,
-      options?.aiGuidance,
+      options?.aiGuidance ?? `Module '${moduleId}' does not exist in the registry. Verify the module ID spelling. Use system.manifest.full to list available modules.`,
       options?.userFixable,
       options?.suggestion,
     );
@@ -177,7 +177,7 @@ export class ModuleDisabledError extends ModuleError {
       options?.cause,
       options?.traceId,
       options?.retryable,
-      options?.aiGuidance,
+      options?.aiGuidance ?? `Module '${moduleId}' is currently disabled. Use system.control.toggle_feature to re-enable it, or find an alternative module.`,
       options?.userFixable,
       options?.suggestion,
     );
@@ -196,7 +196,7 @@ export class ModuleTimeoutError extends ModuleError {
       options?.cause,
       options?.traceId,
       options?.retryable,
-      options?.aiGuidance,
+      options?.aiGuidance ?? `Module '${moduleId}' timed out after ${timeoutMs}ms. Consider: 1) Breaking the operation into smaller steps. 2) Reducing the input data size. 3) Asking the user if a longer timeout is acceptable.`,
       options?.userFixable,
       options?.suggestion,
     );
@@ -227,7 +227,7 @@ export class SchemaValidationError extends ModuleError {
       options?.cause,
       options?.traceId,
       options?.retryable,
-      options?.aiGuidance,
+      options?.aiGuidance ?? 'Input validation failed. Review the error details to identify which fields have invalid values, then correct them or ask the user for valid input.',
       options?.userFixable,
       options?.suggestion,
     );
@@ -293,7 +293,7 @@ export class CallDepthExceededError extends ModuleError {
       options?.cause,
       options?.traceId,
       options?.retryable,
-      options?.aiGuidance,
+      options?.aiGuidance ?? `Call depth ${depth} exceeds maximum ${maxDepth}. Simplify the module call chain or restructure to reduce nesting depth.`,
       options?.userFixable,
       options?.suggestion,
     );
@@ -320,7 +320,7 @@ export class CircularCallError extends ModuleError {
       options?.cause,
       options?.traceId,
       options?.retryable,
-      options?.aiGuidance,
+      options?.aiGuidance ?? 'A circular call was detected in the module call chain. Review the call_chain in error details and restructure to eliminate the cycle.',
       options?.userFixable,
       options?.suggestion,
     );
@@ -736,6 +736,7 @@ export const ErrorCodes = Object.freeze({
   MODULE_TIMEOUT: "MODULE_TIMEOUT",
   MODULE_LOAD_ERROR: "MODULE_LOAD_ERROR",
   RELOAD_FAILED: "RELOAD_FAILED",
+  EXECUTION_CANCELLED: "EXECUTION_CANCELLED",
   MODULE_EXECUTE_ERROR: "MODULE_EXECUTE_ERROR",
   SCHEMA_VALIDATION_ERROR: "SCHEMA_VALIDATION_ERROR",
   SCHEMA_NOT_FOUND: "SCHEMA_NOT_FOUND",

src/executor.ts

@@ -35,8 +35,8 @@ import type { Registry } from './registry/registry.js';
 export const REDACTED_VALUE: string = '***REDACTED***';
 
 /** Well-known context.data keys used internally by the framework. */
-export const CTX_GLOBAL_DEADLINE = '_global_deadline';
-export const CTX_TRACING_SPANS = '_tracing_spans';
+export const CTX_GLOBAL_DEADLINE = '_apcore.executor.global_deadline';
+export const CTX_TRACING_SPANS = '_apcore.mw.tracing.spans';
 
 export function redactSensitive(
   data: Record<string, unknown>,
@@ -553,6 +553,26 @@ export class Executor {
       checks.push({ check: 'schema', passed: true });
     }
 
+    // Check 7: module-level preflight (optional)
+    if (typeof (mod as any).preflight === 'function') {
+      try {
+        const preflightWarnings = (mod as any).preflight(effectiveInputs, ctx);
+        if (Array.isArray(preflightWarnings) && preflightWarnings.length > 0) {
+          checks.push({ check: 'module_preflight', passed: true, warnings: preflightWarnings });
+        } else {
+          checks.push({ check: 'module_preflight', passed: true });
+        }
+      } catch (exc: unknown) {
+        const excName = exc instanceof Error ? exc.constructor.name : 'Error';
+        const excMsg = exc instanceof Error ? exc.message : String(exc);
+        checks.push({
+          check: 'module_preflight',
+          passed: true,
+          warnings: [`preflight() raised ${excName}: ${excMsg}`],
+        });
+      }
+    }
+
     return createPreflightResult(checks, requiresApproval);
   }
 

src/index.ts

@@ -16,7 +16,7 @@ export { Executor, redactSensitive, REDACTED_VALUE, CTX_GLOBAL_DEADLINE, CTX_TRA
 
 // Module types
 export { DEFAULT_ANNOTATIONS, createPreflightResult } from './module.js';
-export type { ModuleAnnotations, ModuleExample, ValidationResult, PreflightCheckResult, PreflightResult, Module } from './module.js';
+export type { ModuleAnnotations, ModuleExample, ModuleDescription, ValidationResult, PreflightCheckResult, PreflightResult, Module } from './module.js';
 
 // Config
 export { Config } from './config.js';
@@ -160,4 +160,4 @@ export type { UsageRecord, CallerUsageSummary, HourlyBucket, ModuleUsageSummary,
 export { TraceContext } from './trace-context.js';
 export type { TraceParent } from './trace-context.js';
 
-export const VERSION = '0.11.0';
+export const VERSION = '0.12.0';

src/middleware/logging.ts

@@ -43,7 +43,7 @@ export class LoggingMiddleware extends Middleware {
     inputs: Record<string, unknown>,
     context: Context,
   ): null {
-    context.data['_logging_mw_start'] = performance.now();
+    context.data['_apcore.mw.logging.start_time'] = performance.now();
 
     if (this._logInputs) {
       const redacted = context.redactedInputs ?? inputs;
@@ -64,7 +64,7 @@ export class LoggingMiddleware extends Middleware {
     output: Record<string, unknown>,
     context: Context,
   ): null {
-    const startTime = (context.data['_logging_mw_start'] as number) ?? performance.now();
+    const startTime = (context.data['_apcore.mw.logging.start_time'] as number) ?? performance.now();
     const durationMs = performance.now() - startTime;
 
     if (this._logOutputs) {

src/middleware/retry.ts

@@ -7,8 +7,8 @@ import type { ModuleError } from '../errors.js';
 import { Middleware } from './base.js';
 
 /** Well-known context.data key prefixes for retry state. */
-export const CTX_RETRY_COUNT_PREFIX = '_retry_count_';
-export const CTX_RETRY_DELAY_PREFIX = '_retry_delay_ms_';
+export const CTX_RETRY_COUNT_PREFIX = '_apcore.mw.retry.count.';
+export const CTX_RETRY_DELAY_PREFIX = '_apcore.mw.retry.delay_ms.';
 
 export interface RetryConfig {
   maxRetries: number;

src/module.ts

@@ -39,6 +39,7 @@ export interface PreflightCheckResult {
   readonly check: string;
   readonly passed: boolean;
   readonly error?: Record<string, unknown>;
+  readonly warnings?: string[];
 }
 
 export interface PreflightResult {
@@ -68,8 +69,20 @@ export interface Module {
   stream?(inputs: Record<string, unknown>, context: Context): AsyncGenerator<Record<string, unknown>>;
   /** Optional: Custom input validation without execution. */
   validate?(inputs: Record<string, unknown>): ValidationResult | Promise<ValidationResult>;
+  /** Optional: Domain-specific pre-execution warnings (called by Executor.validate() Check 7). Advisory only — warnings do NOT block execution. */
+  preflight?(inputs: Record<string, unknown>, context: Context): string[] | Promise<string[]>;
+  /** Optional: Return module description for LLM/AI tool discovery. */
+  describe?(): ModuleDescription | Promise<ModuleDescription>;
   /** Optional: Called when module is loaded into the registry. */
   onLoad?(): void | Promise<void>;
   /** Optional: Called when module is unloaded from the registry. */
   onUnload?(): void | Promise<void>;
 }
+
+export interface ModuleDescription {
+  readonly description: string;
+  readonly inputSchema: Record<string, unknown>;
+  readonly outputSchema: Record<string, unknown>;
+  readonly annotations: ModuleAnnotations;
+  readonly examples: ModuleExample[];
+}

src/observability/context-logger.ts

@@ -145,9 +145,9 @@ export class ObsLoggingMiddleware extends Middleware {
     inputs: Record<string, unknown>,
     context: Context,
   ): null {
-    const starts = (context.data['_obs_logging_starts'] as number[]) ?? [];
+    const starts = (context.data['_apcore.mw.logging.obs_starts'] as number[]) ?? [];
     starts.push(performance.now());
-    context.data['_obs_logging_starts'] = starts;
+    context.data['_apcore.mw.logging.obs_starts'] = starts;
 
     const extra: Record<string, unknown> = {
       module_id: moduleId,
@@ -166,7 +166,7 @@ export class ObsLoggingMiddleware extends Middleware {
     output: Record<string, unknown>,
     context: Context,
   ): null {
-    const starts = context.data['_obs_logging_starts'] as number[] | undefined;
+    const starts = context.data['_apcore.mw.logging.obs_starts'] as number[] | undefined;
     if (!starts || starts.length === 0) return null;
     const startTime = starts.pop()!;
     const durationMs = performance.now() - startTime;
@@ -188,7 +188,7 @@ export class ObsLoggingMiddleware extends Middleware {
     error: Error,
     context: Context,
   ): null {
-    const starts = context.data['_obs_logging_starts'] as number[] | undefined;
+    const starts = context.data['_apcore.mw.logging.obs_starts'] as number[] | undefined;
     if (!starts || starts.length === 0) return null;
     const startTime = starts.pop()!;
     const durationMs = performance.now() - startTime;