@object-ui/data-objectstack 16.0.0 → 17.1.0

package/src/onWriteWarning.test.ts

@@ -0,0 +1,172 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * ObjectStackAdapter must surface the framework's write-observability channel
+ * (#3431/#3455): when a create/update response carries `droppedFields` — fields
+ * the backend LEGALLY stripped (read-only / locked-by-state) — the adapter emits
+ * a WriteWarningEvent so the app shell can toast the user instead of letting the
+ * dropped value vanish silently. The write itself still succeeded.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+import type { WriteWarningEvent } from './index';
+
+function makeDS(stub: Record<string, any>) {
+  const ds: any = new ObjectStackAdapter({
+    baseUrl: 'http://test.local',
+    fetch: vi.fn(async () =>
+      new Response(JSON.stringify({ success: true, data: { capabilities: {}, routes: {} } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    ),
+  });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  ds.client = { data: stub };
+  return ds;
+}
+
+const ONE_DROP = [{ object: 'approval_case', fields: ['approval_status'], reason: 'readonly' }];
+
+describe('ObjectStackAdapter.onWriteWarning', () => {
+  it('emits a create write-warning carrying the dropped fields and the new id', async () => {
+    const create = vi.fn().mockResolvedValue({ record: { id: 'r1', title: 'A' }, droppedFields: ONE_DROP });
+    const ds = makeDS({ create });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    const rec = await ds.create('approval_case', { title: 'A', approval_status: 'approved' });
+
+    // The write still returns the plain record (unchanged behaviour).
+    expect(rec).toEqual({ id: 'r1', title: 'A' });
+    expect(events).toEqual([
+      { operation: 'create', resource: 'approval_case', id: 'r1', droppedFields: ONE_DROP },
+    ]);
+  });
+
+  it('emits an update write-warning carrying the target id', async () => {
+    const update = vi.fn().mockResolvedValue({ record: { id: 'r1' }, droppedFields: ONE_DROP });
+    const ds = makeDS({ update });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.update('approval_case', 'r1', { approval_status: 'approved' });
+
+    expect(events).toEqual([
+      { operation: 'update', resource: 'approval_case', id: 'r1', droppedFields: ONE_DROP },
+    ]);
+  });
+
+  it('does NOT emit when the response carries no droppedFields (the common case)', async () => {
+    const create = vi.fn().mockResolvedValue({ record: { id: 'r1', title: 'A' } });
+    const update = vi.fn().mockResolvedValue({ record: { id: 'r1' } });
+    const ds = makeDS({ create, update });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.create('approval_case', { title: 'A' });
+    await ds.update('approval_case', 'r1', { title: 'B' });
+
+    expect(events).toEqual([]);
+  });
+
+  it('does NOT emit for an empty or malformed droppedFields payload', async () => {
+    const create = vi
+      .fn()
+      .mockResolvedValueOnce({ record: { id: 'r1' }, droppedFields: [] })
+      .mockResolvedValueOnce({ record: { id: 'r2' }, droppedFields: 'nope' })
+      .mockResolvedValueOnce({ record: { id: 'r3' }, droppedFields: [{ object: 'x', fields: [] }] });
+    const ds = makeDS({ create });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.create('x', {});
+    await ds.create('x', {});
+    await ds.create('x', {}); // event present but its fields[] is empty → filtered out
+
+    expect(events).toEqual([]);
+  });
+
+  // ── cross-object batch (framework #3794) ─────────────────────────────────
+  //
+  // `batchTransaction` is the console record form's save path for a
+  // master-detail record, so this is where a `readonlyWhen` strip actually
+  // reaches a user editing a form. Its response tags each event with the index
+  // of the operation that produced it.
+
+  it('emits a write-warning per event on a cross-object batch, resolving the op', async () => {
+    const batchTransaction = vi.fn().mockResolvedValue({
+      results: [{ id: 'acc1' }, { id: 'inv1' }],
+      droppedFields: [
+        { object: 'invoice', fields: ['tax_rate'], reason: 'readonly_when', index: 1 },
+      ],
+    });
+    const ds = makeDS({ batchTransaction });
+    ds.atomicBatchCapability = true;
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.batchTransaction([
+      { object: 'account', action: 'create', data: { name: 'Acme' } },
+      { object: 'invoice', action: 'update', id: 'inv1', data: { status: 'paid', tax_rate: 9 } },
+    ]);
+
+    expect(events).toEqual([
+      {
+        operation: 'update',
+        resource: 'invoice',
+        id: 'inv1',
+        droppedFields: [{ object: 'invoice', fields: ['tax_rate'], reason: 'readonly_when' }],
+      },
+    ]);
+  });
+
+  it('does NOT emit for a clean batch or a malformed droppedFields list', async () => {
+    const batchTransaction = vi
+      .fn()
+      .mockResolvedValueOnce({ results: [{ id: 'a' }] })
+      .mockResolvedValueOnce({ results: [{ id: 'a' }], droppedFields: [{ object: 'x', fields: [], index: 0 }] });
+    const ds = makeDS({ batchTransaction });
+    ds.atomicBatchCapability = true;
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.batchTransaction([{ object: 'x', action: 'create', data: {} }]);
+    await ds.batchTransaction([{ object: 'x', action: 'create', data: {} }]);
+
+    expect(events).toEqual([]);
+  });
+
+  it('stops delivering after unsubscribe', async () => {
+    const create = vi.fn().mockResolvedValue({ record: { id: 'r1' }, droppedFields: ONE_DROP });
+    const ds = makeDS({ create });
+    const events: WriteWarningEvent[] = [];
+    const unsub = ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.create('approval_case', {});
+    unsub();
+    await ds.create('approval_case', {});
+
+    expect(events).toHaveLength(1);
+  });
+
+  it('isolates a throwing listener so the write still resolves and other listeners fire', async () => {
+    const update = vi.fn().mockResolvedValue({ record: { id: 'r1' }, droppedFields: ONE_DROP });
+    const ds = makeDS({ update });
+    const good = vi.fn();
+    ds.onWriteWarning(() => { throw new Error('boom'); });
+    ds.onWriteWarning(good);
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    await expect(ds.update('approval_case', 'r1', { approval_status: 'x' })).resolves.toBeTruthy();
+    expect(good).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+});

package/src/orderby-serialization.test.ts

@@ -0,0 +1,115 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Every shape `QueryParams['$orderby']` declares reaches the wire as a sort.
+ *
+ * `find()` has TWO routes to the server — a plain read goes through
+ * `convertQueryParams` and the client SDK, a read with `$expand`/`$search`
+ * through `rawFindWithPopulate` — and each used to carry its own copy of the
+ * "which `$orderby` shape is this?" fold. Both copies handled three of the four
+ * declared shapes; both missed the bare string, and missed it the same
+ * spectacular way: the string fell into the `Record<field, direction>` branch,
+ * where `Object.entries('name asc')` enumerates character indices and the
+ * request went out as `sort=0,1,2,3,4,5,6,7`.
+ *
+ * That is not a cosmetic mistranslation. Since objectstack#4226 the server
+ * refuses a sort it cannot read (`400 INVALID_SORT`) rather than dropping it,
+ * so the whole list fails to load — and `"${field} ${order}"` is exactly what a
+ * standalone `ObjectGrid` builds from its view metadata's `sort`.
+ *
+ * Both routes are asserted for every shape, because "the two routes agree" is
+ * the property that was actually missing; one serializer now backs both.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ObjectStackAdapter, clearSharedDiscoveryCache, serializeOrderBy } from './index';
+
+function makeAdapter() {
+  const calls: string[] = [];
+  const fetchImpl = vi.fn(async (url: any) => {
+    const u = String(url);
+    calls.push(u);
+    if (u.includes('/api/v1/discovery')) {
+      return {
+        ok: true, status: 200, statusText: 'OK',
+        json: async () => ({ success: true, data: { version: 'v1', routes: {} } }),
+      } as any;
+    }
+    return {
+      ok: true, status: 200, statusText: 'OK',
+      json: async () => ({ success: true, data: { object: 'account', records: [], total: 0 } }),
+    } as any;
+  });
+  const adapter = new ObjectStackAdapter({
+    baseUrl: 'http://localhost:3000', token: 't', autoReconnect: false, fetch: fetchImpl as any,
+  });
+  return { adapter, calls };
+}
+
+/** The `sort=` this `$orderby` produced on the wire, or `undefined` if none was sent. */
+async function sortOnWire($orderby: unknown, route: 'plain' | 'expand'): Promise<string | undefined> {
+  const { adapter, calls } = makeAdapter();
+  await adapter.find('account', {
+    $orderby,
+    ...(route === 'expand' ? { $expand: ['owner'] } : {}),
+  } as any);
+  const dataCall = calls.filter((u) => u.includes('/data/account')).pop();
+  const raw = dataCall ? new URL(dataCall).searchParams.get('sort') : null;
+  return raw === null ? undefined : raw;
+}
+
+/** Run one input down both `find()` routes and assert they agree. */
+function bothRoutes(name: string, $orderby: unknown, expected: string | undefined) {
+  for (const route of ['plain', 'expand'] as const) {
+    it(`${name} (${route} route)`, async () => {
+      expect(await sortOnWire($orderby, route)).toBe(expected);
+    });
+  }
+}
+
+describe('$orderby reaches the wire for every declared shape', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  // The regression: ObjectGrid's own `"${field} ${order}"`.
+  bothRoutes('a bare "field order" string', 'name asc', 'name asc');
+  bothRoutes('a bare string with a descending key', 'created_at desc', 'created_at desc');
+  bothRoutes('a bare string already in `-field` shorthand', '-created_at', '-created_at');
+  bothRoutes('a bare multi-key string', 'status asc,-created_at', 'status asc,-created_at');
+
+  bothRoutes('a SortNode[]', [{ field: 'name', order: 'asc' }], 'name');
+  bothRoutes(
+    'a SortNode[] with a descending key',
+    [{ field: 'status', order: 'asc' }, { field: 'created_at', order: 'desc' }],
+    'status,-created_at',
+  );
+  bothRoutes('a string[]', ['name', '-age'], 'name,-age');
+  bothRoutes('a Record<field, direction>', { name: 'asc', age: 'desc' }, 'name,-age');
+
+  bothRoutes('no sort at all', undefined, undefined);
+  bothRoutes('an empty array', [], undefined);
+  bothRoutes('an empty object', {}, undefined);
+  bothRoutes('a whitespace-only string', '   ', undefined);
+});
+
+describe('serializeOrderBy', () => {
+  it('never enumerates a string as an object — the defect this replaced', () => {
+    // `Object.entries('name asc')` → [['0','n'],['1','a'],…]. The old fold
+    // reached that branch for every string input.
+    expect(serializeOrderBy('name asc')).toBe('name asc');
+    expect(serializeOrderBy('name asc')).not.toMatch(/^0,1,2/);
+  });
+
+  it('reads `order` case-insensitively', () => {
+    expect(serializeOrderBy([{ field: 'name', order: 'DESC' as any }])).toBe('-name');
+  });
+
+  it('defaults a missing direction to ascending', () => {
+    expect(serializeOrderBy([{ field: 'name' }])).toBe('name');
+  });
+});

package/src/queryDataset.test.ts

@@ -7,7 +7,11 @@
  */
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { ObjectStackAdapter, clearSharedDiscoveryCache } from './index';
+import {
+  ObjectStackAdapter,
+  clearSharedDiscoveryCache,
+  isAnalyticsNotInstalledError,
+} from './index';
 
 /** A fetch mock that answers discovery + records the dataset-query POST. */
 function makeFetch(datasetResponse: { ok: boolean; status?: number; body: unknown }) {
@@ -80,4 +84,49 @@ describe('ObjectStackAdapter.queryDataset', () => {
     const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
     await expect(adapter.queryDataset(inlineDataset as any, selection)).rejects.toThrow(/relationship not declared/);
   });
+
+  // framework#3891 retired the degraded in-kernel analytics fallback, so a
+  // deployment without @objectstack/service-analytics answers 501 (REST route
+  // present, no service) or 404 (framework#4019 stopped mounting the routes).
+  // Neither is an authoring mistake — the caller gets a typed, readable error
+  // instead of `Dataset query failed: 501 Not Implemented — …`.
+  describe('analytics capability absent', () => {
+    it('maps 501 NOT_IMPLEMENTED to a readable ANALYTICS_NOT_INSTALLED error', async () => {
+      const { fetchImpl } = makeFetch({
+        ok: false,
+        status: 501,
+        body: {
+          code: 'NOT_IMPLEMENTED',
+          message: 'Analytics dataset query is not available on this deployment (no analytics service with queryDataset).',
+        },
+      });
+      const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+
+      const err = await adapter.queryDataset(inlineDataset as any, selection).catch((e) => e);
+
+      expect(isAnalyticsNotInstalledError(err)).toBe(true);
+      expect(err.code).toBe('ANALYTICS_NOT_INSTALLED');
+      expect(err.message).toContain('Analytics capability is not installed');
+      expect(err.message).toContain('@objectstack/service-analytics');
+    });
+
+    it('maps a 404 (routes not mounted) the same way', async () => {
+      const { fetchImpl } = makeFetch({ ok: false, status: 404, body: { error: 'Not found' } });
+      const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+
+      const err = await adapter.queryDataset(inlineDataset as any, selection).catch((e) => e);
+
+      expect(isAnalyticsNotInstalledError(err)).toBe(true);
+    });
+
+    it('leaves a real compile error alone (it is NOT a missing capability)', async () => {
+      const { fetchImpl } = makeFetch({ ok: false, status: 400, body: { message: 'relationship not declared in include' } });
+      const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+
+      const err = await adapter.queryDataset(inlineDataset as any, selection).catch((e) => e);
+
+      expect(isAnalyticsNotInstalledError(err)).toBe(false);
+      expect(String(err.message)).toContain('relationship not declared');
+    });
+  });
 });

package/src/searchAll.test.ts

@@ -0,0 +1,120 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ObjectStackAdapter, clearSharedDiscoveryCache } from './index';
+
+/** A fetch mock that answers discovery + records the global-search GET. */
+function makeFetch(searchResponse: { ok: boolean; status?: number; body: unknown }) {
+  const calls: Array<{ url: string; init?: any }> = [];
+  const fetchImpl = vi.fn(async (url: any, init?: any) => {
+    const u = String(url);
+    calls.push({ url: u, init });
+    if (u.includes('/api/v1/discovery')) {
+      return { ok: true, status: 200, statusText: 'OK', json: async () => ({ success: true, data: { version: 'v1', routes: {} } }) } as any;
+    }
+    if (u.includes('/api/v1/search')) {
+      return {
+        ok: searchResponse.ok,
+        status: searchResponse.status ?? (searchResponse.ok ? 200 : 400),
+        statusText: searchResponse.ok ? 'OK' : 'Error',
+        json: async () => searchResponse.body,
+      } as any;
+    }
+    return { ok: true, status: 200, statusText: 'OK', json: async () => ({}) } as any;
+  });
+  return { fetchImpl, calls };
+}
+
+const WAYNE_HITS = {
+  query: 'Wayne',
+  hits: [
+    { object: 'crm_account', id: 'a1', title: 'Wayne Enterprises', snippet: 'Wayne Enterprises', record: { id: 'a1', account_number: 'ACC-000005' } },
+    { object: 'crm_opportunity', id: 'o1', title: 'Wayne Q1 Expansion', record: { id: 'o1' } },
+  ],
+};
+
+describe('ObjectStackAdapter.searchAll', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  it('GETs /api/v1/search?q= and returns normalized ranked hits', async () => {
+    const { fetchImpl, calls } = makeFetch({ ok: true, body: WAYNE_HITS });
+    const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', token: 'tok_123', autoReconnect: false, fetch: fetchImpl as any });
+
+    const result = await adapter.searchAll('Wayne');
+
+    expect(result.query).toBe('Wayne');
+    expect(result.hits.map((h) => `${h.object}:${h.id}`)).toEqual(['crm_account:a1', 'crm_opportunity:o1']);
+    expect(result.hits[0].title).toBe('Wayne Enterprises');
+    expect(result.hits[0].record).toEqual({ id: 'a1', account_number: 'ACC-000005' });
+
+    const get = calls.find((c) => c.url.includes('/api/v1/search'))!;
+    const url = new URL(get.url);
+    expect(url.pathname).toBe('/api/v1/search');
+    expect(url.searchParams.get('q')).toBe('Wayne');
+    expect(get.init.method).toBe('GET');
+    expect(get.init.headers.Authorization).toBe('Bearer tok_123');
+  });
+
+  it('trims the query and forwards limit + objects scoping', async () => {
+    const { fetchImpl, calls } = makeFetch({ ok: true, body: { query: 'Wayne', hits: [] } });
+    const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+
+    await adapter.searchAll('  Wayne  ', { limit: 12, objects: ['crm_account', 'crm_opportunity'] });
+
+    const url = new URL(calls.find((c) => c.url.includes('/api/v1/search'))!.url);
+    expect(url.searchParams.get('q')).toBe('Wayne');
+    expect(url.searchParams.get('limit')).toBe('12');
+    expect(url.searchParams.get('objects')).toBe('crm_account,crm_opportunity');
+  });
+
+  it('short-circuits an empty query without hitting the network', async () => {
+    const { fetchImpl, calls } = makeFetch({ ok: true, body: { query: '', hits: [] } });
+    const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+
+    const result = await adapter.searchAll('   ');
+
+    expect(result).toEqual({ query: '', hits: [] });
+    expect(calls.some((c) => c.url.includes('/api/v1/search'))).toBe(false);
+  });
+
+  it('unwraps a { success, data } envelope', async () => {
+    const { fetchImpl } = makeFetch({ ok: true, body: { success: true, data: WAYNE_HITS } });
+    const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+    const result = await adapter.searchAll('Wayne');
+    expect(result.hits).toHaveLength(2);
+  });
+
+  it('treats a 404 (search plugin absent) as an empty result, not an error', async () => {
+    const { fetchImpl } = makeFetch({ ok: false, status: 404, body: { message: 'not found' } });
+    const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+    await expect(adapter.searchAll('Wayne')).resolves.toEqual({ query: 'Wayne', hits: [] });
+  });
+
+  it('throws with the server message on a non-404 error', async () => {
+    const { fetchImpl } = makeFetch({ ok: false, status: 500, body: { error: { message: 'index unavailable' } } });
+    const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+    await expect(adapter.searchAll('Wayne')).rejects.toThrow(/index unavailable/);
+  });
+
+  it('drops malformed hits (missing object or id)', async () => {
+    const { fetchImpl } = makeFetch({
+      ok: true,
+      body: { query: 'x', hits: [
+        { object: 'crm_account', id: 'a1', title: 'Keep' },
+        { id: 'no_object' },
+        { object: 'crm_lead' },
+        null,
+        { object: 'crm_contact', record: { id: 'c9' } },
+      ] },
+    });
+    const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+    const result = await adapter.searchAll('x');
+    expect(result.hits.map((h) => `${h.object}:${h.id}`)).toEqual(['crm_account:a1', 'crm_contact:c9']);
+  });
+});

package/src/userState.test.ts

@@ -144,7 +144,6 @@ describe('createObjectStackUserStateAdapter', () => {
         user_id: 'u1',
         key: 'ui.favorites',
         value: [{ id: 'a' }],
-        updated_at: expect.any(String),
       });
     });
 
