apcore-js 0.1.0

package/planning/schema-system/plan.md

@@ -0,0 +1,121 @@
+# Implementation Plan: Schema System
+
+## Goal
+
+Implement the complete schema infrastructure for apcore: YAML-based schema loading with `$ref` resolution, recursive conversion from JSON Schema to TypeBox `TSchema` objects, runtime validation with coercion support, annotation merging between YAML and code metadata, strict-mode transformations for LLM provider compatibility, and multi-format export targeting MCP, OpenAI, Anthropic, and Generic consumers.
+
+## Architecture Design
+
+### Component Structure
+
+- **Types and Interfaces** (`schema/types.ts`, ~74 lines) -- Core type definitions for the schema system. Defines `SchemaStrategy` enum (`YamlFirst`, `NativeFirst`, `YamlOnly`), `ExportProfile` enum (`MCP`, `OpenAI`, `Anthropic`, `Generic`), `SchemaDefinition` interface (moduleId, description, inputSchema, outputSchema, errorSchema, definitions, version, documentation, schemaUrl), `ResolvedSchema` interface (jsonSchema, schema TSchema, moduleId, direction), `SchemaValidationErrorDetail` and `SchemaValidationResult` interfaces, `LLMExtensions` interface, and `validationResultToError()` converter.
+
+- **Annotations** (`schema/annotations.ts`, ~67 lines) -- Conflict resolution layer for merging YAML-defined and code-defined module metadata. Exposes `mergeAnnotations()` (boolean annotation fields with YAML-wins precedence), `mergeExamples()` (YAML examples override code examples), and `mergeMetadata()` (shallow merge with YAML overrides). Consumes `ModuleAnnotations` and `ModuleExample` types from `module.ts`.
+
+- **SchemaLoader** (`schema/loader.ts`, ~271 lines) -- Primary entry point for the schema system. Manages YAML file loading via `js-yaml`, two-level caching (`_schemaCache` for raw definitions, `_modelCache` for resolved TypeBox pairs), strategy-based schema selection (`getSchema()` with `YamlFirst`/`NativeFirst`/`YamlOnly` behavior), and `$ref` resolution delegation to `RefResolver`. Contains `jsonSchemaToTypeBox()` as an exported function for recursive JSON Schema to TypeBox conversion.
+
+- **RefResolver** (`schema/ref-resolver.ts`, ~236 lines) -- `$ref` resolution engine following Algorithm A05. Supports local JSON pointers (`#/definitions/Foo`), relative file paths (`../shared.schema.yaml#/definitions/Bar`), `apcore://` canonical URIs (`apcore://module.id/definitions/Type`), and inline sentinel for self-referencing schemas. Implements circular reference detection via visited-set tracking and configurable max depth (default 32). Caches loaded files in `_fileCache`.
+
+- **SchemaValidator** (`schema/validator.ts`, ~83 lines) -- Runtime validation using TypeBox `Value.Check()`, `Value.Decode()`, and `Value.Errors()`. Constructor accepts `coerceTypes` boolean (default `true`). When coercion is enabled, uses `Value.Decode()` for type coercion; when disabled, uses strict `Value.Check()`. Exposes `validate()` (returns `SchemaValidationResult`), `validateInput()` and `validateOutput()` (return data or throw `SchemaValidationError`). Error details include JSON path, message, constraint type, expected schema, and actual value.
+
+- **SchemaExporter** (`schema/exporter.ts`, ~94 lines) -- Multi-format schema export for LLM provider integration. Dispatches on `ExportProfile` enum to four export methods: `exportMcp()` (MCP tool format with `readOnlyHint`/`destructiveHint`/`idempotentHint`/`openWorldHint` annotations), `exportOpenai()` (OpenAI function calling with strict mode, `additionalProperties: false`, all-required, LLM descriptions applied), `exportAnthropic()` (Anthropic tool use with `input_schema`, LLM descriptions, extensions stripped, optional `input_examples`), `exportGeneric()` (passthrough with raw input/output schemas and definitions).
+
+- **Strict Mode** (`schema/strict.ts`, ~129 lines) -- Schema transformation utilities for OpenAI strict-mode compliance (Algorithm A23). `toStrictSchema()` deep-copies, strips extensions, then applies strict conversion. `stripExtensions()` recursively removes all `x-` prefixed keys and `default` values. `applyLlmDescriptions()` replaces `description` with `x-llm-description` where both exist. Internal `convertToStrict()` sets `additionalProperties: false`, promotes all properties to required, and wraps optional properties with `null` union types.
+
+- **Barrel Export** (`schema/index.ts`, ~15 lines) -- Re-exports all public types, classes, and functions from the schema module.
+
+### Data Flow
+
+The schema system processes module schemas through this pipeline:
+
+1. **YAML Loading** -- `SchemaLoader.load()` reads `{moduleId}.schema.yaml` from disk, parses with `js-yaml`, extracts required fields (`input_schema`, `output_schema`, `description`), merges `definitions`/`$defs`, and caches the `SchemaDefinition`
+2. **Ref Resolution** -- `SchemaLoader.resolve()` delegates to `RefResolver.resolve()` which deep-copies the schema and recursively walks all nodes, resolving `$ref` pointers in-place with circular detection
+3. **TypeBox Generation** -- `jsonSchemaToTypeBox()` recursively converts the resolved JSON Schema dictionary to TypeBox `TSchema` objects (`Type.Object`, `Type.Array`, `Type.String`, `Type.Integer`, `Type.Number`, `Type.Boolean`, `Type.Null`, `Type.Union`, `Type.Intersect`, `Type.Literal`, `Type.Record`, `Type.Unknown`)
+4. **Strategy Selection** -- `SchemaLoader.getSchema()` applies the configured `SchemaStrategy` to choose between YAML-loaded and native (code-provided) TypeBox schemas, with fallback behavior per strategy
+5. **Validation** -- `SchemaValidator.validate()` checks runtime data against TypeBox schemas using `Value.Check()` (strict) or `Value.Decode()` (coercion), collecting errors via `Value.Errors()`
+6. **Export** -- `SchemaExporter.export()` transforms the `SchemaDefinition` to the target `ExportProfile` format, applying strict-mode transformations (OpenAI), LLM description substitution (OpenAI, Anthropic), extension stripping (Anthropic), and annotation mapping (MCP)
+
+### Technical Choices and Rationale
+
+- **TypeBox instead of Pydantic**: The Python apcore uses Pydantic for schema validation and `create_model()` for dynamic model generation. In TypeScript, TypeBox provides the same JSON Schema-based validation through `Value.Check()`/`Value.Decode()` with full TypeScript type inference. TypeBox schemas ARE valid JSON Schema objects, which eliminates a separate conversion layer and simplifies the `jsonSchemaToTypeBox()` function to a thin wrapper that produces TypeBox-tagged objects.
+
+- **`jsonSchemaToTypeBox()` instead of `create_model()`**: Pydantic's `create_model()` dynamically generates Python classes at runtime. The TypeScript equivalent maps JSON Schema types to TypeBox builder calls (`Type.Object`, `Type.String`, etc.) which return plain objects with a `[Kind]` symbol tag. This is cheaper than class instantiation and integrates naturally with TypeBox's `Value.*` validation functions.
+
+- **`js-yaml` for YAML parsing**: Standard YAML parsing library for Node.js. Used with `yaml.load()` for single-document loading. Synchronous file I/O via `readFileSync` is acceptable since schema loading is a startup-time operation.
+
+- **Two-level caching in SchemaLoader**: Separate caches for `SchemaDefinition` (raw YAML parse result) and `[ResolvedSchema, ResolvedSchema]` (resolved TypeBox pair) avoid redundant `$ref` resolution and TypeBox conversion on repeated lookups while allowing cache invalidation at each level independently.
+
+- **In-place mutation for `$ref` resolution**: The `RefResolver` deep-copies the schema first, then mutates in-place during resolution. This avoids creating intermediate copies at each `$ref` node while preserving the original schema. The visited-set tracking uses a fresh `Set` per `$ref` chain to allow the same definition to be referenced from multiple locations without false circular-detection positives.
+
+- **`JSON.parse(JSON.stringify())` for deep copy**: Used in `RefResolver` and `strict.ts` for deep cloning JSON-compatible schema objects. Suitable because schemas are always JSON-serializable (no functions, symbols, or circular references in the input).
+
+## Task Breakdown
+
+```mermaid
+graph TD
+    T1[types-and-annotations] --> T2[loader]
+    T1 --> T3[ref-resolver]
+    T1 --> T4[typebox-generation]
+    T1 --> T5[validator]
+    T3 --> T2
+    T4 --> T2
+    T5 --> T2
+    T1 --> T6[exporter]
+    T7[strict-mode] --> T6
+```
+
+| Task ID | Title | Estimated Time | Dependencies |
+|---------|-------|---------------|--------------|
+| types-and-annotations | Core interfaces, enums, and annotation merging | 2h | none |
+| loader | SchemaLoader with YAML loading, caching, strategy | 4h | types-and-annotations, ref-resolver, typebox-generation |
+| ref-resolver | RefResolver with $ref resolution and circular detection | 3h | types-and-annotations |
+| typebox-generation | jsonSchemaToTypeBox() recursive converter | 3h | types-and-annotations |
+| validator | SchemaValidator with TypeBox validation and coercion | 2h | types-and-annotations |
+| exporter | SchemaExporter with 4 export profiles | 3h | types-and-annotations, strict-mode |
+| strict-mode | toStrictSchema(), stripExtensions(), applyLlmDescriptions() | 2h | none |
+
+## Risks and Considerations
+
+- **TypeBox version compatibility**: The `Value.Decode()` API changed between TypeBox 0.32 and 0.34. The implementation targets `>= 0.34.0` where `Value.Decode()` performs coercion and returns the decoded value. Pinning the minimum version is essential.
+
+- **JSON Schema coverage gaps**: `jsonSchemaToTypeBox()` handles the most common JSON Schema constructs (`object`, `array`, `string`, `integer`, `number`, `boolean`, `null`, `enum`, `oneOf`, `anyOf`, `allOf`) but does not cover `if/then/else`, `not`, `patternProperties`, or `$dynamicRef`. Unsupported constructs fall through to `Type.Unknown()`.
+
+- **Synchronous file I/O**: `SchemaLoader` and `RefResolver` use `readFileSync` for YAML loading. This is acceptable for startup-time schema loading but would block the event loop if called during request handling. Future versions may need async variants.
+
+- **Strict-mode `null` wrapping**: `convertToStrict()` wraps optional properties with `[type, "null"]` arrays or `{ oneOf: [schema, { type: "null" }] }`. This matches OpenAI's strict mode requirements but may confuse validators that do not support type arrays.
+
+- **`apcore://` URI resolution**: The canonical URI scheme (`apcore://module.id/definitions/Type`) converts dots to path separators and appends `.schema.yaml`. This convention must be documented and consistently used across all schema files.
+
+## Acceptance Criteria
+
+- [x] `SchemaDefinition`, `ResolvedSchema`, `SchemaStrategy`, `ExportProfile` types are defined and exported
+- [x] `SchemaLoader.load()` reads YAML files, validates required fields, and caches results
+- [x] `SchemaLoader.getSchema()` applies `YamlFirst`/`NativeFirst`/`YamlOnly` strategy correctly
+- [x] `RefResolver.resolve()` handles local pointers, relative files, `apcore://` URIs, and nested `$ref` chains
+- [x] `RefResolver` detects circular references and raises `SchemaCircularRefError`
+- [x] `RefResolver` enforces max depth and raises on exceeded depth
+- [x] `jsonSchemaToTypeBox()` converts all supported JSON Schema types to TypeBox equivalents
+- [x] `jsonSchemaToTypeBox()` passes through constraint options (`minLength`, `maximum`, etc.)
+- [x] `SchemaValidator.validate()` returns `SchemaValidationResult` with detailed error paths
+- [x] `SchemaValidator` supports coercion mode (`Value.Decode`) and strict mode (`Value.Check`)
+- [x] `SchemaExporter` produces correct MCP, OpenAI, Anthropic, and Generic export formats
+- [x] `toStrictSchema()` sets `additionalProperties: false`, makes all properties required, wraps optionals with null
+- [x] `stripExtensions()` removes all `x-` keys and `default` values recursively
+- [x] `applyLlmDescriptions()` replaces `description` with `x-llm-description` where present
+- [x] `mergeAnnotations()`, `mergeExamples()`, `mergeMetadata()` merge YAML/code metadata with correct precedence
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## References
+
+- `src/schema/types.ts` -- Type definitions and enums
+- `src/schema/annotations.ts` -- Annotation conflict resolution
+- `src/schema/loader.ts` -- SchemaLoader and jsonSchemaToTypeBox()
+- `src/schema/ref-resolver.ts` -- RefResolver
+- `src/schema/validator.ts` -- SchemaValidator
+- `src/schema/exporter.ts` -- SchemaExporter
+- `src/schema/strict.ts` -- Strict-mode utilities
+- `src/schema/index.ts` -- Barrel export
+- `tests/schema/test-loader.test.ts` -- Loader and TypeBox generation tests
+- `tests/schema/test-validator.test.ts` -- Validator tests
+- `tests/schema/test-ref-resolver.test.ts` -- RefResolver tests
+- `tests/schema/test-strict.test.ts` -- Strict-mode tests

