refactor(clickhouse): drop builder state mutation in bulkInsert(); document Format::serialize() column contract

- bulkInsert() no longer assigns to the fluent insertFormat / insertFormatColumns
  fields after the envelope is compiled. The compileFormatInsertEnvelope() helper
  is already parameterised, so those assignments were stale state — reusing a
  builder instance for a subsequent regular insert() previously inherited the
  residual format envelope.
- Format::serialize() PHPDoc now spells out the $columns === null contract:
  ordering is derived from the keys of the first row, with no cross-row
  consistency check. Positional formats (TabSeparated) corrupt silently on
  inconsistent row shapes; named formats (JSONEachRow) tolerate reordering but
  the explicit $columns argument acts as a projection filter.
- New tests guard both invariants: builder-reuse after bulkInsert() and the
  explicit-columns ordering contract on Format::serialize() across rows whose
  keys vary.

Author: lohanidamodar

src/Query/Builder/ClickHouse.php

@@ -176,9 +176,6 @@ public function bulkInsert(Format $format, iterable $rows, array $columns = []):
 
         $body = $format->serialize($materialized, empty($columns) ? null : $columns);
 
-        $this->insertFormat = $format->value;
-        $this->insertFormatColumns = $columns;
-
         return new FormattedInsertStatement(
             $sql,
             [],

src/Query/Builder/ClickHouse/Format.php

@@ -19,12 +19,27 @@ enum Format: string
 
     /**
      * Serialize an iterable of associative rows into the body payload for
-     * this format. Columns are derived from the first row; subsequent rows
-     * use the same column ordering. An empty iterable yields an empty
-     * string — ClickHouse accepts an empty body as a zero-row insert.
+     * this format. An empty iterable yields an empty string — ClickHouse
+     * accepts an empty body as a zero-row insert.
+     *
+     * When `$columns` is null the column ordering is derived from the keys
+     * of the first row encountered. Subsequent rows are serialized against
+     * whatever shape they themselves carry — there is no cross-row
+     * consistency check. The implications differ per format:
+     *
+     * - For positional formats (e.g. {@see Format::TabSeparated}) values
+     *   are emitted in row-key order. If later rows reorder their keys the
+     *   columns silently misalign with the envelope's column list. Pass
+     *   `$columns` explicitly whenever row shapes are not guaranteed
+     *   identical, or whenever the format is positional.
+     * - For named formats (e.g. {@see Format::JSONEachRow}) key ordering
+     *   does not affect correctness because each value is paired with its
+     *   key in the wire format. `$columns` still acts as a projection
+     *   filter: rows missing a listed column receive `null`, and row keys
+     *   outside the list are dropped.
      *
      * @param  iterable<array<string, mixed>>  $rows
-     * @param  list<string>|null  $columns  Optional explicit column ordering. When null, derived from the first row.
+     * @param  list<string>|null  $columns  Optional explicit column ordering. When null, derived from the keys of the first row.
      */
     public function serialize(iterable $rows, ?array $columns = null): string
     {

tests/Query/Builder/Feature/ClickHouse/BulkInsertTest.php

@@ -352,4 +352,48 @@ public function testInsertFormatRejectsEmptyColumnNameMatchingBulkInsert(): void
             ->insertFormat('JSONEachRow', ['id', ''])
             ->insert();
     }
+
+    public function testBulkInsertDoesNotPersistFormatStateOnBuilder(): void
+    {
+        $builder = (new Builder())
+            ->into('events');
+
+        $builder->bulkInsert(Format::JSONEachRow, [['id' => 1]]);
+
+        $regular = $builder
+            ->into('users')
+            ->set(['name' => 'alice'])
+            ->insert();
+
+        $this->assertNotInstanceOf(FormattedInsertStatement::class, $regular);
+        $this->assertStringNotContainsString('FORMAT', $regular->query);
+        $this->assertSame(
+            'INSERT INTO `users` (`name`) VALUES (?)',
+            $regular->query,
+        );
+        $this->assertSame(['alice'], $regular->bindings);
+    }
+
+    public function testFormatSerializeExplicitColumnsPinOrderingAcrossInconsistentRows(): void
+    {
+        $rows = [
+            ['id' => 1, 'event' => 'login'],
+            ['event' => 'view', 'id' => 2],
+            ['id' => 3],
+        ];
+
+        $tabSeparated = Format::TabSeparated->serialize($rows, ['id', 'event']);
+        $this->assertSame(
+            "1\tlogin\n2\tview\n3\t\\N",
+            $tabSeparated,
+        );
+
+        $jsonEachRow = Format::JSONEachRow->serialize($rows, ['id', 'event']);
+        $this->assertSame(
+            '{"id":1,"event":"login"}' . "\n"
+            . '{"id":2,"event":"view"}' . "\n"
+            . '{"id":3,"event":null}',
+            $jsonEachRow,
+        );
+    }
 }