@object-ui/data-objectstack 16.1.0 → 17.2.0

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/security.ts

@@ -11,7 +11,20 @@
  * Provides advanced security policies: CSP config, audit logging, data masking.
  */
 
-export interface SecurityPolicy {
+/**
+ * Configuration for {@link SecurityManager} — this adapter's browser-side
+ * security posture: the CSP header it generates, the in-memory audit log it
+ * keeps, and the field-masking rules it applies before a record is rendered.
+ *
+ * NOT the spec's `SecurityPolicy` (`@objectstack/spec/kernel`), whose name this
+ * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
+ * is the PACKAGE SUPPLY-CHAIN policy — `{ id, name, autoScan, thresholds,
+ * allowedLicenses, prohibitedLicenses, codeSigning, sandbox }` — the rules a
+ * marketplace applies when scanning a plugin before install. It shares no key
+ * with this one, so there was nothing to derive; the collision is the word
+ * "security", not the concept.
+ */
+export interface SecurityManagerPolicy {
   /** Content Security Policy configuration */
   csp?: CSPConfig;
   /** Audit logging configuration */
@@ -100,10 +113,10 @@ export interface AuditLogEntry {
  * Handles CSP generation, audit logging, and data masking.
  */
 export class SecurityManager {
-  private policy: SecurityPolicy;
+  private policy: SecurityManagerPolicy;
   private auditLog: AuditLogEntry[] = [];
 
-  constructor(policy: SecurityPolicy = {}) {
+  constructor(policy: SecurityManagerPolicy = {}) {
     this.policy = policy;
   }
 
@@ -204,14 +217,14 @@ export class SecurityManager {
   /**
    * Update the security policy.
    */
-  updatePolicy(policy: Partial<SecurityPolicy>): void {
+  updatePolicy(policy: Partial<SecurityManagerPolicy>): void {
     this.policy = { ...this.policy, ...policy };
   }
 
   /**
    * Get current security policy.
    */
-  getPolicy(): SecurityPolicy {
+  getPolicy(): SecurityManagerPolicy {
     return { ...this.policy };
   }
 }

package/src/spec-symbol-batch6.test.ts

@@ -0,0 +1,303 @@
+/**
+ * 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.
+ */
+
+/**
+ * `@object-ui/data-objectstack` ↔ `@objectstack/spec` symbol-collision guards
+ * (objectui#3160, objectstack#4115 ledger batch 6).
+ *
+ * Five symbols here wore names the spec already owns. One really WAS the spec's
+ * and now carries its binding (`DroppedFieldsEvent`); the other four model
+ * something the spec has never modelled under that name and were renamed:
+ *
+ *   CacheStats          → MetadataCacheStats
+ *   MetadataSaveOptions → MetadataClientSaveOptions
+ *   SecurityPolicy      → SecurityManagerPolicy
+ *   ValidationError     → DataApiValidationError
+ *
+ * The batch's own triage note said "data-objectstack is a direct client of the
+ * spec protocol, so `SecurityPolicy` / `DroppedFieldsEvent` are probably hand
+ * copies — derive them first". Half of that held: `DroppedFieldsEvent` was
+ * exactly a hand copy, and `SecurityPolicy` turned out to share not one key with
+ * the spec's. That asymmetry is why every assertion below is per SYMBOL and
+ * never per cluster.
+ *
+ * ## Why the spec's names are read through the compiler, not `import * as`
+ *
+ * A runtime namespace import sees VALUES only, and every name checked here is a
+ * TYPE; a tripwire built on `Object.keys(await import(…))` would pass while
+ * proving nothing. So this reads each subpath's `.d.ts` through the TypeScript
+ * checker, exactly as `scripts/check-spec-symbol-derivation.mjs` does.
+ *
+ * ## …and why through `ts.sys` rather than `node:fs`
+ *
+ * Unlike the sibling batches' parity tests, this package's `tsconfig.json`
+ * compiles its whole test tree (it is not in `check-type-check-coverage.mjs`'s
+ * TEST_DEBT), so the pins below are already checked by `tsc --noEmit` with no
+ * separate `tsconfig.typetests.json`. Keeping that property means NOT pulling
+ * `@types/node` into a browser-side adapter's type environment just to read a
+ * file — so the probe uses the TypeScript compiler's own host, which is typed
+ * by the `typescript` dependency this file already has, and resolves the spec
+ * through TS's module resolver instead of hard-coding its subpath list.
+ */
+
+import { describe, it, expect } from 'vitest';
+import ts from 'typescript';
+
+import { DataApiValidationError } from './errors';
+import type { MetadataCacheStats } from './cache/MetadataCache';
+import type { MetadataClientSaveOptions } from './metadata-client';
+import type { SecurityManagerPolicy } from './security';
+import type { DroppedFieldsEvent } from './index';
+
+import type { DroppedFieldsEvent as SpecDroppedFieldsEvent } from '@objectstack/spec/data';
+import type { CacheStats as SpecCacheStats } from '@objectstack/spec/contracts';
+import type {
+  MetadataSaveOptions as SpecMetadataSaveOptions,
+  SecurityPolicy as SpecSecurityPolicy,
+  ValidationError as SpecValidationError,
+} from '@objectstack/spec/kernel';
+
+const PROBE_OPTIONS: ts.CompilerOptions = {
+  noEmit: true,
+  skipLibCheck: true,
+  strict: false,
+  target: ts.ScriptTarget.ESNext,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  resolveJsonModule: true,
+};
+
+/** This file, as TypeScript's module resolver wants it: an absolute path. */
+const HERE = new URL(import.meta.url).pathname;
+
+/** Every name `@objectstack/spec` exports from any subpath — types AND values. */
+function specExportNames(): Set<string> {
+  const pkgPath = ts.resolveModuleName('@objectstack/spec/package.json', HERE, PROBE_OPTIONS, ts.sys)
+    .resolvedModule?.resolvedFileName;
+  if (!pkgPath) {
+    throw new Error('cannot resolve @objectstack/spec — run `pnpm install` first');
+  }
+  const pkgDir = pkgPath.slice(0, pkgPath.lastIndexOf('/'));
+  const raw = ts.sys.readFile(pkgPath);
+  if (!raw) throw new Error(`cannot read ${pkgPath}`);
+  const pkg = JSON.parse(raw) as {
+    exports?: Record<string, { import?: { types?: string }; require?: { types?: string } }>;
+  };
+
+  // Read the export map rather than a hand-written subpath list: a list is a
+  // copy, and a copy of the spec's shape is what this whole ledger is about.
+  const files: string[] = [];
+  for (const cond of Object.values(pkg.exports ?? {})) {
+    if (typeof cond !== 'object' || cond === null) continue;
+    const dts = cond.import?.types ?? cond.require?.types;
+    if (dts) files.push(ts.sys.resolvePath(`${pkgDir}/${dts.replace(/^\.\//, '')}`));
+  }
+
+  const program = ts.createProgram(files, PROBE_OPTIONS);
+  const checker = program.getTypeChecker();
+
+  const names = new Set<string>();
+  for (const file of files) {
+    const sf = program.getSourceFile(file);
+    if (!sf) continue;
+    const moduleSymbol = checker.getSymbolAtLocation(sf);
+    if (!moduleSymbol) continue;
+    for (const exported of checker.getExportsOfModule(moduleSymbol)) names.add(exported.getName());
+  }
+  return names;
+}
+
+const SPEC_NAMES = specExportNames();
+
+describe('the spec export-name probe itself works', () => {
+  it('reads a non-trivial number of names', () => {
+    expect(SPEC_NAMES.size).toBeGreaterThan(1000);
+  });
+
+  it('sees TYPE-only exports, not just runtime values', () => {
+    // `DroppedFieldsEvent` is a type alias — invisible to a runtime `import()`.
+    expect(SPEC_NAMES.has('DroppedFieldsEvent')).toBe(true);
+  });
+});
+
+const RENAMES: Array<[local: string, formerly: string, specMeaning: string]> = [
+  [
+    'MetadataCacheStats',
+    'CacheStats',
+    "the platform's ICacheService counters (keyCount / memoryUsage)",
+  ],
+  [
+    'MetadataClientSaveOptions',
+    'MetadataSaveOptions',
+    'options for writing a metadata item to a FILE (format / path / indent / atomic)',
+  ],
+  [
+    'SecurityManagerPolicy',
+    'SecurityPolicy',
+    'the package supply-chain policy (autoScan / licences / codeSigning / sandbox)',
+  ],
+  [
+    'DataApiValidationError',
+    'ValidationError',
+    'a plain { field, message, code? } entry in a validation report',
+  ],
+];
+
+describe('renamed local concepts do not collide with a spec export', () => {
+  it.each(RENAMES)('the spec does not own `%s`', (local) => {
+    expect(
+      SPEC_NAMES.has(local),
+      `@objectstack/spec now exports \`${local}\`. This package declares its own ` +
+        `\`${local}\`, so the rename that fixed objectstack#4115 has re-created the ` +
+        `collision under the new name. Rename again — and check the new name here ` +
+        `FIRST: objectui#3074 landed a rename straight onto another spec export, and ` +
+        `batch 4 burned two obvious candidates (SchemaValidationResult, ` +
+        `SchemaValidationReport) the same way.`,
+    ).toBe(false);
+  });
+
+  it.each(RENAMES)('the spec still owns `%s` (it means: %s)', (_local, formerly) => {
+    expect(
+      SPEC_NAMES.has(formerly),
+      `@objectstack/spec no longer exports \`${formerly}\`, which is the only reason ` +
+        `this package renamed it. Either the spec dropped the name (then the plain ` +
+        `name can be taken back) or it moved (then re-read what it means now). A ` +
+        `workaround must not outlive its reason.`,
+    ).toBe(true);
+  });
+});
+
+/* -------------------------------------------------------------------------- */
+/* Compile-time pins. A violation is a `tsc` error, not a runtime failure.      */
+/* Compiled by this package's own `tsc --noEmit`: unlike its siblings, this      */
+/* package's tsconfig.json does NOT exclude test files, so no separate           */
+/* tsconfig.typetests.json is needed to make these pins load-bearing.            */
+/* -------------------------------------------------------------------------- */
+
+type Assert<T extends true> = T;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** The `unknown` erasure the `any` probe reports `false` for (objectui#3155). */
+type IsUnknown<T> = [unknown] extends [T] ? ([T] extends [unknown] ? true : false) : false;
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+  ? true
+  : false;
+type HasKey<T, K extends PropertyKey> = K extends keyof T ? true : false;
+
+describe('DroppedFieldsEvent IS the spec type, not a mirror of it', () => {
+  it('is pinned at compile time', () => {
+    type _SpecNotAny = Assert<Equal<IsAny<SpecDroppedFieldsEvent>, false>>;
+    type _SpecNotUnknown = Assert<Equal<IsUnknown<SpecDroppedFieldsEvent>, false>>;
+
+    type _IsTheSpecType = Assert<Equal<DroppedFieldsEvent, SpecDroppedFieldsEvent>>;
+
+    // The pin that matters. The deleted copy widened `reason` to bare `string`
+    // "for forward-compatibility with reasons added server-side" — which is the
+    // AGENTS.md #12 lenient fallback, and it deleted the only signal that would
+    // tell AdapterProvider's toast (it branches on `readonly_when`) that a third
+    // reason had appeared. `Equal` is used rather than `extends` because
+    // `'readonly' | 'readonly_when' extends string` is true in the drifted
+    // direction too.
+    type _ReasonIsTheEnum = Assert<Equal<DroppedFieldsEvent['reason'], 'readonly' | 'readonly_when'>>;
+    type _ReasonIsNotString = Assert<Equal<Equal<DroppedFieldsEvent['reason'], string>, false>>;
+
+    expect(true).toBe(true);
+  });
+});
+
+describe('MetadataCacheStats is not the spec ICacheService stats', () => {
+  it('is pinned at compile time', () => {
+    type _SpecNotAny = Assert<Equal<IsAny<SpecCacheStats>, false>>;
+
+    // The two agree only on the two counters every cache has. Everything that
+    // says what KIND of cache each describes is exclusive to one side: the
+    // spec's is a server KV store sized in keys and bytes; this one is a bounded
+    // browser LRU that evicts, coalesces in-flight fetches and reports a rate.
+    type _Shared = Assert<Equal<Extract<keyof MetadataCacheStats, keyof SpecCacheStats>, 'hits' | 'misses'>>;
+    type _SpecOnly = Assert<Equal<Exclude<keyof SpecCacheStats, keyof MetadataCacheStats>, 'keyCount' | 'memoryUsage'>>;
+    type _LocalOnly = Assert<
+      Equal<
+        Exclude<keyof MetadataCacheStats, keyof SpecCacheStats>,
+        'size' | 'maxSize' | 'evictions' | 'coalesced' | 'hitRate'
+      >
+    >;
+
+    expect(true).toBe(true);
+  });
+});
+
+describe('MetadataClientSaveOptions is not the spec file-save options', () => {
+  it('is pinned at compile time', () => {
+    type _SpecNotAny = Assert<Equal<IsAny<SpecMetadataSaveOptions>, false>>;
+
+    // Disjoint: the spec's describes serialising an item to disk, this one
+    // describes a PUT to /api/v1/meta/*. Not one key is shared, so there was
+    // never a subset relationship to derive from.
+    type _NoOverlap = Assert<Equal<Extract<keyof MetadataClientSaveOptions, keyof SpecMetadataSaveOptions>, never>>;
+
+    // The keys that make this the HTTP envelope.
+    type _HasIfMatch = Assert<HasKey<MetadataClientSaveOptions, 'ifMatch'>>;
+    type _HasDraftMode = Assert<Equal<MetadataClientSaveOptions['mode'], 'draft' | 'publish' | undefined>>;
+    // …and the ones that make the spec's the file writer.
+    type _SpecHasPath = Assert<HasKey<SpecMetadataSaveOptions, 'path'>>;
+    type _SpecHasFormat = Assert<HasKey<SpecMetadataSaveOptions, 'format'>>;
+
+    expect(true).toBe(true);
+  });
+});
+
+describe('SecurityManagerPolicy is not the spec package-security policy', () => {
+  it('is pinned at compile time', () => {
+    type _SpecNotAny = Assert<Equal<IsAny<SpecSecurityPolicy>, false>>;
+
+    // Also fully disjoint. The spec's governs installing a plugin (scan
+    // schedule, licence allowlists, code signing, sandbox limits); this one
+    // governs what the browser adapter emits and hides (CSP header, audit log,
+    // field masking).
+    type _NoOverlap = Assert<Equal<Extract<keyof SecurityManagerPolicy, keyof SpecSecurityPolicy>, never>>;
+    type _SpecIsIdentified = Assert<Equal<SpecSecurityPolicy['id'], string>>;
+    type _LocalIsAllOptional = Assert<
+      Equal<
+        undefined extends SecurityManagerPolicy['csp' | 'auditLog' | 'dataMasking'] ? true : false,
+        true
+      >
+    >;
+
+    expect(true).toBe(true);
+  });
+});
+
+describe('DataApiValidationError is an Error, the spec ValidationError is a record', () => {
+  it('is pinned at compile time', () => {
+    type _SpecNotAny = Assert<Equal<IsAny<SpecValidationError>, false>>;
+
+    // The spec's is one entry in a validation report. `@object-ui/types`
+    // re-exports it under that name, so the two were importable side by side.
+    type _SpecShape = Assert<Equal<Exclude<keyof SpecValidationError, 'field' | 'message' | 'code'>, never>>;
+
+    // This one is a thrown runtime object: it has a `stack`, which no data
+    // record does, and it carries the whole list the spec type is one item of.
+    type _WeAreAnError = Assert<HasKey<DataApiValidationError, 'stack'>>;
+    type _WeCarryTheList = Assert<
+      Equal<DataApiValidationError['validationErrors'], Array<{ field: string; message: string }> | undefined>
+    >;
+
+    expect(true).toBe(true);
+  });
+
+  it('keeps `name === "ValidationError"` — the RUNTIME name is a wire contract', () => {
+    // Deliberately NOT renamed with the class. `normaliseClientError` in
+    // ./index.ts sniffs `e.name === 'ValidationError'` on errors thrown by
+    // `@objectstack/client`, and `@object-ui/react`'s `error-message` does the
+    // same on the way out. Renaming the TypeScript symbol is a source change;
+    // renaming this string would be a silent behaviour change.
+    expect(new DataApiValidationError('nope').name).toBe('ValidationError');
+    expect(new DataApiValidationError('nope')).toBeInstanceOf(Error);
+    expect(new DataApiValidationError('nope').code).toBe('VALIDATION_ERROR');
+    expect(new DataApiValidationError('nope').statusCode).toBe(400);
+  });
+});

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 { DataApiValidationError } 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 DataApiValidationError', () => {
+    const normalised = normaliseClientError(upstream());
+    expect(normalised).toBeInstanceOf(DataApiValidationError);
+  });
+
+  it('carries every field entry through', () => {
+    const normalised = normaliseClientError(upstream()) as DataApiValidationError;
+    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 DataApiValidationError;
+    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 DataApiValidationError;
+    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 DataApiValidationError;
+    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 DataApiValidationError;
+    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 DataApiValidationError;
+    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);
+  });
+});