package/planning/schema-system/state.json

@@ -0,0 +1,98 @@
+{
+  "feature": "schema-system",
+  "created": "2026-02-16T00:00:00Z",
+  "updated": "2026-02-16T00:00:00Z",
+  "status": "completed",
+  "execution_order": [
+    "types-and-annotations",
+    "loader",
+    "ref-resolver",
+    "typebox-generation",
+    "validator",
+    "exporter",
+    "strict-mode"
+  ],
+  "progress": {
+    "total_tasks": 7,
+    "completed": 7,
+    "in_progress": 0,
+    "pending": 0
+  },
+  "tasks": [
+    {
+      "id": "types-and-annotations",
+      "file": "tasks/types-and-annotations.md",
+      "title": "Core Interfaces, Enums, and Annotation Merging",
+      "status": "completed",
+      "started_at": "2026-02-16T08:00:00Z",
+      "completed_at": "2026-02-16T09:30:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "loader",
+      "file": "tasks/loader.md",
+      "title": "SchemaLoader with YAML Loading, Caching, and Strategy Selection",
+      "status": "completed",
+      "started_at": "2026-02-16T09:30:00Z",
+      "completed_at": "2026-02-16T12:30:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "ref-resolver",
+      "file": "tasks/ref-resolver.md",
+      "title": "RefResolver with $ref Resolution and Circular Detection",
+      "status": "completed",
+      "started_at": "2026-02-16T12:30:00Z",
+      "completed_at": "2026-02-16T15:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "typebox-generation",
+      "file": "tasks/typebox-generation.md",
+      "title": "jsonSchemaToTypeBox() Recursive Converter",
+      "status": "completed",
+      "started_at": "2026-02-16T15:00:00Z",
+      "completed_at": "2026-02-16T17:30:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "validator",
+      "file": "tasks/validator.md",
+      "title": "SchemaValidator with TypeBox Validation and Coercion",
+      "status": "completed",
+      "started_at": "2026-02-16T17:30:00Z",
+      "completed_at": "2026-02-16T19:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "exporter",
+      "file": "tasks/exporter.md",
+      "title": "SchemaExporter with 4 Export Profiles",
+      "status": "completed",
+      "started_at": "2026-02-16T19:00:00Z",
+      "completed_at": "2026-02-16T21:30:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "strict-mode",
+      "file": "tasks/strict-mode.md",
+      "title": "Strict-Mode Transformations (toStrictSchema, stripExtensions, applyLlmDescriptions)",
+      "status": "completed",
+      "started_at": "2026-02-16T21:30:00Z",
+      "completed_at": "2026-02-16T23:00:00Z",
+      "assignee": null,
+      "commits": []
+    }
+  ],
+  "metadata": {
+    "source_doc": "planning/features/schema-system.md",
+    "created_by": "code-forge",
+    "version": "1.0"
+  }
+}

