apcore-js 0.1.0

package/planning/core-executor/tasks/async-support.md

@@ -0,0 +1,106 @@
+# Task: Unified Async Execution Path
+
+## Goal
+
+Implement the unified async execution model for the TypeScript executor. Unlike the Python implementation which requires separate `call()` (sync) and `call_async()` methods with a complex sync/async bridge (daemon threads, new event loops, `asyncio.to_thread`), the TypeScript implementation uses a single async `call()` method that transparently handles both sync and async module `execute()` functions via `Promise.resolve()`.
+
+## Files Involved
+
+- `src/executor.ts` -- `call()` method, `_executeWithTimeout()` (~50 lines of async-specific logic)
+- `tests/test-executor.test.ts` -- Tests for async/sync module handling
+
+## Steps
+
+### 1. Verify Promise.resolve() handles both sync and async (TDD)
+
+Write tests demonstrating that `Promise.resolve(syncFn())` and `Promise.resolve(asyncFn())` both produce the same awaitable result:
+
+```typescript
+describe('unified async execution', () => {
+  it('handles sync execute function', async () => {
+    const syncModule = {
+      execute: (inputs: Record<string, unknown>) => ({ result: inputs['x'] }),
+      // ... schemas
+    };
+    const result = await executor.call('sync.mod', { x: 42 });
+    expect(result).toEqual({ result: 42 });
+  });
+
+  it('handles async execute function', async () => {
+    const asyncModule = {
+      execute: async (inputs: Record<string, unknown>) => {
+        await new Promise(r => setTimeout(r, 10));
+        return { result: inputs['x'] };
+      },
+      // ... schemas
+    };
+    const result = await executor.call('async.mod', { x: 42 });
+    expect(result).toEqual({ result: 42 });
+  });
+});
+```
+
+### 2. Verify timeout works for both execution modes (TDD)
+
+```typescript
+it('times out slow sync execution', async () => {
+  // Sync module that blocks (while-loop spin)
+  // Promise.race with setTimeout catches this
+});
+
+it('times out slow async execution', async () => {
+  // Async module with long await
+  // Promise.race with setTimeout catches this
+});
+```
+
+### 3. Document the architectural simplification
+
+The Python implementation requires ~260 lines for sync/async bridging:
+- `call_async()` -- async pipeline duplicate
+- `_execute_async()` -- async-aware execution dispatch
+- `_run_async_in_sync()` -- bridge for async modules in sync context
+- `_run_in_new_thread()` -- daemon thread with new event loop
+- `_execute_on_error_async()` -- async-aware error recovery
+- `_is_async_module()` -- cached async detection with thread lock
+
+The TypeScript version eliminates all of this with a single pattern:
+```typescript
+const result = await Promise.resolve(module.execute(inputs, ctx));
+```
+
+This works because:
+1. `Promise.resolve(value)` wraps sync values in a resolved Promise
+2. `Promise.resolve(promise)` returns the same Promise (identity for thenables)
+3. `await` unwraps both cases identically
+4. `Promise.race` provides timeout for both sync and async paths
+
+### 4. Verify middleware hooks work for both module types (TDD)
+
+Test that middleware `before()`, `after()`, and `onError()` execute correctly regardless of whether the module's `execute()` is sync or async.
+
+### 5. Run full test suite
+
+```bash
+npx vitest run tests/test-executor.test.ts
+```
+
+## Acceptance Criteria
+
+- [x] Single `call()` method handles both sync and async modules
+- [x] `Promise.resolve()` transparently wraps sync return values
+- [x] `Promise.race` provides timeout enforcement for both execution modes
+- [x] No async detection cache needed (no `_isAsyncModule()`, no thread lock)
+- [x] No separate `callAsync()` method needed
+- [x] No daemon threads, new event loops, or `to_thread()` bridges needed
+- [x] Middleware hooks work identically for sync and async modules
+- [x] Error propagation works for both sync throws and async rejections
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## Dependencies
+
+- Task: execution-pipeline (base `call()` implementation with `_executeWithTimeout()`)
+
+## Estimated Time
+
+4 hours

