universal-llm-client 4.0.0 → 4.2.0

package/src/tests/structured-output.test.ts

@@ -0,0 +1,1450 @@
+/**
+ * Tests for structured-output.ts — Core structured output types
+ * 
+ * Validates assertions:
+ * - VAL-SCHEMA-001: Zod Schema Input with Type Inference
+ * - VAL-SCHEMA-003: Raw JSON Schema Input
+ * - VAL-SCHEMA-005: Validation Error with Raw Output
+ * - VAL-SCHEMA-007: tryParseStructured Returns Result Object
+ */
+import { describe, it, expect } from 'bun:test';
+import { z } from 'zod';
+import {
+    StructuredOutputError,
+    type StructuredOutputOptions,
+    type StructuredOutputResult,
+    type StructuredOutputSuccess,
+    type StructuredOutputFailure,
+    type JSONSchema,
+    isStructuredOutputSuccess,
+    isStructuredOutputFailure,
+    // Schema conversion functions
+    normalizeJsonSchema,
+    convertToProviderSchema,
+    stripUnsupportedFeatures,
+    // Validation functions
+    parseStructured,
+    tryParseStructured,
+    validateStructuredOutput,
+    stripJsonFences,
+} from '../structured-output.js';
+import {  fromZod } from '../zod-adapter.js';
+
+// ============================================================================
+// Test Schemas
+// ============================================================================
+
+const UserSchema = z.object({
+    name: z.string(),
+    age: z.number(),
+    email: z.string().email().optional(),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+// ============================================================================
+// StructuredOutputError Tests
+// ============================================================================
+
+describe('StructuredOutputError', () => {
+    it('extends Error class', () => {
+        const error = new StructuredOutputError('Validation failed', {
+            rawOutput: '{"name": 123}',
+        });
+        expect(error instanceof Error).toBe(true);
+    });
+
+    it('has rawOutput property', () => {
+        const error = new StructuredOutputError('Validation failed', {
+            rawOutput: '{"invalid": "json"}',
+        });
+        expect(error.rawOutput).toBe('{"invalid": "json"}');
+    });
+
+    it('has cause property for Zod validation errors', () => {
+        const zodError = new z.ZodError([
+            { code: 'invalid_type', expected: 'string', path: ['name'], message: 'Invalid input: expected string, received number' },
+        ]);
+        const error = new StructuredOutputError('Validation failed', {
+            rawOutput: '{"name": 123}',
+            cause: zodError,
+        });
+        expect(error.cause).toBe(zodError);
+    });
+
+    it('has optional cause property', () => {
+        const error = new StructuredOutputError('Validation failed', {
+            rawOutput: 'not json at all',
+        });
+        expect(error.cause).toBeUndefined();
+    });
+
+    it('captures stack trace', () => {
+        const error = new StructuredOutputError('Validation failed', {
+            rawOutput: '{}',
+        });
+        expect(error.stack).toBeDefined();
+        // Stack trace should contain the error message and show where it was thrown
+        expect(error.stack).toContain('Validation failed');
+    });
+
+    it('message includes raw output preview', () => {
+        const error = new StructuredOutputError('Validation failed', {
+            rawOutput: '{"long": "output that should be truncated in preview"}',
+        });
+        expect(error.message).toContain('Validation failed');
+    });
+});
+
+// ============================================================================
+// StructuredOutputOptions Tests
+// ============================================================================
+
+describe('StructuredOutputOptions', () => {
+    it('accepts Zod schema config', () => {
+        const config = fromZod(UserSchema);
+        const options: StructuredOutputOptions<User> = {
+            schemaConfig: config,
+        };
+        expect(options.schemaConfig).toBe(config);
+    });
+
+    it('accepts raw JSON Schema', () => {
+        const jsonSchema: JSONSchema = {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                age: { type: 'number' },
+            },
+            required: ['name', 'age'],
+        };
+        const options: StructuredOutputOptions<User> = {
+            jsonSchema,
+        };
+        expect(options.jsonSchema).toBe(jsonSchema);
+    });
+
+    it('accepts optional name for LLM guidance', () => {
+        const options: StructuredOutputOptions<User> = {
+            schemaConfig: fromZod(UserSchema, { name: 'User' }),
+        };
+        expect(options.schemaConfig?.name).toBe('User');
+    });
+
+    it('accepts optional description for LLM guidance', () => {
+        const options: StructuredOutputOptions<User> = {
+            schemaConfig: fromZod(UserSchema, { name: 'User', description: 'A user object with name and age' }),
+        };
+        expect(options.schemaConfig?.description).toBe('A user object with name and age');
+    });
+
+    it('accepts both schema and name/description', () => {
+        const config = fromZod(UserSchema);
+        const options: StructuredOutputOptions<User> = {
+            schemaConfig: config,
+            name: 'User',
+            description: 'User schema',
+        };
+        expect(options.schemaConfig).toBe(config);
+        expect(options.name).toBe('User');
+        expect(options.description).toBe('User schema');
+    });
+});
+
+// ============================================================================
+// StructuredOutputResult Tests
+// ============================================================================
+
+describe('StructuredOutputResult', () => {
+    describe('Success case', () => {
+        it('has ok: true and value property', () => {
+            const result: StructuredOutputSuccess<User> = {
+                ok: true,
+                value: { name: 'John', age: 30 },
+            };
+            expect(result.ok).toBe(true);
+            expect(result.value).toEqual({ name: 'John', age: 30 });
+        });
+
+        it('narrows type correctly', () => {
+            const result: StructuredOutputResult<User> = {
+                ok: true,
+                value: { name: 'Jane', age: 25 },
+            };
+            if (result.ok) {
+                // TypeScript should infer result.value is User
+                const name: string = result.value.name;
+                expect(name).toBe('Jane');
+            }
+        });
+    });
+
+    describe('Failure case', () => {
+        it('has ok: false, error, and rawOutput properties', () => {
+            const zodError = new z.ZodError([
+                { code: 'invalid_type', expected: 'string', path: ['name'], message: 'Invalid input: expected string, received number' },
+            ]);
+            const result: StructuredOutputFailure<User> = {
+                ok: false,
+                error: new StructuredOutputError('Validation failed', {
+                    rawOutput: '{"name": 123}',
+                    cause: zodError,
+                }),
+                rawOutput: '{"name": 123}',
+            };
+            expect(result.ok).toBe(false);
+            expect(result.error).toBeInstanceOf(StructuredOutputError);
+            expect(result.rawOutput).toBe('{"name": 123}');
+        });
+
+        it('narrows type correctly', () => {
+            const result: StructuredOutputResult<User> = {
+                ok: false,
+                error: new StructuredOutputError('Invalid JSON', {
+                    rawOutput: 'not json',
+                }),
+                rawOutput: 'not json',
+            };
+            if (!result.ok) {
+                // TypeScript should infer result.error and result.rawOutput
+                const errorMessage: string = result.error.message;
+                const raw: string = result.rawOutput;
+                expect(errorMessage).toContain('Invalid JSON');
+                expect(raw).toBe('not json');
+            }
+        });
+    });
+});
+
+// ============================================================================
+// Type Guard Tests
+// ============================================================================
+
+describe('isStructuredOutputSuccess', () => {
+    it('returns true for success result', () => {
+        const result: StructuredOutputResult<User> = {
+            ok: true,
+            value: { name: 'Alice', age: 28 },
+        };
+        expect(isStructuredOutputSuccess(result)).toBe(true);
+    });
+
+    it('returns false for failure result', () => {
+        const result: StructuredOutputResult<User> = {
+            ok: false,
+            error: new StructuredOutputError('Failed', {
+                rawOutput: '{}',
+            }),
+            rawOutput: '{}',
+        };
+        expect(isStructuredOutputSuccess(result)).toBe(false);
+    });
+});
+
+// ============================================================================
+// Type Inference Tests
+// ============================================================================
+
+describe('Type Inference (VAL-SCHEMA-001)', () => {
+    it('infers type from Zod schema correctly', () => {
+        // This test ensures TypeScript infers the correct type
+        const options: StructuredOutputOptions<User> = {
+            schemaConfig: fromZod(UserSchema),
+        };
+        
+        // TypeScript compilation is the test - if type is wrong, this won't compile
+        type InferredType = z.infer<typeof UserSchema>;
+        const _typeCheck: InferredType = { name: 'Test', age: 0 };
+        
+        expect(options.schemaConfig).toBeDefined();
+    });
+
+    it('structured output result type narrows correctly', () => {
+        // Test that TypeScript correctly narrows the union type
+        const successResult: StructuredOutputResult<User> = {
+            ok: true,
+            value: { name: 'Bob', age: 35 },
+        };
+        
+        const failureResult: StructuredOutputResult<User> = {
+            ok: false,
+            error: new StructuredOutputError('Error', { rawOutput: '{}' }),
+            rawOutput: '{}',
+        };
+        
+        // TypeScript narrow check - these should compile
+        if (successResult.ok) {
+            const name: string = successResult.value.name;
+            expect(name).toBe('Bob');
+        }
+        
+        if (!failureResult.ok) {
+            const raw: string = failureResult.rawOutput;
+            expect(raw).toBe('{}');
+        }
+    });
+});
+
+// ============================================================================
+// JSON Schema Input Tests (VAL-SCHEMA-003)
+// ============================================================================
+
+describe('Raw JSON Schema Input', () => {
+    it('accepts JSONSchema object without Zod', () => {
+        const jsonSchema: JSONSchema = {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                count: { type: 'integer' },
+            },
+            required: ['id'],
+        };
+        
+        const options: StructuredOutputOptions<{ id: string; count?: number }> = {
+            jsonSchema,
+        };
+        
+        expect(options.jsonSchema).toEqual(jsonSchema);
+    });
+
+    it('allows both schema and jsonSchema to be specified (schema takes precedence)', () => {
+        const jsonSchema: JSONSchema = {
+            type: 'object',
+            properties: {
+                value: { type: 'number' },
+            },
+        };
+        
+        const options: StructuredOutputOptions<{ value: number }> = {
+            schemaConfig: fromZod(z.object({ value: z.number() })),
+            jsonSchema,
+        };
+        
+        // Both can be set, implementation will use schema for validation
+        expect(options.schemaConfig).toBeDefined();
+        expect(options.jsonSchema).toBeDefined();
+    });
+});
+
+// ============================================================================
+// Schema Conversion Tests (VAL-SCHEMA-002)
+// ============================================================================
+
+describe('Schema Conversion (VAL-SCHEMA-002)', () => {
+    describe('zodToJsonSchema', () => {
+        it('converts Zod string schema to JSON Schema', () => {
+            const stringSchema = z.string();
+            const jsonSchema = fromZod(stringSchema).jsonSchema;
+            
+            expect(jsonSchema.type).toBe('string');
+        });
+
+        it('converts Zod number schema to JSON Schema', () => {
+            const numberSchema = z.number();
+            const jsonSchema = fromZod(numberSchema).jsonSchema;
+            
+            expect(jsonSchema.type).toBe('number');
+        });
+
+        it('converts Zod boolean schema to JSON Schema', () => {
+            const boolSchema = z.boolean();
+            const jsonSchema = fromZod(boolSchema).jsonSchema;
+            
+            expect(jsonSchema.type).toBe('boolean');
+        });
+
+        it('converts Zod object schema with required properties', () => {
+            const objectSchema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            const jsonSchema = fromZod(objectSchema).jsonSchema;
+            
+            expect(jsonSchema.type).toBe('object');
+            expect(jsonSchema.properties).toBeDefined();
+            expect(jsonSchema.properties?.['name']).toEqual({ type: 'string' });
+            expect(jsonSchema.properties?.['age']).toEqual({ type: 'number' });
+            expect(jsonSchema.required).toEqual(['name', 'age']);
+        });
+
+        it('converts Zod object schema with optional properties', () => {
+            const objectSchema = z.object({
+                name: z.string(),
+                email: z.string().optional(),
+            });
+            const jsonSchema = fromZod(objectSchema).jsonSchema;
+            
+            expect(jsonSchema.type).toBe('object');
+            expect(jsonSchema.required).toEqual(['name']);
+            expect(jsonSchema.properties?.['name']).toEqual({ type: 'string' });
+            expect(jsonSchema.properties?.['email']).toEqual({ type: 'string' });
+        });
+
+        it('converts nested Zod object schema', () => {
+            const nestedAddressSchema = z.object({
+                city: z.string(),
+                country: z.string(),
+            });
+            const personSchema = z.object({
+                name: z.string(),
+                address: nestedAddressSchema,
+            });
+            const jsonSchema = fromZod(personSchema).jsonSchema;
+            
+            expect(jsonSchema.type).toBe('object');
+            // zod-to-json-schema adds additionalProperties: false by default
+            const addressProp = jsonSchema.properties?.['address'] as JSONSchema;
+            expect(addressProp.type).toBe('object');
+            expect(addressProp.properties?.['city']).toEqual({ type: 'string' });
+            expect(addressProp.properties?.['country']).toEqual({ type: 'string' });
+            expect(addressProp.required).toEqual(['city', 'country']);
+        });
+    });
+
+    describe('normalizeJsonSchema', () => {
+        it('passes through JSON Schema without modification when not needed', () => {
+            const input: JSONSchema = {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    count: { type: 'number' },
+                },
+                required: ['name'],
+            };
+            
+            const result = normalizeJsonSchema(input);
+            
+            expect(result.type).toBe('object');
+            expect(result.properties).toEqual(input.properties);
+            expect(result.required).toEqual(['name']);
+        });
+
+        it('preserves description in JSON Schema', () => {
+            const input: JSONSchema = {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'User name' },
+                },
+                description: 'A user object',
+            };
+            
+            const result = normalizeJsonSchema(input);
+            
+            expect(result.description).toBe('A user object');
+            expect(result.properties?.['name']?.description).toBe('User name');
+        });
+    });
+});
+
+// ============================================================================
+// Schema Name/Description Tests (VAL-SCHEMA-004)
+// ============================================================================
+
+describe('Schema Name and Description (VAL-SCHEMA-004)', () => {
+    describe('convertToProviderSchema', () => {
+        it('includes schema name in OpenAI-compatible format', () => {
+            const schema = z.object({ name: z.string() });
+            const options: StructuredOutputOptions<{ name: string }> = {
+                schemaConfig: fromZod(schema, { name: 'User', description: 'A user object' }),
+            };
+            
+            const result = convertToProviderSchema('openai', options);
+            
+            expect(result.name).toBe('User');
+            expect(result.description).toBe('A user object');
+        });
+
+        it('works without name/description (optional)', () => {
+            const schema = z.object({ name: z.string() });
+            const options: StructuredOutputOptions<{ name: string }> = {
+                schemaConfig: fromZod(schema),
+            };
+            
+            const result = convertToProviderSchema('openai', options);
+            
+            expect(result.schema).toBeDefined();
+            expect(result.schema.type).toBe('object');
+        });
+
+        it('generates default name if not provided for providers that require it', () => {
+            const schema = z.object({ value: z.number() });
+            const options: StructuredOutputOptions<{ value: number }> = {
+                schemaConfig: fromZod(schema),
+            };
+            
+            const result = convertToProviderSchema('openai', options);
+            
+            // Should have a name, either provided or auto-generated
+            expect(result.name).toBeDefined();
+            expect(typeof result.name).toBe('string');
+        });
+    });
+});
+
+// ============================================================================
+// Enum Schema Tests (VAL-SCHEMA-008)
+// ============================================================================
+
+describe('Schema with Enums (VAL-SCHEMA-008)', () => {
+    it('converts Zod enum to JSON Schema with enum constraint', () => {
+        const statusSchema = z.enum(['active', 'inactive', 'pending']);
+        const jsonSchema = fromZod(statusSchema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('string');
+        expect(jsonSchema.enum).toEqual(['active', 'inactive', 'pending']);
+    });
+
+    it('converts Zod native enum to JSON Schema', () => {
+        enum Color {
+            Red = 'red',
+            Green = 'green',
+            Blue = 'blue',
+        }
+        const colorSchema = z.nativeEnum(Color);
+        const jsonSchema = fromZod(colorSchema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('string');
+        expect(jsonSchema.enum).toContain('red');
+        expect(jsonSchema.enum).toContain('green');
+        expect(jsonSchema.enum).toContain('blue');
+    });
+
+    it('converts object with enum property', () => {
+        const userSchema = z.object({
+            name: z.string(),
+            status: z.enum(['active', 'inactive']),
+        });
+        const jsonSchema = fromZod(userSchema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('object');
+        expect(jsonSchema.properties?.['status']).toEqual({
+            type: 'string',
+            enum: ['active', 'inactive'],
+        });
+    });
+
+    it('validates enum values correctly', () => {
+        const schema = z.enum(['a', 'b', 'c']);
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.enum).toEqual(['a', 'b', 'c']);
+        expect(jsonSchema.type).toBe('string');
+    });
+});
+
+// ============================================================================
+// Nested Object Schema Tests (VAL-SCHEMA-009)
+// ============================================================================
+
+describe('Nested Object Schema (VAL-SCHEMA-009)', () => {
+    it('converts deeply nested object schema', () => {
+        const addressSchema = z.object({
+            street: z.string(),
+            city: z.string(),
+            country: z.string(),
+        });
+        
+        const userSchema = z.object({
+            name: z.string(),
+            address: addressSchema,
+        });
+        
+        const companySchema = z.object({
+            name: z.string(),
+            users: z.array(userSchema),
+        });
+        
+        const jsonSchema = fromZod(companySchema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('object');
+        // Check the structure exists
+        const usersSchema = jsonSchema.properties?.['users'] as JSONSchema;
+        expect(usersSchema.type).toBe('array');
+        
+        const itemsSchema = usersSchema.items as JSONSchema;
+        expect(itemsSchema.type).toBe('object');
+        expect(itemsSchema.properties?.['name']).toEqual({ type: 'string' });
+        
+        // Navigate deep into the schema
+        const addressProp = itemsSchema.properties?.['address'] as JSONSchema;
+        expect(addressProp.type).toBe('object');
+        expect(addressProp.properties?.['street']).toEqual({ type: 'string' });
+        expect(addressProp.properties?.['city']).toEqual({ type: 'string' });
+        expect(addressProp.properties?.['country']).toEqual({ type: 'string' });
+    });
+
+    it('handles three levels of nesting', () => {
+        const citySchema = z.object({
+            name: z.string(),
+            population: z.number(),
+        });
+        
+        const addressSchema = z.object({
+            street: z.string(),
+            city: citySchema,
+        });
+        
+        const personSchema = z.object({
+            name: z.string(),
+            address: addressSchema,
+        });
+        
+        const jsonSchema = fromZod(personSchema).jsonSchema;
+        
+        // Navigate deep into the schema
+        const addressProps = jsonSchema.properties?.['address'];
+        const cityProps = (addressProps as JSONSchema)?.properties?.['city'];
+        const citySchemaProps = (cityProps as JSONSchema)?.properties;
+        
+        expect(citySchemaProps?.['name']).toEqual({ type: 'string' });
+        expect(citySchemaProps?.['population']).toEqual({ type: 'number' });
+    });
+
+    it('handles optional nested objects', () => {
+        const schema = z.object({
+            name: z.string(),
+            metadata: z.object({
+                created: z.string(),
+            }).optional(),
+        });
+        
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.required).toEqual(['name']);
+        expect(jsonSchema.properties?.['metadata']?.type).toBe('object');
+    });
+});
+
+// ============================================================================
+// Array Schema Tests (VAL-SCHEMA-010)
+// ============================================================================
+
+describe('Array Schema (VAL-SCHEMA-010)', () => {
+    it('converts Zod array of strings to JSON Schema', () => {
+        const schema = z.array(z.string());
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('array');
+        expect(jsonSchema.items).toEqual({ type: 'string' });
+    });
+
+    it('converts Zod array of numbers to JSON Schema', () => {
+        const schema = z.array(z.number());
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('array');
+        expect(jsonSchema.items).toEqual({ type: 'number' });
+    });
+
+    it('converts Zod array of objects to JSON Schema', () => {
+        const schema = z.array(z.object({
+            id: z.string(),
+            name: z.string(),
+        }));
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('array');
+        // zod-to-json-schema adds additionalProperties: false by default
+        const items = jsonSchema.items as JSONSchema;
+        expect(items.type).toBe('object');
+        expect(items.properties?.['id']).toEqual({ type: 'string' });
+        expect(items.properties?.['name']).toEqual({ type: 'string' });
+        expect(items.required).toEqual(['id', 'name']);
+    });
+
+    it('converts nested arrays', () => {
+        const schema = z.array(z.array(z.string()));
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('array');
+        expect(jsonSchema.items).toEqual({
+            type: 'array',
+            items: { type: 'string' },
+        });
+    });
+
+    it('handles array with min/max constraints', () => {
+        const schema = z.array(z.string()).min(1).max(10);
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('array');
+        expect(jsonSchema.minItems).toBe(1);
+        expect(jsonSchema.maxItems).toBe(10);
+    });
+});
+
+// ============================================================================
+// Primitives Schema Tests
+// ============================================================================
+
+describe('Primitive Schemas', () => {
+    it('converts Zod null schema', () => {
+        const schema = z.null();
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('null');
+    });
+
+    it('converts Zod literal schema', () => {
+        const schema = z.literal('fixed');
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.const).toBe('fixed');
+    });
+
+    it('converts Zod union schema', () => {
+        const schema = z.union([z.string(), z.number()]);
+        const jsonSchema = fromZod(schema).jsonSchema;
+        // Zod 4 native z.toJSONSchema uses anyOf for unions
+        expect(jsonSchema.anyOf).toEqual([
+            { type: 'string' },
+            { type: 'number' },
+        ]);
+    });
+
+    it('converts Zod record schema', () => {
+        const schema = z.record(z.string(), z.number());
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('object');
+        expect(jsonSchema.additionalProperties).toEqual({ type: 'number' });
+    });
+
+    it('converts Zod tuple schema', () => {
+        const schema = z.tuple([z.string(), z.number()]);
+        const jsonSchema = fromZod(schema).jsonSchema;
+        
+        expect(jsonSchema.type).toBe('array');
+        // Zod 4 native z.toJSONSchema uses items array for tuples
+        expect(jsonSchema.items).toEqual([
+            { type: 'string' },
+            { type: 'number' },
+        ]);
+    });
+});
+
+// ============================================================================
+// Google-Specific Schema Transformation Tests (VAL-PROVIDER-GOOGLE-006)
+// ============================================================================
+
+describe('Google Schema Transformation (VAL-PROVIDER-GOOGLE-006)', () => {
+    describe('stripUnsupportedFeatures', () => {
+        it('removes pattern property (not supported by Gemini)', () => {
+            const input: JSONSchema = {
+                type: 'string',
+                pattern: '^[a-zA-Z]+$',
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.pattern).toBeUndefined();
+            expect(result.type).toBe('string');
+        });
+
+        it('removes minLength/maxLength for strings', () => {
+            const input: JSONSchema = {
+                type: 'string',
+                minLength: 1,
+                maxLength: 100,
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.minLength).toBeUndefined();
+            expect(result.maxLength).toBeUndefined();
+            expect(result.type).toBe('string');
+        });
+
+        it('keeps minLength/maxLength for other providers', () => {
+            const input: JSONSchema = {
+                type: 'string',
+                minLength: 1,
+                maxLength: 100,
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'openai');
+            
+            expect(result.minLength).toBe(1);
+            expect(result.maxLength).toBe(100);
+        });
+
+        it('removes minimum/maximum for numbers', () => {
+            const input: JSONSchema = {
+                type: 'number',
+                minimum: 0,
+                maximum: 100,
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.minimum).toBeUndefined();
+            expect(result.maximum).toBeUndefined();
+        });
+
+        it('removes exclusiveMinimum/exclusiveMaximum', () => {
+            const input: JSONSchema = {
+                type: 'number',
+                exclusiveMinimum: 0,
+                exclusiveMaximum: 100,
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.exclusiveMinimum).toBeUndefined();
+            expect(result.exclusiveMaximum).toBeUndefined();
+        });
+
+        it('removes unsupported features recursively in nested objects', () => {
+            const input: JSONSchema = {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        pattern: '^[a-z]+$',
+                    },
+                    age: {
+                        type: 'number',
+                        minimum: 0,
+                    },
+                },
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.properties?.['name']?.pattern).toBeUndefined();
+            expect(result.properties?.['age']?.minimum).toBeUndefined();
+        });
+
+        it('removes unsupported features in array items', () => {
+            const input: JSONSchema = {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        code: {
+                            type: 'string',
+                            pattern: '^[A-Z]{3}$',
+                        },
+                    },
+                },
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            const items = result.items as JSONSchema;
+            expect(items.properties?.['code']?.pattern).toBeUndefined();
+        });
+
+        it('preserves required array', () => {
+            const input: JSONSchema = {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    age: { type: 'number' },
+                },
+                required: ['name', 'age'],
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.required).toEqual(['name', 'age']);
+        });
+
+        it('preserves enum array', () => {
+            const input: JSONSchema = {
+                type: 'string',
+                enum: ['active', 'inactive', 'pending'],
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.enum).toEqual(['active', 'inactive', 'pending']);
+        });
+
+        it('removes additionalProperties for Google (not supported)', () => {
+            const input: JSONSchema = {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                },
+                additionalProperties: false,
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.additionalProperties).toBeUndefined();
+        });
+
+        it('removes additionalProperties as object schema for Google', () => {
+            const input: JSONSchema = {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                },
+                additionalProperties: { type: 'string' },
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.additionalProperties).toBeUndefined();
+        });
+
+        it('keeps additionalProperties for other providers', () => {
+            const input: JSONSchema = {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                },
+                additionalProperties: false,
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'openai');
+            
+            expect(result.additionalProperties).toBe(false);
+        });
+
+        it('preserves description', () => {
+            const input: JSONSchema = {
+                type: 'object',
+                description: 'User object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: 'User name',
+                    },
+                },
+            };
+            
+            const result = stripUnsupportedFeatures(input, 'google');
+            
+            expect(result.description).toBe('User object');
+            expect(result.properties?.['name']?.description).toBe('User name');
+        });
+    });
+
+    describe('convertToProviderSchema for Google', () => {
+        it('applies Google-specific transformations', () => {
+            const schema = z.object({
+                email: z.string().regex(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
+            });
+            
+            const options: StructuredOutputOptions<{ email: string }> = {
+                schemaConfig: fromZod(schema),
+            };
+            
+            const result = convertToProviderSchema('google', options);
+            
+            // Google doesn't support pattern, should be stripped
+            const emailProp = result.schema.properties?.['email'] as JSONSchema;
+            expect(emailProp.pattern).toBeUndefined();
+            expect(emailProp.type).toBe('string');
+        });
+    });
+});
+
+// ============================================================================
+// Validation Logic Tests (VAL-SCHEMA-005, VAL-SCHEMA-006, VAL-SCHEMA-007)
+// ============================================================================
+
+describe('Validation Logic (VAL-SCHEMA-005)', () => {
+    describe('parseStructured', () => {
+        it('returns parsed object when JSON is valid and matches schema', () => {
+            const schema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            
+            const rawOutput = '{"name": "Alice", "age": 30}';
+            const result = parseStructured(fromZod(schema), rawOutput);
+            
+            expect(result).toEqual({ name: 'Alice', age: 30 });
+        });
+
+        it('returns parsed object for complex nested schema', () => {
+            const addressSchema = z.object({
+                street: z.string(),
+                city: z.string(),
+            });
+            const personSchema = z.object({
+                name: z.string(),
+                address: addressSchema,
+            });
+            
+            const rawOutput = '{"name": "Bob", "address": {"street": "123 Main", "city": "NYC"}}';
+            const result = parseStructured(fromZod(personSchema), rawOutput);
+            
+            expect(result).toEqual({
+                name: 'Bob',
+                address: { street: '123 Main', city: 'NYC' },
+            });
+        });
+
+        it('throws StructuredOutputError when JSON fails schema validation', () => {
+            const schema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            
+            // Missing 'age' field
+            const rawOutput = '{"name": "Alice"}';
+            
+            expect(() => parseStructured(fromZod(schema), rawOutput)).toThrow(StructuredOutputError);
+        });
+
+        it('throws StructuredOutputError with rawOutput when schema validation fails', () => {
+            const schema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            
+            // 'age' is string instead of number
+            const rawOutput = '{"name": "Alice", "age": "thirty"}';
+            
+            try {
+                parseStructured(fromZod(schema), rawOutput);
+                expect(true).toBe(false); // Should not reach here
+            } catch (error) {
+                expect(error).toBeInstanceOf(StructuredOutputError);
+                if (error instanceof StructuredOutputError) {
+                    expect(error.rawOutput).toBe(rawOutput);
+                    expect(error.cause).toBeInstanceOf(z.ZodError);
+                }
+            }
+        });
+
+        it('throws StructuredOutputError with ZodError as cause on validation failure', () => {
+            const schema = z.object({
+                email: z.string().email(),
+            });
+            
+            const rawOutput = '{"email": "not-an-email"}';
+            
+            try {
+                parseStructured(fromZod(schema), rawOutput);
+                expect(true).toBe(false); // Should not reach here
+            } catch (error) {
+                expect(error).toBeInstanceOf(StructuredOutputError);
+                if (error instanceof StructuredOutputError) {
+                    expect(error.cause).toBeInstanceOf(z.ZodError);
+                    const zodError = error.cause as z.ZodError;
+                    expect(zodError.issues.length).toBeGreaterThan(0);
+                }
+            }
+        });
+    });
+
+    describe('Markdown Fence Tolerance (VAL-SCHEMA-008)', () => {
+        // Some providers/models wrap structured output in ```json ... ```
+        // fences even when a JSON schema is supplied via the `format`
+        // field (observed with Gemma variants via Ollama). parseStructured
+        // must tolerate this so the first such response doesn't fail the
+        // whole scoring run.
+
+        const schema = z.object({
+            score: z.number(),
+            reasoning: z.string(),
+            correct: z.boolean(),
+        });
+
+        it('parses JSON wrapped in ```json fences', () => {
+            const rawOutput = '```json\n{"score": 0.9, "reasoning": "matches", "correct": true}\n```';
+            const result = parseStructured(fromZod(schema), rawOutput);
+            expect(result).toEqual({ score: 0.9, reasoning: 'matches', correct: true });
+        });
+
+        it('parses JSON wrapped in bare ``` fences (no language tag)', () => {
+            const rawOutput = '```\n{"score": 0.5, "reasoning": "partial", "correct": false}\n```';
+            const result = parseStructured(fromZod(schema), rawOutput);
+            expect(result).toEqual({ score: 0.5, reasoning: 'partial', correct: false });
+        });
+
+        it('parses JSON wrapped in ```JSON (uppercase language tag)', () => {
+            const rawOutput = '```JSON\n{"score": 1.0, "reasoning": "exact", "correct": true}\n```';
+            const result = parseStructured(fromZod(schema), rawOutput);
+            expect(result).toEqual({ score: 1.0, reasoning: 'exact', correct: true });
+        });
+
+        it('parses JSON with inline fences on a single line', () => {
+            const rawOutput = '```json{"score": 0.0, "reasoning": "wrong", "correct": false}```';
+            const result = parseStructured(fromZod(schema), rawOutput);
+            expect(result).toEqual({ score: 0.0, reasoning: 'wrong', correct: false });
+        });
+
+        it('parses JSON with leading/trailing whitespace around fences', () => {
+            const rawOutput = '  \n```json\n{"score": 0.7, "reasoning": "ok", "correct": true}\n```\n  ';
+            const result = parseStructured(fromZod(schema), rawOutput);
+            expect(result).toEqual({ score: 0.7, reasoning: 'ok', correct: true });
+        });
+
+        it('falls back to first fenced block when prose precedes the JSON', () => {
+            const rawOutput = "Here's the evaluation:\n```json\n{\"score\": 0.3, \"reasoning\": \"weak\", \"correct\": false}\n```\nHope that helps!";
+            const result = parseStructured(fromZod(schema), rawOutput);
+            expect(result).toEqual({ score: 0.3, reasoning: 'weak', correct: false });
+        });
+
+        it('does not disturb well-formed JSON without fences (fast path)', () => {
+            const rawOutput = '{"score": 0.8, "reasoning": "good", "correct": true}';
+            const result = parseStructured(fromZod(schema), rawOutput);
+            expect(result).toEqual({ score: 0.8, reasoning: 'good', correct: true });
+        });
+
+        it('preserves JSON string values that contain literal backticks', () => {
+            // The reasoning field contains the sequence ``` inside a string
+            // literal but there is no fenced block. parseStructured should
+            // take the fast path and not touch the value.
+            const rawOutput = '{"score": 0.5, "reasoning": "the model emitted ``` once", "correct": false}';
+            const result = parseStructured(fromZod(schema), rawOutput);
+            expect(result.reasoning).toBe('the model emitted ``` once');
+        });
+
+        it('throws with the original rawOutput when fence stripping does not yield valid JSON', () => {
+            const rawOutput = '```json\nthis is not json at all\n```';
+            try {
+                parseStructured(fromZod(schema), rawOutput);
+                expect(true).toBe(false);
+            } catch (error) {
+                expect(error).toBeInstanceOf(StructuredOutputError);
+                if (error instanceof StructuredOutputError) {
+                    // The error should report the original raw output so
+                    // users debugging can see exactly what the model sent.
+                    expect(error.rawOutput).toBe(rawOutput);
+                }
+            }
+        });
+    });
+
+    describe('stripJsonFences helper', () => {
+        it('returns input unchanged when no fences are present', () => {
+            expect(stripJsonFences('{"a": 1}')).toBe('{"a": 1}');
+            expect(stripJsonFences('plain text')).toBe('plain text');
+            expect(stripJsonFences('')).toBe('');
+        });
+
+        it('strips ```json fences', () => {
+            expect(stripJsonFences('```json\n{"a": 1}\n```')).toBe('{"a": 1}');
+        });
+
+        it('strips bare ``` fences', () => {
+            expect(stripJsonFences('```\n{"a": 1}\n```')).toBe('{"a": 1}');
+        });
+
+        it('is idempotent', () => {
+            const once = stripJsonFences('```json\n{"a": 1}\n```');
+            const twice = stripJsonFences(once);
+            expect(twice).toBe(once);
+        });
+
+        it('returns input unchanged if a stray ``` has no closing fence', () => {
+            // No matched pair — leave the input alone so the JSON parser
+            // sees the real output and produces a meaningful error.
+            const input = '{"a": 1, "note": "stray ``` here"}';
+            expect(stripJsonFences(input)).toBe(input);
+        });
+    });
+
+    describe('Malformed JSON Handling (VAL-SCHEMA-006)', () => {
+        it('throws StructuredOutputError on malformed JSON', () => {
+            const schema = z.object({ name: z.string() });
+            const rawOutput = 'not valid json at all';
+            
+            expect(() => parseStructured(fromZod(schema), rawOutput)).toThrow(StructuredOutputError);
+        });
+
+        it('includes raw output in error for malformed JSON', () => {
+            const schema = z.object({ name: z.string() });
+            const rawOutput = '{"name": "incomplete"';
+            
+            try {
+                parseStructured(fromZod(schema), rawOutput);
+                expect(true).toBe(false); // Should not reach here
+            } catch (error) {
+                expect(error).toBeInstanceOf(StructuredOutputError);
+                if (error instanceof StructuredOutputError) {
+                    expect(error.rawOutput).toBe(rawOutput);
+                    expect(error.cause).toBeDefined();
+                    expect(error.cause).toBeInstanceOf(SyntaxError);
+                }
+            }
+        });
+
+        it('handles completely empty output', () => {
+            const schema = z.object({ name: z.string() });
+            const rawOutput = '';
+            
+            try {
+                parseStructured(fromZod(schema), rawOutput);
+                expect(true).toBe(false); // Should not reach here
+            } catch (error) {
+                expect(error).toBeInstanceOf(StructuredOutputError);
+                if (error instanceof StructuredOutputError) {
+                    expect(error.rawOutput).toBe('');
+                }
+            }
+        });
+
+        it('handles null JSON value', () => {
+            const schema = z.object({ name: z.string() });
+            const rawOutput = 'null';
+            
+            expect(() => parseStructured(fromZod(schema), rawOutput)).toThrow(StructuredOutputError);
+        });
+
+        it('handles array when object expected', () => {
+            const schema = z.object({ name: z.string() });
+            const rawOutput = '["not", "an", "object"]';
+            
+            try {
+                parseStructured(fromZod(schema), rawOutput);
+                expect(true).toBe(false); // Should not reach here
+            } catch (error) {
+                expect(error).toBeInstanceOf(StructuredOutputError);
+                if (error instanceof StructuredOutputError) {
+                    expect(error.rawOutput).toBe(rawOutput);
+                    expect(error.cause).toBeInstanceOf(z.ZodError);
+                }
+            }
+        });
+    });
+});
+
+describe('tryParseStructured (VAL-SCHEMA-007)', () => {
+    describe('Success Path', () => {
+        it('returns { ok: true, value } on success', () => {
+            const schema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            
+            const rawOutput = '{"name": "Alice", "age": 30}';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value).toEqual({ name: 'Alice', age: 30 });
+            }
+        });
+
+        it('never throws on success', () => {
+            const schema = z.object({ value: z.number() });
+            const rawOutput = '{"value": 42}';
+            
+            // Should not throw, should return result object
+            expect(() => tryParseStructured(fromZod(schema), rawOutput)).not.toThrow();
+            
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            expect(result.ok).toBe(true);
+        });
+
+        it('handles optional fields correctly', () => {
+            const schema = z.object({
+                name: z.string(),
+                email: z.string().email().optional(),
+            });
+            
+            const rawOutput = '{"name": "Bob"}';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value).toEqual({ name: 'Bob' });
+            }
+        });
+
+        it('validates nested objects', () => {
+            const schema = z.object({
+                user: z.object({
+                    name: z.string(),
+                    address: z.object({
+                        city: z.string(),
+                    }),
+                }),
+            });
+            
+            const rawOutput = '{"user": {"name": "Carol", "address": {"city": "NYC"}}}';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value).toEqual({
+                    user: { name: 'Carol', address: { city: 'NYC' } },
+                });
+            }
+        });
+
+        it('validates arrays', () => {
+            const schema = z.object({
+                items: z.array(z.string()),
+            });
+            
+            const rawOutput = '{"items": ["a", "b", "c"]}';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value).toEqual({ items: ['a', 'b', 'c'] });
+            }
+        });
+
+        it('validates enums', () => {
+            const schema = z.object({
+                status: z.enum(['active', 'inactive']),
+            });
+            
+            const rawOutput = '{"status": "active"}';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value).toEqual({ status: 'active' });
+            }
+        });
+    });
+
+    describe('Failure Path', () => {
+        it('returns { ok: false, error, rawOutput } on validation failure', () => {
+            const schema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            
+            // Missing 'age' field
+            const rawOutput = '{"name": "Alice"}';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error).toBeInstanceOf(StructuredOutputError);
+                expect(result.rawOutput).toBe(rawOutput);
+            }
+        });
+
+        it('returns { ok: false, ... } on malformed JSON', () => {
+            const schema = z.object({ name: z.string() });
+            const rawOutput = 'not json';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error).toBeInstanceOf(StructuredOutputError);
+                expect(result.rawOutput).toBe(rawOutput);
+            }
+        });
+
+        it('never throws, always returns result object', () => {
+            const schema = z.object({ name: z.string() });
+            
+            // Test with invalid JSON
+            expect(() => tryParseStructured(fromZod(schema), 'invalid')).not.toThrow();
+            
+            // Test with schema validation failure
+            expect(() => tryParseStructured(fromZod(schema), '{"age": 30}')).not.toThrow();
+            
+            // Test with type mismatch
+            expect(() => tryParseStructured(fromZod(schema), '{"name": 123}')).not.toThrow();
+        });
+
+        it('includes ZodError as cause in failure result', () => {
+            const schema = z.object({
+                email: z.string().email(),
+            });
+            
+            const rawOutput = '{"email": "not-an-email"}';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error.cause).toBeInstanceOf(z.ZodError);
+            }
+        });
+
+        it('includes SyntaxError as cause for malformed JSON', () => {
+            const schema = z.object({ name: z.string() });
+            const rawOutput = '{"incomplete": ';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error.cause).toBeInstanceOf(SyntaxError);
+            }
+        });
+
+        it('handles empty string input', () => {
+            const schema = z.object({ name: z.string() });
+            const rawOutput = '';
+            const result = tryParseStructured(fromZod(schema), rawOutput);
+            
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.rawOutput).toBe('');
+            }
+        });
+    });
+
+    describe('Type Narrowing', () => {
+        it('narrows type correctly with ok check', () => {
+            const schema = z.object({ name: z.string() });
+            const result = tryParseStructured(fromZod(schema), '{"name": "test"}');
+            
+            // TypeScript should narrow the type correctly
+            if (result.ok) {
+                // result.value is User type
+                const name: string = result.value.name;
+                expect(name).toBe('test');
+            } else {
+                // This branch should not execute
+                expect(true).toBe(false);
+            }
+        });
+
+        it('isStructuredOutputFailure works correctly', () => {
+            const schema = z.object({ name: z.string() });
+            const successResult = tryParseStructured(fromZod(schema), '{"name": "test"}');
+            const failureResult = tryParseStructured(fromZod(schema), 'invalid json');
+            
+            expect(isStructuredOutputSuccess(successResult)).toBe(true);
+            expect(isStructuredOutputFailure(successResult)).toBe(false);
+            expect(isStructuredOutputSuccess(failureResult)).toBe(false);
+            expect(isStructuredOutputFailure(failureResult)).toBe(true);
+        });
+    });
+});
+
+describe('validateStructuredOutput', () => {
+    it('validates output against Zod schema', () => {
+        const schema = z.object({
+            name: z.string(),
+            count: z.number(),
+        });
+        
+        const data = { name: 'test', count: 5 };
+        const result = validateStructuredOutput(fromZod(schema), data);
+        
+        expect(result).toEqual(data);
+    });
+
+    it('throws StructuredOutputError on validation failure', () => {
+        const schema = z.object({
+            name: z.string(),
+            count: z.number(),
+        });
+        
+        const data = { name: 'test', count: 'not a number' };
+        
+        expect(() => validateStructuredOutput(fromZod(schema), data)).toThrow(StructuredOutputError);
+    });
+
+    it('includes raw output in error for failed validation', () => {
+        const schema = z.object({ name: z.string() });
+        const rawOutput = '{"name": 123}';
+        
+        try {
+            validateStructuredOutput(fromZod(schema), JSON.parse(rawOutput), rawOutput);
+            expect(true).toBe(false); // Should not reach here
+        } catch (error) {
+            expect(error).toBeInstanceOf(StructuredOutputError);
+            if (error instanceof StructuredOutputError) {
+                expect(error.rawOutput).toBe(rawOutput);
+            }
+        }
+    });
+});