@teleporthq/teleport-plugin-next-workflows 0.43.1

package/__tests__/data-api-anon-user-id-fallback.test.ts

@@ -0,0 +1,265 @@
+import { generateDataAPIRoute } from '../src/data-api-route-generator'
+
+// Regression guard for "guest places order, lands on
+// /order-details/<num>, then bounces to home before the page can
+// load". Root cause: `coerceUuidColumnValue` was NULL'ing the
+// "user" / "" sentinel that the AI-generated workflow stamps on
+// `teleport_orders.user_id` for a not-signed-in buyer. With
+// user_id = NULL, the page-load SQL
+// `WHERE user_id::text = anonymousUserId` returns 0 rows, the
+// post-SQL `found === true` IF takes its FALSE branch, and the
+// navigation-go-to-page node sends the buyer home before the
+// order they just paid for can render.
+//
+// The fix: `data-create-item` / `data-update-item` now scan the
+// workflow context for a resolve-user output and forward the
+// `anonymousUserId` to the data-api as `body.__anonymousUserId`.
+// The data-api's coercion helper substitutes that UUID for any
+// non-UUID string destined for a `user_id`-shaped ownership
+// column (`user_id`, `*_user_id`). Non-ownership uuid foreign
+// keys still get the safer "drop garbage to NULL" treatment so
+// we don't invent a non-existent reference for an unrelated FK.
+
+const extractFunctionSource = (haystack: string, funcDecl: string): string => {
+  const startIdx = haystack.indexOf(funcDecl)
+  if (startIdx === -1) {
+    throw new Error('Helper not found: ' + funcDecl)
+  }
+  let depth = 0
+  let i = haystack.indexOf('{', startIdx)
+  if (i === -1) {
+    throw new Error('No opening brace after ' + funcDecl)
+  }
+  for (; i < haystack.length; i++) {
+    const ch = haystack.charAt(i)
+    if (ch === '{') {
+      depth++
+    } else if (ch === '}') {
+      depth--
+      if (depth === 0) {
+        return haystack.slice(startIdx, i + 1)
+      }
+    }
+  }
+  throw new Error('Unbalanced braces for ' + funcDecl)
+}
+
+describe('data-api route generator: anonymousUserId fallback', () => {
+  const code = generateDataAPIRoute()
+
+  it('emits the ownership-column predicate', () => {
+    // Pin the column-shape detection so a refactor can't silently
+    // expand it to non-ownership columns (which would corrupt
+    // unrelated UUID FKs by aliasing them to the anon user).
+    expect(code).toContain('function isUserOwnershipColumn')
+    expect(code).toContain("if (col === 'user_id') return true")
+    expect(code).toContain("col.lastIndexOf('_user_id') === col.length - 8")
+  })
+
+  it('coerceUuidColumnValue accepts the fallback as a 4th argument', () => {
+    // Old signature was (col, val, colTypes). The new 4th
+    // argument carries the workflow's anonymousUserId hint.
+    expect(code).toContain(
+      'function coerceUuidColumnValue(col, val, colTypes, anonymousUserIdFallback)'
+    )
+  })
+
+  it('handleCreate reads body.__anonymousUserId and passes it through to coercion', () => {
+    expect(code).toContain('var anonymousUserIdFallback = body.__anonymousUserId')
+    expect(code).toContain('coerceUuidColumnValue(col, val, colTypes, anonymousUserIdFallback)')
+  })
+
+  it('handleUpdate reads body.__anonymousUserId and passes it through to coercion', () => {
+    const updateBody = code.slice(
+      code.indexOf('async function handleUpdate'),
+      code.indexOf('async function handleDelete')
+    )
+    expect(updateBody).toContain('var anonymousUserIdFallback = body.__anonymousUserId')
+    expect(updateBody).toContain(
+      'coerceUuidColumnValue(col, val, colTypes, anonymousUserIdFallback)'
+    )
+  })
+
+  it('substitutes the fallback UUID for `user_id` when the value is a non-UUID string', () => {
+    // Spin up the helper in a sandbox and exercise the contract:
+    // the "user" sentinel for `user_id` becomes the anon UUID
+    // when a valid one is provided.
+    const helperSource = extractFunctionSource(code, 'function coerceUuidColumnValue')
+    const predicateSource = extractFunctionSource(code, 'function isUserOwnershipColumn')
+    const uuidReSource =
+      'var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;'
+    const factory = new Function(
+      uuidReSource +
+        '\n' +
+        predicateSource +
+        '\n' +
+        helperSource +
+        '\nreturn coerceUuidColumnValue;'
+    )
+    const coerce = factory() as (
+      col: string,
+      val: unknown,
+      colTypes: Record<string, string>,
+      anon?: string
+    ) => unknown
+
+    const ANON = '11111111-2222-3333-4444-555555555555'
+    const colTypes = {
+      user_id: 'uuid',
+      created_by_user_id: 'uuid',
+      pickup_location_id: 'uuid',
+      notes: 'text',
+    }
+
+    // user_id gets the anon UUID when sentinel + fallback present.
+    expect(coerce('user_id', 'user', colTypes, ANON)).toBe(ANON)
+    expect(coerce('user_id', '', colTypes, ANON)).toBe(ANON)
+    expect(coerce('user_id', 'anonymous', colTypes, ANON)).toBe(ANON)
+    expect(coerce('user_id', 'guest', colTypes, ANON)).toBe(ANON)
+
+    // *_user_id columns (e.g. created_by_user_id) follow the same rule.
+    expect(coerce('created_by_user_id', 'user', colTypes, ANON)).toBe(ANON)
+
+    // A real UUID coming in is kept verbatim regardless of fallback.
+    const real = '550e8400-e29b-41d4-a716-446655440000'
+    expect(coerce('user_id', real, colTypes, ANON)).toBe(real)
+  })
+
+  it('falls back to NULL for non-ownership uuid columns even when fallback is present', () => {
+    // Non-ownership UUID FK columns must NOT get the anon UUID
+    // substituted in — that would invent a foreign-key reference
+    // to a row that doesn't exist (e.g. pickup_location_id =
+    // <anon UUID> would point at a non-existent pickup location).
+    const helperSource = extractFunctionSource(code, 'function coerceUuidColumnValue')
+    const predicateSource = extractFunctionSource(code, 'function isUserOwnershipColumn')
+    const uuidReSource =
+      'var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;'
+    const factory = new Function(
+      uuidReSource +
+        '\n' +
+        predicateSource +
+        '\n' +
+        helperSource +
+        '\nreturn coerceUuidColumnValue;'
+    )
+    const coerce = factory() as (
+      col: string,
+      val: unknown,
+      colTypes: Record<string, string>,
+      anon?: string
+    ) => unknown
+
+    const ANON = '11111111-2222-3333-4444-555555555555'
+    const colTypes = { user_id: 'uuid', pickup_location_id: 'uuid' }
+
+    expect(coerce('pickup_location_id', '', colTypes, ANON)).toBe(null)
+    expect(coerce('pickup_location_id', 'user', colTypes, ANON)).toBe(null)
+  })
+
+  it('ignores a non-UUID fallback rather than passing garbage to PG', () => {
+    // Belt and braces: even if someone constructs a request with
+    // `__anonymousUserId = "not-a-uuid"`, the helper must reject
+    // the substitution so PG never sees an invalid UUID.
+    const helperSource = extractFunctionSource(code, 'function coerceUuidColumnValue')
+    const predicateSource = extractFunctionSource(code, 'function isUserOwnershipColumn')
+    const uuidReSource =
+      'var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;'
+    const factory = new Function(
+      uuidReSource +
+        '\n' +
+        predicateSource +
+        '\n' +
+        helperSource +
+        '\nreturn coerceUuidColumnValue;'
+    )
+    const coerce = factory() as (
+      col: string,
+      val: unknown,
+      colTypes: Record<string, string>,
+      anon?: string
+    ) => unknown
+
+    const colTypes = { user_id: 'uuid' }
+    expect(coerce('user_id', 'user', colTypes, 'not-a-uuid')).toBe(null)
+    expect(coerce('user_id', 'user', colTypes, '')).toBe(null)
+    expect(coerce('user_id', 'user', colTypes, undefined)).toBe(null)
+  })
+
+  it('still skips the id PK column regardless of fallback', () => {
+    // The id PK has its own auto-generate-a-fresh-UUID path
+    // elsewhere in handleCreate. The coercion helper must early-
+    // return on `id` so the PK's value is never replaced with the
+    // anon UUID.
+    const helperSource = extractFunctionSource(code, 'function coerceUuidColumnValue')
+    const predicateSource = extractFunctionSource(code, 'function isUserOwnershipColumn')
+    const uuidReSource =
+      'var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;'
+    const factory = new Function(
+      uuidReSource +
+        '\n' +
+        predicateSource +
+        '\n' +
+        helperSource +
+        '\nreturn coerceUuidColumnValue;'
+    )
+    const coerce = factory() as (
+      col: string,
+      val: unknown,
+      colTypes: Record<string, string>,
+      anon?: string
+    ) => unknown
+
+    expect(coerce('id', 'not-a-uuid', { id: 'uuid' }, '11111111-2222-3333-4444-555555555555')).toBe(
+      'not-a-uuid'
+    )
+  })
+})
+
+describe('data-create-item / data-update-item workflow handlers: anon-id hint', () => {
+  // The compiled package emits these handlers verbatim inside
+  // `node-handlers-server.js`. We can import the generators
+  // directly and check the emitted string.
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { dataCreateItem } = require('../src/nodes/data/data-create-item')
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { dataUpdateItem } = require('../src/nodes/data/data-update-item')
+
+  it('data-create-item scans context for anonymousUserId before POSTing', () => {
+    const src = dataCreateItem.generateHandler() as string
+    expect(src).toContain('__anonymousUserId')
+    expect(src).toContain('anonymousUserId')
+    expect(src).toContain('reqBody.__anonymousUserId = __anonymousUserId')
+  })
+
+  it('data-update-item scans context for anonymousUserId before PATCHing', () => {
+    const src = dataUpdateItem.generateHandler() as string
+    expect(src).toContain('__anonymousUserId')
+    expect(src).toContain('reqBody.__anonymousUserId = __anonymousUserId')
+  })
+
+  it('only forwards the hint when context carries a non-empty anonymousUserId', () => {
+    // Pin the conditional: the handler emits a guard that skips
+    // the hint when `__anonymousUserId` is empty, so a logged-in
+    // flow with empty anonymousUserId never sends it. We assert
+    // on the substring fragment that survives both ES5 and
+    // ES2017 ts-jest compilation targets — the
+    // `reqBody.__anonymousUserId = __anonymousUserId` assignment
+    // and an `if (__anonymousUserId)` guard.
+    const src = dataCreateItem.generateHandler() as string
+    expect(src).toContain('reqBody.__anonymousUserId = __anonymousUserId')
+    expect(/if\s*\(\s*__anonymousUserId\s*\)/.test(src)).toBe(true)
+
+    const updSrc = dataUpdateItem.generateHandler() as string
+    expect(updSrc).toContain('reqBody.__anonymousUserId = __anonymousUserId')
+    expect(/if\s*\(\s*__anonymousUserId\s*\)/.test(updSrc)).toBe(true)
+  })
+
+  it('skips empty / missing anonymousUserId entries during context scan', () => {
+    // The scan must NOT latch onto a node output whose
+    // anonymousUserId is the empty string (logged-in users get
+    // resolveUser({ ..., anonymousUserId: "" })). The emitted
+    // length check is the guard.
+    const src = dataCreateItem.generateHandler() as string
+    expect(src).toContain('__cv.anonymousUserId.length > 0')
+  })
+})