package/planning/core-executor/tasks/execution-pipeline.md

@@ -0,0 +1,113 @@
+# Task: 10-Step Async Execution Pipeline
+
+## Goal
+
+Implement the complete execution pipeline in the `Executor.call()` method, integrating all 10 steps: context creation, safety checks, module lookup, ACL enforcement, input validation with redaction, middleware before chain, module execution with timeout, output validation, middleware after chain, and result return. Unlike the Python implementation which has separate `call()` and `call_async()`, the TypeScript version uses a single async `call()` method.
+
+## Files Involved
+
+- `src/executor.ts` -- `Executor` class: `constructor()`, `call()`, `validate()`, `_executeWithTimeout()`, middleware registration methods (~300 lines)
+- `src/errors.ts` -- `ModuleNotFoundError`, `ACLDeniedError`, `SchemaValidationError`, `ModuleTimeoutError`, `InvalidInputError`
+- `tests/test-executor.test.ts` -- Full pipeline unit and integration tests
+
+## Steps
+
+### 1. Implement Executor constructor (TDD)
+
+- Accept options object: `{ registry, middlewares?, acl?, config? }`
+- Initialize `MiddlewareManager` and register provided middlewares
+- Read config values for `defaultTimeout` (30000ms), `globalTimeout` (60000ms), `maxCallDepth` (32), `maxModuleRepeat` (3)
+
+### 2. Implement middleware registration (TDD)
+
+- `use(middleware)` -- adds class-based middleware, returns `this` for chaining
+- `useBefore(callback)` -- wraps in `BeforeMiddleware` adapter
+- `useAfter(callback)` -- wraps in `AfterMiddleware` adapter
+- `remove(middleware)` -- delegates to `MiddlewareManager.remove()`
+
+### 3. Implement call() pipeline (TDD)
+
+- **Step 1**: Create or derive Context via `Context.create()` + `child()` or `context.child()`
+- **Step 2**: Run `_checkSafety(moduleId, ctx)`
+- **Step 3**: `registry.get(moduleId)`, throw `ModuleNotFoundError` if null
+- **Step 4**: `acl.check()` if ACL configured, throw `ACLDeniedError` if denied
+- **Step 5**: TypeBox `Value.Check()` for input validation, build `redactedInputs` via `redactSensitive()`
+- **Step 6**: `executeBefore()`, handle `MiddlewareChainError` with `onError` recovery
+- **Step 7**: `_executeWithTimeout()` via `Promise.race`
+- **Step 8**: TypeBox `Value.Check()` for output validation
+- **Step 9**: `executeAfter()` in reverse order
+- **Step 10**: Return output or propagate error with `onError` recovery
+
+### 4. Implement _executeWithTimeout (TDD)
+
+- Wrap module execution in `Promise.race` against a timeout promise
+- Timeout promise rejects with `ModuleTimeoutError` after `timeout_ms` milliseconds
+- Uses `setTimeout` for the timeout timer
+- Zero timeout: log warning, execute without timeout enforcement
+- Negative timeout: throw `InvalidInputError`
+- Both sync and async `execute()` return values handled via `Promise.resolve()`
+
+```typescript
+private async _executeWithTimeout(
+  module: unknown,
+  inputs: Record<string, unknown>,
+  ctx: Context,
+  timeoutMs: number,
+): Promise<Record<string, unknown>> {
+  if (timeoutMs < 0) throw new InvalidInputError('Timeout cannot be negative');
+
+  const executeFn = (module as any).execute.bind(module);
+  const resultPromise = Promise.resolve(executeFn(inputs, ctx));
+
+  if (timeoutMs === 0) {
+    // Warning: timeout disabled
+    return resultPromise;
+  }
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    setTimeout(() => reject(new ModuleTimeoutError(moduleId, timeoutMs)), timeoutMs);
+  });
+
+  return Promise.race([resultPromise, timeoutPromise]);
+}
+```
+
+### 5. Implement validate() (TDD)
+
+- Standalone pre-flight check without execution
+- Returns `{ valid: boolean, errors: Array<{ path, message }> }`
+- Throws `ModuleNotFoundError` if module not found
+- Uses TypeBox `Value.Check()` and `Value.Errors()` for validation
+
+### 6. Verify full pipeline tests pass
+
+```bash
+npx vitest run tests/test-executor.test.ts
+```
+
+## Acceptance Criteria
+
+- [x] All 10 steps execute in order for the success path
+- [x] Each step can independently throw its specific error type
+- [x] MiddlewareChainError triggers onError recovery before re-throwing
+- [x] Outer exception handler catches errors from steps 6-9 and runs onError on executed middlewares
+- [x] Recovery output from onError short-circuits the error and returns the recovery dict
+- [x] Timeout enforcement uses `Promise.race` with `setTimeout`
+- [x] Timeout of 0 disables enforcement with a logged warning
+- [x] Negative timeout throws `InvalidInputError`
+- [x] `validate()` returns structured errors without executing the module
+- [x] Both sync and async module `execute()` methods handled via `Promise.resolve()`
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## Dependencies
+
+- Task: setup (Context, Config)
+- Task: safety-checks (`_checkSafety` method)
+- Task: redaction (`redactSensitive` utility)
+- Registry system (module lookup)
+- Middleware system (MiddlewareManager)
+- Schema system (TypeBox validation)
+
+## Estimated Time
+
+6 hours

