@@ -0,0 +1,12 @@
+---
+'@objectstack/driver-sql': patch
+---
+
+fix(driver-sql): paged reads of a federated object keyed through `external.columnMap` are a partition, ordered by that key, on every dialect
+
+Clause-②: no
+Metadata-protocol: none
+
+A paged `find()` gets a unique tie-breaker so its pages partition the result set (objectui#3106, #4363). That tie-breaker was imposed only on tables this driver created. A federated object got none, even when its `external.columnMap` names the remote key column (`T_NO: 'id'`), which is the column the by-id doors already address. Ties within the caller's sort were not ordered at all, and an unsorted paged read had no order. SQLite mostly hid this, because a plain table scan returns rowid order. PostgreSQL and MySQL promise no order among ties, so a page walk there can repeat some rows and never serve others.
+
+A paged read of such an object is now ordered by the mapped key after the caller's own keys, the same rule a managed table follows. A federated object with no mapped key keeps the old behaviour exactly: no column is guessed, and the existing warning still names the gap.
@@ -0,0 +1,12 @@
+---
+'@objectstack/driver-sql': patch
+---
+
+fix(driver-sql): `upsert()` resolves its conflict target and its read-back through `external.columnMap` on every dialect
+
+Clause-②: no
+Metadata-protocol: none
+
+A federated object whose `external.columnMap` maps its key to a remote column (`CUST_NO: 'id'`) could not be upserted correctly. The payload was mapped, but the conflict target stayed the field names: the default target compiled `ON CONFLICT ("id")`, and an explicit `conflictKeys` naming the key did the same. On SQLite, PostgreSQL and MySQL alike, on a remote table without an `id` column every upsert failed. On a remote table that also has its own `id` column, which is not the mapped key, the conflict target was that other column: an upsert of an existing key raised a primary-key violation instead of merging, and the read-back of an inserted row matched that other column and answered a different row.
+
+The conflict target, the MySQL pre-flight and identity probes, and the read-back now name the mapped columns. Refusals still name the fields the caller passed. An object without a `columnMap` compiles the statement it compiled before.
@@ -0,0 +1,64 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * A paged read of a federated object whose `external.columnMap` names its key
+ * column is a PARTITION of the result set (objectui#3106, #4363), ordered by
+ * that key — the column the by-id doors already address.
+ *
+ * The tie-breaker used to be imposed only on tables this driver created, so
+ * every federated page walk was unordered among ties. SQLite mostly hides it
+ * (a plain table scan returns rowid order), which is why these pins read the
+ * compiled ORDER BY as well as the rows; a dialect that promises no order
+ * among ties repeats and loses rows across pages.
+ *
+ * A federated object with NO mapped key keeps the old behaviour exactly — no
+ * column is guessed (`paginationTieBreaker`'s docblock says why).
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { SqlDriver } from './index.js';
+
+let driver: any;
+afterEach(async () => { await driver?.disconnect(); driver = undefined; });
+
+async function over(columnMap: Record<string, string> | undefined): Promise<{ driver: any; sql: string[] }> {
+  const d = new SqlDriver({
+    client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, schemaMode: 'external',
+  } as any) as any;
+  d.name = 'extds';
+  await d.connect();
+  await d.knex.raw('create table REMOTE_T (T_NO text primary key, STATUS text)');
+  await d.knex.raw("insert into REMOTE_T values ('b', 'open'), ('a', 'open'), ('c', 'done')");
+  d.registerExternalObject({
+    name: 't',
+    external: { remoteName: 'REMOTE_T', ...(columnMap ? { columnMap } : {}) },
+    fields: { status: { type: 'text' } },
+  });
+  const sql: string[] = [];
+  d.knex.on('query', (q: { sql: string }) => sql.push(q.sql));
+  return { driver: d, sql };
+}
+
+describe('paged reads of a columnMap-keyed federated object', () => {
+  it('an unsorted page is ordered by the mapped key column', async () => {
+    const run = await over({ T_NO: 'id', STATUS: 'status' });
+    driver = run.driver;
+    const rows = await driver.find('t', { limit: 2 });
+    expect(rows.map((r: any) => r.id)).toEqual(['a', 'b']);
+    expect(run.sql[run.sql.length - 1]).toMatch(/order by [`"]T_NO[`"] asc/);
+  });
+
+  it('a sorted page breaks its ties on the mapped key, in the last key’s direction', async () => {
+    const run = await over({ T_NO: 'id', STATUS: 'status' });
+    driver = run.driver;
+    await driver.find('t', { orderBy: [{ field: 'status', order: 'desc' }], limit: 2 });
+    expect(run.sql[run.sql.length - 1]).toMatch(/order by [`"]STATUS[`"] desc, [`"]T_NO[`"] desc/);
+  });
+
+  it('an object with no mapped key is left alone: no column is guessed', async () => {
+    const run = await over(undefined);
+    driver = run.driver;
+    await driver.find('t', { orderBy: [{ field: 'status', order: 'asc' }], limit: 2 }).catch(() => undefined);
+    expect(run.sql[run.sql.length - 1]).not.toMatch(/[`"]id[`"]/);
+  });
+});
@@ -99,3 +99,75 @@ describe('a remote table with its own unmapped `id` column (the silent case)', (
     expect(await driver.knex('legacy_part').count({ n: '*' })).toEqual([{ n: 2 }]);
   });
 });
+
+describe('upsert() over a columnMap-ed key', () => {
+  // The conflict target and the read-back both name the key's mapped column.
+  // Unmapped, the statement said `on conflict ("id")` — a column this table
+  // does not have — and every upsert failed.
+  const ddl = 'create table legacy_cust (CUST_NO text primary key, FULL_NAME text)';
+  const rows = ["insert into legacy_cust values ('c1', 'Aurora'), ('c2', 'Borealis')"];
+  const register = (d: any) => d.registerExternalObject({
+    name: 'cust',
+    external: { remoteName: 'legacy_cust', columnMap: { CUST_NO: 'id', FULL_NAME: 'name' } },
+    fields: { name: { type: 'text' } },
+  });
+
+  it('merges onto the row an existing key names', async () => {
+    driver = await driverOver(ddl, rows);
+    register(driver);
+    expect(await driver.upsert('cust', { id: 'c2', name: 'Bore' })).toEqual({ id: 'c2', name: 'Bore' });
+    const raw = await driver.knex('legacy_cust').select('CUST_NO', 'FULL_NAME').orderBy('CUST_NO');
+    expect(raw).toEqual([
+      { CUST_NO: 'c1', FULL_NAME: 'Aurora' },
+      { CUST_NO: 'c2', FULL_NAME: 'Bore' },
+    ]);
+  });
+
+  it('inserts a new key and reads it back', async () => {
+    driver = await driverOver(ddl, rows);
+    register(driver);
+    expect(await driver.upsert('cust', { id: 'c9', name: 'Nine' })).toEqual({ id: 'c9', name: 'Nine' });
+    expect(await driver.knex('legacy_cust').count({ n: '*' })).toEqual([{ n: 3 }]);
+  });
+
+  it('an explicit conflictKeys naming the key field resolves through the map', async () => {
+    driver = await driverOver(ddl, rows);
+    register(driver);
+    expect(await driver.upsert('cust', { id: 'c1', name: 'Aurora2' }, ['id'])).toEqual({ id: 'c1', name: 'Aurora2' });
+    expect(await driver.knex('legacy_cust').where('CUST_NO', 'c1').first('FULL_NAME')).toEqual({ FULL_NAME: 'Aurora2' });
+  });
+});
+
+describe('upsert() on a remote table with its own unmapped `id` column (the silent case)', () => {
+  // `id` is the remote system's surrogate; the object's key is CODE.
+  const ddl = 'create table legacy_part (id integer unique, CODE text primary key, LABEL text)';
+  const rows = ["insert into legacy_part values (1, 'B', 'bolt'), (2, 'A', 'anchor')"];
+  const register = (d: any) => d.registerExternalObject({
+    name: 'part',
+    external: { remoteName: 'legacy_part', columnMap: { CODE: 'id', LABEL: 'label' } },
+    fields: { label: { type: 'text' } },
+  });
+
+  it('merges on the mapped key, not on the surrogate', async () => {
+    driver = await driverOver(ddl, rows);
+    register(driver);
+    // Unmapped, the conflict target was the surrogate, so the insert of an
+    // existing CODE raised the primary-key violation instead of merging.
+    expect(await driver.upsert('part', { id: 'A', label: 'anchor!' })).toEqual({ id: 'A', label: 'anchor!' });
+    const raw = await driver.knex('legacy_part').select('id', 'CODE', 'LABEL').orderBy('id');
+    expect(raw).toEqual([
+      { id: 1, CODE: 'B', LABEL: 'bolt' },
+      { id: 2, CODE: 'A', LABEL: 'anchor!' },
+    ]);
+  });
+
+  it('answers the row it wrote, not the row whose surrogate equals the key', async () => {
+    driver = await driverOver(ddl, rows);
+    register(driver);
+    // Key '1' names no row by CODE, so this inserts. The unmapped read-back
+    // matched surrogate id 1 and answered row B.
+    expect(await driver.upsert('part', { id: '1', label: 'one' })).toEqual({ id: '1', label: 'one' });
+    expect(await driver.knex('legacy_part').where('CODE', '1').first('LABEL')).toEqual({ LABEL: 'one' });
+    expect(await driver.knex('legacy_part').where('CODE', 'B').first('LABEL')).toEqual({ LABEL: 'bolt' });
+  });
+});
@@ -60,11 +60,16 @@ export class FieldMappingFacet {
   }
 
   /** The body of `SqlDriver#paginationTieBreaker`; the method's docblock there is its contract. */
-  static paginationTieBreaker(this: Pick<FieldMappingHost, 'managedObjectFields'>, object: string): string | null {
+  static paginationTieBreaker(this: Pick<FieldMappingHost, 'managedObjectFields' | 'fieldColumnByObject'>, object: string): string | null {
     const tableName = StorageNameMapping.resolveTableName({ name: object } as any);
     const managed =
       this.managedObjectFields.has(tableName) || this.managedObjectFields.has(object);
-    return managed ? 'id' : null;
+    if (managed) return 'id';
+    // A federated object whose binding NAMES its key column — `external.columnMap`
+    // mapping a remote column to `id` — is not a guess: the binding declares
+    // which remote column identifies a row, the column the by-id doors already
+    // address. Without it, nothing is known and nothing is imposed.
+    return this.fieldColumnByObject[object]?.id ? 'id' : null;
   }
 
   /** The body of `SqlDriver#orderKeysFor`; the method's docblock there is its contract. */