fix: address coderabbit review on #693

- translateExplainError now catches $N and :name bind errors too, not
  just bare `?`. Detects a syntax-error keyword plus a bind token
  delimited by whitespace or quotes, covering PG, Snowflake and Oracle
  phrasings. Adds "there is no parameter $N" (PostgreSQL).
- NO_SCHEMA_NOTE documents the flat table-map shape actually accepted
  by the tool, not the verbose SchemaDefinition shape.
- Regression tests added for $1, :name, and the NO_SCHEMA wording.

Author: anandgupta42

packages/opencode/src/altimate/native/connections/register.ts

@@ -299,9 +299,26 @@ export function translateExplainError(
     return "No warehouses are configured. Run `warehouse_add` to set one up before calling sql_explain."
   }
 
-  // Unsubstituted-placeholder compilation errors from Snowflake / PG / MySQL.
-  if (/syntax error.*unexpected\s*\?/i.test(msg) || /syntax error.*position\s+\d+.*\?/i.test(msg)) {
-    return "SQL compilation error: the query contains an unsubstituted `?` placeholder. sql_explain does not support parameterized queries — inline the literal value before calling."
+  // Unsubstituted-placeholder compilation errors.
+  //
+  // Bind placeholders come in three flavours: positional `?` (MySQL / JDBC),
+  // numbered `$1`, `$2`, ... (PostgreSQL), and named `:name` (Oracle / SQLite /
+  // some SQLAlchemy dialects). Drivers phrase the resulting syntax error in
+  // many different ways — Snowflake says "unexpected ?", PostgreSQL says
+  // `syntax error at or near "$1"`, Oracle says `ORA-00911: invalid character`,
+  // etc. Rather than enumerate every phrasing, detect a bind-token next to a
+  // syntax-error keyword and translate them all to the same guidance.
+  const isSyntaxError = /syntax error|invalid character|unexpected token/i.test(msg)
+  // Match a bind token that is delimited by whitespace, start/end, or a quote.
+  // The negative lookbehind `(?<!\w)` prevents matching `$1` inside identifiers.
+  const containsBindToken =
+    /(?<!\w)\?(?!\w)/.test(msg) ||
+    /(?<!\w)\$\d+/.test(msg) ||
+    /(?<!\w):[a-zA-Z_]\w*/.test(msg)
+  // PostgreSQL surfaces bind-param issues with its own distinctive phrasing.
+  const isPgBindError = /there is no parameter \$\d+/i.test(msg)
+  if ((isSyntaxError && containsBindToken) || isPgBindError) {
+    return "SQL compilation error: the query contains an unsubstituted bind placeholder (`?`, `$1`, or `:name`). sql_explain does not support parameterized queries — inline the literal values before calling."
   }
 
   // Snowflake-specific: ANALYZE not supported.

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

@@ -77,10 +77,15 @@ function classifyValidationError(message: string): string {
 // Warning appended when validation runs without a schema. Stored without a
 // leading blank so it can be pushed into a line array; a blank line is added
 // explicitly at each call site where spacing is desired.
+//
+// The hint uses the flat table-map shape accepted by the tool (see
+// schema-resolver.ts), not the verbose SchemaDefinition form — callers that
+// already know the inner Rust struct layout can use either, but the flat form
+// is strictly easier to construct inline.
 const NO_SCHEMA_NOTE =
   "Note: No schema was provided, so table/column existence checks were skipped. " +
   "To catch missing tables or columns, run `schema_inspect` on the referenced tables first " +
-  "or pass `schema_context` inline with {tables: {...}}."
+  'or pass `schema_context` inline as a table map, for example `{ users: { id: "INTEGER", email: "VARCHAR" } }`.'
 
 function formatValidate(data: Record<string, any>, hasSchema: boolean): string {
   if (data.error) return `Error: ${data.error}`

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

@@ -153,6 +153,16 @@ describe("formatValidate", () => {
     expect(result).toContain("No schema was provided")
     expect(result).not.toContain("\n\n\n")
   })
+
+  test("no-schema note recommends the flat table-map shape, not {tables: {...}}", () => {
+    // Regression: an earlier draft of the note documented the verbose
+    // SchemaDefinition shape `{tables: {...}}`, but the tool's examples and
+    // tests use the flat `{users: {...}}` shape. Using the wrong shape in
+    // the hint would send callers down a rabbit hole.
+    const result = formatValidate({ valid: true }, false)
+    expect(result).not.toContain("{tables:")
+    expect(result).toMatch(/users.*INTEGER/)
+  })
 })
 
 // ---------------------------------------------------------------------------

packages/opencode/test/altimate/tools/sql-explain.test.ts

@@ -296,8 +296,35 @@ describe("translateExplainError", () => {
       "snowflake",
       ["snowflake"],
     )
-    expect(result).toContain("unsubstituted `?` placeholder")
-    expect(result).toContain("inline the literal value")
+    expect(result).toContain("unsubstituted bind placeholder")
+    expect(result).toContain("inline the literal values")
+  })
+
+  test("translates `$1` numbered placeholder compile errors (PostgreSQL style)", () => {
+    const result = translateExplainError(
+      new Error("syntax error at or near \"$1\" at position 24"),
+      "postgres",
+      ["postgres"],
+    )
+    expect(result).toContain("unsubstituted bind placeholder")
+  })
+
+  test("translates `:name` named placeholder compile errors", () => {
+    const result = translateExplainError(
+      new Error("syntax error, unexpected :userid near position 31"),
+      "oracle",
+      ["oracle"],
+    )
+    expect(result).toContain("unsubstituted bind placeholder")
+  })
+
+  test("translates PostgreSQL 'no parameter $N' errors", () => {
+    const result = translateExplainError(
+      new Error('there is no parameter $1'),
+      "postgres",
+      ["postgres"],
+    )
+    expect(result).toContain("unsubstituted bind placeholder")
   })
 
   test("translates EXPLAIN ANALYZE-not-supported errors", () => {