package/planning/core-executor/tasks/redaction.md

@@ -0,0 +1,85 @@
+# Task: Sensitive Field Redaction Utility
+
+## Goal
+
+Implement the `redactSensitive` utility that walks input/output dictionaries and replaces values of fields marked `x-sensitive: true` in the schema with `***REDACTED***`. This ensures sensitive data never appears in logs or error reports.
+
+## Files Involved
+
+- `src/executor.ts` -- `redactSensitive()`, `_redactFields()`, `_redactSecretPrefix()`, `REDACTED_VALUE` constant
+- `tests/test-redaction.test.ts` -- Redaction unit tests
+
+## Steps
+
+### 1. Define REDACTED_VALUE constant (TDD)
+
+```typescript
+export const REDACTED_VALUE = '***REDACTED***';
+```
+
+Test: verify constant value is `"***REDACTED***"`.
+
+### 2. Implement redactSensitive (TDD)
+
+- Accept `data: Record<string, unknown>` and `schemaDict: Record<string, unknown>`
+- Deep copy via `JSON.parse(JSON.stringify(data))` to avoid mutating original
+- Call `_redactFields()` for schema-based redaction
+- Call `_redactSecretPrefix()` for key-prefix-based redaction
+- Return the redacted copy
+
+```typescript
+export function redactSensitive(
+  data: Record<string, unknown>,
+  schemaDict: Record<string, unknown>,
+): Record<string, unknown> {
+  const copy = JSON.parse(JSON.stringify(data));
+  _redactFields(copy, schemaDict);
+  _redactSecretPrefix(copy);
+  return copy;
+}
+```
+
+Test: deep copy (original not mutated), no mutation of original data.
+
+### 3. Implement _redactFields (TDD)
+
+- In-place redaction on the deep copy
+- Read `properties` from `schemaDict`; return early if missing
+- For each property: if `x-sensitive: true`, replace value with `REDACTED_VALUE` (skip `null`/`undefined`)
+- For nested objects (`type: 'object'` with `properties`): recurse into the value dict
+- For arrays (`type: 'array'` with `items`): if items have `x-sensitive`, redact each item; if items are objects with properties, recurse into each dict item
+
+Test: flat fields, nested objects, arrays with `x-sensitive` items.
+
+### 4. Implement _redactSecretPrefix (TDD)
+
+- In-place redaction of any key starting with `_secret_`
+- Replace non-null values with `REDACTED_VALUE`
+
+Test: keys starting with `_secret_` redacted, non-matching keys preserved.
+
+### 5. Verify tests pass
+
+```bash
+npx vitest run tests/test-redaction.test.ts
+```
+
+## Acceptance Criteria
+
+- [x] Original data dict is never mutated (`JSON.parse(JSON.stringify())` deep copy)
+- [x] Fields with `x-sensitive: true` in schema are replaced with `***REDACTED***`
+- [x] `null`/`undefined` values are not redacted (remain as-is)
+- [x] Nested object fields are recursively redacted
+- [x] Array items with `x-sensitive` are individually redacted
+- [x] Array items that are objects with properties are recursively redacted
+- [x] Keys starting with `_secret_` are redacted regardless of schema
+- [x] Non-sensitive fields pass through unchanged
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## Dependencies
+
+- None (standalone utility, used by execution-pipeline task at step 5)
+
+## Estimated Time
+
+2 hours

