@object-ui/data-objectstack 16.0.0 → 17.1.0

package/src/integration.ts

@@ -143,6 +143,10 @@ export class IntegrationManager {
           }
         } catch (e) {
           if (e instanceof TypeError) {
+            // A malformed URL surfaces as its own message; we can't attach `e`
+            // as the `Error` `cause` because this package targets ES2020, whose
+            // lib types the 1-arg `Error` constructor only. Scoped disable.
+            // eslint-disable-next-line preserve-caught-error
             throw new Error(`Invalid webhook URL: ${url}`);
           }
           throw e;
@@ -168,6 +172,10 @@ export class IntegrationManager {
           }
         } catch (e) {
           if (e instanceof TypeError) {
+            // A malformed URL surfaces as its own message; we can't attach `e`
+            // as the `Error` `cause` because this package targets ES2020, whose
+            // lib types the 1-arg `Error` constructor only. Scoped disable.
+            // eslint-disable-next-line preserve-caught-error
             throw new Error(`Invalid Slack webhook URL: ${url}`);
           }
           throw e;

package/src/listViews.test.ts

@@ -30,6 +30,33 @@ function makeDS(items: any[]) {
   return ds;
 }
 
+/**
+ * A DS whose HTTP layer answers the `?preview=draft` metadata route with a
+ * pre-overlaid list (the shape the framework already returns: draft wins by
+ * name, each draft tagged `_draft`). The published `client.meta.getItems` stub
+ * is present but MUST NOT be used in preview mode.
+ */
+function makeDraftDS(overlaid: any[]) {
+  const fetchImpl = vi.fn(async (input: RequestInfo | URL) => {
+    const url = String(input);
+    if (url.includes('/meta/view')) {
+      return new Response(JSON.stringify({ items: overlaid }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    return new Response(JSON.stringify({ success: true, data: {} }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  });
+  const ds: any = new ObjectStackAdapter({ baseUrl: 'http://test.local', fetch: fetchImpl });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  ds.client = { meta: { getItems: vi.fn(async () => ({ items: [] })) } };
+  return { ds, fetchImpl };
+}
+
 describe('ObjectStackDataSource.listViews', () => {
   // The crm_activity view set as the framework expands it.
   const listAll = {
@@ -75,4 +102,74 @@ describe('ObjectStackDataSource.listViews', () => {
     const views = await ds.listViews('crm_activity');
     expect(views.map((v: any) => v.name).sort()).toEqual(['saved_grid', 'wrapped_grid']);
   });
+
+  // ── #2767 draft-preview branch ───────────────────────────────────────────
+  describe('previewDrafts (#2767 P2/P3)', () => {
+    it('reads the draft-overlaid list in a SINGLE preview=draft request', async () => {
+      // Server response overlays a draft edit of `all` (draft wins by name) and
+      // a brand-new draft-only `mine`; `calendar` is untouched/published.
+      const overlaid = [
+        {
+          name: 'crm_activity.all', object: 'crm_activity', viewKind: 'list',
+          label: 'All (edited)', config: { type: 'grid', data: { object: 'crm_activity' } },
+          _draft: true,
+        },
+        {
+          name: 'crm_activity.calendar', object: 'crm_activity', viewKind: 'list',
+          label: 'Activity Calendar', config: { type: 'calendar', data: { object: 'crm_activity' } },
+        },
+        {
+          name: 'crm_activity.mine', object: 'crm_activity', viewKind: 'list',
+          label: 'Mine', config: { type: 'grid', data: { object: 'crm_activity' } },
+          _draft: true,
+        },
+      ];
+      const { ds, fetchImpl } = makeDraftDS(overlaid);
+      const views = await ds.listViews('crm_activity', { previewDrafts: true });
+
+      // Exactly one request, and it carries the preview flag.
+      const metaCalls = fetchImpl.mock.calls.filter(([u]: any[]) => String(u).includes('/meta/view'));
+      expect(metaCalls).toHaveLength(1);
+      expect(String(metaCalls[0][0])).toContain('preview=draft');
+      // Preview mode must NOT also hit the published path (that's the P2 dupe bug).
+      expect(ds.client.meta.getItems).not.toHaveBeenCalled();
+
+      // One tab per name — the draft edit of `all` does not duplicate it.
+      expect(views.map((v: any) => v.name).sort()).toEqual([
+        'crm_activity.all', 'crm_activity.calendar', 'crm_activity.mine',
+      ]);
+    });
+
+    it('flows the _draft provenance flag through for the switcher badge', async () => {
+      const overlaid = [
+        {
+          name: 'crm_activity.mine', object: 'crm_activity', viewKind: 'list',
+          label: 'Mine', config: { type: 'grid', data: { object: 'crm_activity' } }, _draft: true,
+        },
+        {
+          name: 'crm_activity.calendar', object: 'crm_activity', viewKind: 'list',
+          label: 'Cal', config: { type: 'calendar', data: { object: 'crm_activity' } },
+        },
+      ];
+      const { ds } = makeDraftDS(overlaid);
+      const views = await ds.listViews('crm_activity', { previewDrafts: true });
+      expect(views.find((v: any) => v.name === 'crm_activity.mine')?._draft).toBe(true);
+      expect(views.find((v: any) => v.name === 'crm_activity.calendar')?._draft).toBeUndefined();
+    });
+
+    it('non-preview mode uses the published getItems path (no draft fetch)', async () => {
+      const { ds, fetchImpl } = makeDraftDS([]);
+      ds.client.meta.getItems = vi.fn(async () => ({
+        items: [{
+          name: 'crm_activity.all', object: 'crm_activity', viewKind: 'list',
+          config: { type: 'grid', data: { object: 'crm_activity' } },
+        }],
+      }));
+      const views = await ds.listViews('crm_activity');
+      expect(ds.client.meta.getItems).toHaveBeenCalledTimes(1);
+      expect(fetchImpl.mock.calls.filter(([u]: any[]) => String(u).includes('/meta/view'))).toHaveLength(0);
+      expect(views.map((v: any) => v.name)).toEqual(['crm_activity.all']);
+      expect(views[0]._draft).toBeUndefined();
+    });
+  });
 });

package/src/metadata-client.test.ts

@@ -59,6 +59,14 @@ describe('MetadataClient', () => {
     expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object');
   });
 
+  it('save() rejects an empty name before any request (#2767 empty-name 405)', async () => {
+    const c = client('http://localhost:3000');
+    await expect(c.save('view', '', { columns: [] })).rejects.toThrow(/name must be non-empty/);
+    await expect(c.save('view', '   ', { columns: [] })).rejects.toThrow(/name must be non-empty/);
+    // No malformed `PUT /meta/view/` ever reached the transport.
+    expect(urls).toEqual([]);
+  });
+
   it('builds scoped URLs when environmentId is set', async () => {
     await client('http://localhost:3000', 'env_42').list('object');
     expect(urls[0]).toBe('http://localhost:3000/api/v1/environments/env_42/meta/object');

package/src/metadata-client.ts

@@ -529,6 +529,15 @@ export class MetadataClient {
     item: unknown,
     options: MetadataSaveOptions = {},
   ): Promise<T> {
+    if (!name || !String(name).trim()) {
+      // The `PUT /meta/:type/:name` route rejects a missing `:name` segment
+      // with 405. Fail with a clear contextual error at the call boundary
+      // instead of firing a malformed request at the server (#2767).
+      throw new Error(
+        `MetadataClient.save: name must be non-empty (type="${type}").` +
+          ' The PUT /meta/:type/:name route requires a name segment.',
+      );
+    }
     const params: string[] = [];
     if (options.force) params.push('force=true');
     if (options.mode === 'draft') params.push('mode=draft');

package/src/onMutation.test.ts

@@ -17,9 +17,13 @@
  * issued by ObjectGrid's default batch-save were silent and the grid kept
  * showing stale rows until a manual reload.
  */
-import { describe, it, expect, vi } from 'vitest';
-import { ObjectStackAdapter } from './index';
-import type { MutationEvent } from '@object-ui/types';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  ObjectStackAdapter,
+  clearSharedDiscoveryCache,
+  readTransactionalBatchCapability,
+} from './index';
+import type { DataSourceMutationEvent } from '@object-ui/types';
 
 function makeDS(stub: Record<string, any>) {
   const ds: any = new ObjectStackAdapter({
@@ -45,8 +49,8 @@ describe('ObjectStackAdapter.onMutation', () => {
       .mockResolvedValue({ record: { id: 'r1', account: 'acc-1' } });
     const ds = makeDS({ update });
 
-    const events: MutationEvent[] = [];
-    const unsub = ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    const unsub = ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.update('showcase_project', 'r1', { account: 'acc-1' });
 
@@ -63,8 +67,8 @@ describe('ObjectStackAdapter.onMutation', () => {
   it('emits a create event with the new record', async () => {
     const create = vi.fn().mockResolvedValue({ record: { id: 'new', name: 'X' } });
     const ds = makeDS({ create });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.create('showcase_project', { name: 'X' });
 
@@ -79,8 +83,8 @@ describe('ObjectStackAdapter.onMutation', () => {
       .mockResolvedValueOnce({ deleted: true })
       .mockResolvedValueOnce({ deleted: false });
     const ds = makeDS({ delete: del });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.delete('showcase_project', 'r1');
     await ds.delete('showcase_project', 'r2');
@@ -93,8 +97,8 @@ describe('ObjectStackAdapter.onMutation', () => {
   it('emits a single bulk event per bulkUpdate call (not per id)', async () => {
     const updateMany = vi.fn().mockResolvedValue({ succeeded: 3, failed: 0, results: [] });
     const ds = makeDS({ updateMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulkUpdate('showcase_project', ['a', 'b', 'c'], { archived: true });
 
@@ -104,8 +108,8 @@ describe('ObjectStackAdapter.onMutation', () => {
   it('does not emit when a bulk operation affected zero rows', async () => {
     const updateMany = vi.fn().mockResolvedValue({ succeeded: 0, failed: 0, results: [] });
     const ds = makeDS({ updateMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulkUpdate('showcase_project', ['a'], { archived: true });
 
@@ -156,8 +160,8 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
         { status: 200, headers: { 'Content-Type': 'application/json' } },
       ),
     );
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.batchTransaction([
       { object: 'ehr_task_version', action: 'create', data: { name: 'Task version A' } },
@@ -179,8 +183,8 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
         { status: 200, headers: { 'Content-Type': 'application/json' } },
       ),
     );
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.batchTransaction([
       { object: 'ehr_task_version', action: 'update', id: 'p1', data: { name: 'Renamed' } },
@@ -204,8 +208,8 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
         headers: { 'Content-Type': 'application/json' },
       }),
     );
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.batchTransaction([{ object: 'ehr_task_version', data: { name: 'X' } }]);
 
@@ -221,8 +225,8 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
         headers: { 'Content-Type': 'application/json' },
       }),
     );
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await expect(
       ds.batchTransaction([{ object: 'ehr_task_version', action: 'create', data: {} }]),
@@ -232,6 +236,94 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
   });
 });
 
+/**
+ * #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 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: { 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, batchTransaction } = makeFallbackDS({ batchStatus: 404, clientData: { create } });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
+
+    const res = await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'A' } }]);
+
+    expect(res.results[0]).toMatchObject({ id: 'p1', name: 'A' });
+    expect(create).toHaveBeenCalledWith('proj', { name: 'A' });
+    expect(warn).toHaveBeenCalledTimes(1);
+    // Events come from the create primitive ONCE — not also re-emitted by the
+    // committed-batch path (no double emission).
+    expect(events).toEqual([{ type: 'create', resource: 'proj', record: { id: 'p1', name: 'A' } }]);
+
+    // A second batch short-circuits: the endpoint is known-unsupported, so we
+    // never call the SDK batch method again.
+    expect(batchTransaction).toHaveBeenCalledTimes(1);
+    await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'B' } }]);
+    expect(batchTransaction).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+
+  it('501 (runtime without transactions) also degrades to emulation', async () => {
+    const create = vi.fn(async (_o: string, d: any) => ({ record: { id: 'p1', ...d } }));
+    const { ds } = makeFallbackDS({ batchStatus: 501, clientData: { create } });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'A' } }]);
+    expect(create).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+
+  it('a real error (400) surfaces — never downgraded to emulation', async () => {
+    const create = vi.fn();
+    const { ds } = makeFallbackDS({ batchStatus: 400, clientData: { create } });
+    await expect(
+      ds.batchTransaction([{ object: 'proj', action: 'create', data: {} }]),
+    ).rejects.toThrow(/nope/);
+    // No client-side writes happened — the batch was rejected, not retried.
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  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 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: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
+
+    const res = await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'A' } }]);
+
+    expect(sdkBatch).toHaveBeenCalledTimes(1);
+    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' } }]);
+  });
+});
+
 /**
  * Regression for #2582 (fallback path): when the server lacks the transactional
  * batch endpoint, MasterDetailForm persists child rows via `bulk(child,
@@ -243,8 +335,8 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('emits a single create event per bulk create call', async () => {
     const createMany = vi.fn().mockResolvedValue([{ id: 'c1' }, { id: 'c2' }]);
     const ds = makeDS({ createMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulk('ehr_task_check_item', 'create', [{ label: 'a' }, { label: 'b' }]);
 
@@ -254,8 +346,8 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('does not emit when a bulk create returned zero records', async () => {
     const createMany = vi.fn().mockResolvedValue([]);
     const ds = makeDS({ createMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulk('ehr_task_check_item', 'create', [{ label: 'a' }]);
 
@@ -265,8 +357,8 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('emits a single delete event per bulk delete call', async () => {
     const deleteMany = vi.fn().mockResolvedValue(undefined);
     const ds = makeDS({ deleteMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulk('ehr_task_check_item', 'delete', [{ id: 'c1' }, { id: 'c2' }] as any);
 
@@ -276,8 +368,8 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('emits a single update event per bulk update call', async () => {
     const updateMany = vi.fn().mockResolvedValue([{ id: 'c1' }]);
     const ds = makeDS({ updateMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulk('ehr_task_check_item', 'update', [{ id: 'c1', label: 'x' }] as any);
 
@@ -287,11 +379,184 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('bulk create failure emits nothing', async () => {
     const createMany = vi.fn().mockRejectedValue(new Error('boom'));
     const ds = makeDS({ createMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await expect(ds.bulk('ehr_task_check_item', 'create', [{ label: 'a' }])).rejects.toThrow();
 
     expect(events).toEqual([]);
   });
 });
+
+/**
+ * #2693 / framework#3298 — declarative capability negotiation for atomic batch.
+ *
+ * The adapter reads `capabilities.transactionalBatch` from discovery at
+ * connect(). When the backend DECLARES support it TRUSTS server atomicity and
+ * never degrades to the non-atomic client emulation — a batch failure (even
+ * 404/405/501) is a real error. When the capability is ABSENT (backend predates
+ * #3298) or explicitly `false`, the legacy runtime-probe + emulation fallback
+ * stays active so a save is still possible (#2679 compatibility constraint).
+ */
+describe('ObjectStackAdapter.batchTransaction capability gate (#2693 / framework#3298)', () => {
+  // The discovery cache is module-level and shared across files in the (unit)
+  // project — reset it so each case reads its own advertised capability.
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  function makeCapabilityDS(opts: {
+    /** Value placed at `capabilities.transactionalBatch`; omit to leave it absent. */
+    capability?: boolean | { enabled: boolean };
+    batchStatus: number;
+    /** 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')) {
+        return new Response(
+          JSON.stringify({ success: true, data: { name: 't', version: '1.0.0', capabilities } }),
+          { status: 200, 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,
+    });
+    // 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 () => {
+    const create = vi.fn();
+    const { ds } = makeCapabilityDS({ capability: { enabled: true }, batchStatus: 404, clientData: { create } });
+
+    await expect(
+      ds.batchTransaction([{ object: 'proj', action: 'create', data: {} }]),
+    ).rejects.toThrow(/nope/);
+    // A declared-atomic backend is trusted: no client-side compensation ran.
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('declared transactionalBatch:true → 501 is also a hard error (no emulation)', async () => {
+    const create = vi.fn();
+    const { ds } = makeCapabilityDS({ capability: { enabled: true }, batchStatus: 501, clientData: { create } });
+
+    await expect(
+      ds.batchTransaction([{ object: 'proj', action: 'create', data: {} }]),
+    ).rejects.toThrow();
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('accepts the flat boolean capability shape too', async () => {
+    const create = vi.fn();
+    const { ds } = makeCapabilityDS({ capability: true, batchStatus: 404, clientData: { create } });
+
+    await expect(
+      ds.batchTransaction([{ object: 'proj', action: 'create', data: {} }]),
+    ).rejects.toThrow();
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('declared support → a committed batch commits via /batch and emits one event per op', async () => {
+    const { ds } = makeCapabilityDS({
+      capability: { enabled: true },
+      batchStatus: 200,
+      batchBody: { results: [{ id: 'p1', name: 'A' }, { id: 'c1', proj: 'p1' }] },
+    });
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
+
+    const res = await ds.batchTransaction([
+      { object: 'proj', action: 'create', data: { name: 'A' } },
+      { object: 'item', action: 'create', data: { proj: { $ref: 0 } } },
+    ]);
+
+    expect(res.results).toHaveLength(2);
+    expect(events).toEqual([
+      { type: 'create', resource: 'proj', record: { id: 'p1', name: 'A' } },
+      { type: 'create', resource: 'item', record: { id: 'c1', proj: 'p1' } },
+    ]);
+  });
+
+  it('declared transactionalBatch:false → 404 still degrades to non-atomic emulation', async () => {
+    const create = vi.fn(async (_o: string, d: any) => ({ record: { id: 'p1', ...d } }));
+    const { ds } = makeCapabilityDS({ capability: { enabled: false }, batchStatus: 404, clientData: { create } });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const res = await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'A' } }]);
+
+    expect(create).toHaveBeenCalledWith('proj', { name: 'A' });
+    expect(res.results[0]).toMatchObject({ id: 'p1', name: 'A' });
+    warn.mockRestore();
+  });
+
+  it('capability ABSENT (backend predates #3298) → 404 degrades to emulation (back-compat)', async () => {
+    const create = vi.fn(async (_o: string, d: any) => ({ record: { id: 'p1', ...d } }));
+    const { ds } = makeCapabilityDS({ batchStatus: 404, clientData: { create } }); // no capability advertised
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'A' } }]);
+
+    expect(create).toHaveBeenCalledWith('proj', { name: 'A' });
+    warn.mockRestore();
+  });
+
+  it('declared support → a real error (400) surfaces unchanged', async () => {
+    const create = vi.fn();
+    const { ds } = makeCapabilityDS({ capability: { enabled: true }, batchStatus: 400, clientData: { create } });
+
+    await expect(
+      ds.batchTransaction([{ object: 'proj', action: 'create', data: {} }]),
+    ).rejects.toThrow(/nope/);
+    expect(create).not.toHaveBeenCalled();
+  });
+});
+
+/**
+ * Unit coverage for the discovery capability reader — it must accept both the
+ * hierarchical `{ enabled }` wire shape (what the framework producers emit) and
+ * the flat boolean the client SDK normalizes to, and return `undefined` for a
+ * pre-#3298 backend that advertises nothing.
+ */
+describe('readTransactionalBatchCapability (#3298 shape reader)', () => {
+  it('reads the hierarchical { enabled } form', () => {
+    expect(readTransactionalBatchCapability({ capabilities: { transactionalBatch: { enabled: true } } })).toBe(true);
+    expect(readTransactionalBatchCapability({ capabilities: { transactionalBatch: { enabled: false } } })).toBe(false);
+  });
+
+  it('reads the flat boolean form', () => {
+    expect(readTransactionalBatchCapability({ capabilities: { transactionalBatch: true } })).toBe(true);
+    expect(readTransactionalBatchCapability({ capabilities: { transactionalBatch: false } })).toBe(false);
+  });
+
+  it('returns undefined when the capability (or the whole map) is absent', () => {
+    expect(readTransactionalBatchCapability({ capabilities: {} })).toBeUndefined();
+    expect(readTransactionalBatchCapability({ capabilities: { comments: { enabled: true } } })).toBeUndefined();
+    expect(readTransactionalBatchCapability({})).toBeUndefined();
+    expect(readTransactionalBatchCapability(null)).toBeUndefined();
+    expect(readTransactionalBatchCapability(undefined)).toBeUndefined();
+  });
+
+  it('ignores a malformed capability value', () => {
+    expect(readTransactionalBatchCapability({ capabilities: { transactionalBatch: { enabled: 'yes' } } })).toBeUndefined();
+    expect(readTransactionalBatchCapability({ capabilities: { transactionalBatch: 'true' } })).toBeUndefined();
+  });
+});