package/__tests__/data-api-low-stock-autofire.test.ts

@@ -0,0 +1,190 @@
+import { generateDataAPIRoute } from '../src/data-api-route-generator'
+
+// Regression guard for "merchant configured low-stock alerts but
+// no email arrives after a purchase". The workflow's place-order
+// chain decrements stock and then runs a follow-up SELECT to find
+// products at or below the threshold — but the AI-generated email-
+// payload node returns skip: true and never dispatches. We close
+// that gap from the data-api side: when handleRawQuery sees the
+// post-decrement SELECT pattern with rows, it fires a POST to
+// /api/ecommerce/low-stock-alert (the actual sender).
+//
+// Detection has to be precise enough to avoid false positives on
+// unrelated stock queries (e.g. an inventory dashboard SELECT).
+// We do that by requiring THREE signals in the SAME query string:
+// SELECT, FROM teleport_products, WHERE...quantity...<=
+
+const extractFn = (haystack: string, decl: string): string => {
+  const start = haystack.indexOf(decl)
+  if (start === -1) {
+    throw new Error('decl not found: ' + decl)
+  }
+  let depth = 0
+  let i = haystack.indexOf('{', start)
+  if (i === -1) {
+    throw new Error('no brace after ' + decl)
+  }
+  for (; i < haystack.length; i++) {
+    const ch = haystack.charAt(i)
+    if (ch === '{') {
+      depth++
+    } else if (ch === '}') {
+      depth--
+      if (depth === 0) {
+        return haystack.slice(start, i + 1)
+      }
+    }
+  }
+  throw new Error('unbalanced braces in ' + decl)
+}
+
+describe('data-api emits LOW_STOCK_ALERTS_ENABLED + threshold constants', () => {
+  it('emits LOW_STOCK_ALERTS_ENABLED = false by default', () => {
+    const code = generateDataAPIRoute()
+    expect(code).toContain('const LOW_STOCK_ALERTS_ENABLED = false')
+    expect(code).toContain('const LOW_STOCK_THRESHOLD = 5')
+  })
+
+  it('emits LOW_STOCK_ALERTS_ENABLED = true when option is set', () => {
+    const code = generateDataAPIRoute({ lowStockAlertsEnabled: true, lowStockThreshold: 12 })
+    expect(code).toContain('const LOW_STOCK_ALERTS_ENABLED = true')
+    expect(code).toContain('const LOW_STOCK_THRESHOLD = 12')
+  })
+
+  it('coerces a negative threshold to the safe default', () => {
+    const code = generateDataAPIRoute({ lowStockAlertsEnabled: true, lowStockThreshold: -1 })
+    expect(code).toContain('const LOW_STOCK_THRESHOLD = 5')
+  })
+})
+
+describe('looksLikeLowStockProductSelect — SQL pattern detector', () => {
+  const code = generateDataAPIRoute({ lowStockAlertsEnabled: true })
+  const detector = new Function(
+    `${extractFn(
+      code,
+      'function looksLikeLowStockProductSelect'
+    )}\nreturn looksLikeLowStockProductSelect;`
+  )() as (q: string) => boolean
+
+  it('matches the canonical post-decrement low-stock SELECT', () => {
+    const query =
+      "SELECT id, name, quantity AS stock, COALESCE(sku, '') AS sku FROM teleport_products " +
+      "WHERE quantity IS NOT NULL AND quantity <= 5 AND id IN ('a','b')"
+    expect(detector(query)).toBe(true)
+  })
+
+  it('matches even with lowercase and odd whitespace', () => {
+    expect(detector('select * from teleport_products where quantity<=3')).toBe(true)
+    expect(detector('SELECT\nx\nFROM teleport_products\nWHERE quantity <= 0')).toBe(true)
+  })
+
+  it('rejects an UPDATE that touches quantity (not a SELECT)', () => {
+    expect(detector("UPDATE teleport_products SET quantity = quantity - 1 WHERE id IN ('a')")).toBe(
+      false
+    )
+  })
+
+  it('rejects a SELECT on a different table', () => {
+    expect(detector('SELECT * FROM teleport_orders WHERE quantity <= 5')).toBe(false)
+  })
+
+  it('rejects a SELECT without a <= comparator on quantity', () => {
+    expect(detector('SELECT id FROM teleport_products WHERE quantity > 0')).toBe(false)
+  })
+
+  it('rejects empty / null / non-string queries', () => {
+    expect(detector('')).toBe(false)
+    expect(detector(null as any)).toBe(false)
+    expect(detector(123 as any)).toBe(false)
+  })
+})
+
+describe('extractThresholdFromQuery — read threshold from WHERE', () => {
+  const code = generateDataAPIRoute({ lowStockAlertsEnabled: true, lowStockThreshold: 5 })
+  const extractor = new Function(
+    `const LOW_STOCK_THRESHOLD = 5;\n${extractFn(
+      code,
+      'function extractThresholdFromQuery'
+    )}\nreturn extractThresholdFromQuery;`
+  )() as (q: string) => number
+
+  it('reads an integer threshold', () => {
+    expect(extractor('SELECT FROM teleport_products WHERE quantity <= 7')).toBe(7)
+  })
+
+  it('reads a float threshold', () => {
+    expect(extractor('SELECT FROM teleport_products WHERE quantity <= 0.5')).toBe(0.5)
+  })
+
+  it('falls back to LOW_STOCK_THRESHOLD when the comparison is via a placeholder', () => {
+    expect(extractor('SELECT FROM teleport_products WHERE quantity <= $1')).toBe(5)
+  })
+
+  it('falls back when the query has no <= at all', () => {
+    expect(extractor('SELECT * FROM teleport_products')).toBe(5)
+  })
+})
+
+describe('handleRawQuery — wires the auto-fire correctly', () => {
+  const code = generateDataAPIRoute({ lowStockAlertsEnabled: true, lowStockThreshold: 5 })
+
+  it('passes req to handleRawQuery from the dispatcher', () => {
+    // The dispatcher (case 'raw-query') must forward req so the
+    // auto-fire can derive the self base URL from the request
+    // host header. Without it we fall back to env vars only,
+    // which aren't set in typical dev.
+    expect(code).toContain('handleRawQuery(client, body, req)')
+  })
+
+  it('handleRawQuery accepts (client, body, req)', () => {
+    expect(code).toContain('async function handleRawQuery(client, body, req)')
+  })
+
+  it('only fires the alert under the three required guards', () => {
+    // Guard 1: LOW_STOCK_ALERTS_ENABLED at codegen time
+    // Guard 2: rows.length > 0 at request time
+    // Guard 3: looksLikeLowStockProductSelect at request time
+    expect(code).toContain(
+      'if (LOW_STOCK_ALERTS_ENABLED && rows.length > 0 && looksLikeLowStockProductSelect(query))'
+    )
+  })
+
+  it('the alert call is fire-and-forget — does NOT await the response', () => {
+    // The auto-fire MUST not block the data-api response back to
+    // the workflow. The workflow proceeds; the alert email is
+    // dispatched asynchronously by the alert endpoint.
+    const fireFn = extractFn(code, 'function fireAndForgetLowStockAlert')
+    expect(fireFn).not.toMatch(/await\s+fetchImpl\(/)
+    expect(fireFn).toContain('.catch(function(err)')
+  })
+
+  it('prefers the live request host, then falls back to NEXTAUTH_URL / VERCEL_URL', () => {
+    // Request host wins because NEXTAUTH_URL is a common source of
+    // dev foot-guns (stuck at :3000 while the actual dev server
+    // is on :3001 — the symptom is a silent "fetch failed" from
+    // the fire-and-forget call). Env vars cover the rare
+    // serverless background-work case where the request context
+    // isn't visible.
+    const resolveFn = extractFn(code, 'function resolveSelfBaseUrl')
+    expect(resolveFn).toContain('req && req.headers && req.headers.host')
+    expect(resolveFn).toContain('process.env.NEXTAUTH_URL')
+    expect(resolveFn).toContain('process.env.VERCEL_URL')
+    // Order matters: req.headers.host check must appear BEFORE
+    // the env var checks.
+    const hostIdx = resolveFn.indexOf('req.headers.host')
+    const envIdx = resolveFn.indexOf('process.env.NEXTAUTH_URL')
+    expect(hostIdx).toBeGreaterThan(0)
+    expect(envIdx).toBeGreaterThan(hostIdx)
+  })
+
+  it('skips the auto-fire when LOW_STOCK_ALERTS_ENABLED is false (no flag, no detection cost)', () => {
+    const noopCode = generateDataAPIRoute({ lowStockAlertsEnabled: false })
+    expect(noopCode).toContain('const LOW_STOCK_ALERTS_ENABLED = false')
+    // The guard still appears (single conditional), so the
+    // short-circuit is a no-op at runtime — what matters is that
+    // the flag wins.
+    expect(noopCode).toContain(
+      'if (LOW_STOCK_ALERTS_ENABLED && rows.length > 0 && looksLikeLowStockProductSelect(query))'
+    )
+  })
+})

package/__tests__/data-api-safe-query.test.ts

@@ -0,0 +1,202 @@
+import { generateDataAPIRoute } from '../src/data-api-route-generator'
+
+// Regression guard for "Stripe webhook 500s because metadata.orderId
+// is empty string and the workflow's SELECT runs `WHERE id = ''` —
+// Postgres rejects with `22P02 invalid input syntax for type uuid`".
+//
+// The generic fix lives in /api/data/[...params].js: every
+// `client.query()` that filters on user-supplied values is wrapped
+// in a `safeQuery` helper that catches the small set of Postgres
+// type-coercion error codes (UUID, integer, date, numeric out of
+// range, parameter type mismatch) and degrades to an empty result
+// instead of throwing. Empty results are the correct semantics for
+// the "filter value would never have matched a real row anyway"
+// case — and they let upstream workflow code take its "not found"
+// branch cleanly instead of crashing the request.
+
+describe('data-api safeQuery wrapper — defends against Postgres type-coercion errors', () => {
+  const code = generateDataAPIRoute()
+
+  it('emits a SAFE_COERCION_ERROR_CODES set listing every code we degrade for', () => {
+    expect(code).toContain('SAFE_COERCION_ERROR_CODES')
+    // 22P02 = invalid_text_representation (uuid / integer / json coercion failure)
+    expect(code).toContain("'22P02'")
+    // 22008 = datetime out of range
+    expect(code).toContain("'22008'")
+    // 22003 = numeric out of range
+    expect(code).toContain("'22003'")
+    // 22023 = invalid parameter value (e.g. wrong parameter shape)
+    expect(code).toContain("'22023'")
+  })
+
+  it('emits a safeQuery helper that returns empty rows for SELECT mode', () => {
+    expect(code).toContain('async function safeQuery(client, sql, params, mode)')
+    expect(code).toMatch(/return\s*\{\s*rows:\s*\[\s*\],\s*rowCount:\s*0\s*\}/)
+  })
+
+  it('emits a count-specific empty result so callers parsing rows[0].count still work', () => {
+    // The COUNT path reads `result.rows[0].count` — returning `rows: []`
+    // would crash with "Cannot read properties of undefined" downstream.
+    // safeQuery must give the count caller `rows: [{ count: '0' }]`.
+    expect(code).toMatch(/rows:\s*\[\s*\{\s*count:\s*'0'\s*\}\s*\]/)
+  })
+
+  it('logs the suppressed error with the SQL and params so the user can still diagnose', () => {
+    // We deliberately don't swallow silently — the warn lets the merchant
+    // figure out which upstream node fed in the bad value.
+    expect(code).toContain('[data-api] suppressed Postgres coercion error')
+    expect(code).toContain('JSON.stringify(params)')
+  })
+
+  it('rethrows errors with codes outside the safe set so real bugs still surface', () => {
+    expect(code).toContain('throw err')
+  })
+
+  it('handleSelect routes the main query through safeQuery', () => {
+    expect(code).toMatch(
+      /var\s+result\s*=\s*await\s+safeQuery\(client,\s*sql,\s*queryParams,\s*'select'\)/
+    )
+  })
+
+  it('handleSelect routes the COUNT query through safeQuery', () => {
+    expect(code).toMatch(/safeQuery\(client,\s*countSql,\s*countParams,\s*'count'\)/)
+  })
+
+  it('handleCount routes its query through safeQuery', () => {
+    expect(code).toMatch(/safeQuery\(client,\s*sql,\s*queryParams,\s*'count'\)/)
+  })
+
+  it('handleUpdate routes its query through safeQuery (degrades to 0 updated)', () => {
+    expect(code).toMatch(/safeQuery\(client,\s*sql,\s*queryParams,\s*'update'\)/)
+  })
+
+  it('handleDelete routes its query through safeQuery', () => {
+    expect(code).toMatch(/safeQuery\(client,\s*sql,\s*queryParams,\s*'delete'\)/)
+  })
+
+  it('handleRawQuery routes through safeQuery so workflow-level raw SELECTs also degrade gracefully', () => {
+    expect(code).toMatch(/safeQuery\(client,\s*query,\s*\[\s*\],\s*'raw-query'\)/)
+  })
+
+  it('handleCreate is NOT wrapped (an INSERT failing on a bad UUID is a real error, not "no match")', () => {
+    // The INSERT path already has its own UUID coercion (the previous
+    // regression). Wrapping it would mask a programming bug where the
+    // caller sends an invalid UUID *value* — that should still 500.
+    // Check by counting safeQuery occurrences and confirming the
+    // INSERT site is NOT among them.
+    const insertSection = code.slice(
+      code.indexOf('async function handleCreate'),
+      code.indexOf('async function handleUpdate')
+    )
+    expect(insertSection).not.toContain('safeQuery(')
+    // The plain client.query in handleCreate must still be present
+    expect(insertSection).toMatch(/await\s+client\.query\(sql,\s*values\)/)
+  })
+})
+
+describe('data-api safeQuery — runtime semantics', () => {
+  const code = generateDataAPIRoute()
+  // Eval the safeQuery helper out of the emitted file and verify it
+  // behaves as we expect against a fake client.
+  const evalFn = () => {
+    const startTag = 'async function safeQuery'
+    const start = code.indexOf(startTag)
+    // Find the matching closing brace via depth counting
+    let depth = 0
+    let i = code.indexOf('{', start)
+    for (; i < code.length; i++) {
+      if (code[i] === '{') {
+        depth++
+      } else if (code[i] === '}') {
+        depth--
+        if (depth === 0) {
+          break
+        }
+      }
+    }
+    const fnSrc = code.slice(start, i + 1)
+    // Also extract the SAFE_COERCION_ERROR_CODES constant
+    const codesStart = code.indexOf('var SAFE_COERCION_ERROR_CODES')
+    const codesEnd = code.indexOf(';', codesStart)
+    const codesSrc = code.slice(codesStart, codesEnd + 1)
+    return new Function(codesSrc + '\n' + fnSrc + '\nreturn safeQuery;')() as any
+  }
+  const safeQuery = evalFn()
+
+  it('returns rows:[] when client.query throws code 22P02', async () => {
+    const fakeClient = {
+      query: async () => {
+        const e: any = new Error('invalid input syntax for type uuid: ""')
+        e.code = '22P02'
+        throw e
+      },
+    }
+    const r = await safeQuery(fakeClient, 'SELECT *', [], 'select')
+    expect(r).toEqual({ rows: [], rowCount: 0 })
+  })
+
+  it('returns count "0" envelope for count mode', async () => {
+    const fakeClient = {
+      query: async () => {
+        const e: any = new Error('invalid')
+        e.code = '22P02'
+        throw e
+      },
+    }
+    const r = await safeQuery(fakeClient, 'SELECT COUNT(*)', [], 'count')
+    expect(r.rows[0].count).toBe('0')
+  })
+
+  it('rethrows non-coercion errors verbatim (real bugs still surface)', async () => {
+    const fakeClient = {
+      query: async () => {
+        const e: any = new Error('relation "missing" does not exist')
+        e.code = '42P01'
+        throw e
+      },
+    }
+    await expect(safeQuery(fakeClient, 'SELECT *', [], 'select')).rejects.toThrow(
+      /relation "missing"/
+    )
+  })
+
+  it('passes through successful results', async () => {
+    const fakeClient = {
+      query: async () => ({ rows: [{ a: 1 }], rowCount: 1 }),
+    }
+    const r = await safeQuery(fakeClient, 'SELECT *', [], 'select')
+    expect(r.rowCount).toBe(1)
+    expect(r.rows[0].a).toBe(1)
+  })
+
+  it('also degrades on 22008 (datetime out of range)', async () => {
+    const fakeClient = {
+      query: async () => {
+        const e: any = new Error('bad date')
+        e.code = '22008'
+        throw e
+      },
+    }
+    expect((await safeQuery(fakeClient, 'SELECT', [], 'select')).rows).toEqual([])
+  })
+
+  it('also degrades on 22003 (numeric out of range)', async () => {
+    const fakeClient = {
+      query: async () => {
+        const e: any = new Error('numeric')
+        e.code = '22003'
+        throw e
+      },
+    }
+    expect((await safeQuery(fakeClient, 'SELECT', [], 'select')).rows).toEqual([])
+  })
+
+  it('does NOT swallow a coercion error that has no code (e.g. arbitrary throw)', async () => {
+    const fakeClient = {
+      query: async () => {
+        throw new Error('plain')
+      },
+    }
+    await expect(safeQuery(fakeClient, 'SELECT', [], 'select')).rejects.toThrow('plain')
+  })
+})