package/planning/core-executor/tasks/safety-checks.md

@@ -0,0 +1,65 @@
+# Task: Safety Checks -- Call Depth, Circular Detection, Frequency Throttling
+
+## Goal
+
+Implement the three safety mechanisms evaluated at step 2 of the execution pipeline: call depth limiting, circular call detection, and per-module frequency throttling. These prevent unbounded recursion, circular invocation chains, and tight-loop abuse.
+
+## Files Involved
+
+- `src/executor.ts` -- `_checkSafety()` method
+- `src/errors.ts` -- `CallDepthExceededError`, `CircularCallError`, `CallFrequencyExceededError`
+- `tests/test-executor.test.ts` -- Safety check unit tests
+
+## Steps
+
+### 1. Implement error types (TDD)
+
+Write tests for each error's code, message, and details, then implement:
+
+- `CallDepthExceededError(depth, maxDepth, callChain)` with code `CALL_DEPTH_EXCEEDED`
+- `CircularCallError(moduleId, callChain)` with code `CIRCULAR_CALL`
+- `CallFrequencyExceededError(moduleId, count, maxRepeat, callChain)` with code `CALL_FREQUENCY_EXCEEDED`
+
+All extend `ModuleError` with `timestamp`, `code`, `message`, `details` record, and optional `cause`.
+
+### 2. Implement call depth check (TDD)
+
+- Compare `callChain.length` against `_maxCallDepth` (default 32)
+- Throw `CallDepthExceededError` when exceeded
+- Test: depth at limit (pass), below limit (pass), above limit (throw)
+
+### 3. Implement circular call detection (TDD)
+
+- Examine `callChain.slice(0, -1)` (prior chain, since `child()` already appended moduleId)
+- If `moduleId` is found in prior chain, extract subsequence between last occurrence and end
+- Only throw `CircularCallError` if subsequence length > 0 (true cycle of length >= 2)
+- Test: A->B->A cycle (throw), A->B->C->B cycle (throw), non-cycle repetition (pass)
+
+### 4. Implement frequency throttling (TDD)
+
+- Count occurrences of `moduleId` in `callChain` using `filter().length`
+- Throw `CallFrequencyExceededError` when count exceeds `_maxModuleRepeat` (default 3)
+- Test: count at limit (pass), below limit (pass), above limit (throw)
+
+### 5. Verify tests pass
+
+```bash
+npx vitest run tests/test-executor.test.ts
+```
+
+## Acceptance Criteria
+
+- [x] Call depth check rejects chains exceeding maxCallDepth
+- [x] Circular detection identifies A->B->A patterns but allows simple repetition (A->A)
+- [x] Frequency throttle fires when a module appears more than maxModuleRepeat times in the chain
+- [x] All errors carry full callChain in details for debugging
+- [x] Configurable limits via Config (`executor.max_call_depth`, `executor.max_module_repeat`)
+- [x] All error types extend ModuleError with timestamp and structured details
+
+## Dependencies
+
+- Task: setup (Context with callChain, Config with dot-path access)
+
+## Estimated Time
+
+2 hours

package/planning/core-executor/tasks/setup.md

