apcore-js 0.1.0

package/planning/decorator-bindings/tasks/schema-modes.md

@@ -0,0 +1,142 @@
+# Task: Schema Resolution Modes: Inline, schema_ref, Permissive Fallback
+
+## Goal
+
+Implement the three schema resolution modes used by `BindingLoader._createModuleFromBinding()` when constructing `FunctionModule` instances from YAML binding entries. Each binding entry can specify schemas in one of three ways: inline `input_schema`/`output_schema` JSON Schema objects, an external `schema_ref` file path, or no schema at all (permissive fallback). This task also covers the `jsonSchemaToTypeBox()` integration and notes the dead `JSON_SCHEMA_TYPE_MAP` code that should be cleaned up.
+
+## Files Involved
+
+- `src/bindings.ts` -- `_createModuleFromBinding()` schema resolution logic, `buildSchemaFromJsonSchema()` wrapper, dead `JSON_SCHEMA_TYPE_MAP`
+- `src/schema/loader.ts` -- `jsonSchemaToTypeBox()` consumed for JSON Schema to TypeBox conversion
+- `tests/test-bindings.test.ts` -- Tests for each schema resolution mode
+
+## Steps
+
+### 1. Write failing tests (TDD)
+
+Create tests for:
+- **Inline input_schema/output_schema**: Binding with inline JSON Schema objects produces FunctionModule with correct TypeBox schemas
+- **Only input_schema present**: Missing `output_schema` defaults to empty object schema `{}`
+- **Only output_schema present**: Missing `input_schema` defaults to empty object schema `{}`
+- **schema_ref mode**: Binding with `schema_ref: ./schemas/my-module.yaml` loads schemas from the referenced file
+- **schema_ref file not found**: Throws `BindingFileInvalidError` when referenced file does not exist
+- **schema_ref invalid YAML**: Throws `BindingFileInvalidError` on malformed YAML in referenced file
+- **Permissive fallback**: Binding with no schema keys produces permissive `Type.Record(Type.String(), Type.Unknown())` for both input and output
+- **Schema priority**: `input_schema`/`output_schema` takes precedence over `schema_ref` when both present
+
+### 2. Implement schema resolution in _createModuleFromBinding()
+
+```typescript
+private async _createModuleFromBinding(
+  binding: Record<string, unknown>,
+  bindingFileDir: string,
+): Promise<FunctionModule> {
+  const func = await this.resolveTarget(binding['target'] as string);
+  const moduleId = binding['module_id'] as string;
+
+  let inputSchema: TSchema;
+  let outputSchema: TSchema;
+
+  if ('input_schema' in binding || 'output_schema' in binding) {
+    // Mode 1: Inline JSON Schema
+    const inputSchemaDict = (binding['input_schema'] as Record<string, unknown>) ?? {};
+    const outputSchemaDict = (binding['output_schema'] as Record<string, unknown>) ?? {};
+    inputSchema = buildSchemaFromJsonSchema(inputSchemaDict);
+    outputSchema = buildSchemaFromJsonSchema(outputSchemaDict);
+  } else if ('schema_ref' in binding) {
+    // Mode 2: External schema reference file
+    const refPath = resolve(bindingFileDir, binding['schema_ref'] as string);
+    if (!existsSync(refPath)) {
+      throw new BindingFileInvalidError(refPath, 'Schema reference file not found');
+    }
+    let refData: Record<string, unknown>;
+    try {
+      refData = (yaml.load(readFileSync(refPath, 'utf-8')) as Record<string, unknown>) ?? {};
+    } catch (e) {
+      throw new BindingFileInvalidError(refPath, `YAML parse error: ${e}`);
+    }
+    inputSchema = buildSchemaFromJsonSchema(
+      (refData['input_schema'] as Record<string, unknown>) ?? {},
+    );
+    outputSchema = buildSchemaFromJsonSchema(
+      (refData['output_schema'] as Record<string, unknown>) ?? {},
+    );
+  } else {
+    // Mode 3: Permissive fallback -- no schema specified
+    inputSchema = Type.Record(Type.String(), Type.Unknown());
+    outputSchema = Type.Record(Type.String(), Type.Unknown());
+  }
+
+  return new FunctionModule({
+    execute: async (inputs, context) => {
+      const result = await func(inputs, context);
+      if (result === null || result === undefined) return {};
+      if (typeof result === 'object' && !Array.isArray(result))
+        return result as Record<string, unknown>;
+      return { result };
+    },
+    moduleId,
+    inputSchema,
+    outputSchema,
+    description: (binding['description'] as string) ?? undefined,
+    tags: (binding['tags'] as string[]) ?? null,
+    version: (binding['version'] as string) ?? '1.0.0',
+  });
+}
+```
+
+### 3. Note buildSchemaFromJsonSchema() wrapper and dead code
+
+The `buildSchemaFromJsonSchema()` function is a thin wrapper around `jsonSchemaToTypeBox()`:
+
+```typescript
+function buildSchemaFromJsonSchema(schema: Record<string, unknown>): TSchema {
+  return jsonSchemaToTypeBox(schema);
+}
+```
+
+The `JSON_SCHEMA_TYPE_MAP` constant defined at the top of `bindings.ts` is dead code. It was part of an earlier implementation before `jsonSchemaToTypeBox()` was extracted to the schema system. It maps JSON Schema type strings to TypeBox constructors but is never referenced. This should be removed in a cleanup pass.
+
+```typescript
+// DEAD CODE -- cleanup needed
+const JSON_SCHEMA_TYPE_MAP: Record<string, () => TSchema> = {
+  string: () => Type.String(),
+  integer: () => Type.Integer(),
+  number: () => Type.Number(),
+  boolean: () => Type.Boolean(),
+  array: () => Type.Array(Type.Unknown()),
+  object: () => Type.Record(Type.String(), Type.Unknown()),
+};
+```
+
+### 4. Document the three modes
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Inline | `input_schema` or `output_schema` key present | Parse inline JSON Schema objects via `jsonSchemaToTypeBox()`. Missing schema defaults to `{}` (empty object). |
+| schema_ref | `schema_ref` key present (no inline schemas) | Load external YAML file relative to binding file directory. Parse `input_schema` and `output_schema` from it. |
+| Permissive | No schema keys present | Use `Type.Record(Type.String(), Type.Unknown())` for both input and output. Accepts any key-value pairs. |
+
+### 5. Verify tests pass
+
+Run `npx vitest run tests/test-bindings.test.ts`.
+
+## Acceptance Criteria
+
+- [x] Inline mode: `input_schema`/`output_schema` JSON Schema objects are converted to TypeBox via `jsonSchemaToTypeBox()`
+- [x] Inline mode: Missing input or output schema defaults to empty `{}` (produces `Type.Object({})` equivalent)
+- [x] schema_ref mode: External YAML file is loaded relative to the binding file's directory
+- [x] schema_ref mode: `BindingFileInvalidError` thrown when reference file is missing or unparseable
+- [x] Permissive mode: No schema keys produces `Type.Record(Type.String(), Type.Unknown())` for both schemas
+- [x] Inline mode takes precedence over schema_ref when both are present
+- [x] `buildSchemaFromJsonSchema()` delegates to `jsonSchemaToTypeBox()` from schema system
+- [x] Dead `JSON_SCHEMA_TYPE_MAP` code is identified and documented for cleanup
+
+## Dependencies
+
+- `binding-loader` -- Requires `BindingLoader` class with `resolveTarget()` and `loadBindings()` structure
+- `schema-system` (external) -- Consumes `jsonSchemaToTypeBox()` for JSON Schema to TypeBox conversion
+
+## Estimated Time
+
+3 hours

