apcore-js 0.1.0

package/planning/observability/tasks/tracing-middleware.md

@@ -0,0 +1,179 @@
+# Task: TracingMiddleware with Sampling Strategies
+
+## Goal
+
+Implement `TracingMiddleware` that extends the `Middleware` base class to provide distributed tracing through the executor pipeline. The middleware uses a stack-based approach to manage nested spans via `context.data`, supports 4 sampling strategies (`full`, `proportional`, `error_first`, `off`), and delegates span export to a pluggable `SpanExporter`.
+
+## Files Involved
+
+- `src/observability/tracing.ts` -- TracingMiddleware class
+- `src/middleware/base.ts` -- Middleware base class (dependency)
+- `src/context.ts` -- Context class with shared `data` record (dependency)
+- `tests/observability/test-tracing.test.ts` -- Unit tests for TracingMiddleware
+
+## Steps (TDD)
+
+### 1. Write failing tests for TracingMiddleware
+
+```typescript
+describe('TracingMiddleware', () => {
+  it('creates and exports spans on success', () => {
+    const exporter = new InMemoryExporter();
+    const mw = new TracingMiddleware(exporter);
+    const ctx = Context.create();
+
+    mw.before('mod.a', {}, ctx);
+    mw.after('mod.a', {}, { result: 'ok' }, ctx);
+
+    const spans = exporter.getSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0].name).toBe('apcore.module.execute');
+    expect(spans[0].status).toBe('ok');
+    expect(spans[0].attributes['moduleId']).toBe('mod.a');
+  });
+
+  it('creates error spans', () => {
+    const exporter = new InMemoryExporter();
+    const mw = new TracingMiddleware(exporter);
+    const ctx = Context.create();
+
+    mw.before('mod.err', {}, ctx);
+    mw.onError('mod.err', {}, new Error('fail'), ctx);
+
+    const spans = exporter.getSpans();
+    expect(spans).toHaveLength(1);
+    expect(spans[0].status).toBe('error');
+    expect(spans[0].attributes['success']).toBe(false);
+  });
+
+  it('supports nested spans with parent chain', () => {
+    const exporter = new InMemoryExporter();
+    const mw = new TracingMiddleware(exporter);
+    const ctx = Context.create();
+
+    mw.before('mod.outer', {}, ctx);
+    mw.before('mod.inner', {}, ctx);
+    mw.after('mod.inner', {}, {}, ctx);
+    mw.after('mod.outer', {}, {}, ctx);
+
+    const spans = exporter.getSpans();
+    expect(spans).toHaveLength(2);
+    expect(spans[0].parentSpanId).toBe(spans[1].spanId);
+  });
+
+  it('off strategy does not export', () => {
+    const exporter = new InMemoryExporter();
+    const mw = new TracingMiddleware(exporter, 1.0, 'off');
+    const ctx = Context.create();
+
+    mw.before('mod.a', {}, ctx);
+    mw.after('mod.a', {}, {}, ctx);
+
+    expect(exporter.getSpans()).toHaveLength(0);
+  });
+
+  it('error_first exports errors even when not sampled', () => {
+    const exporter = new InMemoryExporter();
+    const mw = new TracingMiddleware(exporter, 0.0, 'error_first');
+    const ctx = Context.create();
+
+    mw.before('mod.a', {}, ctx);
+    mw.onError('mod.a', {}, new Error('fail'), ctx);
+
+    expect(exporter.getSpans()).toHaveLength(1);
+  });
+
+  it('throws on invalid sampling rate', () => {
+    const exporter = new InMemoryExporter();
+    expect(() => new TracingMiddleware(exporter, -0.1)).toThrow();
+    expect(() => new TracingMiddleware(exporter, 1.5)).toThrow();
+  });
+
+  it('throws on invalid sampling strategy', () => {
+    const exporter = new InMemoryExporter();
+    expect(() => new TracingMiddleware(exporter, 1.0, 'invalid')).toThrow();
+  });
+});
+```
+
+### 2. Implement sampling strategy validation
+
+```typescript
+const VALID_STRATEGIES = new Set(['full', 'proportional', 'error_first', 'off']);
+
+export class TracingMiddleware extends Middleware {
+  constructor(
+    exporter: SpanExporter,
+    samplingRate: number = 1.0,
+    samplingStrategy: string = 'full',
+  ) {
+    super();
+    if (samplingRate < 0.0 || samplingRate > 1.0) {
+      throw new Error(`sampling_rate must be between 0.0 and 1.0, got ${samplingRate}`);
+    }
+    if (!VALID_STRATEGIES.has(samplingStrategy)) {
+      throw new Error(`sampling_strategy must be one of ${[...VALID_STRATEGIES].join(', ')}, got '${samplingStrategy}'`);
+    }
+    // ...
+  }
+}
+```
+
+### 3. Implement _shouldSample() with strategy logic
+
+The sampling decision is computed once per context and cached at `context.data['_tracing_sampled']`:
+
+- **full**: Always sample (`decision = true`)
+- **off**: Never sample (`decision = false`)
+- **proportional**: Sample with probability `samplingRate` (`Math.random() < samplingRate`)
+- **error_first**: Same as proportional for the decision, but errors are always exported regardless
+
+### 4. Implement before() with stack-based span creation
+
+```typescript
+override before(moduleId: string, _inputs: Record<string, unknown>, context: Context): null {
+  this._shouldSample(context);
+  const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
+  context.data['_tracing_spans'] = spansStack;
+  const parentSpanId = spansStack.length > 0
+    ? spansStack[spansStack.length - 1].spanId
+    : null;
+
+  const span = createSpan({
+    traceId: context.traceId,
+    name: 'apcore.module.execute',
+    startTime: performance.now(),
+    parentSpanId,
+    attributes: { moduleId, method: 'execute', callerId: context.callerId },
+  });
+  spansStack.push(span);
+  return null;
+}
+```
+
+### 5. Implement after() and onError() with span finalization
+
+Both methods pop the top span from the stack, set `endTime`, compute `duration_ms`, set status, and conditionally export. `onError()` additionally checks `error_first` strategy to force export.
+
+### 6. Run tests and verify all pass
+
+## Acceptance Criteria
+
+- [x] `TracingMiddleware` extends `Middleware` and accepts `exporter`, `samplingRate`, `samplingStrategy`
+- [x] Constructor validates `samplingRate` in `[0.0, 1.0]` and `samplingStrategy` in valid set
+- [x] 4 strategies implemented: `full` (always), `proportional` (random), `error_first` (random + always-export-errors), `off` (never)
+- [x] Sampling decision computed once per context and cached at `_tracing_sampled`
+- [x] Stack-based span management at `context.data['_tracing_spans']` handles nested calls
+- [x] `parentSpanId` correctly chains from top-of-stack span
+- [x] Span attributes include `moduleId`, `method`, `callerId`, `duration_ms`, `success`
+- [x] Error spans include `error_code` from `error.code` or `error.constructor.name`
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- **span-model** -- Requires `Span`, `createSpan()`, `SpanExporter`
+- **exporters** -- Requires `InMemoryExporter` for testing
+
+## Estimated Time
+
+3 hours