@@ -0,0 +1,75 @@
+# Task: Context, Identity, and Config Classes
+
+## Goal
+
+Implement the foundational data structures for the execution pipeline: `Context` class for per-call metadata propagation, `Identity` interface with `createIdentity()` factory for caller representation, and `Config` accessor for dot-path configuration.
+
+## Files Involved
+
+- `src/context.ts` -- `Context` class and `Identity` interface with `createIdentity()`
+- `src/config.ts` -- `Config` class with dot-path key support
+- `tests/test-context.test.ts` -- Unit tests for Context and Identity
+- `tests/test-config.test.ts` -- Unit tests for Config
+
+## Steps
+
+### 1. Write failing tests (TDD)
+
+Create tests for:
+- **Identity**: `createIdentity({ id: 'user-1' })` creates frozen object with defaults (type="user", roles=[], attrs={})
+- **Identity immutability**: Frozen identity cannot be mutated at runtime
+- **Context.create()**: Creates root context with UUID traceId, empty callChain, shared data dict
+- **Context.child()**: Creates child context inheriting traceId, appending moduleId to callChain, sharing data by reference
+- **Config.get()**: Dot-path navigation (e.g., `config.get('executor.default_timeout')`)
+- **Config.get() with default**: Returns default when key not found
+
+### 2. Implement Identity interface and createIdentity()
+
+```typescript
+export interface Identity {
+  readonly id: string;
+  readonly type: string;
+  readonly roles: readonly string[];
+  readonly attrs: Readonly<Record<string, unknown>>;
+}
+
+export function createIdentity(options: { id: string; type?: string; roles?: string[]; attrs?: Record<string, unknown> }): Identity {
+  return Object.freeze({
+    id: options.id,
+    type: options.type ?? 'user',
+    roles: Object.freeze([...(options.roles ?? [])]),
+    attrs: Object.freeze({ ...(options.attrs ?? {}) }),
+  });
+}
+```
+
+### 3. Implement Context class
+
+- `create()` static factory: generates traceId via `crypto.randomUUID()`, initializes empty callChain and data
+- `child()` method: copies traceId, appends current moduleId to callChain, shares data reference
+
+### 4. Implement Config class
+
+- Constructor takes nested `Record<string, unknown>`
+- `get(key, defaultValue?)` splits on `.` and traverses nested records
+
+### 5. Verify tests pass
+
+Run `npx vitest run tests/test-context.test.ts tests/test-config.test.ts`.
+
+## Acceptance Criteria
+
+- [x] `createIdentity()` returns frozen Identity with correct defaults
+- [x] `Context.create()` generates UUID v4 traceId
+- [x] `Context.child()` shares data dict by reference, appends to callChain
+- [x] `Config.get()` supports dot-path navigation
+- [x] `Config.get()` returns defaultValue when key not found
+- [x] All fields correctly typed with readonly where appropriate
+
+## Dependencies
+
+None -- these are foundational data structures.
+
+## Estimated Time
+
+2 hours

package/planning/decorator-bindings/overview.md

