fix: [AI-5975] address code review findings for tool wrappers

- Add contract documentation to `ok()` explaining `success` semantics
- Make `extractEquivalenceErrors` and `extractSemanticsErrors` defensive
  against object-type `validation_errors` entries
- Apply `isRealFailure` pattern to validate tool for consistent error handling

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

Author: suryaiyer95

packages/opencode/src/altimate/native/altimate-core.ts

@@ -25,7 +25,14 @@ function toData(obj: unknown): Record<string, unknown> {
   return JSON.parse(JSON.stringify(obj)) as Record<string, unknown>
 }
 
-/** Wrap a handler body into the standard AltimateCoreResult envelope. */
+/**
+ * Wrap a handler body into the standard AltimateCoreResult envelope.
+ *
+ * Contract: ok(true, data) means "the operation completed." Semantic results
+ * (e.g., SQL is invalid, queries are not equivalent) live in the data fields,
+ * NOT in the success flag. success=false only when the handler throws (fail()).
+ * This prevents semantic findings from being misreported as tool crashes.
+ */
 function ok(
   success: boolean,
   data: Record<string, unknown>,

packages/opencode/src/altimate/tools/altimate-core-equivalence.ts

@@ -42,7 +42,9 @@ export const AltimateCoreEquivalenceTool = Tool.define("altimate_core_equivalenc
 
 function extractEquivalenceErrors(data: Record<string, any>): string | undefined {
   if (Array.isArray(data.validation_errors) && data.validation_errors.length > 0) {
-    const msgs = data.validation_errors.filter(Boolean)
+    const msgs = data.validation_errors
+      .map((e: any) => (typeof e === "string" ? e : e.message ?? String(e)))
+      .filter(Boolean)
     return msgs.length > 0 ? msgs.join("; ") : undefined
   }
   return undefined

packages/opencode/src/altimate/tools/altimate-core-semantics.ts

@@ -39,7 +39,9 @@ export const AltimateCoreSemanticsTool = Tool.define("altimate_core_semantics",
 
 function extractSemanticsErrors(data: Record<string, any>): string | undefined {
   if (Array.isArray(data.validation_errors) && data.validation_errors.length > 0) {
-    const msgs = data.validation_errors.filter(Boolean)
+    const msgs = data.validation_errors
+      .map((e: any) => (typeof e === "string" ? e : e.message ?? String(e)))
+      .filter(Boolean)
     return msgs.length > 0 ? msgs.join("; ") : undefined
   }
   return undefined

packages/opencode/src/altimate/tools/altimate-core-validate.ts

@@ -24,9 +24,10 @@ export const AltimateCoreValidateTool = Tool.define("altimate_core_validate", {
       })
       const data = (result.data ?? {}) as Record<string, any>
       const error = result.error ?? data.error ?? extractValidationErrors(data)
+      const isRealFailure = !!error
       return {
-        title: `Validate: ${data.valid ? "VALID" : "INVALID"}`,
-        metadata: { success: result.success, valid: data.valid, ...(error && { error }) },
+        title: isRealFailure ? "Validate: ERROR" : `Validate: ${data.valid ? "VALID" : "INVALID"}`,
+        metadata: { success: !isRealFailure, valid: data.valid, ...(error && { error }) },
         output: formatValidate(data),
       }
     } catch (e) {