diff --git a/‎.changeset/20054-turso-remote-no-native-driver.md‎
Lines changed: 32 additions & 0 deletions b/‎.changeset/20054-turso-remote-no-native-driver.md‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎packages/drivers/driver-turso/src/turso-driver.ts‎
Lines changed: 61 additions & 26 deletions b/‎packages/drivers/driver-turso/src/turso-driver.ts‎
Lines changed: 61 additions & 26 deletions
diff --git a/‎packages/drivers/driver-turso/src/turso-remote-drift-detection-refusal.test.ts‎
Lines changed: 4 additions & 3 deletions b/‎packages/drivers/driver-turso/src/turso-remote-drift-detection-refusal.test.ts‎
Lines changed: 4 additions & 3 deletions
diff --git a/‎packages/drivers/driver-turso/src/turso-remote-media-column-move-refusal.test.ts‎
Lines changed: 3 additions & 2 deletions b/‎packages/drivers/driver-turso/src/turso-remote-media-column-move-refusal.test.ts‎
Lines changed: 3 additions & 2 deletions
@@ -0,0 +1,32 @@
+---
+"@objectstack/driver-turso": minor
+---
+
+fix(driver-turso)!: a REMOTE `TursoDriver` no longer needs `better-sqlite3` installed, and the two inherited calls that answered from its private in-memory database now reject (#20054)
+
+Clause-②: no (narrowing)
+
+`package.json` declares `better-sqlite3` an optional peer, and the README tells a remote-only deployment (Vercel, an Edge runtime) that it does not need it. The code did not keep that promise. With `better-sqlite3` absent, `new TursoDriver({ url: 'libsql://…' })` threw knex's `Knex: run $ npm install better-sqlite3 --save` error at construction, before any remote call.
+
+The cause: remote mode handed the `SqlDriver` base a `better-sqlite3` Knex config on `:memory:`, and knex loads a dialect's native driver whenever the config carries a `connection`. Remote mode now builds that Knex instance with no `connection`. It loads no native module, opens no pool and holds no private in-memory database. With `better-sqlite3` absent, a remote driver constructs, connects and runs CRUD through `@libsql/client`.
+
+**BREAKING** — two calls on a remote driver that resolved before now reject. This is an accept-set narrowing on a published driver, shipped as `minor` under the repo's launch-window convention for breaking changes (`scripts/check-changeset-no-major.mjs`). The calls are `SqlDriver` methods that remote mode does not override, and they now reject with knex's `Unable to acquire a connection` error:
+
+- `introspectSchema()` used to resolve `{ tables: {} }`, "no tables", whatever the remote database held;
+- `reclaimSpace()` used to resolve.
+
+Both old answers came from the private in-memory database, not from the remote one. The per-method answer or refusal for these inherited calls is carried by #20055.
+
+**Error wording only, not the narrowing.** On a remote driver:
+
+- `findWithWindowFunctions()` still rejects. The error is now knex's `Unable to acquire a connection` instead of a missing-table error from the in-memory database.
+- `analyzeQuery()` and `explain()` still resolve the compiled SQL with an `error` field. That field now carries knex's message instead of a missing-table error.
+- `distinct()` answers the same `DATABASE_ERROR` / 500 as before.
+
+**Unchanged:**
+
+- **Local and embedded-replica modes.** Their `toKnexConfig` arms are untouched and still run on `better-sqlite3`, so a local driver (`:memory:` or a `file:` url) still fails at construction without it.
+- **Every call remote mode sends to `RemoteTransport` behaves as before**, including raw SQL through `execute()`. None of them used the Knex instance.
+- **The `NOT_IMPLEMENTED` / 501 refusals of `detectManagedDrift()` and `planMediaColumnMove()` on a remote driver** still refuse, with the same code and status. Their messages no longer say that remote mode's Knex connection is a placeholder in-memory database; they say that remote mode has no Knex connection.
+
+<!-- adr-0087: not-required (no-migration-prescription) A narrowing of which calls a remote `TursoDriver` answers: no key, spec symbol, Zod schema, object definition or stored representation is added, removed or renamed — `TursoDriverConfig` and both `TursoConfigSchema` copies are untouched, and `introspectSchema` / `reclaimSpace` keep their names and signatures. What moves is only that a remote driver no longer answers those two calls from a private in-memory database, so `objectstack migrate meta` has nothing to visit and there is no tombstone to mint. The per-method answer or refusal on the remote face is carried by #20055. -->
@@ -450,13 +450,16 @@ function refuseRemoteDeferredDdl(): never {
  *
  * `SqlDriver.detectManagedDrift` reads the physical schema through Knex: a
  * `hasTable` probe per table, then column and index introspection fed to the
- * shared differ. In remote mode that Knex instance is the placeholder
- * `:memory:` database {@link TursoDriver.toKnexConfig} hands the base
- * constructor. It holds none of this datasource's tables, so every table was
+ * shared differ. In remote mode that Knex instance was then the placeholder
+ * `:memory:` database {@link TursoDriver.toKnexConfig} handed the base
+ * constructor. It held none of this datasource's tables, so every table was
  * skipped as absent and the answer was `[]` whatever the remote database held.
  * The no-argument call had a second reason to answer `[]`: it iterates
  * `managedObjectFields`, which only the Knex `initObjects` fills and no remote
- * schema door reaches. Measured on the transport's SQLite-backed double
+ * schema door reaches. [#20054] Remote mode's Knex has no connection at all
+ * now, so an explicit-objects call would fail on its first `hasTable`; the
+ * no-argument call would still answer `[]` from the empty registry, which is
+ * why the refusal stays. Measured on the transport's SQLite-backed double
  * (`turso-remote-drift-detection-refusal.test.ts`): a synced table carrying an
  * extra physical column the declaration omits reads `unmapped_column` /
  * `drop_column` on the local face and `[]` on the remote one, with or without
@@ -473,7 +476,7 @@ function refuseRemoteDeferredDdl(): never {
  * the NULL-safe duplicate probe), so a remote implementation is a second copy
  * of each of those SQLite arms. It also needs a remote answer for
  * `applyMigrationEntries`, which the gate calls on whatever it finds and which
- * runs on the same placeholder. Until that exists the refusal is the honest
+ * runs through the same `this.knex`. Until that exists the refusal is the honest
  * answer, in the envelope and for the reason {@link refuseRemoteDeferredDdl}
  * records for its sibling gap on this transport: the call is spelled correctly
  * and the base class declares it, so the gap is the backend's.
@@ -494,9 +497,11 @@ function refuseRemoteDriftDetection(): never {
     'Schema drift detection is not supported by the Turso REMOTE transport (this datasource\'s ' +
     'transport mode is `remote`), so this driver cannot say whether the database\'s physical ' +
     'schema matches the declared objects. Drift detection reads the physical schema through the ' +
-    'SQL driver\'s Knex connection, and in remote mode that connection is a placeholder in-memory ' +
-    'database holding none of this datasource\'s tables. Answering from it would report "no drift" ' +
-    'for every remote database, whatever its tables hold, so the call refuses. The call is spelled ' +
+    'SQL driver\'s Knex connection, which remote mode does not have: every statement goes to the ' +
+    'remote database through the libSQL client instead. The objects it compares by default are the ' +
+    'ones the SQL driver\'s own schema sync registers, and remote mode registers none there, so ' +
+    'answering would report "no drift" for every remote database, whatever its tables hold; the ' +
+    'call refuses instead. The call is spelled ' +
     'correctly and `SqlDriver` declares it, so this is a capability gap of the remote transport ' +
     'rather than a mistake in the request, which is why it answers NOT_IMPLEMENTED/501 and not a ' +
     '400. To check this database for drift, run `os migrate plan` against a local SQLite copy of it ' +
@@ -520,9 +525,12 @@ function refuseRemoteDriftDetection(): never {
  * `os migrate files-to-references --apply`. It walks `managedObjectFields`,
  * which the Knex `initObjects` fills (through `registerObjectMetadata`) and no
  * remote schema door reaches, and it probes each table with `hasTable` and
- * column introspection through `this.knex`, which in remote mode is the
- * placeholder `:memory:` database {@link TursoDriver.toKnexConfig} hands the
- * base constructor. Either reason alone empties the answer. Measured on the
+ * column introspection through `this.knex`, which in remote mode was then the
+ * placeholder `:memory:` database {@link TursoDriver.toKnexConfig} handed the
+ * base constructor. Either reason alone empties the answer. [#20054] Remote
+ * mode's Knex has no connection at all now, and the walk over the empty
+ * registry still answers an empty scan without reaching it, which is why the
+ * refusal stays. Measured on the
  * transport's SQLite-backed double
  * (`turso-remote-media-column-move-refusal.test.ts`): a table `m` with a `file`
  * and an `image` field, synced through each of the three remote schema doors,
@@ -564,8 +572,8 @@ function refuseRemoteMediaColumnMove(): never {
     'Planning the ADR-0104 media column move is not supported by the Turso REMOTE transport ' +
     '(this datasource\'s transport mode is `remote`), so this driver cannot say which single-value ' +
     'media columns the database holds or how their values are encoded. The planner reads the ' +
-    'physical columns through the SQL driver\'s Knex connection, and in remote mode that connection ' +
-    'is a placeholder in-memory database holding none of this datasource\'s tables; the objects it ' +
+    'physical columns through the SQL driver\'s Knex connection, which remote mode does not have: ' +
+    'every statement goes to the remote database through the libSQL client instead. The objects it ' +
     'walks are the ones the SQL driver\'s own schema sync registers, and remote mode registers its ' +
     'objects another way. Answering from them would report "nothing to move" for every remote ' +
     'database, whatever media columns it holds, so the call refuses: nothing was planned and nothing ' +
@@ -1357,17 +1365,43 @@ export class TursoDriver extends SqlDriver {
   /**
    * Convert TursoDriverConfig to a Knex-compatible SqlDriverConfig.
    * Extracts the file path from the URL for local/embedded modes.
-   * In remote mode, uses a dummy :memory: config (Knex is not used).
+   * In remote mode, hands the base a Knex with NO connection: the SQLite
+   * dialect's compiler and nothing else (see the remote arm below).
    */
   private static toKnexConfig(config: TursoDriverConfig, mode: TursoTransportMode): SqlDriverConfig {
-    // Remote mode: All CRUD/schema operations delegate to RemoteTransport
-    // (via @libsql/client). Knex is never used for queries, but the SqlDriver
-    // base class constructor requires a valid config. We provide a minimal
-    // :memory: config that initializes Knex without side effects.
+    // [#20054] Remote mode: every CRUD and schema door delegates to
+    // RemoteTransport (`@libsql/client`), and none of them reads `this.knex`.
+    // Measured with the Knex instance wrapped to record every access after
+    // construction, across connect, the CRUD and bulk doors, aggregate,
+    // execute, the three schema doors and disconnect: zero reads. The
+    // `SqlDriver` constructor still builds a Knex instance, so this arm only
+    // decides WHICH one.
+    //
+    // It is built WITHOUT a `connection`, and that is the whole fix. knex's
+    // `Client` constructor loads the dialect's native driver
+    // (`initializeDriver` → `require('better-sqlite3')`) and builds a pool only
+    // when the config carries a `connection`. This arm used to pass
+    // `{ filename: ':memory:' }`, but loading the native module is a side
+    // effect: with `better-sqlite3` absent — the install this package's
+    // manifest (an OPTIONAL peer) and README give remote mode, e.g. on Vercel
+    // or an Edge runtime — construction threw knex's `npm install
+    // better-sqlite3` error before any remote call was made.
+    //
+    // What stays the same: the client is still spelled `better-sqlite3`, so
+    // `isSqlite` and every dialect-keyed rule the remote arms borrow from the
+    // base (`temporalFilterColumnSql`, the canonical-time SQL) answer exactly
+    // as before, and so does anything that reads the dialect name off
+    // `config.client`.
+    //
+    // What changes for a path that still reaches `this.knex` (only `SqlDriver`
+    // methods this class does not override for remote mode): it used to RUN
+    // against a private, empty `:memory:` database and could answer from it,
+    // as `introspectSchema()` did with "no tables". Now knex refuses to run it
+    // (`Unable to acquire a connection`), because there is no connection to
+    // run it on. That failure is loud; it never adds a silent answer.
     if (mode === 'remote') {
       return {
         client: 'better-sqlite3',
-        connection: { filename: ':memory:' },
         useNullAsDefault: true,
       };
     }
@@ -2551,10 +2585,11 @@ export class TursoDriver extends SqlDriver {
   /**
    * Detect managed-schema drift — refused on the REMOTE face, see
    * {@link refuseRemoteDriftDetection}. The inherited detector reads the
-   * physical schema through the placeholder Knex connection remote mode is
-   * built with, so its remote answer was always `[]`. Refused with or without
-   * explicit `objects`, because both read the same placeholder. Local and
-   * replica modes inherit the Knex detector unchanged.
+   * physical schema through `this.knex`, which remote mode builds with no
+   * connection; with no `objects` it walks a registry no remote schema door
+   * fills and answers `[]`. Refused with or without explicit `objects`, because
+   * neither can judge the remote database. Local and replica modes inherit the
+   * Knex detector unchanged.
    *
    * The parameter repeats the base's declared shape key for key rather than
    * deriving it (`check:object-def-param-keys` arm C), so the keys a caller may
@@ -2571,9 +2606,9 @@ export class TursoDriver extends SqlDriver {
    * Plan the ADR-0104 media column move — refused on the REMOTE face, see
    * {@link refuseRemoteMediaColumnMove}. The inherited planner walks
    * `managedObjectFields`, which no remote schema door fills, and probes each
-   * table through the placeholder Knex connection remote mode is built with,
-   * so its remote answer was always an empty scan. Local and replica modes
-   * inherit the Knex planner unchanged.
+   * table through `this.knex`, which remote mode builds with no connection, so
+   * its remote answer is an empty scan. Local and replica modes inherit the
+   * Knex planner unchanged.
    */
   override async planMediaColumnMove(): ReturnType<SqlDriver['planMediaColumnMove']> {
     if (this.isRemote) refuseRemoteMediaColumnMove();
 
@@ -5,9 +5,10 @@
  * answering "no drift".
  *
  * `SqlDriver.detectManagedDrift` reads the physical schema through Knex, and a
- * remote `TursoDriver` is built with a placeholder `:memory:` Knex connection
- * that holds none of the datasource's tables. Before the refusal, the remote
- * answer was `[]` for every database. That is the answer the artifact-pinned
+ * remote `TursoDriver` was then built with a placeholder `:memory:` Knex
+ * connection that held none of the datasource's tables (since #20054 it is
+ * built with no Knex connection at all). Before the refusal, the remote answer
+ * was `[]` for every database. That is the answer the artifact-pinned
  * boot gate of `os serve` reads as "never drifted", so a gate whose job is to
  * refuse a boot on destructive drift let every remote-Turso boot through.
  *
 
@@ -7,8 +7,9 @@
  * `SqlDriver.planMediaColumnMove` walks `managedObjectFields` and probes each
  * table through Knex. A remote `TursoDriver` fills neither: no remote schema
  * door reaches the Knex `initObjects` that fills the map, and its Knex
- * connection is a placeholder `:memory:` database holding none of the
- * datasource's tables. `os migrate files-to-references` mapped the resulting
+ * connection was then a placeholder `:memory:` database holding none of the
+ * datasource's tables (since #20054 there is no Knex connection at all).
+ * `os migrate files-to-references` mapped the resulting
  * empty scan to "nothing to move — this datastore declares no single-value
  * media column".
  *
Original file line number	Diff line number	Diff line change
`@@ -5,9 +5,10 @@`
`5`	`5`	`* answering "no drift".`
`6`	`6`	`*`
`7`	`7`	* `SqlDriver.detectManagedDrift` reads the physical schema through Knex, and a
`8`		- * remote `TursoDriver` is built with a placeholder `:memory:` Knex connection
`9`		`- * that holds none of the datasource's tables. Before the refusal, the remote`
`10`		- * answer was `[]` for every database. That is the answer the artifact-pinned
	`8`	+ * remote `TursoDriver` was then built with a placeholder `:memory:` Knex
	`9`	`+ * connection that held none of the datasource's tables (since #20054 it is`
	`10`	`+ * built with no Knex connection at all). Before the refusal, the remote answer`
	`11`	+ * was `[]` for every database. That is the answer the artifact-pinned
`11`	`12`	* boot gate of `os serve` reads as "never drifted", so a gate whose job is to
`12`	`13`	`* refuse a boot on destructive drift let every remote-Turso boot through.`
`13`	`14`	`*`