feat(data-objectstack): gate non-atomic batch fallback on discovery transactionalBatch capability (#2693) (#2755)

ObjectStackAdapter.batchTransaction now negotiates atomic cross-object batch
declaratively via the discovery capability bit (framework #3298) instead of
only probing at runtime.

- connect() reads capabilities.transactionalBatch from GET /api/v1/discovery
  and records it as a tri-state (readTransactionalBatchCapability accepts both
  the hierarchical `{ enabled }` wire shape and the flat boolean the client SDK
  normalizes to).
- When the backend DECLARES support (true), batchTransaction trusts server
  atomicity: it calls /batch and surfaces any failure — including 404/405/501 —
  as a real error. No runtime probe, no non-atomic client-side compensation.
- When the capability is false or ABSENT (backend predates #3298), the legacy
  runtime-probe + emulation fallback stays active so a save is still possible;
  hard-removing it would regress older backends from "saves, less safe" to
  "no save path" (#2679 compatibility constraint).

core's generic emulateBatchTransaction / runBatchTransaction are untouched and
remain the fallback for adapters with no server-side transaction.

Docs: adapter README + data-source guide document the capability table and the
minimum-backend note (atomicity guaranteed only against backends advertising
the capability — framework #3298 / #1604). Adds tests for each capability state
and a unit test for the shape reader.

Picks up #2679 acceptance item 4; unblocked by framework#3298 (merged).


Claude-Session: https://claude.ai/code/session_01U1UuBuaurza8a2XWSUaDQr

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/batch-transactional-capability-gate.md

@@ -0,0 +1,32 @@
+---
+"@object-ui/data-objectstack": minor
+---
+
+feat(data-objectstack): gate the non-atomic batch fallback on the discovery `transactionalBatch` capability (#2693)
+
+`ObjectStackAdapter.batchTransaction` now negotiates atomic cross-object batch
+**declaratively** instead of only probing at runtime. At `connect()` the adapter
+reads `capabilities.transactionalBatch` from `GET /api/v1/discovery`
+(framework #3298 — `declared === enforced`; the server advertises `true` only
+when the `/batch` route is mounted *and* the runtime engine can honour a
+transaction):
+
+- **Declared `true`** — the adapter TRUSTS server atomicity: it calls `/batch`
+  and surfaces any failure (including `404`/`405`/`501`) as a real error. No
+  runtime probe, no non-atomic client-side compensation.
+- **Declared `false`, or absent** (backend predates #3298) — the legacy path is
+  unchanged: probe `/batch` and, on `404`/`405`/`501`, fall back to the
+  non-atomic `emulateBatchTransaction`. Keeping this avoids regressing older
+  backends from "saves, less safe" to "no save path" (#2679 compat constraint).
+
+Both the hierarchical wire shape (`{ transactionalBatch: { enabled: true } }`)
+and the flat form the client SDK normalizes to (`{ transactionalBatch: true }`)
+are accepted. `@object-ui/core`'s generic `emulateBatchTransaction` /
+`runBatchTransaction` are untouched and remain the fallback for adapters with no
+server-side transaction (`ValueDataSource`, `MockDataSource`, …).
+
+Docs: the adapter README and the data-source guide now document the capability
+table and the minimum-backend note — atomic cross-object saves are guaranteed
+only against backends advertising the capability (framework #3298 / #1604).
+
+Picks up #2679 acceptance item 4; unblocked by framework#3298 (merged).

content/docs/guide/data-source.md

@@ -186,3 +186,16 @@ executes the operations sequentially (resolving `$ref`s) with best-effort
 compensation on failure. UI components never branch on atomicity — they call
 `runBatchTransaction(dataSource, operations)` (also from `@object-ui/core`),
 which uses the adapter's method when present and emulates otherwise.
+
+The `@object-ui/data-objectstack` adapter decides whether it can trust server
+atomicity **declaratively**, at connect time: it reads the
+`capabilities.transactionalBatch` flag from `GET /api/v1/discovery`
+(framework #3298). When the backend advertises `true`, the adapter treats any
+`/batch` failure as a real error — no non-atomic client-side compensation. When
+the flag is `false` or absent (a backend predating #3298), it keeps the legacy
+behaviour: probe `/batch` and fall back to the non-atomic emulation on
+`404`/`405`/`501`. Atomic cross-object saves are therefore guaranteed only
+against backends that advertise the capability; older ones still save, but
+best-effort. See the
+[adapter README](../../../packages/data-objectstack/README.md#cross-object-atomic-batch-batchtransaction)
+for the full capability table and minimum-backend note.

packages/data-objectstack/README.md

@@ -272,6 +272,68 @@ await dataSource.bulk('users', 'delete', [
 - Provides partial success reporting for resilient error handling
 - Atomic operations where supported by the backend
 
+## Cross-Object Atomic Batch (`batchTransaction`)
+
+`bulk()` above operates on **one** object. To persist a set of **cross-object**
+writes as a single all-or-nothing unit — the master-detail case, where a parent
+and its children must commit or roll back together — use `batchTransaction`:
+
+```typescript
+// Create a parent and a child that references it, atomically.
+// `{ $ref: 0 }` resolves to the id minted by operation 0 (the parent).
+await dataSource.batchTransaction([
+  { object: 'invoice',      action: 'create', data: { no: 'INV-1' } },
+  { object: 'invoice_line', action: 'create', data: { invoice: { $ref: 0 }, amount: 10 } },
+]);
+```
+
+On a supporting backend this is one `POST /api/v1/batch` that commits or rolls
+back the whole set in a single server transaction — no orphaned parent if a
+child write fails.
+
+### Declarative capability negotiation (`transactionalBatch`)
+
+Whether the adapter can rely on server atomicity is decided **at connect time**,
+not by firing a batch and reading the failure. `connect()` reads the
+`capabilities.transactionalBatch` flag from `GET /api/v1/discovery`
+([framework #3298](https://github.com/objectstack-ai/framework/issues/3298)),
+which the server sets to `true` only when the `/batch` route is mounted **and**
+the runtime engine can honour a transaction (`declared === enforced`):
+
+| Discovery `capabilities.transactionalBatch` | `batchTransaction` behaviour |
+| --- | --- |
+| `true` | **Trusts server atomicity.** Calls `/batch`; any failure — including `404`/`405`/`501` — surfaces as a real error. No non-atomic client-side fallback. |
+| `false` | Backend can't do an atomic batch (route absent, or a runtime without transactions) → falls back to the non-atomic client-side emulation below. |
+| *absent* | Backend predates #3298 and advertises nothing → the legacy runtime probe stays: try `/batch`, and on `404`/`405`/`501` fall back to emulation. |
+
+The hierarchical wire shape (`{ transactionalBatch: { enabled: true } }`) and the
+flat form the client SDK normalizes to (`{ transactionalBatch: true }`) are both
+accepted.
+
+### Non-atomic fallback
+
+When the capability is `false` or absent, the adapter degrades to a client-side
+emulation (`@object-ui/core`'s `emulateBatchTransaction`): the operations run in
+order and, on failure, it best-effort deletes the records it created (children
+before parent) before rethrowing. This is **not** a transaction — a create's
+side effects (hooks, rollups, webhooks) are not undone by a later delete, and a
+mid-batch network drop leaves no chance to compensate. It exists only so a save
+is still possible against a backend that lacks server atomicity; removing it
+would turn "saves, less safe" into "no save path" on older backends
+([objectui #2679](https://github.com/objectstack-ai/objectui/issues/2679)).
+
+### Minimum supported backend
+
+Atomic cross-object saves are **guaranteed only against ObjectStack backends on
+the 16.x line that advertise `capabilities.transactionalBatch: true`** — the
+endpoint landed in [framework #1604](https://github.com/objectstack-ai/framework/issues/1604)
+and its discovery capability in
+[framework #3298](https://github.com/objectstack-ai/framework/issues/3298).
+ObjectUI does not hard-require it: against an older backend a master-detail save
+still succeeds, but non-atomically via the fallback above. Treat the advertised
+capability as the floor for the atomicity guarantee, not as a connection
+prerequisite.
+
 ## User-Scoped State Adapter
 
 In addition to the main `DataSource` adapter, this package ships
@@ -348,6 +410,7 @@ new ObjectStackAdapter(config: {
 - `update(resource, id, data)` - Update an existing record
 - `delete(resource, id)` - Delete a record
 - `bulk(resource, operation, data)` - Batch operations (create/update/delete)
+- `batchTransaction(operations)` - Cross-object atomic batch (master-detail); atomic when the backend advertises `transactionalBatch`, else non-atomic client-side fallback
 - `getObjectSchema(objectName)` - Get schema metadata (cached)
 - `getCacheStats()` - Get cache statistics
 - `invalidateCache(key?)` - Invalidate cache entries

packages/data-objectstack/src/index.ts

@@ -178,6 +178,44 @@ export function clearSharedDiscoveryCache(): void {
   discoveryCache.clear();
 }
 
+/**
+ * Read the cross-object atomic-batch capability from a `discovery` document
+ * (framework #3298 / objectui #2693). The server advertises it hierarchically
+ * under `capabilities.transactionalBatch.enabled`; the published
+ * `@objectstack/client` also accepts the flat `capabilities.transactionalBatch:
+ * boolean` form and normalizes the two — mirror that here so the adapter reads
+ * the same bit regardless of which shape reaches it.
+ *
+ * Returns:
+ *   - `true`  — the backend GUARANTEES an atomic `/batch` (declared === enforced,
+ *     i.e. the route is mounted AND the runtime can honour a transaction): the
+ *     client may drop its non-atomic fallback and treat any batch failure as a
+ *     real error.
+ *   - `false` — the backend explicitly does NOT (route absent, or a runtime that
+ *     can't open a transaction).
+ *   - `undefined` — the capability is absent, i.e. the backend predates #3298;
+ *     the caller must keep the legacy runtime-probe fallback (we can't tell
+ *     whether `/batch` exists without trying it).
+ */
+export function readTransactionalBatchCapability(
+  discovery: unknown,
+): boolean | undefined {
+  const caps = (discovery as { capabilities?: unknown } | null | undefined)?.capabilities;
+  if (!caps || typeof caps !== 'object') return undefined;
+  const value = (caps as Record<string, unknown>).transactionalBatch;
+  // Flat form: `{ transactionalBatch: true }`.
+  if (typeof value === 'boolean') return value;
+  // Hierarchical form: `{ transactionalBatch: { enabled: true } }`.
+  if (
+    value &&
+    typeof value === 'object' &&
+    typeof (value as { enabled?: unknown }).enabled === 'boolean'
+  ) {
+    return (value as { enabled: boolean }).enabled;
+  }
+  return undefined;
+}
+
 /**
  * Detect "missing resource" errors regardless of where they originate.
  *
@@ -415,6 +453,15 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   // 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
+  // backend GUARANTEES an atomic `/batch`, so batchTransaction trusts it and
+  // never degrades to the non-atomic emulation (any failure surfaces as a real
+  // error). `false` or `undefined` (capability absent → backend predates #3298)
+  // → keep the legacy runtime-probe + emulation fallback so a save is still
+  // possible; dropping it there would turn "saves, less safe" into "no save
+  // path" on older backends (#2679 compatibility constraint).
+  private atomicBatchCapability: boolean | undefined;
   // Subscribers registered via onMutation(). Emitted after each successful
   // create/update/delete so data-bound views (ListView, ObjectView, kanban,
   // calendar) auto-refresh — the interface ListView relies on to reflect
@@ -490,6 +537,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         // helpers continue to work without a redundant fetch.
         (this.client as unknown as { discoveryInfo?: unknown }).discoveryInfo = data;
 
+        // Record the declared cross-object atomic-batch capability (#3298) so
+        // batchTransaction can decide declaratively at call time whether it may
+        // trust server atomicity instead of runtime-probing 404/405/501.
+        this.atomicBatchCapability = readTransactionalBatchCapability(data);
+
         this.connected = true;
         this.reconnectAttempts = 0;
         this.setConnectionState('connected');
@@ -945,19 +997,39 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * batch (master-detail).
    *
    * Transport preference: the published `@objectstack/client` SDK method when
-   * available (framework #3271), else a raw `POST /api/v1/batch`. Either way,
-   * if the backend has no such endpoint (404/405) or a runtime that can't do
-   * transactions (501), we degrade to a client-side, NON-atomic emulation via
-   * {@link emulateBatchTransaction} so a save is still possible — this is the
-   * isolated home of the non-atomic fallback. Hard removal of the emulation is
-   * gated on the server advertising a batch capability via discovery (the
-   * current discovery payload does not), so the fallback stays for now.
+   * available (framework #3271), else a raw `POST /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.
+   *   - 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
+   *     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.
    */
   async batchTransaction(
     operations: BatchTransactionOperation[],
   ): Promise<{ results: any[] }> {
-    // Already known-unsupported on this backend — skip the probe entirely.
-    if (this.batchUnsupported) {
+    // Ensure discovery (and thus the #3298 capability) is loaded so the
+    // decision below is declarative, not "fire a batch and read the status".
+    await this.connect();
+
+    // 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.
+    const guaranteed = this.atomicBatchCapability === true;
+
+    // Already probed-and-degraded on a non-declaring backend — skip the probe.
+    // (Unreachable once `guaranteed`: that path never sets `batchUnsupported`.)
+    if (!guaranteed && this.batchUnsupported) {
       return emulateBatchTransaction(this, operations);
     }
 
@@ -966,14 +1038,14 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     // predate it fall through to the raw-fetch mainline below.
     const sdkBatch = (this.client.data as any).batchTransaction;
     if (typeof sdkBatch === 'function') {
-      await this.connect();
       try {
         const payload: { results: any[] } = await sdkBatch.call(this.client.data, operations);
         this.emitBatchMutations(operations, payload?.results);
         return payload;
       } catch (err) {
-        if (this.batchStatusUnsupported(this.errorStatusOf(err))) {
-          return this.fallbackToEmulation(operations, this.errorStatusOf(err));
+        const status = this.errorStatusOf(err);
+        if (!guaranteed && this.batchStatusUnsupported(status)) {
+          return this.fallbackToEmulation(operations, status);
         }
         throw err;
       }
@@ -991,12 +1063,14 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       body: JSON.stringify({ operations }),
     });
     if (!response.ok) {
-      // 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. Every
-      // other status (400 validation, 401/403 auth, 409 conflict, 500 fault)
-      // is a real error the caller must see — never silently retried.
-      if (this.batchStatusUnsupported(response.status)) {
+      // 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);
       }
       const error = await response.json().catch(() => ({ message: response.statusText }));