refactor: Simplify ensureError to use cause instead of string conversion

- Use `{ cause: error }` to preserve original value instead of string conversion
- Standardize message to "Unknown error" for all non-Error values
- Remove unnecessary number-to-error test case
- Update tests to verify cause preservation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: abretonc7s

src/errors.test.ts

@@ -344,60 +344,61 @@ describe('ensureError', () => {
     expect(result).toBe(originalError);
   });
 
-  it('converts string to Error with string as message', () => {
+  it('converts string to Error and preserves original as cause', () => {
     const result = ensureError('something went wrong');
 
     expect(result).toBeInstanceOf(Error);
-    expect(result.message).toBe('something went wrong');
-  });
-
-  it('converts number to Error', () => {
-    const result = ensureError(42);
-
-    expect(result).toBeInstanceOf(Error);
-    expect(result.message).toBe('42');
+    expect(result.message).toBe('Unknown error');
+    expect(result.cause).toBe('something went wrong');
   });
 
-  it('converts object to Error using String()', () => {
-    const result = ensureError({ some: 'object' });
+  it('converts object to Error and preserves original as cause', () => {
+    const originalObject = { some: 'object' };
+    const result = ensureError(originalObject);
 
     expect(result).toBeInstanceOf(Error);
-    expect(result.message).toBe('[object Object]');
+    expect(result.message).toBe('Unknown error');
+    expect(result.cause).toBe(originalObject);
   });
 
-  it('handles null with descriptive message', () => {
+  it('handles null with descriptive message and preserves as cause', () => {
     const result = ensureError(null);
 
     expect(result).toBeInstanceOf(Error);
     expect(result.message).toBe('Unknown error');
+    expect(result.cause).toBeNull();
   });
 
-  it('handles undefined with descriptive message', () => {
+  it('handles undefined with descriptive message and preserves as cause', () => {
     const result = ensureError(undefined);
 
     expect(result).toBeInstanceOf(Error);
     expect(result.message).toBe('Unknown error');
+    expect(result.cause).toBeUndefined();
   });
 
   it('appends context to message for null', () => {
     const result = ensureError(null, 'fetchData');
 
     expect(result).toBeInstanceOf(Error);
     expect(result.message).toBe('Unknown error (fetchData)');
+    expect(result.cause).toBeNull();
   });
 
   it('appends context to message for undefined', () => {
     const result = ensureError(undefined, 'processInput');
 
     expect(result).toBeInstanceOf(Error);
     expect(result.message).toBe('Unknown error (processInput)');
+    expect(result.cause).toBeUndefined();
   });
 
-  it('appends context for non-Error values', () => {
+  it('appends context for non-Error values and preserves original as cause', () => {
     const result = ensureError('network failure', 'apiCall');
 
     expect(result).toBeInstanceOf(Error);
-    expect(result.message).toBe('network failure (apiCall)');
+    expect(result.message).toBe('Unknown error (apiCall)');
+    expect(result.cause).toBe('network failure');
   });
 
   it('does NOT add context to existing Error instances', () => {

src/errors.ts

@@ -123,7 +123,8 @@ export function wrapError<Throwable>(
 /**
  * Ensures we have a proper Error object.
  * If the input is already an Error, returns it unchanged.
- * Otherwise, converts to an Error with an appropriate message.
+ * Otherwise, converts to an Error with an appropriate message and preserves
+ * the original value as the cause.
  *
  * @param error - The caught error (could be Error, string, or unknown).
  * @param context - Optional context to help identify the error source.
@@ -134,11 +135,6 @@ export function ensureError(error: unknown, context?: string): Error {
     return error;
   }
 
-  if (isNullOrUndefined(error)) {
-    const message = context ? `Unknown error (${context})` : 'Unknown error';
-    return new Error(message);
-  }
-
-  const message = context ? `${String(error)} (${context})` : String(error);
-  return new Error(message);
+  const message = context ? `Unknown error (${context})` : 'Unknown error';
+  return new Error(message, { cause: error });
 }