fix: apply 7 bug fixes for schema correctness (Phase 1)

Copilot · hotlong · Copilot · commit 6df1c786ef4a · 2026-02-07T17:54:50.000Z
1.1 Replace z.any() with z.function() in hook handler union
1.2 Fix ValidationRuleSchema inferring as any with proper base type
1.3 Fix invalid computed key syntax in AuthConfigSchema with .catchall()
1.4 Fix MongoDriverSpec capability key mismatches
1.5 Fix DatasourceConfig type alias naming
1.6 Replace z.instanceof(Error) with JSON-serializable error shape
1.7 Fix filter operator typo $exist → $exists

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/spec/json-schema/data/FieldOperators.json b/packages/spec/json-schema/data/FieldOperators.json
@@ -175,7 +175,7 @@
         "$null": {
           "type": "boolean"
         },
-        "$exist": {
+        "$exists": {
           "type": "boolean"
         }
       },
diff --git a/packages/spec/json-schema/data/Hook.json b/packages/spec/json-schema/data/Hook.json
@@ -58,10 +58,9 @@
           "anyOf": [
             {
               "type": "string"
-            },
-            {}
+            }
           ],
-          "description": "Function handler name or direct function"
+          "description": "Handler function name (string) or inline function reference"
         },
         "priority": {
           "type": "number",
diff --git a/packages/spec/json-schema/data/NormalizedFilter.json b/packages/spec/json-schema/data/NormalizedFilter.json
@@ -184,7 +184,7 @@
                     "$null": {
                       "type": "boolean"
                     },
-                    "$exist": {
+                    "$exists": {
                       "type": "boolean"
                     }
                   },
@@ -375,7 +375,7 @@
                     "$null": {
                       "type": "boolean"
                     },
-                    "$exist": {
+                    "$exists": {
                       "type": "boolean"
                     }
                   },
@@ -564,7 +564,7 @@
                   "$null": {
                     "type": "boolean"
                   },
-                  "$exist": {
+                  "$exists": {
                     "type": "boolean"
                   }
                 },
diff --git a/packages/spec/json-schema/data/SpecialOperator.json b/packages/spec/json-schema/data/SpecialOperator.json
@@ -7,7 +7,7 @@
         "$null": {
           "type": "boolean"
         },
-        "$exist": {
+        "$exists": {
           "type": "boolean"
         }
       },
diff --git a/packages/spec/json-schema/kernel/PluginErrorEvent.json b/packages/spec/json-schema/kernel/PluginErrorEvent.json
@@ -13,7 +13,31 @@
           "description": "Unix timestamp in milliseconds when event occurred"
         },
         "error": {
-          "description": "Error object"
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Error class name"
+            },
+            "message": {
+              "type": "string",
+              "description": "Error message"
+            },
+            "stack": {
+              "type": "string",
+              "description": "Stack trace"
+            },
+            "code": {
+              "type": "string",
+              "description": "Error code"
+            }
+          },
+          "required": [
+            "name",
+            "message"
+          ],
+          "additionalProperties": false,
+          "description": "Serializable error representation"
         },
         "phase": {
           "type": "string",
diff --git a/packages/spec/json-schema/kernel/PluginStartupResult.json b/packages/spec/json-schema/kernel/PluginStartupResult.json
@@ -30,7 +30,31 @@
           "description": "Time taken to start the plugin in milliseconds"
         },
         "error": {
-          "description": "Error object if startup failed"
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Error class name"
+            },
+            "message": {
+              "type": "string",
+              "description": "Error message"
+            },
+            "stack": {
+              "type": "string",
+              "description": "Stack trace"
+            },
+            "code": {
+              "type": "string",
+              "description": "Error code"
+            }
+          },
+          "required": [
+            "name",
+            "message"
+          ],
+          "additionalProperties": false,
+          "description": "Serializable error representation if startup failed"
         },
         "health": {
           "type": "object",
diff --git a/packages/spec/json-schema/kernel/StartupOrchestrationResult.json b/packages/spec/json-schema/kernel/StartupOrchestrationResult.json
@@ -35,7 +35,31 @@
                 "description": "Time taken to start the plugin in milliseconds"
               },
               "error": {
-                "description": "Error object if startup failed"
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Error class name"
+                  },
+                  "message": {
+                    "type": "string",
+                    "description": "Error message"
+                  },
+                  "stack": {
+                    "type": "string",
+                    "description": "Stack trace"
+                  },
+                  "code": {
+                    "type": "string",
+                    "description": "Error code"
+                  }
+                },
+                "required": [
+                  "name",
+                  "message"
+                ],
+                "additionalProperties": false,
+                "description": "Serializable error representation if startup failed"
               },
               "health": {
                 "type": "object",
diff --git a/packages/spec/json-schema/system/AuthConfig.json b/packages/spec/json-schema/system/AuthConfig.json
@@ -90,10 +90,9 @@
             }
           },
           "additionalProperties": false