package/planning/schema-system/tasks/exporter.md

@@ -0,0 +1,153 @@
+# Task: SchemaExporter
+
+## Goal
+
+Implement the `SchemaExporter` class that converts `SchemaDefinition` objects to platform-specific export formats for four LLM providers: MCP (Model Context Protocol), OpenAI (function calling with strict mode), Anthropic (tool use with examples), and Generic (passthrough for non-LLM consumers).
+
+## Files Involved
+
+- `src/schema/exporter.ts` -- `SchemaExporter` class
+- `src/schema/strict.ts` -- Consumed for `toStrictSchema()`, `applyLlmDescriptions()`, `stripExtensions()`
+- `src/schema/types.ts` -- Consumed for `ExportProfile`, `SchemaDefinition`
+- `src/module.ts` -- Consumed for `ModuleAnnotations`, `ModuleExample`
+
+## Steps
+
+### 1. Implement export() dispatcher
+
+Route to the correct export method based on `ExportProfile` enum value.
+
+```typescript
+export class SchemaExporter {
+  export(
+    schemaDef: SchemaDefinition,
+    profile: ExportProfile,
+    annotations?: ModuleAnnotations | null,
+    examples?: ModuleExample[] | null,
+    name?: string | null,
+  ): Record<string, unknown> {
+    if (profile === ExportProfile.MCP) return this.exportMcp(schemaDef, annotations, name);
+    if (profile === ExportProfile.OpenAI) return this.exportOpenai(schemaDef);
+    if (profile === ExportProfile.Anthropic) return this.exportAnthropic(schemaDef, examples);
+    return this.exportGeneric(schemaDef);
+  }
+}
+```
+
+TDD: Test dispatch routes to correct method for each profile.
+
+### 2. Implement exportMcp()
+
+Produce MCP tool format with `name`, `description`, `inputSchema`, and `annotations` object mapping module annotations to MCP hint fields.
+
+```typescript
+exportMcp(
+  schemaDef: SchemaDefinition,
+  annotations?: ModuleAnnotations | null,
+  name?: string | null,
+): Record<string, unknown> {
+  return {
+    name: name ?? schemaDef.moduleId,
+    description: schemaDef.description,
+    inputSchema: schemaDef.inputSchema,
+    annotations: {
+      readOnlyHint: annotations?.readonly ?? false,
+      destructiveHint: annotations?.destructive ?? false,
+      idempotentHint: annotations?.idempotent ?? false,
+      openWorldHint: annotations?.openWorld ?? true,
+    },
+  };
+}
+```
+
+TDD: Test MCP output includes correct annotation hints. Test custom `name` override. Test default `openWorldHint` is `true`.
+
+### 3. Implement exportOpenai()
+
+Produce OpenAI function-calling format with strict mode. Deep-copy input schema, apply LLM descriptions, convert to strict schema, wrap in `{ type: "function", function: { name, description, parameters, strict: true } }`. Module ID dots are replaced with underscores for the function name.
+
+```typescript
+exportOpenai(schemaDef: SchemaDefinition): Record<string, unknown> {
+  const schema = deepCopy(schemaDef.inputSchema);
+  applyLlmDescriptions(schema);
+  const strictSchema = toStrictSchema(schema);
+  return {
+    type: 'function',
+    function: {
+      name: schemaDef.moduleId.replace(/\./g, '_'),
+      description: schemaDef.description,
+      parameters: strictSchema,
+      strict: true,
+    },
+  };
+}
+```
+
+TDD: Test function name replaces dots with underscores. Test `strict: true` is set. Test `additionalProperties: false` is present in parameters.
+
+### 4. Implement exportAnthropic()
+
+Produce Anthropic tool-use format. Deep-copy input schema, apply LLM descriptions, strip extensions. Include `input_examples` from module examples if available.
+
+```typescript
+exportAnthropic(
+  schemaDef: SchemaDefinition,
+  examples?: ModuleExample[] | null,
+): Record<string, unknown> {
+  const schema = deepCopy(schemaDef.inputSchema);
+  applyLlmDescriptions(schema);
+  stripExtensions(schema);
+  const result: Record<string, unknown> = {
+    name: schemaDef.moduleId.replace(/\./g, '_'),
+    description: schemaDef.description,
+    input_schema: schema,
+  };
+  if (examples && examples.length > 0) {
+    result['input_examples'] = examples.map((ex) => ex.inputs);
+  }
+  return result;
+}
+```
+
+TDD: Test `x-` extensions are removed from output. Test examples are included when provided. Test examples are omitted when empty.
+
+### 5. Implement exportGeneric()
+
+Passthrough format with all schema data for non-LLM consumers.
+
+```typescript
+exportGeneric(schemaDef: SchemaDefinition): Record<string, unknown> {
+  return {
+    module_id: schemaDef.moduleId,
+    description: schemaDef.description,
+    input_schema: schemaDef.inputSchema,
+    output_schema: schemaDef.outputSchema,
+    definitions: schemaDef.definitions,
+  };
+}
+```
+
+TDD: Test all fields are present including `output_schema` and `definitions`.
+
+## Acceptance Criteria
+
+- [x] `export()` dispatches to the correct profile method
+- [x] MCP format includes `name`, `description`, `inputSchema`, and annotation hints
+- [x] MCP format supports custom `name` override via parameter
+- [x] OpenAI format wraps schema in `{ type: "function", function: { ... } }` with `strict: true`
+- [x] OpenAI format applies LLM descriptions and strict-mode transformations
+- [x] OpenAI format replaces dots with underscores in function name
+- [x] Anthropic format applies LLM descriptions and strips extensions
+- [x] Anthropic format includes `input_examples` when examples are provided
+- [x] Generic format passes through all schema data including `output_schema` and `definitions`
+- [x] No export method mutates the original `SchemaDefinition`
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- types-and-annotations (for `ExportProfile`, `SchemaDefinition`)
+- strict-mode (for `toStrictSchema()`, `stripExtensions()`, `applyLlmDescriptions()`)
+
+## Estimated Time
+
+3 hours

