TML-3167: Split SQL query and execute driver SPI - #29907

Linked issue

Refs TML-3167

At a glance

interface SqlQueryable {
  query<Row>(request: SqlExecuteRequest): AsyncIterable<Row>
  execute(request: SqlExecuteRequest): Promise<SqlStatementStats>
}

Drivers now distinguish streaming rows from DML execution statistics instead of exposing separate prepared variants or a buffered query API.

Decision

This PR ships the Slice 1 driver-SPI split for affected-row counts: query() streams rows, execute() returns { affectedRows }, and prepared execution is represented by an optional handle on the request. PostgreSQL and SQLite implement the final surface; the SQL runtime, Supabase runtime, adapters, and test doubles use it end to end.

It also makes a failed PostgreSQL stale prepared-statement retry emit the structural DRIVER.PREPARE_FAILED envelope required by ADR 239, preserving the normalized driver error as its cause.

Reviewer notes

• This is a deliberate hard-cut migration. The broad test/fake changes are mechanical consumers of the two-method driver contract, not independent behavior changes.
• PostgreSQL counts rowCount; SQLite counts stmt.run().changes. Their distinct engine semantics are intentionally preserved.
• SQLite rejects a RETURNING statement routed to execute() before execution, preventing silent row loss.
• pnpm test:packages still has unrelated telemetry/CLI harness failures: telemetry-backend cannot locate prisma-next, and seven CLI process tests exceed their timeout. The changed packages and workspace typecheck are green.

How it fits together

1. The relational driver contract exposes one streaming path and one statistics path in packages/2-sql/4-lanes/relational-core/src/ast/driver-types.ts.
2. PostgreSQL maps buffered command results to { affectedRows }, while SQLite maps StatementSync.run().changes and retains its defensive RETURNING guard.
3. Preparedness moves onto the request, letting packages/2-sql/5-runtime/src/sql-runtime.ts use one streaming execution pipeline for ad-hoc and prepared plans.
4. Supabase session setup, target adapters, runtime helpers, and all fakes consume the same request-shaped contract.

Behavior changes & evidence

• Drivers report write statistics directly through execute(request).
  • Implementation: packages/3-targets/7-drivers/postgres/src/postgres-driver.ts, packages/3-targets/7-drivers/sqlite/src/sqlite-driver.ts
  • Evidence: packages/3-targets/7-drivers/postgres/test/driver.basic.test.ts, packages/3-targets/7-drivers/sqlite/test/sqlite-driver.test.ts
• Prepared retry failures carry a stable DRIVER error code and original cause.
  • Implementation: packages/3-targets/7-drivers/postgres/src/postgres-driver.ts, packages/3-targets/7-drivers/postgres/src/driver-error.ts
  • Evidence: packages/3-targets/7-drivers/postgres/test/driver.prepared.test.ts
• The runtime has one streamed-row execution flow for normal and prepared plans.
  • Implementation: packages/2-sql/5-runtime/src/sql-runtime.ts
  • Evidence: packages/2-sql/5-runtime/test/prepared.test.ts, packages/2-sql/5-runtime/test/plan-execution-id.test.ts

Compatibility / migration / risk

This is a breaking internal driver SPI change. All in-repository implementations and fakes are migrated in this PR. ORM-visible count-terminal behavior remains unchanged; the count-terminal behavior change belongs to TML-3168.

Testing performed

• pnpm typecheck — 165/165 tasks passed
• pnpm lint:deps passed
• PostgreSQL driver typecheck, test (127 tests), and lint passed
• SQLite driver typecheck, test (29 tests), and lint passed
• Supabase build, typecheck, lint, and test (89 tests) passed
• executePrepared and SqlQueryResult searches under packages/ and test/ returned zero results
• pnpm test:packages ran but has the unrelated telemetry/CLI harness failures noted above

Skill update

n/a — internal SPI refactor; no end-user skill surface changed.

Alternatives considered

• Keeping a separate executePrepared() method was rejected because preparedness is a request property, not a distinct execution operation.
• Returning statistics in the row stream was rejected because count consumers should not need to demultiplex row and metadata frames.
• Normalizing affected-row semantics across engines was rejected; each driver reports its native engine result.

Checklist

• All commits are signed off (git commit -s) per the DCO.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• Tests are updated.
• The PR title is in TML-NNNN: <sentence-case title> form.
• The Skill update section is filled in.

Summary by CodeRabbit

• New Features

  • SQL queries now stream rows asynchronously, improving support for large result sets.
  • Statement execution reports affected-row statistics.
  • Prepared statements reuse handles and recover from stale handles.
  • PostgreSQL and SQLite support the unified SQL execution interface.
  • Added structured PostgreSQL driver errors with standardized codes and severity metadata.

• Breaking Changes

  • Removed separate prepared-execution methods and the legacy query-result format.
  • Query and execution methods now use request objects.