-        },
-        "[object Object]": {}
+        }
       },
-      "additionalProperties": false
+      "additionalProperties": {}
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"
diff --git a/packages/spec/src/data/datasource.test.ts b/packages/spec/src/data/datasource.test.ts
@@ -5,7 +5,7 @@ import {
   DriverDefinitionSchema,
   DriverType,
   type Datasource,
-  type DatasourceConfig,
+  type DatasourceCapabilitiesType,
 } from './datasource.zod';
 
 describe('DriverType', () => {
diff --git a/packages/spec/src/data/datasource.zod.ts b/packages/spec/src/data/datasource.zod.ts
@@ -138,4 +138,4 @@ export const DatasourceSchema = z.object({
 });
 
 export type Datasource = z.infer<typeof DatasourceSchema>;
-export type DatasourceConfig = z.infer<typeof DatasourceCapabilities>;
+export type DatasourceCapabilitiesType = z.infer<typeof DatasourceCapabilities>;
diff --git a/packages/spec/src/data/driver/mongo.zod.ts b/packages/spec/src/data/driver/mongo.zod.ts
@@ -65,14 +65,13 @@ export const MongoDriverSpec = DriverDefinitionSchema.parse({
   capabilities: {
     transactions: true,
     // Query
+    queryFilters: true,
+    queryAggregations: true,
+    querySorting: true,
+    queryPagination: true,
     fullTextSearch: true,
-    geoSpatial: true,
-    aggregation: true,
     // Schema
-    mutableSchema: true,
-    jsonField: true,
-    // Relations
-    crossObjectJoin: true
+    dynamicSchema: true,
   }
 });
 
diff --git a/packages/spec/src/data/filter.test.ts b/packages/spec/src/data/filter.test.ts
@@ -124,9 +124,9 @@ describe('SpecialOperatorSchema', () => {
     expect(() => SpecialOperatorSchema.parse({ $null: false })).not.toThrow();
   });
 
-  it('should accept $exist operator', () => {
-    expect(() => SpecialOperatorSchema.parse({ $exist: true })).not.toThrow();
-    expect(() => SpecialOperatorSchema.parse({ $exist: false })).not.toThrow();
+  it('should accept $exists operator', () => {
+    expect(() => SpecialOperatorSchema.parse({ $exists: true })).not.toThrow();
+    expect(() => SpecialOperatorSchema.parse({ $exists: false })).not.toThrow();
   });
 });
 
@@ -158,7 +158,7 @@ describe('FieldOperatorsSchema', () => {
       $startsWith: 'prefix',
       $endsWith: 'suffix',
       $null: false,
-      $exist: true,
+      $exists: true,
     };
     expect(() => FieldOperatorsSchema.parse(filter)).not.toThrow();
   });
@@ -367,7 +367,7 @@ describe('QueryFilterSchema - Complete Examples', () => {
         
         // Special
         deletedAt: { $null: true },
-        metadata: { $exist: true },
+        metadata: { $exists: true },
         
         // Logical
         $or: [
@@ -472,7 +472,7 @@ describe('Filter Operator Constants', () => {
     expect(FILTER_OPERATORS).toContain('$startsWith');
     expect(FILTER_OPERATORS).toContain('$endsWith');
     expect(FILTER_OPERATORS).toContain('$null');
-    expect(FILTER_OPERATORS).toContain('$exist');
+    expect(FILTER_OPERATORS).toContain('$exists');
   });
 
   it('should export all logical operators', () => {
diff --git a/packages/spec/src/data/filter.zod.ts b/packages/spec/src/data/filter.zod.ts
@@ -129,7 +129,7 @@ export const SpecialOperatorSchema = z.object({
   $null: z.boolean().optional(),
   
   /** Field exists check (primarily for NoSQL) - MongoDB: $exists */
-  $exist: z.boolean().optional(),
+  $exists: z.boolean().optional(),
 });
 
 // ============================================================================
@@ -166,7 +166,7 @@ export const FieldOperatorsSchema = z.object({
   
   // Special
   $null: z.boolean().optional(),
-  $exist: z.boolean().optional(),
+  $exists: z.boolean().optional(),
 });
 
 // ============================================================================
@@ -273,7 +273,7 @@ export type Filter<T = any> = {
         $startsWith?: T[K] extends string ? string : never;
         $endsWith?: T[K] extends string ? string : never;
         $null?: boolean;
-        $exist?: boolean;
+        $exists?: boolean;
       }
     | (T[K] extends object ? Filter<T[K]> : never);  // Nested relation
 } & {
@@ -351,7 +351,7 @@ export const FILTER_OPERATORS = [
   // String
   '$contains', '$startsWith', '$endsWith',
   // Special
-  '$null', '$exist',
+  '$null', '$exists',
 ] as const;
 
 /**
diff --git a/packages/spec/src/data/hook.zod.ts b/packages/spec/src/data/hook.zod.ts
@@ -64,7 +64,7 @@ export const HookSchema = z.object({
    * Handler Logic
    * Reference to a registered function in the plugin system OR a direct function (runtime only).
    */
-  handler: z.union([z.string(), z.any()]).optional().describe('Function handler name or direct function'),
+  handler: z.union([z.string(), z.function()]).optional().describe('Handler function name (string) or inline function reference'),
 
   /**
    * Execution Order
diff --git a/packages/spec/src/data/validation.zod.ts b/packages/spec/src/data/validation.zod.ts
@@ -338,7 +338,21 @@ export const CustomValidatorSchema = BaseValidationSchema.extend({
 /**
  * 9. Master Validation Rule Schema
  */
-export const ValidationRuleSchema: z.ZodType<any> = z.lazy(() =>
+/** Base type for validation rules - used for z.lazy() recursive type annotation */
+export interface BaseValidationRuleShape {
+  type: string;
+  name: string;
+  message: string;
+  label?: string;
+  description?: string;
+  active?: boolean;
+  events?: ('insert' | 'update' | 'delete')[];
+  tags?: string[];
+  severity?: 'error' | 'warning' | 'info';
+  [key: string]: unknown;
+}
+
+export const ValidationRuleSchema: z.ZodType<BaseValidationRuleShape> = z.lazy(() =>
   z.discriminatedUnion('type', [
     ScriptValidationSchema,
     UniquenessValidationSchema,
diff --git a/packages/spec/src/kernel/plugin-lifecycle-events.test.ts b/packages/spec/src/kernel/plugin-lifecycle-events.test.ts
@@ -68,7 +68,7 @@ describe('Plugin Lifecycle Events Protocol', () => {
       const event = {
         pluginName: 'failing-plugin',
         timestamp: Date.now(),
-        error: new Error('Connection failed'),
+        error: { name: 'Error', message: 'Connection failed' },
         phase: 'start' as const,
         errorMessage: 'Connection failed',
       };
@@ -81,7 +81,7 @@ describe('Plugin Lifecycle Events Protocol', () => {
       const event = {
         pluginName: 'failing-plugin',
         timestamp: Date.now(),
-        error: new Error('Connection failed'),
+        error: { name: 'Error', message: 'Connection failed' },
         // missing phase
       };
 
diff --git a/packages/spec/src/kernel/plugin-lifecycle-events.zod.ts b/packages/spec/src/kernel/plugin-lifecycle-events.zod.ts
@@ -102,7 +102,12 @@ export const PluginErrorEventSchema = PluginEventBaseSchema.extend({
   /**
    * Error object
    */
-  error: z.instanceof(Error).describe('Error object'),
+  error: z.object({
+    name: z.string().describe('Error class name'),
+    message: z.string().describe('Error message'),
+    stack: z.string().optional().describe('Stack trace'),
+    code: z.string().optional().describe('Error code'),
+  }).describe('Serializable error representation'),
   
   /**
    * Lifecycle phase where error occurred
diff --git a/packages/spec/src/kernel/startup-orchestrator.test.ts b/packages/spec/src/kernel/startup-orchestrator.test.ts
@@ -95,7 +95,7 @@ describe('Startup Orchestrator Protocol', () => {
         },
         success: false,
         duration: 500,
-        error: new Error('Connection failed'),
+        error: { name: 'Error', message: 'Connection failed' },
       };
 
       const result = PluginStartupResultSchema.safeParse(failedResult);
@@ -166,7 +166,7 @@ describe('Startup Orchestrator Protocol', () => {
             plugin: { name: 'plugin2' },
             success: false,
             duration: 850,
-            error: new Error('Startup failed'),
+            error: { name: 'Error', message: 'Startup failed' },
           },
         ],
         totalDuration: 2050,
diff --git a/packages/spec/src/kernel/startup-orchestrator.zod.ts b/packages/spec/src/kernel/startup-orchestrator.zod.ts
@@ -147,7 +147,12 @@ export const PluginStartupResultSchema = z.object({
   /**
    * Error if startup failed
    */
-  error: z.instanceof(Error).optional().describe('Error object if startup failed'),
+  error: z.object({
+    name: z.string().describe('Error class name'),
+    message: z.string().describe('Error message'),
+    stack: z.string().optional().describe('Stack trace'),
+    code: z.string().optional().describe('Error code'),
+  }).optional().describe('Serializable error representation if startup failed'),
   
   /**
    * Health status after startup (if healthCheck enabled)
diff --git a/packages/spec/src/system/auth-config.zod.ts b/packages/spec/src/system/auth-config.zod.ts
@@ -31,7 +31,4 @@ export const AuthConfigSchema = z.object({
     expiresIn: z.number().default(60 * 60 * 24 * 7).describe('Session duration in seconds'),
     updateAge: z.number().default(60 * 60 * 24).describe('Session update frequency'),
   }).optional(),
-  
-  // Custom auth properties
-  [z.string().regex(/^[^A-Z]+$/).toString()]: z.any().optional(),
-});
+}).catchall(z.unknown());

Original file line number	Diff line number	Diff line change
`@@ -175,7 +175,7 @@`
`175`	`175`	`"$null": {`
`176`	`176`	`"type": "boolean"`
`177`	`177`	`},`
`178`		`- "$exist": {`
	`178`	`+ "$exists": {`
`179`	`179`	`"type": "boolean"`
`180`	`180`	`}`
`181`	`181`	`},`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`"$null": {`
`8`	`8`	`"type": "boolean"`
`9`	`9`	`},`
`10`		`- "$exist": {`
	`10`	`+ "$exists": {`
`11`	`11`	`"type": "boolean"`
`12`	`12`	`}`
`13`	`13`	`},`
Original file line number	Diff line number	Diff line change
`@@ -90,10 +90,9 @@`
`90`	`90`	`}`
`91`	`91`	`},`
`92`	`92`	`"additionalProperties": false`
`93`		`- },`
`94`		`- "[object Object]": {}`
	`93`	`+ }`
`95`	`94`	`},`
`96`		`- "additionalProperties": false`
	`95`	`+ "additionalProperties": {}`
`97`	`96`	`}`
`98`	`97`	`},`
`99`	`98`	`"$schema": "http://json-schema.org/draft-07/schema#"`