package/planning/schema-system/tasks/loader.md

@@ -0,0 +1,106 @@
+# Task: SchemaLoader
+
+## Goal
+
+Implement the `SchemaLoader` class as the primary entry point for the schema system. It loads YAML schema files from disk, resolves `$ref` references via `RefResolver`, converts JSON Schema dictionaries to TypeBox `TSchema` objects via `jsonSchemaToTypeBox()`, and supports three schema resolution strategies with two-level caching.
+
+## Files Involved
+
+- `src/schema/loader.ts` -- `SchemaLoader` class and `jsonSchemaToTypeBox()` function
+- `src/schema/ref-resolver.ts` -- Consumed for `$ref` resolution
+- `src/schema/types.ts` -- Consumed for `SchemaDefinition`, `ResolvedSchema`, `SchemaStrategy`
+- `tests/schema/test-loader.test.ts` -- Unit tests for `jsonSchemaToTypeBox()` and SchemaLoader
+
+## Steps
+
+### 1. Implement SchemaLoader constructor
+
+Accept `Config` and optional `schemasDir`. Resolve the schemas directory from config (`schema.root`, default `./schemas`). Create a `RefResolver` with `schema.max_ref_depth` (default 32). Initialize empty caches.
+
+```typescript
+export class SchemaLoader {
+  private _config: Config;
+  private _schemasDir: string;
+  private _resolver: RefResolver;
+  private _schemaCache: Map<string, SchemaDefinition> = new Map();
+  private _modelCache: Map<string, [ResolvedSchema, ResolvedSchema]> = new Map();
+
+  constructor(config: Config, schemasDir?: string | null) {
+    this._config = config;
+    this._schemasDir = schemasDir
+      ? resolve(schemasDir)
+      : resolve(config.get('schema.root', './schemas') as string);
+    const maxDepth = config.get('schema.max_ref_depth', 32) as number;
+    this._resolver = new RefResolver(this._schemasDir, maxDepth);
+  }
+}
+```
+
+TDD: Verify constructor sets `_schemasDir` from explicit param and from config fallback.
+
+### 2. Implement load() method
+
+Read YAML file at `{schemasDir}/{moduleId.replace('.','/')}.schema.yaml`. Parse with `js-yaml`. Validate required fields (`input_schema`, `output_schema`, `description`). Merge `definitions` and `$defs`. Cache and return `SchemaDefinition`.
+
+TDD: Test successful load, missing file (`SchemaNotFoundError`), invalid YAML (`SchemaParseError`), missing required fields (`SchemaParseError`), and cache hit on second call.
+
+### 3. Implement resolve() method
+
+Delegate to `RefResolver.resolve()` for both input and output schemas. Convert resolved JSON Schema to TypeBox via `jsonSchemaToTypeBox()`. Return `[ResolvedSchema, ResolvedSchema]` tuple.
+
+TDD: Test resolution of a schema with `$ref` pointers produces valid TypeBox schemas.
+
+### 4. Implement getSchema() with strategy selection
+
+Parse the strategy from config string (`schema.strategy`, default `yaml_first`). Convert snake_case to PascalCase for enum lookup. Apply strategy logic:
+- `YamlFirst`: Try YAML, fall back to native if `SchemaNotFoundError` and native schemas provided
+- `NativeFirst`: Use native if provided, else fall back to YAML
+- `YamlOnly`: YAML only, no fallback
+
+Cache and return result.
+
+```typescript
+getSchema(
+  moduleId: string,
+  nativeInputSchema?: TSchema | null,
+  nativeOutputSchema?: TSchema | null,
+): [ResolvedSchema, ResolvedSchema]
+```
+
+TDD: Test each strategy path, including fallback behavior and `SchemaNotFoundError` propagation.
+
+### 5. Implement _wrapNative() helper
+
+Wrap native TypeBox schemas into `ResolvedSchema` objects with `jsonSchema` set to the TypeBox schema cast as `Record<string, unknown>`.
+
+TDD: Verify wrapped native schemas have correct `direction` and `moduleId`.
+
+### 6. Implement clearCache()
+
+Clear all three caches: `_schemaCache`, `_modelCache`, and `_resolver.clearCache()`.
+
+TDD: Verify cache is cleared and subsequent loads re-read from disk.
+
+## Acceptance Criteria
+
+- [x] `SchemaLoader.load()` reads and parses YAML schema files correctly
+- [x] `SchemaLoader.load()` throws `SchemaNotFoundError` for missing files
+- [x] `SchemaLoader.load()` throws `SchemaParseError` for invalid YAML or missing required fields
+- [x] `SchemaLoader.load()` caches `SchemaDefinition` on first load
+- [x] `SchemaLoader.resolve()` produces `[ResolvedSchema, ResolvedSchema]` with TypeBox schemas
+- [x] `SchemaLoader.getSchema()` applies `YamlFirst` strategy with native fallback
+- [x] `SchemaLoader.getSchema()` applies `NativeFirst` strategy with YAML fallback
+- [x] `SchemaLoader.getSchema()` applies `YamlOnly` strategy without fallback
+- [x] `SchemaLoader.getSchema()` caches resolved schema pairs
+- [x] `SchemaLoader.clearCache()` invalidates all caches
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- types-and-annotations (for `SchemaDefinition`, `ResolvedSchema`, `SchemaStrategy`)
+- ref-resolver (for `RefResolver`)
+- typebox-generation (for `jsonSchemaToTypeBox()`)
+
+## Estimated Time
+
+4 hours

