refactor(data-objectstack): route batchTransaction through the client SDK only (#2694)

ObjectStackAdapter.batchTransaction now calls the typed SDK method
client.data.batchTransaction(operations) directly; the transitional
hand-rolled fetch('/api/v1/batch') branch is removed. Guaranteed present by
the @objectstack/client@^16 dependency floor (framework #3271). Composes with
the #2755 capability gate: a declared-atomic backend treats any failure as a
real error; otherwise the SDK's status-decorated throw (404/405/501) still
degrades to the non-atomic emulateBatchTransaction. Fallback tests reworked to
drive via the SDK method. Docs + changeset updated.

Closes #2694.

Author: os-zhuang

.changeset/batchtransaction-drop-raw-fetch.md

@@ -0,0 +1,18 @@
+---
+"@object-ui/data-objectstack": patch
+---
+
+refactor(data-objectstack): route `batchTransaction` through the client SDK only, drop the raw-fetch branch
+
+`@objectstack/client@^16` (framework #3271, the current ObjectUI dependency
+floor) ships `data.batchTransaction`, so `ObjectStackAdapter.batchTransaction`
+now calls the typed SDK method directly. The transitional hand-rolled
+`fetch('/api/v1/batch')` branch — a feature-detect shim kept while the SDK
+method was unreleased — is removed (#2694). Per AGENTS.md §7, adapter data
+always flows through `@objectstack/client`, never a raw `fetch`.
+
+No behavior change: the SDK still drives the server's atomic `POST /api/v1/batch`,
+one `MutationEvent` is emitted per committed op (no double-fire), and the adapter
+still degrades to the non-atomic `emulateBatchTransaction` when this backend lacks
+the endpoint (404/405) or its runtime can't do transactions (501). Every other
+status still surfaces to the caller.

content/docs/guide/data-source.md

@@ -178,8 +178,10 @@ Master-detail saves (a parent record plus its child line items) go through
 `dataSource.batchTransaction(operations)` — one ordered list of cross-object
 create/update/delete operations, where a child's foreign key can be
 `{ $ref: <parent op index> }` to point at a parent created in the same batch.
-The `@object-ui/data-objectstack` adapter maps this to the server's atomic
-`POST /api/v1/batch` endpoint (commit-all-or-roll-back-all). Adapters without a
+The `@object-ui/data-objectstack` adapter maps this to the published
+`@objectstack/client` `data.batchTransaction` SDK method, which drives the
+server's atomic `POST /api/v1/batch` endpoint (commit-all-or-roll-back-all).
+Adapters without a
 transactional endpoint don't need to hand-write orchestration: call
 `emulateBatchTransaction(dataSource, operations)` from `@object-ui/core`, which
 executes the operations sequentially (resolving `$ref`s) with best-effort

docs/adr/0001-master-detail-subform.md

@@ -347,3 +347,21 @@ item 4):
   endpoint is absent (404/405) or the runtime can't do transactions (501).
 - Hard removal of the emulation is gated on the server advertising a batch
   capability via discovery (not yet advertised), so the fallback stays for now.
+
+## Addendum (2026-07, #2694): batch transport goes through the client SDK
+
+Follow-up to the #2679 unification above, now that `@objectstack/client@^16`
+(framework #3271) ships `data.batchTransaction` and is the ObjectUI dependency
+floor:
+
+- `ObjectStackAdapter.batchTransaction` calls the typed SDK method
+  `client.data.batchTransaction(operations)` directly. The transitional
+  hand-rolled `fetch('/api/v1/batch')` branch — a feature-detect shim kept while
+  the SDK method was unreleased — has been removed. Per AGENTS.md §7, adapter
+  data always flows through `@objectstack/client`, never a raw `fetch`.
+- Behavior is unchanged: the SDK still drives the server's atomic
+  `POST /api/v1/batch`, and the adapter still degrades to
+  `emulateBatchTransaction` when this backend lacks the endpoint (404/405) or its
+  runtime can't do transactions (501). Every other status surfaces to the caller.
+- The non-atomic emulation itself is untouched (still gated on a
+  discovery-advertised batch capability, not yet advertised).

packages/data-objectstack/src/index.ts

@@ -448,10 +448,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   // failing requests on every record open / panel render.
   private missingResources = new Set<string>();
   // Set once the server has told us it can't do a cross-object transactional
-  // batch (POST /api/v1/batch answered 404/405/501). After that, batchTransaction
-  // stops probing the endpoint and serves every call via the client-side
-  // emulation — the non-atomic fallback lives HERE, isolated to the one adapter
-  // that has to cope with a backend lacking server atomicity (#2679).
+  // batch (the client SDK's data.batchTransaction threw HTTP 404/405/501). After
+  // that, batchTransaction skips the SDK call and serves every call via the
+  // client-side emulation — the non-atomic fallback lives HERE, isolated to the
+  // one adapter that has to cope with a backend lacking server atomicity (#2679).
   private batchUnsupported = false;
   // The server's declared cross-object atomic-batch capability, read from
   // discovery at connect() (framework #3298 / objectui #2693). `true` → the
@@ -996,20 +996,22 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * created id, so a child can reference its parent created earlier in the same
    * batch (master-detail).
    *
-   * Transport preference: the published `@objectstack/client` SDK method when
-   * available (framework #3271), else a raw `POST /api/v1/batch`.
+   * Transport: the published `@objectstack/client` SDK method
+   * `data.batchTransaction` (framework #3271; shipped since client v16, our
+   * dependency floor). Per AGENTS.md §7 data always flows through the client —
+   * never a hand-rolled `fetch('/api/v1/batch')`.
    *
    * Fallback decision — declarative capability negotiation (framework #3298 /
    * objectui #2693). At connect() we read `capabilities.transactionalBatch`
    * from discovery:
    *   - Declared `true` → the backend GUARANTEES atomicity (declared ===
    *     enforced). We TRUST it: any batch failure — including 404/405/501 —
-   *     surfaces as a real error. No runtime probe, no non-atomic client-side
-   *     compensation. This is the path modern backends take.
+   *     surfaces as a real error. No non-atomic client-side compensation. This
+   *     is the path modern backends take.
    *   - Declared `false`, or ABSENT (backend predates #3298) → we can't rely on
-   *     server atomicity, so we keep the legacy behaviour: try `/batch`, and on
-   *     404/405 (no endpoint) or 501 (runtime without transactions) degrade to
-   *     the client-side, NON-atomic {@link emulateBatchTransaction} so a save is
+   *     server atomicity, so we keep the legacy behaviour: on 404/405 (no
+   *     endpoint) or 501 (runtime without transactions) degrade to the
+   *     client-side, NON-atomic {@link emulateBatchTransaction} so a save is
    *     still possible. Removing that here would regress older backends from
    *     "saves, less safe" to "no save path" (#2679 compatibility constraint).
    *     The non-atomic fallback stays isolated to THIS adapter.
@@ -1023,66 +1025,37 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
 
     // When the backend declares atomic batch support we never degrade: a
     // failure is a real error, not a cue to fall back. Otherwise (declared
-    // false, or capability absent on a pre-#3298 backend) the runtime-probe +
-    // emulation fallback below stays active.
+    // false, or capability absent on a pre-#3298 backend) the emulation
+    // fallback below stays active.
     const guaranteed = this.atomicBatchCapability === true;
 
-    // Already probed-and-degraded on a non-declaring backend — skip the probe.
+    // Already degraded on a non-declaring backend — skip the SDK call.
     // (Unreachable once `guaranteed`: that path never sets `batchUnsupported`.)
     if (!guaranteed && this.batchUnsupported) {
       return emulateBatchTransaction(this, operations);
     }
 
-    // Prefer the typed SDK method when the installed client exposes it
-    // (feature-detect, same pattern as updateMany/import). Older clients that
-    // predate it fall through to the raw-fetch mainline below.
-    const sdkBatch = (this.client.data as any).batchTransaction;
-    if (typeof sdkBatch === 'function') {
-      try {
-        const payload: { results: any[] } = await sdkBatch.call(this.client.data, operations);
-        this.emitBatchMutations(operations, payload?.results);
-        return payload;
-      } catch (err) {
-        const status = this.errorStatusOf(err);
-        if (!guaranteed && this.batchStatusUnsupported(status)) {
-          return this.fallbackToEmulation(operations, status);
-        }
-        throw err;
-      }
-    }
-
-    const url = `${this.baseUrl}/api/v1/batch`;
-    const response = await this.fetchImpl(url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-      // Send the session cookie too: in the browser console auth is cookie-based
-      // (no bearer `token`), so without `credentials: 'include'` this raw fetch
-      // is unauthenticated — every master-detail batch save would 401. Bearer
-      // (server-to-server) and cookie (console) auth now both work.
-      credentials: 'include',
-      body: JSON.stringify({ operations }),
-    });
-    if (!response.ok) {
-      // On a non-declaring backend, endpoint missing (404/405) or runtime can't
-      // do transactions (the framework rest-server answers 501 "Transactional
-      // batch not supported by this runtime") → degrade to the non-atomic client
-      // emulation. When the backend DECLARED support (`guaranteed`), even these
-      // are hard errors — a server that advertised the capability must honour it.
-      // Every other status (400 validation, 401/403 auth, 409 conflict, 500
-      // fault) is a real error the caller must see — never silently retried.
-      if (!guaranteed && this.batchStatusUnsupported(response.status)) {
-        return this.fallbackToEmulation(operations, response.status);
+    try {
+      // Typed SDK method — guaranteed present by the `@objectstack/client@^16`
+      // dependency floor (framework #3271). No hand-rolled POST /api/v1/batch.
+      const payload = await this.client.data.batchTransaction(operations);
+      this.emitBatchMutations(operations, payload?.results);
+      return payload;
+    } catch (err) {
+      // On a non-declaring backend, endpoint missing (404/405) or a runtime that
+      // can't do transactions (the framework rest-server answers 501
+      // "Transactional batch not supported by this runtime") → degrade to the
+      // non-atomic client emulation so the save still goes through. When the
+      // backend DECLARED support (`guaranteed`), even these are hard errors — a
+      // server that advertised the capability must honour it. Every other status
+      // (400 validation, 401/403 auth, 409 conflict, 500 fault) is a real error
+      // the caller must see — never silently retried.
+      const status = this.errorStatusOf(err);
+      if (!guaranteed && this.batchStatusUnsupported(status)) {
+        return this.fallbackToEmulation(operations, status);
       }
-      const error = await response.json().catch(() => ({ message: response.statusText }));
-      throw new ObjectStackError(
-        error.error || error.message || `Batch failed with status ${response.status}`,
-        'BATCH_ERROR',
-        response.status,
-      );
+      throw err;
     }
-    const payload: { results: any[] } = await response.json();
-    this.emitBatchMutations(operations, payload?.results);
-    return payload;
   }
 
   /** True for statuses that mean "this backend can't do a transactional batch". */

packages/data-objectstack/src/onMutation.test.ts

@@ -237,30 +237,33 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
 });
 
 /**
- * #2679: when POST /api/v1/batch is unavailable (endpoint missing → 404/405, or
- * a runtime without transactions → 501), the adapter degrades to a client-side,
- * NON-atomic emulation instead of failing the save. This is the isolated home of
- * the non-atomic fallback — the form no longer carries it. Real errors (4xx/5xx
- * other than those three) must still surface, never be silently downgraded.
+ * #2679 / #2694: cross-object saves go through the SDK's
+ * `client.data.batchTransaction` (no hand-rolled POST /api/v1/batch). When the
+ * SDK reports this backend can't do a transactional batch — it throws an error
+ * carrying HTTP 404/405 (endpoint missing) or 501 (runtime without
+ * transactions) — the adapter degrades to a client-side, NON-atomic emulation
+ * instead of failing the save. This is the isolated home of the non-atomic
+ * fallback — the form no longer carries it. Real errors (any other 4xx/5xx)
+ * must still surface, never be silently downgraded.
  */
 describe('ObjectStackAdapter.batchTransaction fallback (no server atomicity)', () => {
+  // The SDK's batchTransaction signals "backend can't do a transactional batch"
+  // by throwing an error decorated with the HTTP status (the @objectstack/client
+  // convention that `errorStatusOf` reads).
   function makeFallbackDS(opts: { batchStatus: number; clientData: Record<string, any> }) {
-    const fetchMock = vi.fn(async () =>
-      new Response(JSON.stringify({ error: 'nope' }), {
-        status: opts.batchStatus,
-        headers: { 'Content-Type': 'application/json' },
-      }),
-    );
-    const ds: any = new ObjectStackAdapter({ baseUrl: 'http://test.local', fetch: fetchMock });
+    const batchTransaction = vi.fn(async () => {
+      throw Object.assign(new Error('nope'), { httpStatus: opts.batchStatus });
+    });
+    const ds: any = new ObjectStackAdapter({ baseUrl: 'http://test.local', fetch: vi.fn() });
     ds.connected = true;
     ds.connectionState = 'connected';
-    ds.client = { data: opts.clientData };
-    return { ds, fetchMock };
+    ds.client = { data: { batchTransaction, ...opts.clientData } };
+    return { ds, batchTransaction };
   }
 
   it('404 → warns once, saves via the create primitive, and caches the detection', async () => {
     const create = vi.fn(async (_o: string, d: any) => ({ record: { id: 'p1', ...d } }));
-    const { ds, fetchMock } = makeFallbackDS({ batchStatus: 404, clientData: { create } });
+    const { ds, batchTransaction } = makeFallbackDS({ batchStatus: 404, clientData: { create } });
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const events: MutationEvent[] = [];
     ds.onMutation((e: MutationEvent) => events.push(e));
@@ -274,11 +277,11 @@ describe('ObjectStackAdapter.batchTransaction fallback (no server atomicity)', (
     // committed-batch path (no double emission).
     expect(events).toEqual([{ type: 'create', resource: 'proj', record: { id: 'p1', name: 'A' } }]);
 
-    const probes = fetchMock.mock.calls.length;
     // A second batch short-circuits: the endpoint is known-unsupported, so we
-    // never probe POST /api/v1/batch again.
+    // never call the SDK batch method again.
+    expect(batchTransaction).toHaveBeenCalledTimes(1);
     await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'B' } }]);
-    expect(fetchMock.mock.calls.length).toBe(probes);
+    expect(batchTransaction).toHaveBeenCalledTimes(1);
     warn.mockRestore();
   });
 
@@ -291,7 +294,7 @@ describe('ObjectStackAdapter.batchTransaction fallback (no server atomicity)', (
     warn.mockRestore();
   });
 
-  it('a real error (400) surfaces as ObjectStackError — never downgraded to emulation', async () => {
+  it('a real error (400) surfaces — never downgraded to emulation', async () => {
     const create = vi.fn();
     const { ds } = makeFallbackDS({ batchStatus: 400, clientData: { create } });
     await expect(
@@ -301,16 +304,20 @@ describe('ObjectStackAdapter.batchTransaction fallback (no server atomicity)', (
     expect(create).not.toHaveBeenCalled();
   });
 
-  it('prefers the SDK client.data.batchTransaction when present (no raw fetch)', async () => {
+  it('routes a committed batch through the SDK method and never hand-rolls a fetch', async () => {
     const sdkBatch = vi.fn(async () => ({ results: [{ id: 'p1', name: 'A' }] }));
-    const { ds, fetchMock } = makeFallbackDS({ batchStatus: 500, clientData: { batchTransaction: sdkBatch } });
+    const fetchMock = vi.fn();
+    const ds: any = new ObjectStackAdapter({ baseUrl: 'http://test.local', fetch: fetchMock });
+    ds.connected = true;
+    ds.connectionState = 'connected';
+    ds.client = { data: { batchTransaction: sdkBatch } };
     const events: MutationEvent[] = [];
     ds.onMutation((e: MutationEvent) => events.push(e));
 
     const res = await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'A' } }]);
 
     expect(sdkBatch).toHaveBeenCalledTimes(1);
-    expect(fetchMock).not.toHaveBeenCalled(); // raw /api/v1/batch not used
+    expect(fetchMock).not.toHaveBeenCalled(); // no raw POST /api/v1/batch
     expect(res.results[0]).toMatchObject({ id: 'p1' });
     // Committed via the SDK → one event per op (emitted once).
     expect(events).toEqual([{ type: 'create', resource: 'proj', record: { id: 'p1', name: 'A' } }]);
@@ -400,12 +407,14 @@ describe('ObjectStackAdapter.batchTransaction capability gate (#2693 / framework
     /** Value placed at `capabilities.transactionalBatch`; omit to leave it absent. */
     capability?: boolean | { enabled: boolean };
     batchStatus: number;
-    /** Response body for the `/batch` call (defaults to an error envelope). */
+    /** Result the SDK batch resolves with on a 2xx `batchStatus`. */
     batchBody?: unknown;
     clientData?: Record<string, any>;
   }) {
     const capabilities: Record<string, unknown> = {};
     if (opts.capability !== undefined) capabilities.transactionalBatch = opts.capability;
+    // connect() still fetches discovery to read the #3298 capability; the batch
+    // itself now goes through the SDK method (no raw POST /api/v1/batch).
     const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
       const url = String(input);
       if (url.includes('/api/v1/discovery')) {
@@ -414,20 +423,25 @@ describe('ObjectStackAdapter.batchTransaction capability gate (#2693 / framework
           { status: 200, headers: { 'Content-Type': 'application/json' } },
         );
       }
-      // POST /api/v1/batch
-      return new Response(JSON.stringify(opts.batchBody ?? { error: 'nope' }), {
-        status: opts.batchStatus,
-        headers: { 'Content-Type': 'application/json' },
-      });
+      return new Response('{}', { status: 404, headers: { 'Content-Type': 'application/json' } });
+    });
+    // The SDK batch resolves on a 2xx status and otherwise throws a
+    // status-decorated error (the @objectstack/client convention `errorStatusOf`
+    // reads) — the signal the capability gate + fallback branch on.
+    const batchTransaction = vi.fn(async () => {
+      if (opts.batchStatus >= 200 && opts.batchStatus < 300) {
+        return opts.batchBody ?? { results: [] };
+      }
+      throw Object.assign(new Error('nope'), { httpStatus: opts.batchStatus });
     });
     const ds: any = new ObjectStackAdapter({
       baseUrl: 'http://test.local',
       autoReconnect: false,
       fetch: fetchMock,
     });
-    // Feature-detect target for the SDK batch method + emulation primitives.
-    ds.client = { data: opts.clientData ?? {} };
-    return { ds, fetchMock };
+    // SDK batch method + emulation primitives live on the stubbed client.
+    ds.client = { data: { batchTransaction, ...(opts.clientData ?? {}) } };
+    return { ds, fetchMock, batchTransaction };
   }
 
   it('declared transactionalBatch:true → a 404 is a hard error, NOT downgraded to emulation', async () => {