package/planning/middleware-system/overview.md

@@ -0,0 +1,48 @@
+# Feature: Middleware System
+
+## Overview
+
+The Middleware System provides a composable onion-model pipeline for intercepting module calls in apcore. Each middleware can hook into three lifecycle phases -- `before()` (pre-execution input transformation), `after()` (post-execution output transformation), and `onError()` (error recovery). The `MiddlewareManager` orchestrates execution in forward order for `before`, reverse order for `after` and `onError`, and wraps middleware failures in `MiddlewareChainError`. Function adapter classes (`BeforeMiddleware`, `AfterMiddleware`) allow lightweight callback-based middleware without subclassing, and a built-in `LoggingMiddleware` provides structured call tracing with `performance.now()` timing.
+
+## Scope
+
+### Included
+
+- `Middleware` base class with no-op `before()`, `after()`, `onError()` lifecycle hooks
+- `MiddlewareManager` with `add()`, `remove()`, `snapshot()`, and onion-model `executeBefore()` / `executeAfter()` / `executeOnError()` methods
+- `MiddlewareChainError` extending `ModuleError` for wrapping middleware-phase failures with executed-middleware tracking
+- `BeforeMiddleware` and `AfterMiddleware` adapter classes with `BeforeCallback` and `AfterCallback` type aliases
+- `LoggingMiddleware` with pluggable `Logger` interface, configurable input/output/error logging, and `performance.now()` duration measurement
+- Barrel export via `middleware/index.ts`
+
+### Excluded
+
+- Executor integration (consumed by `core-executor` module)
+- Observability middleware (tracing, metrics -- implemented in `observability` module)
+- Async middleware support (all hooks are synchronous by design)
+
+## Technology Stack
+
+- **TypeScript 5.5+** with strict mode
+- **Node.js >= 18.0.0** with ES Module support
+- **vitest** for unit testing
+
+## Task Execution Order
+
+| # | Task File | Description | Status |
+|---|-----------|-------------|--------|
+| 1 | [base](./tasks/base.md) | Middleware base class with no-op lifecycle hooks | completed |
+| 2 | [manager](./tasks/manager.md) | MiddlewareManager with onion-model execution and MiddlewareChainError | completed |
+| 3 | [adapters](./tasks/adapters.md) | BeforeMiddleware and AfterMiddleware adapter classes with callback types | completed |
+| 4 | [logging-middleware](./tasks/logging-middleware.md) | LoggingMiddleware with Logger interface and performance.now() timing | completed |
+
+## Progress
+
+| Total | Completed | In Progress | Pending |
+|-------|-----------|-------------|---------|
+| 4     | 4         | 0           | 0       |
+
+## Reference Documents
+
+- [Implementation Plan](./plan.md)
+- [Project Overview](../overview.md)