@@ -165,11 +164,35 @@ describe('createObjectStackUserStateAdapter', () => {
 
       expect(ds.update).toHaveBeenCalledWith('sys_user_preference', 'row-99', {
         value: [{ id: 'x' }],
-        updated_at: expect.any(String),
       });
       expect(ds.create).not.toHaveBeenCalled();
     });
 
+    // #3794 — `updated_at` is server-managed. A caller-supplied value is
+    // stripped (framework #2948) and reported back as a dropped field, which
+    // the console turns into a "Some fields were not saved" toast. Stamping it
+    // here fired that warning on every recents/favorites write, about a field
+    // no user ever touched — noise on the exact surface that is supposed to
+    // tell a user their edit did not land.
+    it('never sends the server-managed updated_at column', async () => {
+      const ds = mockDataSource({
+        find: vi.fn().mockResolvedValue({ data: [] }) as any,
+        create: vi.fn().mockResolvedValue({ id: 'row-1' }) as any,
+      });
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        key: 'ui.recent',
+      });
+
+      await adapter.save([{ id: 'a' } as any]);
+      await adapter.save([{ id: 'b' } as any]);
+
+      for (const call of [...(ds.create as any).mock.calls, ...(ds.update as any).mock.calls]) {
+        expect(call[call.length - 1]).not.toHaveProperty('updated_at');
+      }
+    });
+
     it('uses the cached row id from a previous load on subsequent saves', async () => {
       const ds = mockDataSource({
         find: vi.fn().mockResolvedValue({
@@ -242,7 +265,6 @@ describe('createObjectStackUserStateAdapter', () => {
       expect(ds.create).toHaveBeenCalledTimes(1);
       expect(ds.update).toHaveBeenCalledWith('sys_user_preference', 'row-7', {
         value: [{ id: 'q' }],
-        updated_at: expect.any(String),
       });
     });
 
@@ -270,7 +292,6 @@ describe('createObjectStackUserStateAdapter', () => {
       expect(ds.create).toHaveBeenCalledTimes(1);
       expect(ds.update).toHaveBeenCalledWith('sys_user_preference', 'row-1', {
         value: [{ id: 'a' }, { id: 'b' }],
-        updated_at: expect.any(String),
       });
     });
 

package/src/userState.ts

@@ -159,13 +159,18 @@ export function createObjectStackUserStateAdapter<T = unknown>(
   // (a concurrent writer created the row, or the backend dropped our find
   // predicate), recover by re-finding and updating rather than surfacing the
   // failed insert.
+  //
+  // Deliberately does NOT stamp `updated_at`: the column is server-managed, and
+  // a non-system caller's write to it is stripped (framework #2948) and reported
+  // back as a dropped field — which the console surfaces as a "Some fields were
+  // not saved" toast (#3431). Sending it made every recents/favorites write pop
+  // a scary warning about a field the user never touched, drowning the real
+  // signal the toast exists for (#3794). The server stamps it either way.
   const upsert = async (items: T[]): Promise<void> => {
-    const now = new Date().toISOString();
-
     // Fast path: we already know the row id from a previous load/save.
     if (cachedRowId !== null) {
       try {
-        await dataSource.update(resource, cachedRowId, { value: items, updated_at: now });
+        await dataSource.update(resource, cachedRowId, { value: items });
         return;
       } catch (updateError) {
         // Row may have been deleted server-side — fall through to find/insert.
@@ -177,7 +182,7 @@ export function createObjectStackUserStateAdapter<T = unknown>(
     const existing = await findExisting();
     if (existing && existing.id !== undefined && existing.id !== null) {
       cachedRowId = existing.id;
-      await dataSource.update(resource, existing.id, { value: items, updated_at: now });
+      await dataSource.update(resource, existing.id, { value: items });
       return;
     }
 
@@ -186,7 +191,6 @@ export function createObjectStackUserStateAdapter<T = unknown>(
         user_id: userId,
         key,
         value: items,
-        updated_at: now,
       });
       const newId = (created as UserPreferenceRecord | undefined)?.id;
       if (newId !== undefined && newId !== null) cachedRowId = newId;
@@ -196,7 +200,7 @@ export function createObjectStackUserStateAdapter<T = unknown>(
       const recovered = await findExisting();
       if (recovered && recovered.id !== undefined && recovered.id !== null) {
         cachedRowId = recovered.id;
-        await dataSource.update(resource, recovered.id, { value: items, updated_at: now });
+        await dataSource.update(resource, recovered.id, { value: items });
         return;
       }
       throw createError;

package/src/validation-error.test.ts

@@ -0,0 +1,94 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { normaliseClientError } from './index';
+import { ValidationError } from './errors';
+
+/**
+ * The server has always sent per-field rejection detail; the adapter used to
+ * hand callers the raw client error, so `fields[]` had no typed home and every
+ * form fell back to one undirected toast.
+ */
+describe('normaliseClientError — VALIDATION_FAILED', () => {
+  // `@objectstack/rest` serves a thrown validation failure as 400 with `fields[]`
+  // verbatim; `@objectstack/client` sets `error.details` to the parsed body's
+  // `details` OR — as here, since the envelope has no such key — the whole body.
+  const upstream = () =>
+    Object.assign(new Error('Name is required; Stage is not a valid option'), {
+      code: 'VALIDATION_FAILED',
+      httpStatus: 400,
+      details: {
+        error: 'Name is required; Stage is not a valid option',
+        code: 'VALIDATION_FAILED',
+        fields: [
+          { field: 'name', code: 'required', message: 'Name is required' },
+          { field: 'stage', code: 'invalid_option', message: 'Stage is not a valid option' },
+        ],
+        object: 'crm_opportunity',
+      },
+    });
+
+  it('wraps it into a typed ValidationError', () => {
+    const normalised = normaliseClientError(upstream());
+    expect(normalised).toBeInstanceOf(ValidationError);
+  });
+
+  it('carries every field entry through', () => {
+    const normalised = normaliseClientError(upstream()) as ValidationError;
+    expect(normalised.validationErrors).toEqual([
+      { field: 'name', message: 'Name is required' },
+      { field: 'stage', message: 'Stage is not a valid option' },
+    ]);
+  });
+
+  it('keeps the server message verbatim — it names every field', () => {
+    const normalised = normaliseClientError(upstream()) as ValidationError;
+    expect(normalised.message).toBe('Name is required; Stage is not a valid option');
+  });
+
+  it('exposes the first offending field on `.field`', () => {
+    const normalised = normaliseClientError(upstream()) as ValidationError;
+    expect(normalised.field).toBe('name');
+  });
+
+  it('falls back to the machine code when an entry has no message', () => {
+    const err = Object.assign(new Error('Validation failed'), {
+      code: 'VALIDATION_FAILED',
+      details: { fields: [{ field: 'name', code: 'required' }] },
+    });
+    const normalised = normaliseClientError(err) as ValidationError;
+    expect(normalised.validationErrors).toEqual([{ field: 'name', message: 'required' }]);
+  });
+
+  it('drops entries with no field rather than inventing one', () => {
+    const err = Object.assign(new Error('Validation failed'), {
+      code: 'VALIDATION_FAILED',
+      details: { fields: [{ message: 'something is wrong' }] },
+    });
+    const normalised = normaliseClientError(err) as ValidationError;
+    expect(normalised.validationErrors).toEqual([]);
+  });
+
+  it('still wraps when the error carries `fields` directly (hand-rolled shape)', () => {
+    // The server duck-types on `code`/`name`, so a hook throwing the bare shape
+    // is served identically — the client must not be pickier than the server.
+    const err = Object.assign(new Error('nope'), {
+      name: 'ValidationError',
+      fields: [{ field: 'amount', message: 'Amount must be positive' }],
+    });
+    const normalised = normaliseClientError(err) as ValidationError;
+    expect(normalised.validationErrors).toEqual([{ field: 'amount', message: 'Amount must be positive' }]);
+  });
+
+  it('leaves an unrelated 400 untouched', () => {
+    const err = Object.assign(new Error('bad request'), { code: 'BAD_REQUEST', httpStatus: 400 });
+    expect(normaliseClientError(err)).toBe(err);
+  });
+});