tjs-lang 0.7.4 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Type-safe JavaScript dialect with runtime validation, sandboxed VM execution, and AI agent orchestration. Transpiles TypeScript to validated JS with fuel-metered execution for untrusted code.",
   "keywords": [
     "typescript",

package/src/lang/emitters/js.ts

@@ -822,8 +822,8 @@ export function transpileToJS(
     // Core: MonadicError + typeError (needed by almost all validated functions)
     if (needsTypeError) {
       inlineParts.push(
-        `class MonadicError extends Error{constructor(m,p,e,a,c){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c}}`,
-        `function typeError(p,e,v){const a=v===null?'null':typeof v;const err=new MonadicError('Expected '+e+" for '"+p+"', got "+a,p,e,a);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
+        `class MonadicError extends Error{constructor(m,p,e,a,c,r){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;this.reason=r}}`,
+        `function typeError(p,e,v,r){const a=v===null?'null':typeof v;const m=r?'Expected '+e+" for '"+p+"': "+r:'Expected '+e+" for '"+p+"', got "+a;const err=new MonadicError(m,p,e,a,undefined,r);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
         `function isMonadicError(v){return v instanceof Error&&v.name==='MonadicError'&&'path' in v}`
       )
     }
@@ -892,8 +892,8 @@ export function transpileToJS(
       // bang depends on typeError and isMonadicError — ensure they're inlined
       if (!needsTypeError) {
         inlineParts.push(
-          `class MonadicError extends Error{constructor(m,p,e,a,c){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c}}`,
-          `function typeError(p,e,v){const a=v===null?'null':typeof v;const err=new MonadicError('Expected '+e+" for '"+p+"', got "+a,p,e,a);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
+          `class MonadicError extends Error{constructor(m,p,e,a,c,r){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;this.reason=r}}`,
+          `function typeError(p,e,v,r){const a=v===null?'null':typeof v;const m=r?'Expected '+e+" for '"+p+"': "+r:'Expected '+e+" for '"+p+"', got "+a;const err=new MonadicError(m,p,e,a,undefined,r);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
           `function isMonadicError(v){return v instanceof Error&&v.name==='MonadicError'&&'path' in v}`
         )
       }

package/src/lang/function-predicate.test.ts

@@ -12,9 +12,11 @@ describe('FunctionPredicate runtime', () => {
     })
     expect(Callback.check(() => {})).toBe(true)
     expect(Callback.check((x: number) => String(x))).toBe(true)
-    expect(Callback.check(42)).toBe(false)
-    expect(Callback.check('not a function')).toBe(false)
-    expect(Callback.check(null)).toBe(false)
+    expect(Callback.check(42)).toBe('expected function, got number')
+    expect(Callback.check('not a function')).toBe(
+      'expected function, got string'
+    )
+    expect(Callback.check(null)).toBe('expected function, got null')
   })
 
   it('should create from existing typed function', () => {
@@ -73,7 +75,7 @@ describe('FunctionPredicate runtime', () => {
         x: { type: { kind: 'integer' }, example: 0 },
       },
     }
-    expect(Binop.check(wrongArity)).toBe(false)
+    expect(Binop.check(wrongArity)).toBe('expected 2 params, got 1')
   })
 
   it('should reject function with wrong param types via __tjs metadata', () => {
@@ -93,7 +95,7 @@ describe('FunctionPredicate runtime', () => {
     ;(badFn as any).__tjs = {
       params: { n: { type: { kind: 'integer' }, example: 0 } },
     }
-    expect(StrFn.check(badFn)).toBe(false)
+    expect(StrFn.check(badFn)).toBe("param 'name' expected string, got integer")
   })
 
   it('should accept function with any-typed params', () => {
@@ -230,7 +232,7 @@ describe('Generic FunctionPredicate runtime', () => {
     expect(StringCreator.returns).toBe('')
     expect(StringCreator.params.x).toBe('')
     expect(StringCreator.check(() => {})).toBe(true)
-    expect(StringCreator.check(42)).toBe(false)
+    expect(StringCreator.check(42)).toBe('expected function, got number')
   })
 
   it('should use default type arg when none provided', () => {

package/src/lang/runtime.test.ts

@@ -28,6 +28,9 @@ import {
   Is,
   IsNot,
   tjsEquals,
+  checkType,
+  MonadicError,
+  isMonadicError,
 } from './runtime'
 import { Eval, SafeFunction } from './eval'
 
@@ -1120,3 +1123,58 @@ function add(a: 1, b: 2): 3 {
     }
   })
 })
+
+describe('predicate reason strings', () => {
+  it('typeError includes reason in message and field', () => {
+    const err = typeError('foo.bar', 'even number', 3, 'value is odd')
+    expect(err.message).toContain('value is odd')
+    expect(err.message).toContain('foo.bar')
+    expect(err.reason).toBe('value is odd')
+    expect(isMonadicError(err)).toBe(true)
+  })
+
+  it('typeError without reason works as before', () => {
+    const err = typeError('foo.bar', 'string', 42)
+    expect(err.message).toContain('got number')
+    expect(err.reason).toBeUndefined()
+  })
+
+  it('checkType captures reason from predicate', () => {
+    const EvenType = {
+      check: (v: unknown): boolean | string => {
+        if (typeof v !== 'number') return `expected number, got ${typeof v}`
+        if (v % 2 !== 0) return `${v} is odd`
+        return true
+      },
+      description: 'even number',
+    }
+
+    // Pass
+    expect(checkType(4, EvenType, 'test.val')).toBeNull()
+
+    // Fail with reason
+    const err = checkType(3, EvenType, 'test.val')
+    expect(err).not.toBeNull()
+    expect(err!.message).toContain('3 is odd')
+    expect(err!.reason).toBe('3 is odd')
+
+    // Fail with different reason
+    const err2 = checkType('x', EvenType, 'test.val')
+    expect(err2).not.toBeNull()
+    expect(err2!.message).toContain('expected number, got string')
+  })
+
+  it('checkType works with boolean-only predicates', () => {
+    const PositiveType = {
+      check: (v: unknown) => typeof v === 'number' && v > 0,
+      description: 'positive number',
+    }
+
+    expect(checkType(5, PositiveType, 'x')).toBeNull()
+
+    const err = checkType(-1, PositiveType, 'x')
+    expect(err).not.toBeNull()
+    expect(err!.message).toContain('positive number')
+    expect(err!.reason).toBeUndefined()
+  })
+})

package/src/lang/runtime.ts

@@ -142,13 +142,16 @@ export class MonadicError extends Error {
   readonly actual?: string
   /** TJS call stack (only in debug mode) - shows source locations */
   readonly callStack?: string[]
+  /** Why the check failed (from predicate reason strings) */
+  readonly reason?: string
 
   constructor(
     message: string,
     path: string,
     expected?: string,
     actual?: string,
-    callStack?: string[]
+    callStack?: string[],
+    reason?: string
   ) {
     super(message)
     this.name = 'MonadicError'
@@ -156,6 +159,7 @@ export class MonadicError extends Error {
     this.expected = expected
     this.actual = actual
     this.callStack = callStack
+    this.reason = reason
     // Maintains proper stack trace in V8 environments
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, MonadicError)
@@ -177,18 +181,16 @@ export class MonadicError extends Error {
 export function typeError(
   path: string,
   expected: string,
-  value: unknown
+  value: unknown,
+  reason?: string
 ): MonadicError {
   const actual = value === null ? 'null' : typeof value
   // Capture call stack in debug mode (getStack returns [] if not in debug mode)
   const stack = config.callStacks || config.debug ? getStack() : undefined
-  const err = new MonadicError(
-    `Expected ${expected} for '${path}', got ${actual}`,
-    path,
-    expected,
-    actual,
-    stack
-  )
+  const msg = reason
+    ? `Expected ${expected} for '${path}': ${reason}`
+    : `Expected ${expected} for '${path}', got ${actual}`
+  const err = new MonadicError(msg, path, expected, actual, stack, reason)
 
   // Track in error history ring buffer (zero cost on happy path)
   if (config.trackErrors !== false) {
@@ -238,6 +240,8 @@ export interface TJSError {
   stack?: string[]
   expected?: string
   actual?: string
+  /** Why the check failed (from predicate reason strings) */
+  reason?: string
   cause?: Error | TJSError
   /** Source location for error reporting */
   loc?: { start: number; end: number }
@@ -779,7 +783,9 @@ export function isNativeType(value: unknown, typeName: string): boolean {
  */
 export function checkType(
   value: unknown,
-  expected: string | { check: (v: unknown) => boolean; description: string },
+  expected:
+    | string
+    | { check: (v: unknown) => boolean | string; description: string },
   path?: string
 ): TJSError | null {
   // If value is already an error, propagate it
@@ -791,11 +797,17 @@ export function checkType(
     expected !== null &&
     'check' in expected
   ) {
-    if (expected.check(value)) return null
-    return error(`Expected ${expected.description} but got ${typeOf(value)}`, {
+    const result = expected.check(value)
+    if (result === true) return null
+    const reason = typeof result === 'string' ? result : undefined
+    const msg = reason
+      ? `Expected ${expected.description} for '${path}': ${reason}`
+      : `Expected ${expected.description} but got ${typeOf(value)}`
+    return error(msg, {
       path,
       expected: expected.description,
       actual: typeOf(value),
+      reason,
     })
   }
 
@@ -828,7 +840,9 @@ export function checkType(
 }
 
 /** Type specifier - either a string name or a RuntimeType */
-type TypeSpec = string | { check: (v: unknown) => boolean; description: string }
+type TypeSpec =
+  | string
+  | { check: (v: unknown) => boolean | string; description: string }
 
 /** Parameter metadata with optional location */
 interface ParamMeta {

package/src/types/Type.test.ts

@@ -207,8 +207,8 @@ describe('Built-in Types', () => {
   it('TString validates strings', () => {
     expect(TString.check('hello')).toBe(true)
     expect(TString.check('')).toBe(true)
-    expect(TString.check(123)).toBe(false)
-    expect(TString.check(null)).toBe(false)
+    expect(TString.check(123)).toBe('expected string, got number')
+    expect(TString.check(null)).toBe('expected string, got null')
   })
 
   it('TNumber validates numbers', () => {
@@ -216,60 +216,64 @@ describe('Built-in Types', () => {
     expect(TNumber.check(0)).toBe(true)
     expect(TNumber.check(-1.5)).toBe(true)
     expect(TNumber.check(NaN)).toBe(true) // NaN is typeof number
-    expect(TNumber.check('123')).toBe(false)
+    expect(TNumber.check('123')).toBe('expected number, got string')
   })
 
   it('TBoolean validates booleans', () => {
     expect(TBoolean.check(true)).toBe(true)
     expect(TBoolean.check(false)).toBe(true)
-    expect(TBoolean.check(1)).toBe(false)
-    expect(TBoolean.check('true')).toBe(false)
+    expect(TBoolean.check(1)).toBe('expected boolean, got number')
+    expect(TBoolean.check('true')).toBe('expected boolean, got string')
   })
 
   it('TInteger validates integers', () => {
     expect(TInteger.check(1)).toBe(true)
     expect(TInteger.check(0)).toBe(true)
     expect(TInteger.check(-5)).toBe(true)
-    expect(TInteger.check(1.5)).toBe(false)
-    expect(TInteger.check('1')).toBe(false)
+    expect(TInteger.check(1.5)).toBe('1.5 is not an integer')
+    expect(TInteger.check('1')).toBe('expected integer, got string')
   })
 
   it('TPositiveInt validates positive integers', () => {
     expect(TPositiveInt.check(1)).toBe(true)
     expect(TPositiveInt.check(100)).toBe(true)
-    expect(TPositiveInt.check(0)).toBe(false)
-    expect(TPositiveInt.check(-1)).toBe(false)
-    expect(TPositiveInt.check(1.5)).toBe(false)
+    expect(TPositiveInt.check(0)).toBe('0 is not positive')
+    expect(TPositiveInt.check(-1)).toBe('-1 is not positive')
+    expect(TPositiveInt.check(1.5)).toBe('1.5 is not an integer')
   })
 
   it('TNonEmptyString validates non-empty strings', () => {
     expect(TNonEmptyString.check('hello')).toBe(true)
     expect(TNonEmptyString.check('a')).toBe(true)
-    expect(TNonEmptyString.check('')).toBe(false)
-    expect(TNonEmptyString.check(123)).toBe(false)
+    expect(TNonEmptyString.check('')).toBe('string is empty')
+    expect(TNonEmptyString.check(123)).toBe('expected string, got number')
   })
 
   it('TEmail validates email addresses', () => {
     expect(TEmail.check('user@example.com')).toBe(true)
     expect(TEmail.check('a@b.c')).toBe(true)
-    expect(TEmail.check('invalid')).toBe(false)
-    expect(TEmail.check('no@domain')).toBe(false)
-    expect(TEmail.check('@example.com')).toBe(false)
+    expect(TEmail.check('invalid')).toBe('"invalid" is not a valid email')
+    expect(TEmail.check('no@domain')).toBe('"no@domain" is not a valid email')
+    expect(TEmail.check('@example.com')).toBe(
+      '"@example.com" is not a valid email'
+    )
   })
 
   it('TUrl validates URLs', () => {
     expect(TUrl.check('https://example.com')).toBe(true)
     expect(TUrl.check('http://localhost:3000')).toBe(true)
     expect(TUrl.check('ftp://files.example.com')).toBe(true)
-    expect(TUrl.check('not-a-url')).toBe(false)
-    expect(TUrl.check('example.com')).toBe(false)
+    expect(TUrl.check('not-a-url')).toBe('"not-a-url" is not a valid URL')
+    expect(TUrl.check('example.com')).toBe('"example.com" is not a valid URL')
   })
 
   it('TUuid validates UUIDs', () => {
     expect(TUuid.check('550e8400-e29b-41d4-a716-446655440000')).toBe(true)
     expect(TUuid.check('550E8400-E29B-41D4-A716-446655440000')).toBe(true)
-    expect(TUuid.check('not-a-uuid')).toBe(false)
-    expect(TUuid.check('550e8400-e29b-41d4-a716')).toBe(false)
+    expect(TUuid.check('not-a-uuid')).toBe('"not-a-uuid" is not a valid UUID')
+    expect(TUuid.check('550e8400-e29b-41d4-a716')).toBe(
+      '"550e8400-e29b-41d4-a716" is not a valid UUID'
+    )
   })
 })
 
@@ -676,3 +680,48 @@ describe('Enum', () => {
     expect(HttpStatus.members.NotFound).toBe(404)
   })
 })
+
+describe('predicate reason strings', () => {
+  it('Type() passes through reason strings from predicates', () => {
+    const EvenNumber = Type<number>('even number', (v: unknown) => {
+      if (typeof v !== 'number') return 'not a number'
+      if (v % 2 !== 0) return `${v} is odd`
+      return true
+    })
+
+    expect(EvenNumber.check(4)).toBe(true)
+    expect(EvenNumber.check(3)).toBe('3 is odd')
+    expect(EvenNumber.check('x')).toBe('not a number')
+  })
+
+  it('schema-based types still return boolean', () => {
+    const StringType = Type('a string', s.string)
+    expect(StringType.check('hello')).toBe(true)
+    expect(StringType.check(42)).toBe(false)
+  })
+
+  it('Nullable correctly handles reason-returning predicates', () => {
+    const EvenNumber = Type<number>('even number', (v: unknown) => {
+      if (typeof v !== 'number') return 'not a number'
+      if (v % 2 !== 0) return `${v} is odd`
+      return true
+    })
+    const NullableEven = Nullable(EvenNumber)
+
+    expect(NullableEven.check(null)).toBe(true)
+    expect(NullableEven.check(4)).toBe(true)
+    expect(NullableEven.check(3)).toBe(false) // reason lost in combinator, but correctly fails
+  })
+
+  it('TArray correctly handles reason-returning predicates', () => {
+    const Positive = Type<number>('positive', (v: unknown) => {
+      if (typeof v !== 'number') return 'not a number'
+      if (v <= 0) return `${v} is not positive`
+      return true
+    })
+    const PositiveArray = TArray(Positive)
+
+    expect(PositiveArray.check([1, 2, 3])).toBe(true)
+    expect(PositiveArray.check([1, -1, 3])).toBe(false)
+  })
+})

package/src/types/Type.ts

@@ -35,12 +35,12 @@ type Schema = Base<any> | JSONSchema
 export interface RuntimeType<T = unknown> {
   /** Human-readable description of the type */
   readonly description: string
-  /** Check if a value matches this type */
-  check(value: unknown): value is T
+  /** Check if a value matches this type. Returns true on pass, false on fail, or a reason string on fail. */
+  check(value: unknown): boolean | string
   /** The underlying schema (if schema-based) */
   readonly schema?: Schema
-  /** The predicate function (if predicate-based) */
-  readonly predicate?: (value: unknown) => boolean
+  /** The predicate function (if predicate-based). May return a reason string on failure. */
+  readonly predicate?: (value: unknown) => boolean | string
   /** Example value (for documentation and signature testing) */
   readonly example?: T
   /** Multiple example values (from schema metadata, for autocomplete hints) */
@@ -99,7 +99,7 @@ function isJSONSchema(value: unknown): value is JSONSchema {
 export function Type<T = unknown>(
   descriptionOrSchema: string | Schema,
   predicateOrSchemaOrExample?:
-    | ((value: unknown) => boolean)
+    | ((value: unknown) => boolean | string)
     | Schema
     | T
     | undefined,
@@ -108,7 +108,7 @@ export function Type<T = unknown>(
 ): RuntimeType<T> {
   // Parse arguments
   let description: string
-  let predicate: ((value: unknown) => boolean) | undefined
+  let predicate: ((value: unknown) => boolean | string) | undefined
   let schema: Schema | undefined
   let example: T | undefined = exampleArg
   let defaultValue: T | undefined = defaultArg
@@ -119,7 +119,9 @@ export function Type<T = unknown>(
 
     if (typeof predicateOrSchemaOrExample === 'function') {
       // Type(description, predicate, example?, default?)
-      predicate = predicateOrSchemaOrExample as (value: unknown) => boolean
+      predicate = predicateOrSchemaOrExample as (
+        value: unknown
+      ) => boolean | string
       // If we have example, infer schema from it for the type guard in predicate
       if (example !== undefined) {
         schema = s.infer(example)
@@ -176,7 +178,8 @@ export function Type<T = unknown>(
   }
 
   // Build the check function
-  const check = (value: unknown): value is T => {
+  // Returns true on pass, false on fail, or a reason string on fail
+  const check = (value: unknown): boolean | string => {
     if (predicate) {
       return predicate(value)
     }
@@ -264,46 +267,59 @@ function schemaToDescription(schema: Schema): string {
 // ============================================================================
 
 /** String type */
-export const TString = Type<string>(
-  'string',
-  (v: unknown) => typeof v === 'string'
-)
+export const TString = Type<string>('string', (v: unknown) => {
+  if (typeof v === 'string') return true
+  return `expected string, got ${v === null ? 'null' : typeof v}`
+})
 
 /** Number type */
-export const TNumber = Type<number>(
-  'number',
-  (v: unknown) => typeof v === 'number'
-)
+export const TNumber = Type<number>('number', (v: unknown) => {
+  if (typeof v === 'number') return true
+  return `expected number, got ${v === null ? 'null' : typeof v}`
+})
 
 /** Boolean type */
-export const TBoolean = Type<boolean>(
-  'boolean',
-  (v: unknown) => typeof v === 'boolean'
-)
+export const TBoolean = Type<boolean>('boolean', (v: unknown) => {
+  if (typeof v === 'boolean') return true
+  return `expected boolean, got ${v === null ? 'null' : typeof v}`
+})
 
 /** Integer type */
-export const TInteger = Type<number>(
-  'integer',
-  (v: unknown) => typeof v === 'number' && Number.isInteger(v)
-)
+export const TInteger = Type<number>('integer', (v: unknown) => {
+  if (typeof v !== 'number')
+    return `expected integer, got ${v === null ? 'null' : typeof v}`
+  if (!Number.isInteger(v)) return `${v} is not an integer`
+  return true
+})
 
 /** Positive integer type */
-export const TPositiveInt = Type<number>(
-  'positive integer',
-  (v: unknown) => typeof v === 'number' && Number.isInteger(v) && v > 0
-)
+export const TPositiveInt = Type<number>('positive integer', (v: unknown) => {
+  if (typeof v !== 'number')
+    return `expected positive integer, got ${v === null ? 'null' : typeof v}`
+  if (!Number.isInteger(v)) return `${v} is not an integer`
+  if (v <= 0) return `${v} is not positive`
+  return true
+})
 
 /** Non-empty string type */
 export const TNonEmptyString = Type<string>(
   'non-empty string',
-  (v: unknown) => typeof v === 'string' && v.length > 0
+  (v: unknown) => {
+    if (typeof v !== 'string')
+      return `expected string, got ${v === null ? 'null' : typeof v}`
+    if (v.length === 0) return 'string is empty'
+    return true
+  }
 )
 
 /** Email type (basic validation) */
-export const TEmail = Type<string>(
-  'email address',
-  (v: unknown) => typeof v === 'string' && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)
-)
+export const TEmail = Type<string>('email address', (v: unknown) => {
+  if (typeof v !== 'string')
+    return `expected string, got ${v === null ? 'null' : typeof v}`
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v))
+    return `"${v}" is not a valid email`
+  return true
+})
 
 /**
  * Check if a string is a valid URL (portable helper for predicates)
@@ -319,18 +335,23 @@ export const isValidUrl = (v: string): boolean => {
 }
 
 /** URL type */
-export const TUrl = Type<string>(
-  'URL',
-  (v: unknown) => typeof v === 'string' && isValidUrl(v)
-)
+export const TUrl = Type<string>('URL', (v: unknown) => {
+  if (typeof v !== 'string')
+    return `expected string, got ${v === null ? 'null' : typeof v}`
+  if (!isValidUrl(v)) return `"${v}" is not a valid URL`
+  return true
+})
 
 /** UUID type */
-export const TUuid = Type<string>(
-  'UUID',
-  (v: unknown) =>
-    typeof v === 'string' &&
-    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v)
-)
+export const TUuid = Type<string>('UUID', (v: unknown) => {
+  if (typeof v !== 'string')
+    return `expected string, got ${v === null ? 'null' : typeof v}`
+  if (
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v)
+  )
+    return `"${v}" is not a valid UUID`
+  return true
+})
 
 /**
  * Check if a string is a valid ISO 8601 timestamp (portable helper for predicates)
@@ -371,7 +392,7 @@ export const LegalDate = Type<string>(
 export function Nullable<T>(type: RuntimeType<T>): RuntimeType<T | null> {
   return Type<T | null>(
     `${type.description} or null`,
-    (v: unknown) => v === null || type.check(v)
+    (v: unknown) => v === null || type.check(v) === true
   )
 }
 
@@ -381,7 +402,7 @@ export function Optional<T>(
 ): RuntimeType<T | null | undefined> {
   return Type<T | null | undefined>(
     `${type.description} (optional)`,
-    (v: unknown) => v === null || v === undefined || type.check(v)
+    (v: unknown) => v === null || v === undefined || type.check(v) === true
   )
 }
 
@@ -434,14 +455,17 @@ export function Union<T extends unknown[]>(
   types.push(...restTypes)
 
   const description = types.map((t) => t.description).join(' | ')
-  return Type(description, (v: unknown) => types.some((t) => t.check(v)))
+  return Type(description, (v: unknown) =>
+    types.some((t) => t.check(v) === true)
+  )
 }
 
 /** Create an array type */
 export function TArray<T>(itemType: RuntimeType<T>): RuntimeType<T[]> {
   return Type<T[]>(
     `array of ${itemType.description}`,
-    (v: unknown) => Array.isArray(v) && v.every((item) => itemType.check(item))
+    (v: unknown) =>
+      Array.isArray(v) && v.every((item) => itemType.check(item) === true)
   )
 }
 
@@ -467,7 +491,7 @@ export interface GenericType<TParams extends string[] = string[]> {
  */
 function typeParamToCheck(param: TypeParam): (value: unknown) => boolean {
   if (isRuntimeType(param)) {
-    return (v) => param.check(v)
+    return (v) => param.check(v) === true
   }
   // Check if it's a schema builder (has .schema property)
   if (param && typeof param === 'object' && 'schema' in param) {
@@ -820,21 +844,23 @@ function _createFunctionPredicate(
     returnContract,
     toJSONSchema: () => ({ description: name, type: 'function' as any }),
     strip: (value: unknown) => value,
-    // eslint-disable-next-line @typescript-eslint/ban-types
-    check: (value: unknown): value is Function => {
-      if (typeof value !== 'function') return false
+    check: (value: unknown): boolean | string => {
+      if (typeof value !== 'function')
+        return `expected function, got ${
+          value === null ? 'null' : typeof value
+        }`
 
       // Structural validation: check arity and __tjs metadata
       const expectedArity = Object.keys(params).length
       if (expectedArity > 0) {
-        // Check function.length (number of params before first default)
         // eslint-disable-next-line @typescript-eslint/ban-types
         const fn = value as Function
         const meta = (fn as any).__tjs
         if (meta?.params) {
           // Has TJS metadata — check param count matches
           const metaParamCount = Object.keys(meta.params).length
-          if (metaParamCount !== expectedArity) return false
+          if (metaParamCount !== expectedArity)
+            return `expected ${expectedArity} params, got ${metaParamCount}`
 
           // Check param type kinds match where both sides have type info
           const expectedKeys = Object.keys(params)
@@ -849,7 +875,7 @@ function _createFunctionPredicate(
                 metaInfo.type.kind !== expectedKind &&
                 metaInfo.type.kind !== 'any'
               )
-                return false
+                return `param '${expectedKeys[i]}' expected ${expectedKind}, got ${metaInfo.type.kind}`
             }
           }
         }