refactor: Migrate context logging to a dedicated ContextLogger and update related core and test files.

Author: tercel

CHANGELOG.md

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

README.md

@@ -2,6 +2,7 @@
 import { v4 as uuidv4 } from 'uuid';
 import type { CancelToken } from './cancel.js';
 import type { TraceParent } from './trace-context.js';
+import { ContextLogger } from './observability/context-logger.js';
 
 /**
  * Execution context, identity, and context creation.
@@ -131,14 +132,8 @@ export class Context<T = null> {
     );
   }
 
-  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),
-    };
+  get logger(): ContextLogger {
+    return ContextLogger.fromContext(this, this.callerId ?? 'unknown');
   }
 
   child(targetModuleId: string): Context<T> {

package.json

@@ -19,15 +19,17 @@ import {
   ApprovalPendingError,
   ApprovalTimeoutError,
   InvalidInputError,
+  ModuleError,
   ModuleNotFoundError,
   ModuleTimeoutError,
   SchemaValidationError,
 } from './errors.js';
 import { AfterMiddleware, BeforeMiddleware, Middleware } from './middleware/index.js';
 import { MiddlewareChainError, MiddlewareManager } from './middleware/manager.js';
 import { guardCallChain } from './utils/call-chain.js';
-import type { ModuleAnnotations, ValidationResult } from './module.js';
-import { DEFAULT_ANNOTATIONS } from './module.js';
+import type { ModuleAnnotations, PreflightCheckResult, PreflightResult } from './module.js';
+import { DEFAULT_ANNOTATIONS, createPreflightResult } from './module.js';
+import { MODULE_ID_PATTERN } from './registry/registry.js';
 import type { Registry } from './registry/registry.js';
 
 export const REDACTED_VALUE: string = '***REDACTED***';
@@ -178,7 +180,7 @@ export class Executor {
     this._acl = acl;
   }
 
-  /** Set the approval handler for Step 4.5 gate. */
+  /** Set the approval handler for Step 5 gate. */
   setApprovalHandler(handler: ApprovalHandler): void {
     this._approvalHandler = handler;
   }
@@ -336,7 +338,7 @@ export class Executor {
     const mod = this._lookupModule(moduleId);
     this._checkAcl(moduleId, ctx);
 
-    // Step 4.5 -- Approval Gate (strips internal keys like _approval_token)
+    // Step 5 -- Approval Gate (strips internal keys like _approval_token)
     effectiveInputs = await this._checkApproval(mod, moduleId, effectiveInputs, ctx);
 
     effectiveInputs = this._validateInputs(mod, effectiveInputs, ctx);
@@ -457,32 +459,98 @@ export class Executor {
     }
   }
 
