fix: correct wording in batch schema sync docs to reflect actual round-trip count

Updated all JSDoc, Zod descriptions, and CHANGELOG to accurately say
"fewer round-trips" / "up to three batch calls" instead of incorrectly
claiming "single round-trip". Clarified that RemoteTransport does not
implement internal fallback — the caller (ObjectQLPlugin) handles it.

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/bb7821bf-99fd-4b8e-8d7d-6a464b4f51a3

Author: Copilot

CHANGELOG.md

@@ -19,11 +19,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - **Batch schema sync for remote DDL in kernel bootstrap** — `ObjectQLPlugin.syncRegisteredSchemas()`
   now groups objects by driver and uses `syncSchemasBatch()` when the driver advertises
-  `supports.batchSchemaSync = true`. This sends all DDL (CREATE TABLE / ALTER TABLE ADD COLUMN)
-  in a single `client.batch()` call instead of N sequential round-trips, reducing cold-start times
-  from 58+ seconds to under 10 seconds for 100+ objects on remote drivers (e.g. Turso cloud).
+  `supports.batchSchemaSync = true`. This reduces the number of remote DDL round-trips from
+  roughly N×(2–3) individual calls (introspection + optional PRAGMA + DDL write per object)
+  to a small constant number of batched `client.batch()` calls, cutting cold-start times from
+  58+ seconds to under 10 seconds for 100+ objects on remote drivers (e.g. Turso cloud).
   Falls back to sequential `syncSchema()` per object for drivers without batch support or if the
-  batch call fails at runtime. Added `batchSchemaSync` capability flag to `DriverCapabilitiesSchema`,
+  batched calls fail at runtime. Added `batchSchemaSync` capability flag to `DriverCapabilitiesSchema`,
   optional `syncSchemasBatch()` to `IDataDriver`, and `RemoteTransport.syncSchemasBatch()` using
   `@libsql/client`'s `batch()` API.
 - **`@objectstack/driver-turso` — dual transport architecture** — TursoDriver now supports three

packages/plugins/driver-turso/src/remote-transport.ts

@@ -378,15 +378,17 @@ export class RemoteTransport {
   }
 
   /**
-   * Batch-synchronize multiple object schemas in a single round-trip.
+   * Batch-synchronize multiple object schemas using batched libsql calls.
    *
    * Collects all DDL statements (CREATE TABLE / ALTER TABLE ADD COLUMN)
-   * for every schema and submits them via `client.batch()` in a single
-   * network call.  This reduces N × (2–3) HTTP round-trips to exactly 2:
-   * one batch to introspect existing tables, and one batch to apply DDL.
+   * for every schema and uses `client.batch()` to minimize network
+   * round-trips. The process may perform up to three batch calls:
+   * one to introspect existing tables, one to introspect columns for
+   * existing tables, and one to apply DDL statements.
    *
-   * Falls back to sequential `syncSchema()` if the batch call fails
-   * (e.g. unsupported by the libsql endpoint).
+   * This method does not implement an internal fallback to sequential
+   * `syncSchema()`. Any fallback behavior is expected to be handled
+   * by the caller if a batch operation is not supported or fails.
    */
   async syncSchemasBatch(schemas: Array<{ object: string; schema: any }>): Promise<void> {
     this.ensureClient();

packages/spec/src/contracts/data-driver.ts

@@ -154,7 +154,7 @@ export interface IDataDriver {
   syncSchema(object: string, schema: unknown, options?: DriverOptions): Promise<void>;
 
   /**
-   * Batch-synchronize multiple object schemas in a single round-trip.
+   * Batch-synchronize multiple object schemas with fewer round-trips.
    *
    * Drivers that set `supports.batchSchemaSync = true` MUST implement this.
    * The engine calls it once with all `{ object, schema }` pairs instead

packages/spec/src/data/driver.zod.ts

@@ -216,11 +216,11 @@ export const DriverCapabilitiesSchema = z.object({
 
   /**
    * Whether the driver supports batching multiple schema sync operations
-   * into a single round-trip. When true, the engine may call
-   * `syncSchemasBatch()` instead of calling `syncSchema()` per object,
-   * drastically reducing network round-trips for remote drivers.
+   * into a single (or fewer) round-trips for the DDL phase. When true,
+   * the engine may call `syncSchemasBatch()` instead of calling
+   * `syncSchema()` per object, reducing network round-trips for remote drivers.
    */
-  batchSchemaSync: z.boolean().default(false).describe('Supports batched schema sync (single round-trip DDL)'),
+  batchSchemaSync: z.boolean().default(false).describe('Supports batched schema sync to reduce schema DDL round-trips'),
 
   /**
    * Whether the driver supports database migrations.
@@ -585,7 +585,7 @@ export const DriverInterfaceSchema = z.object({
     .describe('Sync object schema to DB'),
 
   /**
-   * Batch-synchronize multiple object schemas in a single round-trip.
+   * Batch-synchronize multiple object schemas with fewer round-trips.
    *
    * Drivers that advertise `supports.batchSchemaSync = true` MUST implement
    * this method.  The engine will call it once with every