apcore-js 0.4.0 → 0.6.0

package/planning/decorator-bindings/state.json

@@ -1,87 +0,0 @@
-{
-  "feature": "decorator-bindings",
-  "created": "2026-02-16T00:00:00Z",
-  "updated": "2026-02-16T00:00:00Z",
-  "status": "completed",
-  "execution_order": [
-    "function-module",
-    "module-factory",
-    "explicit-schemas",
-    "binding-loader",
-    "binding-directory",
-    "schema-modes"
-  ],
-  "progress": {
-    "total_tasks": 6,
-    "completed": 6,
-    "in_progress": 0,
-    "pending": 0
-  },
-  "tasks": [
-    {
-      "id": "function-module",
-      "file": "tasks/function-module.md",
-      "title": "FunctionModule Class with Execute, Schemas, and normalizeResult()",
-      "status": "completed",
-      "started_at": "2026-02-16T08:00:00Z",
-      "completed_at": "2026-02-16T09:30:00Z",
-      "assignee": null,
-      "commits": []
-    },
-    {
-      "id": "module-factory",
-      "file": "tasks/module-factory.md",
-      "title": "module() Factory Function with Options Object Pattern",
-      "status": "completed",
-      "started_at": "2026-02-16T09:30:00Z",
-      "completed_at": "2026-02-16T11:00:00Z",
-      "assignee": null,
-      "commits": []
-    },
-    {
-      "id": "explicit-schemas",
-      "file": "tasks/explicit-schemas.md",
-      "title": "Explicit TypeBox Schema Passing",
-      "status": "completed",
-      "started_at": "2026-02-16T11:00:00Z",
-      "completed_at": "2026-02-16T11:45:00Z",
-      "assignee": null,
-      "commits": []
-    },
-    {
-      "id": "binding-loader",
-      "file": "tasks/binding-loader.md",
-      "title": "BindingLoader with Async loadBindings() from YAML",
-      "status": "completed",
-      "started_at": "2026-02-16T11:45:00Z",
-      "completed_at": "2026-02-16T14:30:00Z",
-      "assignee": null,
-      "commits": []
-    },
-    {
-      "id": "binding-directory",
-      "file": "tasks/binding-directory.md",
-      "title": "loadBindingDir() for Directory Scanning of Binding YAML Files",
-      "status": "completed",
-      "started_at": "2026-02-16T14:30:00Z",
-      "completed_at": "2026-02-16T16:00:00Z",
-      "assignee": null,
-      "commits": []
-    },
-    {
-      "id": "schema-modes",
-      "file": "tasks/schema-modes.md",
-      "title": "Schema Resolution Modes: Inline, schema_ref, Permissive Fallback",
-      "status": "completed",
-      "started_at": "2026-02-16T16:00:00Z",
-      "completed_at": "2026-02-16T18:30:00Z",
-      "assignee": null,
-      "commits": []
-    }
-  ],
-  "metadata": {
-    "source_doc": "planning/features/decorator-bindings.md",
-    "created_by": "code-forge",
-    "version": "1.0"
-  }
-}

package/planning/decorator-bindings/tasks/binding-directory.md

@@ -1,79 +0,0 @@
-# Task: loadBindingDir() for Directory Scanning of Binding YAML Files
-
-## Goal
-
-Implement the `loadBindingDir()` method on `BindingLoader` that scans a directory for binding YAML files matching a glob pattern (default `*.binding.yaml`), loads each one via `loadBindings()`, and returns all created `FunctionModule` instances. This enables convention-based module registration where all binding files in a directory are automatically discovered and loaded.
-
-## Files Involved
-
-- `src/bindings.ts` -- `BindingLoader.loadBindingDir()` method
-- `tests/test-bindings.test.ts` -- Unit tests for loadBindingDir()
-
-## Steps
-
-### 1. Write failing tests (TDD)
-
-Create tests for:
-- **loadBindingDir throws on nonexistent directory**: Throws `BindingFileInvalidError` with "Directory does not exist"
-- **loadBindingDir throws on file path (not directory)**: A path pointing to a file throws `BindingFileInvalidError`
-- **loadBindingDir returns empty array for empty directory**: Directory with no matching files returns `[]`
-- **loadBindingDir loads matching files in sorted order**: Files are processed alphabetically
-- **loadBindingDir respects custom pattern**: `pattern: '*.modules.yaml'` only matches files with that suffix
-
-### 2. Implement loadBindingDir()
-
-```typescript
-async loadBindingDir(
-  dirPath: string,
-  registry: Registry,
-  pattern: string = '*.binding.yaml',
-): Promise<FunctionModule[]> {
-  if (!existsSync(dirPath) || !statSync(dirPath).isDirectory()) {
-    throw new BindingFileInvalidError(dirPath, 'Directory does not exist');
-  }
-
-  const files = readdirSync(dirPath)
-    .filter((f) => {
-      // Simple glob matching: extract suffix after the wildcard
-      const suffix = pattern.replace('*', '');
-      return f.endsWith(suffix);
-    })
-    .sort();
-
-  const results: FunctionModule[] = [];
-  for (const f of files) {
-    const fms = await this.loadBindings(join(dirPath, f), registry);
-    results.push(...fms);
-  }
-  return results;
-}
-```
-
-Key design decisions:
-- **Simple glob matching**: Only supports `*` prefix patterns (e.g., `*.binding.yaml`). The wildcard is stripped and the remaining suffix is used for `endsWith()` matching. This covers the primary use case without introducing a glob library dependency.
-- **Sorted file order**: Files are sorted alphabetically to ensure deterministic loading order across platforms.
-- **Sequential loading**: Files are loaded sequentially (not in parallel) to maintain deterministic registration order in the registry. This is acceptable since binding loading is a startup-time operation.
-- **Sync directory listing**: Uses `readdirSync` and `statSync` for directory operations (same rationale as `loadBindings`'s use of `readFileSync`).
-
-### 3. Verify tests pass
-
-Run `npx vitest run tests/test-bindings.test.ts`.
-
-## Acceptance Criteria
-
-- [x] `loadBindingDir()` scans directory for files matching the pattern
-- [x] Default pattern is `'*.binding.yaml'`
-- [x] Custom patterns like `'*.modules.yaml'` are supported
-- [x] Files are processed in sorted (alphabetical) order
-- [x] Each matching file is loaded via `loadBindings()` and results are aggregated
-- [x] Throws `BindingFileInvalidError` when directory does not exist
-- [x] Throws `BindingFileInvalidError` when path is a file, not a directory
-- [x] Returns empty array when no files match the pattern
-
-## Dependencies
-
-- `binding-loader` -- Requires `BindingLoader` class with `loadBindings()` method
-
-## Estimated Time
-
-2 hours

package/planning/decorator-bindings/tasks/binding-loader.md

@@ -1,148 +0,0 @@
-# Task: BindingLoader with Async loadBindings() from YAML
-
-## Goal
-
-Implement the `BindingLoader` class that reads YAML binding configuration files, resolves target strings to callable functions via dynamic `import()`, wraps them in `FunctionModule` instances, and registers them with a `Registry`. This enables zero-code-modification module registration: existing functions can be exposed as apcore modules purely through YAML configuration.
-
-## Files Involved
-
-- `src/bindings.ts` -- `BindingLoader` class with `loadBindings()`, `resolveTarget()`, `_createModuleFromBinding()`
-- `src/errors.ts` -- `BindingFileInvalidError`, `BindingInvalidTargetError`, `BindingModuleNotFoundError`, `BindingCallableNotFoundError`, `BindingNotCallableError`
-- `tests/test-bindings.test.ts` -- Unit tests for BindingLoader
-
-## Steps
-
-### 1. Write failing tests (TDD)
-
-Create tests for:
-- **BindingLoader instantiation**: `new BindingLoader()` creates a valid instance
-- **resolveTarget throws on missing colon**: `resolveTarget('no_colon')` throws `BindingInvalidTargetError`
-- **loadBindings throws on nonexistent file**: Throws `BindingFileInvalidError` with file path
-- **loadBindings throws on invalid YAML**: Malformed YAML throws `BindingFileInvalidError`
-- **loadBindings throws on missing bindings key**: YAML without `bindings` key throws `BindingFileInvalidError`
-- **loadBindings throws on non-array bindings**: `bindings: "not_a_list"` throws `BindingFileInvalidError`
-- **loadBindings throws on missing module_id**: Binding entry without `module_id` throws `BindingFileInvalidError`
-- **loadBindings throws on missing target**: Binding entry without `target` throws `BindingFileInvalidError`
-
-### 2. Implement resolveTarget()
-
-```typescript
-async resolveTarget(targetString: string): Promise<(...args: unknown[]) => unknown> {
-  if (!targetString.includes(':')) {
-    throw new BindingInvalidTargetError(targetString);
-  }
-
-  const [modulePath, callableName] = targetString.split(':', 2);
-
-  let mod: Record<string, unknown>;
-  try {
-    mod = await import(modulePath);
-  } catch (e) {
-    throw new BindingModuleNotFoundError(modulePath);
-  }
-
-  // Handle Class.method syntax
-  if (callableName.includes('.')) {
-    const [className, methodName] = callableName.split('.', 2);
-    const cls = mod[className];
-    if (cls == null) throw new BindingCallableNotFoundError(className, modulePath);
-    let instance: Record<string, unknown>;
-    try {
-      instance = new (cls as new () => Record<string, unknown>)();
-    } catch {
-      throw new BindingCallableNotFoundError(callableName, modulePath);
-    }
-    const method = instance[methodName];
-    if (method == null) throw new BindingCallableNotFoundError(callableName, modulePath);
-    if (typeof method !== 'function') throw new BindingNotCallableError(targetString);
-    return method.bind(instance) as (...args: unknown[]) => unknown;
-  }
-
-  // Handle plain function export
-  const result = mod[callableName];
-  if (result == null) throw new BindingCallableNotFoundError(callableName, modulePath);
-  if (typeof result !== 'function') throw new BindingNotCallableError(targetString);
-  return result as (...args: unknown[]) => unknown;
-}
-```
-
-### 3. Implement loadBindings()
-
-```typescript
-async loadBindings(filePath: string, registry: Registry): Promise<FunctionModule[]> {
-  const bindingFileDir = dirname(filePath);
-
-  let content: string;
-  try {
-    content = readFileSync(filePath, 'utf-8');
-  } catch (e) {
-    throw new BindingFileInvalidError(filePath, String(e));
-  }
-
-  let data: unknown;
-  try {
-    data = yaml.load(content);
-  } catch (e) {
-    throw new BindingFileInvalidError(filePath, `YAML parse error: ${e}`);
-  }
-
-  // Validate structure
-  if (data === null || data === undefined) {
-    throw new BindingFileInvalidError(filePath, 'File is empty');
-  }
-  const dataObj = data as Record<string, unknown>;
-  if (!('bindings' in dataObj)) {
-    throw new BindingFileInvalidError(filePath, "Missing 'bindings' key");
-  }
-  const bindings = dataObj['bindings'];
-  if (!Array.isArray(bindings)) {
-    throw new BindingFileInvalidError(filePath, "'bindings' must be a list");
-  }
-
-  const results: FunctionModule[] = [];
-  for (const entry of bindings) {
-    const entryObj = entry as Record<string, unknown>;
-    if (!('module_id' in entryObj)) {
-      throw new BindingFileInvalidError(filePath, "Binding entry missing 'module_id'");
-    }
-    if (!('target' in entryObj)) {
-      throw new BindingFileInvalidError(filePath, "Binding entry missing 'target'");
-    }
-    const fm = await this._createModuleFromBinding(entryObj, bindingFileDir);
-    registry.register(entryObj['module_id'] as string, fm);
-    results.push(fm);
-  }
-
-  return results;
-}
-```
-
-### 4. Implement _createModuleFromBinding()
-
-Private method that resolves the target callable, builds schemas (delegated to schema-modes task), and constructs a `FunctionModule`.
-
-### 5. Verify tests pass
-
-Run `npx vitest run tests/test-bindings.test.ts`.
-
-## Acceptance Criteria
-
-- [x] `BindingLoader` class is instantiable with no constructor arguments
-- [x] `resolveTarget()` resolves `modulePath:funcName` to the exported function
-- [x] `resolveTarget()` resolves `modulePath:ClassName.methodName` to a bound method
-- [x] `resolveTarget()` throws `BindingInvalidTargetError` when target string has no colon
-- [x] `resolveTarget()` throws `BindingModuleNotFoundError` when module cannot be imported
-- [x] `resolveTarget()` throws `BindingCallableNotFoundError` when export is not found
-- [x] `resolveTarget()` throws `BindingNotCallableError` when export is not a function
-- [x] `loadBindings()` reads YAML, creates FunctionModules, and registers them
-- [x] `loadBindings()` throws `BindingFileInvalidError` for missing files, invalid YAML, missing keys
-- [x] Each binding entry requires `module_id` and `target` keys
-
-## Dependencies
-
-- `explicit-schemas` -- Requires understanding of explicit schema passing for FunctionModule construction
-- `schema-system` (external) -- Consumes `jsonSchemaToTypeBox()` for JSON Schema conversion
-
-## Estimated Time
-
-4 hours

package/planning/decorator-bindings/tasks/explicit-schemas.md

@@ -1,85 +0,0 @@
-# Task: Explicit TypeBox Schema Passing
-
-## Goal
-
-Establish and enforce the pattern of explicit TypeBox schema passing for all module definitions. In Python's apcore, `@module` can introspect function signatures and type annotations at runtime to auto-generate schemas. TypeScript erases types at compile time, making this impossible. This task documents and validates the explicit schema requirement: every `FunctionModule` and `module()` call must receive `inputSchema` and `outputSchema` as TypeBox `TSchema` objects.
-
-## Files Involved
-
-- `src/decorator.ts` -- `FunctionModule` constructor requiring `inputSchema`/`outputSchema` as `TSchema`
-- `tests/test-decorator.test.ts` -- Tests validating schema presence and TypeBox compatibility
-
-## Steps
-
-### 1. Write failing tests (TDD)
-
-Create tests for:
-- **FunctionModule requires inputSchema and outputSchema**: Constructing without schemas causes TypeScript compilation error (structural test via type assertions)
-- **Schemas are stored as readonly TSchema**: `fm.inputSchema` and `fm.outputSchema` are accessible and match the provided TypeBox schemas
-- **Complex schemas work**: Nested `Type.Object()` with optional fields, `Type.Array()`, `Type.Union()` all accepted as valid schemas
-- **Schema is not validated at construction**: FunctionModule stores schemas but does not validate inputs against them (validation is the executor's responsibility)
-
-### 2. Validate TypeBox schema integration
-
-```typescript
-import { Type, type TSchema } from '@sinclair/typebox';
-
-// Simple schemas
-const inputSchema = Type.Object({ name: Type.String() });
-const outputSchema = Type.Object({ greeting: Type.String() });
-
-// Complex schemas
-const complexInput = Type.Object({
-  query: Type.String(),
-  options: Type.Optional(Type.Object({
-    limit: Type.Number(),
-    offset: Type.Number(),
-  })),
-  tags: Type.Array(Type.String()),
-});
-
-const complexOutput = Type.Object({
-  results: Type.Array(Type.Object({
-    id: Type.String(),
-    score: Type.Number(),
-  })),
-  total: Type.Integer(),
-});
-
-// Both simple and complex schemas are accepted by FunctionModule
-const fm = new FunctionModule({
-  execute: (inputs) => ({ results: [], total: 0 }),
-  moduleId: 'search.query',
-  inputSchema: complexInput,
-  outputSchema: complexOutput,
-});
-```
-
-### 3. Document the no-auto-schema rationale
-
-The TypeScript implementation intentionally omits the Python `auto_schema` mode because:
-- TypeScript types are erased at compile time; `typeof` at runtime only yields `"object"`, `"string"`, etc.
-- There is no equivalent of Python's `inspect.signature()` or `typing.get_type_hints()` for TypeScript
-- TypeBox provides a runtime-accessible schema representation that doubles as both a TypeScript type (via `Static<T>`) and a JSON Schema
-- Explicit schemas are self-documenting and enable IDE autocompletion via `Static<typeof inputSchema>`
-
-### 4. Verify tests pass
-
-Run `npx vitest run tests/test-decorator.test.ts` and confirm schema-related tests pass.
-
-## Acceptance Criteria
-
-- [x] `FunctionModule` constructor requires `inputSchema: TSchema` and `outputSchema: TSchema`
-- [x] TypeBox schemas of any complexity are accepted (`Type.Object`, `Type.Array`, `Type.Union`, `Type.Optional`, etc.)
-- [x] `fm.inputSchema` and `fm.outputSchema` are accessible as `readonly TSchema`
-- [x] No auto-schema mode exists (verified by absence of introspection code)
-- [x] `module()` factory also requires explicit `inputSchema` and `outputSchema`
-- [x] Complex nested schemas round-trip correctly through FunctionModule construction
-
-## Dependencies
-
-- `function-module` -- Requires `FunctionModule` class with `inputSchema`/`outputSchema` fields
-
-## Estimated Time
-
-1 hour

package/planning/decorator-bindings/tasks/function-module.md

@@ -1,127 +0,0 @@
-# Task: FunctionModule Class with Execute, Schemas, and normalizeResult()
-
-## Goal
-
-Implement the `FunctionModule` class that wraps an execute function with explicit TypeBox `inputSchema`/`outputSchema`, metadata properties (description, documentation, tags, version, annotations, metadata, examples), and a `normalizeResult()` utility for standardizing module return values. Also implement `makeAutoId()` for generating valid module IDs from arbitrary strings.
-
-## Files Involved
-
-- `src/decorator.ts` -- `FunctionModule` class, `normalizeResult()`, `makeAutoId()`
-- `tests/test-decorator.test.ts` -- Unit tests for FunctionModule, normalizeResult(), makeAutoId()
-
-## Steps
-
-### 1. Write failing tests (TDD)
-
-Create tests for:
-- **FunctionModule wraps execute**: Construct with execute function, moduleId, inputSchema, outputSchema; call `execute()` and verify result
-- **FunctionModule exposes properties**: Verify moduleId, description, documentation, tags, version are accessible
-- **FunctionModule defaults**: Verify sensible defaults (description="Module {id}", documentation=null, tags=null, version="1.0.0", annotations=null, metadata=null, examples=null)
-- **FunctionModule normalizes null return**: Execute function returning null produces `{}`
-- **normalizeResult(null)**: Returns `{}`
-- **normalizeResult(undefined)**: Returns `{}`
-- **normalizeResult(Record)**: Passes through unchanged
-- **normalizeResult(string)**: Returns `{ result: "hello" }`
-- **normalizeResult(number)**: Returns `{ result: 42 }`
-- **normalizeResult(boolean)**: Returns `{ result: true }`
-- **normalizeResult(array)**: Returns `{ result: [1, 2, 3] }`
-- **makeAutoId lowercases**: `makeAutoId('Hello World')` -> `'hello_world'`
-- **makeAutoId preserves dots**: `makeAutoId('my.module.name')` -> `'my.module.name'`
-- **makeAutoId prefixes digit-leading segments**: `makeAutoId('2fast.4you')` -> `'_2fast._4you'`
-- **makeAutoId no-op on valid IDs**: `makeAutoId('valid_id')` -> `'valid_id'`
-
-### 2. Implement normalizeResult()
-
-```typescript
-export function normalizeResult(result: unknown): Record<string, unknown> {
-  if (result === null || result === undefined) return {};
-  if (typeof result === 'object' && !Array.isArray(result)) return result as Record<string, unknown>;
-  return { result };
-}
-```
-
-### 3. Implement makeAutoId()
-
-```typescript
-export function makeAutoId(name: string): string {
-  let raw = name.toLowerCase();
-  raw = raw.replace(/[^a-z0-9_.]/g, '_');
-  const segments = raw.split('.');
-  return segments
-    .map((s) => (s && s[0] >= '0' && s[0] <= '9' ? '_' + s : s))
-    .join('.');
-}
-```
-
-### 4. Implement FunctionModule class
-
-```typescript
-export class FunctionModule {
-  readonly moduleId: string;
-  readonly inputSchema: TSchema;
-  readonly outputSchema: TSchema;
-  readonly description: string;
-  readonly documentation: string | null;
-  readonly tags: string[] | null;
-  readonly version: string;
-  readonly annotations: ModuleAnnotations | null;
-  readonly metadata: Record<string, unknown> | null;
-  readonly examples: ModuleExample[] | null;
-
-  private _executeFn: (inputs: Record<string, unknown>, context: Context) =>
-    Promise<Record<string, unknown>> | Record<string, unknown>;
-
-  constructor(options: {
-    execute: (inputs: Record<string, unknown>, context: Context) =>
-      Promise<Record<string, unknown>> | Record<string, unknown>;
-    moduleId: string;
-    inputSchema: TSchema;
-    outputSchema: TSchema;
-    description?: string;
-    documentation?: string | null;
-    tags?: string[] | null;
-    version?: string;
-    annotations?: ModuleAnnotations | null;
-    metadata?: Record<string, unknown> | null;
-    examples?: ModuleExample[] | null;
-  }) {
-    this.moduleId = options.moduleId;
-    this.inputSchema = options.inputSchema;
-    this.outputSchema = options.outputSchema;
-    this.description = options.description ?? `Module ${options.moduleId}`;
-    this.documentation = options.documentation ?? null;
-    this.tags = options.tags ?? null;
-    this.version = options.version ?? '1.0.0';
-    this.annotations = options.annotations ?? null;
-    this.metadata = options.metadata ?? null;
-    this.examples = options.examples ?? null;
-    this._executeFn = options.execute;
-  }
-
-  async execute(inputs: Record<string, unknown>, context: Context): Promise<Record<string, unknown>> {
-    const result = await this._executeFn(inputs, context);
-    return normalizeResult(result);
-  }
-}
-```
-
-### 5. Verify tests pass
-
-Run `npx vitest run tests/test-decorator.test.ts` and confirm all FunctionModule, normalizeResult, and makeAutoId tests pass.
-
-## Acceptance Criteria
-
-- [x] `FunctionModule` constructor accepts options object with execute, moduleId, inputSchema, outputSchema, and optional metadata
-- [x] `FunctionModule.execute()` calls wrapped function and passes result through `normalizeResult()`
-- [x] Default description is `"Module {moduleId}"`, version is `"1.0.0"`, others default to `null`
-- [x] `normalizeResult()` correctly handles null, undefined, Record, string, number, boolean, and array
-- [x] `makeAutoId()` lowercases, replaces invalid characters, preserves dots, prefixes digit-leading segments
-- [x] All fields are typed with `readonly` where appropriate
-
-## Dependencies
-
-None -- this is the foundational data structure for the decorator-bindings module.
-
-## Estimated Time
-
-2 hours

package/planning/decorator-bindings/tasks/module-factory.md

@@ -1,89 +0,0 @@
-# Task: module() Factory Function with Options Object Pattern
-
-## Goal
-
-Implement the `module()` factory function that creates a `FunctionModule` from an options object. This is the primary ergonomic API for defining apcore modules in TypeScript. Unlike Python's `@module` decorator, this is a plain factory function that returns a `FunctionModule` instance. It supports optional auto-registration with a `Registry` and auto-generates a module ID via `makeAutoId('anonymous')` when no `id` is provided.
-
-## Files Involved
-
-- `src/decorator.ts` -- `module()` factory function
-- `tests/test-decorator.test.ts` -- Unit tests for module() factory
-
-## Steps
-
-### 1. Write failing tests (TDD)
-
-Create tests for:
-- **Creates FunctionModule with correct properties**: `module({ id: 'factory.test', inputSchema, outputSchema, execute })` returns `FunctionModule` with correct moduleId and description
-- **Generates auto ID when not provided**: `module({ inputSchema, outputSchema, execute })` creates module with moduleId `'anonymous'`
-- **Passes through optional fields**: documentation, tags, version, metadata are forwarded to FunctionModule
-- **Auto-registers with registry**: When `registry` option is provided, the module is registered via `registry.register()`
-
-### 2. Implement module() factory
-
-```typescript
-export function module(options: {
-  id?: string;
-  inputSchema: TSchema;
-  outputSchema: TSchema;
-  description?: string;
-  documentation?: string | null;
-  annotations?: ModuleAnnotations | null;
-  tags?: string[] | null;
-  version?: string;
-  metadata?: Record<string, unknown> | null;
-  examples?: ModuleExample[] | null;
-  execute: (inputs: Record<string, unknown>, context: Context) =>
-    Promise<Record<string, unknown>> | Record<string, unknown>;
-  registry?: { register(moduleId: string, module: unknown): void } | null;
-}): FunctionModule {
-  const moduleId = options.id ?? makeAutoId('anonymous');
-
-  const fm = new FunctionModule({
-    execute: options.execute,
-    moduleId,
-    inputSchema: options.inputSchema,
-    outputSchema: options.outputSchema,
-    description: options.description,
-    documentation: options.documentation,
-    tags: options.tags,
-    version: options.version,
-    annotations: options.annotations,
-    metadata: options.metadata,
-    examples: options.examples,
-  });
-
-  if (options.registry) {
-    options.registry.register(fm.moduleId, fm);
-  }
-
-  return fm;
-}
-```
-
-Key design decisions:
-- The `registry` option uses a structural type `{ register(moduleId: string, module: unknown): void }` rather than importing the `Registry` class, enabling loose coupling and easier testing
-- When `id` is omitted, `makeAutoId('anonymous')` produces `'anonymous'` (a valid ID)
-- All optional metadata fields are forwarded to `FunctionModule` without transformation
-
-### 3. Verify tests pass
-
-Run `npx vitest run tests/test-decorator.test.ts` and confirm all module() factory tests pass.
-
-## Acceptance Criteria
-
-- [x] `module()` returns a `FunctionModule` instance
-- [x] `module()` forwards all options to `FunctionModule` constructor
-- [x] `module({ id: 'x', ... })` creates module with `moduleId === 'x'`
-- [x] `module({ ... })` without `id` creates module with `moduleId === 'anonymous'`
-- [x] `module({ registry, ... })` auto-registers the module with the provided registry
-- [x] `module({ registry: null, ... })` does not attempt registration
-- [x] `registry` option uses structural typing for loose coupling
-
-## Dependencies
-
-- `function-module` -- Requires `FunctionModule` class and `makeAutoId()`
-
-## Estimated Time
-
-2 hours