fix: resolve CI build errors and address all PR review comments

- Fix DTS build: remove legacy tuple indexing in orderBy (item[0]/item[1])
- Fix DTS build: widen SqlDriver name/version types to string for subclass override
- Fix test: update orderBy test to use standard {field, order} format
- Move better-sqlite3 from devDependencies to dependencies (runtime dep)
- Throw error for unsupported remote-only URLs without syncUrl
- Clarify TursoDriverConfig docs: encryptionKey/concurrency/timeout need syncUrl
- Add in-flight promise dedup in multi-tenant router (prevents concurrent duplicates)
- Interpolate {tenant} in syncUrl and other string config fields
- Use os.tmpdir() + random suffix in tests (cross-platform, no collisions)
- Update README: clarify connection modes, syncUrl interpolation, concurrency safety

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/e1258eb3-0b40-4278-af78-15e3ede22d41

Author: Copilot

packages/plugins/driver-sql/src/sql-driver-queryast.test.ts

@@ -144,7 +144,7 @@ describe('SqlDriver (QueryAST Format)', () => {
       const results = await driver.find('products', {
         fields: ['name'],
         limit: 2,
-        orderBy: [['price', 'asc']],
+        orderBy: [{ field: 'price', order: 'asc' }],
       } as any);
 
       expect(results.length).toBe(2);

packages/plugins/driver-sql/src/sql-driver.ts

@@ -65,8 +65,8 @@ export type SqlDriverConfig = Knex.Config;
  */
 export class SqlDriver implements IDataDriver {
   // IDataDriver metadata
-  public readonly name = 'com.objectstack.driver.sql';
-  public readonly version = '1.0.0';
+  public readonly name: string = 'com.objectstack.driver.sql';
+  public readonly version: string = '1.0.0';
   public readonly supports = {
     // Basic CRUD Operations
     create: true,
@@ -185,10 +185,8 @@ export class SqlDriver implements IDataDriver {
     // ORDER BY
     if (query.orderBy && Array.isArray(query.orderBy)) {
       for (const item of query.orderBy) {
-        const field = item.field || item[0];
-        const dir = item.order || item[1] || 'asc';
-        if (field) {
-          builder.orderBy(this.mapSortField(field), dir);
+        if (item.field) {
+          builder.orderBy(this.mapSortField(item.field), item.order || 'asc');
         }
       }
     }

packages/plugins/driver-turso/README.md

@@ -69,6 +69,10 @@ await driver.connect();
 await driver.sync();
 ```
 
+> **Note:** Remote-only URLs (`url: 'libsql://...'`) without `syncUrl` are
+> not supported and will throw. Always use a local `file:` or `:memory:` URL
+> as the primary store. For remote persistence, use embedded replica mode with `syncUrl`.
+
 ## Multi-Tenant Routing
 
 Database-per-tenant architecture with automatic driver caching:
@@ -92,7 +96,9 @@ const users = await driver.find('users', { where: { active: true } });
 await router.destroyAll();
 ```
 
-### Multi-Tenant with Turso Cloud
+### Multi-Tenant with Embedded Replicas
+
+Both `urlTemplate` and `driverConfigOverrides.syncUrl` support `{tenant}` placeholder interpolation:
 
 ```typescript
 const router = createMultiTenantRouter({
@@ -105,32 +111,46 @@ const router = createMultiTenantRouter({
 });
 ```
 
+### Concurrency Safety
+
+Concurrent `getDriverForTenant()` calls for the same tenant are deduplicated — only one driver is created, and all callers share the same instance.
+
 ## Configuration
 
 ```typescript
 interface TursoDriverConfig {
-  /** Database URL (file:, :memory:, libsql://, https://) */
+  /** Database URL for the local store (file: or :memory:) */
   url: string;
 
-  /** JWT auth token for remote Turso database */
+  /** JWT auth token for the remote Turso database (used with syncUrl) */
   authToken?: string;
 
-  /** AES-256 encryption key for local files */
+  /**
+   * AES-256 encryption key for local database file.
+   * Only effective in embedded replica mode (requires syncUrl).
+   */
   encryptionKey?: string;
 
-  /** Maximum concurrent requests. Default: 20 */
+  /**
+   * Maximum concurrent requests to the remote database.
+   * Only effective in embedded replica mode (requires syncUrl).
+   * Default: 20
+   */
   concurrency?: number;
 
-  /** Remote sync URL for embedded replica mode */
+  /** Remote sync URL for embedded replica mode (libsql:// or https://) */
   syncUrl?: string;
 
-  /** Sync configuration */
+  /** Sync configuration (requires syncUrl) */
   sync?: {
     intervalSeconds?: number; // Default: 60
     onConnect?: boolean;      // Default: true
   };
 
-  /** Operation timeout in milliseconds */
+  /**
+   * Operation timeout in milliseconds for remote operations.
+   * Only effective in embedded replica mode (requires syncUrl).
+   */
   timeout?: number;
 }
 ```
@@ -164,7 +184,7 @@ await kernel.enablePlugin(tursoPlugin, {
 ## Testing
 
 ```bash
-pnpm test        # Run all 53 tests
+pnpm test        # Run all tests
 ```
 
 Tests run against in-memory SQLite (`:memory:`) — no external services required.

packages/plugins/driver-turso/package.json

@@ -33,11 +33,11 @@
     "@objectstack/driver-sql": "workspace:*",
     "@objectstack/spec": "workspace:*",
     "@libsql/client": "^0.17.2",
+    "better-sqlite3": "^11.9.1",
     "nanoid": "^3.3.11"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "better-sqlite3": "^11.9.1",
     "typescript": "^5.0.0",
     "vitest": "^4.1.0"
   }

packages/plugins/driver-turso/src/multi-tenant.test.ts

@@ -4,6 +4,14 @@ import { describe, it, expect, afterEach } from 'vitest';
 import { createMultiTenantRouter, type MultiTenantRouter } from '../src/multi-tenant.js';
 import { TursoDriver } from '../src/turso-driver.js';
 import { SqlDriver } from '@objectstack/driver-sql';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** Build a unique temp path template for test isolation. */
+function tmpTemplate(label: string): string {
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `file:${join(tmpdir(), `test-turso-${label}-${rand}-{tenant}.db`)}`;
+}
 
 describe('Multi-Tenant Router', () => {
   let router: MultiTenantRouter | null = null;
@@ -29,7 +37,7 @@ describe('Multi-Tenant Router', () => {
 
   it('should create a TursoDriver for a tenant', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-mt-{tenant}.db',
+      urlTemplate: tmpTemplate('mt'),
     });
 
     const driver = await router.getDriverForTenant('acme');
@@ -40,7 +48,7 @@ describe('Multi-Tenant Router', () => {
 
   it('should cache drivers and return same instance', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-cache-{tenant}.db',
+      urlTemplate: tmpTemplate('cache'),
     });
 
     const driver1 = await router.getDriverForTenant('acme');
@@ -50,7 +58,7 @@ describe('Multi-Tenant Router', () => {
 
   it('should create separate drivers per tenant', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-sep-{tenant}.db',
+      urlTemplate: tmpTemplate('sep'),
     });
 
     const driver1 = await router.getDriverForTenant('tenant-a');
@@ -63,15 +71,15 @@ describe('Multi-Tenant Router', () => {
 
   it('should reject empty tenantId', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-val-{tenant}.db',
+      urlTemplate: tmpTemplate('val'),
     });
 
     await expect(router.getDriverForTenant('')).rejects.toThrow();
   });
 
   it('should reject invalid tenantId with special characters', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-val2-{tenant}.db',
+      urlTemplate: tmpTemplate('val2'),
     });
 
     await expect(router.getDriverForTenant('a')).rejects.toThrow();
@@ -80,7 +88,7 @@ describe('Multi-Tenant Router', () => {
 
   it('should accept valid tenantId', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-accept-{tenant}.db',
+      urlTemplate: tmpTemplate('accept'),
     });
 
     const driver = await router.getDriverForTenant('valid-tenant');
@@ -91,7 +99,7 @@ describe('Multi-Tenant Router', () => {
 
   it('should report cache size', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-size-{tenant}.db',
+      urlTemplate: tmpTemplate('size'),
     });
 
     expect(router.getCacheSize()).toBe(0);
@@ -103,7 +111,7 @@ describe('Multi-Tenant Router', () => {
 
   it('should invalidate cache for a tenant', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-inv-{tenant}.db',
+      urlTemplate: tmpTemplate('inv'),
     });
 
     await router.getDriverForTenant('to-invalidate');
@@ -115,7 +123,7 @@ describe('Multi-Tenant Router', () => {
 
   it('should destroy all cached drivers', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-destroy-{tenant}.db',
+      urlTemplate: tmpTemplate('destroy'),
     });
 
     await router.getDriverForTenant('destroy-a');
@@ -132,7 +140,7 @@ describe('Multi-Tenant Router', () => {
     const created: string[] = [];
 
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-cb-{tenant}.db',
+      urlTemplate: tmpTemplate('cb'),
       onTenantCreate: async (tenantId) => {
         created.push(tenantId);
       },
@@ -150,7 +158,7 @@ describe('Multi-Tenant Router', () => {
     const evicted: string[] = [];
 
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-evict-{tenant}.db',
+      urlTemplate: tmpTemplate('evict'),
       onTenantEvict: async (tenantId) => {
         evicted.push(tenantId);
       },
@@ -163,11 +171,39 @@ describe('Multi-Tenant Router', () => {
     expect(evicted).toEqual(['evict-test']);
   });
 
+  // ── Concurrent Access Guard ────────────────────────────────────────────
+
+  it('should deduplicate concurrent getDriverForTenant calls', async () => {
+    let createCount = 0;
+
+    router = createMultiTenantRouter({
+      urlTemplate: tmpTemplate('conc'),
+      onTenantCreate: async () => {
+        createCount++;
+      },
+    });
+
+    // Fire multiple concurrent calls for the same tenant
+    const [d1, d2, d3] = await Promise.all([
+      router.getDriverForTenant('same-tenant'),
+      router.getDriverForTenant('same-tenant'),
+      router.getDriverForTenant('same-tenant'),
+    ]);
+
+    // All calls should return the same driver instance
+    expect(d1).toBe(d2);
+    expect(d2).toBe(d3);
+
+    // onTenantCreate should only be called once
+    expect(createCount).toBe(1);
+    expect(router.getCacheSize()).toBe(1);
+  });
+
   // ── CRUD through Multi-Tenant Driver ───────────────────────────────────
 
   it('should perform CRUD operations through a tenant driver', async () => {
     router = createMultiTenantRouter({
-      urlTemplate: 'file:/tmp/test-turso-crud-{tenant}.db',
+      urlTemplate: tmpTemplate('crud'),
     });
 
     const driver = await router.getDriverForTenant('crud-test');