-  validate(moduleId: string, inputs: Record<string, unknown>): ValidationResult {
+  /**
+   * Non-destructive preflight check through Steps 1-6 of the pipeline.
+   * Returns a PreflightResult that is duck-type compatible with ValidationResult.
+   */
+  validate(
+    moduleId: string,
+    inputs?: Record<string, unknown> | null,
+    context?: Context | null,
+  ): PreflightResult {
+    const effectiveInputs = inputs ?? {};
+    const checks: PreflightCheckResult[] = [];
+    let requiresApproval = false;
+
+    // Check 1: module_id format
+    if (!MODULE_ID_PATTERN.test(moduleId)) {
+      checks.push({
+        check: 'module_id', passed: false,
+        error: { code: 'INVALID_INPUT', message: `Invalid module ID: "${moduleId}"` },
+      });
+      return createPreflightResult(checks);
+    }
+    checks.push({ check: 'module_id', passed: true });
+
+    // Check 2: module lookup
     const module = this._registry.get(moduleId);
     if (module === null) {
-      throw new ModuleNotFoundError(moduleId);
+      checks.push({
+        check: 'module_lookup', passed: false,
+        error: { code: 'MODULE_NOT_FOUND', message: `Module not found: ${moduleId}` },
+      });
+      return createPreflightResult(checks);
     }
-
+    checks.push({ check: 'module_lookup', passed: true });
     const mod = module as Record<string, unknown>;
-    const inputSchema = mod['inputSchema'] as TSchema | undefined;
 
-    if (inputSchema == null) {
-      return { valid: true, errors: [] };
+    // Check 3: call chain safety
+    const ctx = this._createContext(moduleId, context);
+    try {
+      this._checkSafety(moduleId, ctx);
+      checks.push({ check: 'call_chain', passed: true });
+    } catch (e) {
+      const err = e instanceof ModuleError
+        ? { code: e.code, message: e.message }
+        : { code: 'CALL_CHAIN_ERROR', message: String(e) };
+      checks.push({ check: 'call_chain', passed: false, error: err });
     }
 
-    if (Value.Check(inputSchema, inputs)) {
-      return { valid: true, errors: [] };
+    // Check 4: ACL
+    if (this._acl !== null) {
+      const allowed = this._acl.check(ctx.callerId, moduleId, ctx);
+      if (!allowed) {
+        checks.push({
+          check: 'acl', passed: false,
+          error: { code: 'ACL_DENIED', message: `Access denied: ${ctx.callerId} -> ${moduleId}` },
+        });
+      } else {
+        checks.push({ check: 'acl', passed: true });
+      }
+    } else {
+      checks.push({ check: 'acl', passed: true });
     }
 
-    const errors: Array<Record<string, string>> = [];
-    for (const error of Value.Errors(inputSchema, inputs)) {
-      errors.push({
-        field: error.path || '/',
-        code: String(error.type),
-        message: error.message,
-      });
+    // Check 5: approval detection (report only, no handler invocation)
+    if (this._needsApproval(mod)) {
+      requiresApproval = true;
     }
-    return { valid: false, errors };
+    checks.push({ check: 'approval', passed: true });
+
+    // Check 6: input schema validation
+    const inputSchema = mod['inputSchema'] as TSchema | undefined;
+    if (inputSchema != null) {
+      if (Value.Check(inputSchema, effectiveInputs)) {
+        checks.push({ check: 'schema', passed: true });
+      } else {
+        const errors: Array<Record<string, unknown>> = [];
+        for (const error of Value.Errors(inputSchema, effectiveInputs)) {
+          errors.push({
+            field: error.path || '/',
+            code: String(error.type),
+            message: error.message,
+          });
+        }
+        checks.push({
+          check: 'schema', passed: false,
+          error: { code: 'SCHEMA_VALIDATION_ERROR', errors },
+        });
+      }
+    } else {
+      checks.push({ check: 'schema', passed: true });
+    }
+
+    return createPreflightResult(checks, requiresApproval);
   }
 
   private _checkSafety(moduleId: string, ctx: Context): void {
@@ -568,7 +636,7 @@ export class Executor {
     }
   }
 
-  /** Step 4.5: Approval gate. Returns inputs with internal keys stripped. */
+  /** Step 5: Approval gate. Returns inputs with internal keys stripped. */
   private async _checkApproval(
     mod: Record<string, unknown>,
     moduleId: string,

src/context.ts

@@ -11,8 +11,8 @@ export type { Discoverer, ModuleValidator } from './registry/registry.js';
 export { Executor, redactSensitive, REDACTED_VALUE, CTX_GLOBAL_DEADLINE, CTX_TRACING_SPANS } from './executor.js';
 
 // Module types
-export { DEFAULT_ANNOTATIONS } from './module.js';
-export type { ModuleAnnotations, ModuleExample, ValidationResult, Module } from './module.js';
+export { DEFAULT_ANNOTATIONS, createPreflightResult } from './module.js';
+export type { ModuleAnnotations, ModuleExample, ValidationResult, PreflightCheckResult, PreflightResult, Module } from './module.js';
 
 // Config
 export { Config } from './config.js';
@@ -120,4 +120,4 @@ export { ContextLogger, ObsLoggingMiddleware } from './observability/context-log
 export { TraceContext } from './trace-context.js';
 export type { TraceParent } from './trace-context.js';
 
-export const VERSION = '0.8.0';
+export const VERSION = '0.9.0';

src/executor.ts

@@ -35,6 +35,30 @@ export interface ValidationResult {
   errors: Array<Record<string, string>>;
 }
 
+export interface PreflightCheckResult {
+  readonly check: string;
+  readonly passed: boolean;
+  readonly error?: Record<string, unknown>;
+}
+
+export interface PreflightResult {
+  readonly valid: boolean;
+  readonly checks: PreflightCheckResult[];
+  readonly requiresApproval: boolean;
+  readonly errors: Array<Record<string, unknown>>;
+}
+
+export function createPreflightResult(
+  checks: PreflightCheckResult[],
+  requiresApproval: boolean = false,
+): PreflightResult {
+  const valid = checks.every(c => c.passed);
+  const errors = checks
+    .filter(c => !c.passed && c.error != null)
+    .map(c => c.error!);
+  return { valid, checks, requiresApproval, errors };
+}
+
 export interface Module {
   inputSchema: TSchema;
   outputSchema: TSchema;

src/index.ts

@@ -47,7 +47,7 @@ export class ContextLogger {
     this._output = options?.output ?? { write: (s: string) => console.error(s) };
   }
 
-  static fromContext(context: Context, name: string, options?: {
+  static fromContext(context: Context<unknown>, name: string, options?: {
     format?: string;
     level?: string;
     redactSensitive?: boolean;