package/planning/schema-system/tasks/ref-resolver.md

@@ -0,0 +1,133 @@
+# Task: RefResolver
+
+## Goal
+
+Implement the `RefResolver` class for resolving `$ref` pointers in JSON Schema documents. Supports local JSON pointers, relative file paths, `apcore://` canonical URIs, nested `$ref` chains, sibling key merging, circular reference detection, and configurable max depth.
+
+## Files Involved
+
+- `src/schema/ref-resolver.ts` -- `RefResolver` class
+- `src/errors.ts` -- `SchemaCircularRefError`, `SchemaNotFoundError`, `SchemaParseError`
+- `tests/schema/test-ref-resolver.test.ts` -- Unit tests
+
+## Steps
+
+### 1. Implement constructor and file cache
+
+```typescript
+export class RefResolver {
+  private _schemasDir: string;
+  private _maxDepth: number;
+  private _fileCache: Map<string, Record<string, unknown>> = new Map();
+
+  constructor(schemasDir: string, maxDepth: number = 32) {
+    this._schemasDir = resolve(schemasDir);
+    this._maxDepth = maxDepth;
+  }
+}
+```
+
+TDD: Verify constructor resolves `schemasDir` to absolute path and stores `maxDepth`.
+
+### 2. Implement resolve() entry point
+
+Deep-copy the input schema. Set it as the inline sentinel (`__inline__`) in the file cache. Walk all nodes via `_resolveNode()`. Clean up sentinel on completion.
+
+```typescript
+resolve(schema: Record<string, unknown>, currentFile?: string | null): Record<string, unknown> {
+  const result = deepCopy(schema);
+  this._fileCache.set(INLINE_SENTINEL, result);
+  try {
+    this._resolveNode(result, currentFile ?? null, new Set(), 0);
+  } finally {
+    this._fileCache.delete(INLINE_SENTINEL);
+  }
+  return result;
+}
+```
+
+TDD: Test that schemas without `$ref` pass through unchanged (deep-copied).
+
+### 3. Implement _parseRef() for $ref URI parsing
+
+Handle four `$ref` formats:
+- Local pointer: `#/definitions/Foo` -- resolve against current file or inline sentinel
+- `apcore://` URI: `apcore://module.id/definitions/Type` -- convert dots to path separators, append `.schema.yaml`
+- File with pointer: `../shared.yaml#/definitions/Bar` -- resolve file relative to current file or schemas dir
+- File only: `../shared.yaml` -- resolve file with empty pointer
+
+```typescript
+private _parseRef(refString: string, currentFile: string | null): [string, string]
+```
+
+TDD: Test each format with expected `[filePath, jsonPointer]` output.
+
+### 4. Implement _resolveJsonPointer()
+
+Walk the JSON pointer segments (split on `/`, skip empty leading segment, unescape `~1` -> `/` and `~0` -> `~`). Throw `SchemaNotFoundError` if any segment is not found.
+
+TDD: Test successful pointer traversal, nested paths, and missing segment error.
+
+### 5. Implement resolveRef() for single $ref resolution
+
+Check visited set for circular detection. Check depth against `_maxDepth`. Parse the `$ref` string. Load the target file. Resolve the JSON pointer within the document. Deep-copy the target. Merge sibling keys if present. Recursively resolve nested `$ref` in the result.
+
+TDD: Test basic `$ref` resolution, sibling key merging, nested `$ref` chains.
+
+### 6. Implement _resolveNode() recursive walker
+
+Walk objects and arrays. When a `$ref` key is found, extract sibling keys, call `resolveRef()`, then replace the node contents in-place. For non-`$ref` objects and arrays, recurse into children.
+
+TDD: Test resolution of schemas with multiple `$ref` at different nesting levels.
+
+### 7. Implement circular reference detection
+
+The visited set tracks resolved `$ref` strings within a single chain. A fresh `Set` copy is used for each branch of the tree to avoid false positives when the same definition is referenced from multiple independent locations.
+
+TDD: Test that `A -> B -> A` circular chain throws `SchemaCircularRefError`. Test that the same definition referenced from two independent properties does NOT throw.
+
+### 8. Implement max depth enforcement
+
+When `depth >= _maxDepth`, throw `SchemaCircularRefError` with a descriptive message including the ref string and max depth value.
+
+TDD: Test with `maxDepth = 2` and a 3-deep chain.
+
+### 9. Implement _loadFile() with caching
+
+Load YAML files via `readFileSync` and `yaml.load()`. Cache parsed results in `_fileCache`. Handle empty files (return `{}`), non-mapping files (`SchemaParseError`), and missing files (`SchemaNotFoundError`).
+
+TDD: Test file loading, caching (second call returns same object), and error cases.
+
+### 10. Implement clearCache()
+
+```typescript
+clearCache(): void {
+  this._fileCache.clear();
+}
+```
+
+TDD: Verify cache is cleared.
+
+## Acceptance Criteria
+
+- [x] Local `#/definitions/Foo` pointers resolve correctly
+- [x] Relative file paths with pointers (`../shared.yaml#/definitions/Bar`) resolve correctly
+- [x] `apcore://module.id/definitions/Type` canonical URIs resolve to correct file paths
+- [x] Nested `$ref` chains (ref pointing to another ref) resolve fully
+- [x] Sibling keys alongside `$ref` are merged into the resolved result
+- [x] Circular references (`A -> B -> A`) throw `SchemaCircularRefError`
+- [x] Max depth exceeded throws `SchemaCircularRefError` with descriptive message
+- [x] Schemas without `$ref` pass through as deep copies
+- [x] Missing files throw `SchemaNotFoundError`
+- [x] Invalid YAML throws `SchemaParseError`
+- [x] File cache prevents redundant disk reads
+- [x] `clearCache()` invalidates all cached files
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- types-and-annotations (for error types from `errors.ts`)
+
+## Estimated Time
+
+3 hours