package/planning/overview.md

@@ -0,0 +1,81 @@
+# apcore-typescript - Implementation Overview
+
+## Overall Progress
+
+```
+[████████████████████████████████████████] 42/42 tasks (100%)
+```
+
+| Status | Count |
+|--------|-------|
+| Completed | 7 modules |
+| In Progress | 0 modules |
+| Pending | 0 modules |
+
+## Module Overview
+
+| # | Module | Description | Status | Progress |
+|---|--------|-------------|--------|----------|
+| 1 | [core-executor](./core-executor/) | Central orchestration: 10-step execution pipeline with context, safety checks, ACL, and middleware chains | completed | 5/5 |
+| 2 | [schema-system](./schema-system/) | Schema loading, $ref resolution, TypeBox model generation, validation, and LLM provider format export | completed | 7/7 |
+| 3 | [registry-system](./registry-system/) | Module discovery, registration, and querying with 8-step pipeline and topological dependency sort | completed | 8/8 |
+| 4 | [middleware-system](./middleware-system/) | Composable onion-model middleware with before/after/on_error phases | completed | 4/4 |
+| 5 | [acl-system](./acl-system/) | Pattern-based ACL with first-match-wins evaluation and conditional rules | completed | 5/5 |
+| 6 | [observability](./observability/) | Distributed tracing, metrics collection, and structured logging middleware | completed | 7/7 |
+| 7 | [decorator-bindings](./decorator-bindings/) | module() factory for code-first and BindingLoader for YAML-driven module registration | completed | 6/6 |
+
+## Module Dependencies
+
+```mermaid
+graph TD
+    CE[core-executor] --> SS[schema-system]
+    CE --> MS[middleware-system]
+    CE --> ACL[acl-system]
+    CE --> RS[registry-system]
+    RS --> SS
+    RS --> DB[decorator-bindings]
+    DB --> SS
+    OBS[observability] --> MS
+    OBS --> CE
+
+    style CE fill:#2d6,stroke:#333,color:#fff
+    style SS fill:#2d6,stroke:#333,color:#fff
+    style RS fill:#2d6,stroke:#333,color:#fff
+    style MS fill:#2d6,stroke:#333,color:#fff
+    style ACL fill:#2d6,stroke:#333,color:#fff
+    style OBS fill:#2d6,stroke:#333,color:#fff
+    style DB fill:#2d6,stroke:#333,color:#fff
+```
+
+## Recommended Implementation Order
+
+### Phase 1: Foundation (Why first: no dependencies on other modules)
+
+| Module | Rationale |
+|--------|-----------|
+| [schema-system](./schema-system/) | Core type definitions and validation used by all other modules |
+| [middleware-system](./middleware-system/) | Base middleware infrastructure needed by executor and observability |
+| [acl-system](./acl-system/) | Standalone access control with no internal dependencies |
+
+### Phase 2: Core (Why next: depends only on Phase 1 modules)
+
+| Module | Rationale |
+|--------|-----------|
+| [decorator-bindings](./decorator-bindings/) | Depends on schema-system for TypeBox schema generation |
+| [registry-system](./registry-system/) | Depends on schema-system and decorator-bindings for module discovery |
+
+### Phase 3: Orchestration (Why next: integrates all previous modules)
+
+| Module | Rationale |
+|--------|-----------|
+| [core-executor](./core-executor/) | Depends on schema-system, middleware-system, acl-system, and registry-system |
+
+### Phase 4: Cross-Cutting (Why last: enhances existing modules without changing behavior)
+
+| Module | Rationale |
+|--------|-----------|
+| [observability](./observability/) | Depends on middleware-system and core-executor; adds tracing/metrics/logging |
+
+---
+
+*Generated by [code-forge](https://github.com/tercel/code-forge) | Source: [planning/features/](../features/)*

package/planning/registry-system/overview.md

@@ -0,0 +1,57 @@
+# Feature: Registry System
+
+## Overview
+
+The Registry System is the module discovery, loading, and querying backbone of apcore. It scans extension directories for `.ts`/`.js` files, loads companion YAML metadata, resolves module entry points via async `import()`, validates structural requirements (inputSchema, outputSchema, description, execute), resolves inter-module dependencies through Kahn's topological sort, and registers modules in dependency order. The `Registry` class exposes query methods (`get`, `has`, `list`, `iter`, `count`, `moduleIds`, `getDefinition`) and event callbacks for register/unregister lifecycle hooks. Schema export functions provide JSON and YAML serialization with optional strict-mode and LLM export profiles.
+
+## Scope
+
+### Included
+
+- `ModuleDescriptor`, `DiscoveredModule`, and `DependencyInfo` interfaces for type-safe module representation
+- `EventCallback` type for register/unregister event subscriptions
+- `scanExtensions()` and `scanMultiRoot()` for recursive directory scanning with `.ts`/`.js` filtering, `.d.ts`/test file exclusion, case-collision detection, and configurable symlink following
+- `loadMetadata()`, `mergeModuleMetadata()`, `loadIdMap()`, `parseDependencies()` for YAML metadata loading and code/YAML conflict resolution
+- `resolveDependencies()` implementing Kahn's topological sort with cycle detection and extraction
+- `resolveEntryPoint()` using async `import()` with default-export preference, named-export auto-inference, and metadata-driven entry point override
+- `validateModule()` for duck-type structural validation of inputSchema, outputSchema, description, and execute
+- `Registry` class with 8-step async `discover()` pipeline, manual `register()`/`unregister()`, query accessors, event system, and schema cache management
+- `getSchema()`, `exportSchema()`, `getAllSchemas()`, `exportAllSchemas()` with strict-mode, compact-mode, and LLM export profile support
+
+### Excluded
+
+- Schema system internals (consumed via TypeBox `TSchema` and `SchemaExporter`)
+- ACL enforcement (consumed by `core-executor`)
+- Middleware chains (consumed by `core-executor`)
+- YAML schema file authoring and schema directory management
+
+## Technology Stack
+
+- **TypeScript 5.5+** with strict mode
+- **@sinclair/typebox >= 0.34.0** for schema representation (`TSchema`)
+- **js-yaml** for YAML metadata and ID map parsing
+- **Node.js >= 18.0.0** with ES Module support (`node:fs`, `node:path`, dynamic `import()`)
+- **vitest** for unit and integration testing
+
+## Task Execution Order
+
+| # | Task File | Description | Status |
+|---|-----------|-------------|--------|
+| 1 | [types](./tasks/types.md) | ModuleDescriptor, DiscoveredModule, DependencyInfo interfaces | completed |
+| 2 | [scanner](./tasks/scanner.md) | scanExtensions(), scanMultiRoot() directory scanning | completed |
+| 3 | [metadata](./tasks/metadata.md) | loadMetadata(), mergeModuleMetadata(), loadIdMap(), parseDependencies() | completed |
+| 4 | [dependencies](./tasks/dependencies.md) | resolveDependencies() Kahn's topological sort with cycle detection | completed |
+| 5 | [entry-point](./tasks/entry-point.md) | resolveEntryPoint() with async import() and auto-inference | completed |
+| 6 | [validation](./tasks/validation.md) | validateModule() structural duck-type checks | completed |
+| 7 | [registry-core](./tasks/registry-core.md) | Registry class with 8-step discover() and query methods | completed |
+| 8 | [schema-export](./tasks/schema-export.md) | getSchema(), exportSchema(), getAllSchemas(), exportAllSchemas() | completed |
+
+## Progress
+
+| Total | Completed | In Progress | Pending |
+|-------|-----------|-------------|---------|
+| 8     | 8         | 0           | 0       |
+
+## Reference Documents
+
+- [Registry System Feature Specification](../../features/registry-system.md)

package/planning/registry-system/plan.md

@@ -0,0 +1,114 @@
+# Implementation Plan: Registry System
+
+## Goal
+
+Implement the module discovery and registration backbone for apcore, providing recursive directory scanning for `.ts`/`.js` extension files, YAML metadata loading with code-level merging, dependency resolution via Kahn's topological sort, dynamic module loading via async `import()`, structural validation, and a central `Registry` class that orchestrates the full 8-step discovery pipeline and exposes query, event, and schema export APIs.
+
+## Architecture Design
+
+### Component Structure
+
+- **Types** (`registry/types.ts`, ~30 lines) -- Core interfaces: `ModuleDescriptor` (full module definition with schemas, tags, annotations, examples), `DiscoveredModule` (file path, canonical ID, meta path, namespace), and `DependencyInfo` (module ID, version, optional flag). Imports `ModuleAnnotations` and `ModuleExample` from the shared `module.ts` types.
+
+- **Scanner** (`registry/scanner.ts`, ~140 lines) -- `scanExtensions()` recursively walks a single directory tree collecting `.ts`/`.js` files, skipping `.d.ts`, `.test.ts`, `.test.js`, `.spec.ts`, `.spec.js`, dot-prefixed entries, underscore-prefixed entries, and `node_modules`/`__pycache__` directories. Builds canonical IDs from relative paths using dot notation. Detects case collisions. Supports configurable `maxDepth` and `followSymlinks`. `scanMultiRoot()` delegates to `scanExtensions()` per root, prepending namespace prefixes and enforcing namespace uniqueness. **Known bug**: symlink detection uses `statSync` instead of `lstatSync`, so `stat.isSymbolicLink()` always returns false after stat follows the link.
+
+- **Metadata** (`registry/metadata.ts`, ~105 lines) -- `loadMetadata()` reads and parses a YAML `_meta.yaml` file into a record. `parseDependencies()` converts raw dependency arrays into typed `DependencyInfo[]`. `mergeModuleMetadata()` merges code-level properties with YAML overrides (YAML wins for description, name, tags, version, annotations, examples, documentation; metadata records are shallow-merged). `loadIdMap()` loads a YAML ID map file with a `mappings` list for canonical ID overrides.
+
+- **Dependencies** (`registry/dependencies.ts`, ~100 lines) -- `resolveDependencies()` implements Kahn's topological sort. Builds an adjacency graph and in-degree map from module dependency lists. Processes zero-in-degree nodes in sorted order for deterministic output. Throws `ModuleLoadError` for missing required dependencies and `CircularDependencyError` with an extracted cycle path when not all modules can be ordered. `extractCycle()` traces the first reachable cycle from remaining nodes.
+
+- **Entry Point** (`registry/entry-point.ts`, ~65 lines) -- `resolveEntryPoint()` uses async `import()` to dynamically load a `.ts`/`.js` file, then resolves the module object. Priority: (1) metadata `entry_point` class name override, (2) default export if it passes `isModuleClass()`, (3) single named export passing `isModuleClass()`. Throws `ModuleLoadError` on import failure, missing class, no candidates, or ambiguous multiple candidates. `snakeToPascal()` utility converts snake_case to PascalCase. `isModuleClass()` duck-types by checking for inputSchema (object), outputSchema (object), description (string), and execute (function).
+
+- **Validation** (`registry/validation.ts`, ~40 lines) -- `validateModule()` performs duck-type structural validation. Checks for: inputSchema (must be a non-null object, checked on instance and constructor), outputSchema (same), description (non-empty string), and execute (function). Returns an array of error strings; empty array means valid.
+
+- **Registry** (`registry/registry.ts`, ~315 lines) -- Central `Registry` class. Constructor accepts optional `config`, `extensionsDir`, `extensionsDirs` (mutually exclusive), and `idMapPath`. Maintains `_modules` (Map of module ID to module object), `_moduleMeta` (Map of merged metadata), `_callbacks` (Map of event name to callback arrays), `_idMap` (canonical ID overrides), and `_schemaCache`. Exposes: `discover()` (async, returns count), `register()`, `unregister()`, `get()`, `has()`, `list()` (with tag/prefix filtering), `iter()`, `count` (getter), `moduleIds` (getter), `getDefinition()`, `on()`, `clearCache()`. Lifecycle hooks: calls `onLoad()` during registration and `onUnload()` during unregistration.
+
+- **Schema Export** (`registry/schema-export.ts`, ~180 lines) -- `getSchema()` extracts a schema record from a registered module. `exportSchema()` serializes with optional strict mode (`toStrictSchema()`), compact mode (truncated descriptions, stripped extensions), or LLM export profile (MCP, OpenAI, Anthropic, Generic). `getAllSchemas()` and `exportAllSchemas()` operate on all registered modules. `serialize()` outputs JSON or YAML format.
+
+### Data Flow
+
+The 8-step `discover()` pipeline processes modules in this order:
+
+1. **Scan Extension Roots** -- `scanExtensions()` or `scanMultiRoot()` depending on root configuration, producing `DiscoveredModule[]` with file paths, canonical IDs, and meta paths
+2. **Apply ID Map Overrides** -- If an ID map was loaded, override canonical IDs for matching relative file paths
+3. **Load Metadata** -- For each discovered module with a `_meta.yaml` companion, `loadMetadata()` parses the YAML into a metadata record
+4. **Resolve Entry Points** -- `resolveEntryPoint()` uses async `import()` to load each file and resolve the module object (default export, named export, or metadata-specified class)
+5. **Validate Modules** -- `validateModule()` checks structural requirements; invalid modules are silently dropped
+6. **Collect Dependencies** -- `parseDependencies()` extracts `DependencyInfo[]` from each module's metadata
+7. **Resolve Dependency Order** -- `resolveDependencies()` applies Kahn's topological sort, detecting cycles and missing required dependencies
+8. **Register in Order** -- Modules are registered in dependency order, merged metadata is stored, `onLoad()` is called, and register event callbacks fire
+
+### Technical Choices and Rationale
+
+- **Async `import()` vs Python's `importlib`**: TypeScript/Node.js uses native ES module dynamic `import()` which is inherently async, unlike Python's synchronous `importlib.import_module()`. This makes `discover()` an async method returning `Promise<number>`, whereas the Python equivalent is synchronous.
+- **No thread locking**: Node.js runs on a single-threaded event loop, eliminating the need for Python's `threading.Lock()` around registry mutations. The `_modules` Map is safely accessed without synchronization.
+- **`statSync` instead of `lstatSync`**: The scanner uses `statSync` which follows symlinks before checking `isSymbolicLink()`, making the symlink check always return false. This is a known bug carried from the initial implementation. The fix would be to use `lstatSync` for the symlink check.
+- **TypeBox schemas as JSON Schema**: Module `inputSchema` and `outputSchema` are TypeBox `TSchema` objects, which are already valid JSON Schema. No conversion step is needed for schema export, unlike Python's Pydantic models which require `.model_json_schema()`.
+- **Deterministic sort in Kahn's algorithm**: Zero-in-degree nodes and dependents are processed in sorted order to ensure deterministic load ordering across runs.
+- **Duck-type validation**: Instead of Python's class hierarchy checks (`issubclass`), TypeScript validation uses duck typing -- checking for the presence and types of `inputSchema`, `outputSchema`, `description`, and `execute` properties.
+
+## Task Breakdown
+
+```mermaid
+graph TD
+    T1[types] --> T2[scanner]
+    T1 --> T3[metadata]
+    T1 --> T4[dependencies]
+    T1 --> T5[entry-point]
+    T1 --> T6[validation]
+    T2 --> T7[registry-core]
+    T3 --> T7
+    T4 --> T7
+    T5 --> T7
+    T6 --> T7
+    T7 --> T8[schema-export]
+```
+
+| Task ID | Title | Estimated Time | Dependencies |
+|---------|-------|---------------|--------------|
+| types | ModuleDescriptor, DiscoveredModule, DependencyInfo interfaces | 1h | none |
+| scanner | scanExtensions(), scanMultiRoot() directory scanning | 3h | types |
+| metadata | loadMetadata(), mergeModuleMetadata(), loadIdMap(), parseDependencies() | 2h | types |
+| dependencies | resolveDependencies() Kahn's topological sort | 3h | types |
+| entry-point | resolveEntryPoint() with async import() | 2h | types |
+| validation | validateModule() structural checks | 1h | types |
+| registry-core | Registry class with 8-step discover() and query methods | 5h | scanner, metadata, dependencies, entry-point, validation |
+| schema-export | getSchema(), exportSchema(), getAllSchemas(), exportAllSchemas() | 3h | registry-core |
+
+## Risks and Considerations
+
+- **Symlink detection bug**: `statSync` follows symlinks before `isSymbolicLink()` is called, so the symlink guard in the scanner never triggers. Symlink cycles could cause infinite recursion up to `maxDepth`. The fix is to use `lstatSync` for the initial stat call.
+- **Silent module drop on import failure**: If `resolveEntryPoint()` throws during `discover()`, the module is silently skipped with `continue`. This could hide genuine configuration or code errors. Consider adding a logging callback or accumulating warnings.
+- **Case-insensitive filesystem collisions**: The scanner detects case collisions in canonical IDs but does not prevent registration. On case-insensitive filesystems (macOS default), this could lead to unexpected behavior.
+- **`onLoad` failure during discover**: If a module's `onLoad()` throws during step 8, the module is removed from the registry but no error is propagated. This is intentional for resilience but could mask setup failures.
+- **Schema cache invalidation**: `clearCache()` only clears the schema cache; it does not affect `_modules` or `_moduleMeta`. Re-running `discover()` will add modules but not remove previously registered ones.
+
+## Acceptance Criteria
+
+- [x] `ModuleDescriptor`, `DiscoveredModule`, `DependencyInfo` interfaces compile with strict TypeScript
+- [x] `scanExtensions()` discovers `.ts`/`.js` files, skips `.d.ts`, test files, dot/underscore prefixed, and `node_modules`
+- [x] `scanMultiRoot()` enforces unique namespaces and prepends namespace to canonical IDs
+- [x] `loadMetadata()` parses YAML `_meta.yaml` files; returns `{}` for missing files
+- [x] `mergeModuleMetadata()` merges code and YAML metadata with YAML taking precedence
+- [x] `loadIdMap()` loads YAML ID map with `mappings` list; throws on invalid format
+- [x] `parseDependencies()` converts raw dependency arrays to typed `DependencyInfo[]`
+- [x] `resolveDependencies()` produces correct topological order and detects cycles
+- [x] `resolveEntryPoint()` resolves default exports, single named exports, and metadata-specified classes
+- [x] `validateModule()` returns empty array for valid modules and descriptive errors for invalid ones
+- [x] `Registry.discover()` executes all 8 pipeline steps and returns registered count
+- [x] `Registry.register()`/`unregister()` manage modules with lifecycle hooks and event callbacks
+- [x] `Registry.get()`, `has()`, `list()`, `iter()`, `count`, `moduleIds` provide correct query results
+- [x] `getSchema()`/`exportSchema()` produce correct JSON/YAML with strict and compact modes
+- [x] `getAllSchemas()`/`exportAllSchemas()` operate across all registered modules
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## References
+
+- `src/registry/types.ts` -- Core type interfaces
+- `src/registry/scanner.ts` -- Directory scanning
+- `src/registry/metadata.ts` -- Metadata loading and merging
+- `src/registry/dependencies.ts` -- Dependency resolution
+- `src/registry/entry-point.ts` -- Dynamic module loading
+- `src/registry/validation.ts` -- Module structural validation
+- `src/registry/registry.ts` -- Central Registry class
+- `src/registry/schema-export.ts` -- Schema query and export
+- `src/registry/index.ts` -- Public API re-exports

package/planning/registry-system/state.json

@@ -0,0 +1,109 @@
+{
+  "feature": "registry-system",
+  "created": "2026-02-16T00:00:00Z",
+  "updated": "2026-02-16T00:00:00Z",
+  "status": "completed",
+  "execution_order": [
+    "types",
+    "scanner",
+    "metadata",
+    "dependencies",
+    "entry-point",
+    "validation",
+    "registry-core",
+    "schema-export"
+  ],
+  "progress": {
+    "total_tasks": 8,
+    "completed": 8,
+    "in_progress": 0,
+    "pending": 0
+  },
+  "tasks": [
+    {
+      "id": "types",
+      "file": "tasks/types.md",
+      "title": "ModuleDescriptor, DiscoveredModule, DependencyInfo Interfaces",
+      "status": "completed",
+      "started_at": "2026-02-16T08:00:00Z",
+      "completed_at": "2026-02-16T09:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "scanner",
+      "file": "tasks/scanner.md",
+      "title": "Directory Scanning with scanExtensions() and scanMultiRoot()",
+      "status": "completed",
+      "started_at": "2026-02-16T09:00:00Z",
+      "completed_at": "2026-02-16T12:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "metadata",
+      "file": "tasks/metadata.md",
+      "title": "Metadata Loading, Merging, ID Map, and Dependency Parsing",
+      "status": "completed",
+      "started_at": "2026-02-16T12:00:00Z",
+      "completed_at": "2026-02-16T14:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "dependencies",
+      "file": "tasks/dependencies.md",
+      "title": "Kahn's Topological Sort with Cycle Detection",
+      "status": "completed",
+      "started_at": "2026-02-16T14:00:00Z",
+      "completed_at": "2026-02-16T17:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "entry-point",
+      "file": "tasks/entry-point.md",
+      "title": "Dynamic Module Loading via async import()",
+      "status": "completed",
+      "started_at": "2026-02-16T17:00:00Z",
+      "completed_at": "2026-02-16T19:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "validation",
+      "file": "tasks/validation.md",
+      "title": "Module Structural Validation",
+      "status": "completed",
+      "started_at": "2026-02-16T19:00:00Z",
+      "completed_at": "2026-02-16T20:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "registry-core",
+      "file": "tasks/registry-core.md",
+      "title": "Registry Class with 8-Step Discover Pipeline",
+      "status": "completed",
+      "started_at": "2026-02-16T20:00:00Z",
+      "completed_at": "2026-02-17T01:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "schema-export",
+      "file": "tasks/schema-export.md",
+      "title": "Schema Query and Export Functions",
+      "status": "completed",
+      "started_at": "2026-02-17T01:00:00Z",
+      "completed_at": "2026-02-17T04:00:00Z",
+      "assignee": null,
+      "commits": []
+    }
+  ],
+  "metadata": {
+    "source_doc": "planning/features/registry-system.md",
+    "created_by": "code-forge",
+    "version": "1.0"
+  }
+}