feat(discovery): broadcast transactionalBatch capability bit for declarative atomic-batch negotiation (#3298) (#3345)

Add a required `transactionalBatch` bit to discovery so clients negotiate the atomic cross-object batch declaratively instead of runtime-probing 404/405/501. Filled honestly by every producer (metadata-protocol via engine.transaction, rest-server ANDed with api.enableBatch, hono standalone false, client exposes it). Closes #3298.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/console-3b2e4d98d904.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/console": minor
+---
+
+Console (objectui) refreshed to `3b2e4d98d904`. Frontend changes in this range:
+
+- fix(list): route remaining system-field groupings through shared classifier (#2706)
+- feat(console): user-import wizard defaults to the `auto` password policy (tracks framework#3236) (#2701)
+- feat(flow-designer): schema-driven keyValue + numberList mapping (#3304) (#2708)
+
+objectui range: `0318118e02fd...3b2e4d98d904`

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

@@ -0,0 +1,20 @@
+---
+"@objectstack/spec": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/rest": minor
+"@objectstack/plugin-hono-server": minor
+"@objectstack/client": minor
+---
+
+**Broadcast a `transactionalBatch` capability bit in discovery so clients negotiate the atomic cross-object batch declaratively, instead of runtime-probing 404/405/501 (#3298).**
+
+The atomic cross-object batch endpoint (`POST {basePath}/batch`, #1604 / ADR-0034 item 4) and its typed SDK surface (`client.data.batchTransaction`, #3271) already shipped, but discovery never told a client whether a backend actually supports it. Consumers (notably ObjectUI's `ObjectStackAdapter`) had to *probe*: fire a `/batch`, read `404`/`405` (no route) or `501` (no runtime transaction), and only then fall back to non-atomic client-side simulation. That is "find out by calling", not capability negotiation — it cannot be decided at connect time and cannot serve as the "minimum backend supports `/batch`" gate that blocks hard-deleting the non-atomic fallback downstream.
+
+`WellKnownCapabilitiesSchema` gains a required `transactionalBatch: boolean`, and **every** discovery producer fills it honestly (`declared === enforced`), so it never becomes a declared-but-unpopulated bit:
+
+- **`@objectstack/metadata-protocol`** (`getDiscovery`) — reports whether the runtime engine can honour a transaction (`typeof engine.transaction === 'function'`). The `/batch` handler runs its ops inside `engine.transaction()`, which degrades to a non-atomic passthrough (or 501) without one.
+- **`@objectstack/rest`** (`/discovery`) — ANDs the engine signal with whether it actually mounts the route (`api.enableBatch`), so a server with batch disabled reports `false` even on a transaction-capable engine (never advertise an endpoint that would 404).
+- **`@objectstack/plugin-hono-server`** (standalone discovery) — reports `false`: this minimal surface registers CRUD only and does not mount `/batch` (that ships with `@objectstack/rest`). Under-reporting is the safe direction — a client keeps its correct-but-slower fallback rather than losing atomicity.
+- **`@objectstack/client`** — already normalizes hierarchical `capabilities` to flat booleans, so `client.capabilities.transactionalBatch` is exposed (and now typed) for declarative consumers.
+
+The bit follows the existing capability semantics: `true` ⟺ the `/batch` route is mounted **and** the runtime can honour a transaction — the exact condition under which the endpoint returns `200` rather than `404`/`405`/`501`. Additive and behavior-preserving; only the discovery payload gains a field.

.objectui-sha

@@ -1 +1 @@
-0318118e02fd0ef377492f3b09b687a84cccc908
+3b2e4d98d904d695a8372c394d46b81673011270

content/docs/references/api/discovery.mdx

@@ -160,6 +160,7 @@ Well-known capability flags for frontend intelligent adaptation
 | **search** | `boolean` | ✅ | Whether the backend supports full-text search |
 | **export** | `boolean` | ✅ | Whether the backend supports async export |
 | **chunkedUpload** | `boolean` | ✅ | Whether the backend supports chunked (multipart) uploads |
+| **transactionalBatch** | `boolean` | ✅ | Whether the backend exposes the atomic cross-object batch endpoint (POST `{basePath}`/batch, #1604/ADR-0034): all ops commit or roll back together in one transaction. Lets clients skip non-atomic client-side simulation instead of runtime-probing 404/405/501. True ⟺ the /batch route is mounted AND the runtime can honour a transaction. |
 
 
 ---

packages/client/src/client.test.ts

@@ -890,6 +890,32 @@ describe('ObjectStackClient.automation', () => {
         expect(client.capabilities!.automation).toBe(false);
         expect(client.capabilities!.search).toBe(true);
     });
+
+    it('should expose the transactionalBatch capability (hierarchical → flat) for declarative negotiation (#3298)', async () => {
+        // A real backend serves the hierarchical shape `{ key: { enabled } }`.
+        // The client normalizes it to a flat boolean so callers can decide at
+        // connect time whether to send an atomic batch or fall back to
+        // non-atomic simulation — instead of runtime-probing POST /batch.
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            json: async () => ({
+                version: 'v1',
+                apiName: 'ObjectStack API',
+                capabilities: {
+                    comments: { enabled: false },
+                    transactionalBatch: { enabled: true },
+                },
+            }),
+        });
+
+        const client = new ObjectStackClient({
+            baseUrl: 'http://localhost:3000',
+            fetch: fetchMock,
+        });
+
+        await client.connect();
+        expect(client.capabilities!.transactionalBatch).toBe(true);
+    });
 });
 
 // ==========================================

packages/metadata-protocol/src/protocol.ts

@@ -1422,6 +1422,15 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             search: registeredServices.has('search'),
             export: registeredServices.has('automation') || registeredServices.has('queue'),
             chunkedUpload: registeredServices.has('file-storage'),
+            // Atomic cross-object batch (#3298 / #1604 / ADR-0034 item 4): the
+            // REST /batch endpoint runs its ops inside `engine.transaction()`,
+            // which only opens a real (all-or-nothing) transaction when the
+            // engine exposes one — otherwise it degrades to a non-atomic
+            // passthrough. Advertise the capability iff the runtime engine can
+            // honour a transaction, so `declared === enforced` (Prime Directive
+            // #10). The rest-server producer ANDs this with `api.enableBatch` so
+            // a server that doesn't mount the route reports `false` at its layer.
+            transactionalBatch: typeof (this.engine as { transaction?: unknown })?.transaction === 'function',
         };
 
         // Convert flat booleans → hierarchical capability objects

packages/objectql/src/protocol-discovery.test.ts

@@ -238,6 +238,31 @@ describe('ObjectStackProtocolImplementation - Dynamic Service Discovery', () =>
     expect(discovery.capabilities!.comments).toEqual({ enabled: false });
   });
 
+  // ── Atomic cross-object batch capability (#3298 / #1604 / ADR-0034) ─────────
+  // The bit tracks whether the runtime engine can honour a transaction (the
+  // REST /batch endpoint runs inside `engine.transaction()`), NOT a registered
+  // service — so it is independent of the services map.
+  it('advertises transactionalBatch when the engine exposes transaction() — the real ObjectQL engine (#3298)', async () => {
+    protocol = new ObjectStackProtocolImplementation(engine);
+    const discovery = await protocol.getDiscovery();
+
+    // ObjectQL always implements transaction() (ADR-0034), so a real engine
+    // reports the capability regardless of which services are registered.
+    expect(typeof (engine as unknown as { transaction?: unknown }).transaction).toBe('function');
+    expect(discovery.capabilities!.transactionalBatch).toEqual({ enabled: true });
+  });
+
+  it('does NOT advertise transactionalBatch when the engine has no transaction() (declared === enforced, #3298)', async () => {
+    // A minimal engine without transaction(): the /batch endpoint would 501, so
+    // discovery must report false — never let a client drop its non-atomic
+    // fallback against a runtime that cannot honour an atomic batch.
+    const noTxEngine = { registry: { getObject: () => undefined } } as any;
+    protocol = new ObjectStackProtocolImplementation(noTxEngine);
+    const discovery = await protocol.getDiscovery();
+
+    expect(discovery.capabilities!.transactionalBatch).toEqual({ enabled: false });
+  });
+
   it('should enable comments capability when the sys_comment object is registered (#3180)', async () => {
     // comments/chatter are served by the sys_comment object via the data API
     // (ADR-0052 §5), not a dedicated service — so the capability tracks that

packages/plugins/plugin-hono-server/src/hono-plugin.test.ts

@@ -103,6 +103,34 @@ describe('HonoServerPlugin', () => {
         await expect(plugin.start(context as PluginContext)).resolves.not.toThrow();
     });
 
+    it('standalone discovery advertises transactionalBatch=false — the /batch route is not mounted here (#3298)', async () => {
+        // This standalone surface registers CRUD + auth only; the cross-object
+        // /batch endpoint ships with @objectstack/rest. declared === enforced:
+        // discovery must report the capability as disabled so a client never
+        // drops its non-atomic fallback against this backend.
+        const plugin = new HonoServerPlugin({ registerStandardEndpoints: true });
+        await plugin.init(context as PluginContext);
+
+        // Capture the routes the producer registers on the raw app.
+        const routes: Record<string, any> = {};
+        const rawApp = {
+            get: vi.fn((path: string, h: any) => { routes[`GET ${path}`] = h; }),
+            post: vi.fn((path: string, h: any) => { routes[`POST ${path}`] = h; }),
+            use: vi.fn(),
+        };
+        (plugin as any).server.getRawApp = () => rawApp;
+        (plugin as any).registerDiscoveryAndCrudEndpoints(context);
+
+        const handler = routes['GET /api/v1/discovery'];
+        expect(handler).toBeDefined();
+        const c = { json: vi.fn((x: any) => x) };
+        const res = handler(c);
+        expect(res.data.capabilities.transactionalBatch).toEqual({ enabled: false });
+        // Sanity: the standalone surface really has no /batch route (so `false`
+        // is honest, not merely conservative).
+        expect(routes['POST /api/v1/batch']).toBeUndefined();
+    });
+
     it('should configure static files and SPA fallback when enabled', async () => {
         const plugin = new HonoServerPlugin({
             staticRoot: './public',

packages/plugins/plugin-hono-server/src/hono-plugin.ts

@@ -690,6 +690,16 @@ export class HonoServerPlugin implements Plugin {
                 storage:       `${prefix}/storage`,
                 ui:            `${prefix}/ui`,
             },
+            capabilities: {
+                // This standalone Hono surface registers CRUD + auth only (see
+                // below) — it does NOT mount the cross-object `/batch` route,
+                // which ships with `@objectstack/rest`. `declared === enforced`
+                // (#3298): report `transactionalBatch: false` so a client never
+                // drops its non-atomic fallback against a backend that lacks the
+                // endpoint. When `@objectstack/rest` is mounted it serves its own
+                // discovery, which reports the real value from the runtime engine.
+                transactionalBatch: { enabled: false },
+            },
         };
 
         // Discovery endpoints

packages/rest/src/rest-server.ts

@@ -1860,6 +1860,27 @@ export class RestServer {
                         }
                     }
 
+                    // Cross-object atomic batch capability (#3298). `declared ===
+                    // enforced`: advertise it only when THIS server actually mounts
+                    // the `/batch` route (`api.enableBatch`, gated in
+                    // registerBatchEndpoints) AND the runtime engine can honour a
+                    // transaction (the protocol derived that from `engine.transaction`).
+                    // AND-ing the two keeps us from advertising an endpoint that would
+                    // 404 (batch disabled) or 501 (engine without `transaction()`), so
+                    // a client can safely drop its non-atomic fallback on `true`.
+                    const caps = ((discovery as any).capabilities ??= {}) as Record<
+                        string,
+                        { enabled: boolean; description?: string }
+                    >;
+                    const runtimeSupportsTx = !!caps.transactionalBatch?.enabled;
+                    caps.transactionalBatch = {
+                        enabled: runtimeSupportsTx && this.config.api.enableBatch !== false,
+                        description:
+                            'Atomic cross-object batch endpoint (POST {basePath}/batch): all-or-nothing '
+                            + 'create/update/delete across objects in one transaction, with intra-batch '
+                            + '{ $ref: <opIndex> } parent references (#1604 / ADR-0034).',
+                    };
+
                     // Attach scoping metadata so clients can detect dual-mode routing.
                     (discovery as any).scoping = {
                         enabled: this.config.api.enableProjectScoping,