package/planning/middleware-system/plan.md

@@ -0,0 +1,102 @@
+# Implementation Plan: Middleware System
+
+## Goal
+
+Implement a composable onion-model middleware pipeline that allows interception, transformation, and error recovery at each phase of a module call. The system provides a base class for subclassing, function adapters for lightweight usage, a manager for orchestration, and a built-in logging middleware with high-resolution timing.
+
+## Architecture Design
+
+### Component Structure
+
+- **Middleware** (`middleware/base.ts`, ~30 lines) -- Abstract base class with three no-op lifecycle hooks: `before(moduleId, inputs, context)`, `after(moduleId, inputs, output, context)`, and `onError(moduleId, inputs, error, context)`. Each returns `Record<string, unknown> | null`; returning `null` signals "no transformation". Imports `Context` from the core context module.
+
+- **MiddlewareManager** (`middleware/manager.ts`, ~100 lines) -- Onion-model execution engine. Maintains an internal `_middlewares` array with `add()`, `remove()` (by reference identity), and `snapshot()` (shallow copy). Exposes `executeBefore()` (forward order, returns `[transformedInputs, executedMiddlewares]` tuple), `executeAfter()` (reverse order), and `executeOnError()` (reverse over executed middlewares, first non-null recovery wins, errors in handlers are swallowed).
+
+- **MiddlewareChainError** (`middleware/manager.ts`) -- Error subclass extending `ModuleError` (not `Exception` as in Python). Captures the `original` error and the `executedMiddlewares` array at the point of failure, enabling the executor to run `onError()` recovery on the correct subset of middlewares.
+
+- **BeforeMiddleware / AfterMiddleware** (`middleware/adapters.ts`, ~55 lines) -- Adapter classes that wrap a single callback function (`BeforeCallback` or `AfterCallback` type alias) and delegate to the corresponding lifecycle hook. All other hooks remain no-op from the base class. Enables functional middleware patterns without subclassing.
+
+- **LoggingMiddleware** (`middleware/logging.ts`, ~100 lines) -- Concrete middleware that logs structured messages at each phase via a pluggable `Logger` interface (`info` and `error` methods). Uses `performance.now()` for high-resolution timing stored on `context.data['_logging_mw_start']`. Supports configurable flags: `logInputs`, `logOutputs`, `logErrors` (all default `true`). Uses `context.redactedInputs` when available to avoid logging sensitive data.
+
+- **Barrel Export** (`middleware/index.ts`) -- Re-exports all public classes, types, and interfaces.
+
+### Data Flow
+
+The middleware pipeline integrates into the executor's 10-step call sequence:
+
+```
+Inputs ──> [Before Phase: forward order] ──> Module Execution ──> [After Phase: reverse order] ──> Output
+                                                    │
+                                                    ▼ (on error)
+                                              [OnError Phase: reverse over executed middlewares]
+```
+
+1. **Before Phase** -- `executeBefore()` iterates middlewares in registration order. Each `before()` can return transformed inputs or `null` (pass-through). If any middleware throws, a `MiddlewareChainError` is raised carrying the list of already-executed middlewares.
+
+2. **After Phase** -- `executeAfter()` iterates middlewares in reverse registration order (onion unwinding). Each `after()` can return transformed output or `null` (pass-through).
+
+3. **OnError Phase** -- `executeOnError()` iterates the `executedMiddlewares` list in reverse. The first middleware returning a non-null value provides the recovery result. Errors thrown inside `onError()` handlers are swallowed to prevent cascading failures.
+
+### Technical Choices and Rationale
+
+- **No thread locking**: Node.js runs on a single-threaded event loop. The Python implementation uses `threading.Lock` for middleware list mutations; this is unnecessary in TypeScript. The `snapshot()` method provides a stable copy for iteration, which is sufficient to guard against mutations during execution.
+
+- **`MiddlewareChainError` extends `ModuleError`**: TypeScript uses `Error` (not `Exception` as in Python). `MiddlewareChainError` extends `ModuleError` to integrate with the framework's structured error hierarchy (code, details, timestamp). It carries `original: Error` and `executedMiddlewares: Middleware[]` for error recovery.
+
+- **`performance.now()` for timing**: Provides sub-millisecond resolution timing available in Node.js 18+ without additional dependencies. The start timestamp is stored on `context.data` (shared between parent/child contexts) rather than middleware instance state, ensuring correct timing in concurrent call scenarios.
+
+- **Synchronous lifecycle hooks**: All middleware hooks are synchronous. This is a deliberate design choice -- middleware should perform lightweight transformations and logging, not I/O. The executor wraps the entire pipeline in its async `call()` method.
+
+- **Identity-based `remove()`**: Middleware removal uses strict reference equality (`===`), matching the Python implementation's `is` comparison. This ensures that only the exact instance is removed, not a structurally equivalent one.
+
+## Task Breakdown
+
+```mermaid
+graph TD
+    T1[base] --> T2[manager]
+    T1 --> T3[adapters]
+    T1 --> T4[logging-middleware]
+    T2 --> T4
+```
+
+| Task ID | Title | Estimated Time | Dependencies |
+|---------|-------|---------------|--------------|
+| base | Middleware base class with no-op hooks | 1h | none |
+| manager | MiddlewareManager with onion-model execution | 3h | base |
+| adapters | BeforeMiddleware and AfterMiddleware adapters | 1.5h | base |
+| logging-middleware | LoggingMiddleware with Logger and timing | 2h | base, manager |
+
+## Risks and Considerations
+
+- **Middleware ordering sensitivity**: The onion model means registration order directly affects behavior. Middlewares registered first run their `before()` first but their `after()` last. Users must understand this ordering to compose middleware correctly.
+- **Error swallowing in `onError()`**: Errors thrown inside `onError()` handlers are silently swallowed. This prevents cascading failures but can hide bugs in error-recovery logic. Consider adding debug-level logging in the future.
+- **`context.data` key collisions**: `LoggingMiddleware` writes to `context.data['_logging_mw_start']`. Other middlewares writing to the same key would corrupt timing. The `_logging_mw_` prefix is a convention to reduce collision risk, but there is no namespace enforcement.
+- **No async middleware support**: If a use case requires async middleware (e.g., fetching external config before execution), the current synchronous design does not support it. This is an intentional trade-off for simplicity and performance.
+
+## Acceptance Criteria
+
+- [x] `Middleware` base class has `before()`, `after()`, `onError()` returning `null` by default
+- [x] `MiddlewareManager.add()` appends and `remove()` removes by reference identity
+- [x] `snapshot()` returns a shallow copy that does not affect the internal list
+- [x] `executeBefore()` runs middlewares in forward order and returns `[inputs, executedMiddlewares]`
+- [x] `executeAfter()` runs middlewares in reverse order
+- [x] `executeOnError()` runs in reverse over executed middlewares; first non-null wins; errors in handlers are swallowed
+- [x] `MiddlewareChainError` extends `ModuleError` with `original` and `executedMiddlewares` properties
+- [x] `BeforeMiddleware` delegates only `before()` to the callback; other hooks remain no-op
+- [x] `AfterMiddleware` delegates only `after()` to the callback; other hooks remain no-op
+- [x] `LoggingMiddleware` logs START/END/ERROR with trace ID, module ID, and timing
+- [x] `LoggingMiddleware` uses `performance.now()` for sub-millisecond duration measurement
+- [x] `LoggingMiddleware` respects `logInputs`, `logOutputs`, `logErrors` configuration flags
+- [x] `LoggingMiddleware` uses `context.redactedInputs` when available
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## References
+
+- `src/middleware/base.ts` -- Middleware base class
+- `src/middleware/manager.ts` -- MiddlewareManager and MiddlewareChainError
+- `src/middleware/adapters.ts` -- BeforeMiddleware, AfterMiddleware, and callback types
+- `src/middleware/logging.ts` -- LoggingMiddleware and Logger interface
+- `src/middleware/index.ts` -- Barrel export
+- `src/errors.ts` -- ModuleError base class
+- `tests/test-middleware.test.ts` -- Base class and adapter tests
+- `tests/test-middleware-manager.test.ts` -- Manager and MiddlewareChainError tests

