refactor(core): add Zod validation to metadata loading (Priority 3)

Following TypeScript Standards Rule #2: No Type Assertions Without Validation

Changes:
- Created validation schema (packages/core/src/storage/validation.ts)
  * RepositoryMetadataSchema with nested objects
  * validateRepositoryMetadata() helper

- Replaced type assertion in metadata.ts
  * Before: JSON.parse(content) as RepositoryMetadata
  * After: validateRepositoryMetadata(JSON.parse(content))

Impact:
- Protects against corrupted metadata.json files
- Returns null on validation failure (existing error handling)
- All 1739 tests passing ✅

Scope: State file validation (metadata only, LOW RISK boundary)

Note: Indexer state files are more complex and would require significant
refactoring. This completes validation for the primary metadata file.

Author: prosdev

packages/core/package.json

@@ -30,9 +30,9 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "tree-sitter-wasms": "^0.1.13",
     "@types/mdast": "^4.0.4",
     "@types/node": "^24.10.1",
+    "tree-sitter-wasms": "^0.1.13",
     "typescript": "^5.3.3"
   },
   "dependencies": {
@@ -45,6 +45,7 @@
     "remark-stringify": "^11.0.0",
     "ts-morph": "^27.0.2",
     "unified": "^11.0.5",
-    "web-tree-sitter": "^0.25.10"
+    "web-tree-sitter": "^0.25.10",
+    "zod": "^4.1.13"
   }
 }

packages/core/src/storage/metadata.ts

@@ -7,6 +7,7 @@ import { execSync } from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { getGitRemote, normalizeGitRemote } from './path';
+import { validateRepositoryMetadata } from './validation.js';
 
 export interface RepositoryMetadata {
   version: string;
@@ -73,7 +74,9 @@ export async function loadMetadata(storagePath: string): Promise<RepositoryMetad
   const metadataPath = path.join(storagePath, 'metadata.json');
   try {
     const content = await fs.readFile(metadataPath, 'utf-8');
-    return JSON.parse(content) as RepositoryMetadata;
+    const data = JSON.parse(content);
+    const validated = validateRepositoryMetadata(data);
+    return validated as RepositoryMetadata | null;
   } catch {
     return null;
   }

packages/core/src/storage/validation.ts

@@ -0,0 +1,52 @@
+/**
+ * State File Validation Utilities
+ *
+ * Following TypeScript Standards Rule #2: No Type Assertions Without Validation
+ * State files (JSON) must be validated at runtime to handle corruption/format changes
+ */
+
+import { z } from 'zod';
+
+/**
+ * Repository metadata schema
+ */
+export const RepositoryMetadataSchema = z.object({
+  version: z.string(),
+  repository: z.object({
+    path: z.string(),
+    remote: z.string().optional(),
+    branch: z.string().optional(),
+    lastCommit: z.string().optional(),
+  }),
+  indexed: z
+    .object({
+      timestamp: z.string(),
+      files: z.number().int().nonnegative(),
+      components: z.number().int().nonnegative(),
+      size: z.number().int().nonnegative(),
+    })
+    .optional(),
+  config: z
+    .object({
+      languages: z.array(z.string()).optional(),
+      excludePatterns: z.array(z.string()).optional(),
+    })
+    .optional(),
+  migrated: z
+    .object({
+      timestamp: z.string(),
+      from: z.string(),
+    })
+    .optional(),
+});
+
+export type RepositoryMetadataData = z.infer<typeof RepositoryMetadataSchema>;
+
+/**
+ * Validate repository metadata from JSON
+ * Returns null if validation fails (for backward compatibility with current error handling)
+ */
+export function validateRepositoryMetadata(data: unknown): RepositoryMetadataData | null {
+  const result = RepositoryMetadataSchema.safeParse(data);
+  return result.success ? result.data : null;
+}