@object-ui/data-objectstack 13.2.0 → 14.1.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @object-ui/data-objectstack
 
+## 14.1.0
+
+### Patch Changes
+
+- Updated dependencies [0890fa7]
+- Updated dependencies [2ded18c]
+- Updated dependencies [e628d1f]
+- Updated dependencies [5523fc4]
+- Updated dependencies [887062c]
+- Updated dependencies [9e2d58f]
+- Updated dependencies [dea65f7]
+- Updated dependencies [d5b1bc0]
+- Updated dependencies [f0f10f5]
+  - @object-ui/core@14.1.0
+  - @object-ui/types@14.1.0
+
+## 14.0.0
+
+### Minor Changes
+
+- 6a74160: Sharing-rule form: pick, don't type. Three new widget-hint field components make
+  the generic object form render pickers where an admin previously had to type
+  machine data (driven by the framework `widget` hints on `sys_sharing_rule`;
+  generalizes the `capability-multiselect` pattern). All degrade to the underlying
+  `type` renderer when a widget is unregistered.
+
+  - **`object-ref`** — choose a registered object by name (searchable `Combobox`),
+    backed by the new `DataSource.getObjects()` (`ObjectStackAdapter` lists code-
+    and DB-defined objects via `/api/v1/meta/object`), falling back to a
+    `sys_metadata` query. Stores the object's `name`.
+  - **`filter-condition`** — a visual criteria builder (`FilterBuilder`) scoped to
+    the fields of the object chosen in a sibling field (via `getObjectSchema`),
+    round-tripping the stored **MongoDB-style** FilterCondition JSON. Criteria the
+    builder can't represent (or invalid JSON) fall back to a raw-JSON editor, with
+    an always-available "Edit as JSON" toggle — nothing is hidden or lost.
+  - **`recipient-picker`** — a record picker whose target object follows a sibling
+    `recipient_type` (`user`→sys_user, `team`→sys_team, `business_unit`/
+    `unit_and_subordinates`→sys_business_unit, `position`→sys_position), storing the
+    value the evaluator matches on (a record id, or the position **name**). Resets
+    the stored id when the type changes.
+
+  Wiring: the three keys join `DATA_SOURCE_FIELD_TYPES` (form.tsx) so the form
+  threads `dataSource` + `dependentValues` to them, and `INLINE_EXCLUDED_FIELD_TYPES`
+  (they're authored in the record form, not a grid cell). `DataSource.getObjects()`
+  is optional on the interface; the ObjectStack adapter implements it.
+
+### Patch Changes
+
+- Updated dependencies [443360a]
+- Updated dependencies [86c69c3]
+- Updated dependencies [05e56ca]
+- Updated dependencies [6a74160]
+  - @object-ui/core@14.0.0
+  - @object-ui/types@14.0.0
+
 ## 13.2.0
 
 ### Patch Changes

package/dist/index.cjs

@@ -119,6 +119,24 @@ function convertFiltersToAST(filter) {
   return ["and", ...conditions];
 }
 
+// ../core/src/utils/reference-keys.ts
+function normalizeFieldReferenceKeys(fieldDef) {
+  if (!fieldDef || typeof fieldDef !== "object") return fieldDef;
+  const f = fieldDef;
+  const target = f.reference_to ?? f.reference ?? f.referenceTo;
+  if (target == null || target === "") return fieldDef;
+  if (f.reference_to === void 0) f.reference_to = target;
+  if (f.reference === void 0) f.reference = target;
+  return fieldDef;
+}
+function normalizeSchemaReferenceKeys(schema) {
+  const fields = schema && typeof schema === "object" ? schema.fields : null;
+  if (!fields || typeof fields !== "object") return schema;
+  const defs = Array.isArray(fields) ? fields : Object.values(fields);
+  for (const def of defs) normalizeFieldReferenceKeys(def);
+  return schema;
+}
+
 // src/cache/MetadataCache.ts
 var MetadataCache = class {
   /**
@@ -1922,7 +1940,7 @@ var ObjectStackAdapter = class {
    */
   async batchTransaction(operations) {
     const url = `${this.baseUrl}/api/v1/batch`;
-    const response = await fetch(url, {
+    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
@@ -1940,7 +1958,20 @@ var ObjectStackAdapter = class {
         response.status
       );
     }
-    return response.json();
+    const payload = await response.json();
+    const results = Array.isArray(payload?.results) ? payload.results : [];
+    operations.forEach((op, i) => {
+      const action = op.action ?? "create";
+      const echo = results[i];
+      if (action === "create") {
+        this.emitMutation({ type: "create", resource: op.object, record: echo });
+      } else if (action === "update") {
+        this.emitMutation({ type: "update", resource: op.object, id: op.id ?? echo?.id ?? echo?._id, record: echo });
+      } else if (action === "delete") {
+        this.emitMutation({ type: "delete", resource: op.object, id: op.id });
+      }
+    });
+    return payload;
   }
   async bulk(resource, operation, data) {
     await this.connect();
@@ -1967,6 +1998,7 @@ var ObjectStackAdapter = class {
           completed = created.length;
           failed = total - completed;
           emitProgress();
+          if (completed > 0) this.emitMutation({ type: "create", resource });
           return created;
         }
         case "delete": {
@@ -1985,6 +2017,7 @@ var ObjectStackAdapter = class {
           completed = ids.length;
           failed = total - completed;
           emitProgress();
+          if (completed > 0) this.emitMutation({ type: "delete", resource });
           return [];
         }
         case "update": {
@@ -1996,6 +2029,7 @@ var ObjectStackAdapter = class {
               completed = updated.length;
               failed = total - completed;
               emitProgress();
+              if (completed > 0) this.emitMutation({ type: "update", resource });
               return updated;
             } catch {
             }
@@ -2023,6 +2057,7 @@ var ObjectStackAdapter = class {
               emitProgress();
             }
           }
+          if (completed > 0) this.emitMutation({ type: "update", resource });
           if (errors.length > 0) {
             throw new BulkOperationError(
               "update",
@@ -2432,6 +2467,7 @@ var ObjectStackAdapter = class {
         objectName,
         () => this.fetchObjectSchemaFresh(objectName)
       );
+      normalizeSchemaReferenceKeys(schema);
       this.applyFieldWidgetOverrides(objectName, schema);
       return schema;
     } catch (error) {
@@ -2525,6 +2561,35 @@ var ObjectStackAdapter = class {
     const data = body && typeof body === "object" && "success" in body && "data" in body ? body.data : body;
     return data && typeof data === "object" && "item" in data ? data.item : data;
   }
+  /**
+   * List every registered object (code- and DB-defined) from the metadata
+   * registry — `GET /api/v1/meta/object`. Returns lightweight `{ name, label }`
+   * headers for object-picker widgets (e.g. the sharing-rule `object-ref`
+   * field). The list endpoint is uncached server-side, so no cache-busting
+   * dance is needed. Returns `[]` on any failure so callers degrade gracefully.
+   */
+  async getObjects() {
+    try {
+      await this.connect();
+      const baseUrl = (this.baseUrl || "").replace(/\/$/, "");
+      const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+      const metaPath = hasApiVersionSuffix ? "/meta" : "/api/v1/meta";
+      const url = `${baseUrl}${metaPath}/object`;
+      const headers = { "Content-Type": "application/json" };
+      if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
+      const res = await this.fetchImpl(url, { method: "GET", headers });
+      if (!res.ok) return [];
+      const body = await res.json();
+      const data = body && typeof body === "object" && "success" in body && "data" in body ? body.data : body;
+      const items = Array.isArray(data) ? data : Array.isArray(data?.items) ? data.items : [];
+      return items.map((it) => ({
+        name: String(it?.name ?? ""),
+        label: it?.label != null ? String(it.label) : void 0
+      })).filter((it) => it.name);
+    } catch {
+      return [];
+    }
+  }
   /**
    * Get access to the underlying ObjectStack client for advanced operations.
    */

package/dist/index.d.cts

@@ -1557,6 +1557,17 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * not expose the request cache mode.
      */
     private fetchObjectSchemaFresh;
+    /**
+     * List every registered object (code- and DB-defined) from the metadata
+     * registry — `GET /api/v1/meta/object`. Returns lightweight `{ name, label }`
+     * headers for object-picker widgets (e.g. the sharing-rule `object-ref`
+     * field). The list endpoint is uncached server-side, so no cache-busting
+     * dance is needed. Returns `[]` on any failure so callers degrade gracefully.
+     */
+    getObjects(): Promise<Array<{
+        name: string;
+        label?: string;
+    }>>;
     /**
      * Get access to the underlying ObjectStack client for advanced operations.
      */

package/dist/index.d.ts

@@ -1557,6 +1557,17 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * not expose the request cache mode.
      */
     private fetchObjectSchemaFresh;
+    /**
+     * List every registered object (code- and DB-defined) from the metadata
+     * registry — `GET /api/v1/meta/object`. Returns lightweight `{ name, label }`
+     * headers for object-picker widgets (e.g. the sharing-rule `object-ref`
+     * field). The list endpoint is uncached server-side, so no cache-busting
+     * dance is needed. Returns `[]` on any failure so callers degrade gracefully.
+     */
+    getObjects(): Promise<Array<{
+        name: string;
+        label?: string;
+    }>>;
     /**
      * Get access to the underlying ObjectStack client for advanced operations.
      */

package/dist/index.js

@@ -71,6 +71,24 @@ function convertFiltersToAST(filter) {
   return ["and", ...conditions];
 }
 
+// ../core/src/utils/reference-keys.ts
+function normalizeFieldReferenceKeys(fieldDef) {
+  if (!fieldDef || typeof fieldDef !== "object") return fieldDef;
+  const f = fieldDef;
+  const target = f.reference_to ?? f.reference ?? f.referenceTo;
+  if (target == null || target === "") return fieldDef;
+  if (f.reference_to === void 0) f.reference_to = target;
+  if (f.reference === void 0) f.reference = target;
+  return fieldDef;
+}
+function normalizeSchemaReferenceKeys(schema) {
+  const fields = schema && typeof schema === "object" ? schema.fields : null;
+  if (!fields || typeof fields !== "object") return schema;
+  const defs = Array.isArray(fields) ? fields : Object.values(fields);
+  for (const def of defs) normalizeFieldReferenceKeys(def);
+  return schema;
+}
+
 // src/cache/MetadataCache.ts
 var MetadataCache = class {
   /**
@@ -1874,7 +1892,7 @@ var ObjectStackAdapter = class {
    */
   async batchTransaction(operations) {
     const url = `${this.baseUrl}/api/v1/batch`;
-    const response = await fetch(url, {
+    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
@@ -1892,7 +1910,20 @@ var ObjectStackAdapter = class {
         response.status
       );
     }
-    return response.json();
+    const payload = await response.json();
+    const results = Array.isArray(payload?.results) ? payload.results : [];
+    operations.forEach((op, i) => {
+      const action = op.action ?? "create";
+      const echo = results[i];
+      if (action === "create") {
+        this.emitMutation({ type: "create", resource: op.object, record: echo });
+      } else if (action === "update") {
+        this.emitMutation({ type: "update", resource: op.object, id: op.id ?? echo?.id ?? echo?._id, record: echo });
+      } else if (action === "delete") {
+        this.emitMutation({ type: "delete", resource: op.object, id: op.id });
+      }
+    });
+    return payload;
   }
   async bulk(resource, operation, data) {
     await this.connect();
@@ -1919,6 +1950,7 @@ var ObjectStackAdapter = class {
           completed = created.length;
           failed = total - completed;
           emitProgress();
+          if (completed > 0) this.emitMutation({ type: "create", resource });
           return created;
         }
         case "delete": {
@@ -1937,6 +1969,7 @@ var ObjectStackAdapter = class {
           completed = ids.length;
           failed = total - completed;
           emitProgress();
+          if (completed > 0) this.emitMutation({ type: "delete", resource });
           return [];
         }
         case "update": {
@@ -1948,6 +1981,7 @@ var ObjectStackAdapter = class {
               completed = updated.length;
               failed = total - completed;
               emitProgress();
+              if (completed > 0) this.emitMutation({ type: "update", resource });
               return updated;
             } catch {
             }
@@ -1975,6 +2009,7 @@ var ObjectStackAdapter = class {
               emitProgress();
             }
           }
+          if (completed > 0) this.emitMutation({ type: "update", resource });
           if (errors.length > 0) {
             throw new BulkOperationError(
               "update",
@@ -2384,6 +2419,7 @@ var ObjectStackAdapter = class {
         objectName,
         () => this.fetchObjectSchemaFresh(objectName)
       );
+      normalizeSchemaReferenceKeys(schema);
       this.applyFieldWidgetOverrides(objectName, schema);
       return schema;
     } catch (error) {
@@ -2477,6 +2513,35 @@ var ObjectStackAdapter = class {
     const data = body && typeof body === "object" && "success" in body && "data" in body ? body.data : body;
     return data && typeof data === "object" && "item" in data ? data.item : data;
   }
+  /**
+   * List every registered object (code- and DB-defined) from the metadata
+   * registry — `GET /api/v1/meta/object`. Returns lightweight `{ name, label }`
+   * headers for object-picker widgets (e.g. the sharing-rule `object-ref`
+   * field). The list endpoint is uncached server-side, so no cache-busting
+   * dance is needed. Returns `[]` on any failure so callers degrade gracefully.
+   */
+  async getObjects() {
+    try {
+      await this.connect();
+      const baseUrl = (this.baseUrl || "").replace(/\/$/, "");
+      const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+      const metaPath = hasApiVersionSuffix ? "/meta" : "/api/v1/meta";
+      const url = `${baseUrl}${metaPath}/object`;
+      const headers = { "Content-Type": "application/json" };
+      if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
+      const res = await this.fetchImpl(url, { method: "GET", headers });
+      if (!res.ok) return [];
+      const body = await res.json();
+      const data = body && typeof body === "object" && "success" in body && "data" in body ? body.data : body;
+      const items = Array.isArray(data) ? data : Array.isArray(data?.items) ? data.items : [];
+      return items.map((it) => ({
+        name: String(it?.name ?? ""),
+        label: it?.label != null ? String(it.label) : void 0
+      })).filter((it) => it.name);
+    } catch {
+      return [];
+    }
+  }
   /**
    * Get access to the underlying ObjectStack client for advanced operations.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "13.2.0",
+  "version": "14.1.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,9 +22,9 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^14.3.0",
-    "@object-ui/core": "13.2.0",
-    "@object-ui/types": "13.2.0"
+    "@objectstack/client": "^14.6.0",
+    "@object-ui/core": "14.1.0",
+    "@object-ui/types": "14.1.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/getObjectSchema.test.ts

@@ -75,6 +75,38 @@ describe('ObjectStackAdapter.getObjectSchema', () => {
     expect(Object.keys(schema.fields)).toEqual(['x']);
   });
 
+  it('canonicalizes the ObjectStack-convention `reference` key onto `reference_to` (and back)', async () => {
+    // The server names a relational field's target `reference`
+    // (showcase_project.account → { type: 'lookup', reference: 'showcase_account' }),
+    // while most consumers read `reference_to` (#2407 / PR #2587). getObjectSchema
+    // is the choke point every schema read goes through, so both keys must come
+    // back stamped — regardless of which convention the served schema used.
+    const { fetchImpl } = makeFetch({
+      name: 'showcase_project',
+      fields: {
+        name: { type: 'text' },
+        account: { type: 'lookup', reference: 'showcase_account' },
+        team_members: { type: 'user', reference: 'sys_user', multiple: true },
+        legacy: { type: 'master_detail', reference_to: 'showcase_order' },
+      },
+    });
+    const adapter = new ObjectStackAdapter({
+      baseUrl: 'http://localhost:3000',
+      autoReconnect: false,
+      fetch: fetchImpl as any,
+    });
+
+    const schema: any = await adapter.getObjectSchema('showcase_project');
+
+    expect(schema.fields.account.reference_to).toBe('showcase_account');
+    expect(schema.fields.team_members.reference_to).toBe('sys_user');
+    // Mirror direction: `.reference`-only readers (e.g. attachInlineSubforms)
+    // must also see the target on a reference_to-authored schema.
+    expect(schema.fields.legacy.reference).toBe('showcase_order');
+    // Non-relational fields stay untouched.
+    expect('reference_to' in schema.fields.name).toBe(false);
+  });
+
   it('preserves `validations` (incl. state_machine transitions) — the seam the inline editor depends on', async () => {
     // Inert-metadata regression guard. The inline select editor filters its
     // options by the object's `state_machine` validation (objectui#2110). That

package/src/index.ts

@@ -23,7 +23,7 @@ import type {
   ImportJobUndoResult,
   ListImportJobsOptions,
 } from '@object-ui/types';
-import { convertFiltersToAST } from '@object-ui/core';
+import { convertFiltersToAST, normalizeSchemaReferenceKeys } from '@object-ui/core';
 import { MetadataCache } from './cache/MetadataCache';
 import {
   ObjectStackError,
@@ -936,7 +936,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     operations: Array<{ object: string; action?: 'create' | 'update' | 'delete'; data?: any; id?: string }>,
   ): Promise<{ results: any[] }> {
     const url = `${this.baseUrl}/api/v1/batch`;
-    const response = await fetch(url, {
+    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
@@ -954,7 +954,27 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         response.status,
       );
     }
-    return response.json();
+    const payload: { results: any[] } = await response.json();
+    // The whole transaction committed — emit one MutationEvent per operation so
+    // the invalidation bus (#2269) sees writes that went through /batch exactly
+    // like single create/update/delete calls (master-detail ModalForm saves
+    // otherwise leave related lists and count badges stale, #2582). `results`
+    // is index-aligned with `operations`; creates take id/record from the
+    // server echo. A failed batch rolled back entirely and throws above, so
+    // nothing is emitted for it.
+    const results = Array.isArray(payload?.results) ? payload.results : [];
+    operations.forEach((op, i) => {
+      const action = op.action ?? 'create';
+      const echo = results[i];
+      if (action === 'create') {
+        this.emitMutation({ type: 'create', resource: op.object, record: echo });
+      } else if (action === 'update') {
+        this.emitMutation({ type: 'update', resource: op.object, id: op.id ?? echo?.id ?? echo?._id, record: echo });
+      } else if (action === 'delete') {
+        this.emitMutation({ type: 'delete', resource: op.object, id: op.id });
+      }
+    });
+    return payload;
   }
 
   async bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]> {
@@ -986,6 +1006,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
           completed = created.length;
           failed = total - completed;
           emitProgress();
+          // One resource-level event for the whole batch (same contract as
+          // bulkUpdate/bulkDelete) so bound views refresh after subform child
+          // rows are created through this path (#2582).
+          if (completed > 0) this.emitMutation({ type: 'create', resource });
           return created;
         }
         
@@ -1010,6 +1034,8 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
           completed = ids.length;
           failed = total - completed;
           emitProgress();
+          // One resource-level event per batch — see the create branch.
+          if (completed > 0) this.emitMutation({ type: 'delete', resource });
           return [] as T[];
         }
         
@@ -1025,6 +1051,8 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
               completed = updated.length;
               failed = total - completed;
               emitProgress();
+              // One resource-level event per batch — see the create branch.
+              if (completed > 0) this.emitMutation({ type: 'update', resource });
               return updated;
             } catch {
               // If updateMany is not supported, fall back to individual updates
@@ -1060,6 +1088,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
             }
           }
           
+          // Rows that DID persist must still reach subscribers, even when the
+          // batch as a whole reports failure below (continueOnError semantics
+          // — the successful writes are not rolled back).
+          if (completed > 0) this.emitMutation({ type: 'update', resource });
+
           // If there were any errors, throw BulkOperationError
           if (errors.length > 0) {
             throw new BulkOperationError(
@@ -1070,7 +1103,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
               { resource, totalRecords: data.length }
             );
           }
-          
+
           return results;
         }
         
@@ -1609,6 +1642,13 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         this.fetchObjectSchemaFresh(objectName),
       );
 
+      // Canonicalize the relational-target key: the server names it
+      // `reference` (ObjectStack convention) while most consumers read
+      // `reference_to` (#2407 / PR #2587). Stamping both here — the choke
+      // point every schema read goes through — means no per-consumer
+      // dual-key fallback can drift. Idempotent on the cached object.
+      normalizeSchemaReferenceKeys(schema);
+
       // ADR-0056 P2 (epic #2398): stamp structured-widget hints onto specific
       // platform fields. This is the single choke point both the record form
       // (ObjectForm) and the detail view (DetailView/DetailSection) read the
@@ -1725,6 +1765,49 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     return data && typeof data === 'object' && 'item' in data ? data.item : data;
   }
 
+  /**
+   * List every registered object (code- and DB-defined) from the metadata
+   * registry — `GET /api/v1/meta/object`. Returns lightweight `{ name, label }`
+   * headers for object-picker widgets (e.g. the sharing-rule `object-ref`
+   * field). The list endpoint is uncached server-side, so no cache-busting
+   * dance is needed. Returns `[]` on any failure so callers degrade gracefully.
+   */
+  async getObjects(): Promise<Array<{ name: string; label?: string }>> {
+    try {
+      await this.connect();
+      const baseUrl = (this.baseUrl || '').replace(/\/$/, '');
+      // Avoid doubling /api/v1 when baseUrl already carries the version suffix
+      // (mirrors fetchObjectSchemaFresh).
+      const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+      const metaPath = hasApiVersionSuffix ? '/meta' : '/api/v1/meta';
+      const url = `${baseUrl}${metaPath}/object`;
+
+      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+      if (this.token) headers['Authorization'] = `Bearer ${this.token}`;
+
+      const res = await this.fetchImpl(url, { method: 'GET', headers });
+      if (!res.ok) return [];
+      const body: any = await res.json();
+      // Unwrap the `{ success, data }` envelope, the `{ type, items }` list
+      // shape, or a bare array.
+      const data =
+        body && typeof body === 'object' && 'success' in body && 'data' in body ? body.data : body;
+      const items: any[] = Array.isArray(data)
+        ? data
+        : Array.isArray(data?.items)
+          ? data.items
+          : [];
+      return items
+        .map((it: any) => ({
+          name: String(it?.name ?? ''),
+          label: it?.label != null ? String(it.label) : undefined,
+        }))
+        .filter((it) => it.name);
+    } catch {
+      return [];
+    }
+  }
+
   /**
    * Get access to the underlying ObjectStack client for advanced operations.
    */

package/src/onMutation.test.ts

@@ -123,3 +123,175 @@ describe('ObjectStackAdapter.onMutation', () => {
     expect(good).toHaveBeenCalledTimes(1);
   });
 });
+
+/**
+ * Regression for #2582: a ModalForm over an object WITH subforms delegates to
+ * MasterDetailForm, which persists parent + child rows through ONE
+ * `batchTransaction` (`POST /api/v1/batch`). That path never emitted
+ * MutationEvents, so the related list and the "相关" tab count badge stayed
+ * stale after a successful create/edit until a full page reload. The adapter
+ * must emit one event per committed operation — and nothing when the
+ * transaction failed (it rolled back entirely).
+ */
+describe('ObjectStackAdapter.batchTransaction mutation events', () => {
+  function makeBatchDS(responder: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) {
+    const ds: any = new ObjectStackAdapter({
+      baseUrl: 'http://test.local',
+      fetch: vi.fn(responder),
+    });
+    ds.connected = true;
+    ds.connectionState = 'connected';
+    return ds;
+  }
+
+  it('emits one event per op after a committed master-detail CREATE batch', async () => {
+    const ds = makeBatchDS(async () =>
+      new Response(
+        JSON.stringify({
+          results: [
+            { id: 'p1', name: 'Task version A' },
+            { id: 'c1', task: 'p1', label: 'Check item 1' },
+          ],
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+    const events: MutationEvent[] = [];
+    ds.onMutation((e: MutationEvent) => events.push(e));
+
+    await ds.batchTransaction([
+      { object: 'ehr_task_version', action: 'create', data: { name: 'Task version A' } },
+      { object: 'ehr_task_check_item', action: 'create', data: { task: { $ref: 0 }, label: 'Check item 1' } },
+    ]);
+
+    expect(events).toEqual([
+      { type: 'create', resource: 'ehr_task_version', record: { id: 'p1', name: 'Task version A' } },
+      { type: 'create', resource: 'ehr_task_check_item', record: { id: 'c1', task: 'p1', label: 'Check item 1' } },
+    ]);
+  });
+
+  it('emits update/create/delete events after a committed master-detail EDIT batch', async () => {
+    const ds = makeBatchDS(async () =>
+      new Response(
+        JSON.stringify({
+          results: [{ id: 'p1' }, { id: 'c-new' }, { id: 'c1' }, { deleted: true }],
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      ),
+    );
+    const events: MutationEvent[] = [];
+    ds.onMutation((e: MutationEvent) => events.push(e));
+
+    await ds.batchTransaction([
+      { object: 'ehr_task_version', action: 'update', id: 'p1', data: { name: 'Renamed' } },
+      { object: 'ehr_task_check_item', action: 'create', data: { task: 'p1' } },
+      { object: 'ehr_task_check_item', action: 'update', id: 'c1', data: { label: 'Edited' } },
+      { object: 'ehr_task_check_item', action: 'delete', id: 'c2' },
+    ]);
+
+    expect(events).toEqual([
+      { type: 'update', resource: 'ehr_task_version', id: 'p1', record: { id: 'p1' } },
+      { type: 'create', resource: 'ehr_task_check_item', record: { id: 'c-new' } },
+      { type: 'update', resource: 'ehr_task_check_item', id: 'c1', record: { id: 'c1' } },
+      { type: 'delete', resource: 'ehr_task_check_item', id: 'c2' },
+    ]);
+  });
+
+  it('treats an op without an explicit action as a create (the server default)', async () => {
+    const ds = makeBatchDS(async () =>
+      new Response(JSON.stringify({ results: [{ id: 'p1' }] }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    const events: MutationEvent[] = [];
+    ds.onMutation((e: MutationEvent) => events.push(e));
+
+    await ds.batchTransaction([{ object: 'ehr_task_version', data: { name: 'X' } }]);
+
+    expect(events).toEqual([
+      { type: 'create', resource: 'ehr_task_version', record: { id: 'p1' } },
+    ]);
+  });
+
+  it('emits NOTHING when the batch failed — the transaction rolled back', async () => {
+    const ds = makeBatchDS(async () =>
+      new Response(JSON.stringify({ error: 'validation failed' }), {
+        status: 422,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    const events: MutationEvent[] = [];
+    ds.onMutation((e: MutationEvent) => events.push(e));
+
+    await expect(
+      ds.batchTransaction([{ object: 'ehr_task_version', action: 'create', data: {} }]),
+    ).rejects.toThrow('validation failed');
+
+    expect(events).toEqual([]);
+  });
+});
+
+/**
+ * Regression for #2582 (fallback path): when the server lacks the transactional
+ * batch endpoint, MasterDetailForm persists child rows via `bulk(child,
+ * 'create', rows)` (applyDetail → createMany). `bulk` only emitted progress
+ * events, so those writes were equally invisible to the invalidation bus. Each
+ * branch now emits ONE resource-level event, matching bulkUpdate/bulkDelete.
+ */
+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));
+
+    await ds.bulk('ehr_task_check_item', 'create', [{ label: 'a' }, { label: 'b' }]);
+
+    expect(events).toEqual([{ type: 'create', resource: 'ehr_task_check_item' }]);
+  });
+
+  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));
+
+    await ds.bulk('ehr_task_check_item', 'create', [{ label: 'a' }]);
+
+    expect(events).toEqual([]);
+  });
+
+  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));
+
+    await ds.bulk('ehr_task_check_item', 'delete', [{ id: 'c1' }, { id: 'c2' }] as any);
+
+    expect(events).toEqual([{ type: 'delete', resource: 'ehr_task_check_item' }]);
+  });
+
+  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));
+
+    await ds.bulk('ehr_task_check_item', 'update', [{ id: 'c1', label: 'x' }] as any);
+
+    expect(events).toEqual([{ type: 'update', resource: 'ehr_task_check_item' }]);
+  });
+
+  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));
+
+    await expect(ds.bulk('ehr_task_check_item', 'create', [{ label: 'a' }])).rejects.toThrow();
+
+    expect(events).toEqual([]);
+  });
+});