@@ -0,0 +1,62 @@
+# Feature: Decorator Bindings
+
+## Overview
+
+The Decorator Bindings module provides the primary API for defining apcore modules from TypeScript functions. Unlike the Python implementation which uses `@module` decorators with runtime type introspection, the TypeScript version uses a `module()` factory function that accepts an options object with explicit TypeBox schemas. The `FunctionModule` class wraps any async or sync function with `inputSchema`/`outputSchema`, description, and metadata. The `normalizeResult()` utility (exported, unlike Python where it is private) standardizes return values. The `BindingLoader` class enables YAML-driven zero-code-modification module registration, resolving targets to callables via async `import()` and building schemas from JSON Schema definitions or external schema reference files.
+
+Note: TypeScript cannot introspect types at runtime (type erasure at compile time), so there is no `auto_schema` mode and no type inference from function signatures. All schemas must be provided explicitly as TypeBox `TSchema` objects or via JSON Schema in YAML binding files.
+
+## Scope
+
+### Included
+
+- `FunctionModule` class wrapping an execute function with explicit `inputSchema`/`outputSchema` (TypeBox `TSchema`), `description`, `documentation`, `tags`, `version`, `annotations`, `metadata`, `examples`
+- `normalizeResult()` exported utility: `null`/`undefined` -> `{}`, `Record` -> passthrough, other -> `{ result: value }`
+- `makeAutoId(name)` for ID generation from arbitrary strings (simpler than Python's `__module__`+`__qualname__`)
+- `module()` factory function accepting an options object with explicit schemas and optional `registry` for auto-registration
+- `BindingLoader` class with async `loadBindings(filePath, registry)` for YAML-driven module registration
+- `loadBindingDir(dirPath, registry, pattern)` for directory scanning of binding YAML files
+- Schema resolution modes in bindings: inline `input_schema`/`output_schema`, `schema_ref` to external YAML, permissive fallback
+- `jsonSchemaToTypeBox()` integration for schema building from JSON Schema in binding files
+- Dead `JSON_SCHEMA_TYPE_MAP` code in `bindings.ts` (noted as cleanup needed)
+
+### Excluded
+
+- Runtime type inference / `auto_schema` mode (impossible in TypeScript due to type erasure)
+- Python-style `@module` decorator syntax (TypeScript uses factory function pattern)
+- Schema system internals (consumed via `jsonSchemaToTypeBox()` from `schema-system`)
+- Registry implementation (consumed as a dependency for module registration)
+- Executor pipeline integration (FunctionModule is consumed by `core-executor`)
+
+## Technology Stack
+
+- **TypeScript 5.5+** with strict mode
+- **@sinclair/typebox >= 0.34.0** for schema representation (`TSchema`, `Type.Object()`, `Type.Record()`, etc.)
+- **js-yaml** for YAML binding file parsing
+- **Node.js >= 18.0.0** with ES Module support (`node:fs`, `node:path`, dynamic `import()`)
+- **vitest** for unit testing
+
+## Task Execution Order
+
+| # | Task File | Description | Status |
+|---|-----------|-------------|--------|
+| 1 | [function-module](./tasks/function-module.md) | FunctionModule class with execute, schemas, description, normalizeResult() | completed |
+| 2 | [module-factory](./tasks/module-factory.md) | module() factory function with options object pattern | completed |
+| 3 | [explicit-schemas](./tasks/explicit-schemas.md) | Explicit TypeBox schema passing (vs Python's auto-generation) | completed |
+| 4 | [binding-loader](./tasks/binding-loader.md) | BindingLoader with async loadBindings() from YAML | completed |
+| 5 | [binding-directory](./tasks/binding-directory.md) | loadBindingDir() for directory scanning of binding YAML files | completed |
+| 6 | [schema-modes](./tasks/schema-modes.md) | Schema resolution modes: input_schema, output_schema, schema_ref, permissive fallback | completed |
+
+## Progress
+
+| Total | Completed | In Progress | Pending |
+|-------|-----------|-------------|---------|
+| 6     | 6         | 0           | 0       |
+
+## Reference Documents
+
+- `src/decorator.ts` -- FunctionModule class, module() factory, normalizeResult(), makeAutoId() (~110 lines)
+- `src/bindings.ts` -- BindingLoader class with YAML loading and target resolution (~208 lines)
+- `src/errors.ts` -- Binding error hierarchy (BindingInvalidTargetError, BindingFileInvalidError, etc.)
+- `tests/test-decorator.test.ts` -- Unit tests for FunctionModule, module(), normalizeResult(), makeAutoId()
+- `tests/test-bindings.test.ts` -- Unit tests for BindingLoader

package/planning/decorator-bindings/plan.md

@@ -0,0 +1,104 @@
+# Implementation Plan: Decorator Bindings
+
+## Goal
+
+Implement the TypeScript module definition and YAML binding system for apcore, providing a `FunctionModule` class that wraps execute functions with explicit TypeBox schemas, a `module()` factory for ergonomic module creation, and a `BindingLoader` for zero-code-modification module registration from YAML configuration files. Unlike the Python implementation, TypeScript cannot introspect types at runtime, so all schemas must be explicitly provided.
+
+## Architecture Design
+
+### Component Structure
+
+- **FunctionModule** (`decorator.ts`, ~60 lines) -- Core wrapper class that associates an execute function with `inputSchema`/`outputSchema` (TypeBox `TSchema`), `description`, `documentation`, `tags`, `version`, `annotations`, `metadata`, and `examples`. The `execute()` method calls the wrapped function and passes the result through `normalizeResult()`. All optional fields default to sensible values (description defaults to `"Module {moduleId}"`, version to `"1.0.0"`, others to `null`).
+
+- **normalizeResult()** (`decorator.ts`, ~4 lines) -- Exported utility that standardizes module return values: `null`/`undefined` becomes `{}`, plain `Record` objects pass through unchanged, and all other values (strings, numbers, booleans, arrays) are wrapped in `{ result: value }`. Exported (unlike Python where it is private) for use by `BindingLoader` and testing.
+
+- **makeAutoId()** (`decorator.ts`, ~7 lines) -- ID generation utility that lowercases a name string, replaces non-alphanumeric/non-dot/non-underscore characters with underscores, and prefixes digit-leading segments. Simpler than Python's `__module__`+`__qualname__` approach since TypeScript functions lack equivalent introspectable qualified names.
+
+- **module()** (`decorator.ts`, ~25 lines) -- Factory function that creates a `FunctionModule` from an options object. This is NOT a decorator (unlike Python's `@module`); it is a plain function call that returns a `FunctionModule`. Accepts optional `registry` for auto-registration. Generates an auto ID via `makeAutoId('anonymous')` when `id` is not provided.
+
+- **BindingLoader** (`bindings.ts`, ~175 lines) -- YAML binding file loader that reads binding configuration, resolves `target` strings to callable functions via dynamic `import()`, builds schemas from JSON Schema definitions, and registers `FunctionModule` instances with a `Registry`. Supports target resolution for both exported functions (`module:funcName`) and class methods (`module:ClassName.methodName`). Schema resolution has three modes: inline `input_schema`/`output_schema`, external `schema_ref`, and permissive fallback.
+
+- **Error Hierarchy** (`errors.ts`) -- Six binding-specific error classes extending `ModuleError`: `BindingInvalidTargetError`, `BindingModuleNotFoundError`, `BindingCallableNotFoundError`, `BindingNotCallableError`, `BindingSchemaMissingError`, `BindingFileInvalidError`.
+
+### Data Flow
+
+Module creation via `module()` factory:
+
+1. Caller provides options object with `execute`, `inputSchema`, `outputSchema`, and optional metadata
+2. `module()` resolves `moduleId` from `id` option or generates one via `makeAutoId('anonymous')`
+3. `module()` constructs a `FunctionModule` with all provided options
+4. If `registry` is provided, the module is registered via `registry.register()`
+5. `FunctionModule.execute()` calls the wrapped function and passes the result through `normalizeResult()`
+
+Module creation via YAML binding:
+
+1. `BindingLoader.loadBindings()` reads and parses a YAML file containing a `bindings` array
+2. For each binding entry, `resolveTarget()` dynamically imports the target module and resolves the callable
+3. Schema is resolved via one of three modes: inline JSON Schema, external `schema_ref` file, or permissive fallback
+4. A `FunctionModule` is constructed wrapping the resolved callable with the resolved schemas
+5. The module is registered with the provided `Registry`
+
+### Technical Choices and Rationale
+
+- **Factory function instead of decorator**: TypeScript decorators (TC39 Stage 3) operate on class methods/fields, not standalone functions. A factory function is more natural for wrapping plain functions and aligns with TypeScript's functional composition patterns.
+
+- **Explicit schemas required**: TypeScript types are erased at compile time. Unlike Python where `inspect.signature()` and type annotations can be read at runtime, TypeScript provides no runtime type metadata. Therefore, all schemas must be provided as TypeBox `TSchema` objects at the call site. This is the fundamental architectural difference from the Python implementation.
+
+- **`normalizeResult()` exported**: Made public (unlike Python's private method) because `BindingLoader._createModuleFromBinding()` duplicates the normalization logic inline. The export enables both `FunctionModule.execute()` and future binding code to share the same normalization behavior. The duplication in `_createModuleFromBinding` is a known minor issue.
+
+- **Async binding loading with sync file I/O**: `loadBindings()` and `loadBindingDir()` are `async` methods because target resolution uses dynamic `import()`, which is inherently asynchronous. However, YAML file reading uses `readFileSync` for simplicity since binding loading is a startup-time operation.
+
+- **`JSON_SCHEMA_TYPE_MAP` dead code**: The `bindings.ts` file contains a `JSON_SCHEMA_TYPE_MAP` constant and `buildSchemaFromJsonSchema()` wrapper that delegates to `jsonSchemaToTypeBox()` from the schema system. The map is unused dead code from an earlier iteration and should be cleaned up.
+
+## Task Breakdown
+
+```mermaid
+graph TD
+    T1[function-module] --> T2[module-factory]
+    T1 --> T3[explicit-schemas]
+    T3 --> T4[binding-loader]
+    T4 --> T5[binding-directory]
+    T4 --> T6[schema-modes]
+```
+
+| Task ID | Title | Estimated Time | Dependencies |
+|---------|-------|---------------|--------------|
+| function-module | FunctionModule class with execute, schemas, normalizeResult() | 2h | none |
+| module-factory | module() factory function with options object pattern | 2h | function-module |
+| explicit-schemas | Explicit TypeBox schema passing | 1h | function-module |
+| binding-loader | BindingLoader with async loadBindings() from YAML | 4h | explicit-schemas |
+| binding-directory | loadBindingDir() for directory scanning | 2h | binding-loader |
+| schema-modes | Schema resolution modes: inline, schema_ref, permissive | 3h | binding-loader |
+
+## Risks and Considerations
+
+- **`normalizeResult()` duplication**: The `_createModuleFromBinding()` method in `BindingLoader` duplicates the normalization logic inline rather than calling the exported `normalizeResult()`. This creates a maintenance risk if the normalization rules change. Should be refactored to use the shared utility.
+- **Dead code**: `JSON_SCHEMA_TYPE_MAP` in `bindings.ts` is unreferenced dead code. It was superseded by `jsonSchemaToTypeBox()` from the schema system and should be removed in a cleanup pass.
+- **Sync file I/O in async methods**: `readFileSync` is used inside async `loadBindings()`. This blocks the event loop during file reads. Acceptable for startup-time binding loading but would be problematic if called during request handling.
+- **Target resolution security**: Dynamic `import()` in `resolveTarget()` can import arbitrary modules. There is no allowlist or sandboxing of target module paths. This is by design for flexibility but should be documented.
+- **No schema validation of binding YAML structure**: The binding YAML structure (required keys like `module_id`, `target`) is validated via imperative checks rather than a formal schema. A YAML schema for binding files could improve error messages.
+
+## Acceptance Criteria
+
+- [x] `FunctionModule` wraps execute functions with explicit `inputSchema`/`outputSchema`
+- [x] `FunctionModule.execute()` calls the wrapped function and normalizes the result
+- [x] `normalizeResult()` handles null/undefined -> `{}`, Record -> passthrough, other -> `{ result: value }`
+- [x] `makeAutoId()` generates valid module IDs from arbitrary strings
+- [x] `module()` factory creates `FunctionModule` with all options forwarded
+- [x] `module()` auto-registers with registry when `registry` option is provided
+- [x] `module()` generates anonymous ID when `id` is not provided
+- [x] `BindingLoader.loadBindings()` reads YAML and creates registered modules
+- [x] `BindingLoader.resolveTarget()` resolves `module:funcName` and `module:Class.method` targets
+- [x] `loadBindingDir()` scans directories for `*.binding.yaml` files
+- [x] Schema resolution supports inline, schema_ref, and permissive fallback modes
+- [x] All binding error types are thrown with correct error classes
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## References
+
+- `src/decorator.ts` -- FunctionModule, module(), normalizeResult(), makeAutoId()
+- `src/bindings.ts` -- BindingLoader class
+- `src/errors.ts` -- Binding error hierarchy
+- `src/schema/loader.ts` -- jsonSchemaToTypeBox() used by binding schema resolution
+- `tests/test-decorator.test.ts` -- FunctionModule and module() tests
+- `tests/test-bindings.test.ts` -- BindingLoader tests