package/planning/middleware-system/state.json

@@ -0,0 +1,65 @@
+{
+  "feature": "middleware-system",
+  "created": "2026-02-16T00:00:00Z",
+  "updated": "2026-02-16T00:00:00Z",
+  "status": "completed",
+  "execution_order": [
+    "base",
+    "manager",
+    "adapters",
+    "logging-middleware"
+  ],
+  "progress": {
+    "total_tasks": 4,
+    "completed": 4,
+    "in_progress": 0,
+    "pending": 0
+  },
+  "tasks": [
+    {
+      "id": "base",
+      "file": "tasks/base.md",
+      "title": "Middleware Base Class",
+      "status": "completed",
+      "started_at": "2026-02-16T08:00:00Z",
+      "completed_at": "2026-02-16T08:45:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "manager",
+      "file": "tasks/manager.md",
+      "title": "MiddlewareManager with Onion-Model Execution",
+      "status": "completed",
+      "started_at": "2026-02-16T08:45:00Z",
+      "completed_at": "2026-02-16T11:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "adapters",
+      "file": "tasks/adapters.md",
+      "title": "BeforeMiddleware and AfterMiddleware Adapters",
+      "status": "completed",
+      "started_at": "2026-02-16T11:00:00Z",
+      "completed_at": "2026-02-16T12:15:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "logging-middleware",
+      "file": "tasks/logging-middleware.md",
+      "title": "LoggingMiddleware with Logger Interface and Timing",
+      "status": "completed",
+      "started_at": "2026-02-16T12:15:00Z",
+      "completed_at": "2026-02-16T13:45:00Z",
+      "assignee": null,
+      "commits": []
+    }
+  ],
+  "metadata": {
+    "source_doc": "planning/overview.md",
+    "created_by": "code-forge",
+    "version": "1.0"
+  }
+}

package/planning/middleware-system/tasks/adapters.md

@@ -0,0 +1,170 @@
+# Task: BeforeMiddleware and AfterMiddleware Adapters
+
+## Goal
+
+Implement `BeforeMiddleware` and `AfterMiddleware` adapter classes that wrap callback functions into the middleware interface. These adapters enable lightweight, functional middleware creation without requiring users to subclass `Middleware`. Each adapter delegates a single lifecycle hook to the provided callback while inheriting no-op behavior for the other hooks from the base class. Also define `BeforeCallback` and `AfterCallback` type aliases for the callback signatures.
+
+## Files Involved
+
+| File | Action |
+|------|--------|
+| `src/middleware/adapters.ts` | Create -- BeforeMiddleware, AfterMiddleware, and callback types |
+| `tests/test-middleware.test.ts` | Extend -- Unit tests for adapter classes |
+
+## Steps (TDD)
+
+### Step 1: Define callback type aliases
+
+```typescript
+export type BeforeCallback = (
+  moduleId: string,
+  inputs: Record<string, unknown>,
+  context: Context,
+) => Record<string, unknown> | null;
+
+export type AfterCallback = (
+  moduleId: string,
+  inputs: Record<string, unknown>,
+  output: Record<string, unknown>,
+  context: Context,
+) => Record<string, unknown> | null;
+```
+
+### Step 2: Write failing tests for BeforeMiddleware
+
+```typescript
+describe('BeforeMiddleware', () => {
+  it('wraps a callback and delegates to before()', () => {
+    const mw = new BeforeMiddleware((moduleId, inputs) => {
+      return { ...inputs, injected: moduleId };
+    });
+    const ctx = makeContext();
+    const result = mw.before('mod.x', { a: 1 }, ctx);
+    expect(result).toEqual({ a: 1, injected: 'mod.x' });
+  });
+
+  it('after() still returns null', () => {
+    const mw = new BeforeMiddleware(() => ({ replaced: true }));
+    const ctx = makeContext();
+    expect(mw.after('mod.x', {}, {}, ctx)).toBeNull();
+  });
+
+  it('onError() still returns null', () => {
+    const mw = new BeforeMiddleware(() => ({ replaced: true }));
+    const ctx = makeContext();
+    expect(mw.onError('mod.x', {}, new Error('fail'), ctx)).toBeNull();
+  });
+
+  it('can return null from callback', () => {
+    const mw = new BeforeMiddleware(() => null);
+    const ctx = makeContext();
+    expect(mw.before('mod.x', { a: 1 }, ctx)).toBeNull();
+  });
+});
+```
+
+### Step 3: Implement BeforeMiddleware
+
+```typescript
+import type { Context } from '../context.js';
+import { Middleware } from './base.js';
+
+export class BeforeMiddleware extends Middleware {
+  private _callback: BeforeCallback;
+
+  constructor(callback: BeforeCallback) {
+    super();
+    this._callback = callback;
+  }
+
+  override before(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    context: Context,
+  ): Record<string, unknown> | null {
+    return this._callback(moduleId, inputs, context);
+  }
+}
+```
+
+### Step 4: Write failing tests for AfterMiddleware
+
+```typescript
+describe('AfterMiddleware', () => {
+  it('wraps a callback and delegates to after()', () => {
+    const mw = new AfterMiddleware((moduleId, _inputs, output) => {
+      return { ...output, processedBy: moduleId };
+    });
+    const ctx = makeContext();
+    const result = mw.after('mod.y', { a: 1 }, { out: 42 }, ctx);
+    expect(result).toEqual({ out: 42, processedBy: 'mod.y' });
+  });
+
+  it('before() still returns null', () => {
+    const mw = new AfterMiddleware(() => ({ replaced: true }));
+    const ctx = makeContext();
+    expect(mw.before('mod.y', {}, ctx)).toBeNull();
+  });
+
+  it('onError() still returns null', () => {
+    const mw = new AfterMiddleware(() => ({ replaced: true }));
+    const ctx = makeContext();
+    expect(mw.onError('mod.y', {}, new Error('fail'), ctx)).toBeNull();
+  });
+
+  it('can return null from callback', () => {
+    const mw = new AfterMiddleware(() => null);
+    const ctx = makeContext();
+    expect(mw.after('mod.y', {}, { out: 1 }, ctx)).toBeNull();
+  });
+});
+```
+
+### Step 5: Implement AfterMiddleware
+
+```typescript
+export class AfterMiddleware extends Middleware {
+  private _callback: AfterCallback;
+
+  constructor(callback: AfterCallback) {
+    super();
+    this._callback = callback;
+  }
+
+  override after(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    output: Record<string, unknown>,
+    context: Context,
+  ): Record<string, unknown> | null {
+    return this._callback(moduleId, inputs, output, context);
+  }
+}
+```
+
+### Step 6: Run tests and confirm all pass
+
+```bash
+npx vitest run tests/test-middleware.test.ts
+```
+
+## Acceptance Criteria
+
+- [x] `BeforeCallback` type alias is exported with signature `(moduleId, inputs, context) => Record<string, unknown> | null`
+- [x] `AfterCallback` type alias is exported with signature `(moduleId, inputs, output, context) => Record<string, unknown> | null`
+- [x] `BeforeMiddleware` extends `Middleware` and delegates only `before()` to the callback
+- [x] `BeforeMiddleware.after()` and `BeforeMiddleware.onError()` return `null` (inherited no-op)
+- [x] `AfterMiddleware` extends `Middleware` and delegates only `after()` to the callback
+- [x] `AfterMiddleware.before()` and `AfterMiddleware.onError()` return `null` (inherited no-op)
+- [x] Callbacks stored as `private _callback` fields
+- [x] Both adapters use `override` keyword on the delegated method
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `src/middleware/base.ts` -- `Middleware` base class (task: base)
+- `src/context.ts` -- `Context` class (type import)
+
+## Estimated Time
+
+1.5 hours

package/planning/middleware-system/tasks/base.md

@@ -0,0 +1,115 @@
+# Task: Middleware Base Class
+
+## Goal
+
+Implement the `Middleware` base class that defines the three lifecycle hooks for the middleware pipeline: `before()`, `after()`, and `onError()`. Each hook returns `Record<string, unknown> | null` -- returning `null` signals "no transformation" and the pipeline passes the original value through. The base class provides no-op defaults so subclasses only need to override the hooks they care about.
+
+## Files Involved
+
+| File | Action |
+|------|--------|
+| `src/middleware/base.ts` | Create -- Middleware base class |
+| `tests/test-middleware.test.ts` | Create -- Unit tests for base class hooks |
+
+## Steps (TDD)
+
+### Step 1: Write failing tests for `before()` default behavior
+
+Write a test that instantiates `Middleware` and calls `before()` with a module ID, inputs record, and context. Assert it returns `null`.
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { Middleware } from '../src/middleware/base.js';
+import { Context, createIdentity } from '../src/context.js';
+
+function makeContext(): Context {
+  return Context.create(null, createIdentity('test-user'));
+}
+
+describe('Middleware base class', () => {
+  it('before() returns null by default', () => {
+    const mw = new Middleware();
+    const ctx = makeContext();
+    expect(mw.before('mod.a', { x: 1 }, ctx)).toBeNull();
+  });
+});
+```
+
+### Step 2: Write failing tests for `after()` default behavior
+
+```typescript
+it('after() returns null by default', () => {
+  const mw = new Middleware();
+  const ctx = makeContext();
+  expect(mw.after('mod.a', { x: 1 }, { y: 2 }, ctx)).toBeNull();
+});
+```
+
+### Step 3: Write failing tests for `onError()` default behavior
+
+```typescript
+it('onError() returns null by default', () => {
+  const mw = new Middleware();
+  const ctx = makeContext();
+  expect(mw.onError('mod.a', { x: 1 }, new Error('boom'), ctx)).toBeNull();
+});
+```
+
+### Step 4: Implement the Middleware class
+
+```typescript
+import type { Context } from '../context.js';
+
+export class Middleware {
+  before(
+    _moduleId: string,
+    _inputs: Record<string, unknown>,
+    _context: Context,
+  ): Record<string, unknown> | null {
+    return null;
+  }
+
+  after(
+    _moduleId: string,
+    _inputs: Record<string, unknown>,
+    _output: Record<string, unknown>,
+    _context: Context,
+  ): Record<string, unknown> | null {
+    return null;
+  }
+
+  onError(
+    _moduleId: string,
+    _inputs: Record<string, unknown>,
+    _error: Error,
+    _context: Context,
+  ): Record<string, unknown> | null {
+    return null;
+  }
+}
+```
+
+### Step 5: Run tests and confirm all pass
+
+```bash
+npx vitest run tests/test-middleware.test.ts
+```
+
+## Acceptance Criteria
+
+- [x] `Middleware` class is exported from `src/middleware/base.ts`
+- [x] `before(moduleId, inputs, context)` returns `null` by default
+- [x] `after(moduleId, inputs, output, context)` returns `null` by default
+- [x] `onError(moduleId, inputs, error, context)` returns `null` by default
+- [x] All parameters use underscore-prefixed names to indicate intentional non-use
+- [x] Type signature uses `Record<string, unknown> | null` return type
+- [x] Imports `Context` as a type-only import
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `src/context.ts` -- `Context` class (used as parameter type)
+
+## Estimated Time
+
+1 hour