apcore-js 0.1.0

package/planning/decorator-bindings/state.json

@@ -0,0 +1,87 @@
+{
+  "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

@@ -0,0 +1,79 @@
+# 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

@@ -0,0 +1,148 @@
+# 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

@@ -0,0 +1,85 @@
+# 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

@@ -0,0 +1,127 @@
+# 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

@@ -0,0